inkmap 0.1.2__tar.gz → 0.1.4__tar.gz

inkmap-0.1.4/.claude/skills/inkmap-dev-validation/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: inkmap-dev-validation
+description: Read before changing anything in inkmap that could move a number — geometry, coverage rasterisation, refinement, blur estimation, measurement weighting, or a locator — and before regenerating docs/methods-and-results.md or docs/validation.md. Covers the three validation tiers (synthetic ground truth, real-photograph round-trip, corpus detection), how to run each, which numbers live in which document, and the half-pixel convention failures that any of these changes can silently reintroduce. Triggers on "regenerate the benchmarks", "update the validation numbers", "the report is stale", "did that change accuracy", or any edit to coverage.py / geometry.py / models/ / locate/.
+metadata:
+  audience: developers
+  project: inkmap
+---
+
+# Validating inkmap
+
+Three tiers, answering three different questions. Changing anything geometric means
+re-running at least tiers 1 and 2, because the failure mode here is *silent*: a wrong
+mask still looks like a mask.
+
+| Tier | Question | Ground truth | Script |
+|---|---|---|---|
+| 1. Synthetic | Is the coverage value *correct*? | exact, by construction | `scripts/validate.py` |
+| 2. Round-trip | Is the geometry right on *real* photos? | an independent decoder | `scripts/evaluate.py` |
+| 3. Corpus | Does detection survive the real world? | none (rates only) | `scripts/corpus_eval.py` |
+
+## Tier 1 — synthetic, exact
+
+```bash
+python scripts/validate.py > /tmp/validation.md
+```
+
+No network, ~2 minutes. Produces the geometric-accuracy, coverage-MAE,
+photometric-bias and blur-estimation tables in `docs/validation.md`.
+
+**Why it can be exact:** `synth.render` builds the image *from* the coverage map —
+supersample the model through a known transform, then form the image as
+`255 * (1 - coverage)`. Ground truth and stimulus are the same object, so degradations
+applied afterwards leave the truth correct. `test_scene_ground_truth_is_self_consistent`
+guards that property; if it fails, every number in tier 1 is meaningless.
+
+## Tier 2 — round-trip on real photographs
+
+```bash
+python scripts/evaluate.py <corpus_root> eval.json
+```
+
+`<corpus_root>` holds `qr/`, `barcode/`, `text/` subfolders of real images.
+
+**The trick:** no per-pixel ground truth exists for real photographs, so instead sample
+the model through inkmap's *own* fitted transform, re-render it clean, and hand it to a
+decoder. The decoder was not involved in fitting the geometry and has error correction,
+so it does not accept near-misses.
+
+**Calibrated sensitivity** (measured, and worth re-checking if you touch sampling):
+round-trip passes at ≤0.25 units of transform error and fails at ≥0.5. So it certifies
+"within a quarter of a unit", not "perfect". Do not oversell it.
+
+Also computed: independent-model agreement (our sampled QR matrix vs OpenCV's separate
+rectification) and class separation (background minus foreground grey level, which
+collapses if the mask is misaligned).
+
+## Tier 3 — corpus detection rates
+
+```bash
+python scripts/corpus_eval.py
+```
+
+Fetches and caches ~189 CC-licensed Commons photographs on first run (several minutes;
+Commons rate-limits and the fetcher backs off). Produces the per-locator detection table.
+
+## What lives where
+
+- `docs/validation.md` — the numbers, all tiers. Regenerate wholesale; do not hand-edit
+  a table, or it will drift from the script that claims to produce it.
+- `docs/methods-and-results.md` — the narrative: approach, algorithms, results, limits.
+  The published report; also the source of the PDF.
+- `README.md` — only the headline photometric-bias table and the detection rates. If you
+  change those numbers, update the README too; there is no automation tying them.
+
+Rebuild the PDF after editing the report:
+
+```bash
+python scripts/build_report.py
+```
+
+## The failure this all exists to catch
+
+Three half-pixel conventions have to agree, and each is invisible on inspection:
+
+1. **Pixel centre vs corner** — OpenCV's integer coordinate `x` is the *centre* of a
+   pixel spanning `[x-0.5, x+0.5)`. Rasterising `[x, x+1)` offsets the whole map half a
+   pixel.
+2. **The ECC template raster** — a model rendered at `s` px/unit puts template pixel `t`
+   over `[t/s, (t+1)/s)`, so its centre is `(t+0.5)/s`.
+3. **Locator corner conventions differ** — OpenCV's QR corners are the last *contained*
+   pixel index; zxing-cpp returns the continuous outer boundary.
+
+Getting these wrong cost 50× in accuracy during development. **The diagnostic:** if
+refinement error grows with the mark's rotation angle following `R(d) − d`, the residual
+`d` is a coordinate-convention offset, not noise. `test_rotation_does_not_scramble_the_model`
+is the regression test; it is parameterised over eight angles precisely because the bug
+is invisible at 0°.
+
+A fourth, related trap: the ECC template needs a rendered clear margin. Blurring a
+template that stops at the mark's edge makes the kernel reflect interior content across
+the border, inventing an edge profile the photograph does not have — ECC then shifts the
+whole fit to match the artefact (~0.45 px).
+
+## Before you claim an improvement
+
+- Run the full test suite; `tests/test_inkmap.py` is parameterised across model kinds
+  (matrix, bars, raster, polygon, glyph) on purpose — a change that helps QR and breaks
+  glyphs is not an improvement.
+- Re-run tier 1 and compare tables, not vibes.
+- Check that `measurability` still refuses the cases it should. Making more images
+  "measurable" is a regression unless the bias table improved with it.

{inkmap-0.1.2 → inkmap-0.1.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: inkmap
-Version: 0.1.2
+Version: 0.1.4
 Summary: Per-pixel foreground coverage for photographed marks -- QR, barcodes, text, any shape you can model
 Project-URL: Homepage, https://github.com/thorwhalen/inkmap
 Author: Thor Whalen
@@ -159,24 +159,73 @@ and medical-imaging vocabulary: [docs/terminology.md](docs/terminology.md).
 
 ## How it works
 
+```
+photograph ──► locate ──► recover model ──► refine transform ──► rasterise ──► erode
+```
+
 1. **Locate** — a cascade of `zxing-cpp`, OpenCV's Aruco-based QR detector and OpenCV's
    classic detector, plus linear barcodes. On 189 real photographs: zxing 74%, aruco
    68%, OpenCV 43%, **union 80%**. For marks nothing can auto-detect, `inkmap.place()`
    takes the corners from you.
 2. **Recover the model** — from a bit-exact rectification where a decoder offers one,
    otherwise sampled from the image. *Never* by re-encoding a decoded payload:
-   error-correction level and mask pattern are not recoverable from the text, so
-   re-encoding can silently produce a different pattern.
+   error-correction level, mask pattern and code-set choices are not recoverable from
+   the text, so re-encoding can silently produce a different pattern.
 3. **Refine** — align the rendered model to the photograph with ECC. Four locator
    corners are four observations; the model has thousands. Takes corner error from
-   ~1 px to **0.02–0.03 px**.
+   ~1 px to **0.02–0.03 px** (4–53× depending on conditions).
 4. **Rasterise** — supersample each pixel, back-project through the transform, ask the
-   model. Exact up to quantisation, and independent of lighting.
-5. **Erode to a weight** — by 2–3× the estimated blur σ.
+   model `occupancy(u, v)`. Exact up to the supersampling rate, and independent of
+   lighting. Coverage MAE against exact ground truth is **0.0000–0.0005**.
+5. **Erode to a weight** — by ~2× the estimated blur σ, because geometric purity is not
+   enough (see the table above).
 
 Decoding is optional throughout. A mark whose material barely deposited will not
 decode, and that is exactly the case that must still work.
 
+Sub-pixel geometry turns out to hinge on **three half-pixel conventions agreeing** —
+pixel-centre vs pixel-corner rasterisation, the template raster, and the fact that
+different locators disagree about what a "corner" is. Getting them wrong cost 50× in
+accuracy during development, and none of it is visible on inspection: the mask still
+looks like a mask. The diagnostic, if you ever chase this: *if the error grows with the
+mark's rotation angle following `R(d) − d`, the residual `d` is a convention offset, not
+noise.*
+
+## How well it works
+
+Validated three ways, because no single way is sufficient — synthetic scenes (exact
+ground truth by construction), real photographs (round-trip through an independent
+decoder), and DIBCO (hand-labelled per-pixel ink truth).
+
+| | detection | round-trip geometry | round-trip when *measurable* |
+|---|---|---|---|
+| **QR** (189 real photos) | 80% | 77% | **96%** |
+| **Barcode** (56 real photos) | 95% | 48% | **89%** |
+| **Text** (86 real words) | — (no locator; you supply the quad) | — | see below |
+
+The conditional matters: **when inkmap judges an image measurable, an independent decoder
+confirms the geometry 96% of the time.** Failures concentrate where the library already
+says not to trust it.
+
+On **real ink with hand-labelled ground truth** (DIBCO), eroding a *perfect* mask by one
+pixel shifts the measured foreground mean by **17% of the foreground/background
+contrast** — so the contamination argument is not an artefact of synthetic data.
+
+**Text is the honest weak spot.** Placement works (IoU 0.76 with an image-derived shape)
+but a glyph model with the wrong font does not (IoU 0.17). Measured directly: with the
+correct font IoU is 0.997–1.000; with a wrong one, 0.46–0.80. For text, pass the actual
+font or take the shape from the image.
+
+📄 **[Methods and results](docs/methods-and-results.md)** ([PDF](docs/methods-and-results.pdf))
+— the full write-up: approach, algorithms, every number, the datasets, the limits, and a
+barcode defect the evaluation caught and forced a fix for (round-trip 5% → 48%).
+
+## Large photographs: locate coarse, refine fine
+
+Locating is a large share of the cost on big frames and scales with pixel count, so `find_all(photo, locate_scale=0.5)` (or `locate(bgr, gray, scale=0.5)`) runs the detectors on an `INTER_AREA`-downscaled copy and maps the placements back to full resolution; refinement then pins them to sub-pixel accuracy as usual, so coverage maps match the full-resolution ones. On a 4000 x 3000 photograph of a page with 8 QR codes, locating took 1,129 ms at full resolution, 288 ms at 0.5 and 152 ms at 0.35, with all 8 codes found and decoded (on a slower 2-core server, a synthetic page of the same size: 11.6 s, 2.5 s and 1.1 s).
+
+Use it when your codes are large in the frame: a code's modules should still span about 4 px after downscaling (`config.MIN_COARSE_PIXELS_PER_FEATURE`), i.e. 8 px at full resolution for 0.5 and about 11.5 px for 0.35. Below that the module count and pattern read off the small frame go wrong even though the code still decodes (at 2 px a 25 x 25 QR reads as 21 x 21), and refinement cannot repair a wrong model. So, with `full_res_retry=True` (the default), any coarse placement under that floor, or found but not decoded, is re-located on a full-resolution crop around it (`metadata["locate_retry"]` says why). The crops are small, but if every code needs one the speedup is gone, so pick the scale from your smallest code. With `full_res_retry=False`, placements under the floor are kept and marked `metadata["locate_undersampled"] = True`; do not trust their model. Custom locators run on the downscaled frame and must return coordinates in the frame they are given. A code the coarse pass misses entirely is not recovered, so lower the downscaling instead. The default, `None`, locates at full resolution exactly as before.
+
 ## Extending it
 
 ```python
@@ -187,15 +236,25 @@ inkmap.find(photo, locators=["mine", "qr_zxing"])
 Tunable defaults live in `inkmap.config` — supersampling, ECC parameters, erosion
 margin, saturation levels — as documented constants rather than inline magic numbers.
 
+## Skills for AI agents
+
+If you drive inkmap from an agent, the shipped skill
+[`inkmap-usage`](inkmap/data/skills/inkmap-usage/SKILL.md) is the short version of
+everything that is easy to get wrong: choosing a model, the corner-order trap, which of
+the three 0–1 channels to use for what, and gating on measurability. Install it with
+[`skill`](https://github.com/thorwhalen/skill), or just read it.
+
 ## Test data
 
-189 real photographs of marks in the wild (CC0 / public domain / CC BY / CC BY-SA),
-fetched on demand and cached:
+384 real photographs of marks in the wild — 189 QR, 56 barcodes, 139 printed text —
+(CC0 / public domain / CC BY / CC BY-SA), fetched on demand and cached:
 
 ```python
-from inkmap import data
-paths = data.fetch()
-print(data.attribution_text())
+from inkmap import corpus
+
+corpus.kinds()                        # {'qr': 189, 'barcode': 56, 'text': 139}
+paths = corpus.fetch(kind="barcode")
+print(corpus.attribution_text())      # attribution is required for CC BY / CC BY-SA
 ```
 
 Synthetic scenes with **exact** ground-truth coverage — the only way to validate a 0–1

{inkmap-0.1.2 → inkmap-0.1.4}/README.md

@@ -126,24 +126,73 @@ and medical-imaging vocabulary: [docs/terminology.md](docs/terminology.md).
 
 ## How it works
 
+```
+photograph ──► locate ──► recover model ──► refine transform ──► rasterise ──► erode
+```
+
 1. **Locate** — a cascade of `zxing-cpp`, OpenCV's Aruco-based QR detector and OpenCV's
    classic detector, plus linear barcodes. On 189 real photographs: zxing 74%, aruco
    68%, OpenCV 43%, **union 80%**. For marks nothing can auto-detect, `inkmap.place()`
    takes the corners from you.
 2. **Recover the model** — from a bit-exact rectification where a decoder offers one,
    otherwise sampled from the image. *Never* by re-encoding a decoded payload:
-   error-correction level and mask pattern are not recoverable from the text, so
-   re-encoding can silently produce a different pattern.
+   error-correction level, mask pattern and code-set choices are not recoverable from
+   the text, so re-encoding can silently produce a different pattern.
 3. **Refine** — align the rendered model to the photograph with ECC. Four locator
    corners are four observations; the model has thousands. Takes corner error from
-   ~1 px to **0.02–0.03 px**.
+   ~1 px to **0.02–0.03 px** (4–53× depending on conditions).
 4. **Rasterise** — supersample each pixel, back-project through the transform, ask the
-   model. Exact up to quantisation, and independent of lighting.
-5. **Erode to a weight** — by 2–3× the estimated blur σ.
+   model `occupancy(u, v)`. Exact up to the supersampling rate, and independent of
+   lighting. Coverage MAE against exact ground truth is **0.0000–0.0005**.
+5. **Erode to a weight** — by ~2× the estimated blur σ, because geometric purity is not
+   enough (see the table above).
 
 Decoding is optional throughout. A mark whose material barely deposited will not
 decode, and that is exactly the case that must still work.
 
+Sub-pixel geometry turns out to hinge on **three half-pixel conventions agreeing** —
+pixel-centre vs pixel-corner rasterisation, the template raster, and the fact that
+different locators disagree about what a "corner" is. Getting them wrong cost 50× in
+accuracy during development, and none of it is visible on inspection: the mask still
+looks like a mask. The diagnostic, if you ever chase this: *if the error grows with the
+mark's rotation angle following `R(d) − d`, the residual `d` is a convention offset, not
+noise.*
+
+## How well it works
+
+Validated three ways, because no single way is sufficient — synthetic scenes (exact
+ground truth by construction), real photographs (round-trip through an independent
+decoder), and DIBCO (hand-labelled per-pixel ink truth).
+
+| | detection | round-trip geometry | round-trip when *measurable* |
+|---|---|---|---|
+| **QR** (189 real photos) | 80% | 77% | **96%** |
+| **Barcode** (56 real photos) | 95% | 48% | **89%** |
+| **Text** (86 real words) | — (no locator; you supply the quad) | — | see below |
+
+The conditional matters: **when inkmap judges an image measurable, an independent decoder
+confirms the geometry 96% of the time.** Failures concentrate where the library already
+says not to trust it.
+
+On **real ink with hand-labelled ground truth** (DIBCO), eroding a *perfect* mask by one
+pixel shifts the measured foreground mean by **17% of the foreground/background
+contrast** — so the contamination argument is not an artefact of synthetic data.
+
+**Text is the honest weak spot.** Placement works (IoU 0.76 with an image-derived shape)
+but a glyph model with the wrong font does not (IoU 0.17). Measured directly: with the
+correct font IoU is 0.997–1.000; with a wrong one, 0.46–0.80. For text, pass the actual
+font or take the shape from the image.
+
+📄 **[Methods and results](docs/methods-and-results.md)** ([PDF](docs/methods-and-results.pdf))
+— the full write-up: approach, algorithms, every number, the datasets, the limits, and a
+barcode defect the evaluation caught and forced a fix for (round-trip 5% → 48%).
+
+## Large photographs: locate coarse, refine fine
+
+Locating is a large share of the cost on big frames and scales with pixel count, so `find_all(photo, locate_scale=0.5)` (or `locate(bgr, gray, scale=0.5)`) runs the detectors on an `INTER_AREA`-downscaled copy and maps the placements back to full resolution; refinement then pins them to sub-pixel accuracy as usual, so coverage maps match the full-resolution ones. On a 4000 x 3000 photograph of a page with 8 QR codes, locating took 1,129 ms at full resolution, 288 ms at 0.5 and 152 ms at 0.35, with all 8 codes found and decoded (on a slower 2-core server, a synthetic page of the same size: 11.6 s, 2.5 s and 1.1 s).
+
+Use it when your codes are large in the frame: a code's modules should still span about 4 px after downscaling (`config.MIN_COARSE_PIXELS_PER_FEATURE`), i.e. 8 px at full resolution for 0.5 and about 11.5 px for 0.35. Below that the module count and pattern read off the small frame go wrong even though the code still decodes (at 2 px a 25 x 25 QR reads as 21 x 21), and refinement cannot repair a wrong model. So, with `full_res_retry=True` (the default), any coarse placement under that floor, or found but not decoded, is re-located on a full-resolution crop around it (`metadata["locate_retry"]` says why). The crops are small, but if every code needs one the speedup is gone, so pick the scale from your smallest code. With `full_res_retry=False`, placements under the floor are kept and marked `metadata["locate_undersampled"] = True`; do not trust their model. Custom locators run on the downscaled frame and must return coordinates in the frame they are given. A code the coarse pass misses entirely is not recovered, so lower the downscaling instead. The default, `None`, locates at full resolution exactly as before.
+
 ## Extending it
 
 ```python
@@ -154,15 +203,25 @@ inkmap.find(photo, locators=["mine", "qr_zxing"])
 Tunable defaults live in `inkmap.config` — supersampling, ECC parameters, erosion
 margin, saturation levels — as documented constants rather than inline magic numbers.
 
+## Skills for AI agents
+
+If you drive inkmap from an agent, the shipped skill
+[`inkmap-usage`](inkmap/data/skills/inkmap-usage/SKILL.md) is the short version of
+everything that is easy to get wrong: choosing a model, the corner-order trap, which of
+the three 0–1 channels to use for what, and gating on measurability. Install it with
+[`skill`](https://github.com/thorwhalen/skill), or just read it.
+
 ## Test data
 
-189 real photographs of marks in the wild (CC0 / public domain / CC BY / CC BY-SA),
-fetched on demand and cached:
+384 real photographs of marks in the wild — 189 QR, 56 barcodes, 139 printed text —
+(CC0 / public domain / CC BY / CC BY-SA), fetched on demand and cached:
 
 ```python
-from inkmap import data
-paths = data.fetch()
-print(data.attribution_text())
+from inkmap import corpus
+
+corpus.kinds()                        # {'qr': 189, 'barcode': 56, 'text': 139}
+paths = corpus.fetch(kind="barcode")
+print(corpus.attribution_text())      # attribution is required for CC BY / CC BY-SA
 ```
 
 Synthetic scenes with **exact** ground-truth coverage — the only way to validate a 0–1