ngio 0.4.0a4__tar.gz → 0.4.1__tar.gz

{ngio-0.4.0a4 → ngio-0.4.1}/.github/workflows/build_docs.yml

@@ -22,7 +22,7 @@ jobs:
         with:
           fetch-depth: 0
       - name: 🐍 Set up Python
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v6
         with:
           python-version: "3.13"
           cache-dependency-path: "pyproject.toml"

{ngio-0.4.0a4 → ngio-0.4.1}/.github/workflows/ci.yml

@@ -40,7 +40,7 @@ jobs:
       - uses: actions/checkout@v5
 
       - name: 🐍 Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v6
         with:
           python-version: ${{ matrix.python-version }}
           cache-dependency-path: "pyproject.toml"
@@ -103,7 +103,7 @@ jobs:
           fetch-depth: 0
 
       - name: 🐍 Set up Python
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v6
         with:
           python-version: "3.x"
 

{ngio-0.4.0a4 → ngio-0.4.1}/CHANGELOG.md

@@ -1,13 +1,22 @@
 # Changelog
 
-## [v0.4.0a1]
+## [v0.4.1]
+
+### Bug Fixes
+- Fix bug in zoom transform when input axes contain unknown axes (e.g. virtual axes). Now unknown axes are treated as virtual axes and set to 1 in the target shape.
+
+## [v0.4.0]
 
 ### Features
 
-- add support for time in rois and roi-tables
+- Add Iterators for image processing pipelines
+- Add support for time in rois and roi-tables
 - Building masking roi tables expanded to time series data
-- add experimental support for Iterators
-- add support for rescaling on-the-fly masks for masked images
+- Add zoom transformation
+- Add support for rescaling on-the-fly masks for masked images
+- Big refactor of the io pipeline to support iterators and lazy loading
+- Add support for customize dimension separators and compression codecs
+- Simplify AxesHandler and Dataset Classes
 
 ### API Changes
 
@@ -19,15 +28,12 @@
 - Image like objects now have a more clean API to load data. Instead of `get_array` and `set_array`, they now use `get_as_numpy`, and `get_as_dask` for delayed arrays.
 - Also for `get_roi` now specific methods are available. For ROI objects, the `get_roi_as_numpy`, and `get_roi_as_dask` methods.
 - Table ops moved to `ngio.images`
-- Make `label` an explicit attribute in `Roi` objects.
+- int `label` as an explicit attribute in `Roi` objects (previously only in stored in name and relying on convention)
+- Slight changes to `Image` and `Label` objects. Some minor attributes have been renamed for consistency.
 
 ### Table specs
 
-- add `t_second` and `len_t_second` to ROI tables and masking ROI tables
-
-### Bug Fixes
-
-- improve type consistency and remove non-necessary "type: ignore"
+- Add `t_second` and `len_t_second` to ROI tables and masking ROI tables
 
 ## [v0.3.5]
 

{ngio-0.4.0a4 → ngio-0.4.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ngio
-Version: 0.4.0a4
+Version: 0.4.1
 Summary: Next Generation file format IO
 Project-URL: homepage, https://github.com/BioVisionCenter/ngio
 Project-URL: repository, https://github.com/BioVisionCenter/ngio
@@ -28,7 +28,6 @@ Requires-Dist: pooch
 Requires-Dist: pyarrow
 Requires-Dist: pydantic
 Requires-Dist: requests
-Requires-Dist: xarray
 Requires-Dist: zarr<3
 Provides-Extra: dev
 Requires-Dist: devtools; extra == 'dev'
@@ -83,20 +82,22 @@ Ngio's mission is to streamline working with OME-Zarr files by providing a simpl
 
 ## Key Features
 
-### 📊 Simple Object-Based API
+### 🔍 Simple Object-Based API
 
 - Easily open, explore, and manipulate OME-Zarr images and HCS plates
 - Create and derive new images and labels with minimal boilerplate code
 
-### 🔍 Rich Tables and Regions of Interest (ROI) Support
+### 📊 Rich Tables and Regions of Interest (ROI) Support
 
+- Tight integration with [tabular data](https://biovisioncenter.github.io/ngio/stable/table_specs/overview/)
 - Extract and analyze specific regions of interest
-- Tight integration with [Tabular Data](https://BioVisionCenter.github.io/ngio/stable/table_specs/overview/)
+- Store measurements and other metadata in the OME-Zarr container
+- Extensible & modular allowing users to define custom table schemas and on disk serialization
 
-### 🔄 Scalable Data Processing (Coming Soon)
+### 🔄 Scalable Data Processing
 
-- Powerful iterators for processing data at scale
-- Efficient memory management for large datasets
+- Powerful iterators for building scalable and generalizable image processing pipelines
+- Extensible mapping mechanism for custom parallelization strategies
 
 ## Installation
 
@@ -114,23 +115,22 @@ Currently, ngio only supports OME-Zarr v0.4. Support for version 0.5 and higher
 
 ## Development Status
 
-!!! warning
-    Ngio is under active development and is not yet stable. The API is subject to change, and bugs and breaking changes are expected.
-    We follow [Semantic Versioning](https://semver.org/). Which means for 0.x releases potentially breaking changes can be introduced in minor releases.
+Ngio is under active development and is not yet stable. The API is subject to change, and bugs and breaking changes are expected.
+We follow [Semantic Versioning](https://semver.org/). Which means for 0.x releases potentially breaking changes can be introduced in minor releases.
 
 ### Available Features
 
 - ✅ OME-Zarr metadata handling and validation
 - ✅ Image and label access across pyramid levels
 - ✅ ROI and table support
+- ✅ Image processing iterators
 - ✅ Streaming from remote sources
 - ✅ Documentation and examples
 
 ### Upcoming Features
 
-- Advanced image processing iterators
-- Parallel processing capabilities
-- Support for OME-Zarr v0.5 and Zarr v3
+- Support for OME-Zarr v0.5 and Zarr v3 (via `zarr-python` v3)
+- Enhanced performance optimizations (parallel iterators, optimized io strategies)
 
 ## Contributors
 

{ngio-0.4.0a4 → ngio-0.4.1}/README.md

@@ -16,20 +16,22 @@ Ngio's mission is to streamline working with OME-Zarr files by providing a simpl
 
 ## Key Features
 
-### 📊 Simple Object-Based API
+### 🔍 Simple Object-Based API
 
 - Easily open, explore, and manipulate OME-Zarr images and HCS plates
 - Create and derive new images and labels with minimal boilerplate code
 
-### 🔍 Rich Tables and Regions of Interest (ROI) Support
+### 📊 Rich Tables and Regions of Interest (ROI) Support
 
+- Tight integration with [tabular data](https://biovisioncenter.github.io/ngio/stable/table_specs/overview/)
 - Extract and analyze specific regions of interest
-- Tight integration with [Tabular Data](https://BioVisionCenter.github.io/ngio/stable/table_specs/overview/)
+- Store measurements and other metadata in the OME-Zarr container
+- Extensible & modular allowing users to define custom table schemas and on disk serialization
 
-### 🔄 Scalable Data Processing (Coming Soon)
+### 🔄 Scalable Data Processing
 
-- Powerful iterators for processing data at scale
-- Efficient memory management for large datasets
+- Powerful iterators for building scalable and generalizable image processing pipelines
+- Extensible mapping mechanism for custom parallelization strategies
 
 ## Installation
 
@@ -47,23 +49,22 @@ Currently, ngio only supports OME-Zarr v0.4. Support for version 0.5 and higher
 
 ## Development Status
 
-!!! warning
-    Ngio is under active development and is not yet stable. The API is subject to change, and bugs and breaking changes are expected.
-    We follow [Semantic Versioning](https://semver.org/). Which means for 0.x releases potentially breaking changes can be introduced in minor releases.
+Ngio is under active development and is not yet stable. The API is subject to change, and bugs and breaking changes are expected.
+We follow [Semantic Versioning](https://semver.org/). Which means for 0.x releases potentially breaking changes can be introduced in minor releases.
 
 ### Available Features
 
 - ✅ OME-Zarr metadata handling and validation
 - ✅ Image and label access across pyramid levels
 - ✅ ROI and table support
+- ✅ Image processing iterators
 - ✅ Streaming from remote sources
 - ✅ Documentation and examples
 
 ### Upcoming Features
 
-- Advanced image processing iterators
-- Parallel processing capabilities
-- Support for OME-Zarr v0.5 and Zarr v3
+- Support for OME-Zarr v0.5 and Zarr v3 (via `zarr-python` v3)
+- Enhanced performance optimizations (parallel iterators, optimized io strategies)
 
 ## Contributors
 

ngio-0.4.1/docs/api/iterators.md

@@ -0,0 +1,17 @@
+# Iterators API Reference
+
+## ImageProcessingIterator
+
+::: ngio.experimental.iterators.ImageProcessingIterator
+
+## SegmentationIterator
+
+::: ngio.experimental.iterators.SegmentationIterator
+
+## MaskedSegmentationIterator
+
+::: ngio.experimental.iterators.MaskedSegmentationIterator
+
+## FeatureExtractorIterator
+     
+::: ngio.experimental.iterators.FeatureExtractorIterator

ngio-0.4.1/docs/api/ngio/io_pipes.md

@@ -0,0 +1,3 @@
+# ngio.io_pipes API documentation
+
+::: ngio.io_pipes

ngio-0.4.1/docs/api/ngio/iterators.md

@@ -0,0 +1,3 @@
+# ngio.iterators API documentation
+
+::: ngio.experimental.iterators

ngio-0.4.1/docs/api/ngio/transforms.md

@@ -0,0 +1,3 @@
+# ngio.transforms API documentation
+
+::: ngio.transforms

{ngio-0.4.0a4 → ngio-0.4.1}/docs/getting_started/2_images.md

@@ -96,7 +96,7 @@ Once you have the `Image` object, you can access the image data as a:
 The `get_as_*` can also be used to slice the image data, and query specific axes in specific orders:
 
 ```pycon exec="true" source="console" session="get_started"
->>> image_slice = image.get_as_numpy(c=0, x=slice(0, 128), axes_order=["t", "z", "y", "x", "c"]) # Get a specific channel and axes order
+>>> image_slice = image.get_as_numpy(channel_selection="DAPI", x=slice(0, 128), axes_order=["t", "z", "y", "x", "c"]) # Get a specific channel and axes order
 >>> image_slice.shape
 >>> print(image_slice.shape) # markdown-exec: hide
 ```
@@ -113,14 +113,14 @@ A minimal example of how to use the `get_array` and `set_array` methods:
 
 ```python exec="true" source="material-block" session="get_started"
 # Get the image data as a numpy array
-data = image.get_as_numpy(c=0, x=slice(0, 128), y=slice(0, 128), axes_order=["z", "y", "x", "c"])
+data = image.get_as_numpy(channel_selection="DAPI", x=slice(0, 128), y=slice(0, 128), axes_order=["z", "y", "x", "c"])
 
 # Modify the image data
 some_function = lambda x: x # markdown-exec: hide
 data = some_function(data)
 
 # Set the modified image data
-image.set_array(data, c=0, x=slice(0, 128), y=slice(0, 128), axes_order=["z", "y", "x", "c"])
+image.set_array(data, channel_selection="DAPI", x=slice(0, 128), y=slice(0, 128), axes_order=["z", "y", "x", "c"])
 image.consolidate() # Consolidate the changes to all resolution levels, see below for more details
 ```
 
@@ -131,6 +131,17 @@ image.consolidate() # Consolidate the changes to all resolution levels, see belo
     ```
     This will write the changes to the OME-Zarr file at all resolution levels.
 
+### World coordinates slicing
+
+To read or write a specific region of the image defined in world coordinates, you can use the `Roi` object.
+
+```pycon exec="true" source="console" session="get_started"
+>>> from ngio import Roi
+>>> roi = Roi(x=34.1, y=10, x_length=321.6, y_length=330) # Define a ROI in world coordinates
+>>> image.get_roi_as_numpy(roi) # Get the image data in the ROI as a numpy array
+>>> print(image.get_roi_as_numpy(roi).shape) # markdown-exec: hide
+```
+
 ## Labels
 
 `Labels` represent segmentation masks that identify objects in the image. In ngio `Labels` are similar to `Images` and can

ngio-0.4.1/docs/getting_started/6_iterators.md

@@ -0,0 +1,14 @@
+# 6. Iterators
+
+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).
+
+Moreover, when working with OME-Zarr Images it is often useful to set specific broadcasting rules for the iteration, for example to iterate over all z-planes or iterate over all timepoints.
+
+Ngio provides a set of `Iterator` classes that can be used for this purpose. We provide iterators four basic iterators: 
+
+* The `SegmentationIterator` is designed to build segmentation pipelines, where an input image is processed to produce a segmentation mask. An example use case on how to use the `SegmentationIterator` can be found in the [Image Segmentation Tutorial](../tutorials/image_segmentation.ipynb).
+* 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. An example use case on how to use the `MaskedSegmentationIterator` can be found in the [Image Segmentation Tutorial](../tutorials/image_segmentation.ipynb).
+* The `ImageProcessingIterator` is designed to build image processing pipelines, where an input image is processed to produce a new image. An example use case on how to use the `ImageProcessingIterator` can be found in the [Image Processing Tutorial](../tutorials/image_processing.ipynb).
+* The `FeatureExtractionIterator` is read-only iterator designed to iterate over pairs of images and labels to extract features from the image based on the labels. An example use case on how to use the `FeatureExtractionIterator` can be found in the [Feature Extraction Tutorial](../tutorials/feature_extraction.ipynb).
+
+A set of more complete example can be found in the [Fractal Tasks Template](https://github.com/fractal-analytics-platform/fractal-tasks-template).

{ngio-0.4.0a4 → ngio-0.4.1}/docs/index.md

@@ -8,20 +8,22 @@ Ngio's mission is to streamline working with OME-Zarr files by providing a simpl
 
 ## Key Features
 
-### 📊 Simple Object-Based API
+### 🔍 Simple Object-Based API
 
 - Easily open, explore, and manipulate OME-Zarr images and HCS plates
 - Create and derive new images and labels with minimal boilerplate code
 
-### 🔍 Rich Tables and Regions of Interest (ROI) Support
+### 📊 Rich Tables and Regions of Interest (ROI) Support
 
+- Tight integration with [tabular data](https://biovisioncenter.github.io/ngio/stable/table_specs/overview/)
 - Extract and analyze specific regions of interest
-- Tight integration with [Fractal's table framework](https://BioVisionCenter.github.io/fractal-tasks-core/tables/)
+- Store measurements and other metadata in the OME-Zarr container
+- Extensible & modular allowing users to define custom table schemas and on disk serialization
 
-### 🔄 Scalable Data Processing (Coming Soon)
+### 🔄 Scalable Data Processing
 
-- Powerful iterators for processing data at scale
-- Efficient memory management for large datasets
+- Powerful iterators for building scalable and generalizable image processing pipelines
+- Extensible mapping mechanism for custom parallelization strategies
 
 ## Getting Started
 
@@ -43,14 +45,14 @@ Currently, ngio only supports OME-Zarr v0.4. Support for version 0.5 and higher
 - ✅ OME-Zarr metadata handling and validation
 - ✅ Image and label access across pyramid levels
 - ✅ ROI and table support
+- ✅ Image processing iterators
 - ✅ Streaming from remote sources
 - ✅ Documentation and examples
 
 ### Upcoming Features
 
-- Advanced image processing iterators
-- Parallel processing capabilities
-- Support for OME-Zarr v0.5 and Zarr v3
+- Support for OME-Zarr v0.5 and Zarr v3 (via `zarr-python` v3)
+- Enhanced performance optimizations (parallel iterators, optimized io strategies)
 
 ## Contributors
 

{ngio-0.4.0a4 → ngio-0.4.1}/docs/tutorials/create_ome_zarr.ipynb

@@ -52,7 +52,7 @@
    "id": "3",
    "metadata": {},
    "source": [
-    "## Adding Rois to OME-Zarr\n",
+    "## Adding a ROI table to an OME-Zarr image\n",
     "\n",
     "Often, is useful to add ROIs to OME-Zarr images to be able to retrieve them later.  \n",
     "This can be done using the `ngio` library as follows."

ngio-0.4.1/docs/tutorials/feature_extraction.ipynb

@@ -0,0 +1,168 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Feature Extraction\n",
+    "\n",
+    "This sections will cover how to extract regionprops features from an image using `ngio`, `skimage`. Moreover we will also write the features to a table in the ome-zarr container.\n",
+    "\n",
+    "# Step 1: Open the OME-Zarr Container"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import numpy as np\n",
+    "import pandas as pd\n",
+    "from skimage import measure\n",
+    "\n",
+    "\n",
+    "def extract_features(image: np.ndarray, label: np.ndarray) -> pd.DataFrame:\n",
+    "    \"\"\"Basic feature extraction using skimage.measure.regionprops_table.\"\"\"\n",
+    "    label = label.squeeze(-1)  # Remove the channel axis if present\n",
+    "    roi_feat_table = measure.regionprops_table(\n",
+    "        label_image=label,\n",
+    "        intensity_image=image,\n",
+    "        properties=[\n",
+    "            \"label\",\n",
+    "            \"area\",\n",
+    "            \"mean_intensity\",\n",
+    "            \"max_intensity\",\n",
+    "            \"min_intensity\",\n",
+    "        ],\n",
+    "    )\n",
+    "    return pd.DataFrame(roi_feat_table)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from pathlib import Path\n",
+    "\n",
+    "from ngio import open_ome_zarr_container\n",
+    "from ngio.utils import download_ome_zarr_dataset\n",
+    "\n",
+    "# Download the dataset\n",
+    "download_dir = Path(\".\").absolute().parent.parent / \"data\"\n",
+    "hcs_path = download_ome_zarr_dataset(\"CardiomyocyteTinyMip\", download_dir=download_dir)\n",
+    "image_path = hcs_path / \"B\" / \"03\" / \"0\"\n",
+    "\n",
+    "# Open the ome-zarr container\n",
+    "ome_zarr = open_ome_zarr_container(image_path)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Step 2: Setup the inputs"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from ngio.transforms import ZoomTransform\n",
+    "\n",
+    "# First we will need the image object and the FOVs table\n",
+    "image = ome_zarr.get_image()\n",
+    "\n",
+    "# Get the nuclei label\n",
+    "nuclei = ome_zarr.get_label(\"nuclei\")\n",
+    "\n",
+    "# In this example we the image is available at an higher resolution than the nuclei\n",
+    "print(f\"Image dimensions: {image.dimensions}, pixel size: {image.pixel_size}\")\n",
+    "print(f\"Nuclei dimensions: {nuclei.dimensions}, pixel size: {nuclei.pixel_size}\")\n",
+    "\n",
+    "# We need to setup a transform to resample the nuclei to the image resolution\n",
+    "zoom_transform = ZoomTransform(\n",
+    "    input_image=nuclei,\n",
+    "    target_image=image,\n",
+    "    order=\"nearest\",  # Nearest neighbor interpolation for labels\n",
+    ")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Step 3: Use the FeatureExtractorIterator to create a feature table"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from ngio.experimental.iterators import FeatureExtractorIterator\n",
+    "from ngio.tables import FeatureTable\n",
+    "\n",
+    "iterator = FeatureExtractorIterator(\n",
+    "    input_image=image,\n",
+    "    input_label=nuclei,\n",
+    "    label_transforms=[zoom_transform],\n",
+    "    axes_order=[\"y\", \"x\", \"c\"],\n",
+    ")\n",
+    "\n",
+    "feat_table = []\n",
+    "for image_data, label_data, roi in iterator.iter_as_numpy():\n",
+    "    print(f\"Processing ROI: {roi}\")\n",
+    "    roi_feat_table = extract_features(image=image_data, label=label_data)\n",
+    "    feat_table.append(roi_feat_table)\n",
+    "\n",
+    "# Concatenate all the dataframes into a single one\n",
+    "feat_table = pd.concat(feat_table)\n",
+    "feat_table = FeatureTable(table_data=feat_table, reference_label=\"nuclei\")\n",
+    "ome_zarr.add_table(\"nuclei_regionprops\", feat_table)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Sanity Check: Read the Table back"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "ome_zarr.get_table(\"nuclei_regionprops\").lazy_frame.collect()"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "dev",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.11.13"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 2
+}

{ngio-0.4.0a4 → ngio-0.4.1}/docs/tutorials/hcs_exploration.ipynb

@@ -102,16 +102,6 @@
     "print(test_plate)\n",
     "print(f\"Rows: {test_plate.rows}, Columns: {test_plate.columns}\")"
    ]
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": []
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": []
   }
  ],
  "metadata": {

{ngio-0.4.0a4 → ngio-0.4.1}/docs/tutorials/image_processing.ipynb

@@ -11,7 +11,7 @@
     "For this example we will apply gaussian blur to an image.\n",
     "\n",
     "\n",
-    "# Step 1: Setup\n",
+    "## Step 1: Setup\n",
     "\n",
     "We will first create a simple function to apply gaussian blur to an image. This function will take an image and a sigma value as input and return the blurred image."
    ]
@@ -98,7 +98,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "# Step 4: Apply the gaussian blur and consolidate the processed image"
+    "## Step 4: Apply the gaussian blur and consolidate the processed image"
    ]
   },
   {
@@ -130,7 +130,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "# Plot the results\n",
+    "### Plot the results\n",
     "\n",
     "Finally, we can visualize the original and blurred images using `matplotlib`."
    ]
@@ -164,7 +164,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "## Out of memory processing\n",
+    "## Step 5: Out of memory processing\n",
     "\n",
     "Sometimes we want to apply some simple processing to larger than memory images. In this case, we can use the `dask` library to process the image in chunks. In `ngio` we can simply query the data as a `dask` array and apply the desired processing function to it."
    ]
@@ -180,6 +180,9 @@
     "\n",
     "def dask_gaussian_blur(image: da.Array, sigma: float) -> da.Array:\n",
     "    \"\"\"Apply gaussian blur to a dask array.\"\"\"\n",
+    "    # This will itroduce some edge artifacts at chunk boundaries\n",
+    "    # In a real application, consider using map_overlap to mitigate this\n",
+    "    # With appropriate depth based on sigma\n",
     "    return da.map_blocks(gaussian_blur, image, dtype=image.dtype, sigma=sigma)\n",
     "\n",
     "\n",
@@ -191,7 +194,53 @@
   {
    "cell_type": "markdown",
    "metadata": {},
-   "source": []
+   "source": [
+    "## Step 6. Image Processing Iterators\n",
+    "\n",
+    "`ngio` provides an alternative way to process large images using iterators. This API is not meant to replace `dask` but to provide a simple way to iterate over arbitrary regions, moreover it provides a simple way to implement default broadcasting behaviors."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from ngio.experimental.iterators import ImageProcessingIterator\n",
+    "\n",
+    "iterator = ImageProcessingIterator(\n",
+    "    input_image=image,\n",
+    "    output_image=blurred_image,\n",
+    "    axes_order=[\"c\", \"z\", \"y\", \"x\"],\n",
+    ")\n",
+    "\n",
+    "# After initializing the iterator, the iterator will have created\n",
+    "# will iterate over the entire image.\n",
+    "print(f\"Iterator after initialization: {iterator}\")\n",
+    "\n",
+    "# Iterate over an arbitrary region of interest table\n",
+    "# We can use the product method that performs a cartesian product\n",
+    "# between the iterator and the table.\n",
+    "table = ome_zarr.get_roi_table(\"FOV_ROI_table\")\n",
+    "iterator = iterator.product(table)\n",
+    "print(f\"Iterator after product with table: {iterator}\")\n",
+    "\n",
+    "# We can explicitly set a broadcasting behavior\n",
+    "# For example we can iterate over all zyx planes, and broadcast all the other\n",
+    "# spatial dimensions\n",
+    "iterator = iterator.by_zyx()\n",
+    "\n",
+    "# Finally (if needed) we can check if the regions are not-overlapping\n",
+    "iterator.require_no_regions_overlap()\n",
+    "# We can also check if the regions lay on non-overlapping chunks\n",
+    "iterator.require_no_chunks_overlap()\n",
+    "\n",
+    "# Now we can map the gaussian blur function to the iterator\n",
+    "iterator.map_as_numpy(lambda x: gaussian_blur(x, sigma=sigma))\n",
+    "\n",
+    "# No need to consolidate, the iterator takes care of that\n",
+    "# after all the regions have been processed"
+   ]
   }
  ],
  "metadata": {