教程/MuJoCo Menagerie·14 天前

从 URDF 到 MuJoCo MJCF：碰撞网格简化、执行器增益标定与 Menagerie 对齐指南

把厂商 URDF 转为可仿真 MJCF：精简 mesh 碰撞、按 Menagerie 惯例写 actuator、用 identify 流程标定 PD 增益。

• 仿真与训练
• 数据与采集

HStretch机器人

URDF 描述的是 kinematic tree 与惯性，MJCF 还要显式声明 solver、contact 与 actuator。很多 RL 仓库直接读 Menagerie，是因为这些隐含参数已经调通。自行从 URDF 转换时，推荐路径是：先用官方或社区转换脚本生成初版 XML，再手工对照 Menagerie 同名机型 diff，而不是从零写标签。

获取 URDF 与参考 MJCF

从 Menagerie 克隆对应机型目录，对照 hello_robot_stretch_3/stretch.xml 与官方 URDF 的 link 命名。新建工作目录，复制 Menagerie 的 assets 子树以避免重复造 mesh。Menagerie 的 MJCF 经过维护者验证，可作为「金标准」：你的 URDF 转译结果应在相同初始 pose 下与 Menagerie 模型质心高度误差小于 1cm。若厂商 URDF 含 mimic 或连续关节，MuJoCo 侧需改成等效 equality 或拆分 tendon。

惯性核对

转换后逐 link 对比 URDF 的 <inertial> 与 MJCF 的 <inertial mass="..." diaginertia="..."/>，总质量误差应小于 2%。若 URDF 缺 inertia，不要填单位矩阵，应先用 SolidWorks 或 mesh 体积分估算。质心偏移 1cm 会在 locomotion 里放大成步态前后晃。移动操作机型还要核对 wheel 与 ground 的初始间隙，避免一加载就产生巨大接触力脉冲。

碰撞简化

URDF 常用 high-poly STL 作 collision；MuJoCo 仿真应换 primitive 或 decimate mesh（目标面数 <5k/ link）。在 <asset> 注册后，<geom type="mesh" contype="0" conaffinity="0" group="1"/> 仅视觉，碰撞 geom 用 capsule/box 近似。自碰撞在 URDF 里常被忽略，仿真里要对相邻 link 设 contype/conaffinity 掩码，否则手臂折叠时会数值爆炸。地面 contact 建议用 <geom name="floor" type="plane" size="0 0 1"/>，摩擦系数与 RL 论文设定一致并写进 README。

执行器与增益

Menagerie 惯例：每关节 <position kp="..." kv="..." forcerange="..."/>。初值可从 URDF effort/velocity limit 反推，再在 0.5kg 负载下微调：

python -m mujoco.viewer --mjcf stretch.xml

记录阶跃响应超调；超调 >10% 则略增 kv。若关节在零位附近振荡，多半是 kp 过大或 timestep 过大；Menagerie 模型多用 timestep="0.002"。forcerange 必须覆盖真实峰值力矩，否则 RL 策略会学到「顶饱和」的伪最优。对 gripper 使用 <position> 驱动时，记得把 ctrlrange 与 joint range 对齐，并在 keyframe 里给出半开夹爪的中性位。

与 RL 训练对齐

导出 keyframe 站立姿态，质量与 URDF <inertial> 一致。若用 MJX，确认 mesh 为 convex 或启用 sdf 选项。提交前跑 Menagerie 自带 simulate 示例 60s 无 NaN。

校验清单

link 树无断链；joint 限位与 URDF 相同；actuator ctrlrange 与 joint range 一致；地面 contact 无初始穿透。提交 Menagerie PR 前，用 tests/ 里同类模型的惯例补 README 与 thumbnail 路径。与 Isaac Lab 互通时，可导出 USD 但质量属性仍以 MJCF 为准做交叉验证。常见失败案例：STL 单位是毫米未缩放、关节 axis 未归一化、以及把 fixed joint 写成 zero-length slide。修完上述项后再跑 60s 随机 torque 测试，无 NaN 即可进入 RL 管线。

工具链与版本

MuJoCo 3.x 与 2.x 的 compiler 默认值不同，团队内应统一版本。可用 simulate 加载模型后查看 Contact 计数，初始帧若上千 contact 说明 mesh 穿透。对移动底盘，把 wheel 与 body 的 friction 分开设，否则 sim 里会出现 unrealistically 高的侧向抓地。最后把 MJCF、mesh 哈希与 kp/kv 表一并存档，真机辨识后回写 sim，闭环 sim2real 才有依据。Stretch 一类移动操作平台还要检查 castor 是否建模为 ball joint；忽略 castor 会导致导航 sim 里转向刚度与真机不符，Nav2 参数迁移会系统性偏乐观。建议为每个新机型建立最小 regression：自由落体 1s、单关节阶跃、全零 pose 站立各一项，CI 里自动跑，防止后续 PR 悄悄改坏 contact。文档里注明 Menagerie 上游 commit，便于将来 rebase 官方更新时不丢失本地辨识参数。合并冲突时优先保留 Menagerie 的 contact 默认值，再叠加本地 kp/kv 覆盖层。完成转换后请同事交叉 review 一遍 XML，单人改 inertia 很容易手滑。

来源

本页事实对应的公开页面，以原文为准。

1. MuJoCo Menagerie访问 2026-10-14
2. MuJoCo Modeling访问 2026-10-14