Skip to content

6. Iterators

Process an image region by region without writing the loop.

When building image processing pipelines it is often useful to iterate over specific regions of the image, for example to process the image in smaller tiles or to process only specific regions of interest (ROIs). Iterators also let you set broadcasting rules for the iteration, for example to iterate over all z-planes or over all timepoints.

How an iterator walks an image A ROI table names the regions. For each region the iterator reads that part of the input, applies your function, and writes the result into the output, one region at a time. 1234 ROI TABLE INPUT YOUR FUNCTION OUTPUT region 1 region 2 region 3 … process() repeat for every region the table names

ngio provides four basic Iterator classes, all imported from ngio.iterators (or from the top-level ngio namespace):

The four iterators, by what they take and return Segmentation takes an image and returns a label. Masked segmentation takes an image and a label and returns a label. Image processing takes an image and returns an image. Feature extraction takes an image and a label and returns a table. SegmentationIterator MaskedSegmentationIterator ImageProcessingIterator FeatureExtractorIterator an image in, a new label out the same, restricted to one mask an image in, a new image out read only — measurements out image labels table
  • The SegmentationIterator is designed to build segmentation pipelines, where an input image is processed to produce a segmentation mask. For a worked example, see the image segmentation tutorial.
  • The MaskedSegmentationIterator is similar to the SegmentationIterator, but it uses a masking ROI table to restrict the segmentation to masks. This is useful when you want to segment only specific regions of the image, for example, segmenting cells only within a specific tissue region. For a worked example, see the image segmentation tutorial.
  • The ImageProcessingIterator is designed to build image processing pipelines, where an input image is processed to produce a new image. For a worked example, see the image processing tutorial.
  • The FeatureExtractorIterator is a read-only iterator designed to iterate over pairs of images and labels to extract features from the image based on the labels. For a worked example, see the feature extraction tutorial.

Building one

Every iterator is constructed from the images it reads and writes, then narrowed. A fresh iterator covers the whole image as a single region:

from pathlib import Path

from ngio import open_ome_zarr_container
from ngio.iterators import ImageProcessingIterator
from ngio.utils import download_ome_zarr_dataset

download_dir = Path("./data").absolute()
hcs_path = download_ome_zarr_dataset(
    "CardiomyocyteSmallMip", download_dir=download_dir, re_unzip=False
)
ome_zarr = open_ome_zarr_container(hcs_path / "B" / "03" / "0")
image = ome_zarr.get_image()

# A new iterator covers the whole image as a single region
iterator = ImageProcessingIterator(input_image=image, output_image=image)
print(iterator)
ImageProcessingIterator(regions=1)

product replaces that single region with the ones a ROI table names — here the microscope fields of view:

# Narrow it to the regions named by a ROI table
iterator = iterator.product(ome_zarr.get_roi_table("FOV_ROI_table"))
print(iterator)
ImageProcessingIterator(regions=4)

The regions are ordinary Roi objects, so you can inspect them before processing anything:

# The regions are plain Roi objects, so you can look before you process
for roi in iterator.rois[:2]:
    print(roi)
name='FOV_1' slices=[z: 0.0->1.0, y: 0.0->351.0, x: 0.0->416.0] label=None space='world' name='FOV_2' slices=[z: 0.0->1.0, y: 0.0->351.0, x: 416.0->832.0] label=None space='world'

From here you would call map_as_numpy or iterate with iter_as_numpy to do the work; the image processing tutorial carries this through to a written result.

More complete examples can be found in the Fractal tasks template.

Next steps