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:

vertices (NDArray[floating])
faces (NDArray[int64])
metadata (dict[str, Any] | None)

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.
`from_volume`(volume, affine, *[, raw, label, ...])	Build a mesh from a (label) volume, improved by default for the LBO.
`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.

classmethod from_volume(volume, affine, *, raw=False, label=None, metadata=None, **kwargs)[source]#

Build a mesh from a (label) volume, improved by default for the LBO.

Thin wrapper over spectralbrain.io.meshing.volume_to_mesh(). With raw=False (default) the volume is turned into a well-conditioned, LBO-ready surface (sub-voxel iso-surface, topology cleanup, Taubin smoothing, isotropic remeshing). With raw=True it reproduces the legacy plain-marching-cubes path exactly.

Parameters:

volume (ndarray, shape (X, Y, Z)) – Intensity or integer-label volume.
affine (ndarray, shape (4, 4)) – Voxel-to-world affine.
raw (bool) – Skip the improvement pipeline (legacy behaviour) if True.
label (int or sequence of int, optional) – Restrict to these label id(s) before meshing.
metadata (dict, optional) – Provenance stored on the returned mesh.
**kwargs – Forwarded to volume_to_mesh() (e.g. closed, level, field_mode, taubin_iterations, remesh, target_edge_mm).

Returns:

BrainMesh

Return type:

BrainMesh

Examples

>>> seg, affine = sb.io.load_nifti("aseg.mgz")
>>> hippo = BrainMesh.from_volume(seg, affine, label=17)  # improved
>>> raw = BrainMesh.from_volume(seg, affine, label=17, raw=True)

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[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[floating]

curvedness()[source]#

Koenderink Curvedness C ≥ 0.

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

Returns:: ndarray, shape (N,)
Return type:: NDArray[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[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[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[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[floating], NDArray[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[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[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[floating]

willmore_energy()[source]#

Total Willmore energy ∫ H² dA.

Returns:: float
Return type:: float

property coordinates: NDArray[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.