data-collection-sim

データ収集シミュレーション

目的

ヘッドレスのバッチ実行で、Replicator のライター（RGB、深度、セグメンテーション、ポーズ、Kitti／COCO バリアント）を使用して、注釈付きの静的シーン合成データを生成します。

前提条件

• ビルド済みの Isaac Sim（$ISAAC_SIM_DIR または _build/linux-x86_64/release）。
• 最新のドライバーを搭載した NVIDIA GPU（nvidia-smi）。
• isaac-sim-orchestrator のシェル環境変数の要件：$ISAAC_SIM_DIR、$ISAAC_LAB_DIR、$WORKSPACE_DIR。

制限事項

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

トラブルシューティング

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

Isaac Sim 6.0 Replicator を使用して、ヘッドレスの SDG パイプラインを構築します。ライターを介して、注釈付きフレーム（RGB、深度、セグメンテーション、バウンディングボックス、ポーズ）をディスクに出力します。

利用可能なスクリプト

スクリプト	目的	引数
scripts/minimal_sdg_pipeline.py	Isaac Sim Replicator を使用した最小限の静的シーン SDG パイプライン	--help を参照
scripts/shelf_pose_grid_capture.py	静的シーン SDG 用の棚ポーズグリッドキャプチャ	argparse 経由の CLI フラグ（--help を参照）
scripts/validate_sdg_output.sh	SDG 出力の検証	スクリプトヘッダーに記載の位置引数（スクリプトを参照）
scripts/warehouse_sdg.py	倉庫 SDG	argparse 経由の CLI フラグ（--help を参照）

スクリプトの実行

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

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

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

関連スキル

• mobility-gen — モバイルロボットの軌道を記録してから再生・レンダリングします（二段階、ロボット搭載センサー）
• isaac-sim-sensor — センサーの基本要素（カメラ、LiDAR、IMU、接触）
• occupancy-map — 配置場所用の占有マップを生成します

アーキテクチャ

Config (YAML/JSON) → SimulationApp (headless) → Scene Setup → Randomizers → Capture Loop → Writer → Disk

必須インポート

from isaacsim import SimulationApp
simulation_app = SimulationApp({"renderer": "RealTimePathTracing", "headless": True})

import carb.settings
import omni.replicator.core as rep
import omni.usd
import isaacsim.core.experimental.utils.stage as stage_utils
from isaacsim.core.experimental.utils.semantics import add_labels, remove_all_labels
from isaacsim.storage.native import get_assets_root_path

stage_utils.open_stage()／stage_utils.add_reference_to_stage()／stage_utils.define_prim()／stage_utils.get_current_stage() は、従来の isaacsim.core.utils.stage.* および isaacsim.core.utils.prims.create_prim のフローに代わる Kit 110 の関数です。SDG の基本要素には omni.replicator.core を引き続き使用してください。

移行： omni.isaac.* から isaacsim.* への完全な対応表については、拡張機能の名称変更を参照してください。

ライター

rep.WriterRegistry.get(name)（または rep.writers.get(name)。どちらも同じレジストリ）を使ってライターを取得します。

omni.replicator.core の組み込みライター（omni.replicator.core/scripts/writers_default/）：

ライター	用途
BasicWriter	RGB、bbox_2d（タイト／ルーズ）、bbox_3d、セマンティック／インスタンス／instance_id セグメンテーション、深度（画像平面／カメラ）、法線、オクルージョン、モーションベクトル、カメラパラメーター、点群、スケルトン
KittiWriter	KITTI 形式のデータセット
CocoWriter	COCO 形式のデータセット（インスタンス／bbox）
CosmosWriter	Cosmos の倉庫動画クリップ（モダリティごとの PNG シーケンス＋MP4：rgb、shaded_seg、segmentation、depth、edges）。/app/omni.graph.scriptnode/opt_in = True が必要です
FPSWriter	フレームレート／キャプチャ時刻のテレメトリー
カスタム Writer サブクラス	アノテーターのテンソルに直接アクセスします（omni.replicator.core.Writer をサブクラス化し、rep.writers.register_writer で登録します）

isaacsim.replicator.writers は Isaac 固有のライターを追加します：

ライター	用途
PoseWriter	6 DoF オブジェクトの姿勢推定（write_debug_images=True はオプション）
DataVisualizationWriter	デバッグ／オーバーレイの可視化

非推奨であり、新規作業には使用しないでください：DOPEWriter、YCBVideoWriter、PytorchWriter、PytorchListener（および OgnPose ノード）。今後のメジャーリリースで削除されます。

ライターの初期化パターン

同等のパターンを 2 種類サポートしています。最近の（Isaac Sim 6.0 以降の）例では、明示的なバックエンドを指定する形式が推奨されています：

backend = rep.backends.get("DiskBackend")
backend.initialize(output_dir="/tmp/sdg_output")
writer = rep.writers.get("BasicWriter")
writer.initialize(backend=backend, rgb=True, bounding_box_2d_tight=True)
writer.attach(rp)

従来の短縮形式（引き続き使用できます。output_dir からバックエンドが暗黙的に作成されます）：

writer = rep.WriterRegistry.get("BasicWriter")
writer.initialize(output_dir="/tmp/sdg_output", rgb=True, bounding_box_2d_tight=True)
writer.attach(rp)

アノテーター

rep.annotators.get(name) で利用できるコアアノテーター：

• rgb — RGBA uint8
• distance_to_image_plane — 深度 float32
• semantic_segmentation — ピクセル単位のクラスラベル
• instance_segmentation — ピクセル単位のインスタンス ID
• bounding_box_2d_tight — タイトな 2D バウンディングボックス
• bounding_box_2d_loose — ルーズな 2D バウンディングボックス
• bounding_box_3d — ワールド座標系の 3D バウンディングボックス
• camera_params — 内部パラメーター、外部パラメーター、解像度
• occlusion — インスタンスごとの可視性比率
• normals — 表面法線
• pointcloud — 深度から生成された 3D 点群

最小パイプライン

run_minimal_sdg_pipeline(output_dir, num_frames, rt_subframes) — 倉庫のステージを開き、プロップにセマンティックラベルを付け、カメラを作成し、BasicWriter をアタッチして、キャプチャループを実行します。

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

倉庫のフルパイプライン

設定駆動のヘッドレス倉庫キャプチャ（YAML 設定、--num-frames、--output-dir）については、scripts/warehouse_sdg.py を参照してください。生成されたデータセットを scripts/validate_sdg_output.sh で検証します：

bash scripts/validate_sdg_output.sh <output_dir> [expected_frames]

ドメインランダム化

各フレームでランダム化するには、rep.functional API を使用します：

# Scatter objects on surface
rep.functional.randomizer.scatter_2d(prims=objects, surface_prims=plane, check_for_collisions=True, rng=rng)

# Randomize camera pose
rep.functional.modify.pose(cam, position_value=rng.uniform(pos_min, pos_max),
                           look_at_value=target_prim, look_at_up_axis=(0, 0, 1))

# Randomize lights via OmniGraph events
rep.utils.send_og_event(event_name="randomize_lights")

ヘッドレス実行

標準的な Isaac Sim Python ランチャーは python.sh です（Windows では python.bat を使用します）。isaac-sim.sh は完全なエディターアプリを起動するため、スタンドアロンの SDG スクリプトのエントリーポイントとしては適していません。

# $ISAAC_SIM_DIR is either the install root or <repo>/_build/linux-x86_64/release
"$ISAAC_SIM_DIR/python.sh" "$WORKSPACE_DIR/data_collection.py" --config config.yaml

ヘッドレス動作はランチャーフラグではなく、スクリプト内の SimulationApp({"headless": True}) で制御します。

または、Isaac Lab ランナーを使用します（$ISAAC_LAB_DIR は Isaac Lab のチェックアウト先です）：

"$ISAAC_LAB_DIR/isaaclab.sh" -p data_collection.py --config config.yaml

設定パターン

すべてをパラメーター化するには、YAML 設定を使用します：

resolution: [1280, 720]
rt_subframes: 32
num_frames: 100
headless: true
env_url: "/Isaac/Environments/Simple_Warehouse/full_warehouse.usd"
writer: BasicWriter
output_dir: /tmp/sdg_output
annotations:
  rgb: true
  bounding_box_2d_tight: true
  semantic_segmentation: true
  distance_to_image_plane: true
  bounding_box_3d: true
objects:
  - url: "/Isaac/Props/YCB/Axis_Aligned/003_cracker_box.usd"
    label: cracker_box
    count: 5
  - url: "/Isaac/Props/YCB/Axis_Aligned/008_pudding_box.usd"
    label: pudding_box
    count: 3

検証チェックリスト

1. 出力ディレクトリに想定数のフレームが含まれている
2. RGB 画像が真っ黒ではない（RGB 平均値 > 30）
3. アノテーションファイルの数がフレーム数と一致している
4. セグメンテーションマップにセマンティックラベルが表示されている
5. バウンディングボックスの面積がゼロではない
6. 深度マップに NaN がない

主なルール

• 手動でステップを制御するには、rep.orchestrator.set_capture_on_play(False) を設定します。
• rt_subframes：同じフレームを複数回レンダリングして、大きなポーズ差によるゴーストを軽減し、マテリアルやテクスチャを収束させます。レンダラーに合わせて調整してください。RTX Real-Time + DLSS Quality では小さめの値（4-8）で十分なことが多く、パストレーシングやマテリアルのストリーミングが多いシーンでは、通常 16-32 が適切です。
• DLSS Quality：carb.settings.get_settings().set("rtx/post/dlss/execMode", 2)。SDG に推奨されます。デフォルトの Performance モードでは、~600x600 未満でエッジにアーティファクトが発生することがあります。
• 注釈を付けるすべての prim に、add_labels(...)（タクソノミー対応）または rep.functional.modify.semantics(...) でタグを付けます。どちらも UsdSemantics.LabelsAPI スキーマを書き込みます。
• 静的シーンの SDG では、キャプチャ間にタイムラインが進まないように、rep.orchestrator.step に delta_time=0.0 を渡します。
• クリーンアップの前に rep.orchestrator.wait_until_complete() を呼び出し、バックグラウンドのバックエンドがすべてをディスクに書き込んだことを確認します。
• 再現可能なランダム化には、rng = np.random.default_rng(seed) と rep.set_global_seed(seed) を使用します。
• 高スループットのキャプチャ向けパフォーマンス設定（sdg_getting_started_05.py を参照）：
  • rep.orchestrator.step(wait_for_render=False) を使うと、キャプチャとレンダリングの完了を切り離せます。データが前のフレームに対応する場合があります。フレームとデータの厳密な対応が不要な場合にのみ使用してください。
  • carb.settings.get_settings().set("/exts/omni.replicator.core/enableWriteToFabric", True) を使うと、USD を介さずにランダム化の差分を Fabric に直接書き込みます。高速ですが、一時的な変更であり、USD ステージには保存されません。

関連する SDG ワークフロー

ワークフロー	モジュール／例
モバイルロボットの軌道の記録と再生	mobility-gen スキル + isaacsim.replicator.mobility_gen
把持データセットの生成	isaacsim.replicator.grasping（GraspingManager、GraspPhase）— source/standalone_examples/api/isaacsim.replicator.grasping/grasping_workflow_sdg.py
エピソードの記録と再生	isaacsim.replicator.episode_recorder
遠隔操作の記録と再生	isaacsim.replicator.teleop
再利用可能なランダム化動作スクリプト（prim にアタッチ、USD に永続化）	isaacsim.replicator.behavior
センサーのプリミティブ（LiDAR、IMU、カメラ）	isaac-sim-sensor、isaac-camera
マップからのスポーン位置の配置	occupancy-map

参考例

$ISAAC_SIM_DIR（インストールルート、またはソースからビルドした場合は <this-repo>）および $ISAAC_LAB_DIR からの相対パス：

• API の例：$ISAAC_SIM_DIR/source/standalone_examples/api/isaacsim.replicator.examples/sdg_getting_started_0[1-5].py、sdg_workflow_0[12].py、multi_camera.py、motion_blur_raytracing.py、motion_blur_pathtracing.py、cosmos_writer_simple.py、simready_assets_sdg.py、sdg_deformables.py、sdg_geomsubset.py、subscribers_and_events.py、custom_event_and_write.py、custom_fps_writer_annotator.py。
• シーンベースの SDG：$ISAAC_SIM_DIR/source/standalone_examples/replicator/scene_based_sdg/
• オブジェクトベースの SDG：$ISAAC_SIM_DIR/source/standalone_examples/replicator/object_based_sdg/
• 拡張パイプライン：$ISAAC_SIM_DIR/source/standalone_examples/replicator/augmentation/
• Cosmos の倉庫ライター：$ISAAC_SIM_DIR/source/standalone_examples/replicator/cosmos_writer_warehouse.py
• Infinigen SDG：$ISAAC_SIM_DIR/source/standalone_examples/replicator/infinigen/
• 把持 SDG：$ISAAC_SIM_DIR/source/standalone_examples/api/isaacsim.replicator.grasping/grasping_workflow_sdg.py
• Isaac Lab の模倣学習：$ISAAC_LAB_DIR/scripts/imitation_learning/