{"id":8369,"library":"ome-zarr","title":"OME-Zarr Python Library","description":"ome-zarr is a Python library providing an implementation of images in Zarr files according to the OME-Zarr specification. It enables reading and writing bioimaging data stored in the OME-Zarr format, supporting multiscale images, metadata, and various Zarr features like chunking and compression. The current version is 0.16.0, with a release cadence that sees new features and bug fixes approximately every few months, often tied to updates in the OME-Zarr specification itself.","status":"active","version":"0.16.0","language":"en","source_language":"en","source_url":"https://github.com/ome/ome-zarr-py","tags":["image processing","ome","zarr","bioimaging","scientific data","microscopy"],"install":[{"cmd":"pip install ome-zarr","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Core Zarr array storage and manipulation.","package":"zarr","optional":false},{"reason":"Fundamental array operations for image data.","package":"numpy","optional":false},{"reason":"Compression and filter codecs for Zarr.","package":"numcodecs","optional":false},{"reason":"Parsing and validating OME metadata.","package":"ome-types","optional":false},{"reason":"For out-of-core and parallel array computations, especially with large datasets.","package":"dask","optional":true},{"reason":"For accessing various file systems (e.g., S3, Google Cloud Storage).","package":"fsspec","optional":true},{"reason":"For converting TIFF files to OME-Zarr.","package":"tifffile","optional":true}],"imports":[{"symbol":"parse_url","correct":"from ome_zarr.io import parse_url"},{"symbol":"Writer","correct":"from ome_zarr.io import Writer"},{"symbol":"Reader","correct":"from ome_zarr.reader import Reader"},{"symbol":"write_image","correct":"from ome_zarr.writer import write_image"},{"symbol":"write_multiscale","correct":"from ome_zarr.writer import write_multiscale"},{"note":"`Scaler` class was deprecated in v0.14.0, use `scale_pyramid` function directly.","wrong":"from ome_zarr.scale import Scaler","symbol":"scale_pyramid","correct":"from ome_zarr.scale import scale_pyramid"}],"quickstart":{"code":"import numpy as np\nimport zarr\nimport os\nimport shutil\nfrom ome_zarr.io import parse_url\nfrom ome_zarr.writer import write_image\nfrom ome_zarr.reader import Reader\n\n# Define a path for the OME-Zarr store\nstore_path = 'my_ome_zarr_image.zarr'\n\n# Clean up previous store if it exists for a fresh run\nif os.path.exists(store_path):\n    shutil.rmtree(store_path)\n\n# 1. Create a dummy numpy array (e.g., a 5D image: T, C, Z, Y, X)\n# OME-Zarr typically uses this dimension order or a subset.\n# Here: 1 Time point, 2 Channels, 3 Z-slices, 64 Y, 64 X\ndata = np.zeros((1, 2, 3, 64, 64), dtype=np.uint16)\ndata[0, 0, 1, 10:20, 10:20] = 100 # Channel 0, Z-slice 1\ndata[0, 1, 2, 30:40, 30:40] = 200 # Channel 1, Z-slice 2\n\n# 2. Write the numpy array to an OME-Zarr store\n# `parse_url` creates an FSSpec store object.\n# `zarr.group` creates the root Zarr group, overwriting if it exists.\nstorage = parse_url(store_path, mode='w').store\nroot_group = zarr.group(storage, overwrite=True)\n\n# `write_image` handles the OME-Zarr metadata and array layout.\nwrite_image(\n    image=data,\n    group=root_group,\n    axes=['t', 'c', 'z', 'y', 'x'], # Specify axes order, crucial for OME-Zarr\n    chunks=(1, 1, 1, 32, 32) # Optional: define Zarr chunking\n)\n\nprint(f\"OME-Zarr image written to: {store_path}\")\n\n# 3. Read the OME-Zarr image\nreader = Reader(parse_url(store_path))\n\n# Get the list of nodes (images) in the Zarr store. Typically one at the root.\nnodes = list(reader())[0] \n\n# Access image data for the highest resolution (level 0)\nimage_data_level_0 = nodes.data[0]\n\n# Access OME metadata (a dictionary parsed from the OME-XML JSON)\nome_metadata = nodes.metadata\n\nprint(f\"Successfully read OME-Zarr image from: {store_path}\")\nprint(f\"Shape of data (level 0): {image_data_level_0.shape}\")\nprint(f\"OME metadata keys: {ome_metadata.keys()}\")\n\n# Clean up the created Zarr store (optional but good practice for examples)\nshutil.rmtree(store_path)\nprint(f\"Cleaned up: {store_path}\")\n","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=0.15.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)`.","message":"The `ome_zarr.scale.Scaler` class was deprecated in v0.14.0.","severity":"deprecated","affected_versions":">=0.14.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.","message":"The default OME-Zarr specification version for writing changed to v0.5 with `ome-zarr-py` v0.12.0.","severity":"gotcha","affected_versions":">=0.12.0"},{"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.","message":"When reading or modifying existing Zarr groups, it is best practice to use `zarr.open_group()` instead of `zarr.group()`.","severity":"gotcha","affected_versions":"All versions, especially relevant with `zarr` library updates."},{"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.","message":"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.","severity":"gotcha","affected_versions":"*"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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)`.","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.","error":"AttributeError: module 'zarr' has no attribute 'group'"},{"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.","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.","error":"ome_zarr.exceptions.UnsupportedOMEZarrVersionError: The OME-Zarr version '0.1' is not supported for writing."},{"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.","cause":"The `axes` parameter provided to `write_image` or `write_multiscale` contains invalid characters or does not match the dimensionality of the image data.","error":"ValueError: image axes must be 't', 'c', 'z', 'y', 'x' or a subset thereof."}]}