|
|
| (9 intermediate revisions by the same user not shown) |
| Line 1: |
Line 1: |
| − | [[Documentation-3.5|Return to Slicer 3.5 Documentation]] | + | [[Documentation-3.6|Return to Slicer 3.6 Documentation]] |
| | | | |
| − | [[Announcements:Slicer3.4#Highlights|Gallery of New Features]] | + | [[Announcements:Slicer3.6#Highlights|Gallery of New Features]] |
| − | ===Register Images=== | + | |
| | + | __NOTOC__ |
| | + | ===Module Name=== |
| | + | Register Images Robust Affine |
| | | | |
| | {| | | {| |
| − | |[[Image:RegisterImagesOverview.png|thumb|280px|Before <br> Two [[Modules:Color-Documentation-3.4#Module_Description|LUTs]] are used to display the two volumes]] | + | |[[Image:Fiducial_registration_before.jpg|thumb|280px|Images before alignment]] |
| − | |[[Image:RegisterImageRunning.png|thumb|280px|During <br> Note that both cores run at full capacity]] | + | |[[Image:Fiducial_registration_after_multires.jpg|thumb|280px|Images after alignment]] |
| − | |-
| |
| − | |[[Image:B-spline-reg.png|thumb|280px|After <br> Fixed data set with red, moving with blue LUT.]]
| |
| − | |[[Image:B-spline-reg-detail.png|thumb|280px|After <br> Moving versus Resampled <br> Demonstration of the extent of deformation<br>grid spacing = 60 pixels, 4 core machine, <br>9GB memory footprint, roughly 1.5 hours<br>volume=512x512x472]]
| |
| | |} | | |} |
| | | | |
| Line 15: |
Line 15: |
| | ===Module Type & Category=== | | ===Module Type & Category=== |
| | | | |
| − | Type: CLI Module calling ITK functions | + | Type: CLI |
| | | | |
| | Category: Registration | | Category: Registration |
| | | | |
| | ===Authors, Collaborators & Contact=== | | ===Authors, Collaborators & Contact=== |
| − | * Author1: Stephen Aylward, Kitware | + | * Author1: Casey Goodlett, Kitware |
| − | * Author2: Casey Goodlett, Kitware
| + | * Contributor1: Dominik Meier, BWH |
| − | * Contributor1: Ron Kikinis (copying documentation) | + | * Contact: Casey Goodlett |
| − | * Contact: Casey Goodlett, Kitware | |
| | | | |
| | ===Module Description=== | | ===Module Description=== |
| − | This Module is an integrated framework providing access to ITK registration technologies. Algorithms can be run in single mode or pipelined. Depending on the size of the data sets, a significant amount of memory is needed. There is an option to trade off speed for memory. Most of the code is parallelized and will take advantage of multicore capabilities, if available.
| + | Mutual information based affine registration using a multi-resolution optimization strategy. Several parts of the algorithm are based on a description of the FLIRT algorithm, see the Reference section. |
| | | | |
| − | ==== Major Features ==== | + | == Usage == |
| | | | |
| − | The major features of the module include:
| |
| − | * Default parameters register many full-head and skull-stripped MRI: rigid, affine, and BSpline
| |
| − | * Offers a complete, pipeline-based registration solution
| |
| − | ** Load and apply existing transforms
| |
| − | ** Compute rigid, affine, and bspline transforms in sequence with a single command
| |
| − | * Intuitive parameters
| |
| − | ** Instead of setting obscure "scales" for parameters, you set global values for "Expected Offset", "Expected Rotation", ... to indicate how much mis-registration is anticipated in the data being registered
| |
| − | * MinimizeMemory option provides a way to compute bspline registrations using a dense set of control points and a large number of samples on "normal" computers (albeit computation time increases)
| |
| − | * SampleFromOverlap option allows images of vastly different sizes to be registered
| |
| − | ** Helps to avoid (but does not completely eliminate) the annoying ITK exception, "too many samples falls outside of the image"
| |
| − | * Incorporates testing
| |
| − | ** Specify a baseline image, and modules will perform the requested registration, compare its results with the baseline image, and return success/failure
| |
| − | * Based on an extensible and re-usable class structure.
| |
| | | | |
| − | == Usage == | + | ===Examples, Use Cases & Tutorials=== |
| − | * If you have a large data set or little memory, [[Modules:RegisterImages-Documentation-3.4#Advaned_Registration_Parameters_Tab|select the minimize memory option]]
| |
| − | * If you are planning to use the b-spline registration, be sure to read the [[Modules:RegisterImages-Documentation-3.4#Advanced_BSpline_Parameters|discussion of parameter setting]] in the section below.
| |
| | | | |
| | + | * This module is intended to be a robust general-purpose mutual information affine registration tool |
| | + | * See [http://na-mic.org/Wiki/index.php/Projects:RegistrationDocumentation:UseCaseInventory Registration Use Case project] |
| | | | |
| | ===Quick Tour of Features and Use=== | | ===Quick Tour of Features and Use=== |
| | + | List all the panels in your interface, their features, what they mean, and how to use them. For instance: |
| | | | |
| − | See [http://www.na-mic.org/Wiki/index.php/ITK_Registration_Optimization here] for more information.
| + | * '''Required:''' |
| − | | + | ** Fixed Image - Target image for registration. The resulting transform will map the moving image to the fixed image. |
| − | == Main Registration Panel ==
| + | ** Moving Image - Source image for registration. The resulting transform will map the moving image to the fixed image. |
| − | === Parameter Choices ===
| + | ** Resample Image - Image node to create a resampled moving image. The image node specified in this transform will store the result of resampling the moving image with computed transform. Typically the user should select to create a new volume here. This does not need to be specified, but the user should select either this option or output transform. |
| − | * The default parameters should work for a wide range of cases
| + | ** Output Transform - Store the result of the transform in the given transform node. Typically the user should select to create a new transform node. |
| − | * In some cases (e.g. unusual acquisition conditions and/or highly inconsistent acquisition protocols) you will need to change the default parameters.
| + | * '''Optional:''' |
| − | * In other situations, you may wish to tweak parameters to achieve your application-specific speed-vs-accuracy trade-off
| + | ** Fixed Image Mask Image - A label image that is used to mask regions of interest in the fixed image. The mask specified here is used to restrict the placement of samples in the fixed image used for optimizing the registration. The user may want to mask the brain from background, mask everything in the brain except a lesion region, or otherwise specify the regions they would like to optimize in the registration. |
| − | | + | ** Fixed Image ROI - A box specified by the ROI module to limit the region of the fixed image used for computing the image match metric. |
| − | See also [http://www.na-mic.org/Wiki/index.php/ITK_Registration_Optimization this page on the NA-MIC wiki about parameter tuning for this module].
| + | * '''Advanced:''' |
| − | | + | ** Number of iteration - Number of iterations to run at each stage of the optimization. This method uses Fletcher-Reeves-Polak-Ribiere optimizer and the number of 1-D optimization is bounded by the number of iterations times the dimensionality of the transform. |
| − | ===Overview===
| + | ** Number of line iterations - Number of iterations to use in the 1-D line optimization. This is used to bound the maximum number of iterations that can be used in the 1-D optimization at each iteration of the optimization . |
| − | * Step 1: Loaded transform | + | ** Step size - Maximum step size of each iteration of the transform. The optimizer computes a 1-D minimum along the gradient direction that is bounded by the current location and this distance. This should be specified in terms of voxels. |
| − | ** You may load a pre-computed transform to initialize the registration. | + | ** Step Tolerance - Minimum step size to continue optimization. When the 1-D minimization bounds the minimum within this tolerance, the optimizer moves to the next iteration. |
| − | ** If one is loaded, it is immediately applied (i.e., the moving image is resampled)
| + | ** Metric Tolerance - When steps of the optimizer result in changes in the metric value less than this, the optimization stops and the current result is returned. |
| − | * Step 2: Initial registration
| |
| − | ** Options are:
| |
| − | *** None (sets the center of rotation to the center of the moving image)
| |
| − | *** Landmark (uses N-pairs of landmarks (passed as vectors) and a least-squared error metric to register the images using a rigid transform | |
| − | *** Image Centers (shifts the images to align their centers)
| |
| − | *** Centers of Mass (shifts the images to align their centers of mass)
| |
| − | *** Second Moments (shifts and rotates the images to align the 1st and 2nd moments)
| |
| − | * Step 3: Registration
| |
| − | ** Options are:
| |
| − | *** None (applies the loaded transforms)
| |
| − | *** Initial
| |
| − | **** computes and applies the initial transform to the loaded registrations)
| |
| − | *** Rigid
| |
| − | **** computes a rigid transform and then applies it to the loaded registrations
| |
| − | *** Affine
| |
| − | **** computes an affine transform and then applies it to the loaded registrations
| |
| − | *** BSpline
| |
| − | **** computes a bspline transform and then applies it to the loaded registrations
| |
| − | *** PipelineRigid
| |
| − | **** computes a rigid transform (initialized using the results from the initial registration) and then applies it to the loaded registrations
| |
| − | *** PipelineAffine | |
| − | **** computes a rigid transform (initialized using the results from the initial registration), uses those results to initialize and compute an affine transform, and then applies it to the loaded registrations
| |
| − | *** PipelineBSpline
| |
| − | **** computes a rigid transform (initialized using the results from the initial registration), uses those results to initialize and compute an affine transform, and then applies it to the loaded registrations, THEN computes and applies a BSpline transform
| |
| − | | |
| − | | |
| − | | |
| − | ==Detailed Information==
| |
| − | | |
| − | === IO Tab ===
| |
| − | {|
| |
| − | |
| |
| − | * Set the fixed and moving images using images in the scene | |
| − | * Optionally set the ResampleImage to store the output image
| |
| − | ** If not set, registration won't conduct the final resampling, saving computation time
| |
| − | |[[Image:RegisterImagesIO.png|thumb|380px| IO panel <br> Resample image is the resampled moving image.]]
| |
| − | |}
| |
| − | | |
| − | === Registration Parameters Tab ===
| |
| − | {|
| |
| − | |
| |
| − | * Load Transform | |
| − | ** provide the Loaded Transform for the loaded phase of registration | |
| − | * Save Transform
| |
| − | ** results of the entire registration pipeline will be saved here
| |
| − | * Initialization
| |
| − | ** see registration pipeline discussion
| |
| − | * Registration
| |
| − | ** see registration pipeline discussion
| |
| − | ** For rigid and affine registrations, one-plus-one evoluation optimization is first applied for N iterations, and then FRPR gradient-line-search optimization is applied.
| |
| − | *** For more information, check the code: RegisterImagesModule/itkOptimizedImageToImageRegistrationmethod.h/txx
| |
| − | ** For BSpline registration, a hierarchical registration scheme is used. An image pyramid having 3 levels is used to resample the images and the control grids. Heuristics are used to control the various resampling parameters. At each level, registration is conducted using FRPR gradient-line-search optimization.
| |
| − | *** For more information, check the code: RegisterImagesModule/itkBSplineImageToImageRegistrationMethod.h/txx
| |
| − | * Metric
| |
| − | ** Use the Mutual Information metric. It is an multithreaded and optimized version of the Mattes MI method.
| |
| − | *** For more information, check the code; Insight/Code/Review/itkOptMattesMutualInformationImageMetric.h/txx
| |
| − | * "Expected" values
| |
| − | ** For rigid, affine, and bspline registration, parameter scales (refer to the Insight Software Guide) are represented as hyper-parameters in the RegisterImages module.
| |
| − | *** "Expected Offset" controls the offset scales in rigid and affine registration the deformation vector scale in bspline registration
| |
| − | *** "Expected Rotation" is roughly in terms of radians. It controls the rotation angles in rigid and affine registration
| |
| − | *** "Expected Scale" is for scaling during affine registration | |
| − | *** "Expected Skew" is for skew for affine registration
| |
| − | |[[Image:RegisterImagesGlobalParameters.png|thumb|380px| Global Parameters<br> This panel controls what will happen overall.]]
| |
| − | |}
| |
| − | | |
| − | === Advaned Registration Parameters Tab ===
| |
| − | {|
| |
| − | |* Verbosity level
| |
| − | ** Controls the level of detail in the reports in the log file
| |
| − | * Sample from fixed/moving overlap
| |
| − | ** When the fixed image is much larger than the moving image, it is CRITICAL to set this flag and to pick a good initialization method. In that way, only the portion of the fixed image that is initially covered by the moving image will be used during registration. This prevents ITK from throwing an exception (error) stating that too many fixed-image samples miss (map outside of) the moving image.
| |
| − | * Fixed image intensity percentage threshold
| |
| − | ** A less robust way to overcome the image overlap issue discussed above, you can specify a threshold as a portion (0 to 1) of the fixed image intensity range that should be used to select fixed image samples for computing the metric. That is, by specifying 0.5, only the pixels in the upper half of the fixed-image's intensity range will be used during random sample selection.
| |
| − | ** Remember, it is important to include pixels inside and outside of the object of interest, otherwise the fixed image histogram may be too homogeneous for mis-registrations to be detected.
| |
| − | * Random number seed
| |
| − | ** To ensure consistent performance, you can set a seed - repeated runs should produce identical results.
| |
| − | * Number of threads
| |
| − | ** Number of multi-core/mult-processor threads to use during metric value computations.
| |
| − | * MimimizeMemory
| |
| − | ** Turns off caching of intermediate values during bspline registration
| |
| − | ** Provides a way to compute bspline registrations using a dense set of control points and a large number of samples on "normal" computers (albeit computation time increases)
| |
| − | ** Rule of thumb, if the BSpline registration crashes - re-run with this option enabled.
| |
| − | * use windowed sinc for final interpolation | |
| − | ** If you have time to kill. Extremely slow and only marginally better than bspline resampling (the default).
| |
| − | | |
| − | |[[Image:RegisterImagesAdvancedGlobalParameters.png|thumb|380px| Advanced Global Parameters Tab]]
| |
| − | |}
| |
| − | | |
| − | === Registration Testing Parameters ===
| |
| − | | |
| − | | |
| − | <big>'''The testing section exposes functionality for development and compilation. It should not be used in regular operation of Slicer.'''</big>
| |
| − | {|
| |
| − | |
| |
| − | * Baseline Image
| |
| − | ** Set the image against which the Resampled Image (IO tab) will be compared after registration | |
| − | * Number of Failed Pixels Tolerance
| |
| − | ** Registration returns "failure" if this many pixels are different between the Resampled and Baseline images
| |
| − | * Intensity Tolerance
| |
| − | ** Minimum intensity difference between corresponding Resampled and Baseline pixels for those pixels to be counted as failures
| |
| − | * Radius Tolerance
| |
| − | ** The program will search this neighborhood size about each Resampled pixel to find the closest matching Baseline pixel. The closest matching pixels are compared using the Intensity Tolerance (above)
| |
| − | * Baseline Difference Image
| |
| − | ** Result of subtracting the resampled image from the baseline image
| |
| − | * Baseline Resamples Moving Image
| |
| − | ** resampled image, resampled into the space of the baseline image
| |
| − | |[[Image:RegisterImagesTestingParameters.png|thumb|380px| Testing Parameters]]
| |
| − | |}
| |
| − | | |
| − | === Advanced Initial Registration Parameters ===
| |
| − | {|
| |
| − | |
| |
| − | * Fixed / Moving Landmarks
| |
| − | ** A vector string (comma separated base-3 list) of the indexes of corresponding points in the fixed and moving images
| |
| − | ** If supplied, then choose "Landmarks" as the initial registration method (see discussion on registration pipeline)
| |
| − | |[[Image:RegisterImagesAdvancedInitialFiducials.png|thumb|380px|Initialization of rigid registration]]
| |
| − | |}
| |
| − | | |
| − | === Advanaced Rigid and Affine Parameters ===
| |
| − | {|
| |
| − | |
| |
| − | * MaxIterations
| |
| − | ** Number of iterations for one-plus-one and for FRPR registration | |
| − | * Sampling Ratio
| |
| − | ** Portion of the image pixels to be used when computing the metric
| |
| − | |[[Image:RegisterImagesAdvnacedRigidParameters.png|thumb|380px|Advanced Parameters for rigid registration]]
| |
| − | [[Image:RegisterImagesAdvancedAffineParameters.png|thumb|380px| Advanced Parameters for affine registration]]
| |
| − | |}
| |
| − | | |
| − | === Advanced BSpline Parameters ===
| |
| − | {|
| |
| − | |
| |
| − | * MaxIterations | |
| − | ** Number of iterations for one-plus-one and for FRPR registration | |
| − | * Sampling Ratio
| |
| − | ** Portion of the image pixels to be used when computing the metric
| |
| − | ** Do the math...if you have 40 pixels between control points, then there will be 40^3 (64,000) pixels relevant to each control point. That excessive for directing one control point. Keep the sampling small. For 40 pixels between control points, a sampling density of 0.1 provide 6,400 pixels for metric computation at each control point - more than enough.
| |
| − | ** When in doubt, turn on MinimizeMemory
| |
| − | * Control point spacing (pixels)
| |
| − | ** Don't think about grid size - instead think about the level of detail that needs to be resolved (see discussion on sampling ratio).
| |
| − | ** When in doubt, turn on MinimizeMemory
| |
| − | |[[Image:RegisterImagesAdvancedBSplineParameters.png|thumb|380px|Advanced Parameters for B-Spline registration]]
| |
| − | |}
| |
| − | | |
| − | ==Use Cases==
| |
| − | === Example 2: Affine Registration ===
| |
| − | | |
| − | * Task:
| |
| − | ** Affine registration of head MRI from two different subjects | |
| − | * Data:
| |
| − | ** Using cases UNC-Healthy-Normal002 (fixed) and UNC-Healthy-Normal004 (moving)
| |
| − | ** Data provided by Dr. Bullitt at UNC.
| |
| − | ** Data is available from Kitware's MIDAS archive at http://hdl.handle.net/1926/542
| |
| − | ** Data can be automatically downloaded into ${RegisterImages_BINARY_DIR}/Testing/Data directory by enabling the CMake variable "BUILD_REGISTER_IMAGES_REAL_WORLD_TESTING"
| |
| − | *** Warning this also enables additional tests that can take 4+ hours to complete.
| |
| − | *** To see the code for automatically downloading from MIDAS (via svn), see Slicer3/Applications/CLI/RegisterImagesModule/Applications/CMakeLists.txt
| |
| − | | |
| − | === Example 3: BSpline Registration ===
| |
| − | | |
| − | * Task: | |
| − | ** BSpline registration of head MRI from two different subjects | |
| − | * Data:
| |
| − | ** Using cases UNC-Healthy-Normal002 (fixed) and UNC-Healthy-Normal004 (moving)
| |
| − | ** Data provided by Dr. Bullitt at UNC.
| |
| − | ** Data is available from Kitware's MIDAS archive at http://hdl.handle.net/1926/542
| |
| − | ** Data can be automatically downloaded into ${RegisterImages_BINARY_DIR}/Testing/Data directory by enabling the CMake variable "BUILD_REGISTER_IMAGES_REAL_WORLD_TESTING"
| |
| − | *** Warning this also enables additional tests that can take 4+ hours to complete.
| |
| − | *** To see the code for automatically downloading from MIDAS (via svn), see Slicer3/Applications/CLI/RegisterImagesModule/Applications/CMakeLists.txt
| |
| | | | |
| | == Development == | | == Development == |
| Line 238: |
Line 57: |
| | ===Dependencies=== | | ===Dependencies=== |
| | | | |
| − | This module makes use of GenerateCLP, MRMLIO and ITK.
| + | * Editor, Threshold, Segmentation module: Useful for computing a label mask for the 'Fixed Image Mask Image' option. |
| − | * GenerateCLP is used to defined the command-line options. GenerateCLP is distributed with Slicer (/Libs/GenerateCLP).
| |
| − | * MRMLIO is used to replace reading/writing images in ITK to instead passing pointers to shared memory. MRMLIO is distributed with Slicer (/Libs/MRMLIO).
| |
| − | * ITK is used to provide the algorithms. ITK must be compiled with the CMake variables USE_REVIEW, USE_TRANSFORM_IO, and USE_OPTIMIZED_REGISTRATION_METHODS enabled. These options are automatically enabled when ITK is build using Slicer's getBuildTest.tcl script. | |
| | | | |
| | ===Known bugs=== | | ===Known bugs=== |
| | | | |
| − | * Module may fail (and not report a useful error to the console - check the log files) if insufficient memory is available. If so, please consider enabling the MinimizeMemory option in the Advanced Options tab. | + | * [http://na-mic.org/Mantis/view.php?id=789 Box ROI is slow] |
| | + | * Follow this [http://na-mic.org/Mantis/main_page.php link] to the Slicer3 bug tracker. |
| | | | |
| − | Follow this [http://na-mic.org/Mantis/main_page.php link] to the Slicer3 bug tracker.
| |
| | | | |
| | ===Usability issues=== | | ===Usability issues=== |
| Line 255: |
Line 71: |
| | ===Source code & documentation=== | | ===Source code & documentation=== |
| | | | |
| − | Customize following [http://viewvc.slicer.org/viewcvs.cgi/ links] for your module. | + | Customize following links for your module: |
| − | | |
| − | [http://www.na-mic.org/Slicer/Documentation/Slicer3-doc/html/ Links] to documentation generated by doxygen.
| |
| | | | |
| | + | Source code: |
| | + | *[http://viewvc.slicer.org/viewcvs.cgi/Applications/CLI/RegisterImagesModule/MultiResApplications/RegisterImagesMultiRes.cxx] |
| | + | |
| | == More Information == | | == More Information == |
| | | | |
| | ===Acknowledgment=== | | ===Acknowledgment=== |
| − | Include funding and other support here.
| + | This work is part of the National Alliance for Medical Image Computing (NAMIC), funded by the National Institutes of Health through the NIH Roadmap for Medical Research, Grant U54 EB005149. Information on the National Centers for Biomedical Computing can be obtained from National Centers for Biomedical Computing. |
| | | | |
| | ===References=== | | ===References=== |
| − | Publications related to this module go here. Links to pdfs would be useful.
| + | *The algorithm here is based on the description of the flirt algorithm as described below. |
| − | *[[Media:Rigid registration of aligned images-03-2009.txt|some email about initialization]]
| + | *[http://www.fmrib.ox.ac.uk/analysis/research/flirt/] |
| − | *[http://www.na-mic.org/Wiki/index.php/ITK_Registration_Optimization ITK Registration optimization] | + | *M. Jenkinson and S.M. Smith. A global optimisation method for robust affine registration of brain images. Medical Image Analysis, 5(2):143-156, 2001. |
| − | *[http://www.slicer.org/slicerWiki/index.php/Slicer3:LinearRegistrationUseCases Slicer2 vs Slicer3 registration validation] | + | *M. Jenkinson, P.R. Bannister, J.M. Brady, and S.M. Smith. Improved optimisation for the robust and accurate linear registration and motion correction of brain images. NeuroImage, 17(2):825-841, 2002. |
| − | *[http://www.batchmake.org/Wiki/Batchmake_slicer Using BatchMake with Slicer RegisterImages module] | |
| − | | |
| − | ===Wishlist===
| |
| − | *custom gui for creation of matched fiducials for fiducial based initialization
| |
| − | *using Slicer transforms for initialization
| |
| − | *output results of rigid, affine, b-spline either as transforms or as resampled volumes
| |
| − | *include moving filename into default names of results
| |
| − | *display fixed and moving results in compareview with proper LUTs (different colors for fixed and result, apply w/l from moving to results volume
| |
| − | *use in combination with VOI
| |
| − | *more detailed explanation of how to set parameters
| |
| − | *increase number of example solutions
| |
