Skip to content

1. OME-Zarr Container

Let's see how to open and explore an OME-Zarr image using ngio:

from pathlib import Path
from ngio import open_ome_zarr_container
from ngio.utils import download_ome_zarr_dataset

# Download a sample dataset
download_dir = Path("./data")
hcs_path = download_ome_zarr_dataset("CardiomyocyteSmallMip", download_dir=download_dir)
image_path = hcs_path / "B" / "03" / "0"

# Open the OME-Zarr container
ome_zarr_container = open_ome_zarr_container(image_path)

The OME-Zarr Container in is your entry point to working with OME-Zarr images. It provides high-level access to the image metadata, images, labels, and tables.

>>> ome_zarr_container
OmeZarrContainer(levels=5, #labels=4, #tables=7)

The OME-Zarr Container will be the starting point for all your image processing tasks.

Main concepts

What is the OME-Zarr container?

The OME-Zarr Container in ngio is your entry point to working with OME-Zarr images.

It provides:

  • OME-Zarr overview: get an overview of the OME-Zarr file, including the number of image levels, list of labels, and tables available.
  • Image access: get access to the images at different resolution levels and pixel sizes.
  • Label management: check which labels are available, access them, and create new labels.
  • Table management: check which tables are available, access them, and create new tables.
  • Derive new OME-Zarr images: create new images based on the original one, with the same or similar metadata.

What is the OME-Zarr container not?

The OME-Zarr Container object does not allow the user to interact with the image data directly. For that, we need to use the Image, Label, and Table objects.

OME-Zarr overview

Examples of the OME-Zarr metadata access:

Show the number of resolution levels: 

>>> ome_zarr_container.levels # Show the number of resolution levels
5

Show the paths to all available resolution levels: 

>>> ome_zarr_container.level_paths # Show the paths to all available images
['0', '1', '2', '3', '4']

Show if the image is 2D or 3D: 

>>> ome_zarr_container.is_3d # Get if the image is 3D
False
or if the image is a time series: 
>>> ome_zarr_container.is_time_series # Get if the image is a time series
False


>>> metadata = ome_zarr_container.meta
NgioImageMeta(name=None, datasets=['0', '1', '2', '3', '4'], axes=('c', 'z', 'y', 'x'))
The metadata object contains all the information about the image, for example, the channel labels: 
>>> metadata.channels_meta.channel_labels
['DAPI', 'nanog', 'Lamin B1']

Modifying metadata

ngio provides methods to modify the image metadata, such as channel labels, colors, display windows, axes names, and units.

Channel metadata

You can update channel labels, colors, and display windows:

Update the labels (names) of the channels: 

>>> ome_zarr_container.set_channel_labels(["DAPI", "GFP", "RFP"])

Update the display colors of the channels (hex format): 

>>> ome_zarr_container.set_channel_colors(["0000FF", "00FF00", "FF0000"])

Update the display windows (start/end values) for each channel: 

>>> ome_zarr_container.set_channel_windows([(0, 255), (0, 1000), (0, 500)])

Automatically compute display windows based on data percentiles: 

>>> ome_zarr_container.set_channel_windows_with_percentiles(percentiles=(0.1, 99.9))

Axes metadata

You can update the axes names and units:

Rename the axes in the metadata: 

>>> ome_zarr_container.set_axes_names(["t", "c", "z", "y", "x"])

Set the space and time units: 

>>> ome_zarr_container.set_axes_units(space_unit="micrometer", time_unit="second")

Image name

You can set the name of the image in the metadata:

>>> ome_zarr_container.set_name("My Processed Image")

Note

The set_name method only updates the metadata. It does not change the group name or file paths.

Accessing images / labels / tables

To access images, labels, and tables, you can use the get_image, get_label, and get_table methods of the OME-Zarr Container object.

A variety of examples and additional information can be found in the Images and Labels, and Tables sections.

Creating derived images

When processing an image, you might want to create a new image with the same metadata:

# Create a new image based on the original
new_image = ome_zarr_container.derive_image("data/new_ome.zarr", overwrite=True)

This will create a new OME-Zarr image with the same metadata as the original image. But you can also create a new image with slightly different metadata, for example, with a different shape:

# Create a new image with a different shape
new_image = ome_zarr_container.derive_image(
    "data/new_ome.zarr", 
    overwrite=True, 
    shape=(16, 128, 128), 
    pixelsize=0.65, 
    z_spacing=1.0
)

Creating new images

You can create OME-Zarr images from an existing numpy array using the create_ome_zarr_from_array function.

import numpy as np
from ngio import create_ome_zarr_from_array

# Create a random 3D array
x = np.random.randint(0, 255, (16, 128, 128), dtype=np.uint8)

# Save as OME-Zarr
new_ome_zarr_image = create_ome_zarr_from_array(
    store="random_ome.zarr", 
    array=x, 
    pixelsize=0.65, 
    z_spacing=1.0
)

Alternatively, if you wanto to create an a empty OME-Zarr image, you can use the create_empty_ome_zarr function:

from ngio import create_empty_ome_zarr
# Create an empty OME-Zarr image
new_ome_zarr_image = create_empty_ome_zarr(
    store="empty_ome.zarr", 
    shape=(16, 128, 128), 
    pixelsize=0.65, 
    z_spacing=1.0
)

This will create an empty OME-Zarr image with the specified shape and pixel sizes.

Opening remote OME-Zarr containers

You can use ngio to open remote OME-Zarr containers. For publicly available OME-Zarr containers, you can just use the open_ome_zarr_container function with a URL.

For example, to open a remote OME-Zarr container hosted on a github repository:

from ngio.utils import fractal_fsspec_store

url = (
    "https://raw.githubusercontent.com/"
    "fractal-analytics-platform/fractal-ome-zarr-examples/"
    "refs/heads/main/v04/"
    "20200812-CardiomyocyteDifferentiation14-Cycle1_B_03_mip.zarr/"
)

store = fractal_fsspec_store(url=url)
ome_zarr_container = open_ome_zarr_container(store)

For fractal users, the fractal_fsspec_store function can be used to open private OME-Zarr containers. In this case we need to provide a fractal_token to authenticate the user.

from ngio.utils import fractal_fsspec_store

store = fractal_fsspec_store(url="https://fractal_url...", fractal_token="**your_secret_token**")
ome_zarr_container = open_ome_zarr_container(store)