使用 OpenCV 调用 Orbbec 深度相机

💻 安装 OpenCV 5 并检查版本

下面以 Python 3 为例。命令在普通终端中执行，会在当前 Python 环境安装 OpenCV，不会修改相机固件。若正在使用虚拟环境，先激活对应环境。

OpenCV 主包已经覆盖本文示例需要的接口：

python -m pip install --upgrade opencv-python

如果后续还会使用 OpenCV Contrib 中的扩展模块，可以改装完整模块版：

python -m pip install --upgrade opencv-contrib-python

两个包都提供名为 cv2 的 Python 模块，因此同一环境选择其中一个即可。安装后检查版本：

python -c "import cv2; print('OpenCV 版本:', cv2.version)"

正常情况下会输出以下内容或是其他版本。

OpenCV 版本: 4.11.0

🔍 先确认 OBSENSOR 后端是否真正可用

cv2.CAP_OBSENSOR 常量存在，只说明 Python 接口中保留了这个枚举；是否能调用 Orbbec，还取决于当前 OpenCV 构建时有没有启用 OBSENSOR 后端。复制下面整条命令到终端：

python -c "import cv2; print('OpenCV 版本:', cv2.__version__); print('CAP_OBSENSOR 常量:', hasattr(cv2, 'CAP_OBSENSOR')); print('OBSENSOR 后端可用:', cv2.videoio_registry.hasBackend(cv2.CAP_OBSENSOR) if hasattr(cv2, 'CAP_OBSENSOR') else False)"

若已启用结果应如下图所示：

若出现不同结果可以这样判断：

通过 pip 获得的预编译包是否包含某个视频后端，取决于官方轮子的构建配置。若这里返回 False，问题发生在 OpenCV 构建层，此时更换 USB 口或相机序号不会改变结果。

📷 OpenCV 官方 Orbbec 采集方式

OpenCV 官方提供了相应的示例程序 videocapture_obsensor.py。

官方GitHub链接：🔗 OpenCV 官方 Python 示例：videocapture_obsensor.py

官方文档链接：🔗 OpenCV 官方 Orbbec UVC 教程

#!/usr/bin/env python

import numpy as np
import sys
import cv2 as cv


def main():
    # Open Orbbec depth sensor
    orbbec_cap = cv.VideoCapture(0, cv.CAP_OBSENSOR)
    if orbbec_cap.isOpened() == False:
        sys.exit("Fail to open camera.")

    while True:
        # Grab data from the camera
        if orbbec_cap.grab():
            # RGB data
            ret_bgr, bgr_image = orbbec_cap.retrieve(None, cv.CAP_OBSENSOR_BGR_IMAGE)
            if ret_bgr:
                cv.imshow("BGR", bgr_image)

            # depth data
            ret_depth, depth_map = orbbec_cap.retrieve(None, cv.CAP_OBSENSOR_DEPTH_MAP)
            if ret_depth:
                color_depth_map = cv.normalize(depth_map, None, 0, 255, cv.NORM_MINMAX, cv.CV_8UC1)
                color_depth_map = cv.applyColorMap(color_depth_map, cv.COLORMAP_JET)
                cv.imshow("DEPTH", color_depth_map)
        else:
            print("Fail to grab data from the camera.")

        if cv.pollKey() >= 0:
            break

    orbbec_cap.release()


if __name__ == '__main__':
    main()

运行代码后，效果如下：

若需要C++版本可见官方链接：

🔗 OpenCV 官方 C++ 示例：videocapture_obsensor.cpp

🔗 OpenCV 官方 Orbbec UVC 教程

⚠️ 直接调用 Orbbec 时的注意事项

🔌 相机打不开时先检查设备侧条件

后端为 True，但 cap.isOpened() 为 False 时，可以按下面的顺序检查：

Orbbec Viewer 是否能正常识别相机并显示 RGB、Depth；

相机是否连接到满足设备带宽要求的 USB 接口和线缆；

Linux 当前用户是否具备访问视频与 USB 设备的权限；

设备索引 0 是否被其他摄像头占用；

当前相机型号、固件和 OpenCV OBSENSOR 后端是否兼容。

OpenCV 官方示例证明了接口的调用方式，但不等于所有 Orbbec 型号和固件组合都已完成验证。

🌈 伪彩色图不再保留原始深度值

normalize() 和 applyColorMap() 适合把深度数据显示成容易观察的颜色，但处理后的 8 位图像不再保存原始距离信息。测距、范围筛选和点云计算应继续使用原始 depth 矩阵。

🧭 RGB 与 Depth 默认不一定逐像素对齐

彩色传感器和深度传感器可能具有不同的分辨率、视场角和光心。OpenCV 官方最小示例分别取出并显示两幅图，没有演示 D2C 对齐。因此，直接在 RGB 检测框中心读取深度图相同坐标，可能得到背景或相邻物体的深度。

项目需要流同步、D2C 对齐、相机标定参数、深度后处理、点云、IR、IMU 或多相机控制时，可以使用 Orbbec SDK v2 采集数据，再将得到的 NumPy 图像交给 OpenCV 处理。

🔗 Orbbec SDK v2 官方仓库 🔗 Orbbec SDK v2 官方示例目录

🔄 OpenCV 直接调用与 Orbbec SDK 的区别

OpenCV 可以通过 CAP_OBSENSOR 后端直接读取 Orbbec 相机的彩色图和深度图，获得的数据可直接用于画面显示、图像保存、深度伪彩色和简单测距。这种方式代码较少，适合快速验证相机取流以及开展基础图像处理。具体调用方法可参考 OpenCV 官方 Orbbec 示例。

对于更完整的 RGB-D 应用，Orbbec SDK 提供了帧同步、软件与硬件 D2C 对齐、深度滤波、点云生成、坐标转换及设备参数配置等功能。SDK 负责完成相机取流和深度数据处理后，可以将图像转换为 NumPy 数组，再使用 OpenCV进行显示、识别或其他视觉处理。

D2C 对齐： 将深度图映射到彩色图的视角，使彩色像素与深度值能够正确对应。

因此，基础取图和快速验证可以使用 OpenCV 直接调用；涉及稳定同步、RGB-D 对齐、点云或相机参数控制时，更适合采用 Orbbec SDK 采集数据，再交给 OpenCV完成后续处理。

🆕 OpenCV 5.0 的 3D 视觉补充

CAP_OBSENSOR 并不是 OpenCV 5.0 新增的接口，OpenCV 4.x 已经提供对应示例。OpenCV 5.0 与 3D 视觉更相关的变化，是将原来的 calib3d 能力重新组织为 geometry、calib、stereo 和 ptcloud 等模块，并增加了初步的点云与网格处理能力，包括 ICP、TSDF 以及 .ply、.obj 文件导入导出。

这些能力适合接在 RGB-D 数据采集之后，用于相机标定、几何估计、点云配准和多帧深度融合。第一次接入 Orbbec 相机时，仍建议先完成本文的后端检查和 RGB、Depth 取流验证，再加入更复杂的 3D 处理。

🔗 OpenCV 5 官方说明 🔗 OpenCV 4 → 5 迁移指南