Home < Documentation < 4.1 < Modules < BRAINSFit
General Registration (BRAINS)
General Registration (BRAINS)
General Information
Module Type & Category
Type: CLI
Category: Registration
Authors, Collaborators & Contact
Author: Hans J. Johnson, hans-johnson -at- uiowa.edu, http://wwww.psychiatry.uiowa.edu
Contributors:
Contact: name, email
Module Description
Usage
Use Cases, Examples
This module is especially appropriate for these use cases:
Examples of the module in use:
Tutorials
Quick Tour of Features and Use
A list panels in the interface, their features, what they mean, and how to use them.
- Input Images :
- 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.
- 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 Image Volume [--outputVolume] : (optional) Output image for registration. NOTE: You must select either the outputTransform or the outputVolume option.
- Initialization of registration: Options for initializing transform parameters to a initial starting point.
- Initialization 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
- 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 superceeds the use of transformType if any of them are set. Default value: false
- Rigid+Scale(7 DOF) [--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
- Rigid+Scale+Skew(10 DOF) [--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
- Affine(12 DOF) [--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
- BSpline (>27 DOF) [--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
- Composite (many DOF) [--useComposite] : Perform a Composite 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
- Main Parameters:
- 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
- B-Spline Grid Size [--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
- Max 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
- Mask Option:
- Masking Option [--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
- (ROI)Masking input fixed [--fixedBinaryVolume] : Fixed Image binary mask volume, ONLY FOR MANUAL ROI mode.
- (ROI)Masking input moving [--movingBinaryVolume] : Moving Image binary mask volume, ONLY FOR MANUAL ROI mode.
- (ROIAUTO) Output fixed mask [--outputFixedVolumeROI] : The ROI automatically found in fixed image, ONLY FOR ROIAUTO mode.
- (ROIAUTO) Output moving mask [--outputMovingVolumeROI] : The ROI automatically found in moving image, ONLY FOR ROIAUTO mode.
- Advanced Output Settings:
- Output Image Pixel Type [--outputVolumePixelType] : The output image Pixel Type is the scalar datatype for representation of the Output Volume. Default value: float
- 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 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. Default value: Linear
- 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
- 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
- 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
- Histogram bin count [--numberOfHistogramBins] : The number of histogram levels Default value: 50
- Histogram match point count [--numberOfMatchPoints] : the number of match points Default value: 10
- Special Modes Parameters:
- 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.
- 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.
- Output Transform [--outputTransform] : (optional) Filename to which save the (optional) estimated transform. NOTE: You must select either the outputTransform or the outputVolume option.
- 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
- Remove Intensity Outliers value at one tail [--removeIntensityOutliers] : 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 moduel will throw away 0.005 % of both tails, so 0.01% of intensities in total would be ignored in its statistic calculation. Default value: 0.0
- 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
- Number Of Threads [--numberOfThreads] : Explicitly specify the maximum number of threads to use. (default is auto-detected) Default value: -1
- Debug MI metric Number Of Threads [--forceMINumberOfThreads] : Force the the maximum number of threads to use for non thread safe MI metric. 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
|
|
Development
Notes from the Developer(s)
Algorithms used, library classes depended upon, use cases, etc.
Dependencies
Other modules or packages that are required for this module's use.
Tests
On the Dashboard, these tests verify that the module is working on various platforms:
Known bugs
Links to known bugs in the Slicer4 bug tracker
Usability issues
Follow this link to
the Slicer4 bug tracker. Please select the usabilityissue category when browsing or contributing.
Source code & documentation
Links to the module's source code:
Source code:
Doxygen documentation:
More Information
Acknowledgment
References
Publications related to this module go here. Links to pdfs would be useful.
