NiBabel

Access a cacophony of neuro-imaging file formats

Previous topic

nibabel.trackvis.read

Next topic

nibabel.trackvis.TrackvisFile

Reggie -- the one

nibabel.trackvis.write

nibabel.trackvis.write(fileobj, streamlines, hdr_mapping=None, endianness=None, points_space=None)

Write header and streamlines to trackvis file fileobj

The parameters from the streamlines override conflicting parameters in the hdr_mapping information. In particular, the number of streamlines, the number of scalars, and the number of properties are written according to streamlines rather than hdr_mapping.

Parameters :

fileobj : filename or file-like

If filename, open file as ‘wb’, otherwise fileobj should be an open file-like object, with a write method.

streamlines : iterable

iterable returning 3 element sequences with elements:

  1. points : ndarray shape (N,3) where N is the number of points
  2. scalars : None or ndarray shape (N, M) where M is the number of scalars per point
  3. properties : None or ndarray shape (P,) where P is the number of properties

If streamlines has a len (for example, it is a list or a tuple), then we can write the number of streamlines into the header. Otherwise we write 0 for the number of streamlines (a valid trackvis header) and write streamlines into the file until the iterable is exhausted. M - the number of scalars - has to be the same for each streamline in streamlines. Similarly for P. See points_space and Notes for more detail on the coordinate system for points above.

hdr_mapping : None, ndarray or mapping, optional

Information for filling header fields. Can be something dict-like (implementing items) or a structured numpy array

endianness : {None, ‘<’, ‘>’}, optional

Endianness of file to be written. ‘<’ is little-endian, ‘>’ is big-endian. None (the default) is to use the endianness of the streamlines data.

points_space : {None, ‘voxel’, ‘rasmm’}, optional

The coordinates in which the points in the input streamlines are expressed. If None, then assume the points are as you want them (probably trackviz voxmm space - see Notes). If ‘voxel’, the points are in voxel space, and we will transform them to trackviz voxmm space. If ‘rasmm’ the points are in RAS mm space (real space). We transform them to trackvis voxmm space. If ‘voxel’ or ‘rasmm’ we insist that the voxel sizes and ordering are set to non-default values. If ‘rasmm’ we also check if the affine is set and matches the voxel sizes

Returns :

None :

Notes

Trackvis (the application) expects the points in the streamlines be in what we call trackviz voxmm coordinates. If we have a point (x, y, z) in voxmm coordinates, and voxel_size has the voxel sizes for each of the 3 dimensions, then x, y, z refer to mm in voxel space. Thus if i, j, k is a point in voxel coordinates, then x = i * voxel_size[0]; y = j * voxel_size[1]; z = k * voxel_size[2]. The spatial direction of x, y and z are defined with the “voxel_order” field. For example, if the original image had RAS voxel ordering then “voxel_order” would be “RAS”. RAS here refers to the spatial direction of the voxel axes: “R” means that moving along first voxel axis moves from left to right in space, “A” -> second axis goes from posterior to anterior, “S” -> inferior to superior. If “voxel_order” is empty we assume “LPS”.

This information comes from some helpful replies on the trackviz forum about interpreting point coordiantes

Examples

>>> from StringIO import StringIO #23dt : BytesIO
>>> file_obj = StringIO() #23dt : BytesIO
>>> pts0 = np.random.uniform(size=(10,3))
>>> pts1 = np.random.uniform(size=(10,3))
>>> streamlines = ([(pts0, None, None), (pts1, None, None)])
>>> write(file_obj, streamlines)
>>> _ = file_obj.seek(0) # returns 0 in python 3
>>> streams, hdr = read(file_obj)
>>> len(streams)
2

If there are too many streamlines to fit in memory, you can pass an iterable thing instead of a list

>>> file_obj = StringIO() #23dt : BytesIO
>>> def gen():
...     yield (pts0, None, None)
...     yield (pts0, None, None)
>>> write(file_obj, gen())
>>> _ = file_obj.seek(0)
>>> streams, hdr = read(file_obj)
>>> len(streams)
2