Add image class

[jo-mueller]

Hi @will-moore ,

this is an implementation of my idea for a class-based, user-facing API to writing and reading.

Key features

• Implemented classes: Implements the OMEZarrImage, OMEZarrMultiscale and OMEZarrLabels (similar to the implementation over at ngff-zarr), that serve as primary entrypoints to the writing. OMEZarrImage accepts the data to be written as an array and coerces it to dask internally. It requires the axes (i.e., "tczyx") to be passed at instantiation. It also accepts kwargs for pixel sizes (scale), axes units (axes_units), display settings, channel names and the name of the image (name) which are later serialized in the ome-zarr metadata.
  The OMEZarrMultiscale and OMEZarrLabels then construct a pyramid using the already existing methods (_build_pyramid) that were implemented in deprecate scaler class #516, using different defaults for downsampling (resize and nearest).
• Ome-zarr-models-py: Usage of ome-zarr-models-py for the internal construction of the corresponding Metadata class from there for simpke serialization and de-serialization in the write/read process. Primarily, the coordinate transformation classes and the Multiscales metadata classes are used.
  Importantly, all metadata is internally coerced to ozmp.v05.Multiscales. Only on writing the metadata class is converted to whatever ome-zarr version is desired.
• Writing: Writing happens through the OMEZarrMultiscale.to_ome_zarr() method. This method makes use of the already existing writing API from Streamline writing #531 (_write_pyramid_to_zarr). It then converts the metadata to the chosen version and uses pydantic's object.model_dump() to create the metadata dictionary. Importantly, the version conversion is only implemented in implement version converters ome-zarr-models/ome-zarr-models-py#398, so this is currently blocked by that.
• Reading: The implemented OMEZarrMultiscale/OMEZarrLabels class also has an attached from_ome_zarr(...) classmethod. The argument is simply the path/group of the ome-zarr image. The function then reads the metadata and the multiscales as dask arrays and returns an instance of OMEZarrMultiscale. The version is automatically detected and again coerced to ozmp.v05.Multiscales internally.
• Labels: Writing labels can be done by converting them to instances of OMEZarrMultiscale and passing them as a single image or as a dict(str, OMEZarrLabels) to the to_ome_zarr writer function. The labels attribute is also automatically populated when an image is read using the .from_ome_zarr function: The reader then searches for all labels that exist under the labels zarr group and adds them as a dict[str, OMEZarrLabels] to the attribute. One can the add more label images to the attribute, call to_ome_zarr(..., overwrite=False), and only the added label images will be written and the corresponding metadata will be updated
• Backwards compatibility: The existing entrypoints to writing (write_image and write_labels now use the OMEZarrImage,OMEZarrMultiscale and OMEZarrLabels classes under the hood. Since the scale transformations are now entirely calculated under the hood, this means that the coordinateTransformations argument is now essentially deprecated, which I think is good since it was unvalidated anyway. The raised warning message reflects this.
• Inheritance: The introduce OMEZarrMultiscale and NgffLabels share quite a bit of functionality regarding reading, writing and pyramid generation, so they both derive from a common ancestral class OMEZarrMultiscaleBase, which handles that and offers hook functions for the child classes' respective functionality:
  • _parse_additional_metadata: Called on end of __init__, can be used to parse more stuff (i.e., omero or iamge-labels metadata.
  • _write_additional_meta_data: Called on end of to_ome_zarr() - derived classes can use it to validate and dump more metadata to a store that's only relevant to the respective implementation of OMEZarrMultiscaleBase
  • _read_additional_metadata: Called on end of read_ome_zarr(): Can be used to populate additional (meta)data fields from store, i.e., the .labels field, etc.

All in all, I think especially the to_ome_zarr and from_ome_zarr methods are super convenient. I have written a follow-up implementation of the scene metadata from 0.6 and making use of the same API there makes a lot of sense. We could think of similar entrypoints to writing HCS layouts.

TODOs:

• Document
• Support omero metadata and image-label metadata
• Increase coverage
• Merge Use markdown and Jupyter notebooks in doc pages #548
• Merge BREAKING CHANGE: Deprecate writing v01, v02 and v03 #557
• Merge feat: add scale argument to entrypoints #553

[codecov]

Codecov Report

❌ Patch coverage is 92.45742% with 31 lines in your changes missing coverage. Please review.
✅ Project coverage is 86.65%. Comparing base (66478bb) to head (d9bad78).
⚠️ Report is 2 commits behind head on master.

Files with missing lines	Patch %	Lines
ome_zarr/classes/image.py	91.98%	29 Missing ⚠️
ome_zarr/utils.py	96.77%	1 Missing ⚠️
ome_zarr/writer.py	92.85%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master     #515      +/-   ##
==========================================
+ Coverage   85.42%   86.65%   +1.23%     
==========================================
  Files          14       16       +2     
  Lines        1921     2316     +395     
==========================================
+ Hits         1641     2007     +366     
- Misses        280      309      +29     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[will-moore]

@jo-mueller Thanks for that - This looks like a nice approach to separate the metadata creation and manipulation from the writing to zarr.

Comparing APIs:

• This PR:

i = Image(data = my_array, dims = ["c", "z", "y", "x"], scale_factors = [2, 4], scale = [1, 0.5, 0.3, 0.3], axes_units = [None, "micrometer", "micrometer", "micrometer"], name="my image"]
i.to_ome_zarr("my_image.zarr", version="0.4")

• ngff-zarr

image = nz.to_ngff_image(data, dims=['y', 'x'], scale={'y': 1.0, 'x': 1.0}, translation={'y': 0.0, 'x': 0.0})
multiscales = nz.to_multiscales(image, scale_factors=[2,4], chunks=64)
nz.to_ngff_zarr('lightsheet.ome.zarr', multiscales, chunks_per_shard=2, version="0.4")

Various comments, questions. I realise some of this is just not implemented yet... And I haven't tried the code (which might answer some of these)...

• Spec(ABC) class isn't used/needed
• to_zarr() should take an existing root OR string
• No code for reading ome-zarrs yet
• The current Scaler doesn't downsample in z in most cases (existing issue). Might be best to calculate the scales for each Dataset from the shape of each new_image
• axes_units isn't used, nor is labels
• metadata writing to_zarr is missing currently
• "version" is ignored. How do we handle versions / converting e.g. read v0.4 and write v0.5?
• No translation added. See code to add this at 492
• da.to_zarr() needs to specify dimension_names for zarr v3 arrays, e.g. fixed in fix recursion error if __store.fs.protocol is a tuple #511
• Where do we specify chunks, shards, compressors and other options to pass down to zarr-python?
• support for omero metadata? Yaozarrs has _omero but it's not exposed very much
• I think we could drop support for writing v0.1, v0.2 and v0.3, but what about reading them?
• Yaozarrs is slightly less verbose than ome-zarr-models-py, but generally similar
• If your data is a 5D array shape = (50, 3, 100, 1024, 1024) and your dims/scale were 4D, e.g. dims = ["c", "z", "y", "x"] would you get any validation errors?

[jo-mueller]

@will-moore thanks for the breakdown. I was aware of some of these points (not all) but decided to send it anyway to not go too far in the wrong direction in case there were strong objections to the approach.

Actually, what you wrote is an excellent to-do list :)

[jo-mueller]

@will-moore I think this is taking a bit more shape towards how I'd expect it. But before this can continue, I think there is value in discussing first the current duplicity in functionality between these two functions:

• write_image: calls _build_pyramid under the hood and uses _write_dask_image to serialize the data and metadata to disk
• write_multiscales: Requires up-front call to _build_pyramid and then serializes data to disk, uses write_multiscales_metadata to write metadata to disc

There's a lot of overlap between these two functions which I think can be condensed so we'd have a single place where

• metadata is created
• format parsing is happening

Anyway, I just tried the Image.to_ome_zarr with a large image (3 x 15k x 15k) and I'm getting very decent writing speeds!

[imagesc-bot]

This pull request has been mentioned on Image.sc Forum. There might be relevant details there:

https://forum.image.sc/t/separate-tiles-to-ome-zarr/109071/55

[will-moore]

@jo-mueller Could you update the description to reflect where this is heading now?

Are we planning to keep all the existing write methods (any API changes)?

[will-moore]

It would be nice to support writing of "omero" metadata. I think that's covered by ome-zarr-models-py too.
Could be a follow-up PR?

[jo-mueller]

@will-moore

Could be a follow-up PR?

Agree.

where this is heading now?
Are we planning to keep all the existing write methods (any API changes)?

THAT is a good question I'm not entirely sure of myself. I guess if we want to go this way further, we would ultimately deprecate write_image and its siblings over the class-based API. As an intermediate step, we could make these functions do something like this under the hood:

def write_image(args, kwargs):
  image = NGffImage(args, kwargs)
  multiscales = NgffMultiscales(image, ....)
  multiscales.to_ome_zarr(....)

which would at least reduce the amount of code to maintain and make sure that everything we do on the class-based API side is covered well by the already existing tests.

What's missing here

The only thing that makes tests fail here currently is this one: ome-zarr-models/ome-zarr-models-py#398. Locally, all tests are passing.

Also, note that this branch has been rebased on #544, so that'll have to go in first, too.

[jo-mueller]

@will-moore to go forward with this one, my idea for a soft transition would be this:

Step 1: Refactor - I am just now trying to see if I can get the existing entrypoints (write_image, etc) to convert the passed data to instances of the introduced classes under the hood. For this, I am adding some of the relevant arguments as explicit keywords (i.e., for name, axes_units) which are passed to the NgffImage class where they are internally validated by ozmp.
This doesn't affect ongoing refactorings regarding sharding, because the central writing logic is still in the same place (_write_pyramid_to_zarr), the classes just wrap around this function.
Step 2: Expose: After #548 is merged, this would be a good opportunity to expose the classes more to the outside. Right now, I am refraining a bit from extensive documentation if there are pending changes on the structure of the docs :)

[will-moore]

from ome_zarr import NgffMultiscales
img_path = "https://uk1s3.embassy.ebi.ac.uk/idr/zarr/v0.1/1884807.zarr"
ms = NgffMultiscales.from_ome_zarr(img_path)
out_path = "test_image_class_1884807_05.zarr"
ms.to_ome_zarr(out_path, version="0.5")

This writes an invalid image because the zarr.json has datasets[0].path: "0" but the array is written to path s0.

EDIT: Also the omero metadata is not preserved into the output image

[will-moore]

img_path = "https://uk1s3.embassy.ebi.ac.uk/idr/zarr/v0.4/idr0076A/10501752.zarr"
NgffMultiscales.from_ome_zarr(img_path)

  File "/Users/wmoore/Desktop/ZARR/ome-zarr-py/ome_zarr/classes/image.py", line 547, in from_ome_zarr
    raise ValueError(f"Unsupported OME-Zarr version: {version}")
ValueError: Unsupported OME-Zarr version: 0.4.0

This image has .zattrs with an "unexpected" version:

    "_creator": {
        "name": "omero-zarr",
        "version": "0.4.0"
    },
    "multiscales": [
        { "version": "0.4"...

so the version lookup needs to be a bit more specific

[jo-mueller]

Hi @70Gage70 , thanks for the suggestion. I added a hard removal of any remaining#s in the parser function, so that one could pass the #, if one wanted. Mainly because one can then do this in an IDE (at least in VSCode):

08.06.2026_10.07.34_REC.mp4

[jo-mueller]

@pennycuda sorry for missing your comment here! We will see to have this merged this week, so to contribute it's probably easiest to check out this branch and open it as a PR to main and rebase later (won't do any force pushes here anymore)

[will-moore]

LGTM: let's get this in and then followup with any remaining issues we need...