fs_surface.h File Reference

Reader and in-memory representation of a single FreeSurfer triangular surface (e.g. lh.pial, rh.white, lh.inflated). More...

#include "fs_global.h"
#include <QSharedPointer>
#include <QDataStream>
#include <iostream>
#include <Eigen/Core>

Include dependency graph for fs_surface.h:

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

Go to the source code of this file.

Classes
class	FSLIB::FsSurface
	In-memory FreeSurfer triangular cortical surface for one hemisphere. More...

Namespaces
namespace	FSLIB
	FreeSurfer surface, annotation and parcellation I/O for mne-cpp.

Detailed Description

Reader and in-memory representation of a single FreeSurfer triangular surface (e.g. lh.pial, rh.white, lh.inflated).

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

March 2026

A FreeSurfer surface file stores one cortical hemisphere as a closed triangular mesh: a list of vertex positions in Tk-surface RAS millimetres followed by a list of triangle faces given as indices into that vertex array. The reader handles the two binary container variants emitted by FreeSurfer’s MRISwrite():

• The legacy quadrangle format QUAD_FILE_MAGIC_NUMBER (0xFFFFFE), whose quad faces are split into two triangles on load.
• The modern triangle format TRIANGLE_FILE_MAGIC_NUMBER (0xFFFFFE) produced by current versions of mris_convert and recon-all, with a textual created by / filename header line preceding the little-endian 24-bit magic.

Magic numbers, file layout and the implicit big-endian byte order all follow utils/mrisurf_io.c (in particular mrisReadTriangleFile and mrisReadQuadFile) and the public reference in freesurfer/utils/read_surf.c. Coordinates are returned in millimetres in the FreeSurfer Tk-surface RAS frame; conversion to scanner RAS requires the vox2ras-tkr / vox2ras-scanner transform pair from the subject’s orig.mgz and is intentionally left to callers.

The class also accepts the subject_id + hemi + surf shorthand used throughout the MNE-Python and mne-c stack and resolves it against $SUBJECTS_DIR/ <id>/surf/{lh|rh}.<surf>, so existing analysis scripts port across without path rewrites.

Definition in file fs_surface.h.