Depth Net Fast Stereo

Estimation en temps réel de la profondeur stéréo à l'aide de FastFoundationStereo (FFS) — la variante commerciale distillée bp2 de FoundationStereo. Prédit les cartes de disparité à partir de paires d'images stéréo rectifiées avec largeurs élagées par couche pour l'inférence en temps réel.

Les compétences mono / stéréo / fast-stereo partagent l'interface CLI TAO unifiée depth_net ; FFS est sélectionné via model.model_type: FastFoundationStereo. FFS diffère de FoundationStereo uniquement par les largeurs élagées par couche et un chemin forward sérialisé ; tout le reste (point d'entrée, verbes d'action, classes de dataset, chaîne de déploiement) est identique à depth-net-stereo.

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

Train Action Policy

Ce modèle est activé AutoML au niveau du modèle. Avant de traiter toute requête d'étape train, consultez references/skill_info.yaml et résolvez le remplacement d'exécution à partir d'une valeur automl_policy explicite ou de la requête de 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 empaquetés, acheminez l'action train via tao-skill-bank:tao-run-automl par défaut avec le skill_dir de ce modèle. Préservez les remplacements de workflow/application pour les datasets, specs, répertoires de sortie, paramètres GPU/plateforme, checkpoints parents et automl_policy. Utilisez l'entraînement direct du modèle uniquement quand automl_policy: off ou que le schema/modèle train empaqueté est manquant ; dans le cas du schéma manquant, signalez qu'AutoML est activé mais non exécutable pour ce modèle jusqu'à ce que les schémas soient générés.

Les actions non-train comme evaluate, inference, export et les flux de déploiement restent dans cette compétence de modèle. Le remplacement automl_policy par exécution ne modifie pas les métadonnées du modèle.

Two Use Cases

FFS est livré avec un checkpoint commercial bp2 pré-entraîné (model_best_bp2_serialize.pth).

1. Raw deploy — utilisez le ckpt bp2 tel quel. Ignorez train ; exécutez inference / evaluate / export / gen_trt_engine directement avec le fichier bp2 comme checkpoint de l'action.
2. Finetune on user data — définissez train.pretrained_model_path sur le fichier bp2, entraînez sur les données utilisateur, puis vérifiez et déployez sur le ckpt résultant. La séquence complète de 7 actions (train → evaluate pyt → inference pyt → export → gen_trt_engine → inference deploy → evaluate deploy) est prise en charge.

Workflow

Prerequisites — data accessibility

Votre dataset (images gauche + droite + disparité GT pour train / evaluate, gauche + droite uniquement pour inference) doit être accessible de l'intérieur du conteneur :

• SDK runner: placez les fichiers aux chemins S3 que le runner résout (S3_TRAIN / S3_EVAL affichés dans les remplacements de spec).
• Direct docker run (par ex. test local): montez la racine du dataset hôte en lecture seule au même chemin in-conteneur :

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

La même exigence d'accessibilité s'applique à <output_dir> écrit par toutes les actions, et au chemin du checkpoint bp2.

Step 1 — Annotation file

Fichier d'annotation par ligne référencé par data_sources[*].data_file. Le schéma est identique à depth-net-stereo :

Générez via depth_net convert si nécessaire ; consultez la compétence depth-net-stereo pour le modèle convert_spec.yaml.

Step 2 — Pair model_type and dataset_name based on your data

Utilisez model_type: FastFoundationStereo pour FFS. Le choix dataset_name reflète la compétence stéréo — choisissez la classe spécifique au dataset quand votre disposition correspond à une disposition enregistrée, sinon GenericDataset.

Pour l'inférence avec annotations à 2 colonnes (gauche + droite, pas de GT), utilisez dataset_name: GenericDataset quel que soit la disposition.

Step 3 — Set the bp2 distilled width overrides

FFS nécessite 15 champs de remplacement de largeur de section de modèle dont les valeurs correspondent exactement au checkpoint commercial bp2. Omettre un champ revient à utiliser les valeurs par défaut TAO qui ne correspondent pas au ckpt bp2 et produisent des erreurs de non-concordance de forme au moment du forward.

model:
  model_type: FastFoundationStereo
  encoder: vitl
  hidden_dims: [128]                    # GRU 1 couche; NOT [128,128,128]
  n_gru_layers: 1                       # bp2 single-GRU
  corr_radius: 4
  corr_levels: 2
  n_downsample: 2
  valid_iters: 8
  max_disparity: 192                    # bp2 commercial; NOT 416 (full FS default)
  volume_dim: 28                       # bp2 ckpt invariant; NOT 32 (full FS default)
  mixed_precision: false                # see references/parameters.md
  gwc_feature_normalize: true           # see references/parameters.md

  # 15 bp2 distilled width overrides — copy as-is
  motion_encoder_widths: [56, 96, 16, 12]
  motion_encoder_final: 48
  gru_hidden: 60
  gru_gating_conv_widths: [100, 168]
  disp_head_input_dim: 60
  disp_head_intermediate: 36
  disp_head_pwconv1_widths: [212, 244]
  mask_widths: [32, 16]
  stem_2_widths: [12, 16]
  spx_2_gru_widths: [16, 12, 16, 24]
  spx_gru_out: 9
  classifier_mid: 14
  cnet_conv04_widths: [60, 48]
  cam_mid_channels: 8
  cost_agg_conv_patch_padding: [0, 0, 0]

Les modèles de spec à references/spec_template_*.yaml portent ce bloc comme source canonique.

Step 4 — Write spec yaml from the spec overrides

Copiez le bloc d'action de references/spec-overrides.md (dicts de remplacement Python par action plus le bloc FFS_MODEL_BLOCK partagé). Remplacez :

• model.model_type: FastFoundationStereo (déjà défini)
• dataset.<...>.data_sources[*].dataset_name de l'étape 2
• dataset.<...>.data_sources[*].data_file par le chemin de l'étape 1
• Pour les cas d'utilisation raw deploy (sans train) : définissez <action>.checkpoint sur le chemin du fichier bp2
• Pour les cas d'utilisation finetune : définissez train.pretrained_model_path sur le chemin du fichier bp2

Chained train → next action checkpoint path: Pour le chaînage Docker local (sans SDK runner), le checkpoint entraîné se trouve à <train.results_dir>/<task>/dn_model_latest.pth — Lightning ModelCheckpoint s'imbrique sous le nom de la tâche. Exemple : train.results_dir: /workspace/results/finetune/train produit /workspace/results/finetune/train/train/dn_model_latest.pth. Utilisez ce chemin imbriqué pour le <action>.checkpoint de l'action suivante. Les déploiements SDK runner résolvent ceci automatiquement via parent_job_id — voir references/parent-model-inference.md.

Shape consistency: crop_size dans dataset.test_dataset.augmentation.crop_size doit correspondre à export.input_height / input_width pour la comparabilité pyt-vs-deploy end-to-end — voir la table de formes dans references/tao-deploy-fast-foundation-stereo.md.

Step 5 — Run

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> \
  -v <bp2_ckpt_dir>:<bp2_ckpt_dir>:ro \
  <container> \
  depth_net <action> -e <spec.yaml>

Sans --user $(id -u):$(id -g) le conteneur écrit les sorties sous nobody:nogroup, bloquant le nettoyage / réessai côté hôte.

Pour la mise en garde du bind-mount local __pycache__ (assurance qualité / développement uniquement — effacement des fichiers .pyc obsolètes qui masquent le source patché), voir references/troubleshooting.md → « Local bind-mount tip ».

Step 6 — Verify

• Code de sortie du conteneur 0
• Bloc kpi de status.json rempli
• 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 sont non-significatifs pour la stéréo)
• Pour inference : artifacts sous results_dir
• Différence d'espace de noms KPI entre pyt et deploy : pyt evaluate écrit l'ensemble de métriques sous kpi.val/epe, kpi.val/bp1, etc. (espace de noms par le préfixe val/ de Lightning). Deploy evaluate (chemin du moteur TRT) écrit le même ensemble de métriques sous kpi.epe, kpi.bp1, etc. (pas de préfixe val/). Les scripts de vérification aval qui lisent status.json doivent gérer les deux formes.
• Validez la dérive sur votre propre dataset : si vous comparez TAO FFS deploy (gen_trt_engine + TRT evaluate) contre le chemin de déploiement FFS amont sur la même entrée, attendez une petite dérive de disparité moyenne absolue résiduelle (interaction TAO export graph + TRT 10.13 ; non améliourable au niveau du code source). La magnitude exacte dépend du dataset et du matériel — mesurez sur vos propres données et décidez si la dérive est acceptable pour votre tâche aval.

7-action deploy flow

train (optional)            → finetuned ckpt
evaluate (pyt)              → PyT eager EPE / bp on val GT
inference (pyt)             → PyT eager disparity samples (visual sanity)
export                      → static fp32 ONNX (recommended at 480×736 or 320×736)
gen_trt_engine             → fp16 TRT engine on static ONNX path
inference (deploy)         → TRT disparity samples
evaluate (deploy)          → TRT EPE / bp drift vs PyT eager fp32

Ignorez train pour raw-bp2 deploy. Les 6 actions restantes (ou les 4 verbes deploy-only à partir de export) couvrent les deux cas d'utilisation.

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

Training Requirements

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

Per-Action Dataset Requirements

Les remplacements de source de données sont obligatoires pour chaque action. Chaque entrée data_sources a besoin à la fois de data_file et dataset_name. Les champs de largeur model.* de l'étape 3 sont aussi obligatoires. Consultez references/spec-overrides.md pour les dicts de remplacement complets par action (finetune train, raw-bp2 evaluate / inference / export) et le bloc FFS_MODEL_BLOCK partagé.

Eval Dataset

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

Parameters, Metrics, Hardware

Consultez references/parameters.md pour le glossaire de paramètres complet (model.* / dataset.* / train.* commandes incluant max_disparity: 192, gwc_feature_normalize: true, mixed_precision: false, volume_dim: 28, valid_iters, save_raw_pfm), la table de métriques d'évaluation (epe / bp1 / bp2 / bp3 / d1 / rmse sont significatifs ; abs_rel / sq_rel / rmse_log ne le sont pas), les clés de spec multi-GPU / multi-node, et les exigences matérielles.

Export / TRT Defaults

export émet toujours une ONNX fp32 indépendamment de model.mixed_precision ; la sélection fp16 vs fp32 se fait à gen_trt_engine via gen_trt_engine.tensorrt.data_type. La précision TRT recommandée pour FFS-bp2 est fp16 sur le chemin ONNX à forme statique (dérive la plus faible). Le chemin à forme dynamique supporte à la fois fp32 (défaut ; parité avec statique-fp32) et fp16 (critique pour la latence multi-résolution ; dérive plus élevée, peut NaN sous certains états de checkpoint — revenez à fp32 si observé).

Consultez references/export-trt-defaults.md pour les valeurs par défaut TRT/ONNX complètes et la matrice de cas d'utilisation quatre-voies (export.batch_size × export.dynamic_hw ; dynamique H/W est FFS-uniquement). Consultez references/tao-deploy-fast-foundation-stereo.md pour la matrice de déploiement et les conseils de forme statique-vs-dynamique.

Troubleshooting

Consultez references/troubleshooting.md pour les motifs d'erreurs et les corrections, incluant shape mismatch au forward (remplacement de largeur manquant), gwc_feature_normalize manquant (TAO Core trop ancien), avertissement dynamic_hw: true sur export FS / mono, Key 'encoder' not in 'StereoBackBone', dataset_name manquant dans data_sources, disparité négative, dérive de disparité plus grande que prévu (manque de max_disparity: 192), depth_net_stereo: not found, crop_size pyt-eval décoratif, avertissement cosmétique Failed to import SAM3, et stride-incompatibility de déploiement dynamique silencieux.

Spec Param / Parent Model Inference

Les mappages d'inférence spécifiques au modèle appartiennent à cette compétence, pas à config.json. Les runners générés doivent appliquer les mappages avec les helpers SDK avant create_job(). Consultez references/parent-model-inference.md pour la table de mappages complète champ-spec-par-action → fonction-inférence.

Pour parent_model ou parent_model_folder, passez l'id de job enfant train / export / AutoML amont comme parent_job_id. Le SDK liste le dossier de résultat parent, filtre les artifacts de checkpoint, et retourne le fichier ou dossier de modèle sélectionné. Pour les cas d'utilisation raw-bp2 sans job train parent, définissez le champ <action>.checkpoint explicitement au chemin du fichier bp2. Ne patchez pas les scripts de runner générés pour deviner les chemins de checkpoint.