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.rsindex 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.rsindex 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.rsindex 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.rsindex 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.rsindex 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-zerodiff --git a/crates/liteparse/src/markdown_layout/tables.rs b/crates/liteparse/src/markdown_layout/tables.rsindex 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.rsindex 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 ®ion.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 ®ion.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.rsindex 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 projectionlet 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.tsindex 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.tsindex 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.tsindex 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__.pyindex 53e99d7..196657f 100644--- a/packages/python/liteparse/__init__.py+++ b/packages/python/liteparse/__init__.py@@ -3,6 +3,7 @@ from importlib.metadata import PackageNotFoundError, versionfrom .parser import LiteParse, search_itemsfrom .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.pyindex 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_itemsfrom .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.pyindex 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]++@dataclassclass PageComplexityStats:"""Per-page complexity signals used to decide whether a document needs OCR."""@@ -107,6 +134,8 @@ class PageComplexityStats:page_area: floatneeds_ocr: boolreasons: list[str]+ #: Layout-difficulty signals; see :class:`LayoutComplexityStats`.+ layout: Optional[LayoutComplexityStats] = None@dataclass