brainsdemonwarp:BRAINSDemonsWarp UserGuide

From NITRC Wiki

Introduction

Thirion developed a diffusing model of registration based on the concept of demons that was introduced in the 19th century by Maxwell to illustrate a paradox of thermodynamics [?, ?]. In ITK implementation of demons registration [?], a whole image grid and a free form transformation constrained by a Gaussian filter of the displacement vector field were used to control the deformability of the model. The expression of the demons force is given by Optical flow equation [?]. By plugging the Newton method tools for Lie groups within the alternate optimization framework of the demons, T. Vercauteren et al. developed an efficient non-parametric diffeomorphic image registration algorithm based on an extension of the demons algorithm. The second chapter in this document gives a short description of the program. The user’s guide is given in the chapter 3. Examples and test cases for parameters selection were described at Chapter 5.

Description

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.

Usage

This section outlines usage of BrainDemonsWarpCLP command-line tool. The goal of this application is to perform an intra-modality deformable registration with a chosen variant of the demons. If a target image is specified then the input image is registered onto the target image to produce an output image. Along with the target image other parameters need to be given by the user giving information for registration. This program can be run using the command BrainDemonsWarpCLP <Arguments>

   --numberOfBCHApproximationTerms <int>
    Number of terms in the BCH expansion (default: 2)

  -G,  --gui
    Display intermediate image volumes for debugging (default: 0)

  -a,  --use_vanilla_dem
    Run vanilla demons algorithm (default: 0)

  -e,  --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. (default: 0)

  -l <double>,  --max_step_length <double>
    Maximum length of an update vector (0: no restriction) (default: 2)

  -g <double>,  --up_field_sigma <double>
    Smoothing sigma for the update field at each iteration (default: 0)

  -t <0|1|2>,  --gradient_type <0|1|2>
    Type of gradient used for computing the demons force (0 is symmetrized
    , 1 is fixed image, 2 is moving image) (default: 0)

  --minimumMovingPyramid <std::vector<int>>
    the Shrink factor for the first level of the moving image pyramid
    (default: 16,16,16)

  --minimumFixedPyramid <std::vector<int>>
    the Shrink factor for the first level of the fixed image pyramid
    (default: 16,16,16)

  -i <std::vector<int>>,  --arrayOfPyramidLevelIterations
     <std::vector<int>>
    the iterations for each pyramid level (default: 100,100,100)

  -n <int>,  --numberOfPyramidLevels <int>
    the number of pyramid levels (default: 3)

  --numberOfMatchPoints <int>
    the number of match points (default: 2)

  --numberOfHistogramBins <int>
    the number of histogram levels (default: 256)

  --initializeWithTransform <std::string>
    Initial Transform filename

  --initializeWithFourier <std::string>
    Initial Coefficient filename.

  --initializeWithDeformationField <std::string>
    Initial deformation field vector image file name

  --fixedLandmarks <std::string>
    Landmarks filename for fixed (target) image to initialize deformation
    field

  --movingLandmarks <std::string>
    Landmarks filename for moving image to initialize deformation field

  --medianFilterSize <std::vector<int>>
    Median filter radius in all 3 directions (default: 0,0,0)

  --neighborhoodForBOBF <std::vector<int>>
    neighborhood in all 3 directions to be included when performing BOBF
    (default: 1,1,1)

  --seedForBOBF <std::vector<int>>
    coordinates in all 3 directions for Seed when performing BOBF
    (default: 0,0,0)

  --backgroundFillValue <int>
    Replacement value to overwrite background when performing BOBF
    (default: 0)

  --upperThresholdForBOBF <int>
    Upper threshold for performing BOBF (default: 70)

  --lowerThresholdForBOBF <int>
    Lower threshold for performing BOBF (default: 0)

  --movingBinaryVolume <std::string>
    Mask filename for desired region of interest in the Moving image.

  --fixedBinaryVolume <std::string>
    Mask filename for desired region of interest in the Fixed image.

  --maskProcessingMode <NOMASK|ROIAUTO|ROI|BOBF>
    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. (default: NOMASK)

  -v,  --outputDebug
    Flag to write the images after each step (default: 0)

  --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 (default:
    0)

  --forceCoronalZeroOrigin
    Flag to indicate that all images being read in must have their spatial
    centers matched. (default: 0)

  --checkerboardPatternSubdivisions <std::vector<int>>
    Number of Checkerboard subdivisions in all 3 directions (default: 4,4
    ,4)

  --outputCheckerboardVolume <std::string>
    Checkerboard image volume

  --outputDisplacementFieldPrefix <std::string>
    Displacement Field filename prefix for x y and z component images
    (default: none)

  --outputPixelType <CopyInputPixelType|float|uchar|short|ushort|int>
    Output Volume Pixel Type: float|uchar|short|ushort|int (default:
    CopyInputPixelType)

  --inputPixelType <float|uchar|short|ushort|int>
    Input Volumes Pixel Type: float|uchar|short|ushort|int (default:
    float)

  -s <double>,  --smoothDeformationFieldSigma <double>
    A gaussian smoothing value to be applied to the deformation feild/
    (default: 1)

  --registrationFilterType <FastSymmetricForces|Diffeomorphic|LogDemons
     |SymmetricLogDemons>
    Registration Filter Type: Demons|FastSymmetricForces|Diffeomorphic
    |LogDemons|SymmetricLogDemons (default: Demons)

  -O <std::string>,  --outputDeformationFieldVolume <std::string>
    Required: output deformation field vector image.

  -o <std::string>,  --outputVolume <std::string>
    Required: output resampled moving image.

  -f <std::string>,  --fixedVolume <std::string>
    Required: input fixed target image

  -m <std::string>,  --movingVolume <std::string>
    Required: input moving image

  --,  --ignore_rest
    Ignores the rest of the labeled arguments following this flag.

 --processinformationaddress <std::string>
    Address of a structure to store process information (progress, abort,
    etc.). (default: 0)

  --xml
    Produce xml description of command line arguments (default: 0)

  --echo
    Echo the command line arguments (default: 0)

  --version
    Displays version information and exits.

  -h,  --help
    Displays usage information and exits.