vss-generate-video-calibration

目的

在本地文件、RTSP 流或随附的示例数据集上端到端运行 AutoMagicCalib，并在需要时部署 AMC 微服务。

说明

按照下方的路由表和分步工作流操作。以 workflow、quick start 或 flow 结尾的每个部分，都应从上到下执行。详细参考资料位于 references/ 中；仅加载所选输入模式所需的参考资料。

示例

端到端操作示例存放在 evals/ 下（每个 *.json 清单都包含一个可运行的场景），下方各工作流中的 curl 代码块也包含内嵌示例。运行 Tier-3 评估：nv-base validate <this-skill-dir> --agent-eval，即可重放这些示例。

限制

• 需要部署与之匹配且调用方可访问的 VSS 配置文件 / 微服务。
• 托管于 NGC 的模型和 NIM 可能受速率限制、GPU 内存要求和许可限制。
• 并发、GPU 内存和存储限制取决于主机硬件以及配置文件的 compose 文件。

故障排查

• 错误：REST 调用返回连接被拒绝。原因：目标微服务未运行。解决方案：检查 /docs 或 /health；通过 vss-deploy-profile 或匹配的 vss-deploy-* 技能重新部署。
• 错误：从 NGC 拉取时收到 HTTP 401/403。原因：缺少或过期的 NGC_CLI_API_KEY。解决方案：运行 docker login nvcr.io 并重新导出密钥，然后重试。
• 错误：容器发生 OOM，或模型加载失败。原因：所选配置文件的 GPU 内存不足。解决方案：切换到较小的变体，或通过 docker compose down 释放 GPU。

VSS 生成视频校准

通过微服务 REST API，对三种输入源之一运行 AutoMagicCalib 并执行校准。各输入源的输入解析步骤有所不同；从 verify_project 开始的所有步骤都相同，且位于此文件中。选择合适的输入模式参考资料，并结合下方的共享校准后续步骤。

仅在需要时加载共享辅助参考资料：

• 当模式参考资料需要共享的 create_project、视频上传或移交片段时，阅读 references/common-steps.md。
• 需要 verify → calibrate → poll → results 后续步骤的可复用 Python 实现时，阅读 references/calibration-tail.md。

输入路由

将用户的请求匹配到相应模式，然后加载该模式的参考资料，以了解输入收集、特定模式的 API 调用以及完整 Python 脚本。

用户的说法 / 提供的内容	模式	参考资料
“启动 AMC” / “部署自动校准” / “设置 auto-magic-calib” / “启动 AMC 微服务”	deploy	references/deploy-auto-calibration-service.md
“校准我的视频” / “根据视频文件校准” / 本地 cam_*.mp4 文件	videos	references/videos.md
“校准 RTSP 流” / “根据实时摄像机校准” / 实时 RTSP URL	rtsp	references/rtsp.md
“测试示例数据集” / “验证 AMC 安装” / “启动并测试”	sample-dataset	references/sample-dataset.md

**消歧规则：**如果用户想启动 / 部署 / 设置 AMC（没有提到校准）→ deploy。如果用户提供 RTSP URL → rtsp。如果用户提到本地文件 / 视频目录 → videos。如果用户想验证安装或测试随附的示例 → sample-dataset。对于组合意图（例如“启动 AMC 并校准我的视频”）→ 先执行 deploy，再执行校准模式。意图不明确时，通过 AskUserQuestion 询问。

前置条件（各校准模式通用）

• AMC 微服务和 UI 正在运行。如果尚未运行，请先参阅 references/deploy-auto-calibration-service.md。
• 微服务可通过 http://<HOST_IP>:${VSS_AUTO_CALIBRATION_PORT:-8010}/v1/ready 访问 → {"code":0,...}。
• 容器用户对项目目录具有写入权限。如果不是刚完成部署（即部署参考文档中的第 5 步尚未执行），请按照 references/deploy-auto-calibration-service.md § 第 5 步确认写入测试已通过；否则，首次调用 create_project 会返回 [Errno 13] Permission denied。
• 已安装 Python 3 和 requests（每个输入模式参考文档都包含可在直接运行时自动修复的 venv 回退方案）。

模式专属前置条件（rtsp 所需的 VIOS、sample-dataset 所需的示例 zip）请参阅各自的参考文档。

通用校准后续步骤

无论输入模式如何，验证 → 校准 → 轮询 → 查看结果这一流程都相同。模式专属参考文档完成视频上传 / RTSP 片段导入 / 捆绑示例上传后，运行以下步骤。通用 Python 代码片段请参阅 references/calibration-tail.md。

步骤 A — 验证项目

POST /v1/verify_project/<project_id>

响应：{"project_state": "READY"} — 校准前必须处于 READY 状态。如果未就绪，请重新检查视频、对齐和布局是否均已准备就绪（可通过 API 检查，也可在 UI 中手动对齐）。

步骤 B — 开始校准

校准前确认方案。 无论设置文件和检测器是自动检测到的，还是通过询问确定的，都应先简要总结并通过 AskUserQuestion 确认，然后再调用 POST /calibrate。已解析的值就是默认值，因此只需单击一次即可确认，但用户也可以切换检测器或跳过自动检测到的设置文件。请总结：

• 检测器 — resnet 或 transformer（要发送的值）。
• 校准设置 — 要应用的文件（路径），或默认参数（可选择先在 UI 中调整，见下文）。
• 可选覆盖项 — 实际地面真值 zip 和焦距（如有）。

sample-dataset 安装检查运行使用固定的 resnet，无需此确认即可继续。

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

{"detector_type": "resnet"}   # or "transformer"

detector_type 是独立的 /calibrate 参数，不会由 /v1/config/<id> 使用。如果用户提供了校准设置文件，请解析其中的 "detector" / "detector_type" 并使用该值。如果文件中未指定，默认值（resnet）就是上述确认中显示的值；用户可以在确认时切换。如果完全没有设置文件，请通过 AskUserQuestion 询问用户：

• resnet — 默认选项，速度快。
• transformer — 速度较慢，但在严重遮挡情况下效果更好。

UI 第 3 步（Parameters）不包含检测器选择；切勿假设用户已在 UI 中选择检测器。

此外，如果没有设置文件，还要询问是否先调整校准参数（AskUserQuestion）：

• 使用默认参数继续 — 适合典型仓库场景；除非用户有明确的调参需求，否则建议使用此选项。
• 先在 UI 中调整参数 — 打开项目，进入第 3 步：Parameters，修改值并点击 Save；然后继续。

调用 /calibrate 前，请等待用户选择；如果用户选择调整参数，还需等待用户确认已点击 Save。

步骤 C — 轮询完成状态

GET /v1/get_project_info/<project_id>

每隔 10 s 轮询一次。project_info.project_state：

状态	含义
RUNNING	正在进行标定
COMPLETED	已完成
ERROR	失败 — 通过 GET /v1/amc/calibrate/<id>/log 获取日志

标定开始时，向用户展示项目 ID、UI URL（http://<HOST_IP>:${VSS_AUTO_CALIBRATION_UI_PORT:-5000}）和日志端点，以便用户在运行过程中查看进度。在 RUNNING 期间，至少每分钟输出一条包含已用时间的进度信息，避免长时间运行看起来像是卡住了。遇到 ERROR 时，在停止前获取并展示 GET /v1/amc/calibrate/<id>/log 的末尾几行。也可以通过 GET /v1/calibrate/<project_id>/log/<type>/stream 实时流式传输日志。

典型耗时：10–60 min（用户自己的视频）、10–30 min（捆绑示例）。

步骤 D — 结果

GET /v1/get_project_info/<project_id>                    # project state
GET /v1/result/<project_id>/evaluation_statistics        # only if GT uploaded
GET /v1/result/<project_id>/overlay_image                # visual overlay (PNG)
GET /v1/amc/calibrate/<project_id>/log                   # calibration log

评估响应包含 Average L2 distance(m) 和 Average reprojection error 0(px)。只有在上传了真值 GT.zip 时才会生成评估指标——否则没有 evaluation_statistics 结果是正常情况，并不代表结果报告到此结束。

状态变为 COMPLETED 后，始终为用户提供查看该项目结果的方式，无论是否存在指标：

• UI — http://<HOST_IP>:${VSS_AUTO_CALIBRATION_UI_PORT:-5000}；打开项目，然后前往 Results 页面查看叠加图。
• 磁盘上的叠加图像 — ${VSS_APPS_DIR}/services/auto-calibration/projects/project_<id>/output/multi_view_results/BA_output/results_ba_scaled_world/overlay_img_*.png（单摄像头项目使用 output/single_view_results/cam_00/verification_map_overlay.png）。
• 项目文件 — ${VSS_APPS_DIR}/services/auto-calibration/projects/project_<id}/。

步骤 E — VGGT 精化

AMC 运行完成后，始终检查项目详情中的 vggt_state。设置期间可选择是否暂存 VGGT 模型，不得因此阻碍 AMC 结果；但 AMC 运行后的处理取决于该状态：

• 如果 vggt_state == "READY"，且用户明确要求 VGGT 精化或在此设置流程中暂存了 VGGT，则无需再次询问，直接运行 VGGT 精化。
• 如果 vggt_state == "READY"，但 VGGT 在此次请求之前就已暂存，且用户没有要求生成经 VGGT 精化的结果，则在开始精化前通过 AskUserQuestion 询问是否运行精化。
• 如果 VGGT 尚未就绪，则跳过精化，并说明暂存模型后即可使用 VGGT 精化（参见 references/deploy-auto-calibration-service.md 的步骤 2）。

POST /v1/vggt/calibrate/<project_id>
GET  /v1/get_project_info/<project_id>                    # poll vggt_state
GET  /v1/vggt_results/<project_id>/evaluation_statistics  # VGGT metrics

设置文件 + 检测器模式

三种模式均可选。用户提供 JSON 设置文件时（通常从 UI 的步骤 3 导出下载），原样 POST：

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

<file contents, posted as-is>

该文件会替代用户原本需要在 UI 步骤 3 中调整的设置（校正、束调整、评估参数、检测器等）。POST 成功后，还要解析文件中的 "detector" / "detector_type"——如果值为 "resnet" 或 "transformer"，则在步骤 B 调用 /calibrate 时使用该值（检测器是单独的 API 参数，不由 /config 使用）。

对于非 2xx 响应，应向用户展示错误，不要静默回退。如果用户选择了 UI 回退路径，则完全跳过此调用。

UI 回退模式

当磁盘上没有对齐 / 布局文件时，引导用户执行相应的 AMC UI 步骤：

• 缺少设置 → “打开 UI 项目 <project_id>，转到 Step 3: Parameters，通过设置对话框调整参数（或接受默认值），然后点击 Save。”另外：在调用 /calibrate 之前，通过 AskUserQuestion 询问用户使用 resnet 还是 transformer 检测器——Step 3 不涉及检测器选择。
• 缺少布局 → “打开 UI 项目 <project_id>，转到 Step 2: Video Configuration，仅上传 layout.png（不要重新上传视频——它们已通过 API/RTSP 附加），然后点击 Save。”
• 缺少对齐 → “打开 UI 项目 <project_id>，转到 Step 4: Alignment，上传 alignment_data.json，或在布局上标记对应点，然后点击 Save。”

等待用户确认。对于对齐 / 布局，在继续之前先确认磁盘上已有相应文件：

# Project state lives under $VSS_APPS_DIR/services/auto-calibration/projects
# (the path bind-mounted into the MS container in
#  deploy/docker/services/auto-calibration/ms/compose.yml).
HOST_PROJECTS="${VSS_APPS_DIR}/services/auto-calibration/projects"

ls "$HOST_PROJECTS/project_<project_id>/manual_adjustment/"
# Expected: alignment_data.json, layout.png

成功标准

• 轮询后，project_state == "COMPLETED"。
• 如果使用了手动对齐：${VSS_APPS_DIR}/services/auto-calibration/projects/project_<id>/manual_adjustment/ 中包含 alignment_data.json 和 layout.png。
• 如果上传了 GT：评估结果达到常见阈值（对于你的数据，Average L2 distance(m) < 1.5，Average reprojection error 0(px) < 5；对于捆绑样例，< 10）。
• 不处于 ERROR 状态。

关键输出文件

位于 ${VSS_APPS_DIR}/services/auto-calibration/projects/project_<project_id>/ 下：

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
│   └── multi_view_results/BA_output/results_ba_scaled_world/
│       └── overlay_img_XX.png               # ← visual overlay for review
└── calibration.log

通用故障排查

各模式的特定问题请参阅对应参考文档中的故障排查表。

问题	解决方法
verify_project 状态不是 READY	确认视频已上传 / 导入，且对齐和布局文件已就位（通过 API 或 UI 手动对齐）。各模式的上传步骤请参阅对应参考文档。
执行 UI 步骤后仍缺少手动对齐文件	用户没有点击 Save；同时确认 ${VSS_APPS_DIR}/services/auto-calibration/projects/project_<id>/manual_adjustment/ 存在。
校准处于 RUNNING 状态超过 90 分钟	GET /v1/amc/calibrate/<id>/log — 通常是轨迹段不足（场景过于静态）。请参阅根目录 README.md 中的“自定义数据集”指南。
立即进入 ERROR 状态	检查视频命名：必须为 cam_00.mp4、cam_01.mp4，依此类推，且编号连续（视频模式）/ 标签为 camera_name（RTSP 模式）。
L2 误差低但重投影误差高	上传输入时提供明确的 focal_length 覆盖值（请参阅 videos / rtsp 参考文档）。
VGGT 处于 INIT，始终未进入 READY	VGGT 模型未加载——请参阅 references/deploy-auto-calibration-service.md 的 Step 2。
上传超时	视频文件较大——在各模式的 Python 脚本中将 timeout=300 调高至例如 600。
端口扫描未发现后端	后端未运行——请先按 references/deploy-auto-calibration-service.md 中的步骤操作。

下游技能 — MV3DT 导出

下游使用方（例如由其他团队维护的 Multi-View 3D Tracking 技能）会直接从微服务获取 MV3DT 格式的校准输出。此技能会返回 project_id；下游技能调用：

GET /v1/result/{project_id}/mv3dt_result?result_type=amc
# Response: application/zip — mv3dt_output.zip containing transforms.yml

对于 VGGT 优化后的输出（仅当 VGGT 运行至 COMPLETED 时可用，请参阅 Step E）：

GET /v1/result/{project_id}/mv3dt_result?result_type=vggt
# Response: application/zip — vggt_mv3dt_output.zip

下游技能流程：

1. 使用用户输入调用此技能；记录打印出的 project_id。
2. 等待技能返回（它会在内部轮询，直到状态为 COMPLETED）。
3. GET /v1/result/{project_id}/mv3dt_result?result_type=amc — 将 ZIP 保存到本地。
4. 如果也运行了 VGGT，可选获取 ?result_type=vggt 以取得优化后的 MV3DT。

相关技能

• vss-manage-video-io-storage — VIOS API 技能；只有 rtsp 校准模式依赖 VIOS 可访问。

根目录 README.md 中的“自定义数据集”和“校准工作流（UI）”章节介绍了输入视频指南，以及此 API 流程的 UI 操作替代方案。

bump:1