modules/core/include/opencv2/core/mat.hpp

   1 /*M///////////////////////////////////////////////////////////////////////////////////////
   2 //
   3 //  IMPORTANT: READ BEFORE DOWNLOADING, COPYING, INSTALLING OR USING.
   4 //
   5 //  By downloading, copying, installing or using the software you agree to this license.
   6 //  If you do not agree to this license, do not download, install,
   7 //  copy or use the software.
   8 //
   9 //
  10 //                          License Agreement
  11 //                For Open Source Computer Vision Library
  12 //
  13 // Copyright (C) 2000-2008, Intel Corporation, all rights reserved.
  14 // Copyright (C) 2009, Willow Garage Inc., all rights reserved.
  15 // Copyright (C) 2013, OpenCV Foundation, all rights reserved.
  16 // Third party copyrights are property of their respective owners.
  17 //
  18 // Redistribution and use in source and binary forms, with or without modification,
  19 // are permitted provided that the following conditions are met:
  20 //
  21 //   * Redistribution's of source code must retain the above copyright notice,
  22 //     this list of conditions and the following disclaimer.
  23 //
  24 //   * Redistribution's in binary form must reproduce the above copyright notice,
  25 //     this list of conditions and the following disclaimer in the documentation
  26 //     and/or other materials provided with the distribution.
  27 //
  28 //   * The name of the copyright holders may not be used to endorse or promote products
  29 //     derived from this software without specific prior written permission.
  30 //
  31 // This software is provided by the copyright holders and contributors "as is" and
  32 // any express or implied warranties, including, but not limited to, the implied
  33 // warranties of merchantability and fitness for a particular purpose are disclaimed.
  34 // In no event shall the Intel Corporation or contributors be liable for any direct,
  35 // indirect, incidental, special, exemplary, or consequential damages
  36 // (including, but not limited to, procurement of substitute goods or services;
  37 // loss of use, data, or profits; or business interruption) however caused
  38 // and on any theory of liability, whether in contract, strict liability,
  39 // or tort (including negligence or otherwise) arising in any way out of
  40 // the use of this software, even if advised of the possibility of such damage.
  41 //
  42 //M*/
  43
  44 #ifndef __OPENCV_CORE_MAT_HPP__
  45 #define __OPENCV_CORE_MAT_HPP__
  46
  47 #ifndef __cplusplus
  48 #  error mat.hpp header must be compiled as C++
  49 #endif
  50
  51 #include "opencv2/core/matx.hpp"
  52 #include "opencv2/core/types.hpp"
  53
  54 #include "opencv2/core/bufferpool.hpp"
  55
  56 namespace cv
  57 {
  58
  59 enum { ACCESS_READ=1<<24, ACCESS_WRITE=1<<25,
  60     ACCESS_RW=3<<24, ACCESS_MASK=ACCESS_RW, ACCESS_FAST=1<<26 };
  61
  62 class CV_EXPORTS _OutputArray;
  63
  64 //////////////////////// Input/Output Array Arguments /////////////////////////////////
  65
  66 /*!
  67  Proxy datatype for passing Mat's and vector<>'s as input parameters
  68  */
  69 class CV_EXPORTS _InputArray
  70 {
  71 public:
  72     enum {
  73         KIND_SHIFT = 16,
  74         FIXED_TYPE = 0x8000 << KIND_SHIFT,
  75         FIXED_SIZE = 0x4000 << KIND_SHIFT,
  76         KIND_MASK = 31 << KIND_SHIFT,
  77
  78         NONE              = 0 << KIND_SHIFT,
  79         MAT               = 1 << KIND_SHIFT,
  80         MATX              = 2 << KIND_SHIFT,
  81         STD_VECTOR        = 3 << KIND_SHIFT,
  82         STD_VECTOR_VECTOR = 4 << KIND_SHIFT,
  83         STD_VECTOR_MAT    = 5 << KIND_SHIFT,
  84         EXPR              = 6 << KIND_SHIFT,
  85         OPENGL_BUFFER     = 7 << KIND_SHIFT,
  86         CUDA_MEM          = 8 << KIND_SHIFT,
  87         GPU_MAT           = 9 << KIND_SHIFT,
  88         UMAT              =10 << KIND_SHIFT,
  89         STD_VECTOR_UMAT   =11 << KIND_SHIFT
  90     };
  91
  92     _InputArray();
  93     _InputArray(int _flags, void* _obj);
  94     _InputArray(const Mat& m);
  95     _InputArray(const MatExpr& expr);
  96     _InputArray(const std::vector<Mat>& vec);
  97     template<typename _Tp> _InputArray(const Mat_<_Tp>& m);
  98     template<typename _Tp> _InputArray(const std::vector<_Tp>& vec);
  99     template<typename _Tp> _InputArray(const std::vector<std::vector<_Tp> >& vec);
 100     template<typename _Tp> _InputArray(const std::vector<Mat_<_Tp> >& vec);
 101     template<typename _Tp> _InputArray(const _Tp* vec, int n);
 102     template<typename _Tp, int m, int n> _InputArray(const Matx<_Tp, m, n>& matx);
 103     _InputArray(const double& val);
 104     _InputArray(const cuda::GpuMat& d_mat);
 105     _InputArray(const ogl::Buffer& buf);
 106     _InputArray(const cuda::CudaMem& cuda_mem);
 107     template<typename _Tp> _InputArray(const cudev::GpuMat_<_Tp>& m);
 108     _InputArray(const UMat& um);
 109     _InputArray(const std::vector<UMat>& umv);
 110
 111     virtual Mat getMat(int idx=-1) const;
 112     virtual UMat getUMat(int idx=-1) const;
 113     virtual void getMatVector(std::vector<Mat>& mv) const;
 114     virtual void getUMatVector(std::vector<UMat>& umv) const;
 115     virtual cuda::GpuMat getGpuMat() const;
 116     virtual ogl::Buffer getOGlBuffer() const;
 117     void* getObj() const;
 118
 119     virtual int kind() const;
 120     virtual int dims(int i=-1) const;
 121     virtual int cols(int i=-1) const;
 122     virtual int rows(int i=-1) const;
 123     virtual Size size(int i=-1) const;
 124     virtual int sizend(int* sz, int i=-1) const;
 125     virtual bool sameSize(const _InputArray& arr) const;
 126     virtual size_t total(int i=-1) const;
 127     virtual int type(int i=-1) const;
 128     virtual int depth(int i=-1) const;
 129     virtual int channels(int i=-1) const;
 130     virtual bool isContinuous(int i=-1) const;
 131     virtual bool isSubmatrix(int i=-1) const;
 132     virtual bool empty() const;
 133     virtual void copyTo(const _OutputArray& arr) const;
 134     virtual size_t offset(int i=-1) const;
 135     virtual size_t step(int i=-1) const;
 136     bool isMat() const;
 137     bool isUMat() const;
 138     bool isMatVector() const;
 139     bool isUMatVector() const;
 140     bool isMatx() const;
 141
 142     virtual ~_InputArray();
 143
 144 protected:
 145     int flags;
 146     void* obj;
 147     Size sz;
 148
 149     void init(int _flags, const void* _obj);
 150     void init(int _flags, const void* _obj, Size _sz);
 151 };
 152
 153
 154 /*!
 155  Proxy datatype for passing Mat's and vector<>'s as input parameters
 156  */
 157 class CV_EXPORTS _OutputArray : public _InputArray
 158 {
 159 public:
 160     enum
 161     {
 162         DEPTH_MASK_8U = 1 << CV_8U,
 163         DEPTH_MASK_8S = 1 << CV_8S,
 164         DEPTH_MASK_16U = 1 << CV_16U,
 165         DEPTH_MASK_16S = 1 << CV_16S,
 166         DEPTH_MASK_32S = 1 << CV_32S,
 167         DEPTH_MASK_32F = 1 << CV_32F,
 168         DEPTH_MASK_64F = 1 << CV_64F,
 169         DEPTH_MASK_ALL = (DEPTH_MASK_64F<<1)-1,
 170         DEPTH_MASK_ALL_BUT_8S = DEPTH_MASK_ALL & ~DEPTH_MASK_8S,
 171         DEPTH_MASK_FLT = DEPTH_MASK_32F + DEPTH_MASK_64F
 172     };
 173
 174     _OutputArray();
 175     _OutputArray(int _flags, void* _obj);
 176     _OutputArray(Mat& m);
 177     _OutputArray(std::vector<Mat>& vec);
 178     _OutputArray(cuda::GpuMat& d_mat);
 179     _OutputArray(ogl::Buffer& buf);
 180     _OutputArray(cuda::CudaMem& cuda_mem);
 181     template<typename _Tp> _OutputArray(cudev::GpuMat_<_Tp>& m);
 182     template<typename _Tp> _OutputArray(std::vector<_Tp>& vec);
 183     template<typename _Tp> _OutputArray(std::vector<std::vector<_Tp> >& vec);
 184     template<typename _Tp> _OutputArray(std::vector<Mat_<_Tp> >& vec);
 185     template<typename _Tp> _OutputArray(Mat_<_Tp>& m);
 186     template<typename _Tp> _OutputArray(_Tp* vec, int n);
 187     template<typename _Tp, int m, int n> _OutputArray(Matx<_Tp, m, n>& matx);
 188     _OutputArray(UMat& m);
 189     _OutputArray(std::vector<UMat>& vec);
 190
 191     _OutputArray(const Mat& m);
 192     _OutputArray(const std::vector<Mat>& vec);
 193     _OutputArray(const cuda::GpuMat& d_mat);
 194     _OutputArray(const ogl::Buffer& buf);
 195     _OutputArray(const cuda::CudaMem& cuda_mem);
 196     template<typename _Tp> _OutputArray(const cudev::GpuMat_<_Tp>& m);
 197     template<typename _Tp> _OutputArray(const std::vector<_Tp>& vec);
 198     template<typename _Tp> _OutputArray(const std::vector<std::vector<_Tp> >& vec);
 199     template<typename _Tp> _OutputArray(const std::vector<Mat_<_Tp> >& vec);
 200     template<typename _Tp> _OutputArray(const Mat_<_Tp>& m);
 201     template<typename _Tp> _OutputArray(const _Tp* vec, int n);
 202     template<typename _Tp, int m, int n> _OutputArray(const Matx<_Tp, m, n>& matx);
 203     _OutputArray(const UMat& m);
 204     _OutputArray(const std::vector<UMat>& vec);
 205
 206     virtual bool fixedSize() const;
 207     virtual bool fixedType() const;
 208     virtual bool needed() const;
 209     virtual Mat& getMatRef(int i=-1) const;
 210     virtual UMat& getUMatRef(int i=-1) const;
 211     virtual cuda::GpuMat& getGpuMatRef() const;
 212     virtual ogl::Buffer& getOGlBufferRef() const;
 213     virtual cuda::CudaMem& getCudaMemRef() const;
 214     virtual void create(Size sz, int type, int i=-1, bool allowTransposed=false, int fixedDepthMask=0) const;
 215     virtual void create(int rows, int cols, int type, int i=-1, bool allowTransposed=false, int fixedDepthMask=0) const;
 216     virtual void create(int dims, const int* size, int type, int i=-1, bool allowTransposed=false, int fixedDepthMask=0) const;
 217     virtual void createSameSize(const _InputArray& arr, int mtype) const;
 218     virtual void release() const;
 219     virtual void clear() const;
 220     virtual void setTo(const _InputArray& value, const _InputArray & mask = _InputArray()) const;
 221
 222     void assign(const UMat& u) const;
 223     void assign(const Mat& m) const;
 224 };
 225
 226
 227 class CV_EXPORTS _InputOutputArray : public _OutputArray
 228 {
 229 public:
 230     _InputOutputArray();
 231     _InputOutputArray(int _flags, void* _obj);
 232     _InputOutputArray(Mat& m);
 233     _InputOutputArray(std::vector<Mat>& vec);
 234     _InputOutputArray(cuda::GpuMat& d_mat);
 235     _InputOutputArray(ogl::Buffer& buf);
 236     _InputOutputArray(cuda::CudaMem& cuda_mem);
 237     template<typename _Tp> _InputOutputArray(cudev::GpuMat_<_Tp>& m);
 238     template<typename _Tp> _InputOutputArray(std::vector<_Tp>& vec);
 239     template<typename _Tp> _InputOutputArray(std::vector<std::vector<_Tp> >& vec);
 240     template<typename _Tp> _InputOutputArray(std::vector<Mat_<_Tp> >& vec);
 241     template<typename _Tp> _InputOutputArray(Mat_<_Tp>& m);
 242     template<typename _Tp> _InputOutputArray(_Tp* vec, int n);
 243     template<typename _Tp, int m, int n> _InputOutputArray(Matx<_Tp, m, n>& matx);
 244     _InputOutputArray(UMat& m);
 245     _InputOutputArray(std::vector<UMat>& vec);
 246
 247     _InputOutputArray(const Mat& m);
 248     _InputOutputArray(const std::vector<Mat>& vec);
 249     _InputOutputArray(const cuda::GpuMat& d_mat);
 250     _InputOutputArray(const ogl::Buffer& buf);
 251     _InputOutputArray(const cuda::CudaMem& cuda_mem);
 252     template<typename _Tp> _InputOutputArray(const cudev::GpuMat_<_Tp>& m);
 253     template<typename _Tp> _InputOutputArray(const std::vector<_Tp>& vec);
 254     template<typename _Tp> _InputOutputArray(const std::vector<std::vector<_Tp> >& vec);
 255     template<typename _Tp> _InputOutputArray(const std::vector<Mat_<_Tp> >& vec);
 256     template<typename _Tp> _InputOutputArray(const Mat_<_Tp>& m);
 257     template<typename _Tp> _InputOutputArray(const _Tp* vec, int n);
 258     template<typename _Tp, int m, int n> _InputOutputArray(const Matx<_Tp, m, n>& matx);
 259     _InputOutputArray(const UMat& m);
 260     _InputOutputArray(const std::vector<UMat>& vec);
 261 };
 262
 263 typedef const _InputArray& InputArray;
 264 typedef InputArray InputArrayOfArrays;
 265 typedef const _OutputArray& OutputArray;
 266 typedef OutputArray OutputArrayOfArrays;
 267 typedef const _InputOutputArray& InputOutputArray;
 268 typedef InputOutputArray InputOutputArrayOfArrays;
 269
 270 CV_EXPORTS InputOutputArray noArray();
 271
 272 /////////////////////////////////// MatAllocator //////////////////////////////////////
 273
 274 //! Usage flags for allocator
 275 enum UMatUsageFlags
 276 {
 277     USAGE_DEFAULT = 0,
 278
 279     // default allocation policy is platform and usage specific
 280     USAGE_ALLOCATE_HOST_MEMORY = 1 << 0,
 281     USAGE_ALLOCATE_DEVICE_MEMORY = 1 << 1,
 282
 283     __UMAT_USAGE_FLAGS_32BIT = 0x7fffffff // Binary compatibility hint
 284 };
 285
 286 struct CV_EXPORTS UMatData;
 287
 288 /*!
 289    Custom array allocator
 290
 291 */
 292 class CV_EXPORTS MatAllocator
 293 {
 294 public:
 295     MatAllocator() {}
 296     virtual ~MatAllocator() {}
 297
 298     // let's comment it off for now to detect and fix all the uses of allocator
 299     //virtual void allocate(int dims, const int* sizes, int type, int*& refcount,
 300     //                      uchar*& datastart, uchar*& data, size_t* step) = 0;
 301     //virtual void deallocate(int* refcount, uchar* datastart, uchar* data) = 0;
 302     virtual UMatData* allocate(int dims, const int* sizes, int type,
 303                                void* data, size_t* step, int flags, UMatUsageFlags usageFlags) const = 0;
 304     virtual bool allocate(UMatData* data, int accessflags, UMatUsageFlags usageFlags) const = 0;
 305     virtual void deallocate(UMatData* data) const = 0;
 306     virtual void map(UMatData* data, int accessflags) const;
 307     virtual void unmap(UMatData* data) const;
 308     virtual void download(UMatData* data, void* dst, int dims, const size_t sz[],
 309                           const size_t srcofs[], const size_t srcstep[],
 310                           const size_t dststep[]) const;
 311     virtual void upload(UMatData* data, const void* src, int dims, const size_t sz[],
 312                         const size_t dstofs[], const size_t dststep[],
 313                         const size_t srcstep[]) const;
 314     virtual void copy(UMatData* srcdata, UMatData* dstdata, int dims, const size_t sz[],
 315                       const size_t srcofs[], const size_t srcstep[],
 316                       const size_t dstofs[], const size_t dststep[], bool sync) const;
 317
 318     // default implementation returns DummyBufferPoolController
 319     virtual BufferPoolController* getBufferPoolController() const;
 320 };
 321
 322
 323 //////////////////////////////// MatCommaInitializer //////////////////////////////////
 324
 325 /*!
 326  Comma-separated Matrix Initializer
 327
 328  The class instances are usually not created explicitly.
 329  Instead, they are created on "matrix << firstValue" operator.
 330
 331  The sample below initializes 2x2 rotation matrix:
 332
 333  \code
 334  double angle = 30, a = cos(angle*CV_PI/180), b = sin(angle*CV_PI/180);
 335  Mat R = (Mat_<double>(2,2) << a, -b, b, a);
 336  \endcode
 337 */
 338 template<typename _Tp> class MatCommaInitializer_
 339 {
 340 public:
 341     //! the constructor, created by "matrix << firstValue" operator, where matrix is cv::Mat
 342     MatCommaInitializer_(Mat_<_Tp>* _m);
 343     //! the operator that takes the next value and put it to the matrix
 344     template<typename T2> MatCommaInitializer_<_Tp>& operator , (T2 v);
 345     //! another form of conversion operator
 346     operator Mat_<_Tp>() const;
 347 protected:
 348     MatIterator_<_Tp> it;
 349 };
 350
 351
 352 /////////////////////////////////////// Mat ///////////////////////////////////////////
 353
 354 // note that umatdata might be allocated together
 355 // with the matrix data, not as a separate object.
 356 // therefore, it does not have constructor or destructor;
 357 // it should be explicitly initialized using init().
 358 struct CV_EXPORTS UMatData
 359 {
 360     enum { COPY_ON_MAP=1, HOST_COPY_OBSOLETE=2,
 361         DEVICE_COPY_OBSOLETE=4, TEMP_UMAT=8, TEMP_COPIED_UMAT=24,
 362         USER_ALLOCATED=32 };
 363     UMatData(const MatAllocator* allocator);
 364     ~UMatData();
 365
 366     // provide atomic access to the structure
 367     void lock();
 368     void unlock();
 369
 370     bool hostCopyObsolete() const;
 371     bool deviceCopyObsolete() const;
 372     bool copyOnMap() const;
 373     bool tempUMat() const;
 374     bool tempCopiedUMat() const;
 375     void markHostCopyObsolete(bool flag);
 376     void markDeviceCopyObsolete(bool flag);
 377
 378     const MatAllocator* prevAllocator;
 379     const MatAllocator* currAllocator;
 380     int urefcount;
 381     int refcount;
 382     uchar* data;
 383     uchar* origdata;
 384     size_t size, capacity;
 385
 386     int flags;
 387     void* handle;
 388     void* userdata;
 389     int allocatorFlags_;
 390 };
 391
 392
 393 struct CV_EXPORTS UMatDataAutoLock
 394 {
 395     UMatDataAutoLock(UMatData* u);
 396     ~UMatDataAutoLock();
 397     UMatData* u;
 398 };
 399
 400
 401 struct CV_EXPORTS MatSize
 402 {
 403     MatSize(int* _p);
 404     Size operator()() const;
 405     const int& operator[](int i) const;
 406     int& operator[](int i);
 407     operator const int*() const;
 408     bool operator == (const MatSize& sz) const;
 409     bool operator != (const MatSize& sz) const;
 410
 411     int* p;
 412 };
 413
 414 struct CV_EXPORTS MatStep
 415 {
 416     MatStep();
 417     MatStep(size_t s);
 418     const size_t& operator[](int i) const;
 419     size_t& operator[](int i);
 420     operator size_t() const;
 421     MatStep& operator = (size_t s);
 422
 423     size_t* p;
 424     size_t buf[2];
 425 protected:
 426     MatStep& operator = (const MatStep&);
 427 };
 428
 429  /*!
 430    The n-dimensional matrix class.
 431
 432    The class represents an n-dimensional dense numerical array that can act as
 433    a matrix, image, optical flow map, 3-focal tensor etc.
 434    It is very similar to CvMat and CvMatND types from earlier versions of OpenCV,
 435    and similarly to those types, the matrix can be multi-channel. It also fully supports ROI mechanism.
 436
 437    There are many different ways to create cv::Mat object. Here are the some popular ones:
 438    <ul>
 439    <li> using cv::Mat::create(nrows, ncols, type) method or
 440      the similar constructor cv::Mat::Mat(nrows, ncols, type[, fill_value]) constructor.
 441      A new matrix of the specified size and specifed type will be allocated.
 442      "type" has the same meaning as in cvCreateMat function,
 443      e.g. CV_8UC1 means 8-bit single-channel matrix, CV_32FC2 means 2-channel (i.e. complex)
 444      floating-point matrix etc:
 445
 446      \code
 447      // make 7x7 complex matrix filled with 1+3j.
 448      cv::Mat M(7,7,CV_32FC2,Scalar(1,3));
 449      // and now turn M to 100x60 15-channel 8-bit matrix.
 450      // The old content will be deallocated
 451      M.create(100,60,CV_8UC(15));
 452      \endcode
 453
 454      As noted in the introduction of this chapter, Mat::create()
 455      will only allocate a new matrix when the current matrix dimensionality
 456      or type are different from the specified.
 457
 458    <li> by using a copy constructor or assignment operator, where on the right side it can
 459      be a matrix or expression, see below. Again, as noted in the introduction,
 460      matrix assignment is O(1) operation because it only copies the header
 461      and increases the reference counter. cv::Mat::clone() method can be used to get a full
 462      (a.k.a. deep) copy of the matrix when you need it.
 463
 464    <li> by constructing a header for a part of another matrix. It can be a single row, single column,
 465      several rows, several columns, rectangular region in the matrix (called a minor in algebra) or
 466      a diagonal. Such operations are also O(1), because the new header will reference the same data.
 467      You can actually modify a part of the matrix using this feature, e.g.
 468
 469      \code
 470      // add 5-th row, multiplied by 3 to the 3rd row
 471      M.row(3) = M.row(3) + M.row(5)*3;
 472
 473      // now copy 7-th column to the 1-st column
 474      // M.col(1) = M.col(7); // this will not work
 475      Mat M1 = M.col(1);
 476      M.col(7).copyTo(M1);
 477
 478      // create new 320x240 image
 479      cv::Mat img(Size(320,240),CV_8UC3);
 480      // select a roi
 481      cv::Mat roi(img, Rect(10,10,100,100));
 482      // fill the ROI with (0,255,0) (which is green in RGB space);
 483      // the original 320x240 image will be modified
 484      roi = Scalar(0,255,0);
 485      \endcode
 486
 487      Thanks to the additional cv::Mat::datastart and cv::Mat::dataend members, it is possible to
 488      compute the relative sub-matrix position in the main "container" matrix using cv::Mat::locateROI():
 489
 490      \code
 491      Mat A = Mat::eye(10, 10, CV_32S);
 492      // extracts A columns, 1 (inclusive) to 3 (exclusive).
 493      Mat B = A(Range::all(), Range(1, 3));
 494      // extracts B rows, 5 (inclusive) to 9 (exclusive).
 495      // that is, C ~ A(Range(5, 9), Range(1, 3))
 496      Mat C = B(Range(5, 9), Range::all());
 497      Size size; Point ofs;
 498      C.locateROI(size, ofs);
 499      // size will be (width=10,height=10) and the ofs will be (x=1, y=5)
 500      \endcode
 501
 502      As in the case of whole matrices, if you need a deep copy, use cv::Mat::clone() method
 503      of the extracted sub-matrices.
 504
 505    <li> by making a header for user-allocated-data. It can be useful for
 506       <ol>
 507       <li> processing "foreign" data using OpenCV (e.g. when you implement
 508          a DirectShow filter or a processing module for gstreamer etc.), e.g.
 509
 510          \code
 511          void process_video_frame(const unsigned char* pixels,
 512                                   int width, int height, int step)
 513          {
 514             cv::Mat img(height, width, CV_8UC3, pixels, step);
 515             cv::GaussianBlur(img, img, cv::Size(7,7), 1.5, 1.5);
 516          }
 517          \endcode
 518
 519       <li> for quick initialization of small matrices and/or super-fast element access
 520
 521          \code
 522          double m[3][3] = {{a, b, c}, {d, e, f}, {g, h, i}};
 523          cv::Mat M = cv::Mat(3, 3, CV_64F, m).inv();
 524          \endcode
 525       </ol>
 526
 527        partial yet very common cases of this "user-allocated data" case are conversions
 528        from CvMat and IplImage to cv::Mat. For this purpose there are special constructors
 529        taking pointers to CvMat or IplImage and the optional
 530        flag indicating whether to copy the data or not.
 531
 532        Backward conversion from cv::Mat to CvMat or IplImage is provided via cast operators
 533        cv::Mat::operator CvMat() an cv::Mat::operator IplImage().
 534        The operators do not copy the data.
 535
 536
 537        \code
 538        IplImage* img = cvLoadImage("greatwave.jpg", 1);
 539        Mat mtx(img); // convert IplImage* -> cv::Mat
 540        CvMat oldmat = mtx; // convert cv::Mat -> CvMat
 541        CV_Assert(oldmat.cols == img->width && oldmat.rows == img->height &&
 542            oldmat.data.ptr == (uchar*)img->imageData && oldmat.step == img->widthStep);
 543        \endcode
 544
 545    <li> by using MATLAB-style matrix initializers, cv::Mat::zeros(), cv::Mat::ones(), cv::Mat::eye(), e.g.:
 546
 547    \code
 548    // create a double-precision identity martix and add it to M.
 549    M += Mat::eye(M.rows, M.cols, CV_64F);
 550    \endcode
 551
 552    <li> by using comma-separated initializer:
 553
 554    \code
 555    // create 3x3 double-precision identity matrix
 556    Mat M = (Mat_<double>(3,3) << 1, 0, 0, 0, 1, 0, 0, 0, 1);
 557    \endcode
 558
 559    here we first call constructor of cv::Mat_ class (that we describe further) with the proper matrix,
 560    and then we just put "<<" operator followed by comma-separated values that can be constants,
 561    variables, expressions etc. Also, note the extra parentheses that are needed to avoid compiler errors.
 562
 563    </ul>
 564
 565    Once matrix is created, it will be automatically managed by using reference-counting mechanism
 566    (unless the matrix header is built on top of user-allocated data,
 567    in which case you should handle the data by yourself).
 568    The matrix data will be deallocated when no one points to it;
 569    if you want to release the data pointed by a matrix header before the matrix destructor is called,
 570    use cv::Mat::release().
 571
 572    The next important thing to learn about the matrix class is element access. Here is how the matrix is stored.
 573    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,
 574    cv::Mat::rows contains the number of matrix rows and cv::Mat::cols - the number of matrix columns. There is yet another member,
 575    cv::Mat::step that is used to actually compute address of a matrix element. cv::Mat::step is needed because the matrix can be
 576    a part of another matrix or because there can some padding space in the end of each row for a proper alignment.
 577
 578    \image html roi.png
 579
 580    Given these parameters, address of the matrix element M_{ij} is computed as following:
 581
 582    addr(M_{ij})=M.data + M.step*i + j*M.elemSize()
 583
 584    if you know the matrix element type, e.g. it is float, then you can use cv::Mat::at() method:
 585
 586    addr(M_{ij})=&M.at<float>(i,j)
 587
 588    (where & is used to convert the reference returned by cv::Mat::at() to a pointer).
 589    if you need to process a whole row of matrix, the most efficient way is to get
 590    the pointer to the row first, and then just use plain C operator []:
 591
 592    \code
 593    // compute sum of positive matrix elements
 594    // (assuming that M is double-precision matrix)
 595    double sum=0;
 596    for(int i = 0; i < M.rows; i++)
 597    {
 598        const double* Mi = M.ptr<double>(i);
 599        for(int j = 0; j < M.cols; j++)
 600            sum += std::max(Mi[j], 0.);
 601    }
 602    \endcode
 603
 604    Some operations, like the above one, do not actually depend on the matrix shape,
 605    they just process elements of a matrix one by one (or elements from multiple matrices
 606    that are sitting in the same place, e.g. matrix addition). Such operations are called
 607    element-wise and it makes sense to check whether all the input/output matrices are continuous,
 608    i.e. have no gaps in the end of each row, and if yes, process them as a single long row:
 609
 610    \code
 611    // compute sum of positive matrix elements, optimized variant
 612    double sum=0;
 613    int cols = M.cols, rows = M.rows;
 614    if(M.isContinuous())
 615    {
 616        cols *= rows;
 617        rows = 1;
 618    }
 619    for(int i = 0; i < rows; i++)
 620    {
 621        const double* Mi = M.ptr<double>(i);
 622        for(int j = 0; j < cols; j++)
 623            sum += std::max(Mi[j], 0.);
 624    }
 625    \endcode
 626    in the case of continuous matrix the outer loop body will be executed just once,
 627    so the overhead will be smaller, which will be especially noticeable in the case of small matrices.
 628
 629    Finally, there are STL-style iterators that are smart enough to skip gaps between successive rows:
 630    \code
 631    // compute sum of positive matrix elements, iterator-based variant
 632    double sum=0;
 633    MatConstIterator_<double> it = M.begin<double>(), it_end = M.end<double>();
 634    for(; it != it_end; ++it)
 635        sum += std::max(*it, 0.);
 636    \endcode
 637
 638    The matrix iterators are random-access iterators, so they can be passed
 639    to any STL algorithm, including std::sort().
 640 */
 641 class CV_EXPORTS Mat
 642 {
 643 public:
 644     //! default constructor
 645     Mat();
 646     //! constructs 2D matrix of the specified size and type
 647     // (_type is CV_8UC1, CV_64FC3, CV_32SC(12) etc.)
 648     Mat(int rows, int cols, int type);
 649     Mat(Size size, int type);
 650     //! constucts 2D matrix and fills it with the specified value _s.
 651     Mat(int rows, int cols, int type, const Scalar& s);
 652     Mat(Size size, int type, const Scalar& s);
 653
 654     //! constructs n-dimensional matrix
 655     Mat(int ndims, const int* sizes, int type);
 656     Mat(int ndims, const int* sizes, int type, const Scalar& s);
 657
 658     //! copy constructor
 659     Mat(const Mat& m);
 660     //! constructor for matrix headers pointing to user-allocated data
 661     Mat(int rows, int cols, int type, void* data, size_t step=AUTO_STEP);
 662     Mat(Size size, int type, void* data, size_t step=AUTO_STEP);
 663     Mat(int ndims, const int* sizes, int type, void* data, const size_t* steps=0);
 664
 665     //! creates a matrix header for a part of the bigger matrix
 666     Mat(const Mat& m, const Range& rowRange, const Range& colRange=Range::all());
 667     Mat(const Mat& m, const Rect& roi);
 668     Mat(const Mat& m, const Range* ranges);
 669     //! builds matrix from std::vector with or without copying the data
 670     template<typename _Tp> explicit Mat(const std::vector<_Tp>& vec, bool copyData=false);
 671     //! builds matrix from cv::Vec; the data is copied by default
 672     template<typename _Tp, int n> explicit Mat(const Vec<_Tp, n>& vec, bool copyData=true);
 673     //! builds matrix from cv::Matx; the data is copied by default
 674     template<typename _Tp, int m, int n> explicit Mat(const Matx<_Tp, m, n>& mtx, bool copyData=true);
 675     //! builds matrix from a 2D point
 676     template<typename _Tp> explicit Mat(const Point_<_Tp>& pt, bool copyData=true);
 677     //! builds matrix from a 3D point
 678     template<typename _Tp> explicit Mat(const Point3_<_Tp>& pt, bool copyData=true);
 679     //! builds matrix from comma initializer
 680     template<typename _Tp> explicit Mat(const MatCommaInitializer_<_Tp>& commaInitializer);
 681
 682     //! download data from GpuMat
 683     explicit Mat(const cuda::GpuMat& m);
 684
 685     //! destructor - calls release()
 686     ~Mat();
 687     //! assignment operators
 688     Mat& operator = (const Mat& m);
 689     Mat& operator = (const MatExpr& expr);
 690
 691     //! retrieve UMat from Mat
 692     UMat getUMat(int accessFlags, UMatUsageFlags usageFlags = USAGE_DEFAULT) const;
 693
 694     //! returns a new matrix header for the specified row
 695     Mat row(int y) const;
 696     //! returns a new matrix header for the specified column
 697     Mat col(int x) const;
 698     //! ... for the specified row span
 699     Mat rowRange(int startrow, int endrow) const;
 700     Mat rowRange(const Range& r) const;
 701     //! ... for the specified column span
 702     Mat colRange(int startcol, int endcol) const;
 703     Mat colRange(const Range& r) const;
 704     //! ... for the specified diagonal
 705     // (d=0 - the main diagonal,
 706     //  >0 - a diagonal from the lower half,
 707     //  <0 - a diagonal from the upper half)
 708     Mat diag(int d=0) const;
 709     //! constructs a square diagonal matrix which main diagonal is vector "d"
 710     static Mat diag(const Mat& d);
 711
 712     //! returns deep copy of the matrix, i.e. the data is copied
 713     Mat clone() const;
 714     //! copies the matrix content to "m".
 715     // It calls m.create(this->size(), this->type()).
 716     void copyTo( OutputArray m ) const;
 717     //! copies those matrix elements to "m" that are marked with non-zero mask elements.
 718     void copyTo( OutputArray m, InputArray mask ) const;
 719     //! converts matrix to another datatype with optional scalng. See cvConvertScale.
 720     void convertTo( OutputArray m, int rtype, double alpha=1, double beta=0 ) const;
 721
 722     void assignTo( Mat& m, int type=-1 ) const;
 723
 724     //! sets every matrix element to s
 725     Mat& operator = (const Scalar& s);
 726     //! sets some of the matrix elements to s, according to the mask
 727     Mat& setTo(InputArray value, InputArray mask=noArray());
 728     //! creates alternative matrix header for the same data, with different
 729     // number of channels and/or different number of rows. see cvReshape.
 730     Mat reshape(int cn, int rows=0) const;
 731     Mat reshape(int cn, int newndims, const int* newsz) const;
 732
 733     //! matrix transposition by means of matrix expressions
 734     MatExpr t() const;
 735     //! matrix inversion by means of matrix expressions
 736     MatExpr inv(int method=DECOMP_LU) const;
 737     //! per-element matrix multiplication by means of matrix expressions
 738     MatExpr mul(InputArray m, double scale=1) const;
 739
 740     //! computes cross-product of 2 3D vectors
 741     Mat cross(InputArray m) const;
 742     //! computes dot-product
 743     double dot(InputArray m) const;
 744
 745     //! Matlab-style matrix initialization
 746     static MatExpr zeros(int rows, int cols, int type);
 747     static MatExpr zeros(Size size, int type);
 748     static MatExpr zeros(int ndims, const int* sz, int type);
 749     static MatExpr ones(int rows, int cols, int type);
 750     static MatExpr ones(Size size, int type);
 751     static MatExpr ones(int ndims, const int* sz, int type);
 752     static MatExpr eye(int rows, int cols, int type);
 753     static MatExpr eye(Size size, int type);
 754
 755     //! allocates new matrix data unless the matrix already has specified size and type.
 756     // previous data is unreferenced if needed.
 757     void create(int rows, int cols, int type);
 758     void create(Size size, int type);
 759     void create(int ndims, const int* sizes, int type);
 760
 761     //! increases the reference counter; use with care to avoid memleaks
 762     void addref();
 763     //! decreases reference counter;
 764     // deallocates the data when reference counter reaches 0.
 765     void release();
 766
 767     //! deallocates the matrix data
 768     void deallocate();
 769     //! internal use function; properly re-allocates _size, _step arrays
 770     void copySize(const Mat& m);
 771
 772     //! reserves enough space to fit sz hyper-planes
 773     void reserve(size_t sz);
 774     //! resizes matrix to the specified number of hyper-planes
 775     void resize(size_t sz);
 776     //! resizes matrix to the specified number of hyper-planes; initializes the newly added elements
 777     void resize(size_t sz, const Scalar& s);
 778     //! internal function
 779     void push_back_(const void* elem);
 780     //! adds element to the end of 1d matrix (or possibly multiple elements when _Tp=Mat)
 781     template<typename _Tp> void push_back(const _Tp& elem);
 782     template<typename _Tp> void push_back(const Mat_<_Tp>& elem);
 783     void push_back(const Mat& m);
 784     //! removes several hyper-planes from bottom of the matrix
 785     void pop_back(size_t nelems=1);
 786
 787     //! locates matrix header within a parent matrix. See below
 788     void locateROI( Size& wholeSize, Point& ofs ) const;
 789     //! moves/resizes the current matrix ROI inside the parent matrix.
 790     Mat& adjustROI( int dtop, int dbottom, int dleft, int dright );
 791     //! extracts a rectangular sub-matrix
 792     // (this is a generalized form of row, rowRange etc.)
 793     Mat operator()( Range rowRange, Range colRange ) const;
 794     Mat operator()( const Rect& roi ) const;
 795     Mat operator()( const Range* ranges ) const;
 796
 797     // //! converts header to CvMat; no data is copied
 798     // operator CvMat() const;
 799     // //! converts header to CvMatND; no data is copied
 800     // operator CvMatND() const;
 801     // //! converts header to IplImage; no data is copied
 802     // operator IplImage() const;
 803
 804     template<typename _Tp> operator std::vector<_Tp>() const;
 805     template<typename _Tp, int n> operator Vec<_Tp, n>() const;
 806     template<typename _Tp, int m, int n> operator Matx<_Tp, m, n>() const;
 807
 808     //! returns true iff the matrix data is continuous
 809     // (i.e. when there are no gaps between successive rows).
 810     // similar to CV_IS_MAT_CONT(cvmat->type)
 811     bool isContinuous() const;
 812
 813     //! returns true if the matrix is a submatrix of another matrix
 814     bool isSubmatrix() const;
 815
 816     //! returns element size in bytes,
 817     // similar to CV_ELEM_SIZE(cvmat->type)
 818     size_t elemSize() const;
 819     //! returns the size of element channel in bytes.
 820     size_t elemSize1() const;
 821     //! returns element type, similar to CV_MAT_TYPE(cvmat->type)
 822     int type() const;
 823     //! returns element type, similar to CV_MAT_DEPTH(cvmat->type)
 824     int depth() const;
 825     //! returns element type, similar to CV_MAT_CN(cvmat->type)
 826     int channels() const;
 827     //! returns step/elemSize1()
 828     size_t step1(int i=0) const;
 829     //! returns true if matrix data is NULL
 830     bool empty() const;
 831     //! returns the total number of matrix elements
 832     size_t total() const;
 833
 834     //! returns N if the matrix is 1-channel (N x ptdim) or ptdim-channel (1 x N) or (N x 1); negative number otherwise
 835     int checkVector(int elemChannels, int depth=-1, bool requireContinuous=true) const;
 836
 837     //! returns pointer to i0-th submatrix along the dimension #0
 838     uchar* ptr(int i0=0);
 839     const uchar* ptr(int i0=0) const;
 840
 841     //! returns pointer to (i0,i1) submatrix along the dimensions #0 and #1
 842     uchar* ptr(int i0, int i1);
 843     const uchar* ptr(int i0, int i1) const;
 844
 845     //! returns pointer to (i0,i1,i3) submatrix along the dimensions #0, #1, #2
 846     uchar* ptr(int i0, int i1, int i2);
 847     const uchar* ptr(int i0, int i1, int i2) const;
 848
 849     //! returns pointer to the matrix element
 850     uchar* ptr(const int* idx);
 851     //! returns read-only pointer to the matrix element
 852     const uchar* ptr(const int* idx) const;
 853
 854     template<int n> uchar* ptr(const Vec<int, n>& idx);
 855     template<int n> const uchar* ptr(const Vec<int, n>& idx) const;
 856
 857     //! template version of the above method
 858     template<typename _Tp> _Tp* ptr(int i0=0);
 859     template<typename _Tp> const _Tp* ptr(int i0=0) const;
 860
 861     template<typename _Tp> _Tp* ptr(int i0, int i1);
 862     template<typename _Tp> const _Tp* ptr(int i0, int i1) const;
 863
 864     template<typename _Tp> _Tp* ptr(int i0, int i1, int i2);
 865     template<typename _Tp> const _Tp* ptr(int i0, int i1, int i2) const;
 866
 867     template<typename _Tp> _Tp* ptr(const int* idx);
 868     template<typename _Tp> const _Tp* ptr(const int* idx) const;
 869
 870     template<typename _Tp, int n> _Tp* ptr(const Vec<int, n>& idx);
 871     template<typename _Tp, int n> const _Tp* ptr(const Vec<int, n>& idx) const;
 872
 873     //! the same as above, with the pointer dereferencing
 874     template<typename _Tp> _Tp& at(int i0=0);
 875     template<typename _Tp> const _Tp& at(int i0=0) const;
 876
 877     template<typename _Tp> _Tp& at(int i0, int i1);
 878     template<typename _Tp> const _Tp& at(int i0, int i1) const;
 879
 880     template<typename _Tp> _Tp& at(int i0, int i1, int i2);
 881     template<typename _Tp> const _Tp& at(int i0, int i1, int i2) const;
 882
 883     template<typename _Tp> _Tp& at(const int* idx);
 884     template<typename _Tp> const _Tp& at(const int* idx) const;
 885
 886     template<typename _Tp, int n> _Tp& at(const Vec<int, n>& idx);
 887     template<typename _Tp, int n> const _Tp& at(const Vec<int, n>& idx) const;
 888
 889     //! special versions for 2D arrays (especially convenient for referencing image pixels)
 890     template<typename _Tp> _Tp& at(Point pt);
 891     template<typename _Tp> const _Tp& at(Point pt) const;
 892
 893     //! template methods for iteration over matrix elements.
 894     // the iterators take care of skipping gaps in the end of rows (if any)
 895     template<typename _Tp> MatIterator_<_Tp> begin();
 896     template<typename _Tp> MatIterator_<_Tp> end();
 897     template<typename _Tp> MatConstIterator_<_Tp> begin() const;
 898     template<typename _Tp> MatConstIterator_<_Tp> end() const;
 899
 900     enum { MAGIC_VAL  = 0x42FF0000, AUTO_STEP = 0, CONTINUOUS_FLAG = CV_MAT_CONT_FLAG, SUBMATRIX_FLAG = CV_SUBMAT_FLAG };
 901     enum { MAGIC_MASK = 0xFFFF0000, TYPE_MASK = 0x00000FFF, DEPTH_MASK = 7 };
 902
 903     /*! includes several bit-fields:
 904          - the magic signature
 905          - continuity flag
 906          - depth
 907          - number of channels
 908      */
 909     int flags;
 910     //! the matrix dimensionality, >= 2
 911     int dims;
 912     //! the number of rows and columns or (-1, -1) when the matrix has more than 2 dimensions
 913     int rows, cols;
 914     //! pointer to the data
 915     uchar* data;
 916
 917     //! helper fields used in locateROI and adjustROI
 918     uchar* datastart;
 919     uchar* dataend;
 920     uchar* datalimit;
 921
 922     //! custom allocator
 923     MatAllocator* allocator;
 924     //! and the standard allocator
 925     static MatAllocator* getStdAllocator();
 926
 927     //! interaction with UMat
 928     UMatData* u;
 929
 930     MatSize size;
 931     MatStep step;
 932
 933 protected:
 934 };
 935
 936
 937 ///////////////////////////////// Mat_<_Tp> ////////////////////////////////////
 938
 939 /*!
 940  Template matrix class derived from Mat
 941
 942  The class Mat_ is a "thin" template wrapper on top of cv::Mat. It does not have any extra data fields,
 943  nor it or cv::Mat have any virtual methods and thus references or pointers to these two classes
 944  can be safely converted one to another. But do it with care, for example:
 945
 946  \code
 947  // create 100x100 8-bit matrix
 948  Mat M(100,100,CV_8U);
 949  // this will compile fine. no any data conversion will be done.
 950  Mat_<float>& M1 = (Mat_<float>&)M;
 951  // the program will likely crash at the statement below
 952  M1(99,99) = 1.f;
 953  \endcode
 954
 955  While cv::Mat is sufficient in most cases, cv::Mat_ can be more convenient if you use a lot of element
 956  access operations and if you know matrix type at compile time.
 957  Note that cv::Mat::at<_Tp>(int y, int x) and cv::Mat_<_Tp>::operator ()(int y, int x) do absolutely the
 958  same thing and run at the same speed, but the latter is certainly shorter:
 959
 960  \code
 961  Mat_<double> M(20,20);
 962  for(int i = 0; i < M.rows; i++)
 963     for(int j = 0; j < M.cols; j++)
 964        M(i,j) = 1./(i+j+1);
 965  Mat E, V;
 966  eigen(M,E,V);
 967  cout << E.at<double>(0,0)/E.at<double>(M.rows-1,0);
 968  \endcode
 969
 970  It is easy to use Mat_ for multi-channel images/matrices - just pass cv::Vec as cv::Mat_ template parameter:
 971
 972  \code
 973  // allocate 320x240 color image and fill it with green (in RGB space)
 974  Mat_<Vec3b> img(240, 320, Vec3b(0,255,0));
 975  // now draw a diagonal white line
 976  for(int i = 0; i < 100; i++)
 977      img(i,i)=Vec3b(255,255,255);
 978  // and now modify the 2nd (red) channel of each pixel
 979  for(int i = 0; i < img.rows; i++)
 980     for(int j = 0; j < img.cols; j++)
 981        img(i,j)[2] ^= (uchar)(i ^ j); // img(y,x)[c] accesses c-th channel of the pixel (x,y)
 982  \endcode
 983 */
 984 template<typename _Tp> class Mat_ : public Mat
 985 {
 986 public:
 987     typedef _Tp value_type;
 988     typedef typename DataType<_Tp>::channel_type channel_type;
 989     typedef MatIterator_<_Tp> iterator;
 990     typedef MatConstIterator_<_Tp> const_iterator;
 991
 992     //! default constructor
 993     Mat_();
 994     //! equivalent to Mat(_rows, _cols, DataType<_Tp>::type)
 995     Mat_(int _rows, int _cols);
 996     //! constructor that sets each matrix element to specified value
 997     Mat_(int _rows, int _cols, const _Tp& value);
 998     //! equivalent to Mat(_size, DataType<_Tp>::type)
 999     explicit Mat_(Size _size);
1000     //! constructor that sets each matrix element to specified value
1001     Mat_(Size _size, const _Tp& value);
1002     //! n-dim array constructor
1003     Mat_(int _ndims, const int* _sizes);
1004     //! n-dim array constructor that sets each matrix element to specified value
1005     Mat_(int _ndims, const int* _sizes, const _Tp& value);
1006     //! copy/conversion contructor. If m is of different type, it's converted
1007     Mat_(const Mat& m);
1008     //! copy constructor
1009     Mat_(const Mat_& m);
1010     //! constructs a matrix on top of user-allocated data. step is in bytes(!!!), regardless of the type
1011     Mat_(int _rows, int _cols, _Tp* _data, size_t _step=AUTO_STEP);
1012     //! constructs n-dim matrix on top of user-allocated data. steps are in bytes(!!!), regardless of the type
1013     Mat_(int _ndims, const int* _sizes, _Tp* _data, const size_t* _steps=0);
1014     //! selects a submatrix
1015     Mat_(const Mat_& m, const Range& rowRange, const Range& colRange=Range::all());
1016     //! selects a submatrix
1017     Mat_(const Mat_& m, const Rect& roi);
1018     //! selects a submatrix, n-dim version
1019     Mat_(const Mat_& m, const Range* ranges);
1020     //! from a matrix expression
1021     explicit Mat_(const MatExpr& e);
1022     //! makes a matrix out of Vec, std::vector, Point_ or Point3_. The matrix will have a single column
1023     explicit Mat_(const std::vector<_Tp>& vec, bool copyData=false);
1024     template<int n> explicit Mat_(const Vec<typename DataType<_Tp>::channel_type, n>& vec, bool copyData=true);
1025     template<int m, int n> explicit Mat_(const Matx<typename DataType<_Tp>::channel_type, m, n>& mtx, bool copyData=true);
1026     explicit Mat_(const Point_<typename DataType<_Tp>::channel_type>& pt, bool copyData=true);
1027     explicit Mat_(const Point3_<typename DataType<_Tp>::channel_type>& pt, bool copyData=true);
1028     explicit Mat_(const MatCommaInitializer_<_Tp>& commaInitializer);
1029
1030     Mat_& operator = (const Mat& m);
1031     Mat_& operator = (const Mat_& m);
1032     //! set all the elements to s.
1033     Mat_& operator = (const _Tp& s);
1034     //! assign a matrix expression
1035     Mat_& operator = (const MatExpr& e);
1036
1037     //! iterators; they are smart enough to skip gaps in the end of rows
1038     iterator begin();
1039     iterator end();
1040     const_iterator begin() const;
1041     const_iterator end() const;
1042
1043     //! equivalent to Mat::create(_rows, _cols, DataType<_Tp>::type)
1044     void create(int _rows, int _cols);
1045     //! equivalent to Mat::create(_size, DataType<_Tp>::type)
1046     void create(Size _size);
1047     //! equivalent to Mat::create(_ndims, _sizes, DatType<_Tp>::type)
1048     void create(int _ndims, const int* _sizes);
1049     //! cross-product
1050     Mat_ cross(const Mat_& m) const;
1051     //! data type conversion
1052     template<typename T2> operator Mat_<T2>() const;
1053     //! overridden forms of Mat::row() etc.
1054     Mat_ row(int y) const;
1055     Mat_ col(int x) const;
1056     Mat_ diag(int d=0) const;
1057     Mat_ clone() const;
1058
1059     //! overridden forms of Mat::elemSize() etc.
1060     size_t elemSize() const;
1061     size_t elemSize1() const;
1062     int type() const;
1063     int depth() const;
1064     int channels() const;
1065     size_t step1(int i=0) const;
1066     //! returns step()/sizeof(_Tp)
1067     size_t stepT(int i=0) const;
1068
1069     //! overridden forms of Mat::zeros() etc. Data type is omitted, of course
1070     static MatExpr zeros(int rows, int cols);
1071     static MatExpr zeros(Size size);
1072     static MatExpr zeros(int _ndims, const int* _sizes);
1073     static MatExpr ones(int rows, int cols);
1074     static MatExpr ones(Size size);
1075     static MatExpr ones(int _ndims, const int* _sizes);
1076     static MatExpr eye(int rows, int cols);
1077     static MatExpr eye(Size size);
1078
1079     //! some more overriden methods
1080     Mat_& adjustROI( int dtop, int dbottom, int dleft, int dright );
1081     Mat_ operator()( const Range& rowRange, const Range& colRange ) const;
1082     Mat_ operator()( const Rect& roi ) const;
1083     Mat_ operator()( const Range* ranges ) const;
1084
1085     //! more convenient forms of row and element access operators
1086     _Tp* operator [](int y);
1087     const _Tp* operator [](int y) const;
1088
1089     //! returns reference to the specified element
1090     _Tp& operator ()(const int* idx);
1091     //! returns read-only reference to the specified element
1092     const _Tp& operator ()(const int* idx) const;
1093
1094     //! returns reference to the specified element
1095     template<int n> _Tp& operator ()(const Vec<int, n>& idx);
1096     //! returns read-only reference to the specified element
1097     template<int n> const _Tp& operator ()(const Vec<int, n>& idx) const;
1098
1099     //! returns reference to the specified element (1D case)
1100     _Tp& operator ()(int idx0);
1101     //! returns read-only reference to the specified element (1D case)
1102     const _Tp& operator ()(int idx0) const;
1103     //! returns reference to the specified element (2D case)
1104     _Tp& operator ()(int idx0, int idx1);
1105     //! returns read-only reference to the specified element (2D case)
1106     const _Tp& operator ()(int idx0, int idx1) const;
1107     //! returns reference to the specified element (3D case)
1108     _Tp& operator ()(int idx0, int idx1, int idx2);
1109     //! returns read-only reference to the specified element (3D case)
1110     const _Tp& operator ()(int idx0, int idx1, int idx2) const;
1111
1112     _Tp& operator ()(Point pt);
1113     const _Tp& operator ()(Point pt) const;
1114
1115     //! conversion to vector.
1116     operator std::vector<_Tp>() const;
1117     //! conversion to Vec
1118     template<int n> operator Vec<typename DataType<_Tp>::channel_type, n>() const;
1119     //! conversion to Matx
1120     template<int m, int n> operator Matx<typename DataType<_Tp>::channel_type, m, n>() const;
1121 };
1122
1123 typedef Mat_<uchar> Mat1b;
1124 typedef Mat_<Vec2b> Mat2b;
1125 typedef Mat_<Vec3b> Mat3b;
1126 typedef Mat_<Vec4b> Mat4b;
1127
1128 typedef Mat_<short> Mat1s;
1129 typedef Mat_<Vec2s> Mat2s;
1130 typedef Mat_<Vec3s> Mat3s;
1131 typedef Mat_<Vec4s> Mat4s;
1132
1133 typedef Mat_<ushort> Mat1w;
1134 typedef Mat_<Vec2w> Mat2w;
1135 typedef Mat_<Vec3w> Mat3w;
1136 typedef Mat_<Vec4w> Mat4w;
1137
1138 typedef Mat_<int>   Mat1i;
1139 typedef Mat_<Vec2i> Mat2i;
1140 typedef Mat_<Vec3i> Mat3i;
1141 typedef Mat_<Vec4i> Mat4i;
1142
1143 typedef Mat_<float> Mat1f;
1144 typedef Mat_<Vec2f> Mat2f;
1145 typedef Mat_<Vec3f> Mat3f;
1146 typedef Mat_<Vec4f> Mat4f;
1147
1148 typedef Mat_<double> Mat1d;
1149 typedef Mat_<Vec2d> Mat2d;
1150 typedef Mat_<Vec3d> Mat3d;
1151 typedef Mat_<Vec4d> Mat4d;
1152
1153 class CV_EXPORTS UMat
1154 {
1155 public:
1156     //! default constructor
1157     UMat(UMatUsageFlags usageFlags = USAGE_DEFAULT);
1158     //! constructs 2D matrix of the specified size and type
1159     // (_type is CV_8UC1, CV_64FC3, CV_32SC(12) etc.)
1160     UMat(int rows, int cols, int type, UMatUsageFlags usageFlags = USAGE_DEFAULT);
1161     UMat(Size size, int type, UMatUsageFlags usageFlags = USAGE_DEFAULT);
1162     //! constucts 2D matrix and fills it with the specified value _s.
1163     UMat(int rows, int cols, int type, const Scalar& s, UMatUsageFlags usageFlags = USAGE_DEFAULT);
1164     UMat(Size size, int type, const Scalar& s, UMatUsageFlags usageFlags = USAGE_DEFAULT);
1165
1166     //! constructs n-dimensional matrix
1167     UMat(int ndims, const int* sizes, int type, UMatUsageFlags usageFlags = USAGE_DEFAULT);
1168     UMat(int ndims, const int* sizes, int type, const Scalar& s, UMatUsageFlags usageFlags = USAGE_DEFAULT);
1169
1170     //! copy constructor
1171     UMat(const UMat& m);
1172
1173     //! creates a matrix header for a part of the bigger matrix
1174     UMat(const UMat& m, const Range& rowRange, const Range& colRange=Range::all());
1175     UMat(const UMat& m, const Rect& roi);
1176     UMat(const UMat& m, const Range* ranges);
1177     //! builds matrix from std::vector with or without copying the data
1178     template<typename _Tp> explicit UMat(const std::vector<_Tp>& vec, bool copyData=false);
1179     //! builds matrix from cv::Vec; the data is copied by default
1180     template<typename _Tp, int n> explicit UMat(const Vec<_Tp, n>& vec, bool copyData=true);
1181     //! builds matrix from cv::Matx; the data is copied by default
1182     template<typename _Tp, int m, int n> explicit UMat(const Matx<_Tp, m, n>& mtx, bool copyData=true);
1183     //! builds matrix from a 2D point
1184     template<typename _Tp> explicit UMat(const Point_<_Tp>& pt, bool copyData=true);
1185     //! builds matrix from a 3D point
1186     template<typename _Tp> explicit UMat(const Point3_<_Tp>& pt, bool copyData=true);
1187     //! builds matrix from comma initializer
1188     template<typename _Tp> explicit UMat(const MatCommaInitializer_<_Tp>& commaInitializer);
1189
1190     //! destructor - calls release()
1191     ~UMat();
1192     //! assignment operators
1193     UMat& operator = (const UMat& m);
1194
1195     Mat getMat(int flags) const;
1196
1197     //! returns a new matrix header for the specified row
1198     UMat row(int y) const;
1199     //! returns a new matrix header for the specified column
1200     UMat col(int x) const;
1201     //! ... for the specified row span
1202     UMat rowRange(int startrow, int endrow) const;
1203     UMat rowRange(const Range& r) const;
1204     //! ... for the specified column span
1205     UMat colRange(int startcol, int endcol) const;
1206     UMat colRange(const Range& r) const;
1207     //! ... for the specified diagonal
1208     // (d=0 - the main diagonal,
1209     //  >0 - a diagonal from the lower half,
1210     //  <0 - a diagonal from the upper half)
1211     UMat diag(int d=0) const;
1212     //! constructs a square diagonal matrix which main diagonal is vector "d"
1213     static UMat diag(const UMat& d);
1214
1215     //! returns deep copy of the matrix, i.e. the data is copied
1216     UMat clone() const;
1217     //! copies the matrix content to "m".
1218     // It calls m.create(this->size(), this->type()).
1219     void copyTo( OutputArray m ) const;
1220     //! copies those matrix elements to "m" that are marked with non-zero mask elements.
1221     void copyTo( OutputArray m, InputArray mask ) const;
1222     //! converts matrix to another datatype with optional scalng. See cvConvertScale.
1223     void convertTo( OutputArray m, int rtype, double alpha=1, double beta=0 ) const;
1224
1225     void assignTo( UMat& m, int type=-1 ) const;
1226
1227     //! sets every matrix element to s
1228     UMat& operator = (const Scalar& s);
1229     //! sets some of the matrix elements to s, according to the mask
1230     UMat& setTo(InputArray value, InputArray mask=noArray());
1231     //! creates alternative matrix header for the same data, with different
1232     // number of channels and/or different number of rows. see cvReshape.
1233     UMat reshape(int cn, int rows=0) const;
1234     UMat reshape(int cn, int newndims, const int* newsz) const;
1235
1236     //! matrix transposition by means of matrix expressions
1237     UMat t() const;
1238     //! matrix inversion by means of matrix expressions
1239     UMat inv(int method=DECOMP_LU) const;
1240     //! per-element matrix multiplication by means of matrix expressions
1241     UMat mul(InputArray m, double scale=1) const;
1242
1243     //! computes dot-product
1244     double dot(InputArray m) const;
1245
1246     //! Matlab-style matrix initialization
1247     static UMat zeros(int rows, int cols, int type);
1248     static UMat zeros(Size size, int type);
1249     static UMat zeros(int ndims, const int* sz, int type);
1250     static UMat ones(int rows, int cols, int type);
1251     static UMat ones(Size size, int type);
1252     static UMat ones(int ndims, const int* sz, int type);
1253     static UMat eye(int rows, int cols, int type);
1254     static UMat eye(Size size, int type);
1255
1256     //! allocates new matrix data unless the matrix already has specified size and type.
1257     // previous data is unreferenced if needed.
1258     void create(int rows, int cols, int type, UMatUsageFlags usageFlags = USAGE_DEFAULT);
1259     void create(Size size, int type, UMatUsageFlags usageFlags = USAGE_DEFAULT);
1260     void create(int ndims, const int* sizes, int type, UMatUsageFlags usageFlags = USAGE_DEFAULT);
1261
1262     //! increases the reference counter; use with care to avoid memleaks
1263     void addref();
1264     //! decreases reference counter;
1265     // deallocates the data when reference counter reaches 0.
1266     void release();
1267
1268     //! deallocates the matrix data
1269     void deallocate();
1270     //! internal use function; properly re-allocates _size, _step arrays
1271     void copySize(const UMat& m);
1272
1273     //! locates matrix header within a parent matrix. See below
1274     void locateROI( Size& wholeSize, Point& ofs ) const;
1275     //! moves/resizes the current matrix ROI inside the parent matrix.
1276     UMat& adjustROI( int dtop, int dbottom, int dleft, int dright );
1277     //! extracts a rectangular sub-matrix
1278     // (this is a generalized form of row, rowRange etc.)
1279     UMat operator()( Range rowRange, Range colRange ) const;
1280     UMat operator()( const Rect& roi ) const;
1281     UMat operator()( const Range* ranges ) const;
1282
1283     //! returns true iff the matrix data is continuous
1284     // (i.e. when there are no gaps between successive rows).
1285     // similar to CV_IS_MAT_CONT(cvmat->type)
1286     bool isContinuous() const;
1287
1288     //! returns true if the matrix is a submatrix of another matrix
1289     bool isSubmatrix() const;
1290
1291     //! returns element size in bytes,
1292     // similar to CV_ELEM_SIZE(cvmat->type)
1293     size_t elemSize() const;
1294     //! returns the size of element channel in bytes.
1295     size_t elemSize1() const;
1296     //! returns element type, similar to CV_MAT_TYPE(cvmat->type)
1297     int type() const;
1298     //! returns element type, similar to CV_MAT_DEPTH(cvmat->type)
1299     int depth() const;
1300     //! returns element type, similar to CV_MAT_CN(cvmat->type)
1301     int channels() const;
1302     //! returns step/elemSize1()
1303     size_t step1(int i=0) const;
1304     //! returns true if matrix data is NULL
1305     bool empty() const;
1306     //! returns the total number of matrix elements
1307     size_t total() const;
1308
1309     //! returns N if the matrix is 1-channel (N x ptdim) or ptdim-channel (1 x N) or (N x 1); negative number otherwise
1310     int checkVector(int elemChannels, int depth=-1, bool requireContinuous=true) const;
1311
1312     void* handle(int accessFlags) const;
1313     void ndoffset(size_t* ofs) const;
1314
1315     enum { MAGIC_VAL  = 0x42FF0000, AUTO_STEP = 0, CONTINUOUS_FLAG = CV_MAT_CONT_FLAG, SUBMATRIX_FLAG = CV_SUBMAT_FLAG };
1316     enum { MAGIC_MASK = 0xFFFF0000, TYPE_MASK = 0x00000FFF, DEPTH_MASK = 7 };
1317
1318     /*! includes several bit-fields:
1319          - the magic signature
1320          - continuity flag
1321          - depth
1322          - number of channels
1323      */
1324     int flags;
1325     //! the matrix dimensionality, >= 2
1326     int dims;
1327     //! the number of rows and columns or (-1, -1) when the matrix has more than 2 dimensions
1328     int rows, cols;
1329
1330     //! custom allocator
1331     MatAllocator* allocator;
1332     UMatUsageFlags usageFlags; // usage flags for allocator
1333     //! and the standard allocator
1334     static MatAllocator* getStdAllocator();
1335
1336     // black-box container of UMat data
1337     UMatData* u;
1338
1339     // offset of the submatrix (or 0)
1340     size_t offset;
1341
1342     MatSize size;
1343     MatStep step;
1344
1345 protected:
1346 };
1347
1348
1349 /////////////////////////// multi-dimensional sparse matrix //////////////////////////
1350
1351 /*!
1352  Sparse matrix class.
1353
1354  The class represents multi-dimensional sparse numerical arrays. Such a sparse array can store elements
1355  of any type that cv::Mat is able to store. "Sparse" means that only non-zero elements
1356  are stored (though, as a result of some operations on a sparse matrix, some of its stored elements
1357  can actually become 0. It's user responsibility to detect such elements and delete them using cv::SparseMat::erase().
1358  The non-zero elements are stored in a hash table that grows when it's filled enough,
1359  so that the search time remains O(1) in average. Elements can be accessed using the following methods:
1360
1361  <ol>
1362  <li>Query operations: cv::SparseMat::ptr() and the higher-level cv::SparseMat::ref(),
1363       cv::SparseMat::value() and cv::SparseMat::find, for example:
1364  \code
1365  const int dims = 5;
1366  int size[] = {10, 10, 10, 10, 10};
1367  SparseMat sparse_mat(dims, size, CV_32F);
1368  for(int i = 0; i < 1000; i++)
1369  {
1370      int idx[dims];
1371      for(int k = 0; k < dims; k++)
1372         idx[k] = rand()%sparse_mat.size(k);
1373      sparse_mat.ref<float>(idx) += 1.f;
1374  }
1375  \endcode
1376
1377  <li>Sparse matrix iterators. Like cv::Mat iterators and unlike cv::Mat iterators, the sparse matrix iterators are STL-style,
1378  that is, the iteration is done as following:
1379  \code
1380  // prints elements of a sparse floating-point matrix and the sum of elements.
1381  SparseMatConstIterator_<float>
1382         it = sparse_mat.begin<float>(),
1383         it_end = sparse_mat.end<float>();
1384  double s = 0;
1385  int dims = sparse_mat.dims();
1386  for(; it != it_end; ++it)
1387  {
1388      // print element indices and the element value
1389      const Node* n = it.node();
1390      printf("(")
1391      for(int i = 0; i < dims; i++)
1392         printf("%3d%c", n->idx[i], i < dims-1 ? ',' : ')');
1393      printf(": %f\n", *it);
1394      s += *it;
1395  }
1396  printf("Element sum is %g\n", s);
1397  \endcode
1398  If you run this loop, you will notice that elements are enumerated
1399  in no any logical order (lexicographical etc.),
1400  they come in the same order as they stored in the hash table, i.e. semi-randomly.
1401
1402  You may collect pointers to the nodes and sort them to get the proper ordering.
1403  Note, however, that pointers to the nodes may become invalid when you add more
1404  elements to the matrix; this is because of possible buffer reallocation.
1405
1406  <li>A combination of the above 2 methods when you need to process 2 or more sparse
1407  matrices simultaneously, e.g. this is how you can compute unnormalized
1408  cross-correlation of the 2 floating-point sparse matrices:
1409  \code
1410  double crossCorr(const SparseMat& a, const SparseMat& b)
1411  {
1412      const SparseMat *_a = &a, *_b = &b;
1413      // if b contains less elements than a,
1414      // it's faster to iterate through b
1415      if(_a->nzcount() > _b->nzcount())
1416         std::swap(_a, _b);
1417      SparseMatConstIterator_<float> it = _a->begin<float>(),
1418                                     it_end = _a->end<float>();
1419      double ccorr = 0;
1420      for(; it != it_end; ++it)
1421      {
1422          // take the next element from the first matrix
1423          float avalue = *it;
1424          const Node* anode = it.node();
1425          // and try to find element with the same index in the second matrix.
1426          // since the hash value depends only on the element index,
1427          // we reuse hashvalue stored in the node
1428          float bvalue = _b->value<float>(anode->idx,&anode->hashval);
1429          ccorr += avalue*bvalue;
1430      }
1431      return ccorr;
1432  }
1433  \endcode
1434  </ol>
1435 */
1436 class CV_EXPORTS SparseMat
1437 {
1438 public:
1439     typedef SparseMatIterator iterator;
1440     typedef SparseMatConstIterator const_iterator;
1441
1442     enum { MAGIC_VAL=0x42FD0000, MAX_DIM=32, HASH_SCALE=0x5bd1e995, HASH_BIT=0x80000000 };
1443
1444     //! the sparse matrix header
1445     struct CV_EXPORTS Hdr
1446     {
1447         Hdr(int _dims, const int* _sizes, int _type);
1448         void clear();
1449         int refcount;
1450         int dims;
1451         int valueOffset;
1452         size_t nodeSize;
1453         size_t nodeCount;
1454         size_t freeList;
1455         std::vector<uchar> pool;
1456         std::vector<size_t> hashtab;
1457         int size[MAX_DIM];
1458     };
1459
1460     //! sparse matrix node - element of a hash table
1461     struct CV_EXPORTS Node
1462     {
1463         //! hash value
1464         size_t hashval;
1465         //! index of the next node in the same hash table entry
1466         size_t next;
1467         //! index of the matrix element
1468         int idx[MAX_DIM];
1469     };
1470
1471     //! default constructor
1472     SparseMat();
1473     //! creates matrix of the specified size and type
1474     SparseMat(int dims, const int* _sizes, int _type);
1475     //! copy constructor
1476     SparseMat(const SparseMat& m);
1477     //! converts dense 2d matrix to the sparse form
1478     /*!
1479      \param m the input matrix
1480     */
1481     explicit SparseMat(const Mat& m);
1482     //! converts old-style sparse matrix to the new-style. All the data is copied
1483     //SparseMat(const CvSparseMat* m);
1484     //! the destructor
1485     ~SparseMat();
1486
1487     //! assignment operator. This is O(1) operation, i.e. no data is copied
1488     SparseMat& operator = (const SparseMat& m);
1489     //! equivalent to the corresponding constructor
1490     SparseMat& operator = (const Mat& m);
1491
1492     //! creates full copy of the matrix
1493     SparseMat clone() const;
1494
1495     //! copies all the data to the destination matrix. All the previous content of m is erased
1496     void copyTo( SparseMat& m ) const;
1497     //! converts sparse matrix to dense matrix.
1498     void copyTo( Mat& m ) const;
1499     //! multiplies all the matrix elements by the specified scale factor alpha and converts the results to the specified data type
1500     void convertTo( SparseMat& m, int rtype, double alpha=1 ) const;
1501     //! converts sparse matrix to dense n-dim matrix with optional type conversion and scaling.
1502     /*!
1503       \param rtype The output matrix data type. When it is =-1, the output array will have the same data type as (*this)
1504       \param alpha The scale factor
1505       \param beta The optional delta added to the scaled values before the conversion
1506     */
1507     void convertTo( Mat& m, int rtype, double alpha=1, double beta=0 ) const;
1508
1509     // not used now
1510     void assignTo( SparseMat& m, int type=-1 ) const;
1511
1512     //! reallocates sparse matrix.
1513     /*!
1514         If the matrix already had the proper size and type,
1515         it is simply cleared with clear(), otherwise,
1516         the old matrix is released (using release()) and the new one is allocated.
1517     */
1518     void create(int dims, const int* _sizes, int _type);
1519     //! sets all the sparse matrix elements to 0, which means clearing the hash table.
1520     void clear();
1521     //! manually increments the reference counter to the header.
1522     void addref();
1523     // decrements the header reference counter. When the counter reaches 0, the header and all the underlying data are deallocated.
1524     void release();
1525
1526     //! converts sparse matrix to the old-style representation; all the elements are copied.
1527     //operator CvSparseMat*() const;
1528     //! returns the size of each element in bytes (not including the overhead - the space occupied by SparseMat::Node elements)
1529     size_t elemSize() const;
1530     //! returns elemSize()/channels()
1531     size_t elemSize1() const;
1532
1533     //! returns type of sparse matrix elements
1534     int type() const;
1535     //! returns the depth of sparse matrix elements
1536     int depth() const;
1537     //! returns the number of channels
1538     int channels() const;
1539
1540     //! returns the array of sizes, or NULL if the matrix is not allocated
1541     const int* size() const;
1542     //! returns the size of i-th matrix dimension (or 0)
1543     int size(int i) const;
1544     //! returns the matrix dimensionality
1545     int dims() const;
1546     //! returns the number of non-zero elements (=the number of hash table nodes)
1547     size_t nzcount() const;
1548
1549     //! computes the element hash value (1D case)
1550     size_t hash(int i0) const;
1551     //! computes the element hash value (2D case)
1552     size_t hash(int i0, int i1) const;
1553     //! computes the element hash value (3D case)
1554     size_t hash(int i0, int i1, int i2) const;
1555     //! computes the element hash value (nD case)
1556     size_t hash(const int* idx) const;
1557
1558     //@{
1559     /*!
1560      specialized variants for 1D, 2D, 3D cases and the generic_type one for n-D case.
1561
1562      return pointer to the matrix element.
1563      <ul>
1564       <li>if the element is there (it's non-zero), the pointer to it is returned
1565       <li>if it's not there and createMissing=false, NULL pointer is returned
1566       <li>if it's not there and createMissing=true, then the new element
1567         is created and initialized with 0. Pointer to it is returned
1568       <li>if the optional hashval pointer is not NULL, the element hash value is
1569       not computed, but *hashval is taken instead.
1570      </ul>
1571     */
1572     //! returns pointer to the specified element (1D case)
1573     uchar* ptr(int i0, bool createMissing, size_t* hashval=0);
1574     //! returns pointer to the specified element (2D case)
1575     uchar* ptr(int i0, int i1, bool createMissing, size_t* hashval=0);
1576     //! returns pointer to the specified element (3D case)
1577     uchar* ptr(int i0, int i1, int i2, bool createMissing, size_t* hashval=0);
1578     //! returns pointer to the specified element (nD case)
1579     uchar* ptr(const int* idx, bool createMissing, size_t* hashval=0);
1580     //@}
1581
1582     //@{
1583     /*!
1584      return read-write reference to the specified sparse matrix element.
1585
1586      ref<_Tp>(i0,...[,hashval]) is equivalent to *(_Tp*)ptr(i0,...,true[,hashval]).
1587      The methods always return a valid reference.
1588      If the element did not exist, it is created and initialiazed with 0.
1589     */
1590     //! returns reference to the specified element (1D case)
1591     template<typename _Tp> _Tp& ref(int i0, size_t* hashval=0);
1592     //! returns reference to the specified element (2D case)
1593     template<typename _Tp> _Tp& ref(int i0, int i1, size_t* hashval=0);
1594     //! returns reference to the specified element (3D case)
1595     template<typename _Tp> _Tp& ref(int i0, int i1, int i2, size_t* hashval=0);
1596     //! returns reference to the specified element (nD case)
1597     template<typename _Tp> _Tp& ref(const int* idx, size_t* hashval=0);
1598     //@}
1599
1600     //@{
1601     /*!
1602      return value of the specified sparse matrix element.
1603
1604      value<_Tp>(i0,...[,hashval]) is equivalent
1605
1606      \code
1607      { const _Tp* p = find<_Tp>(i0,...[,hashval]); return p ? *p : _Tp(); }
1608      \endcode
1609
1610      That is, if the element did not exist, the methods return 0.
1611      */
1612     //! returns value of the specified element (1D case)
1613     template<typename _Tp> _Tp value(int i0, size_t* hashval=0) const;
1614     //! returns value of the specified element (2D case)
1615     template<typename _Tp> _Tp value(int i0, int i1, size_t* hashval=0) const;
1616     //! returns value of the specified element (3D case)
1617     template<typename _Tp> _Tp value(int i0, int i1, int i2, size_t* hashval=0) const;
1618     //! returns value of the specified element (nD case)
1619     template<typename _Tp> _Tp value(const int* idx, size_t* hashval=0) const;
1620     //@}
1621
1622     //@{
1623     /*!
1624      Return pointer to the specified sparse matrix element if it exists
1625
1626      find<_Tp>(i0,...[,hashval]) is equivalent to (_const Tp*)ptr(i0,...false[,hashval]).
1627
1628      If the specified element does not exist, the methods return NULL.
1629     */
1630     //! returns pointer to the specified element (1D case)
1631     template<typename _Tp> const _Tp* find(int i0, size_t* hashval=0) const;
1632     //! returns pointer to the specified element (2D case)
1633     template<typename _Tp> const _Tp* find(int i0, int i1, size_t* hashval=0) const;
1634     //! returns pointer to the specified element (3D case)
1635     template<typename _Tp> const _Tp* find(int i0, int i1, int i2, size_t* hashval=0) const;
1636     //! returns pointer to the specified element (nD case)
1637     template<typename _Tp> const _Tp* find(const int* idx, size_t* hashval=0) const;
1638
1639     //! erases the specified element (2D case)
1640     void erase(int i0, int i1, size_t* hashval=0);
1641     //! erases the specified element (3D case)
1642     void erase(int i0, int i1, int i2, size_t* hashval=0);
1643     //! erases the specified element (nD case)
1644     void erase(const int* idx, size_t* hashval=0);
1645
1646     //@{
1647     /*!
1648        return the sparse matrix iterator pointing to the first sparse matrix element
1649     */
1650     //! returns the sparse matrix iterator at the matrix beginning
1651     SparseMatIterator begin();
1652     //! returns the sparse matrix iterator at the matrix beginning
1653     template<typename _Tp> SparseMatIterator_<_Tp> begin();
1654     //! returns the read-only sparse matrix iterator at the matrix beginning
1655     SparseMatConstIterator begin() const;
1656     //! returns the read-only sparse matrix iterator at the matrix beginning
1657     template<typename _Tp> SparseMatConstIterator_<_Tp> begin() const;
1658     //@}
1659     /*!
1660        return the sparse matrix iterator pointing to the element following the last sparse matrix element
1661     */
1662     //! returns the sparse matrix iterator at the matrix end
1663     SparseMatIterator end();
1664     //! returns the read-only sparse matrix iterator at the matrix end
1665     SparseMatConstIterator end() const;
1666     //! returns the typed sparse matrix iterator at the matrix end
1667     template<typename _Tp> SparseMatIterator_<_Tp> end();
1668     //! returns the typed read-only sparse matrix iterator at the matrix end
1669     template<typename _Tp> SparseMatConstIterator_<_Tp> end() const;
1670
1671     //! returns the value stored in the sparse martix node
1672     template<typename _Tp> _Tp& value(Node* n);
1673     //! returns the value stored in the sparse martix node
1674     template<typename _Tp> const _Tp& value(const Node* n) const;
1675
1676     ////////////// some internal-use methods ///////////////
1677     Node* node(size_t nidx);
1678     const Node* node(size_t nidx) const;
1679
1680     uchar* newNode(const int* idx, size_t hashval);
1681     void removeNode(size_t hidx, size_t nidx, size_t previdx);
1682     void resizeHashTab(size_t newsize);
1683
1684     int flags;
1685     Hdr* hdr;
1686 };
1687
1688
1689
1690 ///////////////////////////////// SparseMat_<_Tp> ////////////////////////////////////
1691
1692 /*!
1693  The Template Sparse Matrix class derived from cv::SparseMat
1694
1695  The class provides slightly more convenient operations for accessing elements.
1696
1697  \code
1698  SparseMat m;
1699  ...
1700  SparseMat_<int> m_ = (SparseMat_<int>&)m;
1701  m_.ref(1)++; // equivalent to m.ref<int>(1)++;
1702  m_.ref(2) += m_(3); // equivalent to m.ref<int>(2) += m.value<int>(3);
1703  \endcode
1704 */
1705 template<typename _Tp> class SparseMat_ : public SparseMat
1706 {
1707 public:
1708     typedef SparseMatIterator_<_Tp> iterator;
1709     typedef SparseMatConstIterator_<_Tp> const_iterator;
1710
1711     //! the default constructor
1712     SparseMat_();
1713     //! the full constructor equivelent to SparseMat(dims, _sizes, DataType<_Tp>::type)
1714     SparseMat_(int dims, const int* _sizes);
1715     //! the copy constructor. If DataType<_Tp>.type != m.type(), the m elements are converted
1716     SparseMat_(const SparseMat& m);
1717     //! the copy constructor. This is O(1) operation - no data is copied
1718     SparseMat_(const SparseMat_& m);
1719     //! converts dense matrix to the sparse form
1720     SparseMat_(const Mat& m);
1721     //! converts the old-style sparse matrix to the C++ class. All the elements are copied
1722     //SparseMat_(const CvSparseMat* m);
1723     //! the assignment operator. If DataType<_Tp>.type != m.type(), the m elements are converted
1724     SparseMat_& operator = (const SparseMat& m);
1725     //! the assignment operator. This is O(1) operation - no data is copied
1726     SparseMat_& operator = (const SparseMat_& m);
1727     //! converts dense matrix to the sparse form
1728     SparseMat_& operator = (const Mat& m);
1729
1730     //! makes full copy of the matrix. All the elements are duplicated
1731     SparseMat_ clone() const;
1732     //! equivalent to cv::SparseMat::create(dims, _sizes, DataType<_Tp>::type)
1733     void create(int dims, const int* _sizes);
1734     //! converts sparse matrix to the old-style CvSparseMat. All the elements are copied
1735     //operator CvSparseMat*() const;
1736
1737     //! returns type of the matrix elements
1738     int type() const;
1739     //! returns depth of the matrix elements
1740     int depth() const;
1741     //! returns the number of channels in each matrix element
1742     int channels() const;
1743
1744     //! equivalent to SparseMat::ref<_Tp>(i0, hashval)
1745     _Tp& ref(int i0, size_t* hashval=0);
1746     //! equivalent to SparseMat::ref<_Tp>(i0, i1, hashval)
1747     _Tp& ref(int i0, int i1, size_t* hashval=0);
1748     //! equivalent to SparseMat::ref<_Tp>(i0, i1, i2, hashval)
1749     _Tp& ref(int i0, int i1, int i2, size_t* hashval=0);
1750     //! equivalent to SparseMat::ref<_Tp>(idx, hashval)
1751     _Tp& ref(const int* idx, size_t* hashval=0);
1752
1753     //! equivalent to SparseMat::value<_Tp>(i0, hashval)
1754     _Tp operator()(int i0, size_t* hashval=0) const;
1755     //! equivalent to SparseMat::value<_Tp>(i0, i1, hashval)
1756     _Tp operator()(int i0, int i1, size_t* hashval=0) const;
1757     //! equivalent to SparseMat::value<_Tp>(i0, i1, i2, hashval)
1758     _Tp operator()(int i0, int i1, int i2, size_t* hashval=0) const;
1759     //! equivalent to SparseMat::value<_Tp>(idx, hashval)
1760     _Tp operator()(const int* idx, size_t* hashval=0) const;
1761
1762     //! returns sparse matrix iterator pointing to the first sparse matrix element
1763     SparseMatIterator_<_Tp> begin();
1764     //! returns read-only sparse matrix iterator pointing to the first sparse matrix element
1765     SparseMatConstIterator_<_Tp> begin() const;
1766     //! returns sparse matrix iterator pointing to the element following the last sparse matrix element
1767     SparseMatIterator_<_Tp> end();
1768     //! returns read-only sparse matrix iterator pointing to the element following the last sparse matrix element
1769     SparseMatConstIterator_<_Tp> end() const;
1770 };
1771
1772
1773
1774 ////////////////////////////////// MatConstIterator //////////////////////////////////
1775
1776 class CV_EXPORTS MatConstIterator
1777 {
1778 public:
1779     typedef uchar* value_type;
1780     typedef ptrdiff_t difference_type;
1781     typedef const uchar** pointer;
1782     typedef uchar* reference;
1783
1784 #ifndef OPENCV_NOSTL
1785     typedef std::random_access_iterator_tag iterator_category;
1786 #endif
1787
1788     //! default constructor
1789     MatConstIterator();
1790     //! constructor that sets the iterator to the beginning of the matrix
1791     MatConstIterator(const Mat* _m);
1792     //! constructor that sets the iterator to the specified element of the matrix
1793     MatConstIterator(const Mat* _m, int _row, int _col=0);
1794     //! constructor that sets the iterator to the specified element of the matrix
1795     MatConstIterator(const Mat* _m, Point _pt);
1796     //! constructor that sets the iterator to the specified element of the matrix
1797     MatConstIterator(const Mat* _m, const int* _idx);
1798     //! copy constructor
1799     MatConstIterator(const MatConstIterator& it);
1800
1801     //! copy operator
1802     MatConstIterator& operator = (const MatConstIterator& it);
1803     //! returns the current matrix element
1804     uchar* operator *() const;
1805     //! returns the i-th matrix element, relative to the current
1806     uchar* operator [](ptrdiff_t i) const;
1807
1808     //! shifts the iterator forward by the specified number of elements
1809     MatConstIterator& operator += (ptrdiff_t ofs);
1810     //! shifts the iterator backward by the specified number of elements
1811     MatConstIterator& operator -= (ptrdiff_t ofs);
1812     //! decrements the iterator
1813     MatConstIterator& operator --();
1814     //! decrements the iterator
1815     MatConstIterator operator --(int);
1816     //! increments the iterator
1817     MatConstIterator& operator ++();
1818     //! increments the iterator
1819     MatConstIterator operator ++(int);
1820     //! returns the current iterator position
1821     Point pos() const;
1822     //! returns the current iterator position
1823     void pos(int* _idx) const;
1824
1825     ptrdiff_t lpos() const;
1826     void seek(ptrdiff_t ofs, bool relative = false);
1827     void seek(const int* _idx, bool relative = false);
1828
1829     const Mat* m;
1830     size_t elemSize;
1831     uchar* ptr;
1832     uchar* sliceStart;
1833     uchar* sliceEnd;
1834 };
1835
1836
1837
1838 ////////////////////////////////// MatConstIterator_ /////////////////////////////////
1839
1840 /*!
1841  Matrix read-only iterator
1842  */
1843 template<typename _Tp>
1844 class MatConstIterator_ : public MatConstIterator
1845 {
1846 public:
1847     typedef _Tp value_type;
1848     typedef ptrdiff_t difference_type;
1849     typedef const _Tp* pointer;
1850     typedef const _Tp& reference;
1851
1852 #ifndef OPENCV_NOSTL
1853     typedef std::random_access_iterator_tag iterator_category;
1854 #endif
1855
1856     //! default constructor
1857     MatConstIterator_();
1858     //! constructor that sets the iterator to the beginning of the matrix
1859     MatConstIterator_(const Mat_<_Tp>* _m);
1860     //! constructor that sets the iterator to the specified element of the matrix
1861     MatConstIterator_(const Mat_<_Tp>* _m, int _row, int _col=0);
1862     //! constructor that sets the iterator to the specified element of the matrix
1863     MatConstIterator_(const Mat_<_Tp>* _m, Point _pt);
1864     //! constructor that sets the iterator to the specified element of the matrix
1865     MatConstIterator_(const Mat_<_Tp>* _m, const int* _idx);
1866     //! copy constructor
1867     MatConstIterator_(const MatConstIterator_& it);
1868
1869     //! copy operator
1870     MatConstIterator_& operator = (const MatConstIterator_& it);
1871     //! returns the current matrix element
1872     _Tp operator *() const;
1873     //! returns the i-th matrix element, relative to the current
1874     _Tp operator [](ptrdiff_t i) const;
1875
1876     //! shifts the iterator forward by the specified number of elements
1877     MatConstIterator_& operator += (ptrdiff_t ofs);
1878     //! shifts the iterator backward by the specified number of elements
1879     MatConstIterator_& operator -= (ptrdiff_t ofs);
1880     //! decrements the iterator
1881     MatConstIterator_& operator --();
1882     //! decrements the iterator
1883     MatConstIterator_ operator --(int);
1884     //! increments the iterator
1885     MatConstIterator_& operator ++();
1886     //! increments the iterator
1887     MatConstIterator_ operator ++(int);
1888     //! returns the current iterator position
1889     Point pos() const;
1890 };
1891
1892
1893
1894 //////////////////////////////////// MatIterator_ ////////////////////////////////////
1895
1896 /*!
1897  Matrix read-write iterator
1898 */
1899 template<typename _Tp>
1900 class MatIterator_ : public MatConstIterator_<_Tp>
1901 {
1902 public:
1903     typedef _Tp* pointer;
1904     typedef _Tp& reference;
1905
1906 #ifndef OPENCV_NOSTL
1907     typedef std::random_access_iterator_tag iterator_category;
1908 #endif
1909
1910     //! the default constructor
1911     MatIterator_();
1912     //! constructor that sets the iterator to the beginning of the matrix
1913     MatIterator_(Mat_<_Tp>* _m);
1914     //! constructor that sets the iterator to the specified element of the matrix
1915     MatIterator_(Mat_<_Tp>* _m, int _row, int _col=0);
1916     //! constructor that sets the iterator to the specified element of the matrix
1917     MatIterator_(const Mat_<_Tp>* _m, Point _pt);
1918     //! constructor that sets the iterator to the specified element of the matrix
1919     MatIterator_(const Mat_<_Tp>* _m, const int* _idx);
1920     //! copy constructor
1921     MatIterator_(const MatIterator_& it);
1922     //! copy operator
1923     MatIterator_& operator = (const MatIterator_<_Tp>& it );
1924
1925     //! returns the current matrix element
1926     _Tp& operator *() const;
1927     //! returns the i-th matrix element, relative to the current
1928     _Tp& operator [](ptrdiff_t i) const;
1929
1930     //! shifts the iterator forward by the specified number of elements
1931     MatIterator_& operator += (ptrdiff_t ofs);
1932     //! shifts the iterator backward by the specified number of elements
1933     MatIterator_& operator -= (ptrdiff_t ofs);
1934     //! decrements the iterator
1935     MatIterator_& operator --();
1936     //! decrements the iterator
1937     MatIterator_ operator --(int);
1938     //! increments the iterator
1939     MatIterator_& operator ++();
1940     //! increments the iterator
1941     MatIterator_ operator ++(int);
1942 };
1943
1944
1945
1946 /////////////////////////////// SparseMatConstIterator ///////////////////////////////
1947
1948 /*!
1949  Read-Only Sparse Matrix Iterator.
1950  Here is how to use the iterator to compute the sum of floating-point sparse matrix elements:
1951
1952  \code
1953  SparseMatConstIterator it = m.begin(), it_end = m.end();
1954  double s = 0;
1955  CV_Assert( m.type() == CV_32F );
1956  for( ; it != it_end; ++it )
1957     s += it.value<float>();
1958  \endcode
1959 */
1960 class CV_EXPORTS SparseMatConstIterator
1961 {
1962 public:
1963     //! the default constructor
1964     SparseMatConstIterator();
1965     //! the full constructor setting the iterator to the first sparse matrix element
1966     SparseMatConstIterator(const SparseMat* _m);
1967     //! the copy constructor
1968     SparseMatConstIterator(const SparseMatConstIterator& it);
1969
1970     //! the assignment operator
1971     SparseMatConstIterator& operator = (const SparseMatConstIterator& it);
1972
1973     //! template method returning the current matrix element
1974     template<typename _Tp> const _Tp& value() const;
1975     //! returns the current node of the sparse matrix. it.node->idx is the current element index
1976     const SparseMat::Node* node() const;
1977
1978     //! moves iterator to the previous element
1979     SparseMatConstIterator& operator --();
1980     //! moves iterator to the previous element
1981     SparseMatConstIterator operator --(int);
1982     //! moves iterator to the next element
1983     SparseMatConstIterator& operator ++();
1984     //! moves iterator to the next element
1985     SparseMatConstIterator operator ++(int);
1986
1987     //! moves iterator to the element after the last element
1988     void seekEnd();
1989
1990     const SparseMat* m;
1991     size_t hashidx;
1992     uchar* ptr;
1993 };
1994
1995
1996
1997 ////////////////////////////////// SparseMatIterator /////////////////////////////////
1998
1999 /*!
2000  Read-write Sparse Matrix Iterator
2001
2002  The class is similar to cv::SparseMatConstIterator,
2003  but can be used for in-place modification of the matrix elements.
2004 */
2005 class CV_EXPORTS SparseMatIterator : public SparseMatConstIterator
2006 {
2007 public:
2008     //! the default constructor
2009     SparseMatIterator();
2010     //! the full constructor setting the iterator to the first sparse matrix element
2011     SparseMatIterator(SparseMat* _m);
2012     //! the full constructor setting the iterator to the specified sparse matrix element
2013     SparseMatIterator(SparseMat* _m, const int* idx);
2014     //! the copy constructor
2015     SparseMatIterator(const SparseMatIterator& it);
2016
2017     //! the assignment operator
2018     SparseMatIterator& operator = (const SparseMatIterator& it);
2019     //! returns read-write reference to the current sparse matrix element
2020     template<typename _Tp> _Tp& value() const;
2021     //! returns pointer to the current sparse matrix node. it.node->idx is the index of the current element (do not modify it!)
2022     SparseMat::Node* node() const;
2023
2024     //! moves iterator to the next element
2025     SparseMatIterator& operator ++();
2026     //! moves iterator to the next element
2027     SparseMatIterator operator ++(int);
2028 };
2029
2030
2031
2032 /////////////////////////////// SparseMatConstIterator_ //////////////////////////////
2033
2034 /*!
2035  Template Read-Only Sparse Matrix Iterator Class.
2036
2037  This is the derived from SparseMatConstIterator class that
2038  introduces more convenient operator *() for accessing the current element.
2039 */
2040 template<typename _Tp> class SparseMatConstIterator_ : public SparseMatConstIterator
2041 {
2042 public:
2043
2044 #ifndef OPENCV_NOSTL
2045     typedef std::forward_iterator_tag iterator_category;
2046 #endif
2047
2048     //! the default constructor
2049     SparseMatConstIterator_();
2050     //! the full constructor setting the iterator to the first sparse matrix element
2051     SparseMatConstIterator_(const SparseMat_<_Tp>* _m);
2052     SparseMatConstIterator_(const SparseMat* _m);
2053     //! the copy constructor
2054     SparseMatConstIterator_(const SparseMatConstIterator_& it);
2055
2056     //! the assignment operator
2057     SparseMatConstIterator_& operator = (const SparseMatConstIterator_& it);
2058     //! the element access operator
2059     const _Tp& operator *() const;
2060
2061     //! moves iterator to the next element
2062     SparseMatConstIterator_& operator ++();
2063     //! moves iterator to the next element
2064     SparseMatConstIterator_ operator ++(int);
2065 };
2066
2067
2068
2069 ///////////////////////////////// SparseMatIterator_ /////////////////////////////////
2070
2071 /*!
2072  Template Read-Write Sparse Matrix Iterator Class.
2073
2074  This is the derived from cv::SparseMatConstIterator_ class that
2075  introduces more convenient operator *() for accessing the current element.
2076 */
2077 template<typename _Tp> class SparseMatIterator_ : public SparseMatConstIterator_<_Tp>
2078 {
2079 public:
2080
2081 #ifndef OPENCV_NOSTL
2082     typedef std::forward_iterator_tag iterator_category;
2083 #endif
2084
2085     //! the default constructor
2086     SparseMatIterator_();
2087     //! the full constructor setting the iterator to the first sparse matrix element
2088     SparseMatIterator_(SparseMat_<_Tp>* _m);
2089     SparseMatIterator_(SparseMat* _m);
2090     //! the copy constructor
2091     SparseMatIterator_(const SparseMatIterator_& it);
2092
2093     //! the assignment operator
2094     SparseMatIterator_& operator = (const SparseMatIterator_& it);
2095     //! returns the reference to the current element
2096     _Tp& operator *() const;
2097
2098     //! moves the iterator to the next element
2099     SparseMatIterator_& operator ++();
2100     //! moves the iterator to the next element
2101     SparseMatIterator_ operator ++(int);
2102 };
2103
2104
2105
2106 /////////////////////////////////// NAryMatIterator //////////////////////////////////
2107
2108 /*!
2109  n-Dimensional Dense Matrix Iterator Class.
2110
2111  The class cv::NAryMatIterator is used for iterating over one or more n-dimensional dense arrays (cv::Mat's).
2112
2113  The iterator is completely different from cv::Mat_ and cv::SparseMat_ iterators.
2114  It iterates through the slices (or planes), not the elements, where "slice" is a continuous part of the arrays.
2115
2116  Here is the example on how the iterator can be used to normalize 3D histogram:
2117
2118  \code
2119  void normalizeColorHist(Mat& hist)
2120  {
2121  #if 1
2122      // intialize iterator (the style is different from STL).
2123      // after initialization the iterator will contain
2124      // the number of slices or planes
2125      // the iterator will go through
2126      Mat* arrays[] = { &hist, 0 };
2127      Mat planes[1];
2128      NAryMatIterator it(arrays, planes);
2129      double s = 0;
2130      // iterate through the matrix. on each iteration
2131      // it.planes[i] (of type Mat) will be set to the current plane of
2132      // i-th n-dim matrix passed to the iterator constructor.
2133      for(int p = 0; p < it.nplanes; p++, ++it)
2134         s += sum(it.planes[0])[0];
2135      it = NAryMatIterator(hist);
2136      s = 1./s;
2137      for(int p = 0; p < it.nplanes; p++, ++it)
2138         it.planes[0] *= s;
2139  #elif 1
2140      // this is a shorter implementation of the above
2141      // using built-in operations on Mat
2142      double s = sum(hist)[0];
2143      hist.convertTo(hist, hist.type(), 1./s, 0);
2144  #else
2145      // and this is even shorter one
2146      // (assuming that the histogram elements are non-negative)
2147      normalize(hist, hist, 1, 0, NORM_L1);
2148  #endif
2149  }
2150  \endcode
2151
2152  You can iterate through several matrices simultaneously as long as they have the same geometry
2153  (dimensionality and all the dimension sizes are the same), which is useful for binary
2154  and n-ary operations on such matrices. Just pass those matrices to cv::MatNDIterator.
2155  Then, during the iteration it.planes[0], it.planes[1], ... will
2156  be the slices of the corresponding matrices
2157 */
2158 class CV_EXPORTS NAryMatIterator
2159 {
2160 public:
2161     //! the default constructor
2162     NAryMatIterator();
2163     //! the full constructor taking arbitrary number of n-dim matrices
2164     NAryMatIterator(const Mat** arrays, uchar** ptrs, int narrays=-1);
2165     //! the full constructor taking arbitrary number of n-dim matrices
2166     NAryMatIterator(const Mat** arrays, Mat* planes, int narrays=-1);
2167     //! the separate iterator initialization method
2168     void init(const Mat** arrays, Mat* planes, uchar** ptrs, int narrays=-1);
2169
2170     //! proceeds to the next plane of every iterated matrix
2171     NAryMatIterator& operator ++();
2172     //! proceeds to the next plane of every iterated matrix (postfix increment operator)
2173     NAryMatIterator operator ++(int);
2174
2175     //! the iterated arrays
2176     const Mat** arrays;
2177     //! the current planes
2178     Mat* planes;
2179     //! data pointers
2180     uchar** ptrs;
2181     //! the number of arrays
2182     int narrays;
2183     //! the number of hyper-planes that the iterator steps through
2184     size_t nplanes;
2185     //! the size of each segment (in elements)
2186     size_t size;
2187 protected:
2188     int iterdepth;
2189     size_t idx;
2190 };
2191
2192
2193
2194 ///////////////////////////////// Matrix Expressions /////////////////////////////////
2195
2196 class CV_EXPORTS MatOp
2197 {
2198 public:
2199     MatOp();
2200     virtual ~MatOp();
2201
2202     virtual bool elementWise(const MatExpr& expr) const;
2203     virtual void assign(const MatExpr& expr, Mat& m, int type=-1) const = 0;
2204     virtual void roi(const MatExpr& expr, const Range& rowRange,
2205                      const Range& colRange, MatExpr& res) const;
2206     virtual void diag(const MatExpr& expr, int d, MatExpr& res) const;
2207     virtual void augAssignAdd(const MatExpr& expr, Mat& m) const;
2208     virtual void augAssignSubtract(const MatExpr& expr, Mat& m) const;
2209     virtual void augAssignMultiply(const MatExpr& expr, Mat& m) const;
2210     virtual void augAssignDivide(const MatExpr& expr, Mat& m) const;
2211     virtual void augAssignAnd(const MatExpr& expr, Mat& m) const;
2212     virtual void augAssignOr(const MatExpr& expr, Mat& m) const;
2213     virtual void augAssignXor(const MatExpr& expr, Mat& m) const;
2214
2215     virtual void add(const MatExpr& expr1, const MatExpr& expr2, MatExpr& res) const;
2216     virtual void add(const MatExpr& expr1, const Scalar& s, MatExpr& res) const;
2217
2218     virtual void subtract(const MatExpr& expr1, const MatExpr& expr2, MatExpr& res) const;
2219     virtual void subtract(const Scalar& s, const MatExpr& expr, MatExpr& res) const;
2220
2221     virtual void multiply(const MatExpr& expr1, const MatExpr& expr2, MatExpr& res, double scale=1) const;
2222     virtual void multiply(const MatExpr& expr1, double s, MatExpr& res) const;
2223
2224     virtual void divide(const MatExpr& expr1, const MatExpr& expr2, MatExpr& res, double scale=1) const;
2225     virtual void divide(double s, const MatExpr& expr, MatExpr& res) const;
2226
2227     virtual void abs(const MatExpr& expr, MatExpr& res) const;
2228
2229     virtual void transpose(const MatExpr& expr, MatExpr& res) const;
2230     virtual void matmul(const MatExpr& expr1, const MatExpr& expr2, MatExpr& res) const;
2231     virtual void invert(const MatExpr& expr, int method, MatExpr& res) const;
2232
2233     virtual Size size(const MatExpr& expr) const;
2234     virtual int type(const MatExpr& expr) const;
2235 };
2236
2237
2238 class CV_EXPORTS MatExpr
2239 {
2240 public:
2241     MatExpr();
2242     explicit MatExpr(const Mat& m);
2243
2244     MatExpr(const MatOp* _op, int _flags, const Mat& _a = Mat(), const Mat& _b = Mat(),
2245             const Mat& _c = Mat(), double _alpha = 1, double _beta = 1, const Scalar& _s = Scalar());
2246
2247     operator Mat() const;
2248     template<typename _Tp> operator Mat_<_Tp>() const;
2249
2250     Size size() const;
2251     int type() const;
2252
2253     MatExpr row(int y) const;
2254     MatExpr col(int x) const;
2255     MatExpr diag(int d = 0) const;
2256     MatExpr operator()( const Range& rowRange, const Range& colRange ) const;
2257     MatExpr operator()( const Rect& roi ) const;
2258
2259     MatExpr t() const;
2260     MatExpr inv(int method = DECOMP_LU) const;
2261     MatExpr mul(const MatExpr& e, double scale=1) const;
2262     MatExpr mul(const Mat& m, double scale=1) const;
2263
2264     Mat cross(const Mat& m) const;
2265     double dot(const Mat& m) const;
2266
2267     const MatOp* op;
2268     int flags;
2269
2270     Mat a, b, c;
2271     double alpha, beta;
2272     Scalar s;
2273 };
2274
2275
2276 CV_EXPORTS MatExpr operator + (const Mat& a, const Mat& b);
2277 CV_EXPORTS MatExpr operator + (const Mat& a, const Scalar& s);
2278 CV_EXPORTS MatExpr operator + (const Scalar& s, const Mat& a);
2279 CV_EXPORTS MatExpr operator + (const MatExpr& e, const Mat& m);
2280 CV_EXPORTS MatExpr operator + (const Mat& m, const MatExpr& e);
2281 CV_EXPORTS MatExpr operator + (const MatExpr& e, const Scalar& s);
2282 CV_EXPORTS MatExpr operator + (const Scalar& s, const MatExpr& e);
2283 CV_EXPORTS MatExpr operator + (const MatExpr& e1, const MatExpr& e2);
2284
2285 CV_EXPORTS MatExpr operator - (const Mat& a, const Mat& b);
2286 CV_EXPORTS MatExpr operator - (const Mat& a, const Scalar& s);
2287 CV_EXPORTS MatExpr operator - (const Scalar& s, const Mat& a);
2288 CV_EXPORTS MatExpr operator - (const MatExpr& e, const Mat& m);
2289 CV_EXPORTS MatExpr operator - (const Mat& m, const MatExpr& e);
2290 CV_EXPORTS MatExpr operator - (const MatExpr& e, const Scalar& s);
2291 CV_EXPORTS MatExpr operator - (const Scalar& s, const MatExpr& e);
2292 CV_EXPORTS MatExpr operator - (const MatExpr& e1, const MatExpr& e2);
2293
2294 CV_EXPORTS MatExpr operator - (const Mat& m);
2295 CV_EXPORTS MatExpr operator - (const MatExpr& e);
2296
2297 CV_EXPORTS MatExpr operator * (const Mat& a, const Mat& b);
2298 CV_EXPORTS MatExpr operator * (const Mat& a, double s);
2299 CV_EXPORTS MatExpr operator * (double s, const Mat& a);
2300 CV_EXPORTS MatExpr operator * (const MatExpr& e, const Mat& m);
2301 CV_EXPORTS MatExpr operator * (const Mat& m, const MatExpr& e);
2302 CV_EXPORTS MatExpr operator * (const MatExpr& e, double s);
2303 CV_EXPORTS MatExpr operator * (double s, const MatExpr& e);
2304 CV_EXPORTS MatExpr operator * (const MatExpr& e1, const MatExpr& e2);
2305
2306 CV_EXPORTS MatExpr operator / (const Mat& a, const Mat& b);
2307 CV_EXPORTS MatExpr operator / (const Mat& a, double s);
2308 CV_EXPORTS MatExpr operator / (double s, const Mat& a);
2309 CV_EXPORTS MatExpr operator / (const MatExpr& e, const Mat& m);
2310 CV_EXPORTS MatExpr operator / (const Mat& m, const MatExpr& e);
2311 CV_EXPORTS MatExpr operator / (const MatExpr& e, double s);
2312 CV_EXPORTS MatExpr operator / (double s, const MatExpr& e);
2313 CV_EXPORTS MatExpr operator / (const MatExpr& e1, const MatExpr& e2);
2314
2315 CV_EXPORTS MatExpr operator < (const Mat& a, const Mat& b);
2316 CV_EXPORTS MatExpr operator < (const Mat& a, double s);
2317 CV_EXPORTS MatExpr operator < (double s, const Mat& a);
2318
2319 CV_EXPORTS MatExpr operator <= (const Mat& a, const Mat& b);
2320 CV_EXPORTS MatExpr operator <= (const Mat& a, double s);
2321 CV_EXPORTS MatExpr operator <= (double s, const Mat& a);
2322
2323 CV_EXPORTS MatExpr operator == (const Mat& a, const Mat& b);
2324 CV_EXPORTS MatExpr operator == (const Mat& a, double s);
2325 CV_EXPORTS MatExpr operator == (double s, const Mat& a);
2326
2327 CV_EXPORTS MatExpr operator != (const Mat& a, const Mat& b);
2328 CV_EXPORTS MatExpr operator != (const Mat& a, double s);
2329 CV_EXPORTS MatExpr operator != (double s, const Mat& a);
2330
2331 CV_EXPORTS MatExpr operator >= (const Mat& a, const Mat& b);
2332 CV_EXPORTS MatExpr operator >= (const Mat& a, double s);
2333 CV_EXPORTS MatExpr operator >= (double s, const Mat& a);
2334
2335 CV_EXPORTS MatExpr operator > (const Mat& a, const Mat& b);
2336 CV_EXPORTS MatExpr operator > (const Mat& a, double s);
2337 CV_EXPORTS MatExpr operator > (double s, const Mat& a);
2338
2339 CV_EXPORTS MatExpr operator & (const Mat& a, const Mat& b);
2340 CV_EXPORTS MatExpr operator & (const Mat& a, const Scalar& s);
2341 CV_EXPORTS MatExpr operator & (const Scalar& s, const Mat& a);
2342
2343 CV_EXPORTS MatExpr operator | (const Mat& a, const Mat& b);
2344 CV_EXPORTS MatExpr operator | (const Mat& a, const Scalar& s);
2345 CV_EXPORTS MatExpr operator | (const Scalar& s, const Mat& a);
2346
2347 CV_EXPORTS MatExpr operator ^ (const Mat& a, const Mat& b);
2348 CV_EXPORTS MatExpr operator ^ (const Mat& a, const Scalar& s);
2349 CV_EXPORTS MatExpr operator ^ (const Scalar& s, const Mat& a);
2350
2351 CV_EXPORTS MatExpr operator ~(const Mat& m);
2352
2353 CV_EXPORTS MatExpr min(const Mat& a, const Mat& b);
2354 CV_EXPORTS MatExpr min(const Mat& a, double s);
2355 CV_EXPORTS MatExpr min(double s, const Mat& a);
2356
2357 CV_EXPORTS MatExpr max(const Mat& a, const Mat& b);
2358 CV_EXPORTS MatExpr max(const Mat& a, double s);
2359 CV_EXPORTS MatExpr max(double s, const Mat& a);
2360
2361 CV_EXPORTS MatExpr abs(const Mat& m);
2362 CV_EXPORTS MatExpr abs(const MatExpr& e);
2363
2364 } // cv
2365
2366 #include "opencv2/core/mat.inl.hpp"
2367
2368 #endif // __OPENCV_CORE_MAT_HPP__