|
|
Command-line Tools
This part is for advanced users only.
The backend of Diffusion Toolkit consists of a set of command-line programs. Thus,
it allows users to write their own script to process multiple datasets automatically.
To learn how each command-line program work, you may run each program with '--help' option.
Another good reference is look into the script that was automatically
generated by the GUI frontend (displayed in the output window).
An important note for Mac OS X and Linux users: to use odf_recon and odf_tracker, you must
set an environment variable called "DSI_PATH" and point it to the "matrices" directory in your installation location. On Macintosh that directory is
usually located at "/Applications/Diffusion\ Toolkit.app/Contents/MacOS/matrices/".
Following command-tools are included in Diffusion Toolkit release:
-
diff_unpack convert dicom images to analyze images.
Usage: diff_unpack INPUT_DICOM OUTPUT_DIR_&_PREFIX [OPTION]...
-ot, --output_type
output file type. accepted values are:
analyze -> analyze format 7.5
ni1 -> nifti format saved in seperate .hdr and .img file
nii -> nifti format with one .nii file
nii.gz -> nifti format with compression
default type is 'nii'
-split, --split
instead of saving everything in one big multi-timepoint 4D image,
split it into seperate files, one timepoint per file
-p, --paddings
number of 0 paddings for output filename prefix when '-split' enabled.
default is 3
-sn, --start_number
start number of the output filename numbering. default is 1, meaning
the first filename in the series is prefix001.suffix
NOTE: '-p' and '-sn' options are only effective when '-split' is
on, meaning output as a series of 3D image files instead of one 4D
file
-h, --help
display this help
Example:
diff_unpack dtiraw/xxxxx.dcm foo/dti
-
dti_recon reconstruct raw analyze images to tensors and a few other maps.
Usage: dti_recon RAW_DATA_FILE_NAME OUTPUT_FILE_PREFIX [OPTION]...
-ot, --output_type
output file type. accepted values are:
analyze -> analyze format 7.5 (NOT recommended)
ni1 -> nifti format saved in seperate .hdr and .img file
nii -> nifti format with one .nii file (default)
nii.gz -> nifti format with compression
default type is 'nii'
-gm, --gradient_matrix
specify gradient matrix to use. required. if 'MultiBvalue' is 'true'
or 1, it will either use the bvalues specified as the 4th component
of each gradient vector, or use max b value scaled by the magnitude
of the vector
-b, --b_value
set b value or maximum b value for multi-bvalue data. default is 1000
-b0, --number_of_b0
number of repeated b0 images on top. default is 1. the program
assumes b0 images are on top
-nex, --nex
number of averages. default is auto, meaning it will automatically
figure out how many averages based on the gradient table and number
of volumes in the 4D nifti file. auto only works on 4D input data
following 5 options are to provide image orientation information. if the
input image(s) are genuine nifti format, these flags are NOT needed because
nifti header contains all the needed information. if the program can not
find those information for image header, it will look for -info flag,
if not then -iop, then -sag/cor/axial
-info, --image_info
specify image information file. the image info file is generated
from original dicom image by diff_unpack program and contains image
orientation and other information needed for reconstruction and
tracking. by default will look into the image folder for .info file
NOTE: if info file was not found or given, the following '-iop',
'-sag', '-cor', '-axial' will be used
-iop, --image_orientation_patient
specify image orientation vectors. if just one argument given,
will treat it as filename and read the orientation vectors from
the file. if 6 arguments are given, will treat them as 6 float
numbers and construct the 1st and 2nd vector and calculate the 3rd
one automatically.
this information will be used to determine image orientation,
as well as to adjust gradient vectors with oblique angle when
'-oc' flag is on
default use the identity matrix vectors
-sag, --sagittal
this flag is equal to '-iop 0 1 0 0 0 -1'
-cor, --coronal
this flag is equal to '-iop 1 0 0 0 0 -1'
-axial, --axial
this flag is equal to '-iop 1 0 0 0 1 0'
the above flags indicate image orientation. default is axial.
NOTE: '-iop', '-sag', '-cor' and '-axial' options will overwrite
what '-info' has given. usually if an .info file exists, it should
be used instead of providing '-iop', etc., options manually
end of image orientation options
-oc, --oblique_correction
when oblique angle(s) applied, some SIEMENS dti protocols do not
adjust gradient accordingly, thus it requires adjustment for correct
diffusion tensor calculation
-b0_th, --b0_threshold
program will use b0 image with the given threshold to mask out high
background of fa/adc maps. by default it will calculate threshold
automatically. but if it failed, you need to set it manually.
-no_eigen, --no_eigen_output
do not write eigen-value and eigen-vector output
-no_tensor, --no_tensor_output
do not write tensor output
-no_exp, --no_exp_output
do not write exp output
-p, --paddings
number of 0 paddings for input raw data file prefix. default
value is 3
-sn, --start_number
start number of the input filename numbering. default is 1, meaning
the first filename in the series is prefix001.img
NOTE: '-p' and '-sn' options are only effective when a series of
single timepoint image files are given. when input is a 4D time
series file, those options are ignored
-output_5d, --output_5d
output vector and tensor files as standard nifti vector/tensor
format which is defined as 5d volume (4th dimension size as 1).
by default output is multi-frame (4D) nifti file for easy data
exchange with other software package
-h, --help
display this help
Example:
dti_recon dtiraw.nii dti -gm dti_mgh_dti60.txt
-
hardi_mat calculate the reconstruction matrix from a given gradient table.
The matrix will be
used by odf_recon.
Usage: hardi_mat INPUT_GRADIENT_TABLE OUTPUT_MATRIX_FILE [OPTION]...
-order, --order
maximum order of spherical harmonics. must be even number. default
is 4
-odf, --odf_file
filename that contains the reconstruction points on a HEMI-sphere.
use the pre-set 181 points by default
-info, --image_info
specify image information file. the image info file is generated
from original dicom image by diff_unpack program and contains image
orientation and other information needed for reconstruction and
tracking. by default will look into the image folder for .info file
NOTE: if info file was not found or given, the following '-iop',
'-sag', '-cor', '-axial' will be used
-iop, --image_orientation_patient
specify image orientation vectors. if just one argument given,
will treat it as filename and read the orientation vectors from
the file. if 6 arguments are given, will treat them as 6 float
numbers and construct the 1st and 2nd vector and calculate the 3rd
one automatically.
this information will be used to determine image orientation,
as well as to adjust gradient vectors with oblique angle when
'-oc' flag is on
default use the identity matrix vectors
-sag, --sagittal
this flag is equal to '-iop 0 1 0 0 0 -1'
-cor, --coronal
this flag is equal to '-iop 1 0 0 0 0 -1'
-axial, --axial
this flag is equal to '-iop 1 0 0 0 1 0'
the above flags indicate image orientation. default is axial.
NOTE: '-iop', '-sag', '-cor' and '-axial' options will overwrite
what '-info' has given. usually if an .info file exists, it should
be used instead of providing '-iop', etc., options manually
-oc, --oblique_correction
when oblique angle(s) applied, some SIEMENS dti protocols do not
adjust gradient accordingly, thus it requires adjustment for correct
diffusion tensor calculation. when this flag in on, '-iop' information
must also be given
-h, --help
display this help
Example:
hardi_mat gradient_table.txt recon_mat.dat
-
odf_recon reconstruct the raw images to odf and a few maps,
with a given pre-calculated recon matrix.
Usage: odf_recon RAW_DATA_PREFIX NUMBER_OF_DIRECTIONS NUMBER_OF_OUTPUT_DIRS
OUTPUT_FILE_PREFIX [OPTION]
-mat, --matrix
use given file as reconstruction matrix. by default the program
will pick matrix file automatically by the given number of
diffusion and output directions
-b0, --number_of_b0
number of b0 scans. by default the program gets this information
from the number of directions and number of volume files in
the raw data directory. useful when dealing with incomplete raw
data set or only using part of raw data set to reconstruct
-ot, --output_type
output file type. accepted values are:
analyze -> analyze format 7.5 (NOT recommended)
ni1 -> nifti format saved in seperate .hdr and .img file
nii -> nifti format with one .nii file (default)
nii.gz -> nifti format with compression
default type is 'nii'
-s, --sharpness
smooth or sharpen the raw data. factor > 0 is smoothing.
factor < 0 is sharpening. default value is 0
NOTE: this option applies to DSI study only
-f, --filter
apply a filter (e.g. high pass) to the raw image
-bg, --subtract_background
subtract the background value before reconstruction. if the
switch is on and no value is given, the value will be
calculated automatically from lowb maps
-dsi, --dsi
indicates that the data is dsi
-oe, --output_entropy
output entropy map
following 5 options are to provide image orientation information. if the
input image(s) are genuine nifti format, these flags are NOT needed because
nifti header contains all the needed information. if the program can not
find those information for image header, it will look for -info flag,
if not then -iop, then -sag/cor/axial
-info, --image_info
specify image information file. the image info file is generated
from original dicom image by diff_unpack program and contains image
orientation and other information needed for reconstruction and
tracking. by default will look into the image folder for .info file
NOTE: if info file was not found or given, the following '-iop',
'-sag', '-cor', '-axial' will be used
-iop, --image_orientation_patient
specify image orientation vectors. if just one argument given,
will treat it as filename and read the orientation vectors from
the file. if 6 arguments are given, will treat them as 6 float
numbers and construct the 1st and 2nd vector and calculate the 3rd
one automatically.
this information will be used to determine image orientation,
as well as to adjust gradient vectors with oblique angle when
'-oc' flag is on
default use the identity matrix vectors
-sag, --sagittal
this flag is equal to '-iop 0 1 0 0 0 -1'
-cor, --coronal
this flag is equal to '-iop 1 0 0 0 0 -1'
-axial, --axial
this flag is equal to '-iop 1 0 0 0 1 0'
the above flags indicate image orientation. default is axial.
NOTE: '-iop', '-sag', '-cor' and '-axial' options will overwrite
what '-info' has given. usually if an .info file exists, it should
be used instead of providing '-iop', etc., options manually
end of image orientation options
-p, --paddings
number of 0 paddings for input raw data file prefix. default
value is 3
-sn, --start_number
start number of the input filename numbering. default is 1, meaning
the first filename in the series is prefix001.img
-h, --help
display this help
Example:
assume the raw dsi data has 514 diffusion volumes and 4 lowb(b0) volumes.
1. normal reconstruction -
odf_recon raw\dsi 515 181 recon_out
2. to reconstruct using only part of the raw images -
odf_recon raw\dsi 251 181 recon_out -b0 4
in this case, -b0 must be specified as the program would assume
(518-251+1) as the number of b0's, which is apparently wrong
3. to reconstruct using part of a reconstruction matrix -
odf_recon raw\dsi 515 181 recon_out -mat DSI_matrix_1419x181.dat
in this case, the given matrix has to be in format of n by 181 (the
same number of output directions). The program will use the top 515
rows of the matrix to reconstruct
Note:
starting from v0.2, raw data file(s) can be nifti format and can be one big 4D
image.
-
dti_tracker perform fiber tracking from the reconstructed tensor
and maps by dti_recon and output a track file for TrackVis.
Usage: dti_tracker INPUT_DATA_PREFIX OUTPUT_FILE [OPTION]...
-it, --input_type
input and output file type. accepted values are:
analyze -> analyze format 7.5
ni1 -> nifti format saved in seperate .hdr and .img file
nii -> nifti format with one .nii file
nii.gz -> nifti format with compression
default type is 'nii'
-fact, --fact
use FACT method for tracking. this is the default method.
-rk2, --runge_kutta2
use 2nd order runge-kutta method for tracking.
-tl, --tensor_line
use tensorline method for tracking.
-sl, --stream_line
use interpolated streamline method with fixed step-length
-l, --step_length
set step length, in the unit of minimum voxel size.
default value is 0.5 for interpolated streamline method
and 0.1 for other methods
-at, --angle_threshold
set angle threshold. default value is 35 degree
-atw, --angle_threshold_weight
set angle threshold weighting factor. weighting will be be applied
on top of the angle_threshold
-rseed, --random_seed
use random location in a voxel instead of the center of the voxel
to seed. can also define number of seed per voxel. default is 1
-ix, --invert_x
-iy, --invert_y
-iz, --invert_z
invert x, y or z component(s) of the vector
-sxy, --swap_xy
swap x & y vectors while tracking
-syz, --swap_yz
swap y & z vectors while tracking
-szx, --swap_zx
swap x & z vectors while tracking
-m, --mask
-m2, --mask2
threshold value for mask image. can combine 2 masks.
if not given, the program will try automatically find
the threshold
-om, --output_mask
output a binary mask file in analyze format
-v2, --v2
using the 2nd eigenvector as the primary vector for fiber tracking
-v3, --v3
using the 3rd eigenvector as the primary vector for fiber tracking
following 4 options are to provide image orientation information. if the
input data are genuine nifti format, these flags are NOT needed because
nifti header contains all the needed information. if the program can not
find those information for input data header, it will use the folloing flags
to determine image orientation and slice order
-info, --image_info
specify image information file. the image info file is generated
from original dicom image by diff_unpack program and contains image
orientation and other information needed for reconstruction and
tracking. by default will look into the image folder for .info file
NOTE: if info file was not found or given, the following '-iop',
'-sag', '-cor', '-axial' will be used
-iop, --image_orientation_patient
specify image orientation vectors. if just one argument given,
will treat it as filename and read the orientation vectors from
the file. if 6 arguments are given, will treat them as 6 float
numbers and construct the 1st and 2nd vector and calculate the 3rd
one automatically.
this information will be used to determine image orientation,
as well as to adjust gradient vectors with oblique angle when
'-oc' flag is on
default use the identity matrix vectors
-sorder, --slice_order
set the slice order. 1 means normal, -1 means reversed. default
value is 1
NOTE: '-iop' and '-sorder' is used to determine '-vorder' if
if '-vorder' is not explicitly given
-vorder, --voxel_order
specify the voxel order in RL/AP/IS (human brain) reference. must be
3 letters with no space in between.
for example, RAS means the voxel row is from L->R, the column
is from P->A and the slice order is from I->S.
by default voxel order is determined by the image orientation
(but NOT guaranteed to be correct because of various standards).
for example, siemens axial image is LPS, coronal image is LIP and
sagittal image is PIL.
this information also is NOT needed for tracking but will be saved
in the track file and is essential for track display to map onto
the right coordinates
NOTE: .info file contains all the information for '-iop', '-sorder'
and '-vorder'. so if an .info file exists, it should be used instead
of applying '-iop', '-sorder' or '-vorder' manually, unless you want
to overwrite what '-info' option provided
-h, --help
display this help
Example:
dti_tracker test tracks.trk -m test_FA.img 0.15
-
odf_tracker perform fiber tracking from the reconstructed odf data
and maps by odf_recon and output a track file for TrackVis.
Usage: odf_tracker RECON_DATA_PREFIX OUTPUT_FILE [OPTION]...
-it, --input_type
input and output file type. accepted values are:
analyze -> analyze format 7.5
ni1 -> nifti format saved in seperate .hdr and .img file
nii -> nifti format with one .nii file
nii.gz -> nifti format with compression
legacy -> old odf/max format. will be abandoned in the future
default type is 'nii'
-rk2, --runge_kutta2
use 2nd order runge-kutta method for tracking.
default tracking method is non-interpolate streamline
-l, --step_length
set step length, in the unit of minimum voxel size.
default value is 0.1.
-at, --angle_threshold
set angle threshold. default value is 35 degree for
default tracking method and 25 for rk2
-rseed, --random_seed
use random location in a voxel instead of the center of the voxel
to seed. can also define number of seed per voxel. default is 1
-ix, --invert_x
-iy, --invert_y
-iz, --invert_z
invert x, y or z component(s) of the vector
-sxy, --swap_xy
swap x & y vectors while tracking
-syz, --swap_yz
swap y & z vectors while tracking
-szx, --swap_zx
swap x & z vectors while tracking
-disc, --disc_tracking
use disc tracking.
-m, --mask
-m2, --mask2
threshold value for mask image. can combine 2 masks.
if not given, the program will try automatically find
the threshold
-limit, --limit
in some special case, such as heart data, some track may go into
infinite circle and take long time to stop. this option allows
setting a limit for the longest tracking steps (voxels)
-dsi, --dsi
specify the input odf data is dsi. because dsi recon uses fixed
pre-calculated matrix, some special orientation patch needs to
be applied to keep dti/dsi/q-ball consistent.
this is a temporary solution.
following 4 options are to provide image orientation information. if the
input data are genuine nifti format, these flags are NOT needed because
nifti header contains all the needed information. if the program can not
find those information for input data header, it will use the folloing flags
to determine image orientation and slice order
-info, --image_info
specify image information file. the image info file is generated
from original dicom image by diff_unpack program and contains image
orientation and other information needed for reconstruction and
tracking. by default will look into the image folder for .info file
NOTE: if info file was not found or given, the following '-iop',
'-sag', '-cor', '-axial' will be used
-iop, --image_orientation_patient
specify image orientation vectors. if just one argument given,
will treat it as filename and read the orientation vectors from
the file. if 6 arguments are given, will treat them as 6 float
numbers and construct the 1st and 2nd vector and calculate the 3rd
one automatically.
this information will be used to determine image orientation,
as well as to adjust gradient vectors with oblique angle when
'-oc' flag is on
default use the identity matrix vectors
-sorder, --slice_order
set the slice order. 1 means normal, -1 means reversed. default
value is 1
NOTE: '-iop' and '-sorder' is used to determine '-vorder' if
if '-vorder' is not explicitly given
-vorder, --voxel_order
specify the voxel order in RL/AP/IS (human brain) reference. must be
3 letters with no space in between.
for example, RAS means the voxel row is from L->R, the column
is from P->A and the slice order is from I->S.
by default voxel order is determined by the image orientation
(but NOT guaranteed to be correct because of various standards).
for example, siemens axial image is LPS, coronal image is LIP and
sagittal image is PIL.
this information also is NOT needed for tracking but will be saved
in the track file and is essential for track display to map onto
the right coordinates
NOTE: .info file contains all the information for '-iop', '-sorder'
and '-vorder'. so if an .info file exists, it should be used instead
of applying '-iop', '-sorder' or '-vorder' manually, unless you want
to overwrite what '-info' option provided
-h, --help
display this help
Example:
odf_tracker recon_data_prefix tracks.trk -at 35
Note:
make sure to set DSI_PATH to the directory where all the reconstruction
matrix files are located. by default DSI_PATH points to ~rpwang/bin/DSI
-
spline_filter smooth and clean up the original track file generated by
dti_tracker or odf_tracker.
Usage: spline_filter INPUT_TRACK_FILE STEP_LENGTH OUTPUT_TRACK_FILE
Note:
STEP_LENGTH is in the unit of minimum voxel size
Example:
spline_filter tracks.trk 0.5 tracks_spline.trk
-
track_transform transform a track file using given registration matrix.
Usage: track_transform INPUT_TRACK_FILE OUTPUT_TRACK_FILE [OPTION]...
-src, --source_volume
source volume file that the original tracks are based on, usually
dwi or b0 volume. must be in nifti format.
-ref, --reference_volume
reference volume file that the tracks are registered to.
must be in nifti format.
-reg, --registration_matrix_file
registration matrix file from source to reference volume.
-invert_reg, --invert_registration_matrix
invert the registration matrix. for convenience of inverse
transformation.
-reg_type, --registration_type
type of the registration matrix. valid inputs are 'flirt' or
'tkregister'. default is 'flirt'.
-h, --help
display this help
Example:
track_transform tracks.trk tracks_new.trk -src dti_b0.nii -ref brain.nii -reg reg.mtx
-
track_info print out header information of a track file.
Usage: track_info INPUT_TRACK_FILE
-
track_merge merge multiple track files into one.
Usage: track_merge INPUT_TRACK_FILE_1 INPUT_TRACK_FILE_2 ... OUTPUT_FILE
Note: OUTPUT_FILE will be over-written if exists.
|
