TAO Analyze Gaps OD mAP

Utilisez cette skill pour exécuter l'analyse de gaps TAO Data Services en détection d'objets. La skill compare les annotations de vérité terrain et d'inférence, calcule les métriques TP/FP/FN/AP50 par image et par classe, et identifie les images faibles où une métrique de classe quelconque tombe sous son seuil. Elle n'exécute pas l'inférence ; les étapes en amont doivent d'abord produire les annotations d'inférence.

Le point d'entrée du container est :

gap_analysis object_detection -e /absolute/path/to/object_detection.yaml

Inputs

Champs de spec requis :

Champ	Signification
`ground_truth_ann_path`	Répertoire d'étiquettes KITTI ou `.json` COCO avec les boîtes de vérité terrain.
`inference_ann_path`	Répertoire d'étiquettes KITTI ou `.json` COCO avec les prédictions du modèle.
`images_dir`	Répertoire racine des images. Établit l'univers complet d'images incluant les images sans annotations.
`results_dir`	Répertoire de sortie pour tous les artifacts.
`kpi`	Étiquette d'identifiant écrite dans chaque ligne de sortie.
`input_format`	`kitti` ou `coco`. Doit être déclaré explicitement ; jamais inféré du chemin.

Champs optionnels courants :

Champ	Défaut	Signification
`iou_threshold`	`0.5`	IoU à partir duquel une prédiction est acceptée comme vrai positif.
`conf_threshold`	`0.0`	Les prédictions en dessous de cette confiance sont supprimées avant l'appariement.
`min_area`	`0`	Les boîtes dont la surface en pixels (l × h) est strictement inférieure à cette valeur sont écartées.
`class_mapping`	`{}`	Mappe les chaînes d'étiquettes d'annotation brutes aux noms de classes canoniques. Les étiquettes absentes sont conservées telles quelles.
`weak_thresholds`	`{}`	Seuils par classe sous la forme `{class_name: {recall, precision, ap50}}`. Les clés absentes reviennent aux valeurs `default_*_threshold`. Références des défauts ITS : `car 0.99`, `bicycle 0.7`, `person 0.7` — une barrière stricte sur la classe abondante bien apprise et des barrières plus souples sur les rares que la boucle existe pour améliorer.
`default_recall_threshold`	`0.5`	Seuil de rappel par défaut pour les classes non listées dans `weak_thresholds`.
`default_precision_threshold`	`0.0`	Seuil de précision par défaut. Mettez à `0.0` pour désactiver la sélection d'images faibles basée sur la précision.
`default_ap50_threshold`	`0.5`	Défaut pour les classes absentes de `weak_thresholds`. Mettez à `0.0` pour que les classes non listées ne marquent jamais une image comme faible — le filtre de référence n'avait pas de fallback, et laisser le `0.5` de TAO DS en place filtre silencieusement chaque classe que vous n'avez pas listée.

Ne rédigez pas la spec à la main. Copiez le template et remplissez les null — chaque valeur de tuning qu'il porte déjà est celle que cette étape veut — puis validez :

cp skills/data/tao-analyze-gaps-od-map/assets/default_object_detection.yaml "$SPEC"
# fill ground_truth_ann_path, inference_ann_path, images_dir, results_dir, kpi, input_format
python3 skills/data/tao-analyze-gaps-od-map/scripts/verify_object_detection_spec.py --spec "$SPEC"

verify rejette les orthographes qui échouent — input_format en majuscules, chemins relatifs ou manquants, une entrée weak_thresholds qui est un nombre brut plutôt qu'un mapping — et rapporte chaque classe filtrée ainsi que les fallbacks default_*, de sorte que les critères de sélection derrière un ensemble faible sont récupérables à partir de la sortie de la exécution. Il avertit quand un fallback est supérieur à zéro, puisque cela filtre les classes que vous n'avez pas listées.

Quick Start

Exécutez depuis la racine du repo tao-skill-bank.

Écrivez la spec dans le répertoire des résultats. L'exécution émet quatre artifacts et ne conserve pas la spec, donc une analyse de gaps terminée ne pourrait sinon pas vous dire quels seuils ont produit son ensemble faible — et cet ensemble faible dimensionne le budget de mining en aval. Les garder ensemble rend les critères de sélection récupérables à partir de l'exécution seule.

RESULTS_DIR=/absolute/path/for/this/run          # results_dir in the spec
SPEC="$RESULTS_DIR/object_detection.yaml"        # spec lives beside its outputs
RUN_ROOT=/absolute/path/that/contains/annotations/images/and/results
GPU_COUNT=1

DS_IMAGE=nvcr.io/nvidia/tao/tao-toolkit:7.2.0-data-services  # versions-key: images.tao_toolkit.data_services

docker run --rm --gpus "$GPU_COUNT" --shm-size=8g --network=host \
  -v "$RUN_ROOT:$RUN_ROOT" \
  -w "$RUN_ROOT" \
  "$DS_IMAGE" \
  gap_analysis object_detection -e "$SPEC"

Ne passez pas --user $(id -u):$(id -g) ; certaines images TAO DS appellent getpass.getuser() au démarrage et échouent quand l'UID n'est pas dans /etc/passwd.

Preflight

Vérifiez l'accès Docker :

docker info > /dev/null

Résolvez et tirez l'image data-services si nécessaire :

DS_IMAGE=nvcr.io/nvidia/tao/tao-toolkit:7.2.0-data-services  # versions-key: images.tao_toolkit.data_services
docker image inspect "$DS_IMAGE" > /dev/null || docker pull "$DS_IMAGE"

Confirmez que RUN_ROOT contient la spec, les deux sources d'annotations et le répertoire d'images. Montez RUN_ROOT au même chemin absolu à l'intérieur de Docker.

Outputs

Artifact	Emplacement	Contenu
Gaps FP/FN	`results_dir/box_gaps.parquet`	Une ligne par boîte non appariée : `kpi`, `image_id`, `filepath`, `class`, `gap_type` (FP/FN), `bbox`, `confidence`, `best_iou`.
Métriques par image	`results_dir/image_metrics.parquet`	Par image par classe : `tp`, `fp`, `fn`, `precision`, `recall`, `ap50`.
Images faibles	`results_dir/weak_images.parquet`	Images où une métrique de classe quelconque tombe sous le seuil : `filepath`, `weak_classes`, `weak_recall`, `weak_precision`, `weak_ap50`. À transmettre à `tao-mine-od-images`.
Rapport de gaps	`results_dir/gap_report.json`	Comptages FP/FN par type et classe, ainsi que les paramètres d'exécution.

Les quatre artifacts sont toujours écrits, même quand aucun gap n'est trouvé.

Troubleshooting

The subtask object_detection requires -e/--experiment_spec_file : réexécutez avec gap_analysis object_detection -e "$SPEC".

Chemin d'entrée non trouvé dans Docker : utilisez un montage RUN_ROOT où les chemins host et container sont identiques.

Erreur input_format : définissez explicitement input_format: kitti ou input_format: coco — il n'est jamais inféré du chemin.

weak_images.parquet est vide : toutes les métriques de classe sont au-dessus de leurs seuils. Abaissez default_recall_threshold / default_ap50_threshold ou ajoutez des entrées par classe à weak_thresholds.

Répertoire de sortie non accessible en écriture après la sortie de Docker : le container écrit en tant que root. Récupérez avec docker run --rm -v "$RUN_ROOT:$RUN_ROOT" alpine chown -R "$(id -u):$(id -g)" "$RESULTS_DIR".