GrabBag/AppAlgo/stereo_bolt_delivery/INSTALL_3588.md

# 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_0703_20260702.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_0703_20260702.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` | 内部错误 |