Снимаем карту глубины Orbbec с Python и OpenCV за 15 минут

Камеры глубины Orbbec давно вышли из лабораторий: трекинг людей на складе, объёмная съёмка, контроль габаритов на конвейере. Чтобы начать работать с ними, не нужны C++ и неделя настройки: официальный пакет pyorbbecsdk ставится через pip, а кадры приезжают в Python как обычные массивы numpy. Ниже — минимальный путь от камеры в коробке до окна с цветной картой глубины и сохранённого 16-битного PNG. Весь цикл занимает минут пятнадцать.

Что понадобится

Python 3.8–3.11 (под эти версии публикуются wheel-пакеты pyorbbecsdk), библиотеки opencv-python и numpy, компьютер с портом USB 3.0 и штатным кабелем камеры. На USB 2.0 полосы не хватает — это самая частая причина «камера не отдаёт кадры». На Linux дополнительно ставятся udev-правила (в репозитории pyorbbecsdk есть установочный скрипт), на Windows обычно достаточно свежего системного драйвера. Из камер подойдёт ToF-камера Femto Bolt с глубиной 640×576 или стереопара Gemini 335L.

pip install pyorbbecsdk opencv-python numpy

Как устроен пайплайн

В pyorbbecsdk всё держится на трёх сущностях. Pipeline — сессия работы с устройством, Config — список включаемых потоков и их параметры, FrameSet — пакет кадров, снятых за один такт. Глубина приходит в формате Z16: каждый пиксель — целое uint16 в миллиметрах, а метод get_depth_scale() возвращает масштаб (у Orbbec чаще всего 1.0). Нулевые пиксели означают «измерения нет»: блик, поглощающий материал или объект за пределами дальности.

# pip install pyorbbecsdk opencv-python numpy
import numpy as np
import cv2
from pyorbbecsdk import Pipeline, Config, OBFormat, OBSensorType

pipeline = Pipeline()
config = Config()
# Femto Bolt: глубина 640x576@30; для Gemini 335/335L — 640x480@30
config.enable_stream(OBSensorType.DEPTH_SENSOR, 640, 576, OBFormat.Z16, 30)
config.enable_stream(OBSensorType.COLOR_SENSOR, 640, 480, OBFormat.RGB, 30)
pipeline.start(config)

try:
    while cv2.waitKey(1) != 27:                    # ESC — выход
        frames = pipeline.wait_for_frames(100)     # FrameSet или None
        if frames is None:
            continue
        depth = frames.get_depth_frame()
        if depth is None:
            continue

        h, w = depth.get_height(), depth.get_width()
        scale = depth.get_depth_scale()            # обычно 1.0: значения в мм
        raw = np.asarray(depth.get_data(), dtype=np.uint16).reshape(h, w)

        # 16-битный PNG: в пикселях — настоящие миллиметры
        cv2.imwrite("depth.png", raw)

        # колоризация: 0–4000 мм -> 0–255, затем палитра JET
        norm = cv2.convertScaleAbs(raw, alpha=255.0 / (4000.0 * scale))
        colored = cv2.applyColorMap(norm, cv2.COLORMAP_JET)
        cv2.imshow("Orbbec depth", colored)
finally:
    pipeline.stop()
    cv2.destroyAllWindows()

Колоризация глубины и сохранение результата

Сырая 16-битная карта на экране выглядит чёрным пятном, глазу нужен контраст. Классическая связка: нормировать диапазон 0–4000 мм в 0–255 через cv2.convertScaleAbs и прогнать результат через cv2.applyColorMap с cv2.COLORMAP_JET — близкие объекты станут синими, дальние красными. Для инженерных задач важнее другое: сохраняйте именно 16-битный PNG, как в примере, а не скриншот колоризации. В PNG живут настоящие миллиметры, которые потом читают фотограмметрические пакеты и ROS-ноды.

Камера под задачу

Критерий	Femto Bolt	Gemini 335L
Технология глубины	ToF (время пролёта)	активная ИК-стереопара
Режим глубины	640×576 @ 30 fps	до 1280×800, обычный режим 640×480
Сильная сторона	точная глубина вблизи, скелетный трекинг	дальность и плотность для навигации
Типовой проект	AR, объёмный захват, аналитика людей	роботы и AMR, большие залы

На фото — Gemini 335Lg, версия семейства 335 с интерфейсом GMSL2 для мобильных платформ; логика работы pyorbbecsdk в ней та же.

Частые вопросы

Чёрное окно, wait_for_frames возвращает None — что не так?

В девяти случаях из десяти камера сидит на USB 2.0 или на Linux не отработали udev-правила. Проверьте устройство в lsusb или диспетчере задач и увеличьте таймаут до 200–300 мс: первые кадры после pipeline.start() всегда приходят с задержкой.

В каких единицах глубина и почему в облаке нули?

Миллиметры, тип uint16, ноль — нет данных. Перевод в метры: raw.astype(np.float32) * 0.001. Дыры от бликов закрываются медианным фильтром 5×5 до того, как облако уйдёт в дальнейшую обработку.

Как получить цвет, выровненный по глубине?

Включите выравнивание потока цвета к глубине через config.set_align_mode() — у Femto это делается аппаратно, у старых моделей программно. После выравнивания frames.get_color_frame() возвращает кадр уже в системе координат глубинного сенсора, попиксельно совпадающий с картой Z16.

Камеры для проекта

Femto Bolt — рабочий инструмент для задач, где в кадре человек: скелет, AR, объёмный захват. Gemini 335L — дальнобойная стереопара для навигации роботов и контроля больших помещений. Каталог Orbbec — счёт для юрлица, консультация по SDK, гарантия.