coal  3.0.1
Coal, The Collision Detection Library. Previously known as HPP-FCL, fork of FCL -- The Flexible Collision Library
coal::ContactPatch Struct Reference

This structure allows to encode contact patches. A contact patch is defined by a set of points belonging to a subset of a plane passing by p and supported by n, where n = Contact::normal and p = Contact::pos. If we denote by P this plane and by S1 and S2 the first and second shape of a collision pair, a contact patch is represented as a polytope which vertices all belong to P & S1 & S2, where & denotes the set-intersection. Since a contact patch is a subset of a plane supported by n, it has a preferred direction. In Coal, the Contact::normal points from S1 to S2. In the same way, a contact patch points by default from S1 to S2. More...

#include <coal/collision_data.h>

Collaboration diagram for coal::ContactPatch:

Public Types

enum  PatchDirection { DEFAULT = 0 , INVERTED = 1 }
 Direction of ContactPatch. When doing collision detection, the convention of Coal is that the normal always points from the first to the second shape of the collision pair i.e. from shape1 to shape2 when calling collide(shape1, shape2). The PatchDirection enum allows to identify if the patch points from shape 1 to shape 2 (Default type) or from shape 2 to shape 1 (Inverted type). The Inverted type should only be used for internal Coal computations (it allows to properly define two separate contact patches in the same frame). More...
 
using Polygon = std::vector< Vec2s >
 

Public Member Functions

 ContactPatch (size_t preallocated_size=default_preallocated_size)
 Default constructor. Note: the preallocated size does not determine the maximum number of points in the patch, it only serves as preallocation if the maximum size of the patch is known in advance. Coal will automatically expand/shrink the contact patch if needed. More...
 
Vec3s getNormal () const
 Normal of the contact patch, expressed in the WORLD frame. More...
 
size_t size () const
 Returns the number of points in the contact patch. More...
 
void addPoint (const Vec3s &point_3d)
 Add a 3D point to the set, expressed in the world frame. More...
 
Vec3s getPoint (const size_t i) const
 Get the i-th point of the set, expressed in the 3D world frame. More...
 
Vec3s getPointShape1 (const size_t i) const
 Get the i-th point of the contact patch, projected back onto the first shape of the collision pair. This point is expressed in the 3D world frame. More...
 
Vec3s getPointShape2 (const size_t i) const
 Get the i-th point of the contact patch, projected back onto the first shape of the collision pair. This 3D point is expressed in the world frame. More...
 
Polygonpoints ()
 Getter for the 2D points in the set. More...
 
const Polygonpoints () const
 Const getter for the 2D points in the set. More...
 
Vec2spoint (const size_t i)
 Getter for the i-th 2D point in the set. More...
 
const Vec2spoint (const size_t i) const
 Const getter for the i-th 2D point in the set. More...
 
void clear ()
 Clear the set. More...
 
bool operator== (const ContactPatch &other) const
 Whether two contact patches are the same or not. More...
 
bool isSame (const ContactPatch &other, const Scalar tol=Eigen::NumTraits< Scalar >::dummy_precision()) const
 Whether two contact patches are the same or not. Checks for different order of the points. More...
 

Public Attributes

Transform3s tf
 Frame of the set, expressed in the world coordinates. The z-axis of the frame's rotation is the contact patch normal. More...
 
PatchDirection direction
 Direction of this contact patch. More...
 
Scalar penetration_depth
 Penetration depth of the contact patch. This value corresponds to the signed distance d between the shapes. More...
 

Static Public Attributes

static constexpr size_t default_preallocated_size = 12
 Default maximum size of the polygon representing the contact patch. Used to pre-allocate memory for the patch. More...
 

Protected Attributes

Polygon m_points
 Container for the vertices of the set. More...
 

Detailed Description

This structure allows to encode contact patches. A contact patch is defined by a set of points belonging to a subset of a plane passing by p and supported by n, where n = Contact::normal and p = Contact::pos. If we denote by P this plane and by S1 and S2 the first and second shape of a collision pair, a contact patch is represented as a polytope which vertices all belong to P & S1 & S2, where & denotes the set-intersection. Since a contact patch is a subset of a plane supported by n, it has a preferred direction. In Coal, the Contact::normal points from S1 to S2. In the same way, a contact patch points by default from S1 to S2.

Note
For now (April 2024), a ContactPatch is a polygon (2D polytope), so the points of the set, forming the convex-hull of the polytope, are stored in a counter-clockwise fashion.
If needed, the internal algorithms of Coal can easily be extended to compute a contact volume instead of a contact patch.

Member Typedef Documentation

◆ Polygon

using coal::ContactPatch::Polygon = std::vector<Vec2s>

Member Enumeration Documentation

◆ PatchDirection

Direction of ContactPatch. When doing collision detection, the convention of Coal is that the normal always points from the first to the second shape of the collision pair i.e. from shape1 to shape2 when calling collide(shape1, shape2). The PatchDirection enum allows to identify if the patch points from shape 1 to shape 2 (Default type) or from shape 2 to shape 1 (Inverted type). The Inverted type should only be used for internal Coal computations (it allows to properly define two separate contact patches in the same frame).

Enumerator
DEFAULT 
INVERTED 

Constructor & Destructor Documentation

◆ ContactPatch()

coal::ContactPatch::ContactPatch ( size_t  preallocated_size = default_preallocated_size)
inlineexplicit

Default constructor. Note: the preallocated size does not determine the maximum number of points in the patch, it only serves as preallocation if the maximum size of the patch is known in advance. Coal will automatically expand/shrink the contact patch if needed.

Member Function Documentation

◆ addPoint()

void coal::ContactPatch::addPoint ( const Vec3s point_3d)
inline

Add a 3D point to the set, expressed in the world frame.

Note
This function takes a 3D point and expresses it in the local frame of the set. It then takes only the x and y components of the vector, effectively doing a projection onto the plane to which the set belongs. TODO(louis): if necessary, we can store the offset to the plane (x, y).

◆ clear()

void coal::ContactPatch::clear ( )
inline

Clear the set.

◆ getNormal()

Vec3s coal::ContactPatch::getNormal ( ) const
inline

Normal of the contact patch, expressed in the WORLD frame.

◆ getPoint()

Vec3s coal::ContactPatch::getPoint ( const size_t  i) const
inline

Get the i-th point of the set, expressed in the 3D world frame.

◆ getPointShape1()

Vec3s coal::ContactPatch::getPointShape1 ( const size_t  i) const
inline

Get the i-th point of the contact patch, projected back onto the first shape of the collision pair. This point is expressed in the 3D world frame.

◆ getPointShape2()

Vec3s coal::ContactPatch::getPointShape2 ( const size_t  i) const
inline

Get the i-th point of the contact patch, projected back onto the first shape of the collision pair. This 3D point is expressed in the world frame.

◆ isSame()

bool coal::ContactPatch::isSame ( const ContactPatch other,
const Scalar  tol = Eigen::NumTraits<Scalar>::dummy_precision() 
) const
inline

Whether two contact patches are the same or not. Checks for different order of the points.

◆ operator==()

bool coal::ContactPatch::operator== ( const ContactPatch other) const
inline

Whether two contact patches are the same or not.

Note
This compares the two sets terms by terms. However, two contact patches can be identical, but have a different order for their points. Use isEqual in this case.

◆ point() [1/2]

Vec2s& coal::ContactPatch::point ( const size_t  i)
inline

Getter for the i-th 2D point in the set.

◆ point() [2/2]

const Vec2s& coal::ContactPatch::point ( const size_t  i) const
inline

Const getter for the i-th 2D point in the set.

◆ points() [1/2]

Polygon& coal::ContactPatch::points ( )
inline

Getter for the 2D points in the set.

◆ points() [2/2]

const Polygon& coal::ContactPatch::points ( ) const
inline

Const getter for the 2D points in the set.

◆ size()

size_t coal::ContactPatch::size ( ) const
inline

Returns the number of points in the contact patch.

Member Data Documentation

◆ default_preallocated_size

constexpr size_t coal::ContactPatch::default_preallocated_size = 12
staticconstexpr

Default maximum size of the polygon representing the contact patch. Used to pre-allocate memory for the patch.

◆ direction

PatchDirection coal::ContactPatch::direction

Direction of this contact patch.

◆ m_points

Polygon coal::ContactPatch::m_points
protected

Container for the vertices of the set.

◆ penetration_depth

Scalar coal::ContactPatch::penetration_depth

Penetration depth of the contact patch. This value corresponds to the signed distance d between the shapes.

Note
For each contact point p in the patch of normal n, p1 = p - 0.5*d*n and p2 = p + 0.5*d*n define a pair of witness points. p1 belongs to the surface of the first shape and p2 belongs to the surface of the second shape. For any pair of witness points, we always have p2 - p1 = d * n. The vector d * n is called a minimum separation vector: if S1 is translated by it, S1 and S2 are not in collision anymore.
Although there may exist multiple minimum separation vectors between two shapes, the term "minimum" comes from the fact that it's impossible to find a different separation vector which has a smaller norm than d * n.

◆ tf

Transform3s coal::ContactPatch::tf

Frame of the set, expressed in the world coordinates. The z-axis of the frame's rotation is the contact patch normal.


The documentation for this struct was generated from the following file: