Rename CanonicalLink to RootLink (#234)

This deprecates the end-user facing function CanonicalLink and adds a new one called RootLink. This also replaces `ignition::physics::FindFreeGroupFeature::Implementation::GetFreeGroupCanonicalLink` 
with `ignition::physics::FindFreeGroupFeature::Implementation::GetFreeGroupRootLink`.

Signed-off-by: Addisu Z. Taddese <addisu@openrobotics.org>

Migration.md

@@ -13,6 +13,15 @@ release will remove the deprecated code.
 
 1. Depends on sdformat11.
 
+1. `ignition::physics::FindFreeGroupFeature::Implementation::GetFreeGroupCanonicalLink` 
+   has been replaced by `ignition::physics::FindFreeGroupFeature::Implementation::GetFreeGroupRootLink`.
+
+### Deprecations
+
+1. **physics/FreeGroup.hh**
+    + **Deprecation:** `Identity ignition::physics::FreeGroup::CanonicalLink(const Identity &_groupID)`
+    + **Replacement:** `Identity ignition::physics::FreeGroup::RootLink(const Identity &_groupID)`
+
 ## Ignition Physics 2.X to 3.X
 
 ### Modifications

dartsim/src/FreeGroupFeatures.cc

@@ -82,8 +82,7 @@ Identity FreeGroupFeatures::FindFreeGroupForLink(
 }
 
 /////////////////////////////////////////////////
-Identity FreeGroupFeatures::GetFreeGroupCanonicalLink(
-    const Identity &_groupID) const
+Identity FreeGroupFeatures::GetFreeGroupRootLink(const Identity &_groupID) const
 {
   const FreeGroupInfo &info = GetCanonicalInfo(_groupID);
   return this->GenerateIdentity(this->links.IdentityOf(info.link));

dartsim/src/FreeGroupFeatures.hh

@@ -42,11 +42,11 @@ class FreeGroupFeatures
 
   Identity FindFreeGroupForLink(const Identity &_linkID) const override;
 
-  Identity GetFreeGroupCanonicalLink(const Identity &_groupID) const override;
+  Identity GetFreeGroupRootLink(const Identity &_groupID) const override;
 
   struct FreeGroupInfo
   {
-    /// \brief Pointer to the canonical link
+    /// \brief Pointer to the root link
     DartBodyNode *link;
 
     /// \brief If the FreeGroup is wrapping an entire model, then this will

include/ignition/physics/FreeGroup.hh

@@ -77,13 +77,26 @@ namespace ignition
       public: template <typename PolicyT, typename FeaturesT>
       class FreeGroup : public virtual Entity<PolicyT, FeaturesT>
       {
-        /// \brief The canonical link of this FreeGroup. Getting and setting
-        /// properties (like poses and velocities) on the group will be done
-        /// in terms of this link.
-        public: LinkPtr<PolicyT, FeaturesT> CanonicalLink();
+        /// \brief The root link of this FreeGroup. This link is the root of one
+        /// of the kinematic trees represented by this FreeGroup. Getting and
+        /// setting properties (like poses and velocities) on the group will be
+        /// done in terms of this link.
+        public: LinkPtr<PolicyT, FeaturesT> RootLink();
+
+        /// \brief const version of RootLink()
+        public: ConstLinkPtr<PolicyT, FeaturesT> RootLink() const;
+
+        /// \brief The root link of this FreeGroup. This link is the root of one
+        /// of the kinematic trees represented by this FreeGroup. Getting and
+        /// setting properties (like poses and velocities) on the group will be
+        /// done in terms of this link.
+        /// DEPRECATED. Please use RootLink()
+        public: LinkPtr<PolicyT, FeaturesT> IGN_DEPRECATED(4.0) CanonicalLink();
 
         /// \brief const version of CanonicalLink()
-        public: ConstLinkPtr<PolicyT, FeaturesT> CanonicalLink() const;
+        /// DEPRECATED. Please use RootLink()
+        public: ConstLinkPtr<PolicyT, FeaturesT> IGN_DEPRECATED(4.0)
+                    CanonicalLink() const;
       };
 
       public: template <typename PolicyT>
@@ -95,7 +108,7 @@ namespace ignition
         public: virtual Identity FindFreeGroupForLink(
             const Identity &_linkID) const = 0;
 
-        public: virtual Identity GetFreeGroupCanonicalLink(
+        public: virtual Identity GetFreeGroupRootLink(
             const Identity &_groupID) const = 0;
       };
     };

include/ignition/physics/detail/FreeGroup.hh

@@ -67,21 +67,37 @@ namespace ignition
     /////////////////////////////////////////////////
     template <typename PolicyT, typename FeaturesT>
     LinkPtr<PolicyT, FeaturesT>
-    FindFreeGroupFeature::FreeGroup<PolicyT, FeaturesT>::CanonicalLink()
+    FindFreeGroupFeature::FreeGroup<PolicyT, FeaturesT>::RootLink()
     {
       return LinkPtr<PolicyT, FeaturesT>(this->pimpl,
         this->template Interface<FindFreeGroupFeature>()
-          ->GetFreeGroupCanonicalLink(this->identity));
+          ->GetFreeGroupRootLink(this->identity));
     }
 
     /////////////////////////////////////////////////
     template <typename PolicyT, typename FeaturesT>
-    ConstLinkPtr<PolicyT, FeaturesT>
-    FindFreeGroupFeature::FreeGroup<PolicyT, FeaturesT>::CanonicalLink() const
+    ConstLinkPtr<PolicyT, FeaturesT> FindFreeGroupFeature::FreeGroup<
+        PolicyT, FeaturesT>::RootLink() const
     {
       return LinkPtr<PolicyT, FeaturesT>(this->pimpl,
         this->template Interface<FindFreeGroupFeature>()
-          ->GetFreeGroupCanonicalLink(this->identity));
+          ->GetFreeGroupRootLink(this->identity));
+    }
+
+    /////////////////////////////////////////////////
+    template <typename PolicyT, typename FeaturesT>
+    LinkPtr<PolicyT, FeaturesT>
+    FindFreeGroupFeature::FreeGroup<PolicyT, FeaturesT>::CanonicalLink()
+    {
+      return this->RootLink();
+    }
+
+    /////////////////////////////////////////////////
+    template <typename PolicyT, typename FeaturesT>
+    ConstLinkPtr<PolicyT, FeaturesT>
+    FindFreeGroupFeature::FreeGroup<PolicyT, FeaturesT>::CanonicalLink() const
+    {
+      return this->RootLink();
     }
 
     /////////////////////////////////////////////////

tpe/plugin/src/FreeGroupFeatures.cc

@@ -54,8 +54,7 @@ Identity FreeGroupFeatures::FindFreeGroupForLink(
 }
 
 /////////////////////////////////////////////////
-Identity FreeGroupFeatures::GetFreeGroupCanonicalLink(
-  const Identity &_groupID) const
+Identity FreeGroupFeatures::GetFreeGroupRootLink(const Identity &_groupID) const
 {
   // assume no canonical link for now
   // assume groupID ~= modelID

tpe/plugin/src/FreeGroupFeatures.hh

@@ -41,7 +41,7 @@ class FreeGroupFeatures :
 
   Identity FindFreeGroupForLink(const Identity &_linkID) const override;
 
-  Identity GetFreeGroupCanonicalLink(const Identity &_groupID) const override;
+  Identity GetFreeGroupRootLink(const Identity &_groupID) const override;
 
   void SetFreeGroupWorldPose(
     const Identity &_groupID,

tpe/plugin/src/SimulationFeatures_TEST.cc

@@ -21,6 +21,7 @@
 #include <ignition/math/Vector3.hh>
 #include <ignition/math/eigen3/Conversions.hh>
 
+#include <ignition/utils/SuppressWarning.hh>
 #include <ignition/plugin/Loader.hh>
 
 // Features
@@ -257,7 +258,10 @@ TEST_P(SimulationFeatures_TEST, FreeGroup)
     auto model = world->GetModel("sphere");
     auto freeGroup = model->FindFreeGroup();
     ASSERT_NE(nullptr, freeGroup);
+    IGN_UTILS_WARN_IGNORE__DEPRECATED_DECLARATION
     ASSERT_NE(nullptr, freeGroup->CanonicalLink());
+    IGN_UTILS_WARN_RESUME__DEPRECATED_DECLARATION
+    ASSERT_NE(nullptr, freeGroup->RootLink());
 
     auto link = model->GetLink("sphere_link");
     auto freeGroupLink = link->FindFreeGroup();