/amc-run-video-calibration

name: "amc-run-video-calibration"
description: "Calibrates pre-recorded `cam_*.mp4` datasets through the AutoMagicCalib REST API. Use for user-supplied local MP4s; route live RTSP streams to `amc-run-rtsp-calibration`."
owner: "NVIDIA CORPORATION"
service: "auto-magic-calib"
reviewed: "2026-04-28"
license: "Apache-2.0"
permissions: [env, file_read, network]
metadata:
  version: "1.0.0"
  author: "Shubham Agrawal <shuagrawal@nvidia.com>"
  tags: [amc, calibration, rest-api, camera, python]

Skill: Calibrate from Video Files

When to Use This Skill

Activate this skill when the user has pre-recorded MP4 files and wants to calibrate them via the AMC REST API. Typical prompts:

• "calibrate my videos" / "run AMC on these videos"
• "calibrate from video files"

Drives calibration through the REST API on user-supplied **pre-recorded MP4 files** — no CLI scripts or Docker bind-mounts required, just a running microservice and your files.

Do not use this skill for live RTSP streams or `rtsp://...` URLs; route those requests to `skills/amc-run-rtsp-calibration/SKILL.md`.

Purpose

Guide the agent through project creation, sorted MP4 upload, local asset resolution, UI fallback only when necessary, project verification, calibration, polling, evaluation, and optional VGGT refinement for a user-provided multi-camera dataset.

Prerequisites

• [ ] AMC microservice **and** UI running (follow `skills/amc-setup-calibration-stack/SKILL.md`)
• [ ] You know the microservice URL (use `https://<HOST_IP>:<MS_PORT>` for remote AMC, or `http://localhost:<MS_PORT>` on loopback) and UI URL
• [ ] Video files locally as contiguous `cam_00.mp4`, `cam_01.mp4`, … time-synchronized, ~1920×1080
• [ ] Python 3 with `requests`
• [ ] If AMC stores project outputs outside the default `projects/` directory, you know the host `PROJECTS_DIR`

Interaction Model

• The "host's question mechanism" means the runtime's built-in prompt API for short user decisions, such as terminal stdin, an IDE ask tool, or an equivalent interactive dialog.
• If that mechanism is unavailable, ask in chat and wait before any guarded step that requires user confirmation or a missing-file decision.
• For unattended runs, the bundled script requires all non-UI inputs up front and exits before `/calibrate` unless `CONFIRM_CALIBRATION=true` is set. `RUN_VGGT=true` remains a separate opt-in for the optional VGGT step.

Data Privacy

Video files uploaded via this skill are transmitted to the AutoMagicCalib backend (REST endpoint). Only use this skill when the backend is deployed on a trusted platform / network.

Inputs

• Required inputs: `VIDEO_DIR`, `BASE_URL`, and `PROJECT_NAME`.
• Optional local inputs: `CONFIG_FILE`, `ALIGNMENT_JSON`, `LAYOUT_PNG`, `GT_ZIP`, `FOCAL_LENGTHS`, and `DETECTOR_TYPE`.
• Optional control inputs: `CONFIRM_CALIBRATION`, `RUN_VGGT`, `PROJECTS_DIR`, `CALIBRATION_TIMEOUT_SECONDS`, and `VGGT_TIMEOUT_SECONDS`.
• `BASE_URL` should use HTTPS for non-loopback hosts. Set `ALLOW_INSECURE_HTTP=true` only for trusted development setups that intentionally use remote plain HTTP.
• Resolution precedence for settings, alignment, and layout: explicit path, single local auto-detected match, then UI fallback.

What to Ask the User

Required

(Video-file naming and the microservice URL are specified under Prerequisites above — collect the inputs below.) 1. **Videos directory** — the folder the skill globs for `cam_*.mp4`, uploaded sorted alphabetically. 2. **Microservice URL** 3. **Project name** — short descriptive string

Auto-Detected (ask only if not found)

The script searches the videos dir, its first-level subdirectories, and its parent. If exactly one match is found, it is used; otherwise the script prints the searched locations and continues to explicit path or UI fallback:

| File | Candidate filenames | UI fallback | |---|---|---| | Calibration settings | `settings.json`, `config.json`, `calibration_config.json` | UI Step 3: Parameters | | Alignment JSON | `alignment_data.json` | UI Step 4: Alignment | | Layout PNG | `layout.png` | UI Step 4: Alignment |

Posting the settings file replaces UI Step 3 and may pin the detector (`resnet`/`transformer`), which is passed to `/calibrate` separately — see Step 4.

Optional

4. **Ground truth zip** — `GT.zip` with `_World_Cameras_Camera_XX/` folders (enables evaluation metrics) 5. **Focal lengths** — one per camera, e.g. `1269.0, 1099.5, 1099.5` 6. **Detector type** — `resnet` (default, fast) or `transformer` (slower, better under occlusion) 7. **Run VGGT refinement?** — if VGGT is ready after AMC completes, ask the user whether to run refinement (see setup skill)

See root `README.md` "Custom Dataset" section for input-video guidelines and ground-truth format.

---

Available Scripts

| Script | Purpose | Key inputs | |---|---|---| | [run_video_calibration.py](scripts/run_video_calibration.py) | Executes create-project, upload, verify, calibrate, poll, evaluate, and optional VGGT refinement for a local MP4 dataset. | Required: `BASE_URL`, `PROJECT_NAME`, `VIDEO_DIR`. Optional: `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`. |

Instructions

All endpoints below are implemented end-to-end in the [Complete Python Script](#complete-python-script) — the prose is the workflow plus the decisions the agent must make; the script is the authoritative runnable.

Step 1 — Create Project

`POST /v1/create_project` (form field `project_name`) → save the returned `project_id`.

Step 2 — Upload Videos (required)

`POST /v1/upload_video_files/<project_id>` (multipart `files`). **Upload sorted alphabetically** — the server assigns camera indices by upload order. The bundled script rejects non-contiguous or non-zero-based camera sequences up front; the directory must contain `cam_00.mp4`, `