amc-run-video-calibration

スキル：動画ファイルからキャリブレーションする

このスキルを使用するタイミング

ユーザーが録画済みの MP4 ファイルを持っていて、AMC REST API を使ってキャリブレーションしたい場合に、このスキルを有効にしてください。よくあるプロンプトの例：

• 「動画をキャリブレーションして」／「これらの動画で AMC を実行して」
• 「動画ファイルからキャリブレーションして」

ユーザーが用意した録画済みの MP4 ファイルを使い、REST API 経由でキャリブレーションします。CLI スクリプトや Docker のバインドマウントは不要です。稼働中のマイクロサービスとファイルがあれば実行できます。

ライブ RTSP ストリームや rtsp://... URL には、このスキルを使用しないでください。そのリクエストは skills/amc-run-rtsp-calibration/SKILL.md に振り分けてください。

目的

ユーザーが提供したマルチカメラデータセットを使い、プロジェクトの作成、MP4 のソート済みアップロード、ローカルアセットの解決、必要な場合に限った UI の代替手段、プロジェクトの検証、キャリブレーション、ポーリング、評価、および任意の VGGT による補正をエージェントが進められるようにします。

前提条件

• AMC マイクロサービスと UI が稼働していること（skills/amc-setup-calibration-stack/SKILL.md に従ってください）
• マイクロサービス URL を把握していること（リモート AMC には https://<HOST_IP>:<MS_PORT> を、ループバックには http://localhost:<MS_PORT> を使用）および UI URL
• 動画ファイルがローカルにあり、連番の cam_00.mp4、cam_01.mp4、…という名前で、時間同期済み、解像度は約 1920×1080 であること
• requests を使用できる Python 3
• AMC がプロジェクト出力を既定の projects/ ディレクトリ以外に保存する場合、ホスト側の PROJECTS_DIR を把握していること

操作モデル

• 「ホストの質問メカニズム」とは、端末の stdin、IDE の質問ツール、または同等の対話型ダイアログなど、短いユーザー判断を求めるランタイム組み込みのプロンプト API を指します。
• そのメカニズムが利用できない場合は、チャットで質問し、ユーザーの確認またはファイルがない場合の判断が必要な、確認を要する手順に進む前に回答を待ってください。
• 無人実行の場合、付属スクリプトにはすべての UI 以外の入力を事前に指定する必要があります。また、CONFIRM_CALIBRATION=true が設定されていない限り、/calibrate の前に終了します。任意の VGGT 手順には、別途 RUN_VGGT=true を指定する必要があります。

データのプライバシー

このスキルを通じてアップロードされた動画ファイルは、AutoMagicCalib バックエンド（REST エンドポイント）に送信されます。バックエンドが信頼できるプラットフォーム／ネットワーク上にデプロイされている場合に限り、このスキルを使用してください。

入力

• 必須入力：VIDEO_DIR、BASE_URL、PROJECT_NAME。
• 任意のローカル入力：CONFIG_FILE、ALIGNMENT_JSON、LAYOUT_PNG、GT_ZIP、FOCAL_LENGTHS、DETECTOR_TYPE。
• 任意の制御入力：CONFIRM_CALIBRATION、RUN_VGGT、PROJECTS_DIR、CALIBRATION_TIMEOUT_SECONDS、VGGT_TIMEOUT_SECONDS。
• BASE_URL には、ループバック以外のホストでは HTTPS を使用してください。信頼できる開発環境で、意図的にリモートのプレーン HTTP を使用する場合に限り、ALLOW_INSECURE_HTTP=true を設定してください。
• 設定、アラインメント、レイアウトの解決順序：明示的なパス、ローカルで自動検出された候補が 1 件、UI の代替手段。

ユーザーに確認する内容

必須

（動画の命名規則とマイクロサービス URL は上記の前提条件に記載されています。以下の入力を取得してください。）

1. 動画ディレクトリ — スキルが cam_*.mp4 を検索し、アルファベット順にアップロードするフォルダー。
2. マイクロサービス URL
3. プロジェクト名 — 短い説明的な文字列

自動検出（見つからない場合のみ確認）

スクリプトは動画ディレクトリ、その直下のサブディレクトリ、および親ディレクトリを検索します。一致する候補がちょうど 1 件見つかった場合はそれを使用します。それ以外の場合、スクリプトは検索した場所を表示し、明示的なパスまたは UI の代替手段に進みます。

ファイル	候補ファイル名	UI の代替手段
キャリブレーション設定	settings.json、config.json、calibration_config.json	UI のステップ 3：パラメーター
アラインメント JSON	alignment_data.json	UI のステップ 4：アラインメント
レイアウト PNG	layout.png	UI のステップ 4：アラインメント

設定ファイルを送信すると UI のステップ 3 が置き換わり、検出器（resnet／transformer）が固定される場合があります。この値は /calibrate に別途渡されます。ステップ 4 を参照してください。

任意

4. 正解データの ZIP ファイル — _World_Cameras_Camera_XX/ フォルダーを含む GT.zip（評価指標を利用できるようになります）
5. 焦点距離 — カメラごとに 1 つ。例：1269.0, 1099.5, 1099.5
6. 検出器の種類 — resnet（デフォルト、高速）または transformer（低速ですが、オクルージョンに強い）
7. VGGT のリファインメントを実行しますか？ — AMC の完了後に VGGT の準備ができている場合は、リファインメントを実行するかユーザーに確認します（セットアップスキルを参照）

入力動画のガイドラインと正解データの形式については、ルートの README.md の「Custom Dataset」セクションを参照してください。

---

利用可能なスクリプト

スクリプト	用途	主な入力
run_video_calibration.py	ローカルの MP4 データセットに対して、プロジェクトの作成、アップロード、検証、キャリブレーション、ポーリング、評価、および任意の VGGT リファインメントを実行します。	必須：BASE_URL、PROJECT_NAME、VIDEO_DIR。任意：CONFIG_FILE、ALIGNMENT_JSON、LAYOUT_PNG、GT_ZIP、FOCAL_LENGTHS、DETECTOR_TYPE、CONFIRM_CALIBRATION、RUN_VGGT、PROJECTS_DIR、CALIBRATION_TIMEOUT_SECONDS、VGGT_TIMEOUT_SECONDS、ALLOW_INSECURE_HTTP。

手順

以下のエンドポイントはすべて、Complete Python Script でエンドツーエンドに実装されています。説明文はワークフローとエージェントが判断すべき内容を示し、実行可能なスクリプトが正式な仕様です。

ステップ 1 — プロジェクトを作成する

POST /v1/create_project（フォームフィールド project_name）→ 返された project_id を保存します。

ステップ 2 — 動画をアップロードする（必須）

POST /v1/upload_video_files/<project_id>（multipart files）。アルファベット順にアップロードしてください。サーバーはアップロード順にカメラのインデックスを割り当てます。付属のスクリプトは、連番でないカメラ番号や 0 以外から始まるカメラ番号を事前に拒否します。ディレクトリには、番号に欠けがないよう cam_00.mp4、cam_01.mp4、... を格納する必要があります。

ステップ 3 — ローカルファイルを解決する（自動スキャン、ユーザーに確認、または UI）

キャリブレーション設定、アライメント、レイアウトそれぞれについて、次の解決手順を実行します。

自動使用ルール： 一致するファイルがちょうど 1 つ見つかった場合、スクリプトはそのファイルを自動的に使用し、解決されたパスを表示します。そのファイルについて、追加の確認は行いません。

1. 候補ファイル名（上の表を参照）を対象に、VIDEO_DIR、VIDEO_DIR の 1 階層下のサブディレクトリ、および VIDEO_DIR.parent を自動スキャンします。
2. 一致がちょうど 1 つの場合は、そのファイルを使用し、見つかったファイルを表示します。
3. 一致が 0 件または複数件の場合は、検索した場所を表示してから、ホストの質問機能を使ってユーザーに明示的なパスを尋ねます。利用できない場合はチャットで尋ね、返答を待ちます。ファイルがない場合は、UI による代替手順の対象として記録します。
4. UI による代替手順：該当する UI の手順を完了するようユーザーに伝え、確認を待ってからステップ 6 に進みます。その後、UI から提供されたアライメント／レイアウトデータが揃っているかどうかは、verify_project を正とする情報源として扱います。

ステップ 4 — 解決したファイルをアップロードする

ローカルで解決した各ファイルをアップロードします。

ファイル	エンドポイント	備考
キャリブレーション設定	POST /v1/config/<project_id>（JSON、そのまま POST）	UI のステップ 3（補正、バンドル調整、評価、検出器、…）を置き換えます。2xx 以外の応答はユーザーに通知します。暗黙のフォールバックは行いません。UI による代替手順の場合はスキップします。
アライメント	POST /v1/upload_alignment/<project_id>（alignment_data.json）
レイアウト	POST /v1/upload_layout/<project_id>（layout.png）
正解データ（任意）	POST /v1/upload_gt_file/<project_id>（GT.zip）	評価指標を利用できるようになります
焦点距離（任意）	POST /v1/upload_focal_length/<project_id>（focal_length= を繰り返し指定）	GeoCalib の推定値を上書きします

ローカルで解決したすべてのファイルを、順序を問わず先にアップロードします。ローカルファイルのアップロード完了後、未解決のファイルがある場合のみステップ 5 に進み、その後、組み立てたプロジェクトを検証するため、ステップ 6 を 1 回だけ実行します。

設定の POST が成功したら、ファイル内の "detector"／"detector_type" を解析します。値が "resnet" または "transformer" の場合は、ステップ 7 の /calibrate 呼び出しでその値を使用します（検出器は /config では処理されない別個の API パラメーターです）。

ステップ 5 — UI によるフォールバック（ユーザーがローカルに持っていないファイルのみ）

ステップ 3 で設定／アラインメント／レイアウトのいずれかが解決されなかった場合は、該当する UI の手順にユーザーを案内します。

• 設定が不足している場合 → 「UI プロジェクト <project_id> を開き、ステップ 3：パラメーターに進んで、設定ダイアログで調整する（またはデフォルトを受け入れる）をクリックし、保存します。」また：/calibrate を呼び出す前に、ホストの質問機能を使ってどの検出器を使用するか（resnet または transformer）をユーザーに尋ねます。利用できない場合は、チャットで尋ねて返答を待ちます。UI のステップ 3 では検出器の選択は行いません。
• アラインメントまたはレイアウトが不足している場合 → 「UI プロジェクト <project_id> を開き、ステップ 4：アラインメントに進んで、レイアウトをアップロードし、対応点に印を付けて、保存します。」

ユーザーの確認を待ちます。非対話型のスクリプト実行では、必要なファイルをあらかじめ提示してください。スクリプトは入力を待つのではなく、明確なメッセージを表示して終了します。UI によるフォールバックで AMC の projects/ ストレージへのローカルアクセスを要求しないでください。サーバー側の確認には、ステップ 6 を正式な手順として使用します。

ステップ 6 — プロジェクトの確認

POST /v1/verify_project/<project_id> → キャリブレーションを開始する前に、{"project_state": "READY"} が返される必要があります。

ステップ 7 — キャリブレーションの開始

キャリブレーションの前に、計画を確認します。 設定ファイルと検出器が自動検出された場合でも、ユーザーに尋ねた場合でも、概要を簡潔に提示し、ホストの質問機能を使って POST /calibrate の前にユーザーから明示的な確認を得てください。利用できない場合は、チャットで尋ねて返答を待ちます。解決された値がデフォルトなので、確認はワンクリックで済みますが、ユーザーは検出器を切り替えたり、自動検出された設定ファイルをスキップしたりできます。単独の Python スクリプトは stdin が対話型の場合にプロンプトを表示します。非対話型の実行では、CONFIRM_CALIBRATION=true が設定されていない限り、/calibrate の前に終了します。以下を要約します。

• 検出器 — resnet または transformer（送信する値）。
• キャリブレーション設定 — 適用するファイル（パス）、またはファイルがない場合は「デフォルト」。
• 任意のオーバーライド — GT の zip ファイルと焦点距離（指定されている場合）。

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

{"detector_type": "resnet"}

ステップ 8 — 完了までポーリング

GET /v1/get_project_info/<project_id> を 10 秒ごとに実行します — project_info.project_state は RUNNING → COMPLETED（または ERROR。ログを取得してください）に変化します。所要時間の目安は、動画の長さと検出器によって 10～60 分です。同梱のスクリプトは CALIBRATION_TIMEOUT_SECONDS=5400 による 90 分の上限をデフォルトで設定しています。プロセスを予告なく終了させるのではなく、より長時間の実行にはこの環境変数の値を大きくしてください。

ステップ 9 — 結果の取得

GET /v1/result/<project_id>/evaluation_statistics（GT をアップロードした場合のみ。Average L2 distance(m) と Average reprojection error 0(px) が含まれます）、およびキャリブレーションログ用の GET /v1/amc/calibrate/<project_id>/log を実行します。GT をアップロードしていて evaluation_statistics が 200 以外を返した場合、GT がないケースとして扱わず、その HTTP エラーを提示します。

get_project_info のステータスフィールド

project_info.project_state は、プロジェクトにおける AMC キャリブレーションのライフサイクルを示します。RUNNING → COMPLETED（または ERROR）です。

project_info.vggt_state もプロジェクトごとの値であり、グローバルサービスやモデル読み込みのステータスを直接示すものではなく、プロジェクト単位の VGGT リファインメントのライフサイクルを示します。新しく作成したプロジェクトでは、VGGT モデルが存在してマウントされていても、vggt_state: "INIT" が報告されることがあります。想定される VGGT のライフサイクルは、AMC キャリブレーション完了後に INIT → READY、VGGT リファインメント実行中に RUNNING、その後 COMPLETED（または ERROR）です。

ステップ 10 の任意の VGGT リファインメントを実行するかどうかの判定に限り、vggt_state == "READY" をゲートとして使用します。新規または未キャリブレーションのプロジェクトで INIT となるのは正常なプロジェクト状態です。AMC キャリブレーションが完了してもプロジェクトが準備完了以外の VGGT 状態のままの場合は、セットアップスキルの確認とサービスログを使って、VGGT の設定とモデルの利用可能性を確認してください。

ステップ 10 — （任意）VGGT による調整

AMC のキャリブレーションが完了したら、GET /v1/get_project_info/<project_id> から vggt_state を読み取ります。

• プロジェクトの状態が vggt_state == "READY" の場合は、ホストの質問機能を使って VGGT による調整を実行するかユーザーに尋ねます。質問機能がない場合は、チャットで尋ねて返答を待ちます。
• ユーザーが実行を確認したら、POST /v1/vggt/calibrate/<project_id> を実行し、get_project_info で vggt_state をポーリングしてから、GET /v1/vggt_results/<project_id>/evaluation_statistics を実行します。
• VGGT の準備ができていない場合は、調整をスキップし、amc-setup-calibration-stack で VGGT をセットアップすれば、後でこの任意のステップを再実行できることを説明します。

スタンドアロンの Python スクリプトは、stdin が対話モードの場合にのみプロンプトを表示します。非対話実行では、オプトインするには RUN_VGGT = True を設定してください。設定しない場合、スクリプトは VGGT の準備ができていることを表示し、待機せずに続行します。

---

Python スクリプト全体

auto-magic-calib リポジトリのルートではなく、amc-run-video-calibration スキルパッケージに同梱されているスクリプトを使用してください。インストールせず、このスキルフォルダーをエージェントに直接指定する場合は、AMC_VIDEO_SKILL_DIR にこの SKILL.md があるディレクトリを設定するか、そのディレクトリからコマンドを実行してください。BASE_URL、PROJECT_NAME、VIDEO_DIR を設定します。任意の環境変数は、CONFIG_FILE、ALIGNMENT_JSON、LAYOUT_PNG、GT_ZIP、FOCAL_LENGTHS、DETECTOR_TYPE、RUN_VGGT、REPO_ROOT、PROJECTS_DIR、CONFIRM_CALIBRATION、CALIBRATION_TIMEOUT_SECONDS、VGGT_TIMEOUT_SECONDS、ALLOW_INSECURE_HTTP です。このスクリプトは、AMC の準備状況チェック、UI フォールバック、明示的な確認による実行制御、上限付きのポーリング、調整後の統計情報の取得を実装しています。

# Optional but recommended: REPO_ROOT points to the auto-magic-calib checkout.
# PROJECTS_DIR can be set explicitly when project outputs live elsewhere.
if [ -z "${DEEPSTREAM_REPO_ROOT:-}" ] && [ -n "${REPO_ROOT:-}" ] && [ -d "$REPO_ROOT/../../skills/amc-run-video-calibration" ]; then
  DEEPSTREAM_REPO_ROOT="$(cd "$REPO_ROOT/../.." && pwd)"
fi

SCRIPT_PATH=""
for candidate in \
  "${AMC_VIDEO_SKILL_DIR:+$AMC_VIDEO_SKILL_DIR/scripts/run_video_calibration.py}" \
  "$PWD/scripts/run_video_calibration.py" \
  "${DEEPSTREAM_REPO_ROOT:+$DEEPSTREAM_REPO_ROOT/skills/amc-run-video-calibration/scripts/run_video_calibration.py}" \
  "$PWD/skills/amc-run-video-calibration/scripts/run_video_calibration.py" \
  "$HOME/.claude/skills/amc-run-video-calibration/scripts/run_video_calibration.py" \
  "$HOME/.codex/skills/amc-run-video-calibration/scripts/run_video_calibration.py" \
  "$HOME/.cursor/skills/amc-run-video-calibration/scripts/run_video_calibration.py"; do
  if [ -f "$candidate" ]; then
    SCRIPT_PATH="$candidate"
    break
  fi
done

[ -n "$SCRIPT_PATH" ] || {
  echo "ERROR: could not find amc-run-video-calibration/scripts/run_video_calibration.py" >&2
  echo "Set AMC_VIDEO_SKILL_DIR to the amc-run-video-calibration skill directory, or run this block from that directory." >&2
  exit 1
}

python3 "$SCRIPT_PATH"

使用例

ローカルの設定、アライメント、レイアウトを自動検出する対話モードでの実行：

BASE_URL="http://localhost:8000/v1" \
PROJECT_NAME="warehouse-calibration" \
VIDEO_DIR="/data/warehouse_session" \
python3 "$SCRIPT_PATH"

必要なローカルファイルをすべて事前に指定する非対話モードでの実行：

BASE_URL="http://localhost:8000/v1" \
PROJECT_NAME="warehouse-batch" \
VIDEO_DIR="/data/warehouse_session" \
CONFIG_FILE="/data/warehouse_session/settings.json" \
ALIGNMENT_JSON="/data/warehouse_session/alignment_data.json" \
LAYOUT_PNG="/data/warehouse_session/layout.png" \
CONFIRM_CALIBRATION=true \
RUN_VGGT=true \
python3 "$SCRIPT_PATH"

成功条件

• ポーリング後に project_state == "COMPLETED" であること。
• キャリブレーション前に verify_project が READY を返すこと（手動アライメント／UI フォールバックの経路も含みます）。
• GT をアップロードした場合、評価結果が一般的な閾値を満たすこと：
  • Average L2 distance(m) < 1.5
  • Average reprojection error 0(px) < 5
• ERROR 状態にならないこと。

主要な出力ファイル（サーバー上）

projects/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
└── calibration.log

制限事項

• このスキルは、ローカルに保存済みの cam_*.mp4 データセットにのみ適用されます。ライブ RTSP ストリームと同梱のサンプルデータセットは対象外です。
• 無人実行では UI フォールバックを利用できません。必要なローカルファイルを事前に指定し、CONFIRM_CALIBRATION=true を設定してください。
• サーバー側で報告される出力パスは、AMC がデフォルトの projects/ ディレクトリ以外にプロジェクト出力を書き込む場合、ホストの PROJECTS_DIR が正しく設定されているかどうかに依存します。

トラブルシューティング

問題	対処方法
verify_project の状態が READY ではない	動画がアップロードされており、アライメントとレイアウトが揃っていることを確認します（API または UI での手動アライメントを使用）。
UI の手順後も手動アライメントが受け付けられない	ユーザーが「Save」をクリックしていないか、UI のデータが不完全な可能性があります。verify_project を再実行し、UI のステップ 4 を繰り返してください。
キャリブレーションが 90 分を超えて RUNNING のまま	GET /v1/amc/calibrate/<id>/log を実行します。通常はトラックレット不足が原因です（シーンの動きが少なすぎます）。ルート README の「カスタムデータセット」のガイドラインを参照してください。
直ちに ERROR 状態になる	動画の命名を確認してください。cam_00.mp4、cam_01.mp4、…のように、連番である必要があります。
L2 は低いが、再投影誤差が高い	ステップ 3 で focal_length の上書き値を明示的に指定してください。
AMC 完了後も VGGT が準備完了にならない	新しいプロジェクトでは INIT が想定される状態です。AMC のキャリブレーションが COMPLETED になると、VGGT が設定済みの場合、任意の VGGT 調整の前にプロジェクトは READY に移行するはずです。調整が必要なのに状態が INIT のまま、またはそれ以外の準備未完了状態の場合は、セットアップスキルのステップ 2 と MS のログを確認し、VGGT のセットアップとモデルの利用可能性を確認してください。
アップロードのタイムアウト	動画のサイズが大きい場合は、スクリプト内の timeout=300 を 600 などに増やしてください。

下流スキル向け — MV3DT エクスポート

下流のマルチビュー 3D トラッキングスキルは、マイクロサービスから MV3DT 形式のキャリブレーションを直接取得します（このスキルはダウンロードせず、project_id を返します）。このスキルが COMPLETED を報告した後：

• GET /v1/result/{project_id}/mv3dt_result?result_type=amc → mv3dt_output.zip（transforms.yml を含みます）。
• VGGT が COMPLETED まで実行された場合（ステップ 10）：?result_type=vggt → vggt_mv3dt_output.zip。

関連スキル

• skills/amc-setup-calibration-stack/SKILL.md — まず MS と UI を起動します。
• skills/amc-run-sample-calibration/SKILL.md — 独自のデータを試す前に、同梱のサンプルでスタックを検証します。
• skills/amc-run-rtsp-calibration/SKILL.md — 同じキャリブレーションの後続処理を行いますが、VIOS 経由のライブ RTSP ストリームから映像を取得します。

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