Ultralytics YOLO Depth8 数据集详解：8 张图快速验证单目深度估计训练管线

Depth8 是 Ultralytics 深度估计任务内置的最小调试数据集，由 8 张来自 SUN RGB-D 的室内 RGB-D 图像（4 训练 + 4 验证）组成，首次使用时会自动下载约 1.3 MB 的压缩包。读完本篇，你将掌握 Depth8 的目录布局、uint16 深度 PNG 格式约定、depth8.yaml 各字段含义，以及如何用 Python 或 CLI 在数秒内跑通 YOLO26 深度模型的完整 train / val 流程，并理解其底层的数据加载、验证指标与自动校准实现。

定位：只用于管线调试，不用于基准测试

Depth8 的定位非常明确——快速测试、调试和实验。它从 SUN RGB-D 数据集中采样 8 张图像，训练集与验证集各 4 张，且每个数据集中分别覆盖 Kinect v1 与 Kinect v2 两种传感器的采集（每种传感器各 2 张），保证深度图稠密、无伪影。由于归档仅 1.3 MB，yolo depth train data=depth8.yaml 触发首次下载后几秒钟即可开始训练，适合在切换到 SUN RGB-D 或 NYU Depth V2 等完整数据集之前，验证整条训练管线是否正确。

官方文档同时给出了一条重要边界提醒：

Depth8 仅用于管线测试，不用于基准评测——8 张图远不足以产生有统计意义的深度指标。需要代表性结果时，请使用完整的 NYU Depth V2 或 SUN RGB-D 验证集。

数据集结构：RGB 图像与 uint16 深度 PNG 配对

Depth8 遵循 Ultralytics 标准的深度数据集布局：RGB 图像与配对的 uint16 毫米级深度 PNG 按文件主名（stem）一一对应，并通过数据集级参数 depth_scale: 1000 将整数换算为米。

depth8-png/
├── images/
│   ├── train/  # 4 张 RGB 图像
│   └── val/    # 4 张 RGB 图像
└── depth/
    ├── train/  # 4 张 16 位 PNG 深度图
    └── val/    # 4 张 16 位 PNG 深度图

格式约定的关键事实（由 depth8.yaml 头部注释与 数据格式总览 共同确认）：

• 深度值为真实室内传感器采集，范围大约在 0.5 m 到 4 m，完全落在 SUN RGB-D 整体不超过 10 m 的深度范围内；
• uint16 PNG 的整数值除以 depth_scale 得到米，默认 1000 即 1 mm 分辨率，可表示 0.001～65.535 m 共 65,535 个正值；
• 编码 0 保留给无效像素（传感器噪声、天空、反光面等），加载后这些像素会被排除在损失与指标计算之外。

源码印证：深度文件的配对与加载

数据加载逻辑可以完整追踪到仓库源码中：

1. 路径推导：DepthDataset._depth_path_for 将图像路径中最后一个 images 目录分量替换为 depth，优先寻找 .png，找不到再回退 .npy。因此 images/train/xxx.jpg 天然对应 depth/train/xxx.png，无需额外映射文件。
2. 数值解码：load_depth 打开 PNG 后强制校验其为 16 位灰度（I / I;16 模式），再按 scale 除以得到米制 float32；DEPTH_PNG_SCALE = 1000 是全局默认值（见 utils.py 第 63 行）。
3. 分辨率对齐：get_image_and_label 中，若深度图分辨率与缩放后的 RGB 不一致，会以 cv2.INTER_NEAREST 最近邻插值对齐——最近邻能避免对离散深度值做双线性混合，防止产生物理上不可存在的中间深度。
4. 缓存键：get_cache_hash 将图像、深度文件路径和 depth_scale 一起纳入哈希，确保修改 depth_scale 后缓存不会误用旧数据。

数据集 YAML 完整配置

Depth8 的配置文件位于 ultralytics/cfg/datasets/depth8.yaml，全文如下（含仓库内注释）：

# Ultralytics 🚀 AGPL-3.0 License - https://ultralytics.com/license

# Depth8 dataset (8 clean-label indoor images from SUN RGB-D Kinect v1/v2, 4 train / 4 val) by Ultralytics
# uint16 PNG values are divided by depth_scale to produce meters. The default 1000 gives 65,535
# one-millimeter depth values from 0.001 to 65.535 m; code 0 is invalid.
# parent
# ├── ultralytics
# └── datasets
#     └── depth8-png ← downloads here (1.3 MB)
#         ├── images/{train,val}  # RGB images
#         └── depth/{train,val}   # paired 16-bit *.png depth maps (images/ -> depth/)

path: depth8-png # dataset root dir (relative to Ultralytics settings 'datasets_dir')
train: images/train # train images (relative to 'path') 4 images
val: images/val # val images (relative to 'path') 4 images

nc: 1
names:
  0: depth

channels: 3
depth_scale: 1000 # PNG value 1000 = 1 meter

# Download script/URL (optional)
download: https://github.com/ultralytics/assets/releases/download/v0.0.0/depth8-png.zip

各字段的作用：

字段	取值	说明
path	depth8-png	数据集根目录，相对于 Ultralytics 配置中的 datasets_dir，首次运行时自动下载解压
train / val	images/train / images/val	训练/验证图像路径（相对 path），深度图自动在 depth/ 平行目录中按 stem 配对
nc / names	1 / {0: depth}	深度任务固定单类，类名恒为 depth
channels	3	RGB 输入通道数
depth_scale	1000	PNG 整数单位每米，即 1 毫米分辨率；仅当 PNG 不遵循毫米约定时才需要修改（如 KITTI 用 256、Virtual KITTI 2 用 100）
download	GitHub Release URL	1.3 MB 归档的自动下载地址，下载逻辑在首次 yolo depth train data=depth8.yaml 时触发

训练与验证用法

在 Depth8 上训练 YOLO26n-depth 模型（图像尺寸 640）的两种方式，完整继承自官方文档：

# Python
from ultralytics import YOLO

# 加载预训练 YOLO26n-depth 模型
model = YOLO("yolo26n-depth.pt")

# 在 Depth8 上训练
results = model.train(data="depth8.yaml", epochs=100, imgsz=640)

# CLI：命令行训练 YOLO26n-depth
yolo depth train data=depth8.yaml model=yolo26n-depth.pt epochs=100 imgsz=640

更完整的训练参数说明可参考 YOLO 训练文档。

训练器在 Depth8 上实际做了什么

从源码结构看，depth 任务的训练链与检测任务共用主干，但有若干深度专属定制：

• DepthTrainer 继承自 DetectionTrainer，构造时强制 task = "depth"，并用 DepthModel 建模；preprocess_batch 将 batch["depth"] 保持为 float32，避免整数精度污染。
• 数据增强被主动裁剪：DepthDataset.build_transforms 将 mosaic、mixup、cutmix、copy_paste 全部置 0——这些以拼接/混合为核心的增强会破坏逐像素深度的物理一致性；验证阶段则用 LetterBox(scale_fill=True) 直接拉伸填充，避免黑边污染深度监督。
• 训练标签图：深度任务没有 bounding box 可画，plot_training_labels 被重写为训练集 GT 深度分布直方图（标注均值、中位数等统计量），输出为 labels.jpg。
• 自动校准：final_eval 在最终验证后调用 calibrate_checkpoint，在验证集上以闭式最小二乘拟合仅含缩放的对数仿射参数 d' = exp(a·log d + b)（a=1，仅拟合 b），并按“calibrate only if it helps”策略——只有当交叉验证的保留集 δ1 分数优于未校准时才写回 best.pt/last.pt。也就是说，即使只跑 8 张图的 Depth8，产出的检查点也自带尺度校准结果，模型开箱即输出米制深度。

验证指标

验证由 DepthValidator 完成，通过 DepthMetrics 累加器输出四个标准深度指标（对应 深度任务文档 的指标集）：

指标	含义	方向
delta1	满足 max(d̂/d, d/d̂) < 1.25 的像素占比	越大越好
abs_rel	平均绝对相对误差	越小越好
rmse	米制均方根误差	越小越好
silog	尺度不变对数误差	越小越好

验证进度条以 depth_val 行汇总输出（见 print_results），多卡 DDP 场景下各 rank 的累加器会 all-reduce 汇总后统一计算（gather_stats）。因此即便在 Depth8 这种极小数据集上跑 val，也能得到格式规范的四项指标——这正是它“验证完整 cycle”的价值所在；但再次强调，8 张图上的指标数值没有统计意义。

FAQ（源自官方文档）

Depth8 数据集的用途是什么？ 用于单目深度估计管线的快速测试与调试。8 张图像（4 训练 + 4 验证）、1.3 MB 自动下载的归档，可以在数秒内验证完整的 train / val / predict 循环——深度图配对加载、数据增强、损失计算与指标输出，之后再平滑放大到 SUN RGB-D 或 NYU Depth V2 等完整数据集。

Depth8 与完整 SUN RGB-D 有什么区别？ Depth8 从 SUN RGB-D 的 9,245 训练 / 1,090 验证图像中采样 8 张，优先挑选深度图干净、稠密的 Kinect v1/v2 采集。二者使用完全相同的 16 位 PNG 深度格式，所以在 Depth8 上能跑通的管线无需任何修改即可直接运行在完整数据集上；区别仅在于 Depth8 秒级下载且无需转换步骤。

能否用 Depth8 做基准评测？ 不能。样本量太小，不足以支撑有意义的模型对比，它只用于训练与评估管线的正确性检查。需要代表性深度指标时，请使用 NYU Depth V2 或 SUN RGB-D 的完整验证集。

引用与致谢

Depth8 采样自 SUN RGB-D，来源归属与引用细节见 SUN RGB-D 数据集页面；来源数据集未指定许可证。若在你的研究或开发工作中使用了 SUN RGB-D，请引用以下论文：

@inproceedings{song2015sunrgbd,
      title={SUN RGB-D: A RGB-D Scene Understanding Benchmark Suite},
      author={Song, Shuran and Lichtenberg, Samuel P. and Xiao, Jianxiong},
      booktitle={Proceedings of the IEEE Conference on Computer Vision and Pattern Recognition (CVPR)},
      year={2015}
}

小结

Depth8 以最小代价解决了深度估计项目的一个真实痛点：在投入完整数据集之前，用一条命令验证“数据加载 → 增强 → 损失 → 验证 → 校准”整条链路是否就绪。理解了它的 depth_scale 约定、images/ 与 depth/ 平行目录配对规则，以及训练器中自动裁剪的增强与自动尺度校准逻辑后，你就具备了把自定义室内/室外 RGB-D 数据接入 Ultralytics 深度数据集格式 的全部前置知识。