OMEZarr classes (`ome_zarr.classes`)

class ome_zarr.classes.image.OMEZarrImage(data: Array | ndarray, axes: Sequence[str] | str, scale: dict[str, float] | None = None, axes_units: dict[str, str] | None = None, name: str = 'image')[source]

Single-scale image representation with metadata.

This class serves as the entrypoint to creating ome-zarr images on disk. The OMEZarrMultiscale class and OMEZarrLabels multi-resolution representations of ome-zarr images can be created from instances of this class.

Parameters:

data (dask.array.Array or numpy.ndarray) – The image data array. Can be a NumPy array or a Dask array. If a NumPy array is provided, it will be converted to a Dask array internally.
axes (Sequence[str] or str) – The axis names corresponding to the data array axes, i.e. (‘c’, ‘z’, ‘y’, ‘x’).
scale (dict[str, float] | None) – The physical scale for each axis, with keys as axis names, e.g. {‘x’: 0.1, ‘y’: 0.1, ‘z’: 0.5}. Missing axes are auto-set to 1.0 with a warning. Default is None, which sets all scales to 1.0.
axes_units (dict[str, str] | None) – Units for each axis, e.g. {‘x’: ‘micrometer’, ‘y’: ‘micrometer’}. Default is None (no units).
name (str) – Name of the image. Default is “image”.

Example

import numpy as np
data = np.random.poisson(lam=10, size=(2, 10, 128, 128)).astype(np.uint8)
image = OMEZarrImage(
    data=data,
    axes="czyx",
    scale={"c": 1.0, "z": 0.5, "y": 0.1, "x": 0.1},
    axes_units={"c": None, "z": "micrometer", "y": "micrometer", "x": "micrometer"},
    name="my_image",
)

Container for multiscale image pyramid with OME-Zarr metadata.

If built from an instance of OMEZarrImage, the instantiation of this class handles the construction of the ome-zarr multi-resolution scheme as delayed dask arrays. It can be used to write such arrays and associated metadata to disk and read from local and remote storages.

This class implements convenient handling of additional subgroups (i.e., labels) or metadata fields (i.e., the omero metadata field for display settings).

Parameters:

image (OMEZarrImage) – The OMEZarrImage instance from which to build the multi-resolution levels.
scale_factors (list[int] | tuple[int, ...] | list[dict[str, int]] | None) – Scale factors for each pyramid level. If a list of ints or tuple is provided, it is applied uniformly across all spatial axes. If a list of dicts is provided, each dict should specify scale factors for each axis, e.g. {‘x’: 2, ‘y’: 2, ‘z’: 1}. Default is (2, 4, 8, 16).
method (ome_zarr.scale.Methods | str | None) – Rescaling method to use when generating pyramid levels. Default is Methods.RESIZE.
coordinateTransformations – Additional coordinate transformations to include in the metadata for each level.
labels (OMEZarrLabels | list[OMEZarrLabels] | dict[str, OMEZarrLabels] | None) – Labels associated with the image. Can be a single OMEZarrLabels instance, a list of them, or a dict mapping label names to OMEZarrLabels instances. Default is None (no labels).
channel_names (list[str] | None) – List of channel names corresponding to the ‘c’ axis, e.g. [‘DAPI’, ‘GFP’, ‘RFP’]. Default is None (no channel names).
channel_colors (list[list[int]] | list[str] | None) – List of colors for each channel corresponding to the ‘c’ axis. Can be passed as a list of RGB values (i.e., [[255, 0, 0], [0, 255, 0], …]) or as hex strings (i.e., [‘FF0000’, ‘00FF00’, ‘0000FF’]). Default is None (no channel colors).
contrast_limits (list[tuple[float, float]] | None) – List of contrast limits for each channel corresponding to the ‘c’ axis, e.g. [(0, 255), (0, 1000), …]. Default is None (no contrast limits).

images

List of images at each pyramid level.

Type:: list[OMEZarrImage]

labels

Dictionary mapping label names to OMEZarrLabels instances, or None if no labels are associated.

Type:: dict[str, OMEZarrLabels] | None

metadata

The OME-Zarr metadata associated with this multiscale image, stored as a Pydantic model instance. Automatically created upon instantiation of the class.

Type:: ome_zarr_models.v05.multiscales.Multiscale

to_ome_zarr(group, storage_options, version, compute, overwrite): Write the multiscale image pyramid and metadata to an OME-Zarr group.

from_ome_zarr(group): Load a multiscale image pyramid and metadata from an OME-Zarr group.

Examples

import numpy as np
from ome_zarr import OMEZarrImage, OMEZarrMultiscale
data = np.random.poisson(lam=10, size=(2, 10, 128, 128)).astype(np.uint8)
image = OMEZarrImage(
    data=data,
    axes="czyx",
)
multiscale = OMEZarrMultiscale(
    image=image,
    scale_factors=[2, 4, 8, 16],
    channel_names=["DAPI", "GFP"]
)

Container for label images with OME-Zarr metadata.

This class extends OMEZarrMultiscaleBase and implements handling of additional metadata fields specific to label images, such as image-label metadata.

Parameters:

image (OMEZarrImage)
scale_factors (list[int] | tuple[int, ...] | list[dict[str, int]] | None, optional) – Scale factors for each pyramid level. If a list of ints or tuple is provided, it is applied uniformly across all spatial axes. If a list of dicts is provided, each dict should specify scale factors for each axis, e.g. {‘x’: 2, ‘y’: 2, ‘z’: 1}. Default is (2, 4, 8, 16).
method (str | ome_zarr.scale.Methods, optional) – Rescaling method to use when generating pyramid levels. Default is Methods.NEAREST, since these are labels.
auto_parse_labels (bool, optional) –

Whether to automatically inspect the data for present label values and write these
to the metadata. This can be time consuming for large datasets, so it is optional. Default is True.

Attributes
----------
images (list[OMEZarrImage]) – List of label images at each pyramid level.
image_label (Label | None) – Optional image-label metadata for rendering label images, or None if not provided.
metadata (ome_zarr_models.v05.multiscales.Multiscale) – The OME-Zarr metadata associated with this multiscale image, stored as a Pydantic model instance. Automatically created upon instantiation of the class.

OMEZarr classes (ome_zarr.classes)

OMEZarr classes (`ome_zarr.classes`)