{"id":3851,"library":"vhacdx","title":"VHACD Python Bindings","description":"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.","status":"active","version":"0.0.10","language":"en","source_language":"en","source_url":"https://github.com/trimesh/vhacdx","tags":["3D","mesh","geometry","convex decomposition","collision detection","trimesh"],"install":[{"cmd":"pip install vhacdx","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Required for handling mesh vertices and faces as numerical arrays.","package":"numpy","optional":false},{"reason":"Commonly used for generating, loading, and visualizing 3D mesh data, often used as input for vhacdx.vhacd.","package":"trimesh","optional":true}],"imports":[{"symbol":"vhacd","correct":"from vhacdx import vhacd"},{"symbol":"vhacdx","correct":"import vhacdx"}],"quickstart":{"code":"import numpy as np\nimport vhacdx\nimport trimesh # Used to generate example mesh\n\n# 1. Create a sample mesh (e.g., a simple box)\n# For a more complex shape, you might load from a file: mesh = trimesh.load('your_mesh.obj')\nmesh = trimesh.creation.box()\nvertices = mesh.vertices.astype(np.float64) # VHACD expects float64\nfaces = mesh.faces.astype(np.int32)       # VHACD expects int32\n\nprint(f\"Original mesh has {len(vertices)} vertices and {len(faces)} faces.\")\n\n# 2. Perform convex decomposition\n# Parameters like 'resolution' and 'depth' significantly impact quality and performance.\n# Consult the underlying VHACD C++ library documentation for detailed parameter explanations.\ndecomposed_hulls = vhacdx.vhacd(\n    vertices=vertices,\n    faces=faces,\n    resolution=100000, # Max voxels generated during voxelization (default 100,000)\n    depth=8            # Max recursion depth for the V-HACD algorithm (default 8)\n)\n\n# 3. Process the output\nprint(f\"Decomposed into {len(decomposed_hulls)} convex hulls.\")\n\n# Each hull is a dictionary containing its own 'vertices' and 'faces'\nfor i, hull in enumerate(decomposed_hulls):\n    hull_vertices = hull['vertices']\n    hull_faces = hull['faces']\n    print(f\"  Hull {i}: {len(hull_vertices)} vertices, {len(hull_faces)} faces\")\n\n    # You could then, for example, create trimesh objects for each hull:\n    # hull_mesh = trimesh.Trimesh(vertices=hull_vertices, faces=hull_faces)\n    # hull_mesh.show() # To visualize each hull separately\n","lang":"python","description":"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."},"warnings":[{"fix":"Ensure `mesh.vertices.astype(np.float64)` and `mesh.faces.astype(np.int32)` before passing to `vhacdx.vhacd`.","message":"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.","severity":"gotcha","affected_versions":"0.0.1 to 0.0.10"},{"fix":"Pin the library version in your `requirements.txt` (`vhacdx==0.0.10`) and thoroughly test your application after any version upgrade.","message":"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.","severity":"gotcha","affected_versions":"0.0.1 to 0.0.10"},{"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.","message":"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.","severity":"gotcha","affected_versions":"0.0.1 to 0.0.10"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}