amc-run-sample-calibration

# Skill: Calibrate Sample Dataset ## When to Use This Skill Activate this skill when the user wants to sanity-check a running AMC stack with the bundled sample dataset. Typical prompts: - "test the sample dataset" / "run sample calibration" - "verify AMC install" - "launch and test" (chain with `amc-setup-calibration-stack` if the MS isn't already running) **Do NOT use this skill when:** - The user references their own video paths (e.g. `/data/videos/`, `cam_*.mp4` not from the bundled zip) — route to `amc-run-video-calibration`. - The user provides live RTSP streams or `rtsp://...` URLs — route to `amc-run-rtsp-calibration`. - This skill is exclusively for `assets/sdg_08_2_sample_data_010926.zip`. Prerequisite: AMC microservice running on a port in 8000-8009. If no backend is detected, delegate to `amc-setup-calibration-stack` first. If execution cannot proceed in the current environment (no backend, missing sample data, etc.), surface the blocker AND describe the expected workflow + API sequence concisely so the user understands what will run once prerequisites are met. Do not fabricate calibration outputs, evaluation metrics, or trajectories. ## Overview Run a full calibration on the bundled sample dataset (`sdg_08_2_sample_data_010926.zip`, 4 synthetic warehouse cameras with ground truth) against a running AutoMagicCalib microservice. Useful for verifying that a freshly-launched stack works end-to-end before throwing real data at it. The sample includes GT, so the run produces evaluation metrics (L2 distance, reprojection error) — no calibration parameter tuning needed. ## Prerequisites - [ ] AMC microservice running (follow `skills/amc-setup-calibration-stack/SKILL.md` if not) - [ ] Sample zip present at `assets/sdg_08_2_sample_data_010926.zip` (published as a DeepStream v9.2.0 release asset; if missing, download it: `curl -L -o assets/sdg_08_2_sample_data_010926.zip https://github.com/NVIDIA/DeepStream/releases/download/v9.2.0/sdg_08_2_sample_data_010926.zip`) - [ ] Python 3 with `requests` installed, or use the Swagger UI path below - Install it explicitly before running the script: `python3 -m pip install requests` - If `pip` is unavailable, install your distro's Python packaging support first ## Instructions **"launch AMC and test sample dataset" (or similar):** 1. Run `skills/amc-setup-calibration-stack/SKILL.md` first. 2. Wait for `/v1/ready` to return OK. 3. Extract sample data (snippet below) — idempotent, safe to re-run. 4. Run the bundled script in [Run Script](#run-script). 5. Report final metrics + UI URL for manual inspection. 6. VGGT refinement is attempted by default when the project reports `vggt_state: READY`; otherwise the script explains that VGGT setup is optional and can be enabled later for refinement. **"test sample dataset" (MS already running):** 1. Detect backend: scan ports 8000–8009 for a `/v1/ready` response. 2. If none → point to the setup skill. 3. Extract sample data if not already cached. 4. Run the bundled script. 5. Report metrics. ### Detect Running Backend ```bash 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 "No running backend. Run amc-setup-calibration-stack skill first."; exit 1; } echo "Backend on port $MS_PORT" ``` ### Locate + Extract Sample Data (idempotent) ```bash : "${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; } SAMPLE_ZIP="$REPO_ROOT/assets/sdg_08_2_sample_data_010926.zip" [ -f "$SAMPLE_ZIP" ] || { echo "Sample zip not found at $SAMPLE_ZIP"; exit 1; } # Cache directory next to the 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" # Expected (possibly inside a wrapper folder): alignment_data/ GT.zip videos/ ``` ## Run Script Run the bundled script from the `amc-run-sample-calibration` skill package, not from the `auto-magic-calib` repo root. If the user points the agent at this skill folder directly instead of installing it, set `AMC_SAMPLE_SKILL_DIR` to the directory containing this `SKILL.md`, or run the command from that directory. Set `REPO_ROOT` to the AutoMagicCalib checkout resolved by `amc-setup-calibration-stack`; the script auto-detects a running backend on localhost ports `8000`-`8009` when `BASE_URL` / `MS_PORT` are not set, accepts `BASE_URL`, `MS_PORT`, `SAMPLE_DIR`, and `RUN_VGGT` overrides, creates a fresh project each run, attempts VGGT when ready, and prints the NGC warehouse dataset note at the end. ```bash # REPO_ROOT must point to the auto-magic-calib checkout, not the DeepStream repo. : "${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; } # If AMC was resolved from DeepStream's tools/auto-magic-calib submodule, # derive the DeepStream root so the unpacked repo skill can be used directly. 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: could not find amc-run-sample-calibration/scripts/run_sample_calibration.py" >&2 echo "Set AMC_SAMPLE_SKILL_DIR to the amc-run-sample-calibration skill directory, or run this block from that directory." >&2 exit 1 } python3 "$SCRIPT_PATH" ``` ## Alternative: Swagger UI Walkthrough > **Agent shortcut**: if the user explicitly requested a Swagger UI walkthrough (or said "no Python"), emit the table below and stop — do not invoke shell tooling, read other sections, or run the bundled Python script. The microservice exposes an interactive OpenAPI UI at **`http://<HOST_IP>:<MS_PORT>/docs`**. If you prefer clicking through the API by hand: 1. Open `http://<HOST_IP>:<MS_PORT>/docs` in a browser. 2. Unzip `sdg_08_2_sample_data_010926.zip` into a cache directory next to it. 3. Execute these endpoints **in order**, copying the `project_id` from step 1 into subsequent paths: | # | Endpoint | Body / Files | |---|---|---| | 1 | `POST /v1/create_project` | `project_name`: any string | | 2 | `POST /v1/upload_video_files/{project_id}` | `files`: upload all 4 `videos/cam_0*.mp4` **sorted by name** | | 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}` | — (expect `project_state: READY`) | | 7 | `POST /v1/calibrate/{project_id}` | JSON: `{"detector_type": "resnet"}` | | 8 | `GET /v1/get_project_info/{project_id}` | Refresh every ~10 s until `project_state` = `COMPLETED` | | 9 | `GET /v1/result/{project_id}/evaluation_statistics` | Read L2 distance + reprojection error | | 10 optional | `POST /v1/vggt/calibrate/{project_id}` then `GET /v1/vggt_results/{project_id}/evaluation_statistics` | Run only when `vggt_state` is `READY`; poll `vggt_state` until `COMPLETED` | This is the same sequence the bundled Python script runs, just executed manually. Step 10 is attempted by default when `vggt_state` is `READY`; otherwise it is skipped with setup guidance. ### Status Fields from `get_project_info` `project_info.project_state` is the AMC calibration lifecycle for the project. Poll it until it reaches `COMPLETED` (or stop on `ERROR`). `project_info.vggt_state` is a **per-project** VGGT refinement lifecycle, a project-scoped status rather than a direct global service or model-load status. A newly created project can report `vggt_state: "INIT"` even when the VGGT model is present and mounted. The expected lifecycle is `INIT` → `READY` after AMC calibration completes → `RUNNING` while VGGT refinement runs → `COMPLETED` (or `ERROR`). Interpret `INIT` on a new or uncalibrated project as normal project state. If AMC calibration is complete and the project remains in a non-ready VGGT state, confirm VGGT setup and model availability with the setup skill checks and service logs. ## Success Criteria - Project reaches `project_state == "COMPLETED"` within ~30 min. - `/v1/result/{id}/evaluation_statistics` returns non-empty `statistics` (GT was uploaded). - VGGT either runs to `vggt_state == "COMPLETED"` and reports `/v1/vggt_results/{id}/evaluation_statistics`, or is skipped with setup guidance because the project is not `READY` for VGGT. - No `ERROR` state encountered. Representative metrics for the sample (yours should be similar): ``` Average L2 distance(m) : < 1.5 Average reprojection error 0(px) : < 10 ``` ## Key Output Files (on the server) Results persist under `$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 # ← final calibration (use this) └── calibration.log ``` ## Monitoring Progress ```bash PROJECT_ID=<id_from_step_1> : "${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; } tail -F --retry "$REPO_ROOT/projects/project_${PROJECT_ID}/calibration.log" ``` Or stream MS logs: ```bash : "${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; } docker compose -f "$REPO_ROOT/compose/compose.yml" logs -f auto-magic-calib-ms ``` ## Troubleshooting | Issue | Fix | |---|---| | `requests` not installed | Install it before running the script: `python3 -m pip install requests` | | `[2] Uploaded N videos` where N >> 4 | `SAMPLE_DIR` resolved to the repo root (or another over-broad path) and `rglob("cam_*.mp4")` swept stale videos from `.cache/`, `projects/`, etc. Correct `SAMPLE_DIR`, then start a fresh project instead of trying to salvage the bad upload set. The script anchors on `videos/` and asserts `len(videos) <= 16` to fail loud | | `verify_project` returns state `!= READY` | Confirm all 4 videos + alignment + layout + GT uploaded; inspect `GET /v1/get_project_info/{id}` response | | Sample not extracted | `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 finds 0 files | Check wrapper-folder depth: `find <sample_dir> -name "cam_*.mp4"` | | Calibration times out (>60 min) | Check `calibration.log` for "insufficient tracklets"; see root `README.md` guidelines on input videos | | Upload returns 413 | Raise server upload limit, or split files (sample files are <200 MB total so this is unusual) | | Port scan finds no backend | Backend not running — run `amc-setup-calibration-stack` skill | ## Additional Sample Dataset The root `README.md` also documents `nv_warehouse_032326.zip`, a real-world warehouse dataset available from NGC. Download it with `ngc registry resource download-version "nvidia/amc-nv-warehouse"`; then use `amc-run-video-calibration`, upload `nv_warehouse_config.json` in the config step, and run with the `transformer` detector. It does not include ground-truth data.