Intelligent Coordinates Docu

etc/doxygen/pages/armarpose.dox

+/**
+\defgroup RobotAPI-ArmarPose Intelligent Coordinates
+\ingroup RobotAPI
+
+ArmarX contains a concept for Intelligent Coordinates that eases transformation
+into different coordinate frames. Here, we mean with coordinates \ref armarx::Vector3 "positions",
+\ref armarx::Quaternion "orientation", and \ref armarx::Pose "poses".
+These Intelligent Coordinates exist in 3 levels of "intelligence".
+- The first level are just normal coordinates. They do not contain any information how to transform them in
+other coordinate frames (e.g. \ref armarx::Pose Pose).
+- The second level is are the FramedCoordinates (e.g. \ref armarx::FramedPose "FramedPose"). These contain
+the name and the agent of frame in which they currently are. To convert these the changeFrame() function
+can be called. One needs to give the new frame and the \ref armarx::SharedRobotInterface "robot proxy" to this
+function.
+- The third level are the LinkedCoordinates (e.g. \ref armarx::LinkedPose "LinkedPose"), which contain all the information needed to do frame transformations.
+
+\section ArmarPose-FramedPositionCreation Creation of new FramedPositions
+To create a new FramedPosition (FramedOrientation, FramedVector and FramedPose work analogously) one needs
+to know the Position, the coordinate frame name and the agent name.
+The coordinate frame is usually the name of the RobotNode, e.g. the tcp of the robot.
+The agent name can be retrieved via the \ref armarx::RobotStateComponent like this:
+
+\code
+    SharedRobotInterfacePrx robot = robotStateInterfacePrx->getSynchronizedRobot();
+    agentName = robot->getName();
+\endcode
+So an example code for creating a new FramedPosition looks like this:
+
+\code
+    RobotStateComponentInterfacePrx robotStateInterfacePrx = ....; // you need to have this proxy
+    SharedRobotInterfacePrx robot = robotStateInterfacePrx->getSynchronizedRobot();
+    agentName = robot->getName();
+    std::string frame = root->getRoot()->getName();
+    Eigen::Vector3f pos;
+    pos << 100, 0, 0;
+    armarx::FramedPositionPtr position = new armarx::FramedPosition(pos, frame, agentName);
+\endcode
+
+\section ArmarPose-ChangeFrame Change the frame of an FramedPosition
+In ArmarX the most common coordinate type is the FramedX, e.g. FramedPosition.
+To change the frame in this coordinate type, you can call \ref armarx::FramedPosition::changeFrame "changeFrame()" on the FramedPosition.
+You need to know the new frame, in which you want to have the
+FramedPosition and a proxy to the \ref armarx::SharedRobotInterface "robot proxy" (e.g. \ref \ref armarx::RobotStateComponent::getSynchronizedRobot):
+
+\code
+    armarx::RobotStateComponentInterfacePrx robotStateInterfacePrx = ....; // you need to have this proxy
+    armarx::SharedRobotInterfacePrx robot = robotStateInterfacePrx->getSynchronizedRobot();
+    agentName = robot->getName();
+    std::string frame = root->getRoot()->getName();
+    Eigen::Vector3f pos;
+    pos << 100, 0, 0;
+    armarx::FramedPositionPtr position = new armarx::FramedPosition(pos, frame, agentName);
+
+    position->changeFrame(robot, "TCP L");
+\endcode
+
+*/

source/RobotAPI/libraries/robotstate/remote/ArmarPose.h

@@ -60,6 +60,7 @@ namespace armarx
     /**
      * @class Vector3
      * @ingroup Variants
+     * @ingroup RobotAPI-ArmarPose
      * @brief The Vector3 class
      */
     class Vector3 :
@@ -124,6 +125,7 @@ namespace armarx
     /**
      * @class Quaternion
      * @ingroup Variants
+     * @ingroup RobotAPI-ArmarPose
      * @brief The Quaternion class
      */
     class Quaternion :
@@ -207,6 +209,7 @@ namespace armarx
     /**
      * @class Pose
      * @ingroup Variants
+     * @ingroup RobotAPI-ArmarPose
      * @brief The Pose class
      */
     class Pose :
@@ -282,6 +285,7 @@ namespace armarx
     /**
      * @class FramedPose
      * @ingroup Variants
+     * @ingroup RobotAPI-ArmarPose
      * @brief The FramedPose class
      */
     class FramedPose :
@@ -353,12 +357,13 @@ namespace armarx
 
     /**
      * @class FramedVector3
-     * @brief FramedVector3 is a 3 dimensional vector with a reference frame.
+     * @ingroup RobotAPI-ArmarPose
      * @ingroup Variants
+     * @brief FramedVector3 is a 3 dimensional @b direction vector with a reference frame.
      * The reference frame can be used to change the coordinate system to which
-     * the vector relates. The difference to a framed position is, that on frame
-     * changing only the orientation of the vector is changed. The translation
-     * part remains unchanged. This class is usefull e.g. for forces, torques and tcp
+     * the vector relates. The difference to a FramedPosition is, that on frame
+     * changing only the orientation of the vector is changed. The length of the vector
+     * remains unchanged. This class is usefull e.g. for forces and tcp
      * velocities.
      *
      * @see Vector3, FramedPosition
@@ -434,6 +439,7 @@ namespace armarx
     /**
      * @class FramedPosition
      * @ingroup Variants
+     * @ingroup RobotAPI-ArmarPose
      * @brief The FramedPosition class
      */
     class FramedPosition :
@@ -503,6 +509,7 @@ namespace armarx
     /**
      * @class FramedOrientation
      * @ingroup Variants
+     * @ingroup RobotAPI-ArmarPose
      * @brief The FramedOrientation class
      */
     class FramedOrientation :

source/RobotAPI/libraries/robotstate/remote/LinkedPose.h

@@ -53,6 +53,7 @@ namespace armarx
     /**
      * @class LinkedPose
      * @ingroup Variants
+     * @ingroup RobotAPI-ArmarPose
      * @brief The LinkedPose class
      */
     class LinkedPose :
@@ -142,6 +143,7 @@ namespace armarx
      * @class LinkedVector3 is a direction vector (NOT a position vector) with an attached robotstate proxy
      * for frame changes.
      * @ingroup Variants
+     * @ingroup RobotAPI-ArmarPose
      * @brief The LinkedVector3 class
      */
     class LinkedVector3 :