Drake
GeometryInstance Class Reference

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

#include <drake/geometry/geometry_instance.h>

Public Member Functions

 GeometryInstance (const Isometry3< double > &X_PG, std::unique_ptr< Shape > shape, const std::string &name)
 Constructor with default visual material (see VisualMaterial default constructor for details on what that color is). More...
 
 GeometryInstance (const Isometry3< double > &X_PG, std::unique_ptr< Shape > shape, const std::string &name, const VisualMaterial &vis_material)
 Constructor. More...
 
GeometryId id () const
 Returns the globally unique id for this geometry specification. More...
 
const Isometry3< double > & pose () const
 
void set_pose (const Isometry3< double > &X_PG)
 
const Shapeshape () const
 
std::unique_ptr< Shaperelease_shape ()
 Releases the shape from the instance. More...
 
const VisualMaterialvisual_material () const
 
const std::string & name () const
 Returns the canonicalized name for the instance. More...
 
Implements CopyConstructible, CopyAssignable, MoveConstructible, MoveAssignable
 GeometryInstance (const GeometryInstance &)=default
 
GeometryInstanceoperator= (const GeometryInstance &)=default
 
 GeometryInstance (GeometryInstance &&)=default
 
GeometryInstanceoperator= (GeometryInstance &&)=default
 

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 a visual geometry. This requirement is not currently enforced but will be enforced in the future.

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:

1 ...
2 <visual name=" visual">
3  <geometry>
4  <sphere>
5  <radius>1.0</radius>
6  </sphere>
7  </geometry>
8 </visual>
9 ...

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.

Constructor & Destructor Documentation

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

Constructor with default visual material (see VisualMaterial default constructor for details on what that color is).

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::logic_errorif the canonicalized version of name is empty.
GeometryInstance ( const Isometry3< double > &  X_PG,
std::unique_ptr< Shape shape,
const std::string &  name,
const VisualMaterial vis_material 
)

Constructor.

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).
vis_materialThe visual material to apply to this geometry.
Exceptions
std::logic_errorif the canonicalized version of name is empty.

Member Function Documentation

GeometryId id ( ) const
inline

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.

const std::string& name ( ) const
inline

Returns the canonicalized name for the instance.

GeometryInstance& operator= ( GeometryInstance &&  )
default
GeometryInstance& operator= ( const GeometryInstance )
default
const Isometry3<double>& pose ( ) const
inline
std::unique_ptr<Shape> release_shape ( )
inline

Releases the shape from the instance.

void set_pose ( const Isometry3< double > &  X_PG)
inline
const Shape& shape ( ) const
inline
const VisualMaterial& visual_material ( ) const
inline

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