[Question] Need some clarity on reference frames usage in ArticulationData

[kbkartik]

Question

newbie to sim2real world. I am trying to understand how reference frames are setup in ArticulationData. My doubt is w.r.t the following 6 methods:

1. root_link_state_w()
2. root_com_state_w()
3. body_link_state_w()
4. body_com_state_w()
5. com_pos_b()
6. com_quat_b()
7. root_com_lin_vel_b()
8. root_com_ang_vel_b()

Among all these methods, I am seeing multiple definitions of reference frame such as:

1. simulation world frame
2. body frame
3. center of mass frame
4. actor frame
5. orientation of principle inertia (or principle axes of inertia)

I know what reference frames are. What I don't understand is how its setup in IsaacLab? For instance,

1. Why do we adjust linear velocity in root_link_state_w() and (pos, quat) in root_com_state_w()?
2. Why do we use com_pos_b and com_quat_b in root_link_state_w() and root_com_state_w()? Are we transforming from body frame to world frame?
3. Why do we do update_articulations_kinematics() in body_link_state_w() and body_com_state_w()?
4. What is the mapping/ordering of bodies in body_link_state_w/body_com_state_w's shape: (num_instances, num_bodies, 13)?
5. In root_com_lin_vel_b() and root_com_ang_vel_b(), why are we using root_link_quat_w to inverse rotate root_com_lin_vel_b and root_com_ang_vel_b? Shouldn't we be using root_com_quat_w? Is this a bug?

Some clarity on the above questions will definitely be helpful to understand the code and the documentations.

best,
kb

[RandomOakForest]

Thank you for submitting these questions. We are working on improving our documentation. I will move this to a discussion for the team to follow up.

[StrainFlow]

Great questions, I've had similar trouble with the clarity of these functions. I'm going to try clarifying these in the documentation. Would you mind if I shared links to the revisions as I go and have you proof read them for me for clarity? Once they're all clear we can submit a PR. This is an open discussion as well, so I would welcome feedback from anyone else as we go.

[kbkartik]

Works with me!

[RandomOakForest]

In a note to give some context, the physics engine provides us pose data in link frame and velocity data in com frame. Anything that has link in the name is in link frame. For velocities, we do the transformation under the hood to convert from com frame to link frame. Similar idea for APIs that have com in the name.