Exécuter et évaluer le pipeline de perception FoundationPose

Objectif

Exécuter la profondeur, la segmentation SAM3 et FoundationPose sur des datasets au format BOP en utilisant le moteur de profondeur TensorRT de TAO Deploy. Adapter les datasets, préserver la traçabilité de l'exécution et interpréter les métriques de pose. Pour les dépendances manquantes ou la construction du moteur, utilisez foundationpose-setup s'il est installé, ou consultez les sections Install et Verify du README du checkout du produit.

Prérequis

Localisez le checkout du produit de l'utilisateur via pyproject.toml (projet foundationpose-perception-pipeline), script/run_pipeline.py et config/defaults.yaml. Exécutez les commandes depuis cette racine, pas depuis le répertoire de cette skill installée. Une installation de catalogue fournit des instructions, pas le code du produit, les datasets ou les poids. Si l'exécution a été demandée et aucun checkout n'existe, obtenez-le à partir de l'URL ci-dessus et complétez d'abord la configuration. Pour des conseils ou une analyse d'artefacts fournis, utilisez ces entrées sans cloner ni charger les modèles.

L'exécution requiert la venv Python 3.12 du produit, un accès autorisé au checkpoint SAM3, la bibliothèque FoundationPose construite, un dataset adapté, un moteur TAO correspondant avec son fichier annexe et une mémoire GPU suffisante. Consultez les sections Configuration et Dataset adaptation du README du checkout pour les chemins de profil; consultez ARCHITECTURE.md Outputs pour le schéma d'artefact correspondant.

Définissez les chemins absolus avant le travail GPU:

export FOUNDATIONPOSE_ROOT="$(realpath ../foundation-pose-inference-library)"
PIPELINE_SITE="$(realpath .venv/lib/python3.12/site-packages)"
export LD_LIBRARY_PATH="${PIPELINE_SITE}/tensorrt_libs:${PIPELINE_SITE}/nvidia/cu13/lib:${LD_LIBRARY_PATH:-}"
./.venv/bin/python -c "import ctypes; ctypes.CDLL('libcudart.so.13'); print('ok')"

Ne mélangez pas les bibliothèques d'une autre venv dans ce chemin. Ignorer la vérification peut causer l'échec de la pose après la fin de la profondeur.

Instructions

1. Résoudre la tâche et les entrées

Identifiez le profil, le nom du dataset, les chemins de scène source ou adapté, le moteur, la disponibilité de la vérité terrain et le répertoire de sortie. <profile> et <dataset> peuvent différer. --config sélectionne un profil; il ne remplace pas un --dataset obligatoire. Les profils du même nom peuvent être déduits par les commandes qui acceptent --dataset.

Une capture sans scene_gt.json peut utiliser l'inférence uniquement. --no-depth-metrics ignore la notation de profondeur de capteur collectée; il ne supprime pas l'obligation de vérité terrain de pose pour l'évaluation.

2. Adapter avant de construire ou vérifier un moteur

Ignorez l'adaptation uniquement pour la disposition du rig du pipeline: <split>/<scene>/rgb/<im_id>.png, un scene_camera.json par scène, et im_ids représentant les caméras du rig (caméra de base 0 dans les profils livrés).

./.venv/bin/python tools/bop_adapt/adapt.py --config <profile> --src <downloaded-dataset>

Le dataset.name du profil sélectionne un adaptateur enregistré; --help expose ses drapeaux. Un adaptateur inconnu n'est pas automatiquement supporté. Sur les datasets de scène statique, l'adaptateur émet une scène par paire (scène source, image de base) utilisable et signale les images ignorées sans partenaire rectifiable. Changer la bande de base modifie les données adaptées: reconstruisez les caches GT et régénérez la profondeur.

La construction du moteur utilise tools/build_tao_engine.py --shape-from-scene <adapted-scene>; consultez la section Install du README du checkout si la skill de configuration n'est pas disponible. Un répertoire BOP brut ou des dimensions d'image brutes n'établissent pas la forme de moteur rectifiée requise.

3. Valider les entrées et préparer les caches GT

./.venv/bin/python test/check_engine_depth_smoke.py \
  --config <profile> --dataset <dataset> --engine <engine-path>

Attendez-vous à backend=tao, normalization=imagenet, une forme fixe, une fraction valide plausible et aucun avertissement cropping N rows. Un fichier annexe obsolète, un GPU/TensorRT/précision modifié, une largeur-max modifiée ou le rognage nécessite de reconstruire le moteur et de régénérer la profondeur. Ne contournez pas ces vérifications.

Pour les exécutions de notation avec GT de pose, précomputez le cache:

./.venv/bin/python script/build_gt_cache.py --config <profile> --dataset <dataset>

Utilisez --config <profile> --all pour tous les datasets correspondants. Une profondeur collectée manquante appelle --no-depth-metrics; un scene_gt.json manquant appelle l'inférence uniquement. Vérifiez le dataset.collected_depth_root résolu en utilisant le chemin réel, pas une substitution de commande shell.

4. Exécuter seulement le travail nécessaire

Pour une nouvelle exécution de bout en bout:

./.venv/bin/python script/run_pipeline.py --config <profile> --dataset <dataset> \
  --output-dir output/<new-run> --foundation-stereo-model <engine-path> \
  --depth-backend commercial --no-depth-metrics

Omettez --no-depth-metrics lorsque la profondeur de capteur collectée est disponible et doit être notée. Commencez avec --max-scenes 1 pour une vérification de temps/ajustement avant de dimensionner une exécution plus grande. Pour une capture sans vérité terrain de pose:

./.venv/bin/python script/infer.py --config <profile> --dataset <dataset> \
  --output-dir output/<new-run> --foundation-stereo-model <engine-path> \
  --depth-backend commercial

Le chemin du modèle sélectionne le backend. --depth-backend commercial affirme cette sélection; il ne télécharge ni modèle ni n'établit les droits aux poids. Définissez le moteur une fois dans overrides.depth.engine du profil pour éviter de répéter le drapeau chemin-modèle.

Préservez les résultats existants lors de la comparaison des exécutions. Réutilisez la profondeur mise en cache uniquement après vérification de ses métadonnées. --overwrite-results réexécute la segmentation et la pose; --overwrite-depth régénère également la profondeur. Régénérez la profondeur après des changements au moteur, à la largeur rectifiée, CLAHE, bornes de distance de travail ou données adaptées. Reprenez une défaillance de pose uniquement sans écraser une profondeur valide. Les bornes de distance de travail doivent être fournies ensemble.

Ne répétez pas les défauts réglés de config/defaults.yaml sur chaque commande; utilisez les remplacements de profil pour les changements délibérés spécifiques au dataset. Reconstruisez le moteur si foundation_stereo_max_width change.

5. Re-noter sans répéter l'inférence

Pour un changement de cutoff de reclassement, seuil IoU ou bande de visibilité, conservez les prédictions terminées, les fichiers annexes de masque et les fichiers de profondeur et exécutez:

./.venv/bin/python script/evaluate.py --config <profile> --dataset <dataset> \
  --run output/<completed-run> --output-dir output/<new-score-run> \
  --rerank-cutoff 4.5 --no-depth-metrics

Omettez --no-depth-metrics lorsque la comparaison de profondeur est souhaitée. Un --output-dir séparé préserve l'ancien rapport. Aucun modèle d'inférence n'est chargé; un miss de cache GT peut toujours nécessiter une rastérisation. Pour un balayage de cutoff hors ligne, tools/sweep_rerank_cutoff.py --config <profile> --results-root output --datasets <dataset> s'attend à un répertoire de dataset par répertoire de résultats.

6. Vérifier la traçabilité et interpréter les résultats

Inspectez inference_config.json pour le moteur et la largeur-max, et le depth/<scene>/metadata.json de chaque scène pour backend: tao, normalization: imagenet et model_fixed_hw. Inspectez les deux avant de faire confiance à la profondeur mise en cache. Ceux-ci établissent la traçabilité de l'exécution, pas l'approbation légale.

Lisez report.md, pose_summary.json (overall, by_visibility, by_object) et depth_summary.json lorsque la profondeur a été notée. Comparez:

• matched_predictions en premier: un changement de population appariée peut biaiser les gains de précision apparents.
• max_vertex_error_within_threshold_rate contre le seuil configuré et le taux requis.
• Erreur de sommet médiane, p90 et p99, ADD/ADD-S et erreur de rotation, incluant les résultats par objet.
• Erreur de profondeur sur les pixels d'objet; l'erreur d'image entière peut être dominée par la table ou l'arrière-plan.

Un taux de succès plus élevé peut coexister avec une moyenne ou une queue pire. Rapportez les deux, ainsi que les changements de population. Préservez une baseline avant de réécrire les résultats; utilisez des répertoires d'exécution séparés lorsque la rétention de prédictions et de traçabilité importe.

7. Exécutions par batch

./.venv/bin/python script/run_batch_eval.py --config <profile> --output-root output/<batch-run> \
  --foundation-stereo-model <engine-path> --depth-backend commercial --no-depth-metrics

Le drapeau sans-profondeur supprime également le filtrage de profondeur collectée de la découverte de dataset par batch. Ajoutez --continue-on-error uniquement lorsque les datasets défaillants ne doivent pas arrêter le balayage. Exécutez les datasets GPU séquentiellement; inspectez run_status.jsonl avant d'interpréter les summary.json ou report.md agrégés.

Exemples

• « Adapter T-LESS et exécuter une scène avec le moteur de profondeur TAO. »
• « Re-noter cette exécution FoundationPose terminée au cutoff 4,5 et préserver l'ancien rapport. »
• « Comparer ces résumés de pose; le taux de succès 5 mm a-t-il amélioré à la même couverture? »

Dépannage et limitations

Un test de fumée démontre l'opération du backend, pas la précision de pose. La précision requiert un dataset représentatif réel et une baseline conservée. Ne signalez jamais une métrique non disponible comme zéro. invalid resource handle pointe vers les limites de contexte pycuda autour des appels TAO. Une profondeur plausible à environ le double de l'échelle attendue appelle la vérification de la normalisation d'entrée et de l'étalonnage. Signalez la commande, le dataset/profil, les chemins de sortie, la provenance du modèle, le statut d'achèvement, les métriques principales avec les comptages appariés et toutes les étapes non vérifiées.