Slicer Wiki - User contributions [en]

Documentation/Nightly/Developers/Tutorials/MigrationGuide/Slicer

2020-04-15T12:35:08Z

Hjmjohnson: /* Slicer backward incompatible changes */

<noinclude>__TOC__</noinclude>
==Slicer backward incompatible changes==

===Slicer 5.0: API changes since 4.10===

*Removed protected method <tt>vtkMRMLModelDisplayableManager::FindPickedDisplayNodeFromMesh</tt>

====Python 2 to Python 3====

Slicer core has been updated to only support Python 3.

C++ classes and python scripts have been updated to use idioms and constructs only available in Python 3.

Update to python scripts have been done leveraging the CLI provided by https://python-future.org by (1) iteratively applying each one of the associates "fixes", (2) reviewing associated changes and (3) updating as needed.

Updates specific to extensions are discussed in [[Documentation/Nightly/Developers/Tutorials/MigrationGuide#Slicer_5.0:_Python2_to_Python3]]

====Interactor styles====

Limitations of VTK widgets (editable points, lines, curves, etc.) prevented Slicer from having sophisticated user interaction in slice and 3D views. In Slicer5, we replaced VTK widgets with MRML widgets. These widgets are still VTK-based and somewhat similar to VTK widgets, but they operate directly on MRML nodes, they use direct method calls between widgets and their representation, and they use a more efficient and flexible event processing. Instead of hardcoding how viewers behave in response to interaction (mouse move, button click, keyboard, ...) events in an interactor style, all these events are translated to actions and performed in a MRML widget. Most modules are not expected to observe interactor events or styles directly, but if they did, then they may need to be updated accordingly.

*vtkSliceViewInteractorStyle renamed to vtkMRMLSliceDViewInteractorStyle to reflect that it uses MRML classes directly.
*vtkThreeDViewInteractorStyle renamed to vtkMRMLThreeDViewInteractorStyle to reflect that it uses MRML classes directly.

====slicer.util functions====

*slicer.util.loadVolume (and other node load functions) now return the loaded node instead of a True/False flag. In case of an error, a RuntimeError exception is thrown.
**Old way of loading a node and get it in a variable: <code>volumeNode = slicer.util.loadVolume('path/to/volume.nrrd', returnNode=True)[1]</code>
**New way of loading a node and get it in a variable: <code>volumeNode = slicer.util.loadVolume('path/to/volume.nrrd')</code>

====Markups====

*<tt>vtkCommand::Modified</tt> events are no longer invoked when control points are added/removed/modified to improve performance. Modules that need to know If a point position is modified need to add observers to <tt>vtkMRMLMarkupsNode::PointAddedEvent</tt>, <tt>vtkMRMLMarkupsNode::PointRemovedEvent</tt>, <tt>vtkMRMLMarkupsNode::PointModifiedEvent</tt> events. See example in [[Documentation/Nightly/ScriptRepository#Get_a_notification_if_a_markup_point_position_is_modified|script repository]].
*<tt>vtkMRMLMarkupsNode::MarkupAddedEvent</tt> is renamed to <tt>vtkMRMLMarkupsNode::PointAddedEvent</tt>. This is called even when preview point is created. Use <tt>vtkMRMLMarkupsNode::PointPositionDefinedEvent</tt> to get notification only when position of a point becomes defined (and not during preview).
*<tt>vtkMRMLMarkupsNode::MarkupRemovedEvent</tt> is renamed to <tt>vtkMRMLMarkupsNode::PointRemovedEvent</tt>. This is called even when preview point is removed. Use <tt>vtkMRMLMarkupsNode::PointPositionUndefinedEvent</tt> to get notification only when position of a point becomes undefined (and not during preview).
*<tt>vtkMRMLMarkupsNode::NthMarkupModifiedEvent</tt> is replaced by <tt>vtkMRMLMarkupsNode::PointModifiedEvent</tt>
*During placement of markups, a preview markup point is created. If number of already placed markup points needs to be determined then <code>GetNumberOfDefinedControlPoints()</code> method can be used.
*<tt>GetDefaultMarkups...()</tt> and <tt>SetDefaultMarkups...()</tt> methods are removed. Instead default display node can be accessed by <tt>GetDefaultMarkupsDisplayNode()</tt> method and default values can be get/set in that class.
*<tt>vtkMRMLMarkupsNode::GetNthMarkupSelected()</tt> is replaced by <tt>GetNthControlPointSelected()</tt>
*<tt>vtkMRMLMarkupsNode::PointPositionDefinedEvent</tt> event is added. This event is invoked whenever position is defined for a new point.
*<tt>vtkMRMLMarkupsNode::PointPositionUndefinedEvent</tt> event is added. This event is invoked whenever point with defined position is removed (point is deleted or its position gets undefined).
*For more details, see [{{doxygen-class-url|vtkMRMLMarkupsNode}} vtkMRMLMarkupsNode]

====Segmentations====

Binary labelmap segmentations can now be represented as shared labelmaps.
The previous implementation of binary labelmaps was performance intensive as each labelmap was represented using a separate vtkDataObject.
Visualizing and editing segmentations that contained a large number of segments could cause performance issues, due to the large number of vtkActors required, as well as calculating masks and overwriting other segments when editing.

By default, newly created segments will now be contained on the same layer.
Segments will only be separated into multiple layers if the user creates an overlapping segment when editing.

Segments are now saved as a 4D volume with shared 3D layers.
For a segmentation that only uses one layer, the resulting image is a 3D volume.
Before saving, the labelmaps will be collapsed into as few layers as possible.

*seg.nrrd files now contain two additional attributes for each segment: SegmentX_LabelValue and SegmentX_Layer
*The label value of a segment can be found using vtkSegment::GetLabelValue()
*Whether or not a segment is shared can be found using vtkSegmentation::IsSharedBinaryLabelmap()
*The other segments sharing the same labelmap can be found using vtkSegmentation::GetSegmentIDsSharingBinaryLabelmapRepresentation()
*Segment editor effects should generally use modifySelectedSegmentByLabelmap rather than SetBinaryLabelmapToSegment to manage layer separation
*Conversion rules now call PreConvert() and PostConvert() before and after conversion to perform pre and post processing steps on the segmentation as a whole
*The function signature for vtkSegmentationConverterRule::Convert now accepts a vtkSegment rather than two vtkDataObjects
*slicer.util.arrayFromSegment has been deprecated. slicer.util.arrayFromSegmentBinaryLabelmap and slicer.util.arrayFromSegmentInternalBinaryLabelmap can be used instead

=====Erase the contents of a single segment=====

<pre>
segmentation = segmentationNode.GetSegmentation()
segmentation.ClearSegment(segmentId)
</pre>

=====Move a segment from a shared labelmap to a separate layer=====

<pre>
segmentation = segmentationNode.GetSegmentation()
segmentation.SeparateSegmentLabelmap(segmentId)
</pre>

=====Combine all binary labelmaps to as few layers as possible=====

<pre>
segmentation = segmentationNode.GetSegmentation()
segmentation.CollapseBinaryLabelmaps(forceToSingleLayer=false)
</pre>

Get a read-only labelmap for a single segment:

<pre>
labelmap = slicer.vtkOrientedImageData()
segmentationNode.GetBinaryLabelmapRepresentation(segmentId, labelmap)
</pre>

(similarly, use GetClosedSurfaceRepresentation with an additional vtk.vtkPolyData parameter to get a read-only surface mesh)

or

<pre>
labelmapNumpyArray = slicer.util.arrayFromSegmentBinaryLabelmap(segmentationNode, segmentId)
</pre>

=====Get a modifiable shared labelmap=====

<pre>
labelmap = slicer.vtkOrientedImageData()
segmentationNode.GetBinaryLabelmapInternalRepresentation(segmentId, labelmap)
</pre>

(similarly, use GetClosedSurfaceInternalRepresentation to get a modifiable surface mesh)

or

<pre>
labelmapNumpyArray = slicer.util.arrayFromSegmentInternalBinaryLabelmap(segmentationNode, segmentId)
</pre>

=====Export segments to models=====

Model hierarchies no longer exist in Slicer5, but instead various kinds of hierarchies are now replaced by "subject hierarchy", which can accommodate any node types in a single hierarchy. Accordingly, `ExportSegmentsToModelHierarchy`, `ExportAllSegmentsToModelHierarchy`, etc. are replaced by `ExportSegmentsToModels`, `ExportAllSegmentsToModels`, which take a subject hierarchy folder item ID as input.
Documentation/Nightly
See code example in [[Documentation/{{documentation/version}}/ScriptRepository#Export_model_nodes_from_segmentation_node|script repository]].

====Volume rendering====

vtkMRMLVolumeRenderingDisplayNode::SetAndObserveVolumeNodeID method was removed, as display node base class already maintains a pointer to the displayed (volume) node. To associate a volume display node with a volume node, call <pre>volumeNode->AddAndObserveDisplayNodeID(volumeRenderingDisplayNode->GetID());</pre> after both nodes are added to the scene.

== 5.0 : Avoid typedef of anonymous structure ==
<nowiki>https://reviews.llvm.org/D74103</nowiki>

Due to a recent (but retroactive) C++ rule change, only sufficiently

C-compatible classes are permitted to be given a typedef name for

linkage purposes. Add an enabled-by-default warning for these cases, and

rephrase our existing error for the case where we encounter the typedef

name for linkage after we've already computed and used a wrong linkage

in terms of the new rule.<blockquote>Slicer/Libs/MRML/Core/vtkMRMLTableStorageNode.h:95:17:</blockquote><blockquote>warning: anonymous non-C-compatible type given name for linkage purposes by typedef declaration; add a tag name here [-Wnon-c-typedef-for-linkage]</blockquote><blockquote> typedef struct</blockquote><blockquote> ^</blockquote><blockquote> ColumnInfo</blockquote><blockquote>Slicer/Libs/MRML/Core/vtkMRMLTableStorageNode.h:99:5:</blockquote><blockquote>note: type is not C-compatible due to this default member initializer</blockquote><blockquote> int ScalarType = VTK_STRING;</blockquote><blockquote><nowiki> ^~~~~~~~~~~~~~</nowiki></blockquote><blockquote>Slicer/Libs/MRML/Core/vtkMRMLTableStorageNode.h:102:5:</blockquote><blockquote>note: type is given name 'ColumnInfo' for linkage purposes by this typedef declaration</blockquote><blockquote> } ColumnInfo;</blockquote><blockquote> ^</blockquote><blockquote>For consistency, Use 'using' to a named structure definintion for all </blockquote><blockquote>structures.</blockquote> 
===Slicer 4.11: Variable CMAKE_DEFAULT_BUILD_TYPE renamed to Slicer_DEFAULT_BUILD_TYPE===

Setting the default build type for single config generator may be done setting <tt>Slicer_DEFAULT_BUILD_TYPE</tt> instead of <tt>CMAKE_DEFAULT_BUILD_TYPE</tt>.

Error message similar to:

<pre>
CMake Error:
Generator

Visual Studio 15 2017

does not support variable

CMAKE_DEFAULT_BUILD_TYPE

but it has been specified.
</pre>

References:

https://github.com/Slicer/Slicer/pull/4799

===Slicer 4.11: teem python module renamed to vtkTeem, explicit import required===

*Since the module provides VTK classes interfacing with "teem", the name is now representative of the class it contains.
*<tt>vtkTeem</tt> classes are expected to be used by explicitly importing the module.

Replace code like this:

<pre>
import teem

class CalculateTensorScalars(object):
def __init__(self):
self.dti_math = teem.vtkDiffusionTensorMathematics()
</pre>

By this:

<pre>
import vtkTeem

class CalculateTensorScalars(object):
def __init__(self):
self.dti_math = vtkTeem.vtkDiffusionTensorMathematics()
</pre>

===Slicer 4.11: Display window/level (brightness/contrast) adjustment===

*A new "Window/level" mouse interaction mode was introduced. Volume display window/level can only be changed if this mode is activated by clicking the corresponding button in the toolbar. The new mouse mode prevents accidental modification of volume window/level (when for example the user accidentally clicked too far from a markup) and it also allows more sophisticated window/level adjustments.
*New region-based auto window/level feature added: activate "Window/level" mouse mode and use Ctrl + left-click-and-drag to highlight a region and optimize window/level for that (pressing Escape or right-click cancels the operation).
*Auto window/level reset: activate "Window/level" mouse mode and double-click the left mouse button.
*Improved auto window/level algorithm to prevent too bright display of images. Window/level is set to display values between 0.1th and 99.9th percentile of gray levels. See details here: https://discourse.slicer.org/t/feedback-requested-how-to-improve-mouse-interaction-in-views/6420.
*Removed class <tt>vtkImageBimodalAnalysis</tt>

===Slicer 4.10: Registration of runTest function done in ScriptedLoadableModule base class===

Following [http://viewvc.slicer.org/viewvc.cgi/Slicer4?view=revision&revision=27617 r27617]:

*the <code>ScriptedLoadableModule</code> class takes care of registering the <code>runTest</code> function.
*the <code>runTest</code> function expects <code>msec</code> keyword argument.

Error message similar to:

<pre>
Traceback (most recent call last):
File "/path/to/Slicer-SuperBuild/Slicer-build/bin/Python/slicer/ScriptedLoadableModule.py", line 205, in onReloadAndTest
test(msec=int(slicer.app.userSettings().value("Developer/SelfTestDisplayMessageDelay")), **kwargs)
TypeError: runTest() got an unexpected keyword argument 'msec'
Reload and Test: Exception!

runTest() got an unexpected keyword argument 'msec'
</pre>

Replace code like this:

<pre>
class sceneImport2428(ScriptedLoadableModule):
[...]
def __init__(self, parent):
ScriptedLoadableModule.__init__(self, parent)
parent.title = "..."
[...]
parent.acknowledgementText = "..."
self.parent = parent

# Add this test to the SelfTest module's list for discovery when the module
# is created. Since this module may be discovered before SelfTests itself,
# create the list if it doesn't already exist.
try:
slicer.selfTests
except AttributeError:
slicer.selfTests = {}
slicer.selfTests['sceneImport2428'] = self.runTest

def runTest(self):
tester = sceneImport2428Test()
tester.runTest()

[...]
</pre>

By this:

<pre>
class sceneImport2428(ScriptedLoadableModule):
[...]
def __init__(self, parent):
ScriptedLoadableModule.__init__(self, parent)
parent.title = "..."
[...]
parent.acknowledgementText = "..."

[...]
</pre>

===Slicer 4.9: Update of VTK version from 9.0 to 8.2===

Following [https://github.com/Kitware/VTK/commit/b703d78be3ffd8ae69c319afa0230097ff270f26 kitware/VTK@b703d78be], VTK has updated to use version number 8.2 instead of 9.0. This was discussed in on the VTK mailing list in http://vtk.1045678.n5.nabble.com/Discussion-OK-to-change-VTK-s-version-number-from-9-0-to-8-2-tt5748702.html

At first, this VTK commit and its companion [https://github.com/Kitware/VTK/commit/8a00b357e84eec695bda049216f30f2b76d80855 kitware/VTK@8a00b357e] were both reverted from the [https://github.com/Slicer/VTK/ Slicer/VTK] fork. Then, since having the corresponding changes reverted in VTK was not possible, it was decided to also update Slicer. This was done in the following commits:

*[http://viewvc.slicer.org/viewvc.cgi/Slicer4?view=revision&revision=27472 r27472]: COMP: Update c++ classes to support building against VTK >= 9 and VTK >= 8.2
*[http://viewvc.slicer.org/viewvc.cgi/Slicer4?view=revision&revision=27473 r27473]: COMP: Update VTK to include version change from 9.0 to 8.2. Fixes #4623

This means that code depending on VTK must also be updated to include similar fixes.

'''Replace this:'''
#if VTK_MAJOR_VERSION >= 9

'''By this:'''
#if VTK_MAJOR_VERSION >= 9 || (VTK_MAJOR_VERSION >= 8 && VTK_MINOR_VERSION >= 2)

and

'''Replace this:'''
#if VTK_MAJOR_VERSION < 9

'''By this:'''
#if VTK_MAJOR_VERSION <= 7 || (VTK_MAJOR_VERSION <= 8 && VTK_MINOR_VERSION <= 1)

===Slicer 4.9: ITK_LEGACY_REMOVE is now OFF===
In preparation to switch to ITK 5.0, we disable legacy functionality in ITK. This might affect some modules which rely on ITK. Take a look at [https://itk.org/migrationv4 ITK 4 migration guide] before [https://github.com/InsightSoftwareConsortium/ITK/blob/master/Documentation/ITK5MigrationGuide.md ITK 5 migration guide].

===Slicer 4.9: vtkMRMLPlotDataNode renamed to vtkMRMLPlotSeriesNode===
Plotting was improved in [https://github.com/Slicer/Slicer/commit/082edc40c this commit]

'''Replace this:'''

vtkMRMLPlotDataNode

'''By this:'''
vtkMRMLPlotSeriesNode

===Slicer 4.9: CMake: Module MIDAS not available===

The test infrastructure of your project should be updated to use [https://cmake.org/cmake/help/latest/module/ExternalData.html ExternalData] built-in CMake module
instead of the specific <tt>MIDAS</tt> module.

See EMSegment commit [http://viewvc.slicer.org/viewvc.cgi/Slicer3?view=revision&revision=17150 r17150] for an example of transition.

This means that instead of using <tt>midas_add_test</tt> with the <tt>MIDAS{path/to/file.ext.md5}</tt>
syntax for addressing the test data, the function [https://cmake.org/cmake/help/latest/module/ExternalData.html#command:externaldata_add_test ExternalData_add_target] is used by
specifying both <tt>DATA{path/to/file.ext}</tt> and a download target name.

'''Replace this:'''

midas_add_test(NAME test1 COMMAND ...)
midas_add_test(NAME test2 COMMAND ...)

'''By this:'''

ExternalData_add_test(EMSegmentData NAME test1 COMMAND ...)
ExternalData_add_test(EMSegmentData NAME test2 COMMAND ...)

[...]

ExternalData_add_target(EMSegmentData)

A key difference with the former approaches is that instead of adding two tests (one named
<tt><testName>_fetchData</tt> to downoad the data and one running the test command), only one
test is added but a common download target is added at the end using [https://cmake.org/cmake/help/latest/module/ExternalData.html#command:externaldata_add_target ExternalData_add_target]
function.

This means that test data can now be downloaded in parallel (and cached) at build time instead
of testing time.

===Slicer 4.9: CMake: Module SlicerMacroCheckExternalProjectDependency not available===

Since the module was removed in [http://viewvc.slicer.org/viewvc.cgi/Slicer4?view=revision&revision=26992 r26992], consider updating
your build system to use CMake module <code>ExternalProjectDependency</code>

===Slicer 4.9: CMake: Module SlicerMacroEmptyExternalProject not available===

Since the module was removed in [http://viewvc.slicer.org/viewvc.cgi/Slicer4?view=revision&revision=26991 r26991]

'''Replace this:'''

<pre>
include(SlicerMacroEmptyExternalProject)

[...]

SlicerMacroEmptyExternalProject("${proj}" "${${proj}_DEPENDENCIES}")
</pre>

'''By this:'''

<pre>
include(ExternalProjectDependency)

[...]

ExternalProject_Add_Empty(${proj} DEPENDS ${${proj}_DEPENDENCIES})
</pre>

===Slicer 4.9: CMake: Module SlicerBlockSetCMakeOSXVariables not available===

Since it was renamed to <tt>SlicerInitializeOSXVariables</tt> in [http://viewvc.slicer.org/viewvc.cgi/Slicer4?view=revision&revision=26982 r26982]

'''Replace this:'''

<pre>
include(SlicerBlockSetCMakeOSXVariables)
</pre>

'''By this:'''

<pre>
include(SlicerInitializeOSXVariables)
</pre>

===Slicer 4.9: Application: isRelease() function not available===

See [[#Slicer_4.8:_Application:_isRelease.28.29_function_not_available_or_deprecated]]

===Slicer 4.9: slicer.util.getNode() raises exception if node not found===

If slicer.util.getNode() is called and the node is not found then instead of just returning None (Slicer 4.8 behavior), the method now raises a MRMLNodeNotFoundException. This makes code debugging easier (the error is reported when it happens), and in general more consistent with Python conventions.

How to update existing code:

It is advisable to only use slicer.util.getNode in tests, or interactively in the Python console, as its behavior is somewhat unpredictable (it may either found a node by name or ID, and result of wildcard search is even less deterministic). In general, it is recommended to use the MRML scene's GetFirstNodeByName and GetNodeByID methods instead.

'''Replace this:'''

<pre>
n = slicer.util.getNode(nodeNameOrID)
</pre>

'''By one of these:'''

If node is to be found by name:
<pre>
n = slicer.mrmlScene.GetFirstNodeByName(nodeName)
</pre>

If node is to be found by ID:
<pre>
n = slicer.mrmlScene.GetNodeByID(nodeID)
</pre>

If node is to be found by name or ID (slower, less predictable, recommended for testing only):

<pre>
try:
n = slicer.util.getNode(nodeNameOrID)
except slicer.util.MRMLNodeNotFoundException:
n = None
</pre>

More information: https://github.com/Slicer/Slicer/commit/b63484af1b1b413f35396f8f7efb73e870448bd4

===Slicer 4.8: Application: isRelease() function not available or deprecated===

Error message similar to:

Missing/deprecated qSlicerCoreApplication::isRelease()

or

Missing/deprecated slicer.app.isRelease()

Solution:

Use <tt>qSlicerCoreApplication::releaseType() == "Stable"</tt>

Summary:

Prior to r26420, the variable <tt>Slicer_VERSION_TWEAK</tt> was used to check if a "stable release" was built. The variable value
was set by updating the sources and defining the variable to an integer greater or equal to 0. In other word, if the variable
evaluated to an empty string, a nighty or experimental build was being done, if it evaluated to an integer, a stable release build
was being done.

The approach had few issues:

*the name of the variable was confusing
*identifying a "stable release" only from a source tree revision was not enough. Indeed the environment defining a "release" is the one found on the build machines used to generate the installer.
*nightly build are also considered as release

To address this, the CMake variable <tt>Slicer_RELEASE_TYPE</tt> was introduced. As of 2017-10-04, it can be set to <tt>Experimental</tt>, <tt>Nightly</tt>
or <tt>Stable</tt> with <tt>Experimental</tt> being the value hard-coded in the source.

Identifying a build as "stable" is now explicitly done by setting <tt>Slicer_RELEASE_TYPE</tt> to <tt>Stable</tt> at configure time.

Also, since the concept of release types was introduced, the function <tt>isRelease()</tt> has been removed in favor of <tt>releaseType()</tt>.

References:

https://github.com/Slicer/Slicer/pull/354

===Slicer Python Module: modulewidget and others removed.===

 Summary
Python classes formerly in "slicer.moduledm", "slicer.modulelogic", "slicer.modulemrml"
and "slicer.modulewidget" are now directly available in the slicer module.

See example of change [https://github.com/QIICR/LongitudinalPETCT/pull/11 here].

Rational:

See comments in commit messages referenced blow.

References:

https://github.com/Slicer/Slicer/commit/628f83fe7a6f4e0710e306bcaf7c04b9e3e5e6bd

https://github.com/Slicer/Slicer/commit/9cb5668fde1abc8f0430a91ca37fc29277ceeb4e

===MRML: Slicer 4.6: Moved up vtkMRMLStorableNode in the MRML node hierarchy.===

Rational:

vtkMRMLStorableNode is not a children of vtkMRMLTransformable node anymore,
but directly a children of vtkMRMLNode.

This allows making a node storable without requiring it to be also
transformable. It is important for several node types (color maps, tables,
etc), which require separate storage node but are not transformable.

References:

*Changed introduced in [http://viewvc.slicer.org/viewvc.cgi/Slicer4?view=revision&revision=24891 r24891]

Error message similar to:

/tmp/LongitudinalPETCT/MRML/vtkMRMLLongitudinalPETCTStudyNode.cxx: In member function ‘void vtkMRMLLongitudinalPETCTStudyNode::ObserveRegistrationTransform(bool)’:
/tmp/LongitudinalPETCT/MRML/vtkMRMLLongitudinalPETCTStudyNode.cxx:478:28: error: ‘class vtkMRMLVolumePropertyNode’ has no member named ‘GetParentTransformNode’
&& propNode->GetParentTransformNode()
^
/tmp/LongitudinalPETCT/MRML/vtkMRMLLongitudinalPETCTStudyNode.cxx:480:23: error: ‘class vtkMRMLVolumePropertyNode’ has no member named ‘SetAndObserveTransformNodeID’
propNode->SetAndObserveTransformNodeID(
^
/tmp/LongitudinalPETCT/MRML/vtkMRMLLongitudinalPETCTStudyNode.cxx:503:23: error: ‘class vtkMRMLVolumePropertyNode’ has no member named ‘SetAndObserveTransformNodeID’
propNode->SetAndObserveTransformNodeID(NULL);
^

Solution:

Removes lines and/or refactor code

===MRML: Slicer 4.5: Introduction of vtkMRMLLabelMapVolumeNode===

Rational:

Before <tt>vtkMRMLScalarVolumeNode</tt> was used for both scalar and label map
volumes and the LabelMap custom MRML node attribute was used for
distinguishing between them (0=scalar; 1=label map volume).

This made conversion between labelmap/scalar volumes very easy but made
it difficult to customize behavior, display, processing of segmentation
information.

Now a new <tt>vtkMRMLLabelMapVolumeNode</tt> class is used for storing segmentation
information (still using <tt>vtkMRMLScalarVolume</tt> used as base class for backward
compatibility; but in the future the base class may be changed to reflect
that segmentation can be represented in various ways, not just as volumes).

Error message similar to:

error: ‘class vtkMRMLScalarVolumeNode’ has no member named ‘SetLabelMap’
outputVolumeNode->SetLabelMap(1);
^

Solution (part1: down cast to <tt>vtkMRMLLabelMapVolumeNode</tt>, remove call to <tt>SetLabelMap</tt>)

Replace lines like:

vtkMRMLNode* outputNode = d->OutputLabelVolumeMRMLNodeComboBox->currentNode();
vtkMRMLScalarVolumeNode* outputVolumeNode = vtkMRMLScalarVolumeNode::SafeDownCast(outputNode);
[...]
outputVolumeNode->SetLabelMap(1);

with:

vtkMRMLLabelMapVolumeNode* outputVolumeNode =
vtkMRMLLabelMapVolumeNode::SafeDownCast(d->OutputLabelVolumeMRMLNodeComboBox->currentNode());
[...]

Solution (part2: Update UI file):

Replace lines like:

<widget class="qMRMLNodeComboBox" name="InputLabelVolumeMRMLNodeComboBox">
<property name="nodeTypes">
<stringlist>
<string>vtkMRMLScalarVolumeNode</string>
</stringlist>
</property>
[...]
</widget>

with:

<widget class="qMRMLNodeComboBox" name="InputLabelVolumeMRMLNodeComboBox">
<property name="nodeTypes">
<stringlist>
<string>vtkMRMLLabelMapVolumeNode</string> <------------- Update Here
</stringlist>
</property>
[...]
</widget>

Solution (part3: Update node selector configuration):

Replace lines like:

nodeSelector.setNodeTypes(QStringList("vtkMRMLScalarVolumeNode"));
nodeSelector.addAttribute("vtkMRMLScalarVolumeNode", "LabelMap", "1");

with:

nodeSelector.setNodeTypes(QStringList("vtkMRMLLabelMapVolumeNode"));

References:

*https://www.slicer.org/wiki/Documentation/Labs/Segmentations#vtkMRMLLabelMapVolumeNode_integration* http://viewvc.slicer.org/viewvc.cgi/Slicer4?view=revision&revision=24291

===CLI: Slicer 4.3: Add ITKFactoryRegistration library centralizing ITK IO factory registration===

Rational:

Linking against <tt>ITKFactoryRegistration</tt> ensures that ITK IO factory are properly registered on all supported platforms.

Error message similar to:

Undefined symbols for architecture x86_64:
"itk::itkFactoryRegistration()", referenced from:
_main in ImageMakerTest.cxx.o
ld: symbol(s) not found for architecture x86_64

Solution:

Replace lines like:

target_link_libraries(${CLP}Test ${CLP}Lib)

with:

target_link_libraries(${CLP}Test ${CLP}Lib ${SlicerExecutionModel_EXTRA_EXECUTABLE_TARGET_LIBRARIES})

References:

*http://viewvc.slicer.org/viewvc.cgi/Slicer4?view=revision&revision=21592
*https://issues.slicer.org/view.php?id=2813

Documentation/Labs/BRAINS and ITKv4 issue

2013-04-18T19:53:57Z

Hjmjohnson: /* Experiment results */

This page documents the experiment done while trying to sort the issue causing BRAINS to crash when built within Slicer.

== Experiment Setup ==

Here is the VERY simple program that is failing:
https://github.com/BRAINSia/BRAINSTools/blob/SlicerDebugBRAINSFitInstrumentation/BRAINSFit/DebugSlicerProg.cxx

In my slicer build tree:
/scratch/johnsonhj/src/Slicer-DEBUG/BRAINSTools (SlicerDebugBRAINSFitInstrumentation)

With git remove –v:
origin git://github.com/BRAINSia/BRAINSTools.git (push)

And BRAINSTools hash 31beee592eba2d98655b864e6dc704ac9bf995e8

== Experiment results ==

* BRAINS standalone
** ITKv4 tag:
** ITKv4 options: DCMTK disabled
** Result:

* BRAINS slicer
** ITKv4 tag:
** ITKv4 options: DCMTK disabled, EMsegment disabled
** Result:

=======================
[FAILED]
Build Slicer: Run Slicers version of Debug
johnsonhj@neuron$ /scratch/johnsonhj/src/Slicer-DEBUG/Slicer-build/bin/DebugSlicerProg
TESTING: STARTED
PRE : 9945 Segmentation fault: 11

=======================
[PASSED]

Build Stand Alone version of BRAINSTools using the same source code:

johnsonhj@neuron$ /scratch/johnsonhj/src/Slicer-DEBUG/BT_DEBUG/bin/DebugSlicerProg
TESTING: STARTED
PRE : 9945 0
POST: 9945 9945
PRE : 9945 0
POST: 9945 9945
TESTING: STOPPED

========================================
I have a separate build of Slicer available under a branch named "InstrumentForBRAINSFitFailures" at git@github.com:hjmjohnson/Slicer.git ( a version built on top of today's SlicerSVN)

This branch includes a version of BRAINSTools with a very small program that demonstrates the problem we are seeing in BRAINSFit.

I still think there is something that is overwriting the vtable of this object, and that is the root cause of our problems, but I don't know how to continue debugging that guess.

This is mostly for my own note taking:
There are the experiments that I have done to try to figure out what the heck is going on:

"StandAlone Shared library build of BRAINSTools"
BSA_BASE=/scratch/johnsonhj/src/BT_FAILURED_SHARED/BT-DEBUG-SHARED/

"Slicer build of BRAINSTools"
SLICER_BASE=/Volumes/scratch/johnsonhj/src/Slicer-DEBUG

TEST #1: [PASS]
===========================
BIN=${BSA_BASE}/bin/BRAINSFit
DYLD_LIBRARY_PATH=${BSA_BASE}/ITKv4-install/lib

TEST #2: [PASS]
===========================
BIN=${SLICER_BASE}/Slicer-build/lib/Slicer-4.2/cli-modules/BRAINSFit
DYLD_LIBRARY_PATH=${BSA_BASE}/ITKv4-install/lib

TEST #3: [FAIL]
===========================
BIN=${BSA_BASE}/bin/BRAINSFit
DYLD_LIBRARY_PATH=${SLICER_BASE}/ITKv4-build/lib

TEST #4: [FAIL]
===========================
BIN=${SLICER_BASE}/Slicer-build/lib/Slicer-4.2/cli-modules/BRAINSFit
DYLD_LIBRARY_PATH=${SLICER_BASE}/ITKv4-build/lib

TEST #5: [FAIL]
================================
Build with DICOM support turned off.
BIN=${SLICER_BASE}/Slicer-build/lib/Slicer-4.2/cli-modules/BRAINSFit
DYLD_LIBRARY_PATH=${SLICER_BASE}/ITKv4-build/lib

TEST #6: [FAIL]
================================
Build minimum CLI based program to replicate the problem.

When debugging TEST #6 I put a break point at:
/Volumes/scratch/johnsonhj/src/Slicer-DEBUG/BRAINSTools/BRAINSFit/DebugSlicerCLI.cxx line 59
59├> std::cout << "PRE : " << LBFGSBoptimizer->GetUpperBound().size() << " " << upperBound.size() << std::endl;

When stepping into the line, it reports segfault at line 209 of /Volumes/scratch/johnsonhj/src/Slicer-DEBUG/ITKv4/Modules/Numerics/Optimizers/src/itkLBFGSBOptimizer.cxx
204│ void
205│ LBFGSBOptimizer
206│ ::SetUpperBound(
207│ const BoundValueType & value)
208│ {
209├> m_UpperBound = value;
210│ if ( m_OptimizerInitialized )
211│ {
212│ m_VnlOptimizer->set_upper_bound(m_UpperBound);
213│ }
214│
215│ this->Modified();
216│ }

NOTE: NOTE: NOTE: Line 59 of DebugSlicerCLI.cxx DOES NOT CALL "SetUpperBound" it calls "GetUpperBound", and that is the same type of problem we are seeing in BRAINSFit.

ITKv4 Migration plan

2012-12-05T15:28:10Z

Hjmjohnson: /* Timeline */

[[Slicer4#Plan| Back to Slicer]]

=Overview=

This page is designed to identify and track the work that needs to be done during the month of 2012-12-01 to 2012-12-31 in order to transition Slicer to a solid and uniform ITKv4 platform. Originally this document, created following the NAMIC Engineering TCon of July 28th [http://wiki.na-mic.org/Wiki/index.php/Engineering:TCON_2011#2011-07-28], discuss the element that should be considered before transitioning Slicer to ITKv4.

Historical and other old pages with possibly outdated information. If the information on these other pages is relevant, they need to be pushed here.

* http://www.slicer.org/slicerWiki/index.php/ITKv4_Migration_plan
* http://www.slicer.org/slicerWiki/index.php/Developer_Meetings/20121106#ITKv4
* http://wiki.na-mic.org/Wiki/index.php/Engineering:TCON_2011#2011-07-28

== Issue To Address ==

== Timeline ==
{| border="1" style="color:firebrick; background-color:ltgrey;" cellpadding="5" class="wikitable"
|+ Issues for migration to ITKv4
|-
! _Due_Date_
! Progress Status
! Team Members
! Description
|-
| 2012-12-31
| Started
| Hans J., Steve P., JC, Bill L., Matt M., Kent W.
| http://www.na-mic.org/Bug/search.php?project_id=3&sticky_issues=on&sortby=last_updated&dir=DESC&hide_status_id=80&tag_string=ITKv4
|-
| 2012-12-05
|
| Steve P., Bill L., Matt M., Kent W.
| Test Slicer/ITKv4 on all platforms, especially 64bit VS2008. ( see comments in table below for checkout information: 2012-12-01 )
|-
| 2012-12-05
|
| Matt M., Bill L.
| Look into reducing the number of ITKv4 Modules enabled when building
|-
| N/A to ITKv4
|
| Matt M., Steve P., Bill L., Matt M.
| Slicer modules to reduce load time on Windows
|-
|}

== Timeline ==
{| border="1" style="color:green; background-color:white;" cellpadding="10" class="wikitable"
|+ Timeline for ITKv4
|-
! _Due_Date_
! Progress Status
! Description
|-
| style="background-color: orange;"| 2012-12-01
| style="background-color: orange;"| Done
| style="background-color: orange;" |Hans provides a first pass reference set of patches that build on Mac and demonstrates that nearly all functionality is maintained identically between ITKv3 and ITKv4
|-
|
|
| I've successfully created a mac dmg package. "CPack: - package: /Users/johnsonhj/src/Slicer-git-itkv4/Slicer-build/Slicer-4.2.0-macosx-amd64.dmg generated." 
The package is not yet completely successful though :(.  It seems to run just fine on the machine I used to build the package, but when running on my wifes laptop, it can not find a Qt library in /usr/local/lib/

This is probably something best left for discussion next Wednesday.

I am building on 10.8 with a private build of clang 3.1 tagged as stable from svn. 
I also installed homebrew, and from that installed QT 4.8.3. ( I manually set the required Qt version to 4.8.3)

*FROM THE SAME SOURCE TREE* I also am building Slicer built with ITKv3, and that also seems to be building a reasonable package.

<pre style="font-size: 13px;">
git clone git@github.com:BRAINSia/Slicer43.git
cd Slicer43
git checkout origin/next-slicer43 –b next-slicer43
cd ../ && mkdir sl-itkv3 && sl-itkv3 && CC=/opt/clang31/bin/clang CXX=/opt/clang31/bin/clang++ ccmake –DITK_VERSION_MAJOR:STRING=3 ../Slicer43
cd ../ && mkdir sl-itkv4 && sl-itkv4 && CC=/opt/clang31/bin/clang CXX=/opt/clang31/bin/clang++ ccmake –DITK_VERSION_MAJOR:STRING=4 ../Slicer43
</pre>
|-
| style="background-color: orange;"| 2012-12-05
| style="background-color: orange;"|
| style="background-color: orange;"| Matt McCormick coordinates a Google Hang out
|-
|
|
| In preparation for the upcoming Slicer 4.3 and the NA-MIC Winter Project Week, we are planning a hackathon to help with migration to ITKv4 as the default version of ITK in Slicer.  For some time, community members such as Hans Johnson, Bill Lorensen, and Jean-Christophe Fillion-Robin have made sure ITKv4 works well with Slicer, and we hope to gather and focus on remaining issues that should be addressed.

The hackathon will take place on:  <br\>

* Wednesday, December 5th from 10AM Eastern Time until we run out of energy :-). <br\>
* Primary Connection Information: Google Hangout to be announce at 10AM Eastern time on the ITK and Slicer mailing lists. The link to join the hangout: https://plus.google.com/hangouts/_/a52d596290231e5806eec50e14ab2dcddad72fcd?authuser=2&eid=106512397331641956186&hl=en
* Fallback/Auxiliary connection information: GoTo Meeting for sharing screens with mouse control: <br\>
Please join my meeting, Dec 5, 2012 at 9:00 AM CST. <br\>
https://www1.gotomeeting.com/join/739397184 <br\>
Meeting ID: 739-397-184<br\>


<div style="font-size: 13px;">The hackathon will take place on a Google+ Hangout.  I will follow up with the link to the hangout on this email thread when we starts.</div>

Issues to address at Google Hangout:

Issues in the Slicer bug tracker with the ITKv4 tag: ( See table above )

If there are other issues to address, please report them in the Slicer bug tracker and reply to this thread.

Work will occur on the following repository on Github.   https://github.com/BRAINSia/Slicer43
|-
| style="background-color: orange;"| 2012-12-
| style="background-color: orange;"|
| style="background-color: orange;"|
|-
|
|
|
|-
| style="background-color: orange;"| 2012-12-
| style="background-color: orange;"|
| style="background-color: orange;"|
|-
|
|
|
|-
| style="background-color: orange;"| 2012-12-
| style="background-color: orange;"|
| style="background-color: orange;"|
|-
|
|
|
|-
| style="background-color: orange;"| 2012-12-
| style="background-color: orange;"|
| style="background-color: orange;"|
|-
|
|
|
|-
| style="background-color: orange;"| 2012-12-
| style="background-color: orange;"|
| style="background-color: orange;"|
|-
|
|
|
|-

|}

= Historical (and probably outdated) information =

== Consensus as of 2011 ==

* Slicer RSNA 2011 will be built against ITKv3

* External module requiring ITKv4 will be linked statically against ITKv4
** Associated command line module will be built as executable only. Indeed having both ITKv3 and ITKv4 in the same process will most likely result in some weird symbol clash.

=== Questions ===

* Should each extension depending on ITKv4 download and build its own copy of ITKv4 or should Slicer build and expose both ITKv3 and ITKv4 ?

== Custom MetaIO in SlicerITK ==

* To minimize memory usage and increase efficiency of Command line module execution, itkImageFileReader.txx in SlicerITK has been patched. See https://github.com/Slicer/ITK/commit/8c73dc57e4ae67328ff8e44934b72fd4cc5d4dd3 and https://github.com/Slicer/ITK/commit/12349021b152ac6546c2caf09bbbee4266baddad

* Bill mentioned it should be possible to avoid patching SlicerITK by creating a custom Factory / plugins.

* From Bradley Lowekamp - ITK mailing list - Sun, Jul 17, 2011 at 11:33 AM subject '''Re: [Insight-developers] ITK 3 tag to use with slicer? Fwd: Slicer release schedule'''

<pre>
Stephen,

If I understand this change correctly, this patch allows the usage of a buffer allocated by the ImageIO to be passed
all the way to the Image class if all the types match up. The is accomplished by adding the following
methods: ImageIO::CanUseOwnBuffer, ImageIO::ReadUsingOwnBuffer() and ImageIO::GetOwnBuffer.

I assume that this change is for the MemoryImageFileReader that is used with Slicer. ( can see how this could be
quite advantageous ( and also the potential for scary alias when combined with InPlace filters ). But as not one
single ITK ImageIO has support for these methods. I'd like to question if they should be brought into the ITK main repo,
as they don't appear to currently provide any benefit to ITK and only complicate as already complicated interface to the
ImageIO. If these changes are desired in ITK, then I would strongly encourage better documentation for the new methods in
ImageIO, to enable new developers with add this feature to ImageIO classes.

Brad
</pre>

* From Bill - Thu, Jul 28, 2011 at 5:19 PM '''Re: [slicer-devel] Engineering:TCON 2011 - NAMIC'''
<pre>
I checked the patches. Two classes are patched: ImageIOBase and ImageFileReader. Now I do not think my factory idea is worthwhile.
We should to bring the changes into ITK, and convert ITK's Meta and Nifti ImageIO's to use it.

Bill
</pre>

* In the na-mic tcon it was discussed that nrrd and nifti readers also perform the memcpy since the native libraries perform the Information and Read steps in a single API call. Therefor if the feature existed at the ITK level, then several readers could take advantage of it.

Documentation/4.2/Developers/Build Instructions/Prerequisites/Qt

2012-12-04T19:38:41Z

Hjmjohnson: /* Download links */

= Binary vs build-from-source ? =

If you build Slicer on ...

== Linux ==

* Using [[#Download_links|binary]] works great for both '''Debug''' and '''Release''' build of Slicer. See [[#Download_links]] and [[#Installation_instruction]]

== Mac ==

* Using [[#Download_links|binary]] works great for both '''Debug''' and '''Release''' build of Slicer. See [[#Download_links]] and [[#Installation_instruction]]

* To use QtCreator and the Slicer designer plugins, a possible option is to build QtCreator against the installed Qt libraries. See [http://slicer-devel.65872.n3.nabble.com/Using-Qt-Creator-with-Slicer4-On-Mac-OS-X-Multiple-Qt-libs-loaded-tp4026660p4026690.html discussion on the mailing list].

== Windows ==

=== Debug (32 and 64-bit) or Release (64-bit) ===

* You have to build Qt from source. See [[#Download_links]] and [[#Windows_4|Build instructions]]

{{note}} Using the Qt Designer on Windows requires that the Slicer plugins are [http://doc.trolltech.com/4.6/deployment-plugins.html#debugging-plugins|compiled in the same mode as Qt]. If Qt was compiled in Release mode (default), Slicer would have to be compiled in Release mode as well. However if Qt is compiled in Debug mode only, Slicer has to be compiled in Debug too. When Qt is in "Release and Debug" mode only the Release version of Designer.exe is generated, Slicer would have to be compiled in Release. So for developers, the Debug mode is recommended, this is why we detail the compilation of Qt below.

=== Release (32-bit) ===

* Using [[#Download_links|binary]] works great for 32-bit Release build of Slicer. See [[#Download_links]] and [[#Installation_instruction]]

 

= Download Qt: Source and Binaries =

== Download links ==

The following table list the link allowing to download either the '''recommended''' source code or binary of Qt.

{| border="1" style="margin-left: 20px;"
|- bgcolor="#FFFFCC"
!rowspan="3"|
!colspan="2" rowspan="2"|Linux
!colspan="2"|Mac
!colspan="4"|Windows
|- bgcolor="#FFFFCC"
!colspan="1"|<del>Tiger</del>
!colspan="1"|Leopard, SnowLeopard
!colspan="2"|VS2008
!colspan="2"|VS2010
|- bgcolor="#FFFFCC"
!|32bits
!|64bits
!|<del>32bits</del>
!|64bits
!|32bits
!|64bits
!|32bits
!|64bits
|-
! bgcolor="#FFFFCC" | [http://get.qt.nokia.com/qt/source/ Qt source link]
|align="center" colspan="2"| [http://get.qt.nokia.com/qt/source/qt-everywhere-opensource-src-4.7.4.tar.gz 4.7.4]
|style="background-color:#C0C0C0;" align="center" colspan="1"| <del>[http://get.qt.nokia.com/qt/source/qt-everywhere-opensource-src-4.7.4.tar.gz 4.7.4]</del>
|align="center" colspan="1"| [http://get.qt.nokia.com/qt/source/qt-everywhere-opensource-src-4.7.4.tar.gz 4.7.4]
|align="center" colspan="2"| [http://get.qt.nokia.com/qt/source/qt-everywhere-opensource-src-4.7.4.zip 4.7.4]
|align="center" colspan="2"| [http://get.qt.nokia.com/qt/source/qt-everywhere-opensource-src-4.7.4.zip 4.7.4]
|-
! bgcolor="#FFFFCC" | [http://get.qt.nokia.com/qt/source/ Qt binary link]
|align="center" colspan="1"| [http://sw.nokia.com/id/8ea74da4-fec1-4277-8b26-c58cc82e204b/Qt_SDK_Lin32_offline SDK-1.2]
|align="center" colspan="1"| [http://sw.nokia.com/id/14b2039c-0e1f-4774-a4f2-9aa60b6d5313/Qt_SDK_Lin64_offline SDK-1.2]
|style="background-color:#C0C0C0;" align="center" colspan="1"| <del>[http://get.qt.nokia.com/qt/source/qt-mac-carbon-opensource-4.7.0.dmg carbon_4.7.0]</del>
|align="center" colspan="1"| [ftp://ftp.qt.nokia.com/qt/source/qt-mac-opensource-4.7.4.dmg 4.7.4] [ftp://ftp.qt.nokia.com/qt/source/qt-mac-opensource-4.7.4-debug-libs.dmg 4.7.4 (optional: debug libs)]

|align="center" colspan="1"| [http://get.qt.nokia.com/qt/source/qt-win-opensource-4.7.4-vs2008.exe 4.7.4]
|align="center" colspan="1"| (src build only)
|align="center" colspan="1"| [http://get.qt.nokia.com/qt/source/qt-win-opensource-4.7.4-vs2008.exe 4.7.4]
|align="center" colspan="1"| (src build only)
|}

== Installation instruction ==

=== Linux ===

See [[Documentation/{{documentation/version}}/Developers/Build_Instructions/Prerequisites/Qt/Instal_QtSDK1.2_Offline_Linux_64|Qt installation guide (4.7.4, Linux, 64-bit, Offline)]]

=== Mac ===

TBD

=== Windows ===

TBD

== Qt version specific issues ==

=== All ===

* '''Qt 4.6.x''' on windows (and possibly in linux/mac): No image base64 support in QLabel/QTooltips (work around exists though)
* '''Qt 4.8''' does not work with PythonQt in slicer4 - suggested version is 4.7.4

=== Linux ===

* NA

=== Mac ===

* '''Qt 4.6''': hard to compile - TBD: Be more specific
* '''Qt 4.7''': click outside of popup (http://na-mic.org/Mantis/view.php?id=1241) - Is it fixed in Qt 4.8 ?
* '''Qt 4.7.3''': http://na-mic.org/Mantis/view.php?id=1388 - Fixed in Qt 4.7.4

=== Windows ===

* NA

== How to change the minimum required version ? ==

* It's indeed possible to use a different version, just be aware that moving forward in time, things may not work as expected. Even worse Slicer may simply fail to compile.

* By configuring Slicer using <code>-DSlicer_REQUIRED_QT_VERSION:STRING=4.7.0</code>, you will be able to change the minimum required version.

* See [https://github.com/Slicer/Slicer/commit/898bb14e 898bb14e], [http://viewvc.slicer.org/viewvc.cgi/Slicer4?view=revision&revision=19698 r19698], [http://massmail.spl.harvard.edu/public-archives/slicer-devel/2012/008130.html Mailing list]

 

= Build instructions =
 
{{mbox
| text = Please, make sure that your IDE/compiler is '''properly installed''' and that all associated '''ServicePack''' are also installed. See [[Documentation/{{documentation/version}}/Developers/Build_Instructions/Prerequisites|Prerequisites]].
}}
 

== Linux ==


* Consider installing the following optional packages (<code>libxt-dev libxrender-dev libxrandr-dev libxinerama-dev libxcursor-dev libfontconfig-dev libglib2.0-dev</code>)

<pre>
mkdir qt-everywhere-opensource-build-4.7.4
tar xvfz qt-everywhere-opensource-src-4.7.4.tar.gz
cd qt-everywhere-opensource-src-4.7.4
./configure -prefix ../qt-everywhere-opensource-build-4.7.4 -debug-and-release -opensource -confirm-license -no-qt3support -webkit -nomake examples -nomake demos
make -j8
make install
</pre>

Note: Adapt <code>-j8</code> with the number of core on your machine, a dual core should probably not do more than <code>-j3</code>, an 8 core machine can resonably go as much as <code>-j12</code>.

== Mac ==

Similar to Linux configuration. Note that <code>-arch x86_64</code> has been added.

For earlier versions of Xcode and Mac OS X
<pre>
mkdir qt-everywhere-opensource-build-4.7.4
tar xvfz qt-everywhere-opensource-src-4.7.4.tar.gz
cd qt-everywhere-opensource-src-4.7.4
./configure -prefix ../qt-everywhere-opensource-build-4.7.4 -debug-and-release -opensource -confirm-license -no-qt3support -webkit -arch x86_64 -nomake examples -nomake demos -sdk /Developer/SDKs/MacOSX10.5.sdk/
make -j8
make install
</pre>

On the latest Xcode versions (4.3) and Lion (10.7) the Developer directories have moved. The command is now:

<pre>
./configure -prefix ../qt-everywhere-opensource-build-4.7.4 -debug-and-release -opensource -confirm-license -no-qt3support -arch x86_64 -nomake examples -nomake demos -webkit -sdk /Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX10.7.sdk
</pre>

* Consider reading: http://doc.qt.nokia.com/4.7/developing-on-mac.html)

* Note:
** If building against SDK 10.6 or 10.7, you will probably get link errors similar to what's described in [https://trac.macports.org/ticket/30346] and [http://qt-project.org/forums/viewthread/15933]. The solution is probably to disable the <code>corewlan</code> module but didn't figure out to do that properly.

== Windows ==

# Use a windows extracter to unzip the [[Documentation/{{documentation/version}}/Developers/Build_Instructions/Prerequisites/Qt#Download_links|Qt archive]], don't use cygwin unzip it.
# launch the msvc2008 command prompt (MSVC08->Tools->Visual Studio 2008 CommandPrompt) (or: launch cmd.exe and run <code>vcvars32.bat</code>) Note: Start x64 prompt from Start menu (don't start from inside visual studio or it will be an x86 32 bit shell). Menu item is "Visual Studio 2008 x64 Win64 Command Prompt"
# build with <code>configure.exe -platform win32-msvc2008 -opensource -confirm-license -debug -webkit -nomake examples -nomake demos</code>
#* When asked, choose open source license type (o), then accept the license (y)
#* Note: the option <code>-prefix</code> doesn't work on Windows.
#* Note: According to [http://qt.nokia.com/doc/4.7/supported-platforms.html] Qt does not support msvc2008 on windows xp. However, running <code>configure.exe</code> with no <code>-platform</code> argument seems to work. If you run configure with the <code>-platform</code> argument first by mistake, and if <code>configure -clean</code> doesn't work, then you may need to start from a fresh extraction from the .zip archive before running <code>configure.exe</code> again with no <code>-platform</code>, unless you can run <code>nmake</code> with the config clean target.
#* Note: for Microsoft Visual Studio 2010 users, Qt 4.6.3 is hard to configure with MSVC2010, use Qt 4.7.x instead. Build with <code>set QMAKESPEC=win32-msvc2010</code> and <code>configure -platform win32-msvc2010 -debug</code>
# run <code>nmake</code>
#* Note: building with webkit support requires that src/3rdparty/webkit/WebCore/tmp/moc/{debug,release}_shared/mocinclude.tmp be removed. else you will get linker errors like <code>QNetworkReplyHandler.obj : error LNK2001: unresolved external symbol "public: virtual struct QMetaObject const * __thiscall WebCore::FormDataIODevice::metaObject(void)const (?metaObject@FormDataIODevice@WebCore@@UBEPBUQMetaObject@@XZ)</code>
#* Note: If you encounter the following error <code>api\qscriptextensionplugin.h(43): Error: Undefined interface,</code>, delete the files \src\script\tmp\moc\debug_shared\mocinclude.tmp and \src\script\tmp\moc\release_shared\mocinclude.tmp and restart nmake. For more info, please see [http://bugreports.qt.nokia.com/browse/QTBUG-6470 QTBug 6470]].

ITKv4 Migration plan

2012-12-01T17:11:48Z

Hjmjohnson: /* Timeline */

[[Slicer4#Plan| Back to Slicer]]

=Overview=

This page is designed to identify and track the work that needs to be done during the month of 2012-12-01 to 2012-12-31 in order to transition Slicer to a solid and uniform ITKv4 platform. Originally this document, created following the NAMIC Engineering TCon of July 28th [http://wiki.na-mic.org/Wiki/index.php/Engineering:TCON_2011#2011-07-28], discuss the element that should be considered before transitioning Slicer to ITKv4.

Historical and other old pages with possibly outdated information. If the information on these other pages is relevant, they need to be pushed here.

* http://www.slicer.org/slicerWiki/index.php/ITKv4_Migration_plan </li>
* http://www.slicer.org/slicerWiki/index.php/Developer_Meetings/20121106#ITKv4 </li>
* http://wiki.na-mic.org/Wiki/index.php/Engineering:TCON_2011#2011-07-28 </li>

== Issue To Address ==

== Timeline ==
{| border="1" style="color:red; background-color:ltgrey;" cellpadding="5" class="wikitable"
|+ Issues for migration to ITKv4
|-
! _Due_Date_
! Progress Status
! Team Members
! Description
|-
| 2012-12-31
| Started
| Hans J., Steve P., JC, Bill L., Matt M., Kent W.
| http://www.na-mic.org/Bug/search.php?project_id=3&sticky_issues=on&sortby=last_updated&dir=DESC&hide_status_id=80&tag_string=ITKv4
|-
| 2012-12-05
|
| Steve P., Bill L., Matt M., Kent W.
| Test Slicer/ITKv4 on all platforms, especially 64bit VS2008. ( see comments in table below for checkout information: 2012-12-01 )
|-
| 2012-12-05
|
| Matt M., Bill L.
| Look into reducing the number of ITKv4 Modules enabled when building
|-
| N/A to ITKv4
|
| Matt M., Steve P., Bill L., Matt M.
| Slicer modules to reduce load time on Windows
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|-
|}

== Timeline ==
{| border="1" style="color:green; background-color:white;" cellpadding="10" class="wikitable"
|+ Timeline for ITKv4
|-
! _Due_Date_
! Progress Status
! Description
|-
| style="background-color: orange;"| 2012-12-01
| style="background-color: orange;"| Done
| style="background-color: orange;" |Hans provides a first pass reference set of patches that build on Mac and demonstrates that nearly all functionality is maintained identically between ITKv3 and ITKv4
|-
|
|
| I've successfully created a mac dmg package. "CPack: - package: /Users/johnsonhj/src/Slicer-git-itkv4/Slicer-build/Slicer-4.2.0-macosx-amd64.dmg generated." 
The package is not yet completely successful though :(.  It seems to run just fine on the machine I used to build the package, but when running on my wifes laptop, it can not find a Qt library in /usr/local/lib/

This is probably something best left for discussion next Wednesday.

I am building on 10.8 with a private build of clang 3.1 tagged as stable from svn. 
I also installed homebrew, and from that installed QT 4.8.3. ( I manually set the required Qt version to 4.8.3)

*FROM THE SAME SOURCE TREE* I also am building Slicer built with ITKv3, and that also seems to be building a reasonable package.

<pre style="font-size: 13px;">
git clone git@github.com:BRAINSia/Slicer43.git
cd Slicer43
git checkout origin/AddDWIConvert –b AddDWIConvert
cd ../ && mkdir sl-itkv3 && sl-itkv3 && CC=/opt/clang31/bin/clang CXX=/opt/clang31/bin/clang++ ccmake –DITK_VERSION_MAJOR:STRING=3 ../Slicer43
cd ../ && mkdir sl-itkv4 && sl-itkv4 && CC=/opt/clang31/bin/clang CXX=/opt/clang31/bin/clang++ ccmake –DITK_VERSION_MAJOR:STRING=4 ../Slicer43
</pre>
|-
| style="background-color: orange;"| 2012-12-05
| style="background-color: orange;"|
| style="background-color: orange;"| Matt McCormick coordinates a Google Hang out
|-
|
|
| In preparation for the upcoming Slicer 4.3 and the NA-MIC Winter Project Week, we are planning a hackathon to help with migration to ITKv4 as the default version of ITK in Slicer.  For some time, community members such as Hans Johnson, Bill Lorensen, and Jean-Christophe Fillion-Robin have made sure ITKv4 works well with Slicer, and we hope to gather and focus on remaining issues that should be addressed.

The hackathon will take place on:  <br\>

* Wednesday, December 5th from 10AM Eastern Time until we run out of energy :-). <br\>
* Primary Connection Information: << Matt Please Fill this in >> 
* Fallback/Auxiliary connection information: GoTo Meeting for sharing screens with mouse control: <br\>
Please join my meeting, Dec 5, 2012 at 9:00 AM CST. <br\>
https://www1.gotomeeting.com/join/739397184 <br\>
Meeting ID: 739-397-184<br\>


<div style="font-size: 13px;">The hackathon will take place on a Google+ Hangout.  I will follow up with the link to the hangout on this email thread when we starts.</div>

Issues to address at Google Hangout:

Issues in the Slicer bug tracker with the ITKv4 tag: ( See table above )

If there are other issues to address, please report them in the Slicer bug tracker and reply to this thread.

Work will occur on the following repository on Github.   https://github.com/BRAINSia/Slicer43
|-
| style="background-color: orange;"| 2012-12-
| style="background-color: orange;"|
| style="background-color: orange;"|
|-
|
|
|
|-
| style="background-color: orange;"| 2012-12-
| style="background-color: orange;"|
| style="background-color: orange;"|
|-
|
|
|
|-
| style="background-color: orange;"| 2012-12-
| style="background-color: orange;"|
| style="background-color: orange;"|
|-
|
|
|
|-
| style="background-color: orange;"| 2012-12-
| style="background-color: orange;"|
| style="background-color: orange;"|
|-
|
|
|
|-
| style="background-color: orange;"| 2012-12-
| style="background-color: orange;"|
| style="background-color: orange;"|
|-
|
|
|
|-

|}

= Historical (and probably outdated) information =

== Consensus as of 2011 ==

* Slicer RSNA 2011 will be built against ITKv3

* External module requiring ITKv4 will be linked statically against ITKv4
** Associated command line module will be built as executable only. Indeed having both ITKv3 and ITKv4 in the same process will most likely result in some weird symbol clash.

=== Questions ===

* Should each extension depending on ITKv4 download and build its own copy of ITKv4 or should Slicer build and expose both ITKv3 and ITKv4 ?

== Custom MetaIO in SlicerITK ==

* To minimize memory usage and increase efficiency of Command line module execution, itkImageFileReader.txx in SlicerITK has been patched. See https://github.com/Slicer/ITK/commit/8c73dc57e4ae67328ff8e44934b72fd4cc5d4dd3 and https://github.com/Slicer/ITK/commit/12349021b152ac6546c2caf09bbbee4266baddad

* Bill mentioned it should be possible to avoid patching SlicerITK by creating a custom Factory / plugins.

* From Bradley Lowekamp - ITK mailing list - Sun, Jul 17, 2011 at 11:33 AM subject '''Re: [Insight-developers] ITK 3 tag to use with slicer? Fwd: Slicer release schedule'''

<pre>
Stephen,

If I understand this change correctly, this patch allows the usage of a buffer allocated by the ImageIO to be passed
all the way to the Image class if all the types match up. The is accomplished by adding the following
methods: ImageIO::CanUseOwnBuffer, ImageIO::ReadUsingOwnBuffer() and ImageIO::GetOwnBuffer.

I assume that this change is for the MemoryImageFileReader that is used with Slicer. ( can see how this could be
quite advantageous ( and also the potential for scary alias when combined with InPlace filters ). But as not one
single ITK ImageIO has support for these methods. I'd like to question if they should be brought into the ITK main repo,
as they don't appear to currently provide any benefit to ITK and only complicate as already complicated interface to the
ImageIO. If these changes are desired in ITK, then I would strongly encourage better documentation for the new methods in
ImageIO, to enable new developers with add this feature to ImageIO classes.

Brad
</pre>

* From Bill - Thu, Jul 28, 2011 at 5:19 PM '''Re: [slicer-devel] Engineering:TCON 2011 - NAMIC'''
<pre>
I checked the patches. Two classes are patched: ImageIOBase and ImageFileReader. Now I do not think my factory idea is worthwhile.
We should to bring the changes into ITK, and convert ITK's Meta and Nifti ImageIO's to use it.

Bill
</pre>

* In the na-mic tcon it was discussed that nrrd and nifti readers also perform the memcpy since the native libraries perform the Information and Read steps in a single API call. Therefor if the feature existed at the ITK level, then several readers could take advantage of it.

ITKv4 Migration plan

2012-12-01T17:10:53Z

Hjmjohnson: /* Timeline */

[[Slicer4#Plan| Back to Slicer]]

=Overview=

This page is designed to identify and track the work that needs to be done during the month of 2012-12-01 to 2012-12-31 in order to transition Slicer to a solid and uniform ITKv4 platform. Originally this document, created following the NAMIC Engineering TCon of July 28th [http://wiki.na-mic.org/Wiki/index.php/Engineering:TCON_2011#2011-07-28], discuss the element that should be considered before transitioning Slicer to ITKv4.

Historical and other old pages with possibly outdated information. If the information on these other pages is relevant, they need to be pushed here.

* http://www.slicer.org/slicerWiki/index.php/ITKv4_Migration_plan </li>
* http://www.slicer.org/slicerWiki/index.php/Developer_Meetings/20121106#ITKv4 </li>
* http://wiki.na-mic.org/Wiki/index.php/Engineering:TCON_2011#2011-07-28 </li>

== Issue To Address ==

== Timeline ==
{| border="1" style="color:red; background-color:ltgrey;" cellpadding="5" class="wikitable"
|+ Issues for migration to ITKv4
|-
! _Due_Date_
! Progress Status
! Team Members
! Description
|-
| 2012-12-31
| Started
| Hans J., Steve P., JC, Bill L., Matt M., Kent W.
| http://www.na-mic.org/Bug/search.php?project_id=3&sticky_issues=on&sortby=last_updated&dir=DESC&hide_status_id=80&tag_string=ITKv4
|-
| 2012-12-05
|
| Steve P., Bill L., Matt M., Kent W.
| Test Slicer/ITKv4 on all platforms, especially 64bit VS2008.
|-
| 2012-12-05
|
| Matt M., Bill L.
| Look into reducing the number of ITKv4 Modules enabled when building
|-
| N/A to ITKv4
|
| Matt M., Steve P., Bill L., Matt M.
| Slicer modules to reduce load time on Windows
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|-
|}

== Timeline ==
{| border="1" style="color:green; background-color:white;" cellpadding="10" class="wikitable"
|+ Timeline for ITKv4
|-
! _Due_Date_
! Progress Status
! Description
|-
| style="background-color: orange;"| 2012-12-01
| style="background-color: orange;"| Done
| style="background-color: orange;" |Hans provides a first pass reference set of patches that build on Mac and demonstrates that nearly all functionality is maintained identically between ITKv3 and ITKv4
|-
|
|
| I've successfully created a mac dmg package. "CPack: - package: /Users/johnsonhj/src/Slicer-git-itkv4/Slicer-build/Slicer-4.2.0-macosx-amd64.dmg generated." 
The package is not yet completely successful though :(.  It seems to run just fine on the machine I used to build the package, but when running on my wifes laptop, it can not find a Qt library in /usr/local/lib/

This is probably something best left for discussion next Wednesday.

I am building on 10.8 with a private build of clang 3.1 tagged as stable from svn. 
I also installed homebrew, and from that installed QT 4.8.3. ( I manually set the required Qt version to 4.8.3)

*FROM THE SAME SOURCE TREE* I also am building Slicer built with ITKv3, and that also seems to be building a reasonable package.

<pre style="font-size: 13px;">
git clone git@github.com:BRAINSia/Slicer43.git
cd Slicer43
git checkout origin/AddDWIConvert –b AddDWIConvert
cd ../ && mkdir sl-itkv3 && sl-itkv3 && CC=/opt/clang31/bin/clang CXX=/opt/clang31/bin/clang++ ccmake –DITK_VERSION_MAJOR:STRING=3 ../Slicer43
cd ../ && mkdir sl-itkv4 && sl-itkv4 && CC=/opt/clang31/bin/clang CXX=/opt/clang31/bin/clang++ ccmake –DITK_VERSION_MAJOR:STRING=4 ../Slicer43
</pre>
|-
| style="background-color: orange;"| 2012-12-05
| style="background-color: orange;"|
| style="background-color: orange;"| Matt McCormick coordinates a Google Hang out
|-
|
|
| In preparation for the upcoming Slicer 4.3 and the NA-MIC Winter Project Week, we are planning a hackathon to help with migration to ITKv4 as the default version of ITK in Slicer.  For some time, community members such as Hans Johnson, Bill Lorensen, and Jean-Christophe Fillion-Robin have made sure ITKv4 works well with Slicer, and we hope to gather and focus on remaining issues that should be addressed.

The hackathon will take place on:  <br\>

* Wednesday, December 5th from 10AM Eastern Time until we run out of energy :-). <br\>
* Primary Connection Information: << Matt Please Fill this in >> 
* Fallback/Auxiliary connection information: GoTo Meeting for sharing screens with mouse control: <br\>
Please join my meeting, Dec 5, 2012 at 9:00 AM CST. <br\>
https://www1.gotomeeting.com/join/739397184 <br\>
Meeting ID: 739-397-184<br\>


<div style="font-size: 13px;">The hackathon will take place on a Google+ Hangout.  I will follow up with the link to the hangout on this email thread when we starts.</div>

Issues to address at Google Hangout:

Issues in the Slicer bug tracker with the ITKv4 tag: ( See table above )

If there are other issues to address, please report them in the Slicer bug tracker and reply to this thread.

Work will occur on the following repository on Github.   https://github.com/BRAINSia/Slicer43
|-
| style="background-color: orange;"| 2012-12-
| style="background-color: orange;"|
| style="background-color: orange;"|
|-
|
|
|
|-
| style="background-color: orange;"| 2012-12-
| style="background-color: orange;"|
| style="background-color: orange;"|
|-
|
|
|
|-
| style="background-color: orange;"| 2012-12-
| style="background-color: orange;"|
| style="background-color: orange;"|
|-
|
|
|
|-
| style="background-color: orange;"| 2012-12-
| style="background-color: orange;"|
| style="background-color: orange;"|
|-
|
|
|
|-
| style="background-color: orange;"| 2012-12-
| style="background-color: orange;"|
| style="background-color: orange;"|
|-
|
|
|
|-

|}

= Historical (and probably outdated) information =

== Consensus as of 2011 ==

* Slicer RSNA 2011 will be built against ITKv3

* External module requiring ITKv4 will be linked statically against ITKv4
** Associated command line module will be built as executable only. Indeed having both ITKv3 and ITKv4 in the same process will most likely result in some weird symbol clash.

=== Questions ===

* Should each extension depending on ITKv4 download and build its own copy of ITKv4 or should Slicer build and expose both ITKv3 and ITKv4 ?

== Custom MetaIO in SlicerITK ==

* To minimize memory usage and increase efficiency of Command line module execution, itkImageFileReader.txx in SlicerITK has been patched. See https://github.com/Slicer/ITK/commit/8c73dc57e4ae67328ff8e44934b72fd4cc5d4dd3 and https://github.com/Slicer/ITK/commit/12349021b152ac6546c2caf09bbbee4266baddad

* Bill mentioned it should be possible to avoid patching SlicerITK by creating a custom Factory / plugins.

* From Bradley Lowekamp - ITK mailing list - Sun, Jul 17, 2011 at 11:33 AM subject '''Re: [Insight-developers] ITK 3 tag to use with slicer? Fwd: Slicer release schedule'''

<pre>
Stephen,

If I understand this change correctly, this patch allows the usage of a buffer allocated by the ImageIO to be passed
all the way to the Image class if all the types match up. The is accomplished by adding the following
methods: ImageIO::CanUseOwnBuffer, ImageIO::ReadUsingOwnBuffer() and ImageIO::GetOwnBuffer.

I assume that this change is for the MemoryImageFileReader that is used with Slicer. ( can see how this could be
quite advantageous ( and also the potential for scary alias when combined with InPlace filters ). But as not one
single ITK ImageIO has support for these methods. I'd like to question if they should be brought into the ITK main repo,
as they don't appear to currently provide any benefit to ITK and only complicate as already complicated interface to the
ImageIO. If these changes are desired in ITK, then I would strongly encourage better documentation for the new methods in
ImageIO, to enable new developers with add this feature to ImageIO classes.

Brad
</pre>

* From Bill - Thu, Jul 28, 2011 at 5:19 PM '''Re: [slicer-devel] Engineering:TCON 2011 - NAMIC'''
<pre>
I checked the patches. Two classes are patched: ImageIOBase and ImageFileReader. Now I do not think my factory idea is worthwhile.
We should to bring the changes into ITK, and convert ITK's Meta and Nifti ImageIO's to use it.

Bill
</pre>

* In the na-mic tcon it was discussed that nrrd and nifti readers also perform the memcpy since the native libraries perform the Information and Read steps in a single API call. Therefor if the feature existed at the ITK level, then several readers could take advantage of it.

ITKv4 Migration plan

2012-12-01T16:38:56Z

Hjmjohnson: /* Overview */

[[Slicer4#Plan| Back to Slicer]]

=Overview=

This page is designed to identify and track the work that needs to be done during the month of 2012-12-01 to 2012-12-31 in order to transition Slicer to a solid and uniform ITKv4 platform. Originally this document, created following the NAMIC Engineering TCon of July 28th [http://wiki.na-mic.org/Wiki/index.php/Engineering:TCON_2011#2011-07-28], discuss the element that should be considered before transitioning Slicer to ITKv4.

Historical and other old pages with possibly outdated information. If the information on these other pages is relevant, they need to be pushed here.

* http://www.slicer.org/slicerWiki/index.php/ITKv4_Migration_plan </li>
* http://www.slicer.org/slicerWiki/index.php/Developer_Meetings/20121106#ITKv4 </li>
* http://wiki.na-mic.org/Wiki/index.php/Engineering:TCON_2011#2011-07-28 </li>

== Timeline ==
{| border="1" style="color:green; background-color:#ffffcc;" cellpadding="10" class="wikitable"
|+ Timeline for ITKv4
|-
! Date
! Status
! Description
|-
| 2012-12-01
| Done
| Hans provides a first pass reference set of patches that build on Mac and demonstrates that nearly all functionality is maintained identically between ITKv3 and ITKv4
|-
|
|
| I've successfully created a mac dmg package. "CPack: - package: /Users/johnsonhj/src/Slicer-git-itkv4/Slicer-build/Slicer-4.2.0-macosx-amd64.dmg generated." 
The package is not yet completely successful though :(.  It seems to run just fine on the machine I used to build the package, but when running on my wifes laptop, it can not find a Qt library in /usr/local/lib/

This is probably something best left for discussion next Wednesday.

I am building on 10.8 with a private build of clang 3.1 tagged as stable from svn. 
I also installed homebrew, and from that installed QT 4.8.3. ( I manually set the required Qt version to 4.8.3)

*FROM THE SAME SOURCE TREE* I also am building Slicer built with ITKv3, and that also seems to be building a reasonable package.

<pre style="font-size: 13px;">
git clone git@github.com:BRAINSia/Slicer43.git
cd Slicer43
git checkout origin/AddDWIConvert –b AddDWIConvert
cd ../ && mkdir sl-itkv3 && sl-itkv3 && CC=/opt/clang31/bin/clang CXX=/opt/clang31/bin/clang++ ccmake –DITK_VERSION_MAJOR:STRING=3 ../Slicer43
cd ../ && mkdir sl-itkv4 && sl-itkv4 && CC=/opt/clang31/bin/clang CXX=/opt/clang31/bin/clang++ ccmake –DITK_VERSION_MAJOR:STRING=4 ../Slicer43
</pre>
|-
| 2012-12-05
|
| Matt McCormick coordinates a Google Hang out
|-
|
|
| In preparation for the upcoming Slicer 4.3 and the NA-MIC Winter Project Week, we are planning a hackathon to help with migration to ITKv4 as the default version of ITK in Slicer.  For some time, community members such as Hans Johnson, Bill Lorensen, and Jean-Christophe Fillion-Robin have made sure ITKv4 works well with Slicer, and we hope to gather and focus on remaining issues that should be addressed.

The hackathon will take place on:  Wednesday, December 5th from 10AM Eastern Time until we run out of energy :-).
<div style="font-size: 13px;">The hackathon will take place on a Google+ Hangout.  I will follow up with the link to the hangout on this email thread when we starts.</div>

Issues to address at Google Hangout:

Issues in the Slicer bug tracker with the ITKv4 tag: <br\>
* http://www.na-mic.org/Bug/search.php?project_id=3&sticky_issues=on&sortby=last_updated&dir=DESC&hide_status_id=80&tag_string=ITKv4
* Test Slicer/ITKv4 on all platforms, especially 64bit VS2008.
* Look into reducing the number of ITK Modules enabled when building
* Slicer modules to reduce load time on Windows

If there are other issues to address, please report them in the Slicer bug tracker and reply to this thread.</div>

Work will occur on the following repository on Github.   https://github.com/BRAINSia/Slicer43</div>
|-

|}

= Historical (and probably outdated) information =

== Consensus as of 2011 ==

* Slicer RSNA 2011 will be built against ITKv3

* External module requiring ITKv4 will be linked statically against ITKv4
** Associated command line module will be built as executable only. Indeed having both ITKv3 and ITKv4 in the same process will most likely result in some weird symbol clash.

=== Questions ===

* Should each extension depending on ITKv4 download and build its own copy of ITKv4 or should Slicer build and expose both ITKv3 and ITKv4 ?

== Custom MetaIO in SlicerITK ==

* To minimize memory usage and increase efficiency of Command line module execution, itkImageFileReader.txx in SlicerITK has been patched. See https://github.com/Slicer/ITK/commit/8c73dc57e4ae67328ff8e44934b72fd4cc5d4dd3 and https://github.com/Slicer/ITK/commit/12349021b152ac6546c2caf09bbbee4266baddad

* Bill mentioned it should be possible to avoid patching SlicerITK by creating a custom Factory / plugins.

* From Bradley Lowekamp - ITK mailing list - Sun, Jul 17, 2011 at 11:33 AM subject '''Re: [Insight-developers] ITK 3 tag to use with slicer? Fwd: Slicer release schedule'''

<pre>
Stephen,

If I understand this change correctly, this patch allows the usage of a buffer allocated by the ImageIO to be passed
all the way to the Image class if all the types match up. The is accomplished by adding the following
methods: ImageIO::CanUseOwnBuffer, ImageIO::ReadUsingOwnBuffer() and ImageIO::GetOwnBuffer.

I assume that this change is for the MemoryImageFileReader that is used with Slicer. ( can see how this could be
quite advantageous ( and also the potential for scary alias when combined with InPlace filters ). But as not one
single ITK ImageIO has support for these methods. I'd like to question if they should be brought into the ITK main repo,
as they don't appear to currently provide any benefit to ITK and only complicate as already complicated interface to the
ImageIO. If these changes are desired in ITK, then I would strongly encourage better documentation for the new methods in
ImageIO, to enable new developers with add this feature to ImageIO classes.

Brad
</pre>

* From Bill - Thu, Jul 28, 2011 at 5:19 PM '''Re: [slicer-devel] Engineering:TCON 2011 - NAMIC'''
<pre>
I checked the patches. Two classes are patched: ImageIOBase and ImageFileReader. Now I do not think my factory idea is worthwhile.
We should to bring the changes into ITK, and convert ITK's Meta and Nifti ImageIO's to use it.

Bill
</pre>

* In the na-mic tcon it was discussed that nrrd and nifti readers also perform the memcpy since the native libraries perform the Information and Read steps in a single API call. Therefor if the feature existed at the ITK level, then several readers could take advantage of it.

ITKv4 Migration plan

2012-12-01T16:36:32Z

Hjmjohnson: /* Consensus as of 2011 */

[[Slicer4#Plan| Back to Slicer]]

=Overview=

This page is designed to identify and track the work that needs to be done during the month of 2012-12-01 to 2012-12-31 in order to transition Slicer to a solid and uniform ITKv4 platform. Originally this document, created following the NAMIC Engineering TCon of July 28th [http://wiki.na-mic.org/Wiki/index.php/Engineering:TCON_2011#2011-07-28], discuss the element that should be considered before transitioning Slicer to ITKv4.

Historical and other old pages with possibly outdated information. If the information on these other pages is relevant, they need to be pushed here.

* http://www.slicer.org/slicerWiki/index.php/ITKv4_Migration_plan </li>
* http://www.slicer.org/slicerWiki/index.php/Developer_Meetings/20121106#ITKv4 </li>
* http://wiki.na-mic.org/Wiki/index.php/Engineering:TCON_2011#2011-07-28 </li>

{| style="color:green; background-color:#ffffcc;" cellpadding="10" class="wikitable"
|+ Timeline for ITKv4
|-
! Date
! Status
! Description
|-
| 2012-12-01
| Done
| Hans provides a first pass reference set of patches that build on Mac and demonstrates that nearly all functionality is maintained identically between ITKv3 and ITKv4
|-
|
|
| I've successfully created a mac dmg package. "CPack: - package: /Users/johnsonhj/src/Slicer-git-itkv4/Slicer-build/Slicer-4.2.0-macosx-amd64.dmg generated." 
The package is not yet completely successful though :(.  It seems to run just fine on the machine I used to build the package, but when running on my wifes laptop, it can not find a Qt library in /usr/local/lib/

This is probably something best left for discussion next Wednesday.

I am building on 10.8 with a private build of clang 3.1 tagged as stable from svn. 
I also installed homebrew, and from that installed QT 4.8.3. ( I manually set the required Qt version to 4.8.3)

*FROM THE SAME SOURCE TREE* I also am building Slicer built with ITKv3, and that also seems to be building a reasonable package.

<pre style="font-size: 13px;">
git clone git@github.com:BRAINSia/Slicer43.git
cd Slicer43
git checkout origin/AddDWIConvert –b AddDWIConvert
cd ../ && mkdir sl-itkv3 && sl-itkv3 && CC=/opt/clang31/bin/clang CXX=/opt/clang31/bin/clang++ ccmake –DITK_VERSION_MAJOR:STRING=3 ../Slicer43
cd ../ && mkdir sl-itkv4 && sl-itkv4 && CC=/opt/clang31/bin/clang CXX=/opt/clang31/bin/clang++ ccmake –DITK_VERSION_MAJOR:STRING=4 ../Slicer43
</pre>
|-
| 2012-12-05
|
| Matt McCormick coordinates a Google Hang out
|-
|
|
| In preparation for the upcoming Slicer 4.3 and the NA-MIC Winter Project Week, we are planning a hackathon to help with migration to ITKv4 as the default version of ITK in Slicer.  For some time, community members such as Hans Johnson, Bill Lorensen, and Jean-Christophe Fillion-Robin have made sure ITKv4 works well with Slicer, and we hope to gather and focus on remaining issues that should be addressed.

The hackathon will take place on:  Wednesday, December 5th from 10AM Eastern Time until we run out of energy :-).
<div style="font-size: 13px;">The hackathon will take place on a Google+ Hangout.  I will follow up with the link to the hangout on this email thread when we starts.</div>

Issues to address at Google Hangout:

Issues in the Slicer bug tracker with the ITKv4 tag: <br\>
* http://www.na-mic.org/Bug/search.php?project_id=3&sticky_issues=on&sortby=last_updated&dir=DESC&hide_status_id=80&tag_string=ITKv4
* Test Slicer/ITKv4 on all platforms, especially 64bit VS2008.
* Look into reducing the number of ITK Modules enabled when building
* Slicer modules to reduce load time on Windows

If there are other issues to address, please report them in the Slicer bug tracker and reply to this thread.</div>

Work will occur on the following repository on Github.   https://github.com/BRAINSia/Slicer43</div>
|-

|}

= Historical (and probably outdated) information =

== Consensus as of 2011 ==

* Slicer RSNA 2011 will be built against ITKv3

* External module requiring ITKv4 will be linked statically against ITKv4
** Associated command line module will be built as executable only. Indeed having both ITKv3 and ITKv4 in the same process will most likely result in some weird symbol clash.

=== Questions ===

* Should each extension depending on ITKv4 download and build its own copy of ITKv4 or should Slicer build and expose both ITKv3 and ITKv4 ?

== Custom MetaIO in SlicerITK ==

* To minimize memory usage and increase efficiency of Command line module execution, itkImageFileReader.txx in SlicerITK has been patched. See https://github.com/Slicer/ITK/commit/8c73dc57e4ae67328ff8e44934b72fd4cc5d4dd3 and https://github.com/Slicer/ITK/commit/12349021b152ac6546c2caf09bbbee4266baddad

* Bill mentioned it should be possible to avoid patching SlicerITK by creating a custom Factory / plugins.

* From Bradley Lowekamp - ITK mailing list - Sun, Jul 17, 2011 at 11:33 AM subject '''Re: [Insight-developers] ITK 3 tag to use with slicer? Fwd: Slicer release schedule'''

<pre>
Stephen,

If I understand this change correctly, this patch allows the usage of a buffer allocated by the ImageIO to be passed
all the way to the Image class if all the types match up. The is accomplished by adding the following
methods: ImageIO::CanUseOwnBuffer, ImageIO::ReadUsingOwnBuffer() and ImageIO::GetOwnBuffer.

I assume that this change is for the MemoryImageFileReader that is used with Slicer. ( can see how this could be
quite advantageous ( and also the potential for scary alias when combined with InPlace filters ). But as not one
single ITK ImageIO has support for these methods. I'd like to question if they should be brought into the ITK main repo,
as they don't appear to currently provide any benefit to ITK and only complicate as already complicated interface to the
ImageIO. If these changes are desired in ITK, then I would strongly encourage better documentation for the new methods in
ImageIO, to enable new developers with add this feature to ImageIO classes.

Brad
</pre>

* From Bill - Thu, Jul 28, 2011 at 5:19 PM '''Re: [slicer-devel] Engineering:TCON 2011 - NAMIC'''
<pre>
I checked the patches. Two classes are patched: ImageIOBase and ImageFileReader. Now I do not think my factory idea is worthwhile.
We should to bring the changes into ITK, and convert ITK's Meta and Nifti ImageIO's to use it.

Bill
</pre>

* In the na-mic tcon it was discussed that nrrd and nifti readers also perform the memcpy since the native libraries perform the Information and Read steps in a single API call. Therefor if the feature existed at the ITK level, then several readers could take advantage of it.

ITKv4 Migration plan

2012-12-01T16:35:51Z

Hjmjohnson: /* Current consensus */

[[Slicer4#Plan| Back to Slicer]]

=Overview=

This page is designed to identify and track the work that needs to be done during the month of 2012-12-01 to 2012-12-31 in order to transition Slicer to a solid and uniform ITKv4 platform. Originally this document, created following the NAMIC Engineering TCon of July 28th [http://wiki.na-mic.org/Wiki/index.php/Engineering:TCON_2011#2011-07-28], discuss the element that should be considered before transitioning Slicer to ITKv4.

Historical and other old pages with possibly outdated information. If the information on these other pages is relevant, they need to be pushed here.

* http://www.slicer.org/slicerWiki/index.php/ITKv4_Migration_plan </li>
* http://www.slicer.org/slicerWiki/index.php/Developer_Meetings/20121106#ITKv4 </li>
* http://wiki.na-mic.org/Wiki/index.php/Engineering:TCON_2011#2011-07-28 </li>

{| style="color:green; background-color:#ffffcc;" cellpadding="10" class="wikitable"
|+ Timeline for ITKv4
|-
! Date
! Status
! Description
|-
| 2012-12-01
| Done
| Hans provides a first pass reference set of patches that build on Mac and demonstrates that nearly all functionality is maintained identically between ITKv3 and ITKv4
|-
|
|
| I've successfully created a mac dmg package. "CPack: - package: /Users/johnsonhj/src/Slicer-git-itkv4/Slicer-build/Slicer-4.2.0-macosx-amd64.dmg generated." 
The package is not yet completely successful though :(.  It seems to run just fine on the machine I used to build the package, but when running on my wifes laptop, it can not find a Qt library in /usr/local/lib/

This is probably something best left for discussion next Wednesday.

I am building on 10.8 with a private build of clang 3.1 tagged as stable from svn. 
I also installed homebrew, and from that installed QT 4.8.3. ( I manually set the required Qt version to 4.8.3)

*FROM THE SAME SOURCE TREE* I also am building Slicer built with ITKv3, and that also seems to be building a reasonable package.

<pre style="font-size: 13px;">
git clone git@github.com:BRAINSia/Slicer43.git
cd Slicer43
git checkout origin/AddDWIConvert –b AddDWIConvert
cd ../ && mkdir sl-itkv3 && sl-itkv3 && CC=/opt/clang31/bin/clang CXX=/opt/clang31/bin/clang++ ccmake –DITK_VERSION_MAJOR:STRING=3 ../Slicer43
cd ../ && mkdir sl-itkv4 && sl-itkv4 && CC=/opt/clang31/bin/clang CXX=/opt/clang31/bin/clang++ ccmake –DITK_VERSION_MAJOR:STRING=4 ../Slicer43
</pre>
|-
| 2012-12-05
|
| Matt McCormick coordinates a Google Hang out
|-
|
|
| In preparation for the upcoming Slicer 4.3 and the NA-MIC Winter Project Week, we are planning a hackathon to help with migration to ITKv4 as the default version of ITK in Slicer.  For some time, community members such as Hans Johnson, Bill Lorensen, and Jean-Christophe Fillion-Robin have made sure ITKv4 works well with Slicer, and we hope to gather and focus on remaining issues that should be addressed.

The hackathon will take place on:  Wednesday, December 5th from 10AM Eastern Time until we run out of energy :-).
<div style="font-size: 13px;">The hackathon will take place on a Google+ Hangout.  I will follow up with the link to the hangout on this email thread when we starts.</div>

Issues to address at Google Hangout:

Issues in the Slicer bug tracker with the ITKv4 tag: <br\>
* http://www.na-mic.org/Bug/search.php?project_id=3&sticky_issues=on&sortby=last_updated&dir=DESC&hide_status_id=80&tag_string=ITKv4
* Test Slicer/ITKv4 on all platforms, especially 64bit VS2008.
* Look into reducing the number of ITK Modules enabled when building
* Slicer modules to reduce load time on Windows

If there are other issues to address, please report them in the Slicer bug tracker and reply to this thread.</div>

Work will occur on the following repository on Github.   https://github.com/BRAINSia/Slicer43</div>
|-

|}

== Consensus as of 2011 ==

* Slicer RSNA 2011 will be built against ITKv3

* External module requiring ITKv4 will be linked statically against ITKv4
** Associated command line module will be built as executable only. Indeed having both ITKv3 and ITKv4 in the same process will most likely result in some weird symbol clash.

=== Questions ===

* Should each extension depending on ITKv4 download and build its own copy of ITKv4 or should Slicer build and expose both ITKv3 and ITKv4 ?

== Custom MetaIO in SlicerITK ==

* To minimize memory usage and increase efficiency of Command line module execution, itkImageFileReader.txx in SlicerITK has been patched. See https://github.com/Slicer/ITK/commit/8c73dc57e4ae67328ff8e44934b72fd4cc5d4dd3 and https://github.com/Slicer/ITK/commit/12349021b152ac6546c2caf09bbbee4266baddad

* Bill mentioned it should be possible to avoid patching SlicerITK by creating a custom Factory / plugins.

* From Bradley Lowekamp - ITK mailing list - Sun, Jul 17, 2011 at 11:33 AM subject '''Re: [Insight-developers] ITK 3 tag to use with slicer? Fwd: Slicer release schedule'''

<pre>
Stephen,

If I understand this change correctly, this patch allows the usage of a buffer allocated by the ImageIO to be passed
all the way to the Image class if all the types match up. The is accomplished by adding the following
methods: ImageIO::CanUseOwnBuffer, ImageIO::ReadUsingOwnBuffer() and ImageIO::GetOwnBuffer.

I assume that this change is for the MemoryImageFileReader that is used with Slicer. ( can see how this could be
quite advantageous ( and also the potential for scary alias when combined with InPlace filters ). But as not one
single ITK ImageIO has support for these methods. I'd like to question if they should be brought into the ITK main repo,
as they don't appear to currently provide any benefit to ITK and only complicate as already complicated interface to the
ImageIO. If these changes are desired in ITK, then I would strongly encourage better documentation for the new methods in
ImageIO, to enable new developers with add this feature to ImageIO classes.

Brad
</pre>

* From Bill - Thu, Jul 28, 2011 at 5:19 PM '''Re: [slicer-devel] Engineering:TCON 2011 - NAMIC'''
<pre>
I checked the patches. Two classes are patched: ImageIOBase and ImageFileReader. Now I do not think my factory idea is worthwhile.
We should to bring the changes into ITK, and convert ITK's Meta and Nifti ImageIO's to use it.

Bill
</pre>

* In the na-mic tcon it was discussed that nrrd and nifti readers also perform the memcpy since the native libraries perform the Information and Read steps in a single API call. Therefor if the feature existed at the ITK level, then several readers could take advantage of it.

ITKv4 Migration plan

2012-12-01T16:34:49Z

Hjmjohnson: /* Overview */

[[Slicer4#Plan| Back to Slicer]]

=Overview=

This page is designed to identify and track the work that needs to be done during the month of 2012-12-01 to 2012-12-31 in order to transition Slicer to a solid and uniform ITKv4 platform. Originally this document, created following the NAMIC Engineering TCon of July 28th [http://wiki.na-mic.org/Wiki/index.php/Engineering:TCON_2011#2011-07-28], discuss the element that should be considered before transitioning Slicer to ITKv4.

Historical and other old pages with possibly outdated information. If the information on these other pages is relevant, they need to be pushed here.

* http://www.slicer.org/slicerWiki/index.php/ITKv4_Migration_plan </li>
* http://www.slicer.org/slicerWiki/index.php/Developer_Meetings/20121106#ITKv4 </li>
* http://wiki.na-mic.org/Wiki/index.php/Engineering:TCON_2011#2011-07-28 </li>

{| style="color:green; background-color:#ffffcc;" cellpadding="10" class="wikitable"
|+ Timeline for ITKv4
|-
! Date
! Status
! Description
|-
| 2012-12-01
| Done
| Hans provides a first pass reference set of patches that build on Mac and demonstrates that nearly all functionality is maintained identically between ITKv3 and ITKv4
|-
|
|
| I've successfully created a mac dmg package. "CPack: - package: /Users/johnsonhj/src/Slicer-git-itkv4/Slicer-build/Slicer-4.2.0-macosx-amd64.dmg generated." 
The package is not yet completely successful though :(.  It seems to run just fine on the machine I used to build the package, but when running on my wifes laptop, it can not find a Qt library in /usr/local/lib/

This is probably something best left for discussion next Wednesday.

I am building on 10.8 with a private build of clang 3.1 tagged as stable from svn. 
I also installed homebrew, and from that installed QT 4.8.3. ( I manually set the required Qt version to 4.8.3)

*FROM THE SAME SOURCE TREE* I also am building Slicer built with ITKv3, and that also seems to be building a reasonable package.

<pre style="font-size: 13px;">
git clone git@github.com:BRAINSia/Slicer43.git
cd Slicer43
git checkout origin/AddDWIConvert –b AddDWIConvert
cd ../ && mkdir sl-itkv3 && sl-itkv3 && CC=/opt/clang31/bin/clang CXX=/opt/clang31/bin/clang++ ccmake –DITK_VERSION_MAJOR:STRING=3 ../Slicer43
cd ../ && mkdir sl-itkv4 && sl-itkv4 && CC=/opt/clang31/bin/clang CXX=/opt/clang31/bin/clang++ ccmake –DITK_VERSION_MAJOR:STRING=4 ../Slicer43
</pre>
|-
| 2012-12-05
|
| Matt McCormick coordinates a Google Hang out
|-
|
|
| In preparation for the upcoming Slicer 4.3 and the NA-MIC Winter Project Week, we are planning a hackathon to help with migration to ITKv4 as the default version of ITK in Slicer.  For some time, community members such as Hans Johnson, Bill Lorensen, and Jean-Christophe Fillion-Robin have made sure ITKv4 works well with Slicer, and we hope to gather and focus on remaining issues that should be addressed.

The hackathon will take place on:  Wednesday, December 5th from 10AM Eastern Time until we run out of energy :-).
<div style="font-size: 13px;">The hackathon will take place on a Google+ Hangout.  I will follow up with the link to the hangout on this email thread when we starts.</div>

Issues to address at Google Hangout:

Issues in the Slicer bug tracker with the ITKv4 tag: <br\>
* http://www.na-mic.org/Bug/search.php?project_id=3&sticky_issues=on&sortby=last_updated&dir=DESC&hide_status_id=80&tag_string=ITKv4
* Test Slicer/ITKv4 on all platforms, especially 64bit VS2008.
* Look into reducing the number of ITK Modules enabled when building
* Slicer modules to reduce load time on Windows

If there are other issues to address, please report them in the Slicer bug tracker and reply to this thread.</div>

Work will occur on the following repository on Github.   https://github.com/BRAINSia/Slicer43</div>
|-

|}

== Current consensus ==

* Slicer RSNA will be built against ITKv3

* External module requiring ITKv4 will be linker statically against ITKv4
** Associated command line module will be built as executable only. Indeed having both ITKv3 and ITKv4 in the same process will most likely result in some weird symbol clash.

=== Questions ===

* Should each extension depending on ITKv4 download and build its own copy of ITKv4 or should Slicer build and expose both ITKv3 and ITKv4 ?

== Custom MetaIO in SlicerITK ==

* To minimize memory usage and increase efficiency of Command line module execution, itkImageFileReader.txx in SlicerITK has been patched. See https://github.com/Slicer/ITK/commit/8c73dc57e4ae67328ff8e44934b72fd4cc5d4dd3 and https://github.com/Slicer/ITK/commit/12349021b152ac6546c2caf09bbbee4266baddad

* Bill mentioned it should be possible to avoid patching SlicerITK by creating a custom Factory / plugins.

* From Bradley Lowekamp - ITK mailing list - Sun, Jul 17, 2011 at 11:33 AM subject '''Re: [Insight-developers] ITK 3 tag to use with slicer? Fwd: Slicer release schedule'''

<pre>
Stephen,

If I understand this change correctly, this patch allows the usage of a buffer allocated by the ImageIO to be passed
all the way to the Image class if all the types match up. The is accomplished by adding the following
methods: ImageIO::CanUseOwnBuffer, ImageIO::ReadUsingOwnBuffer() and ImageIO::GetOwnBuffer.

I assume that this change is for the MemoryImageFileReader that is used with Slicer. ( can see how this could be
quite advantageous ( and also the potential for scary alias when combined with InPlace filters ). But as not one
single ITK ImageIO has support for these methods. I'd like to question if they should be brought into the ITK main repo,
as they don't appear to currently provide any benefit to ITK and only complicate as already complicated interface to the
ImageIO. If these changes are desired in ITK, then I would strongly encourage better documentation for the new methods in
ImageIO, to enable new developers with add this feature to ImageIO classes.

Brad
</pre>

* From Bill - Thu, Jul 28, 2011 at 5:19 PM '''Re: [slicer-devel] Engineering:TCON 2011 - NAMIC'''
<pre>
I checked the patches. Two classes are patched: ImageIOBase and ImageFileReader. Now I do not think my factory idea is worthwhile.
We should to bring the changes into ITK, and convert ITK's Meta and Nifti ImageIO's to use it.

Bill
</pre>

* In the na-mic tcon it was discussed that nrrd and nifti readers also perform the memcpy since the native libraries perform the Information and Read steps in a single API call. Therefor if the feature existed at the ITK level, then several readers could take advantage of it.

Documentation/4.0/HowTo

2011-11-11T16:25:52Z

Hjmjohnson: /* Overview */

{{documentation/{{documentation/version}}/module-header}}


{{Infobox
|name = 3D Slicer {{documentation/version}}
|above = 3D Slicer
|abovestyle =

|image = [[File:Logo-3DSlicer.png|200px|alt=3D Slicer {{documentation/version}}]]
|imagestyle =
|headerstyle = background:#E7DCC3;
|labelstyle =
|datastyle =

|header1 = Description
|label1 =
|data1 =
|header2 =
|label2 =
|data2 = Research platform for the analysis and visualization of medical images, including image guided therapy.
|header3 =
|label3 =
|data3 = Free and extensible open source package.
|header4 =
|label4 = Multi-platform
|data4 = Linux, MacOSX, Windows
|header5 =
|label5 = Version
|data5 = {{documentation/version}}
|header6 =
|label6 = License
|data6 = [http://www.slicer.org/pages/LicenseText Contribution and Software License Agreement]
}}

= Overview =
This document aims at describing the steps required to write Slicer user documentation.

The user documentation could be grouped under two main sections:
* Slicer Application
* Modules



The basic approach is to have most of the documentation in the source code and to populate the wiki pages using scripts.
*For the end user documentation use this [[Documentation/{{documentation/version}}/Modules/YOURMODULENAME|Template]]

*All module documentation page should be named according to the following pattern: '''Documentation/4.0/Modules/MODULENAME'''
** There is a python helper script for SEM compliant tools that can save a significant amount of transcription time: Slicer/Scripts/SEMToMediaWiki.py
*High resolution logos are in the [[Logo_Gallery|Logo Gallery]]
*Collaborators' name, logo, URL have been centralized into a convenient set of [http://wiki.slicer.org/slicerWiki/index.php/Template:Collaborator templates]
*The following [http://wiki.slicer.org/slicerWiki/index.php?title=Category:Documentation/4.0/Modules link] will list all modules belonging to the Documentation/4.0/Modules category.
*For CLI modules, the '''SVNREVISION''' revision number is reported on this [http://viewvc.slicer.org/viewvc.cgi/Slicer4/trunk/Applications/CLI page]. The module description and the information for developers would be automatically extracted from the corresponding XML description. '''Note:''' for the moment it's required to update that number at multiple location within the wiki source of a given module documentation page. Soon this will be centralized.

Documentation/4.0/Acknowledgment Team

2011-11-01T21:30:42Z

Hjmjohnson: /* Funding Sources */

This is a place holder
=Introduction=
Sincere thanks go to members of the Slicer Community for their contributions to the design, functionality and usability of 3D Slicer.

Major funding for the 3D Slicer software package was provided by the NIH through a number of grants. Additional contributions came from a number of sources, nationally and internationally.

=List of Contributors=
==People And Their Roles==
*[http://www.spl.harvard.edu/pages/People/kikinis Ron Kikinis]: Principal Investigator
*Steve Pieper
*[http://www.kitware.com/company/team/finet.html Julien Finet]
*[http://www.kitware.com/company/team/fillion.html Jean-Christophe Fillion-Robin]
*[http://www.kitware.com/company/team/aylward.html Stephen Aylward]
*Nicole Aucoin
*Alex Yarmarkovich
*Hans Johnson
*Daniel Haehn
*Kilian Pohl
*[http://www.kitware.com/company/team/schroeder.html Will Schroeder]
*Jim Miller
*Junichi Tokuda
*Noby Hata
*Andrey Fedorov
*[http://www.spl.harvard.edu/pages/People/spujol Sonia Pujol]
*[http://www.kitware.com/company/team/pace.html Danielle Pace]

==Groups==
*[http://www.spl.harvard.edu/ SPL]: Ron Kikinis, Nicole Aucoin, Wendy Plesniak, Demian Wassermann, Isaiah Norton, Sonia Pujol
*Isomics: Steve Pieper, Alex Yarmarkovich
*[http://www.kitware.com Kitware]: [mailto:julien.finet@kitware.com Julien Finet], [mailto:jchris.fillionr@kitware.com Jean-Christophe Fillion-Robin], Danielle Pace, Will Schroeder, [mailto:stephen.aylward@kitware.com Stephen Aylward]
*U Iowa
*U Penn
*GE: Jim Miller

==Funding Sources==
*ARRA supplement to NAC: [http://wiki.na-mic.org/Wiki/index.php/Projects:ARRA:SlicerUI Qt port], [http://wiki.na-mic.org/Wiki/index.php/Projects:ARRA:SlicerEM EM Segmenter], [http://wiki.na-mic.org/Wiki/index.php/Projects:ARRA:miAnnotation Annotations]
*[http://nac.spl.harvard.edu/ NAC]
*[http://na-mic.org NA-MIC]
*[http://ncigt.org NCIGT]
* 1U01CA151261-01 (PI Fennessy)
* [http://public.kitware.com/Wiki/NeuralNav 1R01CA138419-01 (PI: Wells and Aylward), NCI academia-industry partnership]
* “Cognitive and Functional Brain Changes in Preclinical Huntington’s Disease (HD)” (HD-fMRI); NS054893)
* “Neurobiological Predictors of Huntington's Disease” (PREDICT-HD; NS40068)

Modules:BRAINSFit

2011-01-14T18:07:14Z

Hjmjohnson: /* Module Name */

[[Documentation-3.6|Return to Slicer 3.6 Documentation]]

[[Announcements:Slicer3.6#Highlights|Gallery of New Features]]

__NOTOC__
===Module Name===
BRAINSFit

{|
| [[Image:Before.png|thumb|280px|Before registration]]
|-
| [[Image:After.png|thumb|280px|AfterRegistration]]
|}

=== Experimental results from the registration library ===

http://www.na-mic.org/Wiki/index.php/Projects:RegistrationLibrary:RegLib_C02

http://www.na-mic.org/Wiki/index.php/Projects:RegistrationLibrary:RegLib_C14

-- And several more from:

http://www.na-mic.org/Wiki/index.php/Projects:RegistrationDocumentation:UseCaseInventory#BRAIN

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

{| 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 || http://wiki.slicer.org/slicerWiki/index.php/Modules:BRAINSFit
|-

|}

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

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

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

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

You can see the differences in results if you re-run BRAINSFit using Rigid, ScaleVersor3D, or ScaleSkewVersor3D as the ----transformType parameter. In this case, the authors judged Affine the best method for registering these particular two images; in the BRAINS2 automated processing pipeline, Rigid usually works well for registering research scans.
===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.
<pre>
--fixedVolume testT1.nii.gz \
--movingVolume testT1Longitudinal.nii.gz \
--outputVolume testT1LongRegFixed.nii.gz \
--outputTransform longToBase.xform \
</pre>
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".
<pre>
--transformType Rigid \
</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>

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

* '''''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.
<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.

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>

The full command is:
<pre>
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>

{|
| [[Image:T1T2PreRegCheckerboard.png|thumb|180px|Multimodal Checkerboard Before registration]]
| [[Image:T1T2RegCheckerboard.png|thumb|180px|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.
<pre>
--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>

The full command is:
<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>

{|
| [[Image:MouseCheckerboardPreRegistration.png|thumb|180px|Mouse Checkerboard Before registration]]
| [[Image:MouseCheckerboardPostRegistration.png|thumb|180px|Mouse Checkerboard After registration]]
|}



===Quick Tour of Features and Use===

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]

{|
|
* '''''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''

||[[Image:BRAINSFitUI_part1.png|thumb|280px|User Interface]] [[Image:BRAINSFitUI_part2.png|thumb|280px|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:
<pre>

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");
}

</pre>

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

===Tests===

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

===Known bugs===

Links to known bugs and feature requests are listed at:
* http://www.nitrc.org/projects/multimodereg/

===Usability issues===

Follow this [http://na-mic.org/Mantis/main_page.php 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:
*[http://www.nitrc.org/projects/multimodereg/|Hosted by NITRC ]

== More Information ==

===Acknowledgment===

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

===References===
* [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.

Slicer3:3.6 Final Issues

2010-07-30T02:51:07Z

Hjmjohnson:

==Issues to include in 3.6.1 patch release==

* Fixes for EMSegment command line working with BRAINS (Kilian)
* VTK GPU Ray Cast flashing (Julien)
* Import scene does not update 3D viewer (Nicole, Wendy) http://na-mic.org/Mantis/view.php?id=840
* brackets in filenames (Steve - fixed in trunk, migrate to branch if tests well) http://www.na-mic.org/Bug/view.php?id=851
* changes to avoid error messages when using single-slice volumes (Steve) - in trunk, need to move to branch
* Editor rounding issue [http://www.na-mic.org/Bug/view.php?id=932] (Steve) - in trunk, need to move to branch
* Snapshot issue [http://na-mic.org/Mantis/view.php?id=933] (Alex)
* CompareView issues [http://na-mic.org/Mantis/view.php?id=927 927], [http://na-mic.org/Mantis/view.php?id=929 929], [http://na-mic.org/Mantis/view.php?id=936 936]
* CompareView + Crosshairs issue [http://na-mic.org/Mantis/view.php?id=928 928]
* KWWidgets issue with "%" in file names produced by DICOM browser -- fixed in trunk, need to make sure propagated to 3.6 [http://na-mic.org/Mantis/view.php?id=886 bug 886] (Steve)
* Diffusion Tensor Glyphs not showing (Demian)
* Diffusion Tensor Tractography having a strange no-tracking through high FA areas case (Demian)
* Cannot change the window/level on color-by-orientation dti volumes (Alexy - may not be included in 3.6.1).

Done (in branches/Slicer-3-6 after June 10):
* make sure all BRAINS and Registration fixes are in the 3.6 branch (Hans and Jim with help from Dominik)
* check for duplicate filepaths when saving data (Alex) http://www.na-mic.org/Bug/view.php?id=925
* tractography seeding issue (Alexy) http://www.na-mic.org/Bug/view.php?id=885: Changed Tracttography/LabelMapSeeding module: 1. added UseIndexSpace option for seeding placement. 2. Also found that IJK indexes used for traversing the label volume were floats. Changed them to doubles that may crate slightly different tracts, but it is less prone to error accumulation (Alex).
* Added multi-label selection to Tractography/ROISelect module (PNL request for Slicer2 compatibility, Alex)
* Added more scalar options to Diffusion Tensor Scalar Measurement module (PNL request for Slicer2 compatibility, Alex)
* [http://www.na-mic.org/Bug/view.php?id=871 fix] for Python programming tutorial (Steve, Luca)
* Fixes for color table preview icons showing up in node selectors (Wendy and Nicole)
** [http://viewvc.slicer.org/viewcvs.cgi?rev=13771&view=rev svn 1377]
* DicomToNrrd issues reported by AlexZ and Sylvain (Xiaodong)
* Crosshair traking modes (Jim); also see [http://na-mic.org/Mantis/view.php?id=861 bug #861]
* Wizard page transition error in ProstateNav. The issue was fixed by Haiying.
* OpenIGTLink reslice performance (Junichi) (fixed by Steve)
* Updated meshing module (Curt) - checked in trunk for [http://www.na-mic.org/Wiki/index.php/Slicer3:IAFEMesh_TutorialContestSummer2010|tutorial contest]; needs merge to branch if all is well.
* "Change island" effect of Editor is not functioning when the Scope is set to "all"

==3.6 Release issues==
Final punch list for [[Slicer3:3.6Release|slicer 3.6 release]]:

'''Finalized June 10 for 3.6 binaries and [[Announcements:Slicer3.6]]'''

*VTK GPU ray-cast clipping issue
**bug fix:[[http://na-mic.org/Mantis/view.php?id=800 Non axis aligned volumes]]
**bug fix:[[http://na-mic.org/Mantis/view.php?id=798#c1780 ROI on Non axis aligned volumes]]
**90% of the flickering when the camera is inside the volume is removed
*compare view + crosshair issue when loading a scene, the crosshair does not appear in all viewers until the slice location is changed, (Jim)

*Picking NCI GPU Raycasting on machine that doesn't support it causes lockup. Not able to reproduce the problem (Yanling).

Done:
* Remove unused color and glyph options from fiber bundle display (Alex)
* fiducial behavior
* fiducial behavior/3D viewer behavior: (Steve, Nicole, Wendy met Jun 7)
** saw one example of persistent place mode being stolen by pick mode. I think this has to do with inappropriate initialization of modes. It is possible for pick mode to take over until transient-pick mode is explicitly chosen. (FIXED)
** tractography updates not happening during drag - fixes checked into SlicerVTK and Slicer3 branch
** tractography updates slow when drag stops (Steve confirmed this was due to update only happening when mouse was moved after button released - made it seem extra slow)
**widget issues (Nicole putting fixes in [http://github.com/pieper/CTK SlicerVTK])
*making sure mouse-modes work same in 3D/2D (Wendy and Nicole) Let's call it DONE!
** done for 2d, Andras has tested it and says it's fine
*editor volume merge feature clarification (Steve meeting Sonia June 2, fixes committed June 3)
*getting BRAINS tests to pass (Hans is working on it)
*tracking down what is making that crash on Mac OsX when several PET volumes are loaded into Slicer (Wendy).
* are there extra pick operations going on? There seems to be a delay after clicking mouse before camera begins to rotate when large models are present in scene. ''could not replicate - tried 2.5 million triangle model on slicer and paraview and performance is the same''
* should picking of fiducials in 3D be disabled unless user explicitly chooses 'pick mode'? ''Not a good idea to change behavior at this point''
** should parallel behavior be implemented in 2D for consistency? Stevie votes no, Wendy votes yes. ''Not a good idea to change behavior at this point''
* roundtrip to xnat desktop --OK: confirmed that Ron was using dirty files in cache; checking 'always re-download' in the Cache and DataI/O Manager GUI caused fresh download and successful load into slicer. Sometimes, even when you delete cached files thru the GUI, some applicaiton is holding on to files still there and they don't get cleared out. I'm adding a little code to check for remaining files after a ClearCache() is called; if so, we'll warn user that not all files were removed, and to select 'always re-download' to ensure proper data loading.(Wendy)
* view control gui: (Wendy) this guy isn't always updating anymore. He may be a casualty of multiple view nodes in the scene. He was a casualty but is fixed now!
*The diffusion tensor estimation module is using defaults that are not good and partially incorrect. Can the defaults be as follows:
**for Output DTI volume: DTI Volume
**for Output Baseline Volume: Baseline DTI Volume
**for Otsu Threshold Mask: Otsu Threshold Label Volume
*new default color table (Nicole and Mike)
** Mike working on creating a LUT from <strike>[[CCA:Atlases:Florins_2010_Hierarchy|this hierarchy]]</strike> [[CCA:Atlases:Florins_2010_Hierarchy_Short|this subset]], by Jun 7
** Steve and Nicole to meet June 9 to integrate default editor color table
** Jun 10: checked in new color files, one from [[Slicer3:2010_GenericAnatomyColors|GenericAnatomyColors]], and one based on that but with names set to integer values and the color for 255 changed to blue. Wendy making new drop down menu icons.
*finishing up the DICOM file copy on remote upload, also close (Wendy) (DONE)

Issues that cannot be fixed (or aren't crucial to fix) should be listed in [[Release-notes-3.6| the slicer 3.6 release notes]].

GTRACT V4

2010-06-22T19:29:21Z

Hjmjohnson: /* GTRACT Programs */

== GTRACT Overview ==

This is a manual for the GTRACT program. This program suite now incorporates a full DTI data processing pipeline. In this version of the tools, all of the functional units exist as command line programs that integrate with Slicer3 using the Execution model framework. The standard format for the DTI data in this version is the NRRD format. Anatomical images and label maps can be in any format supported by ITK. The program support several version of fiber tracking including:

# Free tracking - Basic streamlines with only a starting region
# Streamlines - Streamlines tracking between two regions of interest
# Graph Search - Modified streamlines that tries multiple solutions in low anisotropy regions
# Guided Tracking - Uses an initial guess to the fiber track to guide the tracking
# Fast Marching - Method based on the method proposed by Geoffrey Parker

Funding for this version of the GTRACT program was provided by NIH/NINDS R01NS050568-01A2S1. The software is hosted by the Neuroimaging Informatics Tools and Resources Clearinghouse [http://www.nitrc.org/projects/vmagnotta/ (NITRC)].

== Installing GTRACT ==
The easiest way to install GTRACT is to obtain pre-compiled binaries from the NITRC website. You should be able to download and install these on most platforms. Currently this is just an archive file for the various platforms that can be unpacked wherever the user has write access.

===Installing Into Slicer3===
The command line modules do support the Slicer3 execution model and could be placed within the Slicer3 build and will be become active when the user starts Slicer3. The modules are installed under the '''BRAINS->GTRACT''' menu in the Slicer3 Module tree. More details will be forthcoming on this. Copyright information for GTRACT can be obtained [https://mri.radiology.uiowa.edu/copyright/GTRACT-Copyright.txt here].

===Building GTRACT===
GTRACT depends on only ITK and VTK. It also requires CMake for building. Most recent versions of VTK and ITK should work. Presently GTRACT requires using CMake version 2.8 or higher for the builds.

== Conversion from DICOM to NRRD Format ==
The program for the conversion of DICOM images into Gordan Kindlmann's [http://teem.sourceforge.net/nrrd/ NRRD format] is supported by the Slicer3 DicomToNrrd. This is included within the GTRACT package for convenience. This program should handle most images from GE and Siemens scanners including Mosaic format images. For Siemens scanners, software version above VB13 should be supported. We would like to thank Xiaodong Tao for his great work on this tool. This program should read the diffusion directions from the DICOM header.

% DicomToNrrd <DICOM-Directory> <OutputDirectory> <OutputFilename>

The output file will contain the Diffusion weighted images in a vector format. The tools within the GTRACT analysis pipeline now expect the images in NRRD format.

== GTRACT Programs ==
This documentation is mostly generated using a script from http://svn.slicer.org/Slicer3/trunk/Scripts/SEMToMediaWiki.py

<pre>
python SEMToMediaWiki.py ${progname}.xml > ${progname}.txt
</pre>

* [[compareTractInclusion|compareTractInclusion Documentation]]
* [[extractNrrdVectorIndex|extractNrrdVectorIndex Documentation]]
* [[gtractAnisotropyMap|gtractAnisotropyMap Documentation]]
* [[gtractAverageBvalues|gtractAverageBvalues Documentation]]
* [[gtractClipAnisotropy|gtractClipAnisotropy Documentation]]
* [[gtractCoRegAnatomyBspline|gtractCoRegAnatomyBspline Documentation]]
* [[gtractCoRegAnatomyPrimary|gtractCoRegAnatomyPrimary Documentation]]
* [[gtractCoRegAnatomyRigid|gtractCoRegAnatomyRigid Documentation]]
* [[gtractConcatDwi|gtractConcatDwi Documentation]]
* [[gtractCopyImageOrientation|gtractCopyImageOrientation Documentation]]
* [[gtractCoregBvaluesPrimary|gtractCoregBvaluesPrimary Documentation]]
* [[gtractCostFastMarching|gtractCostFastMarching Documentation]]
* [[gtractCreateGuideFiber|gtractCreateGuideFiber Documentation]]
* [[gtractFastMarchingTracking|gtractFastMarchingTracking Documentation]]
* [[gtractFiberTracking|gtractFiberTracking Documentation]]
* [[gtractFreeTracking|gtractFreeTracking Documentation]]
* [[gtractGraphSearchTracking|gtractGraphSearchTracking Documentation]]
* [[gtractGuidedTracking|gtractGuidedTracking Documentation]]
* [[gtractImageConformity|gtractImageConformity Documentation]]
* [[gtractInvertBSplineTransform|gtractInvertBSplineTransform Documentation]]
* [[gtractInvertDeformationField|gtractInvertDeformationField Documentation]]
* [[gtractInvertRigidTransform|gtractInvertRigidTransform Documentation]]
* [[gtractResampleAnisotropy|gtractResampleAnisotropy Documentation]]
* [[gtractResampleB0|gtractResampleB0 Documentation]]
* [[gtractResampleCodeImage|gtractResampleCodeImage Documentation]]
* [[gtractResampleFibers|gtractResampleFibers Documentation]]
* [[gtractStreamlineTracking|gtractStreamlineTracking Documentation]]
* [[gtractTensor|gtractTensor Documentation]]
* [[gtractTransformToDeformationField|gtractTransformToDeformationField Documentation]]

== DTI Image Co-Registration ==
Once the images are in NRRD format the next step in the analysis pipeline is the elimination of motion and eddy current artifacts between the diffusion weighted images. The program for this step of the analysis is '''gtractCoregBvalues'''. This program will support registration between two diffusion series in the case where you would like to average this data across runs. It also would allow for co-regsitration with a T2 weighted image or field map in the same plane as the DTI data.

A mutual information metric cost function is used for the registration because of the differences in the signal intensity as a result of the diffusion gradients. The fixed image for the registration should be a b0 image. The user has the option to perform a rigid or a full affine registration. The full affine allows the registration procedure to correct for eddy current distortions that may exist in the data. This is specified with the '''eddyCurrentCorrection''' option. In general the standard parameters work fairly well for a rigid registration, and you probably just need to specify the images for registration. When the eddyCurrent Correction is specified, then we have had to adjusrt the '''relaxationFactor''' and '''maximumStepSize''' parameters. We typically use values of around 0.25 for the relaxation factor and 0.1 for the maximum step size when this option is turned on.

% gtractCoregBvalues --fixedImageVolume baseImage.nhdr --movingImageVolume baseImage.nhdr --fixedImageIndex 0

A complete listing of parameters can be found here, [[gtractCoregBvalues]], or can be obtained on the command line using

% gtractCoregBvalues --help

== Tensor Image Calculation ==
This step takes the diffusion tensor image data and generates a tensor representation of the data based on the signal intensity decay, b values applied and the diffusion directions. The apparent diffusion (ADC) for a given orientation is computed on a pixel-by-pixel basis by fitting the image data (i.e. voxel intensities) to the Stejskal-Tanner equation:

Sb = S0 exp-b ADC

If at least six orientations are used, then the diffusion tensor can be computed. The measured ADC values is related to the diffusion tensor elements via the following equation:

ADC = M D

where ADC is a vector of the measured apparent diffusion coefficients, M is the matrix describing the diffusion directions applied, and D is a vector of the diffusion tensor elements. This can be solved using standard matrix operations

D = M-1 ADC

In this step we are solving for the diffusion tensor which contains size elements (Dxx, Dyy, Dzz, Dxy, Dxz, Dyz). These can then be used to define the diffusion tensor

|Dxx Dxy Dxz|
|Dyx Dyy Dyz| = D
|Dzx Dzy Dzz|

This is a symmetric matrix therefore Dxy=Dyx, Dxz=Dzx, and Dyz=Dzy.

The program [[gtractTensor]] is responsible for the estimation of the Tensor. The program uses itk::DiffusionTensor3DReconstructionImageFilter for this step. There are several options for the analysis that can be tuned by the user.

* '''Background threshold''' - This sets a threshold used on the b=0 image to remove background voxels from the processing. Typically a value around 100 works well for Siemens DTI images. We have found that 500 works better for GE datasets. Check your data particularly in the globus pallidus to make sure that brain tissue is not being eliminated with this threshold.

* '''Median filter''' - If the filter is enabled, a median filter will be applied to the data. The x, y, and z values specify the size of the median filter in voxels.

* '''Isotropic Resampling''' - If this option is enabled, the data will be resample to isotropic resolution specified. This is recommended if fiber tracking is to be performed.

'''Example:'''
% gtractTensor --inputVolume Series0003_coreg.nhdr --outputVolume Series0003_Tensor.nhdr \
--useMedianFilter --medianFilterSize 1,1,1 --backgroundSuppressingThreshold

--[[User:Admin|Admin]] 10:44, 2 July 2009 (CDT)

'''NOTE:''' We have recently made changes to this program top make it more flexible. There is now a ''--ignoreIndex'' option that allows the user to remove specific gradient directions if artifacts exist in a particular gradient direction. A DTI volume can now have multiple B0 and gradient direction images. These are now handled properly without requiring averaging of the diffusion weighted images. Averaging of the B0 image is done internally in this program.

== Compute Anisotropy Images ==
Anistropy mapping can be used to generate the following diffusion tensor indices:
* Fractional Anistroy (FA)
* Relative Anistroy (RA)
* Volume Ratio (VR)
* Lattice Index (LI)
* Coherence Index (CI)
* Mean Diffusivity (ADC)
* Axial Diffusivity (AD)
* Radial Diffusivity (RD)

Anisotropy images are used for fiber tracking, but the anisotropy scalars are not defined along the path. Instead the Tensor representation is included as point data allowing all of these metric to be computed using only the fiber tract point data. The images can be saved in any ITK supported format, but it is suggested that you use an image format that supports the definition of the image origin. This includes NRRD, NifTI, and Meta formats. These images can also be used for scalar analysis including regional anisotropy measures or VBM style analysis.

The command line parameters are defined here [[gtractAnisotropyMap Version 3]].

'''Example:'''
% gtractAnisotropyMap --inputVolume Series0003_Tensor.nhdr \
--anisotropyType FA --outputVolume Series0003_FA.nhdr

== Alignment with Anatomical Image ==
The two registration methods supported for alignment with Anatomical images, Rigid and B-Spline. The rigid registration performs a rigid body registration with the anatomical images and should be done as well to initialize the B-Spline transform. The B-SPline transform is the deformable transform, where the user can control the amount of deformation based on the number of control points as well as the maximum distance that these points can move. This allows for some susceptibility related distortions to be removed from the diffusion weighted images. It is recommended that for image co-registration with the B-Spline Transform that the skull stripped (i.e. image containing only brain with skull removed) image be used.

===Copy Reference Image Orientation===
Currently, the registration process requires that the diffusion weighted images and the anatomical images have the same image orientation (i.e. Axial, Coronal, Sagittal). It is suggested that you copy the image orientation from the diffusion weighted images and apply this to the anatomical image. This image can be subsequently removed after the registration step is complete. We anticipate that this limitation will be removed in future versions of the registration programs. The program '''gtractCopyImageOrientation''' is used for this step. The complete command line arguements for [[gtractCopyImageOrientation Version 3]] can be generated using the '--help' flag.

% gtractCopyImageOrientation --inputVolume T1_ACPC_clip.nii.gz \
--inputReferenceVolume DWI_coreg.nhdr --outputVolume T1_ACPC_Axial.nhdr

===Anatomical Rigid===
The rigid registration uses a mutual information metric to align the b0 image with the anatomical image. A reasonable set of parameters is specified as the default set of parameters. These were initially tested on a data from both a Siemens 1.5T and 3.0T scanners. Here are the complete set of parameters for [[gtractCoRegAnatomyRigid Version 3]]

'''Example'''
% gtractCoRegAnatomyRigid --inputVolume 0226770_DWI_coreg.nhdr \
--vectorIndex 0 --inputAnatomicalVolume 30670508_T1_ACPC_Axial.nhdr \
--outputRigidTransform ACPC_rigid.xfm --numberOfIterations 1000

It is recommended that the rigid registration be run before the B-Spline nonlinear registration is run.

{|
| style="width:50%" | [[Image:T1-Scan.gif|T1 Weighted Volume|300px|thumb|T1 Volume]]
| style="width:50%" | [[Image:DTI-Rigid.gif|300px|thumb|T1 Weighted with B0 image overlay]]
|}

===Anatomical B-Spline===
The B-SPline registration places a low dimensional grid in the image which is deformed. The B-Spline registratiuon works best if the anatomical image has been skull stripped and a rigid registration is used as the staring point for the registration. The user can specify the number of control points to be used in the registration and the maximum distance that each control point should move. In general the amount of motion in the slice selection and read-out directions direction should be kept low. The distortion is in the phase encoding direction in the images. A bulk transform can be applied to the B-Spline transform to initialize the transform. This should be the rigid transform generated from the previous step for the optimal results. The program '''gtractCoRegAnatomyBspline''' performs this registration step and a detailed list of parameters can nbe found here, [[gtractCoRegAnatomyBspline Version 3]]

'''Example:'''

% gtractCoRegAnatomyBspline

{|
| style="width:50%" | [[Image:DTI-Rigid.gif|300px|thumb|T1 Weighted Volume with B0 image (Rigid Registration) overlay]]
| style="width:50%" | [[Image:DTI-Bspline.gif|300px|thumb|T1 Weighted Volume with B0 image (B-Spline Registration) overlay.]]
|}

'''Notice:''' Improved registration especially at the anterior portion of the corpus callosum

===Invert Rigid Transform===
The program '''gtractInvertRigidTransform''' is used to invert rigid transforms. Typically this is used to map images in anatomical space to the diffusion weighted image space. This is useful for transforming labels defined on the anatomical image into the space of the diffusion weighted images to be used for fiber tracking. Complete parameters for [[gtractInvertRigidTransform Version 3]] are available using the '--help' option.

'''Example:'''
% gtractInvertRigidTransform --inputTransform ACPC_rigid.xfm \
--outputTransform ACPC_Inverse_Rigid.xfm

===Invert B-Spline===
Since the B-Spline transform cannot be directly inverted, we have implemented a thin plate spline approximation to its inverse. This can be created yusing the gtractInvertBspline. The X, Y and Z grid specifiy the grid utilized to sample the B-Spline transform. The parameters for [[gtractInvertBspline Version 3]] can be obtained using the '-help' option. The inverse needs to be computed to map fiber tracts from the DTI space to the anatomical image and to map regions of interest from the anatomical image onto the diffusion weighted images using this non-linear transform that accounts in part for susecptility artifcats.

'''Example'''
% gtractInvertBSplineTransform

===Resampling Images===
Three programs have been written to resample the various types of images that may be encountered in diffusion tensor analysis. All of the programs accept only ITK transforms and in particular '''Versor Rigid'' or '''B-Spline''' transforms that are described above.

* [[gtractResampleCodeImage Version 3]] - Resamples a mask or label - Image pixel type is signed short and neareast neigbor interpolation is used
* [[gtractResampleB0 Version 3]] - Resamples the B0 image - Image pixel type is signed short and linear interpolation is used
* [[gtractResampleAnisotropy Version 3]] - Resamples an anisotropy map - Image pixel type is float and linear interpolation is used

When running these programs the user must also specify a template image that will be used to define the origin, orientation, spacing and size of the resampled image.

'''Example:'''
% gtractResampleCodeImage --inputTransform ACPC_Inverse_Rigid.xfm -\
-transformType Rigid --inputCodeVolume Thal_axial.nhdr \
--inputReferenceVolume DWI_coreg.nhdr --outputVolume Thal_DWI.nhdr

You may want to save the aligned B0 image after each of the co-registration steps with the anatomical image to check the registration quality with another tool such as [http://www.nitrc.org/projects/brains/ BRAINS] or [http://www.slicer.org Slicer].

== Fiber Tracking ==

Once an isotropy image, a tensor image, and a spatial object have either been created and loaded fiber tracking can take place. Selecting the '''Tracking''' tab will allow the user to specify the type of tracking to be performed. Currently the GTRACT tool supports a number of fiber tracking methods. These include:

# [https://mri.radiology.uiowa.edu/mediawiki/index.php/GTRACT_Software_-_Version_3#Free_Tracking Free Tracking]
# [https://mri.radiology.uiowa.edu/mediawiki/index.php/GTRACT_Software_-_Version_3#Streamlines_Tracking Streamlines Tracking]
# [https://mri.radiology.uiowa.edu/mediawiki/index.php/GTRACT_Software_-_Version_3#Graph_Search_Tracking Graph Search Tracking]
# [https://mri.radiology.uiowa.edu/mediawiki/index.php/GTRACT_Software_-_Version_3#Guided_Tracking Guided Tracking]
# [https://mri.radiology.uiowa.edu/mediawiki/index.php/GTRACT_Software_-_Version_3#Fast_Marching_Tracking Fast Marching Tracking]

The output of the fiber tracking is vtkPolyData (i.e. Polylines) that can be loaded into Slicer3 for visualization. The poly data can be saved in either old VTK format files (.vtk) or in the new VTK XML format (.xml). Currently, Slicer3 only accepts the old .vtk file format. The polylines contain point data that defines ther Tensor at each point along the fiber tract. This can then be used to rendered as glyphs in Slicer3 and can be used to define severeal scalar measures without referencing back to the anisotropy images.

===Free Tracking===
The Free tracking is a basic streamlines algorithm. This is a direct implementation of the method original proposed by Basser et al. The tracking follows the primarty eigenvector. The tracking begins with seed points in the starting region. Only those voxels above the specified anisotropy threshold in the starting region are used as seed points. Tracking terminates either as a result of maximum fiber length, low ansiotropy, or large curvature. This is a great way to explore your data, but the tools to appropriately edit these down to a fiber tract of interest do not yet exist. The user should explore using the other approaches described below once they have performed an initial review of their data.
A complete set of parameters for [[gtractFreeTracking Version 3]] can be obtained using the '--help' option.

'''Example:'''
% gtractFreeTracking --inputTensorVolume Tensor.nhdr \
--inputAnisotropyVolume FA.nhdr \
--inputStartingSeedsLabelMapVolume Thal_DWI.nhdr \
--startingSeedsLabel 1 --seedThreshold 0.25 \
--curvatureThreshold 60 --outputTract freeTracking.vtk

===Streamline Tracking===
The streamlines algorithm is a direct implementation of the method original proposed by Basser et al. The tracking follows the primarty eigenvector. The tracking begins with seed points in the starting region. Only those voxels above the specified anisotropy threshold in the starting region are used as seed points. Tracking terminates either by reaching the ending region or reaching some stopping criteria. Stopping criteria are specified using the following parameters:

* '''Tracking Threshold''': Anistropy values of the next point along the path
* '''Curvature''': Angle of the next tracking direction relative to the current path direction
* '''Max Length''': Length of the track in voxels

Only paths terminating in the ending region are kept in this method. The TEND algorithm proposed by Lazar et al. ([http://www3.interscience.wiley.com/cgi-bin/abstract/103525670/ABSTRACT?CRETRY=1&SRETRY=0 Human Brain Mapping 18:306-321, 2003]) has been instrumented. This can be enabled using the '''--useTend''' option while performing Streamlines tracking. This utilizes the entire diffusion tensor to deflect the incoming vector instead of simply following the primary eigenvector. The TEND parameters are set using the '''--tendF''' and '''--tendG''' options.

vout = fe1 + (1-f) * ((1-g)vin+gD · vin)

Where:
*vout is the outgoing vector direction
*vin is the incoming vector direction defined in the previous step
*ein is the primary eigenvector direction
*D is the diffusion Tensor

The complete set of command line arguements for [[gtractStreamlineTracking Version 3]] are available with the '--help' option at the command line.

'''Example:'''
% gtractStreamlineTracking

===Graph Search Tracking===
The Graph Serach tracking is the first step in the full GTRACT algorithm developed by Cheng et al. ([http://www.sciencedirect.com/science?_ob=ArticleURL&_udi=B6WNP-4JVTCDN-1&_user=440026&_rdoc=1&_fmt=&_orig=search&_sort=d&view=c&_acct=C000020939&_version=1&_urlVersion=0&_userid=440026&md5=a58d1d1ffaf9741f2d95aa294e017b17 NeuroImage 31(3): 1075-1085, 2006]). for finding the tracks in a tensor image. This method was developed to
generate fibers in a Tensor representation where crossing fibers occur. The graph search algorithm follows the primary eigenvector in non-ambigous regions and utilizes branching and a graph search algorithm in ambigous regions. Ambigous tracking regions are defined based on two criteria:

*'''Branching AI Threshold''': Anistropy values below this value and above the tracking threshold
* '''Curvature Major Eigen''': Angles of the primary eigenvector direction and the current tracking direction

In regions that meet this criteria, two or three tracking paths are considered. The first is the standard primary eigenvector direction. The second is the seconadary eigenvector direction. This is based on the assumption that these regions may be prolate regions. If the '''Random Walk''' option is selected then a third direction is also considered. This direction is defined by a cone pointing from the current position to the centroid of the ending region. The interior angle of the cone is specified by the user with the '''Branch/Guide Angle''' parameter. A vector contained inside of the cone is selected at random and used as the third direction. This method can also utilize the TEND option where the primary tracking direction is that specified by the TEND method instead of the primary eigenvector.

The parameter '--maximumBranchPoints' allows the tracking to have this number of branches being considered at a time. If this number of branch points is exceeded at any time, then the algorithm will revert back to a streamline alogrithm until the number of branches is reduced. This allows the user to constrain the computational complexity of the algorithm. A complete set of command line arguements for [[gtractGraphSearchTracking Version 3]] can be obtained using the '--help' option from the command line.

'''Example:'''
% gtractGraphSearchTracking

===Guided Tracking===
The second phase of the GTRACT algorithm is Guided Tracking. This method incorporates anatomical information about the track orientation using an initial guess of the fiber track. In the originally proposed GTRACT method, this would be created from the fibers resulting from the Graph Search tracking. However, in practice this can be created using any method and could be defined manually. To create the guide fiber the program '''gtractCreateGuideFiber''' can be used. This program will load a fiber tract that has been generated and create a centerline representation of the fiber tract (i.e. a single fiber). The complete set of parameters for [[gtractCreateGuideFiber Version 3]] can be obtained using the '--help' option.

'''Example:'''
% gtractCreateGuideFiber --inputFiber graph.vtk --outputFiber guide.vtk --numberOfPoints 100

In this method, the fiber tracking follows the primary eigenvector direction unless it deviates from the guide fiber track by a angle greater than that specified by the '--guidedCurvatureThreshold' parameter. The program [[gtractGuidedTracking Version 3]] implements this algorithm. The user must specify the guide fiber when running this program.

'''Example:'''
% gtractGuidedTracking

===Fast Marching Tracking===

This algorithm implements a fast marching fiber tracking algorithm to identify fiber tracts from a tensor image. This
algorithm is based on the work by G. Parker et al. ([http://ieeexplore.ieee.org/xpl/freeabs_all.jsp?isnumber=21763&arnumber=1009386&count=12&index=8 IEEE Transactions On Medical Imaging, 21(5): 505-512, 2002]) An additional
feature of this version is the inclusion of anisotropy in the cost function calculation. The user has the ability to weight the contribution of the anisotropy weight.

This algorithm is broken into two parts. The first phase of the algorithm generates a cost image. This starts with a seed region specified by the user. The cost of the path tracking from the seed region to every voxel in the brain is computed. The cost is based on the direction of the front, the primary eigenvector direction, and the anisotropy value. The user can adjust the weight of the anisotropy value using the '--anisotropyWeight' flag. The program [[gtractCostFastMarching version 3]] is responsible for the generation of the cost image. This may take several minutes to generate and increases with the size of the seed region. Currently, both a cost and spped image are generated. The speed image is not used in the fiber tracking phase and will become an optional parameter in future releases. Currently, it is a required parameter.

'''Example:'''
% gtractCostFastMarching --inputTensorVolume Tensor.nhdr \
--inputAnisotropyVolume FA.nhdr \
--inputStartingSeedsLabelMapVolume seeds.nhdr \
--startingSeedsLabel 1 --outputCostVolume cost.nhdr \
--outputSpeedVolume speed.nhdr --anisotropyWeight 0.5

Once the cost image is generated, the user can then generate tracts between the any region of the brain and the seed region specified in the previous step. Fiber tracking is fairly quick and uses a gradient descent solution from the defined regions back to the seed points specified in '''gtractCostFastMarching'''. The parameters for [[gtractFastMarchingTracking Version 3]] can be obtained using the '-help' option from the command line. The resulting paths can be constrained using the anisotropy threshold and the number of iterations. This will help to eliminate unrealistic fiber tracts.

'''Example:'''
% gtractFastMarchingTracking --inputTensorVolume Tensor.nhdr \
--inputAnisotropyVolume FA.nhdr \
--inputStartingSeedsLabelMapVolume seedsEnd.nhdr \
--startingSeedsLabel 1 --inputCostVolume cost.nhdr \
--seedThreshold 0.3 --trackingThreshold 0.2 \
--outputTract fastMarching.vtk

==Visualizing Fiber Tracts==
The resulting fiber tracts can be loaded into [http://www.Slicer.org Slicer3] or [http://www.paraview.org Paraview]. After starting Slicer3, the loading of fiber tracts can be found under the '''Tractography->DisplayLoadSave''' module. Selecting this module will bring up the interface to load the fiber tracts. Select the '''Load Tractography''' Button and select the fiber tract of interest. The user can also select the type of glyph to be use for display, including, lines, tubes, or ellipsoids. The fiber tracts will be visible in the 3D view and can be overlaid on the image data as well.

{|
| style="width:50%" | [[Image:Slicer3-Display-Tracks.jpg|thumb|300px|Slicer3 DisplayLoadSave Tab]]
| style="width:50%" |
|}

== Mapping Fiber Tracts ==

== Data Analysis ==

GTRACT V4

2010-06-22T18:59:54Z

Hjmjohnson: Created page with '== GTRACT Overview == This is a manual for the GTRACT program. This program suite now incorporates a full DTI data processing pipeline. In this version of the tools, all of the…'

== GTRACT Overview ==

This is a manual for the GTRACT program. This program suite now incorporates a full DTI data processing pipeline. In this version of the tools, all of the functional units exist as command line programs that integrate with Slicer3 using the Execution model framework. The standard format for the DTI data in this version is the NRRD format. Anatomical images and label maps can be in any format supported by ITK. The program support several version of fiber tracking including:

# Free tracking - Basic streamlines with only a starting region
# Streamlines - Streamlines tracking between two regions of interest
# Graph Search - Modified streamlines that tries multiple solutions in low anisotropy regions
# Guided Tracking - Uses an initial guess to the fiber track to guide the tracking
# Fast Marching - Method based on the method proposed by Geoffrey Parker

Funding for this version of the GTRACT program was provided by NIH/NINDS R01NS050568-01A2S1. The software is hosted by the Neuroimaging Informatics Tools and Resources Clearinghouse [http://www.nitrc.org/projects/vmagnotta/ (NITRC)].

== Installing GTRACT ==
The easiest way to install GTRACT is to obtain pre-compiled binaries from the NITRC website. You should be able to download and install these on most platforms. Currently this is just an archive file for the various platforms that can be unpacked wherever the user has write access.

===Installing Into Slicer3===
The command line modules do support the Slicer3 execution model and could be placed within the Slicer3 build and will be become active when the user starts Slicer3. The modules are installed under the '''BRAINS->GTRACT''' menu in the Slicer3 Module tree. More details will be forthcoming on this. Copyright information for GTRACT can be obtained [https://mri.radiology.uiowa.edu/copyright/GTRACT-Copyright.txt here].

===Building GTRACT===
GTRACT depends on only ITK and VTK. It also requires CMake for building. Most recent versions of VTK and ITK should work. Presently GTRACT requires using CMake version 2.8 or higher for the builds.

== Conversion from DICOM to NRRD Format ==
The program for the conversion of DICOM images into Gordan Kindlmann's [http://teem.sourceforge.net/nrrd/ NRRD format] is supported by the Slicer3 DicomToNrrd. This is included within the GTRACT package for convenience. This program should handle most images from GE and Siemens scanners including Mosaic format images. For Siemens scanners, software version above VB13 should be supported. We would like to thank Xiaodong Tao for his great work on this tool. This program should read the diffusion directions from the DICOM header.

% DicomToNrrd <DICOM-Directory> <OutputDirectory> <OutputFilename>

The output file will contain the Diffusion weighted images in a vector format. The tools within the GTRACT analysis pipeline now expect the images in NRRD format.

== GTRACT Programs ==
This documentation is mostly generated using a script from http://svn.slicer.org/Slicer3/trunk/Scripts/SEMToMediaWiki.py

<pre>
python SEMToMediaWiki.py ${progname}.xml > ${progname}.txt
</pre>

* [[vmagnotta:compareTractInclusion|compareTractInclusion Documentation]]
* [[vmagnotta:extractNrrdVectorIndex|extractNrrdVectorIndex Documentation]]
* [[vmagnotta:gtractAnisotropyMap|gtractAnisotropyMap Documentation]]
* [[vmagnotta:gtractAverageBvalues|gtractAverageBvalues Documentation]]
* [[vmagnotta:gtractClipAnisotropy|gtractClipAnisotropy Documentation]]
* [[vmagnotta:gtractCoRegAnatomyBspline|gtractCoRegAnatomyBspline Documentation]]
* [[vmagnotta:gtractCoRegAnatomyPrimary|gtractCoRegAnatomyPrimary Documentation]]
* [[vmagnotta:gtractCoRegAnatomyRigid|gtractCoRegAnatomyRigid Documentation]]
* [[vmagnotta:gtractConcatDwi|gtractConcatDwi Documentation]]
* [[vmagnotta:gtractCopyImageOrientation|gtractCopyImageOrientation Documentation]]
* [[vmagnotta:gtractCoregBvaluesPrimary|gtractCoregBvaluesPrimary Documentation]]
* [[vmagnotta:gtractCostFastMarching|gtractCostFastMarching Documentation]]
* [[vmagnotta:gtractCreateGuideFiber|gtractCreateGuideFiber Documentation]]
* [[vmagnotta:gtractFastMarchingTracking|gtractFastMarchingTracking Documentation]]
* [[vmagnotta:gtractFiberTracking|gtractFiberTracking Documentation]]
* [[vmagnotta:gtractFreeTracking|gtractFreeTracking Documentation]]
* [[vmagnotta:gtractGraphSearchTracking|gtractGraphSearchTracking Documentation]]
* [[vmagnotta:gtractGuidedTracking|gtractGuidedTracking Documentation]]
* [[vmagnotta:gtractImageConformity|gtractImageConformity Documentation]]
* [[vmagnotta:gtractInvertBSplineTransform|gtractInvertBSplineTransform Documentation]]
* [[vmagnotta:gtractInvertDeformationField|gtractInvertDeformationField Documentation]]
* [[vmagnotta:gtractInvertRigidTransform|gtractInvertRigidTransform Documentation]]
* [[vmagnotta:gtractResampleAnisotropy|gtractResampleAnisotropy Documentation]]
* [[vmagnotta:gtractResampleB0|gtractResampleB0 Documentation]]
* [[vmagnotta:gtractResampleCodeImage|gtractResampleCodeImage Documentation]]
* [[vmagnotta:gtractResampleFibers|gtractResampleFibers Documentation]]
* [[vmagnotta:gtractStreamlineTracking|gtractStreamlineTracking Documentation]]
* [[vmagnotta:gtractTensor|gtractTensor Documentation]]
* [[vmagnotta:gtractTransformToDeformationField|gtractTransformToDeformationField Documentation]]

== DTI Image Co-Registration ==
Once the images are in NRRD format the next step in the analysis pipeline is the elimination of motion and eddy current artifacts between the diffusion weighted images. The program for this step of the analysis is '''gtractCoregBvalues'''. This program will support registration between two diffusion series in the case where you would like to average this data across runs. It also would allow for co-regsitration with a T2 weighted image or field map in the same plane as the DTI data.

A mutual information metric cost function is used for the registration because of the differences in the signal intensity as a result of the diffusion gradients. The fixed image for the registration should be a b0 image. The user has the option to perform a rigid or a full affine registration. The full affine allows the registration procedure to correct for eddy current distortions that may exist in the data. This is specified with the '''eddyCurrentCorrection''' option. In general the standard parameters work fairly well for a rigid registration, and you probably just need to specify the images for registration. When the eddyCurrent Correction is specified, then we have had to adjusrt the '''relaxationFactor''' and '''maximumStepSize''' parameters. We typically use values of around 0.25 for the relaxation factor and 0.1 for the maximum step size when this option is turned on.

% gtractCoregBvalues --fixedImageVolume baseImage.nhdr --movingImageVolume baseImage.nhdr --fixedImageIndex 0

A complete listing of parameters can be found here, [[gtractCoregBvalues]], or can be obtained on the command line using

% gtractCoregBvalues --help

== Tensor Image Calculation ==
This step takes the diffusion tensor image data and generates a tensor representation of the data based on the signal intensity decay, b values applied and the diffusion directions. The apparent diffusion (ADC) for a given orientation is computed on a pixel-by-pixel basis by fitting the image data (i.e. voxel intensities) to the Stejskal-Tanner equation:

Sb = S0 exp-b ADC

If at least six orientations are used, then the diffusion tensor can be computed. The measured ADC values is related to the diffusion tensor elements via the following equation:

ADC = M D

where ADC is a vector of the measured apparent diffusion coefficients, M is the matrix describing the diffusion directions applied, and D is a vector of the diffusion tensor elements. This can be solved using standard matrix operations

D = M-1 ADC

In this step we are solving for the diffusion tensor which contains size elements (Dxx, Dyy, Dzz, Dxy, Dxz, Dyz). These can then be used to define the diffusion tensor

|Dxx Dxy Dxz|
|Dyx Dyy Dyz| = D
|Dzx Dzy Dzz|

This is a symmetric matrix therefore Dxy=Dyx, Dxz=Dzx, and Dyz=Dzy.

The program [[gtractTensor]] is responsible for the estimation of the Tensor. The program uses itk::DiffusionTensor3DReconstructionImageFilter for this step. There are several options for the analysis that can be tuned by the user.

* '''Background threshold''' - This sets a threshold used on the b=0 image to remove background voxels from the processing. Typically a value around 100 works well for Siemens DTI images. We have found that 500 works better for GE datasets. Check your data particularly in the globus pallidus to make sure that brain tissue is not being eliminated with this threshold.

* '''Median filter''' - If the filter is enabled, a median filter will be applied to the data. The x, y, and z values specify the size of the median filter in voxels.

* '''Isotropic Resampling''' - If this option is enabled, the data will be resample to isotropic resolution specified. This is recommended if fiber tracking is to be performed.

'''Example:'''
% gtractTensor --inputVolume Series0003_coreg.nhdr --outputVolume Series0003_Tensor.nhdr \
--useMedianFilter --medianFilterSize 1,1,1 --backgroundSuppressingThreshold

--[[User:Admin|Admin]] 10:44, 2 July 2009 (CDT)

'''NOTE:''' We have recently made changes to this program top make it more flexible. There is now a ''--ignoreIndex'' option that allows the user to remove specific gradient directions if artifacts exist in a particular gradient direction. A DTI volume can now have multiple B0 and gradient direction images. These are now handled properly without requiring averaging of the diffusion weighted images. Averaging of the B0 image is done internally in this program.

== Compute Anisotropy Images ==
Anistropy mapping can be used to generate the following diffusion tensor indices:
* Fractional Anistroy (FA)
* Relative Anistroy (RA)
* Volume Ratio (VR)
* Lattice Index (LI)
* Coherence Index (CI)
* Mean Diffusivity (ADC)
* Axial Diffusivity (AD)
* Radial Diffusivity (RD)

Anisotropy images are used for fiber tracking, but the anisotropy scalars are not defined along the path. Instead the Tensor representation is included as point data allowing all of these metric to be computed using only the fiber tract point data. The images can be saved in any ITK supported format, but it is suggested that you use an image format that supports the definition of the image origin. This includes NRRD, NifTI, and Meta formats. These images can also be used for scalar analysis including regional anisotropy measures or VBM style analysis.

The command line parameters are defined here [[gtractAnisotropyMap Version 3]].

'''Example:'''
% gtractAnisotropyMap --inputVolume Series0003_Tensor.nhdr \
--anisotropyType FA --outputVolume Series0003_FA.nhdr

== Alignment with Anatomical Image ==
The two registration methods supported for alignment with Anatomical images, Rigid and B-Spline. The rigid registration performs a rigid body registration with the anatomical images and should be done as well to initialize the B-Spline transform. The B-SPline transform is the deformable transform, where the user can control the amount of deformation based on the number of control points as well as the maximum distance that these points can move. This allows for some susceptibility related distortions to be removed from the diffusion weighted images. It is recommended that for image co-registration with the B-Spline Transform that the skull stripped (i.e. image containing only brain with skull removed) image be used.

===Copy Reference Image Orientation===
Currently, the registration process requires that the diffusion weighted images and the anatomical images have the same image orientation (i.e. Axial, Coronal, Sagittal). It is suggested that you copy the image orientation from the diffusion weighted images and apply this to the anatomical image. This image can be subsequently removed after the registration step is complete. We anticipate that this limitation will be removed in future versions of the registration programs. The program '''gtractCopyImageOrientation''' is used for this step. The complete command line arguements for [[gtractCopyImageOrientation Version 3]] can be generated using the '--help' flag.

% gtractCopyImageOrientation --inputVolume T1_ACPC_clip.nii.gz \
--inputReferenceVolume DWI_coreg.nhdr --outputVolume T1_ACPC_Axial.nhdr

===Anatomical Rigid===
The rigid registration uses a mutual information metric to align the b0 image with the anatomical image. A reasonable set of parameters is specified as the default set of parameters. These were initially tested on a data from both a Siemens 1.5T and 3.0T scanners. Here are the complete set of parameters for [[gtractCoRegAnatomyRigid Version 3]]

'''Example'''
% gtractCoRegAnatomyRigid --inputVolume 0226770_DWI_coreg.nhdr \
--vectorIndex 0 --inputAnatomicalVolume 30670508_T1_ACPC_Axial.nhdr \
--outputRigidTransform ACPC_rigid.xfm --numberOfIterations 1000

It is recommended that the rigid registration be run before the B-Spline nonlinear registration is run.

{|
| style="width:50%" | [[Image:T1-Scan.gif|T1 Weighted Volume|300px|thumb|T1 Volume]]
| style="width:50%" | [[Image:DTI-Rigid.gif|300px|thumb|T1 Weighted with B0 image overlay]]
|}

===Anatomical B-Spline===
The B-SPline registration places a low dimensional grid in the image which is deformed. The B-Spline registratiuon works best if the anatomical image has been skull stripped and a rigid registration is used as the staring point for the registration. The user can specify the number of control points to be used in the registration and the maximum distance that each control point should move. In general the amount of motion in the slice selection and read-out directions direction should be kept low. The distortion is in the phase encoding direction in the images. A bulk transform can be applied to the B-Spline transform to initialize the transform. This should be the rigid transform generated from the previous step for the optimal results. The program '''gtractCoRegAnatomyBspline''' performs this registration step and a detailed list of parameters can nbe found here, [[gtractCoRegAnatomyBspline Version 3]]

'''Example:'''

% gtractCoRegAnatomyBspline

{|
| style="width:50%" | [[Image:DTI-Rigid.gif|300px|thumb|T1 Weighted Volume with B0 image (Rigid Registration) overlay]]
| style="width:50%" | [[Image:DTI-Bspline.gif|300px|thumb|T1 Weighted Volume with B0 image (B-Spline Registration) overlay.]]
|}

'''Notice:''' Improved registration especially at the anterior portion of the corpus callosum

===Invert Rigid Transform===
The program '''gtractInvertRigidTransform''' is used to invert rigid transforms. Typically this is used to map images in anatomical space to the diffusion weighted image space. This is useful for transforming labels defined on the anatomical image into the space of the diffusion weighted images to be used for fiber tracking. Complete parameters for [[gtractInvertRigidTransform Version 3]] are available using the '--help' option.

'''Example:'''
% gtractInvertRigidTransform --inputTransform ACPC_rigid.xfm \
--outputTransform ACPC_Inverse_Rigid.xfm

===Invert B-Spline===
Since the B-Spline transform cannot be directly inverted, we have implemented a thin plate spline approximation to its inverse. This can be created yusing the gtractInvertBspline. The X, Y and Z grid specifiy the grid utilized to sample the B-Spline transform. The parameters for [[gtractInvertBspline Version 3]] can be obtained using the '-help' option. The inverse needs to be computed to map fiber tracts from the DTI space to the anatomical image and to map regions of interest from the anatomical image onto the diffusion weighted images using this non-linear transform that accounts in part for susecptility artifcats.

'''Example'''
% gtractInvertBSplineTransform

===Resampling Images===
Three programs have been written to resample the various types of images that may be encountered in diffusion tensor analysis. All of the programs accept only ITK transforms and in particular '''Versor Rigid'' or '''B-Spline''' transforms that are described above.

* [[gtractResampleCodeImage Version 3]] - Resamples a mask or label - Image pixel type is signed short and neareast neigbor interpolation is used
* [[gtractResampleB0 Version 3]] - Resamples the B0 image - Image pixel type is signed short and linear interpolation is used
* [[gtractResampleAnisotropy Version 3]] - Resamples an anisotropy map - Image pixel type is float and linear interpolation is used

When running these programs the user must also specify a template image that will be used to define the origin, orientation, spacing and size of the resampled image.

'''Example:'''
% gtractResampleCodeImage --inputTransform ACPC_Inverse_Rigid.xfm -\
-transformType Rigid --inputCodeVolume Thal_axial.nhdr \
--inputReferenceVolume DWI_coreg.nhdr --outputVolume Thal_DWI.nhdr

You may want to save the aligned B0 image after each of the co-registration steps with the anatomical image to check the registration quality with another tool such as [http://www.nitrc.org/projects/brains/ BRAINS] or [http://www.slicer.org Slicer].

== Fiber Tracking ==

Once an isotropy image, a tensor image, and a spatial object have either been created and loaded fiber tracking can take place. Selecting the '''Tracking''' tab will allow the user to specify the type of tracking to be performed. Currently the GTRACT tool supports a number of fiber tracking methods. These include:

# [https://mri.radiology.uiowa.edu/mediawiki/index.php/GTRACT_Software_-_Version_3#Free_Tracking Free Tracking]
# [https://mri.radiology.uiowa.edu/mediawiki/index.php/GTRACT_Software_-_Version_3#Streamlines_Tracking Streamlines Tracking]
# [https://mri.radiology.uiowa.edu/mediawiki/index.php/GTRACT_Software_-_Version_3#Graph_Search_Tracking Graph Search Tracking]
# [https://mri.radiology.uiowa.edu/mediawiki/index.php/GTRACT_Software_-_Version_3#Guided_Tracking Guided Tracking]
# [https://mri.radiology.uiowa.edu/mediawiki/index.php/GTRACT_Software_-_Version_3#Fast_Marching_Tracking Fast Marching Tracking]

The output of the fiber tracking is vtkPolyData (i.e. Polylines) that can be loaded into Slicer3 for visualization. The poly data can be saved in either old VTK format files (.vtk) or in the new VTK XML format (.xml). Currently, Slicer3 only accepts the old .vtk file format. The polylines contain point data that defines ther Tensor at each point along the fiber tract. This can then be used to rendered as glyphs in Slicer3 and can be used to define severeal scalar measures without referencing back to the anisotropy images.

===Free Tracking===
The Free tracking is a basic streamlines algorithm. This is a direct implementation of the method original proposed by Basser et al. The tracking follows the primarty eigenvector. The tracking begins with seed points in the starting region. Only those voxels above the specified anisotropy threshold in the starting region are used as seed points. Tracking terminates either as a result of maximum fiber length, low ansiotropy, or large curvature. This is a great way to explore your data, but the tools to appropriately edit these down to a fiber tract of interest do not yet exist. The user should explore using the other approaches described below once they have performed an initial review of their data.
A complete set of parameters for [[gtractFreeTracking Version 3]] can be obtained using the '--help' option.

'''Example:'''
% gtractFreeTracking --inputTensorVolume Tensor.nhdr \
--inputAnisotropyVolume FA.nhdr \
--inputStartingSeedsLabelMapVolume Thal_DWI.nhdr \
--startingSeedsLabel 1 --seedThreshold 0.25 \
--curvatureThreshold 60 --outputTract freeTracking.vtk

===Streamline Tracking===
The streamlines algorithm is a direct implementation of the method original proposed by Basser et al. The tracking follows the primarty eigenvector. The tracking begins with seed points in the starting region. Only those voxels above the specified anisotropy threshold in the starting region are used as seed points. Tracking terminates either by reaching the ending region or reaching some stopping criteria. Stopping criteria are specified using the following parameters:

* '''Tracking Threshold''': Anistropy values of the next point along the path
* '''Curvature''': Angle of the next tracking direction relative to the current path direction
* '''Max Length''': Length of the track in voxels

Only paths terminating in the ending region are kept in this method. The TEND algorithm proposed by Lazar et al. ([http://www3.interscience.wiley.com/cgi-bin/abstract/103525670/ABSTRACT?CRETRY=1&SRETRY=0 Human Brain Mapping 18:306-321, 2003]) has been instrumented. This can be enabled using the '''--useTend''' option while performing Streamlines tracking. This utilizes the entire diffusion tensor to deflect the incoming vector instead of simply following the primary eigenvector. The TEND parameters are set using the '''--tendF''' and '''--tendG''' options.

vout = fe1 + (1-f) * ((1-g)vin+gD · vin)

Where:
*vout is the outgoing vector direction
*vin is the incoming vector direction defined in the previous step
*ein is the primary eigenvector direction
*D is the diffusion Tensor

The complete set of command line arguements for [[gtractStreamlineTracking Version 3]] are available with the '--help' option at the command line.

'''Example:'''
% gtractStreamlineTracking

===Graph Search Tracking===
The Graph Serach tracking is the first step in the full GTRACT algorithm developed by Cheng et al. ([http://www.sciencedirect.com/science?_ob=ArticleURL&_udi=B6WNP-4JVTCDN-1&_user=440026&_rdoc=1&_fmt=&_orig=search&_sort=d&view=c&_acct=C000020939&_version=1&_urlVersion=0&_userid=440026&md5=a58d1d1ffaf9741f2d95aa294e017b17 NeuroImage 31(3): 1075-1085, 2006]). for finding the tracks in a tensor image. This method was developed to
generate fibers in a Tensor representation where crossing fibers occur. The graph search algorithm follows the primary eigenvector in non-ambigous regions and utilizes branching and a graph search algorithm in ambigous regions. Ambigous tracking regions are defined based on two criteria:

*'''Branching AI Threshold''': Anistropy values below this value and above the tracking threshold
* '''Curvature Major Eigen''': Angles of the primary eigenvector direction and the current tracking direction

In regions that meet this criteria, two or three tracking paths are considered. The first is the standard primary eigenvector direction. The second is the seconadary eigenvector direction. This is based on the assumption that these regions may be prolate regions. If the '''Random Walk''' option is selected then a third direction is also considered. This direction is defined by a cone pointing from the current position to the centroid of the ending region. The interior angle of the cone is specified by the user with the '''Branch/Guide Angle''' parameter. A vector contained inside of the cone is selected at random and used as the third direction. This method can also utilize the TEND option where the primary tracking direction is that specified by the TEND method instead of the primary eigenvector.

The parameter '--maximumBranchPoints' allows the tracking to have this number of branches being considered at a time. If this number of branch points is exceeded at any time, then the algorithm will revert back to a streamline alogrithm until the number of branches is reduced. This allows the user to constrain the computational complexity of the algorithm. A complete set of command line arguements for [[gtractGraphSearchTracking Version 3]] can be obtained using the '--help' option from the command line.

'''Example:'''
% gtractGraphSearchTracking

===Guided Tracking===
The second phase of the GTRACT algorithm is Guided Tracking. This method incorporates anatomical information about the track orientation using an initial guess of the fiber track. In the originally proposed GTRACT method, this would be created from the fibers resulting from the Graph Search tracking. However, in practice this can be created using any method and could be defined manually. To create the guide fiber the program '''gtractCreateGuideFiber''' can be used. This program will load a fiber tract that has been generated and create a centerline representation of the fiber tract (i.e. a single fiber). The complete set of parameters for [[gtractCreateGuideFiber Version 3]] can be obtained using the '--help' option.

'''Example:'''
% gtractCreateGuideFiber --inputFiber graph.vtk --outputFiber guide.vtk --numberOfPoints 100

In this method, the fiber tracking follows the primary eigenvector direction unless it deviates from the guide fiber track by a angle greater than that specified by the '--guidedCurvatureThreshold' parameter. The program [[gtractGuidedTracking Version 3]] implements this algorithm. The user must specify the guide fiber when running this program.

'''Example:'''
% gtractGuidedTracking

===Fast Marching Tracking===

This algorithm implements a fast marching fiber tracking algorithm to identify fiber tracts from a tensor image. This
algorithm is based on the work by G. Parker et al. ([http://ieeexplore.ieee.org/xpl/freeabs_all.jsp?isnumber=21763&arnumber=1009386&count=12&index=8 IEEE Transactions On Medical Imaging, 21(5): 505-512, 2002]) An additional
feature of this version is the inclusion of anisotropy in the cost function calculation. The user has the ability to weight the contribution of the anisotropy weight.

This algorithm is broken into two parts. The first phase of the algorithm generates a cost image. This starts with a seed region specified by the user. The cost of the path tracking from the seed region to every voxel in the brain is computed. The cost is based on the direction of the front, the primary eigenvector direction, and the anisotropy value. The user can adjust the weight of the anisotropy value using the '--anisotropyWeight' flag. The program [[gtractCostFastMarching version 3]] is responsible for the generation of the cost image. This may take several minutes to generate and increases with the size of the seed region. Currently, both a cost and spped image are generated. The speed image is not used in the fiber tracking phase and will become an optional parameter in future releases. Currently, it is a required parameter.

'''Example:'''
% gtractCostFastMarching --inputTensorVolume Tensor.nhdr \
--inputAnisotropyVolume FA.nhdr \
--inputStartingSeedsLabelMapVolume seeds.nhdr \
--startingSeedsLabel 1 --outputCostVolume cost.nhdr \
--outputSpeedVolume speed.nhdr --anisotropyWeight 0.5

Once the cost image is generated, the user can then generate tracts between the any region of the brain and the seed region specified in the previous step. Fiber tracking is fairly quick and uses a gradient descent solution from the defined regions back to the seed points specified in '''gtractCostFastMarching'''. The parameters for [[gtractFastMarchingTracking Version 3]] can be obtained using the '-help' option from the command line. The resulting paths can be constrained using the anisotropy threshold and the number of iterations. This will help to eliminate unrealistic fiber tracts.

'''Example:'''
% gtractFastMarchingTracking --inputTensorVolume Tensor.nhdr \
--inputAnisotropyVolume FA.nhdr \
--inputStartingSeedsLabelMapVolume seedsEnd.nhdr \
--startingSeedsLabel 1 --inputCostVolume cost.nhdr \
--seedThreshold 0.3 --trackingThreshold 0.2 \
--outputTract fastMarching.vtk

==Visualizing Fiber Tracts==
The resulting fiber tracts can be loaded into [http://www.Slicer.org Slicer3] or [http://www.paraview.org Paraview]. After starting Slicer3, the loading of fiber tracts can be found under the '''Tractography->DisplayLoadSave''' module. Selecting this module will bring up the interface to load the fiber tracts. Select the '''Load Tractography''' Button and select the fiber tract of interest. The user can also select the type of glyph to be use for display, including, lines, tubes, or ellipsoids. The fiber tracts will be visible in the 3D view and can be overlaid on the image data as well.

{|
| style="width:50%" | [[Image:Slicer3-Display-Tracks.jpg|thumb|300px|Slicer3 DisplayLoadSave Tab]]
| style="width:50%" |
|}

== Mapping Fiber Tracts ==

== Data Analysis ==

Modules:GTRACT

2010-06-22T18:59:45Z

Hjmjohnson: /* GTRACT v4 */

== GTRACT v4 ==

[[GTRACT_V4|Documentation for GTRACT version 4]]

== GTRACT v3.0.0 ==
Previous documentation for GTRACT Version 3 can be found at the following Website:
https://mri.radiology.uiowa.edu/mediawiki/index.php/GTRACT_Software_-_Version_3

Vmagnotta:GTRACT V4

2010-06-22T18:58:50Z

== GTRACT Overview ==

This is a manual for the GTRACT program. This program suite now incorporates a full DTI data processing pipeline. In this version of the tools, all of the functional units exist as command line programs that integrate with Slicer3 using the Execution model framework. The standard format for the DTI data in this version is the NRRD format. Anatomical images and label maps can be in any format supported by ITK. The program support several version of fiber tracking including:

# Free tracking - Basic streamlines with only a starting region
# Streamlines - Streamlines tracking between two regions of interest
# Graph Search - Modified streamlines that tries multiple solutions in low anisotropy regions
# Guided Tracking - Uses an initial guess to the fiber track to guide the tracking
# Fast Marching - Method based on the method proposed by Geoffrey Parker

Funding for this version of the GTRACT program was provided by NIH/NINDS R01NS050568-01A2S1. The software is hosted by the Neuroimaging Informatics Tools and Resources Clearinghouse [http://www.nitrc.org/projects/vmagnotta/ (NITRC)].

== Installing GTRACT ==
The easiest way to install GTRACT is to obtain pre-compiled binaries from the NITRC website. You should be able to download and install these on most platforms. Currently this is just an archive file for the various platforms that can be unpacked wherever the user has write access.

===Installing Into Slicer3===
The command line modules do support the Slicer3 execution model and could be placed within the Slicer3 build and will be become active when the user starts Slicer3. The modules are installed under the '''BRAINS->GTRACT''' menu in the Slicer3 Module tree. More details will be forthcoming on this. Copyright information for GTRACT can be obtained [https://mri.radiology.uiowa.edu/copyright/GTRACT-Copyright.txt here].

===Building GTRACT===
GTRACT depends on only ITK and VTK. It also requires CMake for building. Most recent versions of VTK and ITK should work. Presently GTRACT requires using CMake version 2.8 or higher for the builds.

== Conversion from DICOM to NRRD Format ==
The program for the conversion of DICOM images into Gordan Kindlmann's [http://teem.sourceforge.net/nrrd/ NRRD format] is supported by the Slicer3 DicomToNrrd. This is included within the GTRACT package for convenience. This program should handle most images from GE and Siemens scanners including Mosaic format images. For Siemens scanners, software version above VB13 should be supported. We would like to thank Xiaodong Tao for his great work on this tool. This program should read the diffusion directions from the DICOM header.

% DicomToNrrd <DICOM-Directory> <OutputDirectory> <OutputFilename>

The output file will contain the Diffusion weighted images in a vector format. The tools within the GTRACT analysis pipeline now expect the images in NRRD format.

== GTRACT Programs ==
This documentation is mostly generated using a script from http://svn.slicer.org/Slicer3/trunk/Scripts/SEMToMediaWiki.py

<pre>
python SEMToMediaWiki.py ${progname}.xml > ${progname}.txt
</pre>

* [[vmagnotta:compareTractInclusion|compareTractInclusion Documentation]]
* [[vmagnotta:extractNrrdVectorIndex|extractNrrdVectorIndex Documentation]]
* [[vmagnotta:gtractAnisotropyMap|gtractAnisotropyMap Documentation]]
* [[vmagnotta:gtractAverageBvalues|gtractAverageBvalues Documentation]]
* [[vmagnotta:gtractClipAnisotropy|gtractClipAnisotropy Documentation]]
* [[vmagnotta:gtractCoRegAnatomyBspline|gtractCoRegAnatomyBspline Documentation]]
* [[vmagnotta:gtractCoRegAnatomyPrimary|gtractCoRegAnatomyPrimary Documentation]]
* [[vmagnotta:gtractCoRegAnatomyRigid|gtractCoRegAnatomyRigid Documentation]]
* [[vmagnotta:gtractConcatDwi|gtractConcatDwi Documentation]]
* [[vmagnotta:gtractCopyImageOrientation|gtractCopyImageOrientation Documentation]]
* [[vmagnotta:gtractCoregBvaluesPrimary|gtractCoregBvaluesPrimary Documentation]]
* [[vmagnotta:gtractCostFastMarching|gtractCostFastMarching Documentation]]
* [[vmagnotta:gtractCreateGuideFiber|gtractCreateGuideFiber Documentation]]
* [[vmagnotta:gtractFastMarchingTracking|gtractFastMarchingTracking Documentation]]
* [[vmagnotta:gtractFiberTracking|gtractFiberTracking Documentation]]
* [[vmagnotta:gtractFreeTracking|gtractFreeTracking Documentation]]
* [[vmagnotta:gtractGraphSearchTracking|gtractGraphSearchTracking Documentation]]
* [[vmagnotta:gtractGuidedTracking|gtractGuidedTracking Documentation]]
* [[vmagnotta:gtractImageConformity|gtractImageConformity Documentation]]
* [[vmagnotta:gtractInvertBSplineTransform|gtractInvertBSplineTransform Documentation]]
* [[vmagnotta:gtractInvertDeformationField|gtractInvertDeformationField Documentation]]
* [[vmagnotta:gtractInvertRigidTransform|gtractInvertRigidTransform Documentation]]
* [[vmagnotta:gtractResampleAnisotropy|gtractResampleAnisotropy Documentation]]
* [[vmagnotta:gtractResampleB0|gtractResampleB0 Documentation]]
* [[vmagnotta:gtractResampleCodeImage|gtractResampleCodeImage Documentation]]
* [[vmagnotta:gtractResampleFibers|gtractResampleFibers Documentation]]
* [[vmagnotta:gtractStreamlineTracking|gtractStreamlineTracking Documentation]]
* [[vmagnotta:gtractTensor|gtractTensor Documentation]]
* [[vmagnotta:gtractTransformToDeformationField|gtractTransformToDeformationField Documentation]]

== DTI Image Co-Registration ==
Once the images are in NRRD format the next step in the analysis pipeline is the elimination of motion and eddy current artifacts between the diffusion weighted images. The program for this step of the analysis is '''gtractCoregBvalues'''. This program will support registration between two diffusion series in the case where you would like to average this data across runs. It also would allow for co-regsitration with a T2 weighted image or field map in the same plane as the DTI data.

A mutual information metric cost function is used for the registration because of the differences in the signal intensity as a result of the diffusion gradients. The fixed image for the registration should be a b0 image. The user has the option to perform a rigid or a full affine registration. The full affine allows the registration procedure to correct for eddy current distortions that may exist in the data. This is specified with the '''eddyCurrentCorrection''' option. In general the standard parameters work fairly well for a rigid registration, and you probably just need to specify the images for registration. When the eddyCurrent Correction is specified, then we have had to adjusrt the '''relaxationFactor''' and '''maximumStepSize''' parameters. We typically use values of around 0.25 for the relaxation factor and 0.1 for the maximum step size when this option is turned on.

% gtractCoregBvalues --fixedImageVolume baseImage.nhdr --movingImageVolume baseImage.nhdr --fixedImageIndex 0

A complete listing of parameters can be found here, [[gtractCoregBvalues]], or can be obtained on the command line using

% gtractCoregBvalues --help

== Tensor Image Calculation ==
This step takes the diffusion tensor image data and generates a tensor representation of the data based on the signal intensity decay, b values applied and the diffusion directions. The apparent diffusion (ADC) for a given orientation is computed on a pixel-by-pixel basis by fitting the image data (i.e. voxel intensities) to the Stejskal-Tanner equation:

Sb = S0 exp-b ADC

If at least six orientations are used, then the diffusion tensor can be computed. The measured ADC values is related to the diffusion tensor elements via the following equation:

ADC = M D

where ADC is a vector of the measured apparent diffusion coefficients, M is the matrix describing the diffusion directions applied, and D is a vector of the diffusion tensor elements. This can be solved using standard matrix operations

D = M-1 ADC

In this step we are solving for the diffusion tensor which contains size elements (Dxx, Dyy, Dzz, Dxy, Dxz, Dyz). These can then be used to define the diffusion tensor

|Dxx Dxy Dxz|
|Dyx Dyy Dyz| = D
|Dzx Dzy Dzz|

This is a symmetric matrix therefore Dxy=Dyx, Dxz=Dzx, and Dyz=Dzy.

The program [[gtractTensor]] is responsible for the estimation of the Tensor. The program uses itk::DiffusionTensor3DReconstructionImageFilter for this step. There are several options for the analysis that can be tuned by the user.

* '''Background threshold''' - This sets a threshold used on the b=0 image to remove background voxels from the processing. Typically a value around 100 works well for Siemens DTI images. We have found that 500 works better for GE datasets. Check your data particularly in the globus pallidus to make sure that brain tissue is not being eliminated with this threshold.

* '''Median filter''' - If the filter is enabled, a median filter will be applied to the data. The x, y, and z values specify the size of the median filter in voxels.

* '''Isotropic Resampling''' - If this option is enabled, the data will be resample to isotropic resolution specified. This is recommended if fiber tracking is to be performed.

'''Example:'''
% gtractTensor --inputVolume Series0003_coreg.nhdr --outputVolume Series0003_Tensor.nhdr \
--useMedianFilter --medianFilterSize 1,1,1 --backgroundSuppressingThreshold

--[[User:Admin|Admin]] 10:44, 2 July 2009 (CDT)

'''NOTE:''' We have recently made changes to this program top make it more flexible. There is now a ''--ignoreIndex'' option that allows the user to remove specific gradient directions if artifacts exist in a particular gradient direction. A DTI volume can now have multiple B0 and gradient direction images. These are now handled properly without requiring averaging of the diffusion weighted images. Averaging of the B0 image is done internally in this program.

== Compute Anisotropy Images ==
Anistropy mapping can be used to generate the following diffusion tensor indices:
* Fractional Anistroy (FA)
* Relative Anistroy (RA)
* Volume Ratio (VR)
* Lattice Index (LI)
* Coherence Index (CI)
* Mean Diffusivity (ADC)
* Axial Diffusivity (AD)
* Radial Diffusivity (RD)

Anisotropy images are used for fiber tracking, but the anisotropy scalars are not defined along the path. Instead the Tensor representation is included as point data allowing all of these metric to be computed using only the fiber tract point data. The images can be saved in any ITK supported format, but it is suggested that you use an image format that supports the definition of the image origin. This includes NRRD, NifTI, and Meta formats. These images can also be used for scalar analysis including regional anisotropy measures or VBM style analysis.

The command line parameters are defined here [[gtractAnisotropyMap Version 3]].

'''Example:'''
% gtractAnisotropyMap --inputVolume Series0003_Tensor.nhdr \
--anisotropyType FA --outputVolume Series0003_FA.nhdr

== Alignment with Anatomical Image ==
The two registration methods supported for alignment with Anatomical images, Rigid and B-Spline. The rigid registration performs a rigid body registration with the anatomical images and should be done as well to initialize the B-Spline transform. The B-SPline transform is the deformable transform, where the user can control the amount of deformation based on the number of control points as well as the maximum distance that these points can move. This allows for some susceptibility related distortions to be removed from the diffusion weighted images. It is recommended that for image co-registration with the B-Spline Transform that the skull stripped (i.e. image containing only brain with skull removed) image be used.

===Copy Reference Image Orientation===
Currently, the registration process requires that the diffusion weighted images and the anatomical images have the same image orientation (i.e. Axial, Coronal, Sagittal). It is suggested that you copy the image orientation from the diffusion weighted images and apply this to the anatomical image. This image can be subsequently removed after the registration step is complete. We anticipate that this limitation will be removed in future versions of the registration programs. The program '''gtractCopyImageOrientation''' is used for this step. The complete command line arguements for [[gtractCopyImageOrientation Version 3]] can be generated using the '--help' flag.

% gtractCopyImageOrientation --inputVolume T1_ACPC_clip.nii.gz \
--inputReferenceVolume DWI_coreg.nhdr --outputVolume T1_ACPC_Axial.nhdr

===Anatomical Rigid===
The rigid registration uses a mutual information metric to align the b0 image with the anatomical image. A reasonable set of parameters is specified as the default set of parameters. These were initially tested on a data from both a Siemens 1.5T and 3.0T scanners. Here are the complete set of parameters for [[gtractCoRegAnatomyRigid Version 3]]

'''Example'''
% gtractCoRegAnatomyRigid --inputVolume 0226770_DWI_coreg.nhdr \
--vectorIndex 0 --inputAnatomicalVolume 30670508_T1_ACPC_Axial.nhdr \
--outputRigidTransform ACPC_rigid.xfm --numberOfIterations 1000

It is recommended that the rigid registration be run before the B-Spline nonlinear registration is run.

{|
| style="width:50%" | [[Image:T1-Scan.gif|T1 Weighted Volume|300px|thumb|T1 Volume]]
| style="width:50%" | [[Image:DTI-Rigid.gif|300px|thumb|T1 Weighted with B0 image overlay]]
|}

===Anatomical B-Spline===
The B-SPline registration places a low dimensional grid in the image which is deformed. The B-Spline registratiuon works best if the anatomical image has been skull stripped and a rigid registration is used as the staring point for the registration. The user can specify the number of control points to be used in the registration and the maximum distance that each control point should move. In general the amount of motion in the slice selection and read-out directions direction should be kept low. The distortion is in the phase encoding direction in the images. A bulk transform can be applied to the B-Spline transform to initialize the transform. This should be the rigid transform generated from the previous step for the optimal results. The program '''gtractCoRegAnatomyBspline''' performs this registration step and a detailed list of parameters can nbe found here, [[gtractCoRegAnatomyBspline Version 3]]

'''Example:'''

% gtractCoRegAnatomyBspline

{|
| style="width:50%" | [[Image:DTI-Rigid.gif|300px|thumb|T1 Weighted Volume with B0 image (Rigid Registration) overlay]]
| style="width:50%" | [[Image:DTI-Bspline.gif|300px|thumb|T1 Weighted Volume with B0 image (B-Spline Registration) overlay.]]
|}

'''Notice:''' Improved registration especially at the anterior portion of the corpus callosum

===Invert Rigid Transform===
The program '''gtractInvertRigidTransform''' is used to invert rigid transforms. Typically this is used to map images in anatomical space to the diffusion weighted image space. This is useful for transforming labels defined on the anatomical image into the space of the diffusion weighted images to be used for fiber tracking. Complete parameters for [[gtractInvertRigidTransform Version 3]] are available using the '--help' option.

'''Example:'''
% gtractInvertRigidTransform --inputTransform ACPC_rigid.xfm \
--outputTransform ACPC_Inverse_Rigid.xfm

===Invert B-Spline===
Since the B-Spline transform cannot be directly inverted, we have implemented a thin plate spline approximation to its inverse. This can be created yusing the gtractInvertBspline. The X, Y and Z grid specifiy the grid utilized to sample the B-Spline transform. The parameters for [[gtractInvertBspline Version 3]] can be obtained using the '-help' option. The inverse needs to be computed to map fiber tracts from the DTI space to the anatomical image and to map regions of interest from the anatomical image onto the diffusion weighted images using this non-linear transform that accounts in part for susecptility artifcats.

'''Example'''
% gtractInvertBSplineTransform

===Resampling Images===
Three programs have been written to resample the various types of images that may be encountered in diffusion tensor analysis. All of the programs accept only ITK transforms and in particular '''Versor Rigid'' or '''B-Spline''' transforms that are described above.

* [[gtractResampleCodeImage Version 3]] - Resamples a mask or label - Image pixel type is signed short and neareast neigbor interpolation is used
* [[gtractResampleB0 Version 3]] - Resamples the B0 image - Image pixel type is signed short and linear interpolation is used
* [[gtractResampleAnisotropy Version 3]] - Resamples an anisotropy map - Image pixel type is float and linear interpolation is used

When running these programs the user must also specify a template image that will be used to define the origin, orientation, spacing and size of the resampled image.

'''Example:'''
% gtractResampleCodeImage --inputTransform ACPC_Inverse_Rigid.xfm -\
-transformType Rigid --inputCodeVolume Thal_axial.nhdr \
--inputReferenceVolume DWI_coreg.nhdr --outputVolume Thal_DWI.nhdr

You may want to save the aligned B0 image after each of the co-registration steps with the anatomical image to check the registration quality with another tool such as [http://www.nitrc.org/projects/brains/ BRAINS] or [http://www.slicer.org Slicer].

== Fiber Tracking ==

Once an isotropy image, a tensor image, and a spatial object have either been created and loaded fiber tracking can take place. Selecting the '''Tracking''' tab will allow the user to specify the type of tracking to be performed. Currently the GTRACT tool supports a number of fiber tracking methods. These include:

# [https://mri.radiology.uiowa.edu/mediawiki/index.php/GTRACT_Software_-_Version_3#Free_Tracking Free Tracking]
# [https://mri.radiology.uiowa.edu/mediawiki/index.php/GTRACT_Software_-_Version_3#Streamlines_Tracking Streamlines Tracking]
# [https://mri.radiology.uiowa.edu/mediawiki/index.php/GTRACT_Software_-_Version_3#Graph_Search_Tracking Graph Search Tracking]
# [https://mri.radiology.uiowa.edu/mediawiki/index.php/GTRACT_Software_-_Version_3#Guided_Tracking Guided Tracking]
# [https://mri.radiology.uiowa.edu/mediawiki/index.php/GTRACT_Software_-_Version_3#Fast_Marching_Tracking Fast Marching Tracking]

The output of the fiber tracking is vtkPolyData (i.e. Polylines) that can be loaded into Slicer3 for visualization. The poly data can be saved in either old VTK format files (.vtk) or in the new VTK XML format (.xml). Currently, Slicer3 only accepts the old .vtk file format. The polylines contain point data that defines ther Tensor at each point along the fiber tract. This can then be used to rendered as glyphs in Slicer3 and can be used to define severeal scalar measures without referencing back to the anisotropy images.

===Free Tracking===
The Free tracking is a basic streamlines algorithm. This is a direct implementation of the method original proposed by Basser et al. The tracking follows the primarty eigenvector. The tracking begins with seed points in the starting region. Only those voxels above the specified anisotropy threshold in the starting region are used as seed points. Tracking terminates either as a result of maximum fiber length, low ansiotropy, or large curvature. This is a great way to explore your data, but the tools to appropriately edit these down to a fiber tract of interest do not yet exist. The user should explore using the other approaches described below once they have performed an initial review of their data.
A complete set of parameters for [[gtractFreeTracking Version 3]] can be obtained using the '--help' option.

'''Example:'''
% gtractFreeTracking --inputTensorVolume Tensor.nhdr \
--inputAnisotropyVolume FA.nhdr \
--inputStartingSeedsLabelMapVolume Thal_DWI.nhdr \
--startingSeedsLabel 1 --seedThreshold 0.25 \
--curvatureThreshold 60 --outputTract freeTracking.vtk

===Streamline Tracking===
The streamlines algorithm is a direct implementation of the method original proposed by Basser et al. The tracking follows the primarty eigenvector. The tracking begins with seed points in the starting region. Only those voxels above the specified anisotropy threshold in the starting region are used as seed points. Tracking terminates either by reaching the ending region or reaching some stopping criteria. Stopping criteria are specified using the following parameters:

* '''Tracking Threshold''': Anistropy values of the next point along the path
* '''Curvature''': Angle of the next tracking direction relative to the current path direction
* '''Max Length''': Length of the track in voxels

Only paths terminating in the ending region are kept in this method. The TEND algorithm proposed by Lazar et al. ([http://www3.interscience.wiley.com/cgi-bin/abstract/103525670/ABSTRACT?CRETRY=1&SRETRY=0 Human Brain Mapping 18:306-321, 2003]) has been instrumented. This can be enabled using the '''--useTend''' option while performing Streamlines tracking. This utilizes the entire diffusion tensor to deflect the incoming vector instead of simply following the primary eigenvector. The TEND parameters are set using the '''--tendF''' and '''--tendG''' options.

vout = fe1 + (1-f) * ((1-g)vin+gD · vin)

Where:
*vout is the outgoing vector direction
*vin is the incoming vector direction defined in the previous step
*ein is the primary eigenvector direction
*D is the diffusion Tensor

The complete set of command line arguements for [[gtractStreamlineTracking Version 3]] are available with the '--help' option at the command line.

'''Example:'''
% gtractStreamlineTracking

===Graph Search Tracking===
The Graph Serach tracking is the first step in the full GTRACT algorithm developed by Cheng et al. ([http://www.sciencedirect.com/science?_ob=ArticleURL&_udi=B6WNP-4JVTCDN-1&_user=440026&_rdoc=1&_fmt=&_orig=search&_sort=d&view=c&_acct=C000020939&_version=1&_urlVersion=0&_userid=440026&md5=a58d1d1ffaf9741f2d95aa294e017b17 NeuroImage 31(3): 1075-1085, 2006]). for finding the tracks in a tensor image. This method was developed to
generate fibers in a Tensor representation where crossing fibers occur. The graph search algorithm follows the primary eigenvector in non-ambigous regions and utilizes branching and a graph search algorithm in ambigous regions. Ambigous tracking regions are defined based on two criteria:

*'''Branching AI Threshold''': Anistropy values below this value and above the tracking threshold
* '''Curvature Major Eigen''': Angles of the primary eigenvector direction and the current tracking direction

In regions that meet this criteria, two or three tracking paths are considered. The first is the standard primary eigenvector direction. The second is the seconadary eigenvector direction. This is based on the assumption that these regions may be prolate regions. If the '''Random Walk''' option is selected then a third direction is also considered. This direction is defined by a cone pointing from the current position to the centroid of the ending region. The interior angle of the cone is specified by the user with the '''Branch/Guide Angle''' parameter. A vector contained inside of the cone is selected at random and used as the third direction. This method can also utilize the TEND option where the primary tracking direction is that specified by the TEND method instead of the primary eigenvector.

The parameter '--maximumBranchPoints' allows the tracking to have this number of branches being considered at a time. If this number of branch points is exceeded at any time, then the algorithm will revert back to a streamline alogrithm until the number of branches is reduced. This allows the user to constrain the computational complexity of the algorithm. A complete set of command line arguements for [[gtractGraphSearchTracking Version 3]] can be obtained using the '--help' option from the command line.

'''Example:'''
% gtractGraphSearchTracking

===Guided Tracking===
The second phase of the GTRACT algorithm is Guided Tracking. This method incorporates anatomical information about the track orientation using an initial guess of the fiber track. In the originally proposed GTRACT method, this would be created from the fibers resulting from the Graph Search tracking. However, in practice this can be created using any method and could be defined manually. To create the guide fiber the program '''gtractCreateGuideFiber''' can be used. This program will load a fiber tract that has been generated and create a centerline representation of the fiber tract (i.e. a single fiber). The complete set of parameters for [[gtractCreateGuideFiber Version 3]] can be obtained using the '--help' option.

'''Example:'''
% gtractCreateGuideFiber --inputFiber graph.vtk --outputFiber guide.vtk --numberOfPoints 100

In this method, the fiber tracking follows the primary eigenvector direction unless it deviates from the guide fiber track by a angle greater than that specified by the '--guidedCurvatureThreshold' parameter. The program [[gtractGuidedTracking Version 3]] implements this algorithm. The user must specify the guide fiber when running this program.

'''Example:'''
% gtractGuidedTracking

===Fast Marching Tracking===

This algorithm implements a fast marching fiber tracking algorithm to identify fiber tracts from a tensor image. This
algorithm is based on the work by G. Parker et al. ([http://ieeexplore.ieee.org/xpl/freeabs_all.jsp?isnumber=21763&arnumber=1009386&count=12&index=8 IEEE Transactions On Medical Imaging, 21(5): 505-512, 2002]) An additional
feature of this version is the inclusion of anisotropy in the cost function calculation. The user has the ability to weight the contribution of the anisotropy weight.

This algorithm is broken into two parts. The first phase of the algorithm generates a cost image. This starts with a seed region specified by the user. The cost of the path tracking from the seed region to every voxel in the brain is computed. The cost is based on the direction of the front, the primary eigenvector direction, and the anisotropy value. The user can adjust the weight of the anisotropy value using the '--anisotropyWeight' flag. The program [[gtractCostFastMarching version 3]] is responsible for the generation of the cost image. This may take several minutes to generate and increases with the size of the seed region. Currently, both a cost and spped image are generated. The speed image is not used in the fiber tracking phase and will become an optional parameter in future releases. Currently, it is a required parameter.

'''Example:'''
% gtractCostFastMarching --inputTensorVolume Tensor.nhdr \
--inputAnisotropyVolume FA.nhdr \
--inputStartingSeedsLabelMapVolume seeds.nhdr \
--startingSeedsLabel 1 --outputCostVolume cost.nhdr \
--outputSpeedVolume speed.nhdr --anisotropyWeight 0.5

Once the cost image is generated, the user can then generate tracts between the any region of the brain and the seed region specified in the previous step. Fiber tracking is fairly quick and uses a gradient descent solution from the defined regions back to the seed points specified in '''gtractCostFastMarching'''. The parameters for [[gtractFastMarchingTracking Version 3]] can be obtained using the '-help' option from the command line. The resulting paths can be constrained using the anisotropy threshold and the number of iterations. This will help to eliminate unrealistic fiber tracts.

'''Example:'''
% gtractFastMarchingTracking --inputTensorVolume Tensor.nhdr \
--inputAnisotropyVolume FA.nhdr \
--inputStartingSeedsLabelMapVolume seedsEnd.nhdr \
--startingSeedsLabel 1 --inputCostVolume cost.nhdr \
--seedThreshold 0.3 --trackingThreshold 0.2 \
--outputTract fastMarching.vtk

==Visualizing Fiber Tracts==
The resulting fiber tracts can be loaded into [http://www.Slicer.org Slicer3] or [http://www.paraview.org Paraview]. After starting Slicer3, the loading of fiber tracts can be found under the '''Tractography->DisplayLoadSave''' module. Selecting this module will bring up the interface to load the fiber tracts. Select the '''Load Tractography''' Button and select the fiber tract of interest. The user can also select the type of glyph to be use for display, including, lines, tubes, or ellipsoids. The fiber tracts will be visible in the 3D view and can be overlaid on the image data as well.

{|
| style="width:50%" | [[Image:Slicer3-Display-Tracks.jpg|thumb|300px|Slicer3 DisplayLoadSave Tab]]
| style="width:50%" |
|}

== Mapping Fiber Tracts ==

== Data Analysis ==

Modules:GTRACT

2010-06-22T18:58:03Z

Hjmjohnson: GTRACT

== GTRACT v4 ==

[[vmagnotta:GTRACT_V4|Documentation for GTRACT version 4]]

== GTRACT v3.0.0 ==
Previous documentation for GTRACT Version 3 can be found at the following Website:
https://mri.radiology.uiowa.edu/mediawiki/index.php/GTRACT_Software_-_Version_3

File:BRAINSResample.png

2010-06-10T20:20:53Z

Hjmjohnson:

Announcements:Slicer3.6

2010-06-10T19:46:05Z

Hjmjohnson: /* Slicer Highlights */

[[Documentation-3.6|Back to Documentation 3.6]]
[[image:Slicer3-6Announcement-v2.png|3.6 Icon large]]

=Introduction=

The [[Announcments-3.6-Team|community]] of Slicer developers is proud to announce the release of '''Slicer 3.6'''.

*Click here to [http://www.slicer.org/pages/Downloads download] different versions of Slicer3 and find pointers to the source code, mailing lists and bug tracker. *Please note that Slicer continues to be a research package and is not intended for clinical use. Testing of functionality is an ongoing activity with high priority, however, some features of Slicer3 are not fully tested.
*The [[Training|Slicer Training page]] provides a series of courses for learning how to use Slicer3. The portfolio contains self-guided presentation and sample data sets

The main [http://www.slicer.org slicer.org] pages provide a guided tour to the application, training materials, and the development community. New users should start there because we try to keep the pages organized and up to date.

=Slicer Highlights=
<gallery caption="Slicer v3.6 - New and Improved Modules" widths="250px" heights="150px" perrow="3">
Image:Slicer3.6-Editor-2010-05-06.png|The [[Modules:Editor-Documentation-3.6|Interactive Editor]] can be used to create and edit label maps for quantitative analysis and surface model generation (Steve Pieper)
Image:VolumeRenderingICPE.png| [[Modules:VolumeRendering-Documentation-3.6|Volume Rendering]] (Yanling Liu, Julien Finet, Lisa Avila)
Image:Slicer-ColorGUI-3.6.jpg| [[Modules:Colors-Documentation-3.6|Colors]] (Nicole Aucoin)
Image:Slicer3.6MeasurementsRulersModel.jpg| [[Modules:Measurements-Documentation-3.6 |Measurements (rulers and angles)]] (Nicole Aucoin)
Image:SlicerFiducialsGlyphs-3.4.jpg| [[Modules:Fiducials-Documentation-3.6|Fiducials]] (Nicole Aucoin)
Image:EMSegment-Simple.png|[[Modules:EMSegment-Simple3.6|EM Segmenter, simple version]] (Kilian Pohl)
Image:Fastmarching-result-adjusted.jpg| [[Modules:FastMarchingSegmentation-Documentation-3.6|Fast Marching segmentation]] (Andriy Fedorov)
Image:RSSkidneyL.png| [[Modules:RobustStatisticsSeg-Documentation-3.6|Robust Statistical Segmentation]] (Yi Gao)
Image:Fiducial registration before.jpg|NEW: [[Modules:RegisterImagesMultiRes-Documentation-3.6|Multiresolution Affine registration]] (Casey Goodlett)
Image:B-spline-reg-detail.png|Improved: [[Modules:RegisterImages-Documentation-3.6|Expert Automated Registration]] (Casey Goodlett)
Image:Fiducial_registration_before.jpg|NEW: [[Modules:TransformFromFiducials-Documentation-3.6|Fiducial Registration]] (Casey Goodlett)
Image:Registration_BRAINSfit.png|NEW: [[Modules:BRAINSFit |BRAINSFit Registration]] (Hans Johnson)
Image:Registration_BRAINSdemonwarp.png|NEW: [[Modules:BRAINSDemonWarp|BRAINSDemonWarp]] (Hans Johnson)
Image:BRAINSResample.png|NEW: [[Modules:BRAINSResample|BRAINSResample]] (Hans J. Johnson)
Image:BRAINSROIAuto.png|NEW: [[Modules:BRAINSROIAuto|BRAINSROIAuto]] (Hans J. Johnson)
Image:Plastimatch_icon.png|NEW: [[Modules:Plastimatch |Plastimatch non-rigid registration]] (Greg Sharp)
Image:PETCTFusion.png| [[Modules:PETCTFusion-Documentation-3.6 |PETCTFusion]] (Wendy Plesniak)
Image:| [[Modules:CollectFiducials-Documentation-3.6 |Collect Patient Fiducials]] (Andrew Wiles)
Image:| [[Modules:IGTToolSelector-Documentation-3.6 |IGT Tool Selector]] (Andrew Wiles)
Image:FourDImage Screenshot1.png| [[Modules:FourDImage-Documentation-3.6|4D Image Viewer]] (Junichi Tokuda)
Image:MRI_Bias_Field_Correction_Slicer3_close_up.png|[[Modules:MRIBiasFieldCorrection-Documentation-3.6|MRIBiasFieldCorrection]] correction of MRI intensity inhomogeneity i.e. bias field (Sylvain Jaume)
Image:N4 prostate bias ax.png| [[Modules:N4ITKBiasFieldCorrection-Documentation-3.6|N4 Bias Field Correction]] (Andriy Fedorov)
Image:Surface H c.png| [[Modules:MeshContourSegmentation-Documentation-3.6|Mesh Contour Segmentation]] (Peter Karasev)
Image:ModelTransform.PNG| [[Modules:ModelTransform-Documentation-3.6|Model Transform]] (Alex Yarmarkovich)
Image:BrainWebImageTransformed.jpg| [[Modules:ResampleScalarVectorDWIVolume-Documentation-3.6|Resample Scalar/Vector/DWI Volume]] (Francois Budin)
Image:ExtractSubvolume3.png| [[Modules:CropVolume-Documentation-3.6|Crop Volume]] (Andriy Fedorov)
Image:Endoscopy-slicer3.6.png| [[Modules:Endoscopy-Documentation-3.6|Virtual Endoscopy]] (Steve Pieper)
Image:ChangeTracker_Analysis-3.4.png| [[Modules:ChangeTracker-Documentation-3.6|ChangeTracker]] (Andriy Fedorov)
Image:Slicer3_OpenIGTLinkIF__VolumeReslice2.png| [[Modules:OpenIGTLinkIF-Documentation-3.6|OpenIGTLinkIF]] (Junichi Tokuda)
Image:ProstateNav-3.6_Transrectal.png| [[Modules:ProstateNav-Documentation-3.6|ProstateNav]] (Andras Lasso, Junichi Tokuda)
Image:slicer3.6_neuronav_OR.jpeg| [[Modules:NeuroNav-Documentation-3.6|NeuroNav]] (Haiying Liu)

</gallery>

=Slicer Extensions=
<gallery caption="Slicer v3.6 - Extensions" widths="250px" heights="150px" perrow="3">
Image:Plastimatch_dicomrt_dose.png|The [[Modules:PlastimatchDICOMRT| Plastimatch DICOM RT reader]] allows import and conversion of data in that format. (Greg Sharp)
Image:ABC out3d.png|The [[Modules:ABC-Documentation-3.5|ABC Segmenter]] is based on ITK EM technology.
Image:FCMResultLabels-3-6.png|[[Modules:FuzzySegmentationModule|Fuzzy segmentation]]
Image:HammerAverage-3-6.png|[[Modules:HammerRegistration|Hammer Registration]] can be used to build statistical brain atlases
Image:Plastimatch image 2.png|[[Modules:Plastimatch|Plastimatch non-rigid registration]] (Greg Sharp)
Image:Corticalthickness.png|[[Modules:ARCTIC-Documentation-3.6|Arctic wizard]] (Automatic Regional Cortical ThICkness)
Image:LesionsWithVentricles.png|[[Modules:LesionSegmentationApplications-Documentation-3.6| Lupus white matter lesions segmentation]] (Jeremy Bockholt, Mark Scully)
Image:Shot2.png|[[Modules:EMDTIClustering-Documentation-3.6|EM DTI clustering]] (Mahnaz Maddah)
Image:RicianTensorCorrectionImage.png|[[Modules:RicianNoiseFilter|Rician Noise Filter]] for noise removal in DWI data
Image:FourDAnalysisModuleScreenShot-3.5.png|The [[Modules:FourDAnalysis-Documentation-3.6|FourD Analysis module]] was designed for time series analysis (Junichi Takuda)
Image:Avf 3d voronoi big.png|[[Modules:VMTKCenterlines|Centerline extraction using Voronoi diagrams]] (Luca Antiga, Daniel Haehn)
Image:Labeldiameterestimation1.png|[[Modules:LabelDiameterEstimation-Documentation-3.6|Label diameter estimation]] (Andriy Fedorov)
</gallery>

Checklist for the [[Checklist-3.6-Release|3.6 release]]

= Other Improvements, Additions & Documentation =
[[Image:RegPortal_Icon.png|100px|Registration Portal|link=Slicer3:Registration]] [[Slicer3:Registration|Registration Portal Page: overview of avail. tools & modules]] (Dominik Meier) 
[[Image:Registration DecisionMatrix.png| 100px | link=Registration:Categories]] [[Registration:Categories|Registration Tool Feature Matrix]] (Dominik Meier) 
[[Image:Resampling_DecisionMatrix.png| 100px | link=Registration:Resampling]] [[Registration:Resampling|Resampling Tool Feature Matrix]] (Dominik Meier) 
[[Image:RegLib_Banner.png| 100px |link=http://na-mic.org/Wiki/index.php/Projects:RegistrationDocumentation:UseCaseInventory]] [http://na-mic.org/Wiki/index.php/Projects:RegistrationDocumentation:UseCaseInventory| Slicer Registration Case Library] (Dominik Meier) 
[[Image:SlicerRegistrationLibrary_Ad.png| 100px | link=http://na-mic.org/Wiki/index.php/Projects:RegistrationDocumentation:UseCaseAdvertisement]] [http://na-mic.org/Wiki/index.php/Projects:RegistrationDocumentation:UseCaseAdvertisement|Slicer Registration Case Library: Call for Example Datasets] (Dominik Meier) 
* Registration Welcome Module
* Segmentation Welcome Module
* Diffusion Welcome Module
* Performance Improvements in all registration modules due to bug fixes and performance enhancements in new ITK release

File:Registration BRAINSfit.png

2010-06-10T19:45:20Z

Hjmjohnson: uploaded a new version of "File:Registration BRAINSfit.png"

File:BRAINSROIAuto.png

2010-06-10T19:43:50Z

Hjmjohnson:

File:BRAINSRROIAutoUI.png

2010-06-10T19:40:16Z

Hjmjohnson: uploaded a new version of "File:BRAINSRROIAutoUI.png"

File:BRAINSRROIAutoUI.png

2010-06-10T19:39:15Z

Hjmjohnson:

Modules:BRAINSROIAuto

2010-06-10T19:38:37Z

Hjmjohnson: Created page with 'Return to Slicer 3.6 Documentation Gallery of New Features __NOTOC__ ===Module Name=== BRAINSROIAuto {| |[[Image:B…'

[[Documentation-3.6|Return to Slicer 3.6 Documentation]]

[[Announcements:Slicer3.6#Highlights|Gallery of New Features]]

__NOTOC__
===Module Name===
BRAINSROIAuto

{|
|[[Image:BRAINSRROIAutoUI.png|thumb|280px|User Interface]]
|}

== General Information ==
===Module Type & Category===

Type: CLI

Category: Segmentation

===Authors, Collaborators & Contact===

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

Contributors: Hans Johnson(1,3,4); (1=University of Iowa Department of Psychiatry, 3=University of Iowa Department of Biomedical Engineering, 4=University of Iowa Department of Electrical and Computer Engineering)

===Module Description===

{| style="color:green" border="1"

|Program title || BRAINSROIAuto - Foreground masking tool

|-
|Program version || 2.4.1

|-
|Program documentation-url ||
|-
|}

== Usage ==
BRAINSROIAuto finds the foreground tissue region in an image.

* '''''IO''''' 
** '''Input Image Volume''' [--inputVolume] : The input image for finding the largest region filled mask.
** '''Output Mask''' [--outputROIMaskVolume] : The ROI automatically found from the input image.
** '''Output Image Clipped by ROI''' [--outputClippedVolumeROI] : The inputVolume clipped to the region of the brain mask.

* '''''Configuration Parameters''''' 
** '''Otsu Percentile Threshold''' [--otsuPercentileThreshold] : Parameter to the Otsu threshold algorithm. ''Default value: 0.01''
** '''Otsu Correction Factor''' [--thresholdCorrectionFactor] : A factor to scale the Otsu algorithm's result threshold, in case clipping mangles the image. ''Default value: 1.0''
** '''Closing Size''' [--closingSize] : The Closing Size (in millimeters) for largest connected filled mask. This value is divided by image spacing and rounded to the next largest voxel number. ''Default value: 9.0''
** ''' 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''
** '''Output Image Pixel Type''' [--outputVolumePixelType] : The output image Pixel Type is the scalar datatype for representation of the Output Volume. ''Default value: short''

===Tutorials===

===Quick Tour of Features and Use===

== Development ==

===Notes from the Developer(s)===

===Dependencies===
BRAINSROIAuto depends on Slicer3 (for the SlicerExecutionModel support) and ITK.
BRAINSROIAuto depends on BRAINSCommonLib

===Tests===
http://testing.psychiatry.uiowa.edu

===Usability issues===

Follow this [http://na-mic.org/Mantis/main_page.php link] to the Slicer3 bug tracker. Please select the '''usability issue category''' when browsing or contributing.

== More Information ==

===Acknowledgment===
The development of this tool was supported by funding from grants NS050568 and NS40068 from the National Institute of Neurological Disorders and Stroke and grants MH31593, MH40856, from the National Institute of Mental Health.

===References===
Publications related to this module go here. Links to pdfs would be useful.
-->

Announcements:Slicer3.6

2010-06-10T19:26:08Z

Hjmjohnson: /* Slicer Highlights */

[[Documentation-3.6|Back to Documentation 3.6]]
[[image:Slicer3-6Announcement-v2.png|3.6 Icon large]]

=Introduction=

The [[Announcments-3.6-Team|community]] of Slicer developers is proud to announce the release of '''Slicer 3.6'''.

*Click here to [http://www.slicer.org/pages/Downloads download] different versions of Slicer3 and find pointers to the source code, mailing lists and bug tracker. *Please note that Slicer continues to be a research package and is not intended for clinical use. Testing of functionality is an ongoing activity with high priority, however, some features of Slicer3 are not fully tested.
*The [[Training|Slicer Training page]] provides a series of courses for learning how to use Slicer3. The portfolio contains self-guided presentation and sample data sets

The main [http://www.slicer.org slicer.org] pages provide a guided tour to the application, training materials, and the development community. New users should start there because we try to keep the pages organized and up to date.

=Slicer Highlights=
<gallery caption="Slicer v3.6 - New and Improved Modules" widths="250px" heights="150px" perrow="3">
Image:Slicer3.6-Editor-2010-05-06.png|The [[Modules:Editor-Documentation-3.6|Interactive Editor]] can be used to create and edit label maps for quantitative analysis and surface model generation (Steve Pieper)
Image:VolumeRenderingICPE.png| [[Modules:VolumeRendering-Documentation-3.6|Volume Rendering]] (Yanling Liu, Julien Finet, Lisa Avila)
Image:Slicer-ColorGUI-3.6.jpg| [[Modules:Colors-Documentation-3.6|Colors]] (Nicole Aucoin)
Image:Slicer3.6MeasurementsRulersModel.jpg| [[Modules:Measurements-Documentation-3.6 |Measurements (rulers and angles)]] (Nicole Aucoin)
Image:SlicerFiducialsGlyphs-3.4.jpg| [[Modules:Fiducials-Documentation-3.6|Fiducials]] (Nicole Aucoin)
Image:EMSegment-Simple.png|[[Modules:EMSegment-Simple3.6|EM Segmenter, simple version]] (Kilian Pohl)
Image:Fastmarching-result-adjusted.jpg| [[Modules:FastMarchingSegmentation-Documentation-3.6|Fast Marching segmentation]] (Andriy Fedorov)
Image:RSSkidneyL.png| [[Modules:RobustStatisticsSeg-Documentation-3.6|Robust Statistical Segmentation]] (Yi Gao)
Image:Fiducial registration before.jpg|NEW: [[Modules:RegisterImagesMultiRes-Documentation-3.6|Multiresolution Affine registration]] (Casey Goodlett)
Image:B-spline-reg-detail.png|Improved: [[Modules:RegisterImages-Documentation-3.6|Expert Automated Registration]] (Casey Goodlett)
Image:Fiducial_registration_before.jpg|NEW: [[Modules:TransformFromFiducials-Documentation-3.6|Fiducial Registration]] (Casey Goodlett)
Image:Registration_BRAINSfit.png|NEW: [[Modules:BRAINSFit |BRAINSFit Registration]] (Hans Johnson)
Image:Registration_BRAINSdemonwarp.png|NEW: [[Modules:BRAINSDemonWarp|BRAINSDemonWarp]] (Hans Johnson)
Image:BRAINSResample.png| [[Modules:BRAINSResample|BRAINSResample]] (Hans J. Johnson)
Image:BRAINSROIAuto.png| [[Modules:BRAINSROIAuto|BRAINSROIAuto]] (Hans J. Johnson)
Image:Plastimatch_icon.png|NEW: [[Modules:Plastimatch |Plastimatch non-rigid registration]] (Greg Sharp)
Image:PETCTFusion.png| [[Modules:PETCTFusion-Documentation-3.6 |PETCTFusion]] (Wendy Plesniak)
Image:| [[Modules:CollectFiducials-Documentation-3.6 |Collect Patient Fiducials]] (Andrew Wiles)
Image:| [[Modules:IGTToolSelector-Documentation-3.6 |IGT Tool Selector]] (Andrew Wiles)
Image:FourDImage Screenshot1.png| [[Modules:FourDImage-Documentation-3.6|4D Image Viewer]] (Junichi Tokuda)
Image:MRI_Bias_Field_Correction_Slicer3_close_up.png|[[Modules:MRIBiasFieldCorrection-Documentation-3.6|MRIBiasFieldCorrection]] correction of MRI intensity inhomogeneity i.e. bias field (Sylvain Jaume)
Image:N4 prostate bias ax.png| [[Modules:N4ITKBiasFieldCorrection-Documentation-3.6|N4 Bias Field Correction]] (Andriy Fedorov)
Image:Surface H c.png| [[Modules:MeshContourSegmentation-Documentation-3.6|Mesh Contour Segmentation]] (Peter Karasev)
Image:ModelTransform.PNG| [[Modules:ModelTransform-Documentation-3.6|Model Transform]] (Alex Yarmarkovich)
Image:BrainWebImageTransformed.jpg| [[Modules:ResampleScalarVectorDWIVolume-Documentation-3.6|Resample Scalar/Vector/DWI Volume]] (Francois Budin)
Image:ExtractSubvolume3.png| [[Modules:CropVolume-Documentation-3.6|Crop Volume]] (Andriy Fedorov)
Image:Endoscopy-slicer3.6.png| [[Modules:Endoscopy-Documentation-3.6|Virtual Endoscopy]] (Steve Pieper)
Image:ChangeTracker_Analysis-3.4.png| [[Modules:ChangeTracker-Documentation-3.6|ChangeTracker]] (Andriy Fedorov)
Image:Slicer3_OpenIGTLinkIF__VolumeReslice2.png| [[Modules:OpenIGTLinkIF-Documentation-3.6|OpenIGTLinkIF]] (Junichi Tokuda)
Image:ProstateNav-3.6_Transrectal.png| [[Modules:ProstateNav-Documentation-3.6|ProstateNav]] (Andras Lasso, Junichi Tokuda)
Image:slicer3.6_neuronav_OR.jpeg| [[Modules:NeuroNav-Documentation-3.6|NeuroNav]] (Haiying Liu)

</gallery>

=Slicer Extensions=
<gallery caption="Slicer v3.6 - Extensions" widths="250px" heights="150px" perrow="3">
Image:Plastimatch_dicomrt_dose.png|The [[Modules:PlastimatchDICOMRT| Plastimatch DICOM RT reader]] allows import and conversion of data in that format. (Greg Sharp)
Image:ABC out3d.png|The [[Modules:ABC-Documentation-3.5|ABC Segmenter]] is based on ITK EM technology.
Image:FCMResultLabels-3-6.png|[[Modules:FuzzySegmentationModule|Fuzzy segmentation]]
Image:HammerAverage-3-6.png|[[Modules:HammerRegistration|Hammer Registration]] can be used to build statistical brain atlases
Image:Plastimatch image 2.png|[[Modules:Plastimatch|Plastimatch non-rigid registration]] (Greg Sharp)
Image:Corticalthickness.png|[[Modules:ARCTIC-Documentation-3.6|Arctic wizard]] (Automatic Regional Cortical ThICkness)
Image:LesionsWithVentricles.png|[[Modules:LesionSegmentationApplications-Documentation-3.6| Lupus white matter lesions segmentation]] (Jeremy Bockholt, Mark Scully)
Image:Shot2.png|[[Modules:EMDTIClustering-Documentation-3.6|EM DTI clustering]] (Mahnaz Maddah)
Image:RicianTensorCorrectionImage.png|[[Modules:RicianNoiseFilter|Rician Noise Filter]] for noise removal in DWI data
Image:FourDAnalysisModuleScreenShot-3.5.png|The [[Modules:FourDAnalysis-Documentation-3.6|FourD Analysis module]] was designed for time series analysis (Junichi Takuda)
Image:Avf 3d voronoi big.png|[[Modules:VMTKCenterlines|Centerline extraction using Voronoi diagrams]] (Luca Antiga, Daniel Haehn)
Image:Labeldiameterestimation1.png|[[Modules:LabelDiameterEstimation-Documentation-3.6|Label diameter estimation]] (Andriy Fedorov)
</gallery>

Checklist for the [[Checklist-3.6-Release|3.6 release]]

= Other Improvements, Additions & Documentation =
[[Image:RegPortal_Icon.png|100px|Registration Portal|link=Slicer3:Registration]] [[Slicer3:Registration|Registration Portal Page: overview of avail. tools & modules]] (Dominik Meier) 
[[Image:Registration DecisionMatrix.png| 100px | link=Registration:Categories]] [[Registration:Categories|Registration Tool Feature Matrix]] (Dominik Meier) 
[[Image:Resampling_DecisionMatrix.png| 100px | link=Registration:Resampling]] [[Registration:Resampling|Resampling Tool Feature Matrix]] (Dominik Meier) 
[[Image:RegLib_Banner.png| 100px |link=http://na-mic.org/Wiki/index.php/Projects:RegistrationDocumentation:UseCaseInventory]] [http://na-mic.org/Wiki/index.php/Projects:RegistrationDocumentation:UseCaseInventory| Slicer Registration Case Library] (Dominik Meier) 
[[Image:SlicerRegistrationLibrary_Ad.png| 100px | link=http://na-mic.org/Wiki/index.php/Projects:RegistrationDocumentation:UseCaseAdvertisement]] [http://na-mic.org/Wiki/index.php/Projects:RegistrationDocumentation:UseCaseAdvertisement|Slicer Registration Case Library: Call for Example Datasets] (Dominik Meier) 
* Registration Welcome Module
* Segmentation Welcome Module
* Diffusion Welcome Module
* Performance Improvements in all registration modules due to bug fixes and performance enhancements in new ITK release

Slicer Wiki:Users

2010-06-10T19:21:42Z

Hjmjohnson: Created page with 'Need to add.'

Need to add.

Announcements:Slicer3.6

2010-06-10T14:31:35Z

Hjmjohnson: /* Highlights */

[[Documentation-3.6|Back to Documentation 3.6]]
[[image:Slicer3-6Announcement-v2.png|3.6 Icon large]]

=Introduction=

The [[Announcments-3.6-Team|community]] of Slicer developers is proud to announce the release of '''Slicer 3.6'''.

*Click here to [http://www.slicer.org/pages/Downloads download] different versions of Slicer3 and find pointers to the source code, mailing lists and bug tracker. *Please note that Slicer continues to be a research package and is not intended for clinical use. Testing of functionality is an ongoing activity with high priority, however, some features of Slicer3 are not fully tested.
*The [[Training|Slicer Training page]] provides a series of courses for learning how to use Slicer3. The portfolio contains self-guided presentation and sample data sets

The main [http://www.slicer.org slicer.org] pages provide a guided tour to the application, training materials, and the development community. New users should start there because we try to keep the pages organized and up to date.

==Highlights==
<gallery caption="Slicer v3.6 - New and Improved Modules" widths="250px" heights="150px" perrow="3">
Image:Slicer3.6-Editor-2010-05-06.png|The [[Modules:Editor-Documentation-3.6|Interactive Editor]] can be used to create and edit label maps for quantitative analysis and surface model generation (Steve Pieper)
Image:VolumeRenderingICPE.png| [[Modules:VolumeRendering-Documentation-3.6|Volume Rendering]] (Yanling Liu, Julien Finet, Lisa Avila)
Image:Slicer-ColorGUI-3.6.jpg| [[Modules:Colors-Documentation-3.6|Colors]] (Nicole Aucoin)
Image:Slicer3.6MeasurementsRulersModel.jpg| [[Modules:Measurements-Documentation-3.6 |Measurements (rulers and angles)]] (Nicole Aucoin)
Image:SlicerFiducialsGlyphs-3.4.jpg| [[Modules:Fiducials-Documentation-3.6|Fiducials]] (Nicole Aucoin)
Image:EMSegment-Simple.png|[[Modules:EMSegment-Simple3.6|EM Segmenter, simple version]] (Kilian Pohl)
Image:Fastmarching-result-adjusted.jpg| [[Modules:FastMarchingSegmentation-Documentation-3.6|Fast Marching segmentation]] (Andriy Fedorov)
Image:RSSkidneyL.png| [[Modules:RobustStatisticsSeg-Documentation-3.6|Robust Statistical Segmentation]] (Yi Gao)
Image:Fiducial registration before.jpg|NEW: [[Modules:RegisterImagesMultiRes-Documentation-3.6|Multiresolution Affine registration]] (Casey Goodlett)
Image:B-spline-reg-detail.png|Improved: [[Modules:RegisterImages-Documentation-3.6|Expert Automated Registration]] (Casey Goodlett)
Image:Fiducial_registration_before.jpg|NEW: [[Modules:TransformFromFiducials-Documentation-3.6|Fiducial Registration]] (Casey Goodlett)
Image:Registration_BRAINSfit.png|NEW: [[Modules:BRAINSFit |BRAINSFit Registration]] (Hans Johnson)
Image:Registration_BRAINSdemonwarp.png|NEW: [[Modules:BRAINSDemonWarp|BRAINSDemonWarp]] (Hans Johnson)
Image:Plastimatch_icon.png|NEW: [[Modules:Plastimatch |Plastimatch non-rigid registration]] (Greg Sharp)
Image:PETCTFusion.png| [[Modules:PETCTFusion-Documentation-3.6 |PETCTFusion]] (Wendy Plesniak)
Image:| [[Modules:CollectFiducials-Documentation-3.6 |Collect Patient Fiducials]] (Andrew Wiles)
Image:| [[Modules:IGTToolSelector-Documentation-3.6 |IGT Tool Selector]] (Andrew Wiles)
Image:FourDImage Screenshot1.png| [[Modules:FourDImage-Documentation-3.6|4D Image Viewer]] (Junichi Tokuda)
Image:MRI_Bias_Field_Correction_Slicer3_close_up.png|[[Modules:MRIBiasFieldCorrection-Documentation-3.6|MRIBiasFieldCorrection]] correction of MRI intensity inhomogeneity i.e. bias field (Sylvain Jaume)
Image:N4 prostate bias ax.png| [[Modules:N4ITKBiasFieldCorrection-Documentation-3.6|N4 Bias Field Correction]] (Andriy Fedorov)
Image:Surface H c.png| [[Modules:MeshContourSegmentation-Documentation-3.6|Mesh Contour Segmentation]] (Peter Karasev)
Image:ModelTransform.PNG| [[Modules:ModelTransform-Documentation-3.6|Model Transform]] (Alex Yarmarkovich)
Image:BrainWebImageTransformed.jpg| [[Modules:ResampleScalarVectorDWIVolume-Documentation-3.6|Resample Scalar/Vector/DWI Volume]] (Francois Budin)
Image:ExtractSubvolume3.png| [[Modules:CropVolume-Documentation-3.6|Crop Volume]] (Andriy Fedorov)
Image:Endoscopy-slicer3.6.png| [[Modules:Endoscopy-Documentation-3.6|Virtual Endoscopy]] (Steve Pieper)
Image:ChangeTracker_Analysis-3.4.png| [[Modules:ChangeTracker-Documentation-3.6|ChangeTracker]] (Andriy Fedorov)
Image:BRAINSFit.png| [[Modules:BRAINSFit|BRAINSFit]] (Hans J. Johnson)
Image:BRAINSDemonWarp.png| [[Modules:BRAINSDemonWarp|BRAINSDemonWarp]] (Hans J. Johnson)
Image:BRAINSResample.png| [[Modules:BRAINSResample|BRAINSResample]] (Hans J. Johnson)
Image:BRAINSROIAuto.png| [[Modules:BRAINSROIAuto|BRAINSROIAuto]] (Hans J. Johnson)

</gallery>

==Slicer Extensions==
<gallery caption="Slicer v3.6 - Extensions" widths="250px" heights="150px" perrow="3">
Image:Plastimatch_dicomrt_dose.png|The [[Modules:PlastimatchDICOMRT| Plastimatch DICOM RT reader]] allows import and conversion of data in that format. (Greg Sharp)
Image:ABC out3d.png|The [[Modules:ABC-Documentation-3.5|ABC Segmenter]] is based on ITK EM technology.
Image:FCMResultLabels-3-6.png|[[Modules:FuzzySegmentationModule|Fuzzy segmentation]]
Image:HammerAverage-3-6.png|[[Modules:HammerRegistration|Hammer Registration]] can be used to build statistical brain atlases
Image:Plastimatch image 2.png|[[Modules:Plastimatch|Plastimatch non-rigid registration]] (Greg Sharp)
Image:Corticalthickness.png|[[Modules:ARCTIC-Documentation-3.6|Arctic wizard]] (Automatic Regional Cortical ThICkness)
Image:LesionsWithVentricles.png|[[Modules:LesionSegmentationApplications-Documentation-3.6| Lupus white matter lesions segmentation]] (Jeremy Bockholt, Mark Scully)
Image:Shot2.png|[[Modules:EMDTIClustering-Documentation-3.6|EM DTI clustering]] (Mahnaz Maddah)
Image:RicianTensorCorrectionImage.png|[[Modules:RicianNoiseFilter|Rician Noise Filter]] for noise removal in DWI data
Image:FourDAnalysisModuleScreenShot-3.5.png|The [[Modules:FourDAnalysis-Documentation-3.6|FourD Analysis module]] was designed for time series analysis (Junichi Takuda)
Image:Avf 3d voronoi big.png|[[Modules:VMTKCenterlines|Centerline extraction using Voronoi diagrams]] (Luca Antiga, Daniel Haehn)
Image:Labeldiameterestimation1.png|[[Modules:LabelDiameterEstimation-Documentation-3.6|Label diameter estimation]] (Andriy Fedorov)
</gallery>

Checklist for the [[Checklist-3.6-Release|3.6 release]]

Modules:BRAINSFit

2010-06-09T01:23:56Z

Hjmjohnson: /* Quick Tour of Features and Use */

[[Documentation-3.6|Return to Slicer 3.6 Documentation]]

[[Announcements:Slicer3.6#Highlights|Gallery of New Features]]

__NOTOC__
===Module Name===
BRAINSFit

{|
| [[Image:Before.png|thumb|280px|Before registration]]
|-
| [[Image:After.png|thumb|280px|AfterRegistration]]
|}

== General Information ==
===Module Type & Category===

Type: CLI

Category: Registration

===Authors, Collaborators & Contact===

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

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

===Module Description===

{| style="color:green" border="1"
|Program title || BRAINSFit

|-
|Program version || 3.0.0

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

|-
|}

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

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

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

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

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

===Quick Tour of Features and Use===

This section was partially generated with a [[SEMToMediaWiki.py| 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''''' 
** '''Initialize with previously generated transform''' [--initialTransform] : Filename of transform used to initialize the registration. This CAN NOT be used with either CenterOfHeadLAlign, MomentsAlign, GeometryAlign, or initialTransform file.
** '''Initialize with MomentsAlign registration phase''' [--useMomentsAlign] : MomentsAlign assumes that the center of mass of the images represent similar structures. Perform a MomentsAlign registration as part of the sequential registration steps. This option MUST come first, and CAN NOT be used with either CenterOfHeadLAlign, GeometryAlign, or initialTransform file. This family of options superceeds the use of transformType if any of them are set. ''Default value: false''
** '''Initialize with GeometryCenterAlign registration phase''' [--useGeometryAlign] : GeometryAlign on assumes that the center of the voxel lattice of the images represent similar structures. Perform a GeometryCenterAlign registration as part of the sequential registration steps. This option MUST come first, and CAN NOT be used with either MomentsAlign, CenterOfHeadAlign, or initialTransform file. This family of options superceeds the use of transformType if any of them are set. ''Default value: false''
** '''Initialize with CenterOfHeadAlign registration phase''' [--useCenterOfHeadAlign] : CenterOfHeadAlign attempts to find a hemisphere full of foreground voxels from the superior direction as an estimate of where the center of a head shape would be to drive a center of mass estimate. Perform a CenterOfHeadAlign registration as part of the sequential registration steps. This option MUST come first, and CAN NOT be used with either MomentsAlign, GeometryAlign, or initialTransform file. This family of options superceeds the use of transformType if any of them are set. ''Default value: false''
** '''Include Rigid registration phase''' [--useRigid] : Perform a rigid registration as part of the sequential registration steps. This family of options superceeds the use of transformType if any of them are set. ''Default value: false''
** '''Include ScaleVersor3D registration phase''' [--useScaleVersor3D] : Perform a ScaleVersor3D registration as part of the sequential registration steps. This family of options superceeds the use of transformType if any of them are set. ''Default value: false''
** '''Include ScaleSkewVersor3D registration phase''' [--useScaleSkewVersor3D] : Perform a rigid registration as part of the sequential registration steps. This family of options superceeds the use of transformType if any of them are set. ''Default value: false''
** '''Include Affine registration phase''' [--useAffine] : Perform a rigid registration as part of the sequential registration steps. This family of options superceeds the use of transformType if any of them are set. ''Default value: false''
** '''Include BSpline registration phase''' [--useBSpline] : Perform a rigid registration as part of the sequential registration steps. This family of options superceeds the use of transformType if any of them are set. ''Default value: false''

* '''''Output Settings (At least one output must be specified.)''''' 
** '''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.
** '''Number Of Iterations''' [--numberOfIterations] : The maximum number of iterations to try before failing to converge. Use an explicit limit like 500 or 1000 to manage risk of divergence ''Default value: 1500''
** '''Number Of Samples''' [--numberOfSamples] : The number of voxels sampled for mutual information computation. Increase this for a slower, more careful fit. You can also limit the sampling focus with ROI masks and ROIAUTO mask generation. ''Default value: 100000''
** '''Minimum Step Size''' [--minimumStepSize] : Each step in the optimization takes steps at least this big. When none are possible, registration is complete. ''Default value: 0.005''
** '''Transform Scale''' [--translationScale] : How much to scale up changes in position compared to unit rotational changes in radians -- decrease this to put more rotation in the search pattern. ''Default value: 1000.0''
** '''Reproportion Scale''' [--reproportionScale] : ScaleVersor3D 'Scale' compensation factor. Increase this to put more rescaling in a ScaleVersor3D or ScaleSkewVersor3D search pattern. 1.0 works well with a translationScale of 1000.0 ''Default value: 1.0''
** '''Skew Scale''' [--skewScale] : ScaleSkewVersor3D Skew compensation factor. Increase this to put more skew in a ScaleSkewVersor3D search pattern. 1.0 works well with a translationScale of 1000.0 ''Default value: 1.0''
** '''Number Of Grid Subdivisions''' [--splineGridSize] : The number of subdivisions of the BSpline Grid to be centered on the image space. Each dimension must have at least 3 subdivisions for the BSpline to be correctly computed. ''Default value: 14,10,12''
** '''Maximum B-Spline Displacement''' [--maxBSplineDisplacement] : Sets the maximum allowed displacements in image physical coordinates for BSpline control grid along each axis. A value of 0.0 indicates that the problem should be unbounded. NOTE: This only constrains the BSpline portion, and does not limit the displacement from the associated bulk transform. This can lead to a substantial reduction in computation time in the BSpline optimizer. ''Default value: 0.0''

* '''''Advanced Output Settings''''' 
** '''Stripped Output Transform''' [--strippedOutputTransform] : File name for the rigid component of the estimated affine transform. Can be used to rigidly register the moving image to the fixed image. NOTE: This value is overwritten if either bsplineTransform or linearTransform is set.
** '''Background Fill Value''' [--backgroundFillValue] : Background fill value for output image. ''Default value: 0.0''
** '''Inferior Cut Off From Center''' [--maskInferiorCutOffFromCenter] : For use with --useCenterOfHeadAlign (and --maskProcessingMode ROIAUTO): the cut-off below the image centers, in millimeters, ''Default value: 1000.0''
** '''Scale Output Values''' [--scaleOutputValues] : If true, and the voxel values do not fit within the minimum and maximum values of the desired outputVolumePixelType, then linearly scale the min/max output image voxel values to fit within the min/max range of the outputVolumePixelType. ''Default value: false''
** '''Interpolation Mode''' [--interpolationMode] : Type of interpolation to be used when applying transform to moving volume. Options are Linear, NearestNeighbor, BSpline, or WindowedSinc ''Default value: Linear''

* '''''Control of Mask Processing''''' 
** '''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. ''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''
** '''Relaxation Factor''' [--relaxationFactor] : Internal debugging parameter, and should probably never be used from the command line. This will be removed in the future. ''Default value: 0.5''
** '''Maximum Step Size''' [--maximumStepSize] : Internal debugging parameter, and should probably never be used from the command line. This will be removed in the future. ''Default value: 0.2''
** '''Failure Exit Code''' [--failureExitCode] : If the fit fails, exit with this status code. (It can be used to force a successfult exit status of (0) if the registration fails due to reaching the maximum number of iterations. ''Default value: -1''
** '''Write Transform On Failure''' [--writeTransformOnFailure] : Flag to save the final transform even if the numberOfIterations are reached without convergence. (Intended for use when --failureExitCode 0 ) ''Default value: 0''
** '''debugNumberOfThreads''' [--debugNumberOfThreads] : Explicitly specify the maximum number of threads to use. ''Default value: -1''
** '''Debug option''' [--debugLevel] : Display debug messages, and produce debug intermediate results. 0=OFF, 1=Minimal, 10=Maximum debugging. ''Default value: 0''

* '''''Risky Expert-only Parameters''''' 
** '''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.

||[[Image:BRAINSFitUI_part1.png|thumb|280px|User Interface]] [[Image:BRAINSFitUI_part2.png|thumb|280px|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:
<pre>

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");
}

</pre>

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

===Tests===

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

===Known bugs===

Links to known bugs and feature requests are listed at:
* http://www.nitrc.org/projects/multimodereg/

===Usability issues===

Follow this [http://na-mic.org/Mantis/main_page.php 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:
*[http://www.nitrc.org/projects/multimodereg/|Hosted by NITRC ]

== More Information ==

===Acknowledgment===

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

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

Modules:BRAINSFit

2010-06-07T14:39:09Z

Hjmjohnson: /* Quick Tour of Features and Use */

[[Documentation-3.6|Return to Slicer 3.6 Documentation]]

[[Announcements:Slicer3.6#Highlights|Gallery of New Features]]

__NOTOC__
===Module Name===
BRAINSFit

{|
| [[Image:Before.png|thumb|280px|Before registration]]
|-
| [[Image:After.png|thumb|280px|AfterRegistration]]
|}

== General Information ==
===Module Type & Category===

Type: CLI

Category: Registration

===Authors, Collaborators & Contact===

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

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

===Module Description===

{| style="color:green" border="1"
|Program title || BRAINSFit

|-
|Program version || 3.0.0

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

|-
|}

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

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

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

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

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

===Quick Tour of Features and Use===

This section was partially generated with a [[SEMToMediaWiki.py| python script to convert Slicer Execution Model xml files into MediaWiki compatible documentation]]

{|
|
* '''''Input Parameters''''' The fixed image for registration by mutual information optimization.
** '''Fixed Image Volume''' [--fixedVolume] : The fixed image for registration by mutual information optimization.
** '''Moving Image Volume''' [--movingVolume] : The moving image for registration by mutual information optimization.
* '''''Registration phases to use''''' Filename of transform used to initialize the registration. This CAN NOT be used with either CenterOfHeadLAlign, MomentsAlign, GeometryAlign, or initialTransform file.
** '''Initialize with previously generated transform''' [--initialTransform] : Filename of transform used to initialize the registration. This CAN NOT be used with either CenterOfHeadLAlign, MomentsAlign, GeometryAlign, or initialTransform file.
** '''Initialize with MomentsAlign registration phase''' [--useMomentsAlign] : MomentsAlign assumes that the center of mass of the images represent similar structures. Perform a MomentsAlign registration as part of the sequential registration steps. This option MUST come first, and CAN NOT be used with either CenterOfHeadLAlign, GeometryAlign, or initialTransform file. This family of options superceeds the use of transformType if any of them are set.
** '''Initialize with GeometryCenterAlign registration phase''' [--useGeometryAlign] : GeometryAlign on assumes that the center of the voxel lattice of the images represent similar structures. Perform a GeometryCenterAlign registration as part of the sequential registration steps. This option MUST come first, and CAN NOT be used with either MomentsAlign, CenterOfHeadAlign, or initialTransform file. This family of options superceeds the use of transformType if any of them are set.
** '''Initialize with CenterOfHeadAlign registration phase''' [--useCenterOfHeadAlign] : CenterOfHeadAlign attempts to find a hemisphere full of foreground voxels from the superior direction as an estimate of where the center of a head shape would be to drive a center of mass estimate. Perform a CenterOfHeadAlign registration as part of the sequential registration steps. This option MUST come first, and CAN NOT be used with either MomentsAlign, GeometryAlign, or initialTransform file. This family of options superceeds the use of transformType if any of them are set.
** '''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.
** '''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.
** '''Include ScaleSkewVersor3D registration phase''' [--useScaleSkewVersor3D] : Perform a rigid registration as part of the sequential registration steps. This family of options superceeds the use of transformType if any of them are set.
** '''Include Affine registration phase''' [--useAffine] : Perform a rigid registration as part of the sequential registration steps. This family of options superceeds the use of transformType if any of them are set.
** '''Include BSpline registration phase''' [--useBSpline] : Perform a rigid registration as part of the sequential registration steps. This family of options superceeds the use of transformType if any of them are set.
* '''''Output Settings (At least one output must be specified.)''''' (optional) Filename to which save the estimated transform. NOTE: You must set at least one output object (either a deformed image or a transform. NOTE: USE THIS ONLY IF THE FINAL TRANSFORM IS BSpline
** '''Slicer BSpline Transform''' [--bsplineTransform] : (optional) Filename to which save the estimated transform. NOTE: You must set at least one output object (either a deformed image or a transform. NOTE: USE THIS ONLY IF THE FINAL TRANSFORM IS BSpline
** '''Slicer Linear Transform''' [--linearTransform] : (optional) Filename to which save the estimated transform. NOTE: You must set at least one output object (either a deformed image or a transform. NOTE: USE THIS ONLY IF THE FINAL TRANSFORM IS ---NOT--- BSpline
** '''Output Transform''' [--outputTransform] : (optional) Filename to which save the (optional) estimated transform. NOTE: You must select either the outputTransform or the outputVolume option.
** '''Output Image Volume''' [--outputVolume] : (optional) Output image for registration. NOTE: You must select either the outputTransform or the outputVolume option.
** '''Output Image Pixel Type''' [--outputVolumePixelType] : The output image Pixel Type is the scalar datatype for representation of the Output Volume.
* '''''Registration Parameters''''' Specifies a list of registration types to be used. The valid types are, Rigid, ScaleVersor3D, ScaleSkewVersor3D, Affine, and BSpline. Specifiying more than one in a comma separated list will initialize the next stage with the previous results. If registrationClass flag is used, it overrides this parameter setting.
** '''Transform Type''' [--transformType] : Specifies a list of registration types to be used. The valid types are, Rigid, ScaleVersor3D, ScaleSkewVersor3D, Affine, and BSpline. Specifiying more than one in a comma separated list will initialize the next stage with the previous results. If registrationClass flag is used, it overrides this parameter setting.
** '''Number Of Iterations''' [--numberOfIterations] : The maximum number of iterations to try before failing to converge. Use an explicit limit like 500 or 1000 to manage risk of divergence
** '''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.
** '''Minimum Step Size''' [--minimumStepSize] : Each step in the optimization takes steps at least this big. When none are possible, registration is complete.
** '''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.
** '''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
** '''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
** '''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.
** '''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.

* '''''Advanced Output Settings''''' File name for the rigid component of the estimated affine transform. Can be used to rigidly register the moving image to the fixed image. NOTE: This value is overwritten if either bsplineTransform or linearTransform is set.
** '''Stripped Output Transform''' [--strippedOutputTransform] : File name for the rigid component of the estimated affine transform. Can be used to rigidly register the moving image to the fixed image. NOTE: This value is overwritten if either bsplineTransform or linearTransform is set.
** '''Background Fill Value''' [--backgroundFillValue] : Background fill value for output image.
** '''Inferior Cut Off From Center''' [--maskInferiorCutOffFromCenter] : For use with --useCenterOfHeadAlign (and --maskProcessingMode ROIAUTO): the cut-off below the image centers, in millimeters,
** '''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, or WindowedSinc
* '''''Control of Mask Processing''''' What mode to use for using the masks. If ROIAUTO is choosen, then the mask is implicitly defined using a otsu forground and hole filling algorithm. The Region Of Interest mode (choose ROI) uses the masks to define what parts of the image should be used for computing the transform.
** '''Mask Processing Mode''' [--maskProcessingMode] : What mode to use for using the masks. If ROIAUTO is choosen, then the mask is implicitly defined using a otsu forground and hole filling algorithm. The Region Of Interest mode (choose ROI) uses the masks to define what parts of the image should be used for computing the transform.
** '''Output Fixed Mask (ROIAUTO only)''' [--outputFixedVolumeROI] : The ROI automatically found in fixed image.
** '''Output Moving Mask (ROIAUTO only)''' [--outputMovingVolumeROI] : The ROI automatically found in moving image.
** '''Input Fixed Mask (ROI only)''' [--fixedBinaryVolume] : Fixed Image binary mask volume.
** '''Input Moving Mask (ROI only)''' [--movingBinaryVolume] : Moving Image binary mask volume.
* '''''Special Input Image Parameters''''' The index in the time series for the 3D fixed image to fit, if 4-dimensional.
** '''Fixed Image Time Index''' [--fixedVolumeTimeIndex] : The index in the time series for the 3D fixed image to fit, if 4-dimensional.
** '''Moving Image Time Index''' [--movingVolumeTimeIndex] : The index in the time series for the 3D moving image to fit, if 4-dimensional.
** '''Median Filter Size''' [--medianFilterSize] : The radius for the optional MedianImageFilter preprocessing in all 3 directions.
** '''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.
** '''Number of Histogram Bins''' [--numberOfHistogramBins] : the number of histogram levels
** '''Number of Match Points''' [--numberOfMatchPoints] : the number of match points
* '''''Registration Debugging Parameters''''' This is a 5x speed advantage at the expense of requiring much more memory. Only relevant when transformType is BSpline.
** '''Caching BSpline Weights Mode''' [--useCachingOfBSplineWeightsMode] : This is a 5x speed advantage at the expense of requiring much more memory. Only relevant when transformType is BSpline.
** '''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.
** ''' 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.
** '''Relaxation Factor''' [--relaxationFactor] : Internal debugging parameter, and should probably never be used from the command line. This will be removed in the future.
** '''Maximum Step Size''' [--maximumStepSize] : Internal debugging parameter, and should probably never be used from the command line. This will be removed in the future.
** '''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 )
** '''debugNumberOfThreads''' [--debugNumberOfThreads] : Explicitly specify the maximum number of threads to use.
** '''Debug option''' [--debugLevel] : Display debug messages, and produce debug intermediate results. 0=OFF, 1=Minimal, 10=Maximum debugging.
* '''''Risky Expert-only Parameters''''' A bit vector to permit linear transform parameters to vary under optimization. The vector order corresponds with transform parameters, and beyond the end ones fill in as a default. For instance, you can choose to rotate only in x (pitch) with 1,0,0; this is mostly for expert use in turning on and off individual degrees of freedom in rotation, translation or scaling without multiplying the number of transform representations; this trick is probably meaningless when tried with the general affine transform.
** '''Selective Permission for Transform Parameters to Vary''' [--permitParameterVariation] : A bit vector to permit linear transform parameters to vary under optimization. The vector order corresponds with transform parameters, and beyond the end ones fill in as a default. For instance, you can choose to rotate only in x (pitch) with 1,0,0; this is mostly for expert use in turning on and off individual degrees of freedom in rotation, translation or scaling without multiplying the number of transform representations; this trick is probably meaningless when tried with the general affine transform.

||[[Image:BRAINSFitUI_part1.png|thumb|280px|User Interface]] [[Image:BRAINSFitUI_part2.png|thumb|280px|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:
<pre>

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");
}

</pre>

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

===Tests===

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

===Known bugs===

Links to known bugs and feature requests are listed at:
* http://www.nitrc.org/projects/multimodereg/

===Usability issues===

Follow this [http://na-mic.org/Mantis/main_page.php 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:
*[http://www.nitrc.org/projects/multimodereg/|Hosted by NITRC ]

== More Information ==

===Acknowledgment===

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

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

SEMToMediaWiki.py

2010-06-07T14:12:19Z

Hjmjohnson: Created page with '<pre> #!python # \author Hans J. Johnson # # \description This python script is to help convert from # SEM xml documentation to a form suitable for posting on # a MediaWiki form…'

<pre>

#!python
# \author Hans J. Johnson
#
# \description This python script is to help convert from
# SEM xml documentation to a form suitable for posting on
# a MediaWiki format
#
# \usage python SEMToMediaWiki.py myProgramSEM.xml > MediaWikiFormattedText.txt
#
import sys
import pprint

import xml.dom.minidom
from xml.dom.minidom import Node

# Get this nodes text information.
def getTextValuesFromNode(nodelist):
rc = []
for node in nodelist:
if node.nodeType == node.TEXT_NODE:
rc.append(node.data)
return ''.join(rc)

# Create a formatted text string suitable for inclusion in a MediaWiki table
def getThisNodesInfoAsTextTableLine(executableNode,label):
labelNodeList=executableNode.getElementsByTagName(label)
if labelNodeList.length > 0 :
labelNode=labelNodeList[0] ## Only get the first one
print "|Program %s || %s\n" % (label,getTextValuesFromNode(labelNode.childNodes) )
print "|-"

# Only get the text info for the matching label at this level of the tree
def getThisNodesInfoAsText(executableNode,label):
labelNodeList=executableNode.getElementsByTagName(label)
if labelNodeList.length > 0 :
labelNode=labelNodeList[0] ## Only get the first one
return getTextValuesFromNode(labelNode.childNodes);
return ""

# Extract the long flag, and color the text string
def getLongFlagDefinition(executableNode):
labelNodeList=executableNode.getElementsByTagName("longflag")
if labelNodeList.length > 0 :
labelNode=labelNodeList[0] ## Only get the first one
return "[--"+getTextValuesFromNode(labelNode.childNodes)+"]";
return "";

# Extract the (short) flag, and color the text string
def getFlagDefinition(executableNode):
labelNodeList=executableNode.getElementsByTagName("flag")
if labelNodeList.length > 0 :
labelNode=labelNodeList[0] ## Only get the first one
return "[-"+getTextValuesFromNode(labelNode.childNodes)+"]";
return "";

# Extract the nodes label, and color the text string
def getLabelDefinition(executableNode):
labelNodeList=executableNode.getElementsByTagName("label")
if labelNodeList.length > 0 :
labelNode=labelNodeList[0] ## Only get the first one
return "** '''"+getTextValuesFromNode(labelNode.childNodes)+"'''";
return "";

## Read the xml file from the first argument of command line
doc = xml.dom.minidom.parse(sys.argv[1]);

# Get the primary heirarchial tree node.
executableNode=doc.getElementsByTagName("executable")[0]

# Print information about the program in general
print "===Module Type & Category===\n"
print "Type: CLI\n"
print "Category: %s\n" % getThisNodesInfoAsText(executableNode,"category")
print "\n"

print "===Authors, Collaborators & Contact===\n"
print "Author: %s\n" % getThisNodesInfoAsText(executableNode,"contributor")
print "Contributors: %s\n" % getThisNodesInfoAsText(executableNode,"acknowledgements")
print "\n"

print "===Module Description===\n"
print "{| style=\"color:green\" border=\"1\"\n"
getThisNodesInfoAsTextTableLine(executableNode,"title")
getThisNodesInfoAsTextTableLine(executableNode,"descripition")
getThisNodesInfoAsTextTableLine(executableNode,"version")
getThisNodesInfoAsTextTableLine(executableNode,"documentation-url")
getThisNodesInfoAsTextTableLine(executableNode,"doesnotexiststest")
print "|}\n"

# Now print all the command line arguments and the labels that showup in the GUI interface
for parameterNode in executableNode.getElementsByTagName("parameters"):
print "* '''''%s''''' %s" % (getThisNodesInfoAsText(parameterNode,"label"),getThisNodesInfoAsText(parameterNode,"description"))
currentNode = parameterNode.firstChild
while currentNode is not None :
if currentNode.nodeType == currentNode.ELEMENT_NODE:
if getThisNodesInfoAsText(currentNode,"label") != "": #If this node doe not have a "label" element, then just skip it.
print "%s %s %s: %s" % (getLabelDefinition(currentNode), getLongFlagDefinition(currentNode),getFlagDefinition(currentNode),getThisNodesInfoAsText(currentNode,"description"))
currentNode=currentNode.nextSibling

</pre>

Modules:BRAINSFit

2010-06-07T14:11:31Z

Hjmjohnson: /* Quick Tour of Features and Use */

[[Documentation-3.6|Return to Slicer 3.6 Documentation]]

[[Announcements:Slicer3.6#Highlights|Gallery of New Features]]

__NOTOC__
===Module Name===
BRAINSFit

{|
| [[Image:Before.png|thumb|280px|Before registration]]
|-
| [[Image:After.png|thumb|280px|AfterRegistration]]
|}

== General Information ==
===Module Type & Category===

Type: CLI

Category: Registration

===Authors, Collaborators & Contact===

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

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

===Module Description===

{| style="color:green" border="1"
|Program title || BRAINSFit

|-
|Program version || 3.0.0

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

|-
|}

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

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

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

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

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

===Quick Tour of Features and Use===

This section was partially generated with a [[SEMToMediaWiki.py| python script to convert Slicer Execution Model xml files into MediaWiki compatible documentation]]

{|
|
* '''''Input Parameters''''' The fixed image for registration by mutual information optimization.
** '''Fixed Image Volume''' [--fixedVolume] : The fixed image for registration by mutual information optimization.
** '''Moving Image Volume''' [--movingVolume] : The moving image for registration by mutual information optimization.
* '''''Registration phases to use''''' Filename of transform used to initialize the registration. This CAN NOT be used with either CenterOfHeadLAlign, MomentsAlign, GeometryAlign, or initialTransform file.
** '''Initialize with previously generated transform''' [--initialTransform] : Filename of transform used to initialize the registration. This CAN NOT be used with either CenterOfHeadLAlign, MomentsAlign, GeometryAlign, or initialTransform file.
** '''Initialize with MomentsAlign registration phase''' [--useMomentsAlign] : MomentsAlign assumes that the center of mass of the images represent similar structures. Perform a MomentsAlign registration as part of the sequential registration steps. This option MUST come first, and CAN NOT be used with either CenterOfHeadLAlign, GeometryAlign, or initialTransform file. This family of options superceeds the use of transformType if any of them are set.
** '''Initialize with GeometryCenterAlign registration phase''' [--useGeometryAlign] : GeometryAlign on assumes that the center of the voxel lattice of the images represent similar structures. Perform a GeometryCenterAlign registration as part of the sequential registration steps. This option MUST come first, and CAN NOT be used with either MomentsAlign, CenterOfHeadAlign, or initialTransform file. This family of options superceeds the use of transformType if any of them are set.
** '''Initialize with CenterOfHeadAlign registration phase''' [--useCenterOfHeadAlign] : CenterOfHeadAlign attempts to find a hemisphere full of foreground voxels from the superior direction as an estimate of where the center of a head shape would be to drive a center of mass estimate. Perform a CenterOfHeadAlign registration as part of the sequential registration steps. This option MUST come first, and CAN NOT be used with either MomentsAlign, GeometryAlign, or initialTransform file. This family of options superceeds the use of transformType if any of them are set.
** '''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.
** '''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.
** '''Include ScaleSkewVersor3D registration phase''' [--useScaleSkewVersor3D] : Perform a rigid registration as part of the sequential registration steps. This family of options superceeds the use of transformType if any of them are set.
** '''Include Affine registration phase''' [--useAffine] : Perform a rigid registration as part of the sequential registration steps. This family of options superceeds the use of transformType if any of them are set.
** '''Include BSpline registration phase''' [--useBSpline] : Perform a rigid registration as part of the sequential registration steps. This family of options superceeds the use of transformType if any of them are set.
* '''''Output Settings (At least one output must be specified.)''''' (optional) Filename to which save the estimated transform. NOTE: You must set at least one output object (either a deformed image or a transform. NOTE: USE THIS ONLY IF THE FINAL TRANSFORM IS BSpline
** '''Slicer BSpline Transform''' [--bsplineTransform] : (optional) Filename to which save the estimated transform. NOTE: You must set at least one output object (either a deformed image or a transform. NOTE: USE THIS ONLY IF THE FINAL TRANSFORM IS BSpline
** '''Slicer Linear Transform''' [--linearTransform] : (optional) Filename to which save the estimated transform. NOTE: You must set at least one output object (either a deformed image or a transform. NOTE: USE THIS ONLY IF THE FINAL TRANSFORM IS ---NOT--- BSpline
** '''Output Transform''' [--outputTransform] : (optional) Filename to which save the (optional) estimated transform. NOTE: You must select either the outputTransform or the outputVolume option.
** '''Output Image Volume''' [--outputVolume] : (optional) Output image for registration. NOTE: You must select either the outputTransform or the outputVolume option.
** '''Output Image Pixel Type''' [--outputVolumePixelType] : The output image Pixel Type is the scalar datatype for representation of the Output Volume.
* '''''Registration Parameters''''' Specifies a list of registration types to be used. The valid types are, Rigid, ScaleVersor3D, ScaleSkewVersor3D, Affine, and BSpline. Specifiying more than one in a comma separated list will initialize the next stage with the previous results. If registrationClass flag is used, it overrides this parameter setting.
** '''Transform Type''' [--transformType] : Specifies a list of registration types to be used. The valid types are, Rigid, ScaleVersor3D, ScaleSkewVersor3D, Affine, and BSpline. Specifiying more than one in a comma separated list will initialize the next stage with the previous results. If registrationClass flag is used, it overrides this parameter setting.
** '''Number Of Iterations''' [--numberOfIterations] : The maximum number of iterations to try before failing to converge. Use an explicit limit like 500 or 1000 to manage risk of divergence
** '''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.
** '''Minimum Step Size''' [--minimumStepSize] : Each step in the optimization takes steps at least this big. When none are possible, registration is complete.
** '''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.
** '''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
** '''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
** '''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.
** '''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.

* '''''Advanced Output Settings''''' File name for the rigid component of the estimated affine transform. Can be used to rigidly register the moving image to the fixed image. NOTE: This value is overwritten if either bsplineTransform or linearTransform is set.
** '''Stripped Output Transform''' [--strippedOutputTransform] : File name for the rigid component of the estimated affine transform. Can be used to rigidly register the moving image to the fixed image. NOTE: This value is overwritten if either bsplineTransform or linearTransform is set.
** '''Background Fill Value''' [--backgroundFillValue] : Background fill value for output image.
** '''Inferior Cut Off From Center''' [--maskInferiorCutOffFromCenter] : For use with --useCenterOfHeadAlign (and --maskProcessingMode ROIAUTO): the cut-off below the image centers, in millimeters,
** '''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, or WindowedSinc
* '''''Control of Mask Processing''''' What mode to use for using the masks. If ROIAUTO is choosen, then the mask is implicitly defined using a otsu forground and hole filling algorithm. The Region Of Interest mode (choose ROI) uses the masks to define what parts of the image should be used for computing the transform.
** '''Mask Processing Mode''' [--maskProcessingMode] : What mode to use for using the masks. If ROIAUTO is choosen, then the mask is implicitly defined using a otsu forground and hole filling algorithm. The Region Of Interest mode (choose ROI) uses the masks to define what parts of the image should be used for computing the transform.
** '''Output Fixed Mask (ROIAUTO only)''' [--outputFixedVolumeROI] : The ROI automatically found in fixed image.
** '''Output Moving Mask (ROIAUTO only)''' [--outputMovingVolumeROI] : The ROI automatically found in moving image.
** '''Input Fixed Mask (ROI only)''' [--fixedBinaryVolume] : Fixed Image binary mask volume.
** '''Input Moving Mask (ROI only)''' [--movingBinaryVolume] : Moving Image binary mask volume.
* '''''Special Input Image Parameters''''' The index in the time series for the 3D fixed image to fit, if 4-dimensional.
** '''Fixed Image Time Index''' [--fixedVolumeTimeIndex] : The index in the time series for the 3D fixed image to fit, if 4-dimensional.
** '''Moving Image Time Index''' [--movingVolumeTimeIndex] : The index in the time series for the 3D moving image to fit, if 4-dimensional.
** '''Median Filter Size''' [--medianFilterSize] : The radius for the optional MedianImageFilter preprocessing in all 3 directions.
** '''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.
** '''Number of Histogram Bins''' [--numberOfHistogramBins] : the number of histogram levels
** '''Number of Match Points''' [--numberOfMatchPoints] : the number of match points
* '''''Registration Debugging Parameters''''' This is a 5x speed advantage at the expense of requiring much more memory. Only relevant when transformType is BSpline.
** '''Caching BSpline Weights Mode''' [--useCachingOfBSplineWeightsMode] : This is a 5x speed advantage at the expense of requiring much more memory. Only relevant when transformType is BSpline.
** '''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.
** ''' 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.
** '''Relaxation Factor''' [--relaxationFactor] : Internal debugging parameter, and should probably never be used from the command line. This will be removed in the future.
** '''Maximum Step Size''' [--maximumStepSize] : Internal debugging parameter, and should probably never be used from the command line. This will be removed in the future.
** '''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 )
** '''debugNumberOfThreads''' [--debugNumberOfThreads] : Explicitly specify the maximum number of threads to use.
** '''Debug option''' [--debugLevel] : Display debug messages, and produce debug intermediate results. 0=OFF, 1=Minimal, 10=Maximum debugging.
* '''''Risky Expert-only Parameters''''' A bit vector to permit linear transform parameters to vary under optimization. The vector order corresponds with transform parameters, and beyond the end ones fill in as a default. For instance, you can choose to rotate only in x (pitch) with 1,0,0; this is mostly for expert use in turning on and off individual degrees of freedom in rotation, translation or scaling without multiplying the number of transform representations; this trick is probably meaningless when tried with the general affine transform.
** '''Selective Permission for Transform Parameters to Vary''' [--permitParameterVariation] : A bit vector to permit linear transform parameters to vary under optimization. The vector order corresponds with transform parameters, and beyond the end ones fill in as a default. For instance, you can choose to rotate only in x (pitch) with 1,0,0; this is mostly for expert use in turning on and off individual degrees of freedom in rotation, translation or scaling without multiplying the number of transform representations; this trick is probably meaningless when tried with the general affine transform.
** '''Fixed Image Origin''' [--fixedVolumeOrigin] : The coordinates of the origin of the fixed image. This will over-ride the information read from disk and is VERY DANGEROUS.
** '''Moving Image Origin''' [--movingVolumeOrigin] : The coordinates of the origin of the moving image. This will over-ride the information read from disk and is VERY DANGEROUS.

||[[Image:BRAINSFitUI_part1.png|thumb|280px|User Interface]] [[Image:BRAINSFitUI_part2.png|thumb|280px|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:
<pre>

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");
}

</pre>

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

===Tests===

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

===Known bugs===

Links to known bugs and feature requests are listed at:
* http://www.nitrc.org/projects/multimodereg/

===Usability issues===

Follow this [http://na-mic.org/Mantis/main_page.php 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:
*[http://www.nitrc.org/projects/multimodereg/|Hosted by NITRC ]

== More Information ==

===Acknowledgment===

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

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

Modules:BRAINSFit

2010-06-07T14:10:50Z

Hjmjohnson: /* Quick Tour of Features and Use */

[[Documentation-3.6|Return to Slicer 3.6 Documentation]]

[[Announcements:Slicer3.6#Highlights|Gallery of New Features]]

__NOTOC__
===Module Name===
BRAINSFit

{|
| [[Image:Before.png|thumb|280px|Before registration]]
|-
| [[Image:After.png|thumb|280px|AfterRegistration]]
|}

== General Information ==
===Module Type & Category===

Type: CLI

Category: Registration

===Authors, Collaborators & Contact===

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

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

===Module Description===

{| style="color:green" border="1"
|Program title || BRAINSFit

|-
|Program version || 3.0.0

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

|-
|}

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

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

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

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

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

===Quick Tour of Features and Use===

This section was partially generated with a [[Media:SEMToMediaWiki.py| python script to convert Slicer Execution Model xml files into MediaWiki compatible documentation]]

{|
|
* '''''Input Parameters''''' The fixed image for registration by mutual information optimization.
** '''Fixed Image Volume''' [--fixedVolume] : The fixed image for registration by mutual information optimization.
** '''Moving Image Volume''' [--movingVolume] : The moving image for registration by mutual information optimization.
* '''''Registration phases to use''''' Filename of transform used to initialize the registration. This CAN NOT be used with either CenterOfHeadLAlign, MomentsAlign, GeometryAlign, or initialTransform file.
** '''Initialize with previously generated transform''' [--initialTransform] : Filename of transform used to initialize the registration. This CAN NOT be used with either CenterOfHeadLAlign, MomentsAlign, GeometryAlign, or initialTransform file.
** '''Initialize with MomentsAlign registration phase''' [--useMomentsAlign] : MomentsAlign assumes that the center of mass of the images represent similar structures. Perform a MomentsAlign registration as part of the sequential registration steps. This option MUST come first, and CAN NOT be used with either CenterOfHeadLAlign, GeometryAlign, or initialTransform file. This family of options superceeds the use of transformType if any of them are set.
** '''Initialize with GeometryCenterAlign registration phase''' [--useGeometryAlign] : GeometryAlign on assumes that the center of the voxel lattice of the images represent similar structures. Perform a GeometryCenterAlign registration as part of the sequential registration steps. This option MUST come first, and CAN NOT be used with either MomentsAlign, CenterOfHeadAlign, or initialTransform file. This family of options superceeds the use of transformType if any of them are set.
** '''Initialize with CenterOfHeadAlign registration phase''' [--useCenterOfHeadAlign] : CenterOfHeadAlign attempts to find a hemisphere full of foreground voxels from the superior direction as an estimate of where the center of a head shape would be to drive a center of mass estimate. Perform a CenterOfHeadAlign registration as part of the sequential registration steps. This option MUST come first, and CAN NOT be used with either MomentsAlign, GeometryAlign, or initialTransform file. This family of options superceeds the use of transformType if any of them are set.
** '''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.
** '''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.
** '''Include ScaleSkewVersor3D registration phase''' [--useScaleSkewVersor3D] : Perform a rigid registration as part of the sequential registration steps. This family of options superceeds the use of transformType if any of them are set.
** '''Include Affine registration phase''' [--useAffine] : Perform a rigid registration as part of the sequential registration steps. This family of options superceeds the use of transformType if any of them are set.
** '''Include BSpline registration phase''' [--useBSpline] : Perform a rigid registration as part of the sequential registration steps. This family of options superceeds the use of transformType if any of them are set.
* '''''Output Settings (At least one output must be specified.)''''' (optional) Filename to which save the estimated transform. NOTE: You must set at least one output object (either a deformed image or a transform. NOTE: USE THIS ONLY IF THE FINAL TRANSFORM IS BSpline
** '''Slicer BSpline Transform''' [--bsplineTransform] : (optional) Filename to which save the estimated transform. NOTE: You must set at least one output object (either a deformed image or a transform. NOTE: USE THIS ONLY IF THE FINAL TRANSFORM IS BSpline
** '''Slicer Linear Transform''' [--linearTransform] : (optional) Filename to which save the estimated transform. NOTE: You must set at least one output object (either a deformed image or a transform. NOTE: USE THIS ONLY IF THE FINAL TRANSFORM IS ---NOT--- BSpline
** '''Output Transform''' [--outputTransform] : (optional) Filename to which save the (optional) estimated transform. NOTE: You must select either the outputTransform or the outputVolume option.
** '''Output Image Volume''' [--outputVolume] : (optional) Output image for registration. NOTE: You must select either the outputTransform or the outputVolume option.
** '''Output Image Pixel Type''' [--outputVolumePixelType] : The output image Pixel Type is the scalar datatype for representation of the Output Volume.
* '''''Registration Parameters''''' Specifies a list of registration types to be used. The valid types are, Rigid, ScaleVersor3D, ScaleSkewVersor3D, Affine, and BSpline. Specifiying more than one in a comma separated list will initialize the next stage with the previous results. If registrationClass flag is used, it overrides this parameter setting.
** '''Transform Type''' [--transformType] : Specifies a list of registration types to be used. The valid types are, Rigid, ScaleVersor3D, ScaleSkewVersor3D, Affine, and BSpline. Specifiying more than one in a comma separated list will initialize the next stage with the previous results. If registrationClass flag is used, it overrides this parameter setting.
** '''Number Of Iterations''' [--numberOfIterations] : The maximum number of iterations to try before failing to converge. Use an explicit limit like 500 or 1000 to manage risk of divergence
** '''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.
** '''Minimum Step Size''' [--minimumStepSize] : Each step in the optimization takes steps at least this big. When none are possible, registration is complete.
** '''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.
** '''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
** '''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
** '''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.
** '''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.

* '''''Advanced Output Settings''''' File name for the rigid component of the estimated affine transform. Can be used to rigidly register the moving image to the fixed image. NOTE: This value is overwritten if either bsplineTransform or linearTransform is set.
** '''Stripped Output Transform''' [--strippedOutputTransform] : File name for the rigid component of the estimated affine transform. Can be used to rigidly register the moving image to the fixed image. NOTE: This value is overwritten if either bsplineTransform or linearTransform is set.
** '''Background Fill Value''' [--backgroundFillValue] : Background fill value for output image.
** '''Inferior Cut Off From Center''' [--maskInferiorCutOffFromCenter] : For use with --useCenterOfHeadAlign (and --maskProcessingMode ROIAUTO): the cut-off below the image centers, in millimeters,
** '''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, or WindowedSinc
* '''''Control of Mask Processing''''' What mode to use for using the masks. If ROIAUTO is choosen, then the mask is implicitly defined using a otsu forground and hole filling algorithm. The Region Of Interest mode (choose ROI) uses the masks to define what parts of the image should be used for computing the transform.
** '''Mask Processing Mode''' [--maskProcessingMode] : What mode to use for using the masks. If ROIAUTO is choosen, then the mask is implicitly defined using a otsu forground and hole filling algorithm. The Region Of Interest mode (choose ROI) uses the masks to define what parts of the image should be used for computing the transform.
** '''Output Fixed Mask (ROIAUTO only)''' [--outputFixedVolumeROI] : The ROI automatically found in fixed image.
** '''Output Moving Mask (ROIAUTO only)''' [--outputMovingVolumeROI] : The ROI automatically found in moving image.
** '''Input Fixed Mask (ROI only)''' [--fixedBinaryVolume] : Fixed Image binary mask volume.
** '''Input Moving Mask (ROI only)''' [--movingBinaryVolume] : Moving Image binary mask volume.
* '''''Special Input Image Parameters''''' The index in the time series for the 3D fixed image to fit, if 4-dimensional.
** '''Fixed Image Time Index''' [--fixedVolumeTimeIndex] : The index in the time series for the 3D fixed image to fit, if 4-dimensional.
** '''Moving Image Time Index''' [--movingVolumeTimeIndex] : The index in the time series for the 3D moving image to fit, if 4-dimensional.
** '''Median Filter Size''' [--medianFilterSize] : The radius for the optional MedianImageFilter preprocessing in all 3 directions.
** '''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.
** '''Number of Histogram Bins''' [--numberOfHistogramBins] : the number of histogram levels
** '''Number of Match Points''' [--numberOfMatchPoints] : the number of match points
* '''''Registration Debugging Parameters''''' This is a 5x speed advantage at the expense of requiring much more memory. Only relevant when transformType is BSpline.
** '''Caching BSpline Weights Mode''' [--useCachingOfBSplineWeightsMode] : This is a 5x speed advantage at the expense of requiring much more memory. Only relevant when transformType is BSpline.
** '''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.
** ''' 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.
** '''Relaxation Factor''' [--relaxationFactor] : Internal debugging parameter, and should probably never be used from the command line. This will be removed in the future.
** '''Maximum Step Size''' [--maximumStepSize] : Internal debugging parameter, and should probably never be used from the command line. This will be removed in the future.
** '''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 )
** '''debugNumberOfThreads''' [--debugNumberOfThreads] : Explicitly specify the maximum number of threads to use.
** '''Debug option''' [--debugLevel] : Display debug messages, and produce debug intermediate results. 0=OFF, 1=Minimal, 10=Maximum debugging.
* '''''Risky Expert-only Parameters''''' A bit vector to permit linear transform parameters to vary under optimization. The vector order corresponds with transform parameters, and beyond the end ones fill in as a default. For instance, you can choose to rotate only in x (pitch) with 1,0,0; this is mostly for expert use in turning on and off individual degrees of freedom in rotation, translation or scaling without multiplying the number of transform representations; this trick is probably meaningless when tried with the general affine transform.
** '''Selective Permission for Transform Parameters to Vary''' [--permitParameterVariation] : A bit vector to permit linear transform parameters to vary under optimization. The vector order corresponds with transform parameters, and beyond the end ones fill in as a default. For instance, you can choose to rotate only in x (pitch) with 1,0,0; this is mostly for expert use in turning on and off individual degrees of freedom in rotation, translation or scaling without multiplying the number of transform representations; this trick is probably meaningless when tried with the general affine transform.
** '''Fixed Image Origin''' [--fixedVolumeOrigin] : The coordinates of the origin of the fixed image. This will over-ride the information read from disk and is VERY DANGEROUS.
** '''Moving Image Origin''' [--movingVolumeOrigin] : The coordinates of the origin of the moving image. This will over-ride the information read from disk and is VERY DANGEROUS.

||[[Image:BRAINSFitUI_part1.png|thumb|280px|User Interface]] [[Image:BRAINSFitUI_part2.png|thumb|280px|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:
<pre>

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");
}

</pre>

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

===Tests===

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

===Known bugs===

Links to known bugs and feature requests are listed at:
* http://www.nitrc.org/projects/multimodereg/

===Usability issues===

Follow this [http://na-mic.org/Mantis/main_page.php 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:
*[http://www.nitrc.org/projects/multimodereg/|Hosted by NITRC ]

== More Information ==

===Acknowledgment===

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

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

Modules:BRAINSFit

2010-06-07T14:10:20Z

Hjmjohnson: /* Quick Tour of Features and Use */

[[Documentation-3.6|Return to Slicer 3.6 Documentation]]

[[Announcements:Slicer3.6#Highlights|Gallery of New Features]]

__NOTOC__
===Module Name===
BRAINSFit

{|
| [[Image:Before.png|thumb|280px|Before registration]]
|-
| [[Image:After.png|thumb|280px|AfterRegistration]]
|}

== General Information ==
===Module Type & Category===

Type: CLI

Category: Registration

===Authors, Collaborators & Contact===

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

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

===Module Description===

{| style="color:green" border="1"
|Program title || BRAINSFit

|-
|Program version || 3.0.0

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

|-
|}

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

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

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

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

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

===Quick Tour of Features and Use===

This section was partially generated with a [[File:SEMToMediaWiki.py| python script to convert Slicer Execution Model xml files into MediaWiki compatible documentation]]

{|
|
* '''''Input Parameters''''' The fixed image for registration by mutual information optimization.
** '''Fixed Image Volume''' [--fixedVolume] : The fixed image for registration by mutual information optimization.
** '''Moving Image Volume''' [--movingVolume] : The moving image for registration by mutual information optimization.
* '''''Registration phases to use''''' Filename of transform used to initialize the registration. This CAN NOT be used with either CenterOfHeadLAlign, MomentsAlign, GeometryAlign, or initialTransform file.
** '''Initialize with previously generated transform''' [--initialTransform] : Filename of transform used to initialize the registration. This CAN NOT be used with either CenterOfHeadLAlign, MomentsAlign, GeometryAlign, or initialTransform file.
** '''Initialize with MomentsAlign registration phase''' [--useMomentsAlign] : MomentsAlign assumes that the center of mass of the images represent similar structures. Perform a MomentsAlign registration as part of the sequential registration steps. This option MUST come first, and CAN NOT be used with either CenterOfHeadLAlign, GeometryAlign, or initialTransform file. This family of options superceeds the use of transformType if any of them are set.
** '''Initialize with GeometryCenterAlign registration phase''' [--useGeometryAlign] : GeometryAlign on assumes that the center of the voxel lattice of the images represent similar structures. Perform a GeometryCenterAlign registration as part of the sequential registration steps. This option MUST come first, and CAN NOT be used with either MomentsAlign, CenterOfHeadAlign, or initialTransform file. This family of options superceeds the use of transformType if any of them are set.
** '''Initialize with CenterOfHeadAlign registration phase''' [--useCenterOfHeadAlign] : CenterOfHeadAlign attempts to find a hemisphere full of foreground voxels from the superior direction as an estimate of where the center of a head shape would be to drive a center of mass estimate. Perform a CenterOfHeadAlign registration as part of the sequential registration steps. This option MUST come first, and CAN NOT be used with either MomentsAlign, GeometryAlign, or initialTransform file. This family of options superceeds the use of transformType if any of them are set.
** '''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.
** '''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.
** '''Include ScaleSkewVersor3D registration phase''' [--useScaleSkewVersor3D] : Perform a rigid registration as part of the sequential registration steps. This family of options superceeds the use of transformType if any of them are set.
** '''Include Affine registration phase''' [--useAffine] : Perform a rigid registration as part of the sequential registration steps. This family of options superceeds the use of transformType if any of them are set.
** '''Include BSpline registration phase''' [--useBSpline] : Perform a rigid registration as part of the sequential registration steps. This family of options superceeds the use of transformType if any of them are set.
* '''''Output Settings (At least one output must be specified.)''''' (optional) Filename to which save the estimated transform. NOTE: You must set at least one output object (either a deformed image or a transform. NOTE: USE THIS ONLY IF THE FINAL TRANSFORM IS BSpline
** '''Slicer BSpline Transform''' [--bsplineTransform] : (optional) Filename to which save the estimated transform. NOTE: You must set at least one output object (either a deformed image or a transform. NOTE: USE THIS ONLY IF THE FINAL TRANSFORM IS BSpline
** '''Slicer Linear Transform''' [--linearTransform] : (optional) Filename to which save the estimated transform. NOTE: You must set at least one output object (either a deformed image or a transform. NOTE: USE THIS ONLY IF THE FINAL TRANSFORM IS ---NOT--- BSpline
** '''Output Transform''' [--outputTransform] : (optional) Filename to which save the (optional) estimated transform. NOTE: You must select either the outputTransform or the outputVolume option.
** '''Output Image Volume''' [--outputVolume] : (optional) Output image for registration. NOTE: You must select either the outputTransform or the outputVolume option.
** '''Output Image Pixel Type''' [--outputVolumePixelType] : The output image Pixel Type is the scalar datatype for representation of the Output Volume.
* '''''Registration Parameters''''' Specifies a list of registration types to be used. The valid types are, Rigid, ScaleVersor3D, ScaleSkewVersor3D, Affine, and BSpline. Specifiying more than one in a comma separated list will initialize the next stage with the previous results. If registrationClass flag is used, it overrides this parameter setting.
** '''Transform Type''' [--transformType] : Specifies a list of registration types to be used. The valid types are, Rigid, ScaleVersor3D, ScaleSkewVersor3D, Affine, and BSpline. Specifiying more than one in a comma separated list will initialize the next stage with the previous results. If registrationClass flag is used, it overrides this parameter setting.
** '''Number Of Iterations''' [--numberOfIterations] : The maximum number of iterations to try before failing to converge. Use an explicit limit like 500 or 1000 to manage risk of divergence
** '''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.
** '''Minimum Step Size''' [--minimumStepSize] : Each step in the optimization takes steps at least this big. When none are possible, registration is complete.
** '''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.
** '''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
** '''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
** '''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.
** '''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.

* '''''Advanced Output Settings''''' File name for the rigid component of the estimated affine transform. Can be used to rigidly register the moving image to the fixed image. NOTE: This value is overwritten if either bsplineTransform or linearTransform is set.
** '''Stripped Output Transform''' [--strippedOutputTransform] : File name for the rigid component of the estimated affine transform. Can be used to rigidly register the moving image to the fixed image. NOTE: This value is overwritten if either bsplineTransform or linearTransform is set.
** '''Background Fill Value''' [--backgroundFillValue] : Background fill value for output image.
** '''Inferior Cut Off From Center''' [--maskInferiorCutOffFromCenter] : For use with --useCenterOfHeadAlign (and --maskProcessingMode ROIAUTO): the cut-off below the image centers, in millimeters,
** '''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, or WindowedSinc
* '''''Control of Mask Processing''''' What mode to use for using the masks. If ROIAUTO is choosen, then the mask is implicitly defined using a otsu forground and hole filling algorithm. The Region Of Interest mode (choose ROI) uses the masks to define what parts of the image should be used for computing the transform.
** '''Mask Processing Mode''' [--maskProcessingMode] : What mode to use for using the masks. If ROIAUTO is choosen, then the mask is implicitly defined using a otsu forground and hole filling algorithm. The Region Of Interest mode (choose ROI) uses the masks to define what parts of the image should be used for computing the transform.
** '''Output Fixed Mask (ROIAUTO only)''' [--outputFixedVolumeROI] : The ROI automatically found in fixed image.
** '''Output Moving Mask (ROIAUTO only)''' [--outputMovingVolumeROI] : The ROI automatically found in moving image.
** '''Input Fixed Mask (ROI only)''' [--fixedBinaryVolume] : Fixed Image binary mask volume.
** '''Input Moving Mask (ROI only)''' [--movingBinaryVolume] : Moving Image binary mask volume.
* '''''Special Input Image Parameters''''' The index in the time series for the 3D fixed image to fit, if 4-dimensional.
** '''Fixed Image Time Index''' [--fixedVolumeTimeIndex] : The index in the time series for the 3D fixed image to fit, if 4-dimensional.
** '''Moving Image Time Index''' [--movingVolumeTimeIndex] : The index in the time series for the 3D moving image to fit, if 4-dimensional.
** '''Median Filter Size''' [--medianFilterSize] : The radius for the optional MedianImageFilter preprocessing in all 3 directions.
** '''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.
** '''Number of Histogram Bins''' [--numberOfHistogramBins] : the number of histogram levels
** '''Number of Match Points''' [--numberOfMatchPoints] : the number of match points
* '''''Registration Debugging Parameters''''' This is a 5x speed advantage at the expense of requiring much more memory. Only relevant when transformType is BSpline.
** '''Caching BSpline Weights Mode''' [--useCachingOfBSplineWeightsMode] : This is a 5x speed advantage at the expense of requiring much more memory. Only relevant when transformType is BSpline.
** '''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.
** ''' 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.
** '''Relaxation Factor''' [--relaxationFactor] : Internal debugging parameter, and should probably never be used from the command line. This will be removed in the future.
** '''Maximum Step Size''' [--maximumStepSize] : Internal debugging parameter, and should probably never be used from the command line. This will be removed in the future.
** '''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 )
** '''debugNumberOfThreads''' [--debugNumberOfThreads] : Explicitly specify the maximum number of threads to use.
** '''Debug option''' [--debugLevel] : Display debug messages, and produce debug intermediate results. 0=OFF, 1=Minimal, 10=Maximum debugging.
* '''''Risky Expert-only Parameters''''' A bit vector to permit linear transform parameters to vary under optimization. The vector order corresponds with transform parameters, and beyond the end ones fill in as a default. For instance, you can choose to rotate only in x (pitch) with 1,0,0; this is mostly for expert use in turning on and off individual degrees of freedom in rotation, translation or scaling without multiplying the number of transform representations; this trick is probably meaningless when tried with the general affine transform.
** '''Selective Permission for Transform Parameters to Vary''' [--permitParameterVariation] : A bit vector to permit linear transform parameters to vary under optimization. The vector order corresponds with transform parameters, and beyond the end ones fill in as a default. For instance, you can choose to rotate only in x (pitch) with 1,0,0; this is mostly for expert use in turning on and off individual degrees of freedom in rotation, translation or scaling without multiplying the number of transform representations; this trick is probably meaningless when tried with the general affine transform.
** '''Fixed Image Origin''' [--fixedVolumeOrigin] : The coordinates of the origin of the fixed image. This will over-ride the information read from disk and is VERY DANGEROUS.
** '''Moving Image Origin''' [--movingVolumeOrigin] : The coordinates of the origin of the moving image. This will over-ride the information read from disk and is VERY DANGEROUS.

||[[Image:BRAINSFitUI_part1.png|thumb|280px|User Interface]] [[Image:BRAINSFitUI_part2.png|thumb|280px|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:
<pre>

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");
}

</pre>

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

===Tests===

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

===Known bugs===

Links to known bugs and feature requests are listed at:
* http://www.nitrc.org/projects/multimodereg/

===Usability issues===

Follow this [http://na-mic.org/Mantis/main_page.php 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:
*[http://www.nitrc.org/projects/multimodereg/|Hosted by NITRC ]

== More Information ==

===Acknowledgment===

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

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

Modules:BRAINSFit

2010-06-07T14:08:17Z

Hjmjohnson: /* Quick Tour of Features and Use */

[[Documentation-3.6|Return to Slicer 3.6 Documentation]]

[[Announcements:Slicer3.6#Highlights|Gallery of New Features]]

__NOTOC__
===Module Name===
BRAINSFit

{|
| [[Image:Before.png|thumb|280px|Before registration]]
|-
| [[Image:After.png|thumb|280px|AfterRegistration]]
|}

== General Information ==
===Module Type & Category===

Type: CLI

Category: Registration

===Authors, Collaborators & Contact===

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

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

===Module Description===

{| style="color:green" border="1"
|Program title || BRAINSFit

|-
|Program version || 3.0.0

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

|-
|}

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

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

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

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

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

===Quick Tour of Features and Use===

This section was partially generated with a [[SEMToMediaWiki.py| python script to convert Slicer Execution Model xml files into MediaWiki compatible documentation]]

{|
|
* '''''Input Parameters''''' The fixed image for registration by mutual information optimization.
** '''Fixed Image Volume''' [--fixedVolume] : The fixed image for registration by mutual information optimization.
** '''Moving Image Volume''' [--movingVolume] : The moving image for registration by mutual information optimization.
* '''''Registration phases to use''''' Filename of transform used to initialize the registration. This CAN NOT be used with either CenterOfHeadLAlign, MomentsAlign, GeometryAlign, or initialTransform file.
** '''Initialize with previously generated transform''' [--initialTransform] : Filename of transform used to initialize the registration. This CAN NOT be used with either CenterOfHeadLAlign, MomentsAlign, GeometryAlign, or initialTransform file.
** '''Initialize with MomentsAlign registration phase''' [--useMomentsAlign] : MomentsAlign assumes that the center of mass of the images represent similar structures. Perform a MomentsAlign registration as part of the sequential registration steps. This option MUST come first, and CAN NOT be used with either CenterOfHeadLAlign, GeometryAlign, or initialTransform file. This family of options superceeds the use of transformType if any of them are set.
** '''Initialize with GeometryCenterAlign registration phase''' [--useGeometryAlign] : GeometryAlign on assumes that the center of the voxel lattice of the images represent similar structures. Perform a GeometryCenterAlign registration as part of the sequential registration steps. This option MUST come first, and CAN NOT be used with either MomentsAlign, CenterOfHeadAlign, or initialTransform file. This family of options superceeds the use of transformType if any of them are set.
** '''Initialize with CenterOfHeadAlign registration phase''' [--useCenterOfHeadAlign] : CenterOfHeadAlign attempts to find a hemisphere full of foreground voxels from the superior direction as an estimate of where the center of a head shape would be to drive a center of mass estimate. Perform a CenterOfHeadAlign registration as part of the sequential registration steps. This option MUST come first, and CAN NOT be used with either MomentsAlign, GeometryAlign, or initialTransform file. This family of options superceeds the use of transformType if any of them are set.
** '''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.
** '''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.
** '''Include ScaleSkewVersor3D registration phase''' [--useScaleSkewVersor3D] : Perform a rigid registration as part of the sequential registration steps. This family of options superceeds the use of transformType if any of them are set.
** '''Include Affine registration phase''' [--useAffine] : Perform a rigid registration as part of the sequential registration steps. This family of options superceeds the use of transformType if any of them are set.
** '''Include BSpline registration phase''' [--useBSpline] : Perform a rigid registration as part of the sequential registration steps. This family of options superceeds the use of transformType if any of them are set.
* '''''Output Settings (At least one output must be specified.)''''' (optional) Filename to which save the estimated transform. NOTE: You must set at least one output object (either a deformed image or a transform. NOTE: USE THIS ONLY IF THE FINAL TRANSFORM IS BSpline
** '''Slicer BSpline Transform''' [--bsplineTransform] : (optional) Filename to which save the estimated transform. NOTE: You must set at least one output object (either a deformed image or a transform. NOTE: USE THIS ONLY IF THE FINAL TRANSFORM IS BSpline
** '''Slicer Linear Transform''' [--linearTransform] : (optional) Filename to which save the estimated transform. NOTE: You must set at least one output object (either a deformed image or a transform. NOTE: USE THIS ONLY IF THE FINAL TRANSFORM IS ---NOT--- BSpline
** '''Output Transform''' [--outputTransform] : (optional) Filename to which save the (optional) estimated transform. NOTE: You must select either the outputTransform or the outputVolume option.
** '''Output Image Volume''' [--outputVolume] : (optional) Output image for registration. NOTE: You must select either the outputTransform or the outputVolume option.
** '''Output Image Pixel Type''' [--outputVolumePixelType] : The output image Pixel Type is the scalar datatype for representation of the Output Volume.
* '''''Registration Parameters''''' Specifies a list of registration types to be used. The valid types are, Rigid, ScaleVersor3D, ScaleSkewVersor3D, Affine, and BSpline. Specifiying more than one in a comma separated list will initialize the next stage with the previous results. If registrationClass flag is used, it overrides this parameter setting.
** '''Transform Type''' [--transformType] : Specifies a list of registration types to be used. The valid types are, Rigid, ScaleVersor3D, ScaleSkewVersor3D, Affine, and BSpline. Specifiying more than one in a comma separated list will initialize the next stage with the previous results. If registrationClass flag is used, it overrides this parameter setting.
** '''Number Of Iterations''' [--numberOfIterations] : The maximum number of iterations to try before failing to converge. Use an explicit limit like 500 or 1000 to manage risk of divergence
** '''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.
** '''Minimum Step Size''' [--minimumStepSize] : Each step in the optimization takes steps at least this big. When none are possible, registration is complete.
** '''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.
** '''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
** '''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
** '''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.
** '''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.

* '''''Advanced Output Settings''''' File name for the rigid component of the estimated affine transform. Can be used to rigidly register the moving image to the fixed image. NOTE: This value is overwritten if either bsplineTransform or linearTransform is set.
** '''Stripped Output Transform''' [--strippedOutputTransform] : File name for the rigid component of the estimated affine transform. Can be used to rigidly register the moving image to the fixed image. NOTE: This value is overwritten if either bsplineTransform or linearTransform is set.
** '''Background Fill Value''' [--backgroundFillValue] : Background fill value for output image.
** '''Inferior Cut Off From Center''' [--maskInferiorCutOffFromCenter] : For use with --useCenterOfHeadAlign (and --maskProcessingMode ROIAUTO): the cut-off below the image centers, in millimeters,
** '''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, or WindowedSinc
* '''''Control of Mask Processing''''' What mode to use for using the masks. If ROIAUTO is choosen, then the mask is implicitly defined using a otsu forground and hole filling algorithm. The Region Of Interest mode (choose ROI) uses the masks to define what parts of the image should be used for computing the transform.
** '''Mask Processing Mode''' [--maskProcessingMode] : What mode to use for using the masks. If ROIAUTO is choosen, then the mask is implicitly defined using a otsu forground and hole filling algorithm. The Region Of Interest mode (choose ROI) uses the masks to define what parts of the image should be used for computing the transform.
** '''Output Fixed Mask (ROIAUTO only)''' [--outputFixedVolumeROI] : The ROI automatically found in fixed image.
** '''Output Moving Mask (ROIAUTO only)''' [--outputMovingVolumeROI] : The ROI automatically found in moving image.
** '''Input Fixed Mask (ROI only)''' [--fixedBinaryVolume] : Fixed Image binary mask volume.
** '''Input Moving Mask (ROI only)''' [--movingBinaryVolume] : Moving Image binary mask volume.
* '''''Special Input Image Parameters''''' The index in the time series for the 3D fixed image to fit, if 4-dimensional.
** '''Fixed Image Time Index''' [--fixedVolumeTimeIndex] : The index in the time series for the 3D fixed image to fit, if 4-dimensional.
** '''Moving Image Time Index''' [--movingVolumeTimeIndex] : The index in the time series for the 3D moving image to fit, if 4-dimensional.
** '''Median Filter Size''' [--medianFilterSize] : The radius for the optional MedianImageFilter preprocessing in all 3 directions.
** '''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.
** '''Number of Histogram Bins''' [--numberOfHistogramBins] : the number of histogram levels
** '''Number of Match Points''' [--numberOfMatchPoints] : the number of match points
* '''''Registration Debugging Parameters''''' This is a 5x speed advantage at the expense of requiring much more memory. Only relevant when transformType is BSpline.
** '''Caching BSpline Weights Mode''' [--useCachingOfBSplineWeightsMode] : This is a 5x speed advantage at the expense of requiring much more memory. Only relevant when transformType is BSpline.
** '''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.
** ''' 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.
** '''Relaxation Factor''' [--relaxationFactor] : Internal debugging parameter, and should probably never be used from the command line. This will be removed in the future.
** '''Maximum Step Size''' [--maximumStepSize] : Internal debugging parameter, and should probably never be used from the command line. This will be removed in the future.
** '''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 )
** '''debugNumberOfThreads''' [--debugNumberOfThreads] : Explicitly specify the maximum number of threads to use.
** '''Debug option''' [--debugLevel] : Display debug messages, and produce debug intermediate results. 0=OFF, 1=Minimal, 10=Maximum debugging.
* '''''Risky Expert-only Parameters''''' A bit vector to permit linear transform parameters to vary under optimization. The vector order corresponds with transform parameters, and beyond the end ones fill in as a default. For instance, you can choose to rotate only in x (pitch) with 1,0,0; this is mostly for expert use in turning on and off individual degrees of freedom in rotation, translation or scaling without multiplying the number of transform representations; this trick is probably meaningless when tried with the general affine transform.
** '''Selective Permission for Transform Parameters to Vary''' [--permitParameterVariation] : A bit vector to permit linear transform parameters to vary under optimization. The vector order corresponds with transform parameters, and beyond the end ones fill in as a default. For instance, you can choose to rotate only in x (pitch) with 1,0,0; this is mostly for expert use in turning on and off individual degrees of freedom in rotation, translation or scaling without multiplying the number of transform representations; this trick is probably meaningless when tried with the general affine transform.
** '''Fixed Image Origin''' [--fixedVolumeOrigin] : The coordinates of the origin of the fixed image. This will over-ride the information read from disk and is VERY DANGEROUS.
** '''Moving Image Origin''' [--movingVolumeOrigin] : The coordinates of the origin of the moving image. This will over-ride the information read from disk and is VERY DANGEROUS.

||[[Image:BRAINSFitUI_part1.png|thumb|280px|User Interface]] [[Image:BRAINSFitUI_part2.png|thumb|280px|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:
<pre>

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");
}

</pre>

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

===Tests===

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

===Known bugs===

Links to known bugs and feature requests are listed at:
* http://www.nitrc.org/projects/multimodereg/

===Usability issues===

Follow this [http://na-mic.org/Mantis/main_page.php 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:
*[http://www.nitrc.org/projects/multimodereg/|Hosted by NITRC ]

== More Information ==

===Acknowledgment===

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

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

Modules:BRAINSFit

2010-06-07T13:30:36Z

Hjmjohnson: /* Notes from the Developer(s) */

[[Documentation-3.6|Return to Slicer 3.6 Documentation]]

[[Announcements:Slicer3.6#Highlights|Gallery of New Features]]

__NOTOC__
===Module Name===
BRAINSFit

{|
| [[Image:Before.png|thumb|280px|Before registration]]
|-
| [[Image:After.png|thumb|280px|AfterRegistration]]
|}

== General Information ==
===Module Type & Category===

Type: CLI

Category: Registration

===Authors, Collaborators & Contact===

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

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

===Module Description===

{| style="color:green" border="1"
|Program title || BRAINSFit

|-
|Program version || 3.0.0

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

|-
|}

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

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

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

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

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

===Quick Tour of Features and Use===

A list panels in the interface, their features, what they mean, and how to use them. For instance:

{|
|
* '''''Input Parameters''''' The fixed image for registration by mutual information optimization.
** '''Fixed Image Volume''' [--fixedVolume] : The fixed image for registration by mutual information optimization.
** '''Moving Image Volume''' [--movingVolume] : The moving image for registration by mutual information optimization.
* '''''Registration phases to use''''' Filename of transform used to initialize the registration. This CAN NOT be used with either CenterOfHeadLAlign, MomentsAlign, GeometryAlign, or initialTransform file.
** '''Initialize with previously generated transform''' [--initialTransform] : Filename of transform used to initialize the registration. This CAN NOT be used with either CenterOfHeadLAlign, MomentsAlign, GeometryAlign, or initialTransform file.
** '''Initialize with MomentsAlign registration phase''' [--useMomentsAlign] : MomentsAlign assumes that the center of mass of the images represent similar structures. Perform a MomentsAlign registration as part of the sequential registration steps. This option MUST come first, and CAN NOT be used with either CenterOfHeadLAlign, GeometryAlign, or initialTransform file. This family of options superceeds the use of transformType if any of them are set.
** '''Initialize with GeometryCenterAlign registration phase''' [--useGeometryAlign] : GeometryAlign on assumes that the center of the voxel lattice of the images represent similar structures. Perform a GeometryCenterAlign registration as part of the sequential registration steps. This option MUST come first, and CAN NOT be used with either MomentsAlign, CenterOfHeadAlign, or initialTransform file. This family of options superceeds the use of transformType if any of them are set.
** '''Initialize with CenterOfHeadAlign registration phase''' [--useCenterOfHeadAlign] : CenterOfHeadAlign attempts to find a hemisphere full of foreground voxels from the superior direction as an estimate of where the center of a head shape would be to drive a center of mass estimate. Perform a CenterOfHeadAlign registration as part of the sequential registration steps. This option MUST come first, and CAN NOT be used with either MomentsAlign, GeometryAlign, or initialTransform file. This family of options superceeds the use of transformType if any of them are set.
** '''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.
** '''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.
** '''Include ScaleSkewVersor3D registration phase''' [--useScaleSkewVersor3D] : Perform a rigid registration as part of the sequential registration steps. This family of options superceeds the use of transformType if any of them are set.
** '''Include Affine registration phase''' [--useAffine] : Perform a rigid registration as part of the sequential registration steps. This family of options superceeds the use of transformType if any of them are set.
** '''Include BSpline registration phase''' [--useBSpline] : Perform a rigid registration as part of the sequential registration steps. This family of options superceeds the use of transformType if any of them are set.
* '''''Output Settings (At least one output must be specified.)''''' (optional) Filename to which save the estimated transform. NOTE: You must set at least one output object (either a deformed image or a transform. NOTE: USE THIS ONLY IF THE FINAL TRANSFORM IS BSpline
** '''Slicer BSpline Transform''' [--bsplineTransform] : (optional) Filename to which save the estimated transform. NOTE: You must set at least one output object (either a deformed image or a transform. NOTE: USE THIS ONLY IF THE FINAL TRANSFORM IS BSpline
** '''Slicer Linear Transform''' [--linearTransform] : (optional) Filename to which save the estimated transform. NOTE: You must set at least one output object (either a deformed image or a transform. NOTE: USE THIS ONLY IF THE FINAL TRANSFORM IS ---NOT--- BSpline
** '''Output Transform''' [--outputTransform] : (optional) Filename to which save the (optional) estimated transform. NOTE: You must select either the outputTransform or the outputVolume option.
** '''Output Image Volume''' [--outputVolume] : (optional) Output image for registration. NOTE: You must select either the outputTransform or the outputVolume option.
** '''Output Image Pixel Type''' [--outputVolumePixelType] : The output image Pixel Type is the scalar datatype for representation of the Output Volume.
* '''''Registration Parameters''''' Specifies a list of registration types to be used. The valid types are, Rigid, ScaleVersor3D, ScaleSkewVersor3D, Affine, and BSpline. Specifiying more than one in a comma separated list will initialize the next stage with the previous results. If registrationClass flag is used, it overrides this parameter setting.
** '''Transform Type''' [--transformType] : Specifies a list of registration types to be used. The valid types are, Rigid, ScaleVersor3D, ScaleSkewVersor3D, Affine, and BSpline. Specifiying more than one in a comma separated list will initialize the next stage with the previous results. If registrationClass flag is used, it overrides this parameter setting.
** '''Number Of Iterations''' [--numberOfIterations] : The maximum number of iterations to try before failing to converge. Use an explicit limit like 500 or 1000 to manage risk of divergence
** '''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.
** '''Minimum Step Size''' [--minimumStepSize] : Each step in the optimization takes steps at least this big. When none are possible, registration is complete.
** '''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.
** '''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
** '''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
** '''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.
** '''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.

* '''''Advanced Output Settings''''' File name for the rigid component of the estimated affine transform. Can be used to rigidly register the moving image to the fixed image. NOTE: This value is overwritten if either bsplineTransform or linearTransform is set.
** '''Stripped Output Transform''' [--strippedOutputTransform] : File name for the rigid component of the estimated affine transform. Can be used to rigidly register the moving image to the fixed image. NOTE: This value is overwritten if either bsplineTransform or linearTransform is set.
** '''Background Fill Value''' [--backgroundFillValue] : Background fill value for output image.
** '''Inferior Cut Off From Center''' [--maskInferiorCutOffFromCenter] : For use with --useCenterOfHeadAlign (and --maskProcessingMode ROIAUTO): the cut-off below the image centers, in millimeters,
** '''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, or WindowedSinc
* '''''Control of Mask Processing''''' What mode to use for using the masks. If ROIAUTO is choosen, then the mask is implicitly defined using a otsu forground and hole filling algorithm. The Region Of Interest mode (choose ROI) uses the masks to define what parts of the image should be used for computing the transform.
** '''Mask Processing Mode''' [--maskProcessingMode] : What mode to use for using the masks. If ROIAUTO is choosen, then the mask is implicitly defined using a otsu forground and hole filling algorithm. The Region Of Interest mode (choose ROI) uses the masks to define what parts of the image should be used for computing the transform.
** '''Output Fixed Mask (ROIAUTO only)''' [--outputFixedVolumeROI] : The ROI automatically found in fixed image.
** '''Output Moving Mask (ROIAUTO only)''' [--outputMovingVolumeROI] : The ROI automatically found in moving image.
** '''Input Fixed Mask (ROI only)''' [--fixedBinaryVolume] : Fixed Image binary mask volume.
** '''Input Moving Mask (ROI only)''' [--movingBinaryVolume] : Moving Image binary mask volume.
* '''''Special Input Image Parameters''''' The index in the time series for the 3D fixed image to fit, if 4-dimensional.
** '''Fixed Image Time Index''' [--fixedVolumeTimeIndex] : The index in the time series for the 3D fixed image to fit, if 4-dimensional.
** '''Moving Image Time Index''' [--movingVolumeTimeIndex] : The index in the time series for the 3D moving image to fit, if 4-dimensional.
** '''Median Filter Size''' [--medianFilterSize] : The radius for the optional MedianImageFilter preprocessing in all 3 directions.
** '''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.
** '''Number of Histogram Bins''' [--numberOfHistogramBins] : the number of histogram levels
** '''Number of Match Points''' [--numberOfMatchPoints] : the number of match points
* '''''Registration Debugging Parameters''''' This is a 5x speed advantage at the expense of requiring much more memory. Only relevant when transformType is BSpline.
** '''Caching BSpline Weights Mode''' [--useCachingOfBSplineWeightsMode] : This is a 5x speed advantage at the expense of requiring much more memory. Only relevant when transformType is BSpline.
** '''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.
** ''' 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.
** '''Relaxation Factor''' [--relaxationFactor] : Internal debugging parameter, and should probably never be used from the command line. This will be removed in the future.
** '''Maximum Step Size''' [--maximumStepSize] : Internal debugging parameter, and should probably never be used from the command line. This will be removed in the future.
** '''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 )
** '''debugNumberOfThreads''' [--debugNumberOfThreads] : Explicitly specify the maximum number of threads to use.
** '''Debug option''' [--debugLevel] : Display debug messages, and produce debug intermediate results. 0=OFF, 1=Minimal, 10=Maximum debugging.
* '''''Risky Expert-only Parameters''''' A bit vector to permit linear transform parameters to vary under optimization. The vector order corresponds with transform parameters, and beyond the end ones fill in as a default. For instance, you can choose to rotate only in x (pitch) with 1,0,0; this is mostly for expert use in turning on and off individual degrees of freedom in rotation, translation or scaling without multiplying the number of transform representations; this trick is probably meaningless when tried with the general affine transform.
** '''Selective Permission for Transform Parameters to Vary''' [--permitParameterVariation] : A bit vector to permit linear transform parameters to vary under optimization. The vector order corresponds with transform parameters, and beyond the end ones fill in as a default. For instance, you can choose to rotate only in x (pitch) with 1,0,0; this is mostly for expert use in turning on and off individual degrees of freedom in rotation, translation or scaling without multiplying the number of transform representations; this trick is probably meaningless when tried with the general affine transform.
** '''Fixed Image Origin''' [--fixedVolumeOrigin] : The coordinates of the origin of the fixed image. This will over-ride the information read from disk and is VERY DANGEROUS.
** '''Moving Image Origin''' [--movingVolumeOrigin] : The coordinates of the origin of the moving image. This will over-ride the information read from disk and is VERY DANGEROUS.

||[[Image:BRAINSFitUI_part1.png|thumb|280px|User Interface]] [[Image:BRAINSFitUI_part2.png|thumb|280px|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:
<pre>

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");
}

</pre>

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

===Tests===

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

===Known bugs===

Links to known bugs and feature requests are listed at:
* http://www.nitrc.org/projects/multimodereg/

===Usability issues===

Follow this [http://na-mic.org/Mantis/main_page.php 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:
*[http://www.nitrc.org/projects/multimodereg/|Hosted by NITRC ]

== More Information ==

===Acknowledgment===

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

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

Modules:BRAINSFit

2010-06-06T19:19:04Z

Hjmjohnson: /* Quick Tour of Features and Use */

[[Documentation-3.6|Return to Slicer 3.6 Documentation]]

[[Announcements:Slicer3.6#Highlights|Gallery of New Features]]

__NOTOC__
===Module Name===
BRAINSFit

{|
| [[Image:Before.png|thumb|280px|Before registration]]
|-
| [[Image:After.png|thumb|280px|AfterRegistration]]
|}

== General Information ==
===Module Type & Category===

Type: CLI

Category: Registration

===Authors, Collaborators & Contact===

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

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

===Module Description===

{| style="color:green" border="1"
|Program title || BRAINSFit

|-
|Program version || 3.0.0

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

|-
|}

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

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

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

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

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

===Quick Tour of Features and Use===

A list panels in the interface, their features, what they mean, and how to use them. For instance:

{|
|
* '''''Input Parameters''''' The fixed image for registration by mutual information optimization.
** '''Fixed Image Volume''' [--fixedVolume] : The fixed image for registration by mutual information optimization.
** '''Moving Image Volume''' [--movingVolume] : The moving image for registration by mutual information optimization.
* '''''Registration phases to use''''' Filename of transform used to initialize the registration. This CAN NOT be used with either CenterOfHeadLAlign, MomentsAlign, GeometryAlign, or initialTransform file.
** '''Initialize with previously generated transform''' [--initialTransform] : Filename of transform used to initialize the registration. This CAN NOT be used with either CenterOfHeadLAlign, MomentsAlign, GeometryAlign, or initialTransform file.
** '''Initialize with MomentsAlign registration phase''' [--useMomentsAlign] : MomentsAlign assumes that the center of mass of the images represent similar structures. Perform a MomentsAlign registration as part of the sequential registration steps. This option MUST come first, and CAN NOT be used with either CenterOfHeadLAlign, GeometryAlign, or initialTransform file. This family of options superceeds the use of transformType if any of them are set.
** '''Initialize with GeometryCenterAlign registration phase''' [--useGeometryAlign] : GeometryAlign on assumes that the center of the voxel lattice of the images represent similar structures. Perform a GeometryCenterAlign registration as part of the sequential registration steps. This option MUST come first, and CAN NOT be used with either MomentsAlign, CenterOfHeadAlign, or initialTransform file. This family of options superceeds the use of transformType if any of them are set.
** '''Initialize with CenterOfHeadAlign registration phase''' [--useCenterOfHeadAlign] : CenterOfHeadAlign attempts to find a hemisphere full of foreground voxels from the superior direction as an estimate of where the center of a head shape would be to drive a center of mass estimate. Perform a CenterOfHeadAlign registration as part of the sequential registration steps. This option MUST come first, and CAN NOT be used with either MomentsAlign, GeometryAlign, or initialTransform file. This family of options superceeds the use of transformType if any of them are set.
** '''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.
** '''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.
** '''Include ScaleSkewVersor3D registration phase''' [--useScaleSkewVersor3D] : Perform a rigid registration as part of the sequential registration steps. This family of options superceeds the use of transformType if any of them are set.
** '''Include Affine registration phase''' [--useAffine] : Perform a rigid registration as part of the sequential registration steps. This family of options superceeds the use of transformType if any of them are set.
** '''Include BSpline registration phase''' [--useBSpline] : Perform a rigid registration as part of the sequential registration steps. This family of options superceeds the use of transformType if any of them are set.
* '''''Output Settings (At least one output must be specified.)''''' (optional) Filename to which save the estimated transform. NOTE: You must set at least one output object (either a deformed image or a transform. NOTE: USE THIS ONLY IF THE FINAL TRANSFORM IS BSpline
** '''Slicer BSpline Transform''' [--bsplineTransform] : (optional) Filename to which save the estimated transform. NOTE: You must set at least one output object (either a deformed image or a transform. NOTE: USE THIS ONLY IF THE FINAL TRANSFORM IS BSpline
** '''Slicer Linear Transform''' [--linearTransform] : (optional) Filename to which save the estimated transform. NOTE: You must set at least one output object (either a deformed image or a transform. NOTE: USE THIS ONLY IF THE FINAL TRANSFORM IS ---NOT--- BSpline
** '''Output Transform''' [--outputTransform] : (optional) Filename to which save the (optional) estimated transform. NOTE: You must select either the outputTransform or the outputVolume option.
** '''Output Image Volume''' [--outputVolume] : (optional) Output image for registration. NOTE: You must select either the outputTransform or the outputVolume option.
** '''Output Image Pixel Type''' [--outputVolumePixelType] : The output image Pixel Type is the scalar datatype for representation of the Output Volume.
* '''''Registration Parameters''''' Specifies a list of registration types to be used. The valid types are, Rigid, ScaleVersor3D, ScaleSkewVersor3D, Affine, and BSpline. Specifiying more than one in a comma separated list will initialize the next stage with the previous results. If registrationClass flag is used, it overrides this parameter setting.
** '''Transform Type''' [--transformType] : Specifies a list of registration types to be used. The valid types are, Rigid, ScaleVersor3D, ScaleSkewVersor3D, Affine, and BSpline. Specifiying more than one in a comma separated list will initialize the next stage with the previous results. If registrationClass flag is used, it overrides this parameter setting.
** '''Number Of Iterations''' [--numberOfIterations] : The maximum number of iterations to try before failing to converge. Use an explicit limit like 500 or 1000 to manage risk of divergence
** '''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.
** '''Minimum Step Size''' [--minimumStepSize] : Each step in the optimization takes steps at least this big. When none are possible, registration is complete.
** '''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.
** '''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
** '''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
** '''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.
** '''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.

* '''''Advanced Output Settings''''' File name for the rigid component of the estimated affine transform. Can be used to rigidly register the moving image to the fixed image. NOTE: This value is overwritten if either bsplineTransform or linearTransform is set.
** '''Stripped Output Transform''' [--strippedOutputTransform] : File name for the rigid component of the estimated affine transform. Can be used to rigidly register the moving image to the fixed image. NOTE: This value is overwritten if either bsplineTransform or linearTransform is set.
** '''Background Fill Value''' [--backgroundFillValue] : Background fill value for output image.
** '''Inferior Cut Off From Center''' [--maskInferiorCutOffFromCenter] : For use with --useCenterOfHeadAlign (and --maskProcessingMode ROIAUTO): the cut-off below the image centers, in millimeters,
** '''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, or WindowedSinc
* '''''Control of Mask Processing''''' What mode to use for using the masks. If ROIAUTO is choosen, then the mask is implicitly defined using a otsu forground and hole filling algorithm. The Region Of Interest mode (choose ROI) uses the masks to define what parts of the image should be used for computing the transform.
** '''Mask Processing Mode''' [--maskProcessingMode] : What mode to use for using the masks. If ROIAUTO is choosen, then the mask is implicitly defined using a otsu forground and hole filling algorithm. The Region Of Interest mode (choose ROI) uses the masks to define what parts of the image should be used for computing the transform.
** '''Output Fixed Mask (ROIAUTO only)''' [--outputFixedVolumeROI] : The ROI automatically found in fixed image.
** '''Output Moving Mask (ROIAUTO only)''' [--outputMovingVolumeROI] : The ROI automatically found in moving image.
** '''Input Fixed Mask (ROI only)''' [--fixedBinaryVolume] : Fixed Image binary mask volume.
** '''Input Moving Mask (ROI only)''' [--movingBinaryVolume] : Moving Image binary mask volume.
* '''''Special Input Image Parameters''''' The index in the time series for the 3D fixed image to fit, if 4-dimensional.
** '''Fixed Image Time Index''' [--fixedVolumeTimeIndex] : The index in the time series for the 3D fixed image to fit, if 4-dimensional.
** '''Moving Image Time Index''' [--movingVolumeTimeIndex] : The index in the time series for the 3D moving image to fit, if 4-dimensional.
** '''Median Filter Size''' [--medianFilterSize] : The radius for the optional MedianImageFilter preprocessing in all 3 directions.
** '''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.
** '''Number of Histogram Bins''' [--numberOfHistogramBins] : the number of histogram levels
** '''Number of Match Points''' [--numberOfMatchPoints] : the number of match points
* '''''Registration Debugging Parameters''''' This is a 5x speed advantage at the expense of requiring much more memory. Only relevant when transformType is BSpline.
** '''Caching BSpline Weights Mode''' [--useCachingOfBSplineWeightsMode] : This is a 5x speed advantage at the expense of requiring much more memory. Only relevant when transformType is BSpline.
** '''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.
** ''' 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.
** '''Relaxation Factor''' [--relaxationFactor] : Internal debugging parameter, and should probably never be used from the command line. This will be removed in the future.
** '''Maximum Step Size''' [--maximumStepSize] : Internal debugging parameter, and should probably never be used from the command line. This will be removed in the future.
** '''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 )
** '''debugNumberOfThreads''' [--debugNumberOfThreads] : Explicitly specify the maximum number of threads to use.
** '''Debug option''' [--debugLevel] : Display debug messages, and produce debug intermediate results. 0=OFF, 1=Minimal, 10=Maximum debugging.
* '''''Risky Expert-only Parameters''''' A bit vector to permit linear transform parameters to vary under optimization. The vector order corresponds with transform parameters, and beyond the end ones fill in as a default. For instance, you can choose to rotate only in x (pitch) with 1,0,0; this is mostly for expert use in turning on and off individual degrees of freedom in rotation, translation or scaling without multiplying the number of transform representations; this trick is probably meaningless when tried with the general affine transform.
** '''Selective Permission for Transform Parameters to Vary''' [--permitParameterVariation] : A bit vector to permit linear transform parameters to vary under optimization. The vector order corresponds with transform parameters, and beyond the end ones fill in as a default. For instance, you can choose to rotate only in x (pitch) with 1,0,0; this is mostly for expert use in turning on and off individual degrees of freedom in rotation, translation or scaling without multiplying the number of transform representations; this trick is probably meaningless when tried with the general affine transform.
** '''Fixed Image Origin''' [--fixedVolumeOrigin] : The coordinates of the origin of the fixed image. This will over-ride the information read from disk and is VERY DANGEROUS.
** '''Moving Image Origin''' [--movingVolumeOrigin] : The coordinates of the origin of the moving image. This will over-ride the information read from disk and is VERY DANGEROUS.

||[[Image:BRAINSFitUI_part1.png|thumb|280px|User Interface]] [[Image:BRAINSFitUI_part2.png|thumb|280px|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:

<pre>
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");
}
*/
</pre>

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

===Tests===

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

===Known bugs===

Links to known bugs and feature requests are listed at:
* http://www.nitrc.org/projects/multimodereg/

===Usability issues===

Follow this [http://na-mic.org/Mantis/main_page.php 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:
*[http://www.nitrc.org/projects/multimodereg/|Hosted by NITRC ]

== More Information ==

===Acknowledgment===

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

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

File:After.png

2010-06-06T19:08:54Z

Hjmjohnson:

File:Before.png

2010-06-06T19:08:28Z

Hjmjohnson:

Modules:BRAINSFit

2010-06-06T19:08:13Z

Hjmjohnson: /* Module Name */

Modules:BRAINSFit

2010-06-06T19:07:12Z

Hjmjohnson:

File:BRAINSFitUI part2.png

2010-06-06T19:01:39Z

Hjmjohnson:

File:BRAINSFitUI part1.png

2010-06-06T19:01:10Z

Hjmjohnson:

Modules:BRAINSFit

2010-06-06T19:00:43Z

Hjmjohnson:

[[Documentation-3.6|Return to Slicer 3.6 Documentation]]

[[Announcements:Slicer3.6#Highlights|Gallery of New Features]]

__NOTOC__
===Module Name===
BRAINSFit

{|
| || [[Before.png|thumb|280px|Before registration]]
| || [[After.png|thumb|280px|AfterRegistration]]
|}

== General Information ==
===Module Type & Category===

Type: CLI

Category: Registration

===Authors, Collaborators & Contact===

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

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

===Module Description===

{| style="color:green" border="1"
|Program title || BRAINSFit

|-
|Program version || 3.0.0

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

|-
|}

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

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

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

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

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

===Quick Tour of Features and Use===

A list panels in the interface, their features, what they mean, and how to use them. For instance:

{|
|
* '''''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.
** '''Class of Registration''' [--registrationClass]: Specifies one of the five supported transform types. The valid types are, (R)Rigid, (R+S)ScaleVersor3D, (R+S+S)ScaleSkewVersor3D, (A)Affine, (BS)BSpline, (O)ther. Note that registration proceeds from the lowest parameter dimension upto the parameter type choosen. Selecting BS for registrationClass has the same effect as setting transformType to "Rigid,ScaleVersor3D,ScaleSkewVersor3D,Affine,BSpline". Set to (O)ther when using the more flexible Transform Type flag under Registration Parameters settings.
* '''''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.
* '''''Transform Initialization Parameters''''' 
** '''Intitialze Transform Mode''' [--initializeTransformMode]: 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.
** '''Initial Transform''' [--initialTransform]: Filename of transform used to initialize the registration.
* '''''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
** '''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.
** '''Minimum Step Size''' [--minimumStepSize]: Each step in the optimization takes steps at least this big. When none are possible, registration is complete.
** '''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.
** '''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
** '''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
** '''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.
** '''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.

* '''''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.
** '''Inferior Cut Off From Center''' [--maskInferiorCutOffFromCenter]: For use with --initializeTransformMode CenterOfHead (and --maskProcessingMode ROIAUTO): the cut-off below the image centers, in millimeters,
** '''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, or WindowedSinc
* '''''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.
** '''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.
** '''Moving Image Time Index''' [--movingVolumeTimeIndex]: The index in the time series for the 3D moving image to fit, if 4-dimensional.
** '''Median Filter Size''' [--medianFilterSize]: The radius for the optional MedianImageFilter preprocessing in all 3 directions.
** '''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.
** '''Number of Histogram Bins''' [--numberOfHistogramBins]: the number of histogram levels
** '''Number of Match Points''' [--numberOfMatchPoints]: the number of match points
* '''''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.
** '''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.
** ''' 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.
** '''Relaxation Factor''' [--relaxationFactor]: Internal debugging parameter, and should probably never be used from the command line. This will be removed in the future.
** '''Maximum Step Size''' [--maximumStepSize]: Internal debugging parameter, and should probably never be used from the command line. This will be removed in the future.
** '''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 )
** '''debugNumberOfThreads''' [--debugNumberOfThreads]: Explicitly specify the maximum number of threads to use.
** '''Debug option''' [--debugLevel]: Display debug messages, and produce debug intermediate results. 0=OFF, 1=Minimal, 10=Maximum debugging.
* '''''Risky Expert-only Parameters''''' 
** '''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.
** '''Fixed Image Origin''' [--fixedVolumeOrigin]: The coordinates of the origin of the fixed image. This will over-ride the information read from disk and is VERY DANGEROUS.
** '''Moving Image Origin''' [--movingVolumeOrigin]: The coordinates of the origin of the moving image. This will over-ride the information read from disk and is VERY DANGEROUS.

||[[Image:BRAINSFitUI_part1.png|thumb|280px|User Interface]] [[Image:BRAINSFitUI_part2.png|thumb|280px|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:

<pre>
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");
}
*/
</pre>

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

===Tests===

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

===Known bugs===

Links to known bugs and feature requests are listed at:
* http://www.nitrc.org/projects/multimodereg/

===Usability issues===

Follow this [http://na-mic.org/Mantis/main_page.php 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:
*[http://www.nitrc.org/projects/multimodereg/|Hosted by NITRC ]

== More Information ==

===Acknowledgment===

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

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

File:BRAINSFitUI.png

2010-06-06T18:58:18Z

Hjmjohnson: uploaded a new version of "File:BRAINSFitUI.png"

File:BRAINSFitUI.png

2010-06-06T18:57:01Z

Hjmjohnson: uploaded a new version of "File:BRAINSFitUI.png"

Modules:BRAINSFit

2010-06-05T03:12:25Z

Hjmjohnson: /* Module Name */

[[Documentation-3.6|Return to Slicer 3.6 Documentation]]

[[Announcements:Slicer3.6#Highlights|Gallery of New Features]]

__NOTOC__
===Module Name===
BRAINSFit

{|
|[[Image:BRAINSFitUI.png|thumb|280px|User Interface]] || [[Before.png|thumb|280px|Before registration]]
| || [[After.png|thumb|280px|AfterRegistration]]
|}

== General Information ==
===Module Type & Category===

Type: CLI

Category: Registration

===Authors, Collaborators & Contact===

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

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

===Module Description===

{| style="color:green" border="1"
|Program title || BRAINSFit

|-
|Program version || 3.0.0

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

|-
|}

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

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

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

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

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

===Quick Tour of Features and Use===

A list panels in the interface, their features, what they mean, and how to use them. For instance:

{|
|
* '''''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.
** '''Class of Registration''' [--registrationClass]: Specifies one of the five supported transform types. The valid types are, (R)Rigid, (R+S)ScaleVersor3D, (R+S+S)ScaleSkewVersor3D, (A)Affine, (BS)BSpline, (O)ther. Note that registration proceeds from the lowest parameter dimension upto the parameter type choosen. Selecting BS for registrationClass has the same effect as setting transformType to "Rigid,ScaleVersor3D,ScaleSkewVersor3D,Affine,BSpline". Set to (O)ther when using the more flexible Transform Type flag under Registration Parameters settings.
* '''''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.
* '''''Transform Initialization Parameters''''' 
** '''Intitialze Transform Mode''' [--initializeTransformMode]: 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.
** '''Initial Transform''' [--initialTransform]: Filename of transform used to initialize the registration.
* '''''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
** '''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.
** '''Minimum Step Size''' [--minimumStepSize]: Each step in the optimization takes steps at least this big. When none are possible, registration is complete.
** '''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.
** '''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
** '''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
** '''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.
** '''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.

* '''''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.
** '''Inferior Cut Off From Center''' [--maskInferiorCutOffFromCenter]: For use with --initializeTransformMode CenterOfHead (and --maskProcessingMode ROIAUTO): the cut-off below the image centers, in millimeters,
** '''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, or WindowedSinc
* '''''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.
** '''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.
** '''Moving Image Time Index''' [--movingVolumeTimeIndex]: The index in the time series for the 3D moving image to fit, if 4-dimensional.
** '''Median Filter Size''' [--medianFilterSize]: The radius for the optional MedianImageFilter preprocessing in all 3 directions.
** '''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.
** '''Number of Histogram Bins''' [--numberOfHistogramBins]: the number of histogram levels
** '''Number of Match Points''' [--numberOfMatchPoints]: the number of match points
* '''''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.
** '''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.
** ''' 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.
** '''Relaxation Factor''' [--relaxationFactor]: Internal debugging parameter, and should probably never be used from the command line. This will be removed in the future.
** '''Maximum Step Size''' [--maximumStepSize]: Internal debugging parameter, and should probably never be used from the command line. This will be removed in the future.
** '''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 )
** '''debugNumberOfThreads''' [--debugNumberOfThreads]: Explicitly specify the maximum number of threads to use.
** '''Debug option''' [--debugLevel]: Display debug messages, and produce debug intermediate results. 0=OFF, 1=Minimal, 10=Maximum debugging.
* '''''Risky Expert-only Parameters''''' 
** '''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.
** '''Fixed Image Origin''' [--fixedVolumeOrigin]: The coordinates of the origin of the fixed image. This will over-ride the information read from disk and is VERY DANGEROUS.
** '''Moving Image Origin''' [--movingVolumeOrigin]: The coordinates of the origin of the moving image. This will over-ride the information read from disk and is VERY DANGEROUS.

||[[Image:BRAINSFitUI.png|thumb|280px|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:

<pre>
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");
}
*/
</pre>

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

===Tests===

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

===Known bugs===

Links to known bugs and feature requests are listed at:
* http://www.nitrc.org/projects/multimodereg/

===Usability issues===

Follow this [http://na-mic.org/Mantis/main_page.php 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:
*[http://www.nitrc.org/projects/multimodereg/|Hosted by NITRC ]

== More Information ==

===Acknowledgment===

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

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

File:BRAINSResampleUI.png

2010-06-05T02:59:09Z

Hjmjohnson: uploaded a new version of "File:BRAINSResampleUI.png"

Modules:BRAINSDemonWarp

2010-06-05T02:57:19Z

Hjmjohnson:

[[Documentation-3.6|Return to Slicer 3.6 Documentation]]

[[Announcements:Slicer3.6#Highlights|Gallery of New Features]]

__NOTOC__
===Module Name===
MyModule

{|
|[[Image:BRAINSDemonWarpForm.png|thumb|280px|User Interface]]
|}

== General Information ==
===Module Type & Category===

Type: CLI

Category: Registration

===Authors, Collaborators & Contact===

Author: This tool was developed by Hans J. Johnson and Greg Harris.

Contributors: The development of this tool 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.

===Module Description===

{| style="color:green" border="1"

|Program title || BRAINSDemonWarp

|-
|Program version || 3.0.0

|-
|Program documentation-url || http://wiki.slicer.org/slicerWiki/index.php/Modules:BRAINSDemonWarp

|-
|}

== Usage ==
The module registers the template (moving) image onto the physical space of the target (fixed) image. The resultant deformation fields and metric values can be written to a file. The program uses the Insight Toolkit (www.ITK.org) for all the computations, and can operate on any of the image file types supported by that library.

===Use Cases, Examples===
The inputs to the BrainDemonsWarp program are the target image, the template image and the optional parameters. These parameters define the arguments for histogram matching and multi resolution registration. The outputs are the deformation field, output image, checkerboard image of the output and the fixed image and the x,y,z displacement vectors. If we specify debug option we can get the outputs at different stages. The filter is templated over the input image type, real image type and the output image types. We implement the algorithm by parsing the input, preprocessing them and registering the processed images.

# Parsing - The images are initialized by the ValidationInputParser. This function reads in the arguments from the parameter file. It sets the histogram bins, match points, number of levels in the multi resolution registration, shrink factors and number of iterations at each levels. If the orientations of the images are different it sets the orientation of the moving image to that of the fixed image.
# PreProcessing - In the next step the DemonsPreProcessor preprocesses the images by resampling the template image to target image space. The intensity mismatch problem is solved by histogram matching the images. Histogram matching is done only if the command line option -e is set. ItkHistogramMatchingImageFilter is used to perform this function. Another important step in preprocessing is skull stripping. Skull stripping is done only if the command line option -maskProcessingMode is set to BOBF. We have written an itk filter, named itkBOBFFilter for this purpose. This filter takes in an input image and a whole brain mask and outputs a Brain Only Background Filled(BOBF) image. The non-brain parts in the image are filled with the user specified background value. All computations are performed in the precision of ﬂoat data.
# Registration - The resulting moving Image and the fixed image are given as inputs to the demons registrator.It uses the MultiResolutionPDEDeformableRegistration filter with NN extrapolation as interpolator and implements the demons deformable algorithm by computing the deformation field which will map a moving image onto a fixed image. It is assumed that the vector elements behave like ﬂoating point scalars. Each vector in the deformation field represent the distance between a geometric point in the input space and a point in the output space. The output image is generated by warping the input image with the deformation field using the ItkWarpImageFilter. WarpImageFilter warps an existing image with respect to a given deformation field. Typically the mapped position does not correspond to an integer pixel position in the input image. Interpolation via an image function is used to compute values at non-integer positions. We have used the LinearInterpolateImageFunction for our application. To write the output image we cast the image to the user specified output pixel type.

===Quick Tour of Features and Use===

* '''''Inputs''''' Common input parameters. All must be specified
** '''Moving Image Volume''' [--movingVolume][-m]: Required: input moving image
** '''Fixed Image Volume''' [--fixedVolume][-f]: Required: input fixed (target) image
** '''Input Type''' [--inputPixelType]: Input volumes will be typecast to this format: float|short|ushort|int|uchar
* '''''Outputs''''' Common output parameters. At least one must be specified.
** '''Output Image Volume''' [--outputVolume][-o]: Required: output resampled moving image (will have the same physical space as the fixedVolume).
** '''Output Deformation Field Volume''' [--outputDeformationFieldVolume][-O]: Output deformation field vector image (will have the same physical space as the fixedVolume).
** '''Output Type''' [--outputPixelType]: outputVolume will be typecast to this format: float|short|ushort|int|uchar
** '''Interpolation Mode''' [--interpolationMode]: Type of interpolation to be used when applying transform to moving volume. Options are Linear, NearestNeighbor, BSpline, or WindowedSinc
* '''''Registration Parameters''''' Input parameters controlling the behavior of the demons registration.
** '''Registration Filter Type''' [--registrationFilterType]: Registration Filter Type: Demons|FastSymmetricForces|Diffeomorphic|LogDemons|SymmetricLogDemons
** '''Deformation field smoothing sigma''' [--smoothDeformationFieldSigma][-s]: A gaussian smoothing value to be applied to the deformation feild at each iteration.
** '''Pyramid Levels''' [--numberOfPyramidLevels][-n]: Number of image pyramid levels to use in the multi-resolution registration.
** '''Moving Shrink Factors''' [--minimumFixedPyramid]: The shrink factor for the first level of the fixed image pyramid. (i.e. start at 1/16 scale, then 1/8, then 1/4, then 1/2, and finally full scale)
** '''Moving Shrink Factors''' [--minimumMovingPyramid]: The shrink factor for the first level of the moving image pyramid. (i.e. start at 1/16 scale, then 1/8, then 1/4, then 1/2, and finally full scale)
** '''the iteration count for each pyramid level''' [--arrayOfPyramidLevelIterations][-i]: The number of iterations for each pyramid level
* ''''' Input image pre-processing options ''''' Operations to perform on the images before starting the registration.
** '''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.
** '''Number of histogram bins to use in histogramMatch''' [--numberOfHistogramBins]: The number of histogram levels
** '''Number of Match Points''' [--numberOfMatchPoints]: The number of match points for histrogramMatch
** '''Median Filter Size''' [--medianFilterSize]: Median filter radius in all 3 directions. When images have a lot of salt and pepper noise, this step can improve the registration.
* ''''' Deformation field initialziation ''''' Options for initializing the deformation field.
** '''Initial Deformation Field Volume''' [--initializeWithDeformationField]: Initial deformation field vector image file name
** '''Initial Transform Filename''' [--initializeWithTransform]: Initial Transform filename
* ''''' Mask Options ''''' Options for setting binary masks for the registration.
** '''Mask Processing Mode''' [--maskProcessingMode]: What mode to use for using the masks: NOMASK|ROIAUTO|ROI|BOBF. If ROIAUTO is choosen, then the mask is implicitly defined using a otsu forground and hole filling algorithm. Where the Region Of Interest mode uses the masks to define what parts of the image should be used for computing the deformation field. Brain Only Background Fill uses the masks to pre-process the input images by clipping and filling in the background with a predefined value.
** '''Input Fixed Mask Filename''' [--fixedBinaryVolume]: Mask filename for desired region of interest in the Fixed image.
** '''Input Moving Mask Filename''' [--movingBinaryVolume]: Mask filename for desired region of interest in the Moving image.
** '''BOBF Lower Threshold''' [--lowerThresholdForBOBF]: Lower threshold for performing BOBF
** '''BOBF Upper Threshold''' [--upperThresholdForBOBF]: Upper threshold for performing BOBF
** '''BOBF Background Replacement Value''' [--backgroundFillValue]: Replacement value to overwrite background when performing BOBF
** '''Seed For BOBF''' [--seedForBOBF]: coordinates in all 3 directions for Seed when performing BOBF
** '''Seed For BOBF''' [--neighborhoodForBOBF]: neighborhood in all 3 directions to be included when performing BOBF
* ''''' Advanced Options ''''' Uncommon debugging or other advanced options.
** '''Component displacement field prefix''' [--outputDisplacementFieldPrefix]: Displacement field filename prefix for writing separate x, y, and z component images
** '''Output Checkerboard Volume''' [--outputCheckerboardVolume]: Genete a checkerboard image volume between the fixedVolume and the deformed movingVolume.
** '''Checkerboard Pattern Subdivisions''' [--checkerboardPatternSubdivisions]: Number of Checkerboard subdivisions in all 3 directions
** '''Warp Normalized Images''' [--outputNormalized]: Flag to warp and write the normalized images to output. In normalized images the image values are fit-scaled to be between 0 and the maximum storage type value.
** '''Write Intermediate Images''' [--outputDebug][-v]: Flag to write debugging images after each step.
** '''Gradient Type''' [--gradient_type][-t]: Type of gradient used for computing the demons force (0 is symmetrized, 1 is fixed image, 2 is moving image)
** '''Update field smoothing''' [--upFieldSmoothing][-g]: Smoothing sigma for the update field at each iteration
** '''Max Step Length''' [--max_step_length][-l]: Maximum length of an update vector (0: no restriction)
** '''Turn off Diffeomorphism''' [--use_vanilla_dem][-a]: Run vanilla demons algorithm

== Development ==

===Notes from the Developer(s)===

===Dependencies===

===Tests===
http://testing.psychiatry.uiowa.edu/CDash

===Usability issues===

Follow this [http://na-mic.org/Mantis/main_page.php link] to the Slicer3 bug tracker. Please select the '''usability issue category''' when browsing or contributing.

== More Information ==

===Acknowledgment===
The development of this tool was supported by funding from grants NS050568 and NS40068 from the National Institute of Neurological Disorders and Stroke and grants MH31593, MH40856, from the National Institute of Mental Health.

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