The MGH/MGZ Volume Format
WORK IN PROGRESS
The .mgh file format is used to store high-resolution structural data and other data which are to be overlaid on the high-resolution structural volume. A .mgz (or .mgh.gz) file is a .mgh file that has been compressed with ZLib.
The MGH format is proprietary, defined by the NMR Center (at Massachusetts General Hospital). Below is an informal specification of the format, extracted from the code snippets below:
mri.h - .mgh file merely stores contents of MRI data structure, defined in mri.h
matrix.h - MRI data structure contains MATRIX
mriio.c - see 'mghRead' and 'mghWrite' routines, the MGH file format is implicitly specified by these routines
mri.c - contains helper routines used in mriio.c
mri_info.c - source for mri_info utility; see 'do_file' routine
mri_convert.c - source for mri_convert utility; many examples of reading and writing .mgh and .mgz files
fio.h, fio.c, tags.h, tags.c - miscellaneous files declaring constants and routines used to support routines in mri*.c files (note: input_transform_file, get_linear_transform_ptr and get_inverse_linear_transform_ptr are routines found in the volume_io package of the MINC toolkit)
load_mgh.m / save_mgh.m - Matlab code to read and write .mgh and .mgz files
Overview of the Volume File Format
As mentioned at the beginning of this page, the MGH format can be either plain binary or compressed, using ZLib.
A MGH file is structured as follows:
* at the beginning of the file is a header, which contains information about the general content of the file, size of the image buffer, spacing, and optionally the cosines transform;
* the image data buffer follows; its beginning position in the file is at a fixed length from the beginning of the file;
* after the data buffer, other optional information can follow (such as the scan parameters, as well as different command-lines used to obtain the image etc).
Before detailing the expected file contents, it should be mentioned that the byte order is BIG ENDIAN, so the necessary byte-swapping should be done.
Header Data
As can be seen in the attached code, the header format has specific information at given offsets. For simplicity, the values contained will be enumerated in sequential order and given their type, the offset in the file can be inferred:
MGH Volume Header |
||
Name |
Data Type |
Description |
version |
integer |
current value is 1 |
width |
integer |
first dimension of the image buffer (fastest) |
height |
integer |
second dimension of the image buffer (2nd fastest) |
depth |
integer |
slowest dimension when reading the buffer |
nframes |
integer |
number of scalar components contained in the buffer (i.e. number of components per voxel) |
type |
integer |
data type of the image buffer; can be one of the following: UCHAR, SHORT, INT, or FLOAT (specified as 0, 4, 1, or 3, respectively) |
dof |
integer |
degrees of freedom (where appropriate) |
goodRASFlag |
short |
if true, the direction cosines, which will be detailed next, are in the header; if false, a CORONAL orientation will be assumed |
spacing X |
float |
spacing in the X direction (ranging [0...width]) - default is 1 |
spacing Y |
float |
spacing in the Y direction (ranging [0...height]) - default is 1 |
spacing Z |
float |
spacing in the Z direction (ranging [0...depth]) - default is 1 |
xr |
float |
default is -1 |
xa |
float |
default is 0 |
xs |
float |
default is 0 |
yr |
float |
default is 0 |
ya |
float |
default is 0 |
ys |
float |
default is -1 |
zr |
float |
default is 0 |
za |
float |
default is 1 |
zs |
float |
default is 0 |
cr |
float |
default is 0 |
ca |
float |
default is 0 |
cs |
float |
default is 0 |
The values mentioned above as part of the orientation information for the volume are to be interpreted in the context described in the coordinate systems page. To resume, they define the rotational part of the affine transform that places the image data buffer in the physical space.
Image Data
The image data starts at a specified offset from the beginning of the file, which is currently byte 284 (bytes 0-283 are header). The data is read by frames (components). Each frame is a 3D image, with the voxels being read line by line (from the fastest to the slowest component).
Other Data
Immediately after the data buffer can be found optional data structures, which are:
Optional Data Structures |
||
Name |
Data Type |
Units |
TR |
float |
milliseconds |
FlipAngle |
float |
radians |
TE |
float |
milliseconds |
TI |
float |
milliseconds |
FoV |
float |
IGNORE THIS FIELD (data is inconsistent) |
tags |
variable length char strings |
- |
Tags include the path to the file containing talairach transform, and a list of commands used to create this data (provenance info).