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}