在 Raspberry Pi 5 上运行 Orbbec Gemini 335L — 工业用立体相机的设置与验证

立体相机是一种配备多个摄像头和功能的设备，它像人的双眼一样利用左右视差，主要用于实时获取距离信息。
本次使用的立体相机是 Orbbec Gemini 335L。如图所示，它由红外摄像头、激光投射器等多个组件构成。
我们确认，仅使用立体相机和 Raspberry Pi，就可以较为轻松地搭建这一系统。

1. 立体相机可以做什么？

立体相机的原理很简单。
就像人通过双眼感知距离一样，立体相机会比较两个摄像头拍摄到的图像差异，也就是视差，从而计算对象距离相机有多远。
由于相机本身内置用于数据处理的芯片，连接端设备的处理负载较低。因此，即使是 Raspberry Pi 这类算力有限的设备也比较容易使用。
此外，只需一根 USB 线即可连接运行，导入和验证的门槛也较低。

1) 距离测量与障碍物检测

从工业用途来看，在工厂内自动行驶的自主移动机器人（AMR）或机器人手臂作业现场，系统可以通过立体相机实时掌握“前方有什么”“距离多少厘米”等信息。这些信息可用于检测障碍物并停止设备，或进行绕行等控制。立体相机在照明条件变化较多的环境中也能实现较高精度的运行。

2) 尺寸测量

使用立体相机，可以非接触式地自动测量传送带上包裹的长、宽、高。
在仓库或物流中心，无需人工手动测量尺寸，有助于提高作业效率并减少测量错误。获取的数据还可以进一步用于自动化和分析。

3) 人员检测与动线分析

利用 Depth 信息（深度信息），可以实现仅靠彩色图像难以完成的定量检测。
例如，可以通过捕捉人的移动来掌握人群拥挤程度和人员流动情况。
由于深度信息以颜色表示，而不是可识别个人的图像，因此更容易实现兼顾隐私的运用。
它不仅可用于工厂，也可用于商业设施等场景。

4) 质量检测

在制造现场，零部件或产品检测有时会受到操作人员熟练程度的影响。通过使用立体相机，可以基于 3D 数据进行检测，从而更稳定地发现异常。
如果与普通相机图像结合使用，还可以同时检测颜色异常，有望提高检测精度。因此，也可以期待提升检测速度。

5) 使用 Raspberry Pi 5 快速验证

在正式运用之前，可以使用 Raspberry Pi 5 这类价格较低的设备快速进行验证。只需安装专用 SDK 和 Viewer 软件即可确认相机状态。连接也只需要一根 USB 线。
对于小规模现场，仅使用工业用 Raspberry Pi 也可能足以实现实际运用。

其他

Orbbec Gemini 系列支持 ROS 2，因此也可以直接用于机器人开发。

2. 本次环境与 Viewer

我们在以下环境中进行了确认。

测试环境

• Raspberry Pi 5
• Raspberry Pi OS 64-bit (Bookworm)
• Orbbec Gemini 335L（立体相机）
• 固件 1.4.60
• SDK v2.2.8
• OrbbecViewer

OrbbecViewer

与 SDK 分开下载的 OrbbecViewer，可以通过左侧面板和上方菜单按钮快速试用 5 个主要功能。

• Color
• Depth
• IR Left/Right
• IMU
• PointCloud

Color

Color 是普通相机图像。单独使用的场景较少，通常会与 Depth 结合，用于直观确认“哪个物体位于几米之外”。
它也可用于确认曝光、白平衡、分辨率等画质设置。这是最基本的相机图像。

Depth

Depth（深度）会以伪彩色显示距离信息。在示例程序中，距离越远显示为红色，距离越近显示为蓝色。无法测量的区域显示为黑色。

IR Left/Right

IR Left/Right 显示用于立体计算的左右红外摄像头图像。这些图像是生成 Depth 的源数据。

IMU

IMU 是 Inertial Measurement Unit（惯性测量单元）的缩写。
它提供加速度传感器和陀螺仪的数值，用于检测相机的倾斜和振动。当相机安装在机器人或无人机等移动物体上时，这些数值非常有用。

PointCloud

PointCloud 是将 Depth 作为 XYZ 坐标点集合进行 3D 显示的结果，可用于掌握空间形状。

3. SDK 与 Viewer 的设置

安装各组件之前，先确认立体相机已连接。
连接 USB 线后，可以使用 lsusb 命令确认 Gemini 335L 是否被识别。
输出中可以清楚看到 Gemini 335L 的信息。

lsusb
Bus 002 Device 002: ID 2bc5:0804 Orbbec 3D Technology International, Inc Orbbec Gemini 335L

也建议使用 lsusb -t 命令确认是否以 USB 3.0（5000M）连接。
由于 Bus 002 是 Orbbec Gemini 335L，因此可以看到 Bus 02 正以 5000M 运行。

lsusb -t
/:  Bus 02.Port 1: Dev 1, Class=root_hub, Driver=xhci-hcd/1p, 5000M
    |__ Port 1: Dev 2, If 0, Class=Video, Driver=uvcvideo, 5000M
    |__ Port 1: Dev 2, If 1, Class=Video, Driver=uvcvideo, 5000M
    |__ Port 1: Dev 2, If 2, Class=Video, Driver=uvcvideo, 5000M
    |__ Port 1: Dev 2, If 3, Class=Video, Driver=uvcvideo, 5000M
    |__ Port 1: Dev 2, If 4, Class=Video, Driver=uvcvideo, 5000M
    |__ Port 1: Dev 2, If 5, Class=Video, Driver=uvcvideo, 5000M
    |__ Port 1: Dev 2, If 6, Class=Human Interface Device, Driver=usbhid, 5000M

之后，在下载 SDK 和 Viewer 后，执行 SDK 中包含的 setup 脚本，并配置 udev 规则。两者都是 shell 脚本。
安装和构建完成后，即可通过 Viewer 或示例程序确认运行情况。

下载并设置 SDK v2.2.8

根据我们的确认，固件 1.4.60 推荐使用的 SDK 是 v2.2.8。SDK v1.x 支持到固件 v1.3.25，其推荐 SDK 为 v1.10.12。

由于本次试用的相机固件版本为 1.4.60，因此使用了推荐的 SDK v2.2.8。
截至撰写本文时，最新版本为固件 1.6.0.0 和 SDK v2.7.6。

本次创建了名为 ~/stereo-cam 的项目文件夹进行操作。
下载并解压 OrbbecSDK 和 Viewer。

# SDK 本体（库、示例、头文件）
OrbbecSDK_v2.2.8_202502141816_e0ad10e5_linux_aarch64.zip

# Viewer（独立 GUI）
OrbbecViewer_v2.2.8_202502141834_3a70bf7_linux_aarch64.zip

分别解压。

mkdir ~/stereo-cam
cd ~/stereo-cam
wget https://github.com/orbbec/OrbbecSDK_v2/releases/download/v2.2.8/OrbbecSDK_v2.2.8_202502141816_e0ad10e5_linux_aarch64.zip
wget https://github.com/orbbec/OrbbecSDK_v2/releases/download/v2.2.8/OrbbecViewer_v2.2.8_202502141834_3a70bf7_linux_aarch64.zip
unzip OrbbecSDK_v2.2.8_*.zip
unzip OrbbecViewer_v2.2.8_*.zip

执行 v2.2.8 SDK 文件夹中的设置脚本。
该脚本也会构建 examples 并创建 udev 规则。

cd ~/stereo-cam/OrbbecSDK_v2.2.8_202502141816_e0ad10e5_linux_aarch64
sudo chmod +x setup.sh
./setup.sh

过程中会出现提问，两项均回答 yes 即可。

4. 启动各示例应用的命令

注意：相机会发射激光，请勿直视相机。

在实机上运行 Viewer 或示例文件时，可以使用以下命令启动。
示例程序位于 SDK 文件夹的 /bin 目录中，Viewer 位于 OrbbecViewer 文件夹的根目录下。

LIBGL_ALWAYS_SOFTWARE=1 ./OrbbecViewer

LIBGL_ALWAYS_SOFTWARE=1
该选项用于不通过 GPU 硬件渲染 OpenGL，而是使用 CPU 软件渲染来运行。

在 Raspberry Pi 5 的默认设置中，硬件 OpenGL 是启用的。不过，在我们的环境中 OrbbecViewer 无法正常支持 Wayland 会话，因此指定了该选项。
仅使用 ./OrbbecViewer 也可以启动应用，但主显示区域会变成黑屏。

同样，在 Pi 5（Wayland 环境）上，如果不是直接在实机上启动，而是从另一台机器通过 SSH 启动，也需要指定显示器。
这是因为 SSH 会话无法直接访问 GPU。

DISPLAY=:0 LIBGL_ALWAYS_SOFTWARE=1 ./OrbbecViewer

补充：
在 X11 环境下，可能还需要添加 XAUTHORITY=$HOME/.Xauthority QT_QPA_PLATFORM=xcb 等选项。

5. 注意事项

以下是在测试时需要注意的几点。

• 相机会发射激光，请注意不要让激光直接照射人的眼睛。
• 在本次测试使用的 Raspberry Pi 5 以外的部分硬件上，Depth 流可能无法工作。
• 根据固件版本，需要确认对应的 SDK 版本组合。
• 根据相机固件版本，也确认过 SDK v1.0.27 等部分 v1 系列 SDK 可以运行。

我们在实机上确认了显示服务器是 Wayland 还是 X11。

echo $XDG_SESSION_TYPE
echo $WAYLAND_DISPLAY

# 结果
wayland
wayland-0

根据 Raspberry Pi 的型号和默认设置，兼容情况会有所不同。
同时，根据立体相机固件与 SDK 版本的组合，可用文件和脚本文件的有无也会有所不同。

详细信息请参考官方文档：https://www.orbbec.com/docs/orbbec-gemini-330-series-documentation/