drake::geometry Namespace Reference

Namespaces
namespace	optimization
namespace	proximity
namespace	render
namespace	render_gltf_client
namespace	render_vtk

Classes
class	Aabb
	Axis-aligned bounding box. More...
class	AabbMaker
	AabbMaker implements the logic to fit an Aabb to a collection of points. More...
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...
struct	DefaultProximityProperties
	These properties will be used as defaults when the geometry as added via API calls or parsed from model files doesn't say anything more specific. More...
class	DrakeVisualizer
	A system that publishes LCM messages 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...
struct	EnvironmentMap
struct	EquirectangularMap
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	GeometryState
	The context-dependent state of SceneGraph. More...
class	GeometryVersion
	A version numbering class that reports revisions of SceneGraph's geometric data. More...
struct	GltfExtension
	Specifies how to deal with glTF "extensions" (non-standard capabilities). More...
class	HalfSpace
	Definition of a half space. More...
class	IllustrationProperties
	The set of properties for geometry used in an "illustration" role. More...
struct	InMemoryMesh
	Representation of a mesh file stored in memory. 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) mesh. More...
class	Meshcat
	Provides an interface to Meshcat (https://github.com/meshcat-dev/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 dynamical diagram with MultibodyPlant and SceneGraph. More...
struct	MeshcatVisualizerParams
	The set of parameters for configuring MeshcatVisualizer. More...
struct	MeshcatVisualizerSurfaceVelocityData
	Provides MeshcatVisualizer the information it needs to interpret the surface_displacements input port. 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...
class	MeshSource
	Provides a general abstraction to the definition of a mesh. More...
struct	NullTexture
	(Internal use only) A place holder indicating that no texture has been provided for environment map (and, therefore, no environment map). More...
class	Obb
class	ObbMaker
	ObbMaker performs an algorithm to create an oriented bounding box that fits a specified set of vertices in a mesh. More...
class	ObbMakerTester
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	Plane
	The definition of a plane in ℜ³, posed in an arbitrary frame. More...
class	PolygonSurfaceMesh
	PolygonSurfaceMesh represents a surface comprised of polygonal elements (three or more sides). More...
class	PolygonSurfaceMeshTest
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	RenderEngineGlParams
	Construction parameters for RenderEngineGl. More...
struct	RenderEngineGltfClientParams
	Construction parameters for the MakeRenderEngineGltfClient() to create a client as part of the 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...
struct	SceneGraphConfig
	The set of configurable properties on a SceneGraph. More...
class	SceneGraphInspector
	The SceneGraphInspector serves as a mechanism to query the topological structure of a SceneGraph instance. More...
class	Shape
	The abstract base class for all shape specifications. More...
class	ShapeReifier
	The interface for converting shape descriptions to real shapes. 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...
struct	SsaoParameter
	Screen-space ambient occlusion (SSAO) parameters. 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.
using	FilterId = drake::Identifier<class FilterTag>
	Type used to identify transient collision filter declarations in SceneGraph.
using	SourceId = drake::Identifier<class SourceTag>
	Type used to identify geometry sources in SceneGraph.
using	FrameId = drake::Identifier<class FrameTag>
	Type used to identify geometry frames in SceneGraph.
template<typename T>
using	FramePoseVector = KinematicsVector<FrameId, math::RigidTransform<T>>
	Class for communicating pose information to SceneGraph for registered frames.
template<typename T>
using	GeometryConfigurationVector = KinematicsVector<GeometryId, VectorX<T>>
	Class for communicating configuration information to SceneGraph for registered deformable geometries.
using	MeshcatPointCloudVisualizerd = MeshcatPointCloudVisualizer<double>
	A convenient alias for the MeshcatPointCloudVisualizer class when using the double scalar type.
using	MeshcatVisualizerd = MeshcatVisualizer<double>
	A convenient alias for the MeshcatVisualizer class when using the double scalar type.
template<typename T, typename U>
using	promoted_numerical_t = typename promoted_numerical<T, U>::type
template<typename FieldValue, typename T>
using	PolygonSurfaceMeshFieldLinear
	A convenience alias for instantiating a MeshFieldLinear on a PolygonSurfaceMesh.
template<typename FieldValue, typename T>
using	TriangleSurfaceMeshFieldLinear
	A convenience alias for instantiating a MeshFieldLinear on a TriangleSurfaceMesh.
template<typename FieldValue, typename T>
using	VolumeMeshFieldLinear = MeshFieldLinear<FieldValue, VolumeMesh<T>>
	A convenience alias for instantiating a MeshFieldLinear on a VolumeMesh.
Structures for maintaining the entity relationships
using	FrameIdSet = std::unordered_set<FrameId>
	Collection of unique frame ids.
using	GeometryIdSet = std::unordered_set<GeometryId>
	Collection of unique geometry ids.

Enumerations
enum class	CollisionFilterScope { kAll , kOmitDeformable }
	Enum that defines the scope of the geometries that are affected by the collision filtering mechanism. More...
enum class	Role { kUnassigned = 0x0 , kProximity = 0x1 , kIllustration = 0x2 , kPerception = 0x4 }
	General enumeration for indicating geometry role. More...
enum class	RoleAssign { kNew , kReplace }
	The operations that can be performed on the given properties when assigning roles to geometry. More...
enum class	MeshGradientMode { kNone , kOkOrMarkDegenerate , kOkOrThrow }
	Specify whether to generate gradients, and how to handle numerical failures. More...
enum class	HydroelasticContactRepresentation { kTriangle , kPolygon }
	Reports on how a hydroelastic contact surface is represented. More...

Functions
std::optional< Obb >	CalcObb (const Shape &shape)
	Calculates the oriented bounding box (OBB) for the Shape in its canonical frame.
TriangleSurfaceMesh< double >	ReadObjToTriangleSurfaceMesh (const std::filesystem::path &filename, const Eigen::Vector3d &scale3, 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.
TriangleSurfaceMesh< double >	ReadObjToTriangleSurfaceMesh (const std::filesystem::path &filename, double scale=1.0, std::function< void(std::string_view)> on_warning={})
	Variant that allows defining uniform scaling from a single scalar value.
TriangleSurfaceMesh< double >	ReadObjToTriangleSurfaceMesh (const MeshSource &mesh_source, const Eigen::Vector3d &scale3, std::function< void(std::string_view)> on_warning={})
	Overload of ReadObjToTriangleSurfaceMesh(const std::filesystem::path&, double) with the Wavefront .obj in a Mesh shape specification.
TriangleSurfaceMesh< double >	ReadObjToTriangleSurfaceMesh (const MeshSource &mesh_source, double scale=1.0, std::function< void(std::string_view)> on_warning={})
	Variant that allows defining uniform scaling from a single scalar value.
bool	operator== (const VolumeElement &e1, const VolumeElement &e2)
bool	operator!= (const VolumeElement &e1, const VolumeElement &e2)
VolumeMesh< double >	RefineVolumeMesh (const VolumeMesh< double > &mesh)
	Refines a tetrahedral mesh to eliminate problematic simplices.
std::string	RefineVolumeMeshIntoVtkFileContents (const MeshSource &mesh_source)
	Refines a tetrahedral mesh to eliminate problematic simplices.
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.
void	AddContactMaterial (std::optional< double > dissipation, 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.
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.
void	AddRigidHydroelasticProperties (ProximityProperties *properties)
	Overload, intended for shapes that don't get tessellated in their hydroelastic representation (e.g., HalfSpace and Mesh).
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.
void	AddCompliantHydroelasticPropertiesForHalfSpace (double slab_thickness, double hydroelastic_modulus, ProximityProperties *properties)
	Compliant half spaces are handled as a special case; they do not get tessellated.
InMemoryMesh	ReadGltfToMemory (const std::filesystem::path &gltf_path)
	Given a file path to a .gltf file, loads the .gltf file contents into memory.
std::unique_ptr< render::RenderEngine >	MakeRenderEngineGl (RenderEngineGlParams params={})
	Constructs a RenderEngine implementation which uses a purely OpenGL renderer.
std::unique_ptr< render::RenderEngine >	MakeRenderEngineGltfClient (const RenderEngineGltfClientParams &params)
	Constructs a RenderEngine implementation which generates glTF files to upload to a render server, and retrieves renderings from said server by copying image data back into drake systems::sensors::Image buffers.
std::unique_ptr< render::RenderEngine >	MakeRenderEngineVtk (const RenderEngineVtkParams &params)
	Constructs a RenderEngine implementation which uses a VTK-based OpenGL renderer.
double	CalcVolume (const Shape &shape)
	Calculates the volume (in meters^3) for the Shape.
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)
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.

Variables
const bool	kHasRenderEngineGl
	Reports the availability of the RenderEngineGl implementation.
const bool	kHasRenderEngineGltfClient
	Reports the availability of the RenderEngineGltfClient implementation.
const bool	kHasRenderEngineVtk
	Reports the availability of the RenderEngineVtk implementation.

Typedef Documentation

DrakeVisualizerd

using DrakeVisualizerd = DrakeVisualizer<double>

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

template<typename T>

using FramePoseVector = KinematicsVector<FrameId, math::RigidTransform<T>>

Class for communicating pose information to SceneGraph for registered frames.

Template Parameters

T	The scalar type, which must be one of the default scalars.

GeometryConfigurationVector

template<typename T>

using GeometryConfigurationVector = KinematicsVector<GeometryId, VectorX<T>>

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

Template Parameters

T	The scalar type, which must be one of the default scalars.

GeometryIdSet

using GeometryIdSet = std::unordered_set<GeometryId>

Collection of unique geometry ids.

MeshcatPointCloudVisualizerd

using MeshcatPointCloudVisualizerd = MeshcatPointCloudVisualizer<double>

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

MeshcatVisualizerd

using MeshcatVisualizerd = MeshcatVisualizer<double>

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

PolygonSurfaceMeshFieldLinear

template<typename FieldValue, typename T>

using PolygonSurfaceMeshFieldLinear

Initial value:

 
MeshFieldLinear<FieldValue, PolygonSurfaceMesh<T>>

A convenience alias for instantiating a MeshFieldLinear on a PolygonSurfaceMesh.

Template Parameters

FieldValue	A valid Eigen scalar or vector of valid Eigen scalars for the field value.
T	A valid Eigen scalar for mesh coordinates.

promoted_numerical_t

template<typename T, typename U>

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

template<typename FieldValue, typename T>

using TriangleSurfaceMeshFieldLinear

Initial value:

 
MeshFieldLinear<FieldValue, TriangleSurfaceMesh<T>>

A convenience alias for instantiating a MeshFieldLinear on a TriangleSurfaceMesh.

Template Parameters

FieldValue	A valid Eigen scalar or vector of valid Eigen scalars for the field value.
T	A valid Eigen scalar for mesh coordinates.

VolumeMeshFieldLinear

template<typename FieldValue, typename T>

using VolumeMeshFieldLinear = MeshFieldLinear<FieldValue, VolumeMesh<T>>

A convenience alias for instantiating a MeshFieldLinear on a VolumeMesh.

Template Parameters

FieldValue	A valid Eigen scalar or vector of valid Eigen scalars for the field value.
T	A valid Eigen scalar for mesh coordinates.

Enumeration Type Documentation

CollisionFilterScope

enum class CollisionFilterScope

strong

Enum that defines the scope of the geometries that are affected by the collision filtering mechanism.

Enumerator
kAll	All geometries are considered when collision filters are applied.
kOmitDeformable	Deformable geometries are omitted when applying collision filters. That means that all deformable geometries are not affected by the collision filter declaration even if they are included in the GeometrySet when the filter is declared.

HydroelasticContactRepresentation

enum class HydroelasticContactRepresentation

strong

Reports on how a hydroelastic contact surface is represented.

See the documentation in ContactSurface for more details.

Enumerator
kTriangle
kPolygon

MeshGradientMode

enum class MeshGradientMode

strong

Specify whether to generate gradients, and how to handle numerical failures.

Enumerator
kNone	Don't compute gradients at all.
kOkOrMarkDegenerate	If gradient computation fails, mark it degenerate. See MeshFieldLinear::is_gradient_field_degenerate().
kOkOrThrow	If gradient computation fails, throw an exception.

Role

enum class Role

strong

General enumeration for indicating geometry role.

Enumerator
kUnassigned
kProximity
kIllustration
kPerception

RoleAssign

enum class 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 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_hint	If 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_modulus	A multiplier that maps penetration to pressure. See Properties for hydroelastic contact.
[in,out]	properties	The properties will be added to this property set.

Exceptions

std::exception

If 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 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_thickness	The distance from the half space boundary to its rigid core (this helps define the extent field of the half space).
	hydroelastic_modulus	A multiplier that maps penetration to pressure. See Properties for hydroelastic contact.
[out]	properties	The properties will be added to this property set.

Exceptions

std::exception

If 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 AddContactMaterial	(	std::optional< double >	dissipation,
		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::exception

if 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 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_hint	If 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]	properties	The properties will be added to this property set.

Exceptions

std::exception

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

CalcObb()

std::optional< Obb > CalcObb

(

const Shape &

shape

)

Calculates the oriented bounding box (OBB) for the Shape in its canonical frame.

Returns std::nullopt if the Shape is HalfSpace which doesn't have a bounding box.

Exceptions

std::exception

if a referenced file cannot be opened.

CalcVolume()

double CalcVolume

(

const Shape &

shape

)

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

For convex and mesh geometries, the algorithm only supports ".obj" files and only produces meaningful results for "closed" shapes.

Exceptions

std::exception

if the derived type hasn't overloaded this implementation (yet), if a filetype is unsupported, or if a referenced file cannot be opened.

ConvertVolumeToSurfaceMesh()

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.

Parameters

volume

The 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

T	The scalar type, which must be one of the default nonsymbolic scalars.

MakePhongIllustrationProperties()

IllustrationProperties MakePhongIllustrationProperties

(

const Vector4< double > &

diffuse

)

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

MakeRenderEngineGl()

std::unique_ptr< render::RenderEngine > MakeRenderEngineGl

(

RenderEngineGlParams

params = {}

)

Constructs a RenderEngine implementation which uses a purely OpenGL renderer.

The engine only works under Ubuntu. If called on a Mac, it will throw.

Note

RenderEngineGl behaves a bit differently from other RenderEngine implementations (e.g., RenderEngineVtk) with respect to displayed images. RenderEngineGl can only display a single image type at a time. So, if show_window has been requested for both label and color images, the images will alternate quickly (flickering) in the shared window.

Using RenderEngineGl in multiple threads

Most importantly, a single RenderEngineGl should not be exercised in multiple threads. One thread, one RenderEngineGl instance.

A RenderEngineGl instance and its clones can be used in different threads simultaneously, but only the rendering APIs are threadsafe. Do not mutate the contents of the engine (e.g., adding/removing geometries, etc.) in parallel.

Two independently constructed RenderEngineGl instances can be freely used in different threads – all APIs are available.

The expected workflow is to add a RenderEngineGl instance a SceneGraph instance (see SceneGraph::AddRenderer()) and then to populate SceneGraph with the desired geometry. Each systems::Context allocated for that SceneGraph will receive a clone of the original RenderEngineGl. One systems::Context can be used per thread to create rendered images in parallel.

Exceptions

std::exception

if kHasRenderEngineGl is false.

MakeRenderEngineGltfClient()

std::unique_ptr< render::RenderEngine > MakeRenderEngineGltfClient

(

const RenderEngineGltfClientParams &

params

)

Constructs a RenderEngine implementation which generates glTF files to upload to a render server, and retrieves renderings from said server by copying image data back into drake systems::sensors::Image buffers.

The server url and endpoint are provided through the specified RenderEngineGltfClientParams. The returned RenderEngine implements the client side of the glTF Render Client-Server API. The rules for supported geometries and textures are the same as for the VTK-based engine and are described in MakeRenderEngineVtk().

Note

The underlying RenderEngine utilizes libcurl to communicate with a server. Static curl initialization must be performed once per process, and the operation is not thread-safe! Instantiating this RenderEngine automatically initializes curl with the default curl_global_init(CURL_GLOBAL_ALL | CURL_GLOBAL_ACK_EINTR), the implication for consuming applications being:

1. See DRAKE_ALLOW_NETWORK for an environment variable option to deny remote rendering entirely.
2. If you intend to have your rendering take place in a threaded context, you must instantiate this RenderEngine via MakeRenderEngineGltfClient from the main thread before spawning your threaded workers. As soon as one of these RenderEngine instances has been constructed, libcurl will have been initialized.

   // Setup your server information and create the RenderEngine.  This must
   // be done in a non-threaded context (e.g., at the program start).
   RenderEngineGltfClientParams params;
   params.base_url = "http://some-server.url";
   auto render_engine = MakeRenderEngineGltfClient(params);
    
   // After MakeRenderEngineGltfClient() function call, libcurl has been
   // initialized and you may now create threads if desired.

3. If you need to use a different initialization strategy for libcurl in your application, you should first create the RenderEngine using MakeRenderEngineGltfClient, then manually call curl_global_cleanup(), followed by manually calling curl_global_init(...) with your desired flags. In general, this scenario is atypical and you should not need to worry about this. Applications with specialized libcurl needs, though, must understand the construction and initialization order to be able to modify the behavior to suit their needs.

   // Follow the steps above to construct the RenderEngine given the
   // specified RenderEngineGltfClientParams.
    
   // Libcurl has been initialized at this point, so your application needs
   // to reset and re-initialize curl again.
   curl_global_cleanup();
   curl_global_init(...);  // <<< your custom flags here
    
   // Now that libcurl has been re-initialized to suit your application's
   // needs, you may now create threads if desired.

Exceptions

std::exception

if kHasRenderEngineGltfClient is false, or if disabled via the environment variable DRAKE_ALLOW_NETWORK.

MakeRenderEngineVtk()

std::unique_ptr< render::RenderEngine > MakeRenderEngineVtk

(

const RenderEngineVtkParams &

params

)

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

Warning

On macOS, we've observed that RenderEngineVtk sometimes does not obey render::ColorRenderCamera::show_window when it's set to true. Refer to issue #20144 for further discussion.

Note

On Ubuntu, render::ColorRenderCamera::show_window only shows a window when RenderEngineVtkParams::backend is set to "GLX"; the default backend value of "EGL" cannot show a window.

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. ⁴ The render engine consumes pngs with uchar channels. Pngs with a different bit depth, e.g., uint16 channels, will be converted to that.

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	no⁵	RenderLabel	The label to render into the image.

⁵ When the label property is not set, RenderEngineVtk uses a default render label of RenderLabel::kDontCare.

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

Exceptions

std::exception

if kHasRenderEngineVtk is false.

operator!=()

bool operator!=	(	const VolumeElement &	e1,
		const VolumeElement &	e2 )

operator==()

bool operator==	(	const VolumeElement &	e1,
		const VolumeElement &	e2 )

ReadGltfToMemory()

InMemoryMesh ReadGltfToMemory

(

const std::filesystem::path &

gltf_path

)

Given a file path to a .gltf file, loads the .gltf file contents into memory.

All named .bin and image files are loaded into its supporting files as path-valued FileSource instances (i.e., absolute paths for the external files are included).

Note: the path-valued supporting files are not validated with respect to their accessibility or even their existence.

ReadObjToTriangleSurfaceMesh() [1/4]

TriangleSurfaceMesh< double > ReadObjToTriangleSurfaceMesh	(	const MeshSource &	mesh_source,
		const Eigen::Vector3d &	scale3,
		std::function< void(std::string_view)>	on_warning = {} )

Overload of ReadObjToTriangleSurfaceMesh(const std::filesystem::path&, double) with the Wavefront .obj in a Mesh shape specification.

ReadObjToTriangleSurfaceMesh() [2/4]

TriangleSurfaceMesh< double > ReadObjToTriangleSurfaceMesh	(	const MeshSource &	mesh_source,
		double	scale = 1.0,
		std::function< void(std::string_view)>	on_warning = {} )

Variant that allows defining uniform scaling from a single scalar value.

ReadObjToTriangleSurfaceMesh() [3/4]

TriangleSurfaceMesh< double > ReadObjToTriangleSurfaceMesh	(	const std::filesystem::path &	filename,
		const Eigen::Vector3d &	scale3,
		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

filename	A valid file name with absolute path or relative path.
scale3	A scale to coordinates.
on_warning	An optional callback that will receive warning message(s) encountered while reading the mesh. When not provided, drake::log() will be used.

Exceptions

std::exception

if there is an error reading the mesh data.

Returns

surface mesh

ReadObjToTriangleSurfaceMesh() [4/4]

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

Variant that allows defining uniform scaling from a single scalar value.

RefineVolumeMesh()

VolumeMesh< double > RefineVolumeMesh

(

const VolumeMesh< double > &

mesh

)

Refines a tetrahedral mesh to eliminate problematic simplices.

Parameters

mesh	The mesh to refine.

Returns

The refined mesh, or a copy of the input mesh if no refinement was needed.

Exceptions

std::exception

if mesh is not a valid tetrahedral mesh.

RefineVolumeMeshIntoVtkFileContents()

std::string RefineVolumeMeshIntoVtkFileContents

(

const MeshSource &

mesh_source

)

Refines a tetrahedral mesh to eliminate problematic simplices.

Parameters

mesh_source

The mesh to refine.

Returns

A valid, ASCII VTK file defining the refined tetrahedral mesh. Represents the input mesh if no refinement was needed.

Exceptions

std::exception

if mesh_source does not reference a valid VTK-formatted tetrahedral mesh.

to_string()

std::string to_string

(

const Role &

role

)

Variable Documentation

kHasRenderEngineGl

const bool kHasRenderEngineGl

extern

Reports the availability of the RenderEngineGl implementation.

kHasRenderEngineGltfClient

const bool kHasRenderEngineGltfClient

extern

Reports the availability of the RenderEngineGltfClient implementation.

kHasRenderEngineVtk

const bool kHasRenderEngineVtk

extern

Reports the availability of the RenderEngineVtk implementation.