SUBSCRIBE / SUBACK / UNSUBSCRIBE / UNSUBACK 报文格式

OASIS MQTT 5.0：§3.8 SUBSCRIBE、§3.9 SUBACK、§3.10 UNSUBSCRIBE、§3.11 UNSUBACK
Topic / 通配符 / 共享订阅概念见：01-主题与发布订阅模型.md

1. SUBSCRIBE（§3.8）

1.1 Fixed Header

1.2 Variable Header

1

Packet Identifier → Properties(5.0)

常见 Properties：

1.3 Payload：订阅列表

由一个或多个订阅组成，每项：

1
2
3
4

┌─────────────────────┬──────────────────┐
│ Topic Filter        │ Subscription     │
│ (UTF-8 String)      │ Options (1 byte) │
└─────────────────────┴──────────────────┘

Subscription Options（1 字节，5.0）

1
2
3
4
5
6

 bit7-6      bit5-4     bit3      bit2       bit1-0
┌──────────┬──────────┬─────────┬──────────┬─────────┐
│ Reserved │ Retain   │ Retain  │ No Local │ Maximum │
│ =0       │ Handling │ As Pub.*│          │ QoS     │
└──────────┴──────────┴─────────┴──────────┴─────────┘
* bit3: RAP — Retain As Published（名称以规范为准）

3.1.1：Payload 每项仅为 Topic Filter + Requested QoS（1 字节，高 6 位必须为 0）。

1.4 Topic Filter 规则（摘要）

• 可含 + / # 通配符（# 须单独一层且在末尾）
• MQTT 5 共享订阅：$share/{ShareName}/{TopicFilter}
• 非法 Filter → Server 在 SUBACK 返回失败 Reason，或协议错误处理

2. SUBACK（§3.9）

2.1 Fixed Header

Type=9，Flags=0000。

2.2 Variable Header

1

Packet Identifier → Properties(5.0)（Reason String、User Property…）

2.3 Payload：Reason Code 列表

• 按订阅顺序一一对应 SUBSCRIBE Payload 中的每一项
• 每个 1 字节

要点：Granted QoS 可以低于 Requested QoS；Client 必须以 SUBACK 为准。

3.1.1：Payload 为 Return Code（0x00/0x01/0x02/0x80）。

3. UNSUBSCRIBE（§3.10）

3.1 Fixed Header

Type=10，Flags=0010。

3.2 Variable Header

Packet Identifier + Properties(5.0)。

3.3 Payload

一个或多个 Topic Filter（UTF-8 String），无 Options 字节。

4. UNSUBACK（§3.11）

4.1 Fixed Header

Type=11，Flags=0000。

4.2 Variable Header

Packet Identifier + Properties(5.0)。

4.3 Payload（MQTT 5）

每个 Topic Filter 对应 1 字节 Reason Code，例如：

3.1.1：UNSUBACK 仅有 Packet Identifier，无 Payload Reason 列表。

5. 时序示例

1
2
3
4
5
6

Client ── SUBSCRIBE  (P=10, filter=siteA/+/state, maxQoS=1) ──▶ Server
Client ◀─ SUBACK     (P=10, reason=0x01 Granted QoS1) ─────── Server
Server ── PUBLISH    (匹配消息) ─────────────────────────────▶ Client

Client ── UNSUBSCRIBE (P=11, filter=siteA/+/state) ──────────▶ Server
Client ◀─ UNSUBACK    (P=11, reason=0x00) ─────────────────── Server

下一篇：14-PING-DISCONNECT-AUTH报文格式.md

PING / DISCONNECT / AUTH 报文格式

OASIS MQTT 5.0：§3.12 PINGREQ、§3.13 PINGRESP、§3.14 DISCONNECT、§3.15 AUTH
Keep Alive / 会话行为见：02-控制报文与会话.md、11-CONNECT与CONNACK报文格式.md

1. PINGREQ（§3.12）

用途：在 Keep Alive 周期内保活；证明 Client 存活且连接可用。

1

Fixed Header 仅 2 字节：0xC0 0x00

2. PINGRESP（§3.13）

1

Fixed Header：0xD0 0x00

Server 必须响应 PINGREQ。Client 若收不到 PINGRESP，应按规范处理为连接故障。

3. DISCONNECT（§3.14）

3.1 方向

• MQTT 5：Client→Server 与 Server→Client 均可发送
• MQTT 3.1.1：主要是 Client→Server；且报文极简

3.2 Fixed Header

Type=14，Flags=0000。

3.3 Variable Header（MQTT 5）

1

Reason Code (1 byte) → Properties

Remaining Length 可为 0（等价 Reason=0x00 且无属性，规范允许的简写形式）。

常见 Reason Code

常见 Properties

3.4 正常断开 vs 异常断开

MQTT 5 的 0x04 Disconnect with Will Message 允许显式要求发送 Will。

3.5 MQTT 3.1.1 DISCONNECT

• 仅 Fixed Header：0xE0 0x00
• 无 Reason / Properties

4. AUTH（§3.15，仅 MQTT 5）

用于 Enhanced Authentication 多步交换（CONNECT 中声明 Authentication Method）。

4.1 Fixed Header

Type=15，Flags=0000。

4.2 Variable Header

1

Authenticate Reason Code → Properties

Properties 必含/常含：

4.3 典型流程（概念）

1
2
3
4

Client ── CONNECT (Auth Method=…) ──▶ Server
Client ◀─ AUTH (Continue + Data) ──── Server
Client ── AUTH (Continue + Data) ───▶ Server
Client ◀─ CONNACK (Success) ───────── Server

亦可在已连接状态下 Re-authenticate。

5. 运维抓包提示

下一篇：15-Reason-Code与Properties目录.md

Reason Code 与 Properties 目录（MQTT 5）

依据 OASIS MQTT 5.0 §2.2.2 Properties、§2.4 Reason Code 及各控制报文章节整理
完整规范性定义以正式 HTML/PDF 为准：
https://docs.oasis-open.org/mqtt/mqtt/v5.0/os/mqtt-v5.0-os.html
MQTT 3.1.1 无本目录所述 Properties / 细粒度 Reason Code 体系

1. Reason Code 使用位置

0x00 在多数上下文表示成功；0x80 及以上通常表示错误（具体以该报文章节表格为准）。

2. 常用 Reason Code 速查（跨报文高频）

同一数值在不同报文中的官方名称可能略有差别；排障时以该报文章节的 Reason Code 表为准。

3. Property Identifier 目录（常用）

未列出的 Identifier 见规范完整表；实现必须忽略无法识别属性或按规范报错（视报文规则）。

4. 与本库其它文档

5. 合规声明

本目录为便于联调的速查整理。字段强制条件、默认值、哪些属性可重复、错误时关闭连接还是仅丢包等，一律以 OASIS MQTT 5.0 正式文本对应章节的 Normative 表述为准。

01 OpenCV 4.13.0 系统概述

1.1 项目定位

OpenCV（Open Source Computer Vision Library）是以 C++ 为核心的跨平台计算机视觉基础库。
它用统一的数据结构和 API 覆盖图像处理、几何视觉、视频分析、传统机器学习与神经网络推理，
并通过模块化构建、运行时后端和多级优化适配桌面、服务器、移动端与嵌入式平台。

本篇分析对象是 OpenCV 4.13.0。
源码中的版本宏位于：

1

modules/core/include/opencv2/core/version.hpp

其中 CV_VERSION_MAJOR、CV_VERSION_MINOR、CV_VERSION_REVISION
分别为 4、13、0，CV_VERSION_STATUS 为空。
运行时可使用 cv::getVersionString() 获取版本，
使用 cv::getBuildInformation() 获取本次构建的模块、依赖、CPU 特性和后端信息。

1.2 许可证与再发布边界

源码根目录 LICENSE 是 Apache License 2.0 全文，
因此 OpenCV 4.13.0 主体按 Apache License 2.0 授权。

工程使用时仍应区分三个层面：

Apache License 2.0 通常允许使用、修改和再分发，
但要求保留适用的版权、许可证和通知，并包含专利条款。
本文不构成法律意见；产品发布前应按实际启用的组件生成许可证清单。

注意：OpenCV 的许可证不能替代外部编解码器、模型权重、摄像头 SDK
或加速运行时的许可证审查。构建配置不同，最终软件的第三方义务也可能不同。

1.3 核心能力

OpenCV 4.13.0 主仓库提供的主要能力包括：

• 图像和多维数组表示、内存管理、基础算术与线性代数；
• 颜色转换、滤波、形态学、阈值、边缘、轮廓和几何变换；
• JPEG、PNG、TIFF、WebP、OpenEXR、AVIF 等格式的条件式接入；
• 文件、摄像头、视频流和图像序列的统一输入输出接口；
• 关键点、描述子、匹配、单应性和多视图几何；
• 相机标定、PnP、立体匹配和三维重建基础算法；
• 光流、背景建模、卡尔曼滤波与运动分析；
• 级联检测、二维码等目标检测能力；
• SVM、决策树、随机森林和神经网络等传统机器学习；
• 图像拼接的特征、估计、接缝、曝光补偿和融合流水线；
• ONNX、TensorFlow、Darknet 等模型格式的导入与前向推理；
• G-API 计算图、流式执行和后端映射；
• CPU SIMD、并行框架、HAL、IPP、OpenCL 和条件式设备后端。

1.4 能力边界

OpenCV 的重点是“视觉计算构件”。
它通常与应用框架、媒体系统、模型训练框架、设备 SDK 和部署运行时组合使用。

1.5 源码根目录

以下结构以 OpenCV 4.13.0 发布源码根目录为基准。
目录项承担运行代码、构建、测试、文档或发布支持等不同职责：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

opencv-4.13.0/
├── .github/          # GitHub 工作流、议题和贡献协作配置
├── 3rdparty/         # 可随源码构建的第三方组件
├── apps/             # 命令行工具和交互式应用
├── cmake/            # 依赖探测、平台判断、模块和安装逻辑
├── data/             # 级联分类器等运行数据
├── doc/              # 官方文档与教程源文件
├── hal/              # 可选 HAL 实现与适配层
├── include/          # 全局聚合入口，如 opencv2/opencv.hpp
├── modules/          # OpenCV 功能模块主体
├── platforms/        # Android、Apple、Web、Linux 等构建支持
├── samples/          # C++、Python、DNN、GPU 等示例
├── CMakeLists.txt    # 根构建入口
├── CONTRIBUTING.md   # 贡献规则
├── COPYRIGHT         # 版权说明
├── LICENSE           # Apache License 2.0
├── README.md         # 上游项目说明
└── SECURITY.md       # 安全问题报告政策

发布包、源码归档和版本控制检出可能在隐藏文件或辅助文件上略有差异，
但构建和分析的主要入口如上。

模块内部的常见结构

1
2
3
4
5
6
7
8
9

modules/<module>/
├── include/opencv2/<module>/  # 对外安装的公开头文件
├── src/                       # 内部头文件与实现
├── test/                      # 正确性、回归和异常测试
├── perf/                      # 性能测试
├── samples/                   # 模块专属示例，可能不存在
├── misc/                      # 绑定、打包或辅助元数据
├── cmake/                     # 模块局部的构建逻辑，可能不存在
└── CMakeLists.txt             # 模块声明和条件依赖

公开 API 与内部实现并非一一对应。
一个声明可能由多个平台文件、dispatch 单元、OpenCL 内核或插件共同实现。

1.6 模块分层

这是用于理解的逻辑分层，不是严格的无环分层规范。
例如某些模块具有可选依赖，G-API 和 DNN 也各自维护后端体系。
精确构建关系必须查看模块 CMakeLists.txt。

基础数据与运行设施

core 是绝大多数代码的共同底座：

• Mat、UMat、SparseMat；
• InputArray、OutputArray；
• 标量、向量、点、尺寸、范围等小型类型；
• 算术、归约、矩阵分解和随机数；
• 并行接口、TLS、日志和追踪；
• OpenCL 基础设施；
• 错误码、异常和构建信息。

flann 提供近似最近邻搜索，常被特征匹配和几何模块使用。

通用视觉算法

imgproc 构成经典视觉主干。
features2d、calib3d 和 video 在其上形成特征、几何和时序能力；
ml 主要依赖 core，提供传统机器学习算法。

边界与外部系统

imgcodecs、videoio、highgui 位于 OpenCV 与文件、设备、媒体框架和窗口系统的边界。
它们的公开接口相对稳定，但实际能力最依赖平台和构建配置。

高级图与流水线

stitching 组合多个基础模块形成完整拼接流水线。
dnn 导入并执行神经网络图。
gapi 将运算表达成计算图并映射到执行后端。
三者都不是简单的单函数算法集合。

1.7 cv::Mat 内存模型

头部与数据分离

cv::Mat 对象本身是一个矩阵头部，包含：

• 类型标志；
• 维数、每一维大小；
• 行步长或多维步长；
• 数据起始、当前视图起始和末端指针；
• 指向共享管理块 UMatData 的指针；
• 可选的 MatAllocator。

像素或矩阵元素通常位于独立分配的缓冲区中。
因此复制一个 Mat 头部的成本与复制全部像素不同。

对应声明集中在：

1

modules/core/include/opencv2/core/mat.hpp

常规创建、释放、复制等实现可从以下文件继续跟踪：

1
2

modules/core/src/matrix.cpp
modules/core/src/matrix_operations.cpp

浅拷贝、深拷贝和 ROI

OpenCV 的 Mat 不提供通用写时复制。
两个头部共享缓冲区时，通过任一可写视图修改数据，其他视图都可能看到变化。

引用计数与生命周期

UMatData 中存在 refcount 和 urefcount，
分别参与 Mat 与 UMat 侧的共享管理。
引用计数的增减是原子操作，但这不意味着对像素的并发读写自动安全。

需要区分：

• 对象生命周期安全：不同头部释放共享缓冲区时通过引用计数协调；
• 数据竞争安全：多个线程同时写同一缓冲区仍需应用自行同步；
• 外部缓冲区安全：用用户指针构造时，OpenCV 通常不接管外部内存释放。

步长与连续性

二维交错图像常见地址计算为：

1

address(y, x) = data + y * step[0] + x * elemSize()

ROI、对齐和外部缓冲区可能使 step[0] 大于一行有效像素字节数。
只有 isContinuous() 为真时，才可把所有元素视为单段连续内存处理。

type() 同时编码元素深度和通道数，例如 CV_8UC3。
elemSize() 是一个完整元素的字节数，
elemSize1() 是单通道标量的字节数。

输出分配协议

大多数函数使用 OutputArray 接收输出。
实现常调用目标对象的 create()：

1. 若现有尺寸和类型匹配，可复用缓冲区；
2. 否则释放旧引用并重新分配；
3. 输入输出别名是否允许，必须按具体 API 约定判断。

不能假设每次函数调用都新建内存，也不能假设所有函数都支持原地执行。

分配器

MatAllocator 定义分配、释放、映射、上传、下载和复制等接口。
默认 CPU Mat 使用标准分配器；
UMat 可借助分配器和 UMatData 管理主机与设备侧状态。
自定义分配器适合特殊内存，但必须严格满足对齐、生命周期和线程约定。

1.8 UMat 与透明 API

UMat 为 Transparent API（T-API）提供数据载体。
当 OpenCL 可用、被启用且具体函数存在适用内核时，
使用 UMat 的调用可以进入 OpenCL 路径。

应避免在流水线中频繁执行 Mat → UMat → Mat，
因为上传、下载、映射和同步可能抵消计算收益。
小图、短算子或不支持的类型也可能走 CPU 路径。

UMat 是条件式加速机制，不是独立 GPU 数组 API 的同义词。
是否启用 OpenCL 可通过 cv::ocl 相关接口和运行日志核验。

InputArray、OutputArray 和 InputOutputArray 是统一接收
Mat、UMat、向量等容器的代理，而非数据所有者。
从代理取出特定容器时可能发生映射或复制，别名和临时对象生命周期须按具体 API 处理。

1.9 错误模型

C++ 层

OpenCV 使用状态码枚举、断言宏和 cv::Exception 表达错误。
常见入口包括：

• CV_Error、CV_Error_；
• CV_Assert、CV_DbgAssert；
• cv::error()；
• cv::redirectError()。

主要声明位于：

1
2

modules/core/include/opencv2/core/base.hpp
modules/core/include/opencv2/core/utility.hpp

错误通常携带：

• 数值状态码；
• 错误文本；
• 触发函数；
• 源文件和行号。

在正常启用异常的 C++ 构建中，cv::error() 通常抛出 cv::Exception。
应用边界应捕获 const cv::Exception&，
并同时记录 what()、输入元数据、版本和构建信息。

1
2
3
4
5
6
7
8

try {
    cv::Mat image = cv::imread("input.png");
    if (image.empty()) {
        throw std::runtime_error("image decode returned empty result");
    }
} catch (const cv::Exception& e) {
    std::cerr << "OpenCV error: " << e.what() << '\n';
}

返回值与异常并存

并非所有失败都抛异常：

• imread() 解码失败常返回空 Mat；
• VideoCapture::open()、read() 返回 bool；
• 查询属性可能返回特殊值；
• 某些后端错误仅写日志。

因此必须同时检查返回值、输出是否为空和异常。

断言不是输入校验策略

CV_Assert 主要用于库内部前置条件。
应用对外部文件、网络输入和用户参数仍应主动校验，
不要依赖断言消息构建业务错误协议。

1.10 语言绑定

OpenCV 以 C++ API 为源头，通过模块声明和绑定生成器提供其他语言接口。
模块 CMake 中的 WRAP 列表表示该模块计划参与哪些绑定，
但最终可用性仍受 API 可包装性、平台和构建选项影响。

Python 绑定常将 C++ 异常转换为 cv2.error。
Java 包装持有原生资源时需要遵循对应生命周期接口。
JavaScript 构建通常只包含显式白名单中的能力。

WRAP python 不表示所有重载都能原样出现在 Python。
模板、指针、回调和复杂容器可能需要专门包装或根本不导出。

1.11 构建与产物概览

根 CMakeLists.txt 负责：

1. 检查平台、编译器和最低依赖版本；
2. 建立构建选项；
3. 探测 CPU 特性和第三方库；
4. 扫描模块并解析依赖；
5. 生成配置头、模块目标、绑定、测试和安装规则；
6. 输出构建摘要。

典型产物包括：

• opencv_core、opencv_imgproc 等模块库；
• 可选的单体 opencv_world；
• Python/Java 等绑定；
• 视频、GUI 或并行后端插件；
• 工具、示例和测试程序；
• CMake 包配置和 pkg-config 元数据（按配置生成）。

源码支持、构建启用、产物存在和运行时选中是四个不同状态。

1.12 源码阅读路线

路线 A：应用开发

1. 掌握 Mat 的类型、步长、ROI 和复制语义；
2. 跑通 imgcodecs → imgproc → highgui/imgcodecs；
3. 建立返回值和异常的双重检查；
4. 再进入特征、标定、视频或 DNN 专题。

路线 B：定位一个 API

1. 在 modules/<module>/include/ 找声明；
2. 在模块 CMakeLists.txt 确认依赖和条件；
3. 在 src/ 找同名函数或类方法；
4. 跟踪 dispatch.cpp、simd.hpp、HAL 或 OpenCL 分支；
5. 阅读 test/ 确认行为；
6. 阅读 perf/ 确认主要数据规模。

路线 C：平台适配

1. 阅读根 CMake 和 cmake/ 中的平台探测；
2. 区分内建后端与插件后端；
3. 明确外部库版本、链接方式和部署目录；
4. 用构建信息确认能力；
5. 在目标设备验证格式、摄像头、窗口和加速路径。

路线 D：性能优化

1. 测量端到端和单算子基线；
2. 检查不必要的深拷贝、布局转换和同步；
3. 查看 CPU dispatch、HAL、IPP、OpenCL 或设备后端；
4. 验证线程数和并行后端；
5. 同时检查速度、内存、精度和冷启动。

1.13 阅读时的注意事项

• 不要仅凭头文件判断实际实现；
• 不要仅凭 WITH_* 选项判断依赖已找到；
• 不要把 HAVE_* 宏跨构建环境外推；
• 不要假设 ROI 连续；
• 不要把引用计数安全等同于数据线程安全；
• 不要假设所有后端接受完全相同的属性；
• 不要把 DNN 后端偏好当成不回退的强制契约；
• 不要忽略首次初始化和数据搬运成本；
• 不要用主仓库结论覆盖额外模块；
• 不要在版本升级后沿用未经核验的源码路径。

1.14 后续阅读

• 模块依赖、数据流、插件和执行路径：02_系统架构.md
• 主要模块内部实现：03_核心模块详解.md
• 按业务任务组合算法：04_算法流水线.md
• HAL、SIMD、并行与加速：05_HAL与性能优化.md
• 构建、调试、测试和部署：06_配置与使用.md
• API 与实现文件定位：07_源码文件索引.md

02 OpenCV 4.13.0 系统架构

2.1 架构不是一张模块图

OpenCV 的实际行为由多套机制叠加决定：

1. 模块依赖：哪些 OpenCV 库可以参与构建；
2. 外部依赖：哪些格式、设备、GUI 和加速能力被发现；
3. 数据模型：Mat、UMat、数组代理和张量怎样流转；
4. 实现分派：通用 C++、SIMD、HAL、IPP、OpenCL 等如何选择；
5. 后端注册：VideoIO、HighGUI、DNN、G-API 如何发现实现；
6. 产物组织：分模块库、插件或 opencv_world 如何部署；
7. 调用参数：数据类型、尺寸、后端偏好和设备状态如何影响单次执行。

因此，“OpenCV 支持某功能”至少要拆成：
源码有实现、CMake 找到依赖、实现进入产物、部署完整、运行时成功选中五个问题。

2.2 模块依赖语义

OpenCV 模块通常在 modules/<module>/CMakeLists.txt 中通过
ocv_add_module() 或 ocv_define_module() 声明。

依赖可分为：

WITH_* 通常表达“用户希望启用”，
HAVE_* 通常表达“配置阶段确认可用”。
两者不能混用：设置 WITH_FFMPEG=ON 不保证最终 HAVE_FFMPEG 成立。

2.3 核验过的主干依赖

下表依据 OpenCV 4.13.0 各模块 CMake 声明整理：

表中的“可选”不表示不重要。
例如 video 缺少 dnn 仍可构建，但若干基于模型的跟踪器不会进入可用接口。

2.4 外部依赖：必需与可选

构建系统的基础要求

OpenCV 根工程由 CMake 驱动，并以 C 和 C++ 项目配置。
可工作的 C/C++ 工具链、平台标准库和 CMake 是构建基础。
Python、Java、Ant、NumPy 等只在生成相应绑定或工具时需要。

常见可选依赖

有些第三方库可使用系统版本，也可构建 3rdparty/ 中的副本；
具体策略由 CMake 选项和平台决定。

“必需”是相对于目标能力

对 core + imgproc 最小构建而言，FFmpeg 不是必需依赖；
对“必须读取 H.264 MP4”的产品需求而言，某个能完成该任务的视频后端就是业务必需依赖。
架构评审应同时记录“模块构建必需”和“产品功能必需”。

2.5 从 API 到实现

公开声明通常位于 modules/<module>/include/opencv2/<module>/，
入口实现通常位于 src/*.cpp；*.dispatch.cpp、*.simd.hpp
和 opencl/*.cl 分别是 CPU 分发、向量化主体和 OpenCL 内核的重要线索。
入口通常先校验参数并创建输出，再按数据条件选择通用、优化或外部后端。

典型调用链：GaussianBlur

cv::GaussianBlur 的公开接口属于 imgproc，
4.13.0 的主要入口位于：

1

modules/imgproc/src/smooth.dispatch.cpp

调用链可概括为：

具体选择受输入深度、通道、核大小、边界类型、输出对象种类和构建宏影响。
不能把该图理解成每次都按固定顺序执行全部判断。

典型调用链：imread

cv::imread() 的公开声明在 opencv2/imgcodecs.hpp，
实现入口位于：

1

modules/imgcodecs/src/loadsave.cpp

该文件中的 ImageCodecInitializer 保存已注册解码器和编码器，
findDecoder() 通过读取文件签名字节选择解码器，而不是只信任扩展名。

imwrite() 则主要根据文件扩展名选择编码器。
读取失败常返回空 Mat，应用必须检查 empty()；
参数错误或内部断言也可能抛出 cv::Exception。

典型调用链：VideoCapture

核心入口位于：

1
2
3

modules/videoio/src/cap.cpp
modules/videoio/src/videoio_registry.cpp
modules/videoio/src/backend_plugin.cpp

VideoCapture::open() 根据输入类型和 apiPreference
遍历支持“按索引捕获”“按文件名捕获”或“按流捕获”的后端。
注册表维护后端 ID、名称、优先级和工厂。

read() 在 cap.cpp 中组合 grab() 与 retrieve()。
成功打开不保证每个属性均可设置，也不保证属性单位在所有后端一致。

运行时可通过以下配置影响 VideoIO：

• OPENCV_VIDEOIO_PRIORITY_LIST：提高列出的后端优先级；
• OPENCV_VIDEOIO_PRIORITY_<name>：调整或以 0 禁用某后端；
• OPENCV_VIDEOIO_PLUGIN_PATH：补充插件搜索路径。

环境配置必须在相关注册表初始化前设置，并应结合日志验证。

2.6 Mat 数据流

典型 CPU 图像流水线如下：

关键数据语义：

• 解码器创建并填充目标 Mat；
• ROI 可能共享原缓冲区且不连续；
• OutputArray::create() 可复用匹配的目标内存；
• 通道顺序、色彩空间和深度必须显式管理；
• 某些算法允许原地计算，另一些不允许；
• 跨模块传递 Mat 通常不复制像素，但类型转换和布局转换会复制。

2.7 UMat 数据流

当输入或输出是 UMat 时，支持 Transparent API 的实现可使用 OpenCL：

高效用法是让一串兼容算子持续处理 UMat，
尽量推迟 getMat() 或下载。

以下情况可能破坏收益：

• 每个算子后都转回 Mat；
• 输入很小，内核启动成本占主导；
• 算子或数据类型没有 OpenCL 实现；
• 主机访问触发同步；
• OpenCL 运行时不可用或被禁用；
• OpenCL 路径内部因条件不满足回退。

Mat 与 UMat 可以通过共同的数组代理进入相同 API，
但这不代表内部存储位置和同步成本相同。

2.8 I/O 与插件架构

imgcodecs 按 HAVE_* 条件接入格式实现；
读取通常以文件签名选解码器，写入通常以扩展名选编码器。
OpenEXR 和 Jasper 等能力还可能受运行策略或强制选项影响。

VideoIO 插件与注册

modules/videoio/CMakeLists.txt 默认在多数桌面平台允许插件，
并提供：

• VIDEOIO_ENABLE_PLUGINS；
• VIDEOIO_PLUGIN_LIST；
• opencv_videoio_plugins 聚合目标。

FFmpeg、GStreamer、Media SDK/oneVPL、MSMF 等可按配置成为插件或内建实现。
注册表对不同输入形态维护可用后端列表，并按优先级选择。

部署时要同时考虑：

1. OpenCV 主库；
2. VideoIO 插件；
3. 插件依赖的第三方动态库；
4. 操作系统设备权限；
5. 网络协议、容器和编解码器实际支持；
6. ABI/API 兼容性。

HighGUI 后端

highgui 的模块必需依赖是 imgproc，
imgcodecs 和 videoio 为可选模块依赖。
实现由平台和 CMake 探测选择 Qt、GTK、Wayland、Win32、Cocoa、
Framebuffer 等路径，并支持部分 UI 插件机制。

主要入口和后端组织位于：

1
2
3

modules/highgui/src/window.cpp
modules/highgui/src/backend.cpp
modules/highgui/src/window_*.cpp

OPENCV_UI_BACKEND 可请求特定 UI 后端，
但目标后端必须已构建且能成功初始化。
无头服务器上 imshow() 失败通常是部署环境问题，不是图像算法问题。

2.9 DNN 架构

dnn 必需依赖 core 和 imgproc。
其工作可拆成模型导入、内部图、内存/张量、层实现和执行后端。

主要 API 入口与实现：

1
2
3
4

modules/dnn/include/opencv2/dnn/dnn.hpp
modules/dnn/src/net.cpp
modules/dnn/src/net_impl.cpp
modules/dnn/src/layers/

Net::setPreferableBackend() 和 setPreferableTarget() 只表达偏好组合。
是否成功取决于：

• 后端是否进入构建；
• 运行时和设备是否存在；
• 模型每个算子是否受支持；
• 数据类型、动态形状和精度是否兼容；
• 回退策略是否允许；
• 后端初始化是否成功。

DNN CUDA 后端的 CMake 条件明确要求 CUDA、cuBLAS 和 cuDNN。
仅启用 CUDA 基础模块不足以保证 DNN CUDA 可用。

2.10 G-API 架构

G-API 使用 GMat、GScalar 等描述计算，
先构建图，再编译并执行。

modules/gapi/CMakeLists.txt 明确要求 ade 目标；
缺少它时模块会被禁用。
G-API 必需依赖 imgproc，可选依赖 video 和 calib3d，
另外按构建接入 OpenVINO、GStreamer、oneVPL 等能力。

G-API 的优势来自图级信息：

• 合并或重排可执行阶段；
• 选择不同内核包；
• 构建流式处理；
• 统一管理异构后端。

代价是需要显式描述图、编译参数和后端内核，
并非所有立即执行 API 都能自动转换。

2.11 opencv_world

modules/world/CMakeLists.txt 遍历被标记为 IS_PART_OF_WORLD 的已选模块，
收集其头文件、源文件和链接依赖后生成 opencv_world。

它带来的变化是：

• 应用侧链接库数量减少；
• 模块符号聚合到一个产物；
• 部署时仍可能需要插件和外部动态库；
• 静态链接仍需处理传递依赖；
• 未启用或被排除的模块不会自动出现；
• 模块逻辑边界和命名空间不会因此消失。

world 是构建产物策略，不是比模块库多一套算法实现。

2.12 构建时选择

构建时决定：

• BUILD_LIST 或 BUILD_opencv_* 选择的模块；
• 共享库或静态库；
• 是否生成 opencv_world；
• CPU baseline 与 dispatch 指令集；
• 是否启用 OpenCL、IPP、并行框架；
• 找到哪些图像、视频、GUI 和 DNN 依赖；
• 哪些后端内建，哪些生成插件；
• 生成哪些语言绑定、测试和示例。

配置摘要是架构证据，应随二进制归档。

2.13 运行时选择

运行时还会继续决策：

选择结果可能受环境变量、动态库搜索路径、设备权限和驱动改变。
可重复部署必须控制这些外部条件。

2.14 端到端典型链：相机预处理与 DNN

该链路中最常见的架构问题是：

• 捕获后端输出格式不符合预期；
• BGR/RGB、NCHW/NHWC、缩放和均值设置错误；
• 每帧重复分配或上传下载；
• DNN 后端未实际启用；
• GUI 阻塞或服务器无显示后端；
• 视频时间戳和处理速度不匹配。

2.15 架构排错顺序

定位某项能力时建议按以下顺序：

1. 确认运行时加载的 OpenCV 版本；
2. 保存 cv::getBuildInformation()；
3. 确认模块已进入构建；
4. 核对模块必需和可选依赖；
5. 找到公开声明和入口实现；
6. 检查 WITH_*、HAVE_* 和条件编译；
7. 确认插件与第三方动态库部署；
8. 开启相关日志，记录后端枚举和选择；
9. 检查输入类型、布局、连续性和生命周期；
10. 用最小用例区分配置、数据和算法问题；
11. 阅读模块 test/ 的边界条件；
12. 最后再做性能和精度比较。

2.16 注意事项

• 模块 CMake 是依赖真相的重要来源，但最终目标仍受全局配置修改；
• 格式扩展名存在不代表对应解码器已构建；
• VideoIO 的同名属性在不同后端可能语义不同；
• 插件加载成功不代表其第三方依赖和设备初始化成功；
• Mat 浅拷贝会让跨阶段修改互相可见；
• UMat 映射回主机通常是同步点；
• DNN 指定后端不代表所有层都由该后端执行；
• G-API 编译图的成本应与重复执行次数一起评估；
• opencv_world 不消除插件和外部库依赖；
• 性能结论必须基于目标二进制、目标设备和真实数据。

2.17 后续阅读建议

理解本篇后，可继续：

• 在 03_核心模块详解.md 查看模块内部职责；
• 在 04_算法流水线.md 查看更多任务级组合；
• 在 05_HAL与性能优化.md 深入实现分派；
• 在 06_配置与使用.md 将依赖和后端落到构建命令；
• 在 07_源码文件索引.md 快速定位声明、实现、测试和性能文件。

OpenCV 4.13.0 核心模块手册

1. 手册范围与源码阅读约定

本文面向使用、调试和二次开发 OpenCV 4.13.0 的工程人员。
内容以 OpenCV 4.13.0 主仓库源码为准，不把 opencv_contrib 中的扩展模块混入主库能力。
文中路径均相对于 OpenCV 源码根目录。
17 个模块按同一组问题展开：模块解决什么问题、公开接口在哪里、内部怎样分层、数据怎样进入和离开、性能由谁决定，以及应从哪些文件开始阅读。

源码阅读建议遵循以下顺序：

1. 阅读 modules/<module>/CMakeLists.txt，确认强依赖、可选依赖和条件编译项。
2. 阅读 modules/<module>/include/opencv2/，公开头文件才是稳定使用边界。
3. 从公开 API 名称反查 modules/<module>/src/，定位调度层和通用实现。
4. 检查 modules/<module>/test/，测试比注释更能说明空输入、类型和边界行为。
5. 检查 modules/<module>/perf/，理解热点参数、基准尺寸和优化目标。
6. 遇到 .dispatch.cpp、.simd.hpp、OpenCL 或 CUDA 文件时，先区分基线实现与加速实现。
7. 不要把“头文件中存在”理解为“当前构建一定可用”；很多后端受 CMake 配置和外部库影响。

常见数据约定：

• InputArray、OutputArray 是适配层，可接收 Mat、部分 UMat、向量或数组集合。
• Mat 是带步长的引用计数视图；ROI 通常不连续，不能默认 step == cols * elemSize()。
• UMat 允许透明 API 走 OpenCL，但并不保证每个算子都留在设备端。
• 默认彩色图像通常采用 BGR 通道顺序，而不是 RGB。
• 许多几何 API 接受 float 或 double；整数点会丢失亚像素精度。
• Python 绑定由头文件注解生成，但某些 C++ 重载、模板和内部类不会原样暴露。

2. core：数据结构、运行时与数值基础

2.1 定位

core 是几乎所有 OpenCV 模块的基础依赖。
它提供矩阵容器、数组适配、标量与几何类型、内存管理、数值运算、并行框架、硬件能力检测、持久化和透明加速基础。
如果算法问题最终表现为类型、步长、引用计数、线程或分发问题，应先回到 core。

2.2 关键公开类与 API

• 数据对象：cv::Mat、cv::UMat、cv::SparseMat、cv::MatExpr。
• 类型与容器：Scalar、Point_、Size_、Rect_、Vec、Matx、Range。
• 抽象参数：InputArray、OutputArray、InputOutputArray 及数组集合版本。
• 生命周期与扩展：Algorithm、Ptr、MatAllocator。
• 线性代数：gemm、solve、invert、eigen、SVDecomp、PCA、SVD。
• 数组运算：add、multiply、normalize、reduce、split、merge、LUT、minMaxLoc。
• 频域与随机：dft、dct、RNG、randu、randn、kmeans。
• 运行时：parallel_for_、setNumThreads、getBuildInformation、checkHardwareSupport。
• 持久化：FileStorage、FileNode，支持 XML、YAML 和 JSON。

2.3 内部子系统与主要源码

• modules/core/src/matrix.cpp、matrix_operations.cpp：Mat 分配、复制、表达式和常见操作。
• modules/core/src/umatrix.cpp：UMat 生命周期、映射和设备/主机同步。
• modules/core/src/arithm.dispatch.cpp：算术运算及运行时 CPU 分发。
• modules/core/src/matmul.dispatch.cpp、matrix_decomp.cpp：矩阵乘法与分解。
• modules/core/src/alloc.cpp：对齐分配与内存接口。
• modules/core/src/system.cpp：构建信息、硬件检测、错误和时间工具。
• modules/core/src/parallel.cpp、parallel_impl.cpp：并行循环与后端适配。
• modules/core/src/ocl.cpp、opencl/：OpenCL 上下文、程序缓存和内核。
• modules/core/src/persistence*.cpp：配置序列化与格式解析。
• modules/core/include/opencv2/core/hal/：供上层算子调用的 HAL 契约。

2.4 输入输出约束

• Mat::type() 同时编码深度与通道数；CV_8UC3 不是三个独立矩阵。
• 浅拷贝只增加引用计数；需要独立数据时使用 clone() 或 copyTo()。
• reshape() 通常只改头信息，不重排元素；总元素标量数必须保持一致。
• 原地运算是否安全取决于具体 API，不能由 InputOutputArray 名称之外自行推断。
• 掩码一般要求 CV_8U 单通道，并与被处理数组的空间尺寸一致。
• solve、invert 的数值可靠性依赖分解方法、条件数和输入深度。

2.5 执行与后端特点

• CPU 路径可能经过编译期优化、运行时 SIMD 分发、IPP、HAL 或第三方线性代数库。
• setUseOptimized(false) 可辅助对比基线实现，但不等于关闭所有外部后端。
• parallel_for_ 的具体实现可能是内置线程池、TBB、OpenMP 或平台框架。
• UMat 只有在 OpenCL 可用且算子实现支持时才有收益；频繁 getMat() 会触发同步。
• 小矩阵上调度、分配和同步成本可能高于加速收益。

2.6 常见误区与阅读入口

• 误区：把 ROI 当连续内存；应检查 isContinuous() 并尊重 step。
• 误区：依赖 Mat 离开作用域后仍保留外部裸指针；引用关系必须清晰。
• 误区：认为多线程设置会让每个算法线性加速；内存带宽和算法内部并行度会限制收益。
• 推荐先读 modules/core/include/opencv2/core/mat.hpp 和 modules/core/include/opencv2/core.hpp。
• 再沿 matrix.cpp、arithm.dispatch.cpp、system.cpp、parallel_impl.cpp 阅读一次完整调用链。

3. imgproc：二维图像处理主体

3.1 定位

imgproc 覆盖颜色转换、滤波、几何变换、形态学、边缘、轮廓、直方图、分割和绘制。
它处在解码、视频采集之后，也常处在特征、标定、检测和 DNN 之前。

3.2 关键公开类与 API

• 颜色：cvtColor、cvtColorTwoPlane、demosaicing、applyColorMap。
• 滤波：filter2D、sepFilter2D、GaussianBlur、medianBlur、bilateralFilter。
• 梯度与边缘：Sobel、Scharr、Laplacian、Canny。
• 几何：resize、warpAffine、warpPerspective、remap、warpPolar。
• 形态学：erode、dilate、morphologyEx、getStructuringElement。
• 二值与区域：threshold、adaptiveThreshold、floodFill、connectedComponentsWithStats。
• 形状：findContours、approxPolyDP、convexHull、moments、fitEllipse。
• 检测与分割：HoughLinesP、HoughCircles、matchTemplate、watershed、grabCut。
• 直方图：calcHist、calcBackProject、equalizeHist、CLAHE。

3.3 内部子系统与主要源码

• modules/imgproc/src/color.cpp 及 color_*.dispatch.cpp：颜色空间调度与实现。
• modules/imgproc/src/filter.dispatch.cpp、box_filter.dispatch.cpp：卷积和可分离滤波。
• modules/imgproc/src/imgwarp.cpp：缩放、仿射、透视和重映射。
• modules/imgproc/src/morph.dispatch.cpp：腐蚀、膨胀及形态学组合。
• modules/imgproc/src/canny.cpp、hough.cpp：边缘和霍夫变换。
• modules/imgproc/src/thresh.cpp、histogram.cpp：阈值与直方图。
• modules/imgproc/src/contours_new.cpp、convhull.cpp：轮廓和几何形状。
• modules/imgproc/src/connectedcomponents.cpp：连通域标记。
• modules/imgproc/src/segmentation.cpp、grabcut.cpp：分割算法。
• modules/imgproc/src/opencl/：部分透明 API 的 OpenCL 内核。

3.4 输入输出约束

• 颜色转换必须明确源格式；相同的三通道字节可被解释为 BGR、RGB、HSV 或 YUV。
• 几何变换的 dsize 顺序是宽、高；矩阵坐标按列为 x、行为 y。
• 插值适用于连续值，标签图和掩码通常应使用 INTER_NEAREST。
• findContours 主要接收 8 位单通道二值图；层级结构由检索模式决定。
• watershed 的标记图要求 CV_32S，并会原地写回边界标记。
• filter2D 的 ddepth=-1 保持源深度，可能出现饱和截断。

3.5 执行与后端特点

• 热点算子常通过 HAL、IPP、SIMD、OpenCL 或特定库分发。
• 固定小核、可分离核和通用卷积走的路径可能不同。
• remap 可用 convertMaps 预转换映射，适合重复处理同一几何关系。
• 边界模式直接影响数值结果，BORDER_DEFAULT 不是所有算子的同一种数学外延。
• 大图流水线应尽量复用输出缓冲，避免每步重新分配。

3.6 常见误区与阅读入口

• 误区：对深度图、类别图使用普通线性缩放，造成无意义中间值。
• 误区：混淆阈值返回值与输出图；threshold 返回实际使用的阈值。
• 误区：轮廓坐标忽略 ROI 偏移；应使用 offset 或恢复全图坐标。
• 推荐从 modules/imgproc/include/opencv2/imgproc.hpp 按功能组阅读。
• 性能排查优先查看对应 .dispatch.cpp、opencl/ 和 perf/ 用例。

4. imgcodecs：静态图像编解码

4.1 定位与公开 API

imgcodecs 将文件或内存字节流转换为像素矩阵，也负责反向编码。
主要 API 是 imread、imreadmulti、imdecode、imwrite、imwritemulti、imencode。
辅助 API 包括 haveImageReader、haveImageWriter、imcount、ImageCollection。
读取标志控制灰度/彩色、原深度、方向处理和缩放版本。
写入参数使用成对整数序列，参数语义由格式决定。

4.2 内部子系统与主要源码

• modules/imgcodecs/src/loadsave.cpp：统一入口、编解码器选择、文件和内存适配。
• modules/imgcodecs/src/grfmt_base.*、grfmts.hpp：编解码器基类与注册集合。
• modules/imgcodecs/src/grfmt_jpeg.cpp、grfmt_png.cpp、grfmt_tiff.cpp：常用格式。
• modules/imgcodecs/src/grfmt_webp.cpp、grfmt_avif.cpp、grfmt_jpegxl.cpp：现代格式适配。
• modules/imgcodecs/src/grfmt_exr.cpp、grfmt_hdr.cpp：高动态范围格式。
• modules/imgcodecs/src/exif.cpp：EXIF 方向等元数据处理。

4.3 约束、后端与误区

• imread 失败返回空 Mat，调用方必须检查 empty()。
• 解码结果通常是 BGR/BGRA；位深和通道还受读取标志及编解码器能力影响。
• imdecode 输入是连续字节缓冲，不是已解压像素。
• 编解码能力取决于构建时发现的 JPEG、PNG、TIFF、OpenEXR、WebP 等库。
• 扩展名常用于写入格式选择；读取侧还会检查签名字节。
• 超大或恶意图片可能引发高内存占用，外部输入应设置尺寸和资源限制。
• 误区：以为写入浮点矩阵到任意格式都能保留浮点精度；应核对目标格式。
• 误区：忽略 EXIF 方向导致宽高和像素朝向与原始存储不一致。
• 推荐入口：公开头 modules/imgcodecs/include/opencv2/imgcodecs.hpp，实现入口 loadsave.cpp。

5. videoio：视频、相机与媒体后端统一层

5.1 定位与公开 API

videoio 统一视频文件、图像序列、相机、网络流和视频写出。
核心类是 VideoCapture、VideoWriter 和自定义流接口 IStreamReader。
常用操作包括 open、isOpened、read、grab、retrieve、get、set、write。
videoio_registry 命名空间可查询已注册后端、相机后端和流后端。
CAP_PROP_*、VIDEOWRITER_PROP_* 和 VideoAccelerationType 描述跨后端属性。

5.2 内部子系统与主要源码

• modules/videoio/src/cap.cpp：VideoCapture、VideoWriter 门面和后端选择。
• modules/videoio/src/videoio_registry.cpp：后端注册、优先级与能力查询。
• modules/videoio/src/backend_plugin.cpp：插件后端装载。
• modules/videoio/src/cap_ffmpeg.cpp、cap_ffmpeg_impl.hpp：FFmpeg 适配。
• modules/videoio/src/cap_gstreamer.cpp：GStreamer 管线适配。
• modules/videoio/src/cap_v4l.cpp、cap_msmf.cpp、cap_avfoundation.mm：平台采集。
• modules/videoio/src/cap_images.cpp：图像序列后端。
• modules/videoio/src/cap_mjpeg_decoder.cpp、cap_mjpeg_encoder.cpp：内置 Motion JPEG 路径。

5.3 约束、后端与误区

• read 合并 grab 与 retrieve；多相机同步时可先分别 grab 再 retrieve。
• 属性是后端能力请求，不保证 set 成功，也不保证读取值等于请求值。
• 帧通常输出 BGR，但原始模式、深度相机和硬件解码可能返回其他布局。
• FPS、帧号和时间戳在可变帧率、实时流及某些容器上可能不精确。
• fourcc、封装格式、编码器和像素格式是不同概念。
• FFmpeg、GStreamer、V4L2、MSMF、AVFoundation 等是否可用由构建和运行环境共同决定。
• 硬件加速需要后端、设备和编解码器三方同时支持，不能只设置一个属性。
• 误区：用无限阻塞的 read 充当可靠超时机制；实时系统应设计中断与重连。
• 推荐入口：modules/videoio/include/opencv2/videoio.hpp、cap.cpp、videoio_registry.cpp。

6. highgui：窗口、事件与轻量交互

6.1 定位与公开 API

highgui 提供调试和轻量工具所需的窗口、键鼠事件、轨迹条和按钮接口。
主要 API 是 namedWindow、imshow、waitKey、waitKeyEx、pollKey、destroyWindow。
交互 API 包括 setMouseCallback、createTrackbar、setTrackbarPos、selectROI。
它不是完整 GUI 应用框架，也不负责图像编解码。

6.2 内部子系统与主要源码

• modules/highgui/src/window.cpp：公共窗口 API 与兼容逻辑。
• modules/highgui/src/backend.cpp：现代 UI 后端抽象和选择。
• modules/highgui/src/window_gtk.cpp、window_QT.cpp：GTK 与 Qt 实现。
• modules/highgui/src/window_w32.cpp、window_wayland.cpp：Windows 与 Wayland 实现。
• modules/highgui/src/window_cocoa.mm：macOS Cocoa 实现。

6.3 约束、执行与误区

• imshow 负责显示转换，但不同深度的映射规则不同；定量检查前应显式归一化。
• waitKey 不只是等待按键，也驱动多数后端的事件处理。
• 键码高位具有后端差异；需要完整键码时使用 waitKeyEx。
• GUI API 通常要求在主线程或固定 UI 线程调用，跨线程行为依平台而异。
• 无显示服务器、容器或精简构建中，窗口后端可能不可用。
• OpenGL 窗口能力受构建选项和上下文支持影响。
• 误区：在生产服务端依赖 imshow；应把可视化与核心计算解耦。
• 误区：在回调中做长耗时计算，阻塞整个事件循环。
• 推荐入口：modules/highgui/include/opencv2/highgui.hpp、window.cpp、backend.cpp。

7. features2d：局部特征检测、描述与匹配

7.1 定位与关键 API

features2d 统一二维关键点、描述子及匹配器，是配准、检索、SLAM 前端和拼接的基础。
抽象基类 Feature2D 提供 detect、compute、detectAndCompute。
检测与描述实现包括 SIFT、ORB、BRISK、KAZE、AKAZE。
检测器还包括 FastFeatureDetector、AgastFeatureDetector、GFTTDetector、MSER、SimpleBlobDetector。
匹配抽象为 DescriptorMatcher，常用实现是 BFMatcher 和 FlannBasedMatcher。
辅助接口包括 KeyPoint、DMatch、drawKeypoints、drawMatches、KeyPointsFilter。
词袋接口包括 BOWTrainer、BOWKMeansTrainer、BOWImgDescriptorExtractor。

7.2 内部子系统与主要源码

• modules/features2d/src/feature2d.cpp：统一接口、序列化和工厂相关逻辑。
• modules/features2d/src/sift.dispatch.cpp、orb.cpp、brisk.cpp：主要特征实现。
• modules/features2d/src/kaze/、akaze.cpp：非线性尺度空间特征。
• modules/features2d/src/fast.cpp、agast.cpp、gftt.cpp：角点检测。
• modules/features2d/src/matchers.cpp：暴力与 FLANN 匹配适配。
• modules/features2d/src/draw.cpp：关键点和匹配可视化。
• modules/features2d/src/bagofwords.cpp：视觉词袋。

7.3 输入输出约束与执行特点

• 输入图像通常应为单通道 8 位；部分实现会接受彩色后内部转换，但不应依赖隐式行为。
• 掩码应为与图像同尺寸的 8 位单通道矩阵。
• SIFT、KAZE 描述子通常为浮点向量，适配 L2 距离。
• ORB、BRISK、AKAZE 的二进制描述子通常适配 Hamming 距离。
• KeyPoint::size 是特征尺度直径，不是半径；angle=-1 表示未计算方向。
• knnMatch 可能为某些查询返回少于 k 个候选，使用 Lowe 比率前必须检查长度。
• crossCheck 与 KNN 比率测试是不同筛选策略。
• 特征提取常受图像金字塔、阈值、最大特征数和边缘区域配置影响。

7.4 常见误区与阅读入口

• 误区：把二进制描述子转换为 CV_32F 后用 KD-Tree，语义已被破坏。
• 误区：仅凭描述子距离接受匹配；几何任务还应使用单应或基础矩阵做鲁棒验证。
• 误区：把关键点顺序当作跨帧稳定 ID；检测结果没有这种保证。
• 推荐入口：modules/features2d/include/opencv2/features2d.hpp。
• 实现阅读可从 feature2d.cpp、具体算法文件、matchers.cpp 串联。

8. flann：近似最近邻索引

8.1 定位与关键 API

flann 提供高维数据近似最近邻搜索，既可直接使用，也被 FlannBasedMatcher 调用。
公开门面是 cv::flann::Index。
索引参数包括 KDTreeIndexParams、KMeansIndexParams、CompositeIndexParams、LshIndexParams。
搜索参数由 SearchParams 控制检查次数、近似精度和排序行为。
核心操作是 build、knnSearch、radiusSearch、save、load。

8.2 内部子系统与主要源码

• modules/flann/include/opencv2/flann/miniflann.hpp：OpenCV 风格的公开包装。
• modules/flann/include/opencv2/flann/：索引、距离、矩阵和序列化模板实现。
• modules/flann/src/miniflann.cpp：Mat 与模板 FLANN 的桥接。
• modules/flann/src/flann.cpp：C 接口和公共实现汇集。

8.3 约束、执行与误区

• KD-Tree 等常规索引主要面向 CV_32F 特征和欧氏类距离。
• LSH 面向二进制描述子；距离和索引类型必须与描述子语义一致。
• 近似搜索以速度换召回率，checks 越大通常越接近精确结果。
• 建索引有时间和内存成本，适合被多次查询的数据集。
• 被索引数据的生命周期和连续性必须满足包装层要求，修改数据后应重建索引。
• 误区：把 FLANN 结果当确定性全排序；近似算法、随机种子和并行可能影响候选。
• 推荐入口：miniflann.hpp、miniflann.cpp，再进入对应索引模板头。

9. calib3d：相机标定与多视图几何

9.1 定位与关键 API

calib3d 处理三维视觉中的相机模型、位姿、极几何、三角化和立体匹配。
标定 API 包括 calibrateCamera、calibrateCameraRO、stereoCalibrate 和 fisheye 命名空间。
位姿 API 包括 solvePnP、solvePnPRansac、solvePnPGeneric、recoverPose。
几何估计包括 findHomography、findFundamentalMat、findEssentialMat。
校正与投影包括 undistort、initUndistortRectifyMap、stereoRectify、triangulatePoints。
立体匹配类包括 StereoMatcher、StereoBM、StereoSGBM。
标定靶检测包括 findChessboardCorners、findChessboardCornersSB 和圆点阵接口。

9.2 内部子系统与主要源码

• modules/calib3d/src/calibration.cpp：针孔相机标定与优化。
• modules/calib3d/src/fisheye.cpp：鱼眼模型。
• modules/calib3d/src/solvepnp.cpp、p3p.cpp、ap3p.cpp、sqpnp.cpp：PnP 算法族。
• modules/calib3d/src/fundam.cpp：单应、基础矩阵和本质矩阵入口。
• modules/calib3d/src/usac/：USAC 鲁棒估计框架。
• modules/calib3d/src/stereo_geom.cpp、stereosgbm.cpp、stereobm.cpp：双目几何与匹配。
• modules/calib3d/src/undistort.dispatch.cpp：去畸变映射。
• modules/calib3d/src/triangulate.cpp：三角化。
• modules/calib3d/src/chessboard.cpp：棋盘格检测。

9.3 输入输出约束

• 世界点与图像点必须一一对应；单位可自定，但平移向量继承同一单位。
• 相机矩阵通常为 3×3 浮点矩阵，畸变系数长度由模型和标志决定。
• rvec 是 Rodrigues 旋转向量，不是欧拉角；可用 Rodrigues 转换。
• solvePnP 不同方法对点数、共面性和初值有不同要求。
• findEssentialMat、recoverPose 要求相机归一化关系一致。
• StereoBM、StereoSGBM 的视差通常为定点缩放值，解释前应查看输出类型和比例。
• 三角化输出是齐次坐标，必须除以最后一维并检查数值稳定性。

9.4 执行特点、误区与阅读入口

• RANSAC/USAC 的阈值处于输入坐标单位中；缩放图像后阈值也应调整。
• 标定是非线性优化，初值、姿态覆盖、观测噪声和参数约束决定可观测性。
• 误区：仅看整体重投影 RMS 判断标定质量；还应检查每视图误差和参数合理性。
• 误区：混淆相机到世界与世界到相机变换，导致旋转和平移方向颠倒。
• 误区：用单应矩阵解释有明显视差的非平面场景。
• 推荐入口：modules/calib3d/include/opencv2/calib3d.hpp、calibration.cpp、fundam.cpp。

10. video：跨帧运动分析与跟踪

10.1 定位与关键 API

video 负责跨帧算法，不负责读取和写入媒体。
光流 API 包括 calcOpticalFlowPyrLK、calcOpticalFlowFarneback 和 readOpticalFlow。
抽象与实现包括 SparseOpticalFlow、DenseOpticalFlow、FarnebackOpticalFlow、DISOpticalFlow。
背景建模包括 BackgroundSubtractorMOG2、BackgroundSubtractorKNN 及创建函数。
状态估计使用 KalmanFilter。
目标跟踪包括 Tracker、TrackerMIL、TrackerGOTURN、TrackerDaSiamRPN、TrackerNano、TrackerVit。
区域跟踪还包括 meanShift、CamShift。

10.2 内部子系统与主要源码

• modules/video/src/lkpyramid.cpp：金字塔 Lucas–Kanade 稀疏光流。
• modules/video/src/optflowgf.cpp、dis_flow.cpp：Farneback 与 DIS 稠密光流。
• modules/video/src/bgfg_gaussmix2.cpp、bgfg_KNN.cpp：背景模型。
• modules/video/src/kalman.cpp：卡尔曼滤波。
• modules/video/src/camshift.cpp：MeanShift 与 CamShift。
• modules/video/src/tracking/：统一 Tracker 及具体实现。
• modules/video/src/optical_flow_io.cpp：.flo 光流文件读写。

10.3 约束、执行与误区

• LK 光流输入点通常是 Point2f，状态向量标识每个点是否成功。
• 前后向一致性检查可剔除遮挡、越界和不稳定轨迹。
• 稠密光流输出通常为双通道 CV_32F，分别表示 x、y 位移。
• 背景减除器是有状态对象，学习率和历史长度会改变适应速度。
• Kalman 状态、观测和控制矩阵的维度必须由调用方正确建模。
• 深度跟踪器可能依赖外部模型文件，且预处理尺寸和模型结构固定。
• 误区：把 videoio 的丢帧归因于光流；采集和分析应分别测量。
• 推荐入口：modules/video/include/opencv2/video/tracking.hpp、background_segm.hpp。

11. dnn：深度神经网络推理

11.1 定位与关键 API

dnn 导入训练好的网络并执行推理，不提供通用训练框架。
核心对象是 cv::dnn::Net、Layer、LayerParams 和 LayerFactory。
模型导入入口包括 readNet、readNetFromONNX、readNetFromTensorflow、readNetFromDarknet。
预处理包括 blobFromImage、blobFromImages、Image2BlobParams。
执行包括 setInput、forward、forwardAsync、getUnconnectedOutLayersNames。
部署配置包括 setPreferableBackend、setPreferableTarget。
后处理包括 NMSBoxes、NMSBoxesBatched、softNMSBoxes。
高层包装包括 Model、ClassificationModel、DetectionModel、SegmentationModel、KeypointsModel。

11.2 内部子系统与主要源码

• modules/dnn/src/net.cpp、net_impl.cpp：公开门面、网络状态和执行计划。
• modules/dnn/src/net_impl_fuse.cpp：层融合与图优化。
• modules/dnn/src/net_impl_backend.cpp：后端初始化和节点映射。
• modules/dnn/src/layers/：卷积、池化、激活、注意力等 CPU 层实现。
• modules/dnn/src/onnx/、tensorflow/、darknet/：模型解析与图转换。
• modules/dnn/src/ocl4dnn/、opencl/：OpenCL 加速。
• modules/dnn/src/cuda4dnn/、cuda/：CUDA 后端。
• modules/dnn/src/net_openvino.cpp、op_vkcom.cpp、op_webnn.cpp：可选后端桥接。
• modules/dnn/src/nms.cpp：检测框抑制。

11.3 输入输出约束

• blob 常为 NCHW，但实际输入名、维度、动态形状和数据类型由模型决定。
• blobFromImage 的缩放、均值、通道交换和裁剪顺序必须匹配训练预处理。
• 检测输出布局不是统一标准，高层 DetectionModel 也不能覆盖所有自定义模型。
• Net 的输入缓冲和执行状态不应在无同步保护下被多个线程共享修改。
• 动态形状、量化算子和控制流支持取决于导入器和目标后端。
• forward 返回的数据只代表指定输出层；多输出网络应显式请求输出名称。

11.4 执行特点、误区与阅读入口

• 可选后端包括 OpenCV CPU、OpenCL、CUDA、OpenVINO 等，实际集合由构建决定。
• 后端不支持的层可能回退、拒绝执行或导致分图，必须通过日志和性能剖析确认。
• FP16、INT8 能否生效取决于模型、设备、目标和层覆盖率。
• 首次推理可能包含图初始化、权重转换和内核编译，不宜直接作为稳态延迟。
• 误区：只改 swapRB 便认为预处理正确；还需核对 resize、letterbox、归一化和布局。
• 误区：把 NMS 阈值与分类置信阈值混为一谈。
• 推荐入口：modules/dnn/include/opencv2/dnn/dnn.hpp、net_impl.cpp、对应导入器目录。

12. stitching：全景拼接流水线

12.1 定位与关键 API

stitching 将特征、几何估计、投影、曝光、接缝和融合组织为完整全景管线。
高层入口是 Stitcher::create、estimateTransform、composePanorama、stitch。
模式包括面向旋转相机的 PANORAMA 和面向扫描件的 SCANS。
细节层公开 ImageFeatures、MatchesInfo、CameraParams。
匹配器包括 FeaturesMatcher、BestOf2NearestMatcher。
运动估计包括 HomographyBasedEstimator、AffineBasedEstimator 和多种 BundleAdjuster。
投影、曝光、接缝、融合分别由 RotationWarper、ExposureCompensator、SeamFinder、Blender 抽象。

12.2 内部子系统与主要源码

• modules/stitching/src/stitcher.cpp：高层状态机和阶段编排。
• modules/stitching/src/matchers.cpp：图像对匹配和置信度。
• modules/stitching/src/motion_estimators.cpp：相机估计与光束法平差。
• modules/stitching/src/warpers.cpp：平面、柱面、球面等投影。
• modules/stitching/src/exposure_compensate.cpp：增益和分块曝光补偿。
• modules/stitching/src/seam_finders.cpp：动态规划、图割等接缝。
• modules/stitching/src/blenders.cpp：羽化和多频带融合。
• modules/stitching/src/autocalib.cpp：波形校正与自动标定辅助。

12.3 约束、执行与误区

• 输入图像需要足够重叠和可重复纹理；纯色、重复纹理和运动物体会降低可靠性。
• 工作分辨率、接缝分辨率和合成分辨率是三套尺度，应保持坐标换算一致。
• PANORAMA 主要假设相机绕光心旋转；明显平移和近景视差会破坏单应模型。
• 多频带融合质量较高但内存和时间开销大。
• CUDA/OpenCL 只覆盖部分投影或融合路径，不能假定整条流水线都在设备端。
• 误区：增加所有图像总能改善结果；错误边会污染匹配图和相机估计。
• 误区：只调整融合器掩盖几何错位；应先检查匹配内点与相机参数。
• 推荐入口：modules/stitching/include/opencv2/stitching.hpp、stitcher.cpp，再深入 detail/。

13. ml：传统机器学习

13.1 定位与关键 API

ml 提供基于 Mat 的传统监督与无监督学习，适合中小规模结构化特征。
统一基类是 StatModel，数据包装为 TrainData，超参数搜索辅助为 ParamGrid。
算法包括 NormalBayesClassifier、KNearest、SVM、EM。
树模型包括 DTrees、RTrees、Boost。
神经与线性模型包括 ANN_MLP、LogisticRegression、SVMSGD。
通用接口为 train、predict、save、load、isTrained。

13.2 内部子系统与主要源码

• modules/ml/src/data.cpp：样本布局、训练/测试划分与变量类型。
• modules/ml/src/svm.cpp、svmsgd.cpp：核 SVM 与随机梯度版本。
• modules/ml/src/tree.cpp、rtrees.cpp、boost.cpp：树模型族。
• modules/ml/src/knearest.cpp、nbayes.cpp、em.cpp：经典统计模型。
• modules/ml/src/ann_mlp.cpp、lr.cpp：多层感知机和逻辑回归。
• modules/ml/src/inner_functions.cpp：共享数值辅助。

13.3 约束、执行与误区

• 默认样本布局常为每行一个样本；必须用 ROW_SAMPLE 或 COL_SAMPLE 明确表达。
• 特征通常需转换为 CV_32F；类别标签和回归响应的类型、形状要匹配算法。
• 类别变量必须通过 TrainData 的变量类型正确标记。
• 缺失值、类别编码、归一化和特征缩放不会自动按业务语义处理。
• 训练多在 CPU 完成，并非 UMat 或 GPU 训练框架。
• 模型文件应与 OpenCV 版本和算法参数共同纳入部署验证。
• 误区：在全量数据上调参后报告同一数据的准确率；必须保留独立验证集。
• 推荐入口：modules/ml/include/opencv2/ml.hpp、data.cpp 和目标算法实现文件。

14. gapi：图计算与流式执行

14.1 定位与关键 API

gapi 用声明式图描述计算，再将图编译到一个或多个执行后端。
图数据类型包括 GMat、GScalar、GArray、GOpaque、GFrame。
GComputation 表示输入到输出的计算图，可通过 compile 或 apply 执行。
GCompiled 是普通编译结果，GStreamingCompiled 面向持续数据源。
算子元信息由 GMetaArg、GMatDesc 等描述。
自定义算子使用 G_API_OP，实现通过 CPU、Fluid、OpenCL 等 kernel package 提供。
编译参数可组合 kernel、网络推理参数、队列和流式策略。

14.2 内部子系统与主要源码

• modules/gapi/src/api/：图节点、调用、数据对象和 GComputation 公共实现。
• modules/gapi/src/compiler/：图模型构建、元信息传播、岛划分和编译 Pass。
• modules/gapi/src/executor/：普通与流式执行器、队列和线程调度。
• modules/gapi/src/backends/cpu/：基于 OpenCV CPU 函数的 kernel。
• modules/gapi/src/backends/fluid/：面向缓存行和低内存占用的 Fluid 后端。
• modules/gapi/src/backends/ocl/：OpenCL kernel。
• modules/gapi/src/backends/streaming/：流式 kernel 支持。
• modules/gapi/src/streaming/：媒体源、GStreamer、oneVPL 等接入。
• modules/gapi/src/backends/ov/、onnx/：推理后端桥接。

14.3 约束、执行与误区

• 构图阶段操作的是符号对象，不会立即处理像素。
• 编译需要输入元信息；尺寸、类型变化超出已编译描述时通常需要重新编译。
• 每个图算子都必须在提供的 kernel package 中有可用实现。
• 后端划分按“岛”执行，跨岛可能发生数据适配和同步。
• Fluid 优势来自流水化和缓存局部性，不等价于一般 CPU kernel 的逐算子加速。
• 流式模式需要管理启动、拉取、停止和背压，不是简单的循环 apply。
• 误区：认为任意现有 cv:: 函数会自动进入 G-API 图；必须有对应 G-API 操作与 kernel。
• 推荐入口：modules/gapi/include/opencv2/gapi.hpp、src/api/gcomputation.cpp、src/compiler/。

15. ts：OpenCV 自身测试基础设施

15.1 定位与关键 API

ts 是 OpenCV 模块测试和性能测试的公共支撑，不是业务算法库。
公开头聚合在 modules/ts/include/opencv2/ts.hpp。
它提供测试基类、随机数据生成、矩阵比较、测试数据路径、标签和性能计时工具。
功能测试依赖 GoogleTest 风格基础设施，性能测试使用 OpenCV 的 perf 宏和运行器。

15.2 内部子系统与主要源码

• modules/ts/src/ts.cpp、ts_func.cpp：测试上下文与通用辅助。
• modules/ts/src/ts_arrtest.cpp：数组算法测试基类和误差验证。
• modules/ts/src/ts_gtest.cpp：测试框架集成。
• modules/ts/src/ts_perf.cpp：性能测试运行与统计。
• modules/ts/src/ts_tags.cpp：测试标签过滤。
• modules/ts/src/ocl_test.cpp、cuda_test.cpp：设备测试辅助。

15.3 约束、误区与阅读入口

• 测试数据根目录需要显式配置，不能依赖开发机的绝对路径。
• 数值比较应根据算法、深度和后端选择绝对或相对误差。
• 性能用例应预热并由框架控制迭代，避免把初始化成本混入稳态数据。
• 误区：应用程序链接 ts 来获得通用工具；这些接口主要服务源码树内测试。
• 推荐入口：目标模块 test/、perf/ 与 modules/ts/include/opencv2/ts/ 对照阅读。

16. world：单库聚合目标

16.1 定位与实现方式

world 不是算法模块，而是把当前构建中启用的 OpenCV 模块聚合为单个 opencv_world 库。
它的价值是简化部署和链接参数，不改变 API 命名空间、模块语义或运行时后端。
modules/world/CMakeLists.txt 负责聚合逻辑。
modules/world/include/opencv2/world.hpp 提供聚合头入口。
modules/world/src/world_init.cpp 承担生成目标所需的初始化单元。

16.2 约束、误区与阅读入口

• 单库只包含本次构建实际启用且允许聚合的模块。
• 外部第三方动态库、插件、模型和系统媒体组件不会因 world 自动静态封装。
• 使用单库可能增大链接和发布单元，也可能降低按模块裁剪的清晰度。
• 误区：认为 opencv_world 提供额外算法或自动启用所有后端。
• 推荐入口：modules/world/CMakeLists.txt，并结合顶层构建生成的模块清单核对。

17. objdetect：目标、图形码与标记检测

17.1 定位与关键 API

objdetect 汇集经典目标检测、图形码、ArUco/ChArUco 和部分 DNN 模型包装。
经典检测包括 CascadeClassifier、HOGDescriptor、groupRectangles。
图形码抽象为 GraphicalCodeDetector。
二维码接口包括 QRCodeDetector、QRCodeDetectorAruco、QRCodeEncoder。
条码接口位于 cv::barcode::BarcodeDetector。
标记接口包括 aruco::Dictionary、ArucoDetector、Board、GridBoard。
混合标定板使用 CharucoBoard 和 CharucoDetector。
人脸 DNN 包装包括 FaceDetectorYN 和 FaceRecognizerSF。

17.2 内部子系统与主要源码

• modules/objdetect/src/cascadedetect.cpp、cascadedetect_convert.cpp：级联检测和旧格式转换。
• modules/objdetect/src/hog.cpp：HOG 特征与滑窗检测。
• modules/objdetect/src/qrcode.cpp、qrcode_encoder.cpp：二维码检测、解码和编码。
• modules/objdetect/src/graphical_code_detector.cpp：图形码公共门面。
• modules/objdetect/src/barcode.cpp、barcode_detector/、barcode_decoder/：条码管线。
• modules/objdetect/src/aruco/：字典、检测、板和 ChArUco。
• modules/objdetect/src/face_detect.cpp、face_recognize.cpp：人脸模型包装。
• modules/objdetect/src/opencl/：HOG 和级联检测的部分 OpenCL 内核。

17.3 约束、执行与误区

• 级联分类器必须先成功 load；空分类器不会产生有效检测。
• HOG 的窗口、块、步长和描述子维度必须与检测器权重匹配。
• 二维码和条码检测可接受常见灰度或 BGR 图，但清晰度、静区和尺度决定解码率。
• ArUco 字典、标记边长和坐标系定义必须在生成、检测和位姿阶段一致。
• FaceDetectorYN、FaceRecognizerSF 依赖外部模型，输入尺寸与归一化由包装接口约束。
• 检测结果坐标位于输入图像坐标系，预缩放后需正确映射回原图。
• 误区：把人脸相似度阈值跨模型、跨度量直接复用。
• 推荐入口：modules/objdetect/include/opencv2/objdetect.hpp 和对应子头，再查同名源码。

18. photo：计算摄影与图像修复

18.1 定位与关键 API

photo 提供去噪、修复、HDR、曝光融合、无缝克隆和风格化处理。
去噪包括 fastNlMeansDenoising、fastNlMeansDenoisingColored、多帧版本和 denoise_TVL1。
修复使用 inpaint，算法标志包括 Telea 与 Navier–Stokes 路径。
无缝克隆包括 seamlessClone、colorChange、illuminationChange、textureFlattening。
HDR 对齐使用 AlignMTB。
相机响应标定使用 CalibrateDebevec、CalibrateRobertson。
HDR 合并与曝光融合使用 MergeDebevec、MergeRobertson、MergeMertens。
色调映射包括 Tonemap、TonemapDrago、TonemapReinhard、TonemapMantiuk。
非真实感渲染包括 edgePreservingFilter、detailEnhance、pencilSketch、stylization。

18.2 内部子系统与主要源码

• modules/photo/src/denoising.cpp、denoise_tvl1.cpp：单帧、多帧去噪。
• modules/photo/src/inpaint.cpp：图像修复。
• modules/photo/src/seamless_cloning.cpp、seamless_cloning_impl.cpp：泊松融合。
• modules/photo/src/align.cpp、calibrate.cpp、merge.cpp：HDR 管线。
• modules/photo/src/tonemap.cpp：色调映射。
• modules/photo/src/npr.cpp：风格化与细节增强。
• modules/photo/src/opencl/nlmeans.cl、cuda/nlm.cu：部分去噪加速。

18.3 约束、执行与误区

• NLM 参数以像素噪声与搜索窗口为尺度，窗口增大将显著提高计算量。
• 多帧去噪要求相邻帧已大致对齐，并正确指定目标帧索引和时间窗口。
• inpaint 掩码应为 8 位单通道，非零区域表示待修复像素。
• HDR 辐照度合并通常接收同尺寸曝光序列和对应曝光时间。
• MergeMertens 输出融合图而非物理辐照度图，不要求曝光时间。
• 色调映射把 HDR 映射到显示范围，输出仍应按目标显示/编码格式转换。
• 误区：把无缝克隆当通用几何对齐；源图、掩码和目标位置必须先合理配准。
• 推荐入口：modules/photo/include/opencv2/photo.hpp，按任务进入 denoising.cpp、merge.cpp 等。

19. 跨模块典型调用链

19.1 静态图像分析

1. imgcodecs::imread 解码文件，失败时拒绝继续。
2. core 检查尺寸、类型、连续性和数值范围。
3. imgproc::cvtColor、resize、滤波或阈值完成预处理。
4. features2d、objdetect、dnn 或 ml 执行任务算法。
5. imgproc 绘制结果，imgcodecs::imwrite 编码输出。
6. 调试时可用 highgui 展示，但生产计算不应依赖窗口事件循环。

19.2 相机标定与位姿

1. videoio::VideoCapture 采集帧并记录设备、分辨率和时间信息。
2. imgproc 转灰度，必要时做适度增强。
3. calib3d 检测标定靶，cornerSubPix 提升角点精度。
4. calibrateCamera 或鱼眼接口估计内参与畸变。
5. initUndistortRectifyMap 生成固定映射，imgproc::remap 在每帧复用。
6. solvePnP 从三维点和二维观测估计后续位姿。

19.3 特征配准与全景拼接

1. imgcodecs 或 videoio 提供图像。
2. imgproc 统一尺度和颜色。
3. features2d 检测关键点并生成描述子。
4. BFMatcher 或 FlannBasedMatcher 产生候选匹配。
5. calib3d::findHomography 配合 RANSAC/USAC 剔除外点。
6. 简单任务可用 warpPerspective；完整全景交给 stitching 的相机估计、接缝和融合阶段。

19.4 视频检测与跟踪

1. videoio 解码或采集，独立线程负责限长队列和重连。
2. imgproc 完成颜色、尺寸和归一化前处理。
3. dnn 或 objdetect 周期性给出检测框。
4. video 的光流、Kalman 或 Tracker 在检测间隔内更新状态。
5. core 管理时间戳和状态矩阵，业务层负责轨迹关联与生命周期。
6. videoio::VideoWriter 写出时明确编码器、FPS、帧尺寸和颜色约定。

19.5 HDR 与计算摄影

1. imgcodecs 以保持原位深的标志读取曝光序列。
2. photo::AlignMTB 对齐存在轻微相机移动的图像。
3. CalibrateCRF 估计响应曲线，MergeDebevec 或 MergeRobertson 合成 HDR。
4. 或使用 MergeMertens 直接进行曝光融合。
5. Tonemap 将 HDR 映射到可显示范围。
6. core 做范围检查和类型转换，imgcodecs 按目标格式编码。

19.6 G-API 流式管线

1. 用 GMat、GFrame 等符号数据声明预处理和推理图。
2. 为输入提供准确元信息和流式数据源。
3. 组合 CPU、Fluid、OpenCL 或推理 kernel package。
4. 编译器完成元信息传播、岛划分和执行计划生成。
5. GStreamingCompiled 管理启动、拉取和停止。
6. 用端到端吞吐和延迟验证跨后端复制是否抵消融合收益。

20. 二次开发指南

20.1 先选择扩展层级

• 仅组合公开 API：最稳定，优先放在应用或独立库中。
• 实现 Algorithm 派生类：适合需要统一配置、保存和工厂语义的算法。
• 为 G-API 增加操作与 kernel：适合声明式流水线和多后端部署。
• 扩展 videoio/highgui 后端：需要遵循内部后端接口与插件 ABI，维护成本较高。
• 修改模块内部实现：只在确需进入 OpenCV 主源码时采用，并准备跨平台测试。
• 新增 HAL/SIMD 路径：必须保留标量基线，并证明数值一致性和真实性能收益。

20.2 API 与数据边界

• 公开接口优先使用 InputArray/OutputArray，内部尽早解析并验证真实类型。
• 对尺寸、通道、深度、连续性、允许原地操作与空输入给出明确契约。
• 不缓存短生命周期 Mat 的裸 data 指针。
• 对 ROI、非连续矩阵和自定义步长编写专门测试。
• 算法参数应有可解释默认值，并检查非法组合。
• 序列化模型或配置时记录版本、预处理约定和坐标系。

20.3 后端与性能

• 先建立正确的 CPU 基线，再增加 SIMD、OpenCL、CUDA 或第三方后端。
• 把上传、下载、颜色转换和布局变换计入端到端性能。
• 复用模型、编译图、索引、映射表和输出缓冲。
• 避免在逐帧热路径中反复创建 Net、Stitcher、FLANN 索引或 G-API 编译结果。
• 多线程时区分对象只读共享、内部可变状态和后端上下文约束。
• 使用模块 perf/ 风格覆盖典型尺寸，也测试小输入的调度开销。

20.4 测试与诊断

• 功能测试至少覆盖空输入、最小尺寸、奇数尺寸、ROI、不同深度和多通道。
• 数值算法同时检查绝对误差、相对误差和几何不变量。
• 鲁棒估计算法固定随机种子后测试，也保留统计性压力测试。
• 后端一致性测试不能要求所有浮点位完全相同，应按误差模型设阈值。
• 通过 getBuildInformation 记录构建能力，通过 videoio registry 或 DNN 查询确认实际后端。
• 遇到性能回退时分别测量初始化、首帧、稳态和数据传输。

20.5 源码提交前检查

1. 公共声明是否只放在模块 include/opencv2/ 下。
2. 新实现是否被 CMakeLists.txt 和条件编译正确纳入。
3. 不可用可选依赖时是否仍能构建并给出明确行为。
4. C++ API、Python/Java 绑定注解和文档是否一致。
5. 新增代码是否覆盖标量基线、优化路径和异常路径。
6. 是否在目标模块 test/ 与 perf/ 增加对应案例。
7. 是否避免把机器路径、测试资产位置或外部模型硬编码进源码。

21. 模块选型与阅读路线总结

• 基础矩阵和运行时问题：从 core 开始。
• 静态图像读写与处理：imgcodecs + imgproc + core。
• 相机和视频分析：videoio + imgproc + video。
• 局部特征与几何：features2d + flann + calib3d。
• 深度推理：dnn，并按输入来源搭配 imgcodecs 或 videoio。
• 全景：优先使用 stitching 高层接口，诊断时逐层进入 detail 组件。
• 传统表格特征学习：使用 ml，把预处理和验证集策略放在模块之外。
• 声明式或流式异构图：使用 gapi，先核对 kernel 与后端覆盖。
• 图形码、标记和经典检测：使用 objdetect。
• HDR、去噪、修复和融合：使用 photo。
• OpenCV 自身测试扩展：使用 ts；应用代码不应依赖它。
• 需要简化链接时选择 world，但仍按原模块理解 API、依赖和运行时行为。

阅读任何模块时，公开头文件回答“允许怎样使用”，统一入口源码回答“如何分发”，具体算法文件回答“怎样计算”，测试与性能目录回答“边界和代价是什么”。

04 OpenCV 4.13.0 算法流水线

本章面向需要把“单个 API 示例”组装成可验证视觉系统的开发者。内容以 OpenCV 4.13.0 的公开 API 和源码头文件为准，统一按“输入 → 处理 → 输出 → 失败诊断 → 参数调整 → 验证”描述。示例默认使用 Python 接口 cv2；C++ 中对应类型通常为 cv::Mat、cv::Point2f、cv::KeyPoint 等。

本章只讨论算法流水线。模块边界、构建方式、HAL 优化和完整源码目录分别由其他章节负责。

4.1 流水线设计与输入契约

4.1.1 类型、范围与坐标

OpenCV 图像坐标原点在左上角，x 向右、y 向下；数组索引则写作 image[y, x]。裁剪 ROI 后得到的坐标相对 ROI 原点，回写原图必须加偏移。几何估计宜使用浮点坐标，标签和类别掩膜的缩放必须使用 INTER_NEAREST。

最小输入守卫：

1
2
3
4
5
6
7
8

import cv2 as cv
import numpy as np

image = cv.imread("input.png", cv.IMREAD_COLOR)
if image is None or image.size == 0:
    raise ValueError("图像读取失败或为空")
if image.dtype != np.uint8 or image.ndim != 3 or image.shape[2] != 3:
    raise TypeError(f"期望 uint8 BGR，实际为 {image.dtype}, {image.shape}")

4.1.2 可复现验证

每一级至少记录输入类型、关键参数、有效像素比例、候选数、内点率、误差分位数及耗时。调参时先固定数据、随机种子、尺寸和指标，再确认颜色、位深、范围与坐标映射；从前往后一次只调一层，先提高召回率，最后优化速度。不要只保存最终叠加图，中间掩膜、边缘、内点和重投影结果更能定位失败阶段。

4.2 图像预处理

4.2.1 API、参数和输入输出

• cv.cvtColor(src, code)：COLOR_BGR2GRAY、COLOR_BGR2HSV、COLOR_BGR2Lab 等；输出通道数由转换码决定。
• cv.resize(src, dsize, fx, fy, interpolation)：缩小优先 INTER_AREA，普通放大优先 INTER_LINEAR，离散标签使用 INTER_NEAREST。
• cv.normalize(src, dst, alpha, beta, norm_type)：可做 NORM_MINMAX 或范数归一化，不等同于神经网络的均值方差标准化。
• cv.copyMakeBorder：补边方式包括 BORDER_CONSTANT、REPLICATE、REFLECT_101。
• cv.remap(src, map1, map2, interpolation)：输入映射表常为 CV_32FC1/2 或转换后的定点格式，输出尺寸由映射表决定。

保持宽高比缩放并补边时，设原尺寸为 (W,H)、目标尺寸为 (W_t,H_t)：

[
s=\min(W_t/W,\ H_t/H),\quad W’=sW,\quad H’=sH
]

左右和上下总补边分别是 W_t-W'、H_t-H'。后续坐标映射必须执行 x=(x_t-p_x)/s、y=(y_t-p_y)/s。

1
2
3
4
5
6
7
8
9
10
11

def letterbox(bgr, size=(640, 640), value=(114, 114, 114)):
    tw, th = size
    h, w = bgr.shape[:2]
    scale = min(tw / w, th / h)
    nw, nh = round(w * scale), round(h * scale)
    resized = cv.resize(bgr, (nw, nh), interpolation=cv.INTER_LINEAR)
    left, top = (tw - nw) // 2, (th - nh) // 2
    right, bottom = tw - nw - left, th - nh - top
    out = cv.copyMakeBorder(resized, top, bottom, left, right,
                            cv.BORDER_CONSTANT, value=value)
    return out, scale, (left, top)

4.2.2 失败、调参和验证

• 失败原因：把 RGB 模型输入当 BGR；整数除法导致归一化全零；宽高顺序写反；ROI 越界；重复压缩造成细节丢失。
• 调参顺序：先定颜色空间和范围，再定目标尺寸及插值，最后选择补边和归一化。
• 验证方法：检查通道均值、直方图、角点坐标回映射误差；对掩膜确认缩放后类别集合没有新增值。

4.3 滤波、增强与二值化

4.3.1 滤波与增强

• GaussianBlur(src, ksize, sigmaX, sigmaY=0)：核尺寸通常为正奇数；适合近似高斯噪声。
• medianBlur(src, ksize)：ksize 为大于 1 的奇数；对椒盐噪声稳健。
• bilateralFilter(src, d, sigmaColor, sigmaSpace)：同时按空间距离和颜色差加权，保边但较慢。
• equalizeHist(src)：只接受 8 位单通道图；彩色图宜仅均衡亮度通道。
• createCLAHE(clipLimit, tileGridSize)：限制局部对比度，降低全局均衡放大噪声的风险。

高斯滤波可写为：

[
G(x,y)=\frac{1}{2\pi\sigma^2}\exp\left(-\frac{x^2+y^2}{2\sigma^2}\right),\quad I’=G*I
]

双边滤波的权重同时包含空间项与强度项：

[
w(p,q)\propto \exp(-|p-q|^2/2\sigma_s^2)\exp(-|I_p-I_q|^2/2\sigma_r^2)
]

4.3.2 二值化

• threshold(src, thresh, maxval, type)：输入通常为单通道；返回实际阈值和输出图。
• THRESH_OTSU 自动寻找类间方差最大的阈值，应与 THRESH_BINARY 或反相模式组合。
• adaptiveThreshold 要求 8 位单通道输入；blockSize 必须为大于 1 的奇数，C 从局部均值或高斯加权均值中扣除。
• 目标比背景暗时，优先考虑 THRESH_BINARY_INV，避免后续把背景当作前景。

Otsu 最大化类间方差：

[
\sigma_b^2(t)=\omega_0(t)\omega_1(t)\left[\mu_0(t)-\mu_1(t)\right]^2
]

1
2
3
4
5
6
7

gray = cv.cvtColor(image, cv.COLOR_BGR2GRAY)
gray = cv.GaussianBlur(gray, (5, 5), 0)
clahe = cv.createCLAHE(clipLimit=2.0, tileGridSize=(8, 8))
enhanced = clahe.apply(gray)
otsu_t, mask = cv.threshold(
    enhanced, 0, 255, cv.THRESH_BINARY + cv.THRESH_OTSU
)

4.3.3 失败、调参和验证

• 失败原因：光照梯度破坏全局阈值双峰假设；核过大吞掉细线；CLAHE 放大纹理和噪声；前景极少时 Otsu 偏向背景。
• 调参顺序：先决定灰度/亮度通道和前景极性；再按噪声选滤波器；随后调增强；最后调阈值、blockSize 和 C。
• 验证方法：画灰度直方图；统计前景比例；在标注集上计算 Precision、Recall、IoU；用不同曝光和噪声级别做扰动测试。

4.4 形态学处理

结构元素可由 getStructuringElement(MORPH_RECT/MORPH_ELLIPSE/MORPH_CROSS, ksize) 构造。erode、dilate 和 morphologyEx 接受灰度或多通道图，但语义最清晰的输入通常是 {0,255} 二值图；输出尺寸和类型默认不变。

集合意义下，腐蚀与膨胀为：

[
A\ominus B={z\mid B_z\subseteq A},\qquad
A\oplus B={z\mid (\hat B)_z\cap A\neq\varnothing}
]

开运算是 (A⊖B)⊕B，闭运算是 (A⊕B)⊖B。MORPH_GRADIENT 近似膨胀减腐蚀，MORPH_TOPHAT 提取比结构元素小的亮结构，MORPH_BLACKHAT 提取暗结构。

1
2
3

kernel = cv.getStructuringElement(cv.MORPH_ELLIPSE, (5, 5))
opened = cv.morphologyEx(mask, cv.MORPH_OPEN, kernel, iterations=1)
clean = cv.morphologyEx(opened, cv.MORPH_CLOSE, kernel, iterations=2)

• 失败原因：结构元素大于目标最窄部分；迭代过多合并相邻目标；前景极性颠倒；边界补值引入伪结构。
• 调参顺序：先确认白色代表前景，再按缺陷方向选操作，随后选形状，再从小核、单次迭代开始。
• 验证方法：比较连通域数量、面积分布、孔洞数和细线保留率；用异或图显示处理前后改变的像素。

4.5 Canny 与梯度

4.5.1 梯度 API 与原理

Sobel(src, ddepth, dx, dy, ksize, scale, delta) 输出导数图；对 8 位输入常用 CV_16S 或 CV_32F，不能直接用 CV_8U 保存带符号梯度。Scharr 使用固定高精度 3×3 核，适合小核一阶导。magnitude 和 phase 可由 Gx/Gy 得到幅值与方向。

[
G=\sqrt{G_x^2+G_y^2},\qquad \theta=\operatorname{atan2}(G_y,G_x)
]

Canny(image, threshold1, threshold2, apertureSize=3, L2gradient=False) 接受 8 位图；低阈值以下丢弃，高阈值以上保留，中间像素仅在连接强边缘时保留。L2gradient=False 使用 |Gx|+|Gy| 近似幅值，设为 True 使用欧氏幅值。

1
2
3
4
5
6

gray = cv.cvtColor(image, cv.COLOR_BGR2GRAY)
blur = cv.GaussianBlur(gray, (5, 5), 1.2)
gx = cv.Scharr(blur, cv.CV_32F, 1, 0)
gy = cv.Scharr(blur, cv.CV_32F, 0, 1)
mag = cv.magnitude(gx, gy)
edges = cv.Canny(blur, 50, 150, apertureSize=3, L2gradient=True)

4.5.2 失败、调参和验证

• 失败原因：低阈值太低导致纹理泛滥；高阈值太高造成断边；平滑过强令弱边缘消失；图像动态范围变化使固定阈值失效。
• 调参顺序：先控制输入尺度和降噪，再看梯度幅值分布，先调高阈值定位强边，再调低阈值连接，最后考虑形态学闭合。
• 验证方法：边缘像素比例、与标注边缘的容差匹配 F1、轮廓闭合率；同时检查 Gx、Gy，避免只看最终 Canny 图。

4.6 轮廓与形状分析

4.6.1 API 和类型

• findContours(image, mode, method)：输入为 8 位单通道二值图；RETR_EXTERNAL 仅取外轮廓，RETR_TREE 建立完整嵌套层级。
• CHAIN_APPROX_SIMPLE 压缩水平、垂直和斜线共线点；需要全部边界点时用 CHAIN_APPROX_NONE。
• contourArea(contour, oriented=False) 返回面积；arcLength(contour, closed) 返回周长。
• approxPolyDP(curve, epsilon, closed) 使用 Douglas–Peucker 近似；常设 epsilon=k×周长。
• boundingRect 返回轴对齐整数框；minAreaRect 返回旋转矩形；fitEllipse 至少需要 5 个点。
• moments 给出空间矩；当 m00 != 0 时质心为 (m10/m00, m01/m00)。

圆度常定义为：

[
C=\frac{4\pi A}{P^2}
]

理想圆接近 1；像素化和轮廓噪声会使其下降。矩形填充率可取 A/(w·h)，凸度可取 A/A_hull。

1
2
3
4
5
6
7
8
9
10
11

contours, hierarchy = cv.findContours(
    mask, cv.RETR_EXTERNAL, cv.CHAIN_APPROX_SIMPLE
)
shapes = []
for cnt in contours:
    area = cv.contourArea(cnt)
    if area < 200:
        continue
    perimeter = cv.arcLength(cnt, True)
    polygon = cv.approxPolyDP(cnt, 0.02 * perimeter, True)
    shapes.append((cnt, polygon, area))

4.6.2 失败、调参和验证

• 失败原因：轮廓断裂；噪声产生大量小轮廓；ROI 偏移未还原；用像素面积固定阈值处理多分辨率数据；忽略层级导致孔洞误计。
• 调参顺序：先改善掩膜闭合性，再选检索模式，然后按相对面积过滤，最后调近似误差和形状指标。
• 验证方法：把轮廓、顶点编号和层级叠加到原图；检查面积守恒；对旋转、缩放样本验证归一化指标稳定性。

4.7 几何变换与文档扫描

4.7.1 变换模型

仿射变换用 2×3 矩阵，保持平行关系；透视变换用单应矩阵：

[
s\begin{bmatrix}x’\y’\1\end{bmatrix}
=H\begin{bmatrix}x\y\1\end{bmatrix},\quad H\in\mathbb{R}^{3\times3}
]

getAffineTransform 需要三对点，getPerspectiveTransform 需要四对对应点。warpAffine/warpPerspective 的 dsize 是输出 (width,height)。perspectiveTransform 用于变换点集，不用于重采样整幅图。remap 适合相机去畸变或任意稠密映射。

四点排序不能仅在所有视角下机械依赖坐标和差；更稳妥的做法是先取凸包、验证四边形非自交，再按质心极角排序并统一起点和方向。

1
2
3
4
5
6
7
8

src = np.array([[120, 80], [920, 110], [890, 680], [90, 650]],
               dtype=np.float32)
dst = np.array([[0, 0], [799, 0], [799, 599], [0, 599]],
               dtype=np.float32)
H = cv.getPerspectiveTransform(src, dst)
scan = cv.warpPerspective(image, H, (800, 600),
                          flags=cv.INTER_LINEAR,
                          borderMode=cv.BORDER_REPLICATE)

4.7.2 失败、调参和验证

• 失败原因：四角顺序不一致导致翻转；候选不是凸四边形；文档边缘出画；镜头畸变未校正；纸张弯曲却使用平面单应。
• 调参顺序：先去畸变，再提高边缘召回，按面积/凸性/角度筛四边形，最后确定输出比例与插值。
• 验证方法：将目标四角通过逆单应投回原图；计算边线直线度、相邻边夹角、文字行水平度和正反向变换误差。

4.8 特征匹配与几何验证

4.8.1 描述子与匹配器

SIFT_create 生成 CV_32F 浮点描述子，常用 L2 距离；ORB_create 生成 CV_8U 二进制描述子，使用 NORM_HAMMING。BFMatcher.knnMatch(k=2) 可做比率测试；crossCheck=True 只适用于一一最近邻匹配，不与 KNN 比率测试同时使用。

Lowe 比率判据为：

[
d_1 < r d_2
]

其中 d1,d2 是最近与次近距离，r 常从 0.7~0.8 起试。它只衡量描述子歧义，不能代替几何验证。

• 平面场景或纯旋转：findHomography(..., RANSAC/USAC_MAGSAC, ransacReprojThreshold)。
• 未标定一般双视图：findFundamentalMat，满足 x_2^T F x_1=0。
• 已知相机内参：findEssentialMat 与 recoverPose，满足 x_2^T E x_1=0。

1
2
3
4
5
6
7
8
9
10
11
12
13

gray1 = cv.cvtColor(image1, cv.COLOR_BGR2GRAY)
gray2 = cv.cvtColor(image2, cv.COLOR_BGR2GRAY)
orb = cv.ORB_create(nfeatures=2000)
kp1, des1 = orb.detectAndCompute(gray1, None)
kp2, des2 = orb.detectAndCompute(gray2, None)
if des1 is None or des2 is None:
    raise RuntimeError("描述子为空")
knn = cv.BFMatcher(cv.NORM_HAMMING).knnMatch(des1, des2, k=2)
good = [m for pair in knn if len(pair) == 2
        for m, n in [pair] if m.distance < 0.75 * n.distance]
pts1 = np.float32([kp1[m.queryIdx].pt for m in good])
pts2 = np.float32([kp2[m.trainIdx].pt for m in good])
H, inliers = cv.findHomography(pts1, pts2, cv.USAC_MAGSAC, 3.0)

4.8.2 失败、调参和验证

• 失败原因：纹理重复；关键点过少或集中在小区域；运动模糊；误用距离范数；动态物体主导；平面模型用于强视差场景。
• 调参顺序：先确认描述子类型与范数，再增加特征覆盖；随后调比率阈值；最后按图像噪声调 RANSAC 阈值和置信度。
• 验证方法：报告原始匹配数、筛后匹配数、内点数和内点率；画内点空间分布；计算对称传输误差或极线距离的中位数和 95 分位数。

4.9 相机标定、PnP 与双目

4.9.1 单目标定

针孔模型为：

[
s\begin{bmatrix}u\v\1\end{bmatrix}
=K[R|t]\begin{bmatrix}X\Y\Z\1\end{bmatrix},\quad
K=\begin{bmatrix}f_x&0&c_x\0&f_y&c_y\0&0&1\end{bmatrix}
]

findChessboardCorners 的 patternSize 是每行、每列的内角点数，不是方格数。cornerSubPix 输入灰度图和初始角点。calibrateCamera 输入每帧 N×3 物点与对应 N×2 像点，输出 RMS、内参、畸变、每帧外参。鱼眼模型应使用 cv.fisheye API，不能混用普通畸变系数语义。

1
2
3
4
5
6
7
8
9

ok, corners = cv.findChessboardCorners(gray, (9, 6))
if ok:
    term = (cv.TERM_CRITERIA_EPS + cv.TERM_CRITERIA_COUNT, 30, 1e-3)
    corners = cv.cornerSubPix(gray, corners, (11, 11), (-1, -1), term)
    image_points.append(corners)
    object_points.append(board_points.copy())
rms, K, dist, rvecs, tvecs = cv.calibrateCamera(
    object_points, image_points, gray.shape[::-1], None, None
)

失败原因包括姿态单一、标定板仅居中、覆盖深度不足、运动模糊、打印比例不准和运行分辨率变化。调参先改善采集覆盖，再剔除检测错误帧，最后谨慎固定高阶畸变参数。验证时必须用 projectPoints 计算逐帧误差，而不只看总体 RMS，并检查 fx/fy、主点及畸变曲线是否合理。

4.9.2 PnP 位姿

solvePnP 的物点和像点必须一一对应。通用情况可从 SOLVEPNP_ITERATIVE 开始；平面方形标记可考虑 SOLVEPNP_IPPE_SQUARE，其四个物点有规定顺序；存在离群点时使用 solvePnPRansac，再以内点调用 solvePnPRefineLM。

失败原因：单位不一致；点顺序错误；点近共线；平面解歧义；错误内参；把相机到物体变换与物体到相机变换混淆。调参先核对坐标系和单位，再选求解器，再调 RANSAC 重投影阈值，最后细化。验证应检查正深度、重投影误差以及时序位姿连续性。

4.9.3 双目标定与深度

校正后对应点应位于同一水平扫描线。若焦距为 f、基线为 B、视差为 d，则：

[
Z=\frac{fB}{d}
]

StereoSGBM_create 的 numDisparities 必须为 16 的倍数，blockSize 为正奇数；常用平滑罚项起点为 P1=8·C·b^2、P2=32·C·b^2。输出视差通常带 4 位小数定标，转浮点时除以 16。

失败原因：左右不同步、曝光差、垂直视差、弱纹理、重复纹理和遮挡。调参先验证校正，再定最小/最大视差范围，然后调窗口与 P1/P2，最后做左右一致性和 speckle 清理。验证用极线纵向误差、有效视差比例和已知距离平面的深度误差。

4.10 光流、背景建模与跟踪

4.10.1 光流

亮度恒常和小运动假设给出光流约束：

[
I_xu+I_yv+I_t=0
]

Lucas–Kanade 在局部窗口内联合求解，calcOpticalFlowPyrLK 输入前后帧及 N×1×2 float32 点，输出新点、status 和误差。winSize 控制局部窗口，maxLevel 控制金字塔层数。calcOpticalFlowFarneback 输出 H×W×2 float32 稠密流。

1
2
3
4
5
6
7
8

p0 = cv.goodFeaturesToTrack(prev_gray, 500, 0.01, 8)
p1, status, err = cv.calcOpticalFlowPyrLK(
    prev_gray, gray, p0, None,
    winSize=(21, 21), maxLevel=3,
    criteria=(cv.TERM_CRITERIA_EPS | cv.TERM_CRITERIA_COUNT, 30, 0.01)
)
good0 = p0[status.ravel() == 1]
good1 = p1[status.ravel() == 1]

失败原因：快速运动超出金字塔搜索；遮挡；无纹理区域；曝光突变；点漂移。调参先改善帧间隔和角点质量，再增大金字塔层级，随后调窗口，最后加前后向一致性并周期性重检测。验证可将点正向追踪后反向追踪，统计往返误差和有效点寿命。

4.10.2 背景建模

createBackgroundSubtractorMOG2(history=500, varThreshold=16, detectShadows=True) 适合较稳定相机；阴影通常标为 127，前景为 255，不能直接把所有非零值视为目标。learningRate=0 冻结模型，负值让算法自动选择，较大值适应更快但会吞掉慢速目标。

失败原因：相机抖动、周期背景、自动曝光、目标长时间静止。调参先固定相机和曝光，再设置学习率与历史长度，然后调判定阈值，最后清理阴影和小区域。验证使用前景 IoU、误警面积、目标进入/离开后的适应时间。

4.10.3 状态跟踪

Kalman Filter 只估计状态，不负责目标检测或多目标关联。线性模型为：

[
x_k=Ax_{k-1}+Bu_k+w_k,\qquad z_k=Hx_k+v_k
]

cv.KalmanFilter(dynamParams, measureParams) 的 transitionMatrix、measurementMatrix、过程噪声 Q、测量噪声 R 必须与状态定义一致。失败通常来自时间步长错误、噪声协方差不合理和关联错配。先验证检测，再验证关联门限，随后调 R，最后调 Q；以轨迹 RMSE、ID 切换、丢失恢复时间验证。

4.11 图像分割

4.11.1 连通域与 Watershed

connectedComponentsWithStats 接受 8 位单通道图，返回 int32 标签、包围框/面积统计和质心。connectivity=4 不连接对角像素，8 会连接。

Watershed 把梯度图看作地形，从 marker 指定的种子扩张。watershed(image, markers) 的图像是 8 位三通道，marker 是 int32 单通道；处理后分水岭边界标为 -1。未知区域必须为 0，已知前景实例使用不同正整数标签。

1
2
3
4
5
6
7
8
9

dist = cv.distanceTransform(mask, cv.DIST_L2, 5)
_, sure_fg = cv.threshold(dist, 0.45 * dist.max(), 255, 0)
sure_fg = sure_fg.astype(np.uint8)
sure_bg = cv.dilate(mask, np.ones((3, 3), np.uint8), iterations=3)
unknown = cv.subtract(sure_bg, sure_fg)
count, markers = cv.connectedComponents(sure_fg)
markers = markers + 1
markers[unknown == 255] = 0
markers = cv.watershed(image.copy(), markers.astype(np.int32))

4.11.2 GrabCut、Flood Fill 与聚类

grabCut 输入 BGR 图、uint8 掩膜、矩形、背景/前景模型和迭代数；掩膜值是 GC_BGD/FGD/PR_BGD/PR_FGD。矩形初始化要求目标大体位于框内，精细边界应再用掩膜初始化。floodFill 从种子按颜色差扩张，需谨慎选择 loDiff/upDiff。颜色聚类可把像素转为 float32 N×C 后调用 kmeans，但空间不连续且类别编号无语义。

• 失败原因：marker 粘连或缺失导致 Watershed 欠分/过分；GrabCut 框包含太多背景或目标触边；聚类只看颜色忽略空间。
• 调参顺序：先确认任务线索，再优化前景/背景种子；Watershed 调距离阈值，GrabCut 调初始化和迭代，最后做区域过滤。
• 验证方法：IoU、Dice、边界 F1、实例计数误差；将每个标签随机着色，检查标签泄漏和碎片。

4.12 图像拼接

cv.Stitcher.create(mode) 提供完整封装：PANORAMA 假设相机旋转为主，SCANS 更适合仿射扫描件。stitch(images) 返回状态码和结果，不应只捕获异常。状态包括成功、需要更多图像、单应估计失败和相机参数调整失败。

高级流水线位于 cv::detail：特征寻找、最佳匹配图、运动估计、Bundle Adjustment、球面/柱面 warper、曝光补偿、接缝寻找及 blender 可独立替换。多频段融合减少低频曝光缝，羽化融合开销较小但不能修复错位。

1
2
3
4

stitcher = cv.Stitcher.create(cv.Stitcher_PANORAMA)
status, panorama = stitcher.stitch(images)
if status != cv.Stitcher_OK:
    raise RuntimeError(f"拼接失败，状态码={status}")

• 失败原因：重叠不足；纹理单一；视差显著；滚动快门；移动物体；输入顺序或尺度跨度过大。
• 调参顺序：先检查相邻图重叠和匹配内点，再选 PANORAMA/SCANS；随后调匹配置信度与投影模型，最后才调曝光、接缝和融合。
• 验证方法：匹配图连通性、边缘重影宽度、接缝两侧亮度差、直线弯曲程度和有效画布比例；不要仅凭“能输出图”判定成功。

4.13 DNN 推理

4.13.1 输入、执行和输出

readNet/readNetFromONNX 返回 cv.dnn.Net。blobFromImage(image, scalefactor, size, mean, swapRB, crop, ddepth) 通常输出 NCHW 四维 blob。实际预处理由模型训练配置决定，OpenCV 不会自动推断 letterbox、均值、标准差或输出布局。

常见标准化为：

[
x’=(x-\mu)\cdot s
]

注意 blobFromImage 的顺序是先减 mean 再乘 scalefactor；swapRB=True 会交换红蓝通道。若模型要求逐通道标准差，通常需自行构造浮点输入。

1
2
3
4
5
6
7
8

net = cv.dnn.readNetFromONNX("model.onnx")
inp, scale, (pad_x, pad_y) = letterbox(image, (640, 640))
blob = cv.dnn.blobFromImage(
    inp, scalefactor=1.0 / 255.0, size=(640, 640),
    mean=(0, 0, 0), swapRB=True, crop=False
)
net.setInput(blob)
outputs = net.forward(net.getUnconnectedOutLayersNames())

setPreferableBackend 和 setPreferableTarget 只表达偏好；部署前应通过构建信息、运行日志和基准确认实际后端。动态形状、量化模型和自定义算子必须做兼容性测试。

4.13.2 后处理、失败与验证

检测后处理通常先按置信度筛选，再调用 NMSBoxes(bboxes, scores, score_threshold, nms_threshold)。IoU 为：

[
\operatorname{IoU}(A,B)=\frac{|A\cap B|}{|A\cup B|}
]

失败原因：BGR/RGB 错；拉伸与 letterbox 混用；输出维度按错误模型版本解释；置信度定义错误；坐标忘记减 padding；类别索引偏移；NMS 跨类别误抑制。

调参顺序：先用已知输入对齐训练框架的预处理和原始张量，再实现解码与坐标回映射，随后调置信度和 NMS，最后选择后端和批量。验证应比较参考框架逐层或最终输出、固定样本数值误差、mAP/IoU，以及预热后的端到端延迟和峰值内存。

4.14 模板、霍夫与 ArUco

4.14.1 模板匹配

matchTemplate(image, templ, method, mask) 输出尺寸为 (W-w+1, H-h+1) 的浮点响应图。TM_SQDIFF 系列越小越好，相关系数系列越大越好。归一化相关系数可理解为对均值和能量归一化后的相似度。

1
2
3
4

response = cv.matchTemplate(gray, templ, cv.TM_CCOEFF_NORMED)
_, score, _, location = cv.minMaxLoc(response)
if score >= 0.85:
    x, y = location

失败原因是尺度、旋转、透视和光照差异，以及低纹理模板。先固定尺度搜索，再设置分数阈值和峰值抑制，最后才扩展图像金字塔或角度搜索。用正负样本分数分布、定位误差和重复检测率验证。

4.14.2 霍夫直线与圆

直线法式为：

[
\rho=x\cos\theta+y\sin\theta
]

HoughLinesP(image, rho, theta, threshold, minLineLength, maxLineGap) 输入 8 位二值边缘图，输出线段端点。HoughCircles 常用 HOUGH_GRADIENT；dp 是累加器与图像分辨率反比，minDist 抑制相邻圆，param1 通常是内部 Canny 高阈值，param2 是圆心累加阈值。

失败原因：边缘太碎、纹理伪线、maxLineGap 连接无关边、半径范围过宽。调参先稳定边缘，再限定 ROI 和角度/半径范围，随后调投票阈值，最后调线长或圆间距。验证用端点到标注线距离、角度误差、圆心误差和半径误差。

4.14.3 ArUco 与 ChArUco

OpenCV 4.13.0 使用 cv.aruco.ArucoDetector(dictionary, detectorParams) 检测标记，输出每个标记的四角、ID 和拒绝候选。字典必须与打印标记一致。姿态估计可将已知标记或 Board 的三维角点与检测二维角点交给 solvePnP；单个方形标记适合 IPPE 方形模型。

1
2
3
4
5
6

dictionary = cv.aruco.getPredefinedDictionary(cv.aruco.DICT_6X6_250)
params = cv.aruco.DetectorParameters()
detector = cv.aruco.ArucoDetector(dictionary, params)
corners, ids, rejected = detector.detectMarkers(image)
if ids is not None:
    cv.aruco.drawDetectedMarkers(image, corners, ids)

失败原因：字典错误；打印边框不足；标记像素过少；反光、模糊或遮挡；角点顺序与三维点不一致；未考虑镜头畸变。调参先保证打印质量和像素尺寸，再选角点细化方式，随后调整自适应阈值窗口和候选周长范围，最后估计位姿。验证 marker 检出率、ID 混淆、角点重投影误差、姿态抖动和不同距离下的稳定性。

4.15 验收与源码核验

验收至少覆盖：输入类型契约；中间结果留存；独立验证集阈值；重投影、极线或逆变换误差；空图与无候选分支；噪声、模糊、曝光、尺度、旋转、遮挡扰动；视频延迟和丢帧；DNN 与参考框架数值对齐。

本章 API 与主要参数已按仓库内 opencv-4.13.0/modules/ 下的 imgproc、features2d、calib3d、video、stitching、dnn、objdetect 公开头文件核验，其中 ArUco 类声明位于 objdetect/include/opencv2/objdetect/aruco_detector.hpp。版本升级时仍须复查函数重载、枚举、默认参数、模型导入兼容性和 Python 绑定。

源码/API 核验不能替代任务数据上的定量验证；只有指标、失败样本和中间产物都可复现，流水线才算完成。

OpenCV 4.13.0 HAL 与性能优化

本文面向需要解释、选择或扩展 OpenCV 加速路径的开发者。内容依据 OpenCV 4.13.0 源码树中的 HAL、CPU 分发、并行、OpenCL 和 DNN 实现核验。文中的路径均相对于 OpenCV 源码根目录。

1. 先建立正确的性能模型

一次公开 API 调用可能依次经过：

1
2
3
4
5
6
7

公开 API
  -> 参数检查与输出分配
  -> OpenCL / 专用后端尝试
  -> HAL 替换原语
  -> CPU dispatch 或通用实现
  -> parallel_for_ 分块
  -> SIMD、标量与尾部处理

这不是所有函数都严格遵循的固定层级。不同模块会按算法、数据类型、尺寸和构建能力选择其中一部分。因此，“启用了某个库”不等于“每次调用都进入该库”。性能判断必须同时核对构建结果、运行时选择和实际输入。
HAL、SIMD、线程和异构设备解决的问题不同：

• HAL 替换一组约定好的底层原语；
• CPU dispatch 在同一二进制中选择不同指令集版本；
• 通用 intrinsics 帮助源码以统一方式表达 SIMD；
• parallel_for_ 把独立区间分给多个 CPU 线程；
• T-API 通过 UMat 尝试 OpenCL；
• DNN 后端把网络或网络片段交给专用执行引擎。

2. HAL 的两层含义

OpenCV 源码中的 HAL 至少有两层含义，阅读时不能混为一谈。

2.1 模块内的硬件抽象接口

主要入口包括：

1
2
3
4
5
6

modules/core/include/opencv2/core/hal/interface.h
modules/core/include/opencv2/core/hal/hal.hpp
modules/core/include/opencv2/core/hal/intrin.hpp
modules/core/include/opencv2/core/hal/intrin_*.hpp
modules/imgproc/include/opencv2/imgproc/hal/hal.hpp
modules/features2d/include/opencv2/features2d/hal/

interface.h 定义低层 C 风格接口、类型和返回码。接口返回值的三个基本约定是：

• CV_HAL_ERROR_OK：实现已完成操作；
• CV_HAL_ERROR_NOT_IMPLEMENTED：该输入或操作不支持，应由上层回退；
• CV_HAL_ERROR_UNKNOWN：实现发生无法恢复的错误。
  各模块的 src/hal_replacement.hpp 提供默认替换入口。自定义头通过宏重新绑定 cv_hal_* 名称。例如实现头可先 #undef cv_hal_xxx，再将它定义为供应商函数。这是一种编译期替换机制，不是运行时插件虚函数表。
  intrin.hpp 及架构专用头属于另一类抽象。它们把向量寄存器、加载、存储、算术和归约包装成统一 API。算法可由同一份模板生成 baseline 或多个 dispatch 版本。intrinsics 不是外置 HAL，但两者可以在同一调用链中同时存在。

2.2 源码根目录中的 HAL 子工程

源码根目录 hal/ 保存树内可选实现：

1
2
3
4
5
6
7

hal/carotene/
hal/fastcv/
hal/kleidicv/
hal/ndsrvp/
hal/riscv-rvv/
hal/ipp/
hal/openvx/

这些目录各自构建静态辅助库或接入外部项目。根 CMakeLists.txt 决定其顺序、头文件注入和链接库收集。目录存在并不表示当前平台一定构建或使用它。

3. HAL 注册链与优先级

3.1 CMake 阶段的完整链路

根构建脚本中的关键流程是：

1. 平台与依赖探测生成 HAVE_*；
2. 用户选项和探测结果修改 OpenCV_HAL 列表；
3. foreach(hal ${OpenCV_HAL}) 按列表顺序处理实现；
4. 树内实现通过 add_subdirectory(hal/...) 构建；
5. 未识别名称通过 find_package(<name> NO_MODULE QUIET) 查找；
6. ocv_hal_register() 收集库、头和 include 目录；
7. custom_hal.hpp.in 被配置成构建目录中的 custom_hal.hpp；
8. 收集到的库进入 OpenCV 模块链接关系。
   ocv_hal_register() 实际做三件事：

• 将实现库追加到 OPENCV_HAL_LINKER_LIBS；
• 将实现头变成生成头中的 #include；
• 将实现 include 目录加入构建。
  根脚本默认把 OpenCV_HAL 设为字符串 OpenCV_HAL。这个名称会走 find_package(OpenCV_HAL NO_MODULE QUIET)。因此 OpenCV_HAL_DIR 可指向一个含 OpenCV_HALConfig.cmake 的外置实现构建目录。

3.2 顺序为什么重要

IPP、OpenVX、FastCV、KleidiCV、Carotene、NDSRVP 和 RVV 会按条件前插到列表。每个注册头都可能重定义同一个 cv_hal_* 宏。生成的 custom_hal.hpp 按注册顺序包含这些头。后包含且确实重定义某接口的头，可能覆盖先前绑定。没有覆盖的接口继续由前一实现或默认实现提供。
不要仅根据“某库排在列表中”推断最终处理者。应检查生成的 custom_hal.hpp、具体实现头和目标链接命令。

3.3 从公开 API 到回退

典型路径可以概括为：

1
2
3
4
5

cv::算法
  -> cv_hal_xxx(...)
     -> 返回 OK：结束
     -> 返回 NOT_IMPLEMENTED：执行 OpenCV 内部实现
     -> 返回 UNKNOWN：按调用点的错误策略处理

是否允许回退由具体调用点决定。实现必须遵守接口的步长、尺寸、原地操作、边界和数值约定。“不支持此组合”应返回 NOT_IMPLEMENTED，不能悄悄产生近似错误结果。

4. 编写和接入自定义 HAL

源码自带两个教学实现：

1
2

samples/hal/c_hal/
samples/hal/slow_hal/

c_hal 的函数返回错误，用于验证错误处理和回退。slow_hal 替换按位运算，用可观察的慢实现证明绑定已生效。两者都会生成 OpenCV_HALConfig.cmake。

4.1 最小接入流程

先单独构建自定义 HAL：

1
2
3
4

cmake -S /path/to/opencv/samples/hal/slow_hal \
  -B /path/to/build-hal \
  -D CMAKE_BUILD_TYPE=Release
cmake --build /path/to/build-hal -j

再配置 OpenCV：

1
2
3
4
5

cmake -S /path/to/opencv \
  -B /path/to/build-opencv \
  -D CMAKE_BUILD_TYPE=Release \
  -D OpenCV_HAL_DIR=/path/to/build-hal
cmake --build /path/to/build-opencv -j

外置包至少需要导出：

1
2
3
4
5

set(OpenCV_HAL_FOUND TRUE)
set(OpenCV_HAL_VERSION 0.1.0)
set(OpenCV_HAL_LIBRARIES /path/to/libcustom_hal.a)
set(OpenCV_HAL_HEADERS custom_hal_impl.hpp)
set(OpenCV_HAL_INCLUDE_DIRS /path/to/include)

生产实现应使用可重定位的导出目标或安装路径。上面的绝对占位仅说明变量语义。

4.2 实现检查清单

• 函数签名必须与当前 4.13.0 接口完全一致；
• 只重定义真正实现的接口；
• 对不支持的深度、通道或边界模式返回 NOT_IMPLEMENTED；
• 正确处理非连续矩阵和字节步长；
• 明确是否支持源、目的区域重叠；
• 避免越过每行有效宽度；
• 保证多线程并发调用安全；
• 不把进程级可变状态放进无保护全局变量；
• 静态库用于共享 OpenCV 时通常需要位置无关代码；
• 用正确性测试覆盖空尺寸、奇数尺寸和尾部元素；
• 用性能测试证明收益大于分派与转换成本；
• 将支持矩阵、版本和供应商运行库要求写入发布说明。

4.3 如何确认自定义 HAL 生效

检查以下证据链：

1. CMake 配置日志找到了自定义包；
2. 生成的 custom_hal.hpp 包含自定义头；
3. 目标链接命令含自定义 HAL 库；
4. 针对被替换接口的测试通过；
5. 通过日志、计数器或调试器确认函数被调用；
6. 关闭自定义 HAL 后基准结果按预期变化。
   不要只靠符号出现在静态库中判断生效。链接器可能丢弃未引用对象，宏绑定也可能已被后续头覆盖。

5. 树内 HAL 实现

5.1 Carotene

选项是 WITH_CAROTENE。根 CMake 仅在 ARM/AArch64 的适用平台显示该选项。真正注册前还要求 CPU_BASELINE_FINAL 包含 NEON。接线头是 hal/carotene/hal/tegra_hal.hpp。
Carotene 覆盖多种 core 与 imgproc 原语。其对象库会按 WITH_NEON 添加定义，并包含针对内联增长的编译参数。适合已有 NEON baseline 的 ARM 构建。它不是所有 ARM 算法的统一开关，也不等价于 CPU dispatch 中的 NEON。

5.2 Qualcomm FastCV

选项是 WITH_FASTCV，默认关闭。可见平台为 ARM/AArch64 上的 Android 或适用 Unix。依赖探测成功后形成 HAVE_FASTCV。实现位于 hal/fastcv/src/，注册头覆盖 core 和 imgproc 的部分接口。
hal/fastcv/CMakeLists.txt 将外部 FASTCV_LIBRARY 链接到 fastcv_hal。选项打开但库或头未找到时，HAL 不可用。发布时必须同时考虑 FastCV 二进制、许可、目标 ABI 和运行时装载路径。

5.3 Arm KleidiCV

选项是 WITH_KLEIDICV。源码将其限制到 AArch64 的 Android 或 Unix 环境。依赖可用时，OpenCV包含 KleidiCV 自带的 adapters/opencv/CMakeLists.txt。适配器负责生成 kleidicv_hal 和对应注册信息。
构建中还提供 KLEIDICV_ENABLE_SME2，默认关闭。源码注释指出它与部分 Android NDK Clang 版本不兼容。启用 SME2 前要同时验证编译器、运行设备和部署基线。

5.4 Andes NDSRVP

选项是 WITH_NDSRVP，仅在 RISC-V 平台可见。注册还要求 C 与 C++ flags 都包含 -mext-dsp。同时要求 baseline 不含 RVV。这体现了 NDSRVP 与 RVV HAL 的选择关系。
实现覆盖部分 core、imgproc 和 features2d 接口。构建生成 ndsrvp_hal 静态库。应使用 Andes 对应工具链验证编译选项，不能在普通 RISC-V 工具链上只强开选项。

5.5 RISC-V RVV HAL

选项是 WITH_HAL_RVV，仅在 RISC-V 平台可见。注册要求 CPU_BASELINE_FINAL 含 RVV。构建目标为 rvv_hal。入口头 rvv_hal.hpp 汇集 core、imgproc 和 features2d 替换。
源码覆盖矩阵分解、数学、颜色转换、滤波、几何变换、直方图和 FAST 等多类原语。具体接口仍可能因数据类型或参数而回退。RVV HAL 与通用 intrinsics 中的 RVV dispatch 是不同机制。

5.6 Intel IPP

选项是 WITH_IPP。根 CMake 在 x86/x86_64 且适用平台提供该选项，并以 HAVE_IPP 验证探测结果。注册目标 ipphal 覆盖 mean、min/max、norm、极坐标转换、变换、warp 和 sum 等接口。
OpenCV 其他位置仍保留 IPP 集成。hal/ipp/CMakeLists.txt 的注释明确指出 HAL 尚未成为唯一 IPP 来源。因此分析 IPP 命中时要同时看 HAL 和模块内部 IPP 路径。WITH_IPP_CALLS_ENFORCED 更适合验证和开发，不应在不了解回退影响时用于通用发布。

5.7 OpenVX

选项是 WITH_OPENVX，默认关闭。cmake/FindOpenVX.cmake 探测实现并形成 HAVE_OPENVX。只有探测成功才进入 hal/openvx/hal/。源码还包含 ivx.hpp 等 C++ 包装。
OpenVX HAL 只覆盖它实现的原语。性能受图构建、数据导入导出、供应商实现和目标设备影响。不能把 WITH_OPENVX=ON 理解为整个 OpenCV 流水线自动转换为 OpenVX 图。

5.8 选择摘要

6. CPU baseline 与 runtime dispatch

6.1 两类构建结果

CPU_BASELINE 指定库运行所需的最低优化能力。baseline 指令可以出现在通用代码路径中。把 AVX2 设为 baseline 意味着不支持 AVX2 的机器不应运行该二进制。
CPU_DISPATCH 指定额外编译的优化版本。运行时检测 CPU 后选择可用的最高合适版本。不满足这些额外能力的机器仍可走 baseline。
高级约束还有：

• CPU_BASELINE_REQUIRE：必须成功启用的 baseline；
• CPU_BASELINE_DISABLE：禁止的 baseline；
• CPU_DISPATCH_REQUIRE：必须成功生成的 dispatch。
  最终结果记录在：
• CPU_BASELINE_FINAL；
• CPU_DISPATCH_FINAL；
• CMake Summary 的 CPU/HW features 段。

6.2 源码组织

热点实现常使用：

1
2
3

name.dispatch.cpp
name.simd.hpp
name.avx2.cpp

CV_CPU_DISPATCH 宏按运行时能力调用命名空间中的版本。dispatch 链最终落到 BASELINE。不是每个算法、深度和尺寸都有每种指令集实现。

6.3 构建与运行时控制

构建时 CV_DISABLE_OPTIMIZATION=ON 会关闭多类优化，适合建立调试对照。运行时 cv::setUseOptimized(false) 关闭受该全局标志控制的优化分支。它必须在没有其他 OpenCV 调用并发执行的顶层安全位置调用。
环境变量 OPENCV_CPU_DISABLE 可禁用以逗号或分号分隔的 dispatch 特性。它适合定位某个指令集实现，不适合作为长期性能配置的替代品。

1

OPENCV_CPU_DISABLE=AVX2,AVX512-SKX /path/to/app

cv::getCPUFeaturesLine() 的标记含义为：

• 无标记：baseline；
• 前缀 *：dispatch 中编译的特性；
• 后缀 ?：已编译但当前硬件不可用。

7. parallel_for_ 与线程后端

cv::parallel_for_ 接受一个 Range 和并行循环体。它把区间划分为多个 stripe，再交给并行后端。构建可能使用 TBB、OpenMP、平台后端、插件或内置实现。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

class Body final : public cv::ParallelLoopBody {
public:
    Body(const cv::Mat& src, cv::Mat& dst) : src_(src), dst_(dst) {}

    void operator()(const cv::Range& range) const override {
        for (int y = range.start; y < range.end; ++y)
            src_.row(y).copyTo(dst_.row(y));
    }

private:
    const cv::Mat& src_;
    cv::Mat& dst_;
};

cv::parallel_for_(cv::Range(0, src.rows), Body(src, dst));

循环体应满足：

• 每个 stripe 写入互不重叠的输出；
• 只读共享输入；
• 共享统计量使用归约或同步；
• 不依赖 stripe 的执行顺序；
• 粒度足够大，能覆盖调度开销；
• 异常和对象生命周期符合调用线程语义。
  常用控制 API：

1
2
3

cv::setNumThreads(1);
int configured = cv::getNumThreads();
int cpus = cv::getNumberOfCPUs();

setNumThreads(1) 可用于串行对照。传负数恢复系统默认。该函数不是线程安全的，不能在并行区或并发调用中修改。getNumThreads() 的精确语义取决于 TBB、OpenMP 等后端。
上层线程池与 OpenCV 内部线程并行叠加会过度订阅。批量处理时常见策略是“外层并行、库内单线程”或反之。应分别测量，不能凭核心数直接决定。

8. OpenCL Transparent API

T-API 使用 cv::UMat 表达可由 OpenCL 管理的数据。支持 OpenCL 的函数会尝试设备实现，不支持时可走 CPU 路径。

1
2
3
4
5

cv::UMat src, gray, blurred;
cv::imread("input.jpg", cv::IMREAD_COLOR).copyTo(src);
cv::cvtColor(src, gray, cv::COLOR_BGR2GRAY);
cv::GaussianBlur(gray, blurred, cv::Size(5, 5), 1.2);
cv::ocl::finish();

诊断 API：

1
2
3
4
5

std::cout << cv::ocl::haveOpenCL() << '\n';
std::cout << cv::ocl::useOpenCL() << '\n';
cv::ocl::setUseOpenCL(true);
const cv::ocl::Device& dev = cv::ocl::Device::getDefault();
std::cout << dev.name() << '\n';

环境变量 OPENCV_OPENCL_DEVICE 可选择设备或设为 disabled。设备选择应在 OpenCL 上下文首次初始化前完成。
性能陷阱包括：

• 小算子启动成本高于计算收益；
• Mat 与 UMat 频繁互转造成上传和下载；
• getMat() 可能触发同步；
• 只计异步提交而没有 cv::ocl::finish() 会低估时间；
• 某一步回退到 CPU 可能打断整条设备流水线；
• 首次编译 kernel 与缓存建立不代表稳定态。
  最佳实践是让尽可能长的支持链保持 UMat。端到端基准必须包含必要的输入传输、最终同步和输出取回。

9. DNN 后端与目标

OpenCV 4.13.0 的公开枚举包含：

• 后端：Default、Halide、OpenVINO、OpenCV、VkCom、CUDA、WebNN、TIM-VX、CANN；
• 目标：CPU、OpenCL、OpenCL FP16、Myriad、Vulkan、FPGA、CUDA、CUDA FP16、HDDL、NPU、ARM CPU FP16。
  枚举存在不代表当前构建可用。应查询实际组合：

1
2
3
4

for (const auto& item : cv::dnn::getAvailableBackends())
    std::cout << item.first << " -> " << item.second << '\n';

auto targets = cv::dnn::getAvailableTargets(cv::dnn::DNN_BACKEND_OPENCV);

显式选择示例：

1
2
3

cv::dnn::Net net = cv::dnn::readNet("/path/to/model.onnx");
net.setPreferableBackend(cv::dnn::DNN_BACKEND_OPENCV);
net.setPreferableTarget(cv::dnn::DNN_TARGET_CPU);

CUDA 后端通常要求构建探测到 CUDA，并按能力使用 cuDNN、cuBLAS 等。OpenVINO、TIM-VX、CANN 等也各有构建和运行时依赖。不支持的层可能回退、重新分区或直接报错，取决于后端。
DNN 性能测量应分离：

• 模型读取与解析；
• 首次网络初始化；
• 首次推理和 kernel 编译；
• 稳定态推理；
• blob 预处理；
• 输出复制与后处理。
  Net::getPerfProfile() 可返回层级时间，但支持范围与后端有关。最终仍要以应用端到端延迟和吞吐为准。

10. 内存、数据布局与缓存

许多“计算优化”最终受内存带宽限制。优先检查：

• 是否在循环中反复创建同尺寸输出；
• 是否存在无意的 clone()、copyTo() 或类型转换；
• ROI 是否导致非连续步长；
• 通道转换能否前移、合并或取消；
• 数据类型是否超出精度需求；
• 大图处理是否有更好的 tile；
• 多线程是否争用同一缓存行；
• NUMA 机器上的分配与执行是否跨节点。
  cv::Mat 是引用计数的浅拷贝头。赋值通常不复制像素，clone() 才执行深拷贝。ROI 可能不连续，底层代码必须尊重 step。可用 isContinuous() 判断能否把多行合并为一个线性区间。
  OpenCV 提供 fastMalloc() 与 fastFree()。需要特殊分配策略时可研究 MatAllocator，但这是高级扩展点。自定义 allocator 必须处理生命周期、对齐、map/unmap 和异常路径。一般应用先复用 Mat::create() 管理的缓冲区即可。
  减少峰值内存的常用方法：
• 原地操作仅在 API 明确支持时使用；
• 将中间缓冲区放到循环外复用；
• 流式读取视频，不缓存全部帧；
• 控制 DNN batch 与输入分辨率；
• 对超大图采用分块并处理 halo；
• 避免同时保留 Mat、UMat 和设备副本。

11. 可复现 benchmark 方法

11.1 基准骨架

1
2
3
4
5
6
7
8
9
10
11
12
13
14

cv::TickMeter tm;
cv::Mat dst;

for (int i = 0; i < 10; ++i)
    cv::GaussianBlur(src, dst, cv::Size(5, 5), 1.2);

std::vector<double> samples;
for (int i = 0; i < 100; ++i) {
    tm.reset();
    tm.start();
    cv::GaussianBlur(src, dst, cv::Size(5, 5), 1.2);
    tm.stop();
    samples.push_back(tm.getTimeMilli());
}

GPU 或 OpenCL 路径要在计时区间末尾同步。异步设备后端也要使用其对应同步机制。不要使用 getCPUTickCount() 直接换算耗时；源码文档建议一般计时使用 getTickCount()。

11.2 必须固定和记录

• OpenCV 完整版本与源码修订；
• Release、Debug 或 RelWithDebInfo；
• 编译器、标准库和关键编译参数；
• baseline、dispatch 与 HAL 列表；
• 第三方加速库和驱动版本；
• CPU 型号、频率策略、NUMA 与亲和性；
• GPU/NPU 型号、功耗模式与温度；
• 输入尺寸、类型、通道、步长和内容分布；
• 线程数、并行后端和上层并发；
• 预热次数、样本数和同步位置；
• 中位数、分位数与离群值规则；
• 优化前后的输出误差阈值；
• 是否包含 I/O、传输、预处理和后处理。

11.3 OpenCV 自带 perf

启用 BUILD_PERF_TESTS=ON 后可构建 opencv_perf_<module>。使用 GoogleTest 风格过滤器缩小测试范围：

1
2

/path/to/build/bin/opencv_perf_core \
  --gtest_filter='*bitwise_and*'

先运行 --help 查看当前二进制支持的 perf 参数。不同构建和版本的参数集合可能变化。不要把单个微基准直接外推为完整业务收益。

12. 诊断 API 与环境变量

最小诊断程序：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

#include <opencv2/core.hpp>
#include <opencv2/core/ocl.hpp>
#include <opencv2/core/utils/logger.hpp>
#include <iostream>

int main() {
    cv::utils::logging::setLogLevel(
        cv::utils::logging::LOG_LEVEL_INFO);
    std::cout << cv::getVersionString() << '\n';
    std::cout << cv::getBuildInformation() << '\n';
    std::cout << cv::getCPUFeaturesLine() << '\n';
    std::cout << "optimized=" << cv::useOptimized() << '\n';
    std::cout << "threads=" << cv::getNumThreads() << '\n';
    std::cout << "cpus=" << cv::getNumberOfCPUs() << '\n';
    std::cout << "opencl=" << cv::ocl::haveOpenCL() << '\n';
}

常用环境变量：

1
2
3
4

OPENCV_LOG_LEVEL=DEBUG /path/to/app
OPENCV_CPU_DISABLE=AVX2 /path/to/app
OPENCV_FOR_THREADS_NUM=1 /path/to/app
OPENCV_OPENCL_DEVICE=disabled /path/to/app

诊断顺序建议：

1. 打印 getBuildInformation()；
2. 核对目标模块和第三方依赖确实为 YES；
3. 打印 CPU features 和线程数；
4. 开启日志观察后端选择；
5. 逐个关闭线程、dispatch、OpenCL 或专用后端；
6. 保持相同输入比较结果和时间；
7. 用调试器或 profiler 获取最终证据。

13. 平台决策树

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

先确认热点是否在 OpenCV 内
  |
  +-- 否 -> 优化 I/O、业务逻辑或数据搬运
  |
  +-- 是
      |
      +-- x86/x86_64
      |   -> Release + 合理 baseline/dispatch
      |   -> 检查 IPP、线程和内存带宽
      |
      +-- ARM/AArch64
      |   -> 检查 NEON baseline/dispatch
      |   -> 评估 Carotene / KleidiCV
      |   -> Qualcomm 设备再评估 FastCV
      |
      +-- RISC-V
      |   -> RVV baseline 可用：评估 RVV HAL
      |   -> Andes DSP 工具链：评估 NDSRVP
      |
      +-- 有 OpenCL
      |   -> 流水线可长期保留 UMat：测 T-API
      |   -> 频繁传输或小算子：优先 CPU
      |
      +-- DNN
          -> 查询可用 backend/target
          -> 按模型覆盖率、精度、延迟选择

14. 优化实施顺序

1. 建立正确性基线和误差标准；
2. 用 profiler 找到真实热点；
3. 先减少输入量、重复计算和数据搬运；
4. 确保使用 Release 构建；
5. 核验已有 SIMD、HAL、IPP 和线程路径；
6. 调整线程层级和任务粒度；
7. 评估保持设备驻留的 OpenCL 或 DNN 后端；
8. 仅对稳定且高占比的底层原语开发自定义 HAL；
9. 用同一套正确性与性能测试验收；
10. 在目标设备和热稳态条件下重新测量。
    最终选择应以目标平台的可重复端到端数据为依据。任何加速路径都必须保留可诊断的回退方案，并验证回退结果正确。

OpenCV 4.13.0 配置、构建与使用指南

本文给出从 Linux 源码构建到 C++/Python 使用、测试、调试和部署的完整流程。内容依据 OpenCV 4.13.0 的根 CMakeLists.txt、模块配置和公开头文件核验。所有命令使用 /path/to 占位，不依赖本文之外的说明。

1. 构建前的版本与目录约定

建议准备三个彼此分离的目录：

1
2
3

/path/to/opencv-4.13.0/       # 只读源码
/path/to/build-opencv/        # CMake 缓存和编译产物
/path/to/install-opencv/      # 安装结果

源码外构建便于：

• 同时维护 Debug、Release、静态和交叉构建；删除构建目录后干净重配；
• 避免生成文件污染源码；明确部署内容来自哪个安装前缀。
  记录源码标签、提交、编译器和 CMake 版本。若使用 opencv_contrib，主仓库与 contrib 应来自相同版本标签。不要把不同小版本的头文件、库和 Python 扩展混在一起。

2. Linux 构建环境

2.1 基础工具

最低实用工具集包括：

• 支持 C++11 及项目要求的 GCC 或 Clang；CMake；
• Ninja 或 Make；pkg-config；
• Python 3 和开发文件；Git、下载工具与证书包；
• 目标功能对应的开发包。
  Debian/Ubuntu 类系统的常见准备命令：

1
2

sudo apt-get update
sudo apt-get install -y build-essential cmake ninja-build pkg-config python3 python3-dev python3-numpy libjpeg-dev libpng-dev libtiff-dev libavcodec-dev libavformat-dev libavutil-dev libswscale-dev libgtk-3-dev libtbb-dev

这只是常见组合，不是强制清单。服务器可省略 GTK。不用视频时可省略 FFmpeg。发行版包名和版本可能不同，应以 CMake Summary 的探测结果为准。

2.2 首次 Release 构建

1
2
3
4

cmake -S /path/to/opencv-4.13.0 -B /path/to/build-opencv -G Ninja -D CMAKE_BUILD_TYPE=Release -D CMAKE_INSTALL_PREFIX=/path/to/install-opencv

cmake --build /path/to/build-opencv -j
cmake --install /path/to/build-opencv

单配置生成器使用 CMAKE_BUILD_TYPE。Visual Studio、Xcode 等多配置生成器通常在构建和安装时用 --config Release。不要假设环境变量中的编译器会覆盖已有 CMake 缓存。切换编译器、架构或静态/动态策略时应使用新的构建目录。

2.3 配置结果验收

配置末尾的 Summary 至少检查：

• OpenCV version；C/C++ compiler；
• CPU/HW baseline 与 dispatched code；To be built / Disabled / Unavailable modules；
• GUI 与 Video I/O；Media I/O；
• Parallel framework；OpenCL、IPP、Eigen 等；
• Python 3 interpreter、libraries、numpy 和 install path；Install to。
  WITH_X=ON 表示请求能力。HAVE_X 或 Summary 中的 YES 才表示探测成功。某个模块未进入 “To be built” 时，安装后不会凭空可用。

3. CMake 选项语义

3.1 模块选择

3.2 第三方能力

3.3 CPU 与构建质量

3.4 Python 相关

常用变量包括：

1
2
3
4
5
6

BUILD_opencv_python3
PYTHON3_EXECUTABLE
PYTHON3_INCLUDE_DIR
PYTHON3_LIBRARY
PYTHON3_NUMPY_INCLUDE_DIRS
PYTHON3_PACKAGES_PATH

优先指定目标虚拟环境中的 PYTHON3_EXECUTABLE。其余变量只有在自动探测错误时再显式设置。配置 Summary 必须显示预期解释器、NumPy 和安装路径。

3.5 缓存与重配置

查看缓存：

1
2

cmake -L -N /path/to/build-opencv
cmake -LAH -N /path/to/build-opencv

更改单个普通选项可重新运行 cmake -S ... -B ...。更改编译器、sysroot、生成器、目标架构或主要依赖版本时新建构建目录。不要手工编辑 CMakeCache.txt 作为常规配置方式。

4. 常见构建配方

4.1 最小图像处理

1
2
3

cmake -S /path/to/opencv-4.13.0 -B /path/to/build-min -G Ninja -D CMAKE_BUILD_TYPE=Release -D CMAKE_INSTALL_PREFIX=/path/to/install-min -D BUILD_LIST=core,imgproc,imgcodecs -D BUILD_TESTS=OFF -D BUILD_PERF_TESTS=OFF -D BUILD_EXAMPLES=OFF -D WITH_FFMPEG=OFF -D WITH_GSTREAMER=OFF -D WITH_GTK=OFF
cmake --build /path/to/build-min -j
cmake --install /path/to/build-min

此配方适合无 GUI 的离线图像处理。PNG/JPEG 等能力仍取决于 Media I/O 探测。

4.2 完整桌面构建

1
2

cmake -S /path/to/opencv-4.13.0 -B /path/to/build-full -G Ninja -D CMAKE_BUILD_TYPE=Release -D CMAKE_INSTALL_PREFIX=/path/to/install-full -D WITH_GTK=ON -D WITH_FFMPEG=ON -D WITH_GSTREAMER=ON -D WITH_TBB=ON -D WITH_OPENCL=ON -D BUILD_EXAMPLES=ON -D BUILD_TESTS=ON -D BUILD_PERF_TESTS=ON
cmake --build /path/to/build-full -j

“完整”不是开启所有实验后端。只启用目标机器安装、测试和部署得了的能力。

4.3 contrib 构建

1
2
3

cmake -S /path/to/opencv-4.13.0 -B /path/to/build-contrib -G Ninja -D CMAKE_BUILD_TYPE=Release -D CMAKE_INSTALL_PREFIX=/path/to/install-contrib -D OPENCV_EXTRA_MODULES_PATH=/path/to/opencv_contrib-4.13.0/modules
cmake --build /path/to/build-contrib -j
cmake --install /path/to/build-contrib

变量应指向 modules 目录，不是 contrib 仓库根目录。若只需少数模块，可同时使用：

1

-D BUILD_LIST=core,imgproc,imgcodecs,features2d,xfeatures2d

启用 OPENCV_ENABLE_NONFREE=ON 前先审查算法和部署地区的许可要求。

4.4 静态构建

1
2
3

cmake -S /path/to/opencv-4.13.0 -B /path/to/build-static -G Ninja -D CMAKE_BUILD_TYPE=Release -D CMAKE_INSTALL_PREFIX=/path/to/install-static -D BUILD_SHARED_LIBS=OFF -D BUILD_LIST=core,imgproc,imgcodecs -D BUILD_TESTS=OFF -D BUILD_PERF_TESTS=OFF
cmake --build /path/to/build-static -j
cmake --install /path/to/build-static

静态 OpenCV 不等于最终应用完全静态。编解码器、线程库、系统库和 C++ 运行库仍可能需要显式链接。优先使用安装导出的 CMake 配置传播依赖，不要手写一串 .a。

4.5 Debug 和 RelWithDebInfo

1
2