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, const Shape &shape, const std::string &name)
	Constructs a geometry instance specification. More...

	GeometryInstance (const math::RigidTransform< double > &X_PG, std::unique_ptr< Shape > shape, const std::string &name)
	(Advanced) Overload that transfers ownership of `shape` (for performance). 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 Shape &	shape () const
	Returns the underlying shape specification for this geometry instance. More...

std::unique_ptr< Shape >	release_shape ()
	(Advanced) Transfers ownership of this geometry instance's underlying shape specification to the caller. 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...

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

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

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

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

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

const PerceptionProperties *	perception_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

GeometryInstance &	operator= (const GeometryInstance &)=default

	GeometryInstance (GeometryInstance &&)=default

GeometryInstance &	operator= (GeometryInstance &&)=default

Constructor & Destructor Documentation

◆ GeometryInstance() [1/4]

GeometryInstance ( const GeometryInstance & )

default

◆ GeometryInstance() [2/4]

GeometryInstance ( GeometryInstance && )

default

◆ GeometryInstance() [3/4]

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

Constructs a geometry instance specification.

Parameters

X_PG	The pose of this geometry (`G`) in its parent's frame (`P`).
shape	The underlying shape for this geometry instance.
name	The name of the geometry (must satisfy the name requirements).

Exceptions

std::exception if the canonicalized version of name is empty.

◆ GeometryInstance() [4/4]

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

(Advanced) Overload that transfers ownership of shape (for performance).

Precondition: shape is non-null.

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

(Advanced) Transfers ownership of this geometry instance's underlying shape specification to the caller.

Precondition: release_shape() has not been called nor has this been moved-from.

◆ 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

Returns the underlying shape specification for this geometry instance.

Precondition: release_shape() has not been called nor has this been moved-from.

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

drake/geometry/geometry_instance.h

Detailed Description

Canonicalized names

Public Member Functions

Constructor & Destructor Documentation

◆ GeometryInstance() [1/4]

◆ GeometryInstance() [2/4]

◆ GeometryInstance() [3/4]

◆ GeometryInstance() [4/4]

Member Function Documentation

◆ id()

◆ illustration_properties()

◆ mutable_illustration_properties()

◆ mutable_perception_properties()

◆ mutable_proximity_properties()

◆ name()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ perception_properties()

◆ pose()

◆ proximity_properties()

◆ release_shape()

◆ set_illustration_properties()

◆ set_name()

◆ set_perception_properties()

◆ set_pose()

◆ set_proximity_properties()

◆ shape()