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 <collision_data.h>

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
void	addPoint (const Vec3s &point_3d)
	Add a 3D point to the set, expressed in the world frame. More...

void	clear ()
	Clear the set. More...

	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...

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...

bool	isSame (const ContactPatch &other, const CoalScalar tol=Eigen::NumTraits< CoalScalar >::dummy_precision()) const
	Whether two contact patches are the same or not. Checks for different order of the points. More...

bool	operator== (const ContactPatch &other) const
	Whether two contact patches are the same or not. More...

Vec2s &	point (const size_t i)
	Getter for the i-th 2D point in the set. More...

const Vec2s &	point (const size_t i) const
	Const getter for the i-th 2D point in the set. More...

Polygon &	points ()
	Getter for the 2D points in the set. More...

const Polygon &	points () const
	Const getter for the 2D points in the set. More...

size_t	size () const
	Returns the number of points in the contact patch. More...

Public Attributes
PatchDirection	direction
	Direction of this contact patch. More...

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

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...

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.

Definition at line 512 of file coal/collision_data.h.

Member Typedef Documentation

◆ Polygon

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

Definition at line 514 of file coal/collision_data.h.

Member Enumeration Documentation

◆ PatchDirection

enum coal::ContactPatch::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

Definition at line 529 of file coal/collision_data.h.

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.

Definition at line 561 of file coal/collision_data.h.

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

Definition at line 584 of file coal/collision_data.h.

◆ clear()

void coal::ContactPatch::clear ( )

inline

Clear the set.

Definition at line 640 of file coal/collision_data.h.

◆ getNormal()

Vec3s coal::ContactPatch::getNormal ( ) const

inline

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

Definition at line 569 of file coal/collision_data.h.

◆ 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.

Definition at line 590 of file coal/collision_data.h.

◆ 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.

Definition at line 600 of file coal/collision_data.h.

◆ 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.

Definition at line 609 of file coal/collision_data.h.

◆ isSame()

bool coal::ContactPatch::isSame	(	const ContactPatch &	other,
		const CoalScalar	tol = `Eigen::NumTraits<CoalScalar>::dummy_precision()`
	)		const

inline

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

Definition at line 658 of file coal/collision_data.h.

◆ 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.

Definition at line 650 of file coal/collision_data.h.

◆ point() [1/2]

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

inline

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

Definition at line 622 of file coal/collision_data.h.

◆ 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.

Definition at line 631 of file coal/collision_data.h.

◆ points() [1/2]

Polygon& coal::ContactPatch::points ( )

inline

Getter for the 2D points in the set.

Definition at line 616 of file coal/collision_data.h.

◆ points() [2/2]

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

inline

Const getter for the 2D points in the set.

Definition at line 619 of file coal/collision_data.h.

◆ size()

size_t coal::ContactPatch::size ( ) const

inline

Returns the number of points in the contact patch.

Definition at line 577 of file coal/collision_data.h.

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.

Definition at line 549 of file coal/collision_data.h.

◆ direction

PatchDirection coal::ContactPatch::direction

Direction of this contact patch.

Definition at line 532 of file coal/collision_data.h.

◆ m_points

Polygon coal::ContactPatch::m_points

protected

Container for the vertices of the set.

Definition at line 553 of file coal/collision_data.h.

◆ penetration_depth

CoalScalar 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.

Definition at line 545 of file coal/collision_data.h.

◆ 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.

Definition at line 518 of file coal/collision_data.h.

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

coal/collision_data.h

Public Types

Public Member Functions

Public Attributes

Static Public Attributes

Protected Attributes

Detailed Description

Member Typedef Documentation

◆ Polygon

Member Enumeration Documentation

◆ PatchDirection

Constructor & Destructor Documentation

◆ ContactPatch()

Member Function Documentation

◆ addPoint()

◆ clear()

◆ getNormal()

◆ getPoint()

◆ getPointShape1()

◆ getPointShape2()

◆ isSame()

◆ operator==()

◆ point() [1/2]

◆ point() [2/2]

◆ points() [1/2]

◆ points() [2/2]

◆ size()

Member Data Documentation

◆ default_preallocated_size

◆ direction

◆ m_points

◆ penetration_depth

◆ tf