'''WARNING!!!''': When converting to/from another DTI program, one additional step to check is the physical unit of diffusivity.  Please refer to the page dedicated to this topic.  Be aware that these programs may change their formats unannounced.  To be confident in the correctness of the conversion, it is highly advisable to visually inspect one subject in your dataset using the tensor glyph tool (for more information visit [[http://dti-tk.sourceforge.net/pmwiki/pmwiki.php?n=Documentation.VisualizationTool?action=edit| the visualization section]].
 

DTI-TK is an official [http://fsl.fmrib.ox.ac.uk/fsl/fslwiki/Plugins |FSL plugin].  It implements a two-way interoperability support that enables the existing FSL users to continue to enjoy the powerful tract-based spatial statistic (TBSS) framework while taking advantage of the state-of-the-art tensor-based DTI registration provided by DTI-TK.
 

'''Warning''': When converting to/from another DTI program, one additional step to check is the physical unit of diffusivity.  Please refer to the page dedicated to this topic.  Be aware that these programs may change their formats unannounced.  To be confident in the correctness of the conversion, it is highly advisable to visually inspect one subject in your dataset using the tensor glyph tool (for more information visit [[http://dti-tk.sourceforge.net/pmwiki/pmwiki.php?n=Documentation.VisualizationTool?action=edit| the visualization section]]. 
 
 
!! Interoperability with [[http://afni.nimh.nih.gov/afni | AFNI]]
In [[http://afni.nimh.nih.gov/afni | AFNI]], the program for creating DTI volumes from Diffusion-Weighted MR images, 3dDWItoDT, can output the DTI volume both in the NIfTI and multivolume Analyze format.  The outputs in both cases are fully compatible with DTI-TK.
 
'''NEXT''': Check the [[Documentation.Diffusivity|diffusivity units]] and [[Documentation.VisualizationTool|visualize your DTs]].
 
 

 
!! Interoperability with [[https://www.mristudio.org/ | DTI Studio]]
This popular DTI tool pioneered the fiber tractography known as FACT.  For tractography, [[https://www.mristudio.org/ | DTI Studio]] takes two inputs: a FA image in the ani format and the corresponding principal diffusion direction image in the vec format.  Here we describe the program in DTI-TK, TVToDTIStudio, that supports the conversion of the NIfTI tensor format to the inputs required for tractography in [[https://www.mristudio.org/ | DTI Studio]].  It takes a NIfTI tensor image as input and output the corresponding ani and vec files.
 

TVToDTIStudio -in tensor.nii.gz 

The outputs are simply tensor.ani, the FA map, and tensor.vec, the principal diffusion direction map.  The volume information, including dimension and FOV, can be determined by the command VolumeInfo.
 

VolumeInfo tensor.nii.gz 

Volume Info of tensor.nii.gz
size: 112x112x60, voxel size: 2x2x2, origin: [0, 0, 0]

In this case, the image width is the x dimension, 112, the image height is the y dimension, 112, and the number of slices is 60.  The Field-of-View is then 224x224 (x dimension multiplies x voxel size and y dimension multiplies y voxel size), and the thickness is 2, the z voxel size.
 
'''NEXT''': Check the [[Documentation.Diffusivity|diffusivity units]] and [[Documentation.VisualizationTool|visualize your DTs]].
 
!! Interoperability with [[http://graphics.stanford.edu/projects/dti/software/|DTI-Query/CINCH]]
This excellent tractography visualization and selection/segmentation tools supports the two formats used in DTI-TK.
 
!! Interoperability with [[http://www.fmrib.ox.ac.uk/fsl/fdt/fdt_dtifit.html | FSL]]
Some programs output the eigensystem, i.e., the eigenvalues and the eigenvectors, and [[http://www.fmrib.ox.ac.uk/fsl/fdt/fdt_dtifit.html | FSL]] is one of them.  In this case, we've developed tools to convert from and to such format.  However, be aware that storing tensors in terms of their eigensystem doubles the storage footprint when compared to the format used in DTI-TK.
 
To convert to the FSL format, use ''TVEigenSystem'', e.g.
 

Alternatively, to convert the FSL format to the DTI-TK format, use TVFromEigenSystem, e.g.
 

TVFromEigenSystem -basename tensor -type FSL 

The input eigenvalue and eigenvector volumes are expected to use the FSL naming convention. The example above works for the files named as tensor_L{1,2,3}.nii.gz and tensor_V{1,2,3}.nii.gz.  If your files are xyz_L{1,2,3}.nii.gz and xyz_V{1,2,3}.nii.gz, the basename will be xyz instead.
 
By default, you do not need to provide an output file name.  The program will create the appropriate file name from the basename.  In our example, the output will be tensor.nii.gz.  However, if you prefer to provide your own output file name, you can choose to do so.  In this case, the command should read
 

TVFromEigenSystem -basename tensor -type FSL -out preferredfilename.nii.gz 

fsl_to_dtitk tensor

'''Warning''': FSL also has an option that allows for a DTI volume to be saved on disk in matrix form similar to but NOT the same as the NIfTI tensor format.  It stores the six independent matrix components using the "upper triangular" order rather than the "lower triangular" order specified in NIfTI standard! (See Section about CAMINO above for definition of upper and lower triangular)  So DO NOT use this option if you want to use its output with DTI-TK!

'''NEXT''': Check the diffusivity units and visualize your DTs
 
 

'''NEXT''':  Check the diffusivity units and visualize your DTs
 
 

'''NEXT''':  Check the diffusivity units and visualize your DTs
 

'''NEXT''': Check the [[Documentation.Diffusivity|diffusivity units]] and [[Documentation.VisualizationTool|visualize your DTs].
 
'''fsl_to_dtitk''': This is a convenient script that takes a FSL-generated DTI eigensystem volumes (''non-brain tissue already removed'') and converts them into fully DTI-TK compatible DTI volumes, i.e., in the correct format and [[Documentation.BeforeReg|correctly preprocessed]. 
 

'''NEXT''': Check the diffusivity units and visualize your DTs.
 
'''fsl_to_dtitk''': This is a convenient script that takes a FSL-generated DTI eigensystem volumes (non-brain tissue already removed) and converts them into fully DTI-TK compatible DTI volumes, i.e., in the correct format and correctly preprocessed. 
 

The output from this program will be tensor'_L{1,2,3}_'.nii.gz, the eigenvalues, and tensor'_V{1,2,3}_'.nii.gz, the eigenvectors, following precisely the FSL naming convention.
 

TVFromEigenSystem -basename tensor -type FSL -out something.nii.gz 

'''NEXT''': Check the diffusivity units and visualize your DTs
 
'''Warning''': FSL also has an option that allows for a DTI volume to be saved on disk in matrix form similar to but NOT the same as the NIfTI tensor format.  It stores the six independent matrix components using the "upper triangular" order rather than the "lower triangular" order specified in NIfTI standard! (See Section about CAMINO above for definition of upper and lower triangular)  So DO NOT use this option if you want to use its output with DTI-TK!

Some programs output the egensystem, i.e., the eigenvalues and the egenvectors, and [[http://www.fmrib.ox.ac.uk/fsl/fdt/fdt_dtifit.html | FSL]] is one of them.  In this case, we've developed tools to convert from and to such format.  However, be aware that storing tensors in terms of their eigensystem doubles the storage footprint when compared to the format used in DTI-TK.
 

The input eigenvalue and egenvector volumes are expected to use the FSL naming convention.  In the example above, these files should be named as tensor_L{1,2,3}.nii.gz and tensor_V{1,2,3}.nii.gz.  By default, you do not need to provide a output file name.  The program will create the appropriate file name from the basename.  In our example, the output will be tensor.nii.gz.  However, if you prefer to provide your own output file name, you can choose to do so.  In this case, the command should read
 

->[@ ImageToTensorVolume ${prefix} hdr tensor.nii.gz

->[@ ImageToTensorVolume ${prefix} hdr tensor.nii.gz 1 

->[@ ImageToTensorVolume D hdr tensor.nii.gz

->[@ TVToDTIStudio -in tensor.nii.gz 

->[@ VolumeInfo tensor.nii.gz 

->[@  Volume Info of tensor.nii.gz
  size: 112x112x60, voxel size: 2x2x2, origin: [0, 0, 0] @]
 

->[@ TVEigenSystem -in tensor.nii.gz -type FSL 

->[@ TVFromEigenSystem -basename tensor -type FSL 

->[@ TVFromEigenSystem -basename tensor -type FSL -out something.nii.gz 

When converting to/from another DTI program, one additional step to check is the physical unit of diffusivity.  Please refer to the page dedicated to this topic.  Be aware that these programs may change their formats unannounced.  To be confident in the correctness of the conversion, it is highly advisable to visually inspect one subject in your dataset using the tensor glyph tool (for more information visit [[http://dti-tk.sourceforge.net/pmwiki/pmwiki.php?n=Documentation.VisualizationTool?action=edit| the visualization section]].
 
 

When converting to/from another DTI program, one additional step to check is the physical unit of diffusivity.  Please refer to the page dedicated to this topic.  Be aware that these programs may change their formats unannounced.  To be confident in the correctness of the conversion, it is highly advisable to visually inspect one subject in your dataset using the tensor glyph tool described in the Section 5 of the Visualization page.
 
 

[@  Volume Info of tensor.nii.gz

[@ TVEigenSystem -in tensor.nii.gz -type FSL 

[@ ImageToTensorVolume ${prefix} hdr tensor.nii.gz

[@ ImageToTensorVolume ${prefix} hdr tensor.nii.gz 1 

[@ ImageToTensorVolume D hdr tensor.nii.gz

[@ TVToDTIStudio -in tensor.nii.gz 

[@ VolumeInfo tensor.nii.gz 

[@ TVFromEigenSystem -basename tensor -type FSL 

[@ TVFromEigenSystem -basename tensor -type FSL -out something.nii.gz 

->In [[http://afni.nimh.nih.gov/afni | AFNI]], the program for creating DTI volumes from Diffusion-Weighted MR images, 3dDWItoDT, can output the DTI volume both in the NIfTI and multivolume Analyze format.  The outputs in both cases are fully compatible with DTI-TK.
 

'''Warning''': FSL also has an option that allows for a DTI volume to be saved on disk in matrix form similar to but NOT the same as the NIfTI tensor format.  It stores the six independent matrix components using the "upper triangular" order rather than the "lower triangular" order specified in NIfTI standard! (See Section about CAMINO above for definition of upper and lower triangular)  So DO NOT use this option if you want to use its output with DTI-TK! 
 
Acknowledgement: I'd like thank Dr Phil Cook at University of Pennsylvania for alerting me to the existence of the alternative matrix form DTI volume in FSL.

->When converting to/from another DTI program, one additional step to check is the physical unit of diffusivity.  Please refer to the page dedicated to this topic.  Be aware that these programs may change their formats unannounced.  To be confident in the correctness of the conversion, it is highly advisable to visually inspect one subject in your dataset using the tensor glyph tool described in the Section 5 of the Visualization page.
 
 

->Some programs can output individual tensor component images, and [[http://web4.cs.ucl.ac.uk/research/medic/camino/pmwiki/pmwiki.php?n=Main.Guide | CAMINO]] offers this option.  In this case, these component images, if stored in analyze or NIfTI format and appropriately named, can be converted to NifTI tensor format.  The component images should be named as ${prefix}{xx, yx, yy, zx, zy, zz}.hdr (lower triangular) or ${prefix}{xx, xy, xz, yy, yz, zz}.hdr (upper triangular).  The following command will combine these images into a single NIfTI tensor image, for lower triangular named files:
 
[@ ImageToTensorVolume ${prefix} hdr tensor.nii.gz @]
 

[@ ImageToTensorVolume ${prefix} hdr tensor.nii.gz 1 @]
 

[@ ImageToTensorVolume D hdr tensor.nii.gz @]
 

->This popular DTI tool pioneered the fiber tractography known as FACT.  For tractography, [[https://www.mristudio.org/ | DTI Studio]] takes two inputs: a FA image in the ani format and the corresponding principal diffusion direction image in the vec format.  Here we describe the program in DTI-TK, TVToDTIStudio, that supports the conversion of the NIfTI tensor format to the inputs required for tractography in [[https://www.mristudio.org/ | DTI Studio]].  It takes a NIfTI tensor image as input and output the corresponding ani and vec files.
 
[@ TVToDTIStudio -in tensor.nii.gz @]
 

->Some programs output the egensystem, i.e., the eigenvalues and the egenvectors, and [[http://www.fmrib.ox.ac.uk/fsl/fdt/fdt_dtifit.html | FSL]] is one of them.  In this case, we've developed tools to convert from and to such format.  However, be aware that storing tensors in terms of their eigensystem doubles the storage footprint when compared to the format used in DTI-TK.
 

[@ TVEigenSystem -in tensor.nii.gz -type FSL @]
 

[@ TVFromEigenSystem -basename tensor -type FSL @]
 

[@ TVFromEigenSystem -basename tensor -type FSL -out something.nii.gz @]
 

[@ VolumeInfo tensor.nii.gz @]
 

The output from this program will be tensor_L{1,2,3}.nii.gz, the eigenvalues, and tensor_V{1,2,3}.nii.gz, the eigenvectors, following precisely the FSL naming convention.
 

!! Interoperability with AFNI
 
In AFNI, the program for creating DTI volumes from Diffusion-Weighted MR images, 3dDWItoDT, can output the DTI volume both in the NIfTI and multivolume Analyze format.  The outputs in both cases are fully compatible with DTI-TK.
 
NEXT: Follow instructions described in section 1.1
 
 
!! Interoperability with Camino

Some programs can output individual tensor component images, and Camino offers this option.  In this case, these component images, if stored in analyze or NIfTI format and appropriately named, can be converted to NifTI tensor format.  The component images should be named as ${prefix}{xx, yx, yy, zx, zy, zz}.hdr (lower triangular) or ${prefix}{xx, xy, xz, yy, yz, zz}.hdr (upper triangular).  The following command will combine these images into a single NIfTI tensor image, for lower triangular named files:
 
    $ ImageToTensorVolume ${prefix} hdr tensor.nii.gz
 

    $ ImageToTensorVolume ${prefix} hdr tensor.nii.gz 1
 

    $ ImageToTensorVolume D hdr tensor.nii.gz
 
NEXT: Follow instructions described in section 1.1
 
 
!! Interoperability with DTIStudio
 
This popular DTI tool pioneered the fiber tractography known as FACT.  For tractography, DTIStudio takes two inputs: a FA image in the ani format and the corresponding principal diffusion direction image in the vec format.  Here we describe the program in DTI-TK, TVToDTIStudio, that supports the conversion of the NIfTI tensor format to the inputs required for tractography in DTIStudio.  It takes a NIfTI tensor image as input and output the corresponding ani and vec files.
 
  $ TVToDTIStudio -in tensor.nii.gz
 

  $ VolumeInfo tensor.nii.gz

  Volume Info of tensor.nii.gz
  size: 112x112x60, voxel size: 2x2x2, origin: [0, 0, 0]
 

NEXT: Follow instructions described in section 1.1
 
Acknowledgement: I'd like to thank Dr John Woo at University of Pennsylvania for contributing the key information that makes the DTIStudio support possible.)
 
!! Interoperability with DTI-Query/CINCH 
 

!! Interoperability with FSL
 
Some programs output the egensystem, i.e., the eigenvalues and the egenvectors, and FSL is one of them.  In this case, we've developed tools to convert from and to such format.  However, be AWARE that storing tensors in terms of their eigensystem doubles the storage footprint when compared to the format used in DTI-TK.
 
To convert to the FSL format, use TVEigenSystem, e.g.
 
    $ TVEigenSystem -in tensor.nii.gz -type FSL
 

    $ TVFromEigenSystem -basename tensor -type FSL
 

    $ TVFromEigenSystem -basename tensor -type FSL -out something.nii.gz
 
NEXT: Follow instructions described in section 1.1
 
WARNING!!!: FSL also has an option that allows for a DTI volume to be saved on disk in matrix form similar to but NOT the same as the NIfTI tensor format.  It stores the six independent matrix components using the "upper triangular" order rather than the "lower triangular" order specified in NIfTI standard! (See Section 2.2 above for definition of upper and lower triangular)  So DO NOT use this option if you want to use its output with DTI-TK!