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