1 /*M///////////////////////////////////////////////////////////////////////////////////////
3 // IMPORTANT: READ BEFORE DOWNLOADING, COPYING, INSTALLING OR USING.
5 // By downloading, copying, installing or using the software you agree to this license.
6 // If you do not agree to this license, do not download, install,
7 // copy or use the software.
11 // For Open Source Computer Vision Library
13 // Copyright (C) 2000-2015, Intel Corporation, all rights reserved.
14 // Copyright (C) 2009-2011, Willow Garage Inc., all rights reserved.
15 // Copyright (C) 2015, OpenCV Foundation, all rights reserved.
16 // Copyright (C) 2015, Itseez Inc., all rights reserved.
17 // Third party copyrights are property of their respective owners.
19 // Redistribution and use in source and binary forms, with or without modification,
20 // are permitted provided that the following conditions are met:
22 // * Redistribution's of source code must retain the above copyright notice,
23 // this list of conditions and the following disclaimer.
25 // * Redistribution's in binary form must reproduce the above copyright notice,
26 // this list of conditions and the following disclaimer in the documentation
27 // and/or other materials provided with the distribution.
29 // * The name of the copyright holders may not be used to endorse or promote products
30 // derived from this software without specific prior written permission.
32 // This software is provided by the copyright holders and contributors "as is" and
33 // any express or implied warranties, including, but not limited to, the implied
34 // warranties of merchantability and fitness for a particular purpose are disclaimed.
35 // In no event shall the Intel Corporation or contributors be liable for any direct,
36 // indirect, incidental, special, exemplary, or consequential damages
37 // (including, but not limited to, procurement of substitute goods or services;
38 // loss of use, data, or profits; or business interruption) however caused
39 // and on any theory of liability, whether in contract, strict liability,
40 // or tort (including negligence or otherwise) arising in any way out of
41 // the use of this software, even if advised of the possibility of such damage.
45 #ifndef OPENCV_CORE_HPP
46 #define OPENCV_CORE_HPP
49 # error core.hpp header must be compiled as C++
52 #include "opencv2/core/cvdef.h"
53 #include "opencv2/core/base.hpp"
54 #include "opencv2/core/cvstd.hpp"
55 #include "opencv2/core/traits.hpp"
56 #include "opencv2/core/matx.hpp"
57 #include "opencv2/core/types.hpp"
58 #include "opencv2/core/mat.hpp"
59 #include "opencv2/core/persistence.hpp"
62 @defgroup core Core functionality
64 @defgroup core_basic Basic structures
65 @defgroup core_c C structures and operations
67 @defgroup core_c_glue Connections with C++
69 @defgroup core_array Operations on arrays
70 @defgroup core_async Asynchronous API
71 @defgroup core_xml XML/YAML Persistence
72 @defgroup core_cluster Clustering
73 @defgroup core_utils Utility and system functions and macros
75 @defgroup core_logging Logging facilities
76 @defgroup core_utils_sse SSE utilities
77 @defgroup core_utils_neon NEON utilities
78 @defgroup core_utils_vsx VSX utilities
79 @defgroup core_utils_softfloat Softfloat support
80 @defgroup core_utils_samples Utility functions for OpenCV samples
82 @defgroup core_opengl OpenGL interoperability
83 @defgroup core_ipp Intel IPP Asynchronous C/C++ Converters
84 @defgroup core_optim Optimization Algorithms
85 @defgroup core_directx DirectX interoperability
86 @defgroup core_eigen Eigen support
87 @defgroup core_opencl OpenCL support
88 @defgroup core_va_intel Intel VA-API/OpenCL (CL-VA) interoperability
89 @defgroup core_hal Hardware Acceleration Layer
91 @defgroup core_hal_functions Functions
92 @defgroup core_hal_interface Interface
93 @defgroup core_hal_intrin Universal intrinsics
95 @defgroup core_hal_intrin_impl Private implementation helpers
103 //! @addtogroup core_utils
106 /*! @brief Class passed to an error.
108 This class encapsulates all or almost all necessary
109 information about the error happened in the program. The exception is
110 usually constructed and thrown implicitly via CV_Error and CV_Error_ macros.
113 class CV_EXPORTS Exception : public std::exception
121 Full constructor. Normally the constructor is not called explicitly.
122 Instead, the macros CV_Error(), CV_Error_() and CV_Assert() are used.
124 Exception(int _code, const String& _err, const String& _func, const String& _file, int _line);
125 virtual ~Exception() throw();
128 \return the error description and the context as a text string.
130 virtual const char *what() const throw() CV_OVERRIDE;
131 void formatMessage();
133 String msg; ///< the formatted error message
135 int code; ///< error code @see CVStatus
136 String err; ///< error description
137 String func; ///< function name. Available only when the compiler supports getting it
138 String file; ///< source file name where the error has occurred
139 int line; ///< line number in the source file where the error has occurred
142 /*! @brief Signals an error and raises the exception.
144 By default the function prints information about the error to stderr,
145 then it either stops if cv::setBreakOnError() had been called before or raises the exception.
146 It is possible to alternate error processing by using #redirectError().
147 @param exc the exception raisen.
148 @deprecated drop this version
150 CV_EXPORTS void error( const Exception& exc );
152 enum SortFlags { SORT_EVERY_ROW = 0, //!< each matrix row is sorted independently
153 SORT_EVERY_COLUMN = 1, //!< each matrix column is sorted
154 //!< independently; this flag and the previous one are
155 //!< mutually exclusive.
156 SORT_ASCENDING = 0, //!< each matrix row is sorted in the ascending
158 SORT_DESCENDING = 16 //!< each matrix row is sorted in the
159 //!< descending order; this flag and the previous one are also
160 //!< mutually exclusive.
168 //! Covariation flags
170 /** The output covariance matrix is calculated as:
171 \f[\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} ,...],\f]
172 The covariance matrix will be nsamples x nsamples. Such an unusual covariance matrix is used
173 for fast PCA of a set of very large vectors (see, for example, the EigenFaces technique for
174 face recognition). Eigenvalues of this "scrambled" matrix match the eigenvalues of the true
175 covariance matrix. The "true" eigenvectors can be easily calculated from the eigenvectors of
176 the "scrambled" covariance matrix. */
178 /**The output covariance matrix is calculated as:
179 \f[\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,\f]
180 covar will be a square matrix of the same size as the total number of elements in each input
181 vector. One and only one of #COVAR_SCRAMBLED and #COVAR_NORMAL must be specified.*/
183 /** If the flag is specified, the function does not calculate mean from
184 the input vectors but, instead, uses the passed mean vector. This is useful if mean has been
185 pre-calculated or known in advance, or if the covariance matrix is calculated by parts. In
186 this case, mean is not a mean vector of the input sub-set of vectors but rather the mean
187 vector of the whole set.*/
189 /** If the flag is specified, the covariance matrix is scaled. In the
190 "normal" mode, scale is 1./nsamples . In the "scrambled" mode, scale is the reciprocal of the
191 total number of elements in each input vector. By default (if the flag is not specified), the
192 covariance matrix is not scaled ( scale=1 ).*/
195 specified, all the input vectors are stored as rows of the samples matrix. mean should be a
196 single-row vector in this case.*/
199 specified, all the input vectors are stored as columns of the samples matrix. mean should be a
200 single-column vector in this case.*/
204 //! @addtogroup core_cluster
209 /** Select random initial centers in each attempt.*/
210 KMEANS_RANDOM_CENTERS = 0,
211 /** Use kmeans++ center initialization by Arthur and Vassilvitskii [Arthur2007].*/
212 KMEANS_PP_CENTERS = 2,
213 /** During the first (and possibly the only) attempt, use the
214 user-supplied labels instead of computing them from the initial centers. For the second and
215 further attempts, use the random or semi-random centers. Use one of KMEANS_\*_CENTERS flag
216 to specify the exact method.*/
217 KMEANS_USE_INITIAL_LABELS = 1
225 LINE_4 = 4, //!< 4-connected line
226 LINE_8 = 8, //!< 8-connected line
227 LINE_AA = 16 //!< antialiased line
230 //! Only a subset of Hershey fonts <https://en.wikipedia.org/wiki/Hershey_fonts> are supported
232 FONT_HERSHEY_SIMPLEX = 0, //!< normal size sans-serif font
233 FONT_HERSHEY_PLAIN = 1, //!< small size sans-serif font
234 FONT_HERSHEY_DUPLEX = 2, //!< normal size sans-serif font (more complex than FONT_HERSHEY_SIMPLEX)
235 FONT_HERSHEY_COMPLEX = 3, //!< normal size serif font
236 FONT_HERSHEY_TRIPLEX = 4, //!< normal size serif font (more complex than FONT_HERSHEY_COMPLEX)
237 FONT_HERSHEY_COMPLEX_SMALL = 5, //!< smaller version of FONT_HERSHEY_COMPLEX
238 FONT_HERSHEY_SCRIPT_SIMPLEX = 6, //!< hand-writing style font
239 FONT_HERSHEY_SCRIPT_COMPLEX = 7, //!< more complex variant of FONT_HERSHEY_SCRIPT_SIMPLEX
240 FONT_ITALIC = 16 //!< flag for italic font
243 //! @addtogroup core_array
246 enum ReduceTypes { REDUCE_SUM = 0, //!< the output is the sum of all rows/columns of the matrix.
247 REDUCE_AVG = 1, //!< the output is the mean vector of all rows/columns of the matrix.
248 REDUCE_MAX = 2, //!< the output is the maximum (column/row-wise) of all rows/columns of the matrix.
249 REDUCE_MIN = 3 //!< the output is the minimum (column/row-wise) of all rows/columns of the matrix.
254 /** @brief Swaps two matrices
256 CV_EXPORTS void swap(Mat& a, Mat& b);
258 CV_EXPORTS void swap( UMat& a, UMat& b );
262 //! @addtogroup core_array
265 /** @brief Computes the source location of an extrapolated pixel.
267 The function computes and returns the coordinate of a donor pixel corresponding to the specified
268 extrapolated pixel when using the specified extrapolation border mode. For example, if you use
269 cv::BORDER_WRAP mode in the horizontal direction, cv::BORDER_REFLECT_101 in the vertical direction and
270 want to compute value of the "virtual" pixel Point(-5, 100) in a floating-point image img , it
273 float val = img.at<float>(borderInterpolate(100, img.rows, cv::BORDER_REFLECT_101),
274 borderInterpolate(-5, img.cols, cv::BORDER_WRAP));
276 Normally, the function is not called directly. It is used inside filtering functions and also in
278 @param p 0-based coordinate of the extrapolated pixel along one of the axes, likely \<0 or \>= len
279 @param len Length of the array along the corresponding axis.
280 @param borderType Border type, one of the #BorderTypes, except for #BORDER_TRANSPARENT and
281 #BORDER_ISOLATED . When borderType==#BORDER_CONSTANT , the function always returns -1, regardless
286 CV_EXPORTS_W int borderInterpolate(int p, int len, int borderType);
288 /** @example samples/cpp/tutorial_code/ImgTrans/copyMakeBorder_demo.cpp
289 An example using copyMakeBorder function.
290 Check @ref tutorial_copyMakeBorder "the corresponding tutorial" for more details
293 /** @brief Forms a border around an image.
295 The function copies the source image into the middle of the destination image. The areas to the
296 left, to the right, above and below the copied source image will be filled with extrapolated
297 pixels. This is not what filtering functions based on it do (they extrapolate pixels on-fly), but
298 what other more complex functions, including your own, may do to simplify image boundary handling.
300 The function supports the mode when src is already in the middle of dst . In this case, the
301 function does not copy src itself but simply constructs the border, for example:
304 // let border be the same in all directions
306 // constructs a larger image to fit both the image and the border
307 Mat gray_buf(rgb.rows + border*2, rgb.cols + border*2, rgb.depth());
308 // select the middle part of it w/o copying data
309 Mat gray(gray_canvas, Rect(border, border, rgb.cols, rgb.rows));
310 // convert image from RGB to grayscale
311 cvtColor(rgb, gray, COLOR_RGB2GRAY);
312 // form a border in-place
313 copyMakeBorder(gray, gray_buf, border, border,
314 border, border, BORDER_REPLICATE);
315 // now do some custom filtering ...
318 @note When the source image is a part (ROI) of a bigger image, the function will try to use the
319 pixels outside of the ROI to form a border. To disable this feature and always do extrapolation, as
320 if src was not a ROI, use borderType | #BORDER_ISOLATED.
322 @param src Source image.
323 @param dst Destination image of the same type as src and the size Size(src.cols+left+right,
324 src.rows+top+bottom) .
325 @param top the top pixels
326 @param bottom the bottom pixels
327 @param left the left pixels
328 @param right Parameter specifying how many pixels in each direction from the source image rectangle
329 to extrapolate. For example, top=1, bottom=1, left=1, right=1 mean that 1 pixel-wide border needs
331 @param borderType Border type. See borderInterpolate for details.
332 @param value Border value if borderType==BORDER_CONSTANT .
334 @sa borderInterpolate
336 CV_EXPORTS_W void copyMakeBorder(InputArray src, OutputArray dst,
337 int top, int bottom, int left, int right,
338 int borderType, const Scalar& value = Scalar() );
340 /** @brief Calculates the per-element sum of two arrays or an array and a scalar.
342 The function add calculates:
343 - Sum of two arrays when both input arrays have the same size and the same number of channels:
344 \f[\texttt{dst}(I) = \texttt{saturate} ( \texttt{src1}(I) + \texttt{src2}(I)) \quad \texttt{if mask}(I) \ne0\f]
345 - Sum of an array and a scalar when src2 is constructed from Scalar or has the same number of
346 elements as `src1.channels()`:
347 \f[\texttt{dst}(I) = \texttt{saturate} ( \texttt{src1}(I) + \texttt{src2} ) \quad \texttt{if mask}(I) \ne0\f]
348 - Sum of a scalar and an array when src1 is constructed from Scalar or has the same number of
349 elements as `src2.channels()`:
350 \f[\texttt{dst}(I) = \texttt{saturate} ( \texttt{src1} + \texttt{src2}(I) ) \quad \texttt{if mask}(I) \ne0\f]
351 where `I` is a multi-dimensional index of array elements. In case of multi-channel arrays, each
352 channel is processed independently.
354 The first function in the list above can be replaced with matrix expressions:
357 dst += src1; // equivalent to add(dst, src1, dst);
359 The input arrays and the output array can all have the same or different depths. For example, you
360 can add a 16-bit unsigned array to a 8-bit signed array and store the sum as a 32-bit
361 floating-point array. Depth of the output array is determined by the dtype parameter. In the second
362 and third cases above, as well as in the first case, when src1.depth() == src2.depth(), dtype can
363 be set to the default -1. In this case, the output array will have the same depth as the input
364 array, be it src1, src2 or both.
365 @note Saturation is not applied when the output array has the depth CV_32S. You may even get
366 result of an incorrect sign in the case of overflow.
367 @param src1 first input array or a scalar.
368 @param src2 second input array or a scalar.
369 @param dst output array that has the same size and number of channels as the input array(s); the
370 depth is defined by dtype or src1/src2.
371 @param mask optional operation mask - 8-bit single channel array, that specifies elements of the
372 output array to be changed.
373 @param dtype optional depth of the output array (see the discussion below).
374 @sa subtract, addWeighted, scaleAdd, Mat::convertTo
376 CV_EXPORTS_W void add(InputArray src1, InputArray src2, OutputArray dst,
377 InputArray mask = noArray(), int dtype = -1);
379 /** @brief Calculates the per-element difference between two arrays or array and a scalar.
381 The function subtract calculates:
382 - Difference between two arrays, when both input arrays have the same size and the same number of
384 \f[\texttt{dst}(I) = \texttt{saturate} ( \texttt{src1}(I) - \texttt{src2}(I)) \quad \texttt{if mask}(I) \ne0\f]
385 - Difference between an array and a scalar, when src2 is constructed from Scalar or has the same
386 number of elements as `src1.channels()`:
387 \f[\texttt{dst}(I) = \texttt{saturate} ( \texttt{src1}(I) - \texttt{src2} ) \quad \texttt{if mask}(I) \ne0\f]
388 - Difference between a scalar and an array, when src1 is constructed from Scalar or has the same
389 number of elements as `src2.channels()`:
390 \f[\texttt{dst}(I) = \texttt{saturate} ( \texttt{src1} - \texttt{src2}(I) ) \quad \texttt{if mask}(I) \ne0\f]
391 - The reverse difference between a scalar and an array in the case of `SubRS`:
392 \f[\texttt{dst}(I) = \texttt{saturate} ( \texttt{src2} - \texttt{src1}(I) ) \quad \texttt{if mask}(I) \ne0\f]
393 where I is a multi-dimensional index of array elements. In case of multi-channel arrays, each
394 channel is processed independently.
396 The first function in the list above can be replaced with matrix expressions:
399 dst -= src1; // equivalent to subtract(dst, src1, dst);
401 The input arrays and the output array can all have the same or different depths. For example, you
402 can subtract to 8-bit unsigned arrays and store the difference in a 16-bit signed array. Depth of
403 the output array is determined by dtype parameter. In the second and third cases above, as well as
404 in the first case, when src1.depth() == src2.depth(), dtype can be set to the default -1. In this
405 case the output array will have the same depth as the input array, be it src1, src2 or both.
406 @note Saturation is not applied when the output array has the depth CV_32S. You may even get
407 result of an incorrect sign in the case of overflow.
408 @param src1 first input array or a scalar.
409 @param src2 second input array or a scalar.
410 @param dst output array of the same size and the same number of channels as the input array.
411 @param mask optional operation mask; this is an 8-bit single channel array that specifies elements
412 of the output array to be changed.
413 @param dtype optional depth of the output array
414 @sa add, addWeighted, scaleAdd, Mat::convertTo
416 CV_EXPORTS_W void subtract(InputArray src1, InputArray src2, OutputArray dst,
417 InputArray mask = noArray(), int dtype = -1);
420 /** @brief Calculates the per-element scaled product of two arrays.
422 The function multiply calculates the per-element product of two arrays:
424 \f[\texttt{dst} (I)= \texttt{saturate} ( \texttt{scale} \cdot \texttt{src1} (I) \cdot \texttt{src2} (I))\f]
426 There is also a @ref MatrixExpressions -friendly variant of the first function. See Mat::mul .
428 For a not-per-element matrix product, see gemm .
430 @note Saturation is not applied when the output array has the depth
431 CV_32S. You may even get result of an incorrect sign in the case of
433 @param src1 first input array.
434 @param src2 second input array of the same size and the same type as src1.
435 @param dst output array of the same size and type as src1.
436 @param scale optional scale factor.
437 @param dtype optional depth of the output array
438 @sa add, subtract, divide, scaleAdd, addWeighted, accumulate, accumulateProduct, accumulateSquare,
441 CV_EXPORTS_W void multiply(InputArray src1, InputArray src2,
442 OutputArray dst, double scale = 1, int dtype = -1);
444 /** @brief Performs per-element division of two arrays or a scalar by an array.
446 The function cv::divide divides one array by another:
447 \f[\texttt{dst(I) = saturate(src1(I)*scale/src2(I))}\f]
448 or a scalar by an array when there is no src1 :
449 \f[\texttt{dst(I) = saturate(scale/src2(I))}\f]
451 When src2(I) is zero, dst(I) will also be zero. Different channels of
452 multi-channel arrays are processed independently.
454 @note Saturation is not applied when the output array has the depth CV_32S. You may even get
455 result of an incorrect sign in the case of overflow.
456 @param src1 first input array.
457 @param src2 second input array of the same size and type as src1.
458 @param scale scalar factor.
459 @param dst output array of the same size and type as src2.
460 @param dtype optional depth of the output array; if -1, dst will have depth src2.depth(), but in
461 case of an array-by-array division, you can only pass -1 when src1.depth()==src2.depth().
462 @sa multiply, add, subtract
464 CV_EXPORTS_W void divide(InputArray src1, InputArray src2, OutputArray dst,
465 double scale = 1, int dtype = -1);
468 CV_EXPORTS_W void divide(double scale, InputArray src2,
469 OutputArray dst, int dtype = -1);
471 /** @brief Calculates the sum of a scaled array and another array.
473 The function scaleAdd is one of the classical primitive linear algebra operations, known as DAXPY
474 or SAXPY in [BLAS](http://en.wikipedia.org/wiki/Basic_Linear_Algebra_Subprograms). It calculates
475 the sum of a scaled array and another array:
476 \f[\texttt{dst} (I)= \texttt{scale} \cdot \texttt{src1} (I) + \texttt{src2} (I)\f]
477 The function can also be emulated with a matrix expression, for example:
481 A.row(0) = A.row(1)*2 + A.row(2);
483 @param src1 first input array.
484 @param alpha scale factor for the first array.
485 @param src2 second input array of the same size and type as src1.
486 @param dst output array of the same size and type as src1.
487 @sa add, addWeighted, subtract, Mat::dot, Mat::convertTo
489 CV_EXPORTS_W void scaleAdd(InputArray src1, double alpha, InputArray src2, OutputArray dst);
491 /** @example samples/cpp/tutorial_code/HighGUI/AddingImagesTrackbar.cpp
492 Check @ref tutorial_trackbar "the corresponding tutorial" for more details
495 /** @brief Calculates the weighted sum of two arrays.
497 The function addWeighted calculates the weighted sum of two arrays as follows:
498 \f[\texttt{dst} (I)= \texttt{saturate} ( \texttt{src1} (I)* \texttt{alpha} + \texttt{src2} (I)* \texttt{beta} + \texttt{gamma} )\f]
499 where I is a multi-dimensional index of array elements. In case of multi-channel arrays, each
500 channel is processed independently.
501 The function can be replaced with a matrix expression:
503 dst = src1*alpha + src2*beta + gamma;
505 @note Saturation is not applied when the output array has the depth CV_32S. You may even get
506 result of an incorrect sign in the case of overflow.
507 @param src1 first input array.
508 @param alpha weight of the first array elements.
509 @param src2 second input array of the same size and channel number as src1.
510 @param beta weight of the second array elements.
511 @param gamma scalar added to each sum.
512 @param dst output array that has the same size and number of channels as the input arrays.
513 @param dtype optional depth of the output array; when both input arrays have the same depth, dtype
514 can be set to -1, which will be equivalent to src1.depth().
515 @sa add, subtract, scaleAdd, Mat::convertTo
517 CV_EXPORTS_W void addWeighted(InputArray src1, double alpha, InputArray src2,
518 double beta, double gamma, OutputArray dst, int dtype = -1);
520 /** @brief Scales, calculates absolute values, and converts the result to 8-bit.
522 On each element of the input array, the function convertScaleAbs
523 performs three operations sequentially: scaling, taking an absolute
524 value, conversion to an unsigned 8-bit type:
525 \f[\texttt{dst} (I)= \texttt{saturate\_cast<uchar>} (| \texttt{src} (I)* \texttt{alpha} + \texttt{beta} |)\f]
526 In case of multi-channel arrays, the function processes each channel
527 independently. When the output is not 8-bit, the operation can be
528 emulated by calling the Mat::convertTo method (or by using matrix
529 expressions) and then by calculating an absolute value of the result.
532 Mat_<float> A(30,30);
533 randu(A, Scalar(-100), Scalar(100));
534 Mat_<float> B = A*5 + 3;
536 // Mat_<float> B = abs(A*5+3) will also do the job,
537 // but it will allocate a temporary matrix
539 @param src input array.
540 @param dst output array.
541 @param alpha optional scale factor.
542 @param beta optional delta added to the scaled values.
543 @sa Mat::convertTo, cv::abs(const Mat&)
545 CV_EXPORTS_W void convertScaleAbs(InputArray src, OutputArray dst,
546 double alpha = 1, double beta = 0);
548 /** @brief Converts an array to half precision floating number.
550 This function converts FP32 (single precision floating point) from/to FP16 (half precision floating point). CV_16S format is used to represent FP16 data.
551 There are two use modes (src -> dst): CV_32F -> CV_16S and CV_16S -> CV_32F. The input array has to have type of CV_32F or
552 CV_16S to represent the bit depth. If the input array is neither of them, the function will raise an error.
553 The format of half precision floating point is defined in IEEE 754-2008.
555 @param src input array.
556 @param dst output array.
558 CV_EXPORTS_W void convertFp16(InputArray src, OutputArray dst);
560 /** @brief Performs a look-up table transform of an array.
562 The function LUT fills the output array with values from the look-up table. Indices of the entries
563 are taken from the input array. That is, the function processes each element of src as follows:
564 \f[\texttt{dst} (I) \leftarrow \texttt{lut(src(I) + d)}\f]
566 \f[d = \fork{0}{if \(\texttt{src}\) has depth \(\texttt{CV_8U}\)}{128}{if \(\texttt{src}\) has depth \(\texttt{CV_8S}\)}\f]
567 @param src input array of 8-bit elements.
568 @param lut look-up table of 256 elements; in case of multi-channel input array, the table should
569 either have a single channel (in this case the same table is used for all channels) or the same
570 number of channels as in the input array.
571 @param dst output array of the same size and number of channels as src, and the same depth as lut.
572 @sa convertScaleAbs, Mat::convertTo
574 CV_EXPORTS_W void LUT(InputArray src, InputArray lut, OutputArray dst);
576 /** @brief Calculates the sum of array elements.
578 The function cv::sum calculates and returns the sum of array elements,
579 independently for each channel.
580 @param src input array that must have from 1 to 4 channels.
581 @sa countNonZero, mean, meanStdDev, norm, minMaxLoc, reduce
583 CV_EXPORTS_AS(sumElems) Scalar sum(InputArray src);
585 /** @brief Counts non-zero array elements.
587 The function returns the number of non-zero elements in src :
588 \f[\sum _{I: \; \texttt{src} (I) \ne0 } 1\f]
589 @param src single-channel array.
590 @sa mean, meanStdDev, norm, minMaxLoc, calcCovarMatrix
592 CV_EXPORTS_W int countNonZero( InputArray src );
594 /** @brief Returns the list of locations of non-zero pixels
596 Given a binary matrix (likely returned from an operation such
597 as threshold(), compare(), >, ==, etc, return all of
598 the non-zero indices as a cv::Mat or std::vector<cv::Point> (x,y)
601 cv::Mat binaryImage; // input, binary image
602 cv::Mat locations; // output, locations of non-zero pixels
603 cv::findNonZero(binaryImage, locations);
605 // access pixel coordinates
606 Point pnt = locations.at<Point>(i);
610 cv::Mat binaryImage; // input, binary image
611 vector<Point> locations; // output, locations of non-zero pixels
612 cv::findNonZero(binaryImage, locations);
614 // access pixel coordinates
615 Point pnt = locations[i];
617 @param src single-channel array (type CV_8UC1)
618 @param idx the output array, type of cv::Mat or std::vector<Point>, corresponding to non-zero indices in the input
620 CV_EXPORTS_W void findNonZero( InputArray src, OutputArray idx );
622 /** @brief Calculates an average (mean) of array elements.
624 The function cv::mean calculates the mean value M of array elements,
625 independently for each channel, and return it:
626 \f[\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}\f]
627 When all the mask elements are 0's, the function returns Scalar::all(0)
628 @param src input array that should have from 1 to 4 channels so that the result can be stored in
630 @param mask optional operation mask.
631 @sa countNonZero, meanStdDev, norm, minMaxLoc
633 CV_EXPORTS_W Scalar mean(InputArray src, InputArray mask = noArray());
635 /** Calculates a mean and standard deviation of array elements.
637 The function cv::meanStdDev calculates the mean and the standard deviation M
638 of array elements independently for each channel and returns it via the
640 \f[\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}\f]
641 When all the mask elements are 0's, the function returns
642 mean=stddev=Scalar::all(0).
643 @note The calculated standard deviation is only the diagonal of the
644 complete normalized covariance matrix. If the full matrix is needed, you
645 can reshape the multi-channel array M x N to the single-channel array
646 M\*N x mtx.channels() (only possible when the matrix is continuous) and
647 then pass the matrix to calcCovarMatrix .
648 @param src input array that should have from 1 to 4 channels so that the results can be stored in
650 @param mean output parameter: calculated mean value.
651 @param stddev output parameter: calculated standard deviation.
652 @param mask optional operation mask.
653 @sa countNonZero, mean, norm, minMaxLoc, calcCovarMatrix
655 CV_EXPORTS_W void meanStdDev(InputArray src, OutputArray mean, OutputArray stddev,
656 InputArray mask=noArray());
658 /** @brief Calculates the absolute norm of an array.
660 This version of #norm calculates the absolute norm of src1. The type of norm to calculate is specified using #NormTypes.
662 As example for one array consider the function \f$r(x)= \begin{pmatrix} x \\ 1-x \end{pmatrix}, x \in [-1;1]\f$.
663 The \f$ L_{1}, L_{2} \f$ and \f$ L_{\infty} \f$ norm for the sample value \f$r(-1) = \begin{pmatrix} -1 \\ 2 \end{pmatrix}\f$
664 is calculated as follows
666 \| r(-1) \|_{L_1} &= |-1| + |2| = 3 \\
667 \| r(-1) \|_{L_2} &= \sqrt{(-1)^{2} + (2)^{2}} = \sqrt{5} \\
668 \| r(-1) \|_{L_\infty} &= \max(|-1|,|2|) = 2
670 and for \f$r(0.5) = \begin{pmatrix} 0.5 \\ 0.5 \end{pmatrix}\f$ the calculation is
672 \| r(0.5) \|_{L_1} &= |0.5| + |0.5| = 1 \\
673 \| r(0.5) \|_{L_2} &= \sqrt{(0.5)^{2} + (0.5)^{2}} = \sqrt{0.5} \\
674 \| r(0.5) \|_{L_\infty} &= \max(|0.5|,|0.5|) = 0.5.
676 The following graphic shows all values for the three norm functions \f$\| r(x) \|_{L_1}, \| r(x) \|_{L_2}\f$ and \f$\| r(x) \|_{L_\infty}\f$.
677 It is notable that the \f$ L_{1} \f$ norm forms the upper and the \f$ L_{\infty} \f$ norm forms the lower border for the example function \f$ r(x) \f$.
678 ![Graphs for the different norm functions from the above example](pics/NormTypes_OneArray_1-2-INF.png)
680 When the mask parameter is specified and it is not empty, the norm is
682 If normType is not specified, #NORM_L2 is used.
683 calculated only over the region specified by the mask.
685 Multi-channel input arrays are treated as single-channel arrays, that is,
686 the results for all channels are combined.
688 Hamming norms can only be calculated with CV_8U depth arrays.
690 @param src1 first input array.
691 @param normType type of the norm (see #NormTypes).
692 @param mask optional operation mask; it must have the same size as src1 and CV_8UC1 type.
694 CV_EXPORTS_W double norm(InputArray src1, int normType = NORM_L2, InputArray mask = noArray());
696 /** @brief Calculates an absolute difference norm or a relative difference norm.
698 This version of cv::norm calculates the absolute difference norm
699 or the relative difference norm of arrays src1 and src2.
700 The type of norm to calculate is specified using #NormTypes.
702 @param src1 first input array.
703 @param src2 second input array of the same size and the same type as src1.
704 @param normType type of the norm (see #NormTypes).
705 @param mask optional operation mask; it must have the same size as src1 and CV_8UC1 type.
707 CV_EXPORTS_W double norm(InputArray src1, InputArray src2,
708 int normType = NORM_L2, InputArray mask = noArray());
710 @param src first input array.
711 @param normType type of the norm (see #NormTypes).
713 CV_EXPORTS double norm( const SparseMat& src, int normType );
715 /** @brief Computes the Peak Signal-to-Noise Ratio (PSNR) image quality metric.
717 This function calculates the Peak Signal-to-Noise Ratio (PSNR) image quality metric in decibels (dB), between two input arrays src1 and src2. Arrays must have depth CV_8U.
719 The PSNR is calculated as follows:
722 \texttt{PSNR} = 10 \cdot \log_{10}{\left( \frac{R^2}{MSE} \right) }
725 where R is the maximum integer value of depth CV_8U (255) and MSE is the mean squared error between the two arrays.
727 @param src1 first input array.
728 @param src2 second input array of the same size as src1.
731 CV_EXPORTS_W double PSNR(InputArray src1, InputArray src2);
733 /** @brief naive nearest neighbor finder
735 see http://en.wikipedia.org/wiki/Nearest_neighbor_search
738 CV_EXPORTS_W void batchDistance(InputArray src1, InputArray src2,
739 OutputArray dist, int dtype, OutputArray nidx,
740 int normType = NORM_L2, int K = 0,
741 InputArray mask = noArray(), int update = 0,
742 bool crosscheck = false);
744 /** @brief Normalizes the norm or value range of an array.
746 The function cv::normalize normalizes scale and shift the input array elements so that
747 \f[\| \texttt{dst} \| _{L_p}= \texttt{alpha}\f]
748 (where p=Inf, 1 or 2) when normType=NORM_INF, NORM_L1, or NORM_L2, respectively; or so that
749 \f[\min _I \texttt{dst} (I)= \texttt{alpha} , \, \, \max _I \texttt{dst} (I)= \texttt{beta}\f]
751 when normType=NORM_MINMAX (for dense arrays only). The optional mask specifies a sub-array to be
752 normalized. This means that the norm or min-n-max are calculated over the sub-array, and then this
753 sub-array is modified to be normalized. If you want to only use the mask to calculate the norm or
754 min-max but modify the whole array, you can use norm and Mat::convertTo.
756 In case of sparse matrices, only the non-zero values are analyzed and transformed. Because of this,
757 the range transformation for sparse matrices is not allowed since it can shift the zero level.
759 Possible usage with some positive example data:
761 vector<double> positiveData = { 2.0, 8.0, 10.0 };
762 vector<double> normalizedData_l1, normalizedData_l2, normalizedData_inf, normalizedData_minmax;
764 // Norm to probability (total count)
765 // sum(numbers) = 20.0
766 // 2.0 0.1 (2.0/20.0)
767 // 8.0 0.4 (8.0/20.0)
768 // 10.0 0.5 (10.0/20.0)
769 normalize(positiveData, normalizedData_l1, 1.0, 0.0, NORM_L1);
771 // Norm to unit vector: ||positiveData|| = 1.0
775 normalize(positiveData, normalizedData_l2, 1.0, 0.0, NORM_L2);
777 // Norm to max element
778 // 2.0 0.2 (2.0/10.0)
779 // 8.0 0.8 (8.0/10.0)
780 // 10.0 1.0 (10.0/10.0)
781 normalize(positiveData, normalizedData_inf, 1.0, 0.0, NORM_INF);
783 // Norm to range [0.0;1.0]
784 // 2.0 0.0 (shift to left border)
785 // 8.0 0.75 (6.0/8.0)
786 // 10.0 1.0 (shift to right border)
787 normalize(positiveData, normalizedData_minmax, 1.0, 0.0, NORM_MINMAX);
790 @param src input array.
791 @param dst output array of the same size as src .
792 @param alpha norm value to normalize to or the lower range boundary in case of the range
794 @param beta upper range boundary in case of the range normalization; it is not used for the norm
796 @param norm_type normalization type (see cv::NormTypes).
797 @param dtype when negative, the output array has the same type as src; otherwise, it has the same
798 number of channels as src and the depth =CV_MAT_DEPTH(dtype).
799 @param mask optional operation mask.
800 @sa norm, Mat::convertTo, SparseMat::convertTo
802 CV_EXPORTS_W void normalize( InputArray src, InputOutputArray dst, double alpha = 1, double beta = 0,
803 int norm_type = NORM_L2, int dtype = -1, InputArray mask = noArray());
806 @param src input array.
807 @param dst output array of the same size as src .
808 @param alpha norm value to normalize to or the lower range boundary in case of the range
810 @param normType normalization type (see cv::NormTypes).
812 CV_EXPORTS void normalize( const SparseMat& src, SparseMat& dst, double alpha, int normType );
814 /** @brief Finds the global minimum and maximum in an array.
816 The function cv::minMaxLoc finds the minimum and maximum element values and their positions. The
817 extremums are searched across the whole array or, if mask is not an empty array, in the specified
820 The function do not work with multi-channel arrays. If you need to find minimum or maximum
821 elements across all the channels, use Mat::reshape first to reinterpret the array as
822 single-channel. Or you may extract the particular channel using either extractImageCOI , or
823 mixChannels , or split .
824 @param src input single-channel array.
825 @param minVal pointer to the returned minimum value; NULL is used if not required.
826 @param maxVal pointer to the returned maximum value; NULL is used if not required.
827 @param minLoc pointer to the returned minimum location (in 2D case); NULL is used if not required.
828 @param maxLoc pointer to the returned maximum location (in 2D case); NULL is used if not required.
829 @param mask optional mask used to select a sub-array.
830 @sa max, min, compare, inRange, extractImageCOI, mixChannels, split, Mat::reshape
832 CV_EXPORTS_W void minMaxLoc(InputArray src, CV_OUT double* minVal,
833 CV_OUT double* maxVal = 0, CV_OUT Point* minLoc = 0,
834 CV_OUT Point* maxLoc = 0, InputArray mask = noArray());
837 /** @brief Finds the global minimum and maximum in an array
839 The function cv::minMaxIdx finds the minimum and maximum element values and their positions. The
840 extremums are searched across the whole array or, if mask is not an empty array, in the specified
841 array region. The function does not work with multi-channel arrays. If you need to find minimum or
842 maximum elements across all the channels, use Mat::reshape first to reinterpret the array as
843 single-channel. Or you may extract the particular channel using either extractImageCOI , or
844 mixChannels , or split . In case of a sparse matrix, the minimum is found among non-zero elements
846 @note When minIdx is not NULL, it must have at least 2 elements (as well as maxIdx), even if src is
847 a single-row or single-column matrix. In OpenCV (following MATLAB) each array has at least 2
848 dimensions, i.e. single-column matrix is Mx1 matrix (and therefore minIdx/maxIdx will be
849 (i1,0)/(i2,0)) and single-row matrix is 1xN matrix (and therefore minIdx/maxIdx will be
851 @param src input single-channel array.
852 @param minVal pointer to the returned minimum value; NULL is used if not required.
853 @param maxVal pointer to the returned maximum value; NULL is used if not required.
854 @param minIdx pointer to the returned minimum location (in nD case); NULL is used if not required;
855 Otherwise, it must point to an array of src.dims elements, the coordinates of the minimum element
856 in each dimension are stored there sequentially.
857 @param maxIdx pointer to the returned maximum location (in nD case). NULL is used if not required.
858 @param mask specified array region
860 CV_EXPORTS void minMaxIdx(InputArray src, double* minVal, double* maxVal = 0,
861 int* minIdx = 0, int* maxIdx = 0, InputArray mask = noArray());
864 @param a input single-channel array.
865 @param minVal pointer to the returned minimum value; NULL is used if not required.
866 @param maxVal pointer to the returned maximum value; NULL is used if not required.
867 @param minIdx pointer to the returned minimum location (in nD case); NULL is used if not required;
868 Otherwise, it must point to an array of src.dims elements, the coordinates of the minimum element
869 in each dimension are stored there sequentially.
870 @param maxIdx pointer to the returned maximum location (in nD case). NULL is used if not required.
872 CV_EXPORTS void minMaxLoc(const SparseMat& a, double* minVal,
873 double* maxVal, int* minIdx = 0, int* maxIdx = 0);
875 /** @brief Reduces a matrix to a vector.
877 The function #reduce reduces the matrix to a vector by treating the matrix rows/columns as a set of
878 1D vectors and performing the specified operation on the vectors until a single row/column is
879 obtained. For example, the function can be used to compute horizontal and vertical projections of a
880 raster image. In case of #REDUCE_MAX and #REDUCE_MIN , the output image should have the same type as the source one.
881 In case of #REDUCE_SUM and #REDUCE_AVG , the output may have a larger element bit-depth to preserve accuracy.
882 And multi-channel arrays are also supported in these two reduction modes.
884 The following code demonstrates its usage for a single channel matrix.
885 @snippet snippets/core_reduce.cpp example
887 And the following code demonstrates its usage for a two-channel matrix.
888 @snippet snippets/core_reduce.cpp example2
890 @param src input 2D matrix.
891 @param dst output vector. Its size and type is defined by dim and dtype parameters.
892 @param dim dimension index along which the matrix is reduced. 0 means that the matrix is reduced to
893 a single row. 1 means that the matrix is reduced to a single column.
894 @param rtype reduction operation that could be one of #ReduceTypes
895 @param dtype when negative, the output vector will have the same type as the input matrix,
896 otherwise, its type will be CV_MAKE_TYPE(CV_MAT_DEPTH(dtype), src.channels()).
899 CV_EXPORTS_W void reduce(InputArray src, OutputArray dst, int dim, int rtype, int dtype = -1);
901 /** @brief Creates one multi-channel array out of several single-channel ones.
903 The function cv::merge merges several arrays to make a single multi-channel array. That is, each
904 element of the output array will be a concatenation of the elements of the input arrays, where
905 elements of i-th input array are treated as mv[i].channels()-element vectors.
907 The function cv::split does the reverse operation. If you need to shuffle channels in some other
908 advanced way, use cv::mixChannels.
910 The following example shows how to merge 3 single channel matrices into a single 3-channel matrix.
911 @snippet snippets/core_merge.cpp example
913 @param mv input array of matrices to be merged; all the matrices in mv must have the same
914 size and the same depth.
915 @param count number of input matrices when mv is a plain C array; it must be greater than zero.
916 @param dst output array of the same size and the same depth as mv[0]; The number of channels will
917 be equal to the parameter count.
918 @sa mixChannels, split, Mat::reshape
920 CV_EXPORTS void merge(const Mat* mv, size_t count, OutputArray dst);
923 @param mv input vector of matrices to be merged; all the matrices in mv must have the same
924 size and the same depth.
925 @param dst output array of the same size and the same depth as mv[0]; The number of channels will
926 be the total number of channels in the matrix array.
928 CV_EXPORTS_W void merge(InputArrayOfArrays mv, OutputArray dst);
930 /** @brief Divides a multi-channel array into several single-channel arrays.
932 The function cv::split splits a multi-channel array into separate single-channel arrays:
933 \f[\texttt{mv} [c](I) = \texttt{src} (I)_c\f]
934 If you need to extract a single channel or do some other sophisticated channel permutation, use
937 The following example demonstrates how to split a 3-channel matrix into 3 single channel matrices.
938 @snippet snippets/core_split.cpp example
940 @param src input multi-channel array.
941 @param mvbegin output array; the number of arrays must match src.channels(); the arrays themselves are
942 reallocated, if needed.
943 @sa merge, mixChannels, cvtColor
945 CV_EXPORTS void split(const Mat& src, Mat* mvbegin);
948 @param m input multi-channel array.
949 @param mv output vector of arrays; the arrays themselves are reallocated, if needed.
951 CV_EXPORTS_W void split(InputArray m, OutputArrayOfArrays mv);
953 /** @brief Copies specified channels from input arrays to the specified channels of
956 The function cv::mixChannels provides an advanced mechanism for shuffling image channels.
958 cv::split,cv::merge,cv::extractChannel,cv::insertChannel and some forms of cv::cvtColor are partial cases of cv::mixChannels.
960 In the example below, the code splits a 4-channel BGRA image into a 3-channel BGR (with B and R
961 channels swapped) and a separate alpha-channel image:
963 Mat bgra( 100, 100, CV_8UC4, Scalar(255,0,0,255) );
964 Mat bgr( bgra.rows, bgra.cols, CV_8UC3 );
965 Mat alpha( bgra.rows, bgra.cols, CV_8UC1 );
967 // forming an array of matrices is a quite efficient operation,
968 // because the matrix data is not copied, only the headers
969 Mat out[] = { bgr, alpha };
970 // bgra[0] -> bgr[2], bgra[1] -> bgr[1],
971 // bgra[2] -> bgr[0], bgra[3] -> alpha[0]
972 int from_to[] = { 0,2, 1,1, 2,0, 3,3 };
973 mixChannels( &bgra, 1, out, 2, from_to, 4 );
975 @note Unlike many other new-style C++ functions in OpenCV (see the introduction section and
976 Mat::create ), cv::mixChannels requires the output arrays to be pre-allocated before calling the
978 @param src input array or vector of matrices; all of the matrices must have the same size and the
980 @param nsrcs number of matrices in `src`.
981 @param dst output array or vector of matrices; all the matrices **must be allocated**; their size and
982 depth must be the same as in `src[0]`.
983 @param ndsts number of matrices in `dst`.
984 @param fromTo array of index pairs specifying which channels are copied and where; fromTo[k\*2] is
985 a 0-based index of the input channel in src, fromTo[k\*2+1] is an index of the output channel in
986 dst; the continuous channel numbering is used: the first input image channels are indexed from 0 to
987 src[0].channels()-1, the second input image channels are indexed from src[0].channels() to
988 src[0].channels() + src[1].channels()-1, and so on, the same scheme is used for the output image
989 channels; as a special case, when fromTo[k\*2] is negative, the corresponding output channel is
991 @param npairs number of index pairs in `fromTo`.
992 @sa split, merge, extractChannel, insertChannel, cvtColor
994 CV_EXPORTS void mixChannels(const Mat* src, size_t nsrcs, Mat* dst, size_t ndsts,
995 const int* fromTo, size_t npairs);
998 @param src input array or vector of matrices; all of the matrices must have the same size and the
1000 @param dst output array or vector of matrices; all the matrices **must be allocated**; their size and
1001 depth must be the same as in src[0].
1002 @param fromTo array of index pairs specifying which channels are copied and where; fromTo[k\*2] is
1003 a 0-based index of the input channel in src, fromTo[k\*2+1] is an index of the output channel in
1004 dst; the continuous channel numbering is used: the first input image channels are indexed from 0 to
1005 src[0].channels()-1, the second input image channels are indexed from src[0].channels() to
1006 src[0].channels() + src[1].channels()-1, and so on, the same scheme is used for the output image
1007 channels; as a special case, when fromTo[k\*2] is negative, the corresponding output channel is
1009 @param npairs number of index pairs in fromTo.
1011 CV_EXPORTS void mixChannels(InputArrayOfArrays src, InputOutputArrayOfArrays dst,
1012 const int* fromTo, size_t npairs);
1015 @param src input array or vector of matrices; all of the matrices must have the same size and the
1017 @param dst output array or vector of matrices; all the matrices **must be allocated**; their size and
1018 depth must be the same as in src[0].
1019 @param fromTo array of index pairs specifying which channels are copied and where; fromTo[k\*2] is
1020 a 0-based index of the input channel in src, fromTo[k\*2+1] is an index of the output channel in
1021 dst; the continuous channel numbering is used: the first input image channels are indexed from 0 to
1022 src[0].channels()-1, the second input image channels are indexed from src[0].channels() to
1023 src[0].channels() + src[1].channels()-1, and so on, the same scheme is used for the output image
1024 channels; as a special case, when fromTo[k\*2] is negative, the corresponding output channel is
1027 CV_EXPORTS_W void mixChannels(InputArrayOfArrays src, InputOutputArrayOfArrays dst,
1028 const std::vector<int>& fromTo);
1030 /** @brief Extracts a single channel from src (coi is 0-based index)
1031 @param src input array
1032 @param dst output array
1033 @param coi index of channel to extract
1034 @sa mixChannels, split
1036 CV_EXPORTS_W void extractChannel(InputArray src, OutputArray dst, int coi);
1038 /** @brief Inserts a single channel to dst (coi is 0-based index)
1039 @param src input array
1040 @param dst output array
1041 @param coi index of channel for insertion
1042 @sa mixChannels, merge
1044 CV_EXPORTS_W void insertChannel(InputArray src, InputOutputArray dst, int coi);
1046 /** @brief Flips a 2D array around vertical, horizontal, or both axes.
1048 The function cv::flip flips the array in one of three different ways (row
1049 and column indices are 0-based):
1050 \f[\texttt{dst} _{ij} =
1053 \texttt{src} _{\texttt{src.rows}-i-1,j} & if\; \texttt{flipCode} = 0 \\
1054 \texttt{src} _{i, \texttt{src.cols} -j-1} & if\; \texttt{flipCode} > 0 \\
1055 \texttt{src} _{ \texttt{src.rows} -i-1, \texttt{src.cols} -j-1} & if\; \texttt{flipCode} < 0 \\
1058 The example scenarios of using the function are the following:
1059 * Vertical flipping of the image (flipCode == 0) to switch between
1060 top-left and bottom-left image origin. This is a typical operation
1061 in video processing on Microsoft Windows\* OS.
1062 * Horizontal flipping of the image with the subsequent horizontal
1063 shift and absolute difference calculation to check for a
1064 vertical-axis symmetry (flipCode \> 0).
1065 * Simultaneous horizontal and vertical flipping of the image with
1066 the subsequent shift and absolute difference calculation to check
1067 for a central symmetry (flipCode \< 0).
1068 * Reversing the order of point arrays (flipCode \> 0 or
1070 @param src input array.
1071 @param dst output array of the same size and type as src.
1072 @param flipCode a flag to specify how to flip the array; 0 means
1073 flipping around the x-axis and positive value (for example, 1) means
1074 flipping around y-axis. Negative value (for example, -1) means flipping
1076 @sa transpose , repeat , completeSymm
1078 CV_EXPORTS_W void flip(InputArray src, OutputArray dst, int flipCode);
1081 ROTATE_90_CLOCKWISE = 0, //!<Rotate 90 degrees clockwise
1082 ROTATE_180 = 1, //!<Rotate 180 degrees clockwise
1083 ROTATE_90_COUNTERCLOCKWISE = 2, //!<Rotate 270 degrees clockwise
1085 /** @brief Rotates a 2D array in multiples of 90 degrees.
1086 The function cv::rotate rotates the array in one of three different ways:
1087 * Rotate by 90 degrees clockwise (rotateCode = ROTATE_90_CLOCKWISE).
1088 * Rotate by 180 degrees clockwise (rotateCode = ROTATE_180).
1089 * Rotate by 270 degrees clockwise (rotateCode = ROTATE_90_COUNTERCLOCKWISE).
1090 @param src input array.
1091 @param dst output array of the same type as src. The size is the same with ROTATE_180,
1092 and the rows and cols are switched for ROTATE_90_CLOCKWISE and ROTATE_90_COUNTERCLOCKWISE.
1093 @param rotateCode an enum to specify how to rotate the array; see the enum #RotateFlags
1094 @sa transpose , repeat , completeSymm, flip, RotateFlags
1096 CV_EXPORTS_W void rotate(InputArray src, OutputArray dst, int rotateCode);
1098 /** @brief Fills the output array with repeated copies of the input array.
1100 The function cv::repeat duplicates the input array one or more times along each of the two axes:
1101 \f[\texttt{dst} _{ij}= \texttt{src} _{i\mod src.rows, \; j\mod src.cols }\f]
1102 The second variant of the function is more convenient to use with @ref MatrixExpressions.
1103 @param src input array to replicate.
1104 @param ny Flag to specify how many times the `src` is repeated along the
1106 @param nx Flag to specify how many times the `src` is repeated along the
1108 @param dst output array of the same type as `src`.
1111 CV_EXPORTS_W void repeat(InputArray src, int ny, int nx, OutputArray dst);
1114 @param src input array to replicate.
1115 @param ny Flag to specify how many times the `src` is repeated along the
1117 @param nx Flag to specify how many times the `src` is repeated along the
1120 CV_EXPORTS Mat repeat(const Mat& src, int ny, int nx);
1122 /** @brief Applies horizontal concatenation to given matrices.
1124 The function horizontally concatenates two or more cv::Mat matrices (with the same number of rows).
1126 cv::Mat matArray[] = { cv::Mat(4, 1, CV_8UC1, cv::Scalar(1)),
1127 cv::Mat(4, 1, CV_8UC1, cv::Scalar(2)),
1128 cv::Mat(4, 1, CV_8UC1, cv::Scalar(3)),};
1131 cv::hconcat( matArray, 3, out );
1138 @param src input array or vector of matrices. all of the matrices must have the same number of rows and the same depth.
1139 @param nsrc number of matrices in src.
1140 @param dst output array. It has the same number of rows and depth as the src, and the sum of cols of the src.
1141 @sa cv::vconcat(const Mat*, size_t, OutputArray), @sa cv::vconcat(InputArrayOfArrays, OutputArray) and @sa cv::vconcat(InputArray, InputArray, OutputArray)
1143 CV_EXPORTS void hconcat(const Mat* src, size_t nsrc, OutputArray dst);
1146 cv::Mat_<float> A = (cv::Mat_<float>(3, 2) << 1, 4,
1149 cv::Mat_<float> B = (cv::Mat_<float>(3, 2) << 7, 10,
1154 cv::hconcat(A, B, C);
1160 @param src1 first input array to be considered for horizontal concatenation.
1161 @param src2 second input array to be considered for horizontal concatenation.
1162 @param dst output array. It has the same number of rows and depth as the src1 and src2, and the sum of cols of the src1 and src2.
1164 CV_EXPORTS void hconcat(InputArray src1, InputArray src2, OutputArray dst);
1167 std::vector<cv::Mat> matrices = { cv::Mat(4, 1, CV_8UC1, cv::Scalar(1)),
1168 cv::Mat(4, 1, CV_8UC1, cv::Scalar(2)),
1169 cv::Mat(4, 1, CV_8UC1, cv::Scalar(3)),};
1172 cv::hconcat( matrices, out );
1179 @param src input array or vector of matrices. all of the matrices must have the same number of rows and the same depth.
1180 @param dst output array. It has the same number of rows and depth as the src, and the sum of cols of the src.
1183 CV_EXPORTS_W void hconcat(InputArrayOfArrays src, OutputArray dst);
1185 /** @brief Applies vertical concatenation to given matrices.
1187 The function vertically concatenates two or more cv::Mat matrices (with the same number of cols).
1189 cv::Mat matArray[] = { cv::Mat(1, 4, CV_8UC1, cv::Scalar(1)),
1190 cv::Mat(1, 4, CV_8UC1, cv::Scalar(2)),
1191 cv::Mat(1, 4, CV_8UC1, cv::Scalar(3)),};
1194 cv::vconcat( matArray, 3, out );
1200 @param src input array or vector of matrices. all of the matrices must have the same number of cols and the same depth.
1201 @param nsrc number of matrices in src.
1202 @param dst output array. It has the same number of cols and depth as the src, and the sum of rows of the src.
1203 @sa cv::hconcat(const Mat*, size_t, OutputArray), @sa cv::hconcat(InputArrayOfArrays, OutputArray) and @sa cv::hconcat(InputArray, InputArray, OutputArray)
1205 CV_EXPORTS void vconcat(const Mat* src, size_t nsrc, OutputArray dst);
1208 cv::Mat_<float> A = (cv::Mat_<float>(3, 2) << 1, 7,
1211 cv::Mat_<float> B = (cv::Mat_<float>(3, 2) << 4, 10,
1216 cv::vconcat(A, B, C);
1225 @param src1 first input array to be considered for vertical concatenation.
1226 @param src2 second input array to be considered for vertical concatenation.
1227 @param dst output array. It has the same number of cols and depth as the src1 and src2, and the sum of rows of the src1 and src2.
1229 CV_EXPORTS void vconcat(InputArray src1, InputArray src2, OutputArray dst);
1232 std::vector<cv::Mat> matrices = { cv::Mat(1, 4, CV_8UC1, cv::Scalar(1)),
1233 cv::Mat(1, 4, CV_8UC1, cv::Scalar(2)),
1234 cv::Mat(1, 4, CV_8UC1, cv::Scalar(3)),};
1237 cv::vconcat( matrices, out );
1243 @param src input array or vector of matrices. all of the matrices must have the same number of cols and the same depth
1244 @param dst output array. It has the same number of cols and depth as the src, and the sum of rows of the src.
1247 CV_EXPORTS_W void vconcat(InputArrayOfArrays src, OutputArray dst);
1249 /** @brief computes bitwise conjunction of the two arrays (dst = src1 & src2)
1250 Calculates the per-element bit-wise conjunction of two arrays or an
1253 The function cv::bitwise_and calculates the per-element bit-wise logical conjunction for:
1254 * Two arrays when src1 and src2 have the same size:
1255 \f[\texttt{dst} (I) = \texttt{src1} (I) \wedge \texttt{src2} (I) \quad \texttt{if mask} (I) \ne0\f]
1256 * An array and a scalar when src2 is constructed from Scalar or has
1257 the same number of elements as `src1.channels()`:
1258 \f[\texttt{dst} (I) = \texttt{src1} (I) \wedge \texttt{src2} \quad \texttt{if mask} (I) \ne0\f]
1259 * A scalar and an array when src1 is constructed from Scalar or has
1260 the same number of elements as `src2.channels()`:
1261 \f[\texttt{dst} (I) = \texttt{src1} \wedge \texttt{src2} (I) \quad \texttt{if mask} (I) \ne0\f]
1262 In case of floating-point arrays, their machine-specific bit
1263 representations (usually IEEE754-compliant) are used for the operation.
1264 In case of multi-channel arrays, each channel is processed
1265 independently. In the second and third cases above, the scalar is first
1266 converted to the array type.
1267 @param src1 first input array or a scalar.
1268 @param src2 second input array or a scalar.
1269 @param dst output array that has the same size and type as the input
1271 @param mask optional operation mask, 8-bit single channel array, that
1272 specifies elements of the output array to be changed.
1274 CV_EXPORTS_W void bitwise_and(InputArray src1, InputArray src2,
1275 OutputArray dst, InputArray mask = noArray());
1277 /** @brief Calculates the per-element bit-wise disjunction of two arrays or an
1280 The function cv::bitwise_or calculates the per-element bit-wise logical disjunction for:
1281 * Two arrays when src1 and src2 have the same size:
1282 \f[\texttt{dst} (I) = \texttt{src1} (I) \vee \texttt{src2} (I) \quad \texttt{if mask} (I) \ne0\f]
1283 * An array and a scalar when src2 is constructed from Scalar or has
1284 the same number of elements as `src1.channels()`:
1285 \f[\texttt{dst} (I) = \texttt{src1} (I) \vee \texttt{src2} \quad \texttt{if mask} (I) \ne0\f]
1286 * A scalar and an array when src1 is constructed from Scalar or has
1287 the same number of elements as `src2.channels()`:
1288 \f[\texttt{dst} (I) = \texttt{src1} \vee \texttt{src2} (I) \quad \texttt{if mask} (I) \ne0\f]
1289 In case of floating-point arrays, their machine-specific bit
1290 representations (usually IEEE754-compliant) are used for the operation.
1291 In case of multi-channel arrays, each channel is processed
1292 independently. In the second and third cases above, the scalar is first
1293 converted to the array type.
1294 @param src1 first input array or a scalar.
1295 @param src2 second input array or a scalar.
1296 @param dst output array that has the same size and type as the input
1298 @param mask optional operation mask, 8-bit single channel array, that
1299 specifies elements of the output array to be changed.
1301 CV_EXPORTS_W void bitwise_or(InputArray src1, InputArray src2,
1302 OutputArray dst, InputArray mask = noArray());
1304 /** @brief Calculates the per-element bit-wise "exclusive or" operation on two
1305 arrays or an array and a scalar.
1307 The function cv::bitwise_xor calculates the per-element bit-wise logical "exclusive-or"
1309 * Two arrays when src1 and src2 have the same size:
1310 \f[\texttt{dst} (I) = \texttt{src1} (I) \oplus \texttt{src2} (I) \quad \texttt{if mask} (I) \ne0\f]
1311 * An array and a scalar when src2 is constructed from Scalar or has
1312 the same number of elements as `src1.channels()`:
1313 \f[\texttt{dst} (I) = \texttt{src1} (I) \oplus \texttt{src2} \quad \texttt{if mask} (I) \ne0\f]
1314 * A scalar and an array when src1 is constructed from Scalar or has
1315 the same number of elements as `src2.channels()`:
1316 \f[\texttt{dst} (I) = \texttt{src1} \oplus \texttt{src2} (I) \quad \texttt{if mask} (I) \ne0\f]
1317 In case of floating-point arrays, their machine-specific bit
1318 representations (usually IEEE754-compliant) are used for the operation.
1319 In case of multi-channel arrays, each channel is processed
1320 independently. In the 2nd and 3rd cases above, the scalar is first
1321 converted to the array type.
1322 @param src1 first input array or a scalar.
1323 @param src2 second input array or a scalar.
1324 @param dst output array that has the same size and type as the input
1326 @param mask optional operation mask, 8-bit single channel array, that
1327 specifies elements of the output array to be changed.
1329 CV_EXPORTS_W void bitwise_xor(InputArray src1, InputArray src2,
1330 OutputArray dst, InputArray mask = noArray());
1332 /** @brief Inverts every bit of an array.
1334 The function cv::bitwise_not calculates per-element bit-wise inversion of the input
1336 \f[\texttt{dst} (I) = \neg \texttt{src} (I)\f]
1337 In case of a floating-point input array, its machine-specific bit
1338 representation (usually IEEE754-compliant) is used for the operation. In
1339 case of multi-channel arrays, each channel is processed independently.
1340 @param src input array.
1341 @param dst output array that has the same size and type as the input
1343 @param mask optional operation mask, 8-bit single channel array, that
1344 specifies elements of the output array to be changed.
1346 CV_EXPORTS_W void bitwise_not(InputArray src, OutputArray dst,
1347 InputArray mask = noArray());
1349 /** @brief Calculates the per-element absolute difference between two arrays or between an array and a scalar.
1351 The function cv::absdiff calculates:
1352 * Absolute difference between two arrays when they have the same
1354 \f[\texttt{dst}(I) = \texttt{saturate} (| \texttt{src1}(I) - \texttt{src2}(I)|)\f]
1355 * Absolute difference between an array and a scalar when the second
1356 array is constructed from Scalar or has as many elements as the
1357 number of channels in `src1`:
1358 \f[\texttt{dst}(I) = \texttt{saturate} (| \texttt{src1}(I) - \texttt{src2} |)\f]
1359 * Absolute difference between a scalar and an array when the first
1360 array is constructed from Scalar or has as many elements as the
1361 number of channels in `src2`:
1362 \f[\texttt{dst}(I) = \texttt{saturate} (| \texttt{src1} - \texttt{src2}(I) |)\f]
1363 where I is a multi-dimensional index of array elements. In case of
1364 multi-channel arrays, each channel is processed independently.
1365 @note Saturation is not applied when the arrays have the depth CV_32S.
1366 You may even get a negative value in the case of overflow.
1367 @param src1 first input array or a scalar.
1368 @param src2 second input array or a scalar.
1369 @param dst output array that has the same size and type as input arrays.
1370 @sa cv::abs(const Mat&)
1372 CV_EXPORTS_W void absdiff(InputArray src1, InputArray src2, OutputArray dst);
1374 /** @brief Checks if array elements lie between the elements of two other arrays.
1376 The function checks the range as follows:
1377 - For every element of a single-channel input array:
1378 \f[\texttt{dst} (I)= \texttt{lowerb} (I)_0 \leq \texttt{src} (I)_0 \leq \texttt{upperb} (I)_0\f]
1379 - For two-channel arrays:
1380 \f[\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\f]
1383 That is, dst (I) is set to 255 (all 1 -bits) if src (I) is within the
1384 specified 1D, 2D, 3D, ... box and 0 otherwise.
1386 When the lower and/or upper boundary parameters are scalars, the indexes
1387 (I) at lowerb and upperb in the above formulas should be omitted.
1388 @param src first input array.
1389 @param lowerb inclusive lower boundary array or a scalar.
1390 @param upperb inclusive upper boundary array or a scalar.
1391 @param dst output array of the same size as src and CV_8U type.
1393 CV_EXPORTS_W void inRange(InputArray src, InputArray lowerb,
1394 InputArray upperb, OutputArray dst);
1396 /** @brief Performs the per-element comparison of two arrays or an array and scalar value.
1398 The function compares:
1399 * Elements of two arrays when src1 and src2 have the same size:
1400 \f[\texttt{dst} (I) = \texttt{src1} (I) \,\texttt{cmpop}\, \texttt{src2} (I)\f]
1401 * Elements of src1 with a scalar src2 when src2 is constructed from
1402 Scalar or has a single element:
1403 \f[\texttt{dst} (I) = \texttt{src1}(I) \,\texttt{cmpop}\, \texttt{src2}\f]
1404 * src1 with elements of src2 when src1 is constructed from Scalar or
1405 has a single element:
1406 \f[\texttt{dst} (I) = \texttt{src1} \,\texttt{cmpop}\, \texttt{src2} (I)\f]
1407 When the comparison result is true, the corresponding element of output
1408 array is set to 255. The comparison operations can be replaced with the
1409 equivalent matrix expressions:
1411 Mat dst1 = src1 >= src2;
1412 Mat dst2 = src1 < 8;
1415 @param src1 first input array or a scalar; when it is an array, it must have a single channel.
1416 @param src2 second input array or a scalar; when it is an array, it must have a single channel.
1417 @param dst output array of type ref CV_8U that has the same size and the same number of channels as
1419 @param cmpop a flag, that specifies correspondence between the arrays (cv::CmpTypes)
1420 @sa checkRange, min, max, threshold
1422 CV_EXPORTS_W void compare(InputArray src1, InputArray src2, OutputArray dst, int cmpop);
1424 /** @brief Calculates per-element minimum of two arrays or an array and a scalar.
1426 The function cv::min calculates the per-element minimum of two arrays:
1427 \f[\texttt{dst} (I)= \min ( \texttt{src1} (I), \texttt{src2} (I))\f]
1428 or array and a scalar:
1429 \f[\texttt{dst} (I)= \min ( \texttt{src1} (I), \texttt{value} )\f]
1430 @param src1 first input array.
1431 @param src2 second input array of the same size and type as src1.
1432 @param dst output array of the same size and type as src1.
1433 @sa max, compare, inRange, minMaxLoc
1435 CV_EXPORTS_W void min(InputArray src1, InputArray src2, OutputArray dst);
1437 needed to avoid conflicts with const _Tp& std::min(const _Tp&, const _Tp&, _Compare)
1439 CV_EXPORTS void min(const Mat& src1, const Mat& src2, Mat& dst);
1441 needed to avoid conflicts with const _Tp& std::min(const _Tp&, const _Tp&, _Compare)
1443 CV_EXPORTS void min(const UMat& src1, const UMat& src2, UMat& dst);
1445 /** @brief Calculates per-element maximum of two arrays or an array and a scalar.
1447 The function cv::max calculates the per-element maximum of two arrays:
1448 \f[\texttt{dst} (I)= \max ( \texttt{src1} (I), \texttt{src2} (I))\f]
1449 or array and a scalar:
1450 \f[\texttt{dst} (I)= \max ( \texttt{src1} (I), \texttt{value} )\f]
1451 @param src1 first input array.
1452 @param src2 second input array of the same size and type as src1 .
1453 @param dst output array of the same size and type as src1.
1454 @sa min, compare, inRange, minMaxLoc, @ref MatrixExpressions
1456 CV_EXPORTS_W void max(InputArray src1, InputArray src2, OutputArray dst);
1458 needed to avoid conflicts with const _Tp& std::min(const _Tp&, const _Tp&, _Compare)
1460 CV_EXPORTS void max(const Mat& src1, const Mat& src2, Mat& dst);
1462 needed to avoid conflicts with const _Tp& std::min(const _Tp&, const _Tp&, _Compare)
1464 CV_EXPORTS void max(const UMat& src1, const UMat& src2, UMat& dst);
1466 /** @brief Calculates a square root of array elements.
1468 The function cv::sqrt calculates a square root of each input array element.
1469 In case of multi-channel arrays, each channel is processed
1470 independently. The accuracy is approximately the same as of the built-in
1472 @param src input floating-point array.
1473 @param dst output array of the same size and type as src.
1475 CV_EXPORTS_W void sqrt(InputArray src, OutputArray dst);
1477 /** @brief Raises every array element to a power.
1479 The function cv::pow raises every element of the input array to power :
1480 \f[\texttt{dst} (I) = \fork{\texttt{src}(I)^{power}}{if \(\texttt{power}\) is integer}{|\texttt{src}(I)|^{power}}{otherwise}\f]
1482 So, for a non-integer power exponent, the absolute values of input array
1483 elements are used. However, it is possible to get true values for
1484 negative values using some extra operations. In the example below,
1485 computing the 5th root of array src shows:
1488 pow(src, 1./5, dst);
1489 subtract(Scalar::all(0), dst, dst, mask);
1491 For some values of power, such as integer values, 0.5 and -0.5,
1492 specialized faster algorithms are used.
1494 Special values (NaN, Inf) are not handled.
1495 @param src input array.
1496 @param power exponent of power.
1497 @param dst output array of the same size and type as src.
1498 @sa sqrt, exp, log, cartToPolar, polarToCart
1500 CV_EXPORTS_W void pow(InputArray src, double power, OutputArray dst);
1502 /** @brief Calculates the exponent of every array element.
1504 The function cv::exp calculates the exponent of every element of the input
1506 \f[\texttt{dst} [I] = e^{ src(I) }\f]
1508 The maximum relative error is about 7e-6 for single-precision input and
1509 less than 1e-10 for double-precision input. Currently, the function
1510 converts denormalized values to zeros on output. Special values (NaN,
1511 Inf) are not handled.
1512 @param src input array.
1513 @param dst output array of the same size and type as src.
1514 @sa log , cartToPolar , polarToCart , phase , pow , sqrt , magnitude
1516 CV_EXPORTS_W void exp(InputArray src, OutputArray dst);
1518 /** @brief Calculates the natural logarithm of every array element.
1520 The function cv::log calculates the natural logarithm of every element of the input array:
1521 \f[\texttt{dst} (I) = \log (\texttt{src}(I)) \f]
1523 Output on zero, negative and special (NaN, Inf) values is undefined.
1525 @param src input array.
1526 @param dst output array of the same size and type as src .
1527 @sa exp, cartToPolar, polarToCart, phase, pow, sqrt, magnitude
1529 CV_EXPORTS_W void log(InputArray src, OutputArray dst);
1531 /** @brief Calculates x and y coordinates of 2D vectors from their magnitude and angle.
1533 The function cv::polarToCart calculates the Cartesian coordinates of each 2D
1534 vector represented by the corresponding elements of magnitude and angle:
1535 \f[\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}\f]
1537 The relative accuracy of the estimated coordinates is about 1e-6.
1538 @param magnitude input floating-point array of magnitudes of 2D vectors;
1539 it can be an empty matrix (=Mat()), in this case, the function assumes
1540 that all the magnitudes are =1; if it is not empty, it must have the
1541 same size and type as angle.
1542 @param angle input floating-point array of angles of 2D vectors.
1543 @param x output array of x-coordinates of 2D vectors; it has the same
1544 size and type as angle.
1545 @param y output array of y-coordinates of 2D vectors; it has the same
1546 size and type as angle.
1547 @param angleInDegrees when true, the input angles are measured in
1548 degrees, otherwise, they are measured in radians.
1549 @sa cartToPolar, magnitude, phase, exp, log, pow, sqrt
1551 CV_EXPORTS_W void polarToCart(InputArray magnitude, InputArray angle,
1552 OutputArray x, OutputArray y, bool angleInDegrees = false);
1554 /** @brief Calculates the magnitude and angle of 2D vectors.
1556 The function cv::cartToPolar calculates either the magnitude, angle, or both
1557 for every 2D vector (x(I),y(I)):
1558 \f[\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}\f]
1560 The angles are calculated with accuracy about 0.3 degrees. For the point
1561 (0,0), the angle is set to 0.
1562 @param x array of x-coordinates; this must be a single-precision or
1563 double-precision floating-point array.
1564 @param y array of y-coordinates, that must have the same size and same type as x.
1565 @param magnitude output array of magnitudes of the same size and type as x.
1566 @param angle output array of angles that has the same size and type as
1567 x; the angles are measured in radians (from 0 to 2\*Pi) or in degrees (0 to 360 degrees).
1568 @param angleInDegrees a flag, indicating whether the angles are measured
1569 in radians (which is by default), or in degrees.
1572 CV_EXPORTS_W void cartToPolar(InputArray x, InputArray y,
1573 OutputArray magnitude, OutputArray angle,
1574 bool angleInDegrees = false);
1576 /** @brief Calculates the rotation angle of 2D vectors.
1578 The function cv::phase calculates the rotation angle of each 2D vector that
1579 is formed from the corresponding elements of x and y :
1580 \f[\texttt{angle} (I) = \texttt{atan2} ( \texttt{y} (I), \texttt{x} (I))\f]
1582 The angle estimation accuracy is about 0.3 degrees. When x(I)=y(I)=0 ,
1583 the corresponding angle(I) is set to 0.
1584 @param x input floating-point array of x-coordinates of 2D vectors.
1585 @param y input array of y-coordinates of 2D vectors; it must have the
1586 same size and the same type as x.
1587 @param angle output array of vector angles; it has the same size and
1589 @param angleInDegrees when true, the function calculates the angle in
1590 degrees, otherwise, they are measured in radians.
1592 CV_EXPORTS_W void phase(InputArray x, InputArray y, OutputArray angle,
1593 bool angleInDegrees = false);
1595 /** @brief Calculates the magnitude of 2D vectors.
1597 The function cv::magnitude calculates the magnitude of 2D vectors formed
1598 from the corresponding elements of x and y arrays:
1599 \f[\texttt{dst} (I) = \sqrt{\texttt{x}(I)^2 + \texttt{y}(I)^2}\f]
1600 @param x floating-point array of x-coordinates of the vectors.
1601 @param y floating-point array of y-coordinates of the vectors; it must
1602 have the same size as x.
1603 @param magnitude output array of the same size and type as x.
1604 @sa cartToPolar, polarToCart, phase, sqrt
1606 CV_EXPORTS_W void magnitude(InputArray x, InputArray y, OutputArray magnitude);
1608 /** @brief Checks every element of an input array for invalid values.
1610 The function cv::checkRange checks that every array element is neither NaN nor infinite. When minVal \>
1611 -DBL_MAX and maxVal \< DBL_MAX, the function also checks that each value is between minVal and
1612 maxVal. In case of multi-channel arrays, each channel is processed independently. If some values
1613 are out of range, position of the first outlier is stored in pos (when pos != NULL). Then, the
1614 function either returns false (when quiet=true) or throws an exception.
1615 @param a input array.
1616 @param quiet a flag, indicating whether the functions quietly return false when the array elements
1617 are out of range or they throw an exception.
1618 @param pos optional output parameter, when not NULL, must be a pointer to array of src.dims
1620 @param minVal inclusive lower boundary of valid values range.
1621 @param maxVal exclusive upper boundary of valid values range.
1623 CV_EXPORTS_W bool checkRange(InputArray a, bool quiet = true, CV_OUT Point* pos = 0,
1624 double minVal = -DBL_MAX, double maxVal = DBL_MAX);
1626 /** @brief converts NaNs to the given number
1627 @param a input/output matrix (CV_32F type).
1628 @param val value to convert the NaNs
1630 CV_EXPORTS_W void patchNaNs(InputOutputArray a, double val = 0);
1632 /** @brief Performs generalized matrix multiplication.
1634 The function cv::gemm performs generalized matrix multiplication similar to the
1635 gemm functions in BLAS level 3. For example,
1636 `gemm(src1, src2, alpha, src3, beta, dst, GEMM_1_T + GEMM_3_T)`
1638 \f[\texttt{dst} = \texttt{alpha} \cdot \texttt{src1} ^T \cdot \texttt{src2} + \texttt{beta} \cdot \texttt{src3} ^T\f]
1640 In case of complex (two-channel) data, performed a complex matrix
1643 The function can be replaced with a matrix expression. For example, the
1644 above call can be replaced with:
1646 dst = alpha*src1.t()*src2 + beta*src3.t();
1648 @param src1 first multiplied input matrix that could be real(CV_32FC1,
1649 CV_64FC1) or complex(CV_32FC2, CV_64FC2).
1650 @param src2 second multiplied input matrix of the same type as src1.
1651 @param alpha weight of the matrix product.
1652 @param src3 third optional delta matrix added to the matrix product; it
1653 should have the same type as src1 and src2.
1654 @param beta weight of src3.
1655 @param dst output matrix; it has the proper size and the same type as
1657 @param flags operation flags (cv::GemmFlags)
1658 @sa mulTransposed , transform
1660 CV_EXPORTS_W void gemm(InputArray src1, InputArray src2, double alpha,
1661 InputArray src3, double beta, OutputArray dst, int flags = 0);
1663 /** @brief Calculates the product of a matrix and its transposition.
1665 The function cv::mulTransposed calculates the product of src and its
1667 \f[\texttt{dst} = \texttt{scale} ( \texttt{src} - \texttt{delta} )^T ( \texttt{src} - \texttt{delta} )\f]
1669 \f[\texttt{dst} = \texttt{scale} ( \texttt{src} - \texttt{delta} ) ( \texttt{src} - \texttt{delta} )^T\f]
1670 otherwise. The function is used to calculate the covariance matrix. With
1671 zero delta, it can be used as a faster substitute for general matrix
1672 product A\*B when B=A'
1673 @param src input single-channel matrix. Note that unlike gemm, the
1674 function can multiply not only floating-point matrices.
1675 @param dst output square matrix.
1676 @param aTa Flag specifying the multiplication ordering. See the
1678 @param delta Optional delta matrix subtracted from src before the
1679 multiplication. When the matrix is empty ( delta=noArray() ), it is
1680 assumed to be zero, that is, nothing is subtracted. If it has the same
1681 size as src , it is simply subtracted. Otherwise, it is "repeated" (see
1682 repeat ) to cover the full src and then subtracted. Type of the delta
1683 matrix, when it is not empty, must be the same as the type of created
1684 output matrix. See the dtype parameter description below.
1685 @param scale Optional scale factor for the matrix product.
1686 @param dtype Optional type of the output matrix. When it is negative,
1687 the output matrix will have the same type as src . Otherwise, it will be
1688 type=CV_MAT_DEPTH(dtype) that should be either CV_32F or CV_64F .
1689 @sa calcCovarMatrix, gemm, repeat, reduce
1691 CV_EXPORTS_W void mulTransposed( InputArray src, OutputArray dst, bool aTa,
1692 InputArray delta = noArray(),
1693 double scale = 1, int dtype = -1 );
1695 /** @brief Transposes a matrix.
1697 The function cv::transpose transposes the matrix src :
1698 \f[\texttt{dst} (i,j) = \texttt{src} (j,i)\f]
1699 @note No complex conjugation is done in case of a complex matrix. It
1700 should be done separately if needed.
1701 @param src input array.
1702 @param dst output array of the same type as src.
1704 CV_EXPORTS_W void transpose(InputArray src, OutputArray dst);
1706 /** @brief Performs the matrix transformation of every array element.
1708 The function cv::transform performs the matrix transformation of every
1709 element of the array src and stores the results in dst :
1710 \f[\texttt{dst} (I) = \texttt{m} \cdot \texttt{src} (I)\f]
1711 (when m.cols=src.channels() ), or
1712 \f[\texttt{dst} (I) = \texttt{m} \cdot [ \texttt{src} (I); 1]\f]
1713 (when m.cols=src.channels()+1 )
1715 Every element of the N -channel array src is interpreted as N -element
1716 vector that is transformed using the M x N or M x (N+1) matrix m to
1717 M-element vector - the corresponding element of the output array dst .
1719 The function may be used for geometrical transformation of
1720 N -dimensional points, arbitrary linear color space transformation (such
1721 as various kinds of RGB to YUV transforms), shuffling the image
1722 channels, and so forth.
1723 @param src input array that must have as many channels (1 to 4) as
1725 @param dst output array of the same size and depth as src; it has as
1726 many channels as m.rows.
1727 @param m transformation 2x2 or 2x3 floating-point matrix.
1728 @sa perspectiveTransform, getAffineTransform, estimateAffine2D, warpAffine, warpPerspective
1730 CV_EXPORTS_W void transform(InputArray src, OutputArray dst, InputArray m );
1732 /** @brief Performs the perspective matrix transformation of vectors.
1734 The function cv::perspectiveTransform transforms every element of src by
1735 treating it as a 2D or 3D vector, in the following way:
1736 \f[(x, y, z) \rightarrow (x'/w, y'/w, z'/w)\f]
1738 \f[(x', y', z', w') = \texttt{mat} \cdot \begin{bmatrix} x & y & z & 1 \end{bmatrix}\f]
1740 \f[w = \fork{w'}{if \(w' \ne 0\)}{\infty}{otherwise}\f]
1742 Here a 3D vector transformation is shown. In case of a 2D vector
1743 transformation, the z component is omitted.
1745 @note The function transforms a sparse set of 2D or 3D vectors. If you
1746 want to transform an image using perspective transformation, use
1747 warpPerspective . If you have an inverse problem, that is, you want to
1748 compute the most probable perspective transformation out of several
1749 pairs of corresponding points, you can use getPerspectiveTransform or
1751 @param src input two-channel or three-channel floating-point array; each
1752 element is a 2D/3D vector to be transformed.
1753 @param dst output array of the same size and type as src.
1754 @param m 3x3 or 4x4 floating-point transformation matrix.
1755 @sa transform, warpPerspective, getPerspectiveTransform, findHomography
1757 CV_EXPORTS_W void perspectiveTransform(InputArray src, OutputArray dst, InputArray m );
1759 /** @brief Copies the lower or the upper half of a square matrix to its another half.
1761 The function cv::completeSymm copies the lower or the upper half of a square matrix to
1762 its another half. The matrix diagonal remains unchanged:
1763 - \f$\texttt{m}_{ij}=\texttt{m}_{ji}\f$ for \f$i > j\f$ if
1765 - \f$\texttt{m}_{ij}=\texttt{m}_{ji}\f$ for \f$i < j\f$ if
1768 @param m input-output floating-point square matrix.
1769 @param lowerToUpper operation flag; if true, the lower half is copied to
1770 the upper half. Otherwise, the upper half is copied to the lower half.
1773 CV_EXPORTS_W void completeSymm(InputOutputArray m, bool lowerToUpper = false);
1775 /** @brief Initializes a scaled identity matrix.
1777 The function cv::setIdentity initializes a scaled identity matrix:
1778 \f[\texttt{mtx} (i,j)= \fork{\texttt{value}}{ if \(i=j\)}{0}{otherwise}\f]
1780 The function can also be emulated using the matrix initializers and the
1783 Mat A = Mat::eye(4, 3, CV_32F)*5;
1784 // A will be set to [[5, 0, 0], [0, 5, 0], [0, 0, 5], [0, 0, 0]]
1786 @param mtx matrix to initialize (not necessarily square).
1787 @param s value to assign to diagonal elements.
1788 @sa Mat::zeros, Mat::ones, Mat::setTo, Mat::operator=
1790 CV_EXPORTS_W void setIdentity(InputOutputArray mtx, const Scalar& s = Scalar(1));
1792 /** @brief Returns the determinant of a square floating-point matrix.
1794 The function cv::determinant calculates and returns the determinant of the
1795 specified matrix. For small matrices ( mtx.cols=mtx.rows\<=3 ), the
1796 direct method is used. For larger matrices, the function uses LU
1797 factorization with partial pivoting.
1799 For symmetric positively-determined matrices, it is also possible to use
1800 eigen decomposition to calculate the determinant.
1801 @param mtx input matrix that must have CV_32FC1 or CV_64FC1 type and
1803 @sa trace, invert, solve, eigen, @ref MatrixExpressions
1805 CV_EXPORTS_W double determinant(InputArray mtx);
1807 /** @brief Returns the trace of a matrix.
1809 The function cv::trace returns the sum of the diagonal elements of the
1811 \f[\mathrm{tr} ( \texttt{mtx} ) = \sum _i \texttt{mtx} (i,i)\f]
1812 @param mtx input matrix.
1814 CV_EXPORTS_W Scalar trace(InputArray mtx);
1816 /** @brief Finds the inverse or pseudo-inverse of a matrix.
1818 The function cv::invert inverts the matrix src and stores the result in dst
1819 . When the matrix src is singular or non-square, the function calculates
1820 the pseudo-inverse matrix (the dst matrix) so that norm(src\*dst - I) is
1821 minimal, where I is an identity matrix.
1823 In case of the #DECOMP_LU method, the function returns non-zero value if
1824 the inverse has been successfully calculated and 0 if src is singular.
1826 In case of the #DECOMP_SVD method, the function returns the inverse
1827 condition number of src (the ratio of the smallest singular value to the
1828 largest singular value) and 0 if src is singular. The SVD method
1829 calculates a pseudo-inverse matrix if src is singular.
1831 Similarly to #DECOMP_LU, the method #DECOMP_CHOLESKY works only with
1832 non-singular square matrices that should also be symmetrical and
1833 positively defined. In this case, the function stores the inverted
1834 matrix in dst and returns non-zero. Otherwise, it returns 0.
1836 @param src input floating-point M x N matrix.
1837 @param dst output matrix of N x M size and the same type as src.
1838 @param flags inversion method (cv::DecompTypes)
1841 CV_EXPORTS_W double invert(InputArray src, OutputArray dst, int flags = DECOMP_LU);
1843 /** @brief Solves one or more linear systems or least-squares problems.
1845 The function cv::solve solves a linear system or least-squares problem (the
1846 latter is possible with SVD or QR methods, or by specifying the flag
1848 \f[\texttt{dst} = \arg \min _X \| \texttt{src1} \cdot \texttt{X} - \texttt{src2} \|\f]
1850 If #DECOMP_LU or #DECOMP_CHOLESKY method is used, the function returns 1
1851 if src1 (or \f$\texttt{src1}^T\texttt{src1}\f$ ) is non-singular. Otherwise,
1852 it returns 0. In the latter case, dst is not valid. Other methods find a
1853 pseudo-solution in case of a singular left-hand side part.
1855 @note If you want to find a unity-norm solution of an under-defined
1856 singular system \f$\texttt{src1}\cdot\texttt{dst}=0\f$ , the function solve
1857 will not do the work. Use SVD::solveZ instead.
1859 @param src1 input matrix on the left-hand side of the system.
1860 @param src2 input matrix on the right-hand side of the system.
1861 @param dst output solution.
1862 @param flags solution (matrix inversion) method (#DecompTypes)
1863 @sa invert, SVD, eigen
1865 CV_EXPORTS_W bool solve(InputArray src1, InputArray src2,
1866 OutputArray dst, int flags = DECOMP_LU);
1868 /** @brief Sorts each row or each column of a matrix.
1870 The function cv::sort sorts each matrix row or each matrix column in
1871 ascending or descending order. So you should pass two operation flags to
1872 get desired behaviour. If you want to sort matrix rows or columns
1873 lexicographically, you can use STL std::sort generic function with the
1874 proper comparison predicate.
1876 @param src input single-channel array.
1877 @param dst output array of the same size and type as src.
1878 @param flags operation flags, a combination of #SortFlags
1879 @sa sortIdx, randShuffle
1881 CV_EXPORTS_W void sort(InputArray src, OutputArray dst, int flags);
1883 /** @brief Sorts each row or each column of a matrix.
1885 The function cv::sortIdx sorts each matrix row or each matrix column in the
1886 ascending or descending order. So you should pass two operation flags to
1887 get desired behaviour. Instead of reordering the elements themselves, it
1888 stores the indices of sorted elements in the output array. For example:
1890 Mat A = Mat::eye(3,3,CV_32F), B;
1891 sortIdx(A, B, SORT_EVERY_ROW + SORT_ASCENDING);
1892 // B will probably contain
1893 // (because of equal elements in A some permutations are possible):
1894 // [[1, 2, 0], [0, 2, 1], [0, 1, 2]]
1896 @param src input single-channel array.
1897 @param dst output integer array of the same size as src.
1898 @param flags operation flags that could be a combination of cv::SortFlags
1899 @sa sort, randShuffle
1901 CV_EXPORTS_W void sortIdx(InputArray src, OutputArray dst, int flags);
1903 /** @brief Finds the real roots of a cubic equation.
1905 The function solveCubic finds the real roots of a cubic equation:
1906 - if coeffs is a 4-element vector:
1907 \f[\texttt{coeffs} [0] x^3 + \texttt{coeffs} [1] x^2 + \texttt{coeffs} [2] x + \texttt{coeffs} [3] = 0\f]
1908 - if coeffs is a 3-element vector:
1909 \f[x^3 + \texttt{coeffs} [0] x^2 + \texttt{coeffs} [1] x + \texttt{coeffs} [2] = 0\f]
1911 The roots are stored in the roots array.
1912 @param coeffs equation coefficients, an array of 3 or 4 elements.
1913 @param roots output array of real roots that has 1 or 3 elements.
1914 @return number of real roots. It can be 0, 1 or 2.
1916 CV_EXPORTS_W int solveCubic(InputArray coeffs, OutputArray roots);
1918 /** @brief Finds the real or complex roots of a polynomial equation.
1920 The function cv::solvePoly finds real and complex roots of a polynomial equation:
1921 \f[\texttt{coeffs} [n] x^{n} + \texttt{coeffs} [n-1] x^{n-1} + ... + \texttt{coeffs} [1] x + \texttt{coeffs} [0] = 0\f]
1922 @param coeffs array of polynomial coefficients.
1923 @param roots output (complex) array of roots.
1924 @param maxIters maximum number of iterations the algorithm does.
1926 CV_EXPORTS_W double solvePoly(InputArray coeffs, OutputArray roots, int maxIters = 300);
1928 /** @brief Calculates eigenvalues and eigenvectors of a symmetric matrix.
1930 The function cv::eigen calculates just eigenvalues, or eigenvalues and eigenvectors of the symmetric
1933 src*eigenvectors.row(i).t() = eigenvalues.at<srcType>(i)*eigenvectors.row(i).t()
1936 @note Use cv::eigenNonSymmetric for calculation of real eigenvalues and eigenvectors of non-symmetric matrix.
1938 @param src input matrix that must have CV_32FC1 or CV_64FC1 type, square size and be symmetrical
1940 @param eigenvalues output vector of eigenvalues of the same type as src; the eigenvalues are stored
1941 in the descending order.
1942 @param eigenvectors output matrix of eigenvectors; it has the same size and type as src; the
1943 eigenvectors are stored as subsequent matrix rows, in the same order as the corresponding
1945 @sa eigenNonSymmetric, completeSymm , PCA
1947 CV_EXPORTS_W bool eigen(InputArray src, OutputArray eigenvalues,
1948 OutputArray eigenvectors = noArray());
1950 /** @brief Calculates eigenvalues and eigenvectors of a non-symmetric matrix (real eigenvalues only).
1952 @note Assumes real eigenvalues.
1954 The function calculates eigenvalues and eigenvectors (optional) of the square matrix src:
1956 src*eigenvectors.row(i).t() = eigenvalues.at<srcType>(i)*eigenvectors.row(i).t()
1959 @param src input matrix (CV_32FC1 or CV_64FC1 type).
1960 @param eigenvalues output vector of eigenvalues (type is the same type as src).
1961 @param eigenvectors output matrix of eigenvectors (type is the same type as src). The eigenvectors are stored as subsequent matrix rows, in the same order as the corresponding eigenvalues.
1964 CV_EXPORTS_W void eigenNonSymmetric(InputArray src, OutputArray eigenvalues,
1965 OutputArray eigenvectors);
1967 /** @brief Calculates the covariance matrix of a set of vectors.
1969 The function cv::calcCovarMatrix calculates the covariance matrix and, optionally, the mean vector of
1970 the set of input vectors.
1971 @param samples samples stored as separate matrices
1972 @param nsamples number of samples
1973 @param covar output covariance matrix of the type ctype and square size.
1974 @param mean input or output (depending on the flags) array as the average value of the input vectors.
1975 @param flags operation flags as a combination of #CovarFlags
1976 @param ctype type of the matrixl; it equals 'CV_64F' by default.
1977 @sa PCA, mulTransposed, Mahalanobis
1978 @todo InputArrayOfArrays
1980 CV_EXPORTS void calcCovarMatrix( const Mat* samples, int nsamples, Mat& covar, Mat& mean,
1981 int flags, int ctype = CV_64F);
1984 @note use #COVAR_ROWS or #COVAR_COLS flag
1985 @param samples samples stored as rows/columns of a single matrix.
1986 @param covar output covariance matrix of the type ctype and square size.
1987 @param mean input or output (depending on the flags) array as the average value of the input vectors.
1988 @param flags operation flags as a combination of #CovarFlags
1989 @param ctype type of the matrixl; it equals 'CV_64F' by default.
1991 CV_EXPORTS_W void calcCovarMatrix( InputArray samples, OutputArray covar,
1992 InputOutputArray mean, int flags, int ctype = CV_64F);
1994 /** wrap PCA::operator() */
1995 CV_EXPORTS_W void PCACompute(InputArray data, InputOutputArray mean,
1996 OutputArray eigenvectors, int maxComponents = 0);
1998 /** wrap PCA::operator() and add eigenvalues output parameter */
1999 CV_EXPORTS_AS(PCACompute2) void PCACompute(InputArray data, InputOutputArray mean,
2000 OutputArray eigenvectors, OutputArray eigenvalues,
2001 int maxComponents = 0);
2003 /** wrap PCA::operator() */
2004 CV_EXPORTS_W void PCACompute(InputArray data, InputOutputArray mean,
2005 OutputArray eigenvectors, double retainedVariance);
2007 /** wrap PCA::operator() and add eigenvalues output parameter */
2008 CV_EXPORTS_AS(PCACompute2) void PCACompute(InputArray data, InputOutputArray mean,
2009 OutputArray eigenvectors, OutputArray eigenvalues,
2010 double retainedVariance);
2012 /** wrap PCA::project */
2013 CV_EXPORTS_W void PCAProject(InputArray data, InputArray mean,
2014 InputArray eigenvectors, OutputArray result);
2016 /** wrap PCA::backProject */
2017 CV_EXPORTS_W void PCABackProject(InputArray data, InputArray mean,
2018 InputArray eigenvectors, OutputArray result);
2020 /** wrap SVD::compute */
2021 CV_EXPORTS_W void SVDecomp( InputArray src, OutputArray w, OutputArray u, OutputArray vt, int flags = 0 );
2023 /** wrap SVD::backSubst */
2024 CV_EXPORTS_W void SVBackSubst( InputArray w, InputArray u, InputArray vt,
2025 InputArray rhs, OutputArray dst );
2027 /** @brief Calculates the Mahalanobis distance between two vectors.
2029 The function cv::Mahalanobis calculates and returns the weighted distance between two vectors:
2030 \f[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)})} }\f]
2031 The covariance matrix may be calculated using the #calcCovarMatrix function and then inverted using
2032 the invert function (preferably using the #DECOMP_SVD method, as the most accurate).
2033 @param v1 first 1D input vector.
2034 @param v2 second 1D input vector.
2035 @param icovar inverse covariance matrix.
2037 CV_EXPORTS_W double Mahalanobis(InputArray v1, InputArray v2, InputArray icovar);
2039 /** @brief Performs a forward or inverse Discrete Fourier transform of a 1D or 2D floating-point array.
2041 The function cv::dft performs one of the following:
2042 - Forward the Fourier transform of a 1D vector of N elements:
2043 \f[Y = F^{(N)} \cdot X,\f]
2044 where \f$F^{(N)}_{jk}=\exp(-2\pi i j k/N)\f$ and \f$i=\sqrt{-1}\f$
2045 - Inverse the Fourier transform of a 1D vector of N elements:
2046 \f[\begin{array}{l} X'= \left (F^{(N)} \right )^{-1} \cdot Y = \left (F^{(N)} \right )^* \cdot y \\ X = (1/N) \cdot X, \end{array}\f]
2047 where \f$F^*=\left(\textrm{Re}(F^{(N)})-\textrm{Im}(F^{(N)})\right)^T\f$
2048 - Forward the 2D Fourier transform of a M x N matrix:
2049 \f[Y = F^{(M)} \cdot X \cdot F^{(N)}\f]
2050 - Inverse the 2D Fourier transform of a M x N matrix:
2051 \f[\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}\f]
2053 In case of real (single-channel) data, the output spectrum of the forward Fourier transform or input
2054 spectrum of the inverse Fourier transform can be represented in a packed format called *CCS*
2055 (complex-conjugate-symmetrical). It was borrowed from IPL (Intel\* Image Processing Library). Here
2056 is how 2D *CCS* spectrum looks:
2057 \f[\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}\f]
2059 In case of 1D transform of a real vector, the output looks like the first row of the matrix above.
2061 So, the function chooses an operation mode depending on the flags and size of the input array:
2062 - If #DFT_ROWS is set or the input array has a single row or single column, the function
2063 performs a 1D forward or inverse transform of each row of a matrix when #DFT_ROWS is set.
2064 Otherwise, it performs a 2D transform.
2065 - If the input array is real and #DFT_INVERSE is not set, the function performs a forward 1D or
2067 - When #DFT_COMPLEX_OUTPUT is set, the output is a complex matrix of the same size as
2069 - When #DFT_COMPLEX_OUTPUT is not set, the output is a real matrix of the same size as
2070 input. In case of 2D transform, it uses the packed format as shown above. In case of a
2071 single 1D transform, it looks like the first row of the matrix above. In case of
2072 multiple 1D transforms (when using the #DFT_ROWS flag), each row of the output matrix
2073 looks like the first row of the matrix above.
2074 - If the input array is complex and either #DFT_INVERSE or #DFT_REAL_OUTPUT are not set, the
2075 output is a complex array of the same size as input. The function performs a forward or
2076 inverse 1D or 2D transform of the whole input array or each row of the input array
2077 independently, depending on the flags DFT_INVERSE and DFT_ROWS.
2078 - When #DFT_INVERSE is set and the input array is real, or it is complex but #DFT_REAL_OUTPUT
2079 is set, the output is a real array of the same size as input. The function performs a 1D or 2D
2080 inverse transformation of the whole input array or each individual row, depending on the flags
2081 #DFT_INVERSE and #DFT_ROWS.
2083 If #DFT_SCALE is set, the scaling is done after the transformation.
2085 Unlike dct , the function supports arrays of arbitrary size. But only those arrays are processed
2086 efficiently, whose sizes can be factorized in a product of small prime numbers (2, 3, and 5 in the
2087 current implementation). Such an efficient DFT size can be calculated using the getOptimalDFTSize
2090 The sample below illustrates how to calculate a DFT-based convolution of two 2D real arrays:
2092 void convolveDFT(InputArray A, InputArray B, OutputArray C)
2094 // reallocate the output array if needed
2095 C.create(abs(A.rows - B.rows)+1, abs(A.cols - B.cols)+1, A.type());
2097 // calculate the size of DFT transform
2098 dftSize.width = getOptimalDFTSize(A.cols + B.cols - 1);
2099 dftSize.height = getOptimalDFTSize(A.rows + B.rows - 1);
2101 // allocate temporary buffers and initialize them with 0's
2102 Mat tempA(dftSize, A.type(), Scalar::all(0));
2103 Mat tempB(dftSize, B.type(), Scalar::all(0));
2105 // copy A and B to the top-left corners of tempA and tempB, respectively
2106 Mat roiA(tempA, Rect(0,0,A.cols,A.rows));
2108 Mat roiB(tempB, Rect(0,0,B.cols,B.rows));
2111 // now transform the padded A & B in-place;
2112 // use "nonzeroRows" hint for faster processing
2113 dft(tempA, tempA, 0, A.rows);
2114 dft(tempB, tempB, 0, B.rows);
2116 // multiply the spectrums;
2117 // the function handles packed spectrum representations well
2118 mulSpectrums(tempA, tempB, tempA);
2120 // transform the product back from the frequency domain.
2121 // Even though all the result rows will be non-zero,
2122 // you need only the first C.rows of them, and thus you
2123 // pass nonzeroRows == C.rows
2124 dft(tempA, tempA, DFT_INVERSE + DFT_SCALE, C.rows);
2126 // now copy the result back to C.
2127 tempA(Rect(0, 0, C.cols, C.rows)).copyTo(C);
2129 // all the temporary buffers will be deallocated automatically
2132 To optimize this sample, consider the following approaches:
2133 - Since nonzeroRows != 0 is passed to the forward transform calls and since A and B are copied to
2134 the top-left corners of tempA and tempB, respectively, it is not necessary to clear the whole
2135 tempA and tempB. It is only necessary to clear the tempA.cols - A.cols ( tempB.cols - B.cols)
2136 rightmost columns of the matrices.
2137 - This DFT-based convolution does not have to be applied to the whole big arrays, especially if B
2138 is significantly smaller than A or vice versa. Instead, you can calculate convolution by parts.
2139 To do this, you need to split the output array C into multiple tiles. For each tile, estimate
2140 which parts of A and B are required to calculate convolution in this tile. If the tiles in C are
2141 too small, the speed will decrease a lot because of repeated work. In the ultimate case, when
2142 each tile in C is a single pixel, the algorithm becomes equivalent to the naive convolution
2143 algorithm. If the tiles are too big, the temporary arrays tempA and tempB become too big and
2144 there is also a slowdown because of bad cache locality. So, there is an optimal tile size
2145 somewhere in the middle.
2146 - If different tiles in C can be calculated in parallel and, thus, the convolution is done by
2147 parts, the loop can be threaded.
2149 All of the above improvements have been implemented in #matchTemplate and #filter2D . Therefore, by
2150 using them, you can get the performance even better than with the above theoretically optimal
2151 implementation. Though, those two functions actually calculate cross-correlation, not convolution,
2152 so you need to "flip" the second convolution operand B vertically and horizontally using flip .
2154 - An example using the discrete fourier transform can be found at
2155 opencv_source_code/samples/cpp/dft.cpp
2156 - (Python) An example using the dft functionality to perform Wiener deconvolution can be found
2157 at opencv_source/samples/python/deconvolution.py
2158 - (Python) An example rearranging the quadrants of a Fourier image can be found at
2159 opencv_source/samples/python/dft.py
2160 @param src input array that could be real or complex.
2161 @param dst output array whose size and type depends on the flags .
2162 @param flags transformation flags, representing a combination of the #DftFlags
2163 @param nonzeroRows when the parameter is not zero, the function assumes that only the first
2164 nonzeroRows rows of the input array (#DFT_INVERSE is not set) or only the first nonzeroRows of the
2165 output array (#DFT_INVERSE is set) contain non-zeros, thus, the function can handle the rest of the
2166 rows more efficiently and save some time; this technique is very useful for calculating array
2167 cross-correlation or convolution using DFT.
2168 @sa dct , getOptimalDFTSize , mulSpectrums, filter2D , matchTemplate , flip , cartToPolar ,
2171 CV_EXPORTS_W void dft(InputArray src, OutputArray dst, int flags = 0, int nonzeroRows = 0);
2173 /** @brief Calculates the inverse Discrete Fourier Transform of a 1D or 2D array.
2175 idft(src, dst, flags) is equivalent to dft(src, dst, flags | #DFT_INVERSE) .
2176 @note None of dft and idft scales the result by default. So, you should pass #DFT_SCALE to one of
2177 dft or idft explicitly to make these transforms mutually inverse.
2178 @sa dft, dct, idct, mulSpectrums, getOptimalDFTSize
2179 @param src input floating-point real or complex array.
2180 @param dst output array whose size and type depend on the flags.
2181 @param flags operation flags (see dft and #DftFlags).
2182 @param nonzeroRows number of dst rows to process; the rest of the rows have undefined content (see
2183 the convolution sample in dft description.
2185 CV_EXPORTS_W void idft(InputArray src, OutputArray dst, int flags = 0, int nonzeroRows = 0);
2187 /** @brief Performs a forward or inverse discrete Cosine transform of 1D or 2D array.
2189 The function cv::dct performs a forward or inverse discrete Cosine transform (DCT) of a 1D or 2D
2190 floating-point array:
2191 - Forward Cosine transform of a 1D vector of N elements:
2192 \f[Y = C^{(N)} \cdot X\f]
2194 \f[C^{(N)}_{jk}= \sqrt{\alpha_j/N} \cos \left ( \frac{\pi(2k+1)j}{2N} \right )\f]
2196 \f$\alpha_0=1\f$, \f$\alpha_j=2\f$ for *j \> 0*.
2197 - Inverse Cosine transform of a 1D vector of N elements:
2198 \f[X = \left (C^{(N)} \right )^{-1} \cdot Y = \left (C^{(N)} \right )^T \cdot Y\f]
2199 (since \f$C^{(N)}\f$ is an orthogonal matrix, \f$C^{(N)} \cdot \left(C^{(N)}\right)^T = I\f$ )
2200 - Forward 2D Cosine transform of M x N matrix:
2201 \f[Y = C^{(N)} \cdot X \cdot \left (C^{(N)} \right )^T\f]
2202 - Inverse 2D Cosine transform of M x N matrix:
2203 \f[X = \left (C^{(N)} \right )^T \cdot X \cdot C^{(N)}\f]
2205 The function chooses the mode of operation by looking at the flags and size of the input array:
2206 - If (flags & #DCT_INVERSE) == 0 , the function does a forward 1D or 2D transform. Otherwise, it
2207 is an inverse 1D or 2D transform.
2208 - If (flags & #DCT_ROWS) != 0 , the function performs a 1D transform of each row.
2209 - If the array is a single column or a single row, the function performs a 1D transform.
2210 - If none of the above is true, the function performs a 2D transform.
2212 @note Currently dct supports even-size arrays (2, 4, 6 ...). For data analysis and approximation, you
2213 can pad the array when necessary.
2214 Also, the function performance depends very much, and not monotonically, on the array size (see
2215 getOptimalDFTSize ). In the current implementation DCT of a vector of size N is calculated via DFT
2216 of a vector of size N/2 . Thus, the optimal DCT size N1 \>= N can be calculated as:
2218 size_t getOptimalDCTSize(size_t N) { return 2*getOptimalDFTSize((N+1)/2); }
2219 N1 = getOptimalDCTSize(N);
2221 @param src input floating-point array.
2222 @param dst output array of the same size and type as src .
2223 @param flags transformation flags as a combination of cv::DftFlags (DCT_*)
2224 @sa dft , getOptimalDFTSize , idct
2226 CV_EXPORTS_W void dct(InputArray src, OutputArray dst, int flags = 0);
2228 /** @brief Calculates the inverse Discrete Cosine Transform of a 1D or 2D array.
2230 idct(src, dst, flags) is equivalent to dct(src, dst, flags | DCT_INVERSE).
2231 @param src input floating-point single-channel array.
2232 @param dst output array of the same size and type as src.
2233 @param flags operation flags.
2234 @sa dct, dft, idft, getOptimalDFTSize
2236 CV_EXPORTS_W void idct(InputArray src, OutputArray dst, int flags = 0);
2238 /** @brief Performs the per-element multiplication of two Fourier spectrums.
2240 The function cv::mulSpectrums performs the per-element multiplication of the two CCS-packed or complex
2241 matrices that are results of a real or complex Fourier transform.
2243 The function, together with dft and idft , may be used to calculate convolution (pass conjB=false )
2244 or correlation (pass conjB=true ) of two arrays rapidly. When the arrays are complex, they are
2245 simply multiplied (per element) with an optional conjugation of the second-array elements. When the
2246 arrays are real, they are assumed to be CCS-packed (see dft for details).
2247 @param a first input array.
2248 @param b second input array of the same size and type as src1 .
2249 @param c output array of the same size and type as src1 .
2250 @param flags operation flags; currently, the only supported flag is cv::DFT_ROWS, which indicates that
2251 each row of src1 and src2 is an independent 1D Fourier spectrum. If you do not want to use this flag, then simply add a `0` as value.
2252 @param conjB optional flag that conjugates the second input array before the multiplication (true)
2255 CV_EXPORTS_W void mulSpectrums(InputArray a, InputArray b, OutputArray c,
2256 int flags, bool conjB = false);
2258 /** @brief Returns the optimal DFT size for a given vector size.
2260 DFT performance is not a monotonic function of a vector size. Therefore, when you calculate
2261 convolution of two arrays or perform the spectral analysis of an array, it usually makes sense to
2262 pad the input data with zeros to get a bit larger array that can be transformed much faster than the
2263 original one. Arrays whose size is a power-of-two (2, 4, 8, 16, 32, ...) are the fastest to process.
2264 Though, the arrays whose size is a product of 2's, 3's, and 5's (for example, 300 = 5\*5\*3\*2\*2)
2265 are also processed quite efficiently.
2267 The function cv::getOptimalDFTSize returns the minimum number N that is greater than or equal to vecsize
2268 so that the DFT of a vector of size N can be processed efficiently. In the current implementation N
2269 = 2 ^p^ \* 3 ^q^ \* 5 ^r^ for some integer p, q, r.
2271 The function returns a negative number if vecsize is too large (very close to INT_MAX ).
2273 While the function cannot be used directly to estimate the optimal vector size for DCT transform
2274 (since the current DCT implementation supports only even-size vectors), it can be easily processed
2275 as getOptimalDFTSize((vecsize+1)/2)\*2.
2276 @param vecsize vector size.
2277 @sa dft , dct , idft , idct , mulSpectrums
2279 CV_EXPORTS_W int getOptimalDFTSize(int vecsize);
2281 /** @brief Returns the default random number generator.
2283 The function cv::theRNG returns the default random number generator. For each thread, there is a
2284 separate random number generator, so you can use the function safely in multi-thread environments.
2285 If you just need to get a single random number using this generator or initialize an array, you can
2286 use randu or randn instead. But if you are going to generate many random numbers inside a loop, it
2287 is much faster to use this function to retrieve the generator and then use RNG::operator _Tp() .
2288 @sa RNG, randu, randn
2290 CV_EXPORTS RNG& theRNG();
2292 /** @brief Sets state of default random number generator.
2294 The function cv::setRNGSeed sets state of default random number generator to custom value.
2295 @param seed new state for default random number generator
2296 @sa RNG, randu, randn
2298 CV_EXPORTS_W void setRNGSeed(int seed);
2300 /** @brief Generates a single uniformly-distributed random number or an array of random numbers.
2302 Non-template variant of the function fills the matrix dst with uniformly-distributed
2303 random numbers from the specified range:
2304 \f[\texttt{low} _c \leq \texttt{dst} (I)_c < \texttt{high} _c\f]
2305 @param dst output array of random numbers; the array must be pre-allocated.
2306 @param low inclusive lower boundary of the generated random numbers.
2307 @param high exclusive upper boundary of the generated random numbers.
2308 @sa RNG, randn, theRNG
2310 CV_EXPORTS_W void randu(InputOutputArray dst, InputArray low, InputArray high);
2312 /** @brief Fills the array with normally distributed random numbers.
2314 The function cv::randn fills the matrix dst with normally distributed random numbers with the specified
2315 mean vector and the standard deviation matrix. The generated random numbers are clipped to fit the
2316 value range of the output array data type.
2317 @param dst output array of random numbers; the array must be pre-allocated and have 1 to 4 channels.
2318 @param mean mean value (expectation) of the generated random numbers.
2319 @param stddev standard deviation of the generated random numbers; it can be either a vector (in
2320 which case a diagonal standard deviation matrix is assumed) or a square matrix.
2323 CV_EXPORTS_W void randn(InputOutputArray dst, InputArray mean, InputArray stddev);
2325 /** @brief Shuffles the array elements randomly.
2327 The function cv::randShuffle shuffles the specified 1D array by randomly choosing pairs of elements and
2328 swapping them. The number of such swap operations will be dst.rows\*dst.cols\*iterFactor .
2329 @param dst input/output numerical 1D array.
2330 @param iterFactor scale factor that determines the number of random swap operations (see the details
2332 @param rng optional random number generator used for shuffling; if it is zero, theRNG () is used
2336 CV_EXPORTS_W void randShuffle(InputOutputArray dst, double iterFactor = 1., RNG* rng = 0);
2338 /** @brief Principal Component Analysis
2340 The class is used to calculate a special basis for a set of vectors. The
2341 basis will consist of eigenvectors of the covariance matrix calculated
2342 from the input set of vectors. The class %PCA can also transform
2343 vectors to/from the new coordinate space defined by the basis. Usually,
2344 in this new coordinate system, each vector from the original set (and
2345 any linear combination of such vectors) can be quite accurately
2346 approximated by taking its first few components, corresponding to the
2347 eigenvectors of the largest eigenvalues of the covariance matrix.
2348 Geometrically it means that you calculate a projection of the vector to
2349 a subspace formed by a few eigenvectors corresponding to the dominant
2350 eigenvalues of the covariance matrix. And usually such a projection is
2351 very close to the original vector. So, you can represent the original
2352 vector from a high-dimensional space with a much shorter vector
2353 consisting of the projected vector's coordinates in the subspace. Such a
2354 transformation is also known as Karhunen-Loeve Transform, or KLT.
2355 See http://en.wikipedia.org/wiki/Principal_component_analysis
2357 The sample below is the function that takes two matrices. The first
2358 function stores a set of vectors (a row per vector) that is used to
2359 calculate PCA. The second function stores another "test" set of vectors
2360 (a row per vector). First, these vectors are compressed with PCA, then
2361 reconstructed back, and then the reconstruction error norm is computed
2362 and printed for each vector. :
2367 PCA compressPCA(const Mat& pcaset, int maxComponents,
2368 const Mat& testset, Mat& compressed)
2370 PCA pca(pcaset, // pass the data
2371 Mat(), // we do not have a pre-computed mean vector,
2372 // so let the PCA engine to compute it
2373 PCA::DATA_AS_ROW, // indicate that the vectors
2374 // are stored as matrix rows
2375 // (use PCA::DATA_AS_COL if the vectors are
2376 // the matrix columns)
2377 maxComponents // specify, how many principal components to retain
2379 // if there is no test data, just return the computed basis, ready-to-use
2382 CV_Assert( testset.cols == pcaset.cols );
2384 compressed.create(testset.rows, maxComponents, testset.type());
2387 for( int i = 0; i < testset.rows; i++ )
2389 Mat vec = testset.row(i), coeffs = compressed.row(i), reconstructed;
2390 // compress the vector, the result will be stored
2391 // in the i-th row of the output matrix
2392 pca.project(vec, coeffs);
2393 // and then reconstruct it
2394 pca.backProject(coeffs, reconstructed);
2395 // and measure the error
2396 printf("%d. diff = %g\n", i, norm(vec, reconstructed, NORM_L2));
2401 @sa calcCovarMatrix, mulTransposed, SVD, dft, dct
2403 class CV_EXPORTS PCA
2406 enum Flags { DATA_AS_ROW = 0, //!< indicates that the input samples are stored as matrix rows
2407 DATA_AS_COL = 1, //!< indicates that the input samples are stored as matrix columns
2411 /** @brief default constructor
2413 The default constructor initializes an empty %PCA structure. The other
2414 constructors initialize the structure and call PCA::operator()().
2419 @param data input samples stored as matrix rows or matrix columns.
2420 @param mean optional mean value; if the matrix is empty (@c noArray()),
2421 the mean is computed from the data.
2422 @param flags operation flags; currently the parameter is only used to
2423 specify the data layout (PCA::Flags)
2424 @param maxComponents maximum number of components that %PCA should
2425 retain; by default, all the components are retained.
2427 PCA(InputArray data, InputArray mean, int flags, int maxComponents = 0);
2430 @param data input samples stored as matrix rows or matrix columns.
2431 @param mean optional mean value; if the matrix is empty (noArray()),
2432 the mean is computed from the data.
2433 @param flags operation flags; currently the parameter is only used to
2434 specify the data layout (PCA::Flags)
2435 @param retainedVariance Percentage of variance that PCA should retain.
2436 Using this parameter will let the PCA decided how many components to
2437 retain but it will always keep at least 2.
2439 PCA(InputArray data, InputArray mean, int flags, double retainedVariance);
2441 /** @brief performs %PCA
2443 The operator performs %PCA of the supplied dataset. It is safe to reuse
2444 the same PCA structure for multiple datasets. That is, if the structure
2445 has been previously used with another dataset, the existing internal
2446 data is reclaimed and the new @ref eigenvalues, @ref eigenvectors and @ref
2447 mean are allocated and computed.
2449 The computed @ref eigenvalues are sorted from the largest to the smallest and
2450 the corresponding @ref eigenvectors are stored as eigenvectors rows.
2452 @param data input samples stored as the matrix rows or as the matrix
2454 @param mean optional mean value; if the matrix is empty (noArray()),
2455 the mean is computed from the data.
2456 @param flags operation flags; currently the parameter is only used to
2457 specify the data layout. (Flags)
2458 @param maxComponents maximum number of components that PCA should
2459 retain; by default, all the components are retained.
2461 PCA& operator()(InputArray data, InputArray mean, int flags, int maxComponents = 0);
2464 @param data input samples stored as the matrix rows or as the matrix
2466 @param mean optional mean value; if the matrix is empty (noArray()),
2467 the mean is computed from the data.
2468 @param flags operation flags; currently the parameter is only used to
2469 specify the data layout. (PCA::Flags)
2470 @param retainedVariance Percentage of variance that %PCA should retain.
2471 Using this parameter will let the %PCA decided how many components to
2472 retain but it will always keep at least 2.
2474 PCA& operator()(InputArray data, InputArray mean, int flags, double retainedVariance);
2476 /** @brief Projects vector(s) to the principal component subspace.
2478 The methods project one or more vectors to the principal component
2479 subspace, where each vector projection is represented by coefficients in
2480 the principal component basis. The first form of the method returns the
2481 matrix that the second form writes to the result. So the first form can
2482 be used as a part of expression while the second form can be more
2483 efficient in a processing loop.
2484 @param vec input vector(s); must have the same dimensionality and the
2485 same layout as the input data used at %PCA phase, that is, if
2486 DATA_AS_ROW are specified, then `vec.cols==data.cols`
2487 (vector dimensionality) and `vec.rows` is the number of vectors to
2488 project, and the same is true for the PCA::DATA_AS_COL case.
2490 Mat project(InputArray vec) const;
2493 @param vec input vector(s); must have the same dimensionality and the
2494 same layout as the input data used at PCA phase, that is, if
2495 DATA_AS_ROW are specified, then `vec.cols==data.cols`
2496 (vector dimensionality) and `vec.rows` is the number of vectors to
2497 project, and the same is true for the PCA::DATA_AS_COL case.
2498 @param result output vectors; in case of PCA::DATA_AS_COL, the
2499 output matrix has as many columns as the number of input vectors, this
2500 means that `result.cols==vec.cols` and the number of rows match the
2501 number of principal components (for example, `maxComponents` parameter
2502 passed to the constructor).
2504 void project(InputArray vec, OutputArray result) const;
2506 /** @brief Reconstructs vectors from their PC projections.
2508 The methods are inverse operations to PCA::project. They take PC
2509 coordinates of projected vectors and reconstruct the original vectors.
2510 Unless all the principal components have been retained, the
2511 reconstructed vectors are different from the originals. But typically,
2512 the difference is small if the number of components is large enough (but
2513 still much smaller than the original vector dimensionality). As a
2514 result, PCA is used.
2515 @param vec coordinates of the vectors in the principal component
2516 subspace, the layout and size are the same as of PCA::project output
2519 Mat backProject(InputArray vec) const;
2522 @param vec coordinates of the vectors in the principal component
2523 subspace, the layout and size are the same as of PCA::project output
2525 @param result reconstructed vectors; the layout and size are the same as
2526 of PCA::project input vectors.
2528 void backProject(InputArray vec, OutputArray result) const;
2530 /** @brief write PCA objects
2532 Writes @ref eigenvalues @ref eigenvectors and @ref mean to specified FileStorage
2534 void write(FileStorage& fs) const;
2536 /** @brief load PCA objects
2538 Loads @ref eigenvalues @ref eigenvectors and @ref mean from specified FileNode
2540 void read(const FileNode& fn);
2542 Mat eigenvectors; //!< eigenvectors of the covariation matrix
2543 Mat eigenvalues; //!< eigenvalues of the covariation matrix
2544 Mat mean; //!< mean value subtracted before the projection and added after the back projection
2547 /** @example samples/cpp/pca.cpp
2548 An example using %PCA for dimensionality reduction while maintaining an amount of variance
2551 /** @example samples/cpp/tutorial_code/ml/introduction_to_pca/introduction_to_pca.cpp
2552 Check @ref tutorial_introduction_to_pca "the corresponding tutorial" for more details
2556 @brief Linear Discriminant Analysis
2557 @todo document this class
2559 class CV_EXPORTS LDA
2562 /** @brief constructor
2563 Initializes a LDA with num_components (default 0).
2565 explicit LDA(int num_components = 0);
2567 /** Initializes and performs a Discriminant Analysis with Fisher's
2568 Optimization Criterion on given data in src and corresponding labels
2569 in labels. If 0 (or less) number of components are given, they are
2570 automatically determined for given data in computation.
2572 LDA(InputArrayOfArrays src, InputArray labels, int num_components = 0);
2574 /** Serializes this object to a given filename.
2576 void save(const String& filename) const;
2578 /** Deserializes this object from a given filename.
2580 void load(const String& filename);
2582 /** Serializes this object to a given cv::FileStorage.
2584 void save(FileStorage& fs) const;
2586 /** Deserializes this object from a given cv::FileStorage.
2588 void load(const FileStorage& node);
2594 /** Compute the discriminants for data in src (row aligned) and labels.
2596 void compute(InputArrayOfArrays src, InputArray labels);
2598 /** Projects samples into the LDA subspace.
2599 src may be one or more row aligned samples.
2601 Mat project(InputArray src);
2603 /** Reconstructs projections from the LDA subspace.
2604 src may be one or more row aligned projections.
2606 Mat reconstruct(InputArray src);
2608 /** Returns the eigenvectors of this LDA.
2610 Mat eigenvectors() const { return _eigenvectors; }
2612 /** Returns the eigenvalues of this LDA.
2614 Mat eigenvalues() const { return _eigenvalues; }
2616 static Mat subspaceProject(InputArray W, InputArray mean, InputArray src);
2617 static Mat subspaceReconstruct(InputArray W, InputArray mean, InputArray src);
2620 bool _dataAsRow; // unused, but needed for 3.0 ABI compatibility.
2621 int _num_components;
2624 void lda(InputArrayOfArrays src, InputArray labels);
2627 /** @brief Singular Value Decomposition
2629 Class for computing Singular Value Decomposition of a floating-point
2630 matrix. The Singular Value Decomposition is used to solve least-square
2631 problems, under-determined linear systems, invert matrices, compute
2632 condition numbers, and so on.
2634 If you want to compute a condition number of a matrix or an absolute value of
2635 its determinant, you do not need `u` and `vt`. You can pass
2636 flags=SVD::NO_UV|... . Another flag SVD::FULL_UV indicates that full-size u
2637 and vt must be computed, which is not necessary most of the time.
2639 @sa invert, solve, eigen, determinant
2641 class CV_EXPORTS SVD
2645 /** allow the algorithm to modify the decomposed matrix; it can save space and speed up
2646 processing. currently ignored. */
2648 /** indicates that only a vector of singular values `w` is to be processed, while u and vt
2649 will be set to empty matrices */
2651 /** when the matrix is not square, by default the algorithm produces u and vt matrices of
2652 sufficiently large size for the further A reconstruction; if, however, FULL_UV flag is
2653 specified, u and vt will be full-size square orthogonal matrices.*/
2657 /** @brief the default constructor
2659 initializes an empty SVD structure
2664 initializes an empty SVD structure and then calls SVD::operator()
2665 @param src decomposed matrix. The depth has to be CV_32F or CV_64F.
2666 @param flags operation flags (SVD::Flags)
2668 SVD( InputArray src, int flags = 0 );
2670 /** @brief the operator that performs SVD. The previously allocated u, w and vt are released.
2672 The operator performs the singular value decomposition of the supplied
2673 matrix. The u,`vt` , and the vector of singular values w are stored in
2674 the structure. The same SVD structure can be reused many times with
2675 different matrices. Each time, if needed, the previous u,`vt` , and w
2676 are reclaimed and the new matrices are created, which is all handled by
2678 @param src decomposed matrix. The depth has to be CV_32F or CV_64F.
2679 @param flags operation flags (SVD::Flags)
2681 SVD& operator ()( InputArray src, int flags = 0 );
2683 /** @brief decomposes matrix and stores the results to user-provided matrices
2685 The methods/functions perform SVD of matrix. Unlike SVD::SVD constructor
2686 and SVD::operator(), they store the results to the user-provided
2691 SVD::compute(A, w, u, vt);
2694 @param src decomposed matrix. The depth has to be CV_32F or CV_64F.
2695 @param w calculated singular values
2696 @param u calculated left singular vectors
2697 @param vt transposed matrix of right singular vectors
2698 @param flags operation flags - see SVD::Flags.
2700 static void compute( InputArray src, OutputArray w,
2701 OutputArray u, OutputArray vt, int flags = 0 );
2704 computes singular values of a matrix
2705 @param src decomposed matrix. The depth has to be CV_32F or CV_64F.
2706 @param w calculated singular values
2707 @param flags operation flags - see SVD::Flags.
2709 static void compute( InputArray src, OutputArray w, int flags = 0 );
2711 /** @brief performs back substitution
2713 static void backSubst( InputArray w, InputArray u,
2714 InputArray vt, InputArray rhs,
2717 /** @brief solves an under-determined singular linear system
2719 The method finds a unit-length solution x of a singular linear system
2720 A\*x = 0. Depending on the rank of A, there can be no solutions, a
2721 single solution or an infinite number of solutions. In general, the
2722 algorithm solves the following problem:
2723 \f[dst = \arg \min _{x: \| x \| =1} \| src \cdot x \|\f]
2724 @param src left-hand-side matrix.
2725 @param dst found solution.
2727 static void solveZ( InputArray src, OutputArray dst );
2729 /** @brief performs a singular value back substitution.
2731 The method calculates a back substitution for the specified right-hand
2734 \f[\texttt{x} = \texttt{vt} ^T \cdot diag( \texttt{w} )^{-1} \cdot \texttt{u} ^T \cdot \texttt{rhs} \sim \texttt{A} ^{-1} \cdot \texttt{rhs}\f]
2736 Using this technique you can either get a very accurate solution of the
2737 convenient linear system, or the best (in the least-squares terms)
2738 pseudo-solution of an overdetermined linear system.
2740 @param rhs right-hand side of a linear system (u\*w\*v')\*dst = rhs to
2741 be solved, where A has been previously decomposed.
2743 @param dst found solution of the system.
2745 @note Explicit SVD with the further back substitution only makes sense
2746 if you need to solve many linear systems with the same left-hand side
2747 (for example, src ). If all you need is to solve a single system
2748 (possibly with multiple rhs immediately available), simply call solve
2749 add pass #DECOMP_SVD there. It does absolutely the same thing.
2751 void backSubst( InputArray rhs, OutputArray dst ) const;
2753 /** @todo document */
2754 template<typename _Tp, int m, int n, int nm> static
2755 void compute( const Matx<_Tp, m, n>& a, Matx<_Tp, nm, 1>& w, Matx<_Tp, m, nm>& u, Matx<_Tp, n, nm>& vt );
2757 /** @todo document */
2758 template<typename _Tp, int m, int n, int nm> static
2759 void compute( const Matx<_Tp, m, n>& a, Matx<_Tp, nm, 1>& w );
2761 /** @todo document */
2762 template<typename _Tp, int m, int n, int nm, int nb> static
2763 void backSubst( const Matx<_Tp, nm, 1>& w, const Matx<_Tp, m, nm>& u, const Matx<_Tp, n, nm>& vt, const Matx<_Tp, m, nb>& rhs, Matx<_Tp, n, nb>& dst );
2768 /** @brief Random Number Generator
2770 Random number generator. It encapsulates the state (currently, a 64-bit
2771 integer) and has methods to return scalar random values and to fill
2772 arrays with random values. Currently it supports uniform and Gaussian
2773 (normal) distributions. The generator uses Multiply-With-Carry
2774 algorithm, introduced by G. Marsaglia (
2775 <http://en.wikipedia.org/wiki/Multiply-with-carry> ).
2776 Gaussian-distribution random numbers are generated using the Ziggurat
2777 algorithm ( <http://en.wikipedia.org/wiki/Ziggurat_algorithm> ),
2778 introduced by G. Marsaglia and W. W. Tsang.
2780 class CV_EXPORTS RNG
2787 /** @brief constructor
2789 These are the RNG constructors. The first form sets the state to some
2790 pre-defined value, equal to 2\*\*32-1 in the current implementation. The
2791 second form sets the state to the specified value. If you passed state=0
2792 , the constructor uses the above default value instead to avoid the
2793 singular random number sequence, consisting of all zeros.
2797 @param state 64-bit value used to initialize the RNG.
2800 /**The method updates the state using the MWC algorithm and returns the
2801 next 32-bit random number.*/
2804 /**Each of the methods updates the state using the MWC algorithm and
2805 returns the next random number of the specified type. In case of integer
2806 types, the returned number is from the available value range for the
2807 specified type. In case of floating-point types, the returned value is
2818 operator unsigned();
2826 /** @brief returns a random integer sampled uniformly from [0, N).
2828 The methods transform the state using the MWC algorithm and return the
2829 next random number. The first form is equivalent to RNG::next . The
2830 second form returns the random number modulo N , which means that the
2831 result is in the range [0, N) .
2833 unsigned operator ()();
2835 @param N upper non-inclusive boundary of the returned random number.
2837 unsigned operator ()(unsigned N);
2839 /** @brief returns uniformly distributed integer random number from [a,b) range
2841 The methods transform the state using the MWC algorithm and return the
2842 next uniformly-distributed random number of the specified type, deduced
2843 from the input parameter type, from the range [a, b) . There is a nuance
2844 illustrated by the following sample:
2849 // always produces 0
2850 double a = rng.uniform(0, 1);
2852 // produces double from [0, 1)
2853 double a1 = rng.uniform((double)0, (double)1);
2855 // produces float from [0, 1)
2856 float b = rng.uniform(0.f, 1.f);
2858 // produces double from [0, 1)
2859 double c = rng.uniform(0., 1.);
2861 // may cause compiler error because of ambiguity:
2862 // RNG::uniform(0, (int)0.999999)? or RNG::uniform((double)0, 0.99999)?
2863 double d = rng.uniform(0, 0.999999);
2866 The compiler does not take into account the type of the variable to
2867 which you assign the result of RNG::uniform . The only thing that
2868 matters to the compiler is the type of a and b parameters. So, if you
2869 want a floating-point random number, but the range boundaries are
2870 integer numbers, either put dots in the end, if they are constants, or
2871 use explicit type cast operators, as in the a1 initialization above.
2872 @param a lower inclusive boundary of the returned random number.
2873 @param b upper non-inclusive boundary of the returned random number.
2875 int uniform(int a, int b);
2877 float uniform(float a, float b);
2879 double uniform(double a, double b);
2881 /** @brief Fills arrays with random numbers.
2883 @param mat 2D or N-dimensional matrix; currently matrices with more than
2884 4 channels are not supported by the methods, use Mat::reshape as a
2885 possible workaround.
2886 @param distType distribution type, RNG::UNIFORM or RNG::NORMAL.
2887 @param a first distribution parameter; in case of the uniform
2888 distribution, this is an inclusive lower boundary, in case of the normal
2889 distribution, this is a mean value.
2890 @param b second distribution parameter; in case of the uniform
2891 distribution, this is a non-inclusive upper boundary, in case of the
2892 normal distribution, this is a standard deviation (diagonal of the
2893 standard deviation matrix or the full standard deviation matrix).
2894 @param saturateRange pre-saturation flag; for uniform distribution only;
2895 if true, the method will first convert a and b to the acceptable value
2896 range (according to the mat datatype) and then will generate uniformly
2897 distributed random numbers within the range [saturate(a), saturate(b)),
2898 if saturateRange=false, the method will generate uniformly distributed
2899 random numbers in the original range [a, b) and then will saturate them,
2900 it means, for example, that
2901 <tt>theRNG().fill(mat_8u, RNG::UNIFORM, -DBL_MAX, DBL_MAX)</tt> will likely
2902 produce array mostly filled with 0's and 255's, since the range (0, 255)
2903 is significantly smaller than [-DBL_MAX, DBL_MAX).
2905 Each of the methods fills the matrix with the random values from the
2906 specified distribution. As the new numbers are generated, the RNG state
2907 is updated accordingly. In case of multiple-channel images, every
2908 channel is filled independently, which means that RNG cannot generate
2909 samples from the multi-dimensional Gaussian distribution with
2910 non-diagonal covariance matrix directly. To do that, the method
2911 generates samples from multi-dimensional standard Gaussian distribution
2912 with zero mean and identity covariation matrix, and then transforms them
2913 using transform to get samples from the specified Gaussian distribution.
2915 void fill( InputOutputArray mat, int distType, InputArray a, InputArray b, bool saturateRange = false );
2917 /** @brief Returns the next random number sampled from the Gaussian distribution
2918 @param sigma standard deviation of the distribution.
2920 The method transforms the state using the MWC algorithm and returns the
2921 next random number from the Gaussian distribution N(0,sigma) . That is,
2922 the mean value of the returned random numbers is zero and the standard
2923 deviation is the specified sigma .
2925 double gaussian(double sigma);
2929 bool operator ==(const RNG& other) const;
2932 /** @brief Mersenne Twister random number generator
2934 Inspired by http://www.math.sci.hiroshima-u.ac.jp/~m-mat/MT/MT2002/CODES/mt19937ar.c
2937 class CV_EXPORTS RNG_MT19937
2941 RNG_MT19937(unsigned s);
2942 void seed(unsigned s);
2947 operator unsigned();
2951 unsigned operator ()(unsigned N);
2952 unsigned operator ()();
2954 /** @brief returns uniformly distributed integer random number from [a,b) range*/
2955 int uniform(int a, int b);
2956 /** @brief returns uniformly distributed floating-point random number from [a,b) range*/
2957 float uniform(float a, float b);
2958 /** @brief returns uniformly distributed double-precision floating-point random number from [a,b) range*/
2959 double uniform(double a, double b);
2962 enum PeriodParameters {N = 624, M = 397};
2969 //! @addtogroup core_cluster
2972 /** @example samples/cpp/kmeans.cpp
2973 An example on K-means clustering
2976 /** @brief Finds centers of clusters and groups input samples around the clusters.
2978 The function kmeans implements a k-means algorithm that finds the centers of cluster_count clusters
2979 and groups the input samples around the clusters. As an output, \f$\texttt{bestLabels}_i\f$ contains a
2980 0-based cluster index for the sample stored in the \f$i^{th}\f$ row of the samples matrix.
2983 - (Python) An example on K-means clustering can be found at
2984 opencv_source_code/samples/python/kmeans.py
2985 @param data Data for clustering. An array of N-Dimensional points with float coordinates is needed.
2986 Examples of this array can be:
2987 - Mat points(count, 2, CV_32F);
2988 - Mat points(count, 1, CV_32FC2);
2989 - Mat points(1, count, CV_32FC2);
2990 - std::vector\<cv::Point2f\> points(sampleCount);
2991 @param K Number of clusters to split the set by.
2992 @param bestLabels Input/output integer array that stores the cluster indices for every sample.
2993 @param criteria The algorithm termination criteria, that is, the maximum number of iterations and/or
2994 the desired accuracy. The accuracy is specified as criteria.epsilon. As soon as each of the cluster
2995 centers moves by less than criteria.epsilon on some iteration, the algorithm stops.
2996 @param attempts Flag to specify the number of times the algorithm is executed using different
2997 initial labellings. The algorithm returns the labels that yield the best compactness (see the last
2998 function parameter).
2999 @param flags Flag that can take values of cv::KmeansFlags
3000 @param centers Output matrix of the cluster centers, one row per each cluster center.
3001 @return The function returns the compactness measure that is computed as
3002 \f[\sum _i \| \texttt{samples} _i - \texttt{centers} _{ \texttt{labels} _i} \| ^2\f]
3003 after every attempt. The best (minimum) value is chosen and the corresponding labels and the
3004 compactness value are returned by the function. Basically, you can use only the core of the
3005 function, set the number of attempts to 1, initialize labels each time using a custom algorithm,
3006 pass them with the ( flags = #KMEANS_USE_INITIAL_LABELS ) flag, and then choose the best
3007 (most-compact) clustering.
3009 CV_EXPORTS_W double kmeans( InputArray data, int K, InputOutputArray bestLabels,
3010 TermCriteria criteria, int attempts,
3011 int flags, OutputArray centers = noArray() );
3015 //! @addtogroup core_basic
3018 /////////////////////////////// Formatted output of cv::Mat ///////////////////////////
3020 /** @todo document */
3021 class CV_EXPORTS Formatted
3024 virtual const char* next() = 0;
3025 virtual void reset() = 0;
3026 virtual ~Formatted();
3029 /** @todo document */
3030 class CV_EXPORTS Formatter
3033 enum { FMT_DEFAULT = 0,
3041 virtual ~Formatter();
3043 virtual Ptr<Formatted> format(const Mat& mtx) const = 0;
3045 virtual void set32fPrecision(int p = 8) = 0;
3046 virtual void set64fPrecision(int p = 16) = 0;
3047 virtual void setMultiline(bool ml = true) = 0;
3049 static Ptr<Formatter> get(int fmt = FMT_DEFAULT);
3054 String& operator << (String& out, Ptr<Formatted> fmtd)
3057 for(const char* str = fmtd->next(); str; str = fmtd->next())
3058 out += cv::String(str);
3063 String& operator << (String& out, const Mat& mtx)
3065 return out << Formatter::get()->format(mtx);
3068 //////////////////////////////////////// Algorithm ////////////////////////////////////
3070 class CV_EXPORTS Algorithm;
3072 template<typename _Tp> struct ParamType {};
3075 /** @brief This is a base class for all more or less complex algorithms in OpenCV
3077 especially for classes of algorithms, for which there can be multiple implementations. The examples
3078 are stereo correspondence (for which there are algorithms like block matching, semi-global block
3079 matching, graph-cut etc.), background subtraction (which can be done using mixture-of-gaussians
3080 models, codebook-based algorithm etc.), optical flow (block matching, Lucas-Kanade, Horn-Schunck
3083 Here is example of SimpleBlobDetector use in your application via Algorithm interface:
3084 @snippet snippets/core_various.cpp Algorithm
3086 class CV_EXPORTS_W Algorithm
3090 virtual ~Algorithm();
3092 /** @brief Clears the algorithm state
3094 CV_WRAP virtual void clear() {}
3096 /** @brief Stores algorithm parameters in a file storage
3098 CV_WRAP virtual void write(FileStorage& fs) const { CV_UNUSED(fs); }
3103 CV_WRAP void write(FileStorage& fs, const String& name) const;
3105 /** @brief Reads algorithm parameters from a file storage
3107 CV_WRAP virtual void read(const FileNode& fn) { CV_UNUSED(fn); }
3109 /** @brief Returns true if the Algorithm is empty (e.g. in the very beginning or after unsuccessful read
3111 CV_WRAP virtual bool empty() const { return false; }
3113 /** @brief Reads algorithm from the file node
3115 This is static template method of Algorithm. It's usage is following (in the case of SVM):
3117 cv::FileStorage fsRead("example.xml", FileStorage::READ);
3118 Ptr<SVM> svm = Algorithm::read<SVM>(fsRead.root());
3120 In order to make this method work, the derived class must overwrite Algorithm::read(const
3121 FileNode& fn) and also have static create() method without parameters
3122 (or with all the optional parameters)
3124 template<typename _Tp> static Ptr<_Tp> read(const FileNode& fn)
3126 Ptr<_Tp> obj = _Tp::create();
3128 return !obj->empty() ? obj : Ptr<_Tp>();
3131 /** @brief Loads algorithm from the file
3133 @param filename Name of the file to read.
3134 @param objname The optional name of the node to read (if empty, the first top-level node will be used)
3136 This is static template method of Algorithm. It's usage is following (in the case of SVM):
3138 Ptr<SVM> svm = Algorithm::load<SVM>("my_svm_model.xml");
3140 In order to make this method work, the derived class must overwrite Algorithm::read(const
3143 template<typename _Tp> static Ptr<_Tp> load(const String& filename, const String& objname=String())
3145 FileStorage fs(filename, FileStorage::READ);
3146 CV_Assert(fs.isOpened());
3147 FileNode fn = objname.empty() ? fs.getFirstTopLevelNode() : fs[objname];
3148 if (fn.empty()) return Ptr<_Tp>();
3149 Ptr<_Tp> obj = _Tp::create();
3151 return !obj->empty() ? obj : Ptr<_Tp>();
3154 /** @brief Loads algorithm from a String
3156 @param strModel The string variable containing the model you want to load.
3157 @param objname The optional name of the node to read (if empty, the first top-level node will be used)
3159 This is static template method of Algorithm. It's usage is following (in the case of SVM):
3161 Ptr<SVM> svm = Algorithm::loadFromString<SVM>(myStringModel);
3164 template<typename _Tp> static Ptr<_Tp> loadFromString(const String& strModel, const String& objname=String())
3166 FileStorage fs(strModel, FileStorage::READ + FileStorage::MEMORY);
3167 FileNode fn = objname.empty() ? fs.getFirstTopLevelNode() : fs[objname];
3168 Ptr<_Tp> obj = _Tp::create();
3170 return !obj->empty() ? obj : Ptr<_Tp>();
3173 /** Saves the algorithm to a file.
3174 In order to make this method work, the derived class must implement Algorithm::write(FileStorage& fs). */
3175 CV_WRAP virtual void save(const String& filename) const;
3177 /** Returns the algorithm string identifier.
3178 This string is used as top level xml/yml node tag when the object is saved to a file or string. */
3179 CV_WRAP virtual String getDefaultName() const;
3182 void writeFormat(FileStorage& fs) const;
3186 enum { INT=0, BOOLEAN=1, REAL=2, STRING=3, MAT=4, MAT_VECTOR=5, ALGORITHM=6, FLOAT=7,
3187 UNSIGNED_INT=8, UINT64=9, UCHAR=11, SCALAR=12 };
3192 template<> struct ParamType<bool>
3194 typedef bool const_param_type;
3195 typedef bool member_type;
3197 enum { type = Param::BOOLEAN };
3200 template<> struct ParamType<int>
3202 typedef int const_param_type;
3203 typedef int member_type;
3205 enum { type = Param::INT };
3208 template<> struct ParamType<double>
3210 typedef double const_param_type;
3211 typedef double member_type;
3213 enum { type = Param::REAL };
3216 template<> struct ParamType<String>
3218 typedef const String& const_param_type;
3219 typedef String member_type;
3221 enum { type = Param::STRING };
3224 template<> struct ParamType<Mat>
3226 typedef const Mat& const_param_type;
3227 typedef Mat member_type;
3229 enum { type = Param::MAT };
3232 template<> struct ParamType<std::vector<Mat> >
3234 typedef const std::vector<Mat>& const_param_type;
3235 typedef std::vector<Mat> member_type;
3237 enum { type = Param::MAT_VECTOR };
3240 template<> struct ParamType<Algorithm>
3242 typedef const Ptr<Algorithm>& const_param_type;
3243 typedef Ptr<Algorithm> member_type;
3245 enum { type = Param::ALGORITHM };
3248 template<> struct ParamType<float>
3250 typedef float const_param_type;
3251 typedef float member_type;
3253 enum { type = Param::FLOAT };
3256 template<> struct ParamType<unsigned>
3258 typedef unsigned const_param_type;
3259 typedef unsigned member_type;
3261 enum { type = Param::UNSIGNED_INT };
3264 template<> struct ParamType<uint64>
3266 typedef uint64 const_param_type;
3267 typedef uint64 member_type;
3269 enum { type = Param::UINT64 };
3272 template<> struct ParamType<uchar>
3274 typedef uchar const_param_type;
3275 typedef uchar member_type;
3277 enum { type = Param::UCHAR };
3280 template<> struct ParamType<Scalar>
3282 typedef const Scalar& const_param_type;
3283 typedef Scalar member_type;
3285 enum { type = Param::SCALAR };
3292 #include "opencv2/core/operations.hpp"
3293 #include "opencv2/core/cvstd.inl.hpp"
3294 #include "opencv2/core/utility.hpp"
3295 #include "opencv2/core/optim.hpp"
3296 #include "opencv2/core/ovx.hpp"
3298 #endif /*OPENCV_CORE_HPP*/