usd-composition-architecture

Isaac Sim 的 USD 组合架构

目的

按照 NVIDIA 组合约定，使用分层载荷（基础、实例、材质、物理、机器人）创作可直接用于仿真的 USD。

前置条件

• 独立组合需要 OpenUSD 和匹配的 foundation 发行版。
• 仅在使用 Asset Transformer UI 或进行 wheel 暂存、实时 Kit 场景、MDL 或渲染器验证时，才需要已构建的 Isaac Sim。

限制

• 除非某个部分另有说明，否则适用于 Isaac Sim 6 / Kit 110。
• 不能替代 NVIDIA 官方文档，也不涵盖其中不支持的边缘情况。

故障排除

错误 / 现象	原因	解决方案
画面全黑或为空	缺少灯光，或渲染模式不是 RTX	添加穹顶灯 / 主光；确认 RTX / PathTracing 设置
加载场景或首次渲染时卡住	MDL 编译或场景过大	按照 isaac-sim-troubleshooting 中的隔离步骤操作

组合执行路径

isaacsim.foundation.usd.openusd 后端可在普通库环境中运行，并已测试引用和变体操作。独立的 isaacsim.foundation.usd.ovstage 后端目前不支持添加引用或获取、设置变体；请在模块测试中确认功能一致性。

Asset Transformer UI、实时 omni.usd 上下文、Kit 命令、MDL、渲染和扩展生命周期仍需依赖 Kit。

适用场景

• 构建新的机器人或环境资产。
• 使用 Asset Transformer 重构现有资产。
• 优化 RL 训练的启动时间和 VRAM 占用。
• 诊断 USDA 中未生效的物理编辑。
• 调试关节限位、质量或求解器参数。
• 为现有资产创建变体（配置、材质）。

核心概念：一个二进制 crate，多个 USDA 层

Isaac Sim 推荐的资产结构是将机器人拆分为一个二进制几何 crate 和一组 ASCII 层，并通过 interface.usda 进行组合：

{robot}/
    interface.usda                         <- Final composed asset (entry point)
    payloads/
        base.usda                          <- Simulation-ready hierarchy + xforms
        geometries.usdc                    <- Mesh data ONLY (binary crate)
        instances.usda                     <- Mesh + material + collider assembly
        materials.usda                     <- Material defs (MDL bindings)
        Textures/                          <- Texture assets
        robot.usda                         <- Isaac robot schema + metadata
        Physics/
            physics.usda                   <- Neutral USD/Newton physics
            physx.usda                     <- PhysX-only tuning (sublayers physics.usda)
            mujoco.usda                    <- MuJoCo-only tuning (sublayers physics.usda)

USD 的 payload 弧支持延迟加载——只有在明确请求时才会加载载荷。这是优化无头 RL 的关键。

文件格式选择指南

规则很简单：原始网格数据使用二进制 crate（.usdc），其他内容均使用 USDA。 Asset Transformer 的 GeometriesRoutingRule 会自动执行这种划分。

层	格式	原因
geometries.usdc	.usdc（二进制 crate）	网格拓扑、点、索引——大量数值数据，从不手动编辑
base.usda	.usda	层级结构和变换——便于比较差异，可手动编辑
instances.usda	.usda	引用网格 + 应用材质 + 选择碰撞近似方式
materials.usda	.usda	材质 prim、MDL 着色器绑定——便于查看外观开发内容
physics.usda / physx.usda / mujoco.usda	.usda	关节限位、质量、求解器参数——需要频繁调整
robot.usda	.usda	Isaac 机器人 schema 元数据和关系
interface.usda	.usda	组合弧（引用、载荷、变体）——入口点
纹理资产	原始格式（PNG、JPG、EXR）+ .mdl	存储在 Textures/ 下
归档 / 便携格式	.usdz	单文件分发（iOS AR）

理由： 网格数组很大且从不手动编辑，因此二进制 crate 在文件大小和加载时间方面更有优势。其他内容都较小、需要频繁检查，适合在版本控制中比较差异，也便于人类和 Agent 编辑。

生成此结构：资产转换器

使用资产转换器（Isaac Sim Structure 配置文件）将导入的 URDF/MJCF 资产转换为上述布局。相关规则：

• GeometriesRoutingRule — 将网格 prim 提取到 geometries.usdc（二进制文件），并在 instances.usda 中创建可实例化引用。设置 save_base_as_usda: true 可将 base 保留为 ASCII 格式。
• MaterialsRoutingRule — 将材质去重并写入 materials.usda，将纹理复制到 Textures/。
• SchemaRoutingRule — 将 physics、physx、mujoco 和 robot 架构拆分到各自的 USDA 图层中。
• InterfaceConnectionRule — 使用组合弧生成 interface.usda。

完整流程请参阅资产转换器规则参考。

Physics USDA 架构

physics.usda — 关节和质量定义

#usda 1.0

def PhysicsRevoluteJoint "FL_hip_joint" {
    uniform token physics:axis = "X"
    float physics:lowerLimit = -46.0
    float physics:upperLimit = 46.0
    rel physics:body0 = </Robot/trunk>
    rel physics:body1 = </Robot/FL_hip>
}

def RigidBodyAPI "trunk" {
    float physics:mass = 4.713
    point3f physics:centerOfMass = (0.012, 0.002, -0.002)
    float3 physics:diagonalInertia = (0.0120, 0.0220, 0.0270)
}

physx.usda — 仅限 PhysX 的调优设置

#usda 1.0

def PhysxJointAPI "FL_hip_joint" {
    float physxJoint:maxJointVelocity = 20.0
    float physxJoint:jointFriction = 0.05
}

def PhysxRigidBodyAPI "trunk" {
    bool physxRigidBody:enableGyroscopicForces = true
    float physxRigidBody:maxDepenetrationVelocity = 10.0
    int physxRigidBody:solverPositionIterationCount = 32
    int physxRigidBody:solverVelocityIterationCount = 1
}

physx.usda 通常会将 physics.usda 设为子图层，使仅限 PhysX 的意见叠加在通用 physics 定义之上。

无头 RL 优化：跳过外观

RL 训练启动时，最大的优化是：不加载外观载荷。

Isaac Lab 为 RL 加载机器人时：

1. 加载：interface.usda + base + physics 图层（关节、质量、碰撞形状）。
2. 跳过：materials.usda 和 Textures/（与物理仿真无关）。

ArticulationCfg(
    spawn=sim_utils.UsdFileCfg(
        usd_path=f"{ASSETS_ROOT}/Robots/MyRobot/interface.usda",
        activate_contact_sensors=True,
        # Do NOT load appearance payloads for RL
        visual_material=None,
    )
)

组合弧优先级

USD 按以下顺序应用意见（对于大多数属性，最后应用的意见优先）：

Sublayers < Reference < Payload < VariantSet < Direct opinions

如果 physics USDA 的更改“没有生效”，请检查覆盖意见是否位于优先级更高的图层中。

常见调试问题

from pxr import Usd
# Find which layer is setting a specific property
attr = prim.GetAttribute("physics:mass")
for spec in attr.GetPropertyStack(Usd.TimeCode.Default()):
    print(f"  Layer: {spec.layer.GetDisplayName()} = {spec.default}")