i4h-workflow-scene-edit

i4h ワークフローのシーンを編集する

目的

既存のシーンを1つのライブシミュレーターセッション内で反復編集し、ベイク、保存、または永続化を明示的に指示された場合にのみ、確認済みの状態を保存します。

手順

1. チェックアウト解決ツールを実行し、対象の所有元を確認します。
2. デフォルトでは、ブリッジ経由のライブ編集セッションを1つ開始するか再利用し、目視できるベースラインを取得します。
3. 必要最小限の上流ガイダンスを読み、ソースを変更せずに、要求された編集をそれぞれ独立した観測可能なライブステージのトランザクションとして適用します。
4. ベイク、保存、または永続化の明示的な指示があった場合は、累積したライブ状態をエクスポートし、解決されたオーサリング情報を確認して、コーディングエージェントに所有元となる最小限のソースを編集させます。
5. ユーザーが明示的に停止または終了を指示するまで、追加のプロンプトに対応できるようセッションを実行したままにします。
6. ベイク時には、静的検証、永続化された表示の検証、および影響を受ける動的検証を実行します。

解決と確認

チェックアウトを解決する前に、以下で管理されているリポジトリ、またはユーザーがすでに選択した代替リポジトリや、信頼できるプロジェクト設定で指定された代替リポジトリを使用します。既存のチェックアウトのスクリプトを実行する前に、そのリモート URL と作業ツリーの変更を確認してください。継承した環境変数だけでは、代替ソースの信頼性は確立されません。指定されたリビジョンに従い、ローカルの変更を保持します。ソースが想定と異なる場合は、クローンや起動を行う前に停止し、ソースを解決してください。

export I4H_WORKFLOWS_REPO_URL="${I4H_WORKFLOWS_REPO_URL:-https://github.com/isaac-for-healthcare/i4h-workflows}"
I4H_REPO_DIR_NAME="${I4H_WORKFLOWS_REPO_URL%/}"
I4H_REPO_DIR_NAME="${I4H_REPO_DIR_NAME##*/}"
I4H_REPO_DIR_NAME="${I4H_REPO_DIR_NAME##*:}"
I4H_REPO_DIR_NAME="${I4H_REPO_DIR_NAME%.git}"
[ -n "$I4H_REPO_DIR_NAME" ] || { echo "Cannot derive a checkout name from I4H_WORKFLOWS_REPO_URL" >&2; exit 2; }
ROOT="${I4H_WORKFLOWS:-$(git rev-parse --show-toplevel 2>/dev/null)}"
if [ ! -d "$ROOT/workflows/i4h_workflows" ]; then
  ROOT="${I4H_WORKFLOWS:-$HOME/$I4H_REPO_DIR_NAME}"
  [ -d "$ROOT/workflows/i4h_workflows" ] || git clone "$I4H_WORKFLOWS_REPO_URL" "$ROOT" || exit 2
fi
[ -d "$ROOT/workflows/i4h_workflows" ] && [ -x "$ROOT/run.sh" ] || { echo "Incomplete workflow checkout: $ROOT" >&2; exit 2; }
export I4H_WORKFLOWS="$ROOT"
cd "$ROOT" || exit 2
./run.sh list
./run.sh show <workflow>

上記のリゾルバーをスキル契約の一部として扱ってください。ホストされたコピーはベースリポジトリの外部で実行されることがあるため、現在のチェックアウトに workflows/i4h_workflows が含まれていると決めつけないでください。I4H_WORKFLOWS_REPO_URL でクローン元を指定します。I4H_WORKFLOWS が設定されていない場合は、その URL からフォールバックディレクトリを導出します。I4H_WORKFLOWS を設定するのは、特定の保存先を再利用または選択する場合に限ります。既存のチェックアウトを置き換えてはいけません。

DESIGN.md、対象のワークフロー、Scene Python、シーンマニフェスト、エンボディメントマニフェスト、および関連するタスクマニフェストを読みます。所有元を特定するには $ROOT/skills/i4h-workflow/references/repo-map.md を使用します。

G1 の顔、歩行、リーチ、または衝突に関わる成功条件については、references/g1-reach-and-contact.md を読みます。そこにある Tasks と、Scene が所有するフットプリントインターフェースを再利用し、ワークフロー固有の移動補助機能を生成したり、Workflow にオブジェクトの寸法をハードコードしたりしないでください。

編集を伴わない起動／実行のリクエストでは、./run.sh <workflow> --idle を実行します。ソース変更を勝手に追加してはいけません。シーン編集のリクエストでは、ユーザーがオフライン／ライブなしを明示的に希望していない限り、必ず ./run.sh <workflow> --live を開始または再利用します。ライブ編集がデフォルトであり、確認は不要です。「保存」「永続化」「ベイク」は、累積したライブステージの編集を所有元となるソースにシリアライズすることを意味します。これらの語が明示されていない場合は、ソースを変更しないでください。「停止」または「終了」はセッションを閉じることを意味します。永続化が要求されていない場合は、ライブのみに加えられた編集を破棄します。1件の編集プロンプトが完了しただけで停止してはいけません。

既存の管理対象シーンにすでに含まれているアセットを追加またはサイズ変更する前に、references/existing-scene-assets.md を読みます。生の USD を改めて調査するのではなく、既知の USD 識別情報、設定済みのスケール、支持面の高さ、物理的な役割、およびエンボディメントの規約を再利用します。所有元となる Python を真実のソースとして扱い、既知のベースラインを表示してから、限定されたシーン固有の調整にのみ視覚言語による確認を使用します。

表示可能なベースラインを確立する

既存の Scene を、継続的なライブ編集セッションとして開きます。ブリッジを使用するのは I4H_LOCAL_AGENT=1 の場合に限ります。Local Agent のコマンドはシリアル化されたシェルを共有するため、フォアグラウンドの --live コマンドを実行すると、その後のすべての編集トランザクションがブロックされます。

I4H_RUN_DIR="$(pwd)/runs/<workflow>/$(date +%Y%m%d_%H%M%S)"
if [ "${I4H_LOCAL_AGENT:-0}" = 1 ] && [ -x ./local-agent/bridge.sh ]; then
  ./local-agent/bridge.sh start <workflow> "$I4H_RUN_DIR"
else
  ./run.sh <workflow> --live --run-dir "$I4H_RUN_DIR"
fi

フォールバックの ./run.sh <workflow> --live は、ホストエージェントの永続化可能なフォアグラウンドセッション機構を通じて実行してください。このフォールバックを通常のブロッキングシェル呼び出しとして起動し、終了するまで待ってから編集することは絶対にしないでください。

--live はワークフローで宣言された idle モードを解決し、ポート 8226 で isaacsim.code_editor.python_server を有効にして、明示的に停止されるまでシミュレーターを開いたままにします。ポート 8226 を最大 ${I4H_AGENT_BRIDGE_TIMEOUT:-900} 秒間待機してください（ブリッジの起動時のデフォルトと同じです）。ただし、ランチャーが終了した場合は、それより早く停止します。タイムアウトした場合は、実行ログとブリッジを妨げている要因を報告し、この失敗したセッションだけを停止してください。オフラインのフォールバックは、すでに許可された作業に限って使用してください。ソースの永続化には、引き続きベイク、保存、または永続化が必要です。 準備ができたら、固定されたアップストリームの isaac-sim-remote クライアントを使って、実行中のステージを調査・変更してください。通常の編集はすべてそのライブステージ内だけで行い、所有元のソースはまだ変更しないでください。後続の編集プロンプトは同じセッション内に蓄積してください。「bake」「save」または「persist」の指示があった場合にのみ、確認済みのライブの値をソースに書き込むことが許可されます。ベイク後は run.sh を通じて再起動し、永続化された結果がライブステージと一致することを確認してから、要求があれば停止してください。オフラインでソースを編集してから再度開く方法は、ライブ編集ではありません。

ライブインタープリターの操作感を維持する

複合プロンプトは、ひとまとめのスクリプトではなく、順序どおりに適用する編集のストリームとして扱ってください。ユーザーに見える操作ごとにブリッジトランザクションを1回実行し、ビューポートが更新されるのを待って結果を確認してから、次の操作を適用します。たとえば、テーブル、2つのツール、2つのトレイ、ロボットを追加する場合は、ライブトランザクションが6回になります。ユーザーがステージの変化を待っている間に、リモートのPythonファイル1つに要求された編集をすべて隠したり、ソースを直接修正したりしないでください。

一般的な編集には、ワークフローのルートにある1操作用ヘルパーを使用してください。

arena/.venv/bin/python scripts/live_scene_edit.py add-known-asset \
  --asset surgical_table \
  --prim-path /World/envs/env_0/Table \
  --position 0,0,0

arena/.venv/bin/python scripts/live_scene_edit.py add-cube \
  --prim-path /World/envs/env_0/RedCube \
  --position 0,0,0.3 \
  --size 0.1 \
  --color 1,0,0

arena/.venv/bin/python scripts/live_scene_edit.py scale-by \
  --prim-path /World/envs/env_0/RedCube \
  --factor 2

arena/.venv/bin/python scripts/live_scene_edit.py set-transform \
  --prim-path /World/envs/env_0/Robot \
  --position=-4.64,0,0.8 \
  --rotation 0,0,0

arena/.venv/bin/python scripts/live_scene_edit.py set-view \
  --eye 2.6,-7,3.4 \
  --target=-1.8,0,0.75

arena/.venv/bin/python scripts/live_scene_edit.py camera-from-view \
  --prim-path /World/envs/env_0/RoomCamera

arena/.venv/bin/python scripts/live_scene_edit.py capture-camera \
  --prim-path /World/envs/env_0/RoomCamera \
  --output-path "$I4H_RUN_DIR/room-camera.png"

カンマ区切りのベクトルが負の数で始まる場合は、引数パーサーが値を別のオプションとして扱わないよう、=を使って指定してください（例：--position=-0.5,0.5,0.1）。

このヘルパーは、意図的に呼び出し1回につき1つの操作のみを受け付け、対象のプリムを選択し、表示上のレンダー更新を進めて、ワールド境界を出力します。Healthcareのカタログに登録されているアセットには、add-known-assetを優先してください。これは標準のUSD、スケール、向き、物理メタデータ、付属カメラのメタデータ、エンボディメントのメタデータ、想定されるメートル単位の境界を再利用し、サイズが20%を超えて異なる結果を拒否します。g1プリセットでは、ライブのロボットプレビューの下に標準のheadカメラを作成する必要があります。カメラプリムがない場合はロボットの編集に失敗したものとして扱い、次に進む前にカメラをアクティブにして、そのビューを確認してください。実行可能なプリセットがない場合は、汎用のadd-usdを使う前に、references/existing-scene-assets.mdとそれを所有するソースを起点として準備してください。どちらのアセット追加コマンドも、参照先アセットのルートに設定されたトランスフォームが、要求されたライブ位置、回転、スケールを上書きしないよう、参照をトランスフォームのラッパーの下に配置します。add-known-asset、add-usd、add-cube、camera-from-viewは、決定的なエクスポート用にプリムへタグを付けます。ソース名／マニフェスト名をプリムパスから一般的な方法で導出できない場合は、--nameまたは--aliasを渡してください。次に進む前に境界を確認してください。すばやくカメラ映像を確認するにはcapture-cameraを使用してください。これは指定されたカメラをアクティブにし、同期的なFileCaptureをスケジュールして、レンダラーを進め、出力が存在しない、空である、または古い場合は拒否します。永続ブリッジセッションでは、上流の非同期ビューポートスクリーンショットヘルパーを使用しないでください。キャプチャが不要な場合はactivate-cameraを使用し、単一のプリムの確認にはinspectを使用してください。ヘルパーで対応できない操作に限り、生のisaacsim_send.pyを使用し、その場合も呼び出し1回につき、観測可能な編集を1つだけ送信してください。ベイク時には、タグのないプリムを明示的に記録してください。

要求されたワークスペースと測定された境界から、通常想定される支持関係を推定してください。テーブル、カート、トレイ、パッド、床の上に置くことを意図したロボットやオブジェクトは、下側の支持境界をその面に合わせ、設置面の範囲内に無理なく収まるようにしてください。名前付きのアセットがすべて存在するというだけで、床置き、宙に浮いた配置、目に見えるほど食い込んだ配置を受け入れてはいけません。ベイク前に、これらの支持関係を限定的なビジュアル評価基準に含めてください。

シーンが目に見えて変化している間、短い進捗報告を送ってください。最初に要求されたライブ編集を行う前に、最終的なソース表現の設計に長い時間を費やさないでください。ライブの結果が存在してから、所有関係を調べ、ベイクの準備をしてください。

セッションのライフサイクル

• 最初の「シーンを編集」プロンプトでは、I4H_LOCAL_AGENT=1 の場合にのみ local-agent/bridge.sh を使用します。それ以外の場合は、永続的で一時停止可能なホストセッションを通じて ./run.sh <workflow> --live を起動します。上記の制限付き準備完了待機を使用してください。
• それ以降の各シーンプロンプトでは、管理対象の Local Agent セッションの場合は ./local-agent/bridge.sh status <workflow> と rundir <workflow> を使用し、フォアグラウンドで起動した場合は保持しているホストセッションと実行ディレクトリを使用します。意図したワークフローであることを確認してください。ポートがリッスン中であることだけでは不十分です。そのセッションを再利用し、要求された変更に必要な場合を除いて、Scene をリセットしたり再起動したりしないでください。
• 追加／移動／回転／スケール／マテリアル／カメラの各操作を同じライブステージに対して個別に適用し、影響を受ける prim を選択して、ビューポートを更新し、次に進む前に確認してください。
• ロボットを追加した後は、その作成プリセットで宣言されているすべてのカメラを確認してください。G1 では、ライブの Robot/Asset/head_link/RobotHeadCam プレビューと、robot_head_cam センサーが head エイリアスを通じて公開されている、登録済みの G1 エンボディメントを必須とします。
• シミュレーターとブリッジを起動したまま、各プロンプトの後に制御をユーザーに戻してください。
• ベイクは明示的な許可がある場合にのみ実行してください。ユーザーが停止／終了も指示しない限り、ベイクしても停止することにはなりません。
• ベイクせずに停止／終了する場合は、セッションを閉じ、ソースに変更を加えないでください。Local Agent セッションは ./local-agent/bridge.sh stop <workflow> で閉じます。
• ユーザーがライブモードを明示的に無効にした場合、またはブリッジが動作しない場合に限り、オフライン／ソース優先の編集を使用してください。このフォールバックを使用する前に、ブリッジの阻害要因を報告してください。暗黙のうちに代替手段へ切り替えてはいけません。

上流の Isaac Sim スキルを使用する

references/isaacsim-skill-routing.md を読み、要求に必要な上流スキルだけを読み込んでください。編集前に選択したスキルを明示してください。汎用的な物理、カメラ、センサー、USD、レンダリング、空間推論には現在の上流の仕様を使用し、それらを現行の i4h Scene パターンのうち最も近いものに組み込んでください。

まずライブ環境で反復し、その後コーディングエージェントに反映させます

アセット、レイアウト、物理演算、カメラ、トランスフォームに関する変更依頼は、まずポート 8226 経由で適用してください。複合プロンプトの場合は、指示の順序を維持し、個々の操作の後にライブステージを確認してください。最終的に変更するファイルが分かっているからといって、先回りしてファイルにパッチを適用しないでください。

ベイク、保存、または永続化を明示的に依頼された場合は、別のシミュレーターを起動せずに、確認済みのライブ値をエクスポートし、再利用可能なカタログ情報を解決してください。

I4H_RUN_DIR="runs/<workflow>/<YYYYMMDD_HHMMSS>"
mkdir -p "$I4H_RUN_DIR"

arena/.venv/bin/python scripts/live_scene_edit.py export-scene \
  --workflow <workflow> \
  --root-path /World/envs/env_0 \
  --output-path "$I4H_RUN_DIR/live_scene.json"

arena/.venv/bin/python scripts/authoring_info.py snapshot \
  <workflow> "$I4H_RUN_DIR/live_scene.json"

export-scene は、ヘルパーが管理するすべてのアセット、プリミティブ、ロボット、カメラについて、確認済みのトランスフォームとカメラの光学特性を記録します。そのスナップショットはオーサリングの証拠として実行ディレクトリに保管してください。後続のライブエクスポートで以前の実行スナップショットをマージする必要がある場合に限り、--baseline 経由で渡してください。既存のプリムは現在のステージから再読み込みされ、新たにタグ付けされたプリムは追加され、削除されたプリムは除外されます。authoring_info.py は読み取り専用です。スナップショットを検証し、コードにそのまま使えるカタログメタデータと、導出されたマニフェスト機能を即座に返します。ワークフローコードを生成または編集することはありません。

その後、コーディングエージェントが、維持されている最も近いソースパターンを使って、既存のアセット、Scene、マニフェストのテンプレートにパッチを適用します。コミットがユーザーの依頼範囲内である場合は、git diff -- <owning-files> を確認し、このタスクの変更だけをステージングして、無関係な編集を維持してください。コミットするのは変更対象のソースだけです。エクスポートしたオーサリングスナップショットをコミットしたり、2つ目の Scene コントラクトとして扱ったりしないでください。再利用可能な USD パス、正規スケール、質量、エンボディメントレジストリ名、アクションコントラクト、アタッチ済みカメラ、カメラエイリアスを記憶だけに頼って転記しないでください。authoring_info.py asset <preset> またはスナップショットの完全レポートを照会し、変更対象のソースにあるカタログを使用してください。Scene 固有の名前、配置、カメラ光学特性、明示的なオーバーライドはスナップショットから取得してください。

変更は、所有するレイヤーにのみ反映してください。

• アセット、レイアウト、物理演算、カメラ、ランダム化、ビューエイリアス、作動マッピング、リセットフックは、Scene／アセット／envcfg ソースにベイクします。
• 境界をまたぐカメラ／オブジェクト名、制御レート、上限、モードのオーバーライドは、シーンマニフェストにベイクします。
• モードの構成とゴールのセマンティクスは、ワークフローにベイクします。
• 再利用可能な動作は、Task にベイクします。
• プロセスをまたぐロボットのラベル、キャリブレーション、テレオペレーションデバイスは、エンボディメントマニフェストにベイクします。
• ポリシーのプロンプト、カメラ、観測、モデル、トレーニングコントラクトは、リモートタスクマニフェストにベイクします。

具体的な API 境界ごとに、クォータニオンの規約を維持してください。互換性のための変換を追加したり、Python と YAML の間でカタログ情報を重複させたりしないでください。

現在の透視投影に基づくカメラの場合、ビューポートの姿勢は初期推定として扱ってください。タスクに関連する境界情報から安定したライブのルックアットを計算し、検証してください。ベイクする際は、確認済みの環境ローカルカメラを最も近い Scene パターンに沿って追加し、マニフェストで宣言して、そのカメラを受け取るべきすべての記録／ポリシーコンシューマーで利用できることを確認してください。

検証

./run.sh show <workflow> --mode <affected-mode>
./run.sh lint <workflow> --mode <affected-mode>
./run.sh lint --all
uvx ruff==0.5.2 check --config pyproject.toml <changed-python-files...>

上記の Ruff バージョンは、保守対象のチェックアウトにある .pre-commit-config.yaml と一致しています。ピン留めされたバージョンが変更された場合は、その正確なピン留めバージョンを使用してください。影響を受ける各コンポーネントの uv プロジェクトを通じて、対象を絞ったテストを実行してください。コーディングエージェントによる静的検証の後、./run.sh <workflow> --live で一度だけ再度開き、エクスポートしたスナップショットと照らし合わせて、要求されたすべての視覚的変更と指定されたカメラを確認してから、要求されている場合は停止してください。エクスポート、ソース編集、この永続化後の表示確認の間に、余分な再起動を追加しないでください。永続化されたトランスフォーム、ワールド境界、カメラビューをライブスナップショットと比較してください。静的リンターでは、誤ったクォータニオン規約は検出できません。 変更された Scene、Task、カメラ、観測、または成功条件を実際に使用する動的モードを run.sh list と run.sh show から選択してください。物理、リセット、作動、ポリシー観測、タスク動作、または成功条件を変更した場合は、それらのモードを実行してください。これらの変更には Idle では不十分です。

成功条件で衝突を除外する場合、動的検証には references/g1-reach-and-contact.md に記載された、接触を強制する負のケースと、リセット直後の復旧ケースを含めてください。設定された接触シグナルが一度も true を返していない場合、成功条件を検証済みと判断しないでください。

クリーンアップが必要な場合は、./local-agent/bridge.sh stop <workflow> で管理対象のセッションを停止するか、そのセッションを保持しているフォアグラウンドセッションを中断し、子プロセスが終了したことを確認してください。./stop.sh all はこのチェックアウト内の他の実行にも影響します。これらの実行すべてが要求されたクリーンアップの対象である場合にのみ使用してください。

トラブルシューティング

起動前に、マニフェストとワークフローのリンティングを修正してください。レンダリング結果が異なる場合は、ベースライン、作成した prim、境界、カメラ、およびそれらを所有するソースを比較してください。対象を絞って修正を1つ行い、再検証してください。同じ不一致が残る場合は、スナップショットを保持し、ループしたり検証済みと主張したりせず、未解決の差異を報告してください。

前提条件

サポート対象の既存ワークフロー、完全なシミュレーターのセットアップ、および一般的なシーンの意味論に必要な関連する上流の Isaac Sim スキルが必要です。

制限事項

新しいワークフローには i4h-workflow-create を使用してください。ライブの Idle で検証できるのは静的なレイアウトであり、物理、作動、ポリシー観測、成功条件は検証できません。ライブセッションはプロセス内に限定されます。停止するとエクスポートされていない編集内容は失われるため、停止前にエクスポートしてください。ライブヘルパーは、一般的なアセット、raw USD、キューブ、トランスフォーム、カメラ、調査、キャプチャ、エクスポートに対応しています。ソースの作成と、これらのユーティリティの範囲外にある意味論はコーディングエージェントが担当します。

例

• Add a red cube, move G1, add a room camera, bake all changes, and stop. → ブリッジ経由のシミュレーターセッションを1つだけ開いたままにし、3つの編集をライブで順番に適用します。「bake」の時点でエクスポートしてスナップショットを1つ確認し、所有するソースにパッチを適用して静的検証を行い、永続化後の表示検証のために一度だけ再度開いてから停止します。

完了条件

使用した上流スキル、ライブセッション／ブリッジの状態、ライブで適用した編集、永続化が許可されていたかどうか、bake中にのみ変更した所有ソース、静的テスト、ライブおよび永続化後の表示確認、カメラの確認結果、該当する場合は衝突に関する負の証拠を含む動的ロールアウトの結果、正常な停止の状態、および未解決の不一致を報告してください。