Treat an image stack's z axis as a slice index, not a spatial axis

[krokicki]

Rolls up the image-stack-z-axis branch. A tilt series' z axis is a tilt index, not a spatial axis, and the server was treating it as spatial. The cached-info work in here exists because fixing that needs a cache that can invalidate itself correctly.

The bug

cella_z is meaningless on an image stack, but writers stamp it anyway — Relion copies the x/y pixel size onto the tilt axis, so 55 tilts came out 8.3 nm "thick" against a 621 nm-wide image. A 75× squash that left the tilt axis unnavigable in Neuroglancer. Downsampling made it worse: binning z averaged tilts taken at different angles into one plane. And the (mx,my,mz) != (nx,ny,nz) guard rejected 110 of the corpus's 2871 stacks with HTTP 422, because mz=1 regardless of nz is the convention on those files rather than a defect.

For a file classified as an image stack:

• z resolution is advertised as 1 nm per slice, ignoring cella_z (precomputed has no way to say "this axis is an index", and rejects a zero resolution outright). info carries a non-spec "is_image_stack": true.
• plan_scales never bins z — scale keys go 2_2_1, 4_4_1, …
• the grid-size guard doesn't apply

Why globbing, not the aspect-ratio heuristic

Something has to decide, per file, which kind it is. The first attempt inferred it from shape (nz / max(nx, ny) below a threshold → stack). That cannot be made correct, and the corpus says so numerically: measured over all 3648 files, cross-checked against the directory convention,

	nz / max(nx, ny)
true 2D (stacks)	0.0001 – 0.2200
true 3D (volumes)	0.1276 – 1.4120

The ranges overlap. No threshold separates the classes, so retuning the constant only moves which files are wrong — the shipped value was knowingly wrong on 2 files, both small-format synthetic tilt series.

The header can't answer it either. ispg is 0 on every file in the corpus, tomograms included, and writers agree on nothing else: Relion stamps mz=nz with cella_z = nz * pixel_x, IMOD stamps mz=1 with a dummy cella_z, and only some stacks carry an extended header. There is no field to read.

What does know is the operator — the information lives in the directory layout and the naming convention, which is knowledge about the experiment, not about the bytes. So the classification stops being derived and becomes an input: --stack-glob / --volume-glob on mrc-pyramid, MRCNG_STACK_GLOBS / MRCNG_VOLUME_GLOBS on the server.

mrc-pyramid build ... \
    --stack-glob '*/TiltSeries/*' --stack-glob '*/Gains/*' \
    --volume-glob '*/Tomograms/*' --volume-glob '*_ctf.mrc'

Volume globs win over stack globs, because real trees mix both kinds in one directory — this corpus has external/s200.mrc (a 55-tilt stack) beside external/s200_ctf.mrc (a 512×512×55 volume). An include-only list can't separate those without per-filename patterns.

This trades an inference that is provably unfixable for configuration that has to be kept in sync, and the fingerprint absorbs that cost: the build records the classification it used, and validate() rejects a mismatch as INCOMPATIBLE. Two things follow —

• changing the globs invalidates exactly the entries it would reclassify, so a plain mrc-pyramid build picks them up; no --force sweep
• a server whose globs disagree with the build's degrades to single-resolution instead of the two silently disagreeing about what z means

is_image_stack also stops being a header property and becomes an input threaded into parse_header, so build and serve can't derive it twice and diverge.

Verified on the corpus: the glob set above classifies all 3648 files correctly, including the 250×150×55 synthetic stack the heuristic misread and the _ctf volumes sitting beside their stacks.

Supporting work: the cached info becomes authoritative

The z fix changes what a build produces, which only helps if existing caches stop being served as valid — the earlier zero-cella_z fix shipped and then served stale "resolution": [.., .., 0.0] for weeks. So:

• /info for a cached file now returns the verbatim bytes the build wrote instead of recomputing them on the request path, so info can never disagree with the chunk files next to it
• the fingerprint gains DERIVATION_VERSION (bumped by hand when a change alters info, the scale plan, or the chunk bytes) and the per-scale sizes, so stale entries read as outdated and cached chunk extents are validated against the scale plan the build actually used
• a corrupt info or a non-iterable scale-sizes value degrades to no-cache rather than a 500
• CLAUDE.md and the README state when to bump DERIVATION_VERSION, and how it differs from SCHEMA_VERSION

Two follow-up fixes to the glob plumbing are also here: MRCNG_STACK_GLOBS was tuple[str, ...], and pydantic-settings JSON-parses complex-typed fields straight from the environment, so the documented comma-separated value raised SettingsError and the server wouldn't start — now a plain str split at the use site, matching cors_origins. And the server matched globs against the absolute path while the builder matched the relpath; */TiltSeries/* works either way (which is why tests passed) but an anchored Experimental/* doesn't.

Operational note

SCHEMA_VERSION 2 → 3 for the new fingerprint key, which subsumes a DERIVATION_VERSION bump. Existing caches must be rebuilt: a stack's z-binned scale keys are no longer advertised, so affected files serve single-resolution until then. No wrong bytes are served in the meantime.

Test plan

pixi run -e default pytest -q

@StephanPreibisch @allison-truhlar

[krokicki]

@allison-truhlar I'm not sure how realistic the current globbing strategy is, we should discuss further in our next dev meeting.