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
• Python 3 with requests available, or use the Swagger UI path below
  • The bundled script self-heals: if requests is missing it creates a throwaway venv under ${TMPDIR:-/tmp}/amc-sample-test-venv (nothing written to the repo)
  • If python3 -m venv itself fails with ensurepip not available: sudo apt install -y python3-venv python3-pip

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.
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

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)

: "${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 reads compose/.env from that checkout for the backend port, 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.

# 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

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:

: "${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	Inside a venv: python3 -m venv venv && ./venv/bin/pip install requests. If python3 -m venv fails: sudo apt install -y python3-venv python3-pip first
[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. Stop the run (POST /v1/stop_calibration/{id}), delete the project (DELETE /v1/delete_project/{id}), set SAMPLE_DIR explicitly to the extracted sample dir, re-run. 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.

Related Skills

• skills/amc-setup-calibration-stack/SKILL.md — launch MS + UI (prerequisite).
• skills/amc-run-video-calibration/SKILL.md — run calibration on your own pre-recorded MP4s.
• skills/amc-run-rtsp-calibration/SKILL.md — run calibration from live RTSP streams through VIOS capture.

Root README.md "Sample Data Setup" and "Calibration Workflow (UI)" sections cover the human-oriented path through the same sample.

<!-- signing marker -->