From 0ec0fec945f65f241be65a333280e9e8c5b35f05 Mon Sep 17 00:00:00 2001
From: Matt McCormick <matt@mmmccormick.com>
Date: Fri, 20 Dec 2024 18:11:47 -0500
Subject: [PATCH] WIP: DOC: Add OME-Zarr image registration notebook

---
 examples/ITK_Example23_OMEZarr.ipynb | 310 +++++++++++++++++++++++++++
 1 file changed, 310 insertions(+)
 create mode 100644 examples/ITK_Example23_OMEZarr.ipynb

diff --git a/examples/ITK_Example23_OMEZarr.ipynb b/examples/ITK_Example23_OMEZarr.ipynb
new file mode 100644
index 0000000..1e52bb5
--- /dev/null
+++ b/examples/ITK_Example23_OMEZarr.ipynb
@@ -0,0 +1,310 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## 23. OME-Zarr image registration"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### OME-Zarr"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "[OME-Zarr](https://ngff.openmicroscopy.org/) is a cloud-optimized file format designed for storing and managing large-scale bioimaging data [1][2]. \n",
+    "\n",
+    "## Core Features\n",
+    "\n",
+    "**Storage Architecture**\n",
+    "- Stores N-dimensional typed arrays in individually accessible chunks\n",
+    "- Uses JSON for metadata storage and binary data in chunk-files\n",
+    "- Supports up to 5 dimensions in version 0.4 (time, channel, z, y, x)\n",
+    "\n",
+    "**Performance Optimization**\n",
+    "- Implements Google Maps-style multi-resolution pyramids for smooth zooming\n",
+    "- Offers configurable chunk compression using algorithms like GZIP or Blosc\n",
+    "- Enables efficient data access through colocated pixel storage\n",
+    "\n",
+    "**Data Organization**\n",
+    "- Uses hierarchical Zarr \"groups\" to organize multiple multi-dimensional pyramids\n",
+    "- Allows metadata attachment at each hierarchy level using JSON files\n",
+    "- Supports grouping of related data (raw images, deconvolutions, segmentations)\n",
+    "\n",
+    "## Spatial Metadata Support\n",
+    "\n",
+    "Version 0.4 introduced significant spatial metadata capabilities:\n",
+    "- Supports multi-dimensional raster images with associated volumetric data\n",
+    "- Enables spatial transformations for dataset alignment\n",
+    "\n",
+    "[1] https://www.biorxiv.org/content/10.1101/2023.02.17.528834v2.full\n",
+    "[2] https://pmc.ncbi.nlm.nih.gov/articles/PMC9980008/"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### ngff-zarr"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 1,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import itk\n",
+    "from itkwidgets import compare, checkerboard, view"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "The function calls in the 3D case to import and register the images is similar to the 2D case. Masks, usually binary images, are import with the itk library similar to the images.  "
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 7,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Import Images\n",
+    "fixed_image = itk.imread('data/CT_3D_lung_fixed.mha', itk.F)\n",
+    "moving_image = itk.imread('data/CT_3D_lung_moving.mha', itk.F)\n",
+    "\n",
+    "# Import Custom Parameter Map\n",
+    "parameter_object = itk.ParameterObject.New()\n",
+    "parameter_object.AddParameterFile('data/parameters.3D.NC.affine.ASGD.001.txt')\n",
+    "\n",
+    "# \"WriteResultImage\" needs to be set to \"true\" so that the image is resampled at the end of the registration\n",
+    "# and the result_image is populated properly\n",
+    "parameter_object.SetParameter(0, \"WriteResultImage\", \"true\")\n",
+    "\n",
+    "# Import Mask Images\n",
+    "fixed_mask = itk.imread('data/CT_3D_lung_fixed_mask.mha', itk.UC)\n",
+    "moving_mask = itk.imread('data/CT_3D_lung_moving_mask.mha', itk.UC)\n",
+    "\n",
+    "# Or Optionally Create Masks from scratch\n",
+    "\n",
+    "# MaskImageType = itk.Image[itk.UC, 2]\n",
+    "# fixed_mask = itk.binary_threshold_image_filter(fixed,\n",
+    "#                                               lower_threshold=80.0,\n",
+    "#                                               inside_value=1,\n",
+    "#                                               ttype=(type(fixed), MaskImageType))\n",
+    "# moving_mask = itk.binary_threshold_image_filter(moving,\n",
+    "#                                                lower_threshold=80.0,\n",
+    "#                                                inside_value=1,\n",
+    "#                                                ttype=(type(moving), MaskImageType))"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Input Visualization\n",
+    "The images and their masks can be visualized with the itkwidget's view function. This can be useful to visually inspect the quality of the masks."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 3,
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "application/vnd.jupyter.widget-view+json": {
+       "model_id": "9e0ed89550c043a29bef90625e1cb58e",
+       "version_major": 2,
+       "version_minor": 0
+      },
+      "text/plain": [
+       "Viewer(geometries=[], gradient_opacity=0.22, interpolation=False, point_sets=[], rendered_image=<itk.itkImageP…"
+      ]
+     },
+     "metadata": {},
+     "output_type": "display_data"
+    }
+   ],
+   "source": [
+    "view(fixed_image, label_image=fixed_mask)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 4,
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "application/vnd.jupyter.widget-view+json": {
+       "model_id": "3e093036b3be428389dcebe081bb587b",
+       "version_major": 2,
+       "version_minor": 0
+      },
+      "text/plain": [
+       "Viewer(geometries=[], gradient_opacity=0.22, interpolation=False, point_sets=[], rendered_image=<itk.itkImageP…"
+      ]
+     },
+     "metadata": {},
+     "output_type": "display_data"
+    }
+   ],
+   "source": [
+    "view(moving_image, label_image = moving_mask)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Registration"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Registration can either be done in one line with the registration function..."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 8,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Call registration function\n",
+    "result_image, result_transform_parameters = itk.elastix_registration_method(\n",
+    "    fixed_image, moving_image,\n",
+    "    parameter_object=parameter_object,\n",
+    "    fixed_mask=fixed_mask, moving_mask=moving_mask,\n",
+    "    log_to_console=False)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    ".. or by initiating an elastix image filter object."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 6,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Load Elastix Image Filter Object\n",
+    "# Fixed and moving image should be given to the Elastix method to ensure that\n",
+    "# the correct 3D class is initialized.\n",
+    "elastix_object = itk.ElastixRegistrationMethod.New(fixed_image, moving_image)\n",
+    "elastix_object.SetFixedMask(fixed_mask)\n",
+    "elastix_object.SetMovingMask(moving_mask)\n",
+    "elastix_object.SetParameterObject(parameter_object)\n",
+    "\n",
+    "# Set additional options\n",
+    "elastix_object.SetLogToConsole(False)\n",
+    "\n",
+    "# Update filter object (required)\n",
+    "elastix_object.UpdateLargestPossibleRegion()\n",
+    "\n",
+    "# Results of Registration\n",
+    "result_image = elastix_object.GetOutput()\n",
+    "result_transform_parameters = elastix_object.GetTransformParameterObject()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Output Visualization\n",
+    "The results of the 3D image registration can also be visualized with widgets from the itkwidget library such as the checkerboard and compare widgets."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 9,
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "application/vnd.jupyter.widget-view+json": {
+       "model_id": "94d279f136cc48b3983cc60458776d58",
+       "version_major": 2,
+       "version_minor": 0
+      },
+      "text/plain": [
+       "VBox(children=(Viewer(annotations=False, interpolation=False, rendered_image=<itk.itkImagePython.itkImageF3; p…"
+      ]
+     },
+     "metadata": {},
+     "output_type": "display_data"
+    }
+   ],
+   "source": [
+    "checkerboard(fixed_image, result_image,pattern=5)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 10,
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "application/vnd.jupyter.widget-view+json": {
+       "model_id": "b68308d4d978479789642fe885a49896",
+       "version_major": 2,
+       "version_minor": 0
+      },
+      "text/plain": [
+       "AppLayout(children=(HBox(children=(Label(value='Link:'), Checkbox(value=True, description='cmap'), Checkbox(va…"
+      ]
+     },
+     "metadata": {},
+     "output_type": "display_data"
+    }
+   ],
+   "source": [
+    "compare(fixed_image, result_image, label_image= [fixed_image, result_image],link_cmap=True)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": []
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3 (ipykernel)",
+   "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.11"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 4
+}