# 🖼️ Framesh
A collection of robust Local Reference Frame (LRF) algorithms for 3D mesh patches.
## Overview
Framesh provides efficient implementations of several state-of-the-art Local Reference Frame
computation methods for 3D meshes. LRFs are essential for creating rotation-invariant local surface
descriptors and establishing repeatable coordinate systems on 3D surfaces. The library has minimal
dependencies, requiring only NumPy for computation and Trimesh for mesh handling.
## Installation
Framesh is available on PyPI and can be installed using pip:
```bash
python -m pip install framesh
```
## Usage
Each LRF method follows a consistent API:
```python
import trimesh
from framesh import shot_lrf
# Load your mesh
mesh = trimesh.load('your_mesh.obj')
# Compute LRF for vertex index 0 with default parameters
lrf = shot_lrf(mesh, vertex_index=0, radius=1.0)
# The result is a 3x3 matrix where columns are [x-axis, y-axis, z-axis]
print(lrf)
```
Each method also comes with a vectorized version for computing LRFs on multiple vertices simultaneously, offering better performance for batch processing:
```python
import trimesh
import numpy as np
from framesh import shot_frames
# Load your mesh
mesh = trimesh.load('your_mesh.obj')
# Compute LRFs for multiple vertices
vertex_indices = np.array([0, 1, 2, 3]) # compute LRFs for first 4 vertices
lrfs = shot_frames(mesh, vertex_indices=vertex_indices, radius=1.0)
# The result is a batch of 3x3 matrices with shape (n_vertices, 3, 3)
print(lrfs.shape) # outputs: (4, 3, 3)
```
## Implemented Methods
- **SHOT**
- Implementation of the LRF computation from the SHOT (Signature of Histograms of
OrienTations) descriptor. Uses weighted covariance analysis to establish a robust
coordinate system.
- *Reference:* Tombari et al., "Unique signatures of histograms for local surface
description." ECCV 2010.
- **BOARD**
- Board method for LRF computation. Creates a robust coordinate system using plane fitting
and normal-based point selection strategies.
- *Reference:* Petrelli & Di Stefano, "On the repeatability of the local reference frame
for partial shape matching." ICCV 2011.
- **FLARE**
- Fast Local Axis Reference Extraction method. Combines plane fitting for z-axis computation
with a distance-based point selection strategy for x-axis determination.
- *Reference:* Petrelli & Di Stefano, "A Repeatable and Efficient Canonical Reference for
Surface Matching." 3DIMPVT 2012.
- **ROPS**
- Rotational Projection Statistics-based LRF computation. Utilizes face areas and distances
to construct a weighted scatter matrix for axis determination.
- *Reference:* Guo et al., "A local feature descriptor for 3D rigid objects based on
rotational projection statistics." ICCSPA 2013.
- **TOLDI**
- Triangular-based Overlapping Local Depth Images LRF computation. Uses a combination of PCA
and projection-based weighting for robust axis determination.
- *Reference:* Yang et al., "TOLDI: An effective and robust approach for 3D local shape
description." Pattern Recognition 2017.
- **GFrames**
- Gradient-based local reference frame computation. Utilizes the gradient of a scalar field
defined on the mesh surface to determine axis directions.
- *Reference:* Melzi et al., "GFrames: Gradient-based local reference frame for 3D shape
matching." CVPR 2019.
## Citation
If you use this code in your research, please cite:
```bibtex
@software{grementieri2024framesh,
author = {Grementieri, Luca},
title = {Framesh: A Collection of Local Reference Frame Algorithms for 3D Mesh Patches},
year = {2024},
publisher = {GitHub},
url = {https://github.com/lucagrementieri/framesh},
note = {A library implementing multiple classical Local Reference Frame (LRF) algorithms}
}
```
Raw data
{
"_id": null,
"home_page": null,
"name": "framesh",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "3d, mesh, geometry, local-reference-frame, computer-graphics, computational-geometry, point-cloud",
"author": null,
"author_email": "Luca Grementieri <luca.grementieri@ens-paris-saclay.fr>",
"download_url": null,
"platform": null,
"description": "# \ud83d\uddbc\ufe0f Framesh \n\nA collection of robust Local Reference Frame (LRF) algorithms for 3D mesh patches.\n\n## Overview\n\nFramesh provides efficient implementations of several state-of-the-art Local Reference Frame \ncomputation methods for 3D meshes. LRFs are essential for creating rotation-invariant local surface \ndescriptors and establishing repeatable coordinate systems on 3D surfaces. The library has minimal \ndependencies, requiring only NumPy for computation and Trimesh for mesh handling.\n\n## Installation\n\nFramesh is available on PyPI and can be installed using pip:\n\n```bash\npython -m pip install framesh\n``` \n\n## Usage\n\nEach LRF method follows a consistent API:\n\n```python\nimport trimesh\nfrom framesh import shot_lrf\n\n# Load your mesh\nmesh = trimesh.load('your_mesh.obj')\n# Compute LRF for vertex index 0 with default parameters\nlrf = shot_lrf(mesh, vertex_index=0, radius=1.0)\n# The result is a 3x3 matrix where columns are [x-axis, y-axis, z-axis]\nprint(lrf)\n```\n\nEach method also comes with a vectorized version for computing LRFs on multiple vertices simultaneously, offering better performance for batch processing:\n\n```python\nimport trimesh\nimport numpy as np\nfrom framesh import shot_frames\n\n# Load your mesh\nmesh = trimesh.load('your_mesh.obj')\n# Compute LRFs for multiple vertices\nvertex_indices = np.array([0, 1, 2, 3]) # compute LRFs for first 4 vertices\nlrfs = shot_frames(mesh, vertex_indices=vertex_indices, radius=1.0)\n# The result is a batch of 3x3 matrices with shape (n_vertices, 3, 3)\nprint(lrfs.shape) # outputs: (4, 3, 3)\n```\n\n## Implemented Methods\n\n- **SHOT**\n - Implementation of the LRF computation from the SHOT (Signature of Histograms of \n OrienTations) descriptor. Uses weighted covariance analysis to establish a robust \n coordinate system.\n - *Reference:* Tombari et al., \"Unique signatures of histograms for local surface \n description.\" ECCV 2010.\n\n- **BOARD**\n - Board method for LRF computation. Creates a robust coordinate system using plane fitting \n and normal-based point selection strategies.\n - *Reference:* Petrelli & Di Stefano, \"On the repeatability of the local reference frame \n for partial shape matching.\" ICCV 2011.\n\n- **FLARE**\n - Fast Local Axis Reference Extraction method. Combines plane fitting for z-axis computation \n with a distance-based point selection strategy for x-axis determination.\n - *Reference:* Petrelli & Di Stefano, \"A Repeatable and Efficient Canonical Reference for \n Surface Matching.\" 3DIMPVT 2012.\n\n- **ROPS**\n - Rotational Projection Statistics-based LRF computation. Utilizes face areas and distances \n to construct a weighted scatter matrix for axis determination.\n - *Reference:* Guo et al., \"A local feature descriptor for 3D rigid objects based on \n rotational projection statistics.\" ICCSPA 2013.\n\n- **TOLDI**\n - Triangular-based Overlapping Local Depth Images LRF computation. Uses a combination of PCA \n and projection-based weighting for robust axis determination.\n - *Reference:* Yang et al., \"TOLDI: An effective and robust approach for 3D local shape \n description.\" Pattern Recognition 2017.\n\n- **GFrames**\n - Gradient-based local reference frame computation. Utilizes the gradient of a scalar field \n defined on the mesh surface to determine axis directions.\n - *Reference:* Melzi et al., \"GFrames: Gradient-based local reference frame for 3D shape \n matching.\" CVPR 2019.\n\n## Citation\n\nIf you use this code in your research, please cite:\n\n```bibtex\n@software{grementieri2024framesh,\n author = {Grementieri, Luca},\n title = {Framesh: A Collection of Local Reference Frame Algorithms for 3D Mesh Patches},\n year = {2024},\n publisher = {GitHub},\n url = {https://github.com/lucagrementieri/framesh},\n note = {A library implementing multiple classical Local Reference Frame (LRF) algorithms}\n}\n```\n",
"bugtrack_url": null,
"license": null,
"summary": "Local reference frame algorithms for meshes",
"version": "0.3",
"project_urls": {
"Issues": "https://github.com/lucagrementieri/framesh/issues",
"Repository": "https://github.com/lucagrementieri/framesh"
},
"split_keywords": [
"3d",
" mesh",
" geometry",
" local-reference-frame",
" computer-graphics",
" computational-geometry",
" point-cloud"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "d6e9aa356d7e66e9fe5feb94f65d52cc1f0041e4b7475c4ff9585cdb852ec083",
"md5": "7a7eeeeb111c654ca0bff12f63238981",
"sha256": "0ce6ccf5c91e0c15c133861fe352baf608aa114363529b5011ab4f03f46f43e4"
},
"downloads": -1,
"filename": "framesh-0.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "7a7eeeeb111c654ca0bff12f63238981",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 22865,
"upload_time": "2025-01-03T09:16:04",
"upload_time_iso_8601": "2025-01-03T09:16:04.607254Z",
"url": "https://files.pythonhosted.org/packages/d6/e9/aa356d7e66e9fe5feb94f65d52cc1f0041e4b7475c4ff9585cdb852ec083/framesh-0.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-01-03 09:16:04",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "lucagrementieri",
"github_project": "framesh",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "networkx",
"specs": [
[
"==",
"3.4.2"
]
]
},
{
"name": "numpy",
"specs": [
[
"==",
"2.2.1"
]
]
},
{
"name": "scipy",
"specs": [
[
"==",
"1.14.1"
]
]
},
{
"name": "shapely",
"specs": [
[
"==",
"2.0.6"
]
]
},
{
"name": "trimesh",
"specs": [
[
"==",
"4.5.3"
]
]
}
],
"lcname": "framesh"
}
JSON
