mri_mgh_io.h File Reference

FreeSurfer MGH / MGZ volume reader: byte-level decoder for the 284-byte fixed header, voxel buffer, and optional tag footer. More...

#include "mri_global.h"
#include "mri_vol_data.h"
#include <QString>
#include <QVector>

Include dependency graph for mri_mgh_io.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes
class	MRILIB::MriMghIO
	Stateless decoder for FreeSurfer MGH and MGZ volume containers. More...

Namespaces
namespace	MRILIB
	Volume I/O, voxel geometry and slice resampling for structural MRI data inside mne-cpp.

Detailed Description

FreeSurfer MGH / MGZ volume reader: byte-level decoder for the 284-byte fixed header, voxel buffer, and optional tag footer.

SPDX-License-Identifier: BSD-3-Clause Copyright (c) 2026 MNE-CPP Authors

Author

Christoph Dinh chris.nosp@m.toph.nosp@m..dinh.nosp@m.@mne.nosp@m.-cpp..nosp@m.org

Since

2.0.0

Date

February 2026

MGH is FreeSurfer's native volume container — a fixed 284-byte big-endian header followed by a column-major voxel buffer and an optional tag footer carrying scan parameters and the path to talairach.xfm. MGZ is the same layout wrapped in a single gzip stream; this reader handles both transparently by detecting the .mgz suffix and routing the file through zlib's MAX_WBITS+16 inflate mode before parsing.

Output is materialised into an MriVolData (slice-of-slices representation) using the same per-slice pixel formats the COR.fif writer expects, so the volume can be re-serialised round-trip without a second conversion pass.

File format reference: https://surfer.nmr.mgh.harvard.edu/fswiki/FsTutorial/MghFormat

MGH Header Layout (all big-endian, total 284 bytes):

Offset Size Field

---

0 4 version (int32) — must be 1 4 4 width (int32) — first image dimension 8 4 height (int32) — second image dimension 12 4 depth (int32) — third image dimension 16 4 nframes (int32) — number of frames 20 4 type (int32) — voxel data type (0=uchar, 1=int, 3=float, 4=short) 24 4 dof (int32) — degrees of freedom 28 2 goodRASflag (int16) — if > 0 the following fields are valid 30 12 spacingX, spacingY, spacingZ (3×float32) — voxel sizes in mm 42 36 direction cosines: xr,xa,xs, yr,ya,ys, zr,za,zs (9×float32) 78 12 c_ras: cr, ca, cs (3×float32) — center RAS coordinates 90 194 unused (padding to byte 284)

Image Data (starting at byte 284): width × height × depth × nframes × sizeof(type) bytes Stored in column-major (Fortran) order: x varies fastest.

Footer (after image data, optional): Scan parameters: TR (float32), flipAngle (float32), TE (float32), TI (float32), FoV (float32) Tags: type(int32) + length(int32/int64) + data TAG_OLD_SURF_GEOM (20): old surface geometry, length is int32 TAG_OLD_MGH_XFORM (30): old transform, length is int32 TAG_MGH_XFORM (31): path to talairach.xfm file, length is int64

Ported from make_mgh_cor_set() in MNE C mne_make_cor_set by Matti Hamalainen.

Definition in file mri_mgh_io.h.