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 │ -├── .zattrs # coordinate transformations describing the relationship between two image coordinate systems +├── 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 -│ ├── .zattrs -│ └── .zarray +│ └── zarr.json │ ├── volume -│ ├── .zattrs # group level attributes (multiscales) -│ └── 0 # a group containing the 0th scale -│ └── image # a zarr array -│ ├── .zattrs # physical coordinate system and transformations here -│ └── .zarray # 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 - ├── .zattrs # physical coordinate system and transformations here - └── .zarray # 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-### 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 could, in some cases, 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 (see below for -details). +````{admonition} Example +(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. + +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. + +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" + } +] +``` -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. For example, the scale transformation above -defines the function: +And the image at the path `sampleA_instrument1` would have the following as the first coordinate system: -``` -x = 0.5 * i -y = 1.2 * j +```json +"coordinateSystems": [ + { + "name": "sampleA-instrument1", + "axes": [ + {"name": "z", "type": "space", "unit": "micrometer"}, + {"name": "y", "type": "space", "unit": "micrometer"}, + {"name": "x", "type": "space", "unit": "micrometer"} + ] + }, +] ``` -i.e., the mapping from the first input axis to the first output axis is determined by the first scale parameter. +The image at path `sampleA_instrument2` would have this as the first listed coordinate system: -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: +```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 + +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-metadata) 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. + +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: ```json { @@ -325,179 +447,229 @@ transformation type, for example: "transformation" : { "type": "displacements", "path": "/path/to/displacements", - } + }, + "input": "input_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](#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. +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 -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. 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). +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. +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). +#### Transformation types -### Transformation types +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`. -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, it's length gives the input dimension, otherwise the length of "axes" for the coordinate -system with the name of the "input" value gives the input dimension. If the value of "input" is an array, it's -length 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 length 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 +`identity` transformations map input coordinates to output coordinates without modification. +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. -`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. `identity` transformations are invertible. +The `input` and `output` fields MAY be omitted if wrapped in another transformation that provides `input`/`output` +(e.g., [`sequence`](#sequence), [`inverseOf`](#inverseof), ['byDimension](#bydimension) or [`bijection`](#bijection)). -#### mapAxis +##### mapAxis -`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. +The `input` and `output` fields MAY be omitted if wrapped in another transformation that provides `input`/`output` +(e.g., [`sequence`](#sequence), [`inverseOf`](#inverseof), ['byDimension](#bydimension) or [`bijection`](#bijection)). -#### translation +##### translation -`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). `translation` transformations are -invertible. +`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). +`translation` transformations are invertible. + +The `input` and `output` fields MAY be omitted if wrapped in another transformation that provides `input`/`output` +(e.g., [`sequence`](#sequence), [`inverseOf`](#inverseof), ['byDimension](#bydimension) or [`bijection`](#bijection)). 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`. +: The path to a zarr-array containing the translation parameters. +The array at this path MUST be 1D, and its length MUST be `N`. translation -: The translation parameters stored as a JSON list of numbers. The list MUST have length `N`. +: The translation parameters stored as a JSON list of numbers. +The list MUST have length `N`. +##### scale -#### scale +`scale` transformations are special cases of affine transformations. +When possible, a scale transformation SHOULD be preferred to its equivalent affine. +Input and output dimensionality MUST be identical +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. -`scale` transformations are special cases of affine transformations. When possible, a scale transformation -SHOULD be preferred to its equivalent affine. Input and output dimensionality MUST be identical 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 wrapped in another transformation that provides `input`/`output` +(e.g., [`sequence`](#sequence), [`inverseOf`](#inverseof), ['byDimension](#bydimension) or [`bijection`](#bijection)). 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`. +: 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`. +: The scale parameters are stored as a JSON list of numbers. +The list MUST have length `N`. +##### affine -#### affine +`affine`s are [matrix transformations](#matrix-transformations) from N-dimensional inputs to M-dimensional outputs. +They are represented as the upper `(M)x(N+1)` sub-matrix of a `(M+1)x(N+1)` matrix in [homogeneous +coordinates](https://en.wikipedia.org/wiki/Homogeneous_coordinates) (see examples). +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. -`affine`s are [matrix transformations](#matrix-transformations) from N-dimensional inputs to M-dimensional outputs are -represented as the upper `(M)x(N+1)` sub-matrix of a `(M+1)x(N+1)` matrix in [homogeneous -coordinates](https://en.wikipedia.org/wiki/Homogeneous_coordinates) (see examples). 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 wrapped in another transformation that provides `input`/`output` +(e.g., [`sequence`](#sequence), [`inverseOf`](#inverseof), ['byDimension](#bydimension) or [`bijection`](#bijection)). 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)`. +: 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`. +: The affine parameters stored in JSON. +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`. +##### rotation -#### rotation +`rotation`s are [matrix transformations](#matrix-transformations) that are special cases of affine transformations. +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. -`rotation`s are [matrix transformations](#matrix-transformations) that are special cases of affine transformations. When possible, a rotation -transformation SHOULD be preferred to its 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 wrapped in another transformation that provides `input`/`output` +(e.g., [`sequence`](#sequence), [`inverseOf`](#inverseof), ['byDimension](#bydimension) or [`bijection`](#bijection)). 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`. +: 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`. +: The parameters stored in JSON. +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`. + +##### inverseOf -#### inverseOf +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). -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 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. +Software libraries that perform image registration +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. ``` +##### sequence -#### sequence - -A `sequence` transformation consists of an ordered array of coordinate transformations, and is invertible if every coordinate -transform in the array is invertible (though could be invertible in other cases as well). To apply a sequence transformation -to a point in the input coordinate system, apply the first transformation in the list of transformations. Next, apply the second -transformation to the result. Repeat until every transformation has been applied. The output of the last transformation is the -result of the sequence. - -The transformations included in the `transformations` array may omit their `input` and `output` fields under the conditions -outlined below: - -- The `input` and `output` fields MAY be omitted for the following transformation types: - - `identity`, `scale`, `translation`, `rotation`, `affine`, `displacements`, `coordinates` -- The `input` and `output` fields MAY be omitted for `inverseOf` transformations if those fields may be omitted for the - transformation it wraps -- The `input` and `output` fields MAY be omitted for `bijection` transformations if the fields may be omitted for - both its `forward` and `inverse` transformations -- The `input` and `output` fields MAY be omitted for `sequence` transformations if the fields may be omitted for - all transformations in the sequence after flattening the nested sequence lists. -- The `input` and `output` fields MUST be included for transformations of type: `mapAxis`, and `byDimension` (see the note - below), and under all other conditions. +A `sequence` transformation consists of an ordered array of coordinate transformations, +and is invertible if every coordinate transform in the array is invertible +(though could be invertible in other cases as well). +To apply a sequence transformation to a point in the input coordinate system, +apply the first transformation in the list of transformations. +Next, apply the second transformation to the result. +Repeat until every transformation has been applied. +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. -#### coordinates and displacements +##### coordinates and displacements -`coordinates` and `displacements` transformations store coordinates or displacements in an array and interpret them as a vector -field that defines a transformation. The arrays must have a dimension corresponding to every axis of the input coordinate -system and one additional dimension to hold components of the vector. Applying the transformation amounts to looking up the -appropriate vector in the array, interpolating if necessary, and treating it either as a position directly (`coordinates`) or a -displacement of the input point (`displacements`). +`coordinates` and `displacements` transformations store coordinates or displacements in an array +and interpret them as a vector field that defines a transformation. +The arrays must have a dimension corresponding to every axis of the input coordinate system +and one additional dimension to hold components of the vector. +Applying the transformation amounts to looking up the appropriate vector in the array, +interpolating if necessary, +and treating it either as a position directly (`coordinates`) +or a displacement of the input point (`displacements`). -These transformation types refer to an array at location specified by the `"path"` parameter. 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"). +These transformation types refer to an array at location specified by the `"path"` parameter. +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"). -* If the input coordinate system has `N` axes, the array at location path MUST have `N+1` dimensions -* The field coordinate system MUST contain an axis identical to every axis of its input coordinate system in the same order. -* The field coordinate system MUST contain an axis with type `coordinate` or `displacement` respectively for transformations of type `coordinates` or `displacements`. +The `input` and `output` fields MAY be omitted if wrapped in another transformation that provides `input`/`output` +(e.g., [`sequence`](#sequence), [`inverseOf`](#inverseof), ['byDimension](#bydimension) or [`bijection`](#bijection)). + +* If the input coordinate system has `N` axes, + the array at location path MUST have `N+1` dimensions +* The field coordinate system MUST contain an axis identical to every axis + of its input coordinate system in the same order. +* The field coordinate system MUST contain an axis with type `coordinate` or `displacement`, respectively, + for transformations of type `coordinates` or `displacements`. * This SHOULD be the last axis (contiguous on disk when c-order). -* If the output coordinate system has `M` axes, the length of the array along the `coordinate`/`displacement` dimension MUST be of length `M`. +* 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. -`coordinates` and `displacements` transformations are not invertible in general, but implementations MAY approximate their -inverses. Metadata for these coordinate transforms have the following field: +`coordinates` and `displacements` transformations are not invertible in general, +but implementations MAY approximate their inverses. +Metadata for these coordinate transforms have the following fields:
interpolation attributes MAY be provided. It's value indicates
- the interpolation to use if transforming points not on the array's discrete grid.
+ 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)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.
+ 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.
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 +│ +├── .zattrs # 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. +│ +├── coordinateTransformations # transformations that use array storage go in a "coordinateTransformations" zarr group. +│ └── displacements # for example, a zarr array containing a displacement field +│ ├── .zattrs +│ └── .zarray +│ +├── volume +│ ├── .zattrs # group level attributes (multiscales) +│ └── 0 # a group containing the 0th scale +│ └── image # a zarr array +│ ├── .zattrs # physical coordinate system and transformations here +│ └── .zarray # the array attributes +└── crop + ├── .zattrs # group level attributes (multiscales) + └── 0 # a group containing the 0th scale + └── image # a zarr array + ├── .zattrs # physical coordinate system and transformations here + └── .zarray # 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. + +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 could, in some cases, 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 (see below 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. 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: + +```json +{ + "type": "inverseOf", + "transformation" : { + "type": "displacements", + "path": "/path/to/displacements", + } +} +``` + +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 + +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. 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). + + +### Transformation types + +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, it's length gives the input dimension, otherwise the length of "axes" for the coordinate +system with the name of the "input" value gives the input dimension. If the value of "input" is an array, it's +length 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 length 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` 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. `identity` transformations are invertible. + + +#### mapAxis + +`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. + + +#### translation + +`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). `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`. + +translation +: The translation parameters stored as a JSON list of numbers. The list MUST have length `N`. + + +#### scale + +`scale` transformations are special cases of affine transformations. When possible, a scale transformation +SHOULD be preferred to its equivalent affine. Input and output dimensionality MUST be identical 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. + +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`. + + +#### affine + +`affine`s are [matrix transformations](#matrix-transformations) from N-dimensional inputs to M-dimensional outputs are +represented as the upper `(M)x(N+1)` sub-matrix of a `(M+1)x(N+1)` matrix in [homogeneous +coordinates](https://en.wikipedia.org/wiki/Homogeneous_coordinates) (see examples). 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. + +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`. + + +#### rotation + +`rotation`s are [matrix transformations](#matrix-transformations) that are special cases of affine transformations. When possible, a rotation +transformation SHOULD be preferred to its 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. + +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`. + + +#### inverseOf + +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). + +```{note} +Software libraries that perform image registration 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. +``` + + +#### sequence + +A `sequence` transformation consists of an ordered array of coordinate transformations, and is invertible if every coordinate +transform in the array is invertible (though could be invertible in other cases as well). To apply a sequence transformation +to a point in the input coordinate system, apply the first transformation in the list of transformations. Next, apply the second +transformation to the result. Repeat until every transformation has been applied. The output of the last transformation is the +result of the sequence. + +The transformations included in the `transformations` array may omit their `input` and `output` fields under the conditions +outlined below: + +- The `input` and `output` fields MAY be omitted for the following transformation types: + - `identity`, `scale`, `translation`, `rotation`, `affine`, `displacements`, `coordinates` +- The `input` and `output` fields MAY be omitted for `inverseOf` transformations if those fields may be omitted for the + transformation it wraps +- The `input` and `output` fields MAY be omitted for `bijection` transformations if the fields may be omitted for + both its `forward` and `inverse` transformations +- The `input` and `output` fields MAY be omitted for `sequence` transformations if the fields may be omitted for + all transformations in the sequence after flattening the nested sequence lists. +- The `input` and `output` fields MUST be included for transformations of type: `mapAxis`, and `byDimension` (see the note + below), and under all other conditions. + + +transformations +: A non-empty array of transformations. + + +#### coordinates and displacements + +`coordinates` and `displacements` transformations store coordinates or displacements in an array and interpret them as a vector +field that defines a transformation. The arrays must have a dimension corresponding to every axis of the input coordinate +system and one additional dimension to hold components of the vector. Applying the transformation amounts to looking up the +appropriate vector in the array, interpolating if necessary, and treating it either as a position directly (`coordinates`) or a +displacement of the input point (`displacements`). + +These transformation types refer to an array at location specified by the `"path"` parameter. 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"). + +* If the input coordinate system has `N` axes, the array at location path MUST have `N+1` dimensions +* The field coordinate system MUST contain an axis identical to every axis of its input coordinate system in the same order. +* The field coordinate system MUST contain an axis with type `coordinate` or `displacement` respectively for transformations of type `coordinates` or `displacements`. + * This SHOULD be the last axis (contiguous on disk when c-order). +* 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. + +`coordinates` and `displacements` transformations are not invertible in general, but implementations MAY approximate their +inverses. Metadata for these coordinate transforms have the following field: + +
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)nearestcubicinput 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.
+