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

Ne0inhk

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

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进行编译源码

  1. 不是最终的可执行文件/SDK
    • CMake 自己不会直接编译源码，它的工作是“生成构建系统”。
    • 在 Windows 上，默认的构建系统就是 Visual Studio 工程（.sln + .vcxproj 文件）。
  2. VS 工程的内容也就是说，现在你拿到的 VS 工程就是“施工图纸”，真正的编译要交给 Visual Studio 来执行。
    • .sln → Visual Studio 的解决方案文件（Solution），可以用 VS 打开。
    • .vcxproj → 每个子项目的工程文件，里面记录了源代码、编译器参数、依赖路径。
    • ZERO_CHECK / ALL_BUILD / INSTALL / pyorbbecsdk 等 target。
  3. 作用
    • 我们可以用 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.pySDK 日志系统使用示例。
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.txtPython 依赖包列表。
save_image_to_disk.py保存一帧图像到本地磁盘。
sync_align.py软件对齐 color 与 depth 图像。
two_devices_sync.py两个设备的同步示例。
utils.py工具函数，如图像转换、打印信息等。

总结：

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

祝大家风调码顺！！！

Read more

每日精讲：环形链表、两个数组中的交集、随机链表的复制

每日精讲：环形链表、两个数组中的交集、随机链表的复制

Hello大家好！ 很高兴与大家见面！ 给生活添点快乐，开始今天的编程之路。 我的博客:<但愿. 我的专栏:C语言、题目精讲、算法与数据结构、C++ 欢迎点赞，关注 一 环形链表 1.1题目链接：环形链表II 1.2题目描述： 给定一个链表的头节点  head ，返回链表开始入环的第一个节点。 如果链表无环，则返回 null。 如果链表中有某个节点，可以通过连续跟踪 next 指针再次到达，则链表中存在环。 为了表示给定链表中的环，评测系统内部使用整数 pos 来表示链表尾连接到链表中的位置（索引从 0 开始）。如果 pos 是 -1，则在该链表中没有环。注意：pos 不作为参数进行传递，仅仅是为了标识链表的实际情况。注意不允许修改 链表。

By Ne0inhk
《算法题讲解指南：优选算法-滑动窗口》--13 水果成篮

《算法题讲解指南：优选算法-滑动窗口》--13 水果成篮

🔥小叶-duck：个人主页 ❄️个人专栏：《Data-Structure-Learning》 《C++入门到进阶&自我学习过程记录》《算法题讲解指南》--从优选到贪心 ✨未择之路，不须回头 已择之路，纵是荆棘遍野，亦作花海遨游 目录 13 水果成篮 题目链接： 编辑 题目示例： 解法（滑动窗口）： 算法思路： 算法流程： C++代码演示：方法一(使用容器) C++代码演示：方法二(用数组模拟哈希表) 算法总结及流程解析： 结束语 13 水果成篮 题目链接： 题目示例： 解法（滑动窗口）： 算法思路：       研究的对象是一段连续的区间，可以使用【滑动窗口】思想来解决问题。       让滑动窗口满足：窗口内水果的种类只有两种。       做法：右端水果进入窗口的时候，

By Ne0inhk
TOON：一种为大模型设计的JSON压缩型数据结构

TOON：一种为大模型设计的JSON压缩型数据结构

目录 TOON：一种为大模型设计的JSON压缩型数据结构 一、精准定义，什么是 TOON？ 1、JSON 数据格式的局限性 2、TOON 的结构与优势 3、TOON 数据结构的主要特征 4、媒体类型与文件拓展名 二、举例：JSON 与 TOON 描述同一组数据分别是什么样 三、结语         作者：watermelo37         ZEEKLOG优质创作者、华为云云享专家、阿里云专家博主、腾讯云“创作之星”特邀作者、火山KOL、支付宝合作作者，全平台博客昵称watermelo37。         一个假装是giser的coder，做不只专注于业务逻辑的前端工程师，Java、Docker、Python、LLM均有涉猎。 --------------------------------------------------------------------- 温柔地对待温柔的人，包容的三观就是最大的温柔。 ---------------------------------------------------------------------

By Ne0inhk

Flutter 三方库 in_date_utils 的鸿蒙化适配指南 - 在鸿蒙系统上构建极致、高效的日期逻辑处理与万年历算法引擎

欢迎加入开源鸿蒙跨平台社区：https://openharmonycrossplatform.ZEEKLOG.net Flutter 三方库 in_date_utils 的鸿蒙化适配指南 - 在鸿蒙系统上构建极致、高效的日期逻辑处理与万年历算法引擎 在鸿蒙（OpenHarmony）系统的日历、任务管理或考勤应用中，如何快速计算某月的天数、判断闰年、或优雅地对日期进行加减操作？in_date_utils 为开发者提供了一套开箱即用的日期增强工具集。本文将深入实战其在鸿蒙生态中的应用。 前言 什么是 in_date_utils？它是 Dart 原生 DateTime 的强力补丁。在 Flutter for OpenHarmony 的实际开发中，我们经常需要处理诸如“上周一的日期”、“本月最后一个周五”等复杂的业务逻辑。利用该库，我们可以避免重复编写琐碎的日期数学运算，让鸿蒙应用的代码更加简洁、易读且稳健。 一、

By Ne0inhk