Depth Net Stereo

Estimation de profondeur stéréo utilisant l'architecture FoundationStereo. Prédit des cartes de disparité à partir de paires d'images stéréo pour la reconstruction 3D.

Utilise les encodeurs Depth Anything v2 et EdgeNeXt préentraînés. Définissez model.stereo_backbone.depth_anything_v2_pretrained_path et model.stereo_backbone.edgenext_pretrained_path.

Les skills mono et stéréo invoquent tous deux le CLI unifié TAO depth_net à l'intérieur du conteneur ; la famille mono/stéréo est sélectionnée via model.model_type (par ex. FoundationStereo).

Pour les actions TAO Deploy TensorRT (gen_trt_engine, évaluation TensorRT et inference TensorRT), consultez d'abord references/tao-deploy-foundation-stereo.md. Le modèle de spec de déploiement se trouve dans references/spec_template_deploy.yaml de ce skill.

Train Action Policy

Ce modèle est compatible AutoML au niveau du modèle. Avant de traiter toute demande au stade du training, lisez references/skill_info.yaml et résolvez le run override soit à partir d'une valeur automl_policy explicite, soit à partir de la demande workflow de l'utilisateur. Traitez les phrases comme « turn off AutoML », « disable AutoML », « no HPO » ou « plain training » comme automl_policy: off pour cette exécution uniquement ; sinon par défaut à auto. Quand automl_policy: auto, automl_enabled: true et que schemas/train.schema.json et references/spec_template_train.yaml sont tous deux fournis, routez l'action train via tao-skill-bank:tao-run-automl par défaut avec le skill_dir de ce modèle. Préservez les overrides workflow/application pour les datasets, specs, répertoires de sortie, paramètres GPU/plateforme, checkpoints parents et automl_policy. Utilisez le training direct du modèle uniquement quand automl_policy: off ou que le schema/modèle train fourni est manquant ; dans le cas du schema manquant, signalez que AutoML est activé mais non exécutable pour ce modèle jusqu'à ce que les schemas soient générés.

Les actions sans training comme evaluate, inference, export et les flux de déploiement restent dans ce skill de modèle. L'override automl_policy par exécution ne change pas les métadonnées du modèle.

Workflow

Prérequis — accessibilité des données

Votre dataset (images gauche + droite + disparité GT) doit être accessible de l'intérieur du conteneur :

• SDK runner : placez les fichiers aux chemins S3 que le runner résout (les placeholders S3_TRAIN / S3_EVAL affichés dans Typical Spec Overrides). Le runner gère le montage S3 → chemin-conteneur de façon transparente.
• docker run direct (par ex. test local) : montez la racine du dataset hôte en lecture seule au même chemin dans le conteneur :

docker run ... -v <host_data_root>:<host_data_root>:ro <container> ...

La même exigence d'accessibilité s'applique au <output_dir> écrit par toutes les actions.

Étape 1 — Fichier d'annotation

Fichier d'annotation ligne par ligne référencé par data_sources[*].data_file :

Si vous en possédez déjà un, pointez vers lui. Sinon générez-le via depth_net convert :

depth_net convert -e <convert_spec.yaml>

Modèle convert_spec.yaml (stéréo) :

data_root: <directory whose immediate children are scene folders that contain your image+depth files; convert walks data_root recursively but expects per-scene subdirectories at one level below>
image_dir_pattern: [<substring matching left image paths>]
right_dir_pattern: [<substring matching right image paths>]
depth_dir_pattern: [<substring matching GT disparity paths>]
nocc_dir_pattern: []                 # optional, occlusion mask paths
image_extension: '.png'  # always include the leading dot
depth_extension: '.png'  # form must match image_extension (the swap is a substring replace)
nocc_extension: ''
split_ratio: 0.0        # 0.0/1.0 = test-only; 0.8 = 80/20 train+val

convert parcourt data_root récursivement, sélectionne les chemins dont la chaîne de chemin contient tous les substrings dans image_dir_pattern (filtre ET), puis dérive les chemins droite / profondeur / masque en remplaçant image_dir_pattern[0] par le premier élément du pattern correspondant plus swap d'extension. Inspectez la disposition du répertoire de votre dataset et identifiez les substrings distinguant gauche, droite et GT (par ex. im0 vs im1 vs disp0GT pour Middlebury).

Étape 2 — Appairez model_type et dataset_name en fonction de vos données

Préférez la classe spécifique au dataset quand votre disposition correspond à une disposition supportée — elle applique les conventions de chemin spécifiques à la classe, les crops d'évaluation et (le cas échéant) la gestion des masques d'occlusion. Revenez à GenericDataset uniquement pour les dispositions qui ne correspondent à aucune classe enregistrée.

Voir Training Requirements → Formats pour la liste complète des classes enregistrées. La même valeur dataset_name s'applique dans les actions train et evaluate (qui utilisent toutes des annotations 3-colonnes ou 4-colonnes avec disparité GT). L'action evaluate côté déploiement suit la même règle — voir references/tao-deploy-foundation-stereo.md. Pour l'inference avec des annotations 2-colonnes (gauche + droite, pas de GT), utilisez dataset_name: GenericDataset indépendamment de la disposition des données — les classes spécifiques au dataset (Middlebury / Kitti / Eth3d / FSD / IsaacRealDataset / Crestereo) nécessitent une entrée 3-colonnes et rejettent les annotations 2-colonnes au niveau du dataloader. Pour l'inference avec des annotations 3-colonnes (gauche + droite + GT), la classe spécifique au dataset convient.

Étape 3 — Écrivez spec yaml à partir de Typical Spec Overrides

Copiez le bloc d'action depuis references/foundation-stereo-spec-overrides.md (spec_overrides par action, sources de données obligatoires). Remplacez :

• model.model_type de l'étape 2 (généralement FoundationStereo)
• dataset.<...>.data_sources[*].dataset_name de l'étape 2
• dataset.<...>.data_sources[*].data_file par le chemin de l'étape 1
• Pour evaluate côté déploiement : imposez dataset.test_dataset.batch_size: 1 (voir references/tao-deploy-foundation-stereo.md).

Cohérence de forme : le crop_size dans dataset.test_dataset.augmentation.crop_size doit correspondre à export.input_height / input_width pour que l'évaluateur du modèle entraîné et l'évaluateur TensorRT côté déploiement opèrent à la même forme — voir references/foundation-stereo-troubleshooting.md.

Étape 4 — Exécutez

docker run --gpus 'device=0' --shm-size 16G --ipc=host \
  --user $(id -u):$(id -g) \
  -v <data_root>:<data_root>:ro \
  -v <output_dir>:<output_dir> \
  <container> \
  depth_net <action> -e <spec.yaml>

Sans --user $(id -u):$(id -g) le conteneur écrit les sorties en tant que nobody:nogroup, ce qui bloque le nettoyage / réessai côté hôte.

Étape 5 — Vérifiez

• Code de sortie du conteneur 0
• Bloc kpi de status.json peuplé
• Pour train : inspectez train_loss par étape directement (le point d'entrée rapporte Execution status: PASS même quand la loss est NaN)
• Pour evaluate : fiez-vous à epe / bp1 / bp2 / bp3 / d1 / rmse (l'évaluateur émet aussi abs_rel / sq_rel / rmse_log qui ne sont pas significatifs pour la stéréo — voir references/foundation-stereo-parameters.md)
• Pour inference : artefacts sous results_dir

Pour les actions TAO Deploy TensorRT (gen_trt_engine, évaluation TensorRT et inference TensorRT), consultez d'abord references/tao-deploy-foundation-stereo.md. Les modèles de spec de déploiement se trouvent dans le dossier references/ de ce skill avec le préfixe spec_template_deploy_*.yaml.

Training Requirements

• Valeurs dataset_name valides pour les stereo data_sources (insensible à la casse) : FSD, IsaacRealDataset, Crestereo, Middlebury, Eth3d, Kitti, GenericDataset
• Métrique de monitoring : val/loss

Exigences de Dataset par Action

Typical Spec Overrides

Les overrides de source de données sont obligatoires pour chaque action — l'agent DOIT construire les chemins de source de données à partir du tableau Per-Action Dataset Requirements ci-dessus et les inclure dans spec_overrides. Chaque entrée data_sources est un dictionnaire avec deux champs obligatoires : data_file et dataset_name.

Voir references/foundation-stereo-spec-overrides.md pour les blocs complets spec_overrides par action (train, evaluate, export, gen_trt_engine, inference, quantize) avec les placeholders S3_TRAIN / S3_EVAL.

Eval Dataset

Optionnel. Dataset de validation configuré via dataset.val_dataset.data_sources (chaque entrée a besoin de data_file et dataset_name).

Important Parameters

Valeurs clés par défaut : model.model_type = FoundationStereo (seul type sélectionnable) ; model.encoder (niveau supérieur, pas sous stereo_backbone) défaut schema vitl mais le petit checkpoint NGC FS nécessite vits, override explicitement ; model.max_disparity par défaut 416 ; train.optim.lr par défaut 1e-4 ; train.precision fp32 (recommandé) ou fp16 (pas de bf16) ; export.batch_size par défaut -1. Le nom du champ workers est workers, pas num_workers.

Voir references/foundation-stereo-parameters.md pour le glossaire complet des paramètres (tous les champs model.*, dataset.*, train.*, export.* avec valeurs par défaut et plages) et la référence Evaluation Metrics (quel epe / bp* / d1 / rmse utiliser et pourquoi abs_rel / sq_rel / rmse_log ne sont pas significatifs pour la stéréo).

Multi-GPU / Multi-Node

Méthode de lancement : gérée par Lightning (processus python unique, Lightning crée les workers).

Même comportement DDP/FSDP que depth-net-mono. Multi-node nécessite les variables d'environnement WORLD_SIZE, NODE_RANK, MASTER_ADDR, MASTER_PORT.

Export / TRT Defaults

Types de données TRT FP32 / FP16. ONNX à forme statique (export.batch_size: 1) et ONNX dynamique par batch uniquement (export.batch_size: -1) supportent tous deux fp16 ; hauteur et largeur sont toujours épinglées à la forme de trace (les moteurs H/W-dynamiques ne sont pas supportés — construisez des moteurs séparés par (H, W)). Pour la version NGC (576×960), définissez export.batch_size: 1, export.opset_version: 17, export.on_cpu: True.

Voir references/foundation-stereo-export-trt-hardware.md pour les valeurs par défaut complètes d'export / TRT (les règles d'appairage opset-vs-on_cpu, notes de déterminisme, seuils de mémoire GPU on_cpu) et les exigences Hardware. Voir references/tao-deploy-foundation-stereo.md pour les trois chemins de déploiement supportés et le tableau de validation.

Référence TAO Deploy complète : tao-deploy-foundation-stereo.

Error Patterns

Problèmes courants : débordement de disparité (réduisez model.max_disparity) ; chemins préentraînés manquants (définissez les deux model.stereo_backbone.depth_anything_v2_pretrained_path et model.stereo_backbone.edgenext_pretrained_path) ; Key 'encoder' not in 'StereoBackBone' (encoder est le model.encoder niveau supérieur) ; Key 'dataset_name' is not in struct (chaque entrée data_sources a besoin à la fois de data_file et dataset_name) ; bash: exec: depth_net_stereo: not found (le point d'entrée est depth_net, pas de suffixe).

Voir references/foundation-stereo-troubleshooting.md pour les patterns d'erreur complets plus la discussion pyt-vs-deploy crop_size (le chemin evaluate pyt s'exécute à la résolution d'image native et ignore crop_size, avec les conseils de résolution Middlebury) et la règle Shape consistency.

Spec Param / Parent Model Inference

Les mappages d'inference spécifiques au modèle appartiennent à MD, pas à config.json. Les runners générés lisent ces mappages et les appliquent avec les aides SDK avant create_job() (reflète le flux ancien microservices infer_params.py). Pour parent_model / parent_model_folder, passez l'ID du job enfant train/export/AutoML en amont en tant que parent_job_id ; le SDK liste le dossier de résultat parent, filtre les artefacts de checkpoint et retourne le fichier ou dossier du modèle sélectionné. N'ajoutez pas ces mappages à config.json et ne patchchez pas les scripts runner générés pour deviner les chemins de checkpoint.

Voir references/foundation-stereo-spec-param-inference.md pour le tableau complet de mappages d'inference par action (train / evaluate / inference / export / gen_trt_engine / quantize, incluant le lien de chemin préentraîné train/destination et les mappages de checkpoint de reprise).