3小时跑通！用Orbbec Depth Camera做一个“会自动量快递盒”的工业级小系统 📦✨

一份从零复现到效果优化的手把手教程：先用 Python 快速验证，再用 C++ 接入 OrbbecSDK v2 EnhancedDepthFilter（蚂蚁灵波模型）提升深度图质量。🔗GitHub：C++/Python

1. 这套项目到底解决什么问题？

传统人工量纸箱长宽高速度慢、误差不可控，也不适合接入自动化流水线。本项目使用 Orbbec Depth Camera，从上方采集 RGB-D 数据，自动识别纸箱顶面，计算长、宽、高和体积。

项目复现分成两个版本：

版本	定位	适合做什么	深度图处理方式
Python 快速验证版	快速跑通、调参、排查问题	找 ROI、调地面深度、保存失败样本	中值滤波 + 深度阈值分割
C++ Enhanced Depth 版	工程化增强、部署优化	接入 OrbbecSDK v2 原生链路，提高稳定性	`ob::EnhancedDepthFilter` 蚂蚁灵波模型

建议顺序是：

先跑 Python 版，确认相机、深度流、ROI、地面深度都正常。

再跑 C++ 版，接入增强深度滤波模型，提升纸箱边缘和空洞区域的深度质量。

2. 项目目录说明

假设工作目录为：

~/ws

本项目包含两个功能包：

~/ws/
  box_measurement_pyorbbecsdk2/          Python 快速验证版
  box_measurement_cpp_enhanced_depth/    C++ EnhancedDepthFilter 增强版
  OrbbecSDK_v2/                          Orbbec SDK v2 源码或构建目录

Python 版核心文件：

box_measurement_pyorbbecsdk2/
  configs/default.json
  scripts/smoke_test.py
  scripts/diagnose_capture.py
  src/box_measurement/run_live.py

C++ 版核心文件：

box_measurement_cpp_enhanced_depth/
  CMakeLists.txt
  README.md
  src/box_measure_enhanced.cpp

3. 硬件与系统要求

3.1 硬件

_cgi-bin_mmwebwx-bin_webwxgetmsgimg__&MsgID=2992740443333813346&skey=@crypt_b87d6e1d_fbb2f40d802532c1235a6a0c762d0a78&mmweb_appid=wx_webfilehelper.jpeg

Orbbec Depth Camera

NVIDIA Jetson 开发板，推荐 Jetson Orin NX 16GB

稳定电源

USB 或以太网连接

一个稳定放置的桌面、传送带或测试平台

待测纸箱

3.2 软件

Python 快速验证版需要：

Python 3.9+

pyorbbecsdk2

OpenCV

NumPy

C++ Enhanced Depth 版需要：

OrbbecSDK v2

OpenCV C++ 开发库

CMake

g++ / clang++

EnhancedDepthFilter 授权可用的设备

Jetson Linux arm64

4. SDK 安装与环境准备

4.1 Python 版安装 pyorbbecsdk2

进入 Python 功能包：

cd ~/ws/box_measurement_pyorbbecsdk2

建议使用虚拟环境：

python3 -m venv .venv
source .venv/bin/activate

安装项目和依赖：

python -m pip install -U pip
python -m pip install -e .
python -m pip install pyorbbecsdk2 opencv-python numpy

注意一个容易混淆的点：

pip 包名：pyorbbecsdk2
Python import 名：pyorbbecsdk

验证导入：

python - <<'PY'
from pyorbbecsdk import Pipeline
print("pyorbbecsdk import OK")
p = Pipeline()
print("Pipeline create OK")
PY

常见坑 1：安装了 pyorbbecsdk2，但 import 失败

检查是否装到了当前 Python 环境：

which python
python -m pip show pyorbbecsdk2

如果使用虚拟环境，必须先：

source .venv/bin/activate

4.2 Linux/Jetson 上执行 Orbbec 环境脚本

安装 pyorbbecsdk2 后，建议执行 SDK 自带环境脚本：

python - <<'PY'
import pyorbbecsdk, os
print(os.path.join(os.path.dirname(pyorbbecsdk.__file__), "shared", "setup_env.py"))
PY

复制输出路径并运行：

python /path/to/pyorbbecsdk/shared/setup_env.py

然后重新插拔相机，必要时重启 Jetson。

常见坑 2：相机没权限或打不开

表现：

No device found
Permission denied
Pipeline start error

处理方式：

执行 setup_env.py

重新插拔相机

确认 USB/网口连接稳定

如果是网口模式，确认相机和 Jetson 在同一网段

4.3 C++ 版准备 OrbbecSDK v2

假设 SDK 位于：

~/ws/OrbbecSDK_v2

先构建 SDK：

cd ~/ws/OrbbecSDK_v2
cmake -S . -B build -DBUILD_EXAMPLES=ON
cmake --build build -j4

确认主库生成：

find $HOME/ws/OrbbecSDK_v2/build -name 'libOrbbecSDK.so*'

确认生成头文件存在：

ls $HOME/ws/OrbbecSDK_v2/build/src/generated/Export.h

如果这两个命令没有输出，C++ 功能包通常无法独立编译。

常见坑 3：C++ 编译时报`Export.h: No such file or directory`

原因：独立构建时只 include 了 SDK 源码头文件，没有 include SDK 构建生成目录。

本项目的 CMakeLists.txt 已经加入：

OrbbecSDK_ROOT/build/src/generated
OrbbecSDK_ROOT/build/include

如果仍然报错，先确认：

ls $HOME/ws/OrbbecSDK_v2/build/src/generated/Export.h

5. Python 快速验证版：先把系统跑通 🚀

5.1 无相机冒烟测试

cd ~/ws/box_measurement_pyorbbecsdk2
python scripts/smoke_test.py

正常会看到类似输出：

ok: True
length_mm: 320.7
width_mm: 180.9
height_mm: 120.0

这一步用于确认算法本身、OpenCV 和 NumPy 没问题。

5.2 实时运行

进入源码目录：

cd ~/ws/box_measurement_pyorbbecsdk2/src

基础运行：

python -m box_measurement.run_live --config ../configs/default.json

更推荐使用显式参数运行：

python -m box_measurement.run_live 
  --config ../configs/default.json 
  --roi 380,160,320,280 
  --ground-depth 0.699 
  --min-depth 0.55 
  --max-depth 1.0 
  --min-height 0.04 
  --max-box-height 0.18

参数解释：

参数	含义
`--roi x,y,w,h`	只在指定区域内检测纸箱
`--ground-depth`	固定地面/桌面深度，单位米
`--min-depth`	排除太近的干扰物
`--max-depth`	排除远处背景
`--min-height`	纸箱必须高于桌面的最小高度
`--max-box-height`	排除手、支架等过高物体

5.3 快捷键

按键	功能
`s`	保存当前 RGB、深度 `.npy`、调试图和测量 JSON
`b`	用当前画面重新标定地面深度
`d`	在终端打印诊断信息
`-` / `+`	降低/提高最小箱体高度阈值
`[` / `]`	降低/提高最小轮廓面积阈值
`q` / `Esc`	退出

6. 现场调参方法：看懂诊断信息

按 d 后会打印类似信息：

ground_depth_m: 0.699
top_depth_m: 0.636
length_mm: 166.6
width_mm: 154.5
height_mm: 63.0
valid_depth_px: 23386
foreground_px: 18214
largest_contour_area_px: 17920
valid_depth_min_m: 0.611
valid_depth_median_m: 0.643
valid_depth_p90_m: 0.696

判断逻辑：

ground_depth_m - top_depth_m = height_m

如果 ground_depth_m 不接近桌面深度，高度一定不准

如果检测框贴 ROI 边缘，说明 ROI 裁到了箱体

如果 valid_depth_min_m 很小，画面里可能有手、支架或其它近物

如果 foreground_px 特别大，说明太多区域被当成箱体

7. Python 版常见坑汇总

坑 1：程序“识别不到纸盒”

优先检查：

1. ROI 是否框住纸盒
2. ground-depth 是否正确
3. min-depth/max-depth 是否把纸盒过滤掉
4. min-height 是否过高
5. 纸盒是否被 ROI 边界裁掉

建议先用较大的 ROI，然后逐步收紧。

坑 2：检测出来的框特别大

常见原因：

ground-depth 被远处背景带偏
ROI 包含桌边、墙面、支架
min-height 太低
max-depth 太大

处理方式：

python -m box_measurement.run_live 
  --config ../configs/default.json 
  --roi 380,160,320,280 
  --ground-depth 0.699 
  --min-depth 0.55 
  --max-depth 1.0 
  --min-height 0.04 
  --max-box-height 0.18

坑 3：高度不对

高度由下面公式得到：

height = ground_depth - top_depth

所以高度不对时，先不要怀疑长宽算法，优先检查地面深度。

如果按 b 后地面深度明显不合理，直接使用：

--ground-depth 0.699

坑 4：长宽偏小

常见原因是 ROI 裁到了纸箱。

判断方式：

box_points_px 的点是否贴近 ROI 边界

如果贴边，扩大 ROI。

8. C++ Enhanced Depth 版：接入蚂蚁灵波模型增强效果 🧠

C++ 版的核心链路来自 OrbbecSDK v2 官方示例：

auto alignFilter = std::make_shared<ob::Align>(OB_STREAM_COLOR);
auto enhancedDepthFilter = std::make_shared<ob::EnhancedDepthFilter>(device, modelPath);

auto aligned = alignFilter->process(frameset);
auto processed = enhancedDepthFilter->process(aligned);

增强后的 depth frame 再进入箱体测量算法。

9. C++ 版构建

进入 C++ 包：

cd ~/ws/box_measurement_cpp_enhanced_depth

独立构建：

rm -rf build
cmake -S . -B build -DOrbbecSDK_ROOT=$HOME/ws/OrbbecSDK_v2
cmake --build build -j4

CMake 会查找：

$HOME/ws/OrbbecSDK_v2/include
$HOME/ws/OrbbecSDK_v2/build/src/generated
$HOME/ws/OrbbecSDK_v2/build/include
$HOME/ws/OrbbecSDK_v2/build/**/libOrbbecSDK.so*

10. C++ 版运行

使用默认增强模型：

./build/box_measure_enhanced 
  --roi 190,100,280,240 
  --ground-depth 0.699 
  --min-depth 0.55 
  --max-depth 1.0 
  --min-height 0.04 
  --max-box-height 0.18

指定模型文件：

./build/box_measure_enhanced 
  --model /path/to/model.onnx 
  --roi 190,100,280,240 
  --ground-depth 0.699

注意：C++ 版默认使用 640x480，与官方 enhanced depth filter 示例保持一致。Python 版常用 1280x720，所以 ROI 不能直接照搬。

ROI 粗略换算：

Python: 1280x720
C++:    640x480

x_cpp = x_py * 640 / 1280
y_cpp = y_py * 480 / 720
w_cpp = w_py * 640 / 1280
h_cpp = h_py * 480 / 720

11. C++ 版常见坑汇总

坑 1：找不到`libOrbbecSDK.so`

检查：

find $HOME/ws/OrbbecSDK_v2/build -name 'libOrbbecSDK.so*'

如果没有输出，说明 SDK 主库还没构建出来。

坑 2：找不到`Export.h`

检查：

ls $HOME/ws/OrbbecSDK_v2/build/src/generated/Export.h

如果不存在，先重新构建 OrbbecSDK v2。

坑 3：EnhancedDepthFilter 启动失败

可能原因：

1. 不是 Jetson Linux arm64 平台
2. 设备不支持 license authorization
3. 设备没有 EnhancedDepthFilter 授权
4. SDK extensions 不完整
5. 指定的 model 文件路径不存在

官方示例也明确说明：EnhancedDepthFilter 只支持 Jetson Linux arm64。

坑 4：C++ 版 ROI 不对

C++ 默认分辨率是 640x480，Python 版常用 1280x720。

如果画面里绿色框切到纸箱边缘，就扩大 ROI：

--roi 170,90,330,260

再逐步收紧。

12. 技术亮点总结

12.1 顶视固定机位

通过固定相机位置，减少自由摆放造成的透视畸变和姿态估计复杂度。

12.2 深度图前景分割

相比只用 RGB 边缘，深度差更适合区分纸箱和桌面，不容易受纸箱颜色、光照和背景纹理影响。

12.3 地面基准深度

高度不依赖纸箱侧面识别，而是使用：

height = ground_depth - top_depth

这让高度估计逻辑简单、可解释、便于调试。

12.4 内参反投影计算长宽

顶面旋转矩形的像素角点通过相机内参反投影到 3D 空间，再计算真实边长。

12.5 EnhancedDepthFilter 增强深度图

C++ 版引入 Orbbec 官方增强深度滤波模型，目标是改善：

深度空洞

纸箱边缘破碎

表面深度抖动

轮廓不稳定

这对实际流水线部署很关键。

13. 推荐复现路线

如果是第一次复现，建议按这个顺序：

1. 安装 pyorbbecsdk2
2. 跑 Python smoke_test.py
3. 跑 Python 实时程序
4. 调 ROI 和 ground-depth
5. 保存几组稳定测量样本
6. 构建 OrbbecSDK v2
7. 构建 C++ Enhanced Depth 版
8. 用 Python 版参数换算 C++ ROI
9. 对比原始深度和增强深度测量效果
10. 固化最终参数

14. 最后给项目使用者的建议

这类深度相机测量项目，不要一开始就追求“所有场景自动适配”。更稳妥的工程路线是：

先固定机位。

再限定 ROI。

再标定地面深度。

再调深度范围和高度范围。

最后再用增强深度模型提升复杂表面和边缘的效果。

先把一个稳定场景做到可靠，再逐步扩大适用范围。这样项目会更容易调通，也更容易交付。