python-fcl

What it is and what it does

Python-FCL is an unofficial Python interface to the Flexible Collision Library, a C++ library for geometric proximity queries. It wraps FCL's core algorithms to let you detect collisions between 3D shapes, compute minimum distances between objects, and check for collisions during motion. The package supports geometric primitives (boxes, spheres, cylinders, cones, capsules, ellipsoids, half-spaces, planes) and arbitrary triangle meshes via BVHModel or Convex wrappers, plus OcTree structures for spatial hierarchies.

You work with CollisionObject instances (a geometry plus a pose), set up request/response structures, and call query functions like collide(), distance(), or continuousCollide(). The library is commonly used in robotics, physics simulation, and motion planning where you need fast, accurate proximity checks. Installation requires pre-built system libraries (libfcl-dev and liboctomap-dev on Linux) or manual FCL compilation; wheels are provided for recent Python versions on major platforms.

Use it for:

• Robotics motion planning: check for collisions between robot links and obstacles during path planning
• Physics simulation: compute contact points and distances for rigid body dynamics engines
• Continuous collision detection: detect whether moving objects collide during a time interval
• Mesh-based proximity queries: compute minimum distance between complex triangle meshes
• Spatial reasoning in autonomous systems: query geometric relationships for navigation and manipulation

Worth the install?

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

Python bindings for the Flexible Collision Library (FCL) that perform collision detection, distance computation, and continuous collision detection queries on pairs of geometric models.

Yes, if you need collision detection and distance queries in Python and can satisfy the system library prerequisites. The library is actively maintained, supports current Python versions (3.9+), carries no known vulnerabilities, and has a permissive BSD license. The main friction is the upfront system dependency installation; once that is done, the wheels install cleanly. Suitable for robotics, simulation, and computational geometry projects.

Install

python-fcl on PyPI

pip install python-fcl

uv add python-fcl

poetry add python-fcl

Installing python-fcl

Before you install

Medium install friction due to compiled C++ bindings; requires pre-installed system libraries (libfcl-dev and liboctomap-dev on Ubuntu, or manual FCL compilation). Wheels are available for Python 3.10–3.13 on macOS, Linux, and Windows. Active maintenance with recent release (128 days ago).

License in practice

BSD permissive license allows commercial and private use with minimal restrictions; suitable for most projects.

Quickstart

pip install python-fcl

import fcl
import numpy as np

g1 = fcl.Box(1, 2, 3)
t1 = fcl.Transform()
o1 = fcl.CollisionObject(g1, t1)

g2 = fcl.Sphere(1.0)
t2 = fcl.Transform(np.array([2.0, 0.0, 0.0]))
o2 = fcl.CollisionObject(g2, t2)

request = fcl.CollisionRequest()
result = fcl.CollisionResult()
ret = fcl.collide(o1, o2, request, result)

Requires libfcl-dev and liboctomap-dev system libraries installed before pip install; on Ubuntu use `sudo apt-get install libfcl-dev liboctomap-dev`, or compile FCL from source on other systems.

Verify before relying

• Whether OcTree support requires additional runtime configuration beyond liboctomap-dev installation
• Performance characteristics for large-scale mesh collision queries or high-frequency distance checks
• Stability of the Alpha status (Development Status :: 3) and whether breaking changes are expected

Package facts

Evidence: python_fcl-0.7.0.11-cp310-cp310-macosx_10_9_x86_64.whl; python_fcl-0.7.0.11-cp310-cp310-macosx_11_0_arm64.whl; python_fcl-0.7.0.11-cp310-cp310-manylinux_2_24_aarch64.manylinux_2_28_aarch64.whl; python_fcl-0.7.0.11-cp310-cp310-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl; python_fcl-0.7.0.11-cp310-cp310-win_amd64.whl; python_fcl-0.7.0.11-cp311-cp311-macosx_10_9_x86_64.whl; python_fcl-0.7.0.11-cp311-cp311-macosx_11_0_arm64.whl; python_fcl-0.7.0.11-cp311-cp311-manylinux_2_24_aarch64.manylinux_2_28_aarch64.whl; python_fcl-0.7.0.11-cp311-cp311-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl; python_fcl-0.7.0.11-cp311-cp311-win_amd64.whl; python_fcl-0.7.0.11-cp312-cp312-macosx_10_13_x86_64.whl; python_fcl-0.7.0.11-cp312-cp312-macosx_11_0_arm64.whl; python_fcl-0.7.0.11-cp312-cp312-manylinux_2_24_aarch64.manylinux_2_28_aarch64.whl; python_fcl-0.7.0.11-cp312-cp312-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl; python_fcl-0.7.0.11-cp312-cp312-win_amd64.whl; python_fcl-0.7.0.11-cp313-cp313-macosx_10_13_x86_64.whl; python_fcl-0.7.0.11-cp313-cp313-macosx_11_0_arm64.whl; python_fcl-0.7.0.11-cp313-cp313-manylinux_2_24_aarch64.manylinux_2_28_aarch64.whl; python_fcl-0.7.0.11-cp313-cp313-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl; python_fcl-0.7.0.11-cp313-cp313-win_amd64.whl

Keywords: fcl, collision, distance

Tags

More Scientific/Engineering packages