amc-run-video-calibration

技能：使用视频文件进行标定

何时使用此技能

当用户已有预录制的 MP4 文件，并希望通过 AMC REST API 对其进行标定时，启用此技能。典型提示：

• “标定我的视频” / “对这些视频运行 AMC”
• “使用视频文件进行标定”

通过 REST API 使用用户提供的预录制 MP4 文件进行标定——无需 CLI 脚本或 Docker 绑定挂载，只需运行中的微服务和用户的视频文件。

请勿将此技能用于实时 RTSP 流或 rtsp://... URL；将此类请求转至 skills/amc-run-rtsp-calibration/SKILL.md。

目的

指导 Agent 为用户提供的多摄像机数据集创建项目、按排序上传 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
• Python 3 和 requests
• 如果 AMC 将项目输出存储在默认 projects/ 目录之外，则知道主机上的 PROJECTS_DIR

交互方式

• “主机的提问机制”指运行时内置的简短用户决策提示 API，例如终端 stdin、IDE 提问工具或同等的交互式对话框。
• 如果该机制不可用，则在聊天中提问，并在执行任何需要用户确认或需要决定缺失文件的受控步骤前等待回复。
• 对于无人值守运行，捆绑脚本要求预先提供所有非 UI 输入，并且在设置 CONFIRM_CALIBRATION=true 之前会在 /calibrate 之前退出。RUN_VGGT=true 是启用可选 VGGT 步骤的单独选项。

数据隐私

通过此技能上传的视频文件会传输到 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。
• 非回环主机应使用 HTTPS 作为 BASE_URL。仅在可信的开发环境有意使用远程纯 HTTP 时，才设置 ALLOW_INSECURE_HTTP=true。
• 设置、对齐和布局的解析优先级：显式路径、唯一的本地自动检测匹配项，然后是 UI 回退。

需要向用户询问的内容

必需项

（视频文件命名和微服务 URL 已在上面的前置条件中说明——请收集以下输入。）

1. 视频目录——技能用于匹配 cam_*.mp4 的文件夹；上传时按字母顺序排序。
2. 微服务 URL
3. 项目名称——简短的描述性字符串

自动检测（仅在未找到时询问）

脚本会搜索视频目录、其第一层子目录以及其父目录。如果恰好找到一个匹配项，则使用该项；否则脚本会打印搜索过的位置，并继续尝试显式路径或回退到 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. 真实值压缩包 — GT.zip，包含 _World_Cameras_Camera_XX/ 文件夹（用于启用评估指标）
5. 焦距 — 每个摄像头一个，例如：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。

说明

以下所有端点均已在完整 Python 脚本中端到端实现——文字说明介绍工作流以及 Agent 必须做出的决定；脚本则是权威的可运行实现。

步骤 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. 在 VIDEO_DIR、VIDEO_DIR 下一级子目录以及 VIDEO_DIR.parent 中自动扫描候选文件名（见上表）。
2. 如果恰好找到一个匹配项，则使用该文件并打印找到的内容。
3. 如果未找到或找到多个匹配项，则打印已搜索的位置，然后通过宿主的提问机制向用户询问明确路径；如果没有可用的提问机制，则在聊天中提问并等待。如果用户没有该文件，则标记为由 UI 补充。
4. **UI 补充：**告知用户完成对应的 UI 步骤；等待确认后继续执行步骤 6，并将 verify_project 视为判断 UI 提供的对齐数据/布局数据是否完整的权威依据。

步骤 4 — 上传已解析的文件

上传本地解析出的每个文件：

文件	端点	备注
校准设置	POST /v1/config/<project_id>（JSON，原样提交）	替代 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，以验证组装完成的项目。

成功提交设置后，解析文件中的 "detector" / "detector_type"；如果值为 "resnet" 或 "transformer"，则在步骤 7 的 /calibrate 调用中使用该值（检测器是独立的 API 参数，不由 /config 读取）。

步骤 5 — UI 回退（仅适用于用户本地没有的文件）

如果步骤 3 未能确定 settings、alignment 或 layout 中的任何一项，请引导用户执行相应的 UI 步骤：

• 缺少 settings → “打开 UI 项目 <project_id>，转到 步骤 3：Parameters，通过 settings 对话框进行调整（或接受默认值），然后点击 Save。”另外：调用 /calibrate 之前，使用宿主的提问机制询问用户要使用哪个 detector（resnet 或 transformer）；如果没有可用的提问机制，则在聊天中询问并等待回复。UI 步骤 3 不包含 detector 选择。
• 缺少 alignment 或 layout → “打开 UI 项目 <project_id>，转到 步骤 4：Alignment，上传 layout，标记对应点，然后点击 Save。”

等待用户确认。对于非交互式脚本运行，请预先提供所需文件；脚本会退出并显示清晰消息，而不是等待用户输入。UI 回退不需要用户能够本地访问 AMC 的 projects/ 存储；步骤 6 是标准的服务端验证步骤。

步骤 6 — 验证项目

POST /v1/verify_project/<project_id> → 在开始校准前，必须返回 {"project_state": "READY"}。

步骤 7 — 开始校准

校准前确认计划。 无论 settings 文件和 detector 是自动检测到的还是通过询问确定的，都要先简要总结并获取用户的明确确认，然后再使用宿主的提问机制调用 POST /calibrate；如果没有可用的提问机制，则在聊天中询问并等待回复。已确定的值都是默认值，因此确认只需点击一次；但用户可以切换 detector，也可以跳过自动检测到的 settings 文件。独立 Python 脚本会在 stdin 处于交互模式时提示用户；在非交互式运行中，除非设置了 CONFIRM_CALIBRATION=true，否则脚本会在调用 /calibrate 前退出。总结以下内容：

• Detector — resnet 或 transformer（将要发送的值）。
• Calibration settings — 要应用的文件（路径），如果没有则为“默认值”。
• 可选覆盖项 — ground-truth zip 和焦距（如有）。

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

{"detector_type": "resnet"}

步骤 8 — 轮询完成状态

每隔 10 s 调用 GET /v1/get_project_info/<project_id> — project_info.project_state 将从 RUNNING 变为 COMPLETED（或 ERROR，此时提取日志）。典型耗时：10–60 分钟，具体取决于视频长度和 detector。捆绑脚本默认将时限设为 90 分钟，通过 CALIBRATION_TIMEOUT_SECONDS=5400 配置；运行时间较长时，请提高该环境变量的值，而不要静默终止进程。

步骤 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 状态码，请显示该 HTTP 错误，而不要将其视为缺少 GT 的情况。

get_project_info 中的状态字段

project_info.project_state 表示项目的 AMC 校准生命周期：RUNNING → COMPLETED（或 ERROR）。

project_info.vggt_state 同样是项目级状态，表示项目范围内的 VGGT 优化生命周期，而不是全局服务或模型加载状态。新建项目即使已挂载 VGGT 模型，也可能报告 vggt_state: "INIT"。预期的 VGGT 生命周期为 INIT → AMC 校准完成后变为 READY → VGGT 优化运行期间变为 RUNNING → COMPLETED（或 ERROR）。

仅将 vggt_state == "READY" 用作步骤 10 中可选 VGGT 优化的门槛。对于新建或未经校准的项目，应将 INIT 视为正常项目状态。如果 AMC 校准已完成，但项目的 VGGT 状态仍未就绪，请通过 setup 技能检查和服务日志确认 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 脚本

使用 amc-run-video-calibration 技能包中附带的脚本，而不是 auto-magic-calib 仓库根目录中的脚本。如果用户直接将此技能文件夹提供给 Agent，而不是安装技能，请将 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
标定卡在 RUNNING 状态超过 90 分钟	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）”部分介绍了输入视频指南，以及通过 UI 驱动的 API 流程替代方案。