.clang-format

+BasedOnStyle: Google
+SortIncludes: false

.git-blame-ignore-revs

+0067c8aa66aac548601e2a3fd029aa264cc59f2a
+76b68f785df31b00e153290b45ec290a9c5f7963
+# ruff --fix . (Guilhem Saurel, 2023-10-25)
+02cef56abfacee590c8444fd379c8837bf007fa1
+# black . (Guilhem Saurel, 2023-10-25)
+febfbcbe9c98cdb4e0c7bbf4554a6925b391834b
+# ruff --fix . (Guilhem Saurel, 2023-10-24)
+58dee5ae90eded5125825a2da0fe76a5031f3334
+# black . (Guilhem Saurel, 2023-10-24)
+889ff8d1ca00b9e317e1da4136e233bb49a049df

.gitattributes

+# SCM syntax highlighting
+pixi.lock linguist-language=YAML linguist-generated=true

.github/workflows/check-changelog.yml

+name: Check-changelog
+on:
+  pull_request:
+    types: [assigned, opened, synchronize, reopened, labeled, unlabeled]
+    branches:
+      - devel
+jobs:
+  check-changelog:
+    name: Check changelog action
+    runs-on: ubuntu-latest
+    steps:
+      - uses: tarides/changelog-check-action@v2
+        with:
+          changelog: CHANGELOG.md

.github/workflows/macos-linux-pip.yml

+name: CI - MacOS/Linux via pip
+
+on:
+  push:
+    paths-ignore:
+      - .gitlab-ci.yml
+      - .gitignore
+      - '*.md'
+      - CITATION.*
+      - LICENSE
+      - colcon.pkg
+      - .pre-commit-config.yaml
+      - CHANGELOG.md
+      - development/*.md
+  pull_request:
+    paths-ignore:
+      - .gitlab-ci.yml
+      - .gitignore
+      - '*.md'
+      - CITATION.*
+      - LICENSE
+      - colcon.pkg
+      - .pre-commit-config.yaml
+      - CHANGELOG.md
+      - development/*.md
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+env:
+    CTEST_OUTPUT_ON_FAILURE: 1
+    CTEST_PARALLEL_LEVEL: 4
+
+jobs:
+  coal-pip:
+    name: "CI on ${{ matrix.os }} / py ${{ matrix.python-version }} with pip"
+    runs-on: "${{ matrix.os }}-latest"
+
+    strategy:
+      fail-fast: false
+      matrix:
+        os: ["ubuntu", "macos"]
+        python-version: ["3.8", "3.9", "3.10", "3.11", "3.12", "3.13"]
+        exclude:
+          - os: "macos"
+            python-version: "3.8"  # Not available on arm64
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          submodules: 'true'
+      - uses: actions/setup-python@v4
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: python -m pip install -U pip
+      - run: python -m pip install cmeel-assimp cmeel-octomap cmeel-qhull eigenpy[build]
+      - run: echo "CMAKE_PREFIX_PATH=$(cmeel cmake)" >> $GITHUB_ENV
+      - run: cmake -B build -S . -DCOAL_HAS_QHULL=ON
+      - run: cmake --build build -j 4
+      - run: cmake --build build -t test

.github/workflows/macos-linux-windows-pixi.yml

+name: CI - MacOS/Linux/Windows via Pixi
+
+on:
+  push:
+    paths-ignore:
+      - .gitlab-ci.yml
+      - .gitignore
+      - '*.md'
+      - CITATION.*
+      - LICENSE
+      - colcon.pkg
+      - .pre-commit-config.yaml
+      - CHANGELOG.md
+      - development/*.md
+  pull_request:
+    paths-ignore:
+      - .gitlab-ci.yml
+      - .gitignore
+      - '*.md'
+      - CITATION.*
+      - LICENSE
+      - colcon.pkg
+      - .pre-commit-config.yaml
+      - CHANGELOG.md
+      - development/*.md
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  coal-pixi:
+    name: ${{ matrix.os }} - Env ${{ matrix.environment }} ${{ matrix.build_type }} ${{ matrix.cxx_options }}
+    runs-on: ${{ matrix.os }}
+    env:
+      CCACHE_BASEDIR: "${GITHUB_WORKSPACE}"
+      CCACHE_DIR: "${GITHUB_WORKSPACE}/.ccache"
+      CCACHE_COMPRESS: true
+      CCACHE_COMPRESSLEVEL: 6
+
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, macos-13]
+        environment: [all, all-python-oldest]
+        build_type: [Release, Debug]
+        cxx_options: ['', '-mavx2']
+        exclude:
+          - os: macos-latest
+            cxx_options: '-mavx2'
+          - os: macos-13
+            cxx_options: '-mavx2'
+
+        include:
+          - os: windows-latest
+            environment: all
+            cxx_options: ''
+            build_type: Release
+          - os: windows-latest
+            environment: all-clang-cl
+            cxx_options: ''
+            build_type: Release
+          - os: windows-latest
+            environment: default
+            cxx_options: ''
+            build_type: Debug
+
+    steps:
+    - uses: actions/checkout@v4
+      with:
+        submodules: recursive
+
+    - uses: actions/cache@v4
+      with:
+        path: .ccache
+        key: ccache-macos-linux-windows-pixi-${{ matrix.os }}-${{ matrix.build_type }}-${{ matrix.cxx_options }}-${{ matrix.environment }}-${{ github.sha }}
+        restore-keys: ccache-macos-linux-windows-pixi-${{ matrix.os }}-${{ matrix.build_type }}-${{ matrix.cxx_options }}-${{ matrix.environment }}-
+
+    - uses: prefix-dev/setup-pixi@v0.8.1
+      with:
+        cache: true
+        environments: ${{ matrix.environment }}
+
+    - name: Build Coal [MacOS/Linux/Windows]
+      env:
+        CMAKE_BUILD_PARALLEL_LEVEL: 2
+        COAL_BUILD_TYPE: ${{ matrix.build_type }}
+        COAL_CXX_FLAGS: ${{ matrix.cxx_options }}
+      run: |
+        pixi run -e ${{ matrix.environment }} build
+
+    - name: Test Coal [MacOS/Linux/Windows]
+      if: ${{ ! (contains(matrix.os, 'windows') && matrix.build_type == 'Debug') }}
+      run: |
+        pixi run -e ${{ matrix.environment }} ctest --test-dir build --output-on-failure
+
+  check:
+    if: always()
+    name: check-macos-linux-windows-pixi
+
+    needs:
+    - coal-pixi
+
+    runs-on: Ubuntu-latest
+
+    steps:
+    - name: Decide whether the needed jobs succeeded or failed
+      uses: re-actors/alls-green@release/v1
+      with:
+        jobs: ${{ toJSON(needs) }}

.github/workflows/nix.yml

+name: "CI - Nix"
+
+on:
+  push:
+    paths-ignore:
+      - .gitlab-ci.yml
+      - .gitignore
+      - '*.md'
+      - CITATION.*
+      - LICENSE
+      - colcon.pkg
+      - .pre-commit-config.yaml
+      - CHANGELOG.md
+      - development/*.md
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  nix:
+    runs-on: "${{ matrix.os }}-latest"
+    strategy:
+      matrix:
+        os: [ubuntu, macos]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: cachix/install-nix-action@v27
+      - uses: cachix/cachix-action@v15
+        with:
+          name: gepetto
+          authToken: '${{ secrets.CACHIX_AUTH_TOKEN }}'
+      - run: nix build -L

.github/workflows/ros_ci.yml

+# This config uses industrial_ci (https://github.com/ros-industrial/industrial_ci.git).
+# For troubleshooting, see readme (https://github.com/ros-industrial/industrial_ci/blob/master/README.rst)
+
+name: ROS-CI
+
+# This determines when this workflow is run
+on:
+  push:
+    paths-ignore:
+      - .gitlab-ci.yml
+      - .gitignore
+      - '*.md'
+      - CITATION.*
+      - LICENSE
+      - .pre-commit-config.yaml
+      - CHANGELOG.md
+      - development/*.md
+  pull_request:
+    paths-ignore:
+      - .gitlab-ci.yml
+      - .gitignore
+      - '*.md'
+      - CITATION.*
+      - LICENSE
+      - .pre-commit-config.yaml
+      - CHANGELOG.md
+      - development/*.md
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  CI:
+    strategy:
+      matrix:
+        env:
+          - {ROS_DISTRO: noetic}
+          - {ROS_DISTRO: iron}
+          - {ROS_DISTRO: humble}
+          #- {ROS_DISTRO: rolling}
+    env:
+      #CCACHE_DIR: /github/home/.ccache # Enable ccache
+      BUILDER: colcon
+      PRERELEASE: true
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          submodules: recursive
+      # This step will fetch/store the directory used by ccache before/after the ci run
+      #- uses: actions/cache@v3
+      #  with:
+      #    path: ${{ env.CCACHE_DIR }}
+      #    key: ccache-${{ matrix.env.ROS_DISTRO }}-${{ matrix.env.ROS_REPO }}
+      # Run industrial_ci
+      - uses: 'ros-industrial/industrial_ci@9f963f67ebb889792175776c5ee00134d7bb569b'
+        env: ${{ matrix.env }}
+
+  check:
+    if: always()
+    name: check-ros-ci
+
+    needs:
+    - CI
+
+    runs-on: Ubuntu-latest
+
+    steps:
+    - name: Decide whether the needed jobs succeeded or failed
+      uses: re-actors/alls-green@release/v1
+      with:
+        jobs: ${{ toJSON(needs) }}

.github/workflows/update-flake-lock.yml

+name: update-flake-lock
+
+on:
+  workflow_dispatch:
+  schedule:
+    - cron: '0 11 12 * *'
+
+jobs:
+  lockfile:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+      - name: Install Nix
+        uses: DeterminateSystems/nix-installer-action@main
+      - name: Update flake.lock
+        uses: DeterminateSystems/update-flake-lock@main
+        with:
+          pr-labels: "no changelog"
+          token: ${{ secrets.GH_TOKEN_FOR_UPDATES }}

.github/workflows/update_pixi_lockfile.yml

+name: CI - Update Pixi lockfile
+permissions:
+  contents: write
+  pull-requests: write
+
+on:
+  workflow_dispatch:
+  schedule:
+    - cron: 0 5 1 * *
+
+jobs:
+  pixi-update:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/create-github-app-token@v1
+        id: generate-token
+        with:
+          app-id: ${{ secrets.APP_ID }}
+          private-key: ${{ secrets.APP_PRIVATE_KEY }}
+
+      - uses: actions/checkout@v4
+        with:
+          token: ${{ steps.generate-token.outputs.token }}
+          ref: devel
+          # Make sure the value of GITHUB_TOKEN will not be persisted in repo's config
+          persist-credentials: false
+
+      - name: Set up pixi
+        uses: prefix-dev/setup-pixi@v0.8.1
+        with:
+          run-install: false
+
+      - name: Update lockfile
+        run: |
+          set -o pipefail
+          pixi update --json | pixi exec pixi-diff-to-markdown >> diff.md
+
+      - name: Create pull request
+        uses: peter-evans/create-pull-request@v7
+        with:
+          token: ${{ steps.generate-token.outputs.token }}
+          commit-message: 'pixi: Update pixi lockfile'
+          title: Update pixi lockfile
+          body-path: diff.md
+          branch: topic/update-pixi
+          base: devel
+          labels: |
+            pixi
+            no changelog
+          delete-branch: true
+          add-paths: pixi.lock

.gitignore

+build*/
+Xcode/*
+*~
+*.pyc
+
+
+# pixi environments
+.pixi
+*.egg-info

.gitlab-ci.yml

+include: https://rainboard.laas.fr/project/coal/.gitlab-ci.yml

.gitmodules

+[submodule "cmake"]
+	path = cmake
+	url = https://github.com/jrl-umi3218/jrl-cmakemodules.git
+[submodule "third-parties/qhull"]
+	path = third-parties/qhull
+	url = https://github.com/qhull/qhull.git

.pre-commit-config.yaml

+ci:
+  autoupdate_branch: devel
+  autofix_prs: false
+  autoupdate_schedule: quarterly
+repos:
+- repo: https://github.com/astral-sh/ruff-pre-commit
+  rev: v0.8.6
+  hooks:
+  - id: ruff
+    args:
+    - --fix
+    - --exit-non-zero-on-fix
+  - id: ruff-format
+- repo: https://github.com/pre-commit/mirrors-clang-format
+  rev: v19.1.6
+  hooks:
+  - id: clang-format
+    args:
+    - '--style={BasedOnStyle: Google, SortIncludes: false}'
+- repo: https://github.com/pre-commit/pre-commit-hooks
+  rev: v5.0.0
+  hooks:
+  - id: trailing-whitespace

CITATION.bib

+@misc{coalweb,
+   author = {Jia Pan and Sachin Chitta and Dinesh Manocha and Florent Lamiraux and Joseph Mirabel and Justin Carpentier and Louis Montaut and others},
+   title = {Coal: an extension of the Flexible Collision Library},
+   howpublished = {https://github.com/coal-library/coal},
+   year = {2015--2024}
+}

CITATION.cff

+cff-version: 1.2.0
+message: "Thanks for using Coal. Please use the following metadata to cite us in your documents."
+authors:
+  - family-names: Pan
+    given-names: Jia
+  - family-names: Chitta
+    given-names: Sachin
+  - family-names: Pan
+    given-names: Jia
+  - family-names: Manocha
+    given-names: Dinesh
+  - family-names: Mirabel
+    given-names: Joseph
+  - family-names: Carpentier
+    given-names: Justin
+    orcid: "https://orcid.org/0000-0001-6585-2894"
+  - family-names: Montaut
+    given-names: Louis
+title: "Coal - An extension of the Flexible Collision Library"
+abstract: "An extension of the Flexible Collision Library"
+version: 3.0.1
+date-released: "2025-02-12"
+license: BSD-2-Clause
+url: "https://github.com/coal-library/coal"
+

LICENSE

+Software License Agreement (BSD License)
+
+ Copyright (c) 2008-2014, Willow Garage, Inc.
+ Copyright (c) 2014-2015, Open Source Robotics Foundation
+ Copyright (c) 2014-2023, CNRS
+ Copyright (c) 2018-2025, INRIA
+ All rights reserved.
+
+ Redistribution and use in source and binary forms, with or without
+ modification, are permitted provided that the following conditions
+ are met:
+
+  * Redistributions of source code must retain the above copyright
+    notice, this list of conditions and the following disclaimer.
+  * Redistributions in binary form must reproduce the above
+    copyright notice, this list of conditions and the following
+    disclaimer in the documentation and/or other materials provided
+    with the distribution.
+  * Neither the name of Open Source Robotics Foundation nor the names of its
+    contributors may be used to endorse or promote products derived
+    from this software without specific prior written permission.
+
+ THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+ "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+ LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
+ FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
+ COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
+ INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
+ BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+ LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+ CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+ LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
+ ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ POSSIBILITY OF SUCH DAMAGE.

README.md

+# Coal — An extension of the Flexible Collision Library
+
+<p align="center">
+  <a href="https://gepgitlab.laas.fr/humanoid-path-planner/hpp-fcl/commits/master/"><img src="https://gepgitlab.laas.fr/humanoid-path-planner/hpp-fcl/badges/master/pipeline.svg" alt="Pipeline status"/></a>
+  <a href="https://gepettoweb.laas.fr/hpp/hpp-fcl/doxygen-html/index.html"><img src="https://img.shields.io/badge/docs-online-brightgreen" alt="Documentation"/></a>
+  <a href="http://projects.laas.fr/gepetto/doc/humanoid-path-planner/hpp-fcl/master/coverage/"><img src="https://gepgitlab.laas.fr/humanoid-path-planner/hpp-fcl/badges/master/coverage.svg?job=doc-coverage" alt="Coverage report"/></a>
+  <a href="https://anaconda.org/conda-forge/hpp-fcl"><img src="https://img.shields.io/conda/dn/conda-forge/hpp-fcl.svg" alt="Conda Downloads"/></a>
+  <a href="https://anaconda.org/conda-forge/hpp-fcl"><img src="https://img.shields.io/conda/vn/conda-forge/hpp-fcl.svg" alt="Conda Version"/></a>
+  <a href="https://badge.fury.io/py/hpp-fcl"><img src="https://badge.fury.io/py/hpp-fcl.svg" alt="PyPI version"></a>
+  <a href="https://github.com/psf/black"><img alt="black" src="https://img.shields.io/badge/code%20style-black-000000.svg"></a>
+  <a href="https://github.com/astral-sh/ruff"><img alt="ruff" src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json"></a>
+</p>
+
+[FCL](https://github.com/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](https://raw.githubusercontent.com/coal-library/coal/devel/CITATION.bib).
+
+## New features
+
+Compared to the original [FCL](https://github.com/flexible-collision-library/fcl) library, the main new features are:
+- dedicated and efficient implementations of the GJK and the EPA algorithms (we do not rely on [libccd](https://github.com/danfis/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](https://hal.archives-ouvertes.fr/hal-03662157/)
+- 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](https://github.com/jcarpent) in 2022, based on the FCL version 0.7.0.
+
+This project is now used in several robotics frameworks such as [Pinocchio](https://github.com/stack-of-tasks/pinocchio), an open-source library which implements efficient and versatile rigid-body dynamics algorithms, the [Humanoid Path Planner](https://humanoid-path-planner.github.io/hpp-doc), an open-source library for Motion and Manipulation Planning. **Coal** has recently also been used to develop [Simple](https://github.com/Simple-Robotics/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](https://en.wikipedia.org/wiki/Gilbert%E2%80%93Johnson%E2%80%93Keerthi_distance_algorithm) and [its variants](https://hal.archives-ouvertes.fr/hal-03662157/) 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](https://github.com/bulletphysics/bullet3),
+2. the original [FCL library](https://github.com/flexible-collision-library/fcl) (used in the [Drake framework]()),
+3. the [libccd library](https://github.com/danfis/libccd) (used in [MuJoCo](http://mujoco.org/)).
+
+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.
+
+<p align="center">
+  <img src="./doc/images/coal-vs-the-rest-of-the-world.png" width="600" alt="Coal vs the rest of the world" align="center"/>
+</p>
+
+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](https://github.com/Simple-Robotics/proxsuite))? Here is why:
+
+<p align="center">
+  <img src="./doc/images/coal-performances.jpg" width="600" alt="Coal vs generic QP solvers" align="center"/>
+</p>
+
+One can observe that GJK-based approaches largely outperform solutions based on classic optimization solvers (e.g., QP solver like [ProxQP](https://github.com/Simple-Robotics/proxsuite)), notably for large geometries composed of tens or hundreds of vertices.
+
+## Open-source projects relying on Pinocchio
+
+- [Pinocchio](https://github.com/stack-of-tasks/pinocchio) A fast and flexible implementation of Rigid Body Dynamics algorithms and their analytical derivatives.
+- [IfcOpenShell](https://github.com/IfcOpenShell/IfcOpenShell) Open source IFC library and geometry engine.
+- [Crocoddyl](https://github.com/loco-3d/crocoddyl) A software to realize model predictive control for complex robotics platforms.
+- [TSID](https://github.com/stack-of-tasks/tsid/) A software that implements a Task Space Inverse Dynamics QP.
+- [HPP](https://humanoid-path-planner.github.io/hpp-doc/) A SDK that implements motion planners for humanoids and other robots.
+- [Jiminy](https://github.com/duburcqa/jiminy) A simulator based on Pinocchio.
+- [ocs2](https://github.com/leggedrobotics/ocs2) A toolbox for Optimal Control for Switched Systems (OCS2)
+
+## Installation
+
+### Conda
+
+Coal can be installed from the [conda-forge channel](https://anaconda.org/conda-forge/coal):
+
+```bash
+conda install coal -c conda-forge
+```
+
+## Build
+
+You can find build instruction [here](./development/build.md).
+
+## 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 <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:
+```python
+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](http://projects.laas.fr/gepetto/) [@LAAS-CNRS](http://www.laas.fr), the [Willow team](https://www.di.ens.fr/willow/) [@INRIA](http://www.inria.fr) and, to some extent, [Eureka Robotics](https://eurekarobotics.com/).