Skip to main content

docling_pdf/
ocr.rs

1//! OCR for scanned pages, via the PP-OCRv3 recognition model (CRNN/SVTR) run
2//! with `ort`. The layout model locates the text regions on the page image
3//! (it works without a text layer); inside them the recognizer reads the
4//! lines the PP-OCR text detector found (`ocr_det`, #429/#570 — RapidOCR's
5//! own crops, each one text run with the detector's margin), falling back to
6//! a horizontal-projection split of the region crop where the detector saw
7//! nothing or is not installed; each line is recognised and decoded with CTC
8//! — producing [`TextCell`]s the normal layout assembly then consumes. A line
9//! under RapidOCR's `text_score` confidence is dropped (`ocr_prep::text_score`).
10
11use image::RgbImage;
12use ort::session::Session;
13use ort::value::Tensor;
14
15use crate::layout::Region;
16// The ONNX-free half (line prep, batching, CTC decode) lives in `ocr_prep`
17// so the wasm build shares it verbatim (#79 phase 2).
18use crate::ocr_prep::{
19    batch_input, decode_row_scored, dict_chars, prep_region_lines, prep_region_lines_det,
20    prep_table_words, prep_table_words_det, width_batches, PrepLine, REC_HEIGHT,
21};
22use crate::pdfium_backend::TextCell;
23
24pub struct OcrModel {
25    /// Single-threaded recognition sessions, one per parallel lane (see
26    /// [`Self::load_with`]); lines are dealt across them by batch index.
27    recs: Vec<Session>,
28    /// CTC classes: index 0 = blank, then the dictionary, then space.
29    chars: Vec<String>,
30    /// RapidOCR's line orientation handling (#666). See
31    /// [`crate::Pipeline::ocr_textline_orientation`].
32    orient: bool,
33    /// The text-line orientation classifier, loaded on the first oriented
34    /// page.
35    cls: ClsSlot,
36}
37
38/// [`OcrModel::cls`]: `Missing` records a failed load (warned once per
39/// process), so it is not retried per page.
40enum ClsSlot {
41    Unloaded,
42    Ready(crate::ocr_cls::TextlineCls),
43    Missing,
44}
45
46/// OCR recognition language: which PP-OCRv3 model + dictionary pair runs
47/// when the PP-OCRv6 recognizer is not installed.
48///
49/// With `.models/ocr_rec_v6.onnx` + `.models/ocr_rec_v6_dict.txt` on disk
50/// (#570; `download_dependencies.sh` fetches them) both languages run that
51/// one multilingual model — RapidOCR's `PP-OCRv6_rec_small`, the recognizer
52/// docling runs for English and Chinese alike, and the single largest factor
53/// in the FUNSD word-recall gap once the detector's lines are the crops
54/// (0.70 → 0.77 on 30 forms). Without it, the PP-OCRv3 pairs: the default is
55/// **English** (`.models/ocr_rec_en.onnx` + `.models/en_dict.txt`) — the
56/// multilingual `ch_` v3 model reads Latin scripts with badly degraded word
57/// spacing (glued words on ordinary English scans) — and `Ch` selects the
58/// `ch_` pair (`.models/ocr_rec.onnx` + `.models/ppocr_keys_v1.txt`), what
59/// the PDF conformance baselines were pinned against;
60/// `scripts/conformance/pdf_*.sh` pin it explicitly by path, which wins over
61/// this selector and over the v6 preference.
62#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
63pub enum OcrLang {
64    /// en_PP-OCRv3 — English-only, proper Latin word spacing.
65    #[default]
66    En,
67    /// ch_PP-OCRv3 — multilingual; the docling-conformance model.
68    Ch,
69}
70
71impl OcrLang {
72    /// Parse a user-supplied language id (#388): the engine's own codes
73    /// (`en`, `ch`) and BCP-47 tags naming a language one of the two
74    /// recognizers reads, trimmed and case-insensitive. `None` for anything
75    /// else — callers surface their own error/warning.
76    ///
77    /// docling canonicalizes OCR languages across its engines (docling#4075):
78    /// a bare value is the engine's native code, an `iso:`-prefixed value a
79    /// BCP-47 tag reduced to a language-script pair with the region dropped
80    /// (`zh-CN` and `zh-Hans` are the same recognizer, `en-GB` is `en`), and
81    /// the RapidOCR adapter maps `en` → its `en` model and `zh-Hans` → `ch`.
82    /// With only those two PP-OCRv3 pairs on board there is no ambiguity, so
83    /// the prefix is optional here: `en-US`, `eng`, `zh`, `zh-Hans`, `iso:zh-CN`
84    /// all resolve without a warning. Accepted primary subtags: English as
85    /// `en` / ISO 639-2/3 `eng` / docling's legacy `english`; Chinese as the
86    /// engine code `ch` (and RapidOCR's `chinese_cht`), `zh` / `zho` / `chi` /
87    /// `cmn` / legacy `chinese` / EasyOCR's `ch_sim` / `ch_tra`. Script,
88    /// region and variant subtags (`-Hans`, `-Hant`, `-CN`, `-TW`, `_US`) are
89    /// ignored: a traditional-script request (`zh-Hant`, `zh-TW`) gets the
90    /// multilingual `ch` recognizer too, the closest model shipped — upstream
91    /// would pick RapidOCR's separate `chinese_cht`, which this engine does
92    /// not carry. Genuinely unsupported languages (`de`, `fr`, `ja`, …) parse
93    /// to `None` and keep warning.
94    pub fn parse(s: &str) -> Option<Self> {
95        let token = s.trim().to_ascii_lowercase();
96        let tag = token.strip_prefix("iso:").unwrap_or(&token).trim();
97        let primary = tag.split(['-', '_']).next().unwrap_or_default();
98        match primary {
99            "en" | "eng" | "english" => Some(Self::En),
100            "ch" | "chinese_cht" | "zh" | "zho" | "chi" | "cmn" | "chinese" | "ch_sim"
101            | "ch_tra" => Some(Self::Ch),
102            _ => None,
103        }
104    }
105
106    /// The process-level choice from `DOCLING_RS_OCR_LANG` (empty/unset → the
107    /// English default; unknown values warn and use English). Under a
108    /// `DOCLING_RS_OCR_ENGINE=tesseract` default the variable is Tesseract's
109    /// language list (`rus+eng`, [`crate::tesseract::lang_arg`]), not a
110    /// PP-OCR model choice: a value naming no en/ch model then selects the
111    /// English model silently — it is only used if a request switches the
112    /// engine back to PP-OCR — instead of warning on every request (#889).
113    pub fn from_env() -> Self {
114        let raw = docling_core::env::nonempty("DOCLING_RS_OCR_LANG");
115        Self::from_env_value(raw.as_deref(), OcrEngine::from_env)
116    }
117
118    /// [`Self::from_env`] on the variable's value and the default engine
119    /// (asked only when the value names no model).
120    fn from_env_value(raw: Option<&str>, engine: impl Fn() -> OcrEngine) -> Self {
121        let Some(raw) = raw else {
122            return Self::default();
123        };
124        Self::parse(raw).unwrap_or_else(|| {
125            if engine() == OcrEngine::Tesseract {
126                return Self::default();
127            }
128            eprintln!(
129                "docling-pdf: DOCLING_RS_OCR_LANG={raw:?} names no language the en/ch \
130                 recognizers read ({}); using en",
131                Self::ACCEPTED
132            );
133            Self::default()
134        })
135    }
136
137    /// The accepted spellings, for error messages and docs.
138    pub const ACCEPTED: &'static str =
139        "en | ch, or a BCP-47 tag for English or Chinese such as en-US, eng, zh, zh-Hans, zh-TW";
140}
141
142/// Which document regions feed the OCR — docling 2.116's `OcrMode` (#254,
143/// upstream docling#3710). Upstream restructured its pipeline so OCR runs
144/// *after* layout, on layout regions filtered by the PDF text layer — the
145/// architecture this port has always had — and named the strategies:
146///
147/// - `PdfAwareLayoutRegions` (upstream's **default**): OCR only layout regions
148///   the embedded text layer can't cover. Exactly the standard path here —
149///   scanned pages OCR their regions, digital pages OCR their bare pictures
150///   and every text/furniture/table region no programmatic text touches
151///   (vector-outlined text beside a native text layer, #931).
152/// - `FullPage` / `LayoutRegions`: ignore the PDF text layer and OCR
153///   everything. Both map onto the [`force_full_page_ocr`] machinery (discard
154///   the text layer, OCR every layout region): the upstream distinction —
155///   whole-page vs per-region *detector* input — has no analogue in this
156///   engine, whose PP-OCR recognizer always consumes per-region line crops.
157///
158/// [`force_full_page_ocr`]: crate::Pipeline::force_full_page_ocr
159#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
160pub enum OcrMode {
161    /// Upstream's `default`: currently wired to `PdfAwareLayoutRegions`.
162    #[default]
163    Default,
164    /// OCR the full page, text layer ignored (docling's `full_page`; the
165    /// mode-shaped spelling of `force_full_page_ocr`).
166    FullPage,
167    /// OCR every layout region, text layer ignored (docling's
168    /// `layout_regions`).
169    LayoutRegions,
170    /// OCR layout regions the text layer can't cover (docling's
171    /// `pdf_aware_layout_regions` — the default behavior).
172    PdfAwareLayoutRegions,
173}
174
175impl OcrMode {
176    /// Parse docling's mode ids. `None` for anything else — callers surface
177    /// their own error/warning.
178    pub fn parse(s: &str) -> Option<Self> {
179        match s.trim().to_ascii_lowercase().as_str() {
180            "default" => Some(Self::Default),
181            "full_page" => Some(Self::FullPage),
182            "layout_regions" => Some(Self::LayoutRegions),
183            "pdf_aware_layout_regions" => Some(Self::PdfAwareLayoutRegions),
184            _ => None,
185        }
186    }
187
188    /// The process-level choice from `DOCLING_RS_OCR_MODE` (empty/unset → the
189    /// default; unknown values warn and use the default).
190    pub fn from_env() -> Self {
191        let Some(raw) = docling_core::env::nonempty("DOCLING_RS_OCR_MODE") else {
192            return Self::default();
193        };
194        Self::parse(&raw).unwrap_or_else(|| {
195            eprintln!(
196                "docling-pdf: DOCLING_RS_OCR_MODE={raw:?} is not \
197                 default|full_page|layout_regions|pdf_aware_layout_regions; using default"
198            );
199            Self::default()
200        })
201    }
202
203    /// Whether this mode discards the embedded text layer — the engine truth
204    /// both non-default modes reduce to.
205    pub fn forces_full_page(self) -> bool {
206        matches!(self, Self::FullPage | Self::LayoutRegions)
207    }
208}
209
210/// Which OCR engine recognizes text (#460): the built-in PP-OCRv3 recognizer
211/// (+ the RapidOCR text detector) — the default and the engine every
212/// conformance baseline is pinned against — or the system `tesseract` binary
213/// (see [`crate::tesseract`]), docling's `TesseractCliOcrOptions`
214/// counterpart. Both consume the same layout-region crops and produce the
215/// same cells; everything downstream is engine-agnostic.
216#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
217pub enum OcrEngine {
218    /// PP-OCRv3 recognition via ONNX Runtime (docling's `rapidocr` kind).
219    #[default]
220    PpOcr,
221    /// The `tesseract` CLI (docling's `tesseract` kind).
222    Tesseract,
223}
224
225impl OcrEngine {
226    /// Parse an engine id: `ppocr` (also `pp-ocr`, `rapidocr`, docling's
227    /// kind name) or `tesseract` (also `tesseract_cli`, `tesserocr`),
228    /// trimmed and case-insensitive. `None` for anything else.
229    pub fn parse(s: &str) -> Option<Self> {
230        match s.trim().to_ascii_lowercase().as_str() {
231            "ppocr" | "pp-ocr" | "pp_ocr" | "rapidocr" | "onnx" | "default" => Some(Self::PpOcr),
232            "tesseract" | "tesseract_cli" | "tesseract-cli" | "tesserocr" => Some(Self::Tesseract),
233            _ => None,
234        }
235    }
236
237    /// The process-level choice from `DOCLING_RS_OCR_ENGINE` (empty/unset →
238    /// PP-OCR; unknown values warn and use PP-OCR).
239    pub fn from_env() -> Self {
240        let Some(raw) = docling_core::env::nonempty("DOCLING_RS_OCR_ENGINE") else {
241            return Self::default();
242        };
243        Self::parse(&raw).unwrap_or_else(|| {
244            eprintln!(
245                "docling-pdf: DOCLING_RS_OCR_ENGINE={raw:?} is not ppocr|tesseract; using ppocr"
246            );
247            Self::default()
248        })
249    }
250
251    /// The accepted spellings, for error messages and docs.
252    pub const ACCEPTED: &'static str = "ppocr | tesseract";
253
254    /// Whether `raw` is an `ocr_lang` this engine can act on — what the
255    /// option surfaces validate up front: the en/ch model switch (or a
256    /// BCP-47 tag for either, [`OcrLang::parse`]) under PP-OCR; tessdata
257    /// stems and BCP-47 tags ([`crate::tesseract::lang_arg`]) under
258    /// Tesseract. The `Err` says what is accepted.
259    pub fn validate_lang(self, raw: &str) -> Result<(), String> {
260        match self {
261            Self::PpOcr => OcrLang::parse(raw).map(|_| ()).ok_or_else(|| {
262                format!(
263                    "ocr_lang {raw:?} names no language the OCR models read ({})",
264                    OcrLang::ACCEPTED
265                )
266            }),
267            Self::Tesseract => crate::tesseract::lang_arg(raw).map(|_| ()),
268        }
269    }
270}
271
272/// The process-level OCR render scale from `DOCLING_RS_OCR_SCALE` (#254,
273/// upstream docling#3877's `OcrOptions.scale`): pixels per PDF point fed to
274/// the recognizer. Unset/empty → `None` (OCR reads the pipeline's own page
275/// render, 2.0 px/pt); non-positive or unparsable values warn and are ignored.
276pub fn scale_from_env() -> Option<f32> {
277    positive_scale_env("DOCLING_RS_OCR_SCALE")
278}
279
280/// The process-level picture OCR scale from `DOCLING_RS_PICTURE_OCR_SCALE`
281/// (#666): pixels per picture pixel for the picture-OCR enrichment, before
282/// RapidOCR's 2000 px cap — see [`crate::Pipeline::picture_ocr_scale`].
283/// Unset/empty → `None`; non-positive or unparsable values warn and are
284/// ignored.
285pub fn picture_scale_from_env() -> Option<f32> {
286    positive_scale_env("DOCLING_RS_PICTURE_OCR_SCALE")
287}
288
289fn positive_scale_env(name: &str) -> Option<f32> {
290    let raw = docling_core::env::nonempty(name)?;
291    match raw.parse::<f32>() {
292        Ok(s) if s > 0.0 && s.is_finite() => Some(s),
293        _ => {
294            eprintln!("docling-pdf: {name}={raw:?} is not a positive number; ignored");
295            None
296        }
297    }
298}
299
300/// The process-level default of [`crate::Pipeline::ocr_textline_orientation`]
301/// from `DOCLING_RS_OCR_TEXTLINE_ORIENTATION` (#666; a `docling_core::env`
302/// flag). Off when unset.
303pub fn textline_orientation_from_env() -> bool {
304    docling_core::env::flag("DOCLING_RS_OCR_TEXTLINE_ORIENTATION")
305}
306
307/// Whether the text detector's boxes are the recognizer's line source inside
308/// layout regions (#570; `DOCLING_RS_OCR_LINES`: `det` default, `projection`
309/// = the ink-projection strips alone, the pre-#570 behavior). Cached.
310pub fn det_lines() -> bool {
311    static MODE: std::sync::OnceLock<bool> = std::sync::OnceLock::new();
312    *MODE.get_or_init(|| {
313        let raw = docling_core::env::nonempty("DOCLING_RS_OCR_LINES").unwrap_or_default();
314        match raw.trim().to_ascii_lowercase().as_str() {
315            "" | "det" | "detector" | "auto" => true,
316            "projection" | "proj" | "off" => false,
317            _ => {
318                eprintln!(
319                    "docling-pdf: DOCLING_RS_OCR_LINES={raw:?} is not det|projection; using det"
320                );
321                true
322            }
323        }
324    })
325}
326
327/// Resolve the recognition model + dictionary pair for `lang`. An English
328/// default that isn't on disk (older model checkouts) degrades to the `ch_`
329/// pair with a warning rather than failing — the usual missing-optional-asset
330/// convention. Explicit `DOCLING_OCR_REC_ONNX` / `DOCLING_OCR_DICT` paths win
331/// over all of this; they are a pair, so set both together.
332pub(crate) fn resolve_rec_pair(lang: OcrLang) -> (String, String) {
333    const CH: (&str, &str) = (".models/ocr_rec.onnx", ".models/ppocr_keys_v1.txt");
334    const EN: (&str, &str) = (".models/ocr_rec_en.onnx", ".models/en_dict.txt");
335    const V6: (&str, &str) = (".models/ocr_rec_v6.onnx", ".models/ocr_rec_v6_dict.txt");
336    let exists = |p: &str| std::path::Path::new(p).exists();
337    // The multilingual PP-OCRv6 recognizer, when installed, serves both
338    // languages (see `OcrLang`); explicit paths below still win.
339    let (v6_rec, v6_dict) = (crate::resolve_asset(V6.0), crate::resolve_asset(V6.1));
340    let (mut rec, mut dict) = if exists(&v6_rec) && exists(&v6_dict) {
341        (v6_rec, v6_dict)
342    } else {
343        let pick = if lang == OcrLang::Ch { CH } else { EN };
344        (crate::resolve_asset(pick.0), crate::resolve_asset(pick.1))
345    };
346    let want_ch = lang == OcrLang::Ch;
347    if !want_ch && (!exists(&rec) || !exists(&dict)) {
348        let (ch_rec, ch_dict) = (crate::resolve_asset(CH.0), crate::resolve_asset(CH.1));
349        if std::path::Path::new(&ch_rec).exists() && std::path::Path::new(&ch_dict).exists() {
350            eprintln!(
351                "docling-pdf: English OCR model not found ({rec}); falling back to the \
352                 multilingual ch_ model — expect weak Latin word spacing. Fetch it with \
353                 scripts/install/download_dependencies.sh"
354            );
355            (rec, dict) = (ch_rec, ch_dict);
356        }
357    }
358    (
359        docling_core::env::nonempty("DOCLING_OCR_REC_ONNX").unwrap_or(rec),
360        docling_core::env::nonempty("DOCLING_OCR_DICT").unwrap_or(dict),
361    )
362}
363
364/// One recognised line: its text and mean emitted-character confidence.
365type Recognized = (String, f32);
366
367impl OcrModel {
368    /// Load the recognition model and its character dictionary for `lang` —
369    /// see [`resolve_rec_pair`] for the selection rules (explicit
370    /// `DOCLING_OCR_REC_ONNX`/`DOCLING_OCR_DICT` paths win) — with `lanes`
371    /// recognition sessions.
372    ///
373    /// Each session is pinned to one intra-op thread: ORT's multi-threaded
374    /// float-reduction order varies across runs, which flips the CTC argmax on
375    /// low-confidence characters (e.g. noisy faxes) and makes the snapshot
376    /// output non-deterministic. Recognition is linear in line width (~0.17 ms
377    /// per pixel column on one core) and on a scanned page it, plus the
378    /// orientation probe that reads the six widest lines, is ~35% of the wall
379    /// time while the other cores idle. Lines are independent, so `lanes`
380    /// sessions recognise disjoint same-width batches concurrently — each
381    /// line still sees exactly the single-thread kernel path, results are
382    /// placed by index, and the output is byte-identical to one lane.
383    /// `DOCLING_RS_OCR_SESSIONS` overrides the caller's lane count; under a
384    /// CUDA-class provider the default is one lane (#842) — the lanes exist
385    /// to use idle CPU cores, and on one GPU each is another session's arena.
386    pub fn load_with(lang: OcrLang, lanes: usize) -> Result<Self, String> {
387        let (rec_path, dict_path) = resolve_rec_pair(lang);
388        let lanes = docling_core::env::parse::<usize>("DOCLING_RS_OCR_SESSIONS")
389            .filter(|&n| n > 0)
390            .unwrap_or(if docling_onnx::prefers_single_worker() {
391                1
392            } else {
393                lanes
394            })
395            .clamp(1, 8);
396        let open = || -> Result<Session, String> {
397            let builder = docling_onnx::session_builder()
398                .map_err(|e| format!("ocr: builder: {e}"))?
399                .with_intra_threads(1)
400                .map_err(|e| format!("ocr: intra_threads: {e}"))?;
401            let builder = docling_onnx::apply(builder).map_err(|e| format!("ocr: {e}"))?;
402            docling_onnx::commit(builder, &rec_path, "rec")
403                .map_err(|e| format!("ocr: load {rec_path}: {e}"))
404        };
405        // The lanes are independent sessions over the same file — open them
406        // concurrently so extra lanes cost no extra start-up latency.
407        let recs: Vec<Session> = std::thread::scope(|s| {
408            let handles: Vec<_> = (0..lanes).map(|_| s.spawn(open)).collect();
409            handles
410                .into_iter()
411                .map(|h| {
412                    h.join()
413                        .map_err(|_| "ocr: session thread panicked".to_string())?
414                })
415                .collect::<Result<Vec<_>, String>>()
416        })?;
417        let dict = std::fs::read_to_string(&dict_path)
418            .map_err(|e| format!("ocr: read dict {dict_path}: {e}"))?;
419        Ok(Self {
420            recs,
421            chars: dict_chars(&dict),
422            orient: false,
423            cls: ClsSlot::Unloaded,
424        })
425    }
426
427    /// Turn RapidOCR's line orientation handling on or off (#666): oriented
428    /// crops, the 90° turn, and the 0/180 classifier on detector lines.
429    pub fn set_textline_orientation(&mut self, enable: bool) {
430        self.orient = enable;
431    }
432
433    /// The orientation classifier, loading it on first use; `None` (warned
434    /// once) when the model is not installed or fails to load.
435    fn cls(&mut self) -> Option<&mut crate::ocr_cls::TextlineCls> {
436        if matches!(self.cls, ClsSlot::Unloaded) {
437            self.cls = match crate::ocr_cls::TextlineCls::load() {
438                Ok(m) => ClsSlot::Ready(m),
439                Err(e) => {
440                    static WARNED: std::sync::Once = std::sync::Once::new();
441                    WARNED.call_once(|| {
442                        eprintln!(
443                            "warning: {e}; text lines are cropped and turned upright but not \
444                             checked for 180° (run scripts/install/download_dependencies.sh)"
445                        );
446                    });
447                    ClsSlot::Missing
448                }
449            };
450        }
451        match &mut self.cls {
452            ClsSlot::Ready(m) => Some(m),
453            _ => None,
454        }
455    }
456
457    /// The oriented line prep (#666): RapidOCR's crops, the upside-down ones
458    /// turned 180° by the classifier when it is installed, then prepared
459    /// for recognition like any other line.
460    fn oriented_lines(
461        &mut self,
462        img: &RgbImage,
463        regions: &[Region],
464        scale: f32,
465        detected: &[crate::ocr_det::DetBox],
466    ) -> Result<(Vec<crate::ocr_prep::LineBox>, Vec<PrepLine>), String> {
467        use crate::ocr_prep::LineSrc;
468        let (bboxes, mut srcs) =
469            crate::ocr_prep::region_line_crops_det(img, regions, scale, detected);
470        let crop_idx: Vec<usize> = (0..srcs.len())
471            .filter(|&i| matches!(srcs[i], LineSrc::Crop(_)))
472            .collect();
473        if !crop_idx.is_empty() {
474            if let Some(cls) = self.cls() {
475                let crops: Vec<&RgbImage> = crop_idx
476                    .iter()
477                    .map(|&i| match &srcs[i] {
478                        LineSrc::Crop(c) => c,
479                        LineSrc::Prepared(_) => unreachable!("filtered to crops"),
480                    })
481                    .collect();
482                let flip = crate::timing::timed("ocr.cls", || cls.upside_down(&crops))?;
483                for (&i, flip) in crop_idx.iter().zip(flip) {
484                    if let (true, LineSrc::Crop(c)) = (flip, &mut srcs[i]) {
485                        image::imageops::rotate180_in_place(c);
486                    }
487                }
488            }
489        }
490        let mut boxes = Vec::with_capacity(bboxes.len());
491        let mut lines = Vec::with_capacity(bboxes.len());
492        for (bb, src) in bboxes.into_iter().zip(srcs) {
493            let line = match src {
494                LineSrc::Crop(c) => crate::ocr_prep::prep_line(&c),
495                LineSrc::Prepared(p) => Some(p),
496            };
497            if let Some(line) = line {
498                boxes.push(bb);
499                lines.push(line);
500            }
501        }
502        Ok((boxes, lines))
503    }
504
505    /// Recognise every width batch of `lines`, dealt round-robin across the
506    /// lanes, and return `(line index, (text, confidence))` in batch order —
507    /// the same order the sequential loop produced, whatever the scheduling.
508    fn recognize_all(&mut self, lines: &[PrepLine]) -> Result<Vec<(usize, Recognized)>, String> {
509        let batches = width_batches(lines);
510        let lanes = self.recs.len().min(batches.len()).max(1);
511        let chars = &self.chars;
512        // One result slot per batch keeps the merge order independent of
513        // which lane finished first.
514        let mut per_batch: Vec<Option<Result<Vec<Recognized>, String>>> =
515            (0..batches.len()).map(|_| None).collect();
516        if lanes <= 1 {
517            for (slot, (w, chunk)) in per_batch.iter_mut().zip(&batches) {
518                *slot = Some(recognize_batch(&mut self.recs[0], chars, *w, chunk, lines));
519            }
520        } else {
521            std::thread::scope(|s| {
522                let handles: Vec<_> = self
523                    .recs
524                    .iter_mut()
525                    .take(lanes)
526                    .enumerate()
527                    .map(|(lane, rec)| {
528                        let batches = &batches;
529                        s.spawn(move || {
530                            batches
531                                .iter()
532                                .enumerate()
533                                .filter(|(k, _)| k % lanes == lane)
534                                .map(|(k, (w, chunk))| {
535                                    (k, recognize_batch(rec, chars, *w, chunk, lines))
536                                })
537                                .collect::<Vec<_>>()
538                        })
539                    })
540                    .collect();
541                for h in handles {
542                    for (k, r) in h.join().expect("ocr lane panicked") {
543                        per_batch[k] = Some(r);
544                    }
545                }
546            });
547        }
548        let mut out = Vec::with_capacity(lines.len());
549        for ((_, chunk), slot) in batches.iter().zip(per_batch) {
550            let texts = slot.expect("every batch is assigned a lane")?;
551            out.extend(chunk.iter().copied().zip(texts));
552        }
553        Ok(out)
554    }
555
556    /// Recognise a batch of prepared *same-width* lines in one session run.
557    ///
558    /// Only equal widths ever share a run: same-width batching is
559    /// bit-identical to one-at-a-time recognition (each sample keeps its own
560    /// data and per-sample kernel reduction order — verified empirically on
561    /// the scanned corpus), whereas width-padding leaks into the real
562    /// timesteps through the model's global-attention blocks and measurably
563    /// changes low-confidence characters.
564    /// Recognize `lines` and reduce to orientation-probe evidence: the
565    /// confidence-weighted character count `Σ(conf × chars)` plus the raw
566    /// character total (#225). Same deterministic width-batching as page OCR.
567    pub(crate) fn score_lines(&mut self, lines: &[PrepLine]) -> Result<(f32, usize), String> {
568        // Same accumulation order as the sequential loop (batch order), so
569        // the f32 sum is bit-identical regardless of lane scheduling.
570        let mut weighted = 0.0f32;
571        let mut chars = 0usize;
572        for (_, (text, conf)) in self.recognize_all(lines)? {
573            let n = text.trim().chars().count();
574            weighted += conf * n as f32;
575            chars += n;
576        }
577        Ok((weighted, chars))
578    }
579
580    /// OCR a page: produce text cells (page points) for every line found inside
581    /// the text regions, each paired with its recognition confidence (mean
582    /// emitted-character probability — feeds the page `ocr_score`, #183).
583    /// `scale` is image-px per page-point. `detected` — the text detector's
584    /// boxes, in image pixels of `img` — makes them the line source inside
585    /// the regions (#570, see [`prep_region_lines_det`]); `None` keeps the
586    /// projection segmentation.
587    pub fn ocr_page_with(
588        &mut self,
589        img: &RgbImage,
590        regions: &[Region],
591        scale: f32,
592        detected: Option<&[crate::ocr_det::DetBox]>,
593    ) -> Result<Vec<(TextCell, f32)>, String> {
594        // Gather every line crop on the page first (shared with the browser
595        // path), so equal-width lines can share a recognition run regardless
596        // of which region they came from.
597        let (bboxes, lines) = match detected {
598            Some(det) if self.orient => self.oriented_lines(img, regions, scale, det)?,
599            _ => crate::timing::timed("ocr.prep", || match detected {
600                Some(det) => prep_region_lines_det(img, regions, scale, det),
601                None => prep_region_lines(img, regions, scale),
602            }),
603        };
604
605        // Deterministic width-batching (shared with the wasm path), dealt
606        // across the recognition lanes.
607        let mut texts = vec![(String::new(), 0.0f32); lines.len()];
608        crate::timing::timed("ocr.rec", || -> Result<(), String> {
609            for (i, text) in self.recognize_all(&lines)? {
610                texts[i] = text;
611            }
612            Ok(())
613        })?;
614
615        // Emit cells in page order, exactly as the sequential walk did.
616        Ok(collect_cells(bboxes, texts))
617    }
618
619    /// Recognize the *word* crops inside the page's table regions (mirroring
620    /// the browser scanned path): [`ocr_page`](Self::ocr_page) deliberately
621    /// skips table labels, so a scanned table would otherwise reach the cell
622    /// matcher with no words at all and dissolve (#173). Returns word-level
623    /// [`TextCell`]s in page points.
624    pub fn ocr_table_words(
625        &mut self,
626        img: &RgbImage,
627        regions: &[Region],
628        scale: f32,
629        detected: Option<&[crate::ocr_det::DetBox]>,
630    ) -> Result<Vec<(TextCell, f32)>, String> {
631        let (bboxes, lines) = match detected {
632            Some(det) => prep_table_words_det(img, regions, scale, det),
633            None => prep_table_words(img, regions, scale),
634        };
635        let mut texts = vec![(String::new(), 0.0f32); lines.len()];
636        for (i, text) in self.recognize_all(&lines)? {
637            texts[i] = text;
638        }
639        Ok(collect_cells(bboxes, texts))
640    }
641}
642
643/// Pair recognized texts with their line boxes into page-point cells, in page
644/// order, dropping empty lines and those under [`text_score`].
645fn collect_cells(
646    bboxes: Vec<crate::ocr_prep::LineBox>,
647    texts: Vec<Recognized>,
648) -> Vec<(TextCell, f32)> {
649    let min_conf = crate::ocr_prep::text_score();
650    let mut cells = Vec::new();
651    for ((l, t, r, b), (text, conf)) in bboxes.into_iter().zip(texts) {
652        let text = text.trim().to_string();
653        if text.is_empty() || conf < min_conf {
654            continue;
655        }
656        cells.push((TextCell { text, l, t, r, b }, conf));
657    }
658    cells
659}
660
661/// Recognise a batch of prepared *same-width* lines in one run of `rec`.
662///
663/// Only equal widths ever share a run: same-width batching is bit-identical
664/// to one-at-a-time recognition (each sample keeps its own data and per-sample
665/// kernel reduction order — verified empirically on the scanned corpus),
666/// whereas width-padding leaks into the real timesteps through the model's
667/// global-attention blocks and measurably changes low-confidence characters.
668fn recognize_batch(
669    rec: &mut Session,
670    chars: &[String],
671    w: usize,
672    chunk: &[usize],
673    lines: &[PrepLine],
674) -> Result<Vec<(String, f32)>, String> {
675    let n = chunk.len();
676    let data = batch_input(w, chunk, lines);
677    let input = Tensor::from_array(([n, 3, REC_HEIGHT as usize, w], data))
678        .map_err(|e| format!("ocr: input tensor: {e}"))?;
679    let outputs = docling_onnx::run(rec, ort::inputs!["x" => input])
680        .map_err(|e| format!("ocr: rec inference: {e}"))?;
681    let (shape, probs) = outputs[0]
682        .try_extract_tensor::<f32>()
683        .map_err(|e| format!("ocr: extract rec: {e}"))?;
684    let t_len = shape[1] as usize;
685    let nc = shape[2] as usize;
686    Ok((0..n)
687        .map(|i| decode_row_scored(chars, &probs[i * t_len * nc..(i + 1) * t_len * nc], nc))
688        .collect())
689}
690
691#[cfg(test)]
692mod tests {
693    use super::*;
694
695    /// #889: under a Tesseract default, `DOCLING_RS_OCR_LANG` is Tesseract's
696    /// language list — a value naming no en/ch model picks English without
697    /// the PP-OCR warning; under PP-OCR an en/ch value still selects it.
698    #[test]
699    fn env_lang_under_a_tesseract_default_is_not_a_model_choice() {
700        let tess = || OcrEngine::Tesseract;
701        let pp = || OcrEngine::PpOcr;
702        assert_eq!(OcrLang::from_env_value(Some("rus+eng"), tess), OcrLang::En);
703        assert_eq!(OcrLang::from_env_value(Some("rus+eng"), pp), OcrLang::En);
704        assert_eq!(OcrLang::from_env_value(Some("zh-Hans"), tess), OcrLang::Ch);
705        assert_eq!(OcrLang::from_env_value(None, pp), OcrLang::En);
706    }
707
708    /// #388: BCP-47 tags and the ISO 639-2/3 codes for English and Chinese
709    /// resolve to the two recognizers, with or without docling's `iso:`
710    /// prefix and whatever the script/region subtags; other languages and
711    /// nonsense stay `None`.
712    #[test]
713    fn ocr_lang_accepts_bcp47_tags_for_the_two_recognizers() {
714        for id in [
715            "en",
716            "EN",
717            " en ",
718            "en-US",
719            "en_GB",
720            "eng",
721            "english",
722            "iso:en",
723            "ISO:en-GB",
724            "en-Latn-US",
725        ] {
726            assert_eq!(OcrLang::parse(id), Some(OcrLang::En), "{id:?}");
727        }
728        for id in [
729            "ch",
730            "zh",
731            "zho",
732            "chi",
733            "cmn",
734            "chinese",
735            "ch_sim",
736            "ch_tra",
737            "chinese_cht",
738            "zh-Hans",
739            "zh-Hant",
740            "zh-CN",
741            "zh-TW",
742            "zh-Hant-HK",
743            "zh_SG",
744            "iso:zh-Hans",
745        ] {
746            assert_eq!(OcrLang::parse(id), Some(OcrLang::Ch), "{id:?}");
747        }
748        for id in [
749            "", "de", "fr-FR", "ja", "deu", "cn", "latin", "iso:", "iso:und", "e",
750        ] {
751            assert_eq!(OcrLang::parse(id), None, "{id:?}");
752        }
753    }
754
755    /// #254: docling's four `OcrMode` ids parse; `full_page`/`layout_regions`
756    /// reduce to the force-full-page machinery, the default/pdf-aware pair to
757    /// the standard text-layer-aware path. Unknown ids parse to nothing.
758    #[test]
759    fn ocr_mode_ids_parse_and_map_to_forcing() {
760        for (id, mode, forces) in [
761            ("default", OcrMode::Default, false),
762            ("full_page", OcrMode::FullPage, true),
763            ("layout_regions", OcrMode::LayoutRegions, true),
764            (
765                "pdf_aware_layout_regions",
766                OcrMode::PdfAwareLayoutRegions,
767                false,
768            ),
769        ] {
770            assert_eq!(OcrMode::parse(id), Some(mode));
771            assert_eq!(mode.forces_full_page(), forces, "{id}");
772        }
773        assert_eq!(OcrMode::parse(" Full_Page "), Some(OcrMode::FullPage));
774        assert_eq!(OcrMode::parse("easyocr"), None);
775        assert_eq!(OcrMode::parse(""), None);
776    }
777
778    /// #460: the engine ids, and engine-aware `ocr_lang` validation — `deu`
779    /// is a Tesseract stem, not a PP-OCR model; `en` works under both.
780    #[test]
781    fn ocr_engine_ids_and_lang_validation() {
782        for id in ["ppocr", "PP-OCR", " rapidocr ", "default"] {
783            assert_eq!(OcrEngine::parse(id), Some(OcrEngine::PpOcr), "{id:?}");
784        }
785        for id in ["tesseract", "Tesseract_CLI", "tesserocr"] {
786            assert_eq!(OcrEngine::parse(id), Some(OcrEngine::Tesseract), "{id:?}");
787        }
788        assert_eq!(OcrEngine::parse("easyocr"), None);
789        assert!(OcrEngine::PpOcr.validate_lang("en").is_ok());
790        assert!(OcrEngine::PpOcr.validate_lang("deu").is_err());
791        assert!(OcrEngine::Tesseract.validate_lang("en").is_ok());
792        assert!(OcrEngine::Tesseract.validate_lang("deu+fra").is_ok());
793        assert!(OcrEngine::Tesseract.validate_lang("xx").is_err());
794    }
795}