Writer (ome_zarr.writer)

Image writer utility

ome_zarr.writer.check_format(group: Group, fmt: Format | None = None) → Format[source]

Check if the format is valid for the given group

ome_zarr.writer.check_group_fmt(group: Group | str, fmt: Format | None = None, mode: str = 'a') → tuple[Group, Format][source]

Create group if string, according to fmt OR check fmt is compatible with group

ome_zarr.writer.write_image(image: Array | ndarray, group: Group | str, scale_factors: list[int] | tuple[int, ...] | list[dict[str, int]] = (2, 4, 8, 16), method: Methods | None = Methods.RESIZE, scaler: Scaler | None = None, fmt: Format | None = None, axes: str | list[str] | list[dict[str, str]] | None = None, coordinate_transformations: list[list[dict[str, Any]]] | None = None, storage_options: dict[str, Any] | list[dict[str, Any]] | None = None, compute: bool | None = True, **metadata: str | dict[str, Any] | list[dict[str, Any]]) → list[source]

Write an image to the zarr store according to the OME-Zarr specification, supporting multiscale pyramids.

Parameters:

  • image (numpy.ndarray or dask.array.Array) – The image data to save. A downsampling pyramid will be computed if scale_factors is provided. Image array MUST be up to 5-dimensional with dimensions ordered (t, c, z, y, x). Can be a NumPy or Dask array.

  • group (zarr.Group or str) – The zarr group to write the metadata, or a path to create

  • scale_factors (list of int or list of dict, optional) – The downsampling factors for each pyramid level. Default: [2, 4, 8, 16]. Passing a list of integers (i.e., [2, 4, 8]) will apply the downsampling in all spatial dimensions except the z dimension, which will be left at a scale factor of 1. To apply downsampling to the z-dimension, pass the scale factors as a list of dicts, e.g. [{“z”: 2, “y”: 2, “x”: 2}, {“z”: 4, “y”: 4, “x”: 4}, {“z”: 8, “y”: 8, “x”: 8}]. If dimensions are omitted in this dictionary, the downsampling factor for that dimension will default to 1.

  • method (ome_zarr.scale.Methods, optional) – Downsampling method to use. Available methods are: - nearest: Nearest neighbor downsampling. - resize: Resize-based downsampling using skimage.transform.resize with anti-aliasing (default). - laplacian: Laplacian pyramid downsampling using skimage.transform.pyramid_laplacian. - local_mean: Local mean downsampling using skimage.transform.downscale_local_mean. - zoom: Zoom-based downsampling using scipy.ndimage.zoom.

  • scaler (ome_zarr.scale.Scaler, optional) – [DEPRECATED] Scaler implementation for downsampling the image. Passing this argument will raise a warning and is no longer supported. Use scale_factors and method instead.

  • fmt (ome_zarr.format.Format, optional) – The format of the ome_zarr data which should be used. Defaults to the most current.

  • axes (list of str or list of dicts, optional) – The names of the axes, e.g. [“t”, “c”, “z”, “y”, “x”]. Ignored for versions 0.1 and 0.2. Required for version 0.3 or greater.

  • coordinate_transformations (list of list of dict, optional) – For each resolution, a list of transformation dicts (not validated). Each list of dicts is added to each dataset in order.

  • storage_options (dict or list of dict, optional) –

    Options to be passed on to the storage backend. A list must match the number of datasets in a multiresolution pyramid. Allows different chunk sizes for each level. Regarding the key, value pairs in the dictionar(y)(ies), these depend both on the zarr_format used for writing and the dask version being used. For dask version <=2025.11.0, please refer to https://zarr.readthedocs.io/en/stable/api/zarr/create/#zarr.create for arguments that can be passed on. For >=2026.3.0 and up, please refer to https://zarr.readthedocs.io/en/stable/api/zarr/create/#zarr.create_array. It might be that you have to adjust the version of the docs. Note that the docs will also mention the differences of allowed arguments between zarr_format 2 and 3.

    Note: for chunks the default of auto is not allowed. This because the argument here refers to zarr chunks and autochunking here can result in different chunks then for the dask array. This can cause inconsistent overlap between dask and zarr chunks, potentially resulting in corrupted data. The default will be that if no sharding is specified, that the chunks correspond to the dask chunksize. This is also the case when chunks are provided as None and no sharding is provided.

  • compute (bool, optional) – If True, compute immediately; otherwise, return a list of dask.delayed.Delayed objects.

  • **metadata (dict) – Additional metadata to store.

Returns:

Empty list if compute is True, otherwise a list of dask.delayed.Delayed objects representing the value to be computed by dask.

Return type:

list

Notes

The scaler argument is deprecated and will be removed in a future version. Use scale_factors and method for all new code.

ome_zarr.writer.write_label_metadata(group: Group | str, name: str, colors: list[dict[str, Any]] | None = None, properties: list[dict[str, Any]] | None = None, fmt: Format | None = None, **metadata: list[dict[str, Any]] | dict[str, Any] | str) → None[source]

Write image-label metadata to the group.

The label data must have been written to a sub-group, with the same name as the second argument.

Parameters:

  • group (zarr.Group) – The zarr group or path to write the metadata in.

  • name (str) – The name of the label sub-group.

  • colors (list of JSONDict, optional) – Fixed colors for (a subset of) the label values. Each dict specifies the color for one label and must contain the fields “label-value” and “rgba”.

  • properties (list of JSONDict, optional) – Additional properties for (a subset of) the label values. Each dict specifies additional properties for one label. It must contain the field “label-value” and may contain arbitrary additional properties.

  • fmt (ome_zarr.format.Format, optional) – The format of the ome_zarr data which should be used. Defaults to the most current.

ome_zarr.writer.write_labels(labels: ndarray | Array, group: Group | str, name: str, scaler: Scaler | None = None, scale_factors: list[int] | tuple[int, ...] | list[dict[str, int]] = (2, 4, 8, 16), method: Methods = Methods.NEAREST, fmt: Format | None = None, axes: str | list[str] | list[dict[str, str]] | None = None, coordinate_transformations: list[list[dict[str, Any]]] | None = None, storage_options: dict[str, Any] | list[dict[str, Any]] | None = None, label_metadata: dict[str, Any] | None = None, compute: bool | None = True, **metadata: dict[str, Any]) → list[source]

Write image label data to disk, including multiscale and image-label metadata. Creates the label data in the sub-group “labels/{name}”.

Parameters:

  • labels (numpy.ndarray or dask.array.Array) – The label data to save. A downsampling pyramid will be computed if scale_factors is provided. Label array MUST be up to 5-dimensional with dimensions ordered (t, c, z, y, x).

  • group (zarr.Group) – The group within the zarr store to write the metadata in.

  • name (str) – The name of this labels data.

  • scaler (ome_zarr.scale.Scaler, optional) – [DEPRECATED] Scaler implementation for downsampling the label data. Passing this argument will raise a warning and is no longer supported. Use scale_factors and method instead.

  • scale_factors (tuple of int, optional) – The downsampling factors for each pyramid level. Default: (2, 4, 8, 16). Passing a list of integers (i.e., [2, 4, 8]) will apply the downsampling in all spatial dimensions except the z dimension, which will be left at a scale factor of 1. To apply downsampling to the z-dimension, pass the scale factors as a list of dicts, e.g. [{“z”: 1, “y”: 2, “x”: 2}, {“z”: 1, “y”: 4, “x”: 4}, {“z”: 1, “y”: 8, “x”: 8}]. This default behavior may change in future versions.

  • method (ome_zarr.scale.Methods, optional) – Downsampling method to use. Default: Methods.NEAREST (recommended for labels). See also ome_zarr.scale.Methods for available methods.

  • fmt (ome_zarr.format.Format, optional) – The format of the ome_zarr data which should be used. Defaults to the most current.

  • axes (list of str or list of dicts, optional) – The names of the axes, e.g. [“t”, “c”, “z”, “y”, “x”]. Ignored for versions 0.1 and 0.2. Required for version 0.3 or greater.

  • coordinate_transformations (list of list of dict, optional) – For each resolution, a list of transformation dicts (not validated). Each list of dicts is added to each dataset in order.

  • storage_options (dict or list of dict, optional) –

    Options to be passed on to the storage backend. A list must match the number of datasets in a multiresolution pyramid. Allows different chunk sizes for each level. Regarding the key, value pairs in the dictionar(y)(ies), these depend both on the zarr_format used for writing and the dask version being used. For dask version <=2025.11.0, please refer to https://zarr.readthedocs.io/en/stable/api/zarr/create/#zarr.create for arguments that can be passed on. For >=2026.3.0 and up, please refer to https://zarr.readthedocs.io/en/stable/api/zarr/create/#zarr.create_array. It might be that you have to adjust the version of the docs. Note that the docs will also mention the differences of allowed arguments between zarr_format 2 and 3.

    Note: for chunks the default of auto is not allowed. This because the argument here refers to zarr chunks and autochunking here can result in different chunks then for the dask array. This can cause inconsistent overlap between dask and zarr chunks, potentially resulting in corrupted data. The default will be that if no sharding is specified, that the chunks correspond to the dask chunksize. This is also the case when chunks are provided as None and no sharding is provided.

  • label_metadata (dict, optional) – Image label metadata. See write_label_metadata() for details.

  • compute (bool, optional) – If True, compute immediately; otherwise, return a list of dask.delayed.Delayed objects.

  • **metadata (dict) – Additional metadata to store.

Returns:

Empty list if compute is True, otherwise a list of dask.delayed.Delayed objects representing the value to be computed by dask.

Return type:

list

Notes

The scaler argument is deprecated and will be removed in a future version. Use scale_factors and method for all new code. Labels downsampling should avoid interpolation; nearest-neighbor is recommended.

ome_zarr.writer.write_multiscale(pyramid: list[Array] | list[ndarray], group: Group, fmt: Format | None = None, axes: str | list[str] | list[dict[str, str]] | None = None, coordinate_transformations: list[list[dict[str, Any]]] | None = None, storage_options: dict[str, Any] | list[dict[str, Any]] | None = None, name: str | None = None, compute: bool | None = True, **metadata: str | dict[str, Any] | list[dict[str, Any]]) → list[source]

Write a pyramid with multiscale metadata to disk.

Parameters:

  • pyramid (list of numpy.ndarray or dask.array.Array) – The image data to save. Largest level first. All image arrays MUST be up to 5-dimensional with dimensions ordered (t, c, z, y, x)

  • group (zarr.Group) – The group within the zarr store to store the data in

  • chunks (int or tuple of ints, optional) –

    The size of the saved chunks to store the image.

    Deprecated since version 0.4.0: This argument is deprecated and will be removed in a future version. Use storage_options instead.

  • fmt (ome_zarr.format.Format, optional) – The format of the ome_zarr data which should be used. Defaults to the most current.

  • axes (str list of str or list of dict, optional) – List of axes dicts, or names. Not needed for v0.1 or v0.2 or if 2D. Otherwise this must be provided

  • coordinate_transformations (2Dlist of dict, optional) – List of transformations for each path. Each list of dicts are added to each datasets in order and must include a ‘scale’ transform.

  • storage_options (dict or list of dict, optional) –

    Options to be passed on to the storage backend. A list would need to match the number of datasets in a multiresolution pyramid. One can provide different chunk size and / or shards for each level of a pyramid using this option. Regarding the key, value pairs in the dictionar(y)(ies), these depend both on the zarr_format used for writing and the dask version being used. For dask version <=2025.11.0, please refer to https://zarr.readthedocs.io/en/stable/api/zarr/create/#zarr.create for arguments that can be passed on. For >=2026.3.0 and up, please refer to https://zarr.readthedocs.io/en/stable/api/zarr/create/#zarr.create_array. It might be that you have to adjust the version of the docs. Note that the docs will also mention the differences of allowed arguments between zarr_format 2 and 3.

    Note: for chunks the default of auto is not allowed. This because the argument here refers to zarr chunks and autochunking here can result in different chunks then for the dask array. This can cause inconsistent overlap between dask and zarr chunks, potentially resulting in corrupted data. The default will be that if no sharding is specified, that the chunks correspond to the dask chunksize. This is also the case when chunks are provided as None and no sharding is provided.

  • compute – If true compute immediately otherwise a list of dask.delayed.Delayed is returned.

Returns:

Empty list if the compute flag is True, otherwise it returns a list of dask.delayed.Delayed representing the value to be computed by dask.

ome_zarr.writer.write_multiscale_labels(pyramid: list, group: Group | str, name: str, fmt: Format | None = None, axes: str | list[str] | list[dict[str, str]] | None = None, coordinate_transformations: list[list[dict[str, Any]]] | None = None, storage_options: dict[str, Any] | list[dict[str, Any]] | None = None, label_metadata: dict[str, Any] | None = None, compute: bool | None = True, **metadata: dict[str, Any]) → list[source]

Write pyramidal image labels to disk.

Including the multiscales and image-label metadata. Creates the label data in the sub-group “labels/{name}”

Parameters:

  • pyramid (list of numpy.ndarray) – the image label data to save. Largest level first All image arrays MUST be up to 5-dimensional with dimensions ordered (t, c, z, y, x)

  • group (zarr.Group) – The zarr group or path to write the metadata in.

  • name (str, optional) – The name of this labels data.

  • fmt (ome_zarr.format.Format, optional) – The format of the ome_zarr data which should be used. Defaults to the most current.

  • axes (list of str or list of dicts, optional) – The names of the axes. e.g. [“t”, “c”, “z”, “y”, “x”]. Ignored for versions 0.1 and 0.2. Required for version 0.3 or greater.

  • coordinate_transformations (list of dict) – For each resolution, we have a List of transformation Dicts (not validated). Each list of dicts are added to each datasets in order.

  • storage_options (dict or list of dict, optional) –

    Options to be passed on to the storage backend. A list would need to match the number of datasets in a multiresolution pyramid. One can provide different chunk size for each level of a pyramid using this option. Regarding the key, value pairs in the dictionar(y)(ies), these depend both on the zarr_format used for writing and the dask version being used. For dask version <=2025.11.0, please refer to https://zarr.readthedocs.io/en/stable/api/zarr/create/#zarr.create for arguments that can be passed on. For >=2026.3.0 and up, please refer to https://zarr.readthedocs.io/en/stable/api/zarr/create/#zarr.create_array. It might be that you have to adjust the version of the docs. Note that the docs will also mention the differences of allowed arguments between zarr_format 2 and 3.

    Note: for chunks the default of auto is not allowed. This because the argument here refers to zarr chunks and autochunking here can result in different chunks then for the dask array. This can cause inconsistent overlap between dask and zarr chunks, potentially resulting in corrupted data. The default will be that if no sharding is specified, that the chunks correspond to the dask chunksize. This is also the case when chunks are provided as None and no sharding is provided.

  • label_metadata (dict, optional) – Image label metadata. See write_label_metadata() for details

  • compute – If true compute immediately otherwise a list of dask.delayed.Delayed is returned.

Returns:

Empty list if the compute flag is True, otherwise it returns a list of dask.delayed.Delayed representing the value to be computed by dask.

ome_zarr.writer.write_multiscales_metadata(group: Group | str, datasets: list[dict], fmt: Format | None = None, axes: str | list[str] | list[dict[str, str]] | None = None, name: str | None = None, **metadata: str | dict[str, Any] | list[dict[str, Any]]) → None[source]

Write the multiscales metadata in the group.

Parameters:

  • group (zarr.Group) – The zarr group or path.

  • datasets (list of dicts) – The list of datasets (dicts) for this multiscale image. Each dict must include ‘path’ and a ‘coordinateTransformations’ list for version 0.4 or later that must include a ‘scale’ transform.

  • fmt (ome_zarr.format.Format, optional) – The format of the ome_zarr data which should be used. Defaults to the most current.

  • axes (list of str or list of dicts, optional) – The names of the axes. e.g. [“t”, “c”, “z”, “y”, “x”]. Ignored for versions 0.1 and 0.2. Required for version 0.3 or greater.

ome_zarr.writer.write_plate_metadata(group: Group | str, rows: list[str], columns: list[str], wells: list[str | dict], fmt: Format | None = None, acquisitions: list[dict] | None = None, field_count: int | None = None, name: str | None = None) → None[source]

Write the plate metadata in the group.

Parameters:

  • group (zarr.Group) – The group or path to write the metadata in.

  • rows (list of str) – The list of names for the plate rows.

  • columns (list of str) – The list of names for the plate columns.

  • wells (list of str or dict) – The list of paths for the well groups.

  • fmt (ome_zarr.format.Format, optional) – The format of the ome_zarr data which should be used. Defaults to the most current.

  • acquisitions (list of dict, optional) – A list of the various plate acquisitions.

  • name (str, optional) – The plate name.

  • field_count (int, optional) – The maximum number of fields per view across wells.

ome_zarr.writer.write_well_metadata(group: Group | str, images: list[str | dict], fmt: Format | None = None) → None[source]

Write the well metadata in the group.

Parameters:

  • group (zarr.Group) – The zarr group or path to write the metadata in.

  • images (list of dict) – The list of dictionaries for all fields of views.

  • fmt (ome_zarr.format.Format, optional) – The format of the ome_zarr data which should be used. Defaults to the most current.