NIfTI
Files ending in .nii are in the NIfTI medical image format, which is becoming a standard format for many different medical imaging software packages, including FSL. .nii files combine the metadata header and image data into a single file, but NIfTI-1 is a modified form of Analyze 7.5, so it sometimes comes in .hdr/.img pairs. The NIfTI I/O library and command line tools also directly handle compressed NIfTI, with the extension .nii.gz. You can test for the format by using the is_nifti_file() function in the I/O library.
Paths
$G/src/nifti is the source code for the NIfTI I/O library, which installs to $G/lib/nifti and $G/include/nifti.
Use
Library
To use the NIfTI I/O library, simply #include <nifti1_io.h> in your code and add the following to the library list in your makefile: niftiio znz m z.
$G/src/nifti2mriimage/nifti2mriimage.cpp demonstrates reading the header and extracting information from it, as well as reading the image data.
Command-Line Utilities
The $G/bin/nifti_tool utility can read the header in a structured way and print out tons of metadata, as well as manipulating the actual data and doing a lot more. It's a good way to explore new data before deciding how to script with it. See nifti_tool for a quick guide to common operations.
Format Conversion
$G/bin/nifti2mriimage converts to MRIimage.
Documentation
make install puts some documentation in $G/doc/nifti. However, the online documentation for NIfTI is probably even better and more useful:
Coordinate System
NIfTI strictly defines its coordinate system, which is patient-based. The voxel indices (i,j,k) map onto a spatial (x,y,z) coordinate system according to a transformation matrix that's stored in the header. If the matrix is the identity, then (i,j,k) of course maps directly to (x,y,z); if it is diagonal, then each spatial coordinate is a scalar multiple of each voxel index (which accounts for the voxel size).
The NIfTI standard coordinate system has:
- +x = Patient's Right (x increases from patient's left to patient's right)
- +y = Anterior (y increases from posterior (back of head) to anterior (nose))
- +z = Superior (z increases from inferior (base of head) to superior (top of head))
Note that this is a right-handed coordinate system, and that it is different from the default coordinate system for MRIimage. The nifti2mriimage program properly converts between the two coordinate systems, but if you write your own code that mixes these worlds, this is an important detail to keep in mind.
The voxel index (i,j,k) indicates a memory location (i + j*dim[1] + k*dim[1]*dim[2]) * (bitpix/8) into the dataset array. This means that the i index varies most rapidly, j next, and k slowest. The valid inclusive ranges for (i,j,k) are, respectively, 0 to dim[1]-1, 0 to dim[2]-1, and 0 to dim[3]-1.
The (x,y,z) spatial coordinate specifies the position of the center of the voxel, the central location of the physical measurement recorded in that voxel.
For more details, please read the NIfTI-1 Header Field Descriptions and the NIfTI-1 header file itself.
History
The format was created by the Neuroimaging Informatics Technology Initiative at NIH. It is a superset of Analyze 7.5, re-purposing empty fields in the Analyze format to support more features. Fortunately for us, the NIfTI reference library is available in the public domain, and $G/src/nifti is set up to download the latest version (with make download), build it, and install it. NIfTI is an actively developed format, but the NIfTI-1 specification is fixed; NIfTI-2 will be formulated and released at some point in the future.