freesurferformats (version 1.1.0)

read.dti.trk: Read fiber tracks from Diffusion Toolkit in trk format.

Description

Read fiber tracks from Diffusion Toolkit in trk format.

Usage

read.dti.trk(
  filepath,
  shift_origin = TRUE,
  max_tracks = Inf,
  skip_tracks = 0L,
  bbox = NULL,
  coords = NULL
)

Value

named list, the parsed file data. The naming of the variables follows the spec at http://trackvis.org/docs/?subsect=fileformat. The returned header will contain the field vox2ras (the raw matrix stored in the TRK file, mapping from mm space to RAS) and, if shift_origin is TRUE, the additional field vox2ras_corrected (the computed matrix mapping from voxel indices to voxel center RAS coordinates). It also contains the entry coords_space ('native' or 'ras'), which records the coordinate system the returned tracks are in, so that the result can be passed to write.dti.trk() without losing that information. The tracks are stored in an is.fs.tracts instance: tracks[[i]] returns a list with the entries coords (n x 3 matrix), num_points (integer), scalars (matrix or NULL) and properties (numeric vector or NULL) for the i-th track. Use fs.tracts.lengths(trk$tracks) to get the number of points of each track, and as.list(trk$tracks) to convert to a plain list.

Arguments

filepath

character string, path to file in trk format. Gzip-compressed files are supported as well (the compression is detected from the file content, so a .trk.gz file is read like any other TRK file), which is convenient since tractograms are large and are regularly stored compressed. Note that track files cannot be compressed on the fly for other software: the TrackVis tools and MRtrix do not read compressed track files.

shift_origin

logical, whether to apply the half-voxel origin shift when computing the corrected vox2ras matrix. The TRK format stores a matrix that maps to the voxel corner, not the voxel center (as is the NIfTI convention). Set to TRUE (the default) to compute the corrected vox2ras that maps to voxel centers, as used by TrackVis. Set to FALSE if the file was written by DSI Studio, which does not apply this shift. See the notes for details.

max_tracks

numeric, the maximum number of tracks to read. Use Inf (the default) to read all tracks. This allows reading a subset of a very large tractogram without holding all of it in memory.

skip_tracks

integer, the number of tracks to skip before reading any. Skipped tracks are never held in memory. Note that the count refers to the tracks that a reader returns, and that empty tracks (tracks without any point, which the TRK format allows) are returned as well, e.g., a file with one regular track, then an empty one, yields the empty track for skip_tracks = 1. The only exception is a bbox filter, which drops empty tracks, since no point of them can be inside the box.

bbox

numeric vector of length 6 or NULL. If given, only tracks that have at least one point inside the box are read, the box is given as c(xmin, xmax, ymin, ymax, zmin, zmax).

coords

character string or NULL, the coordinate system of the returned track coordinates. One of 'native' (the coordinates exactly as stored in the file, which for TRK files is usually 'voxelmm' space, in which the coordinates refer to voxel corners) or 'ras' (RAS+ mm space in which a coordinate of (0,0,0) is the center of the first voxel, which is what 'nibabel' and DIPY return by default). If NULL (the default), the coordinates are returned as stored, but a warning is raised when the file stores a transformation that is not the identity, since the coordinates are then not in RAS space and plotting them directly would produce e.g., a mirrored brain. Pass 'native' to silence that warning.

The bbox filter is always interpreted in the same coordinate system as the returned coordinates.

Examples

if (FALSE) {
trk <- read.dti.trk("~/simple.trk")
trk2 <- read.dti.trk("~/standard.trk")
trk3 <- read.dti.trk("~/complex_big_endian.trk")

# Coordinates in RAS+ mm, ready for plotting against an MNI template:
trk_ras <- read.dti.trk("~/simple.trk", coords = "ras")
}