OpenCV 2.4.8 components for OpenCVgrabber.
[mmanager-3rdparty.git] / OpenCV2.4.8 / build / include / opencv2 / core / core.hpp
1 /*! \file core.hpp
2     \brief The Core Functionality
3  */
4 /*M///////////////////////////////////////////////////////////////////////////////////////
5 //
6 //  IMPORTANT: READ BEFORE DOWNLOADING, COPYING, INSTALLING OR USING.
7 //
8 //  By downloading, copying, installing or using the software you agree to this license.
9 //  If you do not agree to this license, do not download, install,
10 //  copy or use the software.
11 //
12 //
13 //                           License Agreement
14 //                For Open Source Computer Vision Library
15 //
16 // Copyright (C) 2000-2008, Intel Corporation, all rights reserved.
17 // Copyright (C) 2009-2011, Willow Garage Inc., all rights reserved.
18 // Third party copyrights are property of their respective owners.
19 //
20 // Redistribution and use in source and binary forms, with or without modification,
21 // are permitted provided that the following conditions are met:
22 //
23 //   * Redistribution's of source code must retain the above copyright notice,
24 //     this list of conditions and the following disclaimer.
25 //
26 //   * Redistribution's in binary form must reproduce the above copyright notice,
27 //     this list of conditions and the following disclaimer in the documentation
28 //     and/or other materials provided with the distribution.
29 //
30 //   * The name of the copyright holders may not be used to endorse or promote products
31 //     derived from this software without specific prior written permission.
32 //
33 // This software is provided by the copyright holders and contributors "as is" and
34 // any express or implied warranties, including, but not limited to, the implied
35 // warranties of merchantability and fitness for a particular purpose are disclaimed.
36 // In no event shall the Intel Corporation or contributors be liable for any direct,
37 // indirect, incidental, special, exemplary, or consequential damages
38 // (including, but not limited to, procurement of substitute goods or services;
39 // loss of use, data, or profits; or business interruption) however caused
40 // and on any theory of liability, whether in contract, strict liability,
41 // or tort (including negligence or otherwise) arising in any way out of
42 // the use of this software, even if advised of the possibility of such damage.
43 //
44 //M*/
45
46 #ifndef __OPENCV_CORE_HPP__
47 #define __OPENCV_CORE_HPP__
48
49 #include "opencv2/core/types_c.h"
50 #include "opencv2/core/version.hpp"
51
52 #ifdef __cplusplus
53
54 #ifndef SKIP_INCLUDES
55 #include <limits.h>
56 #include <algorithm>
57 #include <cmath>
58 #include <cstddef>
59 #include <complex>
60 #include <map>
61 #include <new>
62 #include <string>
63 #include <vector>
64 #include <sstream>
65 #endif // SKIP_INCLUDES
66
67 /*! \namespace cv
68     Namespace where all the C++ OpenCV functionality resides
69 */
70 namespace cv {
71
72 #undef abs
73 #undef min
74 #undef max
75 #undef Complex
76
77 using std::vector;
78 using std::string;
79 using std::ptrdiff_t;
80
81 template<typename _Tp> class Size_;
82 template<typename _Tp> class Point_;
83 template<typename _Tp> class Rect_;
84 template<typename _Tp, int cn> class Vec;
85 template<typename _Tp, int m, int n> class Matx;
86
87 typedef std::string String;
88
89 class Mat;
90 class SparseMat;
91 typedef Mat MatND;
92
93 namespace ogl {
94     class Buffer;
95     class Texture2D;
96     class Arrays;
97 }
98
99 // < Deprecated
100 class GlBuffer;
101 class GlTexture;
102 class GlArrays;
103 class GlCamera;
104 // >
105
106 namespace gpu {
107     class GpuMat;
108 }
109
110 class CV_EXPORTS MatExpr;
111 class CV_EXPORTS MatOp_Base;
112 class CV_EXPORTS MatArg;
113 class CV_EXPORTS MatConstIterator;
114
115 template<typename _Tp> class Mat_;
116 template<typename _Tp> class MatIterator_;
117 template<typename _Tp> class MatConstIterator_;
118 template<typename _Tp> class MatCommaInitializer_;
119
120 #if !defined(ANDROID) || (defined(_GLIBCXX_USE_WCHAR_T) && _GLIBCXX_USE_WCHAR_T)
121 typedef std::basic_string<wchar_t> WString;
122
123 CV_EXPORTS string fromUtf16(const WString& str);
124 CV_EXPORTS WString toUtf16(const string& str);
125 #endif
126
127 CV_EXPORTS string format( const char* fmt, ... );
128 CV_EXPORTS string tempfile( const char* suffix CV_DEFAULT(0));
129
130 // matrix decomposition types
131 enum { DECOMP_LU=0, DECOMP_SVD=1, DECOMP_EIG=2, DECOMP_CHOLESKY=3, DECOMP_QR=4, DECOMP_NORMAL=16 };
132 enum { NORM_INF=1, NORM_L1=2, NORM_L2=4, NORM_L2SQR=5, NORM_HAMMING=6, NORM_HAMMING2=7, NORM_TYPE_MASK=7, NORM_RELATIVE=8, NORM_MINMAX=32 };
133 enum { CMP_EQ=0, CMP_GT=1, CMP_GE=2, CMP_LT=3, CMP_LE=4, CMP_NE=5 };
134 enum { GEMM_1_T=1, GEMM_2_T=2, GEMM_3_T=4 };
135 enum { DFT_INVERSE=1, DFT_SCALE=2, DFT_ROWS=4, DFT_COMPLEX_OUTPUT=16, DFT_REAL_OUTPUT=32,
136     DCT_INVERSE = DFT_INVERSE, DCT_ROWS=DFT_ROWS };
137
138
139 /*!
140  The standard OpenCV exception class.
141  Instances of the class are thrown by various functions and methods in the case of critical errors.
142  */
143 class CV_EXPORTS Exception : public std::exception
144 {
145 public:
146     /*!
147      Default constructor
148      */
149     Exception();
150     /*!
151      Full constructor. Normally the constuctor is not called explicitly.
152      Instead, the macros CV_Error(), CV_Error_() and CV_Assert() are used.
153     */
154     Exception(int _code, const string& _err, const string& _func, const string& _file, int _line);
155     virtual ~Exception() throw();
156
157     /*!
158      \return the error description and the context as a text string.
159     */
160     virtual const char *what() const throw();
161     void formatMessage();
162
163     string msg; ///< the formatted error message
164
165     int code; ///< error code @see CVStatus
166     string err; ///< error description
167     string func; ///< function name. Available only when the compiler supports getting it
168     string file; ///< source file name where the error has occured
169     int line; ///< line number in the source file where the error has occured
170 };
171
172
173 //! Signals an error and raises the exception.
174
175 /*!
176   By default the function prints information about the error to stderr,
177   then it either stops if setBreakOnError() had been called before or raises the exception.
178   It is possible to alternate error processing by using redirectError().
179
180   \param exc the exception raisen.
181  */
182 CV_EXPORTS void error( const Exception& exc );
183
184 //! Sets/resets the break-on-error mode.
185
186 /*!
187   When the break-on-error mode is set, the default error handler
188   issues a hardware exception, which can make debugging more convenient.
189
190   \return the previous state
191  */
192 CV_EXPORTS bool setBreakOnError(bool flag);
193
194 typedef int (CV_CDECL *ErrorCallback)( int status, const char* func_name,
195                                        const char* err_msg, const char* file_name,
196                                        int line, void* userdata );
197
198 //! Sets the new error handler and the optional user data.
199
200 /*!
201   The function sets the new error handler, called from cv::error().
202
203   \param errCallback the new error handler. If NULL, the default error handler is used.
204   \param userdata the optional user data pointer, passed to the callback.
205   \param prevUserdata the optional output parameter where the previous user data pointer is stored
206
207   \return the previous error handler
208 */
209 CV_EXPORTS ErrorCallback redirectError( ErrorCallback errCallback,
210                                         void* userdata=0, void** prevUserdata=0);
211
212
213 #if defined __GNUC__
214 #define CV_Func __func__
215 #elif defined _MSC_VER
216 #define CV_Func __FUNCTION__
217 #else
218 #define CV_Func ""
219 #endif
220
221 #define CV_Error( code, msg ) cv::error( cv::Exception(code, msg, CV_Func, __FILE__, __LINE__) )
222 #define CV_Error_( code, args ) cv::error( cv::Exception(code, cv::format args, CV_Func, __FILE__, __LINE__) )
223 #define CV_Assert( expr ) if(!!(expr)) ; else cv::error( cv::Exception(CV_StsAssert, #expr, CV_Func, __FILE__, __LINE__) )
224
225 #ifdef _DEBUG
226 #define CV_DbgAssert(expr) CV_Assert(expr)
227 #else
228 #define CV_DbgAssert(expr)
229 #endif
230
231 CV_EXPORTS void glob(String pattern, std::vector<String>& result, bool recursive = false);
232
233 CV_EXPORTS void setNumThreads(int nthreads);
234 CV_EXPORTS int getNumThreads();
235 CV_EXPORTS int getThreadNum();
236
237 CV_EXPORTS_W const string& getBuildInformation();
238
239 //! Returns the number of ticks.
240
241 /*!
242   The function returns the number of ticks since the certain event (e.g. when the machine was turned on).
243   It can be used to initialize cv::RNG or to measure a function execution time by reading the tick count
244   before and after the function call. The granularity of ticks depends on the hardware and OS used. Use
245   cv::getTickFrequency() to convert ticks to seconds.
246 */
247 CV_EXPORTS_W int64 getTickCount();
248
249 /*!
250   Returns the number of ticks per seconds.
251
252   The function returns the number of ticks (as returned by cv::getTickCount()) per second.
253   The following code computes the execution time in milliseconds:
254
255   \code
256   double exec_time = (double)getTickCount();
257   // do something ...
258   exec_time = ((double)getTickCount() - exec_time)*1000./getTickFrequency();
259   \endcode
260 */
261 CV_EXPORTS_W double getTickFrequency();
262
263 /*!
264   Returns the number of CPU ticks.
265
266   On platforms where the feature is available, the function returns the number of CPU ticks
267   since the certain event (normally, the system power-on moment). Using this function
268   one can accurately measure the execution time of very small code fragments,
269   for which cv::getTickCount() granularity is not enough.
270 */
271 CV_EXPORTS_W int64 getCPUTickCount();
272
273 /*!
274   Returns SSE etc. support status
275
276   The function returns true if certain hardware features are available.
277   Currently, the following features are recognized:
278   - CV_CPU_MMX - MMX
279   - CV_CPU_SSE - SSE
280   - CV_CPU_SSE2 - SSE 2
281   - CV_CPU_SSE3 - SSE 3
282   - CV_CPU_SSSE3 - SSSE 3
283   - CV_CPU_SSE4_1 - SSE 4.1
284   - CV_CPU_SSE4_2 - SSE 4.2
285   - CV_CPU_POPCNT - POPCOUNT
286   - CV_CPU_AVX - AVX
287
288   \note {Note that the function output is not static. Once you called cv::useOptimized(false),
289   most of the hardware acceleration is disabled and thus the function will returns false,
290   until you call cv::useOptimized(true)}
291 */
292 CV_EXPORTS_W bool checkHardwareSupport(int feature);
293
294 //! returns the number of CPUs (including hyper-threading)
295 CV_EXPORTS_W int getNumberOfCPUs();
296
297 /*!
298   Allocates memory buffer
299
300   This is specialized OpenCV memory allocation function that returns properly aligned memory buffers.
301   The usage is identical to malloc(). The allocated buffers must be freed with cv::fastFree().
302   If there is not enough memory, the function calls cv::error(), which raises an exception.
303
304   \param bufSize buffer size in bytes
305   \return the allocated memory buffer.
306 */
307 CV_EXPORTS void* fastMalloc(size_t bufSize);
308
309 /*!
310   Frees the memory allocated with cv::fastMalloc
311
312   This is the corresponding deallocation function for cv::fastMalloc().
313   When ptr==NULL, the function has no effect.
314 */
315 CV_EXPORTS void fastFree(void* ptr);
316
317 template<typename _Tp> static inline _Tp* allocate(size_t n)
318 {
319     return new _Tp[n];
320 }
321
322 template<typename _Tp> static inline void deallocate(_Tp* ptr, size_t)
323 {
324     delete[] ptr;
325 }
326
327 /*!
328   Aligns pointer by the certain number of bytes
329
330   This small inline function aligns the pointer by the certian number of bytes by shifting
331   it forward by 0 or a positive offset.
332 */
333 template<typename _Tp> static inline _Tp* alignPtr(_Tp* ptr, int n=(int)sizeof(_Tp))
334 {
335     return (_Tp*)(((size_t)ptr + n-1) & -n);
336 }
337
338 /*!
339   Aligns buffer size by the certain number of bytes
340
341   This small inline function aligns a buffer size by the certian number of bytes by enlarging it.
342 */
343 static inline size_t alignSize(size_t sz, int n)
344 {
345     assert((n & (n - 1)) == 0); // n is a power of 2
346     return (sz + n-1) & -n;
347 }
348
349 /*!
350   Turns on/off available optimization
351
352   The function turns on or off the optimized code in OpenCV. Some optimization can not be enabled
353   or disabled, but, for example, most of SSE code in OpenCV can be temporarily turned on or off this way.
354
355   \note{Since optimization may imply using special data structures, it may be unsafe
356   to call this function anywhere in the code. Instead, call it somewhere at the top level.}
357 */
358 CV_EXPORTS_W void setUseOptimized(bool onoff);
359
360 /*!
361   Returns the current optimization status
362
363   The function returns the current optimization status, which is controlled by cv::setUseOptimized().
364 */
365 CV_EXPORTS_W bool useOptimized();
366
367 /*!
368   The STL-compilant memory Allocator based on cv::fastMalloc() and cv::fastFree()
369 */
370 template<typename _Tp> class Allocator
371 {
372 public:
373     typedef _Tp value_type;
374     typedef value_type* pointer;
375     typedef const value_type* const_pointer;
376     typedef value_type& reference;
377     typedef const value_type& const_reference;
378     typedef size_t size_type;
379     typedef ptrdiff_t difference_type;
380     template<typename U> class rebind { typedef Allocator<U> other; };
381
382     explicit Allocator() {}
383     ~Allocator() {}
384     explicit Allocator(Allocator const&) {}
385     template<typename U>
386     explicit Allocator(Allocator<U> const&) {}
387
388     // address
389     pointer address(reference r) { return &r; }
390     const_pointer address(const_reference r) { return &r; }
391
392     pointer allocate(size_type count, const void* =0)
393     { return reinterpret_cast<pointer>(fastMalloc(count * sizeof (_Tp))); }
394
395     void deallocate(pointer p, size_type) {fastFree(p); }
396
397     size_type max_size() const
398     { return max(static_cast<_Tp>(-1)/sizeof(_Tp), 1); }
399
400     void construct(pointer p, const _Tp& v) { new(static_cast<void*>(p)) _Tp(v); }
401     void destroy(pointer p) { p->~_Tp(); }
402 };
403
404 /////////////////////// Vec (used as element of multi-channel images /////////////////////
405
406 /*!
407   A helper class for cv::DataType
408
409   The class is specialized for each fundamental numerical data type supported by OpenCV.
410   It provides DataDepth<T>::value constant.
411 */
412 template<typename _Tp> class DataDepth {};
413
414 template<> class DataDepth<bool> { public: enum { value = CV_8U, fmt=(int)'u' }; };
415 template<> class DataDepth<uchar> { public: enum { value = CV_8U, fmt=(int)'u' }; };
416 template<> class DataDepth<schar> { public: enum { value = CV_8S, fmt=(int)'c' }; };
417 template<> class DataDepth<char> { public: enum { value = CV_8S, fmt=(int)'c' }; };
418 template<> class DataDepth<ushort> { public: enum { value = CV_16U, fmt=(int)'w' }; };
419 template<> class DataDepth<short> { public: enum { value = CV_16S, fmt=(int)'s' }; };
420 template<> class DataDepth<int> { public: enum { value = CV_32S, fmt=(int)'i' }; };
421 // this is temporary solution to support 32-bit unsigned integers
422 template<> class DataDepth<unsigned> { public: enum { value = CV_32S, fmt=(int)'i' }; };
423 template<> class DataDepth<float> { public: enum { value = CV_32F, fmt=(int)'f' }; };
424 template<> class DataDepth<double> { public: enum { value = CV_64F, fmt=(int)'d' }; };
425 template<typename _Tp> class DataDepth<_Tp*> { public: enum { value = CV_USRTYPE1, fmt=(int)'r' }; };
426
427
428 ////////////////////////////// Small Matrix ///////////////////////////
429
430 /*!
431  A short numerical vector.
432
433  This template class represents short numerical vectors (of 1, 2, 3, 4 ... elements)
434  on which you can perform basic arithmetical operations, access individual elements using [] operator etc.
435  The vectors are allocated on stack, as opposite to std::valarray, std::vector, cv::Mat etc.,
436  which elements are dynamically allocated in the heap.
437
438  The template takes 2 parameters:
439  -# _Tp element type
440  -# cn the number of elements
441
442  In addition to the universal notation like Vec<float, 3>, you can use shorter aliases
443  for the most popular specialized variants of Vec, e.g. Vec3f ~ Vec<float, 3>.
444  */
445
446 struct CV_EXPORTS Matx_AddOp {};
447 struct CV_EXPORTS Matx_SubOp {};
448 struct CV_EXPORTS Matx_ScaleOp {};
449 struct CV_EXPORTS Matx_MulOp {};
450 struct CV_EXPORTS Matx_MatMulOp {};
451 struct CV_EXPORTS Matx_TOp {};
452
453 template<typename _Tp, int m, int n> class Matx
454 {
455 public:
456     typedef _Tp value_type;
457     typedef Matx<_Tp, (m < n ? m : n), 1> diag_type;
458     typedef Matx<_Tp, m, n> mat_type;
459     enum { depth = DataDepth<_Tp>::value, rows = m, cols = n, channels = rows*cols,
460            type = CV_MAKETYPE(depth, channels) };
461
462     //! default constructor
463     Matx();
464
465     Matx(_Tp v0); //!< 1x1 matrix
466     Matx(_Tp v0, _Tp v1); //!< 1x2 or 2x1 matrix
467     Matx(_Tp v0, _Tp v1, _Tp v2); //!< 1x3 or 3x1 matrix
468     Matx(_Tp v0, _Tp v1, _Tp v2, _Tp v3); //!< 1x4, 2x2 or 4x1 matrix
469     Matx(_Tp v0, _Tp v1, _Tp v2, _Tp v3, _Tp v4); //!< 1x5 or 5x1 matrix
470     Matx(_Tp v0, _Tp v1, _Tp v2, _Tp v3, _Tp v4, _Tp v5); //!< 1x6, 2x3, 3x2 or 6x1 matrix
471     Matx(_Tp v0, _Tp v1, _Tp v2, _Tp v3, _Tp v4, _Tp v5, _Tp v6); //!< 1x7 or 7x1 matrix
472     Matx(_Tp v0, _Tp v1, _Tp v2, _Tp v3, _Tp v4, _Tp v5, _Tp v6, _Tp v7); //!< 1x8, 2x4, 4x2 or 8x1 matrix
473     Matx(_Tp v0, _Tp v1, _Tp v2, _Tp v3, _Tp v4, _Tp v5, _Tp v6, _Tp v7, _Tp v8); //!< 1x9, 3x3 or 9x1 matrix
474     Matx(_Tp v0, _Tp v1, _Tp v2, _Tp v3, _Tp v4, _Tp v5, _Tp v6, _Tp v7, _Tp v8, _Tp v9); //!< 1x10, 2x5 or 5x2 or 10x1 matrix
475     Matx(_Tp v0, _Tp v1, _Tp v2, _Tp v3,
476          _Tp v4, _Tp v5, _Tp v6, _Tp v7,
477          _Tp v8, _Tp v9, _Tp v10, _Tp v11); //!< 1x12, 2x6, 3x4, 4x3, 6x2 or 12x1 matrix
478     Matx(_Tp v0, _Tp v1, _Tp v2, _Tp v3,
479          _Tp v4, _Tp v5, _Tp v6, _Tp v7,
480          _Tp v8, _Tp v9, _Tp v10, _Tp v11,
481          _Tp v12, _Tp v13, _Tp v14, _Tp v15); //!< 1x16, 4x4 or 16x1 matrix
482     explicit Matx(const _Tp* vals); //!< initialize from a plain array
483
484     static Matx all(_Tp alpha);
485     static Matx zeros();
486     static Matx ones();
487     static Matx eye();
488     static Matx diag(const diag_type& d);
489     static Matx randu(_Tp a, _Tp b);
490     static Matx randn(_Tp a, _Tp b);
491
492     //! dot product computed with the default precision
493     _Tp dot(const Matx<_Tp, m, n>& v) const;
494
495     //! dot product computed in double-precision arithmetics
496     double ddot(const Matx<_Tp, m, n>& v) const;
497
498     //! convertion to another data type
499     template<typename T2> operator Matx<T2, m, n>() const;
500
501     //! change the matrix shape
502     template<int m1, int n1> Matx<_Tp, m1, n1> reshape() const;
503
504     //! extract part of the matrix
505     template<int m1, int n1> Matx<_Tp, m1, n1> get_minor(int i, int j) const;
506
507     //! extract the matrix row
508     Matx<_Tp, 1, n> row(int i) const;
509
510     //! extract the matrix column
511     Matx<_Tp, m, 1> col(int i) const;
512
513     //! extract the matrix diagonal
514     diag_type diag() const;
515
516     //! transpose the matrix
517     Matx<_Tp, n, m> t() const;
518
519     //! invert matrix the matrix
520     Matx<_Tp, n, m> inv(int method=DECOMP_LU) const;
521
522     //! solve linear system
523     template<int l> Matx<_Tp, n, l> solve(const Matx<_Tp, m, l>& rhs, int flags=DECOMP_LU) const;
524     Vec<_Tp, n> solve(const Vec<_Tp, m>& rhs, int method) const;
525
526     //! multiply two matrices element-wise
527     Matx<_Tp, m, n> mul(const Matx<_Tp, m, n>& a) const;
528
529     //! element access
530     const _Tp& operator ()(int i, int j) const;
531     _Tp& operator ()(int i, int j);
532
533     //! 1D element access
534     const _Tp& operator ()(int i) const;
535     _Tp& operator ()(int i);
536
537     Matx(const Matx<_Tp, m, n>& a, const Matx<_Tp, m, n>& b, Matx_AddOp);
538     Matx(const Matx<_Tp, m, n>& a, const Matx<_Tp, m, n>& b, Matx_SubOp);
539     template<typename _T2> Matx(const Matx<_Tp, m, n>& a, _T2 alpha, Matx_ScaleOp);
540     Matx(const Matx<_Tp, m, n>& a, const Matx<_Tp, m, n>& b, Matx_MulOp);
541     template<int l> Matx(const Matx<_Tp, m, l>& a, const Matx<_Tp, l, n>& b, Matx_MatMulOp);
542     Matx(const Matx<_Tp, n, m>& a, Matx_TOp);
543
544     _Tp val[m*n]; //< matrix elements
545 };
546
547
548 typedef Matx<float, 1, 2> Matx12f;
549 typedef Matx<double, 1, 2> Matx12d;
550 typedef Matx<float, 1, 3> Matx13f;
551 typedef Matx<double, 1, 3> Matx13d;
552 typedef Matx<float, 1, 4> Matx14f;
553 typedef Matx<double, 1, 4> Matx14d;
554 typedef Matx<float, 1, 6> Matx16f;
555 typedef Matx<double, 1, 6> Matx16d;
556
557 typedef Matx<float, 2, 1> Matx21f;
558 typedef Matx<double, 2, 1> Matx21d;
559 typedef Matx<float, 3, 1> Matx31f;
560 typedef Matx<double, 3, 1> Matx31d;
561 typedef Matx<float, 4, 1> Matx41f;
562 typedef Matx<double, 4, 1> Matx41d;
563 typedef Matx<float, 6, 1> Matx61f;
564 typedef Matx<double, 6, 1> Matx61d;
565
566 typedef Matx<float, 2, 2> Matx22f;
567 typedef Matx<double, 2, 2> Matx22d;
568 typedef Matx<float, 2, 3> Matx23f;
569 typedef Matx<double, 2, 3> Matx23d;
570 typedef Matx<float, 3, 2> Matx32f;
571 typedef Matx<double, 3, 2> Matx32d;
572
573 typedef Matx<float, 3, 3> Matx33f;
574 typedef Matx<double, 3, 3> Matx33d;
575
576 typedef Matx<float, 3, 4> Matx34f;
577 typedef Matx<double, 3, 4> Matx34d;
578 typedef Matx<float, 4, 3> Matx43f;
579 typedef Matx<double, 4, 3> Matx43d;
580
581 typedef Matx<float, 4, 4> Matx44f;
582 typedef Matx<double, 4, 4> Matx44d;
583 typedef Matx<float, 6, 6> Matx66f;
584 typedef Matx<double, 6, 6> Matx66d;
585
586
587 /*!
588   A short numerical vector.
589
590   This template class represents short numerical vectors (of 1, 2, 3, 4 ... elements)
591   on which you can perform basic arithmetical operations, access individual elements using [] operator etc.
592   The vectors are allocated on stack, as opposite to std::valarray, std::vector, cv::Mat etc.,
593   which elements are dynamically allocated in the heap.
594
595   The template takes 2 parameters:
596   -# _Tp element type
597   -# cn the number of elements
598
599   In addition to the universal notation like Vec<float, 3>, you can use shorter aliases
600   for the most popular specialized variants of Vec, e.g. Vec3f ~ Vec<float, 3>.
601 */
602 template<typename _Tp, int cn> class Vec : public Matx<_Tp, cn, 1>
603 {
604 public:
605     typedef _Tp value_type;
606     enum { depth = DataDepth<_Tp>::value, channels = cn, type = CV_MAKETYPE(depth, channels) };
607
608     //! default constructor
609     Vec();
610
611     Vec(_Tp v0); //!< 1-element vector constructor
612     Vec(_Tp v0, _Tp v1); //!< 2-element vector constructor
613     Vec(_Tp v0, _Tp v1, _Tp v2); //!< 3-element vector constructor
614     Vec(_Tp v0, _Tp v1, _Tp v2, _Tp v3); //!< 4-element vector constructor
615     Vec(_Tp v0, _Tp v1, _Tp v2, _Tp v3, _Tp v4); //!< 5-element vector constructor
616     Vec(_Tp v0, _Tp v1, _Tp v2, _Tp v3, _Tp v4, _Tp v5); //!< 6-element vector constructor
617     Vec(_Tp v0, _Tp v1, _Tp v2, _Tp v3, _Tp v4, _Tp v5, _Tp v6); //!< 7-element vector constructor
618     Vec(_Tp v0, _Tp v1, _Tp v2, _Tp v3, _Tp v4, _Tp v5, _Tp v6, _Tp v7); //!< 8-element vector constructor
619     Vec(_Tp v0, _Tp v1, _Tp v2, _Tp v3, _Tp v4, _Tp v5, _Tp v6, _Tp v7, _Tp v8); //!< 9-element vector constructor
620     Vec(_Tp v0, _Tp v1, _Tp v2, _Tp v3, _Tp v4, _Tp v5, _Tp v6, _Tp v7, _Tp v8, _Tp v9); //!< 10-element vector constructor
621     explicit Vec(const _Tp* values);
622
623     Vec(const Vec<_Tp, cn>& v);
624
625     static Vec all(_Tp alpha);
626
627     //! per-element multiplication
628     Vec mul(const Vec<_Tp, cn>& v) const;
629
630     //! conjugation (makes sense for complex numbers and quaternions)
631     Vec conj() const;
632
633     /*!
634       cross product of the two 3D vectors.
635
636       For other dimensionalities the exception is raised
637     */
638     Vec cross(const Vec& v) const;
639     //! convertion to another data type
640     template<typename T2> operator Vec<T2, cn>() const;
641     //! conversion to 4-element CvScalar.
642     operator CvScalar() const;
643
644     /*! element access */
645     const _Tp& operator [](int i) const;
646     _Tp& operator[](int i);
647     const _Tp& operator ()(int i) const;
648     _Tp& operator ()(int i);
649
650     Vec(const Matx<_Tp, cn, 1>& a, const Matx<_Tp, cn, 1>& b, Matx_AddOp);
651     Vec(const Matx<_Tp, cn, 1>& a, const Matx<_Tp, cn, 1>& b, Matx_SubOp);
652     template<typename _T2> Vec(const Matx<_Tp, cn, 1>& a, _T2 alpha, Matx_ScaleOp);
653 };
654
655
656 /* \typedef
657
658    Shorter aliases for the most popular specializations of Vec<T,n>
659 */
660 typedef Vec<uchar, 2> Vec2b;
661 typedef Vec<uchar, 3> Vec3b;
662 typedef Vec<uchar, 4> Vec4b;
663
664 typedef Vec<short, 2> Vec2s;
665 typedef Vec<short, 3> Vec3s;
666 typedef Vec<short, 4> Vec4s;
667
668 typedef Vec<ushort, 2> Vec2w;
669 typedef Vec<ushort, 3> Vec3w;
670 typedef Vec<ushort, 4> Vec4w;
671
672 typedef Vec<int, 2> Vec2i;
673 typedef Vec<int, 3> Vec3i;
674 typedef Vec<int, 4> Vec4i;
675 typedef Vec<int, 6> Vec6i;
676 typedef Vec<int, 8> Vec8i;
677
678 typedef Vec<float, 2> Vec2f;
679 typedef Vec<float, 3> Vec3f;
680 typedef Vec<float, 4> Vec4f;
681 typedef Vec<float, 6> Vec6f;
682
683 typedef Vec<double, 2> Vec2d;
684 typedef Vec<double, 3> Vec3d;
685 typedef Vec<double, 4> Vec4d;
686 typedef Vec<double, 6> Vec6d;
687
688
689 //////////////////////////////// Complex //////////////////////////////
690
691 /*!
692   A complex number class.
693
694   The template class is similar and compatible with std::complex, however it provides slightly
695   more convenient access to the real and imaginary parts using through the simple field access, as opposite
696   to std::complex::real() and std::complex::imag().
697 */
698 template<typename _Tp> class Complex
699 {
700 public:
701
702     //! constructors
703     Complex();
704     Complex( _Tp _re, _Tp _im=0 );
705     Complex( const std::complex<_Tp>& c );
706
707     //! conversion to another data type
708     template<typename T2> operator Complex<T2>() const;
709     //! conjugation
710     Complex conj() const;
711     //! conversion to std::complex
712     operator std::complex<_Tp>() const;
713
714     _Tp re, im; //< the real and the imaginary parts
715 };
716
717
718 /*!
719   \typedef
720 */
721 typedef Complex<float> Complexf;
722 typedef Complex<double> Complexd;
723
724
725 //////////////////////////////// Point_ ////////////////////////////////
726
727 /*!
728   template 2D point class.
729
730   The class defines a point in 2D space. Data type of the point coordinates is specified
731   as a template parameter. There are a few shorter aliases available for user convenience.
732   See cv::Point, cv::Point2i, cv::Point2f and cv::Point2d.
733 */
734 template<typename _Tp> class Point_
735 {
736 public:
737     typedef _Tp value_type;
738
739     // various constructors
740     Point_();
741     Point_(_Tp _x, _Tp _y);
742     Point_(const Point_& pt);
743     Point_(const CvPoint& pt);
744     Point_(const CvPoint2D32f& pt);
745     Point_(const Size_<_Tp>& sz);
746     Point_(const Vec<_Tp, 2>& v);
747
748     Point_& operator = (const Point_& pt);
749     //! conversion to another data type
750     template<typename _Tp2> operator Point_<_Tp2>() const;
751
752     //! conversion to the old-style C structures
753     operator CvPoint() const;
754     operator CvPoint2D32f() const;
755     operator Vec<_Tp, 2>() const;
756
757     //! dot product
758     _Tp dot(const Point_& pt) const;
759     //! dot product computed in double-precision arithmetics
760     double ddot(const Point_& pt) const;
761     //! cross-product
762     double cross(const Point_& pt) const;
763     //! checks whether the point is inside the specified rectangle
764     bool inside(const Rect_<_Tp>& r) const;
765
766     _Tp x, y; //< the point coordinates
767 };
768
769 /*!
770   template 3D point class.
771
772   The class defines a point in 3D space. Data type of the point coordinates is specified
773   as a template parameter.
774
775   \see cv::Point3i, cv::Point3f and cv::Point3d
776 */
777 template<typename _Tp> class Point3_
778 {
779 public:
780     typedef _Tp value_type;
781
782     // various constructors
783     Point3_();
784     Point3_(_Tp _x, _Tp _y, _Tp _z);
785     Point3_(const Point3_& pt);
786     explicit Point3_(const Point_<_Tp>& pt);
787     Point3_(const CvPoint3D32f& pt);
788     Point3_(const Vec<_Tp, 3>& v);
789
790     Point3_& operator = (const Point3_& pt);
791     //! conversion to another data type
792     template<typename _Tp2> operator Point3_<_Tp2>() const;
793     //! conversion to the old-style CvPoint...
794     operator CvPoint3D32f() const;
795     //! conversion to cv::Vec<>
796     operator Vec<_Tp, 3>() const;
797
798     //! dot product
799     _Tp dot(const Point3_& pt) const;
800     //! dot product computed in double-precision arithmetics
801     double ddot(const Point3_& pt) const;
802     //! cross product of the 2 3D points
803     Point3_ cross(const Point3_& pt) const;
804
805     _Tp x, y, z; //< the point coordinates
806 };
807
808 //////////////////////////////// Size_ ////////////////////////////////
809
810 /*!
811   The 2D size class
812
813   The class represents the size of a 2D rectangle, image size, matrix size etc.
814   Normally, cv::Size ~ cv::Size_<int> is used.
815 */
816 template<typename _Tp> class Size_
817 {
818 public:
819     typedef _Tp value_type;
820
821     //! various constructors
822     Size_();
823     Size_(_Tp _width, _Tp _height);
824     Size_(const Size_& sz);
825     Size_(const CvSize& sz);
826     Size_(const CvSize2D32f& sz);
827     Size_(const Point_<_Tp>& pt);
828
829     Size_& operator = (const Size_& sz);
830     //! the area (width*height)
831     _Tp area() const;
832
833     //! conversion of another data type.
834     template<typename _Tp2> operator Size_<_Tp2>() const;
835
836     //! conversion to the old-style OpenCV types
837     operator CvSize() const;
838     operator CvSize2D32f() const;
839
840     _Tp width, height; // the width and the height
841 };
842
843 //////////////////////////////// Rect_ ////////////////////////////////
844
845 /*!
846   The 2D up-right rectangle class
847
848   The class represents a 2D rectangle with coordinates of the specified data type.
849   Normally, cv::Rect ~ cv::Rect_<int> is used.
850 */
851 template<typename _Tp> class Rect_
852 {
853 public:
854     typedef _Tp value_type;
855
856     //! various constructors
857     Rect_();
858     Rect_(_Tp _x, _Tp _y, _Tp _width, _Tp _height);
859     Rect_(const Rect_& r);
860     Rect_(const CvRect& r);
861     Rect_(const Point_<_Tp>& org, const Size_<_Tp>& sz);
862     Rect_(const Point_<_Tp>& pt1, const Point_<_Tp>& pt2);
863
864     Rect_& operator = ( const Rect_& r );
865     //! the top-left corner
866     Point_<_Tp> tl() const;
867     //! the bottom-right corner
868     Point_<_Tp> br() const;
869
870     //! size (width, height) of the rectangle
871     Size_<_Tp> size() const;
872     //! area (width*height) of the rectangle
873     _Tp area() const;
874
875     //! conversion to another data type
876     template<typename _Tp2> operator Rect_<_Tp2>() const;
877     //! conversion to the old-style CvRect
878     operator CvRect() const;
879
880     //! checks whether the rectangle contains the point
881     bool contains(const Point_<_Tp>& pt) const;
882
883     _Tp x, y, width, height; //< the top-left corner, as well as width and height of the rectangle
884 };
885
886
887 /*!
888   \typedef
889
890   shorter aliases for the most popular cv::Point_<>, cv::Size_<> and cv::Rect_<> specializations
891 */
892 typedef Point_<int> Point2i;
893 typedef Point2i Point;
894 typedef Size_<int> Size2i;
895 typedef Size2i Size;
896 typedef Rect_<int> Rect;
897 typedef Point_<float> Point2f;
898 typedef Point_<double> Point2d;
899 typedef Size_<float> Size2f;
900 typedef Point3_<int> Point3i;
901 typedef Point3_<float> Point3f;
902 typedef Point3_<double> Point3d;
903
904
905 /*!
906   The rotated 2D rectangle.
907
908   The class represents rotated (i.e. not up-right) rectangles on a plane.
909   Each rectangle is described by the center point (mass center), length of each side
910   (represented by cv::Size2f structure) and the rotation angle in degrees.
911 */
912 class CV_EXPORTS RotatedRect
913 {
914 public:
915     //! various constructors
916     RotatedRect();
917     RotatedRect(const Point2f& center, const Size2f& size, float angle);
918     RotatedRect(const CvBox2D& box);
919
920     //! returns 4 vertices of the rectangle
921     void points(Point2f pts[]) const;
922     //! returns the minimal up-right rectangle containing the rotated rectangle
923     Rect boundingRect() const;
924     //! conversion to the old-style CvBox2D structure
925     operator CvBox2D() const;
926
927     Point2f center; //< the rectangle mass center
928     Size2f size;    //< width and height of the rectangle
929     float angle;    //< the rotation angle. When the angle is 0, 90, 180, 270 etc., the rectangle becomes an up-right rectangle.
930 };
931
932 //////////////////////////////// Scalar_ ///////////////////////////////
933
934 /*!
935    The template scalar class.
936
937    This is partially specialized cv::Vec class with the number of elements = 4, i.e. a short vector of four elements.
938    Normally, cv::Scalar ~ cv::Scalar_<double> is used.
939 */
940 template<typename _Tp> class Scalar_ : public Vec<_Tp, 4>
941 {
942 public:
943     //! various constructors
944     Scalar_();
945     Scalar_(_Tp v0, _Tp v1, _Tp v2=0, _Tp v3=0);
946     Scalar_(const CvScalar& s);
947     Scalar_(_Tp v0);
948
949     //! returns a scalar with all elements set to v0
950     static Scalar_<_Tp> all(_Tp v0);
951     //! conversion to the old-style CvScalar
952     operator CvScalar() const;
953
954     //! conversion to another data type
955     template<typename T2> operator Scalar_<T2>() const;
956
957     //! per-element product
958     Scalar_<_Tp> mul(const Scalar_<_Tp>& t, double scale=1 ) const;
959
960     // returns (v0, -v1, -v2, -v3)
961     Scalar_<_Tp> conj() const;
962
963     // returns true iff v1 == v2 == v3 == 0
964     bool isReal() const;
965 };
966
967 typedef Scalar_<double> Scalar;
968
969 CV_EXPORTS void scalarToRawData(const Scalar& s, void* buf, int type, int unroll_to=0);
970
971 //////////////////////////////// Range /////////////////////////////////
972
973 /*!
974    The 2D range class
975
976    This is the class used to specify a continuous subsequence, i.e. part of a contour, or a column span in a matrix.
977 */
978 class CV_EXPORTS Range
979 {
980 public:
981     Range();
982     Range(int _start, int _end);
983     Range(const CvSlice& slice);
984     int size() const;
985     bool empty() const;
986     static Range all();
987     operator CvSlice() const;
988
989     int start, end;
990 };
991
992 /////////////////////////////// DataType ////////////////////////////////
993
994 /*!
995    Informative template class for OpenCV "scalars".
996
997    The class is specialized for each primitive numerical type supported by OpenCV (such as unsigned char or float),
998    as well as for more complex types, like cv::Complex<>, std::complex<>, cv::Vec<> etc.
999    The common property of all such types (called "scalars", do not confuse it with cv::Scalar_)
1000    is that each of them is basically a tuple of numbers of the same type. Each "scalar" can be represented
1001    by the depth id (CV_8U ... CV_64F) and the number of channels.
1002    OpenCV matrices, 2D or nD, dense or sparse, can store "scalars",
1003    as long as the number of channels does not exceed CV_CN_MAX.
1004 */
1005 template<typename _Tp> class DataType
1006 {
1007 public:
1008     typedef _Tp value_type;
1009     typedef value_type work_type;
1010     typedef value_type channel_type;
1011     typedef value_type vec_type;
1012     enum { generic_type = 1, depth = -1, channels = 1, fmt=0,
1013         type = CV_MAKETYPE(depth, channels) };
1014 };
1015
1016 template<> class DataType<bool>
1017 {
1018 public:
1019     typedef bool value_type;
1020     typedef int work_type;
1021     typedef value_type channel_type;
1022     typedef value_type vec_type;
1023     enum { generic_type = 0, depth = DataDepth<channel_type>::value, channels = 1,
1024            fmt=DataDepth<channel_type>::fmt,
1025            type = CV_MAKETYPE(depth, channels) };
1026 };
1027
1028 template<> class DataType<uchar>
1029 {
1030 public:
1031     typedef uchar value_type;
1032     typedef int work_type;
1033     typedef value_type channel_type;
1034     typedef value_type vec_type;
1035     enum { generic_type = 0, depth = DataDepth<channel_type>::value, channels = 1,
1036            fmt=DataDepth<channel_type>::fmt,
1037            type = CV_MAKETYPE(depth, channels) };
1038 };
1039
1040 template<> class DataType<schar>
1041 {
1042 public:
1043     typedef schar value_type;
1044     typedef int work_type;
1045     typedef value_type channel_type;
1046     typedef value_type vec_type;
1047     enum { generic_type = 0, depth = DataDepth<channel_type>::value, channels = 1,
1048            fmt=DataDepth<channel_type>::fmt,
1049            type = CV_MAKETYPE(depth, channels) };
1050 };
1051
1052 template<> class DataType<char>
1053 {
1054 public:
1055     typedef schar value_type;
1056     typedef int work_type;
1057     typedef value_type channel_type;
1058     typedef value_type vec_type;
1059     enum { generic_type = 0, depth = DataDepth<channel_type>::value, channels = 1,
1060            fmt=DataDepth<channel_type>::fmt,
1061            type = CV_MAKETYPE(depth, channels) };
1062 };
1063
1064 template<> class DataType<ushort>
1065 {
1066 public:
1067     typedef ushort value_type;
1068     typedef int work_type;
1069     typedef value_type channel_type;
1070     typedef value_type vec_type;
1071     enum { generic_type = 0, depth = DataDepth<channel_type>::value, channels = 1,
1072            fmt=DataDepth<channel_type>::fmt,
1073            type = CV_MAKETYPE(depth, channels) };
1074 };
1075
1076 template<> class DataType<short>
1077 {
1078 public:
1079     typedef short value_type;
1080     typedef int work_type;
1081     typedef value_type channel_type;
1082     typedef value_type vec_type;
1083     enum { generic_type = 0, depth = DataDepth<channel_type>::value, channels = 1,
1084            fmt=DataDepth<channel_type>::fmt,
1085            type = CV_MAKETYPE(depth, channels) };
1086 };
1087
1088 template<> class DataType<int>
1089 {
1090 public:
1091     typedef int value_type;
1092     typedef value_type work_type;
1093     typedef value_type channel_type;
1094     typedef value_type vec_type;
1095     enum { generic_type = 0, depth = DataDepth<channel_type>::value, channels = 1,
1096            fmt=DataDepth<channel_type>::fmt,
1097            type = CV_MAKETYPE(depth, channels) };
1098 };
1099
1100 template<> class DataType<float>
1101 {
1102 public:
1103     typedef float value_type;
1104     typedef value_type work_type;
1105     typedef value_type channel_type;
1106     typedef value_type vec_type;
1107     enum { generic_type = 0, depth = DataDepth<channel_type>::value, channels = 1,
1108            fmt=DataDepth<channel_type>::fmt,
1109            type = CV_MAKETYPE(depth, channels) };
1110 };
1111
1112 template<> class DataType<double>
1113 {
1114 public:
1115     typedef double value_type;
1116     typedef value_type work_type;
1117     typedef value_type channel_type;
1118     typedef value_type vec_type;
1119     enum { generic_type = 0, depth = DataDepth<channel_type>::value, channels = 1,
1120            fmt=DataDepth<channel_type>::fmt,
1121            type = CV_MAKETYPE(depth, channels) };
1122 };
1123
1124 template<typename _Tp, int m, int n> class DataType<Matx<_Tp, m, n> >
1125 {
1126 public:
1127     typedef Matx<_Tp, m, n> value_type;
1128     typedef Matx<typename DataType<_Tp>::work_type, m, n> work_type;
1129     typedef _Tp channel_type;
1130     typedef value_type vec_type;
1131     enum { generic_type = 0, depth = DataDepth<channel_type>::value, channels = m*n,
1132         fmt = ((channels-1)<<8) + DataDepth<channel_type>::fmt,
1133         type = CV_MAKETYPE(depth, channels) };
1134 };
1135
1136 template<typename _Tp, int cn> class DataType<Vec<_Tp, cn> >
1137 {
1138 public:
1139     typedef Vec<_Tp, cn> value_type;
1140     typedef Vec<typename DataType<_Tp>::work_type, cn> work_type;
1141     typedef _Tp channel_type;
1142     typedef value_type vec_type;
1143     enum { generic_type = 0, depth = DataDepth<channel_type>::value, channels = cn,
1144            fmt = ((channels-1)<<8) + DataDepth<channel_type>::fmt,
1145            type = CV_MAKETYPE(depth, channels) };
1146 };
1147
1148 template<typename _Tp> class DataType<std::complex<_Tp> >
1149 {
1150 public:
1151     typedef std::complex<_Tp> value_type;
1152     typedef value_type work_type;
1153     typedef _Tp channel_type;
1154     enum { generic_type = 0, depth = DataDepth<channel_type>::value, channels = 2,
1155            fmt = ((channels-1)<<8) + DataDepth<channel_type>::fmt,
1156            type = CV_MAKETYPE(depth, channels) };
1157     typedef Vec<channel_type, channels> vec_type;
1158 };
1159
1160 template<typename _Tp> class DataType<Complex<_Tp> >
1161 {
1162 public:
1163     typedef Complex<_Tp> value_type;
1164     typedef value_type work_type;
1165     typedef _Tp channel_type;
1166     enum { generic_type = 0, depth = DataDepth<channel_type>::value, channels = 2,
1167            fmt = ((channels-1)<<8) + DataDepth<channel_type>::fmt,
1168            type = CV_MAKETYPE(depth, channels) };
1169     typedef Vec<channel_type, channels> vec_type;
1170 };
1171
1172 template<typename _Tp> class DataType<Point_<_Tp> >
1173 {
1174 public:
1175     typedef Point_<_Tp> value_type;
1176     typedef Point_<typename DataType<_Tp>::work_type> work_type;
1177     typedef _Tp channel_type;
1178     enum { generic_type = 0, depth = DataDepth<channel_type>::value, channels = 2,
1179            fmt = ((channels-1)<<8) + DataDepth<channel_type>::fmt,
1180            type = CV_MAKETYPE(depth, channels) };
1181     typedef Vec<channel_type, channels> vec_type;
1182 };
1183
1184 template<typename _Tp> class DataType<Point3_<_Tp> >
1185 {
1186 public:
1187     typedef Point3_<_Tp> value_type;
1188     typedef Point3_<typename DataType<_Tp>::work_type> work_type;
1189     typedef _Tp channel_type;
1190     enum { generic_type = 0, depth = DataDepth<channel_type>::value, channels = 3,
1191            fmt = ((channels-1)<<8) + DataDepth<channel_type>::fmt,
1192            type = CV_MAKETYPE(depth, channels) };
1193     typedef Vec<channel_type, channels> vec_type;
1194 };
1195
1196 template<typename _Tp> class DataType<Size_<_Tp> >
1197 {
1198 public:
1199     typedef Size_<_Tp> value_type;
1200     typedef Size_<typename DataType<_Tp>::work_type> work_type;
1201     typedef _Tp channel_type;
1202     enum { generic_type = 0, depth = DataDepth<channel_type>::value, channels = 2,
1203            fmt = ((channels-1)<<8) + DataDepth<channel_type>::fmt,
1204            type = CV_MAKETYPE(depth, channels) };
1205     typedef Vec<channel_type, channels> vec_type;
1206 };
1207
1208 template<typename _Tp> class DataType<Rect_<_Tp> >
1209 {
1210 public:
1211     typedef Rect_<_Tp> value_type;
1212     typedef Rect_<typename DataType<_Tp>::work_type> work_type;
1213     typedef _Tp channel_type;
1214     enum { generic_type = 0, depth = DataDepth<channel_type>::value, channels = 4,
1215            fmt = ((channels-1)<<8) + DataDepth<channel_type>::fmt,
1216            type = CV_MAKETYPE(depth, channels) };
1217     typedef Vec<channel_type, channels> vec_type;
1218 };
1219
1220 template<typename _Tp> class DataType<Scalar_<_Tp> >
1221 {
1222 public:
1223     typedef Scalar_<_Tp> value_type;
1224     typedef Scalar_<typename DataType<_Tp>::work_type> work_type;
1225     typedef _Tp channel_type;
1226     enum { generic_type = 0, depth = DataDepth<channel_type>::value, channels = 4,
1227            fmt = ((channels-1)<<8) + DataDepth<channel_type>::fmt,
1228            type = CV_MAKETYPE(depth, channels) };
1229     typedef Vec<channel_type, channels> vec_type;
1230 };
1231
1232 template<> class DataType<Range>
1233 {
1234 public:
1235     typedef Range value_type;
1236     typedef value_type work_type;
1237     typedef int channel_type;
1238     enum { generic_type = 0, depth = DataDepth<channel_type>::value, channels = 2,
1239            fmt = ((channels-1)<<8) + DataDepth<channel_type>::fmt,
1240            type = CV_MAKETYPE(depth, channels) };
1241     typedef Vec<channel_type, channels> vec_type;
1242 };
1243
1244 //////////////////// generic_type ref-counting pointer class for C/C++ objects ////////////////////////
1245
1246 /*!
1247   Smart pointer to dynamically allocated objects.
1248
1249   This is template pointer-wrapping class that stores the associated reference counter along with the
1250   object pointer. The class is similar to std::smart_ptr<> from the recent addons to the C++ standard,
1251   but is shorter to write :) and self-contained (i.e. does add any dependency on the compiler or an external library).
1252
1253   Basically, you can use "Ptr<MyObjectType> ptr" (or faster "const Ptr<MyObjectType>& ptr" for read-only access)
1254   everywhere instead of "MyObjectType* ptr", where MyObjectType is some C structure or a C++ class.
1255   To make it all work, you need to specialize Ptr<>::delete_obj(), like:
1256
1257   \code
1258   template<> void Ptr<MyObjectType>::delete_obj() { call_destructor_func(obj); }
1259   \endcode
1260
1261   \note{if MyObjectType is a C++ class with a destructor, you do not need to specialize delete_obj(),
1262   since the default implementation calls "delete obj;"}
1263
1264   \note{Another good property of the class is that the operations on the reference counter are atomic,
1265   i.e. it is safe to use the class in multi-threaded applications}
1266 */
1267 template<typename _Tp> class Ptr
1268 {
1269 public:
1270     //! empty constructor
1271     Ptr();
1272     //! take ownership of the pointer. The associated reference counter is allocated and set to 1
1273     Ptr(_Tp* _obj);
1274     //! calls release()
1275     ~Ptr();
1276     //! copy constructor. Copies the members and calls addref()
1277     Ptr(const Ptr& ptr);
1278     template<typename _Tp2> Ptr(const Ptr<_Tp2>& ptr);
1279     //! copy operator. Calls ptr.addref() and release() before copying the members
1280     Ptr& operator = (const Ptr& ptr);
1281     //! increments the reference counter
1282     void addref();
1283     //! decrements the reference counter. If it reaches 0, delete_obj() is called
1284     void release();
1285     //! deletes the object. Override if needed
1286     void delete_obj();
1287     //! returns true iff obj==NULL
1288     bool empty() const;
1289
1290     //! cast pointer to another type
1291     template<typename _Tp2> Ptr<_Tp2> ptr();
1292     template<typename _Tp2> const Ptr<_Tp2> ptr() const;
1293
1294     //! helper operators making "Ptr<T> ptr" use very similar to "T* ptr".
1295     _Tp* operator -> ();
1296     const _Tp* operator -> () const;
1297
1298     operator _Tp* ();
1299     operator const _Tp*() const;
1300
1301     _Tp* obj; //< the object pointer.
1302     int* refcount; //< the associated reference counter
1303 };
1304
1305
1306 //////////////////////// Input/Output Array Arguments /////////////////////////////////
1307
1308 /*!
1309  Proxy datatype for passing Mat's and vector<>'s as input parameters
1310  */
1311 class CV_EXPORTS _InputArray
1312 {
1313 public:
1314     enum {
1315         KIND_SHIFT = 16,
1316         FIXED_TYPE = 0x8000 << KIND_SHIFT,
1317         FIXED_SIZE = 0x4000 << KIND_SHIFT,
1318         KIND_MASK = ~(FIXED_TYPE|FIXED_SIZE) - (1 << KIND_SHIFT) + 1,
1319
1320         NONE              = 0 << KIND_SHIFT,
1321         MAT               = 1 << KIND_SHIFT,
1322         MATX              = 2 << KIND_SHIFT,
1323         STD_VECTOR        = 3 << KIND_SHIFT,
1324         STD_VECTOR_VECTOR = 4 << KIND_SHIFT,
1325         STD_VECTOR_MAT    = 5 << KIND_SHIFT,
1326         EXPR              = 6 << KIND_SHIFT,
1327         OPENGL_BUFFER     = 7 << KIND_SHIFT,
1328         OPENGL_TEXTURE    = 8 << KIND_SHIFT,
1329         GPU_MAT           = 9 << KIND_SHIFT,
1330         OCL_MAT           =10 << KIND_SHIFT
1331     };
1332     _InputArray();
1333
1334     _InputArray(const Mat& m);
1335     _InputArray(const MatExpr& expr);
1336     template<typename _Tp> _InputArray(const _Tp* vec, int n);
1337     template<typename _Tp> _InputArray(const vector<_Tp>& vec);
1338     template<typename _Tp> _InputArray(const vector<vector<_Tp> >& vec);
1339     _InputArray(const vector<Mat>& vec);
1340     template<typename _Tp> _InputArray(const vector<Mat_<_Tp> >& vec);
1341     template<typename _Tp> _InputArray(const Mat_<_Tp>& m);
1342     template<typename _Tp, int m, int n> _InputArray(const Matx<_Tp, m, n>& matx);
1343     _InputArray(const Scalar& s);
1344     _InputArray(const double& val);
1345     // < Deprecated
1346     _InputArray(const GlBuffer& buf);
1347     _InputArray(const GlTexture& tex);
1348     // >
1349     _InputArray(const gpu::GpuMat& d_mat);
1350     _InputArray(const ogl::Buffer& buf);
1351     _InputArray(const ogl::Texture2D& tex);
1352
1353     virtual Mat getMat(int i=-1) const;
1354     virtual void getMatVector(vector<Mat>& mv) const;
1355     // < Deprecated
1356     virtual GlBuffer getGlBuffer() const;
1357     virtual GlTexture getGlTexture() const;
1358     // >
1359     virtual gpu::GpuMat getGpuMat() const;
1360     /*virtual*/ ogl::Buffer getOGlBuffer() const;
1361     /*virtual*/ ogl::Texture2D getOGlTexture2D() const;
1362
1363     virtual int kind() const;
1364     virtual Size size(int i=-1) const;
1365     virtual size_t total(int i=-1) const;
1366     virtual int type(int i=-1) const;
1367     virtual int depth(int i=-1) const;
1368     virtual int channels(int i=-1) const;
1369     virtual bool empty() const;
1370
1371 #ifdef OPENCV_CAN_BREAK_BINARY_COMPATIBILITY
1372     virtual ~_InputArray();
1373 #endif
1374
1375     int flags;
1376     void* obj;
1377     Size sz;
1378 };
1379
1380
1381 enum
1382 {
1383     DEPTH_MASK_8U = 1 << CV_8U,
1384     DEPTH_MASK_8S = 1 << CV_8S,
1385     DEPTH_MASK_16U = 1 << CV_16U,
1386     DEPTH_MASK_16S = 1 << CV_16S,
1387     DEPTH_MASK_32S = 1 << CV_32S,
1388     DEPTH_MASK_32F = 1 << CV_32F,
1389     DEPTH_MASK_64F = 1 << CV_64F,
1390     DEPTH_MASK_ALL = (DEPTH_MASK_64F<<1)-1,
1391     DEPTH_MASK_ALL_BUT_8S = DEPTH_MASK_ALL & ~DEPTH_MASK_8S,
1392     DEPTH_MASK_FLT = DEPTH_MASK_32F + DEPTH_MASK_64F
1393 };
1394
1395
1396 /*!
1397  Proxy datatype for passing Mat's and vector<>'s as input parameters
1398  */
1399 class CV_EXPORTS _OutputArray : public _InputArray
1400 {
1401 public:
1402     _OutputArray();
1403
1404     _OutputArray(Mat& m);
1405     template<typename _Tp> _OutputArray(vector<_Tp>& vec);
1406     template<typename _Tp> _OutputArray(vector<vector<_Tp> >& vec);
1407     _OutputArray(vector<Mat>& vec);
1408     template<typename _Tp> _OutputArray(vector<Mat_<_Tp> >& vec);
1409     template<typename _Tp> _OutputArray(Mat_<_Tp>& m);
1410     template<typename _Tp, int m, int n> _OutputArray(Matx<_Tp, m, n>& matx);
1411     template<typename _Tp> _OutputArray(_Tp* vec, int n);
1412     _OutputArray(gpu::GpuMat& d_mat);
1413     _OutputArray(ogl::Buffer& buf);
1414     _OutputArray(ogl::Texture2D& tex);
1415
1416     _OutputArray(const Mat& m);
1417     template<typename _Tp> _OutputArray(const vector<_Tp>& vec);
1418     template<typename _Tp> _OutputArray(const vector<vector<_Tp> >& vec);
1419     _OutputArray(const vector<Mat>& vec);
1420     template<typename _Tp> _OutputArray(const vector<Mat_<_Tp> >& vec);
1421     template<typename _Tp> _OutputArray(const Mat_<_Tp>& m);
1422     template<typename _Tp, int m, int n> _OutputArray(const Matx<_Tp, m, n>& matx);
1423     template<typename _Tp> _OutputArray(const _Tp* vec, int n);
1424     _OutputArray(const gpu::GpuMat& d_mat);
1425     _OutputArray(const ogl::Buffer& buf);
1426     _OutputArray(const ogl::Texture2D& tex);
1427
1428     virtual bool fixedSize() const;
1429     virtual bool fixedType() const;
1430     virtual bool needed() const;
1431     virtual Mat& getMatRef(int i=-1) const;
1432     /*virtual*/ gpu::GpuMat& getGpuMatRef() const;
1433     /*virtual*/ ogl::Buffer& getOGlBufferRef() const;
1434     /*virtual*/ ogl::Texture2D& getOGlTexture2DRef() const;
1435     virtual void create(Size sz, int type, int i=-1, bool allowTransposed=false, int fixedDepthMask=0) const;
1436     virtual void create(int rows, int cols, int type, int i=-1, bool allowTransposed=false, int fixedDepthMask=0) const;
1437     virtual void create(int dims, const int* size, int type, int i=-1, bool allowTransposed=false, int fixedDepthMask=0) const;
1438     virtual void release() const;
1439     virtual void clear() const;
1440
1441 #ifdef OPENCV_CAN_BREAK_BINARY_COMPATIBILITY
1442     virtual ~_OutputArray();
1443 #endif
1444 };
1445
1446 typedef const _InputArray& InputArray;
1447 typedef InputArray InputArrayOfArrays;
1448 typedef const _OutputArray& OutputArray;
1449 typedef OutputArray OutputArrayOfArrays;
1450 typedef OutputArray InputOutputArray;
1451 typedef OutputArray InputOutputArrayOfArrays;
1452
1453 CV_EXPORTS OutputArray noArray();
1454
1455 /////////////////////////////////////// Mat ///////////////////////////////////////////
1456
1457 enum { MAGIC_MASK=0xFFFF0000, TYPE_MASK=0x00000FFF, DEPTH_MASK=7 };
1458
1459 static inline size_t getElemSize(int type) { return CV_ELEM_SIZE(type); }
1460
1461 /*!
1462    Custom array allocator
1463
1464 */
1465 class CV_EXPORTS MatAllocator
1466 {
1467 public:
1468     MatAllocator() {}
1469     virtual ~MatAllocator() {}
1470     virtual void allocate(int dims, const int* sizes, int type, int*& refcount,
1471                           uchar*& datastart, uchar*& data, size_t* step) = 0;
1472     virtual void deallocate(int* refcount, uchar* datastart, uchar* data) = 0;
1473 };
1474
1475 /*!
1476    The n-dimensional matrix class.
1477
1478    The class represents an n-dimensional dense numerical array that can act as
1479    a matrix, image, optical flow map, 3-focal tensor etc.
1480    It is very similar to CvMat and CvMatND types from earlier versions of OpenCV,
1481    and similarly to those types, the matrix can be multi-channel. It also fully supports ROI mechanism.
1482
1483    There are many different ways to create cv::Mat object. Here are the some popular ones:
1484    <ul>
1485    <li> using cv::Mat::create(nrows, ncols, type) method or
1486      the similar constructor cv::Mat::Mat(nrows, ncols, type[, fill_value]) constructor.
1487      A new matrix of the specified size and specifed type will be allocated.
1488      "type" has the same meaning as in cvCreateMat function,
1489      e.g. CV_8UC1 means 8-bit single-channel matrix, CV_32FC2 means 2-channel (i.e. complex)
1490      floating-point matrix etc:
1491
1492      \code
1493      // make 7x7 complex matrix filled with 1+3j.
1494      cv::Mat M(7,7,CV_32FC2,Scalar(1,3));
1495      // and now turn M to 100x60 15-channel 8-bit matrix.
1496      // The old content will be deallocated
1497      M.create(100,60,CV_8UC(15));
1498      \endcode
1499
1500      As noted in the introduction of this chapter, Mat::create()
1501      will only allocate a new matrix when the current matrix dimensionality
1502      or type are different from the specified.
1503
1504    <li> by using a copy constructor or assignment operator, where on the right side it can
1505      be a matrix or expression, see below. Again, as noted in the introduction,
1506      matrix assignment is O(1) operation because it only copies the header
1507      and increases the reference counter. cv::Mat::clone() method can be used to get a full
1508      (a.k.a. deep) copy of the matrix when you need it.
1509
1510    <li> by constructing a header for a part of another matrix. It can be a single row, single column,
1511      several rows, several columns, rectangular region in the matrix (called a minor in algebra) or
1512      a diagonal. Such operations are also O(1), because the new header will reference the same data.
1513      You can actually modify a part of the matrix using this feature, e.g.
1514
1515      \code
1516      // add 5-th row, multiplied by 3 to the 3rd row
1517      M.row(3) = M.row(3) + M.row(5)*3;
1518
1519      // now copy 7-th column to the 1-st column
1520      // M.col(1) = M.col(7); // this will not work
1521      Mat M1 = M.col(1);
1522      M.col(7).copyTo(M1);
1523
1524      // create new 320x240 image
1525      cv::Mat img(Size(320,240),CV_8UC3);
1526      // select a roi
1527      cv::Mat roi(img, Rect(10,10,100,100));
1528      // fill the ROI with (0,255,0) (which is green in RGB space);
1529      // the original 320x240 image will be modified
1530      roi = Scalar(0,255,0);
1531      \endcode
1532
1533      Thanks to the additional cv::Mat::datastart and cv::Mat::dataend members, it is possible to
1534      compute the relative sub-matrix position in the main "container" matrix using cv::Mat::locateROI():
1535
1536      \code
1537      Mat A = Mat::eye(10, 10, CV_32S);
1538      // extracts A columns, 1 (inclusive) to 3 (exclusive).
1539      Mat B = A(Range::all(), Range(1, 3));
1540      // extracts B rows, 5 (inclusive) to 9 (exclusive).
1541      // that is, C ~ A(Range(5, 9), Range(1, 3))
1542      Mat C = B(Range(5, 9), Range::all());
1543      Size size; Point ofs;
1544      C.locateROI(size, ofs);
1545      // size will be (width=10,height=10) and the ofs will be (x=1, y=5)
1546      \endcode
1547
1548      As in the case of whole matrices, if you need a deep copy, use cv::Mat::clone() method
1549      of the extracted sub-matrices.
1550
1551    <li> by making a header for user-allocated-data. It can be useful for
1552       <ol>
1553       <li> processing "foreign" data using OpenCV (e.g. when you implement
1554          a DirectShow filter or a processing module for gstreamer etc.), e.g.
1555
1556          \code
1557          void process_video_frame(const unsigned char* pixels,
1558                                   int width, int height, int step)
1559          {
1560             cv::Mat img(height, width, CV_8UC3, pixels, step);
1561             cv::GaussianBlur(img, img, cv::Size(7,7), 1.5, 1.5);
1562          }
1563          \endcode
1564
1565       <li> for quick initialization of small matrices and/or super-fast element access
1566
1567          \code
1568          double m[3][3] = {{a, b, c}, {d, e, f}, {g, h, i}};
1569          cv::Mat M = cv::Mat(3, 3, CV_64F, m).inv();
1570          \endcode
1571       </ol>
1572
1573        partial yet very common cases of this "user-allocated data" case are conversions
1574        from CvMat and IplImage to cv::Mat. For this purpose there are special constructors
1575        taking pointers to CvMat or IplImage and the optional
1576        flag indicating whether to copy the data or not.
1577
1578        Backward conversion from cv::Mat to CvMat or IplImage is provided via cast operators
1579        cv::Mat::operator CvMat() an cv::Mat::operator IplImage().
1580        The operators do not copy the data.
1581
1582
1583        \code
1584        IplImage* img = cvLoadImage("greatwave.jpg", 1);
1585        Mat mtx(img); // convert IplImage* -> cv::Mat
1586        CvMat oldmat = mtx; // convert cv::Mat -> CvMat
1587        CV_Assert(oldmat.cols == img->width && oldmat.rows == img->height &&
1588            oldmat.data.ptr == (uchar*)img->imageData && oldmat.step == img->widthStep);
1589        \endcode
1590
1591    <li> by using MATLAB-style matrix initializers, cv::Mat::zeros(), cv::Mat::ones(), cv::Mat::eye(), e.g.:
1592
1593    \code
1594    // create a double-precision identity martix and add it to M.
1595    M += Mat::eye(M.rows, M.cols, CV_64F);
1596    \endcode
1597
1598    <li> by using comma-separated initializer:
1599
1600    \code
1601    // create 3x3 double-precision identity matrix
1602    Mat M = (Mat_<double>(3,3) << 1, 0, 0, 0, 1, 0, 0, 0, 1);
1603    \endcode
1604
1605    here we first call constructor of cv::Mat_ class (that we describe further) with the proper matrix,
1606    and then we just put "<<" operator followed by comma-separated values that can be constants,
1607    variables, expressions etc. Also, note the extra parentheses that are needed to avoid compiler errors.
1608
1609    </ul>
1610
1611    Once matrix is created, it will be automatically managed by using reference-counting mechanism
1612    (unless the matrix header is built on top of user-allocated data,
1613    in which case you should handle the data by yourself).
1614    The matrix data will be deallocated when no one points to it;
1615    if you want to release the data pointed by a matrix header before the matrix destructor is called,
1616    use cv::Mat::release().
1617
1618    The next important thing to learn about the matrix class is element access. Here is how the matrix is stored.
1619    The elements are stored in row-major order (row by row). The cv::Mat::data member points to the first element of the first row,
1620    cv::Mat::rows contains the number of matrix rows and cv::Mat::cols - the number of matrix columns. There is yet another member,
1621    cv::Mat::step that is used to actually compute address of a matrix element. cv::Mat::step is needed because the matrix can be
1622    a part of another matrix or because there can some padding space in the end of each row for a proper alignment.
1623
1624    \image html roi.png
1625
1626    Given these parameters, address of the matrix element M_{ij} is computed as following:
1627
1628    addr(M_{ij})=M.data + M.step*i + j*M.elemSize()
1629
1630    if you know the matrix element type, e.g. it is float, then you can use cv::Mat::at() method:
1631
1632    addr(M_{ij})=&M.at<float>(i,j)
1633
1634    (where & is used to convert the reference returned by cv::Mat::at() to a pointer).
1635    if you need to process a whole row of matrix, the most efficient way is to get
1636    the pointer to the row first, and then just use plain C operator []:
1637
1638    \code
1639    // compute sum of positive matrix elements
1640    // (assuming that M is double-precision matrix)
1641    double sum=0;
1642    for(int i = 0; i < M.rows; i++)
1643    {
1644        const double* Mi = M.ptr<double>(i);
1645        for(int j = 0; j < M.cols; j++)
1646            sum += std::max(Mi[j], 0.);
1647    }
1648    \endcode
1649
1650    Some operations, like the above one, do not actually depend on the matrix shape,
1651    they just process elements of a matrix one by one (or elements from multiple matrices
1652    that are sitting in the same place, e.g. matrix addition). Such operations are called
1653    element-wise and it makes sense to check whether all the input/output matrices are continuous,
1654    i.e. have no gaps in the end of each row, and if yes, process them as a single long row:
1655
1656    \code
1657    // compute sum of positive matrix elements, optimized variant
1658    double sum=0;
1659    int cols = M.cols, rows = M.rows;
1660    if(M.isContinuous())
1661    {
1662        cols *= rows;
1663        rows = 1;
1664    }
1665    for(int i = 0; i < rows; i++)
1666    {
1667        const double* Mi = M.ptr<double>(i);
1668        for(int j = 0; j < cols; j++)
1669            sum += std::max(Mi[j], 0.);
1670    }
1671    \endcode
1672    in the case of continuous matrix the outer loop body will be executed just once,
1673    so the overhead will be smaller, which will be especially noticeable in the case of small matrices.
1674
1675    Finally, there are STL-style iterators that are smart enough to skip gaps between successive rows:
1676    \code
1677    // compute sum of positive matrix elements, iterator-based variant
1678    double sum=0;
1679    MatConstIterator_<double> it = M.begin<double>(), it_end = M.end<double>();
1680    for(; it != it_end; ++it)
1681        sum += std::max(*it, 0.);
1682    \endcode
1683
1684    The matrix iterators are random-access iterators, so they can be passed
1685    to any STL algorithm, including std::sort().
1686 */
1687 class CV_EXPORTS Mat
1688 {
1689 public:
1690     //! default constructor
1691     Mat();
1692     //! constructs 2D matrix of the specified size and type
1693     // (_type is CV_8UC1, CV_64FC3, CV_32SC(12) etc.)
1694     Mat(int rows, int cols, int type);
1695     Mat(Size size, int type);
1696     //! constucts 2D matrix and fills it with the specified value _s.
1697     Mat(int rows, int cols, int type, const Scalar& s);
1698     Mat(Size size, int type, const Scalar& s);
1699
1700     //! constructs n-dimensional matrix
1701     Mat(int ndims, const int* sizes, int type);
1702     Mat(int ndims, const int* sizes, int type, const Scalar& s);
1703
1704     //! copy constructor
1705     Mat(const Mat& m);
1706     //! constructor for matrix headers pointing to user-allocated data
1707     Mat(int rows, int cols, int type, void* data, size_t step=AUTO_STEP);
1708     Mat(Size size, int type, void* data, size_t step=AUTO_STEP);
1709     Mat(int ndims, const int* sizes, int type, void* data, const size_t* steps=0);
1710
1711     //! creates a matrix header for a part of the bigger matrix
1712     Mat(const Mat& m, const Range& rowRange, const Range& colRange=Range::all());
1713     Mat(const Mat& m, const Rect& roi);
1714     Mat(const Mat& m, const Range* ranges);
1715     //! converts old-style CvMat to the new matrix; the data is not copied by default
1716     Mat(const CvMat* m, bool copyData=false);
1717     //! converts old-style CvMatND to the new matrix; the data is not copied by default
1718     Mat(const CvMatND* m, bool copyData=false);
1719     //! converts old-style IplImage to the new matrix; the data is not copied by default
1720     Mat(const IplImage* img, bool copyData=false);
1721     //! builds matrix from std::vector with or without copying the data
1722     template<typename _Tp> explicit Mat(const vector<_Tp>& vec, bool copyData=false);
1723     //! builds matrix from cv::Vec; the data is copied by default
1724     template<typename _Tp, int n> explicit Mat(const Vec<_Tp, n>& vec, bool copyData=true);
1725     //! builds matrix from cv::Matx; the data is copied by default
1726     template<typename _Tp, int m, int n> explicit Mat(const Matx<_Tp, m, n>& mtx, bool copyData=true);
1727     //! builds matrix from a 2D point
1728     template<typename _Tp> explicit Mat(const Point_<_Tp>& pt, bool copyData=true);
1729     //! builds matrix from a 3D point
1730     template<typename _Tp> explicit Mat(const Point3_<_Tp>& pt, bool copyData=true);
1731     //! builds matrix from comma initializer
1732     template<typename _Tp> explicit Mat(const MatCommaInitializer_<_Tp>& commaInitializer);
1733
1734     //! download data from GpuMat
1735     explicit Mat(const gpu::GpuMat& m);
1736
1737     //! destructor - calls release()
1738     ~Mat();
1739     //! assignment operators
1740     Mat& operator = (const Mat& m);
1741     Mat& operator = (const MatExpr& expr);
1742
1743     //! returns a new matrix header for the specified row
1744     Mat row(int y) const;
1745     //! returns a new matrix header for the specified column
1746     Mat col(int x) const;
1747     //! ... for the specified row span
1748     Mat rowRange(int startrow, int endrow) const;
1749     Mat rowRange(const Range& r) const;
1750     //! ... for the specified column span
1751     Mat colRange(int startcol, int endcol) const;
1752     Mat colRange(const Range& r) const;
1753     //! ... for the specified diagonal
1754     // (d=0 - the main diagonal,
1755     //  >0 - a diagonal from the lower half,
1756     //  <0 - a diagonal from the upper half)
1757     Mat diag(int d=0) const;
1758     //! constructs a square diagonal matrix which main diagonal is vector "d"
1759     static Mat diag(const Mat& d);
1760
1761     //! returns deep copy of the matrix, i.e. the data is copied
1762     Mat clone() const;
1763     //! copies the matrix content to "m".
1764     // It calls m.create(this->size(), this->type()).
1765     void copyTo( OutputArray m ) const;
1766     //! copies those matrix elements to "m" that are marked with non-zero mask elements.
1767     void copyTo( OutputArray m, InputArray mask ) const;
1768     //! converts matrix to another datatype with optional scalng. See cvConvertScale.
1769     void convertTo( OutputArray m, int rtype, double alpha=1, double beta=0 ) const;
1770
1771     void assignTo( Mat& m, int type=-1 ) const;
1772
1773     //! sets every matrix element to s
1774     Mat& operator = (const Scalar& s);
1775     //! sets some of the matrix elements to s, according to the mask
1776     Mat& setTo(InputArray value, InputArray mask=noArray());
1777     //! creates alternative matrix header for the same data, with different
1778     // number of channels and/or different number of rows. see cvReshape.
1779     Mat reshape(int cn, int rows=0) const;
1780     Mat reshape(int cn, int newndims, const int* newsz) const;
1781
1782     //! matrix transposition by means of matrix expressions
1783     MatExpr t() const;
1784     //! matrix inversion by means of matrix expressions
1785     MatExpr inv(int method=DECOMP_LU) const;
1786     //! per-element matrix multiplication by means of matrix expressions
1787     MatExpr mul(InputArray m, double scale=1) const;
1788
1789     //! computes cross-product of 2 3D vectors
1790     Mat cross(InputArray m) const;
1791     //! computes dot-product
1792     double dot(InputArray m) const;
1793
1794     //! Matlab-style matrix initialization
1795     static MatExpr zeros(int rows, int cols, int type);
1796     static MatExpr zeros(Size size, int type);
1797     static MatExpr zeros(int ndims, const int* sz, int type);
1798     static MatExpr ones(int rows, int cols, int type);
1799     static MatExpr ones(Size size, int type);
1800     static MatExpr ones(int ndims, const int* sz, int type);
1801     static MatExpr eye(int rows, int cols, int type);
1802     static MatExpr eye(Size size, int type);
1803
1804     //! allocates new matrix data unless the matrix already has specified size and type.
1805     // previous data is unreferenced if needed.
1806     void create(int rows, int cols, int type);
1807     void create(Size size, int type);
1808     void create(int ndims, const int* sizes, int type);
1809
1810     //! increases the reference counter; use with care to avoid memleaks
1811     void addref();
1812     //! decreases reference counter;
1813     // deallocates the data when reference counter reaches 0.
1814     void release();
1815
1816     //! deallocates the matrix data
1817     void deallocate();
1818     //! internal use function; properly re-allocates _size, _step arrays
1819     void copySize(const Mat& m);
1820
1821     //! reserves enough space to fit sz hyper-planes
1822     void reserve(size_t sz);
1823     //! resizes matrix to the specified number of hyper-planes
1824     void resize(size_t sz);
1825     //! resizes matrix to the specified number of hyper-planes; initializes the newly added elements
1826     void resize(size_t sz, const Scalar& s);
1827     //! internal function
1828     void push_back_(const void* elem);
1829     //! adds element to the end of 1d matrix (or possibly multiple elements when _Tp=Mat)
1830     template<typename _Tp> void push_back(const _Tp& elem);
1831     template<typename _Tp> void push_back(const Mat_<_Tp>& elem);
1832     void push_back(const Mat& m);
1833     //! removes several hyper-planes from bottom of the matrix
1834     void pop_back(size_t nelems=1);
1835
1836     //! locates matrix header within a parent matrix. See below
1837     void locateROI( Size& wholeSize, Point& ofs ) const;
1838     //! moves/resizes the current matrix ROI inside the parent matrix.
1839     Mat& adjustROI( int dtop, int dbottom, int dleft, int dright );
1840     //! extracts a rectangular sub-matrix
1841     // (this is a generalized form of row, rowRange etc.)
1842     Mat operator()( Range rowRange, Range colRange ) const;
1843     Mat operator()( const Rect& roi ) const;
1844     Mat operator()( const Range* ranges ) const;
1845
1846     //! converts header to CvMat; no data is copied
1847     operator CvMat() const;
1848     //! converts header to CvMatND; no data is copied
1849     operator CvMatND() const;
1850     //! converts header to IplImage; no data is copied
1851     operator IplImage() const;
1852
1853     template<typename _Tp> operator vector<_Tp>() const;
1854     template<typename _Tp, int n> operator Vec<_Tp, n>() const;
1855     template<typename _Tp, int m, int n> operator Matx<_Tp, m, n>() const;
1856
1857     //! returns true iff the matrix data is continuous
1858     // (i.e. when there are no gaps between successive rows).
1859     // similar to CV_IS_MAT_CONT(cvmat->type)
1860     bool isContinuous() const;
1861
1862     //! returns true if the matrix is a submatrix of another matrix
1863     bool isSubmatrix() const;
1864
1865     //! returns element size in bytes,
1866     // similar to CV_ELEM_SIZE(cvmat->type)
1867     size_t elemSize() const;
1868     //! returns the size of element channel in bytes.
1869     size_t elemSize1() const;
1870     //! returns element type, similar to CV_MAT_TYPE(cvmat->type)
1871     int type() const;
1872     //! returns element type, similar to CV_MAT_DEPTH(cvmat->type)
1873     int depth() const;
1874     //! returns element type, similar to CV_MAT_CN(cvmat->type)
1875     int channels() const;
1876     //! returns step/elemSize1()
1877     size_t step1(int i=0) const;
1878     //! returns true if matrix data is NULL
1879     bool empty() const;
1880     //! returns the total number of matrix elements
1881     size_t total() const;
1882
1883     //! returns N if the matrix is 1-channel (N x ptdim) or ptdim-channel (1 x N) or (N x 1); negative number otherwise
1884     int checkVector(int elemChannels, int depth=-1, bool requireContinuous=true) const;
1885
1886     //! returns pointer to i0-th submatrix along the dimension #0
1887     uchar* ptr(int i0=0);
1888     const uchar* ptr(int i0=0) const;
1889
1890     //! returns pointer to (i0,i1) submatrix along the dimensions #0 and #1
1891     uchar* ptr(int i0, int i1);
1892     const uchar* ptr(int i0, int i1) const;
1893
1894     //! returns pointer to (i0,i1,i3) submatrix along the dimensions #0, #1, #2
1895     uchar* ptr(int i0, int i1, int i2);
1896     const uchar* ptr(int i0, int i1, int i2) const;
1897
1898     //! returns pointer to the matrix element
1899     uchar* ptr(const int* idx);
1900     //! returns read-only pointer to the matrix element
1901     const uchar* ptr(const int* idx) const;
1902
1903     template<int n> uchar* ptr(const Vec<int, n>& idx);
1904     template<int n> const uchar* ptr(const Vec<int, n>& idx) const;
1905
1906     //! template version of the above method
1907     template<typename _Tp> _Tp* ptr(int i0=0);
1908     template<typename _Tp> const _Tp* ptr(int i0=0) const;
1909
1910     template<typename _Tp> _Tp* ptr(int i0, int i1);
1911     template<typename _Tp> const _Tp* ptr(int i0, int i1) const;
1912
1913     template<typename _Tp> _Tp* ptr(int i0, int i1, int i2);
1914     template<typename _Tp> const _Tp* ptr(int i0, int i1, int i2) const;
1915
1916     template<typename _Tp> _Tp* ptr(const int* idx);
1917     template<typename _Tp> const _Tp* ptr(const int* idx) const;
1918
1919     template<typename _Tp, int n> _Tp* ptr(const Vec<int, n>& idx);
1920     template<typename _Tp, int n> const _Tp* ptr(const Vec<int, n>& idx) const;
1921
1922     //! the same as above, with the pointer dereferencing
1923     template<typename _Tp> _Tp& at(int i0=0);
1924     template<typename _Tp> const _Tp& at(int i0=0) const;
1925
1926     template<typename _Tp> _Tp& at(int i0, int i1);
1927     template<typename _Tp> const _Tp& at(int i0, int i1) const;
1928
1929     template<typename _Tp> _Tp& at(int i0, int i1, int i2);
1930     template<typename _Tp> const _Tp& at(int i0, int i1, int i2) const;
1931
1932     template<typename _Tp> _Tp& at(const int* idx);
1933     template<typename _Tp> const _Tp& at(const int* idx) const;
1934
1935     template<typename _Tp, int n> _Tp& at(const Vec<int, n>& idx);
1936     template<typename _Tp, int n> const _Tp& at(const Vec<int, n>& idx) const;
1937
1938     //! special versions for 2D arrays (especially convenient for referencing image pixels)
1939     template<typename _Tp> _Tp& at(Point pt);
1940     template<typename _Tp> const _Tp& at(Point pt) const;
1941
1942     //! template methods for iteration over matrix elements.
1943     // the iterators take care of skipping gaps in the end of rows (if any)
1944     template<typename _Tp> MatIterator_<_Tp> begin();
1945     template<typename _Tp> MatIterator_<_Tp> end();
1946     template<typename _Tp> MatConstIterator_<_Tp> begin() const;
1947     template<typename _Tp> MatConstIterator_<_Tp> end() const;
1948
1949     enum { MAGIC_VAL=0x42FF0000, AUTO_STEP=0, CONTINUOUS_FLAG=CV_MAT_CONT_FLAG, SUBMATRIX_FLAG=CV_SUBMAT_FLAG };
1950
1951     /*! includes several bit-fields:
1952          - the magic signature
1953          - continuity flag
1954          - depth
1955          - number of channels
1956      */
1957     int flags;
1958     //! the matrix dimensionality, >= 2
1959     int dims;
1960     //! the number of rows and columns or (-1, -1) when the matrix has more than 2 dimensions
1961     int rows, cols;
1962     //! pointer to the data
1963     uchar* data;
1964
1965     //! pointer to the reference counter;
1966     // when matrix points to user-allocated data, the pointer is NULL
1967     int* refcount;
1968
1969     //! helper fields used in locateROI and adjustROI
1970     uchar* datastart;
1971     uchar* dataend;
1972     uchar* datalimit;
1973
1974     //! custom allocator
1975     MatAllocator* allocator;
1976
1977     struct CV_EXPORTS MSize
1978     {
1979         MSize(int* _p);
1980         Size operator()() const;
1981         const int& operator[](int i) const;
1982         int& operator[](int i);
1983         operator const int*() const;
1984         bool operator == (const MSize& sz) const;
1985         bool operator != (const MSize& sz) const;
1986
1987         int* p;
1988     };
1989
1990     struct CV_EXPORTS MStep
1991     {
1992         MStep();
1993         MStep(size_t s);
1994         const size_t& operator[](int i) const;
1995         size_t& operator[](int i);
1996         operator size_t() const;
1997         MStep& operator = (size_t s);
1998
1999         size_t* p;
2000         size_t buf[2];
2001     protected:
2002         MStep& operator = (const MStep&);
2003     };
2004
2005     MSize size;
2006     MStep step;
2007
2008 protected:
2009     void initEmpty();
2010 };
2011
2012
2013 /*!
2014    Random Number Generator
2015
2016    The class implements RNG using Multiply-with-Carry algorithm
2017 */
2018 class CV_EXPORTS RNG
2019 {
2020 public:
2021     enum { UNIFORM=0, NORMAL=1 };
2022
2023     RNG();
2024     RNG(uint64 state);
2025     //! updates the state and returns the next 32-bit unsigned integer random number
2026     unsigned next();
2027
2028     operator uchar();
2029     operator schar();
2030     operator ushort();
2031     operator short();
2032     operator unsigned();
2033     //! returns a random integer sampled uniformly from [0, N).
2034     unsigned operator ()(unsigned N);
2035     unsigned operator ()();
2036     operator int();
2037     operator float();
2038     operator double();
2039     //! returns uniformly distributed integer random number from [a,b) range
2040     int uniform(int a, int b);
2041     //! returns uniformly distributed floating-point random number from [a,b) range
2042     float uniform(float a, float b);
2043     //! returns uniformly distributed double-precision floating-point random number from [a,b) range
2044     double uniform(double a, double b);
2045     void fill( InputOutputArray mat, int distType, InputArray a, InputArray b, bool saturateRange=false );
2046     //! returns Gaussian random variate with mean zero.
2047     double gaussian(double sigma);
2048
2049     uint64 state;
2050 };
2051
2052 /*!
2053    Random Number Generator - MT
2054
2055    The class implements RNG using the Mersenne Twister algorithm
2056 */
2057 class CV_EXPORTS RNG_MT19937
2058 {
2059 public:
2060     RNG_MT19937();
2061     RNG_MT19937(unsigned s);
2062     void seed(unsigned s);
2063
2064     unsigned next();
2065
2066     operator int();
2067     operator unsigned();
2068     operator float();
2069     operator double();
2070
2071     unsigned operator ()(unsigned N);
2072     unsigned operator ()();
2073
2074     //! returns uniformly distributed integer random number from [a,b) range
2075     int uniform(int a, int b);
2076     //! returns uniformly distributed floating-point random number from [a,b) range
2077     float uniform(float a, float b);
2078     //! returns uniformly distributed double-precision floating-point random number from [a,b) range
2079     double uniform(double a, double b);
2080
2081 private:
2082     enum PeriodParameters {N = 624, M = 397};
2083     unsigned state[N];
2084     int mti;
2085 };
2086
2087 /*!
2088  Termination criteria in iterative algorithms
2089  */
2090 class CV_EXPORTS TermCriteria
2091 {
2092 public:
2093     enum
2094     {
2095         COUNT=1, //!< the maximum number of iterations or elements to compute
2096         MAX_ITER=COUNT, //!< ditto
2097         EPS=2 //!< the desired accuracy or change in parameters at which the iterative algorithm stops
2098     };
2099
2100     //! default constructor
2101     TermCriteria();
2102     //! full constructor
2103     TermCriteria(int type, int maxCount, double epsilon);
2104     //! conversion from CvTermCriteria
2105     TermCriteria(const CvTermCriteria& criteria);
2106     //! conversion to CvTermCriteria
2107     operator CvTermCriteria() const;
2108
2109     int type; //!< the type of termination criteria: COUNT, EPS or COUNT + EPS
2110     int maxCount; // the maximum number of iterations/elements
2111     double epsilon; // the desired accuracy
2112 };
2113
2114
2115 typedef void (*BinaryFunc)(const uchar* src1, size_t step1,
2116                            const uchar* src2, size_t step2,
2117                            uchar* dst, size_t step, Size sz,
2118                            void*);
2119
2120 CV_EXPORTS BinaryFunc getConvertFunc(int sdepth, int ddepth);
2121 CV_EXPORTS BinaryFunc getConvertScaleFunc(int sdepth, int ddepth);
2122 CV_EXPORTS BinaryFunc getCopyMaskFunc(size_t esz);
2123
2124 //! swaps two matrices
2125 CV_EXPORTS void swap(Mat& a, Mat& b);
2126
2127 //! converts array (CvMat or IplImage) to cv::Mat
2128 CV_EXPORTS Mat cvarrToMat(const CvArr* arr, bool copyData=false,
2129                           bool allowND=true, int coiMode=0);
2130 //! extracts Channel of Interest from CvMat or IplImage and makes cv::Mat out of it.
2131 CV_EXPORTS void extractImageCOI(const CvArr* arr, OutputArray coiimg, int coi=-1);
2132 //! inserts single-channel cv::Mat into a multi-channel CvMat or IplImage
2133 CV_EXPORTS void insertImageCOI(InputArray coiimg, CvArr* arr, int coi=-1);
2134
2135 //! adds one matrix to another (dst = src1 + src2)
2136 CV_EXPORTS_W void add(InputArray src1, InputArray src2, OutputArray dst,
2137                       InputArray mask=noArray(), int dtype=-1);
2138 //! subtracts one matrix from another (dst = src1 - src2)
2139 CV_EXPORTS_W void subtract(InputArray src1, InputArray src2, OutputArray dst,
2140                            InputArray mask=noArray(), int dtype=-1);
2141
2142 //! computes element-wise weighted product of the two arrays (dst = scale*src1*src2)
2143 CV_EXPORTS_W void multiply(InputArray src1, InputArray src2,
2144                            OutputArray dst, double scale=1, int dtype=-1);
2145
2146 //! computes element-wise weighted quotient of the two arrays (dst = scale*src1/src2)
2147 CV_EXPORTS_W void divide(InputArray src1, InputArray src2, OutputArray dst,
2148                          double scale=1, int dtype=-1);
2149
2150 //! computes element-wise weighted reciprocal of an array (dst = scale/src2)
2151 CV_EXPORTS_W void divide(double scale, InputArray src2,
2152                          OutputArray dst, int dtype=-1);
2153
2154 //! adds scaled array to another one (dst = alpha*src1 + src2)
2155 CV_EXPORTS_W void scaleAdd(InputArray src1, double alpha, InputArray src2, OutputArray dst);
2156
2157 //! computes weighted sum of two arrays (dst = alpha*src1 + beta*src2 + gamma)
2158 CV_EXPORTS_W void addWeighted(InputArray src1, double alpha, InputArray src2,
2159                               double beta, double gamma, OutputArray dst, int dtype=-1);
2160
2161 //! scales array elements, computes absolute values and converts the results to 8-bit unsigned integers: dst(i)=saturate_cast<uchar>abs(src(i)*alpha+beta)
2162 CV_EXPORTS_W void convertScaleAbs(InputArray src, OutputArray dst,
2163                                   double alpha=1, double beta=0);
2164 //! transforms array of numbers using a lookup table: dst(i)=lut(src(i))
2165 CV_EXPORTS_W void LUT(InputArray src, InputArray lut, OutputArray dst,
2166                       int interpolation=0);
2167
2168 //! computes sum of array elements
2169 CV_EXPORTS_AS(sumElems) Scalar sum(InputArray src);
2170 //! computes the number of nonzero array elements
2171 CV_EXPORTS_W int countNonZero( InputArray src );
2172 //! returns the list of locations of non-zero pixels
2173 CV_EXPORTS_W void findNonZero( InputArray src, OutputArray idx );
2174
2175 //! computes mean value of selected array elements
2176 CV_EXPORTS_W Scalar mean(InputArray src, InputArray mask=noArray());
2177 //! computes mean value and standard deviation of all or selected array elements
2178 CV_EXPORTS_W void meanStdDev(InputArray src, OutputArray mean, OutputArray stddev,
2179                              InputArray mask=noArray());
2180 //! computes norm of the selected array part
2181 CV_EXPORTS_W double norm(InputArray src1, int normType=NORM_L2, InputArray mask=noArray());
2182 //! computes norm of selected part of the difference between two arrays
2183 CV_EXPORTS_W double norm(InputArray src1, InputArray src2,
2184                          int normType=NORM_L2, InputArray mask=noArray());
2185
2186 //! naive nearest neighbor finder
2187 CV_EXPORTS_W void batchDistance(InputArray src1, InputArray src2,
2188                                 OutputArray dist, int dtype, OutputArray nidx,
2189                                 int normType=NORM_L2, int K=0,
2190                                 InputArray mask=noArray(), int update=0,
2191                                 bool crosscheck=false);
2192
2193 //! scales and shifts array elements so that either the specified norm (alpha) or the minimum (alpha) and maximum (beta) array values get the specified values
2194 CV_EXPORTS_W void normalize( InputArray src, OutputArray dst, double alpha=1, double beta=0,
2195                              int norm_type=NORM_L2, int dtype=-1, InputArray mask=noArray());
2196
2197 //! finds global minimum and maximum array elements and returns their values and their locations
2198 CV_EXPORTS_W void minMaxLoc(InputArray src, CV_OUT double* minVal,
2199                            CV_OUT double* maxVal=0, CV_OUT Point* minLoc=0,
2200                            CV_OUT Point* maxLoc=0, InputArray mask=noArray());
2201 CV_EXPORTS void minMaxIdx(InputArray src, double* minVal, double* maxVal,
2202                           int* minIdx=0, int* maxIdx=0, InputArray mask=noArray());
2203
2204 //! transforms 2D matrix to 1D row or column vector by taking sum, minimum, maximum or mean value over all the rows
2205 CV_EXPORTS_W void reduce(InputArray src, OutputArray dst, int dim, int rtype, int dtype=-1);
2206
2207 //! makes multi-channel array out of several single-channel arrays
2208 CV_EXPORTS void merge(const Mat* mv, size_t count, OutputArray dst);
2209 CV_EXPORTS void merge(const vector<Mat>& mv, OutputArray dst );
2210
2211 //! makes multi-channel array out of several single-channel arrays
2212 CV_EXPORTS_W void merge(InputArrayOfArrays mv, OutputArray dst);
2213
2214 //! copies each plane of a multi-channel array to a dedicated array
2215 CV_EXPORTS void split(const Mat& src, Mat* mvbegin);
2216 CV_EXPORTS void split(const Mat& m, vector<Mat>& mv );
2217
2218 //! copies each plane of a multi-channel array to a dedicated array
2219 CV_EXPORTS_W void split(InputArray m, OutputArrayOfArrays mv);
2220
2221 //! copies selected channels from the input arrays to the selected channels of the output arrays
2222 CV_EXPORTS void mixChannels(const Mat* src, size_t nsrcs, Mat* dst, size_t ndsts,
2223                             const int* fromTo, size_t npairs);
2224 CV_EXPORTS void mixChannels(const vector<Mat>& src, vector<Mat>& dst,
2225                             const int* fromTo, size_t npairs);
2226 CV_EXPORTS_W void mixChannels(InputArrayOfArrays src, InputArrayOfArrays dst,
2227                               const vector<int>& fromTo);
2228
2229 //! extracts a single channel from src (coi is 0-based index)
2230 CV_EXPORTS_W void extractChannel(InputArray src, OutputArray dst, int coi);
2231
2232 //! inserts a single channel to dst (coi is 0-based index)
2233 CV_EXPORTS_W void insertChannel(InputArray src, InputOutputArray dst, int coi);
2234
2235 //! reverses the order of the rows, columns or both in a matrix
2236 CV_EXPORTS_W void flip(InputArray src, OutputArray dst, int flipCode);
2237
2238 //! replicates the input matrix the specified number of times in the horizontal and/or vertical direction
2239 CV_EXPORTS_W void repeat(InputArray src, int ny, int nx, OutputArray dst);
2240 CV_EXPORTS Mat repeat(const Mat& src, int ny, int nx);
2241
2242 CV_EXPORTS void hconcat(const Mat* src, size_t nsrc, OutputArray dst);
2243 CV_EXPORTS void hconcat(InputArray src1, InputArray src2, OutputArray dst);
2244 CV_EXPORTS_W void hconcat(InputArrayOfArrays src, OutputArray dst);
2245
2246 CV_EXPORTS void vconcat(const Mat* src, size_t nsrc, OutputArray dst);
2247 CV_EXPORTS void vconcat(InputArray src1, InputArray src2, OutputArray dst);
2248 CV_EXPORTS_W void vconcat(InputArrayOfArrays src, OutputArray dst);
2249
2250 //! computes bitwise conjunction of the two arrays (dst = src1 & src2)
2251 CV_EXPORTS_W void bitwise_and(InputArray src1, InputArray src2,
2252                               OutputArray dst, InputArray mask=noArray());
2253 //! computes bitwise disjunction of the two arrays (dst = src1 | src2)
2254 CV_EXPORTS_W void bitwise_or(InputArray src1, InputArray src2,
2255                              OutputArray dst, InputArray mask=noArray());
2256 //! computes bitwise exclusive-or of the two arrays (dst = src1 ^ src2)
2257 CV_EXPORTS_W void bitwise_xor(InputArray src1, InputArray src2,
2258                               OutputArray dst, InputArray mask=noArray());
2259 //! inverts each bit of array (dst = ~src)
2260 CV_EXPORTS_W void bitwise_not(InputArray src, OutputArray dst,
2261                               InputArray mask=noArray());
2262 //! computes element-wise absolute difference of two arrays (dst = abs(src1 - src2))
2263 CV_EXPORTS_W void absdiff(InputArray src1, InputArray src2, OutputArray dst);
2264 //! set mask elements for those array elements which are within the element-specific bounding box (dst = lowerb <= src && src < upperb)
2265 CV_EXPORTS_W void inRange(InputArray src, InputArray lowerb,
2266                           InputArray upperb, OutputArray dst);
2267 //! compares elements of two arrays (dst = src1 <cmpop> src2)
2268 CV_EXPORTS_W void compare(InputArray src1, InputArray src2, OutputArray dst, int cmpop);
2269 //! computes per-element minimum of two arrays (dst = min(src1, src2))
2270 CV_EXPORTS_W void min(InputArray src1, InputArray src2, OutputArray dst);
2271 //! computes per-element maximum of two arrays (dst = max(src1, src2))
2272 CV_EXPORTS_W void max(InputArray src1, InputArray src2, OutputArray dst);
2273
2274 //! computes per-element minimum of two arrays (dst = min(src1, src2))
2275 CV_EXPORTS void min(const Mat& src1, const Mat& src2, Mat& dst);
2276 //! computes per-element minimum of array and scalar (dst = min(src1, src2))
2277 CV_EXPORTS void min(const Mat& src1, double src2, Mat& dst);
2278 //! computes per-element maximum of two arrays (dst = max(src1, src2))
2279 CV_EXPORTS void max(const Mat& src1, const Mat& src2, Mat& dst);
2280 //! computes per-element maximum of array and scalar (dst = max(src1, src2))
2281 CV_EXPORTS void max(const Mat& src1, double src2, Mat& dst);
2282
2283 //! computes square root of each matrix element (dst = src**0.5)
2284 CV_EXPORTS_W void sqrt(InputArray src, OutputArray dst);
2285 //! raises the input matrix elements to the specified power (b = a**power)
2286 CV_EXPORTS_W void pow(InputArray src, double power, OutputArray dst);
2287 //! computes exponent of each matrix element (dst = e**src)
2288 CV_EXPORTS_W void exp(InputArray src, OutputArray dst);
2289 //! computes natural logarithm of absolute value of each matrix element: dst = log(abs(src))
2290 CV_EXPORTS_W void log(InputArray src, OutputArray dst);
2291 //! computes cube root of the argument
2292 CV_EXPORTS_W float cubeRoot(float val);
2293 //! computes the angle in degrees (0..360) of the vector (x,y)
2294 CV_EXPORTS_W float fastAtan2(float y, float x);
2295
2296 CV_EXPORTS void exp(const float* src, float* dst, int n);
2297 CV_EXPORTS void log(const float* src, float* dst, int n);
2298 CV_EXPORTS void fastAtan2(const float* y, const float* x, float* dst, int n, bool angleInDegrees);
2299 CV_EXPORTS void magnitude(const float* x, const float* y, float* dst, int n);
2300
2301 //! converts polar coordinates to Cartesian
2302 CV_EXPORTS_W void polarToCart(InputArray magnitude, InputArray angle,
2303                               OutputArray x, OutputArray y, bool angleInDegrees=false);
2304 //! converts Cartesian coordinates to polar
2305 CV_EXPORTS_W void cartToPolar(InputArray x, InputArray y,
2306                               OutputArray magnitude, OutputArray angle,
2307                               bool angleInDegrees=false);
2308 //! computes angle (angle(i)) of each (x(i), y(i)) vector
2309 CV_EXPORTS_W void phase(InputArray x, InputArray y, OutputArray angle,
2310                         bool angleInDegrees=false);
2311 //! computes magnitude (magnitude(i)) of each (x(i), y(i)) vector
2312 CV_EXPORTS_W void magnitude(InputArray x, InputArray y, OutputArray magnitude);
2313 //! checks that each matrix element is within the specified range.
2314 CV_EXPORTS_W bool checkRange(InputArray a, bool quiet=true, CV_OUT Point* pos=0,
2315                             double minVal=-DBL_MAX, double maxVal=DBL_MAX);
2316 //! converts NaN's to the given number
2317 CV_EXPORTS_W void patchNaNs(InputOutputArray a, double val=0);
2318
2319 //! implements generalized matrix product algorithm GEMM from BLAS
2320 CV_EXPORTS_W void gemm(InputArray src1, InputArray src2, double alpha,
2321                        InputArray src3, double gamma, OutputArray dst, int flags=0);
2322 //! multiplies matrix by its transposition from the left or from the right
2323 CV_EXPORTS_W void mulTransposed( InputArray src, OutputArray dst, bool aTa,
2324                                  InputArray delta=noArray(),
2325                                  double scale=1, int dtype=-1 );
2326 //! transposes the matrix
2327 CV_EXPORTS_W void transpose(InputArray src, OutputArray dst);
2328 //! performs affine transformation of each element of multi-channel input matrix
2329 CV_EXPORTS_W void transform(InputArray src, OutputArray dst, InputArray m );
2330 //! performs perspective transformation of each element of multi-channel input matrix
2331 CV_EXPORTS_W void perspectiveTransform(InputArray src, OutputArray dst, InputArray m );
2332
2333 //! extends the symmetrical matrix from the lower half or from the upper half
2334 CV_EXPORTS_W void completeSymm(InputOutputArray mtx, bool lowerToUpper=false);
2335 //! initializes scaled identity matrix
2336 CV_EXPORTS_W void setIdentity(InputOutputArray mtx, const Scalar& s=Scalar(1));
2337 //! computes determinant of a square matrix
2338 CV_EXPORTS_W double determinant(InputArray mtx);
2339 //! computes trace of a matrix
2340 CV_EXPORTS_W Scalar trace(InputArray mtx);
2341 //! computes inverse or pseudo-inverse matrix
2342 CV_EXPORTS_W double invert(InputArray src, OutputArray dst, int flags=DECOMP_LU);
2343 //! solves linear system or a least-square problem
2344 CV_EXPORTS_W bool solve(InputArray src1, InputArray src2,
2345                         OutputArray dst, int flags=DECOMP_LU);
2346
2347 enum
2348 {
2349     SORT_EVERY_ROW=0,
2350     SORT_EVERY_COLUMN=1,
2351     SORT_ASCENDING=0,
2352     SORT_DESCENDING=16
2353 };
2354
2355 //! sorts independently each matrix row or each matrix column
2356 CV_EXPORTS_W void sort(InputArray src, OutputArray dst, int flags);
2357 //! sorts independently each matrix row or each matrix column
2358 CV_EXPORTS_W void sortIdx(InputArray src, OutputArray dst, int flags);
2359 //! finds real roots of a cubic polynomial
2360 CV_EXPORTS_W int solveCubic(InputArray coeffs, OutputArray roots);
2361 //! finds real and complex roots of a polynomial
2362 CV_EXPORTS_W double solvePoly(InputArray coeffs, OutputArray roots, int maxIters=300);
2363 //! finds eigenvalues of a symmetric matrix
2364 CV_EXPORTS bool eigen(InputArray src, OutputArray eigenvalues, int lowindex=-1,
2365                       int highindex=-1);
2366 //! finds eigenvalues and eigenvectors of a symmetric matrix
2367 CV_EXPORTS bool eigen(InputArray src, OutputArray eigenvalues,
2368                       OutputArray eigenvectors,
2369                       int lowindex=-1, int highindex=-1);
2370 CV_EXPORTS_W bool eigen(InputArray src, bool computeEigenvectors,
2371                         OutputArray eigenvalues, OutputArray eigenvectors);
2372
2373 enum
2374 {
2375     COVAR_SCRAMBLED=0,
2376     COVAR_NORMAL=1,
2377     COVAR_USE_AVG=2,
2378     COVAR_SCALE=4,
2379     COVAR_ROWS=8,
2380     COVAR_COLS=16
2381 };
2382
2383 //! computes covariation matrix of a set of samples
2384 CV_EXPORTS void calcCovarMatrix( const Mat* samples, int nsamples, Mat& covar, Mat& mean,
2385                                  int flags, int ctype=CV_64F);
2386 //! computes covariation matrix of a set of samples
2387 CV_EXPORTS_W void calcCovarMatrix( InputArray samples, OutputArray covar,
2388                                    OutputArray mean, int flags, int ctype=CV_64F);
2389
2390 /*!
2391     Principal Component Analysis
2392
2393     The class PCA is used to compute the special basis for a set of vectors.
2394     The basis will consist of eigenvectors of the covariance matrix computed
2395     from the input set of vectors. After PCA is performed, vectors can be transformed from
2396     the original high-dimensional space to the subspace formed by a few most
2397     prominent eigenvectors (called the principal components),
2398     corresponding to the largest eigenvalues of the covariation matrix.
2399     Thus the dimensionality of the vector and the correlation between the coordinates is reduced.
2400
2401     The following sample is the function that takes two matrices. The first one stores the set
2402     of vectors (a row per vector) that is used to compute PCA, the second one stores another
2403     "test" set of vectors (a row per vector) that are first compressed with PCA,
2404     then reconstructed back and then the reconstruction error norm is computed and printed for each vector.
2405
2406     \code
2407     using namespace cv;
2408
2409     PCA compressPCA(const Mat& pcaset, int maxComponents,
2410                     const Mat& testset, Mat& compressed)
2411     {
2412         PCA pca(pcaset, // pass the data
2413                 Mat(), // we do not have a pre-computed mean vector,
2414                        // so let the PCA engine to compute it
2415                 CV_PCA_DATA_AS_ROW, // indicate that the vectors
2416                                     // are stored as matrix rows
2417                                     // (use CV_PCA_DATA_AS_COL if the vectors are
2418                                     // the matrix columns)
2419                 maxComponents // specify, how many principal components to retain
2420                 );
2421         // if there is no test data, just return the computed basis, ready-to-use
2422         if( !testset.data )
2423             return pca;
2424         CV_Assert( testset.cols == pcaset.cols );
2425
2426         compressed.create(testset.rows, maxComponents, testset.type());
2427
2428         Mat reconstructed;
2429         for( int i = 0; i < testset.rows; i++ )
2430         {
2431             Mat vec = testset.row(i), coeffs = compressed.row(i), reconstructed;
2432             // compress the vector, the result will be stored
2433             // in the i-th row of the output matrix
2434             pca.project(vec, coeffs);
2435             // and then reconstruct it
2436             pca.backProject(coeffs, reconstructed);
2437             // and measure the error
2438             printf("%d. diff = %g\n", i, norm(vec, reconstructed, NORM_L2));
2439         }
2440         return pca;
2441     }
2442     \endcode
2443 */
2444 class CV_EXPORTS PCA
2445 {
2446 public:
2447     //! default constructor
2448     PCA();
2449     //! the constructor that performs PCA
2450     PCA(InputArray data, InputArray mean, int flags, int maxComponents=0);
2451     PCA(InputArray data, InputArray mean, int flags, double retainedVariance);
2452     //! operator that performs PCA. The previously stored data, if any, is released
2453     PCA& operator()(InputArray data, InputArray mean, int flags, int maxComponents=0);
2454     PCA& computeVar(InputArray data, InputArray mean, int flags, double retainedVariance);
2455     //! projects vector from the original space to the principal components subspace
2456     Mat project(InputArray vec) const;
2457     //! projects vector from the original space to the principal components subspace
2458     void project(InputArray vec, OutputArray result) const;
2459     //! reconstructs the original vector from the projection
2460     Mat backProject(InputArray vec) const;
2461     //! reconstructs the original vector from the projection
2462     void backProject(InputArray vec, OutputArray result) const;
2463
2464     Mat eigenvectors; //!< eigenvectors of the covariation matrix
2465     Mat eigenvalues; //!< eigenvalues of the covariation matrix
2466     Mat mean; //!< mean value subtracted before the projection and added after the back projection
2467 };
2468
2469 CV_EXPORTS_W void PCACompute(InputArray data, CV_OUT InputOutputArray mean,
2470                              OutputArray eigenvectors, int maxComponents=0);
2471
2472 CV_EXPORTS_W void PCAComputeVar(InputArray data, CV_OUT InputOutputArray mean,
2473                              OutputArray eigenvectors, double retainedVariance);
2474
2475 CV_EXPORTS_W void PCAProject(InputArray data, InputArray mean,
2476                              InputArray eigenvectors, OutputArray result);
2477
2478 CV_EXPORTS_W void PCABackProject(InputArray data, InputArray mean,
2479                                  InputArray eigenvectors, OutputArray result);
2480
2481
2482 /*!
2483     Singular Value Decomposition class
2484
2485     The class is used to compute Singular Value Decomposition of a floating-point matrix and then
2486     use it to solve least-square problems, under-determined linear systems, invert matrices,
2487     compute condition numbers etc.
2488
2489     For a bit faster operation you can pass flags=SVD::MODIFY_A|... to modify the decomposed matrix
2490     when it is not necessarily to preserve it. If you want to compute condition number of a matrix
2491     or absolute value of its determinant - you do not need SVD::u or SVD::vt,
2492     so you can pass flags=SVD::NO_UV|... . Another flag SVD::FULL_UV indicates that the full-size SVD::u and SVD::vt
2493     must be computed, which is not necessary most of the time.
2494 */
2495 class CV_EXPORTS SVD
2496 {
2497 public:
2498     enum { MODIFY_A=1, NO_UV=2, FULL_UV=4 };
2499     //! the default constructor
2500     SVD();
2501     //! the constructor that performs SVD
2502     SVD( InputArray src, int flags=0 );
2503     //! the operator that performs SVD. The previously allocated SVD::u, SVD::w are SVD::vt are released.
2504     SVD& operator ()( InputArray src, int flags=0 );
2505
2506     //! decomposes matrix and stores the results to user-provided matrices
2507     static void compute( InputArray src, OutputArray w,
2508                          OutputArray u, OutputArray vt, int flags=0 );
2509     //! computes singular values of a matrix
2510     static void compute( InputArray src, OutputArray w, int flags=0 );
2511     //! performs back substitution
2512     static void backSubst( InputArray w, InputArray u,
2513                            InputArray vt, InputArray rhs,
2514                            OutputArray dst );
2515
2516     template<typename _Tp, int m, int n, int nm> static void compute( const Matx<_Tp, m, n>& a,
2517         Matx<_Tp, nm, 1>& w, Matx<_Tp, m, nm>& u, Matx<_Tp, n, nm>& vt );
2518     template<typename _Tp, int m, int n, int nm> static void compute( const Matx<_Tp, m, n>& a,
2519         Matx<_Tp, nm, 1>& w );
2520     template<typename _Tp, int m, int n, int nm, int nb> static void backSubst( const Matx<_Tp, nm, 1>& w,
2521         const Matx<_Tp, m, nm>& u, const Matx<_Tp, n, nm>& vt, const Matx<_Tp, m, nb>& rhs, Matx<_Tp, n, nb>& dst );
2522
2523     //! finds dst = arg min_{|dst|=1} |m*dst|
2524     static void solveZ( InputArray src, OutputArray dst );
2525     //! performs back substitution, so that dst is the solution or pseudo-solution of m*dst = rhs, where m is the decomposed matrix
2526     void backSubst( InputArray rhs, OutputArray dst ) const;
2527
2528     Mat u, w, vt;
2529 };
2530
2531 //! computes SVD of src
2532 CV_EXPORTS_W void SVDecomp( InputArray src, CV_OUT OutputArray w,
2533     CV_OUT OutputArray u, CV_OUT OutputArray vt, int flags=0 );
2534
2535 //! performs back substitution for the previously computed SVD
2536 CV_EXPORTS_W void SVBackSubst( InputArray w, InputArray u, InputArray vt,
2537                                InputArray rhs, CV_OUT OutputArray dst );
2538
2539 //! computes Mahalanobis distance between two vectors: sqrt((v1-v2)'*icovar*(v1-v2)), where icovar is the inverse covariation matrix
2540 CV_EXPORTS_W double Mahalanobis(InputArray v1, InputArray v2, InputArray icovar);
2541 //! a synonym for Mahalanobis
2542 CV_EXPORTS double Mahalonobis(InputArray v1, InputArray v2, InputArray icovar);
2543
2544 //! performs forward or inverse 1D or 2D Discrete Fourier Transformation
2545 CV_EXPORTS_W void dft(InputArray src, OutputArray dst, int flags=0, int nonzeroRows=0);
2546 //! performs inverse 1D or 2D Discrete Fourier Transformation
2547 CV_EXPORTS_W void idft(InputArray src, OutputArray dst, int flags=0, int nonzeroRows=0);
2548 //! performs forward or inverse 1D or 2D Discrete Cosine Transformation
2549 CV_EXPORTS_W void dct(InputArray src, OutputArray dst, int flags=0);
2550 //! performs inverse 1D or 2D Discrete Cosine Transformation
2551 CV_EXPORTS_W void idct(InputArray src, OutputArray dst, int flags=0);
2552 //! computes element-wise product of the two Fourier spectrums. The second spectrum can optionally be conjugated before the multiplication
2553 CV_EXPORTS_W void mulSpectrums(InputArray a, InputArray b, OutputArray c,
2554                                int flags, bool conjB=false);
2555 //! computes the minimal vector size vecsize1 >= vecsize so that the dft() of the vector of length vecsize1 can be computed efficiently
2556 CV_EXPORTS_W int getOptimalDFTSize(int vecsize);
2557
2558 /*!
2559  Various k-Means flags
2560 */
2561 enum
2562 {
2563     KMEANS_RANDOM_CENTERS=0, // Chooses random centers for k-Means initialization
2564     KMEANS_PP_CENTERS=2,     // Uses k-Means++ algorithm for initialization
2565     KMEANS_USE_INITIAL_LABELS=1 // Uses the user-provided labels for K-Means initialization
2566 };
2567 //! clusters the input data using k-Means algorithm
2568 CV_EXPORTS_W double kmeans( InputArray data, int K, CV_OUT InputOutputArray bestLabels,
2569                             TermCriteria criteria, int attempts,
2570                             int flags, OutputArray centers=noArray() );
2571
2572 //! returns the thread-local Random number generator
2573 CV_EXPORTS RNG& theRNG();
2574
2575 //! returns the next unifomly-distributed random number of the specified type
2576 template<typename _Tp> static inline _Tp randu() { return (_Tp)theRNG(); }
2577
2578 //! fills array with uniformly-distributed random numbers from the range [low, high)
2579 CV_EXPORTS_W void randu(InputOutputArray dst, InputArray low, InputArray high);
2580
2581 //! fills array with normally-distributed random numbers with the specified mean and the standard deviation
2582 CV_EXPORTS_W void randn(InputOutputArray dst, InputArray mean, InputArray stddev);
2583
2584 //! shuffles the input array elements
2585 CV_EXPORTS void randShuffle(InputOutputArray dst, double iterFactor=1., RNG* rng=0);
2586 CV_EXPORTS_AS(randShuffle) void randShuffle_(InputOutputArray dst, double iterFactor=1.);
2587
2588 //! draws the line segment (pt1, pt2) in the image
2589 CV_EXPORTS_W void line(CV_IN_OUT Mat& img, Point pt1, Point pt2, const Scalar& color,
2590                      int thickness=1, int lineType=8, int shift=0);
2591
2592 //! draws the rectangle outline or a solid rectangle with the opposite corners pt1 and pt2 in the image
2593 CV_EXPORTS_W void rectangle(CV_IN_OUT Mat& img, Point pt1, Point pt2,
2594                           const Scalar& color, int thickness=1,
2595                           int lineType=8, int shift=0);
2596
2597 //! draws the rectangle outline or a solid rectangle covering rec in the image
2598 CV_EXPORTS void rectangle(CV_IN_OUT Mat& img, Rect rec,
2599                           const Scalar& color, int thickness=1,
2600                           int lineType=8, int shift=0);
2601
2602 //! draws the circle outline or a solid circle in the image
2603 CV_EXPORTS_W void circle(CV_IN_OUT Mat& img, Point center, int radius,
2604                        const Scalar& color, int thickness=1,
2605                        int lineType=8, int shift=0);
2606
2607 //! draws an elliptic arc, ellipse sector or a rotated ellipse in the image
2608 CV_EXPORTS_W void ellipse(CV_IN_OUT Mat& img, Point center, Size axes,
2609                         double angle, double startAngle, double endAngle,
2610                         const Scalar& color, int thickness=1,
2611                         int lineType=8, int shift=0);
2612
2613 //! draws a rotated ellipse in the image
2614 CV_EXPORTS_W void ellipse(CV_IN_OUT Mat& img, const RotatedRect& box, const Scalar& color,
2615                         int thickness=1, int lineType=8);
2616
2617 //! draws a filled convex polygon in the image
2618 CV_EXPORTS void fillConvexPoly(Mat& img, const Point* pts, int npts,
2619                                const Scalar& color, int lineType=8,
2620                                int shift=0);
2621 CV_EXPORTS_W void fillConvexPoly(InputOutputArray img, InputArray points,
2622                                  const Scalar& color, int lineType=8,
2623                                  int shift=0);
2624
2625 //! fills an area bounded by one or more polygons
2626 CV_EXPORTS void fillPoly(Mat& img, const Point** pts,
2627                          const int* npts, int ncontours,
2628                          const Scalar& color, int lineType=8, int shift=0,
2629                          Point offset=Point() );
2630
2631 CV_EXPORTS_W void fillPoly(InputOutputArray img, InputArrayOfArrays pts,
2632                            const Scalar& color, int lineType=8, int shift=0,
2633                            Point offset=Point() );
2634
2635 //! draws one or more polygonal curves
2636 CV_EXPORTS void polylines(Mat& img, const Point** pts, const int* npts,
2637                           int ncontours, bool isClosed, const Scalar& color,
2638                           int thickness=1, int lineType=8, int shift=0 );
2639
2640 CV_EXPORTS_W void polylines(InputOutputArray img, InputArrayOfArrays pts,
2641                             bool isClosed, const Scalar& color,
2642                             int thickness=1, int lineType=8, int shift=0 );
2643
2644 //! clips the line segment by the rectangle Rect(0, 0, imgSize.width, imgSize.height)
2645 CV_EXPORTS bool clipLine(Size imgSize, CV_IN_OUT Point& pt1, CV_IN_OUT Point& pt2);
2646
2647 //! clips the line segment by the rectangle imgRect
2648 CV_EXPORTS_W bool clipLine(Rect imgRect, CV_OUT CV_IN_OUT Point& pt1, CV_OUT CV_IN_OUT Point& pt2);
2649
2650 /*!
2651    Line iterator class
2652
2653    The class is used to iterate over all the pixels on the raster line
2654    segment connecting two specified points.
2655 */
2656 class CV_EXPORTS LineIterator
2657 {
2658 public:
2659     //! intializes the iterator
2660     LineIterator( const Mat& img, Point pt1, Point pt2,
2661                   int connectivity=8, bool leftToRight=false );
2662     //! returns pointer to the current pixel
2663     uchar* operator *();
2664     //! prefix increment operator (++it). shifts iterator to the next pixel
2665     LineIterator& operator ++();
2666     //! postfix increment operator (it++). shifts iterator to the next pixel
2667     LineIterator operator ++(int);
2668     //! returns coordinates of the current pixel
2669     Point pos() const;
2670
2671     uchar* ptr;
2672     const uchar* ptr0;
2673     int step, elemSize;
2674     int err, count;
2675     int minusDelta, plusDelta;
2676     int minusStep, plusStep;
2677 };
2678
2679 //! converts elliptic arc to a polygonal curve
2680 CV_EXPORTS_W void ellipse2Poly( Point center, Size axes, int angle,
2681                                 int arcStart, int arcEnd, int delta,
2682                                 CV_OUT vector<Point>& pts );
2683
2684 enum
2685 {
2686     FONT_HERSHEY_SIMPLEX = 0,
2687     FONT_HERSHEY_PLAIN = 1,
2688     FONT_HERSHEY_DUPLEX = 2,
2689     FONT_HERSHEY_COMPLEX = 3,
2690     FONT_HERSHEY_TRIPLEX = 4,
2691     FONT_HERSHEY_COMPLEX_SMALL = 5,
2692     FONT_HERSHEY_SCRIPT_SIMPLEX = 6,
2693     FONT_HERSHEY_SCRIPT_COMPLEX = 7,
2694     FONT_ITALIC = 16
2695 };
2696
2697 //! renders text string in the image
2698 CV_EXPORTS_W void putText( Mat& img, const string& text, Point org,
2699                          int fontFace, double fontScale, Scalar color,
2700                          int thickness=1, int lineType=8,
2701                          bool bottomLeftOrigin=false );
2702
2703 //! returns bounding box of the text string
2704 CV_EXPORTS_W Size getTextSize(const string& text, int fontFace,
2705                             double fontScale, int thickness,
2706                             CV_OUT int* baseLine);
2707
2708 ///////////////////////////////// Mat_<_Tp> ////////////////////////////////////
2709
2710 /*!
2711  Template matrix class derived from Mat
2712
2713  The class Mat_ is a "thin" template wrapper on top of cv::Mat. It does not have any extra data fields,
2714  nor it or cv::Mat have any virtual methods and thus references or pointers to these two classes
2715  can be safely converted one to another. But do it with care, for example:
2716
2717  \code
2718  // create 100x100 8-bit matrix
2719  Mat M(100,100,CV_8U);
2720  // this will compile fine. no any data conversion will be done.
2721  Mat_<float>& M1 = (Mat_<float>&)M;
2722  // the program will likely crash at the statement below
2723  M1(99,99) = 1.f;
2724  \endcode
2725
2726  While cv::Mat is sufficient in most cases, cv::Mat_ can be more convenient if you use a lot of element
2727  access operations and if you know matrix type at compile time.
2728  Note that cv::Mat::at<_Tp>(int y, int x) and cv::Mat_<_Tp>::operator ()(int y, int x) do absolutely the
2729  same thing and run at the same speed, but the latter is certainly shorter:
2730
2731  \code
2732  Mat_<double> M(20,20);
2733  for(int i = 0; i < M.rows; i++)
2734     for(int j = 0; j < M.cols; j++)
2735        M(i,j) = 1./(i+j+1);
2736  Mat E, V;
2737  eigen(M,E,V);
2738  cout << E.at<double>(0,0)/E.at<double>(M.rows-1,0);
2739  \endcode
2740
2741  It is easy to use Mat_ for multi-channel images/matrices - just pass cv::Vec as cv::Mat_ template parameter:
2742
2743  \code
2744  // allocate 320x240 color image and fill it with green (in RGB space)
2745  Mat_<Vec3b> img(240, 320, Vec3b(0,255,0));
2746  // now draw a diagonal white line
2747  for(int i = 0; i < 100; i++)
2748      img(i,i)=Vec3b(255,255,255);
2749  // and now modify the 2nd (red) channel of each pixel
2750  for(int i = 0; i < img.rows; i++)
2751     for(int j = 0; j < img.cols; j++)
2752        img(i,j)[2] ^= (uchar)(i ^ j); // img(y,x)[c] accesses c-th channel of the pixel (x,y)
2753  \endcode
2754 */
2755 template<typename _Tp> class Mat_ : public Mat
2756 {
2757 public:
2758     typedef _Tp value_type;
2759     typedef typename DataType<_Tp>::channel_type channel_type;
2760     typedef MatIterator_<_Tp> iterator;
2761     typedef MatConstIterator_<_Tp> const_iterator;
2762
2763     //! default constructor
2764     Mat_();
2765     //! equivalent to Mat(_rows, _cols, DataType<_Tp>::type)
2766     Mat_(int _rows, int _cols);
2767     //! constructor that sets each matrix element to specified value
2768     Mat_(int _rows, int _cols, const _Tp& value);
2769     //! equivalent to Mat(_size, DataType<_Tp>::type)
2770     explicit Mat_(Size _size);
2771     //! constructor that sets each matrix element to specified value
2772     Mat_(Size _size, const _Tp& value);
2773     //! n-dim array constructor
2774     Mat_(int _ndims, const int* _sizes);
2775     //! n-dim array constructor that sets each matrix element to specified value
2776     Mat_(int _ndims, const int* _sizes, const _Tp& value);
2777     //! copy/conversion contructor. If m is of different type, it's converted
2778     Mat_(const Mat& m);
2779     //! copy constructor
2780     Mat_(const Mat_& m);
2781     //! constructs a matrix on top of user-allocated data. step is in bytes(!!!), regardless of the type
2782     Mat_(int _rows, int _cols, _Tp* _data, size_t _step=AUTO_STEP);
2783     //! constructs n-dim matrix on top of user-allocated data. steps are in bytes(!!!), regardless of the type
2784     Mat_(int _ndims, const int* _sizes, _Tp* _data, const size_t* _steps=0);
2785     //! selects a submatrix
2786     Mat_(const Mat_& m, const Range& rowRange, const Range& colRange=Range::all());
2787     //! selects a submatrix
2788     Mat_(const Mat_& m, const Rect& roi);
2789     //! selects a submatrix, n-dim version
2790     Mat_(const Mat_& m, const Range* ranges);
2791     //! from a matrix expression
2792     explicit Mat_(const MatExpr& e);
2793     //! makes a matrix out of Vec, std::vector, Point_ or Point3_. The matrix will have a single column
2794     explicit Mat_(const vector<_Tp>& vec, bool copyData=false);
2795     template<int n> explicit Mat_(const Vec<typename DataType<_Tp>::channel_type, n>& vec, bool copyData=true);
2796     template<int m, int n> explicit Mat_(const Matx<typename DataType<_Tp>::channel_type, m, n>& mtx, bool copyData=true);
2797     explicit Mat_(const Point_<typename DataType<_Tp>::channel_type>& pt, bool copyData=true);
2798     explicit Mat_(const Point3_<typename DataType<_Tp>::channel_type>& pt, bool copyData=true);
2799     explicit Mat_(const MatCommaInitializer_<_Tp>& commaInitializer);
2800
2801     Mat_& operator = (const Mat& m);
2802     Mat_& operator = (const Mat_& m);
2803     //! set all the elements to s.
2804     Mat_& operator = (const _Tp& s);
2805     //! assign a matrix expression
2806     Mat_& operator = (const MatExpr& e);
2807
2808     //! iterators; they are smart enough to skip gaps in the end of rows
2809     iterator begin();
2810     iterator end();
2811     const_iterator begin() const;
2812     const_iterator end() const;
2813
2814     //! equivalent to Mat::create(_rows, _cols, DataType<_Tp>::type)
2815     void create(int _rows, int _cols);
2816     //! equivalent to Mat::create(_size, DataType<_Tp>::type)
2817     void create(Size _size);
2818     //! equivalent to Mat::create(_ndims, _sizes, DatType<_Tp>::type)
2819     void create(int _ndims, const int* _sizes);
2820     //! cross-product
2821     Mat_ cross(const Mat_& m) const;
2822     //! data type conversion
2823     template<typename T2> operator Mat_<T2>() const;
2824     //! overridden forms of Mat::row() etc.
2825     Mat_ row(int y) const;
2826     Mat_ col(int x) const;
2827     Mat_ diag(int d=0) const;
2828     Mat_ clone() const;
2829
2830     //! overridden forms of Mat::elemSize() etc.
2831     size_t elemSize() const;
2832     size_t elemSize1() const;
2833     int type() const;
2834     int depth() const;
2835     int channels() const;
2836     size_t step1(int i=0) const;
2837     //! returns step()/sizeof(_Tp)
2838     size_t stepT(int i=0) const;
2839
2840     //! overridden forms of Mat::zeros() etc. Data type is omitted, of course
2841     static MatExpr zeros(int rows, int cols);
2842     static MatExpr zeros(Size size);
2843     static MatExpr zeros(int _ndims, const int* _sizes);
2844     static MatExpr ones(int rows, int cols);
2845     static MatExpr ones(Size size);
2846     static MatExpr ones(int _ndims, const int* _sizes);
2847     static MatExpr eye(int rows, int cols);
2848     static MatExpr eye(Size size);
2849
2850     //! some more overriden methods
2851     Mat_& adjustROI( int dtop, int dbottom, int dleft, int dright );
2852     Mat_ operator()( const Range& rowRange, const Range& colRange ) const;
2853     Mat_ operator()( const Rect& roi ) const;
2854     Mat_ operator()( const Range* ranges ) const;
2855
2856     //! more convenient forms of row and element access operators
2857     _Tp* operator [](int y);
2858     const _Tp* operator [](int y) const;
2859
2860     //! returns reference to the specified element
2861     _Tp& operator ()(const int* idx);
2862     //! returns read-only reference to the specified element
2863     const _Tp& operator ()(const int* idx) const;
2864
2865     //! returns reference to the specified element
2866     template<int n> _Tp& operator ()(const Vec<int, n>& idx);
2867     //! returns read-only reference to the specified element
2868     template<int n> const _Tp& operator ()(const Vec<int, n>& idx) const;
2869
2870     //! returns reference to the specified element (1D case)
2871     _Tp& operator ()(int idx0);
2872     //! returns read-only reference to the specified element (1D case)
2873     const _Tp& operator ()(int idx0) const;
2874     //! returns reference to the specified element (2D case)
2875     _Tp& operator ()(int idx0, int idx1);
2876     //! returns read-only reference to the specified element (2D case)
2877     const _Tp& operator ()(int idx0, int idx1) const;
2878     //! returns reference to the specified element (3D case)
2879     _Tp& operator ()(int idx0, int idx1, int idx2);
2880     //! returns read-only reference to the specified element (3D case)
2881     const _Tp& operator ()(int idx0, int idx1, int idx2) const;
2882
2883     _Tp& operator ()(Point pt);
2884     const _Tp& operator ()(Point pt) const;
2885
2886     //! conversion to vector.
2887     operator vector<_Tp>() const;
2888     //! conversion to Vec
2889     template<int n> operator Vec<typename DataType<_Tp>::channel_type, n>() const;
2890     //! conversion to Matx
2891     template<int m, int n> operator Matx<typename DataType<_Tp>::channel_type, m, n>() const;
2892 };
2893
2894 typedef Mat_<uchar> Mat1b;
2895 typedef Mat_<Vec2b> Mat2b;
2896 typedef Mat_<Vec3b> Mat3b;
2897 typedef Mat_<Vec4b> Mat4b;
2898
2899 typedef Mat_<short> Mat1s;
2900 typedef Mat_<Vec2s> Mat2s;
2901 typedef Mat_<Vec3s> Mat3s;
2902 typedef Mat_<Vec4s> Mat4s;
2903
2904 typedef Mat_<ushort> Mat1w;
2905 typedef Mat_<Vec2w> Mat2w;
2906 typedef Mat_<Vec3w> Mat3w;
2907 typedef Mat_<Vec4w> Mat4w;
2908
2909 typedef Mat_<int>   Mat1i;
2910 typedef Mat_<Vec2i> Mat2i;
2911 typedef Mat_<Vec3i> Mat3i;
2912 typedef Mat_<Vec4i> Mat4i;
2913
2914 typedef Mat_<float> Mat1f;
2915 typedef Mat_<Vec2f> Mat2f;
2916 typedef Mat_<Vec3f> Mat3f;
2917 typedef Mat_<Vec4f> Mat4f;
2918
2919 typedef Mat_<double> Mat1d;
2920 typedef Mat_<Vec2d> Mat2d;
2921 typedef Mat_<Vec3d> Mat3d;
2922 typedef Mat_<Vec4d> Mat4d;
2923
2924 //////////// Iterators & Comma initializers //////////////////
2925
2926 class CV_EXPORTS MatConstIterator
2927 {
2928 public:
2929     typedef uchar* value_type;
2930     typedef ptrdiff_t difference_type;
2931     typedef const uchar** pointer;
2932     typedef uchar* reference;
2933     typedef std::random_access_iterator_tag iterator_category;
2934
2935     //! default constructor
2936     MatConstIterator();
2937     //! constructor that sets the iterator to the beginning of the matrix
2938     MatConstIterator(const Mat* _m);
2939     //! constructor that sets the iterator to the specified element of the matrix
2940     MatConstIterator(const Mat* _m, int _row, int _col=0);
2941     //! constructor that sets the iterator to the specified element of the matrix
2942     MatConstIterator(const Mat* _m, Point _pt);
2943     //! constructor that sets the iterator to the specified element of the matrix
2944     MatConstIterator(const Mat* _m, const int* _idx);
2945     //! copy constructor
2946     MatConstIterator(const MatConstIterator& it);
2947
2948     //! copy operator
2949     MatConstIterator& operator = (const MatConstIterator& it);
2950     //! returns the current matrix element
2951     uchar* operator *() const;
2952     //! returns the i-th matrix element, relative to the current
2953     uchar* operator [](ptrdiff_t i) const;
2954
2955     //! shifts the iterator forward by the specified number of elements
2956     MatConstIterator& operator += (ptrdiff_t ofs);
2957     //! shifts the iterator backward by the specified number of elements
2958     MatConstIterator& operator -= (ptrdiff_t ofs);
2959     //! decrements the iterator
2960     MatConstIterator& operator --();
2961     //! decrements the iterator
2962     MatConstIterator operator --(int);
2963     //! increments the iterator
2964     MatConstIterator& operator ++();
2965     //! increments the iterator
2966     MatConstIterator operator ++(int);
2967     //! returns the current iterator position
2968     Point pos() const;
2969     //! returns the current iterator position
2970     void pos(int* _idx) const;
2971     ptrdiff_t lpos() const;
2972     void seek(ptrdiff_t ofs, bool relative=false);
2973     void seek(const int* _idx, bool relative=false);
2974
2975     const Mat* m;
2976     size_t elemSize;
2977     uchar* ptr;
2978     uchar* sliceStart;
2979     uchar* sliceEnd;
2980 };
2981
2982 /*!
2983  Matrix read-only iterator
2984
2985  */
2986 template<typename _Tp>
2987 class MatConstIterator_ : public MatConstIterator
2988 {
2989 public:
2990     typedef _Tp value_type;
2991     typedef ptrdiff_t difference_type;
2992     typedef const _Tp* pointer;
2993     typedef const _Tp& reference;
2994     typedef std::random_access_iterator_tag iterator_category;
2995
2996     //! default constructor
2997     MatConstIterator_();
2998     //! constructor that sets the iterator to the beginning of the matrix
2999     MatConstIterator_(const Mat_<_Tp>* _m);
3000     //! constructor that sets the iterator to the specified element of the matrix
3001     MatConstIterator_(const Mat_<_Tp>* _m, int _row, int _col=0);
3002     //! constructor that sets the iterator to the specified element of the matrix
3003     MatConstIterator_(const Mat_<_Tp>* _m, Point _pt);
3004     //! constructor that sets the iterator to the specified element of the matrix
3005     MatConstIterator_(const Mat_<_Tp>* _m, const int* _idx);
3006     //! copy constructor
3007     MatConstIterator_(const MatConstIterator_& it);
3008
3009     //! copy operator
3010     MatConstIterator_& operator = (const MatConstIterator_& it);
3011     //! returns the current matrix element
3012     _Tp operator *() const;
3013     //! returns the i-th matrix element, relative to the current
3014     _Tp operator [](ptrdiff_t i) const;
3015
3016     //! shifts the iterator forward by the specified number of elements
3017     MatConstIterator_& operator += (ptrdiff_t ofs);
3018     //! shifts the iterator backward by the specified number of elements
3019     MatConstIterator_& operator -= (ptrdiff_t ofs);
3020     //! decrements the iterator
3021     MatConstIterator_& operator --();
3022     //! decrements the iterator
3023     MatConstIterator_ operator --(int);
3024     //! increments the iterator
3025     MatConstIterator_& operator ++();
3026     //! increments the iterator
3027     MatConstIterator_ operator ++(int);
3028     //! returns the current iterator position
3029     Point pos() const;
3030 };
3031
3032
3033 /*!
3034  Matrix read-write iterator
3035
3036 */
3037 template<typename _Tp>
3038 class MatIterator_ : public MatConstIterator_<_Tp>
3039 {
3040 public:
3041     typedef _Tp* pointer;
3042     typedef _Tp& reference;
3043     typedef std::random_access_iterator_tag iterator_category;
3044
3045     //! the default constructor
3046     MatIterator_();
3047     //! constructor that sets the iterator to the beginning of the matrix
3048     MatIterator_(Mat_<_Tp>* _m);
3049     //! constructor that sets the iterator to the specified element of the matrix
3050     MatIterator_(Mat_<_Tp>* _m, int _row, int _col=0);
3051     //! constructor that sets the iterator to the specified element of the matrix
3052     MatIterator_(const Mat_<_Tp>* _m, Point _pt);
3053     //! constructor that sets the iterator to the specified element of the matrix
3054     MatIterator_(const Mat_<_Tp>* _m, const int* _idx);
3055     //! copy constructor
3056     MatIterator_(const MatIterator_& it);
3057     //! copy operator
3058     MatIterator_& operator = (const MatIterator_<_Tp>& it );
3059
3060     //! returns the current matrix element
3061     _Tp& operator *() const;
3062     //! returns the i-th matrix element, relative to the current
3063     _Tp& operator [](ptrdiff_t i) const;
3064
3065     //! shifts the iterator forward by the specified number of elements
3066     MatIterator_& operator += (ptrdiff_t ofs);
3067     //! shifts the iterator backward by the specified number of elements
3068     MatIterator_& operator -= (ptrdiff_t ofs);
3069     //! decrements the iterator
3070     MatIterator_& operator --();
3071     //! decrements the iterator
3072     MatIterator_ operator --(int);
3073     //! increments the iterator
3074     MatIterator_& operator ++();
3075     //! increments the iterator
3076     MatIterator_ operator ++(int);
3077 };
3078
3079 template<typename _Tp> class MatOp_Iter_;
3080
3081 /*!
3082  Comma-separated Matrix Initializer
3083
3084  The class instances are usually not created explicitly.
3085  Instead, they are created on "matrix << firstValue" operator.
3086
3087  The sample below initializes 2x2 rotation matrix:
3088
3089  \code
3090  double angle = 30, a = cos(angle*CV_PI/180), b = sin(angle*CV_PI/180);
3091  Mat R = (Mat_<double>(2,2) << a, -b, b, a);
3092  \endcode
3093 */
3094 template<typename _Tp> class MatCommaInitializer_
3095 {
3096 public:
3097     //! the constructor, created by "matrix << firstValue" operator, where matrix is cv::Mat
3098     MatCommaInitializer_(Mat_<_Tp>* _m);
3099     //! the operator that takes the next value and put it to the matrix
3100     template<typename T2> MatCommaInitializer_<_Tp>& operator , (T2 v);
3101     //! another form of conversion operator
3102     Mat_<_Tp> operator *() const;
3103     operator Mat_<_Tp>() const;
3104 protected:
3105     MatIterator_<_Tp> it;
3106 };
3107
3108
3109 template<typename _Tp, int m, int n> class MatxCommaInitializer
3110 {
3111 public:
3112     MatxCommaInitializer(Matx<_Tp, m, n>* _mtx);
3113     template<typename T2> MatxCommaInitializer<_Tp, m, n>& operator , (T2 val);
3114     Matx<_Tp, m, n> operator *() const;
3115
3116     Matx<_Tp, m, n>* dst;
3117     int idx;
3118 };
3119
3120 template<typename _Tp, int m> class VecCommaInitializer : public MatxCommaInitializer<_Tp, m, 1>
3121 {
3122 public:
3123     VecCommaInitializer(Vec<_Tp, m>* _vec);
3124     template<typename T2> VecCommaInitializer<_Tp, m>& operator , (T2 val);
3125     Vec<_Tp, m> operator *() const;
3126 };
3127
3128 /*!
3129  Automatically Allocated Buffer Class
3130
3131  The class is used for temporary buffers in functions and methods.
3132  If a temporary buffer is usually small (a few K's of memory),
3133  but its size depends on the parameters, it makes sense to create a small
3134  fixed-size array on stack and use it if it's large enough. If the required buffer size
3135  is larger than the fixed size, another buffer of sufficient size is allocated dynamically
3136  and released after the processing. Therefore, in typical cases, when the buffer size is small,
3137  there is no overhead associated with malloc()/free().
3138  At the same time, there is no limit on the size of processed data.
3139
3140  This is what AutoBuffer does. The template takes 2 parameters - type of the buffer elements and
3141  the number of stack-allocated elements. Here is how the class is used:
3142
3143  \code
3144  void my_func(const cv::Mat& m)
3145  {
3146     cv::AutoBuffer<float, 1000> buf; // create automatic buffer containing 1000 floats
3147
3148     buf.allocate(m.rows); // if m.rows <= 1000, the pre-allocated buffer is used,
3149                           // otherwise the buffer of "m.rows" floats will be allocated
3150                           // dynamically and deallocated in cv::AutoBuffer destructor
3151     ...
3152  }
3153  \endcode
3154 */
3155 template<typename _Tp, size_t fixed_size=4096/sizeof(_Tp)+8> class AutoBuffer
3156 {
3157 public:
3158     typedef _Tp value_type;
3159     enum { buffer_padding = (int)((16 + sizeof(_Tp) - 1)/sizeof(_Tp)) };
3160
3161     //! the default contructor
3162     AutoBuffer();
3163     //! constructor taking the real buffer size
3164     AutoBuffer(size_t _size);
3165     //! destructor. calls deallocate()
3166     ~AutoBuffer();
3167
3168     //! allocates the new buffer of size _size. if the _size is small enough, stack-allocated buffer is used
3169     void allocate(size_t _size);
3170     //! deallocates the buffer if it was dynamically allocated
3171     void deallocate();
3172     //! returns pointer to the real buffer, stack-allocated or head-allocated
3173     operator _Tp* ();
3174     //! returns read-only pointer to the real buffer, stack-allocated or head-allocated
3175     operator const _Tp* () const;
3176
3177 protected:
3178     //! pointer to the real buffer, can point to buf if the buffer is small enough
3179     _Tp* ptr;
3180     //! size of the real buffer
3181     size_t size;
3182     //! pre-allocated buffer
3183     _Tp buf[fixed_size+buffer_padding];
3184 };
3185
3186 /////////////////////////// multi-dimensional dense matrix //////////////////////////
3187
3188 /*!
3189  n-Dimensional Dense Matrix Iterator Class.
3190
3191  The class cv::NAryMatIterator is used for iterating over one or more n-dimensional dense arrays (cv::Mat's).
3192
3193  The iterator is completely different from cv::Mat_ and cv::SparseMat_ iterators.
3194  It iterates through the slices (or planes), not the elements, where "slice" is a continuous part of the arrays.
3195
3196  Here is the example on how the iterator can be used to normalize 3D histogram:
3197
3198  \code
3199  void normalizeColorHist(Mat& hist)
3200  {
3201  #if 1
3202      // intialize iterator (the style is different from STL).
3203      // after initialization the iterator will contain
3204      // the number of slices or planes
3205      // the iterator will go through
3206      Mat* arrays[] = { &hist, 0 };
3207      Mat planes[1];
3208      NAryMatIterator it(arrays, planes);
3209      double s = 0;
3210      // iterate through the matrix. on each iteration
3211      // it.planes[i] (of type Mat) will be set to the current plane of
3212      // i-th n-dim matrix passed to the iterator constructor.
3213      for(int p = 0; p < it.nplanes; p++, ++it)
3214         s += sum(it.planes[0])[0];
3215      it = NAryMatIterator(hist);
3216      s = 1./s;
3217      for(int p = 0; p < it.nplanes; p++, ++it)
3218         it.planes[0] *= s;
3219  #elif 1
3220      // this is a shorter implementation of the above
3221      // using built-in operations on Mat
3222      double s = sum(hist)[0];
3223      hist.convertTo(hist, hist.type(), 1./s, 0);
3224  #else
3225      // and this is even shorter one
3226      // (assuming that the histogram elements are non-negative)
3227      normalize(hist, hist, 1, 0, NORM_L1);
3228  #endif
3229  }
3230  \endcode
3231
3232  You can iterate through several matrices simultaneously as long as they have the same geometry
3233  (dimensionality and all the dimension sizes are the same), which is useful for binary