奥比中光Gemini335L 环境配置及Python版本SDK部署

Ne0inhk

16 Mar 2026 — 19 min read

1.前言：

最近为了完成“机械臂手眼标定”的任务需要配置奥比中光Gemini335L深度相机的相关开发环境，这里将遇到的坑以及相关的方法总结一下给大家。这里我会讲的比较细致一点，因为考虑到我们实验室有很多对于相机外设不太了解的同学，希望这篇文章对你们的学习生活会有帮助。
本文目标：完成从驱动配置到 Python SDK 部署的完整流程，避免大家踩坑。

2. orbbec驱动安装与配置

2.1 为什么需要驱动

驱动作用：相机硬件与操作系统的桥梁，确保系统能够识别相机并正确传输深度数据、彩色图像数据。
若无驱动：设备管理器可能显示为未知设备，或者无法被 SDK 调用。

2.2 驱动下载

进入奥比中光官网 → Gemini 335L 产品页面 → 选择对应操作系统（Windows / Linux）。
下载 Orbbec Camera Driver（通常包含 USB 驱动）。

https://www.orbbec.com/developers/orbbec-sdk/

2.3 驱动安装

Windows：运行 .exe 安装包，插入相机后检查 设备管理器 → 照相机 是否显示为 Orbbec Gemini 335L。
Linux：安装 .deb 或 .rpm 包，使用 lsusb / dmesg 确认识别。

3. SDK 下载与安装

3.1 为什么要下载 SDK

SDK（Software Development Kit）提供相机调用的 API、示例代码、工具包，方便开发者在不同语言中快速使用相机功能（彩色图像、深度图、点云）。
SDK 内含 lib、include 文件，以及 Viewer 工具，用于调试和验证相机是否正常工作。
这个SDK可以用于手眼标定时，我们手动拍摄一些标定板的图片用于获取相机内参。

3.2 SDK 与 API 的关系说明

API（应用程序接口）可以理解为前端访问后端数据的一条“通道”。通过 API，开发者无需直接接触或修改底层源码，就能调用和使用后端的数据或功能。
而 SDK（软件开发工具包）则是一个为开发者准备的完整“工具集”或“环境”，里面包含了库、文档、示例代码、调试工具等，帮助开发者快速构建应用。在这个环境中，API 就是开发者与 SDK 提供的功能进行交互的方式。
可以这样类比：SDK 就像一个完整的工具箱，里面装好了各种工具和材料，而 API 就是工具箱对外开放的“接口”，通过这些接口，开发者能够高效地调用 SDK 提供的功能，而无需关心其内部复杂的实现逻辑。

3.3 SDK 获取

从奥比中光官网下载对应平台的 OrbbecSDK（例如 OrbbecSDK v1.x）。

https://www.orbbec.com/developers/orbbec-sdk/

注意版本匹配：驱动与 SDK 需要配套，否则可能出现无法识别相机的问题。

3.4 SDK 安装与应用

Windows：解压后配置环境变量（如 ORBBEC_SDK_PATH）。
Linux：tar -xvf xxx.tar.gz 解压，并将 bin/、lib/ 添加到 PATH 和 LD_LIBRARY_PATH。

视频流组成
- 视频流由每秒若干帧（FPS，Frames Per Second）组成，比如 30FPS 就表示每秒输出 30 张图像。
- 每一帧都是一张静态图像，可以是彩色图（RGB/BGR）、灰度图，或者深度图（Depth）等。
类型
- 彩色视频流（RGB）：普通相机采集的图像，带颜色信息。
- 灰度视频流（Gray）：只有亮度信息的图像，常用于图像处理或计算机视觉。
- 深度视频流（Depth）：由深度相机提供，每个像素表示到相机的距离信息。

深度相机的点云，可以理解为用三维坐标表示场景中物体形状和空间位置的一组点集合。比视频流更进一步，它不仅告诉你物体的颜色或亮度，还告诉你每个点在三维空间中的位置。

详细说明：

1. 点云的组成

每一个“点”包含 (X, Y, Z) 坐标：
- X, Y 表示水平方向和垂直方向的位置（像素坐标经过深度映射转换）。
- Z 表示深度，即这个点到相机的距离。
有些点云还可以包含颜色信息 (R, G, B)，称为彩色点云。

2. 点云来源

由深度相机（如 Gemini 335L）生成：
1. 相机拍摄 RGB 图像（彩色流）
2. 相机拍摄深度图（Depth 流，每个像素代表距离）
3. 利用相机内参（焦距、光心等）将深度图每个像素映射到三维空间 → 形成点云

3. 点云的作用

三维重建：可以重建物体或场景的三维模型
机器人感知：机器人抓取、避障、导航
测量和分析：体积测量、表面分析、手眼标定
计算机视觉/AI：与深度学习结合进行物体识别或姿态估计

4. 点云与视频流的区别

特性	视频流	点云
数据维度	2D 图像	3D 空间点
信息类型	颜色/亮度	空间位置（可选颜色）
用途	可视化、图像处理	三维建模、空间分析、机器人操作

4. Python SDK 部署

4.1 Python SDK 介绍

奥比官方提供 pyorbbecsdk，基于 C++ SDK 封装，便于在 Python 中调用相机（获取 RGB、深度图、点云）。
适合科研和快速实验，例如与 OpenCV、PyTorch、YOLO 结合。

4.2 安装方法

Windows/Linux：

https://github.com/orbbec/

4.3 无法直接使用sdk包的原因

pyorbbecsdk 本质
- 奥比中光 SDK 底层是 C/C++ 实现的库（提供高性能的图像处理、深度计算、点云生成等功能）。
- Python 只是通过 pybind11 封装这些 C++ 接口，让我们能在 Python 里调用。
- 因此，必须先把 C++ 源码编译成二进制文件（动态库或 .pyd 模块），Python 才能 import 使用。
为什么要用 CMake？
- CMake 是一个跨平台的 构建工具，主要作用是生成编译系统。
- pyorbbecsdk 支持 Windows / Linux / ARM 等多种平台，直接写 Makefile 维护成本很高。
- 用 CMake 可以自动检测环境、选择编译器、配置依赖库（如 OpenCV、pybind11），大大简化编译流程。

pyorbbecsdk-2-main/ │ ├─.github/ # GitHub 配置相关（CI/CD 工作流） │ └─workflows/ │ └─build.yaml # 自动化构建配置文件 │ ├─build/ # 编译输出目录（CMake 生成） │ ├─CMakeFiles/ # CMake 内部文件 │ ├─pyorbbecsdk.dir/ # 编译对象文件 │ └─Release/ # 编译生成的库文件 │ └─pyorbbecsdk.cp39-win_amd64.pyd # Python 可调用 SDK 模块 │ ├─cmake/ # CMake 构建脚本 │ └─toolchain-linux.cmake # Linux 工具链配置示例 │ ├─config/ # SDK 配置文件 │ ├─multi_device_sync_config.json # 多相机同步配置 │ ├─OrbbecSDKConfig.md # SDK 配置说明 │ └─OrbbecSDKConfig.xml # SDK 配置 XML 文件 │ ├─docker/ # Docker 构建环境 │ └─build_env/ # Dockerfile 文件 │ ├─docs/ # SDK 文档 │ ├─source/ # 文档源文件 │ └─_images/ # 文档图片资源 │ ├─examples/ # Python 示例程序 │ ├─callback.py # 使用回调获取数据示例 │ ├─color.py # 彩色图像采集示例 │ ├─depth.py # 深度图采集示例 │ ├─point_cloud.py # 点云生成示例 │ ├─coordinate_transform.py # 相机坐标与世界坐标转换示例 │ └─... # 其他功能示例 │ ├─install/ # 安装后的库文件 │ ├─lib/ │ │ OrbbecSDK.dll # Windows 动态库 │ │ pyorbbecsdk.cp39-win_amd64.pyd # Python SDK 模块 │ │ │ └─extensions/ # SDK 扩展模块 │ ├─depthengine/ # 深度处理引擎 │ ├─filters/ # 图像后处理滤波器 │ ├─firmwareupdater/ # 相机固件升级工具 │ └─frameprocessor/ # 数据帧处理模块 │ ├─scripts/ # SDK 构建和工具脚本 │ ├─install_udev_rules.sh # Linux 下设备权限设置 │ └─build_whl/ # 打包 Python wheel 文件脚本 │ ├─sdk/ # 原生 SDK 头文件和库 │ ├─include/libobsensor/ # 公共头文件 │ └─lib/ # 静态/动态库文件 │ ├─win_x64/ # Windows 库文件 │ ├─linux_x64/ # Linux x64 库文件 │ └─arm64/ # ARM 平台库文件 │ ├─src/ # SDK 源码 │ └─pyorbbecsdk/ # Python SDK 封装 C++ 源码 │ ├─context.cpp/hpp │ ├─device.cpp/hpp │ ├─frame.cpp/hpp │ └─... # 其他模块源码 │ ├─stubs/ # Python 类型提示文件 │ └─pyorbbecsdk.pyi │ └─test/ # 单元测试 ├─test_context.py ├─test_device.py └─...

以上是我们所需的依赖文件，以及详细的作用介绍。但是我们还不能直接使用，会有以下的报错。所以接下来我们要用cmake把 C++ 源码编译成二进制文件（动态库和 .pyd 模块）

 File "D:\Camera_Positioning\pyorbbecsdk-2-main\examples\coordinate_transform.py", line 201, in <module> import pyorbbecsdk as ob ModuleNotFoundError: No module named 'pyorbbecsdk'

4.4 配置一个Anaconda虚拟环境

我们需要下载以下的包：

pybind11==2.11.0 pybind11-global==2.11.0 opencv-python wheel numpy<2.0  pygame # for visualization pynput # for keyboard input

新建虚拟环境可能有些资料说必须要下python 3.9版本，但是只要我们把cmake用对了基本上大部分版本都可以用的，可以生成我们真正需要的pyd文件的版本，但是如果盲目使用后续的cmake编译源码的话生成的可能不是虚拟环境里的版本而是电脑环境目录下的默认python版本。后面会详细解释。

conda create -n your_env_name(新建的虚拟环境的名字) python=n（指定python版本）

如果没有指定python的版本，则会默认下载最新版本的python。

删除虚拟环境（同时删除环境里的所有配置）

conda remove -n your_env_name(需要删除的虚拟环境的名字) --all

激活虚拟环境

conda activate your_env_name（需要进入的环境的名称）

4.5 奥比中光 Python SDK 配置所需依赖包说明

1. pybind11==2.11.0

作用：pybind11 是一个用于将 C++ 代码与 Python 绑定 的工具。
原因：奥比中光的底层 SDK 是用 C++ 编写的，Python SDK 通过 pybind11 将 C++ 接口封装成 Python 可调用的模块。
总结：没有它，Python 无法直接调用相机 SDK 的功能。

2. pybind11-global==2.11.0

作用：这是 pybind11 的一个全局安装版本，确保系统全局能找到对应的绑定工具。
原因：有些构建环境需要全局版本来避免依赖冲突。
总结：保证 pybind11 在系统中可用，避免 SDK 编译时报找不到绑定模块的错误。

3. opencv-python

作用：OpenCV 是计算机视觉的核心库，用于图像处理和显示。
原因：相机采集到的图像（彩色流、深度流）往往需要用 OpenCV 进行：
- 图像显示 (cv2.imshow)
- 图像格式转换（RGB → BGR）
- 后续处理（滤波、边缘检测、特征点提取等）
总结：用来展示、处理相机采集的画面。

4. wheel

作用：Python 的打包工具，帮助构建 .whl 安装包。
原因：奥比中光的 Python SDK 在安装时通常以 whl 文件形式发布或需要自己打包。
总结：让 SDK 能顺利打包和安装。

5. numpy<2.0

作用：科学计算的基础库，用于矩阵运算和数据处理。
原因：相机输出的数据（RGB、Depth、Point Cloud）通常是 数组/矩阵格式，需要用 NumPy 来存储和处理。
特别说明：限制 <2.0 是因为部分深度相机 SDK 还不兼容 NumPy 2.x。
总结：处理和运算相机输出的数据核心库。

6. pygame

作用：游戏开发库，提供简单的图形显示和交互功能。
原因：常用于 点云/深度图的可视化（快速画窗口展示，而不是复杂的 3D 引擎）。
总结：方便做实验时快速显示相机输出。

7. pynput

作用：用于键盘和鼠标监听。
原因：在采集或显示视频流时，可以通过键盘输入（比如按 q 退出、按 s 保存图像）来控制程序。
总结：实现与用户的交互，方便调试和采集。

大家这里使用pip3 install -r requirements.txt 命令下载这些包就可以如果觉得下载速度太慢可以打开网络代理速度会有显著变化。

5.Cmake编译生成二进制文件

5.1 下载Cmake GUI版本

Windows用户可直接在CMake官网下载.msi安装包，记得勾选”Add to system PATH”选项。

https://cmake.org/download/

.msi是一个Windows Installer包。和.exe不一样，直接运行MSI安装包不会自动安装自定义系统必备。它只会安装主应用程序。Linux用户输入sudo apt-get install cmake-qt-gui即可。

5.2 配置Visual Studio

首先确保自己电脑上有Visual Studio (全世界第一的c++编译器)

打开Cmake，设置源码路径，在源码路径下新建“build”文件夹设置为生成二进制文件的路径，如下图所示。

打开build文件夹下生成的vs工程，我们还需要进行编译。

5.3 使用vs进行编译源码

不是最终的可执行文件/SDK
- CMake 自己不会直接编译源码，它的工作是“生成构建系统”。
- 在 Windows 上，默认的构建系统就是 Visual Studio 工程（.sln + .vcxproj 文件）。
VS 工程的内容也就是说，现在你拿到的 VS 工程就是“施工图纸”，真正的编译要交给 Visual Studio 来执行。
- .sln → Visual Studio 的解决方案文件（Solution），可以用 VS 打开。
- .vcxproj → 每个子项目的工程文件，里面记录了源代码、编译器参数、依赖路径。
- ZERO_CHECK / ALL_BUILD / INSTALL / pyorbbecsdk 等 target。
作用
- 我们可以用 VS 打开 .sln 文件，点击 Build Solution（生成解决方案），VS 会调用编译器（MSVC）去把源码编译成二进制文件。
- 最终会得到 Python 可以导入的 .pyd 文件（Windows 下 Python 的动态库模块）。

5.4 选择使用Release的原因

1. Debug 模式

主要用途：调试程序
特点：
- 编译器会保留调试信息（符号表），方便在 VS 里打断点、逐行跟踪代码。
- 不会对代码做太多优化（比如变量不会被过度优化掉），所以调试时能看到真实的变量值。
- 生成的程序体积更大，运行速度更慢。
- 文件名/路径里可能带 d 后缀（例如 opencv_world455d.dll）。

2. Release 模式

主要用途：正式发布 / 实际使用
特点：
- 编译器会进行各种优化（如内联、寄存器优化、去除冗余代码）。
- 没有完整的调试信息（调试起来不方便）。
- 生成的程序体积更小，运行速度更快。
- 库文件/动态库通常没有 d 后缀。

3. 为什么我们要选择Release

库文件不兼容问题
- 如果我们用 Debug 模式编译 pyorbbecsdk，它会依赖 Debug 版的库（如 opencv_world455d.dll）。
- 如果系统里只有 Release 版的 OpenCV，就会报 找不到 DLL 的错误。
- 同样的，Python 自身通常是 Release 编译的，所以我们如果用 Debug 版的 .pyd 模块可能会出问题。

如果这里生成的pyd文件和大家的python版本一致整个过程就结束了，但是有些读者可能就会生成cp312也就是适配 python 3.12版本的文件，不是我们虚拟环境的python版本而是我们环境变量下的python版本，大家在这里不要慌张。

这个和我们cmake里面Python 相关路径有关我们如果不修改的话默认按你环境变量里面的python.exe的版本来生成的你只要指定你虚拟环境的python路径

cmake .. ^ -DCMAKE_PREFIX_PATH=D:/ANACONDA/envs/Orbbec ^ -DPYTHON_EXECUTABLE=D:/ANACONDA/envs/Orbbec/python.exe ^ -DPYTHON_INCLUDE_DIR=D:/ANACONDA/envs/Orbbec/include ^ -DPYTHON_LIBRARY=D:/ANACONDA/envs/Orbbec/libs/python39.lib ^ -Dpybind11_DIR=D:/ANACONDA/envs/Orbbec/share/cmake/pybind11

我们可以通过在我们的虚拟环境路径下打开命令提示符输入以上的命令，这段命令的意思就是告诉 CMake：别用系统的，强制用我虚拟环境里的 Python 路径。

逐项解释：

-DCMAKE_PREFIX_PATH=...
→ 指定你的虚拟环境根目录，方便 CMake 搜索依赖。
-DPYTHON_EXECUTABLE=...
→ 告诉 CMake 用哪个 Python 解释器，比如 Anaconda 环境里的 python.exe。
-DPYTHON_INCLUDE_DIR=...
→ Python 的头文件路径（比如 Python.h）。编译 C++ 代码时需要包含这些头文件。
-DPYTHON_LIBRARY=...
→ Python 的库文件路径（.lib 文件）。这是编译动态链接时需要的。
-Dpybind11_DIR=...
→ pybind11 的 CMake 配置文件路径。这样 find_package(pybind11) 才能找到对应的 cmake 脚本。

cmake .. 的意思是告诉 CMake 去找 上一级目录 的 CMakeLists.txt（也就是源码根目录）。
后面的参数是指定 Python、pybind11 等路径。

成功生成 VS 工程后，在 build 目录里继续执行：

cmake --build . --config Release --target install

这样编译的 .pyd 文件会被安装到你的虚拟环境里（或者 build/Release/ 下），而且是我们需要的版本。

6. 附录：

这里的附录内容给大家介绍examples文件下对我们做奥比中光深度相机开发和使用的所有文件的作用。

文件名	作用
`callback.py`	演示如何设置帧到达时的回调函数，响应式处理图像流。
`color.py`	获取并显示彩色图像。
`coordinate_transform.py`	像素坐标 → 相机坐标或世界坐标转换示例。适用于三维定位。
`depth.py`	获取并显示深度图。
`depth_work_mode.py`	设置深度摄像头的工作模式（如近距/远距）。
`device_firmware_update.py`	升级设备固件。
`device_optional_depth_presets_update.py`	更新可选深度配置（presets）。
`enumerate.py`	枚举连接的设备，查看设备信息。
`hdr.py`	配置 HDR 模式（高动态范围）成像。
`hot_plug.py`	演示设备热插拔的检测与处理逻辑。
`hw_d2c_align.py`	使用硬件方式对齐 depth 与 color 图像。
`imu.py`	获取 IMU（惯性测量单元）数据，如陀螺仪或加速度。
`infrared.py`	获取红外图像流。
`logger.py`	SDK 日志系统使用示例。
`metadata.py`	提取图像帧的元数据（如时间戳、帧号等）。
`multi_device.py`	同时控制多个相机设备。
`multi_streams.py`	同时获取多个图像流（如彩色、深度、IR）。
`net_device.py`	演示网络设备的连接和使用（适用于网络摄像头）。
`playback.py`	从 .bag 文件回放录制的数据。
`point_cloud.py`	深度图 → 点云的生成与显示。
`post_processing.py`	后处理，例如深度图滤波、边缘增强等。
`preset.py`	设置图像流参数预设值。
`quick_start.py`	快速入门 Demo，综合打开 color + depth。
`README.md`	简要说明每个示例的功能。
`recorder.py`	录制图像流到磁盘（.bag、图像等）。
`requirements.txt`	Python 依赖包列表。
`save_image_to_disk.py`	保存一帧图像到本地磁盘。
`sync_align.py`	软件对齐 color 与 depth 图像。
`two_devices_sync.py`	两个设备的同步示例。
`utils.py`	工具函数，如图像转换、打印信息等。

总结：

这样就是配置成功了，这篇文章对我来说不仅是对前一段时间学习内容的第一个总结，也希望这篇文章可以帮助到你们，因为看了很多教程和文章，踩了很多坑才完成这些步骤，感谢其他开源作者的文章，它们对我的帮助很大。这里就不罗列出他们的文章了，有问题可以评论区讨论，也希望大家可以点赞+收藏。

祝大家风调码顺！！！