`yaozarrs.v04`#

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

Schema: https://github.com/ome/ngff/tree/7ac3430c74a66e5bcf53e41c429143172d68c0a4

Images#

Image #

Top-level OME-NGFF v0.4 image metadata.

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

Typical Structure

my_image/
├── .zattrs            # contains {"multiscales": [...]}
├── 0/                 # Highest resolution array
├── 1/                 # Next resolution level
└── labels/            # Optional segmentation masks

v0.4 vs v0.5

In v0.4, the version field is inside the multiscale objects rather than at the top level. See Multiscale.

Parameters:

Name	Type	Description	Default
`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 an image at one or 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.

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, 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`
`version`	`Literal['0.4']`		`'0.4'`
`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, v04
>>> 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"),
... ]
>>> v04.Multiscale.from_dims(dims, name="my_multiscale", n_levels=3)

Source code in src/yaozarrs/v04/_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, v04
    >>> 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"),
    ... ]
    >>> v04.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

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.4']`		`'0.4'`

LabelColor #

Display color mapping for a label value.

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

Parameters:

Name	Type	Description	Default
`label_value`	`float`	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.

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 .zattrs file (or zarr.json attributes) in a labels/ directory, which acts as a container for multiple segmentation/annotation images.

Typical Structure

my_image/
├── .zattrs            # Image metadata
├── 0/                 # Image arrays
└── labels/
    ├── .zattrs        # Contains this metadata {"labels": [...]}
    ├── cells/         # One label image
    └── nuclei/        # Another label image

Parameters:

Name	Type	Description	Default
`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 .zattrs file (or zarr.json attributes) 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/                      # Row A
│   ├── 1/                  # Well A1
│   │   ├── 0/              # FOV 0 in A1
│   │   │   ├── 0/          # Multiscale level 0
│   │   │   └── .zattrs     # contains {"multiscales": [...]}
│   │   ├── 1/              # FOV 1 in A1
│   │   └── .zattrs         # contains {"well": {...}}
│   └── 2/                  # Well A2
├── B/                      # Row B
└── .zattrs                 # contains {"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`
`version`	`Literal['0.4']`		`'0.4'`

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 .zattrs file (or zarr.json attributes) 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
├── .zattrs            # Contains this metadata
├── 0/                 # First field-of-view
│   ├── .zattrs        # Image metadata
│   ├── 0/             # Highest resolution
│   └── 1/             # Next resolution
└── 1/                 # Second field-of-view

Parameters:

Name	Type	Description	Default
`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
`version`	`Literal['0.4']`		`'0.4'`

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 #

Parameters:

Name	Type	Description	Default
`bioformats2raw_layout`	`Literal[3]`	The top-level identifier metadata added by bioformats2raw	required

Series #

Model for the ome group that contains OME-XML metadata.

Parameters:

Name	Type	Description	Default
`series`	`list[str]`	An array of the same length and the same order as the images defined in the OME-XML	required

yaozarrs.v04#

Images#

Image #

Multiscale #

from_dims classmethod #

Dataset #

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.v04`#

from_dims `classmethod` #

ndim `property` #

ndim `property` #