isaac-sim-orchestrator

Isaac Sim オーケストレーター

目的

確立された目標または契約を、機能をマッピングし、専門スキルを順番に実行することで、検証済みのライブラリ、Kit 統合、または実行可能なシミュレーションに変換します。「フォークリフトのデモは範囲が定まり、承認済みです。構築して動画をください」のような依頼は、以下の4つのフェーズに直接進みます。成果物や受け入れ基準の範囲を定める必要がある場合に限り、最初に isaac-sim-workflow を使用します。

専門スキルの担当範囲

障害物を考慮した特化型のアームデモは、ポールを避けた物理演算と動画を含め、motion-generation の担当です。このオーケストレーターが最初に読み込まれた場合は、実装に着手する前に motion-generation に引き継ぎ、主要スキルとして維持してください。オーケストレーションでは、構成と納品を支援できます。

ネイティブのスキル呼び出しツールが利用できる場合は、そのツールで専門スキルを呼び出してください。その指示やスクリプトをシェルで読み取っても、呼び出しの代わりにはなりません。ランタイムがファイルベースのスキル読み込みのみをサポートする場合は、その方法を使用し、トレースの制限を正確に伝えてください。

前提条件

• Kit 統合の場合：ビルド済みの Isaac Sim、サポート対象の NVIDIA GPU、および以下のシェル環境。
• スタンドアロンライブラリの基盤の場合：構成済みの source/libraries ビルド、またはインストール済みの wheel／SDK。Kit と GPU は必須ではありません。

制限事項

• セクションで別途記載がない限り、Kit 固有のガイダンスは Isaac Sim 6／Kit 110 を対象としています。
• サポート対象外のエッジケースについて、NVIDIA 公式ドキュメントの代わりにはなりません。

トラブルシューティング

エラー／症状	原因	解決策
拡張機能が見つからない	$ISAAC_SIM_DIR が誤っている、または Kit ビルドが古い	環境変数を _build/linux-x86_64/release に設定するか、再ビルドしてください
フレームが黒い、または空	ライトがない、または非 RTX レンダーモード	ドームライト／キーライトを追加し、RTX／PathTracing の設定を確認してください
ステージの読み込み時または初回レンダリング時に停止する	MDL のコンパイル、またはステージが大きすぎる	isaac-sim-troubleshooting の切り分け手順に従ってください

環境の契約

Kit 経由のスキルでは以下の変数を使用します。スタンドアロンライブラリの作業では、代わりに構成済みのビルド／インストール環境を使用します。

変数	用途	例
$ISAAC_SIM_DIR	Isaac Sim のインストールルートまたはビルド済みリポジトリのパス	$HOME/IsaacSim（インストール）または <this-repo>/_build/linux-x86_64/release（ソースビルド）
$ISAAC_LAB_DIR	Isaac Lab のチェックアウト	$ISAAC_SIM_DIR/IsaacLab
$WORKSPACE_DIR	エージェントごとの出力、一時ファイル、キャッシュ	デフォルトでは未設定。プロジェクト内のパスまたは ~/.cache/<repo> を選択してください
$CIP_ROOT（Windows）	コンテンツパイプラインのインストール先（CIP/WRAPP）	C:\_Data

GPU を使用するシミュレーションまたはレンダリングの前に nvidia-smi を実行し、num_envs の規模を決め、RT2 と PathTracing のどちらを使用するか選択してください。ライブラリのみの CPU ワークフローでは必須にせず、GPU クラスをハードコードしないでください。

実行モード

コードを実行する前に、担当する対象を選択してください。

対象	実行方法
スタンドアロンライブラリ	構成済みのモジュールビルド、インストール済みの wheel／SDK、または source/examples/examples.sh を使用してください。SimulationApp は作成しないでください
Kit デモ／コントローラー	ユーザーがスタンドアロンでの検証を明示的に依頼した場合を除き、スタンドアロンへの引き渡し／キャプチャの前に isaac-sim-remote を通じて反復と検証を行ってください
その他の Kit 拡張機能またはアダプター	ライブ Python サーバーを介した isaac-sim-remote での反復を優先してください。スタンドアロンの Kit 引き渡しテストには python.sh を使用してください
Kit にステージングしたライブラリ	まず通常のプロセスでライブラリの動作を証明してから、Kit で wheel のステージングとライフサイクルアダプターをテストしてください

拡張機能からライブラリへの書き換え手順

確立された契約に基づき、再利用可能な動作を拡張機能から切り出す場合：

1. 旧 API、実装、アダプター、パッケージ化、依存関係、テスト、インポート、バージョンの適用範囲を棚卸しし、分類します。
2. source/libraries に実装を一つだけ保持し、サポート対象のインポートを維持したうえで、Kit なしでも公開ファサードが機能することを確認します。
3. ビルド済みの wheel と SDK を、Kit のライフサイクルまたは変換動作だけを保持する薄い Kit 拡張機能に配置します。
4. isaac-sim-validator を使用して、ライブラリと Kit の経路をそれぞれ独立して検証し、それぞれのバージョンに関する判断も個別に確認します。

isaac-sim-remote の起動手順を使って、サーバーを有効にしたシミュレーションを起動します。ここにそのコマンドを重複して記載しないでください。 Kit コントローラーの反復を始める前に、正常なヘルスレスポンスを必須とし、その後、クライアント経由でシーンのセットアップ、調整、検証のプローブを送信します。実行証跡として、それらのレスポンスを保持します。サーバーを利用可能にできない場合は、そのワークフロー検証がブロックされていると報告してください。SimulationApp の起動を繰り返す方法に黙って切り替えたり、動画が正常に生成されたことだけを根拠にワークフローの完了を主張したりしないでください。 ライブでの反復後に正常終了するには、ローカルホストクライアント経由でリモートスキルのシャットダウンヘルパーを呼び出します。

タスクの分解

依頼にはすべて、4 つのフェーズを実行します。各フェーズの具体的な手順は目標によって異なります。まず必要な機能を特定し、それぞれを単独で検証してから組み合わせます。

フェーズ 1 — 基盤の検証

1a. 機能／スキルのマッピング（コードを書く前に実施）：

• デモに成果物または受け入れ基準がまだ定義されていない場合は、isaac-sim-workflow を読み込んで定義し、その後このフェーズに戻ります。依頼ですでに対象、動作、制約、出力（たとえば、20 秒の動画で納品する、衝突のない通路走行）が決まっている場合は、その契約を直接使い、スコープを定める作業を繰り返さないでください。
• 依頼内容を、文書化されている Isaac Sim の機能や API と照合します。
• 各機能について、既存のスキルがあるか確認します。
  • スキルがある場合 -> 読み込み、手順に従います。
  • スキルがない場合 -> その場で作成します。フロントマターの status を draft にし、skill-distillation で HIGH PRIORITY としてフラグを設定し、その旨を事前にユーザーに伝え、反復サイクルを短縮します（中間結果を共有し、早い段階で対象を絞った質問をします）。
• 1b に進む前に、機能 -> スキルのマッピングをタスクの WORKLOG.md に記録します。

1b. 基盤の検証（機能ごとに実施）：

• タスクに必要な機能（アセット、物理演算、ロボット制御、センサー、レンダリングなど）をすべて列挙します。
• 各機能を単独で検証します。読み込めるか、単独で正しく動作するかを確認します。
• 各基盤の検証に合格するまで先に進まないでください。

フェーズ 2 — 段階的な統合

検証済みの基盤を一度に一つずつ組み合わせます。追加するたびに、安定性と正確性のチェックを再実行します。各失敗では、新しい変数を一つだけ加えます。

フェーズ 3 — 仕上げと納品

• 出力を視覚的またはプログラムで検証します。スクリプトの実行完了だけではなく、タスクの成功を確認します。
• 出力固有の要件（ライター、注釈、動画のキャプチャ、DR）を追加します。
• 簡潔な要約を添えてパッケージ化し、引き渡します。

フェーズ 4 — 知識の抽出（必須）

• 反復、失敗、回避策を列挙します。
• ユーザーからの修正を記録します。
• 各教訓を、新しいスキル、スキルの更新、手順の修正、MEMORY.md の事実のいずれかに分類します。
• 再利用可能な教訓についてスキルの変更が妥当かどうかを、skill-distillation に従って判断します。ユーザーから編集の許可を得ている場合は、対象を限定して編集します。許可を得ていない場合は、書き込む前にパッチを記録するか提案します。再利用可能な教訓がない場合も、その判断を記録します。

手順全体については skill-distillation を参照してください。ファイルの変更が不要な場合でも、フェーズ 4 は省略できません。

サブエージェントのルール

• 各フェーズは、それぞれ独自の WORKLOG.md を持つサブエージェントとして実行できます。
• サブエージェントは、論理的なチェックポイントでコミットし、作業を途中のままコミットしないでください。
• 大きなスクリプトを生成する場合は、ファイルに少しずつ書き込みます。1 回のターンで 200 行を超えるコードを生成しようとしないでください。
• サブエージェントがタイムアウトしても、次に作業を引き継ぐ際に WORKLOG.md は残ります。

ルーティングされたスキル

スキル	用途
isaac-sim-remote	Kit 開発向けのライブ Python サーバーでの反復作業と検証
motion-generation	障害物を考慮したアームコントローラーとピックアンドプレースの主担当。物理シミュレーション／動画デモを含みます
urdf-mjcf-to-usd-conversion	URDF／MJCF のロボット記述を、物理 API とアーティキュレーション構造を用いて USD にインポート
physx-to-newton-conversion	既存の PhysX のみ対応する USD ロボットを Newton 対応のバリアントパッケージに変換
usd-pipeline	アセットの挿入、スケーリング、マテリアル、ヘッドレスレンダリングの互換性
usd-composition-architecture	レイヤー構造の USD アセット（ルート + 物理 + 外観）
usd-articulation	複数リンクのアーティキュレーション、ジョイント階層、Robot Schema オーバーレイ
physics-simulation	PhysicsScene の設定、プリムごとのセットアップ、接触マテリアル、Newton と PhysX の比較
isaac-sim-sensor	RTX／物理センサー（カメラ、LiDAR、IMU、接触）、レンダープロダクト、アノテーター
isaac-sim-rendering	ヘッドレス Kit 110 のキャプチャ、RT2／PathTracing、ACES
isaac-sim-validator	納品前の最終 QA ゲート
Kit のブートストラップと、スタンドアロンライブラリのインポートとの違いについては、
references/api-cheatsheet.md を参照してください。

複数ロボットのフリートリファレンス

サンプルロボット

ロボット	開始 Z	駆動方式	備考
Nova Carter	0.0	差動駆動	ホイール半径 0.14 m、トレッド幅 0.499 m、減衰 100K
VSVXL	0.0	差動駆動	最も信頼性が高い。ホイール半径 0.15 m、トレッド幅 1.52 m
Spot	0.75	オムニホイール	bbox の最小 Z = -0.69。地面とのクリアランスが必要
FR3	0.0	固定ベース	エンドエフェクターのみで、移動機能なし

シーンのセットアップ

• sim_warehouse_v4.usda のパターン：shell + lights + racks + PhysicsScene + 地面のコリジョン。
• シェル（sm_warehouse_mega.usd）の単位は cm、ロボットと機器の単位は m です。
• 環境アセットから物理設定をオフラインで除去してください。実行時に大規模なステージから除去すると、コアダンプが発生します。

PhysicsScene

from pxr import UsdPhysics, PhysxSchema

physics_scene = UsdPhysics.Scene.Define(stage, "/World/PhysicsScene")
physics_scene.CreateGravityDirectionAttr().Set((0, 0, -1))
physics_scene.CreateGravityMagnitudeAttr().Set(9.81)

physx_scene = PhysxSchema.PhysxSceneAPI.Apply(physics_scene.GetPrim())
physx_scene.CreateEnableCCDAttr().Set(True)
physx_scene.CreateEnableStabilizationAttr().Set(True)
physx_scene.CreateSolverTypeAttr().Set("TGS")
physx_scene.CreateTimeStepsPerSecondAttr().Set(60)
physx_scene.CreateGpuMaxNumPartitionsAttr().Set(8)   # 10+ robots

グリッド配置

import math

def place_robots_grid(stage, robot_usd_path, prefix, count, spacing=3.0, start_z=0.0):
    cols = math.ceil(math.sqrt(count))
    robots = []
    for i in range(count):
        row, col = divmod(i, cols)
        x, y = col * spacing, row * spacing
        prim_path = f"/World/Robots/{prefix}_{i}"
        ref = stage.OverridePrim(prim_path)
        ref.GetReferences().AddReference(robot_usd_path)
        from pxr import UsdGeom, Gf
        xform = UsdGeom.Xformable(ref)
        xform.ClearXformOpOrder()
        xform.AddTranslateOp().Set(Gf.Vec3d(x, y, start_z))
        robots.append(prim_path)
    return robots

間隔

• 移動ロボット：中心間の最小距離は 2 m。
• アーティキュレーテッドアーム：最小でリーチ半径の 1.5 倍。
• 航空機：高度を 2 m 以上ずつずらします。

コリジョングループ

from pxr import PhysxSchema

def create_collision_group(stage, group_path, robot_paths):
    group = PhysxSchema.PhysxCollisionAPI.Apply(stage.DefinePrim(group_path))
    for path in robot_paths:
        prim = stage.GetPrimAtPath(path)
        collision_api = PhysxSchema.PhysxCollisionAPI.Apply(prim)
        collision_api.GetCollisionGroupsRel().AddTarget(group_path)

スケーリングの上限（VRAM 別）

上限は、利用可能な VRAM にほぼ比例して増加します。これらのしきい値を超えると、CUDA の OOM が発生するリスクがあります。

指標	12 GB	24 GB	48 GB	96 GB	備考
プリムの合計数	~12K	~25K	~50K	~100K	線形に増加
ロボット数	<= 2	<= 5	<= 10	<= 20	複雑さによって異なります
ロボットごとのアクティブな剛体数	~200	~200	~200	~200	ロボットごとに一定
アーティキュレーション（多自由度）	<= 2	<= 5	<= 10	<= 20
レンダリング解像度	1280x720	1600x900	1920x1080	2560x1440	単一ビューポート

最適化：

• URDF の config.yaml で make_instanceable: true に設定します（メッシュデータを共有）。
• 遠方のロボットには LOD 切り替えを使用します。
• アクティブゾーン外のロボットでは物理シミュレーションを無効にします。

ナビゲーション

差動駆動の運動学：

vL = (vx - omega * tw/2) / wheel_r
vR = (vx + omega * tw/2) / wheel_r

PD ステアリングのデフォルト値：KP=2.5、KD=1.2、MAX_W=1.5、ウェイポイントの許容誤差は 4.0 m です。範囲外：|Z| > 50 または |X|/|Y| > 500 の場合、デッドとしてマークします。

カメラ

チェイスカメラ：後方 12 m、最小高さ 2.5 m、倉庫の境界内に制限し、alpha = min(1.0, DT*2.0) でスムーズに補間します。ラックへの侵入を避けるため、カメラの高さを動的に上げます。

ビューモード（4 秒ごとに切り替え）：チェイス、俯瞰（z=50 m）、通路（目線の高さ）、ワイド（z=20 m、yaw=0）。

照明（倉庫のデフォルト）

パラメーター	値
filmISO	100-120（200 は露出オーバー、80 は通路で暗すぎます）
DomeLight	強度 150、色 (0.85, 0.88, 0.95)
Fill SphereLights	強度 1200、色 (1.0, 0.95, 0.85)、高さ 8-9 m
RectLights	天井に設置し、通路に沿って配置

レンダリング

• RayTracedLighting（RT2）、1920x1080。
• GPU の負荷を抑えるため、hideUi=1 を指定して 320x240 のウィンドウを使用します。
• 常に DISPLAY=:0 を設定してください。複雑な領域では、ヘッドレスでのビューポート初期化に失敗します。
• maxBounces=7、aovs=none。

タイミング

DT = 1/60
Settle: 200-500 frames after timeline.play()
Capture: every 4th step (15 fps)

ワークフロー：マルチロボットシミュレーション

1. リクエストを受け取ります（例：「倉庫に Novas を6台、ラックを100台」）。
2. シーンを構成します：倉庫の USD を読み込み、place_robots_grid でロボットを配置します。
3. 必要に応じてコリジョングループを作成します。
4. usd-pipeline を使って、メッシュのスケールとシェーダーを検証します。
5. 永続セッションで実行します：isaac-sim-remote（Python サーバー）を介してライブで反復するか、スタンドアロン／引き継ぎ実行では isaac-sim.sh --exec script.py を使います。
6. 100ステップごとにレンダーパルスループを実行します。
7. isaac-sim-validator でレンダリングを検証します。
8. 動画と最終シーンを納品します。

ワークフロー：フィジカル AI のエンドツーエンドパイプライン

アセットのインポート、物理演算、センサー、検証にまたがるタスク（例：「Franka アームをインポートし、把持をシミュレートして、LiDAR と RGB をキャプチャし、検証する」）のルートチェーンです。

パイプラインのステージ

┌─────────────────────────┐     ┌──────────────────────┐     ┌───────────────────┐     ┌─────────────────────┐
│ 1. Asset Import         │────▶│ 2. Physics Setup     │────▶│ 3. Sensor Attach  │────▶│ 4. Validate & Ship  │
│                         │     │                      │     │                   │     │                     │
│ urdf-mjcf-to-usd-conv  │     │ physics-simulation   │     │ isaac-sim-sensor  │     │ isaac-sim-validator │
│ usd-pipeline            │     │ usd-articulation     │     │ isaac-camera      │     │ isaac-sim-rendering │
│ usd-composition-arch    │     │                      │     │ isaac-sim-remote  │     │                     │
└─────────────────────────┘     └──────────────────────┘     └───────────────────┘     └─────────────────────┘

ステージ1 — アセットのインポート

入力	スキル	出力の要件
URDF/MJCF ファイル	urdf-mjcf-to-usd-conversion	IsaacRobotAPI、IsaacLinkAPI、IsaacJointAPI、コリジョンメッシュを含む USD
USD 環境アセット	usd-pipeline	計測済みで、シェーダー分類済み、バウンディングボックスのオフセット付きで配置されたアセット
マルチレイヤー構成	usd-composition-architecture	ルート＋物理演算＋外観レイヤー

ステージ2への引き継ぎ：USD ファイルがディスク上にあり、Prim パスが判明していること。RL ワークロードでは make_instanceable: true であること。

ステージ2 — 物理演算の設定

入力	スキル	出力の要件
インポート済み USD ステージ	physics-simulation	PhysicsScene（重力、ソルバー、タイムステップ、CCD）、Prim ごとの RigidBodyAPI／CollisionAPI／MassAPI、接触マテリアル、ジョイントドライブ
多自由度ロボット	usd-articulation	アーティキュレーションルート、ジョイント階層、ドライブの剛性／減衰

ステージ1の前提条件：

• ロボット USD のルートに IsaacRobotAPI が必要です（インポーターによって適用されます）。
• 静的環境 Prim に必要なのは CollisionAPI のみです（RigidBodyAPI は不要です）。
• インポーターがジョイントごとの属性を適用済みであっても、ここで必ず PhysicsScene を作成します。

ステージ3への引き継ぎ：シミュレーションをクラッシュなしで再生でき、ロボットが重力下で200フレームにわたり姿勢を保つこと。

ステージ3 — センサーの取り付け

入力	スキル	出力の要件
安定したシミュレーションステージ	isaac-sim-sensor	ロボットリンクを親とするセンサー Prim、アノテーター付きレンダープロダクト
カメラの内部パラメーター	isaac-camera	レンズモデルと焦点距離パラメーターを設定した USD カメラ
ランタイム検証	isaac-sim-remote	センサー設定をライブで反映し、データストリームがゼロ以外であることを確認

マウントポイントの規約：センサーはロボットリンク下の Xform Prim に取り付けます。インポートした URDF にマウントリンクがない場合は、作成します：

mount = UsdGeom.Xform.Define(stage, f"{robot_path}/{link_name}/sensor_mount")

ステージ4への引き継ぎ：ゼロ以外のセンサーデータを含むフレームが少なくとも1つあること（深度 > 0、ポイントクラウドが空でない、IMU が重力を報告）。

ステージ4 — 検証と納品

入力	スキル	確認項目
完全なシミュレーションスクリプト	isaac-sim-validator	非推奨のインポートがないこと、ハードコードされたパスがないこと、ライトが存在すること、レンダリングが黒くないこと
レンダリング済みフレーム	isaac-sim-rendering	フレーム品質、ACES トーンマップ、解像度
ランタイムの動作	（手動またはスクリプト）	物理演算：ロボットが接地状態を保ち、NaN がないこと。センサー：データストリームが想定範囲と一致すること

バリデーターは納品の可否を判定しますが、ランタイムの物理演算やセンサーの正確性は対象外です。ランタイムの確認では、以下を検証します：

1. シミュレーション期間全体を通じて、RigidBodyAPI.GetVelocityAttr() が有限値を保つこと。
2. センサーアノテーターのデータ形状が、設定された解像度／チャンネル数と一致すること。
3. アーティキュレーションのジョイント位置がドライブの制限内に収まること。

エンドツーエンドの手順

1. Phase 1a — リクエストの機能を上記のパイプラインの各段階に対応付けます。
2. Phase 1b — 各段階を個別に検証します。
   • インポート：USD がエラーなく読み込まれ、prim の数が VRAM に対して妥当であることを確認します。
   • 物理演算：ロボットのポーズが維持され、timeline.play() と 200 フレームの実行が安定することを確認します。
   • センサー：簡略化したシーンで、1 つのセンサーが有効なデータを生成することを確認します。
3. Phase 2 — 段階的に統合し（インポート → 物理演算 → センサー）、追加のたびに安定性を再確認します。
4. Phase 3 — isaac-sim-validator を実行し、最終出力を取得して納品します。
5. Phase 4 — skill-distillation に従って教訓を抽出します。

デバッグプロトコル

レンダリング

問題	対処方法
黒いフレーム	DomeLight と DistantLight が存在することを確認し、settings.set("/rtx/rendermode", "RayTracedLighting") を強制し、nvidia-smi を確認します
色の乱れ	ACES トーンマッピング（/rtx/post/tonemap/op=4）を設定します。倉庫では filmISO=600 にし、PathTracing を削除します
カクつき	DT=1/60 にし、setTimeStepsPerSecond=60 に設定します。物理演算のレートではなく、ディスプレイの更新レートを変更します
亀裂	メッシュの整合性を確認します。バンプ／法線マップの解像度を下げ、低解像度の衝突メッシュを使用します
アーティキュレーションが正しく動かない	SolverType=TGS（fabric）にし、maxPositionIterations >= 6 に設定し、make_instanceable: true にします
OOM によるクラッシュ	pkill -f "kit/kit" を実行し、/dev/shm/carb-* をクリーンアップし、num_envs を減らします

アセットの読み込み

問題	対処方法
アセットが黒く表示される	UsdPreviewSurface またはデュアルシェーダーを使用します。相対パス（./meshes/asset.usd）を使用し、有効な場合はインスタンス化可能であることを確認します
トランスフォームが正しくない	mpu（デフォルトは 1.0）を確認し、配置前にオフセットを適用して、measure_asset() で検証します
メッシュが見つからない	大文字と小文字を区別したパスを使用します。絶対パスを使用し、stage.GetPrimAtPath() で検証します

トレーニング

問題	対処方法
損失が NaN になる	LR を下げ、報酬を [-5, 5] にクリップし、テレオペレーションのベンチマークが発散していないか確認します
報酬が 0 のまま	密な報酬シェーピングを追加し、報酬スケールを 50% 下げ、探索用に入力ノイズを追加します
価値関数が発散する	ターゲットネットワークの更新頻度を上げ、優先度付きリプレイを使い、バッチサイズを大きくします

運用ルール

• 作業フォルダーは削除せず、再利用してブランチを作成します。
• .usd ファイルは必ず保存します。メモリ内にしか存在しないと思い込まないでください。
• すべてのレンダリングを検証します。黒いフレームは絶対に納品しないでください。
• 長時間実行するプロセスはすべて終了できるようにします（pkill または pidfile を使用）。
• 生成するスクリプトで ~/ をそのまま使わず、$HOME または $ENV_VAR に展開します。
• すべての RL ロボットで make_instanceable: true にします。
• カメラを切り替えた後、simulation_app.update() を 5 回呼び出します。
• timeline.play() の前に torch をインポートしないでください。
• 各エポックで GPU メモリをログに記録します。
• HoD アセットは遅延読み込みします（要求に応じて解凍）。
• タスクの終了時に skill-distillation（リクエストループのステップ 5）を実行します。教訓はスクラッチメモリではなく、該当する SKILL.md に記録します。