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.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_eig=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_eig (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.

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)

geomfum.wrap.igl module

igl wrapper.

class geomfum.wrap.igl.IglMeshLaplacianFinder

Bases: BaseLaplacianFinder

Algorithm to find the Laplacian of a mesh.

geomfum.wrap.plotly module

Wraps plotly functions.

class geomfum.wrap.plotly.PlotlyMeshPlotter(colormap='viridis')

Bases: ShapePlotter

Plotting object to display meshes.

add_mesh(mesh, **kwargs)

Add mesh to plot.

Parameters:

mesh (TriangleMesh) – Mesh to be plotted.

highlight_vertices(coords, color='red', size=4)

Highlight vertices on mesh.

Parameters:

• coords (array-like, shape=[n_vertices, 3]) – Coordinates of vertices to highlight.

• color (str) – Color of the highlighted vertices as str.

• size (int) – Size of the highlighted vertices.

set_vertex_scalars(scalars, name='scalars')

Set vertex scalars on mesh.

Parameters:

• scalars (array-like) – Value at each vertex.

• name (str) – Ignored.

show()

Display plot.

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.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.polyscope module

Wraps polyscope functions.

class geomfum.wrap.polyscope.PsMeshPlotter(colormap='viridis', backend='')

Bases: ShapePlotter

Plotting object to display meshes.

add_mesh(mesh)

Add mesh to plot.

Parameters:

mesh (TriangleMesh) – Mesh to be plotted.

highlight_vertices(coords, color=(1.0, 0.0, 0.0), size=0.01)

Highlight vertices on a mesh using Polyscope by adding a point cloud.

Parameters:

• coords (array-like, shape = [n_vertices, 3]) – Coordinates of vertices to highlight.

• color (tuple) – Color of the highlighted vertices (e.g., (1.0, 0.0, 0.0)).

• radius (float) – Radius of the rendered points (visual size).

set_vertex_scalars(scalars, name='scalars')

Set vertex scalars on mesh.

Parameters:

• scalars (array-like) – Value at each vertex.

• name (str) – Scalar field name.

show()

Display plot.

geomfum.wrap.pot module

Python Optimal Trasport wrapper.

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

fit(X)

Store the reference points.

Parameters:

X (array-like, shape=[n_points_x, n_features]) – Reference points.

kneighbors(X, return_distance=True)

Find k nearest neighbors using Sinkhorn regularization.

Parameters:

• X (array-like, shape=[n_points_y, n_features]) – Query points.

• return_distance (bool) – Whether to return the distances.

Returns:

• distances (array-like, shape=[n_points_y, n_neighbors]) – Distances to the nearest neighbors.

• indices (array-like, shape=[n_points_y, n_neighbors]) – Indices of the nearest neighbors.

geomfum.wrap.pp3d module

potpourri3d wrapper.

nmwsharp/potpourri3d by Nicholas Sharp.

class geomfum.wrap.pp3d.Pp3dHeatDistanceMetric(shape)

Bases: _SingleDispatchMixins, FinitePointSetMetric

Heat distance metric between vertices of a mesh.

Parameters:

shape (Shape) – Shape.

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

geomfum.wrap.pyfm module

pyFM wrapper.

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, use_landmarks=False)

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.

• use_landmarks (bool) – Whether to use landmarks.

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, use_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.

• use_landmarks (bool) – Whether to use landmarks.

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.pymeshlab module

pymeshlab wrapper.

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

pyRMT wrapper.

class geomfum.wrap.pyrmt.PyrmtHierarchicalMesh(mesh, min_n_samples)

Bases: HierarchicalShape

Hierarchical mesh from PyRMT.

Based on [MBMR2023].

Parameters:

• mesh (TriangleMesh) – High-resolution mesh.

• min_n_samples (int) – Minimum number of vertices in low-resolution mesh.

References

[MBMR2023]

Filippo Maggioli, Daniele Baieri, Simone Melzi, and Emanuele Rodolà. “ReMatching: Low-Resolution Representations for Scalable Shape Correspondence.” arXiv, October 30, 2023. https://doi.org/10.48550/arXiv.2305.09274.

scalar_low_high(scalar)

Transfer scalar from low-resolution to high.

Parameters:

scalar (array-like, shape=[…, low.n_vertices]) – Scalar map on the low-resolution shape.

Returns:

high_scalar (array-like, shape=[…, high.n_vertices]) – Scalar map on the high-resolution shape.

geomfum.wrap.pyvista module

Wraps pyvista functions.

class geomfum.wrap.pyvista.PvMeshPlotter(colormap='viridis', **kwargs)

Bases: ShapePlotter

Plotting object to display meshes.

add_mesh(mesh, **kwargs)

Add mesh to plot.

Parameters:

mesh (TriangleMesh) – Mesh to be plotted.

highlight_vertices(coords, color='red', size=0.01)

Highlight vertices on the mesh using PyVista.

Parameters:

• coords (array-like, shape = [n_vertices, 3]) – Coordinates of vertices to highlight.

• color (str or tuple) – Color of the highlighted vertices.

• size (float) – Size of the highlighted vertices (radius of spheres).

set_vertex_scalars(scalars, name='scalars')

Set vertex scalars on mesh.

Parameters:

• scalars (array-like) – Value at each vertex.

• name (str) – Scalar field name.

show()

Display plot.

geomfum.wrap.robust module

robust_laplacian wrapper.

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.

Module contents