Skip to main content

FsSurface

Namespace: FSLIB  ·  Library: FreeSurfer Library

Python equivalent

mne.read_surface in MNE-Python.

#include <fs/fs_surface.h>

class FSLIB::FsSurface

In-memory FreeSurfer triangular cortical surface for one hemisphere.

Owns the vertex coordinate matrix (n_vertices × 3, Tk-surface RAS mm), the triangle index matrix (n_faces × 3, zero-based into the vertex array) and the hemisphere id (0 = lh, 1 = rh). Construction is purely an I/O operation: each constructor either takes a direct path to a lh.pial / rh.white / lh.inflated style binary surface file, or the subject_id / hemi / surf shorthand resolved against $SUBJECTS_DIR. The instance is intended to be paired with an FsAnnotation or FsLabel sharing the same vertex indexing.

src/examples/ex_fs/main.cpp
FsSurface white("sample", 0, "white", subjectsDir); // lh = 0, rh = 1; curvature is loaded alongside
const MatrixX3f& rr = white.rr();                   // vertices (metres)
const MatrixX3i& tris = white.tris();
const VectorXf& curv = white.curv();

Public Methods​

FsSurface()​

Default constructor.

FsSurface(p_sFile)​

Construts the surface by reading it of the given file.

Parameters:

  • p_sFile : const QString & FsSurface file name with path.

FsSurface(subject_id, hemi, surf, subjects_dir)​

Construts the surface by reading it of the given file.

Parameters:

  • subject_id : const QString & Name of subject.

  • hemi : qint32 Which hemisphere to load {0 -> lh, 1 -> rh}.

  • surf : const QString & Name of the surface to load (eg. inflated, orig ...).

  • subjects_dir : const QString & Subjects directory.

FsSurface(path, hemi, surf)​

Construts the surface by reading it of the given file.

Parameters:

  • path : const QString & path to surface directory.

  • hemi : qint32 Which hemisphere to load {0 -> lh, 1 -> rh}.

  • surf : const QString & Name of the surface to load (eg. inflated, orig ...).

~FsSurface()​

Destroys the FsSurface class.

clear()​

Initializes the FsSurface.

hemi()​

Returns the hemisphere id (0 = lh; 1 = rh).

Returns:

  • qint32 — hemisphere id.

isEmpty()​

Returns whether FsSurface is empty.

Returns:

  • bool — true if is empty, false otherwise.

surf()​

Loaded surface (eg.

inflated, orig ...)

Returns:

  • QString — the surface.

rr()​

Coordinates of vertices (rr).

Returns:

  • const Eigen::MatrixX3f & — coordinates of vertices.

tris()​

The triangle descriptions.

Returns:

  • const Eigen::MatrixX3i & — triangle descriptions.

nn()​

Normalized surface normals for each vertex.

Returns:

  • const Eigen::MatrixX3f & — surface normals.

curv()​

FreeSurfer curvature.

Returns:

  • const Eigen::VectorXf & — the FreeSurfer curvature data.

offset()​

Vector offset.

Returns:

  • const Eigen::Vector3f & — the offset vector.

offset()​

Vector offset.

Returns:

  • Eigen::Vector3f & — the offset vector.

filePath()​

path to surf directuryt

Returns:

  • QString — the path to surf directory.

fileName()​

surf file name

Returns:

  • QString — the surf file name.

Static Methods​

read(subject_id, hemi, surf, subjects_dir, p_Surface, p_bLoadCurvature)​

mne_read_surface

Reads a FreeSurfer surface file

Parameters:

  • subject_id : const QString & Name of subject.

  • hemi : qint32 Which hemisphere to load {0 -> lh, 1 -> rh}.

  • surf : const QString & Name of the surface to load (eg. inflated, orig ...).

  • subjects_dir : const QString & Subjects directory.

  • p_Surface : FsSurface & The read surface.

  • p_bLoadCurvature : bool True if the curvature should be read (optional, default = true).

Returns:

  • bool — true if read sucessful, false otherwise.

read(path, hemi, surf, p_Surface, p_bLoadCurvature)​

mne_read_surface

Reads a FreeSurfer surface file

Parameters:

  • path : const QString & path to surface directory.

  • hemi : qint32 Which hemisphere to load {0 -> lh, 1 -> rh}.

  • surf : const QString & Name of the surface to load (eg. inflated, orig ...).

  • p_Surface : FsSurface & The read surface.

  • p_bLoadCurvature : bool True if the curvature should be read (optional, default = true).

Returns:

  • bool — true if read sucessful, false otherwise.

read(p_sFileName, p_Surface, p_bLoadCurvature)​

mne_read_surface

Reads a FreeSurfer surface file

Parameters:

  • p_sFileName : const QString & The file to read.

  • p_Surface : FsSurface & The read surface.

  • p_bLoadCurvature : bool True if the curvature should be read (optional, default = true).

Returns:

  • bool — true if read sucessful, false otherwise.

read_curv(p_sFileName)​

reads a binary curvature file into a vector

Parameters:

  • p_sFileName : const QString & Path to the FreeSurfer curvature file (e.g. lh.curv).

Returns:

  • Eigen::VectorXf — the read curvature.

compute_normals(rr, tris)​

Efficiently compute vertex normals for triangulated surface.

Parameters:

  • rr : const Eigen::MatrixX3f & Vertex coordinates in meters.

  • tris : const Eigen::MatrixX3i & The triangle descriptions.

Returns:

  • Eigen::MatrixX3f — The computed normals.

fread3(stream)​

Reads a 3-byte integer out of a QDataStream (FreeSurfer format).

Parameters:

  • stream : QDataStream & Stream to read from.

Returns:

  • qint32 — the read 3-byte integer.

fread3(stream)​

Reads a 3-byte integer out of a std::iostream (FreeSurfer format).

Parameters:

  • stream : std::iostream & Stream to read from.

Returns:

  • qint32 — the read 3-byte integer.

fread3_many(stream, count)​

Reads multiple 3-byte integers out of a QDataStream (FreeSurfer format).

Parameters:

  • stream : QDataStream & Stream to read from.

  • count : qint32 Number of elements to read.

Returns:

  • Eigen::VectorXi — the read 3-byte integers.

fread3_many(stream, count)​

Reads multiple 3-byte integers out of a std::iostream (FreeSurfer format).

Parameters:

  • stream : std::iostream & Stream to read from.

  • count : qint32 Number of elements to read.

Returns:

  • Eigen::VectorXi — the read 3-byte integers.

Example​

Used in examples​

ex_mne_api​

MNE library: BEM surfaces, surface projection, ICP, source spaces and epochs.

src/examples/ex_mne_api/main.cpp, line 533
// Morph map between the registered spheres of two subjects: every vertex of "large" is a
// barycentric blend of the three corners of the "small" triangle it falls into.
const QString subjectsDir = QStringLiteral(MNE_MORPH_SUBJECTS_DIR);
FsSurface smallSphere;
FsSurface largeSphere;
FsSurface::read(subjectsDir + "/small/surf/lh.sphere.reg", smallSphere, false);
FsSurface::read(subjectsDir + "/large/surf/lh.sphere.reg", largeSphere, false);
MNEMorphMap smallToLarge = MNEMorphMap::compute(smallSphere.rr(), smallSphere.tris(), largeSphere.rr());
smallToLarge.from_subj = "small";
smallToLarge.to_subj = "large";
smallToLarge.hemi = 0;
const QString mapFile = tmp.filePath("small-large-morph.fif");
MNEMorphMap::write(mapFile, {&smallToLarge});
const auto reread = MNEMorphMap::read(mapFile, "small", "large", 0);

ex_clustered_inverse_mne​

Example of a Clustered Inverse Minimum Norm Estimation application.

src/examples/ex_clustered_inverse_mne/main.cpp, line 89
QCommandLineOption methodOption("method", "Inverse estimation <method>, i.e., 'MNE', 'dSPM' or 'sLORETA'.", "method", "dSPM"); //"MNE" | "dSPM" | "sLORETA"
QCommandLineOption invFileOption("invOut", "Path to inverse <file>, which is to be written.", "file", "");
QCommandLineOption stcFileOption("stcOut", "Path to stc <file>, which is to be written.", "file", "");
QCommandLineOption surfOption("surfType", "FsSurface type <type>.", "type", "orig");
QCommandLineOption annotOption("annotType", "FsAnnotation type <type>.", "type", "aparc.a2009s");
QCommandLineOption hemiOption("hemi", "Selected hemisphere <hemi>.", "hemi", "2");
QCommandLineOption subjectOption("subject", "Selected subject <subject>.", "subject", "sample");
QCommandLineOption subjectPathOption("subjectPath", "Selected subject path <subjectPath>.", "subjectPath", QCoreApplication::applicationDirPath() + "/../resources/data/MNE-sample-data/subjects");

ex_clustered_inverse_mne_raw​

Example of the computation of a clustered inverse mne raw.

src/examples/ex_clustered_inverse_mne_raw/main.cpp, line 95
QCommandLineOption inputOption("fileIn", "The input file <in>.", "in", QCoreApplication::applicationDirPath() + "/../resources/data/MNE-sample-data/MEG/sample/sample_audvis_raw.fif");
QCommandLineOption surfOption("surfType", "FsSurface type <type>.", "type", "inflated");
QCommandLineOption annotOption("annotType", "FsAnnotation type <type>.", "type", "aparc.a2009s");
QCommandLineOption subjectOption("subject", "Selected subject <subject>.", "subject", "sample");
QCommandLineOption subjectPathOption("subjectPath", "Selected subject path <subjectPath>.", "subjectPath", QCoreApplication::applicationDirPath() + "/../resources/data/MNE-sample-data/subjects");
QCommandLineOption fwdOption("fwd", "Path to forwad solution <file>.", "file", QCoreApplication::applicationDirPath() + "/../resources/data/MNE-sample-data/MEG/sample/sample_audvis-meg-eeg-oct-6-fwd.fif");
QCommandLineOption covFileOption("cov", "Path to the covariance <file>.", "file", QCoreApplication::applicationDirPath() + "/../resources/data/MNE-sample-data/MEG/sample/sample_audvis-cov.fif");
QCommandLineOption evokedIndexOption("aveIdx", "The average <index> to choose from the average file.", "index", "1");
QCommandLineOption eventsFileOption("eve", "Path to the event <file>.", "file", QCoreApplication::applicationDirPath() + "/../resources/data/MNE-sample-data/MEG/sample/sample_audvis_raw-eve.fif");
QCommandLineOption hemiOption("hemi", "Selected hemisphere <hemi>.", "hemi", "2");
QCommandLineOption methodOption("method", "Inverse estimation <method>, i.e., 'MNE', 'dSPM' or 'sLORETA'.", "method", "dSPM"); //"MNE" | "dSPM" | "sLORETA"
QCommandLineOption snrOption("snr", "The SNR value used for computation <snr>.", "snr", "1.0");                                //3.0;//0.1;//3.0;
QCommandLineOption invFileOutOption("invOut", "Path to inverse <file>, which is to be written.", "file", "");
QCommandLineOption stcFileOutOption("stcOut", "Path to stc <file>, which is to be written.", "file", "");

Also used in ex_clustered_inverse_pwl_rap_music_raw, ex_clustered_inverse_rap_music_raw, ex_disp_3D, ex_fs, ex_fs_surface, ex_inverse_mne_raw, ex_inverse_pwl_rap_music, ex_inverse_rap_music, ex_read_fwd, ex_read_fwd_disp_3D, ex_roi_clustered_inverse_pwl_rap_music, ex_st_clustered_inverse_pwl_rap_music.

Authors of this file​