Skip to content

test(viewer): read the RFC-4 orientation conformance corpus - #160

Open
davehorsfall wants to merge 8 commits into
devfrom
test/rfc4-orientation-corpus
Open

davehorsfall wants to merge 8 commits into
devfrom
test/rfc4-orientation-corpus

Conversation

@davehorsfall

Copy link
Copy Markdown
Member

Adds the RFC-4 axis orientation conformance corpus to the remote suite. Part of #158.

The reference implementation for RFC-4 publishes a corpus of images that carry anatomical
orientation — fideus-labs/ome-zarr-rfc4-validation,
data mirrored at https://ome-zarr-rfc4.s3.filebase.io/ with no credentials and
access-control-allow-origin: *. That means the viewer can read it in a browser as well
as in a test, so it doubles as something to click on while building the overlay.

16 valid OME-Zarr cases, written as NGFF 0.5 (zarr v3), using all 24 terms of the
controlled vocabulary between them. Largest is 132 × 80 × 114. 41 tests, ~40s.

Why remote and not offline

filebase.io is a server we do not run. CLAUDE.md is explicit about what happened the last
two times a fetch sat somewhere that had to succeed, so this goes in tests/remote/ and
pnpm test is unchanged at 46 tests, 7 files.

What is asserted

What the viewer can actually do today: every case loads through createSourceData, the
axis labels and rank are right, and the unit is read where a case declares one (8 of the
16 do). Alongside that is a guard on the corpus itself — it is a third party's data, and
every other assertion here is worthless if it changes underneath us without anyone
noticing.

Orientation is not asserted in the viewer, because it does not reach it yet. That
needs BioNGFF/zod-ome-ngff#2 to merge and viewer/package.json to be re-pinned, which is
Phase 0 of #158. The data and the scaffolding are here so that work has something to
assert against.

Two things the corpus taught us

Both are in comments, because neither is guessable and both cost me a wrong test first:

The twins are not uniformly whole-image mirrors. Each case has a _flip twin, and I
assumed every annotated axis reversed. It does not:

brain_icbm_ras_flip        z:REVERSED  y:REVERSED  x:REVERSED
mouse_rosenhain_flip       z:REVERSED  y:SAME(dorsal-to-ventral)  x:none
heart_sunnybrook_flip      z:REVERSED  y:none  x:none

mouse_rosenhain_flip reverses z only; the manifest says it exists "to cover
cranial-to-caudal in real data", not to mirror the image. So the invariant is per axis:
unannotated in both, unchanged, or the exact reverse — and at least one reversed.

Three originals do not share a stem with their twin. skin_janelia_superficial_deep
flips to skin_janelia_flip. Deriving the twin by stripping a suffix produced a test that
looked like it compared the pair and in fact only 404'd, which is why the pairs are now
named explicitly.

Must-reject cases

The corpus ships two. TC-D puts an orientation on a time axis, which RFC-4 forbids —
"The orientation field MUST only be used on spatial axes". The viewer opens it anyway,
and should: refusing a whole image over one misplaced annotation is the opposite of what
parse is for. That is covered here, and is the case Phase 2 of #158 will warn on.

TC-C carries a value outside the vocabulary, and is deliberately left untested. It
loads today. Once the re-pin lands it will not, because the closed enum in
BioNGFF/zod-ome-ngff#2 rejects it and no other schema matches, so parse() returns
undefined and the viewer raises a user-facing error. Whether one unreadable orientation
should cost the reader the whole image is a real question, and it belongs in #158 rather
than being settled by a test written in passing.

Checks

  • pnpm test — 46 passed, 7 files (unchanged; the remote suite is excluded)
  • pnpm test:remote for this file — 41 passed
  • pnpm lint — clean
  • pnpm check — clean

🤖 Generated with Claude Code

The reference implementation for RFC-4 publishes a corpus of images that carry
anatomical axis orientation, with a credential-free mirror and permissive CORS:
https://github.com/fideus-labs/ome-zarr-rfc4-validation

Sixteen valid OME-Zarr cases, written as NGFF 0.5, using all 24 terms of the
controlled vocabulary between them. Each has a flipped twin carrying a reversed
term over identical pixels, which is what will catch a reader that finds the
orientation but labels the wrong end of the axis.

Remote, not offline. These are small images, but filebase.io is a server we do
not run, and a pull request that has nothing to do with it should not go red
when it is slow. The offline suite is unchanged at 46 tests.

The tests assert what the viewer can do today: that every case loads, that the
axis labels and rank are right, and that the unit is read where a case declares
one. Alongside that is a guard on the corpus itself, since third-party data that
changes underneath us would otherwise quietly turn these green for the wrong
reason. Orientation does not yet reach the viewer -- #158 -- so nothing asserts
it there yet.

Two things the corpus taught us, recorded in comments because neither is
guessable from the names:

  - The twins are not uniformly whole-image mirrors. mouse_rosenhain_flip
    reverses z and leaves y as dorsal-to-ventral, because it exists to cover
    cranial-to-caudal in real data. The invariant is per axis: unannotated in
    both, unchanged, or the exact reverse.

  - Three originals do not share a stem with their twin, so the pairs are named
    rather than derived. Deriving them gave a test that appeared to compare the
    two and in fact only 404'd.

TC-D, which puts an orientation on a time axis, is covered: RFC-4 forbids it,
and the viewer opens the image anyway, which is the behaviour we want. TC-C,
whose orientation value is outside the vocabulary, is deliberately left untested
while #158 settles whether an unreadable orientation should cost the reader the
whole image.

Refs #158

Co-Authored-By: Claude Opus 5 <[email protected]>
Copilot AI balanced review requested due to automatic review settings November 3, 2026 09:38
@netlify

netlify Bot commented Nov 3, 2026 •

Copy link
Copy Markdown

✅ Deploy Preview for biongff-vizarr ready!

Name Link
🔨 Latest commit f92e965
🔍 Latest deploy log https://app.netlify.com/projects/biongff-vizarr/deploys/6aec9cc6ccc037c0fadd1b46
😎 Deploy Preview https://deploy-preview-160--biongff-vizarr.netlify.app
📱 Preview on mobile
Toggle QR Code...

QR Code

Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟢 Approval recommended

There are no active review issues for the added RFC-4 orientation corpus tests.

No open issues 🎉

What changed in this PR

Adds remote RFC-4 orientation corpus tests as groundwork for #158, without changing viewer behavior or the offline suite. Viewer orientation assertions remain deferred until metadata support lands.

Changes:

  • Checks loading, axis labels, rank, and declared spatial units for 16 valid corpus cases.
  • Guards recorded orientation metadata and verifies the reversal relationships between paired cases.
  • Confirms that orientation on a time axis does not prevent image loading.
File Description
viewer/​tests/​remote/​rfc4-orientation.test.ts Adds 41 tests covering corpus loading, metadata consistency, paired orientations, and time-axis annotation tolerance.

Review effort: Balanced

@codecov

codecov Bot commented Nov 3, 2026 •

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 62.68657% with 25 lines in your changes missing coverage. Please review.

Files with missing lines Patch % Lines
viewer/src/components/OrientationCompass.tsx 22.22% 13 Missing and 1 partial ⚠️
viewer/src/components/OrientationArrow.tsx 21.42% 11 Missing ⚠️

📢 Thoughts on this report? Let us know!

Phase 0 of #158: the metadata survives being read. Nothing in the interface uses
it yet.

Axes now reach `SourceData` as the metadata declared them, rather than only as a
list of names, so orientation and unit are available to whatever reads them next.

Two separate things were dropping the field, and either alone was enough to lose
it. The schema stripped it, since a non-strict `z.object` discards what it does
not declare; that is fixed in BioNGFF/zod-ome-ngff#2. And `getNgffAxes` rebuilt
every axis from `name`, `type` and `unit`, which it now spreads instead -- the
next RFC to add a field would otherwise be lost in the same place.

WHILE THE SCHEMA PULL REQUEST IS OPEN this pins `zod-ome-ngff` to its branch.
That must go back to `#dev` before this is merged, and is why this is a draft.

A plain image, a plate and a well read their axes through different code, so each
had its own way of losing the orientation, and the tests cover all three. An
image never passes through `getNgffAxes` at all -- it reads axes through
`getDefaultCoordinateSystem`, which returns them untouched -- so a test of images
alone passed with the fix reverted. The plate and the well are what make it
load-bearing.

The generated fixtures gained orientation on their spatial axes, using the values
from the RFC's own example, so the offline suite covers it at all: the
conformance corpus is the better test and is remote, which means CI never runs
it. The time and channel axes are left alone, since RFC-4 permits orientation
only on axes of type `space`.

Offline 46 to 50 tests. The corpus tests now assert orientation reaches the
viewer rather than only that the corpus declares it.

Refs #158

Co-Authored-By: Claude Opus 5 <[email protected]>
davehorsfall and others added 6 commits November 3, 2026 10:20
Phase 1 of #158. The RFC asks an application to "display the encoded
information with, for example, the human-readable names of the axes along the
rendered axes of the image", and that is all this does.

Axes lying in the plane of the view are labelled at the edge each end points
towards. One pointing out of the view -- z, for an ordinary image -- cannot be
drawn at an edge, so its direction goes on the slider that scrolls through it,
ordered the way the handle travels rather than the way coordinates increase.

Nothing moves a pixel. Orientation describes the coordinate system the spatial
metadata already establishes, so a transform that mirrors the image has been
accounted for before these labels are chosen; applying it again would apply it
twice. Flipping the display would also change the world coordinates the ROI
plugin reads, and invalidate every stored region without saying so.

Which edge gets which label therefore goes through the model matrix rather than
the axis order, so the labels follow a flipped or rotated image. That is the
part worth testing, and `orientation.ts` is pure so it can be: a negative scale,
a quarter turn and a reversed through-plane axis are all written down in
`tests/orientation.test.ts` rather than hunted for in real data.

Terms are written out rather than reduced to initials. The 24 values draw on 21
terms whose first letters collide badly -- `p` is posterior, palmar, plantar and
proximal; `d` is dorsal, distal and deep -- and RFC-4 rejected three-letter
codes such as RAS in its Abandoned Ideas, so rebuilding them would reintroduce
the ambiguity the vocabulary exists to avoid.

Suppressed for a plate or a well, which are several subjects at once: RFC-4
applies only where "there is a single subject in the acquired volume".

Checked against the conformance corpus in a browser. `brain_icbm_ras` reads
left/right across and posterior/anterior down, with the slider running inferior
to superior; its flipped twin reads every one of those the other way, which is
what the twins exist to catch. An image with no orientation shows nothing.

Refs #158

Co-Authored-By: Claude Opus 5 <[email protected]>
The slider wrote its two terms as plain muted text with a typed arrow between
them, while the terms at the edges of the image were set as labels. They
describe the same axes, and the only reason they are drawn in different places
is that one axis points at the viewer and cannot be labelled on the image at
all, so reading as two different kinds of thing was just an inconsistency.

The look now has one definition, in `OrientationLabel`, which both use.

The arrow is drawn rather than typed. A glyph in the middle of a caption sits on
the text baseline and reads as punctuation, where this is the one part of the
label whose whole job is to say direction.

Refs #158

Co-Authored-By: Claude Opus 5 <[email protected]>
Labels against all four edges read well but spend all four margins to do it,
which is a lot of the view to give up on a small viewport or beside a wide
image. This gathers the same information into one corner: a four-way arrow with
the term each direction leads to set around it, in the manner of a map legend.

Both are drawn for now, so the two can be judged against each other on real
images rather than in the abstract. One of them should go before this is
merged.

The terms are words here too, not initials, and `vocab-quad-limb` is the case
that settles it: cranial, caudal, dorsal, palmar, proximal and distal appear on
one image, which reduces to c, c, d, p, p, d. RFC-4 threw out three-letter codes
in its Abandoned Ideas for the same reason.

Only arms with something to say are drawn, so an image that orients one axis
gets a double-headed arrow rather than a cross with two blank ends.

The slider's arrow is now `Forward` at 20px rather than a 16px hairline. At
caption size the thin one was barely legible as an arrow, which defeated the
point of drawing it instead of typing one.

Refs #158

Co-Authored-By: Claude Opus 5 <[email protected]>
Both designs were drawn at once so they could be judged side by side on real
images rather than in the abstract, which was never meant to ship. The compass
is the one that survives: the anatomical terms are long words, and set against
the four margins they cost real room on a small viewport and read as four
unrelated captions instead of one statement about the image.

The slider's arrow is now the compass's arrow, drawn from one definition in
`OrientationArrow`. The two displays are saying the same thing about different
axes -- which way along this axis the anatomy runs -- and the only reason the
through-plane axis is described beside its slider at all is that it points at
the viewer and has no direction to draw on a flat legend. An arrow that changed
shape between the two would suggest they meant different things.

`Arm` takes its origin rather than assuming the centre of the compass, so the
same component draws four arms out of one point and a single arm left to right.

Co-Authored-By: Claude Opus 5 <[email protected]>
feat(viewer): carry RFC-4 axis orientation through to the reader
feat(viewer): show RFC-4 anatomical orientation on the view

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants