track¶
fiber tracker
Usage
./trekker track <FOD image> [OPTIONS]
Positionals
<FOD image> FILE:FILE … REQUIRED Input FOD image (.nii, .nii.gz). Trekker supports both symmetric and asymmetric FODs, i.e. spherical harmonics with both even and odd orders.
Options
| Option | Description |
|---|---|
| -o, --output FILE REQUIRED | Output tractogram (.vtk, .tck). |
| -a, --ascii | Write ASCII output (.vtk only). |
| -w, --writeStepSize FLOAT | Because stepSize might be very small, it might not be desirable to save each step of propagation in the output. writeStepSize enables skipping of a number of steps before saving them. This parameter does not change the propagation algorithm; internally Trekker always walks with the specified --stepSize. Default: the distance between the output tracks is 0.5 x the smallest of the FOD voxel dimensions. |
Algorithm parameters
| Option | Description |
|---|---|
| --stepSize FLOAT | Step size. Default=1/40 x the smallest of the FOD voxel dimensions. |
| --minRadiusOfCurvature FLOAT | Minimum radius of curvature. Default=1/2 x the smallest of the FOD voxel dimensions. |
| --minDataSupport FLOAT | Threshold for minimum data support. For PTT algorithm this is minimum FOD threshold. Default=0.05. |
| --dataSupportExponent FLOAT | Data support to the power dataSupportExponent is used for rejection sampling. Default=1. |
| --orderOfDirections TEXT | Switches direction of FOD. By default XYZ is assumed (no change). A lower case can be used to switch the direction, e.g., xYZ switches the sign of the first component. The order of components can be changed as well, e.g., yXz switches the sign of the second component while replacing it with the first, at the same time the sign of the last component is also changed. |
| --dontDiscretizeFod | Turns off FOD discretization. For faster tracking, Trekker by default will discretize the FOD on a sphere (using 2076 points for symmetric functions and 1004 points for asymmetric functions). |
| --runTimeLimit INT | Sets the maximum allowed duration in minutes for Trekker to continue tracking. Tracking stops when time limit is reached. When tracking stops due to time limit, all the streamlines that are computed so far are written to the disk. |
| --idleTimeLimit INT | Sets the maximum allowed duration in minutes from the computation of the last successful streamline, i.e., if no new streamlines were computed within this time, Trekker stops. |
Sampling parameters
| Option | Description |
|---|---|
| --maxEstInterval INT | For random sampling, an estimate for the maximum posterior probability is needed. If set to n, this estimate is computed at every n^th step. Default=1. |
| --initMaxEstTrials INT | Number of trials done for the estimation of maximum posterior probability during initialization. Default: is set adaptively based on previous trials. |
| --propMaxEstTrials INT | Number of trials done for the estimation of maximum posterior probability during propagation. Default: is set adaptively based on previous trials. |
| --maxSamplingPerStep INT | Maximum number of random sampling to select an acceptable candidate for propagation. Tracking stops if a suitable candidate cannot be found after this many attempts. Default: 1000. |
| --useBestAtInit | If used, during initialization, random sampling is skipped and the candidate that has the largest data support is used for propagation. Default: off. |
| --useLegacySampling | If used, during propagation, random sampling will be done using rejection sampling. Default: off. |
| --samplingQuality INT | Integer value between 1 and 7 that controls the quality of sampling. Default=2. |
PTT probe parameters
| Option | Description |
|---|---|
| --probeLength FLOAT | Length of the probe. Default=1/4 x the smallest of the FOD voxel dimensions. |
| --probeRadius FLOAT | Radius of the probe. Default=0. |
| --probeCount INT | probeCount determines the number of parallel lines used to model the cylinder. Default: 1 if probeRadius=0, 4 if probeRadius≠0. |
| --probeQuality INT | This parameter sets the number of segments to split the cylinder along the length of the probe. Default=4. |
| --ignoreWeakLinks FLOAT | If the individual data support (FOD amplitude along the direction of the segment) for any of the points in the probe is lower than what is specified with this parameter, this candidate probe is ignored. Default: 0. |
Seeding parameters
| Option | Description |
|---|---|
| -s, --seed TEXT ... | Seed definition. |
| --discard_seed TEXT ... | If a seed point falls into this region, it will be discarded. |
| --skipSeed | Does not output the points that are within seed region. |
| --seed_trials INT | Sets the maximum number of attempts to generate streamline from the seed point. Default=1. |
| --seed_count INT | Number of seeds. Trekker tries to generate a single streamline from each seed. For that it makes maximum amount of "trials". If an acceptable streamline cannot be generated then it is skipped. If this happens, there will be fewer streamlines in the output tractogram than what is defined with "count". |
| --seed_density FLOAT | Density of seeds. If seed is an image, density is the number of seeds per mm^3. If seed is a surface mesh, density is the number of seeds per mm^2. |
| --seed_surf_faceDensity TEXT ... | A text file containing density information for each face of the input seed surface. |
| --seed_surf_vertDensity TEXT ... | A text file containing density information for each vertex of the input seed surface. |
| --seed_surf_fieldDensity TEXT | The given field in the input seed surface will be used to set seed density. |
| --seed_surf_useSurfNorm | Surface normals will be used as the initial direction. |
Pathway options
Tip
Please check the documentation for pathways for a detailed explanation.
| Option | Description |
|---|---|
| -p, --pathway TEXT ... | Pathway rules. |
| --minlength FLOAT | Minimum length of output streamlines. Default=0. |
| --maxlength FLOAT | Maximum length of output streamlines. Default=infinite. |
| --oneSided | If enabled, tracking is done only towards one direction. Default=OFF. |
| --stopAtMax | If used, propagation stops when maxLength is reached. By default, streamlines are discarded when propagation reaches maxLength. |
| --inOrder | If enabled, all pathway requirements are going to be satisfied in the order that they are input to Trekker. All pathway options should be defined for pathway_A/pathway_B in order to use this option. |
General options
| Option | Description |
|---|---|
| -h, --help | Print this help message and exit. |
| -n, --numberOfThreads INT | Number of threads. |
| -v, --verbose TEXT | Verbose level. Options are "quiet", "fatal", "error", "warn", "info", and "debug". Default=info. |
| -f, --force | Force overwriting of existing file. |
References
Please cite [Aydogan2021], which provides a detailed explanation of the algorithm and the results obtained from extensive experiments. A precursory abstract was initially published during ISMRM 2019, Montreal [Aydogan2019], which can additionally be cited.
