| `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
- | |
store.zarr # Root folder of the zarr store
│
├── zarr.json # coordinate transformations describing the relationship between two image coordinate systems
@@ -476,18 +457,82 @@ store.zarr # Root folder of the zarr store
│ └── zarr.json
│
├── volume
-│ ├── zarr.json # group level attributes (multiscales)
+│ ├── 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 # physical coordinate system and transformations here
└── crop
- ├── .zattrs # group level attributes (multiscales)
+ ├── 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 # physical coordinate system and transformations here
+
+
+````{admonition} Example
+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.
+
+The set of coordinate transformations 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.
+
+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.
+
+```json
+"coordinateTransformations": [
+ {
+ "type": "affine",
+ "path": "coordinateTransformations/sampleA_instrument2-to-instrument1",
+ "input": "sampleA_instrument2",
+ "output": "sampleA_instrument1"
+ }
+]
+```
+
+And the image under `root/sampleA_instrument1` would have the following as the first coordinate system:
+
+```json
+"coordinateSystems": [
+ {
+ "name": "sampleA-instrument1",
+ "axes": [
+ {"name": "z", "type": "space", "unit": "micrometer"},
+ {"name": "y", "type": "space", "unit": "micrometer"},
+ {"name": "x", "type": "space", "unit": "micrometer"}
+ ]
+ },
+]
+```
+
+The image under `root/sampleA_instrument2` would have this as the first listed coordinate system:
+
+```json
+[
+ {
+ "name": "sampleA-instrument2",
+ "axes": [
+ {"name": "z", "type": "space", "unit": "micrometer"},
+ {"name": "y", "type": "space", "unit": "micrometer"},
+ {"name": "x", "type": "space", "unit": "micrometer"}
+ ]
+ }
+],
```
+````
### Additional details
From 5c2c39f83722157edc4cdd0049af6374f37485df Mon Sep 17 00:00:00 2001
From: Johannes Soltwedel <38459088+jo-mueller@users.noreply.github.com>
Date: Tue, 21 Oct 2025 09:48:39 +0200
Subject: [PATCH 15/47] updated matrix transformations
---
ngff_spec/specification.md | 112 ++++++++++++-------------------------
1 file changed, 37 insertions(+), 75 deletions(-)
diff --git a/ngff_spec/specification.md b/ngff_spec/specification.md
index a36a3848..3ab00f1e 100644
--- a/ngff_spec/specification.md
+++ b/ngff_spec/specification.md
@@ -537,71 +537,29 @@ The image under `root/sampleA_instrument2` would have this as the first listed c
### 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.
-
-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).
-
-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
+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 appears in the `transformations` list of a `sequence`
+or is the `transformation` of an `inverseOf` transformation.
+In these two cases input and output could, in some cases, be omitted (see below for details).
+
+If used in a parent-level zarr-group, the `input` field MUST be a path to the input image.
+The authoritative coordinate system for the input image is the first `coordinateSystem` defined therein.
+The `output` field can be a `path` to an output image or the name of a `coordinateSystem` defined in the parent-level zarr group.
+If the names of `input` or `output` can be both a `path` or the name of a `coordinateSystem`, `path` MUST take precedent.
+If unused, the `input` and `output` fields MAY be null.
+
+For usage in multiscales, see [multiscales section](#multiscales-metadata) for details.
+
+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).
-````{admonition} Example
-
-The sequence transformation's input corresponds to an array coordinate system at path "my/array".
-
-```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 ]
- },
- {
- "type" : "sequence",
- "input" : "my/array",
- "output" : "outSeq",
- "transformations" : [
- { "type": "scale", "scale" : [ 0.5, 0.6 ] },
- { "type": "translation", "translation" : [ 2, 5 ] }
- ]
- },
- {
- "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"]}
- ]
- }
-]
-```
-
-````
-
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:
@@ -613,38 +571,42 @@ 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](#transformation-types) 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.
+Two transformation types ([affine](#affine) and [rotation](#rotation)) 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
From 46e7e1c2acfd512d88f040e5452aeca7e419ffb2 Mon Sep 17 00:00:00 2001
From: Johannes Soltwedel <38459088+jo-mueller@users.noreply.github.com>
Date: Tue, 21 Oct 2025 09:49:05 +0200
Subject: [PATCH 16/47] update transformation types
---
ngff_spec/specification.md | 10 +++++-----
1 file changed, 5 insertions(+), 5 deletions(-)
diff --git a/ngff_spec/specification.md b/ngff_spec/specification.md
index 3ab00f1e..083db7d5 100644
--- a/ngff_spec/specification.md
+++ b/ngff_spec/specification.md
@@ -645,11 +645,11 @@ because it is computed with the matrix-vector multiplication:
### 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 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`.
#### identity
(identity-md)=
From d74cd540d5973e191e745bb16a9e4c41e16fd3da Mon Sep 17 00:00:00 2001
From: Johannes Soltwedel <38459088+jo-mueller@users.noreply.github.com>
Date: Tue, 21 Oct 2025 10:04:34 +0200
Subject: [PATCH 17/47] update transformation types metadata
---
ngff_spec/specification.md | 417 ++++++++++++++++++++++---------------
1 file changed, 245 insertions(+), 172 deletions(-)
diff --git a/ngff_spec/specification.md b/ngff_spec/specification.md
index 083db7d5..08a32fe2 100644
--- a/ngff_spec/specification.md
+++ b/ngff_spec/specification.md
@@ -655,9 +655,12 @@ otherwise it is given by the length of `axes` for the coordinate system with the
(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.
+The `input` and `output` fields MAY be omitted if part of a [`sequence`](#sequence) transformation.
+
````{admonition} Example
```{literalinclude} examples/transformations/identity.json
@@ -676,12 +679,16 @@ 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.
+
+The `input` and `output` fields MAY be omitted if part of a [`sequence`](#sequence) transformation.
````{admonition} Example
@@ -731,16 +738,19 @@ z = b
`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.
-interpolation attributes MAY be provided.
+ It's value indicates the interpolation to use
+ if transforming points not on the array's discrete grid.
Values could be:
linear (default)input_axes and output_axes fields
+ whose values are arrays of strings.
+ Every axis name in a child transformation's input_axes
+ 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 coordinate system
+ MUST appear in exactly one child transformation's output_axes array.
+ Each child transformation's input_axes and output_axes arrays
+ MUST have the same length as that transformation's parameter arrays.
interpolation attributes MAY be provided.
- It's value indicates the interpolation to use
- if transforming points not on the array's discrete grid.
- Values could be:
- linear (default)nearestcubic
](https://orcid.org/0000-0003-4028-811X)
## Abstract
From dee0b98c8355c62185872ac18dc393439d524fe0 Mon Sep 17 00:00:00 2001
From: Johannes Soltwedel <38459088+jo-mueller@users.noreply.github.com>
Date: Wed, 22 Oct 2025 12:48:11 +0200
Subject: [PATCH 25/47] fix reference
---
ngff_spec/specification.md | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/ngff_spec/specification.md b/ngff_spec/specification.md
index 4f865bd6..0eef3db9 100644
--- a/ngff_spec/specification.md
+++ b/ngff_spec/specification.md
@@ -387,7 +387,7 @@ Conforming readers:
## "coordinateTransformations" metadata
(coord-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.
From a75d5126e8f8a95da114647daf5982cbcfed074e Mon Sep 17 00:00:00 2001
From: Johannes Soltwedel <38459088+jo-mueller@users.noreply.github.com>
Date: Wed, 22 Oct 2025 12:48:31 +0200
Subject: [PATCH 26/47] change precedence
See discussion [here](https://github.com/bogovicj/ngff-rfc5-coordinate-transformation-examples/issues/11#issuecomment-3431688131)
---
ngff_spec/specification.md | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/ngff_spec/specification.md b/ngff_spec/specification.md
index 0eef3db9..db45ac3f 100644
--- a/ngff_spec/specification.md
+++ b/ngff_spec/specification.md
@@ -542,7 +542,7 @@ In these two cases input and output could, in some cases, be omitted (see below
If used in a parent-level zarr-group, the `input` field MUST be a path to the input image.
The authoritative coordinate system for the input image is the first `coordinateSystem` defined therein.
The `output` field can be a `path` to an output image or the name of a `coordinateSystem` defined in the parent-level zarr group.
-If the names of `input` or `output` can be both a `path` or the name of a `coordinateSystem`, `path` MUST take precedent.
+If the names of `input` or `output` can be both a `path` or the name of a `coordinateSystem`, `coordinateSystem` MUST take precedent.
If unused, the `input` and `output` fields MAY be null.
For usage in multiscales, see [multiscales section](#multiscales-md) for details.
From e52f1fb432cd052ba538c80a37b1f2e97766cbf2 Mon Sep 17 00:00:00 2001
From: Johannes Soltwedel <38459088+jo-mueller@users.noreply.github.com>
Date: Wed, 22 Oct 2025 15:08:29 +0200
Subject: [PATCH 27/47] added examples for transformations with discrete axes
---
.../affine2d2d_with_channel.json | 32 +++++++++++++++++++
.../transformations/scale_with_discrete.json | 28 ++++++++++++++++
ngff_spec/specification.md | 23 ++++++++++++-
3 files changed, 82 insertions(+), 1 deletion(-)
create mode 100644 ngff_spec/examples/transformations/affine2d2d_with_channel.json
create mode 100644 ngff_spec/examples/transformations/scale_with_discrete.json
diff --git a/ngff_spec/examples/transformations/affine2d2d_with_channel.json b/ngff_spec/examples/transformations/affine2d2d_with_channel.json
new file mode 100644
index 00000000..7b3cf84c
--- /dev/null
+++ b/ngff_spec/examples/transformations/affine2d2d_with_channel.json
@@ -0,0 +1,32 @@
+{
+ "coordinateSystems" : [
+ {
+ "name": "cji",
+ "axes": [
+ {"name": "k", "discrete": true},
+ {"name": "j", "discrete": false},
+ {"name": "i", "discrete": false}
+ ]
+ },
+ {
+ "name": "cyx",
+ "axes": [
+ {"name": "c", "discrete": true},
+ {"name": "y", "discrete": false},
+ {"name": "x", "discrete": false}
+ ]
+ }
+ ],
+ "coordinateTransformations" : [
+ {
+ "type": "affine",
+ "affine": [
+ [1, 0, 0, 0],
+ [0, 1, 2, 3],
+ [0, 4, 5, 6]
+ ],
+ "input": "cji",
+ "output": "cyx"
+ }
+ ]
+}
diff --git a/ngff_spec/examples/transformations/scale_with_discrete.json b/ngff_spec/examples/transformations/scale_with_discrete.json
new file mode 100644
index 00000000..b2acb70c
--- /dev/null
+++ b/ngff_spec/examples/transformations/scale_with_discrete.json
@@ -0,0 +1,28 @@
+{
+ "coordinateSystems": [
+ {
+ "name": "in",
+ "axes": [
+ {"name": "k", "discrete": true},
+ {"name": "j", "discrete": false},
+ {"name": "i", "discrete": false}
+ ]
+ },
+ {
+ "name": "out",
+ "axes": [
+ {"name": "c", "discrete": true},
+ {"name": "y", "discrete": false},
+ {"name": "x", "discrete": false}
+ ]
+ }
+ ],
+ "coordinateTransformations": [
+ {
+ "type": "scale",
+ "scale": [1, 3.12, 2],
+ "input": "in",
+ "output": "out"
+ }
+ ]
+}
diff --git a/ngff_spec/specification.md b/ngff_spec/specification.md
index db45ac3f..d8c45c0c 100644
--- a/ngff_spec/specification.md
+++ b/ngff_spec/specification.md
@@ -783,7 +783,7 @@ The array at this path MUST be 1D, and its length MUST be `N`.
: The scale parameters are stored as a JSON list of numbers.
The list MUST have length `N`.
-::::{admonition} Example
+::::{admonition} Example 1
:class: dropdown
```{literalinclude} examples/transformations/scale.json
@@ -798,6 +798,17 @@ y = 2 * j
```
::::
+::::{admonition} Example 2
+:class: dropdown
+
+If the data contains discrete axes (e.g., channels),
+these axes are typically not transformed, but must be represented in the scale parameters.
+
+```{literalinclude} examples/transformations/scale_with_discrete.json
+:language: json
+```
+::::
+
#### affine
(affine-md)=
@@ -878,6 +889,16 @@ it is equivalent to this matrix-vector multiplication in homogeneous coordinates
where the last row `[0 0 1]` is omitted in the JSON representation.
::::
+::::{admonition} Example 3
+:class: dropdown
+
+If the image data contains discrete axes (e.g., channels),
+these axes are typically not transformed, but must be represented in the transformation matrix.
+
+```{literalinclude} examples/transformations/affine2d2d_with_channel.json
+:language: json
+```
+
#### rotation
(rotation-md)=
From 2faa956afe56b0c3375cb61cc69812a70c2c0c70 Mon Sep 17 00:00:00 2001
From: Johannes Soltwedel <38459088+jo-mueller@users.noreply.github.com>
Date: Wed, 22 Oct 2025 15:39:48 +0200
Subject: [PATCH 28/47] fix link to example
---
ngff_spec/examples.md | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/ngff_spec/examples.md b/ngff_spec/examples.md
index 4f25ecbd..bb5e98f9 100644
--- a/ngff_spec/examples.md
+++ b/ngff_spec/examples.md
@@ -9,8 +9,8 @@ This section contains JSON examples for various metadata layouts.
- [image](#examples:bf2raw:image)
- [plate](#examples:bf2raw:plate)
-## coordSystems
-- [arrayCoordSys](#examples:coordSystems:arrayCoordSys)
+## coordinate_systems
+- [arrayCoordSys](#examples:coordinate_systems:arrayCoordSys)
## label_strict
- [colors_properties](#examples:label_strict:colors_properties)
From 8fb8ac1c3e875eaaa6f6db4b7e982a00ba891496 Mon Sep 17 00:00:00 2001
From: Johannes Soltwedel <38459088+jo-mueller@users.noreply.github.com>
Date: Wed, 22 Oct 2025 15:41:17 +0200
Subject: [PATCH 29/47] untrack autogenerated files
---
.gitignore | 3 +++
1 file changed, 3 insertions(+)
diff --git a/.gitignore b/.gitignore
index f97a7680..adb61ce8 100644
--- a/.gitignore
+++ b/.gitignore
@@ -9,6 +9,9 @@ _bikeshed
# do not sync auto-generated md files
ngff_spec/_generated
+ngff_spec/footer.md
+ngff_spec/examples.md
+ngff_spec/schemas.md
# Byte-compiled / optimized / DLL files
__pycache__/
From 7ad14ba9205d428742edab6463df242cca751dd4 Mon Sep 17 00:00:00 2001
From: Johannes Soltwedel <38459088+jo-mueller@users.noreply.github.com>
Date: Wed, 22 Oct 2025 18:23:24 +0200
Subject: [PATCH 30/47] update affine examples and fix variable ordering
---
.../examples/transformations/affine2d3d.json | 6 ++---
ngff_spec/specification.md | 22 ++++++++++---------
2 files changed, 15 insertions(+), 13 deletions(-)
diff --git a/ngff_spec/examples/transformations/affine2d3d.json b/ngff_spec/examples/transformations/affine2d3d.json
index 50b4b82c..8010ee42 100644
--- a/ngff_spec/examples/transformations/affine2d3d.json
+++ b/ngff_spec/examples/transformations/affine2d3d.json
@@ -1,14 +1,14 @@
{
"coordinateSystems": [
{ "name": "ij", "axes": [{"name": "i"}, {"name": "j"}] },
- { "name": "xyz", "axes": [{"name": "x"}, {"name": "y"}, {"name": "z"}] }
+ { "name": "zyx", "axes": [{"name": "z"}, {"name": "y"}, {"name": "x"}] }
],
"coordinateTransformations": [
{
"type": "affine",
- "affine": [[1, 2, 3], [4, 5, 6], [7, 8, 9]],
+ "affine": [[1, 0, 0], [2, 3, 4], [5, 6, 7]],
"input": "ij",
- "output": "xyz"
+ "output": "zyx"
}
]
}
diff --git a/ngff_spec/specification.md b/ngff_spec/specification.md
index d8c45c0c..1e1a38e4 100644
--- a/ngff_spec/specification.md
+++ b/ngff_spec/specification.md
@@ -841,15 +841,15 @@ A 2D-2D example:
defines the function:
```
-x = 1*i + 2*j + 3
-y = 4*i + 5*j + 6
+y = 1*j + 2*i + 3
+x = 4*j + 5*i + 6
```
it is equivalent to this matrix-vector multiplication in homogeneous coordinates:
```
-[ 1 2 3 ][ i ] [ x ]
-[ 4 5 6 ][ j ] = [ y ]
+[ 1 2 3 ][ j ] [ y ]
+[ 4 5 6 ][ i ] = [ x ]
[ 0 0 1 ][ 1 ] [ 1 ]
```
@@ -860,6 +860,7 @@ where the last row `[0 0 1]` is omitted in the JSON representation.
::::{admonition} Example 2
:class: dropdown
An example with two dimensional inputs and three dimensional outputs.
+The affine transformation adds a translation by 1 along the new z-axis.
Note that the order of the axes can in general be determined by the application or user.
These axes relate to the memory or on-disk order insofar as the last dimension is contiguous
@@ -872,17 +873,18 @@ when the zarr array is c-order (the default for zarr version 2, and the only opt
defines the function:
```
-x = 1*i + 2*j + 3
-y = 4*i + 5*j + 6
-z = 7*i + 8*j + 9
+z = 0*i + 0*j + 1
+y = 3*i + 4*j + 2
+x = 6*i + 7*j + 5
+
```
it is equivalent to this matrix-vector multiplication in homogeneous coordinates:
```
-[ 1 2 3 ][ i ] [ x ]
-[ 4 5 6 ][ j ] = [ y ]
-[ 7 8 9 ][ 1 ] [ z ]
+[ 1 0 0 ][ 1 ] [ z ]
+[ 2 3 4 ][ i ] = [ y ]
+[ 5 6 7 ][ j ] [ x ]
[ 0 0 1 ] [ 1 ]
```
From ad495b6d767eadf91f34c8f0b6fe52ec2b33743d Mon Sep 17 00:00:00 2001
From: Johannes Soltwedel <38459088+jo-mueller@users.noreply.github.com>
Date: Wed, 22 Oct 2025 22:08:48 +0200
Subject: [PATCH 31/47] Fixed scale examples
---
ngff_spec/examples/transformations/scale.json | 2 +-
ngff_spec/specification.md | 16 ++++++++++++----
2 files changed, 13 insertions(+), 5 deletions(-)
diff --git a/ngff_spec/examples/transformations/scale.json b/ngff_spec/examples/transformations/scale.json
index 882b9dd7..84664a80 100644
--- a/ngff_spec/examples/transformations/scale.json
+++ b/ngff_spec/examples/transformations/scale.json
@@ -6,7 +6,7 @@
"coordinateTransformations": [
{
"type": "scale",
- "scale": [3.12, 2],
+ "scale": [2, 3.12],
"input": "in",
"output": "out"
}
diff --git a/ngff_spec/specification.md b/ngff_spec/specification.md
index 1e1a38e4..e7388bee 100644
--- a/ngff_spec/specification.md
+++ b/ngff_spec/specification.md
@@ -552,14 +552,22 @@ 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.
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
+::::{admonition} Example
+:class: dropdown
+For example, the [scale transformation](#scale-md) metadata below
+
+```{literalinclude} examples/transformations/scale.json
+:language: json
```
+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.
+::::
When rendering transformed images and interpolating,
implementations may need the "inverse" transformation -
From 51c88095517ae84ee31f4f99f8cb3467d1fe58a1 Mon Sep 17 00:00:00 2001
From: Johannes Soltwedel <38459088+jo-mueller@users.noreply.github.com>
Date: Wed, 22 Oct 2025 22:11:24 +0200
Subject: [PATCH 32/47] removed example from additional details
---
ngff_spec/specification.md | 19 +++----------------
1 file changed, 3 insertions(+), 16 deletions(-)
diff --git a/ngff_spec/specification.md b/ngff_spec/specification.md
index e7388bee..ef16a032 100644
--- a/ngff_spec/specification.md
+++ b/ngff_spec/specification.md
@@ -552,22 +552,7 @@ 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.
The indexes of axis dimensions correspond to indexes into transformation parameter arrays.
-
-::::{admonition} Example
-:class: dropdown
-For example, the [scale transformation](#scale-md) metadata below
-
-```{literalinclude} examples/transformations/scale.json
-:language: json
-```
-
-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.
-::::
+Examples are given below in the respective [transformation type](#trafo-types-md) sections.
When rendering transformed images and interpolating,
implementations may need the "inverse" transformation -
@@ -804,6 +789,8 @@ 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.
+
::::
::::{admonition} Example 2
From 5d99680660817218dde8cf7b37df56f7e241c006 Mon Sep 17 00:00:00 2001
From: Johannes Soltwedel <38459088+jo-mueller@users.noreply.github.com>
Date: Wed, 22 Oct 2025 22:16:54 +0200
Subject: [PATCH 33/47] specify affines/rotations as 2D matrices in parameter
table
---
ngff_spec/specification.md | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/ngff_spec/specification.md b/ngff_spec/specification.md
index ef16a032..aff19c87 100644
--- a/ngff_spec/specification.md
+++ b/ngff_spec/specification.md
@@ -410,8 +410,8 @@ The following transformations are supported:
| `mapAxis` | `"mapAxis":List[number]` | A `mapAxis` transformation specifies an axis permutation as a transpose array of integer indices that refer to the ordering of the axes in the respective coordinate system. |
| `translation` | one of:
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
+│ └── 0 # a group containing the 0th scale
+│ └── image # a zarr array
│ └── zarr.json # physical coordinate system and transformations here
└── crop
├── zarr.json # group level attributes (multiscales)
- └── 0 # a group containing the 0th scale
- └── image # a zarr array
+ └── 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.
-Two samples are collected ("sampleA" and "sampleB").
-An analysis of sample A requires measurements from both instruments' images at certain points in space.
+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 coordinates (x,y,z)
-may not correspond to the measurement at the same point in instrument 2
+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 in the same coordinate system.
+To analyze both images together, they must be transformed to a common coordinate system.
The set of coordinate transformations encodes relationships between coordinate systems,
-specifically, how to convert points and images to different 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, the ROI should be transformed to the "sampleA_image1" 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.
The `coordinateTransformations` in the parent-level metadata would contain the following data.
@@ -499,7 +543,7 @@ under `coordinateTransformations/sampleA_instrument2-to-instrument1` as shown ab
]
```
-And the image under `root/sampleA_instrument1` would have the following as the first coordinate system:
+And the image at the path `sampleA_instrument1` would have the following as the first coordinate system:
```json
"coordinateSystems": [
@@ -514,7 +558,7 @@ And the image under `root/sampleA_instrument1` would have the following as the f
]
```
-The image under `root/sampleA_instrument2` would have this as the first listed coordinate system:
+The image at path `sampleA_instrument2` would have this as the first listed coordinate system:
```json
[
@@ -530,29 +574,32 @@ The image under `root/sampleA_instrument2` would have this as the first listed c
```
::::
-### Additional details
+#### 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 appears in the `transformations` list of a `sequence`
-or is the `transformation` of an `inverseOf` transformation.
+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 used in a parent-level zarr-group, the `input` field MUST be a path to the input image.
-The authoritative coordinate system for the input image is the first `coordinateSystem` defined therein.
-The `output` field can be a `path` to an output image or the name of a `coordinateSystem` defined in the parent-level zarr group.
-If the names of `input` or `output` can be both a `path` or the name of a `coordinateSystem`, `coordinateSystem` MUST take precedent.
If unused, the `input` and `output` fields MAY be null.
-For usage in multiscales, see [multiscales section](#multiscales-md) for details.
+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.
The indexes of axis dimensions correspond to indexes into transformation parameter arrays.
-Examples are given below in the respective [transformation type](#trafo-types-md) sections.
When rendering transformed images and interpolating,
implementations may need the "inverse" transformation -
@@ -585,7 +632,7 @@ 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.
+Two transformation types ([affine](#affine) and [rotation](#rotation)) are parametrized by matrices.
Matrices are applied to column vectors that represent points in the input coordinate system.
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.
@@ -631,8 +678,8 @@ because it is computed with the matrix-vector multiplication:
### 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,
+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`.
@@ -645,7 +692,8 @@ 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.
-The `input` and `output` fields MAY be omitted if part of a [`sequence`](#sequence-md) transformation.
+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
@@ -674,8 +722,11 @@ Each integer in the array MUST be a valid zero-based index into the input coordi
(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.
+
+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)).
-The `input` and `output` fields MAY be omitted if part of a [`sequence`](#sequence-md) transformation.
::::{admonition} Example 1
:class: dropdown
@@ -731,7 +782,8 @@ Input and output dimensionality MUST be identical
and MUST equal the the length of the "translation" array (N).
`translation` transformations are invertible.
-The `input` and `output` fields MAY be omitted if part of a [`sequence`](#sequence-md) transformation.
+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)).
path
: The path to a zarr-array containing the translation parameters.
@@ -766,7 +818,8 @@ and MUST equal the the length of the "scale" array (N).
Values in the `scale` array SHOULD be non-zero;
in that case, `scale` transformations are invertible.
-The `input` and `output` fields MAY be omitted if part of a [`sequence`](#sequence-md) transformation.
+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)).
path
: The path to a zarr-array containing the scale parameters.
@@ -814,7 +867,8 @@ This transformation type may be (but is not necessarily) invertible
when `N` equals `M`.
The matrix MUST be stored as a 2D array either as json or as a zarr array.
-The `input` and `output` fields MAY be omitted if part of a [`sequence`](#sequence-md) transformation.
+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)).
path
: The path to a zarr-array containing the affine parameters.
@@ -822,7 +876,7 @@ 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
+The matrix MUST be stored as 2D nested array (an array of arrays of numbers)
where the outer array MUST be length `M` and the inner arrays MUST be length `N+1`.
::::{admonition} Example 1
@@ -900,14 +954,15 @@ these axes are typically not transformed, but must be represented in the transfo
(rotation-md)=
`rotation`s are [matrix transformations](#matrix-trafo-md) that are special cases of affine transformations.
-When possible, a rotation transformation SHOULD be preferred to its equivalent affine.
+When possible, a rotation transformation SHOULD be used instead of an equivalent affine.
Input and output dimensionality (N) MUST be identical.
Rotations are stored as `NxN` matrices, see below,
and MUST have determinant equal to one, with orthonormal rows and columns.
The matrix MUST be stored as a 2D array either as json or in a zarr array.
`rotation` transformations are invertible.
-The `input` and `output` fields MAY be omitted if part of a [`sequence`](#sequence-md) transformation.
+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)).
path
: The path to an array containing the affine parameters.
@@ -915,7 +970,7 @@ 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`
+The matrix MUST be stored as a 2D nested array (an array of arrays of numbers) where the outer array MUST be length `N`
and the inner arrays MUST be length `N`.
::::{admonition} Example
@@ -937,23 +992,24 @@ y = 1*i + 0*j
#### inverseOf
(inverseOf-md)=
-An `inverseOf` transformation contains another transformation, which is often non-linear.
-It indicates that transforming points from output to input coordinate systems
+An `inverseOf` transformation contains another transformation (often non-linear),
+and indicates that transforming points from output to input coordinate systems
is possible using the contained transformation.
+Transforming points from the input to the output coordinate systems
+requires the inverse of the contained transformation (if it exists).
The `input` and `output` fields MAY be omitted for `inverseOf` transformations
if those fields may be omitted for the transformation it wraps.
```{note}
Software libraries that perform image registration
-often return the transformation from fixed (output) image coordinates to moving (input) image coordinates,
-because this "inverse" transformation is most often required when rendering the transformed moving image.
+often return the transformation from fixed image coordinates to moving image coordinates,
+because this "inverse" transformation is most often required
+when rendering the transformed moving image.
Results such as this may be enclosed in an `inverseOf` transformation.
This enables the "outer" coordinate transformation to specify the moving image coordinates
as `input` and fixed image coordinates as `output`,
a choice that many users and developers find intuitive.
-At the same time, registration libraries can interpret the wrapped, inverted transformation
-as the correct corresponding transformation from fixed (output) to moving (input) coordinates.
```
::::{admonition} Example
@@ -979,6 +1035,9 @@ The output of the last transformation is the result of the sequence.
A sequence transformation MUST NOT be part of another sequence transformation.
The `input` and `output` fields MUST be included for sequence transformations.
+transformations
+: A non-empty array of transformations.
+
````{note}
Considering transformations as functions of points,
@@ -993,9 +1052,6 @@ f2(f1(f0(x)))
````
-transformations
-: A non-empty array of transformations.
-
::::{admonition} Example
:class: dropdown
@@ -1031,7 +1087,8 @@ These transformation types refer to an array at location specified by the `"path
The input and output coordinate systems for these transformations ("input / output coordinate systems")
constrain the array size and the coordinate system metadata for the array ("field coordinate system").
-The `input` and `output` fields MAY be omitted if part of a [`sequence`](#sequence-md) transformation.
+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)).
* If the input coordinate system has `N` axes,
the array at location path MUST have `N+1` dimensions
@@ -1043,37 +1100,40 @@ The `input` and `output` fields MAY be omitted if part of a [`sequence`](#sequen
* If the output coordinate system has `M` axes,
the length of the array along the `coordinate`/`displacement` dimension MUST be of length `M`.
-The i-th value of the array along the `coordinate` or `displacement` axis refers
-to the coordinate or displacement of the i-th output axis.
-See the example below.
+The `i`th value of the array along the `coordinate` or `displacement` axis refers to the coordinate or displacement
+of the `i`th output axis. See the example below.
`coordinates` and `displacements` transformations are not invertible in general,
but implementations MAY approximate their inverses.
Metadata for these coordinate transforms have the following fields:
-path
-: The location of the coordinate array in this (or another) container.
+interpolation attributes 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)nearestcubic