ROS2 Humble + Gazebo 加载模型显示失败
ROS2 Humble + Gazebo 加载 TurtleBot3 小车失败?—— package:// 与 model:// 的坑
摘要:在 ROS2 Humble + Gazebo classic 11 环境下,用
spawn_entity把 URDF 小车导入 Gazebo 时,出现“小车无法正常加载/看不见车身”的问题。本文完整记录排查过程,定位到package://与model://两套 URI 协议不对齐 + 缺少gazebo_model_path导出 这一根本原因,并给出两种解决方案。
一、问题描述
- 使用 ROS2 运行
ros2 launch turtlebot3_sim gazebo_spawn.launch.py。 - 现象:Gazebo 能启动,日志里甚至显示
Successfully spawned entity [turtlebot3],但小车在 Gazebo 里无法正常加载——车身、轮子、激光雷达的视觉模型(mesh)都看不到,只剩碰撞盒或一片空白。 - 与此同时,
/odom、/scan、/imu、/joint_states、/cmd_vel等话题又都正常,说明物理、关节、传感器其实都在工作。
二、环境信息
| 项 | 版本 |
|---|---|
| 操作系统 | Ubuntu 22.04(内核 6.8.0) |
| ROS | ROS2 Humble |
| Gazebo | Gazebo classic 11.10.2(不是新版 gz sim / Ignition) |
| 相关包 | turtlebot3_description、turtlebot3_sim、gazebo_ros |
三、排查过程
- xacro 展开正常:
xacro turtlebot_burger_gazebo.urdf.xacro能正常生成 URDF,无报错。 - robot_state_publisher 正常:能发布
/robot_description(TRANSIENT_LOCAL锁存 QoS),并成功解析所有 link。 - spawn 服务正常:日志显示
SpawnEntity: Successfully spawned entity [turtlebot3],差速驱动插件、关节状态插件都正常加载。 - 但 mesh 加载异常:用
gz model --info -m turtlebot3查看 Gazebo 里最终生成的 SDF,发现 mesh 的路径全被改成了:
filename: "model://turtlebot3_description/meshes/bases/burger_base.stl"
注意:URDF 里写的明明是
package://turtlebot3_description/meshes/...,进 Gazebo 后却变成了model://。
- 路径解析失败:检查 Gazebo 实际使用的
GAZEBO_MODEL_PATH,发现里面只有官方turtlebot3_gazebo/models,没有turtlebot3_description。
四、根本原因
问题本质是两套生态、两套 URI 协议没有对齐:
1. package:// 是 ROS 的协议,model:// 是 Gazebo 的协议
package://xxx/...由 ROS 工具(robot_state_publisher、RViz)通过 ament 资源索引解析。- Gazebo classic 不认
package://,它只认model://(走GAZEBO_MODEL_PATH)、file://、绝对路径。
2. URDF 是 ROS 原生格式,mesh 天然写 package://
URDF 本来就是给 ROS 工具链设计的,mesh 路径用 package:// 对 RViz 完全正确;但对 Gazebo 就不行。
3. gazebo_ros 在 URDF→SDF 转换时把 package:// 重写成 model://
spawn_entity 把 URDF 发给 Gazebo 后,服务端 libgazebo_ros_factory.so 做 URDF→SDF 转换,package://xxx/yyy 被自动改写成 model://xxx/yyy。这一步是自动且躲不掉的。
4. model:// 靠 GAZEBO_MODEL_PATH 解析,而它由各包 package.xml 的导出收集
gazebo_ros 启动时会扫所有包的 package.xml,收集 <gazebo_ros gazebo_model_path="..."> 拼成 GAZEBO_MODEL_PATH。而 turtlebot3_description 的 package.xml 没有这个导出,所以它的目录不在路径里 → model://turtlebot3_description/... 解析不到 → mesh 加载失败。
一句话总结:URDF 里写的是 ROS 的 package://,Gazebo 只认 model://,而 model:// 又没注册路径,两头落空。
五、解决方案
方案 A(推荐,一劳永逸):给 description 包导出 gazebo_model_path
编辑 turtlebot3_description/package.xml,在 <export> 里加一行:
<export>
<build_type>ament_cmake</build_type>
<gazebo_ros gazebo_model_path="${prefix}/.."/>
</export>
说明:${prefix} 会被替换成 install/turtlebot3_description/share/turtlebot3_description,/.. 后正好是 install/turtlebot3_description/share/,这样 model://turtlebot3_description/meshes/... 就能解析到 mesh 文件。
然后重新编译并 source:
cd ~/turtlebot3
colcon build
source install/setup.bash
ros2 launch turtlebot3_sim gazebo_spawn.launch.py
方案 B(快速验证,不用重编译):手动加环境变量
export GAZEBO_MODEL_PATH=$GAZEBO_MODEL_PATH:~/turtlebot3/install/turtlebot3_description/share/
ros2 launch turtlebot3_sim gazebo_spawn.launch.py
缺点:每次开新终端都要重新设置。建议先用 B 快速验证,再落地到 A。
六、验证
用 Gazebo 底层 SystemPaths::FindFileURI 验证:
# 不加路径(修复前)→ 解析不到,会一直尝试联网查询,卡死/找不到
# 加上 install/turtlebot3_description/share/ 之后:
FindFileURI(model://turtlebot3_description/meshes/bases/burger_base.stl)
= /home/lzx/turtlebot3/install/turtlebot3_description/share/turtlebot3_description/meshes/bases/burger_base.stl ← FOUND
修复后重新启动,Gazebo 里小车车身、轮子、激光雷达的视觉模型即可正常显示。
七、延伸:其他人导入 Gazebo 是怎么处理的
ROS2 生态里主要有这几种做法:
- URDF 与 SDF 分离(最标准,官方 TurtleBot3 做法):
turtlebot3_description只放 URDF(package://mesh),给 RViz /robot_state_publisher用;turtlebot3_gazebo另放一套 SDF 模型(model://mesh),给 Gazebo 用,并在package.xml导出<gazebo_ros gazebo_model_path="${prefix}/models"/>。- 原因:URDF 服务 ROS 工具链,SDF 服务 Gazebo 的传感器/插件/材质等更丰富的特性,两者能力不对称。
-
给 description 包直接导出
gazebo_model_path(即本文方案 A),适合“想复用同一套 URDF 直接进 Gazebo”。 -
gazebo_media_path导出:对应GAZEBO_RESOURCE_PATH,用于贴图/材质/shadert 等 media 资源,和model://网格不是一回事,别混淆。 -
手动设
GAZEBO_MODEL_PATH(本文方案 B,quick-fix)。 -
新版 Gazebo(gz sim / Ignition)原生支持
package://:在 ROS2 下通过 ament 直接解析,不再需要这套转换和路径导出;但本文环境是 Gazebo classic 11,用不上。
八、总结
- 现象是“小车加载不进去”,但物理/传感器其实都正常,缺的是视觉 mesh。
- 根因是
package://(ROS)→model://(Gazebo)的自动转换,叠加gazebo_model_path未导出,导致 mesh 路径解析不到。 - 修复只需在
turtlebot3_description/package.xml加一行gazebo_model_path导出即可。
更多推荐
所有评论(0)