Using Zarr for images – The OME-ZARR standard

We can use the Zarr file format for storing image files such as for any other NumPy array. In this post we additionally explore the NGFF (next-generation file format) OME-ZARR standard for storing images with Zarr.

Let’s first prepare an example image by loading the cells3d image from the scikit-image package:

import numpy as np
from skimage import data, exposure
import plotly
import plotly.express as px
import plotly.io as pio
pio.renderers.default = "browser"

# load 4D image (3D + 2 channels) from the skimage samples:
array_3D = data.cells3d()

# select the nuclei channel and refine the image depth:
array_3D    = array_3D[22:54,1,:,:]
image_shape = array_3D.shape
print(image_shape)

# define a function for rescaling the intensity of each 
# layer to enhance the visibility:
def enhance(image):
    vmin, vmax = np.percentile(image, q=(0.5, 99.5))
    image = exposure.rescale_intensity(image, in_range=(vmin, vmax), 
                                       out_range=np.float32 )
    return image

# plot with plotly into the default browser:
fig = px.imshow(enhance(array_3D), animation_frame=0, 
                binary_string=True, binary_format='jpg')
plotly.io.show(fig)

Storing images using default Zarr methods

We can store that image like any other NumPy array as a Zarr file to the disk using default Zarr i/o-syntax:

import zarr

# write the image as a Zarr array to disk:
chunks      = (1, image_shape[1], image_shape[2])
zarr_out_3D = zarr.open('zarr_3D_image.zarr', mode='w', 
                        shape=array_3D.shape,
                        chunks=chunks, 
                        dtype=array_3D.dtype)
zarr_out_3D[:] = array_3D

# reopen/read the Zarr array:
zarr_in_3D  = zarr.open('zarr_3D_image.zarr')
fig = px.imshow(enhance(zarr_in_3D[:]), animation_frame=0, 
                binary_string=True, binary_format='jpg')
plotly.io.show(fig)

The generated plot is identical to the one shown above. For the remainder of this post I will not show that plot and refer to the one above.

The OME-NGFF/OME-ZARR standard

In 2020/2021, the Open Microscopy Environmentꜛ (OME) has proposedꜛ the next-generation file format (NGFF) specificationsꜛ (GitHubꜛ) for storing multi-resolution bioimaging data in the cloud. The OME defines this OME-NGFF called standard based on the Zarr file format, which provides the necessary support for storing and accessing arrays from distributed cloud storages. I will therefore refer to that standard as OME-ZARR for the remainder of this post.

Even though being proposed for the usage of images in the cloud, we can use it as a general standard for storing images as Zarr arrays (like the OME-TIFFꜛ specifications for storing TIFF files). The advantages of using such a standard are:

• standardization of the metadata (regarding both format and name definition, according the OME-XML structured annotations specificationsꜛ),
• standardization of the structure within the Zarr file (i.e., how the image is stored within the Zarr fileꜛ), and
• standardization of the Zarr-store format (Zarr storage specificationsꜛ).

This standardization enables developers to easily provide an API, that works for all OME-ZARR files in a unified manner. We can write image analysis pipelines and don’t have to care, how the hierarchy within a Zarr files might be organized – we can expect it to always be arranged and accessible in the same way. The standardization of the metadata also sets a clear frame for how to store and name image attributes such as the microscope metadata, image resolution or the channel specifications.

OME-ZARR with Python

In Python, the OME-ZARR standard is provided by the ome-zarr-pyꜛ package. Let’s take a look, how to store and read our example image from above accordingly:

from ome_zarr.io import parse_url
from ome_zarr.writer import write_image
from ome_zarr.reader import Reader
store = parse_url("zarr_3D_image.ome.zarr", mode="w").store
root  = zarr.group(store=store, overwrite=True)
write_image(image=array_3D, group=root, axes="zyx",
            storage_options=dict(chunks=chunks))

The parse_url(...).storeꜛ function creates a Zarr directory store in a specific format ("FormatV04") and with a specific dimension separator ("/"). This is equivalent to:

store = zarr.storage.FSStore("zarr_3D_image.ome.zarr", mode="w", 
                             format="FormatV04",
                             dimension_separator="/")
root  = zarr.group(store=store, overwrite=True)
write_image(image=array_3D, group=root, axes="zyx",
            storage_options=dict(chunks=chunks, overwrite=True))

The write_image()ꜛ function saves the image to the created group (root) into the Zarr file by creating a pyramid of resolution levels (the default is five levels), where each image layer is down sampled by a factor of 2 with each level. This is why the stored image array actually consists of five sub-arrays/-folders within the Zarr file:

print(root.info)
print(root.tree())

  Name        : /
  Type        : zarr.hierarchy.Group
  Read-only   : False
  Store type  : zarr.storage.FSStore
  No. members : 5
  No. arrays  : 5
  No. groups  : 0
  Arrays      : 0, 1, 2, 3, 4
  
  /
   ├── 0 (32, 256, 256) uint16
   ├── 1 (32, 128, 128) uint16
   ├── 2 (32, 64, 64) uint16
   ├── 3 (32, 32, 32) uint16
   └── 4 (32, 16, 16) uint16

With the knowledge about the internal file structure, we can read the OME-ZARR file by using default Zarr i/o-syntax:

zarr_in_3D  = zarr.open("zarr_3D_image.ome.zarr")
fig = px.imshow(enhance(zarr_in_3D["0"][:]), animation_frame=0, 
                binary_string=True, binary_format='jpg')
plotly.io.show(fig)

The ome-zarr-py packages also provides its own reader function, Reader()ꜛ:

# read the OME-ZARR file with the ome_zarr io-method:
reader = Reader(parse_url("zarr_3D_image.ome.zarr"))
# nodes may include images, labels etc.:
nodes = list(reader())
# first node will be the image pixel data at full resolution:
image_node = nodes[0]
zarr_in_3D = image_node.data
fig = px.imshow(zarr_in_3D[0][:], animation_frame=0,binary_string=True, binary_format='jpg')
plotly.io.show(fig)

Adding metadata

We can add OME-XMLꜛ-like metadata to the stored image array by assigning Zarr attributes. We follow the example from the ome-zarr-py documentation websiteꜛ and add some omero-styleꜛ rendering settings:

root.attrs["omero"] = {
    "channels": [{
        "color": "00FFFF",
        "window": {"start": 0, "end": 20},
        "label": "nuclei",
        "active": True,
    }]
}

Storing multiple images into one OME-ZARR file

We can also add more than one image to an OME-ZARR file by adding groups to the Zarr store:

store = zarr.storage.FSStore("zarr_3D_image_groups.ome.zarr", 
                             mode="w", 
                             format="FormatV04",
                             dimension_separator="/")
root  = zarr.group(store=store, overwrite=True)
root_sub_1 = root.create_group("sub_array_1", overwrite=True)
root_sub_2 = root.create_group("sub_array_2", overwrite=True)
root_sub_3 = root.create_group("sub_array_2/sub_sub_array_1", overwrite=True)
write_image(image=array_3D, group=root, axes="zyx",
            storage_options=dict(chunks=chunks, overwrite=True))
write_image(image=array_3D, group=root_sub_1, axes="zyx",
            storage_options=dict(chunks=chunks, overwrite=True))
write_image(image=array_3D, group=root_sub_2, axes="zyx",
            storage_options=dict(chunks=chunks, overwrite=True))
write_image(image=array_3D, group=root_sub_3, axes="zyx",
            storage_options=dict(chunks=chunks, overwrite=True))
print(root.tree())

  /
   ├── 0 (32, 256, 256) uint16
   ├── 1 (32, 128, 128) uint16
   ├── 2 (32, 64, 64) uint16
   ├── 3 (32, 32, 32) uint16
   ├── 4 (32, 16, 16) uint16
   ├── sub_array_1
   │   ├── 0 (32, 256, 256) uint16
   │   ├── 1 (32, 128, 128) uint16
   │   ├── 2 (32, 64, 64) uint16
   │   ├── 3 (32, 32, 32) uint16
   │   └── 4 (32, 16, 16) uint16
   └── sub_array_2
       ├── 0 (32, 256, 256) uint16
       ├── 1 (32, 128, 128) uint16
       ├── 2 (32, 64, 64) uint16
       ├── 3 (32, 32, 32) uint16
       ├── 4 (32, 16, 16) uint16
       └── sub_sub_array_1
           ├── 0 (32, 256, 256) uint16
           ├── 1 (32, 128, 128) uint16
           ├── 2 (32, 64, 64) uint16
           ├── 3 (32, 32, 32) uint16
           └── 4 (32, 16, 16) uint16

OME-ZARR arrays stored into groups can be accessed like default OME-ZARR arrays:

zarr_in_3D  = zarr.open("zarr_3D_image_groups.ome.zarr")
fig = px.imshow(enhance(zarr_in_3D["sub_array_1"]["0"][:]), animation_frame=0,
                binary_string=True, binary_format='jpg')
plotly.io.show(fig)

Adding labels

It is also possible to add labels directly to the OME-ZARR store. Let’s calculate some labels for our example image:

from skimage import segmentation as seg
from scipy import ndimage as ndi
from skimage.feature import peak_local_max
from skimage import filters
from scipy import ndimage
import matplotlib.pyplot as plt

def plot_projection(array3D, title="dummy 3D stack", projection_method="mean", axis=2):
    """
    Plot function: plots a 2D average intensity z-projection of an input 3D array.
    """
    fig = plt.figure(2, figsize=(5, 5))
    plt.clf()
    if projection_method =="mean":
        plt.imshow(array3D.mean(axis=axis))
        plt.title(title + "\naverage intensity z-projection", fontweight="bold")
    elif projection_method=="max":
        plt.imshow(array3D.max(axis=axis))
        plt.title(title+"\nmaximum intensity z-projection", fontweight="bold")
    plt.xlabel("x-axis", fontweight="bold")
    plt.ylabel("y-axis", fontweight="bold")
    plt.colorbar()
    plt.tight_layout()
    plt.show()
    plt.savefig(title+" projected.png", dpi=120)

# pre-filter the image stack:
array_3D_filtered = ndimage.median_filter(array_3D, size=7)
array_3D_filtered = filters.gaussian(array_3D_filtered, sigma=2)

# threshold:
threshold = filters.threshold_otsu(array_3D_filtered)
array_3D_threshold = array_3D_filtered > threshold

# segment array_3D_threshold via the watershed method:
distance     = ndi.distance_transform_edt(array_3D_threshold.astype("bool"))
max_coords   = peak_local_max(distance, min_distance=10,labels=array_3D_threshold.astype("bool"))
local_maxima = np.zeros_like(array_3D_threshold, dtype=bool)
local_maxima[tuple(max_coords.T)] = True
markers = ndi.label(local_maxima)[0]
labels  = seg.watershed(-distance, markers, mask=array_3D_threshold.astype("bool"))

# some control plots:
plot_projection(labels, title="dummy 3D stack labels", projection_method="max", axis=0)
plot_projection(enhance(array_3D), title="dummy 3D stack", projection_method="mean", axis=0)

Now we write the labels to the OME-ZARR directory:

# create the OME-ZARR store:
store = parse_url("zarr_3D_image.ome.zarr", mode="w").store
root  = zarr.group(store=store, overwrite=True)
write_image(image=array_3D, group=root, axes="zyx",
            storage_options=dict(chunks=chunks))

# write the labels to "/labels":
labels_grp = root.create_group("labels", overwrite=True)
label_name = "watershed"
labels_grp.attrs["labels"] = [label_name]
label_grp = labels_grp.create_group(label_name)
# the 'image-label' attribute is required to be recognized as label:
label_grp.attrs["image-label"] = { }
write_image(labels, label_grp, axes="zyx")

# control plot:
zarr_in_3D  = zarr.open("zarr_3D_image.ome.zarr")
plot_projection(zarr_in_3D["labels/watershed"]["0"][:],
                title="dummy 3D stack read labels",
                projection_method="max", axis=0)

OME-ZARR in Napari

Napariꜛ is able to read OME-ZARR files via the napari-ome-zarrꜛ plugin:

Image taken from https://www.napari-hub.org/plugins/napari-ome-zarr.

With that plugin, we can simply drag and drop our example OME-ZARR folder “zarr_3D_image.ome.zarr” into the Napari main window, and the image and the associated labels are read accordingly:

We can also pass the image to Napari via Python by opening the OME-ZARR file (or any other Zarr file) and handing over the desired Zarr array to Napari:

zarr_in_3D  = zarr.open("zarr_3D_image.ome.zarr")
viewer = napari.view_image(enhance(zarr_in_3D["0"][:]))
labels_layer = viewer.add_labels(zarr_in_3D["labels/watershed"]["0"][:],
                                 name='watershed')

By now, Napari is not the only image viewer that provides support for OME-ZARR files. There is for example Vizarrꜛ, and in my next post I will show, how to read OME-ZARR files in Fiji.

Accessing OME-ZARR images stored in the cloud

Finally, let’s see how we can access OME-ZARR images that are stored in the cloud:

path   = "https://uk1s3.embassy.ebi.ac.uk/idr/zarr/v0.1/6001246.zarr/"
store  = parse_url(path, mode="r").store
reader = Reader(parse_url(path))
nodes  = list(reader())
image_node = nodes[0]
read_data  = image_node.data
viewer = napari.view_image(read_data[0], channel_axis=0)

You can find more publicly available OME-ZARR samples hereꜛ and hereꜛ.

The Python code used in this post is also available in this GitHub repositoryꜛ.