Difference between revisions of "Modules:BRAINSDemonWarp"

From Slicer Wiki
Jump to: navigation, search
Line 14: Line 14:
 
===Module Type & Category===
 
===Module Type & Category===
  
Type: Interactive
+
Type: CLI
  
 
Category: Registration
 
Category: Registration
 +
 +
  
 
===Authors, Collaborators & Contact===
 
===Authors, Collaborators & Contact===
* Original Author: Tom Vercauteren : Institut National de Recherche En Informatique Et En Automatique
+
 
* Contributor: Gregory Harris : University of Iowa
+
Author: This tool was developed by Hans Johnson and Greg Harris.
* Contributor: Hans J. Johnson : University of Iowa
+
 
* Contributor: Kent WIlliams : University of Iowa
+
Contributors:  
* Contact: Hans J. Johnson hans-johnson@uiowa.edu
+
 
 +
 
  
 
===Module Description===
 
===Module Description===
BRAINSDemonWarp is a command line program for image registration by using different methods including Thirion and diffeomorphic demons algorithms.  
+
 
 +
{| style="color:green" border="1"
 +
 
 +
|Program title || BRAINSDemonWarp
 +
 
 +
|-
 +
|Program version || 1.0
 +
 
 +
|-
 +
|Program documentation-url || http://wiki.slicer.org/slicerWiki/index.php/Modules:BRAINSDemonWarp
 +
 
 +
|-
 +
|}
 +
 
 
== Usage ==
 
== Usage ==
The module requires a template image and a target image and registers the template (moving) image onto the target (fixed) image. The resultant deformation fields and metric values can be written to a file. The program uses the Insight Toolkit (www.ITK.org) for all the computations, and can operate on any of the image file types supported by that library.
+
The module registers the template (moving) image onto the physical space of the target (fixed) image. The resultant deformation fields and metric values can be written to a file. The program uses the Insight Toolkit (www.ITK.org) for all the computations, and can operate on any of the image file types supported by that library.
 +
 
 
===Use Cases, Examples===
 
===Use Cases, Examples===
 
The inputs to the BrainDemonsWarp program are the target image, the template image and the optional parameters. These parameters define the arguments for histogram matching and multi resolution registration. The outputs are the deformation field, output image, checkerboard image of the output and the fixed image and the x,y,z displacement vectors. If we specify debug option we can get the outputs at different stages. The filter is templated over the input image type, real image type and the output image types. We implement the algorithm by parsing the input, preprocessing them and registering the processed images.
 
The inputs to the BrainDemonsWarp program are the target image, the template image and the optional parameters. These parameters define the arguments for histogram matching and multi resolution registration. The outputs are the deformation field, output image, checkerboard image of the output and the fixed image and the x,y,z displacement vectors. If we specify debug option we can get the outputs at different stages. The filter is templated over the input image type, real image type and the output image types. We implement the algorithm by parsing the input, preprocessing them and registering the processed images.
Line 37: Line 54:
  
 
===Quick Tour of Features and Use===
 
===Quick Tour of Features and Use===
 +
 +
* <span style="color:blue">'''''Input Image Files''''' </span>
 +
** <span style="color:green">'''Moving Image Volume'''</span> [<span style="color:orange">--movingVolume</span>][<span style="color:pink">-m</span>]: Required: input moving image
 +
** <span style="color:green">'''Fixed Image Volume'''</span> [<span style="color:orange">--fixedVolume</span>][<span style="color:pink">-f</span>]: Required: input fixed target image
 +
* <span style="color:blue">'''''Output Files''''' </span>
 +
** <span style="color:green">'''Output Image Volume'''</span> [<span style="color:orange">--outputVolume</span>][<span style="color:pink">-o</span>]: Required: output resampled moving image.
 +
** <span style="color:green">'''Output Deformation Field Volume'''</span> [<span style="color:orange">--outputDeformationFieldVolume</span>][<span style="color:pink">-O</span>]: Required: output deformation field vector image.
 +
* <span style="color:blue">'''''Thirion Registration Parameters''''' </span>
 +
** <span style="color:green">'''Registration Filter Type'''</span> [<span style="color:orange">--registrationFilterType</span>]: Registration Filter Type: Demons|FastSymmetricForces|Diffeomorphic|LogDemons|SymmetricLogDemons
 +
** <span style="color:green">'''Deformation field smoothing sigma'''</span> [<span style="color:orange">--smoothDeformationFieldSigma</span>][<span style="color:pink">-s</span>]: A gaussian smoothing value to be applied to the deformation feild/
 +
** <span style="color:green">'''Input Type'''</span> [<span style="color:orange">--inputPixelType</span>]: Input Volumes Pixel Type: float|short|ushort|int|uchar
 +
** <span style="color:green">'''Output Type'''</span> [<span style="color:orange">--outputPixelType</span>]: Output Volume Pixel Type: CopyInputPixelType|float|short|ushort|int|uchar
 +
** <span style="color:green">'''Interpolation Mode'''</span> [<span style="color:orange">--interpolationMode</span>]: Type of interpolation to be used when applying transform to moving volume.  Options are Linear, NearestNeighbor, BSpline, or WindowedSinc
 +
* <span style="color:blue">''''' Advanced Options ''''' </span>
 +
** <span style="color:green">'''Displacement Field Prefix'''</span> [<span style="color:orange">--outputDisplacementFieldPrefix</span>]: Displacement Field filename prefix for x y and z component images
 +
** <span style="color:green">'''Output Checkerboard Volume'''</span> [<span style="color:orange">--outputCheckerboardVolume</span>]: Checkerboard image volume
 +
** <span style="color:green">'''Checkerboard Pattern Subdivisions'''</span> [<span style="color:orange">--checkerboardPatternSubdivisions</span>]: Number of Checkerboard subdivisions in all 3 directions
 +
** <span style="color:green">'''Center Volumes'''</span> [<span style="color:orange">--forceCoronalZeroOrigin</span>]: Flag to indicate that all images being read in must have their spatial centers matched.
 +
** <span style="color:green">'''Warp Normalized Images'''</span> [<span style="color:orange">--outputNormalized</span>]: Flag to warp and write the normalized images to output.  In normalized images the image values are fit-scaled to be between 0 and 1
 +
** <span style="color:green">'''Write Intermediate Images'''</span> [<span style="color:orange">--outputDebug</span>][<span style="color:pink">-v</span>]: Flag to write the images after each step
 +
** <span style="color:green">'''Mask Processing Mode'''</span> [<span style="color:orange">--maskProcessingMode</span>]: What mode to use for using the masks: NOMASK|ROIAUTO|ROI|BOBF.  If ROIAUTO is choosen, then the mask is implicitly defined using a otsu forground and hole filling algorithm. Where the Region Of Interest mode uses the masks to define what parts of the image should be used for computing the deformation field.  Brain Only Background Fill uses the masks to pre-process the input images by clipping and filling in the background with a predefined value.
 +
** <span style="color:green">'''Input Fixed Mask Filename'''</span> [<span style="color:orange">--fixedBinaryVolume</span>]: Mask filename for desired region of interest in the Fixed image.
 +
** <span style="color:green">'''Input Moving Mask Filename'''</span> [<span style="color:orange">--movingBinaryVolume</span>]: Mask filename for desired region of interest in the Moving image.
 +
** <span style="color:green">'''BOBF Lower Threshold'''</span> [<span style="color:orange">--lowerThresholdForBOBF</span>]: Lower threshold for performing BOBF
 +
** <span style="color:green">'''BOBF Upper Threshold'''</span> [<span style="color:orange">--upperThresholdForBOBF</span>]: Upper threshold for performing BOBF
 +
** <span style="color:green">'''BOBF Background Replacement Value'''</span> [<span style="color:orange">--backgroundFillValue</span>]: Replacement value to overwrite background when performing BOBF
 +
** <span style="color:green">'''Seed For BOBF'''</span> [<span style="color:orange">--seedForBOBF</span>]: coordinates in all 3 directions for Seed when performing BOBF
 +
** <span style="color:green">'''Seed For BOBF'''</span> [<span style="color:orange">--neighborhoodForBOBF</span>]: neighborhood in all 3 directions to be included when performing BOBF
 +
** <span style="color:green">'''Median Filter Size'''</span> [<span style="color:orange">--medianFilterSize</span>]: Median filter radius in all 3 directions
 +
** <span style="color:green">'''Initial Deformation Field Volume'''</span> [<span style="color:orange">--initializeWithDeformationField</span>]: Initial deformation field vector image file name
 +
** <span style="color:green">'''Initial Transform  Filename'''</span> [<span style="color:orange">--initializeWithTransform</span>]: Initial Transform filename
 +
** <span style="color:green">'''Number of Histogram Bins'''</span> [<span style="color:orange">--numberOfHistogramBins</span>]: the number of histogram levels
 +
** <span style="color:green">'''Number of Match Points'''</span> [<span style="color:orange">--numberOfMatchPoints</span>]: the number of match points
 +
** <span style="color:green">'''Number of Pyramid Levels'''</span> [<span style="color:orange">--numberOfPyramidLevels</span>][<span style="color:pink">-n</span>]: the number of pyramid levels
 +
** <span style="color:green">'''the iteration count for each pyramid level'''</span> [<span style="color:orange">--arrayOfPyramidLevelIterations</span>][<span style="color:pink">-i</span>]: the iterations for each pyramid level
 +
** <span style="color:green">'''Moving Shrink Factors'''</span> [<span style="color:orange">--minimumFixedPyramid</span>]: the Shrink factor for the first level of the fixed image pyramid
 +
** <span style="color:green">'''Moving Shrink Factors'''</span> [<span style="color:orange">--minimumMovingPyramid</span>]: the Shrink factor for the first level of the moving image pyramid
 +
** <span style="color:green">'''Gradient Type'''</span> [<span style="color:orange">--gradient_type</span>][<span style="color:pink">-t</span>]: Type of gradient used for computing the demons force (0 is symmetrized, 1 is fixed image, 2 is moving image)
 +
** <span style="color:green">'''Update field smoothing'''</span> [<span style="color:orange">--upFieldSmoothing</span>][<span style="color:pink">-g</span>]: Smoothing sigma for the update field at each iteration
 +
** <span style="color:green">'''Max Step Length'''</span> [<span style="color:orange">--max_step_length</span>][<span style="color:pink">-l</span>]: Maximum length of an update vector (0: no restriction)
 +
** <span style="color:green">'''Histogram Match'''</span> [<span style="color:orange">--histogramMatch</span>][<span style="color:pink">-e</span>]: Histogram Match the input images.  This is suitable for images of the same modality that may have different absolute scales, but the same overall intensity profile.
 +
** <span style="color:green">'''Turn off Diffeomorphism'''</span> [<span style="color:orange">--use_vanilla_dem</span>][<span style="color:pink">-a</span>]: Run vanilla demons algorithm
 +
 +
  
 
== Development ==
 
== Development ==

Revision as of 22:07, 4 June 2010

Home < Modules:BRAINSDemonWarp

Return to Slicer 3.6 Documentation

Gallery of New Features


Module Name

MyModule

User Interface

General Information

Module Type & Category

Type: CLI

Category: Registration


Authors, Collaborators & Contact

Author: This tool was developed by Hans Johnson and Greg Harris.

Contributors:


Module Description

Program title BRAINSDemonWarp
Program version 1.0
Program documentation-url http://wiki.slicer.org/slicerWiki/index.php/Modules:BRAINSDemonWarp

Usage

The module registers the template (moving) image onto the physical space of the target (fixed) image. The resultant deformation fields and metric values can be written to a file. The program uses the Insight Toolkit (www.ITK.org) for all the computations, and can operate on any of the image file types supported by that library.

Use Cases, Examples

The inputs to the BrainDemonsWarp program are the target image, the template image and the optional parameters. These parameters define the arguments for histogram matching and multi resolution registration. The outputs are the deformation field, output image, checkerboard image of the output and the fixed image and the x,y,z displacement vectors. If we specify debug option we can get the outputs at different stages. The filter is templated over the input image type, real image type and the output image types. We implement the algorithm by parsing the input, preprocessing them and registering the processed images.

  1. Parsing - The images are initialized by the ValidationInputParser. This function reads in the arguments from the parameter file. It sets the histogram bins, match points, number of levels in the multi resolution registration, shrink factors and number of iterations at each levels. If the orientations of the images are different it sets the orientation of the moving image to that of the fixed image.
  2. PreProcessing - In the next step the DemonsPreProcessor preprocesses the images by resampling the template image to target image space. The intensity mismatch problem is solved by histogram matching the images. Histogram matching is done only if the command line option -e is set. ItkHistogramMatchingImageFilter is used to perform this function. Another important step in preprocessing is skull stripping. Skull stripping is done only if the command line option -maskProcessingMode is set to BOBF. We have written an itk filter, named itkBOBFFilter for this purpose. This filter takes in an input image and a whole brain mask and outputs a Brain Only Background Filled(BOBF) image. The non-brain parts in the image are filled with the user specified background value. All computations are performed in the precision of float data.
  3. Registration - The resulting moving Image and the fixed image are given as inputs to the demons registrator.It uses the MultiResolutionPDEDeformableRegistration filter with NN extrapolation as interpolator and implements the demons deformable algorithm by computing the deformation field which will map a moving image onto a fixed image. It is assumed that the vector elements behave like floating point scalars. Each vector in the deformation field represent the distance between a geometric point in the input space and a point in the output space. The output image is generated by warping the input image with the deformation field using the ItkWarpImageFilter. WarpImageFilter warps an existing image with respect to a given deformation field. Typically the mapped position does not correspond to an integer pixel position in the input image. Interpolation via an image function is used to compute values at non-integer positions. We have used the LinearInterpolateImageFunction for our application. To write the output image we cast the image to the user specified output pixel type.

Quick Tour of Features and Use

  • Input Image Files
    • Moving Image Volume [--movingVolume][-m]: Required: input moving image
    • Fixed Image Volume [--fixedVolume][-f]: Required: input fixed target image
  • Output Files
    • Output Image Volume [--outputVolume][-o]: Required: output resampled moving image.
    • Output Deformation Field Volume [--outputDeformationFieldVolume][-O]: Required: output deformation field vector image.
  • Thirion Registration Parameters
    • Registration Filter Type [--registrationFilterType]: Registration Filter Type: Demons|FastSymmetricForces|Diffeomorphic|LogDemons|SymmetricLogDemons
    • Deformation field smoothing sigma [--smoothDeformationFieldSigma][-s]: A gaussian smoothing value to be applied to the deformation feild/
    • Input Type [--inputPixelType]: Input Volumes Pixel Type: float|short|ushort|int|uchar
    • Output Type [--outputPixelType]: Output Volume Pixel Type: CopyInputPixelType|float|short|ushort|int|uchar
    • Interpolation Mode [--interpolationMode]: Type of interpolation to be used when applying transform to moving volume. Options are Linear, NearestNeighbor, BSpline, or WindowedSinc
  • Advanced Options
    • Displacement Field Prefix [--outputDisplacementFieldPrefix]: Displacement Field filename prefix for x y and z component images
    • Output Checkerboard Volume [--outputCheckerboardVolume]: Checkerboard image volume
    • Checkerboard Pattern Subdivisions [--checkerboardPatternSubdivisions]: Number of Checkerboard subdivisions in all 3 directions
    • Center Volumes [--forceCoronalZeroOrigin]: Flag to indicate that all images being read in must have their spatial centers matched.
    • Warp Normalized Images [--outputNormalized]: Flag to warp and write the normalized images to output. In normalized images the image values are fit-scaled to be between 0 and 1
    • Write Intermediate Images [--outputDebug][-v]: Flag to write the images after each step
    • Mask Processing Mode [--maskProcessingMode]: What mode to use for using the masks: NOMASK|ROIAUTO|ROI|BOBF. If ROIAUTO is choosen, then the mask is implicitly defined using a otsu forground and hole filling algorithm. Where the Region Of Interest mode uses the masks to define what parts of the image should be used for computing the deformation field. Brain Only Background Fill uses the masks to pre-process the input images by clipping and filling in the background with a predefined value.
    • Input Fixed Mask Filename [--fixedBinaryVolume]: Mask filename for desired region of interest in the Fixed image.
    • Input Moving Mask Filename [--movingBinaryVolume]: Mask filename for desired region of interest in the Moving image.
    • BOBF Lower Threshold [--lowerThresholdForBOBF]: Lower threshold for performing BOBF
    • BOBF Upper Threshold [--upperThresholdForBOBF]: Upper threshold for performing BOBF
    • BOBF Background Replacement Value [--backgroundFillValue]: Replacement value to overwrite background when performing BOBF
    • Seed For BOBF [--seedForBOBF]: coordinates in all 3 directions for Seed when performing BOBF
    • Seed For BOBF [--neighborhoodForBOBF]: neighborhood in all 3 directions to be included when performing BOBF
    • Median Filter Size [--medianFilterSize]: Median filter radius in all 3 directions
    • Initial Deformation Field Volume [--initializeWithDeformationField]: Initial deformation field vector image file name
    • Initial Transform Filename [--initializeWithTransform]: Initial Transform filename
    • Number of Histogram Bins [--numberOfHistogramBins]: the number of histogram levels
    • Number of Match Points [--numberOfMatchPoints]: the number of match points
    • Number of Pyramid Levels [--numberOfPyramidLevels][-n]: the number of pyramid levels
    • the iteration count for each pyramid level [--arrayOfPyramidLevelIterations][-i]: the iterations for each pyramid level
    • Moving Shrink Factors [--minimumFixedPyramid]: the Shrink factor for the first level of the fixed image pyramid
    • Moving Shrink Factors [--minimumMovingPyramid]: the Shrink factor for the first level of the moving image pyramid
    • Gradient Type [--gradient_type][-t]: Type of gradient used for computing the demons force (0 is symmetrized, 1 is fixed image, 2 is moving image)
    • Update field smoothing [--upFieldSmoothing][-g]: Smoothing sigma for the update field at each iteration
    • Max Step Length [--max_step_length][-l]: Maximum length of an update vector (0: no restriction)
    • Histogram Match [--histogramMatch][-e]: Histogram Match the input images. This is suitable for images of the same modality that may have different absolute scales, but the same overall intensity profile.
    • Turn off Diffeomorphism [--use_vanilla_dem][-a]: Run vanilla demons algorithm


Development

Notes from the Developer(s)

Dependencies

Tests

On the Dashboard, these tests verify that the module is working on various platforms:

Known bugs

Links to known bugs in the Slicer3 bug tracker


Usability issues

Follow this link to the Slicer3 bug tracker. Please select the usability issue category when browsing or contributing.

Source code & documentation

Links to the module's source code:

Source code: BRAINSDemonWarp

Doxygen documentation:

More Information

Acknowledgment

Include funding and other support here.

References

Publications related to this module go here. Links to pdfs would be useful.