OpenCV 配置选项参考

目录

• 简介
• 通用选项
  • 使用额外模块构建
  • 使用 C++ 标准设置构建
  • 调试构建
  • 静态构建
  • 生成 pkg-config 信息
  • 构建测试、示例和应用程序
  • 构建有限模块集
  • 已下载的依赖项
  • CPU 优化级别
  • 性能分析、代码覆盖、内存清理、强化、大小优化
  • 启用 IPP 优化
• 功能特性和依赖项
  • 选项命名约定
  • 异构计算
    • CUDA 支持
    • OpenCL 支持
  • 图像读写 (imgcodecs 模块)
    • 内置格式
    • PNG、JPEG、TIFF、WEBP、JPEG 2000、EXR、JPEG XL 支持
    • GDAL 集成
    • GDCM 集成
  • 视频读写 (videoio 模块)
    • Video4Linux
    • FFmpeg
    • GStreamer
    • Microsoft Media Foundation
    • DirectShow
    • AVFoundation
    • 其他后端
    • videoio 插件
  • 并行处理
    • 线程插件
  • GUI 后端 (highgui 模块)
    • OpenGL
    • highgui 插件
  • 深度学习神经网络推理后端和选项 (dnn 模块)
• 安装布局
  • 安装根目录
  • 组件和位置
• 杂项功能
  • 自动化构建
  • Contrib 模块
• 其他未文档化选项

上一个教程： OpenCV 安装概述
下一个教程： OpenCV 环境变量参考

简介

注意

我们假设您已阅读 OpenCV 安装概述 教程或有 CMake 使用经验。

配置选项可以通过几种不同的方式设置

• 命令行：cmake -Doption=value ...
• 初始缓存文件：cmake -C my_options.txt ...
• 通过 GUI 交互式设置

在本参考中，我们将使用常规命令行。

大多数选项可以在 OpenCV 的根 cmake 脚本中找到：opencv/CMakeLists.txt。一些选项可以在特定模块中定义。

可以使用 CMake 工具打印所有可用选项

# 初始配置
cmake ../opencv
 
# 打印所有选项
cmake -L
 
# 打印所有选项并附带帮助信息
cmake -LH
 
# 打印所有选项，包括高级选项
cmake -LA

最常用和最有用的选项以 WITH_, ENABLE_, BUILD_, OPENCV_ 开头。

默认值因平台和其他选项值而异。

通用选项

使用额外模块构建

OPENCV_EXTRA_MODULES_PATH 选项包含一个分号分隔的目录列表，这些目录包含将添加到构建中的额外模块。模块目录必须具有兼容的布局和 CMakeLists.txt，简要说明可在 编码风格指南 中找到。

示例

# 使用 opencv_contrib 中的所有模块构建
cmake -DOPENCV_EXTRA_MODULES_PATH=../opencv_contrib/modules ../opencv
 
# 使用 opencv_contrib 模块之一构建
cmake -DOPENCV_EXTRA_MODULES_PATH=../opencv_contrib/modules/bgsegm ../opencv
 
# 使用两个自定义模块构建 (bash 中必须转义分号)
cmake -DOPENCV_EXTRA_MODULES_PATH=../my_mod1\;../my_mod2 ../opencv

注意

仅支持 0 级和 1 级深度的模块位置，以下命令将引发错误

cmake -DOPENCV_EXTRA_MODULES_PATH=../opencv_contrib ../opencv

使用 C++ 标准设置构建

CMAKE_CXX_STANDARD 选项可用于设置 OpenCV 构建的 C++ 标准。

cmake -DCMAKE_CXX_STANDARD=17 ../opencv
cmake --build .

• C++11 是 OpenCV 4.x 的默认/必需/推荐标准。C++17 是 OpenCV 5.x 的默认/必需/推荐标准。
• 如果您的编译器不支持所需的 C++ 标准特性，OpenCV 配置应该会失败。
• 如果您设置的 C++ 标准低于要求，OpenCV 配置应该会失败。作为变通方法，可以使用 OPENCV_SKIP_CMAKE_CXX_STANDARD 选项跳过 CMAKE_CXX_STANDARD 版本检查。
• 如果您设置的 C++ 标准高于推荐标准，可能会出现大量警告，或者 OpenCV 构建可能会失败。

调试构建

CMAKE_BUILD_TYPE 选项可用于启用调试构建；生成的二进制文件将包含调试符号，并且大多数编译器优化将被关闭。要在发布构建中启用调试符号，请打开 BUILD_WITH_DEBUG_INFO 选项。

在某些平台（例如 Linux）上，构建类型必须在配置阶段设置

cmake -DCMAKE_BUILD_TYPE=Debug ../opencv
cmake --build .

在其他平台上，可以在同一个构建目录中生成不同类型的构建（例如 Visual Studio，XCode）

cmake <选项> ../opencv
cmake --build . --config Debug

如果您使用 GNU libstdc++（GCC 的默认设置），您可以打开 ENABLE_GNU_STL_DEBUG 选项，这样 C++ 库将在调试模式下使用，例如，在向量元素访问期间将进行索引边界检查。

许多类型的优化可以通过 CV_DISABLE_OPTIMIZATION 选项禁用

• 一些第三方库（例如 IPP、Lapack、Eigen）
• 显式向量化实现（通用内联函数、原始内联函数等）
• 调度优化
• 显式循环展开

另请参见

https://cmake.com.cn/cmake/help/latest/variable/CMAKE_BUILD_TYPE.html

https://gcc.gnu.org/onlinedocs/libstdc++/manual/using_macros.html

https://github.com/opencv/opencv/wiki/CPU-optimizations-build-options

静态构建

BUILD_SHARED_LIBS 选项控制是生成动态库（.dll, .so, .dylib）还是静态库（.a, .lib）。默认值取决于目标平台，在大多数情况下为 ON。

示例

cmake -DBUILD_SHARED_LIBS=OFF ../opencv

另请参见

https://en.wikipedia.org/wiki/Static_library

ENABLE_PIC 设置 CMAKE_POSITION_INDEPENDENT_CODE 选项。它启用或禁用“位置无关代码”的生成。在构建动态库或旨在链接到动态库的静态库时，此选项必须启用。默认值为 ON。

另请参见

https://en.wikipedia.org/wiki/Position-independent_code

生成 pkg-config 信息

OPENCV_GENERATE_PKGCONFIG 选项支持生成 .pc 文件，以及标准的 CMake 包。此文件对于不使用 CMake 进行构建的项目可能很有用。

示例

cmake -DOPENCV_GENERATE_PKGCONFIG=ON ../opencv

注意

由于配置过程的复杂性，生成的 .pc 文件可能包含不完整的第三方依赖项列表，并且在某些配置中可能无法工作，特别是对于静态构建。此功能自 4.x 版本起不被官方支持，并默认禁用。

构建测试、示例和应用程序

测试有两种类型：准确性测试（opencv_test_*）和性能测试（opencv_perf_*）。测试和应用程序默认启用。示例默认不构建，应显式启用。

相应的 cmake 选项

cmake \
-DBUILD_TESTS=ON \
-DBUILD_PERF_TESTS=ON \
-DBUILD_EXAMPLES=ON \
-DBUILD_opencv_apps=ON \
../opencv

构建有限模块集

每个模块都是 modules 目录的子目录。可以禁用一个模块

cmake -DBUILD_opencv_calib3d=OFF ../opencv

相反的选项是只构建指定的模块以及它们依赖的所有模块

cmake -DBUILD_LIST=calib3d,videoio,ts ../opencv

在这个例子中，我们请求了 3 个模块，配置脚本自动确定了所有依赖项

-- OpenCV 模块
-- 将要构建：calib3d core features2d flann highgui imgcodecs imgproc ts videoio

已下载的依赖项

配置脚本可以尝试从互联网下载额外的库和文件，如果失败，则相应的功能将被关闭。在某些情况下，可能会出现配置错误。默认情况下，所有文件首先下载到 <source>/.cache 目录，然后解压或复制到构建目录。可以通过设置环境变量或配置选项来更改下载缓存位置

export OPENCV_DOWNLOAD_PATH=/tmp/opencv-cache
cmake ../opencv
# 或
cmake -DOPENCV_DOWNLOAD_PATH=/tmp/opencv-cache ../opencv

如果通过代理访问，应在运行 cmake 之前设置相应的环境变量

export http_proxy=<代理主机>:<端口>
export https_proxy=<代理主机>:<端口>

下载过程的完整日志可在构建目录中找到 - CMakeDownloadLog.txt。此外，对于每个失败的下载，一个命令将添加到构建目录中的辅助脚本中，例如 download_with_wget.sh。用户可以按原样运行这些脚本，也可以根据需要进行修改。

CPU 优化级别

在 x86_64 机器上，库默认将为 SSE3 指令集级别编译。此级别可以通过配置选项更改

cmake -DCPU_BASELINE=AVX2 ../opencv

注意

其他平台有其自己的指令集级别：ARM 上的 VFPV3 和 NEON，PowerPC 上的 VSX。

一些函数支持调度机制，允许为多个指令集编译它们并在运行时选择一个。已启用的指令集列表可在配置期间更改

cmake -DCPU_DISPATCH=AVX,AVX2 ../opencv

要禁用调度机制，此选项应设置为空值

cmake -DCPU_DISPATCH= ../opencv

可以禁用代码的优化部分以进行故障排除和调试

# 禁用通用内联函数
cmake -DCV_ENABLE_INTRINSICS=OFF ../opencv
# 禁用所有可能的内置优化
cmake -DCV_DISABLE_OPTIMIZATION=ON ../opencv

注意

有关 CPU 优化选项的更多详细信息可在 wiki 中找到：https://github.com/opencv/opencv/wiki/CPU-optimizations-build-options

性能分析、代码覆盖、内存清理、强化、大小优化

以下选项可用于生成带有插装或改进安全性的特殊构建。所有选项默认禁用。

选项	编译器	描述
ENABLE_PROFILING	GCC 或 Clang	启用性能分析编译器和链接器选项。
ENABLE_COVERAGE	GCC 或 Clang	启用代码覆盖率支持。
OPENCV_ENABLE_MEMORY_SANITIZER	不适用	在代码中启用一些怪异行为以协助内存清理器。
ENABLE_BUILD_HARDENING	GCC、Clang、MSVC	启用编译器选项，以减少代码被利用的可能性。
ENABLE_LTO	GCC、Clang、MSVC	启用链接时优化 (LTO)。
ENABLE_THIN_LTO	Clang	启用 Thin LTO，它将中间字节码合并到二进制文件中，允许消费者以后优化其应用程序。
OPENCV_ALGO_HINT_DEFAULT	任意	设置默认 OpenCV 实现提示值：ALGO_HINT_ACCURATE 或 ALGO_HINT_APPROX。危险！此选项全局更改行为，并可能影响许多算法的准确性。

另请参见

GCC 插装

构建强化

过程间优化

链接时优化

ThinLTO

启用 IPP 优化

以下选项可用于为每个函数启用 IPP 优化，但这会增加 opencv 库的大小。所有选项默认禁用。

选项	函数	+ 大致大小
OPENCV_IPP_GAUSSIAN_BLUR	GaussianBlur()	+8Mb
OPENCV_IPP_MEAN	mean() / meanStdDev()	+0.2Mb
OPENCV_IPP_MINMAX	minMaxLoc() / minMaxIdx()	+0.2Mb
OPENCV_IPP_SUM	sum()	+0.1Mb

功能特性和依赖项

有许多可选依赖项和功能可以打开或关闭。cmake 有一个特殊选项可以打印所有可用的配置参数

cmake -LH ../opencv

选项命名约定

有三种控制库依赖项的选项，它们具有不同的前缀

• 以 WITH_ 开头的选项启用或禁用依赖项
• 以 BUILD_ 开头的选项启用或禁用构建和使用 OpenCV 捆绑的第三方库
• 以 HAVE_ 开头的选项指示依赖项已启用，如果无法使用自动检测，则可用于手动启用依赖项。

当 WITH_ 选项启用时

• 如果 BUILD_ 选项启用，将构建并启用第三方库 => HAVE_ 设置为 ON
• 如果 BUILD_ 选项禁用，将检测第三方库，如果找到则启用 => 如果找到依赖项，HAVE_ 设置为 ON

异构计算

CUDA 支持

WITH_CUDA (默认: *OFF*)

许多算法已使用 CUDA 加速实现，这些函数位于单独的模块中。CUDA 工具包必须作为先决条件从 NVIDIA 官方网站安装。对于早于 3.9 的 cmake 版本，OpenCV 使用自己的 cmake/FindCUDA.cmake 脚本，对于更新的版本，则使用 CMake 附带的脚本。可以使用其他选项来控制构建过程，例如 CUDA_GENERATION 或 CUDA_ARCH_BIN。这些参数尚未文档化，请查阅 cmake/OpenCVDetectCUDA.cmake 脚本以获取详细信息。

注意

自 OpenCV 4.0 版本以来，所有 CUDA 加速算法实现都已移至 *opencv_contrib* 仓库。要同时构建 *opencv* 和 *opencv_contrib*，请查看 使用额外模块构建。

一些教程可以在相应的章节中找到：GPU 加速计算机视觉 (cuda 模块)

另请参见

CUDA加速的计算机视觉

https://en.wikipedia.org/wiki/CUDA

待办：其他选项：WITH_CUFFT、WITH_CUBLAS、WITH_NVCUVID？

OpenCL 支持

WITH_OPENCL (默认: *ON*)

多个 OpenCL 加速算法可通过所谓的“透明 API (T-API)”使用。这种集成在用户级别上使用与常规 CPU 实现相同的函数。如果输入和输出图像参数作为不透明的 cv::UMat 对象传递，则切换到 OpenCL 执行分支。更多信息可在 简要介绍 和 OpenCL 支持 中找到

在构建时，此功能没有任何先决条件。在运行时，需要一个工作的 OpenCL 运行时，要检查它，请运行 clinfo 和/或 opencv_version --opencl 命令。OpenCL 集成的一些参数可以使用环境变量修改，例如 OPENCV_OPENCL_DEVICE。但是，目前还没有对此功能的详细文档，因此请查阅 modules/core/src/ocl.cpp 文件中的源代码以获取详细信息。

另请参见

https://en.wikipedia.org/wiki/OpenCL

待办：其他选项：WITH_OPENCL_SVM、WITH_OPENCLAMDFFT、WITH_OPENCLAMDBLAS、WITH_OPENCL_D3D11_NV、WITH_VA_INTEL

图像读写 (imgcodecs 模块)

内置格式

以下格式可由 OpenCV 读取，无需任何第三方库的帮助

格式	选项	默认
BMP	(总是)	ON
HDR	WITH_IMGCODEC_HDR	ON
Sun Raster	WITH_IMGCODEC_SUNRASTER	ON
PPM, PGM, PBM, PAM	WITH_IMGCODEC_PXM	ON
PFM	WITH_IMGCODEC_PFM	ON
GIF	WITH_IMGCODEC_GIF	OFF

PNG、JPEG、TIFF、WEBP、JPEG 2000、EXR、JPEG XL 支持

格式	库	选项	默认	强制构建自己的
PNG	libpng	WITH_PNG	ON	BUILD_PNG
	libspng(simple png)	WITH_SPNG	OFF	BUILD_SPNG
JPEG	libjpeg-turbo	WITH_JPEG	ON	BUILD_JPEG
	libjpeg	WITH_JPEG	OFF	BUILD_JPEG 与 BUILD_JPEG_TURBO_DISABLE
TIFF	LibTIFF	WITH_TIFF	ON	BUILD_TIFF
WebP		WITH_WEBP	ON	BUILD_WEBP
JPEG 2000	OpenJPEG	WITH_OPENJPEG	ON	BUILD_OPENJPEG
	JasPer	WITH_JASPER	ON (见备注)	BUILD_JASPER
OpenEXR		WITH_OPENEXR	ON	BUILD_OPENEXR
JPEG XL		WITH_JPEGXL	ON	不支持。(见备注)

读取这些格式图像所需的所有库都包含在 OpenCV 中，如果在配置阶段未找到，则会自动构建。相应的 BUILD_* 选项将强制构建和使用自己的库，它们在某些平台（例如 Windows）上默认启用。

注意

(所有) 每种图像格式只能启用一个库（例如，要使用 JasPer 处理 JPEG 2000 格式，必须禁用 OpenJPEG）。

(JPEG 2000) OpenJPEG 具有比已弃用的 JasPer 更高的优先级。

(JPEG XL) OpenCV 不包含 libjxl 源代码，因此不支持 BUILD_JPEGXL。

警告

OpenEXR 版本 2.2 或更早版本不能与 C++17 或更高版本结合使用。在这种情况下，需要更新 OpenEXR 版本 2.3.0 或更高版本。

GDAL 集成

WITH_GDAL (默认: *OFF*)

GDAL 是一个更高级别的库，支持读取多种文件格式，包括 PNG、JPEG 和 TIFF。它在打开文件时将具有更高的优先级，并且可以覆盖其他后端。此库将使用 cmake 包机制进行搜索，请确保已正确安装或手动设置 GDAL_DIR 环境变量或 cmake 变量。

GDCM 集成

WITH_GDCM (默认: *OFF*)

通过 GDCM 库 启用 DICOM 医学图像格式支持。此库将通过 cmake 包机制进行搜索，请确保已正确安装或手动设置 GDCM_DIR 环境变量或 cmake 变量。

视频读写 (videoio 模块)

待办：videoio 如何工作，注册表，优先级

Video4Linux

WITH_V4L (Linux; 默认: *ON* )

使用 Video4Linux API 从摄像头捕获图像。必须安装 Linux 内核头文件。

FFmpeg

WITH_FFMPEG (默认: *ON*)

与 FFmpeg 库集成，用于解码和编码视频文件以及网络流。此库可以读写许多流行的视频格式。它由几个组件组成，这些组件必须作为构建的先决条件安装

• avcodec
• avformat
• avutil
• swscale
• avresample (可选)

Windows 平台是例外，在该平台中，一个预构建的 包含 FFmpeg 的插件库 将在配置阶段下载并复制到与所有生成库相同的 bin 文件夹中。

注意

Libav 库可以替代 FFmpeg 使用，但此组合不受积极支持。

GStreamer

WITH_GSTREAMER (默认: *ON*)

启用与 GStreamer 库的集成，用于解码和编码视频文件，从摄像头和网络流捕获帧。可以安装大量插件以扩展支持的格式列表。OpenCV 允许运行作为字符串传递给 cv::VideoCapture 和 cv::VideoWriter 对象的任意 GStreamer 管道。

各种 GStreamer 插件在不同平台上提供硬件加速视频处理。

Microsoft Media Foundation

WITH_MSMF (Windows; 默认: *ON*)

启用 MSMF 后端，该后端使用 Windows 内置的 Media Foundation 框架。可用于从摄像头捕获帧，解码和编码视频文件。此后端支持硬件加速处理（WITH_MSMF_DXVA 选项，默认 *ON*）。

注意

较旧的 Windows 版本（10 之前）可能具有不兼容的 Media Foundation 版本，并且在使用 OpenCV 时已知存在问题。

DirectShow

WITH_DSHOW (Windows; 默认: *ON*)

此后端使用较旧的 DirectShow 框架。它只能用于从摄像头捕获帧。它现在已弃用，取而代之的是 MSMF 后端，尽管两者可以在同一个构建中启用。

AVFoundation

WITH_AVFOUNDATION (Apple; 默认: *ON*)

AVFoundation 框架是 Apple 平台的一部分，可用于从摄像头捕获帧，编码和解码视频文件。

其他后端

有许多不太流行的框架可用于读写视频。每个都需要安装相应的库或 SDK。

选项	默认	描述
WITH_1394	OFF	使用 DC1394 库支持 IIDC IEEE1394
WITH_OPENNI	OFF	OpenNI 可用于从深度感应摄像头捕获数据。已弃用。
WITH_OPENNI2	OFF	OpenNI2 可用于从深度感应摄像头捕获数据。
WITH_PVAPI	OFF	PVAPI 是 Prosilica GigE 摄像头的传统 SDK。已弃用。
WITH_ARAVIS	OFF	Aravis 库用于使用 Genicam 摄像头进行视频采集。
WITH_XIMEA	OFF	XIMEA 摄像头支持。
WITH_XINE	OFF	XINE 库支持。
WITH_LIBREALSENSE	OFF	RealSense 摄像头支持。
WITH_MFX	OFF	MediaSDK 库可用于对原始视频流进行硬件加速解码和编码。
WITH_GPHOTO2	OFF	GPhoto 库可用于从摄像头捕获帧。
WITH_ANDROID_MEDIANDK	ON	自 API 级别 21 起，MediaNDK 库在 Android 上可用。

videoio 插件

自 4.1.0 版本以来，一些 *videoio* 后端可以作为插件构建，从而打破了对第三方库的严格依赖，使其在运行时可选。以下选项可用于控制此机制

选项	默认	描述
VIDEOIO_ENABLE_PLUGINS	ON	完全启用或禁用插件。
VIDEOIO_PLUGIN_LIST	empty	逗号或分号分隔的后端名称列表，将作为插件编译。支持的名称有 *ffmpeg*、*gstreamer*、*msmf*、*mfx* 和 *all*。

有关独立插件构建说明，请查看 OpenCV 安装概述。

并行处理

某些 OpenCV 算法可以使用多线程来加速处理。OpenCV 可以使用其中一个线程后端进行构建。

Backend	选项	默认	Platform	描述
pthreads	WITH_PTHREADS_PF	ON	类 Unix 系统	基于 pthreads 库的默认后端在 Linux、Android 和其他类 Unix 平台上可用。线程池在 OpenCV 中实现，可以通过环境变量 OPENCV_THREAD_POOL_* 进行控制。请查看 modules/core/src/parallel_impl.cpp 文件中的源代码以获取详细信息。
Concurrency	不适用	ON	Windows	Windows 上提供 并发运行时，并且在支持的平台上将自动启用，除非启用了其他后端。
GCD	不适用	ON	Apple	Grand Central Dispatch 在 Apple 平台上可用，除非启用了其他后端，否则将自动开启。它使用全局系统线程池。
TBB	WITH_TBB	OFF	多平台	Threading Building Blocks 是一个用于并行编程的跨平台库。
OpenMP	WITH_OPENMP	OFF	多平台	OpenMP API 依赖于编译器支持。
HPX	WITH_HPX	OFF	多平台	High Performance ParallelX 是一个实验性后端，更适合多处理器环境。

注意

OpenCV 可以从 GitHub 下载和构建 TBB 库，此功能可以通过 BUILD_TBB 选项启用。

线程插件

自 4.5.2 版本以来，OpenCV 支持动态加载的线程后端。目前仅支持单独编译过程：首先您必须使用某个 *默认* 并行后端（例如 pthreads）构建 OpenCV，然后构建每个插件并将生成的二进制文件复制到 *lib* 或 *bin* 文件夹。

选项	默认	描述
PARALLEL_ENABLE_PLUGINS	ON	启用插件支持，如果此选项禁用，OpenCV 将不会尝试加载任何内容

有关独立插件构建说明，请查看 OpenCV 安装概述。

GUI 后端 (highgui 模块)

OpenCV 依赖各种 GUI 库进行窗口绘制。

选项	默认	Platform	描述
WITH_GTK	ON	Linux	GTK 是 Linux 和类 Unix 操作系统中的常用工具包。默认情况下，如果找到版本 3，则会使用版本 3；可以通过 WITH_GTK_2_X 选项强制使用版本 2。
WITH_WIN32UI	ON	Windows	WinAPI 是 Windows 中的标准 GUI API。
不适用	ON	macOS	Cocoa 是 macOS 中使用的框架。
WITH_QT	OFF	跨平台	Qt 是一个跨平台 GUI 框架。
WITH_FRAMEBUFFER	OFF	Linux	使用 Linux 帧缓冲 的实验性后端。功能有限但不需要依赖项。
WITH_FRAMEBUFFER_XVFB	OFF	Linux	启用 FRAMEBUFFER 后端的特殊输出模式，与 xvfb 工具兼容。需要一些 X11 头文件。

注意

OpenCV 编译时支持 Qt，可启用高级 highgui 接口，详情请参见 Qt 新功能。

OpenGL

WITH_OPENGL (默认: *OFF*)

OpenGL 集成可用于使用以下后端绘制硬件加速窗口：GTK、WIN32 和 Qt。并启用与 OpenGL 的基本互操作性，详情请参见 OpenGL 互操作性 和 OpenGL 支持。

highgui 插件

自 OpenCV 4.5.3 起，GTK 后端可以作为动态加载插件构建。以下选项可用于控制此机制

选项	默认	描述
HIGHGUI_ENABLE_PLUGINS	ON	完全启用或禁用插件。
HIGHGUI_PLUGIN_LIST	empty	逗号或分号分隔的后端名称列表，将作为插件编译。支持的名称有 *gtk*、*gtk2*、*gtk3* 和 *all*。

有关独立插件构建说明，请查看 OpenCV 安装概述。

深度学习神经网络推理后端和选项 (dnn 模块)

OpenCV 有自己的 DNN 推理模块，该模块拥有内置引擎，但也可以使用其他库进行优化处理。在一次构建中可以启用多个后端。选择在运行时自动或手动进行。

选项	默认	描述
WITH_PROTOBUF	ON	启用 protobuf 库搜索。OpenCV 可以构建自己的库副本，也可以使用外部库。dnn 模块需要此依赖项，如果找不到，模块将被禁用。
BUILD_PROTOBUF	ON	构建 protobuf 的自己的副本。如果您想使用外部库，则必须禁用此项。
PROTOBUF_UPDATE_FILES	OFF	重新生成所有 .proto 文件。必须安装与使用的 protobuf 版本兼容的 protoc 编译器。
OPENCV_DNN_OPENCL	ON	启用内置的 OpenCL 推理后端。
WITH_INF_ENGINE	OFF	自 OpenVINO 2022.1 起已弃用 启用 Intel Inference Engine (IE) 后端。允许执行 IE 格式的网络（.xml + .bin）。Inference Engine 必须作为 OpenVINO 工具包 的一部分安装，或者从源代码构建为独立库。
INF_ENGINE_RELEASE	2020040000	自 OpenVINO 2022.1 起已弃用 定义 Inference Engine 库的版本，该版本与 OpenVINO 工具包版本绑定。必须是 10 位字符串，例如 OpenVINO 2020.4 的 2020040000。
WITH_NGRAPH	OFF	自 OpenVINO 2022.1 起已弃用 启用 Intel NGraph 库支持。此库是 Inference Engine 后端的一部分，允许执行从 OpenCV 支持的多种格式文件（Caffe、TensorFlow、PyTorch、Darknet 等）读取的任意网络。NGraph 库必须安装，它包含在 Inference Engine 中。
WITH_OPENVINO	OFF	启用 Intel OpenVINO 工具包支持。应在 OpenVINO >= 2022.1 版本中使用，而不是 WITH_INF_ENGINE 和 WITH_NGRAPH。
OPENCV_DNN_CUDA	OFF	启用 CUDA 后端。CUDA、CUBLAS 和 CUDNN 必须安装。
WITH_HALIDE	OFF	使用实验性的 Halide 后端，该后端可以在运行时为 dnn 层生成优化代码。Halide 必须安装。
WITH_VULKAN	OFF	启用实验性 Vulkan 后端。不需要额外依赖项，但可以使用外部 Vulkan 头文件 (VULKAN_INCLUDE_DIRS)。

安装布局

安装根目录

要安装生成的二进制文件，应配置根位置。默认值取决于发行版，在 Ubuntu 中通常设置为 /usr/local。可以在配置期间更改

cmake -DCMAKE_INSTALL_PREFIX=/opt/opencv ../opencv

此路径可以是相对于当前工作目录的，在以下示例中，它将设置为 <构建的绝对路径>/install

cmake -DCMAKE_INSTALL_PREFIX=install ../opencv

构建库后，所有文件都可以使用以下命令复制到配置的安装位置

cmake --build . --target install

要以普通用户身份将二进制文件安装到系统位置（例如 /usr/local），需要以提升的权限运行上述命令

sudo cmake --build . --target install

注意

在某些平台（Linux）上，可以在安装期间删除符号信息。二进制文件将缩小 10-15%，但调试将受到限制

cmake --build . --target install/strip

组件和位置

可以使用选项来控制是否安装库的一部分

选项	默认	描述
INSTALL_C_EXAMPLES	OFF	从 *samples/cpp* 目录安装 C++ 示例源代码。
INSTALL_PYTHON_EXAMPLES	OFF	从 *samples/python* 目录安装 Python 示例源代码。
INSTALL_ANDROID_EXAMPLES	OFF	从 *samples/android* 目录安装 Android 示例源代码。
INSTALL_BIN_EXAMPLES	OFF	安装预构建的示例应用程序（必须启用 BUILD_EXAMPLES）。
INSTALL_TESTS	OFF	安装测试（必须启用 BUILD_TESTS）。
OPENCV_INSTALL_APPS_LIST	all	逗号或分号分隔的要安装的预构建应用程序列表（来自 *apps* 目录）

以下选项允许修改组件相对于安装前缀的安装位置。这些选项的默认值取决于平台和其他选项，请查阅 *cmake/OpenCVInstallLayout.cmake* 文件以获取详细信息。

选项	组件
OPENCV_BIN_INSTALL_PATH	应用程序、动态库 (win)
OPENCV_TEST_INSTALL_PATH	测试应用程序
OPENCV_SAMPLES_BIN_INSTALL_PATH	示例应用程序
OPENCV_LIB_INSTALL_PATH	动态库、导入库 (win)
OPENCV_LIB_ARCHIVE_INSTALL_PATH	静态库
OPENCV_3P_LIB_INSTALL_PATH	第三方库
OPENCV_CONFIG_INSTALL_PATH	cmake 配置包
OPENCV_INCLUDE_INSTALL_PATH	头文件
OPENCV_OTHER_INSTALL_PATH	额外数据文件
OPENCV_SAMPLES_SRC_INSTALL_PATH	示例源代码
OPENCV_LICENSES_INSTALL_PATH	包含的第三方组件的许可证
OPENCV_TEST_DATA_INSTALL_PATH	测试数据
OPENCV_DOC_INSTALL_PATH	文档
OPENCV_JAR_INSTALL_PATH	包含 Java 绑定的 JAR 文件
OPENCV_JNI_INSTALL_PATH	Java 绑定的 JNI 部分
OPENCV_JNI_BIN_INSTALL_PATH	来自 Java 绑定 JNI 部分的动态库

以下选项可用于更改常见场景的安装布局

选项	默认	描述
INSTALL_CREATE_DISTRIB	OFF	调整多项内容以生成 Windows 和 Android 发行版。
INSTALL_TO_MANGLED_PATHS	OFF	在几个安装位置添加一层目录，以允许并排安装。例如，启用此选项后，头文件将安装到 _/usr/include/opencv-4.4.0_ 而不是 _/usr/include/opencv4_。

杂项功能

选项	默认	描述
OPENCV_ENABLE_NONFREE	OFF	库中包含的一些算法已知受专利保护，默认禁用。
OPENCV_FORCE_3RDPARTY_BUILD	OFF	一次性启用所有 BUILD_ 选项。
OPENCV_IPP_ENABLE_ALL	OFF	一次性启用所有 OPENCV_IPP_ 选项。
ENABLE_CCACHE	ON (在类 Unix 平台上)	启用 ccache 自动检测。此工具封装了编译器调用并缓存结果，可以显著提高重新编译时间。
ENABLE_PRECOMPILED_HEADERS	ON (对于 MSVC)	启用预编译头文件支持。提高构建时间。
BUILD_DOCS	OFF	启用文档构建（doxygen、doxygen_cpp、doxygen_python、doxygen_javadoc 目标）。C++ 文档构建必须安装 Doxygen。Python 文档构建必须安装 Python 和 BeautifulSoup4。Java 文档构建（Java SDK 的一部分）必须安装 Javadoc 和 Ant。
ENABLE_PYLINT	ON (当文档或示例启用时)	启用使用 Pylint 进行 Python 脚本检查（check_pylint 目标）。必须安装 Pylint。
ENABLE_FLAKE8	ON (当文档或示例启用时)	启用使用 Flake8 进行 Python 脚本检查（check_flake8 目标）。必须安装 Flake8。
BUILD_JAVA	ON	构建 Java 包装器。必须安装 Java SDK 和 Ant。
BUILD_FAT_JAVA_LIB	ON (对于静态 Android 构建)	构建单个 opencv_java 动态库，包含所有库功能和 Java 绑定。
BUILD_opencv_python2	ON	构建 python2 绑定（已弃用）。必须安装带有开发文件和 numpy 的 Python。
BUILD_opencv_python3	ON	构建 python3 绑定。必须安装带有开发文件和 numpy 的 Python。

待办：需要单独的教程来介绍绑定构建

自动化构建

已添加一些功能专门用于自动化构建环境，例如持续集成和打包系统。

选项	默认	描述
ENABLE_NOISY_WARNINGS	OFF	启用几个被认为是 *嘈杂* 的编译器警告，即重要性低于其他警告。这些警告通常会被忽略，但在某些情况下值得检查。
OPENCV_WARNINGS_ARE_ERRORS	OFF	将编译器警告视为错误。构建将停止。
ENABLE_CONFIG_VERIFICATION	OFF	对于每个已启用的依赖项（WITH_ 选项），验证它是否已找到并启用（HAVE_ 变量）。默认情况下，如果未找到依赖项，该功能将静默关闭，但启用此选项后，cmake 配置将失败。这对于需要稳定库配置而不受环境波动影响的打包系统非常方便。
OPENCV_CMAKE_HOOKS_DIR	empty	OpenCV 允许通过在每个阶段和子阶段添加自定义钩子脚本来自定义配置过程。在此变量设置的目录中，具有预定义名称的 cmake 脚本将在各种配置阶段之前和之后包含。文件名的示例：CMAKE_INIT.cmake、PRE_CMAKE_BOOTSTRAP.cmake、POST_CMAKE_BOOTSTRAP.cmake 等。其他名称未文档化，可以通过搜索 ocv_cmake_hook 宏调用在项目 cmake 文件中找到。
OPENCV_DUMP_HOOKS_FLOW	OFF	在每次 cmake 钩子脚本调用时启用调试消息打印。

Contrib 模块

以下构建选项用于 opencv_contrib 模块，如 前述 所述，这些额外模块可以通过设置 DOPENCV_EXTRA_MODULES_PATH 选项添加到您的最终构建中。

选项	默认	描述
WITH_CLP	OFF	将添加 coinor 线性规划库构建支持，这是 videostab 模块所需的。请确保安装 coinor-clp 的开发库。

其他未文档化选项

BUILD_ANDROID_PROJECTS BUILD_ANDROID_EXAMPLES ANDROID_HOME ANDROID_SDK ANDROID_NDK ANDROID_SDK_ROOT

CMAKE_TOOLCHAIN_FILE

WITH_CAROTENE WITH_KLEIDICV WITH_CPUFEATURES WITH_EIGEN WITH_OPENVX WITH_DIRECTX WITH_VA WITH_LAPACK WITH_QUIRC BUILD_ZLIB BUILD_ITT WITH_IPP BUILD_IPP_IW