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