{"id":9593,"library":"coacd","title":"COACD: Approximate Convex Decomposition for 3D Meshes","description":"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.","status":"active","version":"1.0.10","language":"en","source_language":"en","source_url":"https://github.com/isl-org/coacd","tags":["3d","mesh","collision-detection","convex-decomposition","geometry","physics-simulation"],"install":[{"cmd":"pip install coacd","lang":"bash","label":"Standard installation"},{"cmd":"pip install coacd trimesh numpy","lang":"bash","label":"With common dependencies for mesh handling"}],"dependencies":[{"reason":"Commonly used for loading, creating, and manipulating 3D meshes, essential for convenient COACD usage.","package":"trimesh","optional":true},{"reason":"COACD's `run_coacd` function expects vertices and faces as NumPy arrays.","package":"numpy","optional":false}],"imports":[{"note":"The primary function for performing convex decomposition. It's directly available under the `coacd` module namespace.","symbol":"run_coacd","correct":"import coacd\nparts = coacd.run_coacd(vertices, faces, ...)"}],"quickstart":{"code":"import trimesh\nimport coacd\nimport numpy as np\n\n# Create a simple mesh (e.g., a box) using trimesh\nmesh = trimesh.primitives.Box()\n\nprint(f\"Original mesh has {len(mesh.vertices)} vertices and {len(mesh.faces)} faces.\")\n\n# Perform convex decomposition\n# Parameters like threshold, max_iter, resolution affect decomposition quality and speed\nparts = coacd.run_coacd(\n    mesh.vertices, # Expected as a (N, 3) numpy array\n    mesh.faces,    # Expected as a (M, 3) numpy array\n    threshold=0.05, # Controls concavity threshold (lower for more parts)\n    max_iter=8,     # Max iterations for tree search\n    resolution=64,  # Voxel grid resolution, lower for faster but less precise\n    render=False,   # Set to True to visualize decomposition (requires PyOpenGL)\n    save_meshes=False # Set to True to save individual parts to disk\n)\n\nprint(f\"Decomposed into {len(parts)} convex parts.\")\n\n# Each part is a tuple (vertices, faces) for a convex hull\nif parts:\n    first_part_vertices, first_part_faces = parts[0]\n    print(f\"First part has {len(first_part_vertices)} vertices and {len(first_part_faces)} faces.\")\n    # You can reconstruct meshes for each part if needed, e.g., trimesh.Trimesh(v, f)","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"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.","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.","error":"ModuleNotFoundError: No module named 'coacd_core'"},{"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')`.","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.","error":"AttributeError: 'list' object has no attribute 'vertices'"},{"fix":"Install `trimesh` using pip: `pip install trimesh`.","cause":"The `trimesh` library, used in the quickstart example for convenient mesh handling, has not been installed.","error":"NameError: name 'trimesh' is not defined"}]}