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.org/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