Оценка глубины

Определение

Задача depth предсказывает по одному RGB-изображению одно значение на каждый пиксель. LibreYOLO определяет это значение как относительную обратную глубину: больше — ближе к камере, а у самих чисел нет ни метрических единиц, ни масштаба, который сохранялся бы между двумя изображениями. Сравнивать глубину двух пикселей одного предсказания осмысленно; сравнивать значение со значением с другого изображения — нет.

Предсказание заполняет result.depth_map — структуру DepthMap с массивом (H, W) на исходном холсте изображения. .min, .max и .mean читают конечные значения, а .normalized() приводит карту к [0, 1] для отображения. result.boxes остаётся пустым, поэтому conf, iou и max_det ни на что не влияют, а save=True записывает изображение карты в псевдоцветах, а не аннотированную фотографию.

Модели

Следующие семейства поддерживают depth.

Depth Anything V2 сочетает энкодер DINOv2 с декодером DPT и служит здесь универсальным вариантом по умолчанию. Размер диктует лицензия не меньше, чем точность: чекпойнт Small идёт под Apache-2.0, а Base и Large — некоммерческие, так что перед выбором посмотрите таблицу чекпойнтов на его странице.

Depth Anything 3 портирует чекпойнт DA3MONO-LARGE — обычный трансформер без архитектурной специализации под глубину.

ZipDepth — компактный уровень: репараметризуемая CNN, дистиллированная из Depth Anything V2 Large, со вторым чекпойнтом, декодер которого обходится без операций gather и unfold — для NPU-компиляторов, где их нет.

MiDaS установил протокол оценки относительной глубины без дообучения, по которому измеряют другие семейства. Его чекпойнты s и l скачиваются с зеркал LibreYOLO по лицензии MIT издателя.

LibreMODUS приходит к глубине как к одной из целей any-to-any-модели, а не через отдельную голову. Ему нужен extra modus и собственный аутентифицированный аккаунт Hugging Face, и он не предлагает ни val(), ни export().

SenseNova-Vision генерирует карту глубины как изображение через диффузионный декод — из того же 7B-чекпойнта, что обслуживает шесть остальных его задач. Ему нужен extra sensenova, а его веса ограничены некоммерческим использованием; лицензия — на его странице.

Marigold V2 добавляет диффузионные адаптеры глубины с явно заданным кодированием глубины.

GTR предсказывает метрическую глубину и возвращает её как относительную обратную глубину, поэтому 1 / result.depth_map.data восстанавливает глубину в метрах для сцен, похожих на его обучающие данные. Он работает на базовом пакете, обучается и экспортируется в ONNX и TorchScript.

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

Веса скачиваются при первом использовании и кэшируются локально. Страницы моделей описывают требования к аутентификации и среде выполнения.

from libreyolo import LibreYOLO, SAMPLE_IMAGE model = LibreYOLO("LibreDepthAnythingV2s-depth.pt")result = model(SAMPLE_IMAGE, save=True) depth = result.depth_mapprint(depth.data.shape)              # (H, W) на исходном холстеprint(depth.min, depth.max, depth.mean)

from libreyolo import LibreYOLO, SAMPLE_IMAGE model = LibreYOLO("LibreDepthAnythingV2s-depth.pt")result = model(SAMPLE_IMAGE) depth = result.depth_mapraw = depth.data          # больше — ближе; без метрических единиц и масштабаgray = depth.normalized() # приведено к [0, 1] для визуализацииprint(raw.shape, float(gray.max()))

from libreyolo import LibreYOLO, SAMPLE_IMAGE # Тот же контракт задачи, но сеть намного меньше — рассчитана на edge-среды выполнения.model = LibreYOLO("LibreZipDepthb-depth.pt")result = model(SAMPLE_IMAGE) print(result.depth_map.data.shape)

Разрешение входа ограничивается каждым семейством. Depth Anything V2 и Depth Anything 3 используют сетку патчей DINOv2, поэтому imgsz должен делиться на 14 без остатка; LibreYOLO проверяет это до запуска. Results.plot() визуализирует результаты глубины. Источники, стриминг и обработка результатов описаны в разделе предсказания.

DepthMap.encoding по умолчанию равен inverse_depth, а также может быть depth или log_depth. Валидация учитывает кодирование перед аффинным выравниванием. Кодирование не придаёт относительным предсказаниям метрический масштаб.

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

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

dataset/  data.yaml  images/    val/room.jpg  depths/    val/room.png

path: datasetval: images/valdepths_dir: depthsnc: 1names: {0: depth}

Карты — одноканальные PNG или TIF либо .npy. Значения — обычная глубина в единицах, единых для всего датасета, а пиксели 0, отрицательные, NaN и бесконечные помечают невалидные образцы, которые исключаются из метрик. Целочисленные карты делятся на depth_scale, по умолчанию 256.0 — соглашение для 16-битных PNG; карты .npy с плавающей точкой используются как есть. depth_stem_suffix и depth_mask_suffix покрывают датасеты, где файлы глубины или маски валидности называются иначе. Полный контракт — в разделе форматы датасетов.

Обучение

GTR — единственное семейство глубины, которое поддерживает обучение: train() на чекпойнте -depth запускает рецепт обучения из исходного проекта, описанный на странице модели. Для остальных семейств train() вызывает NotImplementedError. На странице каждой модели указан скрипт конверсии, который превращает чекпойнт, обученный в исходном проекте, в формат для загрузки LibreYOLO.

Валидация

val() запускает общий валидатор глубины. У относительной глубины нет абсолютного масштаба, поэтому каждое предсказание сначала подгоняется к обратной величине своей эталонной разметки (ground truth) — масштаб и сдвиг подбираются методом наименьших квадратов отдельно для каждого изображения, — а затем обратным преобразованием возвращается к глубине. Каждая метрика ниже считается по такой выровненной карте для каждого изображения и усредняется по датасету, причём учитываются только пиксели, помеченные датасетом как валидные.

from libreyolo import LibreYOLO model = LibreYOLO("LibreDepthAnythingV2s-depth.pt")metrics = model.val(data="my-dataset.yaml") print(metrics["metrics/abs_rel"])print(metrics["metrics/rmse"])print(metrics["metrics/delta1"])   # fitnessprint(metrics["metrics/delta2"], metrics["metrics/delta3"])

metrics/abs_rel — средняя абсолютная относительная ошибка, остаток, делённый на эталонную глубину; меньше — лучше. metrics/rmse — среднеквадратичная ошибка в собственных единицах глубины датасета, тоже меньше — лучше. metrics/delta1, metrics/delta2 и metrics/delta3 — пороговые accuracy: доля валидных пикселей, у которых отношение к эталону, взятое в ту сторону, где оно больше, оказывается меньше 1.25, 1.25 в квадрате и 1.25 в кубе, так что больше — лучше. metrics/delta1 — это ещё и fitness, число, по которому выбирается лучший чекпойнт.

Экспорт

Экспортированная модель глубины загружается обратно через LibreYOLO() по суффиксу файла, поэтому файл .onnx или .engine ведёт себя как чекпойнт и возвращает тот же Results, только с depth_map вместо рамок.

from libreyolo import LibreYOLO model = LibreYOLO("LibreDepthAnythingV2s-depth.pt")model.export(format="onnx")

from libreyolo import LibreYOLO, SAMPLE_IMAGE # Фабрика выбирает загрузчик по суффиксу файла, поэтому экспортированный# артефакт загружается как любой чекпойнт и возвращает тот же объект Results.model = LibreYOLO("LibreDepthAnythingV2s-depth.onnx")result = model(SAMPLE_IMAGE) print(result.depth_map.data.shape)

Покрытие различается по семействам, а Depth Anything 3 отклоняет любой формат вне своего проверенного набора, вместо того чтобы пытаться выполнить непроверенную конвертацию. Прежде чем остановиться на целевом формате, посмотрите страницу модели и полную матрицу экспорта. LibreMODUS и SenseNova-Vision не экспортируются вовсе. В разделе экспорт перечислены аргументы, которые принимает каждый формат.