API concepts and basic datatypes
After installation, preparing a new OpenCV code project is quite a straightforward process that requires including the header files and instructing the compiler to find the files and libraries used in the project.
OpenCV is composed of several modules, grouping related functionalities. Each module has an associated header file (for example, core.hpp) located in the directory with the same name as that of the module (that is, OPENCV_BUILD\install\include\opencv2\<module>). The supplied modules with the current version of OpenCV are as follows:
core: This module defines the basic (core) functions used by all the other modules and fundamental data structures, including the dense multidimensional array,Mat.highgui: This module provides simple user interface (UI) capabilities and an easy interface for video and image capturing. Building the library with the Qt option allows UI compatibility with such frameworks.imgproc: This module includes image-processing functions that include filtering (linear and nonlinear), geometric transformations, color space conversion, and so on.features2d: This module includes functions for feature detection (corners and planar objects), feature description, feature matching, and so on.objdetect: This module includes functions for object detection and instances of the predefined detection classes (for example, face, eyes, smile, people, cars, and so on).video: This module supplies the functionality of video analysis (motion estimation, background extraction, and object tracking).gpu: This module provides a collection of GPU-accelerated algorithms for some functions in the other OpenCV modules.ml: This module includes functions to implement machine-learning tools such as statistical classification, regression, and data clustering.- Some other less usual miscellaneous modules oriented are camera calibration, clustering, computational photography, images stitching, OpenCL-accelerated CV, super resolution, and others.
All OpenCV classes and functions are in the cv namespace. Consequently, we will have the following two options in our source code:
- Add the
using namespace cvdeclaration after including the header files (this is the option used in all the code samples in this book). - Append the
cv::specifier as a prefix to all the OpenCV classes, functions, and data structures that we use. This option is recommended if the external names provided by OpenCV conflict with the standard template library (STL) or other libraries.
The DataType class defines the primitive datatypes for OpenCV. The primitive datatypes can be bool, unsigned char, signed char, unsigned short, signed short, int, float, double, or a tuple of values of one of these primitive types. Any primitive type can be defined by an identifier in the following form:
CV_<bit depth>{U|S|F}C(<number of channels>)
In the preceding code, U, S, and F stand for unsigned, signed, and float respectively. For the single channel arrays, the following enumeration is applied describing the datatypes:
enum {CV_8U=0, CV_8S=1, CV_16U=2, CV_16S=3, CV_32S=4, CV_32F=5, CV_64F=6};
The following diagram shows a graphical representation of a single channel (4 x 4) array with 8 bits of unsigned integers (CV_8U). In this case, each element should have a value from zero to 255, which may be represented by a grayscale image.
Single channel array of 8 bit unsigned integers for a greyscale image
We can define all of the preceding datatypes for multichannel arrays (up to 512 channels). The following diagram illustrates a graphical representation of three channels 4 x 4 array of 8 bits of unsigned integers (CV_8UC3). In this example, the array consists of tuples of three elements corresponding to an RGB image.
A three-channel array of 8 bit unsigned integers for an RGB image
The OpenCV Mat class is used for dense n-dimensional single or multichannel arrays. It can store real or complex-valued vectors and matrices, colored or grayscale images, histograms, point clouds, and so on. There are many different ways to create a Mat object, the most popular being the constructor where the size and type of the array are specified as follows:
Mat(nrows, ncols, type[, fillValue])
The initial value for the array elements might be set by the Scalar class as a typical four-element vector (for the RGB and transparency components of the image stored in the array). Next, we show some usage examples of Mat as follows:
Mat img_A(640, 480, CV_8U, Scalar(255)); // white image // 640 x 480 single-channel array with 8 bits of unsigned integers // (up to 255 values, valid for a grayscale image, for example, // 255=white) … Mat img_B(Size(800, 600), CV_8UC3, Scalar(0,255,0)); // Green image // 800 x 600 three channel array with 8 bits of unsigned integers // (up to 24 bits color depth, valid for a RGB color image)
The Mat class is the main data structure that stores and manipulates images. OpenCV has implemented mechanisms to allocate and release memory automatically for these data structures. However, the programmer should still take special care when data structures share the same buffer memory.
Many functions in OpenCV process dense single or multichannel arrays usually using the Mat class. However, in some cases, a different datatype may be convenient, such as std::vector<>, Matx<>, Vec<>, or Scalar. For this purpose, OpenCV provides the proxy classes, InputArray and OutputArray, which allow any of the previous types to be used as parameters for functions.