URDF 到 MJCF 的映射与差异

本文档面向已将 ROS URDF 模型导入 MuJoCo 并需要精确理解两种格式语义差异的高级开发者。URDF（Unified Robot Description Format）与 MJCF（MuJoCo Composite Format）并非简单的同构转换，而是在运动学表达范式、仿真元数据和控制接口层面存在本质性的设计哲学分歧。以下分析基于本仓库中 urdf/atom01.urdf 与 mjcf/atom01.xml 的逐元素对照，揭示从运动学到动力学参数、从几何到控制接口的全链路映射规则与隐式陷阱。

Sources: atom01.urdf atom01.xml

架构范式：平面关联 vs 嵌套继承

URDF 采用平面链接-关节模型：<link> 与 <joint> 作为同级元素出现，关节通过 parent 与 child 属性显式声明父子关系。这种设计将拓扑信息与局部坐标变换解耦，适合 ROS 生态中基于 TF（Transform Frame）的分布式坐标查询。相比之下，MJCF 采用严格嵌套的身体树：子 <body> 必须物理嵌套在父 <body> 内部，<joint> 作为 body 的直接子元素存在，关节的局部坐标原点即子 body 的原点。这意味着 URDF 中 joint/origin 的平移量被映射到 MJCF 中子 body 的 pos 属性，而 joint/axis 与旋转限制则保留在 <joint> 元素内。

这种范式差异直接影响了坐标计算的数学形式。在 URDF 中，链式变换通过 joint origin 与子 link 内部原点组合得到；而在 MJCF 中，所有子 body 的几何体（<geom>）均以 body 原点为参考系，joint 的 pos="0 0 0" 表示关节轴位于 body 坐标系的原点。以 left_thigh_yaw_joint 为例，URDF 中 joint origin 为 xyz="-0.071093 0.0725 -0.051778"，这直接转化为 MJCF 中 left_thigh_yaw_link body 的 pos="-0.071093 0.0725 -0.051778"，而 joint 本身不再承载平移信息。

graph TD
    subgraph URDF平面结构
        A[base_link] --- J1[joint: left_thigh_yaw]
        J1 --- B[left_thigh_yaw_link]
        B --- J2[joint: left_thigh_roll]
        J2 --- C[left_thigh_roll_link]
    end
    
    subgraph MJCF嵌套结构
        D[worldbody] --> E[body: base_link]
        E --> F[joint: floating_base]
        E --> G[body: left_thigh_yaw_link<br/>pos=joint origin]
        G --> H[joint: left_thigh_yaw<br/>pos=0 0 0]
        G --> I[body: left_thigh_roll_link<br/>pos=joint origin]
        I --> J[joint: left_thigh_roll<br/>pos=0 0 0]
    end

Sources: atom01.urdf atom01.xml

核心元素映射总览

下表汇总了两种格式中承担相同物理语义的核心元素及其属性差异。

物理语义	URDF 元素/属性	MJCF 元素/属性	关键差异说明
刚体本体	`<link name="...">`	`<body name="...">`	MJCF body 强制嵌套；URDF link 平面并列
关节定义	`<joint type="revolute">`	`<joint type="hinge">`	MJCF 中 `revolute` 等价于 `hinge`，嵌套在 body 内
坐标变换	`<joint>/<origin>`	`<body pos="...">` + `<joint pos="...">`	URDF joint origin 映射为 MJCF 子 body pos
旋转轴	`<axis xyz="...">`	`<joint axis="...">`	语义一致，数值存在微小浮点差异
关节限位	`<limit lower="..." upper="...">`	`<joint range="...">`	多处限位范围不一致（见下节）
惯性张量	`<inertial>` + `<origin>` + `<mass>` + `<inertia>`	`<inertial pos="..." mass="..." fullinertia="...">`	MJCF 使用 `fullinertia` 六元组
视觉几何	`<visual>/<geometry>/<mesh>`	`<geom type="mesh"/>`	MJCF 通过 `class` 区分视觉/碰撞角色
碰撞几何	`<collision>/<geometry>`	`<geom>`（通过 contype/conaffinity 控制）	URDF 多数 mesh 碰撞被注释，使用简化几何
材质颜色	`<material>/<color rgba="...">`	`<geom rgba="...">` 或 `<material>`	MJCF 默认统一灰色，URDF 各 link 颜色独立
网格资源	`<mesh filename="...">`	`<asset>/<mesh file="...">`	MJCF 在 `<asset>` 中集中预声明

Sources: atom01.urdf atom01.xml

惯性参数：等价表示与顺序陷阱

惯性参数在两种格式间呈一一映射，但张量分量排列顺序存在陷阱。URDF 使用标准的 3×3 对称矩阵分量 ixx ixy ixz iyy iyz izz，而 MJCF 的 fullinertia 属性采用六元组格式 xx yy zz xy xz yz。以 base_link 为例，URDF 中 ixx="0.03052646" ixy="0.00000063" ixz="-0.00079063" iyy="0.01536233" iyz="0.00000026" izz="0.03006209" 对应到 MJCF 中即为 fullinertia="0.03052646 0.01536233 0.03006209 0.00000063 -0.00079063 0.00000026"。需要特别注意的是，惯性原点的 xyz 在 URDF 中位于 <inertial>/<origin>，而在 MJCF 中直接是 <inertial> 元素的 pos 属性，质量则均为 mass 属性。

Sources: atom01.urdf atom01.xml

关节限位与动力学参数的系统性偏移

这是从 URDF 迁移到 MJCF 时最容易被忽略的高风险区域。本仓库中 MJCF 的关节限位并非简单复刻 URDF，而是基于仿真需求进行了主动调整。下表列举了主要差异：

关节名称	URDF lower/upper	MJCF range	差异说明
`left_thigh_roll_joint`	-0.2 / 1.0	-0.2 / 2.0	上限放宽 1.0 rad
`left_thigh_pitch_joint`	-1.57 / 1.57	-2.5 / 0.8	对称限位改为非对称
`left_knee_joint`	-0.2 / 2.5	0 / 2.5	下限抬升至 0
`left_ankle_pitch_joint`	-0.6 / 0.6	-0.7 / 0.7	双侧各放宽 0.1 rad
`torso_joint`	-3.14 / 3.14	-2.62 / 2.62	范围收窄至 ±150°
`left_arm_pitch_joint`	-3.14 / 1.57	-3.14 / 2.57	上限放宽 1.0 rad
`left_arm_yaw_joint`	-1.57 / 1.57	-2.6 / 2.6	双侧大幅放宽
`left_elbow_pitch_joint`	-0.6 / 1.57	-1.0 / 3.57	上下限均大幅放宽
`right_thigh_roll_joint`	-1.0 / 0.2	-2.0 / 0.2	下限放宽（镜像差异）
`right_knee_joint`	-0.2 / 2.5	0 / 2.5	同左膝

这种限位调整通常源于强化学习训练或行走控制器对关节活动空间的额外需求。开发者在复用 URDF 运动学参数时，必须显式校验 range 值，否则会导致策略在 MuJoCo 中出现不可预期的关节锁死或限位碰撞。

此外，URDF 中 limit 元素的 effort 与 velocity 属性在 MJCF 中没有直接对应位点。MJCF 的 <motor> 执行器通过 ctrlrange="-200 200" 定义输出力矩边界，而速度限制在原生 MuJoCo 中通常由阻尼与电机力矩上限隐式约束。更关键的是，MJCF 引入了 URDF 完全不支持的关节动力学参数：<default class="leg_joint_param"> 中统一设置了 damping="0.01"、frictionloss="0.01" 和 armature="0.01"，且踝关节（left_ankle_pitch_joint、left_ankle_roll_joint 等）还额外覆盖了 frictionloss="0.05"。这些参数直接决定了仿真中的能量耗散特性，是 URDF 无法表达的。

Sources: atom01.urdf atom01.xml atom01.xml

碰撞几何策略：简化几何 vs 统一网格

URDF 与 MJCF 在碰撞几何的处理策略上呈现显著差异。在 URDF 中，大量连杆的 <collision> 块被注释掉（如 left_thigh_yaw_link、left_thigh_roll_link 等），仅对少数关键连杆保留了简化的碰撞体：大腿和小腿使用 <box>，躯干使用 <box>，手臂各关节使用 <cylinder>。这种策略旨在降低 Gazebo 或 ROS 碰撞检测的计算开销。而在 MJCF 中，没有显式定义单独的碰撞几何体，每个 body 仅包含一个 <geom type="mesh">。碰撞与视觉的区分是通过 <default> 中的 contype 与 conaffinity 以及 class 机制实现的——默认 geom 的 contype="1" conaffinity="0" 使其参与碰撞，而 class="visualgeom" 则将某些 geom 设为纯视觉（contype="0"）。

这意味着在 MJCF 中，所有带 mesh 的连杆均以其原始网格形态参与碰撞，而非 URDF 中的简化包围盒。这种差异可能导致在 MuJoCo 中仿真时接触点分布更密集、碰撞检测更精确，但也对网格质量（闭合性、流形性）提出了更高要求。

Sources: atom01.urdf atom01.xml

根节点与浮动基座

URDF 的 base_link 是隐式固定的世界坐标系参考点，不存在显式的根关节。MJCF 则将 base_link 置于 <worldbody> 内部，并显式声明了一个 <joint name="floating_base_joint" type="free" limited="false"/>。这使得机器人在 MuJoCo 中成为一个完整的 6 自由度浮动刚体系，可以在世界坐标系中自由平移与旋转。同时，MJCF 为 base_link 设置了初始悬浮高度 pos="0 0 0.75"（平地场景）或 pos="0 0 2.75"（地形场景），而 URDF 中 base_link 没有初始位置偏移，其几何原点即为模型原点。

Sources: atom01.xml

MJCF 的仿真专属扩展

MJCF 包含大量 URDF 完全不具备的仿真配置与控制接口元素，这些是本模型能在 MuJoCo 中运行的核心前提。

执行器系统：<actuator> 中为全部 22 个自由度配置了 <motor> 执行器，统一设置 gear="1" 与 ctrlrange="-200 200"。这意味着每个关节直接接收力矩指令，传动比为 1:1，最大输出力矩 200 N·m。

传感器系统：<sensor> 块配置了完整的本体感知阵列，包括：

每个关节的 actuatorpos（位置）、actuatorvel（速度）、actuatorfrc（力矩反馈），其中力矩传感器附加了 noise="1e-3"；
基于 imu site 的 framequat（姿态）、framepos（位置）、gyro（角速度，截止频率 34.9 rad/s）、velocimeter（线速度）、accelerometer（线加速度，截止 157 rad/s）和 magnetometer（磁强计）。

全局仿真参数：<option> 定义了 timestep="0.001"、solver="PGS"、iterations="100"，并启用了 frictionloss。<compiler> 指定了 angle="radian" 与 eulerseq="zyx"，确保角度单位与旋转顺序的一致性。

Sources: atom01.xml atom01.xml atom01.xml

颜色与视觉材质差异

URDF 中各连杆具有精细的配色方案，例如 base_link 为浅灰蓝（rgba="0.898 0.917 0.929 1"），手臂连杆为淡紫蓝（rgba="0.796 0.823 0.937 1"）。而 MJCF 中绝大多数连杆被统一设置为中性灰（rgba="0.752941 0.752941 0.752941 1"），仅少数连杆保留差异色。这种简化在强化学习训练中通常不影响策略学习，但在可视化调试时可能降低连杆辨识度。

Sources: atom01.urdf atom01.xml

关键差异的影响与迁移建议

基于上述映射分析，开发者在两种格式间迁移或同步模型时，应优先关注以下三个层级的差异：

运动学层级：坐标变换的数学等价性可通过脚本自动转换，但必须验证关节限位是否被人为修改；
动力学层级：MJCF 中的 damping、frictionloss、armature 是 URDF 的盲区，直接从 URDF 生成的 MJCF 将缺失这些参数，导致仿真中的关节行为过于理想化；
控制-感知层级：URDF 不包含执行器与传感器定义，迁移到 MuJoCo 时必须手动补充 <actuator> 和 <sensor> 块，否则模型虽可加载，但无法接收控制指令或输出状态观测。

若需进一步深化对 MJCF 模型设计原理的理解，可继续阅读 MJCF 模型设计原理；若关注关节动力学参数的调优实践，请参阅关节动力学参数调优。