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