SceneSmith导出的3D场景如何接入MuJoCo和USD/Isaac Sim?导出与互操作完全指南
SceneSmith导出的3D场景如何接入MuJoCo和USD/Isaac Sim?导出与互操作完全指南
SceneSmith 是一个由 MIT 与丰田研究院(TRI)联合开发的智能体式(Agentic)室内 3D 场景生成框架(ICML 2026 Spotlight),能从一段纯文本自动产出可直接进仿真器的物理场景。生成完之后,很多新手最关心的问题就是:这些场景怎么导入 MuJoCo 机器人仿真器,又怎么转成 USD(Universal Scene Description) 喂给 NVIDIA Isaac Sim?本文给你一条"从场景目录到仿真器运行"的完整路径,包括一键导出命令、参数速查和常见的 pxr 冲突坑位。
SceneSmith 场景导出的起点:.dmd.yaml 是什么?
在动手之前先理解一件事:SceneSmith 的"原生格式"不是 GLB、不是 MJCF,而是 Drake 的 Directives 文件(.dmd.yaml)。
一次完整的场景生成(运行 main.py)会把结果写到按日期命名的输出目录,最终合并场景位于:
outputs/YYYY-MM-DD/HH-MM-SS/scene_000/combined_house/
├── house.dmd.yaml # Drake 场景描述(物体、位姿、关节)
├── house.blend # Blender 可视化文件
└── ...
而导出到 MuJoCo / USD 的入口只有一个脚本:scripts/export_scene_to_mujoco.py。它做的事情可以概括为三步:
- 读取场景目录(或单个
.sdf模型),解析其中的刚体、关节和纹理; - 生成一个自包含的 MuJoCo 目录:
scene.xml+meshes/(网格会按需转成 OBJ,纹理统一转成 PNG); - 用
mujoco.MjModel实际加载并跑 10 步仿真做导出后验证(检查 NaN、关节/几何数量),确保导出的场景真的能跑。
💡 提示:场景目录可能非常大。官方建议先用 scripts/clean_scene_output.py 清理掉与最终场景无关的中间文件,再执行导出。
最快配置方法:一键准备 MuJoCo 导出环境
MuJoCo 和 USD 导出不在主虚拟环境里,原因是两个依赖冲突:
mujoco没有装进主 venv;mujoco-usd-converter与 Blender(bpy)各自携带不兼容版本的 OpenUSD(pxr),同一环境里会打架。
官方给出的解法是单独建一个干净的虚拟环境,只需两条命令:
# 1. 一键创建 .mujoco_venv(Python 3.11 + mujoco-usd-converter)
./scripts/setup_mujoco_export.sh
# 2. 激活环境
source .mujoco_venv/bin/activate
这个脚本(scripts/setup_mujoco_export.sh)内部用 uv 建环境并按 scripts/requirements-mujoco-export.txt 安装固定版本依赖,关键版本锁定如下:
| 依赖 | 版本 | 说明 |
|---|---|---|
mujoco |
3.3.5 |
与 converter 严格匹配 |
mujoco-usd-converter |
0.1.0a3 |
MJCF → USD 转换核心 |
drake |
>=1.44.0 |
解析 .dmd.yaml / .sdf |
trimesh / lxml / numpy |
若干 | 网格转换与 XML 处理 |
一键导出:把场景目录变成 scene.xml
激活 .mujoco_venv 后,导出整个生成场景只需一条命令:
python scripts/export_scene_to_mujoco.py outputs/YYYY-MM-DD/HH-MM-SS/scene_000 \
-o mujoco_export
执行完成后你会得到:
mujoco_export/
├── scene.xml # 主 MJCF 文件(可直接被 MuJoCo 加载)
├── meshes/ # 所有网格与纹理(自包含,不依赖原场景目录)
└── usd/ # 加了 --usd 参数时才出现
然后立刻用 MuJoCo 自带查看器验证:
python -m mujoco.viewer --mjcf=mujoco_export/scene.xml
导出脚本默认还会自动运行验证:加载模型、步进仿真、检查 qpos/qvel 是否出现 NaN,并打印 body / joint / geom 统计。如果你确认场景没问题、想跳过这一步加速导出,可以加 --skip-validation。
常用导出参数速查表
以下参数均定义在 scripts/export_scene_to_mujoco.py:
| 参数 | 作用 | 典型场景 |
|---|---|---|
-o, --output |
指定输出目录(默认 scene_path/mujoco) |
控制产物位置 |
--sdf /path/to/model.sdf |
只转换单个 SDF 模型(如机械臂),不走场景目录 | 单独导出铰接模型 |
--static |
配合 --sdf 使用:基座不加 freejoint,作为固定刚体 |
导出机器人基座固定场景 |
--no-floor-plan |
排除地板与墙体 | 只要家具和可操纵物 |
--weld-furniture |
把家具焊死为静态(默认家具带 freejoint 可被推动) |
降低求解器负担 |
--usd |
额外导出 USD(生成 usd/ 子目录) |
接入 Isaac Sim |
--skip-isaac-sim-fix |
跳过 Isaac Sim 物理修复,保留 converter 原始输出 | 需要自行后处理时 |
--skip-validation |
跳过导出后的 MuJoCo 验证 | 批量导出提速 |
导出单个 SDF 模型(例如机械臂)
如果你手上只有一个 .sdf 模型(测试铰接结构很常用),不需要完整场景目录:
python scripts/export_scene_to_mujoco.py --sdf /path/to/model.sdf -o mujoco_export
# 想要 USD 版本
python scripts/export_scene_to_mujoco.py --sdf /path/to/model.sdf -o mujoco_export --usd
脚本会把 SDFormat 关节类型映射到 MuJoCo 等价关节:revolute/continuous → 铰链(hinge)、prismatic → 滑移(slide)、ball → 球关节,fixed 则直接焊接到父刚体(见 scripts/export_scene_to_mujoco.py 中的 SDF_TO_MJCF_JOINT_TYPE 映射表)。
USD / Isaac Sim 导出:一条 --usd 参数搞定
在 MuJoCo 导出的基础上,追加 --usd 就会触发 USD 转换流程(export_to_usd)。内部自动完成 4 件事:
- 预清洗 MJCF:USD 不支持 MuJoCo 的 checker 网格纹理,脚本会先删掉
grid纹理/材质和地面 geom,并把meshdir指向外层的meshes/; - 调用
mujoco-usd-converter把scene.xml转成 USD 阶段(stage),产物落在mujoco_export/usd/; - 修复纹理 tiling:converter 不会给
UsdUVTexture设置wrapS/wrapT,导致地面、墙面的 UV>1 坐标被裁剪而不是平铺。脚本会遍历Payload/MaterialsLibrary.usdc中所有着色器补上repeat模式; - Isaac Sim 物理修复:自动调用 scripts/fix_usd_isaac_sim.py 修复
Payload/Physics.usda。
第 4 步是 Isaac Sim 用户最关心的部分。converter 生成的 PhysicsFixedJoint 把物体连到一个没有刚体 API 的根节点,而 PhysX 要求关节两端都必须是合法刚体——后果就是所有物体被"拽"到原点 (0,0,0)。修复脚本按三类对象分别处理:
| 对象类别 | 示例 | 修复策略 |
|---|---|---|
| 静态物体 | 墙、桌子、床 | 移除全部物理 API 与关节,只留碰撞几何,Isaac Sim 视为静态碰撞体 |
| 动态物体 | 杯子、书本 | 拍平嵌套刚体:把 MassAPI 上移到外层 wrapper,删除内部 RigidBodyAPI 和内部 FixedJoint |
| 铰接物体 | 带门的衣柜、冰箱 | 把非法的"基础刚体"提升为真刚体、必要时重挂关节链、按 MuJoCo 的 <contact><exclude> 重建自碰撞过滤 |
如果只想手动执行物理修复,也可以单独跑:
python scripts/fix_usd_isaac_sim.py /path/to/scene/mujoco/usd
# 批量修复整个实验目录(16 个并行 worker)
python scripts/fix_usd_isaac_sim.py /path/to/SceneAgent_Cleaned --recursive --workers 16
在 Isaac Sim / usdview 中加载 USD
修复后的产物结构为:
mujoco_export/usd/
├── scene.usd # 入口 stage
└── Payload/
├── MaterialsLibrary.usdc # PBR 材质库(已修复 tiling)
└── Physics.usda # 物理刚体与关节(已修复)
把 mujoco_export/usd/scene.usd 拖进 NVIDIA Isaac Sim 或 usdview 即可。场景中的 PBR 材质(如仓库自带的石膏、木纹贴图)会随网格一起带入,例如 materials/Wood094_1K-JPG/Wood094_1K-JPG_Color.jpg 这类 1K 级颜色/法线/粗糙度贴图。
验证你的场景是否真的"simulation-ready"
导出完成 ≠ 万事大吉,建议按下面清单自查:
- ✅ MuJoCo 侧:
python -m mujoco.viewer --mjcf=mujoco_export/scene.xml能打开且物体无穿模、无飞散; - ✅ 日志无 NaN:验证步骤打印
Validation passed: X bodies, Y joints, Z geoms; - ✅ USD 侧:Isaac Sim 中物体停在原位(没有被吸附到原点),地面/墙面纹理正常平铺;
- ✅ 铰接对象:门、抽屉的关节可动且自碰撞过滤正确(衣柜类物体重点检查)。
项目还内置了针对这条管线的集成测试 tests/integration/test_usd_export_pipeline.py,它会对比"修复前 vs 修复后"的 USD 诊断指标,可作为理解导出管线的最佳参考代码。
常见问题(FAQ)
Q1:为什么我激活主环境后跑导出直接报 pxr / bpy 冲突?
这是预期行为——bpy(Blender)与 mujoco-usd-converter 各装一份 pxr,无法共存。脚本会在检测到 bpy 时主动提示你改用 .mujoco_venv。记住"主环境生成场景、.mujoco_venv 做导出"即可。
Q2:导出后家具在 MuJoCo 里会被撞倒,正常吗?
正常。默认给家具挂的是 freejoint(可自由运动)。如果只想让它当背景,加 --weld-furniture。
Q3:能不能只导物体、不导墙和地板?
可以,加 --no-floor-plan,适合把单房间内容搬进已有仿真环境。
Q4:导出到 Isaac Sim 后物体全飞到原点?
说明 Physics.usda 里的 FixedJoint 问题没修。确认导出时没加 --skip-isaac-sim-fix,或手动补跑一次 scripts/fix_usd_isaac_sim.py。
⚠️ 官方提示:MuJoCo 与 USD/Isaac Sim 导出目前仍标记为 experimental,不同仿真器间场景表现可能略有差异,欢迎反馈与贡献新的导出目标。
相关文件速查
- 导出主脚本:scripts/export_scene_to_mujoco.py
- 一键环境准备:scripts/setup_mujoco_export.sh
- 导出依赖清单:scripts/requirements-mujoco-export.txt
- Isaac Sim 物理修复:scripts/fix_usd_isaac_sim.py
- USD 导出集成测试:tests/integration/test_usd_export_pipeline.py
- 场景清理(导出前瘦身):scripts/clean_scene_output.py
按照"建 venv → 跑导出 → 加 --usd → 修物理 → 进仿真器"这条主线走一遍,你的 SceneSmith 场景就能在 MuJoCo 和 Isaac Sim 里动起来了。


