amc-run-rtsp-calibration

技能：通过 RTSP 视频流进行校准

何时使用此技能

当用户想通过实时 RTSP 摄像头视频流进行校准时，启用此技能。常见提示包括：

• “校准 RTSP 视频流”／“通过实时摄像头进行校准”
• “在 RTSP 上运行 AMC”
• 用户提供一个或多个 rtsp://... URL

VIOS 会从每个视频流录制固定时长的片段，AMC 微服务会将这些片段导入项目，然后工作流会遵循与预录制 MP4 校准相同的验证、校准、轮询和结果流程。

对于已存储在磁盘上的本地 MP4 文件，不要使用此技能；应将相关请求转至 skills/amc-run-video-calibration/SKILL.md。对于捆绑的示例数据集，不要使用此技能；应将相关请求转至 skills/amc-run-sample-calibration/SKILL.md。

除非用户明确提供这些路径用于此 RTSP 场景，否则切勿在 RTSP 校准中重复使用捆绑的示例数据集、解压后的示例 zip、assets/ 或先前项目中的文件。摄像头名称相似、视频流数量相同，或按 cam_00／cam_01 排序，都不能证明示例中的对齐、布局、GT 或检测器设置适用于当前场景。

前置条件

• AMC 微服务和 UI 正在运行（如有需要，请按照 skills/amc-setup-calibration-stack/SKILL.md 操作）。
• VIOS 正在运行，且 AMC 微服务能够访问。
• 开始录制前，已在 AMC 微服务环境中配置 VIOS_BASE_URL。
• VIOS 主机能够访问 RTSP URL。
• 摄像头视频流中有足够多的移动人员／物体可供校准；条件允许时，至少录制 2-3 分钟。
• 使用捆绑脚本时，已安装 Python 3 和 requests。

数据隐私

RTSP URL 可能包含用户名、密码、主机名或网络拓扑信息。如果凭据嵌入其中，请勿打印完整 RTSP URL。此技能不处理 bearer 凭据；如果 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/；
   • settings、alignment、layout 和可选 GT 文件的明确路径；或
   • 确认用户会在 AMC UI 中上传／调整 settings 和 alignment。

如果用户未提供本地资源来源，请停止并询问他们是要提供路径，还是使用 UI 上传。提供 UI 链接 http://<HOST_IP>:<AUTO_MAGIC_CALIB_UI_PORT>；默认 UI 端口为 5000。

自动检测或询问

RTSP 片段由 VIOS 录制，因此本地没有可用于定位文件的 videos 目录。对于此 RTSP 场景，只扫描用户明确提供的目录。如果用户提供了设置文件路径，则将该文件所在目录用作扫描目录。如果用户提供了校准素材目录，则只扫描该目录。否则，在规划上传或校准前先询问：

您有这些 RTSP 流的本地校准素材目录或设置文件吗？还是应该在 AMC UI 的 http://<HOST_IP>:<AUTO_MAGIC_CALIB_UI_PORT> 中上传/调整设置和对齐？

文件	候选文件名	UI 备用选项
校准设置	用户明确提供的路径，或用户提供的素材目录中的 settings.json、config.json 或 calibration_config.json	UI 步骤 3：参数
对齐 JSON	用户明确提供的路径，或用户提供的素材目录/设置目录中的 alignment_data.json	UI 步骤 4：对齐
布局 PNG	用户明确提供的路径，或用户提供的素材目录/设置目录中的 layout.png	UI 步骤 4：对齐
Ground truth zip	可选的用户明确提供的路径，或用户提供的素材目录中的 GT.zip/gt.zip	不计算指标

提交设置文件会替代 UI 步骤 3，并可能固定 detector 或 detector_type。如果固定为 resnet 或 transformer，则将同一个检测器传给 /calibrate。如果设置文件未固定检测器，则询问用户要使用哪个检测器；不要默认使用 resnet。

可选

6. 如果摄像头已在 VIOS 中注册，则为每条流提供 sensor_id。留空以自动注册。
7. 用于评估指标的 Ground truth zip（GT.zip）。
8. 每个摄像头对应的焦距。
9. 是否在 AMC 完成后运行 VGGT 优化，仅当项目报告 vggt_state == "READY" 时执行。

说明

随附脚本 scripts/run_rtsp_calibration.py 端到端实现了此流程。决策、UI 备用选项和故障排除请参阅下文。

步骤 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

仅在主机 Shell 中导出变量，在容器已运行后是不够的；必须在环境中包含 VIOS_BASE_URL 的情况下重启微服务进程。

步骤 1 - 创建项目

使用表单字段 project_name 调用 POST /v1/create_project。保存返回的 project_id。

步骤 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。

步骤 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>	Multipart 字段 alignment_file
布局 PNG	POST /v1/upload_layout/<project_id>	Multipart 字段 layout_file
Ground truth 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：参数，然后在校准前询问要使用哪个检测器（resnet 或 transformer）。如果缺少对齐文件或布局文件，请引导用户前往此项目的 UI 步骤 4：对齐。对于 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 脚本

使用 amc-run-rtsp-calibration 技能包中的捆绑脚本，而不是 auto-magic-calib 仓库根目录中的脚本。如果用户直接将此技能文件夹指定给 Agent，而不是安装它，请将 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 部署要求使用 bearer 身份验证，请停止操作，改用管理员管理的手动采集流程，不要通过此技能传递凭据。

成功标准

• VIOS 健康探测返回 200。
• 采集会话达到 COMPLETED。
• 导入成功，且项目信息显示预期的视频文件。
• verify_project 返回 READY。
• AMC 校准达到 project_state == "COMPLETED"。
• 如果已上传 GT，则返回评估统计数据。
• Agent 不会打印或持久化任何 RTSP 凭据、bearer 令牌、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 的流对象。
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 - 使用捆绑的示例数据集验证技术栈。