unplot 0.0.0__tar.gz → 0.0.1__tar.gz

unplot-0.0.1/.github/workflows/pages.yml

@@ -0,0 +1,42 @@
+name: Deploy demo to Pages
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: oven-sh/setup-bun@v2
+      - name: Install
+        working-directory: js
+        run: bun install --frozen-lockfile
+      - name: Build demo
+        working-directory: js
+        run: bun run build:demo
+      - uses: actions/configure-pages@v5
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: js/demo/dist
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v4

unplot-0.0.1/.gitignore

@@ -0,0 +1,20 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+venv/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.DS_Store
+*.so
+
+# manual-comparison artifacts (regenerable / user data)
+compare/plots/
+compare/submissions/
+
+# node / TS port
+node_modules/

unplot-0.0.1/PKG-INFO

@@ -0,0 +1,163 @@
+Metadata-Version: 2.4
+Name: unplot
+Version: 0.0.1
+Summary: Vector-PDF-native plot extraction with automatic multi-curve crossing separation and a first-class QA report.
+Author: Max Ingham
+License: MIT License
+        
+        Copyright (c) 2026 Max Ingham
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: curve,datasheet,digitizer,extraction,pdf,plot,vector
+Requires-Python: >=3.10
+Requires-Dist: numpy>=1.24
+Requires-Dist: pymupdf>=1.23
+Provides-Extra: raster
+Requires-Dist: opencv-python-headless>=4.8; extra == 'raster'
+Requires-Dist: pillow>=10.0; extra == 'raster'
+Provides-Extra: test
+Requires-Dist: pytest>=7.0; extra == 'test'
+Description-Content-Type: text/markdown
+
+# unplot
+
+**Read curves off a plot, straight from the vector PDF, with overlapping curves pulled apart and a confidence score on each.**
+
+**[Try the live demo →](https://somnai-dreams.github.io/unplot/)** — drop a vector PDF in your browser; nothing is uploaded.
+
+unplot is a headless library (Python and TypeScript) for digitizing line and curve plots. Interactive tools like WebPlotDigitizer, Engauge, and PlotDigitizer want you to load an image and click to calibrate the axes. unplot runs unattended instead, and does two things those tools don't:
+
+- **Vector-PDF-native.** When a PDF's curves are real drawn paths, unplot reads the exact geometry out of the file. No rasterizing, no pixel re-detection, no clicking. The numbers you get back are the numbers that were drawn.
+- **Automatic crossing separation.** Where curves overlap and cross, it keeps them apart: by stroke style or colour for vector paths, by hue for colour-coded raster images, or by de-fanning and re-chaining a single pen stroke that traces several lobes at once.
+
+Every result also carries a **confidence report**, per curve and for the set: shape-prior violations, calibration fit, coverage gaps, crossings. If a curve is suspect, the report says so.
+
+## Quick start
+
+Python:
+
+```python
+from unplot import extract, Lobe
+
+cs = extract("plot.pdf", frame=(60, 40, 360, 240),
+             prior=Lobe(0.08), expected_curves=3, order_by="peak-x")
+
+for c in cs.curves:
+    print(c.id, c.points.shape, c.qa.confidence, c.qa.passed)
+
+named = cs.labeled({0: "blue", 1: "green", 2: "red"})   # you map order to meaning
+```
+
+TypeScript, in the browser, with no Python and no server (see [`js/`](js/)):
+
+```ts
+import { extract, lobe } from "unplot";   // js/src/index.ts
+
+const data = new Uint8Array(await (await fetch("plot.pdf")).arrayBuffer());
+const cs = await extract(data, { expectedCurves: 3, prior: lobe(0.08), orderBy: "peak-x" });
+cs.curves.forEach(c => console.log(c.id, c.style.color, c.qa.confidence));
+```
+
+[`js/`](js/) also has a drop-a-PDF demo: it renders the page, overlays the recovered curves, shows the QA, and exports CSV. The bytes never leave the page.
+
+## What you get back
+
+`extract(plot) -> CurveSet`. One plot region in, one CurveSet out:
+
+- **calibrated arrays** per curve (`points`, in your axis units), plus source-space points for overlay
+- **neutral identity.** Curves come back as `c0, c1, …`, ordered deterministically by peak-x, mean-y, or first-x. unplot knows nothing about your domain; you map order to meaning.
+- **a QA report**: `CurveQA` per curve, `CurveSetQA` for the set.
+
+## Shape priors
+
+The one thing you supply is the expected shape of your curves, as a `ShapePrior`. It scores confidence, and it breaks ties at crossings by picking the continuation that keeps each curve on its own flank. Shipped priors:
+
+- `Free`: no assumption, raw geometry.
+- `Monotone(direction)`: the curve only goes one way.
+- `Lobe(tolerance)`: approximately unimodal (rise to a peak, then fall). `tolerance` is how much flank reversal is allowed before a curve is flagged, not a demand for strict unimodality, so real shoulders and double-humps survive.
+- `Smooth`: penalise spikes.
+
+Write your own by implementing `qa_violation` and `separation_bias`.
+
+## Scope
+
+Supported: vector-PDF ingest (exact geometry) and raster images (pixel fallback); linear axis calibration from numeric tick labels, robust to stray labels leaking in from a neighbouring plot; crossing separation under a shape prior; the QA report.
+
+Not yet, and PRs welcome:
+
+- **Log-spaced axes.** Calibration is linear pt-to-value. Axes whose *values* are log quantities work fine when they're drawn linearly; genuinely log-*spaced* axes are not.
+- **Many identically-styled curves on one plot.** With no colour or dash to tell them apart (e.g. a five-curve grey density plot), the separator can merge overlapping ones. The merge is detected — a `roughness` check, total y-variation over y-range — and the tangle is dropped with a warning rather than returned as a curve; cleanly-separated curves on the same plot still come back.
+- **Heavily occluded mono scans.** Colour curves separate by hue; single-colour curves separate by continuity and the shape prior, which handles clean crossings. A low-resolution mono *scan* with a weak curve buried under a stronger one can mis-assign, and the QA reports it as low confidence. Use vector ingest or a colour-coded source there.
+- Broken axis boxes, legends drawn over curves, exotic scales, automatic frame detection for raster scans.
+
+## Accuracy
+
+Peak error on synthetic ground truth, in x-axis units (the plots span x 400 to 700). From `bench/benchmark.py`, seed-fixed, 20 randomized plots per tier:
+
+| tier | median | p90 |
+|-|-|-|
+| vector, 3–4 curves, separated or crossing | 0.5–0.9 | 1.3–1.5 |
+| raster colour, 3 crossing (with or without noise) | 1.1 | 1.5 |
+| raster mono, 3 crossing | 1.0 | 1.6 |
+| raster mono, 3 occluded | 1.3 | 6.3 |
+
+Vector is essentially exact: it reads drawn geometry, so crossings and curve count don't move the number. Raster is tight on synthetic plots, around 1 unit median, with an occluded lobe (one weak curve buried under its neighbours) the harder synthetic case. The real-world hard case, a low-resolution mono scan with heavy occlusion, still degrades, and there the QA flags it rather than returning a confident wrong answer.
+
+The vector path also reproduces reference extractions of real PDFs numerically: a dash/colour-keyed plot of three overlapping curves (every peak matched exactly, peak-normalised shape RMS 0.000), and a continuous-stroke polyline carrying a real double-hump (peaks within 8 units, the substructure preserved rather than flattened).
+
+## How it compares
+
+unplot is narrower than the established tools on purpose: line and curve plots, headless, vector-native, self-reporting its own confidence, built for batch and automation rather than interactive correction. WebPlotDigitizer and Engauge are mature GUIs that cover many chart types and let a human fix mistakes live. To digitize one chart by hand, use them.
+
+| capability | unplot | WebPlotDigitizer | Engauge | PlotDigitizer |
+|-|-|-|-|-|
+| reads vector-PDF geometry | yes | no (image) | no (image) | no (image) |
+| automatic axis calibration | yes (vector) | click axes | click axes | click axes |
+| crossing separation | hue or shape prior | colour / layers | guided | manual / auto |
+| QA / confidence output | yes | no | no | no |
+| headless, scriptable batch | yes | no (web app) | no (GUI) | no |
+| other chart types (polar, bar…) | no | yes | yes | yes |
+| license | MIT | AGPL-3.0 | GPL | proprietary |
+
+On clean colour plots a head-to-head against the real WebPlotDigitizer 4.8 (its own auto-extraction, with an exact calibration set through its API) is a dead heat: both land around 0.5 to 1 unit, because both do a colour mask plus per-column averaging. unplot pulls ahead on vector PDFs, which WPD can't read at all; on noise, where its denoising rode out a case WPD's fixed threshold tripped on; and on frame removal, since WPD grabbed the black plot frame until a region was masked. WPD is the only incumbent benchmarked here. Engauge is a desktop GUI and PlotDigitizer is login-gated, so neither can be batch-run.
+
+## Install
+
+Python:
+
+```bash
+pip install unplot            # vector-PDF core + numpy
+pip install "unplot[raster]"  # adds opencv/pillow for the raster fallback
+```
+
+TypeScript: the port lives in [`js/`](js/). Run `bun install` there; the only runtime dependency is pdf.js (`pdfjs-dist`, Apache-2.0).
+
+## Tests
+
+```bash
+pip install "unplot[test]" && pytest   # Python
+cd js && bun test                           # TypeScript
+```
+
+Both suites build synthetic plots with known ground truth and assert the recovered curves and calibration match. No copyrighted source documents are redistributed.
+
+## License
+
+MIT, see [LICENSE](LICENSE).

unplot-0.0.1/README.md

@@ -0,0 +1,125 @@
+# unplot
+
+**Read curves off a plot, straight from the vector PDF, with overlapping curves pulled apart and a confidence score on each.**
+
+**[Try the live demo →](https://somnai-dreams.github.io/unplot/)** — drop a vector PDF in your browser; nothing is uploaded.
+
+unplot is a headless library (Python and TypeScript) for digitizing line and curve plots. Interactive tools like WebPlotDigitizer, Engauge, and PlotDigitizer want you to load an image and click to calibrate the axes. unplot runs unattended instead, and does two things those tools don't:
+
+- **Vector-PDF-native.** When a PDF's curves are real drawn paths, unplot reads the exact geometry out of the file. No rasterizing, no pixel re-detection, no clicking. The numbers you get back are the numbers that were drawn.
+- **Automatic crossing separation.** Where curves overlap and cross, it keeps them apart: by stroke style or colour for vector paths, by hue for colour-coded raster images, or by de-fanning and re-chaining a single pen stroke that traces several lobes at once.
+
+Every result also carries a **confidence report**, per curve and for the set: shape-prior violations, calibration fit, coverage gaps, crossings. If a curve is suspect, the report says so.
+
+## Quick start
+
+Python:
+
+```python
+from unplot import extract, Lobe
+
+cs = extract("plot.pdf", frame=(60, 40, 360, 240),
+             prior=Lobe(0.08), expected_curves=3, order_by="peak-x")
+
+for c in cs.curves:
+    print(c.id, c.points.shape, c.qa.confidence, c.qa.passed)
+
+named = cs.labeled({0: "blue", 1: "green", 2: "red"})   # you map order to meaning
+```
+
+TypeScript, in the browser, with no Python and no server (see [`js/`](js/)):
+
+```ts
+import { extract, lobe } from "unplot";   // js/src/index.ts
+
+const data = new Uint8Array(await (await fetch("plot.pdf")).arrayBuffer());
+const cs = await extract(data, { expectedCurves: 3, prior: lobe(0.08), orderBy: "peak-x" });
+cs.curves.forEach(c => console.log(c.id, c.style.color, c.qa.confidence));
+```
+
+[`js/`](js/) also has a drop-a-PDF demo: it renders the page, overlays the recovered curves, shows the QA, and exports CSV. The bytes never leave the page.
+
+## What you get back
+
+`extract(plot) -> CurveSet`. One plot region in, one CurveSet out:
+
+- **calibrated arrays** per curve (`points`, in your axis units), plus source-space points for overlay
+- **neutral identity.** Curves come back as `c0, c1, …`, ordered deterministically by peak-x, mean-y, or first-x. unplot knows nothing about your domain; you map order to meaning.
+- **a QA report**: `CurveQA` per curve, `CurveSetQA` for the set.
+
+## Shape priors
+
+The one thing you supply is the expected shape of your curves, as a `ShapePrior`. It scores confidence, and it breaks ties at crossings by picking the continuation that keeps each curve on its own flank. Shipped priors:
+
+- `Free`: no assumption, raw geometry.
+- `Monotone(direction)`: the curve only goes one way.
+- `Lobe(tolerance)`: approximately unimodal (rise to a peak, then fall). `tolerance` is how much flank reversal is allowed before a curve is flagged, not a demand for strict unimodality, so real shoulders and double-humps survive.
+- `Smooth`: penalise spikes.
+
+Write your own by implementing `qa_violation` and `separation_bias`.
+
+## Scope
+
+Supported: vector-PDF ingest (exact geometry) and raster images (pixel fallback); linear axis calibration from numeric tick labels, robust to stray labels leaking in from a neighbouring plot; crossing separation under a shape prior; the QA report.
+
+Not yet, and PRs welcome:
+
+- **Log-spaced axes.** Calibration is linear pt-to-value. Axes whose *values* are log quantities work fine when they're drawn linearly; genuinely log-*spaced* axes are not.
+- **Many identically-styled curves on one plot.** With no colour or dash to tell them apart (e.g. a five-curve grey density plot), the separator can merge overlapping ones. The merge is detected — a `roughness` check, total y-variation over y-range — and the tangle is dropped with a warning rather than returned as a curve; cleanly-separated curves on the same plot still come back.
+- **Heavily occluded mono scans.** Colour curves separate by hue; single-colour curves separate by continuity and the shape prior, which handles clean crossings. A low-resolution mono *scan* with a weak curve buried under a stronger one can mis-assign, and the QA reports it as low confidence. Use vector ingest or a colour-coded source there.
+- Broken axis boxes, legends drawn over curves, exotic scales, automatic frame detection for raster scans.
+
+## Accuracy
+
+Peak error on synthetic ground truth, in x-axis units (the plots span x 400 to 700). From `bench/benchmark.py`, seed-fixed, 20 randomized plots per tier:
+
+| tier | median | p90 |
+|-|-|-|
+| vector, 3–4 curves, separated or crossing | 0.5–0.9 | 1.3–1.5 |
+| raster colour, 3 crossing (with or without noise) | 1.1 | 1.5 |
+| raster mono, 3 crossing | 1.0 | 1.6 |
+| raster mono, 3 occluded | 1.3 | 6.3 |
+
+Vector is essentially exact: it reads drawn geometry, so crossings and curve count don't move the number. Raster is tight on synthetic plots, around 1 unit median, with an occluded lobe (one weak curve buried under its neighbours) the harder synthetic case. The real-world hard case, a low-resolution mono scan with heavy occlusion, still degrades, and there the QA flags it rather than returning a confident wrong answer.
+
+The vector path also reproduces reference extractions of real PDFs numerically: a dash/colour-keyed plot of three overlapping curves (every peak matched exactly, peak-normalised shape RMS 0.000), and a continuous-stroke polyline carrying a real double-hump (peaks within 8 units, the substructure preserved rather than flattened).
+
+## How it compares
+
+unplot is narrower than the established tools on purpose: line and curve plots, headless, vector-native, self-reporting its own confidence, built for batch and automation rather than interactive correction. WebPlotDigitizer and Engauge are mature GUIs that cover many chart types and let a human fix mistakes live. To digitize one chart by hand, use them.
+
+| capability | unplot | WebPlotDigitizer | Engauge | PlotDigitizer |
+|-|-|-|-|-|
+| reads vector-PDF geometry | yes | no (image) | no (image) | no (image) |
+| automatic axis calibration | yes (vector) | click axes | click axes | click axes |
+| crossing separation | hue or shape prior | colour / layers | guided | manual / auto |
+| QA / confidence output | yes | no | no | no |
+| headless, scriptable batch | yes | no (web app) | no (GUI) | no |
+| other chart types (polar, bar…) | no | yes | yes | yes |
+| license | MIT | AGPL-3.0 | GPL | proprietary |
+
+On clean colour plots a head-to-head against the real WebPlotDigitizer 4.8 (its own auto-extraction, with an exact calibration set through its API) is a dead heat: both land around 0.5 to 1 unit, because both do a colour mask plus per-column averaging. unplot pulls ahead on vector PDFs, which WPD can't read at all; on noise, where its denoising rode out a case WPD's fixed threshold tripped on; and on frame removal, since WPD grabbed the black plot frame until a region was masked. WPD is the only incumbent benchmarked here. Engauge is a desktop GUI and PlotDigitizer is login-gated, so neither can be batch-run.
+
+## Install
+
+Python:
+
+```bash
+pip install unplot            # vector-PDF core + numpy
+pip install "unplot[raster]"  # adds opencv/pillow for the raster fallback
+```
+
+TypeScript: the port lives in [`js/`](js/). Run `bun install` there; the only runtime dependency is pdf.js (`pdfjs-dist`, Apache-2.0).
+
+## Tests
+
+```bash
+pip install "unplot[test]" && pytest   # Python
+cd js && bun test                           # TypeScript
+```
+
+Both suites build synthetic plots with known ground truth and assert the recovered curves and calibration match. No copyrighted source documents are redistributed.
+
+## License
+
+MIT, see [LICENSE](LICENSE).

unplot-0.0.1/bench/benchmark.py

@@ -0,0 +1,116 @@
+"""Accuracy benchmark: unplot extraction error across difficulty tiers on synthetic ground truth.
+
+No competitor here — these are absolute numbers. Each tier generates K randomized plots with known peaks
+(via PyMuPDF), extracts them, and reports the recovery rate (got the expected curve count) and the median
+peak error over recovered cases. Deterministic (fixed seed). Run: python bench/benchmark.py
+"""
+from __future__ import annotations
+
+import os
+import tempfile
+
+import fitz
+import numpy as np
+
+from unplot import Lobe, extract
+
+FRAME = (60.0, 40.0, 360.0, 240.0)
+XR, YR = (400.0, 700.0), (0.0, 2.0)
+COLORS = [(0, 0, 1), (0, 0.6, 0), (0.9, 0, 0), (0.6, 0, 0.6)]
+
+
+def x2px(x: float) -> float:
+    return FRAME[0] + (x - XR[0]) / (XR[1] - XR[0]) * (FRAME[2] - FRAME[0])
+
+
+def v2py(v: float) -> float:
+    return FRAME[3] - (v - YR[0]) / (YR[1] - YR[0]) * (FRAME[3] - FRAME[1])
+
+
+def make_pdf(peaks, sigma, amp, path, mono=False):
+    doc = fitz.open()
+    pg = doc.new_page(width=420, height=300)
+    nm = np.arange(400.0, 700.01, 2.0)
+    for k, (pk, a, s) in enumerate(zip(peaks, amp, sigma)):
+        v = a * np.exp(-0.5 * ((nm - pk) / s) ** 2)
+        pts = [fitz.Point(x2px(x), v2py(val)) for x, val in zip(nm, v)]
+        col = (0, 0, 0) if mono else COLORS[k % 4]
+        sh = pg.new_shape(); sh.draw_polyline(pts); sh.finish(color=col, width=1.4, closePath=False); sh.commit()
+    for lbl in (400, 500, 600, 700):
+        pg.insert_text(fitz.Point(x2px(lbl) - 6, FRAME[3] + 12), str(lbl), fontsize=8)
+    for lbl in (0, 1, 2):
+        pg.insert_text(fitz.Point(FRAME[0] - 16, v2py(lbl) + 3), str(lbl), fontsize=8)
+    doc.save(path); doc.close()
+
+
+def render(path, dpi, noise, rng):
+    pix = fitz.open(path)[0].get_pixmap(dpi=dpi)
+    img = np.frombuffer(pix.samples, np.uint8).reshape(pix.height, pix.width, pix.n)[..., :3].copy()
+    if noise > 0:
+        img = np.clip(img.astype(float) + rng.normal(0, noise, img.shape), 0, 255).astype(np.uint8)
+    return img
+
+
+def gen_peaks(n, mode, rng):
+    # fixed lobe width across tiers (so only spacing/amplitude vary, not the argmax-jitter from width)
+    sigma = [26.0] * n
+    spacing = 95.0 if mode == "separated" else 68.0      # crossing/occluded pack the lobes closer
+    start = rng.uniform(440, 460)
+    peaks = sorted(min(start + i * rng.uniform(spacing - 8, spacing + 8), 686.0) for i in range(n))
+    amp = [rng.uniform(1.5, 1.9) for _ in range(n)]
+    if mode == "occluded":                               # one weak lobe buried under its taller neighbours
+        amp[int(rng.integers(0, n))] *= 0.4
+    return peaks, sigma, amp
+
+
+def peak_errors(cs, truth):
+    """Per-curve |recovered peak - true peak| (nm), pairing both sorted by peak. expected_curves is set so
+    the count always matches; the error distribution is the real quality signal."""
+    rec = sorted(float(c.points[np.argmax(c.points[:, 1]), 0]) for c in cs.curves)
+    return [abs(a - b) for a, b in zip(rec, sorted(truth))]
+
+
+TIERS = [
+    ("vector · 3 separated", dict(ingest="vector", n=3, mode="separated")),
+    ("vector · 3 crossing", dict(ingest="vector", n=3, mode="crossing")),
+    ("vector · 4 crossing", dict(ingest="vector", n=4, mode="crossing")),
+    ("raster colour · 3 crossing", dict(ingest="raster", n=3, mode="crossing", dpi=200, noise=0, mono=False)),
+    ("raster colour · 3 crossing · noisy", dict(ingest="raster", n=3, mode="crossing", dpi=200, noise=18, mono=False)),
+    ("raster mono · 3 crossing", dict(ingest="raster", n=3, mode="crossing", dpi=200, noise=0, mono=True)),
+    ("raster mono · 3 occluded", dict(ingest="raster", n=3, mode="occluded", dpi=200, noise=0, mono=True)),
+]
+K = 20
+
+
+def run_tier(cfg, rng, tmp):
+    errs = []
+    for t in range(K):
+        peaks, sigma, amp = gen_peaks(cfg["n"], cfg["mode"], rng)
+        p = os.path.join(tmp, f"p{t}.pdf"); make_pdf(peaks, sigma, amp, p, cfg.get("mono", False))
+        if cfg["ingest"] == "vector":
+            cs = extract(p, frame=FRAME, prior=Lobe(0.08), expected_curves=cfg["n"], order_by="peak-x")
+        else:
+            s = cfg["dpi"] / 72.0
+            img = render(p, cfg["dpi"], cfg["noise"], rng)
+            cs = extract(img, ingest="raster", frame=tuple(v * s for v in FRAME),
+                         x_axis=[(x2px(400) * s, 400.0), (x2px(700) * s, 700.0)],
+                         y_axis=[(v2py(0) * s, 0.0), (v2py(2) * s, 2.0)],
+                         prior=Lobe(0.08), expected_curves=cfg["n"], order_by="peak-x")
+        errs += peak_errors(cs, peaks)
+    return errs
+
+
+def main():
+    rng = np.random.default_rng(7)
+    tmp = tempfile.mkdtemp()
+    print(f"unplot accuracy benchmark (K={K} plots/tier, synthetic ground truth, seed 7)")
+    print("peak error per curve, nm  (vector = exact geometry; raster = pixel floor)\n")
+    print(f"{'tier':32}{'median':>10}{'p90':>10}")
+    print("-" * 52)
+    for name, cfg in TIERS:
+        errs = np.array(run_tier(cfg, rng, tmp))
+        print(f"{name:32}{np.median(errs):>8.1f}  {np.percentile(errs, 90):>8.1f}")
+
+
+if __name__ == "__main__":
+    main()

unplot-0.0.1/compare/INSTRUCTIONS.md

@@ -0,0 +1,52 @@
+# Manual head-to-head: digitize these plots in WebPlotDigitizer / Engauge
+
+unplot runs automatically in the scorer. The interactive tools (WPD, Engauge) can't be scripted, so this
+is the one part that needs a human. Do as many plots/tools as you have patience for — even one is useful.
+
+## The plots (`compare/plots/`)
+
+Each plot is provided as a **PNG** (load this into the GUI tools) and a **PDF** (unplot reads this for its
+vector path). Same axes on all: **x = 400…700, y = 0…2**, with tick labels drawn for calibration.
+
+|file|curves|colours (left→right by peak)|
+|-|-|-|
+|`p1_single`|1|black|
+|`p2_three_separated`|3|blue, green, red|
+|`p3_three_crossing`|3|blue, green, red|
+|`p4_three_noisy`|3|blue, green, red (with image noise)|
+
+## Steps (per plot, per tool)
+
+1. Load the **PNG** into WebPlotDigitizer ([apps.automeris.io](https://apps.automeris.io)) or Engauge.
+2. **Calibrate the axes** by clicking known points: on the x-axis click the **400** and **700** ticks; on
+   the y-axis click the **0** and **2** ticks. Enter those values when prompted.
+3. **Digitize each curve.** For the 3-curve plots, do each colour separately (WPD: add a dataset per colour
+   and use *Automatic Extraction → Color*; Engauge: a curve per colour with *Segment Fill*). Use the
+   automatic tracer where it works — that's the tool's strength.
+4. **Export** each curve as CSV (two columns: x then y, in data units).
+
+## Where to put the exports
+
+Save one CSV per curve, named `<plot>__c<index>.csv`, indexed **left→right by peak** (so c0 = blue, c1 =
+green, c2 = red), under the tool's folder:
+
+```
+compare/submissions/wpd/p2_three_separated__c0.csv
+compare/submissions/wpd/p2_three_separated__c1.csv
+compare/submissions/engauge/p3_three_crossing__c0.csv
+...
+```
+
+CSV format is forgiving — comma or whitespace separated, header lines are skipped.
+
+## Score it
+
+```bash
+python compare/score.py
+```
+
+It runs unplot (vector + raster) on every plot and folds in whatever competitor CSVs you've added,
+reporting mean peak error and mean y-RMS per curve against ground truth (in x/y axis units). Re-run
+anytime you add more.
+
+(Regenerate the plots with `python compare/make_plots.py` if needed — deterministic, no randomness.)