OpenCV is one of the best computer vision tools available. It is the most popular machine vision library among developers and manufacturers. Being open source, the library has enjoyed vast community support and has evolved as one of the most mature software packages. OpenCV itself stands for “Open Source Computer Vision”. The latest version of the library is OpenCV 4.7, available for free commercial use under the Apache license. The library is especially useful for real-time computer vision applications. It also supports most common machine learning algorithms such as K-Nearest Neighbor, Naive Bayes, Random Forest, Decision Tree, Support Vector Machine, Artificial Neural Networks (ANN), and deep neural networks.
Whether someone wants to build a machine vision project using C++ or Python, OpenCV is the best tool to start with. A computer vision project can be easily built on any PC or Mac using OpenCV. It is also possible to invest in OpenCV in embedded artificial vision projects. The new generation microcomputers like Raspberry Pi, NVIDIA Jetson Nano, RockPi, etc. are quite capable of supporting the OpenCV environment.
There are great benefits to running embedded computer vision applications on these low-cost embedded computers. Microcomputers can run 24/7 to host a dedicated computer vision project that may even involve machine learning or deep learning algorithms, that too without any special arrangements other than a good heatsink. The application can be implemented at incredibly low costs without compromising efficiency. Additionally, microcomputers are capable of performing many calculations locally, which makes them more suitable for edge or fog computing.
In this tutorial, we will see how to install OpenCV 4.5 on Raspberry Pi. The Raspberry Pi model used in this tutorial is Raspberry Pi 4B with 8 GB of RAM. Other Raspberry Pi 4 models can also be used. Even though the configuration can be done on a Raspberry Pi 3 or 2, OpenCV may have compromised performance on these boards. The Raspberry Pi 4B used in this tutorial is installed with Raspbian Bullseye. The same instructions dictated here are applicable to installing OpenCV on the NVIDIA Jetson Nano booted from a Debian operating system.
Setting up OpenCV on Raspberry Pi or any other Linux microcomputer is the first thing one needs to do before embarking on developing a machine vision application. Configuration is time-consuming and can be frustrating for beginners, especially those who are new to Linux and Shell scripting. Even if one step is missed, the entire configuration can be compromised. This tutorial will guide you step by step to complete the installation of OpenCV 4.5 plus QT5 on Raspberry Pi 4B installed with Raspbian Bullseye.
There are two ways to install OpenCV on any system. One is a simple PIP installation method. The second is to compile OpenCV from source. The PIP installation method is simple and short, but it does not expose all the details of the software. Source code compilation takes hours to complete, resulting in a complete and optimized installation where all OpenCV features can be obtained at once. This tutorial details the build-from-source method and walks you through the complete installation on a Raspberry Pi step by step. Unlike a PC or Mac, installing on a microcomputer like Raspberry Pi involves several steps required to optimize the installation specifically for the target board. All these steps are provided in this tutorial in the correct sequence.
Without wasting any time, let's quickly get to the configuration. The entire process will take a few hours to complete. Depending on the target board, such as some other Raspberry Pi variant or a different microcomputer, it may take even longer. So be patient and take occasional breaks in your cubicle for coffee while the installation is complete. Let's start.
Confirm operating system specifications
The first thing you need to check is the operating system specifications. The configuration for a 32-bit operating system would be different than a configuration for the 64-bit operating system. Open the Bash Terminal and run the following command.
$ unname -a
If the reported Linux version contains the string 'armv7l', the operating system installed on the Raspberry Pi is 32-bit. If it contains the string 'aarch64', it will be 64-bit. The installation guide presented in this tutorial is for 32-bit operating systems only.
Next, you need to confirm the operating system version. This can be done by running the following command in Terminal.
$ cat /etc/os-release
The above command results in meta information about the Raspbian version installed on the Raspberry Pi. Our Raspberry Pi 4B (8 GB) is installed with the latest Raspbian Bullseye operating system. There is another command that provides even more information about the card and also the operating system. That's the thing.
$hostnamectl
If you haven't prepared your Raspberry Pi, it's best to install the 32-bit Raspbian operating system for this tutorial and the computer vision tutorials that follow. If you already have the Raspberry Pi installed with the operating system, confirm that it is the 32-bit version. We suggest installing 32-bit Raspberry Pi OS with desktop and recommended software.
Expand file system
Next, you must expand the Raspberry Pi file system and utilize all the space on the MicroSD card. By default, when an operating system image is applied to a MicroSD card, a lot of space on it becomes unusable. Since the OpenCV setup itself consumes a few gigabytes, we must reclaim all the space on a 32 GB MicroSD card by expanding the Raspberry Pi file system. Otherwise, the setup may fail or even if it completes, OpenCV may not have enough space for user files and updates. Exhausted space can result in severe underperformance of a computer vision application. To expand the file system on Raspberry Pi, open Bash Terminal and run the following command to open Raspberry Pi Settings.
$ sudo raspi-config
In the pop-up window, select “advanced options”.
Then select “A1 Expand Filesystem” and click “OK” to restart.
After rebooting, all MicroSD card space will be reclaimed by Raspberry Pi OS. The newly available space on the card can be checked by running the following command in the Bash Terminal.
df-h
You can see that we have 18 GB of space available on the MicroSD card after expanding the file system, while 8.9 GB is used by the operating system.
Increase GPU memory
RAM is used by the CPU and GPU. On Raspberry Pi 2B/3B, only 64 MB of RAM is allocated for GPU, while on Raspberry Pi 4B it is only 76 MB. This may be unsuitable for machine vision projects. The RAM allocation for GPU must be at least 128 MB so that a computer vision application does not choke. To increase the RAM allocation for GPU, open the “Raspberry Pi Configuration” window by navigating to Raspberry Pi Menu->Preferences->Raspberry Pi Configuration.
In the “Raspberry Pi Configuration” window, select the “Performance” tab and increase the GPU memory to 128. When you click “OK” after increasing the RAM allocation for the GPU, the Raspberry Pi prompts you to restart. Select “Yes” to restart and the GPU allocation will take effect.
Update EEPROM
Another optimization that we must do before proceeding with the OpenCV installation is to update the Raspberry Pi's EEPROM. Although the Raspberry Pi boots its operating system from the MicroSD card, it also partially boots from two EEPROMs. Although EEPROMs have nothing to do with OpenCV, the latest version of EEPROM has been observed to reduce CPU temperature from 65˚C to 48˚C. Computer vision applications are CPU intensive; If a simple update to the EEPROM can lower the CPU temperature, it can increase application performance. To check the EEPROM version, run the following command in the Bash Terminal.
$ sudo rpi-eeprom-update
If the EEPROM is up to date, it's fine. If not, run the following command in Terminal to update the EEPROM.
$ sudo rpi-eeprom-update -a
Increase SWAP space
OpenCV requires a lot of memory to compile. The latest stable version of OpenCV4.5 requires at least 6.5 GB of space before being built. Therefore, you must increase the swap space, which by default is limited to 2048 MB. To increase swap space, open /sbin/dphys-swapfile by running the following command in the Bash Terminal.
$ sudo nano /sbin/dphys-swapfile
Once the file is open in the nano editor, jump to the CONF_MAXSWAP flag and change it from 2048 MB to 4096 MB. Save the file by pressing Ctrl+S and close the file by pressing Ctrl+X. Then open /etc/dphys-swapfile by running the following command.
$ sudo nano /etc/dphys-swapfile
Now, change CONF_SWAPSIZE to 4096 from 2048. Finally, restart your Raspberry Pi for the changes to take effect by running the following command in Terminal.
$ sudo restart
Successfully updating and upgrading Raspbian
On a fresh installation of Raspbian, when update and OS update commands are executed, it is observed that although the update is done successfully, the update results in the following error.
E: Unable to search for some files, can you run apt-get update or try with –fix-missing?
The above error is only encountered on Raspberry Pi 32-bit operating system. On Raspberry Pi OS 64-bit, this error was not encountered. Although many manufacturers opt for 64-bit operating system just to get around the above error. The error is a result of missing files and libraries from the source repository. This can be easily fixed by redirecting the source repository to a suitable mirror link. It is important to work around this error, otherwise corrupt or missing files in Raspbian may result in unpredictable behavior of our OpenCV application.
To redirect the source repository, open /etc/apt/sources.list in the nano editor by running the following command in the Bash Terminal.
$ sudo nano /etc/apt/sources.list
When the file opens in the nano editor, comment out the first line indicating the original source repository and add the following line at the end.
deb bullseye main contribution rpi not free
Save the file by pressing Ctrl+S and close the file by pressing Ctrl+X. Restart the Raspberry Pi for the changes to take effect. Now when you update and update 32-bit Raspbian, no errors are found. The other mirror links that work near specific geographic locations can be found at this link.
Install dependencies
Before installing OpenCV, you need to install several third-party packages required by OpenCV. Some of these packages may already be installed with Raspbian. Still, it's better to install all the necessary packages than encounter some errors later. If the latest version of any package is already installed with Raspbian, it will be automatically ignored when running the command. Run the following commands in the Bash Terminal one by one to install the required sets of software packages by OpenCV.
$ sudo apt-get update
$ sudo apt-get update
$ sudo apt-get install cmake gfortran
$ sudo apt-get install python3-dev python3-numpy
$ sudo apt-get install libjpeg-dev libtiff-dev libgif-dev
$ sudo apt-get install libgstreamer1.0-dev gstreamer1.0-gtk3
$ sudo apt-get install libgstreamer-plugins-base1.0-dev gstreamer1.0-gl
$ sudo apt-get install libavcodec-dev libavformat-dev libswscale-dev
$ sudo apt-get install libgtk2.0-dev libcanberra-gtk*
$ sudo apt-get install libxvidcore-dev libx264-dev libgtk-3-dev
$ sudo apt-get install libtbb2 libtbb-dev libdc1394-22-dev libv4l-dev
$ sudo apt-get install libopenblas-dev libatlas-base-dev libblas-dev
$ sudo apt-get install libjasper-dev liblapack-dev libhdf5-dev
$ sudo apt-get install protobuf-compiler
Install QT5
QT5 is an open source framework for developing cross-platform graphical user interfaces. It can also be used on Raspberry Pi to build beautiful user interfaces for embedded applications. Some computer vision applications may require interaction through a user interface. Although adding a user interface may slow down your machine vision application somewhat, it may be necessary or useful to add an interface in some applications. To install QT5 on Raspbian Buster, run the following commands one by one in Bash Terminal.
$ sudo apt-get install qt5-default
$ sudo apt-get install qtcreator
$ sudo apt-get install qtdeclarative5-dev
To install QT5 on Raspbian Bullseye, run the following commands one by one in Bash Terminal.
$ sudo apt-get install qtbase5-dev qtchooser
$ sudo apt-get install qt5-qmake qtbase5-dev-tools
$ sudo apt-get install qtcreator
$ sudo apt-get install qtdeclarative5-dev
We already have some tutorials on how to build graphical user interfaces on Raspberry Pi for embedded applications using the Tkinter framework. You should check them out.
Python GUI with Tkinter
Tkinter and TTK widgets
TTK menus, layout management, events and multithreading
GUI Controlled LED Driver
One-button interface and digital input
Download OpenCV
After installing all third-party packages, it's time to install OpenCV. There are two packages for OpenCV — a basic version and additional contributions. You can find the latest versions of OpenCV at this link. We will be installing OpenCV4.5.5 here. You can also install the latest one and change the version number accordingly in the following commands. The installation will consume enough RAM, so first check if there is enough RAM available for installation by running the following command in the Bash Terminal.
$ free -m
Since we are using the 8GB variant of the Raspberry Pi 4B, you may notice that we have more than enough RAM at our disposal. Then open the root directory by running the following command in the Bash Terminal.
$cd~
Download the OpenCV4.5 packages to the root directory by running the following commands in the Bash Terminal.
$ wget -O opencv.zip
$ wget -O opencv_contrib.zip
Unzip the packages by running the following commands in Terminal.
$ unzip opencv.zip
$ unzip opencv_contrib.zip
Rename the directories to simpler names by running the following commands in Terminal.
$ mv opencv-4.5.5 opencv
$ mv opencv_contrib-4.5.5 opencv_contrib
Finally, get rid of the downloaded ZIP files by running the following commands in Terminal.
$rm opencv.zip
$rm opencv_contrib.zip
Installing virtual environments
OpenCV can be installed on a system with or without a virtual environment. If you only want to work with one version of OpenCV, there is no need for a virtual environment. However, you may need to explore some features of a newly released OpenCV version or try some old version of OpenCV; you cannot run both versions together without virtual environments. Suppose you have two versions of OpenCV installed on your Raspberry Pi and you import OpenCV in a Python script, how will Python know which version of OpenCV to import? Installing OpenCV typically takes up just over 1GB of space on a MicroSD card. There is no harm in installing and maintaining more than one OpenCV version on the same SD card. However, multiple versions of OpenCV can be called within a script only through different virtual environments. So if you have OpenCV 4.5 and OpenCV 3.4 installed on the same MicroSD card, you will need two different virtual environments to call different versions of CV in Python scripts.
If you don't want to access OpenCV through virtual environments and still want to work with different versions of OpenCV, the only way left is to install different versions of OpenCV on different MicroSD cards with Raspbian OS. To install virtual environments on Raspberry Pi, it is best to do so through pip, virtualenv and virtualenvwrapper. You must have pip installed on the Raspberry Pi. With a 32-bit Raspberry Pi operating system, including desktop and recommended software, pip3 should already be installed on the Raspberry Pi. To install virtualenv and virtualenvwrapper, run the following commands in the Bash Terminal.
$ sudo pip3 install virtualenv
$ sudo pip3 install virtualenvwrapper
After installing virtualenv and virtualenvwrapper, open the ~/.bashrc file by running the following command in Terminal.
$nano ~/.bashrc
In the ~/.bashrc file, append the following lines at the bottom.
export WORKON_HOME=$HOME/.virtualenvs
export VIRTUALENVWRAPPER_PYTHON=/usr/bin/python3
source /usr/local/bin/virtualenvwrapper.sh
Save the file by pressing Ctrl+S and close the file by pressing Ctrl+X. Now reload the ~/.bashrc file to apply the changes to the current bash session by running the following command.
$ source ~/.bashrc
Then create a virtual environment with the name “cv” with Python3.x by running the following command in Terminal.
$ mkvirtualenv cv -p python3
Once you create a virtual environment, it will be activated in the current Bash session.
While the virtual environment is activated, install picamera and numpy within the environment by running the following commands in the Bash Terminal.
$ pip install “picamera(matrix)”
$ pip3 install numpy
You can disable the virtual environment in a current Bash session at any time by running the following command.
$ disable
Additionally, the virtual environment can be activated in a current Bash session at any time by running the following command
$ work in cv
Note that “cv” is the name of the virtual environment we created.
Build OpenCV
Now it's time to build the OpenCV package. Activate the 'cv' virtual environment by running the following command in the Bash Terminal (if not activated).
$ work in cv
Open the OpenCV folder, create a directory called build and open the directory by running the following commands.
$ cd ~/opencv/
$ mkdir compilation
$cd compilation
Finally, tell cmake to build OpenCV by running the following command which includes several important flags.
$ cmake -D CMAKE_BUILD_TYPE = RELEASE \
-D CMAKE_INSTALL_PREFIX=/usr/local\
-D OPENCV_EXTRA_MODULES_PATH=~/opencv_contrib/modules \
-D ENABLE_NEON = ON \
-D ENABLE_VFPV3 = ON \
-D COM_OPENMP=ON \
-D COM_OPENCL = OFF \
-D BUILD_ZLIB=ON \
-D BUILD_TIFF=ON \
-D COM_FFMPEG=ON \
-D COM_TBB=ON \
-D CONSTRUCTION_TBB=ON \
-D CONSTRUCTION_TESTS = OFF \
-D COM_EIGEN = OFF \
-D COM_GSTREAMER=ON\
-D COM_V4L = ON \
-D COM_LIBV4L=ON\
-D COM_VTK = OFF \
-D COM_QT = OFF \
-D OPENCV_ENABLE_NONFREE=ON \
-D INSTALL_C_EXAMPLES = OFF \
-D INSTALL_PYTHON_EXAMPLES = OFF \
-D PYTHON3_PACKAGES_PATH=/usr/lib/python3/dist-packages\
-D OPENCV_GENERATE_PKGCONFIG=ON \
-D BUILD_EXAMPLES = OFF..
The construction process will take a long time. After OpenCv is built, you can see the output message as shown in the image below.
Make and install OpenCV
After the OpenCV build is complete, start the build process using all four cores of the Raspberry Pi by running the following command in the activated virtual environment of the current Bash session.
$do-j4
On Raspberry Pi 4 it can take around 2 hours. On other Raspberry Pi variants, it can take 5 to 8 hours. You need to wait until the 100% build target is completed.
After OpenCV is compiled successfully, install OpenCV into the “cv” virtual environment by running the following command.
$ sudo make install
Then create the necessary links and cache for the newly installed OpenCV package by running the following command.
$ sudoldconfig
Clean up resources and update the system database by running the following commands.
$ do clean
$ sudo apt-get update
Finally, open the /etc/dphys-swapfile file and reset CONF_SWAPSIZE to 100.
Sym link for OpenCV
We have OpenCV installed in a virtual 'cv' environment. Finally, we need to create a symbolic link to the library. Otherwise, Python would not be able to find and import OpenCV. To create a symbolic link, open the ~/.virtualenvs/cv/lib/python3.9/site-packages folder. The folder path may differ depending on the name given to the virtual environment and the Python version. Remember the name you gave to the virtual environment and confirm the Python version by running the following command.
$ python –version
Run the following commands to open the ~/.virtualenvs/cv/lib/python3.9/site-packages folder, create a symbolic link called 'cv2.so' and return to the root folder.
$ cd ~/.virtualenvs/cv/lib/python3.9/site-packages
$ ln -s /usr/local/lib/python3.9/site-packages/cv2/python-3.9/cv2.cpython-37m-arm-linux-gnueabihf.so
$cd~
Check OpenCV installation
Lastly, you should now verify your OpenCV installation. Activate the 'cv' virtual environment and import the OpenCV library via the “cv2” symbolic link in a Python script. If OpenCV is successfully imported into the script without producing errors, OpenCV will be installed to the virtual environment.
You can confirm the build information about the installed version of OpenCV by running the following Python script.
$ python
>>> import cv2
>>> print(cv2.getBuildInformation )
When running the script, the build information for the installed OpenCV version will be printed in the Terminal.
This completes the installation of OpenCV4.5 on Raspbian Bullseye. A similar installation will occur for other microcomputers running a Debian Linux derivative.
