isaac-sim-validator

Isaac Sim Validator

警告： レベル 3 では、対象スクリプトをユーザーの全権限で実行します。コンテナやサンドボックスによる分離はありません。十分に信頼できるスクリプトに対してのみ、--confirm-execute を使用してください。

目的

ライブラリ単体または Kit アプリケーション／拡張機能を管理する境界で、よくある納品上の不備を検出します。

レベル 1～2 は静的チェックのみを行います。レベル 3 では、呼び出し元ユーザーの権限で timeout を使用して対象の Python スクリプトを実行します。 レベル 3 を実行するには、明示的な --confirm-execute（または CONFIRM_EXECUTE=1）によるオプトインが必要です。サンドボックスではありません。

前提条件

• ライブラリ単体の場合、設定済みのビルド環境またはインストール済みのテスト環境が必要です。
• Kit のチェックにはビルド済みの Isaac Sim ツリーが必要です。GPU が必要なのは、GPU を使用するチェックに限られます。

制限事項

• レベル 1～2 では、あらゆるワークロードで実行時の正しさを証明できません。
• レベル 3 では、--confirm-execute の指定後にのみ、信頼できないスクリプトの内容を実行します。コンテナ／firejail による分離はありません。
• しきい値はよくあるデモ／SDG の問題を対象としており、すべての製品機能を網羅するものではありません。

トラブルシューティング

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

納品前の最終ゲートです。以下のチェックに不合格となる出力を拒否し、結果を甘く評価しないでください。

ライブラリ単体の場合は、通常プロセスでのパブリックインポート、宣言されたパッケージ／ネイティブ依存関係、再配置、該当する場合は SDK コンシューマー、および isaacsim.common.logging.Logger の診断を検証します。SimulationApp、レンダリング、GPU は必須ではありません。

Kit 専用の検証ヘルパー

スクリプト	目的	引数
scripts/validate_sim.sh	シミュレーションを検証します	スクリプトヘッダーに記載された位置引数（スクリプトを参照）

スクリプトの実行

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

run_script("scripts/validate_sim.sh", args=[])

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

Kit シミュレーションチェックリスト

チェック項目	合格条件	不合格時の対応
スクリプトのパス	存在し、読み取り可能	拒否：Script path invalid: <path>
ファイルサイズ	> 1 KB	拒否：Script empty or corrupted
isaacsim のインポート	omni.isaac.core ではなく isaacsim.* を使用	拒否：Use isaacsim.* namespace; omni.isaac.core is deprecated
SimulationApp の設定	width と height を明示	拒否：SimulationApp without window args causes swapchain-capture size mismatch
ライトの設置	DomeLight（intensity >= 100）および DistantLight（>= 500）	拒否：No lighting; render will be black
レンダリングモード	反復作業では RayTracedLighting、ヒーローショットのみ PathTracing	拒否：PathTracing too slow for iteration; use RayTracedLighting
ACES トーンマップ	carb rtx.post.tonemap.op = 4、filmIso はデフォルトで 200／深い通路では 600／空撮では 400	提案：Enable ACES (op=4) for contrast
最終レンダリング	>= 150 KB かつ mean_RGB > 30	拒否：Render is black or low-energy; check lighting
ユーザーパス	/home/<user>/、ハードコードされた C:\path\to\...、エージェントごとのホームパスを使わない。%USERPROFILE%、環境変数、または argparse を優先	拒否：Hardcoded user path; use $ISAAC_SIM_DIR, $ISAAC_LAB_DIR, $WORKSPACE_DIR, or argparse
ネットワークエンドポイント	IP アドレス（192.168.x.x、10.x.x.x）を直接記述せず、localhost 以外のホストも指定しない	拒否：Hardcoded endpoint; parameterize via env var or config
出力ディレクトリ	設定可能（環境変数、CLI、または関数パラメーター）	拒否：Output dir hardcoded; accept as parameter or read $OUTPUT_DIR
VRAM の余裕	安定後の nvidia-smi の空き容量が 20% 超	使用率が >90% の場合は警告。リークまたはスケールの問題が考えられます
pkill -f "kit/kit" の使用	強制終了と再起動のバグを検出	警告：Verify zero kit processes before next launch
シミュレーション時間	物理シミュレーションが >= 3 s	拒否：Sim ran < 3 s; physics has not settled

ファイル構造の検証（USD シーン）

項目	有効	無効	対応
$ISAAC_LAB_DIR/scripts/	読み取り専用の参照先	ここに出力を書き込む	$OUTPUT_DIR または $WORKSPACE_DIR/outputs/ に出力先を変更
get_assets_root_path() -> s3://...	実行時には OK	配布する出力に埋め込む	ローカルにキャッシュし、設定可能なパスで参照
Melting／Splat の MDL 専用シェーダー	未加工の状態なら OK	エクスポート時に MDL 専用	除外する。MDL 専用ではレンダリングが黒くなります
RL の MakeInstanceable	必須（make_instanceable: true）	なし	拒否
サーフェスの usdPreviewSurface	必須	なし	拒否。UsdPreviewSurface の追加を提案
convex_decompose_mesh	false（clean_sdf_dc と併用）	true	安定性のため false を推奨
mpu=0.01	倉庫の外殻（13 m タイル）では OK	ロボットに使用	拒否

レンダリングの検証（フレーム分析）

指標	良好	不良	対応
ファイルサイズ	1–4 MB	~82 KB	82 KB は黒画像。拒否
平均 RGB	80–160	< 20	拒否：Too dark; add lights
最大 RGB	200–250	0	拒否：No light in scene
ピクセルの分散	> 15	< 5	平坦な画像は影が欠落しています。アクセントを追加
カラーヒストグラム	複数のピーク	単一のピーク	露出過多または平坦なライティングです。強度を調整
オブジェクトの視認性	ロボットが >= 3 体、またはアセットが 50 個以上	視認できるものが < 10 個	提案：Scene too sparse; add set dressing
影の一貫性	影に一貫性がある	不規則な黒い塊	拒否：Shadow artifacts; check light cone bounds

動画の検証

納品する MP4/GIF はすべて、開始・中間・終了のフレームを抽出して確認します。最初のフレームにレンダリングのウォームアップが映っている、被写体が遮られている、またはカメラがタスクを捉えられていない場合は、プレゼンテーション用の動画を拒否するか再編集します。短いプレゼンテーション用動画を作成する場合も、元のレンダリング全体とメトリクスを保持してください。

RL トレーニングの検証

問題	対応
AppLauncher が先頭にない	拒否：AppLauncher must precede any isaaclab imports
タスクの __init__.py が空でない	拒否：Task __init__.py must be empty; do not import configs
omni.isaac.lab のインポート	拒否：Use isaaclab.*; omni.isaac.lab is deprecated
PhysX バックエンド（Newton が適用される場合）	拒否：Use Newton; it is the default on Kit 110
PYTHONUNBUFFERED=1 がない	警告：Set PYTHONUNBUFFERED=1 to see logs in real time
GPU メモリのログ記録がない	提案：Log torch.cuda.memory_allocated()/1e6 to W&B
バッチサイズが VRAM を超過	提案：Reduce num_envs (try 2048)
チェックポイント名が不正	拒否：Must be model_XXXX.zip, not policy.pt
シードが 1 つだけ	提案：Run seeds 42, 123, 456 for valid comparison

アセットとシェルの検証

入力	チェック項目	対応
docker run コマンド	/workspace/output の -v マウント	拒否：Output folder not mounted
サブエージェントの起動	workdir=$WORKSPACE_DIR	拒否：Sub-agent workdir hardcoded; use $WORKSPACE_DIR
Blender の USD エクスポート	正しい mpu、デュアルシェーダー（UsdPreviewSurface + MDL）、正しいエクスポートタイプ	いずれかが欠けていれば拒否
シーンの複雑さ	安定化ステップ 10 回以内にレンダリングされること	拒否：Scene too complex; simplify assets
ゴーストアーティファクト	/dev/shm/carb-* のクリーンアップ	拒否：Use workspace_cleanup.py to clear /dev/shm/carb-*

Kit の判断ツリー

graph TD
    A[Received Output] --> B{Has script?}
    B -->|No| C[Reject: "No script provided"]
    B -->|Yes| D{File size >1KB?}
    D -->|No| E[Reject: "Script empty or corrupted"]
    D -->|Yes| F{Python?}
    F -->|Yes| G{isaacsim.* imports?}
    G -->|No| H[Reject: "Use isaacsim.* not omni.isaac.core"]
    G -->|Yes| I{SimulationApp or --exec?}
    I -->|Neither| J[Reject: "Must use SimulationApp with window args OR isaac-sim.sh --exec"]
    I -->|SimulationApp| K{width and height set?}
    K -->|No| L[Reject: "SimulationApp requires explicit width and height"]
    K -->|Yes| M{Dome + Distant lights?}
    M -->|No| N[Reject: "Add DomeLight and DistantLight (min intensity 100 and 500)"]
    M -->|Yes| O{RayTracedLighting?}
    O -->|No| P[Reject: "Use RayTracedLighting for iteration"]
    O -->|Yes| Q{Render output exists?}
    Q -->|No| R[Reject: "No render output"]
    Q -->|Yes| S{>= 150 KB and mean_RGB > 30?}
    S -->|No| T[Reject: "Render is black, too dark, or corrupted"]
    S -->|Yes| U{Hardcoded user paths or bare IPs?}
    U -->|Yes| V[Reject: "Replace hardcoded user paths/IPs with env vars or args"]
    U -->|No| Y[VALID - deliver]

トレーニング出力

項目	対応
policy_only_XXXX.pt	許可
model_XXXX.zip	許可
log.csv または wandb URL	許可
エピソードデータを含む results.json	許可
報酬曲線／メトリクスがない	拒否：Log episode/reward_mean and train/value_loss

返信形式

• 合格：Valid: <one-line summary>
• 不合格：Invalid: <list of failed checks>
• 提案（ほかの項目がすべて有効な場合のみ）：Could be improved: <tip>

曖昧な表現（「そう思います」「たぶん」など）は使わないでください。黒いフレームを出力しないでください。

入力ソース

• isaac-sim-orchestrator、isaac-sim-rendering、その他の生成スキル、およびサブエージェントの出力。
• Isaac Sim の成果物に対して呼び出されます：「この Isaac Sim スクリプトを検証」「この Isaac Sim レンダリングをチェック」「このシミュレーション出力をレビュー」。

自動検証

scripts/validate_sim.sh を使用し、CLI から上記のチェックを実行します。

# Levels 1–2: static only
bash scripts/validate_sim.sh --level <1|2> <script.py> [--output-dir <dir>] [--timeout <seconds>]

# Level 3: EXECUTES the script — requires explicit opt-in
bash scripts/validate_sim.sh --level 3 --confirm-execute <script.py> [--output-dir <dir>] [--timeout <seconds>]
# or: CONFIRM_EXECUTE=1 bash scripts/validate_sim.sh --level 3 <script.py> ...

フィードバックループ

• 拒否内容は、生成スキルの失敗モードカタログにフィードバックされます。
• 繰り返し発生する失敗は、新しいバリデータールールになります。
• 継続的に適用する評価基準：references/quality-criteria.md。各イテレーションを references/feedback-log.md に記録します。