Adding function for overlaying multiple segmentations onto image.

Useful for showing multiple binary segmentations overlaid onto the
same image (multiple manual semantic segmentations or predictions).

Python/05_Results_Visualization.ipynb

@@ -925,7 +925,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "## Comparing two segmentations\n",
+    "## Comparing segmentations\n",
     "\n",
     "In this section we show how to create a binary image illustrating all the locations where two segmentations differ. This is a trivial one liner in SimpleITK.\n",
     "\n",
@@ -935,7 +935,9 @@
   {
    "cell_type": "code",
    "execution_count": null,
-   "metadata": {},
+   "metadata": {
+    "scrolled": true
+   },
    "outputs": [],
    "source": [
     "binary_dilate_filter = sitk.BinaryDilateImageFilter()\n",
@@ -986,6 +988,108 @@
     ")"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "When dealing with **multiple binary** segmentations we can overlay the boundaries onto the original image as shown below."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "def overlay_segmentations(\n",
+    "    image,\n",
+    "    binary_segmentations,\n",
+    "    thickness,\n",
+    "    dilation_radius,\n",
+    "    colors=[\n",
+    "        [230, 159, 0],  # orange\n",
+    "        [86, 180, 233],  # sky blue\n",
+    "        [0, 158, 115],  # bluish green\n",
+    "        [240, 228, 66],  # yellow\n",
+    "        [0, 114, 178],  # blue\n",
+    "        [213, 94, 0],  # vermilion\n",
+    "        [204, 121, 167],  # reddish purple\n",
+    "        [153, 153, 153],  # gray\n",
+    "    ],\n",
+    "):\n",
+    "    \"\"\"\n",
+    "    Parameters\n",
+    "    ----------\n",
+    "    image (SimpleITK.Image): Image on which to overlay segmentations. Expected to be a scalar image with a pixel type of sitkUInt8.\n",
+    "    binary_segmentations (Iterable[SimpleITK.Image]):\n",
+    "    thickness (Tuple): Thickness of contour or surface along each axis (data is 2D or 3D).\n",
+    "    dilation_radius (Tuple): Dilation radius along each axis.\n",
+    "    colors (Iterable[Tuple(3)]): Color to use for each binary segmentation (except black [0,0,0]).\n",
+    "                                 The iterable is expected to contain a set of colors with at least as\n",
+    "                                 many entries as the binary segmentations. If not, a\n",
+    "                                 ValueError is raised. Default setting is the colorblind friendly\n",
+    "                                Okabe-Ito palette minus the first entry which is black\n",
+    "                                (M. Okabe, K. Ito, \"Color universal design (CUD): How to make\n",
+    "                                figures and presentations that are friendly to colorblind people\", 2008.).\n",
+    "    Returns\n",
+    "    -------\n",
+    "    SimpleITK.Image - Original image with segmentation contours/surfaces overlaid onto it in color.\n",
+    "\n",
+    "    Raises\n",
+    "    ------\n",
+    "    ValueError - If the number of entries in the colors iterable is less than the number of binary segmentations.\n",
+    "\n",
+    "    \"\"\"\n",
+    "    if len(binary_segmentations) > len(colors):\n",
+    "        raise ValueError(\n",
+    "            \"Number of segmentations is larger than number of colors, not allowed\"\n",
+    "        )\n",
+    "    for c in colors:\n",
+    "        if c == [0, 0, 0]:\n",
+    "            raise ValueError(\"Colors include black [0,0,0], not allowed\")\n",
+    "    empty_image = image * 0\n",
+    "    overlay_boundaries = [\n",
+    "        sitk.LabelMapContourOverlay(\n",
+    "            sitk.Cast(seg, sitk.sitkLabelUInt8),\n",
+    "            empty_image,\n",
+    "            opacity=1,\n",
+    "            contourThickness=thickness,\n",
+    "            dilationRadius=dilation_radius,\n",
+    "            colormap=color,\n",
+    "        )\n",
+    "        for seg, color in zip(binary_segmentations, colors)\n",
+    "    ]\n",
+    "\n",
+    "    current_image = sitk.Compose([image] * 3)\n",
+    "    for o_image in overlay_boundaries:\n",
+    "        current_mask = (\n",
+    "            sitk.NaryAdd(\n",
+    "                [\n",
+    "                    sitk.VectorIndexSelectionCast(o_image, 0),\n",
+    "                    sitk.VectorIndexSelectionCast(o_image, 1),\n",
+    "                    sitk.VectorIndexSelectionCast(o_image, 2),\n",
+    "                ]\n",
+    "            )\n",
+    "            == 0\n",
+    "        )\n",
+    "        current_image = mask_image_multiply(current_mask, current_image) + o_image\n",
+    "    return current_image\n",
+    "\n",
+    "\n",
+    "binary_segmentations = [\n",
+    "    coronal_segmentation_isotropic == lung_label,\n",
+    "    modified_segmentation == lung_label,\n",
+    "]\n",
+    "gui.multi_image_display2D(\n",
+    "    [\n",
+    "        overlay_segmentations(\n",
+    "            coronal_255_isotropic, binary_segmentations, [3, 3], [2, 2]\n",
+    "        )\n",
+    "    ],\n",
+    "    figure_size=(6, 3),\n",
+    ");"
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},