8 Calculates an absolute value of each matrix element.
10 .. ocv:function:: MatExpr abs( const Mat& m )
11 .. ocv:function:: MatExpr abs( const MatExpr& e )
14 :param e: matrix expression.
16 ``abs`` is a meta-function that is expanded to one of :ocv:func:`absdiff` or :ocv:func:`convertScaleAbs` forms:
18 * ``C = abs(A-B)`` is equivalent to ``absdiff(A, B, C)``
20 * ``C = abs(A)`` is equivalent to ``absdiff(A, Scalar::all(0), C)``
22 * ``C = Mat_<Vec<uchar,n> >(abs(A*alpha + beta))`` is equivalent to ``convertScaleAbs(A, C, alpha, beta)``
24 The output matrix has the same size and the same type as the input one except for the last case, where ``C`` is ``depth=CV_8U`` .
26 .. seealso:: :ref:`MatrixExpressions`, :ocv:func:`absdiff`, :ocv:func:`convertScaleAbs`
31 Calculates the per-element absolute difference between two arrays or between an array and a scalar.
33 .. ocv:function:: void absdiff(InputArray src1, InputArray src2, OutputArray dst)
35 .. ocv:pyfunction:: cv2.absdiff(src1, src2[, dst]) -> dst
37 .. ocv:cfunction:: void cvAbsDiff(const CvArr* src1, const CvArr* src2, CvArr* dst)
38 .. ocv:cfunction:: void cvAbsDiffS(const CvArr* src, CvArr* dst, CvScalar value)
39 .. ocv:pyoldfunction:: cv.AbsDiff(src1, src2, dst)-> None
40 .. ocv:pyoldfunction:: cv.AbsDiffS(src, dst, value)-> None
42 :param src1: first input array or a scalar.
44 :param src2: second input array or a scalar.
46 :param src: single input array.
48 :param value: scalar value.
50 :param dst: output array that has the same size and type as input arrays.
52 The function ``absdiff`` calculates:
55 Absolute difference between two arrays when they have the same size and type:
59 \texttt{dst}(I) = \texttt{saturate} (| \texttt{src1}(I) - \texttt{src2}(I)|)
62 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``:
66 \texttt{dst}(I) = \texttt{saturate} (| \texttt{src1}(I) - \texttt{src2} |)
69 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``:
73 \texttt{dst}(I) = \texttt{saturate} (| \texttt{src1} - \texttt{src2}(I) |)
75 where ``I`` is a multi-dimensional index of array elements. In case of multi-channel arrays, each channel is processed independently.
77 .. 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.
79 .. seealso:: :ocv:func:`abs`
85 Calculates the per-element sum of two arrays or an array and a scalar.
87 .. ocv:function:: void add(InputArray src1, InputArray src2, OutputArray dst, InputArray mask=noArray(), int dtype=-1)
89 .. ocv:pyfunction:: cv2.add(src1, src2[, dst[, mask[, dtype]]]) -> dst
91 .. ocv:cfunction:: void cvAdd(const CvArr* src1, const CvArr* src2, CvArr* dst, const CvArr* mask=NULL)
92 .. ocv:cfunction:: void cvAddS(const CvArr* src, CvScalar value, CvArr* dst, const CvArr* mask=NULL)
93 .. ocv:pyoldfunction:: cv.Add(src1, src2, dst, mask=None)-> None
94 .. ocv:pyoldfunction:: cv.AddS(src, value, dst, mask=None)-> None
96 :param src1: first input array or a scalar.
98 :param src2: second input array or a scalar.
100 :param src: single input array.
102 :param value: scalar value.
104 :param 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``.
106 :param mask: optional operation mask - 8-bit single channel array, that specifies elements of the output array to be changed.
108 :param dtype: optional depth of the output array (see the discussion below).
110 The function ``add`` calculates:
113 Sum of two arrays when both input arrays have the same size and the same number of channels:
117 \texttt{dst}(I) = \texttt{saturate} ( \texttt{src1}(I) + \texttt{src2}(I)) \quad \texttt{if mask}(I) \ne0
120 Sum of an array and a scalar when ``src2`` is constructed from ``Scalar`` or has the same number of elements as ``src1.channels()``:
124 \texttt{dst}(I) = \texttt{saturate} ( \texttt{src1}(I) + \texttt{src2} ) \quad \texttt{if mask}(I) \ne0
127 Sum of a scalar and an array when ``src1`` is constructed from ``Scalar`` or has the same number of elements as ``src2.channels()``:
131 \texttt{dst}(I) = \texttt{saturate} ( \texttt{src1} + \texttt{src2}(I) ) \quad \texttt{if mask}(I) \ne0
133 where ``I`` is a multi-dimensional index of array elements. In case of multi-channel arrays, each channel is processed independently.
135 The first function in the list above can be replaced with matrix expressions: ::
138 dst += src1; // equivalent to add(dst, src1, dst);
140 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.
142 .. 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.
146 :ocv:func:`subtract`,
147 :ocv:func:`addWeighted`,
148 :ocv:func:`scaleAdd`,
149 :ocv:func:`Mat::convertTo`,
150 :ref:`MatrixExpressions`
156 Calculates the weighted sum of two arrays.
158 .. ocv:function:: void addWeighted(InputArray src1, double alpha, InputArray src2, double beta, double gamma, OutputArray dst, int dtype=-1)
160 .. ocv:pyfunction:: cv2.addWeighted(src1, alpha, src2, beta, gamma[, dst[, dtype]]) -> dst
162 .. ocv:cfunction:: void cvAddWeighted(const CvArr* src1, double alpha, const CvArr* src2, double beta, double gamma, CvArr* dst)
163 .. ocv:pyoldfunction:: cv.AddWeighted(src1, alpha, src2, beta, gamma, dst)-> None
165 :param src1: first input array.
167 :param alpha: weight of the first array elements.
169 :param src2: second input array of the same size and channel number as ``src1``.
171 :param beta: weight of the second array elements.
173 :param dst: output array that has the same size and number of channels as the input arrays.
175 :param gamma: scalar added to each sum.
177 :param 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()``.
179 The function ``addWeighted`` calculates the weighted sum of two arrays as follows:
183 \texttt{dst} (I)= \texttt{saturate} ( \texttt{src1} (I)* \texttt{alpha} + \texttt{src2} (I)* \texttt{beta} + \texttt{gamma} )
185 where ``I`` is a multi-dimensional index of array elements. In case of multi-channel arrays, each channel is processed independently.
187 The function can be replaced with a matrix expression: ::
189 dst = src1*alpha + src2*beta + gamma;
191 .. 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.
196 :ocv:func:`subtract`,
197 :ocv:func:`scaleAdd`,
198 :ocv:func:`Mat::convertTo`,
199 :ref:`MatrixExpressions`
205 Calculates the per-element bit-wise conjunction of two arrays or an array and a scalar.
207 .. ocv:function:: void bitwise_and(InputArray src1, InputArray src2, OutputArray dst, InputArray mask=noArray())
209 .. ocv:pyfunction:: cv2.bitwise_and(src1, src2[, dst[, mask]]) -> dst
211 .. ocv:cfunction:: void cvAnd(const CvArr* src1, const CvArr* src2, CvArr* dst, const CvArr* mask=NULL)
212 .. ocv:cfunction:: void cvAndS(const CvArr* src, CvScalar value, CvArr* dst, const CvArr* mask=NULL)
213 .. ocv:pyoldfunction:: cv.And(src1, src2, dst, mask=None)-> None
214 .. ocv:pyoldfunction:: cv.AndS(src, value, dst, mask=None)-> None
216 :param src1: first input array or a scalar.
218 :param src2: second input array or a scalar.
220 :param src: single input array.
222 :param value: scalar value.
224 :param dst: output array that has the same size and type as the input arrays.
226 :param mask: optional operation mask, 8-bit single channel array, that specifies elements of the output array to be changed.
228 The function calculates the per-element bit-wise logical conjunction for:
231 Two arrays when ``src1`` and ``src2`` have the same size:
235 \texttt{dst} (I) = \texttt{src1} (I) \wedge \texttt{src2} (I) \quad \texttt{if mask} (I) \ne0
238 An array and a scalar when ``src2`` is constructed from ``Scalar`` or has the same number of elements as ``src1.channels()``:
242 \texttt{dst} (I) = \texttt{src1} (I) \wedge \texttt{src2} \quad \texttt{if mask} (I) \ne0
245 A scalar and an array when ``src1`` is constructed from ``Scalar`` or has the same number of elements as ``src2.channels()``:
249 \texttt{dst} (I) = \texttt{src1} \wedge \texttt{src2} (I) \quad \texttt{if mask} (I) \ne0
252 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.
258 Inverts every bit of an array.
260 .. ocv:function:: void bitwise_not(InputArray src, OutputArray dst, InputArray mask=noArray())
262 .. ocv:pyfunction:: cv2.bitwise_not(src[, dst[, mask]]) -> dst
264 .. ocv:cfunction:: void cvNot(const CvArr* src, CvArr* dst)
265 .. ocv:pyoldfunction:: cv.Not(src, dst)-> None
267 :param src: input array.
269 :param dst: output array that has the same size and type as the input array.
271 :param mask: optional operation mask, 8-bit single channel array, that specifies elements of the output array to be changed.
273 The function calculates per-element bit-wise inversion of the input array:
277 \texttt{dst} (I) = \neg \texttt{src} (I)
279 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.
285 Calculates the per-element bit-wise disjunction of two arrays or an array and a scalar.
287 .. ocv:function:: void bitwise_or(InputArray src1, InputArray src2, OutputArray dst, InputArray mask=noArray())
289 .. ocv:pyfunction:: cv2.bitwise_or(src1, src2[, dst[, mask]]) -> dst
291 .. ocv:cfunction:: void cvOr(const CvArr* src1, const CvArr* src2, CvArr* dst, const CvArr* mask=NULL)
292 .. ocv:cfunction:: void cvOrS(const CvArr* src, CvScalar value, CvArr* dst, const CvArr* mask=NULL)
293 .. ocv:pyoldfunction:: cv.Or(src1, src2, dst, mask=None)-> None
294 .. ocv:pyoldfunction:: cv.OrS(src, value, dst, mask=None)-> None
296 :param src1: first input array or a scalar.
298 :param src2: second input array or a scalar.
300 :param src: single input array.
302 :param value: scalar value.
304 :param dst: output array that has the same size and type as the input arrays.
306 :param mask: optional operation mask, 8-bit single channel array, that specifies elements of the output array to be changed.
308 The function calculates the per-element bit-wise logical disjunction for:
311 Two arrays when ``src1`` and ``src2`` have the same size:
315 \texttt{dst} (I) = \texttt{src1} (I) \vee \texttt{src2} (I) \quad \texttt{if mask} (I) \ne0
318 An array and a scalar when ``src2`` is constructed from ``Scalar`` or has the same number of elements as ``src1.channels()``:
322 \texttt{dst} (I) = \texttt{src1} (I) \vee \texttt{src2} \quad \texttt{if mask} (I) \ne0
325 A scalar and an array when ``src1`` is constructed from ``Scalar`` or has the same number of elements as ``src2.channels()``:
329 \texttt{dst} (I) = \texttt{src1} \vee \texttt{src2} (I) \quad \texttt{if mask} (I) \ne0
332 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.
337 Calculates the per-element bit-wise "exclusive or" operation on two arrays or an array and a scalar.
339 .. ocv:function:: void bitwise_xor(InputArray src1, InputArray src2, OutputArray dst, InputArray mask=noArray())
341 .. ocv:pyfunction:: cv2.bitwise_xor(src1, src2[, dst[, mask]]) -> dst
343 .. ocv:cfunction:: void cvXor(const CvArr* src1, const CvArr* src2, CvArr* dst, const CvArr* mask=NULL)
344 .. ocv:cfunction:: void cvXorS(const CvArr* src, CvScalar value, CvArr* dst, const CvArr* mask=NULL)
345 .. ocv:pyoldfunction:: cv.Xor(src1, src2, dst, mask=None)-> None
346 .. ocv:pyoldfunction:: cv.XorS(src, value, dst, mask=None)-> None
348 :param src1: first input array or a scalar.
350 :param src2: second input array or a scalar.
352 :param src: single input array.
354 :param value: scalar value.
356 :param dst: output array that has the same size and type as the input arrays.
358 :param mask: optional operation mask, 8-bit single channel array, that specifies elements of the output array to be changed.
360 The function calculates the per-element bit-wise logical "exclusive-or" operation for:
363 Two arrays when ``src1`` and ``src2`` have the same size:
367 \texttt{dst} (I) = \texttt{src1} (I) \oplus \texttt{src2} (I) \quad \texttt{if mask} (I) \ne0
370 An array and a scalar when ``src2`` is constructed from ``Scalar`` or has the same number of elements as ``src1.channels()``:
374 \texttt{dst} (I) = \texttt{src1} (I) \oplus \texttt{src2} \quad \texttt{if mask} (I) \ne0
377 A scalar and an array when ``src1`` is constructed from ``Scalar`` or has the same number of elements as ``src2.channels()``:
381 \texttt{dst} (I) = \texttt{src1} \oplus \texttt{src2} (I) \quad \texttt{if mask} (I) \ne0
384 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.
389 Calculates the covariance matrix of a set of vectors.
391 .. ocv:function:: void calcCovarMatrix( const Mat* samples, int nsamples, Mat& covar, Mat& mean, int flags, int ctype=CV_64F)
393 .. ocv:function:: void calcCovarMatrix( InputArray samples, OutputArray covar, OutputArray mean, int flags, int ctype=CV_64F)
395 .. ocv:pyfunction:: cv2.calcCovarMatrix(samples, flags[, covar[, mean[, ctype]]]) -> covar, mean
397 .. ocv:cfunction:: void cvCalcCovarMatrix( const CvArr** vects, int count, CvArr* cov_mat, CvArr* avg, int flags )
399 .. ocv:pyoldfunction:: cv.CalcCovarMatrix(vects, covMat, avg, flags)-> None
401 :param samples: samples stored either as separate matrices or as rows/columns of a single matrix.
403 :param nsamples: number of samples when they are stored separately.
405 :param covar: output covariance matrix of the type ``ctype`` and square size.
407 :param ctype: type of the matrixl; it equals 'CV_64F' by default.
409 :param mean: input or output (depending on the flags) array as the average value of the input vectors.
411 :param vects: a set of vectors.
413 :param flags: operation flags as a combination of the following values:
415 * **CV_COVAR_SCRAMBLED** The output covariance matrix is calculated as:
419 \texttt{scale} \cdot [ \texttt{vects} [0]- \texttt{mean} , \texttt{vects} [1]- \texttt{mean} ,...]^T \cdot [ \texttt{vects} [0]- \texttt{mean} , \texttt{vects} [1]- \texttt{mean} ,...],
421 The covariance matrix will be ``nsamples x nsamples``. Such an unusual covariance matrix is used for fast PCA of a set of very large vectors (see, for example, the EigenFaces technique for face recognition). Eigenvalues of this "scrambled" matrix match the eigenvalues of the true covariance matrix. The "true" eigenvectors can be easily calculated from the eigenvectors of the "scrambled" covariance matrix.
423 * **CV_COVAR_NORMAL** The output covariance matrix is calculated as:
427 \texttt{scale} \cdot [ \texttt{vects} [0]- \texttt{mean} , \texttt{vects} [1]- \texttt{mean} ,...] \cdot [ \texttt{vects} [0]- \texttt{mean} , \texttt{vects} [1]- \texttt{mean} ,...]^T,
429 ``covar`` will be a square matrix of the same size as the total number of elements in each input vector. One and only one of ``CV_COVAR_SCRAMBLED`` and ``CV_COVAR_NORMAL`` must be specified.
431 * **CV_COVAR_USE_AVG** If the flag is specified, the function does not calculate ``mean`` from the input vectors but, instead, uses the passed ``mean`` vector. This is useful if ``mean`` has been pre-calculated or known in advance, or if the covariance matrix is calculated by parts. In this case, ``mean`` is not a mean vector of the input sub-set of vectors but rather the mean vector of the whole set.
433 * **CV_COVAR_SCALE** If the flag is specified, the covariance matrix is scaled. In the "normal" mode, ``scale`` is ``1./nsamples`` . In the "scrambled" mode, ``scale`` is the reciprocal of the total number of elements in each input vector. By default (if the flag is not specified), the covariance matrix is not scaled ( ``scale=1`` ).
435 * **CV_COVAR_ROWS** [Only useful in the second variant of the function] If the flag is specified, all the input vectors are stored as rows of the ``samples`` matrix. ``mean`` should be a single-row vector in this case.
437 * **CV_COVAR_COLS** [Only useful in the second variant of the function] If the flag is specified, all the input vectors are stored as columns of the ``samples`` matrix. ``mean`` should be a single-column vector in this case.
439 The functions ``calcCovarMatrix`` calculate the covariance matrix and, optionally, the mean vector of the set of input vectors.
444 :ocv:func:`mulTransposed`,
445 :ocv:func:`Mahalanobis`
451 Calculates the magnitude and angle of 2D vectors.
453 .. ocv:function:: void cartToPolar(InputArray x, InputArray y, OutputArray magnitude, OutputArray angle, bool angleInDegrees=false)
455 .. ocv:pyfunction:: cv2.cartToPolar(x, y[, magnitude[, angle[, angleInDegrees]]]) -> magnitude, angle
457 .. ocv:cfunction:: void cvCartToPolar( const CvArr* x, const CvArr* y, CvArr* magnitude, CvArr* angle=NULL, int angle_in_degrees=0 )
459 .. ocv:pyoldfunction:: cv.CartToPolar(x, y, magnitude, angle=None, angleInDegrees=0)-> None
461 :param x: array of x-coordinates; this must be a single-precision or double-precision floating-point array.
463 :param y: array of y-coordinates, that must have the same size and same type as ``x``.
465 :param magnitude: output array of magnitudes of the same size and type as ``x``.
467 :param 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).
469 :param angleInDegrees: a flag, indicating whether the angles are measured in radians (which is by default), or in degrees.
471 :param angle_in_degrees: a flag, indicating whether the angles are measured in radians, or in degrees (specific to C syntax).
473 The function ``cartToPolar`` calculates either the magnitude, angle, or both for every 2D vector (x(I),y(I)):
477 \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}
479 The angles are calculated with accuracy about 0.3 degrees. For the point (0,0), the angle is set to 0.
488 Checks every element of an input array for invalid values.
490 .. ocv:function:: bool checkRange( InputArray a, bool quiet=true, Point* pos=0, double minVal=-DBL_MAX, double maxVal=DBL_MAX )
492 .. ocv:pyfunction:: cv2.checkRange(a[, quiet[, minVal[, maxVal]]]) -> retval, pos
494 :param a: input array.
496 :param quiet: a flag, indicating whether the functions quietly return false when the array elements are out of range or they throw an exception.
498 :param pos: optional output parameter, where the position of the first outlier is stored; in the second function ``pos``, when not NULL, must be a pointer to array of ``src.dims`` elements.
500 :param minVal: inclusive lower boundary of valid values range.
502 :param maxVal: exclusive upper boundary of valid values range.
504 The functions ``checkRange`` check that every array element is neither NaN nor
505 infinite. When ``minVal < -DBL_MAX`` and ``maxVal < DBL_MAX``, the functions also check that each value is between ``minVal`` and ``maxVal``. In case of multi-channel arrays, each channel is processed independently.
506 If some values are out of range, position of the first outlier is stored in ``pos`` (when
507 ``pos != NULL``). Then, the functions either return false (when ``quiet=true``) or throw an exception.
513 Performs the per-element comparison of two arrays or an array and scalar value.
515 .. ocv:function:: void compare(InputArray src1, InputArray src2, OutputArray dst, int cmpop)
517 .. ocv:pyfunction:: cv2.compare(src1, src2, cmpop[, dst]) -> dst
519 .. ocv:cfunction:: void cvCmp( const CvArr* src1, const CvArr* src2, CvArr* dst, int cmp_op )
521 .. ocv:pyoldfunction:: cv.Cmp(src1, src2, dst, cmpOp)-> None
523 .. ocv:cfunction:: void cvCmpS( const CvArr* src, double value, CvArr* dst, int cmp_op )
525 .. ocv:pyoldfunction:: cv.CmpS(src, value, dst, cmpOp)-> None
527 :param src1: first input array or a scalar (in the case of ``cvCmp``, ``cv.Cmp``, ``cvCmpS``, ``cv.CmpS`` it is always an array); when it is an array, it must have a single channel.
529 :param src2: second input array or a scalar (in the case of ``cvCmp`` and ``cv.Cmp`` it is always an array; in the case of ``cvCmpS``, ``cv.CmpS`` it is always a scalar); when it is an array, it must have a single channel.
531 :param src: single input array.
533 :param value: scalar value.
535 :param dst: output array that has the same size as the input arrays and type= ``CV_8UC1`` .
537 :param cmpop: a flag, that specifies correspondence between the arrays:
539 * **CMP_EQ** ``src1`` is equal to ``src2``.
540 * **CMP_GT** ``src1`` is greater than ``src2``.
541 * **CMP_GE** ``src1`` is greater than or equal to ``src2``.
542 * **CMP_LT** ``src1`` is less than ``src2``.
543 * **CMP_LE** ``src1`` is less than or equal to ``src2``.
544 * **CMP_NE** ``src1`` is unequal to ``src2``.
546 The function compares:
550 Elements of two arrays when ``src1`` and ``src2`` have the same size:
554 \texttt{dst} (I) = \texttt{src1} (I) \,\texttt{cmpop}\, \texttt{src2} (I)
557 Elements of ``src1`` with a scalar ``src2`` when ``src2`` is constructed from ``Scalar`` or has a single element:
561 \texttt{dst} (I) = \texttt{src1}(I) \,\texttt{cmpop}\, \texttt{src2}
564 ``src1`` with elements of ``src2`` when ``src1`` is constructed from ``Scalar`` or has a single element:
568 \texttt{dst} (I) = \texttt{src1} \,\texttt{cmpop}\, \texttt{src2} (I)
571 When the comparison result is true, the corresponding element of output array is set to 255.
572 The comparison operations can be replaced with the equivalent matrix expressions: ::
574 Mat dst1 = src1 >= src2;
581 :ocv:func:`checkRange`,
584 :ocv:func:`threshold`,
585 :ref:`MatrixExpressions`
591 Copies the lower or the upper half of a square matrix to another half.
593 .. ocv:function:: void completeSymm(InputOutputArray mtx, bool lowerToUpper=false)
595 .. ocv:pyfunction:: cv2.completeSymm(mtx[, lowerToUpper]) -> None
597 :param mtx: input-output floating-point square matrix.
599 :param lowerToUpper: operation flag; if true, the lower half is copied to the upper half. Otherwise, the upper half is copied to the lower half.
601 The function ``completeSymm`` copies the lower half of a square matrix to its another half. The matrix diagonal remains unchanged:
604 :math:`\texttt{mtx}_{ij}=\texttt{mtx}_{ji}` for
605 :math:`i > j` if ``lowerToUpper=false``
608 :math:`\texttt{mtx}_{ij}=\texttt{mtx}_{ji}` for
609 :math:`i < j` if ``lowerToUpper=true``
614 :ocv:func:`transpose`
620 Scales, calculates absolute values, and converts the result to 8-bit.
622 .. ocv:function:: void convertScaleAbs(InputArray src, OutputArray dst, double alpha=1, double beta=0)
624 .. ocv:pyfunction:: cv2.convertScaleAbs(src[, dst[, alpha[, beta]]]) -> dst
626 .. ocv:cfunction:: void cvConvertScaleAbs(const CvArr* src, CvArr* dst, double scale=1, double shift=0)
627 .. ocv:pyoldfunction:: cv.ConvertScaleAbs(src, dst, scale=1.0, shift=0.0)-> None
629 :param src: input array.
631 :param dst: output array.
633 :param alpha: optional scale factor.
635 :param beta: optional delta added to the scaled values.
637 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:
642 \texttt{dst} (I)= \texttt{saturate\_cast<uchar>} (| \texttt{src} (I)* \texttt{alpha} + \texttt{beta} |)
644 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: ::
646 Mat_<float> A(30,30);
647 randu(A, Scalar(-100), Scalar(100));
648 Mat_<float> B = A*5 + 3;
650 // Mat_<float> B = abs(A*5+3) will also do the job,
651 // but it will allocate a temporary matrix
656 :ocv:func:`Mat::convertTo`,
663 Counts non-zero array elements.
665 .. ocv:function:: int countNonZero( InputArray src )
667 .. ocv:pyfunction:: cv2.countNonZero(src) -> retval
669 .. ocv:cfunction:: int cvCountNonZero(const CvArr* arr)
671 .. ocv:pyoldfunction:: cv.CountNonZero(arr)-> int
673 :param src: single-channel array.
675 The function returns the number of non-zero elements in ``src`` :
679 \sum _{I: \; \texttt{src} (I) \ne0 } 1
684 :ocv:func:`meanStdDev`,
686 :ocv:func:`minMaxLoc`,
687 :ocv:func:`calcCovarMatrix`
693 Converts ``CvMat``, ``IplImage`` , or ``CvMatND`` to ``Mat``.
695 .. ocv:function:: Mat cvarrToMat( const CvArr* arr, bool copyData=false, bool allowND=true, int coiMode=0 )
697 :param arr: input ``CvMat``, ``IplImage`` , or ``CvMatND``.
699 :param copyData: when false (default value), no data is copied and only the new header is created, in this case, the original array should not be deallocated while the new matrix header is used; if the parameter is true, all the data is copied and you may deallocate the original array right after the conversion.
701 :param allowND: when true (default value), ``CvMatND`` is converted to 2-dimensional ``Mat``, if it is possible (see the discussion below); if it is not possible, or when the parameter is false, the function will report an error.
703 :param coiMode: parameter specifying how the IplImage COI (when set) is handled.
705 * If ``coiMode=0`` and COI is set, the function reports an error.
707 * If ``coiMode=1`` , the function never reports an error. Instead, it returns the header to the whole original image and you will have to check and process COI manually. See :ocv:func:`extractImageCOI` .
709 The function ``cvarrToMat`` converts ``CvMat``, ``IplImage`` , or ``CvMatND`` header to
710 :ocv:class:`Mat` header, and optionally duplicates the underlying data. The constructed header is returned by the function.
712 When ``copyData=false`` , the conversion is done really fast (in O(1) time) and the newly created matrix header will have ``refcount=0`` , which means that no reference counting is done for the matrix data. In this case, you have to preserve the data until the new header is destructed. Otherwise, when ``copyData=true`` , the new buffer is allocated and managed as if you created a new matrix from scratch and copied the data there. That is, ``cvarrToMat(arr, true)`` is equivalent to ``cvarrToMat(arr, false).clone()`` (assuming that COI is not set). The function provides a uniform way of supporting
713 ``CvArr`` paradigm in the code that is migrated to use new-style data structures internally. The reverse transformation, from
716 ``IplImage`` can be done by a simple assignment: ::
718 CvMat* A = cvCreateMat(10, 10, CV_32F);
720 IplImage A1; cvGetImage(A, &A1);
721 Mat B = cvarrToMat(A);
722 Mat B1 = cvarrToMat(&A1);
725 // now A, A1, B, B1, C and C1 are different headers
726 // for the same 10x10 floating-point array.
727 // note that you will need to use "&"
728 // to pass C & C1 to OpenCV functions, for example:
729 printf("%g\n", cvNorm(&C1, 0, CV_L2));
731 Normally, the function is used to convert an old-style 2D array (
733 ``IplImage`` ) to ``Mat`` . However, the function can also take
734 ``CvMatND`` as an input and create
735 :ocv:func:`Mat` for it, if it is possible. And, for ``CvMatND A`` , it is possible if and only if ``A.dim[i].size*A.dim.step[i] == A.dim.step[i-1]`` for all or for all but one ``i, 0 < i < A.dims`` . That is, the matrix data should be continuous or it should be representable as a sequence of continuous matrices. By using this function in this way, you can process
736 ``CvMatND`` using an arbitrary element-wise function.
738 The last parameter, ``coiMode`` , specifies how to deal with an image with COI set. By default, it is 0 and the function reports an error when an image with COI comes in. And ``coiMode=1`` means that no error is signalled. You have to check COI presence and handle it manually. The modern structures, such as
740 ``MatND`` do not support COI natively. To process an individual channel of a new-style array, you need either to organize a loop over the array (for example, using matrix iterators) where the channel of interest will be processed, or extract the COI using
741 :ocv:func:`mixChannels` (for new-style arrays) or
742 :ocv:func:`extractImageCOI` (for old-style arrays), process this individual channel, and insert it back to the output array if needed (using
743 :ocv:func:`mixChannels` or
744 :ocv:func:`insertImageCOI` , respectively).
748 :ocv:cfunc:`cvGetImage`,
749 :ocv:cfunc:`cvGetMat`,
750 :ocv:func:`extractImageCOI`,
751 :ocv:func:`insertImageCOI`,
752 :ocv:func:`mixChannels`
756 Performs a forward or inverse discrete Cosine transform of 1D or 2D array.
758 .. ocv:function:: void dct(InputArray src, OutputArray dst, int flags=0)
760 .. ocv:pyfunction:: cv2.dct(src[, dst[, flags]]) -> dst
762 .. ocv:cfunction:: void cvDCT(const CvArr* src, CvArr* dst, int flags)
763 .. ocv:pyoldfunction:: cv.DCT(src, dst, flags)-> None
765 :param src: input floating-point array.
767 :param dst: output array of the same size and type as ``src`` .
769 :param flags: transformation flags as a combination of the following values:
771 * **DCT_INVERSE** performs an inverse 1D or 2D transform instead of the default forward transform.
773 * **DCT_ROWS** performs a forward or inverse transform of every individual row of the input matrix. This flag enables you to transform multiple vectors simultaneously and can be used to decrease the overhead (which is sometimes several times larger than the processing itself) to perform 3D and higher-dimensional transforms and so forth.
775 The function ``dct`` performs a forward or inverse discrete Cosine transform (DCT) of a 1D or 2D floating-point array:
778 Forward Cosine transform of a 1D vector of ``N`` elements:
788 C^{(N)}_{jk}= \sqrt{\alpha_j/N} \cos \left ( \frac{\pi(2k+1)j}{2N} \right )
792 :math:`\alpha_0=1`, :math:`\alpha_j=2` for *j > 0*.
795 Inverse Cosine transform of a 1D vector of ``N`` elements:
799 X = \left (C^{(N)} \right )^{-1} \cdot Y = \left (C^{(N)} \right )^T \cdot Y
802 :math:`C^{(N)}` is an orthogonal matrix,
803 :math:`C^{(N)} \cdot \left(C^{(N)}\right)^T = I` )
806 Forward 2D Cosine transform of ``M x N`` matrix:
810 Y = C^{(N)} \cdot X \cdot \left (C^{(N)} \right )^T
813 Inverse 2D Cosine transform of ``M x N`` matrix:
817 X = \left (C^{(N)} \right )^T \cdot X \cdot C^{(N)}
820 The function chooses the mode of operation by looking at the flags and size of the input array:
823 If ``(flags & DCT_INVERSE) == 0`` , the function does a forward 1D or 2D transform. Otherwise, it is an inverse 1D or 2D transform.
826 If ``(flags & DCT_ROWS) != 0`` , the function performs a 1D transform of each row.
829 If the array is a single column or a single row, the function performs a 1D transform.
832 If none of the above is true, the function performs a 2D transform.
836 Currently ``dct`` supports even-size arrays (2, 4, 6 ...). For data analysis and approximation, you can pad the array when necessary.
838 Also, the function performance depends very much, and not monotonically, on the array size (see
839 :ocv:func:`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: ::
841 size_t getOptimalDCTSize(size_t N) { return 2*getOptimalDFTSize((N+1)/2); }
842 N1 = getOptimalDCTSize(N);
844 .. seealso:: :ocv:func:`dft` , :ocv:func:`getOptimalDFTSize` , :ocv:func:`idct`
850 Performs a forward or inverse Discrete Fourier transform of a 1D or 2D floating-point array.
852 .. ocv:function:: void dft(InputArray src, OutputArray dst, int flags=0, int nonzeroRows=0)
854 .. ocv:pyfunction:: cv2.dft(src[, dst[, flags[, nonzeroRows]]]) -> dst
856 .. ocv:cfunction:: void cvDFT( const CvArr* src, CvArr* dst, int flags, int nonzero_rows=0 )
858 .. ocv:pyoldfunction:: cv.DFT(src, dst, flags, nonzeroRows=0)-> None
860 :param src: input array that could be real or complex.
862 :param dst: output array whose size and type depends on the ``flags`` .
864 :param flags: transformation flags, representing a combination of the following values:
866 * **DFT_INVERSE** performs an inverse 1D or 2D transform instead of the default forward transform.
868 * **DFT_SCALE** scales the result: divide it by the number of array elements. Normally, it is combined with ``DFT_INVERSE``.
869 * **DFT_ROWS** performs a forward or inverse transform of every individual row of the input matrix; this flag enables you to transform multiple vectors simultaneously and can be used to decrease the overhead (which is sometimes several times larger than the processing itself) to perform 3D and higher-dimensional transformations and so forth.
871 * **DFT_COMPLEX_OUTPUT** performs a forward transformation of 1D or 2D real array; the result, though being a complex array, has complex-conjugate symmetry (*CCS*, see the function description below for details), and such an array can be packed into a real array of the same size as input, which is the fastest option and which is what the function does by default; however, you may wish to get a full complex array (for simpler spectrum analysis, and so on) - pass the flag to enable the function to produce a full-size complex output array.
873 * **DFT_REAL_OUTPUT** performs an inverse transformation of a 1D or 2D complex array; the result is normally a complex array of the same size, however, if the input array has conjugate-complex symmetry (for example, it is a result of forward transformation with ``DFT_COMPLEX_OUTPUT`` flag), the output is a real array; while the function itself does not check whether the input is symmetrical or not, you can pass the flag and then the function will assume the symmetry and produce the real output array (note that when the input is packed into a real array and inverse transformation is executed, the function treats the input as a packed complex-conjugate symmetrical array, and the output will also be a real array).
875 :param nonzeroRows: 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.
878 The function performs one of the following:
881 Forward the Fourier transform of a 1D vector of ``N`` elements:
888 :math:`F^{(N)}_{jk}=\exp(-2\pi i j k/N)` and
892 Inverse the Fourier transform of a 1D vector of ``N`` elements:
896 \begin{array}{l} X'= \left (F^{(N)} \right )^{-1} \cdot Y = \left (F^{(N)} \right )^* \cdot y \\ X = (1/N) \cdot X, \end{array}
899 :math:`F^*=\left(\textrm{Re}(F^{(N)})-\textrm{Im}(F^{(N)})\right)^T`
902 Forward the 2D Fourier transform of a ``M x N`` matrix:
906 Y = F^{(M)} \cdot X \cdot F^{(N)}
909 Inverse the 2D Fourier transform of a ``M x N`` matrix:
913 \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}
916 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:
920 \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}
922 In case of 1D transform of a real vector, the output looks like the first row of the matrix above.
924 So, the function chooses an operation mode depending on the flags and size of the input array:
926 * 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.
928 * If the input array is real and ``DFT_INVERSE`` is not set, the function performs a forward 1D or 2D transform:
930 * When ``DFT_COMPLEX_OUTPUT`` is set, the output is a complex matrix of the same size as input.
932 * 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 ``DCT_ROWS`` flag), each row of the output matrix looks like the first row of the matrix above.
934 * 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``.
936 * 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``.
938 If ``DFT_SCALE`` is set, the scaling is done after the transformation.
940 Unlike :ocv:func:`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 :ocv:func:`getOptimalDFTSize` method.
942 The sample below illustrates how to calculate a DFT-based convolution of two 2D real arrays: ::
944 void convolveDFT(InputArray A, InputArray B, OutputArray C)
946 // reallocate the output array if needed
947 C.create(abs(A.rows - B.rows)+1, abs(A.cols - B.cols)+1, A.type());
949 // calculate the size of DFT transform
950 dftSize.width = getOptimalDFTSize(A.cols + B.cols - 1);
951 dftSize.height = getOptimalDFTSize(A.rows + B.rows - 1);
953 // allocate temporary buffers and initialize them with 0's
954 Mat tempA(dftSize, A.type(), Scalar::all(0));
955 Mat tempB(dftSize, B.type(), Scalar::all(0));
957 // copy A and B to the top-left corners of tempA and tempB, respectively
958 Mat roiA(tempA, Rect(0,0,A.cols,A.rows));
960 Mat roiB(tempB, Rect(0,0,B.cols,B.rows));
963 // now transform the padded A & B in-place;
964 // use "nonzeroRows" hint for faster processing
965 dft(tempA, tempA, 0, A.rows);
966 dft(tempB, tempB, 0, B.rows);
968 // multiply the spectrums;
969 // the function handles packed spectrum representations well
970 mulSpectrums(tempA, tempB, tempA);
972 // transform the product back from the frequency domain.
973 // Even though all the result rows will be non-zero,
974 // you need only the first C.rows of them, and thus you
975 // pass nonzeroRows == C.rows
976 dft(tempA, tempA, DFT_INVERSE + DFT_SCALE, C.rows);
978 // now copy the result back to C.
979 tempA(Rect(0, 0, C.cols, C.rows)).copyTo(C);
981 // all the temporary buffers will be deallocated automatically
985 To optimize this sample, consider the following approaches:
988 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.
991 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.
994 If different tiles in ``C`` can be calculated in parallel and, thus, the convolution is done by parts, the loop can be threaded.
996 All of the above improvements have been implemented in :ocv:func:`matchTemplate` and :ocv:func:`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 :ocv:func:`flip` .
998 .. seealso:: :ocv:func:`dct` , :ocv:func:`getOptimalDFTSize` , :ocv:func:`mulSpectrums`, :ocv:func:`filter2D` , :ocv:func:`matchTemplate` , :ocv:func:`flip` , :ocv:func:`cartToPolar` , :ocv:func:`magnitude` , :ocv:func:`phase`
1004 Performs per-element division of two arrays or a scalar by an array.
1006 .. ocv:function:: void divide(InputArray src1, InputArray src2, OutputArray dst, double scale=1, int dtype=-1)
1008 .. ocv:function:: void divide(double scale, InputArray src2, OutputArray dst, int dtype=-1)
1010 .. ocv:pyfunction:: cv2.divide(src1, src2[, dst[, scale[, dtype]]]) -> dst
1011 .. ocv:pyfunction:: cv2.divide(scale, src2[, dst[, dtype]]) -> dst
1013 .. ocv:cfunction:: void cvDiv(const CvArr* src1, const CvArr* src2, CvArr* dst, double scale=1)
1014 .. ocv:pyoldfunction:: cv.Div(src1, src2, dst, scale=1) -> None
1016 :param src1: first input array.
1018 :param src2: second input array of the same size and type as ``src1``.
1020 :param scale: scalar factor.
1022 :param dst: output array of the same size and type as ``src2``.
1024 :param 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()``.
1026 The functions ``divide`` divide one array by another:
1030 \texttt{dst(I) = saturate(src1(I)*scale/src2(I))}
1032 or a scalar by an array when there is no ``src1`` :
1036 \texttt{dst(I) = saturate(scale/src2(I))}
1038 When ``src2(I)`` is zero, ``dst(I)`` will also be zero. Different channels of multi-channel arrays are processed independently.
1040 .. 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.
1044 :ocv:func:`multiply`,
1046 :ocv:func:`subtract`,
1047 :ref:`MatrixExpressions`
1053 Returns the determinant of a square floating-point matrix.
1055 .. ocv:function:: double determinant(InputArray mtx)
1057 .. ocv:pyfunction:: cv2.determinant(mtx) -> retval
1059 .. ocv:cfunction:: double cvDet( const CvArr* mat )
1061 .. ocv:pyoldfunction:: cv.Det(mat) -> float
1063 :param mtx: input matrix that must have ``CV_32FC1`` or ``CV_64FC1`` type and square size.
1065 The function ``determinant`` calculates and returns the determinant of the specified matrix. For small matrices ( ``mtx.cols=mtx.rows<=3`` ),
1066 the direct method is used. For larger matrices, the function uses LU factorization with partial pivoting.
1068 For symmetric positively-determined matrices, it is also possible to use :ocv:func:`eigen` decomposition to calculate the determinant.
1076 :ref:`MatrixExpressions`
1082 Calculates eigenvalues and eigenvectors of a symmetric matrix.
1084 .. ocv:function:: bool eigen(InputArray src, OutputArray eigenvalues, int lowindex=-1, int highindex=-1)
1086 .. ocv:function:: bool eigen(InputArray src, OutputArray eigenvalues, OutputArray eigenvectors, int lowindex=-1,int highindex=-1)
1088 .. ocv:pyfunction:: cv2.eigen(src, computeEigenvectors[, eigenvalues[, eigenvectors]]) -> retval, eigenvalues, eigenvectors
1090 .. ocv:cfunction:: void cvEigenVV( CvArr* mat, CvArr* evects, CvArr* evals, double eps=0, int lowindex=-1, int highindex=-1 )
1092 .. ocv:pyoldfunction:: cv.EigenVV(mat, evects, evals, eps, lowindex=-1, highindex=-1)-> None
1094 :param src: input matrix that must have ``CV_32FC1`` or ``CV_64FC1`` type, square size and be symmetrical (``src`` :sup:`T` == ``src``).
1096 :param eigenvalues: output vector of eigenvalues of the same type as ``src``; the eigenvalues are stored in the descending order.
1098 :param 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.
1100 :param lowindex: optional index of largest eigenvalue/-vector to calculate; the parameter is ignored in the current implementation.
1102 :param highindex: optional index of smallest eigenvalue/-vector to calculate; the parameter is ignored in the current implementation.
1104 The functions ``eigen`` calculate just eigenvalues, or eigenvalues and eigenvectors of the symmetric matrix ``src`` : ::
1106 src*eigenvectors.row(i).t() = eigenvalues.at<srcType>(i)*eigenvectors.row(i).t()
1108 .. note:: in the new and the old interfaces different ordering of eigenvalues and eigenvectors parameters is used.
1110 .. seealso:: :ocv:func:`completeSymm` , :ocv:class:`PCA`
1116 Calculates the exponent of every array element.
1118 .. ocv:function:: void exp(InputArray src, OutputArray dst)
1120 .. ocv:pyfunction:: cv2.exp(src[, dst]) -> dst
1122 .. ocv:cfunction:: void cvExp(const CvArr* src, CvArr* dst)
1123 .. ocv:pyoldfunction:: cv.Exp(src, dst)-> None
1125 :param src: input array.
1127 :param dst: output array of the same size and type as ``src``.
1129 The function ``exp`` calculates the exponent of every element of the input array:
1133 \texttt{dst} [I] = e^{ src(I) }
1135 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.
1137 .. seealso:: :ocv:func:`log` , :ocv:func:`cartToPolar` , :ocv:func:`polarToCart` , :ocv:func:`phase` , :ocv:func:`pow` , :ocv:func:`sqrt` , :ocv:func:`magnitude`
1143 Extracts the selected image channel.
1145 .. ocv:function:: void extractImageCOI( const CvArr* arr, OutputArray coiimg, int coi=-1 )
1147 :param arr: input array; it should be a pointer to ``CvMat`` or ``IplImage``.
1149 :param coiimg: output array with a single channel and the same size and depth as ``arr``.
1151 :param coi: if the parameter is ``>=0``, it specifies the channel to extract, if it is ``<0`` and ``arr`` is a pointer to ``IplImage`` with a valid COI set, the selected COI is extracted.
1153 The function ``extractImageCOI`` is used to extract an image COI from an old-style array and put the result to the new-style C++ matrix. As usual, the output matrix is reallocated using ``Mat::create`` if needed.
1155 To extract a channel from a new-style matrix, use
1156 :ocv:func:`mixChannels` or
1159 .. seealso:: :ocv:func:`mixChannels` , :ocv:func:`split` , :ocv:func:`merge` , :ocv:func:`cvarrToMat` , :ocv:cfunc:`cvSetImageCOI` , :ocv:cfunc:`cvGetImageCOI`
1164 Copies the selected image channel from a new-style C++ matrix to the old-style C array.
1166 .. ocv:function:: void insertImageCOI( InputArray coiimg, CvArr* arr, int coi=-1 )
1168 :param coiimg: input array with a single channel and the same size and depth as ``arr``.
1170 :param arr: output array, it should be a pointer to ``CvMat`` or ``IplImage``.
1172 :param coi: if the parameter is ``>=0``, it specifies the channel to insert, if it is ``<0`` and ``arr`` is a pointer to ``IplImage`` with a valid COI set, the selected COI is extracted.
1174 The function ``insertImageCOI`` is used to extract an image COI from a new-style C++ matrix and put the result to the old-style array.
1176 The sample below illustrates how to use the function:
1179 Mat temp(240, 320, CV_8UC1, Scalar(255));
1180 IplImage* img = cvCreateImage(cvSize(320,240), IPL_DEPTH_8U, 3);
1181 insertImageCOI(temp, img, 1); //insert to the first channel
1182 cvNamedWindow("window",1);
1183 cvShowImage("window", img); //you should see green image, because channel number 1 is green (BGR)
1185 cvDestroyAllWindows();
1186 cvReleaseImage(&img);
1188 To insert a channel to a new-style matrix, use
1191 .. seealso:: :ocv:func:`mixChannels` , :ocv:func:`split` , :ocv:func:`merge` , :ocv:func:`cvarrToMat` , :ocv:cfunc:`cvSetImageCOI` , :ocv:cfunc:`cvGetImageCOI`
1196 Flips a 2D array around vertical, horizontal, or both axes.
1198 .. ocv:function:: void flip(InputArray src, OutputArray dst, int flipCode)
1200 .. ocv:pyfunction:: cv2.flip(src, flipCode[, dst]) -> dst
1202 .. ocv:cfunction:: void cvFlip( const CvArr* src, CvArr* dst=NULL, int flip_mode=0 )
1204 .. ocv:pyoldfunction:: cv.Flip(src, dst=None, flipMode=0)-> None
1206 :param src: input array.
1208 :param dst: output array of the same size and type as ``src``.
1210 :param flipCode: 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 the discussion below for the formulas).
1212 The function ``flip`` flips the array in one of three different ways (row and column indices are 0-based):
1216 \texttt{dst} _{ij} =
1219 \texttt{src} _{\texttt{src.rows}-i-1,j} & if\; \texttt{flipCode} = 0 \\
1220 \texttt{src} _{i, \texttt{src.cols} -j-1} & if\; \texttt{flipCode} > 0 \\
1221 \texttt{src} _{ \texttt{src.rows} -i-1, \texttt{src.cols} -j-1} & if\; \texttt{flipCode} < 0 \\
1225 The example scenarios of using the function are the following:
1228 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.
1231 Horizontal flipping of the image with the subsequent horizontal shift and absolute difference calculation to check for a vertical-axis symmetry (``flipCode > 0``).
1234 Simultaneous horizontal and vertical flipping of the image with the subsequent shift and absolute difference calculation to check for a central symmetry (``flipCode < 0``).
1237 Reversing the order of point arrays (``flipCode > 0`` or ``flipCode == 0``).
1239 .. seealso:: :ocv:func:`transpose` , :ocv:func:`repeat` , :ocv:func:`completeSymm`
1245 Performs generalized matrix multiplication.
1247 .. ocv:function:: void gemm( InputArray src1, InputArray src2, double alpha, InputArray src3, double gamma, OutputArray dst, int flags=0 )
1249 .. ocv:pyfunction:: cv2.gemm(src1, src2, alpha, src3, gamma[, dst[, flags]]) -> dst
1251 .. ocv:cfunction:: void cvGEMM( const CvArr* src1, const CvArr* src2, double alpha, const CvArr* src3, double beta, CvArr* dst, int tABC=0)
1252 .. ocv:pyoldfunction:: cv.GEMM(src1, src2, alpha, src3, beta, dst, tABC=0)-> None
1254 :param src1: first multiplied input matrix that should have ``CV_32FC1``, ``CV_64FC1``, ``CV_32FC2``, or ``CV_64FC2`` type.
1256 :param src2: second multiplied input matrix of the same type as ``src1``.
1258 :param alpha: weight of the matrix product.
1260 :param src3: third optional delta matrix added to the matrix product; it should have the same type as ``src1`` and ``src2``.
1262 :param beta: weight of ``src3``.
1264 :param dst: output matrix; it has the proper size and the same type as input matrices.
1266 :param flags: operation flags:
1268 * **GEMM_1_T** transposes ``src1``.
1269 * **GEMM_2_T** transposes ``src2``.
1270 * **GEMM_3_T** transposes ``src3``.
1272 The function 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
1276 \texttt{dst} = \texttt{alpha} \cdot \texttt{src1} ^T \cdot \texttt{src2} + \texttt{beta} \cdot \texttt{src3} ^T
1278 The function can be replaced with a matrix expression. For example, the above call can be replaced with: ::
1280 dst = alpha*src1.t()*src2 + beta*src3.t();
1283 .. seealso:: :ocv:func:`mulTransposed` , :ocv:func:`transform` , :ref:`MatrixExpressions`
1289 Returns a conversion function for a single pixel.
1291 .. ocv:function:: ConvertData getConvertElem(int fromType, int toType)
1293 .. ocv:function:: ConvertScaleData getConvertScaleElem(int fromType, int toType)
1295 :param fromType: input pixel type.
1297 :param toType: output pixel type.
1299 :param from: callback parameter: pointer to the input pixel.
1301 :param to: callback parameter: pointer to the output pixel
1303 :param cn: callback parameter: the number of channels; it can be arbitrary, 1, 100, 100000, etc.
1305 :param alpha: ``ConvertScaleData`` callback optional parameter: the scale factor.
1307 :param beta: ``ConvertScaleData`` callback optional parameter: the delta or offset.
1309 The functions ``getConvertElem`` and ``getConvertScaleElem`` return pointers to the functions for converting individual pixels from one type to another. While the main function purpose is to convert single pixels (actually, for converting sparse matrices from one type to another), you can use them to convert the whole row of a dense matrix or the whole matrix at once, by setting ``cn = matrix.cols*matrix.rows*matrix.channels()`` if the matrix data is continuous.
1311 ``ConvertData`` and ``ConvertScaleData`` are defined as: ::
1313 typedef void (*ConvertData)(const void* from, void* to, int cn)
1314 typedef void (*ConvertScaleData)(const void* from, void* to,
1315 int cn, double alpha, double beta)
1317 .. seealso:: :ocv:func:`Mat::convertTo` , :ocv:func:`SparseMat::convertTo`
1323 Returns the optimal DFT size for a given vector size.
1325 .. ocv:function:: int getOptimalDFTSize(int vecsize)
1327 .. ocv:pyfunction:: cv2.getOptimalDFTSize(vecsize) -> retval
1329 .. ocv:cfunction:: int cvGetOptimalDFTSize(int size0)
1330 .. ocv:pyoldfunction:: cv.GetOptimalDFTSize(size0)-> int
1332 :param vecsize: vector size.
1334 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.
1335 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.
1337 The function ``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 :sup:`p` * 3 :sup:`q` * 5 :sup:`r` for some integer ``p``, ``q``, ``r``.
1339 The function returns a negative number if ``vecsize`` is too large (very close to ``INT_MAX`` ).
1341 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``.
1343 .. seealso:: :ocv:func:`dft` , :ocv:func:`dct` , :ocv:func:`idft` , :ocv:func:`idct` , :ocv:func:`mulSpectrums`
1349 Calculates the inverse Discrete Cosine Transform of a 1D or 2D array.
1351 .. ocv:function:: void idct(InputArray src, OutputArray dst, int flags=0)
1353 .. ocv:pyfunction:: cv2.idct(src[, dst[, flags]]) -> dst
1355 :param src: input floating-point single-channel array.
1357 :param dst: output array of the same size and type as ``src``.
1359 :param flags: operation flags.
1361 ``idct(src, dst, flags)`` is equivalent to ``dct(src, dst, flags | DCT_INVERSE)``.
1368 :ocv:func:`getOptimalDFTSize`
1374 Calculates the inverse Discrete Fourier Transform of a 1D or 2D array.
1376 .. ocv:function:: void idft(InputArray src, OutputArray dst, int flags=0, int nonzeroRows=0)
1378 .. ocv:pyfunction:: cv2.idft(src[, dst[, flags[, nonzeroRows]]]) -> dst
1380 :param src: input floating-point real or complex array.
1382 :param dst: output array whose size and type depend on the ``flags``.
1384 :param flags: operation flags (see :ocv:func:`dft`).
1386 :param nonzeroRows: number of ``dst`` rows to process; the rest of the rows have undefined content (see the convolution sample in :ocv:func:`dft` description.
1388 ``idft(src, dst, flags)`` is equivalent to ``dft(src, dst, flags | DFT_INVERSE)`` .
1390 See :ocv:func:`dft` for details.
1392 .. 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.
1399 :ocv:func:`mulSpectrums`,
1400 :ocv:func:`getOptimalDFTSize`
1406 Checks if array elements lie between the elements of two other arrays.
1408 .. ocv:function:: void inRange(InputArray src, InputArray lowerb, InputArray upperb, OutputArray dst)
1410 .. ocv:pyfunction:: cv2.inRange(src, lowerb, upperb[, dst]) -> dst
1412 .. ocv:cfunction:: void cvInRange(const CvArr* src, const CvArr* lower, const CvArr* upper, CvArr* dst)
1413 .. ocv:cfunction:: void cvInRangeS(const CvArr* src, CvScalar lower, CvScalar upper, CvArr* dst)
1414 .. ocv:pyoldfunction:: cv.InRange(src, lower, upper, dst)-> None
1415 .. ocv:pyoldfunction:: cv.InRangeS(src, lower, upper, dst)-> None
1417 :param src: first input array.
1419 :param lowerb: inclusive lower boundary array or a scalar.
1421 :param upperb: inclusive upper boundary array or a scalar.
1423 :param dst: output array of the same size as ``src`` and ``CV_8U`` type.
1425 The function checks the range as follows:
1427 * For every element of a single-channel input array:
1431 \texttt{dst} (I)= \texttt{lowerb} (I)_0 \leq \texttt{src} (I)_0 \leq \texttt{upperb} (I)_0
1433 * For two-channel arrays:
1437 \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
1441 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.
1443 When the lower and/or upper boundary parameters are scalars, the indexes ``(I)`` at ``lowerb`` and ``upperb`` in the above formulas should be omitted.
1448 Finds the inverse or pseudo-inverse of a matrix.
1450 .. ocv:function:: double invert(InputArray src, OutputArray dst, int flags=DECOMP_LU)
1452 .. ocv:pyfunction:: cv2.invert(src[, dst[, flags]]) -> retval, dst
1454 .. ocv:cfunction:: double cvInvert( const CvArr* src, CvArr* dst, int method=CV_LU )
1456 .. ocv:pyoldfunction:: cv.Invert(src, dst, method=CV_LU) -> float
1458 :param src: input floating-point ``M x N`` matrix.
1460 :param dst: output matrix of ``N x M`` size and the same type as ``src``.
1462 :param flags: inversion method :
1464 * **DECOMP_LU** Gaussian elimination with the optimal pivot element chosen.
1466 * **DECOMP_SVD** singular value decomposition (SVD) method.
1468 * **DECOMP_CHOLESKY** Cholesky decomposition; the matrix must be symmetrical and positively defined.
1470 The function ``invert`` inverts the matrix ``src`` and stores the result in ``dst`` .
1471 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.
1473 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.
1475 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.
1477 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.
1488 Calculates the natural logarithm of every array element.
1490 .. ocv:function:: void log(InputArray src, OutputArray dst)
1492 .. ocv:pyfunction:: cv2.log(src[, dst]) -> dst
1494 .. ocv:cfunction:: void cvLog(const CvArr* src, CvArr* dst)
1495 .. ocv:pyoldfunction:: cv.Log(src, dst)-> None
1497 :param src: input array.
1499 :param dst: output array of the same size and type as ``src`` .
1501 The function ``log`` calculates the natural logarithm of the absolute value of every element of the input array:
1505 \texttt{dst} (I) = \fork{\log |\texttt{src}(I)|}{if $\texttt{src}(I) \ne 0$ }{\texttt{C}}{otherwise}
1507 where ``C`` is a large negative number (about -700 in the current implementation).
1508 The maximum relative error is about ``7e-6`` for single-precision input and less than ``1e-10`` for double-precision input. Special values (NaN, Inf) are not handled.
1513 :ocv:func:`cartToPolar`,
1514 :ocv:func:`polarToCart`,
1518 :ocv:func:`magnitude`
1524 Performs a look-up table transform of an array.
1526 .. ocv:function:: void LUT( InputArray src, InputArray lut, OutputArray dst, int interpolation=0 )
1528 .. ocv:pyfunction:: cv2.LUT(src, lut[, dst[, interpolation]]) -> dst
1530 .. ocv:cfunction:: void cvLUT(const CvArr* src, CvArr* dst, const CvArr* lut)
1531 .. ocv:pyoldfunction:: cv.LUT(src, dst, lut)-> None
1533 :param src: input array of 8-bit elements.
1535 :param 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.
1537 :param dst: output array of the same size and number of channels as ``src``, and the same depth as ``lut``.
1539 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:
1543 \texttt{dst} (I) \leftarrow \texttt{lut(src(I) + d)}
1549 d = \fork{0}{if \texttt{src} has depth \texttt{CV\_8U}}{128}{if \texttt{src} has depth \texttt{CV\_8S}}
1553 :ocv:func:`convertScaleAbs`,
1554 :ocv:func:`Mat::convertTo`
1560 Calculates the magnitude of 2D vectors.
1562 .. ocv:function:: void magnitude(InputArray x, InputArray y, OutputArray magnitude)
1564 .. ocv:pyfunction:: cv2.magnitude(x, y[, magnitude]) -> magnitude
1566 :param x: floating-point array of x-coordinates of the vectors.
1568 :param y: floating-point array of y-coordinates of the vectors; it must have the same size as ``x``.
1570 :param magnitude: output array of the same size and type as ``x``.
1572 The function ``magnitude`` calculates the magnitude of 2D vectors formed from the corresponding elements of ``x`` and ``y`` arrays:
1576 \texttt{dst} (I) = \sqrt{\texttt{x}(I)^2 + \texttt{y}(I)^2}
1580 :ocv:func:`cartToPolar`,
1581 :ocv:func:`polarToCart`,
1589 Calculates the Mahalanobis distance between two vectors.
1591 .. ocv:function:: double Mahalanobis( InputArray v1, InputArray v2, InputArray icovar )
1593 .. ocv:pyfunction:: cv2.Mahalanobis(v1, v2, icovar) -> retval
1595 .. ocv:cfunction:: double cvMahalanobis( const CvArr* vec1, const CvArr* vec2, const CvArr* mat )
1597 .. ocv:pyoldfunction:: cv.Mahalonobis(vec1, vec2, mat) -> None
1599 :param vec1: first 1D input vector.
1601 :param vec2: second 1D input vector.
1603 :param icovar: inverse covariance matrix.
1605 The function ``Mahalanobis`` calculates and returns the weighted distance between two vectors:
1609 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)})} }
1611 The covariance matrix may be calculated using the
1612 :ocv:func:`calcCovarMatrix` function and then inverted using the
1613 :ocv:func:`invert` function (preferably using the ``DECOMP_SVD`` method, as the most accurate).
1619 Calculates per-element maximum of two arrays or an array and a scalar.
1621 .. ocv:function:: MatExpr max( const Mat& a, const Mat& b )
1623 .. ocv:function:: MatExpr max( const Mat& a, double s )
1625 .. ocv:function:: MatExpr max( double s, const Mat& a )
1627 .. ocv:function:: void max(InputArray src1, InputArray src2, OutputArray dst)
1629 .. ocv:function:: void max(const Mat& src1, const Mat& src2, Mat& dst)
1631 .. ocv:function:: void max( const Mat& src1, double src2, Mat& dst )
1633 .. ocv:pyfunction:: cv2.max(src1, src2[, dst]) -> dst
1635 .. ocv:cfunction:: void cvMax(const CvArr* src1, const CvArr* src2, CvArr* dst)
1636 .. ocv:cfunction:: void cvMaxS(const CvArr* src, double value, CvArr* dst)
1637 .. ocv:pyoldfunction:: cv.Max(src1, src2, dst)-> None
1638 .. ocv:pyoldfunction:: cv.MaxS(src, value, dst)-> None
1640 :param src1: first input array.
1642 :param src2: second input array of the same size and type as ``src1`` .
1644 :param value: real scalar value.
1646 :param dst: output array of the same size and type as ``src1``.
1648 The functions ``max`` calculate the per-element maximum of two arrays:
1652 \texttt{dst} (I)= \max ( \texttt{src1} (I), \texttt{src2} (I))
1654 or array and a scalar:
1658 \texttt{dst} (I)= \max ( \texttt{src1} (I), \texttt{value} )
1660 In the second variant, when the input array is multi-channel, each channel is compared with ``value`` independently.
1662 The first 3 variants of the function listed above are actually a part of
1663 :ref:`MatrixExpressions` . They return an expression object that can be further either transformed/ assigned to a matrix, or passed to a function, and so on.
1668 :ocv:func:`compare`,
1669 :ocv:func:`inRange`,
1670 :ocv:func:`minMaxLoc`,
1671 :ref:`MatrixExpressions`
1676 Calculates an average (mean) of array elements.
1678 .. ocv:function:: Scalar mean(InputArray src, InputArray mask=noArray())
1680 .. ocv:pyfunction:: cv2.mean(src[, mask]) -> retval
1682 .. ocv:cfunction:: CvScalar cvAvg( const CvArr* arr, const CvArr* mask=NULL )
1684 .. ocv:pyoldfunction:: cv.Avg(arr, mask=None) -> scalar
1686 :param src: input array that should have from 1 to 4 channels so that the result can be stored in :ocv:class:`Scalar_` .
1688 :param mask: optional operation mask.
1690 The function ``mean`` calculates the mean value ``M`` of array elements, independently for each channel, and return it:
1694 \begin{array}{l} N = \sum _{I: \; \texttt{mask} (I) \ne 0} 1 \\ M_c = \left ( \sum _{I: \; \texttt{mask} (I) \ne 0}{ \texttt{mtx} (I)_c} \right )/N \end{array}
1696 When all the mask elements are 0's, the functions return ``Scalar::all(0)`` .
1700 :ocv:func:`countNonZero`,
1701 :ocv:func:`meanStdDev`,
1703 :ocv:func:`minMaxLoc`
1709 Calculates a mean and standard deviation of array elements.
1711 .. ocv:function:: void meanStdDev(InputArray src, OutputArray mean, OutputArray stddev, InputArray mask=noArray())
1713 .. ocv:pyfunction:: cv2.meanStdDev(src[, mean[, stddev[, mask]]]) -> mean, stddev
1715 .. ocv:cfunction:: void cvAvgSdv( const CvArr* arr, CvScalar* mean, CvScalar* std_dev, const CvArr* mask=NULL )
1717 .. ocv:pyoldfunction:: cv.AvgSdv(arr, mask=None) -> (mean, stdDev)
1719 :param src: input array that should have from 1 to 4 channels so that the results can be stored in :ocv:class:`Scalar_` 's.
1721 :param mean: output parameter: calculated mean value.
1723 :param stddev: output parameter: calculateded standard deviation.
1725 :param mask: optional operation mask.
1727 The function ``meanStdDev`` calculates the mean and the standard deviation ``M`` of array elements independently for each channel and returns it via the output parameters:
1731 \begin{array}{l} N = \sum _{I, \texttt{mask} (I) \ne 0} 1 \\ \texttt{mean} _c = \frac{\sum_{ I: \; \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}
1733 When all the mask elements are 0's, the functions return ``mean=stddev=Scalar::all(0)`` .
1735 .. 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 :ocv:func:`calcCovarMatrix` .
1739 :ocv:func:`countNonZero`,
1742 :ocv:func:`minMaxLoc`,
1743 :ocv:func:`calcCovarMatrix`
1749 Creates one multichannel array out of several single-channel ones.
1751 .. ocv:function:: void merge(const Mat* mv, size_t count, OutputArray dst)
1753 .. ocv:function:: void merge( InputArrayOfArrays mv, OutputArray dst )
1755 .. ocv:pyfunction:: cv2.merge(mv[, dst]) -> dst
1757 .. ocv:cfunction:: void cvMerge(const CvArr* src0, const CvArr* src1, const CvArr* src2, const CvArr* src3, CvArr* dst)
1758 .. ocv:pyoldfunction:: cv.Merge(src0, src1, src2, src3, dst)-> None
1760 :param mv: input array or vector of matrices to be merged; all the matrices in ``mv`` must have the same size and the same depth.
1762 :param count: number of input matrices when ``mv`` is a plain C array; it must be greater than zero.
1764 :param dst: output array of the same size and the same depth as ``mv[0]``; The number of channels will be the total number of channels in the matrix array.
1766 The functions ``merge`` merge several arrays to make a single multi-channel array. That is, each element of the output array will be a concatenation of the elements of the input arrays, where elements of i-th input array are treated as ``mv[i].channels()``-element vectors.
1769 :ocv:func:`split` does the reverse operation. If you need to shuffle channels in some other advanced way, use
1770 :ocv:func:`mixChannels` .
1774 :ocv:func:`mixChannels`,
1776 :ocv:func:`Mat::reshape`
1782 Calculates per-element minimum of two arrays or an array and a scalar.
1784 .. ocv:function:: MatExpr min( const Mat& a, const Mat& b )
1786 .. ocv:function:: MatExpr min( const Mat& a, double s )
1788 .. ocv:function:: MatExpr min( double s, const Mat& a )
1790 .. ocv:function:: void min(InputArray src1, InputArray src2, OutputArray dst)
1792 .. ocv:function:: void min(const Mat& src1, const Mat& src2, Mat& dst)
1794 .. ocv:function:: void min( const Mat& src1, double src2, Mat& dst )
1796 .. ocv:pyfunction:: cv2.min(src1, src2[, dst]) -> dst
1798 .. ocv:cfunction:: void cvMin(const CvArr* src1, const CvArr* src2, CvArr* dst)
1799 .. ocv:cfunction:: void cvMinS(const CvArr* src, double value, CvArr* dst)
1800 .. ocv:pyoldfunction:: cv.Min(src1, src2, dst)-> None
1801 .. ocv:pyoldfunction:: cv.MinS(src, value, dst)-> None
1803 :param src1: first input array.
1805 :param src2: second input array of the same size and type as ``src1``.
1807 :param value: real scalar value.
1809 :param dst: output array of the same size and type as ``src1``.
1811 The functions ``min`` calculate the per-element minimum of two arrays:
1815 \texttt{dst} (I)= \min ( \texttt{src1} (I), \texttt{src2} (I))
1817 or array and a scalar:
1821 \texttt{dst} (I)= \min ( \texttt{src1} (I), \texttt{value} )
1823 In the second variant, when the input array is multi-channel, each channel is compared with ``value`` independently.
1825 The first three variants of the function listed above are actually a part of
1826 :ref:`MatrixExpressions` . They return the expression object that can be further either transformed/assigned to a matrix, or passed to a function, and so on.
1831 :ocv:func:`compare`,
1832 :ocv:func:`inRange`,
1833 :ocv:func:`minMaxLoc`,
1834 :ref:`MatrixExpressions`
1839 Finds the global minimum and maximum in an array
1841 .. ocv:function:: void minMaxIdx(InputArray src, double* minVal, double* maxVal, int* minIdx=0, int* maxIdx=0, InputArray mask=noArray())
1843 :param src: input single-channel array.
1845 :param minVal: pointer to the returned minimum value; ``NULL`` is used if not required.
1847 :param maxVal: pointer to the returned maximum value; ``NULL`` is used if not required.
1849 :param minIdx: pointer to the returned minimum location (in nD case); ``NULL`` is used if not required; Otherwise, it must point to an array of ``src.dims`` elements, the coordinates of the minimum element in each dimension are stored there sequentially.
1853 When ``minIdx`` is not NULL, it must have at least 2 elements (as well as ``maxIdx``), even if ``src`` is a single-row or single-column matrix. In OpenCV (following MATLAB) each array has at least 2 dimensions, i.e. single-column matrix is ``Mx1`` matrix (and therefore ``minIdx``/``maxIdx`` will be ``(i1,0)``/``(i2,0)``) and single-row matrix is ``1xN`` matrix (and therefore ``minIdx``/``maxIdx`` will be ``(0,j1)``/``(0,j2)``).
1855 :param maxIdx: pointer to the returned maximum location (in nD case). ``NULL`` is used if not required.
1857 The function ``minMaxIdx`` 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.
1859 The function does not work with multi-channel arrays. If you need to find minimum or maximum elements across all the channels, use
1860 :ocv:func:`Mat::reshape` first to reinterpret the array as single-channel. Or you may extract the particular channel using either
1861 :ocv:func:`extractImageCOI` , or
1862 :ocv:func:`mixChannels` , or
1865 In case of a sparse matrix, the minimum is found among non-zero elements only.
1871 Finds the global minimum and maximum in an array.
1873 .. ocv:function:: void minMaxLoc(InputArray src, double* minVal, double* maxVal=0, Point* minLoc=0, Point* maxLoc=0, InputArray mask=noArray())
1875 .. ocv:function:: void minMaxLoc( const SparseMat& a, double* minVal, double* maxVal, int* minIdx=0, int* maxIdx=0 )
1877 .. ocv:pyfunction:: cv2.minMaxLoc(src[, mask]) -> minVal, maxVal, minLoc, maxLoc
1879 .. ocv:cfunction:: void cvMinMaxLoc( const CvArr* arr, double* min_val, double* max_val, CvPoint* min_loc=NULL, CvPoint* max_loc=NULL, const CvArr* mask=NULL )
1881 .. ocv:pyoldfunction:: cv.MinMaxLoc(arr, mask=None)-> (minVal, maxVal, minLoc, maxLoc)
1883 :param src: input single-channel array.
1885 :param minVal: pointer to the returned minimum value; ``NULL`` is used if not required.
1887 :param maxVal: pointer to the returned maximum value; ``NULL`` is used if not required.
1889 :param minLoc: pointer to the returned minimum location (in 2D case); ``NULL`` is used if not required.
1891 :param maxLoc: pointer to the returned maximum location (in 2D case); ``NULL`` is used if not required.
1893 :param mask: optional mask used to select a sub-array.
1895 The functions ``minMaxLoc`` find the minimum and maximum element values and their positions. The extremums are searched across the whole array or,
1896 if ``mask`` is not an empty array, in the specified array region.
1898 The functions do not work with multi-channel arrays. If you need to find minimum or maximum elements across all the channels, use
1899 :ocv:func:`Mat::reshape` first to reinterpret the array as single-channel. Or you may extract the particular channel using either
1900 :ocv:func:`extractImageCOI` , or
1901 :ocv:func:`mixChannels` , or
1908 :ocv:func:`compare`,
1909 :ocv:func:`inRange`,
1910 :ocv:func:`extractImageCOI`,
1911 :ocv:func:`mixChannels`,
1913 :ocv:func:`Mat::reshape`
1919 Copies specified channels from input arrays to the specified channels of output arrays.
1921 .. ocv:function:: void mixChannels( const Mat* src, size_t nsrcs, Mat* dst, size_t ndsts, const int* fromTo, size_t npairs )
1923 .. ocv:function:: void mixChannels( const vector<Mat>& src, vector<Mat>& dst, const int* fromTo, size_t npairs )
1925 .. ocv:pyfunction:: cv2.mixChannels(src, dst, fromTo) -> None
1927 .. ocv:cfunction:: void cvMixChannels( const CvArr** src, int src_count, CvArr** dst, int dst_count, const int* from_to, int pair_count )
1929 .. ocv:pyoldfunction:: cv.MixChannels(src, dst, fromTo) -> None
1931 :param src: input array or vector of matricesl; all of the matrices must have the same size and the same depth.
1933 :param nsrcs: number of matrices in ``src``.
1935 :param dst: output array or vector of matrices; all the matrices *must be allocated*; their size and depth must be the same as in ``src[0]``.
1937 :param ndsts: number of matrices in ``dst``.
1939 :param fromTo: array of index pairs specifying which channels are copied and where; ``fromTo[k*2]`` is a 0-based index of the input channel in ``src``, ``fromTo[k*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 ``src[0].channels()-1``, the second input image channels are indexed from ``src[0].channels()`` to ``src[0].channels() + src[1].channels()-1``, and so on, the same scheme is used for the output image channels; as a special case, when ``fromTo[k*2]`` is negative, the corresponding output channel is filled with zero .
1941 :param npairs: number of index pairs in ``fromTo``.
1943 The functions ``mixChannels`` provide an advanced mechanism for shuffling image channels.
1945 :ocv:func:`split` and
1946 :ocv:func:`merge` and some forms of
1947 :ocv:func:`cvtColor` are partial cases of ``mixChannels`` .
1949 In the example below, the code splits a 4-channel RGBA image into a 3-channel BGR (with R and B channels swapped) and a separate alpha-channel image: ::
1951 Mat rgba( 100, 100, CV_8UC4, Scalar(1,2,3,4) );
1952 Mat bgr( rgba.rows, rgba.cols, CV_8UC3 );
1953 Mat alpha( rgba.rows, rgba.cols, CV_8UC1 );
1955 // forming an array of matrices is a quite efficient operation,
1956 // because the matrix data is not copied, only the headers
1957 Mat out[] = { bgr, alpha };
1958 // rgba[0] -> bgr[2], rgba[1] -> bgr[1],
1959 // rgba[2] -> bgr[0], rgba[3] -> alpha[0]
1960 int from_to[] = { 0,2, 1,1, 2,0, 3,3 };
1961 mixChannels( &rgba, 1, out, 2, from_to, 4 );
1964 .. note:: Unlike many other new-style C++ functions in OpenCV (see the introduction section and :ocv:func:`Mat::create` ), ``mixChannels`` requires the output arrays to be pre-allocated before calling the function.
1970 :ocv:func:`cvtColor`
1976 Performs the per-element multiplication of two Fourier spectrums.
1978 .. ocv:function:: void mulSpectrums( InputArray a, InputArray b, OutputArray c, int flags, bool conjB=false )
1980 .. ocv:pyfunction:: cv2.mulSpectrums(a, b, flags[, c[, conjB]]) -> c
1982 .. ocv:cfunction:: void cvMulSpectrums( const CvArr* src1, const CvArr* src2, CvArr* dst, int flags)
1983 .. ocv:pyoldfunction:: cv.MulSpectrums(src1, src2, dst, flags)-> None
1985 :param src1: first input array.
1987 :param src2: second input array of the same size and type as ``src1`` .
1989 :param dst: output array of the same size and type as ``src1`` .
1991 :param flags: operation flags; currently, the only supported flag is ``DFT_ROWS``, which indicates that each row of ``src1`` and ``src2`` is an independent 1D Fourier spectrum.
1993 :param conjB: optional flag that conjugates the second input array before the multiplication (true) or not (false).
1995 The function ``mulSpectrums`` performs the per-element multiplication of the two CCS-packed or complex matrices that are results of a real or complex Fourier transform.
1997 The function, together with
1999 :ocv:func:`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
2000 :ocv:func:`dft` for details).
2006 Calculates the per-element scaled product of two arrays.
2008 .. ocv:function:: void multiply( InputArray src1, InputArray src2, OutputArray dst, double scale=1, int dtype=-1 )
2010 .. ocv:pyfunction:: cv2.multiply(src1, src2[, dst[, scale[, dtype]]]) -> dst
2012 .. ocv:cfunction:: void cvMul(const CvArr* src1, const CvArr* src2, CvArr* dst, double scale=1)
2013 .. ocv:pyoldfunction:: cv.Mul(src1, src2, dst, scale=1) -> None
2015 :param src1: first input array.
2017 :param src2: second input array of the same size and the same type as ``src1``.
2019 :param dst: output array of the same size and type as ``src1``.
2021 :param scale: optional scale factor.
2023 The function ``multiply`` calculates the per-element product of two arrays:
2027 \texttt{dst} (I)= \texttt{saturate} ( \texttt{scale} \cdot \texttt{src1} (I) \cdot \texttt{src2} (I))
2030 :ref:`MatrixExpressions` -friendly variant of the first function. See
2031 :ocv:func:`Mat::mul` .
2033 For a not-per-element matrix product, see
2036 .. 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.
2041 :ocv:func:`subtract`,
2043 :ref:`MatrixExpressions`,
2044 :ocv:func:`scaleAdd`,
2045 :ocv:func:`addWeighted`,
2046 :ocv:func:`accumulate`,
2047 :ocv:func:`accumulateProduct`,
2048 :ocv:func:`accumulateSquare`,
2049 :ocv:func:`Mat::convertTo`
2055 Calculates the product of a matrix and its transposition.
2057 .. ocv:function:: void mulTransposed( InputArray src, OutputArray dst, bool aTa, InputArray delta=noArray(), double scale=1, int dtype=-1 )
2059 .. ocv:pyfunction:: cv2.mulTransposed(src, aTa[, dst[, delta[, scale[, dtype]]]]) -> dst
2061 .. ocv:cfunction:: void cvMulTransposed( const CvArr* src, CvArr* dst, int order, const CvArr* delta=NULL, double scale=1. )
2063 .. ocv:pyoldfunction:: cv.MulTransposed(src, dst, order, delta=None, scale=1.0) -> None
2065 :param src: input single-channel matrix. Note that unlike :ocv:func:`gemm`, the function can multiply not only floating-point matrices.
2067 :param dst: output square matrix.
2069 :param aTa: Flag specifying the multiplication ordering. See the description below.
2071 :param 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 :ocv:func:`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.
2073 :param scale: Optional scale factor for the matrix product.
2075 :param 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`` .
2077 The function ``mulTransposed`` calculates the product of ``src`` and its transposition:
2081 \texttt{dst} = \texttt{scale} ( \texttt{src} - \texttt{delta} )^T ( \texttt{src} - \texttt{delta} )
2083 if ``aTa=true`` , and
2087 \texttt{dst} = \texttt{scale} ( \texttt{src} - \texttt{delta} ) ( \texttt{src} - \texttt{delta} )^T
2089 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'``
2093 :ocv:func:`calcCovarMatrix`,
2102 Calculates an absolute array norm, an absolute difference norm, or a relative difference norm.
2104 .. ocv:function:: double norm(InputArray src1, int normType=NORM_L2, InputArray mask=noArray())
2106 .. ocv:function:: double norm( InputArray src1, InputArray src2, int normType=NORM_L2, InputArray mask=noArray() )
2108 .. ocv:function:: double norm( const SparseMat& src, int normType )
2110 .. ocv:pyfunction:: cv2.norm(src1[, normType[, mask]]) -> retval
2111 .. ocv:pyfunction:: cv2.norm(src1, src2[, normType[, mask]]) -> retval
2113 .. ocv:cfunction:: double cvNorm( const CvArr* arr1, const CvArr* arr2=NULL, int norm_type=CV_L2, const CvArr* mask=NULL )
2115 .. ocv:pyoldfunction:: cv.Norm(arr1, arr2, normType=CV_L2, mask=None) -> float
2117 :param src1: first input array.
2119 :param src2: second input array of the same size and the same type as ``src1``.
2121 :param normType: type of the norm (see the details below).
2123 :param mask: optional operation mask; it must have the same size as ``src1`` and ``CV_8UC1`` type.
2125 The functions ``norm`` calculate an absolute norm of ``src1`` (when there is no ``src2`` ):
2129 norm = \forkthree{\|\texttt{src1}\|_{L_{\infty}} = \max _I | \texttt{src1} (I)|}{if $\texttt{normType} = \texttt{NORM\_INF}$ }
2130 { \| \texttt{src1} \| _{L_1} = \sum _I | \texttt{src1} (I)|}{if $\texttt{normType} = \texttt{NORM\_L1}$ }
2131 { \| \texttt{src1} \| _{L_2} = \sqrt{\sum_I \texttt{src1}(I)^2} }{if $\texttt{normType} = \texttt{NORM\_L2}$ }
2133 or an absolute or relative difference norm if ``src2`` is there:
2137 norm = \forkthree{\|\texttt{src1}-\texttt{src2}\|_{L_{\infty}} = \max _I | \texttt{src1} (I) - \texttt{src2} (I)|}{if $\texttt{normType} = \texttt{NORM\_INF}$ }
2138 { \| \texttt{src1} - \texttt{src2} \| _{L_1} = \sum _I | \texttt{src1} (I) - \texttt{src2} (I)|}{if $\texttt{normType} = \texttt{NORM\_L1}$ }
2139 { \| \texttt{src1} - \texttt{src2} \| _{L_2} = \sqrt{\sum_I (\texttt{src1}(I) - \texttt{src2}(I))^2} }{if $\texttt{normType} = \texttt{NORM\_L2}$ }
2145 norm = \forkthree{\frac{\|\texttt{src1}-\texttt{src2}\|_{L_{\infty}} }{\|\texttt{src2}\|_{L_{\infty}} }}{if $\texttt{normType} = \texttt{NORM\_RELATIVE\_INF}$ }
2146 { \frac{\|\texttt{src1}-\texttt{src2}\|_{L_1} }{\|\texttt{src2}\|_{L_1}} }{if $\texttt{normType} = \texttt{NORM\_RELATIVE\_L1}$ }
2147 { \frac{\|\texttt{src1}-\texttt{src2}\|_{L_2} }{\|\texttt{src2}\|_{L_2}} }{if $\texttt{normType} = \texttt{NORM\_RELATIVE\_L2}$ }
2149 The functions ``norm`` return the calculated norm.
2151 When the ``mask`` parameter is specified and it is not empty, the norm is calculated only over the region specified by the mask.
2153 A multi-channel input arrays are treated as a single-channel, that is, the results for all channels are combined.
2159 Normalizes the norm or value range of an array.
2161 .. ocv:function:: void normalize( InputArray src, OutputArray dst, double alpha=1, double beta=0, int norm_type=NORM_L2, int dtype=-1, InputArray mask=noArray() )
2163 .. ocv:function:: void normalize(const SparseMat& src, SparseMat& dst, double alpha, int normType)
2165 .. ocv:pyfunction:: cv2.normalize(src[, dst[, alpha[, beta[, norm_type[, dtype[, mask]]]]]]) -> dst
2167 :param src: input array.
2169 :param dst: output array of the same size as ``src`` .
2171 :param alpha: norm value to normalize to or the lower range boundary in case of the range normalization.
2173 :param beta: upper range boundary in case of the range normalization; it is not used for the norm normalization.
2175 :param normType: normalization type (see the details below).
2177 :param 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)``.
2179 :param mask: optional operation mask.
2182 The functions ``normalize`` scale and shift the input array elements so that
2186 \| \texttt{dst} \| _{L_p}= \texttt{alpha}
2188 (where p=Inf, 1 or 2) when ``normType=NORM_INF``, ``NORM_L1``, or ``NORM_L2``, respectively; or so that
2192 \min _I \texttt{dst} (I)= \texttt{alpha} , \, \, \max _I \texttt{dst} (I)= \texttt{beta}
2194 when ``normType=NORM_MINMAX`` (for dense arrays only).
2195 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
2196 :ocv:func:`norm` and
2197 :ocv:func:`Mat::convertTo`.
2199 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.
2204 :ocv:func:`Mat::convertTo`,
2205 :ocv:func:`SparseMat::convertTo`
2213 Principal Component Analysis class.
2215 The class is used to calculate a special basis for a set of vectors. The basis will consist of eigenvectors of the covariance matrix calculated from the input set of vectors. The class ``PCA`` can also transform vectors to/from the new coordinate space defined by the basis. Usually, in this new coordinate system, each vector from the original set (and any linear combination of such vectors) can be quite accurately approximated by taking its first few components, corresponding to the eigenvectors of the largest eigenvalues of the covariance matrix. Geometrically it means that you calculate a projection of the vector to a subspace formed by a few eigenvectors corresponding to the dominant eigenvalues of the covariance matrix. And usually such a projection is very close to the original vector. So, you can represent the original vector from a high-dimensional space with a much shorter vector consisting of the projected vector's coordinates in the subspace. Such a transformation is also known as Karhunen-Loeve Transform, or KLT. See
2216 http://en.wikipedia.org/wiki/Principal\_component\_analysis .
2218 The sample below is the function that takes two matrices. The first function stores a set of vectors (a row per vector) that is used to calculate PCA. The second function stores another "test" set of vectors (a row per vector). First, these vectors are compressed with PCA, then reconstructed back, and then the reconstruction error norm is computed and printed for each vector. ::
2220 PCA compressPCA(InputArray pcaset, int maxComponents,
2221 const Mat& testset, OutputArray compressed)
2223 PCA pca(pcaset, // pass the data
2224 Mat(), // there is no pre-computed mean vector,
2225 // so let the PCA engine to compute it
2226 CV_PCA_DATA_AS_ROW, // indicate that the vectors
2227 // are stored as matrix rows
2228 // (use CV_PCA_DATA_AS_COL if the vectors are
2229 // the matrix columns)
2230 maxComponents // specify how many principal components to retain
2232 // if there is no test data, just return the computed basis, ready-to-use
2235 CV_Assert( testset.cols == pcaset.cols );
2237 compressed.create(testset.rows, maxComponents, testset.type());
2240 for( int i = 0; i < testset.rows; i++ )
2242 Mat vec = testset.row(i), coeffs = compressed.row(i);
2243 // compress the vector, the result will be stored
2244 // in the i-th row of the output matrix
2245 pca.project(vec, coeffs);
2246 // and then reconstruct it
2247 pca.backProject(coeffs, reconstructed);
2248 // and measure the error
2249 printf("%d. diff = %g\n", i, norm(vec, reconstructed, NORM_L2));
2257 :ocv:func:`calcCovarMatrix`,
2258 :ocv:func:`mulTransposed`,
2269 .. ocv:function:: PCA::PCA()
2271 .. ocv:function:: PCA::PCA(InputArray data, InputArray mean, int flags, int maxComponents=0)
2273 .. ocv:function:: PCA::PCA(InputArray data, InputArray mean, int flags, double retainedVariance)
2275 :param data: input samples stored as matrix rows or matrix columns.
2277 :param mean: optional mean value; if the matrix is empty (``noArray()``), the mean is computed from the data.
2279 :param flags: operation flags; currently the parameter is only used to specify the data layout:
2281 * **CV_PCA_DATA_AS_ROW** indicates that the input samples are stored as matrix rows.
2283 * **CV_PCA_DATA_AS_COL** indicates that the input samples are stored as matrix columns.
2285 :param maxComponents: maximum number of components that PCA should retain; by default, all the components are retained.
2287 :param retainedVariance: Percentage of variance that PCA should retain. Using this parameter will let the PCA decided how many components to retain but it will always keep at least 2.
2289 The default constructor initializes an empty PCA structure. The other constructors initialize the structure and call
2290 :ocv:funcx:`PCA::operator()` .
2296 Performs Principal Component Analysis of the supplied dataset.
2298 .. ocv:function:: PCA& PCA::operator()(InputArray data, InputArray mean, int flags, int maxComponents=0)
2300 .. ocv:function:: PCA& PCA::computeVar(InputArray data, InputArray mean, int flags, double retainedVariance)
2302 .. ocv:pyfunction:: cv2.PCACompute(data[, mean[, eigenvectors[, maxComponents]]]) -> mean, eigenvectors
2304 .. ocv:pyfunction:: cv2.PCAComputeVar(data, retainedVariance[, mean[, eigenvectors]]) -> mean, eigenvectors
2306 :param data: input samples stored as the matrix rows or as the matrix columns.
2308 :param mean: optional mean value; if the matrix is empty (``noArray()``), the mean is computed from the data.
2310 :param flags: operation flags; currently the parameter is only used to specify the data layout.
2312 * **CV_PCA_DATA_AS_ROW** indicates that the input samples are stored as matrix rows.
2314 * **CV_PCA_DATA_AS_COL** indicates that the input samples are stored as matrix columns.
2316 :param maxComponents: maximum number of components that PCA should retain; by default, all the components are retained.
2318 :param retainedVariance: Percentage of variance that PCA should retain. Using this parameter will let the PCA decided how many components to retain but it will always keep at least 2.
2320 The operator performs PCA of the supplied dataset. It is safe to reuse the same PCA structure for multiple datasets. That is, if the structure has been previously used with another dataset, the existing internal data is reclaimed and the new ``eigenvalues``, ``eigenvectors`` , and ``mean`` are allocated and computed.
2322 The computed eigenvalues are sorted from the largest to the smallest and the corresponding eigenvectors are stored as ``PCA::eigenvectors`` rows.
2328 Projects vector(s) to the principal component subspace.
2330 .. ocv:function:: Mat PCA::project(InputArray vec) const
2332 .. ocv:function:: void PCA::project(InputArray vec, OutputArray result) const
2334 .. ocv:pyfunction:: cv2.PCAProject(data, mean, eigenvectors[, result]) -> result
2336 :param vec: input vector(s); must have the same dimensionality and the same layout as the input data used at PCA phase, that is, if ``CV_PCA_DATA_AS_ROW`` are specified, then ``vec.cols==data.cols`` (vector dimensionality) and ``vec.rows`` is the number of vectors to project, and the same is true for the ``CV_PCA_DATA_AS_COL`` case.
2338 :param result: output vectors; in case of ``CV_PCA_DATA_AS_COL``, the output matrix has as many columns as the number of input vectors, this means that ``result.cols==vec.cols`` and the number of rows match the number of principal components (for example, ``maxComponents`` parameter passed to the constructor).
2340 The methods project one or more vectors to the principal component subspace, where each vector projection is represented by coefficients in the principal component basis. The first form of the method returns the matrix that the second form writes to the result. So the first form can be used as a part of expression while the second form can be more efficient in a processing loop.
2346 Reconstructs vectors from their PC projections.
2348 .. ocv:function:: Mat PCA::backProject(InputArray vec) const
2350 .. ocv:function:: void PCA::backProject(InputArray vec, OutputArray result) const
2352 .. ocv:pyfunction:: cv2.PCABackProject(data, mean, eigenvectors[, result]) -> result
2354 :param vec: coordinates of the vectors in the principal component subspace, the layout and size are the same as of ``PCA::project`` output vectors.
2356 :param result: reconstructed vectors; the layout and size are the same as of ``PCA::project`` input vectors.
2358 The methods are inverse operations to
2359 :ocv:func:`PCA::project`. They take PC coordinates of projected vectors and reconstruct the original vectors. Unless all the principal components have been retained, the reconstructed vectors are different from the originals. But typically, the difference is small if the number of components is large enough (but still much smaller than the original vector dimensionality). As a result, PCA is used.
2363 perspectiveTransform
2364 --------------------
2365 Performs the perspective matrix transformation of vectors.
2367 .. ocv:function:: void perspectiveTransform( InputArray src, OutputArray dst, InputArray m )
2369 .. ocv:pyfunction:: cv2.perspectiveTransform(src, m[, dst]) -> dst
2371 .. ocv:cfunction:: void cvPerspectiveTransform(const CvArr* src, CvArr* dst, const CvMat* mat)
2372 .. ocv:pyoldfunction:: cv.PerspectiveTransform(src, dst, mat)-> None
2374 :param src: input two-channel or three-channel floating-point array; each element is a 2D/3D vector to be transformed.
2376 :param dst: output array of the same size and type as ``src``.
2378 :param m: ``3x3`` or ``4x4`` floating-point transformation matrix.
2380 The function ``perspectiveTransform`` transforms every element of ``src`` by treating it as a 2D or 3D vector, in the following way:
2384 (x, y, z) \rightarrow (x'/w, y'/w, z'/w)
2390 (x', y', z', w') = \texttt{mat} \cdot \begin{bmatrix} x & y & z & 1 \end{bmatrix}
2396 w = \fork{w'}{if $w' \ne 0$}{\infty}{otherwise}
2398 Here a 3D vector transformation is shown. In case of a 2D vector transformation, the ``z`` component is omitted.
2400 .. note:: The function transforms a sparse set of 2D or 3D vectors. If you want to transform an image using perspective transformation, use :ocv:func:`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 :ocv:func:`getPerspectiveTransform` or :ocv:func:`findHomography` .
2404 :ocv:func:`transform`,
2405 :ocv:func:`warpPerspective`,
2406 :ocv:func:`getPerspectiveTransform`,
2407 :ocv:func:`findHomography`
2413 Calculates the rotation angle of 2D vectors.
2415 .. ocv:function:: void phase(InputArray x, InputArray y, OutputArray angle, bool angleInDegrees=false)
2417 .. ocv:pyfunction:: cv2.phase(x, y[, angle[, angleInDegrees]]) -> angle
2419 :param x: input floating-point array of x-coordinates of 2D vectors.
2421 :param y: input array of y-coordinates of 2D vectors; it must have the same size and the same type as ``x``.
2423 :param angle: output array of vector angles; it has the same size and same type as ``x`` .
2425 :param angleInDegrees: when true, the function calculates the angle in degrees, otherwise, they are measured in radians.
2427 The function ``phase`` calculates the rotation angle of each 2D vector that is formed from the corresponding elements of ``x`` and ``y`` :
2431 \texttt{angle} (I) = \texttt{atan2} ( \texttt{y} (I), \texttt{x} (I))
2433 The angle estimation accuracy is about 0.3 degrees. When ``x(I)=y(I)=0`` , the corresponding ``angle(I)`` is set to 0.
2438 Calculates x and y coordinates of 2D vectors from their magnitude and angle.
2440 .. ocv:function:: void polarToCart(InputArray magnitude, InputArray angle, OutputArray x, OutputArray y, bool angleInDegrees=false)
2442 .. ocv:pyfunction:: cv2.polarToCart(magnitude, angle[, x[, y[, angleInDegrees]]]) -> x, y
2444 .. ocv:cfunction:: void cvPolarToCart( const CvArr* magnitude, const CvArr* angle, CvArr* x, CvArr* y, int angle_in_degrees=0 )
2446 .. ocv:pyoldfunction:: cv.PolarToCart(magnitude, angle, x, y, angleInDegrees=0)-> None
2448 :param 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``.
2450 :param angle: input floating-point array of angles of 2D vectors.
2452 :param x: output array of x-coordinates of 2D vectors; it has the same size and type as ``angle``.
2454 :param y: output array of y-coordinates of 2D vectors; it has the same size and type as ``angle``.
2456 :param angleInDegrees: when true, the input angles are measured in degrees, otherwise, they are measured in radians.
2458 The function ``polarToCart`` calculates the Cartesian coordinates of each 2D vector represented by the corresponding elements of ``magnitude`` and ``angle`` :
2462 \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}
2464 The relative accuracy of the estimated coordinates is about ``1e-6``.
2468 :ocv:func:`cartToPolar`,
2469 :ocv:func:`magnitude`,
2480 Raises every array element to a power.
2482 .. ocv:function:: void pow( InputArray src, double power, OutputArray dst )
2484 .. ocv:pyfunction:: cv2.pow(src, power[, dst]) -> dst
2486 .. ocv:cfunction:: void cvPow( const CvArr* src, CvArr* dst, double power)
2487 .. ocv:pyoldfunction:: cv.Pow(src, dst, power)-> None
2489 :param src: input array.
2491 :param power: exponent of power.
2493 :param dst: output array of the same size and type as ``src``.
2495 The function ``pow`` raises every element of the input array to ``power`` :
2499 \texttt{dst} (I) = \fork{\texttt{src}(I)^power}{if \texttt{power} is integer}{|\texttt{src}(I)|^power}{otherwise}
2501 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: ::
2504 pow(src, 1./5, dst);
2505 subtract(Scalar::all(0), dst, dst, mask);
2508 For some values of ``power`` , such as integer values, 0.5 and -0.5, specialized faster algorithms are used.
2510 Special values (NaN, Inf) are not handled.
2517 :ocv:func:`cartToPolar`,
2518 :ocv:func:`polarToCart`
2527 Random number generator. It encapsulates the state (currently, a 64-bit integer) and has methods to return scalar random values and to fill arrays with random values. Currently it supports uniform and Gaussian (normal) distributions. The generator uses Multiply-With-Carry algorithm, introduced by G. Marsaglia (
2528 http://en.wikipedia.org/wiki/Multiply-with-carry
2529 ). Gaussian-distribution random numbers are generated using the Ziggurat algorithm (
2530 http://en.wikipedia.org/wiki/Ziggurat_algorithm
2531 ), introduced by G. Marsaglia and W. W. Tsang.
2539 .. ocv:function:: RNG::RNG()
2541 .. ocv:function:: RNG::RNG(uint64 state)
2543 :param state: 64-bit value used to initialize the RNG.
2545 These are the RNG constructors. The first form sets the state to some pre-defined value, equal to ``2**32-1`` in the current implementation. The second form sets the state to the specified value. If you passed ``state=0`` , the constructor uses the above default value instead to avoid the singular random number sequence, consisting of all zeros.
2551 Returns the next random number.
2553 .. ocv:function:: unsigned RNG::next()
2555 The method updates the state using the MWC algorithm and returns the next 32-bit random number.
2561 Returns the next random number of the specified type.
2563 .. ocv:function:: RNG::operator uchar()
2565 .. ocv:function:: RNG::operator schar()
2567 .. ocv:function:: RNG::operator ushort()
2569 .. ocv:function:: RNG::operator short()
2571 .. ocv:function:: RNG::operator int()
2573 .. ocv:function:: RNG::operator unsigned()
2575 .. ocv:function:: RNG::operator float()
2577 .. ocv:function:: RNG::operator double()
2579 Each of the methods updates the state using the MWC algorithm and returns the next random number of the specified type. In case of integer types, the returned number is from the available value range for the specified type. In case of floating-point types, the returned value is from ``[0,1)`` range.
2585 Returns the next random number.
2587 .. ocv:function:: unsigned RNG::operator ()()
2589 .. ocv:function:: unsigned RNG::operator ()(unsigned N)
2591 :param N: upper non-inclusive boundary of the returned random number.
2593 The methods transform the state using the MWC algorithm and return the next random number. The first form is equivalent to
2594 :ocv:func:`RNG::next` . The second form returns the random number modulo ``N`` , which means that the result is in the range ``[0, N)`` .
2600 Returns the next random number sampled from the uniform distribution.
2602 .. ocv:function:: int RNG::uniform(int a, int b)
2604 .. ocv:function:: float RNG::uniform(float a, float b)
2606 .. ocv:function:: double RNG::uniform(double a, double b)
2608 :param a: lower inclusive boundary of the returned random numbers.
2610 :param b: upper non-inclusive boundary of the returned random numbers.
2612 The methods transform the state using the MWC algorithm and return the next uniformly-distributed random number of the specified type, deduced from the input parameter type, from the range ``[a, b)`` . There is a nuance illustrated by the following sample: ::
2616 // always produces 0
2617 double a = rng.uniform(0, 1);
2619 // produces double from [0, 1)
2620 double a1 = rng.uniform((double)0, (double)1);
2622 // produces float from [0, 1)
2623 double b = rng.uniform(0.f, 1.f);
2625 // produces double from [0, 1)
2626 double c = rng.uniform(0., 1.);
2628 // may cause compiler error because of ambiguity:
2629 // RNG::uniform(0, (int)0.999999)? or RNG::uniform((double)0, 0.99999)?
2630 double d = rng.uniform(0, 0.999999);
2633 The compiler does not take into account the type of the variable to which you assign the result of ``RNG::uniform`` . The only thing that matters to the compiler is the type of ``a`` and ``b`` parameters. So, if you want a floating-point random number, but the range boundaries are integer numbers, either put dots in the end, if they are constants, or use explicit type cast operators, as in the ``a1`` initialization above.
2639 Returns the next random number sampled from the Gaussian distribution.
2641 .. ocv:function:: double RNG::gaussian(double sigma)
2643 :param sigma: standard deviation of the distribution.
2645 The method transforms the state using the MWC algorithm and returns the next random number from the Gaussian distribution ``N(0,sigma)`` . That is, the mean value of the returned random numbers is zero and the standard deviation is the specified ``sigma`` .
2651 Fills arrays with random numbers.
2653 .. ocv:function:: void RNG::fill( InputOutputArray mat, int distType, InputArray a, InputArray b, bool saturateRange=false )
2655 :param mat: 2D or N-dimensional matrix; currently matrices with more than 4 channels are not supported by the methods, use :ocv:func:`Mat::reshape` as a possible workaround.
2657 :param distType: distribution type, ``RNG::UNIFORM`` or ``RNG::NORMAL``.
2659 :param a: first distribution parameter; in case of the uniform distribution, this is an inclusive lower boundary, in case of the normal distribution, this is a mean value.
2661 :param b: second distribution parameter; in case of the uniform distribution, this is a non-inclusive upper boundary, in case of the normal distribution, this is a standard deviation (diagonal of the standard deviation matrix or the full standard deviation matrix).
2663 :param saturateRange: pre-saturation flag; for uniform distribution only; if true, the method will first convert a and b to the acceptable value range (according to the mat datatype) and then will generate uniformly distributed random numbers within the range ``[saturate(a), saturate(b))``, if ``saturateRange=false``, the method will generate uniformly distributed random numbers in the original range ``[a, b)`` and then will saturate them, it means, for example, that ``theRNG().fill(mat_8u, RNG::UNIFORM, -DBL_MAX, DBL_MAX)`` will likely produce array mostly filled with 0's and 255's, since the range ``(0, 255)`` is significantly smaller than ``[-DBL_MAX, DBL_MAX)``.
2665 Each of the methods fills the matrix with the random values from the specified distribution. As the new numbers are generated, the RNG state is updated accordingly. In case of multiple-channel images, every channel is filled independently, which means that RNG cannot generate samples from the multi-dimensional Gaussian distribution with non-diagonal covariance matrix directly. To do that, the method generates samples from multi-dimensional standard Gaussian distribution with zero mean and identity covariation matrix, and then transforms them using :ocv:func:`transform` to get samples from the specified Gaussian distribution.
2669 Generates a single uniformly-distributed random number or an array of random numbers.
2671 .. ocv:function:: template<typename _Tp> _Tp randu()
2673 .. ocv:function:: void randu( InputOutputArray dst, InputArray low, InputArray high )
2675 .. ocv:pyfunction:: cv2.randu(dst, low, high) -> None
2677 :param dst: output array of random numbers; the array must be pre-allocated.
2679 :param low: inclusive lower boundary of the generated random numbers.
2681 :param high: exclusive upper boundary of the generated random numbers.
2683 The template functions ``randu`` generate and return the next uniformly-distributed random value of the specified type. ``randu<int>()`` is an equivalent to ``(int)theRNG();`` , and so on. See
2684 :ocv:class:`RNG` description.
2686 The second non-template variant of the function fills the matrix ``dst`` with uniformly-distributed random numbers from the specified range:
2690 \texttt{low} _c \leq \texttt{dst} (I)_c < \texttt{high} _c
2702 Fills the array with normally distributed random numbers.
2704 .. ocv:function:: void randn( InputOutputArray dst, InputArray mean, InputArray stddev )
2706 .. ocv:pyfunction:: cv2.randn(dst, mean, stddev) -> None
2708 :param dst: output array of random numbers; the array must be pre-allocated and have 1 to 4 channels.
2710 :param mean: mean value (expectation) of the generated random numbers.
2712 :param 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.
2714 The function ``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.
2725 Shuffles the array elements randomly.
2727 .. ocv:function:: void randShuffle( InputOutputArray dst, double iterFactor=1., RNG* rng=0 )
2729 .. ocv:pyfunction:: cv2.randShuffle(dst[, iterFactor]) -> None
2731 :param dst: input/output numerical 1D array.
2733 :param iterFactor: scale factor that determines the number of random swap operations (see the details below).
2735 :param rng: optional random number generator used for shuffling; if it is zero, :ocv:func:`theRNG` () is used instead.
2737 The function ``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`` .
2748 Reduces a matrix to a vector.
2750 .. ocv:function:: void reduce( InputArray src, OutputArray dst, int dim, int rtype, int dtype=-1 )
2752 .. ocv:pyfunction:: cv2.reduce(src, dim, rtype[, dst[, dtype]]) -> dst
2754 .. ocv:cfunction:: void cvReduce(const CvArr* src, CvArr* dst, int dim=-1, int op=CV_REDUCE_SUM)
2755 .. ocv:pyoldfunction:: cv.Reduce(src, dst, dim=-1, op=CV_REDUCE_SUM)-> None
2757 :param src: input 2D matrix.
2759 :param dst: output vector. Its size and type is defined by ``dim`` and ``dtype`` parameters.
2761 :param 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.
2763 :param rtype: reduction operation that could be one of the following:
2765 * **CV_REDUCE_SUM**: the output is the sum of all rows/columns of the matrix.
2767 * **CV_REDUCE_AVG**: the output is the mean vector of all rows/columns of the matrix.
2769 * **CV_REDUCE_MAX**: the output is the maximum (column/row-wise) of all rows/columns of the matrix.
2771 * **CV_REDUCE_MIN**: the output is the minimum (column/row-wise) of all rows/columns of the matrix.
2773 :param 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())``.
2775 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 ``CV_REDUCE_SUM`` and ``CV_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.
2777 .. seealso:: :ocv:func:`repeat`
2783 Fills the output array with repeated copies of the input array.
2785 .. ocv:function:: void repeat(InputArray src, int ny, int nx, OutputArray dst)
2787 .. ocv:function:: Mat repeat( const Mat& src, int ny, int nx )
2789 .. ocv:pyfunction:: cv2.repeat(src, ny, nx[, dst]) -> dst
2791 .. ocv:cfunction:: void cvRepeat(const CvArr* src, CvArr* dst)
2793 .. ocv:pyoldfunction:: cv.Repeat(src, dst)-> None
2795 :param src: input array to replicate.
2797 :param dst: output array of the same type as ``src``.
2799 :param ny: Flag to specify how many times the ``src`` is repeated along the vertical axis.
2801 :param nx: Flag to specify how many times the ``src`` is repeated along the horizontal axis.
2804 :ocv:func:`repeat` duplicate the input array one or more times along each of the two axes:
2808 \texttt{dst} _{ij}= \texttt{src} _{i\mod src.rows, \; j\mod src.cols }
2810 The second variant of the function is more convenient to use with
2811 :ref:`MatrixExpressions` .
2816 :ref:`MatrixExpressions`
2822 Calculates the sum of a scaled array and another array.
2824 .. ocv:function:: void scaleAdd( InputArray src1, double alpha, InputArray src2, OutputArray dst )
2826 .. ocv:pyfunction:: cv2.scaleAdd(src1, alpha, src2[, dst]) -> dst
2828 .. ocv:cfunction:: void cvScaleAdd(const CvArr* src1, CvScalar scale, const CvArr* src2, CvArr* dst)
2829 .. ocv:pyoldfunction:: cv.ScaleAdd(src1, scale, src2, dst)-> None
2831 :param src1: first input array.
2833 :param scale: scale factor for the first array.
2835 :param src2: second input array of the same size and type as ``src1``.
2837 :param dst: output array of the same size and type as ``src1``.
2839 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:
2843 \texttt{dst} (I)= \texttt{scale} \cdot \texttt{src1} (I) + \texttt{src2} (I)
2845 The function can also be emulated with a matrix expression, for example: ::
2847 Mat A(3, 3, CV_64F);
2849 A.row(0) = A.row(1)*2 + A.row(2);
2855 :ocv:func:`addWeighted`,
2856 :ocv:func:`subtract`,
2857 :ocv:func:`Mat::dot`,
2858 :ocv:func:`Mat::convertTo`,
2859 :ref:`MatrixExpressions`
2865 Initializes a scaled identity matrix.
2867 .. ocv:function:: void setIdentity( InputOutputArray mtx, const Scalar& s=Scalar(1) )
2869 .. ocv:pyfunction:: cv2.setIdentity(mtx[, s]) -> None
2871 .. ocv:cfunction:: void cvSetIdentity(CvArr* mat, CvScalar value=cvRealScalar(1))
2873 .. ocv:pyoldfunction:: cv.SetIdentity(mat, value=1)-> None
2875 :param mtx: matrix to initialize (not necessarily square).
2877 :param value: value to assign to diagonal elements.
2880 :ocv:func:`setIdentity` initializes a scaled identity matrix:
2884 \texttt{mtx} (i,j)= \fork{\texttt{value}}{ if $i=j$}{0}{otherwise}
2886 The function can also be emulated using the matrix initializers and the matrix expressions: ::
2888 Mat A = Mat::eye(4, 3, CV_32F)*5;
2889 // A will be set to [[5, 0, 0], [0, 5, 0], [0, 0, 5], [0, 0, 0]]
2894 :ocv:func:`Mat::zeros`,
2895 :ocv:func:`Mat::ones`,
2896 :ref:`MatrixExpressions`,
2897 :ocv:func:`Mat::setTo`,
2898 :ocv:func:`Mat::operator=`
2904 Solves one or more linear systems or least-squares problems.
2906 .. ocv:function:: bool solve(InputArray src1, InputArray src2, OutputArray dst, int flags=DECOMP_LU)
2908 .. ocv:pyfunction:: cv2.solve(src1, src2[, dst[, flags]]) -> retval, dst
2910 .. ocv:cfunction:: int cvSolve(const CvArr* src1, const CvArr* src2, CvArr* dst, int method=CV_LU)
2911 .. ocv:pyoldfunction:: cv.Solve(A, B, X, method=CV_LU)-> None
2913 :param src1: input matrix on the left-hand side of the system.
2915 :param src2: input matrix on the right-hand side of the system.
2917 :param dst: output solution.
2919 :param flags: solution (matrix inversion) method.
2921 * **DECOMP_LU** Gaussian elimination with optimal pivot element chosen.
2923 * **DECOMP_CHOLESKY** Cholesky :math:`LL^T` factorization; the matrix ``src1`` must be symmetrical and positively defined.
2925 * **DECOMP_EIG** eigenvalue decomposition; the matrix ``src1`` must be symmetrical.
2927 * **DECOMP_SVD** singular value decomposition (SVD) method; the system can be over-defined and/or the matrix ``src1`` can be singular.
2929 * **DECOMP_QR** QR factorization; the system can be over-defined and/or the matrix ``src1`` can be singular.
2931 * **DECOMP_NORMAL** while all the previous flags are mutually exclusive, this flag can be used together with any of the previous; it means that the normal equations :math:`\texttt{src1}^T\cdot\texttt{src1}\cdot\texttt{dst}=\texttt{src1}^T\texttt{src2}` are solved instead of the original system :math:`\texttt{src1}\cdot\texttt{dst}=\texttt{src2}` .
2933 The function ``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`` ):
2937 \texttt{dst} = \arg \min _X \| \texttt{src1} \cdot \texttt{X} - \texttt{src2} \|
2939 If ``DECOMP_LU`` or ``DECOMP_CHOLESKY`` method is used, the function returns 1 if ``src1`` (or
2940 :math:`\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.
2942 .. note:: If you want to find a unity-norm solution of an under-defined singular system :math:`\texttt{src1}\cdot\texttt{dst}=0` , the function ``solve`` will not do the work. Use :ocv:func:`SVD::solveZ` instead.
2954 Finds the real roots of a cubic equation.
2956 .. ocv:function:: int solveCubic( InputArray coeffs, OutputArray roots )
2958 .. ocv:pyfunction:: cv2.solveCubic(coeffs[, roots]) -> retval, roots
2960 .. ocv:cfunction:: int cvSolveCubic( const CvMat* coeffs, CvMat* roots )
2962 .. ocv:pyoldfunction:: cv.SolveCubic(coeffs, roots)-> None
2964 :param coeffs: equation coefficients, an array of 3 or 4 elements.
2966 :param roots: output array of real roots that has 1 or 3 elements.
2968 The function ``solveCubic`` finds the real roots of a cubic equation:
2970 * if ``coeffs`` is a 4-element vector:
2974 \texttt{coeffs} [0] x^3 + \texttt{coeffs} [1] x^2 + \texttt{coeffs} [2] x + \texttt{coeffs} [3] = 0
2976 * if ``coeffs`` is a 3-element vector:
2980 x^3 + \texttt{coeffs} [0] x^2 + \texttt{coeffs} [1] x + \texttt{coeffs} [2] = 0
2982 The roots are stored in the ``roots`` array.
2988 Finds the real or complex roots of a polynomial equation.
2990 .. ocv:function:: double solvePoly( InputArray coeffs, OutputArray roots, int maxIters=300 )
2992 .. ocv:pyfunction:: cv2.solvePoly(coeffs[, roots[, maxIters]]) -> retval, roots
2994 :param coeffs: array of polynomial coefficients.
2996 :param roots: output (complex) array of roots.
2998 :param maxIters: maximum number of iterations the algorithm does.
3000 The function ``solvePoly`` finds real and complex roots of a polynomial equation:
3004 \texttt{coeffs} [n] x^{n} + \texttt{coeffs} [n-1] x^{n-1} + ... + \texttt{coeffs} [1] x + \texttt{coeffs} [0] = 0
3010 Sorts each row or each column of a matrix.
3012 .. ocv:function:: void sort(InputArray src, OutputArray dst, int flags)
3014 .. ocv:pyfunction:: cv2.sort(src, flags[, dst]) -> dst
3016 :param src: input single-channel array.
3018 :param dst: output array of the same size and type as ``src``.
3020 :param flags: operation flags, a combination of the following values:
3022 * **CV_SORT_EVERY_ROW** each matrix row is sorted independently.
3024 * **CV_SORT_EVERY_COLUMN** each matrix column is sorted independently; this flag and the previous one are mutually exclusive.
3026 * **CV_SORT_ASCENDING** each matrix row is sorted in the ascending order.
3028 * **CV_SORT_DESCENDING** each matrix row is sorted in the descending order; this flag and the previous one are also mutually exclusive.
3030 The function ``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.
3034 :ocv:func:`sortIdx`,
3035 :ocv:func:`randShuffle`
3041 Sorts each row or each column of a matrix.
3043 .. ocv:function:: void sortIdx(InputArray src, OutputArray dst, int flags)
3045 .. ocv:pyfunction:: cv2.sortIdx(src, flags[, dst]) -> dst
3047 :param src: input single-channel array.
3049 :param dst: output integer array of the same size as ``src``.
3051 :param flags: operation flags that could be a combination of the following values:
3053 * **CV_SORT_EVERY_ROW** each matrix row is sorted independently.
3055 * **CV_SORT_EVERY_COLUMN** each matrix column is sorted independently; this flag and the previous one are mutually exclusive.
3057 * **CV_SORT_ASCENDING** each matrix row is sorted in the ascending order.
3059 * **CV_SORT_DESCENDING** each matrix row is sorted in the descending order; his flag and the previous one are also mutually exclusive.
3061 The function ``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: ::
3063 Mat A = Mat::eye(3,3,CV_32F), B;
3064 sortIdx(A, B, CV_SORT_EVERY_ROW + CV_SORT_ASCENDING);
3065 // B will probably contain
3066 // (because of equal elements in A some permutations are possible):
3067 // [[1, 2, 0], [0, 2, 1], [0, 1, 2]]
3073 :ocv:func:`randShuffle`
3079 Divides a multi-channel array into several single-channel arrays.
3081 .. ocv:function:: void split( const Mat& src, Mat* mvbegin )
3083 .. ocv:function:: void split( InputArray m, OutputArrayOfArrays mv )
3085 .. ocv:pyfunction:: cv2.split(m[, mv]) -> mv
3087 .. ocv:cfunction:: void cvSplit(const CvArr* src, CvArr* dst0, CvArr* dst1, CvArr* dst2, CvArr* dst3)
3089 .. ocv:pyoldfunction:: cv.Split(src, dst0, dst1, dst2, dst3)-> None
3091 :param src: input multi-channel array.
3093 :param mv: output array or vector of arrays; in the first variant of the function the number of arrays must match ``src.channels()``; the arrays themselves are reallocated, if needed.
3095 The functions ``split`` split a multi-channel array into separate single-channel arrays:
3099 \texttt{mv} [c](I) = \texttt{src} (I)_c
3101 If you need to extract a single channel or do some other sophisticated channel permutation, use
3102 :ocv:func:`mixChannels` .
3107 :ocv:func:`mixChannels`,
3108 :ocv:func:`cvtColor`
3114 Calculates a square root of array elements.
3116 .. ocv:function:: void sqrt(InputArray src, OutputArray dst)
3118 .. ocv:pyfunction:: cv2.sqrt(src[, dst]) -> dst
3120 .. ocv:cfunction:: float cvSqrt(float value)
3121 .. ocv:pyoldfunction:: cv.Sqrt(value)-> float
3123 :param src: input floating-point array.
3125 :param dst: output array of the same size and type as ``src``.
3127 The functions ``sqrt`` calculate 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`` .
3132 :ocv:func:`magnitude`
3138 Calculates the per-element difference between two arrays or array and a scalar.
3140 .. ocv:function:: void subtract(InputArray src1, InputArray src2, OutputArray dst, InputArray mask=noArray(), int dtype=-1)
3142 .. ocv:pyfunction:: cv2.subtract(src1, src2[, dst[, mask[, dtype]]]) -> dst
3144 .. ocv:cfunction:: void cvSub(const CvArr* src1, const CvArr* src2, CvArr* dst, const CvArr* mask=NULL)
3145 .. ocv:cfunction:: void cvSubRS( const CvArr* src, CvScalar value, CvArr* dst, const CvArr* mask=NULL )
3146 .. ocv:cfunction:: void cvSubS( const CvArr* src, CvScalar value, CvArr* dst, const CvArr* mask=NULL )
3148 .. ocv:pyoldfunction:: cv.Sub(src1, src2, dst, mask=None) -> None
3149 .. ocv:pyoldfunction:: cv.SubRS(src, value, dst, mask=None) -> None
3150 .. ocv:pyoldfunction:: cv.SubS(src, value, dst, mask=None) -> None
3152 :param src1: first input array or a scalar.
3154 :param src2: second input array or a scalar.
3156 :param dst: output array of the same size and the same number of channels as the input array.
3158 :param mask: optional operation mask; this is an 8-bit single channel array that specifies elements of the output array to be changed.
3160 :param dtype: optional depth of the output array (see the details below).
3162 The function ``subtract`` calculates:
3165 Difference between two arrays, when both input arrays have the same size and the same number of channels:
3169 \texttt{dst}(I) = \texttt{saturate} ( \texttt{src1}(I) - \texttt{src2}(I)) \quad \texttt{if mask}(I) \ne0
3172 Difference between an array and a scalar, when ``src2`` is constructed from ``Scalar`` or has the same number of elements as ``src1.channels()``:
3176 \texttt{dst}(I) = \texttt{saturate} ( \texttt{src1}(I) - \texttt{src2} ) \quad \texttt{if mask}(I) \ne0
3179 Difference between a scalar and an array, when ``src1`` is constructed from ``Scalar`` or has the same number of elements as ``src2.channels()``:
3183 \texttt{dst}(I) = \texttt{saturate} ( \texttt{src1} - \texttt{src2}(I) ) \quad \texttt{if mask}(I) \ne0
3186 The reverse difference between a scalar and an array in the case of ``SubRS``:
3190 \texttt{dst}(I) = \texttt{saturate} ( \texttt{src2} - \texttt{src1}(I) ) \quad \texttt{if mask}(I) \ne0
3192 where ``I`` is a multi-dimensional index of array elements. In case of multi-channel arrays, each channel is processed independently.
3194 The first function in the list above can be replaced with matrix expressions: ::
3197 dst -= src1; // equivalent to subtract(dst, src1, dst);
3199 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.
3201 .. 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.
3206 :ocv:func:`addWeighted`,
3207 :ocv:func:`scaleAdd`,
3208 :ocv:func:`Mat::convertTo`,
3209 :ref:`MatrixExpressions`
3217 Class for computing Singular Value Decomposition of a floating-point matrix. The Singular Value Decomposition is used to solve least-square problems, under-determined linear systems, invert matrices, compute condition numbers, and so on.
3219 For a faster operation, you can pass ``flags=SVD::MODIFY_A|...`` to modify the decomposed matrix when it is not necessary to preserve it. If you want to compute a condition number of a matrix or an absolute value of its determinant, you do not need ``u`` and ``vt`` . You can pass ``flags=SVD::NO_UV|...`` . Another flag ``FULL_UV`` indicates that full-size ``u`` and ``vt`` must be computed, which is not necessary most of the time.
3226 :ocv:func:`determinant`
3234 .. ocv:function:: SVD::SVD()
3236 .. ocv:function:: SVD::SVD( InputArray src, int flags=0 )
3238 :param src: decomposed matrix.
3240 :param flags: operation flags.
3242 * **SVD::MODIFY_A** use the algorithm to modify the decomposed matrix; it can save space and speed up processing.
3244 * **SVD::NO_UV** indicates that only a vector of singular values ``w`` is to be processed, while ``u`` and ``vt`` will be set to empty matrices.
3246 * **SVD::FULL_UV** when the matrix is not square, by default the algorithm produces ``u`` and ``vt`` matrices of sufficiently large size for the further ``A`` reconstruction; if, however, ``FULL_UV`` flag is specified, ``u`` and ``vt`` will be full-size square orthogonal matrices.
3248 The first constructor initializes an empty ``SVD`` structure. The second constructor initializes an empty ``SVD`` structure and then calls
3249 :ocv:funcx:`SVD::operator()` .
3254 Performs SVD of a matrix.
3256 .. ocv:function:: SVD& SVD::operator()( InputArray src, int flags=0 )
3258 :param src: decomposed matrix.
3260 :param flags: operation flags.
3262 * **SVD::MODIFY_A** use the algorithm to modify the decomposed matrix; it can save space and speed up processing.
3264 * **SVD::NO_UV** use only singular values; the algorithm does not compute ``u`` and ``vt`` matrices.
3266 * **SVD::FULL_UV** when the matrix is not square, by default the algorithm produces ``u`` and ``vt`` matrices of sufficiently large size for the further ``A`` reconstruction; if, however, the ``FULL_UV`` flag is specified, ``u`` and ``vt`` are full-size square orthogonal matrices.
3268 The operator performs the singular value decomposition of the supplied matrix. The ``u``,``vt`` , and the vector of singular values ``w`` are stored in the structure. The same ``SVD`` structure can be reused many times with different matrices. Each time, if needed, the previous ``u``,``vt`` , and ``w`` are reclaimed and the new matrices are created, which is all handled by
3269 :ocv:func:`Mat::create` .
3274 Performs SVD of a matrix
3276 .. ocv:function:: static void SVD::compute( InputArray src, OutputArray w, OutputArray u, OutputArray vt, int flags=0 )
3278 .. ocv:function:: static void SVD::compute( InputArray src, OutputArray w, int flags=0 )
3280 .. ocv:pyfunction:: cv2.SVDecomp(src[, w[, u[, vt[, flags]]]]) -> w, u, vt
3282 .. ocv:cfunction:: void cvSVD( CvArr* A, CvArr* W, CvArr* U=NULL, CvArr* V=NULL, int flags=0 )
3284 .. ocv:pyoldfunction:: cv.SVD(A, W, U=None, V=None, flags=0) -> None
3286 :param src: decomposed matrix
3288 :param w: calculated singular values
3290 :param u: calculated left singular vectors
3292 :param V: calculated right singular vectors
3294 :param vt: transposed matrix of right singular values
3296 :param flags: operation flags - see :ocv:func:`SVD::SVD`.
3298 The methods/functions perform SVD of matrix. Unlike ``SVD::SVD`` constructor and ``SVD::operator()``, they store the results to the user-provided matrices. ::
3301 SVD::compute(A, w, u, vt);
3306 Solves an under-determined singular linear system.
3308 .. ocv:function:: static void SVD::solveZ( InputArray src, OutputArray dst )
3310 :param src: left-hand-side matrix.
3312 :param dst: found solution.
3314 The method finds a unit-length solution ``x`` of a singular linear system
3315 ``A*x = 0``. Depending on the rank of ``A``, there can be no solutions, a single solution or an infinite number of solutions. In general, the algorithm solves the following problem:
3319 dst = \arg \min _{x: \| x \| =1} \| src \cdot x \|
3324 Performs a singular value back substitution.
3326 .. ocv:function:: void SVD::backSubst( InputArray rhs, OutputArray dst ) const
3328 .. ocv:function:: static void SVD::backSubst( InputArray w, InputArray u, InputArray vt, InputArray rhs, OutputArray dst )
3330 .. ocv:pyfunction:: cv2.SVBackSubst(w, u, vt, rhs[, dst]) -> dst
3332 .. ocv:cfunction:: void cvSVBkSb( const CvArr* W, const CvArr* U, const CvArr* V, const CvArr* B, CvArr* X, int flags )
3334 .. ocv:pyoldfunction:: cv.SVBkSb(W, U, V, B, X, flags) -> None
3336 :param w: singular values
3338 :param u: left singular vectors
3340 :param V: right singular vectors
3342 :param vt: transposed matrix of right singular vectors.
3344 :param rhs: right-hand side of a linear system ``(u*w*v')*dst = rhs`` to be solved, where ``A`` has been previously decomposed.
3346 :param dst: found solution of the system.
3348 The method calculates a back substitution for the specified right-hand side:
3352 \texttt{x} = \texttt{vt} ^T \cdot diag( \texttt{w} )^{-1} \cdot \texttt{u} ^T \cdot \texttt{rhs} \sim \texttt{A} ^{-1} \cdot \texttt{rhs}
3354 Using this technique you can either get a very accurate solution of the convenient linear system, or the best (in the least-squares terms) pseudo-solution of an overdetermined linear system.
3356 .. note:: Explicit SVD with the further back substitution only makes sense if you need to solve many linear systems with the same left-hand side (for example, ``src`` ). If all you need is to solve a single system (possibly with multiple ``rhs`` immediately available), simply call :ocv:func:`solve` add pass ``DECOMP_SVD`` there. It does absolutely the same thing.
3362 Calculates the sum of array elements.
3364 .. ocv:function:: Scalar sum( InputArray src )
3366 .. ocv:pyfunction:: cv2.sumElems(src) -> retval
3368 .. ocv:cfunction:: CvScalar cvSum(const CvArr* arr)
3370 .. ocv:pyoldfunction:: cv.Sum(arr) -> scalar
3372 :param arr: input array that must have from 1 to 4 channels.
3374 The functions ``sum`` calculate and return the sum of array elements, independently for each channel.
3378 :ocv:func:`countNonZero`,
3380 :ocv:func:`meanStdDev`,
3382 :ocv:func:`minMaxLoc`,
3389 Returns the default random number generator.
3391 .. ocv:function:: RNG& theRNG()
3393 The function ``theRNG`` returns the default random number generator. For each thread, there is a separate random number generator, so you can use the function safely in multi-thread environments. If you just need to get a single random number using this generator or initialize an array, you can use
3394 :ocv:func:`randu` or
3395 :ocv:func:`randn` instead. But if you are going to generate many random numbers inside a loop, it is much faster to use this function to retrieve the generator and then use ``RNG::operator _Tp()`` .
3407 Returns the trace of a matrix.
3409 .. ocv:function:: Scalar trace( InputArray mtx )
3411 .. ocv:pyfunction:: cv2.trace(mtx) -> retval
3413 .. ocv:cfunction:: CvScalar cvTrace(const CvArr* mat)
3415 .. ocv:pyoldfunction:: cv.Trace(mat) -> scalar
3417 :param mat: input matrix.
3419 The function ``trace`` returns the sum of the diagonal elements of the matrix ``mtx`` .
3423 \mathrm{tr} ( \texttt{mtx} ) = \sum _i \texttt{mtx} (i,i)
3429 Performs the matrix transformation of every array element.
3431 .. ocv:function:: void transform( InputArray src, OutputArray dst, InputArray m )
3433 .. ocv:pyfunction:: cv2.transform(src, m[, dst]) -> dst
3435 .. ocv:cfunction:: void cvTransform( const CvArr* src, CvArr* dst, const CvMat* transmat, const CvMat* shiftvec=NULL )
3437 .. ocv:pyoldfunction:: cv.Transform(src, dst, transmat, shiftvec=None)-> None
3439 :param src: input array that must have as many channels (1 to 4) as ``m.cols`` or ``m.cols-1``.
3441 :param dst: output array of the same size and depth as ``src``; it has as many channels as ``m.rows``.
3443 :param m: transformation ``2x2`` or ``2x3`` floating-point matrix.
3445 :param shiftvec: optional translation vector (when ``m`` is ``2x2``)
3447 The function ``transform`` performs the matrix transformation of every element of the array ``src`` and stores the results in ``dst`` :
3451 \texttt{dst} (I) = \texttt{m} \cdot \texttt{src} (I)
3453 (when ``m.cols=src.channels()`` ), or
3457 \texttt{dst} (I) = \texttt{m} \cdot [ \texttt{src} (I); 1]
3459 (when ``m.cols=src.channels()+1`` )
3461 Every element of the ``N`` -channel array ``src`` is interpreted as ``N`` -element vector that is transformed using
3462 the ``M x N`` or ``M x (N+1)`` matrix ``m``
3463 to ``M``-element vector - the corresponding element of the output array ``dst`` .
3465 The function may be used for geometrical transformation of
3467 points, arbitrary linear color space transformation (such as various kinds of RGB to YUV transforms), shuffling the image channels, and so forth.
3471 :ocv:func:`perspectiveTransform`,
3472 :ocv:func:`getAffineTransform`,
3473 :ocv:func:`estimateRigidTransform`,
3474 :ocv:func:`warpAffine`,
3475 :ocv:func:`warpPerspective`
3481 Transposes a matrix.
3483 .. ocv:function:: void transpose(InputArray src, OutputArray dst)
3485 .. ocv:pyfunction:: cv2.transpose(src[, dst]) -> dst
3487 .. ocv:cfunction:: void cvTranspose(const CvArr* src, CvArr* dst)
3488 .. ocv:pyoldfunction:: cv.Transpose(src, dst)-> None
3490 :param src: input array.
3492 :param dst: output array of the same type as ``src``.
3494 The function :ocv:func:`transpose` transposes the matrix ``src`` :
3498 \texttt{dst} (i,j) = \texttt{src} (j,i)
3500 .. note:: No complex conjugation is done in case of a complex matrix. It it should be done separately if needed.