Оценка монокулярной глубины с Ultralytics YOLO#

Оценка монокулярной глубины предсказывает карту глубины для каждого пикселя по одному RGB-изображению. Каждый выходной пиксель содержит значение глубины в метрах, которое показывает предполагаемое расстояние от камеры до соответствующей точки поверхности.

На выходе модели оценки глубины получается плотная карта чисел с плавающей точкой формы (H, W), совмещенная с входным изображением. Такое попиксельное представление делает оценку монокулярной глубины подходящей для реконструкции 3D-сцен, навигации роботов, создания AR/VR-контента и любых приложений, которым нужна информация о пространственной структуре по изображению с одной камеры.

Смотри: Монокулярная оценка глубины с Ultralytics YOLO26 | Руководство по Python | Vision AI 🚀

Модели#

Ниже представлены модели оценки глубины YOLO26, предварительно обученные на широком наборе данных из разных датасетов (в помещении и на улице, ~2.19M изображений). Метрики в столбцах рассчитаны на тестовой выборке Eigen датасета NYU Depth V2.

Модели автоматически загружаются из последнего релиза Ultralytics при первом использовании.

• delta1^NYU — доля пикселей, для которых предсказанная глубина отличается от истинной не более чем в 1,25 раза. Метрика рассчитана на тестовой выборке Eigen датасета NYU Depth V2 (654 изображения) с TTA с несколькими масштабами и горизонтальным отражением, а также выравниванием методом наименьших квадратов в логарифмическом пространстве.
• Точность при одном масштабе без TTA можно воспроизвести с помощью yolo depth val model=yolo26n-depth.pt data=nyu-depth.yaml imgsz=768 device=0 (подставляй model= для каждого размера). Этот режим использует выравнивание по медиане (только масштаб) и дает более низкие значения delta1: 0.783 (n), 0.793 (s), 0.840 (m), 0.853 (l), 0.860 (x).
• abs_rel — средняя абсолютная относительная ошибка между предсказанными и истинными значениями глубины.
• rmse — среднеквадратичная ошибка в метрах.
• Скорость — задержка только на инференсе (без предварительной и последующей обработки) при imgsz=768, batch=1; указано среднее значение ± стандартное отклонение по замерам после прогрева. CPU ONNX — ONNX Runtime fp32 на 32-ядерном Intel Xeon (Skylake); T4 TensorRT10 — TensorRT fp16 на Tesla T4.
• params и FLOPs измерены при разрешении 768×768 — разрешении обучения выпущенных весов.

Смотри предварительные результаты на NYU Depth V2 в превью невыпущенной YOLO27.

Сравнение скорости с Depth Anything V2#

Depth Anything V2 — широко используемая открытая базовая модель для оценки монокулярной глубины. Ее основа DINOv2 с визуальным трансформером и декодер DPT требуют больших вычислительных ресурсов, поэтому при запуске на одной и той же Tesla T4 с TensorRT fp16 самая маленькая выпущенная модель Depth Anything V2 работает медленнее любой модели оценки глубины YOLO26 — включая YOLO26x-depth, число параметров которой более чем вдвое выше.

При разрешении ~768 px — imgsz=768 для YOLO26, на котором обучены выпущенные веса, и 770 px для Depth Anything V2, поскольку для основы DINOv2 требуется размер, кратный размеру патча 14:

При разрешении ~640 px — imgsz=640 и 644 px соответственно — порядок моделей не меняется, а YOLO26n-depth работает в 5.9 раза быстрее Depth Anything V2 Small:

• Задержка измерена только на инференсе при batch=1 с TensorRT fp16 на Tesla T4 — на той же тестовой системе, что и для таблицы моделей выше; здесь значения округлены до двух знаков после запятой. FPS — обратная величина неокругленной задержки. В столбцах Ускорение задержка Depth Anything V2 Small (20.99 мс) и Base (55.40 мс) делится на задержку YOLO26.
• Depth Anything V2 Small и Base — выпущенные контрольные точки ViT-S и ViT-B.
• Сравнение охватывает только задержку: эти два семейства моделей здесь не оцениваются по единому протоколу точности.

Диапазон глубины и логарифмическая голова оценки глубины#

Голова оценки глубины предсказывает exp(logit) — неограниченный (~0.02–150 м) — и разделяет форму сцены и абсолютный масштаб: сеть предсказывает относительное поле логарифмической глубины, а абсолютные значения в метрах задаются отдельным двухпараметрическим преобразованием (exp(a·log d + b)), которое определяется при оценке, с помощью простой калибровки или дообучения. Распространенная альтернатива — ограниченная голова sigmoid × max_depth, в архитектуру которой заложен фиксированный верхний предел. Поэтому глубина больше max_depth обрезается, что не позволяет обучаться на сценах с большой дальностью и предсказывать их.

Контролируемый A/B-тест: одни и те же данные, тот же график обучения, различается только голова. Обучение обеих голов с нуля на одинаковой смеси данных из помещений (≤10 м) и с улицы (≤80 м):

Ограниченная голова не может представлять большую часть уличных пикселей с глубиной >10 м, поэтому почти сразу перестает улучшаться; голова log обучается на всем диапазоне.

Проблема, которую решает такой подход: дообучение на одном датасете с разбивкой по диапазону глубины. Дообучение ограниченной головы (10 м) на отдельных датасетах работает, если данные укладываются в заданный предел, и приводит к резкому ухудшению, если выходят за него:

Резкое ухудшение происходит точно на границе ограничения. У головы log такой границы нет.

Выпущенные модели — качество на разных диапазонах. Семейство с головой log, доступное в выпущенных моделях, оценивалось на тестах с диапазоном глубины от 10 м (NYU, iBims-1) до 80 м (KITTI); приведена δ1 с выравниванием масштаба:

Оба столбца приведены без изменений из опубликованных данных. Для остальных строк использован протокол TTA и логарифмического выравнивания методом наименьших квадратов, описанный на страницах соответствующих датасетов. Валидатор в этом репозитории его не реализует, поэтому строку KITTI нельзя повторно измерить на тех же условиях; на странице KITTI приведены значения, измеренные на канонической выборке Eigen из 652 кадров.

Наибольший прирост наблюдается на уличных тестах с большей дальностью (KITTI, ETH3D) — именно там фиксированный предел в 10 м вредит сильнее всего; при этом качество на данных из помещений сохраняется.

Обучение#

Обучи YOLO26n-depth на датасете Depth8 в течение 100 эпох с размером изображения 640. Полный список доступных аргументов смотри на странице Configuration.

from ultralytics import YOLO

# Загрузить модель
model = YOLO("yolo26n-depth.yaml")  # создать новую модель из YAML
model = YOLO("yolo26n-depth.pt")  # загрузить предварительно обученную модель (рекомендуется для обучения)
model = YOLO("yolo26n-depth.yaml").load("yolo26n-depth.pt")  # создать модель из YAML и перенести веса

# Обучить модель
results = model.train(data="depth8.yaml", epochs=100, imgsz=640)

Полное описание режима train смотри на странице Train. Модели оценки глубины также можно обучать в облачной среде Ultralytics Platform.

Формат датасета#

Датасеты для оценки глубины сопоставляют каждому RGB-изображению масштабированную карту глубины в формате uint16 PNG или NPY с числами с плавающей точкой, где глубина задана в метрах. По умолчанию значения PNG указываются в миллиметрах; для датасетов с другой системой единиц в YAML задается depth_scale. Загрузчик формирует путь к карте глубины, заменяя компонент images на depth, и сначала ищет .png, а если его нет — .npy.

dataset/
├── images/
│   ├── train/
│   └── val/
└── depth/
    ├── train/
    └── val/

Например, изображению по пути images/train/scene_001.jpg соответствует карта глубины по пути depth/train/scene_001.png. Полную спецификацию формата смотри в руководстве по датасетам для оценки глубины.

Дообучение на собственных данных#

При адаптации предварительно обученной модели оценки глубины под пользовательский датасет уменьши скорость обучения и используй оптимизатор AdamW. Настройки оптимизатора по умолчанию рассчитаны на обучение с нуля; применение этих настроек к уже сошедшейся модели оценки глубины может привести к утрате предварительно изученных знаний и ухудшению результатов — особенно при дообучении на данных из одной предметной области.

from ultralytics import YOLO

model = YOLO("yolo26s-depth.pt")  # начни с предобученных весов

model.train(
    data="path/to/your_dataset.yaml",
    epochs=20,
    imgsz=640,
    optimizer="AdamW",
    lr0=1e-4,  # примерно в 100 раз ниже значения по умолчанию для обучения с нуля
    warmup_bias_lr=1e-4,  # также используй плавный разогрев
)

Дополнительные советы:

• Аугментация настраивается стандартными аргументами (degrees, translate, scale, shear, perspective, flipud, fliplr, hsv_h, hsv_s, hsv_v); геометрические преобразования и отражения одинаково применяются к парной карте глубины. Чтобы узнать точный рецепт, использованный для выпущенных весов YOLO26-Depth, проверь train_args, сохранённый в чекпойнте, — см. Проверка параметров обучения в чекпойнте YOLO26.
• mosaic, mixup, cutmix и copy_paste не реализованы для оценки глубины. Загрузчик набора данных глубины автоматически устанавливает вероятности этих преобразований в 0, поэтому передача этих аргументов ни на что не влияет. Эти аугментации не поддерживаются, поскольку объединяют несколько изображений, что привело бы к некорректным парным картам глубины.
• Любой диапазон глубины работает без дополнительной настройки. Модели с головой log предсказывают неограниченную глубину, поэтому без изменений адаптируются к данным с малым (макросъёмка) или большим диапазоном (съёмка на улице/в движении). Указание max_depth: в YAML-файле набора данных (в метрах) ограничивает значения GT-пикселей, учитываемых при расчёте метрик валидации.
• Сохраняй обобщающую способность. Если модель должна оставаться точной на сценах, не входивших в обучающую выборку, добавь в обучающие данные небольшую долю (~5–10%) разнообразных изображений общего назначения; это значительно уменьшит катастрофическое забывание при дообучении.
• Обучай с нуля (model=yolo26s-depth.yaml), только если твоя предметная область сильно отличается от исходной и у тебя большой набор данных: в этом случае подходит значение optimizer=auto по умолчанию, поскольку сохранять предобученные веса не требуется.

Калибровка масштаба глубины#

Голова оценки глубины разделяет форму (относительную структуру сцены) и масштаб (абсолютные значения в метрах). Если модель уже хорошо оценивает относительную глубину в твоих сценах, но абсолютные значения не подходят для твоей камеры, ты можешь за секунды скорректировать масштаб с помощью model.calibrate() — это замкнутая форма подгонки только масштаба лог-аффинного преобразования головы по небольшому размеченному набору данных. Подгонка применяется, только если она показывает лучший результат по δ1 на отложенных данных при кросс-валидации, без обучения градиентным спуском и изменения весов сети, поэтому относительная структура не может ухудшиться.

from ultralytics import YOLO

model = YOLO("yolo26s-depth.pt")

# Подгони масштаб на размеченной выборке (достаточно примерно 100 и более изображений), затем сохрани результат
model.calibrate(data="path/to/your_dataset.yaml")
model.save("yolo26s-depth-calibrated.pt")

Для калибровки нужна эталонная глубина, поэтому она выполняется на размеченной выборке — при инференсе без разметки провести её нельзя. Подгонка и оценка выполняются по тем же пикселям, которые используются для расчёта метрик валидации: значения GT, равные или превышающие max_depth из YAML-файла набора данных (по умолчанию 100 м), исключаются. Используй эту калибровку, когда относительная глубина уже оценивается хорошо, а неверен только масштаб/диапазон; если для твоей предметной области нужно изменить саму относительную структуру, вместо этого выполни дообучение.

model.calibrate() оценивает три варианта по δ1 исходного масштаба на отложенных изображениях, используя двухблочную кросс-валидацию максимум примерно на 200 изображениях из размеченной выборки, и записывает победивший вариант в модель:

• identity: исходный выход головы без калибровки.
• current: калибровка, которая уже есть у модели, например встроенная в опубликованные контрольные точки.
• scale-only: новый общий масштаб, повторно подогнанный по всем этим изображениям при выборе этого варианта.

Вариант identity сохраняется, если current или scale-only не превосходит его более чем на 0.002 δ1; в противном случае выбирается вариант с более высоким результатом из этих двух, а при равенстве сохраняется current. Таким образом, модель сохраняет имеющуюся калибровку, если только новый масштаб не показывает более высокий результат или ни одна из калибровок не превосходит исходный выход на указанную величину.

Во время обучения этот же выбор выполняется автоматически: после завершения model.train(...) контрольные точки best и last калибруются на валидационной выборке, чтобы сразу выдавать глубину в метрическом масштабе. Модель, обученная с нуля по YAML, не имеет калибровки, поэтому current совпадает с identity. Модель, дообученная на опубликованной контрольной точке, наследует её калибровку, которая участвует в сравнении как current.

Опубликованные контрольные точки yolo26*-depth.pt поставляются с уже встроенной калибровкой, подогнанной на смеси валидационных данных предобучения. Это единый общий масштаб для всех доменов, поэтому для наиболее точной абсолютной оценки глубины с конкретной камерой или в конкретном типе сцен запусти model.calibrate() на небольшой размеченной выборке из собственных данных.

Получение эталонных данных о глубине без камеры глубины#

Если в камере нет датчика глубины, её всё равно можно откалибровать. При калибровке подбирается единый масштаб для всего изображения, а пиксели со значением глубины 0 игнорируются, поэтому для каждого изображения достаточно нескольких измеренных точек.

1. Собери изображения. Сделай от 50 до 150 снимков камерой с теми же разрешением и настройками объектива, которые будешь использовать при работе, и помести их в dataset/images/val/. Для калибровки считывается раздел val.

2. Разметь глубину. Используй один из двух способов ниже. Оба сохраняют по одной карте глубины на изображение в dataset/depth/val/ в формате датасета.

image,x,y,meters
img_0001.jpg,352,453,3.15
img_0001.jpg,28,300,2.672

import csv
from collections import defaultdict
from pathlib import Path

import cv2
import numpy as np

points = defaultdict(list)
with open("points.csv") as f:  # columns: image, x, y, meters
    for row in csv.DictReader(f):
        points[row["image"]].append((int(row["x"]), int(row["y"]), float(row["meters"])))

for name, pts in points.items():
    h, w = cv2.imread(f"dataset/images/val/{name}").shape[:2]
    depth = np.zeros((h, w), np.uint16)  # 0 means no label
    r = max(h, w) // 768 + 1  # dot radius that survives the resize to imgsz=768
    for x, y, meters in pts:
        cv2.circle(depth, (x, y), r, round(meters * 100), -1)  # centimeters, matching depth_scale: 100
    out = Path("dataset/depth/val") / f"{Path(name).stem}.png"
    out.parent.mkdir(parents=True, exist_ok=True)
    cv2.imwrite(str(out), depth)

3. Создай YAML-файл датасета calib.yaml. depth_scale: 100 считывает PNG-файлы с глубиной в сантиметрах, созданные по измеренным точкам, и игнорируется для карт NPY:

   path: dataset
   train: images/val
   val: images/val
   depth_scale: 100 # PNG value 100 = 1 meter
   names:
       0: depth

4. Выполни калибровку и сохрани её, затем загрузи yolo26s-depth-calibrated.pt для предсказания или экспорта:

   from ultralytics import YOLO
   
   model = YOLO("yolo26s-depth.pt")
   model.calibrate(data="calib.yaml", imgsz=768)
   model.save("yolo26s-depth-calibrated.pt")

В тестах с yolo26s-depth.pt и 150 изображениями на камеру опубликованная калибровка отличалась на 4–46% от масштаба, подобранного по полной эталонной разметке для NYU, KITTI и камеры с узкоугольным объективом. Калибровка по 5 измеренным точкам на изображение отличалась от этого значения менее чем на 1%, а по разметке DA3METRIC-LARGE — менее чем на 7%. Увеличение числа изображений даёт больший эффект, чем увеличение числа точек на изображение: для 150 изображений с 1 точкой на каждом отклонение составило около 3%, а для 20 изображений с 5 точками на каждом достигало 9%.

Валидация#

Проверь точность обученной модели YOLO26n-depth на датасете для оценки глубины. Явно укажи data, чтобы при проверке использовался нужный YAML-файл датасета. Опубликованные веса обучены на imgsz=768 на изображениях, растянутых до квадрата, а не дополненных полями при сохранении пропорций. Для наилучшей точности выполняй проверку и предсказание с этим размером. Предсказание, проверка и model.calibrate() одинаково растягивают входное изображение.

from ultralytics import YOLO

# Загрузить модель
model = YOLO("yolo26n-depth.pt")  # загрузить официальную модель
model = YOLO("path/to/best.pt")  # загрузить пользовательскую модель

# Валидировать модель
metrics = model.val(data="nyu-depth.yaml")
metrics.delta1  # доля пикселей, отклонение которых не превышает порог δ=1.25
metrics.abs_rel  # средняя абсолютная относительная ошибка
metrics.rmse  # среднеквадратичная ошибка (в метрах)
metrics.silog  # логарифмическая ошибка, инвариантная к масштабу

Предсказание#

Используй обученную модель YOLO26n-depth для предсказаний на изображениях.

from ultralytics import YOLO

# Загрузить модель
model = YOLO("yolo26n-depth.pt")  # загрузить официальную модель
model = YOLO("path/to/best.pt")  # загрузить пользовательскую модель

# Получи предсказания с помощью модели
results = model("https://ultralytics.com/images/bus.jpg")  # получи предсказание для изображения

# Обратись к результатам
for result in results:
    depth_map = result.depth.data.cpu().numpy()  # torch.Tensor -> NumPy float32, форма (H, W), метры

Полное описание режима predict см. на странице Предсказание.

Результаты работы#

При оценке глубины YOLO возвращает один объект Results для каждого изображения. Каждый результат содержит одну плотную карту глубины с плавающей точкой для всего изображения.

Описание полей Results, специфичных для каждой задачи, см. в разделе Результаты предсказаний по задачам.

Глубина для каждого объекта при сегментации экземпляров#

Сочетай сегментацию экземпляров с оценкой глубины, чтобы определить расстояние до каждого обнаруженного объекта. Запусти обе модели на одном изображении с помощью retina_masks=True, чтобы маски имели исходное разрешение карты глубины, соответствующее разрешению изображения, а затем возьми медиану допустимых значений глубины внутри каждой маски.

from ultralytics import YOLO

image = "https://ultralytics.com/images/bus.jpg"
seg = YOLO("yolo26n-seg.pt")(image, retina_masks=True)[0]
depth = YOLO("yolo26n-depth.pt")(image)[0].depth.data  # (H, W) meters

if seg.masks is not None:
    for mask, cls in zip(seg.masks.data.bool(), seg.boxes.cls):
        values = depth[mask & (depth > 0)]  # valid depth pixels inside this mask
        if values.numel():
            print(f"{seg.names[int(cls)]}: {values.median():.2f} m")

Медиана устойчива к влиянию пикселей фона по краям маски, но описывает видимую поверхность объекта, а не его центр; точность зависит от масштаба глубины модели (см. Калибровка масштаба глубины).

Раскрашивание карты глубины#

Исходная карта глубины — это одноканальный массив чисел с плавающей точкой в метрах: он удобен для вычислений, но его сложно интерпретировать напрямую. Чтобы преобразовать его в цветное изображение, используй функцию colorize_depth из ultralytics.utils.plotting: она преобразует массив глубины (H, W) в цветное изображение BGR (H, W, 3) uint8 (недопустимые пиксели <= 0 отображаются чёрным).

result.plot() уже накладывает эту раскраску на входное изображение с параметрами по умолчанию (cmap="jet", mode="disparity"); вызывай colorize_depth напрямую, если тебе нужно отдельное цветное изображение глубины или другая цветовая карта либо нормализация.

import cv2

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

model = YOLO("yolo26n-depth.pt")
result = model("https://ultralytics.com/images/bus.jpg")[0]

depth = result.depth.data.cpu().numpy()  # (H, W) float32, meters

# Раскрась так, чтобы ближние объекты были тёплых цветов, и сохрани результат
cv2.imwrite("depth_colored.png", colorize_depth(depth, cmap="spectral"))  # (H, W, 3) BGR uint8

# Зафиксируй диапазон 0–20 м, чтобы один и тот же цвет соответствовал одному и тому же расстоянию на разных кадрах
cv2.imwrite("depth_metric.png", colorize_depth(depth, vmin=0.0, vmax=20.0, cmap="inferno", mode="metric"))

# Наложение с цветовой картой напрямую из объекта Results (используются cmap="jet", mode="disparity")
result.save("depth_overlay.png")

Во всех цветовых картах оттенки меняются от холодных/тёмных к тёплым/ярким. Параметр mode определяет, какой конец шкалы соответствует ближним объектам, а vmin/vmax фиксируют диапазон для разных кадров, чтобы один и тот же цвет всегда обозначал одно и то же расстояние.

Экспорт#

Экспортируй модель YOLO26n-depth в другой формат, например ONNX, CoreML и т. д.

from ultralytics import YOLO

# Загрузить модель
model = YOLO("yolo26n-depth.pt")  # загрузить официальную модель
model = YOLO("path/to/best.pt")  # загрузить пользовательскую модель

# Экспортировать модель
model.export(format="onnx")

Доступные форматы экспорта для оценки глубины YOLO26 перечислены в таблице ниже. Ты можешь экспортировать модель в любой формат с помощью аргумента format, например format='onnx' или format='engine'. Ты можешь напрямую выполнять предсказания или валидацию экспортированных моделей, например yolo predict model=yolo26n-depth.onnx. После завершения экспорта появятся примеры использования твоей модели.

nms=None по умолчанию выдаёт необработанные выходные данные для внешней NMS (YOLO26 сохраняет голову без NMS на Axelera). Укажи nms=False, чтобы выбрать доступную голову без NMS; неподдерживаемые форматы используют собственный путь вывода. Записи nms выше указывают форматы, в которые можно встроить NMS с помощью nms=True.

Полное описание export смотри на странице экспорта.

Часто задаваемые вопросы#