⚡

AMC样本数据标定Skill "amc-run-sample-calibration"

该技能用于对AutoMagicCalib（AMC）微服务使用自带的样本数据集（sdg_08_2_sample_data_010926.zip）进行端到端标定验证，帮助用户快速测试AMC安装是否正常。包括检测后端、解压样本、调用REST API跑标定、获取评估指标等流程。关键词：AMC、相机标定、样本验证、REST API、SDG数据集。

视频标定工具 0 次安装 0 次浏览 更新于 9/6/2026
名称 “amc-run-sample-calibration”
描述 “对随附的样本数据集 sdg_08_2_sample_data_010926.zip 在运行中的 AMC 微服务上执行端到端标定。当用户说‘测试样本数据集’、‘运行样本标定’、‘验证 AMC 安装’或‘启动并测试’时使用。” owner: “NVIDIA CORPORATION” service: “auto-magic-calib”
版本 “1.0.0” reviewed: “2026-04-28”
开源协议 “Apache-2.0” metadata:
作者 “NVIDIA CORPORATION” tags: [amc, calibration, sample, rest-api, validation, python]

技能：标定样本数据集

何时使用本技能

当用户想要使用自带的样本数据集对正在运行的 AMC 堆栈进行健康检查时，激活此技能。典型提示：

  • “测试样本数据集” / “运行样本标定”
  • “验证 AMC 安装”
  • “启动并测试”（如果微服务尚未运行，则与 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 顺序，以便用户在满足先决条件后知道将运行什么。不要伪造标定输出、评估指标或轨迹。

概述

针对正在运行的 AutoMagicCalib 微服务，对随附的样本数据集（sdg_08_2_sample_data_010926.zip，4 个带真值的合成仓库摄像头）执行完整标定。有助于在将真实数据投入之前，验证新启动的堆栈能否端到端工作。

样本包含真值，因此运行会产生评估指标（L2 距离、重投影误差）——无需进行标定参数调整。

先决条件

  • [ ] AMC 微服务正在运行（如果没有，请遵循 skills/amc-setup-calibration-stack/SKILL.md）
  • [ ] 样本 zip 存在于 assets/sdg_08_2_sample_data_010926.zip
  • [ ] Python 3 且 requests 可用，或使用下面的 Swagger UI 路径
    • 随附脚本可自愈：如果缺少 requests，它会在 ${TMPDIR:-/tmp}/amc-sample-test-venv 下创建一个临时 venv（不会写入仓库）
    • 如果 python3 -m venv 本身因 ensurepip not available 失败：sudo apt install -y python3-venv python3-pip

说明

“启动 AMC 并测试样本数据集”（或类似）：

  1. 首先运行 skills/amc-setup-calibration-stack/SKILL.md。
  2. 等待 /v1/ready 返回 OK。
  3. 解压样本数据（见下文片段）——幂等，可安全重新运行。
  4. 运行 运行脚本 中的捆绑脚本。
  5. 报告最终指标 + 供手动检查的 UI URL。
  6. 默认情况下，当项目报告 vggt_state: READY 时会尝试 VGGT 优化；否则脚本会解释 VGGT 设置是可选的，可以稍后启用以进行优化。

“测试样本数据集”（微服务已在运行）：

  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 “没有正在运行的后端，请先运行 amc-setup-calibration-stack 技能。”; exit 1; }
echo “后端在端口 $MS_PORT”

查找并解压样本数据（幂等）

: “${REPO_ROOT:?将 REPO_ROOT 设置为 auto-magic-calib 检出目录。请先运行 amc-setup-calibration-stack 第 0b 步。}”
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 不是 auto-magic-calib 检出目录: $REPO_ROOT” >&2; exit 1; }

SAMPLE_ZIP=“$REPO_ROOT/assets/sdg_08_2_sample_data_010926.zip”
[ -f “$SAMPLE_ZIP” ] || { echo “在 $SAMPLE_ZIP 找不到样本 zip”; exit 1; }

# 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”
# 预期（可能在外层文件夹内）：alignment_data/  GT.zip  videos/

运行脚本

从 amc-run-sample-calibration 技能包运行捆绑脚本，而不是从 auto-magic-calib 仓库根目录运行。如果用户直接指向此技能文件夹而不是安装它，请将 AMC_SAMPLE_SKILL_DIR 设置为包含此 SKILL.md 的目录，或从该目录运行命令。将 REPO_ROOT 设置为由 amc-setup-calibration-stack 解析出的 AutoMagicCalib 检出目录；脚本从该检出目录读取 compose/.env 以获取后端端口，接受 BASE_URL、MS_PORT、SAMPLE_DIR 和 RUN_VGGT 覆盖，每次运行创建新项目，在就绪时尝试 VGGT，并在最后打印 NGC 仓库数据集说明。

# REPO_ROOT 必须指向 auto-magic-calib 检出目录，而不是 DeepStream 仓库。
: “${REPO_ROOT:?将 REPO_ROOT 设置为 auto-magic-calib 检出目录。请先运行 amc-setup-calibration-stack 第 0b 步。}”
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 不是 auto-magic-calib 检出目录: $REPO_ROOT” >&2; exit 1; }

# 如果 AMC 是从 DeepStream 的 tools/auto-magic-calib 子模块解析出来的，
# 则推导 DeepStream 根目录，以便直接使用解包后的仓库技能。
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: 找不到 amc-run-sample-calibration/scripts/run_sample_calibration.py” >&2
  echo “将 AMC_SAMPLE_SKILL_DIR 设置为 amc-run-sample-calibration 技能目录，或从该目录运行此块。” >&2
  exit 1
}

python3 “$SCRIPT_PATH”

备选方案：Swagger UI 演练

Agent 快捷方式：如果用户明确要求 Swagger UI 演练（或说“不要 Python”），请输出下面的表格并停止——不要调用 shell 工具、阅读其他部分或运行捆绑的 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：按名称排序上传所有 4 个 videos/cam_0*.mp4
    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} 每隔约 10 秒刷新，直到 project_state = COMPLETED
    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 时运行；轮询 vggt_state 直到 COMPLETED

这与捆绑的 Python 脚本运行的顺序相同，只是手动执行。当 vggt_state 为 READY 时，默认会尝试第 10 步；否则会跳过并提供设置指导。

get_project_info 中的状态字段

project_info.project_state 是项目的 AMC 标定生命周期。轮询它直到达到 COMPLETED（或在 ERROR 时停止）。

project_info.vggt_state 是每个项目的 VGGT 优化生命周期，是项目范围内的状态，而不是直接的全局服务或模型加载状态。即使 VGGT 模型存在并已挂载，新创建的项目也可能报告 vggt_state: “INIT”。预期的生命周期是 INIT → AMC 标定完成后 READY → VGGT 优化运行时 RUNNING → COMPLETED（或 ERROR）。将新或未标定项目上的 INIT 解释为正常的项目状态。如果 AMC 标定已完成，而项目仍处于非就绪的 VGGT 状态，请通过设置技能检查和服务器日志确认 VGGT 设置和模型可用性。

成功标准

  • 项目在大约 30 分钟内达到 project_state == “COMPLETED”。
  • /v1/result/{id}/evaluation_statistics 返回非空 statistics（已上传 GT）。
  • VGGT 要么运行到 vggt_state == “COMPLETED” 并报告 /v1/vggt_results/{id}/evaluation_statistics，要么因为项目未为 VGGT READY 而跳过并提供设置指导。
  • 未遇到 ERROR 状态。

样本的代表性指标（您的应与此类似）：

平均 L2 距离(m)               : < 1.5
平均重投影误差 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          # ← 最终标定（使用此文件）
└── calibration.log

监控进度

PROJECT_ID=<id_from_step_1>
: “${REPO_ROOT:?将 REPO_ROOT 设置为 auto-magic-calib 检出目录。请先运行 amc-setup-calibration-stack 第 0b 步。}”
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 不是 auto-magic-calib 检出目录: $REPO_ROOT” >&2; exit 1; }
tail -F --retry “$REPO_ROOT/projects/project_${PROJECT_ID}/calibration.log”

或流式查看 MS 日志：

: “${REPO_ROOT:?将 REPO_ROOT 设置为 auto-magic-calib 检出目录。请先运行 amc-setup-calibration-stack 第 0b 步。}”
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 不是 auto-magic-calib 检出目录: $REPO_ROOT” >&2; exit 1; }
docker compose -f “$REPO_ROOT/compose/compose.yml” logs -f auto-magic-calib-ms

故障排除

问题 修复
未安装 requests 在 venv 中：python3 -m venv venv && ./venv/bin/pip install requests。如果 python3 -m venv 失败：先运行 sudo apt install -y python3-venv python3-pip
[2] 上传了 N 个视频，其中 N >> 4 SAMPLE_DIR 解析到了仓库根目录（或其他过宽路径），rglob(“cam_*.mp4”) 扫过了 .cache/、projects/ 等中的过时视频。停止运行（POST /v1/stop_calibration/{id}），删除项目（DELETE /v1/delete_project/{id}），显式将 SAMPLE_DIR 设置为解压后的样本目录，重新运行。脚本锚定 videos/ 并断言 len(videos) <= 16 以大声失败
verify_project 返回状态 != READY 确认所有 4 个视频 + alignment + layout + 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 还记录了 nv_warehouse_032326.zip，这是一个可从 NGC 获取的真实世界仓库数据集。使用 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)”部分介绍了通过相同样本的人工导向路径。

<!-- signing marker -->