1. 使用范围与路径约定

本文是一份可独立使用的 OpenCV 4.13.0 源码导航，内容按源码树实际文件核验。

• 所有路径都相对于源码根目录 opencv-4.13.0/。
• “公开头”指安装后供使用者包含的头文件；“内部头”通常只参与 OpenCV 自身编译。
• src/ 是实现主入口，test/ 是正确性与回归测试，perf/ 是性能基准。
• 同一 API 可能经过分派层、HAL、第三方库或硬件后端，不能只凭第一个同名函数判断最终执行位置。
• 本文不依赖同目录或上级目录中的其他说明文档。

建议按“公开声明 → 普通实现 → 分派/HAL → 测试 → perf → Demo”的顺序阅读。

2. 根目录导航

3. 模块总览

4. Core：数据结构、基础运算与运行时

4.1 公开 API 与内部实现

4.2 Core 的分派、测试与性能入口

5. Imgproc：图像处理主干

公开声明集中在 modules/imgproc/include/opencv2/imgproc.hpp；较细的分割接口还可见
modules/imgproc/include/opencv2/imgproc/segmentation.hpp。

Imgproc HAL 的公开边界是 modules/imgproc/include/opencv2/imgproc/hal/hal.hpp 和
modules/imgproc/include/opencv2/imgproc/hal/interface.h，默认回退位于
modules/imgproc/src/hal_replacement.hpp。

6. Features2d：检测、描述与匹配

公开 API 入口为 modules/features2d/include/opencv2/features2d.hpp。

定位特征算法时，先区分检测器、描述子和匹配器；ORB 等类可能同时提供检测和描述。

7. Calib3d：多视图几何与标定

公开入口为 modules/calib3d/include/opencv2/calib3d.hpp，兼容 C 接口位于
modules/calib3d/include/opencv2/calib3d/calib3d_c.h。

8. Video：光流、背景建模与跟踪

9. 图像、窗口与视频 I/O

9.1 Imgcodecs

9.2 Highgui

9.3 Videoio

10. DNN：模型导入、网络执行与后端

排查 DNN 数值差异时，应同时记录模型导入器、层实现、backend 和 target；只检查
net.cpp 往往无法看到真正的计算内核。

11. G-API：计算图、编译器与后端

12. Stitching：全景拼接流水线

13. Objdetect：级联、HOG、二维码与 ArUco

14. Photo：修复、克隆、去噪与 HDR

公开入口为 modules/photo/include/opencv2/photo.hpp，CUDA 相关声明位于
modules/photo/include/opencv2/photo/cuda.hpp。

15. HAL、SIMD、OpenCL 与运行时分派

15.1 HAL 边界

15.2 通用 SIMD

15.3 树内 HAL 实现

典型调用链是“公开 API → 普通入口 → HAL 宏/函数 → 外部 HAL 或默认替换 → SIMD/标量”。
若输入是 UMat，还可能在普通 CPU 路径之前进入 src/opencl/ 中的 kernel。

16. CMake：从模块声明到 CPU 分派

阅读 .dispatch.cpp 时，同时在模块 CMakeLists.txt 中搜索
ocv_add_dispatched_file，可确认哪些源码会按 ISA 生成多个编译变体。

17. 语言绑定

17.1 Python

Python API 不一定有手写的同名包装函数；应先查 C++ 公开头上的导出标注，再查生成器。

17.2 Java

17.3 JavaScript

Objective-C 构建入口可从 modules/objc/CMakeLists.txt 和
modules/objc/generator/CMakeLists.txt 开始。

18. 测试与性能基准的阅读方法

19. 从 API 找到声明、实现、测试和 perf

以一个 API 名称 foo 为例，可按下列顺序查找：

1. 在 modules/*/include/opencv2/ 搜索 foo，确认命名空间、重载和默认参数；
2. 在 modules/*/src/ 搜索 foo( 或类的 ClassName::foo；
3. 若入口只有包装，继续跟踪 CV_OCL_RUN、CALL_HAL、CV_CPU_DISPATCH；
4. 查看同目录的 .dispatch.cpp、.simd.hpp 和 src/opencl/*.cl；
5. 在 modules/*/test/ 搜索 API 名、测试夹具名和相关枚举；
6. 在 modules/*/perf/ 搜索 API 名，确认性能参数；
7. 在 samples/ 搜索调用方式，观察输入准备和完整数据流；
8. 在模块 CMakeLists.txt 中确认文件是否受平台或依赖条件控制。

19.1 常见“搜索不到实现”的原因

20. 任务到源码速查

21. 推荐断点

断点若始终不命中，先确认是否走 OpenCL、IPP、插件、CUDA 或 CPU 分派版本，并核对当前
构建是否包含调试符号。

22. 二次开发的典型修改点

修改原则：先保留可靠的标量实现，再增加加速路径；先补最小回归测试，再运行宽参数 perf。

23. 官方 Demo 到源码映射

24. 推荐阅读路线

1. 从 modules/core/include/opencv2/core/mat.hpp 和 modules/core/src/matrix.cpp 理解数据模型。
2. 选择一个熟悉的 Imgproc API，对照公开声明、CPU 实现、测试和 perf。
3. 阅读一个 .dispatch.cpp 与其 .simd.hpp，理解 CPU 分派。
4. 对照 hal_replacement.hpp 和 hal/，理解默认实现与外接实现。
5. 阅读 Features2d → Calib3d 的匹配与几何估计链。
6. 阅读 Videoio 的注册表与两个不同平台后端，理解运行时选择。
7. 阅读 DNN 的导入器 → Net → layer → backend 数据流。
8. 阅读 G-API 的 API → 图模型 → passes → backend 编译流程。
9. 最后回到根 CMakeLists.txt、cmake/OpenCVModule.cmake 和模块 CMake 串联构建。

根路径：

1

YOLO/yolov5-7.0/

7.1 任务入口

7.2 模型核心

7.3 数据与增强

7.4 损失与指标

7.5 通用与 PyTorch 工具

7.6 配置文件

7.7 检测主调用链

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

detect.py::run
  → DetectMultiBackend(...)
      → attempt_load()                  # .pt
  → LoadImages / LoadStreams
      → letterbox()
  → DetectMultiBackend.forward()
      → DetectionModel.forward()
          → BaseModel._forward_once()
              → Detect.forward()
  → non_max_suppression()
  → scale_boxes()
  → Annotator.box_label()
  → cv2.imwrite / VideoWriter

7.8 训练主调用链

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

train.py::main
  → select_device / DDP 初始化
  → train()
      → check_dataset()
      → Model(...) = DetectionModel(...)
          → parse_model()
      → create_dataloader()
          → LoadImagesAndLabels
      → check_anchors()
      → ComputeLoss(model)
      → epoch
          → model(imgs)
          → compute_loss(pred, targets)
              → build_targets()
          → AMP backward
          → optimizer.step()
          → ModelEMA.update()
          → val.run()
          → torch.save(last/best)

7.9 验证主调用链

1
2
3
4
5
6
7
8
9

val.py::run
  → DetectMultiBackend 或传入 model
  → create_dataloader
  → forward
  → non_max_suppression
  → scale_boxes
  → process_batch
  → ap_per_class
  → P/R/mAP + confusion matrix

7.10 导出函数

export.py 主要导出器：

1
2
3
4
5
6
7
8
9
10
11

export_torchscript
export_onnx
export_openvino
export_paddle
export_coreml
export_engine
export_saved_model
export_pb
export_tflite
export_edgetpu
export_tfjs

7.11 推荐阅读顺序

1. detect.py::run()：先理解端到端推理
2. models/yolov5s.yaml：看网络图
3. models/yolo.py::parse_model()：理解 YAML 如何变成模型
4. BaseModel._forward_once()：理解跳连执行
5. Detect.forward()：理解训练输出和推理解码差异
6. utils/general.py::non_max_suppression()：理解后处理
7. utils/dataloaders.py::LoadImagesAndLabels：理解输入与增强
8. utils/loss.py::ComputeLoss：理解监督信号
9. train.py::train()：最后串起 AMP、EMA、DDP、验证与保存
10. 按需要读 segment/、classify/、export.py

7.12 二次开发定位

本文给出从 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

cmake -S /path/to/opencv-4.13.0 -B /path/to/build-debug -G Ninja -D CMAKE_BUILD_TYPE=RelWithDebInfo -D CMAKE_INSTALL_PREFIX=/path/to/install-debug -D BUILD_TESTS=ON
cmake --build /path/to/build-debug -j

Debug 最便于断言和逐步调试，但性能不能代表发布构建。RelWithDebInfo 常用于接近 Release 的采样和崩溃符号化。

4.6 Linux 交叉构建

OpenCV 源码提供多种工具链文件，例如：

1
2
3
4

platforms/linux/aarch64-gnu.toolchain.cmake
platforms/linux/arm-gnueabi.toolchain.cmake
platforms/linux/riscv64-gcc.toolchain.cmake
platforms/linux/riscv64-clang.toolchain.cmake

示例：

1
2
3

cmake -S /path/to/opencv-4.13.0 -B /path/to/build-aarch64 -G Ninja -D CMAKE_TOOLCHAIN_FILE=/path/to/opencv-4.13.0/platforms/linux/aarch64-gnu.toolchain.cmake -D CMAKE_INSTALL_PREFIX=/usr -D CMAKE_STAGING_PREFIX=/path/to/stage-aarch64 -D ARM_LINUX_SYSROOT=/path/to/sysroot -D BUILD_LIST=core,imgproc,imgcodecs -D BUILD_TESTS=OFF -D BUILD_PERF_TESTS=OFF -D BUILD_EXAMPLES=OFF
cmake --build /path/to/build-aarch64 -j
cmake --install /path/to/build-aarch64

CMAKE_INSTALL_PREFIX=/usr 表示目标机路径。CMAKE_STAGING_PREFIX 是主机侧暂存位置。还可按部署流程使用 DESTDIR，但不要同时混淆两套根目录语义。
交叉构建验收：

• 编译器目标三元组正确；sysroot 中头和库属于目标架构；
• file 或 readelf 显示正确 ELF 架构；CMake 没有误用主机 /usr/lib；
• Python 绑定没有把主机解释器库误当目标库；在真实设备或模拟环境运行最小测试。

5. 安装与卸载边界

安装后常见布局：

1
2
3
4

/path/to/install-opencv/include/opencv4/
/path/to/install-opencv/lib/
/path/to/install-opencv/lib/cmake/opencv4/
/path/to/install-opencv/bin/

精确布局受平台和 GNUInstallDirs 影响。消费工程应通过 OpenCVConfig.cmake 查找，不应依赖固定相对层数。
安装到系统前缀：

1

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

更推荐先安装到项目管理的独立前缀。源码构建通常没有可靠的通用 uninstall 目标。使用独立前缀可通过删除整个前缀干净移除。不要覆盖发行版管理器拥有的同名文件。

6. C++ 工程消费

6.1 推荐 CMake 写法

CMakeLists.txt：

1
2
3
4
5
6
7
8
9
10

cmake_minimum_required(VERSION 3.16)
project(opencv_demo LANGUAGES CXX)

find_package(OpenCV 4.13 REQUIRED
  COMPONENTS core imgproc imgcodecs videoio dnn)

add_executable(opencv_demo main.cpp)
target_compile_features(opencv_demo PRIVATE cxx_std_17)
target_include_directories(opencv_demo PRIVATE ${OpenCV_INCLUDE_DIRS})
target_link_libraries(opencv_demo PRIVATE ${OpenCV_LIBS})

配置消费工程：

1
2

cmake -S /path/to/app -B /path/to/build-app -G Ninja -D OpenCV_DIR=/path/to/install-opencv/lib/cmake/opencv4
cmake --build /path/to/build-app

某些安装还提供导出的具体 target。可用名称应以该安装的 OpenCVConfig.cmake 为准。${OpenCV_LIBS} 是跨不同 OpenCV 包布局更常见的兼容写法。

6.2 pkg-config

根配置中的 OPENCV_GENERATE_PKGCONFIG 默认关闭且标为 deprecated。新工程优先使用 CMake package config。必须兼容旧构建系统时，可显式请求生成并验证：

1

pkg-config --cflags --libs opencv4

静态链接时还要检查：

1

pkg-config --static --libs opencv4

6.3 最小图像程序

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
27

#include <opencv2/imgcodecs.hpp>
#include <opencv2/imgproc.hpp>
#include <iostream>

int main(int argc, char** argv) {
    if (argc != 3) {
        std::cerr << "usage: app input output\n";
        return 2;
    }

    cv::Mat image = cv::imread(argv[1], cv::IMREAD_COLOR);
    if (image.empty()) {
        std::cerr << "cannot decode input\n";
        return 3;
    }

    cv::Mat gray, edges;
    cv::cvtColor(image, gray, cv::COLOR_BGR2GRAY);
    cv::GaussianBlur(gray, gray, cv::Size(5, 5), 1.2);
    cv::Canny(gray, edges, 50, 150);

    if (!cv::imwrite(argv[2], edges)) {
        std::cerr << "cannot encode output\n";
        return 4;
    }
    return 0;
}

检查 imread()、VideoCapture::isOpened() 和模型读取结果。不要让空矩阵继续进入算法后才处理异常。

7. Python 构建与使用

7.1 在虚拟环境中构建

1
2
3
4
5
6

python3 -m venv /path/to/venv
/path/to/venv/bin/python -m pip install --upgrade pip numpy

cmake -S /path/to/opencv-4.13.0 -B /path/to/build-python -G Ninja -D CMAKE_BUILD_TYPE=Release -D CMAKE_INSTALL_PREFIX=/path/to/install-python -D BUILD_opencv_python3=ON -D PYTHON3_EXECUTABLE=/path/to/venv/bin/python -D PYTHON3_PACKAGES_PATH=/path/to/venv/lib/python3.x/site-packages
cmake --build /path/to/build-python -j
cmake --install /path/to/build-python

把 python3.x 替换为实际版本目录。安装后验证实际加载文件：

1
2
3
4
5
6

/path/to/venv/bin/python - <<'PY'
import cv2
print(cv2.__version__)
print(cv2.__file__)
print(cv2.getBuildInformation())
PY

7.2 Python API 示例

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

from pathlib import Path
import cv2

src_path = Path("/path/to/input.jpg")
dst_path = Path("/path/to/output.png")

image = cv2.imread(str(src_path), cv2.IMREAD_COLOR)
if image is None:
    raise FileNotFoundError(src_path)

gray = cv2.cvtColor(image, cv2.COLOR_BGR2GRAY)
edges = cv2.Canny(gray, 50, 150)
if not cv2.imwrite(str(dst_path), edges):
    raise RuntimeError(f"cannot write {dst_path}")

Python 的 NumPy 数组常与 cv::Mat 共享或包装内存。注意 dtype、shape、stride、连续性和生命周期。避免在热点循环中无意义调用 np.ascontiguousarray() 或复制。

7.3 常见 Python 混装

系统包、pip wheel 和源码构建的 cv2 可能同时存在。表现包括：

• cv2.__version__ 不是 4.13.0；getBuildInformation() 缺少刚启用的后端；
• 导入时报未定义符号；NumPy ABI 不匹配；
• IDE 与终端使用不同解释器。
  总是先打印：

1
2

import cv2, sys
print(sys.executable); print(cv2.__file__); print(cv2.__version__)

8. 视频读取与写入

C++ 示例：

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

cv::VideoCapture cap("/path/to/input.mp4", cv::CAP_ANY);
if (!cap.isOpened())
    throw std::runtime_error("cannot open video");

double fps = cap.get(cv::CAP_PROP_FPS);
int width = static_cast<int>(cap.get(cv::CAP_PROP_FRAME_WIDTH));
int height = static_cast<int>(cap.get(cv::CAP_PROP_FRAME_HEIGHT));

cv::VideoWriter out(
    "/path/to/output.mp4",
    cv::VideoWriter::fourcc('m', 'p', '4', 'v'),
    fps > 0 ? fps : 30.0,
    cv::Size(width, height));
if (!out.isOpened())
    throw std::runtime_error("cannot open writer");

cv::Mat frame;
while (cap.read(frame)) {
    cv::putText(frame, "OpenCV", {20, 40},
                cv::FONT_HERSHEY_SIMPLEX, 1.0, {0, 255, 0}, 2);
    out.write(frame);
}

后端、容器和 codec 是三层概念。文件扩展名不能保证编码器存在。用 cap.getBackendName() 或调试日志确认实际后端。相机可显式传 cv::CAP_V4L2、cv::CAP_GSTREAMER 等偏好，但必须由构建支持。
在 Python 中：

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

cap = cv2.VideoCapture("/path/to/input.mp4", cv2.CAP_ANY)
if not cap.isOpened():
    raise RuntimeError("cannot open video")

try:
    while True:
        ok, frame = cap.read()
        if not ok:
            break
        # process frame
finally:
    cap.release()

生产服务应限制网络流的连接、读取和重连策略。不要无限阻塞或无限缓存来自不可信源的视频。

9. DNN 推理

9.1 ONNX 基本流程

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

cv::dnn::Net net = cv::dnn::readNetFromONNX("/path/to/model.onnx");
if (net.empty())
    throw std::runtime_error("cannot load model");

net.setPreferableBackend(cv::dnn::DNN_BACKEND_OPENCV);
net.setPreferableTarget(cv::dnn::DNN_TARGET_CPU);

cv::Mat blob = cv::dnn::blobFromImage(
    image, 1.0 / 255.0, cv::Size(640, 640),
    cv::Scalar(), true, false, CV_32F);
net.setInput(blob);
cv::Mat output = net.forward();

预处理参数必须来自模型契约：

• 输入尺寸；NCHW 或其他布局；
• BGR/RGB 顺序；scale；
• mean；crop 或 letterbox；
• 输入精度；输出节点和后处理。
  “能运行”不代表预处理正确。应使用已知样本与参考框架对齐输出。

9.2 查询并选择后端

1
2

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

公开后端包括 OpenCV、OpenVINO、CUDA、Halide、VkCom、WebNN、TIM-VX 和 CANN 等。实际可用组合由构建与运行时依赖决定。先查询，再设置 backend/target。首次推理通常包含初始化或编译，性能测试要预热。

9.3 DNN 诊断

可先提高日志等级：

1

OPENCV_LOG_LEVEL=DEBUG /path/to/dnn-app

进一步排查可使用：

1

OPENCV_DNN_CHECK_NAN_INF=1 OPENCV_DNN_CHECK_NAN_INF_RAISE_ERROR=1 /path/to/dnn-app

这些检查会影响性能，仅用于诊断。对不支持的 ONNX 算子，先最小化模型并记录导出器版本、opset 和错误层。

10. samples、tests 与 perf

源码中的主要样例目录：

1
2
3
4
5
6
7

samples/cpp/
samples/python/
samples/dnn/
samples/tapi/
samples/opencl/
samples/gpu/
samples/hal/

启用示例：

1
2

cmake -S /path/to/opencv-4.13.0 -B /path/to/build-samples -D CMAKE_BUILD_TYPE=Release -D BUILD_EXAMPLES=ON
cmake --build /path/to/build-samples -j

正确性与性能测试分别位于各模块的 test/ 和 perf/。常见目标名：

1
2
3
4

opencv_test_core
opencv_test_imgproc
opencv_perf_core
opencv_perf_imgproc

运行单个测试：

1

/path/to/build-opencv/bin/opencv_test_core --gtest_filter='Core_Mat.*'

通过 CTest：

1

ctest --test-dir /path/to/build-opencv --output-on-failure

性能测试：

1

/path/to/build-opencv/bin/opencv_perf_imgproc --gtest_filter='*GaussianBlur*'

先运行可执行文件的 --help 确认当前参数。测试数据可能要求额外数据仓库或环境变量。跨机器比较 perf 前固定构建类型、线程数、温度、频率和输入。

11. 调试与日志

11.1 运行时构建信息

1
2
3
4

std::cout << cv::getVersionString() << '\n';
std::cout << cv::getBuildInformation() << '\n';
std::cout << cv::getCPUFeaturesLine() << '\n';
std::cout << cv::getNumThreads() << '\n';

Python 对应：

1

print(cv2.__version__); print(cv2.getBuildInformation()); print(cv2.getCPUFeaturesLine()); print(cv2.getNumThreads())

11.2 日志级别

环境变量方式：

1

OPENCV_LOG_LEVEL=DEBUG /path/to/app

C++ API：

1
2
3
4

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

cv::utils::logging::setLogLevel(
    cv::utils::logging::LOG_LEVEL_VERBOSE);

详细日志可能包含设备、后端和文件信息。生产环境应控制等级并避免把敏感路径直接发送到外部日志。

11.3 GDB 与 sanitizer

1

gdb --args /path/to/app /path/to/input.jpg

应用和 OpenCV 都有符号时回溯最有价值。如需 sanitizer，建议建立独立构建并统一编译、链接选项。

1

cmake -S /path/to/opencv-4.13.0 -B /path/to/build-asan -G Ninja -D CMAKE_BUILD_TYPE=Debug -D CMAKE_C_FLAGS='-fsanitize=address -fno-omit-frame-pointer' -D CMAKE_CXX_FLAGS='-fsanitize=address -fno-omit-frame-pointer' -D CMAKE_EXE_LINKER_FLAGS='-fsanitize=address' -D CMAKE_SHARED_LINKER_FLAGS='-fsanitize=address'

常规定位顺序：

1. 确认实际加载的 OpenCV；
2. 保存原始输入和最小复现；
3. 打印尺寸、类型、步长和连续性；
4. 单线程复现；
5. 关闭特定加速后端做对照；
6. 使用 Debug、断言和 sanitizer；
7. 修复后增加回归测试。

12. 部署

12.1 共享库部署

查看 ELF 依赖：

1
2

ldd /path/to/app
readelf -d /path/to/app

部署时包含：

• 应用直接依赖的 OpenCV .so；OpenCV 所需第三方运行库；
• 视频、GUI 或 DNN 插件；模型、级联文件和配置；
• 与目标系统兼容的 C++ 运行库。
  使用 RPATH/RUNPATH 或系统动态链接器配置管理查找路径。不要依赖开发机的 LD_LIBRARY_PATH 作为正式部署方案。

12.2 容器部署

多阶段构建可将编译环境与运行环境分开。运行镜像只复制安装前缀、应用和必要运行库。还要考虑：

• 摄像头设备映射；GPU 驱动与容器 runtime；
• GUI socket；codec 和字体；
• 非 root 用户权限；只读文件系统下的缓存目录。

12.3 静态部署

静态链接降低部分运行时查找问题，但会：

• 增大文件；增加第三方依赖传播复杂度；
• 影响插件能力；加重许可证合规工作；
• 使安全更新需要重新链接和发布。
  无论共享或静态，都应生成软件物料清单并保留构建配置。

13. ABI 与版本共存

不要假设所有 OpenCV 4.x 二进制 ABI 永久兼容。风险来源包括：

• 编译器和 libstdc++ ABI；Debug 与 Release 混用；
• _GLIBCXX_USE_CXX11_ABI；静态与共享库组合；
• contrib 与主库版本不一致；第三方库 ABI；
• DNN 插件与核心库版本；Python 与 NumPy ABI。
  最佳实践：
• 应用与 OpenCV 使用兼容工具链；编译时和运行时加载同一安装前缀；
• 通过 OpenCV_DIR 固定消费版本；不混合多个前缀的头和库；
• 插件与主库一起构建、测试和部署；升级小版本也执行 ABI 与回归验证；
• 对公共接口避免暴露 cv::Mat 跨不受控插件边界，除非双方 ABI 被锁定。
  并行安装可使用不同前缀。运行时通过 RUNPATH 或隔离容器选择版本。不要用覆盖系统库的方式实现升级。

14. 迁移到 4.13.0

迁移检查清单：

• 移除旧 C API 和废弃常量；核对模块是否移动到 contrib；
• 检查返回值、默认参数和 Python tuple 形态；重新导出并验证 DNN 模型；
• 核对 ONNX opset 和后端覆盖；重新验证视频后端、codec 和设备索引；
• 检查序列化文件、标定参数和模型兼容性；更新 CMake 的组件列表；
• 重跑正确性、性能和资源泄漏测试；检查许可证与部署依赖变化。
  迁移时先固定旧版输出样本。对浮点算法定义绝对或相对误差，而不是要求逐位一致。同时比较性能分布，避免因后端改变出现隐性回退。

15. 安全与资源管理

OpenCV 处理的是复杂二进制格式、视频流和模型。不可信输入应视为攻击面。

15.1 输入控制

• 在解码前限制文件大小；解码后限制宽、高、通道和总像素；
• 对视频限制帧率、分辨率、时长和重连次数；对模型限制来源、大小和允许格式；
• 拒绝路径穿越和意外覆盖输出；设置任务超时和内存上限；
• 将解析服务放入低权限进程或容器；跟踪 OpenCV 与 codec 库安全更新。
  像素内存约为：

1

rows * step

不能只用压缩文件大小估算解码内存。超高压缩比图片和畸形尺寸可能导致资源耗尽。

15.2 C++ 生命周期

cv::Mat 使用引用计数并支持浅拷贝。返回引用、ROI 或包装外部缓冲区时，必须保证底层内存仍存活。跨线程共享只读矩阵通常可行，但并发写入需要应用自行同步。
资源对象使用 RAII：

1
2
3
4
5
6

{
    cv::VideoCapture cap("/path/to/input.mp4");
    if (!cap.isOpened())
        throw std::runtime_error("open failed");
    // cap leaves scope and releases resources
}

不要把 Mat::data 保存到超过矩阵生命周期的异步任务。包装外部内存时，OpenCV 不一定拥有或释放该内存。

15.3 Python 生命周期

使用 try/finally 释放摄像头和 writer。长服务中不要无界保存帧列表。NumPy 视图与 cv2 返回数组共享数据时，保留拥有者引用。捕获 cv2.error 时记录操作和输入元数据，但避免记录敏感图像本身。

16. FAQ

16.1 找不到 OpenCVConfig.cmake

显式指定：

1

-D OpenCV_DIR=/path/to/install-opencv/lib/cmake/opencv4

确认该文件确实由 cmake --install 生成。不要把 OpenCV_DIR 指向源码根目录。

16.2 头文件找到但链接失败

常见原因：

• 头来自一个版本，库来自另一个版本；忘记请求对应组件；
• 静态第三方依赖未传播；Debug/Release 或 C++ ABI 不一致；
• 链接顺序不适合手写静态库列表。
  删除手写 -lopencv_*，先用安装导出的 CMake 配置复现。

16.3 运行时找不到 .so

先查看：

1
2

ldd /path/to/app
readelf -d /path/to/app

为部署配置 RUNPATH，或将库安装到受管理的系统路径。不要复制单个 OpenCV 库后忽略其第三方依赖。

16.4 imread() 返回空

检查：

• 路径与当前工作目录；文件读取权限；
• 文件是否完整；对应 codec 是否在 Summary 中启用；
• 输入是否超出资源限制；cv::haveImageReader() 是否识别该文件。
  内存输入使用 imdecode()，并验证字节缓冲区完整。

16.5 VideoCapture 打不开

检查：

• WITH_FFMPEG / WITH_GSTREAMER 的最终探测；摄像头设备权限；
• 容器设备映射；backend preference；
• URL、认证、网络与超时；codec 和像素格式。
  用 OPENCV_LOG_LEVEL=DEBUG 查看后端尝试。

16.6 imshow() 在服务器失败

无桌面环境通常没有可用显示后端或 display server。改为 imwrite()、Web 输出或无头测试。不要为了 imshow() 给生产容器引入整套 GUI，除非确有需求。

16.7 Python 导入了错误版本

打印：

1
2

import cv2, sys
print(sys.executable); print(cv2.__file__); print(cv2.getBuildInformation())

清理冲突的 pip、系统包或 PYTHONPATH。重新配置时确认 Summary 指向目标虚拟环境。

16.8 打开 CUDA 但算法仍在 CPU

WITH_CUDA=ON 不会让普通 cv::Mat 算法自动迁移到 GPU。CUDA 模块通常使用专用 cv::cuda API，并可能来自 contrib。DNN 还需要选择 CUDA backend/target，并满足对应构建依赖。

16.9 Release 仍然很慢

按顺序确认：

1. 实际加载的是 Release 库；
2. 输入没有重复复制和转换；
3. CPU dispatch 与并行后端存在；
4. 线程没有过度订阅；
5. GPU/OpenCL 计时包含同步；
6. DNN 已预热且未回退；
7. 热点确实位于 OpenCV 调用内部。

16.10 CMake 选项显示 ON，但功能不可用

选项表达请求，不表达探测成功。检查 Summary、CMakeCache.txt、getBuildInformation() 和日志。依赖版本、头、库、目标架构或工具链任一不匹配都可能使能力不可用。

17. 发布前验收清单

• 使用干净构建目录完成配置；保存完整 CMake 命令和 Summary；
• 构建类型是预期的 Release 或 RelWithDebInfo；安装到独立前缀；
• 消费工程只使用该前缀；C++ 最小程序可编译和运行；
• Python 时确认 cv2.__file__；图片、视频和 DNN 各跑一个真实样本；
• 执行目标模块 tests；在目标设备运行 perf 或业务基准；
• 检查共享库和插件依赖；核对模型、codec、contrib 和 nonfree 许可；
• 对不可信输入设置尺寸、时间和内存限制；记录 ABI、编译器和第三方版本；
• 保留回滚所需的旧安装前缀和构建清单。
  完成这些步骤后，构建结果才不仅是“编译通过”，而是可定位、可复现、可部署和可维护的 OpenCV 4.13.0 工程。

6.1 安装

1
2
3
4

cd /home/cp/work2/visualAlgo/YOLO/yolov5-7.0
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

PyTorch 是否带 CUDA，应按本机驱动从 PyTorch 官方安装对应版本。仅执行 requirements.txt 不保证获得正确的 CUDA wheel。

验证环境：

1
2
3
4
5
6

python - <<'PY'
import torch, cv2
print("torch:", torch.__version__)
print("cuda:", torch.cuda.is_available())
print("opencv:", cv2.__version__)
PY

6.2 权重

源码目录不等于权重包。常用权重：

1
2
3
4
5

yolov5n.pt  最小最快
yolov5s.pt  常用入门
yolov5m.pt
yolov5l.pt
yolov5x.pt  最大

传入不存在的官方权重名时，attempt_download() 会尝试下载。离线机器应提前复制 .pt。

也可执行：

1

bash data/scripts/download_weights.sh

6.3 快速检测

1
2
3
4
5
6

python detect.py \
  --weights yolov5s.pt \
  --source data/images \
  --img 640 \
  --conf-thres 0.25 \
  --iou-thres 0.45

结果默认写入：

1

runs/detect/exp/

常见 source：

1
2
3
4
5
6

--source image.jpg
--source images/
--source video.mp4
--source 0
--source rtsp://...
--source screen

常见选项：

1
2
3
4
5
6
7

--save-txt           # 保存 class xywh
--save-conf          # TXT 追加置信度
--save-crop          # 保存目标裁剪
--classes 0 2        # 只保留指定类别
--agnostic-nms       # 类别无关 NMS
--half               # 支持的 GPU/后端上 FP16
--vid-stride 2       # 视频隔帧

6.4 自定义数据集

目录：

1
2
3
4
5
6
7

datasets/mydata/
├── images/
│   ├── train/
│   └── val/
└── labels/
    ├── train/
    └── val/

data/mydata.yaml：

1
2
3
4
5
6

path: ../datasets/mydata
train: images/train
val: images/val
names:
  0: cat
  1: dog

标签：

1

0 0.512 0.480 0.200 0.350

含义为 class cx cy w h，坐标归一化。类别必须从 0 连续编号，且小于 nc。

6.5 训练

迁移学习

1
2
3
4
5
6
7

python train.py \
  --weights yolov5s.pt \
  --data data/mydata.yaml \
  --epochs 100 \
  --img 640 \
  --batch-size 16 \
  --device 0

从零训练

1
2
3
4
5
6

python train.py \
  --weights '' \
  --cfg models/yolov5s.yaml \
  --data data/mydata.yaml \
  --hyp data/hyps/hyp.scratch-low.yaml \
  --epochs 300

自动 Batch

单 GPU 可使用：

1

--batch-size -1

冻结 Backbone

1

--freeze 10

表示冻结模型前 10 层，适合小数据集初期迁移。

6.6 恢复训练

1

python train.py --resume runs/train/exp/weights/last.pt

恢复需要 last.pt 中仍包含：

• epoch
• optimizer
• EMA
• opt/hyp

训练结束时 strip_optimizer() 会移除优化器状态并转 FP16；被 strip 的部署权重不适合完整恢复。

6.7 多 GPU DDP

1
2
3
4
5
6

python -m torch.distributed.run \
  --nproc_per_node 4 \
  train.py \
  --batch-size 64 \
  --device 0,1,2,3 \
  --data data/mydata.yaml

源码明确不推荐传统 DataParallel。DDP 的 batch-size 是总 batch，会按 WORLD_SIZE 分给各 GPU。

6.8 验证

1
2
3
4
5
6

python val.py \
  --weights runs/train/exp/weights/best.pt \
  --data data/mydata.yaml \
  --img 640 \
  --conf-thres 0.001 \
  --iou-thres 0.6

主要输出：

• Precision
• Recall
• mAP@0.5
• mAP@0.5:0.95
• 各类别 AP
• 混淆矩阵和 PR 曲线（未关闭 plots 时）

验证时低 conf-thres 是为了保留完整 PR 曲线，不等同于部署阈值。

6.9 分割

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

python segment/train.py \
  --model yolov5s-seg.pt \
  --data data/coco128-seg.yaml \
  --epochs 5 \
  --img 640

python segment/val.py \
  --weights yolov5s-seg.pt \
  --data data/coco128-seg.yaml

python segment/predict.py \
  --weights yolov5s-seg.pt \
  --source data/images

6.10 分类

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

python classify/train.py \
  --model yolov5s-cls.pt \
  --data cifar100 \
  --epochs 5 \
  --img 224

python classify/val.py \
  --weights yolov5s-cls.pt \
  --data ../datasets/imagenet

python classify/predict.py \
  --weights yolov5s-cls.pt \
  --source data/images

6.11 PyTorch Hub

本地源码（以下直接传图片的写法适用于检测模型；v7.0 的分类/分割模型不会自动套用 AutoShape）：

1
2
3
4
5
6
7
8
9
10
11

import torch

model = torch.hub.load(
    "/home/cp/work2/visualAlgo/YOLO/yolov5-7.0",
    "custom",
    path="best.pt",
    source="local",
)
results = model("image.jpg")
results.print()
results.save()

若输入是 OpenCV 数组，AutoShape 注释期望 RGB：

1
2

rgb = cv2.imread("image.jpg")[:, :, ::-1]
results = model(rgb)

仓库中的 sample_detect.py 是该模式的最小示例。

6.12 导出

ONNX

1
2
3
4
5
6

python export.py \
  --weights best.pt \
  --include onnx \
  --img 640 \
  --opset 12 \
  --simplify

TensorRT

1
2
3
4
5

python export.py \
  --weights best.pt \
  --include engine \
  --device 0 \
  --half

OpenVINO

1

python export.py --weights best.pt --include openvino

其他 --include 格式见：

1

python export.py --help

6.13 ONNX + OpenCV DNN

1
2
3
4

python detect.py \
  --weights best.onnx \
  --source image.jpg \
  --dnn

这会让 DetectMultiBackend 调用 cv2.dnn.readNetFromONNX()，而不是 ONNX Runtime。

6.14 常见问题

yolov5s.pt 不存在

源码没有内置权重。联网时自动下载；离线时手动放到当前目录或传绝对路径。

CUDA 不可用

检查：

1

torch.cuda.is_available()

若为 False，通常是安装了 CPU 版 PyTorch、驱动不匹配或容器没挂 GPU。

标签越界

日志出现：

1

Label class X exceeds nc=N

说明标签类别 ID 大于数据集 YAML 中类别数，或类别不是从 0 开始。

OOM

依次尝试：

• 减小 --batch-size
• 减小 --img
• 使用 --batch-size -1
• 使用更小模型
• 关闭 cache 或改 disk

框映射不准

不要直接把网络输入坐标画到原图；必须用 scale_boxes() 消除 Letterbox 的缩放和 padding。

RK3588 NPU

.pt 默认只能走 PyTorch CPU/GPU。RK3588 NPU 通常要：

1

.pt → ONNX → RKNN → RKNN Runtime

--device 不能让 PyTorch .pt 自动运行在 RK NPU。