docling/converter.rs
1//! The top-level `DocumentConverter`.
2
3use std::collections::HashSet;
4use std::path::PathBuf;
5
6use crate::backend::{
7 is_deepseek_markdown, AbwBackend, AsciiDocBackend, CsvBackend, DeclarativeBackend,
8 DeepSeekBackend, DocBackend, DoclingJsonBackend, DocxBackend, EbcdicBackend, EmailBackend,
9 EpubBackend, InterchangeBackend, JatsBackend, LatexBackend, LotusBackend, MarkdownBackend,
10 MhtmlBackend, PptBackend, PptxBackend, QuattroBackend, RtfBackend, StarOffice5Backend,
11 UsptoBackend, VisioBackend, WebVttBackend, WpdBackend, WpsBackend, XlsBackend, XlsxBackend,
12};
13
14/// Drop the embedded image bytes from every picture — the flat nodes and the
15/// item tree alike — for [`DocumentConverter::keep_picture_images`]`(false)`.
16/// The picture items stay (caption, OCR text, classification, geometry);
17/// only their payload goes, so the JSON writes no `image` and Markdown's
18/// embedded mode prints the placeholder.
19fn strip_picture_images(document: &mut docling_core::DoclingDocument) {
20 document.for_each_picture_mut(&mut |node| {
21 if let docling_core::Node::Picture { image, .. } = node {
22 *image = None;
23 }
24 });
25 if let Some(tree) = document.tree.as_mut() {
26 for item in tree.items.iter_mut() {
27 if let docling_core::tree::TreeKind::Picture { image, .. } = &mut item.kind {
28 *image = None;
29 }
30 }
31 }
32}
33
34/// The picture-OCR reader (#645): the OCR models behind the size floor and
35/// the classifier filter, with a by-bytes cache so the same image embedded
36/// twice is read once. Built by [`DocumentConverter::picture_reader`].
37#[cfg(feature = "pdf")]
38struct PictureReader {
39 pipeline: docling_pdf::Pipeline,
40 min_side: u32,
41 classes: Vec<String>,
42 cache: std::collections::HashMap<u64, Option<docling_core::PictureDescription>>,
43}
44
45#[cfg(feature = "pdf")]
46impl PictureReader {
47 /// The text read off `img`, as the picture's description annotation;
48 /// `None` when the picture is skipped (too small, filtered out by its
49 /// class) or carries no text.
50 fn read(
51 &mut self,
52 img: &docling_core::PictureImage,
53 ) -> Option<docling_core::PictureDescription> {
54 use std::hash::{Hash, Hasher};
55 let mut h = std::collections::hash_map::DefaultHasher::new();
56 img.data.hash(&mut h);
57 let key = h.finish();
58 if let Some(hit) = self.cache.get(&key) {
59 return hit.clone();
60 }
61 let text = self.read_uncached(img);
62 self.cache.insert(key, text.clone());
63 text
64 }
65
66 fn read_uncached(
67 &mut self,
68 img: &docling_core::PictureImage,
69 ) -> Option<docling_core::PictureDescription> {
70 // The declared size is a hint; the decoded one is the truth
71 // (a 16 × 16 icon is skipped before any inference).
72 if img.width.min(img.height) < self.min_side && img.width * img.height > 0 {
73 return None;
74 }
75 let decoded = match self.pipeline.decode_picture(&img.data) {
76 Ok(d) => d,
77 Err(e) => {
78 docling_core::debug_log!("docling: picture OCR: undecodable image: {e}");
79 return None;
80 }
81 };
82 if decoded.width().min(decoded.height()) < self.min_side {
83 return None;
84 }
85 // The loader warned once when the classifier is missing; an
86 // unclassifiable picture is read rather than silently skipped.
87 if !self.classes.is_empty() {
88 if let Some(preds) = self.pipeline.classify_picture(&decoded) {
89 let top = preds.first().map(|p| p.class_name.as_str());
90 if !top.is_some_and(|t| self.classes.iter().any(|c| c == t)) {
91 return None;
92 }
93 }
94 }
95 match self.pipeline.ocr_picture(&decoded) {
96 Ok(Some(t)) => Some(docling_core::PictureDescription {
97 text: t.text,
98 provenance: t.provenance.to_string(),
99 }),
100 Ok(None) => None,
101 Err(e) => {
102 eprintln!("warning: picture OCR failed: {e}");
103 None
104 }
105 }
106 }
107}
108
109/// Without the `pdf` feature there is no reader; the type exists so the
110/// callers compile unchanged.
111#[cfg(not(feature = "pdf"))]
112struct PictureReader;
113
114#[cfg(not(feature = "pdf"))]
115impl PictureReader {
116 fn read(
117 &mut self,
118 _img: &docling_core::PictureImage,
119 ) -> Option<docling_core::PictureDescription> {
120 None
121 }
122}
123
124/// The image type by its magic bytes, for the four the vision endpoints
125/// take (OpenAI's `image_url` set: PNG, JPEG, GIF, WebP) plus BMP and TIFF,
126/// which [`endpoint_image`] re-encodes.
127#[cfg(feature = "vlm")]
128fn image_mimetype(bytes: &[u8]) -> Option<&'static str> {
129 match bytes {
130 [0x89, b'P', b'N', b'G', ..] => Some("image/png"),
131 [0xFF, 0xD8, 0xFF, ..] => Some("image/jpeg"),
132 [b'G', b'I', b'F', b'8', ..] => Some("image/gif"),
133 [b'R', b'I', b'F', b'F', _, _, _, _, b'W', b'E', b'B', b'P', ..] => Some("image/webp"),
134 [b'B', b'M', ..] => Some("image/bmp"),
135 [b'I', b'I', 0x2A, 0x00, ..] | [b'M', b'M', 0x00, 0x2A, ..] => Some("image/tiff"),
136 _ => None,
137 }
138}
139
140/// `img` as the endpoint takes it: PNG/JPEG/GIF/WebP bytes as they are
141/// (the type read off the bytes, not the declared one — an office file's
142/// `image/jpg` or a mislabelled PNG), BMP/TIFF re-encoded as PNG, anything
143/// else (EMF/WMF, SVG, …) `None`.
144#[cfg(feature = "vlm")]
145fn endpoint_image(
146 img: &docling_core::PictureImage,
147) -> Option<(&'static str, std::borrow::Cow<'_, [u8]>)> {
148 match image_mimetype(&img.data)? {
149 m @ ("image/png" | "image/jpeg" | "image/gif" | "image/webp") => {
150 Some((m, std::borrow::Cow::Borrowed(&img.data)))
151 }
152 _ => {
153 let decoded = image::load_from_memory(&img.data).ok()?;
154 let mut buf = std::io::Cursor::new(Vec::new());
155 decoded.write_to(&mut buf, image::ImageFormat::Png).ok()?;
156 Some(("image/png", std::borrow::Cow::Owned(buf.into_inner())))
157 }
158 }
159}
160
161/// Whether `text` begins with an XML prolog — an `<?xml …?>` declaration or a
162/// non-HTML `<!DOCTYPE …>`. Used to route XML documents that arrived with a
163/// text/Markdown extension (e.g. a JATS article saved as `.txt`) to the XML
164/// backends. An HTML5 `<!DOCTYPE html>` is deliberately excluded.
165fn looks_like_xml(text: &str) -> bool {
166 let head = text.trim_start();
167 if head.starts_with("<?xml") {
168 return true;
169 }
170 if let Some(rest) = head.get(..9) {
171 if rest.eq_ignore_ascii_case("<!doctype") {
172 return !head[9..]
173 .trim_start()
174 .to_ascii_lowercase()
175 .starts_with("html");
176 }
177 }
178 false
179}
180
181/// Whether an XML document is a JATS article: a JATS DOCTYPE, or an
182/// `<article` root element (JATS files in the wild often carry no DOCTYPE).
183fn looks_like_jats(bytes: &[u8]) -> bool {
184 let head = String::from_utf8_lossy(&bytes[..bytes.len().min(4000)]);
185 has_jats_doctype(&head) || head.contains("<article")
186}
187
188/// Pick the concrete XML backend for a generic `.xml` source by sniffing its
189/// DOCTYPE / root element (the first part of the file).
190/// docling's `_guess_from_content` JATS rule for an `application/xml` input:
191/// the `<!DOCTYPE …>` declaration names a JATS DTD.
192fn has_jats_doctype(text: &str) -> bool {
193 let Some(start) = text.find("<!DOCTYPE ") else {
194 return false;
195 };
196 let Some(len) = text[start..].find('>') else {
197 return false;
198 };
199 let doctype = &text[start..start + len];
200 doctype.contains("JATS-journalpublishing") || doctype.contains("JATS-archive")
201}
202
203fn sniff_xml(bytes: &[u8]) -> InputFormat {
204 // Lossy over the raw head (docling#4038, 2.122): the window can cut a
205 // well-formed file mid-codepoint — a fixed-offset `&str` slice would
206 // panic on that char boundary — and an XML document may legitimately
207 // declare a non-UTF-8 encoding. Every marker matched below is ASCII, so
208 // replacement characters cannot change the outcome.
209 let head = String::from_utf8_lossy(&bytes[..bytes.len().min(4000)]);
210 let head = head.as_ref();
211 // Case-insensitive: USPTO DOCTYPE/root casing varies in the wild (docling
212 // PR #3801 — Grant Full Text v2.5 files were missed on casing).
213 let lower = head.to_ascii_lowercase();
214 if lower.contains("us-patent")
215 || lower.contains("patent-application-publication")
216 || lower.contains("patdoc")
217 || lower.contains("<pap-v1")
218 {
219 InputFormat::XmlUspto
220 } else if head.contains("<doclang") {
221 // A bare DocLang document saved as `.xml` (docling names them
222 // `*.dclg.xml`, whose final extension is plain `xml`).
223 InputFormat::XmlDoclang
224 } else if crate::backend::feed::looks_like_feed(head) {
225 // An RSS / Atom / RDF feed (#678), by its root element.
226 InputFormat::Feed
227 } else if crate::backend::xbrl::looks_like_xbrl(head) {
228 InputFormat::XmlXbrl
229 } else {
230 InputFormat::XmlJats
231 }
232}
233use crate::error::ConversionError;
234use crate::format::InputFormat;
235use crate::result::{ConversionResult, ConversionStatus};
236use crate::source::SourceDocument;
237#[cfg(feature = "pdf")]
238use crate::stream::MarkdownStream;
239#[cfg(feature = "pdf")]
240use docling_core::{ImageMode, MarkdownExportOptions};
241
242/// Routes a [`SourceDocument`] to the backend for its format and returns a
243/// [`ConversionResult`].
244///
245/// The Rust analogue of `docling.document_converter.DocumentConverter`. In
246/// Phase 0 the format→backend dispatch is a direct match; the Python notion of
247/// per-format `FormatOption` (backend + pipeline + options) arrives with the
248/// PDF/ML pipeline in a later phase.
249#[derive(Debug, Clone)]
250pub struct DocumentConverter {
251 allowed_formats: Option<HashSet<InputFormat>>,
252 strict: bool,
253 /// Which image references the declarative backends may resolve (#646):
254 /// the tier, the remote host allow-list and the limit overrides. See
255 /// [`Self::image_sources`]; [`Self::fetch_images`] is the pre-#646 switch.
256 image_sources: crate::ImageSources,
257 image_hosts: Vec<String>,
258 image_limits: ImageLimitOverrides,
259 list_attachments: bool,
260 /// Omit empty cells from sparse spreadsheet table grids (#271, XLSX/XLS
261 /// family; opt-in docling.rs extension).
262 skip_empty_cells: bool,
263 /// Emit Markdown tables in the compact `| a | b |` form instead of the
264 /// width-padded GitHub serializer (#271, opt-in docling.rs extension).
265 compact_tables: bool,
266 /// Render pictures' alt text in Markdown and HTML (#676). See
267 /// [`Self::picture_alt_text`].
268 picture_alt_text: bool,
269 /// Where the document's metadata goes in the exports (#679). See
270 /// [`Self::metadata_output`].
271 metadata_output: docling_core::MetadataOutput,
272 /// docling-core's `MarkdownParams.page_break_placeholder`: text inserted
273 /// between pages in the Markdown export; `None` (default) omits breaks.
274 page_break_placeholder: Option<String>,
275 /// EBCDIC copybook layout (#252): inline JSON or a file path. `None`
276 /// falls back to the `<stem>.layout.json` sidecar.
277 ebcdic_layout: Option<String>,
278 no_table_former: bool,
279 no_text_panels: bool,
280 /// The text layer only, no models (#611: `--text-layer-only`, the
281 /// pre-2.0 `--no-ocr`).
282 text_layer_only: bool,
283 /// Skip OCR, keep layout and tables — docling's `do_ocr=False` (#611:
284 /// `--no-ocr`, `--skip-ocr`).
285 no_ocr: bool,
286 /// The password of an encrypted PDF (#611) or Office document (#625).
287 password: Option<String>,
288 force_full_page_ocr: bool,
289 /// OCR mode id (docling's `OcrMode`, #254); parsed at the ML call sites.
290 ocr_mode: Option<String>,
291 /// OCR engine id (`ppocr` | `tesseract`, #460); parsed at the ML call
292 /// sites.
293 ocr_engine: Option<String>,
294 /// OCR render scale in px/pt (#254); validated at the ML call sites.
295 ocr_scale: Option<f32>,
296 /// RapidOCR's line orientation handling (#666); `None` = the
297 /// environment's default. See [`Self::ocr_textline_orientation`].
298 ocr_textline_orientation: Option<bool>,
299 /// Picture-crop / page-image scale in px/pt (docling's `images_scale`,
300 /// #520); `None` = the pipeline's 2.0 render.
301 images_scale: Option<f32>,
302 /// Keep page renders as the document's page images (docling's
303 /// `generate_page_images`, #520).
304 generate_page_images: bool,
305 /// Infer PDF/image section-header levels after assembly (#302, docling's
306 /// `HeadingHierarchyModel`): bookmarks > numbering > font style. Off by
307 /// default — heading levels then stay exactly as detected.
308 heading_hierarchy: bool,
309 use_web_browser: bool,
310 /// Named Whisper model preset for audio sources (docling's ASR model
311 /// specs, PR #3741): English-only / Distil-Whisper variants under
312 /// `.models/asr/<preset>/`. `None` = the default Whisper tiny.
313 asr_model: Option<String>,
314 asr_lang: Option<String>,
315 /// Max sampled frames per video (#138 Phase 2). `None` = the default
316 /// ([`DEFAULT_VIDEO_FRAMES`]); `Some(0)` disables frame extraction;
317 /// [`ALL_VIDEO_FRAMES`] keeps every distinct cut (#647).
318 video_frames: Option<usize>,
319 /// ffmpeg's scene score a video frame must exceed to count as a cut
320 /// (#647); `None` = `DOCLING_RS_VIDEO_SCENE_THRESHOLD`, else 0.27.
321 video_scene_threshold: Option<f32>,
322 /// Cap on a sampled frame's longer side in px (#647); `None` =
323 /// `DOCLING_RS_VIDEO_FRAME_MAX_SIDE`, else the source resolution.
324 video_frame_max_side: Option<u32>,
325 /// Hamming distance under which a frame's difference hash makes it a
326 /// duplicate of a kept one (#647); `None` = `DOCLING_RS_VIDEO_FRAME_DEDUPE`,
327 /// else no de-duplication.
328 video_frame_dedupe: Option<u32>,
329 /// The directory an XBRL instance's taxonomy is read from (docling's
330 /// `XBRLBackendOptions.taxonomy`); `None` = the instance's own directory.
331 xbrl_taxonomy: Option<PathBuf>,
332 /// Opt-in PDF/image enrichment models (docling's
333 /// `do_picture_classification` / `do_code_enrichment` /
334 /// `do_formula_enrichment`).
335 enrich: crate::EnrichmentOptions,
336 /// OCR the embedded pictures of non-PDF documents (#645). See
337 /// [`Self::do_picture_ocr`].
338 picture_ocr: bool,
339 /// DocumentFigureClassifier labels a picture must carry to be OCR'd;
340 /// empty = every picture. See [`Self::picture_ocr_classes`].
341 picture_ocr_classes: Vec<String>,
342 /// Smallest side (px) a picture must have to be OCR'd; `None` = the
343 /// environment's default. See [`Self::picture_ocr_min_side`].
344 picture_ocr_min_side: Option<u32>,
345 /// The picture OCR's resolution (#666); `None` = the image-input rule.
346 /// See [`Self::picture_ocr_scale`].
347 picture_ocr_scale: Option<f32>,
348 /// Keep the embedded image bytes on every picture (the default). See
349 /// [`Self::keep_picture_images`].
350 keep_picture_images: bool,
351 /// Describe the pictures through a vision endpoint (#670); `None` = off.
352 /// See [`Self::picture_description`].
353 #[cfg(feature = "vlm")]
354 picture_description: Option<crate::vlm::PictureDescriptionOptions>,
355 /// The PII redaction pass (#621), when asked for. See [`Self::redact_pii`].
356 redact: Option<docling_core::RedactionOptions>,
357 /// 1-based inclusive PDF page window (#80). See [`Self::page_range`].
358 page_range: Option<(usize, usize)>,
359 /// OCR recognition language for scanned PDF/image pages (`en`/`ch`).
360 /// `None` = the process default (`DOCLING_RS_OCR_LANG`, else English).
361 ocr_lang: Option<String>,
362 /// Character encoding for text inputs (docling's
363 /// `TextBackendOptions.encoding`); `None` = detect. See [`Self::encoding`].
364 encoding: Option<String>,
365 /// Which Jupyter notebook outputs the document keeps (#673). See
366 /// [`Self::ipynb_outputs`].
367 ipynb_outputs: crate::IpynbOutputs,
368 /// Directory referenced-mode streaming writes images into (#80).
369 /// See [`Self::artifacts_dir`].
370 artifacts_dir: String,
371 /// Per-document wall-clock budget for the PDF/image pipeline (docling's
372 /// `document_timeout`, #497). See [`Self::document_timeout`].
373 document_timeout: Option<std::time::Duration>,
374 /// Bounds on what a ZIP input may decompress (#557,
375 /// [`DocumentConverter::convert_archive`]).
376 archive_limits: crate::archive::ArchiveLimits,
377 /// The caller's long-lived ML pipeline (#669), when one was lent with
378 /// [`Self::warm_pipeline`]; `None` loads the models per conversion.
379 #[cfg(feature = "pdf")]
380 warm: Option<WarmPipeline>,
381 /// Backends registered with [`Self::register_backend`] (#680), in the
382 /// order they are tried: highest priority first, registration order
383 /// among equals.
384 backends: std::sync::Arc<Vec<crate::plugins::RegisteredBackend>>,
385}
386
387/// The builder's overrides of [`crate::ImageLimits`] (#646): `None` = the
388/// environment's value, else the default.
389#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
390struct ImageLimitOverrides {
391 max_bytes: Option<u64>,
392 max_images: Option<usize>,
393 max_total_mb: Option<u64>,
394 min_bytes: Option<u64>,
395}
396
397/// Default cap on sampled frames per video. Scene changes rarely exceed this
398/// in short clips, and uniform fallback at 8 keeps JSON/DCLX output (which
399/// embeds the PNGs) within sane bounds.
400pub const DEFAULT_VIDEO_FRAMES: usize = 8;
401
402/// The `video_frames` count meaning "every distinct cut" (#647): no cap,
403/// no even resampling of a cut-less video (its first frame alone), the
404/// scene threshold and de-duplication deciding what a distinct frame is.
405/// Any count at or above `u32::MAX` reads as this on the JSON surfaces, so
406/// a binding whose integers are 32-bit (the npm addon) can ask for it.
407pub const ALL_VIDEO_FRAMES: usize = usize::MAX;
408
409/// Parse a user-facing page-range string (issue #80's `--pages`): `"A-B"` for
410/// an inclusive 1-based window, or a single `"N"` for one page. Whitespace
411/// around the numbers is tolerated. Validation against the actual page count
412/// happens at convert time; this only checks the spelling (`first >= 1`,
413/// `first <= last`).
414pub fn parse_page_range(s: &str) -> Result<(usize, usize), String> {
415 let parse_one = |part: &str| {
416 part.trim()
417 .parse::<usize>()
418 .map_err(|_| format!("invalid page number '{}'", part.trim()))
419 };
420 let (first, last) = match s.split_once('-') {
421 Some((a, b)) => (parse_one(a)?, parse_one(b)?),
422 None => {
423 let n = parse_one(s)?;
424 (n, n)
425 }
426 };
427 if first == 0 {
428 return Err("pages are 1-based; the range starts at 1".into());
429 }
430 if last < first {
431 return Err(format!("range {first}-{last} is inverted (first <= last)"));
432 }
433 Ok((first, last))
434}
435
436/// A PDF/image ML pipeline kept loaded across conversions (#669) — what a
437/// long-lived caller (a server, an agent tool) lends its converters with
438/// [`DocumentConverter::warm_pipeline`] so the layout, TableFormer and OCR
439/// sessions load once instead of once per document. Cloning shares the
440/// pipeline; conversions on it take turns.
441///
442/// The pipeline is rebuilt only when a conversion asks for different model
443/// switches (text-layer only, OCR off, no TableFormer, no text panels, the
444/// enrichments — what a built pipeline cannot change); a panic inside a
445/// conversion discards it, so the next one starts clean.
446#[cfg(feature = "pdf")]
447#[derive(Clone, Default)]
448pub struct WarmPipeline {
449 slot: std::sync::Arc<std::sync::Mutex<WarmSlot>>,
450}
451
452#[cfg(feature = "pdf")]
453type WarmSlot = Option<(PipelineSwitches, docling_pdf::Pipeline)>;
454
455#[cfg(feature = "pdf")]
456impl WarmPipeline {
457 /// An empty handle; the models load on the first PDF/image conversion.
458 pub fn new() -> Self {
459 Self::default()
460 }
461
462 /// The pipeline for a conversion with `switches`, rebuilt when the
463 /// loaded one was built with others.
464 fn lease(
465 &self,
466 switches: PipelineSwitches,
467 ) -> Result<std::sync::MutexGuard<'_, WarmSlot>, docling_pdf::PdfError> {
468 let mut slot = self.slot.lock().unwrap_or_else(|poisoned| {
469 // A conversion panicked mid-document: its workers may hold half a
470 // page — start from a fresh pipeline rather than reuse them.
471 let mut slot = poisoned.into_inner();
472 *slot = None;
473 slot
474 });
475 self.slot.clear_poison();
476 if slot.as_ref().map(|(built, _)| *built) != Some(switches) {
477 // Drop the old models before the new ones load, not after.
478 *slot = None;
479 *slot = Some((switches, switches.build()?));
480 }
481 Ok(slot)
482 }
483}
484
485#[cfg(feature = "pdf")]
486impl std::fmt::Debug for WarmPipeline {
487 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
488 let loaded = match self.slot.try_lock() {
489 Ok(slot) => format!("{:?}", slot.as_ref().map(|(switches, _)| switches)),
490 Err(_) => "in use".to_string(),
491 };
492 f.debug_struct("WarmPipeline")
493 .field("loaded", &loaded)
494 .finish()
495 }
496}
497
498/// What a built [`docling_pdf::Pipeline`] cannot change: the model set it
499/// loads. Every other setting is applied per conversion.
500#[cfg(feature = "pdf")]
501#[derive(Clone, Copy, Debug, PartialEq, Eq)]
502struct PipelineSwitches {
503 text_layer_only: bool,
504 no_ocr: bool,
505 no_table_former: bool,
506 no_text_panels: bool,
507 enrich: crate::EnrichmentOptions,
508}
509
510#[cfg(feature = "pdf")]
511impl PipelineSwitches {
512 fn of(c: &DocumentConverter) -> Self {
513 Self {
514 text_layer_only: c.text_layer_only,
515 no_ocr: c.no_ocr,
516 no_table_former: c.no_table_former,
517 no_text_panels: c.no_text_panels,
518 enrich: c.enrich,
519 }
520 }
521
522 fn build(self) -> Result<docling_pdf::Pipeline, docling_pdf::PdfError> {
523 Ok(docling_pdf::Pipeline::new()?
524 .no_table_former(self.no_table_former)
525 // docling-pdf's `Pipeline` keeps its pre-2.0 names: its `no_ocr`
526 // is the text-layer fast path, its `skip_ocr` docling's do_ocr=False.
527 .no_ocr(self.text_layer_only)
528 .skip_ocr(self.no_ocr)
529 .no_text_panels(self.no_text_panels)
530 .enrichments(self.enrich))
531 }
532}
533
534/// A conversion's pipeline: its own, or the warm one held for the call.
535#[cfg(feature = "pdf")]
536enum PipelineLease<'a> {
537 Fresh(Box<docling_pdf::Pipeline>),
538 Warm(std::sync::MutexGuard<'a, WarmSlot>),
539}
540
541#[cfg(feature = "pdf")]
542impl std::ops::Deref for PipelineLease<'_> {
543 type Target = docling_pdf::Pipeline;
544
545 fn deref(&self) -> &Self::Target {
546 match self {
547 Self::Fresh(p) => p,
548 Self::Warm(slot) => &slot.as_ref().expect("filled by the lease").1,
549 }
550 }
551}
552
553#[cfg(feature = "pdf")]
554impl std::ops::DerefMut for PipelineLease<'_> {
555 fn deref_mut(&mut self) -> &mut Self::Target {
556 match self {
557 Self::Fresh(p) => p,
558 Self::Warm(slot) => &mut slot.as_mut().expect("filled by the lease").1,
559 }
560 }
561}
562
563impl Default for DocumentConverter {
564 fn default() -> Self {
565 Self {
566 allowed_formats: None,
567 strict: false,
568 image_sources: crate::ImageSources::None,
569 image_hosts: Vec::new(),
570 image_limits: ImageLimitOverrides::default(),
571 list_attachments: false,
572 skip_empty_cells: false,
573 compact_tables: false,
574 picture_alt_text: false,
575 metadata_output: Default::default(),
576 page_break_placeholder: None,
577 ebcdic_layout: None,
578 no_table_former: false,
579 no_text_panels: false,
580 text_layer_only: false,
581 no_ocr: false,
582 password: None,
583 force_full_page_ocr: false,
584 ocr_mode: None,
585 ocr_engine: None,
586 ocr_scale: None,
587 ocr_textline_orientation: None,
588 images_scale: None,
589 generate_page_images: false,
590 heading_hierarchy: false,
591 use_web_browser: false,
592 asr_model: None,
593 asr_lang: None,
594 video_frames: None,
595 video_scene_threshold: None,
596 video_frame_max_side: None,
597 video_frame_dedupe: None,
598 xbrl_taxonomy: None,
599 enrich: crate::EnrichmentOptions::default(),
600 picture_ocr: false,
601 picture_ocr_classes: Vec::new(),
602 picture_ocr_min_side: None,
603 picture_ocr_scale: None,
604 keep_picture_images: true,
605 #[cfg(feature = "vlm")]
606 picture_description: None,
607 redact: None,
608 page_range: None,
609 ocr_lang: None,
610 encoding: None,
611 ipynb_outputs: crate::IpynbOutputs::None,
612 artifacts_dir: "artifacts".to_string(),
613 document_timeout: None,
614 archive_limits: crate::archive::ArchiveLimits::default(),
615 #[cfg(feature = "pdf")]
616 warm: None,
617 backends: std::sync::Arc::new(Vec::new()),
618 }
619 }
620}
621
622impl DocumentConverter {
623 /// A converter that accepts every supported format.
624 pub fn new() -> Self {
625 Self::default()
626 }
627
628 /// A converter restricted to an explicit set of formats. Sources of any
629 /// other format are rejected with [`ConversionError::UnsupportedFormat`].
630 pub fn with_allowed_formats(formats: impl IntoIterator<Item = InputFormat>) -> Self {
631 Self {
632 allowed_formats: Some(formats.into_iter().collect()),
633 ..Self::default()
634 }
635 }
636
637 /// Convert only PDF pages `first..=last` (**1-based** inclusive, the page
638 /// numbers a viewer shows — issue #80's `--pages A-B`). Out-of-window pages
639 /// are skipped before rasterization, so converting 3 pages of a 500-page
640 /// PDF costs 3 pages. `last` clamps to the document; a window that selects
641 /// no pages at all errors at convert time. Non-PDF formats ignore the
642 /// window (they convert whole).
643 pub fn page_range(mut self, first: usize, last: usize) -> Self {
644 self.page_range = Some((first, last));
645 self
646 }
647
648 /// A wall-clock budget per document for the PDF pipeline — docling's
649 /// `PipelineOptions.document_timeout` (#497); `None` = unlimited, the
650 /// default. The budget starts with the conversion and is checked between
651 /// pages: once spent, no further page is rendered or processed, the pages
652 /// already finished become the document, and the result is a
653 /// [`ConversionStatus::PartialSuccess`] carrying one
654 /// [`ErrorItem`](crate::ErrorItem) (`document_backend` / `pipeline`,
655 /// "document timeout of Ns exceeded after D of S pages …"). A page in
656 /// flight finishes first, so a budget shorter than one page's work still
657 /// yields that page. Only the paginated pipeline has pages to stop
658 /// between: declarative formats (Office, HTML, …) convert whole, as in
659 /// docling, and a single image is never cut. A streaming conversion
660 /// emits the pages that fit and ends with
661 /// [`ConversionError::Timeout`](crate::ConversionError::Timeout) as its
662 /// last item.
663 pub fn document_timeout(mut self, timeout: Option<std::time::Duration>) -> Self {
664 self.document_timeout = timeout;
665 self
666 }
667
668 /// OCR recognition language for scanned PDF/image pages: `"en"` (the
669 /// default — English PP-OCRv3, proper Latin word spacing) or `"ch"` (the
670 /// multilingual model docling conformance is measured with — glues Latin
671 /// words). An unknown value warns at conversion time and uses the
672 /// default; explicit `DOCLING_OCR_REC_ONNX`/`DOCLING_OCR_DICT` paths win
673 /// over this switch. Under [`ocr_engine`](Self::ocr_engine) `tesseract`
674 /// it is Tesseract's language list instead — tessdata stems (`"deu"`,
675 /// `"eng+fra"`, `"script/Cyrillic"`) or BCP-47 tags mapped onto them
676 /// (`"de"`, `"zh-Hant"`), see [`docling_pdf::tesseract_lang_arg`]; `en`
677 /// and `ch` keep working there. Formats that never OCR ignore it.
678 pub fn ocr_lang(mut self, lang: impl Into<String>) -> Self {
679 self.ocr_lang = Some(lang.into());
680 self
681 }
682
683 /// Convert on `warm`'s ML pipeline (#669) instead of loading the models
684 /// for each conversion: PDFs, images, SVG's raster route, METS pages and
685 /// a scanned DjVu's OCR fallback all run on the one instance, which keeps
686 /// its ONNX sessions between conversions. Everything else about the
687 /// conversion is this converter's — page window, password, OCR and
688 /// image settings are applied to the pipeline on every call, so nothing
689 /// carries over from the previous caller's options. Converters sharing a
690 /// handle take turns on it; the declarative formats never touch it.
691 #[cfg(feature = "pdf")]
692 pub fn warm_pipeline(mut self, warm: &WarmPipeline) -> Self {
693 self.warm = Some(warm.clone());
694 self
695 }
696
697 /// The configured ML pipeline for one conversion: a fresh one (models
698 /// load per call), or the [`warm`](Self::warm_pipeline) one this
699 /// converter was lent. Both are configured by the same setters, so the
700 /// warm path cannot drift from the cold one.
701 #[cfg(feature = "pdf")]
702 fn ml_pipeline(&self) -> Result<PipelineLease<'_>, docling_pdf::PdfError> {
703 let switches = PipelineSwitches::of(self);
704 let mut lease = match &self.warm {
705 None => PipelineLease::Fresh(Box::new(switches.build()?)),
706 Some(warm) => PipelineLease::Warm(warm.lease(switches)?),
707 };
708 self.configure_pipeline(&mut lease);
709 Ok(lease)
710 }
711
712 /// Every per-conversion setting, set unconditionally — on a warm
713 /// pipeline a setting left alone would be the previous conversion's.
714 #[cfg(feature = "pdf")]
715 fn configure_pipeline(&self, p: &mut docling_pdf::Pipeline) {
716 p.set_ocr_textline_orientation(self.ocr_textline_orientation);
717 p.set_ocr_lang(self.ocr_lang_choice());
718 p.set_ocr_engine(self.ocr_engine_choice());
719 p.set_tesseract_lang(self.tesseract_lang_choice());
720 p.set_ocr_mode(self.ocr_mode_choice());
721 p.set_ocr_scale(self.ocr_scale_choice());
722 p.set_images(docling_pdf::ImageOutput {
723 scale: self.images_scale,
724 page_images: self.generate_page_images,
725 });
726 p.set_heading_hierarchy(docling_pdf::HeadingHierarchyOptions::enabled(
727 self.heading_hierarchy,
728 ));
729 p.set_document_timeout(self.document_timeout);
730 // The PDF route sets these two for itself; every other route reads
731 // the whole input with OCR left to the layout.
732 p.set_force_full_page_ocr(false);
733 p.set_pages(None);
734 }
735
736 /// DjVu (#434): the hidden text layer by default; a scan-only DjVu (no
737 /// text layer on any selected page) falls back to rasterize + OCR when the
738 /// ML pipeline is built and OCR is not disabled, otherwise it degrades to
739 /// an empty document with a warning. See [`crate::backend::djvu`].
740 fn convert_djvu(
741 &self,
742 source: &SourceDocument,
743 ) -> Result<docling_core::DoclingDocument, ConversionError> {
744 use crate::backend::djvu;
745 let text = djvu::convert_text_layer(source, self.page_range)?;
746 if !djvu::is_text_layer_empty(&text) {
747 return Ok(text);
748 }
749 // No text layer anywhere in the selection.
750 #[cfg(feature = "pdf")]
751 if !self.text_layer_only && !self.no_ocr {
752 let pngs = djvu::rasterize_pages(&source.bytes, self.page_range)?;
753 let mut pipeline = self
754 .ml_pipeline()
755 .map_err(|e| ConversionError::with_source("djvu", e))?;
756 let mut doc = docling_core::DoclingDocument::new(&source.name);
757 for (i, (page_no, png)) in pngs.iter().enumerate() {
758 if i > 0 {
759 doc.push(docling_core::Node::PageBreak);
760 }
761 let mut page = pipeline
762 .convert_image(png, &source.name)
763 .map_err(|e| ConversionError::with_source("djvu", e))?;
764 // An image is its own page 1; the DjVu page keeps its number so
765 // a `--pages` window's JSON `pages` matches the text-layer path.
766 docling_pdf::assemble::stamp_page_no(&mut page.nodes, *page_no);
767 doc.nodes.extend(page.nodes);
768 doc.links.extend(page.links);
769 }
770 return Ok(doc);
771 }
772 eprintln!(
773 "docling: warning: DjVu '{}' has no text layer and OCR is unavailable/disabled; \
774 the document is empty",
775 source.name
776 );
777 Ok(text)
778 }
779
780 /// The parsed [`Self::ocr_lang`] choice for the ML call sites; a value
781 /// that parses to nothing warns here (once per conversion) rather than
782 /// erroring — same degradation the env selector applies.
783 #[cfg(feature = "pdf")]
784 fn ocr_lang_choice(&self) -> Option<docling_pdf::OcrLang> {
785 let raw = self.ocr_lang.as_deref()?;
786 // Under Tesseract the value is its language list, not a PP-OCR model
787 // — see `tesseract_lang_choice`.
788 if self.ocr_engine_choice() == Some(docling_pdf::OcrEngine::Tesseract) {
789 return None;
790 }
791 let parsed = docling_pdf::OcrLang::parse(raw);
792 if parsed.is_none() {
793 eprintln!(
794 "docling: ocr_lang {raw:?} names no language the OCR models read ({}); using \
795 the default",
796 docling_pdf::OcrLang::ACCEPTED
797 );
798 }
799 parsed
800 }
801
802 /// The parsed [`Self::ocr_engine`] choice (#460), with the same
803 /// warn-and-default degradation as [`ocr_lang_choice`](Self::ocr_lang_choice).
804 #[cfg(feature = "pdf")]
805 fn ocr_engine_choice(&self) -> Option<docling_pdf::OcrEngine> {
806 let raw = self.ocr_engine.as_deref()?;
807 let parsed = docling_pdf::OcrEngine::parse(raw);
808 if parsed.is_none() {
809 eprintln!(
810 "docling: ocr_engine {raw:?} is not {}; using the default",
811 docling_pdf::OcrEngine::ACCEPTED
812 );
813 }
814 parsed
815 }
816
817 /// Tesseract's `-l` argument from [`Self::ocr_lang`] (#460) when the
818 /// engine is Tesseract: an unmappable value warns and leaves Tesseract's
819 /// default language.
820 #[cfg(feature = "pdf")]
821 fn tesseract_lang_choice(&self) -> Option<String> {
822 if self.ocr_engine_choice() != Some(docling_pdf::OcrEngine::Tesseract) {
823 return None;
824 }
825 let raw = self.ocr_lang.as_deref()?;
826 match docling_pdf::tesseract_lang_arg(raw) {
827 Ok(arg) => Some(arg),
828 Err(e) => {
829 eprintln!("docling: {e}; using Tesseract's default language");
830 None
831 }
832 }
833 }
834
835 /// The parsed [`Self::ocr_mode`] choice (#254), with the same
836 /// warn-and-default degradation as [`ocr_lang_choice`](Self::ocr_lang_choice).
837 #[cfg(feature = "pdf")]
838 fn ocr_mode_choice(&self) -> Option<docling_pdf::OcrMode> {
839 let raw = self.ocr_mode.as_deref()?;
840 let parsed = docling_pdf::OcrMode::parse(raw);
841 if parsed.is_none() {
842 eprintln!(
843 "docling: ocr_mode {raw:?} is not \
844 default|full_page|layout_regions|pdf_aware_layout_regions; using the default"
845 );
846 }
847 parsed
848 }
849
850 /// The validated [`Self::ocr_scale`] (#254): non-positive/non-finite
851 /// values warn and fall back to the engine default.
852 #[cfg(feature = "pdf")]
853 fn ocr_scale_choice(&self) -> Option<f32> {
854 let s = self.ocr_scale?;
855 if !(s.is_finite() && s > 0.0) {
856 eprintln!("docling: ocr_scale {s} is not a positive number; using the default");
857 return None;
858 }
859 Some(s)
860 }
861
862 /// The validated [`Self::picture_ocr_scale`] (#666), like
863 /// [`Self::ocr_scale_choice`].
864 #[cfg(feature = "pdf")]
865 fn picture_ocr_scale_choice(&self) -> Option<f32> {
866 let s = self.picture_ocr_scale?;
867 if !(s.is_finite() && s > 0.0) {
868 eprintln!("docling: picture_ocr_scale {s} is not a positive number; using the default");
869 return None;
870 }
871 Some(s)
872 }
873
874 /// [`Self::ocr_textline_orientation`] on a pipeline (#666); unset keeps
875 /// the pipeline's `DOCLING_RS_OCR_TEXTLINE_ORIENTATION` default.
876 #[cfg(feature = "pdf")]
877 fn with_textline_orientation(&self, p: docling_pdf::Pipeline) -> docling_pdf::Pipeline {
878 match self.ocr_textline_orientation {
879 Some(enable) => p.ocr_textline_orientation(enable),
880 None => p,
881 }
882 }
883
884 /// Where [`ImageMode::Referenced`] streaming writes image files, and the
885 /// link prefix used in the Markdown (default `artifacts`, matching the
886 /// buffered export's convention). Relative paths resolve against the
887 /// process working directory.
888 pub fn artifacts_dir(mut self, dir: impl Into<String>) -> Self {
889 self.artifacts_dir = dir.into();
890 self
891 }
892
893 /// Decode text inputs (Markdown, CSV, AsciiDoc, WebVTT, LaTeX, the XML
894 /// dialects, …) with this character encoding instead of detecting one —
895 /// docling's `TextBackendOptions.encoding`
896 /// (`MarkdownBackendOptions(encoding="shift_jis")`). A WHATWG encoding
897 /// label (`shift_jis`, `koi8-r`, `windows-1251`, `latin1`; Python codec
898 /// spellings with `_` are accepted). Nothing is guessed: bytes the
899 /// encoding cannot decode fail the conversion, as does an unknown label.
900 /// `None` (default) detects — a byte-order mark, then UTF-8, then
901 /// windows-1252 (see [`SourceDocument::text`]). A source that already
902 /// carries its own [`SourceDocument::encoding`] keeps it.
903 pub fn encoding(mut self, label: Option<String>) -> Self {
904 self.encoding = label;
905 self
906 }
907
908 /// Jupyter notebooks (#673): which cell outputs the document keeps —
909 /// [`IpynbOutputs::None`](crate::IpynbOutputs::None) (the default: the
910 /// notebook as written, MarkItDown's reading) or
911 /// [`IpynbOutputs::Text`](crate::IpynbOutputs::Text): stream and
912 /// `text/plain` results as code blocks after their cell, raster image
913 /// outputs as pictures. The CLI's `--ipynb-outputs none|text`.
914 pub fn ipynb_outputs(mut self, outputs: crate::IpynbOutputs) -> Self {
915 self.ipynb_outputs = outputs;
916 self
917 }
918
919 /// The converter's [`encoding`](Self::encoding) applied to a source that
920 /// did not set its own.
921 /// Bounds on what a ZIP input may make the converter decompress (#557):
922 /// entries considered, per-entry and total uncompressed size, compression
923 /// ratio. [`ArchiveLimits::default`](crate::archive::ArchiveLimits) when
924 /// not set. Only [`DocumentConverter::convert_archive`] reads them.
925 pub fn archive_limits(mut self, limits: crate::archive::ArchiveLimits) -> Self {
926 self.archive_limits = limits;
927 self
928 }
929
930 /// Register `backend` for the sources `matcher` claims (#680), under
931 /// `name` (what format listings print). Registered backends are tried
932 /// before the built-in formats — highest `priority` first, the earliest
933 /// registration first among equals — so a backend can add a format or
934 /// take one over; its document then goes through the same
935 /// post-processing as a built-in one. An extension the built-in tables
936 /// do not know reaches a converter through [`Self::load_file`] /
937 /// [`Self::load_named_bytes`], which resolve such a source as
938 /// [`InputFormat::Plugin`]. See [`crate::plugins`].
939 ///
940 /// ```
941 /// use std::sync::Arc;
942 /// use docling::{BackendMatcher, ConversionError, DocumentConverter, SourceDocument};
943 /// use docling::backend::DeclarativeBackend;
944 /// use docling_core::{DoclingDocument, Node};
945 ///
946 /// struct Shout;
947 /// impl DeclarativeBackend for Shout {
948 /// fn convert(&self, source: &SourceDocument) -> Result<DoclingDocument, ConversionError> {
949 /// let mut doc = DoclingDocument::new(&source.name);
950 /// doc.push(Node::Paragraph { text: source.text()?.to_uppercase() });
951 /// Ok(doc)
952 /// }
953 /// }
954 ///
955 /// let converter = DocumentConverter::new().register_backend(
956 /// "shout",
957 /// BackendMatcher::new().extensions(["shout"]),
958 /// Arc::new(Shout),
959 /// 0,
960 /// );
961 /// let source = converter.load_named_bytes("note.shout", b"hello".to_vec(), None)?;
962 /// let md = converter.convert(source)?.document.export_to_markdown();
963 /// assert_eq!(md, "HELLO\n");
964 /// # Ok::<(), ConversionError>(())
965 /// ```
966 pub fn register_backend(
967 mut self,
968 name: impl Into<String>,
969 matcher: crate::plugins::BackendMatcher,
970 backend: std::sync::Arc<dyn crate::backend::DeclarativeBackend + Send + Sync>,
971 priority: i32,
972 ) -> Self {
973 let mut backends = (*self.backends).clone();
974 backends.push(crate::plugins::RegisteredBackend::new(
975 name.into(),
976 matcher,
977 backend,
978 priority,
979 ));
980 // Stable: registration order stays among equal priorities.
981 backends.sort_by_key(|b| std::cmp::Reverse(b.priority()));
982 self.backends = std::sync::Arc::new(backends);
983 self
984 }
985
986 /// The backends registered with [`Self::register_backend`], in the
987 /// order they are tried.
988 pub fn registered_backends(&self) -> &[crate::plugins::RegisteredBackend] {
989 &self.backends
990 }
991
992 /// The registered backend that claims `source`, if any.
993 fn backend_for(&self, source: &SourceDocument) -> Option<&crate::plugins::RegisteredBackend> {
994 self.backends.iter().find(|b| {
995 b.matcher().matches(
996 source.extension.as_deref(),
997 source.media_type.as_deref(),
998 &source.bytes,
999 )
1000 })
1001 }
1002
1003 /// Whether a registered backend claims `source` (the streaming path
1004 /// then converts it buffered, through [`Self::convert`]).
1005 pub(crate) fn claims(&self, source: &SourceDocument) -> bool {
1006 self.backend_for(source).is_some()
1007 }
1008
1009 /// [`SourceDocument::from_file`] that knows this converter's registered
1010 /// backends (#680): a file a registered backend claims — by extension,
1011 /// or by its bytes — loads even when the built-in tables do not know
1012 /// it, as [`InputFormat::Plugin`] (a claimed file whose extension *is*
1013 /// a built-in format keeps that format). Without registered backends,
1014 /// exactly [`SourceDocument::from_file`].
1015 pub fn load_file(
1016 &self,
1017 path: impl AsRef<std::path::Path>,
1018 ) -> Result<SourceDocument, ConversionError> {
1019 let path = path.as_ref();
1020 let bytes = std::fs::read(path)?;
1021 let ext = path
1022 .extension()
1023 .and_then(|e| e.to_str())
1024 .map(str::to_ascii_lowercase);
1025 if self
1026 .backends
1027 .iter()
1028 .any(|b| b.matcher().matches(ext.as_deref(), None, &bytes))
1029 {
1030 let format = ext
1031 .as_deref()
1032 .and_then(InputFormat::from_extension)
1033 .unwrap_or(InputFormat::Plugin);
1034 let name = path
1035 .file_stem()
1036 .and_then(|s| s.to_str())
1037 .unwrap_or("document")
1038 .to_string();
1039 let mut source = SourceDocument::from_bytes(name, format, bytes);
1040 source.extension = ext;
1041 source.path = Some(path.to_path_buf());
1042 return Ok(source);
1043 }
1044 SourceDocument::from_path_and_bytes(path, bytes)
1045 }
1046
1047 /// [`SourceDocument::from_named_bytes`] that knows this converter's
1048 /// registered backends (#680), as [`Self::load_file`] does: bytes a
1049 /// registered backend claims — by the name's extension, the media type
1050 /// or the content — load even when the built-in tables do not know
1051 /// them, as [`InputFormat::Plugin`] unless the extension or media type
1052 /// names a built-in format.
1053 pub fn load_named_bytes(
1054 &self,
1055 name: &str,
1056 bytes: Vec<u8>,
1057 media_type: Option<&str>,
1058 ) -> Result<SourceDocument, ConversionError> {
1059 let path = std::path::Path::new(name);
1060 let ext = path
1061 .extension()
1062 .and_then(|e| e.to_str())
1063 .map(str::to_ascii_lowercase);
1064 if self
1065 .backends
1066 .iter()
1067 .any(|b| b.matcher().matches(ext.as_deref(), media_type, &bytes))
1068 {
1069 let format = ext
1070 .as_deref()
1071 .and_then(InputFormat::from_extension)
1072 .or_else(|| media_type.and_then(InputFormat::from_mime))
1073 .unwrap_or(InputFormat::Plugin);
1074 let stem = path
1075 .file_stem()
1076 .and_then(|s| s.to_str())
1077 .filter(|s| !s.is_empty())
1078 .unwrap_or("document")
1079 .to_string();
1080 let mut source = SourceDocument::from_bytes(stem, format, bytes);
1081 source.extension = ext;
1082 source.media_type = media_type.map(str::to_string);
1083 return Ok(source);
1084 }
1085 SourceDocument::from_named_bytes(name, bytes, media_type)
1086 }
1087
1088 /// Every input file extension this converter takes: the build's
1089 /// built-in ones ([`InputFormat::supported_extensions`]) and those of
1090 /// its registered backends (#680) — sorted, unique, lowercase, no dot.
1091 pub fn supported_extensions(&self) -> Vec<String> {
1092 let mut out: Vec<String> = InputFormat::supported_extensions()
1093 .into_iter()
1094 .map(str::to_string)
1095 .chain(
1096 self.backends
1097 .iter()
1098 .flat_map(|b| b.matcher().extension_list().iter().cloned()),
1099 )
1100 .collect();
1101 out.sort_unstable();
1102 out.dedup();
1103 out
1104 }
1105
1106 pub(crate) fn archive_limits_ref(&self) -> crate::archive::ArchiveLimits {
1107 self.archive_limits
1108 }
1109
1110 fn with_encoding(&self, mut source: SourceDocument) -> SourceDocument {
1111 if source.encoding.is_none() {
1112 source.encoding = self.encoding.clone();
1113 }
1114 source
1115 }
1116
1117 /// Cap the number of frames sampled from a video (#138 Phase 2); `0`
1118 /// disables frame extraction entirely (Phase 1 behavior: transcript only).
1119 /// Defaults to [`DEFAULT_VIDEO_FRAMES`]. Frames are extracted with the
1120 /// `ffmpeg` binary when present (`DOCLING_FFMPEG` overrides the path);
1121 /// without it a video converts to its transcript alone.
1122 pub fn video_frames(mut self, max: usize) -> Self {
1123 self.video_frames = Some(max);
1124 self
1125 }
1126
1127 /// Keep every distinct cut of a video (#647) — [`ALL_VIDEO_FRAMES`]:
1128 /// no cap, so what bounds the picture count is the scene threshold and
1129 /// the de-duplication. Memory stays one frame at a time whatever the
1130 /// count ([`do_picture_ocr`](Self::do_picture_ocr) +
1131 /// [`keep_picture_images`](Self::keep_picture_images)`(false)` reads and
1132 /// drops each frame before the next is decoded).
1133 pub fn video_frames_all(self) -> Self {
1134 self.video_frames(ALL_VIDEO_FRAMES)
1135 }
1136
1137 /// ffmpeg's `scene` score (0–1, the normalized difference of a frame to
1138 /// its predecessor) a frame must exceed to be a cut (#647). Default
1139 /// 0.27 (`DOCLING_RS_VIDEO_SCENE_THRESHOLD` overrides it): a slide
1140 /// change in a screen recording scores well above it, a fade or a
1141 /// lighting change around 0.5, a hard cut near 1.0 — raise it to keep
1142 /// only hard cuts. Out-of-range values are clamped.
1143 pub fn video_scene_threshold(mut self, threshold: f32) -> Self {
1144 self.video_scene_threshold = Some(threshold.clamp(0.0, 1.0));
1145 self
1146 }
1147
1148 /// Downscale each sampled frame inside ffmpeg so its longer side is at
1149 /// most `px` (#647; the aspect ratio is kept, a smaller frame is left as
1150 /// it is): a 1080p recording at 640 yields 640×360 PNGs, so neither the
1151 /// embedded images nor the OCR input ever reach memory at full size.
1152 /// `0` (the default, `DOCLING_RS_VIDEO_FRAME_MAX_SIDE` overrides it) =
1153 /// the source resolution.
1154 pub fn video_frame_max_side(mut self, px: u32) -> Self {
1155 self.video_frame_max_side = Some(px);
1156 self
1157 }
1158
1159 /// Drop a sampled frame whose perceptual difference hash (64 bits over
1160 /// a 9×8 grey thumbnail) is within `max_distance` bits of a frame
1161 /// already kept (#647): the same slide after a fade, or shown again
1162 /// after a camera cut, becomes one picture. 4–6 is a good distance;
1163 /// `None` (the default, `DOCLING_RS_VIDEO_FRAME_DEDUPE` overrides it)
1164 /// keeps every sampled frame.
1165 pub fn video_frame_dedupe(mut self, max_distance: Option<u32>) -> Self {
1166 self.video_frame_dedupe = max_distance.map(|d| d.min(64));
1167 self
1168 }
1169
1170 /// The folder holding the taxonomy an XBRL instance refers to (docling's
1171 /// `XBRLBackendOptions.taxonomy`): the filing's extension schema and
1172 /// linkbases at the relative paths its `link:schemaRef` names, plus any
1173 /// taxonomy packages (`.zip` with a `META-INF/catalog.xml`) that map the
1174 /// base taxonomies' `http(s)` URLs to files for offline use. Without it the
1175 /// instance's own directory is searched. Nothing is fetched remotely; a
1176 /// document that cannot be found only costs the fact graph the hierarchy
1177 /// it would have contributed.
1178 pub fn xbrl_taxonomy(mut self, dir: impl Into<PathBuf>) -> Self {
1179 self.xbrl_taxonomy = Some(dir.into());
1180 self
1181 }
1182
1183 /// Select a named ASR model preset for audio sources — the English-only
1184 /// (`whisper_tiny_en`, `whisper_base_en`, `whisper_small_en`) and
1185 /// Distil-Whisper (`whisper_distil_small_en`) variants of docling's ASR
1186 /// model specs, or `parakeet_tdt_0.6b_v3` (NVIDIA's Parakeet TDT 0.6B v3
1187 /// transducer, 25 European languages detected by the model, #508 — see
1188 /// `docling_asr::parakeet`). `None` (default) uses Whisper tiny
1189 /// (multilingual) from `.models/asr/`; presets load from
1190 /// `.models/asr/<preset>/` (fetch them with `download_dependencies.sh
1191 /// --asr-model=<preset>`).
1192 pub fn asr_model(mut self, model: Option<String>) -> Self {
1193 self.asr_model = model;
1194 self
1195 }
1196
1197 /// Select the ASR transcription language for audio/video sources: a
1198 /// Whisper code (`en`, `de`, `zh`, …) or `auto`. `None` (default) falls
1199 /// back to `DOCLING_RS_ASR_LANG`, and — when that is unset too — to
1200 /// per-file auto-detection from the first 30-second window (docling
1201 /// 2.116 parity). English-only presets always transcribe English.
1202 pub fn asr_lang(mut self, lang: Option<String>) -> Self {
1203 self.asr_lang = lang;
1204 self
1205 }
1206
1207 /// Select the Markdown export mode for documents this converter produces.
1208 ///
1209 /// `false` (default) makes [`crate::DoclingDocument::export_to_markdown`]
1210 /// reproduce docling's legacy output byte-for-byte; `true` makes it emit
1211 /// cleaner, more conformant Markdown (code-fence languages preserved, no
1212 /// inline-run spacing artifacts, no entity re-escaping). Rust-only — Python
1213 /// docling has no such switch.
1214 pub fn strict(mut self, strict: bool) -> Self {
1215 self.strict = strict;
1216 self
1217 }
1218
1219 /// Fetch and embed external `<img>` images for HTML/EPUB/MHTML/JATS/
1220 /// AsciiDoc/Markdown/email sources — the pre-#646 switch, kept as an
1221 /// alias: `true` is [`image_sources`](Self::image_sources)
1222 /// `(`[`ImageSources::Remote`](crate::ImageSources::Remote)`)`, `false`
1223 /// is `None`.
1224 ///
1225 /// Off by default (matching docling's `enable_*_fetch=False`), so output is
1226 /// unchanged unless you opt in. `Remote` resolves `data:` URIs, container
1227 /// parts (EPUB/MHTML entries, email `cid:` attachments), files under the
1228 /// source file's directory, and `http(s)` URLs — fetched over the network,
1229 /// so enable it only for input you trust (it can otherwise make the
1230 /// process issue requests). A server converting untrusted input wants
1231 /// `image_sources(ImageSources::Embedded)` instead. Unlike before #646 an
1232 /// absolute local path (`/etc/hosts`, `file://…`) is never read.
1233 pub fn fetch_images(self, fetch: bool) -> Self {
1234 self.image_sources(if fetch {
1235 crate::ImageSources::Remote
1236 } else {
1237 crate::ImageSources::None
1238 })
1239 }
1240
1241 /// Which image references the declarative backends resolve (#646):
1242 /// [`None`](crate::ImageSources::None) (the default — every picture a
1243 /// placeholder), [`Embedded`](crate::ImageSources::Embedded) (`data:`
1244 /// URIs and parts of the same container: EPUB/MHTML entries, an email's
1245 /// `cid:` attachments — no filesystem, no network),
1246 /// [`Local`](crate::ImageSources::Local) (plus files under the source
1247 /// file's directory, never an absolute path or one that escapes it) and
1248 /// [`Remote`](crate::ImageSources::Remote) (plus `http(s)` fetches, see
1249 /// [`image_hosts`](Self::image_hosts)). Applies to HTML, EPUB, MHTML,
1250 /// JATS, AsciiDoc, ODF (`http(s)` `draw:image` references), Markdown
1251 /// (`` and inline `<img>`) and email bodies.
1252 pub fn image_sources(mut self, sources: crate::ImageSources) -> Self {
1253 self.image_sources = sources;
1254 self
1255 }
1256
1257 /// Restrict `Remote` fetches to these hosts (#646): exact names or
1258 /// `*.suffix` wildcards for any subdomain, case-insensitive; a redirect
1259 /// is held to the same list. Empty (the default) allows any host. The
1260 /// private/loopback/link-local block-list still applies to a listed
1261 /// host (`DOCLING_RS_ALLOW_PRIVATE_IP_FETCH` is the only way around it).
1262 pub fn image_hosts<I, S>(mut self, hosts: I) -> Self
1263 where
1264 I: IntoIterator<Item = S>,
1265 S: Into<String>,
1266 {
1267 self.image_hosts = hosts
1268 .into_iter()
1269 .map(|h| h.into().trim().to_ascii_lowercase())
1270 .filter(|h| !h.is_empty())
1271 .collect();
1272 self
1273 }
1274
1275 /// Largest image that resolves, in bytes (#646). Default 32 MiB
1276 /// (`DOCLING_RS_MAX_IMAGE_BYTES` overrides it); a larger one stays a
1277 /// placeholder.
1278 pub fn max_image_bytes(mut self, bytes: u64) -> Self {
1279 self.image_limits.max_bytes = Some(bytes.max(1));
1280 self
1281 }
1282
1283 /// How many images resolve per document (#646); the rest stay
1284 /// placeholders and one warning says so. Default unlimited
1285 /// (`DOCLING_RS_MAX_IMAGES` overrides it).
1286 pub fn max_images(mut self, count: usize) -> Self {
1287 self.image_limits.max_images = Some(count);
1288 self
1289 }
1290
1291 /// Total resolved image bytes per document, in MiB (#646). Default
1292 /// unlimited (`DOCLING_RS_MAX_IMAGE_TOTAL_MB` overrides it).
1293 pub fn max_image_total_mb(mut self, mb: u64) -> Self {
1294 self.image_limits.max_total_mb = Some(mb);
1295 self
1296 }
1297
1298 /// Smallest image that resolves, in bytes (#646) — spacers and tracking
1299 /// pixels are a few dozen bytes. Default 0 (`DOCLING_RS_MIN_IMAGE_BYTES`
1300 /// overrides it).
1301 pub fn min_image_bytes(mut self, bytes: u64) -> Self {
1302 self.image_limits.min_bytes = Some(bytes);
1303 self
1304 }
1305
1306 /// The Jupyter notebook backend (#673) under the builder's Markdown
1307 /// flavour, image policy and [`ipynb_outputs`](Self::ipynb_outputs).
1308 fn ipynb_backend(&self) -> crate::IpynbBackend {
1309 crate::IpynbBackend {
1310 strict: self.strict,
1311 images: self.image_policy(),
1312 outputs: self.ipynb_outputs,
1313 }
1314 }
1315
1316 /// The image policy a conversion runs under (#646): the builder's tier
1317 /// and hosts, the limits from the builder where set, else the
1318 /// environment, else the defaults.
1319 pub fn image_policy(&self) -> crate::ImagePolicy {
1320 let env = crate::ImageLimits::from_env();
1321 let o = &self.image_limits;
1322 crate::ImagePolicy {
1323 sources: self.image_sources,
1324 hosts: self.image_hosts.clone(),
1325 limits: crate::ImageLimits {
1326 max_bytes: o.max_bytes.unwrap_or(env.max_bytes),
1327 max_images: o.max_images.or(env.max_images),
1328 max_total_bytes: o
1329 .max_total_mb
1330 .map(|mb| mb.saturating_mul(1024 * 1024))
1331 .or(env.max_total_bytes),
1332 min_bytes: o.min_bytes.unwrap_or(env.min_bytes),
1333 },
1334 }
1335 }
1336
1337 /// Append an `Attachments` section to converted emails (`.eml` / `.msg`):
1338 /// one list item per attachment, `name (content/type)` — names and types
1339 /// only, the payload is never embedded. docling's opt-in
1340 /// `EmailBackendOptions.list_attachments` (#251); off by default.
1341 pub fn list_attachments(mut self, list: bool) -> Self {
1342 self.list_attachments = list;
1343 self
1344 }
1345
1346 /// Omit empty cells from sparse spreadsheet table grids (#271; XLSX/XLS
1347 /// family, opt-in — a docling.rs extension, docling materialises the full
1348 /// bounding box). A ragged region's box is mostly padding on sparse
1349 /// sheets (~7× output inflation); with this on, each row keeps only its
1350 /// occupied cells (merge-covered continuations included) and a table
1351 /// that loses cells drops its span/structure overlay. Off by default —
1352 /// default output stays byte-for-byte docling.
1353 pub fn skip_empty_cells(mut self, skip: bool) -> Self {
1354 self.skip_empty_cells = skip;
1355 self
1356 }
1357
1358 /// Emit Markdown tables in the compact `| a | b |` / `| - | - |` form
1359 /// instead of docling-core's width-padded GitHub serializer (#271, all
1360 /// formats; opt-in — a docling.rs extension). On sparse spreadsheets the
1361 /// padding dominates the output size; compact rendering keeps the grid
1362 /// semantics and drops only whitespace. Off by default — default output
1363 /// stays byte-for-byte docling.
1364 pub fn compact_tables(mut self, compact: bool) -> Self {
1365 self.compact_tables = compact;
1366 self
1367 }
1368
1369 /// Render pictures' author-written alt text (#676) — the `descr` /
1370 /// `title` of a DOCX, PPTX or XLSX picture's non-visual properties,
1371 /// which the backends keep as the picture's description with
1372 /// `created_by = "alt_text"` — in the Markdown and HTML exports: the
1373 /// `` of an image line, the line a description takes above a
1374 /// placeholder, the `<img alt>` and the description text in HTML. Off
1375 /// by default, so the default Markdown and HTML stay byte-for-byte
1376 /// docling's; strict Markdown renders it either way, and the JSON
1377 /// always carries it as `meta.description`. MarkItDown prints the alt
1378 /// text.
1379 pub fn picture_alt_text(mut self, on: bool) -> Self {
1380 self.picture_alt_text = on;
1381 self
1382 }
1383
1384 /// Where the file's own metadata goes in the exports (#679) — an
1385 /// EPUB's Dublin Core, an Office package's properties, an ODF
1386 /// `meta.xml`, a photo's EXIF, an audio file's tags, a PDF's Info
1387 /// dictionary, read into `document.metadata`. `None` (the default)
1388 /// reads nothing and leaves every export as it was; `Json` adds a
1389 /// `metadata` object to the docling JSON; `Frontmatter` adds YAML front
1390 /// matter at the top of the Markdown as well. The PII pass
1391 /// ([`redact_pii`](Self::redact_pii)) covers the metadata: author
1392 /// fields are masked as persons, the GPS position is dropped.
1393 pub fn metadata_output(mut self, mode: docling_core::MetadataOutput) -> Self {
1394 self.metadata_output = mode;
1395 self
1396 }
1397
1398 /// The metadata of `source` as [`metadata_output`](Self::metadata_output)
1399 /// would read it, whatever the mode — for a caller that streams a
1400 /// document itself and wants the front matter
1401 /// (`MarkdownStreamer::with_metadata`). Reads headers only; empty for a
1402 /// format that carries none.
1403 pub fn document_metadata(&self, source: &SourceDocument) -> docling_core::DocumentMetadata {
1404 crate::metadata::read(source, self.password.as_deref())
1405 }
1406
1407 /// Insert `placeholder` between pages in the Markdown export — docling's
1408 /// `export_to_markdown(page_break_placeholder=…)` (docling-core's
1409 /// `MarkdownParams`, docling-serve's `md_page_break_placeholder`). Where
1410 /// docling marks a break between two items whose `prov.page_no` differ,
1411 /// the serializer here marks it between two rendered blocks separated by a
1412 /// page boundary — the `PageInfo` marker opening every PDF page and sheet,
1413 /// the `PageBreak` between slides and DjVu / DocTags pages — so a break
1414 /// never leads or trails the document and empty pages collapse into one.
1415 /// `None` (the default) keeps Markdown free of page breaks, as docling's
1416 /// default export is. Markdown only; JSON carries pages in `prov`.
1417 pub fn page_break_placeholder(mut self, placeholder: Option<String>) -> Self {
1418 self.page_break_placeholder = placeholder;
1419 self
1420 }
1421
1422 /// The document-level settings [`convert`](Self::convert) applies to
1423 /// every backend's output: the serializer knobs carried on the document
1424 /// (`strict`, `compact_tables`, `page_break_placeholder`) so each later
1425 /// Markdown export agrees, and first-class cells for every table. Public
1426 /// for callers that run a backend themselves — docling-serve converts
1427 /// PDFs and images on a warm `Pipeline` and finishes
1428 /// them here, so a request's options reach them as they reach every
1429 /// other format (#547).
1430 pub fn finish_document(&self, document: &mut docling_core::DoclingDocument) {
1431 // Carry the mode so `result.document.export_to_markdown()` reflects it.
1432 document.strict_markdown = self.strict;
1433 // Compact tables (#271) is additive: the PDF backend already turns it
1434 // on for its own corpus; never turn it back off here.
1435 if self.compact_tables {
1436 document.compact_tables = true;
1437 }
1438 // Alt text in Markdown/HTML (#676): additive like compact tables.
1439 if self.picture_alt_text {
1440 document.picture_alt_text = true;
1441 }
1442 // The metadata output mode (#679), likewise.
1443 if self.metadata_output.in_json() {
1444 document.metadata_output = self.metadata_output;
1445 }
1446 // Page-break placeholder: a serializer knob like `strict`, carried on
1447 // the document so every Markdown export of it agrees.
1448 if self.page_break_placeholder.is_some() {
1449 document.page_break_placeholder = self.page_break_placeholder.clone();
1450 }
1451 // First-class cells for every table (#240): backends with page
1452 // geometry (the PDF TableFormer paths) set them; everything else —
1453 // declarative tables included — derives them from the grid plus the
1454 // structure overlay (real spans for DOCX/XLSX merges, HTML `th`
1455 // headers, ODF covered cells; 1×1 records otherwise), so the repair
1456 // API and the JSON `table_cells` are populated uniformly.
1457 for table in document.tables_mut() {
1458 if table.cells.is_none() {
1459 table.cells = Some(table.derive_cells());
1460 }
1461 }
1462 }
1463
1464 /// The picture enrichment pass: describe the pictures through the
1465 /// vision endpoint when [`picture_description`](Self::picture_description)
1466 /// is set (#670), OCR the embedded pictures when
1467 /// [`do_picture_ocr`](Self::do_picture_ocr) asks for it (#645), then
1468 /// drop the image bytes unless [`keep_picture_images`](Self::keep_picture_images)
1469 /// keeps them. Runs on every conversion after the backend, before
1470 /// [`finish_document`](Self::finish_document).
1471 fn enrich_pictures(
1472 &self,
1473 document: &mut docling_core::DoclingDocument,
1474 source: &SourceDocument,
1475 ) {
1476 let format = source.format;
1477 #[cfg(feature = "vlm")]
1478 if let Some(opts) = &self.picture_description {
1479 self.describe_pictures(document, source, opts);
1480 }
1481 if self.picture_ocr {
1482 self.ocr_pictures(document, format);
1483 }
1484 if !self.keep_picture_images {
1485 strip_picture_images(document);
1486 }
1487 }
1488
1489 /// The picture-OCR pass itself: PDF, image and METS pages already went
1490 /// through the OCR pipeline, so their pictures are left alone, and a
1491 /// video's frames were read as they were decoded
1492 /// ([`convert_video`](Self::convert_video)); with OCR disabled, or
1493 /// without the recognizer, the pictures keep no text and one warning
1494 /// says why. The same image embedded twice — a DOCX walked into both
1495 /// the flat nodes and the item tree, a slide master's logo on every
1496 /// slide — is read once (cached by its bytes).
1497 fn ocr_pictures(&self, document: &mut docling_core::DoclingDocument, format: InputFormat) {
1498 use docling_core::{tree::TreeKind, Node};
1499
1500 if matches!(
1501 format,
1502 InputFormat::Pdf | InputFormat::Image | InputFormat::MetsGbs | InputFormat::Video
1503 ) {
1504 return;
1505 }
1506 let Some(mut reader) = self.picture_reader() else {
1507 return;
1508 };
1509 document.for_each_picture_mut(&mut |node| {
1510 if let Node::Picture {
1511 image: Some(img),
1512 description,
1513 ..
1514 } = node
1515 {
1516 if undescribed(description) {
1517 *description = reader.read(img);
1518 }
1519 }
1520 });
1521 if let Some(tree) = document.tree.as_mut() {
1522 for item in tree.items.iter_mut() {
1523 if let TreeKind::Picture {
1524 image: Some(img),
1525 description,
1526 ..
1527 } = &mut item.kind
1528 {
1529 if undescribed(description) {
1530 *description = reader.read(img);
1531 }
1532 }
1533 }
1534 }
1535 }
1536
1537 /// The picture-description pass (#670). Two walks over the document:
1538 /// the first collects every undescribed picture that passes the size
1539 /// floor and the class filter, keyed by its bytes so a logo on every
1540 /// slide is asked about once; the requests run on `concurrency` threads;
1541 /// the second walk writes the answers back. In caption mode an image
1542 /// input, which the layout model turned into text and figures, is also
1543 /// described as a whole — the caption MarkItDown gives an image file.
1544 #[cfg(feature = "vlm")]
1545 fn describe_pictures(
1546 &self,
1547 document: &mut docling_core::DoclingDocument,
1548 source: &SourceDocument,
1549 opts: &crate::vlm::PictureDescriptionOptions,
1550 ) {
1551 use std::collections::HashMap;
1552 use std::hash::{Hash, Hasher};
1553
1554 use docling_core::{tree::TreeKind, Node, PictureDescription, PictureImage};
1555
1556 fn key_of(data: &[u8]) -> u64 {
1557 let mut h = std::collections::hash_map::DefaultHasher::new();
1558 data.hash(&mut h);
1559 h.finish()
1560 }
1561
1562 // Walk 1: the candidates, in document order, each distinct image once.
1563 let mut order: Vec<u64> = Vec::new();
1564 let mut images: HashMap<u64, PictureImage> = HashMap::new();
1565 let mut collect = |img: &PictureImage, description: &Option<PictureDescription>| {
1566 if !undescribed(description) {
1567 return;
1568 }
1569 let key = key_of(&img.data);
1570 if let std::collections::hash_map::Entry::Vacant(e) = images.entry(key) {
1571 order.push(key);
1572 e.insert(img.clone());
1573 }
1574 };
1575 document.for_each_picture_mut(&mut |node| {
1576 if let Node::Picture {
1577 image: Some(img),
1578 description,
1579 ..
1580 } = node
1581 {
1582 collect(img, description);
1583 }
1584 });
1585 if let Some(tree) = document.tree.as_ref() {
1586 for item in &tree.items {
1587 if let TreeKind::Picture {
1588 image: Some(img),
1589 description,
1590 ..
1591 } = &item.kind
1592 {
1593 collect(img, description);
1594 }
1595 }
1596 }
1597 // An image input as a whole (caption mode): the layout model split
1598 // it into text and figures, but the file is the picture.
1599 let whole = (source.format == InputFormat::Image
1600 && opts.mode == crate::vlm::PictureDescriptionMode::Caption)
1601 .then(|| PictureImage {
1602 mimetype: image_mimetype(&source.bytes)
1603 .unwrap_or("application/octet-stream")
1604 .into(),
1605 width: 0,
1606 height: 0,
1607 data: source.bytes.clone(),
1608 dpi: PictureImage::DEFAULT_DPI,
1609 });
1610 if let Some(img) = &whole {
1611 collect(img, &None);
1612 }
1613 if order.is_empty() {
1614 return;
1615 }
1616
1617 // The filters picture OCR applies (#645): the size floor on the
1618 // declared, then decoded, size; the classifier's top label when
1619 // classes are named.
1620 let min_side = self
1621 .picture_ocr_min_side
1622 .or_else(|| docling_core::env::parse::<u32>("DOCLING_RS_PICTURE_OCR_MIN_SIDE"))
1623 .unwrap_or(32);
1624 let mut classifier = (!self.picture_ocr_classes.is_empty())
1625 .then(|| docling_pdf::Pipeline::new().ok())
1626 .flatten()
1627 .map(|p| p.no_ocr(true).no_table_former(true));
1628 let mut jobs: Vec<(u64, String, Vec<u8>)> = Vec::new();
1629 for key in &order {
1630 let img = &images[key];
1631 if img.width.min(img.height) < min_side && img.width * img.height > 0 {
1632 continue;
1633 }
1634 // The endpoint takes PNG/JPEG/GIF/WebP data URIs; a BMP or TIFF
1635 // is re-encoded, a vector or Windows metafile picture skipped.
1636 let Some((mimetype, bytes)) = endpoint_image(img) else {
1637 docling_core::debug_log!(
1638 "docling: picture description: {} is not an image the endpoint takes; skipped",
1639 img.mimetype
1640 );
1641 continue;
1642 };
1643 if min_side > 0 || classifier.is_some() {
1644 let decoded = match image::load_from_memory(&bytes) {
1645 Ok(d) => d.into_rgb8(),
1646 Err(e) => {
1647 docling_core::debug_log!(
1648 "docling: picture description: undecodable image: {e}"
1649 );
1650 continue;
1651 }
1652 };
1653 if decoded.width().min(decoded.height()) < min_side {
1654 continue;
1655 }
1656 if let Some(p) = classifier.as_mut() {
1657 if let Some(preds) = p.classify_picture(&decoded) {
1658 let top = preds.first().map(|c| c.class_name.as_str());
1659 if !top.is_some_and(|t| self.picture_ocr_classes.iter().any(|c| c == t)) {
1660 continue;
1661 }
1662 }
1663 }
1664 }
1665 jobs.push((*key, mimetype.to_string(), bytes.into_owned()));
1666 }
1667 if jobs.is_empty() {
1668 return;
1669 }
1670
1671 // The requests: `concurrency` workers pull from one queue; a
1672 // rejected picture is warned about and skipped, an unreachable
1673 // endpoint stops the queue — every later picture would wait out the
1674 // same retries for the same answer.
1675 let agent = crate::vlm::agent();
1676 let next = std::sync::atomic::AtomicUsize::new(0);
1677 let stop = std::sync::atomic::AtomicBool::new(false);
1678 let answers: std::sync::Mutex<HashMap<u64, String>> = std::sync::Mutex::new(HashMap::new());
1679 let workers = opts.concurrency.max(1).min(jobs.len());
1680 std::thread::scope(|scope| {
1681 for _ in 0..workers {
1682 scope.spawn(|| loop {
1683 if stop.load(std::sync::atomic::Ordering::Relaxed) {
1684 break;
1685 }
1686 let i = next.fetch_add(1, std::sync::atomic::Ordering::Relaxed);
1687 let Some((key, mimetype, bytes)) = jobs.get(i) else {
1688 break;
1689 };
1690 match opts.describe(&agent, mimetype, bytes) {
1691 Ok(Some(text)) => {
1692 answers.lock().unwrap().insert(*key, text);
1693 }
1694 Ok(None) => {}
1695 Err(crate::vlm::RequestError::Rejected(e)) => {
1696 eprintln!("warning: picture description: {e}; the picture keeps none");
1697 }
1698 Err(crate::vlm::RequestError::Unavailable(e)) => {
1699 if !stop.swap(true, std::sync::atomic::Ordering::Relaxed) {
1700 let left = jobs.len().saturating_sub(i);
1701 eprintln!(
1702 "warning: picture description: {e}; {left} picture(s) keep no \
1703 description"
1704 );
1705 }
1706 }
1707 }
1708 });
1709 }
1710 });
1711 let answers = answers.into_inner().unwrap();
1712 if answers.is_empty() {
1713 return;
1714 }
1715
1716 // Walk 2: the answers onto every picture carrying those bytes.
1717 let provenance = opts.provenance();
1718 let described = |img: &PictureImage| -> Option<PictureDescription> {
1719 answers
1720 .get(&key_of(&img.data))
1721 .map(|text| PictureDescription {
1722 text: text.clone(),
1723 provenance: provenance.clone(),
1724 })
1725 };
1726 document.for_each_picture_mut(&mut |node| {
1727 if let Node::Picture {
1728 image: Some(img),
1729 description,
1730 ..
1731 } = node
1732 {
1733 if undescribed(description) {
1734 *description = described(img);
1735 }
1736 }
1737 });
1738 if let Some(tree) = document.tree.as_mut() {
1739 for item in tree.items.iter_mut() {
1740 if let TreeKind::Picture {
1741 image: Some(img),
1742 description,
1743 ..
1744 } = &mut item.kind
1745 {
1746 if undescribed(description) {
1747 *description = described(img);
1748 }
1749 }
1750 }
1751 }
1752 if let Some(img) = whole {
1753 if let Some(description) = described(&img) {
1754 document.nodes.push(Node::Picture {
1755 caption: None,
1756 caption_href: None,
1757 image: self.keep_picture_images.then_some(img),
1758 classification: None,
1759 description: Some(description),
1760 caption_parent: Default::default(),
1761 caption_location: None,
1762 });
1763 }
1764 }
1765 }
1766
1767 /// The reader the picture-OCR pass (#645) and the video frame hook
1768 /// (#647) share: the OCR models only — no layout, no TableFormer, the
1769 /// caller already knows each whole image is the picture — behind the
1770 /// size floor and the classifier filter. `None` (after one warning)
1771 /// when OCR is disabled or the recognizer cannot load.
1772 #[cfg(feature = "pdf")]
1773 fn picture_reader(&self) -> Option<PictureReader> {
1774 static WARNED: std::sync::Once = std::sync::Once::new();
1775 if self.no_ocr || self.text_layer_only {
1776 WARNED.call_once(|| {
1777 eprintln!(
1778 "warning: picture OCR requested, but OCR is disabled (no_ocr / \
1779 text_layer_only); pictures keep no text"
1780 );
1781 });
1782 return None;
1783 }
1784 let pipeline = docling_pdf::Pipeline::new().map(|p| {
1785 self.with_textline_orientation(
1786 p.no_ocr(true)
1787 .no_table_former(true)
1788 .ocr_lang(self.ocr_lang_choice())
1789 .ocr_engine(self.ocr_engine_choice())
1790 .tesseract_lang(self.tesseract_lang_choice())
1791 .ocr_scale(self.ocr_scale_choice())
1792 .picture_ocr_scale(self.picture_ocr_scale_choice()),
1793 )
1794 });
1795 let pipeline = match pipeline {
1796 Ok(p) => p,
1797 Err(e) => {
1798 WARNED.call_once(|| {
1799 eprintln!("warning: picture OCR unavailable ({e}); pictures keep no text");
1800 });
1801 return None;
1802 }
1803 };
1804 let min_side = self
1805 .picture_ocr_min_side
1806 .or_else(|| docling_core::env::parse::<u32>("DOCLING_RS_PICTURE_OCR_MIN_SIDE"))
1807 .unwrap_or(32);
1808 Some(PictureReader {
1809 pipeline,
1810 min_side,
1811 classes: self.picture_ocr_classes.clone(),
1812 cache: std::collections::HashMap::new(),
1813 })
1814 }
1815
1816 /// Without the `pdf` feature there is no OCR engine to run: one warning,
1817 /// the pictures keep no text.
1818 #[cfg(not(feature = "pdf"))]
1819 fn picture_reader(&self) -> Option<PictureReader> {
1820 static WARNED: std::sync::Once = std::sync::Once::new();
1821 WARNED.call_once(|| {
1822 eprintln!(
1823 "warning: picture OCR requested, but this build has no OCR engine (rebuild \
1824 with the `pdf` feature); pictures keep no text"
1825 );
1826 });
1827 None
1828 }
1829
1830 /// The frame sampling a video gets (#647): the builder's settings, else
1831 /// the environment's, else the defaults.
1832 #[cfg(feature = "asr")]
1833 fn frame_options(&self) -> crate::video::FrameOptions {
1834 use docling_core::env;
1835 crate::video::FrameOptions {
1836 max_frames: self.video_frames.unwrap_or(DEFAULT_VIDEO_FRAMES),
1837 scene_threshold: self
1838 .video_scene_threshold
1839 .or_else(|| env::parse::<f32>("DOCLING_RS_VIDEO_SCENE_THRESHOLD"))
1840 .map_or(crate::video::DEFAULT_SCENE_THRESHOLD, |t| t.clamp(0.0, 1.0)),
1841 max_side: self
1842 .video_frame_max_side
1843 .or_else(|| env::parse::<u32>("DOCLING_RS_VIDEO_FRAME_MAX_SIDE"))
1844 .unwrap_or(0),
1845 dedupe: self
1846 .video_frame_dedupe
1847 .or_else(|| env::parse::<u32>("DOCLING_RS_VIDEO_FRAME_DEDUPE"))
1848 .map(|d| d.min(64)),
1849 }
1850 }
1851
1852 /// Video (#138): the audio track transcribes through the ASR path
1853 /// (Phase 1), and — when the ffmpeg binary is available — sampled
1854 /// frames interleave with the transcript as timestamped pictures
1855 /// (Phase 2). Without ffmpeg: transcript only. Each frame goes through
1856 /// the picture enrichment as soon as it is decoded (#647): read by the
1857 /// OCR models when [`do_picture_ocr`](Self::do_picture_ocr) asks, its
1858 /// bytes dropped when [`keep_picture_images`](Self::keep_picture_images)
1859 /// is off — so however many frames are sampled, one is in memory at a
1860 /// time. The models load on the first frame; a video without one costs
1861 /// nothing.
1862 #[cfg(feature = "asr")]
1863 fn convert_video(
1864 &self,
1865 source: &SourceDocument,
1866 ) -> Result<docling_core::DoclingDocument, String> {
1867 use docling_core::Node;
1868 let opts = self.frame_options();
1869 let mut reader: Option<Option<PictureReader>> = None;
1870 let mut on_frame = |node: &mut Node| {
1871 if self.picture_ocr {
1872 let reader = reader.get_or_insert_with(|| self.picture_reader());
1873 if let (
1874 Some(reader),
1875 Node::Picture {
1876 image: Some(img),
1877 description,
1878 ..
1879 },
1880 ) = (reader.as_mut(), &mut *node)
1881 {
1882 if undescribed(description) {
1883 *description = reader.read(img);
1884 }
1885 }
1886 }
1887 if !self.keep_picture_images {
1888 if let Node::Picture { image, .. } = node {
1889 *image = None;
1890 }
1891 }
1892 };
1893 crate::video::convert_video(
1894 &source.bytes,
1895 &source.name,
1896 self.asr_model.as_deref(),
1897 self.asr_lang.as_deref(),
1898 &opts,
1899 &mut on_frame,
1900 )
1901 }
1902
1903 /// The copybook layout for EBCDIC sources (#252): docling's
1904 /// `EbcdicLayout` JSON, inline (a string starting with `{`) or as a file
1905 /// path. Without it, a path-loaded source looks for a
1906 /// `<stem>.layout.json` sidecar; converting EBCDIC with neither is an
1907 /// error — the bytes are meaningless without their copybook.
1908 pub fn ebcdic_layout(mut self, layout: impl Into<String>) -> Self {
1909 self.ebcdic_layout = Some(layout.into());
1910 self
1911 }
1912
1913 /// Option-typed variant of [`ebcdic_layout`](Self::ebcdic_layout) for
1914 /// call sites plumbing an optional flag through (`None` keeps the
1915 /// sidecar fallback).
1916 pub fn ebcdic_layout_opt(mut self, layout: Option<String>) -> Self {
1917 self.ebcdic_layout = layout;
1918 self
1919 }
1920
1921 /// Skip loading and running the TableFormer table-structure model for
1922 /// PDF/image/METS sources.
1923 ///
1924 /// Off by default. When enabled, table regions are still detected and
1925 /// emitted, but their structure is reconstructed geometrically from cell
1926 /// positions instead of the ONNX model's predicted structure — no model
1927 /// load and no per-table inference, at the cost of table fidelity. Useful
1928 /// when parsing speed matters more than exact table structure, especially
1929 /// with [`convert_streaming`](Self::convert_streaming).
1930 pub fn no_table_former(mut self, disable: bool) -> Self {
1931 self.no_table_former = disable;
1932 self
1933 }
1934
1935 /// PDF/image: keep every detected picture as a picture — disable the
1936 /// text-panel demotion that turns an uncaptioned, dense text-panel
1937 /// "picture" into paragraphs (#157). The escape hatch for
1938 /// image-extraction workflows and for charts the heuristic might still
1939 /// misjudge on scanned pages (#173).
1940 pub fn no_text_panels(mut self, disable: bool) -> Self {
1941 self.no_text_panels = disable;
1942 self
1943 }
1944
1945 /// Infer PDF/image section-header levels after assembly (#302, docling's
1946 /// `HeadingHierarchyModel` with its default options): the PDF outline
1947 /// (bookmarks) is authoritative, legal/outline numbering covers headings
1948 /// without a bookmark match, and font size/weight/slant/case rank the
1949 /// rest. Off by default (docling parity): every detected heading then
1950 /// keeps the flat level the assembler emits. Non-PDF/image formats
1951 /// ignore it (their backends carry real heading levels already).
1952 pub fn heading_hierarchy(mut self, enable: bool) -> Self {
1953 self.heading_hierarchy = enable;
1954 self
1955 }
1956
1957 /// Skip layout detection, OCR, and TableFormer entirely for PDF/image/METS
1958 /// sources — no model load, no inference of any kind (#611; this was
1959 /// `no_ocr` before 2.0).
1960 ///
1961 /// Off by default. When enabled, the PDF's embedded text cells are grouped by
1962 /// line and emitted as plain paragraphs in reading order: no headings, lists,
1963 /// tables, code blocks, or pictures, since that structure comes from the
1964 /// layout model. The fastest possible PDF path, but pages with no embedded
1965 /// text layer (scanned/image-only PDFs) yield no text at all — convert those
1966 /// without this flag. Implies [`no_table_former`](Self::no_table_former).
1967 pub fn text_layer_only(mut self, enable: bool) -> Self {
1968 self.text_layer_only = enable;
1969 self
1970 }
1971
1972 /// Never run OCR, but keep layout detection and TableFormer — docling's
1973 /// `do_ocr=False`, its CLI's `--no-ocr` (#244; since 2.0, #611, the
1974 /// meaning of `no_ocr` too). Unlike
1975 /// [`text_layer_only`](Self::text_layer_only) (the skip-everything fast
1976 /// path), structured output — headings, tables, pictures, reading order —
1977 /// is preserved; only text that exists solely as pixels is lost (scanned
1978 /// pages come back with empty regions, and the speculative OCR of large
1979 /// embedded images never runs). The OCR model is never loaded, and
1980 /// independently of this flag a *missing* OCR model degrades to the same
1981 /// behavior with a warning instead of failing the conversion. SVG inputs
1982 /// route to direct `<text>` extraction (their text is native — skipping
1983 /// OCR must not lose it).
1984 pub fn no_ocr(mut self, disable: bool) -> Self {
1985 self.no_ocr = disable;
1986 self
1987 }
1988
1989 /// [`no_ocr`](Self::no_ocr) under its pre-2.0 name, kept as an alias.
1990 pub fn skip_ocr(self, disable: bool) -> Self {
1991 self.no_ocr(disable)
1992 }
1993
1994 /// The password of an encrypted document: a PDF (docling's
1995 /// `--pdf-password`, #611) or an Office document (#625, a docling.rs
1996 /// extension — docling reads none): `.docx`/`.xlsx`/`.pptx` (Agile and
1997 /// Standard encryption), `.doc`/`.xls`/`.ppt` (RC4 and RC4 CryptoAPI).
1998 ///
1999 /// A missing or wrong PDF password fails the conversion with "the PDF is
2000 /// encrypted: a password is required"; PDF passwords are read on the ML
2001 /// pipeline only (the `pdf-text` / wasm build reads unencrypted PDFs).
2002 /// Office documents decrypt in every build. Without a password, or when
2003 /// it is wrong, the format's default password is tried (Excel's
2004 /// `VelvetSweatshop`, PowerPoint's for modify-password-only files);
2005 /// otherwise the error says the document is encrypted, or that the
2006 /// password is wrong.
2007 pub fn password(mut self, password: Option<String>) -> Self {
2008 self.password = password;
2009 self
2010 }
2011
2012 /// [`password`](Self::password) under docling's PDF-only name.
2013 pub fn pdf_password(self, password: Option<String>) -> Self {
2014 self.password(password)
2015 }
2016
2017 /// OCR every PDF page from its rendered image even when the page carries
2018 /// an embedded text layer — docling's `force_full_page_ocr`. The escape
2019 /// hatch for text layers that exist but lie (broken encodings, subset
2020 /// fonts with garbage mappings, scanned forms with a few typed-in
2021 /// fields). Off by default; ignored when [`no_ocr`](Self::no_ocr) or
2022 /// [`text_layer_only`](Self::text_layer_only) is set,
2023 /// mirroring docling, where it is a sub-option of `do_ocr`. Applies to
2024 /// PDFs only — standalone images are always OCR'd.
2025 pub fn force_full_page_ocr(mut self, force: bool) -> Self {
2026 self.force_full_page_ocr = force;
2027 self
2028 }
2029
2030 /// Which document regions feed the OCR — docling's `OcrMode` (#254):
2031 /// `default`, `full_page`, `layout_regions`, or
2032 /// `pdf_aware_layout_regions`. The default is the text-layer-aware
2033 /// behavior (docling's `pdf_aware_layout_regions`);
2034 /// `full_page`/`layout_regions` discard the text layer like
2035 /// [`force_full_page_ocr`](Self::force_full_page_ocr) — see
2036 /// [`docling_pdf::OcrMode`] for the mapping. An unknown value warns at
2037 /// conversion time and uses the default. PDF/image ML pipeline only.
2038 pub fn ocr_mode(mut self, mode: impl Into<String>) -> Self {
2039 self.ocr_mode = Some(mode.into());
2040 self
2041 }
2042
2043 /// Which OCR engine recognizes text on scanned pages (#460): `"ppocr"`
2044 /// (the default — the built-in PP-OCRv3 recognizer, the conformance
2045 /// engine) or `"tesseract"` (the system `tesseract` binary, docling's
2046 /// `TesseractCliOcrOptions`; needs `tesseract-ocr` with a language pack
2047 /// installed — `DOCLING_TESSERACT` names the binary,
2048 /// `DOCLING_RS_TESSERACT_PSM` its page segmentation mode,
2049 /// `DOCLING_RS_TESSDATA_DIR` / `TESSDATA_PREFIX` its data). Both read
2050 /// the same layout-region crops; [`ocr_lang`](Self::ocr_lang) is the
2051 /// engine's language. An unknown value warns at conversion time and uses
2052 /// the default (`DOCLING_RS_OCR_ENGINE`, else PP-OCR). Formats that never
2053 /// OCR ignore it.
2054 pub fn ocr_engine(mut self, engine: impl Into<String>) -> Self {
2055 self.ocr_engine = Some(engine.into());
2056 self
2057 }
2058
2059 /// OCR render scale in pixels per PDF point — docling's
2060 /// `OcrOptions.scale` (#254; docling's default 3 = 216 dpi). Unset feeds
2061 /// the recognizer the pipeline's own 2.0 px/pt page render; a different
2062 /// value resamples that render for the OCR input only, leaving layout and
2063 /// TableFormer pixels untouched. Non-positive values warn at conversion
2064 /// time and are ignored. PDF/image ML pipeline only.
2065 pub fn ocr_scale(mut self, scale: f32) -> Self {
2066 self.ocr_scale = Some(scale);
2067 self
2068 }
2069
2070 /// RapidOCR's handling of text-line orientation (#666), off by default
2071 /// (`DOCLING_RS_OCR_TEXTLINE_ORIENTATION` sets the process default):
2072 /// detected lines are cropped along the detector's rotated rectangle, a
2073 /// crop at least 1.5× taller than wide is turned 90°, and the
2074 /// PP-LCNet text-line orientation classifier
2075 /// (`.models/ocr_textline_ori.onnx`) turns upside-down lines — so
2076 /// vertical axis titles, rotated headers, skewed and upside-down lines
2077 /// read as text. Applies to the PP-OCR lines of scanned pages, images
2078 /// and pictures alike (changing their output when on); table words and
2079 /// Tesseract are untouched. A missing classifier warns once and keeps
2080 /// the crop and the 90° turn.
2081 pub fn ocr_textline_orientation(mut self, enable: bool) -> Self {
2082 self.ocr_textline_orientation = Some(enable);
2083 self
2084 }
2085
2086 /// Pixels per PDF point for picture crops and page images — docling's
2087 /// `images_scale` (#520). Unset delivers crops at the pipeline's own 2.0
2088 /// px/pt render (144 dpi), as before; another value resamples it (above
2089 /// 2.0 that upsamples, it does not re-render). The picture's `dpi` in the
2090 /// JSON export is 72·scale either way (#519). Non-finite or non-positive
2091 /// values are ignored. PDF/image ML pipeline only.
2092 pub fn images_scale(mut self, scale: f32) -> Self {
2093 self.images_scale = Some(scale).filter(|s| s.is_finite() && *s > 0.0);
2094 self
2095 }
2096
2097 /// Keep every page's render as a page image — docling's
2098 /// `generate_page_images` (#520): the JSON export carries it as
2099 /// `pages[n].image` at [`Self::images_scale`], which docling-core's
2100 /// `TableItem.get_image` / `FormulaItem.get_image` crop from. Off by
2101 /// default (one full-page PNG per page in memory). PDF/image ML pipeline
2102 /// only; text-layer-only (`text_layer_only`) and streaming conversions get none.
2103 pub fn generate_page_images(mut self, enabled: bool) -> Self {
2104 self.generate_page_images = enabled;
2105 self
2106 }
2107
2108 /// Classify each detected picture with the DocumentFigureClassifier model
2109 /// (docling's `do_picture_classification`). Off by default.
2110 ///
2111 /// The full 26-class prediction distribution (bar_chart, logo, signature,
2112 /// …) lands on the picture item and is serialized into the docling JSON as
2113 /// the `classification` annotation plus the `meta.classification` field.
2114 /// Markdown output is unaffected. Needs `.models/picture_classifier.onnx`
2115 /// (fetched by `scripts/install/download_dependencies.sh`); a missing
2116 /// model warns once and skips classification.
2117 pub fn do_picture_classification(mut self, enable: bool) -> Self {
2118 self.enrich.picture_classification = enable;
2119 self
2120 }
2121
2122 /// OCR the pictures embedded in non-PDF documents (#645) — a DOCX/PPTX
2123 /// screenshot, an HTML figure, a sampled video frame — with the ML
2124 /// pipeline's OCR models (the PP-OCR recognizer + the `ocr_det.onnx`
2125 /// line detector when installed, or Tesseract under
2126 /// [`ocr_engine`](Self::ocr_engine)), and attach the text to the picture
2127 /// as docling's `PictureDescriptionData` annotation: Markdown prints it
2128 /// between the caption and the image placeholder, JSON/DCLX carry it as
2129 /// `meta.description` + the `description` annotation, the hybrid chunker
2130 /// puts it in the picture's chunk. Off by default — every default export
2131 /// is unchanged. Nothing is attached to a picture the engine reads no
2132 /// text from (lines under `DOCLING_RS_OCR_TEXT_SCORE` are dropped as on a
2133 /// scanned page). PDF, image and METS inputs are untouched: their pages
2134 /// go through the OCR pipeline already. With [`no_ocr`](Self::no_ocr) /
2135 /// [`text_layer_only`](Self::text_layer_only), or without the OCR model
2136 /// (or the `pdf` feature), one warning and no text. See also
2137 /// [`picture_ocr_classes`](Self::picture_ocr_classes),
2138 /// [`picture_ocr_min_side`](Self::picture_ocr_min_side) and
2139 /// [`keep_picture_images`](Self::keep_picture_images).
2140 pub fn do_picture_ocr(mut self, enable: bool) -> Self {
2141 self.picture_ocr = enable;
2142 self
2143 }
2144
2145 /// Only OCR the pictures the DocumentFigureClassifier labels as one of
2146 /// `labels` (its 26 classes: `screenshot_from_computer`,
2147 /// `screenshot_from_manual`, `logo`, `photograph`, …), judged by its top
2148 /// prediction — the way to skip photos and logos on a slide deck while
2149 /// reading its screenshots. Empty (the default) OCRs every picture that
2150 /// passes the size floor. Needs `.models/picture_classifier.onnx`; a
2151 /// missing model warns once and the filter is waived.
2152 pub fn picture_ocr_classes<I, S>(mut self, labels: I) -> Self
2153 where
2154 I: IntoIterator<Item = S>,
2155 S: Into<String>,
2156 {
2157 self.picture_ocr_classes = labels
2158 .into_iter()
2159 .map(|s| s.into().trim().to_ascii_lowercase())
2160 .filter(|s| !s.is_empty())
2161 .collect();
2162 self
2163 }
2164
2165 /// The smallest side, in pixels, a picture must have to be OCR'd:
2166 /// bullets, icons and rules are skipped without decoding or inference.
2167 /// Default 32 (`DOCLING_RS_PICTURE_OCR_MIN_SIDE` overrides it); `0`
2168 /// reads everything.
2169 pub fn picture_ocr_min_side(mut self, px: u32) -> Self {
2170 self.picture_ocr_min_side = Some(px);
2171 self
2172 }
2173
2174 /// The picture OCR's resolution (#666), in pixels per picture pixel
2175 /// before RapidOCR's 2000 px longer-side cap: `1.0` reads a picture at
2176 /// its native pixels, as RapidOCR does, shrinking only what exceeds
2177 /// 2000 px. Unset (`DOCLING_RS_PICTURE_OCR_SCALE`, else the image-input
2178 /// rule) reads it like a scanned image — [`ocr_scale`](Self::ocr_scale)
2179 /// when set, else 3 px/pt under the cap, which upscales a 720 × 180
2180 /// screenshot to 2000 × 500. Scanned pages and image inputs are
2181 /// unaffected. Non-positive values warn and are ignored.
2182 pub fn picture_ocr_scale(mut self, scale: f32) -> Self {
2183 self.picture_ocr_scale = Some(scale);
2184 self
2185 }
2186
2187 /// Describe every picture through an OpenAI-compatible vision endpoint
2188 /// (#670) — MarkItDown's `llm_client` / `llm_model` / `llm_prompt` and
2189 /// its markitdown-ocr plugin, for every format: the embedded pictures of
2190 /// DOCX/PPTX/XLSX/HTML, a PDF's or scan's figure crops, sampled video
2191 /// frames, and (in caption mode) an image input as a whole. The answer
2192 /// becomes the picture's description annotation, where
2193 /// [`do_picture_ocr`](Self::do_picture_ocr) puts its text: Markdown
2194 /// prints it after the caption, JSON carries `meta.description` with the
2195 /// model as `created_by`. [`picture_ocr_min_side`](Self::picture_ocr_min_side)
2196 /// and [`picture_ocr_classes`](Self::picture_ocr_classes) select the
2197 /// pictures here too; identical image bytes are sent once per document;
2198 /// `concurrency` pictures are in flight at once. An endpoint that rejects
2199 /// a picture warns and the rest go on; one that cannot be reached warns
2200 /// once and the remaining pictures keep no description — the conversion
2201 /// never fails over it. Runs before the local picture OCR, which then
2202 /// reads only what stayed undescribed.
2203 #[cfg(feature = "vlm")]
2204 pub fn picture_description(mut self, opts: crate::vlm::PictureDescriptionOptions) -> Self {
2205 self.picture_description = Some(opts);
2206 self
2207 }
2208
2209 /// Whether the pictures keep their embedded image bytes (the default,
2210 /// `true`): `false` drops them from every picture after the enrichment
2211 /// pass, so a document whose images were only there to be read — a slide
2212 /// deck of screenshots, the sampled frames of a video — exports a slim
2213 /// JSON/DCLX and a placeholder-only Markdown while keeping the OCR text.
2214 pub fn keep_picture_images(mut self, keep: bool) -> Self {
2215 self.keep_picture_images = keep;
2216 self
2217 }
2218
2219 /// Redact personal data from every converted document (#621): after
2220 /// the backend builds the [`DoclingDocument`](docling_core::DoclingDocument)
2221 /// and before any export, chunker or stream reads it, every detected
2222 /// span — e-mail, phone, card number, IBAN, IP, URL credentials,
2223 /// national IDs, and names / organizations / locations when the NER
2224 /// model is installed (`.models/ner/`, the `ner` feature) — is replaced
2225 /// in place by a placeholder (`[EMAIL]`, `[PERSON_2]` with
2226 /// [`Replacement::Pseudonym`](docling_core::Replacement::Pseudonym), or
2227 /// a fixed string), in the flat nodes, the item tree behind the JSON,
2228 /// the link table, captions, hrefs, code, comments, table cells. Images
2229 /// are dropped by default
2230 /// ([`ImageRedaction`](docling_core::ImageRedaction)); `BoxOut` paints
2231 /// over the OCR'd lines that carry a span, `Keep` leaves them. The
2232 /// result's `redaction` is the [`RedactionReport`](docling_core::RedactionReport)
2233 /// — counts per label, never the values unless `return_mapping` asks.
2234 /// Off by default; unused, the output is byte-identical. A docling.rs
2235 /// extension — Python docling has no redaction stage — and not a
2236 /// compliance guarantee: pattern and model recall are what they are.
2237 pub fn redact_pii(mut self, opts: docling_core::RedactionOptions) -> Self {
2238 self.redact = Some(opts);
2239 self
2240 }
2241
2242 /// Option-typed variant of [`redact_pii`](Self::redact_pii): `None`
2243 /// turns the pass off.
2244 pub fn redact_pii_opt(mut self, opts: Option<docling_core::RedactionOptions>) -> Self {
2245 self.redact = opts;
2246 self
2247 }
2248
2249 /// Run the PII pass (#621) this converter is configured with over a
2250 /// document built elsewhere — docling-serve's warm pipeline and the
2251 /// VLM pipeline bypass [`convert`](Self::convert) — and return its
2252 /// report; `Ok(None)` when [`redact_pii`](Self::redact_pii) is unset.
2253 pub fn redact(
2254 &self,
2255 document: &mut docling_core::DoclingDocument,
2256 ) -> Result<Option<docling_core::RedactionReport>, ConversionError> {
2257 match self.redact.as_ref() {
2258 Some(opts) => self.redact_document(document, opts).map(Some),
2259 None => Ok(None),
2260 }
2261 }
2262
2263 /// The PII pass over a converted document (#621): the detectors from
2264 /// the options, the OCR pipeline for `BoxOut` when this converter may
2265 /// run OCR (a `no_ocr` / `text_layer_only` converter drops the images
2266 /// instead, with the warning), then the walk. An invalid custom regex
2267 /// is a `Parse` error — the conversion cannot honour the request.
2268 fn redact_document(
2269 &self,
2270 document: &mut docling_core::DoclingDocument,
2271 opts: &docling_core::RedactionOptions,
2272 ) -> Result<docling_core::RedactionReport, ConversionError> {
2273 let detector = crate::redact::detector(opts)?;
2274 #[cfg(feature = "pdf")]
2275 {
2276 let mut ocr = None;
2277 if opts.images == docling_core::ImageRedaction::BoxOut
2278 && !self.no_ocr
2279 && !self.text_layer_only
2280 {
2281 // The OCR models only — no layout, no TableFormer.
2282 match docling_pdf::Pipeline::new() {
2283 Ok(p) => {
2284 ocr = Some(
2285 self.with_textline_orientation(
2286 p.no_ocr(true)
2287 .no_table_former(true)
2288 .ocr_lang(self.ocr_lang_choice())
2289 .ocr_engine(self.ocr_engine_choice())
2290 .tesseract_lang(self.tesseract_lang_choice())
2291 .ocr_scale(self.ocr_scale_choice()),
2292 ),
2293 )
2294 }
2295 Err(e) => crate::redact::warn_box_out_unavailable(&e.to_string()),
2296 }
2297 }
2298 Ok(crate::redact::run(document, opts, &detector, ocr.as_mut()))
2299 }
2300 #[cfg(not(feature = "pdf"))]
2301 {
2302 Ok(crate::redact::run(document, opts, &detector))
2303 }
2304 }
2305
2306 /// Rewrite detected code blocks with the CodeFormulaV2 VLM (docling's
2307 /// `do_code_enrichment`). Off by default.
2308 ///
2309 /// The model re-reads the code crop at ~120 dpi, emits the clean source
2310 /// text (line breaks included) and identifies the language, which lands in
2311 /// the JSON `code_language` field. Needs the `.models/code_formula/` graphs
2312 /// (fetched by `scripts/install/download_dependencies.sh`); a missing
2313 /// model warns once and leaves the block as extracted.
2314 pub fn do_code_enrichment(mut self, enable: bool) -> Self {
2315 self.enrich.code = enable;
2316 self
2317 }
2318
2319 /// Decode display formulas to LaTeX with the CodeFormulaV2 VLM (docling's
2320 /// `do_formula_enrichment`). Off by default.
2321 ///
2322 /// An enriched formula renders as `$$latex$$` in Markdown and as a
2323 /// `formula` text item in the JSON, replacing the
2324 /// `<!-- formula-not-decoded -->` placeholder. Same model artifacts as
2325 /// [`do_code_enrichment`](Self::do_code_enrichment).
2326 pub fn do_formula_enrichment(mut self, enable: bool) -> Self {
2327 self.enrich.formula = enable;
2328 self
2329 }
2330
2331 /// Pre-render HTML-routing input in a headless browser before parsing.
2332 ///
2333 /// Off by default. When enabled, HTML sources — and MHTML/EPUB, which
2334 /// assemble HTML from their archives — are loaded in the system Chromium
2335 /// (driven from Rust over the DevTools protocol — no Node/Playwright) so the
2336 /// CSS cascade is resolved: elements the browser computes as `display:none`
2337 /// (e.g. a stylesheet-collapsed nav menu) are removed before the normal HTML
2338 /// backend runs. This is the one behaviour a pure-Rust parse can't reproduce;
2339 /// everything else (structure, tables, KVP, formatting) is still handled in
2340 /// Rust on the cleaned HTML.
2341 ///
2342 /// Requires the crate's `web-browser` Cargo feature; without it, converting
2343 /// an HTML source with this enabled returns [`ConversionError::Browser`].
2344 pub fn use_web_browser(mut self, enable: bool) -> Self {
2345 self.use_web_browser = enable;
2346 self
2347 }
2348
2349 /// Return `html` unchanged, or — when [`use_web_browser`](Self::use_web_browser)
2350 /// is on — its headless-browser-cleaned form (computed-hidden elements
2351 /// removed). Borrows in the common (disabled) case; only allocates when the
2352 /// browser actually runs.
2353 fn maybe_prerender<'a>(
2354 &self,
2355 html: &'a str,
2356 ) -> Result<std::borrow::Cow<'a, str>, ConversionError> {
2357 crate::backend::maybe_prerender_html(html, self.use_web_browser)
2358 }
2359
2360 /// Convert a source document to Markdown **incrementally**, returning an
2361 /// iterator of Markdown chunks (with picture placeholders).
2362 ///
2363 /// Concatenating every `Ok` chunk reproduces
2364 /// [`convert`](Self::convert)`(...).document.export_to_markdown()`
2365 /// byte-for-byte. The win is for PDF, whose pages are processed in parallel:
2366 /// each page's Markdown is emitted in document order as soon as it is ready, so
2367 /// output starts before the whole document is converted. Other formats build
2368 /// their document up front and stream it through the same interface.
2369 ///
2370 /// Streaming is Markdown-only — JSON needs the whole node tree, so there is no
2371 /// streaming JSON. The conversion runs on a background thread; dropping the
2372 /// returned [`MarkdownStream`] cancels it.
2373 #[cfg(feature = "pdf")]
2374 pub fn convert_streaming(
2375 &self,
2376 source: SourceDocument,
2377 ) -> Result<MarkdownStream, ConversionError> {
2378 self.convert_streaming_images(source, ImageMode::Placeholder)
2379 }
2380
2381 /// Like [`convert_streaming`](Self::convert_streaming) but with an explicit
2382 /// picture [`ImageMode`].
2383 ///
2384 /// [`ImageMode::Referenced`] streams too (issue #80): each page's images
2385 /// are written to [`artifacts_dir`](Self::artifacts_dir) *as the page's
2386 /// Markdown is emitted* and dropped from memory, so an image-heavy PDF
2387 /// holds ~one page of images at a time instead of all of them until
2388 /// export. The chunks and files match the buffered
2389 /// `export_to_markdown_with_images(ImageMode::Referenced, ..)` output.
2390 #[cfg(feature = "pdf")]
2391 pub fn convert_streaming_images(
2392 &self,
2393 source: SourceDocument,
2394 image_mode: ImageMode,
2395 ) -> Result<MarkdownStream, ConversionError> {
2396 self.convert_streaming_with_options(
2397 source,
2398 &MarkdownExportOptions {
2399 image_mode,
2400 artifacts_dir: self.artifacts_dir.clone(),
2401 ..MarkdownExportOptions::default()
2402 },
2403 )
2404 }
2405
2406 /// Like [`convert_streaming_images`](Self::convert_streaming_images) but
2407 /// with every [`MarkdownExportOptions`] setting (#599): content layers,
2408 /// picture traversal, escaping, the image placeholder. Referenced images
2409 /// go under `options.artifacts_dir` (not the converter's
2410 /// [`artifacts_dir`](Self::artifacts_dir)). The concatenated chunks match
2411 /// the buffered `export_to_markdown_with_options(options)` byte-for-byte.
2412 #[cfg(feature = "pdf")]
2413 pub fn convert_streaming_with_options(
2414 &self,
2415 source: SourceDocument,
2416 options: &MarkdownExportOptions,
2417 ) -> Result<MarkdownStream, ConversionError> {
2418 if let Some(allowed) = &self.allowed_formats {
2419 if !allowed.contains(&source.format) {
2420 return Err(ConversionError::UnsupportedFormat(source.format));
2421 }
2422 }
2423 let source = self.with_encoding(source);
2424 Ok(crate::stream::spawn(self.clone(), source, options.clone()))
2425 }
2426
2427 /// Whether the heading-hierarchy stage (#302) is enabled — the streaming
2428 /// front-end buffers PDF conversions when it is (the stage needs the whole
2429 /// assembled document, and streamed output must stay byte-identical to
2430 /// buffered output).
2431 #[cfg(feature = "pdf")]
2432 pub(crate) fn heading_hierarchy_enabled(&self) -> bool {
2433 self.heading_hierarchy
2434 }
2435
2436 /// Streaming internals ([`crate::stream`]) read the producer's settings
2437 /// off the converter clone they receive.
2438 #[cfg(feature = "pdf")]
2439 pub(crate) fn stream_settings(&self) -> crate::stream::StreamSettings {
2440 crate::stream::StreamSettings {
2441 strict: self.strict,
2442 no_table_former: self.no_table_former,
2443 no_text_panels: self.no_text_panels,
2444 text_layer_only: self.text_layer_only,
2445 no_ocr: self.no_ocr,
2446 password: self.password.clone(),
2447 force_full_page_ocr: self.force_full_page_ocr,
2448 enrich: self.enrich,
2449 page_range: self.page_range,
2450 ocr_lang: self.ocr_lang_choice(),
2451 ocr_engine: self.ocr_engine_choice(),
2452 tesseract_lang: self.tesseract_lang_choice(),
2453 ocr_mode: self.ocr_mode_choice(),
2454 ocr_scale: self.ocr_scale_choice(),
2455 ocr_textline_orientation: self.ocr_textline_orientation,
2456 images_scale: self.images_scale,
2457 page_break_placeholder: self.page_break_placeholder.clone(),
2458 compact_tables: self.compact_tables,
2459 picture_alt_text: self.picture_alt_text,
2460 metadata_output: self.metadata_output,
2461 document_timeout: self.document_timeout,
2462 redact: self.redact.clone(),
2463 }
2464 }
2465
2466 /// Convert a single source document.
2467 ///
2468 /// The source converts as its declared format (the extension's). Only if
2469 /// that fails is the content inspected: when it is evidently another
2470 /// format — RTF, an OOXML / ODF / EPUB package, an OLE Word / Excel /
2471 /// PowerPoint / Outlook file, PDF or HTML saved under the wrong extension
2472 /// (#556) — the conversion is retried once as that format, and the result
2473 /// reports the format it was converted as. A document that converts as
2474 /// declared is never inspected; when the retry fails too, or nothing is
2475 /// recognised, the first attempt's error stands.
2476 pub fn convert(&self, source: SourceDocument) -> Result<ConversionResult, ConversionError> {
2477 if let Some(allowed) = &self.allowed_formats {
2478 if !allowed.contains(&source.format) {
2479 return Err(ConversionError::UnsupportedFormat(source.format));
2480 }
2481 }
2482 let source = self.with_encoding(source);
2483 // A source a registered backend claims (#680) is that backend's:
2484 // its failure is not retried as the content's built-in format.
2485 if self.claims(&source) {
2486 return self.convert_as(&source);
2487 }
2488 let err = match self.convert_as(&source) {
2489 Ok(result) => return Ok(result),
2490 Err(err) => err,
2491 };
2492 let Some(format) = crate::sniff::detect(&source.bytes).filter(|f| {
2493 *f != source.format
2494 && self
2495 .allowed_formats
2496 .as_ref()
2497 .is_none_or(|allowed| allowed.contains(f))
2498 }) else {
2499 return Err(err);
2500 };
2501 let declared = source.format;
2502 let retry = SourceDocument { format, ..source };
2503 // The retry's error replaces the first one only when it says the
2504 // file is encrypted (#624) — an encrypted `.ppt` named `.pptx` is
2505 // better reported as encrypted than as a bad ZIP.
2506 let result = self.convert_as(&retry).map_err(|e| {
2507 if crate::backend::offcrypto::is_encryption_error(&e) {
2508 e
2509 } else {
2510 err
2511 }
2512 })?;
2513 // Converted, but not as the name said: worth a line, since the
2514 // mislabelled file is otherwise invisible.
2515 eprintln!(
2516 "docling: warning: {}: not a valid {} file; converted as {} (its content)",
2517 retry.name,
2518 declared.as_str(),
2519 format.as_str()
2520 );
2521 Ok(result)
2522 }
2523
2524 /// Convert `source` as its declared format, no retry.
2525 /// Whether `source` is a YouTube watch page fetched from its URL (#681)
2526 /// — HTML whose base URL names a video. Always false without the
2527 /// `youtube` feature, so such a page converts as the HTML it is.
2528 fn is_youtube_page(source: &SourceDocument) -> bool {
2529 #[cfg(feature = "youtube")]
2530 {
2531 source.format == InputFormat::Html
2532 && source
2533 .base_url
2534 .as_deref()
2535 .is_some_and(|url| crate::backend::youtube::video_id(url).is_some())
2536 }
2537 #[cfg(not(feature = "youtube"))]
2538 {
2539 let _ = source;
2540 false
2541 }
2542 }
2543
2544 /// A YouTube watch page's conversion (#681): the title, metadata and
2545 /// caption transcript, the language from `asr_lang`.
2546 #[cfg(feature = "youtube")]
2547 fn youtube_page(
2548 &self,
2549 source: &SourceDocument,
2550 ) -> Result<docling_core::DoclingDocument, ConversionError> {
2551 crate::backend::youtube::YoutubeBackend {
2552 lang: self.asr_lang.clone(),
2553 // The caption fetch follows the one hop YouTube's `timedtext`
2554 // may bounce through; the SSRF guard sees each.
2555 fetch: crate::fetch::FetchPolicy {
2556 max_redirects: 2,
2557 ..crate::fetch::FetchPolicy::default()
2558 },
2559 }
2560 .convert(source)
2561 }
2562
2563 #[cfg(not(feature = "youtube"))]
2564 fn youtube_page(
2565 &self,
2566 _source: &SourceDocument,
2567 ) -> Result<docling_core::DoclingDocument, ConversionError> {
2568 unreachable!("is_youtube_page is false without the youtube feature")
2569 }
2570
2571 fn convert_as(&self, source: &SourceDocument) -> Result<ConversionResult, ConversionError> {
2572 // Problems a conversion survives (docling's `ConversionResult.errors`):
2573 // today the PDF pipeline's spent document budget (#497).
2574 #[cfg_attr(not(feature = "pdf"), allow(unused_mut))]
2575 let mut errors: Vec<crate::ErrorItem> = Vec::new();
2576 // An encrypted Office document (#624/#625) is decrypted with the
2577 // converter's password (or the format's default password) into the
2578 // file the backend reads; without a key that opens it, the error
2579 // says the document is encrypted — not "bad zip" or an empty result.
2580 let unlocked;
2581 let source = match crate::backend::offcrypto::unlock(source, self.password.as_deref())? {
2582 Some(bytes) => {
2583 unlocked = SourceDocument {
2584 bytes,
2585 ..source.clone()
2586 };
2587 &unlocked
2588 }
2589 None => source,
2590 };
2591 let registered = self.backend_for(source);
2592 let mut document = if let Some(registered) = registered {
2593 // A registered backend (#680) ahead of every built-in format.
2594 registered.backend().convert(source)?
2595 } else {
2596 match source.format {
2597 // A legacy APS (Automated Patent System) plain-text patent (`PATN`
2598 // first record) is reconstructed verbatim, mirroring docling.
2599 InputFormat::Md if crate::backend::uspto::looks_like_aps(&source.text()?) => {
2600 crate::backend::uspto::convert_aps(source)?
2601 }
2602 // A text/Markdown-typed file that is actually an XML document (e.g. a
2603 // JATS article saved with a `.txt` extension) routes to the XML
2604 // backends by content, mirroring docling's content-based detection.
2605 InputFormat::Md if looks_like_xml(&source.text()?) => {
2606 match sniff_xml(&source.bytes) {
2607 InputFormat::XmlUspto => UsptoBackend.convert(source)?,
2608 InputFormat::XmlXbrl => crate::backend::xbrl::convert_xbrl(
2609 source,
2610 self.xbrl_taxonomy.as_deref(),
2611 )?,
2612 // docling's format detection reads an XML-looking `.txt` as
2613 // `application/xml` and, when its DOCTYPE names a JATS DTD
2614 // (`JATS-journalpublishing…` / `JATS-archive…`), converts it
2615 // with the JATS backend like a real `.nxml`; any other XML
2616 // saved as `.txt` is reconstructed generically
2617 // (element-by-element).
2618 _ if has_jats_doctype(&source.text()?) => JatsBackend {
2619 images: self.image_policy(),
2620 }
2621 .convert(source)?,
2622 _ => crate::backend::jats::convert_generic(source)?,
2623 }
2624 }
2625 // DeepSeek-OCR annotated Markdown (VLM token format) is detected by
2626 // its `<|ref|>…[[bbox]]` annotations and parsed separately.
2627 InputFormat::Md if is_deepseek_markdown(&source.text()?) => {
2628 DeepSeekBackend.convert(source)?
2629 }
2630 InputFormat::Md => MarkdownBackend {
2631 strict: self.strict,
2632 images: self.image_policy(),
2633 }
2634 .convert(source)?,
2635 InputFormat::Csv => CsvBackend.convert(source)?,
2636 // A YouTube watch page (#681): routed by the URL it was fetched
2637 // from, as MarkItDown's `accepts` does — its title, metadata and
2638 // caption transcript, not the page's markup.
2639 InputFormat::Html if Self::is_youtube_page(source) => self.youtube_page(source)?,
2640 InputFormat::Html => {
2641 // Optionally resolve the CSS cascade in a headless browser first
2642 // (strips computed-hidden elements); everything else stays in the
2643 // Rust HTML backend, which runs on the cleaned HTML.
2644 // Bytes → text through docling's BeautifulSoup decoding order
2645 // (#371): BOM, declared charset, UTF-8, windows-1252 — so a
2646 // legacy windows-1252 page converts instead of failing the
2647 // UTF-8 check every other text backend applies.
2648 let decoded = crate::backend::decode_html_bytes(&source.bytes);
2649 let html = self.maybe_prerender(&decoded)?;
2650 let policy = self.image_policy();
2651 if policy.sources != crate::ImageSources::None {
2652 let resolver = crate::backend::FsImageResolver::new(
2653 source.base_dir().map(|p| p.to_path_buf()),
2654 source.base_url.clone(),
2655 policy,
2656 );
2657 crate::backend::convert_html(&source.name, &html, &resolver)
2658 } else {
2659 crate::backend::convert_html(&source.name, &html, &crate::backend::NoFetch)
2660 }
2661 }
2662 InputFormat::Asciidoc => AsciiDocBackend {
2663 images: self.image_policy(),
2664 }
2665 .convert(source)?,
2666 InputFormat::Xlsx => XlsxBackend {
2667 skip_empty: self.skip_empty_cells,
2668 }
2669 .convert(source)?,
2670 InputFormat::Pptx => PptxBackend.convert(source)?,
2671 // RTF (#209): a docling.rs extension — docling reaches RTF only via
2672 // LibreOffice; here it parses natively (hand-rolled tokenizer).
2673 InputFormat::Rtf => RtfBackend.convert(source)?,
2674 InputFormat::Visio => VisioBackend.convert(source)?,
2675 // AbiWord (#216): docling.rs extension, native AWML parse.
2676 InputFormat::Abiword => AbwBackend.convert(source)?,
2677 // WordPerfect 5.x/6.x+ (#216): docling.rs extension, native parse
2678 // of the ÿWPC function-code stream.
2679 InputFormat::WordPerfect => WpdBackend.convert(source)?,
2680 // Microsoft Works word processor (#216): docling.rs extension,
2681 // native parse after libwps.
2682 InputFormat::Works => WpsBackend.convert(source)?,
2683 // StarOffice 5 binaries (#215): docling.rs extension, native CFB
2684 // parse (docling would go through LibreOffice).
2685 InputFormat::StarOffice5 => StarOffice5Backend.convert(source)?,
2686 // DjVu (#434): docling.rs extension, pure-Rust decode (`djvu-rs`).
2687 // The hidden text layer is the default; a scan-only DjVu falls back
2688 // to rasterize + OCR when the ML pipeline is built.
2689 InputFormat::Djvu => self.convert_djvu(source)?,
2690 // DIF/SYLK/dBase (#216): docling.rs extensions, one content-sniffing
2691 // backend for the three table relics.
2692 InputFormat::Dbf | InputFormat::Dif | InputFormat::Sylk => {
2693 InterchangeBackend.convert(source)?
2694 }
2695 // Lotus/Quattro/Works record streams (#216): one BOF-sniffing
2696 // backend for the whole DOS-era family.
2697 InputFormat::Lotus => LotusBackend.convert(source)?,
2698 // Quattro Pro (#216): docling.rs extension, native parse after
2699 // libwps (DOS/Windows record streams, QPW OLE zones).
2700 InputFormat::QuattroPro => QuattroBackend.convert(source)?,
2701 InputFormat::Docx => DocxBackend.convert(source)?,
2702 // Legacy binary Office (issue #127): parsed natively — docling
2703 // proper converts these through LibreOffice first (PR #3804).
2704 InputFormat::Xls => XlsBackend {
2705 skip_empty: self.skip_empty_cells,
2706 }
2707 .convert(source)?,
2708 InputFormat::Ppt => PptBackend.convert(source)?,
2709 InputFormat::Doc => DocBackend.convert(source)?,
2710 InputFormat::Vtt => WebVttBackend.convert(source)?,
2711 InputFormat::Ebcdic => EbcdicBackend {
2712 layout: self.ebcdic_layout.clone(),
2713 }
2714 .convert(source)?,
2715 InputFormat::Email => EmailBackend {
2716 list_attachments: self.list_attachments,
2717 images: self.image_policy(),
2718 }
2719 .convert(source)?,
2720 InputFormat::Mhtml => MhtmlBackend {
2721 images: self.image_policy(),
2722 use_web_browser: self.use_web_browser,
2723 }
2724 .convert(source)?,
2725 InputFormat::Epub => EpubBackend {
2726 images: self.image_policy(),
2727 use_web_browser: self.use_web_browser,
2728 }
2729 .convert(source)?,
2730 // A `.json` that is a Jupyter notebook (#673) — `"nbformat"` and
2731 // `"cells"` — reads as one, like MarkItDown's `application/json`
2732 // sniff; any other JSON is the docling-JSON backend's.
2733 InputFormat::JsonDocling => {
2734 if crate::backend::ipynb::looks_like_notebook(&source.text()?) {
2735 self.ipynb_backend().convert(source)?
2736 } else {
2737 DoclingJsonBackend.convert(source)?
2738 }
2739 }
2740 InputFormat::Jsonl => crate::backend::text::convert_json_text(source)?,
2741 InputFormat::Text => crate::backend::TextBackend.convert(source)?,
2742 InputFormat::Ipynb => self.ipynb_backend().convert(source)?,
2743 // RSS / Atom / RDF feeds (#678): the title, each item's heading,
2744 // date and body (its HTML through the HTML backend).
2745 InputFormat::Feed => crate::backend::FeedBackend {
2746 images: self.image_policy(),
2747 }
2748 .convert(source)?,
2749 // A bare `.xml` (#671): the dialects docling reads by content —
2750 // JATS by its DOCTYPE or `<article>` root — else one xml code
2751 // block with a warning, never an empty document.
2752 InputFormat::Xml => match sniff_xml(&source.bytes) {
2753 InputFormat::XmlUspto => UsptoBackend.convert(source)?,
2754 InputFormat::Feed => crate::backend::FeedBackend {
2755 images: self.image_policy(),
2756 }
2757 .convert(source)?,
2758 InputFormat::XmlXbrl => {
2759 crate::backend::xbrl::convert_xbrl(source, self.xbrl_taxonomy.as_deref())?
2760 }
2761 InputFormat::XmlDoclang => crate::backend::DoclangBackend.convert(source)?,
2762 _ if looks_like_jats(&source.bytes) => JatsBackend {
2763 images: self.image_policy(),
2764 }
2765 .convert(source)?,
2766 _ => crate::backend::text::convert_xml_text(source)?,
2767 },
2768 InputFormat::Latex => LatexBackend.convert(source)?,
2769 // A bare `.xml` defaults to XmlJats; sniff the content to route to the
2770 // right XML backend (docling distinguishes by DOCTYPE / root element).
2771 InputFormat::XmlJats | InputFormat::XmlUspto | InputFormat::XmlXbrl => {
2772 match sniff_xml(&source.bytes) {
2773 InputFormat::XmlUspto => UsptoBackend.convert(source)?,
2774 InputFormat::XmlXbrl => crate::backend::xbrl::convert_xbrl(
2775 source,
2776 self.xbrl_taxonomy.as_deref(),
2777 )?,
2778 _ => JatsBackend {
2779 images: self.image_policy(),
2780 }
2781 .convert(source)?,
2782 }
2783 }
2784 InputFormat::Odt | InputFormat::Ods | InputFormat::Odp => {
2785 crate::backend::convert_odf(source, &self.image_policy())?
2786 }
2787 // DocLang back in: bare XML (`.dclg`/`.dclg.xml`) or the OPC
2788 // archive `--to dclx` writes.
2789 InputFormat::XmlDoclang | InputFormat::Dclx => {
2790 crate::backend::DoclangBackend.convert(source)?
2791 }
2792 // Raw DocTags (VLM token markup, #152): the tolerant docling-core
2793 // parser — never fails, best-effort document out.
2794 InputFormat::DocTags => {
2795 let mut doc = docling_core::doctags::parse(&source.text()?);
2796 doc.name = source.name.clone();
2797 doc
2798 }
2799 #[cfg(feature = "pdf")]
2800 InputFormat::Pdf => {
2801 let converted = self
2802 .ml_pipeline()
2803 .and_then(|mut p| {
2804 p.set_force_full_page_ocr(self.force_full_page_ocr);
2805 p.set_pages(self.page_range);
2806 p.convert_outcome(&source.bytes, self.password.as_deref(), &source.name)
2807 })
2808 .map_err(|e| ConversionError::with_source("pdf", e))?;
2809 if let Some(message) = converted.completion.message() {
2810 errors.push(crate::ErrorItem::timeout(message));
2811 }
2812 converted.document
2813 }
2814 // SVG (#212), the ML route: rasterize (resvg, white-backed PNG at
2815 // ~2048px long side) and ride the image pipeline. `--no-ocr` /
2816 // `--text-layer-only` short-circuit to direct <text> extraction
2817 // instead — the SVG carries its text natively, so skipping OCR
2818 // must not mean losing it.
2819 #[cfg(feature = "pdf")]
2820 InputFormat::Svg if !self.text_layer_only && !self.no_ocr => {
2821 let png = crate::backend::svg::rasterize_png(&source.bytes)?;
2822 self.ml_pipeline()
2823 .and_then(|mut p| p.convert_image(&png, &source.name))
2824 .map_err(|e| ConversionError::with_source("svg", e))?
2825 }
2826 // SVG without the ML pipeline (pdf-text / wasm builds) or with
2827 // --no-ocr / --text-layer-only: pure-Rust <text> extraction, flat
2828 // paragraphs in reading order (the pdf / pdf-text split, applied
2829 // to SVG) — the SVG carries its text natively, so skipping OCR
2830 // must not mean losing it.
2831 InputFormat::Svg => crate::backend::SvgBackend.convert(source)?,
2832 // Apple iWork (#213): pure-Rust IWA text extraction, all builds.
2833 InputFormat::Pages | InputFormat::Numbers | InputFormat::Keynote => {
2834 crate::backend::IworkBackend.convert(source)?
2835 }
2836 #[cfg(feature = "pdf")]
2837 InputFormat::Image => self
2838 .ml_pipeline()
2839 .and_then(|mut p| p.convert_image(&source.bytes, &source.name))
2840 .map_err(|e| ConversionError::with_source("image", e))?,
2841 #[cfg(feature = "pdf")]
2842 InputFormat::MetsGbs => self
2843 .ml_pipeline()
2844 .and_then(|mut p| {
2845 docling_pdf::convert_mets_gbs_with_pipeline(
2846 &source.bytes,
2847 &source.name,
2848 &mut p,
2849 )
2850 })
2851 .map_err(|e| ConversionError::with_source("mets-gbs", e))?,
2852 // Audio → Whisper ASR (symphonia decode + ONNX inference); each
2853 // transcribed segment becomes a `[time: start-end] text` paragraph.
2854 #[cfg(feature = "asr")]
2855 InputFormat::Audio => docling_asr::convert_audio_with_options(
2856 &source.bytes,
2857 &source.name,
2858 self.asr_model.as_deref(),
2859 self.asr_lang.as_deref(),
2860 )
2861 .map_err(|e| ConversionError::with_source(source.format.as_str(), e))?,
2862 // Video (#138): the audio track transcribes through the same ASR
2863 // path (Phase 1), and — when the ffmpeg binary is available —
2864 // sampled frames interleave with the transcript as timestamped
2865 // pictures (Phase 2). Without ffmpeg: transcript only.
2866 #[cfg(feature = "asr")]
2867 InputFormat::Video => self
2868 .convert_video(source)
2869 .map_err(|e| ConversionError::with_source(source.format.as_str(), e))?,
2870 // Without the full ML pipeline, `pdf-text` still converts a PDF's
2871 // embedded text layer (pure Rust — the wasm32 path), equivalent to
2872 // `--text-layer-only`: flat paragraphs, no headings/tables/pictures. A
2873 // scanned PDF has no text layer, so an empty document means "this
2874 // needs OCR" — say so instead of returning nothing.
2875 #[cfg(all(feature = "pdf-text", not(feature = "pdf")))]
2876 InputFormat::Pdf => {
2877 let doc = docling_pdf::convert_text_layer_pages(
2878 &source.bytes,
2879 &source.name,
2880 self.page_range,
2881 )
2882 .map_err(|e| ConversionError::with_source("pdf", e))?;
2883 if doc.nodes.is_empty() {
2884 return Err(ConversionError::Parse(
2885 "PDF has no embedded text layer (scanned/image-only?); OCR needs a \
2886 build with the `pdf` feature"
2887 .into(),
2888 ));
2889 }
2890 doc
2891 }
2892 // Compiled without the ML pipelines: the formats stay detectable,
2893 // but converting them needs a build with the matching feature.
2894 #[cfg(not(any(feature = "pdf", feature = "pdf-text")))]
2895 InputFormat::Pdf => {
2896 return Err(ConversionError::Parse(
2897 "Pdf conversion is not compiled in (rebuild with the `pdf` feature, or \
2898 `pdf-text` for text-layer-only extraction)"
2899 .into(),
2900 ))
2901 }
2902 #[cfg(not(feature = "pdf"))]
2903 InputFormat::Image | InputFormat::MetsGbs => {
2904 return Err(ConversionError::Parse(format!(
2905 "{:?} conversion is not compiled in (rebuild with the `pdf` feature)",
2906 source.format
2907 )))
2908 }
2909 #[cfg(not(feature = "asr"))]
2910 InputFormat::Audio | InputFormat::Video => {
2911 return Err(ConversionError::Parse(format!(
2912 "{} conversion is not compiled in (rebuild with the `asr` feature)",
2913 source.format.as_str()
2914 )))
2915 }
2916 // Resolved for a registered backend (#680) that this converter
2917 // does not have.
2918 InputFormat::Plugin => {
2919 return Err(ConversionError::UnknownFormat {
2920 hint: format!(
2921 "'{}' was loaded for a registered backend, but none registered on \
2922 this converter claims it",
2923 source.name
2924 ),
2925 })
2926 }
2927 }
2928 };
2929 self.enrich_pictures(&mut document, source);
2930 // The file's own metadata (#679), read when an export will show it
2931 // (a docling-JSON input keeps what it carried) — before the PII
2932 // pass, which covers it too.
2933 if self.metadata_output.in_json() && document.metadata.is_empty() {
2934 document.metadata = crate::metadata::read(source, self.password.as_deref());
2935 }
2936 // The PII pass (#621) runs on the finished model, before anything
2937 // reads it — after the backend, before the export-side settings.
2938 let redaction = self.redact(&mut document)?;
2939 self.finish_document(&mut document);
2940
2941 let status = if errors.is_empty() {
2942 ConversionStatus::Success
2943 } else {
2944 ConversionStatus::PartialSuccess
2945 };
2946 Ok(ConversionResult {
2947 document,
2948 status,
2949 input_name: source.name.clone(),
2950 format: source.format,
2951 redaction,
2952 errors,
2953 })
2954 }
2955}
2956
2957/// A picture an enrichment pass may still describe: one without a
2958/// description, or with only the alt text its file carried (#676) — the
2959/// model's or the reader's answer replaces that fallback.
2960fn undescribed(description: &Option<docling_core::PictureDescription>) -> bool {
2961 description.as_ref().is_none_or(|d| d.is_alt_text())
2962}
2963
2964#[cfg(test)]
2965mod tests {
2966 use super::*;
2967
2968 /// The warm slot records the switches it was built with and rebuilds
2969 /// on a change (#669).
2970 #[cfg(feature = "pdf")]
2971 #[test]
2972 fn warm_pipeline_tracks_its_switches() {
2973 let warm = WarmPipeline::new();
2974 let full = PipelineSwitches::of(&DocumentConverter::new());
2975 let text = PipelineSwitches::of(&DocumentConverter::new().text_layer_only(true));
2976 assert_ne!(full, text);
2977 let built = |w: &WarmPipeline| w.slot.lock().unwrap().as_ref().map(|(s, _)| *s);
2978 assert_eq!(built(&warm), None, "nothing loads before the first lease");
2979 drop(warm.lease(full).unwrap());
2980 assert_eq!(built(&warm), Some(full));
2981 drop(warm.lease(text).unwrap());
2982 assert_eq!(built(&warm), Some(text));
2983 // Converters share the handle.
2984 let converter = DocumentConverter::new().warm_pipeline(&warm);
2985 drop(converter.ml_pipeline().unwrap());
2986 assert_eq!(built(&warm), Some(full));
2987 }
2988
2989 /// A conversion that panics holding the warm pipeline poisons its lock;
2990 /// the next one gets a fresh pipeline, not the half-used one or a panic.
2991 #[cfg(feature = "pdf")]
2992 #[test]
2993 fn warm_pipeline_recovers_from_a_panic() {
2994 let warm = WarmPipeline::new();
2995 let full = PipelineSwitches::of(&DocumentConverter::new());
2996 drop(warm.lease(full).unwrap());
2997 let held = warm.clone();
2998 let _ = std::thread::spawn(move || {
2999 let _slot = held.lease(full).unwrap();
3000 panic!("a conversion panics mid-document");
3001 })
3002 .join();
3003 assert!(warm.slot.is_poisoned());
3004 let slot = warm.lease(full).expect("recovered");
3005 assert!(slot.is_some());
3006 drop(slot);
3007 assert!(!warm.slot.is_poisoned());
3008 assert!(format!("{warm:?}").contains("WarmPipeline"));
3009 }
3010
3011 /// A file whose extension lies converts as its content after the
3012 /// declared format fails (#556); junk keeps its original error, and a
3013 /// format the converter does not allow is not retried into.
3014 #[test]
3015 fn mislabelled_sources_retry_as_their_content() {
3016 let conv = DocumentConverter::new();
3017 let as_doc =
3018 |bytes: &[u8]| SourceDocument::from_bytes("x", InputFormat::Doc, bytes.to_vec());
3019
3020 let rtf = conv
3021 .convert(as_doc(b"{\\rtf1\\ansi Hello RTF\\par}"))
3022 .unwrap();
3023 assert_eq!(rtf.format, InputFormat::Rtf);
3024 assert_eq!(rtf.document.export_to_markdown().trim(), "Hello RTF");
3025
3026 let html = conv
3027 .convert(as_doc(
3028 b"<!DOCTYPE html><html><body><p>Hello HTML</p></body></html>",
3029 ))
3030 .unwrap();
3031 assert_eq!(html.format, InputFormat::Html);
3032 assert_eq!(html.document.export_to_markdown().trim(), "Hello HTML");
3033
3034 let docx = std::fs::read(
3035 std::path::Path::new(env!("CARGO_MANIFEST_DIR"))
3036 .join("tests/data/docx/sources/docx_moveto_body.docx"),
3037 )
3038 .unwrap();
3039 let docx = conv.convert(as_doc(&docx)).unwrap();
3040 assert_eq!(docx.format, InputFormat::Docx);
3041 assert!(docx
3042 .document
3043 .export_to_markdown()
3044 .contains("avantMARK11apres"));
3045
3046 let err = conv.convert(as_doc(b"neither of them")).unwrap_err();
3047 assert!(err.to_string().contains("doc"), "{err}");
3048
3049 let only_doc = DocumentConverter::with_allowed_formats([InputFormat::Doc]);
3050 assert!(only_doc.convert(as_doc(b"{\\rtf1 Hello\\par}")).is_err());
3051 }
3052
3053 /// docling reads an XML-looking `.txt` as `application/xml` and converts
3054 /// it with the JATS backend when its DOCTYPE names a JATS DTD; other XML
3055 /// under `.txt` stays the generic element-by-element reconstruction.
3056 #[test]
3057 fn jats_doctype_text_file_uses_the_jats_backend() {
3058 let jats = "<!DOCTYPE article PUBLIC \"-//NLM//DTD JATS (Z39.96) Journal Archiving and Interchange DTD v1.2 20190208//EN\" \"JATS-archivearticle1.dtd\">\n<article><front><article-meta><title-group><article-title>T</article-title></title-group></article-meta></front><body><sec><title>S</title><p>Body.</p></sec></body></article>";
3059 let src = SourceDocument::from_bytes("a.txt", InputFormat::Md, jats.as_bytes().to_vec());
3060 let doc = DocumentConverter::new().convert(src).unwrap().document;
3061 assert!(doc.tree.is_some(), "JATS tree expected");
3062 assert_eq!(doc.export_to_markdown().trim(), "# T\n\n## S\n\nBody.");
3063 let other = "<?xml version=\"1.0\"?>\n<article><body><sec><title>S</title><p>Body.</p></sec></body></article>";
3064 let src = SourceDocument::from_bytes("b.txt", InputFormat::Md, other.as_bytes().to_vec());
3065 let doc = DocumentConverter::new().convert(src).unwrap().document;
3066 assert!(doc.tree.is_none(), "generic XML path expected");
3067 }
3068
3069 /// docling's `TextBackendOptions.encoding`: the converter's `encoding`
3070 /// decodes text inputs as named (a source's own setting wins), and an
3071 /// undecodable byte or unknown label is an error, not a guess.
3072 #[test]
3073 fn encoding_option_decodes_text_inputs() {
3074 let sjis = b"# \x93\xfa\x96\x7b\n".to_vec();
3075 let md = |c: &DocumentConverter, s: SourceDocument| {
3076 c.convert(s).map(|r| r.document.export_to_markdown())
3077 };
3078 let conv = DocumentConverter::new().encoding(Some("shift_jis".into()));
3079 let src = || SourceDocument::from_bytes("doc", InputFormat::Md, sjis.clone());
3080 assert_eq!(md(&conv, src()).unwrap().trim(), "# 日本");
3081 // Detection reads the same bytes as windows-1252.
3082 assert_ne!(
3083 md(&DocumentConverter::new(), src()).unwrap().trim(),
3084 "# 日本"
3085 );
3086 // The source's own encoding takes precedence over the converter's.
3087 let own = src().with_encoding(Some("shift_jis".into()));
3088 let latin = DocumentConverter::new().encoding(Some("latin1".into()));
3089 assert_eq!(md(&latin, own).unwrap().trim(), "# 日本");
3090 assert!(md(
3091 &DocumentConverter::new().encoding(Some("utf-8".into())),
3092 src()
3093 )
3094 .is_err());
3095 assert!(md(
3096 &DocumentConverter::new().encoding(Some("nope-1".into())),
3097 src()
3098 )
3099 .is_err());
3100 }
3101
3102 #[test]
3103 fn end_to_end_markdown() {
3104 let src =
3105 SourceDocument::from_bytes("doc", InputFormat::Md, b"# Hello\n\nWorld.\n".to_vec());
3106 let result = DocumentConverter::new().convert(src).unwrap();
3107 assert_eq!(result.status, ConversionStatus::Success);
3108 assert_eq!(result.document.export_to_markdown(), "# Hello\n\nWorld.\n");
3109 }
3110
3111 #[test]
3112 fn doctags_input_converts() {
3113 // Raw DocTags markup (#152) — the VLM token stream — as a first-class
3114 // input format (.doctags/.dt), through the tolerant docling-core
3115 // parser.
3116 let markup = b"<doctag><section_header_level_1><loc_1><loc_2><loc_3><loc_4>Intro</section_header_level_1><text>Body.</text></doctag>"
3117 .to_vec();
3118 let src = SourceDocument::from_bytes("page.doctags", InputFormat::DocTags, markup);
3119 let result = DocumentConverter::new().convert(src).unwrap();
3120 let md = result.document.export_to_markdown();
3121 assert!(md.contains("## Intro"), "{md}");
3122 assert!(md.contains("Body."), "{md}");
3123 }
3124
3125 #[test]
3126 fn doclang_xml_round_trips() {
3127 // Every input format now has a backend; DocLang XML reads back in and
3128 // re-exports as Markdown.
3129 let xml = b"<doclang version=\"0.7\">\n <heading>Title</heading>\n \
3130 <text>Hello <bold>world</bold></text>\n</doclang>"
3131 .to_vec();
3132 let src = SourceDocument::from_bytes("doc.dclg", InputFormat::XmlDoclang, xml);
3133 let result = DocumentConverter::new().convert(src).unwrap();
3134 let md = result.document.export_to_markdown();
3135 assert!(md.contains("# Title"), "{md}");
3136 assert!(md.contains("**world**"), "{md}");
3137 }
3138
3139 #[test]
3140 fn sniffs_uspto_doctype_case_insensitively() {
3141 // docling PR #3801: Grant Full Text v2.5 files were missed when the
3142 // DOCTYPE casing differed.
3143 for head in [
3144 "<?xml version=\"1.0\"?><!DOCTYPE PATDOC SYSTEM \"ST32-US-Grant-025xml.dtd\"><PATDOC/>",
3145 "<?xml version=\"1.0\"?><!DOCTYPE patdoc SYSTEM \"st32-us-grant-025xml.dtd\"><patdoc/>",
3146 "<?xml version=\"1.0\"?><US-PATENT-GRANT-V4/>",
3147 ] {
3148 assert_eq!(
3149 super::sniff_xml(head.as_bytes()),
3150 InputFormat::XmlUspto,
3151 "head: {head}"
3152 );
3153 }
3154 }
3155}