Drake
Drake C++ Documentation
SceneGraphInspector< T > Class Template Reference

Detailed Description

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

The SceneGraphInspector serves as a mechanism to query the topological structure of a SceneGraph instance.

The topological structure consists of all of the SceneGraph data that does not depend on input pose data. Including, but not limited to:

  • names of frames and geometries
  • hierarchies (parents of geometries, parents of frames, etc.)
  • geometry parameters (e.g., contact, rendering, visualization)
  • fixed poses of geometries relative to frames

In contrast, the following pieces of data do depend on input pose data and cannot be performed with the SceneGraphInspector (see the QueryObject instead):

  • world pose of frames or geometry
  • collision queries
  • proximity queries

A SceneGraphInspector cannot be instantiated explicitly. Nor can it be copied or moved. A reference to a SceneGraphInspector instance can be acquired from

  • a SceneGraph instance (to inspect the state of the system's model), or
  • a QueryObject instance (to inspect the state of the scene graph data stored in the context).

The reference should not be persisted (and, as previously indicated, cannot be copied). SceneGraphInspector instances are cheap; they can be created, queried, and thrown out. If there is any doubt about the valid lifespan of a SceneGraphInspector, throw out the old instance and request a new instance.

Template Parameters
TThe scalar of the associated SceneGraph instance. The template parameter is provided for the sake of compatibility, although no queries (or their results) depend on the scalar.

#include <drake/geometry/scene_graph_inspector.h>

Public Member Functions

Does not allow copy, move, or assignment
 SceneGraphInspector (const SceneGraphInspector &)=delete
 
SceneGraphInspectoroperator= (const SceneGraphInspector &)=delete
 
 SceneGraphInspector (SceneGraphInspector &&)=delete
 
SceneGraphInspectoroperator= (SceneGraphInspector &&)=delete
 
Scene-graph wide data
int num_sources () const
 Reports the number of registered sources – whether they have registered frames/geometries or not. More...
 
int num_frames () const
 Reports the total number of frames registered in the scene graph (including the world frame). More...
 
std::vector< SourceIdGetAllSourceIds () const
 Returns all of the source ids in the scene graph. More...
 
std::vector< FrameIdGetAllFrameIds () const
 Returns all of the frame ids in the scene graph. More...
 
FrameId world_frame_id () const
 Reports the id for the world frame. More...
 
int num_geometries () const
 Reports the total number of geometries in the scene graph. More...
 
std::vector< GeometryIdGetAllGeometryIds (std::optional< Role > role=std::nullopt) const
 Returns the set of all ids for registered geometries. More...
 
std::unordered_set< GeometryIdGetGeometryIds (const GeometrySet &geometry_set, std::optional< Role > role=std::nullopt) const
 Returns the geometry ids that are implied by the given GeometrySet and role. More...
 
int NumGeometriesWithRole (Role role) const
 Reports the total number of geometries in the scene graph with the indicated role. More...
 
int NumDynamicGeometries () const
 Reports the total number of dynamic geometries in the scene graph. More...
 
int NumAnchoredGeometries () const
 Reports the total number of anchored non-deformable geometries. More...
 
std::set< std::pair< GeometryId, GeometryId > > GetCollisionCandidates () const
 Returns all pairs of geometries that are candidates for collision (in no particular order). More...
 
const GeometryVersiongeometry_version () const
 Returns the geometry version that can be used to detect changes to the geometry data associated with geometry roles. More...
 
Sources and source-related data
bool SourceIsRegistered (SourceId source_id) const
 Reports true if the given source_id maps to a registered source. More...
 
const std::string & GetName (SourceId source_id) const
 Reports the name for the source with the given source_id. More...
 
int NumFramesForSource (SourceId source_id) const
 Reports the number of frames registered to the source with the given source_id. More...
 
const std::unordered_set< FrameId > & FramesForSource (SourceId source_id) const
 Reports the ids of all of the frames registered to the source with the given source source_id. More...
 
Frames and their properties
bool BelongsToSource (FrameId frame_id, SourceId source_id) const
 Reports if the frame with given frame_id was registered to the source with the given source_id. More...
 
const std::string & GetOwningSourceName (FrameId frame_id) const
 Reports the name of the geometry source that registered the frame with the given frame_id. More...
 
const std::string & GetName (FrameId frame_id) const
 Reports the name of the frame with the given frame_id. More...
 
FrameId GetParentFrame (FrameId frame_id) const
 Reports the FrameId of the parent of frame_id. More...
 
int GetFrameGroup (FrameId frame_id) const
 Reports the frame group for the frame with the given frame_id. More...
 
int NumGeometriesForFrame (FrameId frame_id) const
 Reports the number of geometries affixed to the frame with the given frame_id. More...
 
int NumGeometriesForFrameWithRole (FrameId frame_id, Role role) const
 Reports the total number of geometries with the given role directly registered to the frame with the given frame_id. More...
 
std::vector< GeometryIdGetGeometries (FrameId frame_id, const std::optional< Role > &role=std::nullopt) const
 Returns geometry ids that have been registered directly to the frame indicated by frame_id. More...
 
GeometryId GetGeometryIdByName (FrameId frame_id, Role role, const std::string &name) const
 Reports the id of the geometry with the given name and role, attached to the frame with the given frame frame_id. More...
 
Geometries and their properties
bool BelongsToSource (GeometryId geometry_id, SourceId source_id) const
 Reports if the given geometry id was registered to the source with the given source id. More...
 
const std::string & GetOwningSourceName (GeometryId geometry_id) const
 Reports the name of the geometry source that registered the geometry with the given geometry_id. More...
 
FrameId GetFrameId (GeometryId geometry_id) const
 Reports the id of the frame to which the given geometry with the given geometry_id is registered. More...
 
const std::string & GetName (GeometryId geometry_id) const
 Reports the stored, canonical name of the geometry with the given geometry_id (see GeometryInstance for details). More...
 
const ShapeGetShape (GeometryId geometry_id) const
 Returns the shape specified for the geometry with the given geometry_id. More...
 
const math::RigidTransform< double > & GetPoseInFrame (GeometryId geometry_id) const
 Reports the pose of the geometry G with the given geometry_id in its registered frame F. More...
 
std::variant< std::monostate, const TriangleSurfaceMesh< double > *, const VolumeMesh< double > * > maybe_get_hydroelastic_mesh (GeometryId geometry_id) const
 Returns the mesh used to represent this geometry in hydroelastic contact calculations, if it exists. More...
 
const GeometryPropertiesGetProperties (GeometryId geometry_id, Role role) const
 Return a pointer to the const properties indicated by role of the geometry with the given geometry_id. More...
 
const ProximityPropertiesGetProximityProperties (GeometryId geometry_id) const
 Returns a pointer to the const proximity properties of the geometry with the given geometry_id. More...
 
const IllustrationPropertiesGetIllustrationProperties (GeometryId geometry_id) const
 Returns a pointer to the const illustration properties of the geometry with the given geometry_id. More...
 
const PerceptionPropertiesGetPerceptionProperties (GeometryId geometry_id) const
 Returns a pointer to the const perception properties of the geometry with the given geometry_id. More...
 
const VolumeMesh< double > * GetReferenceMesh (GeometryId geometry_id) const
 Returns the reference mesh of the geometry with the given geometry_id, measured and expressed in the geometry's frame, G. More...
 
bool IsDeformableGeometry (GeometryId geometry_id) const
 Returns true if the geometry with the given geometry_id is deformable. More...
 
std::vector< GeometryIdGetAllDeformableGeometryIds () const
 Returns all geometry ids that correspond to deformable geometries. More...
 
const PolygonSurfaceMesh< double > * GetConvexHull (GeometryId geometry_id) const
 Returns the convex hull (a polytope) associated with the given geometry_id, if it exists. More...
 
bool CollisionFiltered (GeometryId geometry_id1, GeometryId geometry_id2) const
 Reports true if the two geometries with given ids geometry_id1 and geometry_id2, define a collision pair that has been filtered out. More...
 
void Reify (GeometryId geometry_id, ShapeReifier *reifier) const
 (Deprecated.) More...
 
std::unique_ptr< GeometryInstanceCloneGeometryInstance (GeometryId geometry_id) const
 Obtains a new GeometryInstance that copies the geometry indicated by the given geometry_id. More...
 

Friends

class SceneGraph< T >
 
class QueryObject< T >
 
class SceneGraphInspectorTester
 

Constructor & Destructor Documentation

◆ SceneGraphInspector() [1/2]

SceneGraphInspector ( const SceneGraphInspector< T > &  )
delete

◆ SceneGraphInspector() [2/2]

Member Function Documentation

◆ BelongsToSource() [1/2]

bool BelongsToSource ( FrameId  frame_id,
SourceId  source_id 
) const

Reports if the frame with given frame_id was registered to the source with 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::exceptionIf frame_id does not map to a registered frame or source_id does not map to a registered source.

◆ BelongsToSource() [2/2]

bool BelongsToSource ( GeometryId  geometry_id,
SourceId  source_id 
) const

Reports if the given geometry id was registered to the source with 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::exceptionIf geometry_id does not map to a registered geometry or source_id does not map to a registered source.

◆ CloneGeometryInstance()

std::unique_ptr<GeometryInstance> CloneGeometryInstance ( GeometryId  geometry_id) const

Obtains a new GeometryInstance that copies the geometry indicated by the given geometry_id.

Returns
A new GeometryInstance that is ready to be added as a new geometry. All roles/properties will be copied, the shape will be cloned based off of the original, but the returned id() will completely unique.
Exceptions
std::exceptionif the geometry_id does not refer to a valid geometry.

◆ CollisionFiltered()

bool CollisionFiltered ( GeometryId  geometry_id1,
GeometryId  geometry_id2 
) const

Reports true if the two geometries with given ids geometry_id1 and geometry_id2, define a collision pair that has been filtered out.

Exceptions
std::exceptionif either id does not map to a registered geometry or if any of the geometries do not have a proximity role.

◆ FramesForSource()

const std::unordered_set<FrameId>& FramesForSource ( SourceId  source_id) const

Reports the ids of all of the frames registered to the source with the given source source_id.

Exceptions
std::exceptionif source_id does not map to a registered source.

◆ geometry_version()

const GeometryVersion& geometry_version ( ) const

Returns the geometry version that can be used to detect changes to the geometry data associated with geometry roles.

The reference returned should not be persisted. If it needs to be persisted, it should be copied.

◆ GetAllDeformableGeometryIds()

std::vector<GeometryId> GetAllDeformableGeometryIds ( ) const

Returns all geometry ids that correspond to deformable geometries.

The order is guaranteed to be stable and consistent.

◆ GetAllFrameIds()

std::vector<FrameId> GetAllFrameIds ( ) const

Returns all of the frame ids in the scene graph.

The order is guaranteed to be stable and consistent. The ids include the world frame's id.

◆ GetAllGeometryIds()

std::vector<GeometryId> GetAllGeometryIds ( std::optional< Role role = std::nullopt) const

Returns the set of all ids for registered geometries.

The order is guaranteed to be stable and consistent.

Parameters
roleThe requested role; if omitted, all geometries are returned.

◆ GetAllSourceIds()

std::vector<SourceId> GetAllSourceIds ( ) const

Returns all of the source ids in the scene graph.

The order is guaranteed to be stable and consistent. The first element is the SceneGraph-internal source.

◆ GetCollisionCandidates()

std::set<std::pair<GeometryId, GeometryId> > GetCollisionCandidates ( ) const

Returns all pairs of geometries that are candidates for collision (in no particular order).

See CollisionFilterDeclaration and CollisionFilterManager::Apply() for information on why a particular pair may not be a candidate.

For candidate pair (A, B), the candidate is always guaranteed to be reported in a fixed order (i.e., always (A, B) and never (B, A)). This is the same ordering as would be returned by, e.g., QueryObject::ComputePointPairPenetration().

◆ GetConvexHull()

const PolygonSurfaceMesh<double>* GetConvexHull ( GeometryId  geometry_id) const

Returns the convex hull (a polytope) associated with the given geometry_id, if it exists.

Basic primitive shapes don't have convex hulls (including, arbitrarily, Box). But Mesh and Convex shapes do. Alternatively, if you already have a Mesh or Convex you can call Mesh::convex_hull() or Convex::convex_hull(), respectively.

◆ GetFrameGroup()

int GetFrameGroup ( FrameId  frame_id) const

Reports the frame group for the frame with the given frame_id.

Exceptions
std::exceptionif frame_id does not map to a registered frame.

◆ GetFrameId()

FrameId GetFrameId ( GeometryId  geometry_id) const

Reports the id of the frame to which the given geometry with the given geometry_id is registered.

Exceptions
std::exceptionif geometry_id does not map to a registered geometry.

◆ GetGeometries()

std::vector<GeometryId> GetGeometries ( FrameId  frame_id,
const std::optional< Role > &  role = std::nullopt 
) const

Returns geometry ids that have been registered directly to the frame indicated by frame_id.

If a role is provided, only geometries with that role assigned will be returned, otherwise all geometries will be returned. The order of the ids is guaranteed to be stable and consistent.

Parameters
frame_idThe id of the frame in question.
roleThe requested role; if omitted, all geometries registered to the frame are returned.
Returns
The requested unique geometry ids in a consistent order.
Exceptions
std::exceptionif id does not map to a registered frame.

◆ GetGeometryIdByName()

GeometryId GetGeometryIdByName ( FrameId  frame_id,
Role  role,
const std::string &  name 
) const

Reports the id of the geometry with the given name and role, attached to the frame with the given frame frame_id.

Parameters
frame_idThe frame_id of the frame whose geometry is being queried.
roleThe assigned role of the desired geometry.
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 queried geometry.
Exceptions
std::exceptionif no such geometry exists, multiple geometries have that name, or if the frame_id does not map to a registered frame.

◆ GetGeometryIds()

std::unordered_set<GeometryId> GetGeometryIds ( const GeometrySet geometry_set,
std::optional< Role role = std::nullopt 
) const

Returns the geometry ids that are implied by the given GeometrySet and role.

Remember that a GeometrySet can reference a FrameId in place of the ids of the individual geometries affixed to it. If a role is provided, only geometries with that role assigned will be returned, otherwise all geometries will be returned.

Note
Specifying role can have the effect of filtering geometries from the given geometry_set` – if a GeometryId is an explicit member of the geometry set but does not have the requested role, it will not be contained in the output.
Parameters
geometry_setThe encoding of the set of geometries.
roleThe requested role; if omitted, all geometries registered to the frame are returned.
Returns
The requested unique geometry ids.
Warning
For C++ users: this returns an unordered set, which means iteration order will be non-deterministic.

◆ GetIllustrationProperties()

const IllustrationProperties* GetIllustrationProperties ( GeometryId  geometry_id) const

Returns a pointer to the const illustration properties of the geometry with the given geometry_id.

Parameters
geometry_idThe identifier for the queried geometry.
Returns
A pointer to the properties (or nullptr if there are no such properties).
Exceptions
std::exceptionif geometry_id does not map to a registered geometry.

◆ GetName() [1/3]

const std::string& GetName ( SourceId  source_id) const

Reports the name for the source with the given source_id.

Exceptions
std::exceptionif source_id does not map to a registered source.

◆ GetName() [2/3]

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

Reports the name of the frame with the given frame_id.

Exceptions
std::exceptionif frame_id does not map to a registered frame.

◆ GetName() [3/3]

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

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

Exceptions
std::exceptionif geometry_id does not map to a registered geometry.

◆ GetOwningSourceName() [1/2]

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

Reports the name of the geometry source that registered the frame with the given frame_id.

Exceptions
std::exceptionIf frame_id does not map to a registered frame.

◆ GetOwningSourceName() [2/2]

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

Reports the name of the geometry source that registered the geometry with the given geometry_id.

Exceptions
std::exceptionIf geometry_id does not map to a registered geometry.

◆ GetParentFrame()

FrameId GetParentFrame ( FrameId  frame_id) const

Reports the FrameId of the parent of frame_id.

Exceptions
std::exceptionif frame_id does not map to a registered frame.

◆ GetPerceptionProperties()

const PerceptionProperties* GetPerceptionProperties ( GeometryId  geometry_id) const

Returns a pointer to the const perception properties of the geometry with the given geometry_id.

Parameters
geometry_idThe identifier for the queried geometry.
Returns
A pointer to the properties (or nullptr if there are no such properties).
Exceptions
std::exceptionif geometry_id does not map to a registered geometry.

◆ GetPoseInFrame()

const math::RigidTransform<double>& GetPoseInFrame ( GeometryId  geometry_id) const

Reports the pose of the geometry G with the given geometry_id in its registered frame F.

Note
For deformable geometries, this returns the pose of the reference mesh.
Exceptions
std::exceptionif geometry_id does not map to a registered geometry.

◆ GetProperties()

const GeometryProperties* GetProperties ( GeometryId  geometry_id,
Role  role 
) const

Return a pointer to the const properties indicated by role of the geometry with the given geometry_id.

Parameters
geometry_idThe identifier for the queried geometry.
roleThe role whose properties are acquired.
Returns
A pointer to the properties (or nullptr if there are no such properties).
Exceptions
std::exceptionif geometry_id does not map to a registered geometry.

◆ GetProximityProperties()

const ProximityProperties* GetProximityProperties ( GeometryId  geometry_id) const

Returns a pointer to the const proximity properties of the geometry with the given geometry_id.

Parameters
geometry_idThe identifier for the queried geometry.
Returns
A pointer to the properties (or nullptr if there are no such properties).
Exceptions
std::exceptionif geometry_id does not map to a registered geometry.

◆ GetReferenceMesh()

const VolumeMesh<double>* GetReferenceMesh ( GeometryId  geometry_id) const

Returns the reference mesh of the geometry with the given geometry_id, measured and expressed in the geometry's frame, G.

Parameters
geometry_idThe identifier for the queried geometry.
Returns
A pointer to the reference mesh of the geometry if the geometry is deformable, or nullptr if the geometry is rigid.
Note
GetPoseInFrame() provides the transform necessary to measure and express the reference mesh's vertex positions in the geometry's registered frame F.
Exceptions
std::exceptionif geometry_id does not map to a registered geometry.

◆ GetShape()

const Shape& GetShape ( GeometryId  geometry_id) const

Returns the shape specified for the geometry with the given geometry_id.

In order to extract the details of the shape, it should be passed through an implementation of a ShapeReifier.

◆ IsDeformableGeometry()

bool IsDeformableGeometry ( GeometryId  geometry_id) const

Returns true if the geometry with the given geometry_id is deformable.

Parameters
geometry_idThe identifier for the queried geometry.
Exceptions
std::exceptionif geometry_id does not map to a registered geometry.

◆ maybe_get_hydroelastic_mesh()

std::variant<std::monostate, const TriangleSurfaceMesh<double>*, const VolumeMesh<double>*> maybe_get_hydroelastic_mesh ( GeometryId  geometry_id) const

Returns the mesh used to represent this geometry in hydroelastic contact calculations, if it exists.

Most primitives (sphere, cylinder, etc.) are actually represented by discrete approximations (i.e., the mesh). If there is no mesh, the returned variant will hold neither the TriangleSurfaceMesh<double> nor the VolumeMesh<double> alternatives. If either alternative is present, the pointer is guaranteed to be non-null.

Just because hydroelastic properties have been assigned to a geometry does not* mean there is necessarily a mesh associated with it. Some shape types (e.g., half space) have non-mesh representations.

The result can be tested as follows:

auto maybe_mesh = inspector.maybe_get_hydroelastic_mesh(id);
// These two methods are equivalent, although testing index is more
// brittle.
const bool no_mesh1 = maybe_mesh.index() == 0;
const bool no_mesh2 = std::holds_alternative<std::monostate>(maybe_mesh);
Parameters
geometry_idThe id of the geometry to query.
Returns
The associated mesh, if it exists.

◆ num_frames()

int num_frames ( ) const

Reports the total number of frames registered in the scene graph (including the world frame).

◆ num_geometries()

int num_geometries ( ) const

Reports the total number of geometries in the scene graph.

◆ num_sources()

int num_sources ( ) const

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

This will always be at least 1; the SceneGraph itself counts as a source.

◆ NumAnchoredGeometries()

int NumAnchoredGeometries ( ) const

Reports the total number of anchored non-deformable geometries.

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

◆ NumDynamicGeometries()

int NumDynamicGeometries ( ) const

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

This include all deformable geometries.

◆ NumFramesForSource()

int NumFramesForSource ( SourceId  source_id) const

Reports the number of frames registered to the source with the given source_id.

Exceptions
std::exceptionif source_id does not map to a registered source.

◆ NumGeometriesForFrame()

int NumGeometriesForFrame ( FrameId  frame_id) const

Reports the number of geometries affixed to the frame with the given frame_id.

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

Exceptions
std::exceptionif frame_id does not map to a registered frame.

◆ NumGeometriesForFrameWithRole()

int NumGeometriesForFrameWithRole ( FrameId  frame_id,
Role  role 
) const

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

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

Exceptions
std::exceptionif frame_id does not map to a registered frame.

◆ NumGeometriesWithRole()

int NumGeometriesWithRole ( Role  role) const

Reports the total number of geometries in the scene graph with the indicated role.

◆ operator=() [1/2]

SceneGraphInspector& operator= ( SceneGraphInspector< T > &&  )
delete

◆ operator=() [2/2]

SceneGraphInspector& operator= ( const SceneGraphInspector< T > &  )
delete

◆ Reify()

void Reify ( GeometryId  geometry_id,
ShapeReifier reifier 
) const

(Deprecated.)

Deprecated:
This shortcut function is being removed. Instead, call inspector.GetShape(geometry_id).Reify(reifier)
This will be removed from Drake on or after 2024-06-01.

◆ SourceIsRegistered()

bool SourceIsRegistered ( SourceId  source_id) const

Reports true if the given source_id maps to a registered source.

◆ world_frame_id()

FrameId world_frame_id ( ) const

Reports the id for the world frame.

Friends And Related Function Documentation

◆ QueryObject< T >

friend class QueryObject< T >
friend

◆ SceneGraph< T >

friend class SceneGraph< T >
friend

◆ SceneGraphInspectorTester

friend class SceneGraphInspectorTester
friend

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