We present a framework which uses an unscented Kalman filter for performing tractography. At each point on the fiber the most consistent direction is found as a mixture of previous estimates and of the local model.
It is very easy to expand the framework and to implement new fiber representations for it. Currently it is possible to tract fibers using two different 1-, 2-, or 3-tensor methods. Both methods use a mixture of Gaussian tensors. One limits the diffusion ellipsoids to a cylindrical shape (the second and third eigenvalue are assumed to be identical) and the other one uses a full tensor representation.
Authors: Yogesh Rathi (yogesh@bwh.harvard.edu), Stefan Lienhard, Yinpeng Li, Martin Styner, Ipek Oguz, Yundi Shi, Christian Baumgartner (c.f.baumgartner@gmail.com), Ryan Eckbo, Tashrif Billah, Dheshan Mohandass
For references and further documentation, please see the Slicer module homepage.
In April 2025, we revamped ukftractography installation infrastructure and made a Docker container to facilitate future installation and usage. The container can be pulled from Docker Hub:
docker pull tbillah/ukftractography:latest
Then, it can be used as:
docker run --rm -v /local/path/to/data:/remote/data/ ukftractography \
--dwiFile /remote/data/dwi.nhdr --maskFile /remote/data/mask.nhdr \
--tracts /remote/data/tracts.vtk ...
As you see, the mandatory step is to mount local data into the Docker container first.
Then, you can reference the mounted data to construct ukftractography arguments e.g.
--dwiFile, --maskFile, etc.
However, to simply shell into the container, use:
docker run --rm -ti --entrypoint /bin/bash ukftractography
Checkout from github:
git clone https://github.com/pnlbwh/ukftractography.git
There are 3 ways to build this project from source. Way (a) is tested for every pull request to this repository. Way (b) is rarely tested. Way (c) is done every night that can be checked at https://slicer.cdash.org/projects.
cd <build-dir>
cmake <path-to-source>
make
cd UKFTractography-build/UKFTractography
ctest
cd <build-dir>
cmake -DSlicer_DIR=<path-to-Slicer5-Superbuild>/Slicer-build <path-to-source>
make
cd UKFTractography-build/UKFTractography
ctest
c) Build via Slicer ExtensionIndex build
< 8000 a id="user-content-c-build-via-slicer-extensionindex-build" class="anchor" aria-label="Permalink: c) Build via Slicer ExtensionIndex build" href="#c-build-via-slicer-extensionindex-build">Create local extension index following these instructions, containing at least UKFTractography.s4ext and SlicerDMRI.s4ext (required runtime dependency).
Notes:
-
To manually test the
UKF TractographySlicer module, start Slicer using the launcher namedSlicerWithSlicerDMRIavailable in/path/to/SlicerDMRI-build/inner-builddirectory. This ensure that the SlicerDMRI modules are loaded and that the required MRML diffusion nodes are registered (i.e vtkMRMLFiberBundleNode). -
It may be helpful to test the exension upload using your API key.
Navigate to the Slicer Extension Manager and download UKF Tractography to
install it as a Slicer 5 module.
The executable is called 'UKFTractography'. It can be found in:
<build-dir>/UKFTractography-build/UKFTractography/bin/
In order to see all options run.
./UKFTractography --help
In the source directory of the project you will find a shell script called examples/sample_run.sh. It should give you an idea of what a function call could look like.
Files dataset_Mask.nrrd and seeds_full_cc.nrrd in Input folder are mask and seed files of subject 100307
in hcp dataset, download the subject's preprocessed diffusion MRI data from https://db.humanconnectome.org/.
Navigate to the Slicer Extension Manager and download UKF Tractography to
install it as a Slicer 5 module. There will be 3 modules under
Diffusion-->Tractography: UKF Tractography, vtk2mask, and vtkFilter.
-
There are rounding errors that affect the accuracy of 2T FW tracts. This explains why the 2T_FW ctest fails.
-
Several steps in the SuperBuild process download additional git repositories as CMake external projects. By default
UKFTractography_USE_GIT_PROTOCOL:BOOL=OFFindicates to usehttps://instead ofgit://. This default should work behind most firewalls (the git protocol uses port 9418: if this is blocked by your firewall the build will fail). If download problems are encountered, please file an issue. -
In April 2025, there were several updates to ukftractography installation infrastructure. The updates were adequately tested on RHEL 9 OS. However, it was brought to our attention that, upon installing the current UKFTractography from Slicer Extension Manager in Apple Silicon Macs, Slicer-5 crashes when UKFTractography module is started. The solution is believed to be an OS X update: macOS 14.6.1 --> Sequoia 15.4. OS X is expected to ask the user to perform the update to fix this problem. So feel free to do the update.