From SlicerWiki
Jump to: navigation, search
Home < Documentation < Nightly < Modules < BRAINSDemonWarp

For the stable Slicer documentation, visit the 4.6 page.

Introduction and Acknowledgements

This work is part of the National Alliance for Medical Image Computing (NA-MIC), funded by the National Institutes of Health through the NIH Roadmap for Medical Research, Grant U54 EB005149. Information on NA-MIC can be obtained from the NA-MIC website.
Author: Hans Johnson, UIOWA
Contact: Hans Johnson,

University of Iowa  
Surgical Planning Laboratory  

Module Description

This program finds a deformation field to warp a moving image onto a fixed image. The images must be of the same signal kind, and contain an image of the same kind of object. This program uses the Thirion Demons warp software in ITK, the Insight Toolkit. Additional information is available at:

  1. Parsing - The images are initialized by the ValidationInputParser. This function reads in the arguments from a 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 orientation of the images are different, it sets the moving image orientation to that of the fixed image.
  1. 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.
  1. 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.

The inputs to the BrainDemonsWarp program are

  • the target image,
  • the template image and
  • optional parameters.

These parameters define the arguments for histogram matching and multi resolution registration. The outputs are

  • the deformation field,
  • the output image,
  • a checkerboard comparison image of the output and the fixed image and
  • the x,y,z displacement vectors.

If we specify the --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 inputs, preprocessing them and registering the processed images.

Use Cases


Links to tutorials that use this module

Panels and their use


  • Inputs: Common input parameters. All must be specified
    • Moving Image Volume (movingVolume): Required: input moving image
    • Fixed Image Volume (fixedVolume): Required: input fixed (target) image
    • Input Type (inputPixelType): Input volumes will be typecast to this format: float|short|ushort|int|uchar
  • Outputs: Common output parameters. At least one must be specified.
    • Output Image Volume (outputVolume): Required: output resampled moving image (will have the same physical space as the fixedVolume).
    • Output Displacement Field Volume (outputDisplacementFieldVolume): Output deformation field vector image (will have the same physical space as the fixedVolume).
    • Output Type (outputPixelType): outputVolume will be typecast to this format: float|short|ushort|int|uchar
    • Interpolation Mode (interpolationMode): Type of interpolation to be used when applying transform to moving volume. Options are Linear, ResampleInPlace, NearestNeighbor, BSpline, or WindowedSinc
  • Registration Parameters: Input parameters controlling the behavior of the demons registration.
    • Registration Filter Type (registrationFilterType): Registration Filter Type: Demons|FastSymmetricForces|Diffeomorphic
    • Displacement field smoothing sigma (smoothDisplacementFieldSigma): A gaussian smoothing value to be applied to the deformation feild at each iteration.
    • Pyramid Levels (numberOfPyramidLevels): Number of image pyramid levels to use in the multi-resolution registration.
    • Moving Shrink Factors (minimumFixedPyramid): The shrink factor for the first level of the fixed image pyramid. (i.e. start at 1/16 scale, then 1/8, then 1/4, then 1/2, and finally full scale)
    • Moving Shrink Factors (minimumMovingPyramid): The shrink factor for the first level of the moving image pyramid. (i.e. start at 1/16 scale, then 1/8, then 1/4, then 1/2, and finally full scale)
    • the iteration count for each pyramid level (arrayOfPyramidLevelIterations): The number of iterations for each pyramid level
  • Input image pre-processing options: Operations to perform on the images before starting the registration.
    • Histogram Match (histogramMatch): 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.
    • Number of histogram bins to use in histogramMatch (numberOfHistogramBins): The number of histogram levels
    • Number of Match Points (numberOfMatchPoints): The number of match points for histrogramMatch
    • Median Filter Size (medianFilterSize): Median filter radius in all 3 directions. When images have a lot of salt and pepper noise, this step can improve the registration.
  • Displacement field initialziation: Options for initializing the deformation field.
    • Initial Displacement Field Volume (initializeWithDisplacementField): Initial deformation field vector image file name
    • Initial Transform Filename (initializeWithTransform): Initial Transform filename
  • Mask Options: Options for setting binary masks for the registration.
    • 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
  • Advanced Options: Uncommon debugging or other advanced options.
    • Component displacement field prefix (outputDisplacementFieldPrefix): Displacement field filename prefix for writing separate x, y, and z component images
    • Output Checkerboard Volume (outputCheckerboardVolume): Genete a checkerboard image volume between the fixedVolume and the deformed movingVolume.
    • Checkerboard Pattern Subdivisions (checkerboardPatternSubdivisions): Number of Checkerboard subdivisions in all 3 directions
    • 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 the maximum storage type value.
    • Write Intermediate Images (outputDebug): Flag to write debugging images after each step.
    • Gradient Type (gradientType): Type of gradient used for computing the demons force (0 is symmetrized, 1 is fixed image, 2 is moving image)
    • Update field smoothing (smoothingUp): Smoothing sigma for the update field at each iteration
    • Max Step Length (maxStepLength): Maximum length of an update vector (0: no restriction)
    • Turn off Diffeomorphism (turnOffDiffeomorph): Run vanilla demons algorithm
    • Number Of Threads (numberOfThreads): Explicitly specify the maximum number of threads to use.

List of parameters generated transforming this XML file using this XSL file. To update the URL of the XML file, edit this page.

Similar Modules

  • Point to other modules that have similar functionality


Information for Developers