{"id":18339913,"url":"https://github.com/mxagar/voxel_point_collision_detection","last_synced_at":"2026-05-09T14:10:47.771Z","repository":{"id":236139018,"uuid":"791994133","full_name":"mxagar/voxel_point_collision_detection","owner":"mxagar","description":"Collision detection between voxelized and point-sampled objects following the Voxelmap Pointshell Algorithm by McNeely et al.","archived":false,"fork":false,"pushed_at":"2024-05-03T08:59:33.000Z","size":723,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-02-15T12:49:48.985Z","etag":null,"topics":["3d","collision-detection","computational-geometry","force-computation","meshes","physics","robotics","simulation"],"latest_commit_sha":null,"homepage":"","language":"Jupyter Notebook","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mxagar.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-04-25T19:11:13.000Z","updated_at":"2024-05-03T08:59:36.000Z","dependencies_parsed_at":"2024-05-03T09:59:49.109Z","dependency_job_id":"d0cdf756-1be8-4745-8013-66d8478b99ae","html_url":"https://github.com/mxagar/voxel_point_collision_detection","commit_stats":null,"previous_names":["mxagar/voxel_point_collision_detection"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mxagar%2Fvoxel_point_collision_detection","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mxagar%2Fvoxel_point_collision_detection/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mxagar%2Fvoxel_point_collision_detection/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mxagar%2Fvoxel_point_collision_detection/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mxagar","download_url":"https://codeload.github.com/mxagar/voxel_point_collision_detection/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248109288,"owners_count":21049281,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["3d","collision-detection","computational-geometry","force-computation","meshes","physics","robotics","simulation"],"created_at":"2024-11-05T20:19:49.514Z","updated_at":"2026-05-09T14:10:47.757Z","avatar_url":"https://github.com/mxagar.png","language":"Jupyter Notebook","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Voxelmap-Pointshell Collision Detection in Python\n\nThis 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/).\n\nThe current package provides:\n\n- mesh loading into package-owned NumPy arrays\n- integer voxelmap generation\n- hierarchical pointshell generation\n- proximity queries between a transformed pointshell and a voxelmap\n- penalty-based collision detection with force and torque accumulation\n- simple `trimesh` scene builders for visualization\n\nThe 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.\n\nMost of the code was generated by [OpenAI Codex GPT 5.4 Medium](https://openai.com/codex/); see [`Prompts.md`](./Prompts.md).\n\n## Installation\n\n```bash\n# Create conda env\nconda env create -f conda.yaml\nconda activate vps\n\n# ... or create venv in your running Python distro\npython -m venv .venv\nsource .venv/bin/activate\n\n# Then, install dependencies\npython -m pip install -U pip\npython -m pip install -U pip-tools\npip-compile requirements.in\npython -m pip install -r requirements.txt\npython -m pip install -e .\n```\n\n### Development tools\n\nThe repository includes `pytest`, `flake8`, and `pytype` in `requirements.txt`.\n\nValidation commands:\n\n```bash\npytest -q\nflake8 src tests\npytype src\n```\n\n## Project Layout\n\n- [src/](./src): package source code\n- [tests/](./tests): pytest suite\n- [notebooks/](./notebooks): exploratory notebooks and usage examples\n- [data/models/](./data/models): sample meshes\n- [doc/Sagardia_PhD_Chapter3_Summary.md](./doc/Sagardia_PhD_Chapter3_Summary.md): implementation-oriented technical summary of the reference chapter\n\n## Minor Usage Examples\n\n### Load a mesh\n\n```python\nfrom src.mesh import Mesh\n\nmesh = Mesh.from_file(\"data/models/monkey.stl\")\nprint(mesh.vertex_count, mesh.triangle_count)\nprint(mesh.bounds)\n```\n\n### Generate a voxelmap and pointshell\n\n```python\nfrom src.generate_pointshell import generate_pointshell\nfrom src.generate_voxelmap import generate_voxelmap\n\nvoxelmap = generate_voxelmap(mesh, voxel_size=0.2)\npointshell = generate_pointshell(mesh, voxel_size=0.2, target_spheres=32)\n\nprint(voxelmap.shape)\nprint(pointshell.point_count, pointshell.sphere_count)\n```\n\n### Run a proximity query\n\n```python\nimport numpy as np\n\nfrom src.proximity_query import proximity_query\n\ntransform = np.eye(4)\ntransform[:3, 3] = np.array([0.1, 0.0, 0.0])\n\nquery = proximity_query(\n    voxelmap,\n    pointshell,\n    transform=transform,\n    n=5,\n    sphere_percentage=0.5,\n    point_percentage=0.5,\n)\n\nfor hit in query.hits:\n    print(hit.point_id, hit.sphere_id, hit.signed_distance)\n```\n\n### Run a collision query\n\n```python\nfrom src.collision_detection import detect_collision\n\ncollision = detect_collision(\n    voxelmap,\n    pointshell,\n    transform=transform,\n    stiffness=2.0,\n)\n\nprint(collision.is_colliding)\nprint(collision.total_force)\nprint(collision.total_torque)\n```\n\n### Build visualization scenes\n\n```python\nfrom src.viewer import (\n    create_mesh_scene,\n    create_pointshell_scene,\n    create_query_scene,\n    create_voxelmap_scene,\n)\n\nmesh_scene = create_mesh_scene(mesh)\nvoxel_scene = create_voxelmap_scene(voxelmap)\npointshell_scene = create_pointshell_scene(pointshell)\nquery_scene = create_query_scene(voxelmap, pointshell, query, transform=transform)\n\n# In a local interactive session:\n# mesh_scene.show()\n# voxel_scene.show()\n# pointshell_scene.show()\n# query_scene.show()\n```\n\n## Notebook Example\n\nA small end-to-end notebook is available at [notebooks/usage_examples.ipynb](./notebooks/usage_examples.ipynb). It covers:\n\n- generation\n- visualization\n- proximity queries\n- collision queries\n- serialization\n\n## Notes and Limitations\n\n- The current voxelmap stores only the integer layer field.\n- Pointshell generation currently uses surface voxel centers and voxel-gradient normals.\n- The hierarchical traversal is intentionally simple and compatible with later refinement.\n- This is a research/prototyping codebase, not yet a production collision engine.\n\n## References\n\n- [McNeely et al., 1999](https://www.semanticscholar.org/paper/Six-degree-of-freedom-haptic-rendering-using-voxel-McNeely-Puterbaugh/5f5fa4fd695d72fea792f2daccd86244e8b192e7) original VPS work.\n- 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)\n- `trimesh`: https://github.com/mikedh/trimesh\n\n## Authorship\n\nMikel Sagardia, 2024.  \nNo guarantees.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmxagar%2Fvoxel_point_collision_detection","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmxagar%2Fvoxel_point_collision_detection","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmxagar%2Fvoxel_point_collision_detection/lists"}