Read fiber tracks from Diffusion Toolkit in trk format.

Usage

read.dti.trk(filepath, shift_origin = TRUE)

Arguments

filepath: character string, path to file in trk format.
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.

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).

Note

The 4x4 matrix stored in TRK files (labeled vox_to_ras in the spec) is actually a transformation from mm space to RAS, not from voxel space to RAS. The TRK format was designed by TrackVis with the assumption that voxels are 1 mm\(^3\), and that coordinates refer to voxel corners rather than centers. To obtain the actual vox2ras matrix (voxel center in RAS), the raw matrix must be combined with a voxel-size scaling and a half-voxel offset correction: vox2ras_corrected = mm2ras %*% mm_correction %*% vox2mm, where vox2mm scales by the inverse voxel size and mm_correction shifts by -0.5 mm. Note that DSI Studio does not apply this half-voxel shift, so you may need to set shift_origin=FALSE for DSI Studio files.

Examples

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