RaspberryPiへOpenCVを導入（Python用）

---

インストール方法の比較

OpenCVをインストールするには

１：ビルドしてあるものをダウンロードする方法
参考：ホームメイドガーベッジ様
Raspberry Pi Zero に OpenCV を入れてWebカメラをキャプチャする

参考：Quiita@mt08様(独自にビルドしたファイルを公開している方)
ラズパイ3にOpenCV3/4を簡単に導入

参考：からあげ様
Raspberry PiのPythonライブラリはpipよりapt-getで入れるのが断然早い
※mt08様ファイルの導入方法解説


２：自分でビルドする方法
参考：Qiita@nanbuwks様
OpenCV + Python3 on Raspberry Pi

参考：Qiita@Laundly_KUW様
RaspberryPi (3 Model B+) へのOpenCV(3.4.2)のインストール

参考：Qiita@takahiro_itazuri様
ラズパイにOpenCVをインストールする方法


１の方法はとっても簡単です。４行ぐらい実行するだけで終わります。
ビルド済みのため導入も早いのですが、インストール先が正規のフォルダ構成になって
いないため動作しない公式サンプルプログラムが多数あります。

公式サンプルを一通り試すために自分でビルドします。

---

自分でビルドする際の注意点

色々な理由でビルドが失敗します。
今のところ遭遇しているのは

メモリ不足
・Model 3Bの物理メモリが1GBに対してビルド中はメモリの使用量が1GBを超えます。
・仮想メモリ(スワップメモリ)を増やしておく必要があります。
・そのままビルドするとメモリ不足でビルドが停止します。
※メモリスワップ：SDカード等の記憶装置をメモリの代わりに使用する方法

容量不足
・ビルド後はOSとOpenCVで12GB程度の容量が必要になります。
・SDカードは16GB以上が必要です。
・16GBのSDカードを使用していても使用領域の拡張ができていないと容量不足になります。

放熱不足
・ビルド中はCPU使用率が高い状態が２~３時間続き、CPUが高熱になります。
・放熱が不十分だと温度計のマークが出てフリーズします。
・十分に放熱するか、ビルド時にCPUがフル稼働しない設定が必要です。

オフライン
・apt-getの他、cmakeでmakeファイルを生成中もファイルの自動ダウンロードが実行されます。
・必要なファイルが揃っていない状態でビルドするとエラーが出て途中で止まります。
・apt-get中とmakeファイル生成中はラズパイをインターネットに接続しておきましょう。
・makeのオプションを変更してビルドを通すこともできます。

電力不足 ※2024/11/04追記
・RaspberryPi5は処理性能が高い分消費電力も大きくなります。
・使用する電源次第では電力消費に耐えきれず保護機能が働きます。
・専用の大電流電源を使用するか、ビルド時にCPUがフル稼働しない設定が必要です。

---

OpenCVインストール前の準備

OpenCVのインストール前に少々準備が必要です。
１．インストール済機能の更新
２．ラズベリーパイの設定変更
３．画像処理に必要な機能のインストール

１．インストール済機能の更新

とりあえずインストール済機能を更新しておきます。
ターミナルを開いて

sudo apt-get update


OSインストル時にアップデートしていなかったので12.1MBダウンロードしてました

sudo apt-get upgrade


135MBダウンロードするらしいです
ダウンロード後も更新に結構時間がかかります。

これで更新できました。

２．ラズベリーパイの設定変更

先に説明したメモリ不足と容量不足の対策を行っておきます。
※RaspberryPI4ならメモリに余裕があるのでこの設定は不要

スワップメモリの設定変更

現状を確認します

free -h
 
この部分がスワップメモリの容量です。
100MBしかありません。
そこで設定ファイル(/etc/dphys-swapfile)を編集してスワップメモリを増やします。
ただし、普通にテキストエディタで開くと保存できません。
そこで、テキストエディタを管理者権限で実行します。

Raspbian Jessieの場合
sudo leafpad

Raspbian Buster以降だとleafpadがインストールされてないのでmousepad
sudo mousepad

テキストエディタが起動するので設定ファイル/etc/dphys-swapfileを開きます
ファイル＞開く


etcファルダはファイル・システムから開きます


設定ファイル/etc/dphys-swapfileにたどり着きました


設定値を変更します。

　CONF_SWAPSIZE=100
を
　CONF_SWAPSIZE=1024
ぐらいに増やして保存します。

ファイルを編集した段階では機能は更新されていません。
メモリスワップ機能を停止→開始すれば更新されるのですが、
コマンドを打つのが面倒なので再起動します。

reboot

個人的にはコマンドを調べて入力するより再起動した方が短い時間で済みました。

スワップメモリが増えたか確認します。

free -h

増えました。

SDカードの使用領域確認

前回の手順でOSをインストールした場合は、自動的に拡張設定されるので変更は必要ありません。
とりあえず確認だけしておきます。

df -h

この部分が使用可能領域です。
ＳＤカードの容量と同じぐらいならＯＫですが、明らかに小さい場合は拡張が必要です。

ダメな場合の例

16GBのSDカードに対して5.2GBしか容量がありません。

拡張できていない場合は、
参考：Qiita@niwaken様
raspberry pi3でファイルシステムを拡張する方法(raspbian stretch版)

sudo raspi-config --expand-rootfs


使用中で反映できないから再起移動しろと言われるの再起動します

reboot

これで全領域が使える等になります。
これで色々インストールする準備が整いました。

３．画像処理に必要な機能のインストール

細かい解説は参考サイト様にお任せするとして、片っ端からインストールします。

sudo apt-get install build-essential cmake pkg-config
sudo apt-get install libjpeg-dev libtiff5-dev libjasper-dev
sudo apt-get install libavcodec-dev libavformat-dev libswscale-dev libv4l-dev
sudo apt-get install libxvidcore-dev libx264-dev
sudo apt-get install libgtk2.0-dev
sudo apt-get install libatlas-base-dev gfortran
sudo apt-get install python-dev python3-dev

※2019/07/26 python2.7-devをpython-devをへ修正
※2024/10/30 libpng12-devに後継が無く、libjpeg-devのインストールを阻害するので削除
makeファイルの設定を自分で調整したい方はGUI版のcmakeの方が良いでしょう。
参考：ある計算機屋さんの手帳様
Raspberry PiでOpenCV3をビルドする方法

sudo apt-get install cmake-qt-gui


Python2でもPython3でも使える様にpip(Python用パッケージ管理システム)とnumpy(Python用配列演算機能)をインストールしておきます。

sudo apt-get install python-dev python-pip
sudo apt-get install python3-dev python3-pip
sudo pip install numpy
sudo pip3 install numpy

※Python2とPython3の違いはよく知りません。
※2019/07/26 python-devが上と重複してました。
※2022/02/25 python2系がサポート外となりpython-pipをインストールできなくなりました。
→新しい環境だとpython2系でセットアップできません。

※2024/06/19追記
最近のバージョンだと
sudo pip3 install numpy
でエラーが出ます。
error:externally-managed-enviroment

pipで機能をインストールする際は仮想環境に入れろって事に変わったようです。
参考：ラズパイダ様
Raspberry Pi OSでもbookwormでpipインストールエラー

pipを使わずにパッケージを直接インストールすれば良いらしいので
sudo apt-get install python3-numpy
とすればインストールできます。
※自分の環境だと初期状態でインストール済みでした

---

OpenCVのインストール

いよいよOpenCVをインストールします
１．ソースファイルのダウンロード
２．cmakeでmakeファイルの作成
３．ビルド

１．ソースファイルのダウンロード

色々な方法でダウンロードできます。
・githubからクローンしても
・ラズパイでzipファイルをダウンロードしても
・PCでダウンロード後にUSBメモリでコピーしても
どの方法でも構いません。
なるべくオフラインでセットアップしたいので、PCでダウンロード後にUSBメモリでコピーしてみます。

本家からダウンロードします。
OpenCV3系の最終バージョン3.4.6を使ってみます。
https://github.com/opencv/opencv/releases/tag/3.4.6
Source code (zip)

OpenCV用の拡張機能も同じバージョンを使用します。
https://github.com/opencv/opencv_contrib/releases/tag/3.4.6
Source code (zip)

※2024/06/19追記
OpenCV4系の場合、contribが4.xに統合されましたが逐次更新されています。
RaspberryPi5＋BookWormの環境にて、
・2024/04/03時点でダウンロードしたOpenCV4.9.0
・2024/04/03時点でダウンロードしたcontrib-4.x
の組み合わせを2024/06/19に試したところ、make時にエラーが発生しました。
この組み合わせを4月に試した時点では特に問題なくmakeできた覚えがあります。
cmake実行時に追加でダウンロードが実行されるのでcontribのバージョンが古い
と情報が一致しないためmakeできない可能性があります。
2024/06/19時点ではOpenCV4.9.0をcontrib付でmakeすることができませんでした。
→その後組み合わせ次第？ではcontrib付でmakeすることができました。
OpenCV4.10.0でmakeできたのでcontribを使いたい場合は4.10.0を試してみてください。

Windows用に使用しているUSBメモリーにコピーして、ラズベリーパイに挿せば
ラズベリーパイでファイルを開くことができます。

2つのzipファイルを/home/piへコピーします。

USBメモリーを取り外すには

画面左上のアイコン(DVD等の取出しボタンと同じマーク)から取り外しができます。

/home/piへ2つのzipファイルをコピーしたらzipファイルを展開します。
ファイルマネージャーで展開したらちゃんと動きませんでした。
ターミナルから展開します。

unzip opencv-3.4.6.zip
unzip opencv_contrib-3.4.6.zip

/home/piへopencv-3.4.6とopencv_contrib-3.4.6の二つのフォルダができます。
フォルダの名前を
opencv-3.4.6　→　opencv
opencv_contrib-3.4.6　→　opencv_contrib
へ変更します。
※githubからクローンした場合とフォルダ名を同じにするため。深い意味はありません。

２．cmakeでmakeファイルの作成

OpenCVには色々な機能があります。そこでどの機能を実際にビルドするのかcmakeを使って設定します。

まずビルド用フォルダを作成します。
ビルド用フォルダはダウンロードしたファイルがあるopencvフォルダ内に作成します。

cd ~/opencv
mkdir build
フォルダの作成はファイルマネージャーで行っても構いません。

続いてどの機能をビルドするか決めるmakeファイルを作成します。

先ほど作成したフォルダをターミナルで選択します。
cd ~/opencv/build

makeファイルを作成しますが、自分でビルドのオプションを調整したい場合は
GUI版のcmakeを使った方が分かりやすいと思います。
参考：ある計算機屋さんの手帳様
Raspberry PiでOpenCV3をビルド

今回はターミナル版cmakeを使ってみます。
参考サイトによるとビルドの構成は以下となっています。

cmake -D CMAKE_BUILD_TYPE=RELEASE -D CMAKE_INSTALL_PREFIX=/usr/local -D INSTALL_PYTHON_EXAMPLES=ON -D OPENCV_EXTRA_MODULES_PATH=~/opencv_contrib/modules -D BUILD_EXAMPLES=ON ..

※最後の「 ..」も忘れずに。
※C++で開発する際は-D OPENCV_GENERATE_PKGCONFIG=ONも追加しておくとあとが楽

赤文字で示した部分は拡張機能をコピーした場所をしています。
とりあえずビルドしたい人は-D BUILD_EXAMPLES=OFFで問題ありません。

※2022/02/25追記
OpenCV 4.5.5だとビルドに成功してもPython3からcv2をimportできません。
python3用のインストールフォルダが間違っているらしいので
-D PYTHON3_PACKAGES_PATH=/usr/lib/python3/dist-packages
を追加する
参考：Q-engineering様 Install OpenCV 4.5 on Raspberry Pi 4

ここで注意点

先に説明した通り、オフラインでcmakeを実行するとそのあとのビルドで失敗する事があります。
試したところ、OpenCV3.2.0はオフラインでcmakeを実行しても問題なくビルドできます。
OpenCV3.3.0以降だとcmake中にファイルをダウンロードする様で、オフラインでcmakeを
実行すると必要なファイルをダウンロードできず、ビルドが失敗します。
cmakeではエラーにならず、ビルドした時点でエラーになる点に注意が必要です。


fatal error: opencv2/xfeatures2d/cuda.hpp: そのようなファイルやディレクトリはありません

対処法は
１：インターネットに接続した状態でcmakeを実行する。
２：構成を変更してcmakeを実行する。

オンラインであれば特に問題ありませんが、念のため２の方法を説明しておきます。
何をダウンロードしようとするかはcmakeを実行する前にscriptコマンドを実行しておくと確認できます。（参考：yusuke様scriptコマンドで作業ログを記録）

で、ダウンロードしようとする機能は
・xfeatures2d関連のファイル複数
・face_landmark_model.bat
の2系統です。
ビルドの際にエラーになるのはxfeatures2dです。※2019/07/26 訂正
※xfeatures2dのcuda：NVidiaのグラフィックボード関連の機能？

そこで、先のcmakeコマンドのオプションにxfeature2dをビルドしない設定を追加します。

cmake -D CMAKE_BUILD_TYPE=RELEASE -D CMAKE_INSTALL_PREFIX=/usr/local -D INSTALL_PYTHON_EXAMPLES=ON -D OPENCV_EXTRA_MODULES_PATH=~/opencv_contrib/modules -D BUILD_EXAMPLES=ON -D BUILD_opencv_xfeatures2d=OFF ..

この設定であればオフラインでcmakeを実行してもビルドできました。(OpenCV3.4.6にて)

３．ビルド

いよいよビルドです。
ビルドには２～３時間ぐらいかかりました。

とりあえずbuildフォルダへ移動して
cd ~/opencv/build

ビルドを実行します。
しっかり放熱できている場合は4コア使って並列ビルド
make -j4

放熱が心配な場合はコア数を減らしたり
make -j2

1コアでビルドして対応します。
make

容量不足、メモリ不足、放熱不足でビルドが途中で失敗した場合は設定を修正した後に
再度ビルドを実行すれば、ビルド済みの部分はスキップされ、ビルドが中断した個所から
ビルドが再開されます。失敗した場合でももう一度同じコマンドを実行してみましょう。

設定変更して再起動した場合はもう一度
cd ~/opencv/build
で移動した後
make -j4
でリトライします。

※2024/06/19追記
症状が出るバージョン等は不明ですが、並列ビルドを行うと小機能のビルドが完了する
前にこの機能を使ったビルドを実行しようとしているのか、条件が整っているのにエラー
でmakeが中断されることがあります。この状態だと途中で
*** 未完了のジョブを待っています....
といったログが出て、最終的に
make: ***[Makefile:166: all] エラー２
とか出て中断されます。
エラーで中断された場合でも再度
make -j4
でリトライすればビルドが進むことがあります。

※2024/11/04追記
ラズパイ５の電源としてNintendoSwitchの充電器を使用していた際に電力不足になりました。
ラズパイの電力制限が働く前に充電器の電流制限が働いてしまったようで、
ビルド40%ぐらいで電力供給が停止して電源が落ちていました。
再起動後にビルドを再開してみたものの何度試しても途中でエラーになりました。
Contrib無しだビルドが通り、Contrib有だと同様の症状がでます。
電源が途中で落ちてファイルが壊れてしまった可能性があります。
作成したbuildフォルダ内のmodulesフォルダがContrib関連だと思われるので、
modulesフォルダを削除して
make -j3
にてCPUがフル稼働しないようにしたらビルドが通りました。



ビルドが成功しました。
ここまで来ればあと少しです。

ビルドできたファイルをインストールして

sudo make install



関連付け設定をすれば

sudo ldconfig



長かったインストール作業は完了です。

４．インストールできたか確認

pythonからOpenCVを読み出せるか確認しておきます。

python

>>>　が出たらこれに続けて

import cv2

エラーが出なければ続けて

cv2.__version__

でインストールされたOpenCVのバージョンを確認する事が出来ます。



pythonを終了するには

exit()

python3でも同様のコマンドで確認ができます。

---

サンプルプログラムを動かしてみる

インストールできたのでサンプルプログラムを動かしてみます。
pythonのサンプルプログラムを動かしてみます。
サンプルプログラムは/home/pi/opencv/samples/pythonの中にあります。

ターミナルから実行するのは面倒なので、
実行したいプログラム(facedetect.py)のプロパティーを開いて


パーミッションの実行(E)を「すべて」へ変更


この状態でファイルをダブルクリックすればダイアログが出てきて

端末で実行(ターミナルで実行のこと)をすれば

サンプル画像に対して顔の検出が実行されます。


USBカメラを接続して同じプログラムを実行すれば

ラズベリーパイ用としては少々重い処理ですが、カメラで撮影した映像に対して
顔の検出が行われます。

※2024/10/30 追記
bookwormだとOpenCVの機能ではラズパイに直接接続するカメラが使えないようです。
Pythonから読み出す場合はPicamera2を利用することで動作することが確認できました。
参考：Color 日々の備忘録様
Raspberry Pi 5 に OpenCV 4.9.0 インストール

なお、パラメーターを調整すればラズベリーパイでもサクサク動くようになります。