trace-digitiser 2.0.0__tar.gz → 2.1.0__tar.gz

{trace_digitiser-2.0.0 → trace_digitiser-2.1.0}/CHANGELOG.md

@@ -4,6 +4,66 @@ All notable changes to trace-digitiser are recorded here.
 The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/)
 and the project uses [semantic versioning](https://semver.org/).
 
+## [2.1.0] - 2026-11-14
+
+Everything in 2.0.0 works as before. What is new is readers for other kinds of
+figure, and helpers for graphical tools such as the
+[digitiser workbench](https://github.com/comparativechrono/digitiser-workbench).
+
+### Added
+
+- **Points**: `digitise_points` (`trace-digitiser points`) reads the markers of
+  a scatter or dot plot, or of a line drawn with markers, whatever their
+  shape, separating markers that overlap; and the error bars on them,
+  vertical or horizontal, to the middle of their caps.
+- **Bars**: `digitise_bars` (`trace-digitiser bars`) reads where each bar
+  ends, upright or lying down, rising or hanging from the baseline, and its
+  error bar; a legend's patch is left out.
+- **Rows**: `digitise_rows` (`trace-digitiser rows`) reads figures drawn as a
+  stack of rows - actograms, double-plotted records, birthograms - bin by bin,
+  and the dots that mark a peak in them.
+- **Heat maps**: `digitise_heatmap` (`trace-digitiser heatmap`) reads each
+  cell's value from its colour on the colour bar, whose labels are read like
+  an axis's (or from a matplotlib colour map).
+- **Polar plots**: `digitise_polar` (`trace-digitiser polar`) finds the polar
+  axes and their rings, and reads each point's angle and distance.
+- All of them return a `FigureResult` and write a CSV file, a provenance file
+  and, if asked, an overlay, as `digitise` does.
+- `describe_figure` (`trace-digitiser describe`): what the automatic steps
+  find in a figure - plot areas, each axis's tick labels and readings, the
+  colours drawn, a colour bar, polar axes - as plain values.
+- `pixels_to_values`: points picked by hand, in the figure's units.
+- Tick labels are read on the right-hand side of a plot too (a colour bar, a
+  second y axis): `calibrate_axis(..., "y2")`.
+- `y_axis="right"` (`--y-axis right`) reads a line's values against a second
+  y axis on the right of the plot (a twin axis); with `trace_colours`, the
+  lines drawn against each axis are digitised in a run of their own.
+- `describe_figure` gives the tick marks found on each plot's axes, for a
+  program that lets you click on a tick.
+- Colours can be given by name (`"black"`, `"steelblue"`, `"tab:blue"`).
+- Plots stacked on a shared x axis, of which only the lowest has labels, take
+  its x scale (with a message saying so).
+- A plot area hidden among others in a grid (a heat map whose dark colours
+  hide its axis lines) is found by its frame.
+
+### Changed
+
+- An axis scale is held to medium confidence when the tick labels support a
+  different scale just as well. Tesseract compiled to WebAssembly (as it runs
+  in a browser) read the superscript minus signs of a log axis's exponents
+  differently from the Tesseract program, and two scales then fitted equally;
+  between log scales that tie, the one that steps by a decade is chosen.
+- The sides of filled areas (bars) no longer make a plot area of their own
+  inside the real one, which bar charts with a legend could cause.
+- A long axis (ten or more labels) whose labels nearly all agree is not read
+  again in the slower ways; fitting the labels of a long axis (the 59 years of
+  a birthogram) takes a second or two rather than half a minute, with the same
+  result.
+- A heat map's colours are looked up on the colour bar once each, rather than
+  once for each pixel: Figure 4 of Hearn and Whitmore (2026) takes 4 seconds
+  rather than 45, with the same values.
+- pytesseract is imported only when it is first used.
+
 ## [2.0.0] - 2026-11-14
 
 Every call and command-line option of 1.2.0 still works, with the same
@@ -105,5 +165,6 @@ First version tracked in this repository; identical to the 1.2.0 files on PyPI.
 Releases 0.1.0 to 1.0.0 (6-7 June 2026) were uploaded to PyPI directly and are
 not recorded here.
 
+[2.1.0]: https://github.com/comparativechrono/trace-digitiser/compare/v2.0.0...v2.1.0
 [2.0.0]: https://github.com/comparativechrono/trace-digitiser/compare/1d34f75...v2.0.0
 [1.2.0]: https://pypi.org/project/trace-digitiser/1.2.0/

{trace_digitiser-2.0.0/src/trace_digitiser.egg-info → trace_digitiser-2.1.0}/PKG-INFO

@@ -1,14 +1,14 @@
 Metadata-Version: 2.4
 Name: trace-digitiser
-Version: 2.0.0
-Summary: Recover the data from line plots in figure images, on your own computer: no uploads, no AI model.
+Version: 2.1.0
+Summary: Recover the data from figure images - lines, points, bars, actograms, heat maps - on your own computer: no uploads, no AI model.
 Author: Trace Digitiser Contributors
 License-Expression: MIT
 Project-URL: Homepage, https://github.com/comparativechrono/trace-digitiser
 Project-URL: Repository, https://github.com/comparativechrono/trace-digitiser
 Project-URL: Issues, https://github.com/comparativechrono/trace-digitiser/issues
 Project-URL: Changelog, https://github.com/comparativechrono/trace-digitiser/blob/main/CHANGELOG.md
-Keywords: plot digitizer,graph digitiser,data extraction,data rescue,computer vision,time series,circadian,actigraphy
+Keywords: plot digitizer,graph digitiser,data extraction,data rescue,computer vision,time series,circadian,actigraphy,actogram,heat map,scatter plot,bar chart
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Science/Research
 Classifier: Operating System :: OS Independent
@@ -40,11 +40,12 @@ Dynamic: license-file
 
 # trace-digitiser
 
-Get the numbers back out of a line plot when the figure is all that survives — on your own computer.
+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 is ordinary image
-processing, written to be read and checked.
+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](#other-kinds-of-figure). 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](https://github.com/tesseract-ocr/tesseract), also on your machine and optional, to read
@@ -111,6 +112,41 @@ A scale read from labels always comes with a statement of how far to trust it an
 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](#how-accurate-is-it)).
 
+## 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 |
+
+```python
+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](https://github.com/comparativechrono/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
 
 1. **Look at the overlay** (`--overlay`). It shows the plot area that was found, the centre and
@@ -180,6 +216,7 @@ the top-left corner of the image, starting at 0; any image viewer shows them.
 | 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"` |
@@ -253,14 +290,19 @@ does this for a week of minute-by-minute activity drawn at the size of a small j
   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, dashed or dotted lines, and
-  traces that are only markers are not separated or joined up.
+* 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 (`interpolated` is `True`).
-* Axis scales are read only from numeric labels on linear or logarithmic axes; dates, broken axes
-  and a second y axis are not understood. Limits typed in are assumed to be at the axis lines
-  unless `y_ref` / `x_ref` say otherwise.
-* Error bars, shaded bands, bars and scatter plots are not digitised.
+  interpolated (`interpolated` is `True`). 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_ref` for those. Limits typed in are assumed to be at the axis
+  lines unless `y_ref` / `x_ref` say 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
 
@@ -284,6 +326,11 @@ ruff check src tests
 | `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](https://github.com/comparativechrono/trace-digitiser/blob/main/CHANGELOG.md);

{trace_digitiser-2.0.0 → trace_digitiser-2.1.0}/README.md

@@ -1,10 +1,11 @@
 # trace-digitiser
 
-Get the numbers back out of a line plot when the figure is all that survives — on your own computer.
+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 is ordinary image
-processing, written to be read and checked.
+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](#other-kinds-of-figure). 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](https://github.com/tesseract-ocr/tesseract), also on your machine and optional, to read
@@ -71,6 +72,41 @@ A scale read from labels always comes with a statement of how far to trust it an
 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](#how-accurate-is-it)).
 
+## 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 |
+
+```python
+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](https://github.com/comparativechrono/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
 
 1. **Look at the overlay** (`--overlay`). It shows the plot area that was found, the centre and
@@ -140,6 +176,7 @@ the top-left corner of the image, starting at 0; any image viewer shows them.
 | 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"` |
@@ -213,14 +250,19 @@ does this for a week of minute-by-minute activity drawn at the size of a small j
   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, dashed or dotted lines, and
-  traces that are only markers are not separated or joined up.
+* 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 (`interpolated` is `True`).
-* Axis scales are read only from numeric labels on linear or logarithmic axes; dates, broken axes
-  and a second y axis are not understood. Limits typed in are assumed to be at the axis lines
-  unless `y_ref` / `x_ref` say otherwise.
-* Error bars, shaded bands, bars and scatter plots are not digitised.
+  interpolated (`interpolated` is `True`). 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_ref` for those. Limits typed in are assumed to be at the axis
+  lines unless `y_ref` / `x_ref` say 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
 
@@ -244,6 +286,11 @@ ruff check src tests
 | `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](https://github.com/comparativechrono/trace-digitiser/blob/main/CHANGELOG.md);

{trace_digitiser-2.0.0 → trace_digitiser-2.1.0}/RELEASING.md

@@ -23,14 +23,14 @@ This has to be done once by an owner of the `trace-digitiser` project on PyPI.
 
 3. Click **Add**.
 
-That is all. The link works while the repository is private.
+That is all.
 
 ### Optional hardening
 
 PyPI recommends tying the publisher to a GitHub *environment*, which lets you
-require a manual approval before each upload. GitHub only offers environments
-on private repositories for paid plans, so the workflow does not use one. Once
-the repository is public (or on a paid plan):
+require a manual approval before each upload. The workflow does not use one
+yet (when the repository was private, GitHub offered environments only on paid
+plans). Now that the repository is public, one can be added:
 
 1. Create an environment called `pypi` under *Settings -> Environments*
    (optionally with required reviewers).
@@ -39,10 +39,12 @@ the repository is public (or on a paid plan):
 
 ## Making a release
 
-1. Set `version` in `pyproject.toml` (PyPI never accepts the same version
-   twice; the last published version is 1.2.0).
+1. Set `version` in `pyproject.toml`. PyPI never accepts the same version
+   twice; the versions already published are listed at
+   <https://pypi.org/project/trace-digitiser/#history>.
 2. In `CHANGELOG.md`, give the section for the version its date in place of
-   "not yet released".
+   "unreleased", and end its link at the new tag (`...vX.Y.Z` in place of
+   `...HEAD`).
 3. Merge to `main` and wait for the *Tests* workflow to pass.
 4. On GitHub: *Releases -> Draft a new release*, create the tag `vX.Y.Z`
    (matching the version exactly, with a leading `v`) on `main`, and publish.
@@ -53,8 +55,7 @@ uploads to PyPI. If the tag and version disagree, or a test fails, the run
 stops before anything is uploaded.
 
 The README is shown on PyPI as it is in the release. Its links to files in
-this repository are absolute, so they work there only once the repository is
-public.
+this repository are absolute, so they work there too.
 
 ## Checking a build without releasing
 

{trace_digitiser-2.0.0 → trace_digitiser-2.1.0}/pyproject.toml

@@ -4,8 +4,8 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "trace-digitiser"
-version = "2.0.0"
-description = "Recover the data from line plots in figure images, on your own computer: no uploads, no AI model."
+version = "2.1.0"
+description = "Recover the data from figure images - lines, points, bars, actograms, heat maps - on your own computer: no uploads, no AI model."
 readme = "README.md"
 license = "MIT"
 license-files = ["LICENSE"]
@@ -20,6 +20,10 @@ keywords = [
     "time series",
     "circadian",
     "actigraphy",
+    "actogram",
+    "heat map",
+    "scatter plot",
+    "bar chart",
 ]
 classifiers = [
     "Development Status :: 4 - Beta",