ngio 0.4.0a3__tar.gz → 0.4.0b1__tar.gz

{ngio-0.4.0a3 → ngio-0.4.0b1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ngio
-Version: 0.4.0a3
+Version: 0.4.0b1
 Summary: Next Generation file format IO
 Project-URL: homepage, https://github.com/BioVisionCenter/ngio
 Project-URL: repository, https://github.com/BioVisionCenter/ngio

ngio-0.4.0b1/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.0b1/docs/api/ngio/io_pipes.md

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

ngio-0.4.0b1/docs/api/ngio/iterators.md

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

ngio-0.4.0b1/docs/api/ngio/transforms.md

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

{ngio-0.4.0a3 → ngio-0.4.0b1}/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.0a3 → ngio-0.4.0b1}/docs/getting_started/3_tables.md

@@ -38,7 +38,7 @@ Ngio supports three types of tables: `roi_table`, `feature_table`, and `masking_
     image_data = image_3.get_array(c=0)
     image_data = np.squeeze(image_data)
     roi = roi_table.get("FOV_1")
-    roi = roi.to_roi_pixels(pixel_size=image_3.pixel_size, dimensions=image_3.dimensions)
+    roi = roi.to_roi_pixels(pixel_size=image_3.pixel_size)
     #label_3 = ome_zarr_container.get_label("nuclei", pixel_size=image_3.pixel_size)
     #label_data = label_3.get_array()
     #label_data = np.squeeze(label_data)

ngio-0.4.0b1/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.0a3 → ngio-0.4.0b1}/docs/index.md

@@ -17,11 +17,12 @@ Ngio's mission is to streamline working with OME-Zarr files by providing a simpl
 
 - Extract and analyze specific regions of interest
 - Tight integration with [Fractal's table framework](https://BioVisionCenter.github.io/fractal-tasks-core/tables/)
+- 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 +44,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.0a3 → ngio-0.4.0b1}/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.0b1/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.0a3 → ngio-0.4.0b1}/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.0a3 → ngio-0.4.0b1}/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": {

{ngio-0.4.0a3 → ngio-0.4.0b1}/docs/tutorials/image_segmentation.ipynb

@@ -76,6 +76,8 @@
    "metadata": {},
    "outputs": [],
    "source": [
+    "from ngio.experimental.iterators import SegmentationIterator\n",
+    "\n",
     "# First we will need the image object and the FOVs table\n",
     "image = ome_zarr.get_image()\n",
     "roi_table = ome_zarr.get_roi_table(\"FOV_ROI_table\")\n",
@@ -84,30 +86,36 @@
     "\n",
     "label = ome_zarr.derive_label(\"new_label\", overwrite=True)\n",
     "\n",
-    "max_label = 0  # We will use this to avoid label collisions\n",
-    "for roi in roi_table.rois():\n",
-    "    # Get the image data for the ROI\n",
-    "    image_data = image.get_roi_as_numpy(roi=roi, c=0, axes_order=[\"z\", \"y\", \"x\"])\n",
+    "# Setup the segmentation iterator\n",
+    "seg_iterator = SegmentationIterator(\n",
+    "    input_image=image,\n",
+    "    output_label=label,\n",
+    "    channel_selection=\"DAPI\",\n",
+    "    axes_order=[\"z\", \"y\", \"x\"],\n",
+    ")\n",
+    "seg_iterator = seg_iterator.product(roi_table)\n",
+    "\n",
+    "# Make sure that if other axes are present they are iterated over\n",
+    "seg_iterator = seg_iterator.by_zyx()\n",
     "\n",
+    "max_label = 0  # We will use this to avoid label collisions\n",
+    "for image_data, label_writer in seg_iterator.iter_as_numpy():\n",
     "    roi_segmentation = otsu_threshold_segmentation(\n",
     "        image_data, max_label\n",
     "    )  # Segment the image\n",
     "\n",
     "    max_label = roi_segmentation.max()  # Get the max label for the next iteration\n",
     "\n",
-    "    label.set_roi(\n",
-    "        roi=roi, patch=roi_segmentation\n",
-    "    )  # Write the segmentation to the label image"
+    "    label_writer(patch=roi_segmentation)  # Write the segmentation back to the label\n",
+    "\n",
+    "# No need to consolidate, the iterator does it automatically after the last write"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "# Step 4: Consolidate the segmentation\n",
-    "\n",
-    "The `new_label` has data only at a single resolution lebel. To consolidate the segmentation to all other levels we will \n",
-    "need to call the `consolidate` method."
+    "### Plot the segmentation"
    ]
   },
   {
@@ -116,14 +124,100 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "label.consolidate()"
+    "import matplotlib.pyplot as plt\n",
+    "import numpy as np\n",
+    "from matplotlib.colors import ListedColormap\n",
+    "\n",
+    "rand_cmap = np.random.rand(1000, 3)\n",
+    "rand_cmap[0] = 0\n",
+    "rand_cmap = ListedColormap(rand_cmap)\n",
+    "\n",
+    "fig, axs = plt.subplots(2, 1, figsize=(8, 4))\n",
+    "axs[0].set_title(\"Original image\")\n",
+    "axs[0].imshow(image.get_as_numpy(c=0, z=1, axes_order=[\"y\", \"x\"]), cmap=\"gray\")\n",
+    "axs[1].set_title(\"Final segmentation\")\n",
+    "axs[1].imshow(label.get_as_numpy(z=1, axes_order=[\"y\", \"x\"]), cmap=rand_cmap)\n",
+    "for ax in axs:\n",
+    "    ax.axis(\"off\")\n",
+    "plt.tight_layout()\n",
+    "plt.show()"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "## Plot the segmentation"
+    "## Step 4: Masked image segmentation\n",
+    "\n",
+    "In this example we will use a mask to restrict the segmentation to certain areas of the image.\n",
+    "In this case we will create a simple mask for illustration purposes, but in a real case scenario the mask could come\n",
+    "from another segmentation mask."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Create a basic mask for illustration purposes\n",
+    "mask = ome_zarr.derive_label(\"mask\", overwrite=True)\n",
+    "mask_data = mask.get_as_numpy(axes_order=[\"z\", \"y\", \"x\"])\n",
+    "mask_data[:, 200:-200, 500:2000] = 1\n",
+    "mask_data[:, 200:-200, 3000:-500] = 2\n",
+    "mask_data[:, 600:-600, 1200:-1000] = 0\n",
+    "mask_data[:, 700:-700, 1600:-1500] = 3\n",
+    "mask.set_array(mask_data, axes_order=[\"z\", \"y\", \"x\"])\n",
+    "mask.consolidate()\n",
+    "\n",
+    "fig, axs = plt.subplots(2, 1, figsize=(8, 4))\n",
+    "axs[0].set_title(\"Original image\")\n",
+    "axs[0].imshow(image.get_as_numpy(c=0, z=1, axes_order=[\"y\", \"x\"]), cmap=\"gray\")\n",
+    "axs[1].set_title(\"Mask\")\n",
+    "axs[1].imshow(mask.get_as_numpy(z=1, axes_order=[\"y\", \"x\"]), cmap=rand_cmap)\n",
+    "for ax in axs:\n",
+    "    ax.axis(\"off\")\n",
+    "plt.tight_layout()\n",
+    "plt.show()"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from ngio.experimental.iterators import MaskedSegmentationIterator\n",
+    "\n",
+    "# First we will need the masked image object\n",
+    "# (that contains the masking table information inside)\n",
+    "image = ome_zarr.get_masked_image(masking_label_name=\"mask\")\n",
+    "\n",
+    "# Second we need to derive a new label image to use as target for the segmentation\n",
+    "label = ome_zarr.derive_label(\"masked_new_label\", overwrite=True)\n",
+    "\n",
+    "# Setup the masked segmentation iterator\n",
+    "seg_iterator = MaskedSegmentationIterator(\n",
+    "    input_image=image,\n",
+    "    output_label=label,\n",
+    "    channel_selection=\"DAPI\",\n",
+    "    axes_order=[\"z\", \"y\", \"x\"],\n",
+    ")\n",
+    "\n",
+    "# Make sure that if other axes are present they are iterated over\n",
+    "seg_iterator = seg_iterator.by_zyx()\n",
+    "\n",
+    "max_label = 0  # We will use this to avoid label collisions\n",
+    "for image_data, label_writer in seg_iterator.iter_as_numpy():\n",
+    "    roi_segmentation = otsu_threshold_segmentation(\n",
+    "        image_data, max_label\n",
+    "    )  # Segment the image\n",
+    "\n",
+    "    max_label = roi_segmentation.max()  # Get the max label for the next iteration\n",
+    "\n",
+    "    label_writer(patch=roi_segmentation)  # Write the segmentation back to the label\n",
+    "\n",
+    "# No need to consolidate, the iterator does it automatically after the last write"
    ]
   },
   {
@@ -136,10 +230,6 @@
     "import numpy as np\n",
     "from matplotlib.colors import ListedColormap\n",
     "\n",
-    "rand_cmap = np.random.rand(1000, 3)\n",
-    "rand_cmap[0] = 0\n",
-    "rand_cmap = ListedColormap(rand_cmap)\n",
-    "\n",
     "fig, axs = plt.subplots(2, 1, figsize=(8, 4))\n",
     "axs[0].set_title(\"Original image\")\n",
     "axs[0].imshow(image.get_as_numpy(c=0, z=1, axes_order=[\"y\", \"x\"]), cmap=\"gray\")\n",

{ngio-0.4.0a3 → ngio-0.4.0b1}/mkdocs.yml

@@ -112,6 +112,7 @@ nav:
     - getting_started/3_tables.md
     - getting_started/4_masked_images.md
     - getting_started/5_hcs.md
+    - getting_started/6_iterators.md
 
   - Tutorials:
     - tutorials/create_ome_zarr.ipynb
@@ -136,13 +137,17 @@ nav:
     - "Images": api/images.md
     - "HCS": api/hcs.md
     - "Tables": api/tables.md
+    - "Iterators": api/iterators.md
     - "ngio":
       - "ngio": api/ngio/ngio.md
+      - "ngio.common": api/ngio/common.md
+      - "ngio.io_pipes": api/ngio/io_pipes.md
+      - "ngio.iterators": api/ngio/iterators.md
       - "ngio.images": api/ngio/images.md
       - "ngio.tables": api/ngio/tables.md
       - "ngio.hcs": api/ngio/hcs.md
+      - "ngio.transforms": api/ngio/transforms.md
       - "ngio.utils": api/ngio/utils.md
-      - "ngio.common": api/ngio/common.md
     - changelog.md
 
   - Contributing:

{ngio-0.4.0a3 → ngio-0.4.0b1}/src/ngio/__init__.py

@@ -9,7 +9,7 @@ except PackageNotFoundError:  # pragma: no cover
 __author__ = "Lorenzo Cerrone"
 __email__ = "lorenzo.cerrone@uzh.ch"
 
-from ngio.common import ArrayLike, Dimensions, Roi, RoiPixels
+from ngio.common import Dimensions, Roi, RoiPixels
 from ngio.hcs import (
     OmeZarrPlate,
     OmeZarrWell,
@@ -39,7 +39,6 @@ from ngio.ome_zarr_meta.ngio_specs import (
 )
 
 __all__ = [
-    "ArrayLike",
     "AxesSetup",
     "ChannelSelectionModel",
     "DefaultNgffVersion",