使用 pyorbbecsdk 调用 Orbbec 相机

🧰 什么是 PyOrbbecSDK

PyOrbbecSDK 是 Orbbec SDK v2 的 Python 接口，开发者可以通过 Python 获取相机的彩色、深度、红外和 IMU 数据，并完成多数据流、图像对齐及点云生成等操作。它适合用于机器人视觉、三维感知和算法原型开发；安装包名为 pyorbbecsdk2，代码中仍通过 pyorbbecsdk 导入。

📥 下载官方示例代码

打开 PyOrbbecSDK 官方仓库，切换到 v2-main 分支，点击 Code → Download ZIP，解压后将目录改名为 pyorbbecsdk。为减少路径问题，可以放在：

C:orbbecpyorbbecsdk

🔗 下载 PyOrbbecSDK v2-main 源码压缩包。

🔗 查看 PyOrbbecSDK 官方仓库。

🐍 使用 Conda 创建 Python 环境

本文采用 Conda 管理 Python 与依赖。Conda 除了隔离 Python 包，也能统一管理 NumPy、OpenCV、Open3D 等数据科学依赖，适合继续开展图像处理和点云开发。

Conda： 一套跨平台的环境与包管理工具，除了 Python 包，也能管理部分本地库和运行时依赖。

📥 安装 Miniconda

Miniconda 提供 Conda 的基础环境，体积比完整的 Anaconda 更小。已经可以执行 conda --version 的读者可跳过这一步。

Windows x64 用户可下载并运行 Miniconda3-latest-Windows-x86_64.exe。安装完成后，从开始菜单打开 Anaconda PowerShell Prompt，执行：

conda --version

正常情况下会显示 Conda 版本号，说明环境管理工具已经可以使用。

🔗 查看 Miniconda 官方安装指南。

🔗 下载 Miniconda 安装程序。

🐍 创建并激活 Orbbec 环境

以下命令会创建名为 orbbec 的 Python 3.10 环境，不会修改系统 Python：

conda create -n orbbec python=3.10
conda activate orbbec
python --version

正常情况下，命令行开头会出现 (orbbec)，并显示 Python 3.10.x。如果 conda activate 提示尚未初始化，可先运行 conda init，关闭并重新打开终端后再次激活环境。

🔗 查看 Conda 环境管理说明。

📦 安装通用依赖（可选）

项目还需要 Conda 版本的 NumPy 或 OpenCV 时，可在 (orbbec) 环境中执行：

conda install numpy opencv

pyorbbecsdk2 的在线安装会自动解析自身运行依赖，因此只运行官方 Quick Start 时通常可以跳过这一步；已有其他项目希望统一由 Conda 管理 NumPy、OpenCV 时，再提前安装即可。

🔧 安装 PyOrbbecSDK

PyOrbbecSDK 当前通过 PyPI 发布，不在 Conda 默认仓库中。确认命令行开头显示 (orbbec) 后，通过该环境中的 Python 调用 pip：

python -m pip install --upgrade pip
python -m pip install --upgrade pyorbbecsdk2

安装后执行：

python -m pip show pyorbbecsdk2
python -c "import pyorbbecsdk; print('PyOrbbecSDK import successful')"

看到软件包版本和 PyOrbbecSDK import successful，说明 pyorbbecsdk2 已安装到当前 Conda 环境，如下图所示。

这里有三个相近但不同的名称：

因此，已经安装 pyorbbecsdk2 后，代码中仍使用：

from pyorbbecsdk import Pipeline

🔗 查看 PyOrbbecSDK 官方安装指南。

🔗 查看 PyOrbbecSDK PyPI 页面。

▶️ 运行 Color 与 Depth 示例

继续在项目根目录执行：

python examplesquick_start.py

正常情况下会看到：

PowerShell 显示 Pipeline started；

QuickStart Viewer 窗口打开；

左侧 Color 画面随场景变化；

右侧 Depth 画面以伪彩色显示距离变化；

按 Q 或 Esc 后窗口关闭，程序停止相机数据流。

quick_start.py 使用相机的默认数据流配置，适合先确认 Python 取流是否正常。它显示的是 Color 与 Depth 并排画面；彩色图与深度图的对齐、点云生成和数据保存由后续示例分别处理。

🔗 查看 quick_start.py 官方源码。

🔗 查看 PyOrbbecSDK 官方 QuickStart 教程。