search

gazebosim / sdformat

Simulation Description Format (SDFormat) parser and description files.
http://sdformat.org
Apache License 2.0
164 stars 92 forks source link

Update documentation on joints' frames specifying defaults and conventions #170

Closed osrf-migration closed 7 months ago

osrf-migration commented 6 years ago

Original report (archived issue) by Alejandro Castro (Bitbucket: amcastro0622).

Reading the documentation for an SDF's joint axis here I had the following questions:

  1. use_parent_model_frame=true means...? the <model> frame I believe, could it be confirmed? the word "parent" overloads with "parent body" in the same <joint> doc and thus the confusion.
  2. use_parent_model_frame=false means... the "joint frame". How is this "joint frame" defined? where is the origin of this joint frame?

In version 1.6 the documentation for does not state the default when the <pose> itself or the <frame> in which this pose is measured, are not specified. However, version 1.4 doc does state that the default is the identity transform "in the child link frame" (ala urdf, makes sense).

The questions are:

  1. Why didn't this doc make it to 1.6. Clearly default pose and frames need to be stated for a non-ambiguous description.
  2. Unless the convention changed in 1.6?

It seems that, in current version 1.6 an old issue, 494, is mentioned. Is that fully resolved?

Finally, nothing is said about the joint frame on the "parent" body. It'd seem that the implicit convention is that this frame gets defined by making it coincident with the frame on the child body (referred to as, I believe, the "joint frame"). If this is true, it should be explicitly stated somewhere. If not, the documentation should be updated to reflect the actual convention.

osrf-migration commented 6 years ago

Original comment by Louise Poubel (Bitbucket: chapulina, GitHub: chapulina).

  1. Yes, use_parent_model_frame=true means the immediate parent <model>'s frame (not a grandparent <model> for example)
  2. use_parent_model_frame=false means the joint's child link frame

Regarding the "joint frame on the parent body", two details might make this clearer:

  1. The joint pose only defines the position of the constraint the moment the joint is created
  2. SDF defines a graph, not a tree

I think we lost a lot of documentation details since we started including pose.sdf into files.

osrf-migration commented 6 years ago

Original comment by Alejandro Castro (Bitbucket: amcastro0622).

Let me ellaborate on the kind of documentation we'd like so see with a schematic I put together. Generally, the model we are developing in Drake is predicated on the schematic I show below (yes, I need to upload that into master sometime soon!). In that schematic I show two bodies; a parent body with frame P (not necessarily at its center of mass) and a child body with a frame C (not necessarily either at its center of mass). In SDF terms, the "inertial" frames are Pcm and Ccm respectively, not necessarily (as said before) located at the body's frame's origins nor aligned with them. Now, if we place a joint between those two frames, generally we define a frame Jp rigidly attached on body P (that is, pose X_PJp of frame Jp in P is fixed) and a frame Jc rigidly attached on body C (that is, pose X_CJc is of frame Jc in C fixed). That joint has a state, here represented with q, and the pose of frame Jc in Jp, X_JpJc(q) is a function of that state. Since Jp is fixed in P and Jc is fixed in C, this in turns defines the pose of C in P.

Special cases:

  1. Frame C "is" coincident with frame Jc (this is the typical case in urdf)
  2. Frame P (or C) is coincident with Pcm (or Ccm).

Hopefully that'll help aid the discussion. Now, we'd like to know exactly how the sdf format defines its frames and its defaults values so that we can, unambiguously, map to our representation. We hope this can be done by expanding the documentation now provided and that this documentation can also help others. Thoughts?

joint_frames.png

osrf-migration commented 6 years ago

Original comment by Alejandro Castro (Bitbucket: amcastro0622).

Ah, I hadn't refreshed my browser yet buy when I made the second comment. Thank you for your reply @chapulina, does the schematic help understand what we are asking for?

osrf-migration commented 6 years ago

Original comment by Louise Poubel (Bitbucket: chapulina, GitHub: chapulina).

Yes, I can see where you're coming from.

A world SDF description is meant to describe the simulation's initial state. Updates to the state are given by <state> tags.

One single pose is enough to define a joint's (constraint) initial location. By convention, that was chosen to be the pose with respect to the child link.

So it seems to me that in your use case, you should interpret the joint pose as Jc and mathematically deduce Jp to store it in your internal representation. As far as SDF is concerned, the joint can't be broken, that is, the joint pose can't change with time with respect to any of the links.

Here's an example playing with Gazebo's model editor. The box is the parent link and the sphere is the child link. The large axes represent the joint frame. The joint is revolute, and the revolute axis is represented by a yellow circle. You can see how the joint pose is described with respect to the child, and since you know both link poses, you could deduce the joint pose in the parent link frame.

jointcreation.gif

osrf-migration commented 6 years ago

Original comment by Michael Sherman (Bitbucket: sherm1).

When John Hsu and I were working on incorporating Simbody into Gazebo, John extended sdf to optionally allow specification of both the parent joint frame (Jp in Alejandro's diagram) and the child joint frame (Jc). I'm not sure that every made it into the official sdf schema though. Being able to specify both is very useful when building a non-tree system because placing every link so that joint constraints are satisfied is very difficult in that case. In any case it would be great if the documentation could show the general case for an unassembled joint (as in Alejandro's picture), and then explains how sdf's input maps into those frames.

osrf-migration commented 6 years ago

Original comment by Louise Poubel (Bitbucket: chapulina, GitHub: chapulina).

As far as I can tell, it has never been possible to describe an unassembled joint on SDF, so my guess is that it never made it into the schema.

A more recent development added an optional frame of reference to every pose (pull request #237), so that any element could be defined with respect to any other element. This would hopefully make it easier to place links and joints. Note that Gazebo doesn't use that frame information yet, so there isn't a "reference implementation" of exactly how they should be used, and the documentation is probably vague.

osrf-migration commented 6 years ago

Original comment by Alejandro Castro (Bitbucket: amcastro0622).

Thank you so much for your help @chapulina. It'd seem the sdf format gives us a number of different options to specify frames and to specify in what frame a particular quantity (say a joint axis) is specified in. So far, we found ourselves resolving what combinations are allowed not by going to the documentation, but by essentially loading a particular SDF in Gazebo. If it loads, good and if not, well, we assume that is not allowed. You can see one of these iterations in Drake here.

This issue is not about asking for a new feature not even about modifying an existing one. This issue is essentially about formally dumping in the official SDF documentation all this valuable information that experienced developers like you, how have worked with this format for a long time, know about but that of course, most users don't. Probably a schematic similar to what I show above (though of course with whichever SDF's notation prefers) would be best to define frames.

Remark I: In the one issue #124 you directed me above, the reporter also thought, erroneously, that use_parent_model_frame was about specifying the joint in the parent line frame . I think that could also be clarified in the documentation.

Remark II: Jp, Jc are do not denote poses but they denote frames, the actual physical objects. These can exist in our physical world even before we decide to make any measurements of their position in other frame. We denote poses (others call them transforms and see them as a little 4x4 homogeneous transform matrix) as the position and orientation of given frame in another frame (so you need two frames to specify a pose). We denote those with a capital X with superscripts denoting the frames. For instance, a position vector expressed in a frame A can be transformed to be expressed in frame B using p_B = ᴮXᴬ * p_A (sorry for the bad mix of Latex and unicode).

osrf-migration commented 6 years ago

Original comment by Alejandro Castro (Bitbucket: amcastro0622).

osrf-migration commented 6 years ago

Original comment by Carlos Agüero (Bitbucket: caguero, GitHub: caguero).

Update: pull request #383 should fix the absence of some of the default values (original issue #101).

osrf-migration commented 6 years ago

Original comment by Alejandro Castro (Bitbucket: amcastro0622).

Thanks! I added a comment in #171 which I believe also apply to this issue.

scpeters commented 7 months ago

this documentation is now available at http://sdformat.org/tutorials?tut=pose_frame_semantics&cat=specification&