Coal — An extension of the Flexible Collision Library

FCL was forked in 2015, creating a new project called HPP-FCL. Since then, a large part of the code has been rewritten or removed (unused and untested code), and new features have been introduced (see below). Due to these major changes, it was decided in 2024 to rename the HPP-FCL project to Coal.

If you use Coal in your projects and research papers, we would appreciate it if you would cite it.

New features

Compared to the original FCL library, the main new features are:

• dedicated and efficient implementations of the GJK and the EPA algorithms (we do not rely on libccd)
• the support of safety margins for collision detection
• an accelerated version of collision detection à la Nesterov, which leads to increased performance (up to a factor of 2). More details are available in this paper
• the computation of a lower bound of the distance between two objects when collision checking is performed, and no collision is found
• the implementation of Python bindings for easy code prototyping
• the support of new geometries such as height fields, capsules, ellipsoids, etc.
• enhance reliability with the fix of a myriad of bugs
• efficient computation of contact points and contact patches between objects
• full support of object serialization via Boost.Serialization

Note: the broad phase was reintroduced by Justin Carpentier in 2022, based on the FCL version 0.7.0.

This project is now used in several robotics frameworks such as Pinocchio, an open-source library which implements efficient and versatile rigid-body dynamics algorithms, the Humanoid Path Planner, an open-source library for Motion and Manipulation Planning. Coal has recently also been used to develop Simple, a new (differentiable) and efficient simulator for robotics and beyond.

A high-performance library

Unlike the original FCL library, Coal implements the well-established GJK algorithm and its variants for collision detection and distance computation. These implementations lead to state-of-the-art performance, as shown in the figures below.

On the one hand, we have benchmarked Coal against major state-of-the-art software alternatives:

1. the Bullet simulator,
2. the original FCL library (used in the Drake framework),
3. the libccd library (used in MuJoCo).

The results are depicted in the following figure, which notably shows that the accelerated variants of GJK largely outperform by a large margin (from 5x up to 15x times faster). Please notice that the y-axis is in log scale.

On the other hand, why do we care about dedicated collision detection solvers like GJK for the narrow phase? Why can’t we simply formulate the collision detection problem as a quadratic problem and call an off-the-shelf optimization solver like ProxQP)? Here is why:

One can observe that GJK-based approaches largely outperform solutions based on classic optimization solvers (e.g., QP solver like ProxQP), notably for large geometries composed of tens or hundreds of vertices.

Open-source projects relying on Coal

• Pinocchio A fast and flexible implementation of Rigid Body Dynamics algorithms and their analytical derivatives.
• IfcOpenShell Open source IFC library and geometry engine.
• Crocoddyl A software to realize model predictive control for complex robotics platforms.
• TSID A software that implements a Task Space Inverse Dynamics QP.
• HPP A SDK that implements motion planners for humanoids and other robots.
• Jiminy A simulator based on Pinocchio.
• ocs2 A toolbox for Optimal Control for Switched Systems (OCS2)

Installation

Conda

Coal can be installed from the conda-forge channel:

conda install coal -c conda-forge

Build

You can find build instruction here.

C++ example

Both the C++ library and the python bindings can be installed as simply as conda -c conda-forge install coal. The .so library, include files and python bindings will then be installed under $CONDA_PREFIX/lib, $CONDA_PREFIX/include and $CONDA_PREFIX/lib/python3.XX/site-packages.

Here is an example of using Coal in C++:

```cpp #include “coal/math/transform.h” #include “coal/mesh_loader/loader.h” #include “coal/BVH/BVH_model.h” #include “coal/collision.h” #include “coal/collision_data.h” #include #include

// Function to load a convex mesh from a .obj, .stl or .dae file.

File truncated at 100 lines see the full file

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog.

[Unreleased]

Added

• CMake: add COAL_DISABLE_HPP_FCL_WARNINGS option (#709)
• broadphase: add functional API for collision and distance callbacks (#724)

Removed

• Remove constraints on supported doxygen version to generate the python documentation (#681)
• Remove useless COAL_WITH_CXX11_SUPPORT guard (#688)
• Remove qhull submodule, as ubuntu 20.04 is EoL (#704)
• Removed support for octomap < 1.8 (#727)

Changed

• Formatted all CMake listfiles using gersemi, add gersemi to pre-commit configuration (#657)
• Float precision (#665)
  • Rename CoalScalar to Scalar
  • Add option to switch between (default) double precision and float precision
  • Changed all the uses of double to Scalar in Coal
  • Fixed all the compilation warnings when compiling the library using float precision
• Tracy profiling (#668)
  • added cmake option COAL_BUILD_WITH_TRACY
  • put tracy scoped zones in broadphase and primitive shapes collision/distance queries
• Use double precision for GJK/EPA when coal is compiled in float (#674)
  • Everything is in float in coal (including the support functions), except the computations inside GJK/EPA
  • Allows GJK/EPA to avoid limitation of float precision
• Renamed PyPI package from coal-library to coal (#675)
• Fixed malloc in COAL_ASSERT (#687)
• Introducing Convex16 and Convex32 to store neighbors and polygons indices as uint16 or uint32 (#682, #716).
  • Along with #665, this allows to divide by two the memory footprint of Convex.

Fixed

• Fix doc parsing via doxygen scripts (#678 #699)

[3.0.1] - 2025-02-12

Fixed

• Remove CMake CMP0167 warnings (#630)
• Allow to run test in the build directory on Windows (#630)
• Updated nix flake from hpp-fcl to coal (#632
• Fix hpp-fclConfig.cmake on Windows (#633)
• Fix install version (#651)

Added

• Add Pixi support (#629)

Changed

• Set NOMINMAX as a public definitions on Windows (#640)

[3.0.0] - 2024-11-20

Added

• Renaming the library from hpp-fcl to coal. Created a COAL_BACKWARD_COMPATIBILITY_WITH_HPP_FCL CMake option for retro compatibility. This allows to still do find_package(hpp-fcl) and #include <hpp/fcl/...> in C++ and it allows to still do import hppfcl in python (#596).
• Added Transform3f::Random and Transform3f::setRandom (#584)
• New feature: computation of contact surfaces for any pair of primitive shapes (triangle, sphere, ellipsoid, plane, halfspace, cone, capsule, cylinder, convex) (#574).
• Enhance Broadphase DynamicAABBTree to better handle planes and halfspace (#570)
• #558:
  • [internal] Removed dead code in narrowphase/details.h (#558)
  • [internal] Removed specializations of methods of GJKSolver. Now the specializations are all handled by ShapeShapeDistance in shape_shape_func.h.
  • [new feature] Added support for Swept-Sphere primitives (sphere, box, capsule, cone, ellipsoid, triangle, halfspace, plane, convex mesh).
• [API change] Renamed default convergence criterion from VDB to Default (#556)
• Fixed EPA returning nans on cases where it could return an estimate of the normal and penetration depth. (#556)
• Fixed too low tolerance in GJK/EPA asserts (#554)
• Fixed normal_and_nearest_points test (no need to have Eigen 3.4) (#553)
• #549
• Optimize EPA: ignore useless faces in EPA’s polytope; warm-start support computation for Convex; fix edge-cases witness points computation.
• Add Serializable trait to transform, collision data, collision geometries, bounding volumes, bvh models, hfields. Collision problems can now be serialized from C++ and sent to python and vice versa.
• CMake: allow use of installed jrl-cmakemodules (#564)
• CMake: Add compatibility with jrl-cmakemodules workspace (#610)
• Python: add id() support for geometries (#618).

Fixed

• Fix Fix serialization unit test when running without Qhull support (#611)
• Compiler warnings (#601, #605)
• CMake: fix assimp finder
• Don’t define GCC7 Boost serialization hack when HPP_FCL_SKIP_EIGEN_BOOST_SERIALIZATION is defined (#530)
• Default parameters for narrowphase algorithms (GJK and EPA); fixed assertion checks that were sometimes failing in GJK simplex projection and BVH collide (#531).
• Created a new macro HPP_FCL_ASSERT which behaves as an assert by default. When the option HPP_FCL_TURN_ASSERT_INTO_EXCEPTION is turned on, it replaces the macro by an exception (#533). Also fixed an EPA assert in GJKSolver.
• Simplify internals of hpp-fcl (#535):
  • Computing distance between 2 primitives shapes does not use a traversal node anymore.
  • Removed successive mallocs in GJK/EPA when using an instance of GJKSolver multiple times.
  • GJKSolver now deals with all statuses of GJK/EPA. Some of these statuses represent a bad behavior of GJK/EPA and now trigger an assertion in Debug mode. Usefull for debugging these algos.
  • Logging was added with macros like HPP_FCL_LOG_(INFO/DEBUG/WARNING/ERROR); hpp-fcl can now log usefull info when the preprocessor option HPP_FCL_ENABLE_LOGGING is enabled.
  • Deprecated enable_distance_lower_bound in CollisionRequest; a lower bound on distance is always computed.
  • Deprecated enable_nearest_points in DistanceRequest; they are always computed and are the points of the shapes that achieve a distance of DistanceResult::min_distance.
  • Added enable_signed_distance flag in DistanceRequest (default true). Turn this of for better performance if only the distance when objects are disjoint is needed.
  • The internal collision and distance functions of hpp-fcl now use CollisionRequest::enable_contact and DistanceRequest::enable_signed_distance to control whether or not penetration information should be computed. There are many scenarios where we don’t need the penetration information and only want to know if objects are colliding and compute their distance only if they are disjoint. These flags allow the user to control the trade-off between performance vs. information of the library.
  • Fix convergence criterion of EPA; made GJK and EPA convergence criterion absolute + relative to scale to the shapes’ dimensions; remove max face/vertices fields from EPA (these can be deduced from the max number of iterations)
• Account for lateral borders in Height Fields model.
• Fix compilation error on recent APPLE compilers (#539).
• Fix printing of deprecated message (#540).
• Fix compilation with earlier Eigen version
• Fix compilation warning message

File truncated at 100 lines see the full file