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