amc-run-sample-calibration

スキル：サンプルデータセットのキャリブレーション

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

ユーザーが、同梱のサンプルデータセットを使って実行中の AMC スタックを簡易チェックしたい場合に、このスキルを使用します。典型的なプロンプト：

• 「サンプルデータセットをテストして」／「サンプルキャリブレーションを実行して」
• 「AMC のインストールを確認して」
• 「起動してテストして」（MS がまだ起動していない場合は、amc-setup-calibration-stack と組み合わせます）

次の場合は、このスキルを使用しないでください：

• ユーザーが独自の動画パス（例：/data/videos/、同梱 zip 由来ではない cam_*.mp4）を指定している場合 — amc-run-video-calibration に振り分けてください。
• ユーザーがライブ RTSP ストリームまたは rtsp://... URL を指定している場合 — amc-run-rtsp-calibration に振り分けてください。
• このスキルは assets/sdg_08_2_sample_data_010926.zip 専用です。

前提条件：AMC マイクロサービスが 8000～8009 のいずれかのポートで実行中であること。バックエンドが検出されない場合は、まず amc-setup-calibration-stack に委任してください。

現在の環境で実行できない場合（バックエンドがない、サンプルデータがないなど）は、障害となっている要因を示し、前提条件が満たされたときに実行される想定のワークフローと API の順序を簡潔に説明してください。キャリブレーションの出力、評価指標、軌跡を捏造しないでください。

概要

同梱のサンプルデータセット（sdg_08_2_sample_data_010926.zip、正解データ付きの合成倉庫カメラ 4 台）を、実行中の AutoMagicCalib マイクロサービスで一括キャリブレーションします。実データを使う前に、新しく起動したスタックがエンドツーエンドで動作することを確認するのに便利です。

サンプルには GT が含まれているため、この実行では評価指標（L2 距離、再投影誤差）が出力されます — キャリブレーションパラメーターの調整は不要です。

前提条件

• AMC マイクロサービスが実行中であること（未実行の場合は skills/amc-setup-calibration-stack/SKILL.md に従ってください）
• サンプル zip が assets/sdg_08_2_sample_data_010926.zip にあること
• requests がインストールされた Python 3 を使用できること、または以下の Swagger UI の手順を使用すること
  • スクリプトを実行する前に、明示的にインストールしてください：python3 -m pip install requests
  • pip を使用できない場合は、先にお使いのディストリビューションの Python パッケージングサポートをインストールしてください

手順

「AMC を起動してサンプルデータセットをテストして」（または同様の指示）：

1. まず skills/amc-setup-calibration-stack/SKILL.md を実行します。
2. /v1/ready が OK を返すまで待ちます。
3. サンプルデータを展開します（以下のスニペットを参照）— 冪等で、再実行しても安全です。
4. スクリプトを実行 の同梱スクリプトを実行します。
5. 最終的な指標と、手動確認用の UI URL を報告します。
6. プロジェクトから vggt_state: READY が報告された場合は、デフォルトで VGGT によるリファインメントを試みます。それ以外の場合、スクリプトは VGGT のセットアップは任意であり、後からリファインメント用に有効化できることを説明します。

「サンプルデータセットをテストして」（MS はすでに実行中）：

1. バックエンドを検出します：8000～8009 のポートをスキャンし、/v1/ready の応答を確認します。
2. 見つからない場合 → セットアップスキルを案内します。
3. まだキャッシュされていない場合は、サンプルデータを展開します。
4. 同梱スクリプトを実行します。
5. 指標を報告します。

実行中のバックエンドを検出する

MS_PORT=""
for port in {8000..8009}; do
  if curl -s "http://localhost:$port/v1/ready" | grep -q '"code":0'; then
    MS_PORT=$port; break
  fi
done
[ -z "$MS_PORT" ] && { echo "No running backend. Run amc-setup-calibration-stack skill first."; exit 1; }
echo "Backend on port $MS_PORT"

サンプルデータを見つけて展開する（冪等）

: "${REPO_ROOT:?set REPO_ROOT to the auto-magic-calib checkout. Run amc-setup-calibration-stack Step 0b first.}"
grep -q "AutoMagicCalib" "$REPO_ROOT/README.md" 2>/dev/null && grep -q "auto-magic-calib-ms" "$REPO_ROOT/compose/ms/compose.yml" 2>/dev/null || { echo "ERROR: REPO_ROOT is not an auto-magic-calib checkout: $REPO_ROOT" >&2; exit 1; }

SAMPLE_ZIP="$REPO_ROOT/assets/sdg_08_2_sample_data_010926.zip"
[ -f "$SAMPLE_ZIP" ] || { echo "Sample zip not found at $SAMPLE_ZIP"; exit 1; }

# Cache directory next to the zip.
SAMPLE_DIR="$(dirname "$SAMPLE_ZIP")/.cache/sdg_08_2_sample_data_010926"

if [ ! -d "$SAMPLE_DIR" ]; then
  mkdir -p "$SAMPLE_DIR"
  unzip -q "$SAMPLE_ZIP" -d "$SAMPLE_DIR"
fi
ls "$SAMPLE_DIR"
# Expected (possibly inside a wrapper folder): alignment_data/  GT.zip  videos/

スクリプトを実行する

auto-magic-calib リポジトリのルートではなく、amc-run-sample-calibration スキルパッケージに同梱されているスクリプトを実行してください。インストールせずにユーザーがこのスキルフォルダーを直接エージェントに指定した場合は、AMC_SAMPLE_SKILL_DIR をこの SKILL.md が含まれるディレクトリに設定するか、そのディレクトリからコマンドを実行してください。REPO_ROOT には amc-setup-calibration-stack で解決した AutoMagicCalib のチェックアウト先を設定してください。このスクリプトは、BASE_URL／MS_PORT が設定されていない場合、localhost のポート 8000～8009 で実行中のバックエンドを自動検出します。また、BASE_URL、MS_PORT、SAMPLE_DIR、RUN_VGGT による上書きに対応し、実行ごとに新しいプロジェクトを作成し、準備ができていれば VGGT を試み、最後に NGC 倉庫データセットに関する注記を出力します。

# REPO_ROOT must point to the auto-magic-calib checkout, not the DeepStream repo.
: "${REPO_ROOT:?set REPO_ROOT to the auto-magic-calib checkout. Run amc-setup-calibration-stack Step 0b first.}"
grep -q "AutoMagicCalib" "$REPO_ROOT/README.md" 2>/dev/null && grep -q "auto-magic-calib-ms" "$REPO_ROOT/compose/ms/compose.yml" 2>/dev/null || { echo "ERROR: REPO_ROOT is not an auto-magic-calib checkout: $REPO_ROOT" >&2; exit 1; }

# If AMC was resolved from DeepStream's tools/auto-magic-calib submodule,
# derive the DeepStream root so the unpacked repo skill can be used directly.
if [ -z "${DEEPSTREAM_REPO_ROOT:-}" ] && [ -d "$REPO_ROOT/../../skills/amc-run-sample-calibration" ]; then
  DEEPSTREAM_REPO_ROOT="$(cd "$REPO_ROOT/../.." && pwd)"
fi

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

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

python3 "$SCRIPT_PATH"

別の方法：Swagger UI を使った手順

エージェント向けショートカット：ユーザーが Swagger UI を使った手順を明示的に求めた場合（または「Python は使わない」と述べた場合）は、以下の表を出力して終了してください。シェルツールの実行、他のセクションの参照、同梱の Python スクリプトの実行は行わないでください。

マイクロサービスは http://<HOST_IP>:<MS_PORT>/docs でインタラクティブな OpenAPI UI を公開しています。API を手動で操作する場合：

1. ブラウザーで http://<HOST_IP>:<MS_PORT>/docs を開きます。

2. sdg_08_2_sample_data_010926.zip を解凍し、同階層のキャッシュディレクトリに置きます。

3. 以下のエンドポイントを順番に実行します。ステップ 1 の project_id を以降のパスにコピーしてください。

   #	エンドポイント	ボディ／ファイル
   1	POST /v1/create_project	project_name：任意の文字列
   2	POST /v1/upload_video_files/{project_id}	files：videos/cam_0*.mp4 の 4 ファイルすべてを名前順にアップロード
   3	POST /v1/upload_alignment/{project_id}	alignment_file：alignment_data/alignment_data.json
   4	POST /v1/upload_layout/{project_id}	layout_file：alignment_data/layout.png
   5	POST /v1/upload_gt_file/{project_id}	gt_file：GT.zip
   6	POST /v1/verify_project/{project_id}	—（project_state: READY を確認）
   7	POST /v1/calibrate/{project_id}	JSON：{"detector_type": "resnet"}
   8	GET /v1/get_project_info/{project_id}	project_state が COMPLETED になるまで約 10 秒ごとに再取得
   9	GET /v1/result/{project_id}/evaluation_statistics	L2 距離と再投影誤差を確認
   10（任意）	POST /v1/vggt/calibrate/{project_id} の後に GET /v1/vggt_results/{project_id}/evaluation_statistics	vggt_state が READY の場合のみ実行し、COMPLETED になるまで vggt_state を確認

これは同梱の Python スクリプトと同じ一連の手順を手動で実行するものです。デフォルトではステップ 10 は vggt_state が READY の場合に実行されます。それ以外の場合は、セットアップ手順を案内してスキップされます。

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

project_info.project_state は、プロジェクトの AMC キャリブレーションのライフサイクルを示します。COMPLETED になるまで確認してください（ERROR になった場合は中止してください）。

project_info.vggt_state はプロジェクト単位の VGGT リファインメントのライフサイクルを示すものであり、グローバルなサービスやモデル読み込みの状態を直接示すものではありません。VGGT モデルが存在し、マウントされていても、新規作成したプロジェクトでは vggt_state: "INIT" と表示されることがあります。想定されるライフサイクルは、AMC キャリブレーションの完了後に INIT → READY、VGGT リファインメントの実行中に RUNNING → COMPLETED（または ERROR）です。新規プロジェクトや未キャリブレーションのプロジェクトでの INIT は正常なプロジェクト状態です。AMC キャリブレーションが完了してもプロジェクトが VGGT の非 READY 状態のままであれば、セットアップスキルの確認項目とサービスログを使って VGGT のセットアップとモデルの利用可能性を確認してください。

成功条件

• プロジェクトの project_state == "COMPLETED" が約 30 分以内に達成されること。
• /v1/result/{id}/evaluation_statistics が空ではない statistics を返すこと（GT がアップロード済みであること）。
• VGGT が実行されて vggt_state == "COMPLETED" となり、/v1/vggt_results/{id}/evaluation_statistics の結果が報告されること。または、プロジェクトが VGGT に対して READY ではないため、セットアップ手順の案内とともにスキップされること。
• ERROR 状態にならないこと。

サンプルの代表的な指標（実行結果も同程度になるはずです）：

Average L2 distance(m)               : < 1.5
Average reprojection error 0(px)     : < 10

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

結果は $REPO_ROOT/projects/project_<project_id>/ に保存されます：

projects/project_<project_id>/
├── output/
│   ├── single_view_results/cam_XX/
│   │   ├── camInfo_hyper_XX.yaml
│   │   └── trajDump_Stream_0_3d.txt
│   └── multi_view_results/BA_output/results_ba/refined/
│       └── camInfo_XX.yaml          # ← final calibration (use this)
└── calibration.log

進行状況の監視

PROJECT_ID=<id_from_step_1>
: "${REPO_ROOT:?set REPO_ROOT to the auto-magic-calib checkout. Run amc-setup-calibration-stack Step 0b first.}"
grep -q "AutoMagicCalib" "$REPO_ROOT/README.md" 2>/dev/null && grep -q "auto-magic-calib-ms" "$REPO_ROOT/compose/ms/compose.yml" 2>/dev/null || { echo "ERROR: REPO_ROOT is not an auto-magic-calib checkout: $REPO_ROOT" >&2; exit 1; }
tail -F --retry "$REPO_ROOT/projects/project_${PROJECT_ID}/calibration.log"

または、MS のログをストリーミングします：

: "${REPO_ROOT:?set REPO_ROOT to the auto-magic-calib checkout. Run amc-setup-calibration-stack Step 0b first.}"
grep -q "AutoMagicCalib" "$REPO_ROOT/README.md" 2>/dev/null && grep -q "auto-magic-calib-ms" "$REPO_ROOT/compose/ms/compose.yml" 2>/dev/null || { echo "ERROR: REPO_ROOT is not an auto-magic-calib checkout: $REPO_ROOT" >&2; exit 1; }
docker compose -f "$REPO_ROOT/compose/compose.yml" logs -f auto-magic-calib-ms

トラブルシューティング

問題	対処方法
requests がインストールされていない	スクリプトを実行する前にインストールしてください：python3 -m pip install requests
[2] Uploaded N videos で N >> 4	SAMPLE_DIR がリポジトリのルート（または対象範囲が広すぎる別のパス）を指しており、rglob("cam_*.mp4") が .cache/、projects/ などにある古い動画まで収集しています。SAMPLE_DIR を修正し、不正なアップロード一式を修復しようとするのではなく、新しいプロジェクトを開始してください。スクリプトは videos/ を基準にしており、len(videos) <= 16 をアサートして、問題があれば明確に失敗します
verify_project が状態 != READY を返す	動画 4 本、アラインメント、レイアウト、GT がすべてアップロードされていることを確認し、GET /v1/get_project_info/{id} のレスポンスを調べてください
サンプルが展開されない	unzip <repo_root>/assets/sdg_08_2_sample_data_010926.zip -d <repo_root>/assets/.cache/sdg_08_2_sample_data_010926/
cam_*.mp4 の glob でファイルが 0 件見つかる	ラッパーフォルダーの階層を確認してください：find <sample_dir> -name "cam_*.mp4"
キャリブレーションがタイムアウトする（60 分超）	calibration.log で「insufficient tracklets」を確認してください。入力動画に関するガイドラインは、ルートの README.md を参照してください
アップロードが 413 を返す	サーバーのアップロード上限を引き上げるか、ファイルを分割してください（サンプルファイルの合計は 200 MB 未満なので、これは通常ありません）
ポートスキャンでバックエンドが見つからない	バックエンドが実行されていません — amc-setup-calibration-stack スキルを実行してください

追加のサンプルデータセット

ルートの README.md には、NGC から入手できる実際の倉庫データセット nv_warehouse_032326.zip についても記載されています。ngc registry resource download-version "nvidia/amc-nv-warehouse" でダウンロードし、amc-run-video-calibration を使用して、設定ステップで nv_warehouse_config.json をアップロードし、transformer 検出器を指定して実行してください。グラウンドトゥルースデータは含まれていません。

関連スキル

• skills/amc-setup-calibration-stack/SKILL.md — MS + UI を起動します（前提条件）。
• skills/amc-run-video-calibration/SKILL.md — 事前に録画した MP4 を使ってキャリブレーションを実行します。
• skills/amc-run-rtsp-calibration/SKILL.md — VIOS キャプチャを介して、ライブ RTSP ストリームからキャリブレーションを実行します。

ルートの README.md の「Sample Data Setup」と「Calibration Workflow (UI)」のセクションでは、同じサンプルを使った、人向けの手順を説明しています。