DOC: clarify //pose/@relative_to

[FirefoxMetzger]

Thanks to @azeey and @scpeters pointing me to relevant documentation my understanding of how the pose semantics are supposed to work has improved significantly. I thought I use this knowledge for some good and try to clarify the spec. Please double-check if I got it right.

[FirefoxMetzger]

RTR from my side. This morning I found some more docs on scoping behavior and when implicit frames are created. Once this is clear the current pose semantics become much more obvious. I tried to reflect that in the docs of the spec.

[FirefoxMetzger]

Actually, I am not sure if the current description mentions all the entities that generate implicit frames. For example, if I have a //sensor and in particular a //sensor[@type=camera] then there are one (or two) poses that can be specified, which may or may not use @relative_to.

Does this mean that their names, too, must be unique in the current scope? Can an object be placed relative to a //sensor? What about other elements like //visual, or //collision?

[FirefoxMetzger]

I think it's just a bad sample, but the CI pipeline really doesn't seem to stable for my PRs here ... it's been building for two days now.

Does this mean that their names, too, must be unique in the current scope? Can an object be placed relative to a //sensor? What about other elements like //visual, or //collision?

Regarding my earlier question, I think I figured it out for //collision since the test file model_frame_relative_to_joint.sdf declares a collision element with the same name as a link and - as far as I can tell - this is expected to be a valid SDF. So for //collision and //visual, I think it shouldn't create a new frame and consequentially you can't place objects relative to them.

Still not sure about a //sensor.

@azeey Any thoughts on my doc update otherwise?

[scpeters]

I just started looking through this and will resume later when I have a chance. I've made a few comments for now.

Thanks for improving the documentation here!

[scpeters]

Actually, I am not sure if the current description mentions all the entities that generate implicit frames. For example, if I have a //sensor and in particular a //sensor[@type=camera] then there are one (or two) poses that can be specified, which may or may not use @relative_to.

The 1.7 proposal for pose frame semantics discusses explicit and implicit frames in section 1.2 and states that only link, joint, model and world have implicit frames

Does this mean that their names, too, must be unique in the current scope?

the name uniqueness rule in SDFormat 1.7 (see section 3.2 of the proposal) is rather broad, requiring unique names among all sibling elements, even if they don't have frames.

Can an object be placed relative to a //sensor? What about other elements like //visual, or //collision?

The name of a //sensor, //collision, or //visual cannot be used in a //pose/@relative_to or //frame/@attached_to attribute as they do not have implicit frames. These tags can use the //pose/@relative_to attribute to define their own pose, but it must use the name of an implicit frame.

[scpeters]

Does this mean that their names, too, must be unique in the current scope? Can an object be placed relative to a //sensor? What about other elements like //visual, or //collision?

Regarding my earlier question, I think I figured it out for //collision since the test file model_frame_relative_to_joint.sdf declares a collision element with the same name as a link and - as far as I can tell - this is expected to be a valid SDF. So for //collision and //visual, I think it shouldn't create a new frame and consequentially you can't place objects relative to them.

this is correct

Still not sure about a //sensor.

it is similar to //collsiion and //visual; you can't place objects relative to a //sensor. You can, however, place a //frame where the sensor will be and then place the sensor relative to that //frame, so there is a different way to accomplish the desired posturing

[scpeters]

Ok, I've finished looking through your improvements to the 1.7 documentation and just have one last comment there

There are some changes in 1.8, particularly with regard to the :: delimiter token for referencing frames in nested scopes. This hasn't made its way into the documentation section yet, but it is described in the 1.8 composition proposal:

• http://sdformat.org/tutorials?tut=composition_proposal&ver=1.8&cat=pose_semantics_docs&#1-3-1-reserved-delimiter-token

[FirefoxMetzger]

There are some changes in 1.8, particularly with regard to the :: delimiter token for referencing frames in nested scopes.

@scpeters Yep, I added docs for that in the v1.8 spec

New in v1.8: @relative_to may use frames of nested scopes within the same file. 
In this case, the frame is specified using `::` as delimiter to define the scope of the frame, e.g. `nested_model_A::nested_model_B::awesome_frame`.

[scpeters]

just one last change and then I think it will be good to go

[scpeters]

looks good to me. what do you think @azeey?

[codecov-commenter]

Codecov Report

Merging #666 (b56b1ef) into sdf11 (82cb977) will not change coverage.
The diff coverage is n/a.

@@           Coverage Diff           @@
##            sdf11     #666   +/-   ##
=======================================
  Coverage   88.08%   88.08%           
=======================================
  Files          73       73           
  Lines       11023    11023           
=======================================
  Hits         9710     9710           
  Misses       1313     1313           

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 82cb977...b56b1ef. Read the comment docs.

[FirefoxMetzger]

@azeey Once the tests pass, I'm happy with this PR unless you have any further suggestions/comments.

[azeey]

Just a couple more tweaks. Looks great!

[scpeters]

these links are now identical

[azeey]

Oops, they were supposed to be pointing to the 1.5 and 1.7 versions respectively.

[FirefoxMetzger]

Yep, you pasted/put versioned linkes @azeey , but the CI chain is unhappy about the fragment character (#) in the link and breaks if it is there. I removed them but didn't realize that it makes the links the same.

We could patch it and remove the second link.

[FirefoxMetzger]

See: #702

[osrf-triage]

This pull request has been mentioned on Gazebo Community. There might be relevant details there:

https://community.gazebosim.org/t/new-ignition-releases-2022-03-25-fortress-edifice-citadel/1343/1