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、依赖和运行时行为。

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