---
id: coal
version: "3.0.3"
license: BSD-3-Clause
license_treatment: permissive
maintenance: active
---

# coal — An extension of the Flexible Collision Library

License: permissive · Maintenance: active · Downloads: 619.4K/mo

## 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 above — 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

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

- License: BSD-3-Clause (permissive)
- Python support: supports_current
- Install friction: medium
- Maintenance: active
- Downloads: 619.4K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

collision detection library, distance computation geometry, GJK algorithm implementation, 3D object collision checking, rigid body collision detection, geometric proximity queries, convex shape collision, collision-detection, robotics, computational-geometry

[View on SkillFed](https://skillfed.io/packages/coal) · [View on PyPI](https://pypi.org/project/coal/)