dipy logo

Site Navigation

NIPY Community

Previous topic

dipy.tracking.utils

Next topic

dipy viz

dipy.tracking.vox2track

This module contains the parts of dipy.tracking.utils that need to be implemented in cython.

dipy.tracking.vox2track.streamline_mapping()

Creates a mapping from voxel indices to streamlines.

Returns a dictionary where each key is a 3d voxel index and the associated value is a list of the streamlines that pass through that voxel.

Parameters :

streamlines : sequence

A sequence of streamlines.

voxel_size : array_like (3,), optional

The size of the voxels in the image volume. This is ignored if affine is set.

affine : array_like (4, 4), optional

The mapping from voxel coordinates to streamline coordinates. If neither affine or voxel_size is set, the streamline values are assumed to be in voxel coordinates. IE [0, 0, 0] is the center of the first voxel and the voxel size is [1, 1, 1].

mapping_as_streamlines : bool, optional, False by default

If True voxel indices map to lists of streamline objects. Otherwise voxel indices map to lists of integers.

Returns :

mapping : defaultdict(list)

A mapping from voxel indices to the streamlines that pass through that voxel.

Examples

>>> streamlines = [np.array([[0., 0., 0.],
...                          [1., 1., 1.],
...                          [2., 3., 4.]]),
...                np.array([[0., 0., 0.],
...                          [1., 2., 3.]])]
>>> mapping = streamline_mapping(streamlines, (1, 1, 1))
>>> mapping[0, 0, 0]
[0, 1]
>>> mapping[1, 1, 1]
[0]
>>> mapping[1, 2, 3]
[1]
>>> mapping.get((3, 2, 1), 'no streamlines')
'no streamlines'
>>> mapping = streamline_mapping(streamlines, (1, 1, 1),
...                              mapping_as_streamlines=True)
>>> mapping[1, 2, 3][0] is streamlines[1]
True
dipy.tracking.vox2track.track_counts()

Counts of points in tracks that pass through voxels in volume

We find whether a point passed through a track by rounding the mm point values to voxels. For a track that passes through a voxel more than once, we only record counts and elements for the first point in the line that enters the voxel.

Parameters :

tracks : sequence

sequence of T tracks. One track is an ndarray of shape (N, 3), where N is the number of points in that track, and tracks[t][n] is the n-th point in the t-th track. Points are of form x, y, z in voxel mm coordinates. That is, if i, j, k is the possibly non-integer voxel coordinate of the track point, and vox_sizes are 3 floats giving voxel sizes of dimensions 0, 1, 2 respectively, then the voxel mm coordinates x, y, z are simply i * vox_sizes[0], j * vox_sizes[1], k * vox_sizes[2]. This convention derives from trackviz. To pass in tracks as voxel coordinates, just pass vox_sizes=(1, 1, 1) (see below).

vol_dims : sequence length 3

volume dimensions in voxels, x, y, z.

vox_sizes : optional, sequence length 3

voxel sizes in mm. Default is (1,1,1)

return_elements : {True, False}, optional

If True, also return object array with one list per voxel giving track indices and point indices passing through the voxel (see below)

Returns :

tcs : ndarray shape vol_dim

An array where entry tcs[x, y, z] is the number of tracks that passed through voxel at voxel coordinate x, y, z

tes : ndarray dtype np.object, shape vol_dim

If return_elements is True, we also return an object array with one object per voxel. The objects at each voxel are a list of integers, where the integers are the indices of the track that passed through the voxel.

Examples

Imagine you have a volume (voxel) space of dimension (10,20,30). Imagine you had voxel coordinate tracks in vs. To just fill an array with the counts of how many tracks pass through each voxel:

>>> vox_track0 = np.array([[0,0,0],[1.1,2.2,3.3],[2.2,4.4,6.6]])
>>> vox_track1 = np.array([[0,0,0],[0,0,1],[0,0,2]])
>>> vs = (vox_track0, vox_track1)
>>> vox_dim = (10, 20, 30) # original voxel array size
>>> tcs=track_counts(vs, vox_dim, (1,1,1), False)
>>> tcs.shape
(10, 20, 30)
>>> tcs[0,0,0:4]
array([2, 1, 1, 0])
>>> tcs[1,2,3], tcs[2,4,7]
(1, 1)

You can also use the routine to count into larger-than-voxel boxes. To do this, increase the voxel size and decrease the vox_dim accordingly:

>>> tcs=track_counts(vs, (10/2., 20/2., 30/2.), (2,2,2), False)
>>> tcs.shape
(5, 10, 15)
>>> tcs[1,1,2], tcs[1,2,3]
(1, 1)