企业官网建设流程全解析

MuJoCo OpenUSD 集成完全指南：USD 导入、mjcPhysics 物理 Schema、MJCF 文件格式插件与 USD 导出

【免费下载链接】mujocoMulti-Joint dynamics with Contact. A general purpose physics simulator.项目地址: https://gitcode.com/GitHub_Trending/mu/mujoco

MuJoCo 通过实验性的 OpenUSD（USD, Universal Scene Description）支持，打通了与 3D 内容创作工具链（Houdini、Maya、Blender、Omniverse 等）之间的资产互操作通道。读完本文，你将掌握：如何在 MJCF 中以<model content_type="text/usd"/>加载.usd/.usda/.usdc/.usdz资产；如何构建并启用 MuJoCo 的 USD 支持（MUJOCO_WITH_USD构建开关）；mjcPhysics自定义 Schema 各 API 的类型划分与含义；MJCFSdfFileFormat文件格式插件如何让 USD 原生工具直接打开 MJCF 文件；以及当前 USD 导出的可行路径（USDExporter与mujoco-usd-converter）。

注意：MuJoCo 的 OpenUSD 支持目前处于实验阶段，接口和实现变动频繁（原文档每页顶部均带有该 WARNING 提示）。

1. OpenUSD 是什么，为什么 MuJoCo 需要它

USD 是 Pixar 开发的高性能、可扩展的 3D 场景描述、组合、模拟与协作框架，如今已广泛应用于视觉特效、动画、游戏和机器人等行业，充当不同软件之间交换 3D 场景信息的“通用语言”。

MuJoCo 集成 USD 的核心价值在于三点：

• 互操作性（Interoperability）：USD 被广泛的 3D 内容创作工具（Houdini、Maya、Blender 等）支持，MuJoCo 用户可以方便地导入在这些工具中创建的资产与场景；
• 丰富的场景描述（Rich Scene Description）：USD 能以强有力且灵活的方式表达复杂场景——几何、材质、光照、层级结构；
• 协作（Collaboration）：USD 的层级化（layering）与组合（composition）特性支持强大的非破坏性编辑流水线。

MuJoCo 的集成允许用户充分利用 USD 的丰富生态与工具链。

2. USD 支持总览：能力地图

MuJoCo 的 USD 支持由五个部分组成，对应仓库中不同的实现模块：

3. 构建与启用 USD 支持

MuJoCo 需要针对一个预构建的 USD 库进行编译。官方提供了辅助 CMake 项目来简化这一步骤，同时也允许你自带 USD 库。以下命令假设 MuJoCo 克隆在~/mujoco，构建目录为~/mujoco/build。

3.1 构建 USD 本体

如果已有预构建的 USD 库，可跳过此节。MuJoCo 自带一个 CMake 工程（见 openusd.cmake），它只会下载并构建 USD 所必需的功能子集：

cd ~/mujoco cmake -Bcmake/third_party_deps/openusd/build cmake/third_party_deps/openusd cmake --build cmake/third_party_deps/openusd/build

如需自定义构建流程，也可以用 USD 官方的build_usd.py脚本，建议使用位于克隆仓库之外的独立安装目录：

git clone https://github.com/PixarAnimationStudios/OpenUSD python OpenUSD/build_scripts/build_usd.py /path/to/my_usd_install_dir

3.2 启用 MuJoCo 的 USD 支持

若 USD 是通过cmake/third_party_deps/openusd项目构建的，直接用MUJOCO_WITH_USD开关即可：

cd ~/mujoco cmake -Bbuild -S. -DMUJOCO_WITH_USD=True cmake --build build -j 64

若使用自带（BYO）的预构建 USD 库，则必须额外传递pxr_DIR指向安装目录：

cd ~/mujoco cmake -Bbuild -S. -DMUJOCO_WITH_USD=True -Dpxr_DIR=/path/to/my_usd_install_dir cmake --build build -j 64

构建完成后运行simulate，即可直接拖拽 USD 文件进窗口查看：

simulate

3.3 源码侧的实现佐证

从源码结构看，实验性 USD 支持集中在 src/experimental/usd 目录下，按功能拆分为：

• mjcPhysics/——mjcPhysicsSchema 的完整定义（schema.usda、generatedSchema.usda）及由usdGenSchema预生成的 C++ 绑定，按 Schema 类型逐文件组织：actuator.cpp、sceneAPI.cpp、jointAPI.cpp、tendon.cpp、keyframe.cpp、materialAPI.cpp、collisionAPI.cpp、siteAPI.cpp、imageableAPI.cpp、各种equality*API.cpp等，插件元信息见 plugInfo.json；
• plugins/mjcf/——MJCFSdfFileFormat文件格式插件，核心是 mjcf_file_format.cc 与 MJCF→USD 转换逻辑 mujoco_to_usd.cc；
• writer.cc、layer_sink.cc、utils.cc——USD 图层写入与通用工具。

对应的构建条件在 src/experimental/usd/CMakeLists.txt 中声明。

4. USD 导入：在 MJCF 中引用 USD 资产

构建出启用 USD 的 MuJoCo 后，可以在 MJCF 中通过<model>标签并指定content_type="text/usd"来引用 USD 资产：

<mujoco> <asset> <model file="chair.usdz" name="chair" content_type="text/usd"/> </asset> <worldbody> ... </worldbody> </mujoco>

其中<model file="chair.usdz"/>这一行告诉 MuJoCo 加载并处理该 USD 文件。支持的扩展名包括.usd、.usda、.usdc、.usdz；除 MJCF 引用外，也可以直接把文件拖入simulate窗口加载。

5. mjcPhysics：MuJoCo 的自定义物理 Schema

mjcPhysics是 MuJoCo 提供的 USD Schema，用于在 USD 文件中直接、完整地描述 MuJoCo 模拟环境。其设计目标不是取代 UsdPhysics，而是在标准 UsdPhysics 概念之上做扩展，只在新类型确有必要时才创建。该 Schema 既支持 codeless 方式使用，也可使用其 C++ 绑定构建；MuJoCo 已通过usdGenSchema预生成代码（src/experimental/usd/mjcPhysics）供内部使用，但也可以在 MuJoCo 之外的原生 USD 应用（如 Omniverse、Houdini、Maya）中工作。

5.1 API Schemas

API Schema 施加在已有 prim 上，为它们附加语义与属性：

• MjcSceneAPI——提供 MuJoCo 模拟的全局选项，本质上是 MJCF 中<option>、<option/flag>、<compiler>三个元素的合并体，应施加在已有的UsdPhysicsSceneprim 上。关键命名空间属性：
  • mjc:option——映射到<option>元素；
  • mjc:flag——映射到<option/flag>元素；
  • mjc:compiler——映射到<compiler>元素。
• MjcSiteAPI——定义 MuJoCo site，可施加在UsdGeomSphere、UsdGeomCapsule、UsdGeomCylinder、UsdGeomCube上。
• MjcImageableAPI——为“纯视觉实体”提供属性，按 MuJoCo 的术语即contype = conaffinity = 0的几何。
• MjcCollisionAPI——施加在表示碰撞几何的 prim 上，应与UsdPhysicsCollisionAPI一起使用。
• MjcMeshCollisionAPI——施加在网格碰撞几何上，应与UsdPhysicsMeshCollisionAPI一起使用。
• MjcJointAPI——施加在UsdPhysicsJointprim 上，补充完整描述 MuJoCo 关节所需的额外属性。
• MjcMaterialAPI——提供物理材质属性，是UsdPhysicsMaterialAPI的扩展。

5.2 Type Schemas

Type Schema 是独立的 prim 类型：

• MjcActuator——表示 MuJoCo 执行器，通过 USD 的 relationship 指定施加力的传动目标（关节、body 或 site）。官方明确说明未复用UsdPhysicsDriveAPI，因为后者更接近运行时构造，概念映射并不贴合。
• MjcKeyframe——保存特定时刻的模拟器状态张量值，对应 MJCF 的<keyframe>元素。与 MJCF 不同，USD 侧用timeSamples机制表达时间属性；keyframe 中数值的顺序应按组合后 stage 中刚体的深度优先遍历顺序排列。
• MjcTendon——同时表达固定肌腱（fixed tendon）与空间肌腱（spatial tendon），对应 MJCF 的<tendon>。肌腱路径由mjc:pathrelationship 属性中有序的目标列表表示；由于 USD 的 relationship 上不像 MJCF 那样可以优雅地为每个路径目标附加sidesite、divisor等参数，这些参数被改造成索引化数组属性，如mjc:sideSites、mjc:path:divisors。

Schema 的具体声明可参考 schema.usda 与 generatedSchema.usda，各类型的属性读取与模型填充实现见同目录下同名.cpp文件（如 actuator.cpp、sceneAPI.cpp）。

6. MJCF 文件格式插件：让 USD 工具直接打开 MJCF

在 OpenUSD 框架中，Sdf（Scene Description Foundations）是负责场景数据序列化与组合的底层；SdfFileFormat插件则是教会 USD 读写某种特定文件格式的组件。USD 自带.usda/.usdc/.usdz的插件，社区也有 Adobe 等第三方文件格式插件。MuJoCo 的 MJCFSdfFileFormat插件（实现于 mjcf_file_format.cc，插件元信息见 plugInfo.json）让支持 USD 的应用能够把 MuJoCo 原生.xml（MJCF）文件当作 USD 图层来理解与交互。

它带来三种能力：

1. 在 USD 中引用 MJCF 文件：用标准 USD 组合弧（references、payloads 等）把 MJCF 文件直接嵌入更大的 USD 场景，例如把.xml定义的 MuJoCo 机器人放进一个 USD 建模的房间里；
2. 在 USD 工具中打开 MJCF 文件：usdview等工具可以打开、检查、渲染 MJCF 文件，插件会把 MJCF 元素即时翻译成 USD prim 与属性；
3. 把 MJCF 转换为持久 USD 文件：该插件也可以作为将 MJCF 转换为.usda/.usdc的基础。

6.1 实操示例

前置条件：已按第 3 节完成构建（安装步骤见前文）。

在.usda中引用 MJCF 文件（my_robot.xml为同目录下的 MJCF 文件，USD 会通过插件加载并解释其内容）：

#usda 1.0 ( upAxis = "Z" ) def Xform "world" { def "robot" ( prepend references = @./my_robot.xml@ ) { } }

在 usdview 中直接打开：

usdview my_robot.xml

插件配置正确时，usdview将直接渲染 MJCF 中定义的机器人。

在 Python 中用 USD API 打开：

from pxr import Usd # Load an MJCF file as a USD stage stage = Usd.Stage.Open('my_robot.xml') if stage: print(f"Successfully opened {stage.GetRootLayer().identifier}") # You can now inspect the stage as any other USD stage for prim in stage.TraverseAll(): print(prim.GetPath()) else: print("Failed to open MJCF file")

这个插件显著增强了 MuJoCo 与 USD 工作流之间的互操作性，使得以 MJCF 定义的物理资产能够无缝融入更广泛的 3D 环境——本质上让 MJCF 成为 USD 生态中的一等公民。

7. USD 导出

目前将 MuJoCo 场景导出为 OpenUSD 仍处于积极开发中，主要导出途径预期是 Python API。

• USDExporter：当前从 MuJoCo 导出 USD 的唯一方式是使用现有的USDExporter（Python API，实现位于 python/mujoco/usd/exporter.py，配套模块包括 objects.py、shapes.py、camera.py、lights.py，测试见 exporter_test.py）。官方正在开发将模拟作为动画写入现有 USD 场景的原生支持。
• mujoco-usd-converter：若要将既有 MJCF 资产转换为符合严格创作规范的 USD，官方推荐 Newton 项目提供的mujoco-usd-converter工具。转换出的资产不再引用原始 MJCF 文件，而是使用mjcPhysicsSchema 来忠实表达源资产。打开这些资产时，其效果应与 MJCF 文件格式插件生成的类似，但没有运行时将 MJCF 转换为 USD 的开销。

8. 延伸阅读

• 深入理解 USD 本身的入门资料：Remedy 的 USD 教程书（USD Book）、OpenUSD 官方文档（API 与实现细节）、Pixar 的 USD 入门示例，以及 NVIDIA 侧的 USD 资产结构资源，可从 OpenUSD 社区与官方渠道获取。
• 本仓库中与 USD 相关的实现与测试入口：src/experimental/usd（Schema 与插件）、python/mujoco/usd（Python 导出器）、test/experimental/usd（实验性 USD 测试）。

9. 要点回顾

1. MuJoCo 的 OpenUSD 支持是实验性特性，覆盖导入（MJCF<model content_type="text/usd"/>与拖拽）→ 物理 Schema（UsdPhysics + mjcPhysics 扩展）→ MJCF 文件格式插件 → 导出（USDExporter / mujoco-usd-converter）的完整链路；
2. 构建时需要预构建的 USD 库：用仓库自带 CMake 工程（cmake/third_party_deps/openusd）或pxr_DIR指定自建库，再以-DMUJOCO_WITH_USD=True配置 MuJoCo；
3. mjcPhysicsSchema 采用“API Schema 扩展 UsdPhysics + Type Schema 补齐 MuJoCo 独有概念（执行器、keyframe、tendon）”的设计，其属性命名空间（mjc:option/flag/compiler等）与 MJCF 元素一一对应；
4. MJCF 文件格式插件把.xml变成 USD 图层，是双向互操作的关键——它不仅让 MuJoCo 读 USD，也让 USD 世界读 MJCF，并可通过 converter 消除运行时转换开销。

【免费下载链接】mujocoMulti-Joint dynamics with Contact. A general purpose physics simulator.项目地址: https://gitcode.com/GitHub_Trending/mu/mujoco