1 /*M///////////////////////////////////////////////////////////////////////////////////////
2 //
3 // IMPORTANT: READ BEFORE DOWNLOADING, COPYING, INSTALLING OR USING.
4 //
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.
8 //
9 //
10 // License Agreement
11 // For Open Source Computer Vision Library
12 //
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.
18 //
19 // Redistribution and use in source and binary forms, with or without modification,
20 // are permitted provided that the following conditions are met:
21 //
22 // * Redistribution's of source code must retain the above copyright notice,
23 // this list of conditions and the following disclaimer.
24 //
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.
28 //
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.
31 //
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.
42 //
43 //M*/
44
45 #ifndef OPENCV_CORE_HPP
46 #define OPENCV_CORE_HPP
47
48 #ifndef __cplusplus
49 # error core.hpp header must be compiled as C++
50 #endif
51
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"
60
61 /**
62 @defgroup core Core functionality
63 @{
64 @defgroup core_basic Basic structures
65 @defgroup core_c C structures and operations
66 @{
67 @defgroup core_c_glue Connections with C++
68 @}
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
74 @{
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
81 @}
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
90 @{
91 @defgroup core_hal_functions Functions
92 @defgroup core_hal_interface Interface
93 @defgroup core_hal_intrin Universal intrinsics
94 @{
95 @defgroup core_hal_intrin_impl Private implementation helpers
96 @}
97 @defgroup core_lowlevel_api Low-level API for external libraries / plugins
98 @}
99 @defgroup core_parallel Parallel Processing
100 @{
101 @defgroup core_parallel_backend Parallel backends API
102 @}
103 @}
104 */
105
106 namespace cv {
107
108 //! @addtogroup core_utils
109 //! @{
110
111 /*! @brief Class passed to an error.
112
113 This class encapsulates all or almost all necessary
114 information about the error happened in the program. The exception is
115 usually constructed and thrown implicitly via CV_Error and CV_Error_ macros.
116 @see error
117 */
118 class CV_EXPORTS Exception : public std::exception
119 {
120 public:
121 /*!
122 Default constructor
123 */
124 Exception();
125 /*!
126 Full constructor. Normally the constructor is not called explicitly.
127 Instead, the macros CV_Error(), CV_Error_() and CV_Assert() are used.
128 */
129 Exception(int _code, const String& _err, const String& _func, const String& _file, int _line);
130 virtual ~Exception() throw();
131
132 /*!
133 \return the error description and the context as a text string.
134 */
135 virtual const char *what() const throw() CV_OVERRIDE;
136 void formatMessage();
137
138 String msg; ///< the formatted error message
139
140 int code; ///< error code @see CVStatus
141 String err; ///< error description
142 String func; ///< function name. Available only when the compiler supports getting it
143 String file; ///< source file name where the error has occurred
144 int line; ///< line number in the source file where the error has occurred
145 };
146
147 /*! @brief Signals an error and raises the exception.
148
149 By default the function prints information about the error to stderr,
150 then it either stops if cv::setBreakOnError() had been called before or raises the exception.
151 It is possible to alternate error processing by using #redirectError().
152 @param exc the exception raisen.
153 @deprecated drop this version
154 */
155 CV_EXPORTS CV_NORETURN void error(const Exception& exc);
156
157 enum SortFlags { SORT_EVERY_ROW = 0, //!< each matrix row is sorted independently
158 SORT_EVERY_COLUMN = 1, //!< each matrix column is sorted
159 //!< independently; this flag and the previous one are
160 //!< mutually exclusive.
161 SORT_ASCENDING = 0, //!< each matrix row is sorted in the ascending
162 //!< order.
163 SORT_DESCENDING = 16 //!< each matrix row is sorted in the
164 //!< descending order; this flag and the previous one are also
165 //!< mutually exclusive.
166 };
167
168 //! @} core_utils
169
170 //! @addtogroup core
171 //! @{
172
173 //! Covariation flags
174 enum CovarFlags {
175 /** The output covariance matrix is calculated as:
176 \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]
177 The covariance matrix will be nsamples x nsamples. Such an unusual covariance matrix is used
178 for fast PCA of a set of very large vectors (see, for example, the EigenFaces technique for
179 face recognition). Eigenvalues of this "scrambled" matrix match the eigenvalues of the true
180 covariance matrix. The "true" eigenvectors can be easily calculated from the eigenvectors of
181 the "scrambled" covariance matrix. */
182 COVAR_SCRAMBLED = 0,
183 /**The output covariance matrix is calculated as:
184 \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]
185 covar will be a square matrix of the same size as the total number of elements in each input
186 vector. One and only one of #COVAR_SCRAMBLED and #COVAR_NORMAL must be specified.*/
187 COVAR_NORMAL = 1,
188 /** If the flag is specified, the function does not calculate mean from
189 the input vectors but, instead, uses the passed mean vector. This is useful if mean has been
190 pre-calculated or known in advance, or if the covariance matrix is calculated by parts. In
191 this case, mean is not a mean vector of the input sub-set of vectors but rather the mean
192 vector of the whole set.*/
193 COVAR_USE_AVG = 2,
194 /** If the flag is specified, the covariance matrix is scaled. In the
195 "normal" mode, scale is 1./nsamples . In the "scrambled" mode, scale is the reciprocal of the
196 total number of elements in each input vector. By default (if the flag is not specified), the
197 covariance matrix is not scaled ( scale=1 ).*/
198 COVAR_SCALE = 4,
199 /** If the flag is
200 specified, all the input vectors are stored as rows of the samples matrix. mean should be a
201 single-row vector in this case.*/
202 COVAR_ROWS = 8,
203 /** If the flag is
204 specified, all the input vectors are stored as columns of the samples matrix. mean should be a
205 single-column vector in this case.*/
206 COVAR_COLS = 16
207 };
208
209 //! @addtogroup core_cluster
210 //! @{
211
212 //! k-Means flags
213 enum KmeansFlags {
214 /** Select random initial centers in each attempt.*/
215 KMEANS_RANDOM_CENTERS = 0,
216 /** Use kmeans++ center initialization by Arthur and Vassilvitskii [Arthur2007].*/
217 KMEANS_PP_CENTERS = 2,
218 /** During the first (and possibly the only) attempt, use the
219 user-supplied labels instead of computing them from the initial centers. For the second and
220 further attempts, use the random or semi-random centers. Use one of KMEANS_\*_CENTERS flag
221 to specify the exact method.*/
222 KMEANS_USE_INITIAL_LABELS = 1
223 };
224
225 //! @} core_cluster
226
227 //! @addtogroup core_array
228 //! @{
229
230 enum ReduceTypes { REDUCE_SUM = 0, //!< the output is the sum of all rows/columns of the matrix.
231 REDUCE_AVG = 1, //!< the output is the mean vector of all rows/columns of the matrix.
232 REDUCE_MAX = 2, //!< the output is the maximum (column/row-wise) of all rows/columns of the matrix.
233 REDUCE_MIN = 3 //!< the output is the minimum (column/row-wise) of all rows/columns of the matrix.
234 };
235
236 //! @} core_array
237
238 /** @brief Swaps two matrices
239 */
240 CV_EXPORTS void swap(Mat& a, Mat& b);
241 /** @overload */
242 CV_EXPORTS void swap( UMat& a, UMat& b );
243
244 //! @} core
245
246 //! @addtogroup core_array
247 //! @{
248
249 /** @brief Computes the source location of an extrapolated pixel.
250
251 The function computes and returns the coordinate of a donor pixel corresponding to the specified
252 extrapolated pixel when using the specified extrapolation border mode. For example, if you use
253 cv::BORDER_WRAP mode in the horizontal direction, cv::BORDER_REFLECT_101 in the vertical direction and
254 want to compute value of the "virtual" pixel Point(-5, 100) in a floating-point image img , it
255 looks like:
256 @code{.cpp}
257 float val = img.at<float>(borderInterpolate(100, img.rows, cv::BORDER_REFLECT_101),
258 borderInterpolate(-5, img.cols, cv::BORDER_WRAP));
259 @endcode
260 Normally, the function is not called directly. It is used inside filtering functions and also in
261 copyMakeBorder.
262 @param p 0-based coordinate of the extrapolated pixel along one of the axes, likely \<0 or \>= len
263 @param len Length of the array along the corresponding axis.
264 @param borderType Border type, one of the #BorderTypes, except for #BORDER_TRANSPARENT and
265 #BORDER_ISOLATED . When borderType==#BORDER_CONSTANT , the function always returns -1, regardless
266 of p and len.
267
268 @sa copyMakeBorder
269 */
270 CV_EXPORTS_W int borderInterpolate(int p, int len, int borderType);
271
272 /** @example samples/cpp/tutorial_code/ImgTrans/copyMakeBorder_demo.cpp
273 An example using copyMakeBorder function.
274 Check @ref tutorial_copyMakeBorder "the corresponding tutorial" for more details
275 */
276
277 /** @brief Forms a border around an image.
278
279 The function copies the source image into the middle of the destination image. The areas to the
280 left, to the right, above and below the copied source image will be filled with extrapolated
281 pixels. This is not what filtering functions based on it do (they extrapolate pixels on-fly), but
282 what other more complex functions, including your own, may do to simplify image boundary handling.
283
284 The function supports the mode when src is already in the middle of dst . In this case, the
285 function does not copy src itself but simply constructs the border, for example:
286
287 @code{.cpp}
288 // let border be the same in all directions
289 int border=2;
290 // constructs a larger image to fit both the image and the border
291 Mat gray_buf(rgb.rows + border*2, rgb.cols + border*2, rgb.depth());
292 // select the middle part of it w/o copying data
293 Mat gray(gray_canvas, Rect(border, border, rgb.cols, rgb.rows));
294 // convert image from RGB to grayscale
295 cvtColor(rgb, gray, COLOR_RGB2GRAY);
296 // form a border in-place
297 copyMakeBorder(gray, gray_buf, border, border,
298 border, border, BORDER_REPLICATE);
299 // now do some custom filtering ...
300 ...
301 @endcode
302 @note When the source image is a part (ROI) of a bigger image, the function will try to use the
303 pixels outside of the ROI to form a border. To disable this feature and always do extrapolation, as
304 if src was not a ROI, use borderType | #BORDER_ISOLATED.
305
306 @param src Source image.
307 @param dst Destination image of the same type as src and the size Size(src.cols+left+right,
308 src.rows+top+bottom) .
309 @param top the top pixels
310 @param bottom the bottom pixels
311 @param left the left pixels
312 @param right Parameter specifying how many pixels in each direction from the source image rectangle
313 to extrapolate. For example, top=1, bottom=1, left=1, right=1 mean that 1 pixel-wide border needs
314 to be built.
315 @param borderType Border type. See borderInterpolate for details.
316 @param value Border value if borderType==BORDER_CONSTANT .
317
318 @sa borderInterpolate
319 */
320 CV_EXPORTS_W void copyMakeBorder(InputArray src, OutputArray dst,
321 int top, int bottom, int left, int right,
322 int borderType, const Scalar& value = Scalar() );
323
324 /** @brief Calculates the per-element sum of two arrays or an array and a scalar.
325
326 The function add calculates:
327 - Sum of two arrays when both input arrays have the same size and the same number of channels:
328 \f[\texttt{dst}(I) = \texttt{saturate} ( \texttt{src1}(I) + \texttt{src2}(I)) \quad \texttt{if mask}(I) \ne0\f]
329 - Sum of an array and a scalar when src2 is constructed from Scalar or has the same number of
330 elements as `src1.channels()`:
331 \f[\texttt{dst}(I) = \texttt{saturate} ( \texttt{src1}(I) + \texttt{src2} ) \quad \texttt{if mask}(I) \ne0\f]
332 - Sum of a scalar and an array when src1 is constructed from Scalar or has the same number of
333 elements as `src2.channels()`:
334 \f[\texttt{dst}(I) = \texttt{saturate} ( \texttt{src1} + \texttt{src2}(I) ) \quad \texttt{if mask}(I) \ne0\f]
335 where `I` is a multi-dimensional index of array elements. In case of multi-channel arrays, each
336 channel is processed independently.
337
338 The first function in the list above can be replaced with matrix expressions:
339 @code{.cpp}
340 dst = src1 + src2;
341 dst += src1; // equivalent to add(dst, src1, dst);
342 @endcode
343 The input arrays and the output array can all have the same or different depths. For example, you
344 can add a 16-bit unsigned array to a 8-bit signed array and store the sum as a 32-bit
345 floating-point array. Depth of the output array is determined by the dtype parameter. In the second
346 and third cases above, as well as in the first case, when src1.depth() == src2.depth(), dtype can
347 be set to the default -1. In this case, the output array will have the same depth as the input
348 array, be it src1, src2 or both.
349 @note Saturation is not applied when the output array has the depth CV_32S. You may even get
350 result of an incorrect sign in the case of overflow.
351 @param src1 first input array or a scalar.
352 @param src2 second input array or a scalar.
353 @param dst output array that has the same size and number of channels as the input array(s); the
354 depth is defined by dtype or src1/src2.
355 @param mask optional operation mask - 8-bit single channel array, that specifies elements of the
356 output array to be changed.
357 @param dtype optional depth of the output array (see the discussion below).
358 @sa subtract, addWeighted, scaleAdd, Mat::convertTo
359 */
360 CV_EXPORTS_W void add(InputArray src1, InputArray src2, OutputArray dst,
361 InputArray mask = noArray(), int dtype = -1);
362
363 /** @brief Calculates the per-element difference between two arrays or array and a scalar.
364
365 The function subtract calculates:
366 - Difference between two arrays, when both input arrays have the same size and the same number of
367 channels:
368 \f[\texttt{dst}(I) = \texttt{saturate} ( \texttt{src1}(I) - \texttt{src2}(I)) \quad \texttt{if mask}(I) \ne0\f]
369 - Difference between an array and a scalar, when src2 is constructed from Scalar or has the same
370 number of elements as `src1.channels()`:
371 \f[\texttt{dst}(I) = \texttt{saturate} ( \texttt{src1}(I) - \texttt{src2} ) \quad \texttt{if mask}(I) \ne0\f]
372 - Difference between a scalar and an array, when src1 is constructed from Scalar or has the same
373 number of elements as `src2.channels()`:
374 \f[\texttt{dst}(I) = \texttt{saturate} ( \texttt{src1} - \texttt{src2}(I) ) \quad \texttt{if mask}(I) \ne0\f]
375 - The reverse difference between a scalar and an array in the case of `SubRS`:
376 \f[\texttt{dst}(I) = \texttt{saturate} ( \texttt{src2} - \texttt{src1}(I) ) \quad \texttt{if mask}(I) \ne0\f]
377 where I is a multi-dimensional index of array elements. In case of multi-channel arrays, each
378 channel is processed independently.
379
380 The first function in the list above can be replaced with matrix expressions:
381 @code{.cpp}
382 dst = src1 - src2;
383 dst -= src1; // equivalent to subtract(dst, src1, dst);
384 @endcode
385 The input arrays and the output array can all have the same or different depths. For example, you
386 can subtract to 8-bit unsigned arrays and store the difference in a 16-bit signed array. Depth of
387 the output array is determined by dtype parameter. In the second and third cases above, as well as
388 in the first case, when src1.depth() == src2.depth(), dtype can be set to the default -1. In this
389 case the output array will have the same depth as the input array, be it src1, src2 or both.
390 @note Saturation is not applied when the output array has the depth CV_32S. You may even get
391 result of an incorrect sign in the case of overflow.
392 @param src1 first input array or a scalar.
393 @param src2 second input array or a scalar.
394 @param dst output array of the same size and the same number of channels as the input array.
395 @param mask optional operation mask; this is an 8-bit single channel array that specifies elements
396 of the output array to be changed.
397 @param dtype optional depth of the output array
398 @sa add, addWeighted, scaleAdd, Mat::convertTo
399 */
400 CV_EXPORTS_W void subtract(InputArray src1, InputArray src2, OutputArray dst,
401 InputArray mask = noArray(), int dtype = -1);
402
403
404 /** @brief Calculates the per-element scaled product of two arrays.
405
406 The function multiply calculates the per-element product of two arrays:
407
408 \f[\texttt{dst} (I)= \texttt{saturate} ( \texttt{scale} \cdot \texttt{src1} (I) \cdot \texttt{src2} (I))\f]
409
410 There is also a @ref MatrixExpressions -friendly variant of the first function. See Mat::mul .
411
412 For a not-per-element matrix product, see gemm .
413
414 @note Saturation is not applied when the output array has the depth
415 CV_32S. You may even get result of an incorrect sign in the case of
416 overflow.
417 @param src1 first input array.
418 @param src2 second input array of the same size and the same type as src1.
419 @param dst output array of the same size and type as src1.
420 @param scale optional scale factor.
421 @param dtype optional depth of the output array
422 @sa add, subtract, divide, scaleAdd, addWeighted, accumulate, accumulateProduct, accumulateSquare,
423 Mat::convertTo
424 */
425 CV_EXPORTS_W void multiply(InputArray src1, InputArray src2,
426 OutputArray dst, double scale = 1, int dtype = -1);
427
428 /** @brief Performs per-element division of two arrays or a scalar by an array.
429
430 The function cv::divide divides one array by another:
431 \f[\texttt{dst(I) = saturate(src1(I)*scale/src2(I))}\f]
432 or a scalar by an array when there is no src1 :
433 \f[\texttt{dst(I) = saturate(scale/src2(I))}\f]
434
435 Different channels of multi-channel arrays are processed independently.
436
437 For integer types when src2(I) is zero, dst(I) will also be zero.
438
439 @note In case of floating point data there is no special defined behavior for zero src2(I) values.
440 Regular floating-point division is used.
441 Expect correct IEEE-754 behaviour for floating-point data (with NaN, Inf result values).
442
443 @note Saturation is not applied when the output array has the depth CV_32S. You may even get
444 result of an incorrect sign in the case of overflow.
445 @param src1 first input array.
446 @param src2 second input array of the same size and type as src1.
447 @param scale scalar factor.
448 @param dst output array of the same size and type as src2.
449 @param dtype optional depth of the output array; if -1, dst will have depth src2.depth(), but in
450 case of an array-by-array division, you can only pass -1 when src1.depth()==src2.depth().
451 @sa multiply, add, subtract
452 */
453 CV_EXPORTS_W void divide(InputArray src1, InputArray src2, OutputArray dst,
454 double scale = 1, int dtype = -1);
455
456 /** @overload */
457 CV_EXPORTS_W void divide(double scale, InputArray src2,
458 OutputArray dst, int dtype = -1);
459
460 /** @brief Calculates the sum of a scaled array and another array.
461
462 The function scaleAdd is one of the classical primitive linear algebra operations, known as DAXPY
463 or SAXPY in [BLAS](http://en.wikipedia.org/wiki/Basic_Linear_Algebra_Subprograms). It calculates
464 the sum of a scaled array and another array:
465 \f[\texttt{dst} (I)= \texttt{scale} \cdot \texttt{src1} (I) + \texttt{src2} (I)\f]
466 The function can also be emulated with a matrix expression, for example:
467 @code{.cpp}
468 Mat A(3, 3, CV_64F);
469 ...
470 A.row(0) = A.row(1)*2 + A.row(2);
471 @endcode
472 @param src1 first input array.
473 @param alpha scale factor for the first array.
474 @param src2 second input array of the same size and type as src1.
475 @param dst output array of the same size and type as src1.
476 @sa add, addWeighted, subtract, Mat::dot, Mat::convertTo
477 */
478 CV_EXPORTS_W void scaleAdd(InputArray src1, double alpha, InputArray src2, OutputArray dst);
479
480 /** @example samples/cpp/tutorial_code/HighGUI/AddingImagesTrackbar.cpp
481 Check @ref tutorial_trackbar "the corresponding tutorial" for more details
482 */
483
484 /** @brief Calculates the weighted sum of two arrays.
485
486 The function addWeighted calculates the weighted sum of two arrays as follows:
487 \f[\texttt{dst} (I)= \texttt{saturate} ( \texttt{src1} (I)* \texttt{alpha} + \texttt{src2} (I)* \texttt{beta} + \texttt{gamma} )\f]
488 where I is a multi-dimensional index of array elements. In case of multi-channel arrays, each
489 channel is processed independently.
490 The function can be replaced with a matrix expression:
491 @code{.cpp}
492 dst = src1*alpha + src2*beta + gamma;
493 @endcode
494 @note Saturation is not applied when the output array has the depth CV_32S. You may even get
495 result of an incorrect sign in the case of overflow.
496 @param src1 first input array.
497 @param alpha weight of the first array elements.
498 @param src2 second input array of the same size and channel number as src1.
499 @param beta weight of the second array elements.
500 @param gamma scalar added to each sum.
501 @param dst output array that has the same size and number of channels as the input arrays.
502 @param dtype optional depth of the output array; when both input arrays have the same depth, dtype
503 can be set to -1, which will be equivalent to src1.depth().
504 @sa add, subtract, scaleAdd, Mat::convertTo
505 */
506 CV_EXPORTS_W void addWeighted(InputArray src1, double alpha, InputArray src2,
507 double beta, double gamma, OutputArray dst, int dtype = -1);
508
509 /** @brief Scales, calculates absolute values, and converts the result to 8-bit.
510
511 On each element of the input array, the function convertScaleAbs
512 performs three operations sequentially: scaling, taking an absolute
513 value, conversion to an unsigned 8-bit type:
514 \f[\texttt{dst} (I)= \texttt{saturate\_cast<uchar>} (| \texttt{src} (I)* \texttt{alpha} + \texttt{beta} |)\f]
515 In case of multi-channel arrays, the function processes each channel
516 independently. When the output is not 8-bit, the operation can be
517 emulated by calling the Mat::convertTo method (or by using matrix
518 expressions) and then by calculating an absolute value of the result.
519 For example:
520 @code{.cpp}
521 Mat_<float> A(30,30);
522 randu(A, Scalar(-100), Scalar(100));
523 Mat_<float> B = A*5 + 3;
524 B = abs(B);
525 // Mat_<float> B = abs(A*5+3) will also do the job,
526 // but it will allocate a temporary matrix
527 @endcode
528 @param src input array.
529 @param dst output array.
530 @param alpha optional scale factor.
531 @param beta optional delta added to the scaled values.
532 @sa Mat::convertTo, cv::abs(const Mat&)
533 */
534 CV_EXPORTS_W void convertScaleAbs(InputArray src, OutputArray dst,
535 double alpha = 1, double beta = 0);
536
537 /** @brief Converts an array to half precision floating number.
538
539 This function converts FP32 (single precision floating point) from/to FP16 (half precision floating point). CV_16S format is used to represent FP16 data.
540 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
541 CV_16S to represent the bit depth. If the input array is neither of them, the function will raise an error.
542 The format of half precision floating point is defined in IEEE 754-2008.
543
544 @param src input array.
545 @param dst output array.
546 */
547 CV_EXPORTS_W void convertFp16(InputArray src, OutputArray dst);
548
549 /** @brief Performs a look-up table transform of an array.
550
551 The function LUT fills the output array with values from the look-up table. Indices of the entries
552 are taken from the input array. That is, the function processes each element of src as follows:
553 \f[\texttt{dst} (I) \leftarrow \texttt{lut(src(I) + d)}\f]
554 where
555 \f[d = \fork{0}{if \(\texttt{src}\) has depth \(\texttt{CV_8U}\)}{128}{if \(\texttt{src}\) has depth \(\texttt{CV_8S}\)}\f]
556 @param src input array of 8-bit elements.
557 @param lut look-up table of 256 elements; in case of multi-channel input array, the table should
558 either have a single channel (in this case the same table is used for all channels) or the same
559 number of channels as in the input array.
560 @param dst output array of the same size and number of channels as src, and the same depth as lut.
561 @sa convertScaleAbs, Mat::convertTo
562 */
563 CV_EXPORTS_W void LUT(InputArray src, InputArray lut, OutputArray dst);
564
565 /** @brief Calculates the sum of array elements.
566
567 The function cv::sum calculates and returns the sum of array elements,
568 independently for each channel.
569 @param src input array that must have from 1 to 4 channels.
570 @sa countNonZero, mean, meanStdDev, norm, minMaxLoc, reduce
571 */
572 CV_EXPORTS_AS(sumElems) Scalar sum(InputArray src);
573
574 /** @brief Counts non-zero array elements.
575
576 The function returns the number of non-zero elements in src :
577 \f[\sum _{I: \; \texttt{src} (I) \ne0 } 1\f]
578 @param src single-channel array.
579 @sa mean, meanStdDev, norm, minMaxLoc, calcCovarMatrix
580 */
581 CV_EXPORTS_W int countNonZero( InputArray src );
582
583 /** @brief Returns the list of locations of non-zero pixels
584
585 Given a binary matrix (likely returned from an operation such
586 as threshold(), compare(), >, ==, etc, return all of
587 the non-zero indices as a cv::Mat or std::vector<cv::Point> (x,y)
588 For example:
589 @code{.cpp}
590 cv::Mat binaryImage; // input, binary image
591 cv::Mat locations; // output, locations of non-zero pixels
592 cv::findNonZero(binaryImage, locations);
593
594 // access pixel coordinates
595 Point pnt = locations.at<Point>(i);
596 @endcode
597 or
598 @code{.cpp}
599 cv::Mat binaryImage; // input, binary image
600 vector<Point> locations; // output, locations of non-zero pixels
601 cv::findNonZero(binaryImage, locations);
602
603 // access pixel coordinates
604 Point pnt = locations[i];
605 @endcode
606 @param src single-channel array
607 @param idx the output array, type of cv::Mat or std::vector<Point>, corresponding to non-zero indices in the input
608 */
609 CV_EXPORTS_W void findNonZero( InputArray src, OutputArray idx );
610
611 /** @brief Calculates an average (mean) of array elements.
612
613 The function cv::mean calculates the mean value M of array elements,
614 independently for each channel, and return it:
615 \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]
616 When all the mask elements are 0's, the function returns Scalar::all(0)
617 @param src input array that should have from 1 to 4 channels so that the result can be stored in
618 Scalar_ .
619 @param mask optional operation mask.
620 @sa countNonZero, meanStdDev, norm, minMaxLoc
621 */
622 CV_EXPORTS_W Scalar mean(InputArray src, InputArray mask = noArray());
623
624 /** Calculates a mean and standard deviation of array elements.
625
626 The function cv::meanStdDev calculates the mean and the standard deviation M
627 of array elements independently for each channel and returns it via the
628 output parameters:
629 \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]
630 When all the mask elements are 0's, the function returns
631 mean=stddev=Scalar::all(0).
632 @note The calculated standard deviation is only the diagonal of the
633 complete normalized covariance matrix. If the full matrix is needed, you
634 can reshape the multi-channel array M x N to the single-channel array
635 M\*N x mtx.channels() (only possible when the matrix is continuous) and
636 then pass the matrix to calcCovarMatrix .
637 @param src input array that should have from 1 to 4 channels so that the results can be stored in
638 Scalar_ 's.
639 @param mean output parameter: calculated mean value.
640 @param stddev output parameter: calculated standard deviation.
641 @param mask optional operation mask.
642 @sa countNonZero, mean, norm, minMaxLoc, calcCovarMatrix
643 */
644 CV_EXPORTS_W void meanStdDev(InputArray src, OutputArray mean, OutputArray stddev,
645 InputArray mask=noArray());
646
647 /** @brief Calculates the absolute norm of an array.
648
649 This version of #norm calculates the absolute norm of src1. The type of norm to calculate is specified using #NormTypes.
650
651 As example for one array consider the function \f$r(x)= \begin{pmatrix} x \\ 1-x \end{pmatrix}, x \in [-1;1]\f$.
652 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$
653 is calculated as follows
654 \f{align*}
655 \| r(-1) \|_{L_1} &= |-1| + |2| = 3 \\
656 \| r(-1) \|_{L_2} &= \sqrt{(-1)^{2} + (2)^{2}} = \sqrt{5} \\
657 \| r(-1) \|_{L_\infty} &= \max(|-1|,|2|) = 2
658 \f}
659 and for \f$r(0.5) = \begin{pmatrix} 0.5 \\ 0.5 \end{pmatrix}\f$ the calculation is
660 \f{align*}
661 \| r(0.5) \|_{L_1} &= |0.5| + |0.5| = 1 \\
662 \| r(0.5) \|_{L_2} &= \sqrt{(0.5)^{2} + (0.5)^{2}} = \sqrt{0.5} \\
663 \| r(0.5) \|_{L_\infty} &= \max(|0.5|,|0.5|) = 0.5.
664 \f}
665 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$.
666 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$.
667 ![Graphs for the different norm functions from the above example](pics/NormTypes_OneArray_1-2-INF.png)
668
669 When the mask parameter is specified and it is not empty, the norm is
670
671 If normType is not specified, #NORM_L2 is used.
672 calculated only over the region specified by the mask.
673
674 Multi-channel input arrays are treated as single-channel arrays, that is,
675 the results for all channels are combined.
676
677 Hamming norms can only be calculated with CV_8U depth arrays.
678
679 @param src1 first input array.
680 @param normType type of the norm (see #NormTypes).
681 @param mask optional operation mask; it must have the same size as src1 and CV_8UC1 type.
682 */
683 CV_EXPORTS_W double norm(InputArray src1, int normType = NORM_L2, InputArray mask = noArray());
684
685 /** @brief Calculates an absolute difference norm or a relative difference norm.
686
687 This version of cv::norm calculates the absolute difference norm
688 or the relative difference norm of arrays src1 and src2.
689 The type of norm to calculate is specified using #NormTypes.
690
691 @param src1 first input array.
692 @param src2 second input array of the same size and the same type as src1.
693 @param normType type of the norm (see #NormTypes).
694 @param mask optional operation mask; it must have the same size as src1 and CV_8UC1 type.
695 */
696 CV_EXPORTS_W double norm(InputArray src1, InputArray src2,
697 int normType = NORM_L2, InputArray mask = noArray());
698 /** @overload
699 @param src first input array.
700 @param normType type of the norm (see #NormTypes).
701 */
702 CV_EXPORTS double norm( const SparseMat& src, int normType );
703
704 /** @brief Computes the Peak Signal-to-Noise Ratio (PSNR) image quality metric.
705
706 This function calculates the Peak Signal-to-Noise Ratio (PSNR) image quality metric in decibels (dB),
707 between two input arrays src1 and src2. The arrays must have the same type.
708
709 The PSNR is calculated as follows:
710
711 \f[
712 \texttt{PSNR} = 10 \cdot \log_{10}{\left( \frac{R^2}{MSE} \right) }
713 \f]
714
715 where R is the maximum integer value of depth (e.g. 255 in the case of CV_8U data)
716 and MSE is the mean squared error between the two arrays.
717
718 @param src1 first input array.
719 @param src2 second input array of the same size as src1.
720 @param R the maximum pixel value (255 by default)
721
722 */
723 CV_EXPORTS_W double PSNR(InputArray src1, InputArray src2, double R=255.);
724
725 /** @brief naive nearest neighbor finder
726
727 see http://en.wikipedia.org/wiki/Nearest_neighbor_search
728 @todo document
729 */
730 CV_EXPORTS_W void batchDistance(InputArray src1, InputArray src2,
731 OutputArray dist, int dtype, OutputArray nidx,
732 int normType = NORM_L2, int K = 0,
733 InputArray mask = noArray(), int update = 0,
734 bool crosscheck = false);
735
736 /** @brief Normalizes the norm or value range of an array.
737
738 The function cv::normalize normalizes scale and shift the input array elements so that
739 \f[\| \texttt{dst} \| _{L_p}= \texttt{alpha}\f]
740 (where p=Inf, 1 or 2) when normType=NORM_INF, NORM_L1, or NORM_L2, respectively; or so that
741 \f[\min _I \texttt{dst} (I)= \texttt{alpha} , \, \, \max _I \texttt{dst} (I)= \texttt{beta}\f]
742
743 when normType=NORM_MINMAX (for dense arrays only). The optional mask specifies a sub-array to be
744 normalized. This means that the norm or min-n-max are calculated over the sub-array, and then this
745 sub-array is modified to be normalized. If you want to only use the mask to calculate the norm or
746 min-max but modify the whole array, you can use norm and Mat::convertTo.
747
748 In case of sparse matrices, only the non-zero values are analyzed and transformed. Because of this,
749 the range transformation for sparse matrices is not allowed since it can shift the zero level.
750
751 Possible usage with some positive example data:
752 @code{.cpp}
753 vector<double> positiveData = { 2.0, 8.0, 10.0 };
754 vector<double> normalizedData_l1, normalizedData_l2, normalizedData_inf, normalizedData_minmax;
755
756 // Norm to probability (total count)
757 // sum(numbers) = 20.0
758 // 2.0 0.1 (2.0/20.0)
759 // 8.0 0.4 (8.0/20.0)
760 // 10.0 0.5 (10.0/20.0)
761 normalize(positiveData, normalizedData_l1, 1.0, 0.0, NORM_L1);
762
763 // Norm to unit vector: ||positiveData|| = 1.0
764 // 2.0 0.15
765 // 8.0 0.62
766 // 10.0 0.77
767 normalize(positiveData, normalizedData_l2, 1.0, 0.0, NORM_L2);
768
769 // Norm to max element
770 // 2.0 0.2 (2.0/10.0)
771 // 8.0 0.8 (8.0/10.0)
772 // 10.0 1.0 (10.0/10.0)
773 normalize(positiveData, normalizedData_inf, 1.0, 0.0, NORM_INF);
774
775 // Norm to range [0.0;1.0]
776 // 2.0 0.0 (shift to left border)
777 // 8.0 0.75 (6.0/8.0)
778 // 10.0 1.0 (shift to right border)
779 normalize(positiveData, normalizedData_minmax, 1.0, 0.0, NORM_MINMAX);
780 @endcode
781
782 @param src input array.
783 @param dst output array of the same size as src .
784 @param alpha norm value to normalize to or the lower range boundary in case of the range
785 normalization.
786 @param beta upper range boundary in case of the range normalization; it is not used for the norm
787 normalization.
788 @param norm_type normalization type (see cv::NormTypes).
789 @param dtype when negative, the output array has the same type as src; otherwise, it has the same
790 number of channels as src and the depth =CV_MAT_DEPTH(dtype).
791 @param mask optional operation mask.
792 @sa norm, Mat::convertTo, SparseMat::convertTo
793 */
794 CV_EXPORTS_W void normalize( InputArray src, InputOutputArray dst, double alpha = 1, double beta = 0,
795 int norm_type = NORM_L2, int dtype = -1, InputArray mask = noArray());
796
797 /** @overload
798 @param src input array.
799 @param dst output array of the same size as src .
800 @param alpha norm value to normalize to or the lower range boundary in case of the range
801 normalization.
802 @param normType normalization type (see cv::NormTypes).
803 */
804 CV_EXPORTS void normalize( const SparseMat& src, SparseMat& dst, double alpha, int normType );
805
806 /** @brief Finds the global minimum and maximum in an array.
807
808 The function cv::minMaxLoc finds the minimum and maximum element values and their positions. The
809 extremums are searched across the whole array or, if mask is not an empty array, in the specified
810 array region.
811
812 The function do not work with multi-channel arrays. If you need to find minimum or maximum
813 elements across all the channels, use Mat::reshape first to reinterpret the array as
814 single-channel. Or you may extract the particular channel using either extractImageCOI , or
815 mixChannels , or split .
816 @param src input single-channel array.
817 @param minVal pointer to the returned minimum value; NULL is used if not required.
818 @param maxVal pointer to the returned maximum value; NULL is used if not required.
819 @param minLoc pointer to the returned minimum location (in 2D case); NULL is used if not required.
820 @param maxLoc pointer to the returned maximum location (in 2D case); NULL is used if not required.
821 @param mask optional mask used to select a sub-array.
822 @sa max, min, compare, inRange, extractImageCOI, mixChannels, split, Mat::reshape
823 */
824 CV_EXPORTS_W void minMaxLoc(InputArray src, CV_OUT double* minVal,
825 CV_OUT double* maxVal = 0, CV_OUT Point* minLoc = 0,
826 CV_OUT Point* maxLoc = 0, InputArray mask = noArray());
827
828
829 /** @brief Finds the global minimum and maximum in an array
830
831 The function cv::minMaxIdx finds the minimum and maximum element values and their positions. The
832 extremums are searched across the whole array or, if mask is not an empty array, in the specified
833 array region. The function does not work with multi-channel arrays. If you need to find minimum or
834 maximum elements across all the channels, use Mat::reshape first to reinterpret the array as
835 single-channel. Or you may extract the particular channel using either extractImageCOI , or
836 mixChannels , or split . In case of a sparse matrix, the minimum is found among non-zero elements
837 only.
838 @note When minIdx is not NULL, it must have at least 2 elements (as well as maxIdx), even if src is
839 a single-row or single-column matrix. In OpenCV (following MATLAB) each array has at least 2
840 dimensions, i.e. single-column matrix is Mx1 matrix (and therefore minIdx/maxIdx will be
841 (i1,0)/(i2,0)) and single-row matrix is 1xN matrix (and therefore minIdx/maxIdx will be
842 (0,j1)/(0,j2)).
843 @param src input single-channel array.
844 @param minVal pointer to the returned minimum value; NULL is used if not required.
845 @param maxVal pointer to the returned maximum value; NULL is used if not required.
846 @param minIdx pointer to the returned minimum location (in nD case); NULL is used if not required;
847 Otherwise, it must point to an array of src.dims elements, the coordinates of the minimum element
848 in each dimension are stored there sequentially.
849 @param maxIdx pointer to the returned maximum location (in nD case). NULL is used if not required.
850 @param mask specified array region
851 */
852 CV_EXPORTS void minMaxIdx(InputArray src, double* minVal, double* maxVal = 0,
853 int* minIdx = 0, int* maxIdx = 0, InputArray mask = noArray());
854
855 /** @overload
856 @param a input single-channel array.
857 @param minVal pointer to the returned minimum value; NULL is used if not required.
858 @param maxVal pointer to the returned maximum value; NULL is used if not required.
859 @param minIdx pointer to the returned minimum location (in nD case); NULL is used if not required;
860 Otherwise, it must point to an array of src.dims elements, the coordinates of the minimum element
861 in each dimension are stored there sequentially.
862 @param maxIdx pointer to the returned maximum location (in nD case). NULL is used if not required.
863 */
864 CV_EXPORTS void minMaxLoc(const SparseMat& a, double* minVal,
865 double* maxVal, int* minIdx = 0, int* maxIdx = 0);
866
867 /** @brief Reduces a matrix to a vector.
868
869 The function #reduce reduces the matrix to a vector by treating the matrix rows/columns as a set of
870 1D vectors and performing the specified operation on the vectors until a single row/column is
871 obtained. For example, the function can be used to compute horizontal and vertical projections of a
872 raster image. In case of #REDUCE_MAX and #REDUCE_MIN , the output image should have the same type as the source one.
873 In case of #REDUCE_SUM and #REDUCE_AVG , the output may have a larger element bit-depth to preserve accuracy.
874 And multi-channel arrays are also supported in these two reduction modes.
875
876 The following code demonstrates its usage for a single channel matrix.
877 @snippet snippets/core_reduce.cpp example
878
879 And the following code demonstrates its usage for a two-channel matrix.
880 @snippet snippets/core_reduce.cpp example2
881
882 @param src input 2D matrix.
883 @param dst output vector. Its size and type is defined by dim and dtype parameters.
884 @param dim dimension index along which the matrix is reduced. 0 means that the matrix is reduced to
885 a single row. 1 means that the matrix is reduced to a single column.
886 @param rtype reduction operation that could be one of #ReduceTypes
887 @param dtype when negative, the output vector will have the same type as the input matrix,
888 otherwise, its type will be CV_MAKE_TYPE(CV_MAT_DEPTH(dtype), src.channels()).
889 @sa repeat
890 */
891 CV_EXPORTS_W void reduce(InputArray src, OutputArray dst, int dim, int rtype, int dtype = -1);
892
893 /** @brief Creates one multi-channel array out of several single-channel ones.
894
895 The function cv::merge merges several arrays to make a single multi-channel array. That is, each
896 element of the output array will be a concatenation of the elements of the input arrays, where
897 elements of i-th input array are treated as mv[i].channels()-element vectors.
898
899 The function cv::split does the reverse operation. If you need to shuffle channels in some other
900 advanced way, use cv::mixChannels.
901
902 The following example shows how to merge 3 single channel matrices into a single 3-channel matrix.
903 @snippet snippets/core_merge.cpp example
904
905 @param mv input array of matrices to be merged; all the matrices in mv must have the same
906 size and the same depth.
907 @param count number of input matrices when mv is a plain C array; it must be greater than zero.
908 @param dst output array of the same size and the same depth as mv[0]; The number of channels will
909 be equal to the parameter count.
910 @sa mixChannels, split, Mat::reshape
911 */
912 CV_EXPORTS void merge(const Mat* mv, size_t count, OutputArray dst);
913
914 /** @overload
915 @param mv input vector of matrices to be merged; all the matrices in mv must have the same
916 size and the same depth.
917 @param dst output array of the same size and the same depth as mv[0]; The number of channels will
918 be the total number of channels in the matrix array.
919 */
920 CV_EXPORTS_W void merge(InputArrayOfArrays mv, OutputArray dst);
921
922 /** @brief Divides a multi-channel array into several single-channel arrays.
923
924 The function cv::split splits a multi-channel array into separate single-channel arrays:
925 \f[\texttt{mv} [c](I) = \texttt{src} (I)_c\f]
926 If you need to extract a single channel or do some other sophisticated channel permutation, use
927 mixChannels .
928
929 The following example demonstrates how to split a 3-channel matrix into 3 single channel matrices.
930 @snippet snippets/core_split.cpp example
931
932 @param src input multi-channel array.
933 @param mvbegin output array; the number of arrays must match src.channels(); the arrays themselves are
934 reallocated, if needed.
935 @sa merge, mixChannels, cvtColor
936 */
937 CV_EXPORTS void split(const Mat& src, Mat* mvbegin);
938
939 /** @overload
940 @param m input multi-channel array.
941 @param mv output vector of arrays; the arrays themselves are reallocated, if needed.
942 */
943 CV_EXPORTS_W void split(InputArray m, OutputArrayOfArrays mv);
944
945 /** @brief Copies specified channels from input arrays to the specified channels of
946 output arrays.
947
948 The function cv::mixChannels provides an advanced mechanism for shuffling image channels.
949
950 cv::split,cv::merge,cv::extractChannel,cv::insertChannel and some forms of cv::cvtColor are partial cases of cv::mixChannels.
951
952 In the example below, the code splits a 4-channel BGRA image into a 3-channel BGR (with B and R
953 channels swapped) and a separate alpha-channel image:
954 @code{.cpp}
955 Mat bgra( 100, 100, CV_8UC4, Scalar(255,0,0,255) );
956 Mat bgr( bgra.rows, bgra.cols, CV_8UC3 );
957 Mat alpha( bgra.rows, bgra.cols, CV_8UC1 );
958
959 // forming an array of matrices is a quite efficient operation,
960 // because the matrix data is not copied, only the headers
961 Mat out[] = { bgr, alpha };
962 // bgra[0] -> bgr[2], bgra[1] -> bgr[1],
963 // bgra[2] -> bgr[0], bgra[3] -> alpha[0]
964 int from_to[] = { 0,2, 1,1, 2,0, 3,3 };
965 mixChannels( &bgra, 1, out, 2, from_to, 4 );
966 @endcode
967 @note Unlike many other new-style C++ functions in OpenCV (see the introduction section and
968 Mat::create ), cv::mixChannels requires the output arrays to be pre-allocated before calling the
969 function.
970 @param src input array or vector of matrices; all of the matrices must have the same size and the
971 same depth.
972 @param nsrcs number of matrices in `src`.
973 @param dst output array or vector of matrices; all the matrices **must be allocated**; their size and
974 depth must be the same as in `src[0]`.
975 @param ndsts number of matrices in `dst`.
976 @param fromTo array of index pairs specifying which channels are copied and where; fromTo[k\*2] is
977 a 0-based index of the input channel in src, fromTo[k\*2+1] is an index of the output channel in
978 dst; the continuous channel numbering is used: the first input image channels are indexed from 0 to
979 src[0].channels()-1, the second input image channels are indexed from src[0].channels() to
980 src[0].channels() + src[1].channels()-1, and so on, the same scheme is used for the output image
981 channels; as a special case, when fromTo[k\*2] is negative, the corresponding output channel is
982 filled with zero .
983 @param npairs number of index pairs in `fromTo`.
984 @sa split, merge, extractChannel, insertChannel, cvtColor
985 */
986 CV_EXPORTS void mixChannels(const Mat* src, size_t nsrcs, Mat* dst, size_t ndsts,
987 const int* fromTo, size_t npairs);
988
989 /** @overload
990 @param src input array or vector of matrices; all of the matrices must have the same size and the
991 same depth.
992 @param dst output array or vector of matrices; all the matrices **must be allocated**; their size and
993 depth must be the same as in src[0].
994 @param fromTo array of index pairs specifying which channels are copied and where; fromTo[k\*2] is
995 a 0-based index of the input channel in src, fromTo[k\*2+1] is an index of the output channel in
996 dst; the continuous channel numbering is used: the first input image channels are indexed from 0 to
997 src[0].channels()-1, the second input image channels are indexed from src[0].channels() to
998 src[0].channels() + src[1].channels()-1, and so on, the same scheme is used for the output image
999 channels; as a special case, when fromTo[k\*2] is negative, the corresponding output channel is
1000 filled with zero .
1001 @param npairs number of index pairs in fromTo.
1002 */
1003 CV_EXPORTS void mixChannels(InputArrayOfArrays src, InputOutputArrayOfArrays dst,
1004 const int* fromTo, size_t npairs);
1005
1006 /** @overload
1007 @param src input array or vector of matrices; all of the matrices must have the same size and the
1008 same depth.
1009 @param dst output array or vector of matrices; all the matrices **must be allocated**; their size and
1010 depth must be the same as in src[0].
1011 @param fromTo array of index pairs specifying which channels are copied and where; fromTo[k\*2] is
1012 a 0-based index of the input channel in src, fromTo[k\*2+1] is an index of the output channel in
1013 dst; the continuous channel numbering is used: the first input image channels are indexed from 0 to
1014 src[0].channels()-1, the second input image channels are indexed from src[0].channels() to
1015 src[0].channels() + src[1].channels()-1, and so on, the same scheme is used for the output image
1016 channels; as a special case, when fromTo[k\*2] is negative, the corresponding output channel is
1017 filled with zero .
1018 */
1019 CV_EXPORTS_W void mixChannels(InputArrayOfArrays src, InputOutputArrayOfArrays dst,
1020 const std::vector<int>& fromTo);
1021
1022 /** @brief Extracts a single channel from src (coi is 0-based index)
1023 @param src input array
1024 @param dst output array
1025 @param coi index of channel to extract
1026 @sa mixChannels, split
1027 */
1028 CV_EXPORTS_W void extractChannel(InputArray src, OutputArray dst, int coi);
1029
1030 /** @brief Inserts a single channel to dst (coi is 0-based index)
1031 @param src input array
1032 @param dst output array
1033 @param coi index of channel for insertion
1034 @sa mixChannels, merge
1035 */
1036 CV_EXPORTS_W void insertChannel(InputArray src, InputOutputArray dst, int coi);
1037
1038 /** @brief Flips a 2D array around vertical, horizontal, or both axes.
1039
1040 The function cv::flip flips the array in one of three different ways (row
1041 and column indices are 0-based):
1042 \f[\texttt{dst} _{ij} =
1043 \left\{
1044 \begin{array}{l l}
1045 \texttt{src} _{\texttt{src.rows}-i-1,j} & if\; \texttt{flipCode} = 0 \\
1046 \texttt{src} _{i, \texttt{src.cols} -j-1} & if\; \texttt{flipCode} > 0 \\
1047 \texttt{src} _{ \texttt{src.rows} -i-1, \texttt{src.cols} -j-1} & if\; \texttt{flipCode} < 0 \\
1048 \end{array}
1049 \right.\f]
1050 The example scenarios of using the function are the following:
1051 * Vertical flipping of the image (flipCode == 0) to switch between
1052 top-left and bottom-left image origin. This is a typical operation
1053 in video processing on Microsoft Windows\* OS.
1054 * Horizontal flipping of the image with the subsequent horizontal
1055 shift and absolute difference calculation to check for a
1056 vertical-axis symmetry (flipCode \> 0).
1057 * Simultaneous horizontal and vertical flipping of the image with
1058 the subsequent shift and absolute difference calculation to check
1059 for a central symmetry (flipCode \< 0).
1060 * Reversing the order of point arrays (flipCode \> 0 or
1061 flipCode == 0).
1062 @param src input array.
1063 @param dst output array of the same size and type as src.
1064 @param flipCode a flag to specify how to flip the array; 0 means
1065 flipping around the x-axis and positive value (for example, 1) means
1066 flipping around y-axis. Negative value (for example, -1) means flipping
1067 around both axes.
1068 @sa transpose , repeat , completeSymm
1069 */
1070 CV_EXPORTS_W void flip(InputArray src, OutputArray dst, int flipCode);
1071
1072 enum RotateFlags {
1073 ROTATE_90_CLOCKWISE = 0, //!<Rotate 90 degrees clockwise
1074 ROTATE_180 = 1, //!<Rotate 180 degrees clockwise
1075 ROTATE_90_COUNTERCLOCKWISE = 2, //!<Rotate 270 degrees clockwise
1076 };
1077 /** @brief Rotates a 2D array in multiples of 90 degrees.
1078 The function cv::rotate rotates the array in one of three different ways:
1079 * Rotate by 90 degrees clockwise (rotateCode = ROTATE_90_CLOCKWISE).
1080 * Rotate by 180 degrees clockwise (rotateCode = ROTATE_180).
1081 * Rotate by 270 degrees clockwise (rotateCode = ROTATE_90_COUNTERCLOCKWISE).
1082 @param src input array.
1083 @param dst output array of the same type as src. The size is the same with ROTATE_180,
1084 and the rows and cols are switched for ROTATE_90_CLOCKWISE and ROTATE_90_COUNTERCLOCKWISE.
1085 @param rotateCode an enum to specify how to rotate the array; see the enum #RotateFlags
1086 @sa transpose , repeat , completeSymm, flip, RotateFlags
1087 */
1088 CV_EXPORTS_W void rotate(InputArray src, OutputArray dst, int rotateCode);
1089
1090 /** @brief Fills the output array with repeated copies of the input array.
1091
1092 The function cv::repeat duplicates the input array one or more times along each of the two axes:
1093 \f[\texttt{dst} _{ij}= \texttt{src} _{i\mod src.rows, \; j\mod src.cols }\f]
1094 The second variant of the function is more convenient to use with @ref MatrixExpressions.
1095 @param src input array to replicate.
1096 @param ny Flag to specify how many times the `src` is repeated along the
1097 vertical axis.
1098 @param nx Flag to specify how many times the `src` is repeated along the
1099 horizontal axis.
1100 @param dst output array of the same type as `src`.
1101 @sa cv::reduce
1102 */
1103 CV_EXPORTS_W void repeat(InputArray src, int ny, int nx, OutputArray dst);
1104
1105 /** @overload
1106 @param src input array to replicate.
1107 @param ny Flag to specify how many times the `src` is repeated along the
1108 vertical axis.
1109 @param nx Flag to specify how many times the `src` is repeated along the
1110 horizontal axis.
1111 */
1112 CV_EXPORTS Mat repeat(const Mat& src, int ny, int nx);
1113
1114 /** @brief Applies horizontal concatenation to given matrices.
1115
1116 The function horizontally concatenates two or more cv::Mat matrices (with the same number of rows).
1117 @code{.cpp}
1118 cv::Mat matArray[] = { cv::Mat(4, 1, CV_8UC1, cv::Scalar(1)),
1119 cv::Mat(4, 1, CV_8UC1, cv::Scalar(2)),
1120 cv::Mat(4, 1, CV_8UC1, cv::Scalar(3)),};
1121
1122 cv::Mat out;
1123 cv::hconcat( matArray, 3, out );
1124 //out:
1125 //[1, 2, 3;
1126 // 1, 2, 3;
1127 // 1, 2, 3;
1128 // 1, 2, 3]
1129 @endcode
1130 @param src input array or vector of matrices. all of the matrices must have the same number of rows and the same depth.
1131 @param nsrc number of matrices in src.
1132 @param dst output array. It has the same number of rows and depth as the src, and the sum of cols of the src.
1133 @sa cv::vconcat(const Mat*, size_t, OutputArray), @sa cv::vconcat(InputArrayOfArrays, OutputArray) and @sa cv::vconcat(InputArray, InputArray, OutputArray)
1134 */
1135 CV_EXPORTS void hconcat(const Mat* src, size_t nsrc, OutputArray dst);
1136 /** @overload
1137 @code{.cpp}
1138 cv::Mat_<float> A = (cv::Mat_<float>(3, 2) << 1, 4,
1139 2, 5,
1140 3, 6);
1141 cv::Mat_<float> B = (cv::Mat_<float>(3, 2) << 7, 10,
1142 8, 11,
1143 9, 12);
1144
1145 cv::Mat C;
1146 cv::hconcat(A, B, C);
1147 //C:
1148 //[1, 4, 7, 10;
1149 // 2, 5, 8, 11;
1150 // 3, 6, 9, 12]
1151 @endcode
1152 @param src1 first input array to be considered for horizontal concatenation.
1153 @param src2 second input array to be considered for horizontal concatenation.
1154 @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.
1155 */
1156 CV_EXPORTS void hconcat(InputArray src1, InputArray src2, OutputArray dst);
1157 /** @overload
1158 @code{.cpp}
1159 std::vector<cv::Mat> matrices = { cv::Mat(4, 1, CV_8UC1, cv::Scalar(1)),
1160 cv::Mat(4, 1, CV_8UC1, cv::Scalar(2)),
1161 cv::Mat(4, 1, CV_8UC1, cv::Scalar(3)),};
1162
1163 cv::Mat out;
1164 cv::hconcat( matrices, out );
1165 //out:
1166 //[1, 2, 3;
1167 // 1, 2, 3;
1168 // 1, 2, 3;
1169 // 1, 2, 3]
1170 @endcode
1171 @param src input array or vector of matrices. all of the matrices must have the same number of rows and the same depth.
1172 @param dst output array. It has the same number of rows and depth as the src, and the sum of cols of the src.
1173 same depth.
1174 */
1175 CV_EXPORTS_W void hconcat(InputArrayOfArrays src, OutputArray dst);
1176
1177 /** @brief Applies vertical concatenation to given matrices.
1178
1179 The function vertically concatenates two or more cv::Mat matrices (with the same number of cols).
1180 @code{.cpp}
1181 cv::Mat matArray[] = { cv::Mat(1, 4, CV_8UC1, cv::Scalar(1)),
1182 cv::Mat(1, 4, CV_8UC1, cv::Scalar(2)),
1183 cv::Mat(1, 4, CV_8UC1, cv::Scalar(3)),};
1184
1185 cv::Mat out;
1186 cv::vconcat( matArray, 3, out );
1187 //out:
1188 //[1, 1, 1, 1;
1189 // 2, 2, 2, 2;
1190 // 3, 3, 3, 3]
1191 @endcode
1192 @param src input array or vector of matrices. all of the matrices must have the same number of cols and the same depth.
1193 @param nsrc number of matrices in src.
1194 @param dst output array. It has the same number of cols and depth as the src, and the sum of rows of the src.
1195 @sa cv::hconcat(const Mat*, size_t, OutputArray), @sa cv::hconcat(InputArrayOfArrays, OutputArray) and @sa cv::hconcat(InputArray, InputArray, OutputArray)
1196 */
1197 CV_EXPORTS void vconcat(const Mat* src, size_t nsrc, OutputArray dst);
1198 /** @overload
1199 @code{.cpp}
1200 cv::Mat_<float> A = (cv::Mat_<float>(3, 2) << 1, 7,
1201 2, 8,
1202 3, 9);
1203 cv::Mat_<float> B = (cv::Mat_<float>(3, 2) << 4, 10,
1204 5, 11,
1205 6, 12);
1206
1207 cv::Mat C;
1208 cv::vconcat(A, B, C);
1209 //C:
1210 //[1, 7;
1211 // 2, 8;
1212 // 3, 9;
1213 // 4, 10;
1214 // 5, 11;
1215 // 6, 12]
1216 @endcode
1217 @param src1 first input array to be considered for vertical concatenation.
1218 @param src2 second input array to be considered for vertical concatenation.
1219 @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.
1220 */
1221 CV_EXPORTS void vconcat(InputArray src1, InputArray src2, OutputArray dst);
1222 /** @overload
1223 @code{.cpp}
1224 std::vector<cv::Mat> matrices = { cv::Mat(1, 4, CV_8UC1, cv::Scalar(1)),
1225 cv::Mat(1, 4, CV_8UC1, cv::Scalar(2)),
1226 cv::Mat(1, 4, CV_8UC1, cv::Scalar(3)),};
1227
1228 cv::Mat out;
1229 cv::vconcat( matrices, out );
1230 //out:
1231 //[1, 1, 1, 1;
1232 // 2, 2, 2, 2;
1233 // 3, 3, 3, 3]
1234 @endcode
1235 @param src input array or vector of matrices. all of the matrices must have the same number of cols and the same depth
1236 @param dst output array. It has the same number of cols and depth as the src, and the sum of rows of the src.
1237 same depth.
1238 */
1239 CV_EXPORTS_W void vconcat(InputArrayOfArrays src, OutputArray dst);
1240
1241 /** @brief computes bitwise conjunction of the two arrays (dst = src1 & src2)
1242 Calculates the per-element bit-wise conjunction of two arrays or an
1243 array and a scalar.
1244
1245 The function cv::bitwise_and calculates the per-element bit-wise logical conjunction for:
1246 * Two arrays when src1 and src2 have the same size:
1247 \f[\texttt{dst} (I) = \texttt{src1} (I) \wedge \texttt{src2} (I) \quad \texttt{if mask} (I) \ne0\f]
1248 * An array and a scalar when src2 is constructed from Scalar or has
1249 the same number of elements as `src1.channels()`:
1250 \f[\texttt{dst} (I) = \texttt{src1} (I) \wedge \texttt{src2} \quad \texttt{if mask} (I) \ne0\f]
1251 * A scalar and an array when src1 is constructed from Scalar or has
1252 the same number of elements as `src2.channels()`:
1253 \f[\texttt{dst} (I) = \texttt{src1} \wedge \texttt{src2} (I) \quad \texttt{if mask} (I) \ne0\f]
1254 In case of floating-point arrays, their machine-specific bit
1255 representations (usually IEEE754-compliant) are used for the operation.
1256 In case of multi-channel arrays, each channel is processed
1257 independently. In the second and third cases above, the scalar is first
1258 converted to the array type.
1259 @param src1 first input array or a scalar.
1260 @param src2 second input array or a scalar.
1261 @param dst output array that has the same size and type as the input
1262 arrays.
1263 @param mask optional operation mask, 8-bit single channel array, that
1264 specifies elements of the output array to be changed.
1265 */
1266 CV_EXPORTS_W void bitwise_and(InputArray src1, InputArray src2,
1267 OutputArray dst, InputArray mask = noArray());
1268
1269 /** @brief Calculates the per-element bit-wise disjunction of two arrays or an
1270 array and a scalar.
1271
1272 The function cv::bitwise_or calculates the per-element bit-wise logical disjunction for:
1273 * Two arrays when src1 and src2 have the same size:
1274 \f[\texttt{dst} (I) = \texttt{src1} (I) \vee \texttt{src2} (I) \quad \texttt{if mask} (I) \ne0\f]
1275 * An array and a scalar when src2 is constructed from Scalar or has
1276 the same number of elements as `src1.channels()`:
1277 \f[\texttt{dst} (I) = \texttt{src1} (I) \vee \texttt{src2} \quad \texttt{if mask} (I) \ne0\f]
1278 * A scalar and an array when src1 is constructed from Scalar or has
1279 the same number of elements as `src2.channels()`:
1280 \f[\texttt{dst} (I) = \texttt{src1} \vee \texttt{src2} (I) \quad \texttt{if mask} (I) \ne0\f]
1281 In case of floating-point arrays, their machine-specific bit
1282 representations (usually IEEE754-compliant) are used for the operation.
1283 In case of multi-channel arrays, each channel is processed
1284 independently. In the second and third cases above, the scalar is first
1285 converted to the array type.
1286 @param src1 first input array or a scalar.
1287 @param src2 second input array or a scalar.
1288 @param dst output array that has the same size and type as the input
1289 arrays.
1290 @param mask optional operation mask, 8-bit single channel array, that
1291 specifies elements of the output array to be changed.
1292 */
1293 CV_EXPORTS_W void bitwise_or(InputArray src1, InputArray src2,
1294 OutputArray dst, InputArray mask = noArray());
1295
1296 /** @brief Calculates the per-element bit-wise "exclusive or" operation on two
1297 arrays or an array and a scalar.
1298
1299 The function cv::bitwise_xor calculates the per-element bit-wise logical "exclusive-or"
1300 operation for:
1301 * Two arrays when src1 and src2 have the same size:
1302 \f[\texttt{dst} (I) = \texttt{src1} (I) \oplus \texttt{src2} (I) \quad \texttt{if mask} (I) \ne0\f]
1303 * An array and a scalar when src2 is constructed from Scalar or has
1304 the same number of elements as `src1.channels()`:
1305 \f[\texttt{dst} (I) = \texttt{src1} (I) \oplus \texttt{src2} \quad \texttt{if mask} (I) \ne0\f]
1306 * A scalar and an array when src1 is constructed from Scalar or has
1307 the same number of elements as `src2.channels()`:
1308 \f[\texttt{dst} (I) = \texttt{src1} \oplus \texttt{src2} (I) \quad \texttt{if mask} (I) \ne0\f]
1309 In case of floating-point arrays, their machine-specific bit
1310 representations (usually IEEE754-compliant) are used for the operation.
1311 In case of multi-channel arrays, each channel is processed
1312 independently. In the 2nd and 3rd cases above, the scalar is first
1313 converted to the array type.
1314 @param src1 first input array or a scalar.
1315 @param src2 second input array or a scalar.
1316 @param dst output array that has the same size and type as the input
1317 arrays.
1318 @param mask optional operation mask, 8-bit single channel array, that
1319 specifies elements of the output array to be changed.
1320 */
1321 CV_EXPORTS_W void bitwise_xor(InputArray src1, InputArray src2,
1322 OutputArray dst, InputArray mask = noArray());
1323
1324 /** @brief Inverts every bit of an array.
1325
1326 The function cv::bitwise_not calculates per-element bit-wise inversion of the input
1327 array:
1328 \f[\texttt{dst} (I) = \neg \texttt{src} (I)\f]
1329 In case of a floating-point input array, its machine-specific bit
1330 representation (usually IEEE754-compliant) is used for the operation. In
1331 case of multi-channel arrays, each channel is processed independently.
1332 @param src input array.
1333 @param dst output array that has the same size and type as the input
1334 array.
1335 @param mask optional operation mask, 8-bit single channel array, that
1336 specifies elements of the output array to be changed.
1337 */
1338 CV_EXPORTS_W void bitwise_not(InputArray src, OutputArray dst,
1339 InputArray mask = noArray());
1340
1341 /** @brief Calculates the per-element absolute difference between two arrays or between an array and a scalar.
1342
1343 The function cv::absdiff calculates:
1344 * Absolute difference between two arrays when they have the same
1345 size and type:
1346 \f[\texttt{dst}(I) = \texttt{saturate} (| \texttt{src1}(I) - \texttt{src2}(I)|)\f]
1347 * Absolute difference between an array and a scalar when the second
1348 array is constructed from Scalar or has as many elements as the
1349 number of channels in `src1`:
1350 \f[\texttt{dst}(I) = \texttt{saturate} (| \texttt{src1}(I) - \texttt{src2} |)\f]
1351 * Absolute difference between a scalar and an array when the first
1352 array is constructed from Scalar or has as many elements as the
1353 number of channels in `src2`:
1354 \f[\texttt{dst}(I) = \texttt{saturate} (| \texttt{src1} - \texttt{src2}(I) |)\f]
1355 where I is a multi-dimensional index of array elements. In case of
1356 multi-channel arrays, each channel is processed independently.
1357 @note Saturation is not applied when the arrays have the depth CV_32S.
1358 You may even get a negative value in the case of overflow.
1359 @param src1 first input array or a scalar.
1360 @param src2 second input array or a scalar.
1361 @param dst output array that has the same size and type as input arrays.
1362 @sa cv::abs(const Mat&)
1363 */
1364 CV_EXPORTS_W void absdiff(InputArray src1, InputArray src2, OutputArray dst);
1365
1366 /** @brief This is an overloaded member function, provided for convenience (python)
1367 Copies the matrix to another one.
1368 When the operation mask is specified, if the Mat::create call shown above reallocates the matrix, the newly allocated matrix is initialized with all zeros before copying the data.
1369 @param src source matrix.
1370 @param dst Destination matrix. If it does not have a proper size or type before the operation, it is
1371 reallocated.
1372 @param mask Operation mask of the same size as \*this. Its non-zero elements indicate which matrix
1373 elements need to be copied. The mask has to be of type CV_8U and can have 1 or multiple channels.
1374 */
1375
1376 void CV_EXPORTS_W copyTo(InputArray src, OutputArray dst, InputArray mask);
1377 /** @brief Checks if array elements lie between the elements of two other arrays.
1378
1379 The function checks the range as follows:
1380 - For every element of a single-channel input array:
1381 \f[\texttt{dst} (I)= \texttt{lowerb} (I)_0 \leq \texttt{src} (I)_0 \leq \texttt{upperb} (I)_0\f]
1382 - For two-channel arrays:
1383 \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]
1384 - and so forth.
1385
1386 That is, dst (I) is set to 255 (all 1 -bits) if src (I) is within the
1387 specified 1D, 2D, 3D, ... box and 0 otherwise.
1388
1389 When the lower and/or upper boundary parameters are scalars, the indexes
1390 (I) at lowerb and upperb in the above formulas should be omitted.
1391 @param src first input array.
1392 @param lowerb inclusive lower boundary array or a scalar.
1393 @param upperb inclusive upper boundary array or a scalar.
1394 @param dst output array of the same size as src and CV_8U type.
1395 */
1396 CV_EXPORTS_W void inRange(InputArray src, InputArray lowerb,
1397 InputArray upperb, OutputArray dst);
1398
1399 /** @brief Performs the per-element comparison of two arrays or an array and scalar value.
1400
1401 The function compares:
1402 * Elements of two arrays when src1 and src2 have the same size:
1403 \f[\texttt{dst} (I) = \texttt{src1} (I) \,\texttt{cmpop}\, \texttt{src2} (I)\f]
1404 * Elements of src1 with a scalar src2 when src2 is constructed from
1405 Scalar or has a single element:
1406 \f[\texttt{dst} (I) = \texttt{src1}(I) \,\texttt{cmpop}\, \texttt{src2}\f]
1407 * src1 with elements of src2 when src1 is constructed from Scalar or
1408 has a single element:
1409 \f[\texttt{dst} (I) = \texttt{src1} \,\texttt{cmpop}\, \texttt{src2} (I)\f]
1410 When the comparison result is true, the corresponding element of output
1411 array is set to 255. The comparison operations can be replaced with the
1412 equivalent matrix expressions:
1413 @code{.cpp}
1414 Mat dst1 = src1 >= src2;
1415 Mat dst2 = src1 < 8;
1416 ...
1417 @endcode
1418 @param src1 first input array or a scalar; when it is an array, it must have a single channel.
1419 @param src2 second input array or a scalar; when it is an array, it must have a single channel.
1420 @param dst output array of type ref CV_8U that has the same size and the same number of channels as
1421 the input arrays.
1422 @param cmpop a flag, that specifies correspondence between the arrays (cv::CmpTypes)
1423 @sa checkRange, min, max, threshold
1424 */
1425 CV_EXPORTS_W void compare(InputArray src1, InputArray src2, OutputArray dst, int cmpop);
1426
1427 /** @brief Calculates per-element minimum of two arrays or an array and a scalar.
1428
1429 The function cv::min calculates the per-element minimum of two arrays:
1430 \f[\texttt{dst} (I)= \min ( \texttt{src1} (I), \texttt{src2} (I))\f]
1431 or array and a scalar:
1432 \f[\texttt{dst} (I)= \min ( \texttt{src1} (I), \texttt{value} )\f]
1433 @param src1 first input array.
1434 @param src2 second input array of the same size and type as src1.
1435 @param dst output array of the same size and type as src1.
1436 @sa max, compare, inRange, minMaxLoc
1437 */
1438 CV_EXPORTS_W void min(InputArray src1, InputArray src2, OutputArray dst);
1439 /** @overload
1440 needed to avoid conflicts with const _Tp& std::min(const _Tp&, const _Tp&, _Compare)
1441 */
1442 CV_EXPORTS void min(const Mat& src1, const Mat& src2, Mat& dst);
1443 /** @overload
1444 needed to avoid conflicts with const _Tp& std::min(const _Tp&, const _Tp&, _Compare)
1445 */
1446 CV_EXPORTS void min(const UMat& src1, const UMat& src2, UMat& dst);
1447
1448 /** @brief Calculates per-element maximum of two arrays or an array and a scalar.
1449
1450 The function cv::max calculates the per-element maximum of two arrays:
1451 \f[\texttt{dst} (I)= \max ( \texttt{src1} (I), \texttt{src2} (I))\f]
1452 or array and a scalar:
1453 \f[\texttt{dst} (I)= \max ( \texttt{src1} (I), \texttt{value} )\f]
1454 @param src1 first input array.
1455 @param src2 second input array of the same size and type as src1 .
1456 @param dst output array of the same size and type as src1.
1457 @sa min, compare, inRange, minMaxLoc, @ref MatrixExpressions
1458 */
1459 CV_EXPORTS_W void max(InputArray src1, InputArray src2, OutputArray dst);
1460 /** @overload
1461 needed to avoid conflicts with const _Tp& std::min(const _Tp&, const _Tp&, _Compare)
1462 */
1463 CV_EXPORTS void max(const Mat& src1, const Mat& src2, Mat& dst);
1464 /** @overload
1465 needed to avoid conflicts with const _Tp& std::min(const _Tp&, const _Tp&, _Compare)
1466 */
1467 CV_EXPORTS void max(const UMat& src1, const UMat& src2, UMat& dst);
1468
1469 /** @brief Calculates a square root of array elements.
1470
1471 The function cv::sqrt calculates a square root of each input array element.
1472 In case of multi-channel arrays, each channel is processed
1473 independently. The accuracy is approximately the same as of the built-in
1474 std::sqrt .
1475 @param src input floating-point array.
1476 @param dst output array of the same size and type as src.
1477 */
1478 CV_EXPORTS_W void sqrt(InputArray src, OutputArray dst);
1479
1480 /** @brief Raises every array element to a power.
1481
1482 The function cv::pow raises every element of the input array to power :
1483 \f[\texttt{dst} (I) = \fork{\texttt{src}(I)^{power}}{if \(\texttt{power}\) is integer}{|\texttt{src}(I)|^{power}}{otherwise}\f]
1484
1485 So, for a non-integer power exponent, the absolute values of input array
1486 elements are used. However, it is possible to get true values for
1487 negative values using some extra operations. In the example below,
1488 computing the 5th root of array src shows:
1489 @code{.cpp}
1490 Mat mask = src < 0;
1491 pow(src, 1./5, dst);
1492 subtract(Scalar::all(0), dst, dst, mask);
1493 @endcode
1494 For some values of power, such as integer values, 0.5 and -0.5,
1495 specialized faster algorithms are used.
1496
1497 Special values (NaN, Inf) are not handled.
1498 @param src input array.
1499 @param power exponent of power.
1500 @param dst output array of the same size and type as src.
1501 @sa sqrt, exp, log, cartToPolar, polarToCart
1502 */
1503 CV_EXPORTS_W void pow(InputArray src, double power, OutputArray dst);
1504
1505 /** @brief Calculates the exponent of every array element.
1506
1507 The function cv::exp calculates the exponent of every element of the input
1508 array:
1509 \f[\texttt{dst} [I] = e^{ src(I) }\f]
1510
1511 The maximum relative error is about 7e-6 for single-precision input and
1512 less than 1e-10 for double-precision input. Currently, the function
1513 converts denormalized values to zeros on output. Special values (NaN,
1514 Inf) are not handled.
1515 @param src input array.
1516 @param dst output array of the same size and type as src.
1517 @sa log , cartToPolar , polarToCart , phase , pow , sqrt , magnitude
1518 */
1519 CV_EXPORTS_W void exp(InputArray src, OutputArray dst);
1520
1521 /** @brief Calculates the natural logarithm of every array element.
1522
1523 The function cv::log calculates the natural logarithm of every element of the input array:
1524 \f[\texttt{dst} (I) = \log (\texttt{src}(I)) \f]
1525
1526 Output on zero, negative and special (NaN, Inf) values is undefined.
1527
1528 @param src input array.
1529 @param dst output array of the same size and type as src .
1530 @sa exp, cartToPolar, polarToCart, phase, pow, sqrt, magnitude
1531 */
1532 CV_EXPORTS_W void log(InputArray src, OutputArray dst);
1533
1534 /** @brief Calculates x and y coordinates of 2D vectors from their magnitude and angle.
1535
1536 The function cv::polarToCart calculates the Cartesian coordinates of each 2D
1537 vector represented by the corresponding elements of magnitude and angle:
1538 \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]
1539
1540 The relative accuracy of the estimated coordinates is about 1e-6.
1541 @param magnitude input floating-point array of magnitudes of 2D vectors;
1542 it can be an empty matrix (=Mat()), in this case, the function assumes
1543 that all the magnitudes are =1; if it is not empty, it must have the
1544 same size and type as angle.
1545 @param angle input floating-point array of angles of 2D vectors.
1546 @param x output array of x-coordinates of 2D vectors; it has the same
1547 size and type as angle.
1548 @param y output array of y-coordinates of 2D vectors; it has the same
1549 size and type as angle.
1550 @param angleInDegrees when true, the input angles are measured in
1551 degrees, otherwise, they are measured in radians.
1552 @sa cartToPolar, magnitude, phase, exp, log, pow, sqrt
1553 */
1554 CV_EXPORTS_W void polarToCart(InputArray magnitude, InputArray angle,
1555 OutputArray x, OutputArray y, bool angleInDegrees = false);
1556
1557 /** @brief Calculates the magnitude and angle of 2D vectors.
1558
1559 The function cv::cartToPolar calculates either the magnitude, angle, or both
1560 for every 2D vector (x(I),y(I)):
1561 \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]
1562
1563 The angles are calculated with accuracy about 0.3 degrees. For the point
1564 (0,0), the angle is set to 0.
1565 @param x array of x-coordinates; this must be a single-precision or
1566 double-precision floating-point array.
1567 @param y array of y-coordinates, that must have the same size and same type as x.
1568 @param magnitude output array of magnitudes of the same size and type as x.
1569 @param angle output array of angles that has the same size and type as
1570 x; the angles are measured in radians (from 0 to 2\*Pi) or in degrees (0 to 360 degrees).
1571 @param angleInDegrees a flag, indicating whether the angles are measured
1572 in radians (which is by default), or in degrees.
1573 @sa Sobel, Scharr
1574 */
1575 CV_EXPORTS_W void cartToPolar(InputArray x, InputArray y,
1576 OutputArray magnitude, OutputArray angle,
1577 bool angleInDegrees = false);
1578
1579 /** @brief Calculates the rotation angle of 2D vectors.
1580
1581 The function cv::phase calculates the rotation angle of each 2D vector that
1582 is formed from the corresponding elements of x and y :
1583 \f[\texttt{angle} (I) = \texttt{atan2} ( \texttt{y} (I), \texttt{x} (I))\f]
1584
1585 The angle estimation accuracy is about 0.3 degrees. When x(I)=y(I)=0 ,
1586 the corresponding angle(I) is set to 0.
1587 @param x input floating-point array of x-coordinates of 2D vectors.
1588 @param y input array of y-coordinates of 2D vectors; it must have the
1589 same size and the same type as x.
1590 @param angle output array of vector angles; it has the same size and
1591 same type as x .
1592 @param angleInDegrees when true, the function calculates the angle in
1593 degrees, otherwise, they are measured in radians.
1594 */
1595 CV_EXPORTS_W void phase(InputArray x, InputArray y, OutputArray angle,
1596 bool angleInDegrees = false);
1597
1598 /** @brief Calculates the magnitude of 2D vectors.
1599
1600 The function cv::magnitude calculates the magnitude of 2D vectors formed
1601 from the corresponding elements of x and y arrays:
1602 \f[\texttt{dst} (I) = \sqrt{\texttt{x}(I)^2 + \texttt{y}(I)^2}\f]
1603 @param x floating-point array of x-coordinates of the vectors.
1604 @param y floating-point array of y-coordinates of the vectors; it must
1605 have the same size as x.
1606 @param magnitude output array of the same size and type as x.
1607 @sa cartToPolar, polarToCart, phase, sqrt
1608 */
1609 CV_EXPORTS_W void magnitude(InputArray x, InputArray y, OutputArray magnitude);
1610
1611 /** @brief Checks every element of an input array for invalid values.
1612
1613 The function cv::checkRange checks that every array element is neither NaN nor infinite. When minVal \>
1614 -DBL_MAX and maxVal \< DBL_MAX, the function also checks that each value is between minVal and
1615 maxVal. In case of multi-channel arrays, each channel is processed independently. If some values
1616 are out of range, position of the first outlier is stored in pos (when pos != NULL). Then, the
1617 function either returns false (when quiet=true) or throws an exception.
1618 @param a input array.
1619 @param quiet a flag, indicating whether the functions quietly return false when the array elements
1620 are out of range or they throw an exception.
1621 @param pos optional output parameter, when not NULL, must be a pointer to array of src.dims
1622 elements.
1623 @param minVal inclusive lower boundary of valid values range.
1624 @param maxVal exclusive upper boundary of valid values range.
1625 */
1626 CV_EXPORTS_W bool checkRange(InputArray a, bool quiet = true, CV_OUT Point* pos = 0,
1627 double minVal = -DBL_MAX, double maxVal = DBL_MAX);
1628
1629 /** @brief converts NaNs to the given number
1630 @param a input/output matrix (CV_32F type).
1631 @param val value to convert the NaNs
1632 */
1633 CV_EXPORTS_W void patchNaNs(InputOutputArray a, double val = 0);
1634
1635 /** @brief Performs generalized matrix multiplication.
1636
1637 The function cv::gemm performs generalized matrix multiplication similar to the
1638 gemm functions in BLAS level 3. For example,
1639 `gemm(src1, src2, alpha, src3, beta, dst, GEMM_1_T + GEMM_3_T)`
1640 corresponds to
1641 \f[\texttt{dst} = \texttt{alpha} \cdot \texttt{src1} ^T \cdot \texttt{src2} + \texttt{beta} \cdot \texttt{src3} ^T\f]
1642
1643 In case of complex (two-channel) data, performed a complex matrix
1644 multiplication.
1645
1646 The function can be replaced with a matrix expression. For example, the
1647 above call can be replaced with:
1648 @code{.cpp}
1649 dst = alpha*src1.t()*src2 + beta*src3.t();
1650 @endcode
1651 @param src1 first multiplied input matrix that could be real(CV_32FC1,
1652 CV_64FC1) or complex(CV_32FC2, CV_64FC2).
1653 @param src2 second multiplied input matrix of the same type as src1.
1654 @param alpha weight of the matrix product.
1655 @param src3 third optional delta matrix added to the matrix product; it
1656 should have the same type as src1 and src2.
1657 @param beta weight of src3.
1658 @param dst output matrix; it has the proper size and the same type as
1659 input matrices.
1660 @param flags operation flags (cv::GemmFlags)
1661 @sa mulTransposed , transform
1662 */
1663 CV_EXPORTS_W void gemm(InputArray src1, InputArray src2, double alpha,
1664 InputArray src3, double beta, OutputArray dst, int flags = 0);
1665
1666 /** @brief Calculates the product of a matrix and its transposition.
1667
1668 The function cv::mulTransposed calculates the product of src and its
1669 transposition:
1670 \f[\texttt{dst} = \texttt{scale} ( \texttt{src} - \texttt{delta} )^T ( \texttt{src} - \texttt{delta} )\f]
1671 if aTa=true , and
1672 \f[\texttt{dst} = \texttt{scale} ( \texttt{src} - \texttt{delta} ) ( \texttt{src} - \texttt{delta} )^T\f]
1673 otherwise. The function is used to calculate the covariance matrix. With
1674 zero delta, it can be used as a faster substitute for general matrix
1675 product A\*B when B=A'
1676 @param src input single-channel matrix. Note that unlike gemm, the
1677 function can multiply not only floating-point matrices.
1678 @param dst output square matrix.
1679 @param aTa Flag specifying the multiplication ordering. See the
1680 description below.
1681 @param delta Optional delta matrix subtracted from src before the
1682 multiplication. When the matrix is empty ( delta=noArray() ), it is
1683 assumed to be zero, that is, nothing is subtracted. If it has the same
1684 size as src , it is simply subtracted. Otherwise, it is "repeated" (see
1685 repeat ) to cover the full src and then subtracted. Type of the delta
1686 matrix, when it is not empty, must be the same as the type of created
1687 output matrix. See the dtype parameter description below.
1688 @param scale Optional scale factor for the matrix product.
1689 @param dtype Optional type of the output matrix. When it is negative,
1690 the output matrix will have the same type as src . Otherwise, it will be
1691 type=CV_MAT_DEPTH(dtype) that should be either CV_32F or CV_64F .
1692 @sa calcCovarMatrix, gemm, repeat, reduce
1693 */
1694 CV_EXPORTS_W void mulTransposed( InputArray src, OutputArray dst, bool aTa,
1695 InputArray delta = noArray(),
1696 double scale = 1, int dtype = -1 );
1697
1698 /** @brief Transposes a matrix.
1699
1700 The function cv::transpose transposes the matrix src :
1701 \f[\texttt{dst} (i,j) = \texttt{src} (j,i)\f]
1702 @note No complex conjugation is done in case of a complex matrix. It
1703 should be done separately if needed.
1704 @param src input array.
1705 @param dst output array of the same type as src.
1706 */
1707 CV_EXPORTS_W void transpose(InputArray src, OutputArray dst);
1708
1709 /** @brief Performs the matrix transformation of every array element.
1710
1711 The function cv::transform performs the matrix transformation of every
1712 element of the array src and stores the results in dst :
1713 \f[\texttt{dst} (I) = \texttt{m} \cdot \texttt{src} (I)\f]
1714 (when m.cols=src.channels() ), or
1715 \f[\texttt{dst} (I) = \texttt{m} \cdot [ \texttt{src} (I); 1]\f]
1716 (when m.cols=src.channels()+1 )
1717
1718 Every element of the N -channel array src is interpreted as N -element
1719 vector that is transformed using the M x N or M x (N+1) matrix m to
1720 M-element vector - the corresponding element of the output array dst .
1721
1722 The function may be used for geometrical transformation of
1723 N -dimensional points, arbitrary linear color space transformation (such
1724 as various kinds of RGB to YUV transforms), shuffling the image
1725 channels, and so forth.
1726 @param src input array that must have as many channels (1 to 4) as
1727 m.cols or m.cols-1.
1728 @param dst output array of the same size and depth as src; it has as
1729 many channels as m.rows.
1730 @param m transformation 2x2 or 2x3 floating-point matrix.
1731 @sa perspectiveTransform, getAffineTransform, estimateAffine2D, warpAffine, warpPerspective
1732 */
1733 CV_EXPORTS_W void transform(InputArray src, OutputArray dst, InputArray m );
1734
1735 /** @brief Performs the perspective matrix transformation of vectors.
1736
1737 The function cv::perspectiveTransform transforms every element of src by
1738 treating it as a 2D or 3D vector, in the following way:
1739 \f[(x, y, z) \rightarrow (x'/w, y'/w, z'/w)\f]
1740 where
1741 \f[(x', y', z', w') = \texttt{mat} \cdot \begin{bmatrix} x & y & z & 1 \end{bmatrix}\f]
1742 and
1743 \f[w = \fork{w'}{if \(w' \ne 0\)}{\infty}{otherwise}\f]
1744
1745 Here a 3D vector transformation is shown. In case of a 2D vector
1746 transformation, the z component is omitted.
1747
1748 @note The function transforms a sparse set of 2D or 3D vectors. If you
1749 want to transform an image using perspective transformation, use
1750 warpPerspective . If you have an inverse problem, that is, you want to
1751 compute the most probable perspective transformation out of several
1752 pairs of corresponding points, you can use getPerspectiveTransform or
1753 findHomography .
1754 @param src input two-channel or three-channel floating-point array; each
1755 element is a 2D/3D vector to be transformed.
1756 @param dst output array of the same size and type as src.
1757 @param m 3x3 or 4x4 floating-point transformation matrix.
1758 @sa transform, warpPerspective, getPerspectiveTransform, findHomography
1759 */
1760 CV_EXPORTS_W void perspectiveTransform(InputArray src, OutputArray dst, InputArray m );
1761
1762 /** @brief Copies the lower or the upper half of a square matrix to its another half.
1763
1764 The function cv::completeSymm copies the lower or the upper half of a square matrix to
1765 its another half. The matrix diagonal remains unchanged:
1766 - \f$\texttt{m}_{ij}=\texttt{m}_{ji}\f$ for \f$i > j\f$ if
1767 lowerToUpper=false
1768 - \f$\texttt{m}_{ij}=\texttt{m}_{ji}\f$ for \f$i < j\f$ if
1769 lowerToUpper=true
1770
1771 @param m input-output floating-point square matrix.
1772 @param lowerToUpper operation flag; if true, the lower half is copied to
1773 the upper half. Otherwise, the upper half is copied to the lower half.
1774 @sa flip, transpose
1775 */
1776 CV_EXPORTS_W void completeSymm(InputOutputArray m, bool lowerToUpper = false);
1777
1778 /** @brief Initializes a scaled identity matrix.
1779
1780 The function cv::setIdentity initializes a scaled identity matrix:
1781 \f[\texttt{mtx} (i,j)= \fork{\texttt{value}}{ if \(i=j\)}{0}{otherwise}\f]
1782
1783 The function can also be emulated using the matrix initializers and the
1784 matrix expressions:
1785 @code
1786 Mat A = Mat::eye(4, 3, CV_32F)*5;
1787 // A will be set to [[5, 0, 0], [0, 5, 0], [0, 0, 5], [0, 0, 0]]
1788 @endcode
1789 @param mtx matrix to initialize (not necessarily square).
1790 @param s value to assign to diagonal elements.
1791 @sa Mat::zeros, Mat::ones, Mat::setTo, Mat::operator=
1792 */
1793 CV_EXPORTS_W void setIdentity(InputOutputArray mtx, const Scalar& s = Scalar(1));
1794
1795 /** @brief Returns the determinant of a square floating-point matrix.
1796
1797 The function cv::determinant calculates and returns the determinant of the
1798 specified matrix. For small matrices ( mtx.cols=mtx.rows\<=3 ), the
1799 direct method is used. For larger matrices, the function uses LU
1800 factorization with partial pivoting.
1801
1802 For symmetric positively-determined matrices, it is also possible to use
1803 eigen decomposition to calculate the determinant.
1804 @param mtx input matrix that must have CV_32FC1 or CV_64FC1 type and
1805 square size.
1806 @sa trace, invert, solve, eigen, @ref MatrixExpressions
1807 */
1808 CV_EXPORTS_W double determinant(InputArray mtx);
1809
1810 /** @brief Returns the trace of a matrix.
1811
1812 The function cv::trace returns the sum of the diagonal elements of the
1813 matrix mtx .
1814 \f[\mathrm{tr} ( \texttt{mtx} ) = \sum _i \texttt{mtx} (i,i)\f]
1815 @param mtx input matrix.
1816 */
1817 CV_EXPORTS_W Scalar trace(InputArray mtx);
1818
1819 /** @brief Finds the inverse or pseudo-inverse of a matrix.
1820
1821 The function cv::invert inverts the matrix src and stores the result in dst
1822 . When the matrix src is singular or non-square, the function calculates
1823 the pseudo-inverse matrix (the dst matrix) so that norm(src\*dst - I) is
1824 minimal, where I is an identity matrix.
1825
1826 In case of the #DECOMP_LU method, the function returns non-zero value if
1827 the inverse has been successfully calculated and 0 if src is singular.
1828
1829 In case of the #DECOMP_SVD method, the function returns the inverse
1830 condition number of src (the ratio of the smallest singular value to the
1831 largest singular value) and 0 if src is singular. The SVD method
1832 calculates a pseudo-inverse matrix if src is singular.
1833
1834 Similarly to #DECOMP_LU, the method #DECOMP_CHOLESKY works only with
1835 non-singular square matrices that should also be symmetrical and
1836 positively defined. In this case, the function stores the inverted
1837 matrix in dst and returns non-zero. Otherwise, it returns 0.
1838
1839 @param src input floating-point M x N matrix.
1840 @param dst output matrix of N x M size and the same type as src.
1841 @param flags inversion method (cv::DecompTypes)
1842 @sa solve, SVD
1843 */
1844 CV_EXPORTS_W double invert(InputArray src, OutputArray dst, int flags = DECOMP_LU);
1845
1846 /** @brief Solves one or more linear systems or least-squares problems.
1847
1848 The function cv::solve solves a linear system or least-squares problem (the
1849 latter is possible with SVD or QR methods, or by specifying the flag
1850 #DECOMP_NORMAL ):
1851 \f[\texttt{dst} = \arg \min _X \| \texttt{src1} \cdot \texttt{X} - \texttt{src2} \|\f]
1852
1853 If #DECOMP_LU or #DECOMP_CHOLESKY method is used, the function returns 1
1854 if src1 (or \f$\texttt{src1}^T\texttt{src1}\f$ ) is non-singular. Otherwise,
1855 it returns 0. In the latter case, dst is not valid. Other methods find a
1856 pseudo-solution in case of a singular left-hand side part.
1857
1858 @note If you want to find a unity-norm solution of an under-defined
1859 singular system \f$\texttt{src1}\cdot\texttt{dst}=0\f$ , the function solve
1860 will not do the work. Use SVD::solveZ instead.
1861
1862 @param src1 input matrix on the left-hand side of the system.
1863 @param src2 input matrix on the right-hand side of the system.
1864 @param dst output solution.
1865 @param flags solution (matrix inversion) method (#DecompTypes)
1866 @sa invert, SVD, eigen
1867 */
1868 CV_EXPORTS_W bool solve(InputArray src1, InputArray src2,
1869 OutputArray dst, int flags = DECOMP_LU);
1870
1871 /** @brief Sorts each row or each column of a matrix.
1872
1873 The function cv::sort sorts each matrix row or each matrix column in
1874 ascending or descending order. So you should pass two operation flags to
1875 get desired behaviour. If you want to sort matrix rows or columns
1876 lexicographically, you can use STL std::sort generic function with the
1877 proper comparison predicate.
1878
1879 @param src input single-channel array.
1880 @param dst output array of the same size and type as src.
1881 @param flags operation flags, a combination of #SortFlags
1882 @sa sortIdx, randShuffle
1883 */
1884 CV_EXPORTS_W void sort(InputArray src, OutputArray dst, int flags);
1885
1886 /** @brief Sorts each row or each column of a matrix.
1887
1888 The function cv::sortIdx sorts each matrix row or each matrix column in the
1889 ascending or descending order. So you should pass two operation flags to
1890 get desired behaviour. Instead of reordering the elements themselves, it
1891 stores the indices of sorted elements in the output array. For example:
1892 @code
1893 Mat A = Mat::eye(3,3,CV_32F), B;
1894 sortIdx(A, B, SORT_EVERY_ROW + SORT_ASCENDING);
1895 // B will probably contain
1896 // (because of equal elements in A some permutations are possible):
1897 // [[1, 2, 0], [0, 2, 1], [0, 1, 2]]
1898 @endcode
1899 @param src input single-channel array.
1900 @param dst output integer array of the same size as src.
1901 @param flags operation flags that could be a combination of cv::SortFlags
1902 @sa sort, randShuffle
1903 */
1904 CV_EXPORTS_W void sortIdx(InputArray src, OutputArray dst, int flags);
1905
1906 /** @brief Finds the real roots of a cubic equation.
1907
1908 The function solveCubic finds the real roots of a cubic equation:
1909 - if coeffs is a 4-element vector:
1910 \f[\texttt{coeffs} [0] x^3 + \texttt{coeffs} [1] x^2 + \texttt{coeffs} [2] x + \texttt{coeffs} [3] = 0\f]
1911 - if coeffs is a 3-element vector:
1912 \f[x^3 + \texttt{coeffs} [0] x^2 + \texttt{coeffs} [1] x + \texttt{coeffs} [2] = 0\f]
1913
1914 The roots are stored in the roots array.
1915 @param coeffs equation coefficients, an array of 3 or 4 elements.
1916 @param roots output array of real roots that has 1 or 3 elements.
1917 @return number of real roots. It can be 0, 1 or 2.
1918 */
1919 CV_EXPORTS_W int solveCubic(InputArray coeffs, OutputArray roots);
1920
1921 /** @brief Finds the real or complex roots of a polynomial equation.
1922
1923 The function cv::solvePoly finds real and complex roots of a polynomial equation:
1924 \f[\texttt{coeffs} [n] x^{n} + \texttt{coeffs} [n-1] x^{n-1} + ... + \texttt{coeffs} [1] x + \texttt{coeffs} [0] = 0\f]
1925 @param coeffs array of polynomial coefficients.
1926 @param roots output (complex) array of roots.
1927 @param maxIters maximum number of iterations the algorithm does.
1928 */
1929 CV_EXPORTS_W double solvePoly(InputArray coeffs, OutputArray roots, int maxIters = 300);
1930
1931 /** @brief Calculates eigenvalues and eigenvectors of a symmetric matrix.
1932
1933 The function cv::eigen calculates just eigenvalues, or eigenvalues and eigenvectors of the symmetric
1934 matrix src:
1935 @code
1936 src*eigenvectors.row(i).t() = eigenvalues.at<srcType>(i)*eigenvectors.row(i).t()
1937 @endcode
1938
1939 @note Use cv::eigenNonSymmetric for calculation of real eigenvalues and eigenvectors of non-symmetric matrix.
1940
1941 @param src input matrix that must have CV_32FC1 or CV_64FC1 type, square size and be symmetrical
1942 (src ^T^ == src).
1943 @param eigenvalues output vector of eigenvalues of the same type as src; the eigenvalues are stored
1944 in the descending order.
1945 @param eigenvectors output matrix of eigenvectors; it has the same size and type as src; the
1946 eigenvectors are stored as subsequent matrix rows, in the same order as the corresponding
1947 eigenvalues.
1948 @sa eigenNonSymmetric, completeSymm , PCA
1949 */
1950 CV_EXPORTS_W bool eigen(InputArray src, OutputArray eigenvalues,
1951 OutputArray eigenvectors = noArray());
1952
1953 /** @brief Calculates eigenvalues and eigenvectors of a non-symmetric matrix (real eigenvalues only).
1954
1955 @note Assumes real eigenvalues.
1956
1957 The function calculates eigenvalues and eigenvectors (optional) of the square matrix src:
1958 @code
1959 src*eigenvectors.row(i).t() = eigenvalues.at<srcType>(i)*eigenvectors.row(i).t()
1960 @endcode
1961
1962 @param src input matrix (CV_32FC1 or CV_64FC1 type).
1963 @param eigenvalues output vector of eigenvalues (type is the same type as src).
1964 @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.
1965 @sa eigen
1966 */
1967 CV_EXPORTS_W void eigenNonSymmetric(InputArray src, OutputArray eigenvalues,
1968 OutputArray eigenvectors);
1969
1970 /** @brief Calculates the covariance matrix of a set of vectors.
1971
1972 The function cv::calcCovarMatrix calculates the covariance matrix and, optionally, the mean vector of
1973 the set of input vectors.
1974 @param samples samples stored as separate matrices
1975 @param nsamples number of samples
1976 @param covar output covariance matrix of the type ctype and square size.
1977 @param mean input or output (depending on the flags) array as the average value of the input vectors.
1978 @param flags operation flags as a combination of #CovarFlags
1979 @param ctype type of the matrixl; it equals 'CV_64F' by default.
1980 @sa PCA, mulTransposed, Mahalanobis
1981 @todo InputArrayOfArrays
1982 */
1983 CV_EXPORTS void calcCovarMatrix( const Mat* samples, int nsamples, Mat& covar, Mat& mean,
1984 int flags, int ctype = CV_64F);
1985
1986 /** @overload
1987 @note use #COVAR_ROWS or #COVAR_COLS flag
1988 @param samples samples stored as rows/columns of a single matrix.
1989 @param covar output covariance matrix of the type ctype and square size.
1990 @param mean input or output (depending on the flags) array as the average value of the input vectors.
1991 @param flags operation flags as a combination of #CovarFlags
1992 @param ctype type of the matrixl; it equals 'CV_64F' by default.
1993 */
1994 CV_EXPORTS_W void calcCovarMatrix( InputArray samples, OutputArray covar,
1995 InputOutputArray mean, int flags, int ctype = CV_64F);
1996
1997 /** wrap PCA::operator() */
1998 CV_EXPORTS_W void PCACompute(InputArray data, InputOutputArray mean,
1999 OutputArray eigenvectors, int maxComponents = 0);
2000
2001 /** wrap PCA::operator() and add eigenvalues output parameter */
2002 CV_EXPORTS_AS(PCACompute2) void PCACompute(InputArray data, InputOutputArray mean,
2003 OutputArray eigenvectors, OutputArray eigenvalues,
2004 int maxComponents = 0);
2005
2006 /** wrap PCA::operator() */
2007 CV_EXPORTS_W void PCACompute(InputArray data, InputOutputArray mean,
2008 OutputArray eigenvectors, double retainedVariance);
2009
2010 /** wrap PCA::operator() and add eigenvalues output parameter */
2011 CV_EXPORTS_AS(PCACompute2) void PCACompute(InputArray data, InputOutputArray mean,
2012 OutputArray eigenvectors, OutputArray eigenvalues,
2013 double retainedVariance);
2014
2015 /** wrap PCA::project */
2016 CV_EXPORTS_W void PCAProject(InputArray data, InputArray mean,
2017 InputArray eigenvectors, OutputArray result);
2018
2019 /** wrap PCA::backProject */
2020 CV_EXPORTS_W void PCABackProject(InputArray data, InputArray mean,
2021 InputArray eigenvectors, OutputArray result);
2022
2023 /** wrap SVD::compute */
2024 CV_EXPORTS_W void SVDecomp( InputArray src, OutputArray w, OutputArray u, OutputArray vt, int flags = 0 );
2025
2026 /** wrap SVD::backSubst */
2027 CV_EXPORTS_W void SVBackSubst( InputArray w, InputArray u, InputArray vt,
2028 InputArray rhs, OutputArray dst );
2029
2030 /** @brief Calculates the Mahalanobis distance between two vectors.
2031
2032 The function cv::Mahalanobis calculates and returns the weighted distance between two vectors:
2033 \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]
2034 The covariance matrix may be calculated using the #calcCovarMatrix function and then inverted using
2035 the invert function (preferably using the #DECOMP_SVD method, as the most accurate).
2036 @param v1 first 1D input vector.
2037 @param v2 second 1D input vector.
2038 @param icovar inverse covariance matrix.
2039 */
2040 CV_EXPORTS_W double Mahalanobis(InputArray v1, InputArray v2, InputArray icovar);
2041
2042 /** @brief Performs a forward or inverse Discrete Fourier transform of a 1D or 2D floating-point array.
2043
2044 The function cv::dft performs one of the following:
2045 - Forward the Fourier transform of a 1D vector of N elements:
2046 \f[Y = F^{(N)} \cdot X,\f]
2047 where \f$F^{(N)}_{jk}=\exp(-2\pi i j k/N)\f$ and \f$i=\sqrt{-1}\f$
2048 - Inverse the Fourier transform of a 1D vector of N elements:
2049 \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]
2050 where \f$F^*=\left(\textrm{Re}(F^{(N)})-\textrm{Im}(F^{(N)})\right)^T\f$
2051 - Forward the 2D Fourier transform of a M x N matrix:
2052 \f[Y = F^{(M)} \cdot X \cdot F^{(N)}\f]
2053 - Inverse the 2D Fourier transform of a M x N matrix:
2054 \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]
2055
2056 In case of real (single-channel) data, the output spectrum of the forward Fourier transform or input
2057 spectrum of the inverse Fourier transform can be represented in a packed format called *CCS*
2058 (complex-conjugate-symmetrical). It was borrowed from IPL (Intel\* Image Processing Library). Here
2059 is how 2D *CCS* spectrum looks:
2060 \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]
2061
2062 In case of 1D transform of a real vector, the output looks like the first row of the matrix above.
2063
2064 So, the function chooses an operation mode depending on the flags and size of the input array:
2065 - If #DFT_ROWS is set or the input array has a single row or single column, the function
2066 performs a 1D forward or inverse transform of each row of a matrix when #DFT_ROWS is set.
2067 Otherwise, it performs a 2D transform.
2068 - If the input array is real and #DFT_INVERSE is not set, the function performs a forward 1D or
2069 2D transform:
2070 - When #DFT_COMPLEX_OUTPUT is set, the output is a complex matrix of the same size as
2071 input.
2072 - When #DFT_COMPLEX_OUTPUT is not set, the output is a real matrix of the same size as
2073 input. In case of 2D transform, it uses the packed format as shown above. In case of a
2074 single 1D transform, it looks like the first row of the matrix above. In case of
2075 multiple 1D transforms (when using the #DFT_ROWS flag), each row of the output matrix
2076 looks like the first row of the matrix above.
2077 - If the input array is complex and either #DFT_INVERSE or #DFT_REAL_OUTPUT are not set, the
2078 output is a complex array of the same size as input. The function performs a forward or
2079 inverse 1D or 2D transform of the whole input array or each row of the input array
2080 independently, depending on the flags DFT_INVERSE and DFT_ROWS.
2081 - When #DFT_INVERSE is set and the input array is real, or it is complex but #DFT_REAL_OUTPUT
2082 is set, the output is a real array of the same size as input. The function performs a 1D or 2D
2083 inverse transformation of the whole input array or each individual row, depending on the flags
2084 #DFT_INVERSE and #DFT_ROWS.
2085
2086 If #DFT_SCALE is set, the scaling is done after the transformation.
2087
2088 Unlike dct , the function supports arrays of arbitrary size. But only those arrays are processed
2089 efficiently, whose sizes can be factorized in a product of small prime numbers (2, 3, and 5 in the
2090 current implementation). Such an efficient DFT size can be calculated using the getOptimalDFTSize
2091 method.
2092
2093 The sample below illustrates how to calculate a DFT-based convolution of two 2D real arrays:
2094 @code
2095 void convolveDFT(InputArray A, InputArray B, OutputArray C)
2096 {
2097 // reallocate the output array if needed
2098 C.create(abs(A.rows - B.rows)+1, abs(A.cols - B.cols)+1, A.type());
2099 Size dftSize;
2100 // calculate the size of DFT transform
2101 dftSize.width = getOptimalDFTSize(A.cols + B.cols - 1);
2102 dftSize.height = getOptimalDFTSize(A.rows + B.rows - 1);
2103
2104 // allocate temporary buffers and initialize them with 0's
2105 Mat tempA(dftSize, A.type(), Scalar::all(0));
2106 Mat tempB(dftSize, B.type(), Scalar::all(0));
2107
2108 // copy A and B to the top-left corners of tempA and tempB, respectively
2109 Mat roiA(tempA, Rect(0,0,A.cols,A.rows));
2110 A.copyTo(roiA);
2111 Mat roiB(tempB, Rect(0,0,B.cols,B.rows));
2112 B.copyTo(roiB);
2113
2114 // now transform the padded A & B in-place;
2115 // use "nonzeroRows" hint for faster processing
2116 dft(tempA, tempA, 0, A.rows);
2117 dft(tempB, tempB, 0, B.rows);
2118
2119 // multiply the spectrums;
2120 // the function handles packed spectrum representations well
2121 mulSpectrums(tempA, tempB, tempA);
2122
2123 // transform the product back from the frequency domain.
2124 // Even though all the result rows will be non-zero,
2125 // you need only the first C.rows of them, and thus you
2126 // pass nonzeroRows == C.rows
2127 dft(tempA, tempA, DFT_INVERSE + DFT_SCALE, C.rows);
2128
2129 // now copy the result back to C.
2130 tempA(Rect(0, 0, C.cols, C.rows)).copyTo(C);
2131
2132 // all the temporary buffers will be deallocated automatically
2133 }
2134 @endcode
2135 To optimize this sample, consider the following approaches:
2136 - Since nonzeroRows != 0 is passed to the forward transform calls and since A and B are copied to
2137 the top-left corners of tempA and tempB, respectively, it is not necessary to clear the whole
2138 tempA and tempB. It is only necessary to clear the tempA.cols - A.cols ( tempB.cols - B.cols)
2139 rightmost columns of the matrices.
2140 - This DFT-based convolution does not have to be applied to the whole big arrays, especially if B
2141 is significantly smaller than A or vice versa. Instead, you can calculate convolution by parts.
2142 To do this, you need to split the output array C into multiple tiles. For each tile, estimate
2143 which parts of A and B are required to calculate convolution in this tile. If the tiles in C are
2144 too small, the speed will decrease a lot because of repeated work. In the ultimate case, when
2145 each tile in C is a single pixel, the algorithm becomes equivalent to the naive convolution
2146 algorithm. If the tiles are too big, the temporary arrays tempA and tempB become too big and
2147 there is also a slowdown because of bad cache locality. So, there is an optimal tile size
2148 somewhere in the middle.
2149 - If different tiles in C can be calculated in parallel and, thus, the convolution is done by
2150 parts, the loop can be threaded.
2151
2152 All of the above improvements have been implemented in #matchTemplate and #filter2D . Therefore, by
2153 using them, you can get the performance even better than with the above theoretically optimal
2154 implementation. Though, those two functions actually calculate cross-correlation, not convolution,
2155 so you need to "flip" the second convolution operand B vertically and horizontally using flip .
2156 @note
2157 - An example using the discrete fourier transform can be found at
2158 opencv_source_code/samples/cpp/dft.cpp
2159 - (Python) An example using the dft functionality to perform Wiener deconvolution can be found
2160 at opencv_source/samples/python/deconvolution.py
2161 - (Python) An example rearranging the quadrants of a Fourier image can be found at
2162 opencv_source/samples/python/dft.py
2163 @param src input array that could be real or complex.
2164 @param dst output array whose size and type depends on the flags .
2165 @param flags transformation flags, representing a combination of the #DftFlags
2166 @param nonzeroRows when the parameter is not zero, the function assumes that only the first
2167 nonzeroRows rows of the input array (#DFT_INVERSE is not set) or only the first nonzeroRows of the
2168 output array (#DFT_INVERSE is set) contain non-zeros, thus, the function can handle the rest of the
2169 rows more efficiently and save some time; this technique is very useful for calculating array
2170 cross-correlation or convolution using DFT.
2171 @sa dct , getOptimalDFTSize , mulSpectrums, filter2D , matchTemplate , flip , cartToPolar ,
2172 magnitude , phase
2173 */
2174 CV_EXPORTS_W void dft(InputArray src, OutputArray dst, int flags = 0, int nonzeroRows = 0);
2175
2176 /** @brief Calculates the inverse Discrete Fourier Transform of a 1D or 2D array.
2177
2178 idft(src, dst, flags) is equivalent to dft(src, dst, flags | #DFT_INVERSE) .
2179 @note None of dft and idft scales the result by default. So, you should pass #DFT_SCALE to one of
2180 dft or idft explicitly to make these transforms mutually inverse.
2181 @sa dft, dct, idct, mulSpectrums, getOptimalDFTSize
2182 @param src input floating-point real or complex array.
2183 @param dst output array whose size and type depend on the flags.
2184 @param flags operation flags (see dft and #DftFlags).
2185 @param nonzeroRows number of dst rows to process; the rest of the rows have undefined content (see
2186 the convolution sample in dft description.
2187 */
2188 CV_EXPORTS_W void idft(InputArray src, OutputArray dst, int flags = 0, int nonzeroRows = 0);
2189
2190 /** @brief Performs a forward or inverse discrete Cosine transform of 1D or 2D array.
2191
2192 The function cv::dct performs a forward or inverse discrete Cosine transform (DCT) of a 1D or 2D
2193 floating-point array:
2194 - Forward Cosine transform of a 1D vector of N elements:
2195 \f[Y = C^{(N)} \cdot X\f]
2196 where
2197 \f[C^{(N)}_{jk}= \sqrt{\alpha_j/N} \cos \left ( \frac{\pi(2k+1)j}{2N} \right )\f]
2198 and
2199 \f$\alpha_0=1\f$, \f$\alpha_j=2\f$ for *j \> 0*.
2200 - Inverse Cosine transform of a 1D vector of N elements:
2201 \f[X = \left (C^{(N)} \right )^{-1} \cdot Y = \left (C^{(N)} \right )^T \cdot Y\f]
2202 (since \f$C^{(N)}\f$ is an orthogonal matrix, \f$C^{(N)} \cdot \left(C^{(N)}\right)^T = I\f$ )
2203 - Forward 2D Cosine transform of M x N matrix:
2204 \f[Y = C^{(N)} \cdot X \cdot \left (C^{(N)} \right )^T\f]
2205 - Inverse 2D Cosine transform of M x N matrix:
2206 \f[X = \left (C^{(N)} \right )^T \cdot X \cdot C^{(N)}\f]
2207
2208 The function chooses the mode of operation by looking at the flags and size of the input array:
2209 - If (flags & #DCT_INVERSE) == 0 , the function does a forward 1D or 2D transform. Otherwise, it
2210 is an inverse 1D or 2D transform.
2211 - If (flags & #DCT_ROWS) != 0 , the function performs a 1D transform of each row.
2212 - If the array is a single column or a single row, the function performs a 1D transform.
2213 - If none of the above is true, the function performs a 2D transform.
2214
2215 @note Currently dct supports even-size arrays (2, 4, 6 ...). For data analysis and approximation, you
2216 can pad the array when necessary.
2217 Also, the function performance depends very much, and not monotonically, on the array size (see
2218 getOptimalDFTSize ). In the current implementation DCT of a vector of size N is calculated via DFT
2219 of a vector of size N/2 . Thus, the optimal DCT size N1 \>= N can be calculated as:
2220 @code
2221 size_t getOptimalDCTSize(size_t N) { return 2*getOptimalDFTSize((N+1)/2); }
2222 N1 = getOptimalDCTSize(N);
2223 @endcode
2224 @param src input floating-point array.
2225 @param dst output array of the same size and type as src .
2226 @param flags transformation flags as a combination of cv::DftFlags (DCT_*)
2227 @sa dft , getOptimalDFTSize , idct
2228 */
2229 CV_EXPORTS_W void dct(InputArray src, OutputArray dst, int flags = 0);
2230
2231 /** @brief Calculates the inverse Discrete Cosine Transform of a 1D or 2D array.
2232
2233 idct(src, dst, flags) is equivalent to dct(src, dst, flags | DCT_INVERSE).
2234 @param src input floating-point single-channel array.
2235 @param dst output array of the same size and type as src.
2236 @param flags operation flags.
2237 @sa dct, dft, idft, getOptimalDFTSize
2238 */
2239 CV_EXPORTS_W void idct(InputArray src, OutputArray dst, int flags = 0);
2240
2241 /** @brief Performs the per-element multiplication of two Fourier spectrums.
2242
2243 The function cv::mulSpectrums performs the per-element multiplication of the two CCS-packed or complex
2244 matrices that are results of a real or complex Fourier transform.
2245
2246 The function, together with dft and idft , may be used to calculate convolution (pass conjB=false )
2247 or correlation (pass conjB=true ) of two arrays rapidly. When the arrays are complex, they are
2248 simply multiplied (per element) with an optional conjugation of the second-array elements. When the
2249 arrays are real, they are assumed to be CCS-packed (see dft for details).
2250 @param a first input array.
2251 @param b second input array of the same size and type as src1 .
2252 @param c output array of the same size and type as src1 .
2253 @param flags operation flags; currently, the only supported flag is cv::DFT_ROWS, which indicates that
2254 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.
2255 @param conjB optional flag that conjugates the second input array before the multiplication (true)
2256 or not (false).
2257 */
2258 CV_EXPORTS_W void mulSpectrums(InputArray a, InputArray b, OutputArray c,
2259 int flags, bool conjB = false);
2260
2261 /** @brief Returns the optimal DFT size for a given vector size.
2262
2263 DFT performance is not a monotonic function of a vector size. Therefore, when you calculate
2264 convolution of two arrays or perform the spectral analysis of an array, it usually makes sense to
2265 pad the input data with zeros to get a bit larger array that can be transformed much faster than the
2266 original one. Arrays whose size is a power-of-two (2, 4, 8, 16, 32, ...) are the fastest to process.
2267 Though, the arrays whose size is a product of 2's, 3's, and 5's (for example, 300 = 5\*5\*3\*2\*2)
2268 are also processed quite efficiently.
2269
2270 The function cv::getOptimalDFTSize returns the minimum number N that is greater than or equal to vecsize
2271 so that the DFT of a vector of size N can be processed efficiently. In the current implementation N
2272 = 2 ^p^ \* 3 ^q^ \* 5 ^r^ for some integer p, q, r.
2273
2274 The function returns a negative number if vecsize is too large (very close to INT_MAX ).
2275
2276 While the function cannot be used directly to estimate the optimal vector size for DCT transform
2277 (since the current DCT implementation supports only even-size vectors), it can be easily processed
2278 as getOptimalDFTSize((vecsize+1)/2)\*2.
2279 @param vecsize vector size.
2280 @sa dft , dct , idft , idct , mulSpectrums
2281 */
2282 CV_EXPORTS_W int getOptimalDFTSize(int vecsize);
2283
2284 /** @brief Returns the default random number generator.
2285
2286 The function cv::theRNG returns the default random number generator. For each thread, there is a
2287 separate random number generator, so you can use the function safely in multi-thread environments.
2288 If you just need to get a single random number using this generator or initialize an array, you can
2289 use randu or randn instead. But if you are going to generate many random numbers inside a loop, it
2290 is much faster to use this function to retrieve the generator and then use RNG::operator _Tp() .
2291 @sa RNG, randu, randn
2292 */
2293 CV_EXPORTS RNG& theRNG();
2294
2295 /** @brief Sets state of default random number generator.
2296
2297 The function cv::setRNGSeed sets state of default random number generator to custom value.
2298 @param seed new state for default random number generator
2299 @sa RNG, randu, randn
2300 */
2301 CV_EXPORTS_W void setRNGSeed(int seed);
2302
2303 /** @brief Generates a single uniformly-distributed random number or an array of random numbers.
2304
2305 Non-template variant of the function fills the matrix dst with uniformly-distributed
2306 random numbers from the specified range:
2307 \f[\texttt{low} _c \leq \texttt{dst} (I)_c < \texttt{high} _c\f]
2308 @param dst output array of random numbers; the array must be pre-allocated.
2309 @param low inclusive lower boundary of the generated random numbers.
2310 @param high exclusive upper boundary of the generated random numbers.
2311 @sa RNG, randn, theRNG
2312 */
2313 CV_EXPORTS_W void randu(InputOutputArray dst, InputArray low, InputArray high);
2314
2315 /** @brief Fills the array with normally distributed random numbers.
2316
2317 The function cv::randn fills the matrix dst with normally distributed random numbers with the specified
2318 mean vector and the standard deviation matrix. The generated random numbers are clipped to fit the
2319 value range of the output array data type.
2320 @param dst output array of random numbers; the array must be pre-allocated and have 1 to 4 channels.
2321 @param mean mean value (expectation) of the generated random numbers.
2322 @param stddev standard deviation of the generated random numbers; it can be either a vector (in
2323 which case a diagonal standard deviation matrix is assumed) or a square matrix.
2324 @sa RNG, randu
2325 */
2326 CV_EXPORTS_W void randn(InputOutputArray dst, InputArray mean, InputArray stddev);
2327
2328 /** @brief Shuffles the array elements randomly.
2329
2330 The function cv::randShuffle shuffles the specified 1D array by randomly choosing pairs of elements and
2331 swapping them. The number of such swap operations will be dst.rows\*dst.cols\*iterFactor .
2332 @param dst input/output numerical 1D array.
2333 @param iterFactor scale factor that determines the number of random swap operations (see the details
2334 below).
2335 @param rng optional random number generator used for shuffling; if it is zero, theRNG () is used
2336 instead.
2337 @sa RNG, sort
2338 */
2339 CV_EXPORTS_W void randShuffle(InputOutputArray dst, double iterFactor = 1., RNG* rng = 0);
2340
2341 /** @brief Principal Component Analysis
2342
2343 The class is used to calculate a special basis for a set of vectors. The
2344 basis will consist of eigenvectors of the covariance matrix calculated
2345 from the input set of vectors. The class %PCA can also transform
2346 vectors to/from the new coordinate space defined by the basis. Usually,
2347 in this new coordinate system, each vector from the original set (and
2348 any linear combination of such vectors) can be quite accurately
2349 approximated by taking its first few components, corresponding to the
2350 eigenvectors of the largest eigenvalues of the covariance matrix.
2351 Geometrically it means that you calculate a projection of the vector to
2352 a subspace formed by a few eigenvectors corresponding to the dominant
2353 eigenvalues of the covariance matrix. And usually such a projection is
2354 very close to the original vector. So, you can represent the original
2355 vector from a high-dimensional space with a much shorter vector
2356 consisting of the projected vector's coordinates in the subspace. Such a
2357 transformation is also known as Karhunen-Loeve Transform, or KLT.
2358 See http://en.wikipedia.org/wiki/Principal_component_analysis
2359
2360 The sample below is the function that takes two matrices. The first
2361 function stores a set of vectors (a row per vector) that is used to
2362 calculate PCA. The second function stores another "test" set of vectors
2363 (a row per vector). First, these vectors are compressed with PCA, then
2364 reconstructed back, and then the reconstruction error norm is computed
2365 and printed for each vector. :
2366
2367 @code{.cpp}
2368 using namespace cv;
2369
2370 PCA compressPCA(const Mat& pcaset, int maxComponents,
2371 const Mat& testset, Mat& compressed)
2372 {
2373 PCA pca(pcaset, // pass the data
2374 Mat(), // we do not have a pre-computed mean vector,
2375 // so let the PCA engine to compute it
2376 PCA::DATA_AS_ROW, // indicate that the vectors
2377 // are stored as matrix rows
2378 // (use PCA::DATA_AS_COL if the vectors are
2379 // the matrix columns)
2380 maxComponents // specify, how many principal components to retain
2381 );
2382 // if there is no test data, just return the computed basis, ready-to-use
2383 if( !testset.data )
2384 return pca;
2385 CV_Assert( testset.cols == pcaset.cols );
2386
2387 compressed.create(testset.rows, maxComponents, testset.type());
2388
2389 Mat reconstructed;
2390 for( int i = 0; i < testset.rows; i++ )
2391 {
2392 Mat vec = testset.row(i), coeffs = compressed.row(i), reconstructed;
2393 // compress the vector, the result will be stored
2394 // in the i-th row of the output matrix
2395 pca.project(vec, coeffs);
2396 // and then reconstruct it
2397 pca.backProject(coeffs, reconstructed);
2398 // and measure the error
2399 printf("%d. diff = %g\n", i, norm(vec, reconstructed, NORM_L2));
2400 }
2401 return pca;
2402 }
2403 @endcode
2404 @sa calcCovarMatrix, mulTransposed, SVD, dft, dct
2405 */
2406 class CV_EXPORTS PCA
2407 {
2408 public:
2409 enum Flags { DATA_AS_ROW = 0, //!< indicates that the input samples are stored as matrix rows
2410 DATA_AS_COL = 1, //!< indicates that the input samples are stored as matrix columns
2411 USE_AVG = 2 //!
2412 };
2413
2414 /** @brief default constructor
2415
2416 The default constructor initializes an empty %PCA structure. The other
2417 constructors initialize the structure and call PCA::operator()().
2418 */
2419 PCA();
2420
2421 /** @overload
2422 @param data input samples stored as matrix rows or matrix columns.
2423 @param mean optional mean value; if the matrix is empty (@c noArray()),
2424 the mean is computed from the data.
2425 @param flags operation flags; currently the parameter is only used to
2426 specify the data layout (PCA::Flags)
2427 @param maxComponents maximum number of components that %PCA should
2428 retain; by default, all the components are retained.
2429 */
2430 PCA(InputArray data, InputArray mean, int flags, int maxComponents = 0);
2431
2432 /** @overload
2433 @param data input samples stored as matrix rows or matrix columns.
2434 @param mean optional mean value; if the matrix is empty (noArray()),
2435 the mean is computed from the data.
2436 @param flags operation flags; currently the parameter is only used to
2437 specify the data layout (PCA::Flags)
2438 @param retainedVariance Percentage of variance that PCA should retain.
2439 Using this parameter will let the PCA decided how many components to
2440 retain but it will always keep at least 2.
2441 */
2442 PCA(InputArray data, InputArray mean, int flags, double retainedVariance);
2443
2444 /** @brief performs %PCA
2445
2446 The operator performs %PCA of the supplied dataset. It is safe to reuse
2447 the same PCA structure for multiple datasets. That is, if the structure
2448 has been previously used with another dataset, the existing internal
2449 data is reclaimed and the new @ref eigenvalues, @ref eigenvectors and @ref
2450 mean are allocated and computed.
2451
2452 The computed @ref eigenvalues are sorted from the largest to the smallest and
2453 the corresponding @ref eigenvectors are stored as eigenvectors rows.
2454
2455 @param data input samples stored as the matrix rows or as the matrix
2456 columns.
2457 @param mean optional mean value; if the matrix is empty (noArray()),
2458 the mean is computed from the data.
2459 @param flags operation flags; currently the parameter is only used to
2460 specify the data layout. (Flags)
2461 @param maxComponents maximum number of components that PCA should
2462 retain; by default, all the components are retained.
2463 */
2464 PCA& operator()(InputArray data, InputArray mean, int flags, int maxComponents = 0);
2465
2466 /** @overload
2467 @param data input samples stored as the matrix rows or as the matrix
2468 columns.
2469 @param mean optional mean value; if the matrix is empty (noArray()),
2470 the mean is computed from the data.
2471 @param flags operation flags; currently the parameter is only used to
2472 specify the data layout. (PCA::Flags)
2473 @param retainedVariance Percentage of variance that %PCA should retain.
2474 Using this parameter will let the %PCA decided how many components to
2475 retain but it will always keep at least 2.
2476 */
2477 PCA& operator()(InputArray data, InputArray mean, int flags, double retainedVariance);
2478
2479 /** @brief Projects vector(s) to the principal component subspace.
2480
2481 The methods project one or more vectors to the principal component
2482 subspace, where each vector projection is represented by coefficients in
2483 the principal component basis. The first form of the method returns the
2484 matrix that the second form writes to the result. So the first form can
2485 be used as a part of expression while the second form can be more
2486 efficient in a processing loop.
2487 @param vec input vector(s); must have the same dimensionality and the
2488 same layout as the input data used at %PCA phase, that is, if
2489 DATA_AS_ROW are specified, then `vec.cols==data.cols`
2490 (vector dimensionality) and `vec.rows` is the number of vectors to
2491 project, and the same is true for the PCA::DATA_AS_COL case.
2492 */
2493 Mat project(InputArray vec) const;
2494
2495 /** @overload
2496 @param vec input vector(s); must have the same dimensionality and the
2497 same layout as the input data used at PCA phase, that is, if
2498 DATA_AS_ROW are specified, then `vec.cols==data.cols`
2499 (vector dimensionality) and `vec.rows` is the number of vectors to
2500 project, and the same is true for the PCA::DATA_AS_COL case.
2501 @param result output vectors; in case of PCA::DATA_AS_COL, the
2502 output matrix has as many columns as the number of input vectors, this
2503 means that `result.cols==vec.cols` and the number of rows match the
2504 number of principal components (for example, `maxComponents` parameter
2505 passed to the constructor).
2506 */
2507 void project(InputArray vec, OutputArray result) const;
2508
2509 /** @brief Reconstructs vectors from their PC projections.
2510
2511 The methods are inverse operations to PCA::project. They take PC
2512 coordinates of projected vectors and reconstruct the original vectors.
2513 Unless all the principal components have been retained, the
2514 reconstructed vectors are different from the originals. But typically,
2515 the difference is small if the number of components is large enough (but
2516 still much smaller than the original vector dimensionality). As a
2517 result, PCA is used.
2518 @param vec coordinates of the vectors in the principal component
2519 subspace, the layout and size are the same as of PCA::project output
2520 vectors.
2521 */
2522 Mat backProject(InputArray vec) const;
2523
2524 /** @overload
2525 @param vec coordinates of the vectors in the principal component
2526 subspace, the layout and size are the same as of PCA::project output
2527 vectors.
2528 @param result reconstructed vectors; the layout and size are the same as
2529 of PCA::project input vectors.
2530 */
2531 void backProject(InputArray vec, OutputArray result) const;
2532
2533 /** @brief write PCA objects
2534
2535 Writes @ref eigenvalues @ref eigenvectors and @ref mean to specified FileStorage
2536 */
2537 void write(FileStorage& fs) const;
2538
2539 /** @brief load PCA objects
2540
2541 Loads @ref eigenvalues @ref eigenvectors and @ref mean from specified FileNode
2542 */
2543 void read(const FileNode& fn);
2544
2545 Mat eigenvectors; //!< eigenvectors of the covariation matrix
2546 Mat eigenvalues; //!< eigenvalues of the covariation matrix
2547 Mat mean; //!< mean value subtracted before the projection and added after the back projection
2548 };
2549
2550 /** @example samples/cpp/pca.cpp
2551 An example using %PCA for dimensionality reduction while maintaining an amount of variance
2552 */
2553
2554 /** @example samples/cpp/tutorial_code/ml/introduction_to_pca/introduction_to_pca.cpp
2555 Check @ref tutorial_introduction_to_pca "the corresponding tutorial" for more details
2556 */
2557
2558 /**
2559 @brief Linear Discriminant Analysis
2560 @todo document this class
2561 */
2562 class CV_EXPORTS LDA
2563 {
2564 public:
2565 /** @brief constructor
2566 Initializes a LDA with num_components (default 0).
2567 */
2568 explicit LDA(int num_components = 0);
2569
2570 /** Initializes and performs a Discriminant Analysis with Fisher's
2571 Optimization Criterion on given data in src and corresponding labels
2572 in labels. If 0 (or less) number of components are given, they are
2573 automatically determined for given data in computation.
2574 */
2575 LDA(InputArrayOfArrays src, InputArray labels, int num_components = 0);
2576
2577 /** Serializes this object to a given filename.
2578 */
2579 void save(const String& filename) const;
2580
2581 /** Deserializes this object from a given filename.
2582 */
2583 void load(const String& filename);
2584
2585 /** Serializes this object to a given cv::FileStorage.
2586 */
2587 void save(FileStorage& fs) const;
2588
2589 /** Deserializes this object from a given cv::FileStorage.
2590 */
2591 void load(const FileStorage& node);
2592
2593 /** destructor
2594 */
2595 ~LDA();
2596
2597 /** Compute the discriminants for data in src (row aligned) and labels.
2598 */
2599 void compute(InputArrayOfArrays src, InputArray labels);
2600
2601 /** Projects samples into the LDA subspace.
2602 src may be one or more row aligned samples.
2603 */
2604 Mat project(InputArray src);
2605
2606 /** Reconstructs projections from the LDA subspace.
2607 src may be one or more row aligned projections.
2608 */
2609 Mat reconstruct(InputArray src);
2610
2611 /** Returns the eigenvectors of this LDA.
2612 */
eigenvectors() const2613 Mat eigenvectors() const { return _eigenvectors; }
2614
2615 /** Returns the eigenvalues of this LDA.
2616 */
eigenvalues() const2617 Mat eigenvalues() const { return _eigenvalues; }
2618
2619 static Mat subspaceProject(InputArray W, InputArray mean, InputArray src);
2620 static Mat subspaceReconstruct(InputArray W, InputArray mean, InputArray src);
2621
2622 protected:
2623 int _num_components;
2624 Mat _eigenvectors;
2625 Mat _eigenvalues;
2626 void lda(InputArrayOfArrays src, InputArray labels);
2627 };
2628
2629 /** @brief Singular Value Decomposition
2630
2631 Class for computing Singular Value Decomposition of a floating-point
2632 matrix. The Singular Value Decomposition is used to solve least-square
2633 problems, under-determined linear systems, invert matrices, compute
2634 condition numbers, and so on.
2635
2636 If you want to compute a condition number of a matrix or an absolute value of
2637 its determinant, you do not need `u` and `vt`. You can pass
2638 flags=SVD::NO_UV|... . Another flag SVD::FULL_UV indicates that full-size u
2639 and vt must be computed, which is not necessary most of the time.
2640
2641 @sa invert, solve, eigen, determinant
2642 */
2643 class CV_EXPORTS SVD
2644 {
2645 public:
2646 enum Flags {
2647 /** allow the algorithm to modify the decomposed matrix; it can save space and speed up
2648 processing. currently ignored. */
2649 MODIFY_A = 1,
2650 /** indicates that only a vector of singular values `w` is to be processed, while u and vt
2651 will be set to empty matrices */
2652 NO_UV = 2,
2653 /** when the matrix is not square, by default the algorithm produces u and vt matrices of
2654 sufficiently large size for the further A reconstruction; if, however, FULL_UV flag is
2655 specified, u and vt will be full-size square orthogonal matrices.*/
2656 FULL_UV = 4
2657 };
2658
2659 /** @brief the default constructor
2660
2661 initializes an empty SVD structure
2662 */
2663 SVD();
2664
2665 /** @overload
2666 initializes an empty SVD structure and then calls SVD::operator()
2667 @param src decomposed matrix. The depth has to be CV_32F or CV_64F.
2668 @param flags operation flags (SVD::Flags)
2669 */
2670 SVD( InputArray src, int flags = 0 );
2671
2672 /** @brief the operator that performs SVD. The previously allocated u, w and vt are released.
2673
2674 The operator performs the singular value decomposition of the supplied
2675 matrix. The u,`vt` , and the vector of singular values w are stored in
2676 the structure. The same SVD structure can be reused many times with
2677 different matrices. Each time, if needed, the previous u,`vt` , and w
2678 are reclaimed and the new matrices are created, which is all handled by
2679 Mat::create.
2680 @param src decomposed matrix. The depth has to be CV_32F or CV_64F.
2681 @param flags operation flags (SVD::Flags)
2682 */
2683 SVD& operator ()( InputArray src, int flags = 0 );
2684
2685 /** @brief decomposes matrix and stores the results to user-provided matrices
2686
2687 The methods/functions perform SVD of matrix. Unlike SVD::SVD constructor
2688 and SVD::operator(), they store the results to the user-provided
2689 matrices:
2690
2691 @code{.cpp}
2692 Mat A, w, u, vt;
2693 SVD::compute(A, w, u, vt);
2694 @endcode
2695
2696 @param src decomposed matrix. The depth has to be CV_32F or CV_64F.
2697 @param w calculated singular values
2698 @param u calculated left singular vectors
2699 @param vt transposed matrix of right singular vectors
2700 @param flags operation flags - see SVD::Flags.
2701 */
2702 static void compute( InputArray src, OutputArray w,
2703 OutputArray u, OutputArray vt, int flags = 0 );
2704
2705 /** @overload
2706 computes singular values of a matrix
2707 @param src decomposed matrix. The depth has to be CV_32F or CV_64F.
2708 @param w calculated singular values
2709 @param flags operation flags - see SVD::Flags.
2710 */
2711 static void compute( InputArray src, OutputArray w, int flags = 0 );
2712
2713 /** @brief performs back substitution
2714 */
2715 static void backSubst( InputArray w, InputArray u,
2716 InputArray vt, InputArray rhs,
2717 OutputArray dst );
2718
2719 /** @brief solves an under-determined singular linear system
2720
2721 The method finds a unit-length solution x of a singular linear system
2722 A\*x = 0. Depending on the rank of A, there can be no solutions, a
2723 single solution or an infinite number of solutions. In general, the
2724 algorithm solves the following problem:
2725 \f[dst = \arg \min _{x: \| x \| =1} \| src \cdot x \|\f]
2726 @param src left-hand-side matrix.
2727 @param dst found solution.
2728 */
2729 static void solveZ( InputArray src, OutputArray dst );
2730
2731 /** @brief performs a singular value back substitution.
2732
2733 The method calculates a back substitution for the specified right-hand
2734 side:
2735
2736 \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]
2737
2738 Using this technique you can either get a very accurate solution of the
2739 convenient linear system, or the best (in the least-squares terms)
2740 pseudo-solution of an overdetermined linear system.
2741
2742 @param rhs right-hand side of a linear system (u\*w\*v')\*dst = rhs to
2743 be solved, where A has been previously decomposed.
2744
2745 @param dst found solution of the system.
2746
2747 @note Explicit SVD with the further back substitution only makes sense
2748 if you need to solve many linear systems with the same left-hand side
2749 (for example, src ). If all you need is to solve a single system
2750 (possibly with multiple rhs immediately available), simply call solve
2751 add pass #DECOMP_SVD there. It does absolutely the same thing.
2752 */
2753 void backSubst( InputArray rhs, OutputArray dst ) const;
2754
2755 /** @todo document */
2756 template<typename _Tp, int m, int n, int nm> static
2757 void compute( const Matx<_Tp, m, n>& a, Matx<_Tp, nm, 1>& w, Matx<_Tp, m, nm>& u, Matx<_Tp, n, nm>& vt );
2758
2759 /** @todo document */
2760 template<typename _Tp, int m, int n, int nm> static
2761 void compute( const Matx<_Tp, m, n>& a, Matx<_Tp, nm, 1>& w );
2762
2763 /** @todo document */
2764 template<typename _Tp, int m, int n, int nm, int nb> static
2765 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 );
2766
2767 Mat u, w, vt;
2768 };
2769
2770 /** @brief Random Number Generator
2771
2772 Random number generator. It encapsulates the state (currently, a 64-bit
2773 integer) and has methods to return scalar random values and to fill
2774 arrays with random values. Currently it supports uniform and Gaussian
2775 (normal) distributions. The generator uses Multiply-With-Carry
2776 algorithm, introduced by G. Marsaglia (
2777 <http://en.wikipedia.org/wiki/Multiply-with-carry> ).
2778 Gaussian-distribution random numbers are generated using the Ziggurat
2779 algorithm ( <http://en.wikipedia.org/wiki/Ziggurat_algorithm> ),
2780 introduced by G. Marsaglia and W. W. Tsang.
2781 */
2782 class CV_EXPORTS RNG
2783 {
2784 public:
2785 enum { UNIFORM = 0,
2786 NORMAL = 1
2787 };
2788
2789 /** @brief constructor
2790
2791 These are the RNG constructors. The first form sets the state to some
2792 pre-defined value, equal to 2\*\*32-1 in the current implementation. The
2793 second form sets the state to the specified value. If you passed state=0
2794 , the constructor uses the above default value instead to avoid the
2795 singular random number sequence, consisting of all zeros.
2796 */
2797 RNG();
2798 /** @overload
2799 @param state 64-bit value used to initialize the RNG.
2800 */
2801 RNG(uint64 state);
2802 /**The method updates the state using the MWC algorithm and returns the
2803 next 32-bit random number.*/
2804 unsigned next();
2805
2806 /**Each of the methods updates the state using the MWC algorithm and
2807 returns the next random number of the specified type. In case of integer
2808 types, the returned number is from the available value range for the
2809 specified type. In case of floating-point types, the returned value is
2810 from [0,1) range.
2811 */
2812 operator uchar();
2813 /** @overload */
2814 operator schar();
2815 /** @overload */
2816 operator ushort();
2817 /** @overload */
2818 operator short();
2819 /** @overload */
2820 operator unsigned();
2821 /** @overload */
2822 operator int();
2823 /** @overload */
2824 operator float();
2825 /** @overload */
2826 operator double();
2827
2828 /** @brief returns a random integer sampled uniformly from [0, N).
2829
2830 The methods transform the state using the MWC algorithm and return the
2831 next random number. The first form is equivalent to RNG::next . The
2832 second form returns the random number modulo N , which means that the
2833 result is in the range [0, N) .
2834 */
2835 unsigned operator ()();
2836 /** @overload
2837 @param N upper non-inclusive boundary of the returned random number.
2838 */
2839 unsigned operator ()(unsigned N);
2840
2841 /** @brief returns uniformly distributed integer random number from [a,b) range
2842
2843 The methods transform the state using the MWC algorithm and return the
2844 next uniformly-distributed random number of the specified type, deduced
2845 from the input parameter type, from the range [a, b) . There is a nuance
2846 illustrated by the following sample:
2847
2848 @code{.cpp}
2849 RNG rng;
2850
2851 // always produces 0
2852 double a = rng.uniform(0, 1);
2853
2854 // produces double from [0, 1)
2855 double a1 = rng.uniform((double)0, (double)1);
2856
2857 // produces float from [0, 1)
2858 float b = rng.uniform(0.f, 1.f);
2859
2860 // produces double from [0, 1)
2861 double c = rng.uniform(0., 1.);
2862
2863 // may cause compiler error because of ambiguity:
2864 // RNG::uniform(0, (int)0.999999)? or RNG::uniform((double)0, 0.99999)?
2865 double d = rng.uniform(0, 0.999999);
2866 @endcode
2867
2868 The compiler does not take into account the type of the variable to
2869 which you assign the result of RNG::uniform . The only thing that
2870 matters to the compiler is the type of a and b parameters. So, if you
2871 want a floating-point random number, but the range boundaries are
2872 integer numbers, either put dots in the end, if they are constants, or
2873 use explicit type cast operators, as in the a1 initialization above.
2874 @param a lower inclusive boundary of the returned random number.
2875 @param b upper non-inclusive boundary of the returned random number.
2876 */
2877 int uniform(int a, int b);
2878 /** @overload */
2879 float uniform(float a, float b);
2880 /** @overload */
2881 double uniform(double a, double b);
2882
2883 /** @brief Fills arrays with random numbers.
2884
2885 @param mat 2D or N-dimensional matrix; currently matrices with more than
2886 4 channels are not supported by the methods, use Mat::reshape as a
2887 possible workaround.
2888 @param distType distribution type, RNG::UNIFORM or RNG::NORMAL.
2889 @param a first distribution parameter; in case of the uniform
2890 distribution, this is an inclusive lower boundary, in case of the normal
2891 distribution, this is a mean value.
2892 @param b second distribution parameter; in case of the uniform
2893 distribution, this is a non-inclusive upper boundary, in case of the
2894 normal distribution, this is a standard deviation (diagonal of the
2895 standard deviation matrix or the full standard deviation matrix).
2896 @param saturateRange pre-saturation flag; for uniform distribution only;
2897 if true, the method will first convert a and b to the acceptable value
2898 range (according to the mat datatype) and then will generate uniformly
2899 distributed random numbers within the range [saturate(a), saturate(b)),
2900 if saturateRange=false, the method will generate uniformly distributed
2901 random numbers in the original range [a, b) and then will saturate them,
2902 it means, for example, that
2903 <tt>theRNG().fill(mat_8u, RNG::UNIFORM, -DBL_MAX, DBL_MAX)</tt> will likely
2904 produce array mostly filled with 0's and 255's, since the range (0, 255)
2905 is significantly smaller than [-DBL_MAX, DBL_MAX).
2906
2907 Each of the methods fills the matrix with the random values from the
2908 specified distribution. As the new numbers are generated, the RNG state
2909 is updated accordingly. In case of multiple-channel images, every
2910 channel is filled independently, which means that RNG cannot generate
2911 samples from the multi-dimensional Gaussian distribution with
2912 non-diagonal covariance matrix directly. To do that, the method
2913 generates samples from multi-dimensional standard Gaussian distribution
2914 with zero mean and identity covariation matrix, and then transforms them
2915 using transform to get samples from the specified Gaussian distribution.
2916 */
2917 void fill( InputOutputArray mat, int distType, InputArray a, InputArray b, bool saturateRange = false );
2918
2919 /** @brief Returns the next random number sampled from the Gaussian distribution
2920 @param sigma standard deviation of the distribution.
2921
2922 The method transforms the state using the MWC algorithm and returns the
2923 next random number from the Gaussian distribution N(0,sigma) . That is,
2924 the mean value of the returned random numbers is zero and the standard
2925 deviation is the specified sigma .
2926 */
2927 double gaussian(double sigma);
2928
2929 uint64 state;
2930
2931 bool operator ==(const RNG& other) const;
2932 };
2933
2934 /** @brief Mersenne Twister random number generator
2935
2936 Inspired by http://www.math.sci.hiroshima-u.ac.jp/~m-mat/MT/MT2002/CODES/mt19937ar.c
2937 @todo document
2938 */
2939 class CV_EXPORTS RNG_MT19937
2940 {
2941 public:
2942 RNG_MT19937();
2943 RNG_MT19937(unsigned s);
2944 void seed(unsigned s);
2945
2946 unsigned next();
2947
2948 operator int();
2949 operator unsigned();
2950 operator float();
2951 operator double();
2952
2953 unsigned operator ()(unsigned N);
2954 unsigned operator ()();
2955
2956 /** @brief returns uniformly distributed integer random number from [a,b) range*/
2957 int uniform(int a, int b);
2958 /** @brief returns uniformly distributed floating-point random number from [a,b) range*/
2959 float uniform(float a, float b);
2960 /** @brief returns uniformly distributed double-precision floating-point random number from [a,b) range*/
2961 double uniform(double a, double b);
2962
2963 private:
2964 enum PeriodParameters {N = 624, M = 397};
2965 unsigned state[N];
2966 int mti;
2967 };
2968
2969 //! @} core_array
2970
2971 //! @addtogroup core_cluster
2972 //! @{
2973
2974 /** @example samples/cpp/kmeans.cpp
2975 An example on K-means clustering
2976 */
2977
2978 /** @brief Finds centers of clusters and groups input samples around the clusters.
2979
2980 The function kmeans implements a k-means algorithm that finds the centers of cluster_count clusters
2981 and groups the input samples around the clusters. As an output, \f$\texttt{bestLabels}_i\f$ contains a
2982 0-based cluster index for the sample stored in the \f$i^{th}\f$ row of the samples matrix.
2983
2984 @note
2985 - (Python) An example on K-means clustering can be found at
2986 opencv_source_code/samples/python/kmeans.py
2987 @param data Data for clustering. An array of N-Dimensional points with float coordinates is needed.
2988 Examples of this array can be:
2989 - Mat points(count, 2, CV_32F);
2990 - Mat points(count, 1, CV_32FC2);
2991 - Mat points(1, count, CV_32FC2);
2992 - std::vector\<cv::Point2f\> points(sampleCount);
2993 @param K Number of clusters to split the set by.
2994 @param bestLabels Input/output integer array that stores the cluster indices for every sample.
2995 @param criteria The algorithm termination criteria, that is, the maximum number of iterations and/or
2996 the desired accuracy. The accuracy is specified as criteria.epsilon. As soon as each of the cluster
2997 centers moves by less than criteria.epsilon on some iteration, the algorithm stops.
2998 @param attempts Flag to specify the number of times the algorithm is executed using different
2999 initial labellings. The algorithm returns the labels that yield the best compactness (see the last
3000 function parameter).
3001 @param flags Flag that can take values of cv::KmeansFlags
3002 @param centers Output matrix of the cluster centers, one row per each cluster center.
3003 @return The function returns the compactness measure that is computed as
3004 \f[\sum _i \| \texttt{samples} _i - \texttt{centers} _{ \texttt{labels} _i} \| ^2\f]
3005 after every attempt. The best (minimum) value is chosen and the corresponding labels and the
3006 compactness value are returned by the function. Basically, you can use only the core of the
3007 function, set the number of attempts to 1, initialize labels each time using a custom algorithm,
3008 pass them with the ( flags = #KMEANS_USE_INITIAL_LABELS ) flag, and then choose the best
3009 (most-compact) clustering.
3010 */
3011 CV_EXPORTS_W double kmeans( InputArray data, int K, InputOutputArray bestLabels,
3012 TermCriteria criteria, int attempts,
3013 int flags, OutputArray centers = noArray() );
3014
3015 //! @} core_cluster
3016
3017 //! @addtogroup core_basic
3018 //! @{
3019
3020 /////////////////////////////// Formatted output of cv::Mat ///////////////////////////
3021
3022 /** @todo document */
3023 class CV_EXPORTS Formatted
3024 {
3025 public:
3026 virtual const char* next() = 0;
3027 virtual void reset() = 0;
3028 virtual ~Formatted();
3029 };
3030
3031 /** @todo document */
3032 class CV_EXPORTS Formatter
3033 {
3034 public:
3035 enum FormatType {
3036 FMT_DEFAULT = 0,
3037 FMT_MATLAB = 1,
3038 FMT_CSV = 2,
3039 FMT_PYTHON = 3,
3040 FMT_NUMPY = 4,
3041 FMT_C = 5
3042 };
3043
3044 virtual ~Formatter();
3045
3046 virtual Ptr<Formatted> format(const Mat& mtx) const = 0;
3047
3048 virtual void set16fPrecision(int p = 4) = 0;
3049 virtual void set32fPrecision(int p = 8) = 0;
3050 virtual void set64fPrecision(int p = 16) = 0;
3051 virtual void setMultiline(bool ml = true) = 0;
3052
3053 static Ptr<Formatter> get(Formatter::FormatType fmt = FMT_DEFAULT);
3054
3055 };
3056
3057 static inline
operator <<(String & out,Ptr<Formatted> fmtd)3058 String& operator << (String& out, Ptr<Formatted> fmtd)
3059 {
3060 fmtd->reset();
3061 for(const char* str = fmtd->next(); str; str = fmtd->next())
3062 out += cv::String(str);
3063 return out;
3064 }
3065
3066 static inline
operator <<(String & out,const Mat & mtx)3067 String& operator << (String& out, const Mat& mtx)
3068 {
3069 return out << Formatter::get()->format(mtx);
3070 }
3071
3072 //////////////////////////////////////// Algorithm ////////////////////////////////////
3073
3074 class CV_EXPORTS Algorithm;
3075
3076 template<typename _Tp, typename _EnumTp = void> struct ParamType {};
3077
3078
3079 /** @brief This is a base class for all more or less complex algorithms in OpenCV
3080
3081 especially for classes of algorithms, for which there can be multiple implementations. The examples
3082 are stereo correspondence (for which there are algorithms like block matching, semi-global block
3083 matching, graph-cut etc.), background subtraction (which can be done using mixture-of-gaussians
3084 models, codebook-based algorithm etc.), optical flow (block matching, Lucas-Kanade, Horn-Schunck
3085 etc.).
3086
3087 Here is example of SimpleBlobDetector use in your application via Algorithm interface:
3088 @snippet snippets/core_various.cpp Algorithm
3089 */
3090 class CV_EXPORTS_W Algorithm
3091 {
3092 public:
3093 Algorithm();
3094 virtual ~Algorithm();
3095
3096 /** @brief Clears the algorithm state
3097 */
clear()3098 CV_WRAP virtual void clear() {}
3099
3100 /** @brief Stores algorithm parameters in a file storage
3101 */
write(FileStorage & fs) const3102 virtual void write(FileStorage& fs) const { CV_UNUSED(fs); }
3103
3104 /** @brief simplified API for language bindings
3105 * @overload
3106 */
3107 CV_WRAP void write(const Ptr<FileStorage>& fs, const String& name = String()) const;
3108
3109 /** @brief Reads algorithm parameters from a file storage
3110 */
read(const FileNode & fn)3111 CV_WRAP virtual void read(const FileNode& fn) { CV_UNUSED(fn); }
3112
3113 /** @brief Returns true if the Algorithm is empty (e.g. in the very beginning or after unsuccessful read
3114 */
empty() const3115 CV_WRAP virtual bool empty() const { return false; }
3116
3117 /** @brief Reads algorithm from the file node
3118
3119 This is static template method of Algorithm. It's usage is following (in the case of SVM):
3120 @code
3121 cv::FileStorage fsRead("example.xml", FileStorage::READ);
3122 Ptr<SVM> svm = Algorithm::read<SVM>(fsRead.root());
3123 @endcode
3124 In order to make this method work, the derived class must overwrite Algorithm::read(const
3125 FileNode& fn) and also have static create() method without parameters
3126 (or with all the optional parameters)
3127 */
read(const FileNode & fn)3128 template<typename _Tp> static Ptr<_Tp> read(const FileNode& fn)
3129 {
3130 Ptr<_Tp> obj = _Tp::create();
3131 obj->read(fn);
3132 return !obj->empty() ? obj : Ptr<_Tp>();
3133 }
3134
3135 /** @brief Loads algorithm from the file
3136
3137 @param filename Name of the file to read.
3138 @param objname The optional name of the node to read (if empty, the first top-level node will be used)
3139
3140 This is static template method of Algorithm. It's usage is following (in the case of SVM):
3141 @code
3142 Ptr<SVM> svm = Algorithm::load<SVM>("my_svm_model.xml");
3143 @endcode
3144 In order to make this method work, the derived class must overwrite Algorithm::read(const
3145 FileNode& fn).
3146 */
load(const String & filename,const String & objname=String ())3147 template<typename _Tp> static Ptr<_Tp> load(const String& filename, const String& objname=String())
3148 {
3149 FileStorage fs(filename, FileStorage::READ);
3150 CV_Assert(fs.isOpened());
3151 FileNode fn = objname.empty() ? fs.getFirstTopLevelNode() : fs[objname];
3152 if (fn.empty()) return Ptr<_Tp>();
3153 Ptr<_Tp> obj = _Tp::create();
3154 obj->read(fn);
3155 return !obj->empty() ? obj : Ptr<_Tp>();
3156 }
3157
3158 /** @brief Loads algorithm from a String
3159
3160 @param strModel The string variable containing the model you want to load.
3161 @param objname The optional name of the node to read (if empty, the first top-level node will be used)
3162
3163 This is static template method of Algorithm. It's usage is following (in the case of SVM):
3164 @code
3165 Ptr<SVM> svm = Algorithm::loadFromString<SVM>(myStringModel);
3166 @endcode
3167 */
loadFromString(const String & strModel,const String & objname=String ())3168 template<typename _Tp> static Ptr<_Tp> loadFromString(const String& strModel, const String& objname=String())
3169 {
3170 FileStorage fs(strModel, FileStorage::READ + FileStorage::MEMORY);
3171 FileNode fn = objname.empty() ? fs.getFirstTopLevelNode() : fs[objname];
3172 Ptr<_Tp> obj = _Tp::create();
3173 obj->read(fn);
3174 return !obj->empty() ? obj : Ptr<_Tp>();
3175 }
3176
3177 /** Saves the algorithm to a file.
3178 In order to make this method work, the derived class must implement Algorithm::write(FileStorage& fs). */
3179 CV_WRAP virtual void save(const String& filename) const;
3180
3181 /** Returns the algorithm string identifier.
3182 This string is used as top level xml/yml node tag when the object is saved to a file or string. */
3183 CV_WRAP virtual String getDefaultName() const;
3184
3185 protected:
3186 void writeFormat(FileStorage& fs) const;
3187 };
3188
3189 enum struct Param {
3190 INT=0, BOOLEAN=1, REAL=2, STRING=3, MAT=4, MAT_VECTOR=5, ALGORITHM=6, FLOAT=7,
3191 UNSIGNED_INT=8, UINT64=9, UCHAR=11, SCALAR=12
3192 };
3193
3194
3195
3196 template<> struct ParamType<bool>
3197 {
3198 typedef bool const_param_type;
3199 typedef bool member_type;
3200
3201 static const Param type = Param::BOOLEAN;
3202 };
3203
3204 template<> struct ParamType<int>
3205 {
3206 typedef int const_param_type;
3207 typedef int member_type;
3208
3209 static const Param type = Param::INT;
3210 };
3211
3212 template<> struct ParamType<double>
3213 {
3214 typedef double const_param_type;
3215 typedef double member_type;
3216
3217 static const Param type = Param::REAL;
3218 };
3219
3220 template<> struct ParamType<String>
3221 {
3222 typedef const String& const_param_type;
3223 typedef String member_type;
3224
3225 static const Param type = Param::STRING;
3226 };
3227
3228 template<> struct ParamType<Mat>
3229 {
3230 typedef const Mat& const_param_type;
3231 typedef Mat member_type;
3232
3233 static const Param type = Param::MAT;
3234 };
3235
3236 template<> struct ParamType<std::vector<Mat> >
3237 {
3238 typedef const std::vector<Mat>& const_param_type;
3239 typedef std::vector<Mat> member_type;
3240
3241 static const Param type = Param::MAT_VECTOR;
3242 };
3243
3244 template<> struct ParamType<Algorithm>
3245 {
3246 typedef const Ptr<Algorithm>& const_param_type;
3247 typedef Ptr<Algorithm> member_type;
3248
3249 static const Param type = Param::ALGORITHM;
3250 };
3251
3252 template<> struct ParamType<float>
3253 {
3254 typedef float const_param_type;
3255 typedef float member_type;
3256
3257 static const Param type = Param::FLOAT;
3258 };
3259
3260 template<> struct ParamType<unsigned>
3261 {
3262 typedef unsigned const_param_type;
3263 typedef unsigned member_type;
3264
3265 static const Param type = Param::UNSIGNED_INT;
3266 };
3267
3268 template<> struct ParamType<uint64>
3269 {
3270 typedef uint64 const_param_type;
3271 typedef uint64 member_type;
3272
3273 static const Param type = Param::UINT64;
3274 };
3275
3276 template<> struct ParamType<uchar>
3277 {
3278 typedef uchar const_param_type;
3279 typedef uchar member_type;
3280
3281 static const Param type = Param::UCHAR;
3282 };
3283
3284 template<> struct ParamType<Scalar>
3285 {
3286 typedef const Scalar& const_param_type;
3287 typedef Scalar member_type;
3288
3289 static const Param type = Param::SCALAR;
3290 };
3291
3292 template<typename _Tp>
3293 struct ParamType<_Tp, typename std::enable_if< std::is_enum<_Tp>::value >::type>
3294 {
3295 typedef typename std::underlying_type<_Tp>::type const_param_type;
3296 typedef typename std::underlying_type<_Tp>::type member_type;
3297
3298 static const Param type = Param::INT;
3299 };
3300
3301 //! @} core_basic
3302
3303 } //namespace cv
3304
3305 #include "opencv2/core/operations.hpp"
3306 #include "opencv2/core/cvstd.inl.hpp"
3307 #include "opencv2/core/utility.hpp"
3308 #include "opencv2/core/optim.hpp"
3309 #include "opencv2/core/ovx.hpp"
3310
3311 #endif /*OPENCV_CORE_HPP*/
3312