From 2af84703c502fd25ddbb14a84bcc5c99e02e5618 Mon Sep 17 00:00:00 2001 From: Dave Horsfall Date: Tue, 3 Nov 2026 09:50:39 +0000 Subject: [PATCH 1/3] docs: say what vizarr does with each OME-NGFF RFC Nothing on the docs site said which RFCs the viewer supports, how far, or where it deliberately differs from the specification. Anyone deciding whether vizarr would read their data had to infer it from the source or by trying. That gap was about to widen. RFC-4 is in progress and more RFCs are being picked up this week, each landing as a series of pull requests, after which nobody could have said from the outside what the viewer does with the metadata. Adds `docs/rfcs/`, wired into typedoc as a project document with its children declared in the index's own front matter, so a new page is added there rather than in the build configuration. The index carries the support table and says how to read a status. Separating the RFC's status from vizarr's matters: an accepted RFC the viewer does not yet read is exactly the case a reader needs told plainly, and absence from the table means not assessed rather than not supported. RFC-4 is the first page and the pattern for the rest. The parts worth the care are not the summary of the specification, which is a link away, but the two a reader cannot get anywhere else: what the viewer actually does, and where it departs from the spec and why. RFC-4 says orientation MUST NOT appear on a non-spatial axis; vizarr opens such an image anyway, with a warning, because refusing to draw good pixels over a misplaced annotation serves nobody. That reasoning belongs in a document rather than in a code comment. The page is honest that support does not exist yet. A status of "in progress" with the reasoning already written down is more use than a page that appears when the feature does. Both contributor guides now say the page changes in the same pull request as the behaviour, since a page describing last month's viewer is worse than no page. Refs #161, #158 Co-Authored-By: Claude Opus 5 --- CLAUDE.md | 6 ++ CONTRIBUTING.md | 29 ++++++ docs/rfcs/index.md | 38 +++++++ docs/rfcs/rfc-4-axis-orientation.md | 150 ++++++++++++++++++++++++++++ typedoc.json | 4 + 5 files changed, 227 insertions(+) create mode 100644 docs/rfcs/index.md create mode 100644 docs/rfcs/rfc-4-axis-orientation.md diff --git a/CLAUDE.md b/CLAUDE.md index 3c681f7f..b22e0e69 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -110,6 +110,12 @@ fetch anywhere that has to succeed. - **`CONTRIBUTING.md` covers the same ground for outside contributors.** Keep the two in step; if you change the workflow here, change it there. +- **`docs/rfcs/` holds a page per OME-NGFF RFC**, saying what the viewer does with that + metadata, where it deliberately departs from the spec, and which sample images and + tests cover it. Change what the viewer does with an RFC and the page changes in the + same pull request. The two sections worth the care are the ones a reader cannot get + from the specification: what vizarr actually does, and why it declines any part of it. + A new page goes in the `children` list and the support table in `docs/rfcs/index.md`. - **Versions in `package.json` are not edited by hand.** semantic-release owns them. - **`main` is the default branch**, so a `gh` command without an explicit base will target it. Pass `--base dev`. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 26b53fed..afcd20e3 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -137,6 +137,35 @@ locally before asking for a review. pnpm build # builds all packages ``` +## Documentation + +The docs site is built with TypeDoc from the types and the pages under `docs/`. + +```bash +pnpm docs:dev # the site, rebuilt as you edit +pnpm build:docs # what CI builds +``` + +Warnings are errors, so a link to something undocumented fails the build rather than +reaching a reader as a dead end. + +### Documenting support for an OME-NGFF RFC + +`docs/rfcs/` holds a page per RFC, saying what vizarr does with that metadata. If your +change alters what the viewer does with an RFC, update its page in the same pull +request. A page that describes last month's behaviour is worse than no page, because +someone will believe it. + +Copy an existing page for the shape of it. The part worth care is not the summary of +the specification — the specification is a link away — but the two sections a reader +cannot get anywhere else: what the viewer actually does, and where it deliberately +departs from the spec and why. A viewer declines a MUST from time to time, usually +because refusing an image would serve the reader worse than drawing it; write the +reason down rather than leaving it to be rediscovered from a code comment. + +Adding a page means adding it to the `children` list in `docs/rfcs/index.md`, and +giving it a row in that page's support table. + ## How releases happen You do not need to do anything to release your change, and you should not edit version diff --git a/docs/rfcs/index.md b/docs/rfcs/index.md new file mode 100644 index 00000000..32733a54 --- /dev/null +++ b/docs/rfcs/index.md @@ -0,0 +1,38 @@ +--- +title: OME-NGFF RFCs +children: + - ./rfc-4-axis-orientation.md +--- + +[OME-NGFF](https://ngff.openmicroscopy.org/) evolves through RFCs: proposals that add to +the format, each with its own status, review history and adoption timetable. An RFC being +accepted does not mean a viewer reads it, and a viewer reading it does not mean it reads +all of it. + +These pages say, for each RFC, what vizarr does with the metadata — including where it +deliberately departs from the specification, and what it does not do at all. + +## Support + +| RFC | Title | RFC status | Vizarr | +| --- | --- | --- | --- | +| [4](./rfc-4-axis-orientation.md) | Axis Orientation | Accepted | In progress | + +An RFC missing from this table has not been assessed, which is not the same as not being +supported. Some of what the RFCs describe has been in vizarr since before the RFC process +existed. + +## How to read a status + +**Vizarr** describes the viewer, not the format: + +- **Supported** — the metadata is read and acted on. The page says what "acted on" means, + because it is rarely everything the specification permits. +- **In progress** — being implemented. The page says how far it has got. +- **Read, not shown** — the metadata survives parsing and is available through the API, + but nothing in the interface uses it. +- **Not supported** — the metadata is ignored. An image carrying it still opens; vizarr + does not refuse images over metadata it does not understand. +- **Won't support** — a deliberate decision, with the reason on the page. + +A status is about the current release. Where something is only on `dev`, the page says so. diff --git a/docs/rfcs/rfc-4-axis-orientation.md b/docs/rfcs/rfc-4-axis-orientation.md new file mode 100644 index 00000000..f49f0370 --- /dev/null +++ b/docs/rfcs/rfc-4-axis-orientation.md @@ -0,0 +1,150 @@ +--- +title: "RFC-4: Axis Orientation" +--- + +[RFC-4](https://ngff.openmicroscopy.org/rfc/4/index.html) lets a spatial axis say which +anatomical direction it runs in, so a viewer can tell a reader which side of a brain scan +is left without them having to know how the file was written. + +## Status + +| | | +| --- | --- | +| **RFC** | Accepted (S1, SPEC updates). Last changed 2026-09-01. | +| **Vizarr** | In progress. Nothing in the viewer reads orientation yet. | +| **Tracked in** | [#158](https://github.com/BioNGFF/vizarr/issues/158) | + +Images carrying orientation open normally today — the metadata is simply ignored. + +## What RFC-4 adds + +One optional field on each spatial axis: + +```json +{ + "name": "x", + "type": "space", + "unit": "millimeter", + "orientation": { "type": "anatomical", "value": "right-to-left" } +} +``` + +`type` is `"anatomical"`, which is the only domain the RFC defines. `value` is one of 24 +direction pairs — `left-to-right`, `anterior-to-posterior`, `superior-to-inferior`, +`rostral-to-caudal`, `dorsal-to-palmar`, `superficial-to-deep`, `apex-to-base`, and the +reverse of each. + +A value names the direction **from the axis's lowest coordinate to its highest**. So +`anterior-to-posterior` means coordinates increase towards the back. That is a statement +about the coordinate system the spatial metadata establishes, not about array index +order, which is why it composes with `coordinateTransformations` rather than contradicting +them: a negative scale is already accounted for by the time orientation is read. + +Two constraints bound where it can appear. It may only be used on axes of type `space`, +and only where the image holds a single subject roughly aligned to the imaging axes — so +it is not meaningful per well in a plate. + +## What vizarr will do with it + +**Annotate the view; never move a pixel.** + +The tempting reading is that RFC-4 lets a viewer show a brain the right way round, and so +it should reorient images to a canonical frame. Vizarr will not, for four reasons: + +1. The RFC does not ask for it. Its only instruction to applications is to *display the + encoded information*, with axis names along the rendered axes or an orientation widget. +2. Orientation and the coordinate transformations compose rather than conflict, so + treating orientation as an instruction to flip would apply the flip twice. +3. Vizarr renders a single plane through an orthographic camera. At most two of the three + oriented axes are ever on screen, so there is no canonical 3D view to reorient to. +4. A display flip would change the world coordinates that the ROI plugin and host + applications read, silently invalidating every stored region. + +What that means in practice: + +- **Axes in the plane of the view** get their direction labelled at the edge of the + canvas, computed through the image's model matrix rather than from axis order, since a + transform can already rotate or flip the image. +- **Axes through the plane** — usually z — get their direction on the slider, so scrolling + tells you that you are moving superior to inferior rather than only that a number is + rising. +- **Missing orientation** is reported rather than assumed. The RFC permits a viewer to + assume a default but asks it to warn; vizarr warns and assumes nothing. + +## Where vizarr departs from the specification + +RFC-4 says orientation MUST NOT appear on a non-spatial axis. An image that breaks that +rule still opens in vizarr, with a warning. + +This is deliberate. Refusing to display an image because one annotation is in the wrong +place serves nobody: the pixels are fine, and the reader is better off seeing them +alongside a note that the metadata is wrong. It follows the same principle as the rest of +the metadata layer, which prefers a warning to an error wherever an image can still be +drawn. The conformance corpus ships a case for exactly this +(`TC-D_orientation_on_time_axis`), and vizarr opens it. + +The related question — whether an orientation value outside the controlled vocabulary +should cost the reader the whole image — is open, and tracked in +[#158](https://github.com/BioNGFF/vizarr/issues/158). + +## Sample images + +The RFC's reference implementation publishes a conformance corpus: +[fideus-labs/ome-zarr-rfc4-validation](https://github.com/fideus-labs/ome-zarr-rfc4-validation). +The images are mirrored to a public bucket that needs no credentials and sets permissive +CORS headers, so they can be opened directly in the viewer: + +``` +https://ome-zarr-rfc4.s3.filebase.io/ome-zarr/.ome.zarr +``` + +Sixteen valid OME-Zarr cases, written as NGFF 0.5, using all 24 vocabulary terms between +them. A few worth knowing: + +| Image | Orientation | Why it is interesting | +| --- | --- | --- | +| `brain_icbm_ras` | z inferior-to-superior · y posterior-to-anterior · x left-to-right | A full RAS brain; all three axes annotated | +| `mouse_allen_quadruped` | z rostral-to-caudal · y dorsal-to-ventral · x right-to-left | Quadruped vocabulary, which has no biped equivalent | +| `skin_janelia_superficial_deep` | z superficial-to-deep | Tissue-local orientation, with no whole-subject frame | +| `heart_sunnybrook_apex_base` | z apex-to-base | Organ-local orientation | +| `foot_cmb_limb` | z distal-to-proximal · y dorsal-to-plantar | An axis deliberately left unannotated | + +Every case has a `_flip` twin carrying a reversed term over identical pixels. The pair is +the useful test: an implementation that reads orientation but labels the wrong end of the +axis looks correct on one and wrong on the other. + +The twins are not all 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 rather +than to mirror the image. + +These are small single-resolution volumes — the largest is 132 × 80 × 114 — so they +exercise metadata and labelling, not tiling or pyramid behaviour. + +## Conformance testing + +The corpus is read by `viewer/tests/remote/rfc4-orientation.test.ts`, which is part of the +remote suite: + +```bash +pnpm test:remote +``` + +It is remote, and not part of `pnpm test`, because the images come from a server the +project does not run. A third party being slow or down should not turn a pull request red. + +It asserts that every case loads, that axis labels and rank are right, and that the +physical size unit is read where a case declares one. Separately it checks that the corpus +still declares the orientations recorded in the test, since third-party data changing +underneath a test would otherwise leave it passing for the wrong reason. + +Two things it does not assert. Orientation is not yet checked through the viewer, because +it does not reach the viewer yet. And `TC-C_invalid_vocabulary` is left untested while the +question above is open. + +## References + +- [RFC-4: Axis Orientation](https://ngff.openmicroscopy.org/rfc/4/index.html) +- [Reference validator and conformance suite](https://github.com/fideus-labs/ome-zarr-rfc4-validation) +- [ngff-zarr](https://ngff-zarr.readthedocs.io/en/latest/rfc4.html) — writes orientation, + from the command line or Python +- [Vizarr issue #158](https://github.com/BioNGFF/vizarr/issues/158) — implementation diff --git a/typedoc.json b/typedoc.json index 13263438..f79c0a52 100644 --- a/typedoc.json +++ b/typedoc.json @@ -17,5 +17,9 @@ // documented, which reaches the reader as a dead end. Pull requests build the // docs, so these surface before they are published. "treatWarningsAsErrors": true, + // Pages that belong to the project rather than to one package. Nested children are + // declared in the document's own front matter, so a new RFC page is added there and + // not here. + "projectDocuments": ["./docs/rfcs/index.md"], "out": "./docs/build" } From d35074aa249ac992f980698cfda68ebeb68c46c5 Mon Sep 17 00:00:00 2001 From: Dave Horsfall Date: Tue, 3 Nov 2026 12:24:49 +0000 Subject: [PATCH 2/3] docs(rfcs): record the orientation design and the TC-C decision 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 --- docs/rfcs/rfc-4-axis-orientation.md | 33 ++++++++++++++++++----------- 1 file changed, 21 insertions(+), 12 deletions(-) diff --git a/docs/rfcs/rfc-4-axis-orientation.md b/docs/rfcs/rfc-4-axis-orientation.md index f49f0370..680df540 100644 --- a/docs/rfcs/rfc-4-axis-orientation.md +++ b/docs/rfcs/rfc-4-axis-orientation.md @@ -11,7 +11,7 @@ is left without them having to know how the file was written. | | | | --- | --- | | **RFC** | Accepted (S1, SPEC updates). Last changed 2026-09-01. | -| **Vizarr** | In progress. Nothing in the viewer reads orientation yet. | +| **Vizarr** | In progress. The reader carries orientation through ([#163](https://github.com/BioNGFF/vizarr/pull/163)) and the viewer draws it ([#164](https://github.com/BioNGFF/vizarr/pull/164)); neither has reached `dev`. | | **Tracked in** | [#158](https://github.com/BioNGFF/vizarr/issues/158) | Images carrying orientation open normally today — the metadata is simply ignored. @@ -62,12 +62,16 @@ it should reorient images to a canonical frame. Vizarr will not, for four reason What that means in practice: -- **Axes in the plane of the view** get their direction labelled at the edge of the - canvas, computed through the image's model matrix rather than from axis order, since a - transform can already rotate or flip the image. -- **Axes through the plane** — usually z — get their direction on the slider, so scrolling - tells you that you are moving superior to inferior rather than only that a number is - rising. +- **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. Which side gets which term is + computed through the image's model matrix rather than from axis order, since a transform + can already rotate or flip the image. Only the arms with something to say are drawn, so + an image that annotates one in-plane axis gets a double-headed arrow rather than a cross + with two blank ends. +- **Axes through the plane** — usually z — have no direction to draw on a flat legend, so + they go on the slider that scrolls through them, ordered the way the handle travels. The + arrow is the compass's, drawn from one definition, because the two are saying the same + thing about different axes. - **Missing orientation** is reported rather than assumed. The RFC permits a viewer to assume a default but asks it to warn; vizarr warns and assumes nothing. @@ -83,8 +87,11 @@ the metadata layer, which prefers a warning to an error wherever an image can st drawn. The conformance corpus ships a case for exactly this (`TC-D_orientation_on_time_axis`), and vizarr opens it. -The related question — whether an orientation value outside the controlled vocabulary -should cost the reader the whole image — is open, and tracked in +A value outside the controlled vocabulary is treated differently: it fails the schema, and +the image does not open at all. The corpus case `TC-C_invalid_vocabulary` is unopenable in +vizarr today for that reason. This is accepted for now rather than defended — an enum is +the thing that makes the other 23 values trustworthy, and relaxing it would mean carrying a +value no part of the viewer knows what to do with. Revisiting it is tracked in [#158](https://github.com/BioNGFF/vizarr/issues/158). ## Sample images @@ -137,9 +144,11 @@ physical size unit is read where a case declares one. Separately it checks that still declares the orientations recorded in the test, since third-party data changing underneath a test would otherwise leave it passing for the wrong reason. -Two things it does not assert. Orientation is not yet checked through the viewer, because -it does not reach the viewer yet. And `TC-C_invalid_vocabulary` is left untested while the -question above is open. +One thing it does not assert: `TC-C_invalid_vocabulary` is not opened, because it cannot +be. What the viewer draws from orientation is tested offline instead, in +`viewer/tests/orientation.test.ts`, against hand-written matrices — a negative scale, a +quarter turn, a reversed through-plane axis — rather than against real images, so the part +most likely to be subtly wrong does not depend on a network. ## References From 2105f518662c60682203ff27cc3ab2cc0e62079d Mon Sep 17 00:00:00 2001 From: Dave Horsfall Date: Tue, 3 Nov 2026 12:30:18 +0000 Subject: [PATCH 3/3] docs(rfcs): say which version each RFC-4 behaviour belongs to The page used "today" to mean two different things one section apart: that an image carrying orientation opens normally, which is true of the release, and that TC-C_invalid_vocabulary does not open, which is only true once the reader starts validating orientation on #163. A reader on the released viewer would have found the second claim false and had no way to tell why. Each behaviour now names the version it belongs to. The note about TC-C being untested says what the choice is -- not writing a test that pins down a decision still open -- rather than claiming the case cannot be opened at all, which is untrue on `dev`. Co-Authored-By: Claude Opus 5 --- docs/rfcs/rfc-4-axis-orientation.md | 22 +++++++++++++++------- 1 file changed, 15 insertions(+), 7 deletions(-) diff --git a/docs/rfcs/rfc-4-axis-orientation.md b/docs/rfcs/rfc-4-axis-orientation.md index 680df540..7e3502a2 100644 --- a/docs/rfcs/rfc-4-axis-orientation.md +++ b/docs/rfcs/rfc-4-axis-orientation.md @@ -14,7 +14,8 @@ is left without them having to know how the file was written. | **Vizarr** | In progress. The reader carries orientation through ([#163](https://github.com/BioNGFF/vizarr/pull/163)) and the viewer draws it ([#164](https://github.com/BioNGFF/vizarr/pull/164)); neither has reached `dev`. | | **Tracked in** | [#158](https://github.com/BioNGFF/vizarr/issues/158) | -Images carrying orientation open normally today — the metadata is simply ignored. +In the current release the field is discarded while the metadata is parsed, so an image +carrying orientation opens normally and shows nothing of it. ## What RFC-4 adds @@ -88,10 +89,14 @@ drawn. The conformance corpus ships a case for exactly this (`TC-D_orientation_on_time_axis`), and vizarr opens it. A value outside the controlled vocabulary is treated differently: it fails the schema, and -the image does not open at all. The corpus case `TC-C_invalid_vocabulary` is unopenable in -vizarr today for that reason. This is accepted for now rather than defended — an enum is -the thing that makes the other 23 values trustworthy, and relaxing it would mean carrying a -value no part of the viewer knows what to do with. Revisiting it is tracked in +the image does not open at all. That follows from reading orientation rather than from +drawing it, so it arrives with the reader ([#163](https://github.com/BioNGFF/vizarr/pull/163)) +and is not true of the current release, where the field is discarded before anything can +object to it. The corpus case `TC-C_invalid_vocabulary` is the one this costs. + +It is accepted for now rather than defended — an enum is the thing that makes the other 23 +values trustworthy, and relaxing it would mean carrying a value no part of the viewer knows +what to do with. Revisiting it is tracked in [#158](https://github.com/BioNGFF/vizarr/issues/158). ## Sample images @@ -144,8 +149,11 @@ physical size unit is read where a case declares one. Separately it checks that still declares the orientations recorded in the test, since third-party data changing underneath a test would otherwise leave it passing for the wrong reason. -One thing it does not assert: `TC-C_invalid_vocabulary` is not opened, because it cannot -be. What the viewer draws from orientation is tested offline instead, in +One case is deliberately left alone: `TC-C_invalid_vocabulary`. Asserting on it would +pin down the behaviour described above, which is accepted rather than settled, and a test +is a poor place to record a decision still open. + +What the viewer draws from orientation is tested offline instead, in `viewer/tests/orientation.test.ts`, against hand-written matrices — a negative scale, a quarter turn, a reversed through-plane axis — rather than against real images, so the part most likely to be subtly wrong does not depend on a network.