docling_core/document.rs
1//! The unified document representation.
2
3use crate::markdown::{to_markdown, to_markdown_images};
4use crate::ImageMode;
5
6/// The unified, format-agnostic document produced by every backend.
7///
8/// This is the heart of docling: backends parse their source format into a
9/// `DoclingDocument`, and serializers turn it back into Markdown, HTML, JSON,
10/// etc. Phase 0 uses a flat sequence of [`Node`]s; the production schema will
11/// match docling-core's body-tree-with-references layout.
12#[derive(Debug, Clone, PartialEq)]
13pub struct DoclingDocument {
14 /// Logical document name (usually the input file stem).
15 pub name: String,
16 /// Top-level content, in reading order.
17 pub nodes: Vec<Node>,
18 /// Default Markdown export mode for [`Self::export_to_markdown`]. `false`
19 /// (the default) reproduces docling's legacy output byte-for-byte; `true`
20 /// emits cleaner, more conformant Markdown. Set by `DocumentConverter`.
21 pub strict_markdown: bool,
22 /// Emit tables in the compact `| a | b |` / `| - | - |` form rather than
23 /// docling-core's width-padded GitHub serializer. The PDF backend sets this
24 /// (its committed groundtruth corpus predates the padded serializer); DOCX/HTML
25 /// leave it `false` to match current published docling.
26 pub compact_tables: bool,
27 /// Render a picture's author-written alt text (#676: the `descr` /
28 /// `title` of an OOXML picture's non-visual properties, carried as a
29 /// [`PictureDescription`] whose provenance is
30 /// [`PictureDescription::ALT_TEXT`]) in the Markdown and HTML exports
31 /// (the `` of an image line or the line above a placeholder;
32 /// the `<img alt>` and the description text). `false` (the default)
33 /// keeps it to the JSON (and DCLX) output, so the default Markdown and
34 /// HTML stay byte-for-byte docling's; strict Markdown renders it
35 /// regardless. Set by `DocumentConverter::picture_alt_text`.
36 pub picture_alt_text: bool,
37 /// What the file says about itself (#679): an EPUB's Dublin Core, an
38 /// Office package's properties, a photo's EXIF, an audio file's tags —
39 /// see [`crate::metadata`]. Read by the converter when
40 /// [`metadata_output`](Self::metadata_output) asks for it (a document
41 /// read from docling JSON keeps the `metadata` the JSON carried).
42 pub metadata: crate::metadata::DocumentMetadata,
43 /// Where [`metadata`](Self::metadata) goes in the exports: nowhere (the
44 /// default — every export stays docling's), the JSON's `metadata`
45 /// object, or that and YAML front matter at the top of the Markdown.
46 /// Set by `DocumentConverter::metadata_output`.
47 pub metadata_output: crate::metadata::MetadataOutput,
48 /// Text the Markdown export inserts between two pages — docling-core's
49 /// `MarkdownParams.page_break_placeholder` (e.g. `"<!-- page break -->"`).
50 /// `None` (the default) omits page breaks from Markdown, as docling does.
51 /// Set by `DocumentConverter::page_break_placeholder`. See
52 /// [`crate::markdown`] for where a break lands (only between two rendered
53 /// blocks that sit on different pages, never leading or trailing).
54 pub page_break_placeholder: Option<String>,
55 /// Hyperlinks recovered from the source, as `(anchor_text, href)` pairs in
56 /// document order. docling's standard pipeline drops PDF link annotations, so
57 /// these are rendered as Markdown `[anchor](href)` **only in strict mode**
58 /// (legacy/docling output is left byte-for-byte unchanged). The PDF backend
59 /// populates this from pdfium link annotations; other backends leave it empty.
60 pub links: Vec<(String, String)>,
61 /// Conversion-confidence report (#183), populated by the PDF/image ML
62 /// pipeline; `None` for declarative conversions. Deliberately **not**
63 /// part of any document export (docling keeps it on the conversion
64 /// result, outside the document schema) — docling-serve surfaces it in
65 /// the HTTP response instead.
66 pub confidence: Option<crate::confidence::ConfidenceReport>,
67 /// docling's item tree, when the backend built one (the HTML backend
68 /// does): the JSON export serializes it instead of deriving a tree from
69 /// `nodes`, so the JSON carries upstream's exact parent/child structure,
70 /// item numbering, inline groups, formatting and content layers. Every
71 /// other serializer reads `nodes`. See [`crate::tree`].
72 pub tree: Option<crate::tree::ItemTree>,
73 /// Rendered page images by 1-based page number — docling's
74 /// `PageItem.image`, filled by the PDF/image pipeline only when page
75 /// images are requested (docling's `generate_page_images`, #520). The
76 /// JSON export writes each as the page's `image`, so docling-core's
77 /// `TableItem.get_image` / `FormulaItem.get_image` can crop from it.
78 /// Empty otherwise; no other export reads it.
79 pub page_images: std::collections::BTreeMap<usize, PictureImage>,
80 /// What the reader ran into and read around (#912): a limit it hit —
81 /// an HTML page nested past `DOCLING_RS_MAX_HTML_DEPTH`, read as flat
82 /// text with no item tree and no source blocks — named, with the
83 /// effective limit, so a caller sees why the document lacks what it
84 /// lacks instead of an unexplained success. The converter reports each
85 /// as a `partial_success` error item.
86 pub notices: Vec<Notice>,
87}
88
89/// Something the reader did instead of what it does by default (#912),
90/// with the reason — see [`DoclingDocument::notices`].
91#[derive(Debug, Clone, PartialEq, Eq)]
92pub struct Notice {
93 pub kind: NoticeKind,
94 /// One line: what was hit, the effective limit, what the document
95 /// lacks because of it.
96 pub message: String,
97}
98
99/// What a [`Notice`] is about.
100#[derive(Debug, Clone, PartialEq, Eq)]
101pub enum NoticeKind {
102 /// The source nests deeper than the cap `variable` sets (its effective
103 /// value `limit`): it was read as flat text — the content is there,
104 /// the item tree and the source blocks are not.
105 DepthLimit {
106 /// The environment variable that sets the cap.
107 variable: &'static str,
108 limit: usize,
109 },
110}
111
112impl Notice {
113 /// A [`NoticeKind::DepthLimit`] notice for `what` (the format read).
114 pub fn depth_limit(what: &str, variable: &'static str, limit: usize) -> Self {
115 Notice {
116 kind: NoticeKind::DepthLimit { variable, limit },
117 message: format!(
118 "{what} nested deeper than {limit} elements ({variable}): read as flat text, \
119 without the item tree and the source blocks"
120 ),
121 }
122 }
123}
124
125/// A single piece of document content.
126#[derive(Debug, Clone, PartialEq)]
127pub enum Node {
128 /// A heading. `level` is 1-6.
129 Heading { level: u8, text: String },
130 /// A run of body text.
131 Paragraph { text: String },
132 /// A form checkbox (docling's `checkbox_selected`/`checkbox_unselected`): its
133 /// clean label `text` with the checked state. DocLang emits a `<checkbox>`
134 /// element head; Markdown/JSON render the task-list form (`- [x] `/`- [ ] `).
135 CheckboxItem { checked: bool, text: String },
136 /// A single list item at the given nesting `level` (0 = top). For ordered
137 /// items, `number` is the display number (honoring the list's `start`); it
138 /// is unused for unordered items. `first_in_list` marks the first item of a
139 /// list so the serializer can blank-line-separate adjacent sibling lists.
140 ///
141 /// `marker` is the DocLang enumeration marker (`"1."`, `"1.1."`, …) when the
142 /// backend provides one — HTML and DOCX set it for enumerated items, so
143 /// DocLang emits `<ldiv><marker>…</marker></ldiv>`; Markdown and the other
144 /// declarative backends leave it `None`, giving a bare `<ldiv/>` (matching
145 /// docling, whose Markdown backend passes no marker).
146 ListItem {
147 ordered: bool,
148 number: u64,
149 first_in_list: bool,
150 text: String,
151 level: u8,
152 marker: Option<String>,
153 /// Optional layout provenance (`x0,y0,x1,y1`, normalized to 0–511): the
154 /// four DocLang `<location>` values emitted inside the `<list>` right
155 /// after the item's `<ldiv>`. Set only by backends with real geometry
156 /// (e.g. PPTX shapes); `None` for the declarative backends. Kept on the
157 /// item itself (rather than a [`Node::Located`] wrapper) so consecutive
158 /// items still group into one `<list>`.
159 location: Option<[u16; 4]>,
160 /// DocLang-only override for items whose DocLang form diverges from their
161 /// flat Markdown `text`. Markdown/JSON always render the fields above; the
162 /// DocLang serializer, when this is `Some`, takes the list kind, marker,
163 /// and content from here instead. Used for docx multilevel numbering
164 /// (Markdown shows `- 1.1. x`, DocLang an ordered `<marker>1.1.</marker>`
165 /// with clean text) and inline equations/formatting in list items.
166 dclx: Option<ListItemDclx>,
167 /// The item's hyperlink target, when its content is a link — docling's
168 /// HTML backend emits it as an `<href uri=…/>` in the item head, and the
169 /// anchor's Markdown link markup is stripped from the rendered content.
170 /// `None` for a plain item; ignored by Markdown/JSON.
171 href: Option<String>,
172 /// Non-body content layer (docling's HTML site chrome before the first
173 /// heading → `furniture`). DocLang emits a `<layer value=…/>` in the item
174 /// head; Markdown/JSON drop a non-body item entirely.
175 layer: Option<ContentLayer>,
176 },
177 /// A fenced code block.
178 Code {
179 language: Option<String>,
180 text: String,
181 /// The original (pre-enrichment) text when the CodeFormula model
182 /// rewrote `text`: docling keeps the raw extraction in the JSON `orig`
183 /// field while `text` carries the model output. `None` → `orig == text`.
184 orig: Option<String>,
185 /// A line-preserving rendering, when the backend can reconstruct one
186 /// but docling's own output for the format cannot. The PDF pipeline
187 /// sets it (docling-parse joins code lines with single spaces, so
188 /// `text` carries that flat docling-parity form): **strict** Markdown
189 /// prefers `pretty`, every byte-conformance surface (legacy Markdown,
190 /// JSON, DocLang, chunks) serializes `text`.
191 pretty: Option<String>,
192 },
193 /// A table. The first row is treated as the header.
194 Table(Table),
195 /// A picture/figure, with an optional caption and (when a backend extracts
196 /// it) the embedded image itself.
197 Picture {
198 caption: Option<String>,
199 /// Hyperlink annotation on the caption (docling's caption text item
200 /// `hyperlink`): the HTML backend sets it when an `<a href>` wraps the
201 /// image whose `alt` became the caption. DocLang emits the block-form
202 /// `<caption>` with an `<href uri=…/>` head; JSON puts `hyperlink` on
203 /// the caption item; Markdown and LaTeX print the plain caption text,
204 /// as docling does.
205 caption_href: Option<String>,
206 image: Option<PictureImage>,
207 /// DocumentPictureClassifier predictions (all classes, descending
208 /// confidence), when the picture-classification enrichment ran.
209 /// Serialized as docling's `classification` annotation + `meta` field
210 /// on the JSON picture item; Markdown/DocLang output is unaffected.
211 classification: Option<Vec<PictureClass>>,
212 /// Text read off the embedded image by the picture-OCR enrichment
213 /// (#645) — docling's `PictureDescriptionData` annotation /
214 /// `meta.description`, which is where upstream's picture-description
215 /// models (VLM captioning) put their text too. JSON and DCLX carry it
216 /// structurally; Markdown prints it between the caption and the
217 /// image placeholder, where docling's picture serializer renders
218 /// annotations. `None` when the enrichment did not run or read no
219 /// text, so every default export stays unchanged.
220 description: Option<PictureDescription>,
221 /// Where the caption item hangs in the JSON tree (#390); see
222 /// [`CaptionParent`]. Markdown, DocLang and LaTeX ignore it.
223 caption_parent: CaptionParent,
224 /// The caption's own box on the picture's page (0–511 grid, like
225 /// [`Node::Located`]) — the PDF pipeline's caption layout region. The
226 /// JSON export writes it as the caption item's `prov` (#609), as
227 /// docling's `ReadingOrderModel._add_caption_or_footnote` does; `None`
228 /// (every declarative backend) leaves the caption without one.
229 caption_location: Option<[u16; 4]>,
230 },
231 /// A display-math formula item decoded by the CodeFormula enrichment:
232 /// `latex` is the model's LaTeX (no `$$` wrapping), `orig` the raw glyph
233 /// text extracted from the PDF. Markdown renders `$$latex$$`; JSON emits a
234 /// `formula` text item (docling's un-enriched pipeline instead emits a
235 /// placeholder paragraph — see the PDF assembler).
236 Formula {
237 latex: String,
238 orig: String,
239 location: Option<[u16; 4]>,
240 },
241 /// A standalone caption item (docling's `DocItemLabel.CAPTION` text that
242 /// no picture or table claims): the HTML backend emits a `<figure>`'s
243 /// `<figcaption>` this way when the figure produced no picture and its
244 /// first item is not a table (docling#4050). `href` is the caption's
245 /// hyperlink annotation (the first link inside the figcaption); Markdown
246 /// renders it as `[text](href)`, JSON puts `hyperlink` on the caption
247 /// item, DocLang emits the block-form `<caption>` with an `<href>` head.
248 Caption { text: String, href: Option<String> },
249 /// A body text item with a docling label of its own and an optional
250 /// hyperlink — the PDF pipeline's `footnote` regions, whose item docling
251 /// keeps as a `footnote` text with the link annotation covering it as its
252 /// `hyperlink` (`PageAssembleModel._match_hyperlink`). The JSON writes
253 /// exactly that (label, raw text, `hyperlink`); every other serializer
254 /// renders it as the paragraph [`Self::labeled_markdown`] spells —
255 /// docling's Markdown wraps a linked item's whole text, `[text](uri)`.
256 LabeledText {
257 label: String,
258 text: String,
259 href: Option<String>,
260 },
261 /// A chart (docling's `PictureItem` classified as a chart, carrying a
262 /// `PictureTabularChartData` annotation). Markdown and JSON render it exactly
263 /// like a [`Node::Picture`] placeholder (an `<!-- image -->` / `picture`
264 /// item); the DocLang serializer emits `<picture class="chart">` with a
265 /// `<label value="{kind}"/>` and the data `table` as a `<tabular>`.
266 Chart {
267 /// docling's classification label, e.g. `bar_chart`, `line_chart`.
268 kind: String,
269 /// The chart's data grid (row 0 is the header band).
270 table: Table,
271 /// The chart title (docling's caption item on the picture).
272 caption: Option<String>,
273 /// DocLang `<location>` provenance for the picture element.
274 location: Option<[u16; 4]>,
275 },
276 /// A logical grouping of child nodes (e.g. a list, a section, a spreadsheet
277 /// sheet). `name` is docling's group name when it differs from the label —
278 /// an xlsx sheet group is `label: "sheet"`, `name: Some("Sheet1")`. `layer`
279 /// puts the group *and* everything it contains on a non-body content layer
280 /// (a hidden sheet is `invisible`), which is how the serializers that only
281 /// render body content know to skip it; DocLang stamps each child with the
282 /// layer token, exactly as a [`Node::Furniture`] wrapper on each would.
283 /// DocLang has no group element, so a group is transparent there.
284 Group {
285 label: String,
286 name: Option<String>,
287 layer: Option<ContentLayer>,
288 children: Vec<Node>,
289 },
290 /// A form key-value region (docling's `field_region`): a set of form fields,
291 /// each pairing an optional marker, key, and value. Backends detect these
292 /// from form structure (e.g. HTML's `keyN` / `keyN_valueM` / `keyN_marker`
293 /// `id`-convention); the serializers render each item's parts as separate
294 /// labelled texts (`marker` / `field_key` / `field_value`).
295 FieldRegion { items: Vec<FieldItem> },
296 /// docling's `KeyValueItem`: a graph of key and value cells and the links
297 /// between them (docling-core's `GraphData`). The XBRL backend builds one
298 /// from an instance's numeric facts and the presentation and calculation
299 /// hierarchies of its taxonomy. Only the JSON export carries the graph:
300 /// docling's Markdown serializer has no rendering for the item and writes
301 /// its `<!-- missing-key-value-item -->` placeholder, which the Markdown
302 /// export reproduces; the other serializers omit it.
303 KeyValueGraph {
304 cells: Vec<GraphCell>,
305 links: Vec<GraphLink>,
306 },
307 /// Rich inline content — docling's `InlineGroup`: a run of styled text
308 /// segments that a backend captured with formatting (`<bold>`, `<italic>`,
309 /// `<underline>`, `<strikethrough>`, sub/superscript, inline `<code>`) the
310 /// flat Markdown text cannot represent. Markdown/JSON render this exactly
311 /// like `Paragraph { text: md_text }` (so their output is unchanged); the
312 /// DocLang serializer uses the structured `runs`. `unwrapped` is set when the
313 /// group's docling parent is a heading/text (no enclosing `<text>` wrapper).
314 InlineGroup {
315 unwrapped: bool,
316 runs: Vec<InlineRun>,
317 md_text: String,
318 },
319 /// A PDF text item whose superscripts and subscripts the opt-in
320 /// script-position stage marked (#1005, docling's `ScriptPositionModel`,
321 /// `script_position_options.enabled`). `inner` is the item — a paragraph
322 /// or a footnote — with its text already the runs' joined text (Markdown-
323 /// escaped, `E = mc2 in 1905.`): every serializer but JSON and DocLang
324 /// renders it as it is. The JSON writes docling's shape — the item with
325 /// an empty `text`, holding an inline group of the runs, each a text item
326 /// with `formatting.script` and the box of its own characters — and
327 /// DocLang writes the runs as an inline group.
328 ScriptText {
329 inner: Box<Node>,
330 runs: Vec<ScriptRun>,
331 },
332 /// A node in a non-body content layer — `furniture` (page headers/footers,
333 /// the HTML `<title>`, site navigation/chrome) or `notes` (docx comments).
334 /// Markdown and JSON omit these layers by default; DocLang renders the wrapped
335 /// node with a `<layer value="{layer}"/>` head.
336 Furniture {
337 layer: ContentLayer,
338 inner: Box<Node>,
339 },
340 /// One reviewer comment: docling's notes-layer `comment_section` group
341 /// holding a single text item. `name` is docling's own — `comment-{id}` for
342 /// a docx `w:comment`, `comment-{sheet}-{cell}` for a spreadsheet cell note.
343 /// JSON emits the group plus its notes-layer text; DocLang emits the flat
344 /// `<text><layer value="notes"/>…</text>` upstream writes (its DocLang
345 /// carries no group for comments); Markdown and LaTeX omit the notes layer.
346 ///
347 /// `refs_note_text` picks what a [`Node::Commented`] annotation points at,
348 /// mirroring an upstream asymmetry: docling-core's `add_comment` appends the
349 /// **note text**'s ref to each target (which is what the xlsx backend gets),
350 /// while the docx backend overwrites that with the **group**'s ref so a
351 /// comment's replies group together.
352 ///
353 /// `grouped` is whether docling wraps the note in a `comment_section`
354 /// group at all: the docx and spreadsheet backends do, while backends that
355 /// call docling-core's `add_comment` directly (Pages, #383) get a bare
356 /// notes-layer text item under the body — JSON then emits no group and
357 /// `name` is unused.
358 CommentSection {
359 name: String,
360 text: String,
361 refs_note_text: bool,
362 grouped: bool,
363 },
364 /// A body item annotated by reviewer comments: `comments` are indices into
365 /// the document's [`Node::CommentSection`] nodes, in document order. JSON
366 /// emits docling's `comments: [{"$ref": …}]` on the item, each ref pointing
367 /// where the section says (see [`Node::CommentSection::refs_note_text`]);
368 /// every other serializer renders `inner` unchanged.
369 Commented {
370 comments: Vec<usize>,
371 inner: Box<Node>,
372 },
373 /// A text node taken from a time-based track — an ASR segment (#614):
374 /// A link destination (#852: a `.doc` bookmark; the DOCX item tree
375 /// keeps its own, #849): the identifier the document's internal links
376 /// (`#id`) point at. Rendered by nothing but the JSON builder, which
377 /// hands it to the next text item for the Pandoc AST (`_anchors`).
378 Anchor { id: String },
379 /// docling's `TrackSource`. The JSON writes docling's ASR text item — `cue`
380 /// (the segment's words) as its text, `track` as its `source: [{"kind":
381 /// "track", …}]` — which the WebVTT export makes a cue of; every other
382 /// serializer renders `inner` (the `[time: start-end] words` paragraph)
383 /// unchanged.
384 Track {
385 track: crate::tree::TreeTrack,
386 cue: String,
387 inner: Box<Node>,
388 },
389 /// A node carrying layout provenance — the four DocLang `<location>` values
390 /// (`x0,y0,x1,y1`, normalized to 0–511) docling attaches to elements from
391 /// backends with real geometry (e.g. the slide shapes in PPTX). Markdown and
392 /// JSON render the wrapped node unchanged; DocLang emits the `<location>`
393 /// tokens as the element's first children.
394 Located {
395 location: [u16; 4],
396 inner: Box<Node>,
397 },
398 /// Exact page provenance for a backend whose geometry already *is* the
399 /// page's coordinate system — an XLSX item's cell-index box on its sheet,
400 /// which docling writes verbatim (`bbox` in a top-left origin, the
401 /// `charspan` the backend chose) and sizes the page from. The 0–511 grid
402 /// of a [`Node::Located`] cannot round-trip such integers exactly, so the
403 /// JSON export reads this wrapper; every other serializer renders `inner`
404 /// unchanged (DocLang keeps taking its `<location>` tokens from the grid).
405 Prov {
406 page_no: usize,
407 /// `[l, t, r, b]`, page units, top-left origin.
408 bbox: [f32; 4],
409 /// docling's `charspan` for the item (`[0, 0]` for an XLSX table).
410 charspan: [usize; 2],
411 /// The bbox's origin: docling's `BOTTOMLEFT` (a PDF page's
412 /// provenance, as a docling-JSON input carries it — #899) or
413 /// `TOPLEFT` (an XLSX sheet's cell box).
414 bottom_left: bool,
415 /// The item's creation rank among its siblings, when that differs
416 /// from the node order: docling numbers `#/tables/N` / `#/texts/N` /
417 /// `#/pictures/N` in the order it *creates* items (a sheet's tables,
418 /// then its images, then its charts) and only afterwards sorts the
419 /// container's children by position. The JSON export adds siblings in
420 /// this order and lays their refs out in node order; `None` when the
421 /// two orders coincide.
422 seq: Option<usize>,
423 inner: Box<Node>,
424 },
425 /// A PDF page header or footer (docling's `page_header`/`page_footer`
426 /// furniture): DocLang emits `<page_header>`/`<page_footer>` with a
427 /// `<layer value="furniture"/>` head, the four `<location>` tokens, then the
428 /// text. The JSON writes it as a body-parented `page_header`/`page_footer`
429 /// text item on the furniture layer; Markdown omits it.
430 PageFurniture {
431 footer: bool,
432 location: [u16; 4],
433 text: String,
434 },
435 /// A furniture-layer text item with an explicit docling label — a page
436 /// header / footer paragraph (`page_header` / `page_footer`) or a note
437 /// body (`footnote`) from a backend that builds no item tree (#535: the
438 /// Word 97 `.doc` stories). The JSON writes a body-parented item of that
439 /// label on the furniture layer; DocLang `<{label}>` with a `<layer
440 /// value="furniture"/>` head (docling-core's own shape); Markdown, LaTeX
441 /// and the chunker leave it out like any furniture.
442 FurnitureText { label: String, text: String },
443 /// The text a PDF picture contains, kept the way docling keeps it: every
444 /// regular layout cluster > 80 % inside a picture cluster is that
445 /// `PictureItem`'s child (`LayoutPostprocessor._set_cluster_children`,
446 /// `ReadingOrderModel._add_child_elements`). Emitted right after its
447 /// picture node. The JSON export writes these nodes as items parented to
448 /// that picture, after its caption; docling's Markdown and LaTeX picture
449 /// serializers print only the caption and the image, so every other
450 /// serializer skips it — except the Markdown export asked to
451 /// `traverse_pictures` ([`MarkdownExportOptions`], #599), which renders
452 /// them after the picture like upstream's item walk does.
453 PictureChildren(Vec<Node>),
454 /// A page boundary — docling's implicit page break between pages. The PPTX
455 /// backend emits one between consecutive slides. DocLang renders it as
456 /// `<page_break/>`; Markdown and JSON omit it (matching docling's default
457 /// exports, which carry page breaks only in the document model).
458 PageBreak,
459 /// A text item docling hangs in a *list group*, after the item before it
460 /// (an AsciiDoc paragraph still pending when a list opened is flushed into
461 /// the list's group): docling-core's list serializer prints it as one more
462 /// line of the list, indented to the group's depth `level` — or, `glue`,
463 /// when it is an inline group, appended to the line before it with no
464 /// separator at all. `text` is Markdown, like a paragraph's. Every other
465 /// serializer reads it as a paragraph.
466 ListText { level: u8, text: String, glue: bool },
467 /// An invisible page marker — the first node of every page the PDF paths
468 /// assemble: the 1-based page number and the page size in PDF points. It
469 /// carries exactly what the JSON export needs to populate docling's
470 /// `pages` map and to denormalize the 0–511 `<location>` grid back into
471 /// BOTTOMLEFT point bboxes for per-item `prov` (#171). Every other
472 /// serializer skips it, so Markdown / DocLang / DocTags output is
473 /// byte-for-byte unchanged.
474 PageInfo {
475 /// 1-based page number (0 = "not yet numbered": the assembler emits
476 /// the marker, the document-level collector stamps the real number).
477 page_no: usize,
478 /// Page width in PDF points.
479 width: f32,
480 /// Page height in PDF points.
481 height: f32,
482 },
483 /// A node docling keeps in the document model (and DocLang) but leaves out
484 /// of the Markdown and JSON exports — e.g. an ODF *presentation*'s pictures
485 /// and charts, which appear in the `.dclx` body but not in its `.md`/`.json`.
486 /// DocLang renders the wrapped node in place; Markdown and JSON skip it.
487 DoclangOnly(Box<Node>),
488 /// A verbatim plain-text dump: one text item holding text whose line
489 /// breaks are content (a nested table flattened to its cells' text, an
490 /// ODF text box's raw text). Markdown/JSON render it as one text block,
491 /// DocLang as one `<text>` whose `<content>` keeps the breaks.
492 TextDump(String),
493}
494
495/// One run of a [`Node::ScriptText`]: a piece of the item's text at one
496/// script position, with its provenance — one entry per page it is on.
497#[derive(Debug, Clone, PartialEq)]
498pub struct ScriptRun {
499 /// The run's raw text (not Markdown-escaped), its spaces included:
500 /// serializers join runs with nothing.
501 pub text: String,
502 pub script: Script,
503 /// The run's provenance, one per page, in text order.
504 pub prov: Vec<ScriptRunProv>,
505 /// The item's link, on its baseline runs (each linked run exports as a
506 /// link of its own, so a marker stays out of it).
507 pub hyperlink: Option<String>,
508}
509
510/// Where a [`ScriptRun`] sits on one page: docling's `ProvenanceItem` with a
511/// bottom-left-origin box.
512#[derive(Debug, Clone, Copy, PartialEq)]
513pub struct ScriptRunProv {
514 /// 1-based page number.
515 pub page_no: usize,
516 /// `[l, t, r, b]`, PDF points, bottom-left origin (`t > b`).
517 pub bbox: [f32; 4],
518 /// The run's characters on this page, as a span of its `text`.
519 pub charspan: [usize; 2],
520}
521
522/// Vertical text position of an [`InlineRun`] — docling's `Script`.
523#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
524pub enum Script {
525 #[default]
526 Baseline,
527 Sub,
528 Super,
529}
530
531/// One styled segment of a [`Node::InlineGroup`] — the docling.rs analogue of a
532/// `TextItem` inside an `InlineGroup`, carrying the ancestor formatting docling
533/// tracks. `text` is already whitespace-normalized/trimmed (one segment per
534/// source text node). A hyperlink is intentionally not stored: DocLang drops the
535/// target inside inline scope, keeping only the anchor text.
536#[derive(Debug, Clone, PartialEq, Eq, Default)]
537pub struct InlineRun {
538 pub text: String,
539 pub bold: bool,
540 pub italic: bool,
541 pub underline: bool,
542 pub strike: bool,
543 pub script: Script,
544 pub code: bool,
545 /// An inline equation (`text` holds LaTeX): DocLang renders `<formula>…`,
546 /// Markdown/JSON keep the `$…$` already baked into the group's `md_text`.
547 pub formula: bool,
548}
549
550/// A DocLang content layer other than the default `body` (see [`Node::Furniture`]).
551#[derive(Debug, Clone, Copy, PartialEq, Eq)]
552pub enum ContentLayer {
553 /// Page headers/footers, HTML `<title>`, site navigation/chrome.
554 Furniture,
555 /// Editorial notes (docx reviewer comments).
556 Notes,
557 /// Invisible content (hidden spreadsheet sheets).
558 Invisible,
559 /// Background content (watermarks): docling-core 2.99's `background`
560 /// layer, which DocLang has and an `invisible` item is written to
561 /// (docling-core#800) — read back from a DocLang document.
562 Background,
563}
564
565impl ContentLayer {
566 /// The `<layer value="…"/>` token value.
567 pub fn value(self) -> &'static str {
568 match self {
569 ContentLayer::Furniture => "furniture",
570 ContentLayer::Notes => "notes",
571 ContentLayer::Invisible => "invisible",
572 ContentLayer::Background => "background",
573 }
574 }
575}
576
577/// A set of content layers, `body` included — docling-core's
578/// `set[ContentLayer]` (`HTMLParams.layers`,
579/// `export_to_html(included_content_layers=…)`), where `body` is a member
580/// like any other. [`Default`] is docling's `DEFAULT_CONTENT_LAYERS`: body
581/// only, so an export built with it is unchanged from before layers could
582/// be chosen (#499).
583#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
584pub struct ContentLayers {
585 /// The main content (items without an explicit layer).
586 pub body: bool,
587 /// [`ContentLayer::Furniture`]: page headers/footers, navigation chrome.
588 pub furniture: bool,
589 /// [`ContentLayer::Notes`]: reviewer comments and other editorial notes.
590 pub notes: bool,
591 /// [`ContentLayer::Invisible`]: hidden content (hidden sheets, …).
592 pub invisible: bool,
593 /// [`ContentLayer::Background`]: background content (watermarks).
594 pub background: bool,
595}
596
597impl Default for ContentLayers {
598 fn default() -> Self {
599 Self::BODY
600 }
601}
602
603impl ContentLayers {
604 /// Body only — docling's `DEFAULT_CONTENT_LAYERS`.
605 pub const BODY: Self = Self {
606 body: true,
607 furniture: false,
608 notes: false,
609 invisible: false,
610 background: false,
611 };
612 /// Every layer — Python's `set(ContentLayer)`.
613 pub const ALL: Self = Self {
614 body: true,
615 furniture: true,
616 notes: true,
617 invisible: true,
618 background: true,
619 };
620 /// No layer at all (nothing renders); build a set from it with
621 /// [`with`](Self::with) / [`with_body`](Self::with_body).
622 pub const NONE: Self = Self {
623 body: false,
624 furniture: false,
625 notes: false,
626 invisible: false,
627 background: false,
628 };
629
630 /// The set plus `layer`.
631 pub const fn with(mut self, layer: ContentLayer) -> Self {
632 match layer {
633 ContentLayer::Furniture => self.furniture = true,
634 ContentLayer::Notes => self.notes = true,
635 ContentLayer::Invisible => self.invisible = true,
636 ContentLayer::Background => self.background = true,
637 }
638 self
639 }
640
641 /// The set plus the body layer.
642 pub const fn with_body(mut self) -> Self {
643 self.body = true;
644 self
645 }
646
647 /// Whether `layer` is in the set; `None` is the body layer.
648 pub fn contains(&self, layer: Option<ContentLayer>) -> bool {
649 match layer {
650 None => self.body,
651 Some(ContentLayer::Furniture) => self.furniture,
652 Some(ContentLayer::Notes) => self.notes,
653 Some(ContentLayer::Invisible) => self.invisible,
654 Some(ContentLayer::Background) => self.background,
655 }
656 }
657
658 /// Whether the layer spelled `name` (`body`, `furniture`, `notes`,
659 /// `invisible`, `background` — the JSON `content_layer` values) is in
660 /// the set; an unknown name is not.
661 pub fn contains_name(&self, name: &str) -> bool {
662 match name {
663 "body" => self.body,
664 "furniture" => self.furniture,
665 "notes" => self.notes,
666 "invisible" => self.invisible,
667 "background" => self.background,
668 _ => false,
669 }
670 }
671
672 /// Parse a comma-separated list of layer names (`body,furniture`;
673 /// whitespace around a name is ignored, `all` is every layer). An
674 /// unknown name is the error.
675 pub fn parse_list(list: &str) -> Result<Self, String> {
676 let mut set = Self::NONE;
677 for name in list.split(',').map(str::trim).filter(|n| !n.is_empty()) {
678 match name {
679 "body" => set.body = true,
680 "furniture" => set.furniture = true,
681 "notes" => set.notes = true,
682 "invisible" => set.invisible = true,
683 "background" => set.background = true,
684 "all" => set = Self::ALL,
685 other => {
686 return Err(format!(
687 "unknown content layer `{other}` (expected body, furniture, notes, invisible, background or all)"
688 ))
689 }
690 }
691 }
692 Ok(set)
693 }
694}
695
696/// Options of the HTML export ([`DoclingDocument::export_to_html_with`]):
697/// docling-core's `HTMLParams` subset the port honours. [`Default`] is
698/// upstream's default export — placeholder images, `artifacts` as the
699/// referenced-image directory, the body layer only.
700#[derive(Debug, Clone, PartialEq, Eq)]
701pub struct HtmlExportOptions {
702 /// How pictures render (`HTMLParams.image_mode`): nothing but captions
703 /// and meta for [`ImageMode::Placeholder`], `data:` URIs when embedded,
704 /// `<img src>` paths under [`artifacts_dir`](Self::artifacts_dir) when
705 /// referenced.
706 pub image_mode: ImageMode,
707 /// The directory referenced images are named under, the Markdown
708 /// export's convention (`<artifacts_dir>/image_NNNNNN.<ext>`).
709 pub artifacts_dir: String,
710 /// The content layers rendered (`HTMLParams.layers`, #499): an item on a
711 /// layer outside the set is skipped, its children still walked — exactly
712 /// how docling-core's `get_excluded_refs` reads the set.
713 pub layers: ContentLayers,
714}
715
716impl Default for HtmlExportOptions {
717 fn default() -> Self {
718 Self {
719 image_mode: ImageMode::Placeholder,
720 artifacts_dir: "artifacts".to_string(),
721 layers: ContentLayers::BODY,
722 }
723 }
724}
725
726/// Options of the Markdown export
727/// ([`DoclingDocument::export_to_markdown_with_options`], #599): the
728/// docling-core `MarkdownParams` the port honours beyond the image mode.
729/// [`Default`] is upstream's default export — placeholder images,
730/// `artifacts` as the referenced-image directory, the body layer only, no
731/// picture traversal, HTML and underscore escaping on, `<!-- image -->` —
732/// so a document exported with it is byte-identical to
733/// [`DoclingDocument::export_to_markdown`].
734#[derive(Debug, Clone, PartialEq, Eq)]
735pub struct MarkdownExportOptions {
736 /// How pictures render (`MarkdownParams.image_mode`): the placeholder,
737 /// `data:` URIs when embedded, ``
738 /// when referenced (the bytes come back for the caller to write).
739 pub image_mode: ImageMode,
740 /// The directory referenced images are named under.
741 pub artifacts_dir: String,
742 /// The content layers rendered (`MarkdownParams.layers`,
743 /// `export_to_markdown(included_content_layers=…)`): an item on a layer
744 /// outside the set is skipped, its children still walked. The default
745 /// body-only set drops page headers/footers (`furniture`), reviewer
746 /// comments (`notes`) and hidden sheets (`invisible`), as upstream does; a
747 /// scanned form's running header reads out with
748 /// `ContentLayers::BODY.with(ContentLayer::Furniture)`. The extra items
749 /// render through the body's serializers — a page header is a paragraph.
750 pub layers: ContentLayers,
751 /// `CommonParams.traverse_pictures`: render the text items nested in a
752 /// picture (the PDF pipeline's picture children — a bordered form laid
753 /// out as one picture holds every field as a child) after the picture's
754 /// own caption and image, as upstream yields them. Off, a picture prints
755 /// only its caption and image.
756 pub traverse_pictures: bool,
757 /// `MarkdownParams.escape_html`: `&`, `<` and `>` in text as `&`,
758 /// `<`, `>` (Python's `html.escape(quote=False)`). Off, `R&D` stays
759 /// `R&D`.
760 pub escape_html: bool,
761 /// `MarkdownParams.escape_underscores`: `_` in text as `\_`. Off, the
762 /// text keeps its underscores.
763 pub escape_underscores: bool,
764 /// `MarkdownParams.image_placeholder`: what a picture prints as when it
765 /// renders no image data (the placeholder mode, or a picture without a
766 /// payload); upstream's `<!-- image -->`.
767 pub image_placeholder: String,
768 /// docling-core's `PlainTextDocSerializer` (#613, `export_to_text`,
769 /// docling's `--to text`): the Markdown walk with the decoration turned
770 /// off — headings without `#`, bold/italic/strikethrough markers and
771 /// inline code backticks dropped, a hyperlink reduced to its label, code
772 /// blocks unfenced, no GFM hard line breaks. List bullets/numbers,
773 /// checkbox marks and table grids stay. [`Self::plain_text`] pairs it
774 /// with upstream's `PlainTextParams` (no escaping, an empty image
775 /// placeholder).
776 pub plain_text: bool,
777}
778
779impl MarkdownExportOptions {
780 /// docling-core's `PlainTextParams` defaults (#613): [`Self::plain_text`]
781 /// on, HTML and underscore escaping off, pictures print nothing (their
782 /// captions still do), body layer only, no picture traversal — what
783 /// `DoclingDocument.export_to_text()` and docling's `--to text` write.
784 pub fn plain_text() -> Self {
785 Self {
786 escape_html: false,
787 escape_underscores: false,
788 image_placeholder: String::new(),
789 plain_text: true,
790 ..Self::default()
791 }
792 }
793}
794
795impl Default for MarkdownExportOptions {
796 fn default() -> Self {
797 Self {
798 image_mode: ImageMode::Placeholder,
799 artifacts_dir: "artifacts".to_string(),
800 layers: ContentLayers::BODY,
801 traverse_pictures: false,
802 escape_html: true,
803 escape_underscores: true,
804 image_placeholder: "<!-- image -->".to_string(),
805 plain_text: false,
806 }
807 }
808}
809
810/// DocLang-only content for a [`Node::ListItem`] whose DocLang form differs from
811/// its flat Markdown `text` (see [`Node::ListItem::dclx`]). `ordered` picks the
812/// enclosing `<list>` kind, `marker` the `<ldiv><marker>`; content is `runs`
813/// (structured equations/formatting) when non-empty, else `text` re-parsed for
814/// inline markers.
815#[derive(Debug, Clone, PartialEq, Eq, Default)]
816pub struct ListItemDclx {
817 pub ordered: bool,
818 pub marker: Option<String>,
819 pub text: String,
820 pub runs: Vec<InlineRun>,
821}
822
823impl Node {
824 /// The paragraph a [`Node::LabeledText`] renders as outside the JSON:
825 /// its text, wrapped as `[text](uri)` when it carries a hyperlink. Any
826 /// other node is returned unchanged.
827 pub fn labeled_as_paragraph(&self) -> std::borrow::Cow<'_, Node> {
828 match self {
829 Node::LabeledText { text, href, .. } => std::borrow::Cow::Owned(Node::Paragraph {
830 text: match href {
831 Some(uri) => crate::hyperlink::markdown_link(text, uri),
832 None => text.clone(),
833 },
834 }),
835 other => std::borrow::Cow::Borrowed(other),
836 }
837 }
838}
839
840impl InlineRun {
841 /// A run with no active formatting (renders as bare inline text).
842 pub fn is_plain(&self) -> bool {
843 !self.bold
844 && !self.italic
845 && !self.underline
846 && !self.strike
847 && !self.code
848 && !self.formula
849 && self.script == Script::Baseline
850 }
851}
852
853/// Build the [`Node`] for a paragraph of inline content from its structured
854/// `runs` and Markdown text, applying docling's `InlineGroup` boundary:
855///
856/// * a single plain run (or none) → a plain [`Node::Paragraph`] (which the
857/// serializers render as `<text>…</text>`, and a lone hyperlink via `<href>`);
858/// * a single uniformly-formatted run, or two or more runs → a
859/// [`Node::InlineGroup`]. `unwrapped` (the group's docling parent is a
860/// heading, so no enclosing `<text>`) only applies to multi-run groups.
861///
862/// Markdown/JSON render the group's `md_text`, so their output is identical to
863/// emitting a `Paragraph` — the structured runs are DocLang-only.
864pub fn inline_paragraph_node(md_text: String, runs: Vec<InlineRun>, unwrapped: bool) -> Node {
865 let single_plain = runs.len() <= 1 && runs.first().is_none_or(|r| r.is_plain());
866 if single_plain {
867 Node::Paragraph { text: md_text }
868 } else {
869 Node::InlineGroup {
870 unwrapped: unwrapped && runs.len() >= 2,
871 runs,
872 md_text,
873 }
874 }
875}
876
877/// One entry of a [`Node::FieldRegion`]: a marker/key/value triple, any of which
878/// may be absent. Mirrors docling's `field_item` with its `marker` / `field_key`
879/// / `field_value` child texts.
880#[derive(Debug, Clone, PartialEq, Default)]
881pub struct FieldItem {
882 pub marker: Option<String>,
883 pub key: Option<String>,
884 pub value: Option<String>,
885 /// docling's `kind` on the `field_value` item — `read_only` or
886 /// `fillable` (the value is or holds a form control); JSON-only.
887 pub value_kind: Option<String>,
888}
889
890/// One node of a [`Node::KeyValueGraph`] — docling-core's `GraphCell`.
891#[derive(Debug, Clone, PartialEq)]
892pub struct GraphCell {
893 /// docling's `GraphCellLabel` value: `key` or `value` (it also knows
894 /// `unspecified` and `checkbox`).
895 pub label: String,
896 /// The cell's number within its graph, what the links refer to.
897 pub cell_id: usize,
898 pub text: String,
899 /// The text before any cleanup — for an XBRL fact key, the concept's
900 /// qualified name where `text` is its local name.
901 pub orig: String,
902}
903
904/// One edge of a [`Node::KeyValueGraph`] — docling-core's `GraphLink`.
905#[derive(Debug, Clone, PartialEq)]
906pub struct GraphLink {
907 /// docling's `GraphLinkLabel` value: `to_value`, `to_child`, `to_parent`
908 /// or `to_key`.
909 pub label: String,
910 pub source_cell_id: usize,
911 pub target_cell_id: usize,
912}
913
914/// One DocumentPictureClassifier prediction — docling-core's
915/// `PictureClassificationClass` (`class_name` + `confidence`).
916#[derive(Debug, Clone, PartialEq)]
917pub struct PictureClass {
918 /// e.g. `bar_chart`, `logo`, `signature` (the classifier's 26-label set).
919 pub class_name: String,
920 pub confidence: f32,
921}
922
923/// A picture's text annotation — docling-core's `PictureDescriptionData`
924/// (`text` + `provenance`), the one shape upstream uses for every model that
925/// writes prose about a picture. The picture-OCR enrichment (#645) fills it
926/// with the lines the OCR engine read off the image, `provenance` naming the
927/// engine (`ppocr` / `tesseract`) the way a VLM description names its model.
928#[derive(Debug, Clone, PartialEq, Eq)]
929pub struct PictureDescription {
930 pub text: String,
931 pub provenance: String,
932}
933
934impl PictureDescription {
935 /// The provenance of a picture's author-written alt text (#676): the
936 /// `descr` (else `title`) of an OOXML picture's non-visual properties
937 /// — what DOCX, PPTX and XLSX authors type into "Alt Text". JSON writes
938 /// it as `meta.description.created_by`; Markdown renders it under strict
939 /// Markdown or `DoclingDocument::picture_alt_text`, HTML under the latter.
940 pub const ALT_TEXT: &'static str = "alt_text";
941
942 /// An alt-text description, see [`Self::ALT_TEXT`].
943 pub fn alt_text(text: impl Into<String>) -> Self {
944 Self {
945 text: text.into(),
946 provenance: Self::ALT_TEXT.to_string(),
947 }
948 }
949
950 /// Whether this description is a picture's alt text.
951 pub fn is_alt_text(&self) -> bool {
952 self.provenance == Self::ALT_TEXT
953 }
954
955 /// The (empty) provenance of a description docling's backend writes
956 /// itself as `PictureMeta.description` — `text` only, no `created_by`
957 /// and no legacy `annotations` entry: the alt text of an XLSX image
958 /// placed in a cell (docling#5015). Unlike [`Self::ALT_TEXT`] it is
959 /// upstream's own output, so every format renders it unconditionally.
960 pub const DOCLING_META: &'static str = "";
961
962 /// A docling-native description, see [`Self::DOCLING_META`].
963 pub fn docling_meta(text: impl Into<String>) -> Self {
964 Self {
965 text: text.into(),
966 provenance: Self::DOCLING_META.to_string(),
967 }
968 }
969
970 /// Whether this is a docling-native description ([`Self::DOCLING_META`]).
971 pub fn is_docling_meta(&self) -> bool {
972 self.provenance == Self::DOCLING_META
973 }
974}
975
976/// An extracted picture's raw encoded bytes plus its mimetype and pixel size —
977/// the docling.rs analogue of docling-core's `ImageRef`.
978#[derive(Debug, Clone, PartialEq)]
979pub struct PictureImage {
980 /// e.g. `image/png`, `image/jpeg`.
981 pub mimetype: String,
982 pub width: u32,
983 pub height: u32,
984 /// The image file bytes, exactly as embedded (PNG/JPEG/…).
985 pub data: Vec<u8>,
986 /// Pixels per inch of the image relative to the page it came from —
987 /// docling-core's `ImageRef.dpi`, which consumers use to map pixels back
988 /// to points. A crop rendered from a PDF page at `s` px/pt is `72·s`
989 /// (docling: `int(72 * images_scale)`, #519); an image embedded in an
990 /// office file has no render scale and keeps docling's `72`
991 /// ([`Self::DEFAULT_DPI`]).
992 pub dpi: u32,
993 /// The size the picture is *displayed* at in its document, in inches
994 /// (`[width, height]`, #834): a DOCX drawing's `wp:extent`, an ODT
995 /// frame's `svg:width` / `svg:height` — not the bitmap's pixel size
996 /// above, which docling's `ImageRef.size` carries. `None` when the
997 /// format has no such extent (a PDF crop, a standalone image). The
998 /// Pandoc export writes it as the `Image`'s `width` / `height`
999 /// attributes, as Pandoc's own readers do; docling's JSON has no field
1000 /// for it, so the JSON export leaves it out.
1001 pub display_size: Option<[f32; 2]>,
1002}
1003
1004impl PictureImage {
1005 /// docling's `ImageRef` default when no render scale applies.
1006 pub const DEFAULT_DPI: u32 = 72;
1007
1008 /// The `dpi` of an image rendered at `scale` pixels per PDF point
1009 /// (`72·scale`, rounded — `int()` would floor 143.99… to 143).
1010 pub fn dpi_for_scale(scale: f32) -> u32 {
1011 (72.0 * scale).round().max(1.0) as u32
1012 }
1013
1014 /// A `data:` URI for the image (`data:<mimetype>;base64,<…>`).
1015 pub fn data_uri(&self) -> String {
1016 format!(
1017 "data:{};base64,{}",
1018 self.mimetype,
1019 crate::base64::encode(&self.data)
1020 )
1021 }
1022}
1023
1024/// One table cell as a first-class object (#240) — the Rust counterpart of
1025/// docling's `TableCell`: its text, page geometry, grid rectangle and header
1026/// roles. Produced by the PDF TableFormer paths from the predicted OTSL
1027/// structure; `bbox` is `[l, t, r, b]` in page points with a top-left origin.
1028#[derive(Debug, Clone, PartialEq)]
1029pub struct TableCell {
1030 pub text: String,
1031 /// `[l, t, r, b]`, page points, top-left origin; `None` without geometry.
1032 pub bbox: Option<[f32; 4]>,
1033 /// Anchor grid position (0-based row/column offsets).
1034 pub start_row: usize,
1035 pub start_col: usize,
1036 /// Span extents (≥ 1); the covered grid positions repeat the cell's text
1037 /// in [`Table::rows`].
1038 pub row_span: usize,
1039 pub col_span: usize,
1040 /// OTSL `ched` — a column-header cell.
1041 pub column_header: bool,
1042 /// OTSL `rhed` — a row-header cell.
1043 pub row_header: bool,
1044 /// OTSL `srow` — a section-row cell.
1045 pub row_section: bool,
1046}
1047
1048/// Where a picture's or table's caption text item hangs in the docling-JSON
1049/// tree (#390). docling's backends do not agree, and the JSON structure is
1050/// the only surface that shows it (Markdown, DocLang and LaTeX place a
1051/// caption by its item, whatever its parent): the PDF pipeline parents a
1052/// layout caption to the picture or table it belongs to, while every
1053/// declarative backend creates the caption with `doc.add_text(label=CAPTION)`
1054/// and no parent — the document body — even when the item itself sits in a
1055/// group or under a section header (JATS, LaTeX, HTML, Markdown, EPUB,
1056/// AsciiDoc all do). The office backends hang a chart's title caption off the
1057/// chart's container (the sheet group, the slide, docx's current parent,
1058/// docling#4190) — that is [`Node::Chart`]'s own path, not this choice. A
1059/// backend that adds a new captioned item picks the variant matching
1060/// upstream's `add_text` call for that format; the default is upstream's
1061/// default.
1062#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
1063pub enum CaptionParent {
1064 /// `#/body`, listed after the enclosing top-level item — docling's
1065 /// `add_text` default, which every declarative backend leaves alone.
1066 #[default]
1067 Body,
1068 /// The item's own container (its `parent`), listed ahead of the item:
1069 /// the caption is created first, as docling's office backends do.
1070 Container,
1071 /// The item's own container, listed *after* the item: docling's HTML
1072 /// backend adds a `<figure>`-wrapped table, then its `<figcaption>` under
1073 /// `self.parents[self.level]` (docling#4050).
1074 ContainerAfter,
1075 /// The item itself — the caption is the picture's or table's first
1076 /// child, as docling's PDF pipeline attaches a layout caption.
1077 Item,
1078}
1079
1080/// A simple row-major table. By default `rows[0]` is the header row; a
1081/// [`TableStructure`] overlay overrides that and adds column spans.
1082#[derive(Debug, Clone, PartialEq, Default)]
1083pub struct Table {
1084 pub rows: Vec<Vec<String>>,
1085 /// Optional layout provenance: the four DocLang `<location>` values
1086 /// (`x0,y0,x1,y1`, each already normalized to the 0–511 resolution) emitted
1087 /// before the table's cells. Set only by backends with real geometry (e.g.
1088 /// the spreadsheet backend, whose cell grid yields a bounding box); left
1089 /// `None` by declarative backends, which have no coordinates.
1090 pub location: Option<[u16; 4]>,
1091 /// Optional OTSL structure overlay for backends that parse real table
1092 /// geometry (USPTO CALS): explicit header-row count and horizontal-span
1093 /// continuations. `None` → the default (row 0 is the header, no spans).
1094 /// `rows` still carries the full text grid (span text replicated) for
1095 /// Markdown/JSON; DocLang uses this overlay to emit `<ched/>`/`<lcel/>`.
1096 pub structure: Option<TableStructure>,
1097 /// Optional per-cell block content, parallel to `rows`. A *rich* cell (an
1098 /// ODF cell holding a list, several paragraphs, or a nested table) carries
1099 /// its DocLang blocks here; the DocLang serializer emits them after the
1100 /// cell token instead of the flat `rows` text. Markdown/JSON ignore this
1101 /// and render `rows`, so their output is unchanged. `None` (or an empty
1102 /// `Vec` for a given cell) → the flat text is used everywhere.
1103 pub cell_blocks: Option<Vec<Vec<Vec<Node>>>>,
1104 /// Optional caption (docling's `TableItem.captions`): the JATS
1105 /// `<table-wrap>` label+caption, an HTML `<caption>`, etc. Markdown renders
1106 /// it as a text line *before* the grid; JSON emits a caption text item the
1107 /// table references; DocLang emits a `<caption>` as the table's first child.
1108 /// `None` → the table has no caption.
1109 pub caption: Option<String>,
1110 /// Where the caption item hangs in the JSON tree (#390); see
1111 /// [`CaptionParent`]. Only the JSON export reads it.
1112 pub caption_parent: CaptionParent,
1113 /// The caption's own box on the table's page (0–511 grid) — the PDF
1114 /// pipeline's caption layout region, written as the caption item's
1115 /// `prov` (#609); see [`Node::Picture`]'s field of the same name.
1116 pub caption_location: Option<[u16; 4]>,
1117 /// The table's footnotes (docling's `TableItem.footnotes`, #1009): one
1118 /// text each, escaped like [`Self::caption`]. Markdown prints them after
1119 /// the grid, one paragraph each; JSON emits `footnote` text items under
1120 /// the table that its `footnotes` list references (docling-core#675).
1121 pub footnotes: Vec<String>,
1122 /// Optional per-cell bounding boxes, same shape as [`Self::rows`]: `[l, t,
1123 /// r, b]` in page points with a **top-left** origin (the PDF pipeline's
1124 /// native space). Set by the ML pipeline's TableFormer paths — a spanned
1125 /// cell repeats its anchor's box across the covered grid positions — and
1126 /// First-class cells (#240): the authoritative per-cell records —
1127 /// text, page geometry, spans and header roles — when the backend
1128 /// produces them (the PDF TableFormer paths do; declarative backends
1129 /// leave `None`). [`Self::rows`] stays the dense text grid every
1130 /// serializer renders (a spanning cell's text is replicated across its
1131 /// covered positions there); JSON serializes these cells verbatim when
1132 /// present, and the DocLang structure overlay is derived from them.
1133 pub cells: Option<Vec<TableCell>>,
1134 /// The table is a table of contents — docling's `document_index` label
1135 /// (#1091), which the PDF layout model gives a TOC region and docling
1136 /// keeps on the `TableItem`. Only the JSON export (and its read-back)
1137 /// tells it apart: every other serializer renders it as a table, as
1138 /// docling-core does.
1139 pub document_index: bool,
1140}
1141
1142impl Table {
1143 /// A cell's text at a grid position, `None` outside the grid.
1144 pub fn cell_text(&self, row: usize, col: usize) -> Option<&str> {
1145 self.rows.get(row)?.get(col).map(String::as_str)
1146 }
1147
1148 /// Replace the text at a grid position; `false` (and no change) outside
1149 /// the grid. When a first-class cell covers the position, the whole
1150 /// cell is updated: its record text and every grid position its span
1151 /// covers, so the repair shows once in Markdown, not once per covered
1152 /// column.
1153 pub fn set_cell_text(&mut self, row: usize, col: usize, text: impl Into<String>) -> bool {
1154 if self.rows.get(row).and_then(|r| r.get(col)).is_none() {
1155 return false;
1156 }
1157 let text = text.into();
1158 let covering = self.cells.as_mut().and_then(|cells| {
1159 cells.iter_mut().find(|c| {
1160 (c.start_row..c.start_row + c.row_span).contains(&row)
1161 && (c.start_col..c.start_col + c.col_span).contains(&col)
1162 })
1163 });
1164 if let Some(cell) = covering {
1165 cell.text = text.clone();
1166 let (r0, r1) = (cell.start_row, cell.start_row + cell.row_span);
1167 let (c0, c1) = (cell.start_col, cell.start_col + cell.col_span);
1168 for r in self.rows.iter_mut().take(r1).skip(r0) {
1169 for slot in r.iter_mut().take(c1).skip(c0) {
1170 *slot = text.clone();
1171 }
1172 }
1173 } else {
1174 self.rows[row][col] = text;
1175 }
1176 true
1177 }
1178
1179 /// Derive first-class cells (#240) from the dense grid plus the
1180 /// [`TableStructure`] overlay — how declarative tables (DOCX/XLSX merged
1181 /// regions, HTML `th`/spans, ODF covered cells, USPTO CALS) get real
1182 /// `TableCell` records without page geometry. Anchors are the positions
1183 /// not marked as span continuations; extents scan the continuation grids
1184 /// right/down (matching the DocLang `lcel`/`ucel` reading). Header roles
1185 /// come from the per-cell `col_header`/`row_header` grids when present,
1186 /// else the `header_row` band, else docling's declarative default (row 0
1187 /// is the header). Without any overlay every position is a 1×1 cell.
1188 pub fn derive_cells(&self) -> Vec<TableCell> {
1189 let s = self.structure.as_ref();
1190 let flag = |grid: Option<&Vec<Vec<bool>>>, r: usize, c: usize| {
1191 grid.and_then(|g| g.get(r))
1192 .and_then(|row| row.get(c))
1193 .copied()
1194 .unwrap_or(false)
1195 };
1196 let col_cont = |r: usize, c: usize| flag(s.map(|s| &s.col_continuation), r, c);
1197 let row_cont = |r: usize, c: usize| flag(s.map(|s| &s.row_continuation), r, c);
1198 let is_col_header = |r: usize, c: usize| match s {
1199 Some(st) if !st.col_header.is_empty() => flag(Some(&st.col_header), r, c),
1200 Some(st) if !st.header_row.is_empty() => st.header_row.get(r).copied().unwrap_or(false),
1201 _ => r == 0,
1202 };
1203 let mut cells = Vec::new();
1204 for (r, row) in self.rows.iter().enumerate() {
1205 for (c, text) in row.iter().enumerate() {
1206 if col_cont(r, c) || row_cont(r, c) {
1207 continue; // covered by a span anchor
1208 }
1209 let mut col_span = 1;
1210 while c + col_span < row.len() && col_cont(r, c + col_span) {
1211 col_span += 1;
1212 }
1213 let mut row_span = 1;
1214 while r + row_span < self.rows.len() && row_cont(r + row_span, c) {
1215 row_span += 1;
1216 }
1217 cells.push(TableCell {
1218 text: text.clone(),
1219 bbox: None,
1220 start_row: r,
1221 start_col: c,
1222 row_span,
1223 col_span,
1224 column_header: is_col_header(r, c),
1225 row_header: flag(s.map(|s| &s.row_header), r, c),
1226 row_section: false,
1227 });
1228 }
1229 }
1230 cells
1231 }
1232
1233 /// The number of leading grid rows that form the column header block —
1234 /// docling-core's `TableData._count_column_header_rows` (docling-core#767,
1235 /// 2.102, #778), shared by the Markdown serializer
1236 /// ([`Self::header_row_count`]) and the chunker's dataframe view, which
1237 /// must agree on where the header ends. Uses the first-class
1238 /// [`Self::cells`] when present (the PDF pipeline's TableFormer flags),
1239 /// else the cells derived from the structure overlay.
1240 ///
1241 /// - A row counts only when a `column_header` cell *starts* on it
1242 /// (docling-core#723): a header spanning several rows is replicated
1243 /// into each row it covers, and counting those would pull the data rows
1244 /// beneath it into the header block.
1245 /// - A row also stops the block when it *carries body text* (#604,
1246 /// docling-core#766): a cell starting on it that is not a column
1247 /// header, has non-blank text and does not start in the table's first
1248 /// column, which holds row labels left unmarked even on header rows. A
1249 /// scanned form flags its first-column labels `column_header` on every
1250 /// row; without the check each such row folded its values into the
1251 /// header.
1252 /// - Row 0 is exempt from that check — model-predicted header rows are
1253 /// often only partly flagged — unless a later row flags a cell starting
1254 /// in the first column: that marks a column of row headers, not a
1255 /// partly flagged header row.
1256 ///
1257 /// No fallback: a table without flags has no header rows here.
1258 pub fn column_header_row_count(&self) -> usize {
1259 if self.rows.is_empty() {
1260 return 0;
1261 }
1262 let derived;
1263 let cells: &[TableCell] = match &self.cells {
1264 Some(c) if !c.is_empty() => c,
1265 _ => {
1266 derived = self.derive_cells();
1267 &derived
1268 }
1269 };
1270 let num_rows = self.rows.len();
1271 let first_col = cells.iter().map(|c| c.start_col).min().unwrap_or(0);
1272 let leading_col_flagged_below = cells.iter().any(|c| {
1273 c.column_header && c.start_col == first_col && (1..num_rows).contains(&c.start_row)
1274 });
1275 let is_header_row = |r: usize| {
1276 let check_body = r > 0 || leading_col_flagged_below;
1277 let mut flagged = false;
1278 for c in cells.iter().filter(|c| c.start_row == r) {
1279 if c.column_header {
1280 flagged = true;
1281 } else if check_body && c.start_col != first_col && !c.text.trim().is_empty() {
1282 return false;
1283 }
1284 }
1285 flagged
1286 };
1287 (0..num_rows).take_while(|&r| is_header_row(r)).count()
1288 }
1289
1290 /// The number of leading grid rows the Markdown serializer renders as the
1291 /// header — docling-core's `_count_header_rows`:
1292 /// [`Self::column_header_row_count`], plus upstream's row-0 fallback for
1293 /// GFM, which needs a header row: `1` when no flag sits on any grid row
1294 /// below the first (a spanning header cell counts on every row it
1295 /// covers), so tables from backends that never set the flag keep row 0
1296 /// as the header. When flags exist but none makes a header row, the
1297 /// count is `0` and every row stays in the body under an empty header.
1298 pub fn header_row_count(&self) -> usize {
1299 let count = self.column_header_row_count();
1300 if count > 0 || self.rows.is_empty() {
1301 return count;
1302 }
1303 let derived;
1304 let cells: &[TableCell] = match &self.cells {
1305 Some(c) if !c.is_empty() => c,
1306 _ => {
1307 derived = self.derive_cells();
1308 &derived
1309 }
1310 };
1311 if cells
1312 .iter()
1313 .any(|c| c.column_header && c.start_row + c.row_span.max(1) > 1)
1314 {
1315 0
1316 } else {
1317 1
1318 }
1319 }
1320
1321 /// For every grid position, the position of the cell that covers it — its
1322 /// anchor (top-left start): itself for an unmerged position, the merge's
1323 /// start for one a spanning cell covers. Uses the first-class
1324 /// [`Self::cells`] when present, else the cells derived from the
1325 /// structure overlay. A rich cell's blocks ([`Self::cell_blocks`]) live on
1326 /// its anchor only, so a serializer that repeats a merged cell in every
1327 /// position it covers (docling-core#857) reads them through this.
1328 pub fn span_anchors(&self) -> Vec<Vec<(usize, usize)>> {
1329 let num_cols = self.rows.iter().map(Vec::len).max().unwrap_or(0);
1330 let mut anchors: Vec<Vec<(usize, usize)>> = (0..self.rows.len())
1331 .map(|r| (0..num_cols).map(|c| (r, c)).collect())
1332 .collect();
1333 let derived;
1334 let cells: &[TableCell] = match &self.cells {
1335 Some(c) if !c.is_empty() => c,
1336 _ => {
1337 derived = self.derive_cells();
1338 &derived
1339 }
1340 };
1341 for cell in cells {
1342 let rows = cell.start_row..cell.start_row + cell.row_span.max(1);
1343 for row in anchors.iter_mut().take(rows.end).skip(rows.start) {
1344 let cols = cell.start_col..cell.start_col + cell.col_span.max(1);
1345 for pos in row.iter_mut().take(cols.end).skip(cols.start) {
1346 *pos = (cell.start_row, cell.start_col);
1347 }
1348 }
1349 }
1350 anchors
1351 }
1352
1353 /// The first-class cell covering a grid position, if any.
1354 pub fn cell_at(&self, row: usize, col: usize) -> Option<&TableCell> {
1355 self.cells.as_ref()?.iter().find(|c| {
1356 (c.start_row..c.start_row + c.row_span).contains(&row)
1357 && (c.start_col..c.start_col + c.col_span).contains(&col)
1358 })
1359 }
1360
1361 /// A cell's bounding box (`[l, t, r, b]`, page points, top-left origin);
1362 /// `None` when no cell with geometry covers the position.
1363 pub fn cell_bbox(&self, row: usize, col: usize) -> Option<[f32; 4]> {
1364 self.cell_at(row, col)?.bbox
1365 }
1366
1367 /// Set (or replace) the bounding box of the cell covering a grid
1368 /// position; `false` outside the text grid. A table without first-class
1369 /// cells materializes them first (one 1×1 cell per grid position, texts
1370 /// from the grid), so declarative tables can be annotated too.
1371 pub fn set_cell_bbox(&mut self, row: usize, col: usize, bbox: [f32; 4]) -> bool {
1372 if self.rows.get(row).and_then(|r| r.get(col)).is_none() {
1373 return false;
1374 }
1375 let rows = &self.rows;
1376 let cells = self.cells.get_or_insert_with(|| {
1377 rows.iter()
1378 .enumerate()
1379 .flat_map(|(r, cols)| {
1380 cols.iter().enumerate().map(move |(c, text)| TableCell {
1381 text: text.clone(),
1382 bbox: None,
1383 start_row: r,
1384 start_col: c,
1385 row_span: 1,
1386 col_span: 1,
1387 column_header: false,
1388 row_header: false,
1389 row_section: false,
1390 })
1391 })
1392 .collect()
1393 });
1394 match cells.iter_mut().find(|c| {
1395 (c.start_row..c.start_row + c.row_span).contains(&row)
1396 && (c.start_col..c.start_col + c.col_span).contains(&col)
1397 }) {
1398 Some(cell) => {
1399 cell.bbox = Some(bbox);
1400 true
1401 }
1402 None => {
1403 cells.push(TableCell {
1404 text: self.rows[row][col].clone(),
1405 bbox: Some(bbox),
1406 start_row: row,
1407 start_col: col,
1408 row_span: 1,
1409 col_span: 1,
1410 column_header: false,
1411 row_header: false,
1412 row_section: false,
1413 });
1414 true
1415 }
1416 }
1417 }
1418
1419 /// The anchor position of the cell whose box overlaps `bbox` best
1420 /// (largest intersection-over-union), ties resolved in cell order.
1421 /// `None` when nothing overlaps or the table carries no geometry. This
1422 /// is the lookup half of the repair workflow: find the cell an external
1423 /// OCR box refers to, then [`Self::set_cell_text`] it.
1424 pub fn find_cell_by_bbox(&self, bbox: [f32; 4]) -> Option<(usize, usize)> {
1425 let area = |b: &[f32; 4]| ((b[2] - b[0]) * (b[3] - b[1])).max(0.0);
1426 let mut best: Option<(f32, (usize, usize))> = None;
1427 for cell in self.cells.as_deref()?.iter() {
1428 let Some(cb) = cell.bbox else { continue };
1429 let iw = (bbox[2].min(cb[2]) - bbox[0].max(cb[0])).max(0.0);
1430 let ih = (bbox[3].min(cb[3]) - bbox[1].max(cb[1])).max(0.0);
1431 let inter = iw * ih;
1432 if inter <= 0.0 {
1433 continue;
1434 }
1435 let iou = inter / (area(&bbox) + area(&cb) - inter).max(f32::EPSILON);
1436 if best.is_none_or(|(b, _)| iou > b) {
1437 best = Some((iou, (cell.start_row, cell.start_col)));
1438 }
1439 }
1440 best.map(|(_, pos)| pos)
1441 }
1442
1443 /// Locate the cell overlapping `bbox` best and replace its text — the
1444 /// one-call form of the OCR-repair loop. Returns the updated anchor.
1445 pub fn update_cell_by_bbox(
1446 &mut self,
1447 bbox: [f32; 4],
1448 text: impl Into<String>,
1449 ) -> Option<(usize, usize)> {
1450 let (row, col) = self.find_cell_by_bbox(bbox)?;
1451 self.set_cell_text(row, col, text);
1452 Some((row, col))
1453 }
1454}
1455
1456/// OTSL structure overlay for a [`Table`], parallel to [`Table::rows`].
1457#[derive(Debug, Clone, PartialEq, Default)]
1458pub struct TableStructure {
1459 /// Per-row: `true` if the row's non-empty cells are column headers
1460 /// (emitted as `<ched/>` rather than `<fcel/>`).
1461 pub header_row: Vec<bool>,
1462 /// Same shape as [`Table::rows`]; `true` where a cell continues a
1463 /// horizontal span from its left neighbour (emitted as `<lcel/>`).
1464 pub col_continuation: Vec<Vec<bool>>,
1465 /// Same shape as [`Table::rows`]; `true` where a cell continues a
1466 /// vertical span from the cell above (emitted as `<ucel/>`). Empty or all
1467 /// `false` when the backend has no vertical spans (e.g. USPTO CALS).
1468 pub row_continuation: Vec<Vec<bool>>,
1469 /// Same shape as [`Table::rows`]; `true` where a non-empty cell is a row
1470 /// header (emitted as `<rhed/>`) — a chart's category column. Empty when
1471 /// the table has no row headers.
1472 pub row_header: Vec<Vec<bool>>,
1473 /// Same shape as [`Table::rows`]; `true` where a cell is a *column header*
1474 /// cell (an HTML `<th>`). When non-empty this per-cell grid supersedes the
1475 /// per-row [`Self::header_row`] for `<ched/>` emission, matching docling's
1476 /// cell-level `column_header` flag; the chunker derives its header-row
1477 /// count from it.
1478 pub col_header: Vec<Vec<bool>>,
1479}
1480
1481/// [`for_each_picture_in_mut`], read-only: every picture in `nodes`, however
1482/// nested, for a pass that only looks (the DocLang asset digests, #898).
1483pub fn for_each_picture_in<'a>(nodes: &'a [Node], f: &mut dyn FnMut(&'a Node)) {
1484 for node in nodes {
1485 match node {
1486 Node::Picture { .. } => f(node),
1487 Node::Group { children, .. } | Node::PictureChildren(children) => {
1488 for_each_picture_in(children, f)
1489 }
1490 Node::Located { inner, .. }
1491 | Node::Prov { inner, .. }
1492 | Node::Track { inner, .. }
1493 | Node::Furniture { inner, .. }
1494 | Node::Commented { inner, .. }
1495 | Node::DoclangOnly(inner) => for_each_picture_in(std::slice::from_ref(inner), f),
1496 Node::Table(t) => {
1497 if let Some(blocks) = t.cell_blocks.as_ref() {
1498 for row in blocks {
1499 for cell in row {
1500 for_each_picture_in(cell, f);
1501 }
1502 }
1503 }
1504 }
1505 _ => {}
1506 }
1507 }
1508}
1509
1510/// [`DoclingDocument::for_each_picture_mut`] over a node slice — every
1511/// picture in `nodes`, however nested (groups, wrappers, table cell blocks),
1512/// for a caller that holds page batches rather than a document (the
1513/// streaming PDF path, #896).
1514pub fn for_each_picture_in_mut(nodes: &mut [Node], f: &mut dyn FnMut(&mut Node)) {
1515 for node in nodes {
1516 match node {
1517 Node::Picture { .. } => f(node),
1518 Node::Group { children, .. } | Node::PictureChildren(children) => {
1519 for_each_picture_in_mut(children, f)
1520 }
1521 Node::Located { inner, .. }
1522 | Node::Prov { inner, .. }
1523 | Node::Track { inner, .. }
1524 | Node::Furniture { inner, .. }
1525 | Node::Commented { inner, .. }
1526 | Node::DoclangOnly(inner) => for_each_picture_in_mut(std::slice::from_mut(inner), f),
1527 Node::Table(t) => {
1528 if let Some(blocks) = t.cell_blocks.as_mut() {
1529 for row in blocks {
1530 for cell in row {
1531 for_each_picture_in_mut(cell, f);
1532 }
1533 }
1534 }
1535 }
1536 _ => {}
1537 }
1538 }
1539}
1540
1541impl DoclingDocument {
1542 /// Create an empty document with the given name.
1543 pub fn new(name: impl Into<String>) -> Self {
1544 Self {
1545 name: name.into(),
1546 nodes: Vec::new(),
1547 strict_markdown: false,
1548 compact_tables: false,
1549 picture_alt_text: false,
1550 metadata: Default::default(),
1551 metadata_output: Default::default(),
1552 page_break_placeholder: None,
1553 links: Vec::new(),
1554 confidence: None,
1555 tree: None,
1556 page_images: std::collections::BTreeMap::new(),
1557 notices: Vec::new(),
1558 }
1559 }
1560
1561 /// Append a node.
1562 /// The document's top-level tables in reading order — the read half of
1563 /// the post-extraction table API (#238). [`Node::Located`] wrappers (the
1564 /// PDF pipeline attaches layout provenance that way) are looked through;
1565 /// tables nested inside rich table cells (`Table::cell_blocks`) are not
1566 /// traversed.
1567 pub fn tables(&self) -> impl Iterator<Item = &Table> {
1568 fn unwrap_table(n: &Node) -> Option<&Table> {
1569 match n {
1570 Node::Table(t) => Some(t),
1571 Node::Located { inner, .. }
1572 | Node::Prov { inner, .. }
1573 | Node::Track { inner, .. } => unwrap_table(inner),
1574 _ => None,
1575 }
1576 }
1577 self.nodes.iter().filter_map(unwrap_table)
1578 }
1579
1580 /// Mutable access to the document's top-level tables, for repair
1581 /// workflows (#238): locate a cell via [`Table::find_cell_by_bbox`], fix
1582 /// its text with [`Table::set_cell_text`], then re-export — every
1583 /// serializer reads the same grid.
1584 pub fn tables_mut(&mut self) -> impl Iterator<Item = &mut Table> {
1585 fn unwrap_table(n: &mut Node) -> Option<&mut Table> {
1586 match n {
1587 Node::Table(t) => Some(t),
1588 Node::Located { inner, .. }
1589 | Node::Prov { inner, .. }
1590 | Node::Track { inner, .. } => unwrap_table(inner),
1591 _ => None,
1592 }
1593 }
1594 self.nodes.iter_mut().filter_map(unwrap_table)
1595 }
1596
1597 pub fn push(&mut self, node: Node) {
1598 self.nodes.push(node);
1599 }
1600
1601 /// Visit every [`Node::Picture`] in the flat node stream, wherever it
1602 /// nests — group children, table cell blocks, a picture's own
1603 /// children, the located/prov/track/comment/furniture wrappers — so an
1604 /// enrichment that reads the embedded images (picture OCR, #645) reaches
1605 /// each one. The callback gets the picture node itself.
1606 pub fn for_each_picture_mut(&mut self, f: &mut dyn FnMut(&mut Node)) {
1607 for_each_picture_in_mut(&mut self.nodes, f);
1608 }
1609
1610 /// Change the unit the pages are measured in: every length in page units
1611 /// — each [`Node::PageInfo`] size, a [`Node::Prov`] box, a first-class
1612 /// table cell's box, a script run's box — is multiplied by `sx`
1613 /// horizontally and `sy` vertically, and every image's `dpi` (its pixels
1614 /// per inch *of the page unit*: a picture crop, a page image) is divided
1615 /// by `sx`, so the same pixels still cover the same part of the page. The
1616 /// 0–511 `<location>` grid is relative to the page and needs nothing. The
1617 /// image input sizes its page from the file's resolution this way once
1618 /// the models have run on its pixels (#1093).
1619 pub fn rescale_page_units(&mut self, sx: f32, sy: f32) {
1620 let scale_box = |b: &mut [f32; 4]| {
1621 b[0] *= sx;
1622 b[1] *= sy;
1623 b[2] *= sx;
1624 b[3] *= sy;
1625 };
1626 let scale_dpi = |img: &mut PictureImage| {
1627 img.dpi = (img.dpi as f32 / sx).round().max(1.0) as u32;
1628 };
1629 fn table(t: &mut Table, scale_box: &dyn Fn(&mut [f32; 4]), walk: &dyn Fn(&mut [Node])) {
1630 for cell in t.cells.iter_mut().flatten() {
1631 if let Some(b) = cell.bbox.as_mut() {
1632 scale_box(b);
1633 }
1634 }
1635 for row in t.cell_blocks.iter_mut().flatten() {
1636 for cell in row {
1637 walk(cell);
1638 }
1639 }
1640 }
1641 fn walk(
1642 nodes: &mut [Node],
1643 sx: f32,
1644 sy: f32,
1645 scale_box: &dyn Fn(&mut [f32; 4]),
1646 scale_dpi: &dyn Fn(&mut PictureImage),
1647 ) {
1648 let recurse = |n: &mut [Node]| walk(n, sx, sy, scale_box, scale_dpi);
1649 for node in nodes {
1650 match node {
1651 Node::PageInfo { width, height, .. } => {
1652 *width *= sx;
1653 *height *= sy;
1654 }
1655 Node::Prov { bbox, inner, .. } => {
1656 scale_box(bbox);
1657 recurse(std::slice::from_mut(inner));
1658 }
1659 Node::ScriptText { inner, runs } => {
1660 for run in runs {
1661 for prov in &mut run.prov {
1662 scale_box(&mut prov.bbox);
1663 }
1664 }
1665 recurse(std::slice::from_mut(inner));
1666 }
1667 Node::Located { inner, .. }
1668 | Node::Track { inner, .. }
1669 | Node::Furniture { inner, .. }
1670 | Node::Commented { inner, .. }
1671 | Node::DoclangOnly(inner) => recurse(std::slice::from_mut(inner)),
1672 Node::Group { children, .. } | Node::PictureChildren(children) => {
1673 recurse(children)
1674 }
1675 Node::Table(t) | Node::Chart { table: t, .. } => table(t, scale_box, &recurse),
1676 Node::Picture {
1677 image: Some(img), ..
1678 } => scale_dpi(img),
1679 _ => {}
1680 }
1681 }
1682 }
1683 walk(&mut self.nodes, sx, sy, &scale_box, &scale_dpi);
1684 for img in self.page_images.values_mut() {
1685 scale_dpi(img);
1686 }
1687 }
1688
1689 /// Convenience: append a heading.
1690 pub fn add_heading(&mut self, level: u8, text: impl Into<String>) {
1691 self.push(Node::Heading {
1692 level,
1693 text: text.into(),
1694 });
1695 }
1696
1697 /// Convenience: append a paragraph.
1698 pub fn add_paragraph(&mut self, text: impl Into<String>) {
1699 self.push(Node::Paragraph { text: text.into() });
1700 }
1701
1702 /// Serialize the document to Markdown.
1703 ///
1704 /// The Rust equivalent of docling-core's
1705 /// `DoclingDocument.export_to_markdown()`. Uses [`Self::strict_markdown`] to
1706 /// pick between docling-legacy output (default) and the cleaner, more
1707 /// conformant variant.
1708 pub fn export_to_markdown(&self) -> String {
1709 to_markdown(self, self.strict_markdown)
1710 }
1711
1712 /// Serialize to Markdown, explicitly choosing the mode regardless of
1713 /// [`Self::strict_markdown`]. `strict = true` produces cleaner, more
1714 /// conformant Markdown (code-fence languages preserved, no inline-run
1715 /// spacing artifacts); `strict = false` reproduces docling's legacy output.
1716 pub fn export_to_markdown_with(&self, strict: bool) -> String {
1717 to_markdown(self, strict)
1718 }
1719
1720 /// Markdown for this document as the *content of a rich table cell*
1721 /// (docling-core's `in_table_cell` serialization, docling-core#540):
1722 /// headings render as plain text since Markdown tables can't hold them.
1723 /// Backends build a sub-document per rich cell and flatten this into the
1724 /// cell text; no trailing newline.
1725 pub fn export_to_table_cell_markdown(&self) -> String {
1726 crate::markdown::to_markdown_table_cell(self, self.strict_markdown)
1727 }
1728
1729 /// Serialize to docling-core's native JSON wire format (`DoclingDocument`
1730 /// schema), pretty-printed — the Rust equivalent of
1731 /// `DoclingDocument.export_to_dict()` / `save_as_json()`. The output loads
1732 /// back into Python docling-core and round-trips to the same Markdown.
1733 pub fn export_to_json(&self) -> String {
1734 let mut out = Vec::new();
1735 self.write_json_pretty(&mut out)
1736 .expect("DoclingDocument JSON is always serializable");
1737 String::from_utf8(out).expect("serde_json writes UTF-8")
1738 }
1739
1740 /// The same JSON wire format as [`Self::export_to_json`], as a
1741 /// `serde_json::Value` — for callers that append response-level extras
1742 /// (docling-serve adds the confidence report, #183) before serializing.
1743 ///
1744 /// The `Value` is large — ~2.7 KB per text item — so on a long document
1745 /// prefer [`Self::write_json`], which writes the same JSON without it.
1746 pub fn export_to_json_value(&self) -> serde_json::Value {
1747 crate::json::to_json(self)
1748 }
1749
1750 /// Write the JSON of [`Self::export_to_json_value`] to `writer`, compact
1751 /// — byte for byte `serde_json::to_writer(writer, &doc.export_to_json_value())`
1752 /// — without building the `Value`: the export holds its text items in a
1753 /// compact form and serializes them straight to the writer. Wrap a file
1754 /// or socket in a `BufWriter`.
1755 pub fn write_json<W: std::io::Write>(&self, writer: W) -> std::io::Result<()> {
1756 crate::json::write_json(self, writer, false).map_err(std::io::Error::from)
1757 }
1758
1759 /// [`Self::write_json`], indented as [`Self::export_to_json`] is.
1760 pub fn write_json_pretty<W: std::io::Write>(&self, writer: W) -> std::io::Result<()> {
1761 crate::json::write_json(self, writer, true).map_err(std::io::Error::from)
1762 }
1763
1764 /// [`Self::write_json_pretty`] with `extras` appended to the top-level
1765 /// object after `pages` — byte for byte `serde_json::to_writer_pretty`
1766 /// of [`Self::export_to_json_value`] with each `value[key] = v` set (a
1767 /// key the document JSON does not have), without building that `Value`:
1768 /// docling-serve's response adds its `confidence` report this way.
1769 pub fn write_json_pretty_with<W: std::io::Write>(
1770 &self,
1771 writer: W,
1772 extras: &[(&str, &serde_json::Value)],
1773 ) -> std::io::Result<()> {
1774 crate::json::write_json_with(self, writer, true, extras).map_err(std::io::Error::from)
1775 }
1776
1777 /// Serialize to a complete LaTeX document — the Rust counterpart of
1778 /// docling-core's `LaTeXDocSerializer` with default parameters (docling
1779 /// 2.124's `--to latex`, #317). No trailing newline, like the upstream
1780 /// CLI's `<stem>.tex`.
1781 pub fn export_to_latex(&self) -> String {
1782 crate::latex::to_latex(self)
1783 }
1784
1785 /// Serialize to Pandoc's AST as JSON (`pandoc -f json`, #515) with the
1786 /// default options: pictures as captioned figures without image data,
1787 /// body layer only, the [`PANDOC_API_VERSION`](crate::pandoc::PANDOC_API_VERSION)
1788 /// API. One line, no trailing newline. See [`crate::pandoc`].
1789 pub fn export_to_pandoc_json(&self) -> String {
1790 crate::pandoc::to_pandoc(self, &crate::pandoc::PandocExportOptions::default())
1791 .expect("the default Pandoc API version is always supported")
1792 .0
1793 }
1794
1795 /// Pandoc JSON per `options` (image mode, artifacts directory, content
1796 /// layers, required API version). Returns the JSON and, for
1797 /// [`ImageMode::Referenced`], the `(path, bytes)` image files; an
1798 /// unsupported `api_version` is an error.
1799 pub fn export_to_pandoc_json_with(
1800 &self,
1801 options: &crate::pandoc::PandocExportOptions,
1802 ) -> Result<crate::pandoc::PandocOutput, crate::pandoc::PandocError> {
1803 crate::pandoc::to_pandoc(self, options)
1804 }
1805
1806 /// Serialize to DocLang XML (`<doclang version="0.7">…`), the markup that
1807 /// lives inside a `.dclx` archive — the Rust counterpart of docling-core's
1808 /// `export_to_doclang()` with default parameters. No trailing newline; the
1809 /// archive writer appends exactly one.
1810 pub fn export_to_doclang(&self) -> String {
1811 self.export_doclang(crate::doclang::Pictures::Referenced { collect: false })
1812 .0
1813 }
1814
1815 /// [`Self::export_to_doclang`] plus the picture assets its
1816 /// `<src uri="assets/image_….png"/>` references name, as `(path, bytes)`
1817 /// in document order — the parts docling's `save_as_doclang_archive`
1818 /// stores next to `document.xml`. PNG and JPEG pictures come back as PNG
1819 /// (a JPEG re-encoded from its libjpeg-decoded pixels); other encodings
1820 /// keep their own bytes for the archive writer to convert.
1821 pub fn export_to_doclang_with_assets(&self) -> (String, Vec<(String, Vec<u8>)>) {
1822 self.export_doclang(crate::doclang::Pictures::Referenced { collect: true })
1823 }
1824
1825 /// DocLang with docling's `image_mode` for pictures (#884):
1826 /// [`ImageMode::Placeholder`] writes no `<src>` — docling-core's own
1827 /// `export_to_doclang()` default, which upstream's `.dclg` fixtures hold
1828 /// — [`ImageMode::Embedded`] a `data:` URI of the PNG,
1829 /// [`ImageMode::Referenced`] is [`Self::export_to_doclang_with_assets`].
1830 pub fn export_to_doclang_with_images(
1831 &self,
1832 mode: ImageMode,
1833 ) -> (String, Vec<(String, Vec<u8>)>) {
1834 use crate::doclang::Pictures;
1835 self.export_doclang(match mode {
1836 ImageMode::Placeholder => Pictures::Placeholder,
1837 ImageMode::Embedded => Pictures::Embedded,
1838 ImageMode::Referenced => Pictures::Referenced { collect: true },
1839 })
1840 }
1841
1842 /// The item tree's DocLang — docling-core's `DocLangDocSerializer`
1843 /// ported over the tree (`doclang_tree.rs`, #884), the structure the
1844 /// JSON export writes — else (no tree, or one the port does not cover:
1845 /// provenance, picture meta, form fields) the nodes'. The flat nodes
1846 /// cannot carry a footnote's label, a caption's or a cell's inline
1847 /// formulas, text docling never wrote as Markdown, or the whitespace of
1848 /// an inline group's runs, which DocLang 0.9 reads as written.
1849 fn export_doclang(
1850 &self,
1851 pictures: crate::doclang::Pictures,
1852 ) -> (String, Vec<(String, Vec<u8>)>) {
1853 self.tree
1854 .as_ref()
1855 .filter(|t| !t.doclang_nodes)
1856 .and_then(|t| crate::doclang_tree::export(t, pictures))
1857 .unwrap_or_else(|| crate::doclang::render(&self.nodes, pictures))
1858 }
1859
1860 /// Serialize to Markdown with an explicit picture [`ImageMode`] (mirrors
1861 /// docling's `image_mode`). Returns the Markdown and, for
1862 /// [`ImageMode::Referenced`], the `(relative-path, bytes)` of each image the
1863 /// caller should write next to the Markdown file. `artifacts_dir` is the
1864 /// directory name used in referenced links.
1865 pub fn export_to_markdown_with_images(
1866 &self,
1867 image_mode: ImageMode,
1868 artifacts_dir: &str,
1869 ) -> (String, Vec<(String, Vec<u8>)>) {
1870 to_markdown_images(self, self.strict_markdown, image_mode, artifacts_dir)
1871 }
1872
1873 /// Markdown per `options` (#599) — docling-core's
1874 /// `export_to_markdown(included_content_layers=…, image_mode=…,
1875 /// image_placeholder=…, escape_html=…, escape_underscores=…,
1876 /// traverse_pictures=…)`: the content layers rendered, whether a
1877 /// picture's nested text items print, HTML and underscore escaping, the
1878 /// image placeholder, and the image mode with its referenced-image
1879 /// directory. [`Self::strict_markdown`] still picks the Markdown flavour.
1880 /// Returns the Markdown and, for [`ImageMode::Referenced`], the
1881 /// `(path, bytes)` artifacts. With [`MarkdownExportOptions::default`]
1882 /// the Markdown is [`Self::export_to_markdown`]'s byte for byte.
1883 pub fn export_to_markdown_with_options(
1884 &self,
1885 options: &MarkdownExportOptions,
1886 ) -> (String, Vec<(String, Vec<u8>)>) {
1887 crate::markdown::to_markdown_with_options(self, self.strict_markdown, options)
1888 }
1889
1890 /// WebVTT (#614) — what docling's `--to vtt` writes
1891 /// (`DoclingDocument.save_as_vtt`): a cue per timed text item — a WebVTT
1892 /// input's cues, an audio/video transcript's segments — hours always
1893 /// written, the `</v>` of a lone voice span omitted. A document without
1894 /// timed text is the bare `WEBVTT` header. No trailing newline.
1895 pub fn export_to_vtt(&self) -> String {
1896 crate::vtt::to_vtt(self, &crate::vtt::VttExportOptions::default())
1897 }
1898
1899 /// [`Self::export_to_vtt`] with docling-core's `WebVTTParams`
1900 /// (`omit_hours_if_zero`, `omit_voice_end`).
1901 pub fn export_to_vtt_with_options(&self, options: &crate::vtt::VttExportOptions) -> String {
1902 crate::vtt::to_vtt(self, options)
1903 }
1904
1905 /// Plain text — docling-core's `DoclingDocument.export_to_text()` with
1906 /// its defaults (#613, docling's `--to text` / `<stem>.txt`): the
1907 /// Markdown export without decoration ([`MarkdownExportOptions::plain_text`]).
1908 /// Lists keep their bullets and numbers, tables their `|` grid. No
1909 /// trailing newline: upstream's `serialize().text`, which its CLI
1910 /// writes verbatim to `<stem>.txt`.
1911 pub fn export_to_text(&self) -> String {
1912 let (mut text, _) = crate::markdown::to_markdown_with_options(
1913 self,
1914 self.strict_markdown,
1915 &MarkdownExportOptions::plain_text(),
1916 );
1917 if text.ends_with('\n') {
1918 text.pop();
1919 }
1920 text
1921 }
1922
1923 /// A complete HTML document — docling-core's `HTMLDocSerializer` with its
1924 /// defaults (#492): pictures stay out (`ImageRefMode.PLACEHOLDER`, only
1925 /// their captions and meta render). See [`export_to_html_with_images`]
1926 /// for the embedded / referenced modes and [`crate::html`]'s module docs
1927 /// for what is reproduced.
1928 ///
1929 /// [`export_to_html_with_images`]: Self::export_to_html_with_images
1930 pub fn export_to_html(&self) -> String {
1931 crate::html::to_html(self, &HtmlExportOptions::default()).0
1932 }
1933
1934 /// HTML with pictures per `image_mode`: `data:` URIs when embedded, and
1935 /// when referenced `<img src>` paths under `artifacts_dir` whose bytes come
1936 /// back as `(path, bytes)` for the caller to write — the Markdown export's
1937 /// contract and file names.
1938 pub fn export_to_html_with_images(
1939 &self,
1940 image_mode: ImageMode,
1941 artifacts_dir: &str,
1942 ) -> (String, Vec<(String, Vec<u8>)>) {
1943 crate::html::to_html(
1944 self,
1945 &HtmlExportOptions {
1946 image_mode,
1947 artifacts_dir: artifacts_dir.to_string(),
1948 ..HtmlExportOptions::default()
1949 },
1950 )
1951 }
1952
1953 /// HTML rendering the content `layers` — docling-core's
1954 /// `export_to_html(included_content_layers=…)` (#499). The default export
1955 /// is body only; `ContentLayers::BODY.with(ContentLayer::Furniture)` adds
1956 /// page headers/footers, `.with(ContentLayer::Notes)` reviewer comments,
1957 /// [`ContentLayers::ALL`] is Python's `set(ContentLayer)`. An item on a
1958 /// layer outside the set is skipped while its children are still walked,
1959 /// and the items that do render go through the same serializers as the
1960 /// body (a page header is a `<p>`, a comment a `<p>`, a header table a
1961 /// `<table>`), exactly as upstream's `HTMLParams.layers` behaves. Pictures
1962 /// stay placeholders; see [`export_to_html_with`] for the full option set.
1963 ///
1964 /// [`export_to_html_with`]: Self::export_to_html_with
1965 pub fn export_to_html_with_layers(&self, layers: ContentLayers) -> String {
1966 crate::html::to_html(
1967 self,
1968 &HtmlExportOptions {
1969 layers,
1970 ..HtmlExportOptions::default()
1971 },
1972 )
1973 .0
1974 }
1975
1976 /// HTML per `options` — image mode, referenced-image directory and content
1977 /// layers in one call; the other `export_to_html*` methods are
1978 /// shorthands for it. Returns the HTML and, for
1979 /// [`ImageMode::Referenced`], the `(path, bytes)` artifacts.
1980 pub fn export_to_html_with(
1981 &self,
1982 options: &HtmlExportOptions,
1983 ) -> (String, Vec<(String, Vec<u8>)>) {
1984 crate::html::to_html(self, options)
1985 }
1986}
1987
1988#[cfg(test)]
1989mod table_api_tests {
1990 use super::*;
1991
1992 fn cell(
1993 text: &str,
1994 bbox: [f32; 4],
1995 (start_row, start_col): (usize, usize),
1996 (row_span, col_span): (usize, usize),
1997 ) -> TableCell {
1998 TableCell {
1999 text: text.into(),
2000 bbox: Some(bbox),
2001 start_row,
2002 start_col,
2003 row_span,
2004 col_span,
2005 column_header: false,
2006 row_header: false,
2007 row_section: false,
2008 }
2009 }
2010
2011 fn table() -> Table {
2012 Table {
2013 rows: vec![
2014 vec!["Year".into(), "Ducks".into()],
2015 vec!["2019".into(), "120".into()],
2016 ],
2017 cells: Some(vec![
2018 cell("Year", [0.0, 0.0, 50.0, 10.0], (0, 0), (1, 1)),
2019 cell("Ducks", [50.0, 0.0, 100.0, 10.0], (0, 1), (1, 1)),
2020 cell("2019", [0.0, 10.0, 50.0, 20.0], (1, 0), (1, 1)),
2021 cell("120", [50.0, 10.0, 100.0, 20.0], (1, 1), (1, 1)),
2022 ]),
2023 ..Default::default()
2024 }
2025 }
2026
2027 /// Declarative tables derive first-class cells from the structure
2028 /// overlay: continuation grids become span extents, `col_header` (or the
2029 /// row-0 fallback) becomes the header role — the XLSX/DOCX/HTML merge
2030 /// path into real `TableCell`s (#240).
2031 #[test]
2032 fn derive_cells_reads_spans_and_headers_from_structure() {
2033 let t = Table {
2034 rows: vec![
2035 vec!["Wide".into(), "Wide".into(), "C".into()],
2036 vec!["a".into(), "b".into(), "c".into()],
2037 ],
2038 structure: Some(TableStructure {
2039 header_row: vec![true, false],
2040 col_continuation: vec![vec![false, true, false], vec![false; 3]],
2041 row_continuation: vec![vec![false; 3], vec![false; 3]],
2042 row_header: Vec::new(),
2043 col_header: Vec::new(),
2044 }),
2045 ..Default::default()
2046 };
2047 let cells = t.derive_cells();
2048 assert_eq!(cells.len(), 5, "two anchors in row 0, three in row 1");
2049 let wide = &cells[0];
2050 assert_eq!((wide.col_span, wide.row_span), (2, 1));
2051 assert!(wide.column_header, "header_row band");
2052 assert!(cells.iter().skip(2).all(|c| !c.column_header));
2053
2054 // Without any overlay: every position 1x1, row 0 the header
2055 // (docling's declarative default — the old JSON synthesis).
2056 let plain = Table {
2057 rows: vec![vec!["h".into()], vec!["x".into()]],
2058 ..Default::default()
2059 };
2060 let cells = plain.derive_cells();
2061 assert_eq!(cells.len(), 2);
2062 assert!(cells[0].column_header && !cells[1].column_header);
2063 }
2064
2065 /// A spanning cell updates once: the record text and every covered grid
2066 /// position — a repair shows once in Markdown, not once per column.
2067 #[test]
2068 fn span_repair_updates_the_whole_cell() {
2069 let mut t = Table {
2070 rows: vec![
2071 vec!["Wide".into(), "Wide".into(), "C".into()],
2072 vec!["a".into(), "b".into(), "c".into()],
2073 ],
2074 cells: Some(vec![
2075 cell("Wide", [0.0, 0.0, 100.0, 10.0], (0, 0), (1, 2)),
2076 cell("C", [100.0, 0.0, 150.0, 10.0], (0, 2), (1, 1)),
2077 ]),
2078 ..Default::default()
2079 };
2080 // Update through the covered (non-anchor) position.
2081 assert!(t.set_cell_text(0, 1, "Fixed"));
2082 assert_eq!(
2083 t.rows[0],
2084 vec!["Fixed".to_string(), "Fixed".into(), "C".into()]
2085 );
2086 assert_eq!(t.cell_at(0, 1).unwrap().text, "Fixed");
2087 assert_eq!(t.cell_at(0, 1).unwrap().col_span, 2);
2088 }
2089
2090 /// The OCR-repair loop (#238): locate a cell by an external box (best
2091 /// IoU), replace its text, and see the fix in the export — the grid is
2092 /// the single source of truth for every serializer.
2093 #[test]
2094 fn bbox_lookup_and_repair_flow_into_exports() {
2095 let mut doc = DoclingDocument::new("t");
2096 doc.push(Node::Table(table()));
2097 assert_eq!(doc.tables().count(), 1);
2098
2099 let t = doc.tables_mut().next().unwrap();
2100 // A slightly-off OCR box still lands on the (1,1) cell.
2101 assert_eq!(t.find_cell_by_bbox([52.0, 11.0, 98.0, 19.0]), Some((1, 1)));
2102 assert_eq!(
2103 t.update_cell_by_bbox([52.0, 11.0, 98.0, 19.0], "125"),
2104 Some((1, 1))
2105 );
2106 assert_eq!(t.cell_text(1, 1), Some("125"));
2107 assert!(doc.export_to_markdown().contains("125"));
2108
2109 // No overlap → no match, nothing changed.
2110 let t = doc.tables_mut().next().unwrap();
2111 assert_eq!(t.find_cell_by_bbox([500.0, 500.0, 600.0, 600.0]), None);
2112 }
2113
2114 #[test]
2115 fn cell_accessors_bound_check_and_geometry_materializes() {
2116 let mut t = table();
2117 assert_eq!(t.cell_text(0, 0), Some("Year"));
2118 assert_eq!(t.cell_text(5, 0), None);
2119 assert!(!t.set_cell_text(0, 9, "x"), "outside the grid");
2120 assert_eq!(t.cell_bbox(1, 0), Some([0.0, 10.0, 50.0, 20.0]));
2121
2122 // A geometry-less table materializes its box grid on first set.
2123 let mut plain = Table {
2124 rows: vec![vec!["a".into(), "b".into()]],
2125 ..Default::default()
2126 };
2127 assert_eq!(plain.cell_bbox(0, 1), None);
2128 assert!(!plain.set_cell_bbox(0, 5, [0.0; 4]), "outside the grid");
2129 assert!(plain.set_cell_bbox(0, 1, [1.0, 2.0, 3.0, 4.0]));
2130 assert_eq!(plain.cell_bbox(0, 1), Some([1.0, 2.0, 3.0, 4.0]));
2131 assert_eq!(plain.find_cell_by_bbox([1.5, 2.5, 2.5, 3.5]), Some((0, 1)));
2132 }
2133}
2134
2135#[cfg(test)]
2136mod rescale_tests {
2137 use super::*;
2138
2139 fn image(dpi: u32) -> PictureImage {
2140 PictureImage {
2141 mimetype: "image/png".into(),
2142 width: 300,
2143 height: 150,
2144 data: Vec::new(),
2145 dpi,
2146 display_size: None,
2147 }
2148 }
2149
2150 /// #1093: a page measured in pixels re-measured in points — the page size,
2151 /// a table cell's box and a script run's box scale per axis, an image's
2152 /// pixels per inch of the page grow by the inverse, and the 0–511
2153 /// locations, relative to the page, stay.
2154 #[test]
2155 fn a_page_unit_change_scales_lengths_and_resolutions() {
2156 let table = Table {
2157 rows: vec![vec!["a".into()]],
2158 location: Some([10, 20, 30, 40]),
2159 cells: Some(vec![TableCell {
2160 text: "a".into(),
2161 bbox: Some([100.0, 200.0, 300.0, 400.0]),
2162 start_row: 0,
2163 start_col: 0,
2164 row_span: 1,
2165 col_span: 1,
2166 column_header: false,
2167 row_header: false,
2168 row_section: false,
2169 }]),
2170 ..Table::default()
2171 };
2172 let mut doc = DoclingDocument::new("scan");
2173 doc.push(Node::PageInfo {
2174 page_no: 1,
2175 width: 1000.0,
2176 height: 2000.0,
2177 });
2178 doc.push(Node::Located {
2179 location: [1, 2, 3, 4],
2180 inner: Box::new(Node::Table(table)),
2181 });
2182 doc.push(Node::Group {
2183 label: "group".into(),
2184 name: None,
2185 layer: None,
2186 children: vec![Node::Picture {
2187 caption: None,
2188 caption_href: None,
2189 image: Some(image(72)),
2190 classification: None,
2191 description: None,
2192 caption_parent: Default::default(),
2193 caption_location: None,
2194 }],
2195 });
2196 doc.page_images.insert(1, image(144));
2197
2198 doc.rescale_page_units(0.24, 0.5);
2199
2200 assert!(matches!(
2201 doc.nodes[0],
2202 Node::PageInfo { width, height, .. } if width == 240.0 && height == 1000.0
2203 ));
2204 let Node::Located { location, inner } = &doc.nodes[1] else {
2205 panic!("located table")
2206 };
2207 assert_eq!(*location, [1, 2, 3, 4]);
2208 let Node::Table(t) = inner.as_ref() else {
2209 panic!("table")
2210 };
2211 assert_eq!(t.location, Some([10, 20, 30, 40]));
2212 assert_eq!(
2213 t.cells.as_ref().unwrap()[0].bbox,
2214 Some([24.0, 100.0, 72.0, 200.0])
2215 );
2216 let Node::Group { children, .. } = &doc.nodes[2] else {
2217 panic!("group")
2218 };
2219 assert!(matches!(&children[0], Node::Picture { image: Some(i), .. } if i.dpi == 300));
2220 assert_eq!(doc.page_images[&1].dpi, 600);
2221 }
2222}