11 KiB
URDF 组件接口坐标系导出规范
本文面向为组件库导出 URDF 的机械工程师,说明本项目如何识别接口,以及如何设置 joint 和 Link 坐标系,保证组件拼装后的方向正确。
一条必须遵守的规则
系统不会猜测模型正反面,也不会在拼装时自动旋转或翻转子组件。它使父、子两个接口的坐标系完全重合:原点重合,+X、+Y、+Z 三个方向也分别同向。
子组件世界位姿 = 父接口世界位姿 x 子接口相对组件根的位姿的逆
因此,接口不是“只有一个安装方向的点”,而是一个完整的右手坐标系。导出错误的 xyz 或 rpy,都会直接导致拼装后的组件位置或方向错误。
父接口与子接口的方向关系
设一条连接为“父组件 -> 子组件”。安装面将两个模型分在两侧,坐标系的正确关系如下:
父模型实体 安装面 子模型实体
位于 -Z 侧 [ 两个接口原点重合 ] 位于 +Z 侧
+Z ->
拼装后,两个接口的蓝色 +Z 箭头是同向的,并不相向:
- 父接口的
+Z从父组件实体指向外部,也就是指向子组件。 - 子接口的
+Z从安装面指向子组件实体内部。 - 两个接口的红色
+X也必须同向;它决定绕+Z轴的默认旋转角度。
从各自模型外观看,父接口箭头“朝外”、子接口箭头“朝里”;从装配后的世界坐标看,它们是同一套坐标轴。若把子接口也设置成从子模型朝外,模型就会落到父组件一侧,通常会倒置或穿模。
坐标轴含义
本项目的预览标记含义如下:
| 标记 | 含义 | 导出时的要求 |
|---|---|---|
蓝色 +Z |
拼装方向 | 设置为从父安装面指向子组件的一致方向 |
红色 +X |
默认旋转朝向 | 设置为装好后的机械基准方向,例如统一的前方、关键孔位方向或电缆出口方向 |
绿色 +Y |
由右手系推导的辅助方向 | 正常预览隐藏,仅调试时显示 |
+Y 不是独立需要填写的方向。确定 +Z 和 +X 后,+Y = +Z x +X,三轴必须构成右手坐标系。不要为了“看起来对称”单独反转 +Y;那会形成镜像坐标系,不能用刚体变换正确拼装。
接口在 URDF 中如何定义
系统通过接口 Link 的名称识别接口,而不是通过 joint 名称、axis、网格名称或自定义 XML 属性识别。
同一条装配连接的两端必须使用相同的规范接口名。例如躯干为手臂提供的输出接口叫 LINK_ARM_0 时,待安装手臂的输入根接口也应叫 LINK_ARM_0。名称用于接口类型匹配,joint/origin 决定该接口的真实位置和方向。
接口 Link 名称必须符合下表之一:
| 类型 | 接口 Link 名 |
|---|---|
| 躯干 | LINK_TORSO_0 |
| 头 | LINK_HEAD_0 |
| 腰 | LINK_WAIST_0 |
| 臂 | LINK_ARM_L、LINK_ARM_R、LINK_ARM_0 |
| 手 | LINK_HAND_L、LINK_HAND_R、LINK_HAND_0 |
| 足 | LINK_LEG_L、LINK_LEG_R、LINK_LEG_0 |
| 脚 | LINK_FOOT_L、LINK_FOOT_R、LINK_FOOT_0 |
| 尾 | LINK_TAIL_0 |
建议每个安装接口都使用一个没有 visual/collision 的虚拟 Link,并用 fixed joint 将它连接到实际结构。这样接口坐标系可以独立于网格和内部机构,最稳定、最容易检查。
父组件:定义一个向外的输出接口
下面例子在躯干右侧建立一个供 ARM_0 组件接入的接口。接口原点放在实际安装面中心,rpy 让局部 +Z 指向躯干右侧外部。
<link name="LINK_ARM_0" />
<joint name="mount_arm_0" type="fixed">
<parent link="torso_body" />
<child link="LINK_ARM_0" />
<origin xyz="0 -0.0505 0.0580" rpy="1.57079632679 0 0" />
</joint>
上例中,rpy="1.57079632679 0 0" 会使局部 +Z 指向父组件的 -Y 方向。数值必须来自 CAD 中定义好的安装坐标系;例子只用于说明,不应直接复制到别的安装面。
子组件:定义一个朝向组件内部的输入接口
如果手臂通过根部安装到躯干,推荐让 URDF 根 Link 就是输入接口 LINK_ARM_0。实际手臂结构作为它的子 Link,按设计位置延伸到接口局部 +Z 一侧:
<link name="LINK_ARM_0" />
<link name="arm_body">
<visual>
<geometry><mesh filename="package://arm/meshes/arm_body.STL" /></geometry>
</visual>
<collision>
<geometry><mesh filename="package://arm/meshes/arm_body.STL" /></geometry>
</collision>
</link>
<joint name="arm_root_structure" type="fixed">
<parent link="LINK_ARM_0" />
<child link="arm_body" />
<origin xyz="0 0 0" rpy="0 0 0" />
</joint>
此时 LINK_ARM_0 是子组件的输入安装面;手臂本体位于它的局部 +Z 一侧。装配时该根接口与父组件的 LINK_ARM_0 完全重合,手臂自然位于躯干外侧。
如果现有模型必须保留带网格的根 Link,也可以使用它作为输入接口;但仍须保证其根坐标原点在安装面,且本体位于局部 +Z 一侧。根 Link 没有父 joint 可以再调整坐标系,根接口的方向必须在 CAD 导出坐标系中设置正确。
joint/origin 的正确含义
对任意 joint:
<joint name="mount_arm_0" type="fixed">
<parent link="torso_body" />
<child link="LINK_ARM_0" />
<origin xyz="x y z" rpy="roll pitch yaw" />
</joint>
origin xyz:child Link 原点相对 parent Link 原点的位置,单位为米。origin rpy:child Link 坐标轴相对 parent Link 坐标轴的旋转,单位为弧度。- 该变换决定 child Link 的完整坐标系,不只是位置。
- URDF 的
rpy顺序是 roll、pitch、yaw;推荐由 CAD 安装坐标系直接导出,避免人工试填欧拉角。
常用方向参考如下。它们只说明 +Z 的去向,实际使用时还必须检查 +X 是否满足默认朝向要求:
rpy |
局部 +Z 在父坐标中的方向 |
|---|---|
0 0 0 |
+Z |
0 1.57079632679 0 |
+X |
0 -1.57079632679 0 |
-X |
1.57079632679 0 0 |
-Y |
-1.57079632679 0 0 |
+Y |
不要只依据 +Z 填写 rpy。两个姿态即使 +Z 相同,也可能绕 +Z 相差 180 度,导致孔位、电机、前后方向或手臂弯折方向错误;红色 +X 箭头就是检查这个差异的依据。
不应当当作接口方向的数据
joint/axis是 revolute/continuous/prismatic 关节的运动轴,不是组件拼装方向。visual/origin和collision/origin只描述网格相对 Link 坐标系的位置,不定义接口坐标系。- 内部的
J2、J3、J4等关节是机构运动链的一部分。除非其 child Link 有规范的LINK_*接口名,否则不参与组件拼装。 joint的名称可以自定义;决定接口识别的是 child Link 名称。- 本项目当前不读取 URDF 自定义标签来决定安装方向。即使文件添加了自定义属性,也不会改变现有装配结果。
左右接口和不分左右组件
左右位置不是由程序自动镜像出来的。躯干、腰等父组件的左、右接口必须分别在 URDF 中给出正确的 xyz 和 rpy;同一个 ARM_0 子组件装到两侧后,会完整继承各自父接口的 +X/+Y/+Z 姿态。
因此,若左右手臂出现一个朝前、一个朝后,优先检查父组件两个 LINK_ARM_* 接口的红色 +X 是否符合设计。两个接口的蓝色 +Z 都朝外并不代表它们的默认旋转相同;绕 +Z 相差 180 度会直接传递给子组件。
若机械设计要求左右是镜像件,请在 CAD/URDF 中明确建立对应的左、右接口坐标系,或提供左/右模型;系统不会根据 Link 名中的 L/R 自动镜像网格。
导出前检查清单
- 每个可装配位置均创建规范命名的
LINK_*接口 Link;不要只给 joint 命名。 - 接口原点位于实际安装基准面、孔中心或轴线中心,不要放在模型质心或网格原点。
- 对一条父子连接,父接口本体在局部
-Z侧,子接口本体在局部+Z侧。 - 为接口指定明确的
+X机械基准,确保拼装后孔位、前后方向和默认机构姿态正确。 - 接口固定在结构上时使用
type="fixed";内部运动关节仍按真实revolute、continuous或prismatic导出。 - URDF 以零位姿导出:手臂、腿等机构在默认状态应处于工程规定的直立或伸直姿态,不能依赖运行时关节角度校正。
- 上传后台后,在 URDF 预览中检查蓝色
+Z和红色+X。悬停接口可定位标记;绿色+Y仅供调试。 - 实际拼装两个组件后检查几何是否重叠。接口坐标系正确能保证定义的姿态正确,但不能替代几何碰撞校验。
常见错误与处理
| 现象 | 常见原因 | 应修改的位置 |
|---|---|---|
| 子组件完全进入父组件 | 子接口 +Z 也朝子模型外侧,或接口原点不在安装面 |
子组件根接口的 CAD 坐标系,或根接口到结构的 fixed joint |
| 子组件位于正确位置但朝前/朝后反了 | 父、子接口的 +X 未按同一机械基准定义,绕 +Z 相差 180 度 |
对应接口的 origin rpy |
| 左右同一组件方向不同 | 左右父接口的 rpy 不同;程序如实继承完整坐标系 |
父组件左右接口的 CAD 坐标系与 origin rpy |
修改 axis 后拼装方向没有变化 |
axis 仅表示内部运动轴 |
改接口 Link 的坐标系,即 parent-to-child origin |
| 管理后台展示 J2/J3/J4 | 内部 child Link 误用了 LINK_* 命名 |
改内部 Link 名;只有真实接口使用规范名 |
本项目边界
当前装配只执行坐标系对齐,不会自动翻转、自动镜像、自动避让,也不会以碰撞结果修正姿态。URDF 中的接口坐标系是装配姿态的唯一机械来源;碰撞检测属于独立能力,需要在装配结果产生后按网格或简化碰撞体另行校验。