Skill : Calibrer à partir de flux RTSP

Quand utiliser cette skill

Activez cette skill quand l'utilisateur souhaite calibrer à partir de flux de caméras RTSP en direct. Prompts typiques :

• « calibrate RTSP streams » / « calibrer à partir de caméras en direct »
• « run AMC on RTSP »
• L'utilisateur fournit une ou plusieurs URLs rtsp://...

VIOS enregistre des clips de durée fixe à partir de chaque flux, le microservice AMC ingère ces clips dans un projet, puis le workflow suit le même chemin de vérification, calibration, polling et résultats que la calibration MP4 pré-enregistrée.

N'utilisez pas cette skill pour les fichiers MP4 locaux déjà sur disque ; routez ces demandes vers skills/amc-run-video-calibration/SKILL.md. Ne l'utilisez pas pour le dataset exemple fourni ; routez cela vers skills/amc-run-sample-calibration/SKILL.md.

Ne réutilisez jamais les fichiers du dataset exemple fourni, du zip exemple extrait, de assets/, ou de projets antérieurs pour la calibration RTSP sauf si l'utilisateur fournit explicitement ces chemins pour cette scène RTSP. Des noms de caméra similaires, des nombres de flux identiques, ou un ordre cam_00/cam_01 ne sont pas des indices que l'alignement exemple, la disposition, la GT, ou les paramètres détecteur s'appliquent.

Prérequis

• [ ] Microservice AMC et UI en cours d'exécution (suivez skills/amc-setup-calibration-stack/SKILL.md si nécessaire).
• [ ] VIOS est en cours d'exécution et accessible depuis le microservice AMC.
• [ ] VIOS_BASE_URL est configuré dans l'environnement du microservice AMC avant le démarrage de la capture.
• [ ] Les URLs RTSP sont accessibles depuis l'hôte VIOS.
• [ ] Les flux de caméra ont suffisamment de personnes/objets en mouvement pour la calibration ; enregistrez au moins 2-3 minutes si possible.
• [ ] Python 3 avec requests installé lors de l'utilisation du script fourni.

Confidentialité des données

Les URLs RTSP peuvent contenir des noms d'utilisateur, des mots de passe, des noms d'hôte ou une topologie réseau. N'imprimez pas les URLs RTSP complètes si des identifiants sont incorporés. Passez les tokens VIOS via des variables d'environnement ou des prompts de terminal sécurisés ; n'affichez pas les tokens dans le chat, les logs ou les réponses finales.

Questions à poser à l'utilisateur

Obligatoires

1. URLs RTSP, une par caméra.
2. Noms de caméra, un par flux. Utilisez cam_00, cam_01, ... si l'utilisateur ne fournit pas de noms.
3. Durée d'enregistrement en secondes. Le minimum est 60 ; préférez 120-180 ou plus quand la scène a peu de mouvement.
4. URL du microservice, par exemple http://<HOST_IP>:8000 ou http://<HOST_IP>:8000/v1.
5. Nom du projet.
6. Source d'asset de calibration pour cette scène RTSP :
   • un répertoire local à parcourir, par exemple /data/my_rtsp_calib/ ;
   • des chemins explicites vers les fichiers de paramètres, alignement, disposition et optionnel GT ; ou
   • confirmation que l'utilisateur téléversera/ajustera les paramètres et l'alignement dans l'UI AMC.

Si l'utilisateur ne fournit pas de source d'asset locale, arrêtez-vous et demandez s'il souhaite fournir un chemin ou utiliser le téléversement UI. Donnez le lien UI comme http://<HOST_IP>:<AUTO_MAGIC_CALIB_UI_PORT> ; le port UI par défaut est 5000.

Auto-détecté ou demandé

Les clips RTSP sont enregistrés par VIOS, il n'y a donc pas de répertoire vidéos local pour ancrer la découverte de fichiers. Scannez uniquement un répertoire fourni explicitement par l'utilisateur pour cette scène RTSP. Si l'utilisateur fournit un chemin de fichier de paramètres, utilisez le répertoire de ce fichier comme répertoire de scan. Si l'utilisateur fournit un répertoire d'asset de calibration, scannez uniquement ce répertoire. Sinon posez cette question avant de planifier les téléversements ou la calibration :

Avez-vous un répertoire d'asset de calibration locale ou un fichier de paramètres pour ces flux RTSP, ou devriez-vous téléverser/ajuster les paramètres et l'alignement dans l'UI AMC à http://<HOST_IP>:<AUTO_MAGIC_CALIB_UI_PORT> ?

Poster le fichier de paramètres remplace l'UI Étape 3 et peut fixer detector ou detector_type. S'il fixe resnet ou transformer, passez ce même détecteur à /calibrate. Si aucun fichier de paramètres ne fixe un détecteur, demandez à l'utilisateur quel détecteur utiliser ; ne défaut pas silencieusement à resnet.

Optionnels

6. sensor_id par flux si les caméras sont déjà enregistrées dans VIOS. Laissez non défini pour l'auto-enregistrement.
7. Ground truth zip (GT.zip) pour les métriques d'évaluation.
8. Distances focales, une par caméra.
9. Token porteur VIOS, si le déploiement VIOS en requiert un.
10. Que exécuter l'affinage VGGT après la fin d'AMC, uniquement quand le projet rapporte vggt_state == "READY".

Instructions

Le script fourni dans scripts/run_rtsp_calibration.py implémente cette séquence de bout en bout. Utilisez le texte ci-dessous pour les décisions, le fallback UI et le dépannage.

Étape 0 - Vérifier AMC et VIOS

Confirmez que le microservice AMC est accessible :

curl -sf http://<HOST_IP>:<MS_PORT>/v1/ready

Confirmez que VIOS est accessible avant de démarrer la capture. Sondez dans cet ordre et arrêtez à la première URL fonctionnelle :

: "${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; }
VIOS_BASE_URL=""

# Default local VIOS port.
if curl -sf http://localhost:30888/vst/api/v1/sensor/list >/dev/null 2>&1; then
  HOST_IP=$(grep ^HOST_IP "$REPO_ROOT/compose/.env" 2>/dev/null | cut -d= -f2)
  VIOS_BASE_URL="http://${HOST_IP:-localhost}:30888"
  echo "VIOS detected at $VIOS_BASE_URL"
fi

# Running AMC microservice container environment.
if [ -z "$VIOS_BASE_URL" ]; then
  VIOS_BASE_URL=$(docker exec auto-magic-calib-ms-1 printenv VIOS_BASE_URL 2>/dev/null)
fi

# Compose environment file.
if [ -z "$VIOS_BASE_URL" ]; then
  VIOS_BASE_URL=$(grep ^VIOS_BASE_URL "$REPO_ROOT/compose/.env" 2>/dev/null | cut -d= -f2-)
fi

if [ -n "$VIOS_BASE_URL" ]; then
  curl -sf "${VIOS_BASE_URL}/vst/api/v1/sensor/list" >/dev/null \
    && echo "VIOS up at $VIOS_BASE_URL" \
    || { echo "VIOS_BASE_URL=$VIOS_BASE_URL is set but not responding"; VIOS_BASE_URL=""; }
fi

Si VIOS n'est pas accessible, demandez à l'utilisateur de déployer VIOS et de fournir l'URL de base. Ne démarrez pas la capture RTSP jusqu'à ce que ${VIOS_BASE_URL}/vst/api/v1/sensor/list retourne 200.

Si VIOS est accessible mais le microservice AMC ne dispose pas de VIOS_BASE_URL, ne modifiez pas les fichiers compose checked-in. Exportez la variable et relancez le microservice avec un override de compose temporaire :

cd "$REPO_ROOT/compose"
export VIOS_BASE_URL="http://<VIOS_HOST>:30888"
OVERRIDE_FILE="${TMPDIR:-/tmp}/amc-vios.override.yml"
cat > "$OVERRIDE_FILE" <<'YAML'
services:
  auto-magic-calib-ms:
    environment:
      - VIOS_BASE_URL=${VIOS_BASE_URL}
YAML

docker compose -f compose.yml -f "$OVERRIDE_FILE" up -d auto-magic-calib-ms
docker exec auto-magic-calib-ms-1 printenv VIOS_BASE_URL

Une export du shell hôte seule ne suffit pas après que le conteneur soit déjà en cours d'exécution ; le processus du microservice doit être relancé avec VIOS_BASE_URL dans son environnement.

Étape 1 - Créer un projet

POST /v1/create_project avec champ de formulaire project_name. Enregistrez le project_id retourné.

Étape 2 - Démarrer la capture RTSP

POST /v1/rtsp/capture/<project_id>
Content-Type: application/json

{
  "streams": [
    {"rtsp_url": "rtsp://...", "camera_name": "cam_00", "sensor_id": null},
    {"rtsp_url": "rtsp://...", "camera_name": "cam_01", "sensor_id": null}
  ],
  "duration_seconds": 180,
  "vios_token": null,
  "ssl_verify": false
}

La réponse peut imbriquer les champs de session sous session :

{"code": 0, "message": "...", "session": {"session_id": "...", "status": "STARTING"}}

Enregistrez session.session_id.

Étape 3 - Poller la capture, puis ingérer

Pollez toutes les 10 secondes :

GET /v1/rtsp/capture/<project_id>/<session_id>

Cycle de vie de la session :

STARTING -> RECORDING -> COMPLETED -> INGESTING -> INGESTED
                       -> ERROR
RECORDING -> CANCELLED

Quand la capture atteint COMPLETED, ingérez les clips enregistrés dans le projet AMC :

POST /v1/rtsp/capture/<project_id>/<session_id>/ingest

Après succès d'ingest, le projet a les fichiers vidéo attachés et le reste du workflow correspond au chemin MP4 upload.

Besoin d'arrêter tôt : POST /v1/rtsp/capture/<project_id>/<session_id>/stop. Un clip partiel peut toujours être ingéré si VIOS en a produit un.

Autres endpoints de session :

• GET /v1/rtsp/sessions/<project_id> - lister les sessions d'un projet.
• DELETE /v1/rtsp/session/<project_id>/<session_id> - supprimer un enregistrement de session.

Étape 4 - Téléverser paramètres, alignement, disposition et fichiers optionnels

Résolvez les fichiers locaux en utilisant le motif anchor-file ci-dessus. Téléversez les fichiers résolus :

Utilisez uniquement les fichiers à partir de chemins explicites fournis par l'utilisateur ou d'un répertoire d'asset de calibration fourni par l'utilisateur. N'extrayez pas ou ne scannez pas les données exemple pour trouver les paramètres de fallback, l'alignement, la disposition ou la GT.

Si les paramètres sont manquants, dirigez l'utilisateur vers l'UI Étape 3 : Paramètres à http://<HOST_IP>:<AUTO_MAGIC_CALIB_UI_PORT>, puis demandez quel détecteur utiliser (resnet ou transformer) avant la calibration. Si l'alignement ou la disposition est manquant, dirigez l'utilisateur vers l'UI Étape 4 : Alignement pour ce projet. Pour les projets RTSP, les vidéos sont déjà ingérées ; ne retéléversez pas les vidéos dans le fallback UI.

Avant de continuer après l'UI Étape 4, vérifiez :

PROJECT_ID=<project_id>
: "${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; }
PROJECT_DIR_REL=$(grep ^PROJECT_DIR "$REPO_ROOT/compose/.env" 2>/dev/null | cut -d= -f2 | tr -d '[:space:]')
HOST_PROJECTS=$(cd "$REPO_ROOT/compose" && realpath "${PROJECT_DIR_REL:-../../projects}")
ls "$HOST_PROJECTS/project_${PROJECT_ID}/manual_adjustment/"
# Expected: alignment_data.json, layout.png

Étape 5 - Vérifier, calibrer, poller et récupérer les résultats

Vérifiez :

POST /v1/verify_project/<project_id>

Le projet doit retourner project_state == "READY".

Confirmez le plan avant de calibrer. Résumez :

• Nombre de flux et durée d'enregistrement.
• Détecteur : resnet ou transformer.
• Source des paramètres : fichier de paramètres téléversé explicite, répertoire d'asset fourni par l'utilisateur, ou UI Étape 3.
• Source d'alignement/disposition : fichiers téléversés explicites, répertoire d'asset fourni par l'utilisateur, ou ajustement manuel UI.
• Overrides GT et distances focales optionnels.

Démarrez la calibration :

POST /v1/calibrate/<project_id>
Content-Type: application/json

{"detector_type": "<resnet-or-transformer>"}

Pollez :

GET /v1/get_project_info/<project_id>

Arrêtez sur COMPLETED ou ERROR. En cas d'erreur, récupérez GET /v1/amc/calibrate/<project_id>/log.

Récupérez les résultats :

GET /v1/result/<project_id>/evaluation_statistics

Attendez uniquement les statistiques d'évaluation quand la GT a été téléversée.

Étape 6 - Affinage VGGT optionnel

Après la fin de la calibration AMC, lisez project_info.vggt_state depuis GET /v1/get_project_info/<project_id>.

• Si vggt_state == "READY", demandez s'il faut exécuter l'affinage VGGT.
• Si confirmé, appelez POST /v1/vggt/calibrate/<project_id>, pollez vggt_state, puis récupérez GET /v1/vggt_results/<project_id>/evaluation_statistics.
• Si VGGT n'est pas prêt, passez-le et expliquez que la calibration AMC est complète.

Script Python complet

Utilisez le script fourni à partir du package de skill amc-run-rtsp-calibration, pas à partir de la racine du repo auto-magic-calib. Si l'utilisateur pointe l'agent vers ce dossier de skill directement au lieu de l'installer, définissez AMC_RTSP_SKILL_DIR au répertoire contenant ce SKILL.md, ou exécutez la commande à partir de ce répertoire.

Variables d'environnement communes :

export BASE_URL=http://<HOST_IP>:8000
export PROJECT_NAME=rtsp_calibration_run
export RTSP_URLS='rtsp://user:pass@cam0/stream,rtsp://user:pass@cam1/stream'
export CAMERA_NAMES='cam_00,cam_01'
export DURATION_SECONDS=180
export VIOS_BASE_URL=http://<VIOS_HOST>:30888
export CALIB_ASSET_DIR=/path/to/rtsp-calibration-assets
# Or provide explicit CONFIG_FILE, ALIGNMENT_JSON, LAYOUT_PNG, and optional GT_ZIP.
export DETECTOR_TYPE=transformer  # Required when settings do not set detector/detector_type.
export AMC_UI_URL=http://<HOST_IP>:5000
export RUN_VGGT=false

# Optional but recommended: REPO_ROOT points to the auto-magic-calib checkout.
# PROJECTS_DIR can be set explicitly when project outputs live elsewhere.
if [ -z "${DEEPSTREAM_REPO_ROOT:-}" ] && [ -n "${REPO_ROOT:-}" ] && [ -d "$REPO_ROOT/../../skills/amc-run-rtsp-calibration" ]; then
  DEEPSTREAM_REPO_ROOT="$(cd "$REPO_ROOT/../.." && pwd)"
fi

SCRIPT_PATH=""
for candidate in \
  "${AMC_RTSP_SKILL_DIR:+$AMC_RTSP_SKILL_DIR/scripts/run_rtsp_calibration.py}" \
  "$PWD/scripts/run_rtsp_calibration.py" \
  "${DEEPSTREAM_REPO_ROOT:+$DEEPSTREAM_REPO_ROOT/skills/amc-run-rtsp-calibration/scripts/run_rtsp_calibration.py}" \
  "$PWD/skills/amc-run-rtsp-calibration/scripts/run_rtsp_calibration.py" \
  "$HOME/.claude/skills/amc-run-rtsp-calibration/scripts/run_rtsp_calibration.py" \
  "$HOME/.codex/skills/amc-run-rtsp-calibration/scripts/run_rtsp_calibration.py" \
  "$HOME/.cursor/skills/amc-run-rtsp-calibration/scripts/run_rtsp_calibration.py"; do
  if [ -f "$candidate" ]; then
    SCRIPT_PATH="$candidate"
    break
  fi
done

[ -n "$SCRIPT_PATH" ] || {
  echo "ERROR: could not find amc-run-rtsp-calibration/scripts/run_rtsp_calibration.py" >&2
  echo "Set AMC_RTSP_SKILL_DIR to the amc-run-rtsp-calibration skill directory, or run this block from that directory." >&2
  exit 1
}

python3 "$SCRIPT_PATH"

Entrée de flux alternative :

export STREAMS_JSON='[
  {"rtsp_url":"rtsp://cam0/stream","camera_name":"cam_00","sensor_id":null},
  {"rtsp_url":"rtsp://cam1/stream","camera_name":"cam_01","sensor_id":null}
]'

Les env vars optionnels sont CALIB_ASSET_DIR, CONFIG_FILE, ALIGNMENT_JSON, LAYOUT_PNG, GT_ZIP, FOCAL_LENGTHS, DETECTOR_TYPE, AMC_UI_URL, VIOS_TOKEN, SSL_VERIFY, RUN_VGGT, REPO_ROOT, et PROJECTS_DIR.

Critères de succès

• La sonde de santé VIOS retourne 200.
• La session de capture atteint COMPLETED.
• Ingest retourne le succès et les info de projet affichent les fichiers vidéo attendus.
• verify_project retourne READY.
• La calibration AMC atteint project_state == "COMPLETED".
• Si la GT a été téléversée, les statistiques d'évaluation sont retournées.
• Aucune identifiant RTSP, token porteur, clé NGC ou token HuggingFace ne sont imprimés ou persistés par l'agent.

Fichiers de sortie clés

Les résultats persistent sur le serveur AMC sous :

projects/project_<project_id>/
|-- manual_adjustment/
|   |-- alignment_data.json
|   `-- layout.png
|-- output/
|   |-- single_view_results/cam_XX/
|   |   |-- camInfo_hyper_XX.yaml
|   |   `-- trajDump_Stream_0_3d.txt
|   `-- multi_view_results/BA_output/results_ba/
|       |-- initial/camInfo_XX.yaml
|       `-- refined/camInfo_XX.yaml
`-- calibration.log

Dépannage

Skills connexes

• skills/amc-setup-calibration-stack/SKILL.md - démarrer le microservice AMC et l'UI en premier.
• skills/amc-run-video-calibration/SKILL.md - calibrer à partir de fichiers MP4 pré-enregistrés locaux.
• skills/amc-run-sample-calibration/SKILL.md - vérifier la pile avec le dataset exemple fourni.

<!-- signing marker -->