usd-pipeline

USD アセットパイプライン

目的

アセットを検出し、バウンディングボックスとシェーダーを測定し、プレースホルダーを置き換え、オフセットを補正して、レンダリング前にヘッドレスでのシェーダー互換性を検証します。

前提条件

• スタンドアロンで USD の検査・作成を行う場合：source/libraries のビルドが完了しているか、対応する基盤ディストリビューションがインストールされていること。
• Kit のライブステージ、アセットサービス、MDL、またはレンダリングを利用する場合：Isaac Sim をビルドし、isaac-sim-orchestrator の環境を使用すること。GPU の要件は利用経路によって異なります。

制限事項

• 特に記載がない限り、Isaac Sim 6 / Kit 110 を対象とします。
• サポート対象外の特殊なケースについては、NVIDIA の公式ドキュメントに代わるものではありません。

トラブルシューティング

エラー／症状	原因	解決策
フレームが黒い、または空になる	ライトがない、または非 RTX のレンダーモード	ドームライト／キーライトを追加し、RTX／PathTracing の設定を確認します
ステージの読み込み中または初回レンダリング時に停止する	MDL のコンパイル、またはステージのサイズが大きすぎる	isaac-sim-troubleshooting の切り分け手順に従います

スタンドアロン USD と Kit ライブステージ

サポート対象のスタンドアロン OpenUSD ステージ、オブジェクト、プリム、ユーティリティの処理には、source/libraries/isaacsim/foundation/ の isaacsim.foundation.usd.openusd またはスタンドアロンの isaacsim.foundation.usd.ovstage バックエンドに加えて、isaacsim.foundation.objects、isaacsim.foundation.prims、isaacsim.foundation.utils を使用します。

omni.usd、Kit アセットサービス、MDL、ビューポート／レンダリング、コマンド、ライブステージとのインタラクションは、Kit の経路でのみ使用してください。

利用可能なスクリプト

スクリプト	目的	引数
scripts/articulation_builder.py	物理ジョイントを使った USD アーティキュレーションツリーの構築を支援します	スクリプトの --help を参照
scripts/measure_asset.py	USD アセットのバウンディングボックス、シェーダーの種類、プリム数を測定します	スクリプトの --help を参照
scripts/place_assets.py	バウンディングボックス中心のオフセットを補正しながら、ブロック位置に USD アセットを配置します	スクリプトの --help を参照

スクリプトの実行

スキル実行ヘルパーを利用できるエージェントランタイムからは、run_script() を使ってヘルパーを呼び出します。

run_script("scripts/articulation_builder.py", args=["--help"])

ビルド済みの Isaac Sim ツリーからは、_build/*/release にある ./python.sh（Linux）または python.bat（Windows）で同じファイルを実行します。また、シミュレーターを必要としない場合は、シェルヘルパーを直接実行できます。

使用する場面

• フォルダーツリー内の USD アセットをカタログ化する場合（サイズ、シェーダー、プリム数）。
• プレースホルダーの形状（キューブ／球体／バウンディングボックス）を実際のアセットに置き換える場合。
• モジュール式ライブラリからセットドレッシング済みのシーンを構築する場合。
• ヘッドレスレンダリングとの互換性（MDL と UsdPreviewSurface）を検証する場合。
• キューブのプロトタイプを実際のアセットに置き換えるワークフロー。

基本概念

プレースホルダーからアセットへのパイプライン

実環境の USD シーン構築では、次のパターンに従います。

1. キューブでプロトタイプを作成する — 色付きの UsdGeom.Cube メッシュを使って空間ゾーンをレイアウトします
2. アセットをカタログ化する — 候補となる USD アセットをすべて測定します（バウンディングボックス、シェーダー、プリム数）
3. ブロックとアセットを対応付ける — プレースホルダーの種類を、適切なサイズの実アセットに対応付けます
4. オフセットを補正して配置する — アセットのバウンディングボックス中心のオフセットを補正しながら、ブロック位置にアセットを参照します
5. レンダリングを検証する — ビジョンモデルとドメインエキスパートによるスコアリング
6. 反復する — はみ出し、通路への侵入、スケールの不一致を修正します

バウンディングボックスのオフセット補正が重要な理由

ほとんどの USD アセットは原点を中心としていません。たとえば、ラックアセットのバウンディングボックス中心が (46.7, 104.6, 4.5) にあるとします。補正せずに目標位置 (112.0, 20.0, 0.0) に配置すると、目的の位置より東に 46.7 m、北に 104.6 m ずれて配置されます。

数式：

translate_x = target_x - asset_bbox_center_x
translate_y = target_y - asset_bbox_center_y
translate_z = -asset_bbox_min_z  (puts asset base on ground plane)

フェーズ 1：アセットの検出と測定

スクリプトのパターン（Kit Python — レンダラー不要）

measure_asset(path) — USD ファイルを開き、バウンディングボックスを計算し、UsdPreviewSurface シェーダーを検出して、プリム数を数えます。width／depth／height／center／mpu／prims／dual_shader／shader_tag を含む辞書を返します。catalog_assets(root_dir, extensions) — すべての USD アセットを再帰的に検索して測定します。

scripts/measure_asset.py を参照してください。

主な学び

• Sdf.Layer.FindOrOpen() ではなく Usd.Stage.Open() を使用します — Sdf はバイナリの .usd クレートファイルで黙って失敗し、デフォルトの mpu=1.0 を返します
• 必ず mpu を確認します — cm（mpu=0.01）を使用するアセットもあれば、メートル（mpu=1.0）を使用するアセットもあります。測定値はそれに応じてスケーリングしてください。
• 無効な bbox（min > 1e30） は、アセットが合成されていないことを意味します。通常は参照またはペイロードが欠落しています。
• Kit Python（kit/python/bin/python3）は測定に最速です。レンダラーの起動は不要です。
• Kit ランタイム（SimulationApp）で bbox を取得するには、一時 prim に参照を定義し、数フレーム更新してから bbox を計算します。複雑な合成では、こちらの方が信頼性が高くなります。

フェーズ 2：シェーダー互換性の確認

ヘッドレス arm64 での MDL の問題

シェーダーの種類	ヘッドレス SimulationApp	Isaac Sim GUI	OVRTX
UsdPreviewSurface のみ	レンダリングされる	レンダリングされる	レンダリングされる
MDL + UsdPreviewSurface（デュアル）	Preview にフォールバック	MDL を使用	MDL を使用
MDL のみ（sourceAsset）	黒くなる	レンダリングされる	レンダリングされる
マテリアルなし	灰色／不可視	灰色	灰色

ルール： ヘッドレスレンダリングパイプラインでは、UsdPreviewSurface フォールバックを備えたアセット（デュアルシェーダー）またはネイティブの UsdPreviewSurface のみを使用してください。

Xvfb の発見

ロックされた実ディスプレイ :0 の代わりに、DISPLAY=:99（Xvfb 仮想フレームバッファー）で Isaac Sim を実行すると、一部の MDL アセットで黒くないレンダリング結果が得られます。完全に信頼できる方法ではありませんが、試す価値はあります。

# Start Xvfb
Xvfb :99 -screen 0 1920x1080x24 &>/dev/null &

# Run with virtual display
DISPLAY=:99 isaac-sim.sh --exec script.py

デュアルシェーダーアセットの特定

USD 内で次のパターンを探します。

• 任意の Shader prim で info:id = "UsdPreviewSurface" → ヘッドレス環境で安全
• UsdPreviewSurface の兄弟 prim を伴わない info:mdl:sourceAsset → MDL のみで、ヘッドレス環境では安全ではない
• Lightspeed で処理されたアセットは、通常 MDL のみ
• 「Collected」Dematic アセットは、多くの場合デュアルシェーダー

フェーズ 3：プレースホルダーからアセットへのマッピング

戦略

1. プレースホルダーのキューブを名前の接頭辞ごとにグループ化します（例：CvL001→CvL、BRk045→BRk）
2. 各接頭辞について、次の条件に基づいて最適なアセットを探します。
   • 機能が似ている（ラックにはラックのアセット、コンベヤーにはコンベヤーのアセット）
   • サイズに互換性がある（アセットがプレースホルダーの領域から大幅にはみ出さない）
   • デュアルシェーダーに対応している（ヘッドレスレンダリング要件）
3. 構築前にマッピングテーブルを記録します

マッピングテーブルの形式

| Block Prefix | Count | Placeholder Size | Asset | Asset Size | Shader | Notes |
|---|---|---|---|---|---|---|
| BRk | 352 | 3.5×1.2×5.0m | ASRS_Racks_Center | 2.36×2.82×8.29m | dual | Per-block, no scaling |
| CvL | 190 | 2.0×4.0×1.5m | Conveyor_09 | 0.94×6.72×1.66m | dual | Roller conveyor |

サイズに関する方針

キューブに合わせてスケーリングせず、アセット本来のサイズを使用します。 アセットをキューブの寸法に合わせてスケーリングすると、視覚的な密度とリアリティが損なわれます。ブロックの XY 位置に、アセット本来の寸法で配置してください。

例外：アセットが領域より極端に大きい場合（例：20m の領域に対して 83m の組み立て設備）、代わりに小さなモジュール部品を使用します。

フェーズ 4：配置スクリプトのパターン

SimulationApp ランタイムでの配置

get_asset_bbox(stage, asset_path, app) — アセットを一時的に参照し、正確な bbox の中心を取得します。collect_blocks(stage) — 可視の Cube prim をワールド位置と名前の接頭辞でグループ化します。place_assets(stage, blocks, asset_map, asset_bboxes, module_name) — bbox の中心オフセットを補正してブロック位置にアセットを配置し、元のキューブを非表示にします。

scripts/place_assets.py を参照してください。

階層の規約

/World/
  Module1/          # Racks
    VNA/
      VNA001        # Individual asset reference
      VNA002
    BRk/
      BRk001
  Module2/          # Conveyors, sorters
    CvL/
      CvL001
    Sort/
      Sort001
  Module3/          # Safety, humans

フェーズ 5：アニメーションとアーティキュレーション

アニメーションのベイク

spatial-reasoning スキルの bake_waypoints() を使用して、ロボット、人、またはオブジェクトを経路に沿ってアニメーションさせます。

bake_waypoints(xform_op, waypoints, speed_mps, fps, mpu) — XformOp に、（x,y,z）ウェイポイントのリストに沿ったキーフレームを設定します。spatial-reasoning スキルの ../spatial-reasoning/scripts/spatial.py で定義されています。

アーティキュレーションビルダー

ロボット USD の場合：

build_forklift_articulation(output_path) — シャーシ、固定ジョイント付きマスト、直動リフトジョイントを作成します。_create_box、_create_fixed_joint、_create_prismatic_joint ヘルパーを含みます。

scripts/articulation_builder.py を参照してください。

UV マッピングとマテリアル

テクスチャの場合:

• グローバルアセットには sphereUV マッピングを使用する
• 平面（床、壁）には linear を使用する
• フォールバックとして常に UsdPreviewSurface を使用する
• ヘッドレスでは MDL 専用マテリアルを決して使用しない

フェーズ 6: バリデーション

プレースホルダーフローのカラーキー

色	値	意味
赤	(1.0, 0.2, 0.2)	バリデーション失敗
黄	(1.0, 1.0, 0.2)	警告（重なりに近い）
緑	(0.2, 1.0, 0.2)	有効、アセットで置き換え可能

フォーマットバリデーションチェックリスト

• すべてのアセットが .usd、.usda、または .usdc 拡張子を持つ
• すべてのパスがスラッシュ / を使用している
• .. 相対パスが存在しない
• すべてのアセットで mpu = 1.0（スクリプトがスケールを検証）
• 参照に ./ または ../ 構文が含まれていない
• トポロジー: 空の場合、アーティファクトが Xform の下にネストされていない

アセットの推奨（スキャンに基づく）

まず、catalog_assets() ですべてのアセットをスキャンし、次に:

• フィルタ: dual_shader が True
• ソート: prims < 5000
• 割り当て: プレースホルダーキューブの 20% 許容範囲内で bbox 寸法を一致させる
• 除外: すべての blockpallet_a*、palletstack_a* — これらは実際のアセットではありません

苦労して得た教訓

1. キューブの寸法に合わせてアセットをスケーリングしないこと — 視覚的な密度が損なわれます。自然なサイズを使用してください。
2. 大きなアセンブリ（>20m）はブロッククラスターにほとんど収まりません — 代わりに小さなモジュール部品を使用してください。
3. bbox 中心のオフセットを常に補正すること — ほとんどのアセットは原点中心ではありません。
4. Lightspeed で処理されたアセット = MDL 専用 = ヘッドレス arm64 では黒くなる。 「Collected」のデュアルシェーダーバリアントのみを使用してください。
5. Tote_01、Pallet_Pile、AMR_Table = MDL 専用 — 配置されますが黒くレンダリングされます。機能的なプレースホルダーとして Scissor_Lift または Electrical_Panel を使用してください。
6. 新しい Isaac Sim を起動する前にすべての kit プロセスを終了すること — ゾンビプロセスは 90〜170 秒のコールドスタートを引き起こします。
7. 再起動の間に /dev/shm/carb-* をクリーンアップすること — SIGKILL を防ぎます。
8. SimulationApp のヘッドレスには明示的な DomeLight + DistantLight が必要 — GUI はビューポートライトを自動的に追加しますが、ヘッドレスは追加しません。
9. Xvfb（DISPLAY=:99） はロックされたデスクトップ（:0）よりも MDL レンダリングを改善できますが、万能の解決策ではありません。