Allow "drilling down" into nested model frames

Migration.md

@@ -22,9 +22,10 @@ but with improved human-readability..
 
 ### Modifications
 
-1. **sdf/Model.hh**: the following methods now accept nested names
-      that can begin with a sequence of nested model names separated
-      by `::` and may end with the name of an object of the specified type.
+1. **sdf/Model.hh**: the following methods now accept nested names relative to
+      the model's scope that can begin with a sequence of nested model names
+      separated by `::` and may end with the name of an object of the specified
+      type.
     + const Frame \*FrameByName(const std::string &) const
     + const Joint \*JointByName(const std::string &) const
     + const Link \*LinkByName(const std::string &) const

include/sdf/Collision.hh

@@ -36,6 +36,7 @@ namespace sdf
   class Geometry;
   class Surface;
   struct PoseRelativeToGraph;
+  template <typename T> class ScopedGraph;
 
   /// \brief A collision element descibes the collision properties associated
   /// with a link. This can be different from the visual properties of a link.
@@ -141,12 +142,12 @@ namespace sdf
     /// \param[in] _xmlParentName Name of xml parent object.
     private: void SetXmlParentName(const std::string &_xmlParentName);
 
-    /// \brief Give a weak pointer to the PoseRelativeToGraph to be used
-    /// for resolving poses. This is private and is intended to be called by
+    /// \brief Give the scoped PoseRelativeToGraph to be used for resolving
+    /// poses. This is private and is intended to be called by
     /// Link::SetPoseRelativeToGraph.
-    /// \param[in] _graph Weak pointer to PoseRelativeToGraph.
+    /// \param[in] _graph scoped PoseRelativeToGraph object.
     private: void SetPoseRelativeToGraph(
-        std::weak_ptr<const PoseRelativeToGraph> _graph);
+        sdf::ScopedGraph<PoseRelativeToGraph> _graph);
 
     /// \brief Allow Link::SetPoseRelativeToGraph to call SetXmlParentName
     /// and SetPoseRelativeToGraph, but Link::SetPoseRelativeToGraph is

include/sdf/Frame.hh

@@ -35,6 +35,7 @@ namespace sdf
   class FramePrivate;
   struct FrameAttachedToGraph;
   struct PoseRelativeToGraph;
+  template <typename T> class ScopedGraph;
 
   /// \brief A Frame element descibes the properties associated with an
   /// explicit frame defined in a Model or World.
@@ -133,9 +134,8 @@ namespace sdf
     public: sdf::ElementPtr Element() const;
 
     /// \brief Resolve the attached-to body of this frame from the
-    /// FrameAttachedToGraph. If this is in a __model__ scope, it returns
-    /// the name of a link. In the world scope, it returns the name of a
-    /// model or the world.
+    /// FrameAttachedToGraph. Generally, it resolves to the name of a link, but
+    /// if it is in the world scope, it can resolve to "world".
     /// \param[out] _body Name of body to which this frame is attached.
     /// \return Errors.
     public: Errors ResolveAttachedToBody(std::string &_body) const;
@@ -145,19 +145,19 @@ namespace sdf
     /// \return SemanticPose object for this link.
     public: sdf::SemanticPose SemanticPose() const;
 
-    /// \brief Give a weak pointer to the FrameAttachedToGraph to be used
-    /// for resolving attached bodies. This is private and is intended to
-    /// be called by Model::Load or World::Load.
-    /// \param[in] _graph Weak pointer to FrameAttachedToGraph.
+    /// \brief Give a scoped FrameAttachedToGraph to be used for resolving
+    /// attached bodies. This is private and is intended to be called by
+    /// Model::Load or World::Load.
+    /// \param[in] _graph scoped FrameAttachedToGraph object.
     private: void SetFrameAttachedToGraph(
-        std::weak_ptr<const FrameAttachedToGraph> _graph);
+        sdf::ScopedGraph<FrameAttachedToGraph> _graph);
 
-    /// \brief Give a weak pointer to the PoseRelativeToGraph to be used
-    /// for resolving poses. This is private and is intended to be called by
-    /// Model::Load or World::Load.
-    /// \param[in] _graph Weak pointer to PoseRelativeToGraph.
+    /// \brief Give the scoped PoseRelativeToGraph to be used for resolving
+    /// poses. This is private and is intended to be called by Model::Load or
+    /// World::Load.
+    /// \param[in] _graph scoped PoseRelativeToGraph object.
     private: void SetPoseRelativeToGraph(
-        std::weak_ptr<const PoseRelativeToGraph> _graph);
+        sdf::ScopedGraph<PoseRelativeToGraph> _graph);
 
     /// \brief Allow Model::Load and World::Load to call SetPoseRelativeToGraph.
     friend class Model;

include/sdf/Joint.hh

@@ -37,6 +37,7 @@ namespace sdf
   class JointPrivate;
   struct FrameAttachedToGraph;
   struct PoseRelativeToGraph;
+  template <typename T> class ScopedGraph;
 
   /// \enum JointType
   /// \brief The set of joint types. INVALID indicates that joint type has
@@ -221,19 +222,18 @@ namespace sdf
     /// \return SemanticPose object for this link.
     public: sdf::SemanticPose SemanticPose() const;
 
-    /// \brief Give a weak pointer to the FrameAttachedToGraph to be used
-    /// for resolving parent and child link names. This is private and is
-    /// intended to be called by  Model::Load.
-    /// \param[in] _graph Weak pointer to FrameAttachedToGraph.
+    /// \brief Give the scoped FrameAttachedToGraph to be used for resolving
+    /// parent and child link names. This is private and is intended to be
+    /// called by Model::Load.
+    /// \param[in] _graph scoped FrameAttachedToGraph object.
     private: void SetFrameAttachedToGraph(
-        std::weak_ptr<const FrameAttachedToGraph> _graph);
+        sdf::ScopedGraph<FrameAttachedToGraph> _graph);
 
-    /// \brief Give a weak pointer to the PoseRelativeToGraph to be used
-    /// for resolving poses. This is private and is intended to be called by
-    /// Model::Load.
-    /// \param[in] _graph Weak pointer to PoseRelativeToGraph.
+    /// \brief Give the scoped PoseRelativeToGraph to be used for resolving
+    /// poses. This is private and is intended to be called by Model::Load.
+    /// \param[in] _graph scoped PoseRelativeToGraph object.
     private: void SetPoseRelativeToGraph(
-        std::weak_ptr<const PoseRelativeToGraph> _graph);
+        sdf::ScopedGraph<PoseRelativeToGraph> _graph);
 
     /// \brief Allow Model::Load to call SetPoseRelativeToGraph.
     friend class Model;

include/sdf/JointAxis.hh

@@ -35,6 +35,7 @@ namespace sdf
   // Forward declare private data class.
   class JointAxisPrivate;
   struct PoseRelativeToGraph;
+  template <typename T> class ScopedGraph;
 
   /// \brief Parameters related to the axis of rotation for rotational joints,
   /// and the axis of translation for prismatic joints.
@@ -269,12 +270,12 @@ namespace sdf
     /// \param[in] _xmlParentName Name of xml parent object.
     private: void SetXmlParentName(const std::string &_xmlParentName);
 
-    /// \brief Give a weak pointer to the PoseRelativeToGraph to be used
-    /// for resolving poses. This is private and is intended to be called
-    /// by Joint::SetPoseRelativeToGraph.
-    /// \param[in] _graph Weak pointer to PoseRelativeToGraph.
+    /// \brief Give the scoped PoseRelativeToGraph to be used for resolving
+    /// poses. This is private and is intended to be called by
+    /// Joint::SetPoseRelativeToGraph.
+    /// \param[in] _graph scoped PoseRelativeToGraph object.
     private: void SetPoseRelativeToGraph(
-        std::weak_ptr<const PoseRelativeToGraph> _graph);
+        sdf::ScopedGraph<PoseRelativeToGraph> _graph);
 
     /// \brief Allow Joint::SetPoseRelativeToGraph to propagate.
     friend class Joint;

include/sdf/Light.hh

@@ -37,6 +37,7 @@ namespace sdf
   // Forward declare private data class.
   class LightPrivate;
   struct PoseRelativeToGraph;
+  template <typename T> class ScopedGraph;
 
   /// \enum LightType
   /// \brief The set of light types. INVALID indicates that light type has
@@ -273,12 +274,12 @@ namespace sdf
     /// \param[in] _xmlParentName Name of xml parent object.
     private: void SetXmlParentName(const std::string &_xmlParentName);
 
-    /// \brief Give a weak pointer to the PoseRelativeToGraph to be used
-    /// for resolving poses. This is private and is intended to be called by
+    /// \brief Give the scoped PoseRelativeToGraph to be used for resolving
+    /// poses. This is private and is intended to be called by
     /// Link::SetPoseRelativeToGraph or World::Load.
-    /// \param[in] _graph Weak pointer to PoseRelativeToGraph.
+    /// \param[in] _graph scoped PoseRelativeToGraph object.
     private: void SetPoseRelativeToGraph(
-        std::weak_ptr<const PoseRelativeToGraph> _graph);
+        sdf::ScopedGraph<PoseRelativeToGraph> _graph);
 
     /// \brief Allow Link::SetPoseRelativeToGraph or World::Load to call
     /// SetXmlParentName and SetPoseRelativeToGraph,

include/sdf/Link.hh

@@ -40,6 +40,7 @@ namespace sdf
   class Visual;
   class LinkPrivate;
   struct PoseRelativeToGraph;
+  template <typename T> class ScopedGraph;
 
   class SDFORMAT_VISIBLE Link
   {
@@ -225,12 +226,11 @@ namespace sdf
     /// \return SemanticPose object for this link.
     public: sdf::SemanticPose SemanticPose() const;
 
-    /// \brief Give a weak pointer to the PoseRelativeToGraph to be used
-    /// for resolving poses. This is private and is intended to be called by
-    /// Model::Load.
-    /// \param[in] _graph Weak pointer to PoseRelativeToGraph.
+    /// \brief Give the scoped PoseRelativeToGraph to be used for resolving
+    /// poses. This is private and is intended to be called by Model::Load.
+    /// \param[in] _graph scoped PoseRelativeToGraph object.
     private: void SetPoseRelativeToGraph(
-        std::weak_ptr<const PoseRelativeToGraph> _graph);
+        sdf::ScopedGraph<PoseRelativeToGraph> _graph);
 
     /// \brief Allow Model::Load to call SetPoseRelativeToGraph.
     friend class Model;

include/sdf/Model.hh

@@ -39,6 +39,8 @@ namespace sdf
   class Link;
   class ModelPrivate;
   struct PoseRelativeToGraph;
+  struct FrameAttachedToGraph;
+  template <typename T> class ScopedGraph;
 
   class SDFORMAT_VISIBLE Model
   {
@@ -132,11 +134,14 @@ namespace sdf
     /// should be subject to wind.
     public: void SetEnableWind(bool _enableWind);
 
-    /// \brief Get the number of links.
+    /// \brief Get the number of links that are immediate (not nested) children
+    /// of this Model object.
+    /// \remark LinkByName() can find links that are not immediate children of
+    /// this Model object.
     /// \return Number of links contained in this Model object.
     public: uint64_t LinkCount() const;
 
-    /// \brief Get a link based on an index.
+    /// \brief Get an immediate (not nested) child link based on an index.
     /// \param[in] _index Index of the link. The index should be in the
     /// range [0..LinkCount()).
     /// \return Pointer to the link. Nullptr if the index does not exist.
@@ -157,11 +162,14 @@ namespace sdf
     /// \return True if there exists a link with the given name.
     public: bool LinkNameExists(const std::string &_name) const;
 
-    /// \brief Get the number of joints.
+    /// \brief Get the number of joints that are immediate (not nested) children
+    /// of this Model object.
+    /// \remark JointByName() can find joints that are not immediate children of
+    /// this Model object.
     /// \return Number of joints contained in this Model object.
     public: uint64_t JointCount() const;
 
-    /// \brief Get a joint based on an index.
+    /// \brief Get an immediate (not nested) child joint based on an index.
     /// \param[in] _index Index of the joint. The index should be in the
     /// range [0..JointCount()).
     /// \return Pointer to the joint. Nullptr if the index does not exist.
@@ -170,7 +178,7 @@ namespace sdf
 
     /// \brief Get whether a joint name exists.
     /// \param[in] _name Name of the joint to check.
-    /// To check for a joint in a nested model, prefix the link name with
+    /// To check for a joint in a nested model, prefix the joint name with
     /// the sequence of nested models containing this joint, delimited by "::".
     /// \return True if there exists a joint with the given name.
     public: bool JointNameExists(const std::string &_name) const;
@@ -184,11 +192,15 @@ namespace sdf
     /// \sa bool JointNameExists(const std::string &_name) const
     public: const Joint *JointByName(const std::string &_name) const;
 
-    /// \brief Get the number of explicit frames.
+    /// \brief Get the number of explicit frames that are immediate (not nested)
+    /// children of this Model object.
+    /// \remark FrameByName() can find explicit frames that are not immediate
+    /// children of this Model object.
     /// \return Number of explicit frames contained in this Model object.
     public: uint64_t FrameCount() const;
 
-    /// \brief Get an explicit frame based on an index.
+    /// \brief Get an immediate (not nested) child explicit frame based on an
+    /// index.
     /// \param[in] _index Index of the explicit frame. The index should be in
     /// the range [0..FrameCount()).
     /// \return Pointer to the explicit frame. Nullptr if the index does not
@@ -211,11 +223,15 @@ namespace sdf
     /// \return True if there exists an explicit frame with the given name.
     public: bool FrameNameExists(const std::string &_name) const;
 
-    /// \brief Get the number of nested models.
+    /// \brief Get the number of nested models that are immediate (not
+    /// recursively nested) children of this Model object.
+    /// \remark ModelByName() can find nested models that are not immediate
+    /// children of this Model object.
     /// \return Number of nested models contained in this Model object.
     public: uint64_t ModelCount() const;
 
-    /// \brief Get a nested model based on an index.
+    /// \brief Get an immediate (not recursively nested) child model based on an
+    /// index.
     /// \param[in] _index Index of the nested model. The index should be in the
     /// range [0..ModelCount()).
     /// \return Pointer to the model. Nullptr if the index does not exist.
@@ -298,13 +314,19 @@ namespace sdf
     /// \param[in] _name Name of the placement frame.
     public: void SetPlacementFrameName(const std::string &_name);
 
-    /// \brief Give a weak pointer to the PoseRelativeToGraph to be used
-    /// for resolving poses. This is private and is intended to be called by
+    /// \brief Give the scoped PoseRelativeToGraph to be used for resolving
+    /// poses. This is private and is intended to be called by World::Load and
+    /// Model::Load if this is a nested model.
+    /// \param[in] _graph scoped PoseRelativeToGraph object.
+    private: void SetPoseRelativeToGraph(
+        sdf::ScopedGraph<PoseRelativeToGraph> _graph);
+
+    /// \brief Give the scoped FrameAttachedToGraph to be used for resolving
+    /// attached bodies. This is private and is intended to be called by
     /// World::Load and Model::Load if this is a nested model.
-    /// \param[in] _graph Weak pointer to PoseRelativeToGraph.
-    /// \return Error if graph pointer is invalid.
-    private: sdf::Errors SetPoseRelativeToGraph(
-        std::weak_ptr<const PoseRelativeToGraph> _graph);
+    /// \param[in] _graph scoped FrameAttachedToGraph object.
+    private: void SetFrameAttachedToGraph(
+        sdf::ScopedGraph<FrameAttachedToGraph> _graph);
 
     /// \brief Get the model's canonical link and the nested name of the link
     /// relative to the current model, delimited by "::".
@@ -313,7 +335,8 @@ namespace sdf
     private: std::pair<const Link *, std::string> CanonicalLinkAndRelativeName()
         const;
 
-    /// \brief Allow World::Load to call SetPoseRelativeToGraph.
+    /// \brief Allow World::Load to call SetPoseRelativeToGraph and
+    /// SetFrameAttachedToGraph
     friend class World;
 
     /// \brief Allow helper function in FrameSemantics.cc to call

include/sdf/Root.hh

@@ -107,7 +107,8 @@ namespace sdf
     /// \return True if there exists a world with the given name.
     public: bool WorldNameExists(const std::string &_name) const;
 
-    /// \brief Get the number of models.
+    /// \brief Get the number of models that are immediate (not nested) children
+    /// of this Root object.
     /// \return Number of models contained in this Root object.
     public: uint64_t ModelCount() const;
 

include/sdf/SemanticPose.hh

@@ -42,6 +42,7 @@ namespace sdf
   // Forward declare private data class.
   class SemanticPosePrivate;
   struct PoseRelativeToGraph;
+  template <typename T> class ScopedGraph;
 
   /// \brief SemanticPose is a data structure that can be used by different
   /// DOM objects to resolve poses on a PoseRelativeToGraph. This object holds
@@ -78,12 +79,30 @@ namespace sdf
     /// raw pose is applied.
     /// \param[in] _defaultResolveTo Default frame to resolve-to in Resolve()
     /// if no frame is specified.
-    /// \param[in] _graph Weak pointer to PoseRelativeToGraph.
+    /// \param[in] _graph A scoped PoseRelativeToGraph object.
     private: SemanticPose(
         const ignition::math::Pose3d &_pose,
         const std::string &_relativeTo,
         const std::string &_defaultResolveTo,
-        std::weak_ptr<const sdf::PoseRelativeToGraph> _graph);
+        const sdf::ScopedGraph<sdf::PoseRelativeToGraph> &_graph);
+
+    /// \brief Private constructor that is used by object that represent a frame
+    /// in the PoseRelativeTo graph. Examples are Model, Frame, Link and not
+    /// Collision or Visual.
+    /// \param[in] _name Name of object. This should also be the name of the
+    /// frame represented by this object in the PoseRelativeTo graph.
+    /// \param[in] _pose Raw pose of object.
+    /// \param[in] _relativeTo Name of frame in graph relative-to which the
+    /// raw pose is applied.
+    /// \param[in] _defaultResolveTo Default frame to resolve-to in Resolve()
+    /// if no frame is specified.
+    /// \param[in] _graph A scoped PoseRelativeToGraph object.
+    private: SemanticPose(
+        const std::string &_name,
+        const ignition::math::Pose3d &_pose,
+        const std::string &_relativeTo,
+        const std::string &_defaultResolveTo,
+        const sdf::ScopedGraph<sdf::PoseRelativeToGraph> &_graph);
 
     /// \brief Destructor
     public: ~SemanticPose();