Skip to main content

docling_pdf/
lib.rs

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