Skip to content

Commit

Permalink
Merge pull request #438 from dstansby/reg-clean
Browse files Browse the repository at this point in the history 
Minor improvements to text in registration intro
  • Loading branch information
@zivy
zivy authored Mar 5, 2024
2 parents 6982ad5 + f000abb commit 2588b07
Showing 1 changed file with 39 additions and 44 deletions.
83 changes: 39 additions & 44 deletions Python/60_Registration_Introduction.ipynb
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,21 +6,22 @@
"source": [
"# Introduction to SimpleITKv4 Registration <a href=\"https://mybinder.org/v2/gh/InsightSoftwareConsortium/SimpleITK-Notebooks/master?filepath=Python%2F60_Registration_Introduction.ipynb\"><img style=\"float: right;\" src=\"https://mybinder.org/badge_logo.svg\"></a>\n",
"\n",
"**SimpleITK conventions:**\n",
"* Dimensionality and pixel type of registered images is required to be the same (2D/2D or 3D/3D).\n",
"* Supported pixel types are sitkFloat32 and sitkFloat64 (use the SimpleITK [Cast](http://www.simpleitk.org/doxygen/latest/html/namespaceitk_1_1simple.html#af8c9d7cc96a299a05890e9c3db911885) function if your image's pixel type is something else).\n",
"First, a reminder of some SimpleITK conventions:\n",
"* The dimensionality of images being registered is required to be the same (i.e. 2D/2D or 3D/3D).\n",
"* The pixel type of images being registered is required to be the same.\n",
"* Supported pixel types for images being registered are sitkFloat32 and sitkFloat64. You can use the SimpleITK [Cast](http://www.simpleitk.org/doxygen/latest/html/namespaceitk_1_1simple.html#af8c9d7cc96a299a05890e9c3db911885) function if your image's pixel type is something else.\n",
"\n",
"## Registration Components \n",
"\n",
"<img src=\"ITKv4RegistrationComponentsDiagram.svg\"/><br><br>\n",
"\n",
"There are many options for creating an instance of the registration framework, all of which are configured in SimpleITK via methods of the <a href=\"http://www.simpleitk.org/doxygen/latest/html/classitk_1_1simple_1_1ImageRegistrationMethod.html\">ImageRegistrationMethod</a> class. This class encapsulates many of the components available in ITK for constructing a registration instance.\n",
"\n",
"Currently, the available choices from the following groups of ITK components are:\n",
"Here is a list of currently available choices for each group of components:\n",
"\n",
"### Optimizers\n",
"\n",
"The SimpleITK registration framework supports several optimizer types via the SetOptimizerAsX() methods, these include:\n",
"Several optimizer types are supported via the `SetOptimizerAsX()` methods. These include:\n",
"* [Exhaustive](http://www.itk.org/Doxygen/html/classitk_1_1ExhaustiveOptimizerv4.html)\n",
"* [Nelder-Mead downhill simplex](http://www.itk.org/Doxygen/html/classitk_1_1AmoebaOptimizerv4.html), a.k.a. Amoeba\n",
"* [Powell optimizer](https://itk.org/Doxygen/html/classitk_1_1PowellOptimizerv4.html)\n",
Expand All @@ -31,13 +32,12 @@
" * [RegularStepGradientDescent](http://www.itk.org/Doxygen/html/classitk_1_1RegularStepGradientDescentOptimizerv4.html)\n",
"* [ConjugateGradientLineSearch](http://www.itk.org/Doxygen/html/classitk_1_1ConjugateGradientLineSearchOptimizerv4Template.html)\n",
"* [L-BFGS2](https://itk.org/Doxygen/html/classitk_1_1LBFGS2Optimizerv4.html) (Limited memory Broyden, Fletcher, Goldfarb, Shannon)\n",
"* [L-BFGS-B](http://www.itk.org/Doxygen/html/classitk_1_1LBFGSBOptimizerv4.html) (Limited memory Broyden, Fletcher,Goldfarb,Shannon-Bound Constrained) - supports the use of simple constraints ($l\\leq x \\leq u$) \n",
"* [L-BFGS-B](http://www.itk.org/Doxygen/html/classitk_1_1LBFGSBOptimizerv4.html) (Limited memory Broyden, Fletcher, Goldfarb, Shannon - Bound Constrained) - supports the use of simple constraints.\n",
"\n",
"\n",
" \n",
"### Similarity metrics\n",
"\n",
"The SimpleITK registration framework supports several metric types via the SetMetricAsX() methods, these include:\n",
"Several metric types are supported via the `SetMetricAsX()` methods. These include:\n",
"* [MeanSquares](http://www.itk.org/Doxygen/html/classitk_1_1MeanSquaresImageToImageMetricv4.html)\n",
"* [Demons](http://www.itk.org/Doxygen/html/classitk_1_1DemonsImageToImageMetricv4.html)\n",
"* [Correlation](http://www.itk.org/Doxygen/html/classitk_1_1CorrelationImageToImageMetricv4.html)\n",
Expand All @@ -48,8 +48,8 @@
"\n",
"### Interpolators\n",
"\n",
"The SimpleITK registration framework supports several interpolators via the SetInterpolator() method, which receives one of\n",
"the [following enumerations](http://www.simpleitk.org/doxygen/latest/html/namespaceitk_1_1simple.html#a7cb1ef8bd02c669c02ea2f9f5aa374e5):\n",
"Several interpolators are supported via the `SetInterpolator()` method, which can take one of\n",
"the following interpolators:\n",
"* sitkNearestNeighbor \n",
"* sitkLinear\n",
"* sitkBSpline1, sitkBSpline2, sitkBSpline3, sitkBSpline4, sitkBSpline5, where the number denotes the spline order, with sitkBSpline3 being the go-to option.\n",
Expand All @@ -60,9 +60,12 @@
"* sitkLanczosWindowedSinc\n",
"* sitkBlackmanWindowedSinc\n",
"\n",
"See the [list of interpolators in the API reference](http://www.simpleitk.org/doxygen/latest/html/namespaceitk_1_1simple.html#a7cb1ef8bd02c669c02ea2f9f5aa374e5) for more information\n",
"\n",
"\n",
"## Data - Retrospective Image Registration Evaluation\n",
"\n",
"We will be using part of the training data from the Retrospective Image Registration Evaluation ([RIRE](https://rire.insight-journal.org/)) project."
"In this notebook we will be using part of the training data from the Retrospective Image Registration Evaluation ([RIRE](https://rire.insight-journal.org/)) project."
]
},
{
Expand All @@ -89,7 +92,7 @@
"metadata": {},
"source": [
"## Utility functions\n",
"A number of utility callback functions for image display and for plotting the similarity metric during registration."
"First we define a number of utility callback functions for image display and for plotting the similarity metric during registration."
]
},
{
Expand All @@ -105,8 +108,8 @@
"from IPython.display import clear_output\n",
"\n",
"\n",
"# Callback invoked by the interact IPython method for scrolling through the image stacks of\n",
"# the two images (moving and fixed).\n",
"# Callback invoked by the IPython interact method for scrolling through image stacks of\n",
"# the two images being registered.\n",
"def display_images(fixed_image_z, moving_image_z, fixed_npa, moving_npa):\n",
" # Create a figure with two subplots and the specified size.\n",
" plt.subplots(1, 2, figsize=(10, 8))\n",
Expand Down Expand Up @@ -185,7 +188,7 @@
"source": [
"## Read images\n",
"\n",
"We first read the images, casting the pixel type to that required for registration (Float32 or Float64) and look at them."
"Now we can read the images, casting the pixel type to that required for registration (Float32 or Float64) and have a look at them."
]
},
{
Expand All @@ -212,7 +215,7 @@
"source": [
"## Initial Alignment\n",
"\n",
"Use the CenteredTransformInitializer to align the centers of the two volumes and set the center of rotation to the center of the fixed image."
"To set sensible default values for the center of rotation and initial translation between the two images, the CenteredTransformInitializer is used to align the centers of the two volumes and set the center of rotation to the center of the fixed image."
]
},
{
Expand Down Expand Up @@ -252,31 +255,23 @@
"source": [
"## Registration\n",
"\n",
"The specific registration task at hand estimates a 3D rigid transformation between images of different modalities. There are multiple components from each group (optimizers, similarity metrics, interpolators) that are appropriate for the task. Note that each component selection requires setting some parameter values. We have made the following choices:\n",
"\n",
"<ul>\n",
"<li>Similarity metric, mutual information (Mattes MI):\n",
"<ul>\n",
" <li>Number of histogram bins, 50.</li>\n",
" <li>Sampling strategy, random.</li>\n",
" <li>Sampling percentage, 1%.</li>\n",
"</ul>\n",
"</li>\n",
"<li>Interpolator, sitkLinear.</li>\n",
"<li>Optimizer, gradient descent: \n",
"<ul>\n",
" <li>Learning rate, step size along traversal direction in parameter space, 1.0 .</li>\n",
" <li>Number of iterations, maximal number of iterations, 100.</li>\n",
" <li>Convergence minimum value, value used for convergence checking in conjunction with the energy profile of the similarity metric that is estimated in the given window size, 1e-6.</li>\n",
" <li>Convergence window size, number of values of the similarity metric which are used to estimate the energy profile of the similarity metric, 10.</li>\n",
"</ul>\n",
"</li>\n",
"</ul>\n",
"\n",
"\n",
"Perform registration using the settings given above, and take advantage of the built in multi-resolution framework, use a three tier pyramid. \n",
"\n",
"In this example we plot the similarity metric's value during registration. Note that the change of scales in the multi-resolution framework is readily visible."
"The specific registration task at hand estimates a 3D rigid transformation between images of different modalities. There are multiple components from each group (optimizers, similarity metrics, interpolators) that are appropriate for the task. Note that selecting a component from each group requires setting some parameter values. We have made the following choices:\n",
"\n",
"- Similarity metric: Mutual information (Mattes MI)\n",
" - Number of histogram bins = 50\n",
" - Sampling strategy = random\n",
" - Sampling percentage = 1%\n",
"- Interpolator: sitkLinear\n",
"- Optimizer: gradient descent\n",
" - Learning rate, step size along traversal direction in parameter space: 1.0\n",
" - Number of iterations, maximum number of iterations: 100\n",
" - Convergence minimum value, value used for convergence checking in conjunction with the energy profile of the similarity metric that is estimated in the given window size: 1e-6\n",
" - Convergence window size, number of values of the similarity metric which are used to estimate the energy profile of the similarity metric: 10\n",
"\n",
"\n",
"In the next code block we perform registration using the settings given above, and take advantage of the built in multi-resolution framework, using a three tier pyramid. \n",
"\n",
"In this example we plot the similarity metric value during registration. Note that the change of scales in the multi-resolution framework is readily visible."
]
},
{
Expand Down Expand Up @@ -337,11 +332,11 @@
"cell_type": "markdown",
"metadata": {},
"source": [
"Query the registration method to see the metric value and the reason the optimization terminated. \n",
"Having finished registration, we next query the registration method to see the metric value and the reason the optimization terminated. \n",
"\n",
"The metric value allows us to compare multiple registration runs as there is a probabilistic aspect to our registration, we are using random sampling to estimate the similarity metric.\n",
"The metric value allows us to compare multiple registration runs as there is a probabilistic aspect to our registration. This is due to the random sampling used to estimate the similarity metric.\n",
"\n",
"Always remember to query why the optimizer terminated. This will help you understand whether termination is too early, either due to thresholds being too tight, early termination due to small number of iterations - numberOfIterations, or too loose, early termination due to large value for minimal change in similarity measure - convergenceMinimumValue)"
"Always remember to query why the optimizer terminated. This will help you understand whether termination is too early, either due to thresholds being too tight, early termination due to small number of iterations - numberOfIterations, or too loose, early termination due to large value for minimal change in similarity measure - convergenceMinimumValue."
]
},
{
Expand Down

0 comments on commit 2588b07

Please sign in to comment.