-
ROS index logo ROS Index
  1. Home
  2. Repos
  3. coal
  4. coal
 

coal package from coal repo

coal

API Docs
Browse Code

Package Summary

Tags No category tags.
Version 3.0.0
License BSD
Build type CMAKE
Use RECOMMENDED

Repository Summary

Checkout URI https://github.com/coal-library/coal.git
VCS Type git
VCS Version master
Last Updated 2024-11-20
Dev Status DEVELOPED
CI status No Continuous Integration
Released UNRELEASED
Tags No category tags.
Contributing Help Wanted (0)
Good First Issues (0)
Pull Requests to Review (0)

Package Description

An extension of the Flexible Collision Library.

Additional Links

Maintainers

  • Joseph Mirabel
  • Justin Carpentier
  • Louis Montaut
  • Wolfgang Merkt

Authors

No additional authors.
README.md

Coal — An extension of the Flexible Collision Library

Pipeline status Documentation Coverage report Conda Downloads Conda Version PyPI version black ruff

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 (for the unused and untested part), and new features have been developped (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’d 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 performances (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 many robotics frameworks such as Pinocchio, an open-source software that implements efficient and versatile rigid body dynamics algorithms, the Humanoid Path Planner, an open-source software for Motion and Manipulation Planning. Coal has also been recently 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 performances, as depicted by the figures below.

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

  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.

Coal vs the rest of the world

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:

Coal vs generic QP solvers

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 Pinocchio

  • 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)

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++:

#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 <iostream>
#include <memory>

// Function to load a convex mesh from a `.obj`, `.stl` or `.dae` file.
//
// This function imports the object inside the file as a BVHModel, i.e. a point cloud
// which is hierarchically transformed into a tree of bounding volumes.
// The leaves of this tree are the individual points of the point cloud
// stored in the `.obj` file.
// This BVH can then be used for collision detection.
//
// For better computational efficiency, we sometimes prefer to work with
// the convex hull of the point cloud. This insures that the underlying object
// is convex and thus very fast collision detection algorithms such as
// GJK or EPA can be called with this object.
// Consequently, after creating the BVH structure from the point cloud, this function
// also computes its convex hull.
std::shared_ptr<coal::ConvexBase> loadConvexMesh(const std::string& file_name) {
  coal::NODE_TYPE bv_type = coal::BV_AABB;
  coal::MeshLoader loader(bv_type);
  coal::BVHModelPtr_t bvh = loader.load(file_name);
  bvh->buildConvexHull(true, "Qt");
  return bvh->convex;
}

int main() {
  // Create the coal shapes.
  // Coal supports many primitive shapes: boxes, spheres, capsules, cylinders, ellipsoids, cones, planes,
  // halfspace and convex meshes (i.e. convex hulls of clouds of points).
  // It also supports BVHs (bounding volumes hierarchies), height-fields and octrees.
  std::shared_ptr<coal::Ellipsoid> shape1 = std::make_shared<coal::Ellipsoid>(0.7, 1.0, 0.8);
  std::shared_ptr<coal::ConvexBase> shape2 = loadConvexMesh("../path/to/mesh/file.obj");

  // Define the shapes' placement in 3D space
  coal::Transform3s T1;
  T1.setQuatRotation(coal::Quaternion3f::UnitRandom());
  T1.setTranslation(coal::Vec3s::Random());
  coal::Transform3s T2 = coal::Transform3s::Identity();
  T2.setQuatRotation(coal::Quaternion3f::UnitRandom());
  T2.setTranslation(coal::Vec3s::Random());

  // Define collision requests and results.
  //
  // The collision request allows to set parameters for the collision pair.
  // For example, we can set a positive or negative security margin.
  // If the distance between the shapes is less than the security margin, the shapes
  // will be considered in collision.
  // Setting a positive security margin can be usefull in motion planning,
  // i.e to prevent shapes from getting too close to one another.
  // In physics simulation, allowing a negative security margin may be usefull to stabilize the simulation.
  coal::CollisionRequest col_req;
  col_req.security_margin = 1e-1;
  // A collision result stores the result of the collision test (signed distance between the shapes,
  // witness points location, normal etc.)
  coal::CollisionResult col_res;

  // Collision call
  coal::collide(shape1.get(), T1, shape2.get(), T2, col_req, col_res);

  // We can access the collision result once it has been populated
  std::cout << "Collision? " << col_res.isCollision() << "\n";
  if (col_res.isCollision()) {
    coal::Contact contact = col_res.getContact(0);
    // The penetration depth does **not** take into account the security margin.
    // Consequently, the penetration depth is the true signed distance which separates the shapes.
    // To have the distance which takes into account the security margin, we can simply add the two together.
    std::cout << "Penetration depth: " << contact.penetration_depth << "\n";
    std::cout << "Distance between the shapes including the security margin: " << contact.penetration_depth + col_req.security_margin << "\n";
    std::cout << "Witness point on shape1: " << contact.nearest_points[0].transpose() << "\n";
    std::cout << "Witness point on shape2: " << contact.nearest_points[1].transpose() << "\n";
    std::cout << "Normal: " << contact.normal.transpose() << "\n";
  }

  // Before calling another collision test, it is important to clear the previous results stored in the collision result.
  col_res.clear();

  return 0;
}

Python example

Here is the C++ example from above translated in python using the python bindings of Coal:

import numpy as np
import coal
# Optional:
# The Pinocchio library is a rigid body algorithms library and has a handy SE3 module.
# It can be installed as simply as `conda -c conda-forge install pinocchio`.
# Installing pinocchio also installs coal.
import pinocchio as pin

def loadConvexMesh(file_name: str):
    loader = coal.MeshLoader()
    bvh: coal.BVHModelBase = loader.load(file_name)
    bvh.buildConvexHull(True, "Qt")
    return bvh.convex

if __name__ == "__main__":
    # Create coal shapes
    shape1 = coal.Ellipsoid(0.7, 1.0, 0.8)
    shape2 = loadConvexMesh("../path/to/mesh/file.obj")

    # Define the shapes' placement in 3D space
    T1 = coal.Transform3s()
    T1.setTranslation(pin.SE3.Random().translation)
    T1.setRotation(pin.SE3.Random().rotation)
    T2 = coal.Transform3s();
    # Using np arrays also works
    T1.setTranslation(np.random.rand(3))
    T2.setRotation(pin.SE3.Random().rotation)

    # Define collision requests and results
    col_req = coal.CollisionRequest()
    col_res = coal.CollisionResult()

    # Collision call
    coal.collide(shape1, T1, shape2, T2, col_req, col_res)

    # Accessing the collision result once it has been populated
    print("Is collision? ", {col_res.isCollision()})
    if col_res.isCollision():
        contact: coal.Contact = col_res.getContact(0)
        print("Penetration depth: ", contact.penetration_depth)
        print("Distance between the shapes including the security margin: ", contact.penetration_depth + col_req.security_margin)
        print("Witness point shape1: ", contact.getNearestPoint1())
        print("Witness point shape2: ", contact.getNearestPoint2())
        print("Normal: ", contact.normal)

    # Before running another collision call, it is important to clear the old one
    col_res.clear()

Acknowledgments

The development of Coal is actively supported by the Gepetto team @LAAS-CNRS, the Willow team @INRIA and, to some extend, Eureka Robotics.

CHANGELOG

Changelog

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

The format is based on Keep a Changelog.

Unreleased

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
  • Fix issue in Octomap.computeLocalAABB
  • Fix unsupported function for contact_patch_matrix
  • Fix Octomap dependency on ROS

2.4.5 - 2024-07-28

Fixed

  • Fix Octomap dependency on ROS

2.4.4 - 2024-03-06

2.4.3 - 2024-03-06

Fixed

  • updated cmake module to fix documentation generation
  • test documentation in conda ci

2.4.2 - 2024-03-06

Fixed

  • Fix CMAKE_INSTALL_{} path for installation (#543)

2.4.1 - 2024-01-23

Fixed

  • CachedMeshLoader checks file last modification time.
  • Fix call to clear methods for {Collision,Distance}Data inside init function (#509)
  • CMake: fix submodule use in bindings in (#512)
  • Fix bug in DynamicAABBTreeCollisionManager (see #514) in (#515)

    Added

  • In struct Contact
    • Documentation of the members,
    • initialization of normal, closest points and contact point in constructors
    • method getDistanceToCollision
  • New variant of GJK (PolyakAcceleration).
  • Specialization of distance computation between
    • Sphere and Capsule,
    • Ellipsoid and Halfspace,
    • Ellipsoid and Plane.
  • Collision computation between Octree and HeightField.

Changed

  • Matrixx3f and Matrixx3i become row major.
  • Use shared pointers to vectors instead of arrays for vertices and triangles in class BVHModelBase.

Removed

  • members related epa in class QueryRequest

2.4.0 - 2023-11-27

Added

  • Add method to CollisionObject to get CollisionGeometry raw pointer

Fixed

  • Fix RPATH computation on OSX
  • Fix Python stubs generation on Windows

2.3.7 - 2023-11-15

What’s Changed

2.3.6 - 2023-09-30

What’s Changed

New Contributors

2.3.5 - 2023-07-11

What’s Changed

2.3.4 - 2023-06-01

What’s Changed

2.3.3 - 2023-05-09

What’s Changed

2.3.2 - 2023-04-27

What’s Changed

2.3.1 - 2023-03-25

What’s Changed

2.3.0 - 2023-03-17

What’s Changed

2.2.0 - 2022-12-12

What’s Changed

2.1.4 - 2022-10-24

What’s Changed

2.1.3 - 2022-09-13

What’s Changed

New Contributors

2.1.2 - 2022-08-01

What’s Changed

  • core: add EPA::FallBack condition to shapeDistance computation by @lmontaut (#325)
  • CMake: update to eigenpy 2.7.10 by @nim65s (#327)

2.1.1 - 2022-07-25

What’s Changed

  • cmake: relocatable package for recent CMake versions by @nim65s (#319)
  • ROS2/Colcon integration by @wxmerkt (#321)

2.1.0 - 2022-07-13

What’s Changed

New Contributors

2.0.1 - 2022-04-15

This PR mainly fixes packaging issues and removes compilation warnings.

What’s Changed

New Contributors

2.0.0 - 2022-04-06

This new release reintroduces the full support of Broad phase within hpp-fcl while also enforcing C++11 as minimal standard.

What’s Changed

New Contributors

1.8.1 - 2022-03-20

What’s Changed

1.8.0 - 2022-02-08

What’s Changed

1.7.8 - 2021-10-30

What’s Changed

1.7.7 - 2021-09-13

This new release fixes several bugs within the framework.

1.7.6 - 2021-09-08

This new release improves the packaging of the project and integrates the Stub generation of Python bindings.

1.7.5 - 2021-07-30

This new release provides extended API exposition in Python, removes some code related to CDD while also trying to rely on the QHULL version present on the system.

1.7.4 - 2021-06-11

This release fixes several bugs:

  • correct update of the distance lower bound
  • fix memory footprint computation

while also removing the support of Travis CI.

1.7.3 - 2021-05-26

This new release provides:

  • fixes of LINE and POINTS when loading meshes with assimp
  • removing of various warnings
  • computation of memory footprint for geometries

1.7.2 - 2021-04-19

This new release improves the loading of meshes using Assimp by automatically removing degenerated LINES and POINTS.

1.7.1 - 2021-04-02

This new release reduces the impact of timers on the computations. This should be used with care and can be enabled by setting the correct flag to true in the QueryRequest.

1.7.0 - 2021-03-31

This new release provides:

  • extended support for serialization
  • timing of the collision/distance computations
  • helpers to build octree
  • various bug fixes and interface improvements

1.6.0 - 2020-10-06

This new release provides:

  • functors for evaluating Collision and Distances (faster call)
  • extended support of v142 compiler
  • support of collision check between HalfSpace and Convex shapes
  • improvement of GJK solver
  • fixes on Python bindings

1.5.4 - 2020-09-22

In this new release, the support of collision checking between Convex objects and HalfSpace have been enhanced and some minor fixes have been provided.

1.5.3 - 2020-08-31

This new release provides better CMake packaging and improved GJK algorithms.

1.5.2 - 2020-08-15

This release improves the packaging of the project and provides fixes for the GJK solver.

1.5.1 - 2020-08-06

This new release fixes packaging issues with precedent release 1.5.0. It also provides additional fixes in main collision/distance algorithms.

1.4.6 - 2020-06-10

This new release enhances the packaging of the project and allows the compilation of FCL on Windows systems.

1.4.5 - 2020-06-03

Changes in v1.4.5:

  • Fix Python 3 doc generation
  • Fix packaging of the project
  • Compilation on Windows.
  • [CMake] Install missing header.
  • Add collide and distance prototype that update the GJK guess.
  • Add support function cached guess in queries and merge query attribute.
  • Add function to generate the convex hull.
  • Add hint to the support function + Fix usage of GJK guess.
  • [Python] Add constructor for class Convex.
  • [Python] Bind functions to create BVHModel.

1.4.4 - 2020-04-29

Changes in 1.4.4:

  • add MeshLoader::loadOctree
  • fix generation of XML documentation
  • fix generation of Doxygen documentation

1.4.3 - 2020-04-08

This new release fixes some packagings issues for OS X systems.

1.4.2 - 2020-04-04

Changes in v1.4.2:

  • don’t require linking to eigenpy in .pc file.

1.4.1 - 2020-04-03

Changes in v1.4.1:

  • Bug fix + prepare optimization of collision using GJK / EPA
  • Add missing constructor for Transform3f

1.4.0 - 2020-04-03

Changes since v1.3.0:

  • Improve code efficiency + use shared memory between Numpy and Eigen
  • [Python] Doc and minor update + [C++] bugfix
  • [Python] Fix bindings of CollisionResult.
  • FIX: throw when no contact is available
  • Minor fix and computational improvments
  • [GJK/EPA] Fix bugs + Treat sphere as point and capsule as line segment.
  • Fix boxSphereDistance
  • Provide documentation for the Python bindings.
  • Generate Python documentation from doxygen documentation.
  • Fix issue when Python_EXECUTABLE is not defined
  • update CMake packaging

1.3.0 - 2020-01-28

This new release comes with:

  • the removing of the GJK solver
  • the Python bindings build by default
  • an improved documentation
  • additional Python bindings

1.2.2 - 2019-12-17

This new Release improves the Python bindings and fixes an important bug when checking the collision between two Capsules.

Thanks to @rstrudel for this fix.

1.2.1 - 2019-12-09

This new release improves both the packaging of the project, which seems to be totally compatible with the new CMake linkage style. In addition, the bindings are now fully compatible with Pinocchio.

1.2.0 - 2019-11-22

Changes since v1.1.3:

  • Add python bindings
  • Update CMake
  • Add version support
  • New folder Internal for internal header
  • Travis: update CI & change policy to only perform build in DEBUG mode on Bionic
  • assimp: fix issue with recent version of assimp
  • [bindings] [CMakeLists] Use .so for Mac and .pyd for Windows, fix #86
  • Organize documentation
  • [CMake] fix octomap detection
  • [Minor] update CMake module + fix visibility of some methods.
  • Enable Convex / Convex queries + Add Python bindings.
  • Fix unit-tests and compilation
  • [GJK] Fix GJK::encloseOrigin (fixes unit-tests)
  • Improve GJK implementation + OBB overlap test + bug fixes
  • Clean include BV/BVH/math/mesh_loader

1.1.3 - 2019-08-07

This new release enhances the compatibility of hpp-fcl with C++14 and more. This feature is requested for integration in Anaconda.

1.1.2 - 2019-08-05

This new release provides a fix in the parallelization of the computations and improves the packaging of the whole project.

1.0.2 - 2019-04-24

Changes since v1.0.1:

  • obb: fix compatibility with Eigen 3.0.5
  • [CI] octomap for osx

1.0.1 - 2019-02-20

  • Fix CI on OSX
  • Declare CachedMeshLoader::Key::operator<
  • minor details

0.7.0 - 2019-01-31

This release is mainly here to allow the packaging of HPP-RBPRM. Another release will follow with more news.

0.6.0 - 2018-10-22

  • Fix bug when OCTOMAP is not found
  • move buildTrianglePlane and clipTriangle method from private to public
  • Fix bug with “" symbols
  • [CMake] Add flags related to Octomap in pkg-config file and remove FCL_HAVE_EIGEN

0.5.1 - 2017-10-02

Now Eigen is at the heart of linear algebra computations.

0.5 - 2017-03-17

First release

Wiki Tutorials

This package does not provide any links to tutorials in it's rosindex metadata. You can check on the ROS Wiki Tutorials page for the package.

Package Dependencies

Deps Name
catkin
eigenpy

System Dependencies

Name
git
doxygen
python-lxml
python3-lxml
cmake
python
python-numpy
python3
python3-numpy
eigen
boost
assimp
liboctomap-dev

Dependant Packages

No known dependants.

Launch files

No launch files found

Messages

No message files found.

Services

No service files found

Plugins

No plugins found.

Recent questions tagged coal at Robotics Stack Exchange