robotology / idyntree

Multibody Dynamics Library designed for Free Floating Robots
BSD 3-Clause "New" or "Revised" License
176 stars 67 forks source link

Clarify getRelativeJacobian semantics in documentation #912

Open traversaro opened 3 years ago

traversaro commented 3 years ago

Currently, the dcs of getRelativejacobian do not clarify in which frame the velocity obtained multipling the relative jacobian by the internal joint velocity vector is expressed, and it only say "w.r.t. frame expressed depending on the velocity representation", see https://github.com/robotology/idyntree/blob/f9051752ca5a6ca8f3a4f101e4a536fe1eb62c5f/src/high-level/include/iDynTree/KinDynComputations.h#L708 . the actual semantics is documented only in the code itself in https://github.com/robotology/idyntree/blob/f9051752ca5a6ca8f3a4f101e4a536fe1eb62c5f/src/high-level/src/KinDynComputations.cpp#L1690 . In particular, the semantics is (if we call $R$ the referenceFrame and $F$ the frame, and we use the notation from https://research.tue.nl/en/publications/multibody-dynamics-notation-version-2):

getFrameVelocityRepresentation value getRelativeJacobian semantics
MIXED_REPRESENTATION (default) ${}^{F[R]} \mathrm{v}_{R,F} = J_{R,F}^{rel} \dot{s}$
INERTIAL_FIXED_REPRESENTATION ${}^{R} \mathrm{v}_{R,F} = J_{R,F}^{rel} \dot{s}$
BODY_FIXED_REPRESENTATION ${}^{F} \mathrm{v}_{R,F} = J_{R,F}^{rel} \dot{s}$

If this is not document, this is extremly confusing especially in the INERTIAL_FIXED_REPRESENTATION case, as in that case "inertial-fixed representaton" is used a synonime for "right-trivialized representation", that is true for the absolute velocity, but that is misleading for the relative velocity, as in that case the velocity is expressed in the reference frame $R$ instead of the inertial-fixed frame.

Related issues: https://github.com/robotology/idyntree/issues/395, https://github.com/robotology/wb-toolbox/issues/225#issuecomment-903143803 .

cc @HosameldinMohamed @Giulero

HosameldinMohamed commented 2 years ago

@traversaro I'll try to address this, can you give me some pointers?