libcoal

What it is and what it does

libcoal is a Python interface to a modern collision detection and distance computation library that evolved from the Flexible Collision Library (FCL). It provides efficient implementations of the GJK and EPA algorithms for narrow-phase collision detection, along with support for safety margins, contact point computation, and a variety of geometric primitives (boxes, spheres, capsules, ellipsoids, convex meshes, height fields, octrees). The library is designed for robotics and physics simulation where fast, reliable collision checking is critical.

The package wraps a C++ core with compiled dependencies on cmeel-boost, cmeel-assimp, cmeel-octomap, and cmeel-qhull, making installation straightforward on supported platforms (macOS and Linux) but requiring binary wheels. It is actively maintained and used in production robotics frameworks for motion planning and dynamics simulation.

Use it for:

• Motion planning for robotic systems: check collisions between links and obstacles during trajectory generation.
• Physics simulation: detect contacts and compute distances between rigid bodies in a dynamics engine.
• Mesh collision queries: load convex hulls from OBJ/STL/DAE files and perform fast collision detection with other objects.
• Safety margin enforcement: maintain minimum distance constraints between objects in real-time control loops.
• Contact analysis: compute contact points and patches between colliding geometries for force feedback or constraint solving.

Worth the install?

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

libcoal provides Python bindings for collision detection and distance computation between 3D geometric objects using optimized GJK and EPA algorithms.

Yes, if you need collision detection in a robotics or physics simulation context on macOS or Linux. The library is actively maintained, permissively licensed (BSD-3-Clause), and offers state-of-the-art performance via optimized GJK algorithms. Install friction is moderate due to compiled dependencies, but binary wheels are available for common platforms. No known vulnerabilities.

Install

libcoal on PyPI

pip install libcoal

uv add libcoal

poetry add libcoal

Installing libcoal

Before you install

Medium install friction due to compiled dependencies (cmeel-assimp, cmeel-boost, cmeel-octomap, cmeel-qhull). Actively maintained with recent releases; last commit 2026-08-01. Requires Python >=3.9.

License in practice

BSD-3-Clause (permissive) allows commercial use, modification, and distribution with minimal restrictions—suitable for most projects.

Quickstart

pip install libcoal

import libcoal

# Create shapes and check collision
shape1 = libcoal.Ellipsoid(0.7, 1.0, 0.8)
shape2 = libcoal.Sphere(0.5)
request = libcoal.CollisionRequest()
result = libcoal.CollisionResult()
libcoal.collide(shape1, libcoal.Transform3s.Identity(), shape2, libcoal.Transform3s.Identity(), request, result)

Requires compiled C++ libraries; binary wheels available for macOS (x86_64, arm64) and Linux (x86_64, aarch64) only.

Verify before relying

• Whether Python bindings expose the full feature set (contact patches, serialization, broad phase) described in the C++ documentation.
• Performance characteristics of the Python bindings relative to direct C++ usage.
• Availability of comprehensive Python API documentation beyond the excerpt provided.

Package facts

Evidence: libcoal-3.0.3-0-py3-none-macosx_10_9_x86_64.whl; libcoal-3.0.3-0-py3-none-macosx_11_0_arm64.whl; libcoal-3.0.3-0-py3-none-manylinux_2_28_aarch64.whl; libcoal-3.0.3-0-py3-none-manylinux_2_28_x86_64.whl

Tags

More Scientific/Engineering packages