Quickstart

Install a development checkout:

python -m venv .venv
. .venv/bin/activate
python -m pip install -e '.[dev]'

Digitize a prepared image crop with known plot bounds:

figrecover digitize-image crop.png \
  --mode line \
  --series-name harvest \
  --series-color '#1f77b4' \
  --plot-left 80 --plot-right 520 --plot-top 40 --plot-bottom 360 \
  --x-min 0 --x-max 100 --y-min 0 --y-max 250 \
  --out harvest.csv

For filled area charts, use the Python API and set line_aggregation="min" to recover the top edge of the coloured area rather than the median coloured pixel in each x-column.

Use the Python API when integrating into a larger system:

from pathlib import Path

from figrecover import Calibration, DigitizeSpec, SeriesSpec, digitize_image

spec = DigitizeSpec(
    calibration=Calibration.from_plot_bounds(
        plot_left=80,
        plot_right=520,
        plot_top=40,
        plot_bottom=360,
        x_min=0,
        x_max=100,
        y_min=0,
        y_max=250,
    ),
    series=[
        SeriesSpec(
            name="harvest",
            color="#1f77b4",
            mode="line",
            line_aggregation="median",
        )
    ],
)

result = digitize_image(Path("crop.png"), spec)
result.to_dataframe().to_csv("harvest.csv", index=False)

When combining many figures, include provenance columns:

result.to_dataframe(include_provenance=True).to_csv(
    "harvest_with_provenance.csv",
    index=False,
)

Next Steps

For a single chart crop, continue with Manual Calibrated Extraction. For a directory of PDFs, continue with Corpus Workflow. For auditable human review, continue with QA And Review Workflow. Review Limitations And Supported Workflows before using recovered values as scientific or operational model inputs.