Registry / ai-ml / coacd
library1.0.11pypypi✓ verified 84d ago

COACD provides a Python interface for Approximate Convex Decomposition (ACD) of 3D meshes, using collision-aware concavity and a tree search algorithm. It's particularly useful for preparing complex geometries for physics simulations or collision detection by breaking them down into simpler convex hulls. The current version is 1.0.10, and releases are typically driven by updates to the underlying C++ library or improvements in the decomposition algorithms.

pip install coacd
INSTALL
IMPORT
SIG · COACD
C
coacd
ai-mlpythonv1.0.11
Install
3.9s avg
Import
255ms
Disk
108MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v1.0.5 · 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.920 runs
installs and imports cleanly · install 0.0s · import 0.242s · 110.9MB
glibc
py 3.103.920 runs
installs and imports cleanly · install 3.9s · import 0.267s · 98MB
108MB installed
● package 108MB
Code
Verified usage

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

run_coacd
from coacd import run_coacd
import coacd

This quickstart demonstrates how to create a simple 3D mesh using `trimesh` and then decompose it into convex parts using `coacd.run_coacd`. The output `parts` is a list where each element is a tuple containing the vertices and faces of a single convex component. The `resolution` parameter is crucial for balancing speed and accuracy.

import trimesh import coacd import numpy as np # Create a simple mesh (e.g., a box) using trimesh mesh = trimesh.primitives.Box() print(f"Original mesh has {len(mesh.vertices)} vertices and {len(mesh.faces)} faces.") # Perform convex decomposition # Parameters like threshold, max_iter, resolution affect decomposition quality and speed parts = coacd.run_coacd( mesh.vertices, # Expected as a (N, 3) numpy array mesh.faces, # Expected as a (M, 3) numpy array threshold=0.05, # Controls concavity threshold (lower for more parts) max_iter=8, # Max iterations for tree search resolution=64, # Voxel grid resolution, lower for faster but less precise render=False, # Set to True to visualize decomposition (requires PyOpenGL) save_meshes=False # Set to True to save individual parts to disk ) print(f"Decomposed into {len(parts)} convex parts.") # Each part is a tuple (vertices, faces) for a convex hull if parts: first_part_vertices, first_part_faces = parts[0] print(f"First part has {len(first_part_vertices)} vertices and {len(first_part_faces)} faces.") # You can reconstruct meshes for each part if needed, e.g., trimesh.Trimesh(v, f)
Debug
Known issues
gotchaCOACD is a Python wrapper around a C++ library. Installation via `pip install coacd` usually provides pre-compiled wheels for common platforms and Python versions. However, if a wheel is not available for your specific environment, pip will attempt to build the C++ extension from source, which requires a C++ compiler (e.g., GCC, Clang, MSVC) and development tools to be installed on your system.
fix
Ensure you have a C++ compiler and build tools installed (e.g., `build-essential` on Debian/Ubuntu, Xcode Command Line Tools on macOS, Visual C++ Build Tools on Windows). If issues persist, refer to the COACD GitHub repository for specific build instructions or pre-compiled binaries.
affects: All versions
gotchaThe `run_coacd` function expects mesh vertices and faces as NumPy arrays of specific shapes (`(N, 3)` for vertices and `(M, 3)` for faces). Providing other data types (like raw Python lists) or incorrect shapes will lead to errors.
fix
Always convert your mesh data to `numpy.ndarray` before passing it to `coacd.run_coacd`. If using libraries like `trimesh`, you can directly access `mesh.vertices` and `mesh.faces` which are already NumPy arrays.
affects: All versions
gotchaFor complex or high-resolution meshes, `coacd.run_coacd` can be computationally intensive and consume significant memory. The `resolution` parameter (voxel grid resolution) directly impacts performance and detail.
fix
Start with a lower `resolution` (e.g., 32 or 64) for initial tests and simpler meshes. Gradually increase it if higher detail is required. Monitor memory and CPU usage. For very large meshes, consider pre-processing steps like mesh decimation or simplifying the input before decomposition.
affects: All versions
Upgrade
Version history
1.0.11latest on PyPI · released May 4, 2026
Audit
Dependencies
trimeshoptionalCommonly used for loading, creating, and manipulating 3D meshes, essential for convenient COACD usage.
numpyrequiredCOACD's `run_coacd` function expects vertices and faces as NumPy arrays.
Agent activity
34 hits · last 30 days
node
28
Amazon
1
OpenAI (training)
1
Resources
coacd — pip install coacd · libregistry