](https://orcid.org/0000-0003-4028-811X)
## Abstract
@@ -158,97 +158,23 @@ The OME-Zarr Metadata version MUST be consistent within a hierarchy.
}
```
-## "axes" metadata
-(axes-md)=
+### "coordinateSystems" metadata
+(coordinate-systems-md)=
-"axes" describes the dimensions of a coordinate systems and adds an interpretation to the data along that dimension.
-A named collection of axes forms a [coordinate system](#coord-sys-md).
-It is a list of dictionaries, where each dictionary describes a dimension (axis) and:
-
-- MUST contain the field "name" that gives the name for this dimension.
- The values MUST be unique across all "name" fields.
-- SHOULD contain the field "type".
- It SHOULD be one of the strings "array", "space", "time", "channel", "coordinate", or "displacement"
- but MAY take other string values for custom axis types that are not part of this specification yet.
-- SHOULD contain the field "unit" to specify the physical unit of this dimension.
- The value SHOULD be one of the following strings, which are valid units according to UDUNITS-2.
- - Units for "space" axes:
- 'angstrom', 'attometer', 'centimeter', 'decimeter', 'exameter', 'femtometer', 'foot', 'gigameter', 'hectometer', 'inch', 'kilometer', 'megameter', 'meter', 'micrometer', 'mile', 'millimeter', 'nanometer', 'parsec', 'petameter', 'picometer', 'terameter', 'yard', 'yoctometer', 'yottameter', 'zeptometer', 'zettameter'
- - Units for "time" axes:
- 'attosecond', 'centisecond', 'day', 'decisecond', 'exasecond', 'femtosecond', 'gigasecond', 'hectosecond', 'hour', 'kilosecond', 'megasecond', 'microsecond', 'millisecond', 'minute', 'nanosecond', 'petasecond', 'picosecond', 'second', 'terasecond', 'yoctosecond', 'yottasecond', 'zeptosecond', 'zettasecond'
-- MAY contain the field "longName".
- The value MUST be a string, and can provide a longer name or description of an axis and its properties.
-
-The "axes" are used as part of [multiscales metadata](#multiscales-md).
-The length of "axes" MUST be equal to the number of dimensions of the arrays that contain the image data.
-
-The "dimension_names" attribute MUST be included in the `zarr.json` of the Zarr array of a multiscale level and MUST match the names in the "axes" metadata.
-
-````{admonition} Example
-
-Examples of valid axes:
-
-```json
-[
- {"name": "x", "type": "space", "unit": "micrometer"},
- {"name": "t", "type": "time", "unit": "second", "longName": "Unix Epoch time"},
- {"name": "c", "type": "channel", "discrete": true},
- {"name": "i0", "type": "array"},
- {"name": "c", "type": "coordinate", "discrete" : true },
- {"name": "v", "type": "displacement", "discrete": true },
- {"name": "freq", "type": "frequency", "unit": "megahertz"}
-]
-```
-````
-
-Arrays are inherently discrete (see Array coordinate systems, below) but are often used to store discrete samples of a continuous variable.
-The continuous values "in between" discrete samples can be retrieved using an *interpolation* method.
-If an axis is continuous (`"discrete" : false`), it indicates that interpolation is well-defined.
-Axes representing `space` and `time` are usually continuous.
-Similarly, joint interpolation across axes is well-defined only for axes of the same `type`.
-In contrast, discrete axes (`"discrete" : true`) may be indexed only by integers.
-Axes of representing a `channel`, `coordinate`, or `displacement` are usually discrete.
-
-Note: The most common methods for interpolation are "nearest neighbor", "linear", "cubic", and "windowed sinc".
-Here, we refer to any method that obtains values at real valued coordinates using discrete samples as an "interpolator".
-As such, label images may be interpolated using "nearest neighbor" to obtain labels at points along the continuum.
-
-````{admonition} Example
-
-For the coordinate system:
-
-```json
-{
- "name" : "index and interpolation",
- "axes" : [
- {"name": "t", "type": "time"},
- {"name": "c", "type": "channel", "discrete": true},
- {"name": "y", "type": "space"},
- {"name": "x", "type": "space"}
- ]
-}
-```
-
-Indexing an image at the point `(0.1, 0.2, 0.3, 0.4)` is not valid,
-because the value of the first coordinate (`0.1`) refers to the discrete axis `"c"`.
-Indexing an image at the point `(1, 0.2, 0.3, 0.4)` is valid.
-
-````
-
-## "coordinateSystems" metadata
-
-(coord-sys-md)=
-
-A "coordinate system" is a collection of "axes" / dimensions with a name.
+A `coordinateSystem` is a JSON object with a "name" field and a "axes" field.
Every coordinate system:
-
- MUST contain the field "name".
- The value MUST be a non-empty string that is unique among `coordinateSystem`s.
-- MUST contain the field "axes", whose value is an array of valid "axes".
+ The value MUST be a non-empty string that is unique among all entries under `coordinateSystems`.
+- MUST contain the field "axes", whose value is an array of valid "axes" (see below).
+
+The elements of `"axes"` correspond to the index of each array dimension and coordinates for points in that coordinate system.
+For the below example, the `"x"` dimension is the last dimension.
+The "dimensionality" of a coordinate system is indicated by the length of its "axes" array.
+The "volume_micrometers" example coordinate system below is three dimensional (3D).
````{admonition} Example
-Example of valid `coordinateSystems` metadata:
+Coordinate Systems metadata example
```json
{
@@ -262,150 +188,126 @@ Example of valid `coordinateSystems` metadata:
```
````
-The order of the `"axes"` list matters and defines the index of each array dimension and coordinates for points in that coordinate system.
-For the above example, the `"x"` dimension is the last dimension.
-The "dimensionality" of a coordinate system is indicated by the length of its "axes" array.
-The "volume_micrometers" example coordinate system above is three dimensional (3D).
-
-The axes of a coordinate system (see below) give information about the types, units, and other properties of the coordinate system's dimensions.
-Axis `name`s may contain semantically meaningful information, but can be arbitrary.
-As a result, two coordinate systems that have identical axes in the same order may not be "the same"
-in the sense that measurements at the same point refer to different physical entities and therefore should not be analyzed jointly.
+The axes of a coordinate system (see below) give information
+about the types, units, and other properties of the coordinate system's dimensions.
+Axis names may contain semantically meaningful information, but can be arbitrary.
+As a result, two coordinate systems that have identical axes in the same order
+may not be "the same" in the sense that measurements at the same point
+refer to different physical entities and therefore should not be analyzed jointly.
Tasks that require images, annotations, regions of interest, etc.,
-SHOULD ensure that they are in the same coordinate system (same name, with identical axes)
+SHOULD ensure that they are in the same coordinate system (same name and location within the Zarr hierarchy, with identical axes)
or can be transformed to the same coordinate system before doing analysis.
-See the example below.
+See the [example below](#spec:example:coordinate_transformation).
-````{admonition} Example
+#### "axes" metadata
-Two instruments simultaneously image the same sample from two different angles,
-and the 3D data from both instruments are calibrated to "micrometer" units.
-Two samples are collected ("sampleA" and "sampleB").
-An analysis of sample A requires measurements from both instruments' images at certain points in space.
-Suppose a region of interest (ROI) is determined from the image obtained from instrument 2,
-but quantification from that region is needed for instrument 1.
-Since measurements were collected at different angles,
-a measurement by instrument 1 at the point with coordinates (x,y,z) may not correspond to the measurement at the same point in instrument 2
-(i.e., it may not be the same physical location in the sample).
-To analyze both images together, they must be in the same coordinate system.
+"axes" describes the dimensions of a coordinate systems
+and adds an interpretation to the samples along that dimension.
-The set of [coordinate transformations](#trafo-md) encodes relationships between coordinate systems, specifically, how to
-convert points and images to different coordinate systems.
-Implementations can apply the coordinate transform to images or points in coordinate system "sampleA_instrument2" to bring them into the "sampleA_instrument1" coordinate system.
-In this case, the ROI should be transformed to the "sampleA_image1" coordinate system,
-then used for quantification with the instrument 1 image.
+It is a list of dictionaries,
+where each dictionary describes a dimension (axis) and:
+- MUST contain the field "name" that gives the name for this dimension.
+ The values MUST be unique across all "name" fields in the same coordinate system.
+- SHOULD contain the field "type".
+ It SHOULD be one of the strings "array", "space", "time", "channel", "coordinate", or "displacement"
+ but MAY take other string values for custom axis types that are not part of this specification yet.
+- MAY contain the field "discrete".
+ The value MUST be a boolean,
+ and is `true` if the axis represents a discrete dimension (see below for details).
+- SHOULD contain the field "unit" to specify the physical unit of this dimension.
+ The value SHOULD be one of the following strings,
+ which are valid units according to UDUNITS-2.
+ - Units for "space" axes: 'angstrom', 'attometer', 'centimeter', 'decimeter', 'exameter', 'femtometer', 'foot', 'gigameter', 'hectometer', 'inch', 'kilometer', 'megameter', 'meter', 'micrometer', 'mile', 'millimeter', 'nanometer', 'parsec', 'petameter', 'picometer', 'terameter', 'yard', 'yoctometer', 'yottameter', 'zeptometer', 'zettameter'
+ - Units for "time" axes: 'attosecond', 'centisecond', 'day', 'decisecond', 'exasecond', 'femtosecond', 'gigasecond', 'hectosecond', 'hour', 'kilosecond', 'megasecond', 'microsecond', 'millisecond', 'minute', 'nanosecond', 'petasecond', 'picosecond', 'second', 'terasecond', 'yoctosecond', 'yottasecond', 'zeptosecond', 'zettasecond'
+- MAY contain the field "longName".
+ The value MUST be a string,
+ and can provide a longer name or description of an axis and its properties.
-```json
-"coordinateSystems" : [
- {
- "name" : "sampleA-instrument1",
- "axes" : [
- {"name": "z", "type": "space", "unit": "micrometer"},
- {"name": "y", "type": "space", "unit": "micrometer"},
- {"name": "x", "type": "space", "unit": "micrometer"}
- ]
- },
- {
- "name" : "sampleA-instrument2",
- "axes" : [
- {"name": "z", "type": "space", "unit": "micrometer"},
- {"name": "y", "type": "space", "unit": "micrometer"},
- {"name": "x", "type": "space", "unit": "micrometer"}
- ]
- }
-],
-"coordinateTransformations": [
- {
- "type": "affine",
- "path": "../sampleA_instrument2-to-instrument1",
- "input": "sampleA_instrument2",
- "output": "sampleA_instrument1"
- }
-]
-```
+The length of "axes" MUST be equal to the number of dimensions of the arrays that contain the image data.
-````
+Arrays are inherently discrete (see Array coordinate systems, below)
+but are often used to store discrete samples of a continuous variable.
+The continuous values "in between" discrete samples can be retrieved using an *interpolation* method.
+If an axis is continuous (`"discrete" : false`), it indicates that interpolation is well-defined.
+Axes representing `space` and `time` are usually continuous.
+Similarly, joint interpolation across axes is well-defined only for axes of the same `type`.
+In contrast, discrete axes (`"discrete" : true`) may be indexed only by integers.
+Axes representing a channel, coordinate, or displacement are usually discrete.
-### Array coordinate systems
+```{note}
+The most common methods for interpolation are "nearest neighbor", "linear", "cubic", and "windowed sinc".
+Here, we refer to any method that obtains values at real-valued coordinates using discrete samples as an "interpolator".
+As such, label images may be interpolated using "nearest neighbor" to obtain labels at points along the continuum.
+```
-The dimensions of an array do not have an interpretation until they are associated with a coordinate system via a coordinate transformation.
+#### Array coordinate systems
+
+The dimensions of an array do not have an interpretation
+until they are associated with a coordinate system via a coordinate transformation.
Nevertheless, it can be useful to refer to the "raw" coordinates of the array.
Some applications might prefer to define points or regions-of-interest in "pixel coordinates" rather than "physical coordinates," for example.
Indicating that choice explicitly will be important for interoperability.
This is possible by using **array coordinate systems**.
Every array has a default coordinate system whose parameters need not be explicitly defined.
-Its name is the path to the array in the container, its axes have `"type":"array"`, are unitless, and have default "name"s.
-The ith axis has `"name":"dim_i"`
-(these are the same default names used by [xarray](https://docs.xarray.dev/en/stable/user-guide/terminology.html)).
+The dimensionality of each array coordinate system equals the dimensionality of its corresponding Zarr array.
+Its name is the path to the array in the container,
+its axes have `"type": "array"`, are unitless, and have default names.
+The i-th axis has `"name": "dim_i"` (these are the same default names used by [xarray](https://docs.xarray.dev/en/stable/user-guide/terminology.html)).
+As with all coordinate systems, the dimension names must be unique and non-null.
````{admonition} Example
-For example, a 3D array at path `0` defines the coordinate system:
-
```json
{
- "name" : "0",
+ "arrayCoordinateSystem" : {
+ "name" : "myDataArray",
"axes" : [
- {"name": "dim_0", "type": "array"},
- {"name": "dim_1", "type": "array"},
- {"name": "dim_2", "type": "array"}
+ {"name": "dim_0", "type": "array"},
+ {"name": "dim_1", "type": "array"},
+ {"name": "dim_2", "type": "array"}
]
+ }
}
-```
-
-though this object should not and need not explicitly appear in metadata.
-
-````
-
-The dimensionality of each array coordinate system equals the dimensionality of its corresponding zarr array.
-The axis with name `"dim_i"` is the ith element of the `"axes"` list.
-The axes and their order align with the `shape` attribute in the zarr array attributes,
-and whose data depends on the byte order used to store chunks.
-As described in the [zarr array metadata](https://zarr-specs.readthedocs.io/en/latest/v3/core/v3.0.html#array-metadata),
-the last dimension of an array in "C" order are stored contiguously on disk or in-memory when directly loaded.
-
-````{admonition} Example
-For example, if `0/zarr.json` contains:
+```
-```json
+For example, if 0/zarr.json contains:
+```jsonc
{
"zarr_format": 3,
"node_type": "array",
"shape": [4, 3, 5],
- ...
+ //...
}
```
Then `dim_0` has length 4, `dim_1` has length 3, and `dim_2` has length 5.
+
````
+The axes and their order align with the shape of the corresponding zarr array,
+and whose data depends on the byte order used to store chunks.
+As described in the [Zarr array metadata](https://zarr.readthedocs.io/en/stable/spec/v3.html#arrays),
+the last dimension of an array in "C" order are stored contiguously on disk or in-memory when directly loaded.
+
The name and axes names MAY be customized by including a `arrayCoordinateSystem` field
in the user-defined attributes of the array whose value is a coordinate system object.
The length of `axes` MUST be equal to the dimensionality.
The value of `"type"` for each object in the axes array MUST equal `"array"`.
-````{admonition} Example
-
-
-```{literalinclude} examples/coordSystems/arrayCoordSys.json
-```
-
-Note that dimension `i` is contiguous in memory.
-
-````
-
-### Coordinate convention
+#### Coordinate convention
**The pixel/voxel center is the origin of the continuous coordinate system.**
-It is vital to consistently define relationship between the discrete/array and continuous/interpolated coordinate systems.
-A pixel/voxel is the continuous region (rectangle) that corresponds to a single sample in the discrete array,
-i.e., the area corresponding to nearest-neighbor (NN) interpolation of that sample.
-The center of a 2d pixel corresponding to the origin `(0,0)` in the discrete array is the origin of the continuous coordinate system `(0.0, 0.0)` (when the transformation is the identity).
-The continuous rectangle of the pixel is given by the half-open interval `[-0.5, 0.5) x [-0.5, 0.5)`
-(i.e., -0.5 is included, +0.5 is excluded).
-See chapter 4 and figure 4.1 of the ITK Software Guide [[itk]].
+It is vital to consistently define relationship
+between the discrete/array and continuous/interpolated coordinate systems.
+A pixel/voxel is the continuous region (rectangle) that corresponds to a single sample in the discrete array, i.e.,
+the area corresponding to nearest-neighbor (NN) interpolation of that sample.
+The center of a 2d pixel corresponding to the origin `(0,0)` in the discrete array
+is the origin of the continuous coordinate system `(0.0, 0.0)` (when the transformation is the identity).
+The continuous rectangle of the pixel is given
+by the half-open interval `[-0.5, 0.5) x [-0.5, 0.5)` (i.e., -0.5 is included, +0.5 is excluded).
+See chapter 4 and figure 4.1 of the ITK Software Guide.
## bioformats2raw.layout
@@ -437,8 +339,7 @@ series.ome.zarr # One converted fileset from bioformats2raw
```
### bf2raw-attributes
-
-(bf2raw-attributes)=
+(bf2raw-attributes-md)=
The OME-Zarr Metadata in the top-level `zarr.json` file must contain the `bioformats2raw.layout` key:
@@ -451,6 +352,7 @@ but the "plate" key MUST also be present, takes precedence and parsing of such d
It is not possible to mix collections of images with plates at present.
```{literalinclude} examples/bf2raw/plate.json
+:language: json
```
The OME-Zarr Metadata in the `zarr.json` file within the OME group may contain the "series" key:
@@ -491,217 +393,255 @@ Conforming readers:
- MAY ignore other groups or arrays under the root of the hierarchy.
## "coordinateTransformations" metadata
+(coord-trafo-md)=
-(trafo-md)=
-
-"coordinateTransformations" describe the mapping between two coordinate systems (defined by "axes").
+"coordinateTransformations" describe the mapping between two coordinate systems (defined by [coordinateSystems](#coordinate-systems-md)).
For example, to map an array's discrete coordinate system to its corresponding physical coordinates.
Coordinate transforms are in the "forward" direction.
-They represent functions from *points* in the input space to *points* in the output space.
+This means they represent functions from *points* in the input space to *points* in the output space
+(see [example below](#spec:example:coordinate_transformation_scale)).
+
+They:
-- MUST contain the field "type".
+- MUST contain the field "type" (string).
- MUST contain any other fields required by the given "type" (see table below).
-- MUST contain the field "output", unless part of a `sequence` or `inverseOf` (see details).
-- MUST contain the field "input", unless part of a `sequence` or `inverseOf` (see details).
-- MAY contain the field "name". Its value MUST be unique across all "name" fields for coordinate transformations.
+- MUST contain the field "output" (string),
+ unless part of a `sequence` or `inverseOf` (see details).
+- MUST contain the field "input" (string),
+ unless part of a `sequence` or `inverseOf` (see details).
+- MAY contain the field "name" (string).
+ Its value MUST be unique across all "name" fields for coordinate transformations.
- Parameter values MUST be compatible with input and output space dimensionality (see details).
-| `identity` - | - | The identity transformation is the default transformation and is typically not explicitly defined. - | |||
|---|---|---|---|---|---|
| `mapAxis` - | `"mapAxis":Dict[String:String]` - | A `maxAxis` transformation specifies an axis permutation as a map between axis names. - | |||
| `translation` - | one of: `"translation":List[number]`, `"path":str` - | translation vector, stored either as a list of numbers (`"translation"`) or as binary data at a location - in this container (`path`). - | |||
| `scale` - | one of: `"scale":List[number]`, `"path":str` - | scale vector, stored either as a list of numbers (`scale`) or as binary data at a location in this - container (`path`). - | |||
| `affine` - | one of: `"affine":List[List[number]]`, `"path":str` - | affine transformation matrix stored as a flat array stored either with json uing the affine field - or as binary data at a location in this container (path). If both are present, the binary values at path should be used. - | |||
| `rotation` - | one of: `"rotation":List[number]`, `"path":str` - | rotation transformation matrix stored as an array stored either - with json or as binary data at a location in this container (path). - If both are present, the binary parameters at path are used. - | |||
| `sequence` - | `"transformations":List[Transformation]` - | A sequence of transformations, Applying the sequence applies the composition of all transforms in the list, in order. - | |||
| `displacements` - | `"path":str` `"interpolation":str` - | Displacement field transformation located at (path). - | |||
| `coordinates` - | `"path":str` `"interpolation":str` - | Coordinate field transformation located at (path). - | |||
| `inverseOf` - | `"transform":Transform` - | The inverse of a transformation. Useful if a transform is not closed-form invertible. See Forward and inverse for details and examples. - | |||
| `bijection` - | `"forward":Transform` `"inverse":Transform` - | Explicitly define an invertible transformation by providing a forward transformation and its inverse. - | |||
| `byDimension` - | `"transformations":List[Transformation]` - | Define a high dimensional transformation using lower dimensional transformations on subsets of
- dimensions.
-
- | type | fields | description
- | |
`"translation":List[number]`,
`"path":str` | Translation vector, stored either as a list of numbers (`"translation"`) or as a zarr array at a location in this container (`path`). | +| [`scale`](#scale-md) | one of:
`"scale":List[number]`,
`"path":str` | Scale vector, stored either as a list of numbers (`scale`) or as a zarr array at a location in this container (`path`). | +| [`affine`](#affine-md) | one of:
`"affine":List[List[number]]`,
`"path":str` | 2D affine transformation matrix stored either with JSON (`affine`) or as a zarr array at a location in this container (`path`). | +| [`rotation`](#rotation-md) | one of:
`"rotation":List[List[number]]`,
`"path":str` | 2D rotation transformation matrix stored as an array stored either with json (`rotation`) or as a zarr array at a location in this container (`path`).| +| [`sequence`](#sequence-md) | `"transformations":List[Transformation]` | sequence of transformations. Applying the sequence applies the composition of all transforms in the list, in order. | +| [`displacements`](#coordinates-displacements-md) | `"path":str`
`"interpolation":str` | Displacement field transformation located at `path`. | +| [`coordinates`](#coordinates-displacements-md) | `"path":str`
`"interpolation":str` | Coordinate field transformation located at `path`. | +| [`inverseOf`](#inverseof-md) | `"transformation":Transformation` | The inverse of a transformation. Useful if a transform is not closed-form invertible. See forward and inverse of [bijections](#bijection-md) for details and examples. | +| [`bijection`](#bijection-md) | `"forward":Transformation`
`"inverse":Transformation` | An invertible transformation providing an explicit forward transformation and its inverse. | +| [`byDimension`](#bydimension-md) | `"transformations":List[Transformation]`,
`"input_axes": List[str]`,
`"output_axes": List[str]` | A high dimensional transformation using lower dimensional transformations on subsets of dimensions. | + +Implementations SHOULD prefer to store transformations as a sequence of less expressive transformations where possible +(e.g., sequence[translation, rotation], instead of affine transformation with translation/rotation). + +::::{admonition} Example +(spec:example:coordinate_transformation_scale)= +:class: dropdown -Conforming readers: +```json +{ + "coordinateSystems": [ + { "name": "in", "axes": [{"name": "j"}, {"name": "i"}] }, + { "name": "out", "axes": [{"name": "y"}, {"name": "x"}] } + ], + "coordinateTransformations": [ + { + "type": "scale", + "scale": [2, 3.12], + "input": "in", + "output": "out" + } + ] +} + +``` + +For example, the scale transformation above defines the function: + +``` +x = 3.12 * i +y = 2 * j +``` + +i.e., the mapping from the first input axis to the first output axis is determined by the first scale parameter. +:::: +Conforming readers: - MUST parse `identity`, `scale`, `translation` transformations; -- SHOULD parse `mapAxis`, `affine` transformations; +- SHOULD parse `mapAxis`, `affine`, `rotation` transformations; +- SHOULD display an informative warning if encountering transformations that cannot be parsed or displayed by a viewer; - SHOULD be able to apply transformations to points; - SHOULD be able to apply transformations to images; -Coordinate transformations from array to physical coordinates MUST be stored in [multiscales](#multiscales-md). -Transformations between different images MUST be stored in the attributes of a parent zarr group. -For transformations that store data or parameters in a zarr array, those zarr arrays SHOULD be stored in a zarr group `"coordinateTransformations"`. +Coordinate transformations can be stored in multiple places to reflect different usecases. + +- Transformations in individual multiscale datasets represent a special case of transformations + and are explained [below](#multiscales-md). +- Additional transformations for single multiscale images MUST be stored under a field `coordinateTransformations` + in the multiscales dictionaries. + This `coordinateTransformations` field MUST contain a list of valid [transformations](#trafo-types-md). +- Transformations between two or more images MUST be stored in the attributes of a parent zarr group. + For transformations that store data or parameters in a zarr array, + those zarr arrays SHOULD be stored in a zarr group called "coordinateTransformations". -```text + +
store.zarr # Root folder of the zarr store │ ├── zarr.json # coordinate transformations describing the relationship between two image coordinate systems │ # are stored in the attributes of their parent group. -│ # transformations between 'volume' and 'crop' coordinate systems are stored here. +│ # transformations between coordinate systems in the 'volume' and 'crop' multiscale images are stored here. │ -├── coordinateTransformations # transformations that use array storage go in a "coordinateTransformations" zarr group. +├── coordinateTransformations # transformations that use array storage for their parameters should go in a zarr group named "coordinateTransformations". │ └── displacements # for example, a zarr array containing a displacement field │ └── zarr.json │ ├── volume -│ ├── zarr.json # group level attributes (multiscales) -│ └── 0 # a group containing the 0th scale -│ └── image # a zarr array -│ └── zarr.json # physical coordinate system and transformations here -│ # the array attributes +│ ├── zarr.json # group level attributes (multiscales) +│ └── 0 # a group containing the 0th scale +│ └── image # a zarr array +│ └── zarr.json # physical coordinate system and transformations here └── crop - ├── .zattrs # group level attributes (multiscales) - └── 0 # a group containing the 0th scale - └── image # a zarr array - └── zarr.json # physical coordinate system and transformations here - # the array attributes -``` - -### Additional details - -Most coordinate transformations MUST specify their input and output coordinate systems -using `input` and `output` with a string value corresponding to the name of a coordinate system. -The coordinate system's name may be the path to an array, and therefore may not appear in the list of coordinate systems. + ├── zarr.json # group level attributes (multiscales) + └── 0 # a group containing the 0th scale + └── image # a zarr array + └── zarr.json # physical coordinate system and transformations here ++ +::::{admonition} Example +:class: dropdown +(spec:example:coordinate_transformation)= +Two instruments simultaneously image the same sample from two different angles, +and the 3D data from both instruments are calibrated to "micrometer" units. +An analysis of sample A requires measurements from images taken from both instruments at certain points in space. +Suppose a region of interest (ROI) is determined from the image obtained from instrument 2, +but quantification from that region is needed for instrument 1. +Since measurements were collected at different angles, +a measurement by instrument 1 at the point with image array coordinates (x,y,z) +may not correspond to the measurement at the same array coordinates in instrument 2 +(i.e., it may not be the same physical location in the sample). +To analyze both images together, they must be transformed to a common coordinate system. -Exceptions are if the the coordinate transformation appears in the `transformations` list of a `sequence` or is the `transformation` of an `inverseOf` transformation. -In these two cases input and output SHOULD be omitted -(see below for details). +The set of coordinate transformations encodes relationships between coordinate systems, +specifically, how to convert points from one coordinate system to another. +Implementations can apply the coordinate transform to images or points +in coordinate system "sampleA_instrument2" to bring them into the "sampleA_instrument1" coordinate system. +In this case, image data within the ROI defined in image2 should be transformed to the "sampleA_image1" coordinate system, +then used for quantification with the instrument 1 image. -Transformations in the `transformations` list of a `byDimensions` transformation MUST provide `input` and `output` -as arrays of strings corresponding to axis names of the parent transformation's input and output coordinate systems -(see below for details). +The `coordinateTransformations` in the parent-level metadata would contain the following data. +The transformation parameters are stored in a separate zarr-group +under `coordinateTransformations/sampleA_instrument2-to-instrument1` as shown above. -````{admonition} Example +```json +"coordinateTransformations": [ + { + "type": "affine", + "path": "coordinateTransformations/sampleA_instrument2-to-instrument1", + "input": "sampleA_instrument2", + "output": "sampleA_instrument1" + } +] +``` -The sequence transformation's input corresponds to an array coordinate system at path "my/array". +And the image at the path `sampleA_instrument1` would have the following as the first coordinate system: ```json -"coordinateSystems" : [ - { "name" : "in", "axes" : [{"name" : "j"}, {"name":"i"}] }, - { "name" : "outScale", "axes" : [{"name" : "y"}, {"name":"x"}] }, - { "name" : "outSeq", "axes" : [{"name" : "y"}, {"name":"x"}] }, - { "name" : "outInv", "axes" : [{"name" : "y"}, {"name":"x"}] }, - { "name" : "outByDim", "axes" : [{"name" : "y"}, {"name":"x"}] } -], -"coordinateTransformations" : [ - { - "type": "scale", - "input" : "in", - "output" : "outScale", - "scale" : [ 0.5, 1.2 ] - }, +"coordinateSystems": [ { - "type" : "sequence", - "input" : "my/array", - "output" : "outSeq", - "transformations" : [ - { "type": "scale", "scale" : [ 0.5, 0.6 ] }, - { "type": "translation", "translation" : [ 2, 5 ] } + "name": "sampleA-instrument1", + "axes": [ + {"name": "z", "type": "space", "unit": "micrometer"}, + {"name": "y", "type": "space", "unit": "micrometer"}, + {"name": "x", "type": "space", "unit": "micrometer"} ] }, +] +``` + +The image at path `sampleA_instrument2` would have this as the first listed coordinate system: + +```json +[ { - "type": "inverseOf", - "input" : "in", - "output" : "outInv", - "transformation" : { - "type": "displacements", - "path": "path/to/displacements" - } - }, - { - "type": "byDimension", - "input" : "in", - "output" : "outDim", - "transformations" : [ - { "type" : "translation", "translation" : [1], "input" : ["i"], "output" : ["x"]}, - { "type" : "scale", "scale" : [2.0], "input" : ["j"], "output" : ["y"]} + "name": "sampleA-instrument2", + "axes": [ + {"name": "z", "type": "space", "unit": "micrometer"}, + {"name": "y", "type": "space", "unit": "micrometer"}, + {"name": "x", "type": "space", "unit": "micrometer"} ] } -] +], ``` +:::: -```` +#### Additional details + +Most coordinate transformations MUST specify their input and output coordinate systems +using `input` and `output` with a string value +that MUST correspond to the name of a coordinate system or the path to a multiscales group. +Exceptions are if the coordinate transformation is wrapped in another transformation, +e.g. as part of a `transformations` list of a `sequence` or +as `transformation` of an `inverseOf` transformation. +In these two cases input and output could, in some cases, be omitted (see below for details). +If unused, the `input` and `output` fields MAY be null. + +If used in a parent-level zarr-group, the `input` and `output` fields +can be the name of a `coordinateSystem` in the same parent-level group or the path to a multiscale image group. +If either `input` or `output` is a path to a multiscale image group, +the authoritative coordinate system for the respective image is the first `coordinateSystem` defined therein. +If the names of `input` or `output` correspond to both an existing path to a multiscale image group +and the name of a `coordinateSystem` defined in the same metadata document, +the `coordinateSystem` MUST take precedent. + +For usage in multiscales, see [the multiscales section](#multiscales-md) for details. Coordinate transformations are functions of *points* in the input space to *points* in the output space. We call this the "forward" direction. -Points are ordered lists of coordinates, where a coordinate is the location/value of that point along its corresponding axis. +Points are ordered lists of coordinates, +where a coordinate is the location/value of that point along its corresponding axis. The indexes of axis dimensions correspond to indexes into transformation parameter arrays. -For example, the scale transformation above defines the function: - -``` -x = 0.5 * i -y = 1.2 * j -``` - -i.e., the mapping from the first input axis to the first output axis is determined by the first scale parameter. When rendering transformed images and interpolating, -implementations may need the "inverse" transformation - from the output to the input coordinate system. -Inverse transformations will not be explicitly specified when they can be computed in closed form from the forward transformation. -Inverse transformations used for image rendering may be specified using the `inverseOf` transformation type, for example: +implementations may need the "inverse" transformation - +from the output to the input coordinate system. +Inverse transformations will not be explicitly specified +when they can be computed in closed form from the forward transformation. +Inverse transformations used for image rendering may be specified using +the `inverseOf` transformation type, for example: ```json { "type": "inverseOf", "transformation" : { "type": "displacements", - "path": "path/to/displacements", + "path": "/path/to/displacements", }, "input": "input_image", - "output": "output_image" + "output": "output_image", } ``` -Implementations SHOULD be able to compute and apply the inverse of some coordinate transformations when they are computable in closed-form -(as the [Transformation types](#trafo-types-md) section below indicates). -If an operation is requested that requires the inverse of a transformation that can not be inverted in closed-form, -implementations MAY estimate an inverse, or MAY output a warning that the requested operation is unsupported. +Implementations SHOULD be able to compute and apply +the inverse of some coordinate transformations when they are computable +in closed-form (as the [Transformation types](#trafo-types-md) section below indicates). +If an operation is requested that requires +the inverse of a transformation that can not be inverted in closed-form, +implementations MAY estimate an inverse, +or MAY output a warning that the requested operation is unsupported. #### Matrix transformations (matrix-trafo-md)= Two transformation types ([affine](#affine-md) and [rotation](#rotation-md)) are parametrized by matrices. Matrices are applied to column vectors that represent points in the input coordinate system. -The first (last) axis in a coordinate system is the top (bottom) entry in the column vector. +The first and last axes in a coordinate system correspond to the top and bottom entries in the column vector, respectively. Matrices are stored as two-dimensional arrays, either as json or in a zarr array. When stored as a 2D zarr array, the first dimension indexes rows and the second dimension indexes columns (e.g., an array of `"shape":[3,4]` has 3 rows and 4 columns). -When stored as a 2D json array, the inner array contains rows -(e.g. `[[1,2,3], [4,5,6]]` has 2 rows and 3 columns). +When stored as a 2D json array, the inner array contains rows (e.g. `[[1,2,3], [4,5,6]]` has 2 rows and 3 columns). -````{admonition} Example +::::{admonition} Example +:class: dropdown For matrix transformations, points in the coordinate system: @@ -733,25 +673,30 @@ because it is computed with the matrix-vector multiplication: [ 0 0 -1] [3] [-3] ``` -```` +:::: ### Transformation types (trafo-types-md)= -Input and output dimensionality may be determined by the value of the "input" and "output" fields, respectively. -If the value of "input" is an array, its shape gives the input dimension, -otherwise it is given by the length of "axes" for the coordinate system with the name of the "input". -If the value of "output" is an array, its shape gives the output dimension, -otherwise it is given by the length of "axes" for the coordinate system with the name of the "output". +Input and output dimensionality may be determined by the coordinate system referred to by the `input` and `output` fields, respectively. +If the value of `input` is a path to an array, its shape gives the input dimension, +otherwise it is given by the length of `axes` for the coordinate system with the name of the `input`. +If the value of `output` is an array, its shape gives the output dimension, +otherwise it is given by the length of `axes` for the coordinate system with the name of the `output`. #### identity (identity-md)= `identity` transformations map input coordinates to output coordinates without modification. -The position of the ith axis of the output coordinate system is set to the position of the ith axis of the input coordinate system. +The position of the i-th axis of the output coordinate system +is set to the position of the ith axis of the input coordinate system. `identity` transformations are invertible. -````{admonition} Example +The `input` and `output` fields MAY be omitted if wrapped in another transformation that provides `input`/`output` +(e.g., [`sequence`](#sequence-md), [`inverseOf`](#inverseof-md), ['byDimension](#bydimension-md) or [`bijection`](#bijection-md)). + +::::{admonition} Example +:class: dropdown ```{literalinclude} examples/transformations/identity.json :language: json @@ -764,19 +709,27 @@ x = i y = j ``` -```` +:::: #### mapAxis (mapAxis-md)= -`mapAxis` transformations describe axis permutations as a mapping of axis names. -Transformations MUST include a `mapAxis` field whose value is an object, all of whose values are strings. -If the object contains `"x":"i"`, then the transform sets the value of the output coordinate for axis "x" to the value of the coordinate of input axis "i" (think `x = i`). -For every axis in its output coordinate system, the `mapAxis` MUST have a corresponding field. -For every value of the object there MUST be an axis of the input coordinate system with that name. -Note that the order of the keys could be reversed. +`mapAxis` transformations describe axis permutations as a transpose vector of integers. +Transformations MUST include a `mapAxis` field +whose value is an array of integers that specifies the new ordering in terms of indices of the old order. +The length of the array MUST equal the number of dimensions in both the input and output coordinate systems. +Each integer in the array MUST be a valid zero-based index into the input coordinate system's axes +(i.e., between 0 and N-1 for an N-dimensional input). +Each index MUST appear exactly once in the array. +The value at position `i` in the array indicates which input axis becomes the `i`-th output axis. +`mapAxis` transforms are invertible. -````{admonition} Example +The `input` and `output` fields MAY be omitted if wrapped in another transformation that provides `input`/`output` +(e.g., [`sequence`](#sequence-md), [`inverseOf`](#inverseof-md), ['byDimension](#bydimension-md) or [`bijection`](#bijection-md)). + + +::::{admonition} Example 1 +:class: dropdown ```{literalinclude} examples/transformations/mapAxis1.json :language: json @@ -796,9 +749,10 @@ x = j y = i ``` -```` +:::: -````{admonition} Example +::::{admonition} Example 2 +:class: dropdown ```{literalinclude} examples/transformations/mapAxis2.json :language: json @@ -817,25 +771,30 @@ x = a y = b z = b ``` -```` +:::: #### translation (translation-md)= `translation` transformations are special cases of affine transformations. When possible, a translation transformation should be preferred to its equivalent affine. -Input and output dimensionality MUST be identical and MUST equal the the length of the "translation" array (N). +Input and output dimensionality MUST be identical +and MUST equal the the length of the "translation" array (N). `translation` transformations are invertible. -
-
-
- path -
- The path to a zarr-array containing the translation parameters. - The array at this path MUST be 1D, and its length MUST be `N`. -
- scale -
- The scale parameters stored as a JSON list of numbers. The list MUST have length `N`. -
-
-
- path -
- The path to a zarr-array containing the scale parameters. - The array at this path MUST be 1D, and its length MUST be `N`. -
- scale -
- The scale parameters stored as a JSON list of numbers. The list MUST have length `N`. -
-
-
- path -
- The path to a zarr-array containing the affine parameters. - The array at this path MUST be 2D whose shape MUST be `M x (N+1)`. -
- affine -
- The affine parameters stored in JSON. The matrix MUST be stored as 2D nested array where the outer array MUST be length - `M` and the inner arrays MUST be length `N+1`.
-
-
- path -
- The path to an array containing the affine parameters. - The array at this path MUST be 2D whose shape MUST be `N x N`. -
- rotation -
- The parameters stored in JSON. The matrix MUST be stored as a 2D nested array where the outer array MUST be length `N` - and the inner arrays MUST be length `N`.
-
-
- transformations -
- A non-empty array of transformations. -
- path
- The location of the coordinate array in this (or another) container.
- interpolation -
- The `interpolation` attributes MAY be provided. It's value indicates
- the interpolation to use if transforming points not on the array's discrete grid.
+
- The
interpolationattributes MAY be provided. + Its value indicates the interpolation to use + if transforming points not on the array's discrete grid. Values could be:linear(default)
@@ -1158,11 +1122,17 @@ Metadata for these coordinate transforms have the following field:
- The
- transformations -
- A list of transformations, each of which applies to a (non-strict) subset of input and output dimensions (axes).
- The values of `input` and `output` fields MUST be an array of strings.
- Every axis name in `input` MUST correspond to a name of some axis in this parent object's `input` coordinate system.
- Every axis name in the parent byDimension's `output` MUST appear in exactly one of its child transformations' `output`.
+
- Each child transformation MUST contain
input_axesandoutput_axesfields + whose values are arrays of strings. + Every axis name in a child transformation'sinput_axes+ MUST correspond to a name of some axis in this parent object'sinputcoordinate system. + Every axis name in the parent byDimension'soutputcoordinate system + MUST appear in exactly one child transformation'soutput_axesarray. + Each child transformation'sinput_axesandoutput_axesarrays + MUST have the same length as that transformation's parameter arrays. - Each child transformation MUST contain