python-fcl

0.7.0.11 verified Fri May 01 auth: no python

Python bindings for the Flexible Collision Library (FCL), providing collision detection and proximity queries on 3D geometry. Current version 0.7.0.11, requires Python >=3.9. Releases are irregular, mostly bugfix releases.

pip install python-fcl

Common errors

error ImportError: No module named fcl ↓

cause Package not installed or installed under different name.

fix

Run 'pip install python-fcl' (note: import name is 'fcl').

error AttributeError: module 'fcl' has no attribute 'CollisionObject' ↓

cause Very old version (pre-0.6) or copy with renaming.

fix

Upgrade: pip install --upgrade python-fcl. Or check if API changed: use 'import fcl; print(dir(fcl))'.

Warnings

breaking Version 0.7.0.x changed the return type of fcl.collide and fcl.distance from bool to int (return code). Old code checking if ret == True will break. ↓

fix Check ret == 1 for collision detected, or use res.is_collision / res.is_distance_valid.

gotcha Python-fcl uses row-major order for matrices (numpy default), while FCL C++ uses column-major internally. Incorrect transposition can lead to wrong transforms. ↓

fix Always use numpy arrays in row-major format; do not transpose unless explicitly documented.

gotcha CollisionObject instances must outlive the collision query; they are not copied. Deleting or reusing the same object in parallel can cause segfaults. ↓

fix Keep a reference to all CollisionObjects until after all queries are done.

Imports

fcl
```
import fcl
```
The main module is 'fcl', not 'python_fcl' or 'pyfcl'.

Quickstart

Basic collision check between two identical boxes.

import fcl
import numpy as np

# Create box geometry
box = fcl.Box(1, 1, 1)
obj = fcl.CollisionObject(box, fcl.Transform())

# Create collision request/result
req = fcl.CollisionRequest()
res = fcl.CollisionResult()

# Self-collision check (not useful, but simple)
ret = fcl.collide(obj, obj, req, res)
print(f"Collision? {res.is_collision}")