{"id":8019,"library":"coal","title":"Coal (Flexible Collision Library Extension)","description":"Coal is an extension of the Flexible Collision Library (FCL) that provides efficient implementations of GJK and EPA algorithms for collision detection and distance computation in robotics and related fields. It offers robust Python bindings for easy prototyping and integration. Originally a fork named HPP-FCL, it was officially renamed to Coal in 2024. The library is actively maintained, with version 3.0.2 being the latest stable release.","status":"active","version":"3.0.2","language":"en","source_language":"en","source_url":"https://github.com/cmake-wheel/coal","tags":["robotics","collision detection","FCL","geometry","GJK","EPA","distance computation","C++ bindings"],"install":[{"cmd":"pip install coal","lang":"bash","label":"PyPI (recommended)"},{"cmd":"conda install -c conda-forge coal","lang":"bash","label":"Conda"}],"dependencies":[{"reason":"Commonly used for numerical operations and array handling with geometric data.","package":"numpy","optional":false},{"reason":"A rigid body dynamics library that often uses and can install Coal as a dependency.","package":"pinocchio","optional":true},{"reason":"Required for 3D model import; typically handled by binary wheels or conda.","package":"assimp","optional":false},{"reason":"C++ utility libraries; typically handled by binary wheels or conda.","package":"boost","optional":false},{"reason":"C++ template library for linear algebra; typically handled by binary wheels or conda.","package":"eigen","optional":false},{"reason":"Used for Octree-based collision objects; typically handled by binary wheels or conda.","package":"octomap","optional":false}],"imports":[{"note":"The library was renamed from HPP-FCL to Coal in 2024; the old import path is deprecated.","wrong":"import hppfcl","symbol":"coal","correct":"import coal"},{"note":"Core types and functions are typically accessed directly from the `coal` module.","symbol":"Transform3s","correct":"import coal\ntrans = coal.Transform3s()"}],"quickstart":{"code":"import numpy as np\nimport coal\n\n# Define geometries\nradius = 0.1\nlength = 0.5\ncapsule1_geom = coal.Capsule(radius, length)\ncapsule2_geom = coal.Capsule(radius, length)\n\n# Define poses (transformations)\n# Capsule 1 at origin, identity orientation\ncapsule1_tf = coal.Transform3s.Identity()\n\n# Capsule 2 shifted along X-axis\ncapsule2_tf = coal.Transform3s.Identity()\ncapsule2_tf.translation[:] = np.array([0.2, 0.0, 0.0])\n\n# Create collision objects\nobj1 = coal.CollisionObject(capsule1_geom, capsule1_tf)\nobj2 = coal.CollisionObject(capsule2_geom, capsule2_tf)\n\n# Perform collision check\nreq = coal.CollisionRequest()\nres = coal.CollisionResult()\n\n# Note: coal.collide returns a boolean indicating collision state\ncollision_occurred = coal.collide(obj1, obj2, req, res)\n\nif collision_occurred:\n    print(f\"Collision detected! Number of contacts: {len(res.contacts)}\")\n    for contact in res.contacts:\n        print(f\"  Contact point: {contact.pos.transpose()}, Normal: {contact.normal.transpose()}\")\nelse:\n    print(\"No collision detected.\")\n\n# Example for distance computation\nreq_dist = coal.DistanceRequest()\nres_dist = coal.DistanceResult()\n\ndistance_found = coal.distance(obj1, obj2, req_dist, res_dist)\n\nif distance_found:\n    print(f\"Minimum distance: {res_dist.min_distance}\")\n    print(f\"Closest point on obj1: {res_dist.nearest_points[0].transpose()}\")\n    print(f\"Closest point on obj2: {res_dist.nearest_points[1].transpose()}\")","lang":"python","description":"This quickstart demonstrates how to define geometric primitives (e.g., capsules), set their poses using `Transform3s`, create `CollisionObject` instances, and perform collision detection and distance computation using `coal.collide` and `coal.distance`."},"warnings":[{"fix":"Update imports from `import hppfcl` to `import coal`. Ensure you are installing the `coal` package.","message":"The project was renamed from HPP-FCL to Coal in 2024. Code using the old 'hppfcl' import or package name will break.","severity":"breaking","affected_versions":"All versions prior to 3.0.0 (as HPP-FCL) when migrating to Coal."},{"fix":"Ensure you have a C++ compiler (e.g., MSVC on Windows, GCC/Clang on Linux/macOS) and CMake installed. Consider using `conda install -c conda-forge coal` for better dependency management if `pip` fails.","message":"Direct `pip install coal` might fail if pre-built wheels are not available for your specific Python version and operating system, often requiring manual compilation.","severity":"gotcha","affected_versions":"All versions, particularly on less common platforms or with new Python releases."},{"fix":"Be aware that behavioral differences might exist compared to other FCL implementations or wrappers like `python-fcl`. Review Coal's documentation for specific algorithm details and expected performance characteristics.","message":"Coal explicitly implements its own GJK and EPA algorithms and does not rely on `libccd`, a common component in other Flexible Collision Library (FCL) wrappers.","severity":"gotcha","affected_versions":"All versions."}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Install a C++ compiler (e.g., `build-essential` on Debian/Ubuntu, Xcode Command Line Tools on macOS, Visual Studio with C++ development tools on Windows) and CMake. Alternatively, use `conda install -c conda-forge coal` if available, as conda often provides pre-compiled binaries with all dependencies.","cause":"This error occurs when `pip` cannot find a pre-built binary wheel for your system and attempts to build from source, but the necessary C++ compilers, CMake, or other build dependencies are missing or misconfigured. This is common for Python packages with underlying C++ code.","error":"ERROR: Could not build wheels for coal which use PEP 517 and cannot be installed directly"},{"fix":"Ensure the installation was successful (`pip install coal` or `conda install -c conda-forge coal`). If migrating from `hpp-fcl`, verify that the old package is uninstalled and `coal` is correctly installed, and update your import statements from `import hppfcl` to `import coal`.","cause":"The `coal` package was not successfully installed, or you are attempting to import it using an incorrect name. This can also happen if you previously installed the old `hpp-fcl` package.","error":"ModuleNotFoundError: No module named 'coal'"}]}