From 44820d213ee079d5848f409fec0081ef9d9898be Mon Sep 17 00:00:00 2001 From: Johannes Soltwedel <38459088+jo-mueller@users.noreply.github.com> Date: Thu, 2 Jul 2026 13:53:45 +0200 Subject: [PATCH 1/2] chore: fix cross references --- index.md | 35 ++++++++++++++++++----------------- 1 file changed, 18 insertions(+), 17 deletions(-) diff --git a/index.md b/index.md index 0ce51f42..93c168a6 100644 --- a/index.md +++ b/index.md @@ -189,7 +189,7 @@ The OME-Zarr Metadata is stored in the various `zarr.json` files throughout the The OME-Zarr Metadata version MUST be consistent within a hierarchy. The group `attributes` MUST contain a key `ome`. The value of the `ome` key MUST be a JSON -object that MUST contain a `version` key, the value of which MUST be a string specifying the version of the OME-Zarr specification defined by [this document](ngff-spec:spec:0.6.dev4). +object that MUST contain a `version` key, the value of which MUST be a string specifying the version of the OME-Zarr specification defined by [this document](#ngff-spec:spec:0.6.dev4). ```jsonc { @@ -244,6 +244,7 @@ or can be transformed to the same coordinate system before doing analysis. See the [example below](spec:example:coordinate_transformation). #### "axes" metadata +(axes-md)= `axes` describes the dimensions of a coordinate systems and adds an interpretation to the samples along that dimension. @@ -463,11 +464,11 @@ Depending on which, different constraints apply to the transformations, as descr For more information, see [multiscales section below](#multiscales-md). - **Inside `multiscales > coordinateTransformations`**: Additional transformations for single multiscale images MAY be stored here. - - One of `input` or `output` MUST reference the "intrinsic" coordinate system by `name` (`path` MAY be omitted or null). + - One of `input` or `output` MUST reference the "[intrinsic](#spec:hint:multiscales-intrinsic-coordinate-system)" coordinate system by `name` (`path` MAY be omitted or null). - The other MUST reference a named coordinate system in the same multiscales group (by `name`, `path` MAY be omitted or null), or in a child [labels](#labels-md) group (by `name` and `path`). - When referencing a child labels group, the transformation MUST be [`identity`](#identity-md), [`scale`](#scale-md), or [`translation`](#translation-md). -- **Inside `scene > coordinateTransformations`**: Transformations between two or more multiscales. +- **Inside `scene > coordinateTransformations`**: Transformations between two or more multiscales can be expressed here. - Both `input` and `output` MUST specify a coordinate system `name`. - `path` is required when referencing a coordinate system in a multiscale image subgroup; it MAY be omitted or null when referencing a coordinate system defined in the scene's own `coordinateSystems`. @@ -792,7 +793,7 @@ in that case, `scale` transformations are invertible. The array MUST have length `N`. :::{dropdown} Example 1 - +(spec:example:coordinate_transformation_scale)= ```{literalinclude} examples/transformations/scale.json :language: json ``` @@ -990,7 +991,7 @@ and is invertible. ##### coordinates and displacements (coordinates-displacements-md)= -`coordinates` and `displacements` transformations store a vector field of arbitrary sampling density in an ome-zarr [multiscale group](#multiscale-md), +`coordinates` and `displacements` transformations store a vector field of arbitrary sampling density in an ome-zarr [multiscale group](#multiscales-md), defining a mapping from an input coordinate system to an output coordinate system. The array contains either coordinates (absolute positions) or displacements (relative shifts) for each point in the input space. @@ -1225,7 +1226,7 @@ Each object provides the following fields: | | Field | Type | Required | Description | | --- | --- | --- | --- | --- | -| `coordinateSystems` | JSON array of objects | yes | [Coordinate system metadata](coordinate-systems-md) for the multiscale image. | +| `coordinateSystems` | JSON array of objects | yes | [Coordinate system metadata](#coordinate-systems-md) for the multiscale image. | | `datasets` | JSON array of objects | yes | Metadata about arrays storing the individual resolution levels. | | `coordinateTransformations` | JSON array of objects | no | Metadata about transformations that are applied to all resolution levels in the same manner. | | `name` | string | no | Name of the multiscale image. | @@ -1247,12 +1248,12 @@ Each object provides the following fields: the spatial axes SHOULD be ordered as `zyx`. ```{hint} -[Multiscale images](#multiscale-md) have an "intrinsic" coordinate system. +(spec:hint:multiscales-intrinsic-coordinate-system)= +[Multiscale images](#multiscales-md) have an "intrinsic" coordinate system. It will be a representation of the image in its **native physical coordinate system** and can be used for viewing and processing unless a use case dictates otherwise. - In terms of metadata, the coordinate system referred to as the "intrinsic" coordinate system in this document, -is the coordinate system that is referenced by all multiscale coordinate transformations under `datasets` as their `output` (see below). +is the coordinate system that is referenced by all multiscale coordinate transformations under `datasets` as their `output`. ``` **`datasets`** @@ -1267,19 +1268,19 @@ is the coordinate system that is referenced by all multiscale coordinate transfo Each object in `datasets` MUST contain the field `coordinateTransformations`, whose value is an array of objects that define a transformation - that maps Zarr array coordinates for this resolution level to the "intrinsic" coordinate system. + that maps Zarr array coordinates for this resolution level to the "[intrinsic](#spec:hint:multiscales-intrinsic-coordinate-system)" coordinate system. The transformation is defined according to [transformations metadata](#trafo-types-md). * **Input**: The transformation MUST take as `input` points in the array coordinate system corresponding to dataset's `path` field. - The `input` object MUST specify a `path` field matching the `path` field of the dataset. - The `name` field under `input` SHOULD be omitted. - Implementations SHOULD always treat the dataset's `path` field as if it were equal to the value of `path` under `input`. - * **Output**: The `output` of the transformation MUST be the "intrinsic" coordinate system. + - The `output` of the transformation MUST be the "[intrinsic](#spec:hint:multiscales-intrinsic-coordinate-system)" coordinate system. - The `name` field of `output` MUST be the `name` of a coordinate system. - It MUST be the same value for every resolution level in a single multiscales - The `path` field of `output` SHOULD be omitted. - The coordinate system referenced by all `output` fields of the coordinate transformations (the "intrinsic" coordinate system) + The coordinate system referenced by all `output` fields of the coordinate transformations (the "[intrinsic](#spec:hint:multiscales-intrinsic-coordinate-system)" coordinate system) will be a representation of the image in its native physical coordinate system. It should be used for viewing and processing unless a use case dictates otherwise. @@ -1300,14 +1301,14 @@ is the coordinate system that is referenced by all multiscale coordinate transfo and the first resolution for the given axis, defaulting to 1.0 if there is no downsampling along the axis. This is strongly recommended - so that the the "intrinsic" coordinate system of the image avoids more complex transformations. + so that the the "[intrinsic](#spec:hint:multiscales-intrinsic-coordinate-system)" coordinate system of the image avoids more complex transformations. **`coordinateTransformations`** : If applications require additional transformations, each `multiscales` object MAY contain the field `coordinateTransformations`, describing transformations that are applied to all resolution levels in the same manner. The following constraints apply: - - One of `input` or `output` MUST reference the "intrinsic" coordinate system by `name` (`path` MAY be omitted or null). + - One of `input` or `output` MUST reference the "[intrinsic](#spec:hint:multiscales-intrinsic-coordinate-system)" coordinate system by `name` (`path` MAY be omitted or null). - The other of `input` or `output` MUST reference either: - A named coordinate system in the same multiscales group (by `name`, `path` MAY be omitted or null), or - A named coordinate system in a child [labels](#labels-md) group (by `name` and `path`). @@ -1428,8 +1429,8 @@ at the same level of the Zarr hierarchy as the resolution levels for the origina The following requirements for the parent image group apply: - This image group MUST implement the [multiscales](#multiscales-md) specification. - The image group MAY contain an additional coordinate transformation - that links its "intrinsic" coordinate system to the "intrinsic" coordinate system of each label image in the `labels` group. - If no such transformation is provided, the "intrinsic" coordinate system of the image group is usually understood to be the same as the "intrinsic" coordinate system of each label image in the `labels` group. + that links its "[intrinsic](#spec:hint:multiscales-intrinsic-coordinate-system)" coordinate system to the "[intrinsic](#spec:hint:multiscales-intrinsic-coordinate-system)" coordinate system of each label image in the `labels` group. + If no such transformation is provided, the "[intrinsic](#spec:hint:multiscales-intrinsic-coordinate-system)" coordinate system of the image group is usually understood to be the same as the "[intrinsic](#spec:hint:multiscales-intrinsic-coordinate-system)" coordinate system of each label image in the `labels` group. - This transformation, if specified, MUST be one of [`identity`](#identity-md), ['scale'](#scale-md), a ['translation'](#translation-md) or a ['sequence'](#sequence-md) of a scale and a translation transformation. @@ -1503,7 +1504,7 @@ In the `zarr.json` under the image.zarr group, an explicit `identity` transform the coordinate system named `"physical"` in the multiscales metadata of the original image is the same as the coordinate system named `"physical"` in the multiscales metadata of the label image: -```{literalinclude} examples/multiscales_strict/multiscale_with_reference_to_label.json +```{literalinclude} examples/multiscales_strict/multiscale_reference_to_label.json :language: json ``` From e092edd3d8dbb301bff401c1a15629d6fa9b2c45 Mon Sep 17 00:00:00 2001 From: Johannes Soltwedel <38459088+jo-mueller@users.noreply.github.com> Date: Thu, 2 Jul 2026 13:55:09 +0200 Subject: [PATCH 2/2] chore: ref to intrinsic hint everywhere --- index.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/index.md b/index.md index 93c168a6..730b4c56 100644 --- a/index.md +++ b/index.md @@ -572,7 +572,7 @@ indicating that choice explicitly will be important for interoperability. This can be expressed in the metadata in multiple ways, including: - One can embed a transformation defined in array units into a `sequence` transformation that includes the appropriate scale transformation and its inverse to convert to physical units (see example below). -- One can define a unitless coordinate system and connect it to the "intrinsic" coordinate system +- One can define a unitless coordinate system and connect it to the "[intrinsic](#spec:hint:multiscales-intrinsic-coordinate-system)" coordinate system with a scale transformation that has the appropriate scale factors to convert to physical units. :::{dropdown} Example: Embedded expression @@ -615,7 +615,7 @@ and finally the second `scale` transformation converts the coordinates back to p :::{dropdown} Example: Unitless coordinate system -Alternatively, users may choose to define a unitless coordinate system and connect it to the "intrinsic" coordinate system +Alternatively, users may choose to define a unitless coordinate system and connect it to the "[intrinsic](#spec:hint:multiscales-intrinsic-coordinate-system)" coordinate system with a scale transformation that has the appropriate scale factors to convert to physical units. In the context of multiscales metadata, this could look like this: @@ -665,7 +665,7 @@ In the context of multiscales metadata, this could look like this: } ``` In this case, the `scale` transformation under `coordinateTransformations` -defines the mapping from the "intrinsic" coordinate system to the unitless "array" coordinate system. +defines the mapping from the "[intrinsic](#spec:hint:multiscales-intrinsic-coordinate-system)" coordinate system to the unitless "array" coordinate system. Another transformation (e.g. in a `scene`) could then use the "array" coordinate system as an input or output to define transformations in array units. ::: @@ -1524,7 +1524,7 @@ The `zarr.json` under the `labels` group contains a JSON object with the key `la ``` In the `zarr.json` under the `cell_segmentation` multiscales image group, -a coordinate system named `"physical"` serves as the "intrinsic" coordinate system for the label image. +a coordinate system named `"physical"` serves as the "[intrinsic](#spec:hint:multiscales-intrinsic-coordinate-system)" coordinate system for the label image. The `image-label` field contains information about the source image and display colors for the label image, i.e., a label image in which 0s and 1s represent intercellular and cellular space, respectively: