Skill: Calibrer à partir de fichiers vidéo

Quand utiliser cette Skill

Activez cette Skill quand l'utilisateur dispose de fichiers MP4 pré-enregistrés et souhaite les calibrer via l'API REST AMC. Prompts typiques :

• "calibrate my videos" / "run AMC on these videos"
• "calibrate from video files"

Pilote le calibrage via l'API REST sur des fichiers MP4 pré-enregistrés fournis par l'utilisateur — aucun script CLI ou bind-mount Docker requis, juste un microservice en cours d'exécution et vos fichiers.

Prérequis

• [ ] Microservice AMC et UI en fonctionnement (suivez skills/amc-setup-calibration-stack/SKILL.md)
• [ ] Vous connaissez l'URL du microservice (ex. http://<HOST_IP>:<MS_PORT>) et l'URL de l'UI
• [ ] Fichiers vidéo locaux nommés cam_00.mp4, cam_01.mp4, … synchronisés temporellement, ~1920×1080
• [ ] Python 3 avec requests

Confidentialité des données

Les fichiers vidéo uploadés via cette Skill sont transmis au backend AutoMagicCalib (endpoint REST). N'utilisez cette Skill que si le backend est déployé sur une plateforme / réseau de confiance.

Questions à poser à l'utilisateur

Requis

(La nomenclature des fichiers vidéo et l'URL du microservice sont précisées dans les Prérequis ci-dessus — collectez les inputs suivants.)

1. Répertoire des vidéos — le dossier dans lequel la Skill cherche cam_*.mp4, uploadés triés alphabétiquement.
2. URL du microservice
3. Nom du projet — chaîne descriptive courte

Auto-détectés (posez la question seulement s'ils ne sont pas trouvés)

Le script explore le répertoire des vidéos, ses sous-répertoires de premier niveau, et son parent. Si exactement une correspondance est trouvée, elle est utilisée ; sinon le script affiche les emplacements explorés et continue vers un chemin explicite ou un repli UI :

Poster le fichier de paramètres remplace l'Étape 3 de l'UI et peut fixer le détecteur (resnet/transformer), qui est passé séparément à /calibrate — voir Étape 4.

Optionnel

4. ZIP de vérité terrain — GT.zip avec dossiers _World_Cameras_Camera_XX/ (active les métriques d'évaluation)
5. Distances focales — une par caméra, ex. 1269.0, 1099.5, 1099.5
6. Type de détecteur — resnet (par défaut, rapide) ou transformer (plus lent, meilleur avec occlusion)
7. Lancer l'affinage VGGT ? — si VGGT est prêt après la fin d'AMC, demandez à l'utilisateur s'il faut lancer l'affinage (voir setup skill)

Consultez la section "Custom Dataset" du README.md racine pour les recommandations sur les vidéos d'entrée et le format de vérité terrain.

Instructions

Tous les endpoints ci-dessous sont implémentés de bout en bout dans le Script Python complet — la prose décrit le workflow et les décisions que l'agent doit prendre ; le script est la référence exécutable.

Étape 1 — Créer un projet

POST /v1/create_project (champ de formulaire project_name) → enregistrez le project_id retourné.

Étape 2 — Uploader les vidéos (requis)

POST /v1/upload_video_files/<project_id> (multipart files). Uploadez triées alphabétiquement — le serveur assigne les indices des caméras par ordre d'upload.

Étape 3 — Résoudre les fichiers locaux (Auto-scan, Demander, ou UI)

Pour chacun des fichiers (paramètres de calibrage, alignement, mise en page), exécutez cette résolution :

1. Auto-scan de VIDEO_DIR, un niveau de sous-répertoires sous VIDEO_DIR, et VIDEO_DIR.parent pour les noms candidats (tableau ci-dessus).
2. Si exactement une correspondance, utilisez-la et affichez ce qui a été trouvé.
3. Si zéro ou plusieurs correspondances, affichez les emplacements explorés, puis demandez à l'utilisateur un chemin explicite via le mécanisme de questions de l'hôte ; si aucun n'est disponible, posez la question en chat et attendez. S'il n'a pas le fichier, marquez-le pour un repli UI.
4. Repli UI : dites à l'utilisateur de compléter l'étape UI correspondante ; attendez la confirmation ; pour alignement/mise en page, vérifiez aussi que les fichiers ont atterri dans projects/project_<id>/manual_adjustment/.

Étape 4 — Uploader les fichiers résolus

Uploadez chaque fichier résolu localement :

Après un POST de paramètres réussi, analysez le fichier pour "detector" / "detector_type" — si c'est "resnet" ou "transformer", utilisez cette valeur pour l'appel /calibrate de l'Étape 7 (le détecteur est un paramètre API séparé, non consommé par /config).

Étape 5 — Repli UI (seulement pour les fichiers que l'utilisateur n'a pas localement)

Si l'un des fichiers (paramètres / alignement / mise en page) n'a pas été résolu à l'Étape 3, dirigez l'utilisateur vers l'étape UI 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 quel détecteur utiliser (resnet ou transformer) via le mécanisme de questions de l'hôte ; si aucun n'est disponible, posez la question en chat et attendez. L'Étape 3 de l'UI ne couvre pas le choix du détecteur.
• Alignement ou mise en page manquants → "Ouvrez le projet UI <project_id>, allez à Étape 4 : Alignement, uploadez la mise en page, marquez les points de correspondance, cliquez sur Enregistrer."

Attendez la confirmation de l'utilisateur. Pour les exécutions de script non-interactives, fournissez les fichiers nécessaires à l'avance ; le script se termine avec un message clair plutôt que d'attendre des entrées. Pour alignement/mise en page, vérifiez sur le disque avant de continuer :

REPO_ROOT=$(git rev-parse --show-toplevel)
# Résolvez PROJECT_DIR à partir de compose/.env (défaut : projects/ à la racine du repo).
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/"
# Attendu : alignment_data.json, layout.png

Étape 6 — Vérifier le projet

POST /v1/verify_project/<project_id> → doit retourner {"project_state": "READY"} avant de calibrer.

Étape 7 — Démarrer le calibrage

Confirmez le plan avant de calibrer. Que le fichier de paramètres et le détecteur soient auto-détectés ou demandés, présentez un court résumé et obtenez la confirmation explicite de l'utilisateur avant POST /calibrate via le mécanisme de questions de l'hôte ; si aucun n'est disponible, posez la question en chat et attendez. Les valeurs résolues sont les défauts, donc confirmer est un clic, mais l'utilisateur peut changer le détecteur ou sauter un fichier de paramètres auto-détecté. Le script Python autonome affiche le même plan et ne demande que lorsque stdin est interactif. Résumez :

• Détecteur — resnet ou transformer (la valeur à envoyer).
• Paramètres de calibrage — le fichier appliqué (chemin), ou "défauts" si aucun.
• Remplacements optionnels — ZIP de vérité terrain et distances focales, le cas échéant.

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

{"detector_type": "resnet"}

Étape 8 — Interroger la complétion

GET /v1/get_project_info/<project_id> toutes les 10 s — project_info.project_state passe de RUNNING à COMPLETED (ou ERROR, tirez le log). Durée typique : 10–60 min selon la longueur vidéo et le détecteur.

Étape 9 — Obtenir les résultats

GET /v1/result/<project_id>/evaluation_statistics (seulement si GT a été uploadée ; inclut Average L2 distance(m) et Average reprojection error 0(px)), et GET /v1/amc/calibrate/<project_id>/log pour le log de calibrage.

Champs de statut de get_project_info

project_info.project_state est le cycle de vie du calibrage AMC pour le projet : RUNNING → COMPLETED (ou ERROR).

project_info.vggt_state est aussi par-projet, un cycle de vie d'affinage VGGT scoped au projet plutôt qu'un service global direct ou un statut de chargement de modèle. Un projet nouvellement créé peut rapporter vggt_state: "INIT" même quand le modèle VGGT est présent et monté. Le cycle de vie VGGT attendu est INIT → READY après la fin du calibrage AMC → RUNNING pendant l'affinage VGGT → COMPLETED (ou ERROR).

Utilisez vggt_state == "READY" seulement comme portail pour l'affinage VGGT optionnel à l'Étape 10. Interprétez INIT sur un projet nouveau ou non-calibré comme un état de projet normal. Si le calibrage AMC est complet et le projet reste dans un état VGGT non-prêt, confirmez la configuration VGGT et la disponibilité du modèle avec les vérifications du setup skill et les logs du service.

Étape 10 — (Optionnel) Affinage VGGT

Après la fin du calibrage AMC, lisez vggt_state de GET /v1/get_project_info/<project_id>.

• Si le projet rapporte vggt_state == "READY", demandez à l'utilisateur s'il faut lancer l'affinage VGGT via le mécanisme de questions de l'hôte ; si aucun n'est disponible, posez la question en chat et attendez.
• Si l'utilisateur confirme, POST /v1/vggt/calibrate/<project_id>, interrogez vggt_state via get_project_info, puis GET /v1/vggt_results/<project_id>/evaluation_statistics.
• Si VGGT n'est pas prêt, sautez l'affinage et expliquez que l'utilisateur peut configurer VGGT avec amc-setup-calibration-stack et relancer cette étape optionnelle plus tard.

Le script Python autonome ne pose que quand stdin est interactif. Dans les exécutions non-interactives, définissez RUN_VGGT = True pour accepter ; sinon le script affiche que VGGT est prêt et continue sans blocage.

Script Python complet

Utilisez scripts/run_video_calibration.py pour l'implémentation exécutable. Définissez BASE_URL, PROJECT_NAME, et VIDEO_DIR ; les variables d'env optionnelles sont CONFIG_FILE, ALIGNMENT_JSON, LAYOUT_PNG, GT_ZIP, FOCAL_LENGTHS, DETECTOR_TYPE, RUN_VGGT, REPO_ROOT, et PROJECTS_DIR. Le script implémente le repli UI, la confirmation du plan, le comportement d'invite/opt-in VGGT, l'interrogation, et la récupération de statistiques affinées.

Critères de réussite

• project_state == "COMPLETED" après interrogation.
• Si l'alignement manuel a été utilisé : projects/project_<id>/manual_adjustment/ contient alignment_data.json + layout.png.
• Si GT a été uploadée : l'évaluation retourne des seuils typiques :
  • Average L2 distance(m) < 1,5
  • Average reprojection error 0(px) < 5
• Aucun état ERROR.

Fichiers de sortie clés (sur le serveur)

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

Dépannage

Pour les Skills aval — Export MV3DT

Une skill Multi-View 3D Tracking aval récupère l'étalonnage au format MV3DT directement depuis le microservice (cette Skill ne le télécharge pas ; elle retourne le project_id). Après que cette Skill rapporte COMPLETED :

• GET /v1/result/{project_id}/mv3dt_result?result_type=amc → mv3dt_output.zip (contient transforms.yml).
• Si VGGT s'est exécuté vers COMPLETED (Étape 10) : ?result_type=vggt → vggt_mv3dt_output.zip.

Skills associées

• skills/amc-setup-calibration-stack/SKILL.md — démarrez d'abord MS + UI.
• skills/amc-run-sample-calibration/SKILL.md — vérifiez la pile avec l'exemple fourni avant d'essayer le vôtre.

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

<!-- signing marker -->