Skip to content

More and fixed cross refs #169

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
joshmoore merged 3 commits into from
Jul 2, 2026
Merged

More and fixed cross refs #169

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
44820d2
chore: fix cross references
jo-mueller Jul 2, 2026
e092edd
chore: ref to intrinsic hint everywhere
jo-mueller Jul 2, 2026
997bb20
Merge branch 'main' into more-and-fixed-cross-refs
joshmoore Jul 2, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
43 changes: 22 additions & 21 deletions index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
{
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -464,11 +465,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`.
Expand Down Expand Up @@ -572,7 +573,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
Expand Down Expand Up @@ -615,7 +616,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:

Expand Down Expand Up @@ -665,7 +666,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.
:::

Expand Down Expand Up @@ -852,7 +853,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
```
Expand Down Expand Up @@ -1050,7 +1051,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.
Expand Down Expand Up @@ -1285,7 +1286,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. |
Expand All @@ -1307,12 +1308,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`**
Expand All @@ -1327,19 +1328,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.

Expand All @@ -1360,14 +1361,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`).
Expand Down Expand Up @@ -1488,8 +1489,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.

Expand Down Expand Up @@ -1563,7 +1564,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
```

Expand All @@ -1583,7 +1584,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:

Expand Down
Loading