Objectif

Exécuter AutoMagicCalib de 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 tableaux de routage et les flux de travail étape par étape ci-dessous. Chaque section se terminant par workflow, quick start ou flow est destinée à être exécutée de haut en bas. La documentation de référence détaillée se trouve dans references/ ; chargez uniquement la référence nécessaire pour le mode d'entrée sélectionné.

Exemples

Les exemples 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. Exécutez une évaluation Tier-3 avec nv-base validate <this-skill-dir> --agent-eval pour les rejouer.

Limitations

• Nécessite le profil VSS correspondant / le microservice à déployer 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 connexion refusée. Cause : le microservice cible n'est pas en cours d'exécution. Solution : vérifiez /docs ou /health ; redéployez via vss-deploy-profile ou la skill vss-deploy-* correspondante.
• Erreur : HTTP 401/403 à partir des pulls NGC. Cause : NGC_CLI_API_KEY manquant/expiré. Solution : docker login nvcr.io et réexportez la clé avant de réessayer.
• Erreur : conteneur OOM ou le modèle ne charge pas. 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 sur la résolution d'entrée diffère selon la 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.

Les références d'assistance partagées sont chargées uniquement en cas de besoin :

• Lisez references/common-steps.md quand une référence de mode a besoin des extraits partagés create_project, chargement vidéo ou handoff.
• Lisez references/calibration-tail.md quand vous avez besoin de l'implémentation Python réutilisable de la queue stage-linear-media → verify → VGGT/post-process → AMC/post-process → compare-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 URL 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 fourni → sample-dataset. Intentions combinées (par ex. « launch AMC and calibrate my videos ») → parcourez d'abord deploy, puis le mode d'étalonnage. En cas d'ambiguïté, posez la question via AskUserQuestion.

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

• Le préflight de plateforme de references/deploy-auto-calibration-service.md Étape 0 est réussi avant tout déploiement AMC ou travail d'API d'étalonnage. L'hôte d'étalonnage a besoin d'Ubuntu 24.04 sur x86_64, du pilote NVIDIA 590 ou plus récent, d'un accès GPU NVIDIA et du support du codeur matériel NVENC. Si le préflight échoue, arrêtez immédiatement, indiquez à l'utilisateur quelle exigence n'a pas été satisfaite, et demandez-lui de fournir un calibration.json existant, d'exécuter l'étalonnage sur un hôte dGPU x86_64 supporté, ou de transférer les artefacts d'étalonnage générés. Ne poursuivez pas la configuration AMC, la vérification VIOS, la capture, le chargement ou l'étalonnage automatiquement. DGX Spark est aarch64, donc utilisez les artefacts existants/générés pour ce flux.
• Microservice AMC + UI en cours d'exécution. Si ce n'est pas le cas, parcourez d'abord references/deploy-auto-calibration-service.md.
• Microservice accessible à http://<HOST_IP>:${VSS_AUTO_CALIBRATION_HOST_PORT:-8010}/v1/ready → {"code":0,...}.
• Répertoire de projets accessible en écriture par l'utilisateur du conteneur. Si vous n'avez pas déployé récemment (ainsi 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 du mode d'entrée inclut un secours venv auto-réparable 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. Le préflight de plateforme s'applique même quand un service AMC est déjà en cours d'exécution.

Queue d'étalonnage partagée

La séquence partagée est stage-linear-media → verify → VGGT (quand prêt) → post-process → AMC → post-process → results. Après que la référence spécifique au mode a chargé des vidéos / complété l'ingestion RTSP automatiquement / chargé l'exemple fourni, exécutez cette queue. Utilisez references/calibration-tail.md pour l'extrait Python partagé.

Séquence UI AMC : Étape 1 Project Setup, Étape 2 Video Configuration, Étape 3 Parameters, Étape 4 Rectification, Étape 5 Manual Alignment, Étape 6 Execute, Étape 7 Results.

Étape A — Stage Linear Media

AMC v3.3.0 ne peut pas étalonner les médias bruts. Après que le flux de travail spécifique au mode a chargé des vidéos ou complété l'ingestion RTSP, choisissez explicitement un chemin avant la vérification :

• Médias déjà linéaires/sténopéiques — appelez POST /v1/linear_media/<project_id> et nécessitez rectification_state == "COMPLETED".
• Médias distordus — ouvrez AMC UI Étape 4 : Rectification ; sélectionnez Auto, Manual ou Videos Are Rectified ; vérifiez l'estimation ; puis cliquez sur Generate Rectified Videos. Auto supporte simple_divisional (par défaut), simple_radial et radial ; Manual supporte model, k1 et k2 par caméra pour radial. READY_FOR_REVIEW n'est pas complet : nécessitez rectification_state == "COMPLETED" avant de continuer. La re-rectification invalide la vérification, l'étalonnage et les sorties de post-traitement.

La rectification produit rectified.mp4 et rectified.jpg. Les fichiers d'alignement externes utilisent normalement coord_space=original ; utilisez rectified uniquement pour les points créés sur les médias rectifiés AMC. N'appelez jamais /v1/calibrate/<project_id> avant que l'état linear-media ou rectification soit complet.

Étape B — Vérifier le projet

POST /v1/verify_project/<project_id>

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

Étape C — Étalonnage VGGT indépendant

Après la vérification et avant AMC, inspectez vggt_state. Démarrez VGGT par défaut depuis READY, reprenez et attendez depuis RUNNING, et toujours post-traitez un résultat multi-caméra COMPLETED, y compris un complété avant l'invocation actuelle. MODEL_MISSING ou ERROR est signalé comme un secours AMC uniquement. Vérifiez amc_state, vggt_state et postprocess_state indépendamment.

POST /v1/vggt/calibrate/<project_id>
GET  /v1/get_project_info/<project_id>                    # poll vggt_state
POST /v1/postprocess/<project_id>                          # multi-camera only, after VGGT
GET  /v1/get_project_info/<project_id>                    # require postprocess_state == COMPLETED
GET  /v1/vggt_results/<project_id>/evaluation_statistics  # VGGT metrics when GT exists

Étape D — Démarrer l'étalonnage AMC

Confirmez le plan avant d'étalonner. Que le fichier de paramètres et le détecteur aient été auto-détectés 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 basculer le détecteur ou ignorer un fichier de paramètres auto-détecté. Résumez :

• Détecteur — resnet ou transformer (la valeur à envoyer).
• Paramètres d'étalonnage — le fichier appliqué (chemin), ou paramètres par défaut (avec l'option de les ajuster d'abord dans l'UI — voir ci-dessous).
• Overrides optionnels — zip de vérité sol 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 continuer 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, la valeur par défaut (resnet) est la valeur affichée dans la confirmation ci-dessus — l'utilisateur peut la changer avant d'étalonner. S'il n'y a pas du tout de fichier de paramètres, posez la question à l'utilisateur via AskUserQuestion :

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

L'UI Étape 3 (Parameters) 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 s'il faut d'abord ajuster les paramètres d'étalonnage (AskUserQuestion) :

• Procédez 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.
• Ajustez les paramètres dans l'UI en premier — ouvrez le projet, allez à Étape 3 : Parameters, changez les valeurs et cliquez sur Save ; puis continuez.

À l'Étape 3, définissez layout_px_per_m directement ou mesurez une distance connue à deux points. Relancez le post-traitement après un changement d'échelle ou d'alignement.

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

Étape E — Vérifier l'achèvement d'AMC

GET /v1/get_project_info/<project_id>

Vérifiez tous les 10 s. Utilisez project_info.amc_state pour l'achèvement d'AMC ; l'agrégat project_state n'est pas un signal de succès du pipeline.

Quand l'étalonnage démarre, affichez l'ID du projet, l'URL de l'UI (http://<HOST_IP>:${VSS_AUTO_CALIBRATION_UI_HOST_PORT:-5000}) et le point de terminaison du log pour que l'utilisateur puisse surveiller la progression pendant que l'exécution se déroule. Pendant RUNNING, émettez une ligne de progression au moins une fois par minute avec le temps écoulé pour qu'une longue exécution ne paraisse pas figé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 en direct peuvent aussi être diffusés via GET /v1/calibrate/<project_id>/log/<type>/stream.

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

Étape F — AMC Post-process et Results

Pour les projets multi-caméra, exécutez le post-traitement du layout après l'étalonnage AMC. VGGT, quand disponible, s'exécute en premier et est post-traité avant AMC.

POST /v1/postprocess/<project_id>
GET  /v1/get_project_info/<project_id>  # poll postprocess_state until COMPLETED

Ne signalez pas un projet multi-caméra comme réussi jusqu'à postprocess_state == "COMPLETED" ; les résultats AMC bruts peuvent exister même quand le post-traitement échoue.

GET /v1/get_project_info/<project_id>                    # project state
GET /v1/result/<project_id>/evaluation_statistics        # only if GT uploaded
GET /v1/result/<project_id>/overlay_image                # visual overlay (PNG)
GET /v1/amc/calibrate/<project_id>/log                   # calibration log

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é sol a été chargé — un résultat evaluation_statistics manquant est normal sinon et n'est pas la fin du rapportage de résultats. Quand VGGT a aussi complété, comparez les métriques des deux méthodes et les overlays de la page Results, puis sélectionnez l'étalonnage le plus précis pour l'export.

Après COMPLETED, donnez toujours à l'utilisateur un moyen de vérifier le résultat pour ce projet exact, indépendamment du fait que des métriques existent :

• UI — http://<HOST_IP>:${VSS_AUTO_CALIBRATION_UI_HOST_PORT:-5000} ; ouvrez le projet, puis la page Results pour voir l'overlay.
• Image overlay 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 mono-caméra utilisent output/single_view_results/cam_00/verification_map_overlay.png).
• Fichiers de projet — ${VSS_APPS_DIR}/services/auto-calibration/projects/project_<id>/.

Fichier de paramètres + Pattern de détecteur

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

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

<file contents, posted as-is>

Le fichier remplace ce que l'utilisateur ajusterait sinon à l'UI Étape 3 (rectification, bundle-adjustment, évaluation knobs, détecteur, …). Après un POST réussi, aussi analysez le fichier pour "detector" / "detector_type" — s'il s'agit de "resnet" ou "transformer", utilisez cette valeur pour l'appel /calibrate à l'Étape D (le détecteur est un paramètre API séparé, non consommé par /config).

Le non-2xx est affiché — ne basculez pas silencieusement. Ignorez entièrement cet appel si l'utilisateur a choisi le chemin de secours UI.

Pattern de secours UI

Quand les fichiers d'alignement / layout 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 : Parameters, ajustez via la boîte de dialogue des paramètres (ou acceptez les valeurs par défaut), cliquez sur Save. » 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.
• Layout manquant → « Ouvrez le projet UI <project_id>, allez à Étape 2 : Video Configuration, chargez layout.png uniquement (NE rechargez PAS les vidéos — elles sont déjà attachées via l'API/RTSP), cliquez sur Save. »
• Alignement manquant → « Ouvrez le projet UI <project_id>, allez à Étape 5 : Manual Alignment, soit chargez alignment_data.json soit marquez les points de correspondance sur le layout, cliquez sur Save. »

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 bind-monté 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

• amc_state == "COMPLETED" après vérification ; si VGGT s'est exécuté, vggt_state == "COMPLETED" aussi.
• 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é chargé : récupérez les statistiques d'évaluation des deux méthodes disponibles et comparez leurs métriques plus les overlays avant de sélectionner le résultat à exporter. Les seuils typiques sont Average L2 distance(m) < 1,5 et Average reprojection error 0(px) < 5 pour vos données ou < 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               # ← overlay visuel pour vérification
└── 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 skills en aval — Export MV3DT

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

GET /v1/result/{project_id}/mv3dt_result?result_type=amc
# Response: application/zip — mv3dt_output.zip containing transforms.yml

Pour la sortie VGGT indépendante (disponible seulement si VGGT s'est exécuté jusqu'à COMPLETED, voir Étape C) :

GET /v1/result/{project_id}/mv3dt_result?result_type=vggt
# Response: 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 affiché.
2. Attendez que la skill se termine (elle vérife en interne jusqu'à COMPLETED).
3. GET /v1/result/{project_id}/mv3dt_result?result_type=amc — sauvegardez le ZIP localement.
4. Si l'étalonnage VGGT indépendant s'est aussi exécuté, récupérez optionnellement ?result_type=vggt pour le résultat MV3DT VGGT.

Skills connexes

• vss-manage-video-io-storage — skill API VIOS ; seul 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é par l'UI à ce flux d'API.

bump:1