This module traces fibers in a DWI Volume using the multiple tensor unscented Kalman Filter methology.
System overview illustrating relation between the neural fibers, scanner signals, and the unscented Kalman Filter as it is used to estimate the local model
In order to build make a new directory outside of the source tree called for example ukf-build.
There are 3 ways to build the project
cmake <path-to-source>/SuperBuild make
cmake -DSlicer3_DIR=<path-to-slicer3>/Slicer3-build <path-to-source> make
cmake -DSlicer_DIR=<path-to-slicer4>/Slicer-build <path-to-source> make
Manual Build: You can take care of all dependancies yourself, the easiest way to do this is using ccmake. Run ccmake from your build directory
ccmake <path-to-source>
Provide the Links to the builds of ITK, Teem, GenerateCLP, and Boost
make
Note: This is only recommended if the above two methods failed for some reason
./UKFTractography --help
Input/Output (IO)
--dwiFile <std::string> | Input DWI Image |
--seedsFile <std::string> | Seeds for diffusion. If not specified, full brain tractography will be performed, and the algorithm will start from every voxel in the brain mask where the Generalized Anisotropy is bigger than 0.18 |
--labels <std::vector<int>> | A vector of the ROI labels to be used (default: 1) |
--maskFile <std::string> | Mask for diffusion tractography |
--tracts <std::string> | Tracts generated, with first tensor output |
--tractsWithSecondTensor <std::string> | Tracts generated with second tensor output (if there is one) |
Seeding Options
--seedsPerVoxel <int> | Number of seeds per voxel (default: 1) |
Model Options
--numTensor <1|2|3> | Number of tensors used (default: 2) |
--simpleTensorModel | Whether to use the simple tensor model. If unchecked, use the full tensor model |
--freeWater | Adds a term for free water difusion to the model. If checked, the 1T simple model is forced. |
Stopping Criteria
--minFA <double> | Abort the tractography when the Fractional Anisotropy is less than this value (default: 0.15) |
--minGA <double> | Abort the tractography when the Generalized Anisotropy is less than this value (default: 0.1) |
Fiber Scalar Fields
--recordFA | Whether to store FA. Attaches field 'FA', and 'FA2' for 2-tensor case to fiber. |
--recordNMSE | Whether to store NMSE. Attaches field 'NMSE' to fiber. |
--recordTrace | Whether to store Trace. Attaches field 'Trace', and 'Trace2' for 2-tensor case to fiber. |
--recordFreeWater | Whether to store the fraction of free water. Attaches field 'FreeWater' to fiber. |
--recordState | Whether to attach the states to the fiber. Will generate field 'state'. |
--recordCovariance | Whether to store the covariance. Will generate field 'covariance' in fiber. |
--recordTensors | Recording the tensors enables Slicer to color the fiber bundles by FA, orientation, and so on. The fields will be called 'TensorN', where N is the tensor number. |
Advanced Options
--numThreads <int> | Number of threads used during compuation. Set to the number of cores on your workstation for optimal speed. If left undefined boost will figure out the number of cores, and hence threads, during runtime. |
--normalizedDWIData | Whether the DWI input data is already normalized |
--stepLength <double> | Step length of tractography, in millimeters. (If not set, defined during runtime) |
--weightsOnTensors <std::vector<double>> | Weights on different tensors when using multiple tensors. There must be one weight for each tensor, and the weights must sum up to 1. Defaults to equally weighted. |
--maxHalfFiberLength <double> | The max length limit of the half fibers generated during tractography. Here the fiber is "half" because the tractography goes in only one direction from one seed point at a time (default: 10000) |
--seedFALimit <double> | Seed points whose FA are below this value are excluded. (If not set, defined during runtime) |
--Qm <double> | Process noise for angles/direction. (If not set, defined during runtime) |
--Ql <double> | Process noise for eigenvalues. (If not set, defined during runtime) |
--Qw <double> | Process noise for free water weights, ignored if no free water estimation. (If not set, defined during runtime) |
--Rs <double> | Measurement noise. (If not set, defined during runtime) |
--maxBranchingAngle <double> | Maximum branching angle, in degrees. When using multiple tensors, a new branch will be created when the tensors' major directions form an angle between (minBranchingAngle, maxBranchingAngle). Branching is supressed when this maxBranchingAngle is set to 0.0 |
--minBranchingAngle <double> | Minimum branching angle, in degrees. When using multiple tensors, a new branch will be created when the tensors' major directions form an angle between (minBranchingAngle, maxBranchingAngle) |
Additional Output Options
--noTransformPosition | Don't transform Points back from ijk->RAS when writing the output fiber |
--branchesOnly | Only output branches, ignore the primary tracts |
--storeGlyphs | Store tensors' main directions as two-point lines in a separate file named glyphs_{tracts}. When using multiple tensors, only the major tensors' main directions are stored |
--outputNormalizedDWIData | Whether to output the DWI after normalization (i.e. preprocessing) |
Tractography unrelated options
--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. |
--echo | Echo the command line arguments. |
--, --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. |
Tracing fibers through the anterior limb of the internal capsule