The FreeSurfer color look-up table

Container for outputs of a DTI fit

Container for segmentation and tract look-up tables

LUT(infile::String)

Read a look-up table from infile and return a LUT structure

The input file is assumed to have the format of FreeSurferColorLUT.txt

LUT()

Return an empty LUT structure

MRI(ref::MRI, nframes::Integer=ref.nframes)

Return an MRI structure whose header fields are populated based on a reference MRI structure ref, and whose image array are populated with zeros.

Optionally, the new MRI structure can be created with a different number of frames (nframes) than the reference MRI structure.

Container for header and image data of an MRI volume or volume series

MRI()

Return an empty MRI structure

Container for header and image data of a volume stored in NIfTI format

NIfTIheader()

Return an empty NIfTIheader structure

Container for header and streamline data stored in .trk format

Tract(ref::MRI)

Return a Tract structure whose header fields are populated based on the reference MRI structure ref

Tract()

Return an empty Tract structure

dti_fit_ls(dwi::MRI, mask:MRI)

Fit tensors to DWIs and return a DTI structure.

dti_fit_ls(dwi::MRI, mask:MRI)

Perform least-squares fitting of tensors from DWIs and return a DTI structure.

dti_maps(eigval1::MRI, eigval2::MRI, eigval3::MRI)

Compute radial diffusivity (RD), mean diffusivity (MD), and fractional anisotropy (FA) maps from the 3 eigenvalues the diffusion tensors.

Return RD, MD, and FA maps as MRI structures.

dti_write(dti::DTI, basename::String)

Write the volumes from a DTI structure that was created by dti_fit() to files whose names start with the specified base name.

get_tmp_path(tmpdir::String="")

Return path to a directory where temporary files can be stored.

Search for candidate directories in the following order:

1. $TMPDIR: Check if environment variable is defined and directory exists
2. $TEMPDIR: Check if environment variable is defined and directory exists
3. /scratch: Check if directory exists
4. /tmp: Check if directory exists
5. tmpdir: Check if tmpdir argument was passed and directory exists

If none of the above exist, use current directory (./) and print warning.

load_bruker(indir::String, headeronly::Bool=false)

Read Bruker image data from disk and return an MRI structure similar to the FreeSurfer MRI struct defined in mri.h.

Arguments

• indir::String: Path to a Bruker scan directory (files called method,

pdata/1/reco, and pdata/1/2dseq are expected to be found in it)

• headeronly::Bool=false: If true, the pixel data are not read in.

load_mgh(fname::String, slices::Union{Vector{Unsigned}, Nothing}=nothing, frames::Union{Vector{Unsigned}, Nothing}=nothing, headeronly::Bool=false)

Load a .mgh or .mgz file from disk.

Return:

• The image data as an array

• The 4x4 vox2ras matrix that transforms 0-based voxel indices to coordinates such that: [x y z]' = M * [i j k 1]'

• MRI parameters as a vector: [tr, flip_angle, te, ti]

• The image volume dimensions as a vector (useful when headeronly is true, in which case the image array will be empty)

Arguments

• fname::String: Path to the .mgh/.mgz file

• slices::Vector: 1-based slice numbers to load (default: read all slices)

• frames::Vector: 1-based frame numbers to load (default: read all frames)

• headeronly::Bool=false: If true, the pixel data are not read in.

load_nifti(fname::String, hdronly::Bool=false)

Load a NIfTI (.nii or .nii.gz) volume from disk and return a NIfTIheader structure.

Handle compressed NIfTI (nii.gz) by issuing an external Unix call to uncompress the file to a temporary file, which is then deleted.

The output structure contains:

• the image data, in the .vol field
• the units for each dimension of the volume [mm or msec], in the .pixdim field
• the sform and qform matrices, in the .sform and .qform fields
• the vox2ras matrix, which is the sform (if valid), otherwise the qform, in the .vox2ras field

Handle data structures with more than 32k cols by looking at the .dim field. If dim[2] = -1, then the .glmin field contains the numbfer of columns. This is FreeSurfer specific, for handling surfaces. When the total number of spatial voxels equals 163842, then reshape the volume to 163842x1x1xnframes. This is for handling the 7th order icosahedron used by FS group analysis.

hdr = load_nifti_hdr(fname::String)

Load the header of a .nii volume from disk.

Return a NIfTIheader structure, where units have been converted to mm and msec, the sform and qform matrices have been computed and stored in the .sform and .qform fields, and the .vox2ras field has been set to the sform (if valid), then the qform (if valid).

Assume that the input file is uncompressed (compression is handled in the wrapper load_nifti()).

Handle data structures with more than 32k cols by setting the .glmin field to ncols when hdr.dim[2] < 0. This is FreeSurfer specific, for handling surfaces.

mri_filename(fstring::String, checkdisk::Bool=true)

Return a valid file name, file stem, and file extension, given a string fstring that can be either a file name or a file stem.

Valid extensions are: mgh, mgz, nii, nii.gz. Thus a file name is expected to have the form stem.{mgh, mgz, nii, nii.gz}.

If fstring is a file name, then the stem and extension are determined from fstring.

If fstring is a file stem and checkdisk is true (default), then the file name and extension are determined by searching for a file on disk named fstring.{mgh, mgz, nii, nii.gz}, where the possible extensions are searched for in this order. If no such file is found, then empty strings are returned.

mri_read(infile::String, headeronly::Bool=false, permuteflag::Bool=false)

Read an image volume from disk and return an MRI structure similar to the FreeSurfer MRI struct defined in mri.h.

Arguments

• infile::String: Path to the input, which can be:

  1. An MGH file, e.g., f.mgh or f.mgz
  2. A NIfTI file, e.g., f.nii or f.nii.gz
  3. A file stem, in which case the format and full file name are determined by finding a file on disk named infile.{mgh, mgz, nii, nii.gz}
  4. A Bruker scan directory, which is expected to contain the following files: method, pdata/1/reco, pdata/1/2dseq

• headeronly::Bool=false: If true, the pixel data are not read in.

• permuteflag::Bool==false: If true, the first two dimensions of the image volume are permuted in the .vol, .volsize, and .volres fields of the output structure (this is the default behavior of the MATLAB version). The permuteflag will not affect the vox2ras matrices, which always map indices in the (column, row, slice) convention.

Output

In the MRI structure:

• Times are in ms and angles are in radians.

• vox2ras0: This field contains the vox2ras matrix that converts 0-based (column, row, slice) voxel indices to (x, y, z) coordinates. This is the also the matrix that mri_write() uses to derive all geometry information (e.g., direction cosines, voxel resolution, P0). Thus if any other geometry fields of the structure are modified, the change will not be reflected in the output volume.

• vox2ras1: This field contains the vox2ras matrix that converts 1-based (column, row, slice) voxel indices to (x, y, z) coordinates.

• niftihdr: If the input file is NIfTI, this field contains a NIfTIheader structure.

mri_read_bfiles!(dwi::MRI, infile1::String, infile2::String)

Set the .bval and .bvec fields of the MRI structure dwi, by reading a DWI b-value table and gradient table from the text files infile1 and infile2. The two input files can be specified in any order. The gradient table file must contain 3 times as many entries as the b-value table file.

Return the b-value table as a vector of size n and the gradient table as a matrix of size (n, 3).

mri_read_bfiles(infile1::String, infile2::String)

Read a DWI b-value table and gradient table from text files infile1 and infile2. The two input files can be specified in any order. The gradient table file must contain 3 times as many entries as the b-value table file.

Return the b-value table as a vector of size n and the gradient table as a matrix of size (n, 3).

mri_set_geometry!(mri::MRI)

Set header fields related to volume geometry in an MRI structure.

These are redundant fields that can be derived from the vox2ras0, width, height, depth fields. They are in the MRI struct defined in mri.h, as well as the MATLAB version of this structure, so they have been added here for completeness.

Note: mri_write() derives all geometry information (i.e., direction cosines, voxel resolution, and P0 from vox2ras0. If any of the redundant geometry elements below are modified, the change will not be reflected in the output volume.

mri_write(mri::MRI, outfile::String, datatype::DataType=Float32)

Write an MRI volume to disk. Return true is an error occurred (i.e., the number of bytes written were not as expected based on the size of the volume).

Arguments

• mri::MRI: A structure like that returned by mri_read(). The geometry (i.e., direction cosines, voxel resolution, and P0) are all recomputed from mri.vox2ras0. So, if a method has changed one of the other fields, e.g., mri.x_r, this change will not be reflected in the output volume.

• outfile::String: Path to the output file, which can be:

  1. An MGH file, e.g., f.mgh or f.mgz (uncompressed or compressed)
  2. A NIfTI file, e.g., f.nii or f.nii.gz (uncompressed or compressed).

• datatype::DataType=Float32: Only applies to NIfTI and can be UInt8, Int16, Int32, Float32, Float64, Int8, UInt16, UInt32.

save_mgh(vol::Array, fname::String, M::Matrix=Diagonal(ones(4)), mr_parms::Vector=zeros(4))

Write an MRI volume to a .mgh or .mgz file. Return true is an error occurred (i.e., the number of bytes written were not as expected based on the size of the volume).

Arguments

• vol::Array: the image data

• fname::String: path to the output file

• M::Matrix: the 4x4 vox2ras transform such that [x y z]' = M * [i j k 1]', where the voxel indices (i, j, k) are 0-based.

• mr_parms::Vector: a vector of MRI parameters, [tr, flip_angle, te, ti]

save_nifti(hdr::NIfTIheader, fname::String)

Write an MRI volume to a .nii or .nii.gz file. Return true is an error occurred (i.e., the number of bytes written were not as expected based on the size of the volume).

Arguments

• hdr::NIfTIheader: a NIfTI header structure that contains the image data in its .vol field

• fname::String: path to the output file

Handle data structures with more than 32k cols by setting hdr.dim[2] = -1 and hdr.glmin = ncols. This is FreeSurfer specific, for handling surfaces. The exception to this is when the total number of spatial voxels equals 163842, then the volume is reshaped to 27307x1x6xnframes. This is for handling the 7th order icosahedron used by FS group analysis.

show(mri::MRI, mrimod::Union{MRI, Nothing}=nothing)

Show an MRI structure (an image slice and a summary of header info) in the terminal window

Arguments:

• mri::MRI: the main image to display
• mrimod:MRI: an optional image to modulate the main image by (e.g., an FA map to modulate a vector map)

trk_read(infile::String)

Read tractography streamlines from infile and return a Tract structure

Input file must be in .trk format, see: http://trackvis.org/docs/?subsect=fileformat

 trk_write(tr::Tract, outfile::String)

Write a Tract structure to a file in the .trk format

Return true if an error occurred (i.e., the number of bytes written was not the expected based on the size of the Tract structure)

view(mri::MRI)

View an MRI structure in a slice viewer

vol_to_rgb(vol::Array)

Convert an image array to an RGB/Gray array for display.

Determine how the image should be displayed:

• If all the values are IDs in the FreeSurfer color look-up table, the image is assumed to be is a segmentation map and is converted to RGB based on the FreeSurfer color look-up table.
• If the image has size 3 in any dimension, and the sum of squares of the values in that dimension is approx. 1 everywhere, the image is assumed to be a vector map and is converted to RGB based on vector orientation.
• Otherwise, the image is assumed to be a generic intensity map and is converted to grayscale.

Return an array of RGB/Gray values the same size as the input vol.

vox2ras_0to1(M0::Matrix)

Convert a 0-based vox2ras matrix M0 to a 1-based vox2ras matrix such that:

Pxyz = M0 * [c r s 1]' = M1 * [c+1 r+1 s+1 1]'

vox2ras_tkreg(voldim::Vector, voxres::Vector)

Return a 0-based vox2ras transform of a volume that is compatible with the registration matrix produced by tkregister. May work with MINC xfm.

Arguments

• voldim = [ncols; nrows; nslices ...]
• volres = [colres; rowres; sliceres ...]

vox2ras_to_qform(vox2ras::Matrix)

Convert a vox2ras matrix to NIfTI qform parameters. The vox2ras should be 6 DOF.

Return the following NIfTI header fields:

• hdr.quatern_b
• hdr.quatern_c
• hdr.quatern_d
• hdr.qoffset_x
• hdr.qoffset_y
• hdr.qoffset_z
• hdr.pixdim[1]

From DG's vox2rasToQform.m: This code mostly just follows CH's mriToNiftiQform() in mriio.c