vss-generate-video-calibration

目的

ローカルファイル、RTSP ストリーム、または同梱のサンプルデータセットを使用して AutoMagicCalib をエンドツーエンドで実行し、必要に応じて AMC マイクロサービスをデプロイします。

手順

以下のルーティング表とステップごとのワークフローに従ってください。ワークフロー、クイックスタート、またはフローで終わる各セクションは、上から順に実行することを想定しています。詳細なリファレンス資料は references/ にあります。選択した入力モードに必要なリファレンスのみを読み込んでください。

例

エンドツーエンドの実行例は evals/ にあります（各 *.json マニフェストには実行可能なシナリオが含まれています）。また、以下の各ワークフローの curl ブロックにも例が記載されています。nv-base validate <this-skill-dir> --agent-eval を実行して、Tier-3 評価でこれらを再生してください。

制限事項

• 呼び出し元からアクセス可能な、対応する VSS プロファイル／マイクロサービスがデプロイされている必要があります。
• NGC がホストするモデルおよび NIM には、レート制限、GPU メモリ要件、ライセンス上の制限が適用される場合があります。
• 同時実行数、GPU メモリ、ストレージの制限は、ホストのハードウェアとプロファイルの compose ファイルによって異なります。

トラブルシューティング

• エラー：REST 呼び出しで接続拒否が返されます。原因：対象のマイクロサービスが実行されていません。解決策：/docs または /health を確認し、vss-deploy-profile または対応する vss-deploy-* スキルを使用して再デプロイしてください。
• エラー：NGC からのプルで HTTP 401/403 が返されます。原因：NGC_CLI_API_KEY がないか、有効期限が切れています。解決策：再試行する前に docker login nvcr.io を実行し、キーを再度エクスポートしてください。
• エラー：コンテナーが OOM になる、またはモデルの読み込みに失敗します。原因：選択したプロファイルに対して GPU メモリが不足しています。解決策：より小さいバリアントに切り替えるか、docker compose down を実行して GPU を解放してください。

VSS 動画キャリブレーションの実行

3 種類の入力ソースのいずれかを使用して AutoMagicCalib を実行し、マイクロサービス REST API 経由でキャリブレーションを進めます。入力の準備方法はソースごとに異なりますが、verify_project 以降の処理はすべて共通で、このファイルに記載されています。適切な入力モードのリファレンスを選び、以下の共通キャリブレーション後続処理と組み合わせてください。

共通ヘルパーのリファレンスは必要な場合にのみ読み込みます。

• モードのリファレンスで、共通の create_project、動画アップロード、または引き継ぎ用のスニペットが必要な場合は、references/common-steps.md を読んでください。
• verify → calibrate → poll → results の後続処理を再利用可能な Python 実装で行う必要がある場合は、references/calibration-tail.md を読んでください。

入力のルーティング

ユーザーのリクエストに対応するモードを選択し、入力の収集、モード固有の API 呼び出し、完全な Python スクリプトについて、そのモードのリファレンスを読み込んでください。

ユーザーの発言／条件	モード	リファレンス
「AMC を起動」／「自動キャリブレーションをデプロイ」／「auto-magic-calib をセットアップ」／「AMC マイクロサービスを開始」	deploy	references/deploy-auto-calibration-service.md
「動画をキャリブレーション」／「動画ファイルからキャリブレーション」／ローカルの cam_*.mp4 ファイル	videos	references/videos.md
「RTSP ストリームをキャリブレーション」／「ライブカメラからキャリブレーション」／ライブ RTSP URL	rtsp	references/rtsp.md
「サンプルデータセットをテスト」／「AMC のインストールを検証」／「起動してテスト」	sample-dataset	references/sample-dataset.md

**判別ルール：**ユーザーが AMC の起動／デプロイ／セットアップを依頼しており、キャリブレーションについては言及していない場合は、deploy を選択します。RTSP URL が提供された場合は rtsp を選択します。ローカルファイルまたは動画ディレクトリについて言及された場合は videos を選択します。インストールの検証や同梱のサンプルのテストを依頼された場合は sample-dataset を選択します。複合的な依頼（例：「AMC を起動して動画をキャリブレーション」）の場合は、最初に deploy を実行してから、キャリブレーションモードを実行します。判断が難しい場合は、AskUserQuestion を使用して確認してください。

前提条件（すべてのキャリブレーションモード共通）

• AMC マイクロサービスと UI が起動していること。起動していない場合は、先に references/deploy-auto-calibration-service.md の手順を進めてください。
• マイクロサービスが http://<HOST_IP>:${VSS_AUTO_CALIBRATION_PORT:-8010}/v1/ready でアクセス可能であり、{"code":0,...} が返ること。
• プロジェクトディレクトリにコンテナユーザーが書き込めること。直前にデプロイしておらず、デプロイ手順の Step 5 がまだ実行されていない場合は、references/deploy-auto-calibration-service.md § Step 5 の書き込みテストを確認してください。確認しない場合、最初の create_project で [Errno 13] Permission denied が返されます。
• requests がインストールされた Python 3 があること（各入力モードのリファレンスには、直接実行する際の自動修復可能な venv フォールバックが含まれています）。

モード固有の前提条件（rtsp の VIOS、sample-dataset のサンプル zip）は、それぞれのリファレンスに記載されています。

共通のキャリブレーション後半手順

検証 → キャリブレーション → ポーリング → 結果の確認という手順は、入力モードにかかわらず同じです。モード固有のリファレンスに従って動画をアップロードした後、RTSP クリップを取り込んだ後、または同梱のサンプルをアップロードした後、この手順を実行してください。共通の Python スニペットは references/calibration-tail.md を使用してください。

ステップ A — プロジェクトを検証する

POST /v1/verify_project/<project_id>

応答：{"project_state": "READY"} — キャリブレーションを開始する前に、状態が READY である必要があります。READY でない場合は、動画、アライメント、レイアウトがそろっていることを（API または UI での手動アライメントを通じて）再確認してください。

ステップ B — キャリブレーションを開始する

キャリブレーションの前に、プランを確認してください。 設定ファイルと検出器が自動検出された場合も、ユーザーに選択を尋ねた場合も、概要を短く提示し、POST /calibrate の前に AskUserQuestion で確認してください。解決済みの値がデフォルト値なので、確認はワンクリックで完了します。ただし、ユーザーは検出器を切り替えたり、自動検出された設定ファイルを使わないようにしたりできます。次の項目を要約してください。

• 検出器 — resnet または transformer（送信する値）。
• キャリブレーション設定 — 適用するファイル（パス）、またはデフォルトのパラメーター（必要に応じて、先に UI で調整できます。下記を参照）。
• 任意のオーバーライド — 該当する場合は、グラウンドトゥルース zip と焦点距離。

sample-dataset のインストール確認では resnet が固定で使われ、この確認なしで進められます。

POST /v1/calibrate/<project_id>
Content-Type: application/json

{"detector_type": "resnet"}   # or "transformer"

detector_type は独立した /calibrate パラメーターであり、/v1/config/<id> では使用されません。ユーザーからキャリブレーション設定ファイルが提供されている場合は、そのファイルから "detector" / "detector_type" を解析して値を使用してください。ファイルに指定がない場合、デフォルト（resnet）が上記の確認時に提示する値となります。ユーザーはキャリブレーションの前に、そこで切り替えられます。設定ファイルがない場合は、AskUserQuestion でユーザーに確認してください。

• resnet — デフォルト。高速です。
• transformer — 低速ですが、激しいオクルージョンに適しています。

UI のステップ 3（Parameters）では検出器を選択できません。ユーザーが UI で検出器を選択したと想定しないでください。

設定ファイルがない場合は、キャリブレーションパラメーターを先に調整するかどうかも確認してください（AskUserQuestion）。

• デフォルトのパラメーターで進める — 典型的な倉庫のシーンに適しています。調整について具体的な希望がない場合に推奨されます。
• 先に UI でパラメーターを調整する — プロジェクトを開き、ステップ 3：Parameters に移動して値を変更し、Save をクリックしてから続行します。

ユーザーの選択を待ってください。調整を選んだ場合は、ユーザーが保存を完了したことを確認してから /calibrate を呼び出してください。

ステップ C — 完了を確認する

GET /v1/get_project_info/<project_id>

10 秒ごとにポーリングします。project_info.project_state：

状態	意味
RUNNING	キャリブレーション中
COMPLETED	完了
ERROR	失敗 — GET /v1/amc/calibrate/<id>/log でログを取得

キャリブレーションが始まったら、実行中にユーザーが進行状況を確認できるよう、プロジェクト ID、UI の URL（http://<HOST_IP>:${VSS_AUTO_CALIBRATION_UI_PORT:-5000}）、ログエンドポイントを提示します。RUNNING 中は、長時間の実行が停止したように見えないよう、経過時間を含む進捗メッセージを少なくとも 1 分に 1 回出力します。ERROR の場合は、停止する前に GET /v1/amc/calibrate/<id>/log を取得し、末尾の行を表示します。ライブログは GET /v1/calibrate/<project_id>/log/<type>/stream からもストリーミングできます。

所要時間の目安：10～60 分（自前の動画）、10～30 分（同梱サンプル）。

ステップ D — 結果

GET /v1/get_project_info/<project_id>                    # project state
GET /v1/result/<project_id>/evaluation_statistics        # only if GT uploaded
GET /v1/result/<project_id>/overlay_image                # visual overlay (PNG)
GET /v1/amc/calibrate/<project_id>/log                   # calibration log

評価レスポンスには Average L2 distance(m) と Average reprojection error 0(px) が含まれます。評価メトリクスが生成されるのは、グラウンドトゥルースの GT.zip がアップロードされた場合のみです。それ以外の場合に evaluation_statistics の結果がないのは正常であり、結果報告が完了していないという意味ではありません。

COMPLETED の後は、メトリクスの有無にかかわらず、必ずユーザーがそのプロジェクトの結果を確認できる方法を案内します。

• UI — http://<HOST_IP>:${VSS_AUTO_CALIBRATION_UI_PORT:-5000} を開き、プロジェクトを選択してから Results ページでオーバーレイを確認します。
• ディスク上のオーバーレイ画像 — ${VSS_APPS_DIR}/services/auto-calibration/projects/project_<id>/output/multi_view_results/BA_output/results_ba_scaled_world/overlay_img_*.png（単眼カメラのプロジェクトでは output/single_view_results/cam_00/verification_map_overlay.png を使用します）。
• プロジェクトファイル — ${VSS_APPS_DIR}/services/auto-calibration/projects/project_<id>/。

ステップ E — VGGT によるリファインメント

AMC の実行が完了した後は、必ずプロジェクト情報の vggt_state を確認します。セットアップ時の VGGT モデルのステージングは任意であり、AMC の結果を妨げてはなりません。ただし、AMC の実行後の処理は状態に応じて行います。

• vggt_state == "READY" で、ユーザーが VGGT によるリファインメントを明示的にリクエストした場合、またはこのセットアップフローで VGGT をステージングした場合は、再確認せずに VGGT によるリファインメントを実行します。
• vggt_state == "READY" でも、今回のリクエストより前に VGGT がステージング済みで、ユーザーが VGGT でリファインした出力を求めていない場合は、実行を開始する前に AskUserQuestion でリファインメントを実行するかどうか尋ねます。
• VGGT の準備ができていない場合は、リファインメントをスキップし、モデルのステージング後に VGGT によるリファインメントを利用できることを伝えます（references/deploy-auto-calibration-service.md のステップ 2 を参照）。

POST /v1/vggt/calibrate/<project_id>
GET  /v1/get_project_info/<project_id>                    # poll vggt_state
GET  /v1/vggt_results/<project_id>/evaluation_statistics  # VGGT metrics

設定ファイルと検出器のパターン

3 つすべてのモードで任意です。ユーザーから JSON 設定ファイル（通常は UI のステップ 3 でダウンロードしたもの）が提供された場合は、内容をそのまま POST します。

POST /v1/config/<project_id>
Content-Type: application/json

<file contents, posted as-is>

このファイルは、ユーザーが UI のステップ 3 で調整する設定（補正、バンドル調整、評価パラメーター、検出器など）を置き換えます。POST が成功した後は、ファイル内の "detector" / "detector_type" も解析します。値が "resnet" または "transformer" の場合は、ステップ B の /calibrate 呼び出しでその値を使用します（検出器は別個の API パラメーターであり、/config では使用されません）。

2xx 以外のレスポンスはユーザーに伝え、暗黙にフォールバックしないでください。ユーザーが UI フォールバック経路を選択した場合は、この呼び出し全体をスキップします。

UI フォールバックパターン

アラインメント／レイアウトファイルがディスク上にない場合は、ユーザーに適切な AMC UI の手順を案内します。

• 設定がない場合 →「UI プロジェクト <project_id> を開き、ステップ 3：パラメーターに進み、設定ダイアログで調整する（またはデフォルトを受け入れる）よう案内し、［保存］をクリックしてもらいます。」また：/calibrate の呼び出し前に、AskUserQuestion を使って、resnet と transformer のどちらの検出器を使用するかユーザーに尋ねます。ステップ 3 では検出器の選択を扱いません。
• レイアウトがない場合 →「UI プロジェクト <project_id> を開き、ステップ 2：動画設定に進み、layout.png のみをアップロードしてもらいます（動画は API／RTSP 経由ですでに添付されているため、再アップロードしないでください）。［保存］をクリックしてもらいます。」
• アラインメントがない場合 →「UI プロジェクト <project_id> を開き、ステップ 4：アラインメントに進み、alignment_data.json をアップロードするか、レイアウト上で対応点を指定してもらいます。［保存］をクリックしてもらいます。」

ユーザーの確認を待ちます。アラインメント／レイアウトの場合は、続行前にディスク上で確認します。

# Project state lives under $VSS_APPS_DIR/services/auto-calibration/projects
# (the path bind-mounted into the MS container in
#  deploy/docker/services/auto-calibration/ms/compose.yml).
HOST_PROJECTS="${VSS_APPS_DIR}/services/auto-calibration/projects"

ls "$HOST_PROJECTS/project_<project_id>/manual_adjustment/"
# Expected: alignment_data.json, layout.png

成功条件

• ポーリング後の project_state == "COMPLETED"。
• 手動アラインメントを使用した場合：${VSS_APPS_DIR}/services/auto-calibration/projects/project_<id>/manual_adjustment/ に alignment_data.json と layout.png が含まれていること。
• GT をアップロードした場合：評価結果が一般的な閾値を満たすこと（データでは Average L2 distance(m) < 1.5、Average reprojection error 0(px) < 5、同梱のサンプルでは < 10）。
• ERROR 状態にならないこと。

主な出力ファイル

${VSS_APPS_DIR}/services/auto-calibration/projects/project_<project_id>/ 内：

project_<project_id>/
├── manual_adjustment/
│   ├── alignment_data.json
│   └── layout.png
├── output/
│   ├── single_view_results/cam_XX/
│   │   ├── camInfo_hyper_XX.yaml
│   │   └── trajDump_Stream_0_3d.txt
│   ├── multi_view_results/BA_output/results_ba/
│   │   ├── initial/camInfo_XX.yaml
│   │   └── refined/camInfo_XX.yaml          # ← final calibration
│   └── multi_view_results/BA_output/results_ba_scaled_world/
│       └── overlay_img_XX.png               # ← visual overlay for review
└── calibration.log

共通のトラブルシューティング

モード固有の問題については、各リファレンスのトラブルシューティング表を参照してください。

問題	対処方法
verify_project の状態が READY ではない	動画がアップロード／取り込み済みで、アラインメントとレイアウトが存在することを確認します（API 経由または UI での手動アラインメント経由）。モード別のアップロード手順はリファレンスを参照してください。
UI の手順後も手動アラインメントファイルがない	ユーザーが［保存］をクリックしていません。${VSS_APPS_DIR}/services/auto-calibration/projects/project_<id>/manual_adjustment/ が存在することも確認します。
キャリブレーションが RUNNING のまま 90 分以上経過	GET /v1/amc/calibrate/<id>/log を確認します。通常はトラックレットが不足しています（シーンが静止しすぎています）。ルート README.md の「カスタムデータセット」ガイドラインを参照してください。
すぐに ERROR 状態になる	動画の命名を確認します。cam_00.mp4、cam_01.mp4、…のように連番である必要があります（videos モード）／camera_name ラベルを使用します（RTSP モード）。
L2 は低いが再投影誤差が高い	入力のアップロード時に focal_length の明示的なオーバーライドを指定します（videos／rtsp のリファレンスを参照）。
VGGT が INIT のままで READY にならない	VGGT モデルが読み込まれていません。references/deploy-auto-calibration-service.md のステップ 2 を参照してください。
アップロードがタイムアウトする	動画のサイズが大きい場合は、モード別 Python スクリプトの timeout=300 を、たとえば 600 に増やします。
ポートスキャンでバックエンドが見つからない	バックエンドが実行されていません。まず references/deploy-auto-calibration-service.md の手順を進めてください。

後続スキル向け — MV3DT エクスポート

後続のコンシューマー（たとえば、別のチームが所有する Multi-View 3D Tracking スキル）は、マイクロサービスから MV3DT 形式のキャリブレーション出力を直接取得します。このスキルは project_id を返します。後続スキルは次を呼び出します。

GET /v1/result/{project_id}/mv3dt_result?result_type=amc
# Response: application/zip — mv3dt_output.zip containing transforms.yml

VGGT で補正した出力の場合（VGGT が COMPLETED まで実行された場合のみ利用可能。ステップ E を参照）：

GET /v1/result/{project_id}/mv3dt_result?result_type=vggt
# Response: application/zip — vggt_mv3dt_output.zip

後続スキルのフロー：

1. ユーザーの入力を使ってこのスキルを呼び出し、出力された project_id を取得します。
2. スキルが戻るまで待ちます（内部で COMPLETED までポーリングします）。
3. GET /v1/result/{project_id}/mv3dt_result?result_type=amc を実行し、ZIP をローカルに保存します。
4. VGGT も実行された場合は、必要に応じて ?result_type=vggt を取得して、補正済み MV3DT を取得します。

関連スキル

• vss-manage-video-io-storage — VIOS API スキル。VIOS への接続が必要なのは rtsp キャリブレーションモードのみです。

ルート README.md の「カスタムデータセット」および「キャリブレーションワークフロー（UI）」の各セクションでは、入力動画のガイドラインと、この API フローに代わる UI 主導の方法について説明しています。

bump:1