Objectif

Exécuter AutoMagicCalib de bout en bout sur des fichiers locaux, des flux RTSP ou le dataset exemple fourni, et (si nécessaire) déployer le microservice AMC.

Instructions

Suivez les tables de routage et les workflows étape par étape ci-dessous. Chaque section se terminant par workflow, quick start ou flow doit être exécutée de haut en bas. La documentation de référence détaillée se trouve dans references/ et les scripts d'aide se trouvent dans scripts/ — appelez-les via run_script quand la compétence pointe vers un script par nom.

Exemples

Les exemples complets de bout en bout sont conservés dans evals/ (chaque manifeste *.json contient un scénario exécutable) et en ligne dans les blocs curl par workflow ci-dessous. Lancez une évaluation Tier-3 avec nv-base validate <this-skill-dir> --agent-eval pour les rejouer.

Limitations

• Nécessite que le profil VSS correspondant / le microservice soit déployé et accessible depuis l'appelant.
• Les modèles hébergés sur NGC et les NIMs peuvent être soumis à des limitations de débit, des exigences de mémoire GPU et des restrictions de licence.
• Les limites de concurrence, de mémoire GPU et de stockage dépendent du matériel hôte et du fichier compose du profil.

Dépannage

• Erreur : l'appel REST retourne connexion refusée. Cause : le microservice cible n'est pas en cours d'exécution. Solution : sondez /docs ou /health ; redéployez via vss-deploy-profile ou la compétence vss-deploy-* correspondante.
• Erreur : HTTP 401/403 depuis les pulls NGC. Cause : NGC_CLI_API_KEY manquante/expirée. Solution : docker login nvcr.io et ré-exportez la clé avant de réessayer.
• Erreur : container OOM ou échec du chargement du modèle. Cause : mémoire GPU insuffisante pour le profil sélectionné. Solution : basculez vers une variante plus petite ou libérez les GPU via docker compose down.

VSS Generate Video Calibration

Exécutez AutoMagicCalib sur l'une des trois sources d'entrée et pilotez l'étalonnage via l'API REST du microservice. Le travail de résolution d'entrée diffère par source ; tout à partir de verify_project est identique et se trouve dans ce fichier. Choisissez la bonne référence du mode d'entrée et associez-la à la Queue d'étalonnage partagée ci-dessous.

Routage des entrées

Associez la demande de l'utilisateur à un mode, puis chargez la référence de ce mode pour la collecte d'entrée, les appels API spécifiques au mode et le script Python complet.

Règle de désambiguïsation : si l'utilisateur demande de lancer / déployer / configurer AMC (pas de verbe d'étalonnage) → deploy. S'il fournit des URLs RTSP → rtsp. S'il mentionne des fichiers locaux / un répertoire de vidéos → videos. S'il demande de vérifier l'installation ou de tester l'exemple groupé → sample-dataset. Intentions combinées (ex. "launch AMC and calibrate my videos") → parcourez deploy en premier, puis le mode d'étalonnage. En cas d'ambiguïté, demandez via AskUserQuestion.

Prérequis (partagés entre les modes d'étalonnage)

• Microservice AMC + UI en cours d'exécution. Si ce n'est pas le cas, parcourez references/deploy-auto-calibration-service.md en premier.
• Microservice accessible à http://<HOST_IP>:${VSS_AUTO_CALIBRATION_PORT:-8010}/v1/ready → {"code":0,...}.
• Python 3 avec requests installé (chaque référence de mode d'entrée inclut un fallback venv auto-réparant pour les exécutions directes).

Les prérequis spécifiques au mode (VIOS pour rtsp, zip exemple pour sample-dataset) se trouvent dans les références respectives.

Queue d'étalonnage partagée

La séquence vérifier → étalonner → sonder → résultats est identique quel que soit le mode d'entrée. Après que la référence spécifique au mode ait téléchargé les vidéos / ingéré les clips RTSP / téléchargé l'exemple groupé, exécutez cette queue.

Étape A — Vérifier le projet

POST /v1/verify_project/<project_id>

Réponse : {"project_state": "READY"} — doit être READY avant l'étalonnage. Si pas READY, revérifiez que les vidéos + alignement + disposition sont présents (soit via API soit via alignement manuel UI).

Étape B — Démarrer l'étalonnage

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

{"detector_type": "resnet"}   # ou "transformer"

detector_type est un paramètre /calibrate séparé — pas consommé par /v1/config/<id>. Si l'utilisateur a fourni un fichier de paramètres d'étalonnage, analysez-le pour "detector" / "detector_type" et utilisez cette valeur. Si pas de fichier de paramètres, demandez à l'utilisateur via AskUserQuestion :

• resnet — défaut, rapide.
• transformer — plus lent, meilleur avec occlusion importante.

L'étape UI 3 (Paramètres) ne couvre PAS le choix du détecteur ; ne présumez jamais que l'utilisateur en a choisi un dans l'UI.

Étape C — Sonder l'achèvement

GET /v1/get_project_info/<project_id>

Sondez toutes les 10 s. project_info.project_state :

Durée typique : 10–60 min (vos propres vidéos), 10–30 min (exemple groupé).

Étape D — Résultats

GET /v1/get_project_info/<project_id>                    # état du projet
GET /v1/result/<project_id>/evaluation_statistics        # uniquement si GT uploadé
GET /v1/amc/calibrate/<project_id>/log                   # log d'étalonnage

La réponse d'évaluation inclut Average L2 distance(m) et Average reprojection error 0(px).

Étape E — (Optionnel) Raffinement VGGT

Uniquement si vggt_state == "READY" dans les infos du projet (le modèle VGGT doit être organisé — voir references/deploy-auto-calibration-service.md Étape 2) :

POST /v1/vggt/calibrate/<project_id>
GET  /v1/get_project_info/<project_id>                    # sonder vggt_state
GET  /v1/vggt_results/<project_id>/evaluation_statistics  # métriques VGGT

Fichier de paramètres + Motif détecteur

Optionnel sur les trois modes. Quand l'utilisateur fournit un fichier de paramètres JSON (généralement exporté depuis UI Étape 3 Téléchargement), POST-le textuellement :

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

<contenu du fichier, posté tel quel>

Le fichier remplace ce que l'utilisateur aurait autrement affiné dans UI Étape 3 (rectification, ajustement de paquet, knobs d'évaluation, détecteur, …). Après un POST réussi, analysez également le fichier pour "detector" / "detector_type" — si c'est "resnet" ou "transformer", utilisez cette valeur pour l'appel /calibrate à l'étape B (le détecteur est un paramètre API séparé, pas consommé par /config).

Non-2xx est surfacé — ne tombez pas silencieusement en arrière. Ignorez complètement cet appel si l'utilisateur a choisi le chemin de fallback UI.

Motif de fallback UI

Quand les fichiers d'alignement / disposition ne sont pas sur le disque, dirigez l'utilisateur vers l'étape UI AMC appropriée :

• Paramètres manquants → "Ouvrez le projet UI <project_id>, allez à Étape 3 : Paramètres, affinez via la boîte de dialogue de paramètres (ou acceptez les valeurs par défaut), cliquez Enregistrer." Aussi : avant l'appel /calibrate, demandez à l'utilisateur via AskUserQuestion s'il faut utiliser le détecteur resnet ou transformer — l'Étape 3 ne couvre pas le choix du détecteur.
• Disposition manquante → "Ouvrez le projet UI <project_id>, allez à Étape 2 : Configuration vidéo, uploadez layout.png uniquement (NE re-uploadez PAS les vidéos — elles sont déjà attachées via API/RTSP), cliquez Enregistrer."
• Alignement manquant → "Ouvrez le projet UI <project_id>, allez à Étape 4 : Alignement, uploadez alignment_data.json ou marquez les points de correspondance sur la disposition, cliquez Enregistrer."

Attendez la confirmation de l'utilisateur. Pour l'alignement/disposition, vérifiez sur le disque avant de continuer :

# L'état du projet se trouve sous $VSS_APPS_DIR/services/auto-calibration/projects
# (le chemin monté en bind dans le conteneur MS dans
#  deploy/docker/services/auto-calibration/ms/compose.yml).
HOST_PROJECTS="${VSS_APPS_DIR}/services/auto-calibration/projects"

ls "$HOST_PROJECTS/project_<project_id>/manual_adjustment/"
# Attendu : alignment_data.json, layout.png

Critères de succès

• project_state == "COMPLETED" après le sondage.
• Si l'alignement manuel a été utilisé : ${VSS_APPS_DIR}/services/auto-calibration/projects/project_<id>/manual_adjustment/ contient alignment_data.json + layout.png.
• Si GT a été uploadé : l'évaluation retourne des seuils typiques (Average L2 distance(m) < 1,5, Average reprojection error 0(px) < 5 pour vos données ; < 10 pour l'exemple groupé).
• Pas d'état ERROR.

Fichiers de sortie clés

Sous ${VSS_APPS_DIR}/services/auto-calibration/projects/project_<project_id>/ :

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          # ← étalonnage final
└── calibration.log

Dépannage transversal

Les problèmes spécifiques au mode se trouvent dans le tableau de dépannage de chaque référence.

Pour les compétences en aval — Export MV3DT

Les consommateurs en aval (ex. une compétence Multi-View 3D Tracking appartenant à une autre équipe) récupèrent la sortie d'étalonnage au format MV3DT directement du microservice. Cette compétence retourne project_id ; la compétence en aval appelle :

GET /v1/result/{project_id}/mv3dt_result?result_type=amc
# Réponse : application/zip — mv3dt_output.zip contenant transforms.yml

Pour la sortie affinée VGGT (disponible uniquement si VGGT s'est exécuté à COMPLETED, voir Étape E) :

GET /v1/result/{project_id}/mv3dt_result?result_type=vggt
# Réponse : application/zip — vggt_mv3dt_output.zip

Flux de compétence en aval :

1. Appelez cette compétence avec les entrées de l'utilisateur ; capturez le project_id imprimé.
2. Attendez que la compétence retourne (elle sonde en interne jusqu'à COMPLETED).
3. GET /v1/result/{project_id}/mv3dt_result?result_type=amc — enregistrez le ZIP localement.
4. Si VGGT a aussi tourné, extrayez optionnellement ?result_type=vggt pour le MV3DT affiné.

Compétences associées

• vss-manage-video-io-storage — compétence de l'API VIOS ; uniquement le mode d'étalonnage rtsp dépend de VIOS étant accessible.

Les sections "Custom Dataset" et "Calibration Workflow (UI)" du README.md racine documentent les directives vidéo d'entrée et l'alternative pilotée par UI à ce flux API.

bump:1