COACD: Approximate Convex Decomposition for 3D Meshes

1.0.10 · active · verified Fri Apr 17

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.

Common errors

```
ModuleNotFoundError: No module named 'coacd_core'
```
cause The underlying C++ extension (`coacd_core`) failed to compile or load correctly during `pip install coacd`, or its shared library is not discoverable by Python.

fix Ensure you have a C++ compiler installed on your system. Reinstall `coacd` with verbose output: `pip install coacd --verbose`. If build errors appear, address them. On Linux/macOS, check if necessary system libraries are present. On Windows, ensure Visual C++ Build Tools are installed.
```
AttributeError: 'list' object has no attribute 'vertices'
```
cause You are trying to access `.vertices` or `.faces` attributes on a raw Python list, likely when trying to pass mesh data to `coacd.run_coacd` directly from a list of coordinates, instead of a `trimesh.Trimesh` object or NumPy array.

fix Ensure your mesh data is a `trimesh.Trimesh` object or that you are directly passing NumPy arrays: `coacd.run_coacd(np.array(my_vertices), np.array(my_faces), ...)`. If using `trimesh`, ensure the mesh is loaded correctly: `mesh = trimesh.load('path/to/mesh.obj')`.
```
NameError: name 'trimesh' is not defined
```
cause The `trimesh` library, used in the quickstart example for convenient mesh handling, has not been installed.

fix Install `trimesh` using pip: `pip install trimesh`.

Warnings

gotcha COACD 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.
gotcha The `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.
gotcha For 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.

Install

pip install coacd Standard installation
pip install coacd trimesh numpy With common dependencies for mesh handling

Imports

run_coacd
```
import coacd
parts = coacd.run_coacd(vertices, faces, ...)
```
The primary function for performing convex decomposition. It's directly available under the `coacd` module namespace.

Quickstart

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)

view raw JSON →