fig2data

Deterministic CV primitives for extracting calibrated (x,y) numerical data from scientific figure images. Designed to be driven by a vision-capable AI agent: the agent sees (reads ticks, legend, chart type); fig2data measures (pixel to value).

The tool is pure deterministic CV — no models, no OCR, no network.

Install

cd OPC/fig2data
uv venv && uv pip install -e ".[dev]"

Commands

• inspect — image metadata (size, sha256, dpi)
• palette — dominant colors (k-means) in a region
• detect-ticks — tick pixel positions along an axis (gradient projection)
• calibrate — fit pixel/value transform (linear/log), write transform.json (--merge-into to add an axis)
• mask-color — color mask + hit count (HSL tolerance)
• points-from-mask — skeleton/connected-components points through a transform
• resample — uniform_n / dedupe / smooth a series
• trace-line / extract-scatter / extract-bars — one-shot convenience extraction

Every command emits a JSON envelope {"status":"ok"|"warning"|"error", ...}; exit code 0 for ok/warning, non-zero for error. Detection/extraction commands accept --overlay out.png to render point/mask annotations for agent self-check.

Agent cookbook

1. fig2data inspect fig.png
2. fig2data palette fig.png --region <plot bbox>
3. fig2data detect-ticks fig.png --axis x --region <x-axis bbox> --overlay x-ticks.png
4. fig2data calibrate fig.png --axis x --scale linear --anchor px=A,v=0 --anchor px=B,v=100 --save tf.json
   fig2data calibrate fig.png --axis y --scale log   --anchor ... --merge-into tf.json
5. fig2data trace-line fig.png --color "#d62728" --transform tf.json --overlay ov.png
6. agent reads ov.png with its vision; if misaligned, adjust color/region/anchors and retry.

Precision

On synthetic fixtures (linear/log, multiple colors), fig2data achieves median extraction error of 0.53% and p95 of 6.53% versus known ground truth (n=75), well within the v1 gate of median < 3% / p95 < 8%. See tests/test_precision.py.

Scope (v1)

Line / scatter / bar, 2D cartesian, linear + log axes. No heatmaps, polar, dual Y-axis, or error bars (v2). No PDF figure detection (upstream is MinerU's job).