Skill : Calibrer l'exemple de dataset

Quand utiliser cette skill

Activez cette skill quand l'utilisateur veut vérifier qu'une stack AMC en cours d'exécution fonctionne correctement avec l'exemple de dataset fourni. Prompts typiques :

• « test the sample dataset » / « run sample calibration »
• « verify AMC install »
• « launch and test » (chaîner avec amc-setup-calibration-stack si le MS n'est pas déjà en cours d'exécution)

N'utilisez PAS cette skill quand :

• L'utilisateur référence ses propres chemins vidéo (ex. /data/videos/, cam_*.mp4 non issus du zip fourni) — routez vers amc-run-video-calibration. Cette skill est exclusivement pour assets/sdg_08_2_sample_data_010926.zip.

Prérequis : microservice AMC en cours d'exécution sur un port de la plage 8000-8009. Si aucun backend n'est détecté, déléguez d'abord à amc-setup-calibration-stack.

Si l'exécution ne peut pas procéder dans l'environnement actuel (pas de backend, données d'exemple manquantes, etc.), signalez le blocage ET décrivez brièvement le workflow attendu + la séquence API pour que l'utilisateur comprenne ce qui s'exécutera une fois les prérequis satisfaits. Ne fabriquez pas de résultats de calibrage, métriques d'évaluation ou trajectoires.

Présentation

Exécutez une calibration complète sur l'exemple de dataset fourni (sdg_08_2_sample_data_010926.zip, 4 caméras synthétiques d'entrepôt avec vérité terrain) contre un microservice AutoMagicCalib en cours d'exécution. Utile pour vérifier qu'une stack fraîchement lancée fonctionne de bout en bout avant d'alimenter des données réelles.

L'exemple inclut la GT, donc l'exécution produit des métriques d'évaluation (distance L2, erreur de reprojection) — aucun ajustement de paramètres de calibrage nécessaire.

Prérequis

• [ ] Microservice AMC en cours d'exécution (suivez skills/amc-setup-calibration-stack/SKILL.md sinon)
• [ ] Zip d'exemple présent à assets/sdg_08_2_sample_data_010926.zip
• [ ] Python 3 avec requests disponible, ou utilisez le chemin Swagger UI ci-dessous
  • Le script fourni s'auto-répare : si requests est manquant, il crée un venv temporaire sous ${TMPDIR:-/tmp}/amc-sample-test-venv (rien écrit dans le repo)
  • Si python3 -m venv échoue avec ensurepip not available : sudo apt install -y python3-venv python3-pip

Instructions

« launch AMC and test sample dataset » (ou similaire) :

1. Exécutez d'abord skills/amc-setup-calibration-stack/SKILL.md.
2. Attendez que /v1/ready retourne OK.
3. Extrayez les données d'exemple (extrait ci-dessous) — idempotent, sûr de réexécuter.
4. Exécutez le script fourni dans Run Script.
5. Rapportez les métriques finales + URL de l'interface pour inspection manuelle.
6. L'affinement VGGT est tenté par défaut quand le projet rapporte vggt_state: READY ; sinon le script explique que la configuration VGGT est optionnelle et peut être activée plus tard pour l'affinement.

« test sample dataset » (MS déjà en cours d'exécution) :

1. Détectez le backend : scannez les ports 8000–8009 pour une réponse /v1/ready.
2. Si aucune → pointez vers la skill de configuration.
3. Extrayez les données d'exemple si pas déjà en cache.
4. Exécutez le script fourni.
5. Rapportez les métriques.

Détecter le backend en cours d'exécution

MS_PORT=""
for port in {8000..8009}; do
  if curl -s "http://localhost:$port/v1/ready" | grep -q '"code":0'; then
    MS_PORT=$port; break
  fi
done
[ -z "$MS_PORT" ] && { echo "No running backend. Run amc-setup-calibration-stack skill first."; exit 1; }
echo "Backend on port $MS_PORT"

Localiser + extraire les données d'exemple (idempotent)

export REPO_ROOT=$(git rev-parse --show-toplevel)

SAMPLE_ZIP="$REPO_ROOT/assets/sdg_08_2_sample_data_010926.zip"
[ -f "$SAMPLE_ZIP" ] || { echo "Sample zip not found at $SAMPLE_ZIP"; exit 1; }

# Répertoire cache à côté du zip.
SAMPLE_DIR="$(dirname "$SAMPLE_ZIP")/.cache/sdg_08_2_sample_data_010926"

if [ ! -d "$SAMPLE_DIR" ]; then
  mkdir -p "$SAMPLE_DIR"
  unzip -q "$SAMPLE_ZIP" -d "$SAMPLE_DIR"
fi
ls "$SAMPLE_DIR"
# Attendu (possiblement dans un dossier wrapper) : alignment_data/  GT.zip  videos/

Script à exécuter

Exécutez scripts/run_sample_calibration.py depuis la racine du repo auto-magic-calib, ou définissez REPO_ROOT=/path/to/auto-magic-calib. Le script lit compose/.env pour le port du backend, accepte les surcharges BASE_URL, MS_PORT, SAMPLE_DIR et RUN_VGGT, crée un nouveau projet à chaque exécution, tente VGGT quand prêt, et affiche la note du dataset NGC warehouse à la fin.

Alternative : Parcours par interface Swagger UI

Raccourci agent : si l'utilisateur a explicitement demandé un parcours par interface Swagger UI (ou a dit « no Python »), émettez le tableau ci-dessous et arrêtez — n'invoquez pas d'outils shell, ne lisez pas les autres sections, n'exécutez pas le script Python fourni.

Le microservice expose une interface OpenAPI interactive à http://<HOST_IP>:<MS_PORT>/docs. Si vous préférez cliquer dans l'API manuellement :

1. Ouvrez http://<HOST_IP>:<MS_PORT>/docs dans un navigateur.

2. Dézippez sdg_08_2_sample_data_010926.zip dans un répertoire cache à côté.

3. Exécutez ces endpoints dans l'ordre, en copiant project_id de l'étape 1 dans les chemins suivants :

   #	Endpoint	Corps / Fichiers
   1	POST /v1/create_project	project_name : n'importe quelle chaîne
   2	POST /v1/upload_video_files/{project_id}	files : uploadez les 4 videos/cam_0*.mp4 triés par nom
   3	POST /v1/upload_alignment/{project_id}	alignment_file : alignment_data/alignment_data.json
   4	POST /v1/upload_layout/{project_id}	layout_file : alignment_data/layout.png
   5	POST /v1/upload_gt_file/{project_id}	gt_file : GT.zip
   6	POST /v1/verify_project/{project_id}	— (attendez project_state: READY)
   7	POST /v1/calibrate/{project_id}	JSON : {"detector_type": "resnet"}
   8	GET /v1/get_project_info/{project_id}	Rafraîchissez toutes les ~10 s jusqu'à project_state = COMPLETED
   9	GET /v1/result/{project_id}/evaluation_statistics	Lisez distance L2 + erreur de reprojection
   10 optionnel	POST /v1/vggt/calibrate/{project_id} puis GET /v1/vggt_results/{project_id}/evaluation_statistics	Exécutez seulement quand vggt_state est READY ; interrogez vggt_state jusqu'à COMPLETED

C'est la même séquence que le script Python fourni exécute, juste exécutée manuellement. L'étape 10 est tentée par défaut quand vggt_state est READY ; sinon elle est ignorée avec un guide de configuration.

Champs de statut depuis get_project_info

project_info.project_state est le cycle de vie de calibration AMC du projet. Interrogez-le jusqu'à ce qu'il atteigne COMPLETED (ou arrêtez-vous sur ERROR).

project_info.vggt_state est un cycle de vie d'affinement VGGT par projet, un statut orienté projet plutôt qu'un statut de service global direct ou 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 attendu est INIT → READY après complétion de la calibration AMC → RUNNING pendant que l'affinement VGGT s'exécute → COMPLETED (ou ERROR). Interprétez INIT sur un projet nouveau ou non calibré comme un état de projet normal. Si la calibration AMC est complète 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 de la skill de configuration et les logs du service.

Critères de réussite

• Le projet atteint project_state == "COMPLETED" en ~30 min.
• /v1/result/{id}/evaluation_statistics retourne des statistics non vides (GT uploadée).
• VGGT soit s'exécute à vggt_state == "COMPLETED" et rapporte /v1/vggt_results/{id}/evaluation_statistics, soit est ignoré avec un guide de configuration parce que le projet n'est pas READY pour VGGT.
• Aucun état ERROR rencontré.

Métriques représentatives pour l'exemple (les vôtres devraient être similaires) :

Average L2 distance(m)               : < 1,5
Average reprojection error 0(px)     : < 10

Fichiers de sortie clés (sur le serveur)

Les résultats persistent sous $REPO_ROOT/projects/project_<project_id>/ :

projects/project_<project_id>/
├── output/
│   ├── single_view_results/cam_XX/
│   │   ├── camInfo_hyper_XX.yaml
│   │   └── trajDump_Stream_0_3d.txt
│   └── multi_view_results/BA_output/results_ba/refined/
│       └── camInfo_XX.yaml          # ← calibration finale (utilisez celle-ci)
└── calibration.log

Surveiller la progression

PROJECT_ID=<id_from_step_1>
REPO_ROOT=$(git rev-parse --show-toplevel)
tail -F --retry "$REPO_ROOT/projects/project_${PROJECT_ID}/calibration.log"

Ou streamez les logs MS :

REPO_ROOT=$(git rev-parse --show-toplevel)
docker compose -f "$REPO_ROOT/compose/compose.yml" logs -f auto-magic-calib-ms

Dépannage

Dataset d'exemple supplémentaire

Le README.md racine documente aussi nv_warehouse_032326.zip, un dataset d'entrepôt du monde réel disponible depuis NGC. Téléchargez-le avec ngc registry resource download-version "nvidia/amc-nv-warehouse" ; puis utilisez amc-run-video-calibration, uploadez nv_warehouse_config.json à l'étape de configuration, et exécutez avec le détecteur transformer. Il ne contient pas de données de vérité terrain.

Skills connexes

• skills/amc-setup-calibration-stack/SKILL.md — lancez MS + interface (prérequis).
• skills/amc-run-video-calibration/SKILL.md — exécutez la calibration sur vos propres MP4 pré-enregistrés.

Les sections « Sample Data Setup » et « Calibration Workflow (UI) » du README.md racine couvrent le chemin orienté humain via le même exemple.

<!-- signing marker -->