Files
management/Management/docs/urdf-interface-coordinate.md

11 KiB
Raw Permalink Blame History

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 自动镜像网格。

导出前检查清单

  1. 每个可装配位置均创建规范命名的 LINK_* 接口 Link;不要只给 joint 命名。
  2. 接口原点位于实际安装基准面、孔中心或轴线中心,不要放在模型质心或网格原点。
  3. 对一条父子连接,父接口本体在局部 -Z 侧,子接口本体在局部 +Z 侧。
  4. 为接口指定明确的 +X 机械基准,确保拼装后孔位、前后方向和默认机构姿态正确。
  5. 接口固定在结构上时使用 type="fixed";内部运动关节仍按真实 revolute、continuous 或 prismatic 导出。
  6. URDF 以零位姿导出:手臂、腿等机构在默认状态应处于工程规定的直立或伸直姿态,不能依赖运行时关节角度校正。
  7. 上传后台后,在 URDF 预览中检查蓝色 +Z 和红色 +X。悬停接口可定位标记;绿色 +Y 仅供调试。
  8. 实际拼装两个组件后检查几何是否重叠。接口坐标系正确能保证定义的姿态正确,但不能替代几何碰撞校验。

常见错误与处理

现象 常见原因 应修改的位置
子组件完全进入父组件 子接口 +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 中的接口坐标系是装配姿态的唯一机械来源;碰撞检测属于独立能力,需要在装配结果产生后按网格或简化碰撞体另行校验。