OpenCV + opencv_contrib を Raspberry Pi OS でビルドする【C++】

この記事では、Raspberry Pi OS（64bit）上で OpenCV 4.x と opencv_contrib をソースからビルドし、C++ 開発環境を整える手順を解説します。

apt install libopencv-dev でインストールできる OpenCV は contrib モジュールを含まないため、face・aruco・xfeatures2d などを使いたい場合はソースビルドが必須です。記事を最後まで読むと、contrib モジュール込みの OpenCV が /usr/local にインストールされ、C++ プログラムをコンパイル・実行できる状態になります。

前提環境

⚠️ RAM 2GB モデルでもビルド可能ですが、並列数を -j2 に落とすことを推奨します。スワップ不足でビルドが途中終了するケースがあります。

手順

1. パッケージの更新と依存ライブラリの導入

sudo apt update
sudo apt upgrade -y

sudo apt install -y \
  cmake build-essential git \
  libgtk-3-dev \
  libjpeg-dev libpng-dev libtiff-dev \
  libavcodec-dev libavformat-dev libswscale-dev \
  libv4l-dev \
  libatlas-base-dev gfortran \
  python3-dev

build-essential には gcc・g++・make が含まれます。libgtk-3-dev は imshow ウィンドウの表示に必要です。

2. 作業ディレクトリの準備

mkdir ~/opencv_build
cd ~/opencv_build

3. ソースの取得

OpenCV と opencv_contrib は必ず同一バージョンを取得してください。バージョンが異なると cmake 時にエラーになります。

以下では GitHub の releases ページから最新の安定版タグ（例: 4.10.0）を指定しています。実際のバージョンは https://github.com/opencv/opencv/releases で確認してください。

# バージョンを変数にしておくと後のパス指定が楽
export OPENCV_VERSION=4.10.0

wget https://github.com/opencv/opencv/archive/${OPENCV_VERSION}.tar.gz \
     -O opencv.tar.gz

wget https://github.com/opencv/opencv_contrib/archive/${OPENCV_VERSION}.tar.gz \
     -O opencv_contrib.tar.gz

tar -xf opencv.tar.gz
tar -xf opencv_contrib.tar.gz

展開後のディレクトリ構成:

~/opencv_build/
├── opencv-4.10.0/
└── opencv_contrib-4.10.0/

4. CMake による Makefile 生成

contrib を含める場合、OPENCV_EXTRA_MODULES_PATH の指定が最重要です。modules まで含めたパスを渡します。

cd ~/opencv_build/opencv-${OPENCV_VERSION}
mkdir build
cd build

cmake \
  -DCMAKE_BUILD_TYPE=Release \
  -DCMAKE_INSTALL_PREFIX=/usr/local \
  -DOPENCV_EXTRA_MODULES_PATH=../../opencv_contrib-${OPENCV_VERSION}/modules \
  -DOPENCV_ENABLE_NONFREE=ON \
  -DBUILD_opencv_python3=OFF \
  -DBUILD_TESTS=OFF \
  -DBUILD_PERF_TESTS=OFF \
  -DWITH_GTK=ON \
  -DWITH_V4L=ON \
  ..

各オプションの意図:

cmake の最後に以下が表示されれば成功です。

-- Configuring done
-- Build files have been written to: .../opencv-4.10.0/build

✅ cmake ログの Extra modules の行に face aruco xfeatures2d などが列挙されていることを確認してください。空欄の場合、パスの指定が誤っています。

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

make -j4

Raspberry Pi 4（4コア）で -j4 を指定します。RAM 2GB の場合は -j2 に落としてください。ビルド完了まで 50〜70 分かかります。

[100%] が表示されたらインストールします。

sudo make install
sudo ldconfig

6. インストール確認

pkg-config --modversion opencv4

バージョン番号（例: 4.10.0）が表示されれば OK です。

contrib モジュールが含まれているかどうかは、以下のディレクトリに face/ や aruco/ が存在するかで確認できます。

ls /usr/local/include/opencv4/opencv2/ | grep -E "face|aruco|xfeatures2d"

動作確認

ビルドが成功したことを確認するための最小プログラムです。cv::getBuildInformation() でビルド情報を出力し、contrib モジュールが含まれているかを確認します。

#include <iostream>
#include <opencv2/core.hpp>
#include <opencv2/highgui.hpp>

int main()
{
    // ビルド情報の出力（Extra Modules Path が含まれているか確認）
    std::cout << cv::getBuildInformation() << std::endl;

    // カメラキャプチャの疎通確認
    cv::VideoCapture cap(0);
    if (!cap.isOpened()) {
        std::cerr << "カメラを開けませんでした（/dev/video0 が存在するか確認）" << std::endl;
        return 1;
    }

    cv::Mat frame;
    cap >> frame;
    if (frame.empty()) {
        std::cerr << "フレームの取得に失敗しました" << std::endl;
        return 1;
    }

    cv::imshow("Capture Test", frame);
    cv::waitKey(0);

    return 0;
}

コンパイル:

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

実行すると:

ターミナルに getBuildInformation() の出力が表示されます。その中の Extra modules: の行に face, aruco, xfeatures2d などが含まれていれば、opencv_contrib 込みのビルドが正常に機能しています。

Extra modules:
  Location (extra): /home/pi/opencv_build/opencv_contrib-4.10.0/modules
  Version control (extra): 4.10.0

カメラが接続されていれば、キャプチャしたフレームがウィンドウに表示されます。

つまずきポイント

cmake に contrib パスを渡したのにモジュールが入っていない

OPENCV_EXTRA_MODULES_PATH のパスが opencv_contrib-4.10.0/ で終わっているケースがあります。正しくは opencv_contrib-4.10.0/modules まで指定する必要があります。

# ❌ 誤り（modules が抜けている）
-DOPENCV_EXTRA_MODULES_PATH=../../opencv_contrib-4.10.0

# ✅ 正しい
-DOPENCV_EXTRA_MODULES_PATH=../../opencv_contrib-4.10.0/modules

cmake を再実行する際は build/ ディレクトリを一度削除してから再生成してください（キャッシュが残ります）。

make がメモリ不足で止まる

Raspberry Pi OS の初期スワップサイズは 100MB です。RAM 2GB モデルで -j4 を使うとリンク時にメモリ不足になることがあります。

sudo dphys-swapfile swapoff
# /etc/dphys-swapfile の CONF_SWAPSIZE を 2048 に変更
sudo nano /etc/dphys-swapfile
sudo dphys-swapfile setup
sudo dphys-swapfile swapon

スワップを 2GB に増やした上で -j2 でビルドすると安定します。ビルド完了後はスワップサイズを元に戻すことを推奨します（SD カードへの書き込み負荷を減らすため）。

pkg-config --libs opencv4 でライブラリが見つからない

sudo ldconfig を忘れていると、実行時に error while loading shared libraries: libopencv_core.so.4.x が出ることがあります。また、PKG_CONFIG_PATH が通っていない場合は以下を ~/.bashrc に追記してください。

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

まとめ

• Raspberry Pi OS（64bit）で OpenCV + opencv_contrib をビルドするには、cmake の OPENCV_EXTRA_MODULES_PATH に modules まで含めたパスを指定するのが最重要です
• OpenCV と opencv_contrib は必ず同一バージョンを使ってください
• RAM 2GB モデルはスワップを増やして -j2 でビルドするのが安全です
• cv::getBuildInformation() で contrib モジュールが含まれているか確認できます

ソースビルドは時間がかかりますが、一度環境を作ってしまえば face・aruco・xfeatures2d などの強力なモジュールを C++ から直接使えるようになります。