OpenCV設定オプションリファレンス

目次

• はじめに
• General options
  • 追加モジュールを含めてビルドする
  • C++ 標準設定でビルドする
  • デバッグビルド
  • 静的ビルド
  • pkg-config 情報を生成する
  • テスト・サンプル・アプリケーションをビルドする
  • 限定されたモジュール群をビルドする
  • ダウンロードされた依存関係
  • CPU 最適化レベル
  • プロファイリング、カバレッジ、サニタイズ、ハードニング、サイズ最適化
  • IPP 最適化を有効にする
• Functional features and dependencies
  • オプションの命名規則
  • Heterogeneous computation
    • CUDA サポート
    • OpenCL サポート
  • Image reading and writing (imgcodecs module)
    • 組み込み形式
    • PNG, JPEG, TIFF, WEBP, JPEG 2000, EXR, JPEG XL サポート
    • GDAL 連携
    • GDCM 連携
  • Video reading and writing (videoio module)
    • Video4Linux
    • FFmpeg
    • GStreamer
    • Microsoft Media Foundation
    • DirectShow
    • AVFoundation
    • その他のバックエンド
    • videoio プラグイン
  • Parallel processing
    • スレッディングプラグイン
  • GUI backends (highgui module)
    • OpenGL
    • highgui プラグイン
  • ディープラーニングニューラルネットワークの推論バックエンドとオプション (dnn モジュール)
• Installation layout
  • インストールルート
  • コンポーネントと配置場所
• Miscellaneous features
  • 自動ビルド
  • Contrib モジュール
• その他のドキュメント化されていないオプション

前のチュートリアル: OpenCV インストールの概要
次のチュートリアル: OpenCV 環境変数リファレンス

はじめに

覚え書き

OpenCV インストールの概要 のチュートリアルを読んでいるか、CMake の経験があることを前提とする。

設定オプションはいくつかの異なる方法で設定できる:

• コマンドライン: cmake -Doption=value ...
• 初期キャッシュファイル: cmake -C my_options.txt ...
• GUIによる対話的操作

本リファレンスでは通常のコマンドラインを用いる。

ほとんどのオプションはOpenCVのルートにあるcmakeスクリプト opencv/CMakeLists.txt に記載されている。一部のオプションは個別のモジュール内で定義されている場合もある。

CMakeツールを使って、利用可能な全オプションを表示することもできる:

# initial configuration
cmake ../opencv
 
# print all options
cmake -L
 
# print all options with help message
cmake -LH
 
# print all options including advanced
cmake -LA

最もよく使われる有用なオプションは、WITH_、ENABLE_、BUILD_、OPENCV_ で始まるものである。

デフォルト値はプラットフォームや他のオプションの値によって異なる。

一般オプション

追加モジュールつきでビルドする

OPENCV_EXTRA_MODULES_PATH オプションには、ビルドに追加する追加モジュールを含むディレクトリのリストをセミコロン区切りで指定する。モジュールのディレクトリは互換性のあるレイアウトとCMakeLists.txtを持つ必要がある。簡単な説明は Coding Style Guide を参照のこと。

例:

# build with all modules in opencv_contrib
cmake -DOPENCV_EXTRA_MODULES_PATH=../opencv_contrib/modules ../opencv
 
# build with one of opencv_contrib modules
cmake -DOPENCV_EXTRA_MODULES_PATH=../opencv_contrib/modules/bgsegm ../opencv
 
# build with two custom modules (semicolon must be escaped in 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 .

• OpenCV 4.xではC++11がデフォルト/必須/推奨である。OpenCV 5.xではC++17がデフォルト/必須/推奨である。
• 使用するコンパイラが要求されるC++標準規格の機能をサポートしていない場合、OpenCVの構成は失敗するはずである。
• 要求される規格より古いC++標準規格を設定すると、OpenCVの構成は失敗するはずである。回避策として、OPENCV_SKIP_CMAKE_CXX_STANDARD オプションを使い CMAKE_CXX_STANDARD のバージョンチェックをスキップできる。
• 推奨より新しいC++標準規格を設定すると、多数の警告が出るか、OpenCVのビルドが失敗することがある。

デバッグビルド

CMAKE_BUILD_TYPE オプションを使うとデバッグビルドを有効化できる。生成されるバイナリにはデバッグシンボルが含まれ、コンパイラの最適化のほとんどが無効になる。Releaseビルドでデバッグシンボルを有効にするには、BUILD_WITH_DEBUG_INFO オプションをオンにする。

一部のプラットフォーム(例: Linux)では、ビルドタイプを構成段階で設定する必要がある:

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

他のプラットフォーム(例: Visual Studio、XCode)では、同じビルドディレクトリで異なるタイプのビルドを生成できる:

cmake <options> ../opencv
cmake --build . --config Debug

GNU libstdc++(GCCのデフォルト)を使う場合、ENABLE_GNU_STL_DEBUG オプションをオンにすると、C++ライブラリがDebugモードで使われる。例えばベクトルの要素アクセス時にインデックスの境界チェックが行われる。

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 オプションを設定する。これは「位置独立コード(position-independent code)」の生成を有効または無効にする。このオプションは、動的ライブラリ、または動的ライブラリにリンクすることを意図した静的ライブラリをビルドする際には有効にする必要がある。デフォルト値は ON である。

参照

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

pkg-config情報の生成

OPENCV_GENERATE_PKGCONFIG オプションは、標準のCMakeパッケージに加えて .pc ファイルの生成を有効にする。このファイルは、ビルドにCMakeを使わないプロジェクトにとって有用である。

例:

cmake -DOPENCV_GENERATE_PKGCONFIG=ON ../opencv

覚え書き

構成処理が複雑なため、生成される .pc ファイルにはサードパーティ依存関係のリストが不完全に含まれることがあり、特に静的ビルドでは一部の構成で機能しない場合がある。この機能は4.x以降は公式にはサポートされておらず、デフォルトでは無効である。

テスト、サンプル、アプリケーションのビルド

テストには2種類ある: 精度テスト(opencv_test_*)とパフォーマンステスト(opencv_perf_*)である。テストとアプリケーションはデフォルトで有効になっている。サンプルはデフォルトではビルドされず、明示的に有効にする必要がある。

対応する cmake オプション:

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

限定したモジュールセットのビルド

各モジュールは modules ディレクトリのサブディレクトリである。1つのモジュールを無効にすることもできる:

cmake -DBUILD_opencv_calib3d=OFF ../opencv

逆のオプションとして、指定したモジュールとそれが依存する全モジュールのみをビルドすることもできる:

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

この例では3つのモジュールを要求しており、構成スクリプトが全依存関係を自動的に判定している:

--   OpenCV modules:
--     To be built:                 calib3d core features2d flann highgui imgcodecs imgproc ts videoio

ダウンロードされる依存関係

構成スクリプトは、追加のライブラリやファイルをインターネットからダウンロードしようとする場合がある。失敗した場合は対応する機能が無効になる。場合によっては構成エラーが発生することもある。デフォルトでは、すべてのファイルがまず <source>/.cache ディレクトリにダウンロードされ、その後ビルドディレクトリに展開またはコピーされる。環境変数または構成オプションを設定することで、ダウンロードキャッシュの場所を変更できる:

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

プロキシ経由でアクセスする場合は、cmakeを実行する前に対応する環境変数を設定する必要がある:

export http_proxy=<proxy-host>:<port>
export https_proxy=<proxy-host>:<port>

ダウンロード処理の完全なログは、ビルドディレクトリ内の CMakeDownloadLog.txt にある。さらに、ダウンロードに失敗するたびに、ビルドディレクトリ内のヘルパースクリプト(例: download_with_wget.sh)にコマンドが追加される。ユーザーはこれらのスクリプトをそのまま実行することも、必要に応じて変更することもできる。

CPU最適化レベル

x86_64マシンでは、ライブラリはデフォルトでSSE3命令セットレベル向けにコンパイルされる。このレベルは構成オプションで変更できる:

cmake -DCPU_BASELINE=AVX2 ../opencv

覚え書き

他のプラットフォームにはそれぞれ独自の命令セットレベルがある: ARMでは VFPV3 と NEON、PowerPCでは VSX である。

一部の関数はディスパッチ機構をサポートしており、複数の命令セット向けにコンパイルし、実行時にいずれか1つを選択できる。有効にする命令セットのリストは構成時に変更できる:

cmake -DCPU_DISPATCH=AVX,AVX2 ../opencv

ディスパッチ機構を無効にするには、このオプションを空の値に設定する:

cmake -DCPU_DISPATCH= ../opencv

トラブルシューティングやデバッグのために、最適化されたコード部分を無効にすることもできる:

# disable universal intrinsics
cmake -DCV_ENABLE_INTRINSICS=OFF ../opencv
# disable all possible built-in optimizations
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	N/A	メモリサニタイザを補助するためのコード中のいくつかの調整を有効にする。
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

オプションの命名規則

ライブラリの依存関係を制御するオプションには3種類あり、それぞれ異なる接頭辞を持つ:

• 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 を一緒にビルドするには Build with extra modules を参照のこと。

いくつかのチュートリアルは対応するセクションにある: GPUアクセラレーションによるコンピュータビジョン (cudaモジュール)

参照

CUDA で高速化したコンピュータビジョン

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

TODO: その他のオプション: WITH_CUFFT, WITH_CUBLAS, WITH_NVCUVID?

OpenCLサポート

WITH_OPENCL (デフォルト: ON)

いわゆる「Transparent API (T-API)」を通じて、複数のOpenCL高速化アルゴリズムが利用可能である。この統合では、通常の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

TODO: その他のオプション: 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	ON

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など一部のプラットフォームではデフォルトで有効になっている。

覚え書き

(すべて) 各画像フォーマットに対して有効にできるライブラリは1つだけである(例: JPEG 2000フォーマットでJasPerを使うには、OpenJPEGを無効にする必要がある)。

(JPEG 2000) OpenJPEGは、非推奨のJasPerより優先度が高い。

(JPEG XL) OpenCVはlibjxlのソースコードを含まないため、BUILD_JPEGXL はサポートされない。

警告

OpenEXR ver 2.2 以前は、C++17 以降と組み合わせて使用できない。この場合、OpenEXR ver 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モジュール)

TODO: videoioの仕組み、レジストリ、優先度

Video4Linux

WITH_V4L (Linux; デフォルト: ON )

Video4Linux APIを使ってカメラから画像をキャプチャする。Linuxカーネルヘッダがインストールされている必要がある。

FFmpeg

WITH_FFMPEG (デフォルト: ON)

動画ファイルやネットワークストリームのデコード・エンコードを行う FFmpeg ライブラリとの統合。このライブラリは多くの人気のある動画フォーマットを読み書きできる。これはいくつかのコンポーネントで構成されており、ビルドの前提条件としてインストールする必要がある:

• avcodec
• avformat
• avutil
• swscale
• avresample (省略可能)

例外はWindowsプラットフォームであり、設定段階で FFmpegを含むプリビルドのプラグインライブラリ がダウンロードされ、生成されたすべてのライブラリとともに bin フォルダにコピーされる。

覚え書き

FFmpegの代わりに Libav ライブラリを使用できるが、この組み合わせは積極的にはサポートされていない。

GStreamer

WITH_GSTREAMER (デフォルト: ON)

動画ファイルのデコード・エンコード、カメラやネットワークストリームからのフレームキャプチャを行う GStreamer ライブラリとの統合を有効にする。サポートするフォーマットのリストを拡張するために、多数のプラグインをインストールできる。OpenCVでは、文字列として渡された任意のGStreamerパイプラインを cv::VideoCapture および cv::VideoWriter オブジェクトで実行できる。

さまざまなGStreamerプラグインが、異なるプラットフォーム上でハードウェア高速化された動画処理を提供する。

Microsoft Media Foundation

WITH_MSMF (Windows; デフォルト: ON)

Windows組み込みの Media Foundationフレームワーク を使用するMSMFバックエンドを有効にする。カメラからのフレームキャプチャ、動画ファイルのデコード・エンコードに使用できる。このバックエンドはハードウェア高速化処理をサポートする(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	MediaNDK ライブラリはAPIレベル21以降のAndroidで利用可能である。

videoioプラグイン

バージョン4.1.0以降、一部の videoio バックエンドはプラグインとしてビルドでき、サードパーティライブラリへの厳密な依存を解消し、実行時に省略可能にできる。この機構を制御するには次のオプションを使用できる:

オプション	デフォルト	説明
VIDEOIO_ENABLE_PLUGINS	ON	プラグインを完全に有効化または無効化する。
VIDEOIO_PLUGIN_LIST	空	プラグインとしてコンパイルするバックエンド名をカンマまたはセミコロンで区切ったリスト。サポートされる名前は ffmpeg, gstreamer, msmf, mfx, all である。

スタンドアロンプラグインのビルド手順については OpenCVのインストール概要 を確認すること。

並列処理

OpenCVのアルゴリズムの一部は、マルチスレッドを使って処理を高速化できる。OpenCVは、いずれかのスレッディングバックエンドを使ってビルドできる。

バックエンド	オプション	デフォルト	プラットフォーム	説明
pthreads	WITH_PTHREADS_PF	ON	Unix系	pthreads ライブラリに基づくデフォルトバックエンドは、Linux、Android、その他のUnix系プラットフォームで利用可能である。スレッドプールはOpenCV内に実装されており、環境変数 OPENCV_THREAD_POOL_* で制御できる。詳細は modules/core/src/parallel_impl.cpp ファイル内のソースを参照のこと。
Concurrency	N/A	ON	Windows	Concurrency runtime はWindowsで利用可能であり、他のバックエンドが有効化されていない限り、サポートされているプラットフォームではONになる。
GCD	N/A	ON	Apple	Grand Central Dispatch はAppleプラットフォームで利用可能であり、他のバックエンドが有効化されていない限り、自動的にONになる。グローバルなシステムスレッドプールを使用する。
TBB	WITH_TBB	OFF	Multiple	Threading Building Blocks は並列プログラミング向けのクロスプラットフォームライブラリである。
OpenMP	WITH_OPENMP	OFF	Multiple	OpenMP APIはコンパイラのサポートに依存する。
HPX	WITH_HPX	OFF	Multiple	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ライブラリに依存している。

オプション	デフォルト	プラットフォーム	説明
WITH_GTK	ON	Linux	GTK はLinuxやUnix系OSで一般的なツールキットである。デフォルトでは、見つかればバージョン3が使用され、WITH_GTK_2_X オプションでバージョン2を強制することができる。
WITH_WIN32UI	ON	Windows	WinAPI はWindowsにおける標準的なGUI APIである。
N/A	ON	macOS	Cocoa はmacOSで使用されるフレームワークである。
WITH_QT	OFF	Cross-platform	Qt はクロスプラットフォームのGUIフレームワークである。
WITH_FRAMEBUFFER	OFF	Linux	Linux framebuffer を使用する実験的なバックエンド。機能は限定的だが、依存関係を必要としない。
WITH_FRAMEBUFFER_XVFB	OFF	Linux	xvfb ツールと互換性のあるFRAMEBUFFERバックエンドの特別な出力モードを有効にする。いくつかのX11ヘッダを必要とする。

覚え書き

Qtサポート付きでコンパイルされたOpenCVは、高度な 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	空	プラグインとしてコンパイルするバックエンド名のカンマまたはセミコロン区切りのリスト。サポートされている名前は gtk、gtk2、gtk3、all である。

スタンドアロンプラグインのビルド手順については OpenCVのインストール概要 を確認すること。

ディープラーニングニューラルネットワーク推論のバックエンドとオプション (dnnモジュール)

OpenCVには独自のDNN推論モジュールがあり、独自の組み込みエンジンを備えているが、最適化された処理のために他のライブラリも使用できる。1つのビルドで複数のバックエンドを有効にできる。選択は実行時に自動的に、または手動で行われる。

オプション	デフォルト	説明
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 toolkit の一部として、またはソースからビルドしたスタンドアロンライブラリとしてインストールされている必要がある。
INF_ENGINE_RELEASE	2020040000	OpenVINO 2022.1以降は非推奨 OpenVINO toolkitのバージョンに紐づくInference Engineライブラリのバージョンを定義する。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 Toolkitのサポートを有効にする。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

このパスは現在の作業ディレクトリからの相対パスにできる。次の例では <absolute-path-to-build>/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 ファイルを参照のこと。

オプション	Components
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	複数のインストール先に1階層を追加し、サイドバイサイドインストールを可能にする。例えば、このオプションを有効にすると、ヘッダは _/usr/include/opencv4_ ではなく _/usr/include/opencv-4.4.0_ にインストールされる。

その他の機能

オプション	デフォルト	説明
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ドキュメントのビルドには JavadocとAnt(Java SDKの一部)がインストールされている必要がある。
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ビルドの場合)	Javaバインディングとバンドルされたすべてのライブラリ機能を含む単一の opencv_java 動的ライブラリをビルドする。
BUILD_opencv_python2	ON	python2バインディングをビルドする(非推奨)。開発ファイル付きのPythonとnumpyがインストールされている必要がある。
BUILD_opencv_python3	ON	python3バインディングをビルドする。開発ファイル付きのPythonとnumpyがインストールされている必要がある。

TODO: バインディングのビルドを扱う独立したチュートリアルが必要

自動ビルド

継続的インテグレーションやパッケージングシステムなど、自動ビルド環境向けに特化して追加された機能がいくつかある。

オプション	デフォルト	説明
ENABLE_NOISY_WARNINGS	OFF	noisy、すなわち他のものより重要度が低いとみなされるいくつかのコンパイラ警告を有効にする。これらの警告は通常無視されるが、場合によっては確認する価値がある。
OPENCV_WARNINGS_ARE_ERRORS	OFF	コンパイラの警告をエラーとして扱う。ビルドは停止される。
ENABLE_CONFIG_VERIFICATION	OFF	有効化された各依存関係(WITH_オプション)について、それが検出され有効化されていること(HAVE_変数)を検証する。デフォルトでは依存関係が見つからない場合に機能は警告なく無効化されるが、このオプションを有効にするとcmakeの構成が失敗する。環境の変動に依存しない安定したライブラリ構成を必要とするパッケージングシステムに便利である。
OPENCV_CMAKE_HOOKS_DIR	空	OpenCVでは、各ステージおよびサブステージにカスタムフックスクリプトを追加することで構成プロセスをカスタマイズできる。この変数で設定されたディレクトリに配置された、定義済みの名前を持つcmakeスクリプトが、さまざまな構成ステージの前後にインクルードされる。ファイル名の例: CMAKE_INIT.cmake、PRE_CMAKE_BOOTSTRAP.cmake、POST_CMAKE_BOOTSTRAP.cmakeなど。その他の名前は文書化されておらず、プロジェクトのcmakeファイル内でocv_cmake_hookマクロの呼び出しを検索することで見つけられる。
OPENCV_DUMP_HOOKS_FLOW	OFF	各cmakeフックスクリプトの呼び出し時にデバッグメッセージの出力を有効にする。

Contribモジュール

以下のビルドオプションは opencv_contrib モジュールで利用される。前述のとおり、これらの追加モジュールは DOPENCV_EXTRA_MODULES_PATH オプションを設定することで最終ビルドに追加できる。

オプション	デフォルト	説明
WITH_CLP	OFF	videostabモジュールで必要となるcoinor線形計画ライブラリのビルドサポートを追加する。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