Setting up OpenCV

OpenCV can be downloaded from http://opencv.org/, and is available for the most popular operating systems, such as Unix (Linux/Mac), Microsoft Windows (Windows), Android, and iOS. In this book, the last stable release (2.4.9) of OpenCV for Windows 7 (SP1) has been used. For Windows, this release comes in the form of a self-extracting archive (opencv-2.4.9.exe), which should be extracted to the desired location (for example, OPENCV_SCR for C:\opencv-src). It should be noted that in Windows it is strongly recommended to allocate the source and binaries at absolute paths without white spaces because errors might appear later.

After extracting the archive, the obtained files are organized in two subdirectories under OPENCV_SCR: build and sources. The first one (build) includes precompiled (binaries) versions with Microsoft Visual C++ compilers (MSVC, v. 10, 11, and 12) for 32- and 64-bit architectures (located in the x 86 and x 64 subdirectories respectively). The sources subdirectory contains the source code of the OpenCV library. This code might be compiled with other compilers (for example, GNU g++).

Tip

Using the precompiled versions of OpenCV is the easiest option and only requires setting the location of OpenCV's dynamic libraries binaries (DLL files) in the Path environment variable. For instance, in our setup, this location could be OPENCV_SCR/build/x86/vc12/bin where the binaries compiled with MS VC version 12 for the 32 bit architecture are located. Remember that changing the environment variables in Windows 7 (SP1) can be done on Advanced System Settings under Properties of My Computer. The Rapid Environment Editor tool (available at http://www.rapidee.com) provides a convenient way to change Path and other environment variables in Windows 7.

This chapter covers a detailed installation process of OpenCV on Windows 7 (SP1). For Linux and other operating systems, you can have a look at the OpenCV online documentation (OpenCV Tutorials, Introduction to OpenCV section) available at http://docs.opencv.org/doc/tutorials/tutorials.html.

Compiled versus precompiled library

The OpenCV distribution includes the source code of the library that can be compiled when a different binary version is required. One such situation comes when we need to use the Qt-based user interface functions available in OpenCV (which are not included in the precompiled versions). Besides, the build process (compilation) for the OpenCV library is required if our compiler (for example, GNU g++) doesn't match the precompiled version of the library.

The requirements that have to be met in order to compile OpenCV with Qt are as follows:

• A compatible C++ compiler: We use the GNU g++ compiler included with MinGW (Minimal GNU GCC for Windows). This is a standard compiler on Unix and it is appropriate to guarantee code compatibility. Prior to the build process, it is quite convenient to add the location of the compiler binaries (g++ and gmake) to the Path environment variable (for example, in our local system, the location is C:\Qt\Qt5.2.1\Tools\mingw48_32\bin).
• The Qt library: In particular, the Qt 5.2.1 bundle (available at http://qt-project.org/) is customized for an easy setup because it includes the Qt library and the complete development IDE Qt Creator with MinGW 4.8 and OpenGL. Qt Creator is a full-fledged IDE with free software license that we recommend. The Qt binaries location must also be added to the Path environment variable (for example, C:\Qt\Qt5.2.1\5.2.1\mingw48_32\bin).
• The CMake build system: This cross-platform build system is available at http://www.cmake.org/. It consists of a set of tools that help the user prepare and generate the suitable configuration files used for building (compiling), testing, and packaging a large code project such as OpenCV.

Configuring OpenCV with CMake

In this section, we illustrate the configuration steps for OpenCV with CMake, with the help of screenshots of the steps involved:

1. The first step involves the selection of directories and compilers. Once CMake is launched, both the source directory (OPENCV_SCR) and the build directory (OPENCV_BUILD) can be set in the proper text fields in the CMake main window. Also, the checkboxes labeled as Grouped and Advanced should be marked in the CMake main window. We continue clicking on the Configure button. At this point, the tool prompts the user to specify the desired compiler and we choose MinGW Makefiles using the native compilers. If we choose the Specify native compilers option, it is possible to specify a particular location for the compiler and make tools. After clicking on the Finish button, the configuration step continues checking the settings of the system. The following screenshot shows the CMake window at the end of this preconfiguration process:
   

   CMake at the end of the preconfiguration step

   Note

   For the purpose of simplicity, we use in this text OPENCV_BUILD and OPENCV_SCR to denote respectively the target and source directories of the OpenCV local setup. Keep in mind that all directories should match the current local configuration.

2. The next step is the selection of the build options. At the center of the main CMake window, the red entries might be changed if desired. In our setup, we open the entries grouped with the label WITH and there we set the WITH_QT entry to ON, and then we click on Configure again to obtain a new set of options.
3. Now, the next stage is to set the Qt directories. In the main CMake window, a few entries are marked in red. These are the required directories to build OpenCV with Qt. The next entries to be set are: Qt5Concurrent_DIR, Qt5Core_DIR, Qt5Gui_DIR, Qt5OpenGL_DIR, Qt5Test_DIR, and Qt5Widgets_DIR (refer to the following figure). In our setup, these directories can be found under C:/Qt/Qt5.2.1/5.2.1/mingw48_32/lib/cmake.

   By clicking on the Configure button once, we obtain no further red entries and the configuration process is finally done, as shown in the following screenshot:

   

   Setting Qt directories for CMake

4. The last step is to generate the project. In this step, we click on the Generate button to obtain the suitable project files to build OpenCV in the target platform. Then, the CMake GUI should be closed to continue with the compilation.

In the process just described, it is possible to change the configuration options as many times as desired before the generation step. Some other convenient options to be set are listed as follows:

• BUILD_EXAMPLES: This option is used to compile the source code of several examples included in the distribution
• BUILD_SHARED_LIBS: Uncheck this option to get a static version of the libraries
• CMAKE_BUILD_TYPE: Set this to Debug to get a version for debugging purposes and so on
• WITH_TBB: Set this option to activate the use of Intel® Threading Building Block that lets you easily write parallel C++ code
• WITH_CUDA: Set this option to use processing by GPU through CUDA libraries

Building and installing the library

The compilation should be launched from the console at the target directory (OPENCV_BUILD) set during the configuration with CMake (that is, step 1 from the previous list). The command should be as follows:

OPENCV_BUILD>mingw32-make

This command launches a build process using the generated files by CMake. Compilation typically takes several minutes. If the compilation ends without errors, the installation continues with the execution of the following command:

OPENCV_BUILD>mingw32-make install

This command copies the OpenCV binaries to the following directory:

C:\opencv-buildQt\install

If something goes wrong during the compilation, we should return to CMake to change the options selected in the previous steps. Installation ends by adding the location of the library binaries (DLL files) to the Path environment variable. In our setup, this directory is located at OPENCV_BUILD\install\x64\mingw\bin.

To check the success of the installation process, it is possible to run some of the examples compiled along with the library (if the BUILD_EXAMPLES option was set with CMake). The code samples can be found at OPENCV_BUILD\install\x64\mingw\samples\cpp.

Canny edge detection sample

The preceding screenshot shows the output window for the sample cpp-example-edge.exe file, which demonstrates the Canny edge detection on the fruits.jpg input file included with the source OpenCV distribution.

In the next section, we summarize the recipe used to set up OpenCV 2.4.9 in our Windows 7-x32 platform with Qt 5.2.1 (MinGW 4.8).

Quick recipe for setting up OpenCV

The whole process for setting up OpenCV can be done using the following steps:

1. Download and install Qt5 (available at http://qt-project.org/).
2. Add the MinGW bin directory (for g++ and gmake) to the Path environment variable (for example, C:\Qt\Qt5.2.1\Tools\mingw48_32\bin\).
3. Add the Qt bin directory (for DLLs) to the Path environment variable (for example, C:\Qt\Qt5.2.1\5.2.1\mingw48_32\bin\).
4. Download and install CMake (available at http://www.cmake.org/).
5. Download OpenCV archive (available at http://opencv.org/).
6. Extract the downloaded archive to an OPENCV_SRC directory.
7. Configure the OpenCV build project with CMake using the following steps:
   1. Choose the source (OPENCV_SCR) and target (OPENCV_BUILD) directories.
   2. Mark the Grouped and Advanced checkboxes and click on Configure.
   3. Choose a compiler.
   4. Set the BUILD_EXAMPLES and WITH_QT options, and finally click on the Configure button.
   5. Set the following Qt directories: Qt5Concurrent_DIR, Qt5Core_DIR, Qt5Gui_DIR, Qt5OpenGL_DIR, Qt5Test_DIR, Qt5Widgets_DIR. Then, click on Configure again.
   6. If no errors are reported (marked in red in the CMake window), you can click on the Generate button. If some error is reported, the wrong options should be corrected and the Configure steps should be repeated. Close CMake after the Generate step.
8. Open a console under the OPENCV_BUILD directory and run the mingw32-make command to start the compilation.
9. If the build process doesn't produce an error, run mingw32-make install on the command line.
10. Add the OpenCV bin directory (for DLLs) to the Path environment variable (for example, OPENCV_BUILD\install\x64\mingw\bin\).

To check the right installation of the OpenCV library, you can run some of the examples included at OPENCV_BUILD\install\x64\mingw\samples\cpp.