Raspberry Pi 4 で OpenCV をセットアップする

OpenCV は Raspberry Pi 上でソースからビルドでき、Python 3 で cv2 をインポートして確認できます。このガイドでは、Raspberry Pi OS を実行する Raspberry Pi と、インターネットに接続された端末を使用することを前提としています。ビルドには長い時間がかかる場合があり、十分な空き容量が必要です。所要時間と実行できる並列ジョブ数は、ボード、メモリ、選択した OpenCV モジュールによって異なります。

Raspberry Pi とオペレーティングシステムを選ぶ

この手順は Raspberry Pi 4 Model B を対象としていますが、互換性のあるオペレーティングシステムを使う Raspberry Pi のほかのモデルでも OpenCV をビルドできる場合があります。以下のコマンドでは、対象のオペレーティングシステムを Raspberry Pi OS としています。これはこのガイドで明示した前提であり、特定のOSリリースやボード構成でテスト済みという意味ではありません。古いボードやメモリの少ないボードではコンパイルに時間がかかることがあり、空きディスク容量がビルドの制約になる場合もあります。

Raspberry Pi OS を準備する

Pi で端末を開き、sudo apt update の後に sudo apt upgrade を実行して、パッケージ一覧とインストール済みパッケージを更新します。build-essential、cmake、git、pkg-config、python3-dev、python3-numpy などのコンパイラーとツールを、sudo apt install build-essential cmake git pkg-config python3-dev python3-numpy でインストールします。パッケージ名や入手可能性は Raspberry Pi OS のリリースによって異なることがあります。続行する前に、使用中のリリースに応じてパッケージマネージャーのエラーを解決してください。ソースツリーと生成されるビルドファイルを置けるだけの空きディスク容量を確保します。

python3-dev パッケージには、Python バインディングの構成に必要な Python 開発用ヘッダーが含まれています。ビルド時と OpenCV の確認時には、同じ Python 3 のインストールと環境を使ってください。仮想環境を使う場合は、ビルドでその環境のインタープリターと NumPy を認識させる方法を事前に確認します。システムの Python と仮想環境が同じものとして使えるとは限りません。

OpenCV をソースからビルドしてインストールする

インストール済みのオペレーティングシステムと Python 環境に適合する OpenCV リリースを選びます。追加モジュールが必要な場合は、対応するリリースの opencv-contrib を選んでください。そのモジュールは OpenCV のメインリポジトリとは別に提供されています。2つのソースツリーでは、同じリリースバージョンを使う必要があります。追加モジュールについては、関連する opencv-contrib のガイドも参考にしてください。

以下は Raspberry Pi OS の端末で実行するコマンドの手順であり、単独で動くプログラムではありません。各コマンドの VERSION は、同じ OpenCV リリースタグに置き換えてください。対応するソースツリーをホームディレクトリにクローンするには、git clone --branch VERSION --depth 1 https://github.com/opencv/opencv.git ~/opencv-VERSION を実行します。追加モジュールが必要な場合は、git clone --branch VERSION --depth 1 https://github.com/opencv/opencv_contrib.git ~/opencv_contrib-VERSION も実行します。mkdir -p ~/opencv-VERSION/build でビルドディレクトリを作成し、cd ~/opencv-VERSION/build でそのディレクトリに移動します。

そのディレクトリで cmake -D CMAKE_BUILD_TYPE=Release -D CMAKE_INSTALL_PREFIX=/usr/local -D OPENCV_EXTRA_MODULES_PATH="$HOME/opencv_contrib-VERSION/modules" .. を実行し、ビルドを構成します。このオプションには対応する contrib ディレクトリを指定してください。contrib モジュールをビルドしない場合は、このオプションを省略します。これらは構成例であり、利用できるオプションは選んだリリースやシステムの依存関係によって異なります。

構成済みのディレクトリで make -j2 を実行してビルドし、その後 sudo make install でインストールします。Pi のメモリが不足する場合は、ジョブ数を減らしてください。並列ジョブ数を減らすと、通常はビルドに時間がかかります。ビルドとインストールには、ダウンロード済みのソース、動作するコンパイラーツールチェーン、互換性のある依存関係が必要なため、ここでは独立した実行例として扱うことはできません。

Python で OpenCV を確認する

ビルドに使った Python 3 環境で確認コマンドを実行します。このコマンドはバインディングをインポートし、インストール済みモジュールが報告するバージョンを表示します。提供された実行では終了コードは 0 でしたが、その実行環境では cv2 が利用できないと報告されたため、OpenCV のインポート成功は確認されていません。表示されるバージョンはインストール内容によって異なります。

import importlib.util

if importlib.util.find_spec("cv2") is None:
    print("cv2 is not available in this Python environment.")
else:
    import cv2
    print(cv2.__version__)

インポートに成功すれば、そのインタープリターが cv2 モジュールを見つけられることを確認できます。Python がモジュールを見つけられないと報告した場合は、ビルドによって Python バインディングがインストールされたか、コマンドで意図したインタープリターを使っているかを確認してください。バージョン文字列が表示されても、すべてのオプションモジュールやカメラデバイスが利用できるとは限りません。

よくあるインストール失敗への対処

Pi のメモリに負荷がかかってコンパイルが停止した場合は、ビルドディレクトリで make -j1 のようにジョブ数を減らして再実行します。並行して使うリソースを減らせますが、ビルド時間は長くなり、すべての失敗を解決できるとは限りません。ログで最初に現れるコンパイラーまたは CMake のエラーを確認し、CMake が対応する opencv_contrib の modules ディレクトリを指していること、両方のソースツリーで同じリリースタグを使っていることを確かめてください。

インストール後に import cv2 が失敗する場合は、ビルド時に構成したインタープリターが python3 であることと、インストール先にそのインタープリターが検索するディレクトリが含まれていることを確認します。NumPy を別の Python 環境にインストールしても、ビルドに使ったインタープリターから利用できるようにはなりません。

まとめ

Raspberry Pi OS で OpenCV をソースからビルドするには、CMake で構成し、デバイスに合ったジョブ数でコンパイルして、生成されたライブラリをインストールします。対応する Python 3 環境で cv2 をインポートすれば、バインディングを利用できるか実際に確認できます。使用中のシステムに適合する、バージョンのそろった OpenCV と opencv-contrib を選んでください。このガイドは、テスト済みの互換性一覧を示すものでも、すべての Raspberry Pi 構成でビルドが成功することを保証するものでもありません。