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() 声明。

依赖可分为：

类型	典型写法	缺失时的结果
必需 OpenCV 模块	位置参数或 REQUIRED 后的模块	当前模块通常不能正常构建
可选 OpenCV 模块	OPTIONAL 后的模块	当前模块仍可构建，但部分 API/实现关闭
私有外部链接	PRIVATE、LINK_PRIVATE 等	影响实现，不传播为公共接口要求
包装目标	WRAP python java ...	决定绑定生成意图，不是算法依赖
条件功能	if(HAVE_*)、if(WITH_*)	仅满足配置条件时编译

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

2.3 核验过的主干依赖

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

模块	必需 OpenCV 依赖	可选 OpenCV 依赖	说明
core	无其他基础模块	cudev	全库底座；声明多语言包装
imgproc	core	无	经典图像处理主干
imgcodecs	imgproc	格式能力由外部库决定	依赖会传递到 core
videoio	imgproc、imgcodecs	媒体后端由平台/外部库决定	支持内建和插件实现
highgui	imgproc	imgcodecs、videoio	Android 与其他平台包装声明略有差异
features2d	imgproc	flann	调试配置还可引入 highgui
calib3d	imgproc、features2d、flann	LAPACK 是可探测的外部增强	标定和多视图几何
video	imgproc	calib3d、dnn	部分跟踪器依赖 DNN
objdetect	core、imgproc、calib3d	dnn	DNN 缺失时相关能力条件编译
dnn	core、imgproc	多种计算后端	DNN CUDA 还要求 CUDA、cuBLAS、cuDNN
stitching	imgproc、features2d、calib3d、flann	CUDA 模块和额外特征模块	高级组合模块
gapi	imgproc，以及内部图基础 ade	video、calib3d 和推理/流式后端	找不到 ade 时模块会禁用
world	core 起始并聚合选中模块	内容取决于整体构建	不是独立算法层

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

2.4 外部依赖：必需与可选

构建系统的基础要求

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

常见可选依赖

能力域	代表依赖	缺失后的典型影响
JPEG	libjpeg-turbo 或 JPEG 库	JPEG 读写不可用
PNG	libpng/libspng 与 zlib	PNG 读写不可用
TIFF	libtiff	TIFF 读写不可用
JPEG 2000	OpenJPEG/Jasper	对应格式不可用或受策略限制
WebP/AVIF/JPEG XL	对应格式库	对应格式不可用
OpenEXR	OpenEXR	EXR 能力关闭或受运行策略限制
医学/地理影像	GDCM/GDAL	专用格式和元数据能力关闭
视频文件/流	FFmpeg、GStreamer	对应容器、协议和编解码路径不可用
摄像头	V4L2、MSMF、AVFoundation 等平台 API	对应设备后端不可用
GUI	Qt、GTK、Wayland、Win32、Cocoa 等	imshow 等能力受限或不可用
并行	TBB、OpenMP、平台并发框架	退回其他并行后端或串行路径
数值库	LAPACK 等	部分数值实现无法使用外部优化
DNN CPU/图后端	Protobuf、OpenVINO 等	模型格式或执行后端受限
DNN CUDA	CUDA Toolkit、cuBLAS、cuDNN	CUDA DNN 后端不可构建
OpenCL	OpenCL 头、加载机制和运行时	T-API/OpenCL 路径不可用

有些第三方库可使用系统版本，也可构建 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 的主要入口位于：

modules/imgproc/src/smooth.dispatch.cpp

调用链可概括为：

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

典型调用链：imread

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

modules/imgcodecs/src/loadsave.cpp

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

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

典型调用链：VideoCapture

核心入口位于：

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 插件机制。

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

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 入口与实现：

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 运行时选择

运行时还会继续决策：

时机	选择内容
进程初始化	CPU 能力、日志、线程和全局配置
首次使用模块	注册表、插件发现、设备上下文和缓存
打开媒体	后端优先级、输入类型和参数
单次图像调用	类型、尺寸、连续性、输出种类和优化条件
DNN 网络执行	后端、目标、算子支持和回退
UMat 调用	OpenCL 可用性、内核支持和同步状态

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

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 快速定位声明、实现、测试和性能文件。