Repository navigation
feat(viewer): show RFC-4 anatomical orientation on the view - #164
Merged
davehorsfall merged 4 commits intoNov 5, 2026
Merged
Conversation
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]>
davehorsfall
added a commit
that referenced
this pull request
Nov 3, 2026
The page described labels written against the four edges of the canvas, which was the first of two designs built for #164 and is not the one that survived. The terms are long words, and against the margins they cost real room on a small viewport; a corner legend says the same thing in one place. `TC-C_invalid_vocabulary` was written up as an open question. It is now a decision: a value outside the vocabulary fails the schema and the image does not open, which is accepted for the moment rather than argued for. Saying so is more use to a reader than leaving it open, since the behaviour is what they will meet. Co-Authored-By: Claude Opus 5 <[email protected]>
davehorsfall
marked this pull request as ready for review
November 3, 2026 15:24
There was a problem hiding this comment.
🟡 Changes recommended
Unresolved issues can crash image rendering on malformed orientation metadata, omit direction pairs at 45° rotations, leave multi-subject labels unsuppressed, and hide compass information from screen readers.
4 open issues
What changed in this PR
Implements the display phase of RFC-4 anatomical orientation support from #158, building on the metadata passthrough in #163. It annotates the viewer without changing image pixels or ROI coordinates.
Changes:
- Resolves anatomical directions through the image model matrix.
- Adds an in-plane compass and through-plane slider labels using shared arrow artwork.
- Adds 13 offline tests covering orientation parsing, transforms, and missing metadata.
| File | Description |
|---|---|
viewer/tests/orientation.test.ts |
Tests direction parsing and model-matrix orientation mapping. |
viewer/src/orientation.ts |
Resolves anatomical terms into compass and slider directions. |
viewer/src/components/Viewer.tsx |
Mounts the orientation compass. |
viewer/src/components/OrientationLabel.tsx |
Displays direction pairs beside sliders. |
viewer/src/components/OrientationCompass.tsx |
Adds the corner compass for in-plane axes. |
viewer/src/components/OrientationArrow.tsx |
Provides shared compass and slider arrow artwork. |
viewer/src/components/LayerController/AxisSlider.tsx |
Adds through-plane orientation labels to axis controls. |
Review effort: Balanced
Comment on lines
+29
to
+30
| () => resolveScreenOrientation(axes, model_matrix).throughPlane[name], | ||
| [axes, model_matrix, name], |
|
|
||
| return ( | ||
| <Box | ||
| aria-hidden |
Comment on lines
+35
to
+36
| export function splitOrientation(value: string): OrientationEnds | null { | ||
| const halves = value.split("-to-"); |
Comment on lines
+116
to
+118
| if (Math.abs(dx) >= Math.abs(dy)) { | ||
| edges.left = dx >= 0 ? ends.from : ends.to; | ||
| edges.right = dx >= 0 ? ends.to : ends.from; |
This was referenced Nov 4, 2026
Base automatically changed from
feat/158-orientation-passthrough
to
test/rfc4-orientation-corpus
November 5, 2026 15:11
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.

Phase 1 of #158: anatomical orientation is shown on the view.
RFC-4's only instruction to an application is to "display the encoded information with,
for example, the human-readable names of the axes along the rendered axes of the image".
That is all this does.
arrow with the term each direction leads to set around it.
draw on a flat legend, so it goes on the slider that scrolls through it, ordered the way
the handle travels rather than the way coordinates increase.
Both are drawn with the same arrow, from one definition, because they are saying the same
thing about different axes.
Why a corner and not the four edges
The first version wrote the terms against the top, bottom, left and right of the view, and
both were built so they could be compared on real images rather than argued about. The
compass won. The vocabulary is long words —
posterior,proximal— and against themargins they cost real room on a small viewport and read as four unrelated captions rather
than one statement about the image.
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. A display flip would also change the world
coordinates the ROI plugin reads and invalidate every stored region without saying so.
So which side gets which term goes through the model matrix, not the axis order, and
the compass follows a flipped or rotated image. That is the part worth testing, and
orientation.tsis pure so that it can be — a negative scale, a quarter turn and areversed through-plane axis are written down in
tests/orientation.test.tsrather thanhunted for in real data.
Verified in a browser, against the corpus
brain_icbm_rasbrain_icbm_ras_flipEvery term inverts, which is exactly what the flipped twins exist to catch. Reading left
on the left and right on the right for an RAS volume is the radiological convention, and
is the thing that would have been quietly wrong if the matrix were skipped.
An image with no orientation — the default IDR demo — shows no compass and no direction on
the slider.
Decisions worth a look
Terms are written out, not reduced to initials. The 24 values draw on 21 terms whose
first letters collide badly:
pis posterior, palmar, plantar and proximal;disdorsal, distal and deep.
vocab-quad-limbcarries cranial, caudal, dorsal, palmar,proximal and distal at once, which reduces to
c, c, d, p, p, d— four collisions on oneimage. RFC-4 rejected three-letter codes such as
RASin its Abandoned Ideas, sorebuilding them for a tidier legend would reintroduce the ambiguity the vocabulary exists
to avoid.
Only arms with something to say are drawn. An image that orients one in-plane axis
gets a double-headed arrow, not a cross with two blank ends.
Suppressed for a plate or a well. Those are several subjects at once, and RFC-4 applies
only where "there is a single subject in the acquired volume".
Orientation on a non-spatial axis is not drawn. It is a fault in the metadata, and
drawing it would repeat the fault rather than report it. Reporting it is Phase 2.
Read from the first source, as the scale bar is. Several images at once can disagree,
and one frame of reference cannot honestly describe them.
Checks
pnpm test— 63 passed, up from 50 (13 new, all offline and pure)pnpm lint,pnpm check— cleanbrain_icbm_ras, its flipped twin, andvocab-quad-limbKnown rough edge
The compass and the warning snackbar both want the bottom of the window. At 1600px wide
they do not meet; at around 1000px they overlap. The snackbar is dismissible and transient,
so it may not be worth solving, but it is worth knowing before review.
Not in this PR
Phase 2, the warnings: orientation on a non-spatial axis, a value outside the vocabulary,
two axes from the same opposed pair, and absent orientation on an anatomical-looking image.
The corpus ships adversarial cases for these (
TC-D, and theSC-*stress cases in thevalidation repo), which are better fixtures than any I would write to match my own
implementation.
🤖 Generated with Claude Code