Drake
Drake C++ Documentation
drake::geometry Namespace Reference

Namespaces

 optimization
 
 proximity
 
 render
 
 render_gltf_client
 

Classes

class  Box
 Definition of a box. More...
 
class  Capsule
 Definition of a capsule. More...
 
class  CollisionFilterDeclaration
 Class for articulating changes to the configuration of SceneGraph's "collision filters"; collision filters limit the scope of various proximity queries. More...
 
class  CollisionFilterManager
 Class for configuring "collision filters"; collision filters limit the scope of various proximity queries. More...
 
class  ContactSurface
 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: More...
 
class  Convex
 Definition of a convex surface mesh. More...
 
class  Cylinder
 Definition of a cylinder. More...
 
class  DrakeVisualizer
 A system that publishes LCM messages compatible with the drake_visualizer application representing the current state of a SceneGraph instance (whose QueryObject-valued output port is connected to this system's input port). More...
 
struct  DrakeVisualizerParams
 The set of parameters for configuring DrakeVisualizer. More...
 
class  DrakeVisualizerTest
 
class  Ellipsoid
 Definition of an ellipsoid. More...
 
class  GeometryFrame
 This simple class carries the definition of a frame used in the SceneGraph. More...
 
class  GeometryId
 Type used to identify geometry instances in SceneGraph. More...
 
class  GeometryInstance
 A geometry instance combines a geometry definition (i.e., a shape of some sort), a pose (relative to a parent "frame" P), material information, and an opaque collection of metadata. More...
 
class  GeometryProperties
 The base class for defining a set of geometry properties. More...
 
class  GeometrySet
 The GeometrySet, as its name implies, is a convenience class for defining a set of geometries. More...
 
class  GeometrySetTester
 
class  GeometryState
 The context-dependent state of SceneGraph. More...
 
class  GeometryVersion
 A version numbering class that reports revisions of SceneGraph's geometric data. More...
 
class  HalfSpace
 Definition of a half space. More...
 
class  IllustrationProperties
 The set of properties for geometry used in an "illustration" role. More...
 
class  KinematicsVector
 A KinematicsVector is a container class used to report kinematics data for registered frames and geometries (keyed by unique FrameId/GeometryId values) to SceneGraph where the set of keys (FrameId/GeometryId) is usually constant and the values (kinematics data) are varying. More...
 
class  Mesh
 Definition of a general (possibly non-convex) triangular surface mesh. More...
 
class  Meshcat
 Provides an interface to Meshcat (https://github.com/rdeits/meshcat). More...
 
class  MeshcatAnimation
 An interface for recording/playback animations in Meshcat. More...
 
class  MeshcatCone
 Definition of a cone. More...
 
struct  MeshcatParams
 The set of parameters for configuring Meshcat. More...
 
class  MeshcatPointCloudVisualizer
 MeshcatPointCloudVisualizer is a systems::LeafSystem that publishes a perception::PointCloud from its input port to Meshcat. More...
 
class  MeshcatVisualizer
 A system wrapper for Meshcat that publishes the current state of a SceneGraph instance (whose QueryObject-valued output port is connected to this system's input port). More...
 
struct  MeshcatVisualizerParams
 The set of parameters for configuring MeshcatVisualizer. More...
 
class  MeshFieldLinear
 MeshFieldLinear represents a continuous piecewise-linear scalar field f defined on a (triangular or tetrahedral) mesh; the field value changes linearly within each element E (triangle or tetrahedron), and the gradient ∇f is constant within each element. More...
 
struct  PenetrationAsPointPair
 A characterization of the intersection of two penetrating geometries. More...
 
class  PerceptionProperties
 The set of properties for geometry used in a "perception" role. More...
 
class  PolygonSurfaceMesh
 PolygonSurfaceMesh represents a surface comprised of polygonal elements (three or more sides). More...
 
struct  promoted_numerical
 Given the two scalar types U and T, returns the most "promoted" type. More...
 
class  ProximityProperties
 The set of properties for geometry used in a proximity role. More...
 
class  QueryObject
 The QueryObject serves as a mechanism to perform geometry queries on the world's geometry. More...
 
struct  RenderEngineGltfClientParams
 Construction parameters for the MakeRenderEngineGltfClient() to create a client as part of the (Experimental) glTF Render Client-Server API. More...
 
struct  RenderEngineVtkParams
 Construction parameters for the RenderEngineVtk. More...
 
class  Rgba
 Defines RGBA (red, green, blue, alpha) values on the range [0, 1]. More...
 
class  SceneGraph
 SceneGraph serves as the nexus for all geometry (and geometry-based operations) in a Diagram. More...
 
class  SceneGraphInspector
 The SceneGraphInspector serves as a mechanism to query the topological structure of a SceneGraph instance. More...
 
class  Shape
 The base interface for all shape specifications. More...
 
class  ShapeName
 Class that reports the name of the type of shape being reified (e.g., Sphere, Box, etc.) More...
 
class  ShapeReifier
 The interface for converting shape descriptions to real shapes. More...
 
struct  ShapeTag
 Simple struct for instantiating the type-specific Shape functionality. More...
 
struct  SignedDistancePair
 The data for reporting the signed distance between two geometries, A and B. More...
 
struct  SignedDistanceToPoint
 The data for reporting the signed distance from a query point to a geometry. More...
 
class  Sphere
 Definition of sphere. More...
 
class  SurfacePolygon
 Representation of a polygonal face in a SurfacePolygon. More...
 
class  SurfaceTriangle
 SurfaceTriangle represents a triangular face in a TriangleSurfaceMesh. More...
 
class  TriangleSurfaceMesh
 TriangleSurfaceMesh represents a union of triangles. More...
 
class  TriangleSurfaceMeshTester
 
class  VolumeElement
 VolumeElement represents a tetrahedral element in a VolumeMesh. More...
 
class  VolumeMesh
 VolumeMesh represents a tetrahedral volume mesh. More...
 
class  VolumeMeshTester
 

Typedefs

using DrakeVisualizerd = DrakeVisualizer< double >
 A convenient alias for the DrakeVisualizer class when using the double scalar type. More...
 
using FilterId = drake::Identifier< class FilterTag >
 Type used to identify transient collision filter declarations in SceneGraph. More...
 
using SourceId = drake::Identifier< class SourceTag >
 Type used to identify geometry sources in SceneGraph. More...
 
using FrameId = drake::Identifier< class FrameTag >
 Type used to identify geometry frames in SceneGraph. More...
 
template<typename T >
using FramePoseVector = KinematicsVector< FrameId, math::RigidTransform< T > >
 Class for communicating pose information to SceneGraph for registered frames. More...
 
template<typename T >
using GeometryConfigurationVector = KinematicsVector< GeometryId, VectorX< T > >
 Class for communicating configuration information to SceneGraph for registered deformable geometries. More...
 
using MeshcatPointCloudVisualizerd = MeshcatPointCloudVisualizer< double >
 A convenient alias for the MeshcatPointCloudVisualizer class when using the double scalar type. More...
 
using MeshcatVisualizerd = MeshcatVisualizer< double >
 A convenient alias for the MeshcatVisualizer class when using the double scalar type. More...
 
template<typename T , typename U >
using promoted_numerical_t = typename promoted_numerical< T, U >::type
 
template<typename FieldValue , typename T >
using PolygonSurfaceMeshFieldLinear = MeshFieldLinear< FieldValue, PolygonSurfaceMesh< T > >
 A convenience alias for instantiating a MeshFieldLinear on a PolygonSurfaceMesh. More...
 
template<typename FieldValue , typename T >
using TriangleSurfaceMeshFieldLinear = MeshFieldLinear< FieldValue, TriangleSurfaceMesh< T > >
 A convenience alias for instantiating a MeshFieldLinear on a TriangleSurfaceMesh. More...
 
template<typename FieldValue , typename T >
using VolumeMeshFieldLinear = MeshFieldLinear< FieldValue, VolumeMesh< T > >
 A convenience alias for instantiating a MeshFieldLinear on a VolumeMesh. More...
 
Structures for maintaining the entity relationships
using FrameIdSet = std::unordered_set< FrameId >
 Collection of unique frame ids. More...
 
using GeometryIdSet = std::unordered_set< GeometryId >
 Collection of unique geometry ids. More...
 

Enumerations

enum  Role { kUnassigned = 0x0, kProximity = 0x1, kIllustration = 0x2, kPerception = 0x4 }
 General enumeration for indicating geometry role. More...
 
enum  RoleAssign { kNew, kReplace }
 The operations that can be performed on the given properties when assigning roles to geometry. More...
 
enum  HydroelasticContactRepresentation { kTriangle, kPolygon }
 Reports on how a hydroelastic contact surface is represented. More...
 

Functions

TriangleSurfaceMesh< double > ReadObjToTriangleSurfaceMesh (const std::string &filename, double scale=1.0, std::function< void(std::string_view)> on_warning={})
 Constructs a surface mesh from a Wavefront .obj file and optionally scales coordinates by the given scale factor. More...
 
TriangleSurfaceMesh< double > ReadObjToTriangleSurfaceMesh (std::istream *input_stream, double scale=1.0, std::function< void(std::string_view)> on_warning={})
 Overload of ReadObjToTriangleSurfaceMesh(const std::string&, double) with the Wavefront .obj file given in std::istream. More...
 
bool operator== (const VolumeElement &e1, const VolumeElement &e2)
 
bool operator!= (const VolumeElement &e1, const VolumeElement &e2)
 
template<class T >
TriangleSurfaceMesh< T > ConvertVolumeToSurfaceMesh (const VolumeMesh< T > &volume)
 Converts a tetrahedral volume mesh to a triangulated surface mesh of the boundary surface of the volume. More...
 
void AddContactMaterial (const std::optional< double > &dissipation, const std::optional< double > &point_stiffness, const std::optional< multibody::CoulombFriction< double >> &friction, ProximityProperties *properties)
 AddContactMaterial() adds general contact material properties to the given set of proximity properties. More...
 
void AddRigidHydroelasticProperties (double resolution_hint, ProximityProperties *properties)
 Adds properties to the given set of proximity properties sufficient to cause the associated geometry to generate a rigid hydroelastic representation. More...
 
void AddRigidHydroelasticProperties (ProximityProperties *properties)
 Overload, intended for shapes that don't get tessellated in their hydroelastic representation (e.g., HalfSpace and Mesh). More...
 
void AddCompliantHydroelasticProperties (double resolution_hint, double hydroelastic_modulus, ProximityProperties *properties)
 Adds properties to the given set of proximity properties sufficient to cause the associated geometry to generate a compliant hydroelastic representation. More...
 
void AddCompliantHydroelasticPropertiesForHalfSpace (double slab_thickness, double hydroelastic_modulus, ProximityProperties *properties)
 Compliant half spaces are handled as a special case; they do not get tessellated. More...
 
std::unique_ptr< render::RenderEngineMakeRenderEngineVtk (const RenderEngineVtkParams &params)
 Constructs a RenderEngine implementation which uses a VTK-based OpenGL renderer. More...
 
double CalcVolume (const Shape &shape)
 Calculates the volume (in meters^3) for the Shape. More...
 
std::shared_ptr< MeshcatGetTestEnvironmentMeshcat ()
 Returns a singleton Meshcat object to be used during unit tests. More...
 
Geometry role to string conversions

These are simply convenience functions for converting the Role enumeration into a human-readable string.

std::string to_string (const Role &role)
 
std::ostream & operator<< (std::ostream &out, const Role &role)
 
Convenience functions

A collection of functions to help facilitate working with properties.

IllustrationProperties MakePhongIllustrationProperties (const Vector4< double > &diffuse)
 Constructs an IllustrationProperties instance compatible with a simple "phong" material using only the given diffuse color. More...
 

Typedef Documentation

◆ DrakeVisualizerd

A convenient alias for the DrakeVisualizer class when using the double scalar type.

◆ FilterId

using FilterId = drake::Identifier<class FilterTag>

Type used to identify transient collision filter declarations in SceneGraph.

◆ FrameId

using FrameId = drake::Identifier<class FrameTag>

Type used to identify geometry frames in SceneGraph.

◆ FrameIdSet

using FrameIdSet = std::unordered_set<FrameId>

Collection of unique frame ids.

◆ FramePoseVector

Class for communicating pose information to SceneGraph for registered frames.

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

◆ GeometryConfigurationVector

Class for communicating configuration information to SceneGraph for registered deformable geometries.

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

◆ GeometryIdSet

using GeometryIdSet = std::unordered_set<GeometryId>

Collection of unique geometry ids.

◆ MeshcatPointCloudVisualizerd

A convenient alias for the MeshcatPointCloudVisualizer class when using the double scalar type.

◆ MeshcatVisualizerd

A convenient alias for the MeshcatVisualizer class when using the double scalar type.

◆ PolygonSurfaceMeshFieldLinear

A convenience alias for instantiating a MeshFieldLinear on a PolygonSurfaceMesh.

Template Parameters
FieldValueA valid Eigen scalar or vector of valid Eigen scalars for the field value.
TA valid Eigen scalar for mesh coordinates.

◆ promoted_numerical_t

using promoted_numerical_t = typename promoted_numerical<T, U>::type

◆ SourceId

using SourceId = drake::Identifier<class SourceTag>

Type used to identify geometry sources in SceneGraph.

◆ TriangleSurfaceMeshFieldLinear

A convenience alias for instantiating a MeshFieldLinear on a TriangleSurfaceMesh.

Template Parameters
FieldValueA valid Eigen scalar or vector of valid Eigen scalars for the field value.
TA valid Eigen scalar for mesh coordinates.

◆ VolumeMeshFieldLinear

A convenience alias for instantiating a MeshFieldLinear on a VolumeMesh.

Template Parameters
FieldValueA valid Eigen scalar or vector of valid Eigen scalars for the field value.
TA valid Eigen scalar for mesh coordinates.

Enumeration Type Documentation

◆ HydroelasticContactRepresentation

Reports on how a hydroelastic contact surface is represented.

See the documentation in ContactSurface for more details.

Enumerator
kTriangle 
kPolygon 

◆ Role

enum Role
strong

General enumeration for indicating geometry role.

Enumerator
kUnassigned 
kProximity 
kIllustration 
kPerception 

◆ RoleAssign

enum RoleAssign
strong

The operations that can be performed on the given properties when assigning roles to geometry.

Enumerator
kNew 

Assign the properties to a geometry that doesn't already have the role.

kReplace 

Replace the existing role properties completely.

Function Documentation

◆ AddCompliantHydroelasticProperties()

void drake::geometry::AddCompliantHydroelasticProperties ( double  resolution_hint,
double  hydroelastic_modulus,
ProximityProperties properties 
)

Adds properties to the given set of proximity properties sufficient to cause the associated geometry to generate a compliant hydroelastic representation.

The geometry's pressure field will be the function p(e) = Ee, where E is the hydroelastic modulus stored in the given properties.

Parameters
resolution_hintIf the geometry is to be tessellated, it is the parameter that guides the level of mesh refinement. It has length units (in meters) and roughly corresponds to a typical edge length in the resulting mesh. See Properties for hydroelastic contact. This will be ignored for geometry types that don't require tessellation.
hydroelastic_modulusA multiplier that maps penetration to pressure. See Properties for hydroelastic contact.
[in,out]propertiesThe properties will be added to this property set.
Exceptions
std::exceptionIf properties already has properties with the names that this function would need to add.
Precondition
0 < resolution_hint < ∞, 0 < hydroelastic_modulus, and properties is not nullptr.

◆ AddCompliantHydroelasticPropertiesForHalfSpace()

void drake::geometry::AddCompliantHydroelasticPropertiesForHalfSpace ( double  slab_thickness,
double  hydroelastic_modulus,
ProximityProperties properties 
)

Compliant half spaces are handled as a special case; they do not get tessellated.

Instead, they are treated as infinite slabs with a finite thickness. This variant is required for hydroelastic half spaces.

Parameters
slab_thicknessThe distance from the half space boundary to its rigid core (this helps define the extent field of the half space).
hydroelastic_modulusA multiplier that maps penetration to pressure. See Properties for hydroelastic contact.
[out]propertiesThe properties will be added to this property set.
Exceptions
std::exceptionIf properties already has properties with the names that this function would need to add.
Precondition
0 < slab_thickness < ∞, 0 < hydroelastic_modulus, and properties is not nullptr.

◆ AddContactMaterial()

void drake::geometry::AddContactMaterial ( const std::optional< double > &  dissipation,
const std::optional< double > &  point_stiffness,
const std::optional< multibody::CoulombFriction< double >> &  friction,
ProximityProperties properties 
)

AddContactMaterial() adds general contact material properties to the given set of proximity properties.

These are the properties required by the default point contact model. However, other contact models can opt to use these properties as well. Only the parameters that carry values will be added to the given set of properties; no default values will be provided. Downstream consumers of the contact materials can optionally provide defaults for missing properties.

Exceptions
std::exceptionif dissipation is negative, point_stiffness is not positive, of any of the contact material properties have already been defined in `properties.
Precondition
properties is not nullptr.

◆ AddRigidHydroelasticProperties() [1/2]

void drake::geometry::AddRigidHydroelasticProperties ( double  resolution_hint,
ProximityProperties properties 
)

Adds properties to the given set of proximity properties sufficient to cause the associated geometry to generate a rigid hydroelastic representation.

Parameters
resolution_hintIf the geometry is to be tessellated, it is the parameter that guides the level of mesh refinement. It has length units (in meters) and roughly corresponds to a typical edge length in the resulting mesh. See Properties for hydroelastic contact. This will be ignored for geometry types that don't require tessellation.
[in,out]propertiesThe properties will be added to this property set.
Exceptions
std::exceptionIf properties already has properties with the names that this function would need to add.
Precondition
0 < resolution_hint < ∞ and properties is not nullptr.

◆ AddRigidHydroelasticProperties() [2/2]

void drake::geometry::AddRigidHydroelasticProperties ( ProximityProperties properties)

Overload, intended for shapes that don't get tessellated in their hydroelastic representation (e.g., HalfSpace and Mesh).

See Properties for hydroelastic contact.

◆ CalcVolume()

double drake::geometry::CalcVolume ( const Shape shape)

Calculates the volume (in meters^3) for the Shape.

Exceptions
std::exceptionif the derived type hasn't overloaded this implementation (yet).

◆ ConvertVolumeToSurfaceMesh()

TriangleSurfaceMesh<T> drake::geometry::ConvertVolumeToSurfaceMesh ( const VolumeMesh< T > &  volume)

Converts a tetrahedral volume mesh to a triangulated surface mesh of the boundary surface of the volume.

Parameters
volumeThe tetrahedral volume mesh, whose vertex positions are measured and expressed in some frame E.
Returns
The triangulated surface mesh, whose vertex positions are measured and expressed in the same frame E of the volume mesh.
Precondition
The vertices of the volume mesh are unique. Adjacent tetrahedra share the same vertices, instead of repeating the vertices with the same coordinates. Otherwise, the returned surface mesh will have extra triangles in addition to the boundary triangles of the volume.
Template Parameters
TThe scalar type, which must be one of the default nonsymbolic scalars.

◆ GetTestEnvironmentMeshcat()

std::shared_ptr<Meshcat> drake::geometry::GetTestEnvironmentMeshcat ( )

Returns a singleton Meshcat object to be used during unit tests.

The same object is used for all test cases. If test code needs to reset the scene between tests, it must do so explicitly.

◆ MakePhongIllustrationProperties()

IllustrationProperties drake::geometry::MakePhongIllustrationProperties ( const Vector4< double > &  diffuse)

Constructs an IllustrationProperties instance compatible with a simple "phong" material using only the given diffuse color.

◆ MakeRenderEngineVtk()

std::unique_ptr<render::RenderEngine> drake::geometry::MakeRenderEngineVtk ( const RenderEngineVtkParams params)

Constructs a RenderEngine implementation which uses a VTK-based OpenGL renderer.

Geometry perception properties

This RenderEngine implementation looks for the following properties when registering visual geometry, categorized by rendered image type.

RGB images

Group name Property Name Required Property Type Property Description
phong diffuse no¹ Eigen::Vector4d The rgba value of the object surface.
phong diffuse_map no² std::string The path to a texture to apply to the geometry.³

¹ If no diffuse value is given, a default rgba value will be applied. The default color is a bright orange. This default value can be changed to a different value at construction.
² If no path is specified, or the file cannot be read, the diffuse rgba value is used (or its default).
³ RenderEngineVtk implements a legacy feature for associating textures with meshes. If no (phong, diffuse_map) property is provided (or it refers to a file that doesn't exist), for a mesh named /path/to/mesh.obj, RenderEngineVtk will search for a file /path/to/mesh.png (replacing "obj" with "png"). If that image exists, it will be used as a texture on the mesh object.

Note
RenderEngineVtk does not support the OBJ format usemtl directive. Instead, it has two ways to associate a color texture with an obj file:
  • File name matching; see footnote 3 above.
  • Explicit assignment of arbitrary texture files from within model files. In SDFormat, use the tag drake:diffuse_map. In URDF, use //visual/material/texture.

Depth images

No specific properties required.

Label images

Group name Property Name Required Property Type Property Description
label id configurable⁵ RenderLabel The label to render into the image.

⁵ RenderEngineVtk has a default render label value that is applied to any geometry that doesn't have a (label, id) property at registration. If a value is not explicitly specified, RenderEngineVtk uses RenderLabel::kUnspecified as this default value. It can be explicitly set upon construction. The possible values for this default label and the ramifications of that choice are documented here.

Geometries accepted by RenderEngineVtk

As documented in RenderEngine::RegisterVisual(), a RenderEngine implementation can use the properties found in the PerceptionProperties to determine whether it accepts a shape provided for registration. RenderEngineVtk makes use of defaults to accept all geometries (assuming the properties pass validation, e.g., render label validation).

◆ operator!=()

bool drake::geometry::operator!= ( const VolumeElement e1,
const VolumeElement e2 
)

◆ operator<<()

std::ostream& drake::geometry::operator<< ( std::ostream &  out,
const Role role 
)

◆ operator==()

bool drake::geometry::operator== ( const VolumeElement e1,
const VolumeElement e2 
)

◆ ReadObjToTriangleSurfaceMesh() [1/2]

TriangleSurfaceMesh<double> drake::geometry::ReadObjToTriangleSurfaceMesh ( const std::string &  filename,
double  scale = 1.0,
std::function< void(std::string_view)>  on_warning = {} 
)

Constructs a surface mesh from a Wavefront .obj file and optionally scales coordinates by the given scale factor.

Polygons will be triangulated if they are not triangles already. All objects in the .obj file will be merged into the surface mesh. See https://en.wikipedia.org/wiki/Wavefront_.obj_file for the file format.

Parameters
filenameA valid file name with absolute path or relative path.
scaleAn optional scale to coordinates.
on_warningAn optional callback that will receive warning message(s) encountered while reading the mesh. When not provided, drake::log() will be used.
Exceptions
std::exceptionif filename doesn't have a valid file path, or the file has no faces.
Returns
surface mesh

◆ ReadObjToTriangleSurfaceMesh() [2/2]

TriangleSurfaceMesh<double> drake::geometry::ReadObjToTriangleSurfaceMesh ( std::istream *  input_stream,
double  scale = 1.0,
std::function< void(std::string_view)>  on_warning = {} 
)

Overload of ReadObjToTriangleSurfaceMesh(const std::string&, double) with the Wavefront .obj file given in std::istream.

◆ to_string()

std::string drake::geometry::to_string ( const Role role)