Modules:BRAINSFit

Return to Slicer 3.6 Documentation

Gallery of New Features

Module Name

BRAINSFit

Before registration

AfterRegistration

General Information

Module Type & Category

Type: CLI

Category: Registration

Authors, Collaborators & Contact

Author: Hans J. Johnson, hans-johnson -at- uiowa.edu, http://wwww.psychiatry.uiowa.edu

Contributors: Hans Johnson(1,3,4); Kent Williams(1); Gregory Harris(1), Vincent Magnotta(1,2,3); Andriy Fedorov(5), fedorov -at- bwh.harvard.edu (Slicer integration); (1=University of Iowa Department of Psychiatry, 2=University of Iowa Department of Radiology, 3=University of Iowa Department of Biomedical Engineering, 4=University of Iowa Department of Electrical and Computer Engineering, 5=Surgical Planning Lab, Harvard)

Module Description

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

Insight/Examples/Registration/ImageRegistration8.cxx This program is the most functional example of multi-modal 3D rigid image registration provided with ITK. ImageRegistration8 is in the Examples directory, and also sec. 8.5.3 in the ITK manual. We have modified and extended this example in several ways:

• defined a new ITK Transform class, based on itkScaleSkewVersor3DTransform which has 3 dimensions of scale but no skew aspect.
• implemented a set of functions to convert between Versor Transforms and the general itk::AffineTransform and deferred converting from specific to more general representations to preserve transform information specificity as long as possible. Our Rigid transform is the narrowest, a Versor rotation plus separate translation.
• Added a template class itkMultiModal3DMutualRegistrationHelper which is templated over the type of ITK transform generated, and the optimizer used.
• Added image masks as an optional input to the Registration algorithm, limiting the volume considered during registration to voxels within the brain.
• Added image mask generation as an optional input to the Registration algorithm when meaningful masks such as for whole brain are not available, allowing the fit to at least be focused on whole head tissue.
• Added the ability to use one transform result, such as the Rigid transform, to initialize a more adaptive transform
• Defined the command line parameters using tools from the Slicer [ 3] program, in order to conform to the Slicer3 Execution model.

Added the ability to write output images in any ITK-supported scalar image format.

• Extensive testing as part of the BRAINS2 application suite, determined reasonable defaults for registration algorithm parameters. http://testing.psychiatry.uiowa.edu/CDash/

Usage

The BRAINSFit distribution contains a directory named TestData, which contains two example images. The first, test.nii.gz is a NIfTI format image volume, which is used the input for the CTest-managed regression test program. The program makexfrmedImage.cxx, included in the BRAINSFit distribution was used to generate test2.nii.gz, by scaling, rotating and translating test.nii.gz. You can see representative Sagittal slices of test.nii.gz (in this case, the fixed image, test2.nii.gz (the moving image), and the two images ’checkerboarded’ together to the right. To register test2.nii.gz to test.nii.gz, you can use the following command:

BRAINSFit --fixedVolume test.nii.gz \
--movingVolume test2.nii.gz \
--outputVolume registered.nii.gz \
--transformType Affine

A representative slice of the registered results image registered.nii.gz is to the right. You can see from the Checkerboard of the Fixed and Registered images that the fit is quite good with Affine transform-based registration. The blurring of the registered images is a consequence of the initial scaling used in generating the moving image from the fixed image, compounded by the interpolation necessitated by the transform operation.

You can see the differences in results if you re-run BRAINSFit using Rigid, ScaleVersor3D, or ScaleSkewVersor3D as the ----transformType parameter. In this case, the authors judged Affine the best method for registering these particular two images; in the BRAINS2 automated processing pipeline, Rigid usually works well for registering research scans.

Quick Tour of Features and Use

This section was partially generated with a python script to convert Slicer Execution Model xml files into MediaWiki compatible documentation

Input Parameters The fixed image for registration by mutual information optimization. Fixed Image Volume [--fixedVolume] : The fixed image for registration by mutual information optimization. Moving Image Volume [--movingVolume] : The moving image for registration by mutual information optimization. Registration phases to use Filename of transform used to initialize the registration. This CAN NOT be used with either CenterOfHeadLAlign, MomentsAlign, GeometryAlign, or initialTransform file. Initialize with previously generated transform [--initialTransform] : Filename of transform used to initialize the registration. This CAN NOT be used with either CenterOfHeadLAlign, MomentsAlign, GeometryAlign, or initialTransform file. Initialize with MomentsAlign registration phase [--useMomentsAlign] : MomentsAlign assumes that the center of mass of the images represent similar structures. Perform a MomentsAlign registration as part of the sequential registration steps. This option MUST come first, and CAN NOT be used with either CenterOfHeadLAlign, GeometryAlign, or initialTransform file. This family of options superceeds the use of transformType if any of them are set. Default value: false Initialize with GeometryCenterAlign registration phase [--useGeometryAlign] : GeometryAlign on assumes that the center of the voxel lattice of the images represent similar structures. Perform a GeometryCenterAlign registration as part of the sequential registration steps. This option MUST come first, and CAN NOT be used with either MomentsAlign, CenterOfHeadAlign, or initialTransform file. This family of options superceeds the use of transformType if any of them are set. Default value: false Initialize with CenterOfHeadAlign registration phase [--useCenterOfHeadAlign] : CenterOfHeadAlign attempts to find a hemisphere full of foreground voxels from the superior direction as an estimate of where the center of a head shape would be to drive a center of mass estimate. Perform a CenterOfHeadAlign registration as part of the sequential registration steps. This option MUST come first, and CAN NOT be used with either MomentsAlign, GeometryAlign, or initialTransform file. This family of options superceeds the use of transformType if any of them are set. Default value: false Include Rigid registration phase [--useRigid] : Perform a rigid registration as part of the sequential registration steps. This family of options superceeds the use of transformType if any of them are set. Default value: false Include ScaleVersor3D registration phase [--useScaleVersor3D] : Perform a ScaleVersor3D registration as part of the sequential registration steps. This family of options superceeds the use of transformType if any of them are set. Default value: false Include ScaleSkewVersor3D registration phase [--useScaleSkewVersor3D] : Perform a rigid registration as part of the sequential registration steps. This family of options superceeds the use of transformType if any of them are set. Default value: false Include Affine registration phase [--useAffine] : Perform a rigid registration as part of the sequential registration steps. This family of options superceeds the use of transformType if any of them are set. Default value: false Include BSpline registration phase [--useBSpline] : Perform a rigid registration as part of the sequential registration steps. This family of options superceeds the use of transformType if any of them are set. Default value: false Output Settings (At least one output must be specified.) (optional) Filename to which save the estimated transform. NOTE: You must set at least one output object (either a deformed image or a transform. NOTE: USE THIS ONLY IF THE FINAL TRANSFORM IS BSpline Slicer BSpline Transform [--bsplineTransform] : (optional) Filename to which save the estimated transform. NOTE: You must set at least one output object (either a deformed image or a transform. NOTE: USE THIS ONLY IF THE FINAL TRANSFORM IS BSpline Slicer Linear Transform [--linearTransform] : (optional) Filename to which save the estimated transform. NOTE: You must set at least one output object (either a deformed image or a transform. NOTE: USE THIS ONLY IF THE FINAL TRANSFORM IS ---NOT--- BSpline Output Transform [--outputTransform] : (optional) Filename to which save the (optional) estimated transform. NOTE: You must select either the outputTransform or the outputVolume option. Output Image Volume [--outputVolume] : (optional) Output image for registration. NOTE: You must select either the outputTransform or the outputVolume option. Output Image Pixel Type [--outputVolumePixelType] : The output image Pixel Type is the scalar datatype for representation of the Output Volume. Default value: float Registration Parameters Specifies a list of registration types to be used. The valid types are, Rigid, ScaleVersor3D, ScaleSkewVersor3D, Affine, and BSpline. Specifiying more than one in a comma separated list will initialize the next stage with the previous results. If registrationClass flag is used, it overrides this parameter setting. Transform Type [--transformType] : Specifies a list of registration types to be used. The valid types are, Rigid, ScaleVersor3D, ScaleSkewVersor3D, Affine, and BSpline. Specifiying more than one in a comma separated list will initialize the next stage with the previous results. If registrationClass flag is used, it overrides this parameter setting. Number Of Iterations [--numberOfIterations] : The maximum number of iterations to try before failing to converge. Use an explicit limit like 500 or 1000 to manage risk of divergence Default value: 1500 Number Of Samples [--numberOfSamples] : The number of voxels sampled for mutual information computation. Increase this for a slower, more careful fit. You can also limit the sampling focus with ROI masks and ROIAUTO mask generation. Default value: 100000 Minimum Step Size [--minimumStepSize] : Each step in the optimization takes steps at least this big. When none are possible, registration is complete. Default value: 0.005 Transform Scale [--translationScale] : How much to scale up changes in position compared to unit rotational changes in radians -- decrease this to put more rotation in the search pattern. Default value: 1000.0 Reproportion Scale [--reproportionScale] : ScaleVersor3D 'Scale' compensation factor. Increase this to put more rescaling in a ScaleVersor3D or ScaleSkewVersor3D search pattern. 1.0 works well with a translationScale of 1000.0 Default value: 1.0 Skew Scale [--skewScale] : ScaleSkewVersor3D Skew compensation factor. Increase this to put more skew in a ScaleSkewVersor3D search pattern. 1.0 works well with a translationScale of 1000.0 Default value: 1.0 Number Of Grid Subdivisions [--splineGridSize] : The number of subdivisions of the BSpline Grid to be centered on the image space. Each dimension must have at least 3 subdivisions for the BSpline to be correctly computed. Default value: 14,10,12 Maximum B-Spline Displacement [--maxBSplineDisplacement] : Sets the maximum allowed displacements in image physical coordinates for BSpline control grid along each axis. A value of 0.0 indicates that the problem should be unbounded. NOTE: This only constrains the BSpline portion, and does not limit the displacement from the associated bulk transform. This can lead to a substantial reduction in computation time in the BSpline optimizer. Default value: 0.0 Advanced Output Settings File name for the rigid component of the estimated affine transform. Can be used to rigidly register the moving image to the fixed image. NOTE: This value is overwritten if either bsplineTransform or linearTransform is set. Stripped Output Transform [--strippedOutputTransform] : File name for the rigid component of the estimated affine transform. Can be used to rigidly register the moving image to the fixed image. NOTE: This value is overwritten if either bsplineTransform or linearTransform is set. Background Fill Value [--backgroundFillValue] : Background fill value for output image. Default value: 0.0 Inferior Cut Off From Center [--maskInferiorCutOffFromCenter] : For use with --useCenterOfHeadAlign (and --maskProcessingMode ROIAUTO): the cut-off below the image centers, in millimeters, Default value: 1000.0 Scale Output Values [--scaleOutputValues] : If true, and the voxel values do not fit within the minimum and maximum values of the desired outputVolumePixelType, then linearly scale the min/max output image voxel values to fit within the min/max range of the outputVolumePixelType. Default value: false Interpolation Mode [--interpolationMode] : Type of interpolation to be used when applying transform to moving volume. Options are Linear, NearestNeighbor, BSpline, or WindowedSinc Default value: Linear Control of Mask Processing What mode to use for using the masks. If ROIAUTO is choosen, then the mask is implicitly defined using a otsu forground and hole filling algorithm. The Region Of Interest mode (choose ROI) uses the masks to define what parts of the image should be used for computing the transform. Mask Processing Mode [--maskProcessingMode] : What mode to use for using the masks. If ROIAUTO is choosen, then the mask is implicitly defined using a otsu forground and hole filling algorithm. The Region Of Interest mode (choose ROI) uses the masks to define what parts of the image should be used for computing the transform. Default value: NOMASK Output Fixed Mask (ROIAUTO only) [--outputFixedVolumeROI] : The ROI automatically found in fixed image. Output Moving Mask (ROIAUTO only) [--outputMovingVolumeROI] : The ROI automatically found in moving image. Input Fixed Mask (ROI only) [--fixedBinaryVolume] : Fixed Image binary mask volume. Input Moving Mask (ROI only) [--movingBinaryVolume] : Moving Image binary mask volume. Special Input Image Parameters The index in the time series for the 3D fixed image to fit, if 4-dimensional. Fixed Image Time Index [--fixedVolumeTimeIndex] : The index in the time series for the 3D fixed image to fit, if 4-dimensional. Default value: 0 Moving Image Time Index [--movingVolumeTimeIndex] : The index in the time series for the 3D moving image to fit, if 4-dimensional. Default value: 0 Median Filter Size [--medianFilterSize] : The radius for the optional MedianImageFilter preprocessing in all 3 directions. Default value: 0,0,0 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. Default value: false Number of Histogram Bins [--numberOfHistogramBins] : the number of histogram levels Default value: 50 Number of Match Points [--numberOfMatchPoints] : the number of match points Default value: 10 Registration Debugging Parameters This is a 5x speed advantage at the expense of requiring much more memory. Only relevant when transformType is BSpline. Caching BSpline Weights Mode [--useCachingOfBSplineWeightsMode] : This is a 5x speed advantage at the expense of requiring much more memory. Only relevant when transformType is BSpline. Default value: ON Explicit PDF Derivatives Mode [--useExplicitPDFDerivativesMode] : Using mode AUTO means OFF for BSplineDeformableTransforms and ON for the linear transforms. The ON alternative uses more memory to sometimes do a better job. Default value: AUTO ROIAuto Dilate Size [--ROIAutoDilateSize] : This flag is only relavent when using ROIAUTO mode for initializing masks. It defines the final dilation size to capture a bit of background outside the tissue region. At setting of 10mm has been shown to help regularize a BSpline registration type so that there is some background constraints to match the edges of the head better. Default value: 0.0 Relaxation Factor [--relaxationFactor] : Internal debugging parameter, and should probably never be used from the command line. This will be removed in the future. Default value: 0.5 Maximum Step Size [--maximumStepSize] : Internal debugging parameter, and should probably never be used from the command line. This will be removed in the future. Default value: 0.2 Failure Exit Code [--failureExitCode] : If the fit fails, exit with this status code. (It can be used to force a successfult exit status of (0) if the registration fails due to reaching the maximum number of iterations. Default value: -1 Write Transform On Failure [--writeTransformOnFailure] : Flag to save the final transform even if the numberOfIterations are reached without convergence. (Intended for use when --failureExitCode 0 ) Default value: 0 debugNumberOfThreads [--debugNumberOfThreads] : Explicitly specify the maximum number of threads to use. Default value: -1 Debug option [--debugLevel] : Display debug messages, and produce debug intermediate results. 0=OFF, 1=Minimal, 10=Maximum debugging. Default value: 0 Risky Expert-only Parameters A bit vector to permit linear transform parameters to vary under optimization. The vector order corresponds with transform parameters, and beyond the end ones fill in as a default. For instance, you can choose to rotate only in x (pitch) with 1,0,0; this is mostly for expert use in turning on and off individual degrees of freedom in rotation, translation or scaling without multiplying the number of transform representations; this trick is probably meaningless when tried with the general affine transform. Selective Permission for Transform Parameters to Vary [--permitParameterVariation] : A bit vector to permit linear transform parameters to vary under optimization. The vector order corresponds with transform parameters, and beyond the end ones fill in as a default. For instance, you can choose to rotate only in x (pitch) with 1,0,0; this is mostly for expert use in turning on and off individual degrees of freedom in rotation, translation or scaling without multiplying the number of transform representations; this trick is probably meaningless when tried with the general affine transform.

User Interface User Interface

Development

Notes from the Developer(s)

This is a thin wrapper program around the BRAINSFitHelper class in BRAINSCommonLib. The BRAINSFitHelper class is intended to allow all the functionality of BRAINSFit to be easily incorporated into another program by including a single header file, linking against the BRAINSCommonLib library, and adding code similar to the following to your application:

    typedef itk::BRAINSFitHelper HelperType;
    HelperType::Pointer myHelper=HelperType::New();
    myHelper->SetTransformType(localTransformType);
    myHelper->SetFixedVolume(extractFixedVolume);
    myHelper->SetMovingVolume(extractMovingVolume);
    myHelper->StartRegistration();
    currentGenericTransform=myHelper->GetCurrentGenericTransform();
    MovingVolumeType::ConstPointer preprocessedMovingVolume = myHelper->GetPreprocessedMovingVolume();

/*  Optional member functions that can also be set */
    myHelper->SetHistogramMatch(histogramMatch);
    myHelper->SetNumberOfMatchPoints(numberOfMatchPoints);
    myHelper->SetFixedBinaryVolume(fixedMask);
    myHelper->SetMovingBinaryVolume(movingMask);
    myHelper->SetPermitParameterVariation(permitParameterVariation);
    myHelper->SetNumberOfSamples(numberOfSamples);
    myHelper->SetNumberOfHistogramBins(numberOfHistogramBins);
    myHelper->SetNumberOfIterations(numberOfIterations);
    myHelper->SetMaximumStepLength(maximumStepSize);
    myHelper->SetMinimumStepLength(minimumStepSize);
    myHelper->SetRelaxationFactor(relaxationFactor);
    myHelper->SetTranslationScale(translationScale);
    myHelper->SetReproportionScale(reproportionScale);
    myHelper->SetSkewScale(skewScale);
    myHelper->SetUseExplicitPDFDerivativesMode(useExplicitPDFDerivativesMode);
    myHelper->SetUseCachingOfBSplineWeightsMode(useCachingOfBSplineWeightsMode);
    myHelper->SetBackgroundFillValue(backgroundFillValue);
    myHelper->SetInitializeTransformMode(localInitializeTransformMode);
    myHelper->SetMaskInferiorCutOffFromCenter(maskInferiorCutOffFromCenter);
    myHelper->SetCurrentGenericTransform(currentGenericTransform);
    myHelper->SetSplineGridSize(splineGridSize);
    myHelper->SetCostFunctionConvergenceFactor(costFunctionConvergenceFactor);
    myHelper->SetProjectedGradientTolerance(projectedGradientTolerance);
    myHelper->SetMaxBSplineDisplacement(maxBSplineDisplacement);
    myHelper->SetDisplayDeformedImage(UseDebugImageViewer);
    myHelper->SetPromptUserAfterDisplay(PromptAfterImageSend);
    myHelper->SetDebugLevel(debugLevel);
    if(debugLevel > 7 )
      {
      myHelper->PrintCommandLine(true,"BF");
      }

Dependencies

BRAINSFit depends on Slicer3 (for the SlicerExecutionModel support) and ITK. BRAINSFit depends on the BRAINSCommonLib library

Tests

Nightly testing of the development head can be found at: http://testing.psychiatry.uiowa.edu/CDash

Known bugs

Links to known bugs and feature requests are listed at:

• http://www.nitrc.org/projects/multimodereg/

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:

• by NITRC

More Information

Acknowledgment

This research was supported by funding from grants NS050568 and NS40068 from the National Institute of Neurological Disorders and Stroke and grants MH31593, MH40856, from the National Institute of Mental Health.

References

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