Skip to content

ome-zarr-models

A Python package for loading and validating OME-Zarr data.

The core of this package is a set of classes for representing different OME-Zarr groups:

OME-Zarr 0.5 OME-Zarr 0.4
HCS HCS
Image Image
Labels Labels
ImageLabel ImageLabel
Well Well
BioFormats2Raw BioFormats2Raw

Each class has

  • a .from_zarr() method to read and validate groups
  • easy access to all the OME-Zarr metadata
  • a .to_zarr() method to write out metadata to Zarr groups.

Installing

pip install ome-zarr-models

or

conda install -c conda-forge ome-zarr-models

Getting started

Design

This package has been designed with the following guiding principles:

  • Strict adherence to the OME-Zarr specification, with the goal of being a reference implementation.
  • A usable set of Python classes for reading, writing, and interacting with OME-Zarr metadata.
  • The ability to work with multiple versions of the OME-Zarr spec at the same time.

Array reading and writing operations are out of scope, although the classes defined here make it easy to read array data from OME-Zarr groups.

Getting help

Developers of this package are active on the Zulip chat channel, and happy to help. Issues can also be opened on the GitHub issue tracker.

zarr-python support

Versions 0.1.x of ome-zarr-models support zarr-python version 2 and OME-Zarr 0.4, and support will remain until the beginning of 2026. Versions 1.x of ome-zarr-models require zarr-python version 3, and support versions of OME-Zarr >= 0.4.

Known issues

  • Because of the way this package is structured, it can't currently distinguish between values that are present but set to null in saved metadata, and fields that are not present.
  • We do not currently validate bioformats2raw metadata This is because it is transitional, and we have decided to put time into implementing other parts of the specification. We would welcome a pull request to add this functionality though!

OME-Zarr 0.5

  • Since the first release of the OME-Zarr version 0.5 specification ( commit 8a0f886), the specification has been edited without the version number in OME-Zarr datasets being changed. As an implementation we have no way of knowing which version of the specification data that contains version "0.5" was written to, so we have chosen to validate against the original release of OME-Zarr 0.5 ( commit 8a0f886). This means we do not:
  • Validate "omero" metadata.
  • For labels, the OME-Zarr specification says "Intermediate groups between "labels" and the images within it are allowed, but these MUST NOT contain metadata.". Because it is not clear what "metadata" means in this sentence, we do not validate this part of the specification.

Versioning

ome-zarr-models has a major.minor versioning scheme where:

  • The major version is incremented when support for a new version of the OME-Zarr specification is added, or a breaking change is made to the package.
  • The minor version is incremented for any other changes (e.g., documentation improvements, bug fixes, new features)

Minor versions are released often with new improvements and bugfixes.

Roadmap

  • Support for open OME-Zarr RFCs.
  • Emitting warnings when data violates "SHOULD" statements in the specification.

Is something missing from this list? Or do you want to help implement our roadmap? See the contributing guide!

Governance

Core maintainers

Core maintainers are the decision makers for the project, making decisions in consultation and consensus with the wider developer and user community. They are also responsible for making releases of ome-zarr-models. These are initially the founders of the project, and others can join by invitation after several sustained contributions to the project. Core maintainers are expected to be active on maintaining the project, and should step down being core developers after a substantial period of inactivity. For an up to date list, see the "ome-zarr-models maintainers" team on GitHub.

Core developers

Core developers have commit rights to the project, and are encouraged and trusted to use these to review and merge pull requests. Anyone who has made a single contribution to the project will be invited to be a core developer. For an up to date list, see the "ome-zarr-models developers" team on GitHub.

Reviewing and merging code

Code must be submitted via a pull request (PR), and any core developer (including the author of the PR) can merge the pull request using their judgment on whether it is ready to be merged or not. Core developers are trusted to ask for review from other core developers on their own PRs when necessary.