Difference between revisions of "Modules:BRAINSFit"

From Slicer Wiki
Jump to: navigation, search
m (Text replacement - "https?:\/\/(?:www|wiki)\.slicer\.org\/slicerWiki\/index\.php\/([^ ]+) " to "https://www.slicer.org/wiki/$1 ")
 
(49 intermediate revisions by 7 users not shown)
Line 8: Line 8:
  
 
{|
 
{|
−
|[[Image:BRAINSFitUI.png|thumb|280px|User Interface]]
+
| [[Image:Before.png|thumb|280px|Before registration]]
 +
|-
 +
|  [[Image:After.png|thumb|280px|AfterRegistration]]
 
|}
 
|}
 +
 +
 +
=== Example Applications:  from the Registration Library ===
 +
{|
 +
|[[Image:RegLib_C02_Thumb.png|160px|lleft|Registration Library Case 02: Brain Affine|link=http://www.na-mic.org/Wiki/index.php/Projects:RegistrationLibrary:RegLib_C02]]
 +
|[http://www.na-mic.org/Wiki/index.php/Projects:RegistrationLibrary:RegLib_C02 Affine Intra Subject Brain]
 +
|-
 +
|[[Image:RegLib_C14_Thumb_MRI.png|160px|lleft|Registration Library Case 14: PET|link=http://www.na-mic.org/Wiki/index.php/Projects:RegistrationLibrary:RegLib_C14]]
 +
|[http://www.na-mic.org/Wiki/index.php/Projects:RegistrationLibrary:RegLib_C14 PET Brain]
 +
|-
 +
|[[Image:RegLib_C29_thumb4.png|160px|lleft||Registration Library Case 29: DTI nonrigid|link=http://www.na-mic.org/Wiki/index.php/Projects:RegistrationLibrary:RegLib_C29]]
 +
|[http://www.na-mic.org/Wiki/index.php/Projects:RegistrationLibrary:RegLib_C29 Diffusion MRI/DTI]
 +
|}
 +
* And many more, see the [http://na-mic.org/Wiki/index.php/Projects:RegistrationDocumentation:RegLibTable '''Slicer Registration Library''']
 +
(you can sort the table by method)
  
 
== General Information ==
 
== General Information ==
Line 17: Line 34:
  
 
Category: Registration
 
Category: Registration
 +
 +
  
 
===Authors, Collaborators & Contact===
 
===Authors, Collaborators & Contact===
−
* Author1: Hans Johnson, University of Iowa
+
 
−
* Contributor1: Kent WIlliams, University of Iowa
+
Author: Hans J. Johnson, hans-johnson -at- uiowa.edu, http://www.psychiatry.uiowa.edu
−
* Contact: Hans Johnson, hans-johson at 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===
 
===Module Description===
−
BRAINSFit is a program for mutual information registration of brain imaging data using ITK classes. It is based on an example program included in the ITK distribution,
+
 
 +
{| style="color:green" border="1"
 +
|Program title || BRAINSFit
 +
|-
 +
|Program description || Uses the Mattes Mutual Registration algorithm to register a three-dimensional volume to a reference volume. 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
 +
|-
 +
|Program version || 3.0.0
 +
|-
 +
|Program documentation-url || https://www.slicer.org/wiki/Modules:BRAINSFit
 +
|- |}
  
 
Insight/Examples/Registration/ImageRegistration8.cxx
 
Insight/Examples/Registration/ImageRegistration8.cxx
Line 37: Line 66:
 
*Defined the command line parameters using tools from the Slicer [ 3] program, in order to conform to the Slicer3 Execution model.
 
*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.
 
Added the ability to write output images in any ITK-supported scalar image format.
−
*Through extensive testing as part of the BRAINS2 application suite, determined reasonable defaults for registration algorithm parameters.
+
*Extensive testing as part of the BRAINS2 application suite, determined reasonable defaults for registration algorithm parameters. http://testing.psychiatry.uiowa.edu/CDash/
  
 
== Usage ==
 
== Usage ==
Line 53: Line 82:
 
This module is especially appropriate for these use cases:
 
This module is especially appropriate for these use cases:
  
−
* Use Case 1:
+
* '''''Use Case 1: Same Subject: Longitudinal'''''
−
* Use Case 2:
 
  
−
Examples of the module in use:
+
For this use 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 again available in the Slicer3/Applications/CLI/BRAINSTools/BRAINSCommonLib/TestData directory as testT1.nii.gz and testT1Longitudinal.nii.gz
  
−
* Example 1
+
First we set the fixed and moving volumes as well as the output transform and output volume names.
−
* Example 2
+
<pre>
−
 
+
--fixedVolume testT1.nii.gz \
−
===Tutorials===
+
--movingVolume testT1Longitudinal.nii.gz \
−
 
+
--outputVolume testT1LongRegFixed.nii.gz \
−
Links to tutorials explaining how to use this module:
+
--outputTransform longToBase.xform \
−
 
+
</pre>
−
* Tutorial 1
+
Since these are the same subject and very little has likely changed in the last year we'll use a Rigid registration.  If the registration is poor or there are reasons to expect anatomical changes then additional transforms may be needed, in which case they can be added in a comma separated list, such as "Rigid,ScaleVersor3D,ScaleSkewVersor3D,Affine,BSpline".
−
** Data Set 1
+
<pre>
−
 
+
--transformType Rigid \
−
===Quick Tour of Features and Use===
+
</pre>
 +
The scans are the same modality so we'll use --histogramMatch to match the intensity profiles as this tends to help registration.  If there are lesions or tumors that vary between images this may not be a good idea, as it will make it harder to detect differences between the images. 
 +
<pre>
 +
--histogramMatch \
 +
</pre>
 +
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.
 +
<pre>
 +
--initializeTransformMode useCenterOfHeadAlign \
 +
</pre>
 +
ROI masks normally improve registration but we haven't generated any so we turn on --maskProcessingMode ROIAUTO. 
 +
<pre>
 +
--maskProcessingMode ROIAUTO \
 +
</pre>
 +
The registration generally performs better if we include some background in the mask that way the tissue boundary is 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 so a good starting value is 3. 
 +
<pre>
 +
--ROIAutoDilateSize 3 \
 +
</pre>
 +
Last 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 of linear.
 +
<pre>
 +
--interpolationMode Linear
 +
</pre>
  
−
A list panels in the interface, their features, what they mean, and how to use them. For instance:
+
The full command is:
 +
<pre>
 +
BRAINSFit --fixedVolume testT1.nii.gz \
 +
--movingVolume testT1Longitudinal.nii.gz \
 +
--outputVolume testT1LongRegFixed.nii.gz \
 +
--outputTransform longToBase.xform \
 +
--transformType Rigid \
 +
--histogramMatch \
 +
--initializeTransformMode useCenterOfHeadAlign \
 +
--maskProcessingMode ROIAUTO \
 +
--ROIAutoDilateSize 3 \
 +
--interpolationMode Linear
 +
</pre>
  
 
{|
 
{|
−
|
+
| [[Image:LongitudinalCheckerboardPreReg.png|thumb|180px|Longitudinal Checkerboard Before registration]]
 +
|  [[Image:LogitudinalCheckerboardPostReg.png|thumb|180px|Longitudinal Checkerboard After registration]]
 +
|}
  
−
  --returnparameterfile <std::string>
+
* '''''Use Case 2: Same Subject: MultiModal'''''
−
    Filename in which to write simple return parameters (int, float,
 
−
    int-vector, etc.) as opposed to bulk return parameters (image,
 
−
    geometry, transform, measurement, table).
 
  
−
  --processinformationaddress <std::string>
+
For this use case we're registering a T1 scan with a T2 scan collected in the same sesson.  The two images are again available in the Slicer3/Applications/CLI/BRAINSTools/BRAINSCommonLib/TestData directory as testT1.nii.gz and testT2.nii.gz
−
    Address of a structure to store process information (progress, abort,
 
−
    etc.). (default: 0)
 
  
−
  --xml
+
First we set the fixed and moving volumes as well as the output transform and output volume names.
−
    Produce xml description of command line arguments (default: 0)
+
<pre>
 +
--fixedVolume testT1.nii.gz \
 +
--movingVolume testT2.nii.gz \
 +
--outputVolume testT2RegT1.nii.gz \
 +
--outputTransform T2ToT1.xform \
 +
</pre>
 +
Since these are the same subject, same session we'll use a Rigid registration.
 +
<pre>
 +
--transformType Rigid \
 +
</pre>
 +
The scans are different modalities so we absolutely DO NOT want to use --histogramMatch to match the intensity profiles as this would try to map the T2 intensities into T1 intensities, resulting in an image that was neither, and hence useless.
  
−
  --echo
+
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.
−
    Echo the command line arguments (default: 0)
+
<pre>
 +
--initializeTransformMode useCenterOfHeadAlign \
 +
</pre>
 +
ROI masks normally improve registration but we haven't generated any so we turn on --maskProcessingMode ROIAUTO. 
 +
<pre>
 +
--maskProcessingMode ROIAUTO \
 +
</pre>
 +
The registration generally performs better if we include some background in the mask that way the tissue boundary is 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 so a good starting value is 3. 
 +
<pre>
 +
--ROIAutoDilateSize 3 \
 +
</pre>
 +
Last 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 of linear.
 +
<pre>
 +
--interpolationMode Linear
 +
</pre>
  
−
  -p,  --promptUser
+
The full command is:
−
    Prompt the user to hit enter each time an image is sent to the
+
<pre>
−
    DebugImageViewer (default: 0)
+
BRAINSFit --fixedVolume testT1.nii.gz \
 +
--movingVolume testT2.nii.gz \
 +
--outputVolume testT2RegT1.nii.gz \
 +
--outputTransform T2ToT1.xform \
 +
--transformType Rigid \
 +
--initializeTransformMode useCenterOfHeadAlign \
 +
--maskProcessingMode ROIAUTO \
 +
--ROIAutoDilateSize 3 \
 +
--interpolationMode Linear
 +
</pre>
  
−
  -G, --gui
+
{|
−
    Display intermediate image volumes for debugging. NOTE: This is not
+
| [[Image:T1T2PreRegCheckerboard.png|thumb|180px|Multimodal Checkerboard Before registration]]
−
    part of the standard build sytem, and probably does nothing on your
+
| [[Image:T1T2RegCheckerboard.png|thumb|180px|Multimodal Checkerboard After registration]]
−
    installation. (default: 0)
+
|}
  
−
  --projectedGradientTolerance <double>
+
* '''''Use Case 3: Mouse Registration'''''
−
    From itkLBFGSBOptimizer.h: Set/Get the ProjectedGradientTolerance.
 
−
    Algorithm terminates when the project gradient is below the tolerance.
 
−
    Default lbfgsb value is 1e-5, but 1e-4 seems to work well. (default:
 
−
    0.0001)
 
  
−
  --costFunctionConvergenceFactor <double>
+
Here we'll register brains from two different mice together. The fixed and moving mouse brains used in this example are available in the Slicer3/Applications/CLI/BRAINSTools/BRAINSCommonLib/TestData directory.  
−
    From itkLBFGSBOptimizer.h: Set/Get the CostFunctionConvergenceFactor.
 
−
    Algorithm terminates when the reduction in cost function is less than
 
−
    (factor * epsmcj) where epsmch is the machine precision. Typical
 
−
    values for factor: 1e+12 for low accuracy; 1e+7 for moderate accuracy
 
−
    and 1e+1 for extremely high accuracy.  1e+9 seems to work well.
 
−
    (default: 1e+09)
 
  
−
  --debugLevel <int>
+
First we set the fixed and moving volumes as well as the output transform and output volume names.
−
    Display debug messages, and produce debug intermediate results.  0=OFF
+
<pre>
−
    , 1=Minimal, 10=Maximum debugging. (default: 0)
+
--fixedVolume mouseFixed.nii.gz \
 +
--movingVolume mouseMoving.nii.gz \
 +
--outputVolume movingRegFixed.nii.gz \
 +
--outputTransform movingToFixed.xform \
 +
</pre>
 +
Since the subjects are different we are going to use transforms all the way through BSpline. Again, 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.   
 +
<pre>
 +
--transformType Rigid,ScaleVersor3D,ScaleSkewVersor3D,Affine,BSpline \
 +
</pre>
 +
The scans are the same modality so we'll use --histogramMatch. 
 +
<pre>
 +
--histogramMatch \
 +
</pre>
 +
To start with the best possible initial alignment we use --initializeTransformMode but we are't working with human heads so we can't pick useCenterOfHeadAlign. Instead we pick useMomentsAlign which does a reasonable job of selecting the centers of mass. 
 +
<pre>
 +
--initializeTransformMode useMomentsAlign \
 +
</pre>
 +
ROI masks normally improve registration but we haven't generated any so we turn on --maskProcessingMode ROIAUTO. 
 +
<pre>
 +
--maskProcessingMode ROIAUTO \
 +
</pre>
 +
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 so a good starting value for mice is 0.9. 
 +
<pre>
 +
--ROIAutoClosingSize 0.9 \
 +
--ROIAutoDilateSize 0.9 \
 +
</pre>
 +
Last 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 of linear.
 +
<pre>
 +
--interpolationMode Linear
 +
</pre>
  
−
  --debugNumberOfThreads <int>
+
The full command is:
−
    Explicitly specify the maximum number of threads to use. (default: -1)
+
<pre>
 +
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
 +
</pre>
  
−
  --writeTransformOnFailure
+
{|
−
    Flag to save the final transform even if the numberOfIterations are
+
|  [[Image:MouseCheckerboardPreRegistration.png|thumb|180px|Mouse Checkerboard Before registration]]
−
    reached without convergence. (Intended for use when --failureExitCode
+
|  [[Image:MouseCheckerboardPostRegistration.png|thumb|180px|Mouse Checkerboard After registration]]
−
    0 ) (default: 0)
+
|}
  
−
  --failureExitCode <int>
+
<!--===Tutorials===
−
    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: -1)
 
  
−
  --maximumStepSize <double>
+
Links to tutorials explaining how to use this module:
−
    Internal debugging parameter, and should probably never be used from
 
−
    the command line.  This will be removed in the future. (default: 0.2)
 
  
−
  --relaxationFactor <double>
+
* Tutorial 1
−
    Internal debugging parameter, and should probably never be used from
+
** Data Set 1
−
    the command line.  This will be removed in the future. (default: 0.5)
 
  
−
  --useExplicitPDFDerivativesMode <AUTO|ON|OFF>
+
-->
−
    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: AUTO)
 
  
−
  --useCachingOfBSplineWeightsMode <ON|OFF>
+
===Quick Tour of Features and Use===
−
    This is a 5x speed advantage at the expense of requiring much more
 
−
    memory.  Only relevant when transformType is BSpline. (default: ON)
 
  
−
  --movingVolumeOrigin <std::vector<int>>
+
This section was partially generated with a [http://svn.slicer.org/Slicer4/trunk/Scripts/SEMToMediaWiki.py python script to convert Slicer Execution Model xml files into MediaWiki compatible documentation]
−
    The coordinates of the origin of the moving image. This will
 
−
    over-ride the information read from disk and is VERY DANGEROUS.
 
−
    (default: 0,0,0)
 
  
−
  --fixedVolumeOrigin <std::vector<int>>
+
{|
−
    The coordinates of the origin of the fixed image. This will over-ride
+
|
−
    the information read from disk and is VERY DANGEROUS. (default: 0,0
+
* <span style="color:blue">'''''Input Parameters'''''</span>:  
−
    ,0)
+
** <span style="color:green">'''Fixed Image Volume'''</span> [<span style="color:orange">--fixedVolume</span>] : The fixed image for registration by mutual information optimization.
 +
** <span style="color:green">'''Moving Image Volume'''</span> [<span style="color:orange">--movingVolume</span>] : The moving image for registration by mutual information optimization.
  
−
  --permitParameterVariation <std::vector<int>>
+
* <span style="color:blue">'''''Registration phases to use'''''</span>: Parameters that define which registration steps to use.
−
    A bit vector to permit linear transform parameters to vary under
+
** <span style="color:green">'''Initialize with previously generated transform'''</span> [<span style="color:orange">--initialTransform</span>] : Filename of transform used to initialize the registration.  This CAN NOT be used with either CenterOfHeadLAlign, MomentsAlign, GeometryAlign, or initialTransform file.
−
    optimization.  The vector order corresponds with transform parameters,
+
** <span style="color:green">'''Intitialze Transform Mode'''</span> [<span style="color:orange">--initializeTransformMode</span>] : Determine how to initialize the transform center.  GeometryAlign on assumes that the center of the voxel lattice of the images represent similar structures.  MomentsAlign 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.  Off assumes that the physical space of the images are close, and that centering in terms of the image Origins is a good starting point.  This flag is mutually exclusive with the initialTransform flag. ''Default value: Off''
−
    and beyond the end ones fill in as a default.  For instance, you can
+
** <span style="color:green">'''Include Rigid registration phase'''</span> [<span style="color:orange">--useRigid</span>] : 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''
−
    choose to rotate only in x (pitch) with 1,0,0; this is mostly for
+
** <span style="color:green">'''Include ScaleVersor3D registration phase'''</span> [<span style="color:orange">--useScaleVersor3D</span>] : 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''
−
    expert use in turning on and off individual degrees of freedom in
+
** <span style="color:green">'''Include ScaleSkewVersor3D registration phase'''</span> [<span style="color:orange">--useScaleSkewVersor3D</span>] : Perform a ScaleSkewVersor3D 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''
−
    rotation, translation or scaling without multiplying the number of
+
** <span style="color:green">'''Include Affine registration phase'''</span> [<span style="color:orange">--useAffine</span>] : Perform an Affine 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''
−
    transform representations; this trick is probably meaningless when
+
** <span style="color:green">'''Include BSpline registration phase'''</span> [<span style="color:orange">--useBSpline</span>] : Perform a BSpline 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''
−
    tried with the general affine transform.
+
* <span style="color:blue">'''''Output Settings (At least one output must be specified.)'''''</span>:  
 +
** <span style="color:green">'''Slicer BSpline Transform'''</span> [<span style="color:orange">--bsplineTransform</span>] : (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
 +
** <span style="color:green">'''Slicer Linear Transform'''</span> [<span style="color:orange">--linearTransform</span>] : (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
 +
** <span style="color:green">'''Output Transform'''</span> [<span style="color:orange">--outputTransform</span>] : (optional) Filename to which save the (optional) estimated transform. NOTE: You must select either the outputTransform or the outputVolume option.
 +
** <span style="color:green">'''Output Image Volume'''</span> [<span style="color:orange">--outputVolume</span>] : (optional) Output image for registration. NOTE: You must select either the outputTransform or the outputVolume option.
 +
** <span style="color:green">'''Output Image Pixel Type'''</span> [<span style="color:orange">--outputVolumePixelType</span>] : The output image Pixel Type is the scalar datatype for representation of the Output Volume. ''Default value: float''
 +
* <span style="color:blue">'''''Registration Parameters'''''</span>:
 +
** <span style="color:green">'''Transform Type'''</span> [<span style="color:orange">--transformType</span>] : 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.
 +
** <span style="color:green">'''Number Of Iterations'''</span> [<span style="color:orange">--numberOfIterations</span>] : 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''
 +
** <span style="color:green">'''Number Of Samples'''</span> [<span style="color:orange">--numberOfSamples</span>] : 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''
 +
** <span style="color:green">'''Minimum Step Length'''</span> [<span style="color:orange">--minimumStepLength</span>] : Each step in the optimization takes steps at least this big.  When none are possible, registration is complete. ''Default value: 0.005''
 +
** <span style="color:green">'''Transform Scale'''</span> [<span style="color:orange">--translationScale</span>] : 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''
 +
** <span style="color:green">'''Reproportion Scale'''</span> [<span style="color:orange">--reproportionScale</span>] : 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''
 +
** <span style="color:green">'''Skew Scale'''</span> [<span style="color:orange">--skewScale</span>] : 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''
 +
** <span style="color:green">'''Number Of Grid Subdivisions'''</span> [<span style="color:orange">--splineGridSize</span>] : 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''
 +
** <span style="color:green">'''Maximum B-Spline Displacement'''</span> [<span style="color:orange">--maxBSplineDisplacement</span>] :  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''
 +
* <span style="color:blue">'''''Advanced Output Settings'''''</span>:
 +
** <span style="color:green">'''Stripped Output Transform'''</span> [<span style="color:orange">--strippedOutputTransform</span>] : 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.
 +
** <span style="color:green">'''Background Fill Value'''</span> [<span style="color:orange">--backgroundFillValue</span>] : Background fill value for output image. ''Default value: 0.0''
 +
** <span style="color:green">'''Inferior Cut Off From Center'''</span> [<span style="color:orange">--maskInferiorCutOffFromCenter</span>] : For use with --useCenterOfHeadAlign (and --maskProcessingMode ROIAUTO): the cut-off below the image centers, in millimeters,  ''Default value: 1000.0''
 +
** <span style="color:green">'''Scale Output Values'''</span> [<span style="color:orange">--scaleOutputValues</span>] : 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''
 +
** <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, WindowedSinc, or RigidInPlace.  The RigidInPlace option will create an image with the same discrete voxel values and will adjust the origin and direction of the physical space interpretation. ''Default value: Linear''
 +
* <span style="color:blue">'''''Control of Mask Processing'''''</span>:
 +
** <span style="color:green">'''Mask Processing Mode'''</span> [<span style="color:orange">--maskProcessingMode</span>] : 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''
 +
** <span style="color:green">'''Output Fixed Mask (ROIAUTO only)'''</span> [<span style="color:orange">--outputFixedVolumeROI</span>] : The ROI automatically found in fixed image.
 +
** <span style="color:green">'''Output Moving Mask (ROIAUTO only)'''</span> [<span style="color:orange">--outputMovingVolumeROI</span>] : The ROI automatically found in moving image.
 +
** <span style="color:green">'''Input Fixed Mask (ROI only)'''</span> [<span style="color:orange">--fixedBinaryVolume</span>] : Fixed Image binary mask volume.
 +
** <span style="color:green">'''Input Moving Mask (ROI only)'''</span> [<span style="color:orange">--movingBinaryVolume</span>] : Moving Image binary mask volume.
  
−
  --studyID <std::string>
+
* <span style="color:blue">'''''Special Input Image Parameters'''''</span>:
−
    Identifier for the scanner encounter (MRQID), This will eventually be
+
** <span style="color:green">'''Fixed Image Time Index'''</span> [<span style="color:orange">--fixedVolumeTimeIndex</span>] : The index in the time series for the 3D fixed image to fit, if 4-dimensional. ''Default value: 0''
−
    removed. (default: ANON)
+
** <span style="color:green">'''Moving Image Time Index'''</span> [<span style="color:orange">--movingVolumeTimeIndex</span>] : The index in the time series for the 3D moving image to fit, if 4-dimensional. ''Default value: 0''
 +
** <span style="color:green">'''Median Filter Size'''</span> [<span style="color:orange">--medianFilterSize</span>] : The radius for the optional MedianImageFilter preprocessing in all 3 directions. ''Default value: 0,0,0''
 +
** <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. Do NOT use if registering images from different modailties. ''Default value: false''
 +
** <span style="color:green">'''Number of Histogram Bins'''</span> [<span style="color:orange">--numberOfHistogramBins</span>] : The number of histogram levels ''Default value: 50''
 +
** <span style="color:green">'''Number of Match Points'''</span> [<span style="color:orange">--numberOfMatchPoints</span>] : the number of match points ''Default value: 10''
 +
* <span style="color:blue">'''''Registration Debugging Parameters'''''</span>:
 +
** <span style="color:green">'''Caching BSpline Weights Mode'''</span> [<span style="color:orange">--useCachingOfBSplineWeightsMode</span>] : This is a 5x speed advantage at the expense of requiring much more memory.  Only relevant when transformType is BSpline. ''Default value: ON''
 +
** <span style="color:green">'''Explicit PDF Derivatives Mode'''</span> [<span style="color:orange">--useExplicitPDFDerivativesMode</span>] : 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''
 +
** <span style="color:green">''' ROIAuto Dilate Size'''</span> [<span style="color:orange">--ROIAutoDilateSize</span>] : 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''
 +
** <span style="color:green">''' ROIAuto Closing Size'''</span> [<span style="color:orange">--ROIAutoClosingSize</span>] : This flag is only relavent 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. ''Default value: 9.0''
 +
** <span style="color:green">'''Relaxation Factor'''</span> [<span style="color:orange">--relaxationFactor</span>] : Internal debugging parameter, and should probably never be used from the command line.  This will be removed in the future. ''Default value: 0.5''
 +
** <span style="color:green">'''Maximum Step Length'''</span> [<span style="color:orange">--maximumStepLength</span>] : Internal debugging parameter, and should probably never be used from the command line.  This will be removed in the future. ''Default value: 0.2''
 +
** <span style="color:green">'''Failure Exit Code'''</span> [<span style="color:orange">--failureExitCode</span>] : 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''
 +
** <span style="color:green">'''Write Transform On Failure'''</span> [<span style="color:orange">--writeTransformOnFailure</span>] : Flag to save the final transform even if the numberOfIterations are reached without convergence. (Intended for use when --failureExitCode 0 ) ''Default value: 0''
 +
** <span style="color:green">'''debugNumberOfThreads'''</span> [<span style="color:orange">--debugNumberOfThreads</span>] : Explicitly specify the maximum number of threads to use. ''Default value: -1''
 +
** <span style="color:green">'''Debug option'''</span> [<span style="color:orange">--debugLevel</span>] : Display debug messages, and produce debug intermediate results.  0=OFF, 1=Minimal, 10=Maximum debugging. ''Default value: 0''
 +
* <span style="color:blue">'''''Risky Expert-only Parameters'''''</span>:
 +
** <span style="color:green">'''DO NOT USE'''</span> [<span style="color:orange">--NEVER_USE_THIS_FLAG_IT_IS_OUTDATED_00</span>] : DO NOT USE THIS FLAG ''Default value: false''
 +
** <span style="color:green">'''DO NOT USE'''</span> [<span style="color:orange">--NEVER_USE_THIS_FLAG_IT_IS_OUTDATED_01</span>] : DO NOT USE THIS FLAG ''Default value: false''
 +
** <span style="color:green">'''DO NOT USE'''</span> [<span style="color:orange">--NEVER_USE_THIS_FLAG_IT_IS_OUTDATED_02</span>] : DO NOT USE THIS FLAG ''Default value: false''
 +
** <span style="color:green">'''Selective Permission for Transform Parameters to Vary'''</span> [<span style="color:orange">--permitParameterVariation</span>] : 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.=
 +
** <span style="color:green">'''Cost Metric'''</span> [<span style="color:orange">--costMetric</span>] : 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) ''Default value: MMI''
  
−
  --patientID <std::string>
 
−
    Identifier for the research subject, This will eventually be removed.
 
−
    (default: ANON)
 
  
−
  --numberOfMatchPoints <int>
+
||[[Image:BRAINSFitUI_part1.png|thumb|280px|User Interface]] [[Image:BRAINSFitUI_part2.png|thumb|280px|User Interface]]
−
    the number of match points (default: 10)
+
|}
  
−
  --numberOfHistogramBins <int>
+
== Development ==
−
    the number of histogram levels (default: 50)
 
  
−
  -e,  --histogramMatch
+
===Notes from the Developer(s)===
−
    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)
 
−
 
 
−
  --medianFilterSize <std::vector<int>>
 
−
    The radius for the optional MedianImageFilter preprocessing in all 3
 
−
    directions. (default: 0,0,0)
 
  
−
  --movingVolumeTimeIndex <int>
+
This is a thin wrapper program around the BRAINSFitHelper class in BRAINSCommonLib.  The BRAINSFitHelper class
−
    The index in the time series for the 3D moving image to fit, if
+
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:
−
    4-dimensional. (default: 0)
+
<pre>
  
−
  --fixedVolumeTimeIndex <int>
+
    typedef itk::BRAINSFitHelper HelperType;
−
    The index in the time series for the 3D fixed image to fit, if
+
    HelperType::Pointer myHelper=HelperType::New();
−
    4-dimensional. (default: 0)
+
    myHelper->SetTransformType(localTransformType);
 +
    myHelper->SetFixedVolume(extractFixedVolume);
 +
    myHelper->SetMovingVolume(extractMovingVolume);
 +
    myHelper->StartRegistration();
 +
    currentGenericTransform=myHelper->GetCurrentGenericTransform();
 +
    MovingVolumeType::ConstPointer preprocessedMovingVolume = myHelper->GetPreprocessedMovingVolume();
  
−
  --movingBinaryVolume <std::string>
+
/*  Optional member functions that can also be set */
−
    Moving Image binary mask volume.
+
    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");
 +
      }
  
−
  --fixedBinaryVolume <std::string>
+
</pre>
−
    Fixed Image binary mask volume.
 
−
 
 
−
  --outputMovingVolumeROI <std::string>
 
−
    The ROI automatically found in moving image.
 
−
 
 
−
  --outputFixedVolumeROI <std::string>
 
−
    The ROI automatically found in fixed image.
 
−
 
 
−
  --maskProcessingMode <NOMASK|ROIAUTO|ROI>
 
−
    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: NOMASK)
 
−
 
 
−
  --useWindowedSinc
 
−
    Use windowedSinc interpolation to create output images.  WARNING: This
 
−
    will add 8 minutes to the interpolation of the final image of size
 
−
    256x256x256. (default: 0)
 
−
 
 
−
  --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: 0)
 
−
 
 
−
  --backgroundFillValue <double>
 
−
    Background fill value for output image. (default: 0)
 
−
 
 
−
  --outputVolumePixelType <float|short|ushort|int|uint|uchar>
 
−
    The output image Pixel Type is the scalar datatype for representation
 
−
    of the Output Volume. (default: float)
 
−
 
 
−
  --outputVolume <std::string>
 
−
    The (optional) output image for registration.
 
−
 
 
−
  --strippedOutputTransform <std::string>
 
−
    File name for the estimated transform, stripped of scaling, to
 
−
    register the moving image to the fixed image.
 
−
 
 
−
  --outputTransform <std::string>
 
−
    Filename to which save the estimated transform.
 
−
 
 
−
  --maxBSplineDisplacement <double>
 
−
    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: 0)
 
−
 
 
−
  --splineGridSize <std::vector<int>>
 
−
    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: 14,10,12)
 
−
 
 
−
  --skewScale <double>
 
−
    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: 1)
 
−
 
 
−
  --reproportionScale <double>
 
−
    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: 1)
 
−
 
 
−
  --translationScale <double>
 
−
    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: 1000)
 
−
 
 
−
  --minimumStepSize <std::vector<double>>
 
−
    Each step in the optimization takes steps at least this big.  When
 
−
    none are possible, registration is complete. (default: 0.005)
 
−
 
 
−
  --numberOfSamples <int>
 
−
    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:
 
−
    100000)
 
−
 
 
−
  --numberOfIterations <std::vector<int>>
 
−
    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: 1500)
 
−
 
 
−
  --initialTransform <std::string>
 
−
    Filename of transform used to initialize the registration.
 
−
 
 
−
  --maskInferiorCutOffFromCenter <double>
 
−
    For use with --initializeTransformMode CenterOfHead (and
 
−
    --maskProcessingMode ROIAUTO): the cut-off below the image centers, in
 
−
    millimeters, (default: 1000)
 
−
 
 
−
  --initializeTransformMode <Off|MomentsOn|CenterOfHead|GeometryOn>
 
−
    Determine how to initialize the transform center.  GeometryOn on
 
−
    assumes that the center of the voxel lattice of the images represent
 
−
    similar structures.  MomentsOn assumes that the center of mass of the
 
−
    images represent similar structures.  CenterOfHead attempts to use the
 
−
    top of head and shape of neck to drive a center of mass estimate.  Off
 
−
    assumes that the physical space of the images are close, and that
 
−
    centering in terms of the image Origins is a good starting point.
 
−
    This flag is mutually exclusive with the initialTransform flag.
 
−
    (default: Off)
 
−
 
 
−
  --transformType <std::vector<std::string>>
 
−
    Specifies one of the four rigid ITK 3D transform types -- or BSpline
 
−
    -- to use in parameter optimization descent.  BRAINSFit always
 
−
    optimizes mutual information, but the kind of descent varies with the
 
−
    transform type.  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. (default: Rigid)
 
−
 
 
−
  --movingVolume <std::string>
 
−
    The moving image for registration by mutual information optimization.
 
−
 
 
−
  --fixedVolume <std::string>
 
−
    The fixed image for registration by mutual information optimization.
 
−
 
 
−
|[[Image:BRAINSFitUIl.png|thumb|280px|User Interface]]
 
−
|}
 
−
 
 
−
== Development ==
 
−
 
 
−
===Notes from the Developer(s)===
 
  
 
===Dependencies===
 
===Dependencies===
 
BRAINSFit depends on Slicer3 (for the SlicerExecutionModel support) and ITK.
 
BRAINSFit depends on Slicer3 (for the SlicerExecutionModel support) and ITK.
 +
BRAINSFit depends on the BRAINSCommonLib library
 +
 
===Tests===
 
===Tests===
−
TODO: Link to BRAINS3 and/or Slicer3 dashboard tests.
 
−
===Known bugs===
 
  
−
Links to known bugs in the Slicer3 bug tracker
+
Nightly testing of the development head can be found at: http://testing.psychiatry.uiowa.edu/CDash
  
−
* [http://www.na-mic.org/Bug/view.php?id=000 Bug 000: description]
+
===Known bugs===
  
 +
Links to known bugs and feature requests are listed at:
 +
* http://www.nitrc.org/projects/multimodereg/
  
 
===Usability issues===
 
===Usability issues===
Line 349: Line 405:
  
 
Source code:
 
Source code:
−
*[http://viewvc.slicer.org/viewcvs.cgi/trunk file.cxx ]
+
*[http://www.nitrc.org/projects/multimodereg/|Hosted by NITRC ]
−
*[http://viewvc.slicer.org/viewcvs.cgi/trunk file.h ]
 
−
 
−
Doxygen documentation:
 
−
*[http://www.na-mic.org/Slicer/Documentation/Slicer3-doc/html/classes.html class1]
 
  
 
== More Information ==  
 
== More Information ==  
  
 
===Acknowledgment===
 
===Acknowledgment===
−
Include funding and other support here.
+
 
 +
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===
 
===References===
−
Publications related to this module go here. Links to pdfs would be useful.
+
* [http://hdl.handle.net/1926/1291 BRAINSFit: Mutual Information Registrations of Whole-Brain 3D Images, Using the Insight Toolkit], Johnson H.J., Harris G., Williams K., The Insight Journal, 2007.

Latest revision as of 13:15, 27 November 2019

Home < Modules:BRAINSFit

Return to Slicer 3.6 Documentation

Gallery of New Features


Module Name

BRAINSFit

Before registration
AfterRegistration


Example Applications: from the Registration Library

Registration Library Case 02: Brain Affine Affine Intra Subject Brain
Registration Library Case 14: PET PET Brain
lleft link=http://www.na-mic.org/Wiki/index.php/Projects:RegistrationLibrary:RegLib_C29 Diffusion MRI/DTI 
(you can sort the table by method)

General Information

Module Type & Category

Type: CLI

Category: Registration


Authors, Collaborators & Contact

Author: Hans J. Johnson, hans-johnson -at- uiowa.edu, http://www.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

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.

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.

Use Cases, Examples

This module is especially appropriate for these use cases:

  • Use Case 1: Same Subject: Longitudinal

For this use 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 again available in the Slicer3/Applications/CLI/BRAINSTools/BRAINSCommonLib/TestData directory as testT1.nii.gz and testT1Longitudinal.nii.gz

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

--fixedVolume testT1.nii.gz \
--movingVolume testT1Longitudinal.nii.gz \
--outputVolume testT1LongRegFixed.nii.gz \
--outputTransform longToBase.xform \

Since these are the same subject and very little has likely changed in the last year we'll use a Rigid registration. If the registration is poor or there are reasons to expect anatomical changes then additional transforms may be needed, in which case they can be added in a comma separated list, such as "Rigid,ScaleVersor3D,ScaleSkewVersor3D,Affine,BSpline". 

--transformType Rigid \

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

--histogramMatch \

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. 

--maskProcessingMode ROIAUTO \

The registration generally performs better if we include some background in the mask that way the tissue boundary is 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 so a good starting value is 3. 

--ROIAutoDilateSize 3 \

Last 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 of linear. 

--interpolationMode Linear

The full command is: 

BRAINSFit --fixedVolume testT1.nii.gz \
--movingVolume testT1Longitudinal.nii.gz \
--outputVolume testT1LongRegFixed.nii.gz \
--outputTransform longToBase.xform \
--transformType Rigid \
--histogramMatch \
--initializeTransformMode useCenterOfHeadAlign \
--maskProcessingMode ROIAUTO \
--ROIAutoDilateSize 3 \
--interpolationMode Linear
Program title BRAINSFit
Program description Uses the Mattes Mutual Registration algorithm to register a three-dimensional volume to a reference volume. 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
Program version 3.0.0
Program documentation-url https://www.slicer.org/wiki/Modules:BRAINSFit
Longitudinal Checkerboard Before registration
Longitudinal Checkerboard After registration
  • Use Case 2: Same Subject: MultiModal

For this use case we're registering a T1 scan with a T2 scan collected in the same sesson. The two images are again available in the Slicer3/Applications/CLI/BRAINSTools/BRAINSCommonLib/TestData directory as testT1.nii.gz and testT2.nii.gz

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

--fixedVolume testT1.nii.gz \
--movingVolume testT2.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 as this would try to map the T2 intensities into T1 intensities, resulting in an image that was 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. 

--maskProcessingMode ROIAUTO \

The registration generally performs better if we include some background in the mask that way the tissue boundary is 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 so a good starting value is 3. 

--ROIAutoDilateSize 3 \

Last 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 of linear. 

--interpolationMode Linear

The full command is: 

BRAINSFit --fixedVolume testT1.nii.gz \
--movingVolume testT2.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
  • Use Case 3: Mouse Registration

Here we'll register brains from two different mice together. The fixed and moving mouse brains used in this example are available in the Slicer3/Applications/CLI/BRAINSTools/BRAINSCommonLib/TestData directory.

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. Again, 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 are't working with human heads 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 so a good starting value for mice is 0.9. 

--ROIAutoClosingSize 0.9 \
--ROIAutoDilateSize 0.9 \

Last 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 of linear. 

--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


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:
    • 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: Parameters that define which registration steps to use.
    • 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.
    • Intitialze Transform Mode [--initializeTransformMode] : Determine how to initialize the transform center. GeometryAlign on assumes that the center of the voxel lattice of the images represent similar structures. MomentsAlign 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. Off assumes that the physical space of the images are close, and that centering in terms of the image Origins is a good starting point. This flag is mutually exclusive with the initialTransform flag. Default value: Off
    • 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 ScaleSkewVersor3D 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 an Affine 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 BSpline 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.):
    • 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:
    • 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 Length [--minimumStepLength] : 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:
    • 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, WindowedSinc, or RigidInPlace. The RigidInPlace option will create an image with the same discrete voxel values and will adjust the origin and direction of the physical space interpretation. Default value: Linear
  • Control of Mask Processing:
    • 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:
    • 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. Do NOT use if registering images from different modailties. 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:
    • 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
    • ROIAuto Closing Size [--ROIAutoClosingSize] : This flag is only relavent 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. Default value: 9.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 Length [--maximumStepLength] : 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:
    • DO NOT USE [--NEVER_USE_THIS_FLAG_IT_IS_OUTDATED_00] : DO NOT USE THIS FLAG Default value: false
    • DO NOT USE [--NEVER_USE_THIS_FLAG_IT_IS_OUTDATED_01] : DO NOT USE THIS FLAG Default value: false
    • DO NOT USE [--NEVER_USE_THIS_FLAG_IT_IS_OUTDATED_02] : DO NOT USE THIS FLAG Default value: false
    • 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.=
    • 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) Default value: MMI
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:

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:

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

Retrieved from "https://www.slicer.org/w/index.php?title=Modules:BRAINSFit&oldid=62561"