Drake
GeometryState< T > Class Template Reference

The context-dependent state of SceneGraph. More...

#include <drake/geometry/proximity_engine.h>

Public Types

using FrameIdRange = internal::MapKeyRange< FrameId, internal::InternalFrame >
 An object that represents the range of FrameId values in the state. More...
 

Public Member Functions

 GeometryState ()
 Default constructor. More...
 
template<class T1 = T>
std::enable_if<!std::is_same< T1, double >::value, GeometryState< T > & >::type operator= (const GeometryState< double > &other)
 Allow assignment from a GeometryState<double> to a GeometryState<T>. More...
 
Implements CopyConstructible, CopyAssignable, MoveConstructible, MoveAssignable
 GeometryState (const GeometryState &)=default
 
GeometryStateoperator= (const GeometryState &)=default
 
 GeometryState (GeometryState &&)=default
 
GeometryStateoperator= (GeometryState &&)=default
 
State introspection

Various methods that allow reading the state's properties and values.

int get_num_sources () const
 Reports the number of registered sources – whether they have frames or not. More...
 
int get_num_frames () const
 Reports the total number of frames – across all sources. More...
 
int get_num_geometries () const
 Reports the total number of geometries. More...
 
int GetNumFrameGeometries (FrameId frame_id) const
 Reports the total number of geometries directly registered to the given frame. More...
 
int GetNumDynamicGeometries () const
 Reports the total number of dynamic geometries in the scene graph. More...
 
int GetNumAnchoredGeometries () const
 Reports the total number of anchored geometries. More...
 
bool source_is_registered (SourceId source_id) const
 Reports true if the given source_id references a registered source. More...
 
const std::vector< GeometryId > & get_geometry_ids () const
 The set of all dynamic geometries registered to the world. More...
 
FrameIdRange get_frame_ids () const
 Provides a range object for all of the frame ids in the scene graph. More...
 
int get_frame_group (FrameId frame_id) const
 Reports the frame group for the given frame. More...
 
const std::string & get_frame_name (FrameId frame_id) const
 Reports the name of the frame. More...
 
const std::string & get_name (GeometryId geometry_id) const
 Reports the stored, canonical name of the geometry (see GeometryInstance for details). More...
 
GeometryId GetGeometryFromName (FrameId frame_id, const std::string &name) const
 Reports the id for the uniquely named geometry affixed to the indicated frame. More...
 
const Isometry3< T > & get_pose_in_world (FrameId frame_id) const
 Reports the pose of the frame with the given id. More...
 
const Isometry3< T > & get_pose_in_world (GeometryId geometry_id) const
 Reports the pose of the geometry with the given id. More...
 
const Isometry3< T > & get_pose_in_parent (FrameId frame_id) const
 Reports the pose of the frame with the given id relative to its parent frame. More...
 
const std::string & get_source_name (SourceId id) const
 Reports the source name for the given source id. More...
 
const Isometry3< double > & GetPoseInFrame (GeometryId geometry_id) const
 Reports the pose, relative to the registered frame, for the geometry the given identifier refers to. More...
 
const Isometry3< double > & GetPoseInParent (GeometryId geometry_id) const
 Reports the pose of identified dynamic geometry, relative to its registered parent. More...
 
const VisualMaterialget_visual_material (GeometryId geometry_id) const
 Returns the visual material defined for geometry indicated by the given geometry_id (if defined). More...
 
State management

The methods that modify the state including: adding/removing entities from the state, modifying values in the state, etc.

SourceId RegisterNewSource (const std::string &name="")
 Registers a new, named source into the state. More...
 
FrameId RegisterFrame (SourceId source_id, const GeometryFrame &frame)
 Registers a new frame for the given source, the id of the new frame is returned. More...
 
FrameId RegisterFrame (SourceId source_id, FrameId parent_id, const GeometryFrame &frame)
 Registers a new frame for the given source as a child of an existing frame. More...
 
GeometryId RegisterGeometry (SourceId source_id, FrameId frame_id, std::unique_ptr< GeometryInstance > geometry)
 Registers a GeometryInstance with the state. More...
 
GeometryId RegisterGeometryWithParent (SourceId source_id, GeometryId parent_id, std::unique_ptr< GeometryInstance > geometry)
 Registers a GeometryInstance with the state. More...
 
GeometryId RegisterAnchoredGeometry (SourceId source_id, std::unique_ptr< GeometryInstance > geometry)
 Registers a GeometryInstance with the state as anchored geometry. More...
 
bool IsValidGeometryName (FrameId frame_id, const std::string &candidate_name) const
 Reports whether the canonicalized version of the given candidate geometry name is considered valid. More...
 
Relationship queries

Various methods that map identifiers for one type of entity to its related entities.

bool BelongsToSource (FrameId frame_id, SourceId source_id) const
 Reports if the given frame id was registered to the given source id. More...
 
bool BelongsToSource (GeometryId geometry_id, SourceId source_id) const
 Reports if the given geometry id was ultimately registered to the given source id. More...
 
FrameId GetFrameId (GeometryId geometry_id) const
 Retrieves the frame id on which the given geometry id is registered. More...
 
const FrameIdSetGetFramesForSource (SourceId source_id) const
 Returns the set of frames registered to the given source. More...
 
Collision Queries

These queries detect collisions between geometry.

Two geometries collide if they overlap each other and are not explicitly excluded through collision filtering. These algorithms find those colliding cases, characterize them, and report the essential characteristics of that collision.

std::vector< PenetrationAsPointPair< double > > ComputePointPairPenetration () const
 See QueryObject::ComputePointPairPenetration() for documentation. More...
 
Proximity filters

This interface allows control over which pairs of geometries can even be considered for collision.

See Scene Graph Collision Filtering for more details.

void ExcludeCollisionsWithin (const GeometrySet &set)
 Excludes geometry pairs from collision evaluation by updating the candidate pair set C = C - P, where P = {(gᵢ, gⱼ)}, ∀ gᵢ, gⱼ ∈ G and G = {g₀, g₁, ..., gₘ} is the input set of geometries. More...
 
void ExcludeCollisionsBetween (const GeometrySet &setA, const GeometrySet &setB)
 Excludes geometry pairs from collision evaluation by updating the candidate pair set C = C - P, where P = {(a, b)}, ∀ a ∈ A, b ∈ B and A = {a₀, a₁, ..., aₘ} and B = {b₀, b₁, ..., bₙ} are the input sets of geometries setA and setB, respectively. More...
 
Signed Distance Queries

Refer to Signed Distance Queries for more details.

std::vector< SignedDistancePair< double > > ComputeSignedDistancePairwiseClosestPoints () const
 Computes the signed distance together with the witness points across all pairs of geometries in the world. More...
 
Scalar conversion
std::unique_ptr< GeometryState< AutoDiffXd > > ToAutoDiffXd () const
 Returns a deep copy of this state using the AutoDiffXd scalar with all scalar values initialized from the current values. More...
 

Friends

template<typename >
class GeometryState
 
class internal::GeometryVisualizationImpl
 
class SceneGraph< T >
 
template<class U >
class GeometryStateTester
 

Detailed Description

template<typename T>
class drake::geometry::GeometryState< T >

The context-dependent state of SceneGraph.

This serves as an AbstractValue in the context. SceneGraph's time-dependent state includes more than just values; objects can be added to or removed from the world over time. Therefore, SceneGraph's context-dependent state includes values (the poses) and structure (the topology of the world).

Template Parameters
TThe scalar type. Must be a valid Eigen scalar.

Instantiated templates for the following kinds of T's are provided:

  • double
  • AutoDiffXd

They are already available to link against in the containing library. No other values for T are currently supported.

Member Typedef Documentation

◆ FrameIdRange

An object that represents the range of FrameId values in the state.

It is used in range-based for loops to iterate through registered frames.

Constructor & Destructor Documentation

◆ GeometryState() [1/3]

GeometryState ( const GeometryState< T > &  )
default

◆ GeometryState() [2/3]

GeometryState ( GeometryState< T > &&  )
default

◆ GeometryState() [3/3]

Default constructor.

Member Function Documentation

◆ BelongsToSource() [1/2]

bool BelongsToSource ( FrameId  frame_id,
SourceId  source_id 
) const

Reports if the given frame id was registered to the given source id.

Parameters
frame_idThe query frame id.
source_idThe query source id.
Returns
True if frame_id was registered on source_id.
Exceptions
std::logic_errorIf the frame_id does not map to a frame or the identified source is not registered.

◆ BelongsToSource() [2/2]

bool BelongsToSource ( GeometryId  geometry_id,
SourceId  source_id 
) const

Reports if the given geometry id was ultimately registered to the given source id.

Parameters
geometry_idThe query geometry id.
source_idThe query source id.
Returns
True if geometry_id was registered on source_id.
Exceptions
std::logic_errorIf the geometry_id does not map to a valid geometry or the identified source is not registered

◆ ComputePointPairPenetration()

std::vector<PenetrationAsPointPair<double> > ComputePointPairPenetration ( ) const
inline

◆ ComputeSignedDistancePairwiseClosestPoints()

std::vector<SignedDistancePair<double> > ComputeSignedDistancePairwiseClosestPoints ( ) const
inline

Computes the signed distance together with the witness points across all pairs of geometries in the world.

Reports both the separating geometries and penetrating geometries.

Return values
witness_pairsA vector of reporting the signed distance characterized as witness point pairs. Notice that this is an O(N²) operation, where N is the number of geometries in the world. We report the distance between dynamic objects, or between a dynamic object and an anchored object. We DO NOT report the distance between two anchored objects.

◆ ExcludeCollisionsBetween()

void ExcludeCollisionsBetween ( const GeometrySet setA,
const GeometrySet setB 
)

Excludes geometry pairs from collision evaluation by updating the candidate pair set C = C - P, where P = {(a, b)}, ∀ a ∈ A, b ∈ B and A = {a₀, a₁, ..., aₘ} and B = {b₀, b₁, ..., bₙ} are the input sets of geometries setA and setB, respectively.

This does not preclude collisions between members of the same set.

Exceptions
std::logic_errorif the groups include ids that don't exist in the scene graph.

◆ ExcludeCollisionsWithin()

void ExcludeCollisionsWithin ( const GeometrySet set)

Excludes geometry pairs from collision evaluation by updating the candidate pair set C = C - P, where P = {(gᵢ, gⱼ)}, ∀ gᵢ, gⱼ ∈ G and G = {g₀, g₁, ..., gₘ} is the input set of geometries.

Exceptions
std::logic_errorif the set includes ids that don't exist in the scene graph.

◆ get_frame_group()

int get_frame_group ( FrameId  frame_id) const

Reports the frame group for the given frame.

Parameters
frame_idThe identifier of the queried frame.
Returns
The frame group of the identified frame.
Exceptions
std::logic_errorif the frame id is not valid.

◆ get_frame_ids()

FrameIdRange get_frame_ids ( ) const
inline

Provides a range object for all of the frame ids in the scene graph.

The order is not generally guaranteed; but it will be consistent as long as there are no changes to the topology. This is intended to be used as:

for (FrameId id : state.get_frame_ids()) {
...
}

This will include the id for the world frame.

◆ get_frame_name()

const std::string & get_frame_name ( FrameId  frame_id) const

Reports the name of the frame.

Parameters
frame_idThe identifier of the queried frame.
Returns
The name of the identified frame.
Exceptions
std::logic_errorif the frame id is not valid.

◆ get_geometry_ids()

const std::vector<GeometryId>& get_geometry_ids ( ) const
inline

The set of all dynamic geometries registered to the world.

The order is not guaranteed to have any particular semantic meaning. But the order is guaranteed to remain fixed between topological changes (e.g., removal or addition of geometry/frames).

◆ get_name()

const std::string & get_name ( GeometryId  geometry_id) const

Reports the stored, canonical name of the geometry (see GeometryInstance for details).

Parameters
geometry_idThe identifier of the queried geometry.
Returns
The name of the identified geometry.
Exceptions
std::logic_errorif the geometry id is not valid.

◆ get_num_frames()

int get_num_frames ( ) const
inline

Reports the total number of frames – across all sources.

◆ get_num_geometries()

int get_num_geometries ( ) const
inline

Reports the total number of geometries.

◆ get_num_sources()

int get_num_sources ( ) const
inline

Reports the number of registered sources – whether they have frames or not.

◆ get_pose_in_parent()

const Isometry3< T > & get_pose_in_parent ( FrameId  frame_id) const

Reports the pose of the frame with the given id relative to its parent frame.

If the frame's parent is the world, the value should be the same as a call to get_pose_in_world().

Parameters
frame_idThe identifier of the queried frame.
Returns
The pose in the parent frame (X_PF) of the identified frame.
Exceptions
std::logic_errorif the frame id is not valid.

◆ get_pose_in_world() [1/2]

const Isometry3< T > & get_pose_in_world ( FrameId  frame_id) const

Reports the pose of the frame with the given id.

Parameters
frame_idThe identifier of the queried frame.
Returns
The pose in the world (X_WF) of the identified frame.
Exceptions
std::logic_errorif the frame id is not valid.

◆ get_pose_in_world() [2/2]

const Isometry3< T > & get_pose_in_world ( GeometryId  geometry_id) const

Reports the pose of the geometry with the given id.

Parameters
geometry_idThe identifier of the queried geometry.
Returns
The pose in the world (X_WG) of the identified geometry.
Exceptions
std::logic_errorif the geometry id is not valid.

◆ get_source_name()

const std::string & get_source_name ( SourceId  id) const

Reports the source name for the given source id.

Parameters
idThe identifier of the source.
Returns
The name of the source.
Exceptions
std::logic_errorif the id does not map to a registered source.

◆ get_visual_material()

const VisualMaterial & get_visual_material ( GeometryId  geometry_id) const

Returns the visual material defined for geometry indicated by the given geometry_id (if defined).

Exceptions
std::logic_errorIf the geometry_id does not map to a valid GeometryInstance.

◆ GetFrameId()

FrameId GetFrameId ( GeometryId  geometry_id) const

Retrieves the frame id on which the given geometry id is registered.

Parameters
geometry_idThe query geometry id.
Returns
An optional FrameId based on a successful lookup.
Exceptions
std::logic_errorIf the geometry_id does not map to a geometry which belongs to an existing frame.

◆ GetFramesForSource()

const FrameIdSet & GetFramesForSource ( SourceId  source_id) const

Returns the set of frames registered to the given source.

Parameters
source_idThe identifier of the source to query.
Returns
The set of frames associated with the id.
Exceptions
std::logic_errorIf the source_id does not map to a registered source.

◆ GetGeometryFromName()

GeometryId GetGeometryFromName ( FrameId  frame_id,
const std::string &  name 
) const

Reports the id for the uniquely named geometry affixed to the indicated frame.

Parameters
frame_idThe id of the parent frame.
nameThe name of the geometry to query for. The name will be canonicalized prior to lookup (see GeometryInstance for details).
Returns
The id of the requested geometry.
Exceptions
std::logic_errorif no such geometry exists, multiple geometries have that name, or if the frame doesn't exist.

◆ GetNumAnchoredGeometries()

int GetNumAnchoredGeometries ( ) const

Reports the total number of anchored geometries.

This should provide the same answer as calling GetNumFrameGeometries() with the world frame id.

◆ GetNumDynamicGeometries()

int GetNumDynamicGeometries ( ) const

Reports the total number of dynamic geometries in the scene graph.

◆ GetNumFrameGeometries()

int GetNumFrameGeometries ( FrameId  frame_id) const

Reports the total number of geometries directly registered to the given frame.

This count does not include geometries attached to frames that are descendants of this frame.

Exceptions
std::runtime_errorif the frame_id is invalid.

◆ GetPoseInFrame()

const Isometry3< double > & GetPoseInFrame ( GeometryId  geometry_id) const

Reports the pose, relative to the registered frame, for the geometry the given identifier refers to.

Parameters
geometry_idThe id of the queried geometry.
Returns
The geometry's pose relative to its frame.
Exceptions
std::logic_errorIf the geometry_id does not map to a valid GeometryInstance.

◆ GetPoseInParent()

const Isometry3< double > & GetPoseInParent ( GeometryId  geometry_id) const

Reports the pose of identified dynamic geometry, relative to its registered parent.

If the geometry was registered directly to a frame, this must produce the same pose as GetPoseInFrame().

Parameters
geometry_idThe id of the queried geometry.
Returns
The geometry's pose relative to its registered parent.
Exceptions
std::logic_errorIf the geometry_id does not map to a valid GeometryInstance.

◆ IsValidGeometryName()

bool IsValidGeometryName ( FrameId  frame_id,
const std::string &  candidate_name 
) const

Reports whether the canonicalized version of the given candidate geometry name is considered valid.

This tests the requirements described in the documentation of GeometryInstance. When adding a geometry to a frame, if there is doubt if a proposed name is valid, the name can be tested prior to registering the geometry.

Parameters
frame_idThe id of the frame to which the geometry would be assigned.
candidate_nameThe name to validate.
Returns
true if the candidate_name can be given to a GeometryInstance assigned to the indicated frame.
Exceptions
std::exceptionif frame_id does not refer to a valid frame.

◆ operator=() [1/3]

GeometryState& operator= ( const GeometryState< T > &  )
default

◆ operator=() [2/3]

GeometryState& operator= ( GeometryState< T > &&  )
default

◆ operator=() [3/3]

std::enable_if<!std::is_same<T1, double>::value, GeometryState<T>&>::type operator= ( const GeometryState< double > &  other)
inline

Allow assignment from a GeometryState<double> to a GeometryState<T>.

◆ RegisterAnchoredGeometry()

GeometryId RegisterAnchoredGeometry ( SourceId  source_id,
std::unique_ptr< GeometryInstance geometry 
)

Registers a GeometryInstance with the state as anchored geometry.

This registers geometry which "hangs" from the world frame and never moves. The geometry's pose value is relative to the world frame. The state takes ownership of the geometry and associates it with the given source. Returns the new identifier for the GeometryInstance.

Parameters
source_idThe id of the source on which the geometry is being declared.
geometryThe geometry to get the id for. The state takes ownership of the geometry.
Returns
A newly allocated geometry id.
Exceptions
std::logic_error1. the source_id does not map to a registered source,
  1. geometry has a previously registered id, or
  2. the geometry's name doesn't satisfy the requirements outlined in GeometryInstance.

◆ RegisterFrame() [1/2]

FrameId RegisterFrame ( SourceId  source_id,
const GeometryFrame frame 
)

Registers a new frame for the given source, the id of the new frame is returned.

Parameters
source_idThe id of the source for which this frame is allocated.
frameThe frame to register.
Returns
A newly allocated frame id.
Exceptions
std::logic_errorIf the source_id does not map to a registered source, or frame has an id that has already been registered.

◆ RegisterFrame() [2/2]

FrameId RegisterFrame ( SourceId  source_id,
FrameId  parent_id,
const GeometryFrame frame 
)

Registers a new frame for the given source as a child of an existing frame.

The id of the new frame is returned. A pose for this frame will need to be provided in the FramePoseVector parameter to SetFramePoses().

Parameters
source_idThe id of the source for which this frame is allocated.
parent_idThe id of the parent frame.
frameThe frame to register.
Returns
A newly allocated frame id.
Exceptions
std::logic_error1. If the source_id does not map to a registered source,
  1. If the parent_id does not map to a known frame or does not belong to the source
  2. frame has an id that has already been registered.

◆ RegisterGeometry()

GeometryId RegisterGeometry ( SourceId  source_id,
FrameId  frame_id,
std::unique_ptr< GeometryInstance geometry 
)

Registers a GeometryInstance with the state.

The state takes ownership of the geometry and associates it with the given frame and source. Returns the new identifier for the successfully registered GeometryInstance.

Parameters
source_idThe id of the source to which the frame and geometry belongs.
frame_idThe id of the frame on which the geometry is to hang.
geometryThe geometry to get the id for. The state takes ownership of the geometry.
Returns
A newly allocated geometry id.
Exceptions
std::logic_error1. the source_id does not map to a registered source,
  1. the frame_id doesn't belong to the source,
  2. the geometry is equal to nullptr,
  3. geometry has a previously registered id, or
  4. the geometry's name doesn't satisfy the requirements outlined in GeometryInstance.

◆ RegisterGeometryWithParent()

GeometryId RegisterGeometryWithParent ( SourceId  source_id,
GeometryId  parent_id,
std::unique_ptr< GeometryInstance geometry 
)

Registers a GeometryInstance with the state.

Rather than hanging directly from a frame, the instance hangs on another geometry instance. The input geometry instance's pose is assumed to be relative to that parent geometry instance. The state takes ownership of the geometry and associates it with the given geometry parent (and, ultimately, the parent geometry's frame) and source. Returns the new identifier for the successfully registered GeometryInstance.

Parameters
source_idThe id of the source on which the geometry is being declared.
parent_idThe parent geometry for this geometry.
geometryThe geometry to get the id for. The state takes ownership of the geometry.
Returns
A newly allocated geometry id.
Exceptions
std::logic_error1. the source_id does not map to a registered source,
  1. the parent_id doesn't belong to the source,
  2. the geometry is equal to nullptr,
  3. geometry has a previously registered id, or
  4. the geometry's name doesn't satisfy the requirements outlined in GeometryInstance.

◆ RegisterNewSource()

SourceId RegisterNewSource ( const std::string &  name = "")

Registers a new, named source into the state.

Parameters
nameThe optional name of the source. If none or the empty string is provided it will be named "Source_##" where the number is the value of the returned SourceId.
Exceptions
std::logic_erroris thrown if the name is not unique.

◆ source_is_registered()

bool source_is_registered ( SourceId  source_id) const

Reports true if the given source_id references a registered source.

◆ ToAutoDiffXd()

std::unique_ptr< GeometryState< AutoDiffXd > > ToAutoDiffXd ( ) const

Returns a deep copy of this state using the AutoDiffXd scalar with all scalar values initialized from the current values.

If this is invoked on an instance already instantiated on AutoDiffXd, it is equivalent to cloning the instance.

Friends And Related Function Documentation

◆ GeometryState

friend class GeometryState
friend

◆ GeometryStateTester

friend class GeometryStateTester
friend

◆ internal::GeometryVisualizationImpl

friend class internal::GeometryVisualizationImpl
friend

◆ SceneGraph< T >

friend class SceneGraph< T >
friend

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