Ultralytics YOLO26-Depth 深度估计训练指南：Hypersim 合成室内深度数据集的获取、格式转换与实战用法

Ultralytics YOLO26-Depth 深度估计训练指南Hypersim 合成室内深度数据集的获取、格式转换与实战用法【免费下载链接】ultralyticsUltralytics YOLO26, YOLO11, YOLOv8 — object detection, instance segmentation, semantic segmentation, image classification, pose estimation, object tracking项目地址: https://gitcode.com/GitHub_Trending/ul/ultralytics本文围绕 Ultralytics 仓库中的 Hypersim 深度数据集文档docs/en/datasets/depth/hypersim.md展开讲解这个由 Apple 发布的照片级真实感合成室内场景数据集如何为 YOLO26-Depth 单目深度估计模型提供干净、稠密的逐像素深度监督。读完后你将掌握Hypersim 原始数据tonemap RGB 帧 depth_meters.hdf5如何转换为 Ultralytics 深度数据集格式、配套的 depth-hypersim.yaml 配置如何工作以及底层加载/编码实现save_depth_png、DepthDataset的关键细节从而能够独立完成从原始数据下载到yolo depth train的完整流程。数据集概述为什么选择全合成的 HypersimHypersim 是一个面向室内场景整体理解holistic indoor scene understanding的照片级真实感合成数据集其图像基于专业制作的 Evermotion 3D 室内模型进行光线追踪ray-tracing渲染每一帧都配有完美、稠密的逐像素深度真值。由于 Hypersim 是全合成数据每个像素都有精确的深度值不存在传感器噪声、缺失回波或测量伪影。这使它成为训练单目深度估计模型的优质室内几何来源——文档将其定位为 Ultralytics 深度训练混合数据multi-dataset mixture中的“干净稠密室内几何”补充项与带噪声的真实传感器数据如 LiDAR 重建形成互补。关键特性汇总光线追踪渲染的合成室内场景照片级真实感仅覆盖室内环境indoor only稠密、无噪声、无缺失值的逐像素深度真值深度范围以≤10 m为主含少量更大距离为 Ultralytics 深度训练混合数据贡献74,619张图像68,242 训练 / 6,377 验证。数据分为两个子集Train68,242 张图像配对的稠密深度图用于训练Val6,377 张图像配对的稠密深度图用于训练期间验证。每张 RGB 图像都配对一个经缩放的 uint16 深度 PNG遵循 Ultralytics 深度数据集格式第 0 值保留给无效像素PNG 整数值除以depth_scale——默认 1000——还原为米。获取原始数据与目录组织Hypersim不支持自动下载no autodownload约 1.9 TB 的按场景打包 ZIP 由 Apple 以 CC BY-SA 3.0 协议分发需要通过官方 ml-hypersim 仓库 的脚本下载该仓库的contrib/99991中还提供了选择性下载工具git clone https://github.com/apple/ml-hypersim cd ml-hypersim python code/python/tools/dataset_download_images.py --downloads_dir ./downloads --decompress_dir ./scenes下载解压后原始数据的对应关系是RGB 帧各场景目录下的frame.*.tonemap.jpg预览图目录名为{cam}_final_preview深度frame.*.depth_meters.hdf5。这里有一个关键的物理含义陷阱HDF5 中存储的数值是光线到相机中心的距离ray distance而不是垂直于成像平面的平面深度planar depth。因此保存前必须先做几何换算同时玻璃与天空等区域的像素为 NaN需映射为 0无效。训练/验证的划分应使用官方metadata_images_split_scene_v1.csv的场景划分表逐场景指派。参考转换脚本从 HDF5 到 Ultralytics 深度格式文档给出了完整的参考转换代码它把原始场景目录转换为标准布局datasets/depth-hypersim/{images,depth}/{train,val}import shutil from pathlib import Path import h5py import numpy as np from ultralytics.data.utils import save_depth_png W, H, FOCAL 1024, 768, 886.81 # Hypersim 相机内参 x, y np.meshgrid(np.linspace(-W / 2, W / 2, W), np.linspace(-H / 2, H / 2, H)) ray2plane (FOCAL / np.sqrt(x**2 y**2 FOCAL**2)).astype(np.float32) # 光线距离 → 平面深度 src, dst Path(scenes), Path(datasets/depth-hypersim) out train # 按 metadata_images_split_scene_v1.csv 逐场景指派 (dst / fimages/{out}).mkdir(parentsTrue, exist_okTrue) (dst / fdepth/{out}).mkdir(parentsTrue, exist_okTrue) for h5 in sorted(src.rglob(*.depth_meters.hdf5)): scene, cam, frame h5.parts[-4], h5.parent.name.split(_geometry)[0], h5.name.split(.)[1] rgb h5.parents[1] / f{cam}_final_preview / fframe.{frame}.tonemap.jpg dist np.asarray(h5py.File(h5)[dataset], np.float32) depth np.nan_to_num(dist * ray2plane, nan0.0) # NaN天空、玻璃→ 0 无效 name f{scene}_{cam}_{frame} save_depth_png(dst / fdepth/{out}/{name}.png, depth) shutil.copy(rgb, dst / fimages/{out}/{name}.jpg)逐点拆解这段脚本中值得注意的环节光线距离 → 平面深度换算ray2plane FOCAL / sqrt(x² y² FOCAL²)其中(x, y)是以图像中心为原点、以像素为单位的网格坐标FOCAL 886.81为 Hypersim 固定相机焦距对应 1024×768 分辨率。像素离光轴越远光线距离与平面深度差得越多这个逐像素乘数正是二者之间的换算系数。NaN 处理np.nan_to_num(..., nan0.0)把天空/玻璃等无回波区域编码为 0与 Ultralytics 深度格式中“0 无效像素从 loss 与指标计算中剔除”的约定完全一致。save_depth_png来自 ultralytics/data/utils.py 的官方工具函数。从源码看它以DEPTH_PNG_SCALE 1000ultralytics/data/utils.py 中定义的常量为默认缩放把以米为单位的 float32 深度图编码为 uint16 PNG对每个有效像素执行np.rint(depth * 1000)并保证最小为 10 保留给无效若任一像素换算后超过uint16上限 65535会直接抛出“Depth map exceeds the 65.535 meter PNG limit”错误——这意味着该格式默认支持 1 mm 分辨率、最深约 65.5 m而 Hypersim 以 ≤10 m 为主的室内深度完全落在此范围内无需自定义depth_scale。命名对齐RGB 与深度 PNG 共用同一文件 stem{scene}_{cam}_{frame}这是加载器配对的前提下文详述。数据集 YAML 与加载器行为仓库内置的配置 ultralytics/cfg/datasets/depth-hypersim.yaml 完整内容如下path: depth-hypersim # dataset root dir (relative to Ultralytics settings datasets_dir) train: images/train # train images (relative to path) 68242 images val: images/val # val images (relative to path) 6377 images nc: 1 names: 0: depth channels: 3字段含义参见 深度数据集格式总览字段值说明pathdepth-hypersim数据集根目录相对于 Ultralytics 设置的datasets_dirtrainimages/train68,242 张训练图像相对pathvalimages/val6,377 张验证图像相对pathnc/names1/{0: depth}深度任务恒为单类depthdepth_scale未设置缺省即取默认 1000对应 mm 级 uint16 PNG注意该 YAML没有depth_scale字段——这符合 Hypersim 转换后采用默认毫米约定的事实相比之下KITTI256、DIODE/TartanAir256、Virtual KITTI 2100等室外数据集因深度范围更大而显式设置了不同的depth_scale见 depth-kitti.yaml、depth-vkitti2.yaml。加载侧的实现位于 ultralytics/data/dataset.py 的DepthDataset类几个与 Hypersim 目录结构直接相关的行为值得了解深度文件配对规则_depth_path_fordataset.py把图像路径中最后一个images目录分量替换为depth优先取.png不存在则回退.npy。这解释了为什么转换脚本必须把深度 PNG 放在与images平行的depth/{train,val}下且 stem 一致。深度读取_load_depth调用 load_depthPNG 走“uint16 解码后除以depth_scale”路径读取时把depth_scale缺省值兜底为 1000。对齐与无效掩码get_image_and_label会把深度图用最近邻插值INTER_NEAREST对齐到缩放后的 RGB 尺寸——最近邻保证深度值不被插值平滑破坏深度≤ 0的像素在 loss 与指标计算中被剔除正好承接转换时把 NaN 写为 0 的约定。缓存键get_cache_hash把深度文件列表、图像列表和depth_scale一起纳入哈希dataset.py任何一对文件增删都会使旧缓存失效。在 YOLO26-Depth 中的角色Hypersim 是用于预训练 Ultralytics YOLO26-Depth 模型的训练来源之一。该预训练混合数据规模约2.19M 张图像横跨室内≤10 m到室外约 80 m深度范围Hypersim 在其中提供干净、稠密的室内几何补充噪声更大的真实传感器数据来源构成详见 深度数据集总览 的 Supported Datasets 一节。有两点值得强调没有独立的 Hypersim 保留基准该方案下不为 Hypersim 单设 held-out 评测集模型最终在标准单目深度基准上评估——NYU Depth V2、KITTI、Make3D、ETH3D 与 iBims-1。与无界 log 深度头的匹配从 深度任务页 的 A/B 实验看YOLO26-Depth 的深度头预测exp(logit)输出无界约 0.02–150 m避免了固定max_depth上限在单数据集微调实验中Hypersim深度以 ≤10 m 为主即使使用有界头也能取得 δ1 0.74说明其室内深度分布与有界假设兼容而混合训练时正是 Hypersim 这类室内数据与室外数据共同塑造了跨量程能力。训练用法按文档示例以图像尺寸 640 在 Hypersim 上训练 YOLO26n-Depth完整参数列表参见 Training 文档from ultralytics import YOLO # Load a model model YOLO(yolo26n-depth.pt) # load a pretrained model (recommended for training) # Train the model results model.train(datadepth-hypersim.yaml, epochs100, imgsz640)# Start training from a pretrained *.pt model yolo depth train datadepth-hypersim.yaml modelyolo26n-depth.pt epochs100 imgsz640对应的模型架构定义见 ultralytics/cfg/models/26/yolo26-depth.yaml。YOLO26 深度模型家族yolo26n-depth.pt、yolo26s-depth.pt、yolo26m-depth.pt、yolo26l-depth.pt、yolo26x-depth.pt会在首次使用时从 Ultralytics releases 自动下载预训练权重这些权重的预训练数据即包含 Hypersim 在内的多数据集混合集。引文与致谢如果你在研究或开发中使用了 Hypersim 数据集请引用其论文inproceedings{roberts2021hypersim, title{Hypersim: A Photorealistic Synthetic Dataset for Holistic Indoor Scene Understanding}, author{Mike Roberts and Jason Ramapuram and Anurag Ranjan and Atulit Kumar and Miguel Angel Bautista and Nathan Paczan and Russ Webb and Joshua M. Susskind}, booktitle{Proceedings of the IEEE/CVF International Conference on Computer Vision (ICCV)}, year{2021} }感谢 Hypersim 的创建者向计算机视觉社区开放了这个照片级真实感合成室内数据集。小结Hypersim 以 74,619 张68,242 train / 6,377 val无噪声稠密室内深度样本成为 YOLO26-Depth 约 2.19M 张预训练混合数据中的关键室内几何来源使用原始数据必须完成“光线距离 → 平面深度”的逐像素换算FOCAL / sqrt(x² y² FOCAL²)FOCAL886.81、NaN→0 的无效化以及按官方metadata_images_split_scene_v1.csv的场景级 train/val 划分转换产物遵循images/↔depth/平行目录、同名 stem、默认depth_scale1000的 Ultralytics 深度格式由 depth-hypersim.yaml 声明并经DepthDataset的路径替换、最近邻对齐与无效掩码机制消费最终通过yolo depth train datadepth-hypersim.yaml modelyolo26n-depth.pt epochs100 imgsz640即可在 Hypersim 上完成训练。【免费下载链接】ultralyticsUltralytics YOLO26, YOLO11, YOLOv8 — object detection, instance segmentation, semantic segmentation, image classification, pose estimation, object tracking项目地址: https://gitcode.com/GitHub_Trending/ul/ultralytics创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考