# 从 URDF 到 MuJoCo MJCF：碰撞网格简化、执行器增益标定与 Menagerie 对齐指南 > 原文链接：https://robotics.hellobike.com/tutorials/mujoco-menagerie-urdf-to-mjcf-guide > 频道：tutorials | 更新日期：2026-10-14 | 标签：MuJoCo, MJCF, URDF, Menagerie > 核心摘要：把厂商 URDF 转为可仿真 MJCF：精简 mesh 碰撞、按 Menagerie 惯例写 actuator、用 identify 流程标定 PD 增益。 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 的 `` 与 MJCF 的 ``，总质量误差应小于 2%。若 URDF 缺 inertia，不要填单位矩阵，应先用 SolidWorks 或 mesh 体积分估算。质心偏移 1cm 会在 locomotion 里放大成步态前后晃。移动操作机型还要核对 wheel 与 ground 的初始间隙，避免一加载就产生巨大接触力脉冲。 ## 碰撞简化 URDF 常用 high-poly STL 作 collision；MuJoCo 仿真应换 primitive 或 decimate mesh（目标面数 <5k/ link）。在 `` 注册后，`` 仅视觉，碰撞 geom 用 capsule/box 近似。自碰撞在 URDF 里常被忽略，仿真里要对相邻 link 设 contype/conaffinity 掩码，否则手臂折叠时会数值爆炸。地面 contact 建议用 ``，摩擦系数与 RL 论文设定一致并写进 README。 ## 执行器与增益 Menagerie 惯例：每关节 ``。初值可从 URDF effort/velocity limit 反推，再在 0.5kg 负载下微调： ```bash python -m mujoco.viewer --mjcf stretch.xml ``` 记录阶跃响应超调；超调 >10% 则略增 kv。若关节在零位附近振荡，多半是 kp 过大或 timestep 过大；Menagerie 模型多用 `timestep="0.002"`。forcerange 必须覆盖真实峰值力矩，否则 RL 策略会学到「顶饱和」的伪最优。对 gripper 使用 `` 驱动时，记得把 ctrlrange 与 joint range 对齐，并在 keyframe 里给出半开夹爪的中性位。 ## 与 RL 训练对齐 导出 `keyframe` 站立姿态，质量与 URDF `` 一致。若用 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 很容易手滑。 ## 原始参考来源 (Sources) - [MuJoCo Menagerie](https://github.com/google-deepmind/mujoco_menagerie) - [MuJoCo Modeling](https://mujoco.readthedocs.io/en/stable/modeling.html)