https://github.com/mxagar/voxel_point_collision_detection
Collision detection between voxelized and point-sampled objects following the Voxelmap Pointshell Algorithm by McNeely et al.
https://github.com/mxagar/voxel_point_collision_detection
3d collision-detection computational-geometry force-computation meshes physics robotics simulation
Last synced: about 2 months ago
JSON representation
Collision detection between voxelized and point-sampled objects following the Voxelmap Pointshell Algorithm by McNeely et al.
- Host: GitHub
- URL: https://github.com/mxagar/voxel_point_collision_detection
- Owner: mxagar
- Created: 2024-04-25T19:11:13.000Z (about 2 years ago)
- Default Branch: main
- Last Pushed: 2024-05-03T08:59:33.000Z (about 2 years ago)
- Last Synced: 2025-02-15T12:49:48.985Z (over 1 year ago)
- Topics: 3d, collision-detection, computational-geometry, force-computation, meshes, physics, robotics, simulation
- Language: Jupyter Notebook
- Homepage:
- Size: 706 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Voxelmap-Pointshell Collision Detection in Python
This repository contains a Python-first reimplementation of a voxelmap-pointshell proximity and collision framework inspired by the [collision detection approach describe in a chapter of my thesis](https://elib.dlr.de/132879/).
The current package provides:
- mesh loading into package-owned NumPy arrays
- integer voxelmap generation
- hierarchical pointshell generation
- proximity queries between a transformed pointshell and a voxelmap
- penalty-based collision detection with force and torque accumulation
- simple `trimesh` scene builders for visualization
The implementation is intentionally centered on NumPy-backed data structures and explicit geometry logic. `trimesh` is used for mesh IO and visualization support, not for the core runtime query pipeline.
Most of the code was generated by [OpenAI Codex GPT 5.4 Medium](https://openai.com/codex/); see [`Prompts.md`](./Prompts.md).
## Installation
```bash
# Create conda env
conda env create -f conda.yaml
conda activate vps
# ... or create venv in your running Python distro
python -m venv .venv
source .venv/bin/activate
# Then, install dependencies
python -m pip install -U pip
python -m pip install -U pip-tools
pip-compile requirements.in
python -m pip install -r requirements.txt
python -m pip install -e .
```
### Development tools
The repository includes `pytest`, `flake8`, and `pytype` in `requirements.txt`.
Validation commands:
```bash
pytest -q
flake8 src tests
pytype src
```
## Project Layout
- [src/](./src): package source code
- [tests/](./tests): pytest suite
- [notebooks/](./notebooks): exploratory notebooks and usage examples
- [data/models/](./data/models): sample meshes
- [doc/Sagardia_PhD_Chapter3_Summary.md](./doc/Sagardia_PhD_Chapter3_Summary.md): implementation-oriented technical summary of the reference chapter
## Minor Usage Examples
### Load a mesh
```python
from src.mesh import Mesh
mesh = Mesh.from_file("data/models/monkey.stl")
print(mesh.vertex_count, mesh.triangle_count)
print(mesh.bounds)
```
### Generate a voxelmap and pointshell
```python
from src.generate_pointshell import generate_pointshell
from src.generate_voxelmap import generate_voxelmap
voxelmap = generate_voxelmap(mesh, voxel_size=0.2)
pointshell = generate_pointshell(mesh, voxel_size=0.2, target_spheres=32)
print(voxelmap.shape)
print(pointshell.point_count, pointshell.sphere_count)
```
### Run a proximity query
```python
import numpy as np
from src.proximity_query import proximity_query
transform = np.eye(4)
transform[:3, 3] = np.array([0.1, 0.0, 0.0])
query = proximity_query(
voxelmap,
pointshell,
transform=transform,
n=5,
sphere_percentage=0.5,
point_percentage=0.5,
)
for hit in query.hits:
print(hit.point_id, hit.sphere_id, hit.signed_distance)
```
### Run a collision query
```python
from src.collision_detection import detect_collision
collision = detect_collision(
voxelmap,
pointshell,
transform=transform,
stiffness=2.0,
)
print(collision.is_colliding)
print(collision.total_force)
print(collision.total_torque)
```
### Build visualization scenes
```python
from src.viewer import (
create_mesh_scene,
create_pointshell_scene,
create_query_scene,
create_voxelmap_scene,
)
mesh_scene = create_mesh_scene(mesh)
voxel_scene = create_voxelmap_scene(voxelmap)
pointshell_scene = create_pointshell_scene(pointshell)
query_scene = create_query_scene(voxelmap, pointshell, query, transform=transform)
# In a local interactive session:
# mesh_scene.show()
# voxel_scene.show()
# pointshell_scene.show()
# query_scene.show()
```
## Notebook Example
A small end-to-end notebook is available at [notebooks/usage_examples.ipynb](./notebooks/usage_examples.ipynb). It covers:
- generation
- visualization
- proximity queries
- collision queries
- serialization
## Notes and Limitations
- The current voxelmap stores only the integer layer field.
- Pointshell generation currently uses surface voxel centers and voxel-gradient normals.
- The hierarchical traversal is intentionally simple and compatible with later refinement.
- This is a research/prototyping codebase, not yet a production collision engine.
## References
- [McNeely et al., 1999](https://www.semanticscholar.org/paper/Six-degree-of-freedom-haptic-rendering-using-voxel-McNeely-Puterbaugh/5f5fa4fd695d72fea792f2daccd86244e8b192e7) original VPS work.
- My [PhD](https://elib.dlr.de/132879/), specifically, [Chapter 3](./doc/Sagardia_PhD_Chapter3_2019.pdf), which is summarized in [doc/Sagardia_PhD_Chapter3_Summary.md](./doc/Sagardia_PhD_Chapter3_Summary.md)
- `trimesh`: https://github.com/mikedh/trimesh
## Authorship
Mikel Sagardia, 2024.
No guarantees.