![continuous integration](https://github.com/AlexanderFabisch/distance3d/actions/workflows/ci.yml/badge.svg)
[![codecov](https://codecov.io/gh/AlexanderFabisch/distance3d/branch/master/graph/badge.svg?token=GJE5ZMVVB8)](https://codecov.io/gh/AlexanderFabisch/distance3d)
[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.6509736.svg)](https://doi.org/10.5281/zenodo.6509736)

# distance3d

Distance computation and collision detection in 3D.

<table>
<tr>
    <td><img src="https://raw.githubusercontent.com/AlexanderFabisch/distance3d/master/doc/source/_static/robot_collision_detection.png" width=100% /></td>
    <td><img src="https://raw.githubusercontent.com/AlexanderFabisch/distance3d/master/doc/source/_static/capsule_collisions.png" width=100% /></td>
</tr>
<tr>
    <td><a href="https://github.com/AlexanderFabisch/distance3d/blob/master/examples/visualizations/vis_robot_collision_objects.py">Robot collision detection</a></td>
    <td><a href="https://github.com/AlexanderFabisch/distance3d/blob/master/examples/visualizations/vis_capsules_benchmark.py">Capsule collision detection</a></td>
</tr>
<tr>
    <td><img src="https://raw.githubusercontent.com/AlexanderFabisch/distance3d/master/doc/source/_static/closest_points.png" width=100% /></td>
    <td><img src="https://raw.githubusercontent.com/AlexanderFabisch/distance3d/master/doc/source/_static/hydroelastic_contact_surface.png" width=100% /></td>
</tr>
<tr>
    <td><a href="https://github.com/AlexanderFabisch/distance3d/blob/master/examples/visualizations/vis_closest_points.py">Closest points</a></td>
    <td><a href="https://github.com/AlexanderFabisch/distance3d/blob/master/examples/visualizations/vis_pressure_field.py">Hydroelastic contact</a></td>
</tr>
</table>

## Features

* Collision detection and distance computation with GJK.
* Calculation of penetration depth with EPA.
* Collision detection and calculation of penetration depth with MPR.
* Various specific distance calculations for points, lines, line segments,
  planes, triangles, rectangles, circles, disks, boxes, cylinders, ellipsoids,
  ...
* Broad phase collision detection with bounding volume hierarchy (AABB tree).
* Self-collision detection for robots.
* Contact wrench computation with hydroelastic contact model (pressure field
  model).

## Dependencies

distance3d relies on numba to speed up computations. numba in its latest
version requires at least Python 3.7 and NumPy 1.18. See [here](
https://numba.readthedocs.io/en/stable/user/installing.html#compatibility)
for current requirements. Required Python libraries will automatically be
installed during installation of distance3d.

## Installation

Install the package with

    pip install -e .

or from PyPI with

    pip install distance3d

## Unit Tests

Install dependencies with

    pip install -e .[test]

Run unit tests with

    NUMBA_DISABLE_JIT=1 pytest

You will find the coverage report in `htmlcov/index.html`.

## API Documentation

Install dependencies with

    pip install -e .[doc]

Build API documentation with

    cd doc
    make html

You will find the documentation in `doc/build/html/index.html`.

## Licenses

These implementations are mostly based on

* Christer Ericson: Real-Time Collision Detection, CRC Press, 2004.
* David H. Eberly: 3D Game Engine Design, CRC Press, 2006.

and accompanying implementations. These are marked as such.

The distance computation between a line and a circle is based on David Eberly's
implementation, Copyright (c) 1998-2022 David Eberly, Geometric Tools,
Redmond WA 98052, distributed under the Boost Software License, Version 1.0.

The original GJK algorithm is a translation to Python of the translation to C of
the original Fortran implementation. The C implementation is from Diego Ruspini.
It is available from http://realtimecollisiondetection.net/files/gilbert.c

Some features related to the GJK algorithm have been inspired by
[Bullet](https://github.com/bulletphysics/bullet3/) (zlib license) and are
marked as such in the source code.

The EPA algorithm is adapted from
[Kevin Moran's GJK implementation](https://github.com/kevinmoran/GJK)
(MIT License or Unlicense).

A GJK intersection test and the MPR algorithm are based on libccd (for details,
see https://github.com/danfis/libccd). For the original code the copyright is
of Daniel Fiser <danfis@danfis.cz>. It has been released under 3-clause BSD
license.

The main GJK implementation is based on Jolt Physics, Copyright 2021 Jorrit
Rouwe, MIT license.

The translation to Python has been done by Alexander Fabisch and the glue
code around it is licensed under the 3-clause BSD license.
