spectralbrain.BrainMesh#

class spectralbrain.BrainMesh(vertices, faces, metadata=None)[source]#

Bases: object

Triangle surface mesh for brain structures.

Implements the GeometricObject protocol and provides the Laplacian construction → eigendecomposition → descriptor pipeline.

Parameters:

  • vertices (ndarray, shape (N, 3)) – Vertex coordinates in mm.

  • faces (ndarray, shape (F, 3)) – Triangle indices, 0-indexed.

  • metadata (dict, optional) – Provenance (subject, hemisphere, structure, …).

Examples

>>> verts, faces = sb.io.load_freesurfer_surface("lh.white")
>>> mesh = BrainMesh(verts, faces, metadata={"structure": "cortex"})
>>> decomp = mesh.decompose(k=100)
__init__(vertices, faces, metadata=None)[source]#

Initialise from vertices and faces arrays.

Parameters:
Return type:

None

Methods

__init__(vertices, faces[, metadata])

Initialise from vertices and faces arrays.

boundary_vertices()

Indices of boundary (non-manifold edge) vertices.

casorati_curvature()

Casorati curvature — identical to curvedness.

compute_laplacian([method, ...])

Construct the Laplacian and mass matrix.

compute_normals()

Compute area-weighted per-vertex normals from face topology.

curvedness()

Koenderink Curvedness C ≥ 0.

decompose([k, laplacian_method, backend])

Compute the spectral decomposition.

edge_lengths()

All edge lengths.

euler_characteristic()

Euler characteristic χ = V − E + F.

gaussian_curvature()

Gaussian curvature via angle defect (Descartes–Euler).

genus()

Genus g from χ = 2 − 2g (closed surfaces).

geodesic_distance(source_indices, *[, ...])

Geodesic distance from source vertices to all others.

is_closed()

True if the mesh has no boundary.

laplacian_smooth([n_iterations, step_size])

Laplacian smoothing (uniform weights).

mean_curvature()

Mean curvature via the Laplacian (Hn = ΔX / 2).

principal_curvatures()

Principal curvatures κ₁ ≥ κ₂ from H and K.

quality_report()

Mesh quality summary.

shape_index()

Koenderink Shape Index S ∈ [−1, +1].

surface_area()

Total surface area in mm².

taubin_smooth([n_iterations, lambda_, mu])

Taubin smoothing (shrinkage-free).

vertex_areas([method])

Per-vertex area (Voronoi or barycentric lumped).

vertex_valence()

Number of edges incident to each vertex.

willmore_density()

Local Willmore energy density H²(v).

willmore_energy()

Total Willmore energy ∫ H² dA.

Attributes

coordinates

Return the vertex coordinates array.

n_faces

Return the number of triangular faces.

n_points

Return the number of vertices (alias for n_vertices).

n_vertices

Return the number of vertices in the mesh.
boundary_vertices()[source]#

Indices of boundary (non-manifold edge) vertices.

Returns:

ndarray of int – Vertex indices on the mesh boundary.

Return type:

ndarray

casorati_curvature()[source]#

Casorati curvature — identical to curvedness.

K_C = √((κ₁² + κ₂²) / 2)

Preferred over mean/Gaussian curvature for complexity quantification (Matsuyama et al. 2023).

Returns:

ndarray, shape (N,)

Return type:

ndarray[tuple[Any, …], dtype[floating]]

compute_laplacian(method='cotangent', *, robust_mollify_factor=1e-05)[source]#

Construct the Laplacian and mass matrix.

Parameters:

  • method (str) – "cotangent" — FEM cotangent-weighted Laplacian with Voronoi-area mass matrix (Meyer–Desbrun–Schröder–Barr). "robust" — Sharp & Crane tufted Laplacian via robust_laplacian (handles non-manifold edges).

  • robust_mollify_factor (float) – Mollification parameter for the robust method.

Returns:

  • L (SparseMatrix, shape (N, N)) – Stiffness (Laplacian) matrix — symmetric positive semi-definite.

  • M (MassMatrix, shape (N, N)) – Diagonal mass matrix.

Return type:

tuple[spmatrix, spmatrix]

compute_normals()[source]#

Compute area-weighted per-vertex normals from face topology.

Returns:

normals (ndarray, shape (N, 3)) – Unit normals.

Return type:

ndarray[tuple[Any, …], dtype[floating]]

curvedness()[source]#

Koenderink Curvedness C ≥ 0.

C = √((κ₁² + κ₂²) / 2)

Returns:

ndarray, shape (N,)

Return type:

ndarray[tuple[Any, …], dtype[floating]]

decompose(k=100, *, laplacian_method='cotangent', backend=None, **eigsh_kwargs)[source]#

Compute the spectral decomposition.

Parameters:

  • k (int) – Number of eigenpairs to compute.

  • laplacian_method (str) – Passed to compute_laplacian().

  • backend (Backend, optional) – Compute backend. Defaults to NumpyBackend.

  • **eigsh_kwargs – Extra arguments to backend.eigsh().

Returns:

SpectralDecomposition

Return type:

SpectralDecomposition

edge_lengths()[source]#

All edge lengths.

Returns:

ndarray, shape (E,)

Return type:

ndarray

euler_characteristic()[source]#

Euler characteristic χ = V − E + F.

Returns:

int

Return type:

int

gaussian_curvature()[source]#

Gaussian curvature via angle defect (Descartes–Euler).

K(v) = (2π − Σ θ_j) / A(v)

where θ_j are the face angles at vertex v and A(v) is the Voronoi area.

Returns:

ndarray, shape (N,) – Gaussian curvature in 1/mm².

Return type:

ndarray[tuple[Any, …], dtype[floating]]

genus()[source]#

Genus g from χ = 2 − 2g (closed surfaces).

Returns:

int

Return type:

int

geodesic_distance(source_indices, *, method='heat', t_factor=1.0)[source]#

Geodesic distance from source vertices to all others.

Parameters:

  • source_indices (ndarray) – Indices of source vertices.

  • method (str) – "heat" — Crane et al. heat method (smooth, O(N)). "dijkstra" — graph shortest path on edge graph (exact on graph, O(N log N)).

  • t_factor (float) – For the heat method: time-step multiplier relative to the squared mean edge length.

Returns:

distances (ndarray, shape (N,)) – Geodesic distance from the closest source vertex.

Return type:

ndarray[tuple[Any, …], dtype[floating]]

is_closed()[source]#

True if the mesh has no boundary.

Return type:

bool

laplacian_smooth(n_iterations=10, step_size=0.5)[source]#

Laplacian smoothing (uniform weights).

Parameters:

  • n_iterations (int)

  • step_size (float) – Damping factor (0–1).

Returns:

BrainMesh – New mesh with smoothed vertices.

Return type:

BrainMesh

mean_curvature()[source]#

Mean curvature via the Laplacian (Hn = ΔX / 2).

Requires the cotangent Laplacian and mass matrix.

Returns:

ndarray, shape (N,) – Mean curvature (signed) in 1/mm.

Return type:

ndarray[tuple[Any, …], dtype[floating]]

principal_curvatures()[source]#

Principal curvatures κ₁ ≥ κ₂ from H and K.

κ₁ = H + √(H² − K), κ₂ = H − √(H² − K)

Returns:

  • kappa1 (ndarray, shape (N,))

  • kappa2 (ndarray, shape (N,))

Return type:

tuple[ndarray[tuple[Any, …], dtype[floating]], ndarray[tuple[Any, …], dtype[floating]]]

quality_report()[source]#

Mesh quality summary.

Returns:

dict – Keys: n_vertices, n_faces, n_edges, euler, genus, is_closed, area, edge_length_{min,mean,max,std}, valence_{min,mean,max}, n_boundary_vertices.

Return type:

dict[str, Any]

shape_index()[source]#

Koenderink Shape Index S ∈ [−1, +1].

S = (2/π) · arctan((κ₂ + κ₁) / (κ₂ − κ₁))

Returns:

ndarray, shape (N,)

Return type:

ndarray[tuple[Any, …], dtype[floating]]

surface_area()[source]#

Total surface area in mm².

Return type:

float

taubin_smooth(n_iterations=10, lambda_=0.5, mu=-0.53)[source]#

Taubin smoothing (shrinkage-free).

Alternates positive and negative smoothing steps to avoid the volume shrinkage of pure Laplacian smoothing.

Parameters:

  • n_iterations (int) – Number of (λ, μ) cycles.

  • lambda (float) – Positive smoothing factor.

  • mu (float) – Negative (inflation) factor. Must satisfy mu < -lambda_ for shrinkage-free behaviour.

  • lambda_ (float)

Returns:

BrainMesh

Return type:

BrainMesh

vertex_areas(method='barycentric')[source]#

Per-vertex area (Voronoi or barycentric lumped).

Parameters:

method (str) – "barycentric" — A(v) = Σ_{t∈star(v)} area(t) / 3. "voronoi" — mixed Voronoi–barycentric (Meyer et al.).

Returns:

ndarray, shape (N,)

Return type:

ndarray[tuple[Any, …], dtype[floating]]

vertex_valence()[source]#

Number of edges incident to each vertex.

Returns:

ndarray, shape (N,), int

Return type:

ndarray

willmore_density()[source]#

Local Willmore energy density H²(v).

The integral ∫ H² dA is the Willmore energy — conformally invariant, measures deviation from a sphere.

Returns:

ndarray, shape (N,)

Return type:

ndarray[tuple[Any, …], dtype[floating]]

willmore_energy()[source]#

Total Willmore energy ∫ H² dA.

Returns:

float

Return type:

float

property coordinates: ndarray[tuple[Any, ...], dtype[floating]]#

Return the vertex coordinates array.

property n_faces: int#

Return the number of triangular faces.

property n_points: int#

Return the number of vertices (alias for n_vertices).

property n_vertices: int#

Return the number of vertices in the mesh.