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..7e3502a2 --- /dev/null +++ b/docs/rfcs/rfc-4-axis-orientation.md @@ -0,0 +1,167 @@ +--- +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. 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) | + +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 + +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** 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. + +## 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. + +A value outside the controlled vocabulary is treated differently: it fails the schema, and +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 + +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. + +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. + +## 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" }