183 lines
6.1 KiB
Markdown
183 lines
6.1 KiB
Markdown
# RK3588 安装说明
|
||
|
||
你拿到的是**预编译 aarch64 库 + 头 + 模型 + 标定 + 示例**，**依赖库已随包**，
|
||
无需联网、无需 apt 安装 OpenCV 或其他第三方库。
|
||
|
||
> **推荐用内存接口 `sb_create_ex`**：标定（矩阵）、模型（`.rknn` 字节）、参数（结构体）全部经接口传入，
|
||
> 库**零文件 IO、无路径假设、无安装目录读权限问题**。旧的 `sb_create(config.yaml)` 仅作兼容保留。
|
||
|
||
---
|
||
|
||
## 0. 适用板子
|
||
|
||
| 要求 | 值 |
|
||
|---|---|
|
||
| 架构 | **aarch64** |
|
||
| 系统 | **Ubuntu 22.04 LTS**（glibc ≥ 2.32） |
|
||
| NPU | RK3588，NPU 驱动在位（`/dev/rknpu` 或 `/dev/dri/renderD128`） |
|
||
| 联网 / apt | **不需要** |
|
||
|
||
依赖详细清单见 `DEPENDENCIES.md`。
|
||
|
||
---
|
||
|
||
## 1. 解包
|
||
|
||
```bash
|
||
tar xzf stereo_bolt_delivery_selfcontained.tar.gz
|
||
cd stereo_bolt_delivery
|
||
```
|
||
|
||
包结构：
|
||
|
||
```
|
||
stereo_bolt_delivery/
|
||
├── lib/ ← 算法库 + OpenCV 4.5.0 + librknnrt（共 9 个 .so）
|
||
├── include/stereo_bolt/ ← c_api.h（唯一对外头文件）
|
||
├── weights/ ← best_obb_1024.rknn（NPU OBB 模型）
|
||
├── calib/ ← 出厂标定 XML（0621 装配，baseline 482mm）
|
||
├── config/ ← config.rk3588.12mp.yaml（兼容接口用）
|
||
├── example/ ← 最小 C 示例 + CMakeLists
|
||
├── INSTALL_3588.md ← 本文
|
||
├── DELIVERY.md ← 接口契约
|
||
├── DEPENDENCIES.md ← 依赖库详细说明
|
||
└── ABI_FINGERPRINT.txt ← 二进制指纹
|
||
```
|
||
|
||
---
|
||
|
||
## 2. 设置库路径（一次，或写入 ~/.bashrc）
|
||
|
||
```bash
|
||
export LD_LIBRARY_PATH="$(pwd)/lib:$LD_LIBRARY_PATH"
|
||
```
|
||
|
||
---
|
||
|
||
## 3. 验证依赖完整
|
||
|
||
```bash
|
||
ldd lib/libstereo_bolt.so | grep "not found"
|
||
# 应无任何输出 — 所有依赖均在 lib/ 内自洽
|
||
```
|
||
|
||
---
|
||
|
||
## 4. 确认 NPU 驱动
|
||
|
||
```bash
|
||
ls /dev/rknpu* /dev/dri/renderD12* 2>/dev/null
|
||
# 或: dmesg | grep -i rknpu
|
||
# 出厂 RK3588 固件一般已带；若无，需刷含 NPU 驱动的系统镜像
|
||
```
|
||
|
||
---
|
||
|
||
## 5. 创建上下文（推荐 `sb_create_ex`）
|
||
|
||
```c
|
||
// 把标定矩阵/模型字节/参数结构体读进来，经接口传入——库不碰文件
|
||
StereoBoltCalibC calib = { /* K/D/R/T/size/baseline，从 calib/*.xml 读取填入 */ };
|
||
StereoBoltModelC model = {
|
||
.data = rknn_bytes, // weights/*.rknn 的原始字节
|
||
.size = rknn_size,
|
||
.backend = SB_YOLO_BACKEND_RKNN,
|
||
.imgsz = 1024,
|
||
.conf = 0.5f
|
||
};
|
||
StereoBoltParamsC p = sb_default_params();
|
||
p.wd_z_min_mm = 900; // 工作距离下限（mm）
|
||
p.wd_z_max_mm = 4000; // 工作距离上限（mm）
|
||
|
||
StereoBoltCtx* ctx = sb_create_ex(&calib, &model, &p); // 只调一次（慢，载模型进 NPU）
|
||
```
|
||
|
||
> 兼容方式：`sb_create("config/config.rk3588.12mp.yaml")`（读文件，需工作目录正确）。
|
||
> 模型：`weights/best_obb_1024.rknn`（精测 + 测距共用，OBB imgsz 1024）。
|
||
> 标定：`calib/stereo_calib_20260621_202857_ascii.xml`（0621 装配，baseline 482 mm）。
|
||
|
||
### 高度测量模式
|
||
|
||
默认 `height_from_plane: false`：高度 = 螺杆顶端到可见底端（**不跑平面拟合**，快 ~400ms/帧）。
|
||
|
||
如需平面模式（高度 = 顶端到支撑平面法向距离），在 config 中改为：
|
||
```yaml
|
||
measurement:
|
||
height_from_plane: true
|
||
```
|
||
开启后每帧增加 300-550ms 平面拟合耗时。
|
||
|
||
---
|
||
|
||
## 6. 每帧调用
|
||
|
||
```c
|
||
// ── 精测 ──────────────────────────────────────────────────────────────────
|
||
StereoBoltModuleResultC m;
|
||
int rc = sb_process_bolt_module_buffers(
|
||
ctx,
|
||
L, W, H, 0, // 左图 Mono8 buffer，stride=0 表示行紧凑
|
||
R, W, H, 0, // 右图
|
||
1, // channels：1=Mono8，3=BGR 也接受（内部转灰度）
|
||
6, &m // 期望螺栓数，输出结构体
|
||
);
|
||
// rc==SB_OK && m.success==1: m.data.bolts[i].height_mm / top_xyz / foot_xyz
|
||
// rc==SB_OK && m.success==0: m.failure.reason（算法拒绝，非崩溃）
|
||
sb_free_bolt_module_result(&m); // 必须 free
|
||
|
||
// ── 测距（2×2 binning 图）────────────────────────────────────────────────
|
||
StereoBoltRangeSummaryC s;
|
||
StereoBoltRangeBoltC bolts[64];
|
||
sb_range_bolt_binned(ctx, lb, bw, bh, 0, rb, bw, bh, 0, 1, &s, bolts, 64);
|
||
// s.distance_mm：相机到可见螺栓的代表距离（mm）
|
||
|
||
// ── 退出 ─────────────────────────────────────────────────────────────────
|
||
sb_destroy(ctx); // 只调一次
|
||
```
|
||
|
||
> ⚠️ **`sb_create_ex` 只调一次**（NPU 模型加载慢）；两个测量接口每帧复用同一个 `ctx`；
|
||
> 同一 `ctx` 不要多线程并发。
|
||
|
||
---
|
||
|
||
## 7. 编译示例程序（可选，用于集成验证）
|
||
|
||
示例代码 `main.c` 是纯 C，**不依赖 OpenCV**（读 raw Mono8 文件 + C ABI 调用）。
|
||
|
||
```bash
|
||
cd example
|
||
cmake -S . -B build -DSB_ROOT="$(cd .. && pwd)"
|
||
cmake --build build
|
||
```
|
||
|
||
> **生产代码同理**：你自己的调用端只用 `c_api.h`，
|
||
> 相机 buffer 直接喂给 `sb_process_bolt_module_buffers`，全程无 OpenCV 依赖。
|
||
|
||
---
|
||
|
||
## 8. 运行示例
|
||
|
||
```bash
|
||
# 在 stereo_bolt_delivery/ 根目录执行（使 lib/ 路径正确）
|
||
export LD_LIBRARY_PATH="$(pwd)/lib:$LD_LIBRARY_PATH"
|
||
|
||
# 精测 demo（需要左右 12MP raw Mono8，4096×3000）
|
||
./example/build/bolt_demo \
|
||
config/config.rk3588.12mp.yaml \
|
||
/path/to/left.raw /path/to/right.raw 4096 3000 8
|
||
```
|
||
|
||
板上实测吞吐：**精测 ~400 ms/帧 ≈ 2.5 Hz**（height_from_plane=false）、**测距 ~238 ms/帧 ≈ 4.2 Hz**（0621 装配）。
|
||
|
||
---
|
||
|
||
## 错误码
|
||
|
||
| 返回值 | 含义 |
|
||
|---|---|
|
||
| `SB_OK = 0` | 成功（仍需检查 `out.success` 区分"测出"/"算法拒绝"） |
|
||
| `SB_ERR_INVALID_CONFIG = -1` | 配置/标定/模型参数错误 |
|
||
| `SB_ERR_IO = -2` | 图像分辨率不匹配，或文件读取失败 |
|
||
| `SB_ERR_ALGORITHM_REJECTED = -3` | 算法拒绝（`out.failure.reason` 有原因 + 诊断信息） |
|
||
| `SB_ERR_INTERNAL = -99` | 内部错误 |
|