From 848519df1170f56bc780614d99b0338fb1fd588f Mon Sep 17 00:00:00 2001 From: Juan Nunez-Iglesias Date: Tue, 15 Sep 2026 20:32:16 +1000 Subject: [PATCH 01/10] Update proposed axis naming rules to include type --- rfc/3/index.md | 31 +++++++++++++++++-------------- 1 file changed, 17 insertions(+), 14 deletions(-) diff --git a/rfc/3/index.md b/rfc/3/index.md index 1dd2b4ff9..165d5cf2f 100644 --- a/rfc/3/index.md +++ b/rfc/3/index.md @@ -335,24 +335,27 @@ document, taking as base the current development version: 2. The following lines are *added* to "multiscales metadata": -> 0. The length of the axis names MUST match the number of axes of the array. -> 1. *If* a dataset contains exactly 2 spatial dimensions, those dimensions -> SHOULD be named `y` and `x`, except where rule 4 applies. -> 2. *If* a dataset contains exactly 3 spatial dimensions, those dimensions -> SHOULD be named 'z', 'y', and 'x', except where rule 4 applies. -> 3. *If* a dataset contains exactly 1 time dimension, it should be named `t`. -> 4. When image data axes map straightforwardly to axes with common names in +> 1. The length of the axis names MUST match the number of axes of the array. +> 2. *If* a dataset contains exactly 2 spatial dimensions, those dimensions +> SHOULD be named 'y' and 'x', and have type "space", except where rule 5 +> applies. +> 3. *If* a dataset contains exactly 3 spatial dimensions, those dimensions +> SHOULD be named 'z', 'y', and 'x', and have type "space", except where +> rule 5 applies. +> 4. *If* a dataset contains exactly 1 time dimension, it should be named 't' +> and have type "time", except where rule 5 applies. +> 5. When image data axes map straightforwardly to axes with common names in > the relevant field of practice, those axes SHOULD be named according to > such conventions. For example, spatial frequency axes resulting from a -> Fourier transformation of `z', 'y', and 'x' SHOULD be named 'w', 'v', and +> Fourier transformation of 'z', 'y', and 'x' SHOULD be named 'w', 'v', and > `u`, respectively. Similarly, a temporal frequency axis resulting from -> a Fourier transformation of the `t` axis SHOULD be named `w` or `ω`. -> 5. Axis names MUST NOT be repeated within a dataset, and SHOULD NOT be +> a Fourier transformation of the 't' axis SHOULD be named 'w' or 'ω'. +> 6. Axis names MUST NOT be repeated within a dataset, and SHOULD NOT be > different only by upper/lower-case. For example, the same dataset SHOULD -> NOT have both an `X` and an `x` axis. -> 6. The order of the axes MUST match their ordering within the data if -> applicable. For example, if the axes are ordered as `DZYX`, where `D` is a -> field of displacement vectors, then the vectors must be ordered as `ZYX` +> NOT have both an 'X' and an 'x' axis. +> 7. The order of the axes MUST match their ordering within the data if +> applicable. For example, if the axes are ordered as 'DZYX', where 'D' is a +> field of displacement vectors, then the vectors must be ordered as 'ZYX' > within the array. 3. The following lines are amended as noted: From f8e094e9077c06cca96da6d28d6fb8c9af4024e8 Mon Sep 17 00:00:00 2001 From: Juan Nunez-Iglesias Date: Tue, 15 Sep 2026 20:46:44 +1000 Subject: [PATCH 02/10] Clarify w must not be both time and space frequencies --- rfc/3/index.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/rfc/3/index.md b/rfc/3/index.md index 165d5cf2f..3f1ce9ecd 100644 --- a/rfc/3/index.md +++ b/rfc/3/index.md @@ -349,7 +349,8 @@ document, taking as base the current development version: > such conventions. For example, spatial frequency axes resulting from a > Fourier transformation of 'z', 'y', and 'x' SHOULD be named 'w', 'v', and > `u`, respectively. Similarly, a temporal frequency axis resulting from -> a Fourier transformation of the 't' axis SHOULD be named 'w' or 'ω'. +> a Fourier transformation of a time axis SHOULD be named 'w' or, if 'w' is +> already in use in the given dataset, 'ω'. (See Rule 6.) > 6. Axis names MUST NOT be repeated within a dataset, and SHOULD NOT be > different only by upper/lower-case. For example, the same dataset SHOULD > NOT have both an 'X' and an 'x' axis. From eea5035abe1a00aa5bb76413b8f41b25313a79be Mon Sep 17 00:00:00 2001 From: Juan Nunez-Iglesias Date: Tue, 15 Sep 2026 20:47:56 +1000 Subject: [PATCH 03/10] should -> SHOULD --- rfc/3/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/rfc/3/index.md b/rfc/3/index.md index 3f1ce9ecd..18366688c 100644 --- a/rfc/3/index.md +++ b/rfc/3/index.md @@ -342,7 +342,7 @@ document, taking as base the current development version: > 3. *If* a dataset contains exactly 3 spatial dimensions, those dimensions > SHOULD be named 'z', 'y', and 'x', and have type "space", except where > rule 5 applies. -> 4. *If* a dataset contains exactly 1 time dimension, it should be named 't' +> 4. *If* a dataset contains exactly 1 time dimension, it SHOULD be named 't' > and have type "time", except where rule 5 applies. > 5. When image data axes map straightforwardly to axes with common names in > the relevant field of practice, those axes SHOULD be named according to From 92b1a37b027bdcfcc77fe71ecdf15be2e204b765 Mon Sep 17 00:00:00 2001 From: Juan Nunez-Iglesias Date: Tue, 15 Sep 2026 20:50:52 +1000 Subject: [PATCH 04/10] uniqueness within coord system --- rfc/3/index.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/rfc/3/index.md b/rfc/3/index.md index 18366688c..f6b02eb6b 100644 --- a/rfc/3/index.md +++ b/rfc/3/index.md @@ -351,9 +351,9 @@ document, taking as base the current development version: > `u`, respectively. Similarly, a temporal frequency axis resulting from > a Fourier transformation of a time axis SHOULD be named 'w' or, if 'w' is > already in use in the given dataset, 'ω'. (See Rule 6.) -> 6. Axis names MUST NOT be repeated within a dataset, and SHOULD NOT be -> different only by upper/lower-case. For example, the same dataset SHOULD -> NOT have both an 'X' and an 'x' axis. +> 6. Axis names MUST NOT be repeated within a coordinate system, and SHOULD NOT +> be different only by upper/lower-case. For example, the same dataset +> SHOULD NOT have both an 'X' and an 'x' axis. > 7. The order of the axes MUST match their ordering within the data if > applicable. For example, if the axes are ordered as 'DZYX', where 'D' is a > field of displacement vectors, then the vectors must be ordered as 'ZYX' From 82f8acd652e00c9d024572843b3b46b6b2eee4e8 Mon Sep 17 00:00:00 2001 From: Juan Nunez-Iglesias Date: Tue, 15 Sep 2026 21:13:21 +1000 Subject: [PATCH 05/10] More specific example for coordinate ordering --- rfc/3/index.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/rfc/3/index.md b/rfc/3/index.md index f6b02eb6b..1a6624bb2 100644 --- a/rfc/3/index.md +++ b/rfc/3/index.md @@ -355,9 +355,10 @@ document, taking as base the current development version: > be different only by upper/lower-case. For example, the same dataset > SHOULD NOT have both an 'X' and an 'x' axis. > 7. The order of the axes MUST match their ordering within the data if -> applicable. For example, if the axes are ordered as 'DZYX', where 'D' is a -> field of displacement vectors, then the vectors must be ordered as 'ZYX' -> within the array. +> applicable. For example, when representing a vector field representing +> particle if the axes are ordered as 'DZYX', where 'D' contains vector +> coordinates representing particle or fluid motion, then the vectors must +> be ordered as 'ZYX' within the array. 3. The following lines are amended as noted: From b469cc1674f923d0793f606f7ac6f720188c8492 Mon Sep 17 00:00:00 2001 From: Juan Nunez-Iglesias Date: Tue, 15 Sep 2026 21:26:03 +1000 Subject: [PATCH 06/10] Enumerate additional changes to the spec --- rfc/3/index.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/rfc/3/index.md b/rfc/3/index.md index 1a6624bb2..20a2ed1e0 100644 --- a/rfc/3/index.md +++ b/rfc/3/index.md @@ -375,7 +375,11 @@ document, taking as base the current development version: > Every Zarr array referred to by a path MUST have the same number of > dimensions and datatype.~~, and MUST NOT have more than 5 dimensions.~~ -No further changes to the specification document are proposed by this RFC. +Examples in the schema text will also be updated to match the above descriptive +changes, including any notes that prescribe a specific axis ordering. + +Further, axis and transformation schemas will be updated to remove the +restrictions on number, type, and order. ## Stakeholders From 09237183407590ea33620a08a54f44552cbd5065 Mon Sep 17 00:00:00 2001 From: Juan Nunez-Iglesias Date: Tue, 15 Sep 2026 23:20:06 +1000 Subject: [PATCH 07/10] Fix outdated forward-compatibility --- rfc/3/index.md | 13 ++++++------- 1 file changed, 6 insertions(+), 7 deletions(-) diff --git a/rfc/3/index.md b/rfc/3/index.md index 20a2ed1e0..b782365ac 100644 --- a/rfc/3/index.md +++ b/rfc/3/index.md @@ -409,13 +409,12 @@ This should be a small amount of work in most cases. ## Forward Compatibility -A draft proposal for [coordinate transformations][trafo spec] already includes -most of the changes proposed here, so we envision that this RFC is compatible -with future plans for the format. The proposal does currently limit the number -of dimensions of type "space" to at most 3, but that limit [could be -removed][space dims comment]. If this RFC is approved, the transformation -specification would need to be updated to reflect this. However, that is an easy -change and there seems to be sufficient support in the community for this idea. +An earlier version of this proposal described RFC-5 as a future change. As it +happens, RFC-5 was accepted before this one and this section (detailing how +RFC-5 would need to be modified) is no longer relevant: all the relevant +changes are included in this RFC. + +We have identified no further forward compatibility concerns. ## Drawbacks, risks, alternatives, and unknowns From de7093d3b8ca257c44372a679fcd82fc70c4d4c1 Mon Sep 17 00:00:00 2001 From: Juan Nunez-Iglesias Date: Tue, 15 Sep 2026 23:39:35 +1000 Subject: [PATCH 08/10] Update testing section --- rfc/3/index.md | 28 ++++++++++++++++++++-------- 1 file changed, 20 insertions(+), 8 deletions(-) diff --git a/rfc/3/index.md b/rfc/3/index.md index b782365ac..d2554b102 100644 --- a/rfc/3/index.md +++ b/rfc/3/index.md @@ -467,12 +467,15 @@ time. ## Testing -Datasets conforming to the new specification can be found at: +Datasets conforming to the proposed specification can be found at: https://github.com/clbarnes/ome-zarr-rfc3-data -This includes three synthetic datasets and (in progress, pull request #1) two -real (subsampled) datasets. +which provides three synthetic datasets, and + +https://github.com/image-coop/ome-zarr-data + +which includes two real-world downsampled datasets. HTTP access to the datasets is currently available at: @@ -486,11 +489,20 @@ https://test-bucket.image.coop/rfc3/flim-tmr31-3-reduced64.ome.zarr https://test-bucket.image.coop/rfc3/CP-Ti-abnormal-grains.zarr ``` -Implementations may check their compliance with this RFC using these datasets. -As a reminder, this RFC explicitly takes the position that partial -implementations are OK, and software is considered compliant if it provides -an informative error message (e.g. "The given dataset contains an unknown axis -'U', which is not supported by this viewer."). +Implementations may check their compatibility with the proposed changes using +the above datasets. + +Partial implementations that cannot support all the changes in this RFC are +explicitly allowed, but they should provide an informative error message when +rejecting a dataset; for example: "The given dataset contains an unknown axis +'U', which is not supported by this viewer." + +Additional valid and invalid metadata JSONs can be found in versions [0.9.dev1] +and the upcoming [0.9.dev2] (prospective link; not yet tagged) of [ngff-spec]. + +[0.9.dev1]: https://github.com/ome/ngff-spec/releases/tag/0.9.dev1 +[0.9.dev2]: https://github.com/ome/ngff-spec/releases/tag/0.9.dev2 +[ngff-spec]: https://github.com/ome/ngff-spec ## License From 7f13299ae75bf88932b84fc815ef5964377a9ed2 Mon Sep 17 00:00:00 2001 From: Juan Nunez-Iglesias Date: Tue, 15 Sep 2026 23:58:30 +1000 Subject: [PATCH 09/10] Add response --- rfc/3/responses/1/index.md | 102 +++++++++++++++++++++++++++++++++++++ 1 file changed, 102 insertions(+) create mode 100644 rfc/3/responses/1/index.md diff --git a/rfc/3/responses/1/index.md b/rfc/3/responses/1/index.md new file mode 100644 index 000000000..97ca2c3f5 --- /dev/null +++ b/rfc/3/responses/1/index.md @@ -0,0 +1,102 @@ +# RFC-3: Response 1 + +## Summary of Changes + +In response to review 2, RFC-3 has been updated to clarify certain +recommendations and add new ones, to help implementers make decisions. + +## Review feedback + +[Review 2](rfcs:rfc3:review2) provided a convenient checklist of all the +recommendations. It is included below for cross-reference, with responses or +resulting changes noted inline. + +### Minor changes + +- [ ] Add a statement that, if present, `t`, `c`, `z`, `y`, `x` axes SHOULD + occur in that order. + - We disagree with this recommendation, as one of the key motivations of + RFC is freedom to reorder these axes when acquiring data, or when + performing different analyses that may require different access + patterns. While the recommended ordering is optimal in many scenarios, + we continue to stress that documentation is the right place for this + recommendation, not the NGFF specification. +- [x] Carry the `type` recommendation into rules 1 to 3 and provide guidance + and examples on how and what to name custom types. + - Done in 848519d. Note that we have renumbered rules to start from 1, so + these are now 2 to 4. +- [x] Resolve the naming collision between the spatial and temporal frequency + axes in rule 4 so that rules 4 and 5 can both be satisfied. + - Done in f8e094e. +- [x] Use `SHOULD` in rule 3. + - Done in eea5035. +- [x] Say "within the same coordinate system" in rule 5, or state and reconcile + the stronger scope. + - Done in 92b1a37. +- [x] Scope rule 6 to axes whose component semantics the specification defines, + or reword it so the MUST can be checked. + - Rule 6 (now 7) includes the phrase "if applicable". Because we can't + anticipate all the data types where it would apply, we intentionally + leave room for interpretation. Having said that, the reviewers + correctly pointed out that the recommendation for displacement fields + was redundant with RFC-5. However, the recommendation applies more + generally than in the context of coordinate transformations. We have + therefore changed the example to a vector field representing particle + or fluid motion. +- [x] Make the list of specification changes exhaustive (hierarchy comment, + RFC-5 vector-axis placement wording, schema limits), or remove the "no + further changes" sentence and enumerate the known edits. + - Done in b469cc1. +- [x] Update Forward Compatibility to the 0.6rc0 and RFC-5 state and name the + remaining dimensional assumptions. + - Done in 0923718. +- [x] Distinguish dataset conformance from partial implementation support, and + cover the new MUST rules in the shared ngff-spec conformance cases, with + checks outside the schema for name uniqueness and rule 0. + - I have clarified the text in the testing section (de7093d). Additional + test cases in ome-ngff will be added after the 0.9.dev2 cleanup + ([ome/ngff-spec#201](https://github.com/ome/ngff-spec/pull/201)). + +### Not critical, but suggestions + +- [ ] Clarify when `c` is appropriate. + - For the moment, I prefer to leave this question open, since the answer + will be dependent on the use case, and may be refined in future RFCs + (such as a proposed visualization metadata RFC). +- [ ] Provide worked OME-Zarr examples for Zeiss CZI and Leica datasets + (including axis `type` values) and for DTI and frequency-domain (e.g., + MRI k-space) images. + - Although these would be nice to have, we consider that this work can + happen outside of this RFC. +- [ ] Consider name hygiene for the now unrestricted axis names: NFC-normalized + Unicode, no leading or trailing whitespace, no `/` or ASCII control + characters. + - It turns out that axis names are not currently restricted: they have + only been limited to tczyx by convention! (See [ome/ngff-spec#180].) + Therefore, the issue of name sanitisation predates this RFC and should + be handled separately. + +[ome/ngff-spec#180]: https://github.com/ome/ngff-spec/issues/180 + +### Additional comments / questions + +- Overlapping labels with an instance axis + + > Is the intent to allow `projectAxis` in that link, or to store such + masks as a separate multiscales image? Not a blocker. + + The RFC-3 doesn't take a position on this. RFC-8 explicitly allows for + standalone label images, which renders this question moot. A future RFC may + eliminate the required minimal set of transformations between labels and + images. + +- 'omero' 'channels' metadata + + > `omero` describes `channels` as "Array matching the c dimension size" and + > has `defaultT` and `defaultZ`. With several `channel` or `time` axes it is + > unclear which axis these refer to. A sentence stating that it applies to + > datasets with at most one channel and one time axis would suffice. + + Since axes have unique names, this case is already covered. + + From 48e3a9df0ba42d920724f98bb5d0c9a30908f65f Mon Sep 17 00:00:00 2001 From: Juan Nunez-Iglesias Date: Wed, 16 Sep 2026 12:17:12 +1000 Subject: [PATCH 10/10] Update changelog --- rfc/3/index.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/rfc/3/index.md b/rfc/3/index.md index d2554b102..e5b5c0485 100644 --- a/rfc/3/index.md +++ b/rfc/3/index.md @@ -541,5 +541,6 @@ This RFC is placed in the public domain. | Date | Description | Link | | ---------- | ---------------------------- | ---------------------------------------------------------------------------- | -| 2024-10-08 | RFC assigned and published | [https://github.com/ome/ngff/pull/239](https://github.com/ome/ngff/pull/239) | -| 2026-07-04 | Updated to address comments, elaborate on use cases, include specific changes to spec doc, and add test data | [https://github.com/ome/ngff/pull/560](https://github.com/ome/ngff/pull/560) | +| 2024-10-08 | RFC assigned and published | [ome/ngff#239](https://github.com/ome/ngff/pull/239) | +| 2026-07-04 | Updated to address comments, elaborate on use cases, include specific changes to spec doc, and add test data | [ome/ngff#560](https://github.com/ome/ngff/pull/560) | +| 2026-09-16 | Updated to address review 2: fix inconsistencies, clarify some recommendations, and update outdated text. | [ome/ngff#614](https://github.com/ome/ngff/pull/614) |