Skip to content

docs: say what vizarr does with each OME-NGFF RFC - #162

Open
davehorsfall wants to merge 3 commits into
devfrom
docs/rfc-support
Open

davehorsfall wants to merge 3 commits into
devfrom
docs/rfc-support

Conversation

@davehorsfall

Copy link
Copy Markdown
Member

Adds a page per OME-NGFF RFC to the docs site, saying what vizarr does with that metadata.
Closes the structure part of #161; RFC-4 is the first page.

Based on docs/site-deploy-and-design (#156), not dev. It edits typedoc.json,
which #156 rewrites, and it needs that branch's treatWarningsAsErrors for a broken link
to fail the build rather than reach a reader. Merge #156 first and this retargets to dev
cleanly.

Why

Nothing on the site said which RFCs the viewer supports, how far, or where it deliberately
differs from the spec. Anyone deciding whether vizarr would read their data had to infer
it from the source or by trying it.

That gap was about to widen rather than close. RFC-4 is in progress (#158) and more RFCs
are being picked up this week. Each lands as a series of pull requests, and by the time
the last one merges nobody could say from the outside what the viewer actually does.

What is here

docs/rfcs/index.md                    support table, and how to read a status
docs/rfcs/rfc-4-axis-orientation.md   the first page, and the pattern

Wired into typedoc as a project document, with children declared in the index's own front
matter — so adding an RFC means editing that page, not the build configuration.

The statuses are deliberately split. The RFC's status and vizarr's support are
separate columns, because an accepted RFC that the viewer does not yet read is exactly the
case a reader needs told plainly. Absence from the table means not assessed, not not
supported
.

The RFC-4 page says support does not exist yet

It is honest that nothing in the viewer reads orientation today, and that images carrying
it open with the metadata ignored.

That is on purpose. A status of "in progress", with the design reasoning already written
down, is more use to a reader than a page that appears only once the feature does — and it
means the page is edited as support arrives rather than written from memory afterwards.

The sections worth reviewing are not the summary of the specification, which is a link
away, but the two a reader cannot get anywhere else:

  • What the viewer does. For RFC-4: annotate the view, never move a pixel, with the
    four reasons set out — including that a display flip would silently invalidate every
    stored ROI, which is not obvious from the spec.
  • Where vizarr departs from it. 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 one misplaced annotation serves nobody. That reasoning deserves
    better than a code comment.

It also lists the sample images (the conformance corpus, openable directly in the viewer)
and what the remote tests in #160 do and do not assert.

Both contributor guides

CONTRIBUTING.md and CLAUDE.md now say the RFC page changes in the same pull request as
the behaviour. A page describing last month's viewer is worse than no page, because
someone will believe it.

Checks

  • pnpm build:docs — clean, with treatWarningsAsErrors on
  • Verified the pages actually render and nest, rather than being silently ignored:
    documents/OME-NGFF_RFCs.html and documents/OME-NGFF_RFCs.RFC-4__Axis_Orientation.html,
    internal links rewritten to .html, no dangling .md
  • pnpm lint — clean

🤖 Generated with Claude Code

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 <[email protected]>
Copilot AI balanced review requested due to automatic review settings November 3, 2026 09:51

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

The docs development server does not watch the new RFC pages, and the RFC's orientation guidance could lead to reversed anatomical labels.

5 open issues
What changed in this PR

Adds a home for OME-NGFF RFC support documentation in the TypeDoc site, addressing the structure portion of #161. RFC-4 provides the first page, separating current support from planned behavior.

Changes:

  • Adds an RFC support index and an RFC-4 page covering metadata, design decisions, sample images, and conformance testing.
  • Registers the RFC documentation with TypeDoc, using front matter for child pages.
  • Updates both contributor guides to require documentation changes alongside RFC behavior changes.
File Description
typedoc.json Registers the RFC index as a project document.
docs/​rfcs/​rfc-4-axis-orientation.md Documents RFC-4 support status and planned handling.
docs/​rfcs/​index.md Adds the support table, status definitions, and child-page registration.
CONTRIBUTING.md Explains documentation commands and RFC maintenance requirements.
CLAUDE.md Adds matching guidance for maintaining RFC pages.

Review effort: Balanced

Comment thread typedoc.json
// 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"],
Comment on lines +44 to +45
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.
Comment thread docs/rfcs/rfc-4-axis-orientation.md Outdated
Comment on lines +65 to +67
- **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.
Comment on lines +76 to +84
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.
Comment thread docs/rfcs/rfc-4-axis-orientation.md Outdated
Comment on lines +125 to +142
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.
davehorsfall and others added 2 commits November 3, 2026 12:24
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]>
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 <[email protected]>
Base automatically changed from docs/site-deploy-and-design to dev November 3, 2026 13:11

This branch has not been deployed

No deployments
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