coal-library

What it is and what it does

Coal is a collision detection and distance computation library for 3D rigid bodies, forked and substantially rewritten from the Flexible Collision Library (FCL) since 2015 and renamed in 2024. It implements optimized GJK and EPA algorithms for narrow-phase collision detection, supports safety margins, computes contact points and patches, and handles a wide range of geometries including primitives (boxes, spheres, capsules, ellipsoids, cones), convex meshes, bounding volume hierarchies, height fields, and octrees.

The library is used in robotics frameworks like Pinocchio, the Humanoid Path Planner, and the Simple simulator. It provides Python bindings for prototyping and integration, making it accessible to researchers and engineers who need fast, reliable collision queries without implementing low-level geometric algorithms. The package requires six compiled dependencies (cmeel, cmeel-assimp, cmeel-boost, cmeel-octomap, cmeel-qhull, eigenpy) and is actively maintained with wheels for modern Python versions on macOS and Linux.

Use it for:

• Motion planning for humanoid robots: check collisions between planned trajectories and obstacles or the robot itself.
• Physics simulation: detect contacts and compute contact patches for constraint-based rigid body dynamics.
• Grasp planning: compute distances and contact points between gripper and object geometries.
• Path validation: validate collision-free paths in high-dimensional configuration spaces during planning.
• Proximity queries: compute lower bounds on distances between objects for safety margins in real-time control.

Worth the install?

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

Coal provides collision detection, distance computation, and contact analysis for 3D geometric objects, with Python bindings for prototyping and integration into robotics frameworks.

Yes, if you need collision detection and distance computation for robotics or 3D geometric applications. Coal offers state-of-the-art GJK/EPA performance, is actively maintained, has no known vulnerabilities, and integrates well with established robotics frameworks. The medium install friction (compiled dependencies) is manageable via conda. Not necessary if you only need basic bounding-box overlap checks or are already embedded in a framework that provides collision detection.

Install

coal-library on PyPI

pip install coal-library

uv add coal-library

poetry add coal-library

Installing coal-library

Before you install

Medium install friction: depends on six compiled packages (cmeel, cmeel-assimp, cmeel-boost, cmeel-octomap, cmeel-qhull, eigenpy). Pre-built wheels available for multiple Python versions on macOS and Linux. Actively maintained with recent commits.

License in practice

BSD-3-Clause permissive license allows commercial and private use with minimal restrictions; attribution and license notice required in distributions.

Quickstart

import coal

# Create shapes
shape1 = coal.Ellipsoid(0.7, 1.0, 0.8)
shape2 = coal.Sphere(0.5)

# Define placements
T1 = coal.Transform3s()
T2 = coal.Transform3s()

# Collision request and result
request = coal.CollisionRequest()
result = coal.CollisionResult()

# Perform collision check
coal.collide(shape1, T1, shape2, T2, request, result)

Requires compiled dependencies (cmeel-boost, cmeel-assimp, cmeel-octomap, cmeel-qhull, eigenpy); conda installation recommended to handle binary wheels automatically.

Verify before relying

• Whether Python bindings cover the full C++ API surface or a subset of collision/distance operations.
• Whether contact patch computation is exposed in the Python API or only in C++.
• Performance characteristics of accelerated GJK variants relative to baseline GJK in typical use cases.

Package facts

Evidence: coal_library-3.0.1-0-cp310-cp310-macosx_10_9_x86_64.whl; coal_library-3.0.1-0-cp310-cp310-macosx_11_0_arm64.whl; coal_library-3.0.1-0-cp310-cp310-manylinux_2_28_aarch64.whl; coal_library-3.0.1-0-cp310-cp310-manylinux_2_28_x86_64.whl; coal_library-3.0.1-0-cp311-cp311-macosx_10_9_x86_64.whl; coal_library-3.0.1-0-cp311-cp311-macosx_11_0_arm64.whl; coal_library-3.0.1-0-cp311-cp311-manylinux_2_28_aarch64.whl; coal_library-3.0.1-0-cp311-cp311-manylinux_2_28_x86_64.whl; coal_library-3.0.1-0-cp312-cp312-macosx_10_9_x86_64.whl; coal_library-3.0.1-0-cp312-cp312-macosx_11_0_arm64.whl; coal_library-3.0.1-0-cp312-cp312-manylinux_2_28_aarch64.whl; coal_library-3.0.1-0-cp312-cp312-manylinux_2_28_x86_64.whl; coal_library-3.0.1-0-cp313-cp313-macosx_10_9_x86_64.whl; coal_library-3.0.1-0-cp313-cp313-macosx_11_0_arm64.whl; coal_library-3.0.1-0-cp313-cp313-manylinux_2_28_aarch64.whl; coal_library-3.0.1-0-cp313-cp313-manylinux_2_28_x86_64.whl; coal_library-3.0.1-0-cp38-cp38-macosx_10_9_x86_64.whl; coal_library-3.0.1-0-cp38-cp38-manylinux_2_28_aarch64.whl; coal_library-3.0.1-0-cp38-cp38-manylinux_2_28_x86_64.whl; coal_library-3.0.1-0-cp39-cp39-macosx_10_9_x86_64.whl

Tags

More Scientific/Engineering packages