Merge pull request #164 from artiz/claude/force-ocr

pdf: force_full_page_ocr on every surface (#157)

Author: artiz

README.md

@@ -386,7 +386,15 @@ all, only the PDF's embedded text cells grouped into flat paragraphs by
 reading order (no headings/lists/tables/pictures). It's the fastest PDF path
 by a wide margin, but a scanned/image-only PDF (no embedded text layer) comes
 back empty rather than erroring, so a caller can detect that and re-convert
-without the flag.
+without the flag. `--force-full-page-ocr` is the opposite escape hatch
+(docling's `force_full_page_ocr`): OCR every page from its rendered image
+even when it carries a text layer — for layers that exist but lie (broken
+encodings, subset fonts with garbage mappings, a scanned form with a few
+typed-in field values). Ignored under `--no-ocr`, mirroring docling. The same
+switch is available on every surface: `force_full_page_ocr(bool)` on the
+library builder, a `force_full_page_ocr` option in docling-serve, the
+`force_full_page_ocr=` kwarg in Python, `forceFullPageOcr` in Node, and the
+"Force OCR" toggle in the wasm demo.
 
 ### VLM pipeline (remote endpoint)
 

crates/docling-cli/src/main.rs

@@ -3,7 +3,7 @@
 //! The docling.rs counterpart of `docling.cli.main`; `docling-rs serve`
 //! (with `--features serve`) starts the HTTP conversion API.
 //!
-//! Usage: docling-rs [--strict] [--to md|json] [--pages A-B] [--images MODE] [--fetch-images] [--no-stream] [--no-table-former] [--no-ocr] [--ocr-lang en|ch] [--pipeline standard|vlm] [--vlm-endpoint URL] [--vlm-model NAME] [--asr-model PRESET] [--video-frames N] [--use-web-browser] [--enrich-picture-classes] [--enrich-code] [--enrich-formula] <input-file>
+//! Usage: docling-rs [--strict] [--to md|json] [--pages A-B] [--images MODE] [--fetch-images] [--no-stream] [--no-table-former] [--no-ocr] [--force-full-page-ocr] [--ocr-lang en|ch] [--pipeline standard|vlm] [--vlm-endpoint URL] [--vlm-model NAME] [--asr-model PRESET] [--video-frames N] [--use-web-browser] [--enrich-picture-classes] [--enrich-code] [--enrich-formula] <input-file>
 //!   --to md|json       output format (default: md). `json` emits docling-core's
 //!                      native DoclingDocument JSON (export_to_dict).
 //!   --pages A-B        convert only PDF pages A through B (1-based, inclusive;
@@ -37,6 +37,9 @@
 //!                      whisper_base_en, whisper_small_en, whisper_distil_small_en
 //!                      (models under models/asr/<preset>/; fetch them with
 //!                      download_dependencies.sh --asr-model=<preset>)
+//!   --force-full-page-ocr  OCR every PDF page even when it has a text layer
+//!                      (docling's force_full_page_ocr) — for layers that lie:
+//!                      broken encodings, forms with a few typed-in fields
 //!   --no-ocr           skip layout detection, OCR, and TableFormer entirely for
 //!                      PDF/image input — no model load or inference at all.
 //!                      Emits the embedded text layer as flat paragraphs in
@@ -86,6 +89,7 @@ fn main() -> ExitCode {
     let mut no_stream = false;
     let mut no_table_former = false;
     let mut no_ocr = false;
+    let mut force_full_page_ocr = false;
     let mut use_web_browser = false;
     let mut asr_model: Option<String> = None;
     let mut video_frames: Option<usize> = None;
@@ -107,6 +111,7 @@ fn main() -> ExitCode {
             "--no-stream" => no_stream = true,
             "--no-table-former" => no_table_former = true,
             "--no-ocr" => no_ocr = true,
+            "--force-full-page-ocr" => force_full_page_ocr = true,
             "--use-web-browser" => use_web_browser = true,
             // Opt-in enrichment models (docling CLI flag names): picture
             // classification, code rewrite + language, formula LaTeX.
@@ -202,7 +207,7 @@ fn main() -> ExitCode {
     };
 
     let Some(path) = path else {
-        eprintln!("usage: docling-rs [--strict] [--to md|json] [--images MODE] [--fetch-images] [--no-stream] [--no-table-former] [--no-ocr] [--ocr-lang en|ch] [--use-web-browser] <input-file>");
+        eprintln!("usage: docling-rs [--strict] [--to md|json] [--images MODE] [--fetch-images] [--no-stream] [--no-table-former] [--no-ocr] [--force-full-page-ocr] [--ocr-lang en|ch] [--use-web-browser] <input-file>");
         return ExitCode::from(2);
     };
 
@@ -261,6 +266,7 @@ fn main() -> ExitCode {
         .fetch_images(fetch_images)
         .no_table_former(no_table_former)
         .no_ocr(no_ocr)
+        .force_full_page_ocr(force_full_page_ocr)
         .use_web_browser(use_web_browser)
         .do_picture_classification(enrich_picture_classes)
         .do_code_enrichment(enrich_code)

crates/docling-node/src/lib.rs

@@ -44,6 +44,10 @@ pub struct ConverterOptions {
     /// proper Latin word spacing) or `"ch"` (the multilingual
     /// docling-conformance model). Formats that never OCR ignore it.
     pub ocr_lang: Option<String>,
+    /// OCR every PDF page even when it carries an embedded text layer
+    /// (docling's `force_full_page_ocr`) — for text layers that exist but lie.
+    /// Default `false`.
+    pub force_full_page_ocr: Option<bool>,
     /// Emit cleaner, more conformant Markdown (code-fence languages preserved,
     /// no inline-run spacing artifacts) instead of docling's byte-for-byte
     /// legacy output. Markdown only. Default `false`.
@@ -86,6 +90,9 @@ pub struct ConvertOptions {
     pub pages: Option<String>,
     /// OCR recognition language for scanned pages: `"en"` (default) | `"ch"`.
     pub ocr_lang: Option<String>,
+    /// OCR every PDF page even when it carries a text layer (docling's
+    /// `force_full_page_ocr`). Default `false`.
+    pub force_full_page_ocr: Option<bool>,
     pub allowed_formats: Option<Vec<String>>,
     pub to: Option<String>,
     pub image_mode: Option<String>,
@@ -142,6 +149,7 @@ struct ConvertConfig {
     video_frames: Option<usize>,
     page_range: Option<(usize, usize)>,
     ocr_lang: Option<String>,
+    force_full_page_ocr: bool,
     allowed_formats: Option<Vec<InputFormat>>,
     to: OutputKind,
     image_mode: ImageMode,
@@ -201,6 +209,7 @@ fn build_config(o: ConvertOptions) -> Result<ConvertConfig> {
         video_frames: o.video_frames.map(|n| n as usize),
         page_range: parse_pages(o.pages.as_deref())?,
         ocr_lang: parse_ocr_lang(o.ocr_lang)?,
+        force_full_page_ocr: o.force_full_page_ocr.unwrap_or(false),
         allowed_formats: allowed,
         to: parse_output_kind(o.to.as_deref())?,
         image_mode: parse_image_mode(o.image_mode.as_deref())?,
@@ -231,6 +240,7 @@ fn build_converter(cfg: &ConvertConfig) -> RsConverter {
     let base = base
         .strict(cfg.strict)
         .fetch_images(cfg.fetch_images)
+        .force_full_page_ocr(cfg.force_full_page_ocr)
         .asr_model(cfg.asr_model.clone());
     let base = match cfg.video_frames {
         Some(max) => base.video_frames(max),
@@ -416,6 +426,7 @@ pub struct DocumentConverter {
     video_frames: Option<usize>,
     page_range: Option<(usize, usize)>,
     ocr_lang: Option<String>,
+    force_full_page_ocr: bool,
     allowed_formats: Option<Vec<InputFormat>>,
 }
 
@@ -439,6 +450,7 @@ impl DocumentConverter {
             video_frames: o.video_frames.map(|n| n as usize),
             page_range: parse_pages(o.pages.as_deref())?,
             ocr_lang: parse_ocr_lang(o.ocr_lang.clone())?,
+            force_full_page_ocr: o.force_full_page_ocr.unwrap_or(false),
             allowed_formats: allowed,
         })
     }
@@ -452,6 +464,7 @@ impl DocumentConverter {
             video_frames: self.video_frames,
             page_range: self.page_range,
             ocr_lang: self.ocr_lang.clone(),
+            force_full_page_ocr: self.force_full_page_ocr,
             allowed_formats: self.allowed_formats.clone(),
             to: parse_output_kind(out.to.as_deref())?,
             image_mode: parse_image_mode(out.image_mode.as_deref())?,
@@ -865,6 +878,7 @@ fn output_config(out: Option<OutputOptions>, strict: bool) -> Result<ConvertConf
         asr_model: None,
         video_frames: None,
         page_range: None,
+        force_full_page_ocr: false,
         ocr_lang: None,
         allowed_formats: None,
         to: parse_output_kind(out.to.as_deref())?,