idyntree icon indicating copy to clipboard operation
idyntree copied to clipboard

Clarify getRelativeJacobian semantics in documentation

Open traversaro opened this issue 3 years ago • 1 comments

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

traversaro avatar Aug 21 '21 17:08 traversaro

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

HosameldinMohamed avatar Jan 26 '22 16:01 HosameldinMohamed