Extracting chart data

When a document contains charts, you often want the numbers behind them rather than an image. Meibel digitizes line and scatter charts into their series, reconciles those values with a vision model, and recovers the text labels drawn on the chart. All of it arrives on the chart element in the structured result. This guide reads it in code. For how chart digitization works and what it recovers, see charts, formulas, and vision models.

Prerequisites

A completed parse job for a document that contains charts.
The structured result, fetched with get_structured_result, which is where chart data is exposed.

Find the charts

A chart is an element with the Chart label. When its geometry was recovered, the element carries the digitized plot on chart_data. Walk the pages and collect the chart elements that have it.

from meibel import ParseLayoutLabel

result = client.documents.get_structured_result(job_id=job_id)

charts = [
    el
    for page in result.pages
    for el in page.elements
    if el.label == ParseLayoutLabel.CHART and el.chart_data
]
print(f"Found {len(charts)} charts with data")

const result = await client.documents.getStructuredResult(jobId);

const charts = result.pages
  .flatMap((page) => page.elements)
  .filter((el) => el.label === 'Chart' && el.chartData);
console.log(`Found ${charts.length} charts with data`);

Read the series and points

A chart’s chart_data holds its series, and each series holds its points. Each point carries an x and a y in data units. When the x-axis is categorical, the chart also lists its categories, and a point’s x is the index into that list.

for element in charts:
    chart = element.chart_data
    for series in chart.series:
        name = series.name or "series"
        values = [(p.x, p.y) for p in series.points]
        print(name, values)
    if chart.categories:
        print("categories:", chart.categories)

for (const element of charts) {
  const chart = element.chartData;
  for (const series of chart.series) {
    const name = series.name ?? 'series';
    const values = series.points.map((p) => [p.x, p.y]);
    console.log(name, values);
  }
  if (chart.categories.length) console.log('categories:', chart.categories);
}

Read the recognized labels

The text on a chart, such as axis titles and data labels, is recovered onto the element’s ocr_text. Each entry carries the recognized text, its confidence, and a source of PdfText when it came from the document’s own text or Ocr when it was read from the image. Because ocr_text is a sibling of chart_data, it is present even on a chart whose geometry could not be digitized.

Python

for page in result.pages:
    for element in page.elements:
        if element.label == ParseLayoutLabel.CHART:
            for label in element.ocr_text or []:
                print(label.source, label.confidence, label.text)

Check confidence and warnings

Digitization is an estimate, and the chart records how much to trust it. Each chart carries an overall_confidence and a warnings list. A warning is raised when a recognized value disagrees with the geometry, or when a series cannot be assigned to a left or right axis. Read both before treating the values as exact.

Python

for element in charts:
    chart = element.chart_data
    print("confidence:", chart.overall_confidence)
    for w in chart.warnings:
        print("warning:", w)

Chart values are recovered from geometry and vision model recognition, so they are estimates rather than the source data. Gate on overall_confidence and surface warnings before using the numbers in anything that assumes exact figures.

Charts, formulas, and vision models

How chart data is digitized and reconciled.

Output schema

The full chart data field definitions.

Get started

Tutorials

Core concepts

Agents and sessions

Data and documents

Operations

Document parsing reference

Support

Extracting chart data

Prerequisites

Find the charts

Read the series and points

Read the recognized labels

Check confidence and warnings

Charts, formulas, and vision models

Output schema

​Prerequisites

​Find the charts

​Read the series and points

​Read the recognized labels

​Check confidence and warnings

​Related

Charts, formulas, and vision models

Output schema

Prerequisites

Find the charts

Read the series and points

Read the recognized labels

Check confidence and warnings

Related