generic-library/opencv
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Purpose: 2nd review cycle

Browse Source
This commit is contained in:
Elena Fedotova 2011-05-23 21:20:31 +00:00
parent 0848a2d67f
commit 37f745737b
1 changed files with 17 additions and 15 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

32
modules/core/doc/intro.rst
View File

@ -100,9 +100,9 @@ description for details.
Automatic Allocation of the Output Data
---------------------------------------
OpenCV does not only deallocate the memory automatically, it can also automatically allocate the memory for output function parameters most of the time. So, if a function has one or more input arrays (``cv::Mat`` instances) and some output arrays, the output arrays are automatically allocated or reallocated. The size and type of the output arrays are determined from the size and type of input arrays. If needed, the functions take extra parameters that help to figure out the output array properties.
OpenCV deallocates the memory automatically, as well as automatically allocates the memory for output function parameters most of the time. So, if a function has one or more input arrays (``cv::Mat`` instances) and some output arrays, the output arrays are automatically allocated or reallocated. The size and type of the output arrays are determined from the size and type of input arrays. If needed, the functions take extra parameters that help to figure out the output array properties.
Here is the example: ::
Example: ::
#include "cv.h"
#include "highgui.h"
@ -128,26 +128,26 @@ Here is the example: ::
return 0;
}
The array ``frame`` is automatically allocated by the ``>>`` operator, since the video frame resolution and bit-depth is known to the video capturing module. The array ``edges`` is automatically allocated by the ``cvtColor`` function. It has the same size and the bit-depth as the input array. The number of channels is 1 because the color conversion code ``CV_BGR2GRAY`` is passed, which means color to grayscale conversion. Note that ``frame`` and ``edges`` are allocated only once during the first execution of the loop body, since all the next video frames have the same resolution. If you somehow change the video resolution, the arrays are automatically reallocated.
The array ``frame`` is automatically allocated by the ``>>`` operator since the video frame resolution and the bit-depth is known to the video capturing module. The array ``edges`` is automatically allocated by the ``cvtColor`` function. It has the same size and the bit-depth as the input array. The number of channels is 1 because the color conversion code ``CV_BGR2GRAY`` is passed, which means a color to grayscale conversion. Note that ``frame`` and ``edges`` are allocated only once during the first execution of the loop body since all the next video frames have the same resolution. If you somehow change the video resolution, the arrays are automatically reallocated.
The key component of this technology is the ``Mat::create`` method. It takes the desired array size and type. If the array already has the specified size and type, the method does nothing. Otherwise, it releases the previously allocated data, if any (this part involves decrementing the reference counter and comparing it with zero), and then allocates a new buffer of the required size. Most functions call this the ``Mat::create`` method for each output array and so the automatic output data allocation is implemented.
The key component of this technology is the ``Mat::create`` method. It takes the desired array size and type. If the array already has the specified size and type, the method does nothing. Otherwise, it releases the previously allocated data, if any (this part involves decrementing the reference counter and comparing it with zero), and then allocates a new buffer of the required size. Most functions call the ``Mat::create`` method for each output array, and so the automatic output data allocation is implemented.
Some notable exceptions from this scheme are ``cv::mixChannels``, ``cv::RNG::fill``, and a few other functions and methods. They are not able to allocate the output array, so you have to do this in advance.
Saturation Arithmetics
----------------------
As a computer vision library, OpenCV deals a lot with image pixels that are often encoded in a compact, 8- or 16-bit per channel, form and thus have a limited value range. Furthermore, certain operations on images, like color space conversions, brightness/contrast adjustments, sharpening, complex interpolation (bi-cubic, Lanczos) can produce values out of the available range. If you just store the lowest 8 (16) bit of the result, this will result in some visual artifacts and may affect the further image analysis. To solve this problem, the so-called *saturation* arithmetics is used. For example, to store ``r``, a result of an operation, to an 8-bit image, we find the nearest value within 0..255 range:
As a computer vision library, OpenCV deals a lot with image pixels that are often encoded in a compact, 8- or 16-bit per channel, form and thus have a limited value range. Furthermore, certain operations on images, like color space conversions, brightness/contrast adjustments, sharpening, complex interpolation (bi-cubic, Lanczos) can produce values out of the available range. If you just store the lowest 8 (16) bits of the result, this results in visual artifacts and may affect a further image analysis. To solve this problem, the so-called *saturation* arithmetics is used. For example, to store ``r``, the result of an operation, to an 8-bit image, you find the nearest value within the 0..255 range:
.. math::
I(x,y)= \min ( \max (\textrm{round}(r), 0), 255)
The similar rules are applied to 8-bit signed and 16-bit signed and unsigned types. This semantics is used everywhere in the library. In C++ code, it is done using ``saturate_cast<>`` functions that resemble standard C++ cast operations. Here is the implementation of the formula provided above::
Similar rules are applied to 8-bit signed, 16-bit signed and unsigned types. This semantics is used everywhere in the library. In C++ code, it is done using the ``saturate_cast<>`` functions that resemble standard C++ cast operations. See below the implementation of the formula provided above::
I.at<uchar>(y, x) = saturate_cast<uchar>(r);
where ``cv::uchar`` is an OpenCV 8-bit unsigned integer type. In the optimized SIMD code, instructions like SSE2' ``paddusb``, ``packuswb``, and so on are used. They help achieve exactly the same behavior as in C++ code.
where ``cv::uchar`` is an OpenCV 8-bit unsigned integer type. In the optimized SIMD code, such SSE2 instructions as ``paddusb``, ``packuswb``, and so on are used. They help achieve exactly the same behavior as in C++ code.
Fixed Pixel Types. Limited Use of Templates
-------------------------------------------
@ -163,17 +163,19 @@ There is a limited fixed set of primitive data types the library can operate on.
* 32-bit signed integer (int)
* 32-bit floating-point number (float)
* 64-bit floating-point number (double)
* a tuple of several elements, where all elements have the same type (one of the above). An array, whose elements are such tuples, are called multi-channel arrays, as opposite to the single-channel arrays, whose elements are scalar values. The maximum possible number of channels is defined by the ``CV_CN_MAX`` constant (which is not smaller than 32).
* a tuple of several elements where all elements have the same type (one of the above). An array whose elements are such tuples, are called multi-channel arrays, as opposite to the single-channel arrays, whose elements are scalar values. The maximum possible number of channels is defined by the ``CV_CN_MAX`` constant, which is not smaller than 32.
For these basic types, the following enumeration is applied::
enum { CV_8U=0, CV_8S=1, CV_16U=2, CV_16S=3, CV_32S=4, CV_32F=5, CV_64F=6 };
Multi-channel (``n``-channel) types can be specified using the ``CV_8UC1`` ... ``CV_64FC4`` constants (for number of channels from 1 to 4), or using the ``CV_8UC(n)`` ... ``CV_64FC(n)`` or ``CV_MAKETYPE(CV_8U, n)`` ... ``CV_MAKETYPE(CV_64F, n)`` macros when the number of channels is more than 4 or unknown at compilation time.
Multi-channel (``n``-channel) types can be specified using the following options:
.. note:: ``CV_32FC1 == CV_32F``, ``CV_32FC2 == CV_32FC(2) == CV_MAKETYPE(CV_32F, 2)``, and ``CV_MAKETYPE(depth, n) == ((x&7)<<3) + (n-1)``, that is, the constant type is formed from the ``depth``, taking the lowest 3 bits, and the number of channels minus 1, taking the next ``log2(CV_CN_MAX)`` bits.
* ``CV_8UC1`` ... ``CV_64FC4`` constants (for a number of channels from 1 to 4)
* ``CV_8UC(n)`` ... ``CV_64FC(n)`` or ``CV_MAKETYPE(CV_8U, n)`` ... ``CV_MAKETYPE(CV_64F, n)`` macros when the number of channels is more than 4 or unknown at the compilation time.
Here are some examples::
.. note:: ``CV_32FC1 == CV_32F``, ``CV_32FC2 == CV_32FC(2) == CV_MAKETYPE(CV_32F, 2)``, and ``CV_MAKETYPE(depth, n) == ((x&7)<<3) + (n-1)``. This means that the constant type is formed from the ``depth``, taking the lowest 3 bits, and the number of channels minus 1, taking the next ``log2(CV_CN_MAX)`` bits.
Examples::
Mat mtx(3, 3, CV_32F); // make a 3x3 floating-point matrix
Mat cmtx(10, 1, CV_64FC2); // make a 10x1 2-channel floating-point
@ -184,7 +186,7 @@ Here are some examples::
// the same size and same
// channel type as img
Arrays, whose elements are more complex, cannot be constructed or processed using OpenCV. Furthermore, each function or method can handle only a subset of all possible array types. Usually, the more complex is the algorithm, the smaller the supported subset of formats is. Here are some typical examples of such limitations:
Arrays with more complex elements cannot be constructed or processed using OpenCV. Furthermore, each function or method can handle only a subset of all possible array types. Usually, the more complex the algorithm is, the smaller the supported subset of formats is. See below typical examples of such limitations:
* The face detection algorithm only works with 8-bit grayscale or color images.
* Linear algebra functions and most of the machine learning algorithms work with floating-point arrays only.
@ -197,11 +199,11 @@ The subset of supported types for each functions has been defined from practical
Error Handling
--------------
OpenCV uses exceptions to signal critical errors. When the input data has a correct format and within the specified value range, but the algorithm cannot succeed for some reason (for exampl, the optimization algorithm did not converge), it returns a special error code (typically, just a boolean variable).
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 derivative of ``std::exception``, so it can be gracefully handled in the code using other standard C++ library components.
The exceptions can be instances of the ``cv::Exception`` class or its derivatives. In its turn, ``cv::Exception`` is a derivative of ``std::exception``. So it can be gracefully handled in the code using other standard C++ library components.
The exception is typically thrown using either 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. Thanks to the automatic memory management, all the intermediate buffers are automatically deallocated in the case of sudden error. You only need to add a try statement to catch the exceptions, if needed: ::
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 management, all the intermediate buffers are automatically deallocated in case of a sudden error. You only need to add a try statement to catch exceptions, if needed: ::
try
{