coal

What it is and what it does

Coal is a modern collision detection library descended from the Flexible Collision Library (FCL), significantly rewritten since its 2015 fork and renamed in 2024. It implements dedicated, efficient versions of the GJK and EPA algorithms for narrow-phase collision detection and distance computation between 3D geometric objects. The library supports a wide range of primitives (boxes, spheres, capsules, cylinders, ellipsoids, cones, planes) and complex geometries (convex meshes, bounding volume hierarchies, height fields, octrees), and includes Python bindings for prototyping.

The package is built on top of several compiled dependencies (Boost, Assimp, OctoMap, Qhull via cmeel, plus eigenpy and libcoal), making installation medium-friction but straightforward via conda-forge. It is actively maintained, used in production robotics frameworks (Pinocchio, HPP, Crocoddyl), and offers features like safety margins, accelerated collision detection variants, contact point/patch computation, and object serialization. No known security vulnerabilities are recorded.

Use it for:

• Collision detection in robotics motion planning and path planning algorithms to ensure safe trajectories.
• Distance computation between rigid bodies in physics simulation and dynamics engines.
• Contact point and contact patch calculation for grasp planning and manipulation tasks.
• Broad and narrow phase collision checking with safety margins in real-time control loops.
• Geometry queries in CAD and BVH-based spatial indexing for complex 3D scenes.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Coal is a collision detection and distance computation library that provides efficient GJK and EPA algorithm implementations for detecting collisions and computing distances between 3D geometric objects.

Yes, if you need collision detection and distance computation in robotics, physics simulation, or 3D geometry applications. The library is actively maintained, permissively licensed, has no known vulnerabilities, and is already trusted in production robotics frameworks. Install friction is moderate due to compiled dependencies, but conda-forge handles this transparently. Not suitable if you need a pure-Python solution or lightweight geometry library without external C++ dependencies.

Install

coal on PyPI

pip install coal

uv add coal

poetry add coal

Installing coal

Before you install

Medium install friction due to 7 runtime dependencies including cmeel packages (cmeel, cmeel-assimp, cmeel-boost, cmeel-octomap, cmeel-qhull), eigenpy, and libcoal. Prebuilt wheels available for Python 3.10–3.14 on macOS and Linux. Active maintenance with recent releases.

License in practice

BSD-3-Clause permissive license allows commercial and private use with minimal restrictions; you must include a copy of the license and retain copyright notices.

Quickstart

pip install coal

import coal

# Create shapes and perform collision detection
shape1 = coal.Ellipsoid(0.7, 1.0, 0.8)
shape2 = coal.Box(1.0, 1.0, 1.0)

# Define transforms and check collision
request = coal.CollisionRequest()
result = coal.CollisionResult()
coal.collide(shape1, coal.Transform3s.Identity(), shape2, coal.Transform3s.Identity(), request, result)

Requires Python >= 3.9. Runtime dependencies (cmeel packages, eigenpy, libcoal) must be installed; conda install from conda-forge is recommended to handle these automatically.

Verify before relying

• Whether Python bindings cover the full C++ API surface or a subset of collision/distance operations.
• Performance characteristics of the accelerated GJK variants mentioned in the description for typical use cases.
• Whether safety margins and contact patch computation are exposed in the Python API.
• Documentation availability and completeness for Python users.

Package facts

Evidence: coal-3.0.3-0-cp310-cp310-macosx_10_9_x86_64.whl; coal-3.0.3-0-cp310-cp310-macosx_11_0_arm64.whl; coal-3.0.3-0-cp310-cp310-manylinux_2_28_aarch64.whl; coal-3.0.3-0-cp310-cp310-manylinux_2_28_x86_64.whl; coal-3.0.3-0-cp311-cp311-macosx_10_9_x86_64.whl; coal-3.0.3-0-cp311-cp311-macosx_11_0_arm64.whl; coal-3.0.3-0-cp311-cp311-manylinux_2_28_aarch64.whl; coal-3.0.3-0-cp311-cp311-manylinux_2_28_x86_64.whl; coal-3.0.3-0-cp312-cp312-macosx_10_9_x86_64.whl; coal-3.0.3-0-cp312-cp312-macosx_11_0_arm64.whl; coal-3.0.3-0-cp312-cp312-manylinux_2_28_aarch64.whl; coal-3.0.3-0-cp312-cp312-manylinux_2_28_x86_64.whl; coal-3.0.3-0-cp313-cp313-macosx_10_9_x86_64.whl; coal-3.0.3-0-cp313-cp313-macosx_11_0_arm64.whl; coal-3.0.3-0-cp313-cp313-manylinux_2_28_aarch64.whl; coal-3.0.3-0-cp313-cp313-manylinux_2_28_x86_64.whl; coal-3.0.3-0-cp314-cp314-macosx_10_9_x86_64.whl; coal-3.0.3-0-cp314-cp314-macosx_11_0_arm64.whl; coal-3.0.3-0-cp314-cp314-manylinux_2_28_aarch64.whl; coal-3.0.3-0-cp314-cp314-manylinux_2_28_x86_64.whl

Tags

More Scientific/Engineering packages