Run end-to-end calibration on the shipped sample dataset (sdg_08_2_sample_data_010926.zip) against a running AMC microservice. Use when user says 'test sample dataset', 'run sample calibration', 'verify AMC install', or 'launch and test'.
Instrucciones de origen · Vista previa de solo lectura
name
amc-run-sample-calibration
description
Run end-to-end calibration on the shipped sample dataset (sdg_08_2_sample_data_010926.zip) against a running AMC microservice. Use when user says 'test sample dataset', 'run sample calibration', 'verify AMC install', or 'launch and test'.
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):
Run skills/amc-setup-calibration-stack/SKILL.md first.
Wait for /v1/ready to return OK.
Extract sample data (snippet below) — idempotent, safe to re-run.
Report final metrics + UI URL for manual inspection.
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):
Detect backend: scan ports 8000–8009 for a /v1/ready response.
If none → point to the setup skill.
Extract sample data if not already cached.
Run the bundled script.
Report metrics.
Detect Running Backend
MS_PORT=""for port in {8000..8009}; doif curl -s "http://localhost:$port/v1/ready" | grep -q '"code":0'; then
MS_PORT=$port; breakfidone
[ -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" ]; thenmkdir -p "$SAMPLE_DIR"
unzip -q "$SAMPLE_ZIP" -d "$SAMPLE_DIR"fils"$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"; doif [ -f "$candidate" ]; then
SCRIPT_PATH="$candidate"breakfidone
[ -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:
Open http://<HOST_IP>:<MS_PORT>/docs in a browser.
Unzip sdg_08_2_sample_data_010926.zip into a cache directory next to it.
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*.mp4sorted by name
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>/:
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
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.
