奥比中光 / TECHNICAL WIKI

安装并使用奥比中光官方软件

深度相机 / SDK 入门

面向第一次使用奥比中光深度相机的开发者，指导完成从产品与主机检查、选择 Windows 或 Ubuntu 安装路径、运行官方 SDK 示例，到编写自己的深度和彩色取流程序的完整流程

Orbbec SDKWindowsUbuntuC++PythonOrbbec SDK v2.10.6

02 / DOCUMENTATION

内容概述

Orbbec SDK v2.10.6

本文面向第一次使用奥比中光深度相机的开发者，指导完成从产品与主机检查、选择 Windows 或 Ubuntu 安装路径、运行官方 SDK 示例，到编写自己的深度和彩色取流程序的完整流程。示例设备为 Astra 2，示例 SDK 为 Orbbec SDK v2.10.6；使用其他型号前，请先依据官方支持矩阵确认 SDK 世代与固件要求。

阅读方法：先完成“产品准备”，再在“Windows / Ubuntu 平台指南”中点击自己的操作系统。平台步骤完成后，继续阅读“SDK 自写取流”。

03 / DOCUMENTATION

开箱核对

Orbbec SDK v2.10.6

物品	数量	核对要点
相机本体	×1	记下机身丝印上的型号（如 `Astra 2`，型号号 `A30003-15`）—— 第 6 节要用
数据 + 供电线	×1	多为 Type-C 一线通；个别机型 Type-A→Type-C，网口机型用网线（以实物与规格书为准）
出厂资料	×1	快速入门 / 保修卡（视渠道而定）
选配件	视订单	支架、同步线、Sync Hub 等

品相：镜头前盖玻璃无划痕 / 指纹，接口无变形，线缆无折痕。
多数 USB 机型无需外接电源，数据与供电共用同一根 USB 3.0 线；功耗以规格书为准。

04 / DOCUMENTATION

接口与指示灯

Orbbec SDK v2.10.6

接口

类型	出现场合	用途
USB Type-C / Type-A	绝大多数 USB 机型	数据 + 供电
8-Pin / 同步口	支持多机同步的机型	多相机同步触发
网口（以太网 / GMSL）	网络型机型	数据（部分支持 PoE），非 USB 直连

指示灯

状态	含义
常亮	已上电且工作正常
呼吸 / 规律闪烁	初始化中，或已就绪
熄灭	低功耗待机
无规律闪烁	故障 → 拔掉所有线重插复位

安装孔：通常 1/4-20 UNC（三脚架螺纹）+ M3 螺孔。

05 / DOCUMENTATION

主机要求

Orbbec SDK v2.10.6

平台	系统	硬件
Windows	Windows 10 及以上（x64）	USB 3.0 口 / 千兆网口、四核 2.9GHz+、8GB+ 内存
Ubuntu	20.04 / 22.04+（已验证 20.04 / 22.04 / 24.04）	同上
Linux ARM64	Ubuntu（Jetson AGX Orin / Orin NX / Orin Nano / Xavier 等）	同上，走 arm64 包

以上为 Orbbec SDK v2 的通用要求。若需自行编译示例，另加 GCC ≥ 7.5、CMake ≥ 3.15、OpenCV（推荐 3.4.0）。

06 / DOCUMENTATION

连接要点

Orbbec SDK v2.10.6

用 USB 3.0 口（通常蓝色 / 带 SS 标识）；插 USB 2.0 会降速，可能跑不到高分辨率高帧率。
直连主机，不经无源 USB Hub / 扩展坞 —— 供电不足会表现为「设备时有时无 / 数据流中断」。
用随机附带的线；需延长时选 USB 认证、同时支持数据 + 供电的线，长度 1–1.5m 为宜。劣质长线是「找不到设备」的头号原因。
识别不到 / 不响应时：拔掉所有线，重新插回主机复位。
机器人场景走线：USB / 网线避开电机驱动与大电流线束。

07 / DOCUMENTATION

确认主机已识别

Orbbec SDK v2.10.6

平台	怎么确认	详细步骤
Windows	设备管理器（`Win + R` → `devmgmt.msc`）「摄像头」下可见；或 OrbbecViewer 能列出设备	Windows · 01 下载安装与准备
Ubuntu	`lsusb` 能看到奥比设备	Ubuntu · 01 下载安装与准备

1lsusb            # 列出所有 USB 设备2lsusb -d 2bc5:   # 只看奥比设备（VID = 2bc5）

示例（Astra 2）：ID 2bc5:0660。

排查顺序：换 USB 口 → 换线 → 去掉 Hub 直连 → 拔插复位 → 再查驱动 / 权限。

08 / DOCUMENTATION

确认该用 SDK v1 还是 v2

Orbbec SDK v2.10.6

不同型号支持的 SDK 世代不同，这决定应下载哪一套包。

查支持矩阵：在 Orbbec SDK v2 README 的「型号 × v1 / v2 支持状态」表里找第 1 节记下的型号，看 Orbbec SDK v2 那一列。
按判定决定：

判定	动作
`recommended for new designs` / `full maintenance`	✅ 用 v2 —— 本 WIKI 全套适用
`limited maintenance` / `not supported`	⚠️ 改用 v1：Orbbec SDK v1 仓库（其 Releases 里也有配套 OrbbecViewer）
表里查不到	到文档中心按型号查，或联系 FAE

双协议型号按固件判断：Astra Mini Pro / Astra Mini S Pro 同一型号存在两种协议固件 —— 固件 v2.x.x（UVC）用 v2，v1.x.x（OpenNI）只能用 v1。固件号在 OrbbecViewer 或设备信息里查。

⚠️ 已知 v2 不支持的型号：Astra+、Astra Pro Plus、Gemini 2 XL。

示例（Astra 2）：v1 列 full maintenance、v2 列 recommended for new designs → 用 v2；支持表中最小固件 = 推荐固件 = 2.8.20。

09 / DOCUMENTATION

安全与保养

Orbbec SDK v2.10.6

请勿触摸镜头 —— 指纹会影响成像质量。
请勿跌落或施加外力；拆解机壳 / 支架会失去保修。
请勿私自改装，可能导致永久损坏或精度异常。
长时间连续使用时机身温度升高属正常现象；必要时增加散热空间。
产品使用激光（通常为 Class 1）：不建议长时间直视；红外光肉眼不可见，尤须避免近距离正对。

10 / DOCUMENTATION

附 A：示例设备速查（Astra 2）

Orbbec SDK v2.10.6

参数	值
型号	A30003-15
VID / PID	`2bc5:0660`
原理	结构光，红外 850nm
量程	0.6 – 8m（推荐 0.6 – 5m）
深度	最高 1600×1200@30fps；FOV H58.2° × V45.2°
彩色	最高 1920×1080@30fps
IMU	6 轴，50–2000Hz
供电	USB 3.0 Type-C 一线通，平均 < 3.0W（峰值 6.5W）
安装	1 × 1/4-20 UNC，2 × M3
固件	2.8.20

结构光相机：强光 / 高反射 / 透明物体会明显影响深度质量，机器人在室外或复杂光照下需谨慎评估。

11 / DOCUMENTATION

附 B：资料入口

Orbbec SDK v2.10.6

找什么	去哪
各机型文档、使用指南	文档中心
中文参数表、开箱与快速入门视频、线材	中文官网下载中心
固件要求（最小 / 推荐）与支持矩阵	Orbbec SDK v2 README
v1 包、v1 机型资料（含国内 Gitee 镜像）	Orbbec SDK v1 仓库

示例（Astra 2）：规格书 PDF · 固件 2.8.20

12 / DOCUMENTATION

Windows / Ubuntu 平台指南

Orbbec SDK v2.10.6

CURRENT PLATFORMWindows

以下安装、权限配置和 SDK 示例仅适用于当前所选平台。

01下载并安装软件

✅ 从 Releases 页下载 OrbbecSDK_<版本>_win64.exe，即当前最新版本的一体安装包。

该安装包同时包含 OrbbecViewer 与 Orbbec SDK v2，安装一次即可满足两种用途：

用途	使用工具	本文步骤
查看图像、验证设备状态	`OrbbecViewer`（图形界面）	第 3 节安装 → 第 4 节
编写程序读取数据流	`Orbbec SDK v2`（C/C++/Python）	第 3 节安装 → 第 4 节验证 → 02 SDK 示例上手

第 5 节（元数据注册）两种用途均需执行。

02系统要求

项目	要求
操作系统	Windows 10 及以上（x64）。OrbbecViewer 的最低版本要求为 Windows 10 1803（build 17134）
接口	USB 3.0 口（推荐；USB 2.0 可运行，但高分辨率 / 高帧率受限）
硬件	内存 8GB 及以上；建议四核 2.9GHz 及以上

编译 SDK 示例需另行安装 Visual Studio 与 CMake，见 02 SDK 示例上手第 2 节。

03确认设备支持的 SDK 版本

不同型号支持的 SDK 世代不同，需先确认应下载 v1 还是 v2。

确认设备型号 —— 查看设备机身丝印上的型号与料号，或参考包装、规格书。
查询支持列表 —— 在 Orbbec SDK v2 README 的「型号 × v1 / v2 支持状态」表中查找对应型号，查看 Orbbec SDK v2 一列。
按判定结果选择下载位置：

v2 列中的判定	下载位置
`recommended for new designs` / `full maintenance`	✅ Orbbec SDK v2 Releases —— 继续阅读本文
`limited maintenance` / `not supported`	⚠️ Orbbec SDK v1 仓库（国内可访问镜像：Gitee）—— 本文不适用
列表中没有该型号	在文档中心按型号查询，或联系技术支持

⚠️ 已知在 v2 列为 not supported 的型号：Astra+、Astra Pro Plus、Gemini 2 XL，这些型号只能使用 SDK v1。

Astra Mini Pro / Astra Mini S Pro 为双协议型号，需按设备实际固件判断：固件主版本为 v2.x.x（UVC 协议）时使用 SDK v2；为 v1.x.x（OpenNI 协议）时使用 SDK v1。详见通用 / 01 产品准备第 6 节。

其他参考资料（规格书、文档中心、中文下载中心）见通用 / 01 产品准备 · 附 B 资料入口。

04选择下载文件

Releases 页的 Assets 中同时提供多类安装包，其类型与设备型号无关，只需按下表识别，以避免下载错误。Windows 平台会出现以下三类包：

#	文件名	说明	安装后可用的内容
①	`OrbbecSDK_<版本>_win64.exe`	一体安装包，运行安装向导	OrbbecViewer 与 SDK 全套
②	`OrbbecSDK_<版本>_<日期>_<commit>_win_x64.zip`	SDK 压缩包，解压即用	库 / 头文件 / 示例 / `scripts`，使用前需自行编译
③	`OrbbecViewer_<版本>_<日期>_<commit>_win_x64.zip`	独立查看器，解压即用、免安装	仅查看器，不含 SDK

✅ 本步骤使用 ①。

下载前需先点击 Assets 区域的 Show all xx assets 展开全部文件，避免遗漏。

文件识别方式：前缀（OrbbecSDK / OrbbecViewer）加平台后缀（win64.exe / win_x64.zip）。文件名中的版本号、日期与 commit 号随版本变化，不影响识别；linux_*、macOS、.deb、.tar.gz 等为非 Windows 平台文件，可忽略。

05安装

运行 OrbbecSDK_<版本>_win64.exe，按安装向导完成安装。请记录安装目录，后续步骤需引用，本文以 <安装目录> 表示。

安装完成后，目录结构如下：

路径	内容	用途
`toolsOrbbecViewer.exe`	图形界面程序	查看图像（第 4 节）
`sharedobsensor_metadata_win10.ps1`	元数据注册脚本（同目录附 `.md` 说明）	必须执行，见第 5 节
`includelibobsensor` · `libOrbbecSDK.lib`	头文件与导入库	编译程序时使用（见 02）
`binOrbbecSDK.dll`（及 `binextensions`）	运行时动态库	运行示例程序时使用（见 02）
`examplessrc`	SDK 示例源码	学习 API、跑通取流（见 02）
`build_examples.ps1`	一键编译示例的脚本	见 02
`toolsUSBDownloadTool.exe`	设备与固件工具	固件升级时使用

⚠️ 安装包的目录结构与 GitHub 源码仓库不同：安装包内没有 scripts 目录，元数据注册脚本位于 shared、查看器位于 tools，而非源码仓库中的 scriptsenv_setup。

可将 toolsOrbbecViewer.exe 创建为桌面快捷方式，便于后续使用。

06驱动说明

Orbbec SDK v2 使用 UVC 协议，通常无需安装额外驱动，连接设备后即可被系统识别。

需要安装 Windows 驱动的是 OpenNI 协议（v1 体系）机型：DaBai / DaBai DCW / DaBai DW / Astra Mini Pro / Astra Pro Plus / A1 Pro / Gemini E / Gemini E Lite / Gemini。

若设备型号不在上述名单中，且使用 SDK v2，则无需安装驱动 —— astra-win32-driver-*.zip 一类驱动对其无效。

07查看图像

运行 OrbbecViewer：<安装目录>toolsOrbbecViewer.exe。
左侧「设备控制」列表应显示已连接的设备，表示主机已识别到设备。列表项包含型号、序列号与接口类型（形如 Orbbec Astra 2 <序列号> USB3.0），可用于确认连接速率是否为 USB 3.0。
点击顶部工具栏的 彩色 / 深度 / 红外 / IMU / 点云 按钮，开启对应的数据流。

界面构成：左侧为设备列表，顶部为数据流按钮（与左侧「高级模式」下的条目一一对应），底部为日志区。

⚠️ 首次打开时画面为黑色，并提示「当前没有数据流，请点击顶部操作栏上的按钮开启数据流!」，属正常现象，点击顶部对应按钮后即可显示图像。

也可通过「设备管理器」确认：Win + R → devmgmt.msc → 「摄像头」分类下应能看到该设备。

图文指引：相机简易使用指南（含启动 Viewer 与「断开重连」的处理办法）· OrbbecViewer 功能与支持平台

08元数据注册（Windows 必须执行）

原因：Windows 默认限制 UVC 相机的元数据（metadata）获取。未注册会导致设备时间戳异常，进而影响 SDK 内部帧同步（多流时间戳不对齐、帧同步失效）。详细说明见 obsensor_metadata_win10.md（已在 Windows 10 / 11 验证）。

脚本位置：<安装目录>sharedobsensor_metadata_win10.ps1

连接设备，确认设备在线。
以普通权限打开 PowerShell（脚本会自动请求 UAC 提权），进入脚本所在目录，并按顺序执行以下命令：

1cd "<安装目录>shared"2Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser   # 放开执行策略，仅需执行一次3.obsensor_metadata_win10.ps1 -op install_all                          # 执行注册

执行后将弹出 UAC 提示，确认后脚本在新窗口中输出 N connected Orbbec devices were found: …，以及 adding metadata key（本次写入）或 skipping - metadata key already exists（已存在）。

参数说明：install_all（推荐，覆盖所有曾连接过的设备，后续更换设备通常无需重新执行）、install（默认，仅当前在线的设备）、remove / remove_all（移除已写入的键，需要回退时使用）。

脚本行为：在 HKLMSYSTEMCurrentControlSetControlDeviceClasses{…}…Device Parameters 下，为奥比（VID_2BC5）UVC 设备写入 MetadataBufferSizeInKB0 = 5（多 pin 接口另加 1、2 两项），以放开元数据缓冲。

⚠️ 每接入一台新设备均需重新执行一次。建议将上述命令保存为脚本，便于复用。

若安装目录中未包含该脚本（个别旧版安装包可能不含），可从 GitHub 获取：脚本 · 说明

故障处理

现象	处理
提示脚本被禁止运行	未放开执行策略，回到上述第 2 步第 1 条命令
提示「未数字签名」仍被拒绝	仅从浏览器下载的脚本会出现此情况（安装目录中的脚本无此标记）。先执行 `Unblock-File .obsensor_metadata_win10.ps1`，或改用 `powershell -ExecutionPolicy Bypass -File .obsensor_metadata_win10.ps1 -op install_all`
脚本执行后窗口立即关闭，看不到输出	脚本已提权并另开窗口，输出在新窗口中
找不到脚本	脚本位于 `<安装目录>shared`，不是 `scriptsenv_setup`（后者为 GitHub 源码仓库的路径）
提示权限不足或无响应	UAC 提权请求被拒绝
注册后时间戳仍异常	断开设备后重新连接，再次执行脚本

09SDK 示例上手

✅ SDK 示例源码位于 <安装目录>examplessrc，使用安装目录自带的一键构建脚本编译：

1cd "<安装目录>"2.build_examples.ps1

编译产物输出到 bin 目录，可执行文件名为 ob_enumerate.exe、ob_imu.exe 等。

本文以两个示例为主线：0.basic.enumerate 确认设备与流参数（不依赖 OpenCV，见第 4 节）；0.basic.quick_start 跑通视频流（需 OpenCV，见第 5 节）。

10示例程序一览

examplessrc 下共 37 个编号示例目录，另有 C 示例（c_examples）与 LiDAR 示例（lidar_examples）。按用途分组如下：

用途	示例目录 → 生成的可执行文件	功能说明
设备信息	`0.basic.enumerate` → `ob_enumerate.exe`	列出设备型号 / PID / 序列号 / 接口，以及各传感器支持的格式、分辨率、帧率
基础取流	`0.basic.quick_start` → `ob_quick_start.exe`	以默认配置取流，并开窗口显示
综合用法	`3.advanced.common_usages`	查看设备信息、设置参数并显示视频流的综合示例
单流取流	`1.stream.depth` · `1.stream.color` · `1.stream.infrared` · `1.stream.confidence` · `1.stream.decimation`	获取单一路数据流并显示
取流（无窗口）	`1.stream.imu` → `ob_imu.exe`	获取 IMU（加速度计与陀螺仪）数据并打印到控制台
回调式取流	`1.stream.callback`	在回调函数中处理帧数据（自定义处理时推荐的方式）
多流	`1.stream.multi_streams`	同时开启多路数据流
设备控制	`2.device.control`	激光开关、激光强度、白平衡等参数设置
设备预设	`3.advanced.preset`	读取与设置设备预设值
网络设备	`2.device.forceip`	通过 ForceIP 命令为网络设备配置 IP 地址
录制与回放	`2.device.record`（带窗口）· `2.device.record.nogui`（命令行）	将数据流录制为 ROS bag（`.bag`）；`2.device.playback` 用于回放
固件升级	`2.device.firmware_update` · `2.device.optional_depth_presets_update`	读取 BIN 文件升级固件 / 预设
热插拔	`2.device.hot_plugin`	设备热插拔回调与断流处理
对齐与同步	`3.advanced.sync_align` · `3.advanced.hw_d2c_align`	深度与彩色流对齐、同步
后处理	`3.advanced.post_processing` · `3.advanced.enhanced_depth_filter` · `3.advanced.hdr`	滤波、深度增强、HDR 合成
激光交错	`3.advanced.laser_interleave`	开启 / 关闭激光帧交错与 SequenceId 滤波
点云	`3.advanced.point_cloud` → `ob_point_cloud.exe`	生成点云并保存为 `.ply` 文件
坐标变换	`3.advanced.coordinate_transform`	不同坐标系之间的转换
多设备	`3.advanced.multi_devices` · `3.advanced.multi_devices_sync`	多相机同时取流与同步
多设备硬件触发	`3.advanced.multi_devices_sync_gmsltrigger`	通过 `/dev/camsync` 向 GMSL 设备发送硬件同步信号（仅 Linux / GMSL 平台，需 NVIDIA Xavier / Orin）
图像保存	`4.misc.save_to_disk`	将帧数据保存到磁盘
日志与元数据	`4.misc.logger` · `4.misc.metadata`	设置日志级别与输出路径；逐流读取元数据
第三方库集成	`5.wrapper.opencv` · `5.wrapper.pcl` · `5.wrapper.open3d`	与 OpenCV / PCL / Open3D 的集成示例（PCL 与 Open3D 示例需在 CMake 中开启对应选项，默认不构建）

OpenCV 为可选依赖：未安装时，依赖它的示例不会生成，构建过程会给出 OpenCV not found, some examples may not be built … 警告。安装要求见第 2 节，示例缺失时的处理见第 4 节。

utils 为示例公用工具（带窗口显示的 CVWindow 位于 utils_opencv.*）。各示例的代码说明见其所在目录下的 README.md，总览见 examplessrcREADME.md。

11工具链要求

组件	要求
Visual Studio	2017 / 2019 / 2022 任一版本，需包含 C++ 生成工具。仅需编译示例时，安装「Visual Studio 生成工具」并勾选「使用 C++ 的桌面开发」工作负载即可，无需安装完整 IDE
CMake	需可在命令行中直接调用。安装时勾选 Add CMake to the system PATH，或安装后手动添加到 PATH
OpenCV	可选。仅带窗口显示的示例需要，且必须是 C++ 版本（安装目录中含 `OpenCVConfig.cmake`）。若安装在非标准位置，需设置 `OpenCV_DIR` 环境变量供 CMake 定位

⚠️ 两类常见混淆：

Visual Studio Code 与 Visual Studio 不是同一产品。前者为代码编辑器，不包含 C++ 编译器，不能替代 Visual Studio 或 Visual Studio 生成工具。

Python 版 OpenCV 与 C++ 版 OpenCV 不通用。通过 pip 安装的 opencv-python 仅供 Python 使用，无法满足 C++ 示例的编译需求。

环境检查：以下两条命令均需有输出，方满足构建要求。

1cmake --version2& "C:Program Files (x86)Microsoft Visual StudioInstallervswhere.exe" -latest -products * -requires Microsoft.VisualStudio.Component.VC.Tools.x86.x64 -property installationPath

第二条无任何输出，表示未安装 Visual Studio 或缺少 C++ 生成工具组件。若提示 vswhere.exe 不存在，表示本机未安装过 Visual Studio 安装程序。

安装指引

组件	下载位置	安装注意事项
Visual Studio	Visual Studio 下载页 → 「Visual Studio 2022 生成工具」（需完整 IDE 可选择 Community 版本）	在安装器中勾选「使用 C++ 的桌面开发」工作负载（含 MSVC 编译器与 Windows SDK）。未勾选该工作负载时，构建脚本仍会报找不到编译器
CMake	CMake 下载页 → Windows x64 Installer	安装向导中勾选 Add CMake to the system PATH

⚠️ 安装完成后需关闭并重新打开终端，PATH 的变更仅对新打开的终端生效。

构建脚本报错对照（按脚本内的检查顺序排列）

报错信息	原因与处理
`No Visual Studio with the C++ build tools was found.`	未检测到包含 C++ 工具的 Visual Studio。安装 Visual Studio 生成工具或 Community 版本并勾选「使用 C++ 的桌面开发」；如已安装，可通过 Visual Studio 安装程序补装该工作负载
`CMake was not found in PATH. Install CMake and retry.`	命令行中没有可用的 `cmake`。安装 CMake 并勾选加入 PATH，或重新打开终端后重试
`vswhere.exe was not found.`	本机没有 Visual Studio 安装程序，表示从未安装过 Visual Studio，按上表安装

也可通过 -Generator 参数跳过自动探测，例如 .build_examples.ps1 -Generator "Visual Studio 17 2022"。该参数仅跳过探测步骤，编译器本身仍须已安装。

12构建示例

1cd "<安装目录>"2.build_examples.ps1

脚本执行内容：探测 Visual Studio 版本 → 使用 CMake 配置 examples → 编译 → 将可执行文件安装到 bin → 将 toolsextensions 复制到 bin（免去手动复制动态库）→ 删除临时目录 examplesbuild。

参数	默认值	说明
`-Configuration`	`Release`	也可指定 `Debug` / `RelWithDebInfo` / `MinSizeRel`
`-Architecture`	`x64`	仅支持 x64
`-Generator`	自动探测	需要时手动指定，如 `-Generator "Visual Studio 17 2022"`

编译完成后，bin 目录中将生成 ob_enumerate.exe、ob_imu.exe 等文件。

手动构建（不使用脚本）：
代码块
PowerShell
1cmake -S examples -B examplesbuild2cmake --build examplesbuild --config Release3cmake --install examplesbuild --config Release --prefix .
cmake --install 不可省略。若省略，可执行文件将保留在 examplesbuildbin，该目录中不含 OrbbecSDK.dll，运行时将报缺少动态库。

13运行示例

功能说明：列出已连接的设备（型号 / PID / 序列号 / 接口类型），并可按提示选择设备与传感器，列出该传感器支持的全部流格式。

操作步骤

连接设备，确认设备管理器中可见（元数据注册应已完成，见 01 第 5 节）。
进入 bin 目录运行（必须在 bin 目录下运行，动态库与可执行文件位于同一目录）：

1cd "<安装目录>bin"2.ob_enumerate.exe

按提示输入设备序号并回车，列出该设备的传感器。
输入传感器序号并回车，列出该传感器支持的流格式。
按 ESC 逐层返回或退出程序。

输出示例

1enumerated devices:2  0- device name: <设备型号>, device pid: 0x<PID> ,device SN: <序列号>, connection type:<接口类型>3Select a device to enumerate its sensors (Input device index or 'ESC' to exit program):4Sensor list:5 - 0.sensor type: DEPTH6 - 1.sensor type: COLOR7 - 2.sensor type: IR8 - 3.sensor type: ACCEL9 - 4.sensor type: GYRO101.format: Y16, res: 640*480, fps: 30112.format: Y16, res: 848*480, fps: 30

上述输出可用于确认设备支持的数据流参数（格式、分辨率、帧率），是编写取流程序时选择参数的依据。
connection type 显示 USB3.0 时，表示连接速率符合推荐要求。

故障处理

现象	处理
提示 `No device found!`	设备未连接或未被识别。参见 01 第 4 节或通用 / 01 产品准备第 4、5 节排查
找不到某个 `ob_*.exe`	构建未成功，或该示例依赖 OpenCV 而本机未安装。重新执行第 3 节的构建流程，并检查输出中是否有 `OpenCV not found …` 警告；如需要该示例，请安装 C++ 版 OpenCV 后重新构建
运行时报缺少 `OrbbecSDK.dll`	未在 `bin` 目录下运行。进入 `bin` 目录后重新运行，或将 `bin` 目录添加到 PATH

14跑通视频流：obquickstart

ob_enumerate 只确认「设备在、支持哪些流」；真正取流用入门示例 0.basic.quick_start（ob_quick_start.exe，需已安装 OpenCV 才会生成）。

它做什么（依据示例源码）：以默认配置启动 Pipeline（数据流管线，默认开启深度与彩色流），创建一个 1280×720、标题为 QuickStart 的窗口，循环等待复合帧并显示 —— 即实时显示深度与彩色画面；关闭窗口即停止数据流并退出程序。

获取视频流的关键代码（摘自 quick_start.cpp，完整文件位于 <安装目录>examplessrc�.basic.quick_start）：

1ob::Pipeline pipe;                 // ① 创建数据流管线（Pipeline）2pipe.start();                      // ② 以默认配置启动数据流（默认开启深度 + 彩色）3
4ob_smpl::CVWindow win("QuickStart", 1280, 720, ob_smpl::ARRANGE_ONE_ROW);5                                   // ③ 创建 1280×720 的显示窗口6
7while (win.run()) {8    auto frameSet = pipe.waitForFrameset();   // ④ 等待一帧复合数据（含所有已开启的流，超时 1000ms）9    win.pushFramesToView(frameSet);           // ⑤ 将帧送入窗口显示10}11
12pipe.stop();                       // ⑥ 停止数据流

①②④⑥ 是 SDK 的关键函数：创建管线 → 启动数据流 → 等帧 → 停止。③⑤ 使用的 ob_smpl::CVWindow 是示例自带的显示工具（位于 examplessrcutils，基于 OpenCV 实现），不属于 SDK API —— 自己的程序里可以用任意方式处理 frameSet 中的帧数据。

这段取流代码在 Windows 与 Ubuntu 上完全一致（同一份示例源码）—— SDK 的取流接口是跨平台的，两个平台的差异只在编译方式与运行时环境（见各自平台 01）。

运行（仍在 bin 目录）：

1.ob_quick_start.exe

运行后应弹出标题为 QuickStart 的窗口，按单行排列显示深度与彩色画面；关闭窗口即退出程序。

⚠️ 刚启动的前一两帧，深度或彩色可能只有其一（两个传感器的就绪有先后，缺哪个并不固定），属正常现象 —— 自写程序时不要把「某一类帧为空」当作错误处理。

默认开启的数据流可在 SDK 配置文件中调整（binOrbbecSDKConfig.xml）。

⚠️ 该示例依赖 OpenCV 与桌面环境：未安装 OpenCV 时不会生成；无显示环境下无法运行 —— 无窗口取流可改用 2.device.record.nogui（把数据流录制为 .bag 文件），控制台数据可运行 1.stream.imu。

15其他示例

使用目的	示例
查看深度 / 彩色 / 红外图像（带窗口）	`0.basic.quick_start` · `1.stream.depth` / `.color` / `.infrared`
获取数据（无窗口输出）	`1.stream.imu`（控制台输出）· `3.advanced.point_cloud`（导出 `.ply` 文件）· `2.device.record.nogui`（录制为 `.bag` 文件）
编写自有取流程序	参考 `examplessrcREADME.md` 与各示例目录下的 `README.md`（含逐段代码说明）；API 头文件位于 `includelibobsensor`

完整清单（各示例的功能说明）见第 1 节。
示例程序均使用 ob::Error 异常进行错误处理。运行出错时，控制台会输出 function / args / message / type 四项信息，可据此定位问题。

13 / DOCUMENTATION

SDK 取流

Orbbec SDK v2.10.6

✅ 取流只需要四步 API（与各平台篇 02 §5 的 quick_start 相同，代码完全一致）：

1ob::Pipeline pipe;                          // ① 创建数据流管线2pipe.start();                               // ② 启动数据流3auto frameSet = pipe.waitForFrameset();     // ④ 等待一帧复合数据4pipe.stop();                                // ⑥ 停止

与示例的唯一差别在 ④ 与 ⑥ 之间：quick_start 把帧送进窗口显示，应用程序在这里处理帧数据。

本文提供 C++ 与 Python 两份等价实现（同一逻辑，均为完整可运行程序）：

语言	章节	内容
C++（`my_stream.cpp`）	第 1 节	代码、讲解、两平台编译命令与输出示例
Python（`my_stream.py`，pyorbbecsdk2）	第 2 节	安装前提、代码、运行
共同注意事项	第 3 节	两种语言都适用的三个注意点
进阶方向	第 4 节	面向机器人集成的参考示例

14 / DOCUMENTATION

完整示例代码（mystream.cpp）

Orbbec SDK v2.10.6

1#include <libobsensor/ObSensor.hpp>2#include <iostream>3
4int main() try {5    // ① 创建数据流管线，② 以默认配置启动（默认开启深度 + 彩色）6    ob::Pipeline pipe;7    pipe.start();8    std::cout << "[1] Pipeline started (default config)" << std::endl;9
10    // ③ 循环取 10 帧复合数据11    for (int i = 0; i < 10; ++i) {12        // ④ 等待一帧复合数据（包含所有已开启的流；超时返回空指针）13        auto frameSet = pipe.waitForFrameset();14        if (frameSet == nullptr) {15            std::cout << "frame " << i << ": timeout" << std::endl;16            continue;17        }18
19        std::cout << "frame " << i << ":";20
21        // ⑤ 取深度帧：转为 DepthFrame（= 视频帧 + 深度值缩放）22        auto depth = frameSet->getFrame(OB_FRAME_DEPTH);23        if (depth) {24            auto d   = depth->as<ob::DepthFrame>();25            auto buf = static_cast<const uint16_t *>(d->data());   // Y16：每像素 2 字节26            uint32_t w = d->width(), h = d->height();27            // 深度值 = 像素值 × valueScale（结果为毫米，见头文件注释）28            float scale = d->getValueScale();29            uint16_t center = buf[(h / 2) * w + (w / 2)];30            std::cout << " depth " << w << "x" << h31                      << " | center " << center * scale << " mm";32        } else {33            std::cout << " depth: none";34        }35
36        // ⑥ 取彩色帧（启动初期可能还没有，见第 3 节注意事项）37        auto color = frameSet->getFrame(OB_FRAME_COLOR);38        if (color) {39            auto v = color->as<ob::VideoFrame>();40            std::cout << " | color " << v->width() << "x" << v->height();41        } else {42            std::cout << " | color: none";43        }44        std::cout << std::endl;45    }46
47    // ⑦ 停止数据流48    pipe.stop();49    std::cout << "done" << std::endl;50    return 0;51}52catch (ob::Error &e) {   // SDK 以异常报告错误，处理方式与 SDK 示例一致53    std::cerr << "function:" << e.getFunction() << "nargs:" << e.getArgs()54              << "nmessage:" << e.what() << "nstatus:" << e.getStatus()55              << "ntype:" << e.getExceptionType() << std::endl;56    return 1;57}

15 / DOCUMENTATION

代码讲解

Orbbec SDK v2.10.6

代码	说明
`ob::Pipeline pipe;` → `pipe.start();`	创建管线并启动数据流。默认配置开启深度与彩色流，可在 SDK 配置文件中调整
`pipe.waitForFrameset()`	阻塞等待一帧复合数据（`FrameSet`，包含所有已开启流的帧）。超时（默认 1000ms）会返回空指针，必须先判空再解引用
`frameSet->getFrame(OB_FRAME_DEPTH)`	从复合帧中取指定类型的帧；该流未就绪时返回空
`frame->as<ob::DepthFrame>()`	⚠️ `getFrame` 返回的是基类 `Frame` —— 转成 `DepthFrame`（继承自 `VideoFrame`）才有宽高、像素数据与 `getValueScale()`；彩色帧转 `VideoFrame` 即可。用错子类会直接编译失败
`d->data()`	帧数据的内存地址（帧对象存活期间有效）。深度帧为 Y16 格式：每像素 2 字节，`uint16_t` 数组
`d->getValueScale()`	深度值 = 像素值 × valueScale（结果为毫米），见头文件注释。打印真实距离前先乘上它
`catch (ob::Error &e)`	SDK 以异常报告错误。输出 `function` / `args` / `message` / `status` / `type` 五项，与 SDK 示例的处理方式一致

16 / DOCUMENTATION

编译与运行

Orbbec SDK v2.10.6

代码与平台无关，差别只在编译命令。头文件与库均在 SDK 安装目录下：Ubuntu 以 <SDK 安装目录> 表示（约定见 Ubuntu / 01 示例环境），Windows 以 <安装目录> 表示（约定见 Windows / 01 示例环境）。

Ubuntu

1g++ -std=c++11 -DOB_STATIC_DEFINE 2    -I<SDK 安装目录>/include my_stream.cpp 3    -L<SDK 安装目录>/lib -lOrbbecSDK 4    -Wl,-rpath,<SDK 安装目录>/lib 5    -o my_stream6./my_stream

-DOB_STATIC_DEFINE：使 SDK 头文件中的导出宏展开为空。该宏未做平台区分，Linux 下同样需要。

-Wl,-rpath,<SDK 安装目录>/lib：将库目录写入可执行文件的运行时搜索路径，加载 libOrbbecSDK.so 时无需设置 LD_LIBRARY_PATH。

Windows

1g++ -std=c++11 -DOB_STATIC_DEFINE -I<安装目录>include my_stream.cpp <安装目录>libOrbbecSDK.lib -o my_stream.exe

编译产物放到 <安装目录>bin 中运行（该目录已有 OrbbecSDK.dll 与 extensions），或将这两个文件复制到可执行文件所在目录。
使用 Visual Studio + CMake 亦可编译（工具链要求见 Windows / 02 第 2 节）。

输出示例

C++ 与 Python 两个版本的输出格式相同：

1[1] Pipeline started (default config)2frame 0: depth: none | color 1280x720            ← 启动初期，深度传感器尚未就绪3frame 1: depth 1600x1200 | center 0 mm | ...     ← 深度值 0 = 该像素无效（超出量程 / 无回波）4frame 3: depth 1600x1200 | center 1234 mm | ...  ← 对准量程内的物体后即为真实距离5...6done

分辨率与帧率取决于设备与默认配置，以实际输出为准；center 为画面中心点的距离测量值（毫米）。

17 / DOCUMENTATION

SDK 取流（Python）

Orbbec SDK v2.10.6

同一取流逻辑的 Python 实现。注意包名：PyPI 上的 pyorbbecsdk 是 SDK v1 的绑定；SDK v2 的绑定为 pyorbbecsdk2，二者对应不同的 SDK 世代，注意区分。

18 / DOCUMENTATION

安装前提

Orbbec SDK v2.10.6

项	要求
Python	3.8 – 3.13（轮子覆盖 cp38 – cp313；⚠️ Python 3.14 暂无轮子）
平台	Windows x64 · Linux x86_64 与 aarch64 · macOS arm64
依赖	`numpy`（读取帧数据所需）

1pip install pyorbbecsdk2 numpy

轮子内已包含 SDK 动态库与 extensions，无需另行安装 SDK，也无需复制 DLL —— 导入时自动加载。这与 C++ 路线不同。

19 / DOCUMENTATION

完整示例代码（mystream.py）

Orbbec SDK v2.10.6

1# my_stream.py —— 与 my_stream.cpp 相同逻辑的 Python 版本2# 四步取流：创建管线 → 启动 → 等帧 → 停止3import numpy as np4from pyorbbecsdk import OBError, Pipeline5
6try:7    # ① 创建数据流管线，② 以默认配置启动（默认开启深度 + 彩色）8    pipe = Pipeline()9    pipe.start()10    print("[1] Pipeline started (default config)")11
12    # ③ 循环取 10 帧复合数据13    for i in range(10):14        # ④ 等待一帧复合数据（超时返回 None）15        frames = pipe.wait_for_frames(1000)16        if frames is None:17            print(f"frame {i}: timeout")18            continue19
20        print(f"frame {i}:", end="")21
22        # ⑤ 取深度帧：读分辨率与中心点距离23        depth = frames.get_depth_frame()24        if depth is not None:25            w, h = depth.get_width(), depth.get_height()26            scale = depth.get_depth_scale()   # 深度值 = 像素值 × depth_scale（毫米）27            data = np.frombuffer(depth.get_data(), dtype=np.uint16).reshape(h, w)28            print(f" depth {w}x{h} | center {data[h // 2, w // 2] * scale:.0f} mm", end="")29        else:30            print(" depth: none", end="")31
32        # ⑥ 取彩色帧（启动初期可能还没有，见第 3 节注意事项）33        color = frames.get_color_frame()34        if color is not None:35            print(f" | color {color.get_width()}x{color.get_height()}", end="")36        else:37            print(" | color: none", end="")38        print()39
40    # ⑦ 停止数据流41    pipe.stop()42    print("done")43except OBError as e:   # SDK 以异常报告错误44    print("SDK error:", e)

20 / DOCUMENTATION

运行

Orbbec SDK v2.10.6

1python my_stream.py

输出格式与 1.3 的输出示例一致。

21 / DOCUMENTATION

与 C++ 版的对应关系

Orbbec SDK v2.10.6

C++（1.1 / 1.2 节）	Python（本节）
`ob::Pipeline pipe;` + `pipe.start();`	`pipe = Pipeline()` + `pipe.start()`
`pipe.waitForFrameset()`	`pipe.wait_for_frames(1000)`（超时返回 `None`）
`frameset->getFrame(OB_FRAME_DEPTH)`	`frames.get_depth_frame()`
`as<ob::DepthFrame>()` + `getValueScale()`	`depth.get_depth_scale()`
`depth->data()`（Y16，`uint16_t` 数组）	`np.frombuffer(depth.get_data(), dtype=np.uint16)`
`catch (ob::Error &e)`	`except OBError as e`

22 / DOCUMENTATION

注意事项

Orbbec SDK v2.10.6

以下三点对 C++ 与 Python 两种实现同样适用：

⚠️ 刚启动的前一两帧，深度或彩色可能只有其一（两个传感器的就绪有先后，缺哪个并不固定），属正常现象 —— 不要把「某一类帧为空」当作错误处理。
⚠️ 深度值 0 表示该像素无效（超出量程或无回波）。若画面中心恒为 0：可能超出量程或被遮挡，把相机对准 1～3 m 内的实际物体再观察。
⚠️ 彩色帧通常是编码数据（体积远小于同分辨率原始图像），拿到的是压缩字节流，不能直接当像素读；需要图像时先解码 —— SDK 示例是借助 OpenCV 完成的。深度帧（Y16）无此问题。

23 / DOCUMENTATION

进阶参考：面向机器人集成

Orbbec SDK v2.10.6

本文拿到的是「单帧数据 + 控制台打印」。机器人程序中通常需要持续取流并交给算法，下一步可参考 SDK 示例目录中的这些示例（均附 README.md）：

需求	参考示例
持续取流、不阻塞主循环	`1.stream.callback`（注册回调，帧到达即处理）
深度图与彩色图对齐	`3.advanced.sync_align` · `3.advanced.hw_d2c_align`
输出点云	`3.advanced.point_cloud`（导出 `.ply`）
数据落盘供离线分析	`2.device.record.nogui`（录制 `.bag`）· `4.misc.save_to_disk`

返回品牌技术文档

浏览同品牌产品和相关 Wiki。

24 / SUPPORT

讨论、纠错与持续维护

Forum / GitHub / Community

FORUM产品讨论

提交硬件、版本、日志和复现步骤。

进入 Forum GITHUBIssue 与任务

跟踪驱动、SDK 和示例代码问题。

打开 GitHub