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.4 + 全部传递依赖（131 个 .so）
├── include/stereo_bolt/  ← c_api.h（唯一对外头文件）
├── weights/              ← best_1280_20260621.rknn（NPU 模型）
├── 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   = 1280,
    .conf    = 0.5f
};
StereoBoltParamsC p = sb_default_params();
p.wd_z_min_mm = 1200;   // 工作距离下限（mm）
p.wd_z_max_mm = 2800;   // 工作距离上限（mm）

StereoBoltCtx* ctx = sb_create_ex(&calib, &model, &p);  // 只调一次（慢，载模型进 NPU）

兼容方式：sb_create("config/config.rk3588.12mp.yaml")（读文件，需工作目录正确）。模型：weights/best_1280_20260621.rknn（精测 + 测距共用，imgsz 1280）。标定：calib/stereo_calib_20260621_202857_ascii.xml（0621 装配，baseline 482 mm）。

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. 编译示例程序（可选，用于集成验证）

示例代码读图用了 OpenCV，编译时需要 OpenCV 头文件（lib/ 里只有 .so，没有 .h）。

# 安装 OpenCV 头文件（只需 -dev 包；运行库用 lib/ 里的，不用 apt 的 .so）
sudo apt install libopencv-dev

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

生产代码不需要此步骤：你自己的调用端只用 c_api.h，不引用任何 OpenCV 头，相机 buffer 直接喂给 sb_process_bolt_module_buffers，全程无 OpenCV 依赖。

8. 运行示例

# 在 stereo_bolt_delivery/ 根目录执行（使 lib/ 路径正确）
export LD_LIBRARY_PATH="$(pwd)/lib:$LD_LIBRARY_PATH"

# 精测 demo（需要左右 12MP 图，4096×3000，与标定分辨率一致）
./example/build/bolt_demo \
    calib/stereo_calib_20260621_202857_ascii.xml \
    weights/best_1280_20260621.rknn \
    /path/to/left.bmp /path/to/right.bmp 6

# 测距 demo
./example/build/range_demo \
    calib/stereo_calib_20260621_202857_ascii.xml \
    weights/best_1280_20260621.rknn \
    /path/to/left.bmp /path/to/right.bmp

板上实测吞吐：精测 ~582 ms/帧 ≈ 1.7 Hz、测距 ~238 ms/帧 ≈ 4.2 Hz（0621 装配，帧 1）。

错误码

返回值	含义
`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