From 1dd68b85f54167a94053b224b47d8ea3d9febdf1 Mon Sep 17 00:00:00 2001
From: Yadu <yadunund@gmail.com>
Date: Tue, 23 Apr 2024 01:31:03 +0800
Subject: [PATCH] Explain how Gazebo and RViz can resolve mesh URIs (#26)

Signed-off-by: Yadunund <yadunund@gmail.com>
---
 sdformat_urdf/README.md | 14 ++++++++++++++
 1 file changed, 14 insertions(+)

diff --git a/sdformat_urdf/README.md b/sdformat_urdf/README.md
index 3bd08f2c..122e3171 100644
--- a/sdformat_urdf/README.md
+++ b/sdformat_urdf/README.md
@@ -55,3 +55,17 @@ The warning is issued using an `rcutils` logger with the name `sdformat_urdf`.
 * The model should not disable dynamic lighting using the `<lighting>`
 * The model should not use materials with `<script>`, `<shader>`, or `<pbr>`
 * The URDF material name assigned the name of the SDFormat `<visual>` containing the material, so `<visual>` names should be unique within the model
+
+### Considerations for Mesh URIs
+
+The `model://` prefix is commonly used in SDFormat XML files to set URIs for meshes, e.g. `model://my_model/meshes/mesh1.obj`.
+However, ROS tools likes `RViz` which rely on [resource_retriever](https://github.com/ros/resource_retriever/tree/ros2) will throw errors when attempting to load
+a mesh from such an URI since `resource_retriever` does not resolve `model://` prefixes to absolute filepaths.
+This may happen when an SDFormat XML file is parsed into an URDF XML by a `robot_state_publisher` node and published as a serialized
+string over `/robot_description` which is subscribed to by `RViz`.
+To allow both `Gazebo` and `RViz` to resolve URIs to absolute paths and load meshes properly, the following pattern may be adopted.
+- Move the `my_model` folder containing the meshes, `model.sdf` and `model.config` files into a ROS package, say `my_model_description` which installs the model.
+- Set the mesh URIs using the `package://` prefix, e.g. `package://my_model_description/models/my_model/meshes/mesh1.obj`
+- Set the `GZ_SIM_RESOURCE_PATH` environment variable to `<install_prefix>/my_model_description/share/`.
+
+> Note `<install_prefix>/my_model_description/share/` above is the output of `os.path.join(get_package_prefix('my_model_description'), 'share')` or `"$(ros2 pkg prefix my_model_description)/share"` and not `ros2 pkg prefix --share my_model_description` since the latter includes an extra package name at the end. See https://github.com/ros/sdformat_urdf/pull/20#issuecomment-1944430224 for more details.