API Reference

distance3d

Distance computation and collision detection in 3D.

distance3d.distance

Distance calculation of specific geometric shapes.

Note that for distance calculations to triangles, rectangles, boxes, cylinders, spheres, capsules, and convex meshes GJK is usually the fastest option if applicable. GJK is not applicable if one of the geometric objects is a line or a plane and GJK is slower when one of the objects is a point or a line segment.

In the following table an X indicates that the distance computation between two geometric objects is implemented. G means the pair of shapes is covered by GJK.

	point	line	line segment	plane	triangle	rectangle	circle	disk	box	ellipsoid	cylinder
point	-	X	X	X	X	X	X	X	X	X	X
line	X	X	X	X	X	X	X	-	X	-	-
line segment	X	X	X	X	X	X	X	G	X	G	G
plane	X	X	X	X	X	X	-	-	X	X	X
triangle	X	X	X	X	X	X	-	G	G	G	G
rectangle	X	X	X	X	X	G	-	G	G	G	G
circle	X	X	X	-	-	-	-	-	-	-	-
disk	X	-	G	-	G	G	-	X	G	G	G
box	X	X	X	X	G	G	-	G	G	G	G
ellipsoid	X	-	G	X	G	G	-	G	G	G	G
cylinder	X	-	G	X	G	G	-	G	G	G	G

point_to_line	Compute the shortest distance between point and line.
point_to_line_segment	Compute the shortest distance between point and line segment.
point_to_plane	Compute the shortest distance between a point and a plane.
point_to_triangle	Compute the shortest distance between point and triangle.
point_to_rectangle	Compute the shortest distance from point to rectangle.
point_to_circle	Compute the shortest distance between point and circle (only line).
point_to_disk	Compute the shortest distance between point and disk.
point_to_box	Compute the shortest distance between point and box.
point_to_cylinder	Compute the shortest distance between point and cylinder.
point_to_ellipsoid	Compute the shortest distance between point and ellipsoid.
line_to_line	Compute the shortest distance between two lines.
line_to_line_segment	Compute the shortest distance between line and line segment.
line_to_plane	Compute the shortest distance from line to plane.
line_to_triangle	Compute the shortest distance between point and triangle.
line_to_rectangle	Compute the shortest distance between line and rectangle.
line_to_circle	Compute the shortest distance between line and circle.
line_to_box	Compute the shortest distance between line and box.
line_segment_to_line_segment	Compute the shortest distance between two line segments.
line_segment_to_plane	Compute the shortest distance between line segment and plane.
line_segment_to_triangle	Compute the shortest distance from line segment to triangle.
line_segment_to_rectangle	Compute the shortest distance between line segment and rectangle.
line_segment_to_circle	Compute the shortest distance between line segment and circle.
line_segment_to_box	Compute the shortest distance from line segment to box.
plane_to_plane	Compute the shortest distance between two planes.
plane_to_triangle	Compute the shortest distance between a plane and a triangle.
plane_to_rectangle	Compute the shortest distance between a plane and a rectangle.
plane_to_box	Compute the shortest distance between a plane and a box.
plane_to_ellipsoid	Compute the shortest distance between a plane and an ellipsoid.
plane_to_cylinder	Compute the shortest distance between a plane and a cylinder.
triangle_to_triangle	Compute the shortest distance between two triangles.
triangle_to_rectangle	Compute the shortest distance between triangle and rectangle.
rectangle_to_rectangle	Compute the shortest distance between two rectangles.
rectangle_to_box	Compute the shortest distance from rectangle to box.
disk_to_disk	Compute the shortest distance between two disks.

distance3d.colliders

Colliders used for collision detection with GJK and MPR algorithms.

ConvexCollider	Convex collider base class.
ConvexHullVertices	Convex hull of a set of vertices.
MeshGraph	Mesh collider that uses triangles for hill climbing.
Box	Box collider.
Sphere	Sphere collider.
Capsule	Capsule collider.
Ellipsoid	Ellipsoid collider.
Cylinder	Cylinder collider.
Disk	Disk collider.
Ellipse	Ellipse collider.
Cone	Cone collider.
Margin	Margin around collider.

distance3d.broad_phase

Broad-phase collision detection.

BoundingVolumeHierarchy

Bounding volume hierarchy (BVH) for broad phase collision detection.

distance3d.containment

Containment methods compute bounding volumes.

axis_aligned_bounding_box	Compute axis-aligned bounding box (AABB) that contains points.
sphere_aabb	Compute axis-aligned bounding box of sphere.
box_aabb	Compute axis-aligned bounding box of an oriented box.
cylinder_aabb	Compute axis-aligned bounding box of cylinder.
capsule_aabb	Compute axis-aligned bounding box of a capsule.
ellipsoid_aabb	Compute axis-aligned bounding box of a capsule.
disk_aabb	Compute axis-aligned bounding box of a disk.
ellipse_aabb	Compute axis-aligned bounding box of an ellipse.
cone_aabb	Compute axis-aligned bounding box of a cone.

distance3d.gjk

Gilbert-Johnson-Keerthi (GJK) for distance calculation of convex shapes.

The GJK algorithm only works for convex shapes. Concave objects have to be decomposed into convex shapes first.

This module contains several flavours of the GJK algorithm. Some of them only detect collisions (intersections) and some of them calculate distances between separated objects as well.

The original publication describing the algorithm is:

E.G. Gilbert, D.W. Johnson, S.S. Keerthi: A fast procedure for computing the distance between complex objects in three-dimensional space, IEEE Journal on Robotics and Automation (1988), https://graphics.stanford.edu/courses/cs448b-00-winter/papers/gilbert.pdf

gjk	Gilbert-Johnson-Keerthi (GJK) algorithm for distance calculation.
gjk_distance	Gilbert-Johnson-Keerthi (GJK) algorithm for distance calculation.
gjk_intersection	Intersection test with Gilbert-Johnson-Keerthi (GJK) algorithm.
gjk_distance_jolt	Gilbert-Johnson-Keerthi (GJK) algorithm for distance calculation.
gjk_intersection_jolt	Intersection test with Gilbert-Johnson-Keerthi (GJK) algorithm.
gjk_distance_original	Gilbert-Johnson-Keerthi (GJK) algorithm for distance calculation.
gjk_intersection_libccd	Intersection test with Gilbert-Johnson-Keerthi (GJK) algorithm.
gjk_nesterov_accelerated_distance	Nesterov-accelerated GJK algorithm for distance calculation.
gjk_nesterov_accelerated_intersection	Intersection test with Nesterov-accelerated GJK.
gjk_nesterov_accelerated_primitives_distance	Nesterov-accelerated GJK algorithm for distance calculation.
gjk_nesterov_accelerated_primitives_intersection	Intersection test with Nesterov-accelerated GJK.

distance3d.epa

Expanding polytope algorithm (EPA) for collision resolution after GJK.

epa	Expanding Polytope Algorithm (EPA).

distance3d.mpr

Minkowski portal refinement (MPR) for collision detection.

Another name for the algorithm is XenoCollide (for details, see http://xenocollide.snethen.com/). It has been presented in “Game Programming Gems 7” (Gem 2.5: XenoCollide: Complex Collision Made Simple).

This implementation of MPR is 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.

mpr_intersection	Intersection test with Minkowski Portal Refinement (MPR).
mpr_penetration	Minkowski Portal Refinement (MPR) with penetration info.

distance3d.geometry

Tools for geometric computations.

convert_rectangle_to_segment	Extract line segment from rectangle.
convert_rectangle_to_vertices	Convert rectangle to vertices.
convert_box_to_face	Convert box to face.
convert_segment_to_line	Convert line segment to line.
convert_box_to_vertices	Convert box to vertices.
support_function_cylinder	Compute extreme point of cylinder along a direction.
support_function_capsule	Compute extreme point of cylinder along a direction.
support_function_ellipsoid	Compute extreme point of ellipsoid along a direction.
support_function_box	Compute extreme point of box along a direction.
support_function_sphere	Compute extreme point of box along a direction.
support_function_disk	Compute extreme point of disk along a direction.
support_function_ellipse	Compute extreme point of ellipse along a direction.
support_function_cone	Compute extreme point of cone along a direction.
hesse_normal_form	Computes Hesse normal form of a plane.
line_from_pluecker	Computes line from Plücker coordinates.

distance3d.self_collision

Self-collision detection.

detect	Detect self collisions of a robot represented by a BVH.
detect_any	Detect self collisions of a robot represented by a BVH.

distance3d.containment_test

points_in_sphere	Test if points are in sphere.
points_in_capsule	Test if points are in capsule.
points_in_ellipsoid	Test if points are in ellipsoid.
points_in_disk	Test if points are in disk.
points_in_cone	Test if points are in cone.
points_in_cylinder	Test if points are in cylinder.
points_in_box	Test if points are in box.
points_in_convex_mesh	Test if points are in convex mesh.

distance3d.hydroelastic_contact

Hydroelastic contact model for contact wrenches of rigid bodies.

The original name for this model is pressure field model. It has been presented in:

R. Elandt, E. Drumwright, M. Sherman and A. Ruina: A pressure field model for fast, robust approximation of net contact force and moment between nominally rigid objects, IEEE/RSJ International Conference on Intelligent Robots and Systems (IROS), 2019, pp. 8238-8245, doi: 10.1109/IROS40897.2019.8968548.

The implementation is different, but is inspired by:

V. Huang, F. Wang, E. Zhang: An Efficient Implementation of Pressure Field Models, https://www.ekzhang.com/assets/pdf/Hydroelastics.pdf.

contact_forces	Contact forces between two objects.
find_contact_surface	Find contact plane of two rigid bodies.
RigidBody	Rigid body represented by tetrahedral mesh.
ContactSurface	Contact surface of tetrahedral meshes.

distance3d.plotting

Plotting functions for geometric shapes.

plot_line	Plot line.
plot_segment	Plot line.
plot_plane	Plot rectangle.
plot_triangle	Plot triangle.
plot_rectangle	Plot rectangle.
plot_circle	Plot circle.
plot_ellipse	Plot ellipse.
plot_aabb	Plot axis-aligned bounding box.
plot_convex	Plot convex mesh.
plot_tetrahedron	Plot tetrahedron.
plot_aabb_tree	Plot tree of axis-aligned bounding boxes.

distance3d.random

Sample geometric shapes.

randn_point	Sample 3D point from standard normal distribution.
randn_direction	Sample 3D direction from standard normal distribution and normalize it.
randn_line	Sample 3D line.
randn_line_segment	Sample 3D line segment.
randn_plane	Sample plane in 3D.
randn_rectangle	Sample rectangle.
randn_triangle	Sample triangle.
rand_box	Sample box.
rand_capsule	Sample capsule.
rand_ellipsoid	Sample ellipsoid.
rand_cylinder	Sample cylinder.
rand_sphere	Sample sphere.
rand_ellipse	Sample ellipse.
rand_cone	Sample cone.
randn_convex	Sample convex mesh.

distance3d.aabb_tree

AabbTree	AABB Tree for broad phase collision detection.
all_aabbs_overlap	Creates result lists of all the overlapping aabbs (brute force).
aabb_overlap	Returns true if aabb1 and aabb2 overlap.