netneurotools.plotting._pv_make_subcortex_surfaces

netneurotools.plotting._pv_make_subcortex_surfaces(atlas, include_keys, custom_params=None)[source]

Generate surface meshes from volumetric subcortical atlas data.

This function converts volumetric segmentation data (e.g., NIfTI files) into 3D surface meshes suitable for visualization with PyVista. It uses a pipeline of Gaussian smoothing, marching cubes algorithm, and Taubin smoothing to create high-quality surface representations.

Warning

This function is considered experimental and may be subject to changes anytime.

Parameters:

  • atlas (str or Path) – Path to the volumetric atlas file (e.g., NIfTI format) containing integer-labeled regions.

  • include_keys (list of int) – List of integer region identifiers to convert to surface meshes. These should match the integer labels in the atlas file.

  • custom_params (dict, optional) – Custom parameters to override defaults for the meshification process. Can contain:

    • ‘gaussian_filter’: dict with ‘sigma’ (float) and ‘threshold’ (float)

    • ‘taubin_smoothing’: dict with ‘lamb’ (float), ‘nu’ (float), and ‘iterations’ (int)

    Default is None.

Returns:

multiblock – PyVista MultiBlock object containing surface meshes for each region. Keys are string versions of the input region identifiers.

Return type:

pyvista.MultiBlock

Notes

Meshification pipeline:

The function converts volumetric data to surface meshes through three steps:

  1. Gaussian smoothing: Applies a 3D Gaussian filter to smooth the binary mask for each region. The sigma parameter controls the smoothing strength. Higher values create smoother, more rounded surfaces but may lose fine details. Lower values preserve details but may result in blocky surfaces.

  2. Marching cubes: Extracts an isosurface from the smoothed volume using the marching cubes algorithm. The threshold parameter determines the isosurface level. Values around 0.5 work well for binary masks after Gaussian smoothing.

  3. Taubin smoothing: Applies mesh smoothing to reduce surface artifacts while preserving volume. The lamb parameter controls the amount of smoothing (positive shrinking step), nu controls the inverse step (negative expansion), and iterations determines how many smoothing passes to apply. More iterations create smoother surfaces but may over-smooth fine features.

Default parameters:

  • Gaussian filter: sigma=1.0, threshold=0.5

  • Taubin smoothing: lamb=0.75, nu=0.6, iterations=100

These defaults work well for standard 1mm isotropic MNI space atlases. Adjust parameters based on your atlas resolution and desired smoothness.

Examples

Basic usage:

Generate surfaces for specific regions from a FreeSurfer aseg atlas:

>>> from netneurotools.plotting import _pv_make_subcortex_surfaces
>>> surfaces = _pv_make_subcortex_surfaces(
...     atlas="/path/to/aseg.nii.gz",
...     include_keys=[10, 11, 12, 13],  # thalamus, caudate, putamen, pallidum
... )

Custom smoothing parameters:

Create smoother surfaces by increasing Gaussian sigma:

>>> custom_params = {
...     "gaussian_filter": {"sigma": 1.5, "threshold": 0.5},
...     "taubin_smoothing": {"lamb": 0.75, "nu": 0.6, "iterations": 100}
... }
>>> surfaces = _pv_make_subcortex_surfaces(
...     atlas="/path/to/atlas.nii.gz",
...     include_keys=[1, 2, 3],
...     custom_params=custom_params
... )

Access individual surfaces:

The returned MultiBlock can be indexed by string keys:

>>> surfaces = _pv_make_subcortex_surfaces(
...     atlas="/path/to/atlas.nii.gz",
...     include_keys=[10, 11]
... )
>>> thalamus_mesh = surfaces['10']
>>> caudate_mesh = surfaces['11']

Saving generated surfaces:

The MultiBlock object can be saved to a file for later use:

>>> surfaces.save("subcortex_surfaces.vtm")

Note that the .vtm format preserves the MultiBlock structure. It consists of an XML file (.vtm) and associated vtk mesh files (.vtp) stored in a folder with the same name as the .vtm file.

To load the saved surfaces later: >>> import pyvista as pv # doctest: +SKIP >>> loaded_surfaces = pv.read(“subcortex_surfaces.vtm”) # doctest: +SKIP

Use with pv_plot_subcortex:

Generate custom surfaces and visualize them:

>>> from netneurotools.plotting import pv_plot_subcortex
>>> surfaces = _pv_make_subcortex_surfaces(
...     atlas="/path/to/custom_atlas.nii.gz",
...     include_keys=['1', '2', '3', '4']
... )
>>> parcel_data = {'1': 0.5, '2': 0.7, '3': 0.6, '4': 0.8}
>>> pl = pv_plot_subcortex(
...     parcel_data,
...     template="custom",
...     custom_surfaces=surfaces
... )