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/sdg082sampledata_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 (sdg082sampledata_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/sdg082sampledata_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

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 AMCSAMPLESKILLDIR to the directory containing this SKILL.md, or run the command from that directory. Set REPOROOT to the AutoMagicCalib checkout resolved by amc-setup-calibration-stack; the script auto-detects a running backend on localhost ports 8000-8009 when BASEURL / MSPORT are not set, accepts BASEURL, MSPORT, SAMPLEDIR, and RUNVGGT 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://<HOSTIP>:<MSPORT>/docs. If you prefer clicking through the API by hand:

1. Open http://<HOSTIP>:<MSPORT>/docs in a browser.
2. Unzip sdg082sampledata_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:

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 getprojectinfo

projectinfo.projectstate is the AMC calibration lifecycle for the project. Poll it until it reaches COMPLETED (or stop on ERROR).

projectinfo.vggtstate 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 vggtstate == "COMPLETED" and reports /v1/vggtresults/{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 $REPOROOT/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

Additional Sample Dataset

The root README.md also documents nvwarehouse032326.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 nvwarehouseconfig.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 -->