Skip to content

A fast, helpful, and open-source document parser

feat: add layout complexity signals to isComplex

Logan Markewich7e295d38855e
diff --git a/crates/liteparse-napi/src/types.rs b/crates/liteparse-napi/src/types.rs
index bbe9ad2..69ad85a 100644
--- a/crates/liteparse-napi/src/types.rs
+++ b/crates/liteparse-napi/src/types.rs
@@ -465,6 +465,38 @@ pub struct JsScreenshotResult {
pub image_buffer: napi::bindgen_prelude::Buffer,
}
+#[napi(object)]
+#[derive(Clone)]
+pub struct JsLayoutComplexityStats {
+ pub column_count: u32,
+ pub ruled_table_count: u32,
+ pub ruled_table_coverage: f64,
+ pub text_table_run_count: u32,
+ pub figure_count: u32,
+ pub figure_coverage: f64,
+ pub is_complex: bool,
+ pub reasons: Vec<String>,
+}
+
+impl JsLayoutComplexityStats {
+ pub fn from_rust(stats: &liteparse::ocr_merge::LayoutComplexityStats) -> Self {
+ Self {
+ column_count: stats.column_count as u32,
+ ruled_table_count: stats.ruled_table_count as u32,
+ ruled_table_coverage: stats.ruled_table_coverage as f64,
+ text_table_run_count: stats.text_table_run_count as u32,
+ figure_count: stats.figure_count as u32,
+ figure_coverage: stats.figure_coverage as f64,
+ is_complex: stats.is_complex,
+ reasons: stats
+ .reasons
+ .iter()
+ .map(|r| r.as_str().to_string())
+ .collect(),
+ }
+ }
+}
+
#[napi(object)]
#[derive(Clone)]
pub struct JsPageComplexityStats {
@@ -481,6 +513,7 @@ pub struct JsPageComplexityStats {
pub page_area: f64,
pub needs_ocr: bool,
pub reasons: Vec<String>,
+ pub layout: Option<JsLayoutComplexityStats>,
}
impl JsPageComplexityStats {
@@ -503,6 +536,10 @@ impl JsPageComplexityStats {
.iter()
.map(|r| r.as_str().to_string())
.collect(),
+ layout: stats
+ .layout
+ .as_ref()
+ .map(JsLayoutComplexityStats::from_rust),
}
}
}
diff --git a/crates/liteparse-python/src/lib.rs b/crates/liteparse-python/src/lib.rs
index e90b3a1..4be62da 100644
--- a/crates/liteparse-python/src/lib.rs
+++ b/crates/liteparse-python/src/lib.rs
@@ -275,6 +275,56 @@ impl PyScreenshotResult {
}
}
+#[pyclass(frozen, from_py_object)]
+#[derive(Clone)]
+struct PyLayoutComplexityStats {
+ #[pyo3(get)]
+ column_count: usize,
+ #[pyo3(get)]
+ ruled_table_count: usize,
+ #[pyo3(get)]
+ ruled_table_coverage: f32,
+ #[pyo3(get)]
+ text_table_run_count: usize,
+ #[pyo3(get)]
+ figure_count: usize,
+ #[pyo3(get)]
+ figure_coverage: f32,
+ #[pyo3(get)]
+ is_complex: bool,
+ #[pyo3(get)]
+ reasons: Vec<String>,
+}
+
+#[pymethods]
+impl PyLayoutComplexityStats {
+ fn __repr__(&self) -> String {
+ format!(
+ "LayoutComplexityStats(column_count={}, ruled_table_count={}, figure_coverage={:.2}, is_complex={})",
+ self.column_count, self.ruled_table_count, self.figure_coverage, self.is_complex
+ )
+ }
+}
+
+impl PyLayoutComplexityStats {
+ fn from_rust(stats: &liteparse::ocr_merge::LayoutComplexityStats) -> Self {
+ Self {
+ column_count: stats.column_count,
+ ruled_table_count: stats.ruled_table_count,
+ ruled_table_coverage: stats.ruled_table_coverage,
+ text_table_run_count: stats.text_table_run_count,
+ figure_count: stats.figure_count,
+ figure_coverage: stats.figure_coverage,
+ is_complex: stats.is_complex,
+ reasons: stats
+ .reasons
+ .iter()
+ .map(|r| r.as_str().to_string())
+ .collect(),
+ }
+ }
+}
+
#[pyclass(frozen, from_py_object)]
#[derive(Clone)]
struct PyPageComplexityStats {
@@ -304,6 +354,8 @@ struct PyPageComplexityStats {
needs_ocr: bool,
#[pyo3(get)]
reasons: Vec<String>,
+ #[pyo3(get)]
+ layout: Option<PyLayoutComplexityStats>,
}
#[pymethods]
@@ -336,6 +388,10 @@ impl PyPageComplexityStats {
.iter()
.map(|r| r.as_str().to_string())
.collect(),
+ layout: stats
+ .layout
+ .as_ref()
+ .map(PyLayoutComplexityStats::from_rust),
}
}
}
@@ -757,6 +813,7 @@ fn _liteparse(m: &Bound<'_, PyModule>) -> PyResult<()> {
m.add_class::<PyWordBox>()?;
m.add_class::<PyScreenshotResult>()?;
m.add_class::<PyPageComplexityStats>()?;
+ m.add_class::<PyLayoutComplexityStats>()?;
m.add_function(wrap_pyfunction!(run_cli, m)?)?;
m.add_function(wrap_pyfunction!(search_items, m)?)?;
Ok(())
diff --git a/crates/liteparse-wasm/src/lib.rs b/crates/liteparse-wasm/src/lib.rs
index a2db51b..ce76178 100644
--- a/crates/liteparse-wasm/src/lib.rs
+++ b/crates/liteparse-wasm/src/lib.rs
@@ -539,6 +539,39 @@ impl LiteParse {
}
}
+#[derive(Serialize, Tsify)]
+#[tsify(into_wasm_abi)]
+#[serde(rename_all = "camelCase")]
+pub struct LayoutComplexityStats {
+ column_count: usize,
+ ruled_table_count: usize,
+ ruled_table_coverage: f32,
+ text_table_run_count: usize,
+ figure_count: usize,
+ figure_coverage: f32,
+ is_complex: bool,
+ reasons: Vec<String>,
+}
+
+impl LayoutComplexityStats {
+ fn from_rust(stats: &liteparse::ocr_merge::LayoutComplexityStats) -> Self {
+ Self {
+ column_count: stats.column_count,
+ ruled_table_count: stats.ruled_table_count,
+ ruled_table_coverage: stats.ruled_table_coverage,
+ text_table_run_count: stats.text_table_run_count,
+ figure_count: stats.figure_count,
+ figure_coverage: stats.figure_coverage,
+ is_complex: stats.is_complex,
+ reasons: stats
+ .reasons
+ .iter()
+ .map(|r| r.as_str().to_string())
+ .collect(),
+ }
+ }
+}
+
#[derive(Serialize, Tsify)]
#[tsify(into_wasm_abi)]
#[serde(rename_all = "camelCase")]
@@ -556,6 +589,7 @@ pub struct PageComplexityStats {
page_area: f32,
needs_ocr: bool,
reasons: Vec<String>,
+ layout: Option<LayoutComplexityStats>,
}
impl PageComplexityStats {
@@ -578,6 +612,7 @@ impl PageComplexityStats {
.iter()
.map(|r| r.as_str().to_string())
.collect(),
+ layout: stats.layout.as_ref().map(LayoutComplexityStats::from_rust),
}
}
}
diff --git a/crates/liteparse/src/main.rs b/crates/liteparse/src/main.rs
index 021ebcb..47fa851 100644
--- a/crates/liteparse/src/main.rs
+++ b/crates/liteparse/src/main.rs
@@ -2,6 +2,7 @@ use clap::{Args, Parser, Subcommand};
use liteparse::config::{LiteParseConfig, OutputFormat};
use liteparse::conversion;
use liteparse::extract;
+use liteparse::ocr_merge::LayoutComplexityReason;
use liteparse::output::{json, text};
use liteparse::parser::LiteParse;
use liteparse::render;
@@ -572,11 +573,24 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
} else {
"SIMPLE"
};
+ let layout_count = |reason: LayoutComplexityReason| {
+ is_complex
+ .iter()
+ .filter(|c| {
+ c.layout
+ .as_ref()
+ .is_some_and(|l| l.reasons.contains(&reason))
+ })
+ .count()
+ };
eprintln!(
- "{} — {}/{} page(s) need OCR",
+ "{} — {}/{} page(s) need OCR; layout: {} multi-column, {} table, {} graphics-dense",
verdict,
complex_pages,
- is_complex.len()
+ is_complex.len(),
+ layout_count(LayoutComplexityReason::MultiColumn),
+ layout_count(LayoutComplexityReason::TableLikely),
+ layout_count(LayoutComplexityReason::DenseGraphics),
);
}
diff --git a/crates/liteparse/src/markdown_layout/mod.rs b/crates/liteparse/src/markdown_layout/mod.rs
index 5bbff91..80fe019 100644
--- a/crates/liteparse/src/markdown_layout/mod.rs
+++ b/crates/liteparse/src/markdown_layout/mod.rs
@@ -23,6 +23,7 @@ pub use classify::classify_page_with_filters;
pub use headings::{build_heading_map, compute_body_size};
pub use repetition::{compute_header_footer_set, detect_single_page_chrome};
pub use tables::detect_table_rects;
+pub(crate) use tables::{count_text_table_runs, validated_ruled_table_rects};
/// Minimum plausible text-row height in points. Floors a `bbox.height` before
/// it is multiplied into a band / tolerance window, so a degenerate near-zero
diff --git a/crates/liteparse/src/markdown_layout/tables.rs b/crates/liteparse/src/markdown_layout/tables.rs
index f4039ee..465d81d 100644
--- a/crates/liteparse/src/markdown_layout/tables.rs
+++ b/crates/liteparse/src/markdown_layout/tables.rs
@@ -1132,6 +1132,55 @@ fn absorb_header_lines(
/// `start`). Caller uses these as cut-points so the per-line classifier never
/// sees lines inside a table.
pub(super) fn detect_tables(lines: &[ProjectedLine]) -> Vec<TableRun> {
+ detect_tables_impl(lines, true)
+}
+
+/// Count borderless table runs for the layout-complexity stats. Excludes
+/// description lists — a label/value pair block reads fine as text, so it
+/// should not flag the page as table-bearing. `GridFallback` runs DO count:
+/// tabular structure the emitter couldn't extract cleanly is the strongest
+/// possible "route this page to a better parser" signal.
+pub(crate) fn count_text_table_runs(lines: &[ProjectedLine]) -> usize {
+ detect_tables_impl(lines, false).len()
+}
+
+/// Validated ruled-table rects for the layout-complexity stats. Unlike the
+/// raw grid components (`detect_table_rects`, which deliberately over-captures
+/// for use as XY-cut obstacles), each candidate grid here is confirmed against
+/// the projected text by `build_ruled_table` — so a plain boxed callout or a
+/// chart's axis gridlines, which have the lines but not the cell structure,
+/// don't count. Returns the bounding rect of each run's consumed lines.
+pub(crate) fn validated_ruled_table_rects(
+ lines: &[ProjectedLine],
+ graphics: &[GraphicPrimitive],
+ page_width: f32,
+ page_height: f32,
+) -> Vec<Rect> {
+ detect_ruled_tables_global(lines, graphics, page_width, page_height)
+ .into_iter()
+ .filter_map(|(_, consumed)| {
+ let mut x0 = f32::INFINITY;
+ let mut y0 = f32::INFINITY;
+ let mut x1 = f32::NEG_INFINITY;
+ let mut y1 = f32::NEG_INFINITY;
+ for &i in &consumed {
+ let b = &lines[i].bbox;
+ x0 = x0.min(b.x);
+ y0 = y0.min(b.y);
+ x1 = x1.max(b.x + b.width);
+ y1 = y1.max(b.y + b.height);
+ }
+ (x1 > x0 && y1 > y0).then(|| Rect {
+ x: x0,
+ y: y0,
+ width: x1 - x0,
+ height: y1 - y0,
+ })
+ })
+ .collect()
+}
+
+fn detect_tables_impl(lines: &[ProjectedLine], include_desc_lists: bool) -> Vec<TableRun> {
let mut out = Vec::new();
let mut i = 0;
let mut floor = 0;
@@ -1144,7 +1193,10 @@ pub(super) fn detect_tables(lines: &[ProjectedLine]) -> Vec<TableRun> {
floor = run.end;
i = run.end;
out.push(run);
- } else if let Some(run) = try_detect_description_list(lines, i) {
+ } else if let Some(run) = include_desc_lists
+ .then(|| try_detect_description_list(lines, i))
+ .flatten()
+ {
floor = run.end;
i = run.end;
out.push(run);
@@ -3806,6 +3858,34 @@ mod tests {
);
}
+ #[test]
+ fn count_text_table_runs_excludes_description_lists() {
+ // A label/value stack detects as a description-list run, but must not
+ // count toward the layout-complexity table signal.
+ let lines = vec![
+ line_with_spans(&[("Name:", 50.0), ("Alice", 200.0)], 100.0, 10.0),
+ line_with_spans(&[("Role:", 50.0), ("Engineer", 200.0)], 115.0, 10.0),
+ line_with_spans(&[("Team:", 50.0), ("Platform", 200.0)], 130.0, 10.0),
+ line_with_spans(&[("Start:", 50.0), ("2020", 200.0)], 145.0, 10.0),
+ ];
+ assert_eq!(
+ detect_tables(&lines).len(),
+ 1,
+ "sanity: the emitter path should still claim this as a desc-list run"
+ );
+ assert_eq!(count_text_table_runs(&lines), 0);
+ }
+
+ #[test]
+ fn count_text_table_runs_counts_borderless_tables() {
+ let lines = vec![
+ line_with_spans(&[("A", 50.0), ("1", 150.0), ("2", 250.0)], 100.0, 10.0),
+ line_with_spans(&[("B", 50.0), ("3", 150.0), ("4", 250.0)], 115.0, 10.0),
+ line_with_spans(&[("C", 50.0), ("5", 150.0), ("6", 250.0)], 130.0, 10.0),
+ ];
+ assert_eq!(count_text_table_runs(&lines), 1);
+ }
+
#[test]
fn rejects_table_when_row_count_too_low() {
let lines = vec![line_with_spans(
diff --git a/crates/liteparse/src/ocr_merge.rs b/crates/liteparse/src/ocr_merge.rs
index 5b963c4..211baed 100644
--- a/crates/liteparse/src/ocr_merge.rs
+++ b/crates/liteparse/src/ocr_merge.rs
@@ -2,7 +2,7 @@ use std::sync::Arc;
use crate::error::LiteParseError;
use crate::ocr::{OcrEngine, OcrOptions, OcrResult};
-use crate::types::{Page, TextItem};
+use crate::types::{CutAxis, Page, ParsedPage, Region, RegionKind, TextItem};
use pdfium::{Document, ImageBounds};
use serde::Serialize;
@@ -23,6 +23,20 @@ const MIN_IMAGE_SIZE_PT: f32 = 25.0;
/// full-page background and ignored.
const MAX_IMAGE_PAGE_COVERAGE: f32 = 0.9;
+/// An XY-cut subtree must hold at least this many text items to count as a
+/// text column, regardless of page size.
+const MIN_COLUMN_ITEMS: usize = 8;
+
+/// ...and at least this fraction of the page's text items. Together with
+/// `MIN_COLUMN_ITEMS` this keeps thin sidebars, figure captions, and margin
+/// notes from flagging a page as multi-column. First-pass guess pending
+/// calibration against ParseBench's multi_column category.
+const MIN_COLUMN_ITEM_FRACTION: f32 = 0.15;
+
+/// Figure coverage at or above this fraction of the page area flags
+/// `DenseGraphics`. First-pass guess, same calibration caveat as above.
+const DENSE_GRAPHICS_MIN_COVERAGE: f32 = 0.2;
+
/// Owned page bitmap prepared for OCR. Indices refer to positions in the `pages` slice.
pub(crate) struct RenderedPage {
pub idx: usize,
@@ -111,6 +125,13 @@ pub struct PageComplexityStats {
pub needs_ocr: bool,
/// Every reason the page was flagged, in no particular priority order.
pub reasons: Vec<ComplexityReason>,
+ /// Layout-difficulty signals (columns, tables, dense graphics), computed
+ /// from the post-projection page. Orthogonal to `needs_ocr`/`reasons`:
+ /// none of these imply OCR. `None` in the internal per-page OCR gate
+ /// (`render_pages_for_ocr`), which never runs projection — only
+ /// `is_complex()` and `include_complexity` parses populate it.
+ #[serde(skip_serializing_if = "Option::is_none")]
+ pub layout: Option<LayoutComplexityStats>,
}
pub(crate) fn calculate_page_complexity(
@@ -232,9 +253,166 @@ pub(crate) fn calculate_page_complexity(
page_area,
needs_ocr,
reasons,
+ layout: None,
})
}
+/// Why a page's layout is expected to be hard to reconstruct faithfully.
+/// Orthogonal to `ComplexityReason`: none of these imply OCR — they signal
+/// that the text-only path may mangle reading order or structure, so a caller
+/// can route the page to a higher-accuracy pipeline. Same leniency contract
+/// as `ComplexityReason`: new variants will be added, treat unknowns kindly.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)]
+#[serde(rename_all = "kebab-case")]
+pub enum LayoutComplexityReason {
+ /// The XY-cut layout tree splits the page into two or more side-by-side
+ /// regions that each hold a substantial share of the text.
+ MultiColumn,
+ /// Table structure detected: ruled-line grid(s) and/or borderless
+ /// column-aligned text runs — the same detectors the markdown emitter
+ /// uses. Description lists (label/value pairs) do not count.
+ TableLikely,
+ /// Figure regions (charts, diagrams, decorated boxes) cover a large
+ /// fraction of the page; their vector content is invisible to text
+ /// extraction.
+ DenseGraphics,
+}
+
+impl LayoutComplexityReason {
+ pub fn as_str(&self) -> &'static str {
+ match self {
+ LayoutComplexityReason::MultiColumn => "multi-column",
+ LayoutComplexityReason::TableLikely => "table-likely",
+ LayoutComplexityReason::DenseGraphics => "dense-graphics",
+ }
+ }
+}
+
+#[derive(Debug, Clone, Serialize)]
+pub struct LayoutComplexityStats {
+ /// Side-by-side text columns found by the XY-cut layout pass (1 = single
+ /// column). Only subtrees holding a substantial share of the page's text
+ /// count, so a thin sidebar or caption does not inflate this.
+ pub column_count: usize,
+ /// Validated ruled-table runs on the page: grid components confirmed
+ /// against the projected text, so a boxed callout or a chart's axis
+ /// gridlines don't count (raw grid detection fired on 94% of ParseBench's
+ /// chart docs; validation is what makes this a *table* signal).
+ pub ruled_table_count: usize,
+ /// Combined validated ruled-table area (text extent) over page area,
+ /// clamped to 1.0.
+ pub ruled_table_coverage: f32,
+ /// Borderless table runs found by the emitter's track-alignment detector
+ /// over the projected lines (description lists excluded). Ruled tables can
+ /// appear here too — their text rows also align to tracks — so do not sum
+ /// this with `ruled_table_count`; the two discriminate "ruled" from
+ /// "borderless", they don't partition tables.
+ pub text_table_run_count: usize,
+ /// Figure regions clustered from vector graphics.
+ pub figure_count: usize,
+ /// Combined figure area over page area, clamped to 1.0. Overlapping rects
+ /// can inflate the sum past the truly covered fraction — same caveat as
+ /// `image_coverage`.
+ pub figure_coverage: f32,
+ /// Whether any layout reason fired. Equivalent to `!reasons.is_empty()`,
+ /// kept flat for the common predicate case (mirrors `needs_ocr`).
+ pub is_complex: bool,
+ pub reasons: Vec<LayoutComplexityReason>,
+}
+
+/// Compute layout-difficulty signals from a projected page. Read-only over
+/// structures projection already built: the XY-cut region tree for columns,
+/// `figures` for graphics density, and the emitter's own table detectors —
+/// validated ruled grids and borderless track-aligned runs — over the
+/// projected lines and vector primitives.
+pub(crate) fn calculate_layout_complexity(page: &ParsedPage) -> LayoutComplexityStats {
+ let page_area = page.page_width * page.page_height;
+ let total_items = page.text_items.len();
+
+ let column_count = count_columns(&page.regions, total_items).max(1);
+
+ let table_rects = crate::markdown_layout::validated_ruled_table_rects(
+ &page.projected_lines,
+ &page.graphics,
+ page.page_width,
+ page.page_height,
+ );
+ let text_table_run_count = crate::markdown_layout::count_text_table_runs(&page.projected_lines);
+ let table_area: f32 = table_rects
+ .iter()
+ .map(|r| r.width.max(0.0) * r.height.max(0.0))
+ .sum();
+ let figure_area: f32 = page
+ .figures
+ .iter()
+ .map(|r| r.width.max(0.0) * r.height.max(0.0))
+ .sum();
+ // The `area > 0.0` guard also normalizes the `-0.0` an empty `f32` sum
+ // yields, which would otherwise serialize as `-0.0` in JSON.
+ let coverage = |area: f32| {
+ if page_area > 0.0 && area > 0.0 {
+ (area / page_area).min(1.0)
+ } else {
+ 0.0
+ }
+ };
+ let ruled_table_coverage = coverage(table_area);
+ let figure_coverage = coverage(figure_area);
+
+ let mut reasons = Vec::new();
+ if column_count >= 2 {
+ reasons.push(LayoutComplexityReason::MultiColumn);
+ }
+ if !table_rects.is_empty() || text_table_run_count > 0 {
+ reasons.push(LayoutComplexityReason::TableLikely);
+ }
+ if figure_coverage >= DENSE_GRAPHICS_MIN_COVERAGE {
+ reasons.push(LayoutComplexityReason::DenseGraphics);
+ }
+
+ LayoutComplexityStats {
+ column_count,
+ ruled_table_count: table_rects.len(),
+ ruled_table_coverage,
+ text_table_run_count,
+ figure_count: page.figures.len(),
+ figure_coverage,
+ is_complex: !reasons.is_empty(),
+ reasons,
+ }
+}
+
+fn region_item_count(region: &Region) -> usize {
+ match &region.kind {
+ RegionKind::Leaf { item_indices } => item_indices.len(),
+ RegionKind::Split { children, .. } => children.iter().map(region_item_count).sum(),
+ }
+}
+
+/// Count side-by-side text columns in an XY-cut subtree. Subtrees below the
+/// substantiality bar contribute zero. Vertical splits sum their children
+/// (side-by-side regions), horizontal splits take the max of theirs (stacked
+/// bands — a full-width title above a two-column body is a two-column page).
+/// Nested vertical splits therefore count correctly: a three-column page cut
+/// as `V(a, V(b, c))` yields 3.
+fn count_columns(region: &Region, total_items: usize) -> usize {
+ let min_items =
+ MIN_COLUMN_ITEMS.max((total_items as f32 * MIN_COLUMN_ITEM_FRACTION).ceil() as usize);
+ if region_item_count(region) < min_items {
+ return 0;
+ }
+ match &region.kind {
+ RegionKind::Leaf { .. } => 1,
+ RegionKind::Split { axis, children } => {
+ let counts = children.iter().map(|c| count_columns(c, total_items));
+ match axis {
+ CutAxis::Vertical => counts.sum(),
+ CutAxis::Horizontal => counts.max().unwrap_or(0),
+ }
+ }
+ }
+}
+
/// Render pages that need OCR from an already-open document.
///
/// The pdfium `Document` holds raw pointers that are not `Send`, so callers must
@@ -734,6 +912,75 @@ fn clean_ocr_table_artifacts(text: &str) -> String {
#[cfg(test)]
mod tests {
use super::*;
+ use crate::types::Rect;
+
+ fn leaf(n: usize) -> Region {
+ Region {
+ bbox: Rect::default(),
+ kind: RegionKind::Leaf {
+ item_indices: (0..n).collect(),
+ },
+ }
+ }
+
+ fn split(axis: CutAxis, children: Vec<Region>) -> Region {
+ Region {
+ bbox: Rect::default(),
+ kind: RegionKind::Split { axis, children },
+ }
+ }
+
+ #[test]
+ fn test_count_columns_single_leaf() {
+ assert_eq!(count_columns(&leaf(50), 50), 1);
+ }
+
+ #[test]
+ fn test_count_columns_two_columns() {
+ let root = split(CutAxis::Vertical, vec![leaf(40), leaf(40)]);
+ assert_eq!(count_columns(&root, 80), 2);
+ }
+
+ #[test]
+ fn test_count_columns_nested_three_columns() {
+ // Three-column page cut as V(a, V(b, c)).
+ let inner = split(CutAxis::Vertical, vec![leaf(30), leaf(30)]);
+ let root = split(CutAxis::Vertical, vec![leaf(40), inner]);
+ assert_eq!(count_columns(&root, 100), 3);
+ }
+
+ #[test]
+ fn test_count_columns_header_over_two_columns() {
+ // Full-width title band stacked above a two-column body: the page is
+ // still two-column (horizontal splits take the max of their bands).
+ let body = split(CutAxis::Vertical, vec![leaf(40), leaf(40)]);
+ let root = split(CutAxis::Horizontal, vec![leaf(20), body]);
+ assert_eq!(count_columns(&root, 100), 2);
+ }
+
+ #[test]
+ fn test_count_columns_thin_sidebar_not_a_column() {
+ // A 6-item sidebar next to a 94-item body fails both the absolute
+ // (8-item) and fractional (15%) bars.
+ let root = split(CutAxis::Vertical, vec![leaf(6), leaf(94)]);
+ assert_eq!(count_columns(&root, 100), 1);
+ }
+
+ #[test]
+ fn test_count_columns_narrow_table_slices_not_columns() {
+ // Four narrow slices (10 items each of 100): each fails the 15%
+ // fractional bar, so none count — table-ish V-splits stay quiet.
+ let root = split(
+ CutAxis::Vertical,
+ vec![leaf(10), leaf(10), leaf(10), leaf(10)],
+ );
+ assert_eq!(count_columns(&root, 100), 0);
+ }
+
+ #[test]
+ fn test_count_columns_empty_page() {
+ assert_eq!(count_columns(&leaf(0), 0), 0);
+ }
#[test]
fn test_polygon_rotation_horizontal() {
diff --git a/crates/liteparse/src/parser.rs b/crates/liteparse/src/parser.rs
index dd5aa17..adc2541 100644
--- a/crates/liteparse/src/parser.rs
+++ b/crates/liteparse/src/parser.rs
@@ -133,6 +133,11 @@ impl LiteParse {
/// Determine the complexity of each page in a document, returning a vector
/// of `PageComplexityStats` for each page. This is useful for deciding
/// whether to enable OCR on a per-page basis, or for other heuristics.
+ ///
+ /// Besides the OCR-need signals, each entry carries `layout` signals
+ /// (multi-column, ruled tables, dense graphics) computed by running the
+ /// real grid-projection pass — useful for routing pages to a
+ /// higher-accuracy pipeline even when no OCR is needed.
pub async fn is_complex(
&self,
input: PdfInput,
@@ -161,36 +166,60 @@ impl LiteParse {
// pass fast (its whole purpose is a cheap pre-OCR check).
let password = self.config.password.as_deref();
- let lib = Library::init();
- let document = extract::load_document_from_input(&lib, &validated_input, password)?;
-
- let (pages, _) = extract::extract_pages_and_images(
- &document,
- target_pages.as_deref(),
- self.config.max_pages,
- false, // render_images: image rasters not needed for complexity
- false, // extract_links: irrelevant for complexity stats
- self.glyph_resolver.as_deref(),
- false, // emit_word_boxes: word boxes not needed for complexity stats
- )?;
- let t_extract = web_time::Instant::now();
- log(&format!(
- "[liteparse] extract: {:.1}ms ({} pages)",
- t_extract.duration_since(t0).as_secs_f64() * 1000.0,
- pages.len()
- ));
+ let (pages, mut page_complexities) = {
+ let lib = Library::init();
+ let document = extract::load_document_from_input(&lib, &validated_input, password)?;
- let t_complexity = web_time::Instant::now();
- let page_complexities = pages
- .iter()
- .map(|page| {
- let page_obj = document.page((page.page_number - 1) as i32)?;
- ocr_merge::calculate_page_complexity(page, &page_obj)
- })
- .collect::<Result<Vec<_>, _>>()?;
+ let (pages, _) = extract::extract_pages_and_images(
+ &document,
+ target_pages.as_deref(),
+ self.config.max_pages,
+ false, // render_images: image rasters not needed for complexity
+ false, // extract_links: irrelevant for complexity stats
+ self.glyph_resolver.as_deref(),
+ false, // emit_word_boxes: word boxes not needed for complexity stats
+ )?;
+ let t_extract = web_time::Instant::now();
+ log(&format!(
+ "[liteparse] extract: {:.1}ms ({} pages)",
+ t_extract.duration_since(t0).as_secs_f64() * 1000.0,
+ pages.len()
+ ));
+
+ let page_complexities = pages
+ .iter()
+ .map(|page| {
+ let page_obj = document.page((page.page_number - 1) as i32)?;
+ ocr_merge::calculate_page_complexity(page, &page_obj)
+ })
+ .collect::<Result<Vec<_>, _>>()?;
+ log(&format!(
+ "[liteparse] complexity: {:.1}ms",
+ web_time::Instant::now()
+ .duration_since(t_extract)
+ .as_secs_f64()
+ * 1000.0
+ ));
+ // `lib` is dropped here, releasing the PDFium lock; the layout
+ // pass below is pure CPU over the already-extracted items.
+ (pages, page_complexities)
+ };
+
+ // Layout signals come from the projected page: the XY-cut region tree
+ // for columns, figure clusters and ruled-table rects for graphics and
+ // tables. Running real projection here (rather than approximating)
+ // keeps the signals identical to what a full parse will decide.
+ let t_layout = web_time::Instant::now();
+ let parsed_pages = projection::project_pages_to_grid(pages);
+ for (stats, page) in page_complexities.iter_mut().zip(&parsed_pages) {
+ stats.layout = Some(ocr_merge::calculate_layout_complexity(page));
+ }
log(&format!(
- "[liteparse] complexity: {:.1}ms",
- t_complexity.duration_since(t_extract).as_secs_f64() * 1000.0
+ "[liteparse] layout: {:.1}ms",
+ web_time::Instant::now()
+ .duration_since(t_layout)
+ .as_secs_f64()
+ * 1000.0
));
Ok(page_complexities)
@@ -373,8 +402,10 @@ impl LiteParse {
// Grid projection
let mut parsed_pages = projection::project_pages_to_grid(pages);
- // Attach per-page complexity signals
- for (page, stats) in parsed_pages.iter_mut().zip(complexity) {
+ // Attach per-page complexity signals, including the layout signals
+ // that need the projected page (same as `is_complex()` reports).
+ for (page, mut stats) in parsed_pages.iter_mut().zip(complexity) {
+ stats.layout = Some(ocr_merge::calculate_layout_complexity(page));
page.complexity = Some(stats);
}
let t2 = web_time::Instant::now();
diff --git a/packages/node/src/cli.ts b/packages/node/src/cli.ts
index 39df8c6..9be4554 100644
--- a/packages/node/src/cli.ts
+++ b/packages/node/src/cli.ts
@@ -208,8 +208,13 @@ program
// the exit code below carries the same signal for scripts.
if (!opts.quiet) {
const verdict = complexPages > 0 ? "COMPLEX" : "SIMPLE";
+ const layoutCount = (reason: string) =>
+ stats.filter((s) => s.layout?.reasons.includes(reason)).length;
console.error(
- `${verdict} — ${complexPages}/${stats.length} page(s) need OCR`,
+ `${verdict} — ${complexPages}/${stats.length} page(s) need OCR; ` +
+ `layout: ${layoutCount("multi-column")} multi-column, ` +
+ `${layoutCount("table-likely")} table, ` +
+ `${layoutCount("dense-graphics")} graphics-dense`,
);
}
diff --git a/packages/node/src/lib.ts b/packages/node/src/lib.ts
index c28a9ba..a93fbde 100644
--- a/packages/node/src/lib.ts
+++ b/packages/node/src/lib.ts
@@ -234,6 +234,44 @@ export interface PageComplexityStats {
* route on; new reasons may be added over time.
*/
reasons: string[];
+ /**
+ * Layout-difficulty signals (columns, tables, dense graphics). Orthogonal to
+ * `needsOcr`: none of these imply OCR — they signal that the text-only path
+ * may mangle reading order or structure. Present in `isComplex()` results
+ * and `includeComplexity` parses.
+ */
+ layout?: LayoutComplexityStats;
+}
+
+/**
+ * Layout-difficulty signals for one page, computed from the real
+ * grid-projection pass.
+ */
+export interface LayoutComplexityStats {
+ /** Side-by-side text columns found by the layout pass (1 = single column). */
+ columnCount: number;
+ /** Ruled-table grids detected on the page. */
+ ruledTableCount: number;
+ /** Combined ruled-table area over page area, clamped to 1. */
+ ruledTableCoverage: number;
+ /**
+ * Borderless table runs found by track-aligned text detection (description
+ * lists excluded). Ruled tables can appear here too — don't sum with
+ * `ruledTableCount`; the two discriminate ruled from borderless.
+ */
+ textTableRunCount: number;
+ /** Figure regions clustered from vector graphics. */
+ figureCount: number;
+ /** Combined figure area over page area, clamped to 1. */
+ figureCoverage: number;
+ /** Verdict: whether any layout reason fired. */
+ isComplex: boolean;
+ /**
+ * Every layout reason (e.g. `"multi-column"`, `"table-likely"`,
+ * `"dense-graphics"`). Empty exactly when `isComplex` is false; new reasons
+ * may be added over time.
+ */
+ reasons: string[];
}
// ---------------------------------------------------------------------------
@@ -383,6 +421,18 @@ function toComplexity(s: NativePageComplexityStats): PageComplexityStats {
pageArea: s.pageArea,
needsOcr: s.needsOcr,
reasons: s.reasons,
+ layout: s.layout
+ ? {
+ columnCount: s.layout.columnCount,
+ ruledTableCount: s.layout.ruledTableCount,
+ ruledTableCoverage: s.layout.ruledTableCoverage,
+ textTableRunCount: s.layout.textTableRunCount,
+ figureCount: s.layout.figureCount,
+ figureCoverage: s.layout.figureCoverage,
+ isComplex: s.layout.isComplex,
+ reasons: s.layout.reasons,
+ }
+ : undefined,
};
}
diff --git a/packages/node/src/native.ts b/packages/node/src/native.ts
index 22d8acc..f9a0967 100644
--- a/packages/node/src/native.ts
+++ b/packages/node/src/native.ts
@@ -126,6 +126,17 @@ export interface NativeScreenshotResult {
imageBuffer: Buffer;
}
+export interface NativeLayoutComplexityStats {
+ columnCount: number;
+ ruledTableCount: number;
+ ruledTableCoverage: number;
+ textTableRunCount: number;
+ figureCount: number;
+ figureCoverage: number;
+ isComplex: boolean;
+ reasons: string[];
+}
+
export interface NativePageComplexityStats {
pageNumber: number;
textLength: number;
@@ -140,6 +151,7 @@ export interface NativePageComplexityStats {
pageArea: number;
needsOcr: boolean;
reasons: string[];
+ layout?: NativeLayoutComplexityStats;
}
export interface LiteParseNative {
diff --git a/packages/python/liteparse/__init__.py b/packages/python/liteparse/__init__.py
index 53e99d7..196657f 100644
--- a/packages/python/liteparse/__init__.py
+++ b/packages/python/liteparse/__init__.py
@@ -3,6 +3,7 @@ from importlib.metadata import PackageNotFoundError, version
from .parser import LiteParse, search_items
from .types import (
ExtractedImage,
+ LayoutComplexityStats,
LiteParseConfig,
PageComplexityStats,
ParseResult,
@@ -26,6 +27,7 @@ __all__ = [
"WordBox",
"ScreenshotResult",
"PageComplexityStats",
+ "LayoutComplexityStats",
"ExtractedImage",
"ParseError",
"search_items",
diff --git a/packages/python/liteparse/parser.py b/packages/python/liteparse/parser.py
index c776798..f41cd26 100644
--- a/packages/python/liteparse/parser.py
+++ b/packages/python/liteparse/parser.py
@@ -8,6 +8,7 @@ from liteparse._liteparse import search_items as _native_search_items
from .types import (
ExtractedImage,
+ LayoutComplexityStats,
LiteParseConfig,
PageComplexityStats,
ParsedPage,
@@ -35,6 +36,20 @@ def _convert_complexity(s: Any) -> PageComplexityStats:
page_area=s.page_area,
needs_ocr=s.needs_ocr,
reasons=list(s.reasons),
+ layout=(
+ LayoutComplexityStats(
+ column_count=s.layout.column_count,
+ ruled_table_count=s.layout.ruled_table_count,
+ ruled_table_coverage=s.layout.ruled_table_coverage,
+ text_table_run_count=s.layout.text_table_run_count,
+ figure_count=s.layout.figure_count,
+ figure_coverage=s.layout.figure_coverage,
+ is_complex=s.layout.is_complex,
+ reasons=list(s.layout.reasons),
+ )
+ if getattr(s, "layout", None) is not None
+ else None
+ ),
)
diff --git a/packages/python/liteparse/types.py b/packages/python/liteparse/types.py
index e12dfd0..b8d30d1 100644
--- a/packages/python/liteparse/types.py
+++ b/packages/python/liteparse/types.py
@@ -91,6 +91,33 @@ class ScreenshotResult:
image_bytes: bytes
+@dataclass
+class LayoutComplexityStats:
+ """Layout-difficulty signals for one page (columns, tables, dense
+ graphics), computed from the real grid-projection pass. Orthogonal to
+ ``needs_ocr``: none of these imply OCR — they signal that the text-only
+ path may mangle reading order or structure."""
+ #: Side-by-side text columns found by the layout pass (1 = single column).
+ column_count: int
+ #: Ruled-table grids detected.
+ ruled_table_count: int
+ #: Combined ruled-table area over page area, clamped to 1.
+ ruled_table_coverage: float
+ #: Borderless table runs found by track-aligned text detection
+ #: (description lists excluded). Ruled tables can appear here too — do not
+ #: sum with ``ruled_table_count``.
+ text_table_run_count: int
+ #: Figure regions clustered from vector graphics.
+ figure_count: int
+ #: Combined figure area over page area, clamped to 1.
+ figure_coverage: float
+ #: Whether any layout reason fired.
+ is_complex: bool
+ #: Layout reasons (e.g. ``"multi-column"``, ``"table-likely"``,
+ #: ``"dense-graphics"``); new reasons may be added over time.
+ reasons: list[str]
+
+
@dataclass
class PageComplexityStats:
"""Per-page complexity signals used to decide whether a document needs OCR."""
@@ -107,6 +134,8 @@ class PageComplexityStats:
page_area: float
needs_ocr: bool
reasons: list[str]
+ #: Layout-difficulty signals; see :class:`LayoutComplexityStats`.
+ layout: Optional[LayoutComplexityStats] = None
@dataclass