Depth Net Mono

Estimation de la profondeur monoculaire utilisant les architectures Metric Depth Anything v2 ou Relative Depth Anything. Prédit la profondeur par pixel à partir d'images RGB uniques.

Le chargement des checkpoints préentraînés varie selon la variante du modèle et le cas d'usage — voir la matrice Pretrained checkpoint loading — use case matrix dans references/parameters.md.

Les skills mono et stéréo invoquent tous deux la CLI TAO unifiée depth_net à l'intérieur du conteneur ; la famille mono/stéréo est sélectionnée via model.model_type (glossaire complet des paramètres dans references/parameters.md).

Pour les actions TAO Deploy TensorRT (gen_trt_engine, évaluation TensorRT et inférence TensorRT), consultez d'abord references/tao-deploy-depth-anything-v2.md. Le modèle de spécification de déploiement se trouve dans references/spec_template_deploy.yaml de ce skill.

Train Action Policy

Ce modèle est activé AutoML au niveau de la couche modèle. Avant de traiter toute demande d'étape d'entraînement, consultez references/skill_info.yaml et résolvez le remplacement d'exécution à partir d'une valeur explicite automl_policy ou d'une demande de workflow 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, appliquez la valeur par défaut auto. Quand automl_policy: auto, automl_enabled: true, et que schemas/train.schema.json et references/spec_template_train.yaml sont fournis, routez l'action train via tao-skill-bank:tao-run-automl par défaut avec le skill_dir de ce modèle. Conservez les remplacements 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 la spécification train et le modèle fournis sont manquants ; dans le cas du schéma manquant, signalez qu'AutoML est activé mais non exécutable pour ce modèle jusqu'à la génération des schémas.

Les actions hors entraînement telles que evaluate, inference, export et les flux de déploiement restent dans le skill du modèle. Le remplacement 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 RGB + fichiers de profondeur GT) doit être accessible depuis 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 les remplacements de spécification). Le runner gère le montage S3 → chemin-conteneur de manière transparente.
• docker run direct (par exemple, tests locaux) : 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 avez déjà un, pointez vers celui-ci. Sinon, générez via depth_net convert :

depth_net convert -e <convert_spec.yaml>

Modèle convert_spec.yaml :

data_root: <directory whose immediate children are scene/sample 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/RGB image paths>]
depth_dir_pattern: [<substring matching GT depth paths>]
image_extension: ''     # optional .endswith filter, e.g. '.jpg'
depth_extension: ''     # optional, swapped during depth derivation, e.g. '.png'
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 sous-chaînes dans image_dir_pattern (filtre ET), puis dérive le chemin de profondeur en remplaçant image_dir_pattern[0] par depth_dir_pattern[0] et image_extension par depth_extension. Inspectez la disposition des répertoires de votre dataset et identifiez la sous-chaîne distinguant les images RGB des fichiers de profondeur (par exemple, rgb_ vs sync_depth_).

data_root doit pointer vers le parent contenant les sous-répertoires par scène (par exemple, pour l'éval NYU, utilisez /data/nyu_v2/eval/test, pas /data/nyu_v2/eval/test/bathroom — ce dernier limite la recherche à une seule scène). Incluez toujours le point initial dans image_extension / depth_extension (par exemple, '.jpg' et non 'jpg') ; l'échange de sous-chaîne est sensible à la forme et une non-correspondance corrompt silencieusement les chemins dérivés.

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

Par défaut — classe générique pour chaque tâche :

Classe spécifique au dataset — basculez quand les données nécessitent un prétraitement que la classe générique n'effectue pas :

Utiliser une classe générique sur des données qui nécessitent une conversion d'unité (par exemple, des PNG uint16 NYU bruts) entraîne un masque valide vide et un train_loss = NaN silencieux. Faites correspondre la classe à l'encodage de vos données.

Étape 3 — Écrivez la spécification yaml à partir des remplacements de spécification

Copiez le bloc d'action de references/spec-overrides.md. Remplacez :

• model.model_type par l'étape 2
• dataset.<...>.data_sources[*].dataset_name par l'étape 2
• data_sources[*].data_file par le chemin de l'étape 1 (chemin S3 sous SDK runner, chemin hôte pour docker direct)
• Pour l'affinage métrique : appliquez également la Metric Variant Finetuning Recipe dans references/finetuning.md.

Pour l'entraînement mono, définissez train.precision: fp32 (recommandé) ou bf16 (Ampere SM80+, alternative).

É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, bloquant le nettoyage et les tentatives côté hôte.

Étape 5 — Vérifiez

• 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 train_loss = NaN (voir les Sanity-run PASS criteria dans references/finetuning.md)
• Pour evaluate / inference : artefacts sous results_dir

Pour les actions TAO Deploy TensorRT (gen_trt_engine, évaluation TensorRT et inférence TensorRT), consultez d'abord references/tao-deploy-depth-anything-v2.md. Les modèles de spécification 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 data_sources mono (insensible à la casse) : ThreeDVLM, FSD, NvCLIP, IssacStereo, Crestereo, Middlebury, NYUDV2, NYUDV2Relative, RelativeMonoDataset, MetricMonoDataset. NYUDV2 porte la GT de profondeur métrique (mètres) — appairez avec MetricDepthAnything ; NYUDV2Relative est les mêmes données avec des conventions de profondeur relative — appairez avec RelativeDepthAnything.
• Métrique de monitoring : val/loss

Dataset Requirements par action

Spec Overrides

Les remplacements de source de données sont obligatoires pour chaque action — construisez les chemins de source de données à partir du tableau Dataset Requirements par action ci-dessus et incluez-les dans spec_overrides ; chaque entrée data_sources est un dictionnaire avec les deux champs obligatoires data_file et dataset_name. Consultez references/spec-overrides.md pour les blocs complets train / evaluate / export / inference / quantize par action et les recommandations de précision.

Eval Dataset

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

Important Parameters

Glossaire complet des paramètres (model.*, train.*, dataset.*, export.*, champs inference.* avec options, défauts et sources) plus la matrice Pretrained checkpoint loading — use case matrix se trouvent dans references/parameters.md. Points de départ clés : model.model_type (par défaut MetricDepthAnything), model.encoder (par défaut vitl), train.optim.lr (par défaut 1e-4, AdamW), train.precision (fp32 recommandé), dataset.{train,val,test,infer}_dataset.augmentation.crop_size (par défaut [518, 518]).

Finetuning Recipes

Les recettes d'affinage des variantes Relative et Metric — incluant les clés de spécification requises, le bloc métrique dataset.{normalize_depth, min_depth, max_depth} requis dans les spécifications train ET export, les défauts appliqués par le trainer (clip_grad_norm: 0.1, warmup_steps: 20, weight_decay: 1e-4), les remplacements de sanity-run, et les Sanity-run PASS criteria pour détecter le train_loss = NaN silencieux — se trouvent dans references/finetuning.md. Les deux recettes utilisent train.optim.lr: 5e-6 avec LambdaLR (la valeur par défaut AdamW 1e-4 est trop agressive lors de l'affinage à partir d'une colonne vertébrale convergée/préentraînée).

Multi-GPU / Multi-Node

Méthode de lancement : Lightning-managed (processus python unique, Lightning génère les workers).

• ddp avec activation checkpointing : find_unused_parameters=False
• ddp sans : find_unused_parameters=True
• fsdp force la précision à FP16

Variables d'environnement multi-nœud (définies par orchestrator) : WORLD_SIZE, NODE_RANK, MASTER_ADDR, MASTER_PORT, NUM_GPU_PER_NODE.

Export / TRT Defaults

• Types de données TRT : FP32, BF16 (Ampere SM80+). FP16 n'est pas supporté pour la colonne vertébrale mono ViT-L.
• Précision TRT recommandée : bf16. Utilisez fp32 si le matériel BF16 n'est pas disponible.

Référence TAO Deploy complète : tao-deploy-depth-anything-v2.

Hardware

Minimum 1 GPU, recommandé 2 GPUs. 24 GB+ VRAM par GPU. L'encodeur ViT-Large consomme beaucoup de mémoire. Utilisez fp32 (recommandé) ou bf16 (Ampere SM80+, alternative) pour l'entraînement. L'activation checkpointing est disponible pour les entrées plus grandes.

Error Patterns

Les signatures d'échec courantes et les corrections — non-correspondance de plage de profondeur, poids préentraînés manquants, Key 'encoder' not in 'MonoBackBone', dataset_name manquant, depth_net_mono: not found, sourçage d'hyperparamètres de variante métrique et l'erreur ONNX refuse-to-overwrite lors de l'export — sont documentées dans references/troubleshooting.md.

Spec Param / Parent Model Inference

Les mappages d'inférence spécifiques au modèle (le tableau complet du champ spec par action depth_net_mono.config.json → fonction d'inférence, plus le guide de résolution parent_model / parent_job_id) se trouvent dans references/spec-param-inference.md. Ces mappages doivent être en MD, pas dans config.json ; les runners générés doivent lire cette référence et appliquer les mappages avec les aides SDK avant create_job().