geomfum.wrap package

Submodules

geomfum.wrap.diffusionnet module

Implementation of the DiffusionNet feature extractor for 3D shapes.

References

..DiffusionNet: Discretization Agnostic Learning on Surfaces Nicholas Sharp, Souhaib Attaiki, Keenan Crane, Maks Ovsjanikov https://arxiv.org/abs/2012.00888 ..https://github.com/dongliangcao/Self-Supervised-Multimodal-Shape-Matching by Dongliang Cao ..https://github.com/nmwsharp/diffusion-net

class geomfum.wrap.diffusionnet.BaseFeatureExtractor

Bases: ABC

Abstract base class for neural network feature extractors.

load_from_path(path)

Load model parameters from the provided file path.

Parameters:

path (str) – Path to the saved model parameters

save(path)

Save model parameters to the specified file path.

Parameters:

path (str) – Path to the saved model parameters

class geomfum.wrap.diffusionnet.DiffusionNet(in_channels, out_channels, hidden_channels=128, n_block=4, last_activation=None, mlp_hidden_channels=None, output_at='vertices', dropout=True, with_gradient_features=True, with_gradient_rotations=True, diffusion_method='spectral', k_eig=128, cache_dir=None)

Bases: Module

DiffusionNet: stacked of DiffusionBlocks.

Parameters:

• in_channels (int) – Number of input channels.

• out_channels (int) – Number of output channels.

• hidden_channels (int) – Number of hidden channels in diffusion block. Default 128.

• n_block (int) – Number of diffusion blocks. Default 4.

• last_activation (nn.Module or None) – Output layer. Default None.

• mlp_hidden_channels (List or None) – MLP hidden layers. Default None means [hidden_channels, hidden_channels].

• output_at (str) – Produce outputs at various mesh elements by averaging from vertices. One of [‘vertices’, ‘edges’, ‘faces’, ‘global_mean’]. Default ‘vertices’.

• dropout (bool) – Whether use dropout in mlp. Default True.

• with_gradient_features (bool) – Whether use SpatialGradientFeatures in DiffusionBlock. Default True.

• with_gradient_rotations (bool) – Whether use gradient rotations in SpatialGradientFeatures. Default True.

• diffusion_method (str) – Diffusion method applied in diffusion layer. One of [‘spectral’, ‘implicit_dense’]. Default ‘spectral’.

• k_eig (int) – Number of eigenvalues/eigenvectors to compute diffusion. Default 128.

• cache_dir (str or None) – Cache dir contains all pre-computed spectral operators. Default None.

forward(verts, faces=None, feats=None, frames=None, mass=None, L=None, evals=None, evecs=None, gradX=None, gradY=None)

Compute the forward pass of the DiffusionNet.

Parameters:

• verts (torch.Tensor) – Input vertices [B, V, 3].

• faces (torch.Tensor, optional) – Input faces [B, F, 3]. Default None.

• feats (torch.Tensor, optional) – Input features. Default None.

• frames (torch.Tensor) – Tangent frames for vertices.

• mass (torch.Tensor) – Diagonal elements in mass matrix.

• L (torch.SparseTensor) – Sparse Laplacian matrix.

• evals (torch.Tensor) – Eigenvalues of Laplacian Matrix.

• evecs (torch.Tensor) – Eigenvectors of Laplacian Matrix.

• gradX (torch.SparseTensor) – Real part of gradient matrix.

• gradY (torch.SparseTensor) – Imaginary part of gradient matrix.

Returns:

torch.Tensor – Output features.

class geomfum.wrap.diffusionnet.DiffusionNetBlock(in_channels, mlp_hidden_channels, dropout=True, diffusion_method='spectral', with_gradient_features=True, with_gradient_rotations=True)

Bases: Module

Building Block of DiffusionNet.

Parameters:

• in_channels (int) – Number of input channels.

• mlp_hidden_channels (List) – List of mlp hidden channels.

• dropout (bool) – Whether use dropout in MLP. Default True.

• diffusion_method (str) – Method for diffusion. Default “spectral”.

• with_gradient_features (bool) – Whether use spatial gradient feature. Default True.

• with_gradient_rotations (bool) – Whether use spatial gradient rotation. Default True.

forward(feat_in, mass, L, evals, evecs, gradX, gradY)

Compute the forward pass of the diffusion block.

Parameters:

• feat_in (torch.Tensor) – Input feature vector [B, V, C].

• mass (torch.Tensor) – Diagonal elements of mass matrix [B, V].

• L (torch.SparseTensor) – Sparse Laplacian matrix [B, V, V].

• evals (torch.Tensor) – Eigenvalues of Laplacian Matrix [B, K].

• evecs (torch.Tensor) – Eigenvectors of Laplacian Matrix [B, V, K].

• gradX (torch.SparseTensor) – Real part of gradient matrix [B, V, V].

• gradY (torch.SparseTensor) – Imaginary part of gradient matrix [B, V, V].

Returns:

torch.Tensor – Output feature vector.

class geomfum.wrap.diffusionnet.DiffusionnetFeatureExtractor(in_channels=3, out_channels=128, hidden_channels=128, n_block=4, last_activation=None, mlp_hidden_channels=None, output_at='vertices', dropout=True, with_gradient_features=True, with_gradient_rotations=True, diffusion_method='spectral', k=128, cache_dir=None, device=device(type='cpu'), descriptor=None)

Bases: BaseFeatureExtractor, Module

Feature extractor that uses DiffusionNet for geometric deep learning on 3D mesh data.

Parameters:

• in_channels (int) – Number of input feature channels (e.g., 3 for xyz). Default is 3.

• out_channels (int) – Number of output feature channels. Default is 128.

• hidden_channels (int) – Number of hidden channels in the network. Default is 128.

• n_block (int) – Number of DiffusionNet blocks. Default is 4.

• last_activation (nn.Module or None) – Activation function applied to the output. Default is None.

• mlp_hidden_channels (List[int] or None) – Hidden layer sizes in the MLP blocks. Default is None.

• output_at (str) – Output type — one of [‘vertices’, ‘edges’, ‘faces’, ‘global_mean’]. Default is ‘vertices’.

• dropout (bool) – Whether to apply dropout in MLP layers. Default is True.

• with_gradient_features (bool) – Whether to compute and include spatial gradient features. Default is True.

• with_gradient_rotations (bool) – Whether to use gradient rotations in spatial features. Default is True.

• diffusion_method (str) – Diffusion method used — one of [‘spectral’, ‘implicit_dense’]. Default is ‘spectral’.

• k (int) – Number of eigenvectors/eigenvalues used for spectral diffusion. Default is 128.

• cache_dir (str or None) – Path to cache directory for storing/loading spectral operators. Default is None.

• device (torch.device) – Device to run the model on. Default is CPU.

• descriptor (Descriptor or None) – Optional descriptor to compute input features. If None, uses vertex coordinates.

property device

Device inferred from model parameters, stays in sync with .to() calls.

forward(shape)

Call pass through the DiffusionNet model.

Parameters:

shape (Shape) – A shape object.

Returns:

torch.Tensor – Extracted feature tensor of shape [1, V, out_channels].

class geomfum.wrap.diffusionnet.LearnedTimeDiffusion(in_channels, method='spectral')

Bases: Module

Applied diffusion with learned time per-channel.

In the spectral domain this becomes f_out = e ^ (lambda_i * t) * f_in

Parameters:

• in_channels (int) – Number of input channels.

• method (str) – Method to perform time diffusion. Default ‘spectral’.

forward(feat, L, mass, evals, evecs)

Forward pass of the diffusion layer.

Parameters:

• feat (torch.Tensor) – Feature vector [B, V, C].

• L (torch.SparseTensor) – Sparse Laplacian matrix [B, V, V].

• mass (torch.Tensor) – Diagonal elements in mass matrix [B, V].

• evals (torch.Tensor) – Eigenvalues of Laplacian matrix [B, K].

• evecs (torch.Tensor) – Eigenvectors of Laplacian matrix [B, V, K].

Returns:

feat_diffuse (torch.Tensor) – Diffused feature vector [B, V, C].

class geomfum.wrap.diffusionnet.MiniMLP(layer_sizes, dropout=False, activation=<class 'torch.nn.modules.activation.ReLU'>, name='miniMLP')

Bases: Sequential

A simple MLP with configurable hidden layer sizes.

Parameters:

• layer_sizes (List) – List of layer size.

• dropout (bool) – Whether use dropout. Default False.

• activation (nn.Module) – Activation function. Default ReLU.

• name (str) – Module name. Default ‘miniMLP’

class geomfum.wrap.diffusionnet.SpatialGradientFeatures(in_channels, with_gradient_rotations=True)

Bases: Module

Compute dot-products between input vectors. Uses a learned complex-linear layer to keep dimension down.

Parameters:

• in_channels (int) – Number of input channels.

• with_gradient_rotations (bool) – Whether with gradient rotations. Default True.

forward(feat_in)

Compute the spatial gradient features.

Parameters:

feat_in (torch.Tensor) – Input feature vector (B, V, C, 2).

Returns:

feat_out (torch.Tensor) – Output feature vector (B, V, C)

class geomfum.wrap.diffusionnet.TriangleMesh(vertices, faces)

Bases: Shape

Triangulated surface mesh with vertices, faces, and differential operators.

Parameters:

• vertices (array-like, shape=[n_vertices, 3]) – Vertices of the mesh.

• faces (array-like, shape=[n_faces, 3]) – Faces of the mesh.

property dist_matrix

Pairwise distances between all vertices using the equipped metric.

Returns:

_dist_matrix (array-like, shape=[n_vertices, n_vertices]) – Metric distance matrix.

property edge_tangent_vectors

Edge vectors projected onto local tangent planes.

Returns:

edge_tangent_vectors (array-like, shape=[n_edges, 2]) – Tangent vectors of the edges, projected onto the local tangent plane.

property edges

Edges of the mesh.

Returns:

edges (array-like, shape=[n_edges, 2])

equip_with_metric(metric)

Equip mesh with a distance metric.

Parameters:

metric (class) – A metric class to use for the mesh.

property face_area_vectors

Face area vectors (unnormalized normals with magnitude equal to face area).

Returns:

area_vectors (array-like, shape=[n_faces, 3]) – Per-face area vectors.

property face_areas

Area of each triangular face.

Returns:

face_areas (array-like, shape=[n_faces]) – Per-face areas.

property face_normals

Unit normal vectors for each face.

Returns:

normals (array-like, shape=[n_faces, 3]) – Per-face normals.

property face_vertex_coords

Extract vertex coordinates corresponding to each face.

Returns:

vertices (array-like, shape=[{n_faces}, n_per_face_vertex, 3]) – Coordinates of the ith vertex of that face.

classmethod from_file(filename)

Load mesh from file.

Parameters:

filename (str) – Path to the mesh file.

Returns:

mesh (TriangleMesh) – A triangle mesh.

property n_faces

Number of faces.

Returns:

n_faces (int)

property n_vertices

Number of vertices.

Returns:

n_vertices (int)

property vertex_areas

Area associated with each vertex (one-third of adjacent triangle areas).

Returns:

vertex_areas (array-like, shape=[n_vertices]) – Per-vertex areas.

property vertex_normals

Unit normal vectors at vertices (area-weighted average of adjacent face normals).

Returns:

normals (array-like, shape=[n_vertices, 3]) – Normalized per-vertex normals.

property vertex_tangent_frames

Local orthonormal coordinate frames at each vertex.

Returns:

tangent_frame (array-like, shape=[n_vertices, 3, 3]) – Tangent frame of the mesh, where: - [n_vertices, 0, :] are the X basis vectors - [n_vertices, 1, :] are the Y basis vectors - [n_vertices, 2, :] are the vertex normals

geomfum.wrap.igl module

Igl wrapper.

class geomfum.wrap.igl.BaseLaplacianFinder

Bases: ABC

Algorithm to find the Laplacian.

class geomfum.wrap.igl.IglMeshLaplacianFinder

Bases: BaseLaplacianFinder

Algorithm to find the Laplacian of a mesh.

geomfum.wrap.pointnet module

Wrap for PointNet feature extractor.

References

Qi, C. R., Su, H., Mo, K., & Guibas, L. J. (2017). PointNet: Deep learning on point sets for 3D classification and segmentation. In Proceedings of the IEEE conference on computer vision and pattern recognition (pp. 652-660). Qi, C. R., Su, H., Yi, L., & Guibas, L. J. (2017). PointNet++: Deep hierarchical feature learning on point sets in a metric space. In Advances in neural information processing systems (pp. 5098-5108). riccardomarin/Diff-FMaps by Riccardo Marin

class geomfum.wrap.pointnet.BaseFeatureExtractor

Bases: ABC

Abstract base class for neural network feature extractors.

load_from_path(path)

Load model parameters from the provided file path.

Parameters:

path (str) – Path to the saved model parameters

save(path)

Save model parameters to the specified file path.

Parameters:

path (str) – Path to the saved model parameters

class geomfum.wrap.pointnet.PointNet(in_channels=3, conv_channels=[64, 64, 128, 128, 1024], mlp_dims=[1024, 256, 256], head_channels=[512, 256, 256], out_features=128, dropout=0.3)

Bases: Module

Full PointNet model with feature head.

Parameters:

• conv_channels (list of int) – Output dimensions of initial PointNet convolution layers.

• mlp_dims (list of int) – Hidden dimensions of global MLP applied to global features.

• head_channels (list of int) – Output dimensions of the feature head layers.

• out_features (int) – Final number of output features per point.

• dropout (float) – Dropout rate applied before the final layer.

forward(x)

Forward pass of the PointNet model.

Parameters:

x (torch.Tensor) – Input point cloud of shape (B, 3, N).

Returns:

torch.Tensor – Per-point feature embeddings of shape (B, N, out_features).

class geomfum.wrap.pointnet.PointNetfeat(in_channels=3, conv_channels=[64, 64, 128, 128, 1024], mlp_dims=[1024, 256, 256])

Bases: Module

PointNet local and global feature extractor.

Parameters:

• conv_channels (list of int) – List of output dimensions for each 1D convolution layer.

• mlp_dims (list of int) – List of hidden dimensions for the global MLP layers.

forward(x)

Forward pass of the PointNet feature extractor.

Parameters:

x (torch.Tensor) – Input point cloud of shape […, 3, n_vertices]

Returns:

torch.Tensor – Concatenated global and point-wise features of shape […, n_features, n_vertices].

class geomfum.wrap.pointnet.PointnetFeatureExtractor(in_channels=3, out_channels=128, conv_channels=[64, 64, 128], mlp_dims=[512, 256, 128], head_channels=[256, 128], dropout=0.3, device=None, descriptor=None)

Bases: BaseFeatureExtractor, Module

Feature extractor using PointNet architecture.

Parameters:

• n_features (int) – Number of output features per point.

• conv_channels (list of int) – Channels for convolution layers in the feature extractor.

• mlp_dims (list of int) – Hidden dimensions for the global MLP.

• head_channels (list of int) – Convolutional layers in the head network.

• dropout (float) – Dropout probability.

• device (torch.device or str) – Device on which the model is allocated.

• descriptor (Descriptor or None) – Optional descriptor to compute input features. If None, uses vertex coordinates.

forward(shape)

Extract point-wise features from a shape.

Parameters:

shape (object) – An object with a vertices attribute of shape (n_vertices, 3).

Returns:

torch.Tensor – Feature tensor of shape (1, n_vertices, n_features).

geomfum.wrap.pot module

Python Optimal Trasport wrapper.

class geomfum.wrap.pot.BaseNeighborFinder(n_neighbors=1)

Bases: ABC

Base class for a Neighbor finder.

Parameters:

n_neighbors (int) – Number of neighbors to find.

class geomfum.wrap.pot.PotSinkhornNeighborFinder(n_neighbors=1, lambd=0.1, method='sinkhorn', max_iter=100)

Bases: BaseNeighborFinder

Neighbor finder based on Optimal Transport maps computed with Sinkhorn regularization.

Parameters:

• n_neighbors (int, default=1) – Number of neighbors to find.

• lambd (float, default=1e-1) – Regularization parameter for Sinkhorn algorithm.

• method (str, default=”sinkhorn”) – Method to use for Sinkhorn algorithm.

• max_iter (int, default=100) – Maximum number of iterations for Sinkhorn algorithm.

References

[Cuturi2013]

Marco Cuturi. “Sinkhorn Distances: Lightspeed Computation of Optimal Transport.” Advances in Neural Information Processing Systems (NIPS), 2013. http://marcocuturi.net/SI.html

geomfum.wrap.pp3d module

potpourri3d wrapper.

nmwsharp/potpourri3d by Nicholas Sharp.

class geomfum.wrap.pp3d.FinitePointSetMetric(shape)

Bases: Metric, ABC

Metric supporting distance matrices and source-to-all computations on discrete point sets.

abstractmethod dist_from_source(source_point)

Distances from a source point.

Parameters:

source_point (array-like, shape=[…]) – Index of source point.

Returns:

• dist (array-like, shape=[…] or list-like[array-like]) – Distance.

• target_point (array-like, shape=[n_targets] or list-like[array-like]) – Target index.

abstractmethod dist_matrix()

Distances between all the points of a shape.

Returns:

dist_matrix (array-like, shape=[n_vertices, n_vertices]) – Distance matrix.

class geomfum.wrap.pp3d.Pp3dEdgeFlipGeodesicMetric(shape, solver=None)

Bases: _SingleDispatchMixins, FinitePointSetMetric

Geodesic distance metric between vertices of a mesh.

Parameters:

• shape (TriangleMesh) – Mesh.

• solver (pp3d.EdgeFlipGeodesicSolver) – Edge flip geodesic solver class.

References

[SC2020]

Sharp, N., Crane, K., 2020. You Can Find Geodesic Paths in Triangle Meshes by Just Flipping Edges. ACM Trans. Graph.

dist_matrix()

Distance between mesh vertices.

Returns:

dist_matrix (array-like, shape=[n_vertices, n_vertices]) – Distance matrix.

Notes

slow

class geomfum.wrap.pp3d.Pp3dHeatDistanceMetric(shape, solver=None)

Bases: _SingleDispatchMixins, FinitePointSetMetric

Heat distance metric between vertices of a mesh.

Parameters:

• shape (TriangleMesh) – Mesh.

• solver (pp3d.HeatMethodDistanceSolver) – Heat method distance solver class. ‘ ‘

References

[CWW2017]

Crane, K., Weischedel, C., Wardetzky, M., 2017. The heat method for distance computation. Commun. ACM 60, 90–99. https://doi.org/10.1145/3131280

dist_matrix()

Distance between mesh vertices.

Returns:

dist_matrix (array-like, shape=[n_vertices, n_vertices]) – Distance matrix.

Notes

slow

class geomfum.wrap.pp3d.Pp3dMeshHeatDistanceMetric(shape)

Bases: Pp3dHeatDistanceMetric

Heat distance metric between vertices of a mesh.

Parameters:

shape (TriangleMesh) – Mesh.

References

cite:: CWW2017

class geomfum.wrap.pp3d.Pp3dPointSetHeatDistanceMetric(shape)

Bases: Pp3dHeatDistanceMetric

Heat distance metric between points of a PointCloud.

Parameters:

shape (PointCloud) – Point cloud.

References

cite:: CWW2017

geomfum.wrap.pyfm module

pyFM wrapper.

class geomfum.wrap.pyfm.BaseLaplacianFinder

Bases: ABC

Algorithm to find the Laplacian.

class geomfum.wrap.pyfm.BaseSampler

Bases: ABC

Abstract Sampler.

abstractmethod sample(shape)

Sample shape.

class geomfum.wrap.pyfm.FunctionalOperator(shape)

Bases: ABC

Abstract class fot Functional operator.

class geomfum.wrap.pyfm.PyFmFaceOrientationOperator(shape)

Bases: VectorFieldOperator

Orientation operator associated to a gradient field.

For a given function \(g\) on the vertices, this operator linearly computes \(< \grad(f) x \grad(g)\), n> for each vertex by averaging along the adjacent faces. In practice, we compute \(< n x \grad(f), \grad(g) >\) for simpler computation.

class geomfum.wrap.pyfm.PyfmEuclideanFarthestVertexSampler(min_n_samples)

Bases: BaseSampler

Farthest point Euclidean sampling.

Parameters:

min_n_samples (int) – Minimum number of samples to target.

sample(shape)

Sample using farthest point sampling.

Parameters:

shape (TriangleMesh) – Mesh.

Returns:

samples (array-like, shape=[n_samples, 3]) – Coordinates of samples.

class geomfum.wrap.pyfm.PyfmFaceDivergenceOperator(shape)

Bases: VectorFieldOperator

Divergence of a function on a mesh.

class geomfum.wrap.pyfm.PyfmFaceValuedGradient(shape)

Bases: FunctionalOperator

Gradient of a function on a mesh.

Computes the gradient of a function on f using linear interpolation between vertices.

class geomfum.wrap.pyfm.PyfmHeatKernelSignature(scale=True, n_domain=3, domain=None)

Bases: SpectralDescriptor

Heat kernel signature using pyFM.

Parameters:

• scale (bool) – Whether to scale weights to sum to one.

• n_domain (int) – Number of domain points. Ignored if domain is not None.

• domain (callable or array-like, shape=[n_domain]) – Method to compute time points (f(shape, n_domain)) or time points.

class geomfum.wrap.pyfm.PyfmLandmarkHeatKernelSignature(scale=True, n_domain=3, domain=None)

Bases: SpectralDescriptor

Landmark-based Heat kernel signature using pyFM.

Parameters:

• scale (bool) – Whether to scale weights to sum to one.

• n_domain (int) – Number of domain points. Ignored if domain is not None.

• domain (callable or array-like, shape=[n_domain]) – Method to compute domain points (f(shape)) or domain points.

class geomfum.wrap.pyfm.PyfmLandmarkWaveKernelSignature(scale=True, sigma=None, n_domain=3, domain=None)

Bases: SpectralDescriptor

Landmark-based Wave kernel signature using pyFM.

Parameters:

• scale (bool) – Whether to scale weights to sum to one.

• sigma (float) – Standard deviation. Ignored if domain is a callable (other than default one).

• n_domain (int) – Number of energy points. Ignored if domain is not a callable.

• domain (callable or array-like, shape=[n_domain]) – Method to compute domain points (f(shape)) or domain points.

class geomfum.wrap.pyfm.PyfmMeshLaplacianFinder

Bases: BaseLaplacianFinder

Algorithm to find the Laplacian of a mesh.

class geomfum.wrap.pyfm.PyfmWaveKernelSignature(scale=True, sigma=None, n_domain=3, domain=None, landmarks=False)

Bases: SpectralDescriptor

Wave kernel signature using pyFM.

Parameters:

• scale (bool) – Whether to scale weights to sum to one.

• sigma (float) – Standard deviation. Ignored if domain is a callable (other than default one).

• n_domain (int) – Number of energy points. Ignored if domain is not a callable.

• domain (callable or array-like, shape=[n_domain]) – Method to compute domain points (f(shape)) or domain points.

class geomfum.wrap.pyfm.SpectralDescriptor(spectral_filter=None, domain=None, sigma=1, scale=True, landmarks=False, k=None)

Bases: Descriptor, ABC

Spectral descriptor computed from Laplacian eigenfunctions with spectral filters.

Parameters:

• spectral_filter (SpectralFilter) – Spectral filter.

• domain (callable or array-like, shape=[n_domain]) – Method to compute domain points (f(basis, n_domain)) or domain points.

• sigma (float) – Standard deviation for the Gaussian.

• scale (bool) – Whether to scale weights to sum to one.

• landmarks (bool) – Whether to compute landmarks based descriptors.

• k (int, optional) – Number of eigenvalues and eigenvectors to use. If None, basis.use_k is used.

class geomfum.wrap.pyfm.VectorFieldOperator(shape)

Bases: ABC

Vector field operator.

class geomfum.wrap.pyfm.WksDefaultDomain(n_domain, sigma=None, n_overlap=7, n_trans=2)

Bases: object

Default domain generator for Wave Kernel Signature using logarithmic energy sampling.

Parameters:

• shape (Shape.) – Shape with basis.

• n_domain (int) – Number of energy points to use.

• n_overlap (int) – Controls Gaussian overlap. Ignored if sigma is not None.

• n_trans (int) – Number of standard deviations to translate energy bound by.

geomfum.wrap.pyfm.get_orientation_op(grad_field, vertices, faces, normals, per_vert_area, rotated=False)

Compute the linear orientation operator associated to a gradient field grad(f).

This operator computes g -> < grad(f) x grad(g), n> (given at each vertex) for any function g In practice, we compute < n x grad(f), grad(g) > for simpler computation.

Parameters:

• grad_field – (n_f,3) gradient field on the mesh

• vertices – (n_v,3) coordinates of vertices

• faces – (n_f,3) indices of vertices for each face

• normals – (n_f,3) normals coordinate for each face

• per_vert_area – (n_v,) voronoi area for each vertex

• rotated (bool) – whether gradient field is already rotated by n x grad(f)

Returns:

operator (sparse.csc_matrix or list[sparse.csc_matrix], shape=[n_vertices, n_verticess]) – (n_v,n_v) orientation operator.

Notes

• vectorized version of pyFm.geometry.mesh.get_orientation_op.

geomfum.wrap.pyfm.hks_default_domain(shape, n_domain)

Compute HKS default domain. The domain is a set of sampled time points.

Parameters:

• shape (Shape.) – Shape with basis.

• n_domain (int) – Number of time points.

Returns:

domain (array-like, shape=[n_domain]) – Time points.

geomfum.wrap.pymeshlab module

pymeshlab wrapper.

class geomfum.wrap.pymeshlab.BaseSampler

Bases: ABC

Abstract Sampler.

abstractmethod sample(shape)

Sample shape.

class geomfum.wrap.pymeshlab.PymeshlabPoissonSampler(min_n_samples)

Bases: BaseSampler

Poisson disk sampling.

Parameters:

min_n_samples (int) – Minimum number of samples to target.

sample(shape)

Sample using Poisson disk sampling.

Parameters:

shape (TriangleMesh) – Mesh.

Returns:

samples (array-like, shape=[n_samples, 3]) – Coordinates of samples.

geomfum.wrap.pyrmt module

geomfum.wrap.robust module

robust_laplacian wrapper.

class geomfum.wrap.robust.BaseLaplacianFinder

Bases: ABC

Algorithm to find the Laplacian.

class geomfum.wrap.robust.RobustMeshLaplacianFinder(mollify_factor=1e-05)

Bases: BaseLaplacianFinder

Algorithm to find the Laplacian of a mesh.

Parameters:

mollify_factor (float) – Amount of intrinsic mollification to perform.

class geomfum.wrap.robust.RobustPointCloudLaplacianFinder(mollify_factor=1e-05, n_neighbors=30)

Bases: BaseLaplacianFinder

Algorithm to find the Laplacian of a point cloud.

Parameters:

• mollify_factor (float) – Amount of intrinsic mollification to perform.

• n_neighbors (float) – Number of nearest neighbors to use when constructing local triangulations.

geomfum.wrap.transformer module

Transformer for Feature Extraction.

Copyright (c) 2025 Alessandro Riva

References

[RRM2024] Riva, A., Raganato, A, Melzi, S., “Localized Gaussians as Self-Attention Weights for Point Clouds Correspondence”,

Smart Tools and Applications in Graphics, 2024, arXiv:2409.13291

ariva00/aided_transformer

class geomfum.wrap.transformer.AttentionLayer(embed_dim, num_heads, dropout: float = 0.0, attn_bias: bool = True, ff_mult: int = 4)

Bases: Module

Attention Layer for the Transformer.

Parameters:

• embed_dim (int) – Dimension of the used embedding

• num_heads (int) – Number of attention heads

• dropout (float) – Dropout rate

• attn_bias (bool) – Set the use of leaned bias in the output linear layer of the attention heads

• ff_mult (int) – Dimension factor of the feed forward section of the attention layer. The dimension expansion is computed as ff_mult * embed_dim

forward(x, y, attn_mask=None, x_mask=None, y_mask=None, attn_prev=None)

Forward pass of the Attention Layer.

Parameters:

• x (torch.Tensor) – Tokens of x tensor of shape (batch_size, num_points_x, embed_dim)

• y (torch.Tensor) – Tokens of y tensor of shape (batch_size, num_points_y, embed_dim)

• attn_mask (torch.Tensor) – Mask tensor for the attention weights of shape (batch_size, num_heads, num_points_x, num_points_y) or (batch_size, num_points_x, num_points_y). If (batch_size, num_points_x, num_points_y) the mask will be broadcasted over the num_heads dimension

• x_mask (torch.Tensor) – Mask tensor of x of shape (batch_size, num_points_x)

• y_mask (torch.Tensor) – Mask tensor of y of shape (batch_size, num_points_y)

• attn_prev (torch.Tensor) – Attention weights of the previous layer to be used in the residual attention of shape (batch_size, num_heads, num_points_x, num_points_y)

Returns:

• output (torch.Tensor) – Attention output tensor of shape (batch_size, num_points_x, embed_dim)

• hiddens (dict) – Intermediate activations of the attention mechanism

class geomfum.wrap.transformer.BaseFeatureExtractor

Bases: ABC

Abstract base class for neural network feature extractors.

load_from_path(path)

Load model parameters from the provided file path.

Parameters:

path (str) – Path to the saved model parameters

save(path)

Save model parameters to the specified file path.

Parameters:

path (str) – Path to the saved model parameters

class geomfum.wrap.transformer.MultiHeadAttention(embed_dim, num_heads: int, dropout: float = 0.0, bias: bool = True)

Bases: Module

Multi-Head Attention layer.

Parameters:

• embed_dim (int) – Dimension of the used embedding

• num_heads (int) – Number of attention heads

• dropout (float) – Dropout rate

• bias (bool) – Set the use of leaned bias in the output linear layer of the attention heads

forward(query: Tensor, key: Tensor, value: Tensor, attn_mask: Tensor = None, attn_prev: Tensor = None)

Forward pass of the Multi-Head Attention layer.

Parameters:

• query (torch.Tensor) – Query vectors of x

• key (torch.Tensor) – Key vectors of y

• value (torch.Tensor) – Value vectors of y

• attn_mask (torch.Tensor) – Mask tensor for the attention weights of shape (batch_size, num_heads, num_points_x, num_points_y) or (batch_size, num_points_x, num_points_y). If (batch_size, num_points_x, num_points_y) the mask will be broadcasted over the num_heads dimension

• attn_prev (torch.Tensor) – Attention weights of the previous layer to be used in the residual attention of shape (batch_size, num_heads, num_points_x, num_points_y)

Returns:

• output (torch.Tensor) – Attention output tensor of shape (batch_size, num_points_x, embed_dim)

• hiddens (dict) – Intermediate activations of the attention mechanism

class geomfum.wrap.transformer.Transformer(embed_dim, num_heads, num_layers, dropout=0.0, residual=False)

Bases: Module

Transformer for feature extraction.

Parameters:

• embed_dim (int) – Dimension of the used embedding

• num_heads (int) – Number of attention heads

• num_layers (int) – Number of attention layers

• dropout (float) – Dropout rate

• residual (bool) – Boolean control the use of the residual attention

forward(x, y, attn_mask=None, x_mask=None, y_mask=None, return_hiddens=False)

Forward pass of the Transformer.

Parameters:

• x (torch.Tensor) – Tokens of x tensor of shape (batch_size, num_points_x, embed_dim)

• y (torch.Tensor) – Tokens of y tensor of shape (batch_size, num_points_y, embed_dim)

• attn_mask (torch.Tensor) – Mask tensor for the attention weights of shape (batch_size, num_heads, num_points_x, num_points_y) or (batch_size, num_points_x, num_points_y). If (batch_size, num_points_x, num_points_y) the mask will be broadcasted over the num_heads dimension

• x_mask (torch.Tensor) – Mask tensor of x of shape (batch_size, num_points_x)

• y_mask (torch.Tensor) – Mask tensor of y of shape (batch_size, num_points_y)

• return_hiddens (bool) – Boolean to return intermediate activations of the attention mechanism. If True the output is a tuple (output, hiddens)

Returns:

• output (torch.Tensor) – Attention output tensor of shape (batch_size, num_points_x, embed_dim)

• hiddens (dict) – Intermediate activations of the attention mechanism

class geomfum.wrap.transformer.TransformerFeatureExtractor(in_channels: int = 3, embed_dim: int = 256, num_heads: int = 8, num_layers: int = 4, out_channels: int = 512, dropout: float = 0.1, use_global_pool: bool = True, k_neighbors: int = 16, device=None, descriptor=None)

Bases: BaseFeatureExtractor, Module

Transformer Feature Extractor for point clouds.

This feature extractor uses the Transformer architecture to extract features from shapes.

Parameters:

• in_channels (int) – Input feature dimension (typically 3 for xyz coordinates)

• embed_dim (int) – Embedding dimension for the transformer

• num_heads (int) – Number of attention heads

• num_layers (int) – Number of transformer layers

• output_dim (int) – Output feature dimension

• dropout (float) – Dropout probability

• use_global_pool (bool) – Whether to use global max pooling for global features

forward(shape, return_intermediate=False)

Forward pass of the feature extractor.

Parameters:

shape (Shape) – Input shape

Returns:

features (torch.Tensor) – Extracted features tensor of shape (batch_size, num_points, output_dim)

Module contents

Registration of various wrapped components in GeomFum.

geomfum.wrap.has_package(package_name)

Check if package is installed.

Parameters:

package_name (str) – Package name.

geomfum.wrap.register_face_divergence_operator(key, obj_name, requires=(), as_default=False)

Register an implementation with optional package dependencies.

Parameters:

• key (str) – Key.

• obj_name (class name) – Name of the object to register.

• requires (str or tuple) – Required packages.

• as_default (bool) – Whether to set it as default.

geomfum.wrap.register_face_orientation_operator(key, obj_name, requires=(), as_default=False)

Register an implementation with optional package dependencies.

Parameters:

• key (str) – Key.

• obj_name (class name) – Name of the object to register.

• requires (str or tuple) – Required packages.

• as_default (bool) – Whether to set it as default.

geomfum.wrap.register_face_valued_gradient(key, obj_name, requires=(), as_default=False)

Register an implementation with optional package dependencies.

Parameters:

• key (str) – Key.

• obj_name (class name) – Name of the object to register.

• requires (str or tuple) – Required packages.

• as_default (bool) – Whether to set it as default.

geomfum.wrap.register_feature_extractor(key, obj_name, requires=(), as_default=False)

Register an implementation with optional package dependencies.

Parameters:

• key (str) – Key.

• obj_name (class name) – Name of the object to register.

• requires (str or tuple) – Required packages.

• as_default (bool) – Whether to set it as default.

geomfum.wrap.register_heat_distance_metric(key_out, key_in, obj_name, requires=(), as_default=False)

Register implementation in nested registry structure.

Parameters:

• key_out (Hashable) – Key for outer register dict.

• key_in (str) – Key for object in inner register.

• obj_name (class name) – Name of the object to register.

• requires (str or tuple) – Required packages.

• as_default (bool) – Whether to set it as default.

geomfum.wrap.register_heat_kernel_signature(key, obj_name, requires=(), as_default=False)

Register an implementation with optional package dependencies.

Parameters:

• key (str) – Key.

• obj_name (class name) – Name of the object to register.

• requires (str or tuple) – Required packages.

• as_default (bool) – Whether to set it as default.

geomfum.wrap.register_hierarchical_mesh(key, obj_name, requires=(), as_default=False)

Register an implementation with optional package dependencies.

Parameters:

• key (str) – Key.

• obj_name (class name) – Name of the object to register.

• requires (str or tuple) – Required packages.

• as_default (bool) – Whether to set it as default.

geomfum.wrap.register_landmark_heat_kernel_signature(key, obj_name, requires=(), as_default=False)

Register an implementation with optional package dependencies.

Parameters:

• key (str) – Key.

• obj_name (class name) – Name of the object to register.

• requires (str or tuple) – Required packages.

• as_default (bool) – Whether to set it as default.

geomfum.wrap.register_landmark_wave_kernel_signature(key, obj_name, requires=(), as_default=False)

Register an implementation with optional package dependencies.

Parameters:

• key (str) – Key.

• obj_name (class name) – Name of the object to register.

• requires (str or tuple) – Required packages.

• as_default (bool) – Whether to set it as default.

geomfum.wrap.register_laplacian_finder(key_out, key_in, obj_name, requires=(), as_default=False)

Register implementation in nested registry structure.

Parameters:

• key_out (Hashable) – Key for outer register dict.

• key_in (str) – Key for object in inner register.

• obj_name (class name) – Name of the object to register.

• requires (str or tuple) – Required packages.

• as_default (bool) – Whether to set it as default.

geomfum.wrap.register_neighbor_finder(key, obj_name, requires=(), as_default=False)

Register an implementation with optional package dependencies.

Parameters:

• key (str) – Key.

• obj_name (class name) – Name of the object to register.

• requires (str or tuple) – Required packages.

• as_default (bool) – Whether to set it as default.

geomfum.wrap.register_poisson_sampler(key, obj_name, requires=(), as_default=False)

Register an implementation with optional package dependencies.

Parameters:

• key (str) – Key.

• obj_name (class name) – Name of the object to register.

• requires (str or tuple) – Required packages.

• as_default (bool) – Whether to set it as default.

geomfum.wrap.register_precise_geodesic_distance_metric(key, obj_name, requires=(), as_default=False)

Register an implementation with optional package dependencies.

Parameters:

• key (str) – Key.

• obj_name (class name) – Name of the object to register.

• requires (str or tuple) – Required packages.

• as_default (bool) – Whether to set it as default.

geomfum.wrap.register_wave_kernel_signature(key, obj_name, requires=(), as_default=False)

Register an implementation with optional package dependencies.

Parameters:

• key (str) – Key.

• obj_name (class name) – Name of the object to register.

• requires (str or tuple) – Required packages.

• as_default (bool) – Whether to set it as default.