Update descriptions

eigenvivek · Aug 14, 2023 · ed30621 · ed30621
1 parent 7bde740
commit ed30621
Show file tree

Hide file tree

Showing 10 changed files with 111 additions and 142 deletions.
diff --git a/diffdrr/siddon.py b/diffdrr/siddon.py
@@ -6,7 +6,7 @@
 # %% ../notebooks/api/01_siddon.ipynb 3
 import torch
 
-# %% ../notebooks/api/01_siddon.ipynb 5
+# %% ../notebooks/api/01_siddon.ipynb 6
 def siddon_raycast(
     source: torch.Tensor,
     target: torch.Tensor,
@@ -30,7 +30,7 @@ def siddon_raycast(
     drr *= raylength
     return drr
 
-# %% ../notebooks/api/01_siddon.ipynb 7
+# %% ../notebooks/api/01_siddon.ipynb 8
 def _get_alphas(source, target, spacing, dims, eps):
     # Get the CT sizing and spacing parameters
     dx, dy, dz = spacing

diff --git a/notebooks/api/01_siddon.ipynb b/notebooks/api/01_siddon.ipynb
@@ -5,7 +5,7 @@
    "metadata": {},
    "source": [
     "---\n",
-    "description: Mapping from ray to pixel intensity\n",
+    "description: Mapping rays to pixel intensities\n",
     "output-file: siddon.html\n",
     "title: Siddon's Method\n",
     "---"
@@ -46,13 +46,13 @@
    "source": [
     "## DRR Generation\n",
     "\n",
-    "The process of generating a DRR models the geometry of an idealized projectional radiography system.\n",
-    "Let $\\mathbf s \\in \\mathbb R^3$ be the X-ray source, and $\\mathbf p \\in \\mathbb R^3$ be a target pixel on the detector plane.\n",
-    "Then $R(\\alpha) = \\mathbf s + \\alpha (\\mathbf p - \\mathbf s)$ is a ray that originates from $\\mathbf s$ ($\\alpha=0$), passes through the imaged volume, and hits the detector plane at $\\mathbf p$ ($\\alpha=1$).\n",
-    "The total energy attenuation experienced by the X-ray by the time it reaches pixel $\\mathbf p$ is given by the following line integral:\n",
+    "DRRs are generated by modeling the geometry of an idealized projectional radiography system.\n",
+    "Let $\\mathbf s \\in \\mathbb R^3$ be the X-ray source and $\\mathbf p \\in \\mathbb R^3$ be a target pixel on the detector plane.\n",
+    "Then, $R(\\alpha) = \\mathbf s + \\alpha (\\mathbf p - \\mathbf s)$ is a ray that originates from $\\mathbf s$ ($\\alpha=0$), passes through the imaged volume, and hits the detector plane at $\\mathbf p$ ($\\alpha=1$).\n",
+    "The total energy attenuation experienced by the X-ray at the time it reaches pixel $\\mathbf p$ is given by the following line integral:\n",
     "\n",
     "\\begin{equation}\n",
-    "    E(R) = \\|\\mathbf p - \\mathbf s\\|_2 \\int_0^1 \\mathbf V \\left( \\mathbf s + \\alpha (\\mathbf p - \\mathbf s) \\right) \\mathrm d\\alpha \\,,\n",
+    "    E(R) = \\|\\mathbf p - \\mathbf s\\|_2 \\int_0^1 \\mathbf V \\left( \\mathbf s + \\alpha (\\mathbf p - \\mathbf s) \\right) \\, \\mathrm d\\alpha \\,,\n",
     "\\end{equation}\n",
     "\n",
     "where $\\mathbf V : \\mathbb R^3 \\mapsto \\mathbb R$ is the imaged volume.\n",
@@ -63,10 +63,17 @@
     "    E(R) = \\|\\mathbf p - \\mathbf s\\|_2 \\sum_{m=1}^{M-1} (\\alpha_{m+1} - \\alpha_m) \\mathbf V \\left[ \\mathbf s + \\frac{\\alpha_{m+1} + \\alpha_m}{2} (\\mathbf p - \\mathbf s) \\right] \\,,\n",
     "\\end{equation}\n",
     "\n",
-    "where $\\alpha_m$ parameterizes the locations where ray $R$ intersects one of the orthogonal planes comprising the CT volume, and $M$ is the number of such intersections.\n",
+    "where $\\alpha_m$ parameterizes the locations where ray $R$ intersects one of the orthogonal planes comprising the CT volume, and $M$ is the number of such intersections."
+   ]
+  },
+  {
+   "cell_type": "raw",
+   "metadata": {},
+   "source": [
+    "::: {.callout-note}\n",
     "Note that this model does not account for patterns of reflection and scattering that are present in real X-ray systems.\n",
     "While these simplifications preclude synthesis of realistic X-rays, the model in Eq. (2) has been widely and successfully used in slice-to-volume registration.\n",
-    "Additionally, our approach of vectorizing DRR generation might also be interoperable with more sophisticated image synthesis models, an extension we examine further in the Discussion."
+    ":::"
    ]
   },
   {

diff --git a/notebooks/api/02_detector.ipynb b/notebooks/api/02_detector.ipynb
@@ -9,7 +9,6 @@
     "description: Set up the 7 degrees-of-freedom parameters for the C-arm\n",
     "output-file: detector.html\n",
     "title: Detector (C-Arm)\n",
-    "\n",
     "---"
    ]
   },
@@ -50,11 +49,13 @@
    ]
   },
   {
-   "cell_type": "markdown",
-   "id": "8e8deec1-4c6f-4352-8c88-f84491a42bab",
+   "cell_type": "raw",
+   "id": "37d3ffb6-33ea-4885-80be-f78d3d82f498",
    "metadata": {},
    "source": [
-    "Note, the `Detector` is usually initialized in the `DRR` module and shouldn't need to be called directly."
+    "::: {.callout-tip}\n",
+    "The `Detector` is usually initialized in the `DRR` module and shouldn't need to be called directly.\n",
+    ":::"
    ]
   },
   {

diff --git a/notebooks/api/03_data.ipynb b/notebooks/api/03_data.ipynb
@@ -2,15 +2,14 @@
  "cells": [
   {
    "cell_type": "raw",
+   "id": "bb4bed05",
    "metadata": {},
    "source": [
     "---\n",
     "description: Load DICOM datasets as numpy arrays with voxel dimensions\n",
     "output-file: data.html\n",
     "title: data\n",
-    "\n",
-    "---\n",
-    "\n"
+    "---"
    ]
   },
   {

diff --git a/notebooks/tutorials/introduction.ipynb b/notebooks/tutorials/introduction.ipynb
diff --git a/notebooks/tutorials/metamorphasis.ipynb b/notebooks/tutorials/metamorphasis.ipynb
@@ -7,11 +7,9 @@
    "source": [
     "---\n",
     "output-file: metamorphasis.html\n",
-    "skip_exec: true\n",
     "title: Converting to `DeepDRR`\n",
-    "\n",
-    "---\n",
-    "\n"
+    "description: It just involves changing the order of Euler angles\n",
+    "---"
    ]
   },
   {

diff --git a/notebooks/tutorials/metrics.ipynb b/notebooks/tutorials/metrics.ipynb
diff --git a/notebooks/tutorials/optimizers.ipynb b/notebooks/tutorials/optimizers.ipynb
@@ -9,6 +9,7 @@
     "output-file: registration.html\n",
     "skip-exec: true\n",
     "title: 2D-to-3D registration\n",
+    "description: Visualization of auto-differentiable registration with `DiffDRR`\n",
     "---"
    ]
   },
@@ -64,7 +65,6 @@
     }
    ],
    "source": [
-    "#|cuda\n",
     "# Make the ground truth X-ray\n",
     "SDR = 300.0\n",
     "HEIGHT = 100\n",
@@ -110,7 +110,6 @@
     }
    ],
    "source": [
-    "#|cuda\n",
     "# Make a random DRR\n",
     "def get_initial_parameters(true_params):\n",
     "    theta = true_params[\"theta\"] + np.random.uniform(-np.pi / 4, np.pi / 4)\n",
@@ -234,7 +233,6 @@
     }
    ],
    "source": [
-    "#|cuda\n",
     "# Base SGD\n",
     "drr = DRR(volume, spacing, sdr=SDR, height=HEIGHT, delx=DELX).to(device)\n",
     "reg = Registration(drr, rotations.clone(), translations.clone())\n",
@@ -286,7 +284,6 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "#|cuda\n",
     "drr = DRR(volume, spacing, sdr=SDR, height=HEIGHT, delx=DELX).to(device)"
    ]
   },
@@ -317,7 +314,6 @@
     }
    ],
    "source": [
-    "#|cuda\n",
     "animate_in_browser(params_base)"
    ]
   },
@@ -348,7 +344,6 @@
     }
    ],
    "source": [
-    "#|cuda\n",
     "animate_in_browser(params_momentum)"
    ]
   },
@@ -379,7 +374,6 @@
     }
    ],
    "source": [
-    "#|cuda\n",
     "animate_in_browser(params_momentum_dampen)"
    ]
   },

diff --git a/notebooks/tutorials/spherical.ipynb b/notebooks/tutorials/spherical.ipynb
@@ -8,9 +8,8 @@
     "---\n",
     "output-file: spherical.html\n",
     "title: Spherical coordinates\n",
-    "\n",
-    "---\n",
-    "\n"
+    "description: Explanation of Euler angles for parameterizing the C-arm\n",
+    "---"
    ]
   },
   {

diff --git a/notebooks/tutorials/timing.ipynb b/notebooks/tutorials/timing.ipynb
@@ -9,6 +9,7 @@
     "output-file: timing.html\n",
     "skip_exec: true\n",
     "title: Timing versus DRR size\n",
+    "description: Along with tips for rendering DRRs that don't fit in memory\n",
     "---"
    ]
   },
@@ -177,9 +178,17 @@
    "source": [
     "### Memory constraints\n",
     "\n",
-    "Up until this point, we could compute every ray in the DRR in one go on the GPU. However, as the DRRs get bigger, we will quickly run out of memory. For example, on a 12 GB GPU, computing a 600 by 600 DRR will raise a CUDA memory error.\n",
-    "\n",
-    "Instead, we can compute patches of the DRR at a time. Pass `patch_size` to the `DRR` module to specify the size of the patch. Note the patch size must evenly tile (`height`, `width`)."
+    "Up until this point, we could compute every ray in the DRR in one go on the GPU. However, as the DRRs get bigger, we will quickly run out of memory. For example, on a 12 GB GPU, computing a 600 by 600 DRR will raise a CUDA memory error."
+   ]
+  },
+  {
+   "cell_type": "raw",
+   "id": "9cf7598e-d411-4e33-8fbc-59efc9ef5821",
+   "metadata": {},
+   "source": [
+    "::: {.callout-tip}\n",
+    "To render DRRs whose computation won't fit in memory, we can compute patches of the DRR at a time. Pass `patch_size` to the `DRR` module to specify the size of the patch. Note the patch size must evenly tile (`height`, `width`).\n",
+    ":::"
    ]
   },
   {