Using OpenCV

On this page

<< return to C++ examples

OpenCV (Open Computer Vision) is a C++ library containing various state-of-the-art vision algorithms, from object recognition to video analysis, image processing etc.

Since NAOqi 2.7, we provide support for OpenCV 3.1. This means that all toolchains include an opencv3 package and all NAOqi code is compatible with OpenCV 3.1.

Here’s a small guide that explains how to use it, what changed since the last major version and how to troubleshoot the most common issues.


The main modules are

  • core : it contains the basic structures and functionalities
  • highgui : anything to do with display
  • imgcodecs : open and save image files
  • videoio : open and save video files
  • imgproc : color conversion, filters...
  • video : optical flow, background substraction...
  • calib3d : homography, fundamental matrices... anything to do with camera calibration and stereovision
  • features2d : feature detection, descriptors, matching
  • ml : machine learning (neural networks, SVM, boosting, KNN etc)
  • flann : efficient clustering and search in databases
  • objectdetection : object detection with Cascade or Haar classifiers

Detailed information about these modules and more can be found on the official documentation page .

Installing OpenCV on your system

Cleaning old versions (OpenCV 2)

Before doing anything, you have to clean the existing system version because OpenCV2 and OpenCV3 cannot coexist on your system (except if you install them to separate locations).

If you installed OpenCV2 using a package manager ( apt on Ubuntu), use this package manager to uninstall the package. For example

              sudo apt-get remove libopencv-dev


If you installed OpenCV2 from the sources, go to the build folder and run

              sudo make uninstall


If you don’t have the build folder anymore, go through the installation process specified below (see Installing the latest version ) with the exact same version as the one that’s already installed on your system and, after installing it, remove it with the above make command.


For ROS users: ROS depends on OpenCV, so depending on the ROS version installed on your system, you may be unable to uninstall OpenCV2 without uninstalling ROS as well. If you absolutely need to use OpenCV3, consider upgrading to a more recent ROS distro ( Kinetic or above ).

This is true for any other project depending on OpenCV2.

Installing the latest version

The best solution is to build OpenCV from the sources and install it.

  • Get the latest OpenCV version from here .

  • Uncompress it somewhere on your machine (it is better to keep it afterwards)

  • Inside the extracted folder, create a build directory and open it

                    mkdir build
    cd build
  • Configure your project using CMake

                    cmake ..

    You must pay particular attention to the logs of this command. If you see that some libs are marked as ‘not found’, you may want to install them and rerun cmake depending on the functionalities that you want to be built.


    CUDA is not necessary.


    If you need to compile code that creates a graphical user interface with OpenCV, Qt or GTK must be installed on your system.

  • Build the distribution

  • Install it

                    sudo make install

You now have OpenCV installed on your machine! All libraries are located in /usr/local/lib, and header files in /usr/local/include.

Code migration: from OpenCV 2.x to OpenCV 3.1

OpenCV 3.x keeps a very similar API compared to OpenCV 2.4, except for some changes summed up in the Transition Guide .


The most important changes in the available modules are that

  • highgui was split in three: imgcodecs , videoio and highgui itself.
  • legacy and nonfree were removed. Non-free code was moved to the OpenCV Contrib repository.

Note that the header files are still located in the subfolder opencv2 , not opencv3 , for example

              #include <opencv2/core.hpp>
#include <opencv2/videoio.hpp>


CMake dependencies

We have packaged OpenCV according to the modules. So when you want to use OpenCV, specify the modules that you want to use. For example, if you are using core and videoio

              qi_use_lib(mylib OPENCV3_CORE OPENCV3_VIDEOIO)


All modules use the following format: OPENCV3_MODULENAME .


CMake configuration

If you get some issues while configuring the project saying that some OpenCV packages are not found, there might be several explanations:

  • You do not have a version of qibuild recent enough. The support for OpenCV 3.x appeared in qibuild 3.11.9.
  • The opencv3 package is missing from the toolchain you are using.


On Windows and Mac, even when cross-compiling it is necessary to have a recent qibuild (>=3.11.9) because the CMake code necessary to find the headers and shared objects is not included in the toolchain package on these platforms.

Building and linking

If you get a compilation error related to OpenCV, first check the OpenCV version in your toolchain or on your system when compiling with a custom OpenCV install.

If you get some “undefined reference to” errors, make sure that you have added all the required dependencies in the CMakeLists.txt file.