pyFM - Python Functional Maps Library

NEW API Documentation is available here

This package contains a comprehensive Python implementation for shape correspondence using functional maps, featuring code from multiple papers

Core Features

• Complete TriMesh class with geometric measures (geodesics, normals, LBO projections, differential operators)
• Fast Laplace-Beltrami Operator implementation
• Shape descriptors (HKS, WKS) with flexible parameter control
• Efficient correspondence refinement (ICP, ZoomOut)
• Fast functional-to-pointwise map conversion
• Functional Map Network utilities

Installation

pip install pyfmaps

Please check the PyPi page to ensure the latest version is uploaded.

Key Dependencies

• Required: numpy, scipy, tqdm, scikit-learn
• Optional: potpourri3d (geodesics), robust_laplacian (Delaunay/tufted Laplacian)

Design Philosophy

This codebase prioritizes readability and adaptability over rigid modularity. The implementation seeks to make it easy to:

• Read and understand the underlying algorithms
• Copy and modify code snippets for your research
• Experiment with and extend existing methods
• Avoid rewriting core functionality from scratch

Under the hood, core algorithms are implemented as standalone functions operating on basic numpy arrays. This dual-layer design means you can use the high-level interface for standard workflows, but still easily extract and modify the core functions for your research, as they work with simple numpy arrays.

While this approach differs from highly modular packages like scikit-learn, it better serves researchers who need to modify and build upon existing shape correspondence methods.

This design choice comes with some trade-offs:

• Less abstraction means potentially more code to achieve certain tasks
• Users need some familiarity with shape correspondence concepts
• Implementation favors explicit algorithms over general-purpose interfaces

I selected this approach from my personal experience with research codebases and may not suit everyone's needs. More generic and abstracted implementations of geometric processing can be expected to appear soonish in the scikit-shapes or geomstats libraries.

Notation Convention

• Functional maps (FM_12): mesh1 → mesh2
• Pointwise maps (p2p_21): mesh2 → mesh1

Documentation & Examples

• API Documentation
• Example Notebooks

Implemented Papers

This library implements methods from several key papers in shape correspondence, including:

• The Heat Method for Distance Computation
• A Concise and Provably Informative Multi-Scale Signature Based on Heat Diffusion
• The Wave Kernel Signature: A Quantum Mechanical Approach To Shape Analysis
• ZoomOut: Spectral Upsampling for Efficient Shape Correspondence, with MatLab implementation here
• Deblurring and Denoising of Maps between Shapes, with Matlab implementation here
• Functional Maps: A Flexible Representation of Maps Between Shapes
• Informative Descriptor Preservation via Commutativity for Shape Matching
• Continuous and Orientation-preserving Correspondences via Functional Maps, only the orientation preserving / reversing term, matlab implementation can be found here
• Map-Based Exploration of Intrinsic Shape Differences and Variability
• An Optimization Approach to Improving Collections of Shape Maps
• Limit Shapes – A Tool for Understanding Shape Differences and Variability in 3D Model Collections
• CONSISTENT ZOOMOUT: Efficient Spectral Map Synchronization, with Matlab implementation here

Torch Version

Most functions in this package can easily be translated to torch. However, for clarity of the code, a separate version will be released.

For now, the torch implementations can be found in different githubs (see my GitHub profile).

Coming Soon

• Discrete Optimization for Shape Matching and Smooth Non-Rigid Shape Matching via Effective Dirichlet Energy Optimization, already implemented here
• Reversible Harmonic Maps, already implemented here

Contact and Citation

You can contact me for any questions or requests at robin.magnet@inria.fr

This package has not (yet) been presented as a paper in itself, although all my works heavily rely on this.

If you use this package or copy and paste parts of it for you experiments, please cite this github or one of the following paper. Note these papers never directly refer to pyfmaps as so I am fine with you only citing the github for now.

@inproceedings{magnetDWKSLocalDescriptor2021,
  title = {{{DWKS}} : {{A Local Descriptor}} of {{Deformations Between Meshes}} and {{Point Clouds}}},
  shorttitle = {{{DWKS}}},
  booktitle = {2021 {{IEEE}}/{{CVF International Conference}} on {{Computer Vision}} ({{ICCV}})},
  author = {Magnet, Robin and Ovsjanikov, Maks},
  publisher = {IEEE},
}


@inproceedings{magnetSmoothNonRigidShape2022,
  title = {Smooth {{Non-Rigid Shape Matching}} via {{Effective Dirichlet Energy Optimization}}},
  booktitle = {2022 {{International Conference}} on {{3D Vision}} ({{3DV}})},
  author = {Magnet, Robin and Ren, Jing and {Sorkine-Hornung}, Olga and Ovsjanikov, Maks},
  year = {2022},
  publisher = {{IEEE}},

}

@article{magnetScalableEfficientFunctional2023,
  title = {Scalable and {{Efficient Functional Map Computations}} on {{Dense Meshes}}},
  author = {Magnet, Robin and Ovsjanikov, Maks},
  year = {2023},
  journal = {Computer Graphics Forum},
}