Drake

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: 82388245.
In this section, we give motivation for the concept of contact surface from the hydroelastic pressure field contact model. Here the mathematical discussion is coordinatefree (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 twodimensional surface ๐โโ, while the domain of โhโโ is the threedimensional compact set ๐ โฉ โ. Even though eโโ and โhโโ are defined on different domains (๐โโ and ๐ โฉ โ), our implementation only represents them on their common domain, i.e., ๐โโ.
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, piecewiselinear 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, piecewiseconstant function over the triangles – one vector per triangle. These quantities are accessed via EvaluateGradE_M_W() and EvaluateGradE_N_W(), respectively.
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.
T  The 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)  
ContactSurface &  operator= (const ContactSurface &surface) 
ContactSurface (ContactSurface &&)=default  
ContactSurface &  operator= (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 welldefined 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 preconditioned 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 pertriangle 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 
ContactSurface  (  const ContactSurface< T > &  surface  ) 

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.
id_M  The id of the first geometry M. 
id_N  The id of the second geometry N. 
mesh_W  The surface mesh of the contact surface ๐โโ between M and N. The mesh vertices are defined in the world frame. 
e_MN  Represents the scalar field eโโ on the surface mesh. 
mesh_W
point out of geometry N and into M. 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  (  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.
id_M  The id of the first geometry M. 
id_N  The id of the second geometry N. 
mesh_W  The surface mesh of the contact surface ๐โโ between M and N. The mesh vertices are defined in the world frame. 
e_MN  Represents 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. 
mesh_W
point out of geometry N and into M. 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
. 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. const SurfaceMeshFieldLinear<T, T>& e_MN  (  )  const 
Returns a reference to the scalar field eโโ.
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.
surface  The contact surface for comparison. 
true
if the given contact surface is equal. const Vector3<T>& EvaluateGradE_M_W  (  SurfaceFaceIndex  index  )  const 
Returns the value of โeโ for the triangle with index index
.
std::exception  if HasGradE_M() returns false. 
const Vector3<T>& EvaluateGradE_N_W  (  SurfaceFaceIndex  index  )  const 
Returns the value of โeโ for the triangle with index index
.
std::exception  if HasGradE_N() returns false. 
bool HasGradE_M  (  )  const 
true
if this
contains values for โeโ. bool HasGradE_N  (  )  const 
true
if this
contains values for โeโ. GeometryId id_M  (  )  const 
Returns the geometry id of Geometry M.
GeometryId id_N  (  )  const 
Returns the geometry id of Geometry N.
const SurfaceMesh<T>& mesh_W  (  )  const 
Returns a reference to the surface mesh whose vertex positions are measured and expressed in the world frame.
ContactSurface& operator=  (  const ContactSurface< T > &  surface  ) 

default 

friend 