Quickstart¶

Install ngio and open your first OME-Zarr container.

In a few lines of Python you can open an OME-Zarr store, see what is inside it, and reach the images, labels and tables it contains.

Installation¶

To install ngio, use whichever package manager you already work with — it is published on PyPI and conda-forge, and can also be installed from source.

ngio requires Python >=3.11

pipuvpiximamba/condaSource

The recommended way to install ngio is from PyPI using pip:

pip install ngio

Inside a uv project:

uv add ngio

Or into an existing environment:

uv pip install ngio

pixi add ngio          # from conda-forge
pixi add --pypi ngio   # from PyPI

Alternatively, you can install ngio using mamba:

mamba install -c conda-forge ngio

or conda:

conda install -c conda-forge ngio

Clone the repository:

git clone https://github.com/BioVisionCenter/ngio.git
cd ngio

Install the package:
```
pip install .
```

Troubleshooting¶

Please report installation problems by opening an issue on the ngio GitHub repository.

Set up test data¶

Download a sample OME-Zarr dataset to work with.

from pathlib import Path

from ngio.utils import download_ome_zarr_dataset

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

Open an OME-Zarr image¶

Open an OME-Zarr file and inspect its contents.

from ngio import open_ome_zarr_container

ome_zarr_container = open_ome_zarr_container(image_path)
print(ome_zarr_container)

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

The pixels are one call away — here is the DAPI channel of that container, read from a lower pyramid level:

What is the OME-Zarr container?¶

The OME-Zarr container is the core of ngio and the entry point to working with OME-Zarr images. It provides high-level access to the image metadata, images, labels, and tables. The next section goes into more detail: inspecting and editing metadata, opening remote stores, and deriving new images and labels.

What is the OME-Zarr container not?¶

The OME-Zarr container does not give you access to the image data directly. For that, use the Image, Label, and Table objects.

Next steps¶

OME-Zarr containers — inspect and modify metadata, and create new images and labels.
Images and labels — read and write pixel data.
Tables — ROIs, features and measurements stored alongside the image.
Masked images and labels — work object-by-object using a segmentation.
HCS plates — scale up from a single image to a whole plate.

For worked end-to-end examples, see the tutorials:

Image processing — apply a processing step across an image.
Image segmentation — create new labels from images.
Feature extraction — measure objects and store the results.
HCS exploration — navigate high-content screening data.