YOLO26 单目深度估计使用指南

本文档基于 Ultralytics YOLO26 官方文档整理，专注于单目深度估计 的完整使用方法，包括推理、可视化、校准和常见问题处理。

目录

• 概述
• 环境准备
• 支持的深度模型
• 基本推理
• 深度图输出格式
• 深度可视化
• 深度校准
• 完整代码示例
• 参数速查表
• 常见问题排查

概述

YOLO26 深度估计模型使用 log-depth head（无界对数深度头） 架构，从单张 RGB 图像中预测逐像素的稠密深度图。

核心特性

• 单目深度估计：仅需一张 RGB 图像即可推断场景深度
• 对数深度输出：网络预测相对对数深度场，输出范围约 0.02 ~ 150 米，无固定上限
• 米制单位：深度值以米为单位，通过校准或微调获得绝对尺度
• 多种尺寸：提供 n / s / m / l / x 五种模型，覆盖从实时推理到高精度需求

环境准备

安装 Ultralytics

pip install ultralytics

NumPy 版本兼容性

如果运行代码时遇到以下错误：

RuntimeError: Numpy is not available
_ARRAY_API not found

说明你的 PyTorch 版本与 NumPy 2.x 不兼容，需要降级 NumPy：

pip install "numpy<2"

或者升级 PyTorch 到支持 NumPy 2.x 的版本：

pip install –upgrade torch torchvision torchaudio

验证安装

from ultralytics import YOLO
print("Ultralytics 安装成功")

支持的深度模型

首次运行时会自动下载对应的权重文件。

基本推理

图像深度估计

from ultralytics import YOLO

# 加载深度估计模型
model = YOLO("yolo26n-depth.pt")

# 对单张图像进行深度估计
results = model("image.jpg")

视频深度估计

results = model("video.mp4")

摄像头实时深度估计

results = model(0) # 0 为摄像头索引

批量推理

results = model(["image1.jpg", "image2.jpg", "image3.jpg"])

深度图输出格式

推理结果中的深度信息存储在 result.depth 属性中：

获取 NumPy 深度数据

depth = result.depth.data.cpu().numpy() # shape (H, W), float32, 单位：米

深度值特性

YOLO26 深度模型使用 log-depth head，具有以下特点：

• 输出范围约 0.02 ~ 150 米，无固定上限
• 网络预测的是相对对数深度场，绝对米数通过校准或微调设定
• 深度值可能跨越多个数量级，直接 min-max 归一化到 0-255 会丢失远距信息

深度可视化

Ultralytics 提供了内置的 colorize_depth 函数，推荐使用该函数进行深度图可视化，而非手动归一化。

导入方式

from ultralytics.utils.plotting import colorize_depth

模式一：自动范围着色（disparity 模式，默认）

使用逆深度归一化，将深度映射到第 2 和第 98 百分位之间：

depth = result.depth.data.cpu().numpy()
colored = colorize_depth(depth, cmap="spectral")
cv2.imwrite("depth_colored.png", colored)

模式二：固定范围着色（metric 模式）

在指定的 vmin / vmax 范围内线性归一化，颜色含义跨帧一致：

colored = colorize_depth(depth, vmin=0.0, vmax=20.0, cmap="inferno", mode="metric")
cv2.imwrite("depth_metric.png", colored)

模式三：与输入图像混合叠加

最简单的方式，一行代码实现深度与 RGB 图像的混合叠加：

result.save("depth_overlay.png")

colorize_depth 参数说明

色彩映射选择建议

深度校准

如果你的场景深度绝对值不准确，可以使用 model.calibrate() 进行尺度校准。校准不需要修改网络权重，只需提供带标签的数据集。

校准流程

from ultralytics import YOLO

# 加载模型
model = YOLO("yolo26s-depth.pt")

# 使用带深度标签的数据集进行校准
model.calibrate(data="path/to/your_dataset.yaml")

# 保存校准后的模型
model.save("yolo26s-depth-calibrated.pt")

使用校准后的模型

model = YOLO("yolo26s-depth-calibrated.pt")
results = model("image.jpg")

完整代码示例

示例一：基础深度可视化

import cv2
import numpy as np
from ultralytics import YOLO
from ultralytics.utils.plotting import colorize_depth

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

# 推理
results = model("https://ultralytics.com/images/bus.jpg")

for result in results:
# 获取深度图 (H, W), float32, 单位：米
depth = result.depth.data.cpu().numpy()

# 1. 保存原始深度图（uint16 PNG，毫米精度）
depth_uint16 = (depth * 1000).astype(np.uint16)
cv2.imwrite("depth_map_raw.png", depth_uint16)

# 2. 彩色深度图（disparity 模式，自动范围）
cv2.imwrite("depth_colored.png", colorize_depth(depth, cmap="spectral"))

# 3. 固定范围彩色图（0~20 米，颜色跨帧一致）
cv2.imwrite("depth_metric.png", colorize_depth(depth, vmin=0.0, vmax=20.0, cmap="inferno", mode="metric"))

# 4. 与输入图像混合叠加
result.save("depth_overlay.png")

print(f"深度图尺寸: {depth.shape}")
print(f"深度范围: {depth.min():.2f}m ~ {depth.max():.2f}m")

原图 深度图 彩色深度图 固定范围彩色图 输入图像混合叠加图·

示例二：视频深度估计

import cv2
from ultralytics import YOLO
from ultralytics.utils.plotting import colorize_depth

model = YOLO("yolo26n-depth.pt")
cap = cv2.VideoCapture("video.mp4")

# 获取视频属性
fps = int(cap.get(cv2.CAP_PROP_FPS))
width = int(cap.get(cv2.CAP_PROP_FRAME_WIDTH))
height = int(cap.get(cv2.CAP_PROP_FRAME_HEIGHT))

out = cv2.VideoWriter("depth_video.mp4", cv2.VideoWriter_fourcc(*"mp4v"), fps, (width, height))

while cap.isOpened():
ret, frame = cap.read()
if not ret:
break

results = model(frame, verbose=False)
for result in results:
depth = result.depth.data.cpu().numpy()
colored = colorize_depth(depth, cmap="inferno")
out.write(colored)

if cv2.waitKey(1) & 0xFF == ord("q"):
break

cap.release()
out.release()
cv2.destroyAllWindows()

示例三：深度统计分析

from ultralytics import YOLO

model = YOLO("yolo26n-depth.pt")
results = model("image.jpg")

for result in results:
depth = result.depth.data.cpu().numpy()

print("=== 深度统计 ===")
print(f"图像尺寸: {depth.shape}")
print(f"最小深度: {depth.min():.2f} m")
print(f"最大深度: {depth.max():.2f} m")
print(f"平均深度: {depth.mean():.2f} m")
print(f"中位深度: {float(__import__('numpy').median(depth)):.2f} m")
print(f"标准差: {depth.std():.2f} m")

# 深度区间统计
import numpy as np
bins = [0, 1, 5, 10, 20, 50, 100, float("inf")]
hist, _ = np.histogram(depth, bins=bins)
total = depth.size
print("\\n深度区间分布:")
for i in range(len(hist)):
label = f"{bins[i]}–{bins[i+1]}" if bins[i+1] != float("inf") else f"{bins[i]}+"
pct = hist[i] / total * 100
print(f" {label:>10} m: {pct:5.1f}%")

参数速查表

推理参数

模型选择建议

常见问题排查

1. 深度图全黑

原因：直接将 float32 深度数据传给 cv2.imwrite，PNG 只支持 uint8/uint16。

解决方案：

# 方式一：使用官方 colorize_depth 函数（推荐）
from ultralytics.utils.plotting import colorize_depth
cv2.imwrite("depth.png", colorize_depth(depth))

# 方式二：转为 uint16（毫米精度）
depth_uint16 = (depth * 1000).astype(np.uint16)
cv2.imwrite("depth.png", depth_uint16)

2. 深度值异常（过大或过小）

原因：log-depth head 输出的是相对深度，未经校准时绝对值可能不准确。

解决方案：

• 使用 model.calibrate() 进行尺度校准
• 使用 mode="disparity" 模式进行可视化（自动处理范围）

3. NumPy 不兼容

RuntimeError: Numpy is not available

解决方案：

pip install "numpy<2"

4. CUDA 内存不足（OOM）

CUDA out of memory

解决方案：

• 减小输入图像尺寸：model("image.jpg", imgsz=320)
• 使用更小的模型：yolo26n-depth.pt
• 使用 CPU 推理：model("image.jpg", device="cpu")

5. 模型文件不存在

FileNotFoundError: yolo26n-depth.pt

解决方案：确保模型文件路径正确，或让 Ultralytics 自动下载：

model = YOLO("yolo26n-depth.pt") # 首次运行会自动下载

本文档基于 Ultralytics YOLO26 官方文档整理，更多信息请参考 Ultralytics 官方文档。