Libcoal: Flexible Collision Library Extension

3.0.2 · active · verified Fri Apr 17

Libcoal is a Python wrapper and extension for the Flexible Collision Library (FCL), a high-performance C++ library for performing collision detection and distance computation between geometric objects. It provides efficient Python bindings to FCL's core functionalities, enabling robotics, simulation, and planning applications to leverage fast collision checks. The current version is 3.0.2, with frequent patch releases addressing build system and compatibility updates.

Common errors

```
ImportError: No module named 'libcoal_core'
```
cause The `libcoal` package was not installed correctly, or the Python environment is not configured to find it. This can also happen if `pip` attempted a source build that failed silently due to missing C++ dependencies.

fix Verify installation by running `pip list | grep libcoal`. If missing, try `pip install libcoal`. For build failures, check `pip`'s verbose output (`pip install libcoal --verbose`) and ensure required C++ development libraries (FCL, CMake, a C++ compiler) are installed.
```
AttributeError: module 'libcoal' has no attribute 'CollisionGeometry'
```
cause Attempting to access library features through `import libcoal` instead of `import libcoal_core`.

fix Change `import libcoal` to `import libcoal_core` and update all subsequent references (e.g., `libcoal.CollisionGeometry` to `libcoal_core.CollisionGeometry`).
```
RuntimeError: FCL initialization failed: Could not load FCL library.
```
cause The underlying C++ FCL library could not be found or loaded by the Python bindings. This often indicates issues with dynamic linking, missing shared libraries on the system, or a corrupted `libcoal` installation.

fix Ensure that all required C++ shared libraries (FCL, Eigen, Boost, etc., if applicable and not bundled) are correctly installed and discoverable by your system's dynamic linker (e.g., in `LD_LIBRARY_PATH` on Linux). Reinstall `libcoal` to ensure bindings are correct: `pip uninstall libcoal && pip install libcoal`.

Warnings

gotcha The PyPI package is named `libcoal`, but the primary module containing all collision detection functionalities and classes is `libcoal_core`. Attempting to `import libcoal` directly will likely result in an `AttributeError` or missing functionalities.
Fix: Always use `import libcoal_core` to access the library's features and refer to classes (e.g., `libcoal_core.CollisionGeometry`).
gotcha Libcoal provides pre-built binary wheels for common platforms and Python versions. If a suitable wheel is not available for your specific OS/architecture (e.g., ARM, less common Linux distributions), `pip install libcoal` may fail or attempt to build from source, which requires CMake, a C++ compiler, and the FCL development libraries installed on your system.
Fix: Ensure a compatible wheel exists for your environment. If not, refer to the GitHub repository for source build instructions and dependency requirements (e.g., FCL, Eigen, Boost).
breaking Major version upgrades (e.g., from 2.x to 3.x) of `libcoal` often correspond to significant updates to the underlying Flexible Collision Library (FCL). These FCL updates can introduce API changes or behavioral differences that might break existing code that directly interacts with FCL concepts exposed through `libcoal`.
Fix: Consult the `libcoal` GitHub repository's release notes for specific changes, and if issues arise, review the FCL documentation for details on API changes relevant to the integrated FCL version.

Install

pip install libcoal Install stable version

Imports

libcoal_core
wrong:
```
import libcoal
```
correct:
```
import libcoal_core
```
The core functionality and classes are exposed via the 'libcoal_core' module, not 'libcoal' directly, despite the package name.
CollisionGeometry
wrong:
```
from libcoal import CollisionGeometry
```
correct:
```
from libcoal_core import CollisionGeometry
```
Common classes like CollisionGeometry are members of the libcoal_core module. Direct import from libcoal will fail.
Transform3d
wrong:
```
from libcoal import Transform3d
```
correct:
```
from libcoal_core import Transform3d
```
Geometric types like Transform3d are available directly from libcoal_core.

Quickstart

This quickstart demonstrates how to create two simple collision geometries (spheres), define their poses using transforms, and perform a collision check using `libcoal_core.collide`. It shows both colliding and non-colliding scenarios.

import libcoal_core

# Create two spheres
sphere_radius = 1.0
s1 = libcoal_core.CollisionGeometry(libcoal_core.CollisionShape_Sphere(sphere_radius))
s2 = libcoal_core.CollisionGeometry(libcoal_core.CollisionShape_Sphere(sphere_radius))

# Define transforms (position and orientation) for the spheres
tf1 = libcoal_core.Transform3d()
# Move the second sphere to partially overlap with the first
tf2 = libcoal_core.Transform3d()
tf2.translation = libcoal_core.Vector3d([sphere_radius * 0.5, 0.0, 0.0]) # Overlap by 0.5 units

# Perform collision checking
req = libcoal_core.CollisionRequest()
res = libcoal_core.CollisionResult()
libcoal_core.collide(s1, tf1, s2, tf2, req, res)

print(f"Are spheres colliding? {res.is_collision}")
print(f"Number of contacts: {res.num_contacts}")

# Adjust position to not collide
tf2.translation = libcoal_core.Vector3d([sphere_radius * 2.5, 0.0, 0.0]) # Separated by 0.5 units
libcoal_core.collide(s1, tf1, s2, tf2, req, res)
print(f"Are spheres colliding (separated)? {res.is_collision}")

view raw JSON →