spectralbrain.viz.geometry.points#

Point cloud visualization with vedo and Open3D.

This module provides publication-quality 3D renders of point clouds used throughout SpectralBrain’s atlas-free analysis pipeline. Every function produces a headless offscreen render and saves to PNG at 600 DPI-equivalent resolution. An optional Open3D fallback is available for environments without VTK.

The six main figure types cover the critical visual outputs of the SpectralBrain point cloud pathway:

  1. Scalar scatter — 3D point cloud coloured by a spectral descriptor (HKS, WKS, curvature, cluster label).

  2. MLS reconstruction — raw cloud → smoothed → reconstructed surface, showing the atlas-free mesh generation pipeline.

  3. Cluster overlay — K-means or spectral clusters with per-cluster PCA ellipsoids and centroids.

  4. Multi-panel comparison — side-by-side panels comparing descriptors, subjects, or hemispheres.

  5. Warp / morphing — source → target deformation field, useful for longitudinal or group template analyses.

  6. Voronoi diagram — Voronoi tessellation of a projected point cloud, coloured by cluster or scalar.

All functions follow the SpectralBrain convention: (fig_or_path, metadata_dict) return. For vedo-based renders the first element is the output PNG path (a pathlib.Path); for matplotlib composites it is (fig, ax) as usual.

Functions

plot_clusters(coords, labels, *[, ...])

Render clustered point cloud with per-cluster PCA ellipsoids.

plot_mls_reconstruction(coords[, scalars, ...])

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

plot_point_cloud(coords[, scalars, ...])

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

plot_point_cloud_o3d(coords[, scalars, ...])

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

plot_point_cloud_panel(panels, *[, shape, ...])

Multi-panel point cloud comparison.

plot_voronoi(coords[, scalars, scalar_name, ...])

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

plot_warp(source, target[, sigma, ...])

Visualise thin-plate spline warp between two point clouds.
spectralbrain.viz.geometry.points.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.points.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.points.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.points.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.points.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.points.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.points.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]]