OpenCVのインストール概要

目次

• Prebuilt version
  • OpenCVコアチームによるパッケージ
  • サードパーティ製パッケージ
• Build from sources
  • ステップ0: 前提条件
  • ステップ1: ソフトウェアのソースを取得する
  • ステップ2: 構成（Configure）
  • ステップ3: ビルド
  • （省略可能）ステップ3: インストール
  • （省略可能）ステップ4: プラグインのビルド

次のチュートリアル: OpenCV構成オプションリファレンス

OpenCVをマシンにインストールする方法は2通りある。プラットフォーム向けのビルド済みバージョンをダウンロードするか、ソースからコンパイルするかである。

ビルド済みバージョン

多くの場合、用途に合ったOpenCVのビルド済みバージョンを見つけられる。

OpenCVコアチームによるパッケージ

Android、iOS、Windows向けに、デフォルトの引数と最新のコンパイラでビルドされたパッケージが各リリースごとに公開されている。これらには opencv_contrib モジュールは含まれていない。

• GitHubリリース: https://github.com/opencv/opencv/releases
• SourceForge.net: https://sourceforge.net/projects/opencvlibrary/files/

サードパーティ製パッケージ

他の組織や個人もそれぞれ独自のOpenCVバイナリ配布物を保守している。例えば次のものがある:

• 主要なLinuxディストリビューションのシステムパッケージ (https://pkgs.org/search/?q=opencv)
• PyPI (https://pypi.org/search/?q=opencv)
• Conda (https://anaconda.org/search?q=opencv)
• Conan (https://conan.io/center/recipes/opencv)
• vcpkg (https://github.com/microsoft/vcpkg/tree/master/ports/opencv)
• NuGet (https://www.nuget.org/packages?q=opencv)
• Brew (https://formulae.brew.sh/formula/opencv)
• Maven (https://search.maven.org/search?q=opencv)

ソースからビルドする

既存のバイナリパッケージが用途に適さない場合がある。その際は自分でカスタムバージョンのOpenCVをビルドする必要がある。このセクションではビルド処理の概要を説明する。実際のビルド手順については各プラットフォーム向けのチュートリアルを参照すること。

OpenCVは設定とビルドに CMake ビルド管理システムを使用する。そのためこのセクションでは主にCMakeを使ったソフトウェアのビルドの一般的な流れを説明する。

ステップ0: 前提条件

C++コンパイラとビルドツールをインストールする。*NIXプラットフォームでは通常GCC/G++またはClangコンパイラと、MakeまたはNinjaビルドツールである。WindowsではVisual Studio IDEまたはMinGW-w64コンパイラが利用できる。Android向けのネイティブツールチェーンはAndroid NDKで提供される。OSXおよびiOSプラットフォーム向けのソフトウェアのビルドにはXCode IDEを使用する。

公式サイトまたはその他のソースからCMakeをインストールする。

その他のサードパーティ依存物を入手する: 動画のデコードやGUI要素の表示といった追加機能を提供するライブラリ、特定アルゴリズムの最適化実装を提供するライブラリ、ドキュメント生成などに使うツールなどである。利用可能なオプションと対応する依存物については OpenCV設定オプションリファレンス を確認すること。

ステップ1: ソフトウェアのソースを入手する

一般的なソフトウェアプロジェクトは1つまたは複数のコードリポジトリで構成される。OpenCVにはコードを含む2つのリポジトリがある: opencv は安定して継続的にサポートされるアルゴリズムを含むメインリポジトリ、opencv_contrib は実験的なアルゴリズムや非フリー(特許対象)のアルゴリズムを含む。さらにテストデータを含むリポジトリ opencv_extra がある。

リポジトリのスナップショットをアーカイブの形でダウンロードするか、全履歴を含めてリポジトリをクローンできる。

スナップショットアーカイブをダウンロードするには:

• https://github.com/opencv/opencv/releases にアクセスし、任意のリリースから「Source code」アーカイブをダウンロードする。
• (任意) https://github.com/opencv/opencv_contrib/releases にアクセスし、opencv と同じリリースの「Source code」アーカイブをダウンロードする
• (任意) https://github.com/opencv/opencv_extra/releases にアクセスし、opencv と同じリリースの「Source code」アーカイブをダウンロードする
• すべてのアーカイブを任意の場所に展開する

リポジトリをクローンするには、コンソールで次のコマンドを実行する (git が インストールされている必要がある):

git clone https://github.com/opencv/opencv
git -C opencv checkout <some-tag>
 
# optionally
git clone https://github.com/opencv/opencv_contrib
git -C opencv_contrib checkout <same-tag-as-opencv>
 
# optionally
git clone https://github.com/opencv/opencv_extra
git -C opencv_extra checkout <same-tag-as-opencv>

覚え書き

複数のリポジトリを使ってソフトウェアをビルドする場合は、すべてのコンポーネントが互いに互換性があることを確認すること。OpenCVの場合、これは opencv と opencv_contrib のリポジトリが同じタグでチェックアウトされていること、またはすべてのスナップショットアーカイブが同じリリースからダウンロードされていることを意味する。

ダウンロードするバージョンを選ぶ際は、ターゲットプラットフォームと開発ツールのバージョンを考慮すること。OpenCVの最新バージョンは非常に古いコンパイラではビルドに問題が生じることがあり、その逆も同様である。最新リリースと新しいOS/コンパイラの組み合わせを使うことを推奨する。

ステップ2: 設定

このステップでは、CMakeが必要なツールと依存物がすべて利用可能でライブラリと互換性があることを検証し、選択したビルドシステム向けの中間ファイルを生成する。これはMakefile、IDEプロジェクトやソリューションなどになりうる。通常、このステップは新しく作成したビルドディレクトリ内で実行する:

cmake -G<generator> <configuration-options> <source-directory>

覚え書き

cmake-gui アプリケーションを使うと、グラフィカルユーザーインターフェイスで利用可能なオプションを確認・変更できる。詳細は https://cmake.org/runningcmake/ を参照すること。

ステップ3: ビルド

ビルド処理では、ソースファイルがオブジェクトファイルにコンパイルされ、それらがリンクまたは結合されてライブラリやアプリケーションが生成される。このステップは汎用的なコマンドで実行できる:

cmake --build <build-directory> <build-options>

... あるいは、背後のビルドシステムを直接呼び出すこともできる:

make

(任意) ステップ3: インストール

インストール手順では、ビルド結果やビルドディレクトリ内のその他のファイルがインストール先にコピーされる。デフォルトのインストール先はUNIXでは /usr/local、Windowsでは C:/Program Files である。この場所は設定ステップで CMAKE_INSTALL_PREFIX オプションを設定することで変更できる。インストールを実行するには次のコマンドを実行する:

cmake --build <build-directory> --target install <other-options>

覚え書き

このステップは任意であり、OpenCVはビルドディレクトリから直接利用できる。

インストール先のルートが保護されたシステムディレクトリの場合、インストール処理はスーパーユーザーまたは管理者権限で実行する必要がある (例: sudo cmake ...)。

(任意) ステップ4: プラグインのビルド

コードの一部を動的に読み込まれるプラグインとして切り出すことで、OpenCVの一部の依存物を切り離して省略可能にできる。これにより、より少ない依存物のシステムでも動作し、不足するライブラリをインストールするだけで機能を拡張できる適応的なバイナリ配布物を作成できる。現時点では core、videoio、highgui モジュールが一部の依存物についてこの仕組みをサポートしている。場合によっては、VIDEOIO_PLUGIN_LIST や HIGHGUI_PLUGIN_LIST のようなオプションを設定することで、プラグインをOpenCVと一緒にビルドできる。このシナリオに関連するオプションは OpenCV設定オプションリファレンス で確認できる。それ以外の場合、プラグインは独自のビルド手順で個別にビルドする必要があり、このセクションではそのようなスタンドアロンのビルド処理を説明する。

覚え書き

OpenCVのビルドに使用したものと互換性のあるコンパイラ、設定、ビルドオプションを使用することを推奨する。さもないと、できあがったライブラリが読み込みを拒否したり、その他の実行時の問題を引き起こしたりすることがある。バックエンドを動的に読み込む場合、OpenCVと対応するサードパーティライブラリの間に余分な障壁が生じるため、一部の機能が制限されたり動作が遅くなったりすることがある点に注意すること。

ビルド手順はメインのOpenCVビルドと同様だが、対応するサブディレクトリにある専用のCMakeプロジェクトを使う必要がある。これらのフォルダにはリファレンス用のスクリプトやDockerイメージも含まれていることがある。ローダーがプラグインを見つけられるように、プラグインには opencv_<module>_<backend> という名前のプレフィックスを使うことが重要である。サポートされる各プレフィックスは1つのライブラリの読み込みにのみ使えるが、1つのプレフィックスに対して複数の候補を試すことができる。例えば libopencv_videoio_ffmpeg_3.so と libopencv_videoio_ffmpeg_4.so のプラグインを用意でき、最初に正常に読み込めたものが内部スロットを占有し、探索処理を停止する。利用可能なプレフィックスとプロジェクトの場所を次の表に示す:

module	backends	location
core	parallel_tbb, parallel_onetbb, parallel_openmp	opencv/modules/core/misc/plugins
highgui	gtk, gtk2, gtk3	opencv/modules/highgui/misc/plugins
videoio	ffmpeg, gstreamer, intel_mfx, msmf	opencv/modules/videoio/misc

例:

# set-up environment for TBB detection, for example:
#   export TBB_DIR=<dir-with-tbb-cmake-config>
cmake -G<generator> \
    -DOPENCV_PLUGIN_NAME=opencv_core_tbb_<suffix> \
    -DOPENCV_PLUGIN_DESTINATION=<dest-folder> \
    -DCMAKE_BUILD_TYPE=<config> \
    <opencv>/modules/core/misc/plugins/parallel_tbb
cmake --build . --config <config>

覚え書き

Windowsでは、プラグインは既存のOpenCVビルドとリンクする必要がある。OpenCV_DIR 環境変数またはCMake変数を OpenCVConfig.cmake ファイルのあるディレクトリに設定する。これはOpenCVのビルドディレクトリ、またはインストールを行った場所のパスでありうる。