usd-composition-architecture

Isaac Sim の USD 構成アーキテクチャ

目的

NVIDIA の構成規約に従って、レイヤー化されたペイロード（ベース、インスタンス、マテリアル、物理、ロボット）を使用し、シミュレーションですぐに使える USD を作成します。

前提条件

• スタンドアロン構成には、OpenUSD と対応する Foundation ディストリビューションが必要です。
• Asset Transformer UI、またはホイールのステージング、ライブ 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 の物理編集が反映されない原因を診断する。
• ジョイントの制限、質量、またはソルバーパラメーターをデバッグする。
• 既存のアセットのバリアント（構成、マテリアル）を作成する。

基本概念：1 つのバイナリクレートと複数の USDA レイヤー

Isaac Sim で推奨されるアセット構造では、ロボットを 1 つのバイナリジオメトリクレートと一連の 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 の最適化における重要な要素です。

ファイル形式の選択ガイド

ルールはシンプルです。生のメッシュデータにはバイナリクレート（.usdc）、それ以外はすべて USDA を使用します。 Asset Transformer の GeometriesRoutingRule が、この振り分けを自動的に適用します。

レイヤー	形式	理由
geometries.usdc	.usdc（バイナリクレート）	メッシュのトポロジー、点、インデックスなど、大量の数値データを格納します。手作業では編集しません
base.usda	.usda	階層とトランスフォームを格納します。差分を確認でき、手作業で編集できます
instances.usda	.usda	メッシュを参照し、マテリアルと衝突近似の選択を適用します
materials.usda	.usda	マテリアルの prim と MDL シェーダーのバインディングを格納し、ルック開発で読みやすくなっています
physics.usda / physx.usda / mujoco.usda	.usda	ジョイントの制限、質量、ソルバーパラメーターなど、頻繁に調整する項目を格納します
robot.usda	.usda	Isaac ロボットスキーマのメタデータと関係を格納します
interface.usda	.usda	構成アーク（参照、ペイロード、バリアント）を格納するエントリーポイントです
テクスチャアセット	元の形式（PNG、JPG、EXR）＋ .mdl	Textures/ の下に保存します
アーカイブ／ポータブル形式	.usdz	単一ファイルで配布します（iOS AR）

理由： メッシュ配列はサイズが大きく、手作業で編集することはないため、バイナリクレートを使うとファイルサイズと読み込み時間を抑えられます。それ以外のデータは小さく、頻繁に確認するため、バージョン管理で差分を確認でき、人とエージェントの両方が編集できる形式が適しています。

この構造の生成：Asset Transformer

Asset Transformer（Isaac Sim Structure プロファイル）を使用して、インポートした URDF/MJCF アセットを上記のレイアウトに変換します。関連するルールは次のとおりです。

• GeometriesRoutingRule — メッシュ prim を geometries.usdc（バイナリ）に抽出し、instances.usda にインスタンス化可能な参照を作成します。base を ASCII のまま保持するには、save_base_as_usda: true を設定します。
• MaterialsRoutingRule — マテリアルの重複を排除して materials.usda にまとめ、テクスチャを Textures/ にコピーします。
• SchemaRoutingRule — physics、physx、mujoco、robot のスキーマを、それぞれの USDA レイヤーに分割します。
• InterfaceConnectionRule — コンポジションアークを含む interface.usda を生成します。

パイプライン全体については、Asset Transformer Rules Reference を参照してください。

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 専用のオピニオンを中立的な物理定義の上に重ねます。

ヘッドレス RL の最適化：外観をスキップする

RL トレーニングの起動時に最も大きな最適化となるのは、外観ペイロードを読み込まないことです。

Isaac Lab が RL 用のロボットを読み込む際は、次の処理を行います。

1. 読み込むもの：interface.usda と base、および物理レイヤー（ジョイント、質量、衝突形状）。
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

物理 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}")