Documentation/Nightly/Modules/BRAINSFit

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

For the stable Slicer documentation, visit the 4.8 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
Contributor1: Kent Williams, UIOWA
Contributor2: Vincent Magnotta, UIOWA
Contributor3: Andriy Fedorov, BWH
Contact: Hans Johnson,

University of Iowa  
Surgical Planning Laboratory  

Module Description

Register a three-dimensional volume to a reference volume (Mattes Mutual Information by default). Full documentation avalable here: http://wiki.slicer.org/slicerWiki/index.php/Documentation/4.1/Modules/BRAINSFit. Method described in BRAINSFit: Mutual Information Registrations of Whole-Brain 3D Images, Using the Insight Toolkit, Johnson H.J., Harris G., Williams K., The Insight Journal, 2007. http://hdl.handle.net/1926/1291

Use Cases

Most frequently used for these scenarios:

  1. Same Subject: Longitudinal

For this case we're registering a baseline T1 scan with a follow-up T1 scan on the same subject a year later. The two images are available on the Midas site as test.nii.gz and test2.nii.gz

First, set the fixed and moving volumes:

--fixedVolume test.nii.gz \
--movingVolume test2.nii.gz \

Next, set the output transform and volume:

--outputVolume testT1LongRegFixed.nii.gz \
--outputTransform longToBase.xform \

Since the input scans are of the same subject we can assume very little has changed in the last year, so we'll use a Rigid registration.

--transformType Rigid \

Note If the registration is poor or there are reasons to expect anatomical changes (tumor growth, rapid disease progression, etc.) additional transforms may be needed. In that case they can be added in a comma separated list, such as "Rigid,ScaleVersor3D,ScaleSkewVersor3D,Affine,BSpline". Available methods are:

  • Rigid
  • ScaleVersor3D
  • ScaleSkewVersor3D
  • Affine
  • BSpline
Example: multiple registration methods
--transformType Rigid,ScaleVersor3D,ScaleSkewVersor3D,Affine,BSpline \

The scans are the same modality so we'll use --histogramMatch to match the intensity profiles as this tends to help the registration. If there are lesions or tumors that vary between images this may not be a good idea, since it will make it harder to detect differences between the images.

--histogramMatch \

To start with the best possible initial alignment we use --initializeTransformMode. The available transform modes are:

  • useCenterOfHeadAlign
  • useCenterOfROIAlign
  • useMomentsAlign
  • useGeometryAlign

We're working with human heads so we pick useCenterOfHeadAlign, which detects the center of head even with varying amounts of neck or shoulders present.

--initializeTransformMode useCenterOfHeadAlign \

ROI masks normally improve registration but we haven't generated any so we turn on --maskProcessingMode ROIAUTO (other options are NOMASK and ROI).

--maskProcessingMode ROIAUTO \

The registration generally performs better if we include some background in the mask to make the tissue boundary very clear. The parameter that expands the mask outside the brain is ROIAutoDilateSize (under "Registration Debugging Parameters" if using the GUI). These values are in millimeters and a good starting value is 3.

--ROIAutoDilateSize 3 \

Lastly, we set the interpolation mode to be Linear, which is a decent tradeoff between quality and speed. If the best possible interpolation is needed regardless of processing time, select WindowedSync instead.

--interpolationMode Linear

The full command is:

BRAINSFit --fixedVolume test.nii.gz \
--movingVolume test2.nii.gz \
--outputVolume testT1LongRegFixed.nii.gz \
--outputTransform longToBase.xform \
--transformType Rigid \
--histogramMatch \
--initializeTransformMode useCenterOfHeadAlign \
--maskProcessingMode ROIAUTO \
--ROIAutoDilateSize 3 \
--interpolationMode Linear
Longitudinal Checkerboard Before registration
Longitudinal Checkerboard After registration
  1. Same Subject: MultiModal

For this use case we're registering a T1 scan with a T2 scan collected in the same session. The two images are again available on the Midas site as test.nii.gz and standard.nii.gz

First we set the fixed and moving volumes as well as the output transform and output volume names.

--fixedVolume test.nii.gz \
--movingVolume standard.nii.gz \
--outputVolume testT2RegT1.nii.gz \
--outputTransform T2ToT1.xform \

Since these are the same subject, same session we'll use a Rigid registration.

--transformType Rigid \

The scans are different modalities so we absolutely DO NOT want to use --histogramMatch to match the intensity profiles! This would try to map T2 intensities into T1 intensities resulting in an image that is neither, and hence useless.

To start with the best possible initial alignment we use --initializeTransformMode. We're working with human heads so we pick useCenterOfHeadAlign, which detects the center of head even with varying amounts of neck or shoulders present.

--initializeTransformMode useCenterOfHeadAlign \

ROI masks normally improve registration but we haven't generated any so we turn on --maskProcessingMode ROIAUTO (other options are NOMASK and ROI).

--maskProcessingMode ROIAUTO \

The registration generally performs better if we include some background in the mask to make the tissue boundary very clear. The parameter that expands the mask outside the brain is ROIAutoDilateSize (under "Registration Debugging Parameters" if using the GUI). These values are in millimeters and a good starting value is 3.

--ROIAutoDilateSize 3 \

Lastly, we set the interpolation mode to be Linear, which is a decent tradeoff between quality and speed. If the best possible interpolation is needed regardless of processing time, select WindowedSync instead.

--interpolationMode Linear

The full command is:

BRAINSFit --fixedVolume test.nii.gz \
--movingVolume standard.nii.gz \
--outputVolume testT2RegT1.nii.gz \
--outputTransform T2ToT1.xform \
--transformType Rigid \
--initializeTransformMode useCenterOfHeadAlign \
--maskProcessingMode ROIAUTO \
--ROIAutoDilateSize 3 \
--interpolationMode Linear
Multimodal Checkerboard Before registration
Multimodal Checkerboard After registration
  • Mouse Registration

Here we'll register brains from two different mice together. The fixed and moving mouse brains used in this example are available on the Midas site as mouseFixed.nii.gz and mouseMoving.nii.gz.

First we set the fixed and moving volumes as well as the output transform and output volume names.

--fixedVolume mouseFixed.nii.gz \
--movingVolume mouseMoving.nii.gz \
--outputVolume movingRegFixed.nii.gz \
--outputTransform movingToFixed.xform \

Since the subjects are different we are going to use transforms all the way through BSpline. Note Building up transforms one type at a time can't hurt and might help, so we're including all transforms from Rigid through BSpline in the transformType parameter.

--transformType Rigid,ScaleVersor3D,ScaleSkewVersor3D,Affine,BSpline \

The scans are the same modality so we'll use --histogramMatch.

--histogramMatch \

To start with the best possible initial alignment we use --initializeTransformMode but we aren't working with human heads this time, so we can't pick useCenterOfHeadAlign! Instead we pick useMomentsAlign which does a reasonable job of selecting the centers of mass.

--initializeTransformMode useMomentsAlign \

ROI masks normally improve registration but we haven't generated any so we turn on --maskProcessingMode ROIAUTO.

--maskProcessingMode ROIAUTO \

Since the mouse brains are much smaller than human brains there are a few advanced parameters we'll need to tweak, ROIAutoClosingSize and ROIAutoDilateSize (both under Registration Debugging Parameters if using the GUI). These values are in millimeters and a good starting value for mice is 0.9.

--ROIAutoClosingSize 0.9 \
--ROIAutoDilateSize 0.9 \

Lastly, we set the interpolation mode to be Linear, which is a decent tradeoff between quality and speed. If the best possible interpolation is needed regardless of processing time, select WindowedSync instead.

--interpolationMode Linear

The full command is:

BRAINSFit --fixedVolume mouseFixed.nii.gz \
--movingVolume mouseMoving.nii.gz \
--outputVolume movingRegFixed.nii.gz \
--outputTransform movingToFixed.xform \
--transformType Rigid,ScaleVersor3D,ScaleSkewVersor3D,Affine,BSpline \
--histogramMatch \
--initializeTransformMode useMomentsAlign \
--maskProcessingMode ROIAUTO \
--ROIAutoClosingSize 0.9 \
--ROIAutoDilateSize 0.9 \
--interpolationMode Linear
Mouse Checkerboard Before registration
Mouse Checkerboard After registration

Tutorials

TODO

Panels and their use

Parameters:
  • Input Images:
    • Fixed Image Volume (fixedVolume): Input fixed image (the moving image will be transformed into this image space).
    • Moving Image Volume (movingVolume): Input moving image (this image will be transformed into the fixed image space).
    • Percentage Of Samples (samplingPercentage): Fraction of voxels of the fixed image that will be used for registration. The number has to be larger than zero and less or equal to one. Higher values increase the computation time but may give more accurate results. You can also limit the sampling focus with ROI masks and ROIAUTO mask generation. The default is 0.002 (use approximately 0.2% of voxels, resulting in 100000 samples in a 512x512x192 volume) to provide a very fast registration in most cases. Typical values range from 0.01 (1%) for low detail images to 0.2 (20%) for high detail images.
    • B-Spline Grid Size (splineGridSize): Number of BSpline grid subdivisions along each axis of the fixed image, centered on the image space. Values must be 3 or higher for the BSpline to be correctly computed.
  • Output Settings (At least one output must be specified):
    • Slicer Linear Transform (linearTransform): (optional) Output estimated transform - in case the computed transform is not BSpline. NOTE: You must set at least one output object (transform and/or output volume).
    • Slicer BSpline Transform (bsplineTransform): (optional) Output estimated transform - in case the computed transform is BSpline. NOTE: You must set at least one output object (transform and/or output volume).
    • Output Image Volume (outputVolume): (optional) Output image: the moving image warped to the fixed image space. NOTE: You must set at least one output object (transform and/or output volume).
  • Transform Initialization Settings: Options for initializing transform parameters.
    • Initialization transform (initialTransform): Transform to be applied to the moving image to initialize the registration. This can only be used if Initialize Transform Mode is Off.
    • Initialize Transform Mode (initializeTransformMode): Determine how to initialize the transform center. useMomentsAlign assumes that the center of mass of the images represent similar structures. useCenterOfHeadAlign attempts to use the top of head and shape of neck to drive a center of mass estimate. useGeometryAlign on assumes that the center of the voxel lattice of the images represent similar structures. Off assumes that the physical space of the images are close. This flag is mutually exclusive with the Initialization transform.
  • Registration Phases (Check one or more, executed in order listed): Each of the registration phases will be used to initialize the next phase
    • Rigid (6 DOF) (useRigid): Perform a rigid registration as part of the sequential registration steps. This family of options overrides the use of transformType if any of them are set.
    • Rigid+Scale(7 DOF) (useScaleVersor3D): Perform a ScaleVersor3D registration as part of the sequential registration steps. This family of options overrides the use of transformType if any of them are set.
    • Rigid+Scale+Skew(10 DOF) (useScaleSkewVersor3D): Perform a ScaleSkewVersor3D registration as part of the sequential registration steps. This family of options overrides the use of transformType if any of them are set.
    • Affine(12 DOF) (useAffine): Perform an Affine registration as part of the sequential registration steps. This family of options overrides the use of transformType if any of them are set.
    • BSpline (>27 DOF) (useBSpline): Perform a BSpline registration as part of the sequential registration steps. This family of options overrides the use of transformType if any of them are set.
    • SyN (useSyN): Perform a SyN registration as part of the sequential registration steps. This family of options overrides the use of transformType if any of them are set.
    • Composite (many DOF) (useComposite): Perform a Composite registration as part of the sequential registration steps. This family of options overrides the use of transformType if any of them are set.
  • Image Mask and Pre-Processing:
    • Masking Option (maskProcessingMode): Specifies a mask to only consider a certain image region for the registration. If ROIAUTO is chosen, then the mask is computed using Otsu thresholding and hole filling. If ROI is chosen then the mask has to be specified as in input.
    • (ROI) Masking input fixed (fixedBinaryVolume): Fixed Image binary mask volume, required if Masking Option is ROI. Image areas where the mask volume has zero value are ignored during the registration.
    • (ROI) Masking input moving (movingBinaryVolume): Moving Image binary mask volume, required if Masking Option is ROI. Image areas where the mask volume has zero value are ignored during the registration.
    • (ROIAUTO) Output fixed mask (outputFixedVolumeROI): ROI that is automatically computed from the fixed image. Only available if Masking Option is ROIAUTO. Image areas where the mask volume has zero value are ignored during the registration.
    • (ROIAUTO) Output moving mask (outputMovingVolumeROI): ROI that is automatically computed from the moving image. Only available if Masking Option is ROIAUTO. Image areas where the mask volume has zero value are ignored during the registration.
    • Define BSpline grid over the ROI bounding box (useROIBSpline): If enabled then the bounding box of the input ROIs defines the BSpline grid support region. Otherwise the BSpline grid support region is the whole fixed image.
    • Histogram Match (histogramMatch): Apply histogram matching operation for the input images to make them more similar. This is suitable for images of the same modality that may have different brightness or contrast, but the same overall intensity profile. Do NOT use if registering images from different modalities.
    • Median Filter Size (medianFilterSize): Apply median filtering to reduce noise in the input volumes. The 3 values specify the radius for the optional MedianImageFilter preprocessing in all 3 directions (in voxels).
    • Remove Intensity Outliers value at one tail (removeIntensityOutliers): Remove very high and very low intensity voxels from the input volumes. The parameter specifies the half percentage to decide outliers of image intensities. The default value is zero, which means no outlier removal. If the value of 0.005 is given, the 0.005% of both tails will be thrown away, so 0.01% of intensities in total would be ignored in the statistic calculation.
  • Advanced Output Settings:
    • Fixed Image Volume 2 (fixedVolume2): Input fixed image that will be used for multimodal registration. (the moving image will be transformed into this image space).
    • Moving Image Volume2 (movingVolume2): Input moving image that will be used for multimodal registration(this image will be transformed into the fixed image space).
    • Output Image Pixel Type (outputVolumePixelType): Data type for representing a voxel of the Output Volume.
    • Background Fill Value (backgroundFillValue): This value will be used for filling those areas of the output image that have no corresponding voxels in the input moving image.
    • 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.
    • Interpolation Mode (interpolationMode): Type of interpolation to be used when applying transform to moving volume. Options are Linear, NearestNeighbor, BSpline, WindowedSinc, Hamming, Cosine, Welch, Lanczos, or ResampleInPlace. The ResampleInPlace option will create an image with the same discrete voxel values and will adjust the origin and direction of the physical space interpretation.
  • Advanced Optimization Settings:
    • Max Iterations (numberOfIterations): The maximum number of iterations to try before stopping the optimization. When using a lower value (500-1000) then the registration is forced to terminate earlier but there is a higher risk of stopping before an optimal solution is reached.
    • Maximum Step Length (maximumStepLength): Starting step length of the optimizer. In general, higher values allow for recovering larger initial misalignments but there is an increased chance that the registration will not converge.
    • Minimum Step Length (minimumStepLength): Each step in the optimization takes steps at least this big. When none are possible, registration is complete. Smaller values allows the optimizer to make smaller adjustments, but the registration time may increase.
    • Relaxation Factor (relaxationFactor): Specifies how quickly the optimization step length is decreased during registration. The value must be larger than 0 and smaller than 1. Larger values result in slower step size decrease, which allow for recovering larger initial misalignments but it increases the registration time and the chance that the registration will not converge.
    • Transform Scale (translationScale): How much to scale up changes in position (in mm) compared to unit rotational changes (in radians) -- decrease this to allow for more rotation in the search pattern.
    • Reproportion Scale (reproportionScale): ScaleVersor3D 'Scale' compensation factor. Increase this to allow for more rescaling in a ScaleVersor3D or ScaleSkewVersor3D search pattern. 1.0 works well with a translationScale of 1000.0
    • Skew Scale (skewScale): ScaleSkewVersor3D Skew compensation factor. Increase this to allow for more skew in a ScaleSkewVersor3D search pattern. 1.0 works well with a translationScale of 1000.0
    • Maximum B-Spline Displacement (maxBSplineDisplacement): Maximum allowed displacements in image physical coordinates (mm) 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.
  • Expert-only Parameters:
    • Fixed Image Time Index (fixedVolumeTimeIndex): The index in the time series for the 3D fixed image to fit. Only allowed if the fixed input volume is 4-dimensional.
    • Moving Image Time Index (movingVolumeTimeIndex): The index in the time series for the 3D moving image to fit. Only allowed if the moving input volume is 4-dimensional
    • Histogram bin count (numberOfHistogramBins): The number of histogram levels used for mutual information metric estimation.
    • Histogram match point count (numberOfMatchPoints): Number of histogram match points used for mutual information metric estimation.
    • Cost Metric (costMetric): The cost metric to be used during fitting. Defaults to MMI. Options are MMI (Mattes Mutual Information), MSE (Mean Square Error), NC (Normalized Correlation), MC (Match Cardinality for binary images)
    • Inferior Cut Off From Center (maskInferiorCutOffFromCenter): If Initialize Transform Mode is set to useCenterOfHeadAlign or Masking Option is ROIAUTO then this value defines the how much is cut of from the inferior part of the image. The cut-off distance is specified in millimeters, relative to the image center. If the value is 1000 or larger then no cut-off performed.
    • ROIAuto Dilate Size (ROIAutoDilateSize): This flag is only relevant when using ROIAUTO mode for initializing masks. It defines the final dilation size to capture a bit of background outside the tissue region. A 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.
    • ROIAuto Closing Size (ROIAutoClosingSize): This flag is only relevant when using ROIAUTO mode for initializing masks. It defines the hole closing size in mm. It is rounded up to the nearest whole pixel size in each direction. The default is to use a closing size of 9mm. For mouse data this value may need to be reset to 0.9 or smaller.
    • Number Of Samples (numberOfSamples): The number of voxels sampled for mutual information computation. Increase this for higher accuracy, at the cost of longer computation time.\nNOTE that it is suggested to use samplingPercentage instead of this option. However, if set to non-zero, numberOfSamples overwrites the samplingPercentage option.
    • Stripped Output Transform (strippedOutputTransform): Rigid component of the estimated affine transform. Can be used to rigidly register the moving image to the fixed image. NOTE: This value is overridden if either bsplineTransform or linearTransform is set.
    • Transform Type (transformType): Specifies a list of registration types to be used. The valid types are, Rigid, ScaleVersor3D, ScaleSkewVersor3D, Affine, BSpline and SyN. Specifying 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.
    • Output Transform (outputTransform): (optional) Filename to which save the (optional) estimated transform. NOTE: You must select either the outputTransform or the outputVolume option.
    • Pass warped moving image to BSpline registration filter (initializeRegistrationByCurrentGenericTransform): If this flag is ON, the current generic composite transform, resulted from the linear registration stages, is set to initialize the follow nonlinear registration process. However, by the default behaviour, the moving image is first warped based on the existant transform before it is passed to the BSpline registration filter. It is done to speed up the BSpline registration by reducing the computations of composite transform Jacobian.
    • writes the output registration transforms in single precision (writeOutputTransformInFloat): By default, the output registration transforms (either the output composite transform or each transform component) are written to the disk in double precision. If this flag is ON, the output transforms will be written in single (float) precision. It is especially important if the output transform is a displacement field transform, or it is a composite transform that includes several displacement fields.
  • Debugging Parameters:
    • 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.
    • 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 )
    • Number Of Threads (numberOfThreads): Explicitly specify the maximum number of threads to use. (default is auto-detected)
    • Debug option (debugLevel): Display debug messages, and produce debug intermediate results. 0=OFF, 1=Minimal, 10=Maximum debugging.
    • Set Sampling Strategy (metricSamplingStrategy): It defines the method that registration filter uses to sample the input fixed image. Only Random is supported for now.
    • Log File Report (logFileReport): A file to write out final information report in CSV file: MetricName,MetricValue,FixedImageName,FixedMaskName,MovingImageName,MovingMaskName


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

General Registration module panel

Similar Modules

Legacy

References

Information for Developers