amc-run-rtsp-calibration

スキル：RTSP ストリームからキャリブレーションする

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

ユーザーがライブ RTSP カメラストリームからのキャリブレーションを希望する場合に、このスキルを有効にします。一般的なリクエストの例：

• 「RTSP ストリームをキャリブレーションする」／「ライブカメラからキャリブレーションする」
• 「RTSP で AMC を実行する」
• ユーザーが 1 つ以上の rtsp://... URL を提示する

VIOS は各ストリームから固定時間のクリップを録画し、AMC マイクロサービスがそのクリップをプロジェクトに取り込みます。その後のワークフローは、録画済み MP4 を使ったキャリブレーションと同じ検証、キャリブレーション、ポーリング、結果確認の手順に従います。

すでにディスク上にあるローカル MP4 ファイルにはこのスキルを使用しないでください。その場合は skills/amc-run-video-calibration/SKILL.md を案内してください。バンドルされているサンプルデータセットにも使用しないでください。その場合は skills/amc-run-sample-calibration/SKILL.md を案内してください。

ユーザーがこの RTSP シーン用のパスを明示的に提示しない限り、バンドルされたサンプルデータセット、展開済みサンプル zip、assets/、または以前のプロジェクトのファイルを RTSP キャリブレーションに再利用しないでください。カメラ名、ストリーム数、cam_00／cam_01 の順序が似ているだけでは、サンプルの対応付け、レイアウト、GT、検出器設定を適用できる根拠にはなりません。

前提条件

• AMC マイクロサービスと UI が稼働していること（必要に応じて skills/amc-setup-calibration-stack/SKILL.md に従ってください）。
• VIOS が稼働しており、AMC マイクロサービスからアクセスできること。
• 録画を開始する前に、AMC マイクロサービスの環境で VIOS_BASE_URL が設定されていること。
• RTSP URL に VIOS ホストからアクセスできること。
• カメラストリームにキャリブレーションに十分な数の動く人や物体が映っていること。可能な場合は 2～3 分以上録画してください。
• バンドルされたスクリプトを使用する場合は、Python 3 と requests がインストールされていること。

データのプライバシー

RTSP URL には、ユーザー名、パスワード、ホスト名、ネットワーク構成が含まれている場合があります。認証情報が埋め込まれている場合は、RTSP URL 全体を表示しないでください。このスキルはベアラー認証情報を扱いません。VIOS のデプロイで認証が必要な場合は、チャット、スクリプト、ログでシークレットを収集または伝達せず、作業を中止して、管理者が管理する手動ワークフローをユーザーに案内してください。

ユーザーへの確認事項

必須

1. カメラごとの RTSP URL。
2. ストリームごとのカメラ名。ユーザーが指定しない場合は cam_00、cam_01、... を使用してください。
3. 録画時間（秒）。最短は 60 です。シーン内の動きが少ない場合は、120～180 秒以上を推奨します。
4. マイクロサービスの URL。例：http://<HOST_IP>:8000 または http://<HOST_IP>:8000/v1。
5. プロジェクト名。
6. この RTSP シーンのキャリブレーションアセットの提供元：
   • スキャンするローカルディレクトリ（例：/data/my_rtsp_calib/）；
   • 設定、alignment、layout、および任意の GT ファイルの明示的なパス；または
   • ユーザーが AMC UI で設定と alignment をアップロード／調整することの確認。

ユーザーがローカルアセットの提供元を指定しない場合は、処理を中止し、パスを指定するか UI からアップロードするかを確認してください。UI のリンクは http://<HOST_IP>:<AUTO_MAGIC_CALIB_UI_PORT> としてください。UI の既定のポートは 5000 です。

自動検出または確認

RTSP クリップは VIOS によって録画されるため、ファイル検索の起点となるローカルの動画ディレクトリはありません。この RTSP シーン用にユーザーが明示的に指定したディレクトリだけをスキャンしてください。ユーザーが設定ファイルのパスを指定した場合は、そのファイルがあるディレクトリをスキャン対象にします。ユーザーがキャリブレーションアセットのディレクトリを指定した場合は、そのディレクトリだけをスキャンしてください。それ以外の場合、アップロードやキャリブレーションの計画を立てる前に、次の質問をしてください。

これらの RTSP ストリーム用のローカルキャリブレーションアセットディレクトリまたは設定ファイルはありますか？ それとも、AMC UI（http://<HOST_IP>:<AUTO_MAGIC_CALIB_UI_PORT>）で設定とアラインメントをアップロード／調整しますか？

ファイル	候補ファイル名	UI での代替手順
キャリブレーション設定	ユーザーが明示したパス、またはユーザー指定のアセットディレクトリ内の settings.json、config.json、calibration_config.json	UI Step 3: Parameters
アラインメント JSON	ユーザーが明示したパス、またはユーザー指定のアセットディレクトリ／設定ディレクトリ内の alignment_data.json	UI Step 4: Alignment
レイアウト PNG	ユーザーが明示したパス、またはユーザー指定のアセットディレクトリ／設定ディレクトリ内の layout.png	UI Step 4: Alignment
グラウンドトゥルース zip	任意の明示されたユーザーパス、またはユーザー指定のアセットディレクトリ内の GT.zip／gt.zip	メトリクスを省略

設定ファイルを送信すると UI Step 3 は置き換えられ、detector または detector_type が固定される場合があります。resnet または transformer が固定されている場合は、同じ検出器を /calibrate に渡してください。設定ファイルで検出器が固定されていない場合は、どの検出器を使用するかユーザーに確認してください。暗黙に resnet をデフォルトとして使用しないでください。

任意

6. カメラがすでに VIOS に登録されている場合は、ストリームごとの sensor_id。自動登録する場合は未設定のままにします。
7. 評価メトリクス用のグラウンドトゥルース zip（GT.zip）。
8. カメラごとの焦点距離。
9. AMC の完了後に VGGT リファインメントを実行するかどうか。プロジェクトの vggt_state == "READY" が報告された場合に限ります。

手順

同梱のスクリプト scripts/run_rtsp_calibration.py は、この一連の処理をエンドツーエンドで実行します。判断、UI での代替手順、トラブルシューティングには、以下の説明を使用してください。

Step 0 - AMC と VIOS の確認

AMC マイクロサービスに接続できることを確認します。

curl -sf http://<HOST_IP>:<MS_PORT>/v1/ready

キャプチャを開始する前に、VIOS に接続できることを確認します。次の順に確認し、最初に動作する URL が見つかった時点で終了します。

: "${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; }
VIOS_BASE_URL=""

# Default local VIOS port.
if curl -sf http://localhost:30888/vst/api/v1/sensor/list >/dev/null 2>&1; then
  VIOS_BASE_URL="http://localhost:30888"
  echo "VIOS detected at $VIOS_BASE_URL"
fi

# Running AMC microservice container environment.
if [ -z "$VIOS_BASE_URL" ]; then
  VIOS_BASE_URL=$(docker exec auto-magic-calib-ms-1 printenv VIOS_BASE_URL 2>/dev/null)
fi

if [ -n "$VIOS_BASE_URL" ]; then
  curl -sf "${VIOS_BASE_URL}/vst/api/v1/sensor/list" >/dev/null \
    && echo "VIOS up at $VIOS_BASE_URL" \
    || { echo "VIOS_BASE_URL=$VIOS_BASE_URL is set but not responding"; VIOS_BASE_URL=""; }
fi

[ -n "$VIOS_BASE_URL" ] || {
  echo "VIOS is not reachable. Export VIOS_BASE_URL=http://<VIOS_HOST>:30888 and relaunch the AMC microservice." >&2
  exit 1
}

VIOS に接続できない場合は、VIOS をデプロイしてベース URL を提供するようユーザーに依頼してください。${VIOS_BASE_URL}/vst/api/v1/sensor/list が 200 を返すまでは、RTSP キャプチャを開始しないでください。

VIOS に接続できても、AMC マイクロサービスに VIOS_BASE_URL が設定されていない場合は、チェックイン済みの compose ファイルを編集しないでください。この変数をエクスポートし、一時的な compose オーバーライドを使ってマイクロサービスを再起動します。

cd "$REPO_ROOT/compose"
export VIOS_BASE_URL="http://<VIOS_HOST>:30888"
OVERRIDE_FILE="${TMPDIR:-/tmp}/amc-vios.override.yml"
cat > "$OVERRIDE_FILE" <<'YAML'
services:
  auto-magic-calib-ms:
    environment:
      - VIOS_BASE_URL=${VIOS_BASE_URL}
YAML

docker compose -f compose.yml -f "$OVERRIDE_FILE" up -d auto-magic-calib-ms
docker exec auto-magic-calib-ms-1 printenv VIOS_BASE_URL

コンテナがすでに実行されている場合、ホストシェルで変数をエクスポートするだけでは不十分です。AMC マイクロサービスのプロセスを、環境に VIOS_BASE_URL を設定した状態で再起動する必要があります。

Step 1 - プロジェクトの作成

フォームフィールド project_name を指定して POST /v1/create_project を実行します。返された project_id を保存します。

Step 2 - RTSP キャプチャの開始

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

{
  "streams": [
    {"rtsp_url": "rtsp://...", "camera_name": "cam_00", "sensor_id": null},
    {"rtsp_url": "rtsp://...", "camera_name": "cam_01", "sensor_id": null}
  ],
  "duration_seconds": 180,
  "ssl_verify": true
}

レスポンスでは、セッションフィールドが session の下にネストされる場合があります。

{"code": 0, "message": "...", "session": {"session_id": "...", "status": "STARTING"}}

session.session_id を保存します。

Step 3 - キャプチャのポーリング後に取り込み

10 秒ごとにポーリングします。

GET /v1/rtsp/capture/<project_id>/<session_id>

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

STARTING -> RECORDING -> COMPLETED -> INGESTING -> INGESTED
                       -> ERROR
RECORDING -> CANCELLED

キャプチャが COMPLETED に達したら、録画されたクリップを AMC プロジェクトに取り込みます。

POST /v1/rtsp/capture/<project_id>/<session_id>/ingest

取り込みが成功すると、プロジェクトに動画ファイルが添付され、それ以降のワークフローは MP4 アップロードの場合と同じになります。

早めに停止する必要がある場合は、POST /v1/rtsp/capture/<project_id>/<session_id>/stop を実行します。VIOS がクリップを生成していれば、部分的なクリップでも取り込めます。

その他のセッションエンドポイント：

• GET /v1/rtsp/sessions/<project_id> - プロジェクトのセッション一覧を取得します。

ステップ 4 - 設定、アラインメント、レイアウト、任意ファイルのアップロード

上記のアンカーファイルパターンを使用してローカルファイルを解決します。解決したファイルをアップロードします。

ファイル	エンドポイント	備考
キャリブレーション設定	POST /v1/config/<project_id>	JSON 本文をそのまま投稿します。UI のステップ 3 の代わりになります
アラインメント JSON	POST /v1/upload_alignment/<project_id>	マルチパートの alignment_file
レイアウト PNG	POST /v1/upload_layout/<project_id>	マルチパートの layout_file
グラウンドトゥルース ZIP	POST /v1/upload_gt_file/<project_id>	任意
焦点距離	POST /v1/upload_focal_length/<project_id>	focal_length の値を複数指定できます（任意）

明示的にユーザーが指定したパス、またはユーザーが指定したキャリブレーションアセットディレクトリにあるファイルのみを使用してください。フォールバック用の設定、アラインメント、レイアウト、GT を探すためにサンプルデータを展開したり、スキャンしたりしないでください。

設定がない場合は、ユーザーを http://<HOST_IP>:<AUTO_MAGIC_CALIB_UI_PORT> の UI ステップ 3「Parameters」に案内し、キャリブレーションの前に使用する検出器（resnet または transformer）を尋ねてください。アラインメントまたはレイアウトがない場合は、このプロジェクトの UI ステップ 4「Alignment」に案内してください。RTSP プロジェクトでは、動画はすでに取り込まれています。UI を使ったフォールバックでは、動画を再アップロードしないでください。

UI ステップ 4 の後に続行する前に、次を確認してください。

PROJECT_ID=<project_id>
: "${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; }
HOST_PROJECTS="${PROJECTS_DIR:-$(cd "$REPO_ROOT" && realpath projects)}"
ls "$HOST_PROJECTS/project_${PROJECT_ID}/manual_adjustment/"
# Expected: alignment_data.json, layout.png

AMC スタックがプロジェクトの出力をデフォルトの projects/ ディレクトリ以外に保存する場合は、上記の確認を実行する前に PROJECTS_DIR を明示的に設定してください。このワークフローでは、プロジェクトのパスを確認するために compose/.env を読み取らないでください。

ステップ 5 - 検証、キャリブレーション、状態確認、結果の取得

次を検証します。

POST /v1/verify_project/<project_id>

プロジェクトは project_state == "READY" を返す必要があります。

キャリブレーションの前に、実行計画を確認してください。次の項目をまとめます。

• ストリーム数と録画時間。
• 検出器：resnet または transformer。
• 設定の取得元：明示的にアップロードした設定ファイル、ユーザー指定のアセットディレクトリ、または UI ステップ 3。
• アラインメント／レイアウトの取得元：明示的にアップロードしたファイル、ユーザー指定のアセットディレクトリ、または UI による手動調整。
• 任意の GT と焦点距離の上書き設定。

キャリブレーションを開始します。

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

{"detector_type": "<resnet-or-transformer>"}

状態を確認します。

GET /v1/get_project_info/<project_id>

COMPLETED または ERROR になったら停止します。エラーの場合は GET /v1/amc/calibrate/<project_id>/log を取得してください。

結果を取得します。

GET /v1/result/<project_id>/evaluation_statistics

GT をアップロードした場合にのみ、評価統計が返されることを想定してください。

ステップ 6 - VGGT による任意のリファインメント

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

• vggt_state == "READY" の場合は、VGGT によるリファインメントを実行するか尋ねてください。
• 確認できた場合は、POST /v1/vggt/calibrate/<project_id> を呼び出し、vggt_state を確認してから、GET /v1/vggt_results/<project_id>/evaluation_statistics を取得してください。
• VGGT の準備ができていない場合はスキップし、AMC キャリブレーションが完了していることを説明してください。

完全な Python スクリプト

auto-magic-calib リポジトリのルートではなく、amc-run-rtsp-calibration スキルパッケージに同梱されているスクリプトを使用してください。インストールせずにユーザーがこのスキルフォルダーを直接エージェントに指定する場合は、AMC_RTSP_SKILL_DIR にこの SKILL.md を含むディレクトリを設定するか、そのディレクトリからコマンドを実行してください。

一般的な環境変数：

export BASE_URL=http://<HOST_IP>:8000
export PROJECT_NAME=rtsp_calibration_run
export RTSP_URLS='rtsp://user:pass@cam0/stream,rtsp://user:pass@cam1/stream'
export CAMERA_NAMES='cam_00,cam_01'
export DURATION_SECONDS=180
export VIOS_BASE_URL=http://<VIOS_HOST>:30888
export CALIB_ASSET_DIR=/path/to/rtsp-calibration-assets
# Or provide explicit CONFIG_FILE, ALIGNMENT_JSON, LAYOUT_PNG, and optional GT_ZIP.
export DETECTOR_TYPE=transformer  # Required when settings do not set detector/detector_type.
export AMC_UI_URL=http://<HOST_IP>:5000
export RUN_VGGT=false

# 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-rtsp-calibration" ]; then
  DEEPSTREAM_REPO_ROOT="$(cd "$REPO_ROOT/../.." && pwd)"
fi

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

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

python3 "$SCRIPT_PATH"

ストリーム入力の代替方法：

export STREAMS_JSON='[
  {"rtsp_url":"rtsp://cam0/stream","camera_name":"cam_00","sensor_id":null},
  {"rtsp_url":"rtsp://cam1/stream","camera_name":"cam_01","sensor_id":null}
]'

任意の環境変数は CALIB_ASSET_DIR、CONFIG_FILE、ALIGNMENT_JSON、LAYOUT_PNG、GT_ZIP、FOCAL_LENGTHS、DETECTOR_TYPE、AMC_UI_URL、SSL_VERIFY、RUN_VGGT、REPO_ROOT、PROJECTS_DIR です。SSL_VERIFY のデフォルト値は true です。SSL_VERIFY=false を設定するのは、ループバックテストの場合に限ってください。VIOS のデプロイでベアラー認証が必要な場合は処理を停止し、このスキルを通じて認証情報を受け渡すのではなく、管理者が手動で管理するキャプチャフローを使用してください。

成功条件

• VIOS のヘルスプローブが 200 を返す。
• キャプチャセッションが COMPLETED に到達する。
• 取り込みが成功し、プロジェクト情報に想定される動画ファイルが表示される。
• verify_project が READY を返す。
• AMC キャリブレーションが project_state == "COMPLETED" に到達する。
• GT をアップロードした場合、評価統計が返される。
• エージェントが RTSP 認証情報、ベアラートークン、NGC キー、HuggingFace トークンを出力または永続化しない。

主要な出力ファイル

結果は AMC サーバー上の次の場所に保存されます。

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
`-- calibration.log

トラブルシューティング

問題	解決方法
VIOS の /vst/api/v1/sensor/list が「connection refused」を返す	VIOS が実行されていないか、このホストから到達できません。VIOS をデプロイするか、到達可能なベース URL を提供するようユーザーに依頼してください。
キャプチャエンドポイントが 503 または「VIOS not configured」を返す	VIOS_BASE_URL をエクスポートし、手順 0 の一時的な compose オーバーライドを使用してマイクロサービスを再起動してから、キャプチャを再試行してください。
セッションが STARTING のまま停止している	VIOS はリクエストを受け付けましたが、センサーがまだオンラインになっていない可能性があります。${VIOS_BASE_URL}/vst/api/v1/sensor/list を確認し、センサーの再起動後 20～30 秒待ってください。
duration_seconds を過ぎてもセッションが RECORDING のまま停止している	POST /v1/rtsp/capture/<project_id>/<session_id>/stop を呼び出してから、利用可能であれば部分的なクリップを取り込んでください。
取り込み時に「No clip available」エラーが発生する	録画時間帯が VIOS のタイムラインと重なっていない可能性があります。センサーがオンラインになるまで待ってから、新しいキャプチャを開始してください。
400「empty streams」	rtsp_url と camera_name を含むストリームオブジェクトを少なくとも 1 つ渡してください。
400「duration too short」	duration_seconds >= 60 を使用してください。
/v1/rtsp/capture/<project_id> で 404 が発生する	先に /v1/create_project でプロジェクトを作成してください。
取り込み後も verify_project が READY にならない	プロジェクト情報を確認し、想定される動画、アライメント、レイアウトが紐付けられていることを確認してください。
キャリブレーションが ERROR になる	GET /v1/amc/calibrate/<project_id>/log を取得してください。よくある原因は、トラックレットの不足、静的なシーン、またはアライメントの誤りです。

関連スキル

• skills/amc-setup-calibration-stack/SKILL.md - 先に AMC マイクロサービスと UI を起動します。
• skills/amc-run-video-calibration/SKILL.md - ローカルの録画済み MP4 ファイルからキャリブレーションします。
• skills/amc-run-sample-calibration/SKILL.md - 同梱のサンプルデータセットを使用してスタックを検証します。