Drake
GeometryInstance Class Reference

Detailed Description

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.

The parent frame can be a registered frame or another registered geometry.

Every GeometryInstance must be named. The naming convention mirrors that of valid names in SDF files. Specifically, any user-specified name will have all leading and trailing space and tab characters trimmed off. The trimmed name will have to satisfy the following requirements:

  • cannot be empty, and
  • the name should be unique in the scope of its frame and role. For example, two GeometryInstances can both be called "ball" as long as they are affixed to different frames or if one is a collision geometry and the other is an illustration geometry. This is enforced when a role is assigned to the geometry.

If valid, the trimmed name will be assigned to the instance.

Names can have internal whitespace (e.g., "my geometry name").

Canonicalized names

The silent transformation of a user-defined name to canonical name mirrors that of specifying geometry names in an SDF file. Consider the following SDF snippet:

...
<visual name=" visual">
<geometry>
<sphere>
<radius>1.0</radius>
</sphere>
</geometry>
</visual>
...

The name has two leading whitespace characters. The parsing process will consider this name as equivalent to "visual" and tests for uniqueness and non-emptiness will be applied to that trimmed result. The following code has an analogous effect:

scene_graph->RegisterGeometry(
source_id, frame_id,
make_unique<GeometryInstance>(pose, make_unique<Sphere>(1.0), " visual"));

The specified name includes leading whitespace. That name will be trimmed and the result will be stored in the GeometryInstance (to be later validated by SceneGraph as part of geometry registration). Querying the instance of its name will return this canonicalized name.

#include <drake/geometry/geometry_instance.h>

Public Member Functions

 GeometryInstance (const math::RigidTransform< double > &X_PG, std::unique_ptr< Shape > shape, const std::string &name)
 Constructs a geometry instance specification. More...
 
GeometryId id () const
 Returns the globally unique id for this geometry specification. More...
 
const math::RigidTransformd & pose () const
 Returns the instance geometry's pose in its parent frame. More...
 
void set_pose (const math::RigidTransformd &X_PG)
 Sets the pose of this instance in its parent's frame. More...
 
const Shapeshape () const
 
std::unique_ptr< Shaperelease_shape ()
 Releases the shape from the instance. More...
 
const std::string & name () const
 Returns the canonicalized name for the instance. More...
 
void set_name (const std::string &name)
 Sets the canonicalized name for the instance. More...
 
void set_proximity_properties (ProximityProperties properties)
 Sets the proximity properties for the given instance. More...
 
void set_illustration_properties (IllustrationProperties properties)
 Sets the illustration properties for the given instance. More...
 
void set_perception_properties (PerceptionProperties properties)
 Sets the perception properties for the given instance. More...
 
ProximityPropertiesmutable_proximity_properties ()
 Returns a pointer to the geometry's mutable proximity properties (if they are defined). More...
 
const ProximityPropertiesproximity_properties () const
 Returns a pointer to the geometry's const proximity properties (if they are defined). More...
 
IllustrationPropertiesmutable_illustration_properties ()
 Returns a pointer to the geometry's mutable illustration properties (if they are defined). More...
 
const IllustrationPropertiesillustration_properties () const
 Returns a pointer to the geometry's const illustration properties (if they are defined). More...
 
PerceptionPropertiesmutable_perception_properties ()
 Returns a pointer to the geometry's mutable perception properties (if they are defined). More...
 
const PerceptionPropertiesperception_properties () const
 Returns a pointer to the geometry's const perception properties (if they are defined). More...
 
Implements CopyConstructible, CopyAssignable, MoveConstructible, MoveAssignable
 GeometryInstance (const GeometryInstance &)=default
 
GeometryInstanceoperator= (const GeometryInstance &)=default
 
 GeometryInstance (GeometryInstance &&)=default
 
GeometryInstanceoperator= (GeometryInstance &&)=default
 

Constructor & Destructor Documentation

◆ GeometryInstance() [1/3]

GeometryInstance ( const GeometryInstance )
default

◆ GeometryInstance() [2/3]

◆ GeometryInstance() [3/3]

GeometryInstance ( const math::RigidTransform< double > &  X_PG,
std::unique_ptr< Shape shape,
const std::string &  name 
)

Constructs a geometry instance specification.

Parameters
X_PGThe pose of this geometry (G) in its parent's frame (P).
shapeThe underlying shape for this geometry instance.
nameThe name of the geometry (must satisfy the name requirements).
Exceptions
std::exceptionif the canonicalized version of name is empty.

Member Function Documentation

◆ id()

GeometryId id ( ) const

Returns the globally unique id for this geometry specification.

Every instantiation of GeometryInstance will contain a unique id value. The id value is preserved across copies. After successfully registering this GeometryInstance, this id will serve as the identifier for the registered representation as well.

◆ illustration_properties()

const IllustrationProperties* illustration_properties ( ) const

Returns a pointer to the geometry's const illustration properties (if they are defined).

Nullptr otherwise.

◆ mutable_illustration_properties()

IllustrationProperties* mutable_illustration_properties ( )

Returns a pointer to the geometry's mutable illustration properties (if they are defined).

Nullptr otherwise.

◆ mutable_perception_properties()

PerceptionProperties* mutable_perception_properties ( )

Returns a pointer to the geometry's mutable perception properties (if they are defined).

Nullptr otherwise.

◆ mutable_proximity_properties()

ProximityProperties* mutable_proximity_properties ( )

Returns a pointer to the geometry's mutable proximity properties (if they are defined).

Nullptr otherwise.

◆ name()

const std::string& name ( ) const

Returns the canonicalized name for the instance.

See also
Canonicalized names

◆ operator=() [1/2]

GeometryInstance& operator= ( GeometryInstance &&  )
default

◆ operator=() [2/2]

GeometryInstance& operator= ( const GeometryInstance )
default

◆ perception_properties()

const PerceptionProperties* perception_properties ( ) const

Returns a pointer to the geometry's const perception properties (if they are defined).

Nullptr otherwise.

◆ pose()

const math::RigidTransformd& pose ( ) const

Returns the instance geometry's pose in its parent frame.

◆ proximity_properties()

const ProximityProperties* proximity_properties ( ) const

Returns a pointer to the geometry's const proximity properties (if they are defined).

Nullptr otherwise.

◆ release_shape()

std::unique_ptr<Shape> release_shape ( )

Releases the shape from the instance.

◆ set_illustration_properties()

void set_illustration_properties ( IllustrationProperties  properties)

Sets the illustration properties for the given instance.

◆ set_name()

void set_name ( const std::string &  name)

Sets the canonicalized name for the instance.

See also
Canonicalized names

◆ set_perception_properties()

void set_perception_properties ( PerceptionProperties  properties)

Sets the perception properties for the given instance.

◆ set_pose()

void set_pose ( const math::RigidTransformd &  X_PG)

Sets the pose of this instance in its parent's frame.

◆ set_proximity_properties()

void set_proximity_properties ( ProximityProperties  properties)

Sets the proximity properties for the given instance.

◆ shape()

const Shape& shape ( ) const

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