Slicer Wiki - User contributions [en]

Modules:DicomToNRRD-3.6

2011-03-14T20:27:36Z

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

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

__NOTOC__
===Module Name===
DWI Dicom To NRRD

{|
|[[Image:DWIDicomToNrrdGUI.png|thumb|280px|Screenshot of the UI]]
|}

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

Type: Command line module

Category: Converters

===Authors, Collaborators & Contact===
* Author: Xiaodong Tao (with contribution from Vince Magnotta and Hans Johnson)
* Contact: taox @ research.ge.com

===Module Description===
This module converts diffusion weighted MR images in dicom series into Nrrd
format for analysis in Slicer. This program has been tested on only
a limited subset of DTI dicom formats available from Siemens, GE,
and Phillips scanners. Work in progress to support dicom multi-frame
data. The program parses dicom header to extract necessary
information about measurement frame, diffusion weighting directions,
b-values, etc, and write out a nrrd image.

== Usage ==

===Examples, Use cases & Tutorials===

This module is typically used as the first step in diffusion weighted image analysis and tractography to convert diffusion weighted images in Dicom format into Nrrd format, which is recognized by Slicer3 as a legitimate diffusion weighted volume.

In the recent development, it is extended to act as a dicom series to nrrd file converted for non-diffusion-weighted images as well.

====Supported DWI formats====
*Philips scanner/software version combinations:
**Achieva 2.1.3.6
**Achieva 2.5.3.0
**Achieva 2.5.3.3
**Achieva 2.6.1.0
**Acheiva 2.6.3.4
**Intera 2.1.3.6
**Intera 2.6.3.5
*Siemens
**Trio B13
**Trio B15
**Trio B17
**Verio B15V
*GE
**SIGNA HDx14.0
**SIGNA HDxt 15.0
**DVMR 20.0M4
**DVMR 20.1

====Command Line Usage====
A command line example for running the module is:

d:\Builds\Slicer3\lib\Slicer3\Plugins\Release\DicomToNrrdConverter.exe --inputDicomDirectory MyDicomDir --outputVolume MyNrrdImage.nhdr

The module is currently set to quit and alert the user of gradients whose magnitudes are unreasonably small (greater than 0 and less than the smallGradientThreshold) via the '''smallGradientThreshold''' flag (default value for smallGradientThreshold: 0.2). This flag was created after encountering gradient vectors whose magnitudes were unusually small in Siemens Trio Tim B13 data due to incorrect metadata for diffusion gradient vector coordinate entries in the DICOM header public element tags.

'''For Siemens data:''' In event of incorrect metadata for diffusion gradient vector coordinates in the DICOM header public element tags, please set the '''useBMatrixGradientDirections''' flag. When the useBMatrixGradientDirections flag is set, gradient direction coordinates and b values are derived from the '''bMatrix''' DICOM header private element tag for each gradient. In Siemens DWI data, the b matrix elements are the product of the b value and unit gradient direction vector (column vector) multiplied by the transpose of the unit gradient direction vector. Therefore, for a given gradient direction, the unit gradient direction vector coordinates are the first column of the 3x3 unitary matrix from a singular value decomposition of its b matrix, while the b value is the trace of its b matrix.

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

[[Image:DicomToNrrdConverter_wiki.png|thumb|right|280px|Input/Output panels]]
When this module is run from Slicer UI, simply select the directories for '''Input Dicom Data''' and '''Output Directory''', enter the filename (without path name, but '''with''' extension, such as '''mydti.nrrd''') in the '''Output Filename''' field, and press "Apply" button.

The module can also be run from command line to enable batch process. An example command line look like:

d:\Builds\Slicer3\lib\Slicer3\Plugins\Release\DicomToNrrdConverter.exe
--inputDicomDirectory MyDicomDir
--outputDirectory /scratch/Diffusion
--outputVolume MyNrrdImage.nrrd

== Development==

===Dependencies===

This module depends only on the core "Volumes" module of slice for data IO.

===Known Bugs===

===Usability Issues===

Because different vendors used different private tags to store information related to diffusion weighting and documentation on how to interoperate this information is scarce, the current version support diffusion weighted images from GE, Siemens, and Philips scanners. For Siemens, both mosaic and split formats are supported. For Philips, both multi-slice and signal-slice formats are supported.

The current version also support non-diffusion weighted images from any vendors (that GDCM supports), in which case, the module acts as a dicom series to nrrd volume converter.

===Source Code and Documentation===

Source Code: [http://viewvc.na-mic.org/viewcvs.cgi/trunk/Applications/CLI/DicomToNrrdConverter/DicomToNrrdConverter.cxx?view=markup DicomToNrrdConverter.cxx]

XML Description: [http://viewvc.na-mic.org/viewcvs.cgi/trunk/Applications/CLI/DicomToNrrdConverter/DicomToNrrdConverter.xml?view=markup DicomToNrrdConverter.xml]

Test: [http://viewvc.na-mic.org/viewcvs.cgi/trunk/Applications/CLI/DicomToNrrdConverter/Testing/DicomToNrrdConverterTest.cxx?rev=12979&view=log DicomToNrrdConverterTest.cxx]

<pre>
./lib/Slicer3/Plugins/DicomToNrrdConverter --help

USAGE:

./lib/Slicer3/Plugins/DicomToNrrdConverter [--returnparameterfile
<std::string>]
[--processinformationaddress
<std::string>] [--xml] [--echo]
[--useIdentityMeaseurementFrame]
[--writeProtocolGradientsFile]
[--outputVolume <std::string>]
[--outputDirectory <std::string>]
[--inputDicomDirectory
<std::string>] [--] [--version]
[-h]

Where:

--returnparameterfile <std::string>
Filename in which to write simple return parameters (int, float,
int-vector, etc.) as opposed to bulk return parameters (image,
geometry, transform, measurement, table).

--processinformationaddress <std::string>
Address of a structure to store process information (progress, abort,
etc.). (default: 0)

--xml
Produce xml description of command line arguments (default: 0)

--echo
Echo the command line arguments (default: 0)

--useBMatrixGradientDirections
Fill the nhdr header with the gradient directions and bvalues computed
out of the BMatrix. Only changes behavior for Siemens data. (default:
0)

--useIdentityMeaseurementFrame
Adjust all the gradients so that the measurement frame is an identity
matrix. (default: 0)

--writeProtocolGradientsFile
Write the protocol gradients to a file suffixed by '.txt' as they were
specified in the procol by multiplying each diffusion gradient
direction by the measurement frame. This file is for debugging
purposes only, the format is not fixed, and will likely change as
debugging of new dicom formats is necessary. (default: 0)

--smallGradientThreshold <double>
If a gradient magnitude is greater than 0 and less than
smallGradientThreshold, then DicomToNrrdConverter will display an
error message and quit, unless the useBMatrixGradientDirections option
is set. (default: 0.2)

--outputVolume <std::string>
Output filename (.nhdr)

--outputDirectory <std::string>
Directory holding the output NRRD format

--inputDicomDirectory <std::string>
Directory holding Dicom series

--, --ignore_rest
Ignores the rest of the labeled arguments following this flag.

--version
Displays version information and exits.

-h, --help
Displays usage information and exits.

Description: Converts diffusion weighted MR images in dicom series into
Nrrd format for analysis in Slicer. This program has been tested on only
a limited subset of DTI dicom formats available from Siemens, GE, and
Phillips scanners. Work in progress to support dicom multi-frame data.
The program parses dicom header to extract necessary information about
measurement frame, diffusion weighting directions, b-values, etc, and
write out a nrrd image. For non-diffusion weighted dicom images, it
loads in an entire dicom series and writes out a single dicom volume in
a .nhdr/.raw pair.

Author(s): Xiaodong Tao

Acknowledgements: This work is part of the National Alliance for Medical
Image Computing (NAMIC), funded by the National Institutes of Health
through the NIH Roadmap for Medical Research, Grant U54 EB005149.
Additional support for DTI data produced on Philips scanners was
contributed by Vincent Magnotta and Hans Johnson at the University of
Iowa.
</pre>

==More Information==

===Acknowledgement===

Acknowledgements: This work is part of the National Alliance for Medical Image Computing (NAMIC), funded by the National Institutes of Health through the NIH Roadmap for Medical Research, Grant U54 EB005149. Additional support for DTI data produced on Philips scanners was contributed by Vincent Magnotta and Hans Johnson at the University of Iowa.

===References===

More information on Dicom format for diffusion weighted images on [http://www.na-mic.org/Wiki/index.php/NAMIC_Wiki:DTI:DICOM_for_DWI_and_DTI NA-MIC Wiki.]

File:DicomToNrrdConverter wiki.png

2011-03-14T20:27:01Z

Matsuij:

Modules:DicomToNRRD-3.6

2011-03-14T20:15:42Z

Matsuij: /* Command Line Usage */

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

__NOTOC__
===Module Name===
DWI Dicom To NRRD

{|
|[[Image:DWIDicomToNrrdGUI.png|thumb|280px|Screenshot of the UI]]
|}

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

Type: Command line module

Category: Converters

===Authors, Collaborators & Contact===
* Author: Xiaodong Tao (with contribution from Vince Magnotta and Hans Johnson)
* Contact: taox @ research.ge.com

===Module Description===
This module converts diffusion weighted MR images in dicom series into Nrrd
format for analysis in Slicer. This program has been tested on only
a limited subset of DTI dicom formats available from Siemens, GE,
and Phillips scanners. Work in progress to support dicom multi-frame
data. The program parses dicom header to extract necessary
information about measurement frame, diffusion weighting directions,
b-values, etc, and write out a nrrd image.

== Usage ==

===Examples, Use cases & Tutorials===

This module is typically used as the first step in diffusion weighted image analysis and tractography to convert diffusion weighted images in Dicom format into Nrrd format, which is recognized by Slicer3 as a legitimate diffusion weighted volume.

In the recent development, it is extended to act as a dicom series to nrrd file converted for non-diffusion-weighted images as well.

====Supported DWI formats====
*Philips scanner/software version combinations:
**Achieva 2.1.3.6
**Achieva 2.5.3.0
**Achieva 2.5.3.3
**Achieva 2.6.1.0
**Acheiva 2.6.3.4
**Intera 2.1.3.6
**Intera 2.6.3.5
*Siemens
**Trio B13
**Trio B15
**Trio B17
**Verio B15V
*GE
**SIGNA HDx14.0
**SIGNA HDxt 15.0
**DVMR 20.0M4
**DVMR 20.1

====Command Line Usage====
A command line example for running the module is:

d:\Builds\Slicer3\lib\Slicer3\Plugins\Release\DicomToNrrdConverter.exe --inputDicomDirectory MyDicomDir --outputVolume MyNrrdImage.nhdr

The module is currently set to quit and alert the user of gradients whose magnitudes are unreasonably small (greater than 0 and less than the smallGradientThreshold) via the '''smallGradientThreshold''' flag (default value for smallGradientThreshold: 0.2). This flag was created after encountering gradient vectors whose magnitudes were unusually small in Siemens Trio Tim B13 data due to incorrect metadata for diffusion gradient vector coordinate entries in the DICOM header public element tags.

'''For Siemens data:''' In event of incorrect metadata for diffusion gradient vector coordinates in the DICOM header public element tags, please set the '''useBMatrixGradientDirections''' flag. When the useBMatrixGradientDirections flag is set, gradient direction coordinates and b values are derived from the '''bMatrix''' DICOM header private element tag for each gradient. In Siemens DWI data, the b matrix elements are the product of the b value and unit gradient direction vector (column vector) multiplied by the transpose of the unit gradient direction vector. Therefore, for a given gradient direction, the unit gradient direction vector coordinates are the first column of the 3x3 unitary matrix from a singular value decomposition of its b matrix, while the b value is the trace of its b matrix.

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

[[Image:DicomToNrrd-IOPanels-3-6.png|thumb|right|280px|Input/Output panels]]
When this module is run from Slicer UI, simply select the directories for '''Input Dicom Data''' and '''Output Directory''', enter the filename (without path name, but '''with''' extension, such as '''mydti.nrrd''') in the '''Output Filename''' field, and press "Apply" button.

The module can also be run from command line to enable batch process. An example command line look like:

d:\Builds\Slicer3\lib\Slicer3\Plugins\Release\DicomToNrrdConverter.exe
--inputDicomDirectory MyDicomDir
--outputDirectory /scratch/Diffusion
--outputVolume MyNrrdImage.nrrd

== Development==

===Dependencies===

This module depends only on the core "Volumes" module of slice for data IO.

===Known Bugs===

===Usability Issues===

Because different vendors used different private tags to store information related to diffusion weighting and documentation on how to interoperate this information is scarce, the current version support diffusion weighted images from GE, Siemens, and Philips scanners. For Siemens, both mosaic and split formats are supported. For Philips, both multi-slice and signal-slice formats are supported.

The current version also support non-diffusion weighted images from any vendors (that GDCM supports), in which case, the module acts as a dicom series to nrrd volume converter.

===Source Code and Documentation===

Source Code: [http://viewvc.na-mic.org/viewcvs.cgi/trunk/Applications/CLI/DicomToNrrdConverter/DicomToNrrdConverter.cxx?view=markup DicomToNrrdConverter.cxx]

XML Description: [http://viewvc.na-mic.org/viewcvs.cgi/trunk/Applications/CLI/DicomToNrrdConverter/DicomToNrrdConverter.xml?view=markup DicomToNrrdConverter.xml]

Test: [http://viewvc.na-mic.org/viewcvs.cgi/trunk/Applications/CLI/DicomToNrrdConverter/Testing/DicomToNrrdConverterTest.cxx?rev=12979&view=log DicomToNrrdConverterTest.cxx]

<pre>
./lib/Slicer3/Plugins/DicomToNrrdConverter --help

USAGE:

./lib/Slicer3/Plugins/DicomToNrrdConverter [--returnparameterfile
<std::string>]
[--processinformationaddress
<std::string>] [--xml] [--echo]
[--useIdentityMeaseurementFrame]
[--writeProtocolGradientsFile]
[--outputVolume <std::string>]
[--outputDirectory <std::string>]
[--inputDicomDirectory
<std::string>] [--] [--version]
[-h]

Where:

--returnparameterfile <std::string>
Filename in which to write simple return parameters (int, float,
int-vector, etc.) as opposed to bulk return parameters (image,
geometry, transform, measurement, table).

--processinformationaddress <std::string>
Address of a structure to store process information (progress, abort,
etc.). (default: 0)

--xml
Produce xml description of command line arguments (default: 0)

--echo
Echo the command line arguments (default: 0)

--useBMatrixGradientDirections
Fill the nhdr header with the gradient directions and bvalues computed
out of the BMatrix. Only changes behavior for Siemens data. (default:
0)

--useIdentityMeaseurementFrame
Adjust all the gradients so that the measurement frame is an identity
matrix. (default: 0)

--writeProtocolGradientsFile
Write the protocol gradients to a file suffixed by '.txt' as they were
specified in the procol by multiplying each diffusion gradient
direction by the measurement frame. This file is for debugging
purposes only, the format is not fixed, and will likely change as
debugging of new dicom formats is necessary. (default: 0)

--smallGradientThreshold <double>
If a gradient magnitude is greater than 0 and less than
smallGradientThreshold, then DicomToNrrdConverter will display an
error message and quit, unless the useBMatrixGradientDirections option
is set. (default: 0.2)

--outputVolume <std::string>
Output filename (.nhdr)

--outputDirectory <std::string>
Directory holding the output NRRD format

--inputDicomDirectory <std::string>
Directory holding Dicom series

--, --ignore_rest
Ignores the rest of the labeled arguments following this flag.

--version
Displays version information and exits.

-h, --help
Displays usage information and exits.

Description: Converts diffusion weighted MR images in dicom series into
Nrrd format for analysis in Slicer. This program has been tested on only
a limited subset of DTI dicom formats available from Siemens, GE, and
Phillips scanners. Work in progress to support dicom multi-frame data.
The program parses dicom header to extract necessary information about
measurement frame, diffusion weighting directions, b-values, etc, and
write out a nrrd image. For non-diffusion weighted dicom images, it
loads in an entire dicom series and writes out a single dicom volume in
a .nhdr/.raw pair.

Author(s): Xiaodong Tao

Acknowledgements: This work is part of the National Alliance for Medical
Image Computing (NAMIC), funded by the National Institutes of Health
through the NIH Roadmap for Medical Research, Grant U54 EB005149.
Additional support for DTI data produced on Philips scanners was
contributed by Vincent Magnotta and Hans Johnson at the University of
Iowa.
</pre>

==More Information==

===Acknowledgement===

Acknowledgements: This work is part of the National Alliance for Medical Image Computing (NAMIC), funded by the National Institutes of Health through the NIH Roadmap for Medical Research, Grant U54 EB005149. Additional support for DTI data produced on Philips scanners was contributed by Vincent Magnotta and Hans Johnson at the University of Iowa.

===References===

More information on Dicom format for diffusion weighted images on [http://www.na-mic.org/Wiki/index.php/NAMIC_Wiki:DTI:DICOM_for_DWI_and_DTI NA-MIC Wiki.]

Modules:DicomToNRRD-3.6

2011-03-14T20:12:45Z

Matsuij: /* Command Line Usage */

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

__NOTOC__
===Module Name===
DWI Dicom To NRRD

{|
|[[Image:DWIDicomToNrrdGUI.png|thumb|280px|Screenshot of the UI]]
|}

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

Type: Command line module

Category: Converters

===Authors, Collaborators & Contact===
* Author: Xiaodong Tao (with contribution from Vince Magnotta and Hans Johnson)
* Contact: taox @ research.ge.com

===Module Description===
This module converts diffusion weighted MR images in dicom series into Nrrd
format for analysis in Slicer. This program has been tested on only
a limited subset of DTI dicom formats available from Siemens, GE,
and Phillips scanners. Work in progress to support dicom multi-frame
data. The program parses dicom header to extract necessary
information about measurement frame, diffusion weighting directions,
b-values, etc, and write out a nrrd image.

== Usage ==

===Examples, Use cases & Tutorials===

This module is typically used as the first step in diffusion weighted image analysis and tractography to convert diffusion weighted images in Dicom format into Nrrd format, which is recognized by Slicer3 as a legitimate diffusion weighted volume.

In the recent development, it is extended to act as a dicom series to nrrd file converted for non-diffusion-weighted images as well.

====Supported DWI formats====
*Philips scanner/software version combinations:
**Achieva 2.1.3.6
**Achieva 2.5.3.0
**Achieva 2.5.3.3
**Achieva 2.6.1.0
**Acheiva 2.6.3.4
**Intera 2.1.3.6
**Intera 2.6.3.5
*Siemens
**Trio B13
**Trio B15
**Trio B17
**Verio B15V
*GE
**SIGNA HDx14.0
**SIGNA HDxt 15.0
**DVMR 20.0M4
**DVMR 20.1

====Command Line Usage====
A command line example for running the module is:

d:\Builds\Slicer3\lib\Slicer3\Plugins\Release\DicomToNrrdConverter.exe --inputDicomDirectory MyDicomDir --outputVolume MyNrrdImage.nhdr

The module is currently set to quit and alert the user of gradients whose magnitudes are unreasonably small (greater than 0 and less than the smallGradientThreshold) via the '''smallGradientThreshold''' flag (default value for smallGradientThreshold: 0.2). This flag was created after encountering gradient vectors whose magnitudes were unusually small in Siemens Trio Tim B13 data due to incorrect metadata for diffusion gradient vector coordinate entries in the DICOM header public element tags.

'''For Siemens data:''' In event of incorrect metadata for diffusion gradient vector coordinates in the DICOM header public element tags, please set the '''useBMatrixGradientDirections''' flag. When the useBMatrixGradientDirections flag is set, gradient direction coordinates and b values are derived from the '''bMatrix''' DICOM header private element tag for each gradient. In Siemens DWI data, the b matrix elements are the product of the b value and unit gradient direction vector (column vector) multiplied by the transpose of the unit gradient direction vector. Therefore, for a given gradient direction, the unit gradient direction vector coordinates are the first column of the unitary matrix from a singular value decomposition of its b matrix, while the b value is the trace of its b matrix.

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

[[Image:DicomToNrrd-IOPanels-3-6.png|thumb|right|280px|Input/Output panels]]
When this module is run from Slicer UI, simply select the directories for '''Input Dicom Data''' and '''Output Directory''', enter the filename (without path name, but '''with''' extension, such as '''mydti.nrrd''') in the '''Output Filename''' field, and press "Apply" button.

The module can also be run from command line to enable batch process. An example command line look like:

d:\Builds\Slicer3\lib\Slicer3\Plugins\Release\DicomToNrrdConverter.exe
--inputDicomDirectory MyDicomDir
--outputDirectory /scratch/Diffusion
--outputVolume MyNrrdImage.nrrd

== Development==

===Dependencies===

This module depends only on the core "Volumes" module of slice for data IO.

===Known Bugs===

===Usability Issues===

Because different vendors used different private tags to store information related to diffusion weighting and documentation on how to interoperate this information is scarce, the current version support diffusion weighted images from GE, Siemens, and Philips scanners. For Siemens, both mosaic and split formats are supported. For Philips, both multi-slice and signal-slice formats are supported.

The current version also support non-diffusion weighted images from any vendors (that GDCM supports), in which case, the module acts as a dicom series to nrrd volume converter.

===Source Code and Documentation===

Source Code: [http://viewvc.na-mic.org/viewcvs.cgi/trunk/Applications/CLI/DicomToNrrdConverter/DicomToNrrdConverter.cxx?view=markup DicomToNrrdConverter.cxx]

XML Description: [http://viewvc.na-mic.org/viewcvs.cgi/trunk/Applications/CLI/DicomToNrrdConverter/DicomToNrrdConverter.xml?view=markup DicomToNrrdConverter.xml]

Test: [http://viewvc.na-mic.org/viewcvs.cgi/trunk/Applications/CLI/DicomToNrrdConverter/Testing/DicomToNrrdConverterTest.cxx?rev=12979&view=log DicomToNrrdConverterTest.cxx]

<pre>
./lib/Slicer3/Plugins/DicomToNrrdConverter --help

USAGE:

./lib/Slicer3/Plugins/DicomToNrrdConverter [--returnparameterfile
<std::string>]
[--processinformationaddress
<std::string>] [--xml] [--echo]
[--useIdentityMeaseurementFrame]
[--writeProtocolGradientsFile]
[--outputVolume <std::string>]
[--outputDirectory <std::string>]
[--inputDicomDirectory
<std::string>] [--] [--version]
[-h]

Where:

--returnparameterfile <std::string>
Filename in which to write simple return parameters (int, float,
int-vector, etc.) as opposed to bulk return parameters (image,
geometry, transform, measurement, table).

--processinformationaddress <std::string>
Address of a structure to store process information (progress, abort,
etc.). (default: 0)

--xml
Produce xml description of command line arguments (default: 0)

--echo
Echo the command line arguments (default: 0)

--useBMatrixGradientDirections
Fill the nhdr header with the gradient directions and bvalues computed
out of the BMatrix. Only changes behavior for Siemens data. (default:
0)

--useIdentityMeaseurementFrame
Adjust all the gradients so that the measurement frame is an identity
matrix. (default: 0)

--writeProtocolGradientsFile
Write the protocol gradients to a file suffixed by '.txt' as they were
specified in the procol by multiplying each diffusion gradient
direction by the measurement frame. This file is for debugging
purposes only, the format is not fixed, and will likely change as
debugging of new dicom formats is necessary. (default: 0)

--smallGradientThreshold <double>
If a gradient magnitude is greater than 0 and less than
smallGradientThreshold, then DicomToNrrdConverter will display an
error message and quit, unless the useBMatrixGradientDirections option
is set. (default: 0.2)

--outputVolume <std::string>
Output filename (.nhdr)

--outputDirectory <std::string>
Directory holding the output NRRD format

--inputDicomDirectory <std::string>
Directory holding Dicom series

--, --ignore_rest
Ignores the rest of the labeled arguments following this flag.

--version
Displays version information and exits.

-h, --help
Displays usage information and exits.

Description: Converts diffusion weighted MR images in dicom series into
Nrrd format for analysis in Slicer. This program has been tested on only
a limited subset of DTI dicom formats available from Siemens, GE, and
Phillips scanners. Work in progress to support dicom multi-frame data.
The program parses dicom header to extract necessary information about
measurement frame, diffusion weighting directions, b-values, etc, and
write out a nrrd image. For non-diffusion weighted dicom images, it
loads in an entire dicom series and writes out a single dicom volume in
a .nhdr/.raw pair.

Author(s): Xiaodong Tao

Acknowledgements: This work is part of the National Alliance for Medical
Image Computing (NAMIC), funded by the National Institutes of Health
through the NIH Roadmap for Medical Research, Grant U54 EB005149.
Additional support for DTI data produced on Philips scanners was
contributed by Vincent Magnotta and Hans Johnson at the University of
Iowa.
</pre>

==More Information==

===Acknowledgement===

Acknowledgements: This work is part of the National Alliance for Medical Image Computing (NAMIC), funded by the National Institutes of Health through the NIH Roadmap for Medical Research, Grant U54 EB005149. Additional support for DTI data produced on Philips scanners was contributed by Vincent Magnotta and Hans Johnson at the University of Iowa.

===References===

More information on Dicom format for diffusion weighted images on [http://www.na-mic.org/Wiki/index.php/NAMIC_Wiki:DTI:DICOM_for_DWI_and_DTI NA-MIC Wiki.]

Modules:DicomToNRRD-3.6

2011-03-14T20:04:38Z

Matsuij: /* Command Line Usage */

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

__NOTOC__
===Module Name===
DWI Dicom To NRRD

{|
|[[Image:DWIDicomToNrrdGUI.png|thumb|280px|Screenshot of the UI]]
|}

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

Type: Command line module

Category: Converters

===Authors, Collaborators & Contact===
* Author: Xiaodong Tao (with contribution from Vince Magnotta and Hans Johnson)
* Contact: taox @ research.ge.com

===Module Description===
This module converts diffusion weighted MR images in dicom series into Nrrd
format for analysis in Slicer. This program has been tested on only
a limited subset of DTI dicom formats available from Siemens, GE,
and Phillips scanners. Work in progress to support dicom multi-frame
data. The program parses dicom header to extract necessary
information about measurement frame, diffusion weighting directions,
b-values, etc, and write out a nrrd image.

== Usage ==

===Examples, Use cases & Tutorials===

This module is typically used as the first step in diffusion weighted image analysis and tractography to convert diffusion weighted images in Dicom format into Nrrd format, which is recognized by Slicer3 as a legitimate diffusion weighted volume.

In the recent development, it is extended to act as a dicom series to nrrd file converted for non-diffusion-weighted images as well.

====Supported DWI formats====
*Philips scanner/software version combinations:
**Achieva 2.1.3.6
**Achieva 2.5.3.0
**Achieva 2.5.3.3
**Achieva 2.6.1.0
**Acheiva 2.6.3.4
**Intera 2.1.3.6
**Intera 2.6.3.5
*Siemens
**Trio B13
**Trio B15
**Trio B17
**Verio B15V
*GE
**SIGNA HDx14.0
**SIGNA HDxt 15.0
**DVMR 20.0M4
**DVMR 20.1

====Command Line Usage====
A command line example for running the module is:

d:\Builds\Slicer3\lib\Slicer3\Plugins\Release\DicomToNrrdConverter.exe --inputDicomDirectory MyDicomDir --outputVolume MyNrrdImage.nhdr

The module is currently set to quit and alert the user of gradients whose magnitudes are unreasonably small (greater than 0 and less than the smallGradientThreshold) via the '''smallGradientThreshold''' flag (default value for smallGradientThreshold: 0.2). This flag was created after encountering gradient vectors whose magnitudes were unusually small in Siemens Trio Tim B13 data due to incorrect metadata for diffusion gradient vector coordinate entries in the DICOM header public element tags.

In event of incorrect metadata for diffusion gradient vector coordinate entries in the DICOM header public element tags in '''Siemens data''', please set the '''useBMatrixGradientDirections''' flag. When the useBMatrixGradientDirections flag is set, gradient direction coordinates and b values are derived from the bMatrix DICOM header private element tag for each gradient. In Siemens DWI data, the b matrix elements are the product of the b value and unit gradient direction (column vector) multiplied by its transpose. Therefore, the gradient direction coordinates and b value of a gradient can be derived from the b matrix elements via singular value decomposition.

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

[[Image:DicomToNrrd-IOPanels-3-6.png|thumb|right|280px|Input/Output panels]]
When this module is run from Slicer UI, simply select the directories for '''Input Dicom Data''' and '''Output Directory''', enter the filename (without path name, but '''with''' extension, such as '''mydti.nrrd''') in the '''Output Filename''' field, and press "Apply" button.

The module can also be run from command line to enable batch process. An example command line look like:

d:\Builds\Slicer3\lib\Slicer3\Plugins\Release\DicomToNrrdConverter.exe
--inputDicomDirectory MyDicomDir
--outputDirectory /scratch/Diffusion
--outputVolume MyNrrdImage.nrrd

== Development==

===Dependencies===

This module depends only on the core "Volumes" module of slice for data IO.

===Known Bugs===

===Usability Issues===

Because different vendors used different private tags to store information related to diffusion weighting and documentation on how to interoperate this information is scarce, the current version support diffusion weighted images from GE, Siemens, and Philips scanners. For Siemens, both mosaic and split formats are supported. For Philips, both multi-slice and signal-slice formats are supported.

The current version also support non-diffusion weighted images from any vendors (that GDCM supports), in which case, the module acts as a dicom series to nrrd volume converter.

===Source Code and Documentation===

Source Code: [http://viewvc.na-mic.org/viewcvs.cgi/trunk/Applications/CLI/DicomToNrrdConverter/DicomToNrrdConverter.cxx?view=markup DicomToNrrdConverter.cxx]

XML Description: [http://viewvc.na-mic.org/viewcvs.cgi/trunk/Applications/CLI/DicomToNrrdConverter/DicomToNrrdConverter.xml?view=markup DicomToNrrdConverter.xml]

Test: [http://viewvc.na-mic.org/viewcvs.cgi/trunk/Applications/CLI/DicomToNrrdConverter/Testing/DicomToNrrdConverterTest.cxx?rev=12979&view=log DicomToNrrdConverterTest.cxx]

<pre>
./lib/Slicer3/Plugins/DicomToNrrdConverter --help

USAGE:

./lib/Slicer3/Plugins/DicomToNrrdConverter [--returnparameterfile
<std::string>]
[--processinformationaddress
<std::string>] [--xml] [--echo]
[--useIdentityMeaseurementFrame]
[--writeProtocolGradientsFile]
[--outputVolume <std::string>]
[--outputDirectory <std::string>]
[--inputDicomDirectory
<std::string>] [--] [--version]
[-h]

Where:

--returnparameterfile <std::string>
Filename in which to write simple return parameters (int, float,
int-vector, etc.) as opposed to bulk return parameters (image,
geometry, transform, measurement, table).

--processinformationaddress <std::string>
Address of a structure to store process information (progress, abort,
etc.). (default: 0)

--xml
Produce xml description of command line arguments (default: 0)

--echo
Echo the command line arguments (default: 0)

--useBMatrixGradientDirections
Fill the nhdr header with the gradient directions and bvalues computed
out of the BMatrix. Only changes behavior for Siemens data. (default:
0)

--useIdentityMeaseurementFrame
Adjust all the gradients so that the measurement frame is an identity
matrix. (default: 0)

--writeProtocolGradientsFile
Write the protocol gradients to a file suffixed by '.txt' as they were
specified in the procol by multiplying each diffusion gradient
direction by the measurement frame. This file is for debugging
purposes only, the format is not fixed, and will likely change as
debugging of new dicom formats is necessary. (default: 0)

--smallGradientThreshold <double>
If a gradient magnitude is greater than 0 and less than
smallGradientThreshold, then DicomToNrrdConverter will display an
error message and quit, unless the useBMatrixGradientDirections option
is set. (default: 0.2)

--outputVolume <std::string>
Output filename (.nhdr)

--outputDirectory <std::string>
Directory holding the output NRRD format

--inputDicomDirectory <std::string>
Directory holding Dicom series

--, --ignore_rest
Ignores the rest of the labeled arguments following this flag.

--version
Displays version information and exits.

-h, --help
Displays usage information and exits.

Description: Converts diffusion weighted MR images in dicom series into
Nrrd format for analysis in Slicer. This program has been tested on only
a limited subset of DTI dicom formats available from Siemens, GE, and
Phillips scanners. Work in progress to support dicom multi-frame data.
The program parses dicom header to extract necessary information about
measurement frame, diffusion weighting directions, b-values, etc, and
write out a nrrd image. For non-diffusion weighted dicom images, it
loads in an entire dicom series and writes out a single dicom volume in
a .nhdr/.raw pair.

Author(s): Xiaodong Tao

Acknowledgements: This work is part of the National Alliance for Medical
Image Computing (NAMIC), funded by the National Institutes of Health
through the NIH Roadmap for Medical Research, Grant U54 EB005149.
Additional support for DTI data produced on Philips scanners was
contributed by Vincent Magnotta and Hans Johnson at the University of
Iowa.
</pre>

==More Information==

===Acknowledgement===

Acknowledgements: This work is part of the National Alliance for Medical Image Computing (NAMIC), funded by the National Institutes of Health through the NIH Roadmap for Medical Research, Grant U54 EB005149. Additional support for DTI data produced on Philips scanners was contributed by Vincent Magnotta and Hans Johnson at the University of Iowa.

===References===

More information on Dicom format for diffusion weighted images on [http://www.na-mic.org/Wiki/index.php/NAMIC_Wiki:DTI:DICOM_for_DWI_and_DTI NA-MIC Wiki.]

Modules:DicomToNRRD-3.6

2011-03-14T19:48:42Z

Matsuij: /* Command Line Usage */

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

__NOTOC__
===Module Name===
DWI Dicom To NRRD

{|
|[[Image:DWIDicomToNrrdGUI.png|thumb|280px|Screenshot of the UI]]
|}

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

Type: Command line module

Category: Converters

===Authors, Collaborators & Contact===
* Author: Xiaodong Tao (with contribution from Vince Magnotta and Hans Johnson)
* Contact: taox @ research.ge.com

===Module Description===
This module converts diffusion weighted MR images in dicom series into Nrrd
format for analysis in Slicer. This program has been tested on only
a limited subset of DTI dicom formats available from Siemens, GE,
and Phillips scanners. Work in progress to support dicom multi-frame
data. The program parses dicom header to extract necessary
information about measurement frame, diffusion weighting directions,
b-values, etc, and write out a nrrd image.

== Usage ==

===Examples, Use cases & Tutorials===

This module is typically used as the first step in diffusion weighted image analysis and tractography to convert diffusion weighted images in Dicom format into Nrrd format, which is recognized by Slicer3 as a legitimate diffusion weighted volume.

In the recent development, it is extended to act as a dicom series to nrrd file converted for non-diffusion-weighted images as well.

====Supported DWI formats====
*Philips scanner/software version combinations:
**Achieva 2.1.3.6
**Achieva 2.5.3.0
**Achieva 2.5.3.3
**Achieva 2.6.1.0
**Acheiva 2.6.3.4
**Intera 2.1.3.6
**Intera 2.6.3.5
*Siemens
**Trio B13
**Trio B15
**Trio B17
**Verio B15V
*GE
**SIGNA HDx14.0
**SIGNA HDxt 15.0
**DVMR 20.0M4
**DVMR 20.1

====Command Line Usage====
A command line example for running the module is:

d:\Builds\Slicer3\lib\Slicer3\Plugins\Release\DicomToNrrdConverter.exe --inputDicomDirectory MyDicomDir --outputVolume MyNrrdImage.nhdr

The module is currently set to quit and alert the user of gradients whose magnitudes are unreasonably small (greater than 0 and less than the smallGradientThreshold) via the smallGradientThreshold flag (default value for smallGradientThreshold: 0.2). This flag was created after encountering gradient vectors whose magnitudes were unusually small in Siemens Trio Tim B13 data due to incorrect metadata diffusion gradient vector coordinate entries in the DICOM header public element tags.

In event of incorrect metadata diffusion gradient vector coordinate entries in the DICOM header public element tags for Siemens data, please set the useBMatrixGradientDirections flag.

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

[[Image:DicomToNrrd-IOPanels-3-6.png|thumb|right|280px|Input/Output panels]]
When this module is run from Slicer UI, simply select the directories for '''Input Dicom Data''' and '''Output Directory''', enter the filename (without path name, but '''with''' extension, such as '''mydti.nrrd''') in the '''Output Filename''' field, and press "Apply" button.

The module can also be run from command line to enable batch process. An example command line look like:

d:\Builds\Slicer3\lib\Slicer3\Plugins\Release\DicomToNrrdConverter.exe
--inputDicomDirectory MyDicomDir
--outputDirectory /scratch/Diffusion
--outputVolume MyNrrdImage.nrrd

== Development==

===Dependencies===

This module depends only on the core "Volumes" module of slice for data IO.

===Known Bugs===

===Usability Issues===

Because different vendors used different private tags to store information related to diffusion weighting and documentation on how to interoperate this information is scarce, the current version support diffusion weighted images from GE, Siemens, and Philips scanners. For Siemens, both mosaic and split formats are supported. For Philips, both multi-slice and signal-slice formats are supported.

The current version also support non-diffusion weighted images from any vendors (that GDCM supports), in which case, the module acts as a dicom series to nrrd volume converter.

===Source Code and Documentation===

Source Code: [http://viewvc.na-mic.org/viewcvs.cgi/trunk/Applications/CLI/DicomToNrrdConverter/DicomToNrrdConverter.cxx?view=markup DicomToNrrdConverter.cxx]

XML Description: [http://viewvc.na-mic.org/viewcvs.cgi/trunk/Applications/CLI/DicomToNrrdConverter/DicomToNrrdConverter.xml?view=markup DicomToNrrdConverter.xml]

Test: [http://viewvc.na-mic.org/viewcvs.cgi/trunk/Applications/CLI/DicomToNrrdConverter/Testing/DicomToNrrdConverterTest.cxx?rev=12979&view=log DicomToNrrdConverterTest.cxx]

<pre>
./lib/Slicer3/Plugins/DicomToNrrdConverter --help

USAGE:

./lib/Slicer3/Plugins/DicomToNrrdConverter [--returnparameterfile
<std::string>]
[--processinformationaddress
<std::string>] [--xml] [--echo]
[--useIdentityMeaseurementFrame]
[--writeProtocolGradientsFile]
[--outputVolume <std::string>]
[--outputDirectory <std::string>]
[--inputDicomDirectory
<std::string>] [--] [--version]
[-h]

Where:

--returnparameterfile <std::string>
Filename in which to write simple return parameters (int, float,
int-vector, etc.) as opposed to bulk return parameters (image,
geometry, transform, measurement, table).

--processinformationaddress <std::string>
Address of a structure to store process information (progress, abort,
etc.). (default: 0)

--xml
Produce xml description of command line arguments (default: 0)

--echo
Echo the command line arguments (default: 0)

--useBMatrixGradientDirections
Fill the nhdr header with the gradient directions and bvalues computed
out of the BMatrix. Only changes behavior for Siemens data. (default:
0)

--useIdentityMeaseurementFrame
Adjust all the gradients so that the measurement frame is an identity
matrix. (default: 0)

--writeProtocolGradientsFile
Write the protocol gradients to a file suffixed by '.txt' as they were
specified in the procol by multiplying each diffusion gradient
direction by the measurement frame. This file is for debugging
purposes only, the format is not fixed, and will likely change as
debugging of new dicom formats is necessary. (default: 0)

--smallGradientThreshold <double>
If a gradient magnitude is greater than 0 and less than
smallGradientThreshold, then DicomToNrrdConverter will display an
error message and quit, unless the useBMatrixGradientDirections option
is set. (default: 0.2)

--outputVolume <std::string>
Output filename (.nhdr)

--outputDirectory <std::string>
Directory holding the output NRRD format

--inputDicomDirectory <std::string>
Directory holding Dicom series

--, --ignore_rest
Ignores the rest of the labeled arguments following this flag.

--version
Displays version information and exits.

-h, --help
Displays usage information and exits.

Description: Converts diffusion weighted MR images in dicom series into
Nrrd format for analysis in Slicer. This program has been tested on only
a limited subset of DTI dicom formats available from Siemens, GE, and
Phillips scanners. Work in progress to support dicom multi-frame data.
The program parses dicom header to extract necessary information about
measurement frame, diffusion weighting directions, b-values, etc, and
write out a nrrd image. For non-diffusion weighted dicom images, it
loads in an entire dicom series and writes out a single dicom volume in
a .nhdr/.raw pair.

Author(s): Xiaodong Tao

Acknowledgements: This work is part of the National Alliance for Medical
Image Computing (NAMIC), funded by the National Institutes of Health
through the NIH Roadmap for Medical Research, Grant U54 EB005149.
Additional support for DTI data produced on Philips scanners was
contributed by Vincent Magnotta and Hans Johnson at the University of
Iowa.
</pre>

==More Information==

===Acknowledgement===

Acknowledgements: This work is part of the National Alliance for Medical Image Computing (NAMIC), funded by the National Institutes of Health through the NIH Roadmap for Medical Research, Grant U54 EB005149. Additional support for DTI data produced on Philips scanners was contributed by Vincent Magnotta and Hans Johnson at the University of Iowa.

===References===

More information on Dicom format for diffusion weighted images on [http://www.na-mic.org/Wiki/index.php/NAMIC_Wiki:DTI:DICOM_for_DWI_and_DTI NA-MIC Wiki.]

Modules:DicomToNRRD-3.6

2011-03-14T19:44:32Z

Matsuij: /* Command Line Usage */

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

__NOTOC__
===Module Name===
DWI Dicom To NRRD

{|
|[[Image:DWIDicomToNrrdGUI.png|thumb|280px|Screenshot of the UI]]
|}

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

Type: Command line module

Category: Converters

===Authors, Collaborators & Contact===
* Author: Xiaodong Tao (with contribution from Vince Magnotta and Hans Johnson)
* Contact: taox @ research.ge.com

===Module Description===
This module converts diffusion weighted MR images in dicom series into Nrrd
format for analysis in Slicer. This program has been tested on only
a limited subset of DTI dicom formats available from Siemens, GE,
and Phillips scanners. Work in progress to support dicom multi-frame
data. The program parses dicom header to extract necessary
information about measurement frame, diffusion weighting directions,
b-values, etc, and write out a nrrd image.

== Usage ==

===Examples, Use cases & Tutorials===

This module is typically used as the first step in diffusion weighted image analysis and tractography to convert diffusion weighted images in Dicom format into Nrrd format, which is recognized by Slicer3 as a legitimate diffusion weighted volume.

In the recent development, it is extended to act as a dicom series to nrrd file converted for non-diffusion-weighted images as well.

====Supported DWI formats====
*Philips scanner/software version combinations:
**Achieva 2.1.3.6
**Achieva 2.5.3.0
**Achieva 2.5.3.3
**Achieva 2.6.1.0
**Acheiva 2.6.3.4
**Intera 2.1.3.6
**Intera 2.6.3.5
*Siemens
**Trio B13
**Trio B15
**Trio B17
**Verio B15V
*GE
**SIGNA HDx14.0
**SIGNA HDxt 15.0
**DVMR 20.0M4
**DVMR 20.1

====Command Line Usage====
A command line example for running the module is:

d:\Builds\Slicer3\lib\Slicer3\Plugins\Release\DicomToNrrdConverter.exe --inputDicomDirectory MyDicomDir --outputVolume MyNrrdImage.nhdr

The module is currently set to quit and alert the user of gradients whose magnitudes are unreasonably small (greater than 0 and less than the smallGradientThreshold) via the smallGradientThreshold flag (default value for smallGradientThreshold: 0.2). This flag was created after encountering gradient

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

[[Image:DicomToNrrd-IOPanels-3-6.png|thumb|right|280px|Input/Output panels]]
When this module is run from Slicer UI, simply select the directories for '''Input Dicom Data''' and '''Output Directory''', enter the filename (without path name, but '''with''' extension, such as '''mydti.nrrd''') in the '''Output Filename''' field, and press "Apply" button.

The module can also be run from command line to enable batch process. An example command line look like:

d:\Builds\Slicer3\lib\Slicer3\Plugins\Release\DicomToNrrdConverter.exe
--inputDicomDirectory MyDicomDir
--outputDirectory /scratch/Diffusion
--outputVolume MyNrrdImage.nrrd

== Development==

===Dependencies===

This module depends only on the core "Volumes" module of slice for data IO.

===Known Bugs===

===Usability Issues===

Because different vendors used different private tags to store information related to diffusion weighting and documentation on how to interoperate this information is scarce, the current version support diffusion weighted images from GE, Siemens, and Philips scanners. For Siemens, both mosaic and split formats are supported. For Philips, both multi-slice and signal-slice formats are supported.

The current version also support non-diffusion weighted images from any vendors (that GDCM supports), in which case, the module acts as a dicom series to nrrd volume converter.

===Source Code and Documentation===

Source Code: [http://viewvc.na-mic.org/viewcvs.cgi/trunk/Applications/CLI/DicomToNrrdConverter/DicomToNrrdConverter.cxx?view=markup DicomToNrrdConverter.cxx]

XML Description: [http://viewvc.na-mic.org/viewcvs.cgi/trunk/Applications/CLI/DicomToNrrdConverter/DicomToNrrdConverter.xml?view=markup DicomToNrrdConverter.xml]

Test: [http://viewvc.na-mic.org/viewcvs.cgi/trunk/Applications/CLI/DicomToNrrdConverter/Testing/DicomToNrrdConverterTest.cxx?rev=12979&view=log DicomToNrrdConverterTest.cxx]

<pre>
./lib/Slicer3/Plugins/DicomToNrrdConverter --help

USAGE:

./lib/Slicer3/Plugins/DicomToNrrdConverter [--returnparameterfile
<std::string>]
[--processinformationaddress
<std::string>] [--xml] [--echo]
[--useIdentityMeaseurementFrame]
[--writeProtocolGradientsFile]
[--outputVolume <std::string>]
[--outputDirectory <std::string>]
[--inputDicomDirectory
<std::string>] [--] [--version]
[-h]

Where:

--returnparameterfile <std::string>
Filename in which to write simple return parameters (int, float,
int-vector, etc.) as opposed to bulk return parameters (image,
geometry, transform, measurement, table).

--processinformationaddress <std::string>
Address of a structure to store process information (progress, abort,
etc.). (default: 0)

--xml
Produce xml description of command line arguments (default: 0)

--echo
Echo the command line arguments (default: 0)

--useBMatrixGradientDirections
Fill the nhdr header with the gradient directions and bvalues computed
out of the BMatrix. Only changes behavior for Siemens data. (default:
0)

--useIdentityMeaseurementFrame
Adjust all the gradients so that the measurement frame is an identity
matrix. (default: 0)

--writeProtocolGradientsFile
Write the protocol gradients to a file suffixed by '.txt' as they were
specified in the procol by multiplying each diffusion gradient
direction by the measurement frame. This file is for debugging
purposes only, the format is not fixed, and will likely change as
debugging of new dicom formats is necessary. (default: 0)

--smallGradientThreshold <double>
If a gradient magnitude is greater than 0 and less than
smallGradientThreshold, then DicomToNrrdConverter will display an
error message and quit, unless the useBMatrixGradientDirections option
is set. (default: 0.2)

--outputVolume <std::string>
Output filename (.nhdr)

--outputDirectory <std::string>
Directory holding the output NRRD format

--inputDicomDirectory <std::string>
Directory holding Dicom series

--, --ignore_rest
Ignores the rest of the labeled arguments following this flag.

--version
Displays version information and exits.

-h, --help
Displays usage information and exits.

Description: Converts diffusion weighted MR images in dicom series into
Nrrd format for analysis in Slicer. This program has been tested on only
a limited subset of DTI dicom formats available from Siemens, GE, and
Phillips scanners. Work in progress to support dicom multi-frame data.
The program parses dicom header to extract necessary information about
measurement frame, diffusion weighting directions, b-values, etc, and
write out a nrrd image. For non-diffusion weighted dicom images, it
loads in an entire dicom series and writes out a single dicom volume in
a .nhdr/.raw pair.

Author(s): Xiaodong Tao

Acknowledgements: This work is part of the National Alliance for Medical
Image Computing (NAMIC), funded by the National Institutes of Health
through the NIH Roadmap for Medical Research, Grant U54 EB005149.
Additional support for DTI data produced on Philips scanners was
contributed by Vincent Magnotta and Hans Johnson at the University of
Iowa.
</pre>

==More Information==

===Acknowledgement===

Acknowledgements: This work is part of the National Alliance for Medical Image Computing (NAMIC), funded by the National Institutes of Health through the NIH Roadmap for Medical Research, Grant U54 EB005149. Additional support for DTI data produced on Philips scanners was contributed by Vincent Magnotta and Hans Johnson at the University of Iowa.

===References===

More information on Dicom format for diffusion weighted images on [http://www.na-mic.org/Wiki/index.php/NAMIC_Wiki:DTI:DICOM_for_DWI_and_DTI NA-MIC Wiki.]

Modules:DicomToNRRD-3.6

2011-03-14T19:31:48Z

Matsuij: /* Source Code and Documentation */

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

__NOTOC__
===Module Name===
DWI Dicom To NRRD

{|
|[[Image:DWIDicomToNrrdGUI.png|thumb|280px|Screenshot of the UI]]
|}

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

Type: Command line module

Category: Converters

===Authors, Collaborators & Contact===
* Author: Xiaodong Tao (with contribution from Vince Magnotta and Hans Johnson)
* Contact: taox @ research.ge.com

===Module Description===
This module converts diffusion weighted MR images in dicom series into Nrrd
format for analysis in Slicer. This program has been tested on only
a limited subset of DTI dicom formats available from Siemens, GE,
and Phillips scanners. Work in progress to support dicom multi-frame
data. The program parses dicom header to extract necessary
information about measurement frame, diffusion weighting directions,
b-values, etc, and write out a nrrd image.

== Usage ==

===Examples, Use cases & Tutorials===

This module is typically used as the first step in diffusion weighted image analysis and tractography to convert diffusion weighted images in Dicom format into Nrrd format, which is recognized by Slicer3 as a legitimate diffusion weighted volume.

In the recent development, it is extended to act as a dicom series to nrrd file converted for non-diffusion-weighted images as well.

====Supported DWI formats====
*Philips scanner/software version combinations:
**Achieva 2.1.3.6
**Achieva 2.5.3.0
**Achieva 2.5.3.3
**Achieva 2.6.1.0
**Acheiva 2.6.3.4
**Intera 2.1.3.6
**Intera 2.6.3.5
*Siemens
**Trio B13
**Trio B15
**Trio B17
**Verio B15V
*GE
**SIGNA HDx14.0
**SIGNA HDxt 15.0
**DVMR 20.0M4
**DVMR 20.1

====Command Line Usage====
A command line example for running the module is:

d:\Builds\Slicer3\lib\Slicer3\Plugins\Release\DicomToNrrdConverter.exe --inputDicomDirectory MyDicomDir --outputVolume MyNrrdImage.nhdr

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

[[Image:DicomToNrrd-IOPanels-3-6.png|thumb|right|280px|Input/Output panels]]
When this module is run from Slicer UI, simply select the directories for '''Input Dicom Data''' and '''Output Directory''', enter the filename (without path name, but '''with''' extension, such as '''mydti.nrrd''') in the '''Output Filename''' field, and press "Apply" button.

The module can also be run from command line to enable batch process. An example command line look like:

d:\Builds\Slicer3\lib\Slicer3\Plugins\Release\DicomToNrrdConverter.exe
--inputDicomDirectory MyDicomDir
--outputDirectory /scratch/Diffusion
--outputVolume MyNrrdImage.nrrd

== Development==

===Dependencies===

This module depends only on the core "Volumes" module of slice for data IO.

===Known Bugs===

===Usability Issues===

Because different vendors used different private tags to store information related to diffusion weighting and documentation on how to interoperate this information is scarce, the current version support diffusion weighted images from GE, Siemens, and Philips scanners. For Siemens, both mosaic and split formats are supported. For Philips, both multi-slice and signal-slice formats are supported.

The current version also support non-diffusion weighted images from any vendors (that GDCM supports), in which case, the module acts as a dicom series to nrrd volume converter.

===Source Code and Documentation===

Source Code: [http://viewvc.na-mic.org/viewcvs.cgi/trunk/Applications/CLI/DicomToNrrdConverter/DicomToNrrdConverter.cxx?view=markup DicomToNrrdConverter.cxx]

XML Description: [http://viewvc.na-mic.org/viewcvs.cgi/trunk/Applications/CLI/DicomToNrrdConverter/DicomToNrrdConverter.xml?view=markup DicomToNrrdConverter.xml]

Test: [http://viewvc.na-mic.org/viewcvs.cgi/trunk/Applications/CLI/DicomToNrrdConverter/Testing/DicomToNrrdConverterTest.cxx?rev=12979&view=log DicomToNrrdConverterTest.cxx]

<pre>
./lib/Slicer3/Plugins/DicomToNrrdConverter --help

USAGE:

./lib/Slicer3/Plugins/DicomToNrrdConverter [--returnparameterfile
<std::string>]
[--processinformationaddress
<std::string>] [--xml] [--echo]
[--useIdentityMeaseurementFrame]
[--writeProtocolGradientsFile]
[--outputVolume <std::string>]
[--outputDirectory <std::string>]
[--inputDicomDirectory
<std::string>] [--] [--version]
[-h]

Where:

--returnparameterfile <std::string>
Filename in which to write simple return parameters (int, float,
int-vector, etc.) as opposed to bulk return parameters (image,
geometry, transform, measurement, table).

--processinformationaddress <std::string>
Address of a structure to store process information (progress, abort,
etc.). (default: 0)

--xml
Produce xml description of command line arguments (default: 0)

--echo
Echo the command line arguments (default: 0)

--useBMatrixGradientDirections
Fill the nhdr header with the gradient directions and bvalues computed
out of the BMatrix. Only changes behavior for Siemens data. (default:
0)

--useIdentityMeaseurementFrame
Adjust all the gradients so that the measurement frame is an identity
matrix. (default: 0)

--writeProtocolGradientsFile
Write the protocol gradients to a file suffixed by '.txt' as they were
specified in the procol by multiplying each diffusion gradient
direction by the measurement frame. This file is for debugging
purposes only, the format is not fixed, and will likely change as
debugging of new dicom formats is necessary. (default: 0)

--smallGradientThreshold <double>
If a gradient magnitude is greater than 0 and less than
smallGradientThreshold, then DicomToNrrdConverter will display an
error message and quit, unless the useBMatrixGradientDirections option
is set. (default: 0.2)

--outputVolume <std::string>
Output filename (.nhdr)

--outputDirectory <std::string>
Directory holding the output NRRD format

--inputDicomDirectory <std::string>
Directory holding Dicom series

--, --ignore_rest
Ignores the rest of the labeled arguments following this flag.

--version
Displays version information and exits.

-h, --help
Displays usage information and exits.

Description: Converts diffusion weighted MR images in dicom series into
Nrrd format for analysis in Slicer. This program has been tested on only
a limited subset of DTI dicom formats available from Siemens, GE, and
Phillips scanners. Work in progress to support dicom multi-frame data.
The program parses dicom header to extract necessary information about
measurement frame, diffusion weighting directions, b-values, etc, and
write out a nrrd image. For non-diffusion weighted dicom images, it
loads in an entire dicom series and writes out a single dicom volume in
a .nhdr/.raw pair.

Author(s): Xiaodong Tao

Acknowledgements: This work is part of the National Alliance for Medical
Image Computing (NAMIC), funded by the National Institutes of Health
through the NIH Roadmap for Medical Research, Grant U54 EB005149.
Additional support for DTI data produced on Philips scanners was
contributed by Vincent Magnotta and Hans Johnson at the University of
Iowa.
</pre>

==More Information==

===Acknowledgement===

Acknowledgements: This work is part of the National Alliance for Medical Image Computing (NAMIC), funded by the National Institutes of Health through the NIH Roadmap for Medical Research, Grant U54 EB005149. Additional support for DTI data produced on Philips scanners was contributed by Vincent Magnotta and Hans Johnson at the University of Iowa.

===References===

More information on Dicom format for diffusion weighted images on [http://www.na-mic.org/Wiki/index.php/NAMIC_Wiki:DTI:DICOM_for_DWI_and_DTI NA-MIC Wiki.]

Modules:BRAINSFit

2011-01-13T20:51:53Z

Matsuij: /* Use Cases, Examples */

[[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://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.

Modules:BRAINSFit

2011-01-13T20:50:31Z

Matsuij: /* Use Cases, Examples */

[[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://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 useCenterOfHead. 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.

Modules:BRAINSFit

2011-01-13T20:06:52Z

Matsuij: /* Use Cases, Examples */

[[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://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 useCenterOfHead, which detects the center of head even with varying amounts of neck or shoulders present.
<pre>
--initializeTransformMode useCenterOfHead \
</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 useCenterOfHead \
--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 useCenterOfHead. 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.

GTRACT V4

2010-12-21T06:20:03Z

Matsuij: /* Anatomical B-Spline */

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

<pre>
DicomToNrrdConverter --inputDicomDirectory DICOM_directory_name --outputVolume NRRD_file_name.nrrd
</pre>

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 ==
The following are links to the full documentation of GTRACT's programs. The same documentation can be accessed on the command line using the following:

<pre>
${GTRACT_prog_name} --help
</pre>

* [[extractNrrdVectorIndex|extractNrrdVectorIndex Documentation]]
* [[gtractAnisotropyMap|gtractAnisotropyMap Documentation]]
* [[gtractAverageBvalues|gtractAverageBvalues Documentation]]
* [[gtractClipAnisotropy|gtractClipAnisotropy Documentation]]
* [[gtractCoRegAnatomy|gtractCoRegAnatomy Documentation]]
* [[gtractConcatDwi|gtractConcatDwi Documentation]]
* [[gtractCopyImageOrientation|gtractCopyImageOrientation Documentation]]
* [[gtractCoregBvalues|gtractCoregBvalues Documentation]]
* [[gtractCreateGuideFiber|gtractCreateGuideFiber Documentation]]
* [[gtractFiberTracking|gtractFiberTracking Documentation]]
* [[gtractResampleAnisotropy|gtractResampleAnisotropy Documentation]]
* [[gtractResampleB0|gtractResampleB0 Documentation]]
* [[gtractTensor|gtractTensor Documentation]]
* [[gtractInvertRigidTransform|gtractInvertRigidTransform Documentation]]
* [[gtractInvertBSplineTransform|gtractInvertBSplineTransform Documentation]]
* [[gtractResampleCodeImage|gtractResampleCodeImage Documentation]]
* [[gtractFastMarchingTracking|gtractFastMarchingTracking Documentation]]
* [[gtractCostFastMarching|gtractCostFastMarching 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-registration 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 adjust 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 \
--outputVolume outputImage.nhdr

== 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 ==
Anisotropy mapping can be used to generate the following diffusion tensor indices:
* Fractional Anisotropy (FA)
* Relative Anisotropy (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]].

'''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 arguments for [[gtractCopyImageOrientation]] 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 is the complete set of parameters for [[gtractCoRegAnatomy]].

'''Example'''
% gtractCoRegAnatomy --inputVolume DWI_coreg.nhdr --transformType Rigid \
--vectorIndex 0 --inputAnatomicalVolume T1_ACPC_Axial.nhdr \
--outputTransformName ACPC_rigid.mat --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 that is deformed. The B-Spline registration 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 '''gtractCoRegAnatomy''' performs this registration step and a detailed list of parameters can be found here, [[gtractCoRegAnatomy]]

'''Example:'''

% gtractCoRegAnatomy --inputVolume DWI_coreg.nhdr --transformType Bspline \
--vectorIndex 0 --inputRigidTransform ACPC_rigid.mat --inputAnatomicalVolume T1_ACPC_Axial.nhdr \
--outputTransformName ACPC_bspline.mat --numberOfIterations 1000

{|
| 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]] 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 using the gtractInvertBspline. The X, Y and Z grids specify the grid utilized to sample the B-Spline transform. The parameters for [[gtractInvertBSplineTransform]] 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 susceptibility artifacts.

'''Example'''
% gtractInvertBSplineTransform --inputReferenceVolume T1_ACPC.nhdr --inputTransform ACPC_bspline.xfm \
--outputTransform ACPC_Inverse_Bspline.xfm

===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]] - Resamples a mask or label - Image pixel type is signed short and nearest neighbor interpolation is used

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

* [[gtractResampleB0]] - Resamples the B0 image - Image pixel type is signed short and linear interpolation is used

'''Example:'''
% gtractResampleB0 --inputVolume DWI_Coreg.nhdr --inputAnatomicalVolume T1_ACPC.nhdr \
--inputTransform ACPC_Rigid.txt --vectorIndex 0 \
--transformType Rigid --outputVolume B0_ACPC_rigid.nii.gz

* [[gtractResampleAnisotropy]] - Resamples an anisotropy map - Image pixel type is float and linear interpolation is used

'''Example:'''
% gtractResampleAnisotropy --inputAnisotropyVolume FA.nhdr --inputAnatomicalVolume T1_ACPC.nhdr \
--inputTransform ACPC_Rigid.txt --vectorIndex 0 \
--transformType Rigid --outputVolume FA_ACPC_rigid.nii.gz

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.

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:

# Free Tracking
# Streamlines Tracking
# Graph Search Tracking
# Guided 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 the Tensor at each point along the fiber tract. This can then be used to be rendered as glyphs in Slicer3 and can be used to define several 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 primary 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 anisotropy, 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 [[gtractFiberTracking]] can be obtained using the '--help' option.

'''Example:'''
% gtractFiberTracking --inputTensorVolume Tensor.nhdr \
--inputAnisotropyVolume FA.nhdr \
--trackingMethod Free \
--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 primary 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''': Anisotropy 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 arguments for [[gtractFiberTracking]] are available with the '--help' option at the command line.

'''Example:'''
% gtractFiberTracking --inputTensorVolume Tensor.nhdr \
--inputAnisotropyVolume FA.nhdr \
--trackingMethod Streamline \
--inputStartingSeedsLabelMapVolume startingSeedsLabelMap.nhdr \
--startingSeedsLabel 1 \
--inputEndingSeedsLabelMapVolume endingSeedsLabelMap.nhdr \
--endingSeedsLabel 2 \
--curvatureThreshold 60 \
--outputTract streamlineTracking.vtk

===Graph Search Tracking===
The Graph Search 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-ambiguous regions and utilizes branching and a graph search algorithm in ambiguous regions. Ambiguous tracking regions are defined based on two criteria:

*'''Branching AI Threshold''': Anisotropy 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 secondary 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 algorithm 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 arguments for [[gtractFiberTracking]] can be obtained using the '--help' option from the command line.

'''Example:'''
% gtractFiberTracking --inputTensorVolume Tensor.nhdr \
--inputAnisotropyVolume FA.nhdr \
--trackingMethod GraphSearch \
--inputStartingSeedsLabelMapVolume startingSeedsLabelMap.nhdr \
--startingSeedsLabel 1 \
--inputEndingSeedsLabelMapVolume endingSeedsLabelMap.nhdr \
--endingSeedsLabel 2 \
--inputTract guideFiber.vtk \
--curvatureThreshold 60 \
--branchingThreshold 0.20 \
--maximumBranchPoints 5 \
--branchingAngle 45.0 \
--outputTract graphSearchTracking.vtk

===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]] 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 [[gtractFiberTracking]] uses this algorithm. The user must specify the guide fiber when running this program.

'''Example:'''
% gtractFiberTracking --inputTensorVolume Tensor.nhdr \
--inputAnisotropyVolume FA.nhdr \
--inputStartingSeedsLabelMapVolume --startingSeed.nhdr \
--startingSeedsLabel 1 \
--inputEndingSeedsLabelMapVolume --endingSeed.nhdr \
--endingSeedsLable 2 \
--inputTract guide.vtk \
--trackingMethod Guided \
--guidedCurvatureThreshold 30.0 \
--maximumGuideDistance 12.0 \
--outputTract guidedTracking.vtk

===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]] 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 speed 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]] 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-12-21T06:06:45Z

Matsuij: /* Fiber Tracking */

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

<pre>
DicomToNrrdConverter --inputDicomDirectory DICOM_directory_name --outputVolume NRRD_file_name.nrrd
</pre>

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 ==
The following are links to the full documentation of GTRACT's programs. The same documentation can be accessed on the command line using the following:

<pre>
${GTRACT_prog_name} --help
</pre>

* [[extractNrrdVectorIndex|extractNrrdVectorIndex Documentation]]
* [[gtractAnisotropyMap|gtractAnisotropyMap Documentation]]
* [[gtractAverageBvalues|gtractAverageBvalues Documentation]]
* [[gtractClipAnisotropy|gtractClipAnisotropy Documentation]]
* [[gtractCoRegAnatomy|gtractCoRegAnatomy Documentation]]
* [[gtractConcatDwi|gtractConcatDwi Documentation]]
* [[gtractCopyImageOrientation|gtractCopyImageOrientation Documentation]]
* [[gtractCoregBvalues|gtractCoregBvalues Documentation]]
* [[gtractCreateGuideFiber|gtractCreateGuideFiber Documentation]]
* [[gtractFiberTracking|gtractFiberTracking Documentation]]
* [[gtractResampleAnisotropy|gtractResampleAnisotropy Documentation]]
* [[gtractResampleB0|gtractResampleB0 Documentation]]
* [[gtractTensor|gtractTensor Documentation]]
* [[gtractInvertRigidTransform|gtractInvertRigidTransform Documentation]]
* [[gtractInvertBSplineTransform|gtractInvertBSplineTransform Documentation]]
* [[gtractResampleCodeImage|gtractResampleCodeImage Documentation]]
* [[gtractFastMarchingTracking|gtractFastMarchingTracking Documentation]]
* [[gtractCostFastMarching|gtractCostFastMarching 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-registration 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 adjust 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 \
--outputVolume outputImage.nhdr

== 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 ==
Anisotropy mapping can be used to generate the following diffusion tensor indices:
* Fractional Anisotropy (FA)
* Relative Anisotropy (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]].

'''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 arguments for [[gtractCopyImageOrientation]] 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 is the complete set of parameters for [[gtractCoRegAnatomy]].

'''Example'''
% gtractCoRegAnatomy --inputVolume DWI_coreg.nhdr --transformType Rigid \
--vectorIndex 0 --inputAnatomicalVolume T1_ACPC_Axial.nhdr \
--outputTransformName ACPC_rigid.mat --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 that is deformed. The B-Spline registration 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 be found here, [[gtractCoRegAnatomy]]

'''Example:'''

% gtractCoRegAnatomy --inputVolume DWI_coreg.nhdr --transformType Bspline \
--vectorIndex 0 --inputRigidTransform ACPC_rigid.mat --inputAnatomicalVolume T1_ACPC_Axial.nhdr \
--outputTransformName ACPC_bspline.mat --numberOfIterations 1000

{|
| 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]] 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 using the gtractInvertBspline. The X, Y and Z grids specify the grid utilized to sample the B-Spline transform. The parameters for [[gtractInvertBSplineTransform]] 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 susceptibility artifacts.

'''Example'''
% gtractInvertBSplineTransform --inputReferenceVolume T1_ACPC.nhdr --inputTransform ACPC_bspline.xfm \
--outputTransform ACPC_Inverse_Bspline.xfm

===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]] - Resamples a mask or label - Image pixel type is signed short and nearest neighbor interpolation is used

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

* [[gtractResampleB0]] - Resamples the B0 image - Image pixel type is signed short and linear interpolation is used

'''Example:'''
% gtractResampleB0 --inputVolume DWI_Coreg.nhdr --inputAnatomicalVolume T1_ACPC.nhdr \
--inputTransform ACPC_Rigid.txt --vectorIndex 0 \
--transformType Rigid --outputVolume B0_ACPC_rigid.nii.gz

* [[gtractResampleAnisotropy]] - Resamples an anisotropy map - Image pixel type is float and linear interpolation is used

'''Example:'''
% gtractResampleAnisotropy --inputAnisotropyVolume FA.nhdr --inputAnatomicalVolume T1_ACPC.nhdr \
--inputTransform ACPC_Rigid.txt --vectorIndex 0 \
--transformType Rigid --outputVolume FA_ACPC_rigid.nii.gz

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.

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:

# Free Tracking
# Streamlines Tracking
# Graph Search Tracking
# Guided 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 the Tensor at each point along the fiber tract. This can then be used to be rendered as glyphs in Slicer3 and can be used to define several 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 primary 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 anisotropy, 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 [[gtractFiberTracking]] can be obtained using the '--help' option.

'''Example:'''
% gtractFiberTracking --inputTensorVolume Tensor.nhdr \
--inputAnisotropyVolume FA.nhdr \
--trackingMethod Free \
--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 primary 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''': Anisotropy 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 arguments for [[gtractFiberTracking]] are available with the '--help' option at the command line.

'''Example:'''
% gtractFiberTracking --inputTensorVolume Tensor.nhdr \
--inputAnisotropyVolume FA.nhdr \
--trackingMethod Streamline \
--inputStartingSeedsLabelMapVolume startingSeedsLabelMap.nhdr \
--startingSeedsLabel 1 \
--inputEndingSeedsLabelMapVolume endingSeedsLabelMap.nhdr \
--endingSeedsLabel 2 \
--curvatureThreshold 60 \
--outputTract streamlineTracking.vtk

===Graph Search Tracking===
The Graph Search 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-ambiguous regions and utilizes branching and a graph search algorithm in ambiguous regions. Ambiguous tracking regions are defined based on two criteria:

*'''Branching AI Threshold''': Anisotropy 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 secondary 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 algorithm 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 arguments for [[gtractFiberTracking]] can be obtained using the '--help' option from the command line.

'''Example:'''
% gtractFiberTracking --inputTensorVolume Tensor.nhdr \
--inputAnisotropyVolume FA.nhdr \
--trackingMethod GraphSearch \
--inputStartingSeedsLabelMapVolume startingSeedsLabelMap.nhdr \
--startingSeedsLabel 1 \
--inputEndingSeedsLabelMapVolume endingSeedsLabelMap.nhdr \
--endingSeedsLabel 2 \
--inputTract guideFiber.vtk \
--curvatureThreshold 60 \
--branchingThreshold 0.20 \
--maximumBranchPoints 5 \
--branchingAngle 45.0 \
--outputTract graphSearchTracking.vtk

===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]] 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 [[gtractFiberTracking]] uses this algorithm. The user must specify the guide fiber when running this program.

'''Example:'''
% gtractFiberTracking --inputTensorVolume Tensor.nhdr \
--inputAnisotropyVolume FA.nhdr \
--inputStartingSeedsLabelMapVolume --startingSeed.nhdr \
--startingSeedsLabel 1 \
--inputEndingSeedsLabelMapVolume --endingSeed.nhdr \
--endingSeedsLable 2 \
--inputTract guide.vtk \
--trackingMethod Guided \
--guidedCurvatureThreshold 30.0 \
--maximumGuideDistance 12.0 \
--outputTract guidedTracking.vtk

===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]] 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 speed 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]] 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-12-21T05:51:40Z

Matsuij: /* Resampling Images */

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

<pre>
DicomToNrrdConverter --inputDicomDirectory DICOM_directory_name --outputVolume NRRD_file_name.nrrd
</pre>

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 ==
The following are links to the full documentation of GTRACT's programs. The same documentation can be accessed on the command line using the following:

<pre>
${GTRACT_prog_name} --help
</pre>

* [[extractNrrdVectorIndex|extractNrrdVectorIndex Documentation]]
* [[gtractAnisotropyMap|gtractAnisotropyMap Documentation]]
* [[gtractAverageBvalues|gtractAverageBvalues Documentation]]
* [[gtractClipAnisotropy|gtractClipAnisotropy Documentation]]
* [[gtractCoRegAnatomy|gtractCoRegAnatomy Documentation]]
* [[gtractConcatDwi|gtractConcatDwi Documentation]]
* [[gtractCopyImageOrientation|gtractCopyImageOrientation Documentation]]
* [[gtractCoregBvalues|gtractCoregBvalues Documentation]]
* [[gtractCreateGuideFiber|gtractCreateGuideFiber Documentation]]
* [[gtractFiberTracking|gtractFiberTracking Documentation]]
* [[gtractResampleAnisotropy|gtractResampleAnisotropy Documentation]]
* [[gtractResampleB0|gtractResampleB0 Documentation]]
* [[gtractTensor|gtractTensor Documentation]]
* [[gtractInvertRigidTransform|gtractInvertRigidTransform Documentation]]
* [[gtractInvertBSplineTransform|gtractInvertBSplineTransform Documentation]]
* [[gtractResampleCodeImage|gtractResampleCodeImage Documentation]]
* [[gtractFastMarchingTracking|gtractFastMarchingTracking Documentation]]
* [[gtractCostFastMarching|gtractCostFastMarching 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-registration 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 adjust 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 \
--outputVolume outputImage.nhdr

== 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 ==
Anisotropy mapping can be used to generate the following diffusion tensor indices:
* Fractional Anisotropy (FA)
* Relative Anisotropy (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]].

'''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 arguments for [[gtractCopyImageOrientation]] 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 is the complete set of parameters for [[gtractCoRegAnatomy]].

'''Example'''
% gtractCoRegAnatomy --inputVolume DWI_coreg.nhdr --transformType Rigid \
--vectorIndex 0 --inputAnatomicalVolume T1_ACPC_Axial.nhdr \
--outputTransformName ACPC_rigid.mat --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 that is deformed. The B-Spline registration 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 be found here, [[gtractCoRegAnatomy]]

'''Example:'''

% gtractCoRegAnatomy --inputVolume DWI_coreg.nhdr --transformType Bspline \
--vectorIndex 0 --inputRigidTransform ACPC_rigid.mat --inputAnatomicalVolume T1_ACPC_Axial.nhdr \
--outputTransformName ACPC_bspline.mat --numberOfIterations 1000

{|
| 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]] 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 using the gtractInvertBspline. The X, Y and Z grids specify the grid utilized to sample the B-Spline transform. The parameters for [[gtractInvertBSplineTransform]] 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 susceptibility artifacts.

'''Example'''
% gtractInvertBSplineTransform --inputReferenceVolume T1_ACPC.nhdr --inputTransform ACPC_bspline.xfm \
--outputTransform ACPC_Inverse_Bspline.xfm

===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]] - Resamples a mask or label - Image pixel type is signed short and nearest neighbor interpolation is used

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

* [[gtractResampleB0]] - Resamples the B0 image - Image pixel type is signed short and linear interpolation is used

'''Example:'''
% gtractResampleB0 --inputVolume DWI_Coreg.nhdr --inputAnatomicalVolume T1_ACPC.nhdr \
--inputTransform ACPC_Rigid.txt --vectorIndex 0 \
--transformType Rigid --outputVolume B0_ACPC_rigid.nii.gz

* [[gtractResampleAnisotropy]] - Resamples an anisotropy map - Image pixel type is float and linear interpolation is used

'''Example:'''
% gtractResampleAnisotropy --inputAnisotropyVolume FA.nhdr --inputAnatomicalVolume T1_ACPC.nhdr \
--inputTransform ACPC_Rigid.txt --vectorIndex 0 \
--transformType Rigid --outputVolume FA_ACPC_rigid.nii.gz

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.

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:

# Free Tracking
# Streamlines Tracking
# Graph Search Tracking
# Guided 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 primary 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 anisotropy, 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 [[gtractFiberTracking]] can be obtained using the '--help' option.

'''Example:'''
% gtractFiberTracking --inputTensorVolume Tensor.nhdr \
--inputAnisotropyVolume FA.nhdr \
--trackingMethod Free \
--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 arguments for [[gtractFiberTracking]] are available with the '--help' option at the command line.

'''Example:'''
% gtractFiberTracking --inputTensorVolume Tensor.nhdr \
--inputAnisotropyVolume FA.nhdr \
--trackingMethod Streamline \
--inputStartingSeedsLabelMapVolume startingSeedsLabelMap.nhdr \
--startingSeedsLabel 1 \
--inputEndingSeedsLabelMapVolume endingSeedsLabelMap.nhdr \
--endingSeedsLabel 2 \
--curvatureThreshold 60 \
--outputTract streamlineTracking.vtk

===Graph Search Tracking===
The Graph Search 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-ambiguous regions and utilizes branching and a graph search algorithm in ambigous regions. Ambiguous 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 secondary 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 algorithm 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 arguments for [[gtractFiberTracking]] can be obtained using the '--help' option from the command line.

'''Example:'''
% gtractFiberTracking --inputTensorVolume Tensor.nhdr \
--inputAnisotropyVolume FA.nhdr \
--trackingMethod GraphSearch \
--inputStartingSeedsLabelMapVolume startingSeedsLabelMap.nhdr \
--startingSeedsLabel 1 \
--inputEndingSeedsLabelMapVolume endingSeedsLabelMap.nhdr \
--endingSeedsLabel 2 \
--inputTract guideFiber.vtk \
--curvatureThreshold 60 \
--branchingThreshold 0.20 \
--maximumBranchPoints 5 \
--branchingAngle 45.0 \
--outputTract graphSearchTracking.vtk

===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]] 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 [[gtractFiberTracking]] his algorithm. The user must specify the guide fiber when running this program.

'''Example:'''
% gtractFiberTracking --inputTensorVolume Tensor.nhdr \
--inputAnisotropyVolume FA.nhdr \
--inputStartingSeedsLabelMapVolume --startingSeed.nhdr \
--startingSeedsLabel 1 \
--inputEndingSeedsLabelMapVolume --endingSeed.nhdr \
--endingSeedsLable 2 \
--inputTract guide.vtk \
--trackingMethod Guided \
--guidedCurvatureThreshold 30.0 \
--maximumGuideDistance 12.0 \
--outputTract guidedTracking.vtk

===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]] 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]] 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-12-21T05:50:30Z

Matsuij: /* Invert B-Spline */

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

<pre>
DicomToNrrdConverter --inputDicomDirectory DICOM_directory_name --outputVolume NRRD_file_name.nrrd
</pre>

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 ==
The following are links to the full documentation of GTRACT's programs. The same documentation can be accessed on the command line using the following:

<pre>
${GTRACT_prog_name} --help
</pre>

* [[extractNrrdVectorIndex|extractNrrdVectorIndex Documentation]]
* [[gtractAnisotropyMap|gtractAnisotropyMap Documentation]]
* [[gtractAverageBvalues|gtractAverageBvalues Documentation]]
* [[gtractClipAnisotropy|gtractClipAnisotropy Documentation]]
* [[gtractCoRegAnatomy|gtractCoRegAnatomy Documentation]]
* [[gtractConcatDwi|gtractConcatDwi Documentation]]
* [[gtractCopyImageOrientation|gtractCopyImageOrientation Documentation]]
* [[gtractCoregBvalues|gtractCoregBvalues Documentation]]
* [[gtractCreateGuideFiber|gtractCreateGuideFiber Documentation]]
* [[gtractFiberTracking|gtractFiberTracking Documentation]]
* [[gtractResampleAnisotropy|gtractResampleAnisotropy Documentation]]
* [[gtractResampleB0|gtractResampleB0 Documentation]]
* [[gtractTensor|gtractTensor Documentation]]
* [[gtractInvertRigidTransform|gtractInvertRigidTransform Documentation]]
* [[gtractInvertBSplineTransform|gtractInvertBSplineTransform Documentation]]
* [[gtractResampleCodeImage|gtractResampleCodeImage Documentation]]
* [[gtractFastMarchingTracking|gtractFastMarchingTracking Documentation]]
* [[gtractCostFastMarching|gtractCostFastMarching 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-registration 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 adjust 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 \
--outputVolume outputImage.nhdr

== 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 ==
Anisotropy mapping can be used to generate the following diffusion tensor indices:
* Fractional Anisotropy (FA)
* Relative Anisotropy (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]].

'''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 arguments for [[gtractCopyImageOrientation]] 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 is the complete set of parameters for [[gtractCoRegAnatomy]].

'''Example'''
% gtractCoRegAnatomy --inputVolume DWI_coreg.nhdr --transformType Rigid \
--vectorIndex 0 --inputAnatomicalVolume T1_ACPC_Axial.nhdr \
--outputTransformName ACPC_rigid.mat --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 that is deformed. The B-Spline registration 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 be found here, [[gtractCoRegAnatomy]]

'''Example:'''

% gtractCoRegAnatomy --inputVolume DWI_coreg.nhdr --transformType Bspline \
--vectorIndex 0 --inputRigidTransform ACPC_rigid.mat --inputAnatomicalVolume T1_ACPC_Axial.nhdr \
--outputTransformName ACPC_bspline.mat --numberOfIterations 1000

{|
| 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]] 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 using the gtractInvertBspline. The X, Y and Z grids specify the grid utilized to sample the B-Spline transform. The parameters for [[gtractInvertBSplineTransform]] 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 susceptibility artifacts.

'''Example'''
% gtractInvertBSplineTransform --inputReferenceVolume T1_ACPC.nhdr --inputTransform ACPC_bspline.xfm \
--outputTransform ACPC_Inverse_Bspline.xfm

===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]] - Resamples a mask or label - Image pixel type is signed short and neareast neigbor interpolation is used

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

* [[gtractResampleB0]] - Resamples the B0 image - Image pixel type is signed short and linear interpolation is used

'''Example:'''
% gtractResampleB0 --inputVolume DWI_Coreg.nhdr --inputAnatomicalVolume T1_ACPC.nhdr \
--inputTransform ACPC_Rigid.txt --vectorIndex 0 \
--transformType Rigid --outputVolume B0_ACPC_rigid.nii.gz

* [[gtractResampleAnisotropy]] - Resamples an anisotropy map - Image pixel type is float and linear interpolation is used

'''Example:'''
% gtractResampleAnisotropy --inputAnisotropyVolume FA.nhdr --inputAnatomicalVolume T1_ACPC.nhdr \
--inputTransform ACPC_Rigid.txt --vectorIndex 0 \
--transformType Rigid --outputVolume FA_ACPC_rigid.nii.gz

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.

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:

# Free Tracking
# Streamlines Tracking
# Graph Search Tracking
# Guided 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 primary 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 anisotropy, 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 [[gtractFiberTracking]] can be obtained using the '--help' option.

'''Example:'''
% gtractFiberTracking --inputTensorVolume Tensor.nhdr \
--inputAnisotropyVolume FA.nhdr \
--trackingMethod Free \
--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 arguments for [[gtractFiberTracking]] are available with the '--help' option at the command line.

'''Example:'''
% gtractFiberTracking --inputTensorVolume Tensor.nhdr \
--inputAnisotropyVolume FA.nhdr \
--trackingMethod Streamline \
--inputStartingSeedsLabelMapVolume startingSeedsLabelMap.nhdr \
--startingSeedsLabel 1 \
--inputEndingSeedsLabelMapVolume endingSeedsLabelMap.nhdr \
--endingSeedsLabel 2 \
--curvatureThreshold 60 \
--outputTract streamlineTracking.vtk

===Graph Search Tracking===
The Graph Search 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-ambiguous regions and utilizes branching and a graph search algorithm in ambigous regions. Ambiguous 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 secondary 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 algorithm 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 arguments for [[gtractFiberTracking]] can be obtained using the '--help' option from the command line.

'''Example:'''
% gtractFiberTracking --inputTensorVolume Tensor.nhdr \
--inputAnisotropyVolume FA.nhdr \
--trackingMethod GraphSearch \
--inputStartingSeedsLabelMapVolume startingSeedsLabelMap.nhdr \
--startingSeedsLabel 1 \
--inputEndingSeedsLabelMapVolume endingSeedsLabelMap.nhdr \
--endingSeedsLabel 2 \
--inputTract guideFiber.vtk \
--curvatureThreshold 60 \
--branchingThreshold 0.20 \
--maximumBranchPoints 5 \
--branchingAngle 45.0 \
--outputTract graphSearchTracking.vtk

===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]] 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 [[gtractFiberTracking]] his algorithm. The user must specify the guide fiber when running this program.

'''Example:'''
% gtractFiberTracking --inputTensorVolume Tensor.nhdr \
--inputAnisotropyVolume FA.nhdr \
--inputStartingSeedsLabelMapVolume --startingSeed.nhdr \
--startingSeedsLabel 1 \
--inputEndingSeedsLabelMapVolume --endingSeed.nhdr \
--endingSeedsLable 2 \
--inputTract guide.vtk \
--trackingMethod Guided \
--guidedCurvatureThreshold 30.0 \
--maximumGuideDistance 12.0 \
--outputTract guidedTracking.vtk

===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]] 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]] 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-12-21T05:48:02Z

Matsuij: /* Anatomical B-Spline */

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

<pre>
DicomToNrrdConverter --inputDicomDirectory DICOM_directory_name --outputVolume NRRD_file_name.nrrd
</pre>

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 ==
The following are links to the full documentation of GTRACT's programs. The same documentation can be accessed on the command line using the following:

<pre>
${GTRACT_prog_name} --help
</pre>

* [[extractNrrdVectorIndex|extractNrrdVectorIndex Documentation]]
* [[gtractAnisotropyMap|gtractAnisotropyMap Documentation]]
* [[gtractAverageBvalues|gtractAverageBvalues Documentation]]
* [[gtractClipAnisotropy|gtractClipAnisotropy Documentation]]
* [[gtractCoRegAnatomy|gtractCoRegAnatomy Documentation]]
* [[gtractConcatDwi|gtractConcatDwi Documentation]]
* [[gtractCopyImageOrientation|gtractCopyImageOrientation Documentation]]
* [[gtractCoregBvalues|gtractCoregBvalues Documentation]]
* [[gtractCreateGuideFiber|gtractCreateGuideFiber Documentation]]
* [[gtractFiberTracking|gtractFiberTracking Documentation]]
* [[gtractResampleAnisotropy|gtractResampleAnisotropy Documentation]]
* [[gtractResampleB0|gtractResampleB0 Documentation]]
* [[gtractTensor|gtractTensor Documentation]]
* [[gtractInvertRigidTransform|gtractInvertRigidTransform Documentation]]
* [[gtractInvertBSplineTransform|gtractInvertBSplineTransform Documentation]]
* [[gtractResampleCodeImage|gtractResampleCodeImage Documentation]]
* [[gtractFastMarchingTracking|gtractFastMarchingTracking Documentation]]
* [[gtractCostFastMarching|gtractCostFastMarching 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-registration 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 adjust 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 \
--outputVolume outputImage.nhdr

== 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 ==
Anisotropy mapping can be used to generate the following diffusion tensor indices:
* Fractional Anisotropy (FA)
* Relative Anisotropy (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]].

'''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 arguments for [[gtractCopyImageOrientation]] 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 is the complete set of parameters for [[gtractCoRegAnatomy]].

'''Example'''
% gtractCoRegAnatomy --inputVolume DWI_coreg.nhdr --transformType Rigid \
--vectorIndex 0 --inputAnatomicalVolume T1_ACPC_Axial.nhdr \
--outputTransformName ACPC_rigid.mat --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 that is deformed. The B-Spline registration 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 be found here, [[gtractCoRegAnatomy]]

'''Example:'''

% gtractCoRegAnatomy --inputVolume DWI_coreg.nhdr --transformType Bspline \
--vectorIndex 0 --inputRigidTransform ACPC_rigid.mat --inputAnatomicalVolume T1_ACPC_Axial.nhdr \
--outputTransformName ACPC_bspline.mat --numberOfIterations 1000

{|
| 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]] 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 [[gtractInvertBSplineTransform]] 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 artifacts.

'''Example'''
% gtractInvertBSplineTransform --inputReferenceVolume T1_ACPC.nhdr --inputTransform ACPC_bspline.xfm \
--outputTransform ACPC_Inverse_Bspline.xfm

===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]] - Resamples a mask or label - Image pixel type is signed short and neareast neigbor interpolation is used

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

* [[gtractResampleB0]] - Resamples the B0 image - Image pixel type is signed short and linear interpolation is used

'''Example:'''
% gtractResampleB0 --inputVolume DWI_Coreg.nhdr --inputAnatomicalVolume T1_ACPC.nhdr \
--inputTransform ACPC_Rigid.txt --vectorIndex 0 \
--transformType Rigid --outputVolume B0_ACPC_rigid.nii.gz

* [[gtractResampleAnisotropy]] - Resamples an anisotropy map - Image pixel type is float and linear interpolation is used

'''Example:'''
% gtractResampleAnisotropy --inputAnisotropyVolume FA.nhdr --inputAnatomicalVolume T1_ACPC.nhdr \
--inputTransform ACPC_Rigid.txt --vectorIndex 0 \
--transformType Rigid --outputVolume FA_ACPC_rigid.nii.gz

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.

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:

# Free Tracking
# Streamlines Tracking
# Graph Search Tracking
# Guided 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 primary 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 anisotropy, 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 [[gtractFiberTracking]] can be obtained using the '--help' option.

'''Example:'''
% gtractFiberTracking --inputTensorVolume Tensor.nhdr \
--inputAnisotropyVolume FA.nhdr \
--trackingMethod Free \
--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 arguments for [[gtractFiberTracking]] are available with the '--help' option at the command line.

'''Example:'''
% gtractFiberTracking --inputTensorVolume Tensor.nhdr \
--inputAnisotropyVolume FA.nhdr \
--trackingMethod Streamline \
--inputStartingSeedsLabelMapVolume startingSeedsLabelMap.nhdr \
--startingSeedsLabel 1 \
--inputEndingSeedsLabelMapVolume endingSeedsLabelMap.nhdr \
--endingSeedsLabel 2 \
--curvatureThreshold 60 \
--outputTract streamlineTracking.vtk

===Graph Search Tracking===
The Graph Search 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-ambiguous regions and utilizes branching and a graph search algorithm in ambigous regions. Ambiguous 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 secondary 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 algorithm 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 arguments for [[gtractFiberTracking]] can be obtained using the '--help' option from the command line.

'''Example:'''
% gtractFiberTracking --inputTensorVolume Tensor.nhdr \
--inputAnisotropyVolume FA.nhdr \
--trackingMethod GraphSearch \
--inputStartingSeedsLabelMapVolume startingSeedsLabelMap.nhdr \
--startingSeedsLabel 1 \
--inputEndingSeedsLabelMapVolume endingSeedsLabelMap.nhdr \
--endingSeedsLabel 2 \
--inputTract guideFiber.vtk \
--curvatureThreshold 60 \
--branchingThreshold 0.20 \
--maximumBranchPoints 5 \
--branchingAngle 45.0 \
--outputTract graphSearchTracking.vtk

===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]] 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 [[gtractFiberTracking]] his algorithm. The user must specify the guide fiber when running this program.

'''Example:'''
% gtractFiberTracking --inputTensorVolume Tensor.nhdr \
--inputAnisotropyVolume FA.nhdr \
--inputStartingSeedsLabelMapVolume --startingSeed.nhdr \
--startingSeedsLabel 1 \
--inputEndingSeedsLabelMapVolume --endingSeed.nhdr \
--endingSeedsLable 2 \
--inputTract guide.vtk \
--trackingMethod Guided \
--guidedCurvatureThreshold 30.0 \
--maximumGuideDistance 12.0 \
--outputTract guidedTracking.vtk

===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]] 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]] 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-12-21T05:47:01Z

Matsuij: /* Anatomical Rigid */

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

<pre>
DicomToNrrdConverter --inputDicomDirectory DICOM_directory_name --outputVolume NRRD_file_name.nrrd
</pre>

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 ==
The following are links to the full documentation of GTRACT's programs. The same documentation can be accessed on the command line using the following:

<pre>
${GTRACT_prog_name} --help
</pre>

* [[extractNrrdVectorIndex|extractNrrdVectorIndex Documentation]]
* [[gtractAnisotropyMap|gtractAnisotropyMap Documentation]]
* [[gtractAverageBvalues|gtractAverageBvalues Documentation]]
* [[gtractClipAnisotropy|gtractClipAnisotropy Documentation]]
* [[gtractCoRegAnatomy|gtractCoRegAnatomy Documentation]]
* [[gtractConcatDwi|gtractConcatDwi Documentation]]
* [[gtractCopyImageOrientation|gtractCopyImageOrientation Documentation]]
* [[gtractCoregBvalues|gtractCoregBvalues Documentation]]
* [[gtractCreateGuideFiber|gtractCreateGuideFiber Documentation]]
* [[gtractFiberTracking|gtractFiberTracking Documentation]]
* [[gtractResampleAnisotropy|gtractResampleAnisotropy Documentation]]
* [[gtractResampleB0|gtractResampleB0 Documentation]]
* [[gtractTensor|gtractTensor Documentation]]
* [[gtractInvertRigidTransform|gtractInvertRigidTransform Documentation]]
* [[gtractInvertBSplineTransform|gtractInvertBSplineTransform Documentation]]
* [[gtractResampleCodeImage|gtractResampleCodeImage Documentation]]
* [[gtractFastMarchingTracking|gtractFastMarchingTracking Documentation]]
* [[gtractCostFastMarching|gtractCostFastMarching 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-registration 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 adjust 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 \
--outputVolume outputImage.nhdr

== 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 ==
Anisotropy mapping can be used to generate the following diffusion tensor indices:
* Fractional Anisotropy (FA)
* Relative Anisotropy (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]].

'''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 arguments for [[gtractCopyImageOrientation]] 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 is the complete set of parameters for [[gtractCoRegAnatomy]].

'''Example'''
% gtractCoRegAnatomy --inputVolume DWI_coreg.nhdr --transformType Rigid \
--vectorIndex 0 --inputAnatomicalVolume T1_ACPC_Axial.nhdr \
--outputTransformName ACPC_rigid.mat --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, [[gtractCoRegAnatomy]]

'''Example:'''

% gtractCoRegAnatomy --inputVolume DWI_coreg.nhdr --transformType Bspline \
--vectorIndex 0 --inputRigidTransform ACPC_rigid.mat --inputAnatomicalVolume T1_ACPC_Axial.nhdr \
--outputTransformName ACPC_bspline.mat --numberOfIterations 1000

{|
| 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]] 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 [[gtractInvertBSplineTransform]] 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 artifacts.

'''Example'''
% gtractInvertBSplineTransform --inputReferenceVolume T1_ACPC.nhdr --inputTransform ACPC_bspline.xfm \
--outputTransform ACPC_Inverse_Bspline.xfm

===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]] - Resamples a mask or label - Image pixel type is signed short and neareast neigbor interpolation is used

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

* [[gtractResampleB0]] - Resamples the B0 image - Image pixel type is signed short and linear interpolation is used

'''Example:'''
% gtractResampleB0 --inputVolume DWI_Coreg.nhdr --inputAnatomicalVolume T1_ACPC.nhdr \
--inputTransform ACPC_Rigid.txt --vectorIndex 0 \
--transformType Rigid --outputVolume B0_ACPC_rigid.nii.gz

* [[gtractResampleAnisotropy]] - Resamples an anisotropy map - Image pixel type is float and linear interpolation is used

'''Example:'''
% gtractResampleAnisotropy --inputAnisotropyVolume FA.nhdr --inputAnatomicalVolume T1_ACPC.nhdr \
--inputTransform ACPC_Rigid.txt --vectorIndex 0 \
--transformType Rigid --outputVolume FA_ACPC_rigid.nii.gz

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.

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:

# Free Tracking
# Streamlines Tracking
# Graph Search Tracking
# Guided 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 primary 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 anisotropy, 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 [[gtractFiberTracking]] can be obtained using the '--help' option.

'''Example:'''
% gtractFiberTracking --inputTensorVolume Tensor.nhdr \
--inputAnisotropyVolume FA.nhdr \
--trackingMethod Free \
--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 arguments for [[gtractFiberTracking]] are available with the '--help' option at the command line.

'''Example:'''
% gtractFiberTracking --inputTensorVolume Tensor.nhdr \
--inputAnisotropyVolume FA.nhdr \
--trackingMethod Streamline \
--inputStartingSeedsLabelMapVolume startingSeedsLabelMap.nhdr \
--startingSeedsLabel 1 \
--inputEndingSeedsLabelMapVolume endingSeedsLabelMap.nhdr \
--endingSeedsLabel 2 \
--curvatureThreshold 60 \
--outputTract streamlineTracking.vtk

===Graph Search Tracking===
The Graph Search 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-ambiguous regions and utilizes branching and a graph search algorithm in ambigous regions. Ambiguous 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 secondary 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 algorithm 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 arguments for [[gtractFiberTracking]] can be obtained using the '--help' option from the command line.

'''Example:'''
% gtractFiberTracking --inputTensorVolume Tensor.nhdr \
--inputAnisotropyVolume FA.nhdr \
--trackingMethod GraphSearch \
--inputStartingSeedsLabelMapVolume startingSeedsLabelMap.nhdr \
--startingSeedsLabel 1 \
--inputEndingSeedsLabelMapVolume endingSeedsLabelMap.nhdr \
--endingSeedsLabel 2 \
--inputTract guideFiber.vtk \
--curvatureThreshold 60 \
--branchingThreshold 0.20 \
--maximumBranchPoints 5 \
--branchingAngle 45.0 \
--outputTract graphSearchTracking.vtk

===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]] 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 [[gtractFiberTracking]] his algorithm. The user must specify the guide fiber when running this program.

'''Example:'''
% gtractFiberTracking --inputTensorVolume Tensor.nhdr \
--inputAnisotropyVolume FA.nhdr \
--inputStartingSeedsLabelMapVolume --startingSeed.nhdr \
--startingSeedsLabel 1 \
--inputEndingSeedsLabelMapVolume --endingSeed.nhdr \
--endingSeedsLable 2 \
--inputTract guide.vtk \
--trackingMethod Guided \
--guidedCurvatureThreshold 30.0 \
--maximumGuideDistance 12.0 \
--outputTract guidedTracking.vtk

===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]] 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]] 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-12-21T05:46:12Z

Matsuij: /* Copy Reference Image Orientation */

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

<pre>
DicomToNrrdConverter --inputDicomDirectory DICOM_directory_name --outputVolume NRRD_file_name.nrrd
</pre>

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 ==
The following are links to the full documentation of GTRACT's programs. The same documentation can be accessed on the command line using the following:

<pre>
${GTRACT_prog_name} --help
</pre>

* [[extractNrrdVectorIndex|extractNrrdVectorIndex Documentation]]
* [[gtractAnisotropyMap|gtractAnisotropyMap Documentation]]
* [[gtractAverageBvalues|gtractAverageBvalues Documentation]]
* [[gtractClipAnisotropy|gtractClipAnisotropy Documentation]]
* [[gtractCoRegAnatomy|gtractCoRegAnatomy Documentation]]
* [[gtractConcatDwi|gtractConcatDwi Documentation]]
* [[gtractCopyImageOrientation|gtractCopyImageOrientation Documentation]]
* [[gtractCoregBvalues|gtractCoregBvalues Documentation]]
* [[gtractCreateGuideFiber|gtractCreateGuideFiber Documentation]]
* [[gtractFiberTracking|gtractFiberTracking Documentation]]
* [[gtractResampleAnisotropy|gtractResampleAnisotropy Documentation]]
* [[gtractResampleB0|gtractResampleB0 Documentation]]
* [[gtractTensor|gtractTensor Documentation]]
* [[gtractInvertRigidTransform|gtractInvertRigidTransform Documentation]]
* [[gtractInvertBSplineTransform|gtractInvertBSplineTransform Documentation]]
* [[gtractResampleCodeImage|gtractResampleCodeImage Documentation]]
* [[gtractFastMarchingTracking|gtractFastMarchingTracking Documentation]]
* [[gtractCostFastMarching|gtractCostFastMarching 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-registration 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 adjust 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 \
--outputVolume outputImage.nhdr

== 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 ==
Anisotropy mapping can be used to generate the following diffusion tensor indices:
* Fractional Anisotropy (FA)
* Relative Anisotropy (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]].

'''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 arguments for [[gtractCopyImageOrientation]] 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 [[gtractCoRegAnatomy]]

'''Example'''
% gtractCoRegAnatomy --inputVolume DWI_coreg.nhdr --transformType Rigid \
--vectorIndex 0 --inputAnatomicalVolume T1_ACPC_Axial.nhdr \
--outputTransformName ACPC_rigid.mat --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, [[gtractCoRegAnatomy]]

'''Example:'''

% gtractCoRegAnatomy --inputVolume DWI_coreg.nhdr --transformType Bspline \
--vectorIndex 0 --inputRigidTransform ACPC_rigid.mat --inputAnatomicalVolume T1_ACPC_Axial.nhdr \
--outputTransformName ACPC_bspline.mat --numberOfIterations 1000

{|
| 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]] 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 [[gtractInvertBSplineTransform]] 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 artifacts.

'''Example'''
% gtractInvertBSplineTransform --inputReferenceVolume T1_ACPC.nhdr --inputTransform ACPC_bspline.xfm \
--outputTransform ACPC_Inverse_Bspline.xfm

===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]] - Resamples a mask or label - Image pixel type is signed short and neareast neigbor interpolation is used

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

* [[gtractResampleB0]] - Resamples the B0 image - Image pixel type is signed short and linear interpolation is used

'''Example:'''
% gtractResampleB0 --inputVolume DWI_Coreg.nhdr --inputAnatomicalVolume T1_ACPC.nhdr \
--inputTransform ACPC_Rigid.txt --vectorIndex 0 \
--transformType Rigid --outputVolume B0_ACPC_rigid.nii.gz

* [[gtractResampleAnisotropy]] - Resamples an anisotropy map - Image pixel type is float and linear interpolation is used

'''Example:'''
% gtractResampleAnisotropy --inputAnisotropyVolume FA.nhdr --inputAnatomicalVolume T1_ACPC.nhdr \
--inputTransform ACPC_Rigid.txt --vectorIndex 0 \
--transformType Rigid --outputVolume FA_ACPC_rigid.nii.gz

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.

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:

# Free Tracking
# Streamlines Tracking
# Graph Search Tracking
# Guided 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 primary 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 anisotropy, 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 [[gtractFiberTracking]] can be obtained using the '--help' option.

'''Example:'''
% gtractFiberTracking --inputTensorVolume Tensor.nhdr \
--inputAnisotropyVolume FA.nhdr \
--trackingMethod Free \
--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 arguments for [[gtractFiberTracking]] are available with the '--help' option at the command line.

'''Example:'''
% gtractFiberTracking --inputTensorVolume Tensor.nhdr \
--inputAnisotropyVolume FA.nhdr \
--trackingMethod Streamline \
--inputStartingSeedsLabelMapVolume startingSeedsLabelMap.nhdr \
--startingSeedsLabel 1 \
--inputEndingSeedsLabelMapVolume endingSeedsLabelMap.nhdr \
--endingSeedsLabel 2 \
--curvatureThreshold 60 \
--outputTract streamlineTracking.vtk

===Graph Search Tracking===
The Graph Search 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-ambiguous regions and utilizes branching and a graph search algorithm in ambigous regions. Ambiguous 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 secondary 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 algorithm 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 arguments for [[gtractFiberTracking]] can be obtained using the '--help' option from the command line.

'''Example:'''
% gtractFiberTracking --inputTensorVolume Tensor.nhdr \
--inputAnisotropyVolume FA.nhdr \
--trackingMethod GraphSearch \
--inputStartingSeedsLabelMapVolume startingSeedsLabelMap.nhdr \
--startingSeedsLabel 1 \
--inputEndingSeedsLabelMapVolume endingSeedsLabelMap.nhdr \
--endingSeedsLabel 2 \
--inputTract guideFiber.vtk \
--curvatureThreshold 60 \
--branchingThreshold 0.20 \
--maximumBranchPoints 5 \
--branchingAngle 45.0 \
--outputTract graphSearchTracking.vtk

===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]] 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 [[gtractFiberTracking]] his algorithm. The user must specify the guide fiber when running this program.

'''Example:'''
% gtractFiberTracking --inputTensorVolume Tensor.nhdr \
--inputAnisotropyVolume FA.nhdr \
--inputStartingSeedsLabelMapVolume --startingSeed.nhdr \
--startingSeedsLabel 1 \
--inputEndingSeedsLabelMapVolume --endingSeed.nhdr \
--endingSeedsLable 2 \
--inputTract guide.vtk \
--trackingMethod Guided \
--guidedCurvatureThreshold 30.0 \
--maximumGuideDistance 12.0 \
--outputTract guidedTracking.vtk

===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]] 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]] 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-12-21T05:45:17Z

Matsuij: /* Compute Anisotropy Images */

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

<pre>
DicomToNrrdConverter --inputDicomDirectory DICOM_directory_name --outputVolume NRRD_file_name.nrrd
</pre>

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 ==
The following are links to the full documentation of GTRACT's programs. The same documentation can be accessed on the command line using the following:

<pre>
${GTRACT_prog_name} --help
</pre>

* [[extractNrrdVectorIndex|extractNrrdVectorIndex Documentation]]
* [[gtractAnisotropyMap|gtractAnisotropyMap Documentation]]
* [[gtractAverageBvalues|gtractAverageBvalues Documentation]]
* [[gtractClipAnisotropy|gtractClipAnisotropy Documentation]]
* [[gtractCoRegAnatomy|gtractCoRegAnatomy Documentation]]
* [[gtractConcatDwi|gtractConcatDwi Documentation]]
* [[gtractCopyImageOrientation|gtractCopyImageOrientation Documentation]]
* [[gtractCoregBvalues|gtractCoregBvalues Documentation]]
* [[gtractCreateGuideFiber|gtractCreateGuideFiber Documentation]]
* [[gtractFiberTracking|gtractFiberTracking Documentation]]
* [[gtractResampleAnisotropy|gtractResampleAnisotropy Documentation]]
* [[gtractResampleB0|gtractResampleB0 Documentation]]
* [[gtractTensor|gtractTensor Documentation]]
* [[gtractInvertRigidTransform|gtractInvertRigidTransform Documentation]]
* [[gtractInvertBSplineTransform|gtractInvertBSplineTransform Documentation]]
* [[gtractResampleCodeImage|gtractResampleCodeImage Documentation]]
* [[gtractFastMarchingTracking|gtractFastMarchingTracking Documentation]]
* [[gtractCostFastMarching|gtractCostFastMarching 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-registration 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 adjust 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 \
--outputVolume outputImage.nhdr

== 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 ==
Anisotropy mapping can be used to generate the following diffusion tensor indices:
* Fractional Anisotropy (FA)
* Relative Anisotropy (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]].

'''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]] 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 [[gtractCoRegAnatomy]]

'''Example'''
% gtractCoRegAnatomy --inputVolume DWI_coreg.nhdr --transformType Rigid \
--vectorIndex 0 --inputAnatomicalVolume T1_ACPC_Axial.nhdr \
--outputTransformName ACPC_rigid.mat --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, [[gtractCoRegAnatomy]]

'''Example:'''

% gtractCoRegAnatomy --inputVolume DWI_coreg.nhdr --transformType Bspline \
--vectorIndex 0 --inputRigidTransform ACPC_rigid.mat --inputAnatomicalVolume T1_ACPC_Axial.nhdr \
--outputTransformName ACPC_bspline.mat --numberOfIterations 1000

{|
| 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]] 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 [[gtractInvertBSplineTransform]] 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 artifacts.

'''Example'''
% gtractInvertBSplineTransform --inputReferenceVolume T1_ACPC.nhdr --inputTransform ACPC_bspline.xfm \
--outputTransform ACPC_Inverse_Bspline.xfm

===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]] - Resamples a mask or label - Image pixel type is signed short and neareast neigbor interpolation is used

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

* [[gtractResampleB0]] - Resamples the B0 image - Image pixel type is signed short and linear interpolation is used

'''Example:'''
% gtractResampleB0 --inputVolume DWI_Coreg.nhdr --inputAnatomicalVolume T1_ACPC.nhdr \
--inputTransform ACPC_Rigid.txt --vectorIndex 0 \
--transformType Rigid --outputVolume B0_ACPC_rigid.nii.gz

* [[gtractResampleAnisotropy]] - Resamples an anisotropy map - Image pixel type is float and linear interpolation is used

'''Example:'''
% gtractResampleAnisotropy --inputAnisotropyVolume FA.nhdr --inputAnatomicalVolume T1_ACPC.nhdr \
--inputTransform ACPC_Rigid.txt --vectorIndex 0 \
--transformType Rigid --outputVolume FA_ACPC_rigid.nii.gz

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.

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:

# Free Tracking
# Streamlines Tracking
# Graph Search Tracking
# Guided 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 primary 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 anisotropy, 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 [[gtractFiberTracking]] can be obtained using the '--help' option.

'''Example:'''
% gtractFiberTracking --inputTensorVolume Tensor.nhdr \
--inputAnisotropyVolume FA.nhdr \
--trackingMethod Free \
--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 arguments for [[gtractFiberTracking]] are available with the '--help' option at the command line.

'''Example:'''
% gtractFiberTracking --inputTensorVolume Tensor.nhdr \
--inputAnisotropyVolume FA.nhdr \
--trackingMethod Streamline \
--inputStartingSeedsLabelMapVolume startingSeedsLabelMap.nhdr \
--startingSeedsLabel 1 \
--inputEndingSeedsLabelMapVolume endingSeedsLabelMap.nhdr \
--endingSeedsLabel 2 \
--curvatureThreshold 60 \
--outputTract streamlineTracking.vtk

===Graph Search Tracking===
The Graph Search 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-ambiguous regions and utilizes branching and a graph search algorithm in ambigous regions. Ambiguous 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 secondary 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 algorithm 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 arguments for [[gtractFiberTracking]] can be obtained using the '--help' option from the command line.

'''Example:'''
% gtractFiberTracking --inputTensorVolume Tensor.nhdr \
--inputAnisotropyVolume FA.nhdr \
--trackingMethod GraphSearch \
--inputStartingSeedsLabelMapVolume startingSeedsLabelMap.nhdr \
--startingSeedsLabel 1 \
--inputEndingSeedsLabelMapVolume endingSeedsLabelMap.nhdr \
--endingSeedsLabel 2 \
--inputTract guideFiber.vtk \
--curvatureThreshold 60 \
--branchingThreshold 0.20 \
--maximumBranchPoints 5 \
--branchingAngle 45.0 \
--outputTract graphSearchTracking.vtk

===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]] 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 [[gtractFiberTracking]] his algorithm. The user must specify the guide fiber when running this program.

'''Example:'''
% gtractFiberTracking --inputTensorVolume Tensor.nhdr \
--inputAnisotropyVolume FA.nhdr \
--inputStartingSeedsLabelMapVolume --startingSeed.nhdr \
--startingSeedsLabel 1 \
--inputEndingSeedsLabelMapVolume --endingSeed.nhdr \
--endingSeedsLable 2 \
--inputTract guide.vtk \
--trackingMethod Guided \
--guidedCurvatureThreshold 30.0 \
--maximumGuideDistance 12.0 \
--outputTract guidedTracking.vtk

===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]] 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]] 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-12-21T05:43:54Z

Matsuij: /* DTI Image Co-Registration */

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

<pre>
DicomToNrrdConverter --inputDicomDirectory DICOM_directory_name --outputVolume NRRD_file_name.nrrd
</pre>

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 ==
The following are links to the full documentation of GTRACT's programs. The same documentation can be accessed on the command line using the following:

<pre>
${GTRACT_prog_name} --help
</pre>

* [[extractNrrdVectorIndex|extractNrrdVectorIndex Documentation]]
* [[gtractAnisotropyMap|gtractAnisotropyMap Documentation]]
* [[gtractAverageBvalues|gtractAverageBvalues Documentation]]
* [[gtractClipAnisotropy|gtractClipAnisotropy Documentation]]
* [[gtractCoRegAnatomy|gtractCoRegAnatomy Documentation]]
* [[gtractConcatDwi|gtractConcatDwi Documentation]]
* [[gtractCopyImageOrientation|gtractCopyImageOrientation Documentation]]
* [[gtractCoregBvalues|gtractCoregBvalues Documentation]]
* [[gtractCreateGuideFiber|gtractCreateGuideFiber Documentation]]
* [[gtractFiberTracking|gtractFiberTracking Documentation]]
* [[gtractResampleAnisotropy|gtractResampleAnisotropy Documentation]]
* [[gtractResampleB0|gtractResampleB0 Documentation]]
* [[gtractTensor|gtractTensor Documentation]]
* [[gtractInvertRigidTransform|gtractInvertRigidTransform Documentation]]
* [[gtractInvertBSplineTransform|gtractInvertBSplineTransform Documentation]]
* [[gtractResampleCodeImage|gtractResampleCodeImage Documentation]]
* [[gtractFastMarchingTracking|gtractFastMarchingTracking Documentation]]
* [[gtractCostFastMarching|gtractCostFastMarching 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-registration 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 adjust 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 \
--outputVolume outputImage.nhdr

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

'''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]] 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 [[gtractCoRegAnatomy]]

'''Example'''
% gtractCoRegAnatomy --inputVolume DWI_coreg.nhdr --transformType Rigid \
--vectorIndex 0 --inputAnatomicalVolume T1_ACPC_Axial.nhdr \
--outputTransformName ACPC_rigid.mat --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, [[gtractCoRegAnatomy]]

'''Example:'''

% gtractCoRegAnatomy --inputVolume DWI_coreg.nhdr --transformType Bspline \
--vectorIndex 0 --inputRigidTransform ACPC_rigid.mat --inputAnatomicalVolume T1_ACPC_Axial.nhdr \
--outputTransformName ACPC_bspline.mat --numberOfIterations 1000

{|
| 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]] 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 [[gtractInvertBSplineTransform]] 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 artifacts.

'''Example'''
% gtractInvertBSplineTransform --inputReferenceVolume T1_ACPC.nhdr --inputTransform ACPC_bspline.xfm \
--outputTransform ACPC_Inverse_Bspline.xfm

===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]] - Resamples a mask or label - Image pixel type is signed short and neareast neigbor interpolation is used

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

* [[gtractResampleB0]] - Resamples the B0 image - Image pixel type is signed short and linear interpolation is used

'''Example:'''
% gtractResampleB0 --inputVolume DWI_Coreg.nhdr --inputAnatomicalVolume T1_ACPC.nhdr \
--inputTransform ACPC_Rigid.txt --vectorIndex 0 \
--transformType Rigid --outputVolume B0_ACPC_rigid.nii.gz

* [[gtractResampleAnisotropy]] - Resamples an anisotropy map - Image pixel type is float and linear interpolation is used

'''Example:'''
% gtractResampleAnisotropy --inputAnisotropyVolume FA.nhdr --inputAnatomicalVolume T1_ACPC.nhdr \
--inputTransform ACPC_Rigid.txt --vectorIndex 0 \
--transformType Rigid --outputVolume FA_ACPC_rigid.nii.gz

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.

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:

# Free Tracking
# Streamlines Tracking
# Graph Search Tracking
# Guided 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 primary 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 anisotropy, 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 [[gtractFiberTracking]] can be obtained using the '--help' option.

'''Example:'''
% gtractFiberTracking --inputTensorVolume Tensor.nhdr \
--inputAnisotropyVolume FA.nhdr \
--trackingMethod Free \
--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 arguments for [[gtractFiberTracking]] are available with the '--help' option at the command line.

'''Example:'''
% gtractFiberTracking --inputTensorVolume Tensor.nhdr \
--inputAnisotropyVolume FA.nhdr \
--trackingMethod Streamline \
--inputStartingSeedsLabelMapVolume startingSeedsLabelMap.nhdr \
--startingSeedsLabel 1 \
--inputEndingSeedsLabelMapVolume endingSeedsLabelMap.nhdr \
--endingSeedsLabel 2 \
--curvatureThreshold 60 \
--outputTract streamlineTracking.vtk

===Graph Search Tracking===
The Graph Search 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-ambiguous regions and utilizes branching and a graph search algorithm in ambigous regions. Ambiguous 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 secondary 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 algorithm 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 arguments for [[gtractFiberTracking]] can be obtained using the '--help' option from the command line.

'''Example:'''
% gtractFiberTracking --inputTensorVolume Tensor.nhdr \
--inputAnisotropyVolume FA.nhdr \
--trackingMethod GraphSearch \
--inputStartingSeedsLabelMapVolume startingSeedsLabelMap.nhdr \
--startingSeedsLabel 1 \
--inputEndingSeedsLabelMapVolume endingSeedsLabelMap.nhdr \
--endingSeedsLabel 2 \
--inputTract guideFiber.vtk \
--curvatureThreshold 60 \
--branchingThreshold 0.20 \
--maximumBranchPoints 5 \
--branchingAngle 45.0 \
--outputTract graphSearchTracking.vtk

===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]] 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 [[gtractFiberTracking]] his algorithm. The user must specify the guide fiber when running this program.

'''Example:'''
% gtractFiberTracking --inputTensorVolume Tensor.nhdr \
--inputAnisotropyVolume FA.nhdr \
--inputStartingSeedsLabelMapVolume --startingSeed.nhdr \
--startingSeedsLabel 1 \
--inputEndingSeedsLabelMapVolume --endingSeed.nhdr \
--endingSeedsLable 2 \
--inputTract guide.vtk \
--trackingMethod Guided \
--guidedCurvatureThreshold 30.0 \
--maximumGuideDistance 12.0 \
--outputTract guidedTracking.vtk

===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]] 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]] 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-12-21T05:37:41Z

Matsuij: /* 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.

<pre>
DicomToNrrdConverter --inputDicomDirectory DICOM_directory_name --outputVolume NRRD_file_name.nrrd
</pre>

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 ==
The following are links to the full documentation of GTRACT's programs. The same documentation can be accessed on the command line using the following:

<pre>
${GTRACT_prog_name} --help
</pre>

* [[extractNrrdVectorIndex|extractNrrdVectorIndex Documentation]]
* [[gtractAnisotropyMap|gtractAnisotropyMap Documentation]]
* [[gtractAverageBvalues|gtractAverageBvalues Documentation]]
* [[gtractClipAnisotropy|gtractClipAnisotropy Documentation]]
* [[gtractCoRegAnatomy|gtractCoRegAnatomy Documentation]]
* [[gtractConcatDwi|gtractConcatDwi Documentation]]
* [[gtractCopyImageOrientation|gtractCopyImageOrientation Documentation]]
* [[gtractCoregBvalues|gtractCoregBvalues Documentation]]
* [[gtractCreateGuideFiber|gtractCreateGuideFiber Documentation]]
* [[gtractFiberTracking|gtractFiberTracking Documentation]]
* [[gtractResampleAnisotropy|gtractResampleAnisotropy Documentation]]
* [[gtractResampleB0|gtractResampleB0 Documentation]]
* [[gtractTensor|gtractTensor Documentation]]
* [[gtractInvertRigidTransform|gtractInvertRigidTransform Documentation]]
* [[gtractInvertBSplineTransform|gtractInvertBSplineTransform Documentation]]
* [[gtractResampleCodeImage|gtractResampleCodeImage Documentation]]
* [[gtractFastMarchingTracking|gtractFastMarchingTracking Documentation]]
* [[gtractCostFastMarching|gtractCostFastMarching 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 \
--outputVolume outputImage.nhdr

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

'''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]] 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 [[gtractCoRegAnatomy]]

'''Example'''
% gtractCoRegAnatomy --inputVolume DWI_coreg.nhdr --transformType Rigid \
--vectorIndex 0 --inputAnatomicalVolume T1_ACPC_Axial.nhdr \
--outputTransformName ACPC_rigid.mat --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, [[gtractCoRegAnatomy]]

'''Example:'''

% gtractCoRegAnatomy --inputVolume DWI_coreg.nhdr --transformType Bspline \
--vectorIndex 0 --inputRigidTransform ACPC_rigid.mat --inputAnatomicalVolume T1_ACPC_Axial.nhdr \
--outputTransformName ACPC_bspline.mat --numberOfIterations 1000

{|
| 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]] 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 [[gtractInvertBSplineTransform]] 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 artifacts.

'''Example'''
% gtractInvertBSplineTransform --inputReferenceVolume T1_ACPC.nhdr --inputTransform ACPC_bspline.xfm \
--outputTransform ACPC_Inverse_Bspline.xfm

===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]] - Resamples a mask or label - Image pixel type is signed short and neareast neigbor interpolation is used

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

* [[gtractResampleB0]] - Resamples the B0 image - Image pixel type is signed short and linear interpolation is used

'''Example:'''
% gtractResampleB0 --inputVolume DWI_Coreg.nhdr --inputAnatomicalVolume T1_ACPC.nhdr \
--inputTransform ACPC_Rigid.txt --vectorIndex 0 \
--transformType Rigid --outputVolume B0_ACPC_rigid.nii.gz

* [[gtractResampleAnisotropy]] - Resamples an anisotropy map - Image pixel type is float and linear interpolation is used

'''Example:'''
% gtractResampleAnisotropy --inputAnisotropyVolume FA.nhdr --inputAnatomicalVolume T1_ACPC.nhdr \
--inputTransform ACPC_Rigid.txt --vectorIndex 0 \
--transformType Rigid --outputVolume FA_ACPC_rigid.nii.gz

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.

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:

# Free Tracking
# Streamlines Tracking
# Graph Search Tracking
# Guided 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 primary 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 anisotropy, 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 [[gtractFiberTracking]] can be obtained using the '--help' option.

'''Example:'''
% gtractFiberTracking --inputTensorVolume Tensor.nhdr \
--inputAnisotropyVolume FA.nhdr \
--trackingMethod Free \
--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 arguments for [[gtractFiberTracking]] are available with the '--help' option at the command line.

'''Example:'''
% gtractFiberTracking --inputTensorVolume Tensor.nhdr \
--inputAnisotropyVolume FA.nhdr \
--trackingMethod Streamline \
--inputStartingSeedsLabelMapVolume startingSeedsLabelMap.nhdr \
--startingSeedsLabel 1 \
--inputEndingSeedsLabelMapVolume endingSeedsLabelMap.nhdr \
--endingSeedsLabel 2 \
--curvatureThreshold 60 \
--outputTract streamlineTracking.vtk

===Graph Search Tracking===
The Graph Search 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-ambiguous regions and utilizes branching and a graph search algorithm in ambigous regions. Ambiguous 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 secondary 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 algorithm 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 arguments for [[gtractFiberTracking]] can be obtained using the '--help' option from the command line.

'''Example:'''
% gtractFiberTracking --inputTensorVolume Tensor.nhdr \
--inputAnisotropyVolume FA.nhdr \
--trackingMethod GraphSearch \
--inputStartingSeedsLabelMapVolume startingSeedsLabelMap.nhdr \
--startingSeedsLabel 1 \
--inputEndingSeedsLabelMapVolume endingSeedsLabelMap.nhdr \
--endingSeedsLabel 2 \
--inputTract guideFiber.vtk \
--curvatureThreshold 60 \
--branchingThreshold 0.20 \
--maximumBranchPoints 5 \
--branchingAngle 45.0 \
--outputTract graphSearchTracking.vtk

===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]] 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 [[gtractFiberTracking]] his algorithm. The user must specify the guide fiber when running this program.

'''Example:'''
% gtractFiberTracking --inputTensorVolume Tensor.nhdr \
--inputAnisotropyVolume FA.nhdr \
--inputStartingSeedsLabelMapVolume --startingSeed.nhdr \
--startingSeedsLabel 1 \
--inputEndingSeedsLabelMapVolume --endingSeed.nhdr \
--endingSeedsLable 2 \
--inputTract guide.vtk \
--trackingMethod Guided \
--guidedCurvatureThreshold 30.0 \
--maximumGuideDistance 12.0 \
--outputTract guidedTracking.vtk

===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]] 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]] 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-12-21T05:21:13Z

Matsuij: /* DTI Image Co-Registration */

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

<pre>
DicomToNrrdConverter --inputDicomDirectory DICOM_directory_name --outputVolume NRRD_file_name.nrrd
</pre>

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 ==
The following are links to the full documentation of GTRACT's programs. The same documentation can be accessed on the command line using the following:

<pre>
${GTRACT_prog_name} --help
</pre>

* [[extractNrrdVectorIndex|extractNrrdVectorIndex Documentation]]
* [[gtractAnisotropyMap|gtractAnisotropyMap Documentation]]
* [[gtractAverageBvalues|gtractAverageBvalues Documentation]]
* [[gtractClipAnisotropy|gtractClipAnisotropy Documentation]]
* [[gtractCoRegAnatomy|gtractCoRegAnatomy Documentation]]
* [[gtractConcatDwi|gtractConcatDwi Documentation]]
* [[gtractCopyImageOrientation|gtractCopyImageOrientation Documentation]]
* [[gtractCoregBvalues|gtractCoregBvalues Documentation]]
* [[gtractCreateGuideFiber|gtractCreateGuideFiber Documentation]]
* [[gtractFiberTracking|gtractFiberTracking Documentation]]
* [[gtractResampleAnisotropy|gtractResampleAnisotropy Documentation]]
* [[gtractResampleB0|gtractResampleB0 Documentation]]
* [[gtractTensor|gtractTensor 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 \
--outputVolume outputImage.nhdr

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

'''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]] 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 [[gtractCoRegAnatomy]]

'''Example'''
% gtractCoRegAnatomy --inputVolume DWI_coreg.nhdr --transformType Rigid \
--vectorIndex 0 --inputAnatomicalVolume T1_ACPC_Axial.nhdr \
--outputTransformName ACPC_rigid.mat --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, [[gtractCoRegAnatomy]]

'''Example:'''

% gtractCoRegAnatomy --inputVolume DWI_coreg.nhdr --transformType Bspline \
--vectorIndex 0 --inputRigidTransform ACPC_rigid.mat --inputAnatomicalVolume T1_ACPC_Axial.nhdr \
--outputTransformName ACPC_bspline.mat --numberOfIterations 1000

{|
| 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]] 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 [[gtractInvertBSplineTransform]] 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 artifacts.

'''Example'''
% gtractInvertBSplineTransform --inputReferenceVolume T1_ACPC.nhdr --inputTransform ACPC_bspline.xfm \
--outputTransform ACPC_Inverse_Bspline.xfm

===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]] - Resamples a mask or label - Image pixel type is signed short and neareast neigbor interpolation is used

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

* [[gtractResampleB0]] - Resamples the B0 image - Image pixel type is signed short and linear interpolation is used

'''Example:'''
% gtractResampleB0 --inputVolume DWI_Coreg.nhdr --inputAnatomicalVolume T1_ACPC.nhdr \
--inputTransform ACPC_Rigid.txt --vectorIndex 0 \
--transformType Rigid --outputVolume B0_ACPC_rigid.nii.gz

* [[gtractResampleAnisotropy]] - Resamples an anisotropy map - Image pixel type is float and linear interpolation is used

'''Example:'''
% gtractResampleAnisotropy --inputAnisotropyVolume FA.nhdr --inputAnatomicalVolume T1_ACPC.nhdr \
--inputTransform ACPC_Rigid.txt --vectorIndex 0 \
--transformType Rigid --outputVolume FA_ACPC_rigid.nii.gz

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.

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:

# Free Tracking
# Streamlines Tracking
# Graph Search Tracking
# Guided 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 primary 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 anisotropy, 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 [[gtractFiberTracking]] can be obtained using the '--help' option.

'''Example:'''
% gtractFiberTracking --inputTensorVolume Tensor.nhdr \
--inputAnisotropyVolume FA.nhdr \
--trackingMethod Free \
--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 arguments for [[gtractFiberTracking]] are available with the '--help' option at the command line.

'''Example:'''
% gtractFiberTracking --inputTensorVolume Tensor.nhdr \
--inputAnisotropyVolume FA.nhdr \
--trackingMethod Streamline \
--inputStartingSeedsLabelMapVolume startingSeedsLabelMap.nhdr \
--startingSeedsLabel 1 \
--inputEndingSeedsLabelMapVolume endingSeedsLabelMap.nhdr \
--endingSeedsLabel 2 \
--curvatureThreshold 60 \
--outputTract streamlineTracking.vtk

===Graph Search Tracking===
The Graph Search 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-ambiguous regions and utilizes branching and a graph search algorithm in ambigous regions. Ambiguous 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 secondary 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 algorithm 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 arguments for [[gtractFiberTracking]] can be obtained using the '--help' option from the command line.

'''Example:'''
% gtractFiberTracking --inputTensorVolume Tensor.nhdr \
--inputAnisotropyVolume FA.nhdr \
--trackingMethod GraphSearch \
--inputStartingSeedsLabelMapVolume startingSeedsLabelMap.nhdr \
--startingSeedsLabel 1 \
--inputEndingSeedsLabelMapVolume endingSeedsLabelMap.nhdr \
--endingSeedsLabel 2 \
--inputTract guideFiber.vtk \
--curvatureThreshold 60 \
--branchingThreshold 0.20 \
--maximumBranchPoints 5 \
--branchingAngle 45.0 \
--outputTract graphSearchTracking.vtk

===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]] 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 [[gtractFiberTracking]] his algorithm. The user must specify the guide fiber when running this program.

'''Example:'''
% gtractFiberTracking --inputTensorVolume Tensor.nhdr \
--inputAnisotropyVolume FA.nhdr \
--inputStartingSeedsLabelMapVolume --startingSeed.nhdr \
--startingSeedsLabel 1 \
--inputEndingSeedsLabelMapVolume --endingSeed.nhdr \
--endingSeedsLable 2 \
--inputTract guide.vtk \
--trackingMethod Guided \
--guidedCurvatureThreshold 30.0 \
--maximumGuideDistance 12.0 \
--outputTract guidedTracking.vtk

===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]] 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]] 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-12-21T05:16:59Z

Matsuij: /* Guided Tracking */

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

<pre>
DicomToNrrdConverter --inputDicomDirectory DICOM_directory_name --outputVolume NRRD_file_name.nrrd
</pre>

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 ==
The following are links to the full documentation of GTRACT's programs. The same documentation can be accessed on the command line using the following:

<pre>
${GTRACT_prog_name} --help
</pre>

* [[extractNrrdVectorIndex|extractNrrdVectorIndex Documentation]]
* [[gtractAnisotropyMap|gtractAnisotropyMap Documentation]]
* [[gtractAverageBvalues|gtractAverageBvalues Documentation]]
* [[gtractClipAnisotropy|gtractClipAnisotropy Documentation]]
* [[gtractCoRegAnatomy|gtractCoRegAnatomy Documentation]]
* [[gtractConcatDwi|gtractConcatDwi Documentation]]
* [[gtractCopyImageOrientation|gtractCopyImageOrientation Documentation]]
* [[gtractCoregBvalues|gtractCoregBvalues Documentation]]
* [[gtractCreateGuideFiber|gtractCreateGuideFiber Documentation]]
* [[gtractFiberTracking|gtractFiberTracking Documentation]]
* [[gtractResampleAnisotropy|gtractResampleAnisotropy Documentation]]
* [[gtractResampleB0|gtractResampleB0 Documentation]]
* [[gtractTensor|gtractTensor 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 \
--outputVolume outputImage.nhdr

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

'''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]] 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 [[gtractCoRegAnatomy]]

'''Example'''
% gtractCoRegAnatomy --inputVolume DWI_coreg.nhdr --transformType Rigid \
--vectorIndex 0 --inputAnatomicalVolume T1_ACPC_Axial.nhdr \
--outputTransformName ACPC_rigid.mat --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, [[gtractCoRegAnatomy]]

'''Example:'''

% gtractCoRegAnatomy --inputVolume DWI_coreg.nhdr --transformType Bspline \
--vectorIndex 0 --inputRigidTransform ACPC_rigid.mat --inputAnatomicalVolume T1_ACPC_Axial.nhdr \
--outputTransformName ACPC_bspline.mat --numberOfIterations 1000

{|
| 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]] 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 [[gtractInvertBSplineTransform]] 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 artifacts.

'''Example'''
% gtractInvertBSplineTransform --inputReferenceVolume T1_ACPC.nhdr --inputTransform ACPC_bspline.xfm \
--outputTransform ACPC_Inverse_Bspline.xfm

===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]] - Resamples a mask or label - Image pixel type is signed short and neareast neigbor interpolation is used

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

* [[gtractResampleB0]] - Resamples the B0 image - Image pixel type is signed short and linear interpolation is used

'''Example:'''
% gtractResampleB0 --inputVolume DWI_Coreg.nhdr --inputAnatomicalVolume T1_ACPC.nhdr \
--inputTransform ACPC_Rigid.txt --vectorIndex 0 \
--transformType Rigid --outputVolume B0_ACPC_rigid.nii.gz

* [[gtractResampleAnisotropy]] - Resamples an anisotropy map - Image pixel type is float and linear interpolation is used

'''Example:'''
% gtractResampleAnisotropy --inputAnisotropyVolume FA.nhdr --inputAnatomicalVolume T1_ACPC.nhdr \
--inputTransform ACPC_Rigid.txt --vectorIndex 0 \
--transformType Rigid --outputVolume FA_ACPC_rigid.nii.gz

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.

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:

# Free Tracking
# Streamlines Tracking
# Graph Search Tracking
# Guided 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 primary 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 anisotropy, 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 [[gtractFiberTracking]] can be obtained using the '--help' option.

'''Example:'''
% gtractFiberTracking --inputTensorVolume Tensor.nhdr \
--inputAnisotropyVolume FA.nhdr \
--trackingMethod Free \
--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 arguments for [[gtractFiberTracking]] are available with the '--help' option at the command line.

'''Example:'''
% gtractFiberTracking --inputTensorVolume Tensor.nhdr \
--inputAnisotropyVolume FA.nhdr \
--trackingMethod Streamline \
--inputStartingSeedsLabelMapVolume startingSeedsLabelMap.nhdr \
--startingSeedsLabel 1 \
--inputEndingSeedsLabelMapVolume endingSeedsLabelMap.nhdr \
--endingSeedsLabel 2 \
--curvatureThreshold 60 \
--outputTract streamlineTracking.vtk

===Graph Search Tracking===
The Graph Search 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-ambiguous regions and utilizes branching and a graph search algorithm in ambigous regions. Ambiguous 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 secondary 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 algorithm 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 arguments for [[gtractFiberTracking]] can be obtained using the '--help' option from the command line.

'''Example:'''
% gtractFiberTracking --inputTensorVolume Tensor.nhdr \
--inputAnisotropyVolume FA.nhdr \
--trackingMethod GraphSearch \
--inputStartingSeedsLabelMapVolume startingSeedsLabelMap.nhdr \
--startingSeedsLabel 1 \
--inputEndingSeedsLabelMapVolume endingSeedsLabelMap.nhdr \
--endingSeedsLabel 2 \
--inputTract guideFiber.vtk \
--curvatureThreshold 60 \
--branchingThreshold 0.20 \
--maximumBranchPoints 5 \
--branchingAngle 45.0 \
--outputTract graphSearchTracking.vtk

===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]] 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 [[gtractFiberTracking]] his algorithm. The user must specify the guide fiber when running this program.

'''Example:'''
% gtractFiberTracking --inputTensorVolume Tensor.nhdr \
--inputAnisotropyVolume FA.nhdr \
--inputStartingSeedsLabelMapVolume --startingSeed.nhdr \
--startingSeedsLabel 1 \
--inputEndingSeedsLabelMapVolume --endingSeed.nhdr \
--endingSeedsLable 2 \
--inputTract guide.vtk \
--trackingMethod Guided \
--guidedCurvatureThreshold 30.0 \
--maximumGuideDistance 12.0 \
--outputTract guidedTracking.vtk

===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]] 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]] 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-12-21T05:13:37Z

Matsuij: /* Guided Tracking */

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

<pre>
DicomToNrrdConverter --inputDicomDirectory DICOM_directory_name --outputVolume NRRD_file_name.nrrd
</pre>

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 ==
The following are links to the full documentation of GTRACT's programs. The same documentation can be accessed on the command line using the following:

<pre>
${GTRACT_prog_name} --help
</pre>

* [[extractNrrdVectorIndex|extractNrrdVectorIndex Documentation]]
* [[gtractAnisotropyMap|gtractAnisotropyMap Documentation]]
* [[gtractAverageBvalues|gtractAverageBvalues Documentation]]
* [[gtractClipAnisotropy|gtractClipAnisotropy Documentation]]
* [[gtractCoRegAnatomy|gtractCoRegAnatomy Documentation]]
* [[gtractConcatDwi|gtractConcatDwi Documentation]]
* [[gtractCopyImageOrientation|gtractCopyImageOrientation Documentation]]
* [[gtractCoregBvalues|gtractCoregBvalues Documentation]]
* [[gtractCreateGuideFiber|gtractCreateGuideFiber Documentation]]
* [[gtractFiberTracking|gtractFiberTracking Documentation]]
* [[gtractResampleAnisotropy|gtractResampleAnisotropy Documentation]]
* [[gtractResampleB0|gtractResampleB0 Documentation]]
* [[gtractTensor|gtractTensor 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 \
--outputVolume outputImage.nhdr

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

'''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]] 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 [[gtractCoRegAnatomy]]

'''Example'''
% gtractCoRegAnatomy --inputVolume DWI_coreg.nhdr --transformType Rigid \
--vectorIndex 0 --inputAnatomicalVolume T1_ACPC_Axial.nhdr \
--outputTransformName ACPC_rigid.mat --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, [[gtractCoRegAnatomy]]

'''Example:'''

% gtractCoRegAnatomy --inputVolume DWI_coreg.nhdr --transformType Bspline \
--vectorIndex 0 --inputRigidTransform ACPC_rigid.mat --inputAnatomicalVolume T1_ACPC_Axial.nhdr \
--outputTransformName ACPC_bspline.mat --numberOfIterations 1000

{|
| 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]] 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 [[gtractInvertBSplineTransform]] 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 artifacts.

'''Example'''
% gtractInvertBSplineTransform --inputReferenceVolume T1_ACPC.nhdr --inputTransform ACPC_bspline.xfm \
--outputTransform ACPC_Inverse_Bspline.xfm

===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]] - Resamples a mask or label - Image pixel type is signed short and neareast neigbor interpolation is used

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

* [[gtractResampleB0]] - Resamples the B0 image - Image pixel type is signed short and linear interpolation is used

'''Example:'''
% gtractResampleB0 --inputVolume DWI_Coreg.nhdr --inputAnatomicalVolume T1_ACPC.nhdr \
--inputTransform ACPC_Rigid.txt --vectorIndex 0 \
--transformType Rigid --outputVolume B0_ACPC_rigid.nii.gz

* [[gtractResampleAnisotropy]] - Resamples an anisotropy map - Image pixel type is float and linear interpolation is used

'''Example:'''
% gtractResampleAnisotropy --inputAnisotropyVolume FA.nhdr --inputAnatomicalVolume T1_ACPC.nhdr \
--inputTransform ACPC_Rigid.txt --vectorIndex 0 \
--transformType Rigid --outputVolume FA_ACPC_rigid.nii.gz

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.

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:

# Free Tracking
# Streamlines Tracking
# Graph Search Tracking
# Guided 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 primary 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 anisotropy, 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 [[gtractFiberTracking]] can be obtained using the '--help' option.

'''Example:'''
% gtractFiberTracking --inputTensorVolume Tensor.nhdr \
--inputAnisotropyVolume FA.nhdr \
--trackingMethod Free \
--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 arguments for [[gtractFiberTracking]] are available with the '--help' option at the command line.

'''Example:'''
% gtractFiberTracking --inputTensorVolume Tensor.nhdr \
--inputAnisotropyVolume FA.nhdr \
--trackingMethod Streamline \
--inputStartingSeedsLabelMapVolume startingSeedsLabelMap.nhdr \
--startingSeedsLabel 1 \
--inputEndingSeedsLabelMapVolume endingSeedsLabelMap.nhdr \
--endingSeedsLabel 2 \
--curvatureThreshold 60 \
--outputTract streamlineTracking.vtk

===Graph Search Tracking===
The Graph Search 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-ambiguous regions and utilizes branching and a graph search algorithm in ambigous regions. Ambiguous 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 secondary 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 algorithm 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 arguments for [[gtractFiberTracking]] can be obtained using the '--help' option from the command line.

'''Example:'''
% gtractFiberTracking --inputTensorVolume Tensor.nhdr \
--inputAnisotropyVolume FA.nhdr \
--trackingMethod GraphSearch \
--inputStartingSeedsLabelMapVolume startingSeedsLabelMap.nhdr \
--startingSeedsLabel 1 \
--inputEndingSeedsLabelMapVolume endingSeedsLabelMap.nhdr \
--endingSeedsLabel 2 \
--inputTract guideFiber.vtk \
--curvatureThreshold 60 \
--branchingThreshold 0.20 \
--maximumBranchPoints 5 \
--branchingAngle 45.0 \
--outputTract graphSearchTracking.vtk

===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]] 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 [[gtractFiberTracking]] his algorithm. The user must specify the guide fiber when running this program.

'''Example:'''
% gtractFiberTracking --inputTensorVolume Tensor.nhdr \
--inputAnisotropyVolume FA.nhdr \
--inputStartingSeedsLabelMapVolume --startingSeed.nhdr \
--startingSeedsLabel 1 \
--inputEndingSeedsLabelMapVolume --endingSeed.nhdr \
--endingSeedsLable 2 \
--inputTract inputTract.vtk \
--trackingMethod Guided \
--guidedCurvatureThreshold 30.0 \
--maximumGuideDistance 12.0 \
--outputTract guidedTrack.vtk

===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]] 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]] 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-12-21T01:06:20Z

Matsuij: /* Graph Search Tracking */

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

<pre>
DicomToNrrdConverter --inputDicomDirectory DICOM_directory_name --outputVolume NRRD_file_name.nrrd
</pre>

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 ==
The following are links to the full documentation of GTRACT's programs. The same documentation can be accessed on the command line using the following:

<pre>
${GTRACT_prog_name} --help
</pre>

* [[extractNrrdVectorIndex|extractNrrdVectorIndex Documentation]]
* [[gtractAnisotropyMap|gtractAnisotropyMap Documentation]]
* [[gtractAverageBvalues|gtractAverageBvalues Documentation]]
* [[gtractClipAnisotropy|gtractClipAnisotropy Documentation]]
* [[gtractCoRegAnatomy|gtractCoRegAnatomy Documentation]]
* [[gtractConcatDwi|gtractConcatDwi Documentation]]
* [[gtractCopyImageOrientation|gtractCopyImageOrientation Documentation]]
* [[gtractCoregBvalues|gtractCoregBvalues Documentation]]
* [[gtractCreateGuideFiber|gtractCreateGuideFiber Documentation]]
* [[gtractFiberTracking|gtractFiberTracking Documentation]]
* [[gtractResampleAnisotropy|gtractResampleAnisotropy Documentation]]
* [[gtractResampleB0|gtractResampleB0 Documentation]]
* [[gtractTensor|gtractTensor 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 \
--outputVolume outputImage.nhdr

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

'''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]] 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 [[gtractCoRegAnatomy]]

'''Example'''
% gtractCoRegAnatomy --inputVolume DWI_coreg.nhdr --transformType Rigid \
--vectorIndex 0 --inputAnatomicalVolume T1_ACPC_Axial.nhdr \
--outputTransformName ACPC_rigid.mat --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, [[gtractCoRegAnatomy]]

'''Example:'''

% gtractCoRegAnatomy --inputVolume DWI_coreg.nhdr --transformType Bspline \
--vectorIndex 0 --inputRigidTransform ACPC_rigid.mat --inputAnatomicalVolume T1_ACPC_Axial.nhdr \
--outputTransformName ACPC_bspline.mat --numberOfIterations 1000

{|
| 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]] 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 [[gtractInvertBSplineTransform]] 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 artifacts.

'''Example'''
% gtractInvertBSplineTransform --inputReferenceVolume T1_ACPC.nhdr --inputTransform ACPC_bspline.xfm \
--outputTransform ACPC_Inverse_Bspline.xfm

===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]] - Resamples a mask or label - Image pixel type is signed short and neareast neigbor interpolation is used

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

* [[gtractResampleB0]] - Resamples the B0 image - Image pixel type is signed short and linear interpolation is used

'''Example:'''
% gtractResampleB0 --inputVolume DWI_Coreg.nhdr --inputAnatomicalVolume T1_ACPC.nhdr \
--inputTransform ACPC_Rigid.txt --vectorIndex 0 \
--transformType Rigid --outputVolume B0_ACPC_rigid.nii.gz

* [[gtractResampleAnisotropy]] - Resamples an anisotropy map - Image pixel type is float and linear interpolation is used

'''Example:'''
% gtractResampleAnisotropy --inputAnisotropyVolume FA.nhdr --inputAnatomicalVolume T1_ACPC.nhdr \
--inputTransform ACPC_Rigid.txt --vectorIndex 0 \
--transformType Rigid --outputVolume FA_ACPC_rigid.nii.gz

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.

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:

# Free Tracking
# Streamlines Tracking
# Graph Search Tracking
# Guided 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 primary 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 anisotropy, 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 [[gtractFiberTracking]] can be obtained using the '--help' option.

'''Example:'''
% gtractFiberTracking --inputTensorVolume Tensor.nhdr \
--inputAnisotropyVolume FA.nhdr \
--trackingMethod Free \
--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 arguments for [[gtractFiberTracking]] are available with the '--help' option at the command line.

'''Example:'''
% gtractFiberTracking --inputTensorVolume Tensor.nhdr \
--inputAnisotropyVolume FA.nhdr \
--trackingMethod Streamline \
--inputStartingSeedsLabelMapVolume startingSeedsLabelMap.nhdr \
--startingSeedsLabel 1 \
--inputEndingSeedsLabelMapVolume endingSeedsLabelMap.nhdr \
--endingSeedsLabel 2 \
--curvatureThreshold 60 \
--outputTract streamlineTracking.vtk

===Graph Search Tracking===
The Graph Search 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-ambiguous regions and utilizes branching and a graph search algorithm in ambigous regions. Ambiguous 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 secondary 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 algorithm 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 arguments for [[gtractFiberTracking]] can be obtained using the '--help' option from the command line.

'''Example:'''
% gtractFiberTracking --inputTensorVolume Tensor.nhdr \
--inputAnisotropyVolume FA.nhdr \
--trackingMethod GraphSearch \
--inputStartingSeedsLabelMapVolume startingSeedsLabelMap.nhdr \
--startingSeedsLabel 1 \
--inputEndingSeedsLabelMapVolume endingSeedsLabelMap.nhdr \
--endingSeedsLabel 2 \
--inputTract guideFiber.vtk \
--curvatureThreshold 60 \
--branchingThreshold 0.20 \
--maximumBranchPoints 5 \
--branchingAngle 45.0 \
--outputTract graphSearchTracking.vtk

===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]] 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 [[gtractCreateGuideFiber]] implements this algorithm. The user must specify the guide fiber when running this program.

'''Example:'''
% gtractFiberTracking

===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]] 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]] 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-12-21T01:05:53Z

Matsuij: /* Graph Search Tracking */

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

<pre>
DicomToNrrdConverter --inputDicomDirectory DICOM_directory_name --outputVolume NRRD_file_name.nrrd
</pre>

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 ==
The following are links to the full documentation of GTRACT's programs. The same documentation can be accessed on the command line using the following:

<pre>
${GTRACT_prog_name} --help
</pre>

* [[extractNrrdVectorIndex|extractNrrdVectorIndex Documentation]]
* [[gtractAnisotropyMap|gtractAnisotropyMap Documentation]]
* [[gtractAverageBvalues|gtractAverageBvalues Documentation]]
* [[gtractClipAnisotropy|gtractClipAnisotropy Documentation]]
* [[gtractCoRegAnatomy|gtractCoRegAnatomy Documentation]]
* [[gtractConcatDwi|gtractConcatDwi Documentation]]
* [[gtractCopyImageOrientation|gtractCopyImageOrientation Documentation]]
* [[gtractCoregBvalues|gtractCoregBvalues Documentation]]
* [[gtractCreateGuideFiber|gtractCreateGuideFiber Documentation]]
* [[gtractFiberTracking|gtractFiberTracking Documentation]]
* [[gtractResampleAnisotropy|gtractResampleAnisotropy Documentation]]
* [[gtractResampleB0|gtractResampleB0 Documentation]]
* [[gtractTensor|gtractTensor 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 \
--outputVolume outputImage.nhdr

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

'''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]] 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 [[gtractCoRegAnatomy]]

'''Example'''
% gtractCoRegAnatomy --inputVolume DWI_coreg.nhdr --transformType Rigid \
--vectorIndex 0 --inputAnatomicalVolume T1_ACPC_Axial.nhdr \
--outputTransformName ACPC_rigid.mat --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, [[gtractCoRegAnatomy]]

'''Example:'''

% gtractCoRegAnatomy --inputVolume DWI_coreg.nhdr --transformType Bspline \
--vectorIndex 0 --inputRigidTransform ACPC_rigid.mat --inputAnatomicalVolume T1_ACPC_Axial.nhdr \
--outputTransformName ACPC_bspline.mat --numberOfIterations 1000

{|
| 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]] 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 [[gtractInvertBSplineTransform]] 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 artifacts.

'''Example'''
% gtractInvertBSplineTransform --inputReferenceVolume T1_ACPC.nhdr --inputTransform ACPC_bspline.xfm \
--outputTransform ACPC_Inverse_Bspline.xfm

===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]] - Resamples a mask or label - Image pixel type is signed short and neareast neigbor interpolation is used

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

* [[gtractResampleB0]] - Resamples the B0 image - Image pixel type is signed short and linear interpolation is used

'''Example:'''
% gtractResampleB0 --inputVolume DWI_Coreg.nhdr --inputAnatomicalVolume T1_ACPC.nhdr \
--inputTransform ACPC_Rigid.txt --vectorIndex 0 \
--transformType Rigid --outputVolume B0_ACPC_rigid.nii.gz

* [[gtractResampleAnisotropy]] - Resamples an anisotropy map - Image pixel type is float and linear interpolation is used

'''Example:'''
% gtractResampleAnisotropy --inputAnisotropyVolume FA.nhdr --inputAnatomicalVolume T1_ACPC.nhdr \
--inputTransform ACPC_Rigid.txt --vectorIndex 0 \
--transformType Rigid --outputVolume FA_ACPC_rigid.nii.gz

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.

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:

# Free Tracking
# Streamlines Tracking
# Graph Search Tracking
# Guided 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 primary 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 anisotropy, 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 [[gtractFiberTracking]] can be obtained using the '--help' option.

'''Example:'''
% gtractFiberTracking --inputTensorVolume Tensor.nhdr \
--inputAnisotropyVolume FA.nhdr \
--trackingMethod Free \
--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 arguments for [[gtractFiberTracking]] are available with the '--help' option at the command line.

'''Example:'''
% gtractFiberTracking --inputTensorVolume Tensor.nhdr \
--inputAnisotropyVolume FA.nhdr \
--trackingMethod Streamline \
--inputStartingSeedsLabelMapVolume startingSeedsLabelMap.nhdr \
--startingSeedsLabel 1 \
--inputEndingSeedsLabelMapVolume endingSeedsLabelMap.nhdr \
--endingSeedsLabel 2 \
--curvatureThreshold 60 \
--outputTract streamlineTracking.vtk

===Graph Search Tracking===
The Graph Search 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-ambiguous regions and utilizes branching and a graph search algorithm in ambigous regions. Ambiguous 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 secondary 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 algorithm 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 arguments for [[gtractFiberTracking]] can be obtained using the '--help' option from the command line.

'''Example:'''
% gtractGraphSearchTracking --inputTensorVolume Tensor.nhdr \
--inputAnisotropyVolume FA.nhdr \
--trackingMethod GraphSearch \
--inputStartingSeedsLabelMapVolume startingSeedsLabelMap.nhdr \
--startingSeedsLabel 1 \
--inputEndingSeedsLabelMapVolume endingSeedsLabelMap.nhdr \
--endingSeedsLabel 2 \
--inputTract guideFiber.vtk \
--curvatureThreshold 60 \
--branchingThreshold 0.20 \
--maximumBranchPoints 5 \
--branchingAngle 45.0 \
--outputTract graphSearchTracking.vtk

===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]] 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 [[gtractCreateGuideFiber]] implements this algorithm. The user must specify the guide fiber when running this program.

'''Example:'''
% gtractFiberTracking

===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]] 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]] 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-12-21T01:04:45Z

Matsuij: /* Guided Tracking */

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

<pre>
DicomToNrrdConverter --inputDicomDirectory DICOM_directory_name --outputVolume NRRD_file_name.nrrd
</pre>

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 ==
The following are links to the full documentation of GTRACT's programs. The same documentation can be accessed on the command line using the following:

<pre>
${GTRACT_prog_name} --help
</pre>

* [[extractNrrdVectorIndex|extractNrrdVectorIndex Documentation]]
* [[gtractAnisotropyMap|gtractAnisotropyMap Documentation]]
* [[gtractAverageBvalues|gtractAverageBvalues Documentation]]
* [[gtractClipAnisotropy|gtractClipAnisotropy Documentation]]
* [[gtractCoRegAnatomy|gtractCoRegAnatomy Documentation]]
* [[gtractConcatDwi|gtractConcatDwi Documentation]]
* [[gtractCopyImageOrientation|gtractCopyImageOrientation Documentation]]
* [[gtractCoregBvalues|gtractCoregBvalues Documentation]]
* [[gtractCreateGuideFiber|gtractCreateGuideFiber Documentation]]
* [[gtractFiberTracking|gtractFiberTracking Documentation]]
* [[gtractResampleAnisotropy|gtractResampleAnisotropy Documentation]]
* [[gtractResampleB0|gtractResampleB0 Documentation]]
* [[gtractTensor|gtractTensor 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 \
--outputVolume outputImage.nhdr

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

'''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]] 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 [[gtractCoRegAnatomy]]

'''Example'''
% gtractCoRegAnatomy --inputVolume DWI_coreg.nhdr --transformType Rigid \
--vectorIndex 0 --inputAnatomicalVolume T1_ACPC_Axial.nhdr \
--outputTransformName ACPC_rigid.mat --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, [[gtractCoRegAnatomy]]

'''Example:'''

% gtractCoRegAnatomy --inputVolume DWI_coreg.nhdr --transformType Bspline \
--vectorIndex 0 --inputRigidTransform ACPC_rigid.mat --inputAnatomicalVolume T1_ACPC_Axial.nhdr \
--outputTransformName ACPC_bspline.mat --numberOfIterations 1000

{|
| 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]] 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 [[gtractInvertBSplineTransform]] 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 artifacts.

'''Example'''
% gtractInvertBSplineTransform --inputReferenceVolume T1_ACPC.nhdr --inputTransform ACPC_bspline.xfm \
--outputTransform ACPC_Inverse_Bspline.xfm

===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]] - Resamples a mask or label - Image pixel type is signed short and neareast neigbor interpolation is used

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

* [[gtractResampleB0]] - Resamples the B0 image - Image pixel type is signed short and linear interpolation is used

'''Example:'''
% gtractResampleB0 --inputVolume DWI_Coreg.nhdr --inputAnatomicalVolume T1_ACPC.nhdr \
--inputTransform ACPC_Rigid.txt --vectorIndex 0 \
--transformType Rigid --outputVolume B0_ACPC_rigid.nii.gz

* [[gtractResampleAnisotropy]] - Resamples an anisotropy map - Image pixel type is float and linear interpolation is used

'''Example:'''
% gtractResampleAnisotropy --inputAnisotropyVolume FA.nhdr --inputAnatomicalVolume T1_ACPC.nhdr \
--inputTransform ACPC_Rigid.txt --vectorIndex 0 \
--transformType Rigid --outputVolume FA_ACPC_rigid.nii.gz

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.

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:

# Free Tracking
# Streamlines Tracking
# Graph Search Tracking
# Guided 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 primary 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 anisotropy, 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 [[gtractFiberTracking]] can be obtained using the '--help' option.

'''Example:'''
% gtractFiberTracking --inputTensorVolume Tensor.nhdr \
--inputAnisotropyVolume FA.nhdr \
--trackingMethod Free \
--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 arguments for [[gtractFiberTracking]] are available with the '--help' option at the command line.

'''Example:'''
% gtractFiberTracking --inputTensorVolume Tensor.nhdr \
--inputAnisotropyVolume FA.nhdr \
--trackingMethod Streamline \
--inputStartingSeedsLabelMapVolume startingSeedsLabelMap.nhdr \
--startingSeedsLabel 1 \
--inputEndingSeedsLabelMapVolume endingSeedsLabelMap.nhdr \
--endingSeedsLabel 2 \
--curvatureThreshold 60 \
--outputTract streamlineTracking.vtk

===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-ambiguous regions and utilizes branching and a graph search algorithm in ambigous regions. Ambiguous 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 secondary 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 algorithm 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 arguments for [[gtractFiberTracking]] can be obtained using the '--help' option from the command line.

'''Example:'''
% gtractGraphSearchTracking --inputTensorVolume Tensor.nhdr \
--inputAnisotropyVolume FA.nhdr \
--trackingMethod GraphSearch \
--inputStartingSeedsLabelMapVolume startingSeedsLabelMap.nhdr \
--startingSeedsLabel 1 \
--inputEndingSeedsLabelMapVolume endingSeedsLabelMap.nhdr \
--endingSeedsLabel 2 \
--inputTract guideFiber.vtk \
--curvatureThreshold 60 \
--branchingThreshold 0.20 \
--maximumBranchPoints 5 \
--branchingAngle 45.0 \
--outputTract graphSearchTracking.vtk

===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]] 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 [[gtractCreateGuideFiber]] implements this algorithm. The user must specify the guide fiber when running this program.

'''Example:'''
% gtractFiberTracking

===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]] 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]] 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-12-21T01:03:05Z

Matsuij: /* Free Tracking */

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

<pre>
DicomToNrrdConverter --inputDicomDirectory DICOM_directory_name --outputVolume NRRD_file_name.nrrd
</pre>

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 ==
The following are links to the full documentation of GTRACT's programs. The same documentation can be accessed on the command line using the following:

<pre>
${GTRACT_prog_name} --help
</pre>

* [[extractNrrdVectorIndex|extractNrrdVectorIndex Documentation]]
* [[gtractAnisotropyMap|gtractAnisotropyMap Documentation]]
* [[gtractAverageBvalues|gtractAverageBvalues Documentation]]
* [[gtractClipAnisotropy|gtractClipAnisotropy Documentation]]
* [[gtractCoRegAnatomy|gtractCoRegAnatomy Documentation]]
* [[gtractConcatDwi|gtractConcatDwi Documentation]]
* [[gtractCopyImageOrientation|gtractCopyImageOrientation Documentation]]
* [[gtractCoregBvalues|gtractCoregBvalues Documentation]]
* [[gtractCreateGuideFiber|gtractCreateGuideFiber Documentation]]
* [[gtractFiberTracking|gtractFiberTracking Documentation]]
* [[gtractResampleAnisotropy|gtractResampleAnisotropy Documentation]]
* [[gtractResampleB0|gtractResampleB0 Documentation]]
* [[gtractTensor|gtractTensor 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 \
--outputVolume outputImage.nhdr

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

'''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]] 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 [[gtractCoRegAnatomy]]

'''Example'''
% gtractCoRegAnatomy --inputVolume DWI_coreg.nhdr --transformType Rigid \
--vectorIndex 0 --inputAnatomicalVolume T1_ACPC_Axial.nhdr \
--outputTransformName ACPC_rigid.mat --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, [[gtractCoRegAnatomy]]

'''Example:'''

% gtractCoRegAnatomy --inputVolume DWI_coreg.nhdr --transformType Bspline \
--vectorIndex 0 --inputRigidTransform ACPC_rigid.mat --inputAnatomicalVolume T1_ACPC_Axial.nhdr \
--outputTransformName ACPC_bspline.mat --numberOfIterations 1000

{|
| 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]] 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 [[gtractInvertBSplineTransform]] 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 artifacts.

'''Example'''
% gtractInvertBSplineTransform --inputReferenceVolume T1_ACPC.nhdr --inputTransform ACPC_bspline.xfm \
--outputTransform ACPC_Inverse_Bspline.xfm

===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]] - Resamples a mask or label - Image pixel type is signed short and neareast neigbor interpolation is used

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

* [[gtractResampleB0]] - Resamples the B0 image - Image pixel type is signed short and linear interpolation is used

'''Example:'''
% gtractResampleB0 --inputVolume DWI_Coreg.nhdr --inputAnatomicalVolume T1_ACPC.nhdr \
--inputTransform ACPC_Rigid.txt --vectorIndex 0 \
--transformType Rigid --outputVolume B0_ACPC_rigid.nii.gz

* [[gtractResampleAnisotropy]] - Resamples an anisotropy map - Image pixel type is float and linear interpolation is used

'''Example:'''
% gtractResampleAnisotropy --inputAnisotropyVolume FA.nhdr --inputAnatomicalVolume T1_ACPC.nhdr \
--inputTransform ACPC_Rigid.txt --vectorIndex 0 \
--transformType Rigid --outputVolume FA_ACPC_rigid.nii.gz

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.

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:

# Free Tracking
# Streamlines Tracking
# Graph Search Tracking
# Guided 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 primary 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 anisotropy, 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 [[gtractFiberTracking]] can be obtained using the '--help' option.

'''Example:'''
% gtractFiberTracking --inputTensorVolume Tensor.nhdr \
--inputAnisotropyVolume FA.nhdr \
--trackingMethod Free \
--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 arguments for [[gtractFiberTracking]] are available with the '--help' option at the command line.

'''Example:'''
% gtractFiberTracking --inputTensorVolume Tensor.nhdr \
--inputAnisotropyVolume FA.nhdr \
--trackingMethod Streamline \
--inputStartingSeedsLabelMapVolume startingSeedsLabelMap.nhdr \
--startingSeedsLabel 1 \
--inputEndingSeedsLabelMapVolume endingSeedsLabelMap.nhdr \
--endingSeedsLabel 2 \
--curvatureThreshold 60 \
--outputTract streamlineTracking.vtk

===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-ambiguous regions and utilizes branching and a graph search algorithm in ambigous regions. Ambiguous 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 secondary 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 algorithm 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 arguments for [[gtractFiberTracking]] can be obtained using the '--help' option from the command line.

'''Example:'''
% gtractGraphSearchTracking --inputTensorVolume Tensor.nhdr \
--inputAnisotropyVolume FA.nhdr \
--trackingMethod GraphSearch \
--inputStartingSeedsLabelMapVolume startingSeedsLabelMap.nhdr \
--startingSeedsLabel 1 \
--inputEndingSeedsLabelMapVolume endingSeedsLabelMap.nhdr \
--endingSeedsLabel 2 \
--inputTract guideFiber.vtk \
--curvatureThreshold 60 \
--branchingThreshold 0.20 \
--maximumBranchPoints 5 \
--branchingAngle 45.0 \
--outputTract graphSearchTracking.vtk

===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 [[gtractFiberTracking]] 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 [[gtractCreateGuideFiber]] implements this algorithm. The user must specify the guide fiber when running this program.

'''Example:'''
% gtractFiberTracking

===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]] 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]] 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-12-21T01:02:47Z

Matsuij: /* Free Tracking */

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

<pre>
DicomToNrrdConverter --inputDicomDirectory DICOM_directory_name --outputVolume NRRD_file_name.nrrd
</pre>

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 ==
The following are links to the full documentation of GTRACT's programs. The same documentation can be accessed on the command line using the following:

<pre>
${GTRACT_prog_name} --help
</pre>

* [[extractNrrdVectorIndex|extractNrrdVectorIndex Documentation]]
* [[gtractAnisotropyMap|gtractAnisotropyMap Documentation]]
* [[gtractAverageBvalues|gtractAverageBvalues Documentation]]
* [[gtractClipAnisotropy|gtractClipAnisotropy Documentation]]
* [[gtractCoRegAnatomy|gtractCoRegAnatomy Documentation]]
* [[gtractConcatDwi|gtractConcatDwi Documentation]]
* [[gtractCopyImageOrientation|gtractCopyImageOrientation Documentation]]
* [[gtractCoregBvalues|gtractCoregBvalues Documentation]]
* [[gtractCreateGuideFiber|gtractCreateGuideFiber Documentation]]
* [[gtractFiberTracking|gtractFiberTracking Documentation]]
* [[gtractResampleAnisotropy|gtractResampleAnisotropy Documentation]]
* [[gtractResampleB0|gtractResampleB0 Documentation]]
* [[gtractTensor|gtractTensor 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 \
--outputVolume outputImage.nhdr

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

'''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]] 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 [[gtractCoRegAnatomy]]

'''Example'''
% gtractCoRegAnatomy --inputVolume DWI_coreg.nhdr --transformType Rigid \
--vectorIndex 0 --inputAnatomicalVolume T1_ACPC_Axial.nhdr \
--outputTransformName ACPC_rigid.mat --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, [[gtractCoRegAnatomy]]

'''Example:'''

% gtractCoRegAnatomy --inputVolume DWI_coreg.nhdr --transformType Bspline \
--vectorIndex 0 --inputRigidTransform ACPC_rigid.mat --inputAnatomicalVolume T1_ACPC_Axial.nhdr \
--outputTransformName ACPC_bspline.mat --numberOfIterations 1000

{|
| 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]] 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 [[gtractInvertBSplineTransform]] 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 artifacts.

'''Example'''
% gtractInvertBSplineTransform --inputReferenceVolume T1_ACPC.nhdr --inputTransform ACPC_bspline.xfm \
--outputTransform ACPC_Inverse_Bspline.xfm

===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]] - Resamples a mask or label - Image pixel type is signed short and neareast neigbor interpolation is used

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

* [[gtractResampleB0]] - Resamples the B0 image - Image pixel type is signed short and linear interpolation is used

'''Example:'''
% gtractResampleB0 --inputVolume DWI_Coreg.nhdr --inputAnatomicalVolume T1_ACPC.nhdr \
--inputTransform ACPC_Rigid.txt --vectorIndex 0 \
--transformType Rigid --outputVolume B0_ACPC_rigid.nii.gz

* [[gtractResampleAnisotropy]] - Resamples an anisotropy map - Image pixel type is float and linear interpolation is used

'''Example:'''
% gtractResampleAnisotropy --inputAnisotropyVolume FA.nhdr --inputAnatomicalVolume T1_ACPC.nhdr \
--inputTransform ACPC_Rigid.txt --vectorIndex 0 \
--transformType Rigid --outputVolume FA_ACPC_rigid.nii.gz

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.

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:

# Free Tracking
# Streamlines Tracking
# Graph Search Tracking
# Guided 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 primary 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 anisotropy, 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 [[gtractFiberTracking]] can be obtained using the '--help' option.

'''Example:'''
% gtractFiberTracking --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 arguments for [[gtractFiberTracking]] are available with the '--help' option at the command line.

'''Example:'''
% gtractFiberTracking --inputTensorVolume Tensor.nhdr \
--inputAnisotropyVolume FA.nhdr \
--trackingMethod Streamline \
--inputStartingSeedsLabelMapVolume startingSeedsLabelMap.nhdr \
--startingSeedsLabel 1 \
--inputEndingSeedsLabelMapVolume endingSeedsLabelMap.nhdr \
--endingSeedsLabel 2 \
--curvatureThreshold 60 \
--outputTract streamlineTracking.vtk

===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-ambiguous regions and utilizes branching and a graph search algorithm in ambigous regions. Ambiguous 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 secondary 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 algorithm 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 arguments for [[gtractFiberTracking]] can be obtained using the '--help' option from the command line.

'''Example:'''
% gtractGraphSearchTracking --inputTensorVolume Tensor.nhdr \
--inputAnisotropyVolume FA.nhdr \
--trackingMethod GraphSearch \
--inputStartingSeedsLabelMapVolume startingSeedsLabelMap.nhdr \
--startingSeedsLabel 1 \
--inputEndingSeedsLabelMapVolume endingSeedsLabelMap.nhdr \
--endingSeedsLabel 2 \
--inputTract guideFiber.vtk \
--curvatureThreshold 60 \
--branchingThreshold 0.20 \
--maximumBranchPoints 5 \
--branchingAngle 45.0 \
--outputTract graphSearchTracking.vtk

===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 [[gtractFiberTracking]] 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 [[gtractCreateGuideFiber]] implements this algorithm. The user must specify the guide fiber when running this program.

'''Example:'''
% gtractFiberTracking

===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]] 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]] 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-12-21T01:02:35Z

Matsuij: /* Streamline Tracking */

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

<pre>
DicomToNrrdConverter --inputDicomDirectory DICOM_directory_name --outputVolume NRRD_file_name.nrrd
</pre>

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 ==
The following are links to the full documentation of GTRACT's programs. The same documentation can be accessed on the command line using the following:

<pre>
${GTRACT_prog_name} --help
</pre>

* [[extractNrrdVectorIndex|extractNrrdVectorIndex Documentation]]
* [[gtractAnisotropyMap|gtractAnisotropyMap Documentation]]
* [[gtractAverageBvalues|gtractAverageBvalues Documentation]]
* [[gtractClipAnisotropy|gtractClipAnisotropy Documentation]]
* [[gtractCoRegAnatomy|gtractCoRegAnatomy Documentation]]
* [[gtractConcatDwi|gtractConcatDwi Documentation]]
* [[gtractCopyImageOrientation|gtractCopyImageOrientation Documentation]]
* [[gtractCoregBvalues|gtractCoregBvalues Documentation]]
* [[gtractCreateGuideFiber|gtractCreateGuideFiber Documentation]]
* [[gtractFiberTracking|gtractFiberTracking Documentation]]
* [[gtractResampleAnisotropy|gtractResampleAnisotropy Documentation]]
* [[gtractResampleB0|gtractResampleB0 Documentation]]
* [[gtractTensor|gtractTensor 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 \
--outputVolume outputImage.nhdr

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

'''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]] 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 [[gtractCoRegAnatomy]]

'''Example'''
% gtractCoRegAnatomy --inputVolume DWI_coreg.nhdr --transformType Rigid \
--vectorIndex 0 --inputAnatomicalVolume T1_ACPC_Axial.nhdr \
--outputTransformName ACPC_rigid.mat --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, [[gtractCoRegAnatomy]]

'''Example:'''

% gtractCoRegAnatomy --inputVolume DWI_coreg.nhdr --transformType Bspline \
--vectorIndex 0 --inputRigidTransform ACPC_rigid.mat --inputAnatomicalVolume T1_ACPC_Axial.nhdr \
--outputTransformName ACPC_bspline.mat --numberOfIterations 1000

{|
| 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]] 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 [[gtractInvertBSplineTransform]] 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 artifacts.

'''Example'''
% gtractInvertBSplineTransform --inputReferenceVolume T1_ACPC.nhdr --inputTransform ACPC_bspline.xfm \
--outputTransform ACPC_Inverse_Bspline.xfm

===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]] - Resamples a mask or label - Image pixel type is signed short and neareast neigbor interpolation is used

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

* [[gtractResampleB0]] - Resamples the B0 image - Image pixel type is signed short and linear interpolation is used

'''Example:'''
% gtractResampleB0 --inputVolume DWI_Coreg.nhdr --inputAnatomicalVolume T1_ACPC.nhdr \
--inputTransform ACPC_Rigid.txt --vectorIndex 0 \
--transformType Rigid --outputVolume B0_ACPC_rigid.nii.gz

* [[gtractResampleAnisotropy]] - Resamples an anisotropy map - Image pixel type is float and linear interpolation is used

'''Example:'''
% gtractResampleAnisotropy --inputAnisotropyVolume FA.nhdr --inputAnatomicalVolume T1_ACPC.nhdr \
--inputTransform ACPC_Rigid.txt --vectorIndex 0 \
--transformType Rigid --outputVolume FA_ACPC_rigid.nii.gz

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.

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:

# Free Tracking
# Streamlines Tracking
# Graph Search Tracking
# Guided 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 primary 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 anisotropy, 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 [[gtractFiberTracking]] 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 arguments for [[gtractFiberTracking]] are available with the '--help' option at the command line.

'''Example:'''
% gtractFiberTracking --inputTensorVolume Tensor.nhdr \
--inputAnisotropyVolume FA.nhdr \
--trackingMethod Streamline \
--inputStartingSeedsLabelMapVolume startingSeedsLabelMap.nhdr \
--startingSeedsLabel 1 \
--inputEndingSeedsLabelMapVolume endingSeedsLabelMap.nhdr \
--endingSeedsLabel 2 \
--curvatureThreshold 60 \
--outputTract streamlineTracking.vtk

===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-ambiguous regions and utilizes branching and a graph search algorithm in ambigous regions. Ambiguous 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 secondary 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 algorithm 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 arguments for [[gtractFiberTracking]] can be obtained using the '--help' option from the command line.

'''Example:'''
% gtractGraphSearchTracking --inputTensorVolume Tensor.nhdr \
--inputAnisotropyVolume FA.nhdr \
--trackingMethod GraphSearch \
--inputStartingSeedsLabelMapVolume startingSeedsLabelMap.nhdr \
--startingSeedsLabel 1 \
--inputEndingSeedsLabelMapVolume endingSeedsLabelMap.nhdr \
--endingSeedsLabel 2 \
--inputTract guideFiber.vtk \
--curvatureThreshold 60 \
--branchingThreshold 0.20 \
--maximumBranchPoints 5 \
--branchingAngle 45.0 \
--outputTract graphSearchTracking.vtk

===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 [[gtractFiberTracking]] 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 [[gtractCreateGuideFiber]] implements this algorithm. The user must specify the guide fiber when running this program.

'''Example:'''
% gtractFiberTracking

===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]] 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]] 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-12-21T01:02:15Z

Matsuij: /* Streamline Tracking */

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

<pre>
DicomToNrrdConverter --inputDicomDirectory DICOM_directory_name --outputVolume NRRD_file_name.nrrd
</pre>

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 ==
The following are links to the full documentation of GTRACT's programs. The same documentation can be accessed on the command line using the following:

<pre>
${GTRACT_prog_name} --help
</pre>

* [[extractNrrdVectorIndex|extractNrrdVectorIndex Documentation]]
* [[gtractAnisotropyMap|gtractAnisotropyMap Documentation]]
* [[gtractAverageBvalues|gtractAverageBvalues Documentation]]
* [[gtractClipAnisotropy|gtractClipAnisotropy Documentation]]
* [[gtractCoRegAnatomy|gtractCoRegAnatomy Documentation]]
* [[gtractConcatDwi|gtractConcatDwi Documentation]]
* [[gtractCopyImageOrientation|gtractCopyImageOrientation Documentation]]
* [[gtractCoregBvalues|gtractCoregBvalues Documentation]]
* [[gtractCreateGuideFiber|gtractCreateGuideFiber Documentation]]
* [[gtractFiberTracking|gtractFiberTracking Documentation]]
* [[gtractResampleAnisotropy|gtractResampleAnisotropy Documentation]]
* [[gtractResampleB0|gtractResampleB0 Documentation]]
* [[gtractTensor|gtractTensor 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 \
--outputVolume outputImage.nhdr

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

'''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]] 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 [[gtractCoRegAnatomy]]

'''Example'''
% gtractCoRegAnatomy --inputVolume DWI_coreg.nhdr --transformType Rigid \
--vectorIndex 0 --inputAnatomicalVolume T1_ACPC_Axial.nhdr \
--outputTransformName ACPC_rigid.mat --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, [[gtractCoRegAnatomy]]

'''Example:'''

% gtractCoRegAnatomy --inputVolume DWI_coreg.nhdr --transformType Bspline \
--vectorIndex 0 --inputRigidTransform ACPC_rigid.mat --inputAnatomicalVolume T1_ACPC_Axial.nhdr \
--outputTransformName ACPC_bspline.mat --numberOfIterations 1000

{|
| 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]] 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 [[gtractInvertBSplineTransform]] 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 artifacts.

'''Example'''
% gtractInvertBSplineTransform --inputReferenceVolume T1_ACPC.nhdr --inputTransform ACPC_bspline.xfm \
--outputTransform ACPC_Inverse_Bspline.xfm

===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]] - Resamples a mask or label - Image pixel type is signed short and neareast neigbor interpolation is used

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

* [[gtractResampleB0]] - Resamples the B0 image - Image pixel type is signed short and linear interpolation is used

'''Example:'''
% gtractResampleB0 --inputVolume DWI_Coreg.nhdr --inputAnatomicalVolume T1_ACPC.nhdr \
--inputTransform ACPC_Rigid.txt --vectorIndex 0 \
--transformType Rigid --outputVolume B0_ACPC_rigid.nii.gz

* [[gtractResampleAnisotropy]] - Resamples an anisotropy map - Image pixel type is float and linear interpolation is used

'''Example:'''
% gtractResampleAnisotropy --inputAnisotropyVolume FA.nhdr --inputAnatomicalVolume T1_ACPC.nhdr \
--inputTransform ACPC_Rigid.txt --vectorIndex 0 \
--transformType Rigid --outputVolume FA_ACPC_rigid.nii.gz

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.

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:

# Free Tracking
# Streamlines Tracking
# Graph Search Tracking
# Guided 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 primary 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 anisotropy, 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 [[gtractFiberTracking]] 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 arguments for [[gtractFiberTracking]] are available with the '--help' option at the command line.

'''Example:'''
% gtractStreamlineTracking --inputTensorVolume Tensor.nhdr \
--inputAnisotropyVolume FA.nhdr \
--trackingMethod Streamline \
--inputStartingSeedsLabelMapVolume startingSeedsLabelMap.nhdr \
--startingSeedsLabel 1 \
--inputEndingSeedsLabelMapVolume endingSeedsLabelMap.nhdr \
--endingSeedsLabel 2 \
--curvatureThreshold 60 \
--outputTract streamlineTracking.vtk

===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-ambiguous regions and utilizes branching and a graph search algorithm in ambigous regions. Ambiguous 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 secondary 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 algorithm 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 arguments for [[gtractFiberTracking]] can be obtained using the '--help' option from the command line.

'''Example:'''
% gtractGraphSearchTracking --inputTensorVolume Tensor.nhdr \
--inputAnisotropyVolume FA.nhdr \
--trackingMethod GraphSearch \
--inputStartingSeedsLabelMapVolume startingSeedsLabelMap.nhdr \
--startingSeedsLabel 1 \
--inputEndingSeedsLabelMapVolume endingSeedsLabelMap.nhdr \
--endingSeedsLabel 2 \
--inputTract guideFiber.vtk \
--curvatureThreshold 60 \
--branchingThreshold 0.20 \
--maximumBranchPoints 5 \
--branchingAngle 45.0 \
--outputTract graphSearchTracking.vtk

===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 [[gtractFiberTracking]] 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 [[gtractCreateGuideFiber]] implements this algorithm. The user must specify the guide fiber when running this program.

'''Example:'''
% gtractFiberTracking

===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]] 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]] 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-12-21T01:01:35Z

Matsuij: /* Graph Search Tracking */

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

<pre>
DicomToNrrdConverter --inputDicomDirectory DICOM_directory_name --outputVolume NRRD_file_name.nrrd
</pre>

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 ==
The following are links to the full documentation of GTRACT's programs. The same documentation can be accessed on the command line using the following:

<pre>
${GTRACT_prog_name} --help
</pre>

* [[extractNrrdVectorIndex|extractNrrdVectorIndex Documentation]]
* [[gtractAnisotropyMap|gtractAnisotropyMap Documentation]]
* [[gtractAverageBvalues|gtractAverageBvalues Documentation]]
* [[gtractClipAnisotropy|gtractClipAnisotropy Documentation]]
* [[gtractCoRegAnatomy|gtractCoRegAnatomy Documentation]]
* [[gtractConcatDwi|gtractConcatDwi Documentation]]
* [[gtractCopyImageOrientation|gtractCopyImageOrientation Documentation]]
* [[gtractCoregBvalues|gtractCoregBvalues Documentation]]
* [[gtractCreateGuideFiber|gtractCreateGuideFiber Documentation]]
* [[gtractFiberTracking|gtractFiberTracking Documentation]]
* [[gtractResampleAnisotropy|gtractResampleAnisotropy Documentation]]
* [[gtractResampleB0|gtractResampleB0 Documentation]]
* [[gtractTensor|gtractTensor 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 \
--outputVolume outputImage.nhdr

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

'''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]] 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 [[gtractCoRegAnatomy]]

'''Example'''
% gtractCoRegAnatomy --inputVolume DWI_coreg.nhdr --transformType Rigid \
--vectorIndex 0 --inputAnatomicalVolume T1_ACPC_Axial.nhdr \
--outputTransformName ACPC_rigid.mat --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, [[gtractCoRegAnatomy]]

'''Example:'''

% gtractCoRegAnatomy --inputVolume DWI_coreg.nhdr --transformType Bspline \
--vectorIndex 0 --inputRigidTransform ACPC_rigid.mat --inputAnatomicalVolume T1_ACPC_Axial.nhdr \
--outputTransformName ACPC_bspline.mat --numberOfIterations 1000

{|
| 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]] 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 [[gtractInvertBSplineTransform]] 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 artifacts.

'''Example'''
% gtractInvertBSplineTransform --inputReferenceVolume T1_ACPC.nhdr --inputTransform ACPC_bspline.xfm \
--outputTransform ACPC_Inverse_Bspline.xfm

===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]] - Resamples a mask or label - Image pixel type is signed short and neareast neigbor interpolation is used

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

* [[gtractResampleB0]] - Resamples the B0 image - Image pixel type is signed short and linear interpolation is used

'''Example:'''
% gtractResampleB0 --inputVolume DWI_Coreg.nhdr --inputAnatomicalVolume T1_ACPC.nhdr \
--inputTransform ACPC_Rigid.txt --vectorIndex 0 \
--transformType Rigid --outputVolume B0_ACPC_rigid.nii.gz

* [[gtractResampleAnisotropy]] - Resamples an anisotropy map - Image pixel type is float and linear interpolation is used

'''Example:'''
% gtractResampleAnisotropy --inputAnisotropyVolume FA.nhdr --inputAnatomicalVolume T1_ACPC.nhdr \
--inputTransform ACPC_Rigid.txt --vectorIndex 0 \
--transformType Rigid --outputVolume FA_ACPC_rigid.nii.gz

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.

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:

# Free Tracking
# Streamlines Tracking
# Graph Search Tracking
# Guided 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 primary 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 anisotropy, 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 [[gtractFiberTracking]] 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 arguments for [[gtractFiberTracking]] are available with the '--help' option at the command line.

'''Example:'''
% gtractStreamlineTracking --inputTensorVolume Tensor.nhdr \
--inputAnisotropyVolume FA.nhdr \
--inputStartingSeedsLabelMapVolume startingSeedsLabelMap.nhdr \
--startingSeedsLabel 1 \
--inputEndingSeedsLabelMapVolume endingSeedsLabelMap.nhdr \
--endingSeedsLabel 2 \
--curvatureThreshold 60 \
--outputTract streamlineTracking.vtk

===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-ambiguous regions and utilizes branching and a graph search algorithm in ambigous regions. Ambiguous 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 secondary 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 algorithm 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 arguments for [[gtractFiberTracking]] can be obtained using the '--help' option from the command line.

'''Example:'''
% gtractGraphSearchTracking --inputTensorVolume Tensor.nhdr \
--inputAnisotropyVolume FA.nhdr \
--trackingMethod GraphSearch \
--inputStartingSeedsLabelMapVolume startingSeedsLabelMap.nhdr \
--startingSeedsLabel 1 \
--inputEndingSeedsLabelMapVolume endingSeedsLabelMap.nhdr \
--endingSeedsLabel 2 \
--inputTract guideFiber.vtk \
--curvatureThreshold 60 \
--branchingThreshold 0.20 \
--maximumBranchPoints 5 \
--branchingAngle 45.0 \
--outputTract graphSearchTracking.vtk

===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 [[gtractFiberTracking]] 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 [[gtractCreateGuideFiber]] implements this algorithm. The user must specify the guide fiber when running this program.

'''Example:'''
% gtractFiberTracking

===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]] 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]] 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-12-21T00:58:18Z

Matsuij: /* Streamline Tracking */

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

<pre>
DicomToNrrdConverter --inputDicomDirectory DICOM_directory_name --outputVolume NRRD_file_name.nrrd
</pre>

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 ==
The following are links to the full documentation of GTRACT's programs. The same documentation can be accessed on the command line using the following:

<pre>
${GTRACT_prog_name} --help
</pre>

* [[extractNrrdVectorIndex|extractNrrdVectorIndex Documentation]]
* [[gtractAnisotropyMap|gtractAnisotropyMap Documentation]]
* [[gtractAverageBvalues|gtractAverageBvalues Documentation]]
* [[gtractClipAnisotropy|gtractClipAnisotropy Documentation]]
* [[gtractCoRegAnatomy|gtractCoRegAnatomy Documentation]]
* [[gtractConcatDwi|gtractConcatDwi Documentation]]
* [[gtractCopyImageOrientation|gtractCopyImageOrientation Documentation]]
* [[gtractCoregBvalues|gtractCoregBvalues Documentation]]
* [[gtractCreateGuideFiber|gtractCreateGuideFiber Documentation]]
* [[gtractFiberTracking|gtractFiberTracking Documentation]]
* [[gtractResampleAnisotropy|gtractResampleAnisotropy Documentation]]
* [[gtractResampleB0|gtractResampleB0 Documentation]]
* [[gtractTensor|gtractTensor 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 \
--outputVolume outputImage.nhdr

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

'''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]] 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 [[gtractCoRegAnatomy]]

'''Example'''
% gtractCoRegAnatomy --inputVolume DWI_coreg.nhdr --transformType Rigid \
--vectorIndex 0 --inputAnatomicalVolume T1_ACPC_Axial.nhdr \
--outputTransformName ACPC_rigid.mat --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, [[gtractCoRegAnatomy]]

'''Example:'''

% gtractCoRegAnatomy --inputVolume DWI_coreg.nhdr --transformType Bspline \
--vectorIndex 0 --inputRigidTransform ACPC_rigid.mat --inputAnatomicalVolume T1_ACPC_Axial.nhdr \
--outputTransformName ACPC_bspline.mat --numberOfIterations 1000

{|
| 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]] 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 [[gtractInvertBSplineTransform]] 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 artifacts.

'''Example'''
% gtractInvertBSplineTransform --inputReferenceVolume T1_ACPC.nhdr --inputTransform ACPC_bspline.xfm \
--outputTransform ACPC_Inverse_Bspline.xfm

===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]] - Resamples a mask or label - Image pixel type is signed short and neareast neigbor interpolation is used

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

* [[gtractResampleB0]] - Resamples the B0 image - Image pixel type is signed short and linear interpolation is used

'''Example:'''
% gtractResampleB0 --inputVolume DWI_Coreg.nhdr --inputAnatomicalVolume T1_ACPC.nhdr \
--inputTransform ACPC_Rigid.txt --vectorIndex 0 \
--transformType Rigid --outputVolume B0_ACPC_rigid.nii.gz

* [[gtractResampleAnisotropy]] - Resamples an anisotropy map - Image pixel type is float and linear interpolation is used

'''Example:'''
% gtractResampleAnisotropy --inputAnisotropyVolume FA.nhdr --inputAnatomicalVolume T1_ACPC.nhdr \
--inputTransform ACPC_Rigid.txt --vectorIndex 0 \
--transformType Rigid --outputVolume FA_ACPC_rigid.nii.gz

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.

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:

# Free Tracking
# Streamlines Tracking
# Graph Search Tracking
# Guided 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 primary 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 anisotropy, 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 [[gtractFiberTracking]] 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 arguments for [[gtractFiberTracking]] are available with the '--help' option at the command line.

'''Example:'''
% gtractStreamlineTracking --inputTensorVolume Tensor.nhdr \
--inputAnisotropyVolume FA.nhdr \
--inputStartingSeedsLabelMapVolume startingSeedsLabelMap.nhdr \
--startingSeedsLabel 1 \
--inputEndingSeedsLabelMapVolume endingSeedsLabelMap.nhdr \
--endingSeedsLabel 2 \
--curvatureThreshold 60 \
--outputTract streamlineTracking.vtk

===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-ambiguous regions and utilizes branching and a graph search algorithm in ambigous regions. Ambiguous 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 secondary 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 algorithm 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 arguments for [[gtractFiberTracking]] 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 [[gtractFiberTracking]] 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 [[gtractCreateGuideFiber]] implements this algorithm. The user must specify the guide fiber when running this program.

'''Example:'''
% gtractFiberTracking

===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]] 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]] 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-12-21T00:56:42Z

Matsuij: /* Resampling Images */

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

<pre>
DicomToNrrdConverter --inputDicomDirectory DICOM_directory_name --outputVolume NRRD_file_name.nrrd
</pre>

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 ==
The following are links to the full documentation of GTRACT's programs. The same documentation can be accessed on the command line using the following:

<pre>
${GTRACT_prog_name} --help
</pre>

* [[extractNrrdVectorIndex|extractNrrdVectorIndex Documentation]]
* [[gtractAnisotropyMap|gtractAnisotropyMap Documentation]]
* [[gtractAverageBvalues|gtractAverageBvalues Documentation]]
* [[gtractClipAnisotropy|gtractClipAnisotropy Documentation]]
* [[gtractCoRegAnatomy|gtractCoRegAnatomy Documentation]]
* [[gtractConcatDwi|gtractConcatDwi Documentation]]
* [[gtractCopyImageOrientation|gtractCopyImageOrientation Documentation]]
* [[gtractCoregBvalues|gtractCoregBvalues Documentation]]
* [[gtractCreateGuideFiber|gtractCreateGuideFiber Documentation]]
* [[gtractFiberTracking|gtractFiberTracking Documentation]]
* [[gtractResampleAnisotropy|gtractResampleAnisotropy Documentation]]
* [[gtractResampleB0|gtractResampleB0 Documentation]]
* [[gtractTensor|gtractTensor 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 \
--outputVolume outputImage.nhdr

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

'''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]] 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 [[gtractCoRegAnatomy]]

'''Example'''
% gtractCoRegAnatomy --inputVolume DWI_coreg.nhdr --transformType Rigid \
--vectorIndex 0 --inputAnatomicalVolume T1_ACPC_Axial.nhdr \
--outputTransformName ACPC_rigid.mat --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, [[gtractCoRegAnatomy]]

'''Example:'''

% gtractCoRegAnatomy --inputVolume DWI_coreg.nhdr --transformType Bspline \
--vectorIndex 0 --inputRigidTransform ACPC_rigid.mat --inputAnatomicalVolume T1_ACPC_Axial.nhdr \
--outputTransformName ACPC_bspline.mat --numberOfIterations 1000

{|
| 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]] 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 [[gtractInvertBSplineTransform]] 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 artifacts.

'''Example'''
% gtractInvertBSplineTransform --inputReferenceVolume T1_ACPC.nhdr --inputTransform ACPC_bspline.xfm \
--outputTransform ACPC_Inverse_Bspline.xfm

===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]] - Resamples a mask or label - Image pixel type is signed short and neareast neigbor interpolation is used

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

* [[gtractResampleB0]] - Resamples the B0 image - Image pixel type is signed short and linear interpolation is used

'''Example:'''
% gtractResampleB0 --inputVolume DWI_Coreg.nhdr --inputAnatomicalVolume T1_ACPC.nhdr \
--inputTransform ACPC_Rigid.txt --vectorIndex 0 \
--transformType Rigid --outputVolume B0_ACPC_rigid.nii.gz

* [[gtractResampleAnisotropy]] - Resamples an anisotropy map - Image pixel type is float and linear interpolation is used

'''Example:'''
% gtractResampleAnisotropy --inputAnisotropyVolume FA.nhdr --inputAnatomicalVolume T1_ACPC.nhdr \
--inputTransform ACPC_Rigid.txt --vectorIndex 0 \
--transformType Rigid --outputVolume FA_ACPC_rigid.nii.gz

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.

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:

# Free Tracking
# Streamlines Tracking
# Graph Search Tracking
# Guided 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 primary 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 anisotropy, 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 [[gtractFiberTracking]] 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 arguments for [[gtractFiberTracking]] are available with the '--help' option at the command line.

'''Example:'''
% gtractStreamlineTracking --inputTensorVolume Tensor.nhdr \
--inputAnisotropyVolume FA.nhdr \
--inputStartingSeedsLabelMapVolume startingSeedsLabelMap.nhdr \
--startingSeedsLabel 1 --seedThreshold 0.25 \
--inputEndingSeedsLabelMapVolume endingSeedsLabelMap.nhdr \
--endingSeedsLabel 2 \
--curvatureThreshold 60 \
--outputTract streamlineTracking.vtk

===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-ambiguous regions and utilizes branching and a graph search algorithm in ambigous regions. Ambiguous 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 secondary 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 algorithm 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 arguments for [[gtractFiberTracking]] 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 [[gtractFiberTracking]] 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 [[gtractCreateGuideFiber]] implements this algorithm. The user must specify the guide fiber when running this program.

'''Example:'''
% gtractFiberTracking

===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]] 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]] 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-12-21T00:55:53Z

Matsuij: /* Streamline Tracking */

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

<pre>
DicomToNrrdConverter --inputDicomDirectory DICOM_directory_name --outputVolume NRRD_file_name.nrrd
</pre>

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 ==
The following are links to the full documentation of GTRACT's programs. The same documentation can be accessed on the command line using the following:

<pre>
${GTRACT_prog_name} --help
</pre>

* [[extractNrrdVectorIndex|extractNrrdVectorIndex Documentation]]
* [[gtractAnisotropyMap|gtractAnisotropyMap Documentation]]
* [[gtractAverageBvalues|gtractAverageBvalues Documentation]]
* [[gtractClipAnisotropy|gtractClipAnisotropy Documentation]]
* [[gtractCoRegAnatomy|gtractCoRegAnatomy Documentation]]
* [[gtractConcatDwi|gtractConcatDwi Documentation]]
* [[gtractCopyImageOrientation|gtractCopyImageOrientation Documentation]]
* [[gtractCoregBvalues|gtractCoregBvalues Documentation]]
* [[gtractCreateGuideFiber|gtractCreateGuideFiber Documentation]]
* [[gtractFiberTracking|gtractFiberTracking Documentation]]
* [[gtractResampleAnisotropy|gtractResampleAnisotropy Documentation]]
* [[gtractResampleB0|gtractResampleB0 Documentation]]
* [[gtractTensor|gtractTensor 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 \
--outputVolume outputImage.nhdr

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

'''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]] 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 [[gtractCoRegAnatomy]]

'''Example'''
% gtractCoRegAnatomy --inputVolume DWI_coreg.nhdr --transformType Rigid \
--vectorIndex 0 --inputAnatomicalVolume T1_ACPC_Axial.nhdr \
--outputTransformName ACPC_rigid.mat --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, [[gtractCoRegAnatomy]]

'''Example:'''

% gtractCoRegAnatomy --inputVolume DWI_coreg.nhdr --transformType Bspline \
--vectorIndex 0 --inputRigidTransform ACPC_rigid.mat --inputAnatomicalVolume T1_ACPC_Axial.nhdr \
--outputTransformName ACPC_bspline.mat --numberOfIterations 1000

{|
| 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]] 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 [[gtractInvertBSplineTransform]] 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 artifacts.

'''Example'''
% gtractInvertBSplineTransform --inputReferenceVolume T1_ACPC.nhdr --inputTransform ACPC_bspline.xfm \
--outputTransform ACPC_Inverse_Bspline.xfm

===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]] - Resamples a mask or label - Image pixel type is signed short and neareast neigbor interpolation is used

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

* [[gtractResampleB0]] - Resamples the B0 image - Image pixel type is signed short and linear interpolation is used

'''Example:'''
% gtractResampleB0 --inputVolume DWI_Coreg.nhdr --inputAnatomicalVolume T1_ACPC.nhdr \
--inputTransform ACPC_Rigid.txt --vectorIndex 0 \
--transformType Rigid --outputVolume B0_ACPC_rigid.nii.gz

* [[gtractResampleAnisotropy]] - Resamples an anisotropy map - Image pixel type is float and linear interpolation is used

'''Example:'''
% gtractResampleAnisotropy --inputAnisotropyVolume FA_map.nhdr --inputAnatomicalVolume T1_ACPC.nhdr \
--inputTransform ACPC_Rigid.txt --vectorIndex 0 \
--transformType Rigid --outputVolume FA_ACPC_rigid.nii.gz

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.

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:

# Free Tracking
# Streamlines Tracking
# Graph Search Tracking
# Guided 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 primary 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 anisotropy, 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 [[gtractFiberTracking]] 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 arguments for [[gtractFiberTracking]] are available with the '--help' option at the command line.

'''Example:'''
% gtractStreamlineTracking --inputTensorVolume Tensor.nhdr \
--inputAnisotropyVolume FA.nhdr \
--inputStartingSeedsLabelMapVolume startingSeedsLabelMap.nhdr \
--startingSeedsLabel 1 --seedThreshold 0.25 \
--inputEndingSeedsLabelMapVolume endingSeedsLabelMap.nhdr \
--endingSeedsLabel 2 \
--curvatureThreshold 60 \
--outputTract streamlineTracking.vtk

===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-ambiguous regions and utilizes branching and a graph search algorithm in ambigous regions. Ambiguous 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 secondary 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 algorithm 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 arguments for [[gtractFiberTracking]] 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 [[gtractFiberTracking]] 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 [[gtractCreateGuideFiber]] implements this algorithm. The user must specify the guide fiber when running this program.

'''Example:'''
% gtractFiberTracking

===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]] 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]] 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-12-21T00:36:19Z

Matsuij: /* Resampling Images */

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

<pre>
DicomToNrrdConverter --inputDicomDirectory DICOM_directory_name --outputVolume NRRD_file_name.nrrd
</pre>

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 ==
The following are links to the full documentation of GTRACT's programs. The same documentation can be accessed on the command line using the following:

<pre>
${GTRACT_prog_name} --help
</pre>

* [[extractNrrdVectorIndex|extractNrrdVectorIndex Documentation]]
* [[gtractAnisotropyMap|gtractAnisotropyMap Documentation]]
* [[gtractAverageBvalues|gtractAverageBvalues Documentation]]
* [[gtractClipAnisotropy|gtractClipAnisotropy Documentation]]
* [[gtractCoRegAnatomy|gtractCoRegAnatomy Documentation]]
* [[gtractConcatDwi|gtractConcatDwi Documentation]]
* [[gtractCopyImageOrientation|gtractCopyImageOrientation Documentation]]
* [[gtractCoregBvalues|gtractCoregBvalues Documentation]]
* [[gtractCreateGuideFiber|gtractCreateGuideFiber Documentation]]
* [[gtractFiberTracking|gtractFiberTracking Documentation]]
* [[gtractResampleAnisotropy|gtractResampleAnisotropy Documentation]]
* [[gtractResampleB0|gtractResampleB0 Documentation]]
* [[gtractTensor|gtractTensor 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 \
--outputVolume outputImage.nhdr

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

'''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]] 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 [[gtractCoRegAnatomy]]

'''Example'''
% gtractCoRegAnatomy --inputVolume DWI_coreg.nhdr --transformType Rigid \
--vectorIndex 0 --inputAnatomicalVolume T1_ACPC_Axial.nhdr \
--outputTransformName ACPC_rigid.mat --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, [[gtractCoRegAnatomy]]

'''Example:'''

% gtractCoRegAnatomy --inputVolume DWI_coreg.nhdr --transformType Bspline \
--vectorIndex 0 --inputRigidTransform ACPC_rigid.mat --inputAnatomicalVolume T1_ACPC_Axial.nhdr \
--outputTransformName ACPC_bspline.mat --numberOfIterations 1000

{|
| 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]] 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 [[gtractInvertBSplineTransform]] 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 artifacts.

'''Example'''
% gtractInvertBSplineTransform --inputReferenceVolume T1_ACPC.nhdr --inputTransform ACPC_bspline.xfm \
--outputTransform ACPC_Inverse_Bspline.xfm

===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]] - Resamples a mask or label - Image pixel type is signed short and neareast neigbor interpolation is used

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

* [[gtractResampleB0]] - Resamples the B0 image - Image pixel type is signed short and linear interpolation is used

'''Example:'''
% gtractResampleB0 --inputVolume DWI_Coreg.nhdr --inputAnatomicalVolume T1_ACPC.nhdr \
--inputTransform ACPC_Rigid.txt --vectorIndex 0 \
--transformType Rigid --outputVolume B0_ACPC_rigid.nii.gz

* [[gtractResampleAnisotropy]] - Resamples an anisotropy map - Image pixel type is float and linear interpolation is used

'''Example:'''
% gtractResampleAnisotropy --inputAnisotropyVolume FA_map.nhdr --inputAnatomicalVolume T1_ACPC.nhdr \
--inputTransform ACPC_Rigid.txt --vectorIndex 0 \
--transformType Rigid --outputVolume FA_ACPC_rigid.nii.gz

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.

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:

# Free Tracking
# Streamlines Tracking
# Graph Search Tracking
# Guided 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 primary 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 anisotropy, 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 [[gtractFiberTracking]] 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 arguments for [[gtractFiberTracking]] 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-ambiguous regions and utilizes branching and a graph search algorithm in ambigous regions. Ambiguous 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 secondary 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 algorithm 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 arguments for [[gtractFiberTracking]] 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 [[gtractFiberTracking]] 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 [[gtractCreateGuideFiber]] implements this algorithm. The user must specify the guide fiber when running this program.

'''Example:'''
% gtractFiberTracking

===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]] 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]] 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-12-21T00:27:09Z

Matsuij: /* Resampling Images */

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

<pre>
DicomToNrrdConverter --inputDicomDirectory DICOM_directory_name --outputVolume NRRD_file_name.nrrd
</pre>

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 ==
The following are links to the full documentation of GTRACT's programs. The same documentation can be accessed on the command line using the following:

<pre>
${GTRACT_prog_name} --help
</pre>

* [[extractNrrdVectorIndex|extractNrrdVectorIndex Documentation]]
* [[gtractAnisotropyMap|gtractAnisotropyMap Documentation]]
* [[gtractAverageBvalues|gtractAverageBvalues Documentation]]
* [[gtractClipAnisotropy|gtractClipAnisotropy Documentation]]
* [[gtractCoRegAnatomy|gtractCoRegAnatomy Documentation]]
* [[gtractConcatDwi|gtractConcatDwi Documentation]]
* [[gtractCopyImageOrientation|gtractCopyImageOrientation Documentation]]
* [[gtractCoregBvalues|gtractCoregBvalues Documentation]]
* [[gtractCreateGuideFiber|gtractCreateGuideFiber Documentation]]
* [[gtractFiberTracking|gtractFiberTracking Documentation]]
* [[gtractResampleAnisotropy|gtractResampleAnisotropy Documentation]]
* [[gtractResampleB0|gtractResampleB0 Documentation]]
* [[gtractTensor|gtractTensor 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 \
--outputVolume outputImage.nhdr

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

'''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]] 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 [[gtractCoRegAnatomy]]

'''Example'''
% gtractCoRegAnatomy --inputVolume DWI_coreg.nhdr --transformType Rigid \
--vectorIndex 0 --inputAnatomicalVolume T1_ACPC_Axial.nhdr \
--outputTransformName ACPC_rigid.mat --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, [[gtractCoRegAnatomy]]

'''Example:'''

% gtractCoRegAnatomy --inputVolume DWI_coreg.nhdr --transformType Bspline \
--vectorIndex 0 --inputRigidTransform ACPC_rigid.mat --inputAnatomicalVolume T1_ACPC_Axial.nhdr \
--outputTransformName ACPC_bspline.mat --numberOfIterations 1000

{|
| 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]] 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 [[gtractInvertBSplineTransform]] 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 artifacts.

'''Example'''
% gtractInvertBSplineTransform --inputReferenceVolume T1_ACPC.nhdr --inputTransform ACPC_bspline.xfm \
--outputTransform ACPC_Inverse_Bspline.xfm

===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]] - Resamples a mask or label - Image pixel type is signed short and neareast neigbor interpolation is used

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

* [[gtractResampleB0]] - Resamples the B0 image - Image pixel type is signed short and linear interpolation is used

'''Example:'''
% gtractResampleB0 --inputVolume DWI_Coreg.nhdr --inputAnatomicalVolume T1_ACPC.nhdr \
--inputTransform ACPC_Rigid.xfm --vectorIndex 0 \
--transformType Rigid --outputVolume Resampled_B0.nhdr

* [[gtractResampleAnisotropy]] - 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.

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:

# Free Tracking
# Streamlines Tracking
# Graph Search Tracking
# Guided 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 primary 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 anisotropy, 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 [[gtractFiberTracking]] 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 arguments for [[gtractFiberTracking]] 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-ambiguous regions and utilizes branching and a graph search algorithm in ambigous regions. Ambiguous 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 secondary 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 algorithm 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 arguments for [[gtractFiberTracking]] 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 [[gtractFiberTracking]] 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 [[gtractCreateGuideFiber]] implements this algorithm. The user must specify the guide fiber when running this program.

'''Example:'''
% gtractFiberTracking

===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]] 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]] 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-12-21T00:23:14Z

Matsuij: /* Resampling Images */

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

<pre>
DicomToNrrdConverter --inputDicomDirectory DICOM_directory_name --outputVolume NRRD_file_name.nrrd
</pre>

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 ==
The following are links to the full documentation of GTRACT's programs. The same documentation can be accessed on the command line using the following:

<pre>
${GTRACT_prog_name} --help
</pre>

* [[extractNrrdVectorIndex|extractNrrdVectorIndex Documentation]]
* [[gtractAnisotropyMap|gtractAnisotropyMap Documentation]]
* [[gtractAverageBvalues|gtractAverageBvalues Documentation]]
* [[gtractClipAnisotropy|gtractClipAnisotropy Documentation]]
* [[gtractCoRegAnatomy|gtractCoRegAnatomy Documentation]]
* [[gtractConcatDwi|gtractConcatDwi Documentation]]
* [[gtractCopyImageOrientation|gtractCopyImageOrientation Documentation]]
* [[gtractCoregBvalues|gtractCoregBvalues Documentation]]
* [[gtractCreateGuideFiber|gtractCreateGuideFiber Documentation]]
* [[gtractFiberTracking|gtractFiberTracking Documentation]]
* [[gtractResampleAnisotropy|gtractResampleAnisotropy Documentation]]
* [[gtractResampleB0|gtractResampleB0 Documentation]]
* [[gtractTensor|gtractTensor 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 \
--outputVolume outputImage.nhdr

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

'''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]] 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 [[gtractCoRegAnatomy]]

'''Example'''
% gtractCoRegAnatomy --inputVolume DWI_coreg.nhdr --transformType Rigid \
--vectorIndex 0 --inputAnatomicalVolume T1_ACPC_Axial.nhdr \
--outputTransformName ACPC_rigid.mat --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, [[gtractCoRegAnatomy]]

'''Example:'''

% gtractCoRegAnatomy --inputVolume DWI_coreg.nhdr --transformType Bspline \
--vectorIndex 0 --inputRigidTransform ACPC_rigid.mat --inputAnatomicalVolume T1_ACPC_Axial.nhdr \
--outputTransformName ACPC_bspline.mat --numberOfIterations 1000

{|
| 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]] 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 [[gtractInvertBSplineTransform]] 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 artifacts.

'''Example'''
% gtractInvertBSplineTransform --inputReferenceVolume T1_ACPC.nhdr --inputTransform ACPC_bspline.xfm \
--outputTransform ACPC_Inverse_Bspline.xfm

===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]] - Resamples a mask or label - Image pixel type is signed short and neareast neigbor interpolation is used
* [[gtractResampleB0]] - Resamples the B0 image - Image pixel type is signed short and linear interpolation is used
* [[gtractResampleAnisotropy]] - 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.

'''Examples:'''
% 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:

# Free Tracking
# Streamlines Tracking
# Graph Search Tracking
# Guided 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 primary 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 anisotropy, 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 [[gtractFiberTracking]] 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 arguments for [[gtractFiberTracking]] 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-ambiguous regions and utilizes branching and a graph search algorithm in ambigous regions. Ambiguous 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 secondary 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 algorithm 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 arguments for [[gtractFiberTracking]] 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 [[gtractFiberTracking]] 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 [[gtractCreateGuideFiber]] implements this algorithm. The user must specify the guide fiber when running this program.

'''Example:'''
% gtractFiberTracking

===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]] 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]] 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-12-21T00:22:10Z

Matsuij: /* Resampling Images */

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

<pre>
DicomToNrrdConverter --inputDicomDirectory DICOM_directory_name --outputVolume NRRD_file_name.nrrd
</pre>

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 ==
The following are links to the full documentation of GTRACT's programs. The same documentation can be accessed on the command line using the following:

<pre>
${GTRACT_prog_name} --help
</pre>

* [[extractNrrdVectorIndex|extractNrrdVectorIndex Documentation]]
* [[gtractAnisotropyMap|gtractAnisotropyMap Documentation]]
* [[gtractAverageBvalues|gtractAverageBvalues Documentation]]
* [[gtractClipAnisotropy|gtractClipAnisotropy Documentation]]
* [[gtractCoRegAnatomy|gtractCoRegAnatomy Documentation]]
* [[gtractConcatDwi|gtractConcatDwi Documentation]]
* [[gtractCopyImageOrientation|gtractCopyImageOrientation Documentation]]
* [[gtractCoregBvalues|gtractCoregBvalues Documentation]]
* [[gtractCreateGuideFiber|gtractCreateGuideFiber Documentation]]
* [[gtractFiberTracking|gtractFiberTracking Documentation]]
* [[gtractResampleAnisotropy|gtractResampleAnisotropy Documentation]]
* [[gtractResampleB0|gtractResampleB0 Documentation]]
* [[gtractTensor|gtractTensor 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 \
--outputVolume outputImage.nhdr

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

'''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]] 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 [[gtractCoRegAnatomy]]

'''Example'''
% gtractCoRegAnatomy --inputVolume DWI_coreg.nhdr --transformType Rigid \
--vectorIndex 0 --inputAnatomicalVolume T1_ACPC_Axial.nhdr \
--outputTransformName ACPC_rigid.mat --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, [[gtractCoRegAnatomy]]

'''Example:'''

% gtractCoRegAnatomy --inputVolume DWI_coreg.nhdr --transformType Bspline \
--vectorIndex 0 --inputRigidTransform ACPC_rigid.mat --inputAnatomicalVolume T1_ACPC_Axial.nhdr \
--outputTransformName ACPC_bspline.mat --numberOfIterations 1000

{|
| 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]] 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 [[gtractInvertBSplineTransform]] 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 artifacts.

'''Example'''
% gtractInvertBSplineTransform --inputReferenceVolume T1_ACPC.nhdr --inputTransform ACPC_bspline.xfm \
--outputTransform ACPC_Inverse_Bspline.xfm

===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]] - Resamples a mask or label - Image pixel type is signed short and neareast neigbor interpolation is used
* [[gtractResampleB0]] - Resamples the B0 image - Image pixel type is signed short and linear interpolation is used
* [[gtractResampleAnisotropy]] - 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:

# Free Tracking
# Streamlines Tracking
# Graph Search Tracking
# Guided 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 primary 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 anisotropy, 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 [[gtractFiberTracking]] 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 arguments for [[gtractFiberTracking]] 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-ambiguous regions and utilizes branching and a graph search algorithm in ambigous regions. Ambiguous 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 secondary 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 algorithm 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 arguments for [[gtractFiberTracking]] 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 [[gtractFiberTracking]] 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 [[gtractCreateGuideFiber]] implements this algorithm. The user must specify the guide fiber when running this program.

'''Example:'''
% gtractFiberTracking

===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]] 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]] 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-12-21T00:21:29Z

Matsuij: /* Invert B-Spline */

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

<pre>
DicomToNrrdConverter --inputDicomDirectory DICOM_directory_name --outputVolume NRRD_file_name.nrrd
</pre>

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 ==
The following are links to the full documentation of GTRACT's programs. The same documentation can be accessed on the command line using the following:

<pre>
${GTRACT_prog_name} --help
</pre>

* [[extractNrrdVectorIndex|extractNrrdVectorIndex Documentation]]
* [[gtractAnisotropyMap|gtractAnisotropyMap Documentation]]
* [[gtractAverageBvalues|gtractAverageBvalues Documentation]]
* [[gtractClipAnisotropy|gtractClipAnisotropy Documentation]]
* [[gtractCoRegAnatomy|gtractCoRegAnatomy Documentation]]
* [[gtractConcatDwi|gtractConcatDwi Documentation]]
* [[gtractCopyImageOrientation|gtractCopyImageOrientation Documentation]]
* [[gtractCoregBvalues|gtractCoregBvalues Documentation]]
* [[gtractCreateGuideFiber|gtractCreateGuideFiber Documentation]]
* [[gtractFiberTracking|gtractFiberTracking Documentation]]
* [[gtractResampleAnisotropy|gtractResampleAnisotropy Documentation]]
* [[gtractResampleB0|gtractResampleB0 Documentation]]
* [[gtractTensor|gtractTensor 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 \
--outputVolume outputImage.nhdr

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

'''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]] 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 [[gtractCoRegAnatomy]]

'''Example'''
% gtractCoRegAnatomy --inputVolume DWI_coreg.nhdr --transformType Rigid \
--vectorIndex 0 --inputAnatomicalVolume T1_ACPC_Axial.nhdr \
--outputTransformName ACPC_rigid.mat --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, [[gtractCoRegAnatomy]]

'''Example:'''

% gtractCoRegAnatomy --inputVolume DWI_coreg.nhdr --transformType Bspline \
--vectorIndex 0 --inputRigidTransform ACPC_rigid.mat --inputAnatomicalVolume T1_ACPC_Axial.nhdr \
--outputTransformName ACPC_bspline.mat --numberOfIterations 1000

{|
| 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]] 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 [[gtractInvertBSplineTransform]] 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 artifacts.

'''Example'''
% gtractInvertBSplineTransform --inputReferenceVolume T1_ACPC.nhdr --inputTransform ACPC_bspline.xfm \
--outputTransform ACPC_Inverse_Bspline.xfm

===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]] - Resamples a mask or label - Image pixel type is signed short and neareast neigbor interpolation is used
* [[gtractResampleB0]] - Resamples the B0 image - Image pixel type is signed short and linear interpolation is used
* [[gtractResampleAnisotropy]] - 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:

# Free Tracking
# Streamlines Tracking
# Graph Search Tracking
# Guided 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 primary 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 anisotropy, 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 [[gtractFiberTracking]] 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 arguments for [[gtractFiberTracking]] 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-ambiguous regions and utilizes branching and a graph search algorithm in ambigous regions. Ambiguous 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 secondary 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 algorithm 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 arguments for [[gtractFiberTracking]] 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 [[gtractFiberTracking]] 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 [[gtractCreateGuideFiber]] implements this algorithm. The user must specify the guide fiber when running this program.

'''Example:'''
% gtractFiberTracking

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

GtractInvertBSplineTransform

2010-12-21T00:02:35Z

Matsuij: Created page with '===Module Type & Category=== Type: CLI Category: Diffusion.GTRACT ===Authors, Collaborators & Contact=== Author: This tool was developed by Vincent Magnotta and Greg Harris…'

===Module Type & Category===

Type: CLI

Category: Diffusion.GTRACT

===Authors, Collaborators & Contact===

Author: This tool was developed by Vincent Magnotta and Greg Harris.

Contributors: Funding for this version of the GTRACT program was provided by NIH/NINDS R01NS050568-01A2S1

===Module Description===

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

|Program title || B-Spline Transform Inversion

|-
|Program version || 4.0.0

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

|-
|}

* '''''Input Image Files''''' Parameters for specifying the B-Spline transform and the space to invert it in.
** '''Input Reference Image Volume''' [--inputReferenceVolume] : Required: input image file name to exemplify the anatomical space to interpolate over.
** '''Input B-Spline Transform''' [--inputTransform] : Required: input B-Spline transform file name
* '''''Output Image Files''''' Output file from conversion from Dicom to Nrrd
** '''Output Transform''' [--outputTransform] : Required: output transform file name
* '''''Transform Conversion Parameters''''' Input parameters controlling the approximation of a B-Spline inverse by a thin-plate spline.
** '''Landmark Density''' [--landmarkDensity] : Number of landmark subdivisions in all 3 directions

GTRACT V4

2010-12-20T23:58:33Z

Matsuij: /* Invert B-Spline */

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

<pre>
DicomToNrrdConverter --inputDicomDirectory DICOM_directory_name --outputVolume NRRD_file_name.nrrd
</pre>

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 ==
The following are links to the full documentation of GTRACT's programs. The same documentation can be accessed on the command line using the following:

<pre>
${GTRACT_prog_name} --help
</pre>

* [[extractNrrdVectorIndex|extractNrrdVectorIndex Documentation]]
* [[gtractAnisotropyMap|gtractAnisotropyMap Documentation]]
* [[gtractAverageBvalues|gtractAverageBvalues Documentation]]
* [[gtractClipAnisotropy|gtractClipAnisotropy Documentation]]
* [[gtractCoRegAnatomy|gtractCoRegAnatomy Documentation]]
* [[gtractConcatDwi|gtractConcatDwi Documentation]]
* [[gtractCopyImageOrientation|gtractCopyImageOrientation Documentation]]
* [[gtractCoregBvalues|gtractCoregBvalues Documentation]]
* [[gtractCreateGuideFiber|gtractCreateGuideFiber Documentation]]
* [[gtractFiberTracking|gtractFiberTracking Documentation]]
* [[gtractResampleAnisotropy|gtractResampleAnisotropy Documentation]]
* [[gtractResampleB0|gtractResampleB0 Documentation]]
* [[gtractTensor|gtractTensor 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 \
--outputVolume outputImage.nhdr

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

'''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]] 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 [[gtractCoRegAnatomy]]

'''Example'''
% gtractCoRegAnatomy --inputVolume DWI_coreg.nhdr --transformType Rigid \
--vectorIndex 0 --inputAnatomicalVolume T1_ACPC_Axial.nhdr \
--outputTransformName ACPC_rigid.mat --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, [[gtractCoRegAnatomy]]

'''Example:'''

% gtractCoRegAnatomy --inputVolume DWI_coreg.nhdr --transformType Bspline \
--vectorIndex 0 --inputRigidTransform ACPC_rigid.mat --inputAnatomicalVolume T1_ACPC_Axial.nhdr \
--outputTransformName ACPC_bspline.mat --numberOfIterations 1000

{|
| 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]] 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 [[gtractInvertBSplineTransform]] 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 artifacts.

'''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]] - Resamples a mask or label - Image pixel type is signed short and neareast neigbor interpolation is used
* [[gtractResampleB0]] - Resamples the B0 image - Image pixel type is signed short and linear interpolation is used
* [[gtractResampleAnisotropy]] - 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:

# Free Tracking
# Streamlines Tracking
# Graph Search Tracking
# Guided 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 primary 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 anisotropy, 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 [[gtractFiberTracking]] 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 arguments for [[gtractFiberTracking]] 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-ambiguous regions and utilizes branching and a graph search algorithm in ambigous regions. Ambiguous 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 secondary 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 algorithm 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 arguments for [[gtractFiberTracking]] 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 [[gtractFiberTracking]] 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 [[gtractCreateGuideFiber]] implements this algorithm. The user must specify the guide fiber when running this program.

'''Example:'''
% gtractFiberTracking

===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]] 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]] 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-12-20T23:55:45Z

Matsuij: /* Anatomical Rigid */

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

<pre>
DicomToNrrdConverter --inputDicomDirectory DICOM_directory_name --outputVolume NRRD_file_name.nrrd
</pre>

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 ==
The following are links to the full documentation of GTRACT's programs. The same documentation can be accessed on the command line using the following:

<pre>
${GTRACT_prog_name} --help
</pre>

* [[extractNrrdVectorIndex|extractNrrdVectorIndex Documentation]]
* [[gtractAnisotropyMap|gtractAnisotropyMap Documentation]]
* [[gtractAverageBvalues|gtractAverageBvalues Documentation]]
* [[gtractClipAnisotropy|gtractClipAnisotropy Documentation]]
* [[gtractCoRegAnatomy|gtractCoRegAnatomy Documentation]]
* [[gtractConcatDwi|gtractConcatDwi Documentation]]
* [[gtractCopyImageOrientation|gtractCopyImageOrientation Documentation]]
* [[gtractCoregBvalues|gtractCoregBvalues Documentation]]
* [[gtractCreateGuideFiber|gtractCreateGuideFiber Documentation]]
* [[gtractFiberTracking|gtractFiberTracking Documentation]]
* [[gtractResampleAnisotropy|gtractResampleAnisotropy Documentation]]
* [[gtractResampleB0|gtractResampleB0 Documentation]]
* [[gtractTensor|gtractTensor 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 \
--outputVolume outputImage.nhdr

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

'''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]] 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 [[gtractCoRegAnatomy]]

'''Example'''
% gtractCoRegAnatomy --inputVolume DWI_coreg.nhdr --transformType Rigid \
--vectorIndex 0 --inputAnatomicalVolume T1_ACPC_Axial.nhdr \
--outputTransformName ACPC_rigid.mat --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, [[gtractCoRegAnatomy]]

'''Example:'''

% gtractCoRegAnatomy --inputVolume DWI_coreg.nhdr --transformType Bspline \
--vectorIndex 0 --inputRigidTransform ACPC_rigid.mat --inputAnatomicalVolume T1_ACPC_Axial.nhdr \
--outputTransformName ACPC_bspline.mat --numberOfIterations 1000

{|
| 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]] 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 [[gtractInvertBSplineTransform]] 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]] - Resamples a mask or label - Image pixel type is signed short and neareast neigbor interpolation is used
* [[gtractResampleB0]] - Resamples the B0 image - Image pixel type is signed short and linear interpolation is used
* [[gtractResampleAnisotropy]] - 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:

# Free Tracking
# Streamlines Tracking
# Graph Search Tracking
# Guided 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 primary 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 anisotropy, 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 [[gtractFiberTracking]] 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 arguments for [[gtractFiberTracking]] 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-ambiguous regions and utilizes branching and a graph search algorithm in ambigous regions. Ambiguous 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 secondary 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 algorithm 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 arguments for [[gtractFiberTracking]] 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 [[gtractFiberTracking]] 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 [[gtractCreateGuideFiber]] implements this algorithm. The user must specify the guide fiber when running this program.

'''Example:'''
% gtractFiberTracking

===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]] 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]] 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-12-20T23:55:14Z

Matsuij: /* Anatomical B-Spline */

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

<pre>
DicomToNrrdConverter --inputDicomDirectory DICOM_directory_name --outputVolume NRRD_file_name.nrrd
</pre>

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 ==
The following are links to the full documentation of GTRACT's programs. The same documentation can be accessed on the command line using the following:

<pre>
${GTRACT_prog_name} --help
</pre>

* [[extractNrrdVectorIndex|extractNrrdVectorIndex Documentation]]
* [[gtractAnisotropyMap|gtractAnisotropyMap Documentation]]
* [[gtractAverageBvalues|gtractAverageBvalues Documentation]]
* [[gtractClipAnisotropy|gtractClipAnisotropy Documentation]]
* [[gtractCoRegAnatomy|gtractCoRegAnatomy Documentation]]
* [[gtractConcatDwi|gtractConcatDwi Documentation]]
* [[gtractCopyImageOrientation|gtractCopyImageOrientation Documentation]]
* [[gtractCoregBvalues|gtractCoregBvalues Documentation]]
* [[gtractCreateGuideFiber|gtractCreateGuideFiber Documentation]]
* [[gtractFiberTracking|gtractFiberTracking Documentation]]
* [[gtractResampleAnisotropy|gtractResampleAnisotropy Documentation]]
* [[gtractResampleB0|gtractResampleB0 Documentation]]
* [[gtractTensor|gtractTensor 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 \
--outputVolume outputImage.nhdr

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

'''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]] 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 [[gtractCoRegAnatomy]]

'''Example'''
% gtractCoRegAnatomy --inputVolume 0226770_DWI_coreg.nhdr --transformType Rigid \
--vectorIndex 0 --inputAnatomicalVolume 30670508_T1_ACPC_Axial.nhdr \
--outputTransformName ACPC_rigid.mat --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, [[gtractCoRegAnatomy]]

'''Example:'''

% gtractCoRegAnatomy --inputVolume DWI_coreg.nhdr --transformType Bspline \
--vectorIndex 0 --inputRigidTransform ACPC_rigid.mat --inputAnatomicalVolume T1_ACPC_Axial.nhdr \
--outputTransformName ACPC_bspline.mat --numberOfIterations 1000

{|
| 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]] 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 [[gtractInvertBSplineTransform]] 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]] - Resamples a mask or label - Image pixel type is signed short and neareast neigbor interpolation is used
* [[gtractResampleB0]] - Resamples the B0 image - Image pixel type is signed short and linear interpolation is used
* [[gtractResampleAnisotropy]] - 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:

# Free Tracking
# Streamlines Tracking
# Graph Search Tracking
# Guided 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 primary 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 anisotropy, 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 [[gtractFiberTracking]] 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 arguments for [[gtractFiberTracking]] 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-ambiguous regions and utilizes branching and a graph search algorithm in ambigous regions. Ambiguous 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 secondary 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 algorithm 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 arguments for [[gtractFiberTracking]] 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 [[gtractFiberTracking]] 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 [[gtractCreateGuideFiber]] implements this algorithm. The user must specify the guide fiber when running this program.

'''Example:'''
% gtractFiberTracking

===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]] 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]] 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-12-20T23:50:10Z

Matsuij: /* Anatomical Rigid */

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

<pre>
DicomToNrrdConverter --inputDicomDirectory DICOM_directory_name --outputVolume NRRD_file_name.nrrd
</pre>

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 ==
The following are links to the full documentation of GTRACT's programs. The same documentation can be accessed on the command line using the following:

<pre>
${GTRACT_prog_name} --help
</pre>

* [[extractNrrdVectorIndex|extractNrrdVectorIndex Documentation]]
* [[gtractAnisotropyMap|gtractAnisotropyMap Documentation]]
* [[gtractAverageBvalues|gtractAverageBvalues Documentation]]
* [[gtractClipAnisotropy|gtractClipAnisotropy Documentation]]
* [[gtractCoRegAnatomy|gtractCoRegAnatomy Documentation]]
* [[gtractConcatDwi|gtractConcatDwi Documentation]]
* [[gtractCopyImageOrientation|gtractCopyImageOrientation Documentation]]
* [[gtractCoregBvalues|gtractCoregBvalues Documentation]]
* [[gtractCreateGuideFiber|gtractCreateGuideFiber Documentation]]
* [[gtractFiberTracking|gtractFiberTracking Documentation]]
* [[gtractResampleAnisotropy|gtractResampleAnisotropy Documentation]]
* [[gtractResampleB0|gtractResampleB0 Documentation]]
* [[gtractTensor|gtractTensor 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 \
--outputVolume outputImage.nhdr

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

'''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]] 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 [[gtractCoRegAnatomy]]

'''Example'''
% gtractCoRegAnatomy --inputVolume 0226770_DWI_coreg.nhdr --transformType Rigid \
--vectorIndex 0 --inputAnatomicalVolume 30670508_T1_ACPC_Axial.nhdr \
--outputTransformName ACPC_rigid.mat --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, [[gtractCoRegAnatomy]]

'''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]] 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 [[gtractInvertBSplineTransform]] 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]] - Resamples a mask or label - Image pixel type is signed short and neareast neigbor interpolation is used
* [[gtractResampleB0]] - Resamples the B0 image - Image pixel type is signed short and linear interpolation is used
* [[gtractResampleAnisotropy]] - 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:

# Free Tracking
# Streamlines Tracking
# Graph Search Tracking
# Guided 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 primary 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 anisotropy, 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 [[gtractFiberTracking]] 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 arguments for [[gtractFiberTracking]] 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-ambiguous regions and utilizes branching and a graph search algorithm in ambigous regions. Ambiguous 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 secondary 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 algorithm 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 arguments for [[gtractFiberTracking]] 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 [[gtractFiberTracking]] 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 [[gtractCreateGuideFiber]] implements this algorithm. The user must specify the guide fiber when running this program.

'''Example:'''
% gtractFiberTracking

===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]] 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]] 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-12-20T23:30:44Z

Matsuij: /* Anatomical Rigid */

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

<pre>
DicomToNrrdConverter --inputDicomDirectory DICOM_directory_name --outputVolume NRRD_file_name.nrrd
</pre>

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 ==
The following are links to the full documentation of GTRACT's programs. The same documentation can be accessed on the command line using the following:

<pre>
${GTRACT_prog_name} --help
</pre>

* [[extractNrrdVectorIndex|extractNrrdVectorIndex Documentation]]
* [[gtractAnisotropyMap|gtractAnisotropyMap Documentation]]
* [[gtractAverageBvalues|gtractAverageBvalues Documentation]]
* [[gtractClipAnisotropy|gtractClipAnisotropy Documentation]]
* [[gtractCoRegAnatomy|gtractCoRegAnatomy Documentation]]
* [[gtractConcatDwi|gtractConcatDwi Documentation]]
* [[gtractCopyImageOrientation|gtractCopyImageOrientation Documentation]]
* [[gtractCoregBvalues|gtractCoregBvalues Documentation]]
* [[gtractCreateGuideFiber|gtractCreateGuideFiber Documentation]]
* [[gtractFiberTracking|gtractFiberTracking Documentation]]
* [[gtractResampleAnisotropy|gtractResampleAnisotropy Documentation]]
* [[gtractResampleB0|gtractResampleB0 Documentation]]
* [[gtractTensor|gtractTensor 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 \
--outputVolume outputImage.nhdr

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

'''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]] 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 [[gtractCoRegAnatomy]]

'''Example'''
% gtractCoRegAnatomy --inputVolume 0226770_DWI_coreg.nhdr --transformType Rigid \
--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, [[gtractCoRegAnatomy]]

'''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]] 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 [[gtractInvertBSplineTransform]] 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]] - Resamples a mask or label - Image pixel type is signed short and neareast neigbor interpolation is used
* [[gtractResampleB0]] - Resamples the B0 image - Image pixel type is signed short and linear interpolation is used
* [[gtractResampleAnisotropy]] - 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:

# Free Tracking
# Streamlines Tracking
# Graph Search Tracking
# Guided 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 primary 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 anisotropy, 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 [[gtractFiberTracking]] 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 arguments for [[gtractFiberTracking]] 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-ambiguous regions and utilizes branching and a graph search algorithm in ambigous regions. Ambiguous 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 secondary 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 algorithm 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 arguments for [[gtractFiberTracking]] 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 [[gtractFiberTracking]] 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 [[gtractCreateGuideFiber]] implements this algorithm. The user must specify the guide fiber when running this program.

'''Example:'''
% gtractFiberTracking

===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]] 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]] 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-12-20T22:48:07Z

Matsuij: /* DTI Image Co-Registration */

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

<pre>
DicomToNrrdConverter --inputDicomDirectory DICOM_directory_name --outputVolume NRRD_file_name.nrrd
</pre>

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 ==
The following are links to the full documentation of GTRACT's programs. The same documentation can be accessed on the command line using the following:

<pre>
${GTRACT_prog_name} --help
</pre>

* [[extractNrrdVectorIndex|extractNrrdVectorIndex Documentation]]
* [[gtractAnisotropyMap|gtractAnisotropyMap Documentation]]
* [[gtractAverageBvalues|gtractAverageBvalues Documentation]]
* [[gtractClipAnisotropy|gtractClipAnisotropy Documentation]]
* [[gtractCoRegAnatomy|gtractCoRegAnatomy Documentation]]
* [[gtractConcatDwi|gtractConcatDwi Documentation]]
* [[gtractCopyImageOrientation|gtractCopyImageOrientation Documentation]]
* [[gtractCoregBvalues|gtractCoregBvalues Documentation]]
* [[gtractCreateGuideFiber|gtractCreateGuideFiber Documentation]]
* [[gtractFiberTracking|gtractFiberTracking Documentation]]
* [[gtractResampleAnisotropy|gtractResampleAnisotropy Documentation]]
* [[gtractResampleB0|gtractResampleB0 Documentation]]
* [[gtractTensor|gtractTensor 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 \
--outputVolume outputImage.nhdr

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

'''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]] 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 [[gtractCoRegAnatomy]]

'''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, [[gtractCoRegAnatomy]]

'''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]] 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 [[gtractInvertBSplineTransform]] 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]] - Resamples a mask or label - Image pixel type is signed short and neareast neigbor interpolation is used
* [[gtractResampleB0]] - Resamples the B0 image - Image pixel type is signed short and linear interpolation is used
* [[gtractResampleAnisotropy]] - 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:

# Free Tracking
# Streamlines Tracking
# Graph Search Tracking
# Guided 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 primary 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 anisotropy, 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 [[gtractFiberTracking]] 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 arguments for [[gtractFiberTracking]] 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-ambiguous regions and utilizes branching and a graph search algorithm in ambigous regions. Ambiguous 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 secondary 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 algorithm 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 arguments for [[gtractFiberTracking]] 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 [[gtractFiberTracking]] 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 [[gtractCreateGuideFiber]] implements this algorithm. The user must specify the guide fiber when running this program.

'''Example:'''
% gtractFiberTracking

===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]] 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]] 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-12-20T22:47:14Z

Matsuij: /* DTI Image Co-Registration */

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

<pre>
DicomToNrrdConverter --inputDicomDirectory DICOM_directory_name --outputVolume NRRD_file_name.nrrd
</pre>

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 ==
The following are links to the full documentation of GTRACT's programs. The same documentation can be accessed on the command line using the following:

<pre>
${GTRACT_prog_name} --help
</pre>

* [[extractNrrdVectorIndex|extractNrrdVectorIndex Documentation]]
* [[gtractAnisotropyMap|gtractAnisotropyMap Documentation]]
* [[gtractAverageBvalues|gtractAverageBvalues Documentation]]
* [[gtractClipAnisotropy|gtractClipAnisotropy Documentation]]
* [[gtractCoRegAnatomy|gtractCoRegAnatomy Documentation]]
* [[gtractConcatDwi|gtractConcatDwi Documentation]]
* [[gtractCopyImageOrientation|gtractCopyImageOrientation Documentation]]
* [[gtractCoregBvalues|gtractCoregBvalues Documentation]]
* [[gtractCreateGuideFiber|gtractCreateGuideFiber Documentation]]
* [[gtractFiberTracking|gtractFiberTracking Documentation]]
* [[gtractResampleAnisotropy|gtractResampleAnisotropy Documentation]]
* [[gtractResampleB0|gtractResampleB0 Documentation]]
* [[gtractTensor|gtractTensor 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 \
% --outputVolume outputImage.nhdr

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

'''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]] 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 [[gtractCoRegAnatomy]]

'''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, [[gtractCoRegAnatomy]]

'''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]] 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 [[gtractInvertBSplineTransform]] 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]] - Resamples a mask or label - Image pixel type is signed short and neareast neigbor interpolation is used
* [[gtractResampleB0]] - Resamples the B0 image - Image pixel type is signed short and linear interpolation is used
* [[gtractResampleAnisotropy]] - 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:

# Free Tracking
# Streamlines Tracking
# Graph Search Tracking
# Guided 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 primary 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 anisotropy, 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 [[gtractFiberTracking]] 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 arguments for [[gtractFiberTracking]] 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-ambiguous regions and utilizes branching and a graph search algorithm in ambigous regions. Ambiguous 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 secondary 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 algorithm 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 arguments for [[gtractFiberTracking]] 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 [[gtractFiberTracking]] 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 [[gtractCreateGuideFiber]] implements this algorithm. The user must specify the guide fiber when running this program.

'''Example:'''
% gtractFiberTracking

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

GtractFastMarchingTracking

2010-12-20T22:35:21Z

===Module Type & Category===

Type: CLI

Category: Diffusion.GTRACT

===Authors, Collaborators & Contact===

Author: This tool was developed by Vincent Magnotta and Greg Harris. The original code here was developed by Daisy Espino.

Contributors: Funding for this version of the GTRACT program was provided by NIH/NINDS R01NS050568-01A2S1

===Module Description===

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

|Program title || Fast Marching Tracking

|-
|Program version || 4.0.0

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

|-
|}

* '''''Input Image Files''''' Parameters for specifying the diffusion tensor image set
** '''Input Tensor Image Volume''' [--inputTensorVolume] : Required: input tensor image file name
** '''Input Anisotropy Image Volume''' [--inputAnisotropyVolume] : Required: input anisotropy image file name
** '''Input Cost Image Volume''' [--inputCostVolume] : Required: input vcl_cost image file name
** '''Input Starting Seeds LabelMap Volume''' [--inputStartingSeedsLabelMapVolume] : Required: input starting seeds LabelMap image file name
** '''Starting Seeds Label''' [--startingSeedsLabel] : Label value for Starting Seeds
* '''''Output Files''''' Output file in which to store tract lines
** '''Output Tract Filename''' [--outputTract] : Required: name of output vtkPolydata file containing tract lines and the point data collected along them.
** '''Write fiber tracts in XML format''' [--writeXMLPolyDataFile] : Flag to make use of the XML format for vtkPolyData fiber tracts.
* '''''Fast Marching Tracking Parameters''''' Input parameters controlling the Fast Marching Cost Function
** '''Number of Iterations''' [--numberOfIterations] : Number of iterations used for the optimization
** '''Seed Threshold''' [--seedThreshold] : Anisotropy threshold used for seed selection
** '''Tracking Threshold''' [--trackingThreshold] : Anisotropy threshold used for fiber tracking
** '''Cost Step Size''' [--costStepSize] : Cost image sub-voxel sampling
** '''Maximum Step Size''' [--maximumStepSize] : Maximum step size to move when tracking
** '''Minimum Step Size''' [--minimumStepSize] : Minimum step size to move when tracking

GTRACT V4

2010-12-20T22:34:47Z

Matsuij: /* Fast Marching Tracking */

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

<pre>
DicomToNrrdConverter --inputDicomDirectory DICOM_directory_name --outputVolume NRRD_file_name.nrrd
</pre>

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 ==
The following are links to the full documentation of GTRACT's programs. The same documentation can be accessed on the command line using the following:

<pre>
${GTRACT_prog_name} --help
</pre>

* [[extractNrrdVectorIndex|extractNrrdVectorIndex Documentation]]
* [[gtractAnisotropyMap|gtractAnisotropyMap Documentation]]
* [[gtractAverageBvalues|gtractAverageBvalues Documentation]]
* [[gtractClipAnisotropy|gtractClipAnisotropy Documentation]]
* [[gtractCoRegAnatomy|gtractCoRegAnatomy Documentation]]
* [[gtractConcatDwi|gtractConcatDwi Documentation]]
* [[gtractCopyImageOrientation|gtractCopyImageOrientation Documentation]]
* [[gtractCoregBvalues|gtractCoregBvalues Documentation]]
* [[gtractCreateGuideFiber|gtractCreateGuideFiber Documentation]]
* [[gtractFiberTracking|gtractFiberTracking Documentation]]
* [[gtractResampleAnisotropy|gtractResampleAnisotropy Documentation]]
* [[gtractResampleB0|gtractResampleB0 Documentation]]
* [[gtractTensor|gtractTensor 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]].

'''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]] 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 [[gtractCoRegAnatomy]]

'''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, [[gtractCoRegAnatomy]]

'''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]] 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 [[gtractInvertBSplineTransform]] 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]] - Resamples a mask or label - Image pixel type is signed short and neareast neigbor interpolation is used
* [[gtractResampleB0]] - Resamples the B0 image - Image pixel type is signed short and linear interpolation is used
* [[gtractResampleAnisotropy]] - 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:

# Free Tracking
# Streamlines Tracking
# Graph Search Tracking
# Guided 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 primary 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 anisotropy, 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 [[gtractFiberTracking]] 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 arguments for [[gtractFiberTracking]] 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-ambiguous regions and utilizes branching and a graph search algorithm in ambigous regions. Ambiguous 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 secondary 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 algorithm 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 arguments for [[gtractFiberTracking]] 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 [[gtractFiberTracking]] 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 [[gtractCreateGuideFiber]] implements this algorithm. The user must specify the guide fiber when running this program.

'''Example:'''
% gtractFiberTracking

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