geomfum.shape package#
Subpackages#
Submodules#
geomfum.shape.hierarchical module#
Hierarchical objects module. An HierarchicalShape is composed of a low-resolution and a high-resolution shape, with methods to transfer functions between the two resolutions.
- class geomfum.shape.hierarchical.EigenBasis(vals, vecs, use_k=None)[source]#
Bases:
BasisBasis formed by eigenvectors with dynamic truncation support.
- Parameters:
vals (array-like, shape=[full_spectrum_size]) – Eigenvalues.
vecs (array-like, shape=[dim, full_spectrum_size]) – Eigenvectors.
use_k (int) – Number of values to use on computations.
- property full_spectrum_size#
Total number of stored eigenvalues/eigenvectors.
- Returns:
spectrum_size (int) – Spectrum size.
- property nonzero_vals#
Nonzero eigenvalues.
- Returns:
vals (array-like, shape=[spectrum_size - n_zeros]) – Eigenvalues.
- property nonzero_vecs#
Eigenvectors corresponding to nonzero eigenvalues.
- Returns:
vecs (array-like, shape=[dim, spectrum_size - n_zeros]) – Eigenvectors.
- property spectrum_size#
Number of eigenvalues/eigenvectors currently in use.
- Returns:
spectrum_size (int) – Spectrum size.
- truncate(spectrum_size)[source]#
Create new basis with reduced spectrum size.
- Parameters:
spectrum_size (int) – Spectrum size.
- Returns:
basis (Eigenbasis) – Truncated eigenbasis.
- property vals#
Currently used eigenvalues (truncated to use_k).
- Returns:
vals (array-like, shape=[spectrum_size]) – Eigenvalues.
- property vecs#
Currently used eigenvectors (truncated to use_k).
- Returns:
vecs (array-like, shape=[dim, spectrum_size]) – Eigenvectors.
- class geomfum.shape.hierarchical.HierarchicalMesh(*args, **kwargs)[source]#
Bases:
WhichRegistryMixins,HierarchicalShapeHierarchical mesh.
- Parameters:
low (TriangleMesh) – Low resolution shape.
high (TriangleMesh) – High resolution shape.
- class geomfum.shape.hierarchical.HierarchicalMeshRegistry[source]#
Bases:
Registry- MAP = {'pyrmt': ('PyrmtHierarchicalMesh', None)}#
- default = 'pyrmt'#
- class geomfum.shape.hierarchical.HierarchicalShape(low, high)[source]#
Bases:
ABCHierarchical shape. An HierarchicalShape is composed of a low-resolution and a high-resolution shape, with methods to transfer functions between the two resolutions.
- Parameters:
low (Shape) – Low-resolution shape.
high (Shape) – High-resolution shape.
- extend_basis(set_as_basis=True)[source]#
Extend basis.
See section 3.3. of [MBMR2023] for details.
- Parameters:
set_as_basis (bool) – Whether to set as basis.
- Returns:
vecs (array-like, shape=[high.n_vertices, spectrum_size]) – Eigenvectors.
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.
- class geomfum.shape.hierarchical.NestedHierarchicalMesh(hshapes)[source]#
Bases:
NestedHierarchicalShapeNested hierachical mesh.
- property hmeshes#
Meshes from low to high resolution.
Remarks#
- hshapeslist[HierarchicalMesh]
Hierarchical meshes from low to high resolution.
- property meshes#
Meshes from low to high resolution.
Remarks#
- mesheslist[Mesh]
List of meshes from low to high resolution.
- property n_faces#
Number of faces at each level.
- Returns:
n_faces (list[int])
- property n_vertices#
Number of vertices at each level.
- Returns:
n_vertices (list[int])
- class geomfum.shape.hierarchical.NestedHierarchicalShape(hshapes)[source]#
Bases:
objectNested hierachical shape. An object composed of multiple hierarchical shapes from low to high resolution.
- Parameters:
hshapes (list[HierarchicalShape]) – Hierarchical shapes from low to high resolution.
- extend_basis(set_as_basis=True, n_levels=None)[source]#
Extend basis.
See section 3.3. of [MBMR2023] for details.
- Parameters:
set_as_basis (bool) – Whether to set as basis.
n_levels (int) – Number of levels to transfer scalar. If
Nonetransfer up to maximum resolution.
- Returns:
vecs (list[array-like], shape=[level.n_vertices, spectrum_size]) – Eigenvectors. As many as number of levels.
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.
- classmethod from_hierarchical_shape(shape, HierarchicalShape, **kwargs)[source]#
Create nested from hierarchical.
- property highest#
Highest resolution shape.
- Returns:
shape (Shape.)
- property lowest#
Lowest resolution shape.
- Returns:
shape (Shape.)
- scalar_low_high(scalar, n_levels=None)[source]#
Transfer scalar from low-resolution to high.
- Parameters:
scalar (array-like, shape=[…, low.n_vertices]) – Scalar map on the low-resolution shape.
n_levels (int) – Number of levels to transfer scalar. If
Nonetransfer up to maximum resolution.
- Returns:
high_scalar (list[array-like], shape=[…, level.n_vertices]) – Scalar map on the shape at corresponding level. As many as number of levels.
geomfum.shape.mesh module#
Definition of triangle mesh.
- class geomfum.shape.mesh.FaceDivergenceOperator(*args, **kwargs)[source]#
Bases:
WhichRegistryMixins,VectorFieldOperatorDivergence of a function on a mesh.
- class geomfum.shape.mesh.FaceOrientationOperator(*args, **kwargs)[source]#
Bases:
WhichRegistryMixins,VectorFieldOperatorOrientation 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.shape.mesh.FaceValuedGradient(*args, **kwargs)[source]#
Bases:
WhichRegistryMixins,FunctionalOperatorGradient of a function on a mesh.
Computes the gradient of a function on f using linear interpolation between vertices.
- class geomfum.shape.mesh.HeatDistanceMetric(*args, **kwargs)[source]#
Bases:
MeshWhichRegistryMixinsGeodesic distance approximation using the heat method.
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
- class geomfum.shape.mesh.Shape(is_mesh)[source]#
Bases:
ABCAbstract base class for geometric shapes with differential operators.
- Parameters:
is_mesh (bool) – Whether the shape is a mesh (True) or point cloud (False).
- property basis#
Function basis associated with the shape.
- Returns:
basis (Basis) – Basis.
- equip_with_operator(name, Operator, allow_overwrite=True, **kwargs)[source]#
Equip shape with a differential or geometric operator.
- Parameters:
name (str) – Attribute name for the operator.
Operator (class) – Operator class to instantiate.
allow_overwrite (bool, optional) – Whether to allow overwriting existing attributes (default: True).
**kwargs – Additional arguments passed to the Operator constructor.
- Returns:
self (Shape) – The shape instance for method chaining.
- class geomfum.shape.mesh.TriangleMesh(vertices, faces)[source]#
Bases:
ShapeTriangulated 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)[source]#
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)[source]#
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.shape.mesh.compute_edge_tangent_vectors(vertices, edges, tangent_frames)[source]#
Project edge vectors onto local tangent plane coordinates.
- Parameters:
vertices (array-like, shape=[n_vertices, 3]) – Vertex coordinates.
edges (array-like, shape=[n_edges, 2]) – Edges of the shape.
tangent_frames (array-like, shape=[n_vertices, 3, 3]) – Tangent frames for each vertex.
- Returns:
edge_tangent_vectors (array-like, shape=[n_edges, 2]) – Tangent vectors of the edges, projected onto the local tangent plane.
- geomfum.shape.mesh.compute_tangent_frames(vertices, normals)[source]#
Construct local orthonormal frames at each vertex from normal vectors.
- Parameters:
vertices (array-like, shape=[n_vertices, 3]) – Vertex coordinates.
normals (array-like, shape=[n_vertices, 3]) – Vertex normals.
- Returns:
frames (array-like, shape=[n_vertices, 3, 3]) – Tangent frames.
geomfum.shape.point_cloud module#
Definition of point cloud.
- class geomfum.shape.point_cloud.HeatDistanceMetric(*args, **kwargs)[source]#
Bases:
MeshWhichRegistryMixinsGeodesic distance approximation using the heat method.
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
- class geomfum.shape.point_cloud.PointCloud(vertices)[source]#
Bases:
ShapeUnstructured point cloud with k-NN connectivity and differential operators.
- Parameters:
vertices (array-like, shape=[n_vertices, 3]) – Vertices of the point cloud.
- property dist_matrix#
Pairwise distances between all points 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#
Edge connectivity from k-NN graph.
- equip_with_metric(metric)[source]#
Equip point cloud with a distance metric.
- Parameters:
metric (class) – A metric class to use for the point cloud.
- classmethod from_file(filename)[source]#
Load point cloud from file.
- Returns:
mesh (PointCloud) – A point cloud.
- property knn_graph#
K-nearest neighbors connectivity graph.
- Returns:
knn_info (dict) – Dictionary containing: - ‘indices’: array-like, shape=[n_vertices, k] - neighbor indices for each vertex - ‘distances’: array-like, shape=[n_vertices, k] - distances to neighbors - ‘k’: int - number of neighbors - ‘nbrs_model’: sklearn.neighbors.NearestNeighbors - fitted model for reuse
- property n_vertices#
Number of points.
- Returns:
n_vertices (int)
- property vertex_normals#
Normal vectors estimated from local neighborhoods using PCA.
- Returns:
normals (array-like, shape=[n_vertices, 3]) – Normalized per-vertex normals estimated from local neighborhoods using PCA.
- property vertex_tangent_frames#
Local orthonormal coordinate frames at each point.
- 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
- class geomfum.shape.point_cloud.Shape(is_mesh)[source]#
Bases:
ABCAbstract base class for geometric shapes with differential operators.
- Parameters:
is_mesh (bool) – Whether the shape is a mesh (True) or point cloud (False).
- property basis#
Function basis associated with the shape.
- Returns:
basis (Basis) – Basis.
- equip_with_operator(name, Operator, allow_overwrite=True, **kwargs)[source]#
Equip shape with a differential or geometric operator.
- Parameters:
name (str) – Attribute name for the operator.
Operator (class) – Operator class to instantiate.
allow_overwrite (bool, optional) – Whether to allow overwriting existing attributes (default: True).
**kwargs – Additional arguments passed to the Operator constructor.
- Returns:
self (Shape) – The shape instance for method chaining.
- geomfum.shape.point_cloud.compute_edge_tangent_vectors(vertices, edges, tangent_frames)[source]#
Project edge vectors onto local tangent plane coordinates.
- Parameters:
vertices (array-like, shape=[n_vertices, 3]) – Vertex coordinates.
edges (array-like, shape=[n_edges, 2]) – Edges of the shape.
tangent_frames (array-like, shape=[n_vertices, 3, 3]) – Tangent frames for each vertex.
- Returns:
edge_tangent_vectors (array-like, shape=[n_edges, 2]) – Tangent vectors of the edges, projected onto the local tangent plane.
- geomfum.shape.point_cloud.compute_tangent_frames(vertices, normals)[source]#
Construct local orthonormal frames at each vertex from normal vectors.
- Parameters:
vertices (array-like, shape=[n_vertices, 3]) – Vertex coordinates.
normals (array-like, shape=[n_vertices, 3]) – Vertex normals.
- Returns:
frames (array-like, shape=[n_vertices, 3, 3]) – Tangent frames.
geomfum.shape.shape_utils module#
Utility functions for shape computations.
- geomfum.shape.shape_utils.compute_edge_tangent_vectors(vertices, edges, tangent_frames)[source]#
Project edge vectors onto local tangent plane coordinates.
- Parameters:
vertices (array-like, shape=[n_vertices, 3]) – Vertex coordinates.
edges (array-like, shape=[n_edges, 2]) – Edges of the shape.
tangent_frames (array-like, shape=[n_vertices, 3, 3]) – Tangent frames for each vertex.
- Returns:
edge_tangent_vectors (array-like, shape=[n_edges, 2]) – Tangent vectors of the edges, projected onto the local tangent plane.
- geomfum.shape.shape_utils.compute_gradient_matrix_fem(vertices, edges, edge_tangent_vectors)[source]#
Construct gradient operator using local least-squares approximation.
- Parameters:
vertices (array-like, shape=[n_vertices, 3]) – Vertex coordinates.
edges (array-like, shape=[n_edges, 2]) – Edges of the shape.
edge_tangent_vectors (array-like, shape=[n_edges, 2]) – Tangent vectors of the edges, projected onto the local tangent plane.
- Returns:
grad_matrix (array-like, shape=[n_edges, n_vertices]) – Gradient matrix.
- geomfum.shape.shape_utils.compute_tangent_frames(vertices, normals)[source]#
Construct local orthonormal frames at each vertex from normal vectors.
- Parameters:
vertices (array-like, shape=[n_vertices, 3]) – Vertex coordinates.
normals (array-like, shape=[n_vertices, 3]) – Vertex normals.
- Returns:
frames (array-like, shape=[n_vertices, 3, 3]) – Tangent frames.
Module contents#
Shapes Module. This module contains various shape representations used in Geomfum, such as TriangleMesh and PointCloud.
- class geomfum.shape.PointCloud(vertices)[source]#
Bases:
ShapeUnstructured point cloud with k-NN connectivity and differential operators.
- Parameters:
vertices (array-like, shape=[n_vertices, 3]) – Vertices of the point cloud.
- property dist_matrix#
Pairwise distances between all points 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#
Edge connectivity from k-NN graph.
- equip_with_metric(metric)[source]#
Equip point cloud with a distance metric.
- Parameters:
metric (class) – A metric class to use for the point cloud.
- classmethod from_file(filename)[source]#
Load point cloud from file.
- Returns:
mesh (PointCloud) – A point cloud.
- property knn_graph#
K-nearest neighbors connectivity graph.
- Returns:
knn_info (dict) – Dictionary containing: - ‘indices’: array-like, shape=[n_vertices, k] - neighbor indices for each vertex - ‘distances’: array-like, shape=[n_vertices, k] - distances to neighbors - ‘k’: int - number of neighbors - ‘nbrs_model’: sklearn.neighbors.NearestNeighbors - fitted model for reuse
- property n_vertices#
Number of points.
- Returns:
n_vertices (int)
- property vertex_normals#
Normal vectors estimated from local neighborhoods using PCA.
- Returns:
normals (array-like, shape=[n_vertices, 3]) – Normalized per-vertex normals estimated from local neighborhoods using PCA.
- property vertex_tangent_frames#
Local orthonormal coordinate frames at each point.
- 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
- class geomfum.shape.Shape(is_mesh)[source]#
Bases:
ABCAbstract base class for geometric shapes with differential operators.
- Parameters:
is_mesh (bool) – Whether the shape is a mesh (True) or point cloud (False).
- property basis#
Function basis associated with the shape.
- Returns:
basis (Basis) – Basis.
- equip_with_operator(name, Operator, allow_overwrite=True, **kwargs)[source]#
Equip shape with a differential or geometric operator.
- Parameters:
name (str) – Attribute name for the operator.
Operator (class) – Operator class to instantiate.
allow_overwrite (bool, optional) – Whether to allow overwriting existing attributes (default: True).
**kwargs – Additional arguments passed to the Operator constructor.
- Returns:
self (Shape) – The shape instance for method chaining.
- class geomfum.shape.TriangleMesh(vertices, faces)[source]#
Bases:
ShapeTriangulated 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)[source]#
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)[source]#
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