{"id":9038,"library":"hpp-fcl","title":"hpp-fcl","description":"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.","status":"active","version":"3.0.2.c1","language":"en","source_language":"en","source_url":"https://github.com/cmake-wheel/hpp-fcl","tags":["robotics","collision-detection","geometric-primitives","c++-bindings","fcl"],"install":[{"cmd":"pip install hpp-fcl","lang":"bash","label":"Install stable release"}],"dependencies":[],"imports":[{"note":"The Python package is `hpp-fcl` but the importable module name is `hppfcl` (without the hyphen).","wrong":"import hpp-fcl","symbol":"hppfcl","correct":"import hppfcl"},{"note":"The primary transformation class is `Transform3f`, not `Transform`, which existed in older FCL versions.","wrong":"from hppfcl import Transform","symbol":"Transform3f","correct":"from hppfcl import Transform3f"}],"quickstart":{"code":"import hppfcl\nfrom hppfcl import CollisionRequest, CollisionResult, DistanceRequest, DistanceResult\n\n# Create two spheres\ns1 = hppfcl.Sphere(1.0)\ns2 = hppfcl.Sphere(1.0)\n\n# Create an identity transform for s1\ntf1 = hppfcl.Transform3f()\n\n# Create a transform for s2 (translated by 2.0 along X-axis)\ntf2 = hppfcl.Transform3f()\ntf2.setTranslation(hppfcl.Vector3(2.0, 0.0, 0.0))\n\n# Perform collision check\nreq = CollisionRequest()\nres = CollisionResult()\nret = hppfcl.collide(s1, tf1, s2, tf2, req, res)\n\nprint(f\"Collision result: {res.isCollision()}\")\n\n# Perform distance check\ndreq = DistanceRequest()\ndres = DistanceResult()\nret = hppfcl.distance(s1, tf1, s2, tf2, dreq, dres)\n\nprint(f\"Minimum distance: {dres.min_distance}\")","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":"hpp-fcl < 3.0.0"},{"fix":"Always use `import hppfcl` in your Python code, not `import hpp-fcl`.","message":"The Python package name is `hpp-fcl` (with a hyphen), but the module you import into Python code is `hppfcl` (without a hyphen).","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure that development tools like `cmake`, `g++`, and potentially `boost` development libraries are installed on your system before attempting a source build.","message":"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.","severity":"gotcha","affected_versions":"All versions (when building from source or on unsupported platforms)"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Change your import statement from `import hpp-fcl` to `import hppfcl`.","cause":"Attempting to import the module using the package name with a hyphen.","error":"ModuleNotFoundError: No module named 'hpp-fcl'"},{"fix":"The correct class for transformations is `hppfcl.Transform3f` in current versions. Update your code to use `Transform3f`.","cause":"Trying to use an older FCL API transformation class, or a misremembered name.","error":"AttributeError: module 'hppfcl' has no attribute 'Transform'"},{"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.","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.","error":"ImportError: libfcl.so.0.7: cannot open shared object file: No such file or directory"}]}