Registry / ai-ml / vhacdx

vhacdx

JSON →
library0.0.10pypypi✓ verified 24d ago

Python bindings for the V-HACD (Volumetric Hierarchical Approximate Convex Decomposition) C++ library. It enables the decomposition of complex 3D meshes into a set of convex components, which is highly useful for physics engines, collision detection, and simplified mesh representation. The current version is 0.0.10, and it appears to be actively maintained by the Trimesh organization, though with an infrequent release cadence.

pip install vhacdx
INSTALL
IMPORT
SIG · VHACDX
V
vhacdx
ai-mlpythonv0.0.10
Install
3.7s avg
Import
10ms
Disk
92MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v0.0.10 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.95 runs
installs and imports cleanly · install 0.0s · import 0.000s · 93.7MB
glibc
py 3.103.95 runs
installs and imports cleanly · install 3.7s · import 0.002s · 86MB
92MB installed
● package 92MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

compute_vhacd
from vhacdx import compute_vhacd
from vhacdx import vhacd

This example demonstrates how to perform convex decomposition on a simple `trimesh` box. It highlights the expected NumPy array types for vertices (float64) and faces (int32) and how to access the individual convex hulls from the output list.

import numpy as np import vhacdx import trimesh # Used to generate example mesh # 1. Create a sample mesh (e.g., a simple box) # For a more complex shape, you might load from a file: mesh = trimesh.load('your_mesh.obj') mesh = trimesh.creation.box() vertices = mesh.vertices.astype(np.float64) # VHACD expects float64 faces = mesh.faces.astype(np.int32) # VHACD expects int32 print(f"Original mesh has {len(vertices)} vertices and {len(faces)} faces.") # 2. Perform convex decomposition # Parameters like 'resolution' and 'depth' significantly impact quality and performance. # Consult the underlying VHACD C++ library documentation for detailed parameter explanations. decomposed_hulls = vhacdx.vhacd( vertices=vertices, faces=faces, resolution=100000, # Max voxels generated during voxelization (default 100,000) depth=8 # Max recursion depth for the V-HACD algorithm (default 8) ) # 3. Process the output print(f"Decomposed into {len(decomposed_hulls)} convex hulls.") # Each hull is a dictionary containing its own 'vertices' and 'faces' for i, hull in enumerate(decomposed_hulls): hull_vertices = hull['vertices'] hull_faces = hull['faces'] print(f" Hull {i}: {len(hull_vertices)} vertices, {len(hull_faces)} faces") # You could then, for example, create trimesh objects for each hull: # hull_mesh = trimesh.Trimesh(vertices=hull_vertices, faces=hull_faces) # hull_mesh.show() # To visualize each hull separately
Debug
Known issues
gotchaInput mesh data (vertices and faces) must be provided as NumPy arrays with specific data types: vertices as `np.float64` and faces as `np.int32`. Incorrect types will lead to errors or unexpected behavior.
fix
Ensure `mesh.vertices.astype(np.float64)` and `mesh.faces.astype(np.int32)` before passing to `vhacdx.vhacd`.
affects: 0.0.1 to 0.0.10
gotchaAs a library in early development (version 0.0.x), the API may be subject to changes even in minor releases. Breaking changes might occur without explicit deprecation warnings typically found in more mature libraries.
fix
Pin the library version in your `requirements.txt` (`vhacdx==0.0.10`) and thoroughly test your application after any version upgrade.
affects: 0.0.1 to 0.0.10
gotchaThe performance and quality of the decomposition are highly dependent on the parameters passed to `vhacdx.vhacd` (e.g., `resolution`, `depth`, `concavity`). Poorly chosen parameters can result in extremely slow execution, excessive memory usage, or unsatisfactory decomposition results.
fix
Experiment with parameters, starting with conservative values. Consult the VHACD C++ documentation for a deeper understanding of each parameter's effect on the algorithm.
affects: 0.0.1 to 0.0.10
Upgrade
Version history
0.0.10latest on PyPI · released Dec 2, 2025
Audit
Dependencies
numpyrequiredRequired for handling mesh vertices and faces as numerical arrays.
trimeshoptionalCommonly used for generating, loading, and visualizing 3D mesh data, often used as input for vhacdx.vhacd.
Agent activity
43 hits · last 30 days
node
40
OpenAI (training)
1
Resources
vhacdx — pip install vhacdx · libregistry