Repository navigation
test(viewer): read the RFC-4 orientation conformance corpus - #160
Open
davehorsfall wants to merge 8 commits into
Open
davehorsfall wants to merge 8 commits into
davehorsfall wants to merge 8 commits into
Conversation
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]>
✅ Deploy Preview for biongff-vizarr ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
There was a problem hiding this comment.
🟢 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 Report❌ Patch coverage is
📢 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]>
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
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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 andaccess-control-allow-origin: *. That means the viewer can read it in a browser as wellas 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/andpnpm testis unchanged at 46 tests, 7 files.What is asserted
What the viewer can actually do today: every case loads through
createSourceData, theaxis 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.jsonto be re-pinned, which isPhase 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
_fliptwin, and Iassumed every annotated axis reversed. It does not:
mouse_rosenhain_flipreverses z only; the manifest says it exists "to covercranial-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_deepflips to
skin_janelia_flip. Deriving the twin by stripping a suffix produced a test thatlooked 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
orientationfield 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
parseis 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()returnsundefined 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:remotefor this file — 41 passedpnpm lint— cleanpnpm check— clean🤖 Generated with Claude Code