[wiki:FreeSurferWiki top] | [wiki:FileFormats previous]

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:

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 (having #define values of 0, 4, 1, or 3, respectively)

dof

integer

?

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 [wiki:CoordinateSystems 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

TR

float

FlipAngle

float

TE

float

TI

float

FoV

float

tags

variable length

Tags include the path to the file containing talairach transform, and a list of commands used to create this data (provenance info).