Add spatial annotations example

Author: kostrykin

examples/cells.ipynb

@@ -12,7 +12,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 1,
+   "execution_count": null,
    "id": "59e8a2c3",
    "metadata": {
     "execution": {
@@ -27,7 +27,9 @@
    },
    "outputs": [],
    "source": [
-    "import libcarna"
+    "import libcarna\n",
+    "import numpy as np\n",
+    "import scipy.ndimage as ndi"
    ]
   },
   {
@@ -85,7 +87,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 3,
+   "execution_count": null,
    "id": "ed16156a",
    "metadata": {
     "execution": {
@@ -166,7 +168,7 @@
     }
    ],
    "source": [
-    "GEOMETRY_TYPE_VOLUME = 2\n",
+    "GEOMETRY_TYPE_VOLUME = 1\n",
     "\n",
     "# Create and configure frame renderer\n",
     "mip = libcarna.mip(GEOMETRY_TYPE_VOLUME, cmap='jet', sr=500)\n",
@@ -607,7 +609,129 @@
     "Note that we use `dvr.replicate()` when adding the previously defined DVR to the renderer. This is because each\n",
     "rendering stage can only be added to one renderer, hence, we replicate it this time. Of course, we could have used the\n",
     "`dvr.replicate()` method the first time that we added the DVR to a renderer, too, but this is not mandatory. All\n",
-    "rendering stages provide such a method."
+    "rendering stages provide such a method.\n",
+    "\n",
+    "## Segmentation\n",
+    "\n",
+    "Perform segmentation of the nuclei by applying an intensity threshold:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "417a2589",
+   "metadata": {
+    "vscode": {
+     "languageId": "plaintext"
+    }
+   },
+   "outputs": [],
+   "source": [
+    "data_denoised = ndi.gaussian_filter(data, 1)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "b8af663f",
+   "metadata": {
+    "vscode": {
+     "languageId": "plaintext"
+    }
+   },
+   "outputs": [],
+   "source": [
+    "GEOMETRY_TYPE_MASK = 2\n",
+    "\n",
+    "seg = libcarna.volume(\n",
+    "    GEOMETRY_TYPE_MASK,\n",
+    "    ndi.gaussian_filter(data, 10) > 10_000,\n",
+    "    parent=volume,\n",
+    "    spacing=volume.spacing,\n",
+    ")\n",
+    "\n",
+    "libcarna.imshow(\n",
+    "    libcarna.animate(\n",
+    "        libcarna.animate.swing_local(camera, amplitude=22),\n",
+    "        n_frames=50,\n",
+    "    ).render(\n",
+    "        libcarna.renderer(600, 450, [\n",
+    "            dvr.replicate(),\n",
+    "            libcarna.mask_renderer(GEOMETRY_TYPE_MASK),\n",
+    "        ]),\n",
+    "        camera,\n",
+    "    ),\n",
+    ")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "97991990",
+   "metadata": {},
+   "source": [
+    "## Pointwise Annotations"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "9931ba22",
+   "metadata": {
+    "vscode": {
+     "languageId": "plaintext"
+    }
+   },
+   "outputs": [],
+   "source": [
+    "data_max = ndi.maximum_filter(data_denoised, size=5)\n",
+    "detections = np.where(\n",
+    "    np.logical_and(\n",
+    "        data_denoised == data_max,\n",
+    "        data_denoised >= 30_000,\n",
+    "    )\n",
+    ")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "537cfdd2",
+   "metadata": {
+    "vscode": {
+     "languageId": "plaintext"
+    }
+   },
+   "outputs": [],
+   "source": [
+    "GEOMETRY_TYPE_OPAQUE = 3\n",
+    "\n",
+    "ball = libcarna.meshes.create_ball(5)\n",
+    "red = libcarna.material('solid', color=libcarna.color.RED)\n",
+    "\n",
+    "for xyz in zip(*detections):\n",
+    "    libcarna.geometry(\n",
+    "        GEOMETRY_TYPE_OPAQUE,\n",
+    "        parent=volume,\n",
+    "        features={\n",
+    "            libcarna.mesh_renderer.ROLE_DEFAULT_MESH: ball,\n",
+    "            libcarna.mesh_renderer.ROLE_DEFAULT_MATERIAL: red,\n",
+    "        },\n",
+    "    ).translate(\n",
+    "        *volume.transform_from_voxels_into(volume).point(xyz)\n",
+    "    )\n",
+    "\n",
+    "libcarna.imshow(\n",
+    "    libcarna.animate(\n",
+    "        libcarna.animate.swing_local(camera, amplitude=22),\n",
+    "        n_frames=50,\n",
+    "    ).render(\n",
+    "        libcarna.renderer(600, 450, [\n",
+    "            dvr.replicate(),\n",
+    "            libcarna.opaque_renderer(GEOMETRY_TYPE_OPAQUE),\n",
+    "        ]),\n",
+    "        camera,\n",
+    "    ),\n",
+    ")"
    ]
   }
  ],

misc/libcarna/_spatial.py

@@ -282,6 +282,13 @@ def transform_into_voxels_from(self, rhs: libcarna.base.Spatial) -> np.array:
                 self.transform_from(rhs).mat
             )
 
+        def transform_from_voxels_into(self, lhs: libcarna.base.Spatial) -> np.array:
+            """
+            Compute the transformation from the voxel coordinate system of this volume into the local coordinate system
+            of a spatial object `lhs`.
+            """
+            return transform(np.linalg.inv(self.transform_into_voxels_from(lhs).mat))
+        
         def normalized(self, array: np.ndarray) -> np.ndarray:
             """
             Convert raw array intensities to the normalized intensities in [0, 1] used for rendering.

misc/libcarna/_transform.py

@@ -7,10 +7,10 @@ def __init__(self, mat: np.ndarray):
         self.mat = mat
 
     def point(self, xyz: np.ndarray = np.zeros(3)) -> np.ndarray:
-        return self.mat @ np.array([*xyz, 1.0])
+        return (self.mat @ np.array([*xyz, 1.0]))[:3]
 
     def intpoint(self, *args, **kwargs) -> tuple[int, int, int]:
-        return tuple(self.point(*args, **kwargs).round().astype(int))[:3]
+        return tuple(self.point(*args, **kwargs).round().astype(int))
 
     def direction(self, xyz: np.ndarray = np.zeros(3)) -> np.ndarray:
         return self.mat @ np.array([*xyz, 0.0])