GrabBag/AppAlgo/stereo_bolt_delivery/DELIVERY.md

# RK3588 四帧优化版交付说明

## 交付范围

本包是针对 `7.3` 数据集第 19、20、28、43 帧固化的 RK3588/AArch64 版本。
验收条件为每帧：

- 左眼 YOLO OBB = 8 根。
- 右眼 YOLO OBB = 8 根。
- 双目配对 = 8 根。
- 精测接口输出 = 8 根。
- 测距接口输出 = 8 根。

本包不声称已在其他帧或其他相机装配上完成泛化验收。

## 固定版本

- `lib/libstereo_bolt.so`
  SHA256: `39517a349fffc1be3da9ce565bbc5b1bde0b131a365a49eec65ec549e5e6d885`
- `weights/obb_plus_halcon_seg_1024_fp16.rknn`
  SHA256: `4db0d4b30526a4e71d63fb4c0e6ecb2b735eb756636f79e8b1a1462781cd1e72`
- YOLOv8n OBB, 1 class `bolt`, input `1024x1024`, RKNN FP16
- 标定：`calib/stereo_calib_20260621_202857_ascii.xml`
- 配置：`config/config.rk3588.12mp.yaml`
- 四帧优化配置：`config/config.rk3588.selected4.top_plane.yaml`

上述两个配置文件内容完全相同；后者是本版本的规范名称。算法库、配置、模型、
板端源码哈希及双入口验收关系见 `SELECTED4_PROVENANCE.txt`。

## 算法路线

```text
stereo rectify
-> RKNN YOLO OBB left/right
-> stereo ROI pairing
-> 2D bolt centerline and top endpoint
-> sparse stereo 3D centerline
-> SGBM support-plane fitting
-> centerline/plane intersection
-> bolt height and adjacent distances
```

顶点定义：螺杆中线与顶部端面近侧连续边缘的交点。完整的端面远/近边缘对优先于单眼孤立梯度点；
宽容度候选会标为 `suspect`，不伪装成高置信度。

高度定义：从三维顶点沿拟合螺杆轴线，到轴线与拟合支撑平面交点的距离。

## C ABI

公共头文件只有 `include/stereo_bolt/c_api.h`。主要接口：

```c
StereoBoltCtx* sb_create_ex(const StereoBoltCalibC*,
                            const StereoBoltModelC*,
                            const StereoBoltParamsC*);

sb_status_t sb_process_bolt_module_buffers(
    StereoBoltCtx*,
    const uint8_t* left, int lw, int lh, int lstride,
    const uint8_t* right, int rw, int rh, int rstride,
    int channels, int expected_count, StereoBoltModuleResultC* out);

sb_status_t sb_range_bolt_binned(
    StereoBoltCtx*,
    const uint8_t* left, int lw, int lh, int lstride,
    const uint8_t* right, int rw, int rh, int rstride,
    int channels, StereoBoltRangeSummaryC* out,
    StereoBoltRangeBoltC* bolts, int max_bolts);
```

### `sb_create_ex` 四帧参数

```c
StereoBoltParamsC p = sb_default_params();
p.wd_z_min_mm = 900.0;
p.wd_z_max_mm = 4000.0;
p.plane_use_sgbm = 1;
p.height_from_plane = 1;
p.plane_height_along_axis = 1;
p.plane_anchor_max_foot_gap_std_mm = 20.0;
p.plane_sgbm_scale = 0.25;
p.plane_max_samples = 40000;
```

新平面参数均追加在 `StereoBoltParamsC` 尾部。库依据 `struct_size` 兼容旧版较短的输入结构；
旧调用方不会被强制开启平面测高。

兼容的文件方式：

```c
StereoBoltCtx* ctx = sb_create("config/config.rk3588.12mp.yaml");
```

## RK3588 验证结果

| 帧 | 左YOLO | 右YOLO | 配对 | 精测 | 测距 | 代表距离/mm | 结果 |
|---:|---:|---:|---:|---:|---:|---:|---|
| 19 | 8 | 8 | 8 | 8 | 8 | 2298.843 | PASS |
| 20 | 8 | 8 | 8 | 8 | 8 | 2286.521 | PASS |
| 28 | 8 | 8 | 8 | 8 | 8 | 2555.266 | PASS |
| 43 | 8 | 8 | 8 | 8 | 8 | 1893.487 | PASS |

使用本包内图像和一键脚本得到的完整板端输出：
`validation/selected4_package_reverify.log`。构建目录的原始验收输出另保留为
`validation/selected4_validation_final.log`。
四组左右眼原始图像已放入 `validation/inputs/`；文件名、大小和 SHA256 见
`validation/input_sha256.csv`，也受整包 `MANIFEST_SHA256.txt` 校验保护。

## 包内容

```text
lib/                         algorithm and bundled runtime libraries
include/stereo_bolt/c_api.h  public C ABI
weights/                     selected4 RKNN model
calib/                       stereo calibration
config/                      selected4 file-based config
example/                     minimal C consumer
validation/                  board validator, one-click script, logs and four stereo pairs
SELECTED4_PROVENANCE.txt      algorithm/config/model provenance and exact hashes
ABI_FINGERPRINT.txt          binary ABI and hashes
INSTALL_3588.md              install and verification commands
```

`confidence=0` 为 `trusted`，`confidence=1` 为 `suspect`。调用方必须保留该分级，不应把 `suspect` 改写为高置信度结果。