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