The Image Structure Reader

1What the instrument is

The Image Structure Reader (ISR) computes fields — luminance gradient, OKLab chroma, cone-opponent channels, committed and soft edges, structural mass — over a whole image, then reads named regions and their relations as one system in one coordinate space. It recognises nothing: no objects, no learned weights, no training data. Every quantity is a deterministic function of the pixels.

The system has four layers, each built on the one below:

• Evidence fields — nine per-pixel fields, the substrate from which all measurements are derived.
• The spine — read_image(), one call returning the full structural report (schema v0.8).
• Lenses & independent tools — pointable instruments outside the spine: the accent lens, stance, the layered delta, small-corpus compare, absolute position.
• The pattern shelf & candidate register — reusable analysis moves and not-yet-promoted measures, with the machinery that decides what ever enters the spine.

Why Deterministic? The Image Structure Reader is deterministic because its purpose is not recognition but measurement.

Every reported quantity is a reproducible function of a stated image, a stated resolution, and a stated pipeline. The same input produces the same coordinates. If a value changes, the reason can be traced to a different reproduction, a different scale window, a different parameter, or a different implementation. There are no learned weights, hidden state, or stochastic inference paths inside the instrument.

This design deliberately sacrifices expressive power. A trained model can infer identity, style, or likely intent from large statistical priors. The ISR cannot. It will never identify Christ, recognize Pollock, or infer that a photograph depicts a train station. Those questions belong to semantic systems.

The trade is intentional.

A deterministic instrument can be audited at every stage. Every coordinate can be followed backward to the evidence fields from which it was computed. Every disagreement between two readings can be localized to a specific subsystem rather than attributed to opaque model behavior. Calibration is possible because the underlying computations remain fixed as the corpus grows.

Determinism also separates measurement from interpretation. The instrument produces coordinates describing structural organization. Interpretation remains outside the pipeline. A critic, historian, scientist, or conservator may attach different meanings to the same coordinates, but the coordinates themselves remain unchanged.

This distinction matters because reproducibility is a prerequisite for cumulative knowledge. Studies separated by years, domains, or investigators can be compared directly only if the coordinate system itself is stable. The candidate register, calibration suite, theorem anchors, and documented instrument findings all exist to preserve that stability while allowing the library to evolve.

Determinism should therefore not be read as a claim that deterministic methods are universally superior to learned systems. The two answer different questions. Learned models excel at recognition, prediction, and semantic inference. The Image Structure Reader is designed for a narrower purpose: to produce inspectable structural coordinates whose provenance can always be traced back to the pixels from which they were derived.

2What it is not

• Not semantic. It cannot tell a body from bark (finding C-1: a measured structural anomaly in a Degas resolved into a documented figure only via external scholarship — the instrument pointed, it could not name). Pose, gaze, and identity sit above the pre-semantic ceiling by design.
• Not a quality score. No metric measures aesthetic value, correctness, or intent. The state classifier emits legible labels (counterweighted, diffuse_field…), never grades.
• Not a verdict, and it presumes purpose. Distinct from the ceiling above: even the structural read it does produce treats the work as if its structure was intended, and reports what is there as though it were chosen. That presumption cannot be falsified from inside the tool, least of all on a work with no prior (a black square has no baseline to push against, and probability will fill the gap with confident numbers). So every read is analysis, not verdict, and not every analysis is truth; a successful output is not comprehension. "Done with purpose, and the result is xyz" is a frame the instrument brings, not a finding it establishes. The guardrail is the reader on both ends: the eye and research before the run, complete and visible revision after (see the entry protocol).
• Not an AI detector or an authenticator. Choice/default readings (stance torque, default gravity) describe where an image sits relative to known attractors; generated images cluster in certain regions, but so does deliberately stable art. Box-counting D is a descriptive coordinate, never an authentication statistic.
• Not a measurement of the physical object. Every reading is of (object × reproduction chain × scale window). A photograph of a painting is not the painting (finding I-10), and the document says which reproduction and resolution every number came from.
• Not a theory of composition. The instrument carries no encoded thesis about what works "should" show. Each work lands where the deterministic pipeline puts it.

3Layer one — the evidence fields

evidence_fields(rgb) returns nine aligned per-pixel fields. The first four form the primary evidence fields that regions are read against; the rest are supplementary substrates for specific measures.

Optional preprocessing: perona_malik anisotropic diffusion for contaminated reproductions — run as a diagnostic first (the report's pm_verdict); treat only when noise is between you and the work, never when texture is the medium (I-11).

The preshelf — luminance substrate (Round 18)

The luminance field is the front-end every luminance-derived measure (edge, tone, mass, and downstream the kernel, islands, accents, τ, and β's spatial gate) is built on. It defaults to Rec. 709 luma on gamma-encoded sRGB — a display transfer, not a retinal one. The preshelf is where that substrate becomes a toggle. It is the mirror of the pattern shelf: a shelf item is a back-end consultation computed from the fields; a preshelf item is a front-end transform that changes the input before the spine reads it, so one toggle re-colours every downstream reading at once. It is set once, at the front (evidence_fields(image, substrate=…), threaded through read_image, island_structure, gap_lens, and isr read --substrate); do not reimplement it per call.

4Layer two — the spine

read_image(image) — equivalently isr read — runs a single region pass (watershed islands on the density field) so that kernel coordinates, evidence measures, relations, and the state classifier all operate on the same regions, then assembles the full report. Schema image-structure-reader/v0.8. Full definitions, ranges, calibration values, and per-metric caveats live in instrument/docs/METRICS.md — this table is the map, not the dictionary.

The Round-17 consolidation lifted six readings from the parent Saltimbanques instrument (this reference describes the present state; the lift decisions, the bolt-on-vs-invasive analysis, and the history live in CONSOLIDATION.md and CHANGES.md Round 17): three always-on (notan, scanpath, construction) and an opt-in epistemic layer under include_consensus=True. The default read is otherwise unchanged.

5Layer three — lenses & independent tools

6Layer four — the pattern shelf

Runnable, general analysis moves in toolkit/patterns/ — born in studies, generalised so the next study doesn't rediscover them. Each depends only on the instrument and takes any image.

That last clause is an intention the library has failed four times (I-28). Studies have rebuilt chromatic_boundary_independence and void_topology_chi (both already in the spine), and local_contrast_ratio and hue_tension (both already on this shelf since 2026-07-02, re-ported from the same source notebook). The cause is a wording bug, not carelessness: the entry protocol said to check "before inventing an analysis," and every one of the four was a port from a legacy notebook, which does not read as inventing. The cost is not duplicated effort but wrong numbers — one hand-rolled re-implementation used a different normalisation and manufactured 46 phantom void bodies where the spine's returns 0. The rule now covers invent, port, or hand-roll, and sits in Step 0; this table and toolkit/CATALOG.md are the indexes to grep.

The shelf answers with less authority than the spine, so check it before deferring to it (I-28, sharpened 2026-07-22). Two patterns here carried latent defects, and both were found the same way — by running them against an input whose answer was known in advance (I-24). local_contrast_ratio returned a per-image min-max normalised field, render-only, which collapsed a 4.8× discrimination to 1.3×. hue_tension applied a relative chroma floor, so what survived it depended on how much of the canvas was coloured rather than on what was coloured; on a full-bleed two-colour field it emptied its own mask and reported "monochrome pole" for a full warm/cool standoff. In both cases the rule-breaking study's own port was the better measure. The pattern is not that the shelf is untested — address.py has 17 consumer scripts, null_control.py 11, r_spatial.py 7, and those have been pressured hard in use (a real bug was found and fixed inside null_control, and r_spatial's Soejima battery included a no-false-positive-on-an-unstructured-field check). It is that both failures were patterns no study had ever run, while the catalog gave them the same standing as the exercised ones. Every shelf row now carries an exercise status; three read never run. What is true of the whole shelf is only that no pattern has a frozen test — that discipline exists for the spine alone (smoke 7/7, calibration 8/8), and shelf validation lives in lab books rather than in anything that re-runs.

Beyond the shelf: per-study probe batteries (the Degas weave, the Pollock phrase-grammar chain, the Caravaggio literature counter-tests, the Soejima corpus design, the Klimt maneuvers) are catalogued with reproducibility status in toolkit/CATALOG.md — patterns to adapt, not answers to confirm.

7The candidate register

The spine is shared; everything past it is per-image and therefore lossy — a measure discovered in one study doesn't automatically run in the next. toolkit/CANDIDATES.md is the shared path out of the spine: every not-yet-promoted measure, its accumulating corpus table, and an explicit promotion bar. The protocol: run the candidate battery on every new study and append the values in the same commit. Promotion is decided across the accumulated corpus, never by the study that discovered the measure.

8Calibration & validation

The instrument is anchored, where possible, to objects whose structure class is a theorem — the only ground truth that cannot argue back.

These orderings are frozen in instrument/tests/calibration.py (run before changing fields/stance/delta code) alongside the four-check smoke test. The triptych generator ships in instrument/examples/, so the anchors are reproducible forever. Beyond theorem anchors, the corpus itself (§14) provides cross-validated reference points — including one external confirmation, where a measured structural anomaly resolved into a museum-documented figure.

9Epistemics — how to read the numbers

The instrument is deterministic; the discipline is in the reading. These rules were each earned by a documented correction, and they are what separates a reading from a story fitted to numbers.

Know when you are measuring the tool, not the work (I-15)

A whole-image scalar has purchase on some works and floats on others — the same metric can grip one image and read only global statistics on the next. Two ways to tell: the eye (peripheral pull has nothing to grip on a flat, centred image — set it aside on sight), and the null check (a number that reproduces under matched-statistics scrambling is reading the work's statistics, not its arrangement). This is a per-work judgment, never a verdict stamped on a metric.

Null controls, seed-swept

Phase-scramble and patch-shuffle bracket the question: survives both → distributional; dies on both → needs the intact composition. But null values are seed-chaotic for some metrics, so single draws flip on luck — use null_sweep and read the distribution (stability of the real value vs scatter of the nulls, or the empirical percentile at n≥100). Null tightness is also image-class-dependent — generated images produced scramble distributions roughly 3× wider than paintings' — so percentile thresholds do not transfer across classes without checking.

The reproduction is not the work (I-10)

Every measurement is of (object × reproduction chain × scale window). Dense-area measures survive resolution sweeps; thin-structure measures do not. Report numbers with their resolution and physical scale window; compare across images only with sweep-robust measures or matched windows. Crops are different measurements. A claim that hasn't survived a resolution sweep is a reading aid.

Pre-register, then measure (Step 0)

Before the first command: look at the image and say what you see in words; write what you expect each key metric to say and why; name which metrics won't grip this work; carry no target. Then the numbers test a hypothesis instead of seeding a narrative — a surprise you predicted against is a finding; a surprise rationalised afterward is a story. The lab book is built first; the critique does not start until the reading is solid.

Claim discipline

Foreground large, directional findings; a result hinging on a hairline threshold is a reading aid. Label claim strength (pipeline-stable / narrowed / reading aid). When a result surprises — especially a null — look under it before believing it. "Only/never" claims are checked against the register's full corpus. Failures are findings and stay on the record; corrections are appended, never erased. Every critique ends with What This Does Not Prove. A finding is about a measurement: correct a number in one sentence and carry on. A thread's own conduct becomes a finding only when it changed, or came near to changing, a number, and is then logged once with its evidence and no running count — an inflated correction is as much an overclaim as an inflated result.

10The thirty-four instrument findings

Cross-cutting lessons earned by the studies — each cost a real correction. Full accounts in OBSERVATIONS.md; the traps are operationalised in AGENTS.md.

11Trust conditions & working envelope

When to trust a read — by image type

Working scales

Several subsystems pin an internal resolution so their calibrated constants hold; numbers are not comparable across pipelines or scales without noting these.

Performance: a spine read is ≈45 s without the persistence pass, ≈2–3 min with it; stance ≈2 s; a 100-seed null sweep of an address-type metric ≈8 min. Iterate with --no-persistence, finish complete.

Reproductions & rights

The corpus mixes public-domain museum captures (measured and publishable freely) with in-copyright works measured under private structural research. Working practice: measurement and the private record are unrestricted; publication carries only derived outputs — coordinates, overlays, charts — never a republished protected image. Every study states its source, resolution, and pipeline so the reproduction chain is on the record (I-10).

12How to use it

Environment

# the library ships a virtualenv (system python may lack scipy/scikit-image)
VENV=instrument/.venv/bin/python        # or: pip install -e instrument
$VENV instrument/tests/smoke.py         # 7 checks, incl. 16/16 fixture accents
$VENV instrument/tests/calibration.py   # theorem-anchored orderings

The reading workflow

Step 0 first (§9: look, pre-register, name what won't grip, no target) — then:

# 1. Condition check: frame/mat? key? medium? Run the PM *diagnostic* if dark-keyed.
# 2. Full read (iterate fast, finish complete):
cd instrument
PYTHONPATH=. .venv/bin/python -m isr read IMG -o report.json --no-persistence   # ~45 s
PYTHONPATH=. .venv/bin/python -m isr read IMG -o report_full.json               # final, ~2–3 min

# 3. Look at what the instrument sees — against the reproduction:
PYTHONPATH=. .venv/bin/python -m isr island-readout IMG -o islands.png
PYTHONPATH=. .venv/bin/python -m isr gap-readout IMG -o gap.png     # + --accent-channel chromatic --coalesce-sigma 6
PYTHONPATH=. .venv/bin/python -m isr render IMG -o fields.png

# 4. Independent tools as the image merits:
PYTHONPATH=. .venv/bin/python -m isr stance IMG
PYTHONPATH=. .venv/bin/python -m isr compare A B C -o out/ --labels "a,b,c"

# 5. Candidate battery — log the values to toolkit/CANDIDATES.md, same commit:
cd ../toolkit/patterns
PYTHONPATH=../../instrument ../../instrument/.venv/bin/python r_spatial.py IMG
PYTHONPATH=../../instrument ../../instrument/.venv/bin/python address.py IMG   # + null_sweep it

Python API

from isr import read_image                  # the spine (dict, schema v0.8)
from isr.gap import gap_lens                # accents: accent_channel=, coalesce_sigma=
from isr.stance import stance_read          # torque / SCI / VCLI-G
from isr.delta import layered_delta         # pairwise NCD × form
from isr.measures import zone_read          # I-4 mask-to-mass zone reads
from isr.fields import evidence_fields      # the raw substrate

House rules

• Core instrument code stays untouched; tune at the call site. One-off scripts go to the study folder, never into core.
• Interpret every number through instrument/docs/METRICS.md — ranges, calibration values, and the caveat attached to each metric. Never from key names alone.
• Run the candidate battery per study; append values to the register in the same commit.
• Lab book first; critique only after the reading is solid. End with What This Does Not Prove.
• Failures are findings — logged, not deleted. Every claim traces to a measurement, and placement is verified against the pixels before interpretation.
• A finding is about a measurement. Correct a number in one sentence and carry on; a thread's own conduct is a finding only when it changed, or nearly changed, a number, and then it is logged once with no running count.

Full agent-facing protocol: AGENTS.md (Step 0, workflow, traps, appropriate-use conditions). Capability menu: TOOLS.md. Critique method: skills/isr-critique/.

13The surrounding ecosystem

The ISR is the evidence half of a two-part system, and part of its definition is what sits deliberately outside it. Pointers and capability notes live in POINTERS.md and TOOLS.md §D.

14The corpus

Sixteen studies across four domains — thirteen deep single-work reads, a matched painting pair, one born-digital pair, and one 48-frame within-engine ensemble — all in one coordinate space; each has a lab book (the record) and a critique (the essay), with corrections and retractions on the record. Together they are the instrument's empirical calibration — every reference value in the metric dictionary traces to one of them.

15Current state & open threads

Open threads

• A range-width rule for R_spatial — the signal is the range, not the point; an operational rule that discriminates cut-robust from cut-sensitive is what promotion waits on.
• Corpus null-sweeps — the seed-sweep correction retired single-draw null claims; older single-draw rows are flagged and swept as they become decision-relevant.
• Stance thresholds (standing/torquing at 0.15/0.35) remain provisional at small n.
• A fifth domain — the AI case is done (Studies 9–10); scientific imagery (pathology, astronomy) remains the natural next construct, and the purest I-15 test: structure with no composition.
• Cohort mode maturing — the register's cohort-range rows (verdict distributions over unselected draws) are new at n=2 cohorts; a promotion form for cohort-level claims hasn't been needed yet, but will be if ensemble work continues.
• The preshelf, and a retinal default — the substrate toggle (Round 18) ships adapted as an opt-in for cross-reproduction reading. Whether local adaptation should ever become the default substrate is deferred to evidence: it would move every value-referenced measure (τ, β) and must go through the register with the studies re-run, never silently.
• A path-dependent scanpath — shipped (Round 19), as a shelf tool. saccade.py: a foveated, path-dependent tour that reads the field from where it currently is, carries an authority hand-off (island conduit−resistance) between fixations, and aggregates to an entry-invariant transition_field (so no single path is claimed). Its convergence coordinate n_centers is validated on synthetic (rho −0.894) but does not track the semantic single/multi/field labels — a case-study lens, not a classifier. Distinct from the always-on bottom-up scanpath, which is untouched. The open question it raises: convergence-specific pre-registered labels are the right corpus test, not the borrowed focus labels.
• From validation to use — the instrument is calibrated, guarded, and documented; the standing question is no longer whether it measures, but what to point it at.

16Glossary — the library's language

Naming policy. Where a standard technique exists, the entry names it — an unfamiliar house word is often a familiar method underneath (watershed segmentation, Gini coefficient, normalized compression distance, box-counting dimension, phase scrambling, Pearson correlation, Otsu threshold). Terms marked house are this library's coinages; several are metaphors used as handles — they name a measured geometric quantity and must not be over-read as physical or psychological claims.

System & architecture

Measures & symbols

Reading practice

Study-coined descriptors (dissolution, the weave, the spark gap, breath…) belong to individual lab books, not the instrument — they are interpretive vocabulary earned on one work and should be re-earned, not assumed, on the next.