tao-train-foundation-stereo

Depth Net Stereo

FoundationStereo アーキテクチャを使用したステレオ深度推定です。ステレオ画像ペアから視差マップを予測し、3D 再構成に使用します。

事前学習済みの Depth Anything v2 エンコーダーと EdgeNeXt エンコーダーを使用します。model.stereo_backbone.depth_anything_v2_pretrained_path と model.stereo_backbone.edgenext_pretrained_path を設定してください。

モノとステレオの両方のスキルは、コンテナ内で統合 TAO depth_net CLI を呼び出します。モノ／ステレオのどちらのファミリーを使用するかは、model.model_type（例：FoundationStereo）で選択します。

TAO Deploy の TensorRT アクション（gen_trt_engine、TensorRT の evaluate、TensorRT の inference）については、まず references/tao-deploy-foundation-stereo.md をお読みください。デプロイ仕様テンプレートは、このスキルの references/spec_template_deploy.yaml にあります。

Train アクションのポリシー

このモデルは、モデルレイヤーで AutoML が有効になっています。train ステージのリクエストを処理する前に、references/skill_info.yaml を読み、明示的な automl_policy の値またはユーザーのワークフローリクエストから、実行時の上書き設定を決定してください。「AutoML をオフにする」、「AutoML を無効にする」、「HPO なし」、「通常のトレーニング」などの表現は、この実行に限り automl_policy: off として扱ってください。それ以外の場合は、既定で auto にします。automl_policy: auto、automl_enabled: true、および schemas/train.schema.json と references/spec_template_train.yaml の両方がパッケージに含まれている場合は、既定でこのモデルの skill_dir を指定して tao-skill-bank:tao-run-automl 経由で train アクションを実行してください。データセット、仕様、出力ディレクトリ、GPU／プラットフォーム設定、親チェックポイント、automl_policy に関するワークフロー／アプリケーションの上書き設定は保持してください。モデルの直接トレーニングを行うのは、automl_policy: off の場合、またはパッケージに train スキーマ／テンプレートが含まれていない場合に限ります。スキーマがない場合は、AutoML は有効ですが、スキーマが生成されるまではこのモデルで実行できないことを報告してください。

evaluate、inference、export、デプロイフローなど、train 以外のアクションは引き続きこのモデルスキルで実行します。実行ごとの automl_policy 上書き設定によって、モデルのメタデータが変更されることはありません。

ワークフロー

前提条件 — データへのアクセス

データセット（左画像＋右画像＋GT 視差）には、コンテナ内からアクセスできる必要があります。

• SDK runner：runner が解決する S3 パスにファイルを配置します（一般的な仕様の上書き設定に示されている S3_TRAIN／S3_EVAL プレースホルダー）。runner が S3 からコンテナパスへのマウントを透過的に処理します。
• 直接 docker run を実行する場合（例：ローカルテスト）、ホスト上のデータセットルートを同じコンテナ内パスに読み取り専用でマウントします。

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

同じアクセス要件は、すべてのアクションが書き込む <output_dir> にも適用されます。

ステップ 1 — アノテーションファイル

data_sources[*].data_file で指定する、1 行ごとのアノテーションファイルです。

列数	形式	用途
2	<left> <right>	ステレオ推論（GT なし）
3	<left> <right> <disparity>	GT ありのステレオ
4	<left> <right> <disparity> <occlusion_mask>	GT とオクルージョンマスクありのステレオ

すでにファイルがある場合は、そのファイルを指定してください。ない場合は、depth_net convert で生成します。

depth_net convert -e <convert_spec.yaml>

convert_spec.yaml テンプレート（ステレオ）：

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 は data_root を再帰的に走査し、パス文字列に image_dir_pattern のすべての部分文字列が含まれるパスを選択します（AND フィルター）。次に、image_dir_pattern[0] を対応するパターンの先頭要素に置き換え、拡張子を変更して、右画像／深度／マスクのパスを導出します。データセットのディレクトリ構造を確認し、左画像、右画像、GT を区別する部分文字列を特定してください（例：Middlebury の場合は im0、im1、disp0GT）。

ステップ 2 — データに基づいて model_type と dataset_name を組み合わせます

データのレイアウトが対応しているものと一致する場合は、データセット固有のクラスを優先してください。クラス固有のパス規約、評価用クロップ、該当する場合はオクルージョンマスクの処理が適用されます。登録済みのどのクラスにも一致しないレイアウトの場合に限り、GenericDataset にフォールバックしてください。

データカテゴリ	model_type	dataset_name
Middlebury データ	FoundationStereo	Middlebury
KITTI データ	FoundationStereo	Kitti
ETH3D データ	FoundationStereo	Eth3d
FSD 合成データ	FoundationStereo	FSD
IsaacReal 合成データ	FoundationStereo	IsaacRealDataset
Crestereo 合成データ	FoundationStereo	Crestereo
その他／非標準レイアウト	FoundationStereo	GenericDataset

登録済みクラスの一覧は、Training Requirements → Formats を参照してください。train と evaluate の各アクションでは、同じ dataset_name の値を使用します（いずれも GT 視差を含む 3 列または 4 列のアノテーションを使用します）。deploy 側の evaluate アクションにも同じルールが適用されます。references/tao-deploy-foundation-stereo.md を参照してください。2 列のアノテーション（left + right、GT なし）を使用した推論では、データレイアウトに関係なく dataset_name: GenericDataset を使用してください。データセット固有のクラス（Middlebury / Kitti / Eth3d / FSD / IsaacRealDataset / Crestereo）は 3 列入力を必須とし、データローダーレベルで 2 列のアノテーションを拒否します。3 列のアノテーション（left + right + GT）を使用した推論では、データセット固有のクラスを使用できます。

ステップ 3 — Typical Spec Overrides から spec yaml を作成します

references/foundation-stereo-spec-overrides.md から、アクションごとのブロック（アクションごとの spec_overrides、必須データソース）をコピーします。以下を置き換えます。

• model.model_type をステップ 2 の値に置き換えます（通常は FoundationStereo）。
• dataset.<...>.data_sources[*].dataset_name をステップ 2 の値に置き換えます。
• dataset.<...>.data_sources[*].data_file をステップ 1 のパスに置き換えます。
• deploy 側の evaluate では、dataset.test_dataset.batch_size: 1 を必ず設定します（references/tao-deploy-foundation-stereo.md を参照してください）。

形状の整合性：dataset.test_dataset.augmentation.crop_size の crop_size は、export.input_height / input_width と一致させてください。これにより、学習済みモデルの評価器と deploy 側の TensorRT 評価器が同じ形状で動作します。references/foundation-stereo-troubleshooting.md を参照してください。

ステップ 4 — 実行します

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>

--user $(id -u):$(id -g) を指定しない場合、コンテナは出力を nobody:nogroup として書き込むため、ホスト側でのクリーンアップや再試行ができなくなります。

ステップ 5 — 確認します

• コンテナの終了コードが 0 であること
• status.json の kpi ブロックに値が入力されていること
• train の場合：各ステップの train_loss を直接確認してください（loss が NaN でも、エントリーポイントは Execution status: PASS を報告します）。
• evaluate の場合：epe / bp1 / bp2 / bp3 / d1 / rmse を確認してください（評価器は abs_rel / sq_rel / rmse_log も出力しますが、ステレオでは意味のある値ではありません。references/foundation-stereo-parameters.md を参照してください）。
• inference の場合：results_dir 内の成果物を確認してください。

TAO Deploy の TensorRT アクション（gen_trt_engine、TensorRT の evaluate、TensorRT の inference）については、まず references/tao-deploy-foundation-stereo.md をお読みください。deploy 用の spec テンプレートは、このスキルの references/ フォルダーにあり、spec_template_deploy_*.yaml というプレフィックスが付いています。

Training Requirements

• ステレオの data_sources で有効な dataset_name の値（大文字小文字を区別しません）：FSD、IsaacRealDataset、Crestereo、Middlebury、Eth3d、Kitti、GenericDataset
• 監視メトリクス： val/loss

アクションごとのデータセット要件

アクション	仕様キー	ソース	ファイル	リスト？
evaluate	dataset.test_dataset.data_sources	eval_dataset	data_file: annotations.txt + dataset_name	はい
inference	dataset.infer_dataset.data_sources	inference_dataset	data_file: annotations.txt + dataset_name	はい
quantize	dataset.train_dataset.data_sources	train_datasets	data_file: annotations.txt + dataset_name	はい
quantize	dataset.val_dataset.data_sources	eval_dataset	data_file: annotations.txt + dataset_name	はい
quantize	dataset.quant_calibration_dataset.images_dir	train_datasets	images.tar.gz	いいえ
train	dataset.train_dataset.data_sources	train_datasets	data_file: annotations.txt + dataset_name	はい
train	dataset.val_dataset.data_sources	eval_dataset	data_file: annotations.txt + dataset_name	はい

一般的な仕様のオーバーライド

データソースのオーバーライドはすべてのアクションで必須です。エージェントは、上記の「アクションごとのデータセット要件」テーブルに基づいてデータソースのパスを構築し、spec_overrides に含める必要があります。各 data_sources エントリーは、data_file と dataset_name の2つの必須フィールドを持つ辞書です。

S3_TRAIN／S3_EVAL のプレースホルダーを含む、アクションごとの spec_overrides ブロック（train、evaluate、export、gen_trt_engine、inference、quantize）の全容については、references/foundation-stereo-spec-overrides.md を参照してください。

評価用データセット

任意です。検証用データセットは dataset.val_dataset.data_sources で設定します（各エントリーには data_file と dataset_name が必要です）。

重要なパラメーター

主なデフォルト値：model.model_type は FoundationStereo（選択できるタイプはこれのみ）、model.encoder（トップレベルであり、stereo_backbone の配下ではありません）のスキーマ上のデフォルトは vitl ですが、FS small NGC ckpt では vits が必要なため、明示的にオーバーライドしてください。model.max_disparity のデフォルトは 416、train.optim.lr のデフォルトは 1e-4、train.precision は fp32（推奨）または fp16（bf16 は不可）、export.batch_size のデフォルトは -1 です。workers フィールド名は num_workers ではなく workers です。

すべての model.*、dataset.*、train.*、export.* フィールドのデフォルト値と範囲を含むパラメーター用語集の全容と、信頼すべき epe／bp*／d1／rmse およびステレオでは abs_rel／sq_rel／rmse_log が意味をなさない理由については、references/foundation-stereo-parameters.md を参照してください。

マルチ GPU／マルチノード

起動方式： Lightning 管理（単一の python プロセスで Lightning がワーカーを起動します）。

仕様キー	説明	デフォルト
train.num_gpus	GPU 数	1
train.gpu_ids	GPU デバイスのインデックス	[0]
train.num_nodes	ノード数	1
train.distributed_strategy	ddp または fsdp	ddp

depth-net-mono と同じ DDP／FSDP の動作です。マルチノードには WORLD_SIZE、NODE_RANK、MASTER_ADDR、MASTER_PORT の環境変数が必要です。

エクスポート／TRT のデフォルト

TRT のデータ型は FP32／FP16 です。静的形状 ONNX（export.batch_size: 1）と、バッチのみ動的な ONNX（export.batch_size: -1）はいずれも fp16 をサポートします。高さと幅は常にトレース時の形状に固定されます（H／W 動的エンジンはサポートされていません。H と W の各組み合わせに対して個別のエンジンを構築してください）。NGC リリース（576×960）では、export.batch_size: 1、export.opset_version: 17、export.on_cpu: True を設定してください。

エクスポート／TRT のデフォルト設定全般（opset と on_cpu の組み合わせルール、決定性に関する注意事項、on_cpu の GPU メモリーしきい値）およびハードウェア要件については、references/foundation-stereo-export-trt-hardware.md を参照してください。サポートされている3つのデプロイ方法と検証テーブルについては、references/tao-deploy-foundation-stereo.md を参照してください。

TAO Deploy のリファレンス全文：tao-deploy-foundation-stereo.

エラーパターン

よくある問題：視差のオーバーフロー（model.max_disparity を小さくしてください）；事前学習済みモデルのパスがない（model.stereo_backbone.depth_anything_v2_pretrained_path と model.stereo_backbone.edgenext_pretrained_path の両方を設定してください）；Key 'encoder' not in 'StereoBackBone'（encoder はトップレベルの model.encoder にあります）；Key 'dataset_name' is not in struct（各 data_sources エントリーには data_file と dataset_name の両方が必要です）；bash: exec: depth_net_stereo: not found（エントリーポイントは depth_net で、サフィックスは付きません）。

エラーパターンの全容に加え、pyt と deploy の crop_size に関する説明（pyt の evaluate パスはネイティブ画像解像度で実行され、crop_size を無視します。Middlebury の解像度に関するガイダンスを含みます）および Shape consistency ルールについては、references/foundation-stereo-troubleshooting.md を参照してください。

Spec Param / Parent Model の推論

モデル固有の推論マッピングは config.json ではなく、MD に記述します。生成されたランナーはこれらのマッピングを読み込み、create_job() の前に SDK ヘルパーを使って適用します（以前のマイクロサービスの infer_params.py の処理を再現します）。parent_model / parent_model_folder については、上流の train/export/AutoML 子ジョブ ID を parent_job_id として渡してください。SDK は親の結果フォルダーを一覧表示し、チェックポイントのアーティファクトをフィルターして、選択されたモデルファイルまたはフォルダーを返します。これらのマッピングを config.json に戻したり、チェックポイントのパスを推測するために生成されたランナースクリプトを変更したりしないでください。

アクション別の推論マッピング表（train / evaluate / inference / export / gen_trt_engine / quantize。train の事前学習済みパスのリンク先／保存先と、再開用チェックポイントのマッピングを含みます）の全容については、references/foundation-stereo-spec-param-inference.md を参照してください。