trace-digitiser
Get the numbers back out of a figure when the figure is all that survives — on your own computer.
trace-digitiser takes an image of a figure (a scan of an old paper, a figure saved from a PDF),
finds the plot area, follows each trace, and writes the values to a CSV file. It reads line plots,
and also points, bars, actograms, heat maps and polar plots. It is
ordinary image processing, written to be read and checked.
Nothing is uploaded and no AI model is involved. The only other program it runs is Tesseract, also on your machine and optional, to read the numbers printed beside the axes. A figure that you are not free to pass to an online service can therefore still be digitised. (Whether the values in a published figure may be reused is a matter for the licence of the source and the law where you work; no tool can settle that for you.)
A worked example with pictures is in
examples/walkthrough.ipynb.
Install
pip install trace-digitiser
Python 3.10 or later. To have axis values read from the figure, also install Tesseract
(sudo apt-get install tesseract-ocr, brew install tesseract, or the
Windows installer). Without it everything else
works, and you type in the axis limits yourself — which is the better practice anyway.
Use
From the command line:
trace-digitiser figure.png --y-min 0 --y-max 300 --x-min 0 --x-max 7 --overlay -o results/
or from Python:
from trace_digitiser import digitise
result = digitise("figure.png", y_min=0, y_max=300, x_min=0, x_max=7,
output_dir="results", save_overlay=True)
result.trace_data # one row per pixel column of each trace
result.warnings # anything you should check
result.overlay_path # the digitised traces drawn over the figure
y_min and y_max are the values at the bottom and top axis lines, x_min and x_max those at
the left and right. Nothing else is needed for most figures: the plot areas (any number of panels)
and the traces (coloured, black or grey) are found automatically, and a scan that lies a few
degrees askew is straightened first.
Leave the limits out and the scale is read from the tick labels instead:
trace-digitiser figure.png --overlay -o results/
Panels: 2, Traces: 2
panel 1: y 0.31 to 299, read from tick labels (medium confidence); x not calibrated
CHECK: Panel 1: the y-axis scale was read from 7 of 7 tick labels (300, 250, 200, 150, 100, 50, 0);
the print is only 6 pixels high. Confidence in it is medium: check those values against
the figure, or give y_min and y_max.
A scale read from labels always comes with a statement of how far to trust it and, unless that is "high", of the labels it rests on. If too few labels can be read to agree on a scale, the axis is left uncalibrated (values from 0 to 1) and you are told so: the aim is never to pass off a wrong scale as a good one (how well that is met).
Other kinds of figure
Points, bars, stacked rows, heat maps and polar plots each have a reader of their own. They find
the plot areas and read the axes exactly as digitise does, take the same settings for them
(y_min, y_ref, plot_area, exclude …), and give a table with a row for each thing found:
| Figure | Python | Command line | One row for each |
|---|---|---|---|
| Scatter or dot plot, line with markers | digitise_points |
trace-digitiser points |
point, with its error bars |
| Bar chart | digitise_bars |
trace-digitiser bars |
bar: where it ends, and its error bar |
| Actogram, double-plotted record, any stack of rows | digitise_rows |
trace-digitiser rows |
bin (or column) of each row |
| Heat map with a colour bar | digitise_heatmap |
trace-digitiser heatmap |
cell, from its colour on the bar |
| Polar plot | digitise_polar |
trace-digitiser polar |
point: its angle and distance |
from trace_digitiser import digitise_points, digitise_bars, digitise_rows, digitise_heatmap
digitise_points("forest.png", save_overlay=True) # markers, joined by a line or not; error bars too
digitise_bars("bars.png", y_min=-25, y_max=0) # the legend's patch is left out
digitise_rows("birthogram.png", row_values=range(1955, 2014), row_spacing_value=1.1,
bins=24, dots="black") # each row's fill, month by month, and its dot
digitise_heatmap("ccf.png", rows=21) # the colour bar's labels are read too
Each returns a FigureResult: result.data (the table), result.warnings, result.overlay()
and the files written (<image>_points.csv, <image>_points_provenance.json …).
For a program with a graphical interface — the
digitiser workbench, which runs all of
this in a web browser, where you can mark plot areas, ticks and colours with the mouse —
describe_figure reports what the automatic steps find (plot areas, the tick marks on each axis,
each axis's tick labels and what was read from them, the colours drawn, a colour bar, polar axes)
so that they can be shown and corrected, and pixels_to_values turns points picked by hand into
the figure's units. trace-digitiser describe figure.png prints the same as JSON.
Check the result
- Look at the overlay (
--overlay). It shows the plot area that was found, the centre and envelope of each digitised trace drawn over the original, and the positions of the axis values. If the lines sit on the traces, the digitisation is right; if they do not, you can see where. - Read the messages. Everything the program is unsure of is printed as a
CHECK:line (in Python:result.warnings, also raised asDigitiserWarning). A clean run prints none. - Keep the provenance file.
<name>_automated_provenance.jsonrecords the version, the SHA-256 of the image, every setting, what was detected and all messages, so that a digitisation can be reported and repeated exactly.
Output
| File | Contents |
|---|---|
<name>_automated_digitised_trace_by_column.csv |
One row per pixel column per trace (below). |
<name>_automated_panel_metadata.csv |
Where each plot area is, its axis calibrations and how they were obtained. |
<name>_automated_digitised_summary_by_label.csv |
Means per labelled interval, when the x axis carries interval names (1N, 1D, …). |
<name>_automated_provenance.json |
Everything needed to report and repeat the run. |
<name>_automated_overlay.png |
With --overlay: the result drawn over the figure. |
<name>_automated_straightened.png |
Only if the figure was tilted: the image turned upright, which is what pixel positions in the other files refer to. |
Columns of the trace file:
| Column | Meaning |
|---|---|
panel_id, trace_id |
Panels are numbered row by row from the top left; traces within a panel from 1. |
x_pixel, x_norm_0_to_1 |
The pixel column, and its position between the left (0) and right (1) axis lines. |
x_value |
The x value, if the x axis is calibrated. |
center_estimate |
Middle of the trace's ink in this column (median of its pixels). |
mean_estimate |
Mean of the trace's pixels in this column. |
upper_envelope, lower_envelope |
Top and bottom of the trace's ink in this column. |
n_pixels, interpolated |
How many pixels the trace has in this column; True if it has none and the values were interpolated from its neighbours. |
scale_type |
Where the y values come from: user_supplied, ocr_value, normalised_0_to_1, … |
trace_median_rgb, trace_pixel_count |
The trace's colour and size, for identifying it. |
result.resample(...) and --sampling-interval put the trace on an even grid in x.
What the values are — and are not
A digitiser recovers what was drawn, not what was measured.
- For an ordinary curve — a thin line with at most a few samples per pixel column —
center_estimateis the plotted value, to within a fraction of a pixel. - For a dense record, where many samples share each pixel column and the trace is drawn as a
solid band (an activity record of several days in a small figure, for instance), the drawing
shows only the range of the samples in each column.
upper_envelopeandlower_enveloperecover that range;center_estimateis its middle. None of them is the mean of the samples, and for spiky data the middle of the range can be far from the mean. The timing of the rhythm survives; the level does not.
How much this matters for a particular kind of data and size of figure can be measured rather than guessed: see Test it on data you know.
Positions cannot be better than the image. In a plot area 350 pixels wide showing seven days, one pixel is half an hour.
When something is not found
Each automatic step can be replaced by telling the program the answer. Pixel positions count from the top-left corner of the image, starting at 0; any image viewer shows them.
| Problem | Option | Python |
|---|---|---|
| The figure is tilted and was not straightened, or was turned when it should not have been | --straighten DEGREES (its anticlockwise tilt), --straighten never |
straighten=1.3, straighten=False |
| The plot area is wrong or not found | --plot-area LEFT,TOP,RIGHT,BOTTOM (repeat per panel) |
plot_area=(l, t, r, b) |
| The wrong number of panels | --layout, --rows, --cols, --panels |
layout_mode, expected_rows, … |
| The axis continues beyond its last tick, or has no line at the top or right | --y-ref ROW:VALUE twice or more (also --x-ref) |
y_ref=[(row, value), …] |
| A logarithmic axis, with limits given | --y-scale log |
y_scale="log" |
| A line drawn against a second y axis, on the right | --y-axis right (with --trace-colour) |
y_axis="right" |
| A trace is missed, or two are merged | --trace-colour RRGGBB (repeat per trace) |
trace_colours=["#578dd2", …] |
| A legend or annotation is taken for a trace | --exclude LEFT,TOP,RIGHT,BOTTOM |
exclude=(l, t, r, b) |
| A black trace is invented or ignored | --achromatic never / always |
achromatic="never" |
| No Tesseract, or it should not be used | --no-ocr |
ocr=False |
How accurate is it?
The package carries its own tests against known answers, and you can rerun them.
Traces. trace-digitiser --validate results/ draws 44 figures (57 traces) from known data —
different axis styles, twelve colours including black and grey, 60 to 300 dpi, JPEG compression,
noise and blur, line widths, multi-panel layouts, several traces per panel, a logarithmic axis,
jagged and dense records, tilted scans — digitises them, and compares. Errors are in percent of the
height of the plot. A trace counts as recovered if its panel and curve were found with no
spurious extra trace, x positions are within 1 % and the RMS error in y is within 2 %.
| found | recovered | median error | time per figure¹ | |
|---|---|---|---|---|
| 2.0, nothing supplied | 57 of 57 | 55 | 0.13 % | 0.5 s |
| 2.0, axis limits supplied | 57 of 57 | 55 | 0.09 % | 0.3 s |
| 1.2.0, panel layout supplied | 48 of 57 | 20 | 0.49 % | 20 s |
| 1.2.0, panel layout and axis limits supplied | 48 of 57 | 13 | 1.39 % | 0.3 s |
¹ On a two-core machine.
The two traces that 2.0 does not recover are dense records in low-resolution figures (errors of 2.3 % and 4.3 %), for the reason given above. Of the traces that 1.2.0 found but did not recover, most came with a spurious second trace.
Axis scales. Reading a scale from tick labels is the one step that depends on OCR, and OCR of
small print is unreliable, so it is tested separately:
python -m trace_digitiser.validation results/ --axes reads 750 axes (whole numbers, decimals,
negative values, thousands, clock and angle steps, logarithmic; print from 5 to 24 pixels high;
three typefaces; JPEG compression and blur).
| Height of the labels | axes | read correctly | declined | read wrongly, with a warning | read wrongly, no warning |
|---|---|---|---|---|---|
| 8 pixels or more | 477 | 464 | 13 | 0 | 0 |
| under 8 pixels | 273 | 257 (all with a warning to check them) | 15 | 1 | 0 |
Declined means that no scale was offered. All of those at 8 pixels or more are logarithmic axes whose raised exponents are too small to read, though the rest of the label is not. The outcome for small print depends on how the text was rasterised: with the test figures drawn by matplotlib 3.7, which renders small print more softly than current versions, 236 of 292 axes under 8 pixels were read correctly, 46 declined and 10 read wrongly with a warning — and still none without.
Labels under 8 pixels high are never given high confidence, however well they agree, because print that small is misread in consistent ways — the decimal point dropped from every label, say. If your figure has such labels, enlarging the image does not help; typing in two numbers does.
Test it on data you know
The best test of a digitisation is one on data like yours. round_trip draws a known series as a
figure of whatever size and style you choose, digitises the drawing, and reports the errors:
from trace_digitiser.validation import round_trip
check = round_trip(t, y, "check/", xlim=(0, 7), ylim=(0, 300),
panel_px=(347, 137), dpi=72, linewidth=0.8, fmt="jpg")
check["metrics"] # errors of centre and envelopes, correlation with the mean per column, …
check["overlay"] # the picture to look at
examples/validate_with_known_data.py
does this for a week of minute-by-minute activity drawn at the size of a small journal figure.
Limits
- The plot must have at least a left and a bottom axis line, drawn in black or grey. A figure that is askew is straightened automatically if the tilt is under five degrees; beyond that, or for a photograph taken at an angle (where the axes are no longer parallel), correct the image first.
- One trace per colour per panel. Two traces of the same colour and dashed or dotted lines are not
separated or joined up. Markers are read by
digitise_points. - Where traces cross or overlap, the one drawn underneath is hidden and its values there are
interpolated (
interpolatedisTrue). Markers that overlap heavily (the inner turns of a spiral on a polar plot, say) are separated by their size, and some may be missed or doubled: check the overlay. - Axis scales are read only from numeric labels on linear or logarithmic axes (on the left, below,
or for a colour bar or a second y axis, on the right); dates, month names and broken axes are
not understood: give
x_ref/y_reffor those. Limits typed in are assumed to be at the axis lines unlessy_ref/x_refsay otherwise. - Shaded bands are not digitised. A fill drawn with an outline of its own colour (matplotlib's
fill_between) is measured to the middle of the outline; bars are measured to their edges, to the nearest pixel where the bars' edges are not antialiased.
Development
git clone https://github.com/comparativechrono/trace-digitiser.git
cd trace-digitiser
pip install -e ".[dev]"
pytest # the tests that need Tesseract are skipped without it
ruff check src tests
src/trace_digitiser/ in the order the work is done:
| Module | Does |
|---|---|
straighten.py |
Measures the tilt of a scan and turns it upright. |
frames.py, panel_detection.py |
Finds axis lines and assembles them into plot areas. |
axis_labels.py, calibration.py, x_calibration.py |
Locates and reads tick labels, fits the scale, rates its confidence; or takes the limits given. |
trace_detection.py |
Separates the traces from gridlines, axes and text. |
digitise.py |
Converts each trace to values, column by column. |
ocr.py, summarise.py |
Interval labels along the x axis, and means per interval. |
diagnostics.py, provenance.py, io.py |
Overlay, record of the run, files. |
validation.py, synthetic.py |
Figures drawn from known data, and the comparisons. |
_figure.py |
What every reader does first: the image, straightening, plot areas and axes. |
markers.py, points.py |
Markers and their error bars. |
bars.py, rows.py, heatmap.py, polar.py |
Bar charts, stacks of rows, heat maps and polar plots. |
explore.py |
describe_figure and pixels_to_values, for graphical tools. |
_results.py |
What the readers of points, bars, rows, heat maps and polar plots give back. |
cli.py |
The command line. |
Changes are listed in CHANGELOG.md; making a release is described in RELEASING.md.
Licence
MIT; see LICENSE. The example figure has its own licence and attribution, given in
examples/README.md.
Metadata
Release files for trace-digitiser 2.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| trace_digitiser-2.1.0.tar.gz | 1.2 MB | With provenance | Details for trace_digitiser-2.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| trace_digitiser-2.1.0-py3-none-any.whl | Python 3 | none | any | Details for trace_digitiser-2.1.0-py3-none-any.whl |
Total release size: 1.4 MB
Release files / trace_digitiser-2.1.0.tar.gz
| Download URL | trace_digitiser-2.1.0.tar.gz |
|---|---|
| Size | 1.2 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
7c4c9074fbca855618cc4d46468df50085c71479c7daf8d403a8ef37e78e428d
|
|
BLAKE2b-256 checksum How to use checksums |
c3d94369d9c96e751e13b19523c52d89ceedfb98da9ff1c910b6f64e6611b628
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 14, 2026.
Transparency logRelease files / trace_digitiser-2.1.0-py3-none-any.whl
| Download URL | trace_digitiser-2.1.0-py3-none-any.whl |
|---|---|
| Size | 166.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
f042be91a66745ec67734c8edfd720bd4307bb84d9e403562278e979f0f0b7d6
|
|
BLAKE2b-256 checksum How to use checksums |
64396d986283a77ba876fda571441bcde53b6ba481bfbb385a3769ff7b47040d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 14, 2026.
Transparency logSecurity for trace-digitiser 2.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for trace_digitiser-2.1.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 14, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.