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

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

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

Модели#

Ниже представлены модели оценки глубины 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.train(...) лучшие и последние чекпойнты калибруются на валидационной выборке, поэтому сразу выдают глубину в метрическом масштабе.

Выпущенные чекпойнты 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. Укажи nms=False, чтобы выбрать доступную голову без NMS; неподдерживаемые форматы используют собственный путь вывода. Элементы nms выше обозначают форматы, в которые можно встроить NMS с помощью nms=True.

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

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