25-04-2014, 03:26 PM
The OpenCV Reference Manual
INTRODUCTION
OpenCV (Open Source Computer Vision Library: http://opencv.org) is an open-source BSD-licensed library that
includes several hundreds of computer vision algorithms. The document describes the so-called OpenCV 2.x API,
which is essentially a C++ API, as opposite to the C-based OpenCV 1.x API. The latter is described in opencv1x.pdf.
OpenCV has a modular structure, which means that the package includes several shared or static libraries. The
following modules are available:
• core - a compact module defining basic data structures, including the dense multi-dimensional array Mat and
basic functions used by all other modules.
• imgproc - an image processing module that includes linear and non-linear image filtering, geometrical image
transformations (resize, affine and perspective warping, generic table-based remapping), color space conversion,
histograms, and so on.
• video - a video analysis module that includes motion estimation, background subtraction, and object tracking
algorithms.
• calib3d - basic multiple-view geometry algorithms, single and stereo camera calibration, object pose estimation,
stereo correspondence algorithms, and elements of 3D reconstruction.
• features2d - salient feature detectors, descriptors, and descriptor matchers.
• objdetect - detection of objects and instances of the predefined classes (for example, faces, eyes, mugs, people,
cars, and so on).
• highgui - an easy-to-use interface to video capturing, image and video codecs, as well as simple UI capabilities.
• gpu - GPU-accelerated algorithms from different OpenCV modules.
• ... some other helper modules, such as FLANN and Google test wrappers, Python bindings, and others.
The further chapters of the document describe functionality of each module. But first, make sure to get familiar with
the common API concepts used thoroughly in the library.
Automatic Memory Management
OpenCV handles all the memory automatically.
First of all, std::vector, Mat, and other data structures used by the functions and methods have destructors that
deallocate the underlying memory buffers when needed. This means that the destructors do not always deallocate the
buffers as in case of Mat. They take into account possible data sharing. A destructor decrements the reference counter
associated with the matrix data buffer. The buffer is deallocated if and only if the reference counter reaches zero, that
is, when no other structures refer to the same buffer. Similarly, when a Mat instance is copied, no actual data is really
copied. Instead, the reference counter is incremented to memorize that there is another owner of the same data.
Fixed Pixel Types. Limited Use of Templates
Templates is a great feature of C++ that enables implementation of very powerful, efficient and yet safe data struc-
tures and algorithms. However, the extensive use of templates may dramatically increase compilation time and code
size. Besides, it is difficult to separate an interface and implementation when templates are used exclusively. This
could be fine for basic algorithms but not good for computer vision libraries where a single algorithm may span thou-
sands lines of code. Because of this and also to simplify development of bindings for other languages, like Python,
Java, Matlab that do not have templates at all or have limited template capabilities, the current OpenCV implemen-
tation is based on polymorphism and runtime dispatching over templates. In those places where runtime dispatching
would be too slow (like pixel access operators), impossible (generic Ptr<> implementation), or just very inconve-
nient (saturate_cast<>()) the current implementation introduces small template classes, methods, and functions.
Anywhere else in the current OpenCV version the use of templates is limited.
Error Handling
OpenCV uses exceptions to signal critical errors. When the input data has a correct format and belongs to the specified
value range, but the algorithm cannot succeed for some reason (for example, the optimization algorithm did not
converge), it returns a special error code (typically, just a boolean variable).
The exceptions can be instances of the cv::Exception class or its derivatives. In its turn, cv::Exception is a deriva-
tive of std::exception. So it can be gracefully handled in the code using other standard C++ library components.
The exception is typically thrown either using the CV_Error(errcode, description) macro, or its printf-like
CV_Error_(errcode, printf-spec, (printf-args)) variant, or using the CV_Assert(condition) macro that
checks the condition and throws an exception when it is not satisfied. For performance-critical code, there is
CV_DbgAssert(condition) that is only retained in the Debug configuration. Due to the automatic memory man-
agement, all the intermediate buffers are automatically deallocated in case of a sudden error.