OpenCV + opencv_contrib を Ubuntu でビルドする完全ガイド【C++】

OpenCV for C++
📌 準備: OpenCV の環境構築がまだの方はこちら → C++ 環境構築ガイド ／ C#（OpenCvSharp）セットアップ

OpenCV + opencv_contrib を Ubuntu でビルドする完全ガイド【C++】

apt でインストールできる OpenCV には opencv_contrib モジュールが含まれていません。SIFT・SURF・structured edge detection など contrib 専用のアルゴリズムを C++ で使うには、ソースからビルドする必要があります。

この記事を読むと、Ubuntu 上で OpenCV 本体と opencv_contrib を同時にビルドし、C++ から cv::xfeatures2d::SIFT などの contrib API を呼び出せる状態になります。

前提環境

項目 バージョン
OS Ubuntu 22.04 LTS / 24.04 LTS
OpenCV 4.10.x（現行安定版）
opencv_contrib OpenCV 本体と同一タグ
CMake 3.16 以上
コンパイラ GCC 11 以上（C++17 対応）
ビルドツール make または ninja

⚠️ OpenCV 本体と opencv_contrib は必ず同じバージョンタグを使います。バージョンが異なるとビルドエラーになります。

手順

1. 既存パッケージの確認と削除

apt 版 OpenCV が混在するとヘッダ・ライブラリの競合が起きます。事前に削除しておきます。

sudo apt remove libopencv-dev python3-opencv
sudo apt autoremove

2. 依存パッケージのインストール

sudo apt update
sudo apt install -y \
  build-essential cmake git pkg-config \
  libjpeg-dev libpng-dev libtiff-dev \
  libavcodec-dev libavformat-dev libswscale-dev \
  libgtk-3-dev \
  libatlas-base-dev gfortran \
  libeigen3-dev \
  wget unzip

✅ 映像入出力（ffmpeg 系）や GUI 表示（GTK）が不要な場合はそれぞれ省略できますが、後から追加するには再ビルドが必要です。最初にまとめて入れておくことを推奨します。

3. ソースコードの取得

OpenCV 公式リポジトリから本体と contrib を取得します。ダウンロード先は必ず公式サイト（opencv.org/releases/ / github.com/opencv/opencv_contrib）を参照してください。

# バージョンを変数に入れておくと管理しやすい
OPENCV_VERSION=4.10.0

cd ~
git clone --depth 1 --branch ${OPENCV_VERSION} https://github.com/opencv/opencv.git
git clone --depth 1 --branch ${OPENCV_VERSION} https://github.com/opencv/opencv_contrib.git

--depth 1 を付けることでクローン時間を大幅に短縮できます。

4. ビルドディレクトリの作成と CMake 設定

mkdir ~/opencv/build
cd ~/opencv/build

cmake \
  -D CMAKE_BUILD_TYPE=Release \
  -D CMAKE_INSTALL_PREFIX=/usr/local \
  -D OPENCV_EXTRA_MODULES_PATH=~/opencv_contrib/modules \
  -D OPENCV_ENABLE_NONFREE=ON \
  -D BUILD_EXAMPLES=OFF \
  -D BUILD_TESTS=OFF \
  -D BUILD_PERF_TESTS=OFF \
  -D WITH_FFMPEG=ON \
  -D WITH_GTK=ON \
  ..

主要オプション解説

オプション 意味
OPENCV_EXTRA_MODULES_PATH contrib モジュールのパス。これが本質
OPENCV_ENABLE_NONFREE=ON SIFT・SURF など特許関連アルゴリズムを有効化
BUILD_EXAMPLES=OFF サンプルのビルドをスキップ（時間短縮）
CMAKE_BUILD_TYPE=Release 最適化ビルド。Debug にすると速度が大幅低下

CMake の出力に -- Extra modules: の行が表示され、有効なモジュール一覧が出れば設定成功です。

--   Extra modules:
--     Location (extra): ~/opencv_contrib/modules
--     Version control (extra): 4.10.0
...
--     aruco
--     bgsegm
--     ...
--     xfeatures2d
--     ximgproc
--     ...

5. ビルドとインストール

# CPU コア数を確認して並列ビルド
nproc
make -j$(nproc)
sudo make install
sudo ldconfig

make -j$(nproc) で全コアを使います。コア数によりますが、一般的なマシンで 10〜30 分程度かかります。

6. インストール確認

pkg-config --modversion opencv4

4.10.0 のようにバージョンが表示されれば成功です。表示されない場合は /usr/local/lib/pkgconfig/ にパスが通っていることを確認してください。

export PKG_CONFIG_PATH=/usr/local/lib/pkgconfig:$PKG_CONFIG_PATH

動作確認

contrib ビルドが正しく機能しているかを確認するため、cv::buildInformation() でビルド情報を出力しつつ、contrib の SIFT を実際に呼び出す最小プログラムを用意しました。

#include <iostream>
#include <opencv2/opencv.hpp>
#include <opencv2/xfeatures2d.hpp>  // contrib: SIFT

int main()
{
    // ビルド設定の確認（NONFREE や Extra modules が含まれているか確認できる）
    std::cout << cv::getBuildInformation() << std::endl;

    // テスト用の画像を生成（ファイルなしでも動作確認できるようにする）
    cv::Mat img(300, 300, CV_8UC1);
    cv::randu(img, 0, 255);

    // contrib: SIFT 検出器の生成（ここが動けば contrib リンク成功）
    auto sift = cv::SIFT::create();
    std::vector<cv::KeyPoint> keypoints;
    sift->detect(img, keypoints);

    std::cout << "SIFT keypoints detected: " << keypoints.size() << std::endl;

    // 結果画像を保存して imread/imwrite の確認も兼ねる
    cv::Mat output;
    cv::drawKeypoints(img, keypoints, output);
    cv::imwrite("sift_result.png", output);
    std::cout << "sift_result.png を出力しました" << std::endl;

    return 0;
}

コンパイルコマンド

g++ -std=c++17 main.cpp `pkg-config --cflags --libs opencv4` -o main
./main

実行すると ターミナルに OpenCV のビルド設定情報（General configuration から始まる長い出力）が表示され、最後に次のような行が出力されます。

SIFT keypoints detected: 42
sift_result.png を出力しました

SIFT keypoints detected: の行が出れば contrib のリンクに成功しています。カレントディレクトリに sift_result.png が生成されているはずです。

⚠️ OPENCV_ENABLE_NONFREE=OFF でビルドした場合、cv::SIFT::create() は OpenCV 4.4 以降は本体にも入っていますが、SURF は OPENCV_ENABLE_NONFREE=ON かつ contrib が必須 です。

つまずきポイント

① cv::SIFT が見つからない / xfeatures2d.hpp が見つからない

fatal error: opencv2/xfeatures2d.hpp: No such file or directory

CMake 設定時に OPENCV_EXTRA_MODULES_PATH が正しく設定されていないか、contrib のバージョンが本体と一致していない場合に起きます。~/opencv/build 内の CMakeCache.txt を削除してビルドディレクトリを一度クリアしてから再 cmake してください。

cd ~/opencv/build
rm -rf *
cmake ... （再実行）

② pkg-config --modversion opencv4 が空を返す

インストール先 /usr/local/lib/pkgconfig/ が PKG_CONFIG_PATH に含まれていないことが原因です。.bashrc に追記して恒久化します。

echo 'export PKG_CONFIG_PATH=/usr/local/lib/pkgconfig:$PKG_CONFIG_PATH' >> ~/.bashrc
source ~/.bashrc

また、sudo ldconfig の実行忘れも libopencv_*.so が見つからないエラーにつながります。インストール後に必ず実行してください。

③ CMake 時に Could NOT find FFMPEG が出て動画処理ができない

ffmpeg 開発ライブラリが入っていない状態で WITH_FFMPEG=ON にすると、CMake は警告を出してスキップします。依存パッケージをインストール後にビルドキャッシュをクリアして再 cmake が必要です。apt でインストールした後、ビルドディレクトリの CMakeCache.txt だけ削除して cmake をやり直せばライブラリを再検索します。

まとめ

ステップ ポイント
依存パッケージ まとめて入れる。後から追加は再ビルドが必要
バージョン統一 本体と contrib は同一タグを必ず使う
CMake オプション OPENCV_EXTRA_MODULES_PATH と OPENCV_ENABLE_NONFREE=ON が核心
確認 cv::SIFT::create() が動けば contrib リンク成功

contrib が使えるようになると、SIFT・SURF などの特徴量記述子に加え、cv::ximgproc のフィルタ群も利用できます。基本的なフィルタ処理については cv::bilateralFilter の使い方【OpenCV/C++】〜エッジを保ちながらノイズを除去するバイラテラルフィルタ〜 や cv::morphologyEx の使い方【OpenCV/C++】〜オープニング・クロージングでノイズ除去〜 も参照してください。

🛠 画像処理のプロが開発するSDK/API

本ブログを運営するスワローインキュベートは、OpenCV ベースのなりすまし判定SDK/API（C++製・OpenCV 4.10）を開発しています。顔認証システムへの組み込み実績多数。

→ なりすまし判定SDK/APIの詳細を見る
→ API仕様書・サンプルコード

タイトルとURLをコピーしました