# 依赖库说明

本包为**自带闭包**交付。`lib/` 目录内包含 `libstereo_bolt.so` 运行所需的全部动态库，
**无需在目标板上安装 OpenCV 或任何第三方包**。

---

## 一、包含哪些库（lib/ 目录）

### 核心算法库（本包提供）
| 库 | 说明 |
|---|---|
| `libstereo_bolt.so` | 本算法库（主体） |
| `librknnrt.so` | RKNN NPU 推理运行时（Rockchip 2.3.2） |

### OpenCV 4.5.4（Ubuntu 22.04 release，aarch64）
| 库 | 用途 |
|---|---|
| `libopencv_core.so.4.5d` | 基础矩阵/图像容器 |
| `libopencv_imgproc.so.4.5d` | 图像处理（滤波、边缘、几何变换） |
| `libopencv_calib3d.so.4.5d` | 立体标定、rectify、三角测量 |
| `libopencv_imgcodecs.so.4.5d` | 图像文件读写（bmp/png/tiff） |
| `libopencv_dnn.so.4.5d` | DNN 模块（YOLO ONNX 推理备用后端） |
| `libopencv_features2d.so.4.5d` | 特征点（calib3d 依赖） |
| `libopencv_flann.so.4.5d` | FLANN 索引（features2d 依赖） |

### 图像编解码层（OpenCV 依赖）
| 库 | 用途 |
|---|---|
| `libjpeg.so.8` | JPEG |
| `libpng16.so.16` | PNG |
| `libtiff.so.5` | TIFF（含 libjbig/libdeflate/liblzma/libzstd/liblz4） |
| `libwebp.so.7` | WebP |
| `libopenjp2.so.7` | JPEG2000 |
| `libIlmImf-2_5.so.25` 等 | OpenEXR（IlmImf/Imath/Iex/IlmThread/Half） |
| `libheif.so.1` 等 | HEIF/HEVC（libaom/libde265/libx265/libdav1d） |
| `libgif.so.7` | GIF |
| `libcharls.so.2` | JPEG-LS |
| `libz.so.1` | zlib |

### 并行计算（OpenCV 依赖）
| 库 | 用途 |
|---|---|
| `libtbb.so.2` | Intel TBB 线程并行 |

### DNN / 模型序列化（OpenCV DNN 依赖）
| 库 | 用途 |
|---|---|
| `libprotobuf.so.23` | Protobuf（ONNX 模型解析） |

### GDAL / 地理空间（OpenCV imgcodecs 依赖，随包但运行中不主动调用）
libgdal、libgdcm\*、libgeotiff、libproj、libgeos\*、libogdi、libspatialite、
libnetcdf、libhdf5\*、libpq（PostgreSQL）、libmysqlclient、libsqlite3、
libcfitsio、libkml\*、libminizip、liburiparser、libxerces-c、libfreexl、
libarmadillo、libblas/liblapack/libgfortran、libarpack、libsuperlu、
libqhull\_r、libfyba/libfyut/libfygm、libblosc、libsnappy、libsz/libaec、
libmfhdfalt/libdfalt、librttopo、libxml2、libgif

### 字体 / PDF（libgdal → libpoppler 链）
libpoppler、libfreetype、libbrotli\*、libfontconfig、liblcms2

### 网络 / 安全（libgdal → libcurl 链，随包但不主动使用）
libcurl、libcurl-gnutls、libssl/libcrypto（OpenSSL 3）、libgnutls、
libnettle/libhogweed/libgmp、libp11-kit、libffi、libtasn1、
libgssapi\_krb5/libkrb5/libk5crypto/libkrb5support（Kerberos）、
libcom\_err、libkeyutils、libnghttp2、libidn2、libunistring、
librtmp、libssh、libpsl、libldap/liblber、libsasl2

### 其他系统级（随包）
libicuuc/libicudata（Unicode）、libnss\*/libnspr4/libplc4/libplds4/libsmime3（NSS）、
libuuid、libjson-c、libexpat、libpcre2-8、libltdl、libodbc/libodbcinst、
libnuma、libresolv、libtirpc

> 上述库来自 Ubuntu 22.04 apt（OpenCV 4.5.4 的官方传递依赖闭包），均为 **release/优化版本**，
> 非 debug 版。库数量约 **131 个**，打包后约 **70 MB**。

---

## 二、不在包内（由目标板系统提供）

以下是 Linux 系统 ABI 层，**必须与目标板 glibc 版本严格对齐，绝不能替换**：

| 库 | 要求 |
|---|---|
| `libc.so.6` | glibc ≥ 2.32（Ubuntu 22.04 = 2.35，满足） |
| `libpthread.so.0` | 同上（已并入 glibc 2.34+） |
| `libm.so.6` | 同上 |
| `libdl.so.2` | 同上 |
| `librt.so.1` | 同上 |
| `libstdc++.so.6` | GCC 11+（Ubuntu 22.04 自带） |
| `libgcc_s.so.1` | 同上 |
| `ld-linux-aarch64.so.1` | 动态链接器，系统自带 |

---

## 三、为什么这么设计

**问题：** OpenCV 在 Ubuntu 22.04 拖着约 131 个传递依赖（包括 GDAL、curl、Kerberos、
OpenSSL 等）。如果只靠目标板 apt 安装，新板子需要联网、可能遇到镜像源不可达、
版本不一致等问题，交付不可控。

**解法：** 把整个依赖闭包随包发布。运行时通过 `LD_LIBRARY_PATH` 优先搜索 `lib/`，
所有依赖在包内自洽。这些库只对本进程生效，**不替换系统库**，不影响系统
ssl/网络栈/其他程序。

---

## 四、运行时加载方式

```bash
# 解包后，设一次环境变量，之后所有调用本库的程序都能找到这些依赖
export LD_LIBRARY_PATH="$(pwd)/lib:$LD_LIBRARY_PATH"

# 验证：应当没有任何 "not found" 输出
ldd lib/libstereo_bolt.so | grep "not found"
```

`LD_LIBRARY_PATH` 对所有传递依赖生效——当 `libopencv_core` 加载 `libjpeg` 时，
链接器同样优先搜索 `lib/`，无需对每个 `.so` 单独处理。

---

## 五、编译调用程序时注意

运行不需要 OpenCV，但**编译** `example/` 示例代码时需要 OpenCV **头文件**
（`.h`），而 `lib/` 里只有 `.so`（运行库），没有头文件。

两种方案：

**A. 目标板上 apt 装头文件（推荐，只需一次）**
```bash
# 只装 -dev 包获取头文件；运行库用包内 lib/ 的，不用 apt 装的 .so
sudo apt install libopencv-dev
```

**B. 仅使用 C ABI，无需 OpenCV 头（生产路径）**

你自己的产品代码只用 `include/stereo_bolt/c_api.h`，不引用任何 OpenCV 头，
相机 buffer 直接传给 `sb_process_bolt_module_buffers`。这是生产路径，
**完全不需要 OpenCV 头文件**，也不需要 apt。
`example/` 仅作集成验证用，生产端不需要编译它。