spectralbrain.spectral.descriptors#
Spectral shape descriptors derived from the LBO eigenpairs.
Every function in this module consumes a
SpectralDecomposition and produces
a :pydata:`ScalarMap` (N,), :pydata:`DescriptorMatrix` (N, T),
or :pydata:`GlobalDescriptor` (d,).
Once the eigendecomposition is computed (the expensive step), all
descriptors are algebraically cheap — just array operations on
eigenvalues and eigenvectors.
Implemented descriptors#
ShapeDNA — eigenvalue fingerprint (Reuter et al. 2006)
HKS — Heat Kernel Signature (Sun, Ovsjanikov & Guibas 2009)
SI-HKS — Scale-Invariant HKS (Bronstein & Kokkinos 2010)
WKS — Wave Kernel Signature (Aubry, Schlickewei & Cremers 2011)
GPS — Global Point Signature (Rustamov 2007)
Bates SP — Symmetric Polynomial Signatures (Bates et al. 2011)
BKS — Biharmonic Kernel Signature (Lipman et al. 2010)
IBKS — Improved BKS (Zhang et al. 2024)
Functions
|
Compute all 8 spectral descriptors from one decomposition. |
|
Symmetric polynomial signatures — sign/ordering invariant. |
|
Biharmonic Kernel Signature — parameter-free per-vertex scalar. |
|
Global Point Signature — spectral embedding of the surface. |
|
Heat Kernel Signature — multi-scale per-vertex descriptor. |
|
Improved BKS with curvature-aware neighbourhood aggregation. |
|
ShapeDNA — the LBO eigenvalue fingerprint. |
|
Scale-Invariant HKS — removes scale dependence from HKS. |
|
Wave Kernel Signature — band-pass per-vertex descriptor. |
- spectralbrain.spectral.descriptors.compute_all_descriptors(decomp, *, hks_n_times=100, wks_n_energies=100, si_hks_n_freq=8, bates_order=2, bates_n_times=10, gaussian_curvature=None)[source]#
Compute all 8 spectral descriptors from one decomposition.
Efficient because the eigendecomposition (the expensive step) is shared. Each descriptor adds only O(N·k·T) work.
- Parameters:
- Returns:
dict of {str (ndarray}) – Keys:
"shapedna","hks","si_hks","wks","gps","bates_sp","bks","ibks".- Return type:
- spectralbrain.spectral.descriptors.compute_bates_signatures(decomp, t_values=None, *, n_times=10, order=2)[source]#
Symmetric polynomial signatures — sign/ordering invariant.
Construct weighted eigenfunctions w_j(x, t) = exp(-λ_j·t)·φ_j(x), then compute elementary symmetric polynomials e_p of the weights. These are provably invariant under sign flips and permutations of the eigenfunctions.
\[ \begin{align}\begin{aligned}e_1(x, t) &= \sum_j w_j(x, t) \quad \text{(= HKS)}\\e_2(x, t) &= \sum_{j < k} w_j(x, t)\, w_k(x, t)\\e_p(x, t) &= \sum_{j_1 < \cdots < j_p} \prod_{m=1}^{p} w_{j_m}(x, t)\end{aligned}\end{align} \]For order=2 via Newton’s identity: e_2 = (e_1² − Σ w_j²) / 2
- Parameters:
decomp (SpectralDecomposition)
t_values (ndarray, optional) – Time scales.
None= auto.n_times (int) – Number of auto time scales.
order (int) – Maximum order of symmetric polynomials (1, 2, or 3). Higher orders are more informative but O(k^order).
- Returns:
ndarray, shape (N, order × T) – Concatenated symmetric polynomial signatures across orders and time scales.
- Return type:
References
Bates J, Pafundi D, Kanel P, Liu X, Mio W. Spectral signatures of point clouds and applications to detection of Alzheimer’s disease through neuroimaging. IEEE ISBI 2011.
- spectralbrain.spectral.descriptors.compute_bks(decomp)[source]#
Biharmonic Kernel Signature — parameter-free per-vertex scalar.
Uses the biharmonic operator (Δ²) instead of the heat operator. Unlike HKS and WKS, BKS has no tuneable parameter — it is fully determined by the eigenpairs.
\[\text{BKS}(x) = \sum_{i=1}^{k} \frac{\varphi_i^2(x)}{\lambda_i^2}\]The 1/λ² weighting gives dominant weight to low-frequency modes (global shape).
- Parameters:
decomp (SpectralDecomposition)
- Returns:
ndarray, shape (N,) – Per-vertex BKS scalar.
- Return type:
References
Lipman Y, Rustamov RM, Funkhouser TA. Biharmonic distance. ACM Transactions on Graphics 29(3):27, 2010.
- spectralbrain.spectral.descriptors.compute_gps(decomp, *, skip_zero=True)[source]#
Global Point Signature — spectral embedding of the surface.
Embeds each point into a high-dimensional space where Euclidean distance equals diffusion distance (at t → ∞).
\[\text{GPS}(x) = \left( \frac{\varphi_1(x)}{\sqrt{\lambda_1}},\; \frac{\varphi_2(x)}{\sqrt{\lambda_2}},\; \ldots,\; \frac{\varphi_k(x)}{\sqrt{\lambda_k}} \right)\]Warning
GPS is not sign/ordering invariant. Eigenvectors have arbitrary sign (φ and −φ are both valid), so direct comparison between subjects requires sign alignment. For group-level analysis, prefer HKS or WKS which use φ² and are sign-invariant.
- Parameters:
decomp (SpectralDecomposition)
skip_zero (bool) – Exclude the constant eigenfunction (λ₀ ≈ 0).
- Returns:
ndarray, shape (N, d) – Spectral embedding. d = k−1 if skip_zero, else d = k.
- Return type:
References
Rustamov RM. Laplace–Beltrami eigenfunctions for deformation invariant shape representation. SGP 2007.
- spectralbrain.spectral.descriptors.compute_hks(decomp, t_values=None, *, n_times=100, normalize=False)[source]#
Heat Kernel Signature — multi-scale per-vertex descriptor.
The HKS measures how much heat remains at a point after diffusing for time t. Small t captures local geometry (curvature); large t captures global shape.
\[\text{HKS}(x, t) = \sum_{i=0}^{k-1} e^{-\lambda_i t}\, \varphi_i^2(x)\]- Parameters:
decomp (SpectralDecomposition)
t_values (ndarray, shape (T,), optional) – Time scales.
None= auto log-spaced from eigenvalues.n_times (int) – Number of auto time scales (ignored if t_values given).
normalize (bool) – If True, normalise each column (time slice) to unit L2 norm.
- Returns:
ndarray, shape (N, T) – HKS evaluated at each vertex and time.
- Return type:
References
Sun J, Ovsjanikov M, Guibas L. A concise and provably informative multi-scale signature based on heat diffusion. SGP 2009.
- spectralbrain.spectral.descriptors.compute_ibks(decomp, *, gaussian_curvature=None, alpha=0.1, k_neighbours=10)[source]#
Improved BKS with curvature-aware neighbourhood aggregation.
Augments BKS with Gaussian curvature information to improve stability at articulation points and high-curvature regions.
IBKS(x) = BKS(x) + α · mean_{y ∈ N(x)} |K(y)| · BKS(y)
where K is Gaussian curvature and N(x) is the k-nearest neighbourhood.
- Parameters:
decomp (SpectralDecomposition)
gaussian_curvature (ndarray, shape (N,), optional) – Pre-computed Gaussian curvature. If
None, the curvature term is approximated from the eigenvectors (less accurate but avoids requiring a mesh).alpha (float) – Blending weight for the curvature term.
k_neighbours (int) – Neighbourhood size for local aggregation.
- Returns:
ndarray, shape (N,) – Per-vertex IBKS.
- Return type:
References
Zhang Y et al. Improved biharmonic kernel signature for 3D non-rigid shape matching and retrieval. The Visual Computer 40:969–980, 2024.
- spectralbrain.spectral.descriptors.compute_shapedna(decomp, *, normalize='area', skip_zero=True)[source]#
ShapeDNA — the LBO eigenvalue fingerprint.
The simplest spectral descriptor: the truncated sequence of eigenvalues, optionally normalised for cross-subject comparison.
\[\text{ShapeDNA} = (\lambda_1, \lambda_2, \ldots, \lambda_k)\]- Parameters:
decomp (SpectralDecomposition) – Precomputed eigenpairs.
normalize (str) –
"none"— raw eigenvalues."area"— multiply by surface area (Reuter convention)."volume"— multiply by volume^{2/3}."fiedler"— divide by λ₁.skip_zero (bool) – Exclude λ₀ ≈ 0 (the constant mode).
- Returns:
ndarray, shape (d,) – Eigenvalue vector. d = k−1 if skip_zero, else d = k.
- Return type:
References
Reuter M, Wolter FE, Peinecke N. Laplace–Beltrami spectra as “Shape-DNA” of surfaces and solids. Computer-Aided Design 38(4):342–366, 2006.
- spectralbrain.spectral.descriptors.compute_si_hks(decomp, *, n_times=256, n_frequencies=8)[source]#
Scale-Invariant HKS — removes scale dependence from HKS.
Under uniform scaling β the HKS undergoes a log-time shift and amplitude change. SI-HKS eliminates both via:
Sample HKS at log-spaced times τ = log(t).
Take derivative w.r.t. τ (removes amplitude).
Apply DFT; keep modulus of first n_frequencies coefficients (removes shift).
\[\text{SI-HKS}(x) = \left| \mathcal{F}\left\{ \frac{\partial}{\partial \tau} \text{HKS}(x, e^\tau) \right\} \right|_{1:n}\]- Parameters:
decomp (SpectralDecomposition)
n_times (int) – Number of log-time samples (FFT input length). Power of 2 recommended.
n_frequencies (int) – Number of Fourier modulus coefficients to keep.
- Returns:
ndarray, shape (N, n_frequencies) – Scale-invariant spectral descriptor.
- Return type:
References
Bronstein MM, Kokkinos I. Scale-invariant heat kernel signatures for non-rigid shape recognition. CVPR 2010.
- spectralbrain.spectral.descriptors.compute_wks(decomp, e_values=None, *, n_energies=100, sigma=None, normalize=True)[source]#
Wave Kernel Signature — band-pass per-vertex descriptor.
Derived from the Schrödinger equation. Acts as a bank of band-pass filters in log-eigenvalue space, giving balanced weight to all spectral frequencies (unlike HKS which is low-pass).
\[\text{WKS}(x, e) = C_e \sum_{i=1}^{k} \varphi_i^2(x)\, \exp\!\left( -\frac{(e - \log\lambda_i)^2}{2\sigma^2} \right)\]where \(C_e\) normalises so the filter weights sum to 1.
- Parameters:
decomp (SpectralDecomposition)
e_values (ndarray, shape (E,), optional) – Log-energy levels.
None= auto from eigenvalues.n_energies (int) – Number of auto energy levels.
sigma (float, optional) – Gaussian bandwidth.
None= auto (Aubry convention).normalize (bool) – Normalise each energy slice to unit L2 norm.
- Returns:
ndarray, shape (N, E) – WKS evaluated at each vertex and energy level.
- Return type:
References
Aubry M, Schlickewei U, Cremers D. The wave kernel signature: a quantum mechanical approach to shape analysis. ICCV 2011.