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.7).
• 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 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).

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.7. Full definitions, ranges, calibration values, and per-metric caveats live in instrument/docs/METRICS.md — this table is the map, not the dictionary.

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.

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.

10The twenty-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         # 4 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.7)
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.

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

Twelve studies across four domains — ten deep single-work reads, 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.
• 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.