{"id":14666,"library":"libcoal","title":"Libcoal: Flexible Collision Library Extension","description":"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.","status":"active","version":"3.0.2","language":"en","source_language":"en","source_url":"https://github.com/cmake-wheel/libcoal","tags":["collision detection","robotics","FCL","geometry","simulation"],"install":[{"cmd":"pip install libcoal","lang":"bash","label":"Install stable version"}],"dependencies":[],"imports":[{"note":"The core functionality and classes are exposed via the 'libcoal_core' module, not 'libcoal' directly, despite the package name.","wrong":"import libcoal","symbol":"libcoal_core","correct":"import libcoal_core"},{"note":"Common classes like CollisionGeometry are members of the libcoal_core module. Direct import from libcoal will fail.","wrong":"from libcoal import CollisionGeometry","symbol":"CollisionGeometry","correct":"from libcoal_core import CollisionGeometry"},{"note":"Geometric types like Transform3d are available directly from libcoal_core.","wrong":"from libcoal import Transform3d","symbol":"Transform3d","correct":"from libcoal_core import Transform3d"}],"quickstart":{"code":"import libcoal_core\n\n# Create two spheres\nsphere_radius = 1.0\ns1 = libcoal_core.CollisionGeometry(libcoal_core.CollisionShape_Sphere(sphere_radius))\ns2 = libcoal_core.CollisionGeometry(libcoal_core.CollisionShape_Sphere(sphere_radius))\n\n# Define transforms (position and orientation) for the spheres\ntf1 = libcoal_core.Transform3d()\n# Move the second sphere to partially overlap with the first\ntf2 = libcoal_core.Transform3d()\ntf2.translation = libcoal_core.Vector3d([sphere_radius * 0.5, 0.0, 0.0]) # Overlap by 0.5 units\n\n# Perform collision checking\nreq = libcoal_core.CollisionRequest()\nres = libcoal_core.CollisionResult()\nlibcoal_core.collide(s1, tf1, s2, tf2, req, res)\n\nprint(f\"Are spheres colliding? {res.is_collision}\")\nprint(f\"Number of contacts: {res.num_contacts}\")\n\n# Adjust position to not collide\ntf2.translation = libcoal_core.Vector3d([sphere_radius * 2.5, 0.0, 0.0]) # Separated by 0.5 units\nlibcoal_core.collide(s1, tf1, s2, tf2, req, res)\nprint(f\"Are spheres colliding (separated)? {res.is_collision}\")","lang":"python","description":"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."},"warnings":[{"fix":"Always use `import libcoal_core` to access the library's features and refer to classes (e.g., `libcoal_core.CollisionGeometry`).","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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).","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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`.","severity":"breaking","affected_versions":"Major version upgrades (e.g., 2.x to 3.x)"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"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.","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.","error":"ImportError: No module named 'libcoal_core'"},{"fix":"Change `import libcoal` to `import libcoal_core` and update all subsequent references (e.g., `libcoal.CollisionGeometry` to `libcoal_core.CollisionGeometry`).","cause":"Attempting to access library features through `import libcoal` instead of `import libcoal_core`.","error":"AttributeError: module 'libcoal' has no attribute 'CollisionGeometry'"},{"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`.","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.","error":"RuntimeError: FCL initialization failed: Could not load FCL library."}],"ecosystem":"pypi"}