Skip to main content

FsLabelUtils

Namespace: FSLIB  ·  Library: FreeSurfer Library

Python equivalent

mne.grow_labels / mne.split_label / mne.stc_to_label in MNE-Python.

#include <fs/fs_label_utils.h>

class FSLIB::FsLabelUtils

Stateless utilities that grow, split and convert FsLabel objects on a FreeSurfer triangular surface.

All operations take an FsSurface as the topology source and treat its triangle faces as the vertex adjacency graph. The helpers are static because labels carry their own state and the surface is supplied per call, mirroring the function-based API used by MNE-Python.

src/examples/ex_fs/main.cpp
const FsLabel grown = FsLabelUtils::growLabel(v1, white, 1); // add the one-ring neighbours
const QList<FsLabel> parts = FsLabelUtils::splitLabel(v1, white);

Static Methods​

growLabel(label, surface, nSteps)​

Grow a label by expanding along the surface mesh.

Starting from the seed vertices in the label, expands outward by nSteps along surface edges (breadth-first).

Parameters:

  • label : const FsLabel & The seed label to grow from.

  • surface : const FsSurface & The surface providing vertex adjacency.

  • nSteps : int Number of expansion steps.

Returns:

  • FsLabel — Grown label containing original + expanded vertices.

growCircularLabel(surface, seeds, extentMm, hemi, name)​

Grow a circular label around seed vertices, as mne.grow_labels does for one seed set.

Vertices within extentMm geodesic distance along the mesh edges are included, following mne's label growing (a distance found later is lowered but not propagated again). The label values are the distances in whole millimetres, as in MNE-Python.

Parameters:

  • surface : const FsSurface & Surface of the hemisphere.

  • seeds : const QVector< int > & Seed vertices.

  • extentMm : double Maximum geodesic distance in mm.

  • hemi : int Hemisphere (0 = lh, 1 = rh).

  • name : const QString & Label name; "-lh" / "-rh" is appended unless present.

Returns:

  • FsLabel — The grown label, vertices ascending.

splitLabel(label, surface)​

Split a label into connected components.

Like mne Label.split("contiguous"): the parts keep the label's positions and values, come largest first and are named <name>_div<i>, before a trailing -lh / -rh.

Parameters:

  • label : const FsLabel & The label to split.

  • surface : const FsSurface & The surface providing vertex adjacency (empty: every vertex is its own part).

Returns:

  • QList< FsLabel > — List of sub-labels (connected components).

stcToLabel(stcData, vertices, surface, dThreshold, iHemi)​

Convert a source estimate to labels by thresholding.

Vertices whose absolute value exceeds the threshold at any time point are grouped into connected labels on the surface.

Parameters:

  • stcData : const Eigen::MatrixXd & Source estimate data (n_vertices × n_times).

  • vertices : const Eigen::VectorXi & Vertex indices in the source estimate.

  • surface : const FsSurface & The surface providing positions and adjacency.

  • dThreshold : double Absolute threshold for inclusion (default 0.0 = include all).

  • iHemi : int Hemisphere id (0=lh, 1=rh).

Returns:

  • QList< FsLabel > — List of labels (connected components above threshold).

labelsToStc(labels, stcVertices, nTimes)​

Convert labels to a binary source estimate mask.

Creates a matrix of ones for vertices inside the labels, zeros otherwise.

Parameters:

  • labels : const QList< FsLabel > & Labels to convert.

  • stcVertices : const Eigen::VectorXi & Vertex indices of the target STC space.

  • nTimes : int Number of time points.

Returns:

  • Eigen::MatrixXd — Binary mask (n_vertices × n_times).

buildAdjacency(tris, nVerts)​

Build adjacency list from surface triangle mesh.

Parameters:

  • tris : const Eigen::MatrixX3i & Triangle matrix (n_tris × 3).

  • nVerts : int Total number of vertices.

Returns:

  • QList< QSet< int > > — Adjacency list: for each vertex, the set of neighbor vertices.

Example​

Used in examples​

ex_fs​

FreeSurfer library: surfaces, curvature, parcellations, labels and an atlas volume.

src/examples/ex_fs/main.cpp, line 161
const FsLabel grown = FsLabelUtils::growLabel(v1, white, 1); // add the one-ring neighbours
const QList<FsLabel> parts = FsLabelUtils::splitLabel(v1, white);
// Closed form on the mesh graph (scipy.sparse.csgraph): one ring adds 447 vertices; components of 5635, 2 and 1
QList<int> sizes;
for (const FsLabel& part : parts) {
    sizes.append(part.vertices.size());
}
std::sort(sizes.begin(), sizes.end(), std::greater<int>());
ok &= expect(grown.vertices.size() - v1.vertices.size() == 447 && sizes == QList<int>({5635, 2, 1}),
             QString("growLabel adds %1 vertices (447); splitLabel parts %2").arg(grown.vertices.size() - v1.vertices.size()).arg(sizes.size()));

Authors of this file​