spectralbrain.viz.geometry.meshes#

3D mesh rendering with vedo and optional PyVista fallback.

This module handles publication-quality 3D renders of triangular meshes for SpectralBrain’s mesh-based analysis pathway. It complements points.py (which handles atlas-free point clouds) by covering scenarios where mesh connectivity is available — either from FreeSurfer surface files, HippUnfold outputs, or reconstructed from point clouds via Poisson / Delaunay.

The six figure types cover the critical mesh visual outputs:

  1. Surface render — smooth-shaded mesh with optional scalar overlay (HKS, WKS, thickness, curvature).

  2. Wireframe render — mesh topology visualisation for QC and methods figures.

  3. Curvature map — Gaussian, mean, principal curvatures computed and displayed directly on the mesh surface.

  4. Multi-view panel — same mesh from multiple camera angles (anterior, posterior, lateral, medial, superior, inferior).

  5. Mesh comparison — side-by-side panels comparing two or more meshes (e.g., left vs right hemisphere, patient vs control).

  6. Scalar difference map — vertex-wise difference between two meshes overlaid as a diverging colourmap.

All functions follow the SpectralBrain convention: return (Path, metadata_dict) for vedo-based renders.

Functions

plot_curvature(vertices, faces[, method, ...])

Compute and render curvature on a mesh surface.

plot_mesh(vertices, faces[, scalars, ...])

Render a triangular mesh with optional scalar overlay.

plot_mesh_comparison(meshes, *[, shape, bg, ...])

Side-by-side comparison of multiple meshes.

plot_mesh_pyvista(vertices, faces[, ...])

Minimal PyVista mesh render (fallback when vedo unavailable).

plot_multi_view(vertices, faces[, scalars, ...])

Multi-view panel showing the same mesh from different angles.

plot_scalar_difference(vertices, faces, ...)

Vertex-wise scalar difference map between two conditions.

plot_wireframe(vertices, faces, *[, color, ...])

Wireframe render of a mesh for topology inspection.
spectralbrain.viz.geometry.meshes.plot_curvature(vertices, faces, method='mean', *, cmap='RdBu_r', vmin=None, vmax=None, symmetric=True, title=None, bg='white', size=(1600, 1200), scale=2, save=None)[source]#

Compute and render curvature on a mesh surface.

Computes curvature using VTK’s built-in estimator and immediately displays it with a diverging colourmap centred on zero.

Parameters:

  • vertices ((V, 3) array)

  • faces ((F, 3) array)

  • method ({'gaussian', 'mean', 'maximum', 'minimum'}) – Curvature type.

  • cmap (str) – Colourmap (diverging recommended for curvature).

  • vmin (float or None) – Colour range. If symmetric is True and these are None, range is set to ± 95th percentile.

  • vmax (float or None) – Colour range. If symmetric is True and these are None, range is set to ± 95th percentile.

  • symmetric (bool) – Centre the colourmap on zero.

  • title (str | None) – Standard render parameters.

  • bg (str) – Standard render parameters.

  • size (tuple[int, int]) – Standard render parameters.

  • scale (int) – Standard render parameters.

  • save (str | PathLike | None) – Standard render parameters.

Returns:

(Path, dict) – PNG path and metadata with 'curvature_method', 'curvature_stats' (mean, std, min, max).

Return type:

tuple[Path, dict[str, Any]]

spectralbrain.viz.geometry.meshes.plot_mesh(vertices, faces, scalars=None, scalar_name='HKS', cmap=None, vmin=None, vmax=None, color='gold', alpha=1.0, show_edges=False, edge_color='gray', edge_width=0.3, show_scalarbar=True, lighting='default', camera=None, title=None, bg='white', size=(1600, 1200), scale=2, save=None)[source]#

Render a triangular mesh with optional scalar overlay.

This is the primary mesh visualisation: a smooth Phong-shaded surface optionally coloured by a per-vertex spectral descriptor, morphometric measure, or statistical map.

Parameters:

  • vertices ((V, 3) array) – Mesh vertex coordinates.

  • faces ((F, 3) array) – Triangle index array.

  • scalars ((V,) array or None) – Per-vertex scalar values. None → uniform color.

  • scalar_name (str) – Label for colourbar and automatic cmap selection.

  • cmap (str or None) – Colourmap. None → auto from scalar_name.

  • vmin (float or None) – Colour range. None → 1st / 99th percentiles.

  • vmax (float or None) – Colour range. None → 1st / 99th percentiles.

  • color (str) – Uniform mesh colour when scalars is None.

  • alpha (float) – Mesh opacity (0–1).

  • show_edges (bool) – Overlay wireframe edges.

  • edge_color (str, float) – Edge appearance.

  • edge_width (str, float) – Edge appearance.

  • show_scalarbar (bool) – Display colourbar.

  • lighting (str) – VTK lighting style — 'default', 'metallic', 'plastic', 'shiny', 'glossy'.

  • camera (dict or None) – Camera configuration (pos, focal_point, viewup).

  • title (str or None) – Figure title.

  • bg (str) – Standard render parameters.

  • size (tuple[int, int]) – Standard render parameters.

  • scale (int) – Standard render parameters.

  • save (str | PathLike | None) – Standard render parameters.

Returns:

(Path, dict) – PNG path and metadata with 'n_vertices', 'n_faces', 'scalar_range', 'cmap'.

Return type:

tuple[Path, dict[str, Any]]

spectralbrain.viz.geometry.meshes.plot_mesh_comparison(meshes, *, shape=None, bg='white', size=None, scale=2, save=None)[source]#

Side-by-side comparison of multiple meshes.

Each element in meshes is a dict with keys:

  • 'vertices' : (V, 3) array (required)

  • 'faces' : (F, 3) array (required)

  • 'scalars' : (V,) array or None

  • 'scalar_name' : str (default 'value')

  • 'cmap' : str or None

  • 'vmin', 'vmax' : float or None

  • 'color' : str (default 'gold')

  • 'title' : str (default '')

Parameters:

  • meshes (list of dict) – One dict per mesh panel.

  • shape ((rows, cols) or None) – Grid layout. None → single row.

  • bg (str) – Standard render parameters.

  • size (tuple[int, int] | None) – Standard render parameters.

  • scale (int) – Standard render parameters.

  • save (str | PathLike | None) – Standard render parameters.

Returns:

(Path, dict) – PNG path and metadata with 'n_panels'.

Return type:

tuple[Path, dict[str, Any]]

spectralbrain.viz.geometry.meshes.plot_mesh_pyvista(vertices, faces, scalars=None, cmap='viridis', *, show_edges=False, window_size=(1600, 1200), save=None)[source]#

Minimal PyVista mesh render (fallback when vedo unavailable).

Parameters:

  • vertices ((V, 3) array)

  • faces ((F, 3) array)

  • scalars ((V,) array or None)

  • cmap (str)

  • show_edges (bool)

  • window_size ((int, int))

  • save (path or None)

Returns:

Path or None – Output path if successful, None otherwise.

Return type:

Path | None

spectralbrain.viz.geometry.meshes.plot_multi_view(vertices, faces, scalars=None, scalar_name='HKS', cmap=None, vmin=None, vmax=None, views=None, *, color='gold', lighting='default', bg='white', size=None, scale=2, save=None)[source]#

Multi-view panel showing the same mesh from different angles.

Renders the same mesh (optionally with scalar overlay) in a 1×N panel strip. Standard views: anterior, posterior, lateral, medial, superior, inferior.

Parameters:

  • vertices ((V, 3) array)

  • faces ((F, 3) array)

  • scalars ((V,) array or None)

  • scalar_name (str)

  • cmap (str or None)

  • vmin (float or None)

  • vmax (float or None)

  • views (list of str or None) – Camera preset names from CAMERA_PRESETS. None defaults to ['left_lateral', 'anterior', 'superior', 'right_lateral'].

  • color (str) – Uniform colour when scalars is None.

  • lighting (str) – VTK lighting preset.

  • bg (str) – Standard render parameters.

  • size (tuple[int, int] | None) – Standard render parameters.

  • scale (int) – Standard render parameters.

  • save (str | PathLike | None) – Standard render parameters.

Returns:

(Path, dict) – PNG path and metadata.

Return type:

tuple[Path, dict[str, Any]]

spectralbrain.viz.geometry.meshes.plot_scalar_difference(vertices, faces, scalars_a, scalars_b, *, label_a='A', label_b='B', diff_cmap='RdBu_r', symmetric=True, show_individual=True, individual_cmap=None, bg='white', size=None, scale=2, save=None)[source]#

Vertex-wise scalar difference map between two conditions.

Computes scalars_a - scalars_b and displays the difference on the mesh surface with a diverging colourmap centred on zero. Optionally shows individual maps alongside.

Parameters:

  • vertices ((V, 3) array)

  • faces ((F, 3) array)

  • scalars_a ((V,) arrays) – Per-vertex values for conditions A and B.

  • scalars_b ((V,) arrays) – Per-vertex values for conditions A and B.

  • label_a (str) – Labels for panels.

  • label_b (str) – Labels for panels.

  • diff_cmap (str) – Colourmap for the difference (diverging recommended).

  • symmetric (bool) – Centre the difference colourmap on zero.

  • show_individual (bool) – Show A and B alongside the difference (3-panel layout).

  • individual_cmap (str or None) – Colourmap for individual panels. None → ‘viridis’.

  • bg (str) – Standard render parameters.

  • size (tuple[int, int] | None) – Standard render parameters.

  • scale (int) – Standard render parameters.

  • save (str | PathLike | None) – Standard render parameters.

Returns:

(Path, dict) – PNG path and metadata with 'diff_stats'.

Return type:

tuple[Path, dict[str, Any]]

spectralbrain.viz.geometry.meshes.plot_wireframe(vertices, faces, *, color='steelblue', linewidth=0.5, alpha=1.0, camera=None, title=None, bg='white', size=(1600, 1200), scale=2, save=None)[source]#

Wireframe render of a mesh for topology inspection.

Useful for QC of reconstructed surfaces and for methods figures that need to show mesh structure clearly.

Parameters:

  • vertices ((V, 3) array)

  • faces ((F, 3) array)

  • color (str) – Wire colour.

  • linewidth (float) – Wire thickness.

  • alpha (float) – Opacity.

  • camera (dict[str, Any] | None) – Standard render parameters.

  • title (str | None) – Standard render parameters.

  • bg (str) – Standard render parameters.

  • size (tuple[int, int]) – Standard render parameters.

  • scale (int) – Standard render parameters.

  • save (str | PathLike | None) – Standard render parameters.

Returns:

(Path, dict) – PNG path and metadata.

Return type:

tuple[Path, dict[str, Any]]