OME-Zarr Python Library

Common errors

• AttributeError: module 'zarr' has no attribute 'group'

  cause This error typically indicates an outdated `zarr` library version where `zarr.group` might not be exposed at the top level, or an attempt to use `zarr.group()` in a context where `zarr.open_group()` is expected for an existing store.
  fix Ensure your `zarr` library is up-to-date (`pip install --upgrade zarr`). When opening an existing Zarr store or group, prefer `zarr.open_group(store)` over `zarr.group(store)`.

• ome_zarr.exceptions.UnsupportedOMEZarrVersionError: The OME-Zarr version '0.1' is not supported for writing.

  cause Attempting to create or update an OME-Zarr store to an older specification version (v0.1, v0.2, v0.3) that is no longer supported for writing by `ome-zarr-py` v0.15.0 and later.
  fix Adjust your workflow to write OME-Zarr v0.4 or v0.5. The library will automatically default to v0.5 for new writes. If you need to produce older versions, you'd need an older `ome-zarr-py` installation.

• ValueError: image axes must be 't', 'c', 'z', 'y', 'x' or a subset thereof.

  cause The `axes` parameter provided to `write_image` or `write_multiscale` contains invalid characters or does not match the dimensionality of the image data.
  fix Verify that your `axes` list exclusively uses the standard OME-Zarr axis identifiers ('t', 'c', 'z', 'y', 'x') and that the number of axes matches the number of dimensions in your input NumPy array.

Warnings

• breaking Writing OME-Zarr versions v0.1, v0.2, and v0.3 was deprecated in v0.15.0 and is no longer supported for new writes.
  Fix: Ensure your workflow targets OME-Zarr v0.4 or v0.5 for writing. The library defaults to writing v0.5. If older versions are strictly required, use an `ome-zarr-py` version prior to 0.15.0 or convert externally.
• deprecated The `ome_zarr.scale.Scaler` class was deprecated in v0.14.0.
  Fix: Instead of `Scaler()`, use the `ome_zarr.scale.scale_pyramid` function directly for generating multiscale data. For example, `scale_pyramid(data, chunks, max_layer=max_layer, method=method)`.
• gotcha The default OME-Zarr specification version for writing changed to v0.5 with `ome-zarr-py` v0.12.0.
  Fix: While reading is largely backward-compatible, new OME-Zarr stores created will conform to v0.5. Be mindful of this when interoperating with tools that strictly expect an older version. Check the `ome-zarr` metadata within the Zarr store for the exact version being used.
• gotcha When reading or modifying existing Zarr groups, it is best practice to use `zarr.open_group()` instead of `zarr.group()`.
  Fix: For opening an existing Zarr group, always use `zarr.open_group(store_path)` or `zarr.open_group(store)`. Use `zarr.group(store, overwrite=True)` primarily for creating a new root group.
• gotcha The `axes` parameter for `write_image` and `write_multiscale` is critical and must accurately reflect the input array's dimensions using OME-Zarr standard axis identifiers.
  Fix: Always explicitly define the `axes` parameter (e.g., `['t', 'c', 'z', 'y', 'x']` or a subset) to match your input array's dimensionality. Incorrect `axes` will lead to malformed OME-Zarr metadata or errors during writing.

Install

• pip install ome-zarr Install stable version

Imports

• parse_url

  from ome_zarr.io import parse_url

• Writer

  from ome_zarr.io import Writer

• Reader

  from ome_zarr.reader import Reader

• write_image

  from ome_zarr.writer import write_image

• write_multiscale

  from ome_zarr.writer import write_multiscale

• scale_pyramid
  wrong:

  from ome_zarr.scale import Scaler

  correct:

  from ome_zarr.scale import scale_pyramid

  `Scaler` class was deprecated in v0.14.0, use `scale_pyramid` function directly.

Quickstart

This quickstart demonstrates how to create a dummy 5D NumPy array, write it to a local OME-Zarr store using `ome_zarr.writer.write_image`, and then read the data and its associated OME metadata back using `ome_zarr.reader.Reader`. It highlights the use of `parse_url` for store creation and the importance of specifying `axes` during writing.

import numpy as np
import zarr
import os
import shutil
from ome_zarr.io import parse_url
from ome_zarr.writer import write_image
from ome_zarr.reader import Reader

# Define a path for the OME-Zarr store
store_path = 'my_ome_zarr_image.zarr'

# Clean up previous store if it exists for a fresh run
if os.path.exists(store_path):
    shutil.rmtree(store_path)

# 1. Create a dummy numpy array (e.g., a 5D image: T, C, Z, Y, X)
# OME-Zarr typically uses this dimension order or a subset.
# Here: 1 Time point, 2 Channels, 3 Z-slices, 64 Y, 64 X
data = np.zeros((1, 2, 3, 64, 64), dtype=np.uint16)
data[0, 0, 1, 10:20, 10:20] = 100 # Channel 0, Z-slice 1
data[0, 1, 2, 30:40, 30:40] = 200 # Channel 1, Z-slice 2

# 2. Write the numpy array to an OME-Zarr store
# `parse_url` creates an FSSpec store object.
# `zarr.group` creates the root Zarr group, overwriting if it exists.
storage = parse_url(store_path, mode='w').store
root_group = zarr.group(storage, overwrite=True)

# `write_image` handles the OME-Zarr metadata and array layout.
write_image(
    image=data,
    group=root_group,
    axes=['t', 'c', 'z', 'y', 'x'], # Specify axes order, crucial for OME-Zarr
    chunks=(1, 1, 1, 32, 32) # Optional: define Zarr chunking
)

print(f"OME-Zarr image written to: {store_path}")

# 3. Read the OME-Zarr image
reader = Reader(parse_url(store_path))

# Get the list of nodes (images) in the Zarr store. Typically one at the root.
nodes = list(reader())[0] 

# Access image data for the highest resolution (level 0)
image_data_level_0 = nodes.data[0]

# Access OME metadata (a dictionary parsed from the OME-XML JSON)
ome_metadata = nodes.metadata

print(f"Successfully read OME-Zarr image from: {store_path}")
print(f"Shape of data (level 0): {image_data_level_0.shape}")
print(f"OME metadata keys: {ome_metadata.keys()}")

# Clean up the created Zarr store (optional but good practice for examples)
shutil.rmtree(store_path)
print(f"Cleaned up: {store_path}")