usage: __main__.py [-h] [--out_colliding_prefix OUT_COLLIDING_PREFIX]
[--out_metrics OUT_METRICS]
[--out_rotation_matrix OUT_ROTATION_MATRIX]
[--min_distance MIN_DISTANCE] [--disable_shuffling]
[--rng_seed RNG_SEED] [--indent INDENT] [--sort_keys] [-f]
[-v [{DEBUG,INFO,WARNING,ERROR}]]
in_tractogram in_diameters out_tractogram
Given an input tractogram and a text file containing a diameter for each
streamline, filters all intersecting streamlines and saves the resulting
tractogram and diameters.
IMPORTANT: The input tractogram needs to have been resampled to segments of
at most 0.2mm. Otherwise performance will drop significantly. This is because
this script relies on a KDTree to find all neighboring streamline segments of
any given point. Because the search radius is set at the length of the longest
fibertube segment, the performance drops significantly if they are not
shortened to ~0.2mm.
(see scil_tractogram_resample_nb_points)
IMPORTANT: Some tractograms, especially if old, were created with a very high
float precision. scil_tractogram_filter_collisions does not save its output
with such precision. This means that after filtering once and saving the
result, new collisions may be created from saving at a lower float precision.
It will require a second filtering to be truly collision-free.
If you are using the --out_metrics parameter on high float precision data, the
script may even throw an error saying that not all collisions were filtered
prior to metrics computation.
Solution: If you encounter such behaviour, we recommend you load and save your
tractogram to be filtered with up-to-date tools such as MI-Brain or the
Nibabel python library. (Which scilpy scripts use)
----------
The filtering is deterministic and follows this approach:
- Pick next streamline
- Iterate over its segments
- If current segment collides with any other streamline segment given
their diameters
- Current streamline is deemed invalid and is filtered out
- Other streamline is left untouched
- Repeat
This means that the order of the streamlines within the tractogram has a
direct impact on which streamline gets filtered out. To counter the resulting
bias, streamlines are shuffled first unless --disable_shuffling is set.
If the --out_metrics parameter is given, several metrics about the data will
be computed (all expressed in mm):
- min_external_distance
Smallest distance separating two streamlines, outside their diameter.
- max_voxel_anisotropic
Diagonal vector of the largest possible anisotropic voxel that
would not intersect two streamlines, given their diameter.
- max_voxel_isotropic
Isotropic version of max_voxel_anisotropic made by using the smallest
component.
Ex: max_voxel_anisotropic: (3, 5, 5) => max_voxel_isotropic: (3, 3, 3)
- max_voxel_rotated
Largest possible isotropic voxel obtainable if the tractogram is
rotated.
It is only usable if the entire tractogram is rotated according to
[rotation_matrix].
Ex: max_voxel_anisotropic: (1, 0, 0) => max_voxel_isotropic: (0, 0, 0)
=> max_voxel_rotated: (0.5774, 0.5774, 0.5774)
If the --out_rotation_matrix option is provided, the following will be saved:
- rotation_matrix
4D transformation matrix representing the rotation to be applied on
the tractogram to align max_voxel_rotated with the coordinate system
(see scil_tractogram_apply_transform.
See also:
- docs/source/documentation/fibertube_tracking.rst
positional arguments:
in_tractogram Path to the tractogram file containing the
streamlines (must be .trk).
in_diameters Path to a text file containing a list of
diameters in mm. Each line corresponds
to the identically numbered streamline.
If unsure, refer to the diameters text file of the
DiSCo dataset. If a single diameter is provided, all
streamlines will be given this diameter.
out_tractogram Tractogram output file free of collision (must
be .trk). By default, the diameters will be
saved as data_per_streamline.
options:
-h, --help show this help message and exit
--out_colliding_prefix OUT_COLLIDING_PREFIX
Useful for visualization. If set, the script will
produce two other tractograms files containing
colliding streamlines. The first one contains invalid
streamlines that have been filtered out, along with
their collision point as data per streamline. The
second one contains the potentially valid streamlines
that the first tractogram collided with. Note that the
streamlines in the second tractogram may or may not
have been filtered afterwards.
Filenames are derived from [out_colliding_prefix] with
"_invalid" appended for the first tractogram, and
"_obstacle" appended for the second tractogram. You
may include a path in this prefix.
--out_metrics OUT_METRICS
If set, metrics about the streamlines and their
diameter will be computed after filtering and saved at
the given location (must be .json).
--out_rotation_matrix OUT_ROTATION_MATRIX
If set, the transformation required to align the
"max_voxel_rotated" metric with the coordinate system
will be saved at the given location (must be .mat).
This option requires computing all the metrics, even
if --out_metrics is not provided. If it is provided, metrics are not computed twice.
--min_distance MIN_DISTANCE
If set, streamlines will be filtered more
aggressively so that even if they don't collide,
being below [min_distance] apart (external to their
diameter) will be interpreted as a collision. This
option is the same as filtering with a large diameter
but only saving a small diameter in out_tractogram.
(Value in mm) [0]
--disable_shuffling If set, no shuffling will be performed before
the filtering process. Streamline segments will be
picked in order from the first segment of the first
streamlines to the last segment of the last streamline.
--rng_seed RNG_SEED If set, all random values will be generated
using the specified seed. [0]
-f Force overwriting of the output files.
-v [{DEBUG,INFO,WARNING,ERROR}]
Produces verbose output depending on the provided level.
Default level is warning, default when using -v is info.
Json options:
--indent INDENT Indent for json pretty print.
--sort_keys Sort keys in output json.
2.2.2