Skip to content

A fast, helpful, and open-source document parser

docs: document a bunch of parsing params/types

Logan Markewich4e306c71c1fe
diff --git a/crates/liteparse-napi/src/types.rs b/crates/liteparse-napi/src/types.rs
index 162645e..526ffb1 100644
--- a/crates/liteparse-napi/src/types.rs
+++ b/crates/liteparse-napi/src/types.rs
@@ -1017,9 +1017,21 @@ pub struct JsPageComplexityStats {
pub text_length: u32,
pub text_coverage: f64,
pub has_substantial_images: bool,
+ /// Number of counted raster images — inline figures only; full-page
+ /// backgrounds are excluded (see `fullPageImage`).
pub image_block_count: u32,
+ /// Summed image-bbox area over page area, clamped to 1. Counts inline
+ /// figures only: a full-page scan raster contributes 0 here — check
+ /// `fullPageImage` for that.
pub image_coverage: f64,
+ /// Largest single counted image's area over page area, clamped to 1. Same
+ /// exclusion as `imageCoverage`: a full-page raster contributes 0.
pub largest_image_coverage: f64,
+ /// A single raster covering ≥90% of the page is present. Such full-page
+ /// backgrounds are excluded from `imageCoverage`/`largestImageCoverage`
+ /// (they're not inline figures), so this flag is the only signal that
+ /// distinguishes a scan from a genuinely blank page — both otherwise
+ /// report no text and no counted images.
pub full_page_image: bool,
pub uncovered_vector_area: Option<f64>,
pub is_garbled: bool,
diff --git a/crates/liteparse-python/src/lib.rs b/crates/liteparse-python/src/lib.rs
index a3ff467..3c06bac 100644
--- a/crates/liteparse-python/src/lib.rs
+++ b/crates/liteparse-python/src/lib.rs
@@ -892,12 +892,24 @@ struct PyPageComplexityStats {
text_coverage: f32,
#[pyo3(get)]
has_substantial_images: bool,
+ /// Number of counted raster images — inline figures only; full-page
+ /// backgrounds are excluded (see `full_page_image`).
#[pyo3(get)]
image_block_count: usize,
+ /// Summed image-bbox area over page area, clamped to 1. Counts inline
+ /// figures only: a full-page scan raster contributes 0 here — check
+ /// `full_page_image` for that.
#[pyo3(get)]
image_coverage: f32,
+ /// Largest single counted image's area over page area, clamped to 1. Same
+ /// exclusion as `image_coverage`: a full-page raster contributes 0.
#[pyo3(get)]
largest_image_coverage: f32,
+ /// A single raster covering ≥90% of the page is present. Such full-page
+ /// backgrounds are excluded from `image_coverage`/`largest_image_coverage`
+ /// (they're not inline figures), so this flag is the only signal that
+ /// distinguishes a scan from a genuinely blank page — both otherwise
+ /// report no text and no counted images.
#[pyo3(get)]
full_page_image: bool,
#[pyo3(get)]
diff --git a/crates/liteparse-wasm/src/lib.rs b/crates/liteparse-wasm/src/lib.rs
index 4a357f7..9532a9f 100644
--- a/crates/liteparse-wasm/src/lib.rs
+++ b/crates/liteparse-wasm/src/lib.rs
@@ -1057,9 +1057,21 @@ pub struct PageComplexityStats {
text_length: usize,
text_coverage: f32,
has_substantial_images: bool,
+ /// Number of counted raster images — inline figures only; full-page
+ /// backgrounds are excluded (see `fullPageImage`).
image_block_count: usize,
+ /// Summed image-bbox area over page area, clamped to 1. Counts inline
+ /// figures only: a full-page scan raster contributes 0 here — check
+ /// `fullPageImage` for that.
image_coverage: f32,
+ /// Largest single counted image's area over page area, clamped to 1. Same
+ /// exclusion as `imageCoverage`: a full-page raster contributes 0.
largest_image_coverage: f32,
+ /// A single raster covering ≥90% of the page is present. Such full-page
+ /// backgrounds are excluded from `imageCoverage`/`largestImageCoverage`
+ /// (they're not inline figures), so this flag is the only signal that
+ /// distinguishes a scan from a genuinely blank page — both otherwise
+ /// report no text and no counted images.
full_page_image: bool,
uncovered_vector_area: Option<f32>,
is_garbled: bool,
diff --git a/packages/node/src/lib.ts b/packages/node/src/lib.ts
index c034f8d..420dd32 100644
--- a/packages/node/src/lib.ts
+++ b/packages/node/src/lib.ts
@@ -399,10 +399,21 @@ export interface PageComplexityStats {
/** Fraction of the page area covered by native text (0–1). */
textCoverage: number;
hasSubstantialImages: boolean;
+ /**
+ * Number of counted raster images — inline figures only; full-page
+ * backgrounds are excluded (see {@link fullPageImage}).
+ */
imageBlockCount: number;
- /** Summed image-bbox area over page area, clamped to 1. */
+ /**
+ * Summed image-bbox area over page area, clamped to 1. Counts inline figures
+ * only: a full-page scan raster contributes 0 here — check
+ * {@link fullPageImage} for that.
+ */
imageCoverage: number;
- /** Largest single *counted* image's area over page area, clamped to 1. */
+ /**
+ * Largest single *counted* image's area over page area, clamped to 1. Same
+ * exclusion as {@link imageCoverage}: a full-page raster contributes 0.
+ */
largestImageCoverage: number;
/**
* A single raster covers ≥90% of the page. Full-page backgrounds are excluded
diff --git a/packages/python/liteparse/types.py b/packages/python/liteparse/types.py
index 9074e3a..2229d2e 100644
--- a/packages/python/liteparse/types.py
+++ b/packages/python/liteparse/types.py
@@ -299,19 +299,49 @@ class LayoutComplexityStats:
@dataclass
class PageComplexityStats:
- """Per-page complexity signals used to decide whether a document needs OCR."""
+ """Per-page complexity signals used to decide whether a document needs OCR.
+
+ The three image fields (``image_block_count``, ``image_coverage``,
+ ``largest_image_coverage``) describe *inline figures only*: a raster
+ covering ≥90% of the page in both dimensions is treated as a full-page
+ background and excluded from all three. A full-page scan therefore reports
+ ``full_page_image=True`` with ``image_coverage=0.0`` — trust
+ ``full_page_image`` (or ``"scanned"`` in ``reasons``), not the coverage
+ fractions, when deciding whether a page is a scan."""
page_number: int
+ #: Length of usable native text (garbled/unmappable items excluded).
text_length: int
+ #: Fraction of the page area covered by native text (0–1).
text_coverage: float
has_substantial_images: bool
+ #: Number of counted raster images — inline figures only; full-page
+ #: backgrounds are excluded (see class docstring).
image_block_count: int
+ #: Summed bbox area of the counted images over page area, clamped to 1.
+ #: Overlapping images can inflate the raw sum, so read it as "summed
+ #: image-bbox area", not unique covered area. A full-page scan raster
+ #: contributes 0 here — see ``full_page_image``.
image_coverage: float
+ #: Area of the single largest counted image over page area, clamped to 1.
+ #: Same exclusion as ``image_coverage``: a full-page raster contributes 0.
largest_image_coverage: float
+ #: A single raster covering ≥90% of the page is present. Such full-page
+ #: backgrounds are excluded from ``image_coverage`` /
+ #: ``largest_image_coverage`` (they're not inline figures), so this flag is
+ #: the only signal that distinguishes a scan from a genuinely blank page —
+ #: both otherwise report no text and no counted images.
full_page_image: bool
+ #: Filled vector-outline area not covered by native text, in pt².
+ #: ``None`` when a cheaper signal already decided the page, so this
+ #: expensive walk was skipped.
uncovered_vector_area: Optional[float]
is_garbled: bool
page_area: float
+ #: Verdict: whether this page needs more than the cheap text-only path.
needs_ocr: bool
+ #: Every reason the page was flagged (e.g. ``"scanned"``,
+ #: ``"sparse-text"``, ``"garbled"``). Empty exactly when ``needs_ocr`` is
+ #: False; new reasons may be added over time.
reasons: list[str]
#: Layout-difficulty signals; see :class:`LayoutComplexityStats`.
layout: Optional[LayoutComplexityStats] = None