Drake
ContactSurface< T > Class Template Reference

Detailed Description

template<typename T>
class drake::geometry::ContactSurface< T >

The ContactSurface characterizes the intersection of two geometries M and N as a contact surface with a scalar field and a vector field, whose purpose is to support the hydroelastic pressure field contact model as described in:

R. Elandt, E. Drumwright, M. Sherman, and Andy Ruina. A pressure
field model for fast, robust approximation of net contact force
and moment between nominally rigid objects. IROS 2019: 8238-8245.

Mathematical Concepts

In this section, we give motivation for the concept of contact surface from the hydroelastic pressure field contact model. Here the mathematical discussion is coordinate-free (treatment of the topic without reference to any particular coordinate system); however, our implementation heavily relies on coordinate frames. We borrow terminology from differential geometry.

In this section, the mathematical term compact set (a subset of Euclidean space that is closed and bounded) corresponds to the term geometry (or the space occupied by the geometry) in SceneGraph.

We describe the contact surface ๐•Šโ‚˜โ‚™ between two intersecting compact subsets ๐•„ and โ„• of โ„ยณ with the scalar fields eโ‚˜ and eโ‚™ defined on ๐•„ โŠ‚ โ„ยณ and โ„• โŠ‚ โ„ยณ respectively:

           eโ‚˜ : ๐•„ โ†’ โ„,
           eโ‚™ : โ„• โ†’ โ„.

The contact surface ๐•Šโ‚˜โ‚™ is the surface of equilibrium eโ‚˜ = eโ‚™. It is the locus of points Q where eโ‚˜(Q) equals eโ‚™(Q):

         ๐•Šโ‚˜โ‚™ = { Q โˆˆ ๐•„ โˆฉ โ„• : eโ‚˜(Q) = eโ‚™(Q) }.

We can define the scalar field eโ‚˜โ‚™ on the surface ๐•Šโ‚˜โ‚™ as a scalar function that assigns Q โˆˆ ๐•Šโ‚˜โ‚™ the value of eโ‚˜(Q), which is the same as eโ‚™(Q):

         eโ‚˜โ‚™ : ๐•Šโ‚˜โ‚™ โ†’ โ„,
         eโ‚˜โ‚™(Q) = eโ‚˜(Q) = eโ‚™(Q).

We can also define the scalar field hโ‚˜โ‚™ on ๐•„ โˆฉ โ„• as the difference between eโ‚˜ and eโ‚™:

         hโ‚˜โ‚™ : ๐•„ โˆฉ โ„• โ†’ โ„,
         hโ‚˜โ‚™(Q) = eโ‚˜(Q) - eโ‚™(Q).

It follows that the gradient vector field โˆ‡hโ‚˜โ‚™ on ๐•„ โˆฉ โ„• equals the difference between the gradient vector fields โˆ‡eโ‚˜ and โˆ‡eโ‚™:

         โˆ‡hโ‚˜โ‚™ : ๐•„ โˆฉ โ„• โ†’ โ„ยณ,
         โˆ‡hโ‚˜โ‚™(Q) = โˆ‡eโ‚˜(Q) - โˆ‡eโ‚™(Q).

By construction, Q โˆˆ ๐•Šโ‚˜โ‚™ if and only if hโ‚˜โ‚™(Q) = 0. In other words, ๐•Šโ‚˜โ‚™ is the zero level set of hโ‚˜โ‚™. It follows that, for Q โˆˆ ๐•Šโ‚˜โ‚™, โˆ‡hโ‚˜โ‚™(Q) is orthogonal to the surface ๐•Šโ‚˜โ‚™ at Q in the direction of increasing eโ‚˜ - eโ‚™.

Notice that the domain of eโ‚˜โ‚™ is the two-dimensional surface ๐•Šโ‚˜โ‚™, while the domain of โˆ‡hโ‚˜โ‚™ is the three-dimensional compact set ๐•„ โˆฉ โ„•. Even though eโ‚˜โ‚™ and โˆ‡hโ‚˜โ‚™ are defined on different domains (๐•Šโ‚˜โ‚™ and ๐•„ โˆฉ โ„•), our implementation only represents them on their common domain, i.e., ๐•Šโ‚˜โ‚™.

Discrete Representation

In practice, the contact surface is approximated with a discrete triangle mesh. The triangle mesh's normals are defined per face. The normal of each face is guaranteed to point "out of" N and "into" M. They can be accessed via mesh_W().face_normal(face_index).

The pressure values on the contact surface are represented as a continuous, piecewise-linear function, accessed via e_MN().

The normals of the mesh are discontinuous at triangle boundaries, but the pressure can be meaningfully evaluated over the entire domain of the mesh.

When available, the values of โˆ‡eโ‚˜ and โˆ‡eโ‚™ are represented as a discontinuous, piecewise-constant function over the triangles – one vector per triangle. These quantities are accessed via EvaluateGradE_M_W() and EvaluateGradE_N_W(), respectively.

Barycentric Coordinates

For Point Q on the surface mesh of the contact surface between Geometry M and Geometry N, r_WQ = (x,y,z) is the displacement vector from the origin of the world frame to Q expressed in the coordinate frame of W. We also have the barycentric coordinates (b0, b1, b2) on a triangle of the surface mesh that contains Q. With vertices of the triangle labeled as vโ‚€, vโ‚, vโ‚‚, we can map (b0, b1, b2) to r_WQ by:

         r_WQ = b0 * r_Wvโ‚€ + b1 * r_Wvโ‚ + b2 * r_Wvโ‚‚,
         b0 + b1 + b2 = 1, bแตข โˆˆ [0,1],

where r_Wvแตข is the displacement vector of the vertex labeled as vแตข from the origin of the world frame, expressed in the world frame.

We use the barycentric coordinates to evaluate the field values.

Template Parameters
TThe scalar type, which must be one of the default nonsymbolic scalars.

#include <drake/geometry/query_results/contact_surface.h>

Public Member Functions

 ContactSurface (const ContactSurface &surface)
 
ContactSurfaceoperator= (const ContactSurface &surface)
 
 ContactSurface (ContactSurface &&)=default
 
ContactSurfaceoperator= (ContactSurface &&)=default
 
 ContactSurface (GeometryId id_M, GeometryId id_N, std::unique_ptr< SurfaceMesh< T >> mesh_W, std::unique_ptr< SurfaceMeshFieldLinear< T, T >> e_MN)
 Constructs a ContactSurface. More...
 
 ContactSurface (GeometryId id_M, GeometryId id_N, std::unique_ptr< SurfaceMesh< T >> mesh_W, std::unique_ptr< SurfaceMeshFieldLinear< T, T >> e_MN, std::unique_ptr< std::vector< Vector3< T >>> grad_eM_W, std::unique_ptr< std::vector< Vector3< T >>> grad_eN_W)
 Constructs a ContactSurface with the optional gradients of the constituent scalar fields. More...
 
GeometryId id_M () const
 Returns the geometry id of Geometry M. More...
 
GeometryId id_N () const
 Returns the geometry id of Geometry N. More...
 
const SurfaceMesh< T > & mesh_W () const
 Returns a reference to the surface mesh whose vertex positions are measured and expressed in the world frame. More...
 
const SurfaceMeshFieldLinear< T, T > & e_MN () const
 Returns a reference to the scalar field eโ‚˜โ‚™. More...
 
bool Equal (const ContactSurface< T > &surface) const
 Checks to see whether the given ContactSurface object is equal via deep exact comparison. More...
 
Evaluation of constituent pressure fields

The ContactSurface provisionally includes the gradients of the constituent pressure fields (โˆ‡eโ‚˜ and โˆ‡eโ‚™) sampled on the contact surface.

In order for these values to be included in an instance, the gradient for the corresponding mesh must be well defined. For example a rigid mesh will not have a well-defined pressure gradient; as stiffness goes to infinity, the geometry becomes rigid and the gradient direction converges to the direction of the rigid mesh's surface normals, but the magnitude goes to infinity, producing a pressure gradient that would be some variant of <โˆž, โˆž, โˆž>.

Accessing the gradient values must be pre-conditioned on a test that the particular instance of ContactSurface actually contains the gradient data. The presence of gradient data for each geometry must be confirmed separately.

The values โˆ‡eโ‚˜ and โˆ‡eโ‚˜ are piecewise constant over the ContactSurface and can only be evaluate on a per-triangle basis.

bool HasGradE_M () const
 
bool HasGradE_N () const
 
const Vector3< T > & EvaluateGradE_M_W (SurfaceFaceIndex index) const
 Returns the value of โˆ‡eโ‚˜ for the triangle with index index. More...
 
const Vector3< T > & EvaluateGradE_N_W (SurfaceFaceIndex index) const
 Returns the value of โˆ‡eโ‚™ for the triangle with index index. More...
 

Friends

template<typename U >
class ContactSurfaceTester
 

Constructor & Destructor Documentation

◆ ContactSurface() [1/4]

ContactSurface ( const ContactSurface< T > &  surface)

◆ ContactSurface() [2/4]

ContactSurface ( ContactSurface< T > &&  )
default

◆ ContactSurface() [3/4]

ContactSurface ( GeometryId  id_M,
GeometryId  id_N,
std::unique_ptr< SurfaceMesh< T >>  mesh_W,
std::unique_ptr< SurfaceMeshFieldLinear< T, T >>  e_MN 
)

Constructs a ContactSurface.

Parameters
id_MThe id of the first geometry M.
id_NThe id of the second geometry N.
mesh_WThe surface mesh of the contact surface ๐•Šโ‚˜โ‚™ between M and N. The mesh vertices are defined in the world frame.
e_MNRepresents the scalar field eโ‚˜โ‚™ on the surface mesh.
Precondition
The face normals in mesh_W point out of geometry N and into M.
Note
If id_M > id_N, the labels will be swapped and the normals of the mesh reversed (to maintain the documented invariants). Comparing the input parameters with the members of the resulting ContactSurface will reveal if such a swap has occurred.

◆ ContactSurface() [4/4]

ContactSurface ( GeometryId  id_M,
GeometryId  id_N,
std::unique_ptr< SurfaceMesh< T >>  mesh_W,
std::unique_ptr< SurfaceMeshFieldLinear< T, T >>  e_MN,
std::unique_ptr< std::vector< Vector3< T >>>  grad_eM_W,
std::unique_ptr< std::vector< Vector3< T >>>  grad_eN_W 
)

Constructs a ContactSurface with the optional gradients of the constituent scalar fields.

Parameters
id_MThe id of the first geometry M.
id_NThe id of the second geometry N.
mesh_WThe surface mesh of the contact surface ๐•Šโ‚˜โ‚™ between M and N. The mesh vertices are defined in the world frame.
e_MNRepresents the scalar field eโ‚˜โ‚™ on the surface mesh.
grad_eM_Wโˆ‡eโ‚˜ sampled once per face, expressed in the world frame.
grad_eN_Wโˆ‡eโ‚™ sampled once per face, expressed in the world frame.
Precondition
The face normals in mesh_W point out of geometry N and into M.
If given, grad_eM_W and grad_eN_W must have as many entries as mesh_W has faces and the ith entry in each should correspond to the ith face in mesh_W.
Note
If id_M > id_N, the labels will be swapped and the normals of the mesh reversed (to maintain the documented invariants). Comparing the input parameters with the members of the resulting ContactSurface will reveal if such a swap has occurred.

Member Function Documentation

◆ e_MN()

const SurfaceMeshFieldLinear<T, T>& e_MN ( ) const

Returns a reference to the scalar field eโ‚˜โ‚™.

◆ Equal()

bool Equal ( const ContactSurface< T > &  surface) const

Checks to see whether the given ContactSurface object is equal via deep exact comparison.

NaNs are treated as not equal as per the IEEE standard.

Parameters
surfaceThe contact surface for comparison.
Returns
true if the given contact surface is equal.

◆ EvaluateGradE_M_W()

const Vector3<T>& EvaluateGradE_M_W ( SurfaceFaceIndex  index) const

Returns the value of โˆ‡eโ‚˜ for the triangle with index index.

Exceptions
std::exceptionif HasGradE_M() returns false.

◆ EvaluateGradE_N_W()

const Vector3<T>& EvaluateGradE_N_W ( SurfaceFaceIndex  index) const

Returns the value of โˆ‡eโ‚™ for the triangle with index index.

Exceptions
std::exceptionif HasGradE_N() returns false.

◆ HasGradE_M()

bool HasGradE_M ( ) const
Returns
true if this contains values for โˆ‡eโ‚˜.

◆ HasGradE_N()

bool HasGradE_N ( ) const
Returns
true if this contains values for โˆ‡eโ‚™.

◆ id_M()

GeometryId id_M ( ) const

Returns the geometry id of Geometry M.

◆ id_N()

GeometryId id_N ( ) const

Returns the geometry id of Geometry N.

◆ mesh_W()

const SurfaceMesh<T>& mesh_W ( ) const

Returns a reference to the surface mesh whose vertex positions are measured and expressed in the world frame.

◆ operator=() [1/2]

ContactSurface& operator= ( const ContactSurface< T > &  surface)

◆ operator=() [2/2]

ContactSurface& operator= ( ContactSurface< T > &&  )
default

Friends And Related Function Documentation

◆ ContactSurfaceTester

friend class ContactSurfaceTester
friend

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