Pathways

Definitions

Trekker allows for a variety of pathway rules to apply anatomical constraints for fiber tracking and filtering. Before reading the rules in detail, please check the illustration below for definitions:

Trekker's pathways

When a seed is provided, Trekker regards each streamline to be composed of two sides, which are called A and B.

Tip

  • Trekker automatically determines the sides as A or B based on how they meet the user defined pathway rules, i.e., if the first side meets the criteria for B then Trekker assigns it as side B.

  • When a seed is not provided, rules with _A or _B options can not be used.

  • You can disable the default "two-sided" tracking or filtering by using the --oneSided option.

Rules

Trekker offers powerful options for specifying pathway definitions. Rules can be defined using the --pathway option followed by one of the below rules:

  • Require rules

    • require_entry: Pathway has to enter the region

    • require_exit: Pathway has to enter and then exit the region

    • require_end_inside: Pathway has to enter but can’t exit the region

  • Discard rules

    • discard_if_enters: Pathway can’t enter the region

    • discard_if_exits: Pathway can enter but can’t exit the region

    • discard_if_ends_inside: Pathway can enter but can’t end inside the region

  • Stop rules (requires a seed to be defined first)

    • stop_at_entry: If a pathway enters the region, it will be truncated at the point of entry. The end point will be precisely the region border.

    • stop_before_entry: If a pathway is about to enter the region, it will be truncated just before it enters there. The end point will be outside the region.

    • stop_after_entry: If a pathway enters the region, it will be truncated just after it enters there. The end point will be inside the region.

    • stop_at_exit: If a pathway exits the region, it will be truncated at the point of exit. The end point will be precisely the region border.

    • stop_before_exit: If a pathway is about to exit the region, it will be truncated just before it exit. The end point will still be inside the region.

    • stop_after_exit: If a pathway exits the region, it will be truncated just after it exits. The end point will be outside the region.

The rules can be further fine-tuned using the following options:

  • With --inOrder option is used, require_entry and require_exit rules are adhered to in the order that they are specified.

  • Trekker supports the definition of seed regions for both tracking and filtering, using the --seed or -s options.

  • When a seed is defined for filtering, all the streamlines are treated as if they were computed using that region as the seed. This means that if only a seed is provided without any other filtering option, the result is identical to the case where only the require_entry rule is defined.

  • The following filtering features can only be used when a seed is defined:

    • Side-specific filtering: The above pathway rules can be defined separately for each side of the track, using _A and _B extensions, e.g., require_entry_A or discard_if_ends_inside_B. Here, the seed is considered to be somewhere between the end points A and B. If one of the pathway rules is defined using the _A or _B extensions, then all the other rules must also have an _A or _B extension.

    • One-sided filtering: The --oneSided option can only be used when pathway rules are not side-specific. When --oneSided is used, starting from the seed, only one side of the track is taken into account, the other side is ignored, and it will not appear in the output.

    • Skipping seed: The --skipSeed option can only be used together with --oneSided. When --skipSeed is enabled, the output tracks only have one point that falls within the seed, and that point is one of the endpoints of the tracks.

    • Using stop rules: The stop_at_entry and stop_at_exit rules can only be used when a seed is defined.

Regions

Trekker supports the following to be used together with the seed and pathway rule definitions:

  • Sphere: e.g. -p require_entry 1.2,2.4,33.2,4 defines a sphere using x,y,z,r notation.

  • Image files (.nii, .nii.gz): The use of images are interpreted in six different ways:

    1. If only an integer type image is provided, as in img.nii, then it is considered as a mask that is created by thresholding values above zero. During filtering, nearest neighbor interpolation is used.

    2. If only a floating type image is provided, as in img.nii, then it is considered to provide partial volume fraction. A value above zero is considered inside, and during filtering, linear interpolation is used.

    3. If an image is provided followed by label, as in img.nii label, then it is considered as a mask that is created by thresholding values above zero. During filtering, nearest neighbor interpolation is used.

    4. If an image is provided followed by pvf, as in img.nii pvf, then it is considered to provide partial volume fraction. A value above zero is considered inside, and during filtering, linear interpolation is used.

    5. If an image is provided followed by label and an integer, as in img.nii label 1023, then the provided integer value is considered as a label and a label image is created only using that value. During filtering, nearest neighbor interpolation is used.

    6. If an image is provided followed by pvf and an integer, as in img.nii pvf 0, then it is considered that the input image is 4-dimensional, where the 4th dimension contains partial volume fractions, and the provided integer indicates the volume to use for filtering. A value above zero is considered inside, and during filtering, linear interpolation is used.

  • Surface files (.vtk, .gii):

    1. Surfaces can be provided only as they are, as in -s surf.vtk.

    2. If the surface is followed by x,y,z,r notation, as in -s surf.vtk 1.2,2.4,33.2,4, then a disc centered at x,y,z with radius r is extracted and used for the rule.

    3. If the surface is followed by a string and an integer, as in -s surf.vtk label,3, then the surface is considered to contain a field with the provided string. The integer is used as a label, which is used for filtering, e.g., a surface containing labels for different parts of the brain can be used for filtering.

    4. If the surface is defined as in -s surf.vtk fileName,VERT,int,3, then the fileName is considered to contain labels for each VERTices, the file contains int (integer) data type, and the filtering should only consider VERTices with label 3.

    Note

    • Inside/outside of a surface is determined by the direction of the normal vectors. It is considered that normals point towards the outside of surface meshes. This convention can be changed by using -s surf.vtk flipNormals, which will internally flip the direction of the surface normals when tracking/filtering.

    • For fast filtering, Trekker first discretizes the surface meshes onto images. The default discretization resolution is 1, which can be changed by proving a scalar number after the surface file is defined, as in -s surf.vtk 0.4 label,3, where 0.4 will be used to discretize the surface.

    • If the surface is closed, it is possible exclude the interior region, and only apply the rules based on the surface mesh (boundary). This can be done by adding 2D after the file name, as in -s surf.vtk 2D label,3.

    • It is possible change the place of the surface options, e.g. -s surf.vtk label,3 0.5 2D is same as -s surf.vtk 0.5 label,3 2D.