hpp-fcl

3.0.2.c1 · active · verified Thu Apr 16

hpp-fcl is a Python binding for the Flexible Collision Library (FCL), a C++ library for performing collision and distance queries between 3D geometric models. It provides efficient algorithms for checking interference between various primitive shapes and complex meshes. The current version, 3.0.2.c1, is built against FCL v0.7/v0.8 and is actively maintained with a focus on stable releases tied to underlying FCL versions.

Common errors

```
ModuleNotFoundError: No module named 'hpp-fcl'
```
cause Attempting to import the module using the package name with a hyphen.

fix Change your import statement from `import hpp-fcl` to `import hppfcl`.
```
AttributeError: module 'hppfcl' has no attribute 'Transform'
```
cause Trying to use an older FCL API transformation class, or a misremembered name.

fix The correct class for transformations is `hppfcl.Transform3f` in current versions. Update your code to use `Transform3f`.
```
ImportError: libfcl.so.0.7: cannot open shared object file: No such file or directory
```
cause The Python binding was likely built from source or in an environment where the underlying C++ FCL library is not correctly found by the linker at runtime.

fix Ensure the directory containing `libfcl.so` (or `fcl.dll` on Windows) is in your system's `LD_LIBRARY_PATH` (Linux/macOS) or `PATH` (Windows), or reinstall `hpp-fcl` using a pre-compiled wheel if available for your platform and Python version.

Warnings

breaking Major API changes occurred between hpp-fcl 2.x and 3.x, corresponding to underlying FCL library updates from v0.6 to v0.7/v0.8. This affects geometry constructors, transformation classes (e.g., `Transform3f` methods), and collision/distance function signatures.
Fix: Review the official FCL v0.7/v0.8 documentation for API changes. Update code to use `Transform3f.setTranslation()`, `hppfcl.Vector3` for vectors, and verify `collide`/`distance` function arguments.
gotcha The Python package name is `hpp-fcl` (with a hyphen), but the module you import into Python code is `hppfcl` (without a hyphen).
Fix: Always use `import hppfcl` in your Python code, not `import hpp-fcl`.
gotcha While `pip install hpp-fcl` typically installs pre-compiled wheels, certain environments or source builds might encounter issues due to missing C++ compiler tools (e.g., g++, cmake) or underlying FCL library dependencies.
Fix: Ensure that development tools like `cmake`, `g++`, and potentially `boost` development libraries are installed on your system before attempting a source build.

Install

pip install hpp-fcl Install stable release

Imports

hppfcl
wrong:
```
import hpp-fcl
```
correct:
```
import hppfcl
```
The Python package is `hpp-fcl` but the importable module name is `hppfcl` (without the hyphen).
Transform3f
wrong:
```
from hppfcl import Transform
```
correct:
```
from hppfcl import Transform3f
```
The primary transformation class is `Transform3f`, not `Transform`, which existed in older FCL versions.

Quickstart

This quickstart demonstrates how to create two simple sphere objects, position them using `Transform3f`, and then perform both collision and distance checks using the `hppfcl.collide` and `hppfcl.distance` functions.

import hppfcl
from hppfcl import CollisionRequest, CollisionResult, DistanceRequest, DistanceResult

# Create two spheres
s1 = hppfcl.Sphere(1.0)
s2 = hppfcl.Sphere(1.0)

# Create an identity transform for s1
tf1 = hppfcl.Transform3f()

# Create a transform for s2 (translated by 2.0 along X-axis)
tf2 = hppfcl.Transform3f()
tf2.setTranslation(hppfcl.Vector3(2.0, 0.0, 0.0))

# Perform collision check
req = CollisionRequest()
res = CollisionResult()
ret = hppfcl.collide(s1, tf1, s2, tf2, req, res)

print(f"Collision result: {res.isCollision()}")

# Perform distance check
dreq = DistanceRequest()
dres = DistanceResult()
ret = hppfcl.distance(s1, tf1, s2, tf2, dreq, dres)

print(f"Minimum distance: {dres.min_distance}")

view raw JSON →