Skip to main content

docling_pdf/
pdfium_backend.rs

1//! The page walk of the PDF pipeline: per page, the geometry and links from
2//! the object model (`pdf_meta`), the text layer from the pure-Rust parser
3//! (`textparse`), the model-input bitmaps from the docling-parse renderer
4//! plugin, the Rust raster or the Rust page renderer — and, behind the
5//! `pdfium` feature, the pdfium library for `DOCLING_RS_RENDERER=pdfium`
6//! (docling's pypdfium2 chain) and for a file lopdf cannot read ([`native`]).
7//! The module keeps its historical name; every type in it is pdfium-free.
8
9#[cfg(feature = "render")]
10use crate::PdfError;
11#[cfg(feature = "ocr-prep")]
12use image::RgbImage;
13
14/// A run of text with its bounding box, in PDF points with a **top-left** origin
15/// (pdfium's native origin is bottom-left; we flip it to match docling's
16/// `BoundingBox(..., origin=TOPLEFT)`).
17#[derive(Debug, Clone)]
18pub struct TextCell {
19    pub text: String,
20    pub l: f32,
21    pub t: f32,
22    pub r: f32,
23    pub b: f32,
24}
25
26/// Pixels-per-point used to render page images. Layout is scale-invariant (it
27/// scales normalized boxes by the page point size), but OCR benefits from the
28/// extra resolution.
29pub const RENDER_SCALE: f32 = 2.0;
30
31/// One page's geometry, extracted text cells, and a rendered RGB image. The
32/// image is rendered at [`RENDER_SCALE`] pixels per PDF point; `image px =
33/// page point × scale`.
34#[derive(Clone)]
35pub struct PdfPage {
36    pub width: f32,
37    pub height: f32,
38    pub scale: f32,
39    pub cells: Vec<TextCell>,
40    /// Same text grouped for code regions: split only at pdfium space glyphs, so
41    /// monospace runs keep their source spacing instead of the prose heuristic's.
42    pub code_cells: Vec<TextCell>,
43    /// Per-word cells (one per word, not joined into lines) for TableFormer cell
44    /// matching.
45    pub word_cells: Vec<TextCell>,
46    /// Checkbox squares drawn on the page (#609): assembly gives each line
47    /// with one in front of it its own checkbox item. Empty without a text
48    /// layer (OCR pages) or vector paths.
49    pub checkboxes: Vec<crate::checkbox::CheckBox>,
50    /// The rendered page bitmap. Present whenever pixels are available at all
51    /// (`ocr-prep` ⊂ `ml`): the native pipeline renders it with pdfium, the
52    /// browser pipeline receives it from the host canvas. Picture regions are
53    /// cropped out of it.
54    #[cfg(feature = "ocr-prep")]
55    pub image: RgbImage,
56    /// The **scale-1.0** page image the layout model runs on (parity with
57    /// docling's `PyPdfiumDocumentBackend`: the layout stage calls
58    /// `page.get_image(scale=1.0)`, which that backend serves as pdfium at
59    /// 1.5×, PIL-BICUBIC down to point size — a *different* image from the 2×
60    /// OCR/crop bitmap above, and a different resampling regime than
61    /// stretching that bitmap; docling 2.123+'s default docling-parse backend
62    /// renders the same request with its own Blend2D/FreeType renderer, whose
63    /// glyph anti-aliasing differs — #478). `None` on paths without a pdfium
64    /// renderer (browser, METS/TIFF), which fall back to stretching
65    /// [`Self::image`].
66    #[cfg(feature = "ocr-prep")]
67    pub image_layout: Option<RgbImage>,
68    /// The 2x bitmap of a page with a text layer, deferred to the page
69    /// walk's helper thread (#682): [`Self::image`] holds a 1×1 placeholder
70    /// until [`Self::resolve_image`] installs the render. The ML pipeline
71    /// resolves it after layout — the stage that reads
72    /// [`Self::image_layout`] instead — and only for a page whose detections
73    /// read the bitmap (tables, pictures, …; #897), so a text-only page never
74    /// draws it. `None` once resolved, and on every path that renders
75    /// synchronously (scanned pages, the plugin and pdfium renderers,
76    /// images, METS).
77    #[cfg(feature = "render")]
78    pub pending_image: Option<PendingImage>,
79    /// Hyperlink annotations on the page (rect in top-left page coords + target
80    /// URI), restricted to web/mail/tel schemes. Used only by strict Markdown.
81    pub links: Vec<LinkAnnot>,
82    /// The page's `/Rotate` value (0/90/180/270) when it was normalized away
83    /// before inference: a scanned page with `/Rotate` displays its raster
84    /// rotated, which turns OCR into garbage — so extraction un-rotates the
85    /// bitmaps (and swaps `width`/`height`) and records the display rotation
86    /// here. Assembly rotates the finished geometry *back* by this many
87    /// degrees clockwise, so emitted locations and the page size stay in
88    /// display space (matching docling and every PDF viewer). Always 0 for
89    /// text-layer pages (their cells live in display space already) and on
90    /// paths without a pdfium renderer.
91    pub rotation: u16,
92    /// Keep typographic punctuation as drawn — curly and low quotes, dashes,
93    /// `…`, `⁄`, `•` — instead of folding it to ASCII the way docling-parse's
94    /// sanitizer does (`pdf_keep_typography`, #921). Read by assembly.
95    pub keep_typography: bool,
96}
97
98impl PdfPage {
99    /// A page built from recognized cells alone — the browser pipeline's
100    /// shape (#157), where the bitmap lives on the JS side. Exists so callers
101    /// compile identically with and without the `ml` feature: under a
102    /// feature-unified workspace build the struct carries the `image` field,
103    /// which a plain literal in a non-`ml` consumer can't spell.
104    #[cfg(feature = "ocr-prep")]
105    pub fn from_cells(width: f32, height: f32, scale: f32, cells: Vec<TextCell>) -> Self {
106        Self {
107            width,
108            height,
109            scale,
110            cells,
111            code_cells: Vec::new(),
112            word_cells: Vec::new(),
113            checkboxes: Vec::new(),
114            #[cfg(feature = "ocr-prep")]
115            image: RgbImage::new(0, 0),
116            #[cfg(feature = "ocr-prep")]
117            image_layout: None,
118            #[cfg(feature = "render")]
119            pending_image: None,
120            links: Vec::new(),
121            rotation: 0,
122            keep_typography: false,
123        }
124    }
125
126    /// Wait for a deferred 2x render (#682) — starting it first when it was
127    /// left for on demand ([`BitmapRender::OnDemand`], #897) — and install it
128    /// as [`Self::image`]; a no-op when nothing is pending. The ML pipeline
129    /// calls it after layout for a page whose detections need the bitmap,
130    /// before anything reads it.
131    #[cfg(feature = "render")]
132    pub fn resolve_image(&mut self) -> Result<(), PdfError> {
133        if let Some(pending) = self.pending_image.take() {
134            self.image = crate::timing::timed("render.wait", || pending.wait())?;
135        }
136        Ok(())
137    }
138
139    /// Whether [`Self::image`] is still a placeholder for a deferred 2x
140    /// render ([`Self::resolve_image`] installs it).
141    #[cfg(feature = "render")]
142    pub fn image_pending(&self) -> bool {
143        self.pending_image.is_some()
144    }
145
146    /// Nothing is going to read this page's deferred 2x bitmap (#897): the
147    /// helper skips its render if it has not begun it. The page stays
148    /// pending — a later [`Self::resolve_image`] still gets the bitmap,
149    /// rendering it then if it was skipped.
150    #[cfg(feature = "render")]
151    pub fn decline_image(&self) {
152        if let Some(pending) = &self.pending_image {
153            pending.decline();
154        }
155    }
156
157    /// Same as [`from_cells`](Self::from_cells) but carrying the rendered page
158    /// bitmap, so picture regions can be cropped out of it (#157: the browser
159    /// pipeline gets the same figure bytes the native one does).
160    #[cfg(feature = "ocr-prep")]
161    pub fn from_cells_with_image(
162        width: f32,
163        height: f32,
164        scale: f32,
165        cells: Vec<TextCell>,
166        image: RgbImage,
167    ) -> Self {
168        Self {
169            image,
170            ..Self::from_cells(width, height, scale, cells)
171        }
172    }
173
174    /// Un-rotate the page's bitmaps by `deg` (clockwise 90° steps) and record
175    /// the compensating display rotation, composing with any rotation already
176    /// recorded: the raster becomes upright for inference while assembly
177    /// still maps the finished geometry back into display space. Handles both
178    /// `/Rotate` normalization (extraction) and content-detected orientation
179    /// (#225) — the two compose additively (axis-aligned 90° rotations
180    /// commute through the dimension swaps). Link rectangles follow the
181    /// raster; `width`/`height` swap on odd quarter-turns.
182    #[cfg(feature = "ocr-prep")]
183    pub(crate) fn unrotate(&mut self, deg: u16) {
184        if deg == 0 {
185            return;
186        }
187        use image::imageops::{rotate180, rotate270, rotate90};
188        // Display = upright rotated `deg`° clockwise, so upright = display
189        // rotated the complementary amount clockwise.
190        let un = |img: &RgbImage| match deg {
191            90 => rotate270(img),
192            180 => rotate180(img),
193            _ => rotate90(img),
194        };
195        if self.image.width() > 1 {
196            self.image = un(&self.image);
197        }
198        self.image_layout = self.image_layout.as_ref().map(&un);
199        let (width, height) = (self.width, self.height);
200        // Link rects follow the raster from display into upright space (the
201        // inverse of the geometry rotation assembly applies at the end).
202        for l in &mut self.links {
203            let (nl, nt, nr, nb) = match deg {
204                90 => (l.t, width - l.r, l.b, width - l.l),
205                180 => (width - l.r, height - l.b, width - l.l, height - l.t),
206                _ => (height - l.b, l.l, height - l.t, l.r),
207            };
208            (l.l, l.t, l.r, l.b) = (nl, nt, nr, nb);
209        }
210        // Checkbox squares likewise (a scan has none; kept consistent).
211        for c in &mut self.checkboxes {
212            let (nl, nt, nr, nb) = match deg {
213                90 => (c.t, width - c.r, c.b, width - c.l),
214                180 => (width - c.r, height - c.b, width - c.l, height - c.t),
215                _ => (height - c.b, c.l, height - c.t, c.r),
216            };
217            (c.l, c.t, c.r, c.b) = (nl, nt, nr, nb);
218        }
219        if deg != 180 {
220            (self.width, self.height) = (height, width);
221        }
222        self.rotation = (self.rotation + deg) % 360;
223    }
224}
225
226/// A PDF link annotation: its rectangle (top-left page coordinates, matching
227/// [`TextCell`]) and target URI.
228#[derive(Debug, Clone)]
229pub struct LinkAnnot {
230    pub l: f32,
231    pub t: f32,
232    pub r: f32,
233    pub b: f32,
234    pub uri: String,
235}
236
237#[cfg(feature = "render")]
238/// A parsed PDF: per-page text cells and page images.
239pub struct PdfDocument {
240    pub pages: Vec<PdfPage>,
241}
242
243#[cfg(feature = "render")]
244impl PdfDocument {
245    /// Parse a PDF from bytes, optionally decrypting with `password`.
246    ///
247    /// Note: this materialises **every** page's rendered bitmap in memory at
248    /// once. For large documents prefer [`for_each_page`], which streams.
249    pub fn open(bytes: &[u8], password: Option<&str>) -> Result<Self, PdfError> {
250        let mut pages = Vec::new();
251        for_each_page::<PdfError, _>(bytes, password, true, true, None, |_, _, mut page| {
252            // Every page's bitmap, as documented — not the placeholder of a
253            // render still on the helper thread (#682).
254            page.resolve_image()?;
255            pages.push(page);
256            Ok(())
257        })?;
258        Ok(PdfDocument { pages })
259    }
260}
261
262#[cfg(feature = "render")]
263/// The document's text layer: the pure-Rust text parser (docling-parse's
264/// char geometry; the only text source since phase 4 of "Retiring pdfium" —
265/// on the whole corpus every page it reads no text from is one pdfium read
266/// no text from either, i.e. a scan for the OCR path). `None` for a file
267/// lopdf cannot open at all.
268fn rust_parser_cells(
269    bytes: &[u8],
270    password: Option<&str>,
271    word_gap: Option<crate::dp_lines::WordGap>,
272) -> Option<crate::textparse::PageTextParser> {
273    // Only the document load happens here; pages are parsed as the walk
274    // reaches them (`cells_timed`), so nothing is decoded for pages outside
275    // a `--pages` window and the parse overlaps the workers' inference.
276    crate::timing::timed("textparse.open", || {
277        let mut parser = crate::textparse::PageTextParser::open_with_password(bytes, password)?;
278        parser.set_word_gap(word_gap);
279        Some(parser)
280    })
281}
282
283impl crate::textparse::PageTextParser {
284    /// [`cells`](Self::cells) under the `textparse` timing stage (per page).
285    fn cells_timed(&mut self, index: usize) -> crate::textparse::PageParserCells {
286        crate::timing::timed("textparse", || self.cells(index))
287    }
288}
289
290#[cfg(feature = "render")]
291/// Number of pages in a PDF, without rendering any of them — used to decide
292/// whether a document is worth spinning up the parallel worker pool.
293pub fn page_count(bytes: &[u8], password: Option<&str>) -> Result<usize, PdfError> {
294    // The pure-Rust object model first, then the docling-parse plugin's
295    // count, then pdfium (the `pdfium` feature) — the order every entry point
296    // here follows.
297    if let Some(meta) = crate::timing::timed("meta.open", || {
298        crate::pdf_meta::PdfMeta::open_with_password(bytes, password)
299    })? {
300        return Ok(meta.page_count());
301    }
302    if let Some(dp) = crate::dparse_render::Doc::open_if_enabled(bytes, password) {
303        return Ok(dp.page_count());
304    }
305    crate::timing::timed("pdfium.page_count", || {
306        let lib = native::bind()?;
307        let n = lib.open(bytes, password)?.page_count();
308        Ok(n)
309    })
310}
311
312#[cfg(feature = "render")]
313/// Render + extract pages one at a time, handing each (owned) [`PdfPage`] to `f`.
314/// Only one page bitmap is resident at a time — a rendered page is ~5 MB, so a
315/// large PDF would otherwise hold gigabytes of bitmaps at once. `f` receives the
316/// zero-based page index and the total page count.
317///
318/// `render_image` controls whether the page bitmap is rasterized at all: layout,
319/// OCR, TableFormer, and picture cropping all need it, but a caller that skips
320/// every one of those (the `no_ocr` fast path) doesn't, and rasterizing +
321/// downsampling a page is by far the most expensive step per page — skipping it
322/// is most of `no_ocr`'s speedup. `PdfPage::image` is a 1×1 placeholder when
323/// `false`; do not read it.
324///
325/// `extract_text` decodes the page's text layer (parser or pdfium cells); pass
326/// `false` when full-page OCR is forced and the cells would be discarded
327/// unread (docling#4061).
328///
329/// `range` restricts the walk to a **0-based inclusive** page window (issue
330/// #80's `--pages`); out-of-window pages are skipped *before* text extraction
331/// and rasterization, so a 3-page window over a 500-page PDF costs three
332/// pages, not five hundred. `f` still receives the absolute page index, so
333/// downstream page numbering refers to the source document.
334///
335/// `E` is the caller's error type; [`PdfError`]s convert into it via `From`.
336///
337/// A page with a text layer may arrive with its 2x bitmap still rendering
338/// (#682): call [`PdfPage::resolve_image`] before reading [`PdfPage::image`].
339/// The render starts as the page leaves the walk; [`walk_pages`] with
340/// [`BitmapRender::OnDemand`] starts it only when resolved (#897).
341pub fn for_each_page<E, F>(
342    bytes: &[u8],
343    password: Option<&str>,
344    render_image: bool,
345    extract_text: bool,
346    range: Option<(usize, usize)>,
347    f: F,
348) -> Result<(), E>
349where
350    E: From<PdfError>,
351    F: FnMut(usize, usize, PdfPage) -> Result<(), E>,
352{
353    walk_pages(
354        bytes,
355        password,
356        render_image,
357        extract_text,
358        range,
359        BitmapRender::Eager,
360        TextOptions::from_env(),
361        f,
362    )
363}
364
365#[cfg(feature = "render")]
366/// When the 2x bitmap of a page with a text layer is rendered.
367#[derive(Clone, Copy, Debug, PartialEq, Eq)]
368pub enum BitmapRender {
369    /// As soon as the page leaves the walk, on the helper thread while
370    /// layout runs (#682) — for a caller that reads every page's bitmap.
371    Eager,
372    /// Started like [`Self::Eager`] while the document's recent pages mostly
373    /// read their bitmap, left [`Self::OnDemand`] while they mostly do not
374    /// (#897). Layout reads the separate 1x render, and a page whose
375    /// detections hold no table, picture or other bitmap consumer never
376    /// needs the 2x one: on a paper with a figure or table on most pages
377    /// the render overlaps layout as before; on prose the wasted renders go.
378    /// A started render the page then declines ([`PdfPage::decline_image`])
379    /// is still skipped if the helper has not begun it.
380    Adaptive,
381    /// Only once [`PdfPage::resolve_image`] asks for it (#897): no render is
382    /// ever wasted, but a page that needs one waits for it after layout
383    /// instead of having it drawn meanwhile.
384    OnDemand,
385}
386
387/// The text layer's settings a page walk applies (#921): the word-gap rule
388/// of the line and word cells, and whether assembly keeps typographic
389/// punctuation as drawn ([`PdfPage::keep_typography`]).
390#[derive(Clone, Copy, Debug, Default, PartialEq)]
391pub struct TextOptions {
392    /// `None` = the process default (`DOCLING_RS_PDF_WORD_GAP`).
393    pub word_gap: Option<crate::dp_lines::WordGap>,
394    pub keep_typography: bool,
395}
396
397impl TextOptions {
398    /// The process defaults: `DOCLING_RS_PDF_WORD_GAP` and
399    /// `DOCLING_RS_PDF_KEEP_TYPOGRAPHY`.
400    pub fn from_env() -> Self {
401        Self {
402            word_gap: None,
403            keep_typography: crate::assemble::keep_typography_from_env(),
404        }
405    }
406}
407
408#[cfg(feature = "render")]
409/// [`for_each_page`] with the 2x bitmaps rendered as `bitmap` says, and the
410/// text layer's words split by `word_gap` (#921; `None` = the process
411/// default).
412#[allow(clippy::too_many_arguments)]
413pub fn walk_pages<E, F>(
414    bytes: &[u8],
415    password: Option<&str>,
416    render_image: bool,
417    extract_text: bool,
418    range: Option<(usize, usize)>,
419    bitmap: BitmapRender,
420    text: TextOptions,
421    mut f: F,
422) -> Result<(), E>
423where
424    E: From<PdfError>,
425    F: FnMut(usize, usize, PdfPage) -> Result<(), E>,
426{
427    // The pure-Rust object model: page count, geometry, `/Rotate`, links.
428    // `None` only for a file lopdf cannot read even after the parser's
429    // repairs; pdfium (the `pdfium` feature) then answers for it.
430    let meta = crate::timing::timed("meta.open", || {
431        crate::pdf_meta::PdfMeta::open_with_password(bytes, password)
432    })?;
433    // The docling-parse renderer (#478, `DOCLING_RS_RENDERER=docling-parse`):
434    // the page images the models see come from it when it is asked for.
435    let dparse = if render_image {
436        crate::dparse_render::Doc::open_if_enabled(bytes, password)
437    } else {
438        None
439    };
440    // pdfium, when it has a job (`bind_or_skip`).
441    let pdfium = bind_or_skip(meta.is_some())?;
442    let session = match &pdfium {
443        Some(p) => Some(p.open(bytes, password)?),
444        None => None,
445    };
446    // `extract_text = false` (full-page OCR forced, docling#4061 / 2.122):
447    // the text layer would be cleared unread, so neither the pure-Rust parser
448    // nor pdfium's text page is decoded at all — on vector-dense pages (CAD
449    // drawings as 100k+ path segments) that decode is most of the page cost.
450    let mut rust = if extract_text {
451        rust_parser_cells(bytes, password, text.word_gap)
452    } else {
453        None
454    };
455    // pdfium's count when it is loaded (a damaged file can make the two
456    // object models disagree, and pdfium's pages are the ones rendered), the
457    // object model's otherwise.
458    let total = match (&session, &meta) {
459        (Some(s), _) => s.page_count(),
460        (None, Some(m)) => m.page_count(),
461        (None, None) => 0,
462    };
463    // The object model's geometry and links are used whenever it read the same
464    // number of pages pdfium did (or pdfium is absent); a disagreeing file keeps
465    // pdfium's answers throughout.
466    //
467    // Shared, because the helper thread that renders the deferred 2x bitmaps
468    // (#682) outlives the walk: a page resolved on demand (#897) asks for its
469    // render after the walk has handed the last page over.
470    let meta = meta
471        .filter(|m| {
472            session
473                .as_ref()
474                .is_none_or(|s| s.page_count() == m.page_count())
475        })
476        .map(std::sync::Arc::new);
477    // The pure-Rust renderer (phase 3 of retiring pdfium): the model inputs
478    // of every page the plugin does not render and the Rust raster declines
479    // — the default renderer.
480    let renderer = match (&meta, render_image) {
481        (Some(m), true) => Some(crate::render::Renderer::new(m)),
482        _ => None,
483    };
484    let (first, last) = range.unwrap_or((0, total.saturating_sub(1)));
485    // The 2x bitmap of a page with a text layer renders on a helper thread
486    // (#682, `DeferredRender`) when the pure-Rust renderer is the only one
487    // drawing: the plugin and pdfium hold per-document handles the walk
488    // thread owns, so their pages render in place as before.
489    let defer = match (&meta, &renderer, &dparse, &session) {
490        (Some(m), Some(_), None, None) => DeferredRender::spawn(m.clone(), bitmap),
491        _ => None,
492    };
493    {
494        // Index the window directly: iterating pdfium's pages from page 0 and
495        // skipping to `first` would load (and close) every page before the
496        // window — ~0.7 ms each, 1.3 s of pure overhead for a one-page window
497        // over the 1913-page .NET reference.
498        for i in first..=last {
499            if i >= total {
500                break;
501            }
502            let page = match &session {
503                Some(s) => Some(s.page(i)?),
504                None => None,
505            };
506            let geom = match (&meta, &page) {
507                (Some(m), _) => m.geometry(i).ok_or_else(|| no_raster(i as i32))?,
508                (None, Some(p)) => p.geom(),
509                (None, None) => return Err(no_raster(i as i32).into()),
510            };
511            let links = match (&meta, &page) {
512                (Some(m), _) => m.links(i),
513                (None, Some(p)) => p.links(geom.unrotated().1),
514                (None, None) => Vec::new(),
515            };
516            let rc = rust.as_mut().map(|p| p.cells_timed(i));
517            let mut extracted = extract_page(
518                PageSources {
519                    page: page.as_ref(),
520                    dparse: dparse.as_ref(),
521                    meta: meta.as_deref(),
522                    renderer: renderer.as_ref(),
523                    defer: defer.as_ref(),
524                },
525                geom,
526                links,
527                i as i32,
528                rc,
529                render_image,
530            )?;
531            extracted.keep_typography = text.keep_typography;
532            f(i, total, extracted)?;
533        }
534        // The helper ends once this sender and every page's handle are gone.
535        drop(defer);
536    }
537    // Tearing down the parsed document (hundreds of thousands of lopdf
538    // objects on a long PDF — 250 ms for the 1913-page .NET reference) is
539    // nobody's business but the allocator's: hand it to a detached thread so
540    // the last page's output isn't held up by it. `Arc`, not `Rc`, in the
541    // caches is what makes the parser `Send`.
542    if let Some(parser) = rust {
543        std::thread::spawn(move || crate::timing::timed("textparse.close", || drop(parser)));
544    }
545    Ok(())
546}
547
548/// One rasterized page from [`render_pages`] (#243): the absolute 1-based page
549/// number in the source document, the pixel dimensions, and the PNG bytes.
550#[cfg(feature = "render")]
551#[derive(Debug, Clone)]
552pub struct RenderedPage {
553    pub page_no: usize,
554    pub width: u32,
555    pub height: u32,
556    pub png: Vec<u8>,
557    /// The images the page's render drew as a placeholder block or left out,
558    /// each with the reason (#916) — empty when everything decoded. Only the
559    /// pure-Rust renderer reports; the docling-parse plugin and pdfium
560    /// renders leave it empty.
561    pub omissions: Vec<crate::render::Omission>,
562}
563
564/// Upper bound, in pixels, on a rendered page bitmap's side. A crafted PDF can
565/// declare an enormous `MediaBox` in a few hundred bytes; the page render then
566/// asks pdfium — and `into_rgb8` — to allocate `w * h * 4` bytes. At the
567/// pipeline's 3x supersample a 12000 pt box is 36000x36000 ~ 5 GB: pdfium
568/// returns an opaque internal error at the extreme, and just below it the
569/// `image` crate *panics* (a `TryReserveError`, not a recoverable error) when
570/// the allocation fails. Real pages, even large-format (A0 at 3x ~ 10110 px),
571/// stay well under this cap; it only rejects the implausible, turning an abort
572/// into a clean error. Mirrors `decode_image_limited`'s guard on the
573/// standalone-image path. `DOCLING_RS_MAX_RENDER_PIXELS` overrides it.
574#[cfg(feature = "render")]
575fn max_render_side() -> u32 {
576    static M: std::sync::OnceLock<u32> = std::sync::OnceLock::new();
577    *M.get_or_init(|| docling_core::env::parse("DOCLING_RS_MAX_RENDER_PIXELS").unwrap_or(15_000))
578}
579
580/// Round float pixel dimensions to the `i32` pdfium wants, rejecting a page
581/// whose bitmap would exceed [`max_render_side`] on either side before either
582/// pdfium or `image` tries to allocate it.
583#[cfg(feature = "render")]
584fn checked_render_dims(
585    w_px: f64,
586    h_px: f64,
587    page_no: usize,
588) -> Result<(i32, i32), crate::PdfError> {
589    let cap = max_render_side();
590    let w = w_px.round().max(1.0);
591    let h = h_px.round().max(1.0);
592    if w > f64::from(cap) || h > f64::from(cap) {
593        return Err(crate::PdfError::Pdfium(format!(
594            "page {page_no}: render size {w:.0}x{h:.0} px exceeds the {cap}px per-side cap \
595             (raise DOCLING_RS_MAX_RENDER_PIXELS); the page's declared size is implausibly large"
596        )));
597    }
598    Ok((w as i32, h as i32))
599}
600
601#[cfg(feature = "render")]
602/// Rasterize a PDF's pages to PNG (#243) — the lean path behind serve's
603/// `to=images`: pdfium render only, no text extraction, no models, and only
604/// one page bitmap resident at a time (each is PNG-encoded and dropped before
605/// the next renders). `scale` is pixels per PDF point — 2.0 matches the
606/// pipeline's [`RENDER_SCALE`] (144 dpi). Unlike the pipeline's render there
607/// is no 1.5× supersample + downsample pass: that dance exists only because
608/// TableFormer is pixel-pinned to docling's bitmaps, and nothing downstream
609/// of this output is — a single render is nearly twice as fast.
610///
611/// `range` is a **1-based** inclusive page window (issue #80's `pages`
612/// semantics: the end clamps to the document, a start past the end errors).
613///
614/// pdfium is not thread-safe — callers must serialize this against any other
615/// pdfium use (docling-serve holds its pipeline mutex around this call for
616/// exactly that reason).
617pub fn render_pages(
618    bytes: &[u8],
619    password: Option<&str>,
620    range: Option<(usize, usize)>,
621    scale: f32,
622) -> Result<Vec<RenderedPage>, crate::PdfError> {
623    // The docling-parse renderer plugin renders the display bitmap when it is
624    // asked for (full-resolution bitmap decode: this is a viewer's render,
625    // not a model input); the Rust raster / renderer otherwise, pdfium under
626    // `DOCLING_RS_RENDERER=pdfium` or for a file lopdf cannot read.
627    let dparse = crate::dparse_render::Doc::open_if_enabled(bytes, password);
628    // The object model: the page count and the Rust raster / renderer.
629    let meta = crate::pdf_meta::PdfMeta::open_with_password(bytes, password)?;
630    let pdfium = match &dparse {
631        Some(_) => None,
632        None => bind_or_skip(meta.is_some())?,
633    };
634    let session = match &pdfium {
635        Some(p) => Some(p.open(bytes, password)?),
636        None => None,
637    };
638    let total = match (&session, &dparse, &meta) {
639        (Some(s), _, _) => s.page_count(),
640        (None, Some(dp), _) => dp.page_count(),
641        (None, None, Some(m)) => m.page_count(),
642        (None, None, None) => 0,
643    };
644    let (first, last) = match range {
645        None => (0, total.saturating_sub(1)),
646        Some((first, last)) => {
647            if first == 0 || last < first {
648                return Err(PdfError::Document(format!(
649                    "invalid page range {first}-{last} (pages are 1-based, first <= last)"
650                )));
651            }
652            if first > total {
653                return Err(PdfError::Document(format!(
654                    "page range {first}-{last} is outside the document ({total} page(s))"
655                )));
656            }
657            (first - 1, last.min(total) - 1)
658        }
659    };
660    let renderer = match (&dparse, &meta) {
661        // Page rasters a caller keeps decode every image at full size (the
662        // shim is asked with bitmap hint 0.0 below for the same reason).
663        (None, Some(m)) => Some(crate::render::Renderer::with_bitmap_hint(m, 0.0)),
664        _ => None,
665    };
666    let mut out = Vec::with_capacity(last.saturating_sub(first) + 1);
667    for i in first..=last {
668        if i >= total {
669            break;
670        }
671        // Both renderers apply /Rotate themselves, so the bitmap is the page as
672        // a viewer shows it — no orientation handling needed (the pipeline's
673        // scanned-page un-rotation is an OCR-conformance concern, not a display
674        // one).
675        // The plugin's canvas first (the renderer whenever it resolves), then
676        // the Rust raster of an image-only page (pdfium's bitmap byte for
677        // byte, no library needed) or the Rust page renderer, then pdfium
678        // (`DOCLING_RS_RENDERER=pdfium`, or a file lopdf cannot read).
679        // A page the per-side cap refuses is an error naming the cap (#916),
680        // not a missing renderer.
681        let rust = || -> Result<Option<RgbImage>, PdfError> {
682            let Some(g) = meta.as_ref().and_then(|m| m.geometry(i)) else {
683                return Ok(None);
684            };
685            let (tw, th) = checked_render_dims(
686                f64::from(g.width * scale),
687                f64::from(g.height * scale),
688                i + 1,
689            )?;
690            Ok(rust_bitmap(
691                meta.as_ref(),
692                renderer.as_ref(),
693                session.is_some(),
694                i as i32,
695                tw as u32,
696                th as u32,
697                0.0,
698            ))
699        };
700        let bitmap = match (&dparse, &session) {
701            (Some(dp), _) => {
702                crate::timing::timed("dparse.rasterize", || dp.render(i, f64::from(scale), 0.0))
703                    .map_err(PdfError::Document)?
704            }
705            (None, session) => match rust()? {
706                Some(img) => img,
707                None => {
708                    let Some(s) = session else {
709                        return Err(no_raster(i as i32));
710                    };
711                    let page = s.page(i)?;
712                    let (pw, ph) = page.size();
713                    let (tw, th) =
714                        checked_render_dims(f64::from(pw * scale), f64::from(ph * scale), i + 1)?;
715                    page.render(tw, th, "pdfium.rasterize")?
716                }
717            },
718        };
719        let mut png = Vec::new();
720        bitmap
721            .write_to(&mut std::io::Cursor::new(&mut png), image::ImageFormat::Png)
722            .map_err(|e| PdfError::Document(format!("PNG-encoding page {}: {e}", i + 1)))?;
723        out.push(RenderedPage {
724            page_no: i + 1,
725            width: bitmap.width(),
726            height: bitmap.height(),
727            png,
728            omissions: renderer
729                .as_ref()
730                .map(crate::render::Renderer::take_omissions)
731                .unwrap_or_default(),
732        });
733    }
734    Ok(out)
735}
736
737#[cfg(feature = "render")]
738/// The error for a page that needs a raster when the object model could not
739/// be read and neither the docling-parse renderer plugin nor pdfium is there.
740fn no_raster(index: i32) -> PdfError {
741    PdfError::Document(format!(
742        "page {}: no page renderer — the file's object model could not be read (lopdf), \
743         the docling-parse renderer plugin is not installed (.docling-parse/lib) and \
744         pdfium is not available (the `pdfium` feature + PDFIUM_DYNAMIC_LIB_PATH / \
745         .pdfium/lib)",
746        index + 1
747    ))
748}
749
750/// The pure-Rust bitmap of a page at `width` × `height`: the raster of an
751/// image-only page (`raster::render`, pdfium's bytes) when the page
752/// qualifies, the page renderer (`render`) otherwise — `None` only when the
753/// object model is not loaded, or when `DOCLING_RS_RENDERER=pdfium` asks for
754/// pdfium's render of a page the raster declines *and* pdfium's page is open
755/// (`pdfium_page`; a build or machine without the library degrades to the
756/// Rust renderer, as [`bind_or_skip`] warned).
757#[cfg(feature = "render")]
758fn rust_bitmap(
759    meta: Option<&crate::pdf_meta::PdfMeta>,
760    renderer: Option<&crate::render::Renderer<'_>>,
761    pdfium_page: bool,
762    index: i32,
763    width: u32,
764    height: u32,
765    bitmap_hint: f64,
766) -> Option<RgbImage> {
767    let meta = meta?;
768    if let Some(img) = crate::timing::timed("raster.render", || {
769        crate::raster::render(meta, index as usize, width, height)
770    }) {
771        return Some(img);
772    }
773    if pdfium_page && crate::dparse_render::choice() == crate::dparse_render::Choice::Pdfium {
774        return None;
775    }
776    let renderer = renderer?;
777    crate::timing::timed("render.page", || {
778        renderer.render_with_hint(index as usize, width, height, bitmap_hint)
779    })
780}
781
782#[cfg(feature = "render")]
783/// Bind pdfium for a conversion, or decide it can run without it. pdfium has
784/// a job in two cases only: its own render was asked for
785/// (`DOCLING_RS_RENDERER=pdfium`, which only the `pdfium` feature offers), or
786/// the pure-Rust object model could not read the file (`meta_ok` false) — then
787/// pdfium's page tree, geometry and render stand in, and a build without the
788/// feature (or without the library) fails the conversion with the hint.
789/// Otherwise the library is never loaded.
790fn bind_or_skip(meta_ok: bool) -> Result<Option<native::Lib>, PdfError> {
791    if meta_ok && crate::dparse_render::choice() != crate::dparse_render::Choice::Pdfium {
792        return Ok(None);
793    }
794    match native::bind() {
795        Ok(p) => Ok(Some(p)),
796        Err(e) if meta_ok => {
797            // The library was asked for by name and is not there: say so
798            // once, then degrade — the Rust renderer draws every page.
799            static WARNED: std::sync::Once = std::sync::Once::new();
800            WARNED.call_once(|| {
801                eprintln!(
802                    "docling-pdf: DOCLING_RS_RENDERER=pdfium but the pdfium library could not be \
803                     loaded ({e}); rendering with the Rust renderer"
804                );
805            });
806            Ok(None)
807        }
808        Err(e) => Err(e),
809    }
810}
811
812/// The native sources a page may draw on, each optional: pdfium's page handle
813/// (present only when [`bind_or_skip`] opened the library) and the
814/// docling-parse renderer (absent when the plugin is not asked for or no
815/// raster is wanted).
816#[cfg(feature = "render")]
817#[derive(Clone, Copy)]
818struct PageSources<'a> {
819    page: Option<&'a native::Page<'a>>,
820    dparse: Option<&'a crate::dparse_render::Doc>,
821    /// The object model, for the Rust raster of an image-only page.
822    meta: Option<&'a crate::pdf_meta::PdfMeta>,
823    /// The pure-Rust page renderer over the same object model (its
824    /// per-document caches live for the whole conversion).
825    renderer: Option<&'a crate::render::Renderer<'a>>,
826    /// The helper thread that renders the 2x bitmap of pages with a text
827    /// layer off the walk (#682); `None` when another renderer draws.
828    defer: Option<&'a DeferredRender>,
829}
830
831/// A page's 2x bitmap, rendered on the walk's helper thread (#682): queued
832/// until something asks for it ([`BitmapRender::OnDemand`]) or sent at once
833/// ([`BitmapRender::Eager`], [`BitmapRender::Adaptive`]), the result
834/// arriving through a one-shot channel. A sent job can be declined: the
835/// helper then skips it if it has not started it, and a later resolve sends
836/// it again (#897). Cloning a page clones the handle; whichever copy
837/// resolves first gets the bitmap. A handle dropped while still queued, or
838/// declined in time, costs nothing — the render never happens.
839#[cfg(feature = "render")]
840#[derive(Clone)]
841pub struct PendingImage(std::sync::Arc<std::sync::Mutex<Pending>>);
842
843/// The channel a sent job's bitmap comes back through.
844#[cfg(feature = "render")]
845type Reply = std::sync::mpsc::Receiver<Result<RgbImage, PdfError>>;
846
847/// Where a [`PendingImage`] stands: the job and the helper to send it to,
848/// plus — once sent — the reply channel and the flag that lets the helper
849/// skip it.
850#[cfg(feature = "render")]
851struct Pending {
852    spec: RenderSpec,
853    tx: std::sync::mpsc::Sender<RenderJob>,
854    sent: Option<(Reply, std::sync::Arc<std::sync::atomic::AtomicBool>)>,
855    taken: bool,
856    /// The document's recent verdicts, which [`BitmapRender::Adaptive`]
857    /// schedules by; this page's goes in once.
858    stats: std::sync::Arc<Verdicts>,
859    /// This page's verdict so far (`Some(true)` = read).
860    verdict: Option<bool>,
861}
862
863/// Whether the last [`Verdicts::WINDOW`] pages that reached a verdict read
864/// their 2x bitmap — what [`BitmapRender::Adaptive`] decides a new page's
865/// render by (#897).
866#[cfg(feature = "render")]
867#[derive(Default)]
868struct Verdicts(std::sync::Mutex<std::collections::VecDeque<bool>>);
869
870#[cfg(feature = "render")]
871impl Verdicts {
872    const WINDOW: usize = 8;
873
874    /// Record a page's verdict, or turn a declined page's into a read one.
875    fn record(&self, read: bool, replaces_decline: bool) {
876        let mut w = self.0.lock().unwrap_or_else(|p| p.into_inner());
877        if replaces_decline {
878            if let Some(v) = w.iter_mut().rev().find(|v| !**v) {
879                *v = true;
880            }
881            return;
882        }
883        if w.len() == Self::WINDOW {
884            w.pop_front();
885        }
886        w.push_back(read);
887    }
888
889    /// Start the next render now? Yes until a few verdicts are in (most
890    /// documents' first pages are not representative either way, and a
891    /// wrong "yes" costs one render, a wrong "no" one page's latency), then
892    /// while at least half of the window read theirs.
893    fn start_eagerly(&self) -> bool {
894        let w = self.0.lock().unwrap_or_else(|p| p.into_inner());
895        w.len() < 3 || 2 * w.iter().filter(|v| **v).count() >= w.len()
896    }
897}
898
899#[cfg(feature = "render")]
900impl Pending {
901    /// Send the job (again, after a skipped one) and keep its reply channel.
902    /// The helper runs while any job sender lives — this one included — so a
903    /// failed send means it died (a render panicked).
904    fn send(&mut self) -> Result<(), PdfError> {
905        let (reply, rx) = std::sync::mpsc::sync_channel(1);
906        let declined = std::sync::Arc::new(std::sync::atomic::AtomicBool::new(false));
907        self.tx
908            .send(RenderJob {
909                spec: self.spec,
910                declined: declined.clone(),
911                reply,
912            })
913            .map_err(|_| PdfError::Pdfium("page render thread ended early".into()))?;
914        self.sent = Some((rx, declined));
915        Ok(())
916    }
917}
918
919#[cfg(feature = "render")]
920impl PendingImage {
921    fn lock(&self) -> std::sync::MutexGuard<'_, Pending> {
922        self.0.lock().unwrap_or_else(|p| p.into_inner())
923    }
924
925    /// Hand the job to the helper, unless that happened already.
926    fn start(&self) {
927        let mut p = self.lock();
928        if p.sent.is_none() && !p.taken {
929            // A dead helper surfaces as the page's resolve error.
930            let _ = p.send();
931        }
932    }
933
934    /// Nothing will read this bitmap: let the helper skip the job if it has
935    /// not begun it (a job never sent stays unsent).
936    fn decline(&self) {
937        let mut p = self.lock();
938        if p.verdict.is_none() {
939            p.verdict = Some(false);
940            p.stats.record(false, false);
941        }
942        if let Some((_, declined)) = &p.sent {
943            declined.store(true, std::sync::atomic::Ordering::Relaxed);
944        }
945    }
946
947    fn wait(self) -> Result<RgbImage, PdfError> {
948        let mut p = self.lock();
949        if p.taken {
950            return Err(PdfError::Pdfium("page bitmap resolved twice".into()));
951        }
952        if p.verdict != Some(true) {
953            p.stats.record(true, p.verdict == Some(false));
954            p.verdict = Some(true);
955        }
956        loop {
957            match &p.sent {
958                None => p.send()?,
959                Some((rx, declined)) => {
960                    // Asked for after all: a job not yet begun renders.
961                    declined.store(false, std::sync::atomic::Ordering::Relaxed);
962                    match rx.recv() {
963                        Ok(out) => {
964                            p.taken = true;
965                            p.sent = None;
966                            return out;
967                        }
968                        // Skipped while declined (or the helper died, which
969                        // the next send reports): send it again.
970                        Err(_) => p.sent = None,
971                    }
972                }
973            }
974        }
975    }
976}
977
978#[cfg(feature = "render")]
979impl std::fmt::Debug for PendingImage {
980    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
981        f.write_str("PendingImage")
982    }
983}
984
985/// One deferred render: the 3x supersample of page `index` at `w` × `h`
986/// with the decode `hint`, box-downscaled to `dw` × `dh` — exactly the
987/// synchronous path's steps, on another thread.
988#[cfg(feature = "render")]
989#[derive(Clone, Copy)]
990struct RenderSpec {
991    index: i32,
992    w: u32,
993    h: u32,
994    hint: f64,
995    dw: u32,
996    dh: u32,
997}
998
999#[cfg(feature = "render")]
1000struct RenderJob {
1001    spec: RenderSpec,
1002    /// Set when the page turned out not to read the bitmap (#897): the
1003    /// helper skips the job if it gets to it after that — dropping `reply`,
1004    /// which tells a later resolve to send it again.
1005    declined: std::sync::Arc<std::sync::atomic::AtomicBool>,
1006    reply: std::sync::mpsc::SyncSender<Result<RgbImage, PdfError>>,
1007}
1008
1009/// The walk's render helper (#682): a second pure-Rust renderer, with its
1010/// own per-document caches, on its own thread, fed one [`RenderJob`] per
1011/// 2x bitmap asked for. Its bitmaps are the ones the walk thread would have
1012/// drawn — the same renderer code over the same object model — so the
1013/// output is byte-identical; what changes is that the page leaves the walk
1014/// as soon as its 1x layout image is drawn, and the 2x bitmap lands while
1015/// layout runs ([`BitmapRender::Eager`]) or when the page turns out to need
1016/// it ([`BitmapRender::OnDemand`], #897). Not scoped to the walk: a page
1017/// resolved on demand asks after the walk is over, so the thread holds the
1018/// object model and runs until the walk and every page's handle have let go
1019/// of the job sender.
1020#[cfg(feature = "render")]
1021struct DeferredRender {
1022    tx: std::sync::mpsc::Sender<RenderJob>,
1023    mode: BitmapRender,
1024    stats: std::sync::Arc<Verdicts>,
1025}
1026
1027#[cfg(feature = "render")]
1028impl DeferredRender {
1029    /// The helper for `meta`; `None` (render in place, as without one) when
1030    /// the thread cannot be spawned.
1031    fn spawn(meta: std::sync::Arc<crate::pdf_meta::PdfMeta>, mode: BitmapRender) -> Option<Self> {
1032        let (tx, rx) = std::sync::mpsc::channel();
1033        std::thread::Builder::new()
1034            .name("docling-pdf-render".into())
1035            .spawn(move || Self::serve(&meta, rx))
1036            .ok()?;
1037        Some(Self {
1038            tx,
1039            mode,
1040            stats: Default::default(),
1041        })
1042    }
1043
1044    fn submit(&self, index: i32, w: u32, h: u32, hint: f64, dw: u32, dh: u32) -> PendingImage {
1045        let spec = RenderSpec {
1046            index,
1047            w,
1048            h,
1049            hint,
1050            dw,
1051            dh,
1052        };
1053        let pending = PendingImage(std::sync::Arc::new(std::sync::Mutex::new(Pending {
1054            spec,
1055            tx: self.tx.clone(),
1056            sent: None,
1057            taken: false,
1058            stats: self.stats.clone(),
1059            verdict: None,
1060        })));
1061        let start = match self.mode {
1062            BitmapRender::Eager => true,
1063            BitmapRender::Adaptive => self.stats.start_eagerly(),
1064            BitmapRender::OnDemand => false,
1065        };
1066        if start {
1067            pending.start();
1068        }
1069        pending
1070    }
1071
1072    /// The helper's loop: runs until every job sender is dropped.
1073    fn serve(meta: &crate::pdf_meta::PdfMeta, jobs: std::sync::mpsc::Receiver<RenderJob>) {
1074        let renderer = crate::render::Renderer::new(meta);
1075        for RenderJob {
1076            spec,
1077            declined,
1078            reply,
1079        } in jobs
1080        {
1081            if declined.load(std::sync::atomic::Ordering::Relaxed) {
1082                if crate::timing::enabled() {
1083                    crate::timing::record("render.skipped", 0);
1084                }
1085                continue;
1086            }
1087            let out = rust_bitmap(
1088                Some(meta),
1089                Some(&renderer),
1090                false,
1091                spec.index,
1092                spec.w,
1093                spec.h,
1094                spec.hint,
1095            )
1096            .map(|big| {
1097                crate::timing::timed("image.resize", || fast_downscale(&big, spec.dw, spec.dh))
1098            })
1099            .ok_or_else(|| no_raster(spec.index));
1100            let _ = reply.send(out);
1101        }
1102    }
1103}
1104
1105#[cfg(feature = "render")]
1106fn extract_page(
1107    sources: PageSources<'_>,
1108    geom: crate::pdf_meta::PageGeom,
1109    links: Vec<LinkAnnot>,
1110    index: i32,
1111    rust_cells: Option<crate::textparse::PageParserCells>,
1112    render_image: bool,
1113) -> Result<PdfPage, PdfError> {
1114    let PageSources {
1115        page,
1116        dparse,
1117        meta,
1118        renderer,
1119        defer,
1120    } = sources;
1121    // The page size (and the render) is the *display* frame — `/Rotate`
1122    // applied — while every text coordinate (pdfium's own text page, the
1123    // pure-Rust parser's MediaBox-based glyphs, link annotation rects) lives
1124    // in the unrotated frame (docling#4008, 2.121). Keep the unrotated box
1125    // around for the y-flips and bring every rect into the display frame.
1126    let width = geom.width;
1127    let height = geom.height;
1128    let rotation = geom.rotation;
1129    let (unrot_w, unrot_h) = geom.unrotated();
1130
1131    // The text layer: the pure-Rust parser's prose, word and code cells (its
1132    // word grouping reproduces docling-parse's, which TableFormer matches
1133    // against). A page it reads nothing from is a scanned page for the OCR
1134    // path — pdfium's text page is gone (phase 4 of "Retiring pdfium").
1135    let rc = rust_cells.unwrap_or_default();
1136    let (mut cells, mut code_cells, mut word_cells) = (rc.prose, rc.code, rc.words);
1137    let mut checkboxes = rc.checkboxes;
1138    if rotation != 0 {
1139        for c in cells
1140            .iter_mut()
1141            .chain(word_cells.iter_mut())
1142            .chain(code_cells.iter_mut())
1143        {
1144            let (l, t, r, b) = to_display_frame((c.l, c.t, c.r, c.b), rotation, unrot_w, unrot_h);
1145            (c.l, c.t, c.r, c.b) = (l, t, r, b);
1146        }
1147        for c in &mut checkboxes {
1148            let (l, t, r, b) = to_display_frame((c.l, c.t, c.r, c.b), rotation, unrot_w, unrot_h);
1149            (c.l, c.t, c.r, c.b) = (l, t, r, b);
1150        }
1151    }
1152
1153    // The docling-parse renderer (#478, `dparse_render.rs`): the model inputs
1154    // come from docling-parse's Blend2D canvas, requested in docling's order
1155    // and with its decode hint — the scale-1.0 layout image (docling decodes
1156    // the page once, at its `render_scale` of 1.0), then the scale-2.0 bitmap
1157    // TableFormer crops from (`_render_image_at_scale` on the same decoder,
1158    // hence the same hint). One deliberate exception: a *scanned* page — no
1159    // text layer, the OCR path — keeps pdfium's bitmap. docling's 2.0/3.0
1160    // re-renders draw the raster its decoders reduced to 72 dpi, and Blend2D's
1161    // blit of a scan differs from pdfium's render + downscale in a way the
1162    // `ch` conformance recognizer feels (`scanned/ocr_test.pdf` read `JsON` for
1163    // `JSON` from either docling-parse raster, hint 1.0 or full resolution);
1164    // pdfium's raster is the one the scanned groundtruth was matched with, so
1165    // OCR keeps it (recorded in PDF_CONFORMANCE.md) — as long as pdfium is
1166    // loaded: a checkout with the plugin and no `libpdfium` OCRs the
1167    // docling-parse raster rather than failing the page (degradation over
1168    // failure). The canvases are `ceil`-sized where pdfium's are `round`ed;
1169    // every consumer maps points through `RENDER_SCALE`, not through the
1170    // image size, so the extra row/column is harmless.
1171    let scanned = cells.is_empty() && word_cells.is_empty() && code_cells.is_empty();
1172    let mut pending_image = None;
1173    let (mut dp_image, mut dp_layout) = (None, None);
1174    if let (true, Some(dp)) = (render_image, dparse) {
1175        let layout = crate::timing::timed("dparse.render_layout", || {
1176            dp.render(index as usize, 1.0, 1.0)
1177        })
1178        .map_err(PdfError::Document)?;
1179        if !scanned {
1180            let full = crate::timing::timed("dparse.render", || {
1181                dp.render(index as usize, f64::from(RENDER_SCALE), 1.0)
1182            })
1183            .map_err(PdfError::Document)?;
1184            dp_image = Some(full);
1185        }
1186        dp.release_page(index as usize);
1187        dp_layout = Some(layout);
1188    }
1189    // A scanned page's bitmap, in order: the pure-Rust raster (pdfium's bytes;
1190    // `raster`), pdfium itself, and — with neither — the plugin's scale-2.0
1191    // canvas rather than a failed page.
1192    let scanned_fallback = |page: Option<&native::Page<'_>>| match (page, dparse) {
1193        (None, Some(dp)) if scanned => {
1194            let full = crate::timing::timed("dparse.render", || {
1195                dp.render(index as usize, f64::from(RENDER_SCALE), 1.0)
1196            })
1197            .map_err(PdfError::Document)?;
1198            dp.release_page(index as usize);
1199            Ok(Some(full))
1200        }
1201        _ => Ok::<_, PdfError>(None),
1202    };
1203    let image = if let Some(img) = dp_image.take() {
1204        img
1205    } else if render_image {
1206        // docling's pypdfium2 backend renders at 1.5× the target scale and
1207        // downsamples "to make it sharper" (pypdfium2 → PIL BICUBIC). Replicate
1208        // exactly: the TableFormer model is pixel-sensitive, so the page bitmap
1209        // must match that backend's byte-for-byte (docling 2.123+'s default
1210        // docling-parse backend renders it itself — #478).
1211        // `CatmullRom` is the same a=-0.5 cubic kernel as PIL's BICUBIC.
1212        const SUPERSAMPLE: f32 = 1.5;
1213        // The 3x supersample is the largest bitmap the pipeline renders, so the
1214        // per-side cap is enforced here; the 1.5x layout render below is always
1215        // smaller and needs no separate guard.
1216        let (tw, th) = checked_render_dims(
1217            f64::from(width * RENDER_SCALE * SUPERSAMPLE),
1218            f64::from(height * RENDER_SCALE * SUPERSAMPLE),
1219            (index + 1) as usize,
1220        )?;
1221        // An image-only page (a scan) is rendered by the pure-Rust raster —
1222        // pdfium's bitmap byte for byte (`raster`, its oracle test) — and any
1223        // other page by the pure-Rust renderer (`render`), so the OCR path
1224        // needs no `libpdfium`; pdfium renders only when asked for
1225        // (`DOCLING_RS_RENDERER=pdfium`).
1226        let dw = (width * RENDER_SCALE).round().max(1.0) as u32;
1227        let dh = (height * RENDER_SCALE).round().max(1.0) as u32;
1228        // A page without a text layer takes this bitmap to OCR: decode its
1229        // images at full size (hint 0.0); a digital page's TableFormer input
1230        // follows docling's hint 1.0 like the layout image below.
1231        let hint = if cells.is_empty() { 0.0 } else { 1.0 };
1232        // A page with a text layer needs this bitmap only after layout
1233        // (TableFormer, crops): the helper thread draws it meanwhile (#682).
1234        // A scanned page reads it first (orientation, OCR) and renders here.
1235        if let (Some(defer), false) = (defer, scanned) {
1236            pending_image = Some(defer.submit(index, tw as u32, th as u32, hint, dw, dh));
1237            RgbImage::new(1, 1)
1238        } else {
1239            let big = match rust_bitmap(
1240                meta,
1241                renderer,
1242                page.is_some(),
1243                index,
1244                tw as u32,
1245                th as u32,
1246                hint,
1247            ) {
1248                Some(img) => Some(img),
1249                None if page.is_some() => {
1250                    let page = page.ok_or_else(|| no_raster(index))?;
1251                    Some(page.render(tw, th, "pdfium.render")?)
1252                }
1253                None => None,
1254            };
1255            match (big, scanned_fallback(page)?) {
1256                (Some(big), _) => {
1257                    crate::timing::timed("image.resize", || fast_downscale(&big, dw, dh))
1258                }
1259                (None, Some(canvas)) => canvas,
1260                (None, None) => return Err(no_raster(index)),
1261            }
1262        }
1263    } else {
1264        RgbImage::new(1, 1)
1265    };
1266    // The layout model's input image, built exactly like docling's pypdfium2
1267    // `get_page_image(scale=1.0)`: a pdfium render at 1.5× (pypdfium2 sizes
1268    // with `ceil`), PIL-BICUBIC down to the point-size image (PIL `resize`'s
1269    // default kernel; Python `round` = ties-to-even). Distinct from the 2×
1270    // bitmap above — resampling 1224→640 and 612→640 are different regimes,
1271    // and the heron model's borderline scores follow the pixels. "Exactly" is
1272    // against the pypdfium2 backend: docling 2.123+'s default docling-parse
1273    // backend renders this image with its own renderer (#478, see
1274    // docs/PDF_CONFORMANCE.md).
1275    let image_layout = if let Some(img) = dp_layout.take() {
1276        Some(img)
1277    } else if render_image {
1278        let tw = f64::from(width * 1.5).ceil().max(1.0) as i32;
1279        let th = f64::from(height * 1.5).ceil().max(1.0) as i32;
1280        let big = match rust_bitmap(
1281            meta,
1282            renderer,
1283            page.is_some(),
1284            index,
1285            tw as u32,
1286            th as u32,
1287            1.0,
1288        ) {
1289            Some(img) => img,
1290            None => {
1291                let page = page.ok_or_else(|| no_raster(index))?;
1292                page.render(tw, th, "pdfium.render_layout")?
1293            }
1294        };
1295        let dw = f64::from(width).round_ties_even().max(1.0) as u32;
1296        let dh = f64::from(height).round_ties_even().max(1.0) as u32;
1297        Some(crate::timing::timed("image.resize_layout", || {
1298            crate::resample::pil_resize(&big, dw, dh, crate::resample::PilFilter::Bicubic)
1299        }))
1300    } else {
1301        None
1302    };
1303
1304    let mut links = links;
1305    if rotation != 0 {
1306        for l in &mut links {
1307            let (a, t, r, b) = to_display_frame((l.l, l.t, l.r, l.b), rotation, unrot_w, unrot_h);
1308            (l.l, l.t, l.r, l.b) = (a, t, r, b);
1309        }
1310    }
1311
1312    // `/Rotate` normalization for scanned pages: pdfium renders the page as a
1313    // viewer displays it — `/Rotate` applied — so a rotated scan hands layout
1314    // and OCR a sideways/upside-down raster and the recognition output is
1315    // garbage. A page with a text layer needs none of this (its cells carry
1316    // the geometry; the models never see its pixels decide text), so the
1317    // normalization is gated to pages with no cells at all — exactly the set
1318    // the OCR path fires on. The bitmaps are un-rotated to upright (lossless
1319    // 90° steps), `width`/`height` swap to the upright box, and the display
1320    // rotation is recorded so assembly can rotate the finished geometry back
1321    // into display space (docling reports rotated pages in display coords).
1322    let mut page = PdfPage {
1323        width,
1324        height,
1325        scale: RENDER_SCALE,
1326        image_layout,
1327        pending_image,
1328        cells,
1329        code_cells,
1330        word_cells,
1331        checkboxes,
1332        image,
1333        links,
1334        rotation: 0,
1335        keep_typography: false,
1336    };
1337    if rotation != 0 && scanned && render_image {
1338        page.unrotate(rotation);
1339    }
1340    Ok(page)
1341}
1342
1343#[cfg(feature = "render")]
1344/// The supersample→target downscale via `fast_image_resize` (SIMD convolution;
1345/// the same a=-0.5 Catmull-Rom kernel as `image::imageops::resize(...,
1346/// CatmullRom)` and PIL BICUBIC — see the render comment above). Set
1347/// `DOCLING_RS_SLOW_RESIZE=1` to fall back to the `image`-crate scalar resize
1348/// (byte-parity with the pre-SIMD pipeline, several times slower).
1349fn fast_downscale(big: &RgbImage, dw: u32, dh: u32) -> RgbImage {
1350    use fast_image_resize as fir;
1351    static SLOW: std::sync::OnceLock<bool> = std::sync::OnceLock::new();
1352    let slow = *SLOW.get_or_init(|| docling_core::env::flag("DOCLING_RS_SLOW_RESIZE"));
1353    if !slow {
1354        if let Some(out) = (|| {
1355            let src = fir::images::ImageRef::new(
1356                big.width(),
1357                big.height(),
1358                big.as_raw(),
1359                fir::PixelType::U8x3,
1360            )
1361            .ok()?;
1362            let mut dst = fir::images::Image::new(dw, dh, fir::PixelType::U8x3);
1363            fir::Resizer::new()
1364                .resize(
1365                    &src,
1366                    &mut dst,
1367                    &fir::ResizeOptions::new()
1368                        .resize_alg(fir::ResizeAlg::Convolution(fir::FilterType::CatmullRom)),
1369                )
1370                .ok()?;
1371            RgbImage::from_raw(dw, dh, dst.into_vec())
1372        })() {
1373            return out;
1374        }
1375        // Unreachable in practice; fall through to the scalar path on any error.
1376    }
1377    image::imageops::resize(big, dw, dh, image::imageops::FilterType::CatmullRom)
1378}
1379
1380/// Map a top-left-origin rect from a page's unrotated (MediaBox) frame into its
1381/// `/Rotate`d display frame — the counterpart of docling's pypdfium2
1382/// `_rect_to_display_frame` (docling#4008) for our y-down coordinates.
1383/// `unrot_w`/`unrot_h` are the unrotated page box; the display box is the same
1384/// for 180° and swapped for 90°/270°.
1385pub(crate) fn to_display_frame(
1386    (l, t, r, b): (f32, f32, f32, f32),
1387    rotation: u16,
1388    unrot_w: f32,
1389    unrot_h: f32,
1390) -> (f32, f32, f32, f32) {
1391    match rotation {
1392        // Page turned 90° clockwise for display: the unrotated top edge becomes
1393        // the display right edge, so x' runs from the old bottom edge up.
1394        90 => (unrot_h - b, l, unrot_h - t, r),
1395        180 => (unrot_w - r, unrot_h - b, unrot_w - l, unrot_h - t),
1396        270 => (t, unrot_w - r, b, unrot_w - l),
1397        _ => (l, t, r, b),
1398    }
1399}
1400
1401/// One glyph: codepoint + native (y-up) box edges. `l/b/r/t` is pdfium's *tight*
1402/// ink box (used by the legacy `lines_from_glyphs`); `ll/lb/lr/lt` is the *loose*
1403/// box (font ascent/descent + advance — uniform per font/size), which the
1404/// docling-parse-style sanitizer needs so adjacent glyphs share a top edge.
1405pub(crate) struct Glyph {
1406    pub(crate) ch: char,
1407    pub(crate) l: f32,
1408    pub(crate) b: f32,
1409    pub(crate) r: f32,
1410    pub(crate) t: f32,
1411    pub(crate) ll: f32,
1412    pub(crate) lb: f32,
1413    pub(crate) lr: f32,
1414    pub(crate) lt: f32,
1415    /// Hash of the font's docling-parse name — `/FontDescriptor/FontName`,
1416    /// else `/Name`, else `/BaseFont` (#728: not the page's resource key, which
1417    /// binds one face under several keys) — 0 when not fetched. The sanitizer
1418    /// uses it for docling-parse's `enforce_same_font` (keeps a bold label and
1419    /// regular value as separate line cells, e.g. `LABEL : value`).
1420    pub(crate) font: u64,
1421    /// The loose box as the text matrix actually lays it — corners
1422    /// bottom-left, bottom-right, top-right, top-left as `[x0, y0, … x3, y3]`
1423    /// (docling-parse's `r_x0…r_y3`) — for a glyph whose baseline is **not**
1424    /// upright: rotated 90°/180°/270° or tilted (#528). `ll/lb/lr/lt` are then
1425    /// this quad's axis-aligned extent. `None` for upright text, whose quad is
1426    /// the `ll/lb/lr/lt` rectangle itself — that path stays exactly as it was.
1427    pub(crate) quad: Option<[f32; 8]>,
1428    /// Where the pen sets the glyph — the text origin on the baseline, rise
1429    /// included — and the font size in the same space, as `[x, y, size]`
1430    /// (docling-parse's `text_origin_x/y` and `nominal_text_height`). The
1431    /// word contraction tests a baseline shift on these (#921): the loose
1432    /// box's bottom sits a descent below the baseline, which differs between
1433    /// sizes, so a superscript read as shifted further than it is. `None`
1434    /// when unknown (a synthetic glyph); the box stands in then.
1435    pub(crate) pen: Option<[f32; 3]>,
1436    /// The glyph's font is a math face by its name (docling-parse's
1437    /// `has_math_positioning_semantics`): a sub- or superscript in it next to
1438    /// its base is attached, not a new word (#921).
1439    pub(crate) math_font: bool,
1440}
1441
1442impl Glyph {
1443    /// The font's height on the glyph's own axis (ascent − descent): the
1444    /// loose box's height for upright text, the quad's left edge otherwise —
1445    /// a 90°-turned glyph's vertical extent is its advance, not its size.
1446    pub(crate) fn height(&self) -> f32 {
1447        match self.quad {
1448            Some(q) => (q[6] - q[0]).hypot(q[7] - q[1]),
1449            None => self.lt - self.lb,
1450        }
1451    }
1452}
1453
1454/// How [`lines_from_glyphs`] splits a line into words. Two more modes lived
1455/// here — the prose gap heuristic with punctuation glue and pdfium's
1456/// space-glyph-only code split — for pdfium's glyph stream; the parser's
1457/// prose goes through `dp_lines` and pdfium's text page is gone.
1458#[derive(Clone, Copy, PartialEq)]
1459enum Grouping {
1460    /// Split on the inter-glyph **gap** (or a space glyph), but never glue — for
1461    /// the parser's code cells: the parser emits no space glyphs (a source space
1462    /// is a positioning gap), and its clean advance boxes make the gap reliable.
1463    /// There is no punctuation glue, so a real gap always splits (`et al.
1464    /// 2000`, not `et al.2000`) while genuinely touching tokens stay joined
1465    /// (`add(a,` / `b)`).
1466    CodeGap,
1467}
1468
1469/// Group glyphs (document order) into words then lines, the way docling-parse
1470/// does: a new **word** starts where the horizontal gap to the previous glyph
1471/// exceeds ~0.2 × the font height (a real space is ~0.3 × height; letter
1472/// tracking is smaller, so titles don't shatter); a new **line** starts where
1473/// the baseline drops by ~half the font height (a superscript rises without
1474/// dropping, so it stays on its line). Coordinates are flipped to top-left.
1475/// See [`Grouping`] for how each mode decides word boundaries.
1476fn lines_from_glyphs(gs: &[Glyph], page_h: f32, mode: Grouping) -> Vec<TextCell> {
1477    let mut cells: Vec<TextCell> = Vec::new();
1478    let mut words: Vec<String> = Vec::new(); // words on the current line
1479    let mut word = String::new();
1480    // current line bounding box, native
1481    let (mut ll, mut lb, mut lr, mut lt) = (
1482        f32::INFINITY,
1483        f32::INFINITY,
1484        f32::NEG_INFINITY,
1485        f32::NEG_INFINITY,
1486    );
1487    // Tallest glyph seen on the current line: the word-gap threshold is relative
1488    // to it, so a small-font run on the line (a superscript citation) isn't split
1489    // at its tight digit gaps, while a big display title isn't split at its wider
1490    // letter tracking. A real inter-word space is ~0.3× the font height.
1491    let mut line_h: f32 = 0.0;
1492    let mut prev: Option<&Glyph> = None;
1493    // A space glyph between non-space glyphs pins a word split the gap heuristic
1494    // can miss (tight justified spacing); it carries no geometry.
1495    let mut pending_space = false;
1496
1497    for g in gs {
1498        if g.ch == ' ' {
1499            pending_space = true;
1500            continue;
1501        }
1502        let h = (g.t - g.b).abs().max(1.0);
1503        let (mut new_word, mut new_line) = (false, false);
1504        if let Some(p) = prev {
1505            // A new line drops the baseline *and* resets x leftward; requiring the
1506            // x-reset avoids a descending comma/semicolon faking a line break. A
1507            // *large* drop (≥1.5× the line height — a skipped line, e.g. a centered
1508            // page-number footer below a short last word) is always a new line,
1509            // even without the x-reset.
1510            // LTR wraps reset x leftward (`g.l < p.r`); RTL (Arabic) wraps reset
1511            // rightward (the new line begins at the far right). A large drop
1512            // (≥1.5× line height) is a new line regardless of x.
1513            let x_reset = if is_arabic(g.ch) || is_arabic(p.ch) {
1514                g.l > p.r
1515            } else {
1516                g.l < p.r
1517            };
1518            new_line = (p.b - g.b > h * 0.5 && x_reset) || (p.b - g.b > line_h.max(h) * 1.5);
1519            let word_gap = line_h.max(h) * 0.25;
1520            new_word = match mode {
1521                // Gap-based, no glue: a real gap always splits, touching tokens join.
1522                Grouping::CodeGap => new_line || pending_space || g.l - p.r > word_gap,
1523            };
1524        }
1525        pending_space = false;
1526        if new_line {
1527            push_word(&mut word, &mut words);
1528            push_line(&mut words, (ll, lb, lr, lt), page_h, &mut cells);
1529            (ll, lb, lr, lt) = (
1530                f32::INFINITY,
1531                f32::INFINITY,
1532                f32::NEG_INFINITY,
1533                f32::NEG_INFINITY,
1534            );
1535            line_h = 0.0;
1536        } else if new_word {
1537            push_word(&mut word, &mut words);
1538        }
1539        word.push(g.ch);
1540        ll = ll.min(g.l);
1541        lb = lb.min(g.b);
1542        lr = lr.max(g.r);
1543        lt = lt.max(g.t);
1544        line_h = line_h.max(h);
1545        prev = Some(g);
1546    }
1547    push_word(&mut word, &mut words);
1548    push_line(&mut words, (ll, lb, lr, lt), page_h, &mut cells);
1549    cells
1550}
1551
1552/// Code line cells from the parser's glyph stream. The parser emits no space
1553/// glyphs — a source space is a positioning gap — so code cells use
1554/// [`Grouping::CodeGap`], which splits on the inter-glyph gap (a space
1555/// wherever it exceeds ~0.25× the line height) but never glues punctuation,
1556/// so `et al. 2000` keeps its space while `add(a,` / `b)` stay joined. The
1557/// parser's clean advance boxes make the gap heuristic reliable here, where
1558/// pdfium's overhanging loose boxes used to over-split (`f un c t i o n`).
1559pub(crate) fn code_cells_from_glyphs(gs: &[Glyph], page_h: f32) -> Vec<TextCell> {
1560    lines_from_glyphs(gs, page_h, Grouping::CodeGap)
1561}
1562
1563fn is_arabic(c: char) -> bool {
1564    ('\u{0600}'..='\u{06FF}').contains(&c)
1565}
1566
1567fn push_word(word: &mut String, words: &mut Vec<String>) {
1568    if !word.is_empty() {
1569        words.push(std::mem::take(word));
1570    }
1571}
1572
1573fn push_line(
1574    words: &mut Vec<String>,
1575    bbox: (f32, f32, f32, f32),
1576    page_h: f32,
1577    cells: &mut Vec<TextCell>,
1578) {
1579    if words.is_empty() {
1580        return;
1581    }
1582    let text = std::mem::take(words).join(" ");
1583    let (l, b, r, t) = bbox;
1584    cells.push(TextCell {
1585        text,
1586        l,
1587        t: page_h - t,
1588        r,
1589        b: page_h - b,
1590    });
1591}
1592
1593/// The pdfium library, behind the `pdfium` feature (phase 5 of "Retiring
1594/// pdfium"): the render `DOCLING_RS_RENDERER=pdfium` asks for — docling's
1595/// pypdfium2 chain — the last resort for a file lopdf cannot read, and the
1596/// oracle of the raster and object-model tests. The default build has the
1597/// stub below and never links or loads pdfium.
1598#[cfg(feature = "pdfium")]
1599mod native {
1600    use super::LinkAnnot;
1601    use crate::PdfError;
1602    use image::RgbImage;
1603    use pdfium_render::prelude::*;
1604
1605    /// The bound library.
1606    pub(super) struct Lib(Pdfium);
1607    /// An open document.
1608    pub(super) struct Session<'a> {
1609        doc: PdfDocument<'a>,
1610    }
1611    /// A loaded page.
1612    pub(super) struct Page<'a>(PdfPage<'a>);
1613
1614    /// Try binding pdfium from a directory (or a literal library file path):
1615    /// `<dir>/<platform library name>` first, else `<dir>` itself as the file.
1616    fn try_bind_dir(path: &str) -> Option<Box<dyn PdfiumLibraryBindings>> {
1617        let name = Pdfium::pdfium_platform_library_name_at_path(path);
1618        if let Ok(b) = Pdfium::bind_to_library(&name) {
1619            return Some(b);
1620        }
1621        Pdfium::bind_to_library(path).ok()
1622    }
1623
1624    /// Bind to the pdfium dynamic library. Honors `PDFIUM_DYNAMIC_LIB_PATH` (a
1625    /// directory or file) first; else falls back to `.pdfium/lib` relative to
1626    /// the current directory (the layout `scripts/install/pdf_setup.sh`
1627    /// produces); else the system library.
1628    pub(super) fn bind() -> Result<Lib, PdfError> {
1629        if let Some(path) = docling_core::env::nonempty("PDFIUM_DYNAMIC_LIB_PATH") {
1630            if let Some(b) = try_bind_dir(&path) {
1631                return Ok(Lib(Pdfium::new(b)));
1632            }
1633        }
1634        if let Some(b) = try_bind_dir(&crate::resolve_asset(".pdfium/lib")) {
1635            return Ok(Lib(Pdfium::new(b)));
1636        }
1637        Pdfium::bind_to_system_library()
1638            .map(|b| Lib(Pdfium::new(b)))
1639            .map_err(Into::into)
1640    }
1641
1642    /// `bind()` for unit tests: point `PDFIUM_DYNAMIC_LIB_PATH` at the
1643    /// repo-root `.pdfium/lib` first (tests run with CWD = the crate dir,
1644    /// where the CWD-relative default cannot see it).
1645    #[cfg(test)]
1646    pub(crate) fn bind_for_tests() -> Result<Pdfium, PdfError> {
1647        if std::env::var_os("PDFIUM_DYNAMIC_LIB_PATH").is_none() {
1648            let lib = std::path::Path::new(env!("CARGO_MANIFEST_DIR")).join("../../.pdfium/lib");
1649            if lib.is_dir() {
1650                std::env::set_var("PDFIUM_DYNAMIC_LIB_PATH", &lib);
1651            }
1652        }
1653        bind().map(|l| l.0)
1654    }
1655
1656    impl Lib {
1657        pub(super) fn open<'a>(
1658            &'a self,
1659            bytes: &'a [u8],
1660            password: Option<&str>,
1661        ) -> Result<Session<'a>, PdfError> {
1662            crate::timing::timed("pdfium.open", || {
1663                self.0
1664                    .load_pdf_from_byte_slice(bytes, password)
1665                    .map(|doc| Session { doc })
1666                    .map_err(Into::into)
1667            })
1668        }
1669    }
1670
1671    impl Session<'_> {
1672        pub(super) fn page_count(&self) -> usize {
1673            self.doc.pages().len() as usize
1674        }
1675
1676        pub(super) fn page(&self, index: usize) -> Result<Page<'_>, PdfError> {
1677            self.doc
1678                .pages()
1679                .get(index as PdfPageIndex)
1680                .map(Page)
1681                .map_err(Into::into)
1682        }
1683    }
1684
1685    impl Page<'_> {
1686        /// The display size in points.
1687        pub(super) fn size(&self) -> (f32, f32) {
1688            (self.0.width().value, self.0.height().value)
1689        }
1690
1691        /// pdfium's view of the page's geometry, for the files lopdf cannot
1692        /// read — the same numbers `pdf_meta` computes from the object model.
1693        pub(super) fn geom(&self) -> crate::pdf_meta::PageGeom {
1694            crate::pdf_meta::PageGeom {
1695                width: self.0.width().value,
1696                height: self.0.height().value,
1697                rotation: match self.0.rotation() {
1698                    Ok(PdfPageRenderRotation::Degrees90) => 90u16,
1699                    Ok(PdfPageRenderRotation::Degrees180) => 180,
1700                    Ok(PdfPageRenderRotation::Degrees270) => 270,
1701                    _ => 0,
1702                },
1703            }
1704        }
1705
1706        /// Render the page into a `w` × `h` RGB bitmap under timing `stage`.
1707        pub(super) fn render(
1708            &self,
1709            w: i32,
1710            h: i32,
1711            stage: &'static str,
1712        ) -> Result<RgbImage, PdfError> {
1713            let cfg = PdfRenderConfig::new()
1714                .set_target_width(w)
1715                .set_target_height(h);
1716            crate::timing::timed(stage, || {
1717                self.0
1718                    .render_with_config(&cfg)
1719                    .map(|b| b.as_image().into_rgb8())
1720                    .map_err(Into::into)
1721            })
1722        }
1723
1724        /// Collect web/mail/tel hyperlink annotations on the page, mapping
1725        /// each link's rectangle into top-left page coordinates (like
1726        /// [`super::TextCell`]). `file://` and in-document destinations are
1727        /// skipped — only externally meaningful targets are rendered. pdfium
1728        /// occasionally lists a link twice; rects are kept as-is and the
1729        /// caller dedupes by resolved anchor text.
1730        pub(super) fn links(&self, page_h: f32) -> Vec<LinkAnnot> {
1731            let mut out = Vec::new();
1732            for link in self.0.links().iter() {
1733                let Some(uri) = link
1734                    .action()
1735                    .and_then(|a| a.as_uri_action().and_then(|u| u.uri().ok()))
1736                else {
1737                    continue;
1738                };
1739                let scheme_ok = ["http://", "https://", "mailto:", "tel:"]
1740                    .iter()
1741                    .any(|s| uri.starts_with(s));
1742                if !scheme_ok {
1743                    continue;
1744                }
1745                if let Ok(rect) = link.rect() {
1746                    out.push(LinkAnnot {
1747                        l: rect.left().value,
1748                        t: page_h - rect.top().value,
1749                        r: rect.right().value,
1750                        b: page_h - rect.bottom().value,
1751                        uri,
1752                    });
1753                }
1754            }
1755            out
1756        }
1757    }
1758}
1759
1760/// The `pdfium`-less build: pdfium never binds, so every entry point falls
1761/// through to the pure-Rust stack, and a file the object model cannot read
1762/// fails with [`no_raster`]'s hint.
1763#[cfg(all(feature = "render", not(feature = "pdfium")))]
1764mod native {
1765    use super::LinkAnnot;
1766    use crate::PdfError;
1767    use image::RgbImage;
1768    use std::convert::Infallible;
1769    use std::marker::PhantomData;
1770
1771    pub(super) struct Lib(Infallible);
1772    pub(super) struct Session<'a>(Infallible, PhantomData<&'a ()>);
1773    pub(super) struct Page<'a>(Infallible, PhantomData<&'a ()>);
1774
1775    /// Reached only for a file the pure-Rust object model could not read
1776    /// (every entry point tries it first), so the error is about the file:
1777    /// naming the missing library sent users of a corrupt or non-PDF upload
1778    /// looking for a pdfium install that would not have helped either.
1779    pub(super) fn bind() -> Result<Lib, PdfError> {
1780        Err(PdfError::Document(crate::UNREADABLE.into()))
1781    }
1782
1783    impl Lib {
1784        pub(super) fn open<'a>(
1785            &'a self,
1786            _bytes: &'a [u8],
1787            _password: Option<&str>,
1788        ) -> Result<Session<'a>, PdfError> {
1789            match self.0 {}
1790        }
1791    }
1792
1793    impl Session<'_> {
1794        pub(super) fn page_count(&self) -> usize {
1795            match self.0 {}
1796        }
1797
1798        pub(super) fn page(&self, _index: usize) -> Result<Page<'_>, PdfError> {
1799            match self.0 {}
1800        }
1801    }
1802
1803    impl Page<'_> {
1804        pub(super) fn size(&self) -> (f32, f32) {
1805            match self.0 {}
1806        }
1807
1808        pub(super) fn geom(&self) -> crate::pdf_meta::PageGeom {
1809            match self.0 {}
1810        }
1811
1812        pub(super) fn render(
1813            &self,
1814            _w: i32,
1815            _h: i32,
1816            _stage: &'static str,
1817        ) -> Result<RgbImage, PdfError> {
1818            match self.0 {}
1819        }
1820
1821        pub(super) fn links(&self, _page_h: f32) -> Vec<LinkAnnot> {
1822            match self.0 {}
1823        }
1824    }
1825}
1826
1827#[cfg(all(test, feature = "pdfium"))]
1828pub(crate) use native::bind_for_tests;
1829
1830#[cfg(test)]
1831mod tests {
1832    use super::{checked_render_dims, max_render_side, to_display_frame};
1833
1834    /// #897: the adaptive schedule starts renders eagerly for the first
1835    /// pages, then while at least half of the last 8 verdicts read the
1836    /// bitmap; a declined page that turns out to read it counts as read.
1837    #[cfg(feature = "render")]
1838    #[test]
1839    fn adaptive_verdicts() {
1840        let v = super::Verdicts::default();
1841        assert!(v.start_eagerly(), "no verdict yet");
1842        v.record(false, false);
1843        v.record(false, false);
1844        assert!(v.start_eagerly(), "still warming up");
1845        v.record(false, false);
1846        assert!(!v.start_eagerly(), "three text-only pages");
1847        v.record(true, true); // the last declined one was read after all
1848        v.record(true, false);
1849        assert!(v.start_eagerly(), "2 of 4 read");
1850        for _ in 0..8 {
1851            v.record(false, false);
1852        }
1853        assert!(!v.start_eagerly(), "the window forgets the read ones");
1854        for _ in 0..4 {
1855            v.record(true, false);
1856        }
1857        assert!(v.start_eagerly(), "4 of the last 8 read");
1858    }
1859
1860    /// The pure-Rust object model must answer exactly what pdfium answers —
1861    /// page count, display size, `/Rotate`, URI links — on every corpus PDF,
1862    /// or a checkout without pdfium would convert differently. Needs the
1863    /// library; skips cleanly without it (CI has no pdfium).
1864    #[test]
1865    #[cfg(feature = "pdfium")]
1866    fn pdf_meta_matches_pdfium_on_the_corpus() {
1867        let Ok(_) = super::bind_for_tests() else {
1868            eprintln!("skipping: pdfium not found");
1869            return;
1870        };
1871        let lib = super::native::bind().unwrap();
1872        let root = std::path::Path::new(env!("CARGO_MANIFEST_DIR")).join("../..");
1873        let mut files: Vec<std::path::PathBuf> = Vec::new();
1874        for dir in ["tests/data/pdf/sources", "tests/data/scanned/sources"] {
1875            let Ok(rd) = std::fs::read_dir(root.join(dir)) else {
1876                continue;
1877            };
1878            files.extend(
1879                rd.flatten()
1880                    .map(|e| e.path())
1881                    .filter(|p| p.extension().is_some_and(|e| e == "pdf")),
1882            );
1883        }
1884        files.sort();
1885        assert!(!files.is_empty(), "corpus not found");
1886        let mut checked = 0;
1887        for path in files {
1888            let bytes = std::fs::read(&path).unwrap();
1889            let Ok(doc) = lib.open(&bytes, None) else {
1890                continue; // password fixtures etc.
1891            };
1892            let Some(meta) = crate::pdf_meta::PdfMeta::open(&bytes) else {
1893                panic!(
1894                    "{}: lopdf could not read a file pdfium reads",
1895                    path.display()
1896                );
1897            };
1898            assert_eq!(meta.page_count(), doc.page_count(), "{}", path.display());
1899            for i in 0..meta.page_count() {
1900                let page = doc.page(i).unwrap();
1901                let want = page.geom();
1902                let got = meta.geometry(i).unwrap();
1903                assert!(
1904                    (got.width - want.width).abs() < 0.01
1905                        && (got.height - want.height).abs() < 0.01
1906                        && got.rotation == want.rotation,
1907                    "{} p{}: meta {got:?} vs pdfium {want:?}",
1908                    path.display(),
1909                    i + 1
1910                );
1911                let mut want_links = page.links(want.unrotated().1);
1912                let mut got_links = meta.links(i);
1913                let key = |l: &super::LinkAnnot| {
1914                    (
1915                        l.uri.clone(),
1916                        (l.l * 10.0) as i64,
1917                        (l.t * 10.0) as i64,
1918                        (l.r * 10.0) as i64,
1919                        (l.b * 10.0) as i64,
1920                    )
1921                };
1922                want_links.sort_by_key(key);
1923                got_links.sort_by_key(key);
1924                let want_keys: Vec<_> = want_links.iter().map(key).collect();
1925                let got_keys: Vec<_> = got_links.iter().map(key).collect();
1926                assert_eq!(got_keys, want_keys, "{} p{}: links", path.display(), i + 1);
1927                checked += 1;
1928            }
1929        }
1930        eprintln!("pdf_meta checked against pdfium on {checked} pages");
1931    }
1932
1933    /// A page whose declared size renders past the per-side cap is rejected
1934    /// with a recoverable error, before pdfium or `image` allocates the
1935    /// multi-gigabyte bitmap that would otherwise abort the process; a normal
1936    /// page passes through with its dimensions rounded to `i32`.
1937    #[test]
1938    fn oversized_render_is_rejected_not_allocated() {
1939        let cap = f64::from(max_render_side());
1940        // A 12000 pt box at the pipeline's 3x supersample is 36000 px/side.
1941        let huge = checked_render_dims(cap + 1.0, 10.0, 1);
1942        assert!(huge.is_err(), "over-cap width must be rejected");
1943        let tall = checked_render_dims(10.0, cap + 1.0, 7);
1944        assert!(tall.is_err(), "over-cap height must be rejected");
1945        assert!(
1946            tall.unwrap_err().to_string().contains("page 7"),
1947            "the error names the offending page"
1948        );
1949        // A Letter page at 2x supersample (612x792 pt -> 1836x2376 px) is fine.
1950        assert_eq!(
1951            checked_render_dims(1836.4, 2375.6, 1).unwrap(),
1952            (1836, 2376)
1953        );
1954        // Exactly at the cap is allowed; a zero-or-negative size floors to 1.
1955        assert_eq!(
1956            checked_render_dims(cap, cap, 1).unwrap(),
1957            (cap as i32, cap as i32)
1958        );
1959        assert_eq!(checked_render_dims(0.0, 0.0, 1).unwrap(), (1, 1));
1960    }
1961
1962    /// A 612×792 portrait page displayed under `/Rotate`: a rect near the
1963    /// unrotated top-left lands where a viewer shows it (docling#4008).
1964    #[test]
1965    fn display_frame_follows_the_page_rotation() {
1966        let r = (72.0, 63.0, 387.0, 74.0); // top-left origin, unrotated
1967        assert_eq!(to_display_frame(r, 0, 612.0, 792.0), r);
1968        // 90° clockwise: the page becomes 792×612; the old top edge is the
1969        // display right edge, old left edge the display top.
1970        assert_eq!(
1971            to_display_frame(r, 90, 612.0, 792.0),
1972            (718.0, 72.0, 729.0, 387.0)
1973        );
1974        // 180°: both axes mirror inside the same box.
1975        assert_eq!(
1976            to_display_frame(r, 180, 612.0, 792.0),
1977            (225.0, 718.0, 540.0, 729.0)
1978        );
1979        // 270°: the old top edge is the display left edge, old right edge the
1980        // display top.
1981        assert_eq!(
1982            to_display_frame(r, 270, 612.0, 792.0),
1983            (63.0, 225.0, 74.0, 540.0)
1984        );
1985    }
1986
1987    #[test]
1988    fn display_frame_rotations_compose_to_identity() {
1989        let r = (10.0, 20.0, 110.0, 40.0);
1990        // 90° then 270° from the intermediate (792×612) box round-trips.
1991        let once = to_display_frame(r, 90, 612.0, 792.0);
1992        assert_eq!(to_display_frame(once, 270, 792.0, 612.0), r);
1993        let twice = to_display_frame(to_display_frame(r, 180, 612.0, 792.0), 180, 612.0, 792.0);
1994        assert_eq!(twice, r);
1995    }
1996}