Windows 下使用 Orbbec 相机：Orbbec SDK 快速入门

这篇按实际操作顺序分成三部分：先用 Orbbec Viewer 确认相机可以显示彩色图和深度图，再准备 Orbbec SDK 开发环境，最后编译并运行官方示例。示例以 Windows 10/11 x64 和 Orbbec SDK v2.9.3 为参考；不同版本的安装包名称可能略有变化。

SDK： Software Development Kit，即软件开发套件。这里用它连接 Orbbec 相机并获取图像。

🎯 完成后应看到什么

完成本文后，应得到四个可以直接检查的结果：

Orbbec Viewer 能识别相机型号；

Viewer 能持续显示 Color 和 Depth 画面；

Visual Studio 能成功生成 ob_quick_start.exe；

运行示例后，窗口能持续显示相机画面。

🔗 Orbbec SDK v2 Windows Quick Start 🔗 Orbbec SDK v2 官方仓库 🔗 官方 quick_start 示例

1️⃣ 确认相机支持 Orbbec SDK v2

打开 Orbbec SDK v2 官方仓库，在 Supported Devices 表格中查找相机型号，同时查看对应的最低固件版本和推荐固件版本。

如果列表中没有该型号，可再到 Orbbec SDK 下载页查看旧版 SDK 的支持范围。部分较早的 Orbbec 相机使用旧版 SDK 或 OpenNI，所需安装包与本文不同。

成功标志： 支持列表中能找到相机型号，并且当前固件版本符合要求。

🔗 Orbbec SDK v2 支持设备列表 🔗 Orbbec SDK 官方下载与型号支持页 🔗 OpenNI 设备升级至 UVC 协议说明

2️⃣ 安装 Orbbec SDK

请从 https://www.orbbec.com/developers/orbbec-sdk/ 下载安装程序 “OrbbecSDK_vx.x.x_win64.exe”。

双击安装程序，按提示完成安装。

安装完成后，Orbbec SDK 安装目录下的文件如下：

🔗 Orbbec SDK v2 Releases 与安装包说明 🔗 Orbbec SDK Windows 安装图文说明 🔗 Orbbec SDK v2 官方仓库：Windows 安装说明

📷 Orbbec Viewer

Orbbec Viewer 是 Orbbec 基于 SDK 提供的相机管理与数据预览工具。连接相机后，可以查看设备型号、序列号和固件版本，选择 Color、Depth、IR 或 IMU 数据流，并直接预览相机画面。熟悉 Viewer 的基本操作后，再继续安装 SDK 并运行官方示例。Orbbec Viewer 是一款基于 Orbbec SDK 开发的工具，旨在帮助开发者更便捷地使用 Orbbec 的 3D 传感器产品。该工具能够实现 Orbbec 3D 传感器产品的各项功能，包括读取序列号、获取设备类型、获取摄像头参数、控制摄像头等。

安装 Orbbec SDK 会一起安装 Orbbec Viewer，其应用程序位于\OrbbecSDK 2.9.3\tools，如下图所示。

使用配套线缆将相机连接至电脑的 USB 3.x 接口，打开 Orbbec Viewer 选择设备并确认型号、序列号和固件版本，然后选择合适的分辨率与帧率，启动 Color 和 Depth 数据流。然后就可以在Orbbec Viewer看到对应的图像，如下图所示。

具体操作指南可见🔗 Orbbec Viewer 官方使用指南 🔗 Orbbec Viewer Windows 视频教程

元数据注册

对于 Windows 系统，你需要对与视频帧相关的元数据进行注册处理（这些元数据包括时间戳以及与视频帧相关的其他信息）。

元数据注册请按照以下步骤操作：/shared/obsensor_metadata_win10.md

注意：如果元数据没有正确注册，设备的时间戳将会出现异常，从而影响 SDK 的内部帧同步功能。

构建Orbbec SDK 包

首先进入SDK安装目录下的 examples 目录，使用 CMake 来编译该项目。

点击“配置”按钮后，会出现以下对话框：

点击“完成”按钮，将 OpenCV_DIR 设置为 OpenCV 的安装目录，如果没有安装可以在https://opencv.org/releases/选择合适的版本进行安装。

然后点击“生成”按钮，如下所示：

💻 在 Visual Studio 2022 运行示例程序

使用 Visual Studio 2022 打开示例项目（sdk_examples.sln）。

在顶部工具栏选择：

Release | x64

右键 ob_quick_start；

选择“设为启动项目”；

再次确认顶部为 Release | x64；

右键项目并选择“属性”；

选择“调试 → 开始执行（不调试）”，或按：

Ctrl + F5

正常情况下会出现标题为 QuickStart 的窗口，并持续显示相机帧。可以把手或纸盒放在相机前方，在不过度靠近镜头的情况下缓慢前后移动：彩色画面应同步变化，深度画面的层次也应随距离变化。

🧯 常见问题与解决方式

📚 Windows 提示找不到 OrbbecSDK.dll

典型现象：

由于找不到 OrbbecSDK.dll，无法继续执行代码

这表示 ob_quick_start.exe 已经生成，但 Windows 的 DLL 搜索路径中没有 SDK 运行库。把下面的文件复制到 EXE 旁边即可：

<SDK_ROOT>binOrbbecSDK.dll
→ <SDK_ROOT>examplesbuildbinOrbbecSDK.dll

也可以使用通用变量完成复制和复验：

$sdkRoot = "C:pathtoOrbbecSDK"
$runDir = Join-Path $sdkRoot "examplesbuildbin"

Copy-Item `
  (Join-Path $sdkRoot "binOrbbecSDK.dll") `
  (Join-Path $runDir "OrbbecSDK.dll") `
  -Force

Test-Path (Join-Path $runDir "OrbbecSDK.dll")

不需要使用 regsvr32 注册，也不需要因为这一错误重装相机驱动。修复后先用 Test-Path 验证，再启动程序。

🖼️ Windows 提示找不到 opencv_world4100.dll

典型现象：

由于找不到 opencv_world4100.dll，无法继续执行代码

这表示 QuickStart 的 OpenCV 显示依赖没有进入运行目录。先从构建缓存确认 CMake 使用的 OpenCV：

$buildDir = "C:pathtoOrbbecSDKexamplesbuild"

$opencvDirLine = Select-String `
  (Join-Path $buildDir "CMakeCache.txt") `
  -Pattern "^OpenCV_DIR:PATH=" |
Select-Object -First 1 -ExpandProperty Line

if (-not $opencvDirLine) {
  throw "CMakeCache.txt 中没有记录 OpenCV_DIR"
}

$opencvBuildDir = $opencvDirLine -replace "^OpenCV_DIR:PATH=", ""
$opencvBuildDir

正常会返回类似：

C:/path/to/opencv/build

再按报错中的文件名搜索对应的 x64 Release DLL：

$opencvDllName = "opencv_world4100.dll"  # 改为弹窗中的实际文件名

$opencvDll = Get-ChildItem $opencvBuildDir `
  -Recurse `
  -File `
  -Filter $opencvDllName `
  -ErrorAction SilentlyContinue |
Where-Object FullName -Match "[\/]x64[\/]" |
Select-Object -First 1

if (-not $opencvDll) {
  throw "未找到与报错名称一致的 x64 OpenCV DLL"
}

$opencvDll.FullName

找到后，将它复制到示例运行目录并复验：

$runDir = Join-Path $buildDir "bin"

Copy-Item `
  $opencvDll.FullName `
  (Join-Path $runDir $opencvDllName) `
  -Force

Test-Path (Join-Path $runDir $opencvDllName)

不同 OpenCV 版本的文件名不同，其他版本 DLL 不能通过改名代替。pip install opencv-python 安装的是 Python 包，也不能补齐这个 C++ 示例所需的 Windows C++ 运行库。

🔍 Pipeline 报 depth frame processor not found

典型信息：

function:ob_pipeline_start
message:Device Component 'depth frame processor' not found!
status:114
type:13

这个现象说明程序已经成功加载 OrbbecSDK.dll 并进入 SDK，但启动深度流时没有找到 frameprocessor 扩展。将下面整个目录复制到运行目录：

<SDK_ROOT>binextensions
→ <SDK_ROOT>examplesbuildbinextensions

随后确认：

$sdkRoot = "C:pathtoOrbbecSDK"
$runDir = Join-Path $sdkRoot "examplesbuildbin"

Test-Path `
  (Join-Path $runDir "extensionsframeprocessorob_frame_processor.dll")

返回 True 后，从 buildbin 运行示例。如果 PowerShell 能运行、Visual Studio 中仍报同样错误，再检查项目“调试 → 工作目录”是否为 $(TargetDir)。