scilpy.tracking package

scilpy.tracking.fibertube_utils module

scilpy.tracking.fibertube_utils.create_perpendicular(v: ndarray)

Generates a vector perpendicular to v.

Source: https://math.stackexchange.com/questions/133177/finding-a-unit-

vector-perpendicular-to-another-vector

Answer by Ahmed Fasih

Parameters:

v (ndarray) – Vector from which a perpendicular vector will be generated.

Returns:

vp – Vector perpendicular to v.

Return type:

ndarray

scilpy.tracking.fibertube_utils.dist_point_segment(p0, p1, q)

Calculates the shortest distance between a 3D point q and a segment p0-p1.

Parameters:

• p0 (ndarray) – Point forming the first end of the segment.

• p1 (ndarray) – Point forming the second end of the segment.

• q (ndarray) – Point coordinates.

Returns:

• distance (float) – Shortest distance between the two segments

• v (ndarray) – Vector representing the distance between the two segments. v = Ps - q and |v| = distance

• Ps (ndarray) – Point coordinates on segment P that is closest to point q

scilpy.tracking.fibertube_utils.dist_segment_segment(P0, P1, Q0, Q1)

Calculates the shortest distance between two 3D segments P0-P1 and Q0-Q1.

Parameters:

• P0 (ndarray) – Point forming the first end of the P segment.

• P1 (ndarray) – Point forming the second end of the P segment.

• Q0 (ndarray) – Point forming the first end of the Q segment.

• Q1 (ndarray) – Point forming the second end of the Q segment.

Returns:

• distance (float) – Shortest distance between the two segments

• v (ndarray) – Vector representing the distance between the two segments. v = Ps - Qt and |v| = distance

• Ps (ndarray) – Point coordinates on segment P that is closest to segment Q

• Qt (ndarray) – Point coordinates on segment Q that is closest to segment P

• This function is a python version of the following code

• https (//www.geometrictools.com/GTE/Mathematics/DistSegmentSegment.h)

• Scientific source

• https (//www.geometrictools.com/Documentation/DistanceLine3Line3.pdf)

scilpy.tracking.fibertube_utils.point_in_cylinder(pt1, pt2, r, q)

scilpy.tracking.fibertube_utils.rotation_between_vectors_matrix(vec1, vec2)

Produces a rotation matrix that aligns a 3D vector ‘vec1’ with another 3D vector ‘vec2’. Numba compatible.

https://math.stackexchange.com/questions/180418/calculate- rotation-matrix-to-align-vector-a-to-vector-b-in-3d

Parameters:

• vec1 (ndarray) – Vector to be rotated

• vec2 (ndarray) – Targeted orientation

Returns:

rotation_matrix – A transform matrix (3x3) which when applied to vec1, aligns it with vec2.

Return type:

ndarray

scilpy.tracking.fibertube_utils.sample_cylinder(pt1, pt2, radius: float, sample_count: int, random_generator: Generator)

Samples a cylinder uniformly given its dimensions and the amount of samples.

Parameters:

• pt1 (ndarray) – First extremity of the cylinder axis

• pt2 (ndarray) – Second extremity of the cylinder axis

• radius (float) – Radius of the cylinder.

• sample_count (int) – Amount of samples to be produced.

• rand_gen (numpy random generator) – Numpy random generator used for producing samples within the sphere.

Returns:

samples – Array containing the coordinates of each sample.

Return type:

list

scilpy.tracking.fibertube_utils.sample_sphere(center, radius: float, amount: int, rand_gen: Generator)

Samples a sphere uniformly given its dimensions and the amount of samples.

Parameters:

• center (ndarray) – Center coordinates of the sphere. Can be [0, 0, 0] if only the relative displacement interests you.

• radius (float) – Radius of the sphere.

• amount (int) – Amount of samples to be produced.

• rand_gen (numpy random generator) – Numpy random generator used for producing samples within the sphere.

Returns:

samples – Array containing the coordinates of each sample.

Return type:

list

scilpy.tracking.fibertube_utils.sphere_cylinder_intersection(sph_p, sph_r: float, cyl_p1, cyl_p2, cyl_r: float, sample_count: int, shape_to_sample: Literal['sphere', 'cylinder'], random_generator: Generator)

Estimates the volume of intersection between a cylinder and a sphere by sampling the cylinder. Most efficient when the cylinder is smaller than the sphere.

Parameters:

• sph_p (ndarray) – Center coordinate of the sphere.

• sph_r (float) – Radius of the sphere.

• cyl_p1 (ndarray) – First point of the cylinder’s center segment.

• cyl_p2 (ndarray) – Second point of the cylinder’s center segment.

• cyl_r (float) – Radius of the cylinder.

• sample_count (int) – Amount of samples to use for the estimation.

• shape_to_sample ('sphere' | 'cylinder') – Shape to sample. For best accuracy, this should be the smallest shape.

• random_generator (numpy random generator) – Numpy random generator used for producing sample coordinates.

Returns:

• inter_volume (float) – Approximate volume of the sphere-cylinder intersection.

• is_estimated (boolean) – Indicates whether or not the resulting volume has been estimated using samples instead of an analytical solution.

scilpy.tracking.fibertube_utils.streamlines_to_segments(streamlines, streamlines_length=None, verbose=False)

Separates all streamlines of a tractogram into segments that connect each position. Then, flattens the resulting 2D array and returns it

Parameters:

• streamlines (list) – Streamlines to segment. This function is compatible with streamlines as a fixed array with a padding value, as long as the [streamlines_length] parameter is given. Padding will be kept in the result value.

• streamlines_length (list) – Length of each streamline. Only necessary if streamlines are given as a fixed array.

• verbose (bool) – Wether the function should be verbose.

Returns:

• centers (ndarray[float]) – A flattened array of all the tractogram’s segment centers

• indices (ndarray[Tuple[int, int]]) – A flattened array of all the tractogram’s segment indices

• max_length (float) – Length of the longest segment of the whole tractogram

scilpy.tracking.propagator module

class scilpy.tracking.propagator.AbstractPropagator(datavolume, step_size, rk_order, space, origin)

Bases: object

Abstract class for propagator object. “Propagation” means continuing the streamline a step further. The propagator is thus responsible for sampling the next direction at current step through Runge-Kutta integration (whereas the tracker using this propagator will be responsible for the processing parameters, number of streamlines, stopping criteria, etc.).

Propagation depends on the type of data (ex, DTI, fODF) and the way to get a direction from it (ex, det, prob).

finalize_streamline(last_pos, v_in)

Return the last position of the streamline.

Parameters:

• last_pos (ndarray (3,)) – Last propagated position. Important, position must be in the same space and origin as self.space, self.origin!

• v_in (TrackingDirection) – Last propagated direction.

Returns:

final_pos – Position of the final point of the streamline. Return None, or last_pos, if no last step is wished.

Return type:

ndarray (3,)

prepare_backward(line, forward_dir)

Called at the beginning of backward tracking, in case we need to reset some parameters

Parameters:

• line (List) – Result from the forward tracking, reversed.

• forward_dir (ndarray (3,)) – v_in chosen at the forward step.

Returns:

v_in – Last direction of the streamline. If the streamline contains only the seeding point (forward tracking failed), simply inverse the forward direction.

Return type:

ndarray (3,)

prepare_forward(seeding_pos, random_generator)

Prepare information necessary at the first point of the streamline for forward propagation: v_in and any other information necessary for the self.propagate method.

Parameters:

• seeding_pos (tuple(x,y,z)) – The seeding position. Important, position must be in the same space and origin as self.space, self.origin!

• random_generator (numpy Generator.)

Returns:

tracking_info – Any tracking information necessary for the propagation. Return PropagationStatus.ERROR if no good tracking direction can be set at current seeding position.

Return type:

Any

propagate(line, v_in)

Given the current position and direction, computes the next position and direction using Runge-Kutta integration method. If no valid tracking direction is available, v_in is chosen.

Parameters:

• line (list[ndarrray (3,)]) – Current position.

• v_in (ndarray (3,) or TrackingDirection) – Previous tracking direction.

Returns:

• new_pos (ndarray (3,)) – The new segment position, expressed in propagator’s space and origin.

• new_dir (ndarray (3,) or TrackingDirection) – The new segment direction.

• is_direction_valid (bool) – True if new_dir is valid.

reset_data(new_data=None)

Reset data before starting a new process. In current implementation, we reset the internal data to None before starting a multiprocess, then load it back when process has started.

Parameters:

new_data (Any) – Will replace self.datavolume.data.

class scilpy.tracking.propagator.FibertubePropagator(datavolume: FibertubeDataVolume, step_size, rk_order, theta, space, origin)

Bases: AbstractPropagator

Simplified propagator for using fibertube data. It is probabilistic and uses the volume of intersection between fibertube segments and the blurring sphere as a random distribution for picking a segment. This segment is then used as the propagation direction.

This propagator expects an array of possible directions and their random distribution. If using an ftODF (the same directions, but expressed as a spherical function), the ODFPropagator should be used.

finalize_streamline(last_pos, v_in)

Return the last position of the streamline.

Parameters:

• last_pos (ndarray (3,)) – Last propagated position. Important, position must be in the same space and origin as self.space, self.origin!

• v_in (TrackingDirection) – Last propagated direction.

Returns:

final_pos – Position of the final point of the streamline. Return None, or last_pos, if no last step is wished.

Return type:

ndarray (3,)

prepare_backward(line, forward_dir)

Called at the beginning of backward tracking, in case we need to reset some parameters

Parameters:

• line (List) – Result from the forward tracking, reversed.

• forward_dir (ndarray (3,)) – v_in chosen at the forward step.

Returns:

v_in – Last direction of the streamline. If the streamline contains only the seeding point (forward tracking failed), simply inverse the forward direction.

Return type:

ndarray (3,)

prepare_forward(seeding_pos, random_generator)

Prepare information necessary at the first point of the streamline for forward propagation: v_in and any other information necessary for the self.propagate method.

Parameters:

• seeding_pos (tuple(x,y,z)) – The seeding position. Important, position must be in the same space and origin as self.space, self.origin!

• random_generator (numpy Generator.)

Returns:

tracking_info – Any tracking information necessary for the propagation. Return PropagationStatus.ERROR if no good tracking direction can be set at current seeding position.

Return type:

Any

propagate(line, v_in)

Given the current position and direction, computes the next position and direction using Runge-Kutta integration method. If no valid tracking direction is available, v_in is chosen.

Parameters:

• line (list[ndarrray (3,)]) – Current position.

• v_in (ndarray (3,) or TrackingDirection) – Previous tracking direction.

Returns:

• new_pos (ndarray (3,)) – The new segment position, expressed in propagator’s space and origin.

• new_dir (ndarray (3,) or TrackingDirection) – The new segment direction.

• is_direction_valid (bool) – True if new_dir is valid.

reset_data(new_data=None)

Reset data before starting a new process. In current implementation, we reset the internal data to None before starting a multiprocess, then load it back when process has started.

Parameters:

new_data (Any) – Will replace self.datavolume.data.

class scilpy.tracking.propagator.ODFPropagator(datavolume, step_size, rk_order, algo, basis, sf_threshold, sf_threshold_init, theta, dipy_sphere='symmetric724', sub_sphere=0, min_separation_angle=0.19634954084936207, space=Space.VOX, origin=Origin.NIFTI, is_legacy=True)

Bases: PropagatorOnSphere

Propagator on ODFs/fODFs. Algo can be det or prob.

prepare_forward(seeding_pos, random_generator)

Prepare information necessary at the first point of the streamline for forward propagation: v_in and any other information necessary for the self.propagate method.

About v_in, it is used for two things:

• To sample the next direction based on _sample_next_direction method.

  Ex, with fODF, it defines a cone theta of accepable directions.

• If no valid next dir are found, continue straight.

Parameters:

• seeding_pos (tuple(x,y,z)) – The seeding position. Important, position must be in the same space and origin as self.space, self.origin!

• random_generator (numpy Generator)

Returns:

v_in – The “fake” previous direction at first step. Could be None if your propagator can propagate without knowledge of previous direction. Return PropagationStatus.Error if no good tracking direction can be set at current seeding position.

Return type:

TrackingDirection

class scilpy.tracking.propagator.PropagationStatus(*values)

Bases: Enum

ERROR = 1

class scilpy.tracking.propagator.PropagatorOnSphere(datavolume, step_size, rk_order, dipy_sphere, sub_sphere, space, origin)

Bases: AbstractPropagator

prepare_backward(line, forward_dir)

Called at the beginning of backward tracking, in case we need to reset some parameters

Parameters:

• line (List) – Result from the forward tracking, reversed.

• forward_dir (ndarray (3,)) – v_in chosen at the forward step.

Returns:

v_in – Last direction of the streamline, of if it contains only the seeding point (forward tracking failed), simply inverse the forward direction.

Return type:

ndarray (3,)

scilpy.tracking.rap module

class scilpy.tracking.rap.RAP(rap_volume, propagator, max_nbr_pts)

Bases: object

is_in_rap_region(curr_pos, space, origin)

rap_multistep_propagate(line, prev_direction)

All child classes must implement this method. Must receive and return the parameters as defined here:

Params

line: list

The beginning of the streamline

returns:

• line (list) – The streamline extended with RAP in the RAP neighborhood.

• prev_direction (tuple) – The last direction (x, y, z).

• is_line_valid (bool) – If the line generated with RAP is valid.

class scilpy.tracking.rap.RAPContinue(rap_volume, propagator, max_nbr_pts, step_size)

Bases: RAP

Dummy RAP class for tests. Goes straight

rap_multistep_propagate(line, prev_direction)

All child classes must implement this method. Must receive and return the parameters as defined here:

Params

line: list

The beginning of the streamline

returns:

• line (list) – The streamline extended with RAP in the RAP neighborhood.

• prev_direction (tuple) – The last direction (x, y, z).

• is_line_valid (bool) – If the line generated with RAP is valid.

class scilpy.tracking.rap.RAPGraph(mask_rap, propagator, max_nbr_pts, neighboorhood_size)

Bases: RAP

rap_multistep_propagate(line, prev_direction)

All child classes must implement this method. Must receive and return the parameters as defined here:

Params

line: list

The beginning of the streamline

returns:

• line (list) – The streamline extended with RAP in the RAP neighborhood.

• prev_direction (tuple) – The last direction (x, y, z).

• is_line_valid (bool) – If the line generated with RAP is valid.

class scilpy.tracking.rap.RAPSwitch(rap_volume, propagators: dict, max_nbr_pts)

Bases: RAP

RAP class that switches tracking parameters when inside the RAP mask/label.

rap_multistep_propagate(line, prev_direction)

Propagate within the RAP region using modified parameters.

Parameters:

• line (list) – The current streamline.

• prev_direction (np.ndarray) – The previous tracking direction.

Returns:

• line (list) – The extended streamline.

• prev_direction (np.ndarray) – The last direction.

• is_line_valid (bool) – Whether the line is valid.

scilpy.tracking.seed module

class scilpy.tracking.seed.CustomSeedsDispenser(custom_seeds, space=Space.VOX, origin=Origin.NIFTI)

Bases: SeedGenerator

Adaptation of the scilpy.tracking.seed.SeedGenerator interface for using already generated, custom seeds.

get_next_n_pos(random_generator, shuffled_indices, which_seed_start, n)

Generate the next n seed positions. Intended for GPU usage. Equivalent to: >>> for s in range(which_seed_start, which_seed_start + nb_seeds): >>> self.get_next_pos(…, s)

See description of get_next_pos for more information.

To be used with self.n_repeats, we suppose that sequential get_next_n_pos calls are used with sequential values of which_seed_start (with steps of nb_seeds).

Parameters:

• random_generator (numpy random generator) – Initialized numpy number generator.

• shuffled_indices (np.array) – Indices of current seeding map.

• which_seed_start (int) – First seed numbers to be processed. (which_seed_start // self.n_repeats corresponds to the index of the chosen seed in the flattened seeding mask).

• n (int) – Number of seeds to get.

Returns:

seeds – Positions of next seeds expressed seed_generator’s space and origin.

Return type:

List[List]

get_next_pos(random_generator: Generator, shuffled_indices, which_seed)

Generate the next seed position (Space=voxmm, origin=corner). See self.init()_generator to get the generator and shuffled_indices.

To be used with self.n_repeats, we suppose that sequential get_next_pos calls are used with sequentials values of which_seed.

Parameters:

• random_generator (numpy random generator) – Initialized numpy number generator.

• shuffled_indices (np.array) – Indices of current seeding map.

• which_seed (int) – Seed number to be processed. (which_seed // self.n_repeats corresponds to the index of the chosen seed in the flattened seeding mask).

Returns:

seed_pos – Position of next seed expressed in mm.

Return type:

tuple

init_generator(rng_seed, numbers_to_skip)

Does not do anything. Simulates SeedGenerator’s implementation for retro-compatibility.

Parameters:

• rng_seed (int) – The “seed” for the random generator.

• numbers_to_skip (int) – Number of seeds (i.e. voxels) to skip. Useful if you want to continue sampling from the same generator as in a first experiment (with a fixed rng_seed).

Returns:

• random_generator (numpy random generator) – Initialized numpy number generator.

• indices (ndarray) – Empty list for interface retro-compatibility

class scilpy.tracking.seed.FibertubeSeedGenerator(centerlines, diameters, nb_seeds_per_fibertube, local_seeding: Literal['center', 'random'])

Bases: SeedGenerator

Adaptation of the scilpy.tracking.seed.SeedGenerator interface for fibertube tracking. Generates a given number of seed within the first segment of a given number of fibertubes.

get_next_n_pos(random_generator, shuffled_indices, which_seed_start, n)

Generate the next n seed positions. Intended for GPU usage. Equivalent to: >>> for s in range(which_seed_start, which_seed_start + nb_seeds): >>> self.get_next_pos(…, s)

See description of get_next_pos for more information.

To be used with self.n_repeats, we suppose that sequential get_next_n_pos calls are used with sequential values of which_seed_start (with steps of nb_seeds).

Parameters:

• random_generator (numpy random generator) – Initialized numpy number generator.

• shuffled_indices (np.array) – Indices of current seeding map.

• which_seed_start (int) – First seed numbers to be processed. (which_seed_start // self.n_repeats corresponds to the index of the chosen seed in the flattened seeding mask).

• n (int) – Number of seeds to get.

Returns:

seeds – Positions of next seeds expressed seed_generator’s space and origin.

Return type:

List[List]

get_next_pos(random_generator: Generator, shuffled_indices, which_seed)

Generate the next seed position (Space=voxmm, origin=corner). See self.init()_generator to get the generator and shuffled_indices.

To be used with self.n_repeats, we suppose that sequential get_next_pos calls are used with sequentials values of which_seed.

Parameters:

• random_generator (numpy random generator) – Initialized numpy number generator.

• shuffled_indices (np.array) – Indices of current seeding map.

• which_seed (int) – Seed number to be processed. (which_seed // self.n_repeats corresponds to the index of the chosen seed in the flattened seeding mask).

Returns:

seed_pos – Position of next seed expressed in mm.

Return type:

tuple

init_generator(rng_seed, numbers_to_skip)

Initialize a numpy number generator according to user’s parameters. Returns also the shuffled index of all fibertubes.

The values are not stored in this classed, but are returned to the user, who should add them as arguments in the methods self.get_next_pos() self.get_next_n_pos() The use of this is that with multiprocessing, each process may have its own generator, with less risk of using the wrong one when they are managed by the user.

Parameters:

• rng_seed (int) – The “seed” for the random generator.

• numbers_to_skip (int) – Number of seeds (i.e. voxels) to skip. Useful if you want to continue sampling from the same generator as in a first experiment (with a fixed rng_seed).

Returns:

• random_generator (numpy random generator) – Initialized numpy number generator.

• indices (ndarray) – Shuffled indices of current seeding map, shuffled with current generator.

class scilpy.tracking.seed.SeedGenerator(data, voxres, space=Space.VOX, origin=Origin.NIFTI, n_repeats=1)

Bases: object

Class to get seeding positions.

Generated seeds are in voxmm space, origin=corner. Ex: a seed sampled exactly at voxel i,j,k = (0,1,2), with resolution 3x3x3mm will have coordinates x,y,z = (0, 3, 6).

Using get_next_pos, seeds are placed randomly within the voxel. In the same example as above, seed sampled in voxel i,j,k = (0,1,2) will be somewhere in the range x = [0, 3], y = [3, 6], z = [6, 9].

get_next_n_pos(random_generator, shuffled_indices, which_seed_start, n)

Generate the next n seed positions. Intended for GPU usage. Equivalent to: >>> for s in range(which_seed_start, which_seed_start + nb_seeds): >>> self.get_next_pos(…, s)

See description of get_next_pos for more information.

To be used with self.n_repeats, we suppose that sequential get_next_n_pos calls are used with sequential values of which_seed_start (with steps of nb_seeds).

Parameters:

• random_generator (numpy random generator) – Initialized numpy number generator.

• shuffled_indices (np.array) – Indices of current seeding map.

• which_seed_start (int) – First seed numbers to be processed. (which_seed_start // self.n_repeats corresponds to the index of the chosen seed in the flattened seeding mask).

• n (int) – Number of seeds to get.

Returns:

seeds – Positions of next seeds expressed seed_generator’s space and origin.

Return type:

List[List]

get_next_pos(random_generator, shuffled_indices, which_seed)

Generate the next seed position (Space=voxmm, origin=corner). See self.init()_generator to get the generator and shuffled_indices.

To be used with self.n_repeats, we suppose that sequential get_next_pos calls are used with sequentials values of which_seed.

Parameters:

• random_generator (numpy random generator) – Initialized numpy number generator.

• shuffled_indices (np.array) – Indices of current seeding map.

• which_seed (int) – Seed number to be processed. (which_seed // self.n_repeats corresponds to the index of the chosen seed in the flattened seeding mask).

Returns:

seed_pos – Position of next seed expressed in mm.

Return type:

tuple

init_generator(rng_seed, numbers_to_skip)

Initialize a numpy number generator according to user’s parameters. Returns also the suffled index of all voxels.

The values are not stored in this classed, but are returned to the user, who should add them as arguments in the methods self.get_next_pos() self.get_next_n_pos() The use of this is that with multiprocessing, each process may have its own generator, with less risk of using the wrong one when they are managed by the user.

Parameters:

• rng_seed (int) – The “seed” for the random generator.

• numbers_to_skip (int) – Number of seeds (i.e. voxels) to skip. Useful if you want to continue sampling from the same generator as in a first experiment (with a fixed rng_seed).

Returns:

• random_generator (numpy random generator) – Initialized numpy number generator.

• indices (ndarray) – Shuffled indices of current seeding map, shuffled with current generator.

scilpy.tracking.tracker module

class scilpy.tracking.tracker.GPUTracker(sh, mask, seeds, step_size, max_nbr_pts, theta=20.0, sf_threshold=0.1, sh_interp='trilinear', sh_basis='descoteaux07', is_legacy=True, batch_size=100000, forward_only=False, rng_seed=None, sphere=None, algo='prob')

Bases: object

Perform local tracking on a ODF field inside a binary mask. The tracking is executed on the GPU using the OpenCL API. Tracking is performed in voxel space with origin corner.

Streamlines are interrupted as soon as they reach maximum length and returned even if they end inside the tracking mask. The ODF image is interpolated using nearest neighbor interpolation. No backward tracking is performed.

Parameters:

• sh (ndarray) – Spherical harmonics volume. Ex: ODF or fODF.

• mask (ndarray) – Tracking mask. Tracking stops outside the mask.

• seeds (ndarray (n_seeds, 3)) – Seed positions in voxel space with origin center.

• step_size (float) – Step size in voxel space.

• max_nbr_pts (int) – Maximum length of a streamline in voxel space.

• theta (float or list of float, optional) – Maximum angle (degrees) between 2 steps. If a list, a theta is randomly drawn from the list for each streamline.

• sh_basis (str, optional) – Spherical harmonics basis.

• is_legacy (bool, optional) – Whether or not the SH basis is in its legacy form.

• batch_size (int, optional) – Approximate size of GPU batches.

• forward_only (bool, optional) – If True, only forward tracking is performed.

• rng_seed (int, optional) – Seed for GPU random number generator. Reproducible across GPU runs, but not guaranteed to match CPU tracker results for the same seed.

• sphere (int, optional) – Sphere to use for the tracking.

• algo ({'prob', 'det'}, optional) – GPU tracking mode. prob samples directions from the SF and det follows the maximum SF direction.

class scilpy.tracking.tracker.Tracker(propagator: AbstractPropagator, mask: DataVolume, seed_generator: SeedGenerator, nbr_seeds, min_nbr_pts, max_nbr_pts, max_invalid_dirs, compression_th=0.1, nbr_processes=1, save_seeds=False, mmap_mode: str | None = None, rng_seed=1234, track_forward_only=False, skip=0, verbose=False, min_iter=100, append_last_point=True, rap=None)

Bases: object

save_rap_entry_exit_mask(output_path, reference_img)

Save RAP entry/exit coordinates as a nifti mask. Entry points have value 1, exit points have value 2.

Parameters:

• output_path (str) – Path to save the nifti mask file.

• reference_img (nibabel.Nifti1Image) – Reference image to get affine and shape for the output mask.

track()

Generate a set of streamline from seed, mask and odf files.

Returns:

• streamlines (list of numpy.array) – List of streamlines, represented as an array of positions.

• seeds (list of numpy.array) – List of seeding positions, one 3-dimensional position per streamline.

scilpy.tracking.utils module

class scilpy.tracking.utils.TrackingDirection(cartesian, index=None)

Bases: list

Tracking direction use as 3D cartesian direction (list(x,y,z)) and has an index to work with discrete sphere.

scilpy.tracking.utils.add_mandatory_options_tracking(p, fodf_optional=False)

Args that are required in both scil_tracking_local and scil_tracking_local_dev scripts.

scilpy.tracking.utils.add_out_options(p)

Options that are available in both scil_tracking_local and scil_tracking_local_dev scripts.

scilpy.tracking.utils.add_seeding_options(p)

Options that are available in both scil_tracking_local and scil_tracking_local_dev scripts.

scilpy.tracking.utils.add_tracking_options(p)

Options that are available in both scil_tracking_local and scil_tracking_local_dev scripts.

scilpy.tracking.utils.add_tracking_ptt_options(p)

scilpy.tracking.utils.get_direction_getter(in_img, algo, sphere, sub_sphere, theta, sh_basis, voxel_size, sf_threshold, sh_to_pmf, probe_length, probe_radius, probe_quality, probe_count, support_exponent, is_legacy=True)

Return the direction getter object.

Parameters:

• in_img (str) – Path to the input odf file.

• algo (str) – Algorithm to use for tracking. Can be ‘det’, ‘prob’, ‘ptt’ or ‘eudx’.

• sphere (str) – Name of the sphere to use for tracking.

• sub_sphere (int) – Number of subdivisions to use for the sphere.

• theta (float) – Angle threshold for tracking.

• sh_basis (str) – Name of the sh basis to use for tracking.

• voxel_size (float) – Voxel size of the input data.

• sf_threshold (float) – Spherical function-amplitude threshold for tracking.

• sh_to_pmf (bool) – Map sherical harmonics to spherical function (pmf) before tracking (faster, requires more memory).

• probe_length (float) – The length of the probes. Shorter probe_length yields more dispersed fibers.

• probe_radius (float) – The radius of the probe. A large probe_radius helps mitigate noise in the pmf but it might make it harder to sample thin and intricate connections, also the boundary of fiber bundles might be eroded.

• probe_quality (int) – The quality of the probe. This parameter sets the number of segments to split the cylinder along the length of the probe (minimum=2).

• probe_count (int) – The number of probes. This parameter sets the number of parallel lines used to model the cylinder (minimum=1).

• support_exponent (float) – Data support exponent, used for rejection sampling.

• is_legacy (bool, optional) – Whether or not the SH basis is in its legacy form.

Returns:

dg – The direction getter object.

Return type:

dipy.direction.DirectionGetter

scilpy.tracking.utils.get_theta(requested_theta, tracking_type)

scilpy.tracking.utils.sample_distribution(dist, random_generator: Generator)

Parameters:

• dist (numpy.array) – The empirical distribution to sample from.

• random_generator (numpy Generator)

Returns:

ind – The index of the sampled element.

Return type:

int

scilpy.tracking.utils.save_tractogram(streamlines_generator, tracts_format, ref_img, total_nb_seeds, out_tractogram, min_length, max_length, compress, save_seeds, verbose)

Save the streamlines on-the-fly using a generator. Tracts are filtered according to their length and compressed if requested. Seeds are saved if requested. The tractogram is shifted and scaled according to the file format.

Parameters:

• streamlines_generator (generator) – Streamlines generator.

• tracts_format (TrkFile or TckFile) – Tractogram format.

• ref_img (nibabel.Nifti1Image) – Image used as reference.

• total_nb_seeds (int) – Total number of seeds.

• out_tractogram (str) – Output tractogram filename.

• min_length (float) – Minimum length of a streamline in mm.

• max_length (float) – Maximum length of a streamline in mm.

• compress (float) – Distance threshold for compressing streamlines in mm.

• save_seeds (bool) – If True, save the seeds used for the tracking in the data_per_streamline property.

• verbose (bool) – If True, display progression bar.

scilpy.tracking.utils.tqdm_if_verbose(generator: Iterable, verbose: bool, *args, **kwargs)

scilpy.tracking.utils.verify_seed_options(parser, args)

scilpy.tracking.utils.verify_streamline_length_options(parser, args)