Module Opencv

Usage: border_interpolate p len border_type

Computes the source location of an extrapolated pixel.

The function computes and returns the coordinate of a donor pixel corresponding to the specified extrapolated pixel when using the specified extrapolation border mode. For example, if you use cv::BORDER_WRAP mode in the horizontal direction, cv::BORDER_REFLECT_101 in the vertical direction and want to compute value of the "virtual" pixel Point(-5, 100) in a floating-point image img , it looks like:

float val = img.at<float>(borderInterpolate(100, img.rows, cv::BORDER_REFLECT_101),
                          borderInterpolate(-5, img.cols, cv::BORDER_WRAP));

Normally, the function is not called directly. It is used inside filtering functions and also in copyMakeBorder.

• Parameter: p: 0-based coordinate of the extrapolated pixel along one of the axes, likely \<0 or \>= len
• Parameter: len: Length of the array along the corresponding axis.
• Parameter: border_type: Border type, one of the #BorderTypes, except for #BORDER_TRANSPARENT and #BORDER_ISOLATED . When borderType==#BORDER_CONSTANT , the function always returns -1, regardless of p and len.

See also: copyMakeBorder

Usage: copy_make_border ?dst ?value src top bottom left right border_type

Forms a border around an image.

The function copies the source image into the middle of the destination image. The areas to the left, to the right, above and below the copied source image will be filled with extrapolated pixels. This is not what filtering functions based on it do (they extrapolate pixels on-fly), but what other more complex functions, including your own, may do to simplify image boundary handling.

The function supports the mode when src is already in the middle of dst . In this case, the function does not copy src itself but simply constructs the border, for example:

// let border be the same in all directions
int border=2;
// constructs a larger image to fit both the image and the border
Mat gray_buf(rgb.rows + border*2, rgb.cols + border*2, rgb.depth());
// select the middle part of it w/o copying data
Mat gray(gray_canvas, Rect(border, border, rgb.cols, rgb.rows));
// convert image from RGB to grayscale
cvtColor(rgb, gray, COLOR_RGB2GRAY);
// form a border in-place
copyMakeBorder(gray, gray_buf, border, border,
               border, border, BORDER_REPLICATE);
// now do some custom filtering ...
...

Note: When the source image is a part (ROI) of a bigger image, the function will try to use the pixels outside of the ROI to form a border. To disable this feature and always do extrapolation, as if src was not a ROI, use borderType | #BORDER_ISOLATED.

• Parameter: src: Source image.
• Parameter: dst: Destination image of the same type as src and the size Size(src.cols+left+right, src.rows+top+bottom) .
• Parameter: top: the top pixels
• Parameter: bottom: the bottom pixels
• Parameter: left: the left pixels
• Parameter: right: Parameter specifying how many pixels in each direction from the source image rectangle to extrapolate. For example, top=1, bottom=1, left=1, right=1 mean that 1 pixel-wide border needs to be built.
• Parameter: border_type: Border type. See borderInterpolate for details.
• Parameter: value: Border value if borderType==BORDER_CONSTANT .

See also: borderInterpolate

Usage: add ?dst ?mask ?dtype src1 src2

Calculates the per-element sum of two arrays or an array and a scalar.

The function add calculates:

• Sum of two arrays when both input arrays have the same size and the same number of channels: \texttt{dst}(I) = \texttt{saturate} ( \texttt{src1}(I) + \texttt{src2}(I)) \quad \texttt{if mask}(I) \ne0
• Sum of an array and a scalar when src2 is constructed from Scalar or has the same number of elements as src1.channels(): \texttt{dst}(I) = \texttt{saturate} ( \texttt{src1}(I) + \texttt{src2} ) \quad \texttt{if mask}(I) \ne0
• Sum of a scalar and an array when src1 is constructed from Scalar or has the same number of elements as src2.channels(): \texttt{dst}(I) = \texttt{saturate} ( \texttt{src1} + \texttt{src2}(I) ) \quad \texttt{if mask}(I) \ne0 where I is a multi-dimensional index of array elements. In case of multi-channel arrays, each channel is processed independently.

The first function in the list above can be replaced with matrix expressions:

dst = src1 + src2;
dst += src1; // equivalent to add(dst, src1, dst);

The input arrays and the output array can all have the same or different depths. For example, you can add a 16-bit unsigned array to a 8-bit signed array and store the sum as a 32-bit floating-point array. Depth of the output array is determined by the dtype parameter. In the second and third cases above, as well as in the first case, when src1.depth() == src2.depth(), dtype can be set to the default -1. In this case, the output array will have the same depth as the input array, be it src1, src2 or both. Note: Saturation is not applied when the output array has the depth CV_32S. You may even get result of an incorrect sign in the case of overflow.

• Parameter: src1: first input array or a scalar.
• Parameter: src2: second input array or a scalar.
• Parameter: dst: output array that has the same size and number of channels as the input array(s); the depth is defined by dtype or src1/src2.
• Parameter: mask: optional operation mask - 8-bit single channel array, that specifies elements of the output array to be changed.
• Parameter: dtype: optional depth of the output array (see the discussion below). See also: subtract, addWeighted, scaleAdd, Mat::convertTo

Usage: subtract ?dst ?mask ?dtype src1 src2

Calculates the per-element difference between two arrays or array and a scalar.

The function subtract calculates:

• Difference between two arrays, when both input arrays have the same size and the same number of channels: \texttt{dst}(I) = \texttt{saturate} ( \texttt{src1}(I) - \texttt{src2}(I)) \quad \texttt{if mask}(I) \ne0
• Difference between an array and a scalar, when src2 is constructed from Scalar or has the same number of elements as src1.channels(): \texttt{dst}(I) = \texttt{saturate} ( \texttt{src1}(I) - \texttt{src2} ) \quad \texttt{if mask}(I) \ne0
• Difference between a scalar and an array, when src1 is constructed from Scalar or has the same number of elements as src2.channels(): \texttt{dst}(I) = \texttt{saturate} ( \texttt{src1} - \texttt{src2}(I) ) \quad \texttt{if mask}(I) \ne0
• The reverse difference between a scalar and an array in the case of SubRS: \texttt{dst}(I) = \texttt{saturate} ( \texttt{src2} - \texttt{src1}(I) ) \quad \texttt{if mask}(I) \ne0 where I is a multi-dimensional index of array elements. In case of multi-channel arrays, each channel is processed independently.

The first function in the list above can be replaced with matrix expressions:

dst = src1 - src2;
dst -= src1; // equivalent to subtract(dst, src1, dst);

The input arrays and the output array can all have the same or different depths. For example, you can subtract to 8-bit unsigned arrays and store the difference in a 16-bit signed array. Depth of the output array is determined by dtype parameter. In the second and third cases above, as well as in the first case, when src1.depth() == src2.depth(), dtype can be set to the default -1. In this case the output array will have the same depth as the input array, be it src1, src2 or both. Note: Saturation is not applied when the output array has the depth CV_32S. You may even get result of an incorrect sign in the case of overflow.

• Parameter: src1: first input array or a scalar.
• Parameter: src2: second input array or a scalar.
• Parameter: dst: output array of the same size and the same number of channels as the input array.
• Parameter: mask: optional operation mask; this is an 8-bit single channel array that specifies elements of the output array to be changed.
• Parameter: dtype: optional depth of the output array See also: add, addWeighted, scaleAdd, Mat::convertTo

Usage: multiply ?dst ?scale ?dtype src1 src2

Calculates the per-element scaled product of two arrays.

The function multiply calculates the per-element product of two arrays:

\texttt{dst} (I)= \texttt{saturate} ( \texttt{scale} \cdot \texttt{src1} (I) \cdot \texttt{src2} (I))

There is also a MatrixExpressions -friendly variant of the first function. See Mat::mul .

For a not-per-element matrix product, see gemm .

Note: Saturation is not applied when the output array has the depth CV_32S. You may even get result of an incorrect sign in the case of overflow.

• Parameter: src1: first input array.
• Parameter: src2: second input array of the same size and the same type as src1.
• Parameter: dst: output array of the same size and type as src1.
• Parameter: scale: optional scale factor.
• Parameter: dtype: optional depth of the output array See also: add, subtract, divide, scaleAdd, addWeighted, accumulate, accumulateProduct, accumulateSquare, Mat::convertTo

Usage: divide1 ?dst ?scale ?dtype src1 src2

Performs per-element division of two arrays or a scalar by an array.

The function cv::divide divides one array by another: \texttt{dst(I) = saturate(src1(I)*scale/src2(I))} or a scalar by an array when there is no src1 : \texttt{dst(I) = saturate(scale/src2(I))}

Different channels of multi-channel arrays are processed independently.

For integer types when src2(I) is zero, dst(I) will also be zero.

Note: In case of floating point data there is no special defined behavior for zero src2(I) values. Regular floating-point division is used. Expect correct IEEE-754 behaviour for floating-point data (with NaN, Inf result values).

Note: Saturation is not applied when the output array has the depth CV_32S. You may even get result of an incorrect sign in the case of overflow.

• Parameter: src1: first input array.
• Parameter: src2: second input array of the same size and type as src1.
• Parameter: scale: scalar factor.
• Parameter: dst: output array of the same size and type as src2.
• Parameter: dtype: optional depth of the output array; if -1, dst will have depth src2.depth(), but in case of an array-by-array division, you can only pass -1 when src1.depth()==src2.depth(). See also: multiply, add, subtract

Usage: divide2 ?dst ?dtype scale src2

Usage: scale_add ?dst src1 alpha src2

Calculates the sum of a scaled array and another array.

The function scaleAdd is one of the classical primitive linear algebra operations, known as DAXPY or SAXPY in BLAS(http://en.wikipedia.org/wiki/Basic_Linear_Algebra_Subprograms). It calculates the sum of a scaled array and another array: \texttt{dst} (I)= \texttt{scale} \cdot \texttt{src1} (I) + \texttt{src2} (I) The function can also be emulated with a matrix expression, for example:

Mat A(3, 3, CV_64F);
...
A.row(0) = A.row(1)*2 + A.row(2);

• Parameter: src1: first input array.
• Parameter: alpha: scale factor for the first array.
• Parameter: src2: second input array of the same size and type as src1.
• Parameter: dst: output array of the same size and type as src1. See also: add, addWeighted, subtract, Mat::dot, Mat::convertTo

Usage: add_weighted ?dst ?dtype src1 alpha src2 beta gamma

Calculates the weighted sum of two arrays.

The function addWeighted calculates the weighted sum of two arrays as follows: \texttt{dst} (I)= \texttt{saturate} ( \texttt{src1} (I)* \texttt{alpha} + \texttt{src2} (I)* \texttt{beta} + \texttt{gamma} ) where I is a multi-dimensional index of array elements. In case of multi-channel arrays, each channel is processed independently. The function can be replaced with a matrix expression:

dst = src1*alpha + src2*beta + gamma;

Note: Saturation is not applied when the output array has the depth CV_32S. You may even get result of an incorrect sign in the case of overflow.

• Parameter: src1: first input array.
• Parameter: alpha: weight of the first array elements.
• Parameter: src2: second input array of the same size and channel number as src1.
• Parameter: beta: weight of the second array elements.
• Parameter: gamma: scalar added to each sum.
• Parameter: dst: output array that has the same size and number of channels as the input arrays.
• Parameter: dtype: optional depth of the output array; when both input arrays have the same depth, dtype can be set to -1, which will be equivalent to src1.depth(). See also: add, subtract, scaleAdd, Mat::convertTo

Usage: convert_scale_abs ?dst ?alpha ?beta src

Scales, calculates absolute values, and converts the result to 8-bit.

On each element of the input array, the function convertScaleAbs performs three operations sequentially: scaling, taking an absolute value, conversion to an unsigned 8-bit type: \texttt{dst} (I)= \texttt{saturate\_cast<uchar>} (| \texttt{src} (I)* \texttt{alpha} + \texttt{beta} |) In case of multi-channel arrays, the function processes each channel independently. When the output is not 8-bit, the operation can be emulated by calling the Mat::convertTo method (or by using matrix expressions) and then by calculating an absolute value of the result. For example:

Mat_<float> A(30,30);
randu(A, Scalar(-100), Scalar(100));
Mat_<float> B = A*5 + 3;
B = abs(B);
// Mat_<float> B = abs(A*5+3) will also do the job,
// but it will allocate a temporary matrix

• Parameter: src: input array.
• Parameter: dst: output array.
• Parameter: alpha: optional scale factor.
• Parameter: beta: optional delta added to the scaled values. See also: Mat::convertTo, cv::abs(const Mat&)

Usage: convert_fp16 ?dst src

Converts an array to half precision floating number.

This function converts FP32 (single precision floating point) from/to FP16 (half precision floating point). CV_16S format is used to represent FP16 data. There are two use modes (src -> dst): CV_32F -> CV_16S and CV_16S -> CV_32F. The input array has to have type of CV_32F or CV_16S to represent the bit depth. If the input array is neither of them, the function will raise an error. The format of half precision floating point is defined in IEEE 754-2008.

• Parameter: src: input array.
• Parameter: dst: output array.

Usage: lut ?dst src lut

Performs a look-up table transform of an array.

The function LUT fills the output array with values from the look-up table. Indices of the entries are taken from the input array. That is, the function processes each element of src as follows: \texttt{dst} (I) \leftarrow \texttt{lut(src(I) + d)} where d = \fork{0}{if \(\texttt{src}\) has depth \(\texttt{CV_8U}\)}{128}{if \(\texttt{src}\) has depth \(\texttt{CV_8S}\)}

• Parameter: src: input array of 8-bit elements.
• Parameter: lut: look-up table of 256 elements; in case of multi-channel input array, the table should either have a single channel (in this case the same table is used for all channels) or the same number of channels as in the input array.
• Parameter: dst: output array of the same size and number of channels as src, and the same depth as lut. See also: convertScaleAbs, Mat::convertTo

Usage: sum src

Calculates the sum of array elements.

The function cv::sum calculates and returns the sum of array elements, independently for each channel.

• Parameter: src: input array that must have from 1 to 4 channels. See also: countNonZero, mean, meanStdDev, norm, minMaxLoc, reduce

Usage: count_non_zero src

Counts non-zero array elements.

The function returns the number of non-zero elements in src : \; \texttt{src} (I) \ne0 } 1

• Parameter: src: single-channel array. See also: mean, meanStdDev, norm, minMaxLoc, calcCovarMatrix

Usage: find_non_zero ?idx src

Returns the list of locations of non-zero pixels

Given a binary matrix (likely returned from an operation such as threshold(), compare(), >, ==, etc, return all of the non-zero indices as a cv::Mat or std::vector<cv::Point> (x,y) For example:

cv::Mat binaryImage; // input, binary image
cv::Mat locations;   // output, locations of non-zero pixels
cv::findNonZero(binaryImage, locations);

// access pixel coordinates
Point pnt = locations.at<Point>(i);

or

cv::Mat binaryImage; // input, binary image
vector<Point> locations;   // output, locations of non-zero pixels
cv::findNonZero(binaryImage, locations);

// access pixel coordinates
Point pnt = locations[i];

• Parameter: src: single-channel array
• Parameter: idx: the output array, type of cv::Mat or std::vector<Point>, corresponding to non-zero indices in the input

Usage: mean ?mask src

Calculates an average (mean) of array elements.

The function cv::mean calculates the mean value M of array elements, independently for each channel, and return it: \; \texttt{mask} (I) \ne 0} 1 \\ M_c = \left ( \sum _{I: \; \texttt{mask} (I) \ne 0}{ \texttt{mtx} (I)_c} \right )/N \end{array} When all the mask elements are 0's, the function returns Scalar::all(0)

• Parameter: src: input array that should have from 1 to 4 channels so that the result can be stored in Scalar_ .
• Parameter: mask: optional operation mask. See also: countNonZero, meanStdDev, norm, minMaxLoc

Usage: mean_std_dev ?mean ?stddev ?mask src

Calculates a mean and standard deviation of array elements.

The function cv::meanStdDev calculates the mean and the standard deviation M of array elements independently for each channel and returns it via the output parameters: \; \texttt{mask}(I) \ne 0} \texttt{src} (I)_c}{N} \\ \texttt{stddev} _c = \sqrt{\frac{\sum_{ I: \; \texttt{mask}(I) \ne 0} \left ( \texttt{src} (I)_c - \texttt{mean} _c \right )^2}{N}} \end{array} When all the mask elements are 0's, the function returns mean=stddev=Scalar::all(0). Note: The calculated standard deviation is only the diagonal of the complete normalized covariance matrix. If the full matrix is needed, you can reshape the multi-channel array M x N to the single-channel array M\*N x mtx.channels() (only possible when the matrix is continuous) and then pass the matrix to calcCovarMatrix .

• Parameter: src: input array that should have from 1 to 4 channels so that the results can be stored in Scalar_ 's.
• Parameter: mean: output parameter: calculated mean value.
• Parameter: stddev: output parameter: calculated standard deviation.
• Parameter: mask: optional operation mask. See also: countNonZero, mean, norm, minMaxLoc, calcCovarMatrix

Usage: norm1 ?norm_type ?mask src1

Calculates the absolute norm of an array.

This version of #norm calculates the absolute norm of src1. The type of norm to calculate is specified using #NormTypes.

As example for one array consider the function r(x)= \begin{pmatrix} x \\ 1-x \end{pmatrix}, x \in [-1;1] . The L_{1}, L_{2} and L_{\infty} norm for the sample value r(-1) = \begin{pmatrix} -1 \\ 2 \end{pmatrix} is calculated as follows \| r(-1) \|_{L_1} &= |-1| + |2| = 3 \\ \| r(-1) \|_{L_2} &= \sqrt{(-1)^{2} + (2)^{2}} = \sqrt{5} \\ \| r(-1) \|_{L_\infty} &= \max(|-1|,|2|) = 2 and for r(0.5) = \begin{pmatrix} 0.5 \\ 0.5 \end{pmatrix} the calculation is \| r(0.5) \|_{L_1} &= |0.5| + |0.5| = 1 \\ \| r(0.5) \|_{L_2} &= \sqrt{(0.5)^{2} + (0.5)^{2}} = \sqrt{0.5} \\ \| r(0.5) \|_{L_\infty} &= \max(|0.5|,|0.5|) = 0.5. The following graphic shows all values for the three norm functions \| r(x) \|_{L_1}, \| r(x) \|_{L_2} and \| r(x) \|_{L_\infty} . It is notable that the L_{1} norm forms the upper and the L_{\infty} norm forms the lower border for the example function r(x) . !Graphs for the different norm functions from the above example(pics/NormTypes_OneArray_1-2-INF.png)

When the mask parameter is specified and it is not empty, the norm is

If normType is not specified, #NORM_L2 is used. calculated only over the region specified by the mask.

Multi-channel input arrays are treated as single-channel arrays, that is, the results for all channels are combined.

Hamming norms can only be calculated with CV_8U depth arrays.

• Parameter: src1: first input array.
• Parameter: norm_type: type of the norm (see #NormTypes).
• Parameter: mask: optional operation mask; it must have the same size as src1 and CV_8UC1 type.

Usage: norm2 ?norm_type ?mask src1 src2

Calculates an absolute difference norm or a relative difference norm.

This version of cv::norm calculates the absolute difference norm or the relative difference norm of arrays src1 and src2. The type of norm to calculate is specified using #NormTypes.

• Parameter: src1: first input array.
• Parameter: src2: second input array of the same size and the same type as src1.
• Parameter: norm_type: type of the norm (see #NormTypes).
• Parameter: mask: optional operation mask; it must have the same size as src1 and CV_8UC1 type.

Usage: psnr ?r src1 src2

Computes the Peak Signal-to-Noise Ratio (PSNR) image quality metric.

This function calculates the Peak Signal-to-Noise Ratio (PSNR) image quality metric in decibels (dB), between two input arrays src1 and src2. The arrays must have the same type.

The PSNR is calculated as follows:

\texttt{PSNR} = 10 \cdot \log_{10}{\left( \frac{R^2}{MSE} \right) }

where R is the maximum integer value of depth (e.g. 255 in the case of CV_8U data) and MSE is the mean squared error between the two arrays.

• Parameter: src1: first input array.
• Parameter: src2: second input array of the same size as src1.
• Parameter: r: the maximum pixel value (255 by default)

Usage: batch_distance ?dist ?nidx ?norm_type ?k ?mask ?update ?crosscheck src1 src2 dtype

naive nearest neighbor finder

see http://en.wikipedia.org/wiki/Nearest_neighbor_search TODO document

Usage: normalize ?alpha ?beta ?norm_type ?dtype ?mask src dst

Normalizes the norm or value range of an array.

The function cv::normalize normalizes scale and shift the input array elements so that \| \texttt{dst} \| _{L_p}= \texttt{alpha} (where p=Inf, 1 or 2) when normType=NORM_INF, NORM_L1, or NORM_L2, respectively; or so that \min _I \texttt{dst} (I)= \texttt{alpha} , \, \, \max _I \texttt{dst} (I)= \texttt{beta}

when normType=NORM_MINMAX (for dense arrays only). The optional mask specifies a sub-array to be normalized. This means that the norm or min-n-max are calculated over the sub-array, and then this sub-array is modified to be normalized. If you want to only use the mask to calculate the norm or min-max but modify the whole array, you can use norm and Mat::convertTo.

In case of sparse matrices, only the non-zero values are analyzed and transformed. Because of this, the range transformation for sparse matrices is not allowed since it can shift the zero level.

Possible usage with some positive example data:

vector<double> positiveData = { 2.0, 8.0, 10.0 };
vector<double> normalizedData_l1, normalizedData_l2, normalizedData_inf, normalizedData_minmax;

// Norm to probability (total count)
// sum(numbers) = 20.0
// 2.0      0.1     (2.0/20.0)
// 8.0      0.4     (8.0/20.0)
// 10.0     0.5     (10.0/20.0)
normalize(positiveData, normalizedData_l1, 1.0, 0.0, NORM_L1);

// Norm to unit vector: ||positiveData|| = 1.0
// 2.0      0.15
// 8.0      0.62
// 10.0     0.77
normalize(positiveData, normalizedData_l2, 1.0, 0.0, NORM_L2);

// Norm to max element
// 2.0      0.2     (2.0/10.0)
// 8.0      0.8     (8.0/10.0)
// 10.0     1.0     (10.0/10.0)
normalize(positiveData, normalizedData_inf, 1.0, 0.0, NORM_INF);

// Norm to range [0.0;1.0]
// 2.0      0.0     (shift to left border)
// 8.0      0.75    (6.0/8.0)
// 10.0     1.0     (shift to right border)
normalize(positiveData, normalizedData_minmax, 1.0, 0.0, NORM_MINMAX);

• Parameter: src: input array.
• Parameter: dst: output array of the same size as src .
• Parameter: alpha: norm value to normalize to or the lower range boundary in case of the range normalization.
• Parameter: beta: upper range boundary in case of the range normalization; it is not used for the norm normalization.
• Parameter: norm_type: normalization type (see cv::NormTypes).
• Parameter: dtype: when negative, the output array has the same type as src; otherwise, it has the same number of channels as src and the depth =CV_MAT_DEPTH(dtype).
• Parameter: mask: optional operation mask. See also: norm, Mat::convertTo, SparseMat::convertTo

Usage: min_max_loc ?max_val ?min_loc ?max_loc ?mask src min_val

Finds the global minimum and maximum in an array.

The function cv::minMaxLoc finds the minimum and maximum element values and their positions. The extremums are searched across the whole array or, if mask is not an empty array, in the specified array region.

The function do not work with multi-channel arrays. If you need to find minimum or maximum elements across all the channels, use Mat::reshape first to reinterpret the array as single-channel. Or you may extract the particular channel using either extractImageCOI , or mixChannels , or split .

• Parameter: src: input single-channel array.
• Parameter: min_val: pointer to the returned minimum value; NULL is used if not required.
• Parameter: max_val: pointer to the returned maximum value; NULL is used if not required.
• Parameter: min_loc: pointer to the returned minimum location (in 2D case); NULL is used if not required.
• Parameter: max_loc: pointer to the returned maximum location (in 2D case); NULL is used if not required.
• Parameter: mask: optional mask used to select a sub-array. See also: max, min, compare, inRange, extractImageCOI, mixChannels, split, Mat::reshape

Usage: reduce ?dst ?dtype src dim rtype

Reduces a matrix to a vector.

The function #reduce reduces the matrix to a vector by treating the matrix rows/columns as a set of 1D vectors and performing the specified operation on the vectors until a single row/column is obtained. For example, the function can be used to compute horizontal and vertical projections of a raster image. In case of #REDUCE_MAX and #REDUCE_MIN , the output image should have the same type as the source one. In case of #REDUCE_SUM and #REDUCE_AVG , the output may have a larger element bit-depth to preserve accuracy. And multi-channel arrays are also supported in these two reduction modes.

The following code demonstrates its usage for a single channel matrix. Snippet: snippets/core_reduce.cpp example

And the following code demonstrates its usage for a two-channel matrix. Snippet: snippets/core_reduce.cpp example2

• Parameter: src: input 2D matrix.
• Parameter: dst: output vector. Its size and type is defined by dim and dtype parameters.
• Parameter: dim: dimension index along which the matrix is reduced. 0 means that the matrix is reduced to a single row. 1 means that the matrix is reduced to a single column.
• Parameter: rtype: reduction operation that could be one of #ReduceTypes
• Parameter: dtype: when negative, the output vector will have the same type as the input matrix, otherwise, its type will be CV_MAKE_TYPE(CV_MAT_DEPTH(dtype), src.channels()). See also: repeat

Usage: merge ?dst mv

• Parameter: mv: input vector of matrices to be merged; all the matrices in mv must have the same size and the same depth.
• Parameter: dst: output array of the same size and the same depth as mv0; The number of channels will be the total number of channels in the matrix array.

Usage: split ?mv m

• Parameter: m: input multi-channel array.
• Parameter: mv: output vector of arrays; the arrays themselves are reallocated, if needed.

Usage: mix_channels src dst from_to

• Parameter: src: input array or vector of matrices; all of the matrices must have the same size and the same depth.
• Parameter: dst: output array or vector of matrices; all the matrices **must be allocated**; their size and depth must be the same as in src0.
• Parameter: from_to: array of index pairs specifying which channels are copied and where; fromTok\*2 is a 0-based index of the input channel in src, fromTok\*2+1 is an index of the output channel in dst; the continuous channel numbering is used: the first input image channels are indexed from 0 to src0.channels()-1, the second input image channels are indexed from src0.channels() to src0.channels() + src1.channels()-1, and so on, the same scheme is used for the output image channels; as a special case, when fromTok\*2 is negative, the corresponding output channel is filled with zero .

Usage: extract_channel ?dst src coi

Extracts a single channel from src (coi is 0-based index)

• Parameter: src: input array
• Parameter: dst: output array
• Parameter: coi: index of channel to extract See also: mixChannels, split

Usage: insert_channel src dst coi

Inserts a single channel to dst (coi is 0-based index)

• Parameter: src: input array
• Parameter: dst: output array
• Parameter: coi: index of channel for insertion See also: mixChannels, merge

Usage: flip ?dst src flip_code

Flips a 2D array around vertical, horizontal, or both axes.

The function cv::flip flips the array in one of three different ways (row and column indices are 0-based): \texttt{dst} _{ij} = \left\{ \begin{array}{l l} \texttt{src} _{\texttt{src.rows}-i-1,j} & if\; \texttt{flipCode} = 0 \\ \texttt{src} _{i, \texttt{src.cols} -j-1} & if\; \texttt{flipCode} > 0 \\ \texttt{src} _{ \texttt{src.rows} -i-1, \texttt{src.cols} -j-1} & if\; \texttt{flipCode} < 0 \\ \end{array} \right. The example scenarios of using the function are the following: * Vertical flipping of the image (flipCode == 0) to switch between top-left and bottom-left image origin. This is a typical operation in video processing on Microsoft Windows\* OS. * Horizontal flipping of the image with the subsequent horizontal shift and absolute difference calculation to check for a vertical-axis symmetry (flipCode \> 0). * Simultaneous horizontal and vertical flipping of the image with the subsequent shift and absolute difference calculation to check for a central symmetry (flipCode \< 0). * Reversing the order of point arrays (flipCode \> 0 or flipCode == 0).

• Parameter: src: input array.
• Parameter: dst: output array of the same size and type as src.
• Parameter: flip_code: a flag to specify how to flip the array; 0 means flipping around the x-axis and positive value (for example, 1) means flipping around y-axis. Negative value (for example, -1) means flipping around both axes. See also: transpose , repeat , completeSymm

Usage: rotate ?dst src rotate_code

Rotates a 2D array in multiples of 90 degrees. The function cv::rotate rotates the array in one of three different ways: * Rotate by 90 degrees clockwise (rotateCode = ROTATE_90_CLOCKWISE). * Rotate by 180 degrees clockwise (rotateCode = ROTATE_180). * Rotate by 270 degrees clockwise (rotateCode = ROTATE_90_COUNTERCLOCKWISE).

• Parameter: src: input array.
• Parameter: dst: output array of the same type as src. The size is the same with ROTATE_180, and the rows and cols are switched for ROTATE_90_CLOCKWISE and ROTATE_90_COUNTERCLOCKWISE.
• Parameter: rotate_code: an enum to specify how to rotate the array; see the enum #RotateFlags See also: transpose , repeat , completeSymm, flip, RotateFlags

Usage: repeat ?dst src ny nx

Fills the output array with repeated copies of the input array.

The function cv::repeat duplicates the input array one or more times along each of the two axes: \texttt{dst} _{ij}= \texttt{src} _{i\mod src.rows, \; j\mod src.cols } The second variant of the function is more convenient to use with MatrixExpressions.

• Parameter: src: input array to replicate.
• Parameter: ny: Flag to specify how many times the src is repeated along the vertical axis.
• Parameter: nx: Flag to specify how many times the src is repeated along the horizontal axis.
• Parameter: dst: output array of the same type as src. See also: cv::reduce

Usage: hconcat ?dst src

std::vector<cv::Mat> matrices = { cv::Mat(4, 1, CV_8UC1, cv::Scalar(1)),
                                  cv::Mat(4, 1, CV_8UC1, cv::Scalar(2)),
                                  cv::Mat(4, 1, CV_8UC1, cv::Scalar(3)),};

cv::Mat out;
cv::hconcat( matrices, out );
//out:
//[1, 2, 3;
// 1, 2, 3;
// 1, 2, 3;
// 1, 2, 3]

• Parameter: src: input array or vector of matrices. all of the matrices must have the same number of rows and the same depth.
• Parameter: dst: output array. It has the same number of rows and depth as the src, and the sum of cols of the src. same depth.

Usage: vconcat ?dst src

std::vector<cv::Mat> matrices = { cv::Mat(1, 4, CV_8UC1, cv::Scalar(1)),
                                  cv::Mat(1, 4, CV_8UC1, cv::Scalar(2)),
                                  cv::Mat(1, 4, CV_8UC1, cv::Scalar(3)),};

cv::Mat out;
cv::vconcat( matrices, out );
//out:
//[1,   1,   1,   1;
// 2,   2,   2,   2;
// 3,   3,   3,   3]

• Parameter: src: input array or vector of matrices. all of the matrices must have the same number of cols and the same depth
• Parameter: dst: output array. It has the same number of cols and depth as the src, and the sum of rows of the src. same depth.

Usage: bitwise_and ?dst ?mask src1 src2

computes bitwise conjunction of the two arrays (dst = src1 & src2) Calculates the per-element bit-wise conjunction of two arrays or an array and a scalar.

The function cv::bitwise_and calculates the per-element bit-wise logical conjunction for: * Two arrays when src1 and src2 have the same size: \texttt{dst} (I) = \texttt{src1} (I) \wedge \texttt{src2} (I) \quad \texttt{if mask} (I) \ne0 * An array and a scalar when src2 is constructed from Scalar or has the same number of elements as src1.channels(): \texttt{dst} (I) = \texttt{src1} (I) \wedge \texttt{src2} \quad \texttt{if mask} (I) \ne0 * A scalar and an array when src1 is constructed from Scalar or has the same number of elements as src2.channels(): \texttt{dst} (I) = \texttt{src1} \wedge \texttt{src2} (I) \quad \texttt{if mask} (I) \ne0 In case of floating-point arrays, their machine-specific bit representations (usually IEEE754-compliant) are used for the operation. In case of multi-channel arrays, each channel is processed independently. In the second and third cases above, the scalar is first converted to the array type.

• Parameter: src1: first input array or a scalar.
• Parameter: src2: second input array or a scalar.
• Parameter: dst: output array that has the same size and type as the input arrays.
• Parameter: mask: optional operation mask, 8-bit single channel array, that specifies elements of the output array to be changed.

Usage: bitwise_or ?dst ?mask src1 src2

Calculates the per-element bit-wise disjunction of two arrays or an array and a scalar.

The function cv::bitwise_or calculates the per-element bit-wise logical disjunction for: * Two arrays when src1 and src2 have the same size: \texttt{dst} (I) = \texttt{src1} (I) \vee \texttt{src2} (I) \quad \texttt{if mask} (I) \ne0 * An array and a scalar when src2 is constructed from Scalar or has the same number of elements as src1.channels(): \texttt{dst} (I) = \texttt{src1} (I) \vee \texttt{src2} \quad \texttt{if mask} (I) \ne0 * A scalar and an array when src1 is constructed from Scalar or has the same number of elements as src2.channels(): \texttt{dst} (I) = \texttt{src1} \vee \texttt{src2} (I) \quad \texttt{if mask} (I) \ne0 In case of floating-point arrays, their machine-specific bit representations (usually IEEE754-compliant) are used for the operation. In case of multi-channel arrays, each channel is processed independently. In the second and third cases above, the scalar is first converted to the array type.

• Parameter: src1: first input array or a scalar.
• Parameter: src2: second input array or a scalar.
• Parameter: dst: output array that has the same size and type as the input arrays.
• Parameter: mask: optional operation mask, 8-bit single channel array, that specifies elements of the output array to be changed.

Usage: bitwise_xor ?dst ?mask src1 src2

Calculates the per-element bit-wise "exclusive or" operation on two arrays or an array and a scalar.

The function cv::bitwise_xor calculates the per-element bit-wise logical "exclusive-or" operation for: * Two arrays when src1 and src2 have the same size: \texttt{dst} (I) = \texttt{src1} (I) \oplus \texttt{src2} (I) \quad \texttt{if mask} (I) \ne0 * An array and a scalar when src2 is constructed from Scalar or has the same number of elements as src1.channels(): \texttt{dst} (I) = \texttt{src1} (I) \oplus \texttt{src2} \quad \texttt{if mask} (I) \ne0 * A scalar and an array when src1 is constructed from Scalar or has the same number of elements as src2.channels(): \texttt{dst} (I) = \texttt{src1} \oplus \texttt{src2} (I) \quad \texttt{if mask} (I) \ne0 In case of floating-point arrays, their machine-specific bit representations (usually IEEE754-compliant) are used for the operation. In case of multi-channel arrays, each channel is processed independently. In the 2nd and 3rd cases above, the scalar is first converted to the array type.

• Parameter: src1: first input array or a scalar.
• Parameter: src2: second input array or a scalar.
• Parameter: dst: output array that has the same size and type as the input arrays.
• Parameter: mask: optional operation mask, 8-bit single channel array, that specifies elements of the output array to be changed.

Usage: bitwise_not ?dst ?mask src

Inverts every bit of an array.

The function cv::bitwise_not calculates per-element bit-wise inversion of the input array: \texttt{dst} (I) = \neg \texttt{src} (I) In case of a floating-point input array, its machine-specific bit representation (usually IEEE754-compliant) is used for the operation. In case of multi-channel arrays, each channel is processed independently.

• Parameter: src: input array.
• Parameter: dst: output array that has the same size and type as the input array.
• Parameter: mask: optional operation mask, 8-bit single channel array, that specifies elements of the output array to be changed.

Usage: absdiff ?dst src1 src2

Calculates the per-element absolute difference between two arrays or between an array and a scalar.

The function cv::absdiff calculates: * Absolute difference between two arrays when they have the same size and type: \texttt{dst}(I) = \texttt{saturate} (| \texttt{src1}(I) - \texttt{src2}(I)|) * Absolute difference between an array and a scalar when the second array is constructed from Scalar or has as many elements as the number of channels in src1: \texttt{dst}(I) = \texttt{saturate} (| \texttt{src1}(I) - \texttt{src2} |) * Absolute difference between a scalar and an array when the first array is constructed from Scalar or has as many elements as the number of channels in src2: \texttt{dst}(I) = \texttt{saturate} (| \texttt{src1} - \texttt{src2}(I) |) where I is a multi-dimensional index of array elements. In case of multi-channel arrays, each channel is processed independently. Note: Saturation is not applied when the arrays have the depth CV_32S. You may even get a negative value in the case of overflow.

• Parameter: src1: first input array or a scalar.
• Parameter: src2: second input array or a scalar.
• Parameter: dst: output array that has the same size and type as input arrays. See also: cv::abs(const Mat&)

Usage: copy_to ?dst src mask

This is an overloaded member function, provided for convenience (python) Copies the matrix to another one. When the operation mask is specified, if the Mat::create call shown above reallocates the matrix, the newly allocated matrix is initialized with all zeros before copying the data.

• Parameter: src: source matrix.
• Parameter: dst: Destination matrix. If it does not have a proper size or type before the operation, it is reallocated.
• Parameter: mask: Operation mask of the same size as \*this. Its non-zero elements indicate which matrix elements need to be copied. The mask has to be of type CV_8U and can have 1 or multiple channels.

Usage: in_range ?dst src lowerb upperb

Checks if array elements lie between the elements of two other arrays.

The function checks the range as follows:

• For every element of a single-channel input array: \texttt{dst} (I)= \texttt{lowerb} (I)_0 \leq \texttt{src} (I)_0 \leq \texttt{upperb} (I)_0
• For two-channel arrays: \texttt{dst} (I)= \texttt{lowerb} (I)_0 \leq \texttt{src} (I)_0 \leq \texttt{upperb} (I)_0 \land \texttt{lowerb} (I)_1 \leq \texttt{src} (I)_1 \leq \texttt{upperb} (I)_1
• and so forth.

That is, dst (I) is set to 255 (all 1 -bits) if src (I) is within the specified 1D, 2D, 3D, ... box and 0 otherwise.

When the lower and/or upper boundary parameters are scalars, the indexes (I) at lowerb and upperb in the above formulas should be omitted.

• Parameter: src: first input array.
• Parameter: lowerb: inclusive lower boundary array or a scalar.
• Parameter: upperb: inclusive upper boundary array or a scalar.
• Parameter: dst: output array of the same size as src and CV_8U type.

Usage: compare ?dst src1 src2 cmpop

Performs the per-element comparison of two arrays or an array and scalar value.

The function compares: * Elements of two arrays when src1 and src2 have the same size: \texttt{dst} (I) = \texttt{src1} (I) \,\texttt{cmpop}\, \texttt{src2} (I) * Elements of src1 with a scalar src2 when src2 is constructed from Scalar or has a single element: \texttt{dst} (I) = \texttt{src1}(I) \,\texttt{cmpop}\, \texttt{src2} * src1 with elements of src2 when src1 is constructed from Scalar or has a single element: \texttt{dst} (I) = \texttt{src1} \,\texttt{cmpop}\, \texttt{src2} (I) When the comparison result is true, the corresponding element of output array is set to 255. The comparison operations can be replaced with the equivalent matrix expressions:

Mat dst1 = src1 >= src2;
Mat dst2 = src1 < 8;
...

• Parameter: src1: first input array or a scalar; when it is an array, it must have a single channel.
• Parameter: src2: second input array or a scalar; when it is an array, it must have a single channel.
• Parameter: dst: output array of type ref CV_8U that has the same size and the same number of channels as the input arrays.
• Parameter: cmpop: a flag, that specifies correspondence between the arrays (cv::CmpTypes) See also: checkRange, min, max, threshold

Usage: min ?dst src1 src2

Calculates per-element minimum of two arrays or an array and a scalar.

The function cv::min calculates the per-element minimum of two arrays: \texttt{dst} (I)= \min ( \texttt{src1} (I), \texttt{src2} (I)) or array and a scalar: \texttt{dst} (I)= \min ( \texttt{src1} (I), \texttt{value} )

• Parameter: src1: first input array.
• Parameter: src2: second input array of the same size and type as src1.
• Parameter: dst: output array of the same size and type as src1. See also: max, compare, inRange, minMaxLoc

Usage: max ?dst src1 src2

Calculates per-element maximum of two arrays or an array and a scalar.

The function cv::max calculates the per-element maximum of two arrays: \texttt{dst} (I)= \max ( \texttt{src1} (I), \texttt{src2} (I)) or array and a scalar: \texttt{dst} (I)= \max ( \texttt{src1} (I), \texttt{value} )

• Parameter: src1: first input array.
• Parameter: src2: second input array of the same size and type as src1 .
• Parameter: dst: output array of the same size and type as src1. See also: min, compare, inRange, minMaxLoc, MatrixExpressions

Usage: sqrt ?dst src

Calculates a square root of array elements.

The function cv::sqrt calculates a square root of each input array element. In case of multi-channel arrays, each channel is processed independently. The accuracy is approximately the same as of the built-in std::sqrt .

• Parameter: src: input floating-point array.
• Parameter: dst: output array of the same size and type as src.

Usage: pow ?dst src power

Raises every array element to a power.

The function cv::pow raises every element of the input array to power : \texttt{dst} (I) = \fork{\texttt{src}(I)^{power}}{if \(\texttt{power}\) is integer}{ |\texttt{src}(I)|^{power}}{otherwise}

So, for a non-integer power exponent, the absolute values of input array elements are used. However, it is possible to get true values for negative values using some extra operations. In the example below, computing the 5th root of array src shows:

Mat mask = src < 0;
pow(src, 1./5, dst);
subtract(Scalar::all(0), dst, dst, mask);

For some values of power, such as integer values, 0.5 and -0.5, specialized faster algorithms are used.

Special values (NaN, Inf) are not handled.

• Parameter: src: input array.
• Parameter: power: exponent of power.
• Parameter: dst: output array of the same size and type as src. See also: sqrt, exp, log, cartToPolar, polarToCart

Usage: exp ?dst src

Calculates the exponent of every array element.

The function cv::exp calculates the exponent of every element of the input array: \texttt{dst} [I] = e^{ src(I) }

The maximum relative error is about 7e-6 for single-precision input and less than 1e-10 for double-precision input. Currently, the function converts denormalized values to zeros on output. Special values (NaN, Inf) are not handled.

• Parameter: src: input array.
• Parameter: dst: output array of the same size and type as src. See also: log , cartToPolar , polarToCart , phase , pow , sqrt , magnitude

Usage: log ?dst src

Calculates the natural logarithm of every array element.

The function cv::log calculates the natural logarithm of every element of the input array: \texttt{dst} (I) = \log (\texttt{src}(I))

Output on zero, negative and special (NaN, Inf) values is undefined.

• Parameter: src: input array.
• Parameter: dst: output array of the same size and type as src . See also: exp, cartToPolar, polarToCart, phase, pow, sqrt, magnitude

Usage: polar_to_cart ?x ?y ?angle_in_degrees magnitude angle

Calculates x and y coordinates of 2D vectors from their magnitude and angle.

The function cv::polarToCart calculates the Cartesian coordinates of each 2D vector represented by the corresponding elements of magnitude and angle: \begin{array}{l} \texttt{x} (I) = \texttt{magnitude} (I) \cos ( \texttt{angle} (I)) \\ \texttt{y} (I) = \texttt{magnitude} (I) \sin ( \texttt{angle} (I)) \\ \end{array}

The relative accuracy of the estimated coordinates is about 1e-6.

• Parameter: magnitude: input floating-point array of magnitudes of 2D vectors; it can be an empty matrix (=Mat()), in this case, the function assumes that all the magnitudes are =1; if it is not empty, it must have the same size and type as angle.
• Parameter: angle: input floating-point array of angles of 2D vectors.
• Parameter: x: output array of x-coordinates of 2D vectors; it has the same size and type as angle.
• Parameter: y: output array of y-coordinates of 2D vectors; it has the same size and type as angle.
• Parameter: angle_in_degrees: when true, the input angles are measured in degrees, otherwise, they are measured in radians. See also: cartToPolar, magnitude, phase, exp, log, pow, sqrt

Usage: cart_to_polar ?magnitude ?angle ?angle_in_degrees x y

Calculates the magnitude and angle of 2D vectors.

The function cv::cartToPolar calculates either the magnitude, angle, or both for every 2D vector (x(I),y(I)): \begin{array}{l} \texttt{magnitude} (I)= \sqrt{\texttt{x}(I)^2+\texttt{y}(I)^2} , \\ \texttt{angle} (I)= \texttt{atan2} ( \texttt{y} (I), \texttt{x} (I))[ \cdot180 / \pi ] \end{array}

The angles are calculated with accuracy about 0.3 degrees. For the point (0,0), the angle is set to 0.

• Parameter: x: array of x-coordinates; this must be a single-precision or double-precision floating-point array.
• Parameter: y: array of y-coordinates, that must have the same size and same type as x.
• Parameter: magnitude: output array of magnitudes of the same size and type as x.
• Parameter: angle: output array of angles that has the same size and type as x; the angles are measured in radians (from 0 to 2\*Pi) or in degrees (0 to 360 degrees).
• Parameter: angle_in_degrees: a flag, indicating whether the angles are measured in radians (which is by default), or in degrees. See also: Sobel, Scharr

Usage: phase ?angle ?angle_in_degrees x y

Calculates the rotation angle of 2D vectors.

The function cv::phase calculates the rotation angle of each 2D vector that is formed from the corresponding elements of x and y : \texttt{angle} (I) = \texttt{atan2} ( \texttt{y} (I), \texttt{x} (I))

The angle estimation accuracy is about 0.3 degrees. When x(I)=y(I)=0 , the corresponding angle(I) is set to 0.

• Parameter: x: input floating-point array of x-coordinates of 2D vectors.
• Parameter: y: input array of y-coordinates of 2D vectors; it must have the same size and the same type as x.
• Parameter: angle: output array of vector angles; it has the same size and same type as x .
• Parameter: angle_in_degrees: when true, the function calculates the angle in degrees, otherwise, they are measured in radians.

Usage: magnitude ?magnitude x y

Calculates the magnitude of 2D vectors.

The function cv::magnitude calculates the magnitude of 2D vectors formed from the corresponding elements of x and y arrays: \texttt{dst} (I) = \sqrt{\texttt{x}(I)^2 + \texttt{y}(I)^2}

• Parameter: x: floating-point array of x-coordinates of the vectors.
• Parameter: y: floating-point array of y-coordinates of the vectors; it must have the same size as x.
• Parameter: magnitude: output array of the same size and type as x. See also: cartToPolar, polarToCart, phase, sqrt

Usage: check_range ?quiet ?pos ?min_val ?max_val a

Checks every element of an input array for invalid values.

The function cv::checkRange checks that every array element is neither NaN nor infinite. When minVal \> -DBL_MAX and maxVal \< DBL_MAX, the function also checks that each value is between minVal and maxVal. In case of multi-channel arrays, each channel is processed independently. If some values are out of range, position of the first outlier is stored in pos (when pos != NULL). Then, the function either returns false (when quiet=true) or throws an exception.

• Parameter: a: input array.
• Parameter: quiet: a flag, indicating whether the functions quietly return false when the array elements are out of range or they throw an exception.
• Parameter: pos: optional output parameter, when not NULL, must be a pointer to array of src.dims elements.
• Parameter: min_val: inclusive lower boundary of valid values range.
• Parameter: max_val: exclusive upper boundary of valid values range.

Usage: patch_na_ns ?cv_val a

converts NaNs to the given number

• Parameter: a: input/output matrix (CV_32F type).
• Parameter: cv_val: value to convert the NaNs

Usage: gemm ?dst ?flags src1 src2 alpha src3 beta

Performs generalized matrix multiplication.

The function cv::gemm performs generalized matrix multiplication similar to the gemm functions in BLAS level 3. For example, gemm(src1, src2, alpha, src3, beta, dst, GEMM_1_T + GEMM_3_T) corresponds to \texttt{dst} = \texttt{alpha} \cdot \texttt{src1} ^T \cdot \texttt{src2} + \texttt{beta} \cdot \texttt{src3} ^T

In case of complex (two-channel) data, performed a complex matrix multiplication.

The function can be replaced with a matrix expression. For example, the above call can be replaced with:

dst = alpha*src1.t()*src2 + beta*src3.t();

• Parameter: src1: first multiplied input matrix that could be real(CV_32FC1, CV_64FC1) or complex(CV_32FC2, CV_64FC2).
• Parameter: src2: second multiplied input matrix of the same type as src1.
• Parameter: alpha: weight of the matrix product.
• Parameter: src3: third optional delta matrix added to the matrix product; it should have the same type as src1 and src2.
• Parameter: beta: weight of src3.
• Parameter: dst: output matrix; it has the proper size and the same type as input matrices.
• Parameter: flags: operation flags (cv::GemmFlags) See also: mulTransposed , transform

Usage: mul_transposed ?dst ?delta ?scale ?dtype src a_ta

Calculates the product of a matrix and its transposition.

The function cv::mulTransposed calculates the product of src and its transposition: \texttt{dst} = \texttt{scale} ( \texttt{src} - \texttt{delta} )^T ( \texttt{src} - \texttt{delta} ) if aTa=true , and \texttt{dst} = \texttt{scale} ( \texttt{src} - \texttt{delta} ) ( \texttt{src} - \texttt{delta} )^T otherwise. The function is used to calculate the covariance matrix. With zero delta, it can be used as a faster substitute for general matrix product A\*B when B=A'

• Parameter: src: input single-channel matrix. Note that unlike gemm, the function can multiply not only floating-point matrices.
• Parameter: dst: output square matrix.
• Parameter: a_ta: Flag specifying the multiplication ordering. See the description below.
• Parameter: delta: Optional delta matrix subtracted from src before the multiplication. When the matrix is empty ( delta=noArray() ), it is assumed to be zero, that is, nothing is subtracted. If it has the same size as src , it is simply subtracted. Otherwise, it is "repeated" (see repeat ) to cover the full src and then subtracted. Type of the delta matrix, when it is not empty, must be the same as the type of created output matrix. See the dtype parameter description below.
• Parameter: scale: Optional scale factor for the matrix product.
• Parameter: dtype: Optional type of the output matrix. When it is negative, the output matrix will have the same type as src . Otherwise, it will be type=CV_MAT_DEPTH(dtype) that should be either CV_32F or CV_64F . See also: calcCovarMatrix, gemm, repeat, reduce

Usage: transpose ?dst src

Transposes a matrix.

The function cv::transpose transposes the matrix src : \texttt{dst} (i,j) = \texttt{src} (j,i) Note: No complex conjugation is done in case of a complex matrix. It should be done separately if needed.

• Parameter: src: input array.
• Parameter: dst: output array of the same type as src.

Usage: transform ?dst src m

Performs the matrix transformation of every array element.

The function cv::transform performs the matrix transformation of every element of the array src and stores the results in dst : \texttt{dst} (I) = \texttt{m} \cdot \texttt{src} (I) (when m.cols=src.channels() ), or \texttt{dst} (I) = \texttt{m} \cdot [ \texttt{src} (I); 1] (when m.cols=src.channels()+1 )

Every element of the N -channel array src is interpreted as N -element vector that is transformed using the M x N or M x (N+1) matrix m to M-element vector - the corresponding element of the output array dst .

The function may be used for geometrical transformation of N -dimensional points, arbitrary linear color space transformation (such as various kinds of RGB to YUV transforms), shuffling the image channels, and so forth.

• Parameter: src: input array that must have as many channels (1 to 4) as m.cols or m.cols-1.
• Parameter: dst: output array of the same size and depth as src; it has as many channels as m.rows.
• Parameter: m: transformation 2x2 or 2x3 floating-point matrix. See also: perspectiveTransform, getAffineTransform, estimateAffine2D, warpAffine, warpPerspective

Usage: perspective_transform ?dst src m

Performs the perspective matrix transformation of vectors.

The function cv::perspectiveTransform transforms every element of src by treating it as a 2D or 3D vector, in the following way: (x, y, z) \rightarrow (x'/w, y'/w, z'/w) where (x', y', z', w') = \texttt{mat} \cdot \begin{bmatrix} x & y & z & 1 \end{bmatrix} and w = \fork{w'}{if \(w' \ne 0\)}{\infty}{otherwise}

Here a 3D vector transformation is shown. In case of a 2D vector transformation, the z component is omitted.

Note: The function transforms a sparse set of 2D or 3D vectors. If you want to transform an image using perspective transformation, use warpPerspective . If you have an inverse problem, that is, you want to compute the most probable perspective transformation out of several pairs of corresponding points, you can use getPerspectiveTransform or findHomography .

• Parameter: src: input two-channel or three-channel floating-point array; each element is a 2D/3D vector to be transformed.
• Parameter: dst: output array of the same size and type as src.
• Parameter: m: 3x3 or 4x4 floating-point transformation matrix. See also: transform, warpPerspective, getPerspectiveTransform, findHomography

Usage: complete_symm ?lower_to_upper m

Copies the lower or the upper half of a square matrix to its another half.

The function cv::completeSymm copies the lower or the upper half of a square matrix to its another half. The matrix diagonal remains unchanged:

• \texttt{m}_{ij}=\texttt{m}_{ji} for i > j if lowerToUpper=false
• \texttt{m}_{ij}=\texttt{m}_{ji} for i < j if lowerToUpper=true

• Parameter: m: input-output floating-point square matrix.
• Parameter: lower_to_upper: operation flag; if true, the lower half is copied to the upper half. Otherwise, the upper half is copied to the lower half. See also: flip, transpose

Usage: set_identity ?s mtx

Initializes a scaled identity matrix.

The function cv::setIdentity initializes a scaled identity matrix: \texttt{mtx} (i,j)= \fork{\texttt{value}}{ if \(i=j\)}{0}{otherwise}

The function can also be emulated using the matrix initializers and the matrix expressions:

Mat A = Mat::eye(4, 3, CV_32F)*5;
// A will be set to [[5, 0, 0], [0, 5, 0], [0, 0, 5], [0, 0, 0]]

• Parameter: mtx: matrix to initialize (not necessarily square).
• Parameter: s: value to assign to diagonal elements. See also: Mat::zeros, Mat::ones, Mat::setTo, Mat::operator=

Usage: determinant mtx

Returns the determinant of a square floating-point matrix.

The function cv::determinant calculates and returns the determinant of the specified matrix. For small matrices ( mtx.cols=mtx.rows\<=3 ), the direct method is used. For larger matrices, the function uses LU factorization with partial pivoting.

For symmetric positively-determined matrices, it is also possible to use eigen decomposition to calculate the determinant.

• Parameter: mtx: input matrix that must have CV_32FC1 or CV_64FC1 type and square size. See also: trace, invert, solve, eigen, MatrixExpressions

Usage: trace mtx

Returns the trace of a matrix.

The function cv::trace returns the sum of the diagonal elements of the matrix mtx . \mathrm{tr} ( \texttt{mtx} ) = \sum _i \texttt{mtx} (i,i)

• Parameter: mtx: input matrix.

Usage: invert ?dst ?flags src

Finds the inverse or pseudo-inverse of a matrix.

The function cv::invert inverts the matrix src and stores the result in dst . When the matrix src is singular or non-square, the function calculates the pseudo-inverse matrix (the dst matrix) so that norm(src\*dst - I) is minimal, where I is an identity matrix.

In case of the #DECOMP_LU method, the function returns non-zero value if the inverse has been successfully calculated and 0 if src is singular.

In case of the #DECOMP_SVD method, the function returns the inverse condition number of src (the ratio of the smallest singular value to the largest singular value) and 0 if src is singular. The SVD method calculates a pseudo-inverse matrix if src is singular.

Similarly to #DECOMP_LU, the method #DECOMP_CHOLESKY works only with non-singular square matrices that should also be symmetrical and positively defined. In this case, the function stores the inverted matrix in dst and returns non-zero. Otherwise, it returns 0.

• Parameter: src: input floating-point M x N matrix.
• Parameter: dst: output matrix of N x M size and the same type as src.
• Parameter: flags: inversion method (cv::DecompTypes) See also: solve, SVD

Usage: solve ?dst ?flags src1 src2

Solves one or more linear systems or least-squares problems.

The function cv::solve solves a linear system or least-squares problem (the latter is possible with SVD or QR methods, or by specifying the flag #DECOMP_NORMAL ): \texttt{dst} = \arg \min _X \| \texttt{src1} \cdot \texttt{X} - \texttt{src2} \|

If #DECOMP_LU or #DECOMP_CHOLESKY method is used, the function returns 1 if src1 (or \texttt{src1}^T\texttt{src1} ) is non-singular. Otherwise, it returns 0. In the latter case, dst is not valid. Other methods find a pseudo-solution in case of a singular left-hand side part.

Note: If you want to find a unity-norm solution of an under-defined singular system \texttt{src1}\cdot\texttt{dst}=0 , the function solve will not do the work. Use SVD::solveZ instead.

• Parameter: src1: input matrix on the left-hand side of the system.
• Parameter: src2: input matrix on the right-hand side of the system.
• Parameter: dst: output solution.
• Parameter: flags: solution (matrix inversion) method (#DecompTypes) See also: invert, SVD, eigen

Usage: sort ?dst src flags

Sorts each row or each column of a matrix.

The function cv::sort sorts each matrix row or each matrix column in ascending or descending order. So you should pass two operation flags to get desired behaviour. If you want to sort matrix rows or columns lexicographically, you can use STL std::sort generic function with the proper comparison predicate.

• Parameter: src: input single-channel array.
• Parameter: dst: output array of the same size and type as src.
• Parameter: flags: operation flags, a combination of #SortFlags See also: sortIdx, randShuffle

Usage: sort_idx ?dst src flags

Sorts each row or each column of a matrix.

The function cv::sortIdx sorts each matrix row or each matrix column in the ascending or descending order. So you should pass two operation flags to get desired behaviour. Instead of reordering the elements themselves, it stores the indices of sorted elements in the output array. For example:

Mat A = Mat::eye(3,3,CV_32F), B;
sortIdx(A, B, SORT_EVERY_ROW + SORT_ASCENDING);
// B will probably contain
// (because of equal elements in A some permutations are possible):
// [[1, 2, 0], [0, 2, 1], [0, 1, 2]]

• Parameter: src: input single-channel array.
• Parameter: dst: output integer array of the same size as src.
• Parameter: flags: operation flags that could be a combination of cv::SortFlags See also: sort, randShuffle

Usage: solve_cubic ?roots coeffs

Finds the real roots of a cubic equation.

The function solveCubic finds the real roots of a cubic equation:

• if coeffs is a 4-element vector: \texttt{coeffs} [0] x^3 + \texttt{coeffs} [1] x^2 + \texttt{coeffs} [2] x + \texttt{coeffs} [3] = 0
• if coeffs is a 3-element vector: x^3 + \texttt{coeffs} [0] x^2 + \texttt{coeffs} [1] x + \texttt{coeffs} [2] = 0

The roots are stored in the roots array.

• Parameter: coeffs: equation coefficients, an array of 3 or 4 elements.
• Parameter: roots: output array of real roots that has 1 or 3 elements.
• Returns: number of real roots. It can be 0, 1 or 2.

Usage: solve_poly ?roots ?max_iters coeffs

Finds the real or complex roots of a polynomial equation.

The function cv::solvePoly finds real and complex roots of a polynomial equation: \texttt{coeffs} [n] x^{n} + \texttt{coeffs} [n-1] x^{n-1} + ... + \texttt{coeffs} [1] x + \texttt{coeffs} [0] = 0

• Parameter: coeffs: array of polynomial coefficients.
• Parameter: roots: output (complex) array of roots.
• Parameter: max_iters: maximum number of iterations the algorithm does.

Usage: eigen ?eigenvalues ?eigenvectors src

Calculates eigenvalues and eigenvectors of a symmetric matrix.

The function cv::eigen calculates just eigenvalues, or eigenvalues and eigenvectors of the symmetric matrix src:

src*eigenvectors.row(i).t() = eigenvalues.at<srcType>(i)*eigenvectors.row(i).t()

Note: Use cv::eigenNonSymmetric for calculation of real eigenvalues and eigenvectors of non-symmetric matrix.

• Parameter: src: input matrix that must have CV_32FC1 or CV_64FC1 type, square size and be symmetrical (src ^T^ == src).
• Parameter: eigenvalues: output vector of eigenvalues of the same type as src; the eigenvalues are stored in the descending order.
• Parameter: eigenvectors: output matrix of eigenvectors; it has the same size and type as src; the eigenvectors are stored as subsequent matrix rows, in the same order as the corresponding eigenvalues. See also: eigenNonSymmetric, completeSymm , PCA

Usage: eigen_non_symmetric ?eigenvalues ?eigenvectors src

Calculates eigenvalues and eigenvectors of a non-symmetric matrix (real eigenvalues only).

Note: Assumes real eigenvalues.

The function calculates eigenvalues and eigenvectors (optional) of the square matrix src:

src*eigenvectors.row(i).t() = eigenvalues.at<srcType>(i)*eigenvectors.row(i).t()

• Parameter: src: input matrix (CV_32FC1 or CV_64FC1 type).
• Parameter: eigenvalues: output vector of eigenvalues (type is the same type as src).
• Parameter: eigenvectors: output matrix of eigenvectors (type is the same type as src). The eigenvectors are stored as subsequent matrix rows, in the same order as the corresponding eigenvalues. See also: eigen

Usage: calc_covar_matrix ?covar ?ctype samples mean flags

Note: use #COVAR_ROWS or #COVAR_COLS flag

• Parameter: samples: samples stored as rows/columns of a single matrix.
• Parameter: covar: output covariance matrix of the type ctype and square size.
• Parameter: mean: input or output (depending on the flags) array as the average value of the input vectors.
• Parameter: flags: operation flags as a combination of #CovarFlags
• Parameter: ctype: type of the matrixl; it equals 'CV_64F' by default.

Usage: pca_compute1 ?eigenvectors ?max_components data mean

wrap PCA::operator()

Usage: pca_compute2 ?eigenvectors ?eigenvalues ?max_components data mean

wrap PCA::operator() and add eigenvalues output parameter

Usage: pca_compute3 ?eigenvectors data mean retained_variance

wrap PCA::operator()

Usage: pca_compute4 ?eigenvectors ?eigenvalues data mean retained_variance

wrap PCA::operator() and add eigenvalues output parameter

Usage: pca_project ?result data mean eigenvectors

wrap PCA::project

Usage: pca_back_project ?result data mean eigenvectors

wrap PCA::backProject

Usage: sv_decomp ?w ?u ?vt ?flags src

wrap SVD::compute

Usage: sv_back_subst ?dst w u vt rhs

wrap SVD::backSubst

Usage: mahalanobis v1 v2 icovar

Calculates the Mahalanobis distance between two vectors.

The function cv::Mahalanobis calculates and returns the weighted distance between two vectors: d( \texttt{vec1} , \texttt{vec2} )= \sqrt{\sum_{i,j}{\texttt{icovar(i,j)}\cdot(\texttt{vec1}(I)-\texttt{vec2}(I))\cdot(\texttt{vec1(j)}-\texttt{vec2(j)})} } The covariance matrix may be calculated using the #calcCovarMatrix function and then inverted using the invert function (preferably using the #DECOMP_SVD method, as the most accurate).

• Parameter: v1: first 1D input vector.
• Parameter: v2: second 1D input vector.
• Parameter: icovar: inverse covariance matrix.

Usage: dft ?dst ?flags ?nonzero_rows src

Performs a forward or inverse Discrete Fourier transform of a 1D or 2D floating-point array.

The function cv::dft performs one of the following:

• Forward the Fourier transform of a 1D vector of N elements: Y = F^{(N)} \cdot X, where F^{(N)}_{jk}=\exp(-2\pi i j k/N) and i=\sqrt{-1}
• Inverse the Fourier transform of a 1D vector of N elements: \begin{array}{l} X'= \left (F^{(N)} \right )^{-1} \cdot Y = \left (F^{(N)} \right )^* \cdot y \\ X = (1/N) \cdot X, \end{array} where F^*=\left(\textrm{Re}(F^{(N)})-\textrm{Im}(F^{(N)})\right)^T
• Forward the 2D Fourier transform of a M x N matrix: Y = F^{(M)} \cdot X \cdot F^{(N)}
• Inverse the 2D Fourier transform of a M x N matrix: \begin{array}{l} X'= \left (F^{(M)} \right )^* \cdot Y \cdot \left (F^{(N)} \right )^* \\ X = \frac{1}{M \cdot N} \cdot X' \end{array}

In case of real (single-channel) data, the output spectrum of the forward Fourier transform or input spectrum of the inverse Fourier transform can be represented in a packed format called *CCS* (complex-conjugate-symmetrical). It was borrowed from IPL (Intel\* Image Processing Library). Here is how 2D *CCS* spectrum looks: \begin{bmatrix} Re Y_{0,0} & Re Y_{0,1} & Im Y_{0,1} & Re Y_{0,2} & Im Y_{0,2} & \cdots & Re Y_{0,N/2-1} & Im Y_{0,N/2-1} & Re Y_{0,N/2} \\ Re Y_{1,0} & Re Y_{1,1} & Im Y_{1,1} & Re Y_{1,2} & Im Y_{1,2} & \cdots & Re Y_{1,N/2-1} & Im Y_{1,N/2-1} & Re Y_{1,N/2} \\ Im Y_{1,0} & Re Y_{2,1} & Im Y_{2,1} & Re Y_{2,2} & Im Y_{2,2} & \cdots & Re Y_{2,N/2-1} & Im Y_{2,N/2-1} & Im Y_{1,N/2} \\ \hdotsfor{9} \\ Re Y_{M/2-1,0} & Re Y_{M-3,1} & Im Y_{M-3,1} & \hdotsfor{3} & Re Y_{M-3,N/2-1} & Im Y_{M-3,N/2-1}& Re Y_{M/2-1,N/2} \\ Im Y_{M/2-1,0} & Re Y_{M-2,1} & Im Y_{M-2,1} & \hdotsfor{3} & Re Y_{M-2,N/2-1} & Im Y_{M-2,N/2-1}& Im Y_{M/2-1,N/2} \\ Re Y_{M/2,0} & Re Y_{M-1,1} & Im Y_{M-1,1} & \hdotsfor{3} & Re Y_{M-1,N/2-1} & Im Y_{M-1,N/2-1}& Re Y_{M/2,N/2} \end{bmatrix}

In case of 1D transform of a real vector, the output looks like the first row of the matrix above.

So, the function chooses an operation mode depending on the flags and size of the input array:

• If #DFT_ROWS is set or the input array has a single row or single column, the function performs a 1D forward or inverse transform of each row of a matrix when #DFT_ROWS is set. Otherwise, it performs a 2D transform.
• If the input array is real and #DFT_INVERSE is not set, the function performs a forward 1D or 2D transform:
• When #DFT_COMPLEX_OUTPUT is set, the output is a complex matrix of the same size as input.
• When #DFT_COMPLEX_OUTPUT is not set, the output is a real matrix of the same size as input. In case of 2D transform, it uses the packed format as shown above. In case of a single 1D transform, it looks like the first row of the matrix above. In case of multiple 1D transforms (when using the #DFT_ROWS flag), each row of the output matrix looks like the first row of the matrix above.
• If the input array is complex and either #DFT_INVERSE or #DFT_REAL_OUTPUT are not set, the output is a complex array of the same size as input. The function performs a forward or inverse 1D or 2D transform of the whole input array or each row of the input array independently, depending on the flags DFT_INVERSE and DFT_ROWS.
• When #DFT_INVERSE is set and the input array is real, or it is complex but #DFT_REAL_OUTPUT is set, the output is a real array of the same size as input. The function performs a 1D or 2D inverse transformation of the whole input array or each individual row, depending on the flags #DFT_INVERSE and #DFT_ROWS.

If #DFT_SCALE is set, the scaling is done after the transformation.

Unlike dct , the function supports arrays of arbitrary size. But only those arrays are processed efficiently, whose sizes can be factorized in a product of small prime numbers (2, 3, and 5 in the current implementation). Such an efficient DFT size can be calculated using the getOptimalDFTSize method.

The sample below illustrates how to calculate a DFT-based convolution of two 2D real arrays:

void convolveDFT(InputArray A, InputArray B, OutputArray C)
{
    // reallocate the output array if needed
    C.create(abs(A.rows - B.rows)+1, abs(A.cols - B.cols)+1, A.type());
    Size dftSize;
    // calculate the size of DFT transform
    dftSize.width = getOptimalDFTSize(A.cols + B.cols - 1);
    dftSize.height = getOptimalDFTSize(A.rows + B.rows - 1);

    // allocate temporary buffers and initialize them with 0's
    Mat tempA(dftSize, A.type(), Scalar::all(0));
    Mat tempB(dftSize, B.type(), Scalar::all(0));

    // copy A and B to the top-left corners of tempA and tempB, respectively
    Mat roiA(tempA, Rect(0,0,A.cols,A.rows));
    A.copyTo(roiA);
    Mat roiB(tempB, Rect(0,0,B.cols,B.rows));
    B.copyTo(roiB);

    // now transform the padded A & B in-place;
    // use "nonzeroRows" hint for faster processing
    dft(tempA, tempA, 0, A.rows);
    dft(tempB, tempB, 0, B.rows);

    // multiply the spectrums;
    // the function handles packed spectrum representations well
    mulSpectrums(tempA, tempB, tempA);

    // transform the product back from the frequency domain.
    // Even though all the result rows will be non-zero,
    // you need only the first C.rows of them, and thus you
    // pass nonzeroRows == C.rows
    dft(tempA, tempA, DFT_INVERSE + DFT_SCALE, C.rows);

    // now copy the result back to C.
    tempA(Rect(0, 0, C.cols, C.rows)).copyTo(C);

    // all the temporary buffers will be deallocated automatically
}

To optimize this sample, consider the following approaches:

• Since nonzeroRows != 0 is passed to the forward transform calls and since A and B are copied to the top-left corners of tempA and tempB, respectively, it is not necessary to clear the whole tempA and tempB. It is only necessary to clear the tempA.cols - A.cols ( tempB.cols - B.cols) rightmost columns of the matrices.
• This DFT-based convolution does not have to be applied to the whole big arrays, especially if B is significantly smaller than A or vice versa. Instead, you can calculate convolution by parts. To do this, you need to split the output array C into multiple tiles. For each tile, estimate which parts of A and B are required to calculate convolution in this tile. If the tiles in C are too small, the speed will decrease a lot because of repeated work. In the ultimate case, when each tile in C is a single pixel, the algorithm becomes equivalent to the naive convolution algorithm. If the tiles are too big, the temporary arrays tempA and tempB become too big and there is also a slowdown because of bad cache locality. So, there is an optimal tile size somewhere in the middle.
• If different tiles in C can be calculated in parallel and, thus, the convolution is done by parts, the loop can be threaded.

All of the above improvements have been implemented in #matchTemplate and #filter2D . Therefore, by using them, you can get the performance even better than with the above theoretically optimal implementation. Though, those two functions actually calculate cross-correlation, not convolution, so you need to "flip" the second convolution operand B vertically and horizontally using flip . Note:

• An example using the discrete fourier transform can be found at opencv_source_code/samples/cpp/dft.cpp
• (Python) An example using the dft functionality to perform Wiener deconvolution can be found at opencv_source/samples/python/deconvolution.py
• (Python) An example rearranging the quadrants of a Fourier image can be found at opencv_source/samples/python/dft.py
• Parameter: src: input array that could be real or complex.
• Parameter: dst: output array whose size and type depends on the flags .
• Parameter: flags: transformation flags, representing a combination of the #DftFlags
• Parameter: nonzero_rows: when the parameter is not zero, the function assumes that only the first nonzeroRows rows of the input array (#DFT_INVERSE is not set) or only the first nonzeroRows of the output array (#DFT_INVERSE is set) contain non-zeros, thus, the function can handle the rest of the rows more efficiently and save some time; this technique is very useful for calculating array cross-correlation or convolution using DFT. See also: dct , getOptimalDFTSize , mulSpectrums, filter2D , matchTemplate , flip , cartToPolar , magnitude , phase

Usage: idft ?dst ?flags ?nonzero_rows src

Calculates the inverse Discrete Fourier Transform of a 1D or 2D array.

idft(src, dst, flags) is equivalent to dft(src, dst, flags | #DFT_INVERSE) . Note: None of dft and idft scales the result by default. So, you should pass #DFT_SCALE to one of dft or idft explicitly to make these transforms mutually inverse. See also: dft, dct, idct, mulSpectrums, getOptimalDFTSize

• Parameter: src: input floating-point real or complex array.
• Parameter: dst: output array whose size and type depend on the flags.
• Parameter: flags: operation flags (see dft and #DftFlags).
• Parameter: nonzero_rows: number of dst rows to process; the rest of the rows have undefined content (see the convolution sample in dft description.

Usage: dct ?dst ?flags src

Performs a forward or inverse discrete Cosine transform of 1D or 2D array.

The function cv::dct performs a forward or inverse discrete Cosine transform (DCT) of a 1D or 2D floating-point array:

• Forward Cosine transform of a 1D vector of N elements: Y = C^{(N)} \cdot X where C^{(N)}_{jk}= \sqrt{\alpha_j/N} \cos \left ( \frac{\pi(2k+1)j}{2N} \right ) and \alpha_0=1 , \alpha_j=2 for *j \> 0*.
• Inverse Cosine transform of a 1D vector of N elements: X = \left (C^{(N)} \right )^{-1} \cdot Y = \left (C^{(N)} \right )^T \cdot Y (since C^{(N)} is an orthogonal matrix, C^{(N)} \cdot \left(C^{(N)}\right)^T = I )
• Forward 2D Cosine transform of M x N matrix: Y = C^{(N)} \cdot X \cdot \left (C^{(N)} \right )^T
• Inverse 2D Cosine transform of M x N matrix: X = \left (C^{(N)} \right )^T \cdot X \cdot C^{(N)}

The function chooses the mode of operation by looking at the flags and size of the input array:

• If (flags & #DCT_INVERSE) == 0 , the function does a forward 1D or 2D transform. Otherwise, it is an inverse 1D or 2D transform.
• If (flags & #DCT_ROWS) != 0 , the function performs a 1D transform of each row.
• If the array is a single column or a single row, the function performs a 1D transform.
• If none of the above is true, the function performs a 2D transform.

Note: Currently dct supports even-size arrays (2, 4, 6 ...). For data analysis and approximation, you can pad the array when necessary. Also, the function performance depends very much, and not monotonically, on the array size (see getOptimalDFTSize ). In the current implementation DCT of a vector of size N is calculated via DFT of a vector of size N/2 . Thus, the optimal DCT size N1 \>= N can be calculated as:

size_t getOptimalDCTSize(size_t N) { return 2*getOptimalDFTSize((N+1)/2); }
N1 = getOptimalDCTSize(N);

• Parameter: src: input floating-point array.
• Parameter: dst: output array of the same size and type as src .
• Parameter: flags: transformation flags as a combination of cv::DftFlags (DCT_* ) See also: dft , getOptimalDFTSize , idct

Usage: idct ?dst ?flags src

Calculates the inverse Discrete Cosine Transform of a 1D or 2D array.

idct(src, dst, flags) is equivalent to dct(src, dst, flags | DCT_INVERSE).

• Parameter: src: input floating-point single-channel array.
• Parameter: dst: output array of the same size and type as src.
• Parameter: flags: operation flags. See also: dct, dft, idft, getOptimalDFTSize

Usage: mul_spectrums ?c ?conj_b a b flags

Performs the per-element multiplication of two Fourier spectrums.

The function cv::mulSpectrums performs the per-element multiplication of the two CCS-packed or complex matrices that are results of a real or complex Fourier transform.

The function, together with dft and idft , may be used to calculate convolution (pass conjB=false ) or correlation (pass conjB=true ) of two arrays rapidly. When the arrays are complex, they are simply multiplied (per element) with an optional conjugation of the second-array elements. When the arrays are real, they are assumed to be CCS-packed (see dft for details).

• Parameter: a: first input array.
• Parameter: b: second input array of the same size and type as src1 .
• Parameter: c: output array of the same size and type as src1 .
• Parameter: flags: operation flags; currently, the only supported flag is cv::DFT_ROWS, which indicates that each row of src1 and src2 is an independent 1D Fourier spectrum. If you do not want to use this flag, then simply add a 0 as value.
• Parameter: conj_b: optional flag that conjugates the second input array before the multiplication (true) or not (false).

Usage: get_optimal_dft_size vecsize

Returns the optimal DFT size for a given vector size.

DFT performance is not a monotonic function of a vector size. Therefore, when you calculate convolution of two arrays or perform the spectral analysis of an array, it usually makes sense to pad the input data with zeros to get a bit larger array that can be transformed much faster than the original one. Arrays whose size is a power-of-two (2, 4, 8, 16, 32, ...) are the fastest to process. Though, the arrays whose size is a product of 2's, 3's, and 5's (for example, 300 = 5\*5\*3\*2\*2) are also processed quite efficiently.

The function cv::getOptimalDFTSize returns the minimum number N that is greater than or equal to vecsize so that the DFT of a vector of size N can be processed efficiently. In the current implementation N = 2 ^p^ \* 3 ^q^ \* 5 ^r^ for some integer p, q, r.

The function returns a negative number if vecsize is too large (very close to INT_MAX ).

While the function cannot be used directly to estimate the optimal vector size for DCT transform (since the current DCT implementation supports only even-size vectors), it can be easily processed as getOptimalDFTSize((vecsize+1)/2)\*2.

• Parameter: vecsize: vector size. See also: dft , dct , idft , idct , mulSpectrums

Usage: set_rng_seed seed

Sets state of default random number generator.

The function cv::setRNGSeed sets state of default random number generator to custom value.

• Parameter: seed: new state for default random number generator See also: RNG, randu, randn

Usage: randu dst low high

Generates a single uniformly-distributed random number or an array of random numbers.

Non-template variant of the function fills the matrix dst with uniformly-distributed random numbers from the specified range: \texttt{low} _c \leq \texttt{dst} (I)_c < \texttt{high} _c

• Parameter: dst: output array of random numbers; the array must be pre-allocated.
• Parameter: low: inclusive lower boundary of the generated random numbers.
• Parameter: high: exclusive upper boundary of the generated random numbers. See also: RNG, randn, theRNG

Usage: randn dst mean stddev

Fills the array with normally distributed random numbers.

The function cv::randn fills the matrix dst with normally distributed random numbers with the specified mean vector and the standard deviation matrix. The generated random numbers are clipped to fit the value range of the output array data type.

• Parameter: dst: output array of random numbers; the array must be pre-allocated and have 1 to 4 channels.
• Parameter: mean: mean value (expectation) of the generated random numbers.
• Parameter: stddev: standard deviation of the generated random numbers; it can be either a vector (in which case a diagonal standard deviation matrix is assumed) or a square matrix. See also: RNG, randu

Usage: rand_shuffle ?iter_factor ?rng dst

Shuffles the array elements randomly.

The function cv::randShuffle shuffles the specified 1D array by randomly choosing pairs of elements and swapping them. The number of such swap operations will be dst.rows\*dst.cols\*iterFactor .

• Parameter: dst: input/output numerical 1D array.
• Parameter: iter_factor: scale factor that determines the number of random swap operations (see the details below).
• Parameter: rng: optional random number generator used for shuffling; if it is zero, theRNG () is used instead. See also: RNG, sort

Usage: get_gaussian_kernel ?ktype ksize sigma

Returns Gaussian filter coefficients.

The function computes and returns the \texttt{ksize} \times 1 matrix of Gaussian filter coefficients:

G_i= \alpha *e^{-(i-( \texttt{ksize} -1)/2)^2/(2* \texttt{sigma}^2)},

where i=0..\texttt{ksize}-1 and \alpha is the scale factor chosen so that \sum_i G_i=1 .

Two of such generated kernels can be passed to sepFilter2D. Those functions automatically recognize smoothing kernels (a symmetrical kernel with sum of weights equal to 1) and handle them accordingly. You may also use the higher-level GaussianBlur.

• Parameter: ksize: Aperture size. It should be odd ( \texttt{ksize} \mod 2 = 1 ) and positive.
• Parameter: sigma: Gaussian standard deviation. If it is non-positive, it is computed from ksize as sigma = 0.3*((ksize-1)*0.5 - 1) + 0.8.
• Parameter: ktype: Type of filter coefficients. It can be CV_32F or CV_64F . See also: sepFilter2D, getDerivKernels, getStructuringElement, GaussianBlur

Usage: get_deriv_kernels ?kx ?ky ?normalize ?ktype dx dy ksize

Returns filter coefficients for computing spatial image derivatives.

The function computes and returns the filter coefficients for spatial image derivatives. When ksize=FILTER_SCHARR, the Scharr 3 \times 3 kernels are generated (see #Scharr). Otherwise, Sobel kernels are generated (see #Sobel). The filters are normally passed to #sepFilter2D or to

• Parameter: kx: Output matrix of row filter coefficients. It has the type ktype .
• Parameter: ky: Output matrix of column filter coefficients. It has the type ktype .
• Parameter: dx: Derivative order in respect of x.
• Parameter: dy: Derivative order in respect of y.
• Parameter: ksize: Aperture size. It can be FILTER_SCHARR, 1, 3, 5, or 7.
• Parameter: normalize: Flag indicating whether to normalize (scale down) the filter coefficients or not. Theoretically, the coefficients should have the denominator =2^{ksize*2-dx-dy-2} . If you are going to filter floating-point images, you are likely to use the normalized kernels. But if you compute derivatives of an 8-bit image, store the results in a 16-bit image, and wish to preserve all the fractional bits, you may want to set normalize=false .
• Parameter: ktype: Type of filter coefficients. It can be CV_32f or CV_64F .

Usage: get_gabor_kernel ?psi ?ktype ksize sigma theta lambd gamma

Returns Gabor filter coefficients.

For more details about gabor filter equations and parameters, see: Gabor Filter(http://en.wikipedia.org/wiki/Gabor_filter).

• Parameter: ksize: Size of the filter returned.
• Parameter: sigma: Standard deviation of the gaussian envelope.
• Parameter: theta: Orientation of the normal to the parallel stripes of a Gabor function.
• Parameter: lambd: Wavelength of the sinusoidal factor.
• Parameter: gamma: Spatial aspect ratio.
• Parameter: psi: Phase offset.
• Parameter: ktype: Type of filter coefficients. It can be CV_32F or CV_64F .

Usage: get_structuring_element ?anchor shape ksize

Returns a structuring element of the specified size and shape for morphological operations.

The function constructs and returns the structuring element that can be further passed to #erode, #dilate or #morphologyEx. But you can also construct an arbitrary binary mask yourself and use it as the structuring element.

• Parameter: shape: Element shape that could be one of #MorphShapes
• Parameter: ksize: Size of the structuring element.
• Parameter: anchor: Anchor position within the element. The default value (-1, -1) means that the anchor is at the center. Note that only the shape of a cross-shaped element depends on the anchor position. In other cases the anchor just regulates how much the result of the morphological operation is shifted.

Usage: median_blur ?dst src ksize

Blurs an image using the median filter.

The function smoothes an image using the median filter with the \texttt{ksize} \times \texttt{ksize} aperture. Each channel of a multi-channel image is processed independently. In-place operation is supported.

Note: The median filter uses #BORDER_REPLICATE internally to cope with border pixels, see #BorderTypes

• Parameter: src: input 1-, 3-, or 4-channel image; when ksize is 3 or 5, the image depth should be CV_8U, CV_16U, or CV_32F, for larger aperture sizes, it can only be CV_8U.
• Parameter: dst: destination array of the same size and type as src.
• Parameter: ksize: aperture linear size; it must be odd and greater than 1, for example: 3, 5, 7 ... See also: bilateralFilter, blur, boxFilter, GaussianBlur

Usage: gaussian_blur ?dst ?sigma_y ?border_type src ksize sigma_x

Blurs an image using a Gaussian filter.

The function convolves the source image with the specified Gaussian kernel. In-place filtering is supported.

• Parameter: src: input image; the image can have any number of channels, which are processed independently, but the depth should be CV_8U, CV_16U, CV_16S, CV_32F or CV_64F.
• Parameter: dst: output image of the same size and type as src.
• Parameter: ksize: Gaussian kernel size. ksize.width and ksize.height can differ but they both must be positive and odd. Or, they can be zero's and then they are computed from sigma.
• Parameter: sigma_x: Gaussian kernel standard deviation in X direction.
• Parameter: sigma_y: Gaussian kernel standard deviation in Y direction; if sigmaY is zero, it is set to be equal to sigmaX, if both sigmas are zeros, they are computed from ksize.width and ksize.height, respectively (see #getGaussianKernel for details); to fully control the result regardless of possible future modifications of all this semantics, it is recommended to specify all of ksize, sigmaX, and sigmaY.
• Parameter: border_type: pixel extrapolation method, see #BorderTypes. #BORDER_WRAP is not supported.

See also: sepFilter2D, filter2D, blur, boxFilter, bilateralFilter, medianBlur

Usage: bilateral_filter ?dst ?border_type src d sigma_color sigma_space

Applies the bilateral filter to an image.

The function applies bilateral filtering to the input image, as described in http://www.dai.ed.ac.uk/CVonline/LOCAL_COPIES/MANDUCHI1/Bilateral_Filtering.html bilateralFilter can reduce unwanted noise very well while keeping edges fairly sharp. However, it is very slow compared to most filters.

_Sigma values_: For simplicity, you can set the 2 sigma values to be the same. If they are small (\< 10), the filter will not have much effect, whereas if they are large (\> 150), they will have a very strong effect, making the image look "cartoonish".

_Filter size_: Large filters (d \> 5) are very slow, so it is recommended to use d=5 for real-time applications, and perhaps d=9 for offline applications that need heavy noise filtering.

This filter does not work inplace.

• Parameter: src: Source 8-bit or floating-point, 1-channel or 3-channel image.
• Parameter: dst: Destination image of the same size and type as src .
• Parameter: d: Diameter of each pixel neighborhood that is used during filtering. If it is non-positive, it is computed from sigmaSpace.
• Parameter: sigma_color: Filter sigma in the color space. A larger value of the parameter means that farther colors within the pixel neighborhood (see sigmaSpace) will be mixed together, resulting in larger areas of semi-equal color.
• Parameter: sigma_space: Filter sigma in the coordinate space. A larger value of the parameter means that farther pixels will influence each other as long as their colors are close enough (see sigmaColor ). When d\>0, it specifies the neighborhood size regardless of sigmaSpace. Otherwise, d is proportional to sigmaSpace.
• Parameter: border_type: border mode used to extrapolate pixels outside of the image, see #BorderTypes

Usage: box_filter ?dst ?anchor ?normalize ?border_type src ddepth ksize

Blurs an image using the box filter.

The function smooths an image using the kernel:

\texttt{K} = \alpha \begin{bmatrix} 1 & 1 & 1 & \cdots & 1 & 1 \\ 1 & 1 & 1 & \cdots & 1 & 1 \\ \hdotsfor{6} \\ 1 & 1 & 1 & \cdots & 1 & 1 \end{bmatrix}

where

\alpha = \begin{cases} \frac{1}{\texttt{ksize.width*ksize.height}} & \texttt{when } \texttt{normalize=true} \\1 & \texttt{otherwise}\end{cases}

Unnormalized box filter is useful for computing various integral characteristics over each pixel neighborhood, such as covariance matrices of image derivatives (used in dense optical flow algorithms, and so on). If you need to compute pixel sums over variable-size windows, use #integral.

• Parameter: src: input image.
• Parameter: dst: output image of the same size and type as src.
• Parameter: ddepth: the output image depth (-1 to use src.depth()).
• Parameter: ksize: blurring kernel size.
• Parameter: anchor: anchor point; default value Point(-1,-1) means that the anchor is at the kernel center.
• Parameter: normalize: flag, specifying whether the kernel is normalized by its area or not.
• Parameter: border_type: border mode used to extrapolate pixels outside of the image, see #BorderTypes. #BORDER_WRAP is not supported. See also: blur, bilateralFilter, GaussianBlur, medianBlur, integral

Usage: sqr_box_filter ?dst ?anchor ?normalize ?border_type src ddepth ksize

Calculates the normalized sum of squares of the pixel values overlapping the filter.

For every pixel (x, y) in the source image, the function calculates the sum of squares of those neighboring pixel values which overlap the filter placed over the pixel (x, y) .

The unnormalized square box filter can be useful in computing local image statistics such as the the local variance and standard deviation around the neighborhood of a pixel.

• Parameter: src: input image
• Parameter: dst: output image of the same size and type as _src
• Parameter: ddepth: the output image depth (-1 to use src.depth())
• Parameter: ksize: kernel size
• Parameter: anchor: kernel anchor point. The default value of Point(-1, -1) denotes that the anchor is at the kernel center.
• Parameter: normalize: flag, specifying whether the kernel is to be normalized by it's area or not.
• Parameter: border_type: border mode used to extrapolate pixels outside of the image, see #BorderTypes. #BORDER_WRAP is not supported. See also: boxFilter

Usage: blur ?dst ?anchor ?border_type src ksize

Blurs an image using the normalized box filter.

The function smooths an image using the kernel:

\texttt{K} = \frac{1}{\texttt{ksize.width*ksize.height}} \begin{bmatrix} 1 & 1 & 1 & \cdots & 1 & 1 \\ 1 & 1 & 1 & \cdots & 1 & 1 \\ \hdotsfor{6} \\ 1 & 1 & 1 & \cdots & 1 & 1 \\ \end{bmatrix}

The call blur(src, dst, ksize, anchor, borderType) is equivalent to `boxFilter(src, dst, src.type(), ksize, anchor, true, borderType)`.

• Parameter: src: input image; it can have any number of channels, which are processed independently, but the depth should be CV_8U, CV_16U, CV_16S, CV_32F or CV_64F.
• Parameter: dst: output image of the same size and type as src.
• Parameter: ksize: blurring kernel size.
• Parameter: anchor: anchor point; default value Point(-1,-1) means that the anchor is at the kernel center.
• Parameter: border_type: border mode used to extrapolate pixels outside of the image, see #BorderTypes. #BORDER_WRAP is not supported. See also: boxFilter, bilateralFilter, GaussianBlur, medianBlur

Usage: filter2_d ?dst ?anchor ?delta ?border_type src ddepth kernel

Convolves an image with the kernel.

The function applies an arbitrary linear filter to an image. In-place operation is supported. When the aperture is partially outside the image, the function interpolates outlier pixel values according to the specified border mode.

The function does actually compute correlation, not the convolution:

\texttt{dst} (x,y) = \sum _{ \substack{0\leq x' < \texttt{kernel.cols}\\{0\leq y' < \texttt{kernel.rows}}}} \texttt{kernel} (x',y')* \texttt{src} (x+x'- \texttt{anchor.x} ,y+y'- \texttt{anchor.y} )

That is, the kernel is not mirrored around the anchor point. If you need a real convolution, flip the kernel using #flip and set the new anchor to `(kernel.cols - anchor.x - 1, kernel.rows - anchor.y - 1)`.

The function uses the DFT-based algorithm in case of sufficiently large kernels (~11 x 11 or larger) and the direct algorithm for small kernels.

• Parameter: src: input image.
• Parameter: dst: output image of the same size and the same number of channels as src.
• Parameter: ddepth: desired depth of the destination image, see filter_depths "combinations"
• Parameter: kernel: convolution kernel (or rather a correlation kernel), a single-channel floating point matrix; if you want to apply different kernels to different channels, split the image into separate color planes using split and process them individually.
• Parameter: anchor: anchor of the kernel that indicates the relative position of a filtered point within the kernel; the anchor should lie within the kernel; default value (-1,-1) means that the anchor is at the kernel center.
• Parameter: delta: optional value added to the filtered pixels before storing them in dst.
• Parameter: border_type: pixel extrapolation method, see #BorderTypes. #BORDER_WRAP is not supported. See also: sepFilter2D, dft, matchTemplate

Usage: sep_filter2_d ?dst ?anchor ?delta ?border_type src ddepth kernel_x kernel_y

Applies a separable linear filter to an image.

The function applies a separable linear filter to the image. That is, first, every row of src is filtered with the 1D kernel kernelX. Then, every column of the result is filtered with the 1D kernel kernelY. The final result shifted by delta is stored in dst .

• Parameter: src: Source image.
• Parameter: dst: Destination image of the same size and the same number of channels as src .
• Parameter: ddepth: Destination image depth, see filter_depths "combinations"
• Parameter: kernel_x: Coefficients for filtering each row.
• Parameter: kernel_y: Coefficients for filtering each column.
• Parameter: anchor: Anchor position within the kernel. The default value (-1,-1) means that the anchor is at the kernel center.
• Parameter: delta: Value added to the filtered results before storing them.
• Parameter: border_type: Pixel extrapolation method, see #BorderTypes. #BORDER_WRAP is not supported. See also: filter2D, Sobel, GaussianBlur, boxFilter, blur

Usage: sobel ?dst ?ksize ?scale ?delta ?border_type src ddepth dx dy

Calculates the first, second, third, or mixed image derivatives using an extended Sobel operator.

In all cases except one, the \texttt{ksize} \times \texttt{ksize} separable kernel is used to calculate the derivative. When \texttt{ksize = 1} , the 3 \times 1 or 1 \times 3 kernel is used (that is, no Gaussian smoothing is done). ksize = 1 can only be used for the first or the second x- or y- derivatives.

There is also the special value ksize = #FILTER_SCHARR (-1) that corresponds to the 3\times3 Scharr filter that may give more accurate results than the 3\times3 Sobel. The Scharr aperture is

\vecthreethree{-3}{0}{3}{-10}{0}{10}{-3}{0}{3}

for the x-derivative, or transposed for the y-derivative.

The function calculates an image derivative by convolving the image with the appropriate kernel:

\texttt{dst} = \frac{\partial^{xorder+yorder} \texttt{src}}{\partial x^{xorder} \partial y^{yorder}}

The Sobel operators combine Gaussian smoothing and differentiation, so the result is more or less resistant to the noise. Most often, the function is called with ( xorder = 1, yorder = 0, ksize = 3) or ( xorder = 0, yorder = 1, ksize = 3) to calculate the first x- or y- image derivative. The first case corresponds to a kernel of:

\vecthreethree{-1}{0}{1}{-2}{0}{2}{-1}{0}{1}

The second case corresponds to a kernel of:

\vecthreethree{-1}{-2}{-1}{0}{0}{0}{1}{2}{1}

• Parameter: src: input image.
• Parameter: dst: output image of the same size and the same number of channels as src .
• Parameter: ddepth: output image depth, see filter_depths "combinations"; in the case of 8-bit input images it will result in truncated derivatives.
• Parameter: dx: order of the derivative x.
• Parameter: dy: order of the derivative y.
• Parameter: ksize: size of the extended Sobel kernel; it must be 1, 3, 5, or 7.
• Parameter: scale: optional scale factor for the computed derivative values; by default, no scaling is applied (see #getDerivKernels for details).
• Parameter: delta: optional delta value that is added to the results prior to storing them in dst.
• Parameter: border_type: pixel extrapolation method, see #BorderTypes. #BORDER_WRAP is not supported. See also: Scharr, Laplacian, sepFilter2D, filter2D, GaussianBlur, cartToPolar

Usage: spatial_gradient ?dx ?dy ?ksize ?border_type src

Calculates the first order image derivative in both x and y using a Sobel operator

Equivalent to calling:

Sobel( src, dx, CV_16SC1, 1, 0, 3 );
Sobel( src, dy, CV_16SC1, 0, 1, 3 );

• Parameter: src: input image.
• Parameter: dx: output image with first-order derivative in x.
• Parameter: dy: output image with first-order derivative in y.
• Parameter: ksize: size of Sobel kernel. It must be 3.
• Parameter: border_type: pixel extrapolation method, see #BorderTypes. Only #BORDER_DEFAULT=#BORDER_REFLECT_101 and #BORDER_REPLICATE are supported.

See also: Sobel

Usage: scharr ?dst ?scale ?delta ?border_type src ddepth dx dy

Calculates the first x- or y- image derivative using Scharr operator.

The function computes the first x- or y- spatial image derivative using the Scharr operator. The call

\texttt{Scharr(src, dst, ddepth, dx, dy, scale, delta, borderType)}

is equivalent to

\texttt{Sobel(src, dst, ddepth, dx, dy, FILTER_SCHARR, scale, delta, borderType)} .

• Parameter: src: input image.
• Parameter: dst: output image of the same size and the same number of channels as src.
• Parameter: ddepth: output image depth, see filter_depths "combinations"
• Parameter: dx: order of the derivative x.
• Parameter: dy: order of the derivative y.
• Parameter: scale: optional scale factor for the computed derivative values; by default, no scaling is applied (see #getDerivKernels for details).
• Parameter: delta: optional delta value that is added to the results prior to storing them in dst.
• Parameter: border_type: pixel extrapolation method, see #BorderTypes. #BORDER_WRAP is not supported. See also: cartToPolar

Usage: laplacian ?dst ?ksize ?scale ?delta ?border_type src ddepth

Calculates the Laplacian of an image.

The function calculates the Laplacian of the source image by adding up the second x and y derivatives calculated using the Sobel operator:

\texttt{dst} = \Delta \texttt{src} = \frac{\partial^2 \texttt{src}}{\partial x^2} + \frac{\partial^2 \texttt{src}}{\partial y^2}

This is done when ksize > 1. When ksize == 1, the Laplacian is computed by filtering the image with the following 3 \times 3 aperture:

\vecthreethree {0}{1}{0}{1}{-4}{1}{0}{1}{0}

• Parameter: src: Source image.
• Parameter: dst: Destination image of the same size and the same number of channels as src .
• Parameter: ddepth: Desired depth of the destination image.
• Parameter: ksize: Aperture size used to compute the second-derivative filters. See #getDerivKernels for details. The size must be positive and odd.
• Parameter: scale: Optional scale factor for the computed Laplacian values. By default, no scaling is applied. See #getDerivKernels for details.
• Parameter: delta: Optional delta value that is added to the results prior to storing them in dst .
• Parameter: border_type: Pixel extrapolation method, see #BorderTypes. #BORDER_WRAP is not supported. See also: Sobel, Scharr

Usage: canny1 ?edges ?aperture_size ?l2gradient image threshold1 threshold2

Finds edges in an image using the Canny algorithm Canny86 .

The function finds edges in the input image and marks them in the output map edges using the Canny algorithm. The smallest value between threshold1 and threshold2 is used for edge linking. The largest value is used to find initial segments of strong edges. See <http://en.wikipedia.org/wiki/Canny_edge_detector>

• Parameter: image: 8-bit input image.
• Parameter: edges: output edge map; single channels 8-bit image, which has the same size as image .
• Parameter: threshold1: first threshold for the hysteresis procedure.
• Parameter: threshold2: second threshold for the hysteresis procedure.
• Parameter: aperture_size: aperture size for the Sobel operator.
• Parameter: l2gradient: a flag, indicating whether a more accurate L_2 norm =\sqrt{(dI/dx)^2 + (dI/dy)^2} should be used to calculate the image gradient magnitude ( L2gradient=true ), or whether the default L_1 norm =|dI/dx|+|dI/dy| is enough ( L2gradient=false ).

Usage: canny2 ?edges ?l2gradient dx dy threshold1 threshold2

\overload

Finds edges in an image using the Canny algorithm with custom image gradient.

• Parameter: dx: 16-bit x derivative of input image (CV_16SC1 or CV_16SC3).
• Parameter: dy: 16-bit y derivative of input image (same type as dx).
• Parameter: edges: output edge map; single channels 8-bit image, which has the same size as image .
• Parameter: threshold1: first threshold for the hysteresis procedure.
• Parameter: threshold2: second threshold for the hysteresis procedure.
• Parameter: l2gradient: a flag, indicating whether a more accurate L_2 norm =\sqrt{(dI/dx)^2 + (dI/dy)^2} should be used to calculate the image gradient magnitude ( L2gradient=true ), or whether the default L_1 norm =|dI/dx|+|dI/dy| is enough ( L2gradient=false ).

Usage: corner_min_eigen_val ?dst ?ksize ?border_type src block_size

Calculates the minimal eigenvalue of gradient matrices for corner detection.

The function is similar to cornerEigenValsAndVecs but it calculates and stores only the minimal eigenvalue of the covariance matrix of derivatives, that is, \min(\lambda_1, \lambda_2) in terms of the formulae in the cornerEigenValsAndVecs description.

• Parameter: src: Input single-channel 8-bit or floating-point image.
• Parameter: dst: Image to store the minimal eigenvalues. It has the type CV_32FC1 and the same size as src .
• Parameter: block_size: Neighborhood size (see the details on #cornerEigenValsAndVecs ).
• Parameter: ksize: Aperture parameter for the Sobel operator.
• Parameter: border_type: Pixel extrapolation method. See #BorderTypes. #BORDER_WRAP is not supported.

Usage: corner_harris ?dst ?border_type src block_size ksize k

Harris corner detector.

The function runs the Harris corner detector on the image. Similarly to cornerMinEigenVal and cornerEigenValsAndVecs , for each pixel (x, y) it calculates a 2\times2 gradient covariance matrix M^{(x,y)} over a \texttt{blockSize} \times \texttt{blockSize} neighborhood. Then, it computes the following characteristic:

\texttt{dst} (x,y) = \mathrm{det} M^{(x,y)} - k \cdot \left ( \mathrm{tr} M^{(x,y)} \right )^2

Corners in the image can be found as the local maxima of this response map.

• Parameter: src: Input single-channel 8-bit or floating-point image.
• Parameter: dst: Image to store the Harris detector responses. It has the type CV_32FC1 and the same size as src .
• Parameter: block_size: Neighborhood size (see the details on #cornerEigenValsAndVecs ).
• Parameter: ksize: Aperture parameter for the Sobel operator.
• Parameter: k: Harris detector free parameter. See the formula above.
• Parameter: border_type: Pixel extrapolation method. See #BorderTypes. #BORDER_WRAP is not supported.

Usage: corner_eigen_vals_and_vecs ?dst ?border_type src block_size ksize

Calculates eigenvalues and eigenvectors of image blocks for corner detection.

For every pixel p , the function cornerEigenValsAndVecs considers a blockSize \times blockSize neighborhood S(p) . It calculates the covariation matrix of derivatives over the neighborhood as:

M = \begin{bmatrix} \sum _{S(p)}(dI/dx)^2 & \sum _{S(p)}dI/dx dI/dy \\ \sum _{S(p)}dI/dx dI/dy & \sum _{S(p)}(dI/dy)^2 \end{bmatrix}

where the derivatives are computed using the Sobel operator.

After that, it finds eigenvectors and eigenvalues of M and stores them in the destination image as (\lambda_1, \lambda_2, x_1, y_1, x_2, y_2) where

• \lambda_1, \lambda_2 are the non-sorted eigenvalues of M
• x_1, y_1 are the eigenvectors corresponding to \lambda_1
• x_2, y_2 are the eigenvectors corresponding to \lambda_2

The output of the function can be used for robust edge or corner detection.

• Parameter: src: Input single-channel 8-bit or floating-point image.
• Parameter: dst: Image to store the results. It has the same size as src and the type CV_32FC(6) .
• Parameter: block_size: Neighborhood size (see details below).
• Parameter: ksize: Aperture parameter for the Sobel operator.
• Parameter: border_type: Pixel extrapolation method. See #BorderTypes. #BORDER_WRAP is not supported.

See also: cornerMinEigenVal, cornerHarris, preCornerDetect

Usage: pre_corner_detect ?dst ?border_type src ksize

Calculates a feature map for corner detection.

The function calculates the complex spatial derivative-based function of the source image

\texttt{dst} = (D_x \texttt{src} )^2 \cdot D_{yy} \texttt{src} + (D_y \texttt{src} )^2 \cdot D_{xx} \texttt{src} - 2 D_x \texttt{src} \cdot D_y \texttt{src} \cdot D_{xy} \texttt{src}

where D_x , D_y are the first image derivatives, D_{xx} , D_{yy} are the second image derivatives, and D_{xy} is the mixed derivative.

The corners can be found as local maximums of the functions, as shown below:

Mat corners, dilated_corners;
preCornerDetect(image, corners, 3);
// dilation with 3x3 rectangular structuring element
dilate(corners, dilated_corners, Mat(), 1);
Mat corner_mask = corners == dilated_corners;

• Parameter: src: Source single-channel 8-bit of floating-point image.
• Parameter: dst: Output image that has the type CV_32F and the same size as src .
• Parameter: ksize: %Aperture size of the Sobel .
• Parameter: border_type: Pixel extrapolation method. See #BorderTypes. #BORDER_WRAP is not supported.

Usage: good_features_to_track1 ?corners ?mask ?block_size ?use_harris_detector ?k image max_corners quality_level min_distance

Determines strong corners on an image.

The function finds the most prominent corners in the image or in the specified image region, as described in Shi94

• Function calculates the corner quality measure at every source image pixel using the #cornerMinEigenVal or #cornerHarris .
• Function performs a non-maximum suppression (the local maximums in *3 x 3* neighborhood are retained).
• The corners with the minimal eigenvalue less than \texttt{qualityLevel} \cdot \max_{x,y} qualityMeasureMap(x,y) are rejected.
• The remaining corners are sorted by the quality measure in the descending order.
• Function throws away each corner for which there is a stronger corner at a distance less than maxDistance.

The function can be used to initialize a point-based tracker of an object.

Note: If the function is called with different values A and B of the parameter qualityLevel , and A \> B, the vector of returned corners with qualityLevel=A will be the prefix of the output vector with qualityLevel=B .

• Parameter: image: Input 8-bit or floating-point 32-bit, single-channel image.
• Parameter: corners: Output vector of detected corners.
• Parameter: max_corners: Maximum number of corners to return. If there are more corners than are found, the strongest of them is returned. maxCorners <= 0 implies that no limit on the maximum is set and all detected corners are returned.
• Parameter: quality_level: Parameter characterizing the minimal accepted quality of image corners. The parameter value is multiplied by the best corner quality measure, which is the minimal eigenvalue (see #cornerMinEigenVal ) or the Harris function response (see #cornerHarris ). The corners with the quality measure less than the product are rejected. For example, if the best corner has the quality measure = 1500, and the qualityLevel=0.01 , then all the corners with the quality measure less than 15 are rejected.
• Parameter: min_distance: Minimum possible Euclidean distance between the returned corners.
• Parameter: mask: Optional region of interest. If the image is not empty (it needs to have the type CV_8UC1 and the same size as image ), it specifies the region in which the corners are detected.
• Parameter: block_size: Size of an average block for computing a derivative covariation matrix over each pixel neighborhood. See cornerEigenValsAndVecs .
• Parameter: use_harris_detector: Parameter indicating whether to use a Harris detector (see #cornerHarris) or #cornerMinEigenVal.
• Parameter: k: Free parameter of the Harris detector.

See also: cornerMinEigenVal, cornerHarris, calcOpticalFlowPyrLK, estimateRigidTransform,

Usage: good_features_to_track2 ?corners ?use_harris_detector ?k image max_corners quality_level min_distance mask block_size gradient_size

Usage: hough_lines ?lines ?srn ?stn ?min_theta ?max_theta image rho theta threshold

Finds lines in a binary image using the standard Hough transform.

The function implements the standard or standard multi-scale Hough transform algorithm for line detection. See <http://homepages.inf.ed.ac.uk/rbf/HIPR2/hough.htm> for a good explanation of Hough transform.

• Parameter: image: 8-bit, single-channel binary source image. The image may be modified by the function.
• Parameter: lines: Output vector of lines. Each line is represented by a 2 or 3 element vector (\rho, \theta) or (\rho, \theta, \textrm{votes}) . \rho is the distance from the coordinate origin (0,0) (top-left corner of the image). \theta is the line rotation angle in radians ( 0 \sim \textrm{vertical line}, \pi/2 \sim \textrm{horizontal line} ). \textrm{votes} is the value of accumulator.
• Parameter: rho: Distance resolution of the accumulator in pixels.
• Parameter: theta: Angle resolution of the accumulator in radians.
• Parameter: threshold: Accumulator threshold parameter. Only those lines are returned that get enough votes ( >\texttt{threshold} ).
• Parameter: srn: For the multi-scale Hough transform, it is a divisor for the distance resolution rho . The coarse accumulator distance resolution is rho and the accurate accumulator resolution is rho/srn . If both srn=0 and stn=0 , the classical Hough transform is used. Otherwise, both these parameters should be positive.
• Parameter: stn: For the multi-scale Hough transform, it is a divisor for the distance resolution theta.
• Parameter: min_theta: For standard and multi-scale Hough transform, minimum angle to check for lines. Must fall between 0 and max_theta.
• Parameter: max_theta: For standard and multi-scale Hough transform, maximum angle to check for lines. Must fall between min_theta and CV_PI.

Usage: hough_lines_p ?lines ?min_line_length ?max_line_gap image rho theta threshold

Finds line segments in a binary image using the probabilistic Hough transform.

The function implements the probabilistic Hough transform algorithm for line detection, described in Matas00

See the line detection example below: Include: snippets/imgproc_HoughLinesP.cpp This is a sample picture the function parameters have been tuned for:

!image(pics/building.jpg)

And this is the output of the above program in case of the probabilistic Hough transform:

!image(pics/houghp.png)

• Parameter: image: 8-bit, single-channel binary source image. The image may be modified by the function.
• Parameter: lines: Output vector of lines. Each line is represented by a 4-element vector (x_1, y_1, x_2, y_2) , where (x_1,y_1) and (x_2, y_2) are the ending points of each detected line segment.
• Parameter: rho: Distance resolution of the accumulator in pixels.
• Parameter: theta: Angle resolution of the accumulator in radians.
• Parameter: threshold: Accumulator threshold parameter. Only those lines are returned that get enough votes ( >\texttt{threshold} ).
• Parameter: min_line_length: Minimum line length. Line segments shorter than that are rejected.
• Parameter: max_line_gap: Maximum allowed gap between points on the same line to link them.

See also: LineSegmentDetector

Usage: hough_lines_point_set ?_lines _point lines_max threshold min_rho max_rho rho_step min_theta max_theta theta_step

Finds lines in a set of points using the standard Hough transform.

The function finds lines in a set of points using a modification of the Hough transform. Include: snippets/imgproc_HoughLinesPointSet.cpp

• Parameter: _point: Input vector of points. Each vector must be encoded as a Point vector (x,y) . Type must be CV_32FC2 or CV_32SC2.
• Parameter: _lines: Output vector of found lines. Each vector is encoded as a vector<Vec3d> (votes, rho, theta) . The larger the value of 'votes', the higher the reliability of the Hough line.
• Parameter: lines_max: Max count of hough lines.
• Parameter: threshold: Accumulator threshold parameter. Only those lines are returned that get enough votes ( >\texttt{threshold} )
• Parameter: min_rho: Minimum Distance value of the accumulator in pixels.
• Parameter: max_rho: Maximum Distance value of the accumulator in pixels.
• Parameter: rho_step: Distance resolution of the accumulator in pixels.
• Parameter: min_theta: Minimum angle value of the accumulator in radians.
• Parameter: max_theta: Maximum angle value of the accumulator in radians.
• Parameter: theta_step: Angle resolution of the accumulator in radians.

Usage: hough_circles ?circles ?param1 ?param2 ?min_radius ?max_radius image cv_method dp min_dist

Finds circles in a grayscale image using the Hough transform.

The function finds circles in a grayscale image using a modification of the Hough transform.

Example: : Include: snippets/imgproc_HoughLinesCircles.cpp

Note: Usually the function detects the centers of circles well. However, it may fail to find correct radii. You can assist to the function by specifying the radius range ( minRadius and maxRadius ) if you know it. Or, in the case of #HOUGH_GRADIENT method you may set maxRadius to a negative number to return centers only without radius search, and find the correct radius using an additional procedure.

It also helps to smooth image a bit unless it's already soft. For example, GaussianBlur() with 7x7 kernel and 1.5x1.5 sigma or similar blurring may help.

• Parameter: image: 8-bit, single-channel, grayscale input image.
• Parameter: circles: Output vector of found circles. Each vector is encoded as 3 or 4 element floating-point vector (x, y, radius) or (x, y, radius, votes) .
• Parameter: cv_method: Detection method, see #HoughModes. The available methods are #HOUGH_GRADIENT and #HOUGH_GRADIENT_ALT.
• Parameter: dp: Inverse ratio of the accumulator resolution to the image resolution. For example, if dp=1 , the accumulator has the same resolution as the input image. If dp=2 , the accumulator has half as big width and height. For #HOUGH_GRADIENT_ALT the recommended value is dp=1.5, unless some small very circles need to be detected.
• Parameter: min_dist: Minimum distance between the centers of the detected circles. If the parameter is too small, multiple neighbor circles may be falsely detected in addition to a true one. If it is too large, some circles may be missed.
• Parameter: param1: First method-specific parameter. In case of #HOUGH_GRADIENT and #HOUGH_GRADIENT_ALT, it is the higher threshold of the two passed to the Canny edge detector (the lower one is twice smaller). Note that #HOUGH_GRADIENT_ALT uses #Scharr algorithm to compute image derivatives, so the threshold value shough normally be higher, such as 300 or normally exposed and contrasty images.
• Parameter: param2: Second method-specific parameter. In case of #HOUGH_GRADIENT, it is the accumulator threshold for the circle centers at the detection stage. The smaller it is, the more false circles may be detected. Circles, corresponding to the larger accumulator values, will be returned first. In the case of #HOUGH_GRADIENT_ALT algorithm, this is the circle "perfectness" measure. The closer it to 1, the better shaped circles algorithm selects. In most cases 0.9 should be fine. If you want get better detection of small circles, you may decrease it to 0.85, 0.8 or even less. But then also try to limit the search range minRadius, maxRadius to avoid many false circles.
• Parameter: min_radius: Minimum circle radius.
• Parameter: max_radius: Maximum circle radius. If <= 0, uses the maximum image dimension. If < 0, #HOUGH_GRADIENT returns centers without finding the radius. #HOUGH_GRADIENT_ALT always computes circle radiuses.

See also: fitEllipse, minEnclosingCircle

Usage: erode ?dst ?anchor ?iterations ?border_type ?border_value src kernel

Erodes an image by using a specific structuring element.

The function erodes the source image using the specified structuring element that determines the shape of a pixel neighborhood over which the minimum is taken:

\, \texttt{element} (x',y') \ne0 } \texttt{src} (x+x',y+y')

The function supports the in-place mode. Erosion can be applied several ( iterations ) times. In case of multi-channel images, each channel is processed independently.

• Parameter: src: input image; the number of channels can be arbitrary, but the depth should be one of CV_8U, CV_16U, CV_16S, CV_32F or CV_64F.
• Parameter: dst: output image of the same size and type as src.
• Parameter: kernel: structuring element used for erosion; if element=Mat(), a 3 x 3 rectangular structuring element is used. Kernel can be created using #getStructuringElement.
• Parameter: anchor: position of the anchor within the element; default value (-1, -1) means that the anchor is at the element center.
• Parameter: iterations: number of times erosion is applied.
• Parameter: border_type: pixel extrapolation method, see #BorderTypes. #BORDER_WRAP is not supported.
• Parameter: border_value: border value in case of a constant border See also: dilate, morphologyEx, getStructuringElement

Usage: dilate ?dst ?anchor ?iterations ?border_type ?border_value src kernel

Dilates an image by using a specific structuring element.

The function dilates the source image using the specified structuring element that determines the shape of a pixel neighborhood over which the maximum is taken: \, \texttt{element} (x',y') \ne0 } \texttt{src} (x+x',y+y')

The function supports the in-place mode. Dilation can be applied several ( iterations ) times. In case of multi-channel images, each channel is processed independently.

• Parameter: src: input image; the number of channels can be arbitrary, but the depth should be one of CV_8U, CV_16U, CV_16S, CV_32F or CV_64F.
• Parameter: dst: output image of the same size and type as src.
• Parameter: kernel: structuring element used for dilation; if elemenat=Mat(), a 3 x 3 rectangular structuring element is used. Kernel can be created using #getStructuringElement
• Parameter: anchor: position of the anchor within the element; default value (-1, -1) means that the anchor is at the element center.
• Parameter: iterations: number of times dilation is applied.
• Parameter: border_type: pixel extrapolation method, see #BorderTypes. #BORDER_WRAP is not suported.
• Parameter: border_value: border value in case of a constant border See also: erode, morphologyEx, getStructuringElement

Usage: morphology_ex ?dst ?anchor ?iterations ?border_type ?border_value src op kernel

Performs advanced morphological transformations.

The function cv::morphologyEx can perform advanced morphological transformations using an erosion and dilation as basic operations.

Any of the operations can be done in-place. In case of multi-channel images, each channel is processed independently.

• Parameter: src: Source image. The number of channels can be arbitrary. The depth should be one of CV_8U, CV_16U, CV_16S, CV_32F or CV_64F.
• Parameter: dst: Destination image of the same size and type as source image.
• Parameter: op: Type of a morphological operation, see #MorphTypes
• Parameter: kernel: Structuring element. It can be created using #getStructuringElement.
• Parameter: anchor: Anchor position with the kernel. Negative values mean that the anchor is at the kernel center.
• Parameter: iterations: Number of times erosion and dilation are applied.
• Parameter: border_type: Pixel extrapolation method, see #BorderTypes. #BORDER_WRAP is not supported.
• Parameter: border_value: Border value in case of a constant border. The default value has a special meaning. See also: dilate, erode, getStructuringElement Note: The number of iterations is the number of times erosion or dilatation operation will be applied. For instance, an opening operation (#MORPH_OPEN) with two iterations is equivalent to apply successively: erode -> erode -> dilate -> dilate (and not erode -> dilate -> erode -> dilate).

Usage: resize ?dst ?fx ?fy ?interpolation src dsize

Resizes an image.

The function resize resizes the image src down to or up to the specified size. Note that the initial dst type or size are not taken into account. Instead, the size and type are derived from the src,dsize,fx, and fy. If you want to resize src so that it fits the pre-created dst, you may call the function as follows:

// explicitly specify dsize=dst.size(); fx and fy will be computed from that.
resize(src, dst, dst.size(), 0, 0, interpolation);

If you want to decimate the image by factor of 2 in each direction, you can call the function this way:

// specify fx and fy and let the function compute the destination image size.
resize(src, dst, Size(), 0.5, 0.5, interpolation);

To shrink an image, it will generally look best with #INTER_AREA interpolation, whereas to enlarge an image, it will generally look best with c#INTER_CUBIC (slow) or #INTER_LINEAR (faster but still looks OK).

• Parameter: src: input image.
• Parameter: dst: output image; it has the size dsize (when it is non-zero) or the size computed from src.size(), fx, and fy; the type of dst is the same as of src.
• Parameter: dsize: output image size; if it equals zero, it is computed as: \texttt{dsize = Size(round(fx*src.cols), round(fy*src.rows))} Either dsize or both fx and fy must be non-zero.
• Parameter: fx: scale factor along the horizontal axis; when it equals 0, it is computed as \texttt{(double)dsize.width/src.cols}
• Parameter: fy: scale factor along the vertical axis; when it equals 0, it is computed as \texttt{(double)dsize.height/src.rows}
• Parameter: interpolation: interpolation method, see #InterpolationFlags

See also: warpAffine, warpPerspective, remap

Usage: warp_affine ?dst ?flags ?border_mode ?border_value src m dsize

Applies an affine transformation to an image.

The function warpAffine transforms the source image using the specified matrix:

\texttt{dst} (x,y) = \texttt{src} ( \texttt{M} _{11} x + \texttt{M} _{12} y + \texttt{M} _{13}, \texttt{M} _{21} x + \texttt{M} _{22} y + \texttt{M} _{23})

when the flag #WARP_INVERSE_MAP is set. Otherwise, the transformation is first inverted with #invertAffineTransform and then put in the formula above instead of M. The function cannot operate in-place.

• Parameter: src: input image.
• Parameter: dst: output image that has the size dsize and the same type as src .
• Parameter: m: 2\times 3 transformation matrix.
• Parameter: dsize: size of the output image.
• Parameter: flags: combination of interpolation methods (see #InterpolationFlags) and the optional flag #WARP_INVERSE_MAP that means that M is the inverse transformation ( \texttt{dst}\rightarrow\texttt{src} ).
• Parameter: border_mode: pixel extrapolation method (see #BorderTypes); when borderMode=#BORDER_TRANSPARENT, it means that the pixels in the destination image corresponding to the "outliers" in the source image are not modified by the function.
• Parameter: border_value: value used in case of a constant border; by default, it is 0.

See also: warpPerspective, resize, remap, getRectSubPix, transform

Usage: warp_perspective ?dst ?flags ?border_mode ?border_value src m dsize

Applies a perspective transformation to an image.

The function warpPerspective transforms the source image using the specified matrix:

\texttt{dst} (x,y) = \texttt{src} \left ( \frac{M_{11} x + M_{12} y + M_{13}}{M_{31} x + M_{32} y + M_{33}} , \frac{M_{21} x + M_{22} y + M_{23}}{M_{31} x + M_{32} y + M_{33}} \right )

when the flag #WARP_INVERSE_MAP is set. Otherwise, the transformation is first inverted with invert and then put in the formula above instead of M. The function cannot operate in-place.

• Parameter: src: input image.
• Parameter: dst: output image that has the size dsize and the same type as src .
• Parameter: m: 3\times 3 transformation matrix.
• Parameter: dsize: size of the output image.
• Parameter: flags: combination of interpolation methods (#INTER_LINEAR or #INTER_NEAREST) and the optional flag #WARP_INVERSE_MAP, that sets M as the inverse transformation ( \texttt{dst}\rightarrow\texttt{src} ).
• Parameter: border_mode: pixel extrapolation method (#BORDER_CONSTANT or #BORDER_REPLICATE).
• Parameter: border_value: value used in case of a constant border; by default, it equals 0.

See also: warpAffine, resize, remap, getRectSubPix, perspectiveTransform

Usage: remap ?dst ?border_mode ?border_value src map1 map2 interpolation

Applies a generic geometrical transformation to an image.

The function remap transforms the source image using the specified map:

\texttt{dst} (x,y) = \texttt{src} (map_x(x,y),map_y(x,y))

where values of pixels with non-integer coordinates are computed using one of available interpolation methods. map_x and map_y can be encoded as separate floating-point maps in map_1 and map_2 respectively, or interleaved floating-point maps of (x,y) in map_1 , or fixed-point maps created by using convertMaps. The reason you might want to convert from floating to fixed-point representations of a map is that they can yield much faster (\~2x) remapping operations. In the converted case, map_1 contains pairs (cvFloor(x), cvFloor(y)) and map_2 contains indices in a table of interpolation coefficients.

This function cannot operate in-place.

• Parameter: src: Source image.
• Parameter: dst: Destination image. It has the same size as map1 and the same type as src .
• Parameter: map1: The first map of either (x,y) points or just x values having the type CV_16SC2 , CV_32FC1, or CV_32FC2. See convertMaps for details on converting a floating point representation to fixed-point for speed.
• Parameter: map2: The second map of y values having the type CV_16UC1, CV_32FC1, or none (empty map if map1 is (x,y) points), respectively.
• Parameter: interpolation: Interpolation method (see #InterpolationFlags). The methods #INTER_AREA and #INTER_LINEAR_EXACT are not supported by this function.
• Parameter: border_mode: Pixel extrapolation method (see #BorderTypes). When borderMode=#BORDER_TRANSPARENT, it means that the pixels in the destination image that corresponds to the "outliers" in the source image are not modified by the function.
• Parameter: border_value: Value used in case of a constant border. By default, it is 0. Note: Due to current implementation limitations the size of an input and output images should be less than 32767x32767.

Usage: convert_maps ?dstmap1 ?dstmap2 ?nninterpolation map1 map2 dstmap1type

Converts image transformation maps from one representation to another.

The function converts a pair of maps for remap from one representation to another. The following options ( (map1.type(), map2.type()) \rightarrow (dstmap1.type(), dstmap2.type()) ) are supported:

• \texttt{(CV_32FC1, CV_32FC1)} \rightarrow \texttt{(CV_16SC2, CV_16UC1)} . This is the most frequently used conversion operation, in which the original floating-point maps (see remap ) are converted to a more compact and much faster fixed-point representation. The first output array contains the rounded coordinates and the second array (created only when nninterpolation=false ) contains indices in the interpolation tables.

• \texttt{(CV_32FC2)} \rightarrow \texttt{(CV_16SC2, CV_16UC1)} . The same as above but the original maps are stored in one 2-channel matrix.

• Reverse conversion. Obviously, the reconstructed floating-point maps will not be exactly the same as the originals.

• Parameter: map1: The first input map of type CV_16SC2, CV_32FC1, or CV_32FC2 .
• Parameter: map2: The second input map of type CV_16UC1, CV_32FC1, or none (empty matrix), respectively.
• Parameter: dstmap1: The first output map that has the type dstmap1type and the same size as src .
• Parameter: dstmap2: The second output map.
• Parameter: dstmap1type: Type of the first output map that should be CV_16SC2, CV_32FC1, or CV_32FC2 .
• Parameter: nninterpolation: Flag indicating whether the fixed-point maps are used for the nearest-neighbor or for a more complex interpolation.

See also: remap, undistort, initUndistortRectifyMap

Usage: get_rotation_matrix2_d center angle scale

Calculates an affine matrix of 2D rotation.

The function calculates the following matrix:

\begin{bmatrix} \alpha & \beta & (1- \alpha ) \cdot \texttt{center.x} - \beta \cdot \texttt{center.y} \\ - \beta & \alpha & \beta \cdot \texttt{center.x} + (1- \alpha ) \cdot \texttt{center.y} \end{bmatrix}

where

\begin{array}{l} \alpha = \texttt{scale} \cdot \cos \texttt{angle} , \\ \beta = \texttt{scale} \cdot \sin \texttt{angle} \end{array}

The transformation maps the rotation center to itself. If this is not the target, adjust the shift.

• Parameter: center: Center of the rotation in the source image.
• Parameter: angle: Rotation angle in degrees. Positive values mean counter-clockwise rotation (the coordinate origin is assumed to be the top-left corner).
• Parameter: scale: Isotropic scale factor.

See also: getAffineTransform, warpAffine, transform

Usage: invert_affine_transform ?i_m m

Inverts an affine transformation.

The function computes an inverse affine transformation represented by 2 \times 3 matrix M:

\begin{bmatrix} a_{11} & a_{12} & b_1 \\ a_{21} & a_{22} & b_2 \end{bmatrix}

The result is also a 2 \times 3 matrix of the same type as M.

• Parameter: m: Original affine transformation.
• Parameter: i_m: Output reverse affine transformation.

Usage: get_perspective_transform ?solve_method src dst

Calculates a perspective transform from four pairs of the corresponding points.

The function calculates the 3 \times 3 matrix of a perspective transform so that:

\begin{bmatrix} t_i x'_i \\ t_i y'_i \\ t_i \end{bmatrix} = \texttt{map_matrix} \cdot \begin{bmatrix} x_i \\ y_i \\ 1 \end{bmatrix}

where

dst(i)=(x'_i,y'_i), src(i)=(x_i, y_i), i=0,1,2,3

• Parameter: src: Coordinates of quadrangle vertices in the source image.
• Parameter: dst: Coordinates of the corresponding quadrangle vertices in the destination image.
• Parameter: solve_method: method passed to cv::solve (#DecompTypes)

See also: findHomography, warpPerspective, perspectiveTransform

Usage: get_affine_transform src dst

Usage: get_rect_sub_pix ?patch ?patch_type image patch_size center

Retrieves a pixel rectangle from an image with sub-pixel accuracy.

The function getRectSubPix extracts pixels from src:

patch(x, y) = src(x + \texttt{center.x} - ( \texttt{dst.cols} -1)*0.5, y + \texttt{center.y} - ( \texttt{dst.rows} -1)*0.5)

where the values of the pixels at non-integer coordinates are retrieved using bilinear interpolation. Every channel of multi-channel images is processed independently. Also the image should be a single channel or three channel image. While the center of the rectangle must be inside the image, parts of the rectangle may be outside.

• Parameter: image: Source image.
• Parameter: patch_size: Size of the extracted patch.
• Parameter: center: Floating point coordinates of the center of the extracted rectangle within the source image. The center must be inside the image.
• Parameter: patch: Extracted patch that has the size patchSize and the same number of channels as src .
• Parameter: patch_type: Depth of the extracted pixels. By default, they have the same depth as src .

See also: warpAffine, warpPerspective

Usage: log_polar ?dst src center m flags

Remaps an image to semilog-polar coordinates space.

deprecated

This function produces same result as cv::warpPolar(src, dst, src.size(), center, maxRadius, flags+WARP_POLAR_LOG);

Transform the source image using the following transformation (See polar_remaps_reference_image "Polar remaps reference image d)"): \begin{array}{l} dst( \rho , \phi ) = src(x,y) \\ dst.size() \leftarrow src.size() \end{array}

where \begin{array}{l} I = (dx,dy) = (x - center.x,y - center.y) \\ \rho = M \cdot log_e(\texttt{magnitude} (I)) ,\\ \phi = Kangle \cdot \texttt{angle} (I) \\ \end{array}

and \begin{array}{l} M = src.cols / log_e(maxRadius) \\ Kangle = src.rows / 2\Pi \\ \end{array}

The function emulates the human "foveal" vision and can be used for fast scale and rotation-invariant template matching, for object tracking and so forth.

• Parameter: src: Source image
• Parameter: dst: Destination image. It will have same size and type as src.
• Parameter: center: The transformation center; where the output precision is maximal
• Parameter: m: Magnitude scale parameter. It determines the radius of the bounding circle to transform too.
• Parameter: flags: A combination of interpolation methods, see #InterpolationFlags

Note:

• The function can not operate in-place.
• To calculate magnitude and angle in degrees #cartToPolar is used internally thus angles are measured from 0 to 360 with accuracy about 0.3 degrees.

See also: cv::linearPolar

Usage: linear_polar ?dst src center max_radius flags

Remaps an image to polar coordinates space.

deprecated

This function produces same result as cv::warpPolar(src, dst, src.size(), center, maxRadius, flags)

Transform the source image using the following transformation (See polar_remaps_reference_image "Polar remaps reference image c)"): \begin{array}{l} dst( \rho , \phi ) = src(x,y) \\ dst.size() \leftarrow src.size() \end{array}

where \begin{array}{l} I = (dx,dy) = (x - center.x,y - center.y) \\ \rho = Kmag \cdot \texttt{magnitude} (I) ,\\ \phi = angle \cdot \texttt{angle} (I) \end{array}

and \begin{array}{l} Kx = src.cols / maxRadius \\ Ky = src.rows / 2\Pi \end{array}

• Parameter: src: Source image
• Parameter: dst: Destination image. It will have same size and type as src.
• Parameter: center: The transformation center;
• Parameter: max_radius: The radius of the bounding circle to transform. It determines the inverse magnitude scale parameter too.
• Parameter: flags: A combination of interpolation methods, see #InterpolationFlags

Note:

• The function can not operate in-place.
• To calculate magnitude and angle in degrees #cartToPolar is used internally thus angles are measured from 0 to 360 with accuracy about 0.3 degrees.

See also: cv::logPolar

Usage: warp_polar ?dst src dsize center max_radius flags

\brief Remaps an image to polar or semilog-polar coordinates space

polar_remaps_reference_image !Polar remaps reference(pics/polar_remap_doc.png)

Transform the source image using the following transformation: dst(\rho , \phi ) = src(x,y)

where \begin{array}{l} \vec{I} = (x - center.x, \;y - center.y) \\ \phi = Kangle \cdot \texttt{angle} (\vec{I}) \\ \rho = \left\{\begin{matrix} Klin \cdot \texttt{magnitude} (\vec{I}) & default \\ Klog \cdot log_e(\texttt{magnitude} (\vec{I})) & if \; semilog \\ \end{matrix}\right. \end{array}

and \begin{array}{l} Kangle = dsize.height / 2\Pi \\ Klin = dsize.width / maxRadius \\ Klog = dsize.width / log_e(maxRadius) \\ \end{array}

\par Linear vs semilog mapping

Polar mapping can be linear or semi-log. Add one of #WarpPolarMode to flags to specify the polar mapping mode.

Linear is the default mode.

The semilog mapping emulates the human "foveal" vision that permit very high acuity on the line of sight (central vision) in contrast to peripheral vision where acuity is minor.

\par Option on dsize:

• if both values in dsize <=0 (default), the destination image will have (almost) same area of source bounding circle: \begin{array}{l} dsize.area \leftarrow (maxRadius^2 \cdot \Pi) \\ dsize.width = \texttt{cvRound}(maxRadius) \\ dsize.height = \texttt{cvRound}(maxRadius \cdot \Pi) \\ \end{array}

• if only dsize.height <= 0, the destination image area will be proportional to the bounding circle area but scaled by Kx * Kx: \begin{array}{l} dsize.height = \texttt{cvRound}(dsize.width \cdot \Pi) \\ \end{array}

• if both values in dsize > 0 , the destination image will have the given size therefore the area of the bounding circle will be scaled to dsize.

\par Reverse mapping

You can get reverse mapping adding #WARP_INVERSE_MAP to flags \snippet polar_transforms.cpp InverseMap

In addiction, to calculate the original coordinate from a polar mapped coordinate (rho, phi)->(x, y) : \snippet polar_transforms.cpp InverseCoordinate

• Parameter: src: Source image.
• Parameter: dst: Destination image. It will have same type as src.
• Parameter: dsize: The destination image size (see description for valid options).
• Parameter: center: The transformation center.
• Parameter: max_radius: The radius of the bounding circle to transform. It determines the inverse magnitude scale parameter too.
• Parameter: flags: A combination of interpolation methods, #InterpolationFlags + #WarpPolarMode.
• Add #WARP_POLAR_LINEAR to select linear polar mapping (default)
• Add #WARP_POLAR_LOG to select semilog polar mapping
• Add #WARP_INVERSE_MAP for reverse mapping. Note:
• The function can not operate in-place.
• To calculate magnitude and angle in degrees #cartToPolar is used internally thus angles are measured from 0 to 360 with accuracy about 0.3 degrees.
• This function uses #remap. Due to current implementation limitations the size of an input and output images should be less than 32767x32767.

See also: cv::remap

Usage: integral1 ?sum ?sdepth src

Usage: integral2 ?sum ?sqsum ?sdepth ?sqdepth src

Usage: integral3 ?sum ?sqsum ?tilted ?sdepth ?sqdepth src

Calculates the integral of an image.

The function calculates one or more integral images for the source image as follows:

\texttt{sum} (X,Y) = \sum _{x<X,y<Y} \texttt{image} (x,y)

\texttt{sqsum} (X,Y) = \sum _{x<X,y<Y} \texttt{image} (x,y)^2

\texttt{tilted} (X,Y) = \sum _{y<Y,abs(x-X+1) \leq Y-y-1} \texttt{image} (x,y)

Using these integral images, you can calculate sum, mean, and standard deviation over a specific up-right or rotated rectangular region of the image in a constant time, for example:

\sum _{x_1 \leq x < x_2, \, y_1 \leq y < y_2} \texttt{image} (x,y) = \texttt{sum} (x_2,y_2)- \texttt{sum} (x_1,y_2)- \texttt{sum} (x_2,y_1)+ \texttt{sum} (x_1,y_1)

It makes possible to do a fast blurring or fast block correlation with a variable window size, for example. In case of multi-channel images, sums for each channel are accumulated independently.

As a practical example, the next figure shows the calculation of the integral of a straight rectangle Rect(3,3,3,2) and of a tilted rectangle Rect(5,1,2,3) . The selected pixels in the original image are shown, as well as the relative pixels in the integral images sum and tilted .

!integral calculation example(pics/integral.png)

• Parameter: src: input image as W \times H , 8-bit or floating-point (32f or 64f).
• Parameter: sum: integral image as (W+1)\times (H+1) , 32-bit integer or floating-point (32f or 64f).
• Parameter: sqsum: integral image for squared pixel values; it is (W+1)\times (H+1) , double-precision floating-point (64f) array.
• Parameter: tilted: integral for the image rotated by 45 degrees; it is (W+1)\times (H+1) array with the same data type as sum.
• Parameter: sdepth: desired depth of the integral and the tilted integral images, CV_32S, CV_32F, or CV_64F.
• Parameter: sqdepth: desired depth of the integral image of squared pixel values, CV_32F or CV_64F.

Usage: accumulate ?mask src dst

Adds an image to the accumulator image.

The function adds src or some of its elements to dst :

\texttt{dst} (x,y) \leftarrow \texttt{dst} (x,y) + \texttt{src} (x,y) \quad \text{if} \quad \texttt{mask} (x,y) \ne 0

The function supports multi-channel images. Each channel is processed independently.

The function cv::accumulate can be used, for example, to collect statistics of a scene background viewed by a still camera and for the further foreground-background segmentation.

• Parameter: src: Input image of type CV_8UC(n), CV_16UC(n), CV_32FC(n) or CV_64FC(n), where n is a positive integer.
• Parameter: dst: %Accumulator image with the same number of channels as input image, and a depth of CV_32F or CV_64F.
• Parameter: mask: Optional operation mask.

See also: accumulateSquare, accumulateProduct, accumulateWeighted

Usage: accumulate_square ?mask src dst

Adds the square of a source image to the accumulator image.

The function adds the input image src or its selected region, raised to a power of 2, to the accumulator dst :

\texttt{dst} (x,y) \leftarrow \texttt{dst} (x,y) + \texttt{src} (x,y)^2 \quad \text{if} \quad \texttt{mask} (x,y) \ne 0

The function supports multi-channel images. Each channel is processed independently.

• Parameter: src: Input image as 1- or 3-channel, 8-bit or 32-bit floating point.
• Parameter: dst: %Accumulator image with the same number of channels as input image, 32-bit or 64-bit floating-point.
• Parameter: mask: Optional operation mask.

See also: accumulateSquare, accumulateProduct, accumulateWeighted

Usage: accumulate_product ?mask src1 src2 dst

Adds the per-element product of two input images to the accumulator image.

The function adds the product of two images or their selected regions to the accumulator dst :

\texttt{dst} (x,y) \leftarrow \texttt{dst} (x,y) + \texttt{src1} (x,y) \cdot \texttt{src2} (x,y) \quad \text{if} \quad \texttt{mask} (x,y) \ne 0

The function supports multi-channel images. Each channel is processed independently.

• Parameter: src1: First input image, 1- or 3-channel, 8-bit or 32-bit floating point.
• Parameter: src2: Second input image of the same type and the same size as src1 .
• Parameter: dst: %Accumulator image with the same number of channels as input images, 32-bit or 64-bit floating-point.
• Parameter: mask: Optional operation mask.

See also: accumulate, accumulateSquare, accumulateWeighted

Usage: accumulate_weighted ?mask src dst alpha

Updates a running average.

The function calculates the weighted sum of the input image src and the accumulator dst so that dst becomes a running average of a frame sequence:

\texttt{dst} (x,y) \leftarrow (1- \texttt{alpha} ) \cdot \texttt{dst} (x,y) + \texttt{alpha} \cdot \texttt{src} (x,y) \quad \text{if} \quad \texttt{mask} (x,y) \ne 0

That is, alpha regulates the update speed (how fast the accumulator "forgets" about earlier images). The function supports multi-channel images. Each channel is processed independently.

• Parameter: src: Input image as 1- or 3-channel, 8-bit or 32-bit floating point.
• Parameter: dst: %Accumulator image with the same number of channels as input image, 32-bit or 64-bit floating-point.
• Parameter: alpha: Weight of the input image.
• Parameter: mask: Optional operation mask.

See also: accumulate, accumulateSquare, accumulateProduct

Usage: phase_correlate ?window ?response src1 src2

The function is used to detect translational shifts that occur between two images.

The operation takes advantage of the Fourier shift theorem for detecting the translational shift in the frequency domain. It can be used for fast image registration as well as motion estimation. For more information please see <http://en.wikipedia.org/wiki/Phase_correlation>

Calculates the cross-power spectrum of two supplied source arrays. The arrays are padded if needed with getOptimalDFTSize.

The function performs the following equations:

• First it applies a Hanning window (see <http://en.wikipedia.org/wiki/Hann_function>) to each image to remove possible edge effects. This window is cached until the array size changes to speed up processing time.
• Next it computes the forward DFTs of each source array: \mathbf{G}_a = \mathcal{F}\{src_1\}, \; \mathbf{G}_b = \mathcal{F}\{src_2\} where \mathcal{F} is the forward DFT.
• It then computes the cross-power spectrum of each frequency domain array: R = \frac{ \mathbf{G}_a \mathbf{G}_b^*}{ |\mathbf{G}_a \mathbf{G}_b^*|}
• Next the cross-correlation is converted back into the time domain via the inverse DFT: r = \mathcal{F}^{-1}\{R\}
• Finally, it computes the peak location and computes a 5x5 weighted centroid around the peak to achieve sub-pixel accuracy. (\Delta x, \Delta y) = \texttt{weightedCentroid} \{\arg \max_{(x, y)}\{r\}\}
• If non-zero, the response parameter is computed as the sum of the elements of r within the 5x5 centroid around the peak location. It is normalized to a maximum of 1 (meaning there is a single peak) and will be smaller when there are multiple peaks.

• Parameter: src1: Source floating point array (CV_32FC1 or CV_64FC1)
• Parameter: src2: Source floating point array (CV_32FC1 or CV_64FC1)
• Parameter: window: Floating point array with windowing coefficients to reduce edge effects (optional).
• Parameter: response: Signal power within the 5x5 centroid around the peak, between 0 and 1 (optional).
• Returns: detected phase shift (sub-pixel) between the two arrays.

See also: dft, getOptimalDFTSize, idft, mulSpectrums createHanningWindow

Usage: create_hanning_window ?dst win_size cv_type

This function computes a Hanning window coefficients in two dimensions.

See (http://en.wikipedia.org/wiki/Hann_function) and (http://en.wikipedia.org/wiki/Window_function) for more information.

An example is shown below:

// create hanning window of size 100x100 and type CV_32F
Mat hann;
createHanningWindow(hann, Size(100, 100), CV_32F);

• Parameter: dst: Destination array to place Hann coefficients in
• Parameter: win_size: The window size specifications (both width and height must be > 1)
• Parameter: cv_type: Created array type

Usage: threshold ?dst src thresh maxval cv_type

Applies a fixed-level threshold to each array element.

The function applies fixed-level thresholding to a multiple-channel array. The function is typically used to get a bi-level (binary) image out of a grayscale image ( #compare could be also used for this purpose) or for removing a noise, that is, filtering out pixels with too small or too large values. There are several types of thresholding supported by the function. They are determined by type parameter.

Also, the special values #THRESH_OTSU or #THRESH_TRIANGLE may be combined with one of the above values. In these cases, the function determines the optimal threshold value using the Otsu's or Triangle algorithm and uses it instead of the specified thresh.

Note: Currently, the Otsu's and Triangle methods are implemented only for 8-bit single-channel images.

• Parameter: src: input array (multiple-channel, 8-bit or 32-bit floating point).
• Parameter: dst: output array of the same size and type and the same number of channels as src.
• Parameter: thresh: threshold value.
• Parameter: maxval: maximum value to use with the #THRESH_BINARY and #THRESH_BINARY_INV thresholding types.
• Parameter: cv_type: thresholding type (see #ThresholdTypes).
• Returns: the computed threshold value if Otsu's or Triangle methods used.

See also: adaptiveThreshold, findContours, compare, min, max

Usage: adaptive_threshold ?dst src max_value adaptive_method threshold_type block_size c

Applies an adaptive threshold to an array.

The function transforms a grayscale image to a binary image according to the formulae:

• **THRESH_BINARY** dst(x,y) = \fork{\texttt{maxValue}}{if \(src(x,y) > T(x,y)\)}{0}{otherwise}
• **THRESH_BINARY_INV** dst(x,y) = \fork{0}{if \(src(x,y) > T(x,y)\)}{\texttt{maxValue}}{otherwise} where T(x,y) is a threshold calculated individually for each pixel (see adaptiveMethod parameter).

The function can process the image in-place.

• Parameter: src: Source 8-bit single-channel image.
• Parameter: dst: Destination image of the same size and the same type as src.
• Parameter: max_value: Non-zero value assigned to the pixels for which the condition is satisfied
• Parameter: adaptive_method: Adaptive thresholding algorithm to use, see #AdaptiveThresholdTypes. The #BORDER_REPLICATE | #BORDER_ISOLATED is used to process boundaries.
• Parameter: threshold_type: Thresholding type that must be either #THRESH_BINARY or #THRESH_BINARY_INV, see #ThresholdTypes.
• Parameter: block_size: Size of a pixel neighborhood that is used to calculate a threshold value for the pixel: 3, 5, 7, and so on.
• Parameter: c: Constant subtracted from the mean or weighted mean (see the details below). Normally, it is positive but may be zero or negative as well.

See also: threshold, blur, GaussianBlur

Usage: pyr_down ?dst ?dstsize ?border_type src

Blurs an image and downsamples it.

By default, size of the output image is computed as Size((src.cols+1)/2, (src.rows+1)/2), but in any case, the following conditions should be satisfied:

\begin{array}{l} | \texttt{dstsize.width} *2-src.cols| \leq 2 \\ | \texttt{dstsize.height} *2-src.rows| \leq 2 \end{array}

The function performs the downsampling step of the Gaussian pyramid construction. First, it convolves the source image with the kernel:

\frac{1}{256} \begin{bmatrix} 1 & 4 & 6 & 4 & 1 \\ 4 & 16 & 24 & 16 & 4 \\ 6 & 24 & 36 & 24 & 6 \\ 4 & 16 & 24 & 16 & 4 \\ 1 & 4 & 6 & 4 & 1 \end{bmatrix}

Then, it downsamples the image by rejecting even rows and columns.

• Parameter: src: input image.
• Parameter: dst: output image; it has the specified size and the same type as src.
• Parameter: dstsize: size of the output image.
• Parameter: border_type: Pixel extrapolation method, see #BorderTypes (#BORDER_CONSTANT isn't supported)

Usage: pyr_up ?dst ?dstsize ?border_type src

Upsamples an image and then blurs it.

By default, size of the output image is computed as Size(src.cols\*2, (src.rows\*2), but in any case, the following conditions should be satisfied:

\begin{array}{l} | \texttt{dstsize.width} -src.cols*2| \leq ( \texttt{dstsize.width} \mod 2) \\ | \texttt{dstsize.height} -src.rows*2| \leq ( \texttt{dstsize.height} \mod 2) \end{array}

The function performs the upsampling step of the Gaussian pyramid construction, though it can actually be used to construct the Laplacian pyramid. First, it upsamples the source image by injecting even zero rows and columns and then convolves the result with the same kernel as in pyrDown multiplied by 4.

• Parameter: src: input image.
• Parameter: dst: output image. It has the specified size and the same type as src .
• Parameter: dstsize: size of the output image.
• Parameter: border_type: Pixel extrapolation method, see #BorderTypes (only #BORDER_DEFAULT is supported)

Usage: calc_hist ?hist ?accumulate images channels mask hist_size ranges

Usage: calc_back_project ?dst images channels hist ranges scale

Usage: compare_hist h1 h2 cv_method

Compares two histograms.

The function cv::compareHist compares two dense or two sparse histograms using the specified method.

The function returns d(H_1, H_2) .

While the function works well with 1-, 2-, 3-dimensional dense histograms, it may not be suitable for high-dimensional sparse histograms. In such histograms, because of aliasing and sampling problems, the coordinates of non-zero histogram bins can slightly shift. To compare such histograms or more general sparse configurations of weighted points, consider using the #EMD function.

• Parameter: h1: First compared histogram.
• Parameter: h2: Second compared histogram of the same size as H1 .
• Parameter: cv_method: Comparison method, see #HistCompMethods

Usage: equalize_hist ?dst src

Equalizes the histogram of a grayscale image.

The function equalizes the histogram of the input image using the following algorithm:

• Calculate the histogram H for src .
• Normalize the histogram so that the sum of histogram bins is 255.
• Compute the integral of the histogram: H'_i = \sum _{0 \le j < i} H(j)
• Transform the image using H' as a look-up table: \texttt{dst}(x,y) = H'(\texttt{src}(x,y))

The algorithm normalizes the brightness and increases the contrast of the image.

• Parameter: src: Source 8-bit single channel image.
• Parameter: dst: Destination image of the same size and type as src .

Usage: watershed image markers

Performs a marker-based image segmentation using the watershed algorithm.

The function implements one of the variants of watershed, non-parametric marker-based segmentation algorithm, described in Meyer92 .

Before passing the image to the function, you have to roughly outline the desired regions in the image markers with positive (\>0) indices. So, every region is represented as one or more connected components with the pixel values 1, 2, 3, and so on. Such markers can be retrieved from a binary mask using #findContours and #drawContours (see the watershed.cpp demo). The markers are "seeds" of the future image regions. All the other pixels in markers , whose relation to the outlined regions is not known and should be defined by the algorithm, should be set to 0's. In the function output, each pixel in markers is set to a value of the "seed" components or to -1 at boundaries between the regions.

Note: Any two neighbor connected components are not necessarily separated by a watershed boundary (-1's pixels); for example, they can touch each other in the initial marker image passed to the function.

• Parameter: image: Input 8-bit 3-channel image.
• Parameter: markers: Input/output 32-bit single-channel image (map) of markers. It should have the same size as image .

See also: findContours

Group: imgproc_misc

Usage: grab_cut ?mode img mask rect bgd_model fgd_model iter_count

Runs the GrabCut algorithm.

The function implements the GrabCut image segmentation algorithm(http://en.wikipedia.org/wiki/GrabCut).

• Parameter: img: Input 8-bit 3-channel image.
• Parameter: mask: Input/output 8-bit single-channel mask. The mask is initialized by the function when mode is set to #GC_INIT_WITH_RECT. Its elements may have one of the #GrabCutClasses.
• Parameter: rect: ROI containing a segmented object. The pixels outside of the ROI are marked as "obvious background". The parameter is only used when mode==#GC_INIT_WITH_RECT .
• Parameter: bgd_model: Temporary array for the background model. Do not modify it while you are processing the same image.
• Parameter: fgd_model: Temporary arrays for the foreground model. Do not modify it while you are processing the same image.
• Parameter: iter_count: Number of iterations the algorithm should make before returning the result. Note that the result can be refined with further calls with mode==#GC_INIT_WITH_MASK or mode==GC_EVAL .
• Parameter: mode: Operation mode that could be one of the #GrabCutModes

Usage: distance_transform1 ?dst ?labels ?label_type src distance_type mask_size

Calculates the distance to the closest zero pixel for each pixel of the source image.

The function cv::distanceTransform calculates the approximate or precise distance from every binary image pixel to the nearest zero pixel. For zero image pixels, the distance will obviously be zero.

When maskSize == #DIST_MASK_PRECISE and distanceType == #DIST_L2 , the function runs the algorithm described in Felzenszwalb04 . This algorithm is parallelized with the TBB library.

In other cases, the algorithm Borgefors86 is used. This means that for a pixel the function finds the shortest path to the nearest zero pixel consisting of basic shifts: horizontal, vertical, diagonal, or knight's move (the latest is available for a 5\times 5 mask). The overall distance is calculated as a sum of these basic distances. Since the distance function should be symmetric, all of the horizontal and vertical shifts must have the same cost (denoted as a ), all the diagonal shifts must have the same cost (denoted as b), and all knight's moves must have the same cost (denoted as c). For the #DIST_C and #DIST_L1 types, the distance is calculated precisely, whereas for #DIST_L2 (Euclidean distance) the distance can be calculated only with a relative error (a 5\times 5 mask gives more accurate results). For a,b, and c, OpenCV uses the values suggested in the original paper:

• DIST_L1: a = 1, b = 2
• DIST_L2:
• 3 x 3: a=0.955, b=1.3693
• 5 x 5: a=1, b=1.4, c=2.1969
• DIST_C: a = 1, b = 1

Typically, for a fast, coarse distance estimation #DIST_L2, a 3\times 3 mask is used. For a more accurate distance estimation #DIST_L2, a 5\times 5 mask or the precise algorithm is used. Note that both the precise and the approximate algorithms are linear on the number of pixels.

This variant of the function does not only compute the minimum distance for each pixel (x, y) but also identifies the nearest connected component consisting of zero pixels (labelType==#DIST_LABEL_CCOMP) or the nearest zero pixel (labelType==#DIST_LABEL_PIXEL). Index of the component/pixel is stored in labels(x, y). When labelType==#DIST_LABEL_CCOMP, the function automatically finds connected components of zero pixels in the input image and marks them with distinct labels. When labelType==#DIST_LABEL_PIXEL, the function scans through the input image and marks all the zero pixels with distinct labels.

In this mode, the complexity is still linear. That is, the function provides a very fast way to compute the Voronoi diagram for a binary image. Currently, the second variant can use only the approximate distance transform algorithm, i.e. maskSize=#DIST_MASK_PRECISE is not supported yet.

• Parameter: src: 8-bit, single-channel (binary) source image.
• Parameter: dst: Output image with calculated distances. It is a 8-bit or 32-bit floating-point, single-channel image of the same size as src.
• Parameter: labels: Output 2D array of labels (the discrete Voronoi diagram). It has the type CV_32SC1 and the same size as src.
• Parameter: distance_type: Type of distance, see #DistanceTypes
• Parameter: mask_size: Size of the distance transform mask, see #DistanceTransformMasks. #DIST_MASK_PRECISE is not supported by this variant. In case of the #DIST_L1 or #DIST_C distance type, the parameter is forced to 3 because a 3\times 3 mask gives the same result as 5\times 5 or any larger aperture.
• Parameter: label_type: Type of the label array to build, see #DistanceTransformLabelTypes.

Usage: distance_transform2 ?dst ?dst_type src distance_type mask_size

• Parameter: src: 8-bit, single-channel (binary) source image.
• Parameter: dst: Output image with calculated distances. It is a 8-bit or 32-bit floating-point, single-channel image of the same size as src .
• Parameter: distance_type: Type of distance, see #DistanceTypes
• Parameter: mask_size: Size of the distance transform mask, see #DistanceTransformMasks. In case of the #DIST_L1 or #DIST_C distance type, the parameter is forced to 3 because a 3\times 3 mask gives the same result as 5\times 5 or any larger aperture.
• Parameter: dst_type: Type of output image. It can be CV_8U or CV_32F. Type CV_8U can be used only for the first variant of the function and distanceType == #DIST_L1.

Usage: flood_fill ?rect ?lo_diff ?up_diff ?flags image mask seed_point new_val

Fills a connected component with the given color.

The function cv::floodFill fills a connected component starting from the seed point with the specified color. The connectivity is determined by the color/brightness closeness of the neighbor pixels. The pixel at (x,y) is considered to belong to the repainted domain if:

• in case of a grayscale image and floating range \texttt{src} (x',y')- \texttt{loDiff} \leq \texttt{src} (x,y) \leq \texttt{src} (x',y')+ \texttt{upDiff}

• in case of a grayscale image and fixed range \texttt{src} ( \texttt{seedPoint} .x, \texttt{seedPoint} .y)- \texttt{loDiff} \leq \texttt{src} (x,y) \leq \texttt{src} ( \texttt{seedPoint} .x, \texttt{seedPoint} .y)+ \texttt{upDiff}

• in case of a color image and floating range \texttt{src} (x',y')_r- \texttt{loDiff} _r \leq \texttt{src} (x,y)_r \leq \texttt{src} (x',y')_r+ \texttt{upDiff} _r, \texttt{src} (x',y')_g- \texttt{loDiff} _g \leq \texttt{src} (x,y)_g \leq \texttt{src} (x',y')_g+ \texttt{upDiff} _g and \texttt{src} (x',y')_b- \texttt{loDiff} _b \leq \texttt{src} (x,y)_b \leq \texttt{src} (x',y')_b+ \texttt{upDiff} _b

• in case of a color image and fixed range \texttt{src} ( \texttt{seedPoint} .x, \texttt{seedPoint} .y)_r- \texttt{loDiff} _r \leq \texttt{src} (x,y)_r \leq \texttt{src} ( \texttt{seedPoint} .x, \texttt{seedPoint} .y)_r+ \texttt{upDiff} _r, \texttt{src} ( \texttt{seedPoint} .x, \texttt{seedPoint} .y)_g- \texttt{loDiff} _g \leq \texttt{src} (x,y)_g \leq \texttt{src} ( \texttt{seedPoint} .x, \texttt{seedPoint} .y)_g+ \texttt{upDiff} _g and \texttt{src} ( \texttt{seedPoint} .x, \texttt{seedPoint} .y)_b- \texttt{loDiff} _b \leq \texttt{src} (x,y)_b \leq \texttt{src} ( \texttt{seedPoint} .x, \texttt{seedPoint} .y)_b+ \texttt{upDiff} _b

where src(x',y') is the value of one of pixel neighbors that is already known to belong to the component. That is, to be added to the connected component, a color/brightness of the pixel should be close enough to:

• Color/brightness of one of its neighbors that already belong to the connected component in case of a floating range.
• Color/brightness of the seed point in case of a fixed range.

Use these functions to either mark a connected component with the specified color in-place, or build a mask and then extract the contour, or copy the region to another image, and so on.

• Parameter: image: Input/output 1- or 3-channel, 8-bit, or floating-point image. It is modified by the function unless the #FLOODFILL_MASK_ONLY flag is set in the second variant of the function. See the details below.
• Parameter: mask: Operation mask that should be a single-channel 8-bit image, 2 pixels wider and 2 pixels taller than image. Since this is both an input and output parameter, you must take responsibility of initializing it. Flood-filling cannot go across non-zero pixels in the input mask. For example, an edge detector output can be used as a mask to stop filling at edges. On output, pixels in the mask corresponding to filled pixels in the image are set to 1 or to the a value specified in flags as described below. Additionally, the function fills the border of the mask with ones to simplify internal processing. It is therefore possible to use the same mask in multiple calls to the function to make sure the filled areas do not overlap.
• Parameter: seed_point: Starting point.
• Parameter: new_val: New value of the repainted domain pixels.
• Parameter: lo_diff: Maximal lower brightness/color difference between the currently observed pixel and one of its neighbors belonging to the component, or a seed pixel being added to the component.
• Parameter: up_diff: Maximal upper brightness/color difference between the currently observed pixel and one of its neighbors belonging to the component, or a seed pixel being added to the component.
• Parameter: rect: Optional output parameter set by the function to the minimum bounding rectangle of the repainted domain.
• Parameter: flags: Operation flags. The first 8 bits contain a connectivity value. The default value of 4 means that only the four nearest neighbor pixels (those that share an edge) are considered. A connectivity value of 8 means that the eight nearest neighbor pixels (those that share a corner) will be considered. The next 8 bits (8-16) contain a value between 1 and 255 with which to fill the mask (the default value is 1). For example, 4 | ( 255 \<\< 8 ) will consider 4 nearest neighbours and fill the mask with a value of 255. The following additional options occupy higher bits and therefore may be further combined with the connectivity and mask fill values using bit-wise or (|), see #FloodFillFlags.

Note: Since the mask is larger than the filled image, a pixel (x, y) in image corresponds to the pixel (x+1, y+1) in the mask .

See also: findContours

Usage: cvt_color ?dst ?dst_cn src code

Converts an image from one color space to another.

The function converts an input image from one color space to another. In case of a transformation to-from RGB color space, the order of the channels should be specified explicitly (RGB or BGR). Note that the default color format in OpenCV is often referred to as RGB but it is actually BGR (the bytes are reversed). So the first byte in a standard (24-bit) color image will be an 8-bit Blue component, the second byte will be Green, and the third byte will be Red. The fourth, fifth, and sixth bytes would then be the second pixel (Blue, then Green, then Red), and so on.

The conventional ranges for R, G, and B channel values are:

• 0 to 255 for CV_8U images
• 0 to 65535 for CV_16U images
• 0 to 1 for CV_32F images

In case of linear transformations, the range does not matter. But in case of a non-linear transformation, an input RGB image should be normalized to the proper value range to get the correct results, for example, for RGB \rightarrow L\*u\*v\* transformation. For example, if you have a 32-bit floating-point image directly converted from an 8-bit image without any scaling, then it will have the 0..255 value range instead of 0..1 assumed by the function. So, before calling #cvtColor , you need first to scale the image down:

img *= 1./255;
cvtColor(img, img, COLOR_BGR2Luv);

If you use #cvtColor with 8-bit images, the conversion will have some information lost. For many applications, this will not be noticeable but it is recommended to use 32-bit images in applications that need the full range of colors or that convert an image before an operation and then convert back.

If conversion adds the alpha channel, its value will set to the maximum of corresponding channel range: 255 for CV_8U, 65535 for CV_16U, 1 for CV_32F.

• Parameter: src: input image: 8-bit unsigned, 16-bit unsigned ( CV_16UC... ), or single-precision floating-point.
• Parameter: dst: output image of the same size and depth as src.
• Parameter: code: color space conversion code (see #ColorConversionCodes).
• Parameter: dst_cn: number of channels in the destination image; if the parameter is 0, the number of the channels is derived automatically from src and code.

See also imgproc_color_conversions

Usage: cvt_color_two_plane ?dst src1 src2 code

Converts an image from one color space to another where the source image is stored in two planes.

This function only supports YUV420 to RGB conversion as of now.

• Parameter: src1:: 8-bit image (#CV_8U) of the Y plane.
• Parameter: src2:: image containing interleaved U/V plane.
• Parameter: dst:: output image.
• Parameter: code:: Specifies the type of conversion. It can take any of the following values:
• #COLOR_YUV2BGR_NV12
• #COLOR_YUV2RGB_NV12
• #COLOR_YUV2BGRA_NV12
• #COLOR_YUV2RGBA_NV12
• #COLOR_YUV2BGR_NV21
• #COLOR_YUV2RGB_NV21
• #COLOR_YUV2BGRA_NV21
• #COLOR_YUV2RGBA_NV21

Usage: demosaicing ?dst ?dst_cn src code

main function for all demosaicing processes

• Parameter: src: input image: 8-bit unsigned or 16-bit unsigned.
• Parameter: dst: output image of the same size and depth as src.
• Parameter: code: Color space conversion code (see the description below).
• Parameter: dst_cn: number of channels in the destination image; if the parameter is 0, the number of the channels is derived automatically from src and code.

The function can do the following transformations:

• Demosaicing using bilinear interpolation

#COLOR_BayerBG2BGR , #COLOR_BayerGB2BGR , #COLOR_BayerRG2BGR , #COLOR_BayerGR2BGR

#COLOR_BayerBG2GRAY , #COLOR_BayerGB2GRAY , #COLOR_BayerRG2GRAY , #COLOR_BayerGR2GRAY

• Demosaicing using Variable Number of Gradients.

#COLOR_BayerBG2BGR_VNG , #COLOR_BayerGB2BGR_VNG , #COLOR_BayerRG2BGR_VNG , #COLOR_BayerGR2BGR_VNG

• Edge-Aware Demosaicing.

#COLOR_BayerBG2BGR_EA , #COLOR_BayerGB2BGR_EA , #COLOR_BayerRG2BGR_EA , #COLOR_BayerGR2BGR_EA

• Demosaicing with alpha channel

#COLOR_BayerBG2BGRA , #COLOR_BayerGB2BGRA , #COLOR_BayerRG2BGRA , #COLOR_BayerGR2BGRA

See also: cvtColor

Usage: match_template ?result ?mask image templ cv_method

Compares a template against overlapped image regions.

The function slides through image , compares the overlapped patches of size w \times h against templ using the specified method and stores the comparison results in result . #TemplateMatchModes describes the formulae for the available comparison methods ( I denotes image, T template, R result, M the optional mask ). The summation is done over template and/or the image patch: x' = 0...w-1, y' = 0...h-1

After the function finishes the comparison, the best matches can be found as global minimums (when #TM_SQDIFF was used) or maximums (when #TM_CCORR or #TM_CCOEFF was used) using the #minMaxLoc function. In case of a color image, template summation in the numerator and each sum in the denominator is done over all of the channels and separate mean values are used for each channel. That is, the function can take a color template and a color image. The result will still be a single-channel image, which is easier to analyze.

• Parameter: image: Image where the search is running. It must be 8-bit or 32-bit floating-point.
• Parameter: templ: Searched template. It must be not greater than the source image and have the same data type.
• Parameter: result: Map of comparison results. It must be single-channel 32-bit floating-point. If image is W \times H and templ is w \times h , then result is (W-w+1) \times (H-h+1) .
• Parameter: cv_method: Parameter specifying the comparison method, see #TemplateMatchModes
• Parameter: mask: Optional mask. It must have the same size as templ. It must either have the same number of channels as template or only one channel, which is then used for all template and image channels. If the data type is #CV_8U, the mask is interpreted as a binary mask, meaning only elements where mask is nonzero are used and are kept unchanged independent of the actual mask value (weight equals 1). For data tpye #CV_32F, the mask values are used as weights. The exact formulas are documented in #TemplateMatchModes.

Usage: connected_components1 ?labels image connectivity ltype ccltype

computes the connected components labeled image of boolean image

image with 4 or 8 way connectivity - returns N, the total number of labels 0, N-1 where 0 represents the background label. ltype specifies the output label image type, an important consideration based on the total number of labels or alternatively the total number of pixels in the source image. ccltype specifies the connected components labeling algorithm to use, currently Grana (BBDT) and Wu's (SAUF) Wu2009 algorithms are supported, see the #ConnectedComponentsAlgorithmsTypes for details. Note that SAUF algorithm forces a row major ordering of labels while BBDT does not. This function uses parallel version of both Grana and Wu's algorithms if at least one allowed parallel framework is enabled and if the rows of the image are at least twice the number returned by #getNumberOfCPUs.

• Parameter: image: the 8-bit single-channel image to be labeled
• Parameter: labels: destination labeled image
• Parameter: connectivity: 8 or 4 for 8-way or 4-way connectivity respectively
• Parameter: ltype: output image label type. Currently CV_32S and CV_16U are supported.
• Parameter: ccltype: connected components algorithm type (see the #ConnectedComponentsAlgorithmsTypes).

Usage: connected_components2 ?labels ?connectivity ?ltype image

• Parameter: image: the 8-bit single-channel image to be labeled
• Parameter: labels: destination labeled image
• Parameter: connectivity: 8 or 4 for 8-way or 4-way connectivity respectively
• Parameter: ltype: output image label type. Currently CV_32S and CV_16U are supported.

Usage: connected_components_with_stats1 ?labels ?stats ?centroids image connectivity ltype ccltype

computes the connected components labeled image of boolean image and also produces a statistics output for each label

image with 4 or 8 way connectivity - returns N, the total number of labels 0, N-1 where 0 represents the background label. ltype specifies the output label image type, an important consideration based on the total number of labels or alternatively the total number of pixels in the source image. ccltype specifies the connected components labeling algorithm to use, currently Grana's (BBDT) and Wu's (SAUF) Wu2009 algorithms are supported, see the #ConnectedComponentsAlgorithmsTypes for details. Note that SAUF algorithm forces a row major ordering of labels while BBDT does not. This function uses parallel version of both Grana and Wu's algorithms (statistics included) if at least one allowed parallel framework is enabled and if the rows of the image are at least twice the number returned by #getNumberOfCPUs.

• Parameter: image: the 8-bit single-channel image to be labeled
• Parameter: labels: destination labeled image
• Parameter: stats: statistics output for each label, including the background label. Statistics are accessed via stats(label, COLUMN) where COLUMN is one of #ConnectedComponentsTypes, selecting the statistic. The data type is CV_32S.
• Parameter: centroids: centroid output for each label, including the background label. Centroids are accessed via centroids(label, 0) for x and centroids(label, 1) for y. The data type CV_64F.
• Parameter: connectivity: 8 or 4 for 8-way or 4-way connectivity respectively
• Parameter: ltype: output image label type. Currently CV_32S and CV_16U are supported.
• Parameter: ccltype: connected components algorithm type (see #ConnectedComponentsAlgorithmsTypes).

Usage: connected_components_with_stats2 ?labels ?stats ?centroids ?connectivity ?ltype image

• Parameter: image: the 8-bit single-channel image to be labeled
• Parameter: labels: destination labeled image
• Parameter: stats: statistics output for each label, including the background label. Statistics are accessed via stats(label, COLUMN) where COLUMN is one of #ConnectedComponentsTypes, selecting the statistic. The data type is CV_32S.
• Parameter: centroids: centroid output for each label, including the background label. Centroids are accessed via centroids(label, 0) for x and centroids(label, 1) for y. The data type CV_64F.
• Parameter: connectivity: 8 or 4 for 8-way or 4-way connectivity respectively
• Parameter: ltype: output image label type. Currently CV_32S and CV_16U are supported.

Usage: find_contours ?contours ?hierarchy ?offset image mode cv_method

Finds contours in a binary image.

The function retrieves contours from the binary image using the algorithm Suzuki85 . The contours are a useful tool for shape analysis and object detection and recognition. See squares.cpp in the OpenCV sample directory. Note: Since opencv 3.2 source image is not modified by this function.

• Parameter: image: Source, an 8-bit single-channel image. Non-zero pixels are treated as 1's. Zero pixels remain 0's, so the image is treated as binary . You can use #compare, #inRange, #threshold , #adaptiveThreshold, #Canny, and others to create a binary image out of a grayscale or color one. If mode equals to #RETR_CCOMP or #RETR_FLOODFILL, the input can also be a 32-bit integer image of labels (CV_32SC1).
• Parameter: contours: Detected contours. Each contour is stored as a vector of points (e.g. std::vector<std::vector<cv::Point> >).
• Parameter: hierarchy: Optional output vector (e.g. std::vector<cv::Vec4i>), containing information about the image topology. It has as many elements as the number of contours. For each i-th contour contoursi, the elements hierarchyi0 , hierarchyi1 , hierarchyi2 , and hierarchyi3 are set to 0-based indices in contours of the next and previous contours at the same hierarchical level, the first child contour and the parent contour, respectively. If for the contour i there are no next, previous, parent, or nested contours, the corresponding elements of hierarchyi will be negative.
• Parameter: mode: Contour retrieval mode, see #RetrievalModes
• Parameter: cv_method: Contour approximation method, see #ContourApproximationModes
• Parameter: offset: Optional offset by which every contour point is shifted. This is useful if the contours are extracted from the image ROI and then they should be analyzed in the whole image context.

Usage: approx_poly_dp ?approx_curve curve epsilon closed

Approximates a polygonal curve(s) with the specified precision.

The function cv::approxPolyDP approximates a curve or a polygon with another curve/polygon with less vertices so that the distance between them is less or equal to the specified precision. It uses the Douglas-Peucker algorithm <http://en.wikipedia.org/wiki/Ramer-Douglas-Peucker_algorithm>

• Parameter: curve: Input vector of a 2D point stored in std::vector or Mat
• Parameter: approx_curve: Result of the approximation. The type should match the type of the input curve.
• Parameter: epsilon: Parameter specifying the approximation accuracy. This is the maximum distance between the original curve and its approximation.
• Parameter: closed: If true, the approximated curve is closed (its first and last vertices are connected). Otherwise, it is not closed.

Usage: arc_length curve closed

Calculates a contour perimeter or a curve length.

The function computes a curve length or a closed contour perimeter.

• Parameter: curve: Input vector of 2D points, stored in std::vector or Mat.
• Parameter: closed: Flag indicating whether the curve is closed or not.

Usage: bounding_rect array

Calculates the up-right bounding rectangle of a point set or non-zero pixels of gray-scale image.

The function calculates and returns the minimal up-right bounding rectangle for the specified point set or non-zero pixels of gray-scale image.

• Parameter: array: Input gray-scale image or 2D point set, stored in std::vector or Mat.

Usage: contour_area ?oriented contour

Calculates a contour area.

The function computes a contour area. Similarly to moments , the area is computed using the Green formula. Thus, the returned area and the number of non-zero pixels, if you draw the contour using #drawContours or #fillPoly , can be different. Also, the function will most certainly give a wrong results for contours with self-intersections.

Example:

vector<Point> contour;
contour.push_back(Point2f(0, 0));
contour.push_back(Point2f(10, 0));
contour.push_back(Point2f(10, 10));
contour.push_back(Point2f(5, 4));

double area0 = contourArea(contour);
vector<Point> approx;
approxPolyDP(contour, approx, 5, true);
double area1 = contourArea(approx);

cout << "area0 =" << area0 << endl <<
        "area1 =" << area1 << endl <<
        "approx poly vertices" << approx.size() << endl;

• Parameter: contour: Input vector of 2D points (contour vertices), stored in std::vector or Mat.
• Parameter: oriented: Oriented area flag. If it is true, the function returns a signed area value, depending on the contour orientation (clockwise or counter-clockwise). Using this feature you can determine orientation of a contour by taking the sign of an area. By default, the parameter is false, which means that the absolute value is returned.

Usage: min_area_rect points

Finds a rotated rectangle of the minimum area enclosing the input 2D point set.

The function calculates and returns the minimum-area bounding rectangle (possibly rotated) for a specified point set. Developer should keep in mind that the returned RotatedRect can contain negative indices when data is close to the containing Mat element boundary.

• Parameter: points: Input vector of 2D points, stored in std::vector\<\> or Mat

Usage: box_points ?points box

Finds the four vertices of a rotated rect. Useful to draw the rotated rectangle.

The function finds the four vertices of a rotated rectangle. This function is useful to draw the rectangle. In C++, instead of using this function, you can directly use RotatedRect::points method. Please visit the tutorial_bounding_rotated_ellipses "tutorial on Creating Bounding rotated boxes and ellipses for contours" for more information.

• Parameter: box: The input rotated rectangle. It may be the output of
• Parameter: points: The output array of four vertices of rectangles.

Usage: min_enclosing_circle points center radius

Finds a circle of the minimum area enclosing a 2D point set.

The function finds the minimal enclosing circle of a 2D point set using an iterative algorithm.

• Parameter: points: Input vector of 2D points, stored in std::vector\<\> or Mat
• Parameter: center: Output center of the circle.
• Parameter: radius: Output radius of the circle.

Usage: min_enclosing_triangle ?triangle points

Finds a triangle of minimum area enclosing a 2D point set and returns its area.

The function finds a triangle of minimum area enclosing the given set of 2D points and returns its area. The output for a given 2D point set is shown in the image below. 2D points are depicted in *red* and the enclosing triangle in *yellow*.

!Sample output of the minimum enclosing triangle function(pics/minenclosingtriangle.png)

The implementation of the algorithm is based on O'Rourke's ORourke86 and Klee and Laskowski's KleeLaskowski85 papers. O'Rourke provides a \theta(n) algorithm for finding the minimal enclosing triangle of a 2D convex polygon with n vertices. Since the #minEnclosingTriangle function takes a 2D point set as input an additional preprocessing step of computing the convex hull of the 2D point set is required. The complexity of the #convexHull function is O(n log(n)) which is higher than \theta(n) . Thus the overall complexity of the function is O(n log(n)) .

• Parameter: points: Input vector of 2D points with depth CV_32S or CV_32F, stored in std::vector\<\> or Mat
• Parameter: triangle: Output vector of three 2D points defining the vertices of the triangle. The depth of the OutputArray must be CV_32F.

Usage: match_shapes contour1 contour2 cv_method parameter

Compares two shapes.

The function compares two shapes. All three implemented methods use the Hu invariants (see #HuMoments)

• Parameter: contour1: First contour or grayscale image.
• Parameter: contour2: Second contour or grayscale image.
• Parameter: cv_method: Comparison method, see #ShapeMatchModes
• Parameter: parameter: Method-specific parameter (not supported now).

Usage: convex_hull ?hull ?clockwise ?return_points points

Finds the convex hull of a point set.

The function cv::convexHull finds the convex hull of a 2D point set using the Sklansky's algorithm Sklansky82 that has *O(N logN)* complexity in the current implementation.

• Parameter: points: Input 2D point set, stored in std::vector or Mat.
• Parameter: hull: Output convex hull. It is either an integer vector of indices or vector of points. In the first case, the hull elements are 0-based indices of the convex hull points in the original array (since the set of convex hull points is a subset of the original point set). In the second case, hull elements are the convex hull points themselves.
• Parameter: clockwise: Orientation flag. If it is true, the output convex hull is oriented clockwise. Otherwise, it is oriented counter-clockwise. The assumed coordinate system has its X axis pointing to the right, and its Y axis pointing upwards.
• Parameter: return_points: Operation flag. In case of a matrix, when the flag is true, the function returns convex hull points. Otherwise, it returns indices of the convex hull points. When the output array is std::vector, the flag is ignored, and the output depends on the type of the vector: std::vector\<int\> implies returnPoints=false, std::vector\<Point\> implies returnPoints=true.

Note: points and hull should be different arrays, inplace processing isn't supported.

Check tutorial_hull "the corresponding tutorial" for more details.

useful links:

https://www.learnopencv.com/convex-hull-using-opencv-in-python-and-c/

Usage: convexity_defects ?convexity_defects contour convexhull

Finds the convexity defects of a contour.

The figure below displays convexity defects of a hand contour:

!image(pics/defects.png)

• Parameter: contour: Input contour.
• Parameter: convexhull: Convex hull obtained using convexHull that should contain indices of the contour points that make the hull.
• Parameter: convexity_defects: The output vector of convexity defects. In C++ and the new Python/Java interface each convexity defect is represented as 4-element integer vector (a.k.a. #Vec4i): (start_index, end_index, farthest_pt_index, fixpt_depth), where indices are 0-based indices in the original contour of the convexity defect beginning, end and the farthest point, and fixpt_depth is fixed-point approximation (with 8 fractional bits) of the distance between the farthest contour point and the hull. That is, to get the floating-point value of the depth will be fixpt_depth/256.0.

Usage: is_contour_convex contour

Tests a contour convexity.

The function tests whether the input contour is convex or not. The contour must be simple, that is, without self-intersections. Otherwise, the function output is undefined.

• Parameter: contour: Input vector of 2D points, stored in std::vector\<\> or Mat

Usage: intersect_convex_convex ?_p12 ?handle_nested _p1 _p2

Finds intersection of two convex polygons

• Parameter: _p1: First polygon
• Parameter: _p2: Second polygon
• Parameter: _p12: Output polygon describing the intersecting area
• Parameter: handle_nested: When true, an intersection is found if one of the polygons is fully enclosed in the other. When false, no intersection is found. If the polygons share a side or the vertex of one polygon lies on an edge of the other, they are not considered nested and an intersection will be found regardless of the value of handleNested.

• Returns: Absolute value of area of intersecting polygon

Note: intersectConvexConvex doesn't confirm that both polygons are convex and will return invalid results if they aren't.

Usage: fit_ellipse points

Fits an ellipse around a set of 2D points.

The function calculates the ellipse that fits (in a least-squares sense) a set of 2D points best of all. It returns the rotated rectangle in which the ellipse is inscribed. The first algorithm described by Fitzgibbon95 is used. Developer should keep in mind that it is possible that the returned ellipse/rotatedRect data contains negative indices, due to the data points being close to the border of the containing Mat element.

• Parameter: points: Input 2D point set, stored in std::vector\<\> or Mat

Usage: fit_ellipse_ams points

Fits an ellipse around a set of 2D points.

The function calculates the ellipse that fits a set of 2D points. It returns the rotated rectangle in which the ellipse is inscribed. The Approximate Mean Square (AMS) proposed by Taubin1991 is used.

For an ellipse, this basis set is \chi= \left(x^2, x y, y^2, x, y, 1\right) , which is a set of six free coefficients A^T=\left\{A_{\text{xx}},A_{\text{xy}},A_{\text{yy}},A_x,A_y,A_0\right\} . However, to specify an ellipse, all that is needed is five numbers; the major and minor axes lengths (a,b) , the position (x_0,y_0) , and the orientation \theta . This is because the basis set includes lines, quadratics, parabolic and hyperbolic functions as well as elliptical functions as possible fits. If the fit is found to be a parabolic or hyperbolic function then the standard #fitEllipse method is used. The AMS method restricts the fit to parabolic, hyperbolic and elliptical curves by imposing the condition that A^T ( D_x^T D_x + D_y^T D_y) A = 1 where the matrices Dx and Dy are the partial derivatives of the design matrix D with respect to x and y. The matrices are formed row by row applying the following to each of the points in the set: )&=\left\{x_i^2, x_i y_i, y_i^2, x_i, y_i, 1\right\} & D_x(i,:)&=\left\{2 x_i,y_i,0,1,0,0\right\} & D_y(i,:)&=\left\{0,x_i,2 y_i,0,1,0\right\} The AMS method minimizes the cost function { \epsilon ^2=\frac{ A^T D^T D A }{ A^T (D_x^T D_x + D_y^T D_y) A^T }

The minimum cost is found by solving the generalized eigenvalue problem.

{ D^T D A = \lambda \left( D_x^T D_x + D_y^T D_y\right) A

• Parameter: points: Input 2D point set, stored in std::vector\<\> or Mat

Usage: fit_ellipse_direct points

Fits an ellipse around a set of 2D points.

The function calculates the ellipse that fits a set of 2D points. It returns the rotated rectangle in which the ellipse is inscribed. The Direct least square (Direct) method by Fitzgibbon1999 is used.

For an ellipse, this basis set is \chi= \left(x^2, x y, y^2, x, y, 1\right) , which is a set of six free coefficients A^T=\left\{A_{\text{xx}},A_{\text{xy}},A_{\text{yy}},A_x,A_y,A_0\right\} . However, to specify an ellipse, all that is needed is five numbers; the major and minor axes lengths (a,b) , the position (x_0,y_0) , and the orientation \theta . This is because the basis set includes lines, quadratics, parabolic and hyperbolic functions as well as elliptical functions as possible fits. The Direct method confines the fit to ellipses by ensuring that 4 A_{xx} A_{yy}- A_{xy}^2 > 0 . The condition imposed is that 4 A_{xx} A_{yy}- A_{xy}^2=1 which satisfies the inequality and as the coefficients can be arbitrarily scaled is not overly restrictive.

{ \epsilon ^2= A^T D^T D A \quad \text{with} \quad A^T C A =1 \quad \text{and} \quad C=\left(\begin{matrix} 0 & 0 & 2 & 0 & 0 & 0 \\ 0 & -1 & 0 & 0 & 0 & 0 \\ 2 & 0 & 0 & 0 & 0 & 0 \\ 0 & 0 & 0 & 0 & 0 & 0 \\ 0 & 0 & 0 & 0 & 0 & 0 \\ 0 & 0 & 0 & 0 & 0 & 0 \end{matrix} \right)

The minimum cost is found by solving the generalized eigenvalue problem.

{ D^T D A = \lambda \left( C\right) A

The system produces only one positive eigenvalue \lambda which is chosen as the solution with its eigenvector \mathbf{u} . These are used to find the coefficients

{ A = \sqrt{\frac{1}{\mathbf{u}^T C \mathbf{u}}} \mathbf{u} The scaling factor guarantees that A^T C A =1 .

• Parameter: points: Input 2D point set, stored in std::vector\<\> or Mat

Usage: fit_line ?line points dist_type param reps aeps

Fits a line to a 2D or 3D point set.

The function fitLine fits a line to a 2D or 3D point set by minimizing \sum_i \rho(r_i) where r_i is a distance between the i^{th} point, the line and \rho(r) is a distance function, one of the following:

• DIST_L2 \rho (r) = r^2/2 \quad \text{(the simplest and the fastest least-squares method)}
• DIST_L1 \rho (r) = r
• DIST_L12 \rho (r) = 2 \cdot ( \sqrt{1 + \frac{r^2}{2}} - 1)
• DIST_FAIR \rho \left (r \right ) = C^2 \cdot \left ( \frac{r}{C} - \log{\left(1 + \frac{r}{C}\right)} \right ) \quad \text{where} \quad C=1.3998
• DIST_WELSCH \rho \left (r \right ) = \frac{C^2}{2} \cdot \left ( 1 - \exp{\left(-\left(\frac{r}{C}\right)^2\right)} \right ) \quad \text{where} \quad C=2.9846
• DIST_HUBER \rho (r) = \fork{r^2/2}{if \(r < C\)}{C \cdot (r-C/2)}{otherwise} \quad \text{where} \quad C=1.345

The algorithm is based on the M-estimator ( <http://en.wikipedia.org/wiki/M-estimator> ) technique that iteratively fits the line using the weighted least-squares algorithm. After each iteration the weights w_i are adjusted to be inversely proportional to \rho(r_i) .

• Parameter: points: Input vector of 2D or 3D points, stored in std::vector\<\> or Mat.
• Parameter: line: Output line parameters. In case of 2D fitting, it should be a vector of 4 elements (like Vec4f) - (vx, vy, x0, y0), where (vx, vy) is a normalized vector collinear to the line and (x0, y0) is a point on the line. In case of 3D fitting, it should be a vector of 6 elements (like Vec6f) - (vx, vy, vz, x0, y0, z0), where (vx, vy, vz) is a normalized vector collinear to the line and (x0, y0, z0) is a point on the line.
• Parameter: dist_type: Distance used by the M-estimator, see #DistanceTypes
• Parameter: param: Numerical parameter ( C ) for some types of distances. If it is 0, an optimal value is chosen.
• Parameter: reps: Sufficient accuracy for the radius (distance between the coordinate origin and the line).
• Parameter: aeps: Sufficient accuracy for the angle. 0.01 would be a good default value for reps and aeps.

Usage: point_polygon_test contour pt measure_dist

Performs a point-in-contour test.

The function determines whether the point is inside a contour, outside, or lies on an edge (or coincides with a vertex). It returns positive (inside), negative (outside), or zero (on an edge) value, correspondingly. When measureDist=false , the return value is +1, -1, and 0, respectively. Otherwise, the return value is a signed distance between the point and the nearest contour edge.

See below a sample output of the function where each image pixel is tested against the contour:

!sample output(pics/pointpolygon.png)

• Parameter: contour: Input contour.
• Parameter: pt: Point tested against the contour.
• Parameter: measure_dist: If true, the function estimates the signed distance from the point to the nearest contour edge. Otherwise, the function only checks if the point is inside a contour or not.

Usage: rotated_rectangle_intersection ?intersecting_region rect1 rect2

Finds out if there is any intersection between two rotated rectangles.

If there is then the vertices of the intersecting region are returned as well.

Below are some examples of intersection configurations. The hatched pattern indicates the intersecting region and the red vertices are returned by the function.

!intersection examples(pics/intersection.png)

• Parameter: rect1: First rectangle
• Parameter: rect2: Second rectangle
• Parameter: intersecting_region: The output array of the vertices of the intersecting region. It returns at most 8 vertices. Stored as std::vector\<cv::Point2f\> or cv::Mat as Mx1 of type CV_32FC2.
• Returns: One of #RectanglesIntersectTypes

Usage: apply_color_map1 ?dst src colormap

Applies a GNU Octave/MATLAB equivalent colormap on a given image.

• Parameter: src: The source image, grayscale or colored of type CV_8UC1 or CV_8UC3.
• Parameter: dst: The result is the colormapped source image. Note: Mat::create is called on dst.
• Parameter: colormap: The colormap to apply, see #ColormapTypes

Usage: apply_color_map2 ?dst src user_color

Applies a user colormap on a given image.

• Parameter: src: The source image, grayscale or colored of type CV_8UC1 or CV_8UC3.
• Parameter: dst: The result is the colormapped source image. Note: Mat::create is called on dst.
• Parameter: user_color: The colormap to apply of type CV_8UC1 or CV_8UC3 and size 256

Usage: line ?thickness ?line_type ?shift img pt1 pt2 color

Draws a line segment connecting two points.

The function line draws the line segment between pt1 and pt2 points in the image. The line is clipped by the image boundaries. For non-antialiased lines with integer coordinates, the 8-connected or 4-connected Bresenham algorithm is used. Thick lines are drawn with rounding endings. Antialiased lines are drawn using Gaussian filtering.

• Parameter: img: Image.
• Parameter: pt1: First point of the line segment.
• Parameter: pt2: Second point of the line segment.
• Parameter: color: Line color.
• Parameter: thickness: Line thickness.
• Parameter: line_type: Type of the line. See #LineTypes.
• Parameter: shift: Number of fractional bits in the point coordinates.

Usage: arrowed_line ?thickness ?line_type ?shift ?tip_length img pt1 pt2 color

Draws a arrow segment pointing from the first point to the second one.

The function cv::arrowedLine draws an arrow between pt1 and pt2 points in the image. See also #line.

• Parameter: img: Image.
• Parameter: pt1: The point the arrow starts from.
• Parameter: pt2: The point the arrow points to.
• Parameter: color: Line color.
• Parameter: thickness: Line thickness.
• Parameter: line_type: Type of the line. See #LineTypes
• Parameter: shift: Number of fractional bits in the point coordinates.
• Parameter: tip_length: The length of the arrow tip in relation to the arrow length

Usage: rectangle1 ?thickness ?line_type ?shift img pt1 pt2 color

Draws a simple, thick, or filled up-right rectangle.

The function cv::rectangle draws a rectangle outline or a filled rectangle whose two opposite corners are pt1 and pt2.

• Parameter: img: Image.
• Parameter: pt1: Vertex of the rectangle.
• Parameter: pt2: Vertex of the rectangle opposite to pt1 .
• Parameter: color: Rectangle color or brightness (grayscale image).
• Parameter: thickness: Thickness of lines that make up the rectangle. Negative values, like #FILLED, mean that the function has to draw a filled rectangle.
• Parameter: line_type: Type of the line. See #LineTypes
• Parameter: shift: Number of fractional bits in the point coordinates.

Usage: rectangle2 ?thickness ?line_type ?shift img rect color

use rec parameter as alternative specification of the drawn rectangle: `r.tl() and r.br()-Point(1,1)` are opposite corners

Usage: circle ?thickness ?line_type ?shift img center radius color

Draws a circle.

The function cv::circle draws a simple or filled circle with a given center and radius.

• Parameter: img: Image where the circle is drawn.
• Parameter: center: Center of the circle.
• Parameter: radius: Radius of the circle.
• Parameter: color: Circle color.
• Parameter: thickness: Thickness of the circle outline, if positive. Negative values, like #FILLED, mean that a filled circle is to be drawn.
• Parameter: line_type: Type of the circle boundary. See #LineTypes
• Parameter: shift: Number of fractional bits in the coordinates of the center and in the radius value.

Usage: ellipse1 ?thickness ?line_type ?shift img center axes angle start_angle end_angle color

Draws a simple or thick elliptic arc or fills an ellipse sector.

The function cv::ellipse with more parameters draws an ellipse outline, a filled ellipse, an elliptic arc, or a filled ellipse sector. The drawing code uses general parametric form. A piecewise-linear curve is used to approximate the elliptic arc boundary. If you need more control of the ellipse rendering, you can retrieve the curve using #ellipse2Poly and then render it with #polylines or fill it with #fillPoly. If you use the first variant of the function and want to draw the whole ellipse, not an arc, pass startAngle=0 and endAngle=360. If startAngle is greater than endAngle, they are swapped. The figure below explains the meaning of the parameters to draw the blue arc.

!Parameters of Elliptic Arc(pics/ellipse.svg)

• Parameter: img: Image.
• Parameter: center: Center of the ellipse.
• Parameter: axes: Half of the size of the ellipse main axes.
• Parameter: angle: Ellipse rotation angle in degrees.
• Parameter: start_angle: Starting angle of the elliptic arc in degrees.
• Parameter: end_angle: Ending angle of the elliptic arc in degrees.
• Parameter: color: Ellipse color.
• Parameter: thickness: Thickness of the ellipse arc outline, if positive. Otherwise, this indicates that a filled ellipse sector is to be drawn.
• Parameter: line_type: Type of the ellipse boundary. See #LineTypes
• Parameter: shift: Number of fractional bits in the coordinates of the center and values of axes.

Usage: ellipse2 ?thickness ?line_type img box color

• Parameter: img: Image.
• Parameter: box: Alternative ellipse representation via RotatedRect. This means that the function draws an ellipse inscribed in the rotated rectangle.
• Parameter: color: Ellipse color.
• Parameter: thickness: Thickness of the ellipse arc outline, if positive. Otherwise, this indicates that a filled ellipse sector is to be drawn.
• Parameter: line_type: Type of the ellipse boundary. See #LineTypes

Usage: draw_marker ?marker_type ?marker_size ?thickness ?line_type img position color

Draws a marker on a predefined position in an image.

The function cv::drawMarker draws a marker on a given position in the image. For the moment several marker types are supported, see #MarkerTypes for more information.

• Parameter: img: Image.
• Parameter: position: The point where the crosshair is positioned.
• Parameter: color: Line color.
• Parameter: marker_type: The specific type of marker you want to use, see #MarkerTypes
• Parameter: thickness: Line thickness.
• Parameter: line_type: Type of the line, See #LineTypes
• Parameter: marker_size: The length of the marker axis default = 20 pixels

Usage: fill_convex_poly ?line_type ?shift img points color

Fills a convex polygon.

The function cv::fillConvexPoly draws a filled convex polygon. This function is much faster than the function #fillPoly . It can fill not only convex polygons but any monotonic polygon without self-intersections, that is, a polygon whose contour intersects every horizontal line (scan line) twice at the most (though, its top-most and/or the bottom edge could be horizontal).

• Parameter: img: Image.
• Parameter: points: Polygon vertices.
• Parameter: color: Polygon color.
• Parameter: line_type: Type of the polygon boundaries. See #LineTypes
• Parameter: shift: Number of fractional bits in the vertex coordinates.

Usage: fill_poly ?line_type ?shift ?offset img pts color

Fills the area bounded by one or more polygons.

The function cv::fillPoly fills an area bounded by several polygonal contours. The function can fill complex areas, for example, areas with holes, contours with self-intersections (some of their parts), and so forth.

• Parameter: img: Image.
• Parameter: pts: Array of polygons where each polygon is represented as an array of points.
• Parameter: color: Polygon color.
• Parameter: line_type: Type of the polygon boundaries. See #LineTypes
• Parameter: shift: Number of fractional bits in the vertex coordinates.
• Parameter: offset: Optional offset of all points of the contours.

Usage: polylines ?thickness ?line_type ?shift img pts is_closed color

Draws several polygonal curves.

• Parameter: img: Image.
• Parameter: pts: Array of polygonal curves.
• Parameter: is_closed: Flag indicating whether the drawn polylines are closed or not. If they are closed, the function draws a line from the last vertex of each curve to its first vertex.
• Parameter: color: Polyline color.
• Parameter: thickness: Thickness of the polyline edges.
• Parameter: line_type: Type of the line segments. See #LineTypes
• Parameter: shift: Number of fractional bits in the vertex coordinates.

The function cv::polylines draws one or more polygonal curves.

Usage: draw_contours ?thickness ?line_type ?hierarchy ?max_level ?offset image contours contour_idx color

Draws contours outlines or filled contours.

The function draws contour outlines in the image if \texttt{thickness} \ge 0 or fills the area bounded by the contours if \texttt{thickness}<0 . The example below shows how to retrieve connected components from the binary image and label them: : Include: snippets/imgproc_drawContours.cpp

• Parameter: image: Destination image.
• Parameter: contours: All the input contours. Each contour is stored as a point vector.
• Parameter: contour_idx: Parameter indicating a contour to draw. If it is negative, all the contours are drawn.
• Parameter: color: Color of the contours.
• Parameter: thickness: Thickness of lines the contours are drawn with. If it is negative (for example, thickness=#FILLED ), the contour interiors are drawn.
• Parameter: line_type: Line connectivity. See #LineTypes
• Parameter: hierarchy: Optional information about hierarchy. It is only needed if you want to draw only some of the contours (see maxLevel ).
• Parameter: max_level: Maximal level for drawn contours. If it is 0, only the specified contour is drawn. If it is 1, the function draws the contour(s) and all the nested contours. If it is 2, the function draws the contours, all the nested contours, all the nested-to-nested contours, and so on. This parameter is only taken into account when there is hierarchy available.
• Parameter: offset: Optional contour shift parameter. Shift all the drawn contours by the specified \texttt{offset}=(dx,dy) . Note: When thickness=#FILLED, the function is designed to handle connected components with holes correctly even when no hierarchy date is provided. This is done by analyzing all the outlines together using even-odd rule. This may give incorrect results if you have a joint collection of separately retrieved contours. In order to solve this problem, you need to call #drawContours separately for each sub-group of contours, or iterate over the collection using contourIdx parameter.

Usage: clip_line img_rect pt1 pt2

• Parameter: img_rect: Image rectangle.
• Parameter: pt1: First line point.
• Parameter: pt2: Second line point.

Usage: ellipse2_poly center axes angle arc_start arc_end delta pts

Approximates an elliptic arc with a polyline.

The function ellipse2Poly computes the vertices of a polyline that approximates the specified elliptic arc. It is used by #ellipse. If arcStart is greater than arcEnd, they are swapped.

• Parameter: center: Center of the arc.
• Parameter: axes: Half of the size of the ellipse main axes. See #ellipse for details.
• Parameter: angle: Rotation angle of the ellipse in degrees. See #ellipse for details.
• Parameter: arc_start: Starting angle of the elliptic arc in degrees.
• Parameter: arc_end: Ending angle of the elliptic arc in degrees.
• Parameter: delta: Angle between the subsequent polyline vertices. It defines the approximation accuracy.
• Parameter: pts: Output vector of polyline vertices.

Usage: put_text ?thickness ?line_type ?bottom_left_origin img text org font_face font_scale color

Draws a text string.

The function cv::putText renders the specified text string in the image. Symbols that cannot be rendered using the specified font are replaced by question marks. See #getTextSize for a text rendering code example.

• Parameter: img: Image.
• Parameter: text: Text string to be drawn.
• Parameter: org: Bottom-left corner of the text string in the image.
• Parameter: font_face: Font type, see #HersheyFonts.
• Parameter: font_scale: Font scale factor that is multiplied by the font-specific base size.
• Parameter: color: Text color.
• Parameter: thickness: Thickness of the lines used to draw a text.
• Parameter: line_type: Line type. See #LineTypes
• Parameter: bottom_left_origin: When true, the image data origin is at the bottom-left corner. Otherwise, it is at the top-left corner.

Usage: get_text_size text font_face font_scale thickness base_line

Calculates the width and height of a text string.

The function cv::getTextSize calculates and returns the size of a box that contains the specified text. That is, the following code renders some text, the tight box surrounding it, and the baseline: :

String text = "Funny text inside the box";
int fontFace = FONT_HERSHEY_SCRIPT_SIMPLEX;
double fontScale = 2;
int thickness = 3;

Mat img(600, 800, CV_8UC3, Scalar::all(0));

int baseline=0;
Size textSize = getTextSize(text, fontFace,
                            fontScale, thickness, &baseline);
baseline += thickness;

// center the text
Point textOrg((img.cols - textSize.width)/2,
              (img.rows + textSize.height)/2);

// draw the box
rectangle(img, textOrg + Point(0, baseline),
          textOrg + Point(textSize.width, -textSize.height),
          Scalar(0,0,255));
// ... and the baseline first
line(img, textOrg + Point(0, thickness),
     textOrg + Point(textSize.width, thickness),
     Scalar(0, 0, 255));

// then put the text itself
putText(img, text, textOrg, fontFace, fontScale,
        Scalar::all(255), thickness, 8);

• Parameter: text: Input text string.
• Parameter: font_face: Font to use, see #HersheyFonts.
• Parameter: font_scale: Font scale factor that is multiplied by the font-specific base size.
• Parameter: thickness: Thickness of lines used to render the text. See #putText for details.
• Parameter: base_line: y-coordinate of the baseline relative to the bottom-most text point.
• Returns: The size of a box that contains the specified text.

See also putText

Usage: get_font_scale_from_height ?thickness font_face pixel_height

Calculates the font-specific size to use to achieve a given height in pixels.

• Parameter: font_face: Font to use, see cv::HersheyFonts.
• Parameter: pixel_height: Pixel height to compute the fontScale for
• Parameter: thickness: Thickness of lines used to render the text.See putText for details.
• Returns: The fontSize to use for cv::putText

See also cv::putText

Usage: named_window ?flags winname

Creates a window.

The function namedWindow creates a window that can be used as a placeholder for images and trackbars. Created windows are referred to by their names.

If a window with the same name already exists, the function does nothing.

You can call cv::destroyWindow or cv::destroyAllWindows to close the window and de-allocate any associated memory usage. For a simple program, you do not really have to call these functions because all the resources and windows of the application are closed automatically by the operating system upon exit.

Note:

Qt backend supports additional flags:

• **WINDOW_NORMAL or WINDOW_AUTOSIZE:** WINDOW_NORMAL enables you to resize the window, whereas WINDOW_AUTOSIZE adjusts automatically the window size to fit the displayed image (see imshow ), and you cannot change the window size manually.
• **WINDOW_FREERATIO or WINDOW_KEEPRATIO:** WINDOW_FREERATIO adjusts the image with no respect to its ratio, whereas WINDOW_KEEPRATIO keeps the image ratio.
• **WINDOW_GUI_NORMAL or WINDOW_GUI_EXPANDED:** WINDOW_GUI_NORMAL is the old way to draw the window without statusbar and toolbar, whereas WINDOW_GUI_EXPANDED is a new enhanced GUI. By default, flags == WINDOW_AUTOSIZE | WINDOW_KEEPRATIO | WINDOW_GUI_EXPANDED

• Parameter: winname: Name of the window in the window caption that may be used as a window identifier.
• Parameter: flags: Flags of the window. The supported flags are: (cv::WindowFlags)

Usage: destroy_window winname

Destroys the specified window.

The function destroyWindow destroys the window with the given name.

• Parameter: winname: Name of the window to be destroyed.

Usage: destroy_all_windows ()

Destroys all of the HighGUI windows.

The function destroyAllWindows destroys all of the opened HighGUI windows.

Usage: start_window_thread ()

Usage: wait_key_ex ?delay ()

Similar to #waitKey, but returns full key code.

Note:

Key code is implementation specific and depends on used backend: QT/GTK/Win32/etc

Usage: wait_key ?delay ()

Waits for a pressed key.

The function waitKey waits for a key event infinitely (when \texttt{delay}\leq 0 ) or for delay milliseconds, when it is positive. Since the OS has a minimum time between switching threads, the function will not wait exactly delay ms, it will wait at least delay ms, depending on what else is running on your computer at that time. It returns the code of the pressed key or -1 if no key was pressed before the specified time had elapsed.

Note:

This function is the only method in HighGUI that can fetch and handle events, so it needs to be called periodically for normal event processing unless HighGUI is used within an environment that takes care of event processing.

Note:

The function only works if there is at least one HighGUI window created and the window is active. If there are several HighGUI windows, any of them can be active.

• Parameter: delay: Delay in milliseconds. 0 is the special value that means "forever".

Usage: imshow winname mat

Displays an image in the specified window.

The function imshow displays an image in the specified window. If the window was created with the cv::WINDOW_AUTOSIZE flag, the image is shown with its original size, however it is still limited by the screen resolution. Otherwise, the image is scaled to fit the window. The function may scale the image, depending on its depth:

• If the image is 8-bit unsigned, it is displayed as is.
• If the image is 16-bit unsigned or 32-bit integer, the pixels are divided by 256. That is, the value range 0,255\*256 is mapped to 0,255.
• If the image is 32-bit or 64-bit floating-point, the pixel values are multiplied by 255. That is, the value range 0,1 is mapped to 0,255.

If window was created with OpenGL support, cv::imshow also support ogl::Buffer , ogl::Texture2D and cuda::GpuMat as input.

If the window was not created before this function, it is assumed creating a window with cv::WINDOW_AUTOSIZE.

If you need to show an image that is bigger than the screen resolution, you will need to call namedWindow("", WINDOW_NORMAL) before the imshow.

Note: This function should be followed by cv::waitKey function which displays the image for specified milliseconds. Otherwise, it won't display the image. For example, **waitKey(0)** will display the window infinitely until any keypress (it is suitable for image display). **waitKey(25)** will display a frame for 25 ms, after which display will be automatically closed. (If you put it in a loop to read videos, it will display the video frame-by-frame)

Note:

__Windows Backend Only__ Pressing Ctrl+C will copy the image to the clipboard.

__Windows Backend Only__ Pressing Ctrl+S will show a dialog to save the image.

• Parameter: winname: Name of the window.
• Parameter: mat: Image to be shown.

Usage: resize_window1 winname width height

Resizes the window to the specified size

Note:

• The specified window size is for the image area. Toolbars are not counted.
• Only windows created without cv::WINDOW_AUTOSIZE flag can be resized.

• Parameter: winname: Window name.
• Parameter: width: The new window width.
• Parameter: height: The new window height.

Usage: move_window winname x y

Moves the window to the specified position

• Parameter: winname: Name of the window.
• Parameter: x: The new x-coordinate of the window.
• Parameter: y: The new y-coordinate of the window.

Usage: set_window_property winname prop_id prop_value

Changes parameters of a window dynamically.

The function setWindowProperty enables changing properties of a window.

• Parameter: winname: Name of the window.
• Parameter: prop_id: Window property to edit. The supported operation flags are: (cv::WindowPropertyFlags)
• Parameter: prop_value: New value of the window property. The supported flags are: (cv::WindowFlags)

Usage: set_window_title winname title

Updates window title

• Parameter: winname: Name of the window.
• Parameter: title: New title.

Usage: get_window_property winname prop_id

Provides parameters of a window.

The function getWindowProperty returns properties of a window.

• Parameter: winname: Name of the window.
• Parameter: prop_id: Window property to retrieve. The following operation flags are available: (cv::WindowPropertyFlags)

See also: setWindowProperty

Usage: get_window_image_rect winname

Provides rectangle of image in the window.

The function getWindowImageRect returns the client screen coordinates, width and height of the image rendering area.

• Parameter: winname: Name of the window.

See also: resizeWindow moveWindow

Usage: select_roi1 ?show_crosshair ?from_center window_name img

Allows users to select a ROI on the given image.

The function creates a window and allows users to select a ROI using the mouse. Controls: use space or enter to finish selection, use key c to cancel selection (function will return the zero cv::Rect).

• Parameter: window_name: name of the window where selection process will be shown.
• Parameter: img: image to select a ROI.
• Parameter: show_crosshair: if true crosshair of selection rectangle will be shown.
• Parameter: from_center: if true center of selection will match initial mouse position. In opposite case a corner of selection rectangle will correspont to the initial mouse position.
• Returns: selected ROI or empty rect if selection canceled.

Note: The function sets it's own mouse callback for specified window using cv::setMouseCallback(windowName, ...). After finish of work an empty callback will be set for the used window.

Usage: select_roi2 ?show_crosshair ?from_center img

Usage: select_ro_is ?show_crosshair ?from_center window_name img bounding_boxes

Allows users to select multiple ROIs on the given image.

The function creates a window and allows users to select multiple ROIs using the mouse. Controls: use space or enter to finish current selection and start a new one, use esc to terminate multiple ROI selection process.

• Parameter: window_name: name of the window where selection process will be shown.
• Parameter: img: image to select a ROI.
• Parameter: bounding_boxes: selected ROIs.
• Parameter: show_crosshair: if true crosshair of selection rectangle will be shown.
• Parameter: from_center: if true center of selection will match initial mouse position. In opposite case a corner of selection rectangle will correspont to the initial mouse position.

Note: The function sets it's own mouse callback for specified window using cv::setMouseCallback(windowName, ...). After finish of work an empty callback will be set for the used window.

Usage: get_trackbar_pos trackbarname winname

Returns the trackbar position.

The function returns the current position of the specified trackbar.

Note:

__Qt Backend Only__ winname can be empty if the trackbar is attached to the control panel.

• Parameter: trackbarname: Name of the trackbar.
• Parameter: winname: Name of the window that is the parent of the trackbar.

Usage: set_trackbar_pos trackbarname winname pos

Sets the trackbar position.

The function sets the position of the specified trackbar in the specified window.

Note:

__Qt Backend Only__ winname can be empty if the trackbar is attached to the control panel.

• Parameter: trackbarname: Name of the trackbar.
• Parameter: winname: Name of the window that is the parent of trackbar.
• Parameter: pos: New position.

Usage: set_trackbar_max trackbarname winname maxval

Sets the trackbar maximum position.

The function sets the maximum position of the specified trackbar in the specified window.

Note:

__Qt Backend Only__ winname can be empty if the trackbar is attached to the control panel.

• Parameter: trackbarname: Name of the trackbar.
• Parameter: winname: Name of the window that is the parent of trackbar.
• Parameter: maxval: New maximum position.

Usage: set_trackbar_min trackbarname winname minval

Sets the trackbar minimum position.

The function sets the minimum position of the specified trackbar in the specified window.

Note:

__Qt Backend Only__ winname can be empty if the trackbar is attached to the control panel.

• Parameter: trackbarname: Name of the trackbar.
• Parameter: winname: Name of the window that is the parent of trackbar.
• Parameter: minval: New minimum position.

Usage: add_text ?point_size ?color ?weight ?style ?spacing img text org name_font

Draws a text on the image.

• Parameter: img: 8-bit 3-channel image where the text should be drawn.
• Parameter: text: Text to write on an image.
• Parameter: org: Point(x,y) where the text should start on an image.
• Parameter: name_font: Name of the font. The name should match the name of a system font (such as *Times* ). If the font is not found, a default one is used.
• Parameter: point_size: Size of the font. If not specified, equal zero or negative, the point size of the font is set to a system-dependent default value. Generally, this is 12 points.
• Parameter: color: Color of the font in BGRA where A = 255 is fully transparent.
• Parameter: weight: Font weight. Available operation flags are : cv::QtFontWeights You can also specify a positive integer for better control.
• Parameter: style: Font style. Available operation flags are : cv::QtFontStyles
• Parameter: spacing: Spacing between characters. It can be negative or positive.

Usage: display_overlay ?delayms winname text

Displays a text on a window image as an overlay for a specified duration.

The function displayOverlay displays useful information/tips on top of the window for a certain amount of time *delayms*. The function does not modify the image, displayed in the window, that is, after the specified delay the original content of the window is restored.

• Parameter: winname: Name of the window.
• Parameter: text: Overlay text to write on a window image.
• Parameter: delayms: The period (in milliseconds), during which the overlay text is displayed. If this function is called before the previous overlay text timed out, the timer is restarted and the text is updated. If this value is zero, the text never disappears.

Usage: display_status_bar ?delayms winname text

Displays a text on the window statusbar during the specified period of time.

The function displayStatusBar displays useful information/tips on top of the window for a certain amount of time *delayms* . This information is displayed on the window statusbar (the window must be created with the CV_GUI_EXPANDED flags).

• Parameter: winname: Name of the window.
• Parameter: text: Text to write on the window statusbar.
• Parameter: delayms: Duration (in milliseconds) to display the text. If this function is called before the previous text timed out, the timer is restarted and the text is updated. If this value is zero, the text never disappears.

Allows for pure-functional drawing operations by queueing a sequence of operations to be drawn at once on a copy of the source image with draw.