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. 解包

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）

export LD_LIBRARY_PATH="$(pwd)/lib:$LD_LIBRARY_PATH"

3. 验证依赖完整

ldd lib/libstereo_bolt.so | grep "not found"
# 应无任何输出 — 所有依赖均在 lib/ 内自洽

4. 确认 NPU 驱动

ls /dev/rknpu* /dev/dri/renderD12* 2>/dev/null
# 或: dmesg | grep -i rknpu
# 出厂 RK3588 固件一般已带；若无，需刷含 NPU 驱动的系统镜像

5. 创建上下文（推荐 `sb_create_ex`）

// 把标定矩阵/模型字节/参数结构体读进来，经接口传入——库不碰文件
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 中改为：

measurement:
  height_from_plane: true

开启后每帧增加 300-550ms 平面拟合耗时。

6. 每帧调用

// ── 精测 ──────────────────────────────────────────────────────────────────
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 调用）。

cd example
cmake -S . -B build -DSB_ROOT="$(cd .. && pwd)"
cmake --build build

生产代码同理：你自己的调用端只用 c_api.h，相机 buffer 直接喂给 sb_process_bolt_module_buffers，全程无 OpenCV 依赖。

8. 运行示例

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

6.2 KiB Raw Blame History Unescape Escape