Joint model lack of documentation about pinocchio HOT 5 CLOSED

I want to add that in general, there is no real Documention inside Pinocchio. The current documentation is given partially in the doc directory and the Featherstone's Rigid Body Dynamics book. Then, there are also the tutorials that can provide good intuitions about the framework.

We plan to add a complete documentation of Pinocchio in the future. We are working on improving it.
If you need a precise information, don't hesitate to ask us.

Concerning the previous point, we have followed the convention given by Featherstone for minimal computation in the context of the free flyer joint (translation+rotation).

from pinocchio.

Hello,

I agree with your remark. More doc would be nice. In particular, the
joint implementations are not clear. Documentation are needed at two levels:

• on the code structure, the joints are not following a strict
  standardized implementation. This might be enforced and documented using
  the CRTP. Florian started to implement this standard, but the work is
  not achieved yet.
• on the mathematical level, it would be nice to have the equations of
  the model in the header of each joint**.hpp. I am not sure how to
  implement that documentation in a nice Doxygen format: a smart solution
  certainly exists and would be the most satisfactory.

Here are some elements of documentation.

• In pinocchio/doc/latex/se3.tex, you have a small memo about the
  convention that are used in the code. It is not strictly speaking the
  convention of Featherstone (cf the se3.tex for details).
• In JointFreeFlyer:
  -> the configuration of the joint is (x,y,z,q1,q2,q3,q4), with
  p=(x,y,z) the position of the center of the first body in the world and
  r=(q1,q2,q3,q4) the quaternion giving the orientation of the first body
  in the world frame. The kinematic map (from joint configuration to body
  placement) is therefore:
  K: q=(p,r) -> M = [ R(r) p ; 0 1 ] = ^0M_1
  with R(r) the exponential map from quaternion to rotation matrix.
  -> The velocity (tangent vector to q) is the spatial velocity of
  the center of the first body in the frame of the first body expressed at
  the center of the first body:
  ^1vu_1 = ( ^1v_1 ; ^1\omega )
  with ^1v_1 the linear (3D) velocity of the first body in the frame of
  the first body. Note that you can pass from this spatial velocity to the
  one expressed at the center of the world in the frame of the world, by
  pre-multiplying by the action matrix associated with ^0M_1. Note also
  that classical mechanics would be interested by the linear velocity of
  the first body expressed at the center of the first body expressed in
  the world frame:
  ^0v_1 = ^0R_1 ^1v_1
  -> The joint Jacobian (i.e. tangent map to K) is simply the identity.

Possibly, you will find this explanation satisfactory. Would you then
volunteer to integrate it in JointFreeFlyer.hpp under a Doxygen format?
Alternatively, please feedback so that I can explain more. I can also
give a quick class on that topic by Skype if you want (I would even be
very enthusiastic to do so if you then volunteer to transcript the class
as a proper doc).

Nico

On 11/27/2015 05:06 PM, Justin Carpentier wrote:

I want to add that in general, there is no real Documention inside
Pinocchio. The current documentation is given partially in doc and the
Featherstone's Rigid Body Dynamics book. Then, there is also the
tutorials that can provide good intuitions about the framework.

We plan to add a complete documentation of Pinocchio in the future,
but it is not our priority now.
If you need a precise information, don't hesitate to ask us.

Concerning the previous point, we have followed the convention given
by Featherstone for minimal computation in the context of the free
flyer joint (translation+rotation)

—
Reply to this email directly or view it on GitHub
#65 (comment).

from pinocchio.

@nmansard Thanks for the clear explanation!

Regarding doxygen documentation, it is straightforward to write tex formulas in the comments (See here)
They are then interpreted on-the-fly by mathjax if you enable it.

I can take care of documenting the freeflyer, but I cannot sadly give a concrete target date given my tight schedule.

from pinocchio.

On 12/01/2015 12:37 PM, Antonio El Khoury wrote:

Regarding doxygen documentation, it is straightforward to write tex
formulas in the comments (See here
https://www.stack.nl/%7Edimitri/doxygen/manual/formulas.html)

They are then interpreted on-the-fly by mathjax if you enable it.

Agreed. I was more precisely discussing the complexity of the actual
Doxygen of Pinocchio, due in part to the CRTP. Typically, should we put
the math model of JointFF in the class JointModelFreeFlyer, or in
JointDataFreeFlyer? Or in JointFreeFlyer, which is a void class?

N

from pinocchio.

I would say JointModelFreeFlyer, but I'm not sure yet. A good rule of thumb would be to put it where it appears the fastest to a lambda user building a robot model, either "by hand" or through an existing parser.

from pinocchio.