1 /*M///////////////////////////////////////////////////////////////////////////////////////
3 // IMPORTANT: READ BEFORE DOWNLOADING, COPYING, INSTALLING OR USING.
5 // By downloading, copying, installing or using the software you agree to this license.
6 // If you do not agree to this license, do not download, install,
7 // copy or use the software.
11 // For Open Source Computer Vision Library
13 // Copyright (C) 2000-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.
18 // Redistribution and use in source and binary forms, with or without modification,
19 // are permitted provided that the following conditions are met:
21 // * Redistribution's of source code must retain the above copyright notice,
22 // this list of conditions and the following disclaimer.
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.
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.
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.
44 #ifndef __OPENCV_CORE_MAT_HPP__
45 #define __OPENCV_CORE_MAT_HPP__
48 # error mat.hpp header must be compiled as C++
51 #include "opencv2/core/matx.hpp"
52 #include "opencv2/core/types.hpp"
54 #include "opencv2/core/bufferpool.hpp"
59 enum { ACCESS_READ=1<<24, ACCESS_WRITE=1<<25,
60 ACCESS_RW=3<<24, ACCESS_MASK=ACCESS_RW, ACCESS_FAST=1<<26 };
62 class CV_EXPORTS _OutputArray;
64 //////////////////////// Input/Output Array Arguments /////////////////////////////////
67 Proxy datatype for passing Mat's and vector<>'s as input parameters
69 class CV_EXPORTS _InputArray
74 FIXED_TYPE = 0x8000 << KIND_SHIFT,
75 FIXED_SIZE = 0x4000 << KIND_SHIFT,
76 KIND_MASK = 31 << KIND_SHIFT,
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
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);
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;
119 virtual int kind() const;
120 virtual int dims(int i=-1) const;
121 virtual Size size(int i=-1) const;
122 virtual int sizend(int* sz, int i=-1) const;
123 virtual bool sameSize(const _InputArray& arr) const;
124 virtual size_t total(int i=-1) const;
125 virtual int type(int i=-1) const;
126 virtual int depth(int i=-1) const;
127 virtual int channels(int i=-1) const;
128 virtual bool isContinuous(int i=-1) const;
129 virtual bool isSubmatrix(int i=-1) const;
130 virtual bool empty() const;
131 virtual void copyTo(const _OutputArray& arr) const;
132 virtual size_t offset(int i=-1) const;
133 virtual size_t step(int i=-1) const;
136 bool isMatVector() const;
137 bool isUMatVector() const;
140 virtual ~_InputArray();
147 void init(int _flags, const void* _obj);
148 void init(int _flags, const void* _obj, Size _sz);
153 Proxy datatype for passing Mat's and vector<>'s as input parameters
155 class CV_EXPORTS _OutputArray : public _InputArray
160 DEPTH_MASK_8U = 1 << CV_8U,
161 DEPTH_MASK_8S = 1 << CV_8S,
162 DEPTH_MASK_16U = 1 << CV_16U,
163 DEPTH_MASK_16S = 1 << CV_16S,
164 DEPTH_MASK_32S = 1 << CV_32S,
165 DEPTH_MASK_32F = 1 << CV_32F,
166 DEPTH_MASK_64F = 1 << CV_64F,
167 DEPTH_MASK_ALL = (DEPTH_MASK_64F<<1)-1,
168 DEPTH_MASK_ALL_BUT_8S = DEPTH_MASK_ALL & ~DEPTH_MASK_8S,
169 DEPTH_MASK_FLT = DEPTH_MASK_32F + DEPTH_MASK_64F
173 _OutputArray(int _flags, void* _obj);
174 _OutputArray(Mat& m);
175 _OutputArray(std::vector<Mat>& vec);
176 _OutputArray(cuda::GpuMat& d_mat);
177 _OutputArray(ogl::Buffer& buf);
178 _OutputArray(cuda::CudaMem& cuda_mem);
179 template<typename _Tp> _OutputArray(cudev::GpuMat_<_Tp>& m);
180 template<typename _Tp> _OutputArray(std::vector<_Tp>& vec);
181 template<typename _Tp> _OutputArray(std::vector<std::vector<_Tp> >& vec);
182 template<typename _Tp> _OutputArray(std::vector<Mat_<_Tp> >& vec);
183 template<typename _Tp> _OutputArray(Mat_<_Tp>& m);
184 template<typename _Tp> _OutputArray(_Tp* vec, int n);
185 template<typename _Tp, int m, int n> _OutputArray(Matx<_Tp, m, n>& matx);
186 _OutputArray(UMat& m);
187 _OutputArray(std::vector<UMat>& vec);
189 _OutputArray(const Mat& m);
190 _OutputArray(const std::vector<Mat>& vec);
191 _OutputArray(const cuda::GpuMat& d_mat);
192 _OutputArray(const ogl::Buffer& buf);
193 _OutputArray(const cuda::CudaMem& cuda_mem);
194 template<typename _Tp> _OutputArray(const cudev::GpuMat_<_Tp>& m);
195 template<typename _Tp> _OutputArray(const std::vector<_Tp>& vec);
196 template<typename _Tp> _OutputArray(const std::vector<std::vector<_Tp> >& vec);
197 template<typename _Tp> _OutputArray(const std::vector<Mat_<_Tp> >& vec);
198 template<typename _Tp> _OutputArray(const Mat_<_Tp>& m);
199 template<typename _Tp> _OutputArray(const _Tp* vec, int n);
200 template<typename _Tp, int m, int n> _OutputArray(const Matx<_Tp, m, n>& matx);
201 _OutputArray(const UMat& m);
202 _OutputArray(const std::vector<UMat>& vec);
204 virtual bool fixedSize() const;
205 virtual bool fixedType() const;
206 virtual bool needed() const;
207 virtual Mat& getMatRef(int i=-1) const;
208 virtual UMat& getUMatRef(int i=-1) const;
209 virtual cuda::GpuMat& getGpuMatRef() const;
210 virtual ogl::Buffer& getOGlBufferRef() const;
211 virtual cuda::CudaMem& getCudaMemRef() const;
212 virtual void create(Size sz, int type, int i=-1, bool allowTransposed=false, int fixedDepthMask=0) const;
213 virtual void create(int rows, int cols, int type, int i=-1, bool allowTransposed=false, int fixedDepthMask=0) const;
214 virtual void create(int dims, const int* size, int type, int i=-1, bool allowTransposed=false, int fixedDepthMask=0) const;
215 virtual void createSameSize(const _InputArray& arr, int mtype) const;
216 virtual void release() const;
217 virtual void clear() const;
218 virtual void setTo(const _InputArray& value, const _InputArray & mask = _InputArray()) const;
222 class CV_EXPORTS _InputOutputArray : public _OutputArray
226 _InputOutputArray(int _flags, void* _obj);
227 _InputOutputArray(Mat& m);
228 _InputOutputArray(std::vector<Mat>& vec);
229 _InputOutputArray(cuda::GpuMat& d_mat);
230 _InputOutputArray(ogl::Buffer& buf);
231 _InputOutputArray(cuda::CudaMem& cuda_mem);
232 template<typename _Tp> _InputOutputArray(cudev::GpuMat_<_Tp>& m);
233 template<typename _Tp> _InputOutputArray(std::vector<_Tp>& vec);
234 template<typename _Tp> _InputOutputArray(std::vector<std::vector<_Tp> >& vec);
235 template<typename _Tp> _InputOutputArray(std::vector<Mat_<_Tp> >& vec);
236 template<typename _Tp> _InputOutputArray(Mat_<_Tp>& m);
237 template<typename _Tp> _InputOutputArray(_Tp* vec, int n);
238 template<typename _Tp, int m, int n> _InputOutputArray(Matx<_Tp, m, n>& matx);
239 _InputOutputArray(UMat& m);
240 _InputOutputArray(std::vector<UMat>& vec);
242 _InputOutputArray(const Mat& m);
243 _InputOutputArray(const std::vector<Mat>& vec);
244 _InputOutputArray(const cuda::GpuMat& d_mat);
245 _InputOutputArray(const ogl::Buffer& buf);
246 _InputOutputArray(const cuda::CudaMem& cuda_mem);
247 template<typename _Tp> _InputOutputArray(const cudev::GpuMat_<_Tp>& m);
248 template<typename _Tp> _InputOutputArray(const std::vector<_Tp>& vec);
249 template<typename _Tp> _InputOutputArray(const std::vector<std::vector<_Tp> >& vec);
250 template<typename _Tp> _InputOutputArray(const std::vector<Mat_<_Tp> >& vec);
251 template<typename _Tp> _InputOutputArray(const Mat_<_Tp>& m);
252 template<typename _Tp> _InputOutputArray(const _Tp* vec, int n);
253 template<typename _Tp, int m, int n> _InputOutputArray(const Matx<_Tp, m, n>& matx);
254 _InputOutputArray(const UMat& m);
255 _InputOutputArray(const std::vector<UMat>& vec);
258 typedef const _InputArray& InputArray;
259 typedef InputArray InputArrayOfArrays;
260 typedef const _OutputArray& OutputArray;
261 typedef OutputArray OutputArrayOfArrays;
262 typedef const _InputOutputArray& InputOutputArray;
263 typedef InputOutputArray InputOutputArrayOfArrays;
265 CV_EXPORTS InputOutputArray noArray();
267 /////////////////////////////////// MatAllocator //////////////////////////////////////
269 struct CV_EXPORTS UMatData;
272 Custom array allocator
275 class CV_EXPORTS MatAllocator
279 virtual ~MatAllocator() {}
281 // let's comment it off for now to detect and fix all the uses of allocator
282 //virtual void allocate(int dims, const int* sizes, int type, int*& refcount,
283 // uchar*& datastart, uchar*& data, size_t* step) = 0;
284 //virtual void deallocate(int* refcount, uchar* datastart, uchar* data) = 0;
285 virtual UMatData* allocate(int dims, const int* sizes, int type,
286 void* data, size_t* step, int flags) const = 0;
287 virtual bool allocate(UMatData* data, int accessflags) const = 0;
288 virtual void deallocate(UMatData* data) const = 0;
289 virtual void map(UMatData* data, int accessflags) const;
290 virtual void unmap(UMatData* data) const;
291 virtual void download(UMatData* data, void* dst, int dims, const size_t sz[],
292 const size_t srcofs[], const size_t srcstep[],
293 const size_t dststep[]) const;
294 virtual void upload(UMatData* data, const void* src, int dims, const size_t sz[],
295 const size_t dstofs[], const size_t dststep[],
296 const size_t srcstep[]) const;
297 virtual void copy(UMatData* srcdata, UMatData* dstdata, int dims, const size_t sz[],
298 const size_t srcofs[], const size_t srcstep[],
299 const size_t dstofs[], const size_t dststep[], bool sync) const;
301 // default implementation returns DummyBufferPoolController
302 virtual BufferPoolController* getBufferPoolController() const;
306 //////////////////////////////// MatCommaInitializer //////////////////////////////////
309 Comma-separated Matrix Initializer
311 The class instances are usually not created explicitly.
312 Instead, they are created on "matrix << firstValue" operator.
314 The sample below initializes 2x2 rotation matrix:
317 double angle = 30, a = cos(angle*CV_PI/180), b = sin(angle*CV_PI/180);
318 Mat R = (Mat_<double>(2,2) << a, -b, b, a);
321 template<typename _Tp> class MatCommaInitializer_
324 //! the constructor, created by "matrix << firstValue" operator, where matrix is cv::Mat
325 MatCommaInitializer_(Mat_<_Tp>* _m);
326 //! the operator that takes the next value and put it to the matrix
327 template<typename T2> MatCommaInitializer_<_Tp>& operator , (T2 v);
328 //! another form of conversion operator
329 operator Mat_<_Tp>() const;
331 MatIterator_<_Tp> it;
335 /////////////////////////////////////// Mat ///////////////////////////////////////////
337 // note that umatdata might be allocated together
338 // with the matrix data, not as a separate object.
339 // therefore, it does not have constructor or destructor;
340 // it should be explicitly initialized using init().
341 struct CV_EXPORTS UMatData
343 enum { COPY_ON_MAP=1, HOST_COPY_OBSOLETE=2,
344 DEVICE_COPY_OBSOLETE=4, TEMP_UMAT=8, TEMP_COPIED_UMAT=24,
346 UMatData(const MatAllocator* allocator);
349 // provide atomic access to the structure
353 bool hostCopyObsolete() const;
354 bool deviceCopyObsolete() const;
355 bool copyOnMap() const;
356 bool tempUMat() const;
357 bool tempCopiedUMat() const;
358 void markHostCopyObsolete(bool flag);
359 void markDeviceCopyObsolete(bool flag);
361 const MatAllocator* prevAllocator;
362 const MatAllocator* currAllocator;
367 size_t size, capacity;
375 struct CV_EXPORTS UMatDataAutoLock
377 UMatDataAutoLock(UMatData* u);
383 struct CV_EXPORTS MatSize
386 Size operator()() const;
387 const int& operator[](int i) const;
388 int& operator[](int i);
389 operator const int*() const;
390 bool operator == (const MatSize& sz) const;
391 bool operator != (const MatSize& sz) const;
396 struct CV_EXPORTS MatStep
400 const size_t& operator[](int i) const;
401 size_t& operator[](int i);
402 operator size_t() const;
403 MatStep& operator = (size_t s);
408 MatStep& operator = (const MatStep&);
412 The n-dimensional matrix class.
414 The class represents an n-dimensional dense numerical array that can act as
415 a matrix, image, optical flow map, 3-focal tensor etc.
416 It is very similar to CvMat and CvMatND types from earlier versions of OpenCV,
417 and similarly to those types, the matrix can be multi-channel. It also fully supports ROI mechanism.
419 There are many different ways to create cv::Mat object. Here are the some popular ones:
421 <li> using cv::Mat::create(nrows, ncols, type) method or
422 the similar constructor cv::Mat::Mat(nrows, ncols, type[, fill_value]) constructor.
423 A new matrix of the specified size and specifed type will be allocated.
424 "type" has the same meaning as in cvCreateMat function,
425 e.g. CV_8UC1 means 8-bit single-channel matrix, CV_32FC2 means 2-channel (i.e. complex)
426 floating-point matrix etc:
429 // make 7x7 complex matrix filled with 1+3j.
430 cv::Mat M(7,7,CV_32FC2,Scalar(1,3));
431 // and now turn M to 100x60 15-channel 8-bit matrix.
432 // The old content will be deallocated
433 M.create(100,60,CV_8UC(15));
436 As noted in the introduction of this chapter, Mat::create()
437 will only allocate a new matrix when the current matrix dimensionality
438 or type are different from the specified.
440 <li> by using a copy constructor or assignment operator, where on the right side it can
441 be a matrix or expression, see below. Again, as noted in the introduction,
442 matrix assignment is O(1) operation because it only copies the header
443 and increases the reference counter. cv::Mat::clone() method can be used to get a full
444 (a.k.a. deep) copy of the matrix when you need it.
446 <li> by constructing a header for a part of another matrix. It can be a single row, single column,
447 several rows, several columns, rectangular region in the matrix (called a minor in algebra) or
448 a diagonal. Such operations are also O(1), because the new header will reference the same data.
449 You can actually modify a part of the matrix using this feature, e.g.
452 // add 5-th row, multiplied by 3 to the 3rd row
453 M.row(3) = M.row(3) + M.row(5)*3;
455 // now copy 7-th column to the 1-st column
456 // M.col(1) = M.col(7); // this will not work
460 // create new 320x240 image
461 cv::Mat img(Size(320,240),CV_8UC3);
463 cv::Mat roi(img, Rect(10,10,100,100));
464 // fill the ROI with (0,255,0) (which is green in RGB space);
465 // the original 320x240 image will be modified
466 roi = Scalar(0,255,0);
469 Thanks to the additional cv::Mat::datastart and cv::Mat::dataend members, it is possible to
470 compute the relative sub-matrix position in the main "container" matrix using cv::Mat::locateROI():
473 Mat A = Mat::eye(10, 10, CV_32S);
474 // extracts A columns, 1 (inclusive) to 3 (exclusive).
475 Mat B = A(Range::all(), Range(1, 3));
476 // extracts B rows, 5 (inclusive) to 9 (exclusive).
477 // that is, C ~ A(Range(5, 9), Range(1, 3))
478 Mat C = B(Range(5, 9), Range::all());
479 Size size; Point ofs;
480 C.locateROI(size, ofs);
481 // size will be (width=10,height=10) and the ofs will be (x=1, y=5)
484 As in the case of whole matrices, if you need a deep copy, use cv::Mat::clone() method
485 of the extracted sub-matrices.
487 <li> by making a header for user-allocated-data. It can be useful for
489 <li> processing "foreign" data using OpenCV (e.g. when you implement
490 a DirectShow filter or a processing module for gstreamer etc.), e.g.
493 void process_video_frame(const unsigned char* pixels,
494 int width, int height, int step)
496 cv::Mat img(height, width, CV_8UC3, pixels, step);
497 cv::GaussianBlur(img, img, cv::Size(7,7), 1.5, 1.5);
501 <li> for quick initialization of small matrices and/or super-fast element access
504 double m[3][3] = {{a, b, c}, {d, e, f}, {g, h, i}};
505 cv::Mat M = cv::Mat(3, 3, CV_64F, m).inv();
509 partial yet very common cases of this "user-allocated data" case are conversions
510 from CvMat and IplImage to cv::Mat. For this purpose there are special constructors
511 taking pointers to CvMat or IplImage and the optional
512 flag indicating whether to copy the data or not.
514 Backward conversion from cv::Mat to CvMat or IplImage is provided via cast operators
515 cv::Mat::operator CvMat() an cv::Mat::operator IplImage().
516 The operators do not copy the data.
520 IplImage* img = cvLoadImage("greatwave.jpg", 1);
521 Mat mtx(img); // convert IplImage* -> cv::Mat
522 CvMat oldmat = mtx; // convert cv::Mat -> CvMat
523 CV_Assert(oldmat.cols == img->width && oldmat.rows == img->height &&
524 oldmat.data.ptr == (uchar*)img->imageData && oldmat.step == img->widthStep);
527 <li> by using MATLAB-style matrix initializers, cv::Mat::zeros(), cv::Mat::ones(), cv::Mat::eye(), e.g.:
530 // create a double-precision identity martix and add it to M.
531 M += Mat::eye(M.rows, M.cols, CV_64F);
534 <li> by using comma-separated initializer:
537 // create 3x3 double-precision identity matrix
538 Mat M = (Mat_<double>(3,3) << 1, 0, 0, 0, 1, 0, 0, 0, 1);
541 here we first call constructor of cv::Mat_ class (that we describe further) with the proper matrix,
542 and then we just put "<<" operator followed by comma-separated values that can be constants,
543 variables, expressions etc. Also, note the extra parentheses that are needed to avoid compiler errors.
547 Once matrix is created, it will be automatically managed by using reference-counting mechanism
548 (unless the matrix header is built on top of user-allocated data,
549 in which case you should handle the data by yourself).
550 The matrix data will be deallocated when no one points to it;
551 if you want to release the data pointed by a matrix header before the matrix destructor is called,
552 use cv::Mat::release().
554 The next important thing to learn about the matrix class is element access. Here is how the matrix is stored.
555 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,
556 cv::Mat::rows contains the number of matrix rows and cv::Mat::cols - the number of matrix columns. There is yet another member,
557 cv::Mat::step that is used to actually compute address of a matrix element. cv::Mat::step is needed because the matrix can be
558 a part of another matrix or because there can some padding space in the end of each row for a proper alignment.
562 Given these parameters, address of the matrix element M_{ij} is computed as following:
564 addr(M_{ij})=M.data + M.step*i + j*M.elemSize()
566 if you know the matrix element type, e.g. it is float, then you can use cv::Mat::at() method:
568 addr(M_{ij})=&M.at<float>(i,j)
570 (where & is used to convert the reference returned by cv::Mat::at() to a pointer).
571 if you need to process a whole row of matrix, the most efficient way is to get
572 the pointer to the row first, and then just use plain C operator []:
575 // compute sum of positive matrix elements
576 // (assuming that M is double-precision matrix)
578 for(int i = 0; i < M.rows; i++)
580 const double* Mi = M.ptr<double>(i);
581 for(int j = 0; j < M.cols; j++)
582 sum += std::max(Mi[j], 0.);
586 Some operations, like the above one, do not actually depend on the matrix shape,
587 they just process elements of a matrix one by one (or elements from multiple matrices
588 that are sitting in the same place, e.g. matrix addition). Such operations are called
589 element-wise and it makes sense to check whether all the input/output matrices are continuous,
590 i.e. have no gaps in the end of each row, and if yes, process them as a single long row:
593 // compute sum of positive matrix elements, optimized variant
595 int cols = M.cols, rows = M.rows;
601 for(int i = 0; i < rows; i++)
603 const double* Mi = M.ptr<double>(i);
604 for(int j = 0; j < cols; j++)
605 sum += std::max(Mi[j], 0.);
608 in the case of continuous matrix the outer loop body will be executed just once,
609 so the overhead will be smaller, which will be especially noticeable in the case of small matrices.
611 Finally, there are STL-style iterators that are smart enough to skip gaps between successive rows:
613 // compute sum of positive matrix elements, iterator-based variant
615 MatConstIterator_<double> it = M.begin<double>(), it_end = M.end<double>();
616 for(; it != it_end; ++it)
617 sum += std::max(*it, 0.);
620 The matrix iterators are random-access iterators, so they can be passed
621 to any STL algorithm, including std::sort().
626 //! default constructor
628 //! constructs 2D matrix of the specified size and type
629 // (_type is CV_8UC1, CV_64FC3, CV_32SC(12) etc.)
630 Mat(int rows, int cols, int type);
631 Mat(Size size, int type);
632 //! constucts 2D matrix and fills it with the specified value _s.
633 Mat(int rows, int cols, int type, const Scalar& s);
634 Mat(Size size, int type, const Scalar& s);
636 //! constructs n-dimensional matrix
637 Mat(int ndims, const int* sizes, int type);
638 Mat(int ndims, const int* sizes, int type, const Scalar& s);
642 //! constructor for matrix headers pointing to user-allocated data
643 Mat(int rows, int cols, int type, void* data, size_t step=AUTO_STEP);
644 Mat(Size size, int type, void* data, size_t step=AUTO_STEP);
645 Mat(int ndims, const int* sizes, int type, void* data, const size_t* steps=0);
647 //! creates a matrix header for a part of the bigger matrix
648 Mat(const Mat& m, const Range& rowRange, const Range& colRange=Range::all());
649 Mat(const Mat& m, const Rect& roi);
650 Mat(const Mat& m, const Range* ranges);
651 //! builds matrix from std::vector with or without copying the data
652 template<typename _Tp> explicit Mat(const std::vector<_Tp>& vec, bool copyData=false);
653 //! builds matrix from cv::Vec; the data is copied by default
654 template<typename _Tp, int n> explicit Mat(const Vec<_Tp, n>& vec, bool copyData=true);
655 //! builds matrix from cv::Matx; the data is copied by default
656 template<typename _Tp, int m, int n> explicit Mat(const Matx<_Tp, m, n>& mtx, bool copyData=true);
657 //! builds matrix from a 2D point
658 template<typename _Tp> explicit Mat(const Point_<_Tp>& pt, bool copyData=true);
659 //! builds matrix from a 3D point
660 template<typename _Tp> explicit Mat(const Point3_<_Tp>& pt, bool copyData=true);
661 //! builds matrix from comma initializer
662 template<typename _Tp> explicit Mat(const MatCommaInitializer_<_Tp>& commaInitializer);
664 //! download data from GpuMat
665 explicit Mat(const cuda::GpuMat& m);
667 //! destructor - calls release()
669 //! assignment operators
670 Mat& operator = (const Mat& m);
671 Mat& operator = (const MatExpr& expr);
673 //! retrieve UMat from Mat
674 UMat getUMat(int accessFlags) const;
676 //! returns a new matrix header for the specified row
677 Mat row(int y) const;
678 //! returns a new matrix header for the specified column
679 Mat col(int x) const;
680 //! ... for the specified row span
681 Mat rowRange(int startrow, int endrow) const;
682 Mat rowRange(const Range& r) const;
683 //! ... for the specified column span
684 Mat colRange(int startcol, int endcol) const;
685 Mat colRange(const Range& r) const;
686 //! ... for the specified diagonal
687 // (d=0 - the main diagonal,
688 // >0 - a diagonal from the lower half,
689 // <0 - a diagonal from the upper half)
690 Mat diag(int d=0) const;
691 //! constructs a square diagonal matrix which main diagonal is vector "d"
692 static Mat diag(const Mat& d);
694 //! returns deep copy of the matrix, i.e. the data is copied
696 //! copies the matrix content to "m".
697 // It calls m.create(this->size(), this->type()).
698 void copyTo( OutputArray m ) const;
699 //! copies those matrix elements to "m" that are marked with non-zero mask elements.
700 void copyTo( OutputArray m, InputArray mask ) const;
701 //! converts matrix to another datatype with optional scalng. See cvConvertScale.
702 void convertTo( OutputArray m, int rtype, double alpha=1, double beta=0 ) const;
704 void assignTo( Mat& m, int type=-1 ) const;
706 //! sets every matrix element to s
707 Mat& operator = (const Scalar& s);
708 //! sets some of the matrix elements to s, according to the mask
709 Mat& setTo(InputArray value, InputArray mask=noArray());
710 //! creates alternative matrix header for the same data, with different
711 // number of channels and/or different number of rows. see cvReshape.
712 Mat reshape(int cn, int rows=0) const;
713 Mat reshape(int cn, int newndims, const int* newsz) const;
715 //! matrix transposition by means of matrix expressions
717 //! matrix inversion by means of matrix expressions
718 MatExpr inv(int method=DECOMP_LU) const;
719 //! per-element matrix multiplication by means of matrix expressions
720 MatExpr mul(InputArray m, double scale=1) const;
722 //! computes cross-product of 2 3D vectors
723 Mat cross(InputArray m) const;
724 //! computes dot-product
725 double dot(InputArray m) const;
727 //! Matlab-style matrix initialization
728 static MatExpr zeros(int rows, int cols, int type);
729 static MatExpr zeros(Size size, int type);
730 static MatExpr zeros(int ndims, const int* sz, int type);
731 static MatExpr ones(int rows, int cols, int type);
732 static MatExpr ones(Size size, int type);
733 static MatExpr ones(int ndims, const int* sz, int type);
734 static MatExpr eye(int rows, int cols, int type);
735 static MatExpr eye(Size size, int type);
737 //! allocates new matrix data unless the matrix already has specified size and type.
738 // previous data is unreferenced if needed.
739 void create(int rows, int cols, int type);
740 void create(Size size, int type);
741 void create(int ndims, const int* sizes, int type);
743 //! increases the reference counter; use with care to avoid memleaks
745 //! decreases reference counter;
746 // deallocates the data when reference counter reaches 0.
749 //! deallocates the matrix data
751 //! internal use function; properly re-allocates _size, _step arrays
752 void copySize(const Mat& m);
754 //! reserves enough space to fit sz hyper-planes
755 void reserve(size_t sz);
756 //! resizes matrix to the specified number of hyper-planes
757 void resize(size_t sz);
758 //! resizes matrix to the specified number of hyper-planes; initializes the newly added elements
759 void resize(size_t sz, const Scalar& s);
760 //! internal function
761 void push_back_(const void* elem);
762 //! adds element to the end of 1d matrix (or possibly multiple elements when _Tp=Mat)
763 template<typename _Tp> void push_back(const _Tp& elem);
764 template<typename _Tp> void push_back(const Mat_<_Tp>& elem);
765 void push_back(const Mat& m);
766 //! removes several hyper-planes from bottom of the matrix
767 void pop_back(size_t nelems=1);
769 //! locates matrix header within a parent matrix. See below
770 void locateROI( Size& wholeSize, Point& ofs ) const;
771 //! moves/resizes the current matrix ROI inside the parent matrix.
772 Mat& adjustROI( int dtop, int dbottom, int dleft, int dright );
773 //! extracts a rectangular sub-matrix
774 // (this is a generalized form of row, rowRange etc.)
775 Mat operator()( Range rowRange, Range colRange ) const;
776 Mat operator()( const Rect& roi ) const;
777 Mat operator()( const Range* ranges ) const;
779 // //! converts header to CvMat; no data is copied
780 // operator CvMat() const;
781 // //! converts header to CvMatND; no data is copied
782 // operator CvMatND() const;
783 // //! converts header to IplImage; no data is copied
784 // operator IplImage() const;
786 template<typename _Tp> operator std::vector<_Tp>() const;
787 template<typename _Tp, int n> operator Vec<_Tp, n>() const;
788 template<typename _Tp, int m, int n> operator Matx<_Tp, m, n>() const;
790 //! returns true iff the matrix data is continuous
791 // (i.e. when there are no gaps between successive rows).
792 // similar to CV_IS_MAT_CONT(cvmat->type)
793 bool isContinuous() const;
795 //! returns true if the matrix is a submatrix of another matrix
796 bool isSubmatrix() const;
798 //! returns element size in bytes,
799 // similar to CV_ELEM_SIZE(cvmat->type)
800 size_t elemSize() const;
801 //! returns the size of element channel in bytes.
802 size_t elemSize1() const;
803 //! returns element type, similar to CV_MAT_TYPE(cvmat->type)
805 //! returns element type, similar to CV_MAT_DEPTH(cvmat->type)
807 //! returns element type, similar to CV_MAT_CN(cvmat->type)
808 int channels() const;
809 //! returns step/elemSize1()
810 size_t step1(int i=0) const;
811 //! returns true if matrix data is NULL
813 //! returns the total number of matrix elements
814 size_t total() const;
816 //! returns N if the matrix is 1-channel (N x ptdim) or ptdim-channel (1 x N) or (N x 1); negative number otherwise
817 int checkVector(int elemChannels, int depth=-1, bool requireContinuous=true) const;
819 //! returns pointer to i0-th submatrix along the dimension #0
820 uchar* ptr(int i0=0);
821 const uchar* ptr(int i0=0) const;
823 //! returns pointer to (i0,i1) submatrix along the dimensions #0 and #1
824 uchar* ptr(int i0, int i1);
825 const uchar* ptr(int i0, int i1) const;
827 //! returns pointer to (i0,i1,i3) submatrix along the dimensions #0, #1, #2
828 uchar* ptr(int i0, int i1, int i2);
829 const uchar* ptr(int i0, int i1, int i2) const;
831 //! returns pointer to the matrix element
832 uchar* ptr(const int* idx);
833 //! returns read-only pointer to the matrix element
834 const uchar* ptr(const int* idx) const;
836 template<int n> uchar* ptr(const Vec<int, n>& idx);
837 template<int n> const uchar* ptr(const Vec<int, n>& idx) const;
839 //! template version of the above method
840 template<typename _Tp> _Tp* ptr(int i0=0);
841 template<typename _Tp> const _Tp* ptr(int i0=0) const;
843 template<typename _Tp> _Tp* ptr(int i0, int i1);
844 template<typename _Tp> const _Tp* ptr(int i0, int i1) const;
846 template<typename _Tp> _Tp* ptr(int i0, int i1, int i2);
847 template<typename _Tp> const _Tp* ptr(int i0, int i1, int i2) const;
849 template<typename _Tp> _Tp* ptr(const int* idx);
850 template<typename _Tp> const _Tp* ptr(const int* idx) const;
852 template<typename _Tp, int n> _Tp* ptr(const Vec<int, n>& idx);
853 template<typename _Tp, int n> const _Tp* ptr(const Vec<int, n>& idx) const;
855 //! the same as above, with the pointer dereferencing
856 template<typename _Tp> _Tp& at(int i0=0);
857 template<typename _Tp> const _Tp& at(int i0=0) const;
859 template<typename _Tp> _Tp& at(int i0, int i1);
860 template<typename _Tp> const _Tp& at(int i0, int i1) const;
862 template<typename _Tp> _Tp& at(int i0, int i1, int i2);
863 template<typename _Tp> const _Tp& at(int i0, int i1, int i2) const;
865 template<typename _Tp> _Tp& at(const int* idx);
866 template<typename _Tp> const _Tp& at(const int* idx) const;
868 template<typename _Tp, int n> _Tp& at(const Vec<int, n>& idx);
869 template<typename _Tp, int n> const _Tp& at(const Vec<int, n>& idx) const;
871 //! special versions for 2D arrays (especially convenient for referencing image pixels)
872 template<typename _Tp> _Tp& at(Point pt);
873 template<typename _Tp> const _Tp& at(Point pt) const;
875 //! template methods for iteration over matrix elements.
876 // the iterators take care of skipping gaps in the end of rows (if any)
877 template<typename _Tp> MatIterator_<_Tp> begin();
878 template<typename _Tp> MatIterator_<_Tp> end();
879 template<typename _Tp> MatConstIterator_<_Tp> begin() const;
880 template<typename _Tp> MatConstIterator_<_Tp> end() const;
882 enum { MAGIC_VAL = 0x42FF0000, AUTO_STEP = 0, CONTINUOUS_FLAG = CV_MAT_CONT_FLAG, SUBMATRIX_FLAG = CV_SUBMAT_FLAG };
883 enum { MAGIC_MASK = 0xFFFF0000, TYPE_MASK = 0x00000FFF, DEPTH_MASK = 7 };
885 /*! includes several bit-fields:
886 - the magic signature
892 //! the matrix dimensionality, >= 2
894 //! the number of rows and columns or (-1, -1) when the matrix has more than 2 dimensions
896 //! pointer to the data
899 //! helper fields used in locateROI and adjustROI
905 MatAllocator* allocator;
906 //! and the standard allocator
907 static MatAllocator* getStdAllocator();
909 //! interaction with UMat
919 ///////////////////////////////// Mat_<_Tp> ////////////////////////////////////
922 Template matrix class derived from Mat
924 The class Mat_ is a "thin" template wrapper on top of cv::Mat. It does not have any extra data fields,
925 nor it or cv::Mat have any virtual methods and thus references or pointers to these two classes
926 can be safely converted one to another. But do it with care, for example:
929 // create 100x100 8-bit matrix
930 Mat M(100,100,CV_8U);
931 // this will compile fine. no any data conversion will be done.
932 Mat_<float>& M1 = (Mat_<float>&)M;
933 // the program will likely crash at the statement below
937 While cv::Mat is sufficient in most cases, cv::Mat_ can be more convenient if you use a lot of element
938 access operations and if you know matrix type at compile time.
939 Note that cv::Mat::at<_Tp>(int y, int x) and cv::Mat_<_Tp>::operator ()(int y, int x) do absolutely the
940 same thing and run at the same speed, but the latter is certainly shorter:
943 Mat_<double> M(20,20);
944 for(int i = 0; i < M.rows; i++)
945 for(int j = 0; j < M.cols; j++)
949 cout << E.at<double>(0,0)/E.at<double>(M.rows-1,0);
952 It is easy to use Mat_ for multi-channel images/matrices - just pass cv::Vec as cv::Mat_ template parameter:
955 // allocate 320x240 color image and fill it with green (in RGB space)
956 Mat_<Vec3b> img(240, 320, Vec3b(0,255,0));
957 // now draw a diagonal white line
958 for(int i = 0; i < 100; i++)
959 img(i,i)=Vec3b(255,255,255);
960 // and now modify the 2nd (red) channel of each pixel
961 for(int i = 0; i < img.rows; i++)
962 for(int j = 0; j < img.cols; j++)
963 img(i,j)[2] ^= (uchar)(i ^ j); // img(y,x)[c] accesses c-th channel of the pixel (x,y)
966 template<typename _Tp> class Mat_ : public Mat
969 typedef _Tp value_type;
970 typedef typename DataType<_Tp>::channel_type channel_type;
971 typedef MatIterator_<_Tp> iterator;
972 typedef MatConstIterator_<_Tp> const_iterator;
974 //! default constructor
976 //! equivalent to Mat(_rows, _cols, DataType<_Tp>::type)
977 Mat_(int _rows, int _cols);
978 //! constructor that sets each matrix element to specified value
979 Mat_(int _rows, int _cols, const _Tp& value);
980 //! equivalent to Mat(_size, DataType<_Tp>::type)
981 explicit Mat_(Size _size);
982 //! constructor that sets each matrix element to specified value
983 Mat_(Size _size, const _Tp& value);
984 //! n-dim array constructor
985 Mat_(int _ndims, const int* _sizes);
986 //! n-dim array constructor that sets each matrix element to specified value
987 Mat_(int _ndims, const int* _sizes, const _Tp& value);
988 //! copy/conversion contructor. If m is of different type, it's converted
992 //! constructs a matrix on top of user-allocated data. step is in bytes(!!!), regardless of the type
993 Mat_(int _rows, int _cols, _Tp* _data, size_t _step=AUTO_STEP);
994 //! constructs n-dim matrix on top of user-allocated data. steps are in bytes(!!!), regardless of the type
995 Mat_(int _ndims, const int* _sizes, _Tp* _data, const size_t* _steps=0);
996 //! selects a submatrix
997 Mat_(const Mat_& m, const Range& rowRange, const Range& colRange=Range::all());
998 //! selects a submatrix
999 Mat_(const Mat_& m, const Rect& roi);
1000 //! selects a submatrix, n-dim version
1001 Mat_(const Mat_& m, const Range* ranges);
1002 //! from a matrix expression
1003 explicit Mat_(const MatExpr& e);
1004 //! makes a matrix out of Vec, std::vector, Point_ or Point3_. The matrix will have a single column
1005 explicit Mat_(const std::vector<_Tp>& vec, bool copyData=false);
1006 template<int n> explicit Mat_(const Vec<typename DataType<_Tp>::channel_type, n>& vec, bool copyData=true);
1007 template<int m, int n> explicit Mat_(const Matx<typename DataType<_Tp>::channel_type, m, n>& mtx, bool copyData=true);
1008 explicit Mat_(const Point_<typename DataType<_Tp>::channel_type>& pt, bool copyData=true);
1009 explicit Mat_(const Point3_<typename DataType<_Tp>::channel_type>& pt, bool copyData=true);
1010 explicit Mat_(const MatCommaInitializer_<_Tp>& commaInitializer);
1012 Mat_& operator = (const Mat& m);
1013 Mat_& operator = (const Mat_& m);
1014 //! set all the elements to s.
1015 Mat_& operator = (const _Tp& s);
1016 //! assign a matrix expression
1017 Mat_& operator = (const MatExpr& e);
1019 //! iterators; they are smart enough to skip gaps in the end of rows
1022 const_iterator begin() const;
1023 const_iterator end() const;
1025 //! equivalent to Mat::create(_rows, _cols, DataType<_Tp>::type)
1026 void create(int _rows, int _cols);
1027 //! equivalent to Mat::create(_size, DataType<_Tp>::type)
1028 void create(Size _size);
1029 //! equivalent to Mat::create(_ndims, _sizes, DatType<_Tp>::type)
1030 void create(int _ndims, const int* _sizes);
1032 Mat_ cross(const Mat_& m) const;
1033 //! data type conversion
1034 template<typename T2> operator Mat_<T2>() const;
1035 //! overridden forms of Mat::row() etc.
1036 Mat_ row(int y) const;
1037 Mat_ col(int x) const;
1038 Mat_ diag(int d=0) const;
1041 //! overridden forms of Mat::elemSize() etc.
1042 size_t elemSize() const;
1043 size_t elemSize1() const;
1046 int channels() const;
1047 size_t step1(int i=0) const;
1048 //! returns step()/sizeof(_Tp)
1049 size_t stepT(int i=0) const;
1051 //! overridden forms of Mat::zeros() etc. Data type is omitted, of course
1052 static MatExpr zeros(int rows, int cols);
1053 static MatExpr zeros(Size size);
1054 static MatExpr zeros(int _ndims, const int* _sizes);
1055 static MatExpr ones(int rows, int cols);
1056 static MatExpr ones(Size size);
1057 static MatExpr ones(int _ndims, const int* _sizes);
1058 static MatExpr eye(int rows, int cols);
1059 static MatExpr eye(Size size);
1061 //! some more overriden methods
1062 Mat_& adjustROI( int dtop, int dbottom, int dleft, int dright );
1063 Mat_ operator()( const Range& rowRange, const Range& colRange ) const;
1064 Mat_ operator()( const Rect& roi ) const;
1065 Mat_ operator()( const Range* ranges ) const;
1067 //! more convenient forms of row and element access operators
1068 _Tp* operator [](int y);
1069 const _Tp* operator [](int y) const;
1071 //! returns reference to the specified element
1072 _Tp& operator ()(const int* idx);
1073 //! returns read-only reference to the specified element
1074 const _Tp& operator ()(const int* idx) const;
1076 //! returns reference to the specified element
1077 template<int n> _Tp& operator ()(const Vec<int, n>& idx);
1078 //! returns read-only reference to the specified element
1079 template<int n> const _Tp& operator ()(const Vec<int, n>& idx) const;
1081 //! returns reference to the specified element (1D case)
1082 _Tp& operator ()(int idx0);
1083 //! returns read-only reference to the specified element (1D case)
1084 const _Tp& operator ()(int idx0) const;
1085 //! returns reference to the specified element (2D case)
1086 _Tp& operator ()(int idx0, int idx1);
1087 //! returns read-only reference to the specified element (2D case)
1088 const _Tp& operator ()(int idx0, int idx1) const;
1089 //! returns reference to the specified element (3D case)
1090 _Tp& operator ()(int idx0, int idx1, int idx2);
1091 //! returns read-only reference to the specified element (3D case)
1092 const _Tp& operator ()(int idx0, int idx1, int idx2) const;
1094 _Tp& operator ()(Point pt);
1095 const _Tp& operator ()(Point pt) const;
1097 //! conversion to vector.
1098 operator std::vector<_Tp>() const;
1099 //! conversion to Vec
1100 template<int n> operator Vec<typename DataType<_Tp>::channel_type, n>() const;
1101 //! conversion to Matx
1102 template<int m, int n> operator Matx<typename DataType<_Tp>::channel_type, m, n>() const;
1105 typedef Mat_<uchar> Mat1b;
1106 typedef Mat_<Vec2b> Mat2b;
1107 typedef Mat_<Vec3b> Mat3b;
1108 typedef Mat_<Vec4b> Mat4b;
1110 typedef Mat_<short> Mat1s;
1111 typedef Mat_<Vec2s> Mat2s;
1112 typedef Mat_<Vec3s> Mat3s;
1113 typedef Mat_<Vec4s> Mat4s;
1115 typedef Mat_<ushort> Mat1w;
1116 typedef Mat_<Vec2w> Mat2w;
1117 typedef Mat_<Vec3w> Mat3w;
1118 typedef Mat_<Vec4w> Mat4w;
1120 typedef Mat_<int> Mat1i;
1121 typedef Mat_<Vec2i> Mat2i;
1122 typedef Mat_<Vec3i> Mat3i;
1123 typedef Mat_<Vec4i> Mat4i;
1125 typedef Mat_<float> Mat1f;
1126 typedef Mat_<Vec2f> Mat2f;
1127 typedef Mat_<Vec3f> Mat3f;
1128 typedef Mat_<Vec4f> Mat4f;
1130 typedef Mat_<double> Mat1d;
1131 typedef Mat_<Vec2d> Mat2d;
1132 typedef Mat_<Vec3d> Mat3d;
1133 typedef Mat_<Vec4d> Mat4d;
1135 class CV_EXPORTS UMat
1138 //! default constructor
1140 //! constructs 2D matrix of the specified size and type
1141 // (_type is CV_8UC1, CV_64FC3, CV_32SC(12) etc.)
1142 UMat(int rows, int cols, int type);
1143 UMat(Size size, int type);
1144 //! constucts 2D matrix and fills it with the specified value _s.
1145 UMat(int rows, int cols, int type, const Scalar& s);
1146 UMat(Size size, int type, const Scalar& s);
1148 //! constructs n-dimensional matrix
1149 UMat(int ndims, const int* sizes, int type);
1150 UMat(int ndims, const int* sizes, int type, const Scalar& s);
1152 //! copy constructor
1153 UMat(const UMat& m);
1155 //! creates a matrix header for a part of the bigger matrix
1156 UMat(const UMat& m, const Range& rowRange, const Range& colRange=Range::all());
1157 UMat(const UMat& m, const Rect& roi);
1158 UMat(const UMat& m, const Range* ranges);
1159 //! builds matrix from std::vector with or without copying the data
1160 template<typename _Tp> explicit UMat(const std::vector<_Tp>& vec, bool copyData=false);
1161 //! builds matrix from cv::Vec; the data is copied by default
1162 template<typename _Tp, int n> explicit UMat(const Vec<_Tp, n>& vec, bool copyData=true);
1163 //! builds matrix from cv::Matx; the data is copied by default
1164 template<typename _Tp, int m, int n> explicit UMat(const Matx<_Tp, m, n>& mtx, bool copyData=true);
1165 //! builds matrix from a 2D point
1166 template<typename _Tp> explicit UMat(const Point_<_Tp>& pt, bool copyData=true);
1167 //! builds matrix from a 3D point
1168 template<typename _Tp> explicit UMat(const Point3_<_Tp>& pt, bool copyData=true);
1169 //! builds matrix from comma initializer
1170 template<typename _Tp> explicit UMat(const MatCommaInitializer_<_Tp>& commaInitializer);
1172 //! destructor - calls release()
1174 //! assignment operators
1175 UMat& operator = (const UMat& m);
1177 Mat getMat(int flags) const;
1179 //! returns a new matrix header for the specified row
1180 UMat row(int y) const;
1181 //! returns a new matrix header for the specified column
1182 UMat col(int x) const;
1183 //! ... for the specified row span
1184 UMat rowRange(int startrow, int endrow) const;
1185 UMat rowRange(const Range& r) const;
1186 //! ... for the specified column span
1187 UMat colRange(int startcol, int endcol) const;
1188 UMat colRange(const Range& r) const;
1189 //! ... for the specified diagonal
1190 // (d=0 - the main diagonal,
1191 // >0 - a diagonal from the lower half,
1192 // <0 - a diagonal from the upper half)
1193 UMat diag(int d=0) const;
1194 //! constructs a square diagonal matrix which main diagonal is vector "d"
1195 static UMat diag(const UMat& d);
1197 //! returns deep copy of the matrix, i.e. the data is copied
1199 //! copies the matrix content to "m".
1200 // It calls m.create(this->size(), this->type()).
1201 void copyTo( OutputArray m ) const;
1202 //! copies those matrix elements to "m" that are marked with non-zero mask elements.
1203 void copyTo( OutputArray m, InputArray mask ) const;
1204 //! converts matrix to another datatype with optional scalng. See cvConvertScale.
1205 void convertTo( OutputArray m, int rtype, double alpha=1, double beta=0 ) const;
1207 void assignTo( UMat& m, int type=-1 ) const;
1209 //! sets every matrix element to s
1210 UMat& operator = (const Scalar& s);
1211 //! sets some of the matrix elements to s, according to the mask
1212 UMat& setTo(InputArray value, InputArray mask=noArray());
1213 //! creates alternative matrix header for the same data, with different
1214 // number of channels and/or different number of rows. see cvReshape.
1215 UMat reshape(int cn, int rows=0) const;
1216 UMat reshape(int cn, int newndims, const int* newsz) const;
1218 //! matrix transposition by means of matrix expressions
1220 //! matrix inversion by means of matrix expressions
1221 UMat inv(int method=DECOMP_LU) const;
1222 //! per-element matrix multiplication by means of matrix expressions
1223 UMat mul(InputArray m, double scale=1) const;
1225 //! computes dot-product
1226 double dot(InputArray m) const;
1228 //! Matlab-style matrix initialization
1229 static UMat zeros(int rows, int cols, int type);
1230 static UMat zeros(Size size, int type);
1231 static UMat zeros(int ndims, const int* sz, int type);
1232 static UMat ones(int rows, int cols, int type);
1233 static UMat ones(Size size, int type);
1234 static UMat ones(int ndims, const int* sz, int type);
1235 static UMat eye(int rows, int cols, int type);
1236 static UMat eye(Size size, int type);
1238 //! allocates new matrix data unless the matrix already has specified size and type.
1239 // previous data is unreferenced if needed.
1240 void create(int rows, int cols, int type);
1241 void create(Size size, int type);
1242 void create(int ndims, const int* sizes, int type);
1244 //! increases the reference counter; use with care to avoid memleaks
1246 //! decreases reference counter;
1247 // deallocates the data when reference counter reaches 0.
1250 //! deallocates the matrix data
1252 //! internal use function; properly re-allocates _size, _step arrays
1253 void copySize(const UMat& m);
1255 //! locates matrix header within a parent matrix. See below
1256 void locateROI( Size& wholeSize, Point& ofs ) const;
1257 //! moves/resizes the current matrix ROI inside the parent matrix.
1258 UMat& adjustROI( int dtop, int dbottom, int dleft, int dright );
1259 //! extracts a rectangular sub-matrix
1260 // (this is a generalized form of row, rowRange etc.)
1261 UMat operator()( Range rowRange, Range colRange ) const;
1262 UMat operator()( const Rect& roi ) const;
1263 UMat operator()( const Range* ranges ) const;
1265 //! returns true iff the matrix data is continuous
1266 // (i.e. when there are no gaps between successive rows).
1267 // similar to CV_IS_MAT_CONT(cvmat->type)
1268 bool isContinuous() const;
1270 //! returns true if the matrix is a submatrix of another matrix
1271 bool isSubmatrix() const;
1273 //! returns element size in bytes,
1274 // similar to CV_ELEM_SIZE(cvmat->type)
1275 size_t elemSize() const;
1276 //! returns the size of element channel in bytes.
1277 size_t elemSize1() const;
1278 //! returns element type, similar to CV_MAT_TYPE(cvmat->type)
1280 //! returns element type, similar to CV_MAT_DEPTH(cvmat->type)
1282 //! returns element type, similar to CV_MAT_CN(cvmat->type)
1283 int channels() const;
1284 //! returns step/elemSize1()
1285 size_t step1(int i=0) const;
1286 //! returns true if matrix data is NULL
1288 //! returns the total number of matrix elements
1289 size_t total() const;
1291 //! returns N if the matrix is 1-channel (N x ptdim) or ptdim-channel (1 x N) or (N x 1); negative number otherwise
1292 int checkVector(int elemChannels, int depth=-1, bool requireContinuous=true) const;
1294 void* handle(int accessFlags) const;
1295 void ndoffset(size_t* ofs) const;
1297 enum { MAGIC_VAL = 0x42FF0000, AUTO_STEP = 0, CONTINUOUS_FLAG = CV_MAT_CONT_FLAG, SUBMATRIX_FLAG = CV_SUBMAT_FLAG };
1298 enum { MAGIC_MASK = 0xFFFF0000, TYPE_MASK = 0x00000FFF, DEPTH_MASK = 7 };
1300 /*! includes several bit-fields:
1301 - the magic signature
1304 - number of channels
1307 //! the matrix dimensionality, >= 2
1309 //! the number of rows and columns or (-1, -1) when the matrix has more than 2 dimensions
1312 //! custom allocator
1313 MatAllocator* allocator;
1314 //! and the standard allocator
1315 static MatAllocator* getStdAllocator();
1317 // black-box container of UMat data
1320 // offset of the submatrix (or 0)
1330 /////////////////////////// multi-dimensional sparse matrix //////////////////////////
1333 Sparse matrix class.
1335 The class represents multi-dimensional sparse numerical arrays. Such a sparse array can store elements
1336 of any type that cv::Mat is able to store. "Sparse" means that only non-zero elements
1337 are stored (though, as a result of some operations on a sparse matrix, some of its stored elements
1338 can actually become 0. It's user responsibility to detect such elements and delete them using cv::SparseMat::erase().
1339 The non-zero elements are stored in a hash table that grows when it's filled enough,
1340 so that the search time remains O(1) in average. Elements can be accessed using the following methods:
1343 <li>Query operations: cv::SparseMat::ptr() and the higher-level cv::SparseMat::ref(),
1344 cv::SparseMat::value() and cv::SparseMat::find, for example:
1347 int size[] = {10, 10, 10, 10, 10};
1348 SparseMat sparse_mat(dims, size, CV_32F);
1349 for(int i = 0; i < 1000; i++)
1352 for(int k = 0; k < dims; k++)
1353 idx[k] = rand()%sparse_mat.size(k);
1354 sparse_mat.ref<float>(idx) += 1.f;
1358 <li>Sparse matrix iterators. Like cv::Mat iterators and unlike cv::Mat iterators, the sparse matrix iterators are STL-style,
1359 that is, the iteration is done as following:
1361 // prints elements of a sparse floating-point matrix and the sum of elements.
1362 SparseMatConstIterator_<float>
1363 it = sparse_mat.begin<float>(),
1364 it_end = sparse_mat.end<float>();
1366 int dims = sparse_mat.dims();
1367 for(; it != it_end; ++it)
1369 // print element indices and the element value
1370 const Node* n = it.node();
1372 for(int i = 0; i < dims; i++)
1373 printf("%3d%c", n->idx[i], i < dims-1 ? ',' : ')');
1374 printf(": %f\n", *it);
1377 printf("Element sum is %g\n", s);
1379 If you run this loop, you will notice that elements are enumerated
1380 in no any logical order (lexicographical etc.),
1381 they come in the same order as they stored in the hash table, i.e. semi-randomly.
1383 You may collect pointers to the nodes and sort them to get the proper ordering.
1384 Note, however, that pointers to the nodes may become invalid when you add more
1385 elements to the matrix; this is because of possible buffer reallocation.
1387 <li>A combination of the above 2 methods when you need to process 2 or more sparse
1388 matrices simultaneously, e.g. this is how you can compute unnormalized
1389 cross-correlation of the 2 floating-point sparse matrices:
1391 double crossCorr(const SparseMat& a, const SparseMat& b)
1393 const SparseMat *_a = &a, *_b = &b;
1394 // if b contains less elements than a,
1395 // it's faster to iterate through b
1396 if(_a->nzcount() > _b->nzcount())
1398 SparseMatConstIterator_<float> it = _a->begin<float>(),
1399 it_end = _a->end<float>();
1401 for(; it != it_end; ++it)
1403 // take the next element from the first matrix
1405 const Node* anode = it.node();
1406 // and try to find element with the same index in the second matrix.
1407 // since the hash value depends only on the element index,
1408 // we reuse hashvalue stored in the node
1409 float bvalue = _b->value<float>(anode->idx,&anode->hashval);
1410 ccorr += avalue*bvalue;
1417 class CV_EXPORTS SparseMat
1420 typedef SparseMatIterator iterator;
1421 typedef SparseMatConstIterator const_iterator;
1423 enum { MAGIC_VAL=0x42FD0000, MAX_DIM=32, HASH_SCALE=0x5bd1e995, HASH_BIT=0x80000000 };
1425 //! the sparse matrix header
1426 struct CV_EXPORTS Hdr
1428 Hdr(int _dims, const int* _sizes, int _type);
1436 std::vector<uchar> pool;
1437 std::vector<size_t> hashtab;
1441 //! sparse matrix node - element of a hash table
1442 struct CV_EXPORTS Node
1446 //! index of the next node in the same hash table entry
1448 //! index of the matrix element
1452 //! default constructor
1454 //! creates matrix of the specified size and type
1455 SparseMat(int dims, const int* _sizes, int _type);
1456 //! copy constructor
1457 SparseMat(const SparseMat& m);
1458 //! converts dense 2d matrix to the sparse form
1460 \param m the input matrix
1462 explicit SparseMat(const Mat& m);
1463 //! converts old-style sparse matrix to the new-style. All the data is copied
1464 //SparseMat(const CvSparseMat* m);
1468 //! assignment operator. This is O(1) operation, i.e. no data is copied
1469 SparseMat& operator = (const SparseMat& m);
1470 //! equivalent to the corresponding constructor
1471 SparseMat& operator = (const Mat& m);
1473 //! creates full copy of the matrix
1474 SparseMat clone() const;
1476 //! copies all the data to the destination matrix. All the previous content of m is erased
1477 void copyTo( SparseMat& m ) const;
1478 //! converts sparse matrix to dense matrix.
1479 void copyTo( Mat& m ) const;
1480 //! multiplies all the matrix elements by the specified scale factor alpha and converts the results to the specified data type
1481 void convertTo( SparseMat& m, int rtype, double alpha=1 ) const;
1482 //! converts sparse matrix to dense n-dim matrix with optional type conversion and scaling.
1484 \param rtype The output matrix data type. When it is =-1, the output array will have the same data type as (*this)
1485 \param alpha The scale factor
1486 \param beta The optional delta added to the scaled values before the conversion
1488 void convertTo( Mat& m, int rtype, double alpha=1, double beta=0 ) const;
1491 void assignTo( SparseMat& m, int type=-1 ) const;
1493 //! reallocates sparse matrix.
1495 If the matrix already had the proper size and type,
1496 it is simply cleared with clear(), otherwise,
1497 the old matrix is released (using release()) and the new one is allocated.
1499 void create(int dims, const int* _sizes, int _type);
1500 //! sets all the sparse matrix elements to 0, which means clearing the hash table.
1502 //! manually increments the reference counter to the header.
1504 // decrements the header reference counter. When the counter reaches 0, the header and all the underlying data are deallocated.
1507 //! converts sparse matrix to the old-style representation; all the elements are copied.
1508 //operator CvSparseMat*() const;
1509 //! returns the size of each element in bytes (not including the overhead - the space occupied by SparseMat::Node elements)
1510 size_t elemSize() const;
1511 //! returns elemSize()/channels()
1512 size_t elemSize1() const;
1514 //! returns type of sparse matrix elements
1516 //! returns the depth of sparse matrix elements
1518 //! returns the number of channels
1519 int channels() const;
1521 //! returns the array of sizes, or NULL if the matrix is not allocated
1522 const int* size() const;
1523 //! returns the size of i-th matrix dimension (or 0)
1524 int size(int i) const;
1525 //! returns the matrix dimensionality
1527 //! returns the number of non-zero elements (=the number of hash table nodes)
1528 size_t nzcount() const;
1530 //! computes the element hash value (1D case)
1531 size_t hash(int i0) const;
1532 //! computes the element hash value (2D case)
1533 size_t hash(int i0, int i1) const;
1534 //! computes the element hash value (3D case)
1535 size_t hash(int i0, int i1, int i2) const;
1536 //! computes the element hash value (nD case)
1537 size_t hash(const int* idx) const;
1541 specialized variants for 1D, 2D, 3D cases and the generic_type one for n-D case.
1543 return pointer to the matrix element.
1545 <li>if the element is there (it's non-zero), the pointer to it is returned
1546 <li>if it's not there and createMissing=false, NULL pointer is returned
1547 <li>if it's not there and createMissing=true, then the new element
1548 is created and initialized with 0. Pointer to it is returned
1549 <li>if the optional hashval pointer is not NULL, the element hash value is
1550 not computed, but *hashval is taken instead.
1553 //! returns pointer to the specified element (1D case)
1554 uchar* ptr(int i0, bool createMissing, size_t* hashval=0);
1555 //! returns pointer to the specified element (2D case)
1556 uchar* ptr(int i0, int i1, bool createMissing, size_t* hashval=0);
1557 //! returns pointer to the specified element (3D case)
1558 uchar* ptr(int i0, int i1, int i2, bool createMissing, size_t* hashval=0);
1559 //! returns pointer to the specified element (nD case)
1560 uchar* ptr(const int* idx, bool createMissing, size_t* hashval=0);
1565 return read-write reference to the specified sparse matrix element.
1567 ref<_Tp>(i0,...[,hashval]) is equivalent to *(_Tp*)ptr(i0,...,true[,hashval]).
1568 The methods always return a valid reference.
1569 If the element did not exist, it is created and initialiazed with 0.
1571 //! returns reference to the specified element (1D case)
1572 template<typename _Tp> _Tp& ref(int i0, size_t* hashval=0);
1573 //! returns reference to the specified element (2D case)
1574 template<typename _Tp> _Tp& ref(int i0, int i1, size_t* hashval=0);
1575 //! returns reference to the specified element (3D case)
1576 template<typename _Tp> _Tp& ref(int i0, int i1, int i2, size_t* hashval=0);
1577 //! returns reference to the specified element (nD case)
1578 template<typename _Tp> _Tp& ref(const int* idx, size_t* hashval=0);
1583 return value of the specified sparse matrix element.
1585 value<_Tp>(i0,...[,hashval]) is equivalent
1588 { const _Tp* p = find<_Tp>(i0,...[,hashval]); return p ? *p : _Tp(); }
1591 That is, if the element did not exist, the methods return 0.
1593 //! returns value of the specified element (1D case)
1594 template<typename _Tp> _Tp value(int i0, size_t* hashval=0) const;
1595 //! returns value of the specified element (2D case)
1596 template<typename _Tp> _Tp value(int i0, int i1, size_t* hashval=0) const;
1597 //! returns value of the specified element (3D case)
1598 template<typename _Tp> _Tp value(int i0, int i1, int i2, size_t* hashval=0) const;
1599 //! returns value of the specified element (nD case)
1600 template<typename _Tp> _Tp value(const int* idx, size_t* hashval=0) const;
1605 Return pointer to the specified sparse matrix element if it exists
1607 find<_Tp>(i0,...[,hashval]) is equivalent to (_const Tp*)ptr(i0,...false[,hashval]).
1609 If the specified element does not exist, the methods return NULL.
1611 //! returns pointer to the specified element (1D case)
1612 template<typename _Tp> const _Tp* find(int i0, size_t* hashval=0) const;
1613 //! returns pointer to the specified element (2D case)
1614 template<typename _Tp> const _Tp* find(int i0, int i1, size_t* hashval=0) const;
1615 //! returns pointer to the specified element (3D case)
1616 template<typename _Tp> const _Tp* find(int i0, int i1, int i2, size_t* hashval=0) const;
1617 //! returns pointer to the specified element (nD case)
1618 template<typename _Tp> const _Tp* find(const int* idx, size_t* hashval=0) const;
1620 //! erases the specified element (2D case)
1621 void erase(int i0, int i1, size_t* hashval=0);
1622 //! erases the specified element (3D case)
1623 void erase(int i0, int i1, int i2, size_t* hashval=0);
1624 //! erases the specified element (nD case)
1625 void erase(const int* idx, size_t* hashval=0);
1629 return the sparse matrix iterator pointing to the first sparse matrix element
1631 //! returns the sparse matrix iterator at the matrix beginning
1632 SparseMatIterator begin();
1633 //! returns the sparse matrix iterator at the matrix beginning
1634 template<typename _Tp> SparseMatIterator_<_Tp> begin();
1635 //! returns the read-only sparse matrix iterator at the matrix beginning
1636 SparseMatConstIterator begin() const;
1637 //! returns the read-only sparse matrix iterator at the matrix beginning
1638 template<typename _Tp> SparseMatConstIterator_<_Tp> begin() const;
1641 return the sparse matrix iterator pointing to the element following the last sparse matrix element
1643 //! returns the sparse matrix iterator at the matrix end
1644 SparseMatIterator end();
1645 //! returns the read-only sparse matrix iterator at the matrix end
1646 SparseMatConstIterator end() const;
1647 //! returns the typed sparse matrix iterator at the matrix end
1648 template<typename _Tp> SparseMatIterator_<_Tp> end();
1649 //! returns the typed read-only sparse matrix iterator at the matrix end
1650 template<typename _Tp> SparseMatConstIterator_<_Tp> end() const;
1652 //! returns the value stored in the sparse martix node
1653 template<typename _Tp> _Tp& value(Node* n);
1654 //! returns the value stored in the sparse martix node
1655 template<typename _Tp> const _Tp& value(const Node* n) const;
1657 ////////////// some internal-use methods ///////////////
1658 Node* node(size_t nidx);
1659 const Node* node(size_t nidx) const;
1661 uchar* newNode(const int* idx, size_t hashval);
1662 void removeNode(size_t hidx, size_t nidx, size_t previdx);
1663 void resizeHashTab(size_t newsize);
1671 ///////////////////////////////// SparseMat_<_Tp> ////////////////////////////////////
1674 The Template Sparse Matrix class derived from cv::SparseMat
1676 The class provides slightly more convenient operations for accessing elements.
1681 SparseMat_<int> m_ = (SparseMat_<int>&)m;
1682 m_.ref(1)++; // equivalent to m.ref<int>(1)++;
1683 m_.ref(2) += m_(3); // equivalent to m.ref<int>(2) += m.value<int>(3);
1686 template<typename _Tp> class SparseMat_ : public SparseMat
1689 typedef SparseMatIterator_<_Tp> iterator;
1690 typedef SparseMatConstIterator_<_Tp> const_iterator;
1692 //! the default constructor
1694 //! the full constructor equivelent to SparseMat(dims, _sizes, DataType<_Tp>::type)
1695 SparseMat_(int dims, const int* _sizes);
1696 //! the copy constructor. If DataType<_Tp>.type != m.type(), the m elements are converted
1697 SparseMat_(const SparseMat& m);
1698 //! the copy constructor. This is O(1) operation - no data is copied
1699 SparseMat_(const SparseMat_& m);
1700 //! converts dense matrix to the sparse form
1701 SparseMat_(const Mat& m);
1702 //! converts the old-style sparse matrix to the C++ class. All the elements are copied
1703 //SparseMat_(const CvSparseMat* m);
1704 //! the assignment operator. If DataType<_Tp>.type != m.type(), the m elements are converted
1705 SparseMat_& operator = (const SparseMat& m);
1706 //! the assignment operator. This is O(1) operation - no data is copied
1707 SparseMat_& operator = (const SparseMat_& m);
1708 //! converts dense matrix to the sparse form
1709 SparseMat_& operator = (const Mat& m);
1711 //! makes full copy of the matrix. All the elements are duplicated
1712 SparseMat_ clone() const;
1713 //! equivalent to cv::SparseMat::create(dims, _sizes, DataType<_Tp>::type)
1714 void create(int dims, const int* _sizes);
1715 //! converts sparse matrix to the old-style CvSparseMat. All the elements are copied
1716 //operator CvSparseMat*() const;
1718 //! returns type of the matrix elements
1720 //! returns depth of the matrix elements
1722 //! returns the number of channels in each matrix element
1723 int channels() const;
1725 //! equivalent to SparseMat::ref<_Tp>(i0, hashval)
1726 _Tp& ref(int i0, size_t* hashval=0);
1727 //! equivalent to SparseMat::ref<_Tp>(i0, i1, hashval)
1728 _Tp& ref(int i0, int i1, size_t* hashval=0);
1729 //! equivalent to SparseMat::ref<_Tp>(i0, i1, i2, hashval)
1730 _Tp& ref(int i0, int i1, int i2, size_t* hashval=0);
1731 //! equivalent to SparseMat::ref<_Tp>(idx, hashval)
1732 _Tp& ref(const int* idx, size_t* hashval=0);
1734 //! equivalent to SparseMat::value<_Tp>(i0, hashval)
1735 _Tp operator()(int i0, size_t* hashval=0) const;
1736 //! equivalent to SparseMat::value<_Tp>(i0, i1, hashval)
1737 _Tp operator()(int i0, int i1, size_t* hashval=0) const;
1738 //! equivalent to SparseMat::value<_Tp>(i0, i1, i2, hashval)
1739 _Tp operator()(int i0, int i1, int i2, size_t* hashval=0) const;
1740 //! equivalent to SparseMat::value<_Tp>(idx, hashval)
1741 _Tp operator()(const int* idx, size_t* hashval=0) const;
1743 //! returns sparse matrix iterator pointing to the first sparse matrix element
1744 SparseMatIterator_<_Tp> begin();
1745 //! returns read-only sparse matrix iterator pointing to the first sparse matrix element
1746 SparseMatConstIterator_<_Tp> begin() const;
1747 //! returns sparse matrix iterator pointing to the element following the last sparse matrix element
1748 SparseMatIterator_<_Tp> end();
1749 //! returns read-only sparse matrix iterator pointing to the element following the last sparse matrix element
1750 SparseMatConstIterator_<_Tp> end() const;
1755 ////////////////////////////////// MatConstIterator //////////////////////////////////
1757 class CV_EXPORTS MatConstIterator
1760 typedef uchar* value_type;
1761 typedef ptrdiff_t difference_type;
1762 typedef const uchar** pointer;
1763 typedef uchar* reference;
1765 #ifndef OPENCV_NOSTL
1766 typedef std::random_access_iterator_tag iterator_category;
1769 //! default constructor
1771 //! constructor that sets the iterator to the beginning of the matrix
1772 MatConstIterator(const Mat* _m);
1773 //! constructor that sets the iterator to the specified element of the matrix
1774 MatConstIterator(const Mat* _m, int _row, int _col=0);
1775 //! constructor that sets the iterator to the specified element of the matrix
1776 MatConstIterator(const Mat* _m, Point _pt);
1777 //! constructor that sets the iterator to the specified element of the matrix
1778 MatConstIterator(const Mat* _m, const int* _idx);
1779 //! copy constructor
1780 MatConstIterator(const MatConstIterator& it);
1783 MatConstIterator& operator = (const MatConstIterator& it);
1784 //! returns the current matrix element
1785 uchar* operator *() const;
1786 //! returns the i-th matrix element, relative to the current
1787 uchar* operator [](ptrdiff_t i) const;
1789 //! shifts the iterator forward by the specified number of elements
1790 MatConstIterator& operator += (ptrdiff_t ofs);
1791 //! shifts the iterator backward by the specified number of elements
1792 MatConstIterator& operator -= (ptrdiff_t ofs);
1793 //! decrements the iterator
1794 MatConstIterator& operator --();
1795 //! decrements the iterator
1796 MatConstIterator operator --(int);
1797 //! increments the iterator
1798 MatConstIterator& operator ++();
1799 //! increments the iterator
1800 MatConstIterator operator ++(int);
1801 //! returns the current iterator position
1803 //! returns the current iterator position
1804 void pos(int* _idx) const;
1806 ptrdiff_t lpos() const;
1807 void seek(ptrdiff_t ofs, bool relative = false);
1808 void seek(const int* _idx, bool relative = false);
1819 ////////////////////////////////// MatConstIterator_ /////////////////////////////////
1822 Matrix read-only iterator
1824 template<typename _Tp>
1825 class MatConstIterator_ : public MatConstIterator
1828 typedef _Tp value_type;
1829 typedef ptrdiff_t difference_type;
1830 typedef const _Tp* pointer;
1831 typedef const _Tp& reference;
1833 #ifndef OPENCV_NOSTL
1834 typedef std::random_access_iterator_tag iterator_category;
1837 //! default constructor
1838 MatConstIterator_();
1839 //! constructor that sets the iterator to the beginning of the matrix
1840 MatConstIterator_(const Mat_<_Tp>* _m);
1841 //! constructor that sets the iterator to the specified element of the matrix
1842 MatConstIterator_(const Mat_<_Tp>* _m, int _row, int _col=0);
1843 //! constructor that sets the iterator to the specified element of the matrix
1844 MatConstIterator_(const Mat_<_Tp>* _m, Point _pt);
1845 //! constructor that sets the iterator to the specified element of the matrix
1846 MatConstIterator_(const Mat_<_Tp>* _m, const int* _idx);
1847 //! copy constructor
1848 MatConstIterator_(const MatConstIterator_& it);
1851 MatConstIterator_& operator = (const MatConstIterator_& it);
1852 //! returns the current matrix element
1853 _Tp operator *() const;
1854 //! returns the i-th matrix element, relative to the current
1855 _Tp operator [](ptrdiff_t i) const;
1857 //! shifts the iterator forward by the specified number of elements
1858 MatConstIterator_& operator += (ptrdiff_t ofs);
1859 //! shifts the iterator backward by the specified number of elements
1860 MatConstIterator_& operator -= (ptrdiff_t ofs);
1861 //! decrements the iterator
1862 MatConstIterator_& operator --();
1863 //! decrements the iterator
1864 MatConstIterator_ operator --(int);
1865 //! increments the iterator
1866 MatConstIterator_& operator ++();
1867 //! increments the iterator
1868 MatConstIterator_ operator ++(int);
1869 //! returns the current iterator position
1875 //////////////////////////////////// MatIterator_ ////////////////////////////////////
1878 Matrix read-write iterator
1880 template<typename _Tp>
1881 class MatIterator_ : public MatConstIterator_<_Tp>
1884 typedef _Tp* pointer;
1885 typedef _Tp& reference;
1887 #ifndef OPENCV_NOSTL
1888 typedef std::random_access_iterator_tag iterator_category;
1891 //! the default constructor
1893 //! constructor that sets the iterator to the beginning of the matrix
1894 MatIterator_(Mat_<_Tp>* _m);
1895 //! constructor that sets the iterator to the specified element of the matrix
1896 MatIterator_(Mat_<_Tp>* _m, int _row, int _col=0);
1897 //! constructor that sets the iterator to the specified element of the matrix
1898 MatIterator_(const Mat_<_Tp>* _m, Point _pt);
1899 //! constructor that sets the iterator to the specified element of the matrix
1900 MatIterator_(const Mat_<_Tp>* _m, const int* _idx);
1901 //! copy constructor
1902 MatIterator_(const MatIterator_& it);
1904 MatIterator_& operator = (const MatIterator_<_Tp>& it );
1906 //! returns the current matrix element
1907 _Tp& operator *() const;
1908 //! returns the i-th matrix element, relative to the current
1909 _Tp& operator [](ptrdiff_t i) const;
1911 //! shifts the iterator forward by the specified number of elements
1912 MatIterator_& operator += (ptrdiff_t ofs);
1913 //! shifts the iterator backward by the specified number of elements
1914 MatIterator_& operator -= (ptrdiff_t ofs);
1915 //! decrements the iterator
1916 MatIterator_& operator --();
1917 //! decrements the iterator
1918 MatIterator_ operator --(int);
1919 //! increments the iterator
1920 MatIterator_& operator ++();
1921 //! increments the iterator
1922 MatIterator_ operator ++(int);
1927 /////////////////////////////// SparseMatConstIterator ///////////////////////////////
1930 Read-Only Sparse Matrix Iterator.
1931 Here is how to use the iterator to compute the sum of floating-point sparse matrix elements:
1934 SparseMatConstIterator it = m.begin(), it_end = m.end();
1936 CV_Assert( m.type() == CV_32F );
1937 for( ; it != it_end; ++it )
1938 s += it.value<float>();
1941 class CV_EXPORTS SparseMatConstIterator
1944 //! the default constructor
1945 SparseMatConstIterator();
1946 //! the full constructor setting the iterator to the first sparse matrix element
1947 SparseMatConstIterator(const SparseMat* _m);
1948 //! the copy constructor
1949 SparseMatConstIterator(const SparseMatConstIterator& it);
1951 //! the assignment operator
1952 SparseMatConstIterator& operator = (const SparseMatConstIterator& it);
1954 //! template method returning the current matrix element
1955 template<typename _Tp> const _Tp& value() const;
1956 //! returns the current node of the sparse matrix. it.node->idx is the current element index
1957 const SparseMat::Node* node() const;
1959 //! moves iterator to the previous element
1960 SparseMatConstIterator& operator --();
1961 //! moves iterator to the previous element
1962 SparseMatConstIterator operator --(int);
1963 //! moves iterator to the next element
1964 SparseMatConstIterator& operator ++();
1965 //! moves iterator to the next element
1966 SparseMatConstIterator operator ++(int);
1968 //! moves iterator to the element after the last element
1978 ////////////////////////////////// SparseMatIterator /////////////////////////////////
1981 Read-write Sparse Matrix Iterator
1983 The class is similar to cv::SparseMatConstIterator,
1984 but can be used for in-place modification of the matrix elements.
1986 class CV_EXPORTS SparseMatIterator : public SparseMatConstIterator
1989 //! the default constructor
1990 SparseMatIterator();
1991 //! the full constructor setting the iterator to the first sparse matrix element
1992 SparseMatIterator(SparseMat* _m);
1993 //! the full constructor setting the iterator to the specified sparse matrix element
1994 SparseMatIterator(SparseMat* _m, const int* idx);
1995 //! the copy constructor
1996 SparseMatIterator(const SparseMatIterator& it);
1998 //! the assignment operator
1999 SparseMatIterator& operator = (const SparseMatIterator& it);
2000 //! returns read-write reference to the current sparse matrix element
2001 template<typename _Tp> _Tp& value() const;
2002 //! returns pointer to the current sparse matrix node. it.node->idx is the index of the current element (do not modify it!)
2003 SparseMat::Node* node() const;
2005 //! moves iterator to the next element
2006 SparseMatIterator& operator ++();
2007 //! moves iterator to the next element
2008 SparseMatIterator operator ++(int);
2013 /////////////////////////////// SparseMatConstIterator_ //////////////////////////////
2016 Template Read-Only Sparse Matrix Iterator Class.
2018 This is the derived from SparseMatConstIterator class that
2019 introduces more convenient operator *() for accessing the current element.
2021 template<typename _Tp> class SparseMatConstIterator_ : public SparseMatConstIterator
2025 #ifndef OPENCV_NOSTL
2026 typedef std::forward_iterator_tag iterator_category;
2029 //! the default constructor
2030 SparseMatConstIterator_();
2031 //! the full constructor setting the iterator to the first sparse matrix element
2032 SparseMatConstIterator_(const SparseMat_<_Tp>* _m);
2033 SparseMatConstIterator_(const SparseMat* _m);
2034 //! the copy constructor
2035 SparseMatConstIterator_(const SparseMatConstIterator_& it);
2037 //! the assignment operator
2038 SparseMatConstIterator_& operator = (const SparseMatConstIterator_& it);
2039 //! the element access operator
2040 const _Tp& operator *() const;
2042 //! moves iterator to the next element
2043 SparseMatConstIterator_& operator ++();
2044 //! moves iterator to the next element
2045 SparseMatConstIterator_ operator ++(int);
2050 ///////////////////////////////// SparseMatIterator_ /////////////////////////////////
2053 Template Read-Write Sparse Matrix Iterator Class.
2055 This is the derived from cv::SparseMatConstIterator_ class that
2056 introduces more convenient operator *() for accessing the current element.
2058 template<typename _Tp> class SparseMatIterator_ : public SparseMatConstIterator_<_Tp>
2062 #ifndef OPENCV_NOSTL
2063 typedef std::forward_iterator_tag iterator_category;
2066 //! the default constructor
2067 SparseMatIterator_();
2068 //! the full constructor setting the iterator to the first sparse matrix element
2069 SparseMatIterator_(SparseMat_<_Tp>* _m);
2070 SparseMatIterator_(SparseMat* _m);
2071 //! the copy constructor
2072 SparseMatIterator_(const SparseMatIterator_& it);
2074 //! the assignment operator
2075 SparseMatIterator_& operator = (const SparseMatIterator_& it);
2076 //! returns the reference to the current element
2077 _Tp& operator *() const;
2079 //! moves the iterator to the next element
2080 SparseMatIterator_& operator ++();
2081 //! moves the iterator to the next element
2082 SparseMatIterator_ operator ++(int);
2087 /////////////////////////////////// NAryMatIterator //////////////////////////////////
2090 n-Dimensional Dense Matrix Iterator Class.
2092 The class cv::NAryMatIterator is used for iterating over one or more n-dimensional dense arrays (cv::Mat's).
2094 The iterator is completely different from cv::Mat_ and cv::SparseMat_ iterators.
2095 It iterates through the slices (or planes), not the elements, where "slice" is a continuous part of the arrays.
2097 Here is the example on how the iterator can be used to normalize 3D histogram:
2100 void normalizeColorHist(Mat& hist)
2103 // intialize iterator (the style is different from STL).
2104 // after initialization the iterator will contain
2105 // the number of slices or planes
2106 // the iterator will go through
2107 Mat* arrays[] = { &hist, 0 };
2109 NAryMatIterator it(arrays, planes);
2111 // iterate through the matrix. on each iteration
2112 // it.planes[i] (of type Mat) will be set to the current plane of
2113 // i-th n-dim matrix passed to the iterator constructor.
2114 for(int p = 0; p < it.nplanes; p++, ++it)
2115 s += sum(it.planes[0])[0];
2116 it = NAryMatIterator(hist);
2118 for(int p = 0; p < it.nplanes; p++, ++it)
2121 // this is a shorter implementation of the above
2122 // using built-in operations on Mat
2123 double s = sum(hist)[0];
2124 hist.convertTo(hist, hist.type(), 1./s, 0);
2126 // and this is even shorter one
2127 // (assuming that the histogram elements are non-negative)
2128 normalize(hist, hist, 1, 0, NORM_L1);
2133 You can iterate through several matrices simultaneously as long as they have the same geometry
2134 (dimensionality and all the dimension sizes are the same), which is useful for binary
2135 and n-ary operations on such matrices. Just pass those matrices to cv::MatNDIterator.
2136 Then, during the iteration it.planes[0], it.planes[1], ... will
2137 be the slices of the corresponding matrices
2139 class CV_EXPORTS NAryMatIterator
2142 //! the default constructor
2144 //! the full constructor taking arbitrary number of n-dim matrices
2145 NAryMatIterator(const Mat** arrays, uchar** ptrs, int narrays=-1);
2146 //! the full constructor taking arbitrary number of n-dim matrices
2147 NAryMatIterator(const Mat** arrays, Mat* planes, int narrays=-1);
2148 //! the separate iterator initialization method
2149 void init(const Mat** arrays, Mat* planes, uchar** ptrs, int narrays=-1);
2151 //! proceeds to the next plane of every iterated matrix
2152 NAryMatIterator& operator ++();
2153 //! proceeds to the next plane of every iterated matrix (postfix increment operator)
2154 NAryMatIterator operator ++(int);
2156 //! the iterated arrays
2158 //! the current planes
2162 //! the number of arrays
2164 //! the number of hyper-planes that the iterator steps through
2166 //! the size of each segment (in elements)
2175 ///////////////////////////////// Matrix Expressions /////////////////////////////////
2177 class CV_EXPORTS MatOp
2183 virtual bool elementWise(const MatExpr& expr) const;
2184 virtual void assign(const MatExpr& expr, Mat& m, int type=-1) const = 0;
2185 virtual void roi(const MatExpr& expr, const Range& rowRange,
2186 const Range& colRange, MatExpr& res) const;
2187 virtual void diag(const MatExpr& expr, int d, MatExpr& res) const;
2188 virtual void augAssignAdd(const MatExpr& expr, Mat& m) const;
2189 virtual void augAssignSubtract(const MatExpr& expr, Mat& m) const;
2190 virtual void augAssignMultiply(const MatExpr& expr, Mat& m) const;
2191 virtual void augAssignDivide(const MatExpr& expr, Mat& m) const;
2192 virtual void augAssignAnd(const MatExpr& expr, Mat& m) const;
2193 virtual void augAssignOr(const MatExpr& expr, Mat& m) const;
2194 virtual void augAssignXor(const MatExpr& expr, Mat& m) const;
2196 virtual void add(const MatExpr& expr1, const MatExpr& expr2, MatExpr& res) const;
2197 virtual void add(const MatExpr& expr1, const Scalar& s, MatExpr& res) const;
2199 virtual void subtract(const MatExpr& expr1, const MatExpr& expr2, MatExpr& res) const;
2200 virtual void subtract(const Scalar& s, const MatExpr& expr, MatExpr& res) const;
2202 virtual void multiply(const MatExpr& expr1, const MatExpr& expr2, MatExpr& res, double scale=1) const;
2203 virtual void multiply(const MatExpr& expr1, double s, MatExpr& res) const;
2205 virtual void divide(const MatExpr& expr1, const MatExpr& expr2, MatExpr& res, double scale=1) const;
2206 virtual void divide(double s, const MatExpr& expr, MatExpr& res) const;
2208 virtual void abs(const MatExpr& expr, MatExpr& res) const;
2210 virtual void transpose(const MatExpr& expr, MatExpr& res) const;
2211 virtual void matmul(const MatExpr& expr1, const MatExpr& expr2, MatExpr& res) const;
2212 virtual void invert(const MatExpr& expr, int method, MatExpr& res) const;
2214 virtual Size size(const MatExpr& expr) const;
2215 virtual int type(const MatExpr& expr) const;
2219 class CV_EXPORTS MatExpr
2223 explicit MatExpr(const Mat& m);
2225 MatExpr(const MatOp* _op, int _flags, const Mat& _a = Mat(), const Mat& _b = Mat(),
2226 const Mat& _c = Mat(), double _alpha = 1, double _beta = 1, const Scalar& _s = Scalar());
2228 operator Mat() const;
2229 template<typename _Tp> operator Mat_<_Tp>() const;
2234 MatExpr row(int y) const;
2235 MatExpr col(int x) const;
2236 MatExpr diag(int d = 0) const;
2237 MatExpr operator()( const Range& rowRange, const Range& colRange ) const;
2238 MatExpr operator()( const Rect& roi ) const;
2241 MatExpr inv(int method = DECOMP_LU) const;
2242 MatExpr mul(const MatExpr& e, double scale=1) const;
2243 MatExpr mul(const Mat& m, double scale=1) const;
2245 Mat cross(const Mat& m) const;
2246 double dot(const Mat& m) const;
2257 CV_EXPORTS MatExpr operator + (const Mat& a, const Mat& b);
2258 CV_EXPORTS MatExpr operator + (const Mat& a, const Scalar& s);
2259 CV_EXPORTS MatExpr operator + (const Scalar& s, const Mat& a);
2260 CV_EXPORTS MatExpr operator + (const MatExpr& e, const Mat& m);
2261 CV_EXPORTS MatExpr operator + (const Mat& m, const MatExpr& e);
2262 CV_EXPORTS MatExpr operator + (const MatExpr& e, const Scalar& s);
2263 CV_EXPORTS MatExpr operator + (const Scalar& s, const MatExpr& e);
2264 CV_EXPORTS MatExpr operator + (const MatExpr& e1, const MatExpr& e2);
2266 CV_EXPORTS MatExpr operator - (const Mat& a, const Mat& b);
2267 CV_EXPORTS MatExpr operator - (const Mat& a, const Scalar& s);
2268 CV_EXPORTS MatExpr operator - (const Scalar& s, const Mat& a);
2269 CV_EXPORTS MatExpr operator - (const MatExpr& e, const Mat& m);
2270 CV_EXPORTS MatExpr operator - (const Mat& m, const MatExpr& e);
2271 CV_EXPORTS MatExpr operator - (const MatExpr& e, const Scalar& s);
2272 CV_EXPORTS MatExpr operator - (const Scalar& s, const MatExpr& e);
2273 CV_EXPORTS MatExpr operator - (const MatExpr& e1, const MatExpr& e2);
2275 CV_EXPORTS MatExpr operator - (const Mat& m);
2276 CV_EXPORTS MatExpr operator - (const MatExpr& e);
2278 CV_EXPORTS MatExpr operator * (const Mat& a, const Mat& b);
2279 CV_EXPORTS MatExpr operator * (const Mat& a, double s);
2280 CV_EXPORTS MatExpr operator * (double s, const Mat& a);
2281 CV_EXPORTS MatExpr operator * (const MatExpr& e, const Mat& m);
2282 CV_EXPORTS MatExpr operator * (const Mat& m, const MatExpr& e);
2283 CV_EXPORTS MatExpr operator * (const MatExpr& e, double s);
2284 CV_EXPORTS MatExpr operator * (double s, const MatExpr& e);
2285 CV_EXPORTS MatExpr operator * (const MatExpr& e1, const MatExpr& e2);
2287 CV_EXPORTS MatExpr operator / (const Mat& a, const Mat& b);
2288 CV_EXPORTS MatExpr operator / (const Mat& a, double s);
2289 CV_EXPORTS MatExpr operator / (double s, const Mat& a);
2290 CV_EXPORTS MatExpr operator / (const MatExpr& e, const Mat& m);
2291 CV_EXPORTS MatExpr operator / (const Mat& m, const MatExpr& e);
2292 CV_EXPORTS MatExpr operator / (const MatExpr& e, double s);
2293 CV_EXPORTS MatExpr operator / (double s, const MatExpr& e);
2294 CV_EXPORTS MatExpr operator / (const MatExpr& e1, const MatExpr& e2);
2296 CV_EXPORTS MatExpr operator < (const Mat& a, const Mat& b);
2297 CV_EXPORTS MatExpr operator < (const Mat& a, double s);
2298 CV_EXPORTS MatExpr operator < (double s, const Mat& a);
2300 CV_EXPORTS MatExpr operator <= (const Mat& a, const Mat& b);
2301 CV_EXPORTS MatExpr operator <= (const Mat& a, double s);
2302 CV_EXPORTS MatExpr operator <= (double s, const Mat& a);
2304 CV_EXPORTS MatExpr operator == (const Mat& a, const Mat& b);
2305 CV_EXPORTS MatExpr operator == (const Mat& a, double s);
2306 CV_EXPORTS MatExpr operator == (double s, const Mat& a);
2308 CV_EXPORTS MatExpr operator != (const Mat& a, const Mat& b);
2309 CV_EXPORTS MatExpr operator != (const Mat& a, double s);
2310 CV_EXPORTS MatExpr operator != (double s, const Mat& a);
2312 CV_EXPORTS MatExpr operator >= (const Mat& a, const Mat& b);
2313 CV_EXPORTS MatExpr operator >= (const Mat& a, double s);
2314 CV_EXPORTS MatExpr operator >= (double s, const Mat& a);
2316 CV_EXPORTS MatExpr operator > (const Mat& a, const Mat& b);
2317 CV_EXPORTS MatExpr operator > (const Mat& a, double s);
2318 CV_EXPORTS MatExpr operator > (double s, const Mat& a);
2320 CV_EXPORTS MatExpr operator & (const Mat& a, const Mat& b);
2321 CV_EXPORTS MatExpr operator & (const Mat& a, const Scalar& s);
2322 CV_EXPORTS MatExpr operator & (const Scalar& s, const Mat& a);
2324 CV_EXPORTS MatExpr operator | (const Mat& a, const Mat& b);
2325 CV_EXPORTS MatExpr operator | (const Mat& a, const Scalar& s);
2326 CV_EXPORTS MatExpr operator | (const Scalar& s, const Mat& a);
2328 CV_EXPORTS MatExpr operator ^ (const Mat& a, const Mat& b);
2329 CV_EXPORTS MatExpr operator ^ (const Mat& a, const Scalar& s);
2330 CV_EXPORTS MatExpr operator ^ (const Scalar& s, const Mat& a);
2332 CV_EXPORTS MatExpr operator ~(const Mat& m);
2334 CV_EXPORTS MatExpr min(const Mat& a, const Mat& b);
2335 CV_EXPORTS MatExpr min(const Mat& a, double s);
2336 CV_EXPORTS MatExpr min(double s, const Mat& a);
2338 CV_EXPORTS MatExpr max(const Mat& a, const Mat& b);
2339 CV_EXPORTS MatExpr max(const Mat& a, double s);
2340 CV_EXPORTS MatExpr max(double s, const Mat& a);
2342 CV_EXPORTS MatExpr abs(const Mat& m);
2343 CV_EXPORTS MatExpr abs(const MatExpr& e);
2347 #include "opencv2/core/mat.inl.hpp"
2349 #endif // __OPENCV_CORE_MAT_HPP__