Skip to content

feat(viewer): show RFC-4 anatomical orientation on the view - #164

Merged
davehorsfall merged 4 commits into
test/rfc4-orientation-corpusfrom
feat/158-orientation-overlay
Nov 5, 2026
Merged

davehorsfall merged 4 commits into
test/rfc4-orientation-corpusfrom
feat/158-orientation-overlay

Conversation

@davehorsfall

@davehorsfall davehorsfall commented Nov 3, 2026 •

Copy link
Copy Markdown
Member

Phase 1 of #158: anatomical orientation is shown on the view.

Draft, for the same reason as #163 — the branch beneath it still pins zod-ome-ngff
to an unmerged branch. Based on feat/158-orientation-passthrough (#163), not dev.

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.

  • Axes in the plane of the view go on a compass in the bottom-left corner: a four-way
    arrow with the term each direction leads to set around it.
  • An axis pointing out of the view — z, for an ordinary image — has no direction to
    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 the
margins 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.ts is pure so that it can be — a negative scale, a quarter turn and a
reversed through-plane axis are written down in tests/orientation.test.ts rather than
hunted for in real data.

Verified in a browser, against the corpus

brain_icbm_ras brain_icbm_ras_flip
compass, up / down posterior / anterior anterior / posterior
compass, left / right left / right right / left
slider inferior → superior superior → inferior

Every 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: p is posterior, palmar, plantar and proximal; d is
dorsal, distal and deep. vocab-quad-limb carries cranial, caudal, dorsal, palmar,
proximal and distal at once, which reduces to c, c, d, p, p, d — four collisions on one
image. RFC-4 rejected three-letter codes such as RAS in its Abandoned Ideas, so
rebuilding 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 — clean
  • Screenshotted in a real browser against brain_icbm_ras, its flipped twin, and
    vocab-quad-limb

Known 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 the SC-* stress cases in the
validation repo), which are better fixtures than any I would write to match my own
implementation.

🤖 Generated with Claude Code

davehorsfall and others added 4 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]>
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
davehorsfall marked this pull request as ready for review November 3, 2026 15:24
Copilot AI balanced review requested due to automatic review settings November 3, 2026 15:24

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.

🟡 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 thread viewer/src/orientation.ts
Comment on lines +35 to +36
export function splitOrientation(value: string): OrientationEnds | null {
const halves = value.split("-to-");
Comment thread viewer/src/orientation.ts
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;
Base automatically changed from feat/158-orientation-passthrough to test/rfc4-orientation-corpus November 5, 2026 15:11
@davehorsfall
davehorsfall merged commit f92e965 into test/rfc4-orientation-corpus Nov 5, 2026
1 check passed
@davehorsfall
davehorsfall deleted the feat/158-orientation-overlay branch November 5, 2026 15:12
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