Skip to content

Commit b92a87f

Browse files
joshmoorejoshmoore
authored
Merge pull request #285 from normanrz/rfc-multiscale
2 parents 538668b + 2e43d24 commit b92a87f

File tree

1 file changed

+190
-0
lines changed

1 file changed

+190
-0
lines changed

‎rfc/6/index.md

+190
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,190 @@
1+
# RFC-6: Multiscale
2+
3+
Turn the `multiscales` array into a single `multiscale` object.
4+
5+
6+
## Status
7+
8+
This RFC is currently open for reviews (R1).
9+
10+
```{list-table} Record
11+
:widths: 8, 20, 20, 20, 15, 10
12+
:header-rows: 1
13+
:stub-columns: 1
14+
15+
* - Role
16+
- Name
17+
- GitHub Handle
18+
- Institution
19+
- Date
20+
- Status
21+
* - Author
22+
- Norman Rzepka
23+
- @normanrz
24+
- scalable minds
25+
- 2024-12-03
26+
-
27+
* - Author
28+
- David Stansby
29+
- @dstansby
30+
- University College London
31+
- 2024-12-03
32+
-
33+
* - Endorser
34+
- Davis Bennett
35+
- @d-v-b
36+
-
37+
- 2024-12-12
38+
-
39+
* - Endorser
40+
- Will Moore
41+
- @will-moore
42+
- OME, University of Dundee
43+
- 2024-12-12
44+
-
45+
* - Endorser
46+
- Lachlan Deakin
47+
- @LDeakin
48+
- Australian National University
49+
- 2024-12-17
50+
-
51+
* - Endorser
52+
- Joel Lüthi
53+
- @jluethi
54+
- BioVisionCenter, University of Zurich
55+
- 2024-12-18
56+
-
57+
* - Endorser
58+
- Eric Perlman
59+
- @perlman
60+
-
61+
- 2024-12-18
62+
-
63+
```
64+
65+
## Overview
66+
67+
This RFC proposes to change the `multiscales` array into a single `multiscale` object.
68+
69+
## Background
70+
71+
The current spec of OME-Zarr (version 0.5) defines that the metadata for a multiscale is stored in a `multiscales` array.
72+
73+
However, there seem to be only very few OME-Zarr images with mutltiple multiscales in the wild. There is one example from IDR: [4995115.zarr](https://ome.github.io/ome-ngff-validator/?source=https://uk1s3.embassy.ebi.ac.uk/idr/zarr/v0.4/idr0050A/4995115.zarr)
74+
75+
Additionally, most visualization and processing tools today simply process the first multiscale object in the `multiscales` array, ignoring any subsequent entries. Here is a selection of tools that only load the first multiscale object:
76+
77+
- [neuroglancer](https://github.com/google/neuroglancer/blob/master/src/datasource/zarr/ome.ts#L265-L310)
78+
- [vizarr](https://github.com/hms-dbmi/vizarr/blob/main/src/utils.ts#L88)
79+
- [itk-vtk](https://github.com/Kitware/itk-vtk-viewer/blob/master/src/IO/ZarrMultiscaleSpatialImage.js#L173)
80+
- [OMERO](https://github.com/ome/ZarrReader/issues/44)
81+
82+
The current spec seems to acknowledge that this is to be expected to some degree in the following excerpt:
83+
84+
> If only one multiscale is provided, use it. Otherwise, the user can choose by name, using the first multiscale as a fallback:
85+
>
86+
> ```python
87+
> datasets = []
88+
> for named in multiscales:
89+
> if named["name"] == "3D":
90+
> datasets = [x["path"] for x in named["datasets"]]
91+
> break
92+
> if not datasets:
93+
> # Use the first by default. Or perhaps choose based on chunk size.
94+
> datasets = [x["path"] for x in multiscales[0]["datasets"]]
95+
> ```
96+
97+
98+
This RFC aims to codify what already seems to be common practice by moving from a multiscales array to a single multiscale object. This will reduce complexity for implementations.
99+
100+
## Proposal
101+
102+
The OME-Zarr metadata in a `zarr.json` file of a multiscale MUST contain a single `multiscale` object. This replaces the current `multiscales` array.
103+
104+
Adapted example from the current spec:
105+
```json
106+
{
107+
"zarr_format": 3,
108+
"node_type": "group",
109+
"attributes": {
110+
"ome": {
111+
"version": "0.5",
112+
"multiscale": {
113+
"name": "example",
114+
"axes": [
115+
{ "name": "t", "type": "time", "unit": "millisecond" },
116+
{ "name": "c", "type": "channel" },
117+
{ "name": "z", "type": "space", "unit": "micrometer" },
118+
{ "name": "y", "type": "space", "unit": "micrometer" },
119+
{ "name": "x", "type": "space", "unit": "micrometer" }
120+
],
121+
"datasets": [
122+
{
123+
"path": "0",
124+
"coordinateTransformations": [
125+
{
126+
// the voxel size for the first scale level (0.5 micrometer)
127+
"type": "scale",
128+
"scale": [1.0, 1.0, 0.5, 0.5, 0.5]
129+
}
130+
]
131+
},
132+
{
133+
"path": "1",
134+
"coordinateTransformations": [
135+
{
136+
// the voxel size for the second scale level (downscaled by a factor of 2 -> 1 micrometer)
137+
"type": "scale",
138+
"scale": [1.0, 1.0, 1.0, 1.0, 1.0]
139+
}
140+
]
141+
}
142+
],
143+
"coordinateTransformations": [
144+
{
145+
// the time unit (0.1 milliseconds), which is the same for each scale level
146+
"type": "scale",
147+
"scale": [0.1, 1.0, 1.0, 1.0, 1.0]
148+
}
149+
]
150+
}
151+
}
152+
}
153+
}
154+
```
155+
156+
For data that needs to have multiple multiscales, it is encouraged to store them in separate OME-Zarr datasets with their own OME-Zarr metadata.
157+
158+
159+
## Requirements
160+
161+
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [IETF RFC 2119](https://tools.ietf.org/html/rfc2119)
162+
163+
164+
## Stakeholders
165+
166+
The main stakeholders for this RFC are OME-Zarr tool developers and existing OME-Zarr image providers. Developers will have to update their implementations to account for the breaking change. Because this change is not backwards compatible, it will require a change to existing OME-Zarr images to make them compatible with this RFC.
167+
168+
### Socialization
169+
170+
* OME-NGFF hackathon Zurich 2024
171+
* [Github issue](https://github.com/ome/ngff/issues/205)
172+
173+
## Implementation
174+
175+
Many visualization and processing tools already expect only a single multiscale.
176+
This proposal will reduce complexity for implementations.
177+
178+
Examples of implementations that only work with a single multiscale:
179+
- [neuroglancer](https://github.com/google/neuroglancer/blob/master/src/datasource/zarr/ome.ts#L265-L310)
180+
- [vizarr](https://github.com/hms-dbmi/vizarr/blob/main/src/utils.ts#L88)
181+
- [itk-vtk](https://github.com/Kitware/itk-vtk-viewer/blob/master/src/IO/ZarrMultiscaleSpatialImage.js#L173)
182+
- [OMERO](https://github.com/ome/ZarrReader/issues/44)
183+
184+
## Drawbacks, risks, alternatives, and unknowns
185+
186+
This is a breaking change with the typical drawbacks of breaking changes.
187+
188+
## Compatibility
189+
190+
This proposal is not backwards compatible and should be released in a new version of OME-Zarr.

0 commit comments

Comments
 (0)