VHACD Python Bindings

0.0.10 · active · verified Sat Apr 11

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.

Warnings

gotcha Input 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`.
gotcha As 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.
gotcha The 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.

Install

pip install vhacdx Install latest version

Imports

vhacd
```
from vhacdx import vhacd
```
vhacdx
```
import vhacdx
```

Quickstart

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

view raw JSON →