SDF-specific documentation on how to interpret model:// URIs

[traversaro]

Desired behavior

As a mantainer that writes software that loads SDF files, and as a mantainer that distributes SDF models, I would like to understand how URI in the form model:// should be interpreted according to the SDF standard.
It would be great if this information could be documented.

It would be great if this would be documented.

Alternatives considered

Each program could implement its own way to interpret model:// URIs, but in that case as a mantainer that distributes SDF models, it would not be clear to me how to make sure that all programs that interpret SDF are able to load my files.

Implementation suggestion

At least for Gazebo-related software, from what I understand the URI is expanded w.r.t. to the following env variables:

• GAZEBO_MODEL_PATH for Gazebo Classic
• IGN_GAZEBO_RESOURCE_PATH for Ignition Gazebo <= 7
• GZ_SIM_RESOURCE_PATH for Gazebo Sim >= 7

It would be great if there would be a clear way endorsed at the SDF level tha explains how to load model:// URIs.

Additional context

I opened this after reading ami-iit/rod#20 .

[azeey]

There is some documentation in http://sdformat.org/tutorials?tut=composition&cat=specification&#including-a-model. Is that helpful?

[traversaro]

There is some documentation in http://sdformat.org/tutorials?tut=composition&cat=specification&#including-a-model. Is that helpful?

Sorry, I missed your reply. Yes, this is indeed what I was looking for, I was confused as I was mostly investigating the use of model:// URIs for meshes, and so I did not thought of checking documentation on how to include models. So, if I understand all of this correctly, probably instead of using:

• GAZEBO_MODEL_PATH for Gazebo Classic
• IGN_GAZEBO_RESOURCE_PATH for Ignition Gazebo <= 7
• GZ_SIM_RESOURCE_PATH for Gazebo Sim >= 7

We can just use SDF_PATH for all simulators using sdformat, as using SDF_PATH ensures that the path is correctly found directly at the sdformat level. And as a bonus, SDF_PATH has been supported since forever (see 42301db), so that should work fine even for old version of Gazebo Classic. So this is definitely documented, but I was not aware of this.

[traversaro]

I look a bit more into this, and apparently the use of SDF_PATH is explicitly discouraged in Gazebo "Modern" documentation, see https://github.com/gazebosim/gz-sim/blob/gz-sim7_7.4.0/tutorials/resources.md?plain=1#L126 :

The SDF_PATH environment variable also works in some scenarios, but it's not recommended when using Gazebo.

This sentence was added in gazebosim/gz-sim#172 with the rest of the tutorial, but I am not really sure why it is not recommended to use it.

[traversaro]

Anyhow, this is definitely a bit OT here, so let's close this issue.