UKFTractography Documentation

1.0

This module traces fibers in a DWI Volume using the multiple tensor unscented Kalman Filter methology.

UKFloop.png

System overview illustrating relation between the neural fibers, scanner signals, and the unscented Kalman Filter as it is used to estimate the local model

Authors:
Yogesh Rathi, Stefan Lienhard, Yinpeng Li, Martin Styner, Ipek Oguz, Yundi Shi, Christian Baumgartner

Introduction

The C++ module for Unscented Kalman Filter (UKF) Tractography enables the user to easily perform multi-tensor filtered tractography on diffusion weighted MR images.
The model is highly customizable. one-, two-, and three-tensor models are available with, and without free water estimation. In addition, a 'full tensor model' representation is available, where each of the eigenvalues is modeled sperately. The UKF can be run constrained with Quadratic Programming or unconstrained.
The code can be easily compiled as described below, and can be run either from command line or as Slicer 3 or 4 module.

Building

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

  1. Standalone: From your build directory run the following commands
        cmake <path-to-source>/SuperBuild
        make
    
    This will download all resources and build the project for you.
    Note: cmake >= 2.8.4, git, and svn are required for this
  2. Build with Slicer: To build against one of the slicer versions run
    1. Slicer 3
               cmake -DSlicer3_DIR=<path-to-slicer3>/Slicer3-build <path-to-source>
               make
      
    2. Slicer 4
              cmake -DSlicer_DIR=<path-to-slicer4>/Slicer-build <path-to-source>
              make
      
    Note: cmake >= 2.6, and an installed version of boost >1.41.1 is required Also, you must have a Slicer build. Only, executables are not enough.
  3. 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

Running

  1. As Command Line Module: The executable will be called 'UKFTractography', and can be found in the bin directory of your build folder.
    In order to see all options run.
         ./UKFTractography --help 
    
    In the source directory of the project you will find a shell script called 'sample_run.sh' It should give you an idea of what a function call could look like.
  2. As Slicer 3 or 4 module: Open Slicer and in the settings add the '<path-to-build>/bin' directory. When you restart Slicer the module will be under Diffusion->Tractography.

Options

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.

Dependencies

Boost
The Boost C++ Libraries are a collection of free libraries that extend the functionality of C++. In this project boost is used for multithreading, and the progress bar.
teem
Teem is a coordinated group of libraries for representing, processing, and visualising scientific raster data. We use it to read, and process The input data of type NRRD.
ITK
Insight Segmentation and Registration Toolkit (ITK). ITK is an open-source, cross-platform system that provides developers with an extensive suite of software tools for image analysis. In this application we only use the underlying vnl libraries for most of the linear algebra processing. It replaces functionality that was done with LAPACK before.
Slicer Execution Model
The Execution Model provides a simple mechanism for incorporating command line programs as Slicer modules. These command line modules are self-describing, emitting an XML description of its command line arguments. Slicer uses this XML description to construct a GUI for the module. We use it to make our application into a Command Line Module that can be run from Slicer, or from a Consolse without being dependand on Slicer.

Screenshots

2TFW_0.png

Tracing fibers through the anterior limb of the internal capsule

Todo:
Doxygen can elegantly be generated by cmake as describe e.g. here http://www.cmake.org/pipermail/cmake/2006-August/010794.html.
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Defines