## Image formats (.mif / .mih)

These MRtrix-specific image formats are closely related. They consist of a text header, with data stored in binary format, either within the same file (.mif) or as one or more separate files (.mih). In both cases, the header structure is the same, as detailed below. These file formats were devised to address a number of limitations inherent in currently available formats. In particular:

- simplicity: as detailed below, the header format is deliberately kept very simple and human-readable, making it easy to debug and edit manually if needed.
- extendability: any information can be stored in the header, and will simply be ignored by the application if not recognised.
- arbitrary data organisation: voxel values can be stored in any order, making it simple to ensure for example that all FOD coefficients for a given voxel are stored contiguously on file.

Note that MRtrix now includes MatLab® functions to read and write MRtrix image files, and to load MRtrix tracks files. These are located in the `matlab` subfolder.

### Header structure

The header is the first (and possibly only) data stored in the file, as ASCII-encoded text (although other encodings such as UTF8 may work equally well). Lines should be separated by unix-style newlines (line-feed, '\n', ASCII 0x0A), although MRtrix will also accept DOS-type newlines.

The first line should read only 'mrtrix image' to indicate that this is an image in MRtrix format. The last line of the header should read only 'END' to signal the end of the header, after which all data will be considered as binary.

All following lines are in the format 'key: value', with the value entry extending up to the end of the line. All whitespace characters before and after the value entry are ignored. Some keys are required to read the images, others are optional, and any key not recognised by MRtrix will simply be ignored. Recognised keys are listed below, along with the expected format of the corresponding values.

dim
  [required] the image dimensions, supplied as a comma-separated list of integers. The number of entries in the specifies the dimensionality of the image (currently limited to 16 dimensions). For example: `dim: 192,256,256` specifies a 192×256×256 image.
vox
  [required] the voxel size along each dimension, as a comma-separated list of floating-point values. The number of entries should match that given in the `dim` entry. For example: `vox: 0.9,0.898438,0.898438`.
layout
  [required] specifies the organisation of the data on file. In simplest terms, it provides a way of specifying the strides required to navigate the data file, in combination with the `dim` entry. It is given as a comma-separated list of signed integers, with the sign providing the direction of data traversal with respect to voxel coordinates, and the value providing a way of specifying the order of increasing stride.
  For example, assuming an image with `dim: 192,256,256`, the entry `layout: +2,-0,-1` is interpreted as: the shortest stride is along the y-axis (second entry), then the z-axis (third entry), and then along the x-axis. Voxels are stored in the order left to right (positive stride) along the x-axis; anterior to posterior along the y-axis (negative stride); and superior to inferior (negative stride) along the z-axis. Given the image dimensions, the final strides are therefore 256×256=65536 for adjacent voxels along the x-axis, -1 for the y-axis, and -256 for the z-axis. This also implies that the voxel at coordinate [ 0 0 0 ] is located 65536 voxel values into the data portion of the file.
datatype
  [required] the datatype used to store individual voxel values. Valid data types are listed in this section. For example: `datatype: UInt16LE`
file
  [required] speficies where the binary image data are stored, in the format file: filename offset, with the offset provided in bytes from the beginning of the file. For example: `file: image.dat 0`.
  For the single-file format (.mif), the filename should consists of a single full-stop ('.') to indicate the current file, and the offset should correspond to a point in the file after the END statement of the header.
  For the separate header/data format (.mih), the filename should refer to an existing file in the same folder as the header (.mih) file. Multiple such entries can be supplied if the data are stored across several files.
transform
  [optional] used to supply the 4×4 transformation matrix specifying the orientation of the axes with respect to real space. This is supplied as a comma-separated list of floating-point values, and only the first 12 such values will be used to fill the first 3 rows of the transform matrix. Multiple such entries can be provided to fill the matrix; for example, MRtrix will normally produce 3 lines for the transform, with one row of 4 values per entry:

      transform: 0.997986,-0.0541156,-0.033109,-74.0329
      transform: 0.0540858,0.998535,-0.00179436,-100.645
      transform: 0.0331575,2.34007e-08,0.99945,-125.84

labels
  [optional] used to specify the meaning of the axes, provided as a list of descriptions separated by backslashes. For example: `left->right\posterior->anterior\inferior->superior`
units
  [optional] used to specify the units for each axis, provided as a list of descriptions separated by backslashes. For example: `units: mm\mm\mm`
comments
  [optional] used to add generic comments to the header. Multiple such entries can be provided. For example: `comment: some information`

## Tracks file format (.tck)

The format for track files is similar to that for MRtrix-format images. It consists of a text header in the same key: value format, ending with a single 'END' statement, and followed by binary data.

The first line of the header should read "mrtrix tracks" to indicate that the file contains tracks in MRtrix format. Further key: value pairs typically provide information about the parameters used to produce the tracks, and for the most part are not required to read the data. The only required keys are the following:

file
  a file: . offset entry is required to specify the byte offset from the beginning of the file to the start of the binary track data. At this stage, only the single-file format is supported - in other words the filename part must be specified as '.' (see above for details).
datatype
  specifies the datatype (and byte order). At this points only the Float32 data type is supported, either as little-endian (LE) or big-endian (BE).

The binary track data themselves are stored as triplets of floating-point values (at this stage in 32 bit floating-point format), one per vertex along the track. Tracks are separated using a triplet of NaN values. Finally, a triplet of Inf values is used to indicate the end of the file.