📚 课程目录第2章 URDF模型导入与常见错误

2. URDF模型导入与常见错误

做Gazebo仿真，第一步就是把机器人模型导进去。这一步看着简单，但坑是真不少。我见过太多人卡在URDF导入这一步，一卡就是半天。说白了，URDF就是机器人的「身份证」，你得把它写对了，仿真器才能认。

2.1 URDF语法基础

URDF，全称Unified Robot Description Format，基于XML。它的核心就两个东西：连杆（link）和关节（joint）。连杆是刚体，关节是连接方式。

一个最简单的URDF结构长这样：

<robot name="my_robot">
  <link name="base_link">
    <visual>
      <geometry>
        <box size="0.2 0.2 0.1"/>
      </geometry>
    </visual>
  </link>
  
  <joint name="base_to_wheel" type="continuous">
    <parent link="base_link"/>
    <child link="wheel_link"/>
    <origin xyz="0.1 0 0" rpy="0 0 0"/>
  </joint>
</robot>

嗯，这里要注意：<origin>里的xyz是位置偏移，rpy是旋转角度（弧度制）。我刚开始写的时候老把rpy写成角度，结果模型直接飞出去了。

2.2 模型文件路径问题

这个问题，我敢说90%的人遇到过。URDF里引用STL或DAE文件时，路径写不对，模型就加载不出来。

常见的路径写法有三种：

写法	示例	说明
路径	`file:///home/user/model.stl`	不推荐，换个电脑就废了
相对路径	`package://my_package/meshes/model.stl`	推荐，但依赖包路径
环境变量	`$(find my_package)/meshes/model.stl`	最灵活，launch文件里常用

我个人习惯用package://这种写法。为什么？因为它在Gazebo和Rviz里都能识别，省心。

注意：如果你用package://，一定要确保你的包路径在ROS环境变量ROS_PACKAGE_PATH里。否则Gazebo会报「找不到文件」的错误。

2.3 STL/DAE网格文件缺失

网格文件缺失，说白了就是你的URDF里引用了某个.stl或.dae文件，但实际路径下没有这个文件。Gazebo会给你一个灰色的方块代替，或者干脆不显示。

我在项目中遇到过这种情况：明明文件在文件夹里，但就是加载不出来。后来发现是文件名大小写的问题。Linux是区分大小写的，model.STL和model.stl是两个文件。

避坑指南：

检查文件名大小写是否一致
检查文件扩展名是否正确（.stl不是.stl，.dae不是.dae）
检查文件权限（chmod 644）
用ls -la确认文件确实存在

小技巧：你可以用rosrun gazebo_ros check_urdf工具来检查。它会告诉你哪个文件找不到，非常直观。

2.4 关节与连杆定义错误

关节定义错误，是URDF里最常见的逻辑问题。我总结了几种典型情况：

关节类型选错：轮子用continuous，手臂用revolute，别搞混了
父子关系颠倒：parent和child写反了，模型会乱套
原点偏移不对：关节的origin设置不合理，连杆之间出现间隙或重叠
缺少惯性参数：Gazebo要求每个link必须有<inertial>标签，否则仿真会崩溃

举个例子，一个常见的错误写法：

<joint name="arm_joint" type="fixed">
  <parent link="arm_link"/>
  <child link="base_link"/>
</joint>

你看，parent和child写反了。正确的应该是base_link是父，arm_link是子。我曾经因为这个错误，调试了整整一个下午。

2.5 使用check_urdf工具排查

手动检查URDF文件太累了。ROS提供了一个神器——check_urdf。用法很简单：

check_urdf my_robot.urdf

它会输出类似这样的信息：

robot name is: my_robot
---------- Successfully Parsed XML ---------------
root link: base_link has 2 child(es)
    child(1): wheel_left_link
    child(2): wheel_right_link

如果有错误，它会直接告诉你哪一行有问题。比如：

ERROR: Link base_link has no inertial tag
ERROR: Joint arm_joint has no parent specified

嗯，这个工具我几乎天天用。每次写完URDF，第一件事就是跑一遍check_urdf。它就像个语法检查器，能帮你省下大量排错时间。

  核心要点：
  URDF由link和joint组成，语法基于XML
路径问题用package://写法最稳妥
网格文件缺失检查大小写和权限
关节定义注意类型、父子关系和惯性参数
check_urdf是必备的排错工具

最后说一句：URDF写得好不好，直接决定了后面仿真能不能跑起来。别嫌麻烦，多检查几遍。我见过太多人因为URDF里一个小错误，卡了好几天。你想想看，一个逗号写错了，模型就加载不出来，多冤啊。

可可精品资料库