docling 2.85.0

DocumentConverter and format backends for docling.rs (a Rust port of docling).
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
//! A PPTX chart part read the way docling's PowerPoint backend reads it
//! through python-pptx (docling#4773, 2.139): every plot of a combination
//! chart, not just the first.
//!
//! - **Plots**: the plot area's chart elements in document order — every one
//!   of them since docling#4811: a 3-D bar/line/pie, stock, surface or
//!   bar-of-pie plot, which python-pptx has no plot class for, was skipped
//!   as `other_chart` without data; every `c:ser` has the same structure, so
//!   all are read alike now.
//! - **Classification**: one label per plot, by its tag (`bar3DChart` is a
//!   bar chart — the Word and Excel backends' mapping), in drawing order
//!   (the back-most plot first, so it stays the main prediction), each label
//!   once.
//! - **Data table**: the series of every plot as columns, in drawing order
//!   and each plot's `c:order` (a series without one is malformed: the chart
//!   keeps its labels and loses its table, as a value that is not a number
//!   does). The categories come from the first plot that has them, read
//!   from its first series; on a date axis, or a text axis showing a date
//!   number format, the cached serials read as ISO 8601 dates (1900 or 1904
//!   system). That plot's category axis title heads the category column.
//! - **Title**: `c:chart/c:title`'s rich text only — an axis title is not the
//!   chart's.
//!
//! The XLSX and DOCX backends keep their own chart readers
//! ([`super::xlsx_drawings`]): their upstream counterparts did not change.

use roxmltree::{Document, Node as XmlNode};

use super::numfmt::{civil_from_days, days_from_civil};
use super::xlsx_drawings::build_chart_table;

/// A PPTX chart as docling records it on the picture.
pub struct PptxChart {
    /// The classification labels, main first (never empty).
    pub labels: Vec<&'static str>,
    /// The chart title, the picture's caption.
    pub title: Option<String>,
    /// The data grid; `None` when no readable plot has a series or no row
    /// carries data.
    pub table: Option<docling_core::Table>,
}

/// The plot elements python-pptx lists (`CT_PlotArea.iter_xCharts`).
const PLOT_TAGS: [&str; 16] = [
    "area3DChart",
    "areaChart",
    "bar3DChart",
    "barChart",
    "bubbleChart",
    "doughnutChart",
    "line3DChart",
    "lineChart",
    "ofPieChart",
    "pie3DChart",
    "pieChart",
    "radarChart",
    "scatterChart",
    "stockChart",
    "surface3DChart",
    "surfaceChart",
];

/// docling's `_CHART_TAGNAME_TO_CLASSIFICATION` (docling#4811): a plot's
/// label by its tag; every other plot is `other_chart`.
fn plot_label(tag: &str) -> &'static str {
    match tag {
        "barChart" | "bar3DChart" => "bar_chart",
        "lineChart" | "line3DChart" => "line_chart",
        "pieChart" | "pie3DChart" | "doughnutChart" => "pie_chart",
        "scatterChart" => "scatter_chart",
        _ => "other_chart",
    }
}

/// `_XY_PLOT_TAGNAMES`: plots whose series keep their values in `c:yVal`.
fn is_xy_plot(tag: &str) -> bool {
    matches!(tag, "scatterChart" | "bubbleChart")
}

fn child<'a, 'i>(node: XmlNode<'a, 'i>, tag: &str) -> Option<XmlNode<'a, 'i>> {
    node.children().find(|c| c.has_tag_name(tag))
}

/// Parse a chart part; `None` when it is not a chart (no plot area).
pub fn parse(xml: &str) -> Option<PptxChart> {
    let dom = Document::parse(xml).ok()?;
    let chart = child(dom.root_element(), "chart")?;
    let plot_area = child(chart, "plotArea")?;
    let date1904 = child(dom.root_element(), "date1904")
        .and_then(|d| d.attribute("val"))
        .is_some_and(|v| matches!(v, "1" | "true"));
    let plots: Vec<XmlNode> = plot_area
        .children()
        .filter(|c| c.is_element() && PLOT_TAGS.contains(&c.tag_name().name()))
        .collect();

    let mut labels: Vec<&'static str> = Vec::new();
    for plot in &plots {
        let label = plot_label(plot.tag_name().name());
        if !labels.contains(&label) {
            labels.push(label);
        }
    }
    if labels.is_empty() {
        labels.push("other_chart");
    }

    Some(PptxChart {
        labels,
        title: child(chart, "title").and_then(chart_title),
        table: chart_data(plot_area, &plots, date1904),
    })
}

/// python-pptx's `chart_title.text_frame.text`, stripped: the rich text's
/// paragraphs joined with newlines (a line break is `\v`).
fn chart_title(title: XmlNode) -> Option<String> {
    let rich = child(title, "tx").and_then(|tx| child(tx, "rich"))?;
    let text = rich
        .children()
        .filter(|p| p.has_tag_name("p"))
        .map(|p| {
            let mut s = String::new();
            for el in p.children().filter(XmlNode::is_element) {
                match el.tag_name().name() {
                    "r" | "fld" => {
                        if let Some(t) = child(el, "t") {
                            s.push_str(t.text().unwrap_or(""));
                        }
                    }
                    "br" => s.push('\u{b}'),
                    _ => {}
                }
            }
            s
        })
        .collect::<Vec<_>>()
        .join("\n");
    let text = text.trim();
    (!text.is_empty()).then(|| text.to_string())
}

/// docling's `_chart_to_table_data`.
fn chart_data(
    plot_area: XmlNode,
    plots: &[XmlNode],
    date1904: bool,
) -> Option<docling_core::Table> {
    let mut categories: Vec<String> = Vec::new();
    let mut corner = String::new();
    let mut columns: Vec<(String, Vec<String>)> = Vec::new();
    for &plot in plots {
        if categories.is_empty() {
            let axis = category_axis(plot_area, plot);
            categories = category_labels(plot, axis, date1904);
            corner = axis.map(axis_title).unwrap_or_default();
        }
        // `_plot_series`: sorted by `c:order`, whose absence python-pptx
        // rejects as invalid XML — the table is dropped.
        let mut sers: Vec<(i64, XmlNode)> = Vec::new();
        for ser in plot.children().filter(|c| c.has_tag_name("ser")) {
            let order = child(ser, "order")
                .and_then(|o| o.attribute("val"))
                .and_then(|v| v.parse::<i64>().ok())?;
            sers.push((order, ser));
        }
        sers.sort_by_key(|(order, _)| *order);
        let xy = is_xy_plot(plot.tag_name().name());
        for (_, ser) in sers {
            let name = ser
                .children()
                .filter(|c| c.has_tag_name("tx"))
                .flat_map(|tx| tx.descendants())
                .find(|n| n.has_tag_name("pt"))
                .and_then(|pt| child(pt, "v"))
                .and_then(|v| v.text())
                .unwrap_or("")
                .to_string();
            // A value that is not a number fails python-pptx's `float()`,
            // and docling then drops the whole table.
            columns.push((name, series_values(ser, xy)?));
        }
    }
    if columns.is_empty() {
        return None;
    }
    build_chart_table(categories, columns, corner)
}

/// A series' values as python-pptx reads them (`c:val`; an xy plot's
/// `c:yVal`): one per point of the cache's `c:ptCount`, empty where a point
/// is missing, integer-valued numbers without `.0` (docling's `_cell_text`).
/// `None` when a point is not a number.
fn series_values(ser: XmlNode, xy: bool) -> Option<Vec<String>> {
    let Some(val) = child(ser, if xy { "yVal" } else { "val" }) else {
        return Some(Vec::new());
    };
    let count = val
        .descendants()
        .find(|n| n.has_tag_name("ptCount"))
        .and_then(|n| n.attribute("val"))
        .and_then(|v| v.parse::<usize>().ok())
        .unwrap_or(0);
    let mut values = vec![String::new(); count];
    for pt in val.descendants().filter(|n| n.has_tag_name("pt")) {
        let Some(idx) = pt.attribute("idx").and_then(|i| i.parse::<usize>().ok()) else {
            continue;
        };
        if idx >= count {
            continue;
        }
        let text = child(pt, "v").and_then(|v| v.text()).unwrap_or("");
        let value: f64 = text.trim().parse().ok()?;
        values[idx] = python_number(value);
    }
    Some(values)
}

/// A float as docling's `_cell_text` writes it: an integer value without
/// `.0`, anything else as Python's `str(float)`.
fn python_number(v: f64) -> String {
    if v.is_nan() {
        return "nan".into();
    }
    if v.is_infinite() {
        return if v > 0.0 { "inf" } else { "-inf" }.into();
    }
    if v.fract() == 0.0 {
        return if v == 0.0 {
            "0".into()
        } else {
            format!("{v:.0}")
        };
    }
    // Python's repr switches to scientific notation below 1e-4 (and from
    // 1e16, where every float is an integer), with a signed two-digit
    // exponent.
    let sci = format!("{v:e}");
    let (mantissa, exp) = sci.split_once('e').unwrap_or((&sci, "0"));
    let exp: i32 = exp.parse().unwrap_or(0);
    if exp < -4 {
        let sign = if exp < 0 { '-' } else { '+' };
        format!("{mantissa}e{sign}{:02}", exp.abs())
    } else {
        format!("{v}")
    }
}

/// The `c:catAx`/`c:dateAx` a plot is drawn against, matched by `c:axId`
/// (docling's `_category_axis`); `None` for a plot without one (pie, xy).
fn category_axis<'a, 'i>(plot_area: XmlNode<'a, 'i>, plot: XmlNode) -> Option<XmlNode<'a, 'i>> {
    let ids: Vec<&str> = plot
        .children()
        .filter(|c| c.has_tag_name("axId"))
        .filter_map(|c| c.attribute("val"))
        .collect();
    plot_area.children().find(|axis| {
        (axis.has_tag_name("catAx") || axis.has_tag_name("dateAx"))
            && axis
                .children()
                .filter(|c| c.has_tag_name("axId"))
                .filter_map(|c| c.attribute("val"))
                .any(|id| ids.contains(&id))
    })
}

/// A plot's category labels (python-pptx's `plot.categories`: the first
/// series' `c:cat` points, first level only, padded to the cached count),
/// with dates as ISO 8601 when its axis shows dates.
fn category_labels(plot: XmlNode, axis: Option<XmlNode>, date1904: bool) -> Vec<String> {
    let first_cat = plot
        .children()
        .find(|c| c.has_tag_name("ser"))
        .and_then(|ser| child(ser, "cat"));
    let count = plot
        .children()
        .filter(|c| c.has_tag_name("ser"))
        .filter_map(|ser| child(ser, "cat"))
        .flat_map(|cat| cat.descendants())
        .find(|n| n.has_tag_name("ptCount"))
        .and_then(|n| n.attribute("val"))
        .and_then(|v| v.parse::<usize>().ok())
        .unwrap_or(0);
    let mut labels = vec![String::new(); count];
    if let Some(cat) = first_cat {
        let first_level = cat.descendants().find(|n| n.has_tag_name("lvl"));
        let pts: Vec<XmlNode> = match first_level {
            Some(lvl) => lvl.children().filter(|c| c.has_tag_name("pt")).collect(),
            None => cat.descendants().filter(|n| n.has_tag_name("pt")).collect(),
        };
        for pt in pts {
            let Some(idx) = pt.attribute("idx").and_then(|i| i.parse::<usize>().ok()) else {
                continue;
            };
            if let Some(slot) = labels.get_mut(idx) {
                *slot = child(pt, "v")
                    .and_then(|v| v.text())
                    .unwrap_or("")
                    .to_string();
            }
        }
    }
    match axis {
        Some(axis) if categories_are_dates(axis, plot) => labels
            .into_iter()
            .map(|label| serial_to_iso(&label, date1904))
            .collect(),
        _ => labels,
    }
}

/// docling's `_categories_are_dates`: a date axis always; a text axis when
/// the number format it shows — its own, unless linked to the source data,
/// then the cached categories' — is a date format.
fn categories_are_dates(axis: XmlNode, plot: XmlNode) -> bool {
    if axis.has_tag_name("dateAx") {
        return true;
    }
    let own = child(axis, "numFmt")
        .filter(|f| !matches!(f.attribute("sourceLinked"), Some("1") | Some("true")));
    let format_code = match own {
        Some(f) => f.attribute("formatCode").unwrap_or("").to_string(),
        None => plot
            .children()
            .find(|c| c.has_tag_name("ser"))
            .and_then(|ser| child(ser, "cat"))
            .map(|cat| {
                cat.descendants()
                    .filter(|n| n.has_tag_name("numCache"))
                    .filter_map(|c| child(c, "formatCode"))
                    .filter_map(|f| f.text())
                    .collect::<String>()
            })
            .unwrap_or_default(),
    };
    is_date_format(&format_code)
}

/// docling's `_is_date_format`: with the literal parts removed (quoted text,
/// escaped characters, bracketed colours/locales/conditions, padding), a `d`
/// or `y` code is a date, and an `m` code is a month (not minutes) when
/// there is no `h` or `s`.
fn is_date_format(format_code: &str) -> bool {
    let mut codes = String::new();
    let mut chars = format_code.chars();
    while let Some(c) = chars.next() {
        match c {
            '"' => {
                for q in chars.by_ref() {
                    if q == '"' {
                        break;
                    }
                }
            }
            '[' => {
                for q in chars.by_ref() {
                    if q == ']' {
                        break;
                    }
                }
            }
            '\\' | '_' | '*' => {
                chars.next();
            }
            _ => codes.extend(c.to_lowercase()),
        }
    }
    if codes.contains('d') || codes.contains('y') {
        return true;
    }
    codes.contains('m') && !codes.contains('h') && !codes.contains('s')
}

/// docling's `_serial_to_iso`: an Excel date serial as an ISO 8601 date (a
/// date and time to the second when it has a time of day), else the text
/// unchanged — not a number, negative, or out of Python's `datetime` range.
fn serial_to_iso(text: &str, date1904: bool) -> String {
    let Ok(serial) = text.trim().parse::<f64>() else {
        return text.to_string();
    };
    if !serial.is_finite() || serial < 0.0 {
        return text.to_string();
    }
    let epoch = if date1904 {
        days_from_civil(1904, 1, 1)
    } else {
        // Excel counts the nonexistent 1900-02-29 as serial 60.
        days_from_civil(1899, 12, 30) + i64::from(serial < 60.0)
    };
    // `timedelta(seconds=round(serial * 86400))`: Python rounds half to even.
    let seconds = (serial * 86_400.0).round_ties_even();
    if seconds > 1.0e15 {
        return text.to_string();
    }
    let seconds = seconds as i64;
    let days = epoch + seconds.div_euclid(86_400);
    let secs = seconds.rem_euclid(86_400);
    let (y, m, d) = civil_from_days(days);
    if y > 9999 {
        return text.to_string();
    }
    if secs == 0 {
        format!("{y:04}-{m:02}-{d:02}")
    } else {
        format!(
            "{y:04}-{m:02}-{d:02}T{:02}:{:02}:{:02}",
            secs / 3600,
            secs / 60 % 60,
            secs % 60
        )
    }
}

/// docling's `_axis_title_text`: the rich text's paragraphs, each stripped,
/// joined with a space; else a cell-linked title's cached text.
fn axis_title(axis: XmlNode) -> String {
    let Some(tx) = child(axis, "title").and_then(|t| child(t, "tx")) else {
        return String::new();
    };
    let rich = child(tx, "rich")
        .map(|rich| {
            rich.children()
                .filter(|p| p.has_tag_name("p"))
                .map(|p| {
                    p.descendants()
                        .filter(|n| n.has_tag_name("t"))
                        .filter_map(|n| n.text())
                        .collect::<String>()
                        .trim()
                        .to_string()
                })
                .filter(|p| !p.is_empty())
                .collect::<Vec<_>>()
                .join(" ")
        })
        .unwrap_or_default();
    let text = if rich.is_empty() {
        child(tx, "strRef")
            .map(|r| {
                r.descendants()
                    .filter(|n| n.has_tag_name("v"))
                    .filter_map(|n| n.text())
                    .collect::<String>()
            })
            .unwrap_or_default()
    } else {
        rich
    };
    text.trim().to_string()
}

#[cfg(test)]
mod tests {
    use super::*;

    /// A chart part with one plot `tag` holding `sers` (`c:ser` bodies).
    fn chart_xml(tag: &str, sers: &[&str]) -> String {
        let sers: String = sers.iter().map(|s| format!("<c:ser>{s}</c:ser>")).collect();
        format!(
            r#"<c:chartSpace xmlns:c="c"><c:chart><c:plotArea><c:{tag}>{sers}<c:axId val="1"/></c:{tag}><c:catAx><c:axId val="1"/></c:catAx></c:plotArea></c:chart></c:chartSpace>"#
        )
    }

    const SER_2026: &str = r#"<c:idx val="0"/><c:order val="0"/><c:tx><c:strRef><c:strCache><c:pt idx="0"><c:v>2026</c:v></c:pt></c:strCache></c:strRef></c:tx><c:cat><c:strRef><c:strCache><c:ptCount val="3"/><c:pt idx="0"><c:v>Q1</c:v></c:pt><c:pt idx="1"><c:v>Q2</c:v></c:pt><c:pt idx="2"><c:v>Q3</c:v></c:pt></c:strCache></c:strRef></c:cat><c:val><c:numRef><c:numCache><c:ptCount val="3"/><c:pt idx="0"><c:v>10</c:v></c:pt><c:pt idx="1"><c:v>20</c:v></c:pt><c:pt idx="2"><c:v>30</c:v></c:pt></c:numCache></c:numRef></c:val>"#;

    /// docling#4811: a plot python-pptx has no class for (3-D bar, line,
    /// pie, stock, surface, bar-of-pie) is read like any other and labelled
    /// by its tag; a malformed series (no `c:order`) keeps the label and
    /// drops the table instead of failing.
    #[test]
    fn every_plot_type_is_read_and_labelled_by_its_tag() {
        for (tag, label) in [
            ("bar3DChart", "bar_chart"),
            ("line3DChart", "line_chart"),
            ("pie3DChart", "pie_chart"),
            ("area3DChart", "other_chart"),
            ("stockChart", "other_chart"),
            ("surfaceChart", "other_chart"),
            ("ofPieChart", "other_chart"),
        ] {
            let chart = parse(&chart_xml(tag, &[SER_2026])).unwrap();
            assert_eq!(chart.labels, [label], "{tag}");
            let table = chart
                .table
                .unwrap_or_else(|| panic!("{tag}: no data table"));
            assert_eq!(
                table.rows,
                [["", "2026"], ["Q1", "10"], ["Q2", "20"], ["Q3", "30"]],
                "{tag}"
            );
        }
        let no_order = SER_2026.replace(r#"<c:order val="0"/>"#, "");
        let chart = parse(&chart_xml("bar3DChart", &[&no_order])).unwrap();
        assert_eq!(chart.labels, ["bar_chart"]);
        assert!(chart.table.is_none());
    }

    /// docling's `test_serial_to_iso` cases.
    #[test]
    fn serials_map_to_iso_dates_in_both_systems() {
        for (text, date1904, want) in [
            ("40909", false, "2012-01-01"),
            ("40909.0", false, "2012-01-01"),
            ("39447", true, "2012-01-01"),
            ("40909.5", false, "2012-01-01T12:00:00"),
            ("1", false, "1900-01-01"),
            ("61", false, "1900-03-01"),
            ("Jan", false, "Jan"),
            ("", false, ""),
            ("-1", false, "-1"),
            ("1e300", false, "1e300"),
        ] {
            assert_eq!(serial_to_iso(text, date1904), want, "{text}");
        }
    }

    #[test]
    fn date_formats_are_told_from_time_and_general_ones() {
        for (code, want) in [
            ("m/d/yy", true),
            ("mmm d, yy", true),
            ("yyyy", true),
            ("mmm", true),
            ("h:mm", false),
            ("mm:ss", false),
            ("General", false),
            ("\"day\" 0", false),
            ("[Red]0.00", false),
            ("0_m", false),
        ] {
            assert_eq!(is_date_format(code), want, "{code}");
        }
    }

    #[test]
    fn numbers_read_like_python() {
        assert_eq!(python_number(85.0), "85");
        assert_eq!(python_number(0.126), "0.126");
        assert_eq!(python_number(-2.5), "-2.5");
        assert_eq!(python_number(1.5e-5), "1.5e-05");
        assert_eq!(python_number(-0.0), "0");
        assert_eq!(python_number(1e16), "10000000000000000");
    }
}