A fast, helpful, and open-source document parser
fix(ocr): attach word boxes to OCR text items
Yi-111-a26e79210c016
diff --git a/crates/liteparse/src/config.rs b/crates/liteparse/src/config.rsindex 8cf1b7f..65ba55e 100644--- a/crates/liteparse/src/config.rs+++ b/crates/liteparse/src/config.rs@@ -251,6 +251,19 @@ impl LiteParseConfig {pub fn effective_extract_images(&self) -> bool {self.extract_images || self.image_mode == ImageMode::Embed}++ /// Whether per-word boxes are needed for this run, whichever stage+ /// produces the text. True when `emit_word_boxes` is set, or when the+ /// markdown output format is selected: the markdown table detector splits+ /// PDFium's merged multi-cell runs on real word geometry, so it needs+ /// word boxes even when the caller didn't ask for them.+ ///+ /// Every stage that fills `TextItem.words` must gate on this, so a run+ /// with word boxes off stays allocation-free on the whole path — including+ /// the OCR merge, where native text and scanned pages must agree.+ pub fn effective_emit_word_boxes(&self) -> bool {+ self.emit_word_boxes || self.output_format == OutputFormat::Markdown+ }}impl Default for LiteParseConfig {diff --git a/crates/liteparse/src/ocr_merge.rs b/crates/liteparse/src/ocr_merge.rsindex 2180d92..a8d0457 100644--- a/crates/liteparse/src/ocr_merge.rs+++ b/crates/liteparse/src/ocr_merge.rs@@ -3,7 +3,7 @@ use std::sync::Arc;use crate::error::LiteParseError;use crate::ocr::{OcrEngine, OcrOptions, OcrResult};-use crate::types::{CutAxis, Page, ParsedPage, Rect, Region, RegionKind, TextItem};+use crate::types::{CutAxis, Page, ParsedPage, Rect, Region, RegionKind, TextItem, WordBox};use pdfium::{Document, ImageBounds};use serde::{Deserialize, Serialize};@@ -988,10 +988,19 @@ pub async fn recognize_rasters(/// Outcomes are matched to pages by `page_number`; an outcome for a page not/// in `pages` is an error rather than a panic, so a caller can merge a/// subset of pages or hand-built outcomes safely.+///+/// `emit_word_boxes` must match what the extraction stage used+/// (`LiteParseConfig::effective_emit_word_boxes`). An engine reports one+/// [`OcrResult`] per word, so each surviving result becomes a one-word+/// [`TextItem`]; the item's own word box is attached here, which is what lets+/// the projection pass merge neighbouring OCR items into a run that still+/// carries per-word boxes. When `false`, no box is attached, matching the+/// zero-allocation promise the config makes for native text.pub fn merge_ocr_results(pages: &mut [Page],outcomes: Vec<PageOcrOutcome>,ocr_failure_fatal: bool,+ emit_word_boxes: bool,) -> Result<(), LiteParseError> {// Track OCR task outcomes so we can distinguish a systemic failure (e.g.// missing Tesseract language data, which fails identically on every page)@@ -1195,6 +1204,21 @@ pub fn merge_ocr_results(ocr_h};+ // The engine already segmented this result as a single word, so+ // its box is the item's box. The clone only happens when the+ // caller asked for word boxes.+ let words = if emit_word_boxes {+ vec![WordBox {+ text: cleaned.clone(),+ x: ocr_x,+ y: ocr_y,+ width: ocr_w,+ height: ocr_h,+ }]+ } else {+ Vec::new()+ };+page.text_items.push(TextItem {text: cleaned,x: ocr_x,@@ -1205,6 +1229,7 @@ pub fn merge_ocr_results(font_name: Some("OCR".to_string()),font_size: Some(font_size_hint),confidence: Some((r.confidence * 1000.0).round() / 1000.0),+ words,..Default::default()});}@@ -2225,9 +2250,10 @@ mod tests {language: &str,num_workers: usize,ocr_failure_fatal: bool,+ emit_word_boxes: bool,) -> Result<(), LiteParseError> {let outcomes = recognize_rasters(rendered, engine, language, num_workers).await;- merge_ocr_results(pages, outcomes, ocr_failure_fatal)+ merge_ocr_results(pages, outcomes, ocr_failure_fatal, emit_word_boxes)}// A page that already has substantial native text coverage, as would be the@@ -2295,7 +2321,8 @@ mod tests {let rendered = vec![make_rendered(0), make_rendered(1)];let engine: Arc<dyn OcrEngine> = Arc::new(FailingEngine);- let result = ocr_and_merge_rendered(&mut pages, rendered, engine, "eng", 2, true).await;+ let result =+ ocr_and_merge_rendered(&mut pages, rendered, engine, "eng", 2, true, false).await;let err = result.expect_err("expected systemic OCR failure to be surfaced");let msg = err.to_string();@@ -2316,7 +2343,8 @@ mod tests {let mut pages = vec![make_blank_page(1)];let engine: Arc<dyn OcrEngine> = Arc::new(FailingEngine);- let result = ocr_and_merge_rendered(&mut pages, Vec::new(), engine, "eng", 2, true).await;+ let result =+ ocr_and_merge_rendered(&mut pages, Vec::new(), engine, "eng", 2, true, false).await;assert!(result.is_ok(), "empty OCR set should succeed: {result:?}");}@@ -2330,7 +2358,8 @@ mod tests {let rendered = vec![make_rendered(0), make_rendered(1)];let engine: Arc<dyn OcrEngine> = Arc::new(FailingEngine);- let result = ocr_and_merge_rendered(&mut pages, rendered, engine, "eng", 2, true).await;+ let result =+ ocr_and_merge_rendered(&mut pages, rendered, engine, "eng", 2, true, false).await;assert!(result.is_ok(),@@ -2350,7 +2379,8 @@ mod tests {let rendered = vec![make_rendered(0), make_rendered(1)];let engine: Arc<dyn OcrEngine> = Arc::new(FailingEngine);- let result = ocr_and_merge_rendered(&mut pages, rendered, engine, "eng", 2, true).await;+ let result =+ ocr_and_merge_rendered(&mut pages, rendered, engine, "eng", 2, true, false).await;let err = result.expect_err("a text-starved page losing all OCR must surface an error");assert!(@@ -2368,7 +2398,8 @@ mod tests {let rendered = vec![make_rendered(0)];let engine: Arc<dyn OcrEngine> = Arc::new(FailingEngine);- let result = ocr_and_merge_rendered(&mut pages, rendered, engine, "eng", 2, true).await;+ let result =+ ocr_and_merge_rendered(&mut pages, rendered, engine, "eng", 2, true, false).await;let err = result.expect_err("low-coverage text page losing OCR must surface an error");assert!(@@ -2387,7 +2418,8 @@ mod tests {let rendered = vec![make_rendered(0), make_rendered(1)];let engine: Arc<dyn OcrEngine> = Arc::new(FailingEngine);- let result = ocr_and_merge_rendered(&mut pages, rendered, engine, "eng", 2, false).await;+ let result =+ ocr_and_merge_rendered(&mut pages, rendered, engine, "eng", 2, false, false).await;assert!(result.is_ok(),@@ -2396,4 +2428,61 @@ mod tests {// The native-text page keeps its text; the blank page simply has no OCR.assert_eq!(pages[0].text_items.len(), 1);}++ /// An OCR-sourced `TextItem` must carry a word box the way a native one+ /// does. The engine already reports one word per result (`RIL_WORD` for+ /// Tesseract), so the item's own text and box are the word box. Without+ /// it the projection pass has nothing to carry forward when it joins+ /// neighbouring OCR items into a run, so a caller asking for word boxes+ /// gets them on native text only and none on scanned pages (#473).+ #[test]+ fn test_ocr_items_carry_word_boxes_when_enabled() {+ let outcome = |page_number: usize| PageOcrOutcome {+ page_number,+ dpi: 72.0,+ has_native_text: false,+ image_rects: Vec::new(),+ results: vec![+ OcrResult {+ text: "hello".into(),+ bbox: [10.0, 20.0, 60.0, 30.0],+ confidence: 0.9,+ polygon: None,+ },+ OcrResult {+ text: "world".into(),+ bbox: [62.0, 20.0, 110.0, 30.0],+ confidence: 0.9,+ polygon: None,+ },+ ],+ error: None,+ };++ let mut enabled = vec![make_blank_page(1)];+ merge_ocr_results(&mut enabled, vec![outcome(1)], false, true).unwrap();+ assert_eq!(enabled[0].text_items.len(), 2);+ for item in &enabled[0].text_items {+ assert_eq!(+ item.words.len(),+ 1,+ "OCR item {:?} should carry one word box",+ item.text+ );+ let word = &item.words[0];+ assert_eq!(word.text, item.text);+ assert_eq!(+ (word.x, word.y, word.width, word.height),+ (item.x, item.y, item.width, item.height),+ "the word box is the result's own box"+ );+ }++ // The same input with word boxes off must stay allocation-free, as+ // `LiteParseConfig::emit_word_boxes` promises for native text.+ let mut disabled = vec![make_blank_page(1)];+ merge_ocr_results(&mut disabled, vec![outcome(1)], false, false).unwrap();+ assert_eq!(disabled[0].text_items.len(), 2);+ assert!(disabled[0].text_items.iter().all(|i| i.words.is_empty()));+ }}diff --git a/crates/liteparse/src/parser.rs b/crates/liteparse/src/parser.rsindex 4fb0d5f..6f1581d 100644--- a/crates/liteparse/src/parser.rs+++ b/crates/liteparse/src/parser.rs@@ -323,10 +323,7 @@ impl LiteParse {continue_on_page_error: self.config.continue_on_page_error,extract_content_bounds: self.config.extract_content_bounds,extract_images: self.config.effective_extract_images(),- // The markdown table detector splits PDFium's merged- // multi-cell runs on real word geometry, so it needs word- // boxes even when the caller didn't ask for them.- emit_word_boxes: self.config.emit_word_boxes || markdown,+ emit_word_boxes: self.config.effective_emit_word_boxes(),extract_text_metadata: self.config.extract_text_metadata,extract_vector_graphics: self.config.extract_vector_graphics,extract_annotations: self.config.extract_annotations,@@ -819,7 +816,12 @@ impl LiteParse {self.config.num_workers,).await;- stages::merge_ocr(&mut pages, outcomes, self.config.ocr_failure_fatal)?;+ stages::merge_ocr(+ &mut pages,+ outcomes,+ self.config.ocr_failure_fatal,+ self.config.effective_emit_word_boxes(),+ )?;}}let t_ocr = web_time::Instant::now();diff --git a/crates/liteparse/src/stages.rs b/crates/liteparse/src/stages.rsindex 08d4c47..7b46a32 100644--- a/crates/liteparse/src/stages.rs+++ b/crates/liteparse/src/stages.rs@@ -244,12 +244,19 @@ pub async fn recognize(/// text, filter engine artifacts, append the surviving results as `OCR`/// text items in viewport points. Errors only when every outcome failed and/// one of the failed pages had no usable native text (`ocr_failure_fatal`).+///+/// Pass `LiteParseConfig::effective_emit_word_boxes` for `emit_word_boxes`:+/// each engine result is one word, so this is the only place the OCR path can+/// attach a word box, and it has to agree with what extraction used or a run+/// ends up with word boxes on native text only. See+/// [`ExtractionOutputOptions::emit_word_boxes`](crate::extract::ExtractionOutputOptions).pub fn merge_ocr(pages: &mut [Page],outcomes: Vec<PageOcrOutcome>,ocr_failure_fatal: bool,+ emit_word_boxes: bool,) -> Result<(), LiteParseError> {- ocr_merge::merge_ocr_results(pages, outcomes, ocr_failure_fatal)+ ocr_merge::merge_ocr_results(pages, outcomes, ocr_failure_fatal, emit_word_boxes)}// ── Content filters ────────────────────────────────────────────────────diff --git a/crates/liteparse/tests/stages_compose.rs b/crates/liteparse/tests/stages_compose.rsindex b85a819..4c82831 100644--- a/crates/liteparse/tests/stages_compose.rs+++ b/crates/liteparse/tests/stages_compose.rs@@ -316,7 +316,13 @@ async fn compose(parser: &LiteParse, input: PdfInput) -> ParseResult {).await;let outcomes = round_trip(outcomes, "Vec<PageOcrOutcome>");- stages::merge_ocr(&mut pages, outcomes, config.ocr_failure_fatal).unwrap();+ stages::merge_ocr(+ &mut pages,+ outcomes,+ config.ocr_failure_fatal,+ config.effective_emit_word_boxes(),+ )+ .unwrap();}}@@ -665,7 +671,7 @@ fn merge_ocr_rejects_outcome_for_unknown_page() {}],error: None,};- let err = stages::merge_ocr(&mut pages, vec![outcome], false).unwrap_err();+ let err = stages::merge_ocr(&mut pages, vec![outcome], false, false).unwrap_err();assert!(err.to_string().contains("page 7"), "{err}");}