docling_pdf/lib.rs
1//! PDF backend for docling.rs.
2//!
3//! A port of docling's standard PDF pipeline: pdfium extracts the text layer
4//! (cells with bounding boxes) and renders page images; a discriminative ONNX
5//! stack (layout detection, table structure, OCR) classifies regions; the cells
6//! are assembled in reading order into a [`DoclingDocument`].
7//!
8//! Current stages: pdfium text-cell extraction + page rendering ([`pdfium_backend`])
9//! and the deterministic text/reading-order assembly ([`assemble`]). The layout,
10//! table-structure and OCR ONNX stages land behind [`Pipeline`] next.
11
12// Without `ml` only the text-layer path runs; the shared assembly/label
13// helpers it doesn't exercise stay compiled for API stability (the full
14// build still flags genuinely dead code).
15#![cfg_attr(not(feature = "ml"), allow(dead_code))]
16
17mod adobe_glyph_list;
18// Reading-order assembly. Public under `ocr-prep` so the browser pipeline can
19// reuse the geometric table reconstruction and its reliability gate (#157).
20#[cfg(feature = "ocr-prep")]
21pub mod assemble;
22#[cfg(not(feature = "ocr-prep"))]
23mod assemble;
24// Vector checkbox squares from the text parser's path walk (#609).
25pub mod checkbox;
26mod dp_lines;
27#[cfg(feature = "ml")]
28pub mod enrich;
29// Public so sibling crates (e.g. docling-rag's ONNX embedder) can route their
30// own `ort` sessions through the same `DOCLING_RS_EP` selection. Kept as a
31// re-export after the logic moved to the shared `docling-onnx` crate —
32// `docling_pdf::ep::…` remains the stable path downstream crates code against.
33#[cfg(feature = "ml")]
34pub use docling_onnx as ep;
35// Heading-hierarchy stage (#302): PDF font-name style parsing, outline
36// extraction (pure lopdf), and the level-assignment pass. No feature gate on
37// the logic itself — only the glyph style pass needs pdfium (`ml`).
38#[cfg(feature = "render")]
39pub mod dparse_render;
40mod font_style;
41mod heading_hierarchy;
42pub mod layout;
43#[cfg(feature = "ml")]
44mod mets;
45#[cfg(feature = "ner")]
46pub mod ner;
47#[cfg(feature = "ml")]
48mod ocr;
49#[cfg(feature = "ml")]
50mod ocr_cls;
51#[cfg(any(feature = "ml", feature = "ocr-prep"))]
52pub mod ocr_det;
53#[cfg(feature = "ocr-prep")]
54pub mod ocr_prep;
55#[cfg(feature = "ml")]
56mod orient;
57pub mod outline;
58pub mod pdfium_backend;
59#[cfg(feature = "ml")]
60pub mod picture;
61#[cfg(feature = "ml")]
62pub mod quality;
63mod reading_order;
64#[cfg(feature = "ml")]
65mod redact_ocr;
66// Pure-Rust region resampling (page→1024px box-average, crop→448 bilinear) —
67// available to the browser TableFormer path (#157 stage 3), not just `ml`.
68#[cfg(feature = "ocr-prep")]
69pub mod resample;
70#[cfg(feature = "ocr-prep")]
71pub mod scanned;
72// Built-in standard-14 font metrics for the pure-Rust text parser (#187) —
73// no feature gate: the wasm/pdf-text path needs them like the native one.
74pub mod info;
75pub mod pdf_meta;
76// What the reader repaired to read a file (#934) — typed provenance, on
77// demand; pure Rust like `pdf_meta`.
78pub mod repairs;
79pub use repairs::{pdf_repairs, try_pdf_repairs, PdfRepair, RepairInspectError};
80// Embedded images as picture images (#1007, `use_embedded_picture_images`).
81#[cfg(feature = "render")]
82pub mod embedded;
83mod glyph_names;
84#[cfg(feature = "render")]
85pub mod raster;
86#[cfg(feature = "render")]
87pub mod render;
88mod script_position;
89mod std14;
90mod symbol_fonts;
91#[cfg(feature = "ml")]
92mod table_tokens;
93#[cfg(feature = "ml")]
94pub mod tableformer;
95#[cfg(feature = "ml")]
96mod tesseract;
97pub mod textparse;
98#[cfg(feature = "ocr-prep")]
99pub mod tf_core;
100// docling's TableFormer cell matcher — pure Rust, shared with the browser
101// TableFormer path (#157 stage 3).
102#[cfg(feature = "ocr-prep")]
103pub mod tf_match;
104pub mod timing;
105mod tounicode;
106
107#[cfg(feature = "ml")]
108use std::collections::BTreeMap;
109use std::fmt;
110#[cfg(feature = "ml")]
111use std::sync::mpsc::{sync_channel, Receiver};
112#[cfg(feature = "ml")]
113use std::sync::{Arc, Mutex};
114
115// An execution provider only exists on its OS, and ort's prebuilt ONNX
116// Runtime binaries follow suit — requesting an impossible pairing otherwise
117// surfaces as a cryptic ort-sys linker error ("no builds available that
118// satisfy the requested feature set"). Catch it at type-check time with an
119// actionable message instead.
120#[cfg(all(feature = "coreml", not(target_vendor = "apple")))]
121compile_error!(
122 "the `coreml` execution provider exists only on Apple targets (macOS/iOS). \
123 On Linux use `--features cuda` or `--features tensorrt` (NVIDIA), on \
124 Windows also `--features directml`, or build without EP features for CPU."
125);
126#[cfg(all(feature = "directml", not(target_os = "windows")))]
127compile_error!(
128 "the `directml` execution provider exists only on Windows. On Linux use \
129 `--features cuda` or `--features tensorrt` (NVIDIA), on macOS \
130 `--features coreml`, or build without EP features for CPU."
131);
132#[cfg(all(any(feature = "cuda", feature = "tensorrt"), target_vendor = "apple"))]
133compile_error!(
134 "the `cuda`/`tensorrt` execution providers have no Apple builds (no NVIDIA \
135 support on macOS). Use `--features coreml` there, or build without EP \
136 features for CPU."
137);
138
139use docling_core::DoclingDocument;
140pub use docling_core::EncryptionError;
141// The env-knob helpers only gate ML-pipeline diagnostics and tuning; the
142// pure text-layer (wasm) build has no call sites.
143#[cfg(feature = "ml")]
144use docling_core::Node;
145#[cfg(feature = "ml")]
146use docling_core::{debug_log, env};
147
148pub use dp_lines::WordGap;
149pub use heading_hierarchy::HeadingHierarchyOptions;
150#[cfg(feature = "ml")]
151pub use mets::{convert_mets_gbs, convert_mets_gbs_with_options, convert_mets_gbs_with_pipeline};
152#[cfg(feature = "ml")]
153pub use ocr::{OcrEngine, OcrLang, OcrMode, OcrModel, RecognizedLine};
154#[cfg(feature = "render")]
155pub use pdfium_backend::PdfDocument;
156pub use pdfium_backend::TextOptions;
157pub use pdfium_backend::{PdfPage, TextCell};
158#[cfg(feature = "ml")]
159pub use tesseract::{
160 installed_languages as tesseract_languages, lang_arg as tesseract_lang_arg, TesseractOptions,
161};
162// Plain page rasterization (#243) — pdfium only, no models.
163#[cfg(feature = "render")]
164pub use pdfium_backend::{render_pages, RenderedPage};
165#[cfg(feature = "ml")]
166pub use render::Omission;
167
168/// Errors from the PDF backend. Detailed and surfaced (never silently skipped).
169#[derive(Debug)]
170pub enum PdfError {
171 /// pdfium failed to bind, open, or read the document (and, historically,
172 /// any pipeline error outside the models).
173 Pdfium(String),
174 /// The document itself: an object model lopdf cannot read, a page no
175 /// renderer can draw, a page range outside it.
176 Document(String),
177 /// The layout ONNX model failed to load or run.
178 Layout(String),
179 /// The OCR ONNX model failed to load or run.
180 Ocr(String),
181 /// The document budget ([`Pipeline::document_timeout`]) ran out between
182 /// two pages. Internally the sentinel that stops the page walk; a caller
183 /// never sees it from [`Pipeline::convert`] — the conversion returns the
184 /// pages it finished and reports the cut through [`Completion`].
185 Timeout(String),
186 /// The document is encrypted and the password given (or none) does not
187 /// open it (#636) — the typed value a caller prompts for a password on,
188 /// reachable through [`std::error::Error::source`] too. Its text is the
189 /// one docling raises.
190 Encrypted(EncryptionError),
191}
192
193impl fmt::Display for PdfError {
194 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
195 match self {
196 PdfError::Pdfium(m) => write!(f, "pdf: pdfium error: {m}"),
197 PdfError::Document(m) => write!(f, "pdf: {m}"),
198 PdfError::Layout(m) => write!(f, "pdf: {m}"),
199 PdfError::Ocr(m) => write!(f, "pdf: {m}"),
200 PdfError::Timeout(m) => write!(f, "pdf: {m}"),
201 PdfError::Encrypted(EncryptionError::WrongPassword) => {
202 f.write_str("pdf: the PDF is encrypted and the password is wrong")
203 }
204 PdfError::Encrypted(EncryptionError::NeedPassword) => {
205 f.write_str("pdf: the PDF is encrypted: a password is required")
206 }
207 PdfError::Encrypted(e) => write!(f, "pdf: the PDF is encrypted: {e}"),
208 }
209 }
210}
211
212/// How a conversion ended: every selected page, or the pages that fit the
213/// document budget (docling's `document_timeout`, `PARTIAL_SUCCESS`).
214#[derive(Debug, Clone, Copy, PartialEq, Eq)]
215pub enum Completion {
216 /// Every selected page was processed.
217 Complete,
218 /// The budget ran out: `pages_done` of `pages_selected` pages are in the
219 /// document, the rest were never rendered (or never processed).
220 TimedOut {
221 pages_done: usize,
222 pages_selected: usize,
223 budget: std::time::Duration,
224 },
225}
226
227/// One finished page, as the per-page progress hook
228/// ([`Pipeline::set_progress`]) reports it — docling's `PageCompletedProgress`
229/// minus the document fields the caller adds (#783).
230#[derive(Debug, Clone, Copy, PartialEq, Eq)]
231pub struct PageProgress {
232 /// The page's 1-based number in the document: a page window keeps the
233 /// source numbering, so a `2-3` window reports pages 2 and 3.
234 pub page_no: usize,
235 /// Pages finished so far in this conversion, this one included. On the
236 /// parallel walks pages finish out of order, so this — not `page_no` —
237 /// drives a progress bar.
238 pub pages_done: usize,
239 /// Pages the conversion selected: the window's size, else the whole
240 /// document.
241 pub pages_selected: usize,
242}
243
244/// The per-page progress hook: shared with the parallel workers, so it must
245/// be cheap and thread-safe.
246pub type PageProgressHook = std::sync::Arc<dyn Fn(PageProgress) + Send + Sync>;
247
248impl Completion {
249 pub fn timed_out(&self) -> bool {
250 matches!(self, Completion::TimedOut { .. })
251 }
252
253 /// docling's `ErrorItem.error_message` for the cut, `None` when complete.
254 pub fn message(&self) -> Option<String> {
255 match self {
256 Completion::Complete => None,
257 Completion::TimedOut {
258 pages_done,
259 pages_selected,
260 budget,
261 } => Some(format!(
262 "document timeout of {:.3}s exceeded after {pages_done} of {pages_selected} \
263 pages; the output holds the pages processed",
264 budget.as_secs_f64()
265 )),
266 }
267 }
268}
269
270/// A converted document and how its conversion ended ([`Completion`]).
271#[derive(Debug, Clone)]
272pub struct Converted {
273 pub document: DoclingDocument,
274 pub completion: Completion,
275}
276
277/// Has the document budget run out?
278fn expired(deadline: Option<std::time::Instant>) -> bool {
279 deadline.is_some_and(|d| std::time::Instant::now() >= d)
280}
281
282/// The sentinel the page walks stop on once the budget is gone.
283fn timeout_sentinel() -> PdfError {
284 PdfError::Timeout("document timeout exceeded".into())
285}
286
287impl std::error::Error for PdfError {
288 fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
289 match self {
290 PdfError::Encrypted(e) => Some(e),
291 _ => None,
292 }
293 }
294}
295
296#[cfg(feature = "pdfium")]
297impl From<pdfium_render::prelude::PdfiumError> for PdfError {
298 fn from(e: pdfium_render::prelude::PdfiumError) -> Self {
299 // A failed dlopen means the library this build was asked to use
300 // (`pdfium` feature) is not there. Say what to do instead of leaking
301 // the raw loader error.
302 if matches!(e, pdfium_render::prelude::PdfiumError::LoadLibraryError(_)) {
303 // The loader error pretty-prints over several lines; compact it.
304 let detail = e
305 .to_string()
306 .split_whitespace()
307 .collect::<Vec<_>>()
308 .join(" ");
309 return PdfError::Pdfium(format!(
310 "the pdfium library is not installed. This build's `pdfium` feature \
311 was asked for it (DOCLING_RS_RENDERER=pdfium, or a file the pure-Rust \
312 object model cannot read): point PDFIUM_DYNAMIC_LIB_PATH at a directory \
313 containing the pdfium library, or unset DOCLING_RS_RENDERER — the \
314 default renderer needs no library. Declarative formats (DOCX, HTML, \
315 Markdown, …) never need it. [{detail}]"
316 ));
317 }
318 PdfError::Pdfium(e.to_string())
319 }
320}
321
322/// Convert a PDF's **embedded text layer only** — no ONNX, no
323/// threads: the pure-Rust content-stream parser ([`textparse`]) feeds the same
324/// orphan-region assembly the `no_ocr` pipeline flag uses, so text-layer PDFs
325/// come out identical to `--text-layer-only` (flat, line-grouped paragraphs in reading
326/// order; no headings/lists/tables/pictures, and no hyperlink recovery).
327///
328/// This is the only conversion entry compiled without the `ml` feature (it is
329/// what a wasm32 build runs). A scanned/image-only PDF (no embedded text
330/// layer) yields an empty document rather than an error, same as `no_ocr` —
331/// callers can detect that and fall back to an OCR-capable build.
332pub fn convert_text_layer(bytes: &[u8], name: &str) -> Result<DoclingDocument, PdfError> {
333 convert_text_layer_pages(bytes, name, None)
334}
335
336/// The error for bytes no reader here can parse as a PDF — not a PDF at
337/// all, or one damaged past the parser's repairs. Said about the file, not
338/// about a missing renderer or text layer: no library would read it either.
339pub(crate) const UNREADABLE: &str =
340 "not a readable PDF: the file is damaged or not a PDF (its structure could not be parsed)";
341
342/// [`convert_text_layer`] restricted to a **1-based inclusive** page window
343/// (issue #80's `--pages`); `None` converts everything. The window is
344/// validated the same way as [`Pipeline::pages`]: `first <= last`, 1-based,
345/// and it must select at least one existing page.
346pub fn convert_text_layer_pages(
347 bytes: &[u8],
348 name: &str,
349 pages: Option<(usize, usize)>,
350) -> Result<DoclingDocument, PdfError> {
351 convert_text_layer_pages_with(bytes, name, pages, None)
352}
353
354/// [`convert_text_layer_pages`] with the word-gap rule of the text layer's
355/// line and word contraction (#921, [`WordGap`]); `None` = the process
356/// default (`DOCLING_RS_PDF_WORD_GAP`, else [`WordGap::Adaptive`]).
357pub fn convert_text_layer_pages_with(
358 bytes: &[u8],
359 name: &str,
360 pages: Option<(usize, usize)>,
361 word_gap: Option<WordGap>,
362) -> Result<DoclingDocument, PdfError> {
363 convert_text_layer_pages_opts(
364 bytes,
365 name,
366 pages,
367 TextOptions {
368 word_gap,
369 ..TextOptions::from_env()
370 },
371 )
372}
373
374/// [`convert_text_layer_pages`] with every text-layer setting (#921): the
375/// word-gap rule and whether typographic punctuation is kept as drawn.
376pub fn convert_text_layer_pages_opts(
377 bytes: &[u8],
378 name: &str,
379 pages: Option<(usize, usize)>,
380 text: TextOptions,
381) -> Result<DoclingDocument, PdfError> {
382 if let Some((first, last)) = pages {
383 if first == 0 || last < first {
384 return Err(PdfError::Pdfium(format!(
385 "invalid page range {first}-{last} (pages are 1-based, first <= last)"
386 )));
387 }
388 }
389 let mut doc = DoclingDocument::new(name);
390 // A file nothing can open is an error, not a PDF that merely has no
391 // text layer (the caller's "scanned? needs OCR" hint).
392 let Some(mut parser) = textparse::PageTextParser::open(bytes) else {
393 return Err(PdfError::Document(UNREADABLE.into()));
394 };
395 parser.set_word_gap(text.word_gap);
396 parser.set_keep_typography(Some(text.keep_typography));
397 // Pages are parsed, assembled and dropped one at a time: holding every
398 // page's cells until the end made the peak scale with the whole file —
399 // and a page window still paid for every page outside it.
400 let total = parser.page_count();
401 let mut tally = textparse::TextLayerTally::default();
402 for i in 0..total {
403 let selected = pages.is_none_or(|(first, last)| (first..=last).contains(&(i + 1)));
404 // A page outside the window only feeds the vestigial verdict below,
405 // so it is parsed only until that verdict is settled (on any real
406 // text layer, by the first page or two).
407 if !selected && tally.proves_text(total) {
408 continue;
409 }
410 let page = parser.text_page(i);
411 tally.add(&page);
412 if !selected {
413 continue;
414 }
415 let mut regions = Vec::new();
416 assemble::add_orphan_regions(&mut regions, &page.cells);
417 let table_rows = vec![None; regions.len()];
418 let enrich_out = vec![None; regions.len()];
419 let (mut nodes, links) =
420 assemble::assemble_page(&page, regions, &table_rows, &enrich_out, None);
421 assemble::float_running_head(&mut nodes, &page.cells);
422 assemble::stamp_page_no(&mut nodes, i + 1);
423 doc.nodes.extend(nodes);
424 doc.links.extend(links);
425 }
426 // A vestigial layer (a few typed-in form fields over scanned pages) is not
427 // the document's text: return the empty document, which callers already
428 // report as "no text layer" — so an OCR-capable caller falls back to OCR
429 // instead of proudly extracting thirteen characters.
430 if tally.is_vestigial() {
431 return Ok(DoclingDocument::new(name));
432 }
433 if let Some((first, last)) = pages {
434 if first > total {
435 return Err(PdfError::Pdfium(format!(
436 "page range {first}-{last} is outside the document ({total} page(s))"
437 )));
438 }
439 }
440 assemble::merge_continuations(&mut doc.nodes, assemble::Continuations::Lines);
441 // Grown a page at a time, the node vector can be up to half spare
442 // capacity — hundreds of MB on a long document, held for its lifetime.
443 doc.nodes.shrink_to_fit();
444 Ok(doc)
445}
446
447/// Whether a PDF's embedded text layer is the document's text — the verdict
448/// behind [`Pipeline::text_layer_auto`]: `true` when the pages carry real
449/// text, `false` for a scanned / image-only file or a vestigial layer (a few
450/// typed-in form fields over scans; [`textparse::TextLayerTally`]'s rule,
451/// the one [`convert_text_layer`] answers with an empty document). Pure
452/// Rust, no render, no model: the pages are parsed only until the verdict
453/// is settled — on a digital document, by the first page or two; a scanned
454/// one is walked to the end, which is cheap (its content streams hold no
455/// text). Every page counts, not just a page window: the window is the
456/// caller's output selection, the document's nature is the whole file's.
457/// An unreadable file is an error, as on every other path.
458pub fn text_layer_has_text(bytes: &[u8], password: Option<&str>) -> Result<bool, PdfError> {
459 let Some(mut parser) = textparse::PageTextParser::open_with_password(bytes, password) else {
460 return Err(PdfError::Document(UNREADABLE.into()));
461 };
462 let total = parser.page_count();
463 let mut tally = textparse::TextLayerTally::default();
464 for i in 0..total {
465 if tally.proves_text(total) {
466 return Ok(true);
467 }
468 tally.add(&parser.text_page(i));
469 }
470 Ok(!tally.is_vestigial())
471}
472
473/// Threads ONNX inference may use, capped by `DOCLING_RS_PDF_THREADS` if set.
474/// Defaults to the available parallelism (ort otherwise picks a low number).
475#[cfg(feature = "ml")]
476pub(crate) fn intra_threads() -> usize {
477 if let Some(n) = env::parse::<usize>("DOCLING_RS_PDF_THREADS").filter(|&n| n > 0) {
478 return n;
479 }
480 env::cpu_budget()
481}
482
483#[cfg(feature = "ml")]
484/// TableFormer's intra-op width (#262): `DOCLING_RS_TF_INTRA` explicitly,
485/// else the shared [`intra_threads`] budget. The shared TF session used to
486/// take the raw host width on top of the already-sized worker pools —
487/// under a cgroup CPU limit that oversubscription showed up as constant
488/// throttling and ~66% higher peak memory (each intra thread carries its own
489/// arena slab); the reporter's 4-CPU/8-core case dropped from 2.2 GB to
490/// 1.3 GB peak by capping this pool.
491pub(crate) fn tf_intra() -> usize {
492 if let Some(n) = env::parse::<usize>("DOCLING_RS_TF_INTRA").filter(|&n| n > 0) {
493 return n;
494 }
495 intra_threads()
496}
497
498#[cfg(feature = "ml")]
499/// True when `DOCLING_RS_FP32` forces the full-precision models even where
500/// an INT8 variant sits next to the fp32 default.
501pub(crate) fn fp32_forced() -> bool {
502 env::flag("DOCLING_RS_FP32")
503}
504
505#[cfg(feature = "ml")]
506/// Should the int8 model defaults be skipped in favor of fp32? Either the
507/// user said so (`DOCLING_RS_FP32`), or a GPU execution provider is selected
508/// (#74) — the int8 exports are QDQ graphs calibrated for CPU kernels and
509/// only conformance-validated there. An explicit `DOCLING_*_ONNX` path
510/// override still wins over this at every call site.
511pub(crate) fn prefer_fp32() -> bool {
512 fp32_forced() || docling_onnx::prefers_fp32()
513}
514
515#[cfg(feature = "render")]
516/// Resolve a default (CWD-relative) asset path — the shared chain in
517/// [`docling_core::assets`]: CWD, then next to the executable and one level
518/// above it (the `scripts/install/install.sh` layout).
519pub(crate) fn resolve_asset(rel: &str) -> String {
520 docling_core::assets::resolve(rel)
521}
522
523/// One resolved runtime asset — which file a stage would load right now,
524/// given the CWD, the env overrides and the int8/fp32 preference.
525#[cfg(feature = "ml")]
526#[derive(Debug, Clone)]
527pub struct ModelEntry {
528 /// Pipeline stage, e.g. `layout`, `tableformer.decoder`, `ocr.rec`.
529 pub stage: &'static str,
530 /// The resolved path (absolute or CWD-relative, as it will be opened).
531 pub path: String,
532 /// Whether the file exists right now.
533 pub found: bool,
534 /// File size in bytes (0 when missing) — enough to tell an int8 quant
535 /// from an fp32 graph, or a stale model from a re-published one, at a
536 /// glance without hashing gigabytes per request.
537 pub bytes: u64,
538}
539
540/// Resolve the whole runtime model set **without loading anything** — the
541/// exact selection each stage performs at load time (layout honors the
542/// int8/fp32 preference, TableFormer its decoder ranking, OCR the language
543/// pair), plus the pdfium library. docling-serve exposes this at
544/// `/v1/config` and logs it at startup, so "the server picked up different
545/// models" is one `curl` away instead of a mystery of dissolved tables.
546/// Resolution is CWD-relative with an exe-dir fallback, so the answer can
547/// legitimately differ between two working directories.
548#[cfg(feature = "ml")]
549pub fn model_inventory() -> Vec<ModelEntry> {
550 fn entry(stage: &'static str, path: String) -> ModelEntry {
551 let meta = std::fs::metadata(&path).ok();
552 ModelEntry {
553 stage,
554 found: meta.is_some(),
555 bytes: meta.map(|m| m.len()).unwrap_or(0),
556 path,
557 }
558 }
559 let (enc, dec, bbx) = tableformer::resolved_paths();
560 let (rec, dict) = ocr::resolve_rec_pair(ocr::OcrLang::from_env());
561 let pdfium =
562 env::nonempty("PDFIUM_DYNAMIC_LIB_PATH").unwrap_or_else(|| resolve_asset(".pdfium/lib"));
563 vec![
564 entry(
565 "layout",
566 model_path(
567 "DOCLING_LAYOUT_ONNX",
568 ".models/layout_heron.onnx",
569 ".models/layout_heron_int8.onnx",
570 ),
571 ),
572 entry("tableformer.encoder", enc),
573 entry("tableformer.decoder", dec),
574 entry("tableformer.bbox", bbx),
575 entry("ocr.rec", rec),
576 entry("ocr.dict", dict),
577 entry("ocr.textline_ori", ocr_cls::resolve_cls_path()),
578 entry("pdfium", pdfium),
579 ]
580}
581
582/// Resolve a model path: an explicit env override always wins; otherwise the
583/// INT8 variant of the default path when it exists on disk (the quantized
584/// models are conformance-validated — see docs/PDF_CONFORMANCE.md — and load/run
585/// markedly faster on CPU), unless `DOCLING_RS_FP32` opts back into full
586/// precision; else the fp32 default.
587#[cfg(feature = "ml")]
588pub(crate) fn model_path(key: &str, fp32_default: &str, int8_default: &str) -> String {
589 if let Some(p) = env::nonempty(key) {
590 return p;
591 }
592 if !prefer_fp32() {
593 let p = resolve_asset(int8_default);
594 if std::path::Path::new(&p).exists() {
595 return p;
596 }
597 }
598 resolve_asset(fp32_default)
599}
600
601/// Decode a standalone image with hard resource limits. A crafted image can
602/// declare enormous dimensions in a few-KB file; `image::load_from_memory`
603/// then tries to allocate the full pixel buffer (e.g. 60000×60000 → ~10 GB),
604/// and allocation failure aborts the whole process, bypassing the per-request
605/// panic catch. The 256 MiB alloc / 30000-px caps below turn that into a
606/// recoverable decode error instead. `DOCLING_RS_MAX_IMAGE_PIXELS` overrides
607/// the per-side pixel cap for the rare legitimately-huge scan.
608///
609/// Gated on `ml`: the only callers (`convert_image`, the METS backend) are
610/// ML-only, and the `image` crate is an `ml`-feature dependency — the
611/// text-layer wasm build has neither.
612#[cfg(feature = "ml")]
613pub(crate) fn decode_image_limited(bytes: &[u8]) -> Result<image::RgbImage, PdfError> {
614 let max_side: u32 = env::parse("DOCLING_RS_MAX_IMAGE_PIXELS").unwrap_or(30_000);
615 decode_image_with_max_side(bytes, max_side)
616}
617
618/// The `(horizontal, vertical)` resolution an image input's page is sized by,
619/// as docling's `ImageDocumentBackend` reads it (#1093): Pillow's
620/// `info["dpi"]` ([`docling_core::image_dpi::resolution`]), 72 when the file
621/// records none or the `(1, 1)` / `(0, 0)` placeholders, the axes swapped when
622/// the EXIF orientation turned the frame a quarter (`decoded` is the size
623/// after [`decode_image_limited`] applied it; docling's `_oriented_frame`
624/// compares the sizes the same way). A resolution docling rejects — not
625/// finite, zero or negative on one axis — fails its conversion; here it reads
626/// as 72, degradation over failure.
627#[cfg(feature = "ml")]
628fn image_page_dpi(bytes: &[u8], decoded: (u32, u32)) -> (f64, f64) {
629 const DEFAULT: (f64, f64) = (72.0, 72.0);
630 let dpi = match docling_core::image_dpi::resolution(bytes) {
631 None => return DEFAULT,
632 Some(d) if d == (1.0, 1.0) || d == (0.0, 0.0) => return DEFAULT,
633 Some((x, y)) if !(x.is_finite() && y.is_finite() && x > 0.0 && y > 0.0) => return DEFAULT,
634 Some(d) => d,
635 };
636 let stored = image::ImageReader::new(std::io::Cursor::new(bytes))
637 .with_guessed_format()
638 .ok()
639 .and_then(|r| r.into_dimensions().ok());
640 match stored {
641 Some(size) if size != decoded => (dpi.1, dpi.0),
642 _ => dpi,
643 }
644}
645
646/// Whether `bytes` is an ISOBMFF HEIF/HEIC container (the `ftyp` brands
647/// iPhones write). Checked by content, not extension — HEIC regularly
648/// arrives misnamed `.jpg`.
649#[cfg(feature = "ml")]
650fn is_heif(bytes: &[u8]) -> bool {
651 bytes.len() >= 12
652 && &bytes[4..8] == b"ftyp"
653 && matches!(
654 &bytes[8..12],
655 b"heic" | b"heix" | b"hevc" | b"heim" | b"heis" | b"hevm" | b"hevs" | b"mif1" | b"msf1"
656 )
657}
658
659/// Decode a HEIF/HEIC primary image via libheif (#211). Behind the opt-in
660/// `heif` feature — libheif is a native dependency the default build (and
661/// wasm) must not carry.
662#[cfg(all(feature = "ml", feature = "heif"))]
663fn decode_heif(bytes: &[u8], max_side: u32) -> Result<image::RgbImage, PdfError> {
664 use libheif_rs::{ColorSpace, HeifContext, LibHeif, RgbChroma};
665 let err = |e: String| PdfError::Pdfium(format!("heif: {e}"));
666 let ctx = HeifContext::read_from_bytes(bytes).map_err(|e| err(e.to_string()))?;
667 let handle = ctx.primary_image_handle().map_err(|e| err(e.to_string()))?;
668 if handle.width() > max_side || handle.height() > max_side {
669 return Err(err(format!(
670 "image dimensions {}x{} exceed the {max_side}px per-side cap \
671 (DOCLING_RS_MAX_IMAGE_PIXELS overrides)",
672 handle.width(),
673 handle.height()
674 )));
675 }
676 let lib = LibHeif::new();
677 let img = lib
678 .decode(&handle, ColorSpace::Rgb(RgbChroma::Rgb), None)
679 .map_err(|e| err(e.to_string()))?;
680 let (w, h) = (img.width(), img.height());
681 let planes = img.planes();
682 let plane = planes
683 .interleaved
684 .ok_or_else(|| err("no RGB plane".into()))?;
685 let stride = plane.stride;
686 let mut out = image::RgbImage::new(w, h);
687 for (y, row) in out.rows_mut().enumerate() {
688 let src = &plane.data[y * stride..y * stride + w as usize * 3];
689 for (x, px) in row.enumerate() {
690 px.0 = [src[x * 3], src[x * 3 + 1], src[x * 3 + 2]];
691 }
692 }
693 Ok(out)
694}
695
696#[cfg(feature = "ml")]
697fn decode_image_with_max_side(bytes: &[u8], max_side: u32) -> Result<image::RgbImage, PdfError> {
698 use image::{ImageDecoder, ImageReader};
699 use std::io::Cursor;
700
701 if is_heif(bytes) {
702 #[cfg(feature = "heif")]
703 return decode_heif(bytes, max_side);
704 #[cfg(not(feature = "heif"))]
705 return Err(PdfError::Pdfium(
706 "HEIC/HEIF input needs a build with the `heif` cargo feature \
707 (rebuild with --features heif; links the system libheif)"
708 .into(),
709 ));
710 }
711
712 let mut limits = image::Limits::default();
713 limits.max_image_width = Some(max_side);
714 limits.max_image_height = Some(max_side);
715 limits.max_alloc = Some(256 * 1024 * 1024);
716
717 let mut reader = ImageReader::new(Cursor::new(bytes))
718 .with_guessed_format()
719 .map_err(|e| PdfError::Pdfium(format!("image: {e}")))?;
720 reader.limits(limits);
721 let mut decoder = reader
722 .into_decoder()
723 .map_err(|e| PdfError::Pdfium(format!("image: {e}")))?;
724 // docling#4247 (2.128, `ImageOps.exif_transpose`): a camera stores the
725 // sensor readout plus an orientation tag rather than rotated pixels, so
726 // a portrait photo would reach layout and OCR on its side unless the tag
727 // is honoured. An unreadable tag is no orientation, not an error.
728 let orientation = decoder
729 .orientation()
730 .unwrap_or(image::metadata::Orientation::NoTransforms);
731 let mut img = image::DynamicImage::from_decoder(decoder)
732 .map_err(|e| PdfError::Pdfium(format!("image: {e}")))?;
733 img.apply_orientation(orientation);
734 Ok(img.into_rgb8())
735}
736
737/// Image outputs of the PDF/image pipeline (#519/#520): the scale picture
738/// crops are delivered at and whether each page's render is kept as the
739/// document's page image. See [`Pipeline::images_scale`] /
740/// [`Pipeline::generate_page_images`].
741#[derive(Debug, Clone, Copy, Default, PartialEq)]
742pub struct ImageOutput {
743 /// Pixels per PDF point for picture crops and page images — docling's
744 /// `images_scale`. `None` keeps the pipeline's own page render (2.0
745 /// px/pt), resampling nothing.
746 pub scale: Option<f32>,
747 /// Keep every page's render as the document's page image — docling's
748 /// `generate_page_images`.
749 pub page_images: bool,
750 /// A picture region holding exactly one safe embedded image gets that
751 /// bitmap at native resolution (`dpi` 72) instead of a render crop —
752 /// docling's `use_embedded_picture_images` (#1007, docling#5143; see
753 /// [`embedded`]). Anything uncertain keeps the crop.
754 pub embedded_pictures: bool,
755}
756
757#[cfg(feature = "ml")]
758/// Whether a page's text layer is furniture rather than its text (#936): a
759/// page number, a running header — at most [`SPARSE_LAYER_WORDS`] non-blank
760/// words covering under 2 % of the page — beside text drawn as outlines. A
761/// digital page's body text covers far more, so it never pays for the
762/// orientation probe. The area test alone was not enough: a figure page with
763/// a one-line caption (1–2 % covered, 20–30 words — three of the sixteen
764/// pages of `2203.01017v2.pdf`) passed it and paid the full-page text
765/// detector on every such page, +44 % on the document; the word cap keeps
766/// the probe for the layer a sideways outline page keeps (the reporter's
767/// `Page 1`: 2 words, 0.05 %).
768fn sparse_text_layer(page: &PdfPage) -> bool {
769 let (mut covered, mut words) = (0.0f32, 0usize);
770 for c in page.cells.iter().filter(|c| !c.text.trim().is_empty()) {
771 covered += (c.r - c.l).max(0.0) * (c.b - c.t).max(0.0);
772 words += c.text.split_whitespace().count();
773 }
774 words <= SPARSE_LAYER_WORDS && covered < 0.02 * page.width * page.height
775}
776
777#[cfg(feature = "ml")]
778/// The detector's longer-side cap for the orientation probe of a page that
779/// has a text layer (#945): the pre-#570 budget, enough for the few wide
780/// lines the probe scores.
781const PROBE_DET_MAX_SIDE: u32 = 960;
782
783#[cfg(feature = "ml")]
784/// [`sparse_text_layer`]'s word cap: a page number plus a running header of
785/// a few words, not a caption.
786const SPARSE_LAYER_WORDS: usize = 12;
787
788#[cfg(feature = "ml")]
789/// The layout regions of a page with a text layer that no programmatic text
790/// touches — docling's "clusters without any visible programmatic text"
791/// (`_find_pdf_aware_layout_ocr_rects`: any text cell intersecting the
792/// cluster counts), so their text, if any, is drawn as outlines (#931).
793/// Text, furniture and table regions only: pictures have their own pass.
794/// Furniture is relabeled `text`, the label region OCR reads.
795fn text_less_regions(regions: &[layout::Region], cells: &[TextCell]) -> Vec<layout::Region> {
796 regions
797 .iter()
798 .filter(|r| {
799 ocr_prep::is_text_label(r.label)
800 || assemble::is_table_like(r.label)
801 || matches!(r.label, "page_header" | "page_footer")
802 })
803 .filter(|r| {
804 !cells.iter().any(|c| {
805 !c.text.trim().is_empty()
806 && c.r.min(r.r) > c.l.max(r.l)
807 && c.b.min(r.b) > c.t.max(r.t)
808 })
809 })
810 .map(|r| layout::Region {
811 label: match r.label {
812 "page_header" | "page_footer" => "text",
813 l => l,
814 },
815 ..r.clone()
816 })
817 .collect()
818}
819
820#[cfg(feature = "ml")]
821/// docling's `THIN_SHAPE_LINE_HEIGHTS`: a band no thicker than this many
822/// text lines is accounted for by any text on it.
823const THIN_BAND_LINES: f32 = 2.0;
824#[cfg(feature = "ml")]
825/// docling's `TEXT_BACKED_MIN_COVERAGE`: a thicker area is accounted for
826/// when text covers this share of it.
827const TEXT_BACKED_MIN_COVERAGE: f32 = 0.1;
828#[cfg(feature = "ml")]
829/// The share of a region a bitmap must cover for [`bitmap_regions`] to OCR
830/// it.
831const BITMAP_REGION_COVER: f32 = 0.5;
832
833#[cfg(feature = "ml")]
834/// The layout regions of a page with a text layer that lie on a bitmap the
835/// text layer does not account for (#999) — docling's other
836/// `_find_pdf_aware_layout_ocr_rects` trigger, "clusters overlapping a
837/// bitmap": a scanned form with one typed-in value has text in its table
838/// region, so [`text_less_regions`] skipped it and the table read the one
839/// native word. The same labels as there; regions [`text_less_regions`]
840/// already takes are left to it.
841///
842/// Narrower than docling, on purpose: docling OCRs every cluster that
843/// touches a bitmap. Here the bitmap must cover at least
844/// [`BITMAP_REGION_COVER`] of the region, and its part inside the region
845/// must not be accounted for by the text layer, judged with docling's own
846/// rule for shapes (`_text_accounts_for`: a band no thicker than two text
847/// lines is explained by any text on it, a thicker one by text over a
848/// tenth of it). A searchable scan — an invisible text layer over the
849/// page image — and a digital page's logo or figure beside its text are
850/// left to their text layer instead of being OCR'd a second time.
851fn bitmap_regions(
852 regions: &[layout::Region],
853 cells: &[TextCell],
854 bitmaps: &[[f32; 4]],
855) -> Vec<layout::Region> {
856 if bitmaps.is_empty() {
857 return Vec::new();
858 }
859 let ink = |c: &&TextCell| !c.text.trim().is_empty();
860 regions
861 .iter()
862 .filter(|r| {
863 ocr_prep::is_text_label(r.label)
864 || assemble::is_table_like(r.label)
865 || matches!(r.label, "page_header" | "page_footer")
866 })
867 .filter(|r| {
868 // Regions with no text at all are `text_less_regions`'.
869 cells
870 .iter()
871 .filter(ink)
872 .any(|c| c.r.min(r.r) > c.l.max(r.l) && c.b.min(r.b) > c.t.max(r.t))
873 })
874 .filter(|r| {
875 let area = ((r.r - r.l) * (r.b - r.t)).max(1.0);
876 bitmaps.iter().any(|&[bl, bt, br, bb]| {
877 let (l, t, rr, b) = (bl.max(r.l), bt.max(r.t), br.min(r.r), bb.min(r.b));
878 let (w, h) = (rr - l, b - t);
879 if w <= 0.0 || h <= 0.0 || w * h < BITMAP_REGION_COVER * area {
880 return false;
881 }
882 let under: Vec<(f32, f32)> = cells
883 .iter()
884 .filter(ink)
885 .filter_map(|c| {
886 let iw = c.r.min(rr) - c.l.max(l);
887 let ih = c.b.min(b) - c.t.max(t);
888 (iw > 0.0 && ih > 0.0).then_some((c.b - c.t, iw * ih))
889 })
890 .collect();
891 if under.is_empty() {
892 return true;
893 }
894 let mut heights: Vec<f32> = under.iter().map(|u| u.0).collect();
895 heights.sort_by(f32::total_cmp);
896 let line = heights[heights.len() / 2];
897 if w.min(h) <= THIN_BAND_LINES * line {
898 return false;
899 }
900 let covered: f32 = under.iter().map(|u| u.1).sum();
901 covered / (w * h) < TEXT_BACKED_MIN_COVERAGE
902 })
903 })
904 .map(|r| layout::Region {
905 label: match r.label {
906 "page_header" | "page_footer" => "text",
907 l => l,
908 },
909 ..r.clone()
910 })
911 .collect()
912}
913
914#[cfg(feature = "ml")]
915/// The OCR'd cells with their recognition confidence, for the per-cell report
916/// (#915): a copy of what feeds the page `ocr_score`, kept beside it.
917fn cell_confs(scored: &[(TextCell, f32)]) -> Vec<docling_core::OcrCellConfidence> {
918 scored
919 .iter()
920 .map(|(c, conf)| docling_core::OcrCellConfidence {
921 text: c.text.clone(),
922 l: c.l,
923 t: c.t,
924 r: c.r,
925 b: c.b,
926 confidence: *conf,
927 })
928 .collect()
929}
930
931#[cfg(feature = "ml")]
932/// The document's report: page scores plus the per-cell OCR confidences (#915).
933fn confidence_report(
934 confs: std::collections::BTreeMap<usize, docling_core::confidence::PageConfidence>,
935 cells: std::collections::BTreeMap<usize, Vec<docling_core::OcrCellConfidence>>,
936) -> docling_core::ConfidenceReport {
937 cells.into_iter().fold(
938 docling_core::ConfidenceReport::from_pages(confs),
939 |report, (n, cells)| report.with_ocr_cells(n, cells),
940 )
941}
942
943#[cfg(feature = "ml")]
944/// One page's assembled output: typed nodes plus the page's hyperlinks (kept
945/// separate so pages processed out of order can be stitched back in page
946/// order) and its confidence scores (#183).
947type PageOut = (
948 Vec<Node>,
949 Vec<(String, String)>,
950 docling_core::confidence::PageConfidence,
951 // The page image, when page images are requested (#520).
952 Option<docling_core::PictureImage>,
953 // The page's OCR cells with their recognition confidence (#915).
954 Vec<docling_core::OcrCellConfidence>,
955);
956
957/// One page from its text layer alone — the fastest path: no layout, OCR
958/// or TableFormer inference at all. The embedded text cells (if any) become
959/// flat, line-grouped paragraphs in reading order via the same
960/// orphan-region machinery that normally rescues text the detector missed —
961/// here it rescues *all* of it. A page with no text layer (scanned /
962/// image-only) yields nothing. Shared by the `no_ocr` worker branch
963/// (images, METS) and the worker-less PDF loop of
964/// [`Pipeline::convert_text_only`], so `text_layer_only=true` and an
965/// `auto` document with text come out byte-identical.
966#[cfg(feature = "ml")]
967fn text_only_page(
968 page: &PdfPage,
969 images_scale: Option<f32>,
970) -> (
971 Vec<Node>,
972 Vec<(String, String)>,
973 docling_core::confidence::PageConfidence,
974) {
975 let parse = quality::parse_score(&page.cells);
976 let mut regions = Vec::new();
977 assemble::add_orphan_regions(&mut regions, &page.cells);
978 let table_rows = vec![None; regions.len()];
979 let enrich_out = vec![None; regions.len()];
980 let conf = quality::page_confidence(parse, ®ions, &[]);
981 let (nodes, links) = timing::timed("assemble_page", || {
982 assemble::assemble_page(page, regions, &table_rows, &enrich_out, images_scale)
983 });
984 (nodes, links, conf)
985}
986
987/// The page's image for the document's page images (#520) under `images`:
988/// `None` unless page images were requested, or when the page has no bitmap
989/// (the text-layer-only paths never render one).
990#[cfg(feature = "ml")]
991fn page_image_under(
992 images: ImageOutput,
993 n: usize,
994 page: &PdfPage,
995) -> Option<docling_core::PictureImage> {
996 if !images.page_images {
997 return None;
998 }
999 let image = assemble::page_image(page, images.scale);
1000 if image.is_none() {
1001 docling_core::debug_log!("page {}: no page bitmap for the page image", n + 1);
1002 }
1003 image
1004}
1005
1006#[cfg(feature = "ml")]
1007/// A page between region resolution and TableFormer: what `prepare_page`
1008/// produced and `complete_page` still needs, so a pool worker can park the
1009/// page while another worker holds the shared TableFormer (see `Staged`).
1010struct Prepared {
1011 regions: Vec<layout::Region>,
1012 ocr_confs: Vec<f32>,
1013 ocr_cells: Vec<docling_core::OcrCellConfidence>,
1014 parse: Option<f64>,
1015}
1016
1017#[cfg(feature = "ml")]
1018/// A pool worker's per-page outcome. `NeedsTables` is a page whose only
1019/// remaining stage is the shared TableFormer, which was busy when the worker
1020/// got there: rather than block on the mutex — one worker idle for the
1021/// whole of another worker's table decode, ~9.5 s of the 60-page .NET slice
1022/// on a 2-worker pool — the worker keeps the page aside, pulls the next one
1023/// off the render channel, and comes back once the slot is free. Results
1024/// are reassembled by page index anyway, so completion order is free.
1025enum Staged {
1026 Done(PageOut),
1027 NeedsTables(Prepared),
1028}
1029
1030#[cfg(feature = "ml")]
1031/// How many pages a pool worker keeps parked on the TableFormer before it
1032/// falls back to waiting: each carries its ~5 MB bitmaps, so this bounds the
1033/// extra residency to two pages per worker on top of the render channel.
1034const MAX_DEFERRED_PAGES: usize = 2;
1035
1036#[cfg(feature = "ml")]
1037/// The pool-wide TableFormer slot: one instance shared by every worker, loaded
1038/// lazily on the first table region any worker sees. Tables appear on a
1039/// minority of pages, so per-worker copies mostly multiplied ~0.4 GB of
1040/// weights+arenas by the pool size for nothing; a single shared instance keeps
1041/// the peak flat regardless of pool width, and a table's structure prediction
1042/// is independent of which worker runs it, so output is byte-identical. The
1043/// mutex serialises concurrent tables — the shared instance is loaded with the
1044/// full intra-op thread budget to compensate (one wide TableFormer instead of
1045/// several narrow ones).
1046enum TfSlot {
1047 /// Not attempted yet (no table seen so far).
1048 Unloaded,
1049 /// Load attempted, graphs absent — geometric fallback (warned once).
1050 Missing,
1051 Ready(tableformer::TableFormer),
1052}
1053
1054#[cfg(feature = "ml")]
1055impl TfSlot {
1056 /// Load TableFormer on the first call: `Ready`, or `Missing` when its
1057 /// graphs are absent (the geometric fallback — degradation, not an
1058 /// error). Later calls are no-ops either way.
1059 fn load(&mut self) {
1060 if matches!(self, TfSlot::Unloaded) {
1061 *self = match tableformer::TableFormer::load_with(tf_intra()) {
1062 Some(tf) => TfSlot::Ready(tf),
1063 None => TfSlot::Missing,
1064 };
1065 }
1066 }
1067}
1068
1069#[cfg(feature = "ml")]
1070type SharedTables = Arc<Mutex<TfSlot>>;
1071
1072#[cfg(feature = "ml")]
1073/// The same lazy shared-slot pattern for the (rarer still) enrichment models:
1074/// one instance per pipeline, loaded on the first region that needs it.
1075enum EnrichSlot<T> {
1076 Unloaded,
1077 /// Load attempted, model files absent — enrichment skipped (warned once).
1078 Missing,
1079 Ready(T),
1080}
1081
1082#[cfg(feature = "ml")]
1083type SharedClassifier = Arc<Mutex<EnrichSlot<enrich::PictureClassifier>>>;
1084#[cfg(feature = "ml")]
1085type SharedCodeFormula = Arc<Mutex<EnrichSlot<enrich::CodeFormula>>>;
1086
1087#[cfg(feature = "ml")]
1088/// The opt-in enrichment passes, mirroring docling's `PdfPipelineOptions`
1089/// flags (`do_picture_classification`, `do_code_enrichment`,
1090/// `do_formula_enrichment`). All off by default.
1091#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
1092pub struct EnrichmentOptions {
1093 /// Classify each picture with DocumentFigureClassifier (26 classes).
1094 pub picture_classification: bool,
1095 /// Rewrite code blocks (and detect their language) with CodeFormulaV2.
1096 pub code: bool,
1097 /// Decode display formulas to LaTeX with CodeFormulaV2.
1098 pub formula: bool,
1099}
1100
1101#[cfg(feature = "ml")]
1102impl EnrichmentOptions {
1103 fn any(&self) -> bool {
1104 self.picture_classification || self.code || self.formula
1105 }
1106}
1107
1108#[cfg(feature = "ml")]
1109/// The layout model's input for a page: the pypdfium2-exact scale-1.0 page
1110/// image (#478) when the renderer produced one, else the legacy stretch of the 2×
1111/// bitmap (browser / METS paths) — see [`layout::LayoutSrc`]. Public so the
1112/// diagnostic examples feed [`layout::LayoutModel::predict`] the same input
1113/// the pipeline does.
1114pub fn layout_src(page: &PdfPage) -> layout::LayoutSrc<'_> {
1115 match &page.image_layout {
1116 Some(img) => layout::LayoutSrc::PageImage(img),
1117 None => layout::LayoutSrc::Raw(&page.image),
1118 }
1119}
1120
1121#[cfg(feature = "ml")]
1122/// RapidOCR's longest side (`Global.max_side_len`, 2000): docling renders the
1123/// OCR input at `OcrOptions.scale` = 3 and RapidOCR then shrinks what exceeds
1124/// this before detecting and recognizing, so that is the resolution its
1125/// models actually see.
1126pub(crate) const RAPIDOCR_MAX_SIDE: f32 = 2000.0;
1127
1128#[cfg(feature = "ml")]
1129/// The px/pt the OCR reads a page at: the caller's `ocr_scale` when set; else,
1130/// for a standalone bitmap input — its own scale-1.0 page, a resolution the
1131/// pipeline did not choose — docling's rule (#570): three pixels per point
1132/// (`OcrOptions.scale`), shrunk so the longer side stays within RapidOCR's
1133/// 2000 px (a 754 × 1000 scanned form reads at 2.0; a 3000 px photo at 0.67,
1134/// as RapidOCR would downsample it). `None` for a rendered page (PDF, hOCR),
1135/// which keeps its own render — the 2.0 px/pt the conformance baselines are
1136/// pinned to. Measured on FUNSD at 1.0 / 2.0 / 3.0 px/pt: 0.825 / 0.856 /
1137/// 0.836 word recall — the recognizer likes its crops at the resolution
1138/// RapidOCR hands it, no more.
1139fn page_ocr_scale(ocr_scale: Option<f32>, width: f32, height: f32, scale: f32) -> Option<f32> {
1140 if ocr_scale.is_some() || scale != 1.0 {
1141 return ocr_scale;
1142 }
1143 let longest = width.max(height);
1144 if longest <= 0.0 {
1145 return None;
1146 }
1147 let s = 3.0f32.min(RAPIDOCR_MAX_SIDE / longest);
1148 ((s - 1.0).abs() > 1e-3).then_some(s)
1149}
1150
1151#[cfg(feature = "ml")]
1152/// The bitmap + px/pt scale the OCR reads (#254, docling#3877's
1153/// `OcrOptions.scale`): the page's own render unless `ocr_scale` asks for a
1154/// different resolution, where a PIL-bicubic resample of that render is built
1155/// once per page (cached in `cache`) and shared by every OCR pass. Resampling
1156/// — rather than a second native pdfium render — keeps one code path across
1157/// PDF, image, and hOCR inputs and leaves the layout/TableFormer pixels (and
1158/// with them the conformance baseline) untouched; the 144-dpi base render is
1159/// itself supersampled down from 216 dpi, so an upscaled OCR view loses
1160/// little against a native render.
1161fn ocr_input<'a>(
1162 cache: &'a mut Option<image::RgbImage>,
1163 image: &'a image::RgbImage,
1164 scale: f32,
1165 ocr_scale: Option<f32>,
1166) -> (&'a image::RgbImage, f32) {
1167 match ocr_scale {
1168 Some(s) if (s - scale).abs() > 1e-3 && image.width() > 1 => {
1169 let f = s / scale;
1170 let img = cache.get_or_insert_with(|| {
1171 let dw = ((image.width() as f32 * f).round() as u32).max(1);
1172 let dh = ((image.height() as f32 * f).round() as u32).max(1);
1173 resample::pil_resize(image, dw, dh, resample::PilFilter::Bicubic)
1174 });
1175 (img, s)
1176 }
1177 _ => (image, scale),
1178 }
1179}
1180
1181#[cfg(feature = "ml")]
1182/// A self-contained set of the per-page models (layout, OCR). Each parallel
1183/// page-worker owns its own `Worker` so inference runs concurrently without
1184/// sharing an ONNX session (`ort`'s `Session::run` is `&mut self`); only the
1185/// rarely-hit TableFormer is shared (see [`TfSlot`]).
1186struct Worker {
1187 /// `None` when `no_ocr` skips layout entirely — no model load, no inference.
1188 layout: Option<layout::LayoutModel>,
1189 ocr: OcrSlot,
1190 det: SharedDet,
1191 /// Text-detector results computed ahead of a page's OCR pass (#429), keyed
1192 /// by page index: the detector reads nothing but the page image, so it
1193 /// runs on its own thread while the layout model predicts — see
1194 /// [`Self::detect_alongside`] — and the OCR block collects the boxes here
1195 /// instead of paying for detection serially.
1196 pending_det: BTreeMap<usize, Result<Vec<ocr_det::DetBox>, String>>,
1197 /// This worker's intra-op thread budget — also the OCR lane count (see
1198 /// [`ocr::OcrModel::load_with`]): a pool worker with two threads runs two
1199 /// single-thread recognisers, the primary as many as its cores.
1200 intra: usize,
1201 /// Shared TableFormer slot; `None` when `no_table_former`/`no_ocr` skip it.
1202 tables: Option<SharedTables>,
1203 /// Shared enrichment slots; `None` unless the corresponding flag is on.
1204 classifier: Option<SharedClassifier>,
1205 code_formula: Option<SharedCodeFormula>,
1206 enrich: EnrichmentOptions,
1207 /// Skip layout, OCR, and TableFormer; reconstruct text purely from the PDF's
1208 /// embedded text layer. See [`Pipeline::no_ocr`].
1209 no_ocr: bool,
1210 /// Discard the embedded text layer and OCR every page. See
1211 /// [`Pipeline::force_full_page_ocr`].
1212 force_full_page_ocr: bool,
1213 /// OCR a page whose text layer [`quality::is_broken_text_layer`] judges
1214 /// broken, that page only (#1006). See
1215 /// [`Pipeline::replace_broken_text_layer`].
1216 replace_broken_text_layer: bool,
1217 /// Keep text-panel pictures as pictures instead of demoting them to
1218 /// paragraphs. See [`Pipeline::no_text_panels`].
1219 no_text_panels: bool,
1220 /// Never run OCR, but keep layout + TableFormer (#244) — docling's
1221 /// `do_ocr=False`. See [`Pipeline::skip_ocr`].
1222 skip_ocr: bool,
1223 /// Which recognition model [`Self::ocr`] loads. See [`Pipeline::ocr_lang`].
1224 ocr_lang: ocr::OcrLang,
1225 /// Which engine [`Self::ocr`] is (#460). See [`Pipeline::ocr_engine`].
1226 ocr_engine: ocr::OcrEngine,
1227 /// Tesseract's `-l` argument (#460). See [`Pipeline::tesseract_lang`].
1228 tesseract_lang: Option<String>,
1229 /// OCR render scale override (px/pt, #254). See [`Pipeline::ocr_scale`].
1230 ocr_scale: Option<f32>,
1231 /// RapidOCR's line orientation handling (#666), handed to the PP-OCR
1232 /// recognizer. See [`Pipeline::ocr_textline_orientation`].
1233 textline_orientation: bool,
1234 /// Picture-crop scale and page images (#519/#520). See [`ImageOutput`].
1235 images: ImageOutput,
1236}
1237
1238#[cfg(feature = "ml")]
1239/// The worker's lazily-loaded OCR recognition model. `Missing` records a
1240/// failed load (#244: degradation over failure — a deployment without the OCR
1241/// model still gets layout + TableFormer, and OCR-dependent regions stay
1242/// empty) so the load isn't retried per page.
1243enum OcrSlot {
1244 Unloaded,
1245 Ready(Recognizer),
1246 Missing,
1247}
1248
1249#[cfg(feature = "ml")]
1250/// The loaded OCR engine (#460): PP-OCRv3 via ONNX Runtime or the
1251/// `tesseract` binary. Both answer the two questions the page assembly asks
1252/// — line cells for text regions, word cells for table regions — in page
1253/// points with a 0–1 confidence, so the call sites never know which runs.
1254pub(crate) enum Recognizer {
1255 PpOcr(ocr::OcrModel),
1256 Tesseract(tesseract::TesseractOcr),
1257}
1258
1259#[cfg(feature = "ml")]
1260impl Recognizer {
1261 /// See [`ocr::OcrModel::ocr_page_with`].
1262 fn ocr_page(
1263 &mut self,
1264 img: &image::RgbImage,
1265 regions: &[layout::Region],
1266 scale: f32,
1267 ) -> Result<Vec<(TextCell, f32)>, String> {
1268 self.ocr_page_with(img, regions, scale, None)
1269 }
1270
1271 /// [`Self::ocr_page`] with the detector's boxes (#570). Tesseract segments its
1272 /// own lines and ignores the detector's boxes.
1273 fn ocr_page_with(
1274 &mut self,
1275 img: &image::RgbImage,
1276 regions: &[layout::Region],
1277 scale: f32,
1278 detected: Option<&[ocr_det::DetBox]>,
1279 ) -> Result<Vec<(TextCell, f32)>, String> {
1280 match self {
1281 Self::PpOcr(m) => m.ocr_page_with(img, regions, scale, detected),
1282 Self::Tesseract(t) => t.ocr_page(img, regions, scale),
1283 }
1284 }
1285
1286 /// See [`ocr::OcrModel::ocr_table_words`].
1287 fn ocr_table_words(
1288 &mut self,
1289 img: &image::RgbImage,
1290 regions: &[layout::Region],
1291 scale: f32,
1292 detected: Option<&[ocr_det::DetBox]>,
1293 ) -> Result<Vec<(TextCell, f32)>, String> {
1294 match self {
1295 Self::PpOcr(m) => m.ocr_table_words(img, regions, scale, detected),
1296 Self::Tesseract(t) => t.ocr_table_words(img, regions, scale),
1297 }
1298 }
1299}
1300
1301#[cfg(feature = "ml")]
1302/// The text detector (#429), loaded on the first OCR'd page like the
1303/// recognizer; `Missing` keeps the pipeline recognition-only. One instance
1304/// is shared by every worker ([`SharedDet`], #945, as TableFormer is): the
1305/// DB net's activation arena at the 2000 px input (#570) is ~250 MB, the
1306/// largest of any OCR model, and per-worker copies multiplied it by the
1307/// pool width for a model that runs once per page. The mutex serializes
1308/// concurrent detections; each worker's layout still runs alongside its
1309/// own, so the wall time is unchanged, and a page's boxes do not depend on
1310/// which worker detected them, so the output is byte-identical.
1311enum DetSlot {
1312 Unloaded,
1313 Ready(ocr_det::DetModel),
1314 Missing,
1315}
1316
1317#[cfg(feature = "ml")]
1318impl DetSlot {
1319 /// Load the detector on the first call — with the full intra-op budget,
1320 /// one wide session for the pool — `Missing` (said once under
1321 /// `DOCLING_RS_DEBUG`) when the model is not installed.
1322 fn load(&mut self) {
1323 if matches!(self, DetSlot::Unloaded) {
1324 *self = match ocr_det::DetModel::load(intra_threads()) {
1325 Ok(model) => DetSlot::Ready(model),
1326 Err(e) => {
1327 docling_core::debug_log!(
1328 "docling-pdf: text detection unavailable ({e}); OCR stays region-scoped"
1329 );
1330 DetSlot::Missing
1331 }
1332 };
1333 }
1334 }
1335}
1336
1337#[cfg(feature = "ml")]
1338type SharedDet = Arc<Mutex<DetSlot>>;
1339
1340#[cfg(feature = "ml")]
1341impl Worker {
1342 #[allow(clippy::too_many_arguments)] // mirrors the Pipeline's option set
1343 fn load(
1344 intra: usize,
1345 tables: Option<SharedTables>,
1346 det: SharedDet,
1347 enrich_slots: (Option<SharedClassifier>, Option<SharedCodeFormula>),
1348 enrich: EnrichmentOptions,
1349 no_ocr: bool,
1350 skip_ocr: bool,
1351 force_full_page_ocr: bool,
1352 no_text_panels: bool,
1353 ocr_lang: ocr::OcrLang,
1354 ocr_engine: ocr::OcrEngine,
1355 tesseract_lang: Option<String>,
1356 ocr_scale: Option<f32>,
1357 textline_orientation: bool,
1358 images: ImageOutput,
1359 ) -> Result<Self, PdfError> {
1360 Ok(Self {
1361 images,
1362 layout: if no_ocr {
1363 None
1364 } else {
1365 Some(layout::LayoutModel::load_with(intra).map_err(PdfError::Layout)?)
1366 },
1367 ocr: OcrSlot::Unloaded,
1368 det,
1369 pending_det: BTreeMap::new(),
1370 intra,
1371 tables,
1372 classifier: enrich_slots.0,
1373 code_formula: enrich_slots.1,
1374 enrich,
1375 no_ocr,
1376 skip_ocr,
1377 force_full_page_ocr,
1378 // Set by the pipeline after loading (`sync_ocr_config`).
1379 replace_broken_text_layer: false,
1380 no_text_panels,
1381 ocr_lang,
1382 ocr_engine,
1383 tesseract_lang,
1384 ocr_scale,
1385 textline_orientation,
1386 })
1387 }
1388
1389 /// Set [`Pipeline::ocr_textline_orientation`] here and on a loaded
1390 /// PP-OCR recognizer.
1391 fn set_textline_orientation(&mut self, enable: bool) {
1392 self.textline_orientation = enable;
1393 if let OcrSlot::Ready(Recognizer::PpOcr(m)) = &mut self.ocr {
1394 m.set_textline_orientation(enable);
1395 }
1396 }
1397
1398 /// The OCR model, or `None` when this conversion must not (or cannot) OCR:
1399 /// `skip_ocr` short-circuits, and a failed model load degrades to `None`
1400 /// with a one-time warning instead of failing the conversion (#244) —
1401 /// unless `force_full_page_ocr` demanded OCR explicitly, where a missing
1402 /// model stays a hard error (the text layer was deliberately discarded, so
1403 /// degrading would silently emit an empty document).
1404 fn ocr_model(&mut self) -> Result<Option<&mut Recognizer>, PdfError> {
1405 if self.skip_ocr {
1406 return Ok(None);
1407 }
1408 if matches!(self.ocr, OcrSlot::Unloaded) {
1409 let loaded = match self.ocr_engine {
1410 ocr::OcrEngine::PpOcr => {
1411 ocr::OcrModel::load_with(self.ocr_lang, self.intra).map(|mut m| {
1412 m.set_textline_orientation(self.textline_orientation);
1413 Recognizer::PpOcr(m)
1414 })
1415 }
1416 ocr::OcrEngine::Tesseract => tesseract::TesseractOcr::load(
1417 tesseract::TesseractOptions::from_env(self.tesseract_lang.clone()),
1418 self.intra,
1419 )
1420 .map(Recognizer::Tesseract),
1421 };
1422 match loaded {
1423 Ok(model) => self.ocr = OcrSlot::Ready(model),
1424 Err(e) if self.force_full_page_ocr => return Err(PdfError::Ocr(e)),
1425 Err(e) => {
1426 static WARNED: std::sync::Once = std::sync::Once::new();
1427 let hint = match self.ocr_engine {
1428 ocr::OcrEngine::PpOcr => {
1429 "run scripts/install/download_dependencies.sh for the model"
1430 }
1431 ocr::OcrEngine::Tesseract => {
1432 "install tesseract-ocr with the language pack, or use --ocr-engine ppocr"
1433 }
1434 };
1435 WARNED.call_once(|| {
1436 eprintln!(
1437 "warning: OCR model unavailable ({e}); continuing without OCR — \
1438 scanned pages and text inside images will come back empty \
1439 ({hint})"
1440 );
1441 });
1442 self.ocr = OcrSlot::Missing;
1443 }
1444 }
1445 }
1446 Ok(match &mut self.ocr {
1447 OcrSlot::Ready(model) => Some(model),
1448 _ => None,
1449 })
1450 }
1451
1452 /// Run `f` on the shared text detector (#429/#945), loading it on first
1453 /// use; `None` with `skip_ocr` or when the model is not installed —
1454 /// recognition stays region-scoped then, exactly the pre-#429 behavior.
1455 /// The slot's lock is held for the call, which serializes detections
1456 /// across the pool.
1457 fn with_det<R>(&mut self, f: impl FnOnce(&mut ocr_det::DetModel) -> R) -> Option<R> {
1458 if self.skip_ocr {
1459 return None;
1460 }
1461 let mut slot = self.det.lock().unwrap_or_else(|p| p.into_inner());
1462 slot.load();
1463 match &mut *slot {
1464 DetSlot::Ready(model) => Some(f(model)),
1465 _ => None,
1466 }
1467 }
1468
1469 /// Whether the text detector is there to run (loading it on first use).
1470 fn det_available(&mut self) -> bool {
1471 self.with_det(|_| ()).is_some()
1472 }
1473
1474 /// Run layout (+ OCR for cell-less pages) + TableFormer and assemble page `n`
1475 /// into its nodes and links. Pure given the page (mutates only the worker's
1476 /// lazily-loaded OCR model), so it is safe to run concurrently across pages.
1477 fn process(&mut self, n: usize, page: &mut PdfPage) -> Result<PageOut, PdfError> {
1478 if self.no_ocr {
1479 // Fastest path (`text_only_page`): the text layer alone, nothing
1480 // inferred. Pages with no embedded text layer yield nothing;
1481 // convert those without `no_ocr`.
1482 let (nodes, links, conf) = text_only_page(page, self.images.scale);
1483 return Ok((nodes, links, conf, self.page_image(n, page), Vec::new()));
1484 }
1485 self.normalize_orientation(n, page)?;
1486 let det_pages = self.det_candidates(std::slice::from_ref(&(n, &*page)))?;
1487 let regions = {
1488 let Self {
1489 layout,
1490 det,
1491 pending_det,
1492 ocr_scale,
1493 ..
1494 } = self;
1495 let layout = layout.as_mut().expect("layout model loaded unless no_ocr");
1496 let page: &PdfPage = &*page;
1497 Self::detect_alongside(&*det, pending_det, *ocr_scale, &det_pages, || {
1498 timing::timed("layout.predict", || {
1499 layout.predict(layout_src(page), page.width, page.height)
1500 })
1501 })
1502 }
1503 .map_err(|e| PdfError::Layout(format!("page {}: {e}", n + 1)))?;
1504 // The 2x bitmap (#682), when the detections read it (#897).
1505 self.ensure_bitmap(page, ®ions)?;
1506 self.finish_page(n, page, regions)
1507 }
1508
1509 /// The page's render as docling's `PageItem.image` (#520), at
1510 /// [`ImageOutput::scale`] — `None` unless page images were requested, or
1511 /// when the page has no bitmap (the text-layer-only `no_ocr` path never
1512 /// renders one).
1513 fn page_image(&self, n: usize, page: &PdfPage) -> Option<docling_core::PictureImage> {
1514 page_image_under(self.images, n, page)
1515 }
1516
1517 /// The pages of a batch the text detector should sweep (#429): bitmap
1518 /// pages (no text layer) on a run with OCR and the detector available —
1519 /// loading both lazily here so the concurrent run below needs no `self`.
1520 fn det_candidates<'p>(
1521 &mut self,
1522 pages: &[(usize, &'p PdfPage)],
1523 ) -> Result<Vec<(usize, &'p PdfPage)>, PdfError> {
1524 // Pages the orientation pass already detected (#571) are skipped:
1525 // their boxes wait in `pending_det`.
1526 let scanned: Vec<(usize, &PdfPage)> = pages
1527 .iter()
1528 .filter(|(n, p)| {
1529 p.cells.is_empty() && p.image.width() > 1 && !self.pending_det.contains_key(n)
1530 })
1531 .copied()
1532 .collect();
1533 if scanned.is_empty() || self.ocr_model()?.is_none() || !self.det_available() {
1534 return Ok(Vec::new());
1535 }
1536 Ok(scanned)
1537 }
1538
1539 /// Run `layout` on the calling thread while the text detector sweeps
1540 /// `det_pages` on another (#429): the detector only reads each page's
1541 /// image, layout only reads the pages too, and the two sessions are
1542 /// independent, so on a scanned page the ~0.7 s detection hides behind
1543 /// layout instead of adding to it. Results land in `pending_det` for the
1544 /// OCR block; a detector failure is recorded per page and surfaces there.
1545 fn detect_alongside<T>(
1546 det: &SharedDet,
1547 pending_det: &mut BTreeMap<usize, Result<Vec<ocr_det::DetBox>, String>>,
1548 ocr_scale: Option<f32>,
1549 det_pages: &[(usize, &PdfPage)],
1550 layout: impl FnOnce() -> T,
1551 ) -> T {
1552 if det_pages.is_empty() {
1553 return layout();
1554 }
1555 // Loaded by `det_candidates` (which produced a non-empty list); the
1556 // lock is held while this worker's layout runs, so another worker's
1557 // detection waits for this one — its layout does not.
1558 let mut slot = det.lock().unwrap_or_else(|p| p.into_inner());
1559 let DetSlot::Ready(det) = &mut *slot else {
1560 return layout();
1561 };
1562 std::thread::scope(|s| {
1563 let handle = s.spawn(move || {
1564 det_pages
1565 .iter()
1566 .map(|&(n, page)| {
1567 let mut view = None;
1568 let (img, _) = ocr_input(
1569 &mut view,
1570 &page.image,
1571 page.scale,
1572 page_ocr_scale(ocr_scale, page.width, page.height, page.scale),
1573 );
1574 (
1575 n,
1576 timing::timed("ocr.det", || {
1577 det.detect_scan(img, ocr_scale.is_none() && page.scale != 1.0)
1578 }),
1579 )
1580 })
1581 .collect::<Vec<_>>()
1582 });
1583 let out = layout();
1584 match handle.join() {
1585 Ok(results) => pending_det.extend(results),
1586 Err(_) => {
1587 for &(n, _) in det_pages {
1588 pending_det.insert(n, Err("ocr-det: detection thread panicked".into()));
1589 }
1590 }
1591 }
1592 out
1593 })
1594 }
1595
1596 /// Content-based orientation normalization (#225), before any inference:
1597 /// a physically rotated scan (sideways phone photo, landscape-fed sheet)
1598 /// has `/Rotate 0`, so the metadata pass in `extract_page` never fires and
1599 /// layout+OCR would read a sideways raster. Only pages with no text layer
1600 /// at all are probed (a digital page's raster is upright by construction,
1601 /// and its cells — not its pixels — carry the text); the detected angle
1602 /// composes with any `/Rotate` normalization through the same
1603 /// [`PdfPage::unrotate`] + display-space assembly mapping. Detection is
1604 /// evidence-gated and degrades to a no-op — see [`orient`].
1605 fn normalize_orientation(&mut self, n: usize, page: &mut PdfPage) -> Result<(), PdfError> {
1606 let scanned =
1607 page.cells.is_empty() && page.word_cells.is_empty() && page.code_cells.is_empty();
1608 if self.no_ocr || self.skip_ocr || !orient::enabled() {
1609 return Ok(());
1610 }
1611 // A sideways page drawn as vector outlines keeps a small upright text
1612 // layer (a page number, a running header, #936): the layer is too thin
1613 // to be the page's text, so the raster is probed like a scan's. The
1614 // render may still be deferred for a page that needed no bitmap.
1615 if !scanned {
1616 if !sparse_text_layer(page) {
1617 return Ok(());
1618 }
1619 page.resolve_image()?;
1620 }
1621 if page.image.width() <= 1 {
1622 return Ok(());
1623 }
1624 // The probe reads text through the OCR model; without one (missing —
1625 // #244 degradation) the page stays as rendered.
1626 if self.ocr_model()?.is_none() {
1627 return Ok(());
1628 }
1629 // The text detector's lines are the probe's crops (#571). Detected on
1630 // the page image as rendered; an upright scan keeps them for the OCR
1631 // pass (`pending_det`) when that pass reads the same bitmap, so the
1632 // detector runs once per page as before — a rotated page detects
1633 // again on the un-rotated image, alongside layout. A page with a
1634 // (thin) text layer only needs the probe's few wide lines and its
1635 // OCR pass detects on region crops (#931), so it pays the pre-#570
1636 // 960 px budget here instead of the full one (#945).
1637 let ocr_scale = page_ocr_scale(self.ocr_scale, page.width, page.height, page.scale);
1638 let image = &page.image;
1639 let boxes: Vec<ocr_det::DetBox> = self
1640 .with_det(|det| {
1641 timing::timed("orient.det", || {
1642 if scanned {
1643 det.detect_scan(image, ocr_scale.is_none() && page.scale != 1.0)
1644 } else {
1645 det.detect_capped(image, PROBE_DET_MAX_SIDE)
1646 }
1647 })
1648 })
1649 .unwrap_or(Ok(Vec::new()))
1650 .unwrap_or_else(|e| {
1651 debug_log!(
1652 "docling-pdf: page {}: text detection failed ({e}); probing projection strips",
1653 n + 1
1654 );
1655 Vec::new()
1656 });
1657 let Some(ocr) = self.ocr_model()? else {
1658 return Ok(());
1659 };
1660 let deg = timing::timed("orient.detect", || {
1661 orient::detect(&page.image, ocr, page.scale, &boxes)
1662 });
1663 if deg != 0 {
1664 debug_log!(
1665 "docling-pdf: page {}: content rotated {deg}° in the raster; \
1666 un-rotating before layout/OCR",
1667 n + 1
1668 );
1669 page.unrotate(deg);
1670 } else if scanned
1671 && !boxes.is_empty()
1672 && ocr_scale.is_none_or(|s| (s - page.scale).abs() <= 1e-3)
1673 {
1674 self.pending_det.insert(n, Ok(boxes));
1675 }
1676 Ok(())
1677 }
1678
1679 /// Layout-detect a whole batch of pages with one inference call (issue #73),
1680 /// then run each page's remaining stages (OCR / TableFormer / enrichment /
1681 /// assembly) per page. Index-aligned with `items`; a layout failure fails
1682 /// every page in the batch (they shared the one inference call).
1683 fn process_batch(&mut self, items: &mut [(usize, PdfPage)]) -> Vec<Result<Staged, PdfError>> {
1684 if self.no_ocr {
1685 // No layout model to batch — the text-layer-only path is per page.
1686 return items
1687 .iter_mut()
1688 .map(|(n, page)| {
1689 let n = *n;
1690 self.process(n, page).map(Staged::Done)
1691 })
1692 .collect();
1693 }
1694 // Orientation-normalize every scanned page before the shared layout
1695 // call — the batched inference must see upright bitmaps too (#225).
1696 for (n, page) in items.iter_mut() {
1697 let n = *n;
1698 if let Err(e) = self.normalize_orientation(n, page) {
1699 // Model-load failure — every page in the batch needs the same
1700 // model, so they all fail alike (mirrors the layout-error arm).
1701 let msg = e.to_string();
1702 return items
1703 .iter()
1704 .map(|_| Err(PdfError::Ocr(msg.clone())))
1705 .collect();
1706 }
1707 }
1708 let inputs: Vec<(layout::LayoutSrc<'_>, f32, f32)> = items
1709 .iter()
1710 .map(|(_, page)| (layout_src(page), page.width, page.height))
1711 .collect();
1712 let refs: Vec<(usize, &PdfPage)> = items.iter().map(|(n, page)| (*n, page)).collect();
1713 let det_pages = match self.det_candidates(&refs) {
1714 Ok(p) => p,
1715 Err(e) => {
1716 let msg = e.to_string();
1717 return items
1718 .iter()
1719 .map(|_| Err(PdfError::Ocr(msg.clone())))
1720 .collect();
1721 }
1722 };
1723 let batched = {
1724 let Self {
1725 layout,
1726 det,
1727 pending_det,
1728 ocr_scale,
1729 ..
1730 } = self;
1731 let layout = layout.as_mut().expect("layout model loaded unless no_ocr");
1732 Self::detect_alongside(&*det, pending_det, *ocr_scale, &det_pages, || {
1733 timing::timed("layout.predict", || layout.predict_batch(&inputs))
1734 })
1735 };
1736 match batched {
1737 Ok(all) => items
1738 .iter_mut()
1739 .zip(all)
1740 .map(|((n, page), regions)| {
1741 // The 2x bitmap (#682), when the detections read it (#897).
1742 self.ensure_bitmap(page, ®ions)?;
1743 self.stage_page(*n, page, regions)
1744 })
1745 .collect(),
1746 Err(e) => items
1747 .iter()
1748 .map(|(n, _)| Err(PdfError::Layout(format!("page {}: {e}", n + 1))))
1749 .collect(),
1750 }
1751 }
1752
1753 /// A pool worker's main loop: pull rendered pages off the shared channel
1754 /// (whatever is already there, up to the layout batch size), process them,
1755 /// and hand each finished page — or its error — to `deliver`, which returns
1756 /// `false` to stop early (the streaming consumer went away). Returns when
1757 /// the channel is closed and every page this worker took is delivered.
1758 ///
1759 /// Pages whose TableFormer turn would have to wait are parked (see
1760 /// `Staged`) and retried before every new pull; while any are parked the
1761 /// pull is non-blocking, so an empty channel means the worker waits for
1762 /// the TableFormer rather than for the renderer. The parking budget
1763 /// (`MAX_DEFERRED_PAGES`) bounds resident bitmaps; past it the worker waits
1764 /// like the serial path. Output is independent of completion order — the
1765 /// callers reassemble by page index.
1766 fn run_pool(
1767 &mut self,
1768 work_rx: &Mutex<Receiver<(usize, PdfPage)>>,
1769 layout_batch: usize,
1770 deadline: Option<std::time::Instant>,
1771 mut deliver: impl FnMut(usize, Result<PageOut, PdfError>) -> bool,
1772 ) {
1773 use std::sync::mpsc::TryRecvError;
1774 let mut deferred: std::collections::VecDeque<(usize, PdfPage, Prepared)> =
1775 std::collections::VecDeque::new();
1776 loop {
1777 // The document budget (#497), checked between pages: once it is
1778 // spent, every page still queued or parked is reported as timed
1779 // out instead of processed — the renderer stops feeding at the
1780 // same check, so the queue drains quickly.
1781 if expired(deadline) {
1782 while let Some((idx, _, _)) = deferred.pop_front() {
1783 if !deliver(idx, Err(timeout_sentinel())) {
1784 return;
1785 }
1786 }
1787 let rx = work_rx.lock().unwrap();
1788 loop {
1789 match rx.recv() {
1790 Ok((idx, _page)) => {
1791 if !deliver(idx, Err(timeout_sentinel())) {
1792 return;
1793 }
1794 }
1795 Err(_) => return,
1796 }
1797 }
1798 }
1799 // Any parked page the slot has since freed up for, oldest first.
1800 let mut i = 0;
1801 while i < deferred.len() {
1802 let (_, page, prepared) = &deferred[i];
1803 match self.table_rows_try(page, &prepared.regions) {
1804 Some(rows) => {
1805 let (idx, mut page, prepared) = deferred.remove(i).expect("index in range");
1806 if !deliver(idx, self.complete_page(idx, &mut page, prepared, rows)) {
1807 return;
1808 }
1809 }
1810 None => i += 1,
1811 }
1812 }
1813 // Hold the receiver lock only for the recv (plus a non-blocking drain
1814 // up to the layout batch size); release before the (long) per-page
1815 // work so other workers can pull concurrently.
1816 let mut batch: Vec<(usize, PdfPage)> = Vec::new();
1817 let mut closed = false;
1818 {
1819 let rx = work_rx.lock().unwrap();
1820 let first = if deferred.is_empty() {
1821 rx.recv().map_err(|_| TryRecvError::Disconnected)
1822 } else {
1823 rx.try_recv()
1824 };
1825 match first {
1826 Ok(item) => {
1827 batch.push(item);
1828 while batch.len() < layout_batch {
1829 match rx.try_recv() {
1830 Ok(item) => batch.push(item),
1831 Err(_) => break,
1832 }
1833 }
1834 }
1835 Err(TryRecvError::Empty) => {}
1836 Err(TryRecvError::Disconnected) => closed = true,
1837 }
1838 }
1839 if batch.is_empty() {
1840 // Nothing new rendered (or the channel is closed): wait our turn
1841 // on the oldest parked page instead.
1842 match deferred.pop_front() {
1843 Some((idx, mut page, prepared)) => {
1844 let rows = self.table_rows_blocking(&page, &prepared.regions);
1845 if !deliver(idx, self.complete_page(idx, &mut page, prepared, rows)) {
1846 return;
1847 }
1848 continue;
1849 }
1850 None if closed => return,
1851 None => continue,
1852 }
1853 }
1854 let outs = self.process_batch(&mut batch);
1855 for ((idx, mut page), out) in batch.into_iter().zip(outs) {
1856 let delivered = match out {
1857 Ok(Staged::Done(out)) => deliver(idx, Ok(out)),
1858 Ok(Staged::NeedsTables(prepared)) => {
1859 if deferred.len() < MAX_DEFERRED_PAGES {
1860 deferred.push_back((idx, page, prepared));
1861 true
1862 } else {
1863 let rows = self.table_rows_blocking(&page, &prepared.regions);
1864 deliver(idx, self.complete_page(idx, &mut page, prepared, rows))
1865 }
1866 }
1867 Err(e) => deliver(idx, Err(e)),
1868 };
1869 if !delivered {
1870 return;
1871 }
1872 }
1873 }
1874 }
1875
1876 /// Everything after layout detection: per-label confidence thresholds,
1877 /// overlap resolution, orphan-text recovery, OCR for cell-less pages,
1878 /// TableFormer, enrichment, and page assembly. The serial path: waits
1879 /// for the shared TableFormer when a table needs it.
1880 fn finish_page(
1881 &mut self,
1882 n: usize,
1883 page: &mut PdfPage,
1884 regions: Vec<layout::Region>,
1885 ) -> Result<PageOut, PdfError> {
1886 let prepared = self.prepare_page(n, page, regions)?;
1887 self.ensure_bitmap(page, &prepared.regions)?;
1888 let table_rows = self.table_rows_blocking(page, &prepared.regions);
1889 self.complete_page(n, page, prepared, table_rows)
1890 }
1891
1892 /// The pool path: like [`finish_page`](Self::finish_page), except that a
1893 /// page whose TableFormer turn would have to wait comes back as
1894 /// [`Staged::NeedsTables`] for the worker loop to park (see `Staged`).
1895 fn stage_page(
1896 &mut self,
1897 n: usize,
1898 page: &mut PdfPage,
1899 regions: Vec<layout::Region>,
1900 ) -> Result<Staged, PdfError> {
1901 let prepared = self.prepare_page(n, page, regions)?;
1902 self.ensure_bitmap(page, &prepared.regions)?;
1903 match self.table_rows_try(page, &prepared.regions) {
1904 Some(rows) => Ok(Staged::Done(self.complete_page(n, page, prepared, rows)?)),
1905 None => Ok(Staged::NeedsTables(prepared)),
1906 }
1907 }
1908
1909 /// Does this page read its 2x bitmap (#897)? Layout reads the separate
1910 /// 1x render; after it, the bitmap feeds TableFormer, picture crops (and
1911 /// the picture classifier, in-picture OCR and the image outputs on
1912 /// them), the code/formula enrichment crops, page images and OCR. A
1913 /// page without any of those — on a text-heavy document most pages —
1914 /// never renders it. Decided on the detections as they stand (a
1915 /// superset of what survives postprocessing, which only drops or
1916 /// demotes pictures and tables), and asked again wherever the regions
1917 /// change.
1918 fn needs_bitmap(&self, page: &PdfPage, regions: &[layout::Region]) -> bool {
1919 self.images.page_images
1920 || self.force_full_page_ocr
1921 || page.cells.is_empty()
1922 || regions.iter().any(|r| {
1923 r.label == "picture"
1924 || assemble::is_table_like(r.label)
1925 || (r.label == "code" && self.enrich.code)
1926 || (r.label == "formula" && self.enrich.formula)
1927 })
1928 }
1929
1930 /// Install the page's deferred 2x bitmap (#682) if [`Self::needs_bitmap`]
1931 /// says it is read — rendering it now when it was not rendered already —
1932 /// and otherwise decline it, so the render helper skips it when it has
1933 /// not got to it yet (#897). Idempotent, and a declined page can still
1934 /// be resolved later (an fp32 layout retry with new detections).
1935 fn ensure_bitmap(
1936 &self,
1937 page: &mut PdfPage,
1938 regions: &[layout::Region],
1939 ) -> Result<(), PdfError> {
1940 if page.image_pending() {
1941 if self.needs_bitmap(page, regions) {
1942 page.resolve_image()?;
1943 } else {
1944 page.decline_image();
1945 }
1946 }
1947 Ok(())
1948 }
1949
1950 /// Does this page need the shared TableFormer at all? Table-free pages
1951 /// never touch (or load) it.
1952 fn needs_tables(&self, regions: &[layout::Region]) -> bool {
1953 self.tables.is_some() && regions.iter().any(|r| assemble::is_table_like(r.label))
1954 }
1955
1956 /// TableFormer structure for every table region of the page, on an
1957 /// already-locked slot (loading the model on first use). Tables serialise
1958 /// on this mutex, so the one instance gets the shared thread budget
1959 /// (quota-aware, #262) — DOCLING_RS_TF_INTRA narrows it further where the
1960 /// memory-per-thread tradeoff matters more than table latency.
1961 fn predict_tables(
1962 guard: &mut TfSlot,
1963 page: &PdfPage,
1964 regions: &[layout::Region],
1965 ) -> Vec<Option<tf_core::TableGrid>> {
1966 let mut table_rows: Vec<Option<tf_core::TableGrid>> = vec![None; regions.len()];
1967 debug_assert!(
1968 !page.image_pending(),
1969 "TableFormer reached an unrendered page bitmap"
1970 );
1971 guard.load();
1972 if let TfSlot::Ready(tf) = guard {
1973 // One 1024-px frame per page, shared by all of its tables, and one
1974 // call for all of them: with the dynamic-batch decoder their
1975 // decode steps are shared (each step costs about the same for B
1976 // tables as for one).
1977 let page1024 = tableformer::TableFormer::page_1024(&page.image);
1978 let (idx, boxes): (Vec<usize>, Vec<[f32; 4]>) = regions
1979 .iter()
1980 .enumerate()
1981 .filter(|(_, r)| assemble::is_table_like(r.label))
1982 .map(|(i, r)| (i, [r.l, r.t, r.r, r.b]))
1983 .unzip();
1984 let rows =
1985 tf.predict_tables_on(page.image.height(), &page1024, &boxes, &page.word_cells);
1986 for (i, grid) in idx.into_iter().zip(rows) {
1987 table_rows[i] = grid;
1988 }
1989 }
1990 table_rows
1991 }
1992
1993 /// Table structure for the page, waiting for the shared slot if another
1994 /// worker holds it (else geometric fallback downstream when there is no
1995 /// TableFormer at all). The `tableformer` timing stage here includes any
1996 /// wait.
1997 fn table_rows_blocking(
1998 &self,
1999 page: &PdfPage,
2000 regions: &[layout::Region],
2001 ) -> Vec<Option<tf_core::TableGrid>> {
2002 match self.tables.as_ref().filter(|_| self.needs_tables(regions)) {
2003 Some(slot) => timing::timed("tableformer", || {
2004 Self::predict_tables(&mut slot.lock().unwrap(), page, regions)
2005 }),
2006 None => vec![None; regions.len()],
2007 }
2008 }
2009
2010 /// Non-blocking variant: `None` when the slot is held by another worker
2011 /// right now — the caller parks the page and tries again later.
2012 fn table_rows_try(
2013 &self,
2014 page: &PdfPage,
2015 regions: &[layout::Region],
2016 ) -> Option<Vec<Option<tf_core::TableGrid>>> {
2017 let Some(slot) = self.tables.as_ref().filter(|_| self.needs_tables(regions)) else {
2018 return Some(vec![None; regions.len()]);
2019 };
2020 match slot.try_lock() {
2021 Ok(mut guard) => Some(timing::timed("tableformer", || {
2022 Self::predict_tables(&mut guard, page, regions)
2023 })),
2024 Err(std::sync::TryLockError::WouldBlock) => None,
2025 Err(std::sync::TryLockError::Poisoned(e)) => panic!("TableFormer slot poisoned: {e}"),
2026 }
2027 }
2028
2029 /// The stages before TableFormer: fp32 escalation, per-label confidence
2030 /// thresholds, overlap resolution, orphan-text recovery, OCR for cell-less
2031 /// pages, in-picture text and table-word recognition.
2032 fn prepare_page(
2033 &mut self,
2034 n: usize,
2035 page: &mut PdfPage,
2036 regions: Vec<layout::Region>,
2037 ) -> Result<Prepared, PdfError> {
2038 // Force-OCR is exactly "pretend the text layer is not there": clear
2039 // every cell kind the extractors produced before anything reads them,
2040 // and the ordinary no-text-layer machinery below — full-page OCR,
2041 // OCR-fed TableFormer matching — takes over unchanged. (`no_ocr` wins
2042 // when both are set, mirroring docling, where `force_full_page_ocr`
2043 // is a sub-option of `do_ocr`; the no-ocr path never reaches here.)
2044 // Done here rather than in `process` so the batched layout path
2045 // (`process_batch` → `finish_page`) honors the flag too.
2046 // Parse quality is scored on the extracted text layer before force-OCR
2047 // discards it (docling's page-preprocessing stage runs before OCR too,
2048 // so its parse_score also reflects the original text layer).
2049 let mut parse = quality::parse_score(&page.cells);
2050 // docling#4654 (#1006): a text layer a broken font mapping produced
2051 // (`quality::is_broken_text_layer`) is replaced by full-page OCR on
2052 // this page only, its `parse_score` zeroed — it keeps describing the
2053 // PDF layer. Judged only with OCR available: a page whose layer is
2054 // discarded with no recognizer to read it would lose its text, so a
2055 // missing model keeps the (broken) layer, degradation over failure.
2056 let replace_broken = !self.force_full_page_ocr
2057 && self.replace_broken_text_layer
2058 && parse.is_some()
2059 && quality::is_broken_text_layer(
2060 &page
2061 .cells
2062 .iter()
2063 .map(|c| c.text.as_str())
2064 .collect::<Vec<_>>()
2065 .join("\n"),
2066 )
2067 && self.ocr_model()?.is_some();
2068 if replace_broken {
2069 debug_log!(
2070 "docling-pdf: page {}: broken text layer — replaced by full-page OCR",
2071 n + 1
2072 );
2073 parse = Some(0.0);
2074 }
2075 // Recognition confidences of every OCR'd cell on this page → ocr_score.
2076 let mut ocr_confs: Vec<f32> = Vec::new();
2077 let mut ocr_cells: Vec<docling_core::OcrCellConfidence> = Vec::new();
2078 // The bitmap the OCR reads (#254): with `ocr_scale` set, a resample of
2079 // the page render at the requested px/pt, built lazily on the first
2080 // OCR use so non-OCR pages never pay for it. Copied out of `self` up
2081 // front — the OCR sites hold `self.ocr_model()`'s mutable borrow.
2082 let ocr_scale = page_ocr_scale(self.ocr_scale, page.width, page.height, page.scale);
2083 let mut ocr_view: Option<image::RgbImage> = None;
2084 if self.force_full_page_ocr || replace_broken {
2085 page.cells.clear();
2086 page.code_cells.clear();
2087 page.word_cells.clear();
2088 }
2089 if replace_broken {
2090 // The bitmap was judged on the text layer just discarded (a prose
2091 // page declines it, #897); the OCR reads it now.
2092 self.ensure_bitmap(page, ®ions)?;
2093 }
2094 // Quant-robustness guard: the default int8 layout graph keeps its
2095 // confidences near the 0.5 label thresholds, and a different CPU's
2096 // quantized kernels can flip a whole page's detections under them —
2097 // tables and paragraphs then dissolve into orphan one-liners while the
2098 // same build converts the page perfectly elsewhere. When a dense
2099 // digital page ends up with detections covering almost none of its
2100 // text cells, re-run that one page on the fp32 graph (lazy-loaded,
2101 // auto-int8 selection only) and keep whichever detections cover more.
2102 let mut regions = regions;
2103 if !page.cells.is_empty() {
2104 let thresholded = |rs: &[layout::Region]| -> Vec<layout::Region> {
2105 rs.iter()
2106 .filter(|r| r.score >= layout::label_threshold(r.label))
2107 .cloned()
2108 .collect()
2109 };
2110 let text_cells = page
2111 .cells
2112 .iter()
2113 .filter(|c| !c.text.trim().is_empty())
2114 .count();
2115 let cov = assemble::layout_cell_coverage(&thresholded(®ions), &page.cells);
2116 if text_cells >= 15 && cov < 0.5 {
2117 let retry = self
2118 .layout
2119 .as_mut()
2120 .expect("layout model loaded unless no_ocr")
2121 .predict_fp32_fallback(layout_src(page), page.width, page.height)
2122 .map_err(|e| PdfError::Layout(format!("page {}: {e}", n + 1)))?;
2123 if let Some(retry) = retry {
2124 let cov2 = assemble::layout_cell_coverage(&thresholded(&retry), &page.cells);
2125 if cov2 > cov {
2126 debug_log!(
2127 "docling-pdf: page {}: int8 layout covered {:.0}% of the text \
2128 cells; the fp32 retry covers {:.0}% — using it",
2129 n + 1,
2130 cov * 100.0,
2131 cov2 * 100.0
2132 );
2133 regions = retry;
2134 // New detections may read the bitmap the first ones
2135 // did not (#897).
2136 self.ensure_bitmap(page, ®ions)?;
2137 }
2138 }
2139 }
2140 }
2141 // docling's LayoutPostprocessor drops each detection below its label's
2142 // confidence threshold (stricter than the 0.3 base the predictor keeps),
2143 // before any overlap resolution. This removes the low-confidence tables /
2144 // pictures / list-items that otherwise double-emit or mis-classify.
2145 if env::flag("DOCLING_RS_DEBUG_REGIONS") {
2146 for r in ®ions {
2147 eprintln!(
2148 "DBG raw {} {:.2} [{:.2},{:.2},{:.2},{:.2}]",
2149 r.label, r.score, r.l, r.t, r.r, r.b
2150 );
2151 }
2152 }
2153 regions.retain(|r| r.score >= layout::label_threshold(r.label));
2154 // docling's full-page picture filter and same-label picture dedup run
2155 // on the thresholded detections, before overlap resolution: a picture
2156 // that is the whole page goes (its text reads out as text), and a
2157 // figure proposed both whole and as sub-panels collapses to one box
2158 // (see `dedup_pictures`).
2159 assemble::drop_full_page_pictures(&mut regions, page.width, page.height);
2160 assemble::dedup_pictures(&mut regions);
2161 // Resolve overlapping detections once, before OCR.
2162 let mut regions = assemble::resolve(regions);
2163 // Emit text the detector missed as orphan text regions (docling parity).
2164 assemble::add_orphan_regions(&mut regions, &page.cells);
2165 // Drop phantom empty low-confidence picture boxes (docling parity).
2166 assemble::drop_false_pictures(&mut regions, &page.cells, page.width, page.height);
2167 // A regular region fully inside a surviving table/index/picture is that
2168 // special's child (a cell / in-figure label), not a separate block —
2169 // remove it so it isn't emitted twice (docling parity).
2170 assemble::drop_contained_regulars(&mut regions);
2171 // A one-line paragraph in the bottom margin under a body-less heading
2172 // is that heading's text, not furniture (deliberate deviation).
2173 assemble::reclaim_heading_body_footers(&mut regions, page.width);
2174 // No text layer → recognise text from the page image via OCR.
2175 let ocred = page.cells.is_empty();
2176 // Lines the text detector found outside every layout region (#429).
2177 let mut det_cells: Vec<pdfium_backend::TextCell> = Vec::new();
2178 if ocred {
2179 // Region-scoped OCR recognizes each region's crop, so two regular
2180 // regions over the same ink would read it twice — a low-score
2181 // paragraph box over the high-score line boxes `greedy` keeps.
2182 // Collapse such groups to one region first; a digital
2183 // page resolves the same overlap through cell ownership in
2184 // `fit_regions_to_cells` and needs nothing here.
2185 assemble::merge_overlapping_regulars(&mut regions);
2186 // The text detector's lines (#429), fetched before the region
2187 // pass: with `det` line mode (#570, the default) they are the
2188 // recognizer's crops inside the regions too — RapidOCR's own line
2189 // source — not only the supplement outside them. Usually computed
2190 // already, alongside layout (see `detect_alongside`); a page that
2191 // reached OCR another way detects here. Degradation over failure:
2192 // a detector that loaded but cannot run (a damaged file, an
2193 // allocation failure) costs the page its detected lines, not its
2194 // conversion — the projection segmentation is complete on its own.
2195 let detected: Vec<ocr_det::DetBox> = if self.ocr_model()?.is_some() {
2196 let (img, _) = ocr_input(&mut ocr_view, &page.image, page.scale, ocr_scale);
2197 match self.pending_det.remove(&n) {
2198 Some(result) => result,
2199 None => self
2200 .with_det(|det| {
2201 timing::timed("ocr.det", || {
2202 det.detect_scan(img, ocr_scale.is_none() && page.scale != 1.0)
2203 })
2204 })
2205 .unwrap_or(Ok(Vec::new())),
2206 }
2207 .unwrap_or_else(|e| {
2208 docling_core::debug_log!(
2209 "docling-pdf: page {}: text detection failed ({e}); keeping the \
2210 region-scoped OCR only",
2211 n + 1
2212 );
2213 Vec::new()
2214 })
2215 } else {
2216 Vec::new()
2217 };
2218 docling_core::debug_log!(
2219 "docling-pdf: page {}: text detector found {} line(s): {:?}",
2220 n + 1,
2221 detected.len(),
2222 detected
2223 .iter()
2224 .map(|d| (
2225 d.l.round(),
2226 d.t.round(),
2227 d.r.round(),
2228 d.b.round(),
2229 (d.score * 100.0).round() / 100.0
2230 ))
2231 .collect::<Vec<_>>()
2232 );
2233 let det_lines =
2234 (ocr::det_lines() && !detected.is_empty()).then_some(detected.as_slice());
2235 // `None` = `skip_ocr` or a missing model (#244): the page keeps
2236 // its layout regions (and TableFormer structure below) with no
2237 // recognized text, instead of failing the conversion.
2238 if let Some(ocr) = self.ocr_model()? {
2239 let (img, scl) = ocr_input(&mut ocr_view, &page.image, page.scale, ocr_scale);
2240 let cells = timing::timed("ocr.page", || {
2241 ocr.ocr_page_with(img, ®ions, scl, det_lines)
2242 })
2243 .map_err(|e| PdfError::Ocr(format!("page {}: {e}", n + 1)))?;
2244 ocr_confs.extend(cells.iter().map(|(_, conf)| conf));
2245 ocr_cells.extend(cell_confs(&cells));
2246 page.cells = cells.into_iter().map(|(cell, _)| cell).collect();
2247 // Table interiors carry no words yet: region-scoped OCR skips
2248 // table labels, and a scanned page has no pdfium text layer — so
2249 // TableFormer's cell matcher got an empty word list and the table
2250 // dissolved (#173). Recognize the table regions' word crops
2251 // (mirroring the browser scanned path): `word_cells` feeds the
2252 // matcher, and the same cells join `cells` so the geometric
2253 // fallback and the table's region text see them too.
2254 if regions.iter().any(|r| assemble::is_table_like(r.label)) {
2255 let (img, scl) = ocr_input(&mut ocr_view, &page.image, page.scale, ocr_scale);
2256 let words = timing::timed("ocr.table_words", || {
2257 ocr.ocr_table_words(img, ®ions, scl, det_lines)
2258 })
2259 .map_err(|e| PdfError::Ocr(format!("page {}: {e}", n + 1)))?;
2260 ocr_confs.extend(words.iter().map(|(_, conf)| conf));
2261 ocr_cells.extend(cell_confs(&words));
2262 let words: Vec<_> = words.into_iter().map(|(cell, _)| cell).collect();
2263 page.cells.extend(words.iter().cloned());
2264 page.word_cells = words;
2265 }
2266 }
2267 // docling's OCR engines detect text lines over the whole bitmap
2268 // and every line becomes a cell, so text the layout model gave no
2269 // region — a diagram's labels, a stamp, a margin note — still
2270 // reads out as orphan text. Region-scoped recognition above stays
2271 // the source inside layout regions; the detector (#429) adds only
2272 // the lines no recognized cell already covers, and the orphan pass
2273 // below places them (those inside a kept picture or table become
2274 // that special's silent children, as upstream).
2275 if self.ocr_model()?.is_some() {
2276 let (img, scl) = ocr_input(&mut ocr_view, &page.image, page.scale, ocr_scale);
2277 let uncovered = ocr_det::uncovered_lines(&detected, scl, ®ions, &page.cells);
2278 docling_core::debug_log!(
2279 "docling-pdf: page {}: {} of {} detected line(s) not covered by the region pass",
2280 n + 1,
2281 uncovered.len(),
2282 detected.len()
2283 );
2284 if let (false, Some(ocr)) = (uncovered.is_empty(), self.ocr_model()?) {
2285 let scored =
2286 timing::timed("ocr.det_lines", || ocr.ocr_page(img, &uncovered, scl))
2287 .map_err(|e| PdfError::Ocr(format!("page {}: {e}", n + 1)))?;
2288 ocr_confs.extend(scored.iter().map(|(_, conf)| conf));
2289 ocr_cells.extend(cell_confs(&scored));
2290 det_cells = scored.into_iter().map(|(cell, _)| cell).collect();
2291 page.cells.extend(det_cells.iter().cloned());
2292 }
2293 }
2294 } else {
2295 // A page with a text layer can still draw part of its text as
2296 // vector outlines (`gs -dNoOutputFonts`, flattened print PDFs):
2297 // the layout model finds the paragraph, the text layer holds
2298 // nothing there, and the region dropped empty — one native `Page
2299 // 1` footer was enough to switch the page's OCR off (#931).
2300 // docling's default `pdf_aware_layout_regions` OCRs every layout
2301 // cluster without any programmatic text in it
2302 // (`_find_pdf_aware_layout_ocr_rects`); do the same for the text,
2303 // furniture and table regions (pictures go through the bare-
2304 // picture pass below). Its other trigger, a cluster over a
2305 // bitmap, takes the regions a scan's image covers past a thin
2306 // text layer (#999, `bitmap_regions`).
2307 let mut empty = text_less_regions(®ions, &page.cells);
2308 empty.extend(bitmap_regions(®ions, &page.cells, &page.bitmaps));
2309 if let (false, Some(_)) = (empty.is_empty(), self.ocr_model()?) {
2310 // A page with a text layer and no picture or table had its
2311 // bitmap declined (#897); render it now — rare, and only
2312 // for the page that needs it.
2313 page.resolve_image()?;
2314 let (img, scl) = ocr_input(&mut ocr_view, &page.image, page.scale, ocr_scale);
2315 // Detected on the empty regions' crops, not the page (#945):
2316 // the page at the 2000 px budget cost ~2.3 s and ~250 MB per
2317 // such page for a caption's worth of lines; a crop reads at
2318 // full render resolution for a fraction of it. A margin of
2319 // half a line keeps the DB net's context at the edges.
2320 let rects: Vec<(u32, u32, u32, u32)> = empty
2321 .iter()
2322 .map(|r| {
2323 let m = (0.5 * (r.b - r.t)).clamp(4.0, 24.0) * scl;
2324 (
2325 ((r.l * scl - m).max(0.0)) as u32,
2326 ((r.t * scl - m).max(0.0)) as u32,
2327 (r.r * scl + m).ceil() as u32,
2328 (r.b * scl + m).ceil() as u32,
2329 )
2330 })
2331 .collect();
2332 let detected = self
2333 .with_det(|det| timing::timed("ocr.det", || det.detect_regions(img, &rects)))
2334 .unwrap_or(Ok(Vec::new()))
2335 .unwrap_or_else(|e| {
2336 docling_core::debug_log!(
2337 "docling-pdf: page {}: text detection failed ({e}); keeping the \
2338 region-scoped OCR only",
2339 n + 1
2340 );
2341 Vec::new()
2342 });
2343 let det_lines =
2344 (ocr::det_lines() && !detected.is_empty()).then_some(detected.as_slice());
2345 let ocr = self.ocr_model()?.expect("checked above");
2346 // docling's merge for this mode (`PDF_FIRST`): every native
2347 // cell is kept, and an OCR cell only where it touches none —
2348 // a typed-in value over its own scanned pixels is read once.
2349 let native = page.cells.clone();
2350 let pdf_first = |cells: &mut Vec<(TextCell, f32)>| {
2351 cells.retain(|(c, _)| table_tokens::uncovered([c], &native).len() == 1)
2352 };
2353 let mut scored = timing::timed("ocr.page", || {
2354 ocr.ocr_page_with(img, &empty, scl, det_lines)
2355 })
2356 .map_err(|e| PdfError::Ocr(format!("page {}: {e}", n + 1)))?;
2357 pdf_first(&mut scored);
2358 docling_core::debug_log!(
2359 "docling-pdf: page {}: {} text-less layout region(s) OCR'd, {} line(s)",
2360 n + 1,
2361 empty.len(),
2362 scored.len()
2363 );
2364 ocr_confs.extend(scored.iter().map(|(_, conf)| conf));
2365 ocr_cells.extend(cell_confs(&scored));
2366 page.cells.extend(scored.into_iter().map(|(cell, _)| cell));
2367 if empty.iter().any(|r| assemble::is_table_like(r.label)) {
2368 let mut words = timing::timed("ocr.table_words", || {
2369 ocr.ocr_table_words(img, &empty, scl, det_lines)
2370 })
2371 .map_err(|e| PdfError::Ocr(format!("page {}: {e}", n + 1)))?;
2372 pdf_first(&mut words);
2373 ocr_confs.extend(words.iter().map(|(_, conf)| conf));
2374 ocr_cells.extend(cell_confs(&words));
2375 let words: Vec<_> = words.into_iter().map(|(cell, _)| cell).collect();
2376 page.cells.extend(words.iter().cloned());
2377 // TableFormer's tokens (#999, docling's
2378 // `_words_and_ocr_cells`): the native words beside the
2379 // surviving OCR lines — the matcher saw the natives
2380 // alone, and one typed-in value made the whole table.
2381 page.word_cells =
2382 table_tokens::words_and_ocr_cells(&page.word_cells, &[], &words);
2383 }
2384 }
2385 }
2386 // Region-scoped OCR skips `picture` interiors, and a digital page's
2387 // text layer cannot see into an embedded raster either — so a figure
2388 // that is really a text box (terms-and-conditions exported as an
2389 // image) lost its words on every page kind. Python docling OCRs the
2390 // bitmap-covered areas of *every* page — even digital ones — once they
2391 // exceed `bitmap_area_threshold` (5 % of the page); the browser paths
2392 // already do. Recognize the big text-less crops here too; the panel
2393 // demotion / orphan recovery below place the lines.
2394 let mut pic_cells: Vec<pdfium_backend::TextCell> = Vec::new();
2395 {
2396 let page_area = (page.width * page.height).max(1.0);
2397 let has_text = |r: &layout::Region| {
2398 page.cells.iter().any(|c| {
2399 let ca = ((c.r - c.l) * (c.b - c.t)).max(1.0);
2400 let ix = (r.r.min(c.r) - r.l.max(c.l)).max(0.0);
2401 let iy = (r.b.min(c.b) - r.t.max(c.t)).max(0.0);
2402 !c.text.trim().is_empty() && ix * iy / ca > 0.5
2403 })
2404 };
2405 // A captioned picture can never demote to a text panel (see
2406 // recover_text_panels), and on digital pages its speculative OCR
2407 // would be discarded anyway — don't pay for it.
2408 let captioned = |r: &layout::Region| {
2409 regions.iter().any(|c| {
2410 c.label == "caption"
2411 && c.r.min(r.r) - c.l.max(r.l) > 0.0
2412 && ((c.t >= r.b && c.t - r.b <= 25.0) || (r.t >= c.b && r.t - c.b <= 25.0))
2413 })
2414 };
2415 let bare: Vec<layout::Region> = regions
2416 .iter()
2417 .filter(|r| {
2418 r.label == "picture"
2419 && (r.r - r.l) * (r.b - r.t) / page_area >= 0.05
2420 && !has_text(r)
2421 && (ocred || !captioned(r))
2422 })
2423 .map(|r| layout::Region {
2424 label: "text",
2425 ..r.clone()
2426 })
2427 .collect();
2428 // Speculative OCR (#244): with `skip_ocr` or no model, big bare
2429 // pictures simply stay pictures.
2430 if let (false, Some(ocr)) = (bare.is_empty(), self.ocr_model()?) {
2431 let (img, scl) = ocr_input(&mut ocr_view, &page.image, page.scale, ocr_scale);
2432 let scored = timing::timed("ocr.pictures", || ocr.ocr_page(img, &bare, scl))
2433 .map_err(|e| PdfError::Ocr(format!("page {}: {e}", n + 1)))?;
2434 // Speculative in-picture OCR counts toward ocr_score only on
2435 // OCR'd pages, where the recognized lines actually join the
2436 // output; on a digital page they may be discarded below.
2437 if ocred {
2438 ocr_confs.extend(scored.iter().map(|(_, conf)| conf));
2439 ocr_cells.extend(cell_confs(&scored));
2440 }
2441 pic_cells = scored.into_iter().map(|(cell, _)| cell).collect();
2442 page.cells.extend(pic_cells.iter().cloned());
2443 }
2444 }
2445 let cells_before_pic_ocr = page.cells.len() - pic_cells.len();
2446 // A "picture" that is really a colored text panel — dense, wide,
2447 // multi-line — reads out as paragraphs instead of shipping as pixels;
2448 // sparse in-picture text (a chart's labels) keeps the crop and stays
2449 // inside it as the picture's silent children (docling parity, #200).
2450 // `no_text_panels` (#173) opts out entirely for image-extraction
2451 // workflows.
2452 if !self.no_text_panels {
2453 assemble::recover_text_panels(&mut regions, &page.cells);
2454 }
2455 // On an OCR'd page, in-picture text that did NOT demote its picture
2456 // mostly stays silent, exactly as in docling: its postprocess step
2457 // "Remove regular clusters that are included in wrappers" walks
2458 // SPECIAL_TYPES — which includes PICTURE — so an orphan text cluster
2459 // >80 % contained in a kept picture becomes that picture's child and
2460 // never reaches the serializer. Only border-straddlers (≤80 %
2461 // containment) survive as text. Emitting *everything* here used to
2462 // splice a chart's OCR'd axis ticks into the body text right next to
2463 // the image chunk (#200) — so the orphan pass places the recognized
2464 // lines, the containment drop re-runs for the in-table ones, and
2465 // `assemble_page` nests the in-picture ones under their picture
2466 // (JSON-only children, `assemble::picture_parents`).
2467 if ocred && (!pic_cells.is_empty() || !det_cells.is_empty()) {
2468 // Pictures (and wrappers) no longer count as claimers (#165), so
2469 // the plain orphan pass places the recognized lines directly —
2470 // the detector's lines (#429) the same way.
2471 assemble::add_orphan_regions(&mut regions, &pic_cells);
2472 assemble::add_orphan_regions(&mut regions, &det_cells);
2473 assemble::drop_contained_regulars(&mut regions);
2474 } else if !ocred && !pic_cells.is_empty() {
2475 // Digital page, picture kept: its speculative OCR cells must not
2476 // linger in the text-cell set (they were appended at the tail).
2477 let kept: Vec<layout::Region> = regions
2478 .iter()
2479 .filter(|r| r.label == "picture")
2480 .cloned()
2481 .collect();
2482 let tail = page.cells.split_off(cells_before_pic_ocr);
2483 page.cells.extend(tail.into_iter().filter(|c| {
2484 !kept.iter().any(|r| {
2485 let ca = ((c.r - c.l) * (c.b - c.t)).max(1.0);
2486 let ix = (r.r.min(c.r) - r.l.max(c.l)).max(0.0);
2487 let iy = (r.b.min(c.b) - r.t.max(c.t)).max(0.0);
2488 ix * iy / ca > 0.5
2489 })
2490 }));
2491 }
2492 // A text-less *table* detected inside a picture on a digital page — a
2493 // screenshot of a table (2203's Figure 10) — has no text layer and no
2494 // scanned-path OCR to feed it, so its grid used to serialize empty and
2495 // the whole element vanished. docling OCRs bitmap-covered areas on
2496 // every page kind and its table cluster collects those cells; mirror
2497 // the scanned path for exactly these tables: recognize word crops and
2498 // feed them to the TableFormer matcher and the cell set.
2499 if !ocred {
2500 let has_text = |t: &layout::Region| {
2501 page.cells.iter().any(|c| {
2502 let ca = ((c.r - c.l) * (c.b - c.t)).max(1.0);
2503 let ix = (t.r.min(c.r) - t.l.max(c.l)).max(0.0);
2504 let iy = (t.b.min(c.b) - t.t.max(c.t)).max(0.0);
2505 !c.text.trim().is_empty() && ix * iy / ca > 0.5
2506 })
2507 };
2508 let in_picture = |t: &layout::Region| {
2509 regions.iter().any(|r| {
2510 r.label == "picture" && {
2511 let ta = ((t.r - t.l) * (t.b - t.t)).max(1.0);
2512 let ix = (r.r.min(t.r) - r.l.max(t.l)).max(0.0);
2513 let iy = (r.b.min(t.b) - r.t.max(t.t)).max(0.0);
2514 ix * iy / ta > 0.5
2515 }
2516 })
2517 };
2518 let pic_tables: Vec<layout::Region> = regions
2519 .iter()
2520 .filter(|t| assemble::is_table_like(t.label) && !has_text(t) && in_picture(t))
2521 .cloned()
2522 .collect();
2523 // Same degradation as above: without OCR the in-picture table
2524 // keeps its structure (TableFormer is geometry-driven) minus text.
2525 if let (false, Some(ocr)) = (pic_tables.is_empty(), self.ocr_model()?) {
2526 let (img, scl) = ocr_input(&mut ocr_view, &page.image, page.scale, ocr_scale);
2527 let words = timing::timed("ocr.table_words", || {
2528 ocr.ocr_table_words(img, &pic_tables, scl, None)
2529 })
2530 .map_err(|e| PdfError::Ocr(format!("page {}: {e}", n + 1)))?;
2531 ocr_confs.extend(words.iter().map(|(_, conf)| conf));
2532 ocr_cells.extend(cell_confs(&words));
2533 let words: Vec<_> = words.into_iter().map(|(cell, _)| cell).collect();
2534 page.cells.extend(words.iter().cloned());
2535 page.word_cells.extend(words);
2536 }
2537 }
2538 // The cells are final: fit every regular region to the cells it
2539 // claims and fold the orphans it now surrounds (#419), before
2540 // TableFormer and the reading order see the boxes.
2541 assemble::fit_regions_to_cells(&mut regions, &page.cells);
2542 Ok(Prepared {
2543 regions,
2544 ocr_confs,
2545 ocr_cells,
2546 parse,
2547 })
2548 }
2549
2550 /// The stages after TableFormer: enrichment, the page confidence report and
2551 /// assembly into typed nodes.
2552 fn complete_page(
2553 &mut self,
2554 n: usize,
2555 page: &mut PdfPage,
2556 prepared: Prepared,
2557 table_rows: Vec<Option<tf_core::TableGrid>>,
2558 ) -> Result<PageOut, PdfError> {
2559 let Prepared {
2560 regions,
2561 ocr_confs,
2562 ocr_cells,
2563 parse,
2564 } = prepared;
2565 // The crops and the page image below read the bitmap (#897).
2566 self.ensure_bitmap(page, ®ions)?;
2567 if env::flag("DOCLING_RS_DEBUG_REGIONS") {
2568 for (i, r) in regions.iter().enumerate() {
2569 eprintln!(
2570 "DBG final {} {:.2} [{:.0},{:.0},{:.0},{:.0}] rows={:?}",
2571 r.label,
2572 r.score,
2573 r.l,
2574 r.t,
2575 r.r,
2576 r.b,
2577 table_rows[i]
2578 .as_ref()
2579 .map(|t| (t.rows.len(), t.rows.first().map(|r| r.len())))
2580 );
2581 }
2582 eprintln!(
2583 "DBG cells={} words={}",
2584 page.cells.len(),
2585 page.word_cells.len()
2586 );
2587 }
2588 // Enrichment passes (opt-in): DocumentPictureClassifier over picture
2589 // regions, CodeFormulaV2 over code/formula regions. Same shared-slot
2590 // shape as TableFormer — one lazily-loaded instance per pipeline, only
2591 // ever locked when a page actually has a matching region.
2592 let mut enrich_out: Vec<Option<assemble::Enrichment>> = vec![None; regions.len()];
2593 if let Some(slot) = self.classifier.as_ref() {
2594 if regions.iter().any(|r| r.label == "picture") {
2595 timing::timed("picture_classifier", || {
2596 let mut guard = slot.lock().unwrap();
2597 if matches!(*guard, EnrichSlot::Unloaded) {
2598 *guard = match enrich::PictureClassifier::load_with(intra_threads()) {
2599 Some(m) => EnrichSlot::Ready(m),
2600 None => EnrichSlot::Missing,
2601 };
2602 }
2603 if let EnrichSlot::Ready(model) = &mut *guard {
2604 for (i, r) in regions.iter().enumerate() {
2605 if r.label != "picture" {
2606 continue;
2607 }
2608 let Some(crop) = assemble::crop_region_scaled(
2609 page,
2610 [r.l, r.t, r.r, r.b],
2611 enrich::CLASSIFIER_SCALE,
2612 ) else {
2613 continue;
2614 };
2615 match model.classify(&crop) {
2616 Ok(classes) => {
2617 enrich_out[i] =
2618 Some(assemble::Enrichment::PictureClasses(classes));
2619 }
2620 Err(e) => eprintln!("docling-pdf: page {}: {e}", n + 1),
2621 }
2622 }
2623 }
2624 });
2625 }
2626 }
2627 if let Some(slot) = self.code_formula.as_ref() {
2628 let wants = |label: &str| {
2629 (label == "code" && self.enrich.code) || (label == "formula" && self.enrich.formula)
2630 };
2631 if regions.iter().any(|r| wants(r.label)) {
2632 timing::timed("code_formula", || {
2633 let mut guard = slot.lock().unwrap();
2634 if matches!(*guard, EnrichSlot::Unloaded) {
2635 *guard = match enrich::CodeFormula::load_with(intra_threads()) {
2636 Some(m) => EnrichSlot::Ready(m),
2637 None => EnrichSlot::Missing,
2638 };
2639 }
2640 if let EnrichSlot::Ready(model) = &mut *guard {
2641 for (i, r) in regions.iter().enumerate() {
2642 if !wants(r.label) {
2643 continue;
2644 }
2645 // docling crops the postprocessed cluster box — the
2646 // union of the region's text cells, not the raw
2647 // detector box — expanded by 18% per side, at
2648 // ~120 dpi.
2649 let [bl, bt, br, bb] = assemble::region_cell_bbox(r, &page.cells)
2650 .unwrap_or([r.l, r.t, r.r, r.b]);
2651 let (w, h) = (br - bl, bb - bt);
2652 let ex = enrich::CODE_FORMULA_EXPANSION;
2653 let bbox = [bl - w * ex, bt - h * ex, br + w * ex, bb + h * ex];
2654 let Some(crop) = assemble::crop_region_scaled(
2655 page,
2656 bbox,
2657 enrich::CODE_FORMULA_SCALE,
2658 ) else {
2659 continue;
2660 };
2661 let kind = if r.label == "code" {
2662 enrich::CodeFormulaKind::Code
2663 } else {
2664 enrich::CodeFormulaKind::Formula
2665 };
2666 match model.predict(&crop, kind) {
2667 Ok(text) => {
2668 enrich_out[i] = Some(match kind {
2669 enrich::CodeFormulaKind::Code => {
2670 let (code, language) =
2671 enrich::extract_code_language(&text);
2672 assemble::Enrichment::Code {
2673 language,
2674 text: code,
2675 }
2676 }
2677 enrich::CodeFormulaKind::Formula => {
2678 assemble::Enrichment::Formula { latex: text }
2679 }
2680 });
2681 }
2682 Err(e) => eprintln!("docling-pdf: page {}: {e}", n + 1),
2683 }
2684 }
2685 }
2686 });
2687 }
2688 }
2689 // Score the final region set (docling assigns layout_score over the
2690 // postprocessed clusters — the page elements assemble_page emits,
2691 // which leave out the regulars nested in a picture as its children).
2692 let parents = assemble::picture_parents(®ions);
2693 let elements: Vec<layout::Region> = regions
2694 .iter()
2695 .zip(&parents)
2696 .filter(|(_, p)| p.is_none())
2697 .map(|(r, _)| r.clone())
2698 .collect();
2699 let conf = quality::page_confidence(parse, &elements, &ocr_confs);
2700 let (nodes, links) = timing::timed("assemble_page", || {
2701 assemble::assemble_page(page, regions, &table_rows, &enrich_out, self.images.scale)
2702 });
2703 Ok((nodes, links, conf, self.page_image(n, page), ocr_cells))
2704 }
2705}
2706
2707#[cfg(feature = "ml")]
2708/// Per-worker ONNX intra-op threads. The layout model is memory-bandwidth bound,
2709/// so on a typical machine two threads per worker (sharing one in-cache copy of
2710/// the weights) extracts more throughput than one fat model or many single-thread
2711/// workers. `DOCLING_RS_PDF_INTRA` overrides for per-machine tuning.
2712fn pdf_intra() -> usize {
2713 if let Some(n) = env::parse::<usize>("DOCLING_RS_PDF_INTRA").filter(|&n| n > 0) {
2714 return n;
2715 }
2716 if intra_threads() >= 2 {
2717 2
2718 } else {
2719 1
2720 }
2721}
2722
2723#[cfg(feature = "ml")]
2724/// How many page-workers to spin up for a multi-page PDF. `DOCLING_RS_PDF_WORKERS`
2725/// overrides; otherwise size the pool so `workers × intra ≈ cores`.
2726///
2727/// The pool scales with the machine (#324 follow-up testing): the old hard cap
2728/// of 4 left most of a many-core box idle — on a 16-core M4 Max, 10 workers
2729/// measured ~1.2× over the capped pool (10.0 → 8.5 s on a 130-page document,
2730/// byte-identical output). The ceiling of 16 is a memory bound, not a
2731/// performance one: each worker holds its own layout/OCR sessions (~0.4 GB),
2732/// so a worst-case pool stays under ~6.5 GB even on a ≥32-core host — and
2733/// docling-serve's per-request pools sit behind its `DOCLING_RS_MAX_MEMORY_MB`
2734/// admission control besides. Machines with 4 or fewer effective threads keep
2735/// the exact old sizing (`threads / intra`, min 1).
2736fn pdf_worker_count() -> usize {
2737 if let Some(n) = env::parse::<usize>("DOCLING_RS_PDF_WORKERS").filter(|&n| n > 0) {
2738 return n;
2739 }
2740 // One GPU behind every worker (#842): the pool multiplies the sessions,
2741 // and on the device that is memory, not speed — the serial primary's
2742 // render-ahead already overlaps rasterization with inference.
2743 if docling_onnx::prefers_single_worker() {
2744 return 1;
2745 }
2746 (intra_threads() / pdf_intra()).clamp(1, 16)
2747}
2748
2749#[cfg(feature = "ml")]
2750/// Max pages a worker layout-detects with one batched inference call (issue
2751/// #73). Workers drain the work channel opportunistically up to this size —
2752/// whatever is already rendered gets batched, so batching never *waits* for
2753/// pages and adds no latency when rendering is the bottleneck.
2754///
2755/// Default: per-page (1) on the CPU provider, 4 when a CUDA-class GPU
2756/// provider is selected (#338) — CoreML stays per-page (#602,
2757/// [`docling_onnx::prefers_batching`]): only the pinned batch=1 graph is
2758/// static, and static partitions are all CoreML is allowed to take. The old
2759/// "4 on 8+ cores" CPU default was a hypothesis — that single-session
2760/// amortization pays off with a wider thread budget —
2761/// and every actual CPU measurement lands the other way: a 4-core x86 box
2762/// runs the 9-page 2206.01062 fixture in 8.5 s/conv at batch=1 vs 9.3 s at
2763/// batch=4 (re-measured for #338; the original 8.1 vs 9.3 agrees), and the
2764/// issue-#338 report measured batch=1 ~2× faster on a 16-core M4 Max at
2765/// every worker count — batching only adds cache pressure once workers
2766/// saturate the cores. On a GPU the per-call dispatch overhead is real and
2767/// batching amortizes it, so the GPU default stays. Output is bit-identical
2768/// at every batch size, so this is purely a throughput knob.
2769/// `DOCLING_RS_PDF_LAYOUT_BATCH` overrides either way; `1` = per-page.
2770pub(crate) fn pdf_layout_batch() -> usize {
2771 env::parse::<usize>("DOCLING_RS_PDF_LAYOUT_BATCH")
2772 .filter(|&n| n > 0)
2773 .unwrap_or_else(|| {
2774 if docling_onnx::prefers_batching() {
2775 4
2776 } else {
2777 1
2778 }
2779 })
2780}
2781
2782#[cfg(feature = "ml")]
2783/// Pages the serial path renders ahead of the one being processed
2784/// ([`Pipeline::render_ahead`], #682): one in flight on the worker, two
2785/// rendered and waiting — a bound on resident page bitmaps, like the
2786/// pool's channel.
2787const RENDER_AHEAD: usize = 2;
2788
2789#[cfg(feature = "ml")]
2790/// Minimum page count before a PDF goes to the parallel worker pool; below
2791/// it the serial primary runs its model on every core. Four since #682 (was
2792/// six, from the days of the pool's uncached model load): the layout model's
2793/// intra-op scaling is weak (on a 4-core x86 box 4 threads run a page 2.35×
2794/// faster than one, 2 threads 1.6×), so two workers of two threads convert
2795/// pages faster than one worker of four converts them in turn — 4–5-page
2796/// digital documents measured 18% faster than the serial path with its
2797/// render-ahead, the pool's load included (the pool is sized to the page
2798/// count, [`Pipeline::ensure_pool_for`]). Not lower: the text detector a
2799/// scanned page needs scales well with threads, so a 2–3-page scan runs
2800/// 15–20% *slower* split across two-thread workers than on the four-thread
2801/// primary. `DOCLING_RS_PDF_PARALLEL_MIN` overrides.
2802fn pdf_parallel_min() -> usize {
2803 env::parse::<usize>("DOCLING_RS_PDF_PARALLEL_MIN")
2804 .filter(|&n| n > 0)
2805 .unwrap_or(4)
2806}
2807
2808#[cfg(feature = "ml")]
2809/// A reusable PDF pipeline. The **primary** worker runs its models on every core,
2810/// so a single-page / small / image / METS input is converted at full intra-op
2811/// speed with no pool to load. A document with enough pages instead fans out
2812/// across a **pool** of narrower workers processed concurrently. Both load lazily
2813/// and are cached for reuse, so a one-shot conversion only pays for what it uses.
2814pub struct Pipeline {
2815 /// Full-intra worker for the serial path; loaded on first serial use.
2816 primary: Option<Worker>,
2817 /// Narrower workers (≈cores/`target_workers` threads each) for the parallel
2818 /// path; loaded on first multi-page use and cached.
2819 pool: Vec<Worker>,
2820 /// The single TableFormer instance every worker shares (see [`TfSlot`]).
2821 tables: SharedTables,
2822 /// The pool-wide text detector slot (#945), see [`DetSlot`].
2823 det: SharedDet,
2824 /// The shared enrichment-model slots (same pattern as [`TfSlot`]).
2825 classifier: SharedClassifier,
2826 code_formula: SharedCodeFormula,
2827 /// Desired pool size for multi-page documents.
2828 target_workers: usize,
2829 /// Page count at/above which the parallel pool is worth its load cost.
2830 parallel_min: usize,
2831 /// Skip loading/running TableFormer; table regions fall back to geometric
2832 /// reconstruction. See [`Pipeline::no_table_former`].
2833 no_table_former: bool,
2834 /// Skip layout, OCR, and TableFormer entirely. See [`Pipeline::no_ocr`].
2835 no_ocr: bool,
2836 /// Per document: the text layer alone when it carries the text, the
2837 /// full pipeline otherwise. See [`Pipeline::text_layer_auto`].
2838 text_layer_auto: bool,
2839 /// Keep layout + TableFormer, never OCR (#244). See [`Pipeline::skip_ocr`].
2840 skip_ocr: bool,
2841 /// OCR every page even when it carries a text layer. See
2842 /// [`Pipeline::force_full_page_ocr`].
2843 force_full_page_ocr: bool,
2844 /// OCR only the pages whose text layer is broken (#1006). See
2845 /// [`Pipeline::replace_broken_text_layer`].
2846 replace_broken_text_layer: bool,
2847 /// Mark superscripts and subscripts (#1005). See
2848 /// [`Pipeline::script_positions`].
2849 script_positions: bool,
2850 /// Never demote text-panel pictures. See [`Pipeline::no_text_panels`].
2851 no_text_panels: bool,
2852 /// Opt-in enrichment passes. See [`Pipeline::enrichments`].
2853 enrich: EnrichmentOptions,
2854 /// 1-based inclusive page window to convert. See [`Pipeline::pages`].
2855 page_range: Option<(usize, usize)>,
2856 /// OCR recognition language. See [`Pipeline::ocr_lang`].
2857 ocr_lang: ocr::OcrLang,
2858 /// Which OCR engine runs (#460). See [`Pipeline::ocr_engine`].
2859 ocr_engine: ocr::OcrEngine,
2860 /// Tesseract's languages (#460). See [`Pipeline::tesseract_lang`].
2861 tesseract_lang: Option<String>,
2862 /// Which regions feed the OCR (#254). See [`Pipeline::ocr_mode`].
2863 ocr_mode: ocr::OcrMode,
2864 /// OCR render scale override in px/pt (#254). See [`Pipeline::ocr_scale`].
2865 ocr_scale: Option<f32>,
2866 /// Picture OCR scale (#666). See [`Pipeline::picture_ocr_scale`].
2867 picture_ocr_scale: Option<f32>,
2868 /// The text layer's word-gap rule (#921); `None` = the environment's
2869 /// (`DOCLING_RS_PDF_WORD_GAP`), else [`WordGap::Adaptive`].
2870 word_gap: Option<WordGap>,
2871 /// Keep typographic punctuation as drawn (#921); `None` = the
2872 /// environment's (`DOCLING_RS_PDF_KEEP_TYPOGRAPHY`), else folding.
2873 keep_typography: Option<bool>,
2874 /// RapidOCR's line orientation handling (#666). See
2875 /// [`Pipeline::ocr_textline_orientation`].
2876 textline_orientation: bool,
2877 /// Picture-crop scale and page images (#519/#520). See
2878 /// [`Pipeline::images_scale`] / [`Pipeline::generate_page_images`].
2879 images: ImageOutput,
2880 /// Heading-level inference (#302). See [`Pipeline::heading_hierarchy`].
2881 heading_hierarchy: HeadingHierarchyOptions,
2882 /// Optional per-page progress hook, invoked after each page finishes on
2883 /// every walk — the serial and parallel buffered paths, both streaming
2884 /// paths and the pre-rendered page path (images, METS). The converter
2885 /// turns it into its progress events (#783); `None` costs nothing.
2886 progress: Option<PageProgressHook>,
2887 /// Per-document wall-clock budget (docling's `document_timeout`, #497).
2888 /// See [`Pipeline::document_timeout`].
2889 document_timeout: Option<std::time::Duration>,
2890}
2891
2892#[cfg(feature = "ml")]
2893impl Pipeline {
2894 /// Construct the pipeline. Models load lazily on first use (full-intra primary
2895 /// for serial inputs, the helper pool for multi-page PDFs), so nothing is
2896 /// loaded that a given document doesn't need.
2897 pub fn new() -> Result<Self, PdfError> {
2898 Ok(Self {
2899 primary: None,
2900 pool: Vec::new(),
2901 tables: Arc::new(Mutex::new(TfSlot::Unloaded)),
2902 det: Arc::new(Mutex::new(DetSlot::Unloaded)),
2903 classifier: Arc::new(Mutex::new(EnrichSlot::Unloaded)),
2904 code_formula: Arc::new(Mutex::new(EnrichSlot::Unloaded)),
2905 target_workers: pdf_worker_count(),
2906 parallel_min: pdf_parallel_min(),
2907 no_table_former: false,
2908 no_ocr: false,
2909 text_layer_auto: false,
2910 skip_ocr: false,
2911 force_full_page_ocr: false,
2912 replace_broken_text_layer: false,
2913 script_positions: false,
2914 no_text_panels: false,
2915 enrich: EnrichmentOptions::default(),
2916 page_range: None,
2917 ocr_lang: ocr::OcrLang::from_env(),
2918 ocr_engine: ocr::OcrEngine::from_env(),
2919 tesseract_lang: None,
2920 ocr_mode: ocr::OcrMode::from_env(),
2921 ocr_scale: ocr::scale_from_env(),
2922 picture_ocr_scale: ocr::picture_scale_from_env(),
2923 word_gap: None,
2924 keep_typography: None,
2925 textline_orientation: ocr::textline_orientation_from_env(),
2926 images: ImageOutput::default(),
2927 heading_hierarchy: HeadingHierarchyOptions::default(),
2928 progress: None,
2929 document_timeout: None,
2930 })
2931 }
2932
2933 /// A wall-clock budget for each document (docling's
2934 /// `PipelineOptions.document_timeout`, #497; `None` = unlimited, the
2935 /// default). The budget starts when a conversion starts and is checked
2936 /// cooperatively between pages: once it is spent, no further page is
2937 /// rendered or processed, the pages already finished are assembled into
2938 /// the document, and the outcome says so (`Completion::TimedOut`, which
2939 /// the converter reports as `PartialSuccess` with a timeout error, the
2940 /// way docling does). A page in flight finishes — the check costs
2941 /// nothing inside a page, and a single-page document (an image) is never
2942 /// cut. For a long-lived pipeline use
2943 /// [`set_document_timeout`](Self::set_document_timeout) before each
2944 /// conversion.
2945 pub fn document_timeout(mut self, timeout: Option<std::time::Duration>) -> Self {
2946 self.document_timeout = timeout;
2947 self
2948 }
2949
2950 /// In-place variant of [`document_timeout`](Self::document_timeout) for a
2951 /// warm pipeline — set it before every conversion so no request inherits
2952 /// a previous one's budget.
2953 pub fn set_document_timeout(&mut self, timeout: Option<std::time::Duration>) {
2954 self.document_timeout = timeout;
2955 }
2956
2957 /// The deadline of a conversion starting now, from the configured budget.
2958 fn deadline(&self) -> Option<std::time::Instant> {
2959 self.document_timeout.map(|t| std::time::Instant::now() + t)
2960 }
2961
2962 /// The [`Completion`] of a walk that processed `done` of `selected` pages.
2963 fn completion(&self, timed_out: bool, done: usize, selected: usize) -> Completion {
2964 match (timed_out, self.document_timeout) {
2965 (true, Some(budget)) => Completion::TimedOut {
2966 pages_done: done,
2967 pages_selected: selected,
2968 budget,
2969 },
2970 _ => Completion::Complete,
2971 }
2972 }
2973
2974 /// Infer section-header levels after assembly (#302, docling's
2975 /// `HeadingHierarchyModel`): PDF bookmarks > legal/outline numbering >
2976 /// font style, off by default — see [`HeadingHierarchyOptions`]. Pure
2977 /// post-processing configuration; for a warm pipeline use
2978 /// [`set_heading_hierarchy`](Self::set_heading_hierarchy).
2979 pub fn heading_hierarchy(mut self, opts: HeadingHierarchyOptions) -> Self {
2980 self.heading_hierarchy = opts;
2981 self
2982 }
2983
2984 /// In-place variant of [`heading_hierarchy`](Self::heading_hierarchy) for
2985 /// a long-lived pipeline (docling-serve's warm instance) — like
2986 /// [`set_pages`](Self::set_pages), set it before every conversion so no
2987 /// request inherits a previous one's choice.
2988 pub fn set_heading_hierarchy(&mut self, opts: HeadingHierarchyOptions) {
2989 self.heading_hierarchy = opts;
2990 }
2991
2992 /// Run the enabled heading-hierarchy stage (#302) on an assembled
2993 /// document: gather the outline (bookmarks) and the per-page glyph styles
2994 /// on demand, then assign levels in place. `bytes` is `None` on paths
2995 /// with no PDF behind them (standalone images, METS) — those degrade to
2996 /// the numbering signal, exactly like docling without parsed pages.
2997 fn apply_heading_hierarchy(&self, nodes: &mut [Node], bytes: Option<&[u8]>) {
2998 let opts = &self.heading_hierarchy;
2999 if !opts.enabled {
3000 return;
3001 }
3002 let outline = match bytes {
3003 Some(bytes) if opts.use_bookmarks => outline::extract_outline(bytes),
3004 _ => Vec::new(),
3005 };
3006 let styles = match bytes {
3007 Some(bytes) if opts.use_style => {
3008 let pages = heading_hierarchy::heading_pages(nodes);
3009 textparse::glyph_styles(bytes, &pages)
3010 }
3011 _ => Default::default(),
3012 };
3013 heading_hierarchy::apply(nodes, &outline, &styles, opts);
3014 }
3015
3016 /// Run the opt-in script-position stage (#1005) on an assembled
3017 /// document, after the heading hierarchy as docling runs it.
3018 fn apply_script_positions(&self, nodes: &mut [Node], bytes: &[u8]) {
3019 if self.script_positions {
3020 timing::timed("script_position", || script_position::apply(nodes, bytes));
3021 }
3022 }
3023
3024 /// Mark superscript and subscript text — docling's
3025 /// `script_position_options.enabled` (docling#4815, #1005). Characters
3026 /// drawn smaller than their line and raised or lowered against it
3027 /// (footnote markers, `1st`, `mc²`, `H₂O`) become runs with
3028 /// `formatting.script`: a paragraph or footnote holding them keeps its
3029 /// place, and its text moves into an inline group of the runs in the
3030 /// JSON (HTML `<sup>`/`<sub>`, DocLang `<superscript>`/`<subscript>`);
3031 /// Markdown joins the runs as docling does (`E = mc2 in 1905.`, where the
3032 /// plain text layer reads `E = mc 2 in 1905.`). Headings, captions,
3033 /// tables, code, formulas, list items, OCR'd and invisible text are left
3034 /// alone. Off by default: the output is unchanged.
3035 pub fn script_positions(mut self, enable: bool) -> Self {
3036 self.set_script_positions(enable);
3037 self
3038 }
3039
3040 /// In-place variant of [`script_positions`](Self::script_positions).
3041 pub fn set_script_positions(&mut self, enable: bool) {
3042 self.script_positions = enable;
3043 }
3044
3045 /// Install (or clear) the per-page progress hook: called with a
3046 /// [`PageProgress`] after each page completes, on every conversion entry
3047 /// point ([`convert`](Self::convert), the streaming variants,
3048 /// [`convert_image`](Self::convert_image), [`process_pages`](Self::process_pages)).
3049 /// Shared with the parallel workers, so the callback must be cheap and
3050 /// thread-safe. A page the budget cut off is never reported here — the
3051 /// walk's [`Completion`] says how many were; the converter reports those
3052 /// as failed pages (#783).
3053 pub fn set_progress(&mut self, cb: Option<PageProgressHook>) {
3054 self.progress = cb;
3055 }
3056
3057 /// Convert only pages `first..=last` (**1-based**, like the page numbers a
3058 /// PDF viewer shows — issue #80's `--pages A-B`). Out-of-range pages are
3059 /// skipped before rasterization, so the cost is proportional to the window,
3060 /// not the document. `last` past the end of the document clamps; a window
3061 /// that selects no pages at all (`first` beyond the last page) is an error
3062 /// at convert time. `None` (the default) converts everything.
3063 pub fn pages(mut self, range: Option<(usize, usize)>) -> Self {
3064 self.page_range = range;
3065 self
3066 }
3067
3068 /// In-place variant of [`pages`](Self::pages) for a long-lived pipeline
3069 /// (e.g. docling-serve's warm instance) that applies a per-request window
3070 /// without rebuilding — unlike the model switches, the window is pure
3071 /// configuration. Set it before every conversion; it stays until changed.
3072 pub fn set_pages(&mut self, range: Option<(usize, usize)>) {
3073 self.page_range = range;
3074 }
3075
3076 /// OCR recognition language (see [`OcrLang`]): English by default, `ch`
3077 /// for the multilingual docling-conformance model. `None` keeps the
3078 /// process default (`DOCLING_RS_OCR_LANG`, else English). Set before the
3079 /// first conversion; for a warm pipeline use
3080 /// [`set_ocr_lang`](Self::set_ocr_lang).
3081 pub fn ocr_lang(mut self, lang: Option<ocr::OcrLang>) -> Self {
3082 self.set_ocr_lang(lang);
3083 self
3084 }
3085
3086 /// In-place variant of [`ocr_lang`](Self::ocr_lang) for a long-lived
3087 /// pipeline (docling-serve's warm instance). Unlike the page window this
3088 /// is a *model* switch: any worker whose cached recognition model was
3089 /// loaded for a different language drops it, to be lazily reloaded on the
3090 /// next OCR-needing page (cheap — the rec models are ~10 MB).
3091 pub fn set_ocr_lang(&mut self, lang: Option<ocr::OcrLang>) {
3092 let lang = lang.unwrap_or_else(ocr::OcrLang::from_env);
3093 self.ocr_lang = lang;
3094 for worker in self.primary.iter_mut().chain(self.pool.iter_mut()) {
3095 if worker.ocr_lang != lang {
3096 worker.ocr_lang = lang;
3097 worker.ocr = OcrSlot::Unloaded;
3098 }
3099 }
3100 }
3101
3102 /// Which OCR engine recognizes text (#460, see [`OcrEngine`]): the
3103 /// built-in PP-OCRv3 recognizer by default, or the system `tesseract`
3104 /// binary (docling's `TesseractCliOcrOptions`) — same layout-region
3105 /// crops, same cells; Tesseract does its own line/word segmentation and
3106 /// reads orientation from its OSD. `None` keeps the process default
3107 /// (`DOCLING_RS_OCR_ENGINE`, else PP-OCR). Set before the first
3108 /// conversion; for a warm pipeline use
3109 /// [`set_ocr_engine`](Self::set_ocr_engine).
3110 pub fn ocr_engine(mut self, engine: Option<ocr::OcrEngine>) -> Self {
3111 self.set_ocr_engine(engine);
3112 self
3113 }
3114
3115 /// In-place variant of [`ocr_engine`](Self::ocr_engine): a model switch
3116 /// like [`set_ocr_lang`](Self::set_ocr_lang) — workers holding the other
3117 /// engine drop it, to be lazily reloaded.
3118 pub fn set_ocr_engine(&mut self, engine: Option<ocr::OcrEngine>) {
3119 let engine = engine.unwrap_or_else(ocr::OcrEngine::from_env);
3120 self.ocr_engine = engine;
3121 for worker in self.primary.iter_mut().chain(self.pool.iter_mut()) {
3122 if worker.ocr_engine != engine {
3123 worker.ocr_engine = engine;
3124 worker.ocr = OcrSlot::Unloaded;
3125 }
3126 }
3127 }
3128
3129 /// Tesseract's languages (#460): the `-l` argument, tessdata stems joined
3130 /// with `+` — build it from an `ocr_lang` value with
3131 /// [`tesseract_lang_arg`], which also maps BCP-47 tags and the PP-OCR
3132 /// codes. `None` runs Tesseract's default (`eng`). Ignored under the
3133 /// PP-OCR engine, whose language is [`ocr_lang`](Self::ocr_lang). For a
3134 /// warm pipeline use [`set_tesseract_lang`](Self::set_tesseract_lang).
3135 pub fn tesseract_lang(mut self, lang: Option<String>) -> Self {
3136 self.set_tesseract_lang(lang);
3137 self
3138 }
3139
3140 /// In-place variant of [`tesseract_lang`](Self::tesseract_lang): a model
3141 /// switch like [`set_ocr_lang`](Self::set_ocr_lang) — a worker whose
3142 /// Tesseract was probed for other languages drops it.
3143 pub fn set_tesseract_lang(&mut self, lang: Option<String>) {
3144 self.tesseract_lang = lang.clone();
3145 for worker in self.primary.iter_mut().chain(self.pool.iter_mut()) {
3146 if worker.tesseract_lang != lang {
3147 worker.tesseract_lang = lang.clone();
3148 if worker.ocr_engine == ocr::OcrEngine::Tesseract {
3149 worker.ocr = OcrSlot::Unloaded;
3150 }
3151 }
3152 }
3153 }
3154
3155 /// Resolve the configured 1-based window against a page count into the
3156 /// 0-based inclusive form the backend walks, validating it selects at
3157 /// least one existing page.
3158 fn resolve_range(&self, total: usize) -> Result<Option<(usize, usize)>, PdfError> {
3159 let Some((first, last)) = self.page_range else {
3160 return Ok(None);
3161 };
3162 if first == 0 || last < first {
3163 return Err(PdfError::Pdfium(format!(
3164 "invalid page range {first}-{last} (pages are 1-based, first <= last)"
3165 )));
3166 }
3167 if first > total {
3168 return Err(PdfError::Pdfium(format!(
3169 "page range {first}-{last} is outside the document ({total} page(s))"
3170 )));
3171 }
3172 Ok(Some((first - 1, last.min(total) - 1)))
3173 }
3174
3175 /// Enable the opt-in enrichment passes (docling's
3176 /// `do_picture_classification` / `do_code_enrichment` /
3177 /// `do_formula_enrichment`). Each enabled pass lazily loads its model on
3178 /// the first matching region; a missing model warns once and is skipped.
3179 /// Set before the first conversion (no effect on already-loaded workers).
3180 pub fn enrichments(mut self, opts: EnrichmentOptions) -> Self {
3181 self.enrich = opts;
3182 self
3183 }
3184
3185 /// Skip loading and running the TableFormer table-structure model. Table
3186 /// regions still get emitted, but reconstructed geometrically from cell
3187 /// positions instead of via the ONNX model's predicted structure — faster
3188 /// (no model load, no per-table inference) at the cost of table fidelity.
3189 /// No effect if a worker is already loaded; set this before the first
3190 /// conversion.
3191 pub fn no_table_former(mut self, disable: bool) -> Self {
3192 self.no_table_former = disable;
3193 self
3194 }
3195
3196 /// Keep every detected `picture` region as a picture. By default an
3197 /// *uncaptioned* picture that reads like a dense, uniform text panel (a
3198 /// terms-and-conditions box exported as an image) is demoted into
3199 /// paragraphs (#157); a chart the layout mislabels can still trip that
3200 /// heuristic on scanned pages, and image-extraction workflows may simply
3201 /// want every crop — this flag disables the demotion entirely (#173).
3202 /// No effect on already-loaded workers; set before the first conversion.
3203 pub fn no_text_panels(mut self, disable: bool) -> Self {
3204 self.no_text_panels = disable;
3205 self
3206 }
3207
3208 /// Skip layout detection, OCR, and TableFormer entirely — no model load, no
3209 /// inference of any kind. The PDF's embedded text cells are grouped by line
3210 /// and emitted as plain paragraphs in reading order: no headings, lists,
3211 /// tables, code blocks, or pictures, since that structure comes from the
3212 /// layout model. The fastest possible PDF path, but pages with no embedded
3213 /// text layer (scanned/image-only PDFs) yield no text at all — convert those
3214 /// without this flag. Implies `no_table_former`. A PDF conversion reads
3215 /// the flag per call (its pages never touch a worker); image and METS
3216 /// pages read the flag the workers were loaded with, so set it before
3217 /// the first conversion for those.
3218 pub fn no_ocr(mut self, disable: bool) -> Self {
3219 self.no_ocr = disable;
3220 self
3221 }
3222
3223 /// Decide per document between the two: a PDF whose embedded text layer
3224 /// carries its text converts as under [`no_ocr`](Self::no_ocr) — the
3225 /// text layer alone, flat paragraphs, no model loaded, no inference —
3226 /// and one without a usable layer (scanned / image-only, or a vestigial
3227 /// layer of a few typed-in form fields; [`text_layer_has_text`]) runs the
3228 /// full pipeline, which OCRs its pages. The verdict is the document's,
3229 /// not a page's: a digital file with a few scanned pages inserted keeps
3230 /// the text path, and those pages come back empty as under `no_ocr`.
3231 /// `no_ocr` wins when both are set; forcing (`force_full_page_ocr`,
3232 /// `ocr_mode`) is read only on the pipeline side of the verdict, as
3233 /// under `no_ocr`. A per-conversion setting: the workers and their
3234 /// models are untouched, so a warm pipeline serving digital and scanned
3235 /// documents in turn reloads nothing.
3236 pub fn text_layer_auto(mut self, enable: bool) -> Self {
3237 self.text_layer_auto = enable;
3238 self
3239 }
3240
3241 /// Set [`text_layer_auto`](Self::text_layer_auto) on a built pipeline.
3242 pub fn set_text_layer_auto(&mut self, enable: bool) {
3243 self.text_layer_auto = enable;
3244 }
3245
3246 /// Never run OCR, but keep layout detection and TableFormer — docling's
3247 /// independent `do_ocr=False` (#244), the counterpart of
3248 /// [`no_table_former`](Self::no_table_former). Unlike
3249 /// [`no_ocr`](Self::no_ocr) (which skips the whole ML stack), structured
3250 /// output — headings, tables, pictures, reading order — is preserved;
3251 /// only text that exists solely as pixels is lost: scanned pages come
3252 /// back with their regions empty, and the speculative OCR of large
3253 /// embedded images never runs. The OCR model is never loaded. Ignored
3254 /// when `no_ocr` is set (there is no OCR to skip);
3255 /// takes precedence over [`force_full_page_ocr`](Self::force_full_page_ocr),
3256 /// mirroring docling where forcing is a sub-option of `do_ocr`.
3257 pub fn skip_ocr(mut self, disable: bool) -> Self {
3258 self.skip_ocr = disable;
3259 self
3260 }
3261
3262 /// OCR every page from its rendered image even when the page carries an
3263 /// embedded text layer — docling's `force_full_page_ocr`. The escape hatch
3264 /// for text layers that exist but lie: broken encodings, subset fonts with
3265 /// garbage mappings, a scanned form with a few typed-in fields. Ignored
3266 /// when [`no_ocr`](Self::no_ocr) is set, mirroring docling (there
3267 /// `force_full_page_ocr` is a sub-option of `do_ocr`).
3268 pub fn force_full_page_ocr(mut self, force: bool) -> Self {
3269 self.force_full_page_ocr = force;
3270 self
3271 }
3272
3273 /// Which document regions feed the OCR — docling's `OcrMode` (#254). The
3274 /// default (`default` = `pdf_aware_layout_regions`) is the standard
3275 /// text-layer-aware behavior; `full_page`/`layout_regions` discard the
3276 /// text layer like [`force_full_page_ocr`](Self::force_full_page_ocr)
3277 /// (see [`ocr::OcrMode`] for why both map onto it). Whichever of the flag
3278 /// and the mode demands forcing wins, mirroring docling's
3279 /// `force_full_page_ocr` → `mode=full_page` bridge. `None` keeps the
3280 /// process default (`DOCLING_RS_OCR_MODE`, else `default`).
3281 pub fn ocr_mode(mut self, mode: Option<ocr::OcrMode>) -> Self {
3282 self.ocr_mode = mode.unwrap_or_else(ocr::OcrMode::from_env);
3283 self
3284 }
3285
3286 /// In-place variants of [`force_full_page_ocr`](Self::force_full_page_ocr),
3287 /// [`ocr_mode`](Self::ocr_mode) and [`ocr_scale`](Self::ocr_scale) for a
3288 /// long-lived pipeline (docling-serve's warm instance): all three are pure
3289 /// per-worker configuration — no model reloads — so they apply per request
3290 /// like [`set_pages`](Self::set_pages). Set them before every conversion so
3291 /// no request inherits a previous one's choice.
3292 pub fn set_force_full_page_ocr(&mut self, force: bool) {
3293 self.force_full_page_ocr = force;
3294 self.sync_ocr_config();
3295 }
3296
3297 /// Replace a broken PDF text layer with OCR, page by page — docling's
3298 /// `replace_broken_text_layer` (docling#4654, #1006). A page whose text
3299 /// layer [`quality::is_broken_text_layer`] judges broken — control,
3300 /// U+FFFD or private-use characters on the page or in many of its
3301 /// lines, Latin letters that stand for another script, too few vowels —
3302 /// is read with full-page OCR, its `parse_score` set to 0; every other
3303 /// page, and a page without a text layer, keeps the usual behavior. A
3304 /// low `parse_score` alone never replaces a page. Off by default;
3305 /// ignored under [`no_ocr`](Self::no_ocr) / [`skip_ocr`](Self::skip_ocr)
3306 /// (a sub-option of docling's `do_ocr`) and moot under
3307 /// [`force_full_page_ocr`](Self::force_full_page_ocr). Pure per-worker
3308 /// configuration, like the forcing flag.
3309 pub fn replace_broken_text_layer(mut self, replace: bool) -> Self {
3310 self.set_replace_broken_text_layer(replace);
3311 self
3312 }
3313
3314 /// In-place variant of
3315 /// [`replace_broken_text_layer`](Self::replace_broken_text_layer).
3316 pub fn set_replace_broken_text_layer(&mut self, replace: bool) {
3317 self.replace_broken_text_layer = replace;
3318 self.sync_ocr_config();
3319 }
3320
3321 /// See [`set_force_full_page_ocr`](Self::set_force_full_page_ocr).
3322 pub fn set_ocr_mode(&mut self, mode: Option<ocr::OcrMode>) {
3323 self.ocr_mode = mode.unwrap_or_else(ocr::OcrMode::from_env);
3324 self.sync_ocr_config();
3325 }
3326
3327 /// How the text layer splits words where the PDF draws no space glyph
3328 /// (#921): docling-parse ≥ 7's line-local [`WordGap::Adaptive`]
3329 /// threshold (the default), a fixed [`WordGap::Factor`] of the two
3330 /// flanking glyphs' mean advance, or [`WordGap::Legacy`] (docling-parse
3331 /// ≤ 6's running-mean rule). `None` keeps `DOCLING_RS_PDF_WORD_GAP`,
3332 /// else the default.
3333 pub fn set_word_gap(&mut self, gap: Option<WordGap>) {
3334 self.word_gap = gap;
3335 }
3336
3337 /// See [`set_force_full_page_ocr`](Self::set_force_full_page_ocr).
3338 pub fn set_ocr_scale(&mut self, scale: Option<f32>) {
3339 self.ocr_scale = scale
3340 .filter(|s| s.is_finite() && *s > 0.0)
3341 .or_else(ocr::scale_from_env);
3342 self.sync_ocr_config();
3343 }
3344
3345 /// Resolution of the picture-OCR enrichment (#645) in pixels per
3346 /// picture pixel, before RapidOCR's 2000 px longer-side cap (#666) —
3347 /// RapidOCR reads a picture at its native pixels (`1.0`) and only
3348 /// shrinks what exceeds 2000 px. `None` (default:
3349 /// `DOCLING_RS_PICTURE_OCR_SCALE`, else unset) keeps the image-input
3350 /// rule pictures shared with scanned images: [`ocr_scale`](Self::ocr_scale)
3351 /// when set, else 3 px/pt shrunk to the 2000 px cap — which upscales a
3352 /// 720 × 180 screenshot to 2000 × 500. Pages and image inputs are
3353 /// unaffected. Non-positive values are ignored.
3354 pub fn picture_ocr_scale(mut self, scale: Option<f32>) -> Self {
3355 self.set_picture_ocr_scale(scale);
3356 self
3357 }
3358
3359 /// In-place [`picture_ocr_scale`](Self::picture_ocr_scale) for a warm
3360 /// pipeline.
3361 pub fn set_picture_ocr_scale(&mut self, scale: Option<f32>) {
3362 self.picture_ocr_scale = scale
3363 .filter(|s| s.is_finite() && *s > 0.0)
3364 .or_else(ocr::picture_scale_from_env);
3365 }
3366
3367 /// RapidOCR's handling of text-line orientation (#666), off by default
3368 /// (`DOCLING_RS_OCR_TEXTLINE_ORIENTATION` sets the process default): each
3369 /// detected line is cropped along the detector's rotated rectangle (a
3370 /// perspective warp, `get_rotate_crop_image`) instead of its axis-aligned
3371 /// box, a crop at least 1.5× taller than wide is turned 90°
3372 /// counter-clockwise, and the PP-LCNet text-line orientation classifier
3373 /// (`.models/ocr_textline_ori.onnx`, `DOCLING_OCR_TEXTLINE_ORI_ONNX`)
3374 /// turns lines it reads as upside down (`180` above 0.9). Vertical axis
3375 /// titles, rotated headers, skewed and upside-down lines then read as
3376 /// text. Applies to every PP-OCR line read off the detector — pages and
3377 /// pictures alike — but not to table words or the projection fallback;
3378 /// the reported boxes stay axis-aligned. A missing classifier warns once
3379 /// and keeps the crop and the 90° turn. Tesseract orients on its own.
3380 pub fn ocr_textline_orientation(mut self, enable: bool) -> Self {
3381 self.set_ocr_textline_orientation(Some(enable));
3382 self
3383 }
3384
3385 /// In-place [`ocr_textline_orientation`](Self::ocr_textline_orientation)
3386 /// for a warm pipeline (serve, the bindings' `Pipeline`), applied to
3387 /// loaded workers too; `None` restores the process default
3388 /// (`DOCLING_RS_OCR_TEXTLINE_ORIENTATION`), like
3389 /// [`set_ocr_scale`](Self::set_ocr_scale).
3390 pub fn set_ocr_textline_orientation(&mut self, enable: Option<bool>) {
3391 self.textline_orientation = enable.unwrap_or_else(ocr::textline_orientation_from_env);
3392 self.sync_ocr_config();
3393 }
3394
3395 /// Whether page extraction should decode the text layer at all. Forced
3396 /// full-page OCR (the flag or `ocr_mode=full_page|layout_regions`) clears
3397 /// every extracted cell unread, so the decode is skipped outright —
3398 /// docling#4061's `skip_cell_extraction` (2.122). `no_ocr` wins over the
3399 /// forcing, as everywhere else: its fast path *is* the text layer.
3400 fn extract_text_layer(&self) -> bool {
3401 self.no_ocr || !(self.force_full_page_ocr || self.ocr_mode.forces_full_page())
3402 }
3403
3404 /// When the walk renders the 2x bitmaps of pages with a text layer
3405 /// (#897). Adaptively by default: while the document's recent pages read
3406 /// theirs, each starts on the helper thread as the page leaves the walk,
3407 /// overlapping layout (#682); while they do not (prose), only a page that
3408 /// reads it renders it, after layout. Page images read every bitmap, so
3409 /// they keep the #682 schedule. `DOCLING_RS_PAGE_BITMAP` picks one
3410 /// explicitly: `eager` (every bitmap, during layout), `adaptive`,
3411 /// `on-demand` (only the bitmaps read — the least CPU, with every render
3412 /// after layout).
3413 fn bitmap_render(&self) -> pdfium_backend::BitmapRender {
3414 use pdfium_backend::BitmapRender;
3415 match env::nonempty("DOCLING_RS_PAGE_BITMAP")
3416 .map(|v| v.to_ascii_lowercase())
3417 .as_deref()
3418 {
3419 Some("eager") => BitmapRender::Eager,
3420 Some("on-demand" | "ondemand" | "lazy") => BitmapRender::OnDemand,
3421 _ if self.images.page_images => BitmapRender::Eager,
3422 _ => BitmapRender::Adaptive,
3423 }
3424 }
3425
3426 /// Push the current OCR forcing/scale choice onto already-loaded workers
3427 /// (new workers read it at [`Worker::load`]).
3428 fn sync_ocr_config(&mut self) {
3429 let force = self.force_full_page_ocr || self.ocr_mode.forces_full_page();
3430 let scale = self.ocr_scale;
3431 let orient = self.textline_orientation;
3432 let replace = self.replace_broken_text_layer;
3433 for worker in self.primary.iter_mut().chain(self.pool.iter_mut()) {
3434 worker.force_full_page_ocr = force;
3435 worker.replace_broken_text_layer = replace;
3436 worker.ocr_scale = scale;
3437 worker.set_textline_orientation(orient);
3438 }
3439 }
3440
3441 /// Pixels per PDF point for picture crops and page images — docling's
3442 /// `images_scale` (#519/#520). `None` (the default) delivers crops at the
3443 /// pipeline's own page render, 2.0 px/pt (144 dpi), untouched. Another
3444 /// value resamples that render (CatmullRom, docling's PIL BICUBIC), so
3445 /// values above 2.0 upsample rather than re-render. Each picture's
3446 /// `dpi` (docling-core's `ImageRef.dpi`) is 72·scale, so consumers mapping
3447 /// pixels back to points stay exact. Layout, OCR and TableFormer inputs
3448 /// are unaffected. Non-positive values are ignored.
3449 pub fn images_scale(mut self, scale: Option<f32>) -> Self {
3450 self.set_images(ImageOutput {
3451 scale,
3452 ..self.images
3453 });
3454 self
3455 }
3456
3457 /// Keep each page's render as the document's page image — docling's
3458 /// `generate_page_images` (#520): the JSON export writes it as the page's
3459 /// `image` (docling-core's `PageItem.image`, at [`Self::images_scale`],
3460 /// `dpi` = 72·scale), which is what docling-core's
3461 /// `TableItem.get_image` / `FormulaItem.get_image` crop from. Off by
3462 /// default: a page image is a full-page PNG per page held in memory.
3463 /// Pages converted with `no_ocr` (text layer only) are never rendered and
3464 /// get none; streaming conversions carry no page map and drop them.
3465 pub fn generate_page_images(mut self, enabled: bool) -> Self {
3466 self.set_images(ImageOutput {
3467 page_images: enabled,
3468 ..self.images
3469 });
3470 self
3471 }
3472
3473 /// Use a picture's embedded image instead of the render crop when its
3474 /// region holds exactly one image XObject with nothing painted over it —
3475 /// docling's `use_embedded_picture_images` (#1007, docling#5143). The
3476 /// bitmap keeps its native pixel size and the picture's `dpi` is 72; a
3477 /// masked, transparent, clipped, rotated or overlapped image, a second
3478 /// image or text in the box, a `/Rotate`d page or an image that does not
3479 /// decode keep the crop. Off by default; layout, OCR and page images are
3480 /// unaffected.
3481 pub fn use_embedded_picture_images(mut self, enabled: bool) -> Self {
3482 self.set_images(ImageOutput {
3483 embedded_pictures: enabled,
3484 ..self.images
3485 });
3486 self
3487 }
3488
3489 /// Both image outputs at once, also on already-loaded workers — the
3490 /// per-request form a warm pipeline (serve, the Node `Pipeline`) uses,
3491 /// like [`set_ocr_scale`](Self::set_ocr_scale). A non-finite or
3492 /// non-positive scale reads as unset.
3493 pub fn set_images(&mut self, images: ImageOutput) {
3494 self.images = ImageOutput {
3495 scale: images.scale.filter(|s| s.is_finite() && *s > 0.0),
3496 ..images
3497 };
3498 let images = self.images;
3499 for worker in self.primary.iter_mut().chain(self.pool.iter_mut()) {
3500 worker.images = images;
3501 }
3502 }
3503
3504 /// OCR render scale in pixels per PDF point — docling's `OcrOptions.scale`
3505 /// (#254, upstream docling#3877; their default 3 = 216 dpi). `None`
3506 /// (default: `DOCLING_RS_OCR_SCALE`, else unset) feeds the recognizer the
3507 /// pipeline's own page render (2.0 px/pt = 144 dpi) for a rendered page,
3508 /// and for a standalone image input docling's own resolution (#570): 3
3509 /// px/pt shrunk so the longer side stays within RapidOCR's 2000 px — what
3510 /// its models see after RapidOCR's `max_side_len` pass (a 754 × 1000 scan
3511 /// reads at 2.0). A set value resamples the render / image for the OCR
3512 /// input only — layout and TableFormer keep their pinned-resolution
3513 /// pixels, so the conformance baseline never moves. Lower it when the
3514 /// source raster is already high-resolution and upscaling degrades
3515 /// recognition; raise it toward docling's 216 dpi for parity experiments.
3516 /// Non-positive values are ignored.
3517 pub fn ocr_scale(mut self, scale: Option<f32>) -> Self {
3518 self.ocr_scale = scale
3519 .filter(|s| s.is_finite() && *s > 0.0)
3520 .or_else(ocr::scale_from_env);
3521 self
3522 }
3523
3524 /// Keep typographic punctuation as drawn — `„ “ ‚ ‘`, dashes, `…` —
3525 /// instead of folding it to ASCII as docling-parse's sanitizer does
3526 /// (`pdf_keep_typography`, #921). `None` keeps
3527 /// `DOCLING_RS_PDF_KEEP_TYPOGRAPHY`, else folding.
3528 pub fn set_keep_typography(&mut self, keep: Option<bool>) {
3529 self.keep_typography = keep;
3530 }
3531
3532 /// See [`set_keep_typography`](Self::set_keep_typography).
3533 pub fn keep_typography(mut self, keep: Option<bool>) -> Self {
3534 self.keep_typography = keep;
3535 self
3536 }
3537
3538 /// The text-layer settings the page walk applies.
3539 fn text_options(&self) -> pdfium_backend::TextOptions {
3540 pdfium_backend::TextOptions {
3541 word_gap: self.word_gap,
3542 keep_typography: self
3543 .keep_typography
3544 .unwrap_or_else(assemble::keep_typography_from_env),
3545 embedded_pictures: self.images.embedded_pictures,
3546 }
3547 }
3548
3549 /// See [`set_word_gap`](Self::set_word_gap).
3550 pub fn word_gap(mut self, gap: Option<WordGap>) -> Self {
3551 self.word_gap = gap;
3552 self
3553 }
3554
3555 /// The shared TableFormer slot handed to each worker, or `None` when the
3556 /// pipeline options skip TableFormer entirely.
3557 fn tables_slot(&self) -> Option<SharedTables> {
3558 if self.no_table_former || self.no_ocr {
3559 None
3560 } else {
3561 Some(Arc::clone(&self.tables))
3562 }
3563 }
3564
3565 /// The shared enrichment slots for a worker (`None` per model unless its
3566 /// flag is on; `no_ocr` skips layout, so there are no regions to enrich).
3567 fn enrich_slots(&self) -> (Option<SharedClassifier>, Option<SharedCodeFormula>) {
3568 if self.no_ocr || !self.enrich.any() {
3569 return (None, None);
3570 }
3571 (
3572 self.enrich
3573 .picture_classification
3574 .then(|| Arc::clone(&self.classifier)),
3575 (self.enrich.code || self.enrich.formula).then(|| Arc::clone(&self.code_formula)),
3576 )
3577 }
3578
3579 /// Eagerly load the models (the full-intra serial worker: layout + OCR, and
3580 /// the shared TableFormer unless disabled) so the first conversion doesn't pay
3581 /// the load cost. Idempotent; respects `no_ocr` / `no_table_former` (with
3582 /// `no_ocr` there is nothing to load). The docling.rs analogue of docling's
3583 /// `DocumentConverter.initialize_pipeline`.
3584 pub fn warm_up(&mut self) -> Result<(), PdfError> {
3585 self.primary()?;
3586 // The shared TableFormer loads on the first table otherwise — a
3587 // document with one would still pay for it (#548).
3588 if let Some(tables) = self.tables_slot() {
3589 tables.lock().unwrap_or_else(|p| p.into_inner()).load();
3590 }
3591 Ok(())
3592 }
3593
3594 /// [`warm_up`](Self::warm_up) plus the parallel page-worker pool, so the
3595 /// first *multi-page* conversion is no slower than later ones either: a
3596 /// document of `DOCLING_RS_PDF_PARALLEL_MIN` pages (6) or more fans out across the pool,
3597 /// whose workers each load their own layout/OCR sessions on first use
3598 /// (#548 — docling-serve's `--warmup` left a 9-page PDF paying that load).
3599 /// Costs the pool's memory up front (~0.4 GB a worker); with a pool of one
3600 /// worker it is exactly `warm_up`.
3601 pub fn warm_up_all(&mut self) -> Result<(), PdfError> {
3602 self.warm_up()?;
3603 if self.target_workers >= 2 {
3604 self.ensure_pool()?;
3605 }
3606 Ok(())
3607 }
3608
3609 /// The full-intra serial worker, loaded on first use.
3610 fn primary(&mut self) -> Result<&mut Worker, PdfError> {
3611 if self.primary.is_none() {
3612 self.primary = Some(Worker::load(
3613 intra_threads(),
3614 self.tables_slot(),
3615 Arc::clone(&self.det),
3616 self.enrich_slots(),
3617 self.enrich,
3618 self.no_ocr,
3619 self.skip_ocr,
3620 // The mode-shaped spelling (#254) and the flag are one engine
3621 // truth: whichever demands forcing wins, mirroring docling's
3622 // `force_full_page_ocr` → `mode=full_page` bridge.
3623 self.force_full_page_ocr || self.ocr_mode.forces_full_page(),
3624 self.no_text_panels,
3625 self.ocr_lang,
3626 self.ocr_engine,
3627 self.tesseract_lang.clone(),
3628 self.ocr_scale,
3629 self.textline_orientation,
3630 self.images,
3631 )?);
3632 if let Some(w) = self.primary.as_mut() {
3633 w.replace_broken_text_layer = self.replace_broken_text_layer;
3634 }
3635 }
3636 Ok(self.primary.as_mut().unwrap())
3637 }
3638
3639 /// Convert a PDF (bytes) to a [`DoclingDocument`]. A document with fewer than
3640 /// `parallel_min` pages (or a pool size of 1) streams through the full-intra
3641 /// primary; a larger one renders on this thread (pdfium is not thread-safe) and
3642 /// fans the pages out across the worker pool, reassembled in page order so the
3643 /// output is byte-identical to the serial path.
3644 pub fn convert(
3645 &mut self,
3646 bytes: &[u8],
3647 password: Option<&str>,
3648 name: &str,
3649 ) -> Result<DoclingDocument, PdfError> {
3650 self.convert_outcome(bytes, password, name)
3651 .map(|c| c.document)
3652 }
3653
3654 /// [`convert`](Self::convert) that also says how the conversion ended —
3655 /// whether the [`document_timeout`](Self::document_timeout) cut it short
3656 /// and how many pages made it (`Completion`).
3657 pub fn convert_outcome(
3658 &mut self,
3659 bytes: &[u8],
3660 password: Option<&str>,
3661 name: &str,
3662 ) -> Result<Converted, PdfError> {
3663 let deadline = self.deadline();
3664 let pages = pdfium_backend::page_count(bytes, password)?;
3665 let range = self.resolve_range(pages)?;
3666 // Serial vs parallel is decided by the pages actually converted: a
3667 // 3-page window over a 500-page PDF should not pay the pool load.
3668 let selected = range.map_or(pages, |(a, b)| b - a + 1);
3669 let (document, done, timed_out) = if self.text_only_for(bytes, password)? {
3670 self.convert_text_only(bytes, password, name, range, selected, deadline)?
3671 } else if self.target_workers >= 2 && selected >= self.parallel_min {
3672 self.convert_parallel(bytes, password, name, range, selected, deadline)?
3673 } else {
3674 self.convert_serial(bytes, password, name, range, selected, deadline)?
3675 };
3676 timing::report();
3677 Ok(Converted {
3678 document,
3679 completion: self.completion(timed_out, done, selected),
3680 })
3681 }
3682
3683 /// Whether this document converts from its text layer alone: always
3684 /// under [`no_ocr`](Self::no_ocr); under
3685 /// [`text_layer_auto`](Self::text_layer_auto), when the layer carries
3686 /// the text ([`text_layer_has_text`]). Decided before any worker — and
3687 /// so any model — is touched.
3688 fn text_only_for(&self, bytes: &[u8], password: Option<&str>) -> Result<bool, PdfError> {
3689 if self.no_ocr {
3690 return Ok(true);
3691 }
3692 if !self.text_layer_auto {
3693 return Ok(false);
3694 }
3695 let has_text = text_layer_has_text(bytes, password)?;
3696 docling_core::debug_log!(
3697 "text_layer_only=auto: {}",
3698 if has_text {
3699 "the text layer carries the document, converting it alone"
3700 } else {
3701 "no usable text layer, running the full pipeline"
3702 }
3703 );
3704 Ok(has_text)
3705 }
3706
3707 /// The text layer alone, page by page — no worker, no model, no page
3708 /// bitmap: [`text_only_page`] on each extracted page, in order. The path
3709 /// of [`no_ocr`](Self::no_ocr) and of an [`auto`](Self::text_layer_auto)
3710 /// document with text; byte-identical to the serial walk, since the
3711 /// worker's `no_ocr` branch is the same function.
3712 fn convert_text_only(
3713 &mut self,
3714 bytes: &[u8],
3715 password: Option<&str>,
3716 name: &str,
3717 range: Option<(usize, usize)>,
3718 selected: usize,
3719 deadline: Option<std::time::Instant>,
3720 ) -> Result<(DoclingDocument, usize, bool), PdfError> {
3721 let mut doc = DoclingDocument::new(name);
3722 let mut confs = std::collections::BTreeMap::new();
3723 let images = self.images;
3724 let progress = self.progress.clone();
3725 let mut done = 0usize;
3726 let timed_out = Self::render_ahead(
3727 bytes,
3728 password,
3729 false,
3730 pdfium_backend::BitmapRender::Eager,
3731 true,
3732 range,
3733 deadline,
3734 self.text_options(),
3735 |n, page| {
3736 let (mut nodes, links, conf) = text_only_page(&page, images.scale);
3737 assemble::stamp_page_no(&mut nodes, n + 1);
3738 if let Some(img) = page_image_under(images, n, &page) {
3739 doc.page_images.insert(n + 1, img);
3740 }
3741 doc.nodes.extend(nodes);
3742 doc.links.extend(links);
3743 confs.insert(n + 1, conf);
3744 done += 1;
3745 if let Some(cb) = &progress {
3746 cb(PageProgress {
3747 page_no: n + 1,
3748 pages_done: done,
3749 pages_selected: selected,
3750 });
3751 }
3752 Ok(())
3753 },
3754 )?;
3755 assemble::merge_continuations(&mut doc.nodes, assemble::Continuations::Lines);
3756 self.apply_heading_hierarchy(&mut doc.nodes, Some(bytes));
3757 self.apply_script_positions(&mut doc.nodes, bytes);
3758 doc.confidence = Some(docling_core::ConfidenceReport::from_pages(confs));
3759 Ok((doc, done, timed_out))
3760 }
3761
3762 /// Stream pages one at a time through the primary worker — render → process →
3763 /// drop — so the document holds ~one page bitmap (~5 MB) at a time.
3764 fn convert_serial(
3765 &mut self,
3766 bytes: &[u8],
3767 password: Option<&str>,
3768 name: &str,
3769 range: Option<(usize, usize)>,
3770 selected: usize,
3771 deadline: Option<std::time::Instant>,
3772 ) -> Result<(DoclingDocument, usize, bool), PdfError> {
3773 let mut doc = DoclingDocument::new(name);
3774 let mut confs = std::collections::BTreeMap::new();
3775 let mut ocr_cells_by_page = std::collections::BTreeMap::new();
3776 let render_image = !self.no_ocr;
3777 let bitmap = self.bitmap_render();
3778 let extract_text = self.extract_text_layer();
3779 let progress = self.progress.clone();
3780 let mut done = 0usize;
3781 let text = self.text_options();
3782 let worker = self.primary()?;
3783 let timed_out = Self::render_ahead(
3784 bytes,
3785 password,
3786 render_image,
3787 bitmap,
3788 extract_text,
3789 range,
3790 deadline,
3791 text,
3792 |n, mut page| {
3793 let (mut nodes, links, conf, page_image, ocr_cells) =
3794 worker.process(n, &mut page)?;
3795 assemble::stamp_page_no(&mut nodes, n + 1);
3796 if let Some(img) = page_image {
3797 doc.page_images.insert(n + 1, img);
3798 }
3799 doc.nodes.extend(nodes);
3800 doc.links.extend(links);
3801 confs.insert(n + 1, conf);
3802 ocr_cells_by_page.insert(n + 1, ocr_cells);
3803 done += 1;
3804 if let Some(cb) = &progress {
3805 cb(PageProgress {
3806 page_no: n + 1,
3807 pages_done: done,
3808 pages_selected: selected,
3809 });
3810 }
3811 Ok(())
3812 },
3813 )?;
3814 assemble::merge_continuations(&mut doc.nodes, assemble::Continuations::AcrossPages);
3815 self.apply_heading_hierarchy(&mut doc.nodes, Some(bytes));
3816 self.apply_script_positions(&mut doc.nodes, bytes);
3817 doc.confidence = Some(confidence_report(confs, ocr_cells_by_page));
3818 Ok((doc, done, timed_out))
3819 }
3820
3821 /// The serial path's schedule (#682): pages render on a scoped thread
3822 /// and queue through a [`RENDER_AHEAD`]-page channel while the primary
3823 /// worker processes the previous one on the calling thread, so a page's
3824 /// two rasters (about a third of a digital page's cost) hide behind
3825 /// layout and TableFormer instead of preceding them — the render-ahead
3826 /// the worker pool always had, for documents too small for the pool.
3827 /// One consumer, pages in order: the output is byte-identical to the
3828 /// sequential walk. `consume` runs on the calling thread (a streaming
3829 /// `emit` need not be `Send`). A spent budget (#497) ends the walk at
3830 /// the renderer and the consumer alike; a consumer error closes the
3831 /// channel, which stops the renderer, and is the one reported.
3832 #[allow(clippy::too_many_arguments)]
3833 fn render_ahead<F>(
3834 bytes: &[u8],
3835 password: Option<&str>,
3836 render_image: bool,
3837 bitmap: pdfium_backend::BitmapRender,
3838 extract_text: bool,
3839 range: Option<(usize, usize)>,
3840 deadline: Option<std::time::Instant>,
3841 text: pdfium_backend::TextOptions,
3842 mut consume: F,
3843 ) -> Result<bool, PdfError>
3844 where
3845 F: FnMut(usize, PdfPage) -> Result<(), PdfError>,
3846 {
3847 let (tx, rx) = sync_channel::<(usize, PdfPage)>(RENDER_AHEAD);
3848 std::thread::scope(|s| {
3849 let render = s.spawn(move || {
3850 pdfium_backend::walk_pages(
3851 bytes,
3852 password,
3853 render_image,
3854 extract_text,
3855 range,
3856 bitmap,
3857 text,
3858 |n, _total, page| {
3859 if expired(deadline) {
3860 return Err(timeout_sentinel());
3861 }
3862 tx.send((n, page))
3863 .map_err(|_| PdfError::Pdfium("page channel closed".into()))
3864 },
3865 )
3866 });
3867 let mut timed_out = false;
3868 let mut failed = None;
3869 for (n, page) in rx.iter() {
3870 if expired(deadline) {
3871 timed_out = true;
3872 break;
3873 }
3874 if let Err(e) = consume(n, page) {
3875 failed = Some(e);
3876 break;
3877 }
3878 }
3879 // Closing the channel ends a walk still rendering.
3880 drop(rx);
3881 let walk = render
3882 .join()
3883 .map_err(|_| PdfError::Pdfium("page render thread panicked".into()))?;
3884 if let Some(e) = failed {
3885 return Err(e);
3886 }
3887 match walk {
3888 Ok(()) => Ok(timed_out),
3889 Err(PdfError::Timeout(_)) => Ok(true),
3890 Err(_) if timed_out => Ok(true),
3891 Err(e) => Err(e),
3892 }
3893 })
3894 }
3895
3896 /// Render pages serially on this thread (pdfium) and process them in parallel
3897 /// across the worker pool. A bounded channel applies backpressure so only a
3898 /// handful of page bitmaps are resident at once; results carry their page
3899 /// index and are reassembled in order, so the output is byte-identical to the
3900 /// serial path.
3901 fn convert_parallel(
3902 &mut self,
3903 bytes: &[u8],
3904 password: Option<&str>,
3905 name: &str,
3906 range: Option<(usize, usize)>,
3907 selected: usize,
3908 deadline: Option<std::time::Instant>,
3909 ) -> Result<(DoclingDocument, usize, bool), PdfError> {
3910 let text = self.text_options();
3911 self.ensure_pool_for(selected)?;
3912 let progress = self.progress.clone();
3913 let pages_done = std::sync::atomic::AtomicUsize::new(0);
3914 let timed_out = std::sync::atomic::AtomicBool::new(false);
3915 let n_workers = self.pool.len();
3916 let render_image = !self.no_ocr;
3917 let bitmap = self.bitmap_render();
3918 let extract_text = self.extract_text_layer();
3919 let layout_batch = pdf_layout_batch();
3920 // Bound sized so every worker can accumulate a full layout batch while
3921 // rendering stays ahead (and never below the pre-#73 render-ahead of
3922 // two pages per worker); still a hard cap on resident page bitmaps.
3923 let (work_tx, work_rx) = sync_channel::<(usize, PdfPage)>(n_workers * layout_batch.max(2));
3924 let work_rx: Arc<Mutex<Receiver<(usize, PdfPage)>>> = Arc::new(Mutex::new(work_rx));
3925 let results: Arc<Mutex<Vec<(usize, PageOut)>>> = Arc::new(Mutex::new(Vec::new()));
3926 let first_err: Arc<Mutex<Option<PdfError>>> = Arc::new(Mutex::new(None));
3927
3928 // Move the pool into the scope so each worker gets an exclusive `&mut`.
3929 let mut workers = std::mem::take(&mut self.pool);
3930 std::thread::scope(|s| {
3931 for worker in workers.iter_mut() {
3932 let work_rx = Arc::clone(&work_rx);
3933 let results = Arc::clone(&results);
3934 let first_err = Arc::clone(&first_err);
3935 let progress = progress.clone();
3936 let pages_done = &pages_done;
3937 let timed_out = &timed_out;
3938 s.spawn(move || {
3939 worker.run_pool(&work_rx, layout_batch, deadline, |idx, out| {
3940 match out {
3941 Ok(out) => {
3942 results.lock().unwrap().push((idx, out));
3943 let d = pages_done
3944 .fetch_add(1, std::sync::atomic::Ordering::Relaxed)
3945 + 1;
3946 if let Some(cb) = &progress {
3947 cb(PageProgress {
3948 page_no: idx + 1,
3949 pages_done: d,
3950 pages_selected: selected,
3951 });
3952 }
3953 }
3954 // The budget ran out before this page's turn: the
3955 // page is left out, the document is partial.
3956 Err(PdfError::Timeout(_)) => {
3957 timed_out.store(true, std::sync::atomic::Ordering::Relaxed);
3958 }
3959 Err(e) => {
3960 let mut slot = first_err.lock().unwrap();
3961 if slot.is_none() {
3962 *slot = Some(e);
3963 }
3964 }
3965 }
3966 true
3967 });
3968 });
3969 }
3970 // Render on this thread and feed the workers; backpressure blocks here
3971 // when the channel is full. Dropping `work_tx` afterwards signals the
3972 // workers (recv → Err) to finish. A spent budget ends the walk before
3973 // the next page is rendered.
3974 let render = pdfium_backend::walk_pages(
3975 bytes,
3976 password,
3977 render_image,
3978 extract_text,
3979 range,
3980 bitmap,
3981 text,
3982 |i, _total, page| {
3983 if expired(deadline) {
3984 return Err(timeout_sentinel());
3985 }
3986 work_tx
3987 .send((i, page))
3988 .map_err(|_| PdfError::Pdfium("page-worker channel closed".into()))
3989 },
3990 );
3991 drop(work_tx);
3992 match render {
3993 Ok(()) => {}
3994 Err(PdfError::Timeout(_)) => {
3995 timed_out.store(true, std::sync::atomic::Ordering::Relaxed);
3996 }
3997 Err(e) => {
3998 let mut slot = first_err.lock().unwrap();
3999 if slot.is_none() {
4000 *slot = Some(e);
4001 }
4002 }
4003 }
4004 });
4005 // Threads have joined; restore the pool for the next conversion.
4006 self.pool = workers;
4007
4008 if let Some(e) = first_err.lock().unwrap().take() {
4009 return Err(e);
4010 }
4011 let mut results = Arc::try_unwrap(results)
4012 .unwrap_or_else(|arc| Mutex::new(arc.lock().unwrap().clone()))
4013 .into_inner()
4014 .unwrap();
4015 results.sort_by_key(|(idx, _)| *idx);
4016 let done = results.len();
4017 let mut doc = DoclingDocument::new(name);
4018 let mut confs = std::collections::BTreeMap::new();
4019 let mut ocr_cells_by_page = std::collections::BTreeMap::new();
4020 for (idx, (mut nodes, links, conf, page_image, ocr_cells)) in results {
4021 assemble::stamp_page_no(&mut nodes, idx + 1);
4022 if let Some(img) = page_image {
4023 doc.page_images.insert(idx + 1, img);
4024 }
4025 doc.nodes.extend(nodes);
4026 doc.links.extend(links);
4027 confs.insert(idx + 1, conf);
4028 ocr_cells_by_page.insert(idx + 1, ocr_cells);
4029 }
4030 assemble::merge_continuations(&mut doc.nodes, assemble::Continuations::AcrossPages);
4031 self.apply_heading_hierarchy(&mut doc.nodes, Some(bytes));
4032 self.apply_script_positions(&mut doc.nodes, bytes);
4033 doc.confidence = Some(confidence_report(confs, ocr_cells_by_page));
4034 let timed_out = timed_out.load(std::sync::atomic::Ordering::Relaxed);
4035 Ok((doc, done, timed_out))
4036 }
4037
4038 /// Convert a PDF in **streaming** mode: `emit` is called with each finalized,
4039 /// in-document-order batch of nodes (and that span's recovered links) as pages
4040 /// complete, so a caller can serialize Markdown page by page instead of waiting
4041 /// for the whole document. The batches are exactly the buffered [`convert`]'s
4042 /// nodes, split at safe block boundaries by [`assemble::StreamAssembler`] — the
4043 /// parallel path reorders pages back into document order before emitting, so
4044 /// the output is identical regardless of worker scheduling.
4045 ///
4046 /// `emit` runs on the calling thread (never a worker), so it needn't be `Send`
4047 /// and its backpressure throttles the whole pipeline. Returning `Err` from
4048 /// `emit` aborts the conversion with that error.
4049 pub fn convert_streaming<F>(
4050 &mut self,
4051 bytes: &[u8],
4052 password: Option<&str>,
4053 name: &str,
4054 emit: F,
4055 ) -> Result<(), PdfError>
4056 where
4057 F: FnMut(Vec<Node>, Vec<(String, String)>) -> Result<(), PdfError>,
4058 {
4059 self.convert_streaming_outcome(bytes, password, name, emit)
4060 .map(|_| ())
4061 }
4062
4063 /// [`convert_streaming`](Self::convert_streaming) that also says how the
4064 /// conversion ended ([`Completion`]): a spent
4065 /// [`document_timeout`](Self::document_timeout) stops the walk, the pages
4066 /// finished so far are emitted (the tail included) and the outcome is
4067 /// `TimedOut` — never an error.
4068 pub fn convert_streaming_outcome<F>(
4069 &mut self,
4070 bytes: &[u8],
4071 password: Option<&str>,
4072 name: &str,
4073 emit: F,
4074 ) -> Result<Completion, PdfError>
4075 where
4076 F: FnMut(Vec<Node>, Vec<(String, String)>) -> Result<(), PdfError>,
4077 {
4078 let _ = name; // page nodes carry no name; the caller owns the document name.
4079 let deadline = self.deadline();
4080 let pages = pdfium_backend::page_count(bytes, password)?;
4081 let range = self.resolve_range(pages)?;
4082 let selected = range.map_or(pages, |(a, b)| b - a + 1);
4083 let r = if self.text_only_for(bytes, password)? {
4084 self.convert_streaming_text_only(bytes, password, range, deadline, selected, emit)
4085 } else if self.target_workers >= 2 && selected >= self.parallel_min {
4086 self.convert_streaming_parallel(bytes, password, range, deadline, selected, emit)
4087 } else {
4088 self.convert_streaming_serial(bytes, password, range, deadline, selected, emit)
4089 };
4090 timing::report();
4091 let (done, timed_out) = r?;
4092 Ok(self.completion(timed_out, done, selected))
4093 }
4094
4095 /// Streaming from the text layer alone ([`convert_text_only`](Self::convert_text_only)'s
4096 /// emitting twin): extract → [`text_only_page`] → emit, one page at a
4097 /// time, holding back only the tail that might still merge into the next
4098 /// page. No worker, no model, no bitmap.
4099 fn convert_streaming_text_only<F>(
4100 &mut self,
4101 bytes: &[u8],
4102 password: Option<&str>,
4103 range: Option<(usize, usize)>,
4104 deadline: Option<std::time::Instant>,
4105 selected: usize,
4106 mut emit: F,
4107 ) -> Result<(usize, bool), PdfError>
4108 where
4109 F: FnMut(Vec<Node>, Vec<(String, String)>) -> Result<(), PdfError>,
4110 {
4111 let mut asm = assemble::StreamAssembler::new(assemble::Continuations::Lines);
4112 let images = self.images;
4113 let progress = self.progress.clone();
4114 let mut done = 0usize;
4115 let timed_out = Self::render_ahead(
4116 bytes,
4117 password,
4118 false,
4119 pdfium_backend::BitmapRender::Eager,
4120 true,
4121 range,
4122 deadline,
4123 self.text_options(),
4124 |n, page| {
4125 let (nodes, links, _conf) = text_only_page(&page, images.scale);
4126 done += 1;
4127 if let Some(cb) = &progress {
4128 cb(PageProgress {
4129 page_no: n + 1,
4130 pages_done: done,
4131 pages_selected: selected,
4132 });
4133 }
4134 emit(asm.push(nodes), links)
4135 },
4136 )?;
4137 emit(asm.finish(), Vec::new())?;
4138 Ok((done, timed_out))
4139 }
4140
4141 /// Serial streaming: render → process → emit, one page at a time, holding back
4142 /// only the tail that might still merge into the next page.
4143 fn convert_streaming_serial<F>(
4144 &mut self,
4145 bytes: &[u8],
4146 password: Option<&str>,
4147 range: Option<(usize, usize)>,
4148 deadline: Option<std::time::Instant>,
4149 selected: usize,
4150 mut emit: F,
4151 ) -> Result<(usize, bool), PdfError>
4152 where
4153 F: FnMut(Vec<Node>, Vec<(String, String)>) -> Result<(), PdfError>,
4154 {
4155 let mut asm = assemble::StreamAssembler::new(assemble::Continuations::AcrossPages);
4156 let render_image = !self.no_ocr;
4157 let bitmap = self.bitmap_render();
4158 let extract_text = self.extract_text_layer();
4159 let progress = self.progress.clone();
4160 let text = self.text_options();
4161 let worker = self.primary()?;
4162 let mut done = 0usize;
4163 let timed_out = Self::render_ahead(
4164 bytes,
4165 password,
4166 render_image,
4167 bitmap,
4168 extract_text,
4169 range,
4170 deadline,
4171 text,
4172 |n, mut page| {
4173 // Confidence is dropped on the streaming path: the report is
4174 // only complete once every page has run, which defeats
4175 // page-by-page emission — buffered `convert` carries it.
4176 let (nodes, links, _conf, _page_image, _cells) = worker.process(n, &mut page)?;
4177 done += 1;
4178 if let Some(cb) = &progress {
4179 cb(PageProgress {
4180 page_no: n + 1,
4181 pages_done: done,
4182 pages_selected: selected,
4183 });
4184 }
4185 emit(asm.push(nodes), links)
4186 },
4187 )?;
4188 emit(asm.finish(), Vec::new())?;
4189 Ok((done, timed_out))
4190 }
4191
4192 /// Parallel streaming: pages render serially on a dedicated thread (pdfium is
4193 /// not thread-safe) and process across the worker pool; results carry their
4194 /// page index and are reordered on the calling thread into a
4195 /// [`assemble::StreamAssembler`], which emits each page in document order as
4196 /// soon as its predecessors have arrived. Bounded channels keep only a handful
4197 /// of pages resident and let `emit`'s backpressure reach the renderer.
4198 fn convert_streaming_parallel<F>(
4199 &mut self,
4200 bytes: &[u8],
4201 password: Option<&str>,
4202 range: Option<(usize, usize)>,
4203 deadline: Option<std::time::Instant>,
4204 selected: usize,
4205 mut emit: F,
4206 ) -> Result<(usize, bool), PdfError>
4207 where
4208 F: FnMut(Vec<Node>, Vec<(String, String)>) -> Result<(), PdfError>,
4209 {
4210 let text = self.text_options();
4211 self.ensure_pool_for(selected)?;
4212 let n_workers = self.pool.len();
4213 let render_image = !self.no_ocr;
4214 let bitmap = self.bitmap_render();
4215 let extract_text = self.extract_text_layer();
4216 let progress = self.progress.clone();
4217 let layout_batch = pdf_layout_batch();
4218 // Bound sized so every worker can accumulate a full layout batch while
4219 // rendering stays ahead (and never below the pre-#73 render-ahead of
4220 // two pages per worker); still a hard cap on resident page bitmaps.
4221 let (work_tx, work_rx) = sync_channel::<(usize, PdfPage)>(n_workers * layout_batch.max(2));
4222 let work_rx: Arc<Mutex<Receiver<(usize, PdfPage)>>> = Arc::new(Mutex::new(work_rx));
4223 // Workers and the renderer report here; the calling thread drains it in
4224 // page order. Bounded so workers block (bounding resident bitmaps) when the
4225 // consumer falls behind.
4226 let (res_tx, res_rx) = sync_channel::<Result<(usize, PageOut), PdfError>>(n_workers * 2);
4227
4228 let mut workers = std::mem::take(&mut self.pool);
4229 let mut asm = assemble::StreamAssembler::new(assemble::Continuations::AcrossPages);
4230 let mut first_err: Option<PdfError> = None;
4231 let mut timed_out = false;
4232 let mut done = 0usize;
4233
4234 std::thread::scope(|s| {
4235 // Workers: pull a batch of pages (whatever is already rendered, up
4236 // to the layout batch size), process it, report (index-tagged)
4237 // results.
4238 for worker in workers.iter_mut() {
4239 let work_rx = Arc::clone(&work_rx);
4240 let res_tx = res_tx.clone();
4241 s.spawn(move || {
4242 worker.run_pool(&work_rx, layout_batch, deadline, |idx, out| {
4243 // `false` once the consumer is gone.
4244 res_tx.send(out.map(|o| (idx, o))).is_ok()
4245 });
4246 });
4247 }
4248 // Renderer: feed pages to the pool on its own thread (pdfium stays on a
4249 // single thread); report a render error through the same channel. A
4250 // spent budget ends the walk before the next page is rendered.
4251 {
4252 let res_tx = res_tx.clone();
4253 s.spawn(move || {
4254 let render = pdfium_backend::walk_pages(
4255 bytes,
4256 password,
4257 render_image,
4258 extract_text,
4259 range,
4260 bitmap,
4261 text,
4262 |i, _total, page| {
4263 if expired(deadline) {
4264 return Err(timeout_sentinel());
4265 }
4266 work_tx
4267 .send((i, page))
4268 .map_err(|_| PdfError::Pdfium("page-worker channel closed".into()))
4269 },
4270 );
4271 drop(work_tx); // signal workers to finish
4272 if let Err(e) = render {
4273 let _ = res_tx.send(Err(e));
4274 }
4275 });
4276 }
4277 // Drop our own sender so the channel closes once the threads finish.
4278 drop(res_tx);
4279
4280 // Collector (this thread): reorder into document order and emit.
4281 // With a page window, indices start at the window's first page.
4282 // A timed-out page leaves a hole in the sequence: everything
4283 // before it emits in order, the pages after it stay buffered —
4284 // they are the pages the budget did not cover, and the document
4285 // ends at the cut like the buffered path's.
4286 let mut buffer: BTreeMap<usize, PageOut> = BTreeMap::new();
4287 let mut next = range.map_or(0, |(first, _)| first);
4288 for msg in res_rx.iter() {
4289 match msg {
4290 Err(PdfError::Timeout(_)) => timed_out = true,
4291 Err(e) => {
4292 if first_err.is_none() {
4293 first_err = Some(e);
4294 }
4295 }
4296 Ok((idx, out)) => {
4297 buffer.insert(idx, out);
4298 if first_err.is_some() {
4299 continue; // keep draining so the threads can exit
4300 }
4301 // A stream carries Markdown, not the page map: page
4302 // images (#520) have nowhere to go and are dropped.
4303 while let Some((nodes, links, _conf, _page_image, _cells)) =
4304 buffer.remove(&next)
4305 {
4306 if let Err(e) = emit(asm.push(nodes), links) {
4307 first_err = Some(e);
4308 break;
4309 }
4310 next += 1;
4311 done += 1;
4312 // Reported in document order, as emitted: a page
4313 // that finished early counts once it is emitted.
4314 if let Some(cb) = &progress {
4315 cb(PageProgress {
4316 page_no: next,
4317 pages_done: done,
4318 pages_selected: selected,
4319 });
4320 }
4321 }
4322 }
4323 }
4324 }
4325 // Pages that finished after a hole (a page the budget skipped
4326 // before them) cannot follow it in document order; count them
4327 // out of the document like the skipped one.
4328 if timed_out && !buffer.is_empty() {
4329 buffer.clear();
4330 }
4331 });
4332 // Threads have joined; restore the pool for the next conversion.
4333 self.pool = workers;
4334
4335 if let Some(e) = first_err {
4336 return Err(e);
4337 }
4338 emit(asm.finish(), Vec::new())?;
4339 Ok((done, timed_out))
4340 }
4341
4342 /// Lazily grow the pool to `target_workers`, loading the new workers
4343 /// concurrently (model load is mostly I/O + mmap, so N loads overlap to roughly
4344 /// one load's wall-time). Cached for reuse across documents.
4345 fn ensure_pool(&mut self) -> Result<(), PdfError> {
4346 self.ensure_pool_for(self.target_workers)
4347 }
4348
4349 /// [`ensure_pool`](Self::ensure_pool) for a document of `pages` pages:
4350 /// no more workers than pages (#682 — a two-page document on a 16-core
4351 /// host loads two workers, not eight), never fewer than two, and never
4352 /// more than `target_workers`; a later, longer document grows the pool.
4353 fn ensure_pool_for(&mut self, pages: usize) -> Result<(), PdfError> {
4354 let want = pages.max(2).min(self.target_workers);
4355 let need = want.saturating_sub(self.pool.len());
4356 if need == 0 {
4357 return Ok(());
4358 }
4359 let intra = pdf_intra();
4360 let no_ocr = self.no_ocr;
4361 let skip_ocr = self.skip_ocr;
4362 let force = self.force_full_page_ocr || self.ocr_mode.forces_full_page();
4363 let ntp = self.no_text_panels;
4364 let ocr_lang = self.ocr_lang;
4365 let ocr_engine = self.ocr_engine;
4366 let tesseract_lang = self.tesseract_lang.clone();
4367 let ocr_scale = self.ocr_scale;
4368 let textline_orientation = self.textline_orientation;
4369 let images = self.images;
4370 let enrich = self.enrich;
4371 let tables = self.tables_slot();
4372 let det = Arc::clone(&self.det);
4373 let enrich_slots = self.enrich_slots();
4374 let loaded: Vec<Result<Worker, PdfError>> = std::thread::scope(|s| {
4375 let handles: Vec<_> = (0..need)
4376 .map(|_| {
4377 let tables = tables.clone();
4378 let det = Arc::clone(&det);
4379 let enrich_slots = enrich_slots.clone();
4380 let tesseract_lang = tesseract_lang.clone();
4381 s.spawn(move || {
4382 Worker::load(
4383 intra,
4384 tables,
4385 det,
4386 enrich_slots,
4387 enrich,
4388 no_ocr,
4389 skip_ocr,
4390 force,
4391 ntp,
4392 ocr_lang,
4393 ocr_engine,
4394 tesseract_lang,
4395 ocr_scale,
4396 textline_orientation,
4397 images,
4398 )
4399 })
4400 })
4401 .collect();
4402 handles.into_iter().map(|h| h.join().unwrap()).collect()
4403 });
4404 for w in loaded {
4405 let mut w = w?;
4406 w.replace_broken_text_layer = self.replace_broken_text_layer;
4407 self.pool.push(w);
4408 }
4409 Ok(())
4410 }
4411
4412 /// Convert a standalone image (PNG/JPEG/TIFF/WebP/…) as a single page —
4413 /// docling routes images through the same layout+OCR pipeline as a PDF page.
4414 pub fn convert_image(&mut self, bytes: &[u8], name: &str) -> Result<DoclingDocument, PdfError> {
4415 let image = decode_image_limited(bytes)?;
4416 let (w, h) = image.dimensions();
4417 // The image is its own page rendered at 1 px per "point" (scale 1.0); a
4418 // standalone image has no text layer, so OCR supplies the cells.
4419 let page = PdfPage {
4420 width: w as f32,
4421 height: h as f32,
4422 scale: 1.0,
4423 cells: Vec::new(),
4424 code_cells: Vec::new(),
4425 checkboxes: Vec::new(),
4426 bitmaps: Vec::new(),
4427 shapes: Default::default(),
4428 word_cells: Vec::new(),
4429 // A standalone image *is* its own scale-1.0 page image, so the
4430 // layout model sees it through the docling-exact PIL kernel.
4431 image_layout: Some(image.clone()),
4432 image,
4433 links: Vec::new(),
4434 rotation: 0,
4435 keep_typography: false,
4436 #[cfg(feature = "render")]
4437 embedded_images: Vec::new(),
4438 pending_image: None,
4439 };
4440 let mut doc = self.process_pages(vec![page], name)?;
4441 // docling sizes the page from the file's resolution (#1093); the
4442 // models above ran on the file's own pixels, which only the page unit
4443 // changes, so the text and the reading order cannot move.
4444 let (dpi_x, dpi_y) = image_page_dpi(bytes, (w, h));
4445 if (dpi_x, dpi_y) != (72.0, 72.0) {
4446 doc.rescale_page_units((72.0 / dpi_x) as f32, (72.0 / dpi_y) as f32);
4447 }
4448 Ok(doc)
4449 }
4450
4451 /// Run layout (+ OCR for cell-less pages) and assemble each already-rendered
4452 /// page (image / METS inputs, which are small and already materialised).
4453 /// Public so [`mets::convert_mets_gbs_with_pipeline`] can drive a
4454 /// caller-configured pipeline (#244).
4455 pub fn process_pages(
4456 &mut self,
4457 mut pages: Vec<PdfPage>,
4458 name: &str,
4459 ) -> Result<DoclingDocument, PdfError> {
4460 let mut doc = DoclingDocument::new(name);
4461 let mut confs = std::collections::BTreeMap::new();
4462 let mut ocr_cells_by_page = std::collections::BTreeMap::new();
4463 let progress = self.progress.clone();
4464 let total = pages.len();
4465 let worker = self.primary()?;
4466 for (n, page) in pages.iter_mut().enumerate() {
4467 let (mut nodes, links, conf, page_image, ocr_cells) = worker.process(n, page)?;
4468 assemble::stamp_page_no(&mut nodes, n + 1);
4469 if let Some(img) = page_image {
4470 doc.page_images.insert(n + 1, img);
4471 }
4472 doc.nodes.extend(nodes);
4473 doc.links.extend(links);
4474 confs.insert(n + 1, conf);
4475 ocr_cells_by_page.insert(n + 1, ocr_cells);
4476 if let Some(cb) = &progress {
4477 cb(PageProgress {
4478 page_no: n + 1,
4479 pages_done: n + 1,
4480 pages_selected: total,
4481 });
4482 }
4483 }
4484 assemble::merge_continuations(&mut doc.nodes, assemble::Continuations::AcrossPages);
4485 // No PDF behind these pages (images, METS): the heading-hierarchy
4486 // stage degrades to the numbering signal — exactly docling without
4487 // an outline or parsed pages.
4488 self.apply_heading_hierarchy(&mut doc.nodes, None);
4489 doc.confidence = Some(confidence_report(confs, ocr_cells_by_page));
4490 Ok(doc)
4491 }
4492}
4493
4494/// Number of pages in a PDF, without converting anything — what the CLI batch
4495/// mode prints in its per-document start line.
4496#[cfg(feature = "ml")]
4497pub fn page_count(bytes: &[u8], password: Option<&str>) -> Result<usize, PdfError> {
4498 pdfium_backend::page_count(bytes, password)
4499}
4500
4501#[cfg(feature = "ml")]
4502/// Convenience one-shot conversion (loads the pipeline per call). Errors are
4503/// detailed and surfaced (never silently skipped).
4504pub fn convert(
4505 bytes: &[u8],
4506 password: Option<&str>,
4507 name: &str,
4508) -> Result<DoclingDocument, PdfError> {
4509 convert_with_options(
4510 bytes,
4511 password,
4512 name,
4513 false,
4514 false,
4515 false,
4516 false,
4517 EnrichmentOptions::default(),
4518 None,
4519 None,
4520 )
4521}
4522
4523#[cfg(feature = "ml")]
4524/// Like [`convert`], but optionally skips loading/running TableFormer (see
4525/// [`Pipeline::no_table_former`]) and/or layout+OCR+TableFormer entirely (see
4526/// [`Pipeline::no_ocr`]), and/or enables the enrichment passes (see
4527/// [`Pipeline::enrichments`]).
4528// One positional per pipeline switch mirrors the Pipeline builder; growing
4529// past clippy's arity cap is the price of keeping this one-shot signature
4530// stable-ish instead of churning callers into an options struct mid-series.
4531#[allow(clippy::too_many_arguments)]
4532pub fn convert_with_options(
4533 bytes: &[u8],
4534 password: Option<&str>,
4535 name: &str,
4536 no_table_former: bool,
4537 no_ocr: bool,
4538 force_full_page_ocr: bool,
4539 no_text_panels: bool,
4540 enrich: EnrichmentOptions,
4541 pages: Option<(usize, usize)>,
4542 ocr_lang: Option<OcrLang>,
4543) -> Result<DoclingDocument, PdfError> {
4544 Pipeline::new()?
4545 .no_table_former(no_table_former)
4546 .no_ocr(no_ocr)
4547 .force_full_page_ocr(force_full_page_ocr)
4548 .no_text_panels(no_text_panels)
4549 .enrichments(enrich)
4550 .pages(pages)
4551 .ocr_lang(ocr_lang)
4552 .convert(bytes, password, name)
4553}
4554
4555#[cfg(feature = "ml")]
4556/// Convenience one-shot image conversion (loads the pipeline per call).
4557pub fn convert_image(bytes: &[u8], name: &str) -> Result<DoclingDocument, PdfError> {
4558 convert_image_with_options(
4559 bytes,
4560 name,
4561 false,
4562 false,
4563 false,
4564 EnrichmentOptions::default(),
4565 None,
4566 )
4567}
4568
4569#[cfg(feature = "ml")]
4570/// Like [`convert_image`], but optionally skips loading/running TableFormer (see
4571/// [`Pipeline::no_table_former`]) and/or layout+OCR+TableFormer entirely (see
4572/// [`Pipeline::no_ocr`]), and/or enables the enrichment passes.
4573pub fn convert_image_with_options(
4574 bytes: &[u8],
4575 name: &str,
4576 no_table_former: bool,
4577 no_ocr: bool,
4578 no_text_panels: bool,
4579 enrich: EnrichmentOptions,
4580 ocr_lang: Option<OcrLang>,
4581) -> Result<DoclingDocument, PdfError> {
4582 Pipeline::new()?
4583 .no_table_former(no_table_former)
4584 .no_ocr(no_ocr)
4585 .no_text_panels(no_text_panels)
4586 .enrichments(enrich)
4587 .ocr_lang(ocr_lang)
4588 .convert_image(bytes, name)
4589}
4590
4591#[cfg(feature = "ml")]
4592/// Convert pre-segmented pages (image + already-known text cells, e.g. METS/hOCR
4593/// scans) through the shared layout + assembly pipeline.
4594pub fn convert_pages(pages: Vec<PdfPage>, name: &str) -> Result<DoclingDocument, PdfError> {
4595 convert_pages_with_options(
4596 pages,
4597 name,
4598 false,
4599 false,
4600 false,
4601 EnrichmentOptions::default(),
4602 )
4603}
4604
4605#[cfg(feature = "ml")]
4606/// Like [`convert_pages`], but optionally skips loading/running TableFormer (see
4607/// [`Pipeline::no_table_former`]) and/or layout+OCR+TableFormer entirely (see
4608/// [`Pipeline::no_ocr`]), and/or enables the enrichment passes.
4609pub fn convert_pages_with_options(
4610 pages: Vec<PdfPage>,
4611 name: &str,
4612 no_table_former: bool,
4613 no_ocr: bool,
4614 no_text_panels: bool,
4615 enrich: EnrichmentOptions,
4616) -> Result<DoclingDocument, PdfError> {
4617 Pipeline::new()?
4618 .no_table_former(no_table_former)
4619 .no_text_panels(no_text_panels)
4620 .no_ocr(no_ocr)
4621 .enrichments(enrich)
4622 .process_pages(pages, name)
4623}
4624
4625#[cfg(feature = "ml")]
4626#[cfg(all(test, feature = "ml"))]
4627mod image_limit_tests {
4628 use super::decode_image_with_max_side;
4629
4630 /// A small valid PNG encoded via the `image` crate (robust vs. a hand-rolled
4631 /// byte literal).
4632 fn png_bytes(w: u32, h: u32) -> Vec<u8> {
4633 use std::io::Cursor;
4634 let img = image::RgbImage::new(w, h);
4635 let mut out = Vec::new();
4636 img.write_to(&mut Cursor::new(&mut out), image::ImageFormat::Png)
4637 .unwrap();
4638 out
4639 }
4640
4641 #[test]
4642 fn normal_image_decodes_under_the_cap() {
4643 let img = decode_image_with_max_side(&png_bytes(8, 8), 30_000).expect("8x8 decodes");
4644 assert_eq!(img.dimensions(), (8, 8));
4645 }
4646
4647 /// docling#4247 (2.128): the EXIF orientation is applied when a frame is
4648 /// loaded — a 4×2 JPEG tagged "rotate 90° CW" (orientation 6) decodes as
4649 /// 2×4, with the pixels turned.
4650 #[test]
4651 fn exif_orientation_is_applied() {
4652 use std::io::Cursor;
4653 let mut img = image::RgbImage::new(4, 2);
4654 img.put_pixel(0, 0, image::Rgb([255, 0, 0]));
4655 let mut jpeg = Vec::new();
4656 img.write_to(&mut Cursor::new(&mut jpeg), image::ImageFormat::Jpeg)
4657 .unwrap();
4658 // Splice an APP1 Exif segment (little-endian TIFF, one IFD entry:
4659 // Orientation = 6) right after the SOI marker.
4660 let mut tiff = b"II*\0".to_vec();
4661 tiff.extend(8u32.to_le_bytes());
4662 tiff.extend(1u16.to_le_bytes());
4663 tiff.extend(0x0112u16.to_le_bytes());
4664 tiff.extend(3u16.to_le_bytes());
4665 tiff.extend(1u32.to_le_bytes());
4666 tiff.extend(6u16.to_le_bytes());
4667 tiff.extend([0, 0]);
4668 tiff.extend(0u32.to_le_bytes());
4669 let mut app1 = b"Exif\0\0".to_vec();
4670 app1.extend(tiff);
4671 let mut out = jpeg[..2].to_vec();
4672 out.extend([0xff, 0xe1]);
4673 out.extend((app1.len() as u16 + 2).to_be_bytes());
4674 out.extend(app1);
4675 out.extend(&jpeg[2..]);
4676 let plain = decode_image_with_max_side(&jpeg, 30_000).unwrap();
4677 assert_eq!(plain.dimensions(), (4, 2));
4678 let turned = decode_image_with_max_side(&out, 30_000).unwrap();
4679 assert_eq!(turned.dimensions(), (2, 4), "quarter turn swaps the sides");
4680 // Rotating 90° CW moves the top-left pixel to the top-right corner.
4681 assert!(turned.get_pixel(1, 0).0[0] > 128);
4682 assert!(turned.get_pixel(0, 0).0[0] <= 128);
4683 }
4684
4685 #[test]
4686 fn dimensions_over_the_cap_are_rejected_not_aborted() {
4687 // A per-side cap below the image's declared size must yield a
4688 // recoverable Err, never an allocation-abort — the mechanism that stops
4689 // a crafted image declaring 60000×60000 from OOM-killing the process.
4690 let r = decode_image_with_max_side(&png_bytes(8, 8), 4);
4691 assert!(
4692 r.is_err(),
4693 "decode must fail under the pixel cap, not abort"
4694 );
4695 }
4696}
4697
4698#[cfg(all(test, feature = "ml"))]
4699mod image_page_dpi_tests {
4700 use super::{decode_image_with_max_side, image_page_dpi};
4701 use image::codecs::jpeg::{JpegEncoder, PixelDensity, PixelDensityUnit};
4702
4703 /// A 4 × 2 JPEG whose JFIF records `density`, tagged with EXIF
4704 /// `orientation` when given.
4705 fn jpeg(density: PixelDensity, orientation: Option<u16>) -> Vec<u8> {
4706 let img = image::RgbImage::new(4, 2);
4707 let mut out = Vec::new();
4708 let mut enc = JpegEncoder::new(&mut out);
4709 enc.set_pixel_density(density);
4710 enc.encode_image(&img).unwrap();
4711 let Some(o) = orientation else {
4712 return out;
4713 };
4714 // An APP1 Exif segment (little-endian TIFF, one IFD entry:
4715 // Orientation) right after SOI; the JFIF density stays authoritative.
4716 let mut app1 = b"Exif\0\0II*\0".to_vec();
4717 app1.extend(8u32.to_le_bytes());
4718 app1.extend(1u16.to_le_bytes());
4719 app1.extend(0x0112u16.to_le_bytes());
4720 app1.extend(3u16.to_le_bytes());
4721 app1.extend(1u32.to_le_bytes());
4722 app1.extend(o.to_le_bytes());
4723 app1.extend([0, 0, 0, 0, 0, 0]);
4724 let mut spliced = out[..2].to_vec();
4725 spliced.extend([0xff, 0xe1]);
4726 spliced.extend((app1.len() as u16 + 2).to_be_bytes());
4727 spliced.extend(app1);
4728 spliced.extend(&out[2..]);
4729 spliced
4730 }
4731
4732 fn dpi_of(bytes: &[u8]) -> (f64, f64) {
4733 let decoded = decode_image_with_max_side(bytes, 30_000).unwrap();
4734 image_page_dpi(bytes, decoded.dimensions())
4735 }
4736
4737 /// docling's `_get_frame_dpi`: each axis's resolution as Pillow reads it;
4738 /// none, `(1, 1)` and `(0, 0)` read as 72.
4739 #[test]
4740 fn the_page_takes_the_files_resolution() {
4741 let anisotropic = PixelDensity {
4742 density: (300, 150),
4743 unit: PixelDensityUnit::Inches,
4744 };
4745 assert_eq!(dpi_of(&jpeg(anisotropic, None)), (300.0, 150.0));
4746 assert_eq!(dpi_of(&jpeg(PixelDensity::default(), None)), (72.0, 72.0));
4747 assert_eq!(dpi_of(&jpeg(PixelDensity::dpi(1), None)), (72.0, 72.0));
4748 assert_eq!(dpi_of(&jpeg(PixelDensity::dpi(0), None)), (72.0, 72.0));
4749 }
4750
4751 /// docling's `_oriented_frame`: a quarter-turn EXIF orientation swaps the
4752 /// frame's sides, and the resolution's axes with them; a half turn does
4753 /// not.
4754 #[test]
4755 fn a_quarter_turn_swaps_the_axes() {
4756 let anisotropic = PixelDensity {
4757 density: (300, 150),
4758 unit: PixelDensityUnit::Inches,
4759 };
4760 assert_eq!(dpi_of(&jpeg(anisotropic, Some(6))), (150.0, 300.0));
4761 assert_eq!(dpi_of(&jpeg(anisotropic, Some(3))), (300.0, 150.0));
4762 }
4763}
4764
4765#[cfg(all(test, feature = "ml"))]
4766mod ocr_scale_tests {
4767 use super::*;
4768
4769 /// #570: an explicit scale wins everywhere; a rendered page keeps its
4770 /// render; a scale-1.0 image page reads at docling's 3 px/pt, shrunk to
4771 /// RapidOCR's 2000 px longer side (a FUNSD scan at 2.0, a 3000 px photo
4772 /// downsampled to 0.67), and an image that lands at 1.0 is not resampled.
4773 #[test]
4774 fn image_inputs_follow_rapidocrs_resolution() {
4775 assert_eq!(page_ocr_scale(Some(1.5), 754.0, 1000.0, 1.0), Some(1.5));
4776 assert_eq!(page_ocr_scale(None, 612.0, 792.0, 2.0), None);
4777 assert_eq!(page_ocr_scale(None, 754.0, 1000.0, 1.0), Some(2.0));
4778 assert_eq!(page_ocr_scale(None, 400.0, 600.0, 1.0), Some(3.0));
4779 let s = page_ocr_scale(None, 3000.0, 2000.0, 1.0).unwrap();
4780 assert!((s - 2.0 / 3.0).abs() < 1e-6, "{s}");
4781 assert_eq!(page_ocr_scale(None, 2000.0, 1500.0, 1.0), None);
4782 }
4783}
4784
4785#[cfg(test)]
4786mod median_tests {
4787 #[test]
4788 fn median_of_empty_is_zero_not_a_panic() {
4789 // A crafted table can leave a row/column with zero matched cells; the
4790 // even-count branch would index values[0 - 1] and panic (→ remote crash
4791 // via docling-serve) without the empty guard.
4792 assert_eq!(super::tf_match::median_for_test(&mut []), 0.0);
4793 assert_eq!(super::tf_match::median_for_test(&mut [4.0, 2.0]), 3.0);
4794 assert_eq!(super::tf_match::median_for_test(&mut [5.0, 1.0, 3.0]), 3.0);
4795 }
4796}
4797
4798#[cfg(test)]
4799mod unreadable_tests {
4800 /// The text-layer path (the wasm build's only one) tells a file nothing
4801 /// can open apart from a PDF that merely has no text layer: garbage is
4802 /// an error about the file, a real PDF converts.
4803 #[test]
4804 fn text_layer_path_reports_an_unreadable_file() {
4805 for bytes in [b"garbage".as_slice(), b"", b"%PDF-1.7\n%%EOF\n"] {
4806 let err = super::convert_text_layer(bytes, "x.pdf").unwrap_err();
4807 assert!(err.to_string().contains("not a readable PDF"), "{err}");
4808 }
4809 let real = std::fs::read(
4810 std::path::Path::new(env!("CARGO_MANIFEST_DIR"))
4811 .join("../../tests/data/pdf/sources/multi_page.pdf"),
4812 )
4813 .unwrap();
4814 assert!(!super::convert_text_layer(&real, "multi_page.pdf")
4815 .unwrap()
4816 .nodes
4817 .is_empty());
4818 }
4819}
4820
4821#[cfg(test)]
4822mod send_check {
4823 /// The Node bindings (`docling-node`) run a shared [`super::Pipeline`] on
4824 /// libuv worker threads (`Arc<Mutex<Pipeline>>`), which is only sound while
4825 /// `Pipeline: Send` holds — this fails to compile if a non-`Send` field
4826 /// (e.g. an `Rc` or a raw pdfium handle) ever lands in the pipeline.
4827 fn assert_send<T: Send>() {}
4828
4829 #[test]
4830 fn pipeline_is_send() {
4831 assert_send::<super::Pipeline>();
4832 }
4833}
4834
4835#[cfg(all(test, feature = "ml"))]
4836mod ocr_input_tests {
4837 /// #254: without an `ocr_scale` (or with one equal to the render scale)
4838 /// the OCR reads the page render untouched and the cache stays cold; a
4839 /// different scale builds one resampled view, reuses it across calls, and
4840 /// reports the requested px/pt so cell geometry divides back to points.
4841 #[test]
4842 fn ocr_input_resamples_only_on_a_real_scale_change() {
4843 let img = image::RgbImage::new(200, 100);
4844 let mut cache = None;
4845 let (v, s) = super::ocr_input(&mut cache, &img, 2.0, None);
4846 assert!(std::ptr::eq(v, &img) && s == 2.0 && cache.is_none());
4847 let (v, s) = super::ocr_input(&mut cache, &img, 2.0, Some(2.0));
4848 assert!(std::ptr::eq(v, &img) && s == 2.0 && cache.is_none());
4849
4850 let (v, s) = super::ocr_input(&mut cache, &img, 2.0, Some(3.0));
4851 assert_eq!((v.width(), v.height(), s), (300, 150, 3.0));
4852 let first = cache.as_ref().map(|c| c as *const image::RgbImage);
4853 let (v, _) = super::ocr_input(&mut cache, &img, 2.0, Some(3.0));
4854 assert_eq!(
4855 Some(v as *const image::RgbImage),
4856 first,
4857 "cached, not rebuilt"
4858 );
4859
4860 let mut down = None;
4861 let (v, s) = super::ocr_input(&mut down, &img, 2.0, Some(1.0));
4862 assert_eq!((v.width(), v.height(), s), (100, 50, 1.0));
4863 }
4864}
4865
4866#[cfg(all(test, feature = "ml"))]
4867mod text_layer_auto_tests {
4868 use std::path::Path;
4869
4870 fn fixture(rel: &str) -> Vec<u8> {
4871 std::fs::read(
4872 Path::new(env!("CARGO_MANIFEST_DIR"))
4873 .join("../..")
4874 .join(rel),
4875 )
4876 .unwrap()
4877 }
4878
4879 /// The verdict behind `text_layer_only=auto`: a digital PDF's layer
4880 /// carries it, a scan's does not, and garbage is the file's error.
4881 #[test]
4882 fn text_layer_verdict_tells_digital_from_scanned() {
4883 let digital = fixture("tests/data/pdf/sources/multi_page.pdf");
4884 assert!(super::text_layer_has_text(&digital, None).unwrap());
4885 let scanned = fixture("tests/data/scanned/sources/ocr_test_raster.pdf");
4886 assert!(!super::text_layer_has_text(&scanned, None).unwrap());
4887 let err = super::text_layer_has_text(b"garbage", None).unwrap_err();
4888 assert!(err.to_string().contains("not a readable PDF"), "{err}");
4889 }
4890
4891 /// On a digital PDF `auto` is the `no_ocr` path byte for byte — the
4892 /// buffered and the streaming conversion alike — and touches no model:
4893 /// the pipeline below has none to load (`Pipeline::new` loads lazily),
4894 /// so a conversion that reached a worker would fail.
4895 #[test]
4896 fn auto_on_a_digital_pdf_is_the_text_layer_path() {
4897 let bytes = fixture("tests/data/pdf/sources/multi_page.pdf");
4898 let mut only = super::Pipeline::new().unwrap().no_ocr(true);
4899 let mut auto = super::Pipeline::new().unwrap().text_layer_auto(true);
4900 let a = only.convert(&bytes, None, "multi_page.pdf").unwrap();
4901 let b = auto.convert(&bytes, None, "multi_page.pdf").unwrap();
4902 assert!(!a.nodes.is_empty());
4903 assert_eq!(a.export_to_markdown(), b.export_to_markdown());
4904 assert_eq!(a.confidence, b.confidence);
4905 let streamed = |p: &mut super::Pipeline| {
4906 let mut nodes = Vec::new();
4907 p.convert_streaming(&bytes, None, "multi_page.pdf", |page, _| {
4908 nodes.extend(page);
4909 Ok(())
4910 })
4911 .unwrap();
4912 nodes
4913 };
4914 assert_eq!(streamed(&mut only), streamed(&mut auto));
4915 }
4916}
4917
4918#[cfg(all(test, feature = "ml"))]
4919mod bitmap_region_tests {
4920 use super::{bitmap_regions, layout::Region, TextCell};
4921
4922 fn region(label: &'static str, l: f32, t: f32, r: f32, b: f32) -> Region {
4923 Region {
4924 label,
4925 score: 1.0,
4926 l,
4927 t,
4928 r,
4929 b,
4930 }
4931 }
4932
4933 fn cell(text: &str, l: f32, t: f32, r: f32, b: f32) -> TextCell {
4934 TextCell {
4935 text: text.into(),
4936 l,
4937 t,
4938 r,
4939 b,
4940 }
4941 }
4942
4943 const PAGE: [f32; 4] = [0.0, 0.0, 612.0, 792.0];
4944
4945 /// #999: a scanned table with one typed-in value is OCR'd; a text-less
4946 /// region is left to `text_less_regions`; a page without a bitmap, or a
4947 /// region the scan barely touches, is not.
4948 #[test]
4949 fn a_scan_under_a_thin_layer_is_read() {
4950 let table = region("table", 100.0, 300.0, 500.0, 500.0);
4951 let blank = region("text", 100.0, 100.0, 500.0, 120.0);
4952 let cells = [cell("420", 226.0, 444.0, 251.0, 458.0)];
4953 let got = bitmap_regions(&[table.clone(), blank], &cells, &[PAGE]);
4954 assert_eq!(got.len(), 1);
4955 assert_eq!((got[0].label, got[0].t), ("table", 300.0));
4956 assert!(bitmap_regions(std::slice::from_ref(&table), &cells, &[]).is_empty());
4957 // A logo over a corner of the region: not half of it.
4958 let logo = [450.0, 290.0, 520.0, 340.0];
4959 assert!(bitmap_regions(&[table], &cells, &[logo]).is_empty());
4960 }
4961
4962 /// A searchable scan — an invisible layer over the page image — keeps
4963 /// its text layer: a one-line region is a thin band any text explains,
4964 /// a paragraph is covered well past a tenth of its area.
4965 #[test]
4966 fn a_searchable_scan_keeps_its_text_layer() {
4967 let line = region("text", 72.0, 100.0, 540.0, 114.0);
4968 let para = region("text", 72.0, 200.0, 540.0, 260.0);
4969 let cells: Vec<TextCell> = std::iter::once(cell("Heading", 72.0, 100.0, 300.0, 114.0))
4970 .chain((0..4).map(|i| {
4971 let t = 200.0 + 15.0 * i as f32;
4972 cell("body text", 72.0, t, 540.0, t + 12.0)
4973 }))
4974 .collect();
4975 assert!(bitmap_regions(&[line, para], &cells, &[PAGE]).is_empty());
4976 }
4977}