`yaozarrs.v05`#

Specification: https://ngff.openmicroscopy.org/0.5/

Schema: https://github.com/ome/ngff/tree/8cbba216e37407bd2d4bd5c7128ab13bd0a6404e

Images#

Image #

Top-level OME-NGFF image metadata.

This model corresponds to the zarr.json file in an image group. It contains one or more multiscale pyramids plus optional OMERO rendering hints.

Typical Structure

my_image/
├── zarr.json          # contains ["ome"]["multiscales"]
├── 0/                 # Highest resolution array
├── 1/                 # Next resolution level
└── labels/            # Optional segmentation masks
    ├── zarr.json      # contains ["ome"]["labels"]
    └── 0              # Multiscale, labeled image.

Note

For the optional labels group, see LabelsGroup.

Parameters:

Name	Type	Description	Default
`version`	`Literal['0.5']`	OME-NGFF specification version	`'0.5'`
`multiscales`	`list[Multiscale]`	One or more multiscale image pyramids in this group	required
`omero`	`Omero \| None`	Optional OMERO rendering metadata for visualization	`None`

Multiscale #

Multi-resolution image pyramid (<=5D) with coordinate metadata.

Defines a image at one ore more resolution levels, along with the coordinate system that relates array indices to physical space. This is the core metadata for any OME-NGFF image.

Resolution Ordering

Datasets must be ordered from highest to lowest resolution (i.e., finest to coarsest sampling).

Parameters:

Name	Type	Description	Default
`name`	`str \| None`	Optional identifier for this multiscale image	`None`
`axes`	`list[SpaceAxis \| TimeAxis \| ChannelAxis \| CustomAxis]`	Ordered list of dimension axes defining the coordinate system	required
`datasets`	`list[Dataset]`	Resolution pyramid levels, ordered from highest to lowest resolution	required
`coordinateTransformations`	`list[ScaleTransformation \| TranslationTransformation] \| None`	Coordinate transformations that are applied to all resolution levels in the same manner.	`None`
`type`	`str \| None`	Type of downscaling method used to generate the multiscale image pyramid.	`None`
`metadata`	`dict \| None`	Unstructured key-value pair with additional information about the downscaling method.	`None`

from_dims `classmethod` #

from_dims(
    dims: Sequence[DimSpec],
    name: str | None = None,
    n_levels: int = 1,
) -> Self

Convenience constructor: Create Multiscale from a sequence of DimSpec.

Parameters:

Name	Type	Description	Default
`dims`	`Sequence[DimSpec]`	A sequence of dimension specifications defining the image dimensions. Must follow OME-Zarr axis ordering: `[time,] [channel,] space...`	required
`name`	`str \| None`	Name for the multiscale. Default is None.	`None`
`n_levels`	`int`	Number of resolution levels in the pyramid. Default is 1.	`1`

Returns:

Type	Description
`Multiscale`	A fully configured Multiscale model.

Examples:

>>> from yaozarrs import DimSpec, v05
>>> dims = [
...     DimSpec(name="t", size=512, unit="second"),
...     DimSpec(
...         name="z", size=50, scale=2.0, unit="micrometer", scale_factor=1.0
...     ),
...     DimSpec(name="y", size=512, scale=0.5, unit="micrometer"),
...     DimSpec(name="x", size=512, scale=0.5, unit="micrometer"),
... ]
>>> v05.Multiscale.from_dims(dims, name="my_multiscale", n_levels=3)

Source code in src/yaozarrs/v05/_image.py

@classmethod
def from_dims(
    cls,
    dims: Sequence[DimSpec],
    name: str | None = None,
    n_levels: int = 1,
) -> Self:
    """Convenience constructor: Create Multiscale from a sequence of DimSpec.

    Parameters
    ----------
    dims : Sequence[DimSpec]
        A sequence of dimension specifications defining the image dimensions.
        Must follow OME-Zarr axis ordering: `[time,] [channel,] space...`
    name : str | None, optional
        Name for the multiscale. Default is None.
    n_levels : int, optional
        Number of resolution levels in the pyramid. Default is 1.

    Returns
    -------
    Multiscale
        A fully configured Multiscale model.

    Examples
    --------
    >>> from yaozarrs import DimSpec, v05
    >>> dims = [
    ...     DimSpec(name="t", size=512, unit="second"),
    ...     DimSpec(
    ...         name="z", size=50, scale=2.0, unit="micrometer", scale_factor=1.0
    ...     ),
    ...     DimSpec(name="y", size=512, scale=0.5, unit="micrometer"),
    ...     DimSpec(name="x", size=512, scale=0.5, unit="micrometer"),
    ... ]
    >>> v05.Multiscale.from_dims(dims, name="my_multiscale", n_levels=3)
    """
    from yaozarrs._dim_spec import _axes_datasets

    return cls(name=name, **_axes_datasets(dims, n_levels))  # type: ignore

Dataset #

A single resolution level in a multiscale image pyramid.

Each dataset points to a Zarr array and defines how its indices map to physical coordinates. Together, multiple datasets form a resolution pyramid where each level represents the same physical region at different sampling rates.

Parameters:

Name	Type	Description	Default
`path`	`str`	Path to the Zarr array for this resolution level, relative to the parent multiscale group. All strings are allowed according to the spec, but prefer using only alphanumeric characters, dots (.), underscores (_), or hyphens (-) to avoid issues on some filesystems or when used in URLs.	required
`coordinateTransformations`	`list[ScaleTransformation \| TranslationTransformation]`	Transformations mapping array indices to physical coordinates. Must include exactly one scale transformation, and optionally one translation.	required

scale_transform `property` #

scale_transform: ScaleTransformation

Return the scale transformation from the list.

(CoordinateTransformsList validator ensures there is exactly one.)

translation_transform `property` #

translation_transform: TranslationTransformation | None

Return the translation transformation from the list, if present.

(CoordinateTransformsList validator ensures there is at most one.)

ScaleTransformation #

Maps array indices to physical coordinates via scaling.

Defines the pixel/voxel size in physical units for each dimension. Every dataset must have exactly one scale transformation.

Note

Scale values represent physical size per pixel. For example, a scale of [0.5, 0.5] means each pixel is 0.5 units wide in physical space.

Parameters:

Name	Type	Description	Default
`type`	`Literal['scale']`		`'scale'`
`scale`	`list[float]`	Scaling factor for each dimension in physical units per pixel	required

ndim `property` #

ndim: int

Number of dimensions in this transformation.

TranslationTransformation #

Translates the coordinate system origin in physical space.

Specifies the physical coordinates of the origin (index [0, 0, ...]). At most one translation may be present per dataset, and it must appear after the scale transformation.

Parameters:

Name	Type	Description	Default
`type`	`Literal['translation']`		`'translation'`
`translation`	`list[float]`	Translation offset for each dimension in physical units	required

ndim `property` #

ndim: int

Number of dimensions in this transformation.

Labels#

LabelImage #

A complete label image with multiscale pyramids and label metadata.

Combines the standard image structure (multiscale pyramids, axes, etc.) with label-specific metadata (colors, properties, source reference). Label images must use integer data types.

Relationship to Image

This is an Image with additional image-label metadata. The multiscale pyramids follow the same structure as regular images but contain integer segmentation masks instead of intensity data.

Parameters:

Name	Type	Description	Default
`image_label`	`ImageLabel`	Label-specific metadata (colors, properties, source link)	required

ImageLabel #

Metadata for a segmentation/annotation label image.

Enhances a multiscale label image with display colors, semantic properties, and links back to the source intensity image. Label images are integer-valued arrays where each unique value represents a distinct object or region.

Parameters:

Name	Type	Description	Default
`colors`	`list[LabelColor] \| None`	Color mappings for label values, used for visualization	`None`
`properties`	`list[LabelProperty] \| None`	Arbitrary metadata properties for individual label values	`None`
`source`	`LabelSource \| None`	Reference to the source intensity image that was segmented	`None`
`version`	`Literal['0.5'] \| None`	OME-NGFF image-label specification version (often omitted)	`None`

LabelColor #

Display color mapping for a label value.

Associates a specific label integer value with an RGBA color for visualization purposes.

Parameters:

Name	Type	Description	Default
`label_value`	`float`	Integer label value from the segmentation image	required
`rgba`	`list[int] \| None`	RGBA color as [red, green, blue, alpha], each 0-255	`None`

LabelProperty #

Custom metadata for a label value.

Associates arbitrary key-value properties with a specific label integer. Different labels can have different sets of properties - there's no requirement for consistency across labels.

Example

LabelProperty(label_value=1, cell_type="neuron", area=1250.5)
LabelProperty(label_value=2, cell_type="glia", perimeter=180.3)

Parameters:

Name	Type	Description	Default
`label_value`	`int`	Integer label value from the segmentation image	required

LabelSource #

Reference to the source image that was segmented.

Points back to the original intensity image from which this label image was derived.

Parameters:

Name	Type	Description	Default
`image`	`str \| None`	Relative path to the source image group (default: '../../', pointing to the parent of the labels/ directory)	`None`

LabelsGroup #

Top-level labels collection metadata.

This model corresponds to the zarr.json file in a labels/ directory, which acts as a container for multiple segmentation/annotation images.

Typical Structure

my_image/
├── zarr.json          # Image metadata
├── 0/                 # Image arrays
└── labels/
    ├── zarr.json      # Contains this metadata
    ├── cells/         # One label image
    └── nuclei/        # Another label image

Parameters:

Name	Type	Description	Default
`version`	`Literal['0.5']`	OME-NGFF specification version	`'0.5'`
`labels`	`list[str]`	Paths to individual label image groups within this collection	required

Plates#

Plate #

Top-level plate metadata for high-content screening.

This model corresponds to the zarr.json file in a plate group, organizing a microplate's wells in a grid layout. Each well contains one or more fields-of-view, which in turn contain multiscale images.

Typical Structure

my_plate.ome.zarr
├── A                       # Col A
│   ├── 1                   # Row 1
│   │   ├── 0               # FOV 0 (in A1)
│   │   │   ├── 0           # FOV 0 - Multiscale level 0
│   │   │   └── zarr.json   # contains ["ome"]["multiscales"]
│   │   ├── 1               # FOV 1 (in A1)
│   │   │   ├── 0           # FOV 1 - Multiscale level 0
│   │   │   └── zarr.json   # contains ["ome"]["multiscales"]
│   │   └── zarr.json       # well metadata (contains ['ome']['well'])
│   ├── 2
│   │   └── ...
│   └── 3
│       └── ...
├── B
│   └── ...
├── C
│   └── ...
└── zarr.json                # plate metadata (contains ['ome']['plate'])

Note

PlateDef #

Plate layout and well organization.

Defines the grid structure of a microplate and maps wells to their data. This is the core content of the plate metadata field.

Parameters:

Name	Type	Description	Default
`columns`	`list[Column]`	Column definitions for the plate grid	required
`rows`	`list[Row]`	Row definitions for the plate grid	required
`wells`	`list[PlateWell]`	List of all wells present in this plate with their grid positions	required
`acquisitions`	`list[Acquisition] \| None`	Imaging acquisition runs performed on this plate	`None`
`field_count`	`int \| None`	Maximum number of fields-of-view per well across the entire plate	`None`
`name`	`str \| None`	Human-readable name for this plate	`None`

Column #

A column in the plate grid.

Columns are typically numbered (1, 2, 3, ...) but can use any alphanumeric identifier.

Parameters:

Name	Type	Description	Default
`name`	`str`	Column identifier (typically numeric, e.g., '1', '2', '3')	required

Row #

A row in the plate grid.

Rows are typically lettered (A, B, C, ...) but can use any alphanumeric identifier.

Parameters:

Name	Type	Description	Default
`name`	`str`	Row identifier (typically alphabetic, e.g., 'A', 'B', 'C')	required

PlateWell #

A well location reference within a plate.

Maps a well's row/column position to its data location. This is a lightweight reference used in plate metadata, not the full well group (see Well for the complete well metadata).

Parameters:

Name	Type	Description	Default
`path`	`str`	Relative path to the well's group (format: 'row/column', e.g., 'A/1')	required
`rowIndex`	`int`	Zero-based index into the plate's rows list	required
`columnIndex`	`int`	Zero-based index into the plate's columns list	required

Acquisition #

An imaging acquisition run within a plate.

In high-content screening, multiple acquisition runs may be performed on the same plate (e.g., at different timepoints or with different settings). This class groups related images from a single acquisition session.

Parameters:

Name	Type	Description	Default
`id`	`int`	Unique identifier within the plate for this acquisition	required
`maximumfieldcount`	`int \| None`	Maximum number of fields-of-view across all wells in this acquisition	`None`
`name`	`str \| None`	Human-readable name for this acquisition	`None`
`description`	`str \| None`	Detailed description of the acquisition parameters or purpose	`None`
`starttime`	`int \| None`	Acquisition start time as Unix epoch timestamp (seconds since 1970-01-01)	`None`
`endtime`	`int \| None`	Acquisition end time as Unix epoch timestamp (seconds since 1970-01-01)	`None`

Well #

Top-level well metadata within a plate.

This model corresponds to the zarr.json file in a well group. It lists all fields-of-view (imaging positions) captured within this well.

Typical Structure

A/1/                   # Well at row A, column 1
├── zarr.json          # Contains this metadata
├── 0/                 # First field-of-view
│   ├── zarr.json      # Image metadata
│   ├── 0/             # Highest resolution
│   └── 1/             # Next resolution
└── 1/                 # Second field-of-view

Parameters:

Name	Type	Description	Default
`version`	`Literal['0.5']`	OME-NGFF specification version	`'0.5'`
`well`	`WellDef`	Field-of-view organization for this well	required

WellDef #

Organization of fields-of-view within a well.

This is the core content of the well metadata field, listing all imaging positions captured for this well.

Parameters:

Name	Type	Description	Default
`images`	`list[FieldOfView]`	List of all fields-of-view imaged in this well	required

FieldOfView #

A single field-of-view (imaging position) within a well.

Wells typically contain multiple fields-of-view when the well area is larger than a single camera frame. Each field-of-view is a complete multiscale image.

This class appears within the images list of a WellDef.

Parameters:

Name	Type	Description	Default
`path`	`str`	Relative path to this field's image group (typically a number like '0', '1', etc.)	required
`acquisition`	`int \| None`	Acquisition ID linking this field to a specific acquisition run. Required when the parent plate has multiple acquisitions.	`None`

Collections#

Bf2Raw #

Model for zarr.json in a group representing multi-series image collections.

The bioformats2raw layout was added in v0.4 as a transitional specification to specify filesets that already exist in the wild. An upcoming NGFF specification will replace this layout with explicit metadata.

This model is a transitional spec for representing multi-position image collections in OME-NGFF v0.5. It is currently the only way to represent multi-position image collections. It also has a recommended place for OME-XML metadata.

Typical Structure

root.ome.zarr             # One converted fileset from bioformats2raw
├── zarr.json             # Contains "bioformats2raw.layout" metadata
├── OME                   # Special group for containing OME metadata
│   ├── zarr.json         # Contains "series" metadata
│   └── METADATA.ome.xml  # OME-XML file stored within the Zarr fileset
├── 0                     # First image in the collection
├── 1                     # Second image in the collection
└── ...

Note

The OME/zarr.json file typically contains Series metadata that explicitly lists image paths. If not present, images MUST be numbered as shown above, starting from 0, e.g., 0/, 1/, 2/, etc.

Parameters:

Name	Type	Description	Default
`version`	`Literal['0.5']`	OME-NGFF specification version	`'0.5'`
`bioformats2raw_layout`	`Literal[3]`	Layout version marker added by bioformats2raw (currently 3)	required

Series #

Model for OME/zarr.json in an Bf2Raw collection.

Used when converting files containing multiple distinct images (e.g., multi-series microscopy formats) to OME-NGFF. Each series becomes a separate image group, and this metadata lists them all.

Typical Structure

root.ome.zarr             # One converted fileset from bioformats2raw
├── zarr.json             # Contains "bioformats2raw.layout" metadata
├── OME                   # Special group for containing OME metadata
│   ├── zarr.json         # Contains "series" metadata
│   └── METADATA.ome.xml  # OME-XML file stored within the Zarr fileset
├── 0                     # First image in the collection
├── 1                     # Second image in the collection
└── ...

Note

The spec is ambiguous about whether series is required. This library treats it as required for disambiguation. Since otherwise this model would simply contain "version".

Parameters:

Name	Type	Description	Default
`version`	`Literal['0.5']`	OME-NGFF specification version	`'0.5'`
`series`	`list[str]`	Ordered list of paths to image groups, matching the order in the companion OME-XML metadata	required

yaozarrs.v05#

Images#

Image #

Multiscale #

from_dims classmethod #

Dataset #

scale_transform property #

translation_transform property #

ScaleTransformation #

ndim property #

TranslationTransformation #

ndim property #

Labels#

LabelImage #

ImageLabel #

LabelColor #

LabelProperty #

LabelSource #

LabelsGroup #

Plates#

Plate #

PlateDef #

Column #

Row #

PlateWell #

Acquisition #

Well #

WellDef #

FieldOfView #

Collections#

Bf2Raw #

Series #

`yaozarrs.v05`#

from_dims `classmethod` #

scale_transform `property` #

translation_transform `property` #

ndim `property` #

ndim `property` #