1
/*M///////////////////////////////////////////////////////////////////////////////////////
3
// IMPORTANT: READ BEFORE DOWNLOADING, COPYING, INSTALLING OR USING.
5
// By downloading, copying, installing or using the software you agree to this license.
6
// If you do not agree to this license, do not download, install,
7
// copy or use the software.
11
// For Open Source Computer Vision Library
13
// Copyright (C) 2000-2015, Intel Corporation, all rights reserved.
14
// Copyright (C) 2009-2011, Willow Garage Inc., all rights reserved.
15
// Copyright (C) 2015, OpenCV Foundation, all rights reserved.
16
// Copyright (C) 2015, Itseez Inc., all rights reserved.
17
// Third party copyrights are property of their respective owners.
19
// Redistribution and use in source and binary forms, with or without modification,
20
// are permitted provided that the following conditions are met:
22
// * Redistribution's of source code must retain the above copyright notice,
23
// this list of conditions and the following disclaimer.
25
// * Redistribution's in binary form must reproduce the above copyright notice,
26
// this list of conditions and the following disclaimer in the documentation
27
// and/or other materials provided with the distribution.
29
// * The name of the copyright holders may not be used to endorse or promote products
30
// derived from this software without specific prior written permission.
32
// This software is provided by the copyright holders and contributors "as is" and
33
// any express or implied warranties, including, but not limited to, the implied
34
// warranties of merchantability and fitness for a particular purpose are disclaimed.
35
// In no event shall the Intel Corporation or contributors be liable for any direct,
36
// indirect, incidental, special, exemplary, or consequential damages
37
// (including, but not limited to, procurement of substitute goods or services;
38
// loss of use, data, or profits; or business interruption) however caused
39
// and on any theory of liability, whether in contract, strict liability,
40
// or tort (including negligence or otherwise) arising in any way out of
41
// the use of this software, even if advised of the possibility of such damage.
45
#ifndef __OPENCV_CORE_HPP__
46
#define __OPENCV_CORE_HPP__
49
# error core.hpp header must be compiled as C++
52
#include "opencv2/core/cvdef.h"
53
#include "opencv2/core/version.hpp"
54
#include "opencv2/core/base.hpp"
55
#include "opencv2/core/cvstd.hpp"
56
#include "opencv2/core/traits.hpp"
57
#include "opencv2/core/matx.hpp"
58
#include "opencv2/core/types.hpp"
59
#include "opencv2/core/mat.hpp"
60
#include "opencv2/core/persistence.hpp"
63
@defgroup core Core functionality
65
@defgroup core_basic Basic structures
66
@defgroup core_c C structures and operations
68
@defgroup core_c_glue Connections with C++
70
@defgroup core_array Operations on arrays
71
@defgroup core_xml XML/YAML Persistence
72
@defgroup core_cluster Clustering
73
@defgroup core_utils Utility and system functions and macros
75
@defgroup core_utils_sse SSE utilities
76
@defgroup core_utils_neon NEON utilities
78
@defgroup core_opengl OpenGL interoperability
79
@defgroup core_ipp Intel IPP Asynchronous C/C++ Converters
80
@defgroup core_optim Optimization Algorithms
81
@defgroup core_directx DirectX interoperability
82
@defgroup core_eigen Eigen support
83
@defgroup core_opencl OpenCL support
84
@defgroup core_va_intel Intel VA-API/OpenCL (CL-VA) interoperability
85
@defgroup core_hal Hardware Acceleration Layer
87
@defgroup core_hal_functions Functions
88
@defgroup core_hal_interface Interface
89
@defgroup core_hal_intrin Universal intrinsics
91
@defgroup core_hal_intrin_impl Private implementation helpers
99
//! @addtogroup core_utils
102
/*! @brief Class passed to an error.
104
This class encapsulates all or almost all necessary
105
information about the error happened in the program. The exception is
106
usually constructed and thrown implicitly via CV_Error and CV_Error_ macros.
109
class CV_EXPORTS Exception : public std::exception
117
Full constructor. Normally the constuctor is not called explicitly.
118
Instead, the macros CV_Error(), CV_Error_() and CV_Assert() are used.
120
Exception(int _code, const String& _err, const String& _func, const String& _file, int _line);
121
virtual ~Exception() throw();
124
\return the error description and the context as a text string.
126
virtual const char *what() const throw();
127
void formatMessage();
129
String msg; ///< the formatted error message
131
int code; ///< error code @see CVStatus
132
String err; ///< error description
133
String func; ///< function name. Available only when the compiler supports getting it
134
String file; ///< source file name where the error has occured
135
int line; ///< line number in the source file where the error has occured
138
/*! @brief Signals an error and raises the exception.
140
By default the function prints information about the error to stderr,
141
then it either stops if cv::setBreakOnError() had been called before or raises the exception.
142
It is possible to alternate error processing by using cv::redirectError().
143
@param exc the exception raisen.
144
@deprecated drop this version
146
CV_EXPORTS void error( const Exception& exc );
148
enum SortFlags { SORT_EVERY_ROW = 0, //!< each matrix row is sorted independently
149
SORT_EVERY_COLUMN = 1, //!< each matrix column is sorted
150
//!< independently; this flag and the previous one are
151
//!< mutually exclusive.
152
SORT_ASCENDING = 0, //!< each matrix row is sorted in the ascending
154
SORT_DESCENDING = 16 //!< each matrix row is sorted in the
155
//!< descending order; this flag and the previous one are also
156
//!< mutually exclusive.
164
//! Covariation flags
166
/** The output covariance matrix is calculated as:
167
\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]
168
The covariance matrix will be nsamples x nsamples. Such an unusual covariance matrix is used
169
for fast PCA of a set of very large vectors (see, for example, the EigenFaces technique for
170
face recognition). Eigenvalues of this "scrambled" matrix match the eigenvalues of the true
171
covariance matrix. The "true" eigenvectors can be easily calculated from the eigenvectors of
172
the "scrambled" covariance matrix. */
174
/**The output covariance matrix is calculated as:
175
\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]
176
covar will be a square matrix of the same size as the total number of elements in each input
177
vector. One and only one of COVAR_SCRAMBLED and COVAR_NORMAL must be specified.*/
179
/** If the flag is specified, the function does not calculate mean from
180
the input vectors but, instead, uses the passed mean vector. This is useful if mean has been
181
pre-calculated or known in advance, or if the covariance matrix is calculated by parts. In
182
this case, mean is not a mean vector of the input sub-set of vectors but rather the mean
183
vector of the whole set.*/
185
/** If the flag is specified, the covariance matrix is scaled. In the
186
"normal" mode, scale is 1./nsamples . In the "scrambled" mode, scale is the reciprocal of the
187
total number of elements in each input vector. By default (if the flag is not specified), the
188
covariance matrix is not scaled ( scale=1 ).*/
191
specified, all the input vectors are stored as rows of the samples matrix. mean should be a
192
single-row vector in this case.*/
195
specified, all the input vectors are stored as columns of the samples matrix. mean should be a
196
single-column vector in this case.*/
202
/** Select random initial centers in each attempt.*/
203
KMEANS_RANDOM_CENTERS = 0,
204
/** Use kmeans++ center initialization by Arthur and Vassilvitskii [Arthur2007].*/
205
KMEANS_PP_CENTERS = 2,
206
/** During the first (and possibly the only) attempt, use the
207
user-supplied labels instead of computing them from the initial centers. For the second and
208
further attempts, use the random or semi-random centers. Use one of KMEANS_\*_CENTERS flag
209
to specify the exact method.*/
210
KMEANS_USE_INITIAL_LABELS = 1
216
LINE_4 = 4, //!< 4-connected line
217
LINE_8 = 8, //!< 8-connected line
218
LINE_AA = 16 //!< antialiased line
221
//! Only a subset of Hershey fonts
222
//! <http://sources.isc.org/utils/misc/hershey-font.txt> are supported
224
FONT_HERSHEY_SIMPLEX = 0, //!< normal size sans-serif font
225
FONT_HERSHEY_PLAIN = 1, //!< small size sans-serif font
226
FONT_HERSHEY_DUPLEX = 2, //!< normal size sans-serif font (more complex than FONT_HERSHEY_SIMPLEX)
227
FONT_HERSHEY_COMPLEX = 3, //!< normal size serif font
228
FONT_HERSHEY_TRIPLEX = 4, //!< normal size serif font (more complex than FONT_HERSHEY_COMPLEX)
229
FONT_HERSHEY_COMPLEX_SMALL = 5, //!< smaller version of FONT_HERSHEY_COMPLEX
230
FONT_HERSHEY_SCRIPT_SIMPLEX = 6, //!< hand-writing style font
231
FONT_HERSHEY_SCRIPT_COMPLEX = 7, //!< more complex variant of FONT_HERSHEY_SCRIPT_SIMPLEX
232
FONT_ITALIC = 16 //!< flag for italic font
235
enum ReduceTypes { REDUCE_SUM = 0, //!< the output is the sum of all rows/columns of the matrix.
236
REDUCE_AVG = 1, //!< the output is the mean vector of all rows/columns of the matrix.
237
REDUCE_MAX = 2, //!< the output is the maximum (column/row-wise) of all rows/columns of the matrix.
238
REDUCE_MIN = 3 //!< the output is the minimum (column/row-wise) of all rows/columns of the matrix.
242
/** @brief Swaps two matrices
244
CV_EXPORTS void swap(Mat& a, Mat& b);
246
CV_EXPORTS void swap( UMat& a, UMat& b );
250
//! @addtogroup core_array
253
/** @brief Computes the source location of an extrapolated pixel.
255
The function computes and returns the coordinate of a donor pixel corresponding to the specified
256
extrapolated pixel when using the specified extrapolation border mode. For example, if you use
257
cv::BORDER_WRAP mode in the horizontal direction, cv::BORDER_REFLECT_101 in the vertical direction and
258
want to compute value of the "virtual" pixel Point(-5, 100) in a floating-point image img , it
261
float val = img.at<float>(borderInterpolate(100, img.rows, cv::BORDER_REFLECT_101),
262
borderInterpolate(-5, img.cols, cv::BORDER_WRAP));
264
Normally, the function is not called directly. It is used inside filtering functions and also in
266
@param p 0-based coordinate of the extrapolated pixel along one of the axes, likely \<0 or \>= len
267
@param len Length of the array along the corresponding axis.
268
@param borderType Border type, one of the cv::BorderTypes, except for cv::BORDER_TRANSPARENT and
269
cv::BORDER_ISOLATED . When borderType==cv::BORDER_CONSTANT , the function always returns -1, regardless
274
CV_EXPORTS_W int borderInterpolate(int p, int len, int borderType);
276
/** @brief Forms a border around an image.
278
The function copies the source image into the middle of the destination image. The areas to the
279
left, to the right, above and below the copied source image will be filled with extrapolated
280
pixels. This is not what filtering functions based on it do (they extrapolate pixels on-fly), but
281
what other more complex functions, including your own, may do to simplify image boundary handling.
283
The function supports the mode when src is already in the middle of dst . In this case, the
284
function does not copy src itself but simply constructs the border, for example:
287
// let border be the same in all directions
289
// constructs a larger image to fit both the image and the border
290
Mat gray_buf(rgb.rows + border*2, rgb.cols + border*2, rgb.depth());
291
// select the middle part of it w/o copying data
292
Mat gray(gray_canvas, Rect(border, border, rgb.cols, rgb.rows));
293
// convert image from RGB to grayscale
294
cvtColor(rgb, gray, COLOR_RGB2GRAY);
295
// form a border in-place
296
copyMakeBorder(gray, gray_buf, border, border,
297
border, border, BORDER_REPLICATE);
298
// now do some custom filtering ...
301
@note When the source image is a part (ROI) of a bigger image, the function will try to use the
302
pixels outside of the ROI to form a border. To disable this feature and always do extrapolation, as
303
if src was not a ROI, use borderType | BORDER_ISOLATED.
305
@param src Source image.
306
@param dst Destination image of the same type as src and the size Size(src.cols+left+right,
307
src.rows+top+bottom) .
311
@param right Parameter specifying how many pixels in each direction from the source image rectangle
312
to extrapolate. For example, top=1, bottom=1, left=1, right=1 mean that 1 pixel-wide border needs
314
@param borderType Border type. See borderInterpolate for details.
315
@param value Border value if borderType==BORDER_CONSTANT .
317
@sa borderInterpolate
319
CV_EXPORTS_W void copyMakeBorder(InputArray src, OutputArray dst,
320
int top, int bottom, int left, int right,
321
int borderType, const Scalar& value = Scalar() );
323
/** @brief Calculates the per-element sum of two arrays or an array and a scalar.
325
The function add calculates:
326
- Sum of two arrays when both input arrays have the same size and the same number of channels:
327
\f[\texttt{dst}(I) = \texttt{saturate} ( \texttt{src1}(I) + \texttt{src2}(I)) \quad \texttt{if mask}(I) \ne0\f]
328
- Sum of an array and a scalar when src2 is constructed from Scalar or has the same number of
329
elements as `src1.channels()`:
330
\f[\texttt{dst}(I) = \texttt{saturate} ( \texttt{src1}(I) + \texttt{src2} ) \quad \texttt{if mask}(I) \ne0\f]
331
- Sum of a scalar and an array when src1 is constructed from Scalar or has the same number of
332
elements as `src2.channels()`:
333
\f[\texttt{dst}(I) = \texttt{saturate} ( \texttt{src1} + \texttt{src2}(I) ) \quad \texttt{if mask}(I) \ne0\f]
334
where `I` is a multi-dimensional index of array elements. In case of multi-channel arrays, each
335
channel is processed independently.
337
The first function in the list above can be replaced with matrix expressions:
340
dst += src1; // equivalent to add(dst, src1, dst);
342
The input arrays and the output array can all have the same or different depths. For example, you
343
can add a 16-bit unsigned array to a 8-bit signed array and store the sum as a 32-bit
344
floating-point array. Depth of the output array is determined by the dtype parameter. In the second
345
and third cases above, as well as in the first case, when src1.depth() == src2.depth(), dtype can
346
be set to the default -1. In this case, the output array will have the same depth as the input
347
array, be it src1, src2 or both.
348
@note Saturation is not applied when the output array has the depth CV_32S. You may even get
349
result of an incorrect sign in the case of overflow.
350
@param src1 first input array or a scalar.
351
@param src2 second input array or a scalar.
352
@param dst output array that has the same size and number of channels as the input array(s); the
353
depth is defined by dtype or src1/src2.
354
@param mask optional operation mask - 8-bit single channel array, that specifies elements of the
355
output array to be changed.
356
@param dtype optional depth of the output array (see the discussion below).
357
@sa subtract, addWeighted, scaleAdd, Mat::convertTo
359
CV_EXPORTS_W void add(InputArray src1, InputArray src2, OutputArray dst,
360
InputArray mask = noArray(), int dtype = -1);
362
/** @brief Calculates the per-element difference between two arrays or array and a scalar.
364
The function subtract calculates:
365
- Difference between two arrays, when both input arrays have the same size and the same number of
367
\f[\texttt{dst}(I) = \texttt{saturate} ( \texttt{src1}(I) - \texttt{src2}(I)) \quad \texttt{if mask}(I) \ne0\f]
368
- Difference between an array and a scalar, when src2 is constructed from Scalar or has the same
369
number of elements as `src1.channels()`:
370
\f[\texttt{dst}(I) = \texttt{saturate} ( \texttt{src1}(I) - \texttt{src2} ) \quad \texttt{if mask}(I) \ne0\f]
371
- Difference between a scalar and an array, when src1 is constructed from Scalar or has the same
372
number of elements as `src2.channels()`:
373
\f[\texttt{dst}(I) = \texttt{saturate} ( \texttt{src1} - \texttt{src2}(I) ) \quad \texttt{if mask}(I) \ne0\f]
374
- The reverse difference between a scalar and an array in the case of `SubRS`:
375
\f[\texttt{dst}(I) = \texttt{saturate} ( \texttt{src2} - \texttt{src1}(I) ) \quad \texttt{if mask}(I) \ne0\f]
376
where I is a multi-dimensional index of array elements. In case of multi-channel arrays, each
377
channel is processed independently.
379
The first function in the list above can be replaced with matrix expressions:
382
dst -= src1; // equivalent to subtract(dst, src1, dst);
384
The input arrays and the output array can all have the same or different depths. For example, you
385
can subtract to 8-bit unsigned arrays and store the difference in a 16-bit signed array. Depth of
386
the output array is determined by dtype parameter. In the second and third cases above, as well as
387
in the first case, when src1.depth() == src2.depth(), dtype can be set to the default -1. In this
388
case the output array will have the same depth as the input array, be it src1, src2 or both.
389
@note Saturation is not applied when the output array has the depth CV_32S. You may even get
390
result of an incorrect sign in the case of overflow.
391
@param src1 first input array or a scalar.
392
@param src2 second input array or a scalar.
393
@param dst output array of the same size and the same number of channels as the input array.
394
@param mask optional operation mask; this is an 8-bit single channel array that specifies elements
395
of the output array to be changed.
396
@param dtype optional depth of the output array
397
@sa add, addWeighted, scaleAdd, Mat::convertTo
399
CV_EXPORTS_W void subtract(InputArray src1, InputArray src2, OutputArray dst,
400
InputArray mask = noArray(), int dtype = -1);
403
/** @brief Calculates the per-element scaled product of two arrays.
405
The function multiply calculates the per-element product of two arrays:
407
\f[\texttt{dst} (I)= \texttt{saturate} ( \texttt{scale} \cdot \texttt{src1} (I) \cdot \texttt{src2} (I))\f]
409
There is also a @ref MatrixExpressions -friendly variant of the first function. See Mat::mul .
411
For a not-per-element matrix product, see gemm .
413
@note Saturation is not applied when the output array has the depth
414
CV_32S. You may even get result of an incorrect sign in the case of
416
@param src1 first input array.
417
@param src2 second input array of the same size and the same type as src1.
418
@param dst output array of the same size and type as src1.
419
@param scale optional scale factor.
420
@param dtype optional depth of the output array
421
@sa add, subtract, divide, scaleAdd, addWeighted, accumulate, accumulateProduct, accumulateSquare,
424
CV_EXPORTS_W void multiply(InputArray src1, InputArray src2,
425
OutputArray dst, double scale = 1, int dtype = -1);
427
/** @brief Performs per-element division of two arrays or a scalar by an array.
429
The functions divide divide one array by another:
430
\f[\texttt{dst(I) = saturate(src1(I)*scale/src2(I))}\f]
431
or a scalar by an array when there is no src1 :
432
\f[\texttt{dst(I) = saturate(scale/src2(I))}\f]
434
When src2(I) is zero, dst(I) will also be zero. Different channels of
435
multi-channel arrays are processed independently.
437
@note Saturation is not applied when the output array has the depth CV_32S. You may even get
438
result of an incorrect sign in the case of overflow.
439
@param src1 first input array.
440
@param src2 second input array of the same size and type as src1.
441
@param scale scalar factor.
442
@param dst output array of the same size and type as src2.
443
@param dtype optional depth of the output array; if -1, dst will have depth src2.depth(), but in
444
case of an array-by-array division, you can only pass -1 when src1.depth()==src2.depth().
445
@sa multiply, add, subtract
447
CV_EXPORTS_W void divide(InputArray src1, InputArray src2, OutputArray dst,
448
double scale = 1, int dtype = -1);
451
CV_EXPORTS_W void divide(double scale, InputArray src2,
452
OutputArray dst, int dtype = -1);
454
/** @brief Calculates the sum of a scaled array and another array.
456
The function scaleAdd is one of the classical primitive linear algebra operations, known as DAXPY
457
or SAXPY in [BLAS](http://en.wikipedia.org/wiki/Basic_Linear_Algebra_Subprograms). It calculates
458
the sum of a scaled array and another array:
459
\f[\texttt{dst} (I)= \texttt{scale} \cdot \texttt{src1} (I) + \texttt{src2} (I)\f]
460
The function can also be emulated with a matrix expression, for example:
464
A.row(0) = A.row(1)*2 + A.row(2);
466
@param src1 first input array.
467
@param alpha scale factor for the first array.
468
@param src2 second input array of the same size and type as src1.
469
@param dst output array of the same size and type as src1.
470
@sa add, addWeighted, subtract, Mat::dot, Mat::convertTo
472
CV_EXPORTS_W void scaleAdd(InputArray src1, double alpha, InputArray src2, OutputArray dst);
474
/** @brief Calculates the weighted sum of two arrays.
476
The function addWeighted calculates the weighted sum of two arrays as follows:
477
\f[\texttt{dst} (I)= \texttt{saturate} ( \texttt{src1} (I)* \texttt{alpha} + \texttt{src2} (I)* \texttt{beta} + \texttt{gamma} )\f]
478
where I is a multi-dimensional index of array elements. In case of multi-channel arrays, each
479
channel is processed independently.
480
The function can be replaced with a matrix expression:
482
dst = src1*alpha + src2*beta + gamma;
484
@note Saturation is not applied when the output array has the depth CV_32S. You may even get
485
result of an incorrect sign in the case of overflow.
486
@param src1 first input array.
487
@param alpha weight of the first array elements.
488
@param src2 second input array of the same size and channel number as src1.
489
@param beta weight of the second array elements.
490
@param gamma scalar added to each sum.
491
@param dst output array that has the same size and number of channels as the input arrays.
492
@param dtype optional depth of the output array; when both input arrays have the same depth, dtype
493
can be set to -1, which will be equivalent to src1.depth().
494
@sa add, subtract, scaleAdd, Mat::convertTo
496
CV_EXPORTS_W void addWeighted(InputArray src1, double alpha, InputArray src2,
497
double beta, double gamma, OutputArray dst, int dtype = -1);
499
/** @brief Scales, calculates absolute values, and converts the result to 8-bit.
501
On each element of the input array, the function convertScaleAbs
502
performs three operations sequentially: scaling, taking an absolute
503
value, conversion to an unsigned 8-bit type:
504
\f[\texttt{dst} (I)= \texttt{saturate\_cast<uchar>} (| \texttt{src} (I)* \texttt{alpha} + \texttt{beta} |)\f]
505
In case of multi-channel arrays, the function processes each channel
506
independently. When the output is not 8-bit, the operation can be
507
emulated by calling the Mat::convertTo method (or by using matrix
508
expressions) and then by calculating an absolute value of the result.
511
Mat_<float> A(30,30);
512
randu(A, Scalar(-100), Scalar(100));
513
Mat_<float> B = A*5 + 3;
515
// Mat_<float> B = abs(A*5+3) will also do the job,
516
// but it will allocate a temporary matrix
518
@param src input array.
519
@param dst output array.
520
@param alpha optional scale factor.
521
@param beta optional delta added to the scaled values.
522
@sa Mat::convertTo, cv::abs(const Mat&)
524
CV_EXPORTS_W void convertScaleAbs(InputArray src, OutputArray dst,
525
double alpha = 1, double beta = 0);
527
/** @brief Performs a look-up table transform of an array.
529
The function LUT fills the output array with values from the look-up table. Indices of the entries
530
are taken from the input array. That is, the function processes each element of src as follows:
531
\f[\texttt{dst} (I) \leftarrow \texttt{lut(src(I) + d)}\f]
533
\f[d = \fork{0}{if \(\texttt{src}\) has depth \(\texttt{CV_8U}\)}{128}{if \(\texttt{src}\) has depth \(\texttt{CV_8S}\)}\f]
534
@param src input array of 8-bit elements.
535
@param lut look-up table of 256 elements; in case of multi-channel input array, the table should
536
either have a single channel (in this case the same table is used for all channels) or the same
537
number of channels as in the input array.
538
@param dst output array of the same size and number of channels as src, and the same depth as lut.
539
@sa convertScaleAbs, Mat::convertTo
541
CV_EXPORTS_W void LUT(InputArray src, InputArray lut, OutputArray dst);
543
/** @brief Calculates the sum of array elements.
545
The functions sum calculate and return the sum of array elements,
546
independently for each channel.
547
@param src input array that must have from 1 to 4 channels.
548
@sa countNonZero, mean, meanStdDev, norm, minMaxLoc, reduce
550
CV_EXPORTS_AS(sumElems) Scalar sum(InputArray src);
552
/** @brief Counts non-zero array elements.
554
The function returns the number of non-zero elements in src :
555
\f[\sum _{I: \; \texttt{src} (I) \ne0 } 1\f]
556
@param src single-channel array.
557
@sa mean, meanStdDev, norm, minMaxLoc, calcCovarMatrix
559
CV_EXPORTS_W int countNonZero( InputArray src );
561
/** @brief Returns the list of locations of non-zero pixels
563
Given a binary matrix (likely returned from an operation such
564
as threshold(), compare(), >, ==, etc, return all of
565
the non-zero indices as a cv::Mat or std::vector<cv::Point> (x,y)
568
cv::Mat binaryImage; // input, binary image
569
cv::Mat locations; // output, locations of non-zero pixels
570
cv::findNonZero(binaryImage, locations);
572
// access pixel coordinates
573
Point pnt = locations.at<Point>(i);
577
cv::Mat binaryImage; // input, binary image
578
vector<Point> locations; // output, locations of non-zero pixels
579
cv::findNonZero(binaryImage, locations);
581
// access pixel coordinates
582
Point pnt = locations[i];
584
@param src single-channel array (type CV_8UC1)
585
@param idx the output array, type of cv::Mat or std::vector<Point>, corresponding to non-zero indices in the input
587
CV_EXPORTS_W void findNonZero( InputArray src, OutputArray idx );
589
/** @brief Calculates an average (mean) of array elements.
591
The function mean calculates the mean value M of array elements,
592
independently for each channel, and return it:
593
\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]
594
When all the mask elements are 0's, the functions return Scalar::all(0)
595
@param src input array that should have from 1 to 4 channels so that the result can be stored in
597
@param mask optional operation mask.
598
@sa countNonZero, meanStdDev, norm, minMaxLoc
600
CV_EXPORTS_W Scalar mean(InputArray src, InputArray mask = noArray());
602
/** Calculates a mean and standard deviation of array elements.
604
The function meanStdDev calculates the mean and the standard deviation M
605
of array elements independently for each channel and returns it via the
607
\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]
608
When all the mask elements are 0's, the functions return
609
mean=stddev=Scalar::all(0).
610
@note The calculated standard deviation is only the diagonal of the
611
complete normalized covariance matrix. If the full matrix is needed, you
612
can reshape the multi-channel array M x N to the single-channel array
613
M\*N x mtx.channels() (only possible when the matrix is continuous) and
614
then pass the matrix to calcCovarMatrix .
615
@param src input array that should have from 1 to 4 channels so that the results can be stored in
617
@param mean output parameter: calculated mean value.
618
@param stddev output parameter: calculateded standard deviation.
619
@param mask optional operation mask.
620
@sa countNonZero, mean, norm, minMaxLoc, calcCovarMatrix
622
CV_EXPORTS_W void meanStdDev(InputArray src, OutputArray mean, OutputArray stddev,
623
InputArray mask=noArray());
625
/** @brief Calculates an absolute array norm, an absolute difference norm, or a
626
relative difference norm.
628
The functions norm calculate an absolute norm of src1 (when there is no
631
\f[norm = \forkthree{\|\texttt{src1}\|_{L_{\infty}} = \max _I | \texttt{src1} (I)|}{if \(\texttt{normType} = \texttt{NORM_INF}\) }
632
{ \| \texttt{src1} \| _{L_1} = \sum _I | \texttt{src1} (I)|}{if \(\texttt{normType} = \texttt{NORM_L1}\) }
633
{ \| \texttt{src1} \| _{L_2} = \sqrt{\sum_I \texttt{src1}(I)^2} }{if \(\texttt{normType} = \texttt{NORM_L2}\) }\f]
635
or an absolute or relative difference norm if src2 is there:
637
\f[norm = \forkthree{\|\texttt{src1}-\texttt{src2}\|_{L_{\infty}} = \max _I | \texttt{src1} (I) - \texttt{src2} (I)|}{if \(\texttt{normType} = \texttt{NORM_INF}\) }
638
{ \| \texttt{src1} - \texttt{src2} \| _{L_1} = \sum _I | \texttt{src1} (I) - \texttt{src2} (I)|}{if \(\texttt{normType} = \texttt{NORM_L1}\) }
639
{ \| \texttt{src1} - \texttt{src2} \| _{L_2} = \sqrt{\sum_I (\texttt{src1}(I) - \texttt{src2}(I))^2} }{if \(\texttt{normType} = \texttt{NORM_L2}\) }\f]
643
\f[norm = \forkthree{\frac{\|\texttt{src1}-\texttt{src2}\|_{L_{\infty}} }{\|\texttt{src2}\|_{L_{\infty}} }}{if \(\texttt{normType} = \texttt{NORM_RELATIVE_INF}\) }
644
{ \frac{\|\texttt{src1}-\texttt{src2}\|_{L_1} }{\|\texttt{src2}\|_{L_1}} }{if \(\texttt{normType} = \texttt{NORM_RELATIVE_L1}\) }
645
{ \frac{\|\texttt{src1}-\texttt{src2}\|_{L_2} }{\|\texttt{src2}\|_{L_2}} }{if \(\texttt{normType} = \texttt{NORM_RELATIVE_L2}\) }\f]
647
The functions norm return the calculated norm.
649
When the mask parameter is specified and it is not empty, the norm is
650
calculated only over the region specified by the mask.
652
A multi-channel input arrays are treated as a single-channel, that is,
653
the results for all channels are combined.
655
@param src1 first input array.
656
@param normType type of the norm (see cv::NormTypes).
657
@param mask optional operation mask; it must have the same size as src1 and CV_8UC1 type.
659
CV_EXPORTS_W double norm(InputArray src1, int normType = NORM_L2, InputArray mask = noArray());
662
@param src1 first input array.
663
@param src2 second input array of the same size and the same type as src1.
664
@param normType type of the norm (cv::NormTypes).
665
@param mask optional operation mask; it must have the same size as src1 and CV_8UC1 type.
667
CV_EXPORTS_W double norm(InputArray src1, InputArray src2,
668
int normType = NORM_L2, InputArray mask = noArray());
670
@param src first input array.
671
@param normType type of the norm (see cv::NormTypes).
673
CV_EXPORTS double norm( const SparseMat& src, int normType );
675
/** @brief computes PSNR image/video quality metric
677
see http://en.wikipedia.org/wiki/Peak_signal-to-noise_ratio for details
680
CV_EXPORTS_W double PSNR(InputArray src1, InputArray src2);
682
/** @brief naive nearest neighbor finder
684
see http://en.wikipedia.org/wiki/Nearest_neighbor_search
687
CV_EXPORTS_W void batchDistance(InputArray src1, InputArray src2,
688
OutputArray dist, int dtype, OutputArray nidx,
689
int normType = NORM_L2, int K = 0,
690
InputArray mask = noArray(), int update = 0,
691
bool crosscheck = false);
693
/** @brief Normalizes the norm or value range of an array.
695
The functions normalize scale and shift the input array elements so that
696
\f[\| \texttt{dst} \| _{L_p}= \texttt{alpha}\f]
697
(where p=Inf, 1 or 2) when normType=NORM_INF, NORM_L1, or NORM_L2, respectively; or so that
698
\f[\min _I \texttt{dst} (I)= \texttt{alpha} , \, \, \max _I \texttt{dst} (I)= \texttt{beta}\f]
700
when normType=NORM_MINMAX (for dense arrays only). The optional mask specifies a sub-array to be
701
normalized. This means that the norm or min-n-max are calculated over the sub-array, and then this
702
sub-array is modified to be normalized. If you want to only use the mask to calculate the norm or
703
min-max but modify the whole array, you can use norm and Mat::convertTo.
705
In case of sparse matrices, only the non-zero values are analyzed and transformed. Because of this,
706
the range transformation for sparse matrices is not allowed since it can shift the zero level.
708
Possible usage with some positive example data:
710
vector<double> positiveData = { 2.0, 8.0, 10.0 };
711
vector<double> normalizedData_l1, normalizedData_l2, normalizedData_inf, normalizedData_minmax;
713
// Norm to probability (total count)
714
// sum(numbers) = 20.0
715
// 2.0 0.1 (2.0/20.0)
716
// 8.0 0.4 (8.0/20.0)
717
// 10.0 0.5 (10.0/20.0)
718
normalize(positiveData, normalizedData_l1, 1.0, 0.0, NORM_L1);
720
// Norm to unit vector: ||positiveData|| = 1.0
724
normalize(positiveData, normalizedData_l2, 1.0, 0.0, NORM_L2);
726
// Norm to max element
727
// 2.0 0.2 (2.0/10.0)
728
// 8.0 0.8 (8.0/10.0)
729
// 10.0 1.0 (10.0/10.0)
730
normalize(positiveData, normalizedData_inf, 1.0, 0.0, NORM_INF);
732
// Norm to range [0.0;1.0]
733
// 2.0 0.0 (shift to left border)
734
// 8.0 0.75 (6.0/8.0)
735
// 10.0 1.0 (shift to right border)
736
normalize(positiveData, normalizedData_minmax, 1.0, 0.0, NORM_MINMAX);
739
@param src input array.
740
@param dst output array of the same size as src .
741
@param alpha norm value to normalize to or the lower range boundary in case of the range
743
@param beta upper range boundary in case of the range normalization; it is not used for the norm
745
@param norm_type normalization type (see cv::NormTypes).
746
@param dtype when negative, the output array has the same type as src; otherwise, it has the same
747
number of channels as src and the depth =CV_MAT_DEPTH(dtype).
748
@param mask optional operation mask.
749
@sa norm, Mat::convertTo, SparseMat::convertTo
751
CV_EXPORTS_W void normalize( InputArray src, InputOutputArray dst, double alpha = 1, double beta = 0,
752
int norm_type = NORM_L2, int dtype = -1, InputArray mask = noArray());
755
@param src input array.
756
@param dst output array of the same size as src .
757
@param alpha norm value to normalize to or the lower range boundary in case of the range
759
@param normType normalization type (see cv::NormTypes).
761
CV_EXPORTS void normalize( const SparseMat& src, SparseMat& dst, double alpha, int normType );
763
/** @brief Finds the global minimum and maximum in an array.
765
The functions minMaxLoc find the minimum and maximum element values and their positions. The
766
extremums are searched across the whole array or, if mask is not an empty array, in the specified
769
The functions do not work with multi-channel arrays. If you need to find minimum or maximum
770
elements across all the channels, use Mat::reshape first to reinterpret the array as
771
single-channel. Or you may extract the particular channel using either extractImageCOI , or
772
mixChannels , or split .
773
@param src input single-channel array.
774
@param minVal pointer to the returned minimum value; NULL is used if not required.
775
@param maxVal pointer to the returned maximum value; NULL is used if not required.
776
@param minLoc pointer to the returned minimum location (in 2D case); NULL is used if not required.
777
@param maxLoc pointer to the returned maximum location (in 2D case); NULL is used if not required.
778
@param mask optional mask used to select a sub-array.
779
@sa max, min, compare, inRange, extractImageCOI, mixChannels, split, Mat::reshape
781
CV_EXPORTS_W void minMaxLoc(InputArray src, CV_OUT double* minVal,
782
CV_OUT double* maxVal = 0, CV_OUT Point* minLoc = 0,
783
CV_OUT Point* maxLoc = 0, InputArray mask = noArray());
786
/** @brief Finds the global minimum and maximum in an array
788
The function minMaxIdx finds the minimum and maximum element values and their positions. The
789
extremums are searched across the whole array or, if mask is not an empty array, in the specified
790
array region. The function does not work with multi-channel arrays. If you need to find minimum or
791
maximum elements across all the channels, use Mat::reshape first to reinterpret the array as
792
single-channel. Or you may extract the particular channel using either extractImageCOI , or
793
mixChannels , or split . In case of a sparse matrix, the minimum is found among non-zero elements
795
@note When minIdx is not NULL, it must have at least 2 elements (as well as maxIdx), even if src is
796
a single-row or single-column matrix. In OpenCV (following MATLAB) each array has at least 2
797
dimensions, i.e. single-column matrix is Mx1 matrix (and therefore minIdx/maxIdx will be
798
(i1,0)/(i2,0)) and single-row matrix is 1xN matrix (and therefore minIdx/maxIdx will be
800
@param src input single-channel array.
801
@param minVal pointer to the returned minimum value; NULL is used if not required.
802
@param maxVal pointer to the returned maximum value; NULL is used if not required.
803
@param minIdx pointer to the returned minimum location (in nD case); NULL is used if not required;
804
Otherwise, it must point to an array of src.dims elements, the coordinates of the minimum element
805
in each dimension are stored there sequentially.
806
@param maxIdx pointer to the returned maximum location (in nD case). NULL is used if not required.
807
@param mask specified array region
809
CV_EXPORTS void minMaxIdx(InputArray src, double* minVal, double* maxVal = 0,
810
int* minIdx = 0, int* maxIdx = 0, InputArray mask = noArray());
813
@param a input single-channel array.
814
@param minVal pointer to the returned minimum value; NULL is used if not required.
815
@param maxVal pointer to the returned maximum value; NULL is used if not required.
816
@param minIdx pointer to the returned minimum location (in nD case); NULL is used if not required;
817
Otherwise, it must point to an array of src.dims elements, the coordinates of the minimum element
818
in each dimension are stored there sequentially.
819
@param maxIdx pointer to the returned maximum location (in nD case). NULL is used if not required.
821
CV_EXPORTS void minMaxLoc(const SparseMat& a, double* minVal,
822
double* maxVal, int* minIdx = 0, int* maxIdx = 0);
824
/** @brief Reduces a matrix to a vector.
826
The function reduce reduces the matrix to a vector by treating the matrix rows/columns as a set of
827
1D vectors and performing the specified operation on the vectors until a single row/column is
828
obtained. For example, the function can be used to compute horizontal and vertical projections of a
829
raster image. In case of REDUCE_SUM and REDUCE_AVG , the output may have a larger element
830
bit-depth to preserve accuracy. And multi-channel arrays are also supported in these two reduction
832
@param src input 2D matrix.
833
@param dst output vector. Its size and type is defined by dim and dtype parameters.
834
@param dim dimension index along which the matrix is reduced. 0 means that the matrix is reduced to
835
a single row. 1 means that the matrix is reduced to a single column.
836
@param rtype reduction operation that could be one of cv::ReduceTypes
837
@param dtype when negative, the output vector will have the same type as the input matrix,
838
otherwise, its type will be CV_MAKE_TYPE(CV_MAT_DEPTH(dtype), src.channels()).
841
CV_EXPORTS_W void reduce(InputArray src, OutputArray dst, int dim, int rtype, int dtype = -1);
843
/** @brief Creates one multi-channel array out of several single-channel ones.
845
The function merge merges several arrays to make a single multi-channel array. That is, each
846
element of the output array will be a concatenation of the elements of the input arrays, where
847
elements of i-th input array are treated as mv[i].channels()-element vectors.
849
The function cv::split does the reverse operation. If you need to shuffle channels in some other
850
advanced way, use cv::mixChannels.
851
@param mv input array of matrices to be merged; all the matrices in mv must have the same
852
size and the same depth.
853
@param count number of input matrices when mv is a plain C array; it must be greater than zero.
854
@param dst output array of the same size and the same depth as mv[0]; The number of channels will
855
be equal to the parameter count.
856
@sa mixChannels, split, Mat::reshape
858
CV_EXPORTS void merge(const Mat* mv, size_t count, OutputArray dst);
861
@param mv input vector of matrices to be merged; all the matrices in mv must have the same
862
size and the same depth.
863
@param dst output array of the same size and the same depth as mv[0]; The number of channels will
864
be the total number of channels in the matrix array.
866
CV_EXPORTS_W void merge(InputArrayOfArrays mv, OutputArray dst);
868
/** @brief Divides a multi-channel array into several single-channel arrays.
870
The functions split split a multi-channel array into separate single-channel arrays:
871
\f[\texttt{mv} [c](I) = \texttt{src} (I)_c\f]
872
If you need to extract a single channel or do some other sophisticated channel permutation, use
874
@param src input multi-channel array.
875
@param mvbegin output array; the number of arrays must match src.channels(); the arrays themselves are
876
reallocated, if needed.
877
@sa merge, mixChannels, cvtColor
879
CV_EXPORTS void split(const Mat& src, Mat* mvbegin);
882
@param m input multi-channel array.
883
@param mv output vector of arrays; the arrays themselves are reallocated, if needed.
885
CV_EXPORTS_W void split(InputArray m, OutputArrayOfArrays mv);
887
/** @brief Copies specified channels from input arrays to the specified channels of
890
The function cv::mixChannels provides an advanced mechanism for shuffling image channels.
892
cv::split and cv::merge and some forms of cv::cvtColor are partial cases of cv::mixChannels .
894
In the example below, the code splits a 4-channel BGRA image into a 3-channel BGR (with B and R
895
channels swapped) and a separate alpha-channel image:
897
Mat bgra( 100, 100, CV_8UC4, Scalar(255,0,0,255) );
898
Mat bgr( bgra.rows, bgra.cols, CV_8UC3 );
899
Mat alpha( bgra.rows, bgra.cols, CV_8UC1 );
901
// forming an array of matrices is a quite efficient operation,
902
// because the matrix data is not copied, only the headers
903
Mat out[] = { bgr, alpha };
904
// bgra[0] -> bgr[2], bgra[1] -> bgr[1],
905
// bgra[2] -> bgr[0], bgra[3] -> alpha[0]
906
int from_to[] = { 0,2, 1,1, 2,0, 3,3 };
907
mixChannels( &bgra, 1, out, 2, from_to, 4 );
909
@note Unlike many other new-style C++ functions in OpenCV (see the introduction section and
910
Mat::create ), cv::mixChannels requires the output arrays to be pre-allocated before calling the
912
@param src input array or vector of matrices; all of the matrices must have the same size and the
914
@param nsrcs number of matrices in `src`.
915
@param dst output array or vector of matrices; all the matrices **must be allocated**; their size and
916
depth must be the same as in `src[0]`.
917
@param ndsts number of matrices in `dst`.
918
@param fromTo array of index pairs specifying which channels are copied and where; fromTo[k\*2] is
919
a 0-based index of the input channel in src, fromTo[k\*2+1] is an index of the output channel in
920
dst; the continuous channel numbering is used: the first input image channels are indexed from 0 to
921
src[0].channels()-1, the second input image channels are indexed from src[0].channels() to
922
src[0].channels() + src[1].channels()-1, and so on, the same scheme is used for the output image
923
channels; as a special case, when fromTo[k\*2] is negative, the corresponding output channel is
925
@param npairs number of index pairs in `fromTo`.
926
@sa cv::split, cv::merge, cv::cvtColor
928
CV_EXPORTS void mixChannels(const Mat* src, size_t nsrcs, Mat* dst, size_t ndsts,
929
const int* fromTo, size_t npairs);
932
@param src input array or vector of matrices; all of the matrices must have the same size and the
934
@param dst output array or vector of matrices; all the matrices **must be allocated**; their size and
935
depth must be the same as in src[0].
936
@param fromTo array of index pairs specifying which channels are copied and where; fromTo[k\*2] is
937
a 0-based index of the input channel in src, fromTo[k\*2+1] is an index of the output channel in
938
dst; the continuous channel numbering is used: the first input image channels are indexed from 0 to
939
src[0].channels()-1, the second input image channels are indexed from src[0].channels() to
940
src[0].channels() + src[1].channels()-1, and so on, the same scheme is used for the output image
941
channels; as a special case, when fromTo[k\*2] is negative, the corresponding output channel is
943
@param npairs number of index pairs in fromTo.
945
CV_EXPORTS void mixChannels(InputArrayOfArrays src, InputOutputArrayOfArrays dst,
946
const int* fromTo, size_t npairs);
949
@param src input array or vector of matrices; all of the matrices must have the same size and the
951
@param dst output array or vector of matrices; all the matrices **must be allocated**; their size and
952
depth must be the same as in src[0].
953
@param fromTo array of index pairs specifying which channels are copied and where; fromTo[k\*2] is
954
a 0-based index of the input channel in src, fromTo[k\*2+1] is an index of the output channel in
955
dst; the continuous channel numbering is used: the first input image channels are indexed from 0 to
956
src[0].channels()-1, the second input image channels are indexed from src[0].channels() to
957
src[0].channels() + src[1].channels()-1, and so on, the same scheme is used for the output image
958
channels; as a special case, when fromTo[k\*2] is negative, the corresponding output channel is
961
CV_EXPORTS_W void mixChannels(InputArrayOfArrays src, InputOutputArrayOfArrays dst,
962
const std::vector<int>& fromTo);
964
/** @brief extracts a single channel from src (coi is 0-based index)
967
CV_EXPORTS_W void extractChannel(InputArray src, OutputArray dst, int coi);
969
/** @brief inserts a single channel to dst (coi is 0-based index)
972
CV_EXPORTS_W void insertChannel(InputArray src, InputOutputArray dst, int coi);
974
/** @brief Flips a 2D array around vertical, horizontal, or both axes.
976
The function flip flips the array in one of three different ways (row
977
and column indices are 0-based):
978
\f[\texttt{dst} _{ij} =
981
\texttt{src} _{\texttt{src.rows}-i-1,j} & if\; \texttt{flipCode} = 0 \\
982
\texttt{src} _{i, \texttt{src.cols} -j-1} & if\; \texttt{flipCode} > 0 \\
983
\texttt{src} _{ \texttt{src.rows} -i-1, \texttt{src.cols} -j-1} & if\; \texttt{flipCode} < 0 \\
986
The example scenarios of using the function are the following:
987
* Vertical flipping of the image (flipCode == 0) to switch between
988
top-left and bottom-left image origin. This is a typical operation
989
in video processing on Microsoft Windows\* OS.
990
* Horizontal flipping of the image with the subsequent horizontal
991
shift and absolute difference calculation to check for a
992
vertical-axis symmetry (flipCode \> 0).
993
* Simultaneous horizontal and vertical flipping of the image with
994
the subsequent shift and absolute difference calculation to check
995
for a central symmetry (flipCode \< 0).
996
* Reversing the order of point arrays (flipCode \> 0 or
998
@param src input array.
999
@param dst output array of the same size and type as src.
1000
@param flipCode a flag to specify how to flip the array; 0 means
1001
flipping around the x-axis and positive value (for example, 1) means
1002
flipping around y-axis. Negative value (for example, -1) means flipping
1004
@sa transpose , repeat , completeSymm
1006
CV_EXPORTS_W void flip(InputArray src, OutputArray dst, int flipCode);
1008
/** @brief Fills the output array with repeated copies of the input array.
1010
The functions repeat duplicate the input array one or more times along each of the two axes:
1011
\f[\texttt{dst} _{ij}= \texttt{src} _{i\mod src.rows, \; j\mod src.cols }\f]
1012
The second variant of the function is more convenient to use with @ref MatrixExpressions.
1013
@param src input array to replicate.
1014
@param dst output array of the same type as src.
1015
@param ny Flag to specify how many times the src is repeated along the
1017
@param nx Flag to specify how many times the src is repeated along the
1021
CV_EXPORTS_W void repeat(InputArray src, int ny, int nx, OutputArray dst);
1024
@param src input array to replicate.
1025
@param ny Flag to specify how many times the src is repeated along the
1027
@param nx Flag to specify how many times the src is repeated along the
1030
CV_EXPORTS Mat repeat(const Mat& src, int ny, int nx);
1032
/** @brief Applies horizontal concatenation to given matrices.
1034
The function horizontally concatenates two or more cv::Mat matrices (with the same number of rows).
1036
cv::Mat matArray[] = { cv::Mat(4, 1, CV_8UC1, cv::Scalar(1)),
1037
cv::Mat(4, 1, CV_8UC1, cv::Scalar(2)),
1038
cv::Mat(4, 1, CV_8UC1, cv::Scalar(3)),};
1041
cv::hconcat( matArray, 3, out );
1048
@param src input array or vector of matrices. all of the matrices must have the same number of rows and the same depth.
1049
@param nsrc number of matrices in src.
1050
@param dst output array. It has the same number of rows and depth as the src, and the sum of cols of the src.
1051
@sa cv::vconcat(const Mat*, size_t, OutputArray), @sa cv::vconcat(InputArrayOfArrays, OutputArray) and @sa cv::vconcat(InputArray, InputArray, OutputArray)
1053
CV_EXPORTS void hconcat(const Mat* src, size_t nsrc, OutputArray dst);
1056
cv::Mat_<float> A = (cv::Mat_<float>(3, 2) << 1, 4,
1059
cv::Mat_<float> B = (cv::Mat_<float>(3, 2) << 7, 10,
1064
cv::hconcat(A, B, C);
1070
@param src1 first input array to be considered for horizontal concatenation.
1071
@param src2 second input array to be considered for horizontal concatenation.
1072
@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.
1074
CV_EXPORTS void hconcat(InputArray src1, InputArray src2, OutputArray dst);
1077
std::vector<cv::Mat> matrices = { cv::Mat(4, 1, CV_8UC1, cv::Scalar(1)),
1078
cv::Mat(4, 1, CV_8UC1, cv::Scalar(2)),
1079
cv::Mat(4, 1, CV_8UC1, cv::Scalar(3)),};
1082
cv::hconcat( matrices, out );
1089
@param src input array or vector of matrices. all of the matrices must have the same number of rows and the same depth.
1090
@param dst output array. It has the same number of rows and depth as the src, and the sum of cols of the src.
1093
CV_EXPORTS_W void hconcat(InputArrayOfArrays src, OutputArray dst);
1095
/** @brief Applies vertical concatenation to given matrices.
1097
The function vertically concatenates two or more cv::Mat matrices (with the same number of cols).
1099
cv::Mat matArray[] = { cv::Mat(1, 4, CV_8UC1, cv::Scalar(1)),
1100
cv::Mat(1, 4, CV_8UC1, cv::Scalar(2)),
1101
cv::Mat(1, 4, CV_8UC1, cv::Scalar(3)),};
1104
cv::vconcat( matArray, 3, out );
1110
@param src input array or vector of matrices. all of the matrices must have the same number of cols and the same depth.
1111
@param nsrc number of matrices in src.
1112
@param dst output array. It has the same number of cols and depth as the src, and the sum of rows of the src.
1113
@sa cv::hconcat(const Mat*, size_t, OutputArray), @sa cv::hconcat(InputArrayOfArrays, OutputArray) and @sa cv::hconcat(InputArray, InputArray, OutputArray)
1115
CV_EXPORTS void vconcat(const Mat* src, size_t nsrc, OutputArray dst);
1118
cv::Mat_<float> A = (cv::Mat_<float>(3, 2) << 1, 7,
1121
cv::Mat_<float> B = (cv::Mat_<float>(3, 2) << 4, 10,
1126
cv::vconcat(A, B, C);
1135
@param src1 first input array to be considered for vertical concatenation.
1136
@param src2 second input array to be considered for vertical concatenation.
1137
@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.
1139
CV_EXPORTS void vconcat(InputArray src1, InputArray src2, OutputArray dst);
1142
std::vector<cv::Mat> matrices = { cv::Mat(1, 4, CV_8UC1, cv::Scalar(1)),
1143
cv::Mat(1, 4, CV_8UC1, cv::Scalar(2)),
1144
cv::Mat(1, 4, CV_8UC1, cv::Scalar(3)),};
1147
cv::vconcat( matrices, out );
1153
@param src input array or vector of matrices. all of the matrices must have the same number of cols and the same depth
1154
@param dst output array. It has the same number of cols and depth as the src, and the sum of rows of the src.
1157
CV_EXPORTS_W void vconcat(InputArrayOfArrays src, OutputArray dst);
1159
/** @brief computes bitwise conjunction of the two arrays (dst = src1 & src2)
1160
Calculates the per-element bit-wise conjunction of two arrays or an
1163
The function calculates the per-element bit-wise logical conjunction for:
1164
* Two arrays when src1 and src2 have the same size:
1165
\f[\texttt{dst} (I) = \texttt{src1} (I) \wedge \texttt{src2} (I) \quad \texttt{if mask} (I) \ne0\f]
1166
* An array and a scalar when src2 is constructed from Scalar or has
1167
the same number of elements as `src1.channels()`:
1168
\f[\texttt{dst} (I) = \texttt{src1} (I) \wedge \texttt{src2} \quad \texttt{if mask} (I) \ne0\f]
1169
* A scalar and an array when src1 is constructed from Scalar or has
1170
the same number of elements as `src2.channels()`:
1171
\f[\texttt{dst} (I) = \texttt{src1} \wedge \texttt{src2} (I) \quad \texttt{if mask} (I) \ne0\f]
1172
In case of floating-point arrays, their machine-specific bit
1173
representations (usually IEEE754-compliant) are used for the operation.
1174
In case of multi-channel arrays, each channel is processed
1175
independently. In the second and third cases above, the scalar is first
1176
converted to the array type.
1177
@param src1 first input array or a scalar.
1178
@param src2 second input array or a scalar.
1179
@param dst output array that has the same size and type as the input
1181
@param mask optional operation mask, 8-bit single channel array, that
1182
specifies elements of the output array to be changed.
1184
CV_EXPORTS_W void bitwise_and(InputArray src1, InputArray src2,
1185
OutputArray dst, InputArray mask = noArray());
1187
/** @brief Calculates the per-element bit-wise disjunction of two arrays or an
1190
The function calculates the per-element bit-wise logical disjunction for:
1191
* Two arrays when src1 and src2 have the same size:
1192
\f[\texttt{dst} (I) = \texttt{src1} (I) \vee \texttt{src2} (I) \quad \texttt{if mask} (I) \ne0\f]
1193
* An array and a scalar when src2 is constructed from Scalar or has
1194
the same number of elements as `src1.channels()`:
1195
\f[\texttt{dst} (I) = \texttt{src1} (I) \vee \texttt{src2} \quad \texttt{if mask} (I) \ne0\f]
1196
* A scalar and an array when src1 is constructed from Scalar or has
1197
the same number of elements as `src2.channels()`:
1198
\f[\texttt{dst} (I) = \texttt{src1} \vee \texttt{src2} (I) \quad \texttt{if mask} (I) \ne0\f]
1199
In case of floating-point arrays, their machine-specific bit
1200
representations (usually IEEE754-compliant) are used for the operation.
1201
In case of multi-channel arrays, each channel is processed
1202
independently. In the second and third cases above, the scalar is first
1203
converted to the array type.
1204
@param src1 first input array or a scalar.
1205
@param src2 second input array or a scalar.
1206
@param dst output array that has the same size and type as the input
1208
@param mask optional operation mask, 8-bit single channel array, that
1209
specifies elements of the output array to be changed.
1211
CV_EXPORTS_W void bitwise_or(InputArray src1, InputArray src2,
1212
OutputArray dst, InputArray mask = noArray());
1214
/** @brief Calculates the per-element bit-wise "exclusive or" operation on two
1215
arrays or an array and a scalar.
1217
The function calculates the per-element bit-wise logical "exclusive-or"
1219
* Two arrays when src1 and src2 have the same size:
1220
\f[\texttt{dst} (I) = \texttt{src1} (I) \oplus \texttt{src2} (I) \quad \texttt{if mask} (I) \ne0\f]
1221
* An array and a scalar when src2 is constructed from Scalar or has
1222
the same number of elements as `src1.channels()`:
1223
\f[\texttt{dst} (I) = \texttt{src1} (I) \oplus \texttt{src2} \quad \texttt{if mask} (I) \ne0\f]
1224
* A scalar and an array when src1 is constructed from Scalar or has
1225
the same number of elements as `src2.channels()`:
1226
\f[\texttt{dst} (I) = \texttt{src1} \oplus \texttt{src2} (I) \quad \texttt{if mask} (I) \ne0\f]
1227
In case of floating-point arrays, their machine-specific bit
1228
representations (usually IEEE754-compliant) are used for the operation.
1229
In case of multi-channel arrays, each channel is processed
1230
independently. In the 2nd and 3rd cases above, the scalar is first
1231
converted to the array type.
1232
@param src1 first input array or a scalar.
1233
@param src2 second input array or a scalar.
1234
@param dst output array that has the same size and type as the input
1236
@param mask optional operation mask, 8-bit single channel array, that
1237
specifies elements of the output array to be changed.
1239
CV_EXPORTS_W void bitwise_xor(InputArray src1, InputArray src2,
1240
OutputArray dst, InputArray mask = noArray());
1242
/** @brief Inverts every bit of an array.
1244
The function calculates per-element bit-wise inversion of the input
1246
\f[\texttt{dst} (I) = \neg \texttt{src} (I)\f]
1247
In case of a floating-point input array, its machine-specific bit
1248
representation (usually IEEE754-compliant) is used for the operation. In
1249
case of multi-channel arrays, each channel is processed independently.
1250
@param src input array.
1251
@param dst output array that has the same size and type as the input
1253
@param mask optional operation mask, 8-bit single channel array, that
1254
specifies elements of the output array to be changed.
1256
CV_EXPORTS_W void bitwise_not(InputArray src, OutputArray dst,
1257
InputArray mask = noArray());
1259
/** @brief Calculates the per-element absolute difference between two arrays or between an array and a scalar.
1261
The function absdiff calculates:
1262
* Absolute difference between two arrays when they have the same
1264
\f[\texttt{dst}(I) = \texttt{saturate} (| \texttt{src1}(I) - \texttt{src2}(I)|)\f]
1265
* Absolute difference between an array and a scalar when the second
1266
array is constructed from Scalar or has as many elements as the
1267
number of channels in `src1`:
1268
\f[\texttt{dst}(I) = \texttt{saturate} (| \texttt{src1}(I) - \texttt{src2} |)\f]
1269
* Absolute difference between a scalar and an array when the first
1270
array is constructed from Scalar or has as many elements as the
1271
number of channels in `src2`:
1272
\f[\texttt{dst}(I) = \texttt{saturate} (| \texttt{src1} - \texttt{src2}(I) |)\f]
1273
where I is a multi-dimensional index of array elements. In case of
1274
multi-channel arrays, each channel is processed independently.
1275
@note Saturation is not applied when the arrays have the depth CV_32S.
1276
You may even get a negative value in the case of overflow.
1277
@param src1 first input array or a scalar.
1278
@param src2 second input array or a scalar.
1279
@param dst output array that has the same size and type as input arrays.
1280
@sa cv::abs(const Mat&)
1282
CV_EXPORTS_W void absdiff(InputArray src1, InputArray src2, OutputArray dst);
1284
/** @brief Checks if array elements lie between the elements of two other arrays.
1286
The function checks the range as follows:
1287
- For every element of a single-channel input array:
1288
\f[\texttt{dst} (I)= \texttt{lowerb} (I)_0 \leq \texttt{src} (I)_0 \leq \texttt{upperb} (I)_0\f]
1289
- For two-channel arrays:
1290
\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]
1293
That is, dst (I) is set to 255 (all 1 -bits) if src (I) is within the
1294
specified 1D, 2D, 3D, ... box and 0 otherwise.
1296
When the lower and/or upper boundary parameters are scalars, the indexes
1297
(I) at lowerb and upperb in the above formulas should be omitted.
1298
@param src first input array.
1299
@param lowerb inclusive lower boundary array or a scalar.
1300
@param upperb inclusive upper boundary array or a scalar.
1301
@param dst output array of the same size as src and CV_8U type.
1303
CV_EXPORTS_W void inRange(InputArray src, InputArray lowerb,
1304
InputArray upperb, OutputArray dst);
1306
/** @brief Performs the per-element comparison of two arrays or an array and scalar value.
1308
The function compares:
1309
* Elements of two arrays when src1 and src2 have the same size:
1310
\f[\texttt{dst} (I) = \texttt{src1} (I) \,\texttt{cmpop}\, \texttt{src2} (I)\f]
1311
* Elements of src1 with a scalar src2 when src2 is constructed from
1312
Scalar or has a single element:
1313
\f[\texttt{dst} (I) = \texttt{src1}(I) \,\texttt{cmpop}\, \texttt{src2}\f]
1314
* src1 with elements of src2 when src1 is constructed from Scalar or
1315
has a single element:
1316
\f[\texttt{dst} (I) = \texttt{src1} \,\texttt{cmpop}\, \texttt{src2} (I)\f]
1317
When the comparison result is true, the corresponding element of output
1318
array is set to 255. The comparison operations can be replaced with the
1319
equivalent matrix expressions:
1321
Mat dst1 = src1 >= src2;
1322
Mat dst2 = src1 < 8;
1325
@param src1 first input array or a scalar; when it is an array, it must have a single channel.
1326
@param src2 second input array or a scalar; when it is an array, it must have a single channel.
1327
@param dst output array of type ref CV_8U that has the same size and the same number of channels as
1329
@param cmpop a flag, that specifies correspondence between the arrays (cv::CmpTypes)
1330
@sa checkRange, min, max, threshold
1332
CV_EXPORTS_W void compare(InputArray src1, InputArray src2, OutputArray dst, int cmpop);
1334
/** @brief Calculates per-element minimum of two arrays or an array and a scalar.
1336
The functions min calculate the per-element minimum of two arrays:
1337
\f[\texttt{dst} (I)= \min ( \texttt{src1} (I), \texttt{src2} (I))\f]
1338
or array and a scalar:
1339
\f[\texttt{dst} (I)= \min ( \texttt{src1} (I), \texttt{value} )\f]
1340
@param src1 first input array.
1341
@param src2 second input array of the same size and type as src1.
1342
@param dst output array of the same size and type as src1.
1343
@sa max, compare, inRange, minMaxLoc
1345
CV_EXPORTS_W void min(InputArray src1, InputArray src2, OutputArray dst);
1347
needed to avoid conflicts with const _Tp& std::min(const _Tp&, const _Tp&, _Compare)
1349
CV_EXPORTS void min(const Mat& src1, const Mat& src2, Mat& dst);
1351
needed to avoid conflicts with const _Tp& std::min(const _Tp&, const _Tp&, _Compare)
1353
CV_EXPORTS void min(const UMat& src1, const UMat& src2, UMat& dst);
1355
/** @brief Calculates per-element maximum of two arrays or an array and a scalar.
1357
The functions max calculate the per-element maximum of two arrays:
1358
\f[\texttt{dst} (I)= \max ( \texttt{src1} (I), \texttt{src2} (I))\f]
1359
or array and a scalar:
1360
\f[\texttt{dst} (I)= \max ( \texttt{src1} (I), \texttt{value} )\f]
1361
@param src1 first input array.
1362
@param src2 second input array of the same size and type as src1 .
1363
@param dst output array of the same size and type as src1.
1364
@sa min, compare, inRange, minMaxLoc, @ref MatrixExpressions
1366
CV_EXPORTS_W void max(InputArray src1, InputArray src2, OutputArray dst);
1368
needed to avoid conflicts with const _Tp& std::min(const _Tp&, const _Tp&, _Compare)
1370
CV_EXPORTS void max(const Mat& src1, const Mat& src2, Mat& dst);
1372
needed to avoid conflicts with const _Tp& std::min(const _Tp&, const _Tp&, _Compare)
1374
CV_EXPORTS void max(const UMat& src1, const UMat& src2, UMat& dst);
1376
/** @brief Calculates a square root of array elements.
1378
The functions sqrt calculate a square root of each input array element.
1379
In case of multi-channel arrays, each channel is processed
1380
independently. The accuracy is approximately the same as of the built-in
1382
@param src input floating-point array.
1383
@param dst output array of the same size and type as src.
1385
CV_EXPORTS_W void sqrt(InputArray src, OutputArray dst);
1387
/** @brief Raises every array element to a power.
1389
The function pow raises every element of the input array to power :
1390
\f[\texttt{dst} (I) = \fork{\texttt{src}(I)^{power}}{if \(\texttt{power}\) is integer}{|\texttt{src}(I)|^{power}}{otherwise}\f]
1392
So, for a non-integer power exponent, the absolute values of input array
1393
elements are used. However, it is possible to get true values for
1394
negative values using some extra operations. In the example below,
1395
computing the 5th root of array src shows:
1398
pow(src, 1./5, dst);
1399
subtract(Scalar::all(0), dst, dst, mask);
1401
For some values of power, such as integer values, 0.5 and -0.5,
1402
specialized faster algorithms are used.
1404
Special values (NaN, Inf) are not handled.
1405
@param src input array.
1406
@param power exponent of power.
1407
@param dst output array of the same size and type as src.
1408
@sa sqrt, exp, log, cartToPolar, polarToCart
1410
CV_EXPORTS_W void pow(InputArray src, double power, OutputArray dst);
1412
/** @brief Calculates the exponent of every array element.
1414
The function exp calculates the exponent of every element of the input
1416
\f[\texttt{dst} [I] = e^{ src(I) }\f]
1418
The maximum relative error is about 7e-6 for single-precision input and
1419
less than 1e-10 for double-precision input. Currently, the function
1420
converts denormalized values to zeros on output. Special values (NaN,
1421
Inf) are not handled.
1422
@param src input array.
1423
@param dst output array of the same size and type as src.
1424
@sa log , cartToPolar , polarToCart , phase , pow , sqrt , magnitude
1426
CV_EXPORTS_W void exp(InputArray src, OutputArray dst);
1428
/** @brief Calculates the natural logarithm of every array element.
1430
The function log calculates the natural logarithm of the absolute value
1431
of every element of the input array:
1432
\f[\texttt{dst} (I) = \fork{\log |\texttt{src}(I)|}{if \(\texttt{src}(I) \ne 0\) }{\texttt{C}}{otherwise}\f]
1434
where C is a large negative number (about -700 in the current
1435
implementation). The maximum relative error is about 7e-6 for
1436
single-precision input and less than 1e-10 for double-precision input.
1437
Special values (NaN, Inf) are not handled.
1438
@param src input array.
1439
@param dst output array of the same size and type as src .
1440
@sa exp, cartToPolar, polarToCart, phase, pow, sqrt, magnitude
1442
CV_EXPORTS_W void log(InputArray src, OutputArray dst);
1444
/** @brief Calculates x and y coordinates of 2D vectors from their magnitude and angle.
1446
The function polarToCart calculates the Cartesian coordinates of each 2D
1447
vector represented by the corresponding elements of magnitude and angle:
1448
\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]
1450
The relative accuracy of the estimated coordinates is about 1e-6.
1451
@param magnitude input floating-point array of magnitudes of 2D vectors;
1452
it can be an empty matrix (=Mat()), in this case, the function assumes
1453
that all the magnitudes are =1; if it is not empty, it must have the
1454
same size and type as angle.
1455
@param angle input floating-point array of angles of 2D vectors.
1456
@param x output array of x-coordinates of 2D vectors; it has the same
1457
size and type as angle.
1458
@param y output array of y-coordinates of 2D vectors; it has the same
1459
size and type as angle.
1460
@param angleInDegrees when true, the input angles are measured in
1461
degrees, otherwise, they are measured in radians.
1462
@sa cartToPolar, magnitude, phase, exp, log, pow, sqrt
1464
CV_EXPORTS_W void polarToCart(InputArray magnitude, InputArray angle,
1465
OutputArray x, OutputArray y, bool angleInDegrees = false);
1467
/** @brief Calculates the magnitude and angle of 2D vectors.
1469
The function cartToPolar calculates either the magnitude, angle, or both
1470
for every 2D vector (x(I),y(I)):
1471
\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]
1473
The angles are calculated with accuracy about 0.3 degrees. For the point
1474
(0,0), the angle is set to 0.
1475
@param x array of x-coordinates; this must be a single-precision or
1476
double-precision floating-point array.
1477
@param y array of y-coordinates, that must have the same size and same type as x.
1478
@param magnitude output array of magnitudes of the same size and type as x.
1479
@param angle output array of angles that has the same size and type as
1480
x; the angles are measured in radians (from 0 to 2\*Pi) or in degrees (0 to 360 degrees).
1481
@param angleInDegrees a flag, indicating whether the angles are measured
1482
in radians (which is by default), or in degrees.
1485
CV_EXPORTS_W void cartToPolar(InputArray x, InputArray y,
1486
OutputArray magnitude, OutputArray angle,
1487
bool angleInDegrees = false);
1489
/** @brief Calculates the rotation angle of 2D vectors.
1491
The function phase calculates the rotation angle of each 2D vector that
1492
is formed from the corresponding elements of x and y :
1493
\f[\texttt{angle} (I) = \texttt{atan2} ( \texttt{y} (I), \texttt{x} (I))\f]
1495
The angle estimation accuracy is about 0.3 degrees. When x(I)=y(I)=0 ,
1496
the corresponding angle(I) is set to 0.
1497
@param x input floating-point array of x-coordinates of 2D vectors.
1498
@param y input array of y-coordinates of 2D vectors; it must have the
1499
same size and the same type as x.
1500
@param angle output array of vector angles; it has the same size and
1502
@param angleInDegrees when true, the function calculates the angle in
1503
degrees, otherwise, they are measured in radians.
1505
CV_EXPORTS_W void phase(InputArray x, InputArray y, OutputArray angle,
1506
bool angleInDegrees = false);
1508
/** @brief Calculates the magnitude of 2D vectors.
1510
The function magnitude calculates the magnitude of 2D vectors formed
1511
from the corresponding elements of x and y arrays:
1512
\f[\texttt{dst} (I) = \sqrt{\texttt{x}(I)^2 + \texttt{y}(I)^2}\f]
1513
@param x floating-point array of x-coordinates of the vectors.
1514
@param y floating-point array of y-coordinates of the vectors; it must
1515
have the same size as x.
1516
@param magnitude output array of the same size and type as x.
1517
@sa cartToPolar, polarToCart, phase, sqrt
1519
CV_EXPORTS_W void magnitude(InputArray x, InputArray y, OutputArray magnitude);
1521
/** @brief Checks every element of an input array for invalid values.
1523
The functions checkRange check that every array element is neither NaN nor infinite. When minVal \>
1524
-DBL_MAX and maxVal \< DBL_MAX, the functions also check that each value is between minVal and
1525
maxVal. In case of multi-channel arrays, each channel is processed independently. If some values
1526
are out of range, position of the first outlier is stored in pos (when pos != NULL). Then, the
1527
functions either return false (when quiet=true) or throw an exception.
1528
@param a input array.
1529
@param quiet a flag, indicating whether the functions quietly return false when the array elements
1530
are out of range or they throw an exception.
1531
@param pos optional output parameter, when not NULL, must be a pointer to array of src.dims
1533
@param minVal inclusive lower boundary of valid values range.
1534
@param maxVal exclusive upper boundary of valid values range.
1536
CV_EXPORTS_W bool checkRange(InputArray a, bool quiet = true, CV_OUT Point* pos = 0,
1537
double minVal = -DBL_MAX, double maxVal = DBL_MAX);
1539
/** @brief converts NaN's to the given number
1541
CV_EXPORTS_W void patchNaNs(InputOutputArray a, double val = 0);
1543
/** @brief Performs generalized matrix multiplication.
1545
The function performs generalized matrix multiplication similar to the
1546
gemm functions in BLAS level 3. For example,
1547
`gemm(src1, src2, alpha, src3, beta, dst, GEMM_1_T + GEMM_3_T)`
1549
\f[\texttt{dst} = \texttt{alpha} \cdot \texttt{src1} ^T \cdot \texttt{src2} + \texttt{beta} \cdot \texttt{src3} ^T\f]
1551
In case of complex (two-channel) data, performed a complex matrix
1554
The function can be replaced with a matrix expression. For example, the
1555
above call can be replaced with:
1557
dst = alpha*src1.t()*src2 + beta*src3.t();
1559
@param src1 first multiplied input matrix that could be real(CV_32FC1,
1560
CV_64FC1) or complex(CV_32FC2, CV_64FC2).
1561
@param src2 second multiplied input matrix of the same type as src1.
1562
@param alpha weight of the matrix product.
1563
@param src3 third optional delta matrix added to the matrix product; it
1564
should have the same type as src1 and src2.
1565
@param beta weight of src3.
1566
@param dst output matrix; it has the proper size and the same type as
1568
@param flags operation flags (cv::GemmFlags)
1569
@sa mulTransposed , transform
1571
CV_EXPORTS_W void gemm(InputArray src1, InputArray src2, double alpha,
1572
InputArray src3, double beta, OutputArray dst, int flags = 0);
1574
/** @brief Calculates the product of a matrix and its transposition.
1576
The function mulTransposed calculates the product of src and its
1578
\f[\texttt{dst} = \texttt{scale} ( \texttt{src} - \texttt{delta} )^T ( \texttt{src} - \texttt{delta} )\f]
1580
\f[\texttt{dst} = \texttt{scale} ( \texttt{src} - \texttt{delta} ) ( \texttt{src} - \texttt{delta} )^T\f]
1581
otherwise. The function is used to calculate the covariance matrix. With
1582
zero delta, it can be used as a faster substitute for general matrix
1583
product A\*B when B=A'
1584
@param src input single-channel matrix. Note that unlike gemm, the
1585
function can multiply not only floating-point matrices.
1586
@param dst output square matrix.
1587
@param aTa Flag specifying the multiplication ordering. See the
1589
@param delta Optional delta matrix subtracted from src before the
1590
multiplication. When the matrix is empty ( delta=noArray() ), it is
1591
assumed to be zero, that is, nothing is subtracted. If it has the same
1592
size as src , it is simply subtracted. Otherwise, it is "repeated" (see
1593
repeat ) to cover the full src and then subtracted. Type of the delta
1594
matrix, when it is not empty, must be the same as the type of created
1595
output matrix. See the dtype parameter description below.
1596
@param scale Optional scale factor for the matrix product.
1597
@param dtype Optional type of the output matrix. When it is negative,
1598
the output matrix will have the same type as src . Otherwise, it will be
1599
type=CV_MAT_DEPTH(dtype) that should be either CV_32F or CV_64F .
1600
@sa calcCovarMatrix, gemm, repeat, reduce
1602
CV_EXPORTS_W void mulTransposed( InputArray src, OutputArray dst, bool aTa,
1603
InputArray delta = noArray(),
1604
double scale = 1, int dtype = -1 );
1606
/** @brief Transposes a matrix.
1608
The function transpose transposes the matrix src :
1609
\f[\texttt{dst} (i,j) = \texttt{src} (j,i)\f]
1610
@note No complex conjugation is done in case of a complex matrix. It it
1611
should be done separately if needed.
1612
@param src input array.
1613
@param dst output array of the same type as src.
1615
CV_EXPORTS_W void transpose(InputArray src, OutputArray dst);
1617
/** @brief Performs the matrix transformation of every array element.
1619
The function transform performs the matrix transformation of every
1620
element of the array src and stores the results in dst :
1621
\f[\texttt{dst} (I) = \texttt{m} \cdot \texttt{src} (I)\f]
1622
(when m.cols=src.channels() ), or
1623
\f[\texttt{dst} (I) = \texttt{m} \cdot [ \texttt{src} (I); 1]\f]
1624
(when m.cols=src.channels()+1 )
1626
Every element of the N -channel array src is interpreted as N -element
1627
vector that is transformed using the M x N or M x (N+1) matrix m to
1628
M-element vector - the corresponding element of the output array dst .
1630
The function may be used for geometrical transformation of
1631
N -dimensional points, arbitrary linear color space transformation (such
1632
as various kinds of RGB to YUV transforms), shuffling the image
1633
channels, and so forth.
1634
@param src input array that must have as many channels (1 to 4) as
1636
@param dst output array of the same size and depth as src; it has as
1637
many channels as m.rows.
1638
@param m transformation 2x2 or 2x3 floating-point matrix.
1639
@sa perspectiveTransform, getAffineTransform, estimateRigidTransform, warpAffine, warpPerspective
1641
CV_EXPORTS_W void transform(InputArray src, OutputArray dst, InputArray m );
1643
/** @brief Performs the perspective matrix transformation of vectors.
1645
The function perspectiveTransform transforms every element of src by
1646
treating it as a 2D or 3D vector, in the following way:
1647
\f[(x, y, z) \rightarrow (x'/w, y'/w, z'/w)\f]
1649
\f[(x', y', z', w') = \texttt{mat} \cdot \begin{bmatrix} x & y & z & 1 \end{bmatrix}\f]
1651
\f[w = \fork{w'}{if \(w' \ne 0\)}{\infty}{otherwise}\f]
1653
Here a 3D vector transformation is shown. In case of a 2D vector
1654
transformation, the z component is omitted.
1656
@note The function transforms a sparse set of 2D or 3D vectors. If you
1657
want to transform an image using perspective transformation, use
1658
warpPerspective . If you have an inverse problem, that is, you want to
1659
compute the most probable perspective transformation out of several
1660
pairs of corresponding points, you can use getPerspectiveTransform or
1662
@param src input two-channel or three-channel floating-point array; each
1663
element is a 2D/3D vector to be transformed.
1664
@param dst output array of the same size and type as src.
1665
@param m 3x3 or 4x4 floating-point transformation matrix.
1666
@sa transform, warpPerspective, getPerspectiveTransform, findHomography
1668
CV_EXPORTS_W void perspectiveTransform(InputArray src, OutputArray dst, InputArray m );
1670
/** @brief Copies the lower or the upper half of a square matrix to another half.
1672
The function completeSymm copies the lower half of a square matrix to
1673
its another half. The matrix diagonal remains unchanged:
1674
* \f$\texttt{mtx}_{ij}=\texttt{mtx}_{ji}\f$ for \f$i > j\f$ if
1676
* \f$\texttt{mtx}_{ij}=\texttt{mtx}_{ji}\f$ for \f$i < j\f$ if
1678
@param mtx input-output floating-point square matrix.
1679
@param lowerToUpper operation flag; if true, the lower half is copied to
1680
the upper half. Otherwise, the upper half is copied to the lower half.
1683
CV_EXPORTS_W void completeSymm(InputOutputArray mtx, bool lowerToUpper = false);
1685
/** @brief Initializes a scaled identity matrix.
1687
The function setIdentity initializes a scaled identity matrix:
1688
\f[\texttt{mtx} (i,j)= \fork{\texttt{value}}{ if \(i=j\)}{0}{otherwise}\f]
1690
The function can also be emulated using the matrix initializers and the
1693
Mat A = Mat::eye(4, 3, CV_32F)*5;
1694
// A will be set to [[5, 0, 0], [0, 5, 0], [0, 0, 5], [0, 0, 0]]
1696
@param mtx matrix to initialize (not necessarily square).
1697
@param s value to assign to diagonal elements.
1698
@sa Mat::zeros, Mat::ones, Mat::setTo, Mat::operator=
1700
CV_EXPORTS_W void setIdentity(InputOutputArray mtx, const Scalar& s = Scalar(1));
1702
/** @brief Returns the determinant of a square floating-point matrix.
1704
The function determinant calculates and returns the determinant of the
1705
specified matrix. For small matrices ( mtx.cols=mtx.rows\<=3 ), the
1706
direct method is used. For larger matrices, the function uses LU
1707
factorization with partial pivoting.
1709
For symmetric positively-determined matrices, it is also possible to use
1710
eigen decomposition to calculate the determinant.
1711
@param mtx input matrix that must have CV_32FC1 or CV_64FC1 type and
1713
@sa trace, invert, solve, eigen, @ref MatrixExpressions
1715
CV_EXPORTS_W double determinant(InputArray mtx);
1717
/** @brief Returns the trace of a matrix.
1719
The function trace returns the sum of the diagonal elements of the
1721
\f[\mathrm{tr} ( \texttt{mtx} ) = \sum _i \texttt{mtx} (i,i)\f]
1722
@param mtx input matrix.
1724
CV_EXPORTS_W Scalar trace(InputArray mtx);
1726
/** @brief Finds the inverse or pseudo-inverse of a matrix.
1728
The function invert inverts the matrix src and stores the result in dst
1729
. When the matrix src is singular or non-square, the function calculates
1730
the pseudo-inverse matrix (the dst matrix) so that norm(src\*dst - I) is
1731
minimal, where I is an identity matrix.
1733
In case of the DECOMP_LU method, the function returns non-zero value if
1734
the inverse has been successfully calculated and 0 if src is singular.
1736
In case of the DECOMP_SVD method, the function returns the inverse
1737
condition number of src (the ratio of the smallest singular value to the
1738
largest singular value) and 0 if src is singular. The SVD method
1739
calculates a pseudo-inverse matrix if src is singular.
1741
Similarly to DECOMP_LU, the method DECOMP_CHOLESKY works only with
1742
non-singular square matrices that should also be symmetrical and
1743
positively defined. In this case, the function stores the inverted
1744
matrix in dst and returns non-zero. Otherwise, it returns 0.
1746
@param src input floating-point M x N matrix.
1747
@param dst output matrix of N x M size and the same type as src.
1748
@param flags inversion method (cv::DecompTypes)
1751
CV_EXPORTS_W double invert(InputArray src, OutputArray dst, int flags = DECOMP_LU);
1753
/** @brief Solves one or more linear systems or least-squares problems.
1755
The function solve solves a linear system or least-squares problem (the
1756
latter is possible with SVD or QR methods, or by specifying the flag
1758
\f[\texttt{dst} = \arg \min _X \| \texttt{src1} \cdot \texttt{X} - \texttt{src2} \|\f]
1760
If DECOMP_LU or DECOMP_CHOLESKY method is used, the function returns 1
1761
if src1 (or \f$\texttt{src1}^T\texttt{src1}\f$ ) is non-singular. Otherwise,
1762
it returns 0. In the latter case, dst is not valid. Other methods find a
1763
pseudo-solution in case of a singular left-hand side part.
1765
@note If you want to find a unity-norm solution of an under-defined
1766
singular system \f$\texttt{src1}\cdot\texttt{dst}=0\f$ , the function solve
1767
will not do the work. Use SVD::solveZ instead.
1769
@param src1 input matrix on the left-hand side of the system.
1770
@param src2 input matrix on the right-hand side of the system.
1771
@param dst output solution.
1772
@param flags solution (matrix inversion) method (cv::DecompTypes)
1773
@sa invert, SVD, eigen
1775
CV_EXPORTS_W bool solve(InputArray src1, InputArray src2,
1776
OutputArray dst, int flags = DECOMP_LU);
1778
/** @brief Sorts each row or each column of a matrix.
1780
The function sort sorts each matrix row or each matrix column in
1781
ascending or descending order. So you should pass two operation flags to
1782
get desired behaviour. If you want to sort matrix rows or columns
1783
lexicographically, you can use STL std::sort generic function with the
1784
proper comparison predicate.
1786
@param src input single-channel array.
1787
@param dst output array of the same size and type as src.
1788
@param flags operation flags, a combination of cv::SortFlags
1789
@sa sortIdx, randShuffle
1791
CV_EXPORTS_W void sort(InputArray src, OutputArray dst, int flags);
1793
/** @brief Sorts each row or each column of a matrix.
1795
The function sortIdx sorts each matrix row or each matrix column in the
1796
ascending or descending order. So you should pass two operation flags to
1797
get desired behaviour. Instead of reordering the elements themselves, it
1798
stores the indices of sorted elements in the output array. For example:
1800
Mat A = Mat::eye(3,3,CV_32F), B;
1801
sortIdx(A, B, SORT_EVERY_ROW + SORT_ASCENDING);
1802
// B will probably contain
1803
// (because of equal elements in A some permutations are possible):
1804
// [[1, 2, 0], [0, 2, 1], [0, 1, 2]]
1806
@param src input single-channel array.
1807
@param dst output integer array of the same size as src.
1808
@param flags operation flags that could be a combination of cv::SortFlags
1809
@sa sort, randShuffle
1811
CV_EXPORTS_W void sortIdx(InputArray src, OutputArray dst, int flags);
1813
/** @brief Finds the real roots of a cubic equation.
1815
The function solveCubic finds the real roots of a cubic equation:
1816
- if coeffs is a 4-element vector:
1817
\f[\texttt{coeffs} [0] x^3 + \texttt{coeffs} [1] x^2 + \texttt{coeffs} [2] x + \texttt{coeffs} [3] = 0\f]
1818
- if coeffs is a 3-element vector:
1819
\f[x^3 + \texttt{coeffs} [0] x^2 + \texttt{coeffs} [1] x + \texttt{coeffs} [2] = 0\f]
1821
The roots are stored in the roots array.
1822
@param coeffs equation coefficients, an array of 3 or 4 elements.
1823
@param roots output array of real roots that has 1 or 3 elements.
1825
CV_EXPORTS_W int solveCubic(InputArray coeffs, OutputArray roots);
1827
/** @brief Finds the real or complex roots of a polynomial equation.
1829
The function solvePoly finds real and complex roots of a polynomial equation:
1830
\f[\texttt{coeffs} [n] x^{n} + \texttt{coeffs} [n-1] x^{n-1} + ... + \texttt{coeffs} [1] x + \texttt{coeffs} [0] = 0\f]
1831
@param coeffs array of polynomial coefficients.
1832
@param roots output (complex) array of roots.
1833
@param maxIters maximum number of iterations the algorithm does.
1835
CV_EXPORTS_W double solvePoly(InputArray coeffs, OutputArray roots, int maxIters = 300);
1837
/** @brief Calculates eigenvalues and eigenvectors of a symmetric matrix.
1839
The functions eigen calculate just eigenvalues, or eigenvalues and eigenvectors of the symmetric
1842
src*eigenvectors.row(i).t() = eigenvalues.at<srcType>(i)*eigenvectors.row(i).t()
1844
@note in the new and the old interfaces different ordering of eigenvalues and eigenvectors
1846
@param src input matrix that must have CV_32FC1 or CV_64FC1 type, square size and be symmetrical
1848
@param eigenvalues output vector of eigenvalues of the same type as src; the eigenvalues are stored
1849
in the descending order.
1850
@param eigenvectors output matrix of eigenvectors; it has the same size and type as src; the
1851
eigenvectors are stored as subsequent matrix rows, in the same order as the corresponding
1853
@sa completeSymm , PCA
1855
CV_EXPORTS_W bool eigen(InputArray src, OutputArray eigenvalues,
1856
OutputArray eigenvectors = noArray());
1858
/** @brief Calculates the covariance matrix of a set of vectors.
1860
The functions calcCovarMatrix calculate the covariance matrix and, optionally, the mean vector of
1861
the set of input vectors.
1862
@param samples samples stored as separate matrices
1863
@param nsamples number of samples
1864
@param covar output covariance matrix of the type ctype and square size.
1865
@param mean input or output (depending on the flags) array as the average value of the input vectors.
1866
@param flags operation flags as a combination of cv::CovarFlags
1867
@param ctype type of the matrixl; it equals 'CV_64F' by default.
1868
@sa PCA, mulTransposed, Mahalanobis
1869
@todo InputArrayOfArrays
1871
CV_EXPORTS void calcCovarMatrix( const Mat* samples, int nsamples, Mat& covar, Mat& mean,
1872
int flags, int ctype = CV_64F);
1875
@note use cv::COVAR_ROWS or cv::COVAR_COLS flag
1876
@param samples samples stored as rows/columns of a single matrix.
1877
@param covar output covariance matrix of the type ctype and square size.
1878
@param mean input or output (depending on the flags) array as the average value of the input vectors.
1879
@param flags operation flags as a combination of cv::CovarFlags
1880
@param ctype type of the matrixl; it equals 'CV_64F' by default.
1882
CV_EXPORTS_W void calcCovarMatrix( InputArray samples, OutputArray covar,
1883
InputOutputArray mean, int flags, int ctype = CV_64F);
1885
/** wrap PCA::operator() */
1886
CV_EXPORTS_W void PCACompute(InputArray data, InputOutputArray mean,
1887
OutputArray eigenvectors, int maxComponents = 0);
1889
/** wrap PCA::operator() */
1890
CV_EXPORTS_W void PCACompute(InputArray data, InputOutputArray mean,
1891
OutputArray eigenvectors, double retainedVariance);
1893
/** wrap PCA::project */
1894
CV_EXPORTS_W void PCAProject(InputArray data, InputArray mean,
1895
InputArray eigenvectors, OutputArray result);
1897
/** wrap PCA::backProject */
1898
CV_EXPORTS_W void PCABackProject(InputArray data, InputArray mean,
1899
InputArray eigenvectors, OutputArray result);
1901
/** wrap SVD::compute */
1902
CV_EXPORTS_W void SVDecomp( InputArray src, OutputArray w, OutputArray u, OutputArray vt, int flags = 0 );
1904
/** wrap SVD::backSubst */
1905
CV_EXPORTS_W void SVBackSubst( InputArray w, InputArray u, InputArray vt,
1906
InputArray rhs, OutputArray dst );
1908
/** @brief Calculates the Mahalanobis distance between two vectors.
1910
The function Mahalanobis calculates and returns the weighted distance between two vectors:
1911
\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]
1912
The covariance matrix may be calculated using the cv::calcCovarMatrix function and then inverted using
1913
the invert function (preferably using the cv::DECOMP_SVD method, as the most accurate).
1914
@param v1 first 1D input vector.
1915
@param v2 second 1D input vector.
1916
@param icovar inverse covariance matrix.
1918
CV_EXPORTS_W double Mahalanobis(InputArray v1, InputArray v2, InputArray icovar);
1920
/** @brief Performs a forward or inverse Discrete Fourier transform of a 1D or 2D floating-point array.
1922
The function performs one of the following:
1923
- Forward the Fourier transform of a 1D vector of N elements:
1924
\f[Y = F^{(N)} \cdot X,\f]
1925
where \f$F^{(N)}_{jk}=\exp(-2\pi i j k/N)\f$ and \f$i=\sqrt{-1}\f$
1926
- Inverse the Fourier transform of a 1D vector of N elements:
1927
\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]
1928
where \f$F^*=\left(\textrm{Re}(F^{(N)})-\textrm{Im}(F^{(N)})\right)^T\f$
1929
- Forward the 2D Fourier transform of a M x N matrix:
1930
\f[Y = F^{(M)} \cdot X \cdot F^{(N)}\f]
1931
- Inverse the 2D Fourier transform of a M x N matrix:
1932
\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]
1934
In case of real (single-channel) data, the output spectrum of the forward Fourier transform or input
1935
spectrum of the inverse Fourier transform can be represented in a packed format called *CCS*
1936
(complex-conjugate-symmetrical). It was borrowed from IPL (Intel\* Image Processing Library). Here
1937
is how 2D *CCS* spectrum looks:
1938
\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]
1940
In case of 1D transform of a real vector, the output looks like the first row of the matrix above.
1942
So, the function chooses an operation mode depending on the flags and size of the input array:
1943
- If DFT_ROWS is set or the input array has a single row or single column, the function
1944
performs a 1D forward or inverse transform of each row of a matrix when DFT_ROWS is set.
1945
Otherwise, it performs a 2D transform.
1946
- If the input array is real and DFT_INVERSE is not set, the function performs a forward 1D or
1948
- When DFT_COMPLEX_OUTPUT is set, the output is a complex matrix of the same size as
1950
- When DFT_COMPLEX_OUTPUT is not set, the output is a real matrix of the same size as
1951
input. In case of 2D transform, it uses the packed format as shown above. In case of a
1952
single 1D transform, it looks like the first row of the matrix above. In case of
1953
multiple 1D transforms (when using the DFT_ROWS flag), each row of the output matrix
1954
looks like the first row of the matrix above.
1955
- If the input array is complex and either DFT_INVERSE or DFT_REAL_OUTPUT are not set, the
1956
output is a complex array of the same size as input. The function performs a forward or
1957
inverse 1D or 2D transform of the whole input array or each row of the input array
1958
independently, depending on the flags DFT_INVERSE and DFT_ROWS.
1959
- When DFT_INVERSE is set and the input array is real, or it is complex but DFT_REAL_OUTPUT
1960
is set, the output is a real array of the same size as input. The function performs a 1D or 2D
1961
inverse transformation of the whole input array or each individual row, depending on the flags
1962
DFT_INVERSE and DFT_ROWS.
1964
If DFT_SCALE is set, the scaling is done after the transformation.
1966
Unlike dct , the function supports arrays of arbitrary size. But only those arrays are processed
1967
efficiently, whose sizes can be factorized in a product of small prime numbers (2, 3, and 5 in the
1968
current implementation). Such an efficient DFT size can be calculated using the getOptimalDFTSize
1971
The sample below illustrates how to calculate a DFT-based convolution of two 2D real arrays:
1973
void convolveDFT(InputArray A, InputArray B, OutputArray C)
1975
// reallocate the output array if needed
1976
C.create(abs(A.rows - B.rows)+1, abs(A.cols - B.cols)+1, A.type());
1978
// calculate the size of DFT transform
1979
dftSize.width = getOptimalDFTSize(A.cols + B.cols - 1);
1980
dftSize.height = getOptimalDFTSize(A.rows + B.rows - 1);
1982
// allocate temporary buffers and initialize them with 0's
1983
Mat tempA(dftSize, A.type(), Scalar::all(0));
1984
Mat tempB(dftSize, B.type(), Scalar::all(0));
1986
// copy A and B to the top-left corners of tempA and tempB, respectively
1987
Mat roiA(tempA, Rect(0,0,A.cols,A.rows));
1989
Mat roiB(tempB, Rect(0,0,B.cols,B.rows));
1992
// now transform the padded A & B in-place;
1993
// use "nonzeroRows" hint for faster processing
1994
dft(tempA, tempA, 0, A.rows);
1995
dft(tempB, tempB, 0, B.rows);
1997
// multiply the spectrums;
1998
// the function handles packed spectrum representations well
1999
mulSpectrums(tempA, tempB, tempA);
2001
// transform the product back from the frequency domain.
2002
// Even though all the result rows will be non-zero,
2003
// you need only the first C.rows of them, and thus you
2004
// pass nonzeroRows == C.rows
2005
dft(tempA, tempA, DFT_INVERSE + DFT_SCALE, C.rows);
2007
// now copy the result back to C.
2008
tempA(Rect(0, 0, C.cols, C.rows)).copyTo(C);
2010
// all the temporary buffers will be deallocated automatically
2013
To optimize this sample, consider the following approaches:
2014
- Since nonzeroRows != 0 is passed to the forward transform calls and since A and B are copied to
2015
the top-left corners of tempA and tempB, respectively, it is not necessary to clear the whole
2016
tempA and tempB. It is only necessary to clear the tempA.cols - A.cols ( tempB.cols - B.cols)
2017
rightmost columns of the matrices.
2018
- This DFT-based convolution does not have to be applied to the whole big arrays, especially if B
2019
is significantly smaller than A or vice versa. Instead, you can calculate convolution by parts.
2020
To do this, you need to split the output array C into multiple tiles. For each tile, estimate
2021
which parts of A and B are required to calculate convolution in this tile. If the tiles in C are
2022
too small, the speed will decrease a lot because of repeated work. In the ultimate case, when
2023
each tile in C is a single pixel, the algorithm becomes equivalent to the naive convolution
2024
algorithm. If the tiles are too big, the temporary arrays tempA and tempB become too big and
2025
there is also a slowdown because of bad cache locality. So, there is an optimal tile size
2026
somewhere in the middle.
2027
- If different tiles in C can be calculated in parallel and, thus, the convolution is done by
2028
parts, the loop can be threaded.
2030
All of the above improvements have been implemented in matchTemplate and filter2D . Therefore, by
2031
using them, you can get the performance even better than with the above theoretically optimal
2032
implementation. Though, those two functions actually calculate cross-correlation, not convolution,
2033
so you need to "flip" the second convolution operand B vertically and horizontally using flip .
2035
- An example using the discrete fourier transform can be found at
2036
opencv_source_code/samples/cpp/dft.cpp
2037
- (Python) An example using the dft functionality to perform Wiener deconvolution can be found
2038
at opencv_source/samples/python/deconvolution.py
2039
- (Python) An example rearranging the quadrants of a Fourier image can be found at
2040
opencv_source/samples/python/dft.py
2041
@param src input array that could be real or complex.
2042
@param dst output array whose size and type depends on the flags .
2043
@param flags transformation flags, representing a combination of the cv::DftFlags
2044
@param nonzeroRows when the parameter is not zero, the function assumes that only the first
2045
nonzeroRows rows of the input array (DFT_INVERSE is not set) or only the first nonzeroRows of the
2046
output array (DFT_INVERSE is set) contain non-zeros, thus, the function can handle the rest of the
2047
rows more efficiently and save some time; this technique is very useful for calculating array
2048
cross-correlation or convolution using DFT.
2049
@sa dct , getOptimalDFTSize , mulSpectrums, filter2D , matchTemplate , flip , cartToPolar ,
2052
CV_EXPORTS_W void dft(InputArray src, OutputArray dst, int flags = 0, int nonzeroRows = 0);
2054
/** @brief Calculates the inverse Discrete Fourier Transform of a 1D or 2D array.
2056
idft(src, dst, flags) is equivalent to dft(src, dst, flags | DFT_INVERSE) .
2057
@note None of dft and idft scales the result by default. So, you should pass DFT_SCALE to one of
2058
dft or idft explicitly to make these transforms mutually inverse.
2059
@sa dft, dct, idct, mulSpectrums, getOptimalDFTSize
2060
@param src input floating-point real or complex array.
2061
@param dst output array whose size and type depend on the flags.
2062
@param flags operation flags (see dft and cv::DftFlags).
2063
@param nonzeroRows number of dst rows to process; the rest of the rows have undefined content (see
2064
the convolution sample in dft description.
2066
CV_EXPORTS_W void idft(InputArray src, OutputArray dst, int flags = 0, int nonzeroRows = 0);
2068
/** @brief Performs a forward or inverse discrete Cosine transform of 1D or 2D array.
2070
The function dct performs a forward or inverse discrete Cosine transform (DCT) of a 1D or 2D
2071
floating-point array:
2072
- Forward Cosine transform of a 1D vector of N elements:
2073
\f[Y = C^{(N)} \cdot X\f]
2075
\f[C^{(N)}_{jk}= \sqrt{\alpha_j/N} \cos \left ( \frac{\pi(2k+1)j}{2N} \right )\f]
2077
\f$\alpha_0=1\f$, \f$\alpha_j=2\f$ for *j \> 0*.
2078
- Inverse Cosine transform of a 1D vector of N elements:
2079
\f[X = \left (C^{(N)} \right )^{-1} \cdot Y = \left (C^{(N)} \right )^T \cdot Y\f]
2080
(since \f$C^{(N)}\f$ is an orthogonal matrix, \f$C^{(N)} \cdot \left(C^{(N)}\right)^T = I\f$ )
2081
- Forward 2D Cosine transform of M x N matrix:
2082
\f[Y = C^{(N)} \cdot X \cdot \left (C^{(N)} \right )^T\f]
2083
- Inverse 2D Cosine transform of M x N matrix:
2084
\f[X = \left (C^{(N)} \right )^T \cdot X \cdot C^{(N)}\f]
2086
The function chooses the mode of operation by looking at the flags and size of the input array:
2087
- If (flags & DCT_INVERSE) == 0 , the function does a forward 1D or 2D transform. Otherwise, it
2088
is an inverse 1D or 2D transform.
2089
- If (flags & DCT_ROWS) != 0 , the function performs a 1D transform of each row.
2090
- If the array is a single column or a single row, the function performs a 1D transform.
2091
- If none of the above is true, the function performs a 2D transform.
2093
@note Currently dct supports even-size arrays (2, 4, 6 ...). For data analysis and approximation, you
2094
can pad the array when necessary.
2095
Also, the function performance depends very much, and not monotonically, on the array size (see
2096
getOptimalDFTSize ). In the current implementation DCT of a vector of size N is calculated via DFT
2097
of a vector of size N/2 . Thus, the optimal DCT size N1 \>= N can be calculated as:
2099
size_t getOptimalDCTSize(size_t N) { return 2*getOptimalDFTSize((N+1)/2); }
2100
N1 = getOptimalDCTSize(N);
2102
@param src input floating-point array.
2103
@param dst output array of the same size and type as src .
2104
@param flags transformation flags as a combination of cv::DftFlags (DCT_*)
2105
@sa dft , getOptimalDFTSize , idct
2107
CV_EXPORTS_W void dct(InputArray src, OutputArray dst, int flags = 0);
2109
/** @brief Calculates the inverse Discrete Cosine Transform of a 1D or 2D array.
2111
idct(src, dst, flags) is equivalent to dct(src, dst, flags | DCT_INVERSE).
2112
@param src input floating-point single-channel array.
2113
@param dst output array of the same size and type as src.
2114
@param flags operation flags.
2115
@sa dct, dft, idft, getOptimalDFTSize
2117
CV_EXPORTS_W void idct(InputArray src, OutputArray dst, int flags = 0);
2119
/** @brief Performs the per-element multiplication of two Fourier spectrums.
2121
The function mulSpectrums performs the per-element multiplication of the two CCS-packed or complex
2122
matrices that are results of a real or complex Fourier transform.
2124
The function, together with dft and idft , may be used to calculate convolution (pass conjB=false )
2125
or correlation (pass conjB=true ) of two arrays rapidly. When the arrays are complex, they are
2126
simply multiplied (per element) with an optional conjugation of the second-array elements. When the
2127
arrays are real, they are assumed to be CCS-packed (see dft for details).
2128
@param a first input array.
2129
@param b second input array of the same size and type as src1 .
2130
@param c output array of the same size and type as src1 .
2131
@param flags operation flags; currently, the only supported flag is cv::DFT_ROWS, which indicates that
2132
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.
2133
@param conjB optional flag that conjugates the second input array before the multiplication (true)
2136
CV_EXPORTS_W void mulSpectrums(InputArray a, InputArray b, OutputArray c,
2137
int flags, bool conjB = false);
2139
/** @brief Returns the optimal DFT size for a given vector size.
2141
DFT performance is not a monotonic function of a vector size. Therefore, when you calculate
2142
convolution of two arrays or perform the spectral analysis of an array, it usually makes sense to
2143
pad the input data with zeros to get a bit larger array that can be transformed much faster than the
2144
original one. Arrays whose size is a power-of-two (2, 4, 8, 16, 32, ...) are the fastest to process.
2145
Though, the arrays whose size is a product of 2's, 3's, and 5's (for example, 300 = 5\*5\*3\*2\*2)
2146
are also processed quite efficiently.
2148
The function getOptimalDFTSize returns the minimum number N that is greater than or equal to vecsize
2149
so that the DFT of a vector of size N can be processed efficiently. In the current implementation N
2150
= 2 ^p^ \* 3 ^q^ \* 5 ^r^ for some integer p, q, r.
2152
The function returns a negative number if vecsize is too large (very close to INT_MAX ).
2154
While the function cannot be used directly to estimate the optimal vector size for DCT transform
2155
(since the current DCT implementation supports only even-size vectors), it can be easily processed
2156
as getOptimalDFTSize((vecsize+1)/2)\*2.
2157
@param vecsize vector size.
2158
@sa dft , dct , idft , idct , mulSpectrums
2160
CV_EXPORTS_W int getOptimalDFTSize(int vecsize);
2162
/** @brief Returns the default random number generator.
2164
The function theRNG returns the default random number generator. For each thread, there is a
2165
separate random number generator, so you can use the function safely in multi-thread environments.
2166
If you just need to get a single random number using this generator or initialize an array, you can
2167
use randu or randn instead. But if you are going to generate many random numbers inside a loop, it
2168
is much faster to use this function to retrieve the generator and then use RNG::operator _Tp() .
2169
@sa RNG, randu, randn
2171
CV_EXPORTS RNG& theRNG();
2173
/** @brief Generates a single uniformly-distributed random number or an array of random numbers.
2175
Non-template variant of the function fills the matrix dst with uniformly-distributed
2176
random numbers from the specified range:
2177
\f[\texttt{low} _c \leq \texttt{dst} (I)_c < \texttt{high} _c\f]
2178
@param dst output array of random numbers; the array must be pre-allocated.
2179
@param low inclusive lower boundary of the generated random numbers.
2180
@param high exclusive upper boundary of the generated random numbers.
2181
@sa RNG, randn, theRNG
2183
CV_EXPORTS_W void randu(InputOutputArray dst, InputArray low, InputArray high);
2185
/** @brief Fills the array with normally distributed random numbers.
2187
The function randn fills the matrix dst with normally distributed random numbers with the specified
2188
mean vector and the standard deviation matrix. The generated random numbers are clipped to fit the
2189
value range of the output array data type.
2190
@param dst output array of random numbers; the array must be pre-allocated and have 1 to 4 channels.
2191
@param mean mean value (expectation) of the generated random numbers.
2192
@param stddev standard deviation of the generated random numbers; it can be either a vector (in
2193
which case a diagonal standard deviation matrix is assumed) or a square matrix.
2196
CV_EXPORTS_W void randn(InputOutputArray dst, InputArray mean, InputArray stddev);
2198
/** @brief Shuffles the array elements randomly.
2200
The function randShuffle shuffles the specified 1D array by randomly choosing pairs of elements and
2201
swapping them. The number of such swap operations will be dst.rows\*dst.cols\*iterFactor .
2202
@param dst input/output numerical 1D array.
2203
@param iterFactor scale factor that determines the number of random swap operations (see the details
2205
@param rng optional random number generator used for shuffling; if it is zero, theRNG () is used
2209
CV_EXPORTS_W void randShuffle(InputOutputArray dst, double iterFactor = 1., RNG* rng = 0);
2211
/** @brief Principal Component Analysis
2213
The class is used to calculate a special basis for a set of vectors. The
2214
basis will consist of eigenvectors of the covariance matrix calculated
2215
from the input set of vectors. The class %PCA can also transform
2216
vectors to/from the new coordinate space defined by the basis. Usually,
2217
in this new coordinate system, each vector from the original set (and
2218
any linear combination of such vectors) can be quite accurately
2219
approximated by taking its first few components, corresponding to the
2220
eigenvectors of the largest eigenvalues of the covariance matrix.
2221
Geometrically it means that you calculate a projection of the vector to
2222
a subspace formed by a few eigenvectors corresponding to the dominant
2223
eigenvalues of the covariance matrix. And usually such a projection is
2224
very close to the original vector. So, you can represent the original
2225
vector from a high-dimensional space with a much shorter vector
2226
consisting of the projected vector's coordinates in the subspace. Such a
2227
transformation is also known as Karhunen-Loeve Transform, or KLT.
2228
See http://en.wikipedia.org/wiki/Principal_component_analysis
2230
The sample below is the function that takes two matrices. The first
2231
function stores a set of vectors (a row per vector) that is used to
2232
calculate PCA. The second function stores another "test" set of vectors
2233
(a row per vector). First, these vectors are compressed with PCA, then
2234
reconstructed back, and then the reconstruction error norm is computed
2235
and printed for each vector. :
2240
PCA compressPCA(const Mat& pcaset, int maxComponents,
2241
const Mat& testset, Mat& compressed)
2243
PCA pca(pcaset, // pass the data
2244
Mat(), // we do not have a pre-computed mean vector,
2245
// so let the PCA engine to compute it
2246
PCA::DATA_AS_ROW, // indicate that the vectors
2247
// are stored as matrix rows
2248
// (use PCA::DATA_AS_COL if the vectors are
2249
// the matrix columns)
2250
maxComponents // specify, how many principal components to retain
2252
// if there is no test data, just return the computed basis, ready-to-use
2255
CV_Assert( testset.cols == pcaset.cols );
2257
compressed.create(testset.rows, maxComponents, testset.type());
2260
for( int i = 0; i < testset.rows; i++ )
2262
Mat vec = testset.row(i), coeffs = compressed.row(i), reconstructed;
2263
// compress the vector, the result will be stored
2264
// in the i-th row of the output matrix
2265
pca.project(vec, coeffs);
2266
// and then reconstruct it
2267
pca.backProject(coeffs, reconstructed);
2268
// and measure the error
2269
printf("%d. diff = %g\n", i, norm(vec, reconstructed, NORM_L2));
2274
@sa calcCovarMatrix, mulTransposed, SVD, dft, dct
2276
class CV_EXPORTS PCA
2279
enum Flags { DATA_AS_ROW = 0, //!< indicates that the input samples are stored as matrix rows
2280
DATA_AS_COL = 1, //!< indicates that the input samples are stored as matrix columns
2284
/** @brief default constructor
2286
The default constructor initializes an empty %PCA structure. The other
2287
constructors initialize the structure and call PCA::operator()().
2292
@param data input samples stored as matrix rows or matrix columns.
2293
@param mean optional mean value; if the matrix is empty (@c noArray()),
2294
the mean is computed from the data.
2295
@param flags operation flags; currently the parameter is only used to
2296
specify the data layout (PCA::Flags)
2297
@param maxComponents maximum number of components that %PCA should
2298
retain; by default, all the components are retained.
2300
PCA(InputArray data, InputArray mean, int flags, int maxComponents = 0);
2303
@param data input samples stored as matrix rows or matrix columns.
2304
@param mean optional mean value; if the matrix is empty (noArray()),
2305
the mean is computed from the data.
2306
@param flags operation flags; currently the parameter is only used to
2307
specify the data layout (PCA::Flags)
2308
@param retainedVariance Percentage of variance that PCA should retain.
2309
Using this parameter will let the PCA decided how many components to
2310
retain but it will always keep at least 2.
2312
PCA(InputArray data, InputArray mean, int flags, double retainedVariance);
2314
/** @brief performs %PCA
2316
The operator performs %PCA of the supplied dataset. It is safe to reuse
2317
the same PCA structure for multiple datasets. That is, if the structure
2318
has been previously used with another dataset, the existing internal
2319
data is reclaimed and the new eigenvalues, @ref eigenvectors , and @ref
2320
mean are allocated and computed.
2322
The computed eigenvalues are sorted from the largest to the smallest and
2323
the corresponding eigenvectors are stored as eigenvectors rows.
2325
@param data input samples stored as the matrix rows or as the matrix
2327
@param mean optional mean value; if the matrix is empty (noArray()),
2328
the mean is computed from the data.
2329
@param flags operation flags; currently the parameter is only used to
2330
specify the data layout. (Flags)
2331
@param maxComponents maximum number of components that PCA should
2332
retain; by default, all the components are retained.
2334
PCA& operator()(InputArray data, InputArray mean, int flags, int maxComponents = 0);
2337
@param data input samples stored as the matrix rows or as the matrix
2339
@param mean optional mean value; if the matrix is empty (noArray()),
2340
the mean is computed from the data.
2341
@param flags operation flags; currently the parameter is only used to
2342
specify the data layout. (PCA::Flags)
2343
@param retainedVariance Percentage of variance that %PCA should retain.
2344
Using this parameter will let the %PCA decided how many components to
2345
retain but it will always keep at least 2.
2347
PCA& operator()(InputArray data, InputArray mean, int flags, double retainedVariance);
2349
/** @brief Projects vector(s) to the principal component subspace.
2351
The methods project one or more vectors to the principal component
2352
subspace, where each vector projection is represented by coefficients in
2353
the principal component basis. The first form of the method returns the
2354
matrix that the second form writes to the result. So the first form can
2355
be used as a part of expression while the second form can be more
2356
efficient in a processing loop.
2357
@param vec input vector(s); must have the same dimensionality and the
2358
same layout as the input data used at %PCA phase, that is, if
2359
DATA_AS_ROW are specified, then `vec.cols==data.cols`
2360
(vector dimensionality) and `vec.rows` is the number of vectors to
2361
project, and the same is true for the PCA::DATA_AS_COL case.
2363
Mat project(InputArray vec) const;
2366
@param vec input vector(s); must have the same dimensionality and the
2367
same layout as the input data used at PCA phase, that is, if
2368
DATA_AS_ROW are specified, then `vec.cols==data.cols`
2369
(vector dimensionality) and `vec.rows` is the number of vectors to
2370
project, and the same is true for the PCA::DATA_AS_COL case.
2371
@param result output vectors; in case of PCA::DATA_AS_COL, the
2372
output matrix has as many columns as the number of input vectors, this
2373
means that `result.cols==vec.cols` and the number of rows match the
2374
number of principal components (for example, `maxComponents` parameter
2375
passed to the constructor).
2377
void project(InputArray vec, OutputArray result) const;
2379
/** @brief Reconstructs vectors from their PC projections.
2381
The methods are inverse operations to PCA::project. They take PC
2382
coordinates of projected vectors and reconstruct the original vectors.
2383
Unless all the principal components have been retained, the
2384
reconstructed vectors are different from the originals. But typically,
2385
the difference is small if the number of components is large enough (but
2386
still much smaller than the original vector dimensionality). As a
2387
result, PCA is used.
2388
@param vec coordinates of the vectors in the principal component
2389
subspace, the layout and size are the same as of PCA::project output
2392
Mat backProject(InputArray vec) const;
2395
@param vec coordinates of the vectors in the principal component
2396
subspace, the layout and size are the same as of PCA::project output
2398
@param result reconstructed vectors; the layout and size are the same as
2399
of PCA::project input vectors.
2401
void backProject(InputArray vec, OutputArray result) const;
2403
/** @brief write and load PCA matrix
2406
void write(FileStorage& fs ) const;
2407
void read(const FileNode& fs);
2409
Mat eigenvectors; //!< eigenvectors of the covariation matrix
2410
Mat eigenvalues; //!< eigenvalues of the covariation matrix
2411
Mat mean; //!< mean value subtracted before the projection and added after the back projection
2414
/** @example pca.cpp
2415
An example using %PCA for dimensionality reduction while maintaining an amount of variance
2419
@brief Linear Discriminant Analysis
2420
@todo document this class
2422
class CV_EXPORTS LDA
2425
/** @brief constructor
2426
Initializes a LDA with num_components (default 0).
2428
explicit LDA(int num_components = 0);
2430
/** Initializes and performs a Discriminant Analysis with Fisher's
2431
Optimization Criterion on given data in src and corresponding labels
2432
in labels. If 0 (or less) number of components are given, they are
2433
automatically determined for given data in computation.
2435
LDA(InputArrayOfArrays src, InputArray labels, int num_components = 0);
2437
/** Serializes this object to a given filename.
2439
void save(const String& filename) const;
2441
/** Deserializes this object from a given filename.
2443
void load(const String& filename);
2445
/** Serializes this object to a given cv::FileStorage.
2447
void save(FileStorage& fs) const;
2449
/** Deserializes this object from a given cv::FileStorage.
2451
void load(const FileStorage& node);
2457
/** Compute the discriminants for data in src (row aligned) and labels.
2459
void compute(InputArrayOfArrays src, InputArray labels);
2461
/** Projects samples into the LDA subspace.
2462
src may be one or more row aligned samples.
2464
Mat project(InputArray src);
2466
/** Reconstructs projections from the LDA subspace.
2467
src may be one or more row aligned projections.
2469
Mat reconstruct(InputArray src);
2471
/** Returns the eigenvectors of this LDA.
2473
Mat eigenvectors() const { return _eigenvectors; }
2475
/** Returns the eigenvalues of this LDA.
2477
Mat eigenvalues() const { return _eigenvalues; }
2479
static Mat subspaceProject(InputArray W, InputArray mean, InputArray src);
2480
static Mat subspaceReconstruct(InputArray W, InputArray mean, InputArray src);
2483
bool _dataAsRow; // unused, but needed for 3.0 ABI compatibility.
2484
int _num_components;
2487
void lda(InputArrayOfArrays src, InputArray labels);
2490
/** @brief Singular Value Decomposition
2492
Class for computing Singular Value Decomposition of a floating-point
2493
matrix. The Singular Value Decomposition is used to solve least-square
2494
problems, under-determined linear systems, invert matrices, compute
2495
condition numbers, and so on.
2497
If you want to compute a condition number of a matrix or an absolute value of
2498
its determinant, you do not need `u` and `vt`. You can pass
2499
flags=SVD::NO_UV|... . Another flag SVD::FULL_UV indicates that full-size u
2500
and vt must be computed, which is not necessary most of the time.
2502
@sa invert, solve, eigen, determinant
2504
class CV_EXPORTS SVD
2508
/** allow the algorithm to modify the decomposed matrix; it can save space and speed up
2509
processing. currently ignored. */
2511
/** indicates that only a vector of singular values `w` is to be processed, while u and vt
2512
will be set to empty matrices */
2514
/** when the matrix is not square, by default the algorithm produces u and vt matrices of
2515
sufficiently large size for the further A reconstruction; if, however, FULL_UV flag is
2516
specified, u and vt will be full-size square orthogonal matrices.*/
2520
/** @brief the default constructor
2522
initializes an empty SVD structure
2527
initializes an empty SVD structure and then calls SVD::operator()
2528
@param src decomposed matrix.
2529
@param flags operation flags (SVD::Flags)
2531
SVD( InputArray src, int flags = 0 );
2533
/** @brief the operator that performs SVD. The previously allocated u, w and vt are released.
2535
The operator performs the singular value decomposition of the supplied
2536
matrix. The u,`vt` , and the vector of singular values w are stored in
2537
the structure. The same SVD structure can be reused many times with
2538
different matrices. Each time, if needed, the previous u,`vt` , and w
2539
are reclaimed and the new matrices are created, which is all handled by
2541
@param src decomposed matrix.
2542
@param flags operation flags (SVD::Flags)
2544
SVD& operator ()( InputArray src, int flags = 0 );
2546
/** @brief decomposes matrix and stores the results to user-provided matrices
2548
The methods/functions perform SVD of matrix. Unlike SVD::SVD constructor
2549
and SVD::operator(), they store the results to the user-provided
2554
SVD::compute(A, w, u, vt);
2557
@param src decomposed matrix
2558
@param w calculated singular values
2559
@param u calculated left singular vectors
2560
@param vt transposed matrix of right singular values
2561
@param flags operation flags - see SVD::SVD.
2563
static void compute( InputArray src, OutputArray w,
2564
OutputArray u, OutputArray vt, int flags = 0 );
2567
computes singular values of a matrix
2568
@param src decomposed matrix
2569
@param w calculated singular values
2570
@param flags operation flags - see SVD::Flags.
2572
static void compute( InputArray src, OutputArray w, int flags = 0 );
2574
/** @brief performs back substitution
2576
static void backSubst( InputArray w, InputArray u,
2577
InputArray vt, InputArray rhs,
2580
/** @brief solves an under-determined singular linear system
2582
The method finds a unit-length solution x of a singular linear system
2583
A\*x = 0. Depending on the rank of A, there can be no solutions, a
2584
single solution or an infinite number of solutions. In general, the
2585
algorithm solves the following problem:
2586
\f[dst = \arg \min _{x: \| x \| =1} \| src \cdot x \|\f]
2587
@param src left-hand-side matrix.
2588
@param dst found solution.
2590
static void solveZ( InputArray src, OutputArray dst );
2592
/** @brief performs a singular value back substitution.
2594
The method calculates a back substitution for the specified right-hand
2597
\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]
2599
Using this technique you can either get a very accurate solution of the
2600
convenient linear system, or the best (in the least-squares terms)
2601
pseudo-solution of an overdetermined linear system.
2603
@param rhs right-hand side of a linear system (u\*w\*v')\*dst = rhs to
2604
be solved, where A has been previously decomposed.
2606
@param dst found solution of the system.
2608
@note Explicit SVD with the further back substitution only makes sense
2609
if you need to solve many linear systems with the same left-hand side
2610
(for example, src ). If all you need is to solve a single system
2611
(possibly with multiple rhs immediately available), simply call solve
2612
add pass DECOMP_SVD there. It does absolutely the same thing.
2614
void backSubst( InputArray rhs, OutputArray dst ) const;
2616
/** @todo document */
2617
template<typename _Tp, int m, int n, int nm> static
2618
void compute( const Matx<_Tp, m, n>& a, Matx<_Tp, nm, 1>& w, Matx<_Tp, m, nm>& u, Matx<_Tp, n, nm>& vt );
2620
/** @todo document */
2621
template<typename _Tp, int m, int n, int nm> static
2622
void compute( const Matx<_Tp, m, n>& a, Matx<_Tp, nm, 1>& w );
2624
/** @todo document */
2625
template<typename _Tp, int m, int n, int nm, int nb> static
2626
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 );
2631
/** @brief Random Number Generator
2633
Random number generator. It encapsulates the state (currently, a 64-bit
2634
integer) and has methods to return scalar random values and to fill
2635
arrays with random values. Currently it supports uniform and Gaussian
2636
(normal) distributions. The generator uses Multiply-With-Carry
2637
algorithm, introduced by G. Marsaglia (
2638
<http://en.wikipedia.org/wiki/Multiply-with-carry> ).
2639
Gaussian-distribution random numbers are generated using the Ziggurat
2640
algorithm ( <http://en.wikipedia.org/wiki/Ziggurat_algorithm> ),
2641
introduced by G. Marsaglia and W. W. Tsang.
2643
class CV_EXPORTS RNG
2650
/** @brief constructor
2652
These are the RNG constructors. The first form sets the state to some
2653
pre-defined value, equal to 2\*\*32-1 in the current implementation. The
2654
second form sets the state to the specified value. If you passed state=0
2655
, the constructor uses the above default value instead to avoid the
2656
singular random number sequence, consisting of all zeros.
2660
@param state 64-bit value used to initialize the RNG.
2663
/**The method updates the state using the MWC algorithm and returns the
2664
next 32-bit random number.*/
2667
/**Each of the methods updates the state using the MWC algorithm and
2668
returns the next random number of the specified type. In case of integer
2669
types, the returned number is from the available value range for the
2670
specified type. In case of floating-point types, the returned value is
2681
operator unsigned();
2689
/** @brief returns a random integer sampled uniformly from [0, N).
2691
The methods transform the state using the MWC algorithm and return the
2692
next random number. The first form is equivalent to RNG::next . The
2693
second form returns the random number modulo N , which means that the
2694
result is in the range [0, N) .
2696
unsigned operator ()();
2698
@param N upper non-inclusive boundary of the returned random number.
2700
unsigned operator ()(unsigned N);
2702
/** @brief returns uniformly distributed integer random number from [a,b) range
2704
The methods transform the state using the MWC algorithm and return the
2705
next uniformly-distributed random number of the specified type, deduced
2706
from the input parameter type, from the range [a, b) . There is a nuance
2707
illustrated by the following sample:
2712
// always produces 0
2713
double a = rng.uniform(0, 1);
2715
// produces double from [0, 1)
2716
double a1 = rng.uniform((double)0, (double)1);
2718
// produces float from [0, 1)
2719
double b = rng.uniform(0.f, 1.f);
2721
// produces double from [0, 1)
2722
double c = rng.uniform(0., 1.);
2724
// may cause compiler error because of ambiguity:
2725
// RNG::uniform(0, (int)0.999999)? or RNG::uniform((double)0, 0.99999)?
2726
double d = rng.uniform(0, 0.999999);
2729
The compiler does not take into account the type of the variable to
2730
which you assign the result of RNG::uniform . The only thing that
2731
matters to the compiler is the type of a and b parameters. So, if you
2732
want a floating-point random number, but the range boundaries are
2733
integer numbers, either put dots in the end, if they are constants, or
2734
use explicit type cast operators, as in the a1 initialization above.
2735
@param a lower inclusive boundary of the returned random numbers.
2736
@param b upper non-inclusive boundary of the returned random numbers.
2738
int uniform(int a, int b);
2740
float uniform(float a, float b);
2742
double uniform(double a, double b);
2744
/** @brief Fills arrays with random numbers.
2746
@param mat 2D or N-dimensional matrix; currently matrices with more than
2747
4 channels are not supported by the methods, use Mat::reshape as a
2748
possible workaround.
2749
@param distType distribution type, RNG::UNIFORM or RNG::NORMAL.
2750
@param a first distribution parameter; in case of the uniform
2751
distribution, this is an inclusive lower boundary, in case of the normal
2752
distribution, this is a mean value.
2753
@param b second distribution parameter; in case of the uniform
2754
distribution, this is a non-inclusive upper boundary, in case of the
2755
normal distribution, this is a standard deviation (diagonal of the
2756
standard deviation matrix or the full standard deviation matrix).
2757
@param saturateRange pre-saturation flag; for uniform distribution only;
2758
if true, the method will first convert a and b to the acceptable value
2759
range (according to the mat datatype) and then will generate uniformly
2760
distributed random numbers within the range [saturate(a), saturate(b)),
2761
if saturateRange=false, the method will generate uniformly distributed
2762
random numbers in the original range [a, b) and then will saturate them,
2763
it means, for example, that
2764
<tt>theRNG().fill(mat_8u, RNG::UNIFORM, -DBL_MAX, DBL_MAX)</tt> will likely
2765
produce array mostly filled with 0's and 255's, since the range (0, 255)
2766
is significantly smaller than [-DBL_MAX, DBL_MAX).
2768
Each of the methods fills the matrix with the random values from the
2769
specified distribution. As the new numbers are generated, the RNG state
2770
is updated accordingly. In case of multiple-channel images, every
2771
channel is filled independently, which means that RNG cannot generate
2772
samples from the multi-dimensional Gaussian distribution with
2773
non-diagonal covariance matrix directly. To do that, the method
2774
generates samples from multi-dimensional standard Gaussian distribution
2775
with zero mean and identity covariation matrix, and then transforms them
2776
using transform to get samples from the specified Gaussian distribution.
2778
void fill( InputOutputArray mat, int distType, InputArray a, InputArray b, bool saturateRange = false );
2780
/** @brief Returns the next random number sampled from the Gaussian distribution
2781
@param sigma standard deviation of the distribution.
2783
The method transforms the state using the MWC algorithm and returns the
2784
next random number from the Gaussian distribution N(0,sigma) . That is,
2785
the mean value of the returned random numbers is zero and the standard
2786
deviation is the specified sigma .
2788
double gaussian(double sigma);
2793
/** @brief Mersenne Twister random number generator
2795
Inspired by http://www.math.sci.hiroshima-u.ac.jp/~m-mat/MT/MT2002/CODES/mt19937ar.c
2798
class CV_EXPORTS RNG_MT19937
2802
RNG_MT19937(unsigned s);
2803
void seed(unsigned s);
2808
operator unsigned();
2812
unsigned operator ()(unsigned N);
2813
unsigned operator ()();
2815
/** @brief returns uniformly distributed integer random number from [a,b) range
2818
int uniform(int a, int b);
2819
/** @brief returns uniformly distributed floating-point random number from [a,b) range
2822
float uniform(float a, float b);
2823
/** @brief returns uniformly distributed double-precision floating-point random number from [a,b) range
2826
double uniform(double a, double b);
2829
enum PeriodParameters {N = 624, M = 397};
2836
//! @addtogroup core_cluster
2839
/** @example kmeans.cpp
2840
An example on K-means clustering
2843
/** @brief Finds centers of clusters and groups input samples around the clusters.
2845
The function kmeans implements a k-means algorithm that finds the centers of cluster_count clusters
2846
and groups the input samples around the clusters. As an output, \f$\texttt{labels}_i\f$ contains a
2847
0-based cluster index for the sample stored in the \f$i^{th}\f$ row of the samples matrix.
2850
- (Python) An example on K-means clustering can be found at
2851
opencv_source_code/samples/python/kmeans.py
2852
@param data Data for clustering. An array of N-Dimensional points with float coordinates is needed.
2853
Examples of this array can be:
2854
- Mat points(count, 2, CV_32F);
2855
- Mat points(count, 1, CV_32FC2);
2856
- Mat points(1, count, CV_32FC2);
2857
- std::vector\<cv::Point2f\> points(sampleCount);
2858
@param K Number of clusters to split the set by.
2859
@param bestLabels Input/output integer array that stores the cluster indices for every sample.
2860
@param criteria The algorithm termination criteria, that is, the maximum number of iterations and/or
2861
the desired accuracy. The accuracy is specified as criteria.epsilon. As soon as each of the cluster
2862
centers moves by less than criteria.epsilon on some iteration, the algorithm stops.
2863
@param attempts Flag to specify the number of times the algorithm is executed using different
2864
initial labellings. The algorithm returns the labels that yield the best compactness (see the last
2865
function parameter).
2866
@param flags Flag that can take values of cv::KmeansFlags
2867
@param centers Output matrix of the cluster centers, one row per each cluster center.
2868
@return The function returns the compactness measure that is computed as
2869
\f[\sum _i \| \texttt{samples} _i - \texttt{centers} _{ \texttt{labels} _i} \| ^2\f]
2870
after every attempt. The best (minimum) value is chosen and the corresponding labels and the
2871
compactness value are returned by the function. Basically, you can use only the core of the
2872
function, set the number of attempts to 1, initialize labels each time using a custom algorithm,
2873
pass them with the ( flags = KMEANS_USE_INITIAL_LABELS ) flag, and then choose the best
2874
(most-compact) clustering.
2876
CV_EXPORTS_W double kmeans( InputArray data, int K, InputOutputArray bestLabels,
2877
TermCriteria criteria, int attempts,
2878
int flags, OutputArray centers = noArray() );
2882
//! @addtogroup core_basic
2885
/////////////////////////////// Formatted output of cv::Mat ///////////////////////////
2887
/** @todo document */
2888
class CV_EXPORTS Formatted
2891
virtual const char* next() = 0;
2892
virtual void reset() = 0;
2893
virtual ~Formatted();
2896
/** @todo document */
2897
class CV_EXPORTS Formatter
2900
enum { FMT_DEFAULT = 0,
2908
virtual ~Formatter();
2910
virtual Ptr<Formatted> format(const Mat& mtx) const = 0;
2912
virtual void set32fPrecision(int p = 8) = 0;
2913
virtual void set64fPrecision(int p = 16) = 0;
2914
virtual void setMultiline(bool ml = true) = 0;
2916
static Ptr<Formatter> get(int fmt = FMT_DEFAULT);
2921
String& operator << (String& out, Ptr<Formatted> fmtd)
2924
for(const char* str = fmtd->next(); str; str = fmtd->next())
2925
out += cv::String(str);
2930
String& operator << (String& out, const Mat& mtx)
2932
return out << Formatter::get()->format(mtx);
2935
//////////////////////////////////////// Algorithm ////////////////////////////////////
2937
class CV_EXPORTS Algorithm;
2939
template<typename _Tp> struct ParamType {};
2942
/** @brief This is a base class for all more or less complex algorithms in OpenCV
2944
especially for classes of algorithms, for which there can be multiple implementations. The examples
2945
are stereo correspondence (for which there are algorithms like block matching, semi-global block
2946
matching, graph-cut etc.), background subtraction (which can be done using mixture-of-gaussians
2947
models, codebook-based algorithm etc.), optical flow (block matching, Lucas-Kanade, Horn-Schunck
2950
Here is example of SIFT use in your application via Algorithm interface:
2952
#include "opencv2/opencv.hpp"
2953
#include "opencv2/xfeatures2d.hpp"
2954
using namespace cv::xfeatures2d;
2956
Ptr<Feature2D> sift = SIFT::create();
2957
FileStorage fs("sift_params.xml", FileStorage::READ);
2958
if( fs.isOpened() ) // if we have file with parameters, read them
2960
sift->read(fs["sift_params"]);
2963
else // else modify the parameters and store them; user can later edit the file to use different parameters
2965
sift->setContrastThreshold(0.01f); // lower the contrast threshold, compared to the default value
2967
WriteStructContext ws(fs, "sift_params", CV_NODE_MAP);
2971
Mat image = imread("myimage.png", 0), descriptors;
2972
vector<KeyPoint> keypoints;
2973
sift->detectAndCompute(image, noArray(), keypoints, descriptors);
2976
class CV_EXPORTS_W Algorithm
2980
virtual ~Algorithm();
2982
/** @brief Clears the algorithm state
2984
CV_WRAP virtual void clear() {}
2986
/** @brief Stores algorithm parameters in a file storage
2988
virtual void write(FileStorage& fs) const { (void)fs; }
2990
/** @brief Reads algorithm parameters from a file storage
2992
virtual void read(const FileNode& fn) { (void)fn; }
2994
/** @brief Returns true if the Algorithm is empty (e.g. in the very beginning or after unsuccessful read
2996
virtual bool empty() const { return false; }
2998
/** @brief Reads algorithm from the file node
3000
This is static template method of Algorithm. It's usage is following (in the case of SVM):
3002
Ptr<SVM> svm = Algorithm::read<SVM>(fn);
3004
In order to make this method work, the derived class must overwrite Algorithm::read(const
3005
FileNode& fn) and also have static create() method without parameters
3006
(or with all the optional parameters)
3008
template<typename _Tp> static Ptr<_Tp> read(const FileNode& fn)
3010
Ptr<_Tp> obj = _Tp::create();
3012
return !obj->empty() ? obj : Ptr<_Tp>();
3015
/** @brief Loads algorithm from the file
3017
@param filename Name of the file to read.
3018
@param objname The optional name of the node to read (if empty, the first top-level node will be used)
3020
This is static template method of Algorithm. It's usage is following (in the case of SVM):
3022
Ptr<SVM> svm = Algorithm::load<SVM>("my_svm_model.xml");
3024
In order to make this method work, the derived class must overwrite Algorithm::read(const
3027
template<typename _Tp> static Ptr<_Tp> load(const String& filename, const String& objname=String())
3029
FileStorage fs(filename, FileStorage::READ);
3030
FileNode fn = objname.empty() ? fs.getFirstTopLevelNode() : fs[objname];
3031
Ptr<_Tp> obj = _Tp::create();
3033
return !obj->empty() ? obj : Ptr<_Tp>();
3036
/** @brief Loads algorithm from a String
3038
@param strModel The string variable containing the model you want to load.
3039
@param objname The optional name of the node to read (if empty, the first top-level node will be used)
3041
This is static template method of Algorithm. It's usage is following (in the case of SVM):
3043
Ptr<SVM> svm = Algorithm::loadFromString<SVM>(myStringModel);
3046
template<typename _Tp> static Ptr<_Tp> loadFromString(const String& strModel, const String& objname=String())
3048
FileStorage fs(strModel, FileStorage::READ + FileStorage::MEMORY);
3049
FileNode fn = objname.empty() ? fs.getFirstTopLevelNode() : fs[objname];
3050
Ptr<_Tp> obj = _Tp::create();
3052
return !obj->empty() ? obj : Ptr<_Tp>();
3055
/** Saves the algorithm to a file.
3056
In order to make this method work, the derived class must implement Algorithm::write(FileStorage& fs). */
3057
CV_WRAP virtual void save(const String& filename) const;
3059
/** Returns the algorithm string identifier.
3060
This string is used as top level xml/yml node tag when the object is saved to a file or string. */
3061
CV_WRAP virtual String getDefaultName() const;
3065
enum { INT=0, BOOLEAN=1, REAL=2, STRING=3, MAT=4, MAT_VECTOR=5, ALGORITHM=6, FLOAT=7,
3066
UNSIGNED_INT=8, UINT64=9, UCHAR=11 };
3071
template<> struct ParamType<bool>
3073
typedef bool const_param_type;
3074
typedef bool member_type;
3076
enum { type = Param::BOOLEAN };
3079
template<> struct ParamType<int>
3081
typedef int const_param_type;
3082
typedef int member_type;
3084
enum { type = Param::INT };
3087
template<> struct ParamType<double>
3089
typedef double const_param_type;
3090
typedef double member_type;
3092
enum { type = Param::REAL };
3095
template<> struct ParamType<String>
3097
typedef const String& const_param_type;
3098
typedef String member_type;
3100
enum { type = Param::STRING };
3103
template<> struct ParamType<Mat>
3105
typedef const Mat& const_param_type;
3106
typedef Mat member_type;
3108
enum { type = Param::MAT };
3111
template<> struct ParamType<std::vector<Mat> >
3113
typedef const std::vector<Mat>& const_param_type;
3114
typedef std::vector<Mat> member_type;
3116
enum { type = Param::MAT_VECTOR };
3119
template<> struct ParamType<Algorithm>
3121
typedef const Ptr<Algorithm>& const_param_type;
3122
typedef Ptr<Algorithm> member_type;
3124
enum { type = Param::ALGORITHM };
3127
template<> struct ParamType<float>
3129
typedef float const_param_type;
3130
typedef float member_type;
3132
enum { type = Param::FLOAT };
3135
template<> struct ParamType<unsigned>
3137
typedef unsigned const_param_type;
3138
typedef unsigned member_type;
3140
enum { type = Param::UNSIGNED_INT };
3143
template<> struct ParamType<uint64>
3145
typedef uint64 const_param_type;
3146
typedef uint64 member_type;
3148
enum { type = Param::UINT64 };
3151
template<> struct ParamType<uchar>
3153
typedef uchar const_param_type;
3154
typedef uchar member_type;
3156
enum { type = Param::UCHAR };
3163
#include "opencv2/core/operations.hpp"
3164
#include "opencv2/core/cvstd.inl.hpp"
3165
#include "opencv2/core/utility.hpp"
3166
#include "opencv2/core/optim.hpp"
3168
#endif /*__OPENCV_CORE_HPP__*/
added
removed
sw/ext/opencv_bebop/opencv/modules/core/include/opencv2/core.hpp
