Trekker

Note

December 19th, 2024

UPDATE: Trekker v1.0.0-rc2 now out! See below for a list of major changes.

Trekker offers state-of-the-art tractography tools to study the structural connectivity of the brain. Trekker aims to improve fiber tracking pipelines by offering features like:

  • Well-organized, clean, probabilistic streamline tractography using the parallel transport tractography (PTT) algorithm.

  • A comprehensive set of tractogram filtering options, including support for anatomical constraints using surface meshes.

  • Compatibility with .vtk format, to enable the use of powerful third-party 3D rendering software, such as Paraview, for easy and high-quality visualizations.

  • Support for asymmetric FODs, providing greater flexibility in fiber tracking.

  • Several features designed for high-performance computing (HPC), including multithreading, time-limited tracking, and a user-friendly command line interface.

  • Since 2017, algorithms and pipelines based on Trekker have earned awards in every international tractography competition, each featuring different themes.

See also

🏆 Awards and Recognitions

Tractography pipelines based on Trekker have earned awards in every international tractography challenge since 2017. Click here to learn more about Trekker’s awards.

Installation

Option 1: Stand-alone executables

Please find the stand-alone executables under Releases.

Option 2: Building from source

Trekker relies on nibrary. To compile Trekker from source, ensure that nibrary is installed first. Then follow these steps to compile Trekker:

Step 1: Download the Source Code

git clone https://github.com/dmritrekker/trekker

Step 2: Modify and run the build script

  • For Linux: Edit build_Linux.sh

Usage

Simply run trekker on the terminal. This will display help and the commands, which are listed below:

Command Description
info Displays information about input file.
track Performs fiber tracking using parallel transport tractography (PTT) algorithm. PTT excels in reconstructing geometrically smooth and topographically organized fiber bundles.
filter Trekker employs an intuitive set of pathway rules to filter tractograms. The rules can be specified with surface meshes, as well as with spheres, image masks and partial volume fractions.
track2img Maps tractogram features on an image.
track2surf Maps tractogram features on a surface.
img2track Maps image values on a tractogram.
select Selects streamlines from a tractogram.
resample Resamples streamlines in a tractogram.
convert Converts tractogram file formats (.vtk, .tck, .trk).
transform Applies a transform on an input tractogram.
diff Finds different streamlines between two tractograms.
merge Merges two tractograms, optionally ignoring duplicates.
addColor Adds colors to streamlines (.vtk only).
fieldExport Exports a selected vtk field from a tractogram (.vtk only).
fieldImport Adds a new vtk field with values read from a file (.vtk only).
fieldRemove Removes a vtk field from a tractogram (.vtk only).

Examples

Fiber tracking example:

./trekker track \
          FOD.nii.gz \
          --seed WHITE_MATTER_SURFACE.gii \
          --seed_surf_useSurfNorm \
          --seed_count 100000 \
          --pathway discard_if_ends_inside WHITE_MATTER.nii.gz \
          --pathway discard_if_enters CSF.nii.gz \
          --minLength 20 \
          --maxLength 300 \
          --output OUT_TRACK.vtk

Fiber filtering example:

# You can use the --seed option when filtering too.
./trekker filter \
          INP_TRACK.vtk \
          --seed WHITE_MATTER_SURFACE.gii \
          --pathway require_end_inside LEFT_THAL.nii.gz \
          OUT_TRACK.vtk

Release notes for Trekker-v1.0.0-rc2

  • Bug fix 1: Fixed a bug which prevented using negative labels for selecting surface ROIs.

  • Bug fix 2: Fixed a bug in track2surf that was introduced as a result of the major updates in rc1, which led to the saving of wrong field information for mapped streamlines on surface meshes.

  • Improvement 1: Added a new command info, which prints basic information about input files.

  • Improvement 2: Added option to flip surface normals when defining pathway rules.

  • Improvement 3: Added option to use only the surface boundary when the provided mesh is closed for defining pathway rules.

  • Improvement 4: (As a solution to the nibrary issue submitted by Xi Zhu) Added option to use ascii (text) files for defining seed density for fiber tracking with surface-based seeding.

  • Improvement 5: Random seeds are now sampled using an approach based on cumulative distribution function instead of rejection sampling.

Release notes for Trekker-v1.0.0-rc1

  • Bug fix 1: Fixed a bug in track where streamlines were not stopped as expected when a pathway rule was set. This issue occurred because track allowed stop options unsupported by nibrary. The fix involved providing nibrary with the necessary stopping features during tracking.

  • Bug fix 2: (Thanks to John Kruper for spotting this one!) Fixed a bug in track related to the computation of data support in parallel transport tracking. Previously, the contribution from the last part of the probe was reused as the first part’s contribution in the next iteration to speed up computation. This fix ensures the data support contribution is computed only once for the first part and reused for other candidate probes. Although this bug has existed since v0.5, it should not significantly affect results with default probe quality (4) and length (0.25 x voxel size). However, it may impact streamlines computed with longer probe lengths and lower quality probes.

  • Bug fix 3: Fixed a bug affecting both track and filter, where streamlines were not following the require_end_inside rule. The issue occured because this rule was commented out during a part of the development, and it was forgotten to be restored.

  • Improvement 1: Reorganized the code to harmonize the handling of segment-surface interactions.

  • Improvement 2: Switched to the double datatype in certain functions to better manage edge cases.

With the beta release (May 21st, 2024), Trekker has gone through significant changes:

  • Powered by nibrary, Trekker now features:

    • Support for surface based tracking and filtering

    • Advanced pathway rules for filtering streamlines

    • Subcommands to perform various tractogram operations

    • Improved command line interface

  • While the core fiber tracking algorithm (PTT) works the same, the new version of Trekker is not compatible with the previous versions due to the above changes.

    • Remark: Your previous code (script) written for earlier versions of Trekker need to be modified to work with the latest version.

  • Some existing features in earlier versions of Trekker are currently missing in the latest version:

    • Windows compatibility

    • Python and Matlab support

    • Exporting of a .json formatted tracking report

Enjoy the new Trekker!