spectralbrain.viz.geometry#

Geometry visualization subpackage — point clouds and meshes.

This subpackage provides 3D rendering functions for the two core geometric representations in SpectralBrain:

  • Point clouds (points module): atlas-free 3D scatter, MLS reconstruction, clustering, warping, Voronoi diagrams.

  • Meshes (meshes module): surface rendering, wireframe, curvature maps, multi-view panels, difference maps.

Both modules use vedo (VTK-based) as the primary renderer with optional fallbacks to Open3D (points) and PyVista (meshes).

Typical usage:

from spectralbrain.viz.geometry import (
    plot_point_cloud, plot_clusters, plot_mesh, plot_curvature,
)
spectralbrain.viz.geometry.plot_clusters(coords, labels, *, show_ellipsoids=True, ellipsoid_alpha=0.12, show_centroids=True, centroid_size=14, cmap='Set1', point_size=5, title=None, bg='white', size=(1600, 1200), scale=2, save=None)[source]#

Render clustered point cloud with per-cluster PCA ellipsoids.

Useful for visualising K-means, spectral clustering, or HDBSCAN results on subcortical point clouds.

Parameters:

  • coords ((N, 3) array) – Point positions.

  • labels ((N,) int array) – Cluster assignments (0-indexed).

  • show_ellipsoids (bool) – Overlay translucent PCA ellipsoids around each cluster.

  • ellipsoid_alpha (float) – Ellipsoid transparency (0 = invisible, 1 = opaque).

  • show_centroids (bool) – Mark cluster centroids with large dots.

  • centroid_size (int) – Centroid marker size in pixels.

  • cmap (str) – Categorical colourmap for cluster colouring.

  • point_size (int) – Point radius in pixels.

  • title (str or None) – Figure title.

  • bg (str) – Standard rendering parameters.

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

  • scale (int) – Standard rendering parameters.

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

Returns:

(Path, dict) – PNG path and metadata with 'n_clusters', 'cluster_sizes', 'cluster_centroids'.

Return type:

tuple[Path, dict[str, Any]]

spectralbrain.viz.geometry.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.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.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.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.plot_mls_reconstruction(coords, scalars=None, scalar_name='HKS', cmap=None, mls_factor=0.2, recon_dims=(80, 80, 80), point_size=4, bg='white', size=(2400, 800), scale=2, save=None)[source]#

Three-panel pipeline: raw → MLS-smoothed → reconstructed surface.

Demonstrates the atlas-free mesh generation pipeline used when no a priori mesh connectivity is available (e.g., thalamic nuclei from point-cloud segmentation).

Parameters:

  • coords ((N, 3) array) – Raw point cloud coordinates.

  • scalars ((N,) array or None) – Optional per-point scalar for colourmap.

  • scalar_name (str) – Scalar label for colourbar and cmap lookup.

  • cmap (str or None) – Colourmap name (auto-resolved if None).

  • mls_factor (float) – MLS smoothing factor (fraction of bounding box diagonal).

  • recon_dims ((int, int, int)) – Grid resolution for Poisson surface reconstruction.

  • point_size (int) – Point radius in screen pixels.

  • bg (str) – Background colour.

  • size ((int, int)) – Window size in pixels — wider to accommodate 3 panels.

  • scale (int) – Screenshot scale factor.

  • save (path or None) – Output PNG path.

Returns:

(Path, dict) – PNG path and metadata with 'n_points', 'n_mesh_vertices', 'n_mesh_faces'.

Return type:

tuple[Path, dict[str, Any]]

spectralbrain.viz.geometry.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.plot_point_cloud(coords, scalars=None, scalar_name='HKS', cmap=None, vmin=None, vmax=None, point_size=6, title=None, camera=None, show_scalarbar=True, bg='white', size=(1600, 1200), scale=2, save=None)[source]#

Render a 3D point cloud coloured by a scalar descriptor.

This is the workhorse visualisation for atlas-free analyses: thalamic nuclei point clouds, hippocampal point clouds, or any subcortical structure where no mesh connectivity is available.

Parameters:

  • coords ((N, 3) array) – Point positions in mm (RAS or scanner space).

  • scalars ((N,) array or None) – Per-point scalar values for colouring. If None the cloud is rendered in uniform grey.

  • scalar_name (str) – Human-readable name used for the colourbar title and for automatic colourmap selection when cmap is None.

  • cmap (str or None) – Matplotlib colourmap name. None → auto from scalar_name.

  • vmin (float or None) – Colour range limits. None → auto from data percentiles.

  • vmax (float or None) – Colour range limits. None → auto from data percentiles.

  • point_size (int) – Point radius in screen pixels.

  • title (str or None) – Title text rendered on the image.

  • camera (dict or None) – Camera config: {'pos', 'focal_point', 'viewup'}.

  • show_scalarbar (bool) – Whether to display a colourbar legend.

  • bg (str) – Background colour.

  • size ((int, int)) – Window size in pixels (width, height).

  • scale (int) – Screenshot scale multiplier.

  • save (path or None) – Output PNG path. None → auto temp file.

Returns:

(Path, dict) – Path to the saved PNG and metadata dict with keys 'n_points', 'scalar_range', 'cmap'.

Return type:

tuple[Path, dict[str, Any]]

spectralbrain.viz.geometry.plot_point_cloud_o3d(coords, scalars=None, cmap='inferno', point_size=2.0, width=1600, height=1200, save=None)[source]#

Minimal Open3D point cloud render (fallback when vedo unavailable).

Parameters:

  • coords ((N, 3) array) – Point positions.

  • scalars ((N,) array or None) – Per-point scalar for colourmap.

  • cmap (str) – Matplotlib colourmap name.

  • point_size (float) – Point size.

  • width (int) – Image dimensions.

  • height (int) – Image dimensions.

  • save (path or None) – Output PNG path.

Returns:

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

Return type:

Path | None

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

Multi-panel point cloud comparison.

Each panel is a dict with keys:

  • 'coords' : (N, 3) array (required)

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

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

  • 'cmap' : str or None

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

  • 'point_size' : int (default 5)

  • 'title' : str (default '')

Parameters:

  • panels (list of dict) – One dict per panel.

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

  • bg (str) – Background colour.

  • size ((int, int) or None) – Total window size. None → 800px × n_cols by 800px × n_rows.

  • scale (int) – Screenshot scale.

  • save (path or None) – Output PNG path.

Returns:

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

Return type:

tuple[Path, dict[str, Any]]

spectralbrain.viz.geometry.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.plot_voronoi(coords, scalars=None, scalar_name='cluster', cmap=None, *, projection='xy', padding=0.1, wireframe_color='black', wireframe_width=1, point_size=8, bg='white', size=(1600, 1200), scale=2, save=None)[source]#

Voronoi tessellation of a point cloud projected onto a 2D plane.

Particularly useful for spatial domain analysis of thalamic nuclei or hippocampal subfield parcellations in the unfolded space.

Parameters:

  • coords ((N, 3) or (N, 2) array) – Point positions. 3D points are projected onto projection.

  • scalars ((N,) array or None) – Per-point values for cell colouring.

  • scalar_name (str) – Scalar label for colourbar and cmap lookup.

  • cmap (str or None) – Colourmap name.

  • projection ({'xy', 'xz', 'yz'}) – Projection plane for 3D → 2D.

  • padding (float) – Voronoi cell boundary padding.

  • wireframe_color (str) – Cell boundary line colour.

  • wireframe_width (int) – Cell boundary line width.

  • point_size (int) – Overlay point size.

  • bg (str) – Standard rendering parameters.

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

  • scale (int) – Standard rendering parameters.

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

Returns:

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

Return type:

tuple[Path, dict[str, Any]]

spectralbrain.viz.geometry.plot_warp(source, target, sigma=1.0, *, show_displacement=True, source_color='steelblue', target_color='tomato', warped_color='gold', point_size=5, arrow_scale=0.3, title=None, bg='white', size=(2400, 800), scale=2, save=None)[source]#

Visualise thin-plate spline warp between two point clouds.

Three panels: source cloud, target cloud, and warped result with displacement arrows overlaid.

Parameters:

  • source ((N, 3) array) – Source (reference) point cloud.

  • target ((N, 3) array) – Target point cloud — must have same N as source for the TPS warp to be meaningful.

  • sigma (float) – TPS stiffness parameter.

  • show_displacement (bool) – Overlay arrows from source to warped positions.

  • source_color (str) – Point cloud colours for each panel.

  • target_color (str) – Point cloud colours for each panel.

  • warped_color (str) – Point cloud colours for each panel.

  • point_size (int) – Point size in pixels.

  • arrow_scale (float) – Arrow length multiplier.

  • title (str or None) – Figure title.

  • bg (str) – Standard rendering parameters.

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

  • scale (int) – Standard rendering parameters.

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

Returns:

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

Return type:

tuple[Path, dict[str, Any]]

spectralbrain.viz.geometry.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]]

Modules

meshes

3D mesh rendering with vedo and optional PyVista fallback.

points

Point cloud visualization with vedo and Open3D.