GrabBag/AppAlgo/stereo_bolt_delivery/DELIVERY.md

# RK3588 螺栓测量主线路交付说明

## 交付定位

本包将原“四组图特化”实现升级为当前主线路。算法高度定义为：螺杆三维顶点沿拟合轴线，到轴线与局部支撑平面交点的距离。

推理后端只保留原有两条直接路线：

- Windows：OpenCV DNN 直接加载 ONNX。
- RK3588：RKNN Runtime 直接加载 RKNN。

本包不包含、也不依赖 AI Studio Runtime 平台封装层。公共 C ABI、输出结构和函数签名保持不变。

## 主线算法

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

主线参数：

- `plane_use_sgbm: true`
- `height_from_plane: true`
- `plane_height_along_axis: true`
- `plane_anchor_max_foot_gap_std_mm: 20.0`
- `plane_sgbm_scale: 0.25`
- `plane_max_samples: 40000`
- YOLO input `1024x1024`, confidence `0.50`, IoU `0.45`

## 固定交付件

- 算法库：`lib/libstereo_bolt.so`
  - SHA256 `5e7884a9f68ba389105d2af17f57482f4a15c2953f7845ead636653ae2d0aebd`
  - AArch64 Build ID `79fbed2add268e6ceadad58e1e8f93731c844907`
- RKNN 模型：`weights/model_20260713T084621+0000_c732327c.rknn`
  - SHA256 `b9ed3b46c416919dc969637a7093cf01312eda91320066e40e33daad56d9f169`
- 配置：`config/config.rk3588.mainline.yaml`
  - SHA256 `d9157898f966927b38cbe4d9531baa9ea514c28153001654d1e2d5c2c4ad14de`
- 标定：`calib/stereo_calib_20260621_202857_ascii.xml`
  - SHA256 `751e376ef074a4627f95256cac2ba8ea6b96dec2f672689fc5e3cf9b5cb205b4`
- 公共头文件：`include/stereo_bolt/c_api.h`
  - SHA256 `61a56da934fe4ed1fb7e98a4d145aeaf1789c56a8494ccc9bec193cf9701c163`

## 接口兼容

导出的 9 个 C 符号与 `stereo_bolt_delivery_selected4_20260710` 完全一致：

```text
sb_create
sb_create_ex
sb_default_params
sb_destroy
sb_last_error
sb_free_bolt_module_result
sb_process_bolt_module_files
sb_process_bolt_module_buffers
sb_range_bolt_binned
```

生产集成继续使用原接口。`StereoBoltParamsC` 通过 `struct_size` 兼容较短的旧调用方结构；本次没有改变任何已发布函数签名或输出结构布局。

## 验证边界

Windows 对 `7.3` 全部 79 组图像做了真实执行：测距入口 79/79 找到结果，完整 center/top 53/79，严格精测成功 24/79。选定的 19/20/28/43 四帧均为 8 检测、8 配对、8 精测成功。详细结果见 `validation/WINDOWS_7_3_VALIDATION_SUMMARY.md`。

因此，本包对四帧验收集做了完整固定验收，但不能把 24/79 的全量结果表述为已经完成全场景泛化。其余失败主要为数量不符、配对失败和测量失败，仍需要后续数据/算法迭代。

RK3588 真机从本包独立解压执行的结果如下；两种入口均为 4/4 PASS：

| 帧 | 左/右检测 | 配对 | 精测 | 测距 | 显式入口代表距离/mm |
|---:|---:|---:|---:|---:|---:|
| 19 | 8/8 | 8 | 8 | 8 | 2306.606 |
| 20 | 8/8 | 8 | 8 | 8 | 2286.189 |
| 28 | 8/8 | 8 | 8 | 8 | 2554.382 |
| 43 | 8/8 | 8 | 8 | 8 | 1890.147 |

真机原始输出保存在 `validation/mainline_package_reverify.log`，SHA256 为 `3faf413b9503400f3e89a8928108ec8bba1eb165d5e1160fd353edede74eb810`。

板端一键验收脚本同时覆盖：

1. `sb_create(YAML)` + 文件接口。
2. `sb_create_ex(model bytes)` + buffer 精测接口 + 测距接口。
3. 包内 MANIFEST 和动态依赖闭包。

本次脚本返回码为 0，末行已出现 `PACKAGE_REVERIFY_PASS`。

## 目录

```text
lib/                         主算法库、RKNN 与 OpenCV 运行库
include/stereo_bolt/c_api.h  公共 C ABI
weights/                     主线 RKNN 模型
calib/                       双目标定
config/                      RK3588 主线配置
example/                     纯 C 接入示例
validation/                  双入口验收器、日志和四组原图
ABI_FINGERPRINT.txt          ELF/ABI 指纹
SELECTED4_PROVENANCE.txt     算法、模型、配置与构建来源
INSTALL_3588.md              安装和复验命令
```