Documentation of pose/@relative_to syntax.

[FirefoxMetzger]

I found a SDF in the unit tests that features a bit of a strange @relative_to mechanism. @relative_to links are specified using a format like M1::CM1::L, which I assume denotes a nested frame similar to C++ namespace nesting? I find this a bit surprising because none of the documentation I have seen so far suggests that :: has special meaning and I expected that A::B should just be any old frame.

Would it be worthwhile to add a sentence in the docs saying that the frame must be specified relative to document root using the C++ namespace syntax, e.g. model1::link2::frame3?

SDF with namespace-like syntax

<?xml version="1.0" ?>
<sdf version='1.8'>
  <world name="world_relative_to_nested_reference">
    <model name="M1">
      <pose>1 0 0 0 1.5707963267948966 0</pose>
      <link name="L1">
        <pose>0 1 0 0 0 0</pose>
      </link>
      <joint name="J1" type="fixed">
        <parent>L1</parent>
        <child>L2</child>
      </joint>
      <link name="L2">
        <pose>0 0 1 0 0 0</pose>
      </link>
      <frame name="F1">
        <pose relative_to="L2">1 0 0 0 0 0</pose>
      </frame>
      <model name="CM1">
        <pose>0 1 0 1.5707963267948966 0 0</pose>
        <link name="L">
          <pose>1 0 0 0 -1.5707963267948966 0</pose>
        </link>
      </model>
    </model>
    <frame name="F2">
      <pose relative_to="M1">2 0 0 0 0 0</pose>
    </frame>
    <frame name="F3">
      <pose relative_to="M1::L1">3 0 0 0 0 0</pose>
    </frame>
    <frame name="F4">
      <pose relative_to="M1::J1">4 0 0 0 0 0</pose>
    </frame>
    <frame name="F5">
      <pose relative_to="M1::F1">5 0 0 0 0 0</pose>
    </frame>
    <frame name="F6">
      <pose relative_to="M1::CM1">6 0 0 0 0 0</pose>
    </frame>
    <frame name="F7">
      <pose relative_to="M1::CM1::L">7 0 0 0 0 0</pose>
    </frame>
  </world>
</sdf>

[azeey]

The :: delimiter was reserved as of SDFormat 1.8 (http://sdformat.org/tutorials?tut=composition_proposal&cat=pose_semantics_docs&#1-3-1-reserved-delimiter-token) although it has been in use by Gazebo classic long before that. As of SDFormat 1.8, names cannot have :: in them.

Would it be worthwhile to add a sentence in the docs saying that the frame must be specified relative to document root using the C++ namespace syntax, e.g. model1::link2::frame3?

My hope is to update the documentation in http://sdformat.org/tutorials?tut=composition&cat=specification& to include the changes in SDFormat 1.8 in the near future.

[FirefoxMetzger]

@azeey Is the documentation taken from the .sdf file annotations? I'm using those to generate docstrings for my bindings (e.g., v18.model.Model), which in turn become the API doc, so we might have common interest in making them pretty and easy to understand :D

[azeey]

@azeey Is the documentation taken from the .sdf file annotations?

The documentation I mentioned is written/updated manually but updating the .sdf annotations sounds good too. PRs are definitely welcome :)

[FirefoxMetzger]

@azeey On the doc page you linked in an earlier comment I found this quote

libsdformat's current implementation of the tag works by copying all links and joints of the child model into the parent model with their poses modified to be relative to the parent model frame.

Is this still the case? I always wondered what would happen if I //include'd a model that uses a different SDF version as the including one. This comment would suggest that tings ... simply break. I doubt this is what actually happens?

[FirefoxMetzger]

Also, reading up on the :: syntax, I am still confused what should happen in the following SDF

<sdf version="1.8">
  <model name="model">
    <frame name="alias_me">
      <pose>1 2 3 0 0 0</pose>
    </frame>

    <model name="alias_me">
      <pose>4 5 6 0 0 0</pose>
    </model>
    
    <link name="where_am_I">
      <pose relative_to="alias_me"/>
    </link>
    
  </model>
</sdf>

[scpeters]

Also, reading up on the :: syntax, I am still confused what should happen in the following SDF

that is invalid since spec version 1.7, since there are sibling elements with the same name:

• http://sdformat.org/tutorials?tut=pose_frame_semantics&ver=1.7&cat=specification&#unique-names-and-reserved-names

[FirefoxMetzger]

@scpeters Thanks for the clarification; that makes sense.

Perhaps the spec should be updated then. It makes you believe this is possible, since it limits uniqueness to siblings of the same kind, e.g., the frame spec currently says:

Name of the frame. This name must not match another frame defined inside the parent that this frame is attached to.

whereas the (nested) model spec says:

A unique name for the model. This name must not match another nested model in the same level as this model.

While both statements are true, the (nested) model description is incomplete, as the name also must not match a sibling frame (due to the implicit frame of model).

[FirefoxMetzger]

Closing this since #666 is merged.