Struct ContactPatch

Struct Documentation

struct ContactPatch

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.

Note

If needed, the internal algorithms of Coal can easily be extended to compute a contact volume instead of a contact patch.

Public Types

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

Values:

enumerator DEFAULT
enumerator INVERTED
using Polygon = std::vector<Vec2s>

Public Functions

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

inline Vec3s getNormal() const

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

inline size_t size() const

Returns the number of points in the contact patch.

inline void addPoint(const Vec3s &point_3d)

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

inline Vec3s getPoint(const size_t i) const

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

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

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

inline Polygon &points()

Getter for the 2D points in the set.

inline const Polygon &points() const

Const getter for the 2D points in the set.

inline Vec2s &point(const size_t i)

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

inline const Vec2s &point(const size_t i) const

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

inline void clear()

Clear the set.

inline bool operator==(const ContactPatch &other) const

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.

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

Public Members

Transform3s tf

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

PatchDirection direction

Direction of this contact patch.

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

Note

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.

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

Protected Attributes

Polygon m_points

Container for the vertices of the set.