Repository navigation
docs: say what vizarr does with each OME-NGFF RFC - #162
Open
davehorsfall wants to merge 3 commits into
Open
davehorsfall wants to merge 3 commits into
davehorsfall wants to merge 3 commits into
Conversation
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]>
There was a problem hiding this comment.
🟡 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
Add RFC pages to the docs development watch list · New Separate plate-view policy from the RFC specification · New Map orientation into the view without reapplying the world transform · New Clarify orientation warnings are planned and metadata is ignored · New Mark RFC-4 checks as proposed until the test file lands · New
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
| // 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 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 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. |
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]>
This branch has not been deployed
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.


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), notdev. It editstypedoc.json,which #156 rewrites, and it needs that branch's
treatWarningsAsErrorsfor a broken linkto fail the build rather than reach a reader. Merge #156 first and this retargets to
devcleanly.
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
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:
four reasons set out — including that a display flip would silently invalidate every
stored ROI, which is not obvious from the spec.
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.mdandCLAUDE.mdnow say the RFC page changes in the same pull request asthe behaviour. A page describing last month's viewer is worse than no page, because
someone will believe it.
Checks
pnpm build:docs— clean, withtreatWarningsAsErrorsondocuments/OME-NGFF_RFCs.htmlanddocuments/OME-NGFF_RFCs.RFC-4__Axis_Orientation.html,internal links rewritten to
.html, no dangling.mdpnpm lint— clean🤖 Generated with Claude Code