Objectif

Exécuter AutoMagicCalib en bout en bout sur des fichiers locaux, des flux RTSP ou le dataset d'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 est conçue pour être exécutée de haut en bas. Les matériaux de référence détaillés se trouvent dans references/ ; chargez uniquement la référence nécessaire pour le mode d'entrée sélectionné.

Exemples

Les exemples bout en bout sont conservés sous evals/ (chaque manifeste *.json contient un scénario exécutable) et en ligne dans les blocs curl de chaque workflow ci-dessous. Exécutez une évaluation de 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 limites 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 connection refused. 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 skill 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 : OOM du conteneur ou échec du chargement du modèle. Cause : mémoire GPU insuffisante pour le profil sélectionné. Solution : passez à une variante plus petite ou libérez les GPUs 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 selon la source ; tout ce qui suit verify_project est identique et se trouve dans ce fichier. Choisissez la référence du mode d'entrée approprié et associez-la à la Queue d'étalonnage partagée ci-dessous.

Les références d'aide partagées sont chargées uniquement si nécessaire :

• Lisez references/common-steps.md quand une référence de mode a besoin des extraits partagés create_project, video-upload ou handoff.
• Lisez references/calibration-tail.md quand vous avez besoin de l'implémentation Python réutilisable de la queue verify → calibrate → poll → results.

Routage d'entrée

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 tester l'exemple fourni → sample-dataset. Intents combinées (p. ex. « launch AMC and calibrate my videos ») → parcourez d'abord deploy, puis le mode d'étalonnage. En cas d'ambiguïté, demandez via AskUserQuestion.

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

• Microservice + UI AMC en cours d'exécution. Si non, parcourez d'abord references/deploy-auto-calibration-service.md.
• Microservice accessible via http://<HOST_IP>:${VSS_AUTO_CALIBRATION_PORT:-8010}/v1/ready → {"code":0,...}.
• Répertoire de projets accessible en écriture par l'utilisateur du conteneur. Si vous ne venez pas de déployer (donc l'étape 5 de la référence de déploiement n'a pas été exécutée), confirmez le test d'écriture dans references/deploy-auto-calibration-service.md § Étape 5 — sinon le premier create_project retourne [Errno 13] Permission denied.
• Python 3 avec requests installé (chaque référence de mode d'entrée inclut un fallback venv d'auto-guérison pour les exécutions directes).

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

Queue d'étalonnage partagée

La séquence verify → calibrate → poll → results 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 fourni, exécutez cette queue. Utilisez references/calibration-tail.md pour l'extrait Python partagé.

É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 + layout sont présents (soit via l'API, soit via l'alignement manuel UI).

Étape B — Démarrer l'étalonnage

Confirmez le plan avant l'étalonnage. Que le fichier de paramètres et le détecteur aient été détectés automatiquement ou demandés, présentez un court résumé et confirmez via AskUserQuestion avant le POST /calibrate. Les valeurs résolues sont les valeurs par défaut, donc la confirmation est un clic — mais l'utilisateur peut changer de détecteur ou ignorer un fichier de paramètres détecté automatiquement. Résumez :

• Détecteur — resnet ou transformer (la valeur à envoyer).
• Paramètres d'étalonnage — le fichier appliqué (chemin), ou les paramètres par défaut (avec l'option de les ajuster d'abord dans l'UI — voir ci-dessous).
• Overrides optionnelles — zip de vérité terrain et longueurs focales, le cas échéant.

L'exécution de vérification d'installation du dataset d'exemple utilise un resnet fixe et peut procéder sans cette confirmation.

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

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

detector_type est un paramètre /calibrate séparé — non 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 le fichier n'en spécifie pas un, la valeur par défaut (resnet) est la valeur affichée dans le résumé ci-dessus — l'utilisateur peut la changer là avant l'étalonnage. S'il n'y a pas de fichier de paramètres du tout, demandez à l'utilisateur via AskUserQuestion :

• resnet — par défaut, rapide.
• transformer — plus lent, meilleur en cas d'occlusion importante.

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

Aussi quand il n'y a pas de fichier de paramètres, demandez si vous devez d'abord ajuster les paramètres d'étalonnage (AskUserQuestion) :

• Procéder avec les paramètres par défaut — bien adaptés aux scènes d'entrepôt typiques ; recommandé sauf si l'utilisateur a un ajustement spécifique en tête.
• Ajuster les paramètres dans l'UI d'abord — ouvrez le projet, allez à l'étape 3 : Paramètres, modifiez les valeurs et cliquez sur Enregistrer ; puis continuez.

Attendez le choix de l'utilisateur — et, s'il choisit d'ajuster, pour qu'il confirme qu'il a enregistré — avant d'appeler /calibrate.

Étape C — Interroger la fin

GET /v1/get_project_info/<project_id>

Interrogez toutes les 10 s. project_info.project_state :

Quand l'étalonnage démarre, affichez l'ID du projet, l'URL de l'UI (http://<HOST_IP>:${VSS_AUTO_CALIBRATION_UI_PORT:-5000}) et l'endpoint du log afin que l'utilisateur puisse surveiller la progression pendant l'exécution. Pendant RUNNING, émettez une ligne de progression au moins une fois par minute avec le temps écoulé pour qu'une longue exécution ne semble pas bloquée. Sur ERROR, récupérez et affichez les dernières lignes de GET /v1/amc/calibrate/<id>/log avant d'arrêter. Les logs live peuvent également être diffusés en continu via GET /v1/calibrate/<project_id>/log/<type>/stream.

Temps typique : 10–60 min (vos propres vidéos), 10–30 min (exemple fourni).

Étape D — Résultats

GET /v1/get_project_info/<project_id>                    # état du projet
GET /v1/result/<project_id>/evaluation_statistics        # seulement si GT téléchargée
GET /v1/result/<project_id>/overlay_image                # surimpression visuelle (PNG)
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). Les métriques d'évaluation sont produites uniquement quand un GT.zip de vérité terrain a été téléchargé — un résultat evaluation_statistics manquant est normal sinon et n'est pas la fin du rapport de résultats.

Après COMPLETED, donnez toujours à l'utilisateur un moyen d'examiner le résultat pour ce projet exact, indépendamment de l'existence des métriques :

• UI — http://<HOST_IP>:${VSS_AUTO_CALIBRATION_UI_PORT:-5000} ; ouvrez le projet, puis la page Résultats pour afficher la surimpression.
• Image de surimpression sur disque — ${VSS_APPS_DIR}/services/auto-calibration/projects/project_<id>/output/multi_view_results/BA_output/results_ba_scaled_world/overlay_img_*.png (les projets monocaméra utilisent output/single_view_results/cam_00/verification_map_overlay.png).
• Fichiers du projet — ${VSS_APPS_DIR}/services/auto-calibration/projects/project_<id>/.

Étape E — Raffinement VGGT

Après la fin de l'exécution AMC, vérifiez toujours vggt_state dans les infos du projet. La préparation du modèle VGGT est optionnelle pendant la configuration et ne doit pas bloquer le résultat AMC, mais la gestion post-AMC suit l'état :

• Si vggt_state == "READY" et l'utilisateur a explicitement demandé le raffinement VGGT ou préparé VGGT pendant ce flux de configuration, exécutez le raffinement VGGT sans demander à nouveau.
• Si vggt_state == "READY" mais VGGT a déjà été préparé avant cette demande et l'utilisateur n'a pas demandé la sortie affinée VGGT, demandez via AskUserQuestion si vous devez exécuter le raffinement avant de le démarrer.
• Si VGGT n'est pas prêt, ignorer le raffinement et mentionner que le raffinement VGGT est disponible après préparation du modèle (voir references/deploy-auto-calibration-service.md Étape 2).

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

Motif Fichier de paramètres + Détecteur

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

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

<contenu du fichier, posté tel quel>

Le fichier remplace ce que l'utilisateur ajusterait sinon dans l'UI Étape 3 (rectification, bundle-adjustment, boutons d'évaluation, détecteur, …). Après un POST réussi, aussi analysez 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é, non consommé par /config).

Non-2xx est affiché — ne faites pas de fallback silencieux. Ignorez complètement cet appel si l'utilisateur a choisi le chemin de fallback UI.

Motif Fallback UI

Quand les fichiers d'alignement / layout ne sont pas sur 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, ajustez via la boîte de dialogue des paramètres (ou acceptez les défauts), cliquez sur Enregistrer. » Aussi : avant l'appel /calibrate, demandez à l'utilisateur via AskUserQuestion s'il doit utiliser le détecteur resnet ou transformer — l'étape 3 ne couvre pas le choix du détecteur.
• Layout manquant → « Ouvrez le projet UI <project_id>, allez à Étape 2 : Configuration vidéo, téléchargez layout.png uniquement (ne téléchargez PAS les vidéos à nouveau — elles sont déjà attachées via l'API/RTSP), cliquez sur Enregistrer. »
• Alignement manquant → « Ouvrez le projet UI <project_id>, allez à Étape 4 : Alignement, téléchargez soit alignment_data.json soit marquez les points de correspondance sur le layout, cliquez sur Enregistrer. »

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

# L'état du projet se trouve sous $VSS_APPS_DIR/services/auto-calibration/projects
# (le chemin lié au 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 l'interrogation.
• 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é téléchargée : 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 fourni).
• 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
│   └── multi_view_results/BA_output/results_ba_scaled_world/
│       └── overlay_img_XX.png               # ← surimpression visuelle pour examen
└── calibration.log

Dépannage transversal

Les problèmes spécifiques au mode se trouvent dans la table de dépannage propre à chaque référence.

Pour les skills en aval — Export MV3DT

Les consommateurs en aval (p. ex. une skill Multi-View 3D Tracking détenue par une autre équipe) récupèrent la sortie d'étalonnage au format MV3DT directement depuis le microservice. Cette skill retourne le project_id ; la skill 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ée jusqu'à COMPLETED, voir étape E) :

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

Flux de skill en aval :

1. Appelez cette skill avec les entrées de l'utilisateur ; capturez le project_id imprimé.
2. Attendez que la skill retourne (elle interroge jusqu'à COMPLETED en interne).
3. GET /v1/result/{project_id}/mv3dt_result?result_type=amc — enregistrez le ZIP localement.
4. Si VGGT s'est aussi exécutée, récupérez optionnellement ?result_type=vggt pour le MV3DT affiné.

Skills associées

• vss-manage-video-io-storage — skill API VIOS ; seul le mode d'étalonnage rtsp dépend de la disponibilité de VIOS.

Le README.md racine, sections « Custom Dataset » et « Calibration Workflow (UI) » documentent les directives vidéo d'entrée et l'alternative pilotée par l'UI pour ce flux API.

bump:1