Backport importing included models as nested models to v6-9

[lihui815]

Environment

• OS Version: Ubuntu 20
• Source or binary build?
  libsdformat6-dev & libformat9-dev

Description

sdformat<=10 versions do not load models referenced in <include> tags as nested models (see gazebosim/gazebo-classic#2139).

If <include> is nested under <world> directly, then the <model> referenced by the <include><uri> will be loaded as a <model> within <world> CORRECTLY. Examples:

* --- world defined as ---
    
    <world name=some_world>
      <include>
        <uri>model://some_model</uri>
      </include>
    </world>
    
    --- loads as ---
    
    <world name=some_world>
      <model name=some_model>
        <link name=some_link/>
        ...
      </model>
    </world>

If <include> is nested under a parent <model> then the <model> referenced by the <include><uri> will NOT be loaded as a child <model> under the parent <model>. Instead, the name of the referenced <model> (or the overridden name using the <include><name> tag) will be prepended to the names of referenced <model> elements and be imported into the parent model directly. Thus a <link> named some_link of the referenced <model> ref_model that is nested via <include> under a parent <model> parent will show up as a <link> named ref_model::some_link of the parent <model> parent. Examples:

 --- world defined as ---
    
    <world name=some_world>
      <model name=some_parent>
        <include>
            <uri>model://some_model</uri>
        </include>
      </model>
    </world>
    
    --- loads as ---
    
    <world name=some_world>
      <model name=some_parent>
        <link name=some_model::some_link/>
        ...
      </model>
    </world>
    
    --- should load as ---
    
    <world name=some_world>
      <model name=some_parent>
        <model name=some_model>
          <link name=some_link/>
          ...
        </model>
      </model>
    </world>

The referenced model will not be loaded as its own model, instead all of its elements (links, joints, etc) will be directly part of the parent model. If the parent model contains multiple <include> tags, or if the parent model had its own elements separate from nested child models, then all link and joint entities will coexists on the same level and cannot be selected or modified as a model group as intended.

As an additional note, any further nested models from within the included model gets pulled out into the world without modification, but also outside of the top-level model of the referenced include. Examples:

-- world definition --

<world>
  <model name=root>
    <include>
      <uri>model://A</uri>
    </include>
  </model>
</world>

-- If the included model is flat --

<model name="A">
  <link name="link">
</model>

-- Then the loaded world looks like --

<world>
  <model name=root>
    <link name="A::link">
  </model>
</world>

-- If the included model is wrap-nested --

<model name="wrapper">
  <model name="A">
    <link name="link">
  </model>
</model>

-- Then the loaded world looks like --

<world>
  <model name=root>
    <model name="A">
      <link name="link">
    </model>
  </model>
</world>

================

-- Here is a more complicated example --

-- world definition --

<world>
  <model name="root">
     <link name="link"/>
    <include>
      <uri>model://A</uri>
    </include>
  </model>
</world>

-- included model --

<model name="A">
  <link name="link_A"/>
  <model name="B">
    <link name="link_B"/>
    <model name="C">
      <link name="link_C"/>
    </model>
  </model>
</model>


-- Then the resolved world looks like --

<world>
  <model name="root">
    <link name="link"/>
    # no more model A
    # "A" gets prepended to the name of link "link_A"
    # and the link moves to within the root model's scope
    <link name="A::link_A"/>
    # models nested under A gets
    # pulled in with no name changes
    # but scope does change
    <model name="B">
      <link name="link_B"/>
      <model name="C">
        <link name="link_C"/>
      </model>
    </model>
  </model>
</world>

This behavior has already been changed in libsdformat11-dev to load models referenced by tags as nested models. However, the change has not been backported to libsdformat6-dev -> libsdformat9-dev, which are dependencies for Gazebo. This is causing problems for entity identification because it's expecting '::' to deliminate scope and not to be part of enity names names.

Can the change be backported into older stable branches?

[azeey]

The issue with a directly-nested (<model> inside <model>) models not being properly prefixed is being addressed by #597. However, changing the behavior of <include> to not flatten (that's the term we use for the process of links being moved to the parent model with their name prefixed) models is a major behavior change and so we don't plan to backport that to versions earlier than libsdformat11.

[azeey]

Closing this since there's no actionable item. Feel free to reopen if I'm mistaken.