企业官网建设流程全解析

在Gazebo里调模型位姿时，几乎每个人都有过对着SDF配置文件里那一段<pose>发愣的经历。我第一次用SDF写机器人模型，把一个轮子装到底盘上，结果一启动仿真，整个小车像喝醉了一样歪在一边，折腾了一个下午才发现：pose节点里的rpy数值，我把弧度当成了角度去写。后来帮别人排查Gazebo仿真问题时，十次里七八次都出在pose节点上——要么没搞清xyz和rpy的物理含义，要么不知道这段位姿到底是相对于哪个坐标系，要么忘记旋转顺序和单位。这篇文章就把这个基础但极其关键的节点彻底讲明白，适合正在写Gazebo模型、翻开源SDF文件学习，或者从ROS/Panda机械臂仿真教程开始接触机器人仿真的人。

1. 先搞清楚：pose节点的六个数字到底在表达什么

1.1 为什么要先理解pose节点

SDF（Simulation Description Format）是Gazebo仿真的核心描述格式，一个机器人模型里有什么连杆（link）、什么关节（joint）、什么传感器、碰撞体长什么样、材质是什么颜色，全部写在一个后缀为.sdf的XML文件里。而pose节点描述的是“我在哪、我朝哪”，它决定了模型在仿真世界里的初始位置，也决定了每一个零件和另一个零件之间的相对几何关系。

很多人上来就套用网上的SDF模板，把<pose>0 0 0 0 0 0</pose>当作固定开头复制进去，觉得只要存在就行。但当你需要让机械臂的末端执行器对准某个工作台、让激光雷达的扫描方向朝前、让碰撞体精确贴合视觉模型时，不理解这六个数字的含义就会彻底卡住。更麻烦的是，pose不止出现在<model>里，还出现在<link>、<visual>、<collision>、<inertial>、<joint>和传感器插件里，每个地方的参考系都不同，写错一个，仿真里的表现就是模型乱飞、零件错位或者碰撞体积跑偏。

1.2 一个pose节点长什么样

先看最基本的写法：

<pose relative_to="base_link">0.1 0.0 0.2 0 0 1.57</pose>

括号里一共六个数字，位置三个，姿态三个：

• 前三个数：x y z，单位是米，表示相对位置。
• 后三个数：roll pitch yaw，单位是弧度，表示相对姿态。

所以上面这段的意思是：在base_link坐标系下，X方向偏移0.1米，Z方向偏移0.2米，并且绕Z轴旋转1.57弧度（约90度）。

relative_to属性表示“这段位姿是相对于谁的”。如果省略不写，就使用默认的父坐标系，比如<model>里的<pose>默认相对world，<link>里的<pose>默认相对它所在的<model>坐标系。这一点非常容易踩坑，后面我会专门展开。

2. xyz与rpy：位置、姿态、单位与旋转顺序的完整拆解

2.1 xyz位置：前提是搞懂坐标系方向

六个数里最容易理解的是xyz，但它有一个隐含前提：你得先知道坐标系的方向。Gazebo使用右手坐标系，Z轴垂直向上，这是物理引擎的通用约定。至于是X轴朝前还是Y轴朝前，SDF规范并没有强制，具体取决于模型设计者的约定。

在ROS生态和绝大多数开源机器人模型里，习惯采用“X轴向前，Y轴向左，Z轴向上”的坐标系。比如Panda机械臂的基础坐标系，X轴沿手臂伸长方向，Z轴竖直向上。看开源SDF文件时，最好先找到模型根节点的坐标系朝向，再判断xyz里的正负号是否合理。我见过不少新手把一个明明应该在机器人正前方的传感器写成了负X方向，结果雷达装在屁股后面，扫描出来的点云方向完全反了。

xyz还有一个容易忽略的地方：它描述的是坐标系的平移，不是模型中心点的移动。换句话说，子坐标系的xyz是它的原点在父坐标系中的位置。对于复杂模型，可以先在纸上画一个粗略的几何图，标出每个坐标轴方向和各连杆的偏移量，再往SDF里填数字，这样比瞎试要快得多。

2.2 rpy姿态：旋转顺序和正方向决定一切

rpy是roll、pitch、yaw三个姿态角的缩写，对应绕X轴旋转、绕Y轴旋转、绕Z轴旋转。这里最关键的是旋转顺序：SDF中规定按先roll、再pitch、最后yaw的顺序，也就是依次绕固定轴X、Y、Z旋转。这个顺序直接影响最终姿态，不能凭感觉调换。

举个例子：一个传感器原本Z轴朝上，希望让它变成“躺平朝前”的姿态，需要绕X轴旋转90度，对应的rpy是1.5708 0 0；如果写成0 1.5708 0（绕Y轴旋转90度），它就变成朝向侧面了。如果三个角都不为零，不同的读写顺序会得到完全不同的最终指向，这在机械臂末端姿态、相机安装角度里尤其致命。

旋转方向遵循右手定则：沿着旋转轴的正方向看去，逆时针为正。也就是说，绕Z轴旋转90度，会把X轴转到Y轴方向；绕Z轴旋转-90度，才会把X轴转到Y轴负方向。这个细节在做传感器朝向时经常用到。

2.3 单位陷阱：弧度与角度对照表

SDF里姿态角的单位是弧度，不是角度。这是新手最容易踩的坑，没有之一。写成90，Gazebo会按90弧度处理，一个完整圆周也只有6.28弧度，90弧度相当于转了14圈还多，模型自然看起来像在疯狂翻转。

我建议把常用角度对应的弧度值直接贴在SDF文件头部注释里，或者背下来：

注意：在Gazebo图形界面的属性面板里，有些版本会直接显示角度，方便人读；但无论界面怎么显示，.sdf文件里必须是弧度。写完配置文件后如果懒得确认，可以把.2f格式的数值都过一遍，凡是出现6.28以上的数，基本就是角度忘转弧度了。

3. 最容易写错的relative_to：pose到底相对于谁

3.1 父子关系决定数值含义

relative_to是pose节点里最容易被忽略的隐藏属性。SDF里位姿永远是“相对”的，必须有一个参考坐标系。默认规则是这样的：

• 模型<model>下的<pose>，默认相对world坐标系；
• 嵌套模型里，子模型的<pose>默认相对父模型坐标系；
• 连杆<link>下的<pose>，默认相对它所属的<model>坐标系；
• 视觉<visual>、碰撞<collision>、惯性<inertial>里的<pose>，默认相对所在<link>坐标系；
• 关节<joint>下的<pose>，默认相对父连杆坐标系。

很多人以为所有pose都是相对world，于是在写link位姿时直接把在Gazebo里看到的世界坐标填进去。这在一层嵌套时可能碰巧对，但只要模型整体移动位置，或者放到另一个世界文件里，所有子部件就全部“飞走”了。正确做法是：始终想清楚当前这个pose到底挂在哪个节点下面，再决定数值怎么填。

3.2 嵌套model里的相对位姿

嵌套模型是relative_to最容易出问题的地方。比如做一个带机械臂的移动机器人，把机械臂整个作为一个<model>嵌套在机器人模型里，那么机械臂根部的<pose>是相对机器人底盘的，不是相对world的。如果从某个仿真截图里看到机械臂在世界坐标里位于(2.1, 0.3, 0.5)，就直接把这个值写进子模型<pose>，等到底盘一移动，机械臂并不会跟着走，而是悬在原处。

我在调试时的一个习惯是：只要pose节点里的任何数字超过10（除非是世界级大场景），就要停下来问自己“我的模型真有这么大吗？这个数是不是从错误的参考系里抄来的？”。在机器人尺寸范围内，位姿数值通常都在个位数以内，一旦出现夸张数值，多半是相对参考系搞错了。

4. link、collision、joint里的pose：从“看起来”到“算得准”

4.1 visual、collision、inertial三者的作用域

一个<link>里面通常包含三种子节点，它们的pose职责完全不同：

• <visual>里的pose只影响显示，决定网格长在link的哪个位置；
• <collision>里的pose只影响碰撞检测，决定物理引擎拿哪个区域算接触；
• <inertial>里的pose只影响质心和转动惯量，决定给link施力时它怎么运动。

换句话说，视觉模型看起来正常，不代表物理上正常。最常见的坑是：从网上下的模型视觉网格原点不在几何中心，于是你为了让模型“看着居中”，在<visual>里加了偏移；但<collision>没有同步修改，导致仿真里小车还没碰到障碍物就被空气墙挡住。反过来，<inertial>的pose如果写了错误的质心偏移，机器人静止状态下就会因为重心不稳突然倒下去。检查这类问题时，一定要把三种节点的pose放在一起对比，而不是只看视觉效果。

4.2 joint pose是关节位置的关键

<joint>里的<pose>表示关节坐标系相对父连杆的位置。对于旋转关节，这个值决定了旋转轴心在哪里；对于固定关节，它决定两个连杆之间的初始连接位置。很多人只关注关节的type和axis，却忘记设pose，于是关节原点默认在父连杆原点，转起来的位置就完全不对。

比如两连杆摆臂，第一根连杆长0.4米，关节位于第一根连杆末端。如果关节<pose>没写，那么第二根连杆会直接叠在父连杆原点附近，整个机械臂缩成一团。正确写法是让关节的xyz偏移到第一根连杆末端位置，再在子连杆的<pose>（或子link的visual/collision）里安排几何体的相对偏移。这个逻辑和URDF里的joint origin是一样的，只不过SDF把位置和姿态拆在了<pose>标签里。

4.3 传感器link的坐标系才是输出的来源

很多人在Gazebo里给机器人加相机或激光雷达，发现传感器输出的数据方向不对。视觉模型看起来明明朝前，为什么点云指向侧面？原因在于：传感器插件读取的是它所在link的坐标系，而不是<visual>网格的朝向。

所以判断传感器朝向时，别只看网格指向哪，先确认link坐标系的rpy。比如激光雷达的默认视线方向是link的X轴正方向，如果你希望雷达扫到机器人正前方，link的rpy里的yaw应该是0（假设机器人X轴朝前）；如果希望它朝左扫，需要绕Z轴转90度，rpy写0 0 1.5708。传感器插件内部可能还有自己的偏移参数，但通常默认不设置，实际输出轴就是link坐标系。这个链路理清楚了，传感器方向问题基本都能解决。

5. 实操演练：手把手写一个带激光雷达的小车模型

5.1 底盘和雷达的位姿计算

下面用一个极简移动机器人示例来串起上面所有知识点。假设底盘是一个长0.4米、宽0.3米、高0.1米的长方体，坐标系原点在底盘几何中心，X朝前，Y朝左，Z朝上。激光雷达要安装在底盘前方偏左的位置，离地面0.15米，并且雷达的扫描平面要水平，正方向朝前。

雷达相对底盘的偏移：前方0.1米，左侧0.15米，抬高0.15米，所以xyz是0.1 -0.15 0.15（注意Y轴向左为正，装在左侧就是负号？这里要小心：Y向左为正，那么“左侧”应该是正Y还是负Y？在Gazebo默认右手坐标系下，X向前，Y向左，Z向上，所以左侧是正Y方向。如果想要雷达装在左前方，Y就应该是0.15而不是-0.15。这里用0.15更符合“向左为正”的约定。如果你习惯于Y向右，就容易写反，所以一定要先定坐标系方向。

雷达姿态：雷达的X轴应该水平向前，因此不需要旋转，rpy是0 0 0。如果原本雷达模型定义里安装方向朝右，才需要在YAW上加旋转。这里保持默认即可。

底盘模型放在世界原点，底部离地面0.05米，避免刚启动就因为重力穿模。所以<model>的pose写0 0 0.05 0 0 0。

5.2 完整SDF示例与运行验证

<sdf version="1.7"> <world name="default"> <include> <uri>model://sun</uri> </include> <model name="simple_robot"> <pose>0 0 0.05 0 0 0</pose> <link name="chassis"> <pose>0 0 0 0 0 0</pose> <visual name="chassis_visual"> <geometry> <box> <size>0.4 0.3 0.1</size> </box> </geometry> </visual> <collision name="chassis_collision"> <geometry> <box> <size>0.4 0.3 0.1</size> </box> </geometry> </collision> <inertial> <mass>2.0</mass> <inertia> <ixx>0.025</ixx> <iyy>0.05</iyy> <izz>0.05</izz> <ixy>0</ixy> <ixz>0</ixz> <iyz>0</iyz> </inertia> </inertial> </link> <link name="laser_link"> <pose>0.1 0.15 0.15 0 0 0</pose> <visual name="laser_visual"> <geometry> <cylinder> <radius>0.04</radius> <length>0.06</length> </cylinder> </geometry> </visual> <collision name="laser_collision"> <geometry> <cylinder> <radius>0.04</radius> <length>0.06</length> </cylinder> </geometry> </collision> </link> <joint name="laser_joint" type="fixed"> <parent>chassis</parent> <child>laser_link</child> <pose>0 0 0 0 0 0</pose> </joint> </model> </world> </sdf>

这个示例里，laser_link的relative_to省略了，所以默认相对model坐标系，也就是simple_robot的坐标系。它的位置0.1 0.15 0.15就是相对底盘中心的位置。laser_joint的pose是0，表示关节坐标系和底盘坐标系重合，但实际连接位置已经在子link的pose里定义了。这种写法在固定关节里很常见，也是调试时最直观的做法。

把这个文件保存为simulation.world，在命令行执行：

gazebo simulation.world

如果用的是新版Gazebo Sim（原Ignition），命令类似：

gz sim simulation.world

启动后应该能看到一个小车底盘，雷达圆柱安装在底盘左前方。如果雷达跑到车屁股后面，基本就是Y轴方向写反了；如果雷达陷进底盘里，检查Z轴高度是否写够0.15米；如果雷达画面朝侧面，检查rpy是否多转了一个角度。

5.3 在Gazebo里确认pose是否正确

启动仿真后别急着加传感器，先确认位姿。在Gazebo旧版中可以用命令查看模型信息：

gz model --info -m simple_robot

这条命令会输出模型的当前位姿和子节点信息。新版Gazebo Sim里则用：

gz model --list gz topic -e -t /world/default/model/simple_robot/pose

在GUI里，选中模型或某个link后，属性面板会显示该坐标系的实时位姿，很多版本还能切换显示单位。建议把rpy切到弧度显示，和SDF文件对照，确认两者一致。如果只差一个小数点，往往是界面用了角度显示而文件里用的是弧度，并不代表写错。

6. 常见问题与排查技巧实录

6.1 高频问题速查表

排查时有一个好用的技巧：把<visual>、<collision>、<inertial>里的偏移数字按列排列，对比它们的xyz是否一致。三个值不一致的地方，就是问题的高发区。

6.2 我调试pose的独家小习惯

最后分享一个我自己的调试习惯。每次拿到一个新模型，我不会直接打开完整SDF去一个个数位姿，而是先把所有零件简化成一个简单的box，放在正确位置，验证坐标系关系，再一层层加视觉网格、碰撞体积和传感器。这样如果零件飞了，我能立刻判断是位置或姿态哪一层出了问题，而不是在一堆从网上抄来的位姿数字里大海捞针。

另外，凡是涉及旋转的地方，我都会先写注释，把“这个link的相对坐标系是谁、我期望它的哪个轴朝哪个方向”写清楚。例如：

<!-- laser_link: 相对chassis，X朝前，Y朝左，Z朝上，雷达水平安装 --> <pose relative_to="chassis">0.1 0.15 0.15 0 0 0</pose>

看起来多写了几行字，但调试时能省下大量时间。SDF的pose节点学习成本不高，问题几乎都出在“坐标系相对关系”和“单位与旋转顺序”这两个知识点上。把这两个点刻在脑子里，以后不管是看Panda机械臂的SDF，还是自己从零搭建仿真机器人，都会顺畅很多。