Metadata-Version: 2.4
Name: densemaps
Version: 0.1.0
Summary: Abstract, memory-scalable correspondence maps for 3D geometry (NumPy & PyTorch).
Author: Robin Magnet
License: MIT License
        
        Copyright (c) 2024 RobinMagnet
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/RobinMagnet/ScalableDenseMaps
Project-URL: Documentation, https://robinmagnet.github.io/ScalableDenseMaps/
Project-URL: Repository, https://github.com/RobinMagnet/ScalableDenseMaps
Keywords: geometry-processing,shape-correspondence,functional-maps,3d
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Topic :: Scientific/Engineering :: Mathematics
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy
Requires-Dist: scipy
Requires-Dist: scikit-learn
Requires-Dist: tqdm
Provides-Extra: torch
Requires-Dist: torch; extra == "torch"
Provides-Extra: keops
Requires-Dist: pykeops; extra == "keops"
Provides-Extra: all
Requires-Dist: torch; extra == "all"
Requires-Dist: pykeops; extra == "all"
Provides-Extra: test
Requires-Dist: pytest; extra == "test"
Requires-Dist: torch; extra == "test"
Requires-Dist: pykeops; extra == "test"
Provides-Extra: examples
Requires-Dist: pyvista; extra == "examples"
Provides-Extra: docs
Requires-Dist: furo; extra == "docs"
Requires-Dist: myst-parser; extra == "docs"
Requires-Dist: sphinx>=4; extra == "docs"
Requires-Dist: sphinx-math-dollar; extra == "docs"
Requires-Dist: sphinx-design; extra == "docs"
Dynamic: license-file

# Densemaps : Abstract Correspondence Maps for 3D Geometry

<p align="center">
<img src="img/maps.png">
</p>


[![](https://github.com/RobinMagnet/ScalableDenseMaps/actions/workflows/documentation.yml/badge.svg)](https://robinmagnet.github.io/ScalableDenseMaps/)

Welcome to the documentation of `densemaps` !

A lightweight library that offers:
 1. Unified correspondence representation for 3D objects (surfaces, point clouds) with NumPy and PyTorch support
 2. Memory-efficient dense matrix operations for large-scale geometric maps, based on our recent research [*Memory-Scalable and Simplified Functional Map Learning*](https://arxiv.org/abs/2404.00330).

# Installing

Clone the repository and install it with `pip`:

```bash
git clone https://github.com/RobinMagnet/ScalableDenseMaps.git
cd ScalableDenseMaps
pip install .                 # NumPy backend only (numpy, scipy, scikit-learn, tqdm)
pip install ".[torch]"        # + PyTorch backend
pip install ".[torch,keops]"  # + memory-scalable KernelDistMap (pykeops)
pip install ".[all]"          # everything
```

The NumPy backend has no PyTorch dependency; install the `torch` / `keops` extras only if
you need the PyTorch backend or the memory-scalable `KernelDistMap`.


# Shape Correspondence Representations

> **Note**: Throughout this documentation, maps $T$ go from surface $S_2$ to surface $S_1$ (not the reverse).

This library unifies three common ways to represent correspondences between 3D surfaces $S_1$ and $S_2$ (with $n_1$ and $n_2$ vertices):

 1. **Vertex-to-Vertex Maps**: Direct mapping between vertices, represented as either:
     - An array `p2p_21`$\in [0, \dots, n_1]^{n_2}$, where `p2p_21[i]` indicates which vertex in $S_1$ corresponds to vertex $i$ in $S_2$
     - A binary matrix $\Pi\in\{0,1\}^{n_2\times n_1}$ where $\Pi_{ij}=1$ means vertex $i$ maps to vertex $j$
2. **Vertex-to-Barycentri Maps**: Maps vertices to arbitrary points on surface faces, described by barycentric coordinates:
    - Represented by $\Pi\in[0,1]^{n_2\times nc_1}$ with $\sum_j \Pi_{ij} = 1$
    - Maximum 3 non-zero entries per row, which correspond to vertices of a face
    - More details can be found for example in [this paper](https://onlinelibrary.wiley.com/doi/full/10.1111/cgf.13254)
3. **Soft Maps**: Dense correspondence matrices:
    - $\Pi\in[0,1]^{n_2\times n_1}$ from softmax over similarity scores
    - Example: $\Pi_{ij} = \frac{\exp(S_{ij})}{\sum_j \exp(S_{ij})}$ where $S_{ij}$ measures similarity between embeddings

The common operations across all representations are:
- Converting to vertex-to-vertex maps
- Function transfer via $\Pi f$
- Map composition: $\Pi_{13}=\Pi_{12} \Pi_{23}$

The library implements these representations with both NumPy and PyTorch (CUDA-compatible) backends.

# Example Code

```python
from densemaps.torch import maps

emb1 = # Use some per-vertex embedding for object 1. (N1, p)
emb2 = # Use some per-vertex embedding for object 2. (N2, p)

P21 = maps.KernelDistMap(emb1, emb2, blur=1e-1)  # A "dense" kernel map, not used in memory

# If my embeddings were not on CUDA, I can send them easily and come back to cpu
P21.cuda()
P21.cpu()

uv1 = # Get uv-coordinates on mesh1  (N1, 2)
uv2 = P21 @ uv1  # Transfered uv coordinates (n2, 2)

P21_dense = P21._to_dense() # I can get the (N2, N1) map back

p2p_21 = P21.get_nn()  # I can get the (N2,) vertex to vertex map
```

# Example of usage

The `densemaps` package is used for instance in the following github repositories:
- [Reversible Harmonic Maps](https://github.com/RobinMagnet/ReversibleHarmonicMaps.git) implementation in python
- [Memory Scalable and Simplified Functional Map Learning](https://github.com/RobinMagnet/SimplifiedFmapsLearning.git) implementation

 # Citing this work

 If you use this work, please cite

 ```bibtex
@inproceedings{magnetMemoryScalable2024,
  title = {Memory Scalable and Simplified Functional Map Learning},
  booktitle = {2024 {{IEEE}}/{{CVF Conference}} on {{Computer Vision}} and {{Pattern Recognition}} ({{CVPR}})},
  author = {Magnet, Robin and Ovsjanikov, Maks},
  year = {2024},
  publisher = {IEEE},
}
```
