跨后端共用 MJCF/XML 资产的实现机制:9 个物理后端的模型加载、字段支持度与渲染对应调查

[TATP-233]

跨后端共用 MJCF/XML 资产的实现机制调查(UniSim 1.4.0)

背景问题

UniSim 声称所有物理后端共用同一套 MJCF/XML 机器人与场景资产。但并非所有引擎原生支持 MJCF——Isaac 系传统上以 URDF/USD 为主,SuperDex 使用自有的 .superdex_bot 格式。我们对 unisim 仓库(src/unisim/backend/)全部 9 个适配器的资产加载链路做了逐行调查,本文汇报:每个后端如何加载模型、MJCF 字段支持到什么程度、不支持的参数如何处理、渲染如何对应。

一句话结论:整个链路中不存在 MJCF→URDF 转换,仓库内也没有任何 URDF 处理代码。 "共用 MJCF" 靠三种机制组合实现:

1. 引擎自带 MJCF importer(mujoco、motrix、mjwarp、drake、newton、genesis、isaacgym、isaacsim —— 8/9);
2. UniSim 手写翻译层(superdex:用 MuJoCo 包当纯解析器,把 mjModel 逐项映射成 SuperDex 原生 API);
3. MuJoCo 权威扫描兜底(newton、genesis、isaacgym、isaacsim):不信任 importer 会丢弃的物理参数(kv、frictionloss、joint range、keyframe、sensor 等),由 UniSim 用 MuJoCo 编译器或手写 ElementTree 扫描器在同一份 XML 上重建,再按名称对齐回引擎,不一致即 fail closed。

统一入口是 SceneCfg.model_file(MJCF 文件路径)+ fragment_files(场景片段)+ terrain(程序化地形)+ visual_model_file(渲染替身)。解析全部发生在构造/materialize 冷路径,step/reset 热路径不碰 XML。

逐后端机制

后端	MJCF 加载路径	转换方式	兜底机制
mujoco	MjModel.from_xml_path / MjSpec	原生,无转换	—(基准后端)
motrix	motrixsim.msd.from_file 原生吃 MJCF	无	keyframe 合并/注入由 UniSim 补齐
drake	drake_uni 改写 MJCF → Drake 原生 Parser	同格式改写(defaults 展开、STL→OBJ)	改写器 + fail closed
mjwarp	MuJoCo CPU 编译 → mujoco_warp.put_model	无(MuJoCo 家族)	fragment 合并/传感器注入
newton	newton.ModelBuilder.add_mjcf	无(引擎内置 importer)	MuJoCo 权威扫描 + 编译后 audit
genesis	gs.morphs.MJCF importer	无	MuJoCo 扫描补偿 keyframe/sensor/option
superdex	引擎不吃 MJCF	MuJoCo 解析 → UniSim 手写翻译成原生 API	白名单审计,超集即报错
isaacgym	worker 内 gym.load_asset(自带 MJCF importer)	无	宿主 ElementTree 扫描,按名对齐物理参数
isaacsim	worker 内 IsaacLab MjcfConverter → USD	MJCF→USD(引擎自带)	宿主 ElementTree 扫描,不信任 importer 动力学参数

mujoco(基准后端)

原生 MJCF 引擎,编译器全量字段直通。UniSim 只做 XML→XML 改写:物理模型 discardvisual="true" 剥离视觉(backend/mujoco/xml.py:17-33)、注入 frame 跟踪传感器、MjSpec.attach 组合地形场景、场景片段节点级合并。spot/target 灯被删除、普通灯强制 directional。不支持的语义(非 joint 传动、ball/free actuator 目标、越界 DR 项)全部 fail closed。

motrix

motrixsim 的 MSD 导入器原生解析 <mujoco> 风格 XML。UniSim 只补齐 keyframe 跨 fragment 合并(backend/motrix/scene.py:40-96)、程序化 hfield 地形(行序翻转对齐 MuJoCo 语义)、跟踪传感器注入。tendon/equality/材质/灯光等完全交给引擎解析器,UniSim 不干预。地形 geom 摩擦硬编码 [1.0, 0.005, 0.0001]。命名 keyframe 选择未实现(get_keyframe_qpos 恒返回第 0 个)。

drake

外部包 drake-uni 内的 materialize_drake_compatible_mjcf 做同格式改写:展开 default class 继承(Drake parser 不完整支持)、STL→OBJ 网格转换、删除 visual-only geom,再交给 Drake 原生 MJCF Parser。contact 固定 kPointContactOnly + SAP,solref/solimp 不进 Drake;general actuator 降级重写为 motor;ball 关节、tendon 传动、有状态执行器等一律 ValueError。Drake 侧零渲染,视频走 MuJoCo 离线渲染回放。

mjwarp

mujoco-warp 原生消费编译好的 MjModel,零格式转换。复用 mujoco/xml.py 做 fragment 合并与传感器注入。contact 参数(solref/solimp/friction/contype/conaffinity)全暴露且可 DR。hfield/地形显式拒绝;tendon/equality 无专门校验,交给上游 put_model 行为;无引擎渲染,回放走 MuJoCo CPU 视觉替身。

newton

双通道:MuJoCo 编译同一份 XML 作为"权威"元数据,newton.ModelBuilder.add_mjcf 做真实导入,编译后 audit_newton_model 对比布局/重力/质量,不一致即 RuntimeError。导入前显式拒绝会被 importer 静默曲解的几何:cone、碰撞三角 mesh(SolverMuJoCo 会凸包化)。ball 关节、tendon、equality、flex、hfield 全部 fail closed;solver/integrator 硬编码 newton/implicitfast,MJCF <option> 求解器设置不生效。

genesis

Genesis 1.3.3 自带 gs.morphs.MJCF importer,但实测会丢弃三类特性,UniSim 用 MuJoCo 扫描补偿:<keyframe> 整块、全局 <option>(仅 gravity 回读,integrator/solver 改为工厂显式参数)、整个 <sensor> 块(用 link 状态 + IMU 手工重算)。materialize 时交叉校验 dof/joint/link 顺序与增益,失配即 RuntimeError。contype/conaffinity 被引擎重新编码,不可与 MuJoCo 对照。terrain 不支持。

superdex(唯一无 MJCF importer 的后端)

引擎本身不解析 MJCF。链路:mujoco.MjModel.from_xml_path 纯解析(需要 mujoco extra 作为冷路径解析器)→ _audit_model 白名单审计 → 手写翻译成 ArticulatedActorParams 等原生 API;基本体几何经 trimesh 生成网格再 bake_sdf 烘焙成 SDF。白名单外一律 NotImplementedError:equality/tendon/flex/hfield/plugin、mesh 碰撞、关节 stiffness、gravcomp、显式 contact pair、condim>3(可 opt-in 降级为滑动摩擦 + RuntimeWarning)等。per-pair friction 用最小二乘分解补偿。渲染物理侧零消费,录像借道 MuJoCo 离线渲染器,交互用引擎原生 Polyscope(仅 serial + 单 env)。

isaacgym

子进程架构(worker 为 py3.8 + IsaacGym Preview 4)。worker 用自带 gym.load_asset MJCF importer;宿主手写 ElementTree 扫描器提取 importer 会丢的参数(kv、frictionloss、joint range、keyframe),按 joint 名对齐后写入 dof_props,名称顺序被 importer 改动即报错。仅支持单自由度关节 + freejoint、<position> actuator(gear=1、对称 forcerange)、6 种 sensor。contact <exclude> 无法复现 → 整体关闭自碰撞(legged_gym 生态标准近似)。solver 参数硬编码。场景 worldbody 元素(地板/灯/相机)不采用,地面是代码 add_ground。hfield/fragment/terrain 拒绝。

isaacsim

子进程架构(py3.11 Kit worker)。格式转换真实存在但是引擎自带:IsaacLab MjcfConverter 把 MJCF→USD,之后完全按 USD/PhysX 运行。宿主同样手写扫描兜底驱动参数。self-collision 固定关闭,contact exclude/equality/tendon/hfield 无映射;contact 传感器一律不支持(无 PhysX contact reporter,槽位恒 0)——这是 Isaac 系最大的功能缺口。渲染走原生 RTX,MJCF visual 随 converter 进 USD;相机不映射 MJCF <camera>,用球面跟踪参数自建 Pinhole 相机。

不支持参数的统一处理哲学

• fail closed 为主:所有后端对不支持的 MJCF 语义在冷路径报错(NotImplementedError/ValueError),几乎不静默忽略;文档明确"任何后端都不会被静默降级为另一个引擎"。
• 少数文档化降级:superdex 的接触近似(opt-in + warning)、isaacgym 的自碰撞整体关闭、drake 的 general→motor 重写、mujoco 系的灯光规范化。
• 默认补齐:缺省 forcerange→无限(1e20 哨兵)、kv/armature/frictionloss 缺省 0、无限位→±inf、无 actuator 关节=被动。
• 渲染解耦:物理与视觉分离是全局模式——mujoco 系 discardvisual + 视觉替身;drake/mjwarp/superdex 借道 MuJoCo 离线渲染;motrix/genesis/isaac* 用引擎原生渲染器;MJCF <camera> 普遍不映射,相机统一由 CameraCfg 参数化。

值得讨论的开放问题

1. Isaac 系接触传感器缺口:isaacsim contact 恒 0、isaacgym 自碰撞整体关闭,接触密集任务(灵巧手、loco-manipulation)的训练/评测会系统性失真,是否值得在 worker 内接 PhysX contact reporter?
2. solver/option 语义丢失普遍:drake(newton SAP 固定)、newton(isaacgym(硬编码 SimParams)都不消费 MJCF <option> 求解器设置。sim2sim 迁移时这是隐性的动力学漂移源,是否应在契约层暴露 per-backend solver 声明?
3. 字段支持度是隐式的:AdapterSpec 只有 name/extra/status,资产格式与 MJCF 子集支持度没有机器可读的声明。是否值得引入能力清单(如 supported_mjcf_features),让 UniLab 任务配置在选择后端时做静态校验?
4. superdex 手写翻译层的维护成本:9 个后端中唯一的全手写映射,白名单策略意味着每支持一个新 MJCF 特性都要改翻译层;是否考虑与 newton 类似的"MuJoCo 权威扫描 + audit"模式统一?

---

调查基于 unilabsim/unisim @ 1.4.0(src/unisim/backend/),所有结论均有文件:行号证据,可按需索取逐后端详细报告。