opencv/doc/cxcore_basic_structures.tex

   1 \section{Basic Structures}
   2
   3 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
   4 %                                                                                    %
   5 %                                         C                                          %
   6 %                                                                                    %
   7 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
   8
   9 \ifCPy
  10 \label{CvPoint}\cvclass{CvPoint}
  11 2D point with integer coordinates (usually zero-based).
  12
  13 \begin{lstlisting}
  14 typedef struct CvPoint
  15 {
  16     int x;
  17     int y;
  18 }
  19 CvPoint;
  20 \end{lstlisting}
  21
  22 \begin{description}
  23 \cvarg{x}{x-coordinate}
  24 \cvarg{y}{y-coordinate}
  25 \end{description}
  26
  27 \begin{lstlisting}
  28 /* Constructor */
  29 inline CvPoint cvPoint( int x, int y );
  30
  31 /* Conversion from CvPoint2D32f */
  32 inline CvPoint cvPointFrom32f( CvPoint2D32f point );
  33 \end{lstlisting}
  34
  35
  36 \label{CvPoint2D32f}\cvclass{CvPoint2D32f}
  37 2D point with floating-point coordinates
  38
  39 \begin{lstlisting}
  40 typedef struct CvPoint2D32f
  41 {
  42     float x;
  43     float y;
  44 }
  45 CvPoint2D32f;
  46 \end{lstlisting}
  47
  48 \begin{description}
  49 \cvarg{x}{x-coordinate}
  50 \cvarg{y}{y-coordinate}
  51 \end{description}
  52
  53 \begin{lstlisting}
  54 /* Constructor */
  55 inline CvPoint2D32f cvPoint2D32f( double x, double y );
  56
  57 /* Conversion from CvPoint */
  58 inline CvPoint2D32f cvPointTo32f( CvPoint point );
  59 \end{lstlisting}
  60
  61
  62 \label{CvPoint3D32f}\cvclass{CvPoint3D32f}
  63 3D point with floating-point coordinates
  64
  65 \begin{lstlisting}
  66 typedef struct CvPoint3D32f
  67 {
  68     float x;
  69     float y;
  70     float z;
  71 }
  72 CvPoint3D32f;
  73 \end{lstlisting}
  74
  75 \begin{description}
  76 \cvarg{x}{x-coordinate}
  77 \cvarg{y}{y-coordinate}
  78 \cvarg{z}{z-coordinate}
  79 \end{description}
  80
  81 \begin{lstlisting}
  82 /* Constructor */
  83 inline CvPoint3D32f cvPoint3D32f( double x, double y, double z );
  84 \end{lstlisting}
  85
  86 \label{CvPoint2D64f}\cvclass{CvPoint2D64f}
  87 2D point with double precision floating-point coordinates
  88
  89 \begin{lstlisting}
  90 typedef struct CvPoint2D64f
  91 {
  92     double x;
  93     double y;
  94 }
  95 CvPoint2D64f;
  96 \end{lstlisting}
  97
  98 \begin{description}
  99 \cvarg{x}{x-coordinate}
 100 \cvarg{y}{y-coordinate}
 101 \end{description}
 102
 103 \begin{lstlisting}
 104 /* Constructor */
 105 inline CvPoint2D64f cvPoint2D64f( double x, double y );
 106
 107 /* Conversion from CvPoint */
 108 inline CvPoint2D64f cvPointTo64f( CvPoint point );
 109 \end{lstlisting}
 110
 111 \label{CvPoint3D64f}\cvclass{CvPoint3D64f}
 112 3D point with double precision floating-point coordinates
 113
 114 \begin{lstlisting}
 115 typedef struct CvPoint3D64f
 116 {
 117     double x;
 118     double y;
 119     double z;
 120 }
 121 CvPoint3D64f;
 122 \end{lstlisting}
 123
 124 \begin{description}
 125 \cvarg{x}{x-coordinate}
 126 \cvarg{y}{y-coordinate}
 127 \cvarg{z}{z-coordinate}
 128 \end{description}
 129
 130 \begin{lstlisting}
 131 /* Constructor */
 132 inline CvPoint3D64f cvPoint3D64f( double x, double y, double z );
 133 \end{lstlisting}
 134
 135 \label{CvSize}\cvclass{CvSize}
 136 Pixel-accurate size of a rectangle.
 137
 138 \ifC % {
 139 \begin{lstlisting}
 140 typedef struct CvSize
 141 {
 142     int width;
 143     int height;
 144 }
 145 CvSize;
 146 \end{lstlisting}
 147
 148 \begin{description}
 149 \cvarg{width}{Width of the rectangle}
 150 \cvarg{height}{Height of the rectangle}
 151 \end{description}
 152
 153 \begin{lstlisting}
 154 /* Constructor */
 155 inline CvSize cvSize( int width, int height );
 156 \end{lstlisting}
 157 \else % }{
 158 Size of a rectangle, represented as a tuple \texttt{(width, height)}, where width and height are integers.
 159 \fi % }
 160
 161 \label{CvSize2D32f}\cvclass{CvSize2D32f}
 162 Sub-pixel accurate size of a rectangle.
 163
 164 \ifC % {
 165 \begin{lstlisting}
 166 typedef struct CvSize2D32f
 167 {
 168     float width;
 169     float height;
 170 }
 171 CvSize2D32f;
 172 \end{lstlisting}
 173
 174 \begin{description}
 175 \cvarg{width}{Width of the rectangle}
 176 \cvarg{height}{Height of the rectangle}
 177 \end{description}
 178
 179 \begin{lstlisting}
 180 /* Constructor */
 181 inline CvSize2D32f cvSize2D32f( double width, double height );
 182 \end{lstlisting}
 183 \else % }{
 184 Size of a rectangle, represented as a tuple \texttt{(width, height)}, where width and height are floats.
 185 \fi % }
 186
 187 \label{CvRect}\cvclass{CvRect}
 188 Offset (usually the top-left corner) and size of a rectangle.
 189
 190 \begin{lstlisting}
 191 typedef struct CvRect
 192 {
 193     int x;
 194     int y;
 195     int width;
 196     int height;
 197 }
 198 CvRect;
 199 \end{lstlisting}
 200
 201 \begin{description}
 202 \cvarg{x}{x-coordinate of the top-left corner}
 203 \cvarg{y}{y-coordinate of the top-left corner (bottom-left for Windows bitmaps)}
 204 \cvarg{width}{Width of the rectangle}
 205 \cvarg{height}{Height of the rectangle}
 206 \end{description}
 207
 208 \begin{lstlisting}
 209 /* Constructor */
 210 inline CvRect cvRect( int x, int y, int width, int height );
 211 \end{lstlisting}
 212
 213 \label{CvScalar}\cvclass{CvScalar}
 214 A container for 1-,2-,3- or 4-tuples of doubles.
 215
 216 \ifC % {
 217 \begin{lstlisting}
 218 typedef struct CvScalar
 219 {
 220     double val[4];
 221 }
 222 CvScalar;
 223 \end{lstlisting}
 224
 225 \begin{lstlisting}
 226 /* Constructor:
 227 initializes val[0] with val0, val[1] with val1, etc.
 228 */
 229 inline CvScalar cvScalar( double val0, double val1=0,
 230                           double val2=0, double val3=0 );
 231 /* Constructor:
 232 initializes all of val[0]...val[3] with val0123
 233 */
 234 inline CvScalar cvScalarAll( double val0123 );
 235
 236 /* Constructor:
 237 initializes val[0] with val0, and all of val[1]...val[3] with zeros
 238 */
 239 inline CvScalar cvRealScalar( double val0 );
 240 \end{lstlisting}
 241 \else % }{
 242
 243 CvScalar is always represented as a 4-tuple.
 244
 245 \begin{lstlisting}
 246 >>> import cv
 247 >>> cv.Scalar(1, 2, 3, 4)
 248 (1.0, 2.0, 3.0, 4.0)
 249 >>> cv.ScalarAll(7)
 250 (7.0, 7.0, 7.0, 7.0)
 251 >>> cv.RealScalar(7)
 252 (7.0, 0.0, 0.0, 0.0)
 253 >>> cv.RGB(17, 110, 255)
 254 (255.0, 110.0, 17.0, 0.0)
 255 \end{lstlisting}
 256 \fi % }
 257
 258 \label{CvTermCriteria}\cvclass{CvTermCriteria}
 259 Termination criteria for iterative algorithms.
 260
 261 \ifC % {
 262 \begin{lstlisting}
 263 #define CV_TERMCRIT_ITER    1
 264 #define CV_TERMCRIT_NUMBER  CV_TERMCRIT_ITER
 265 #define CV_TERMCRIT_EPS     2
 266
 267 typedef struct CvTermCriteria
 268 {
 269     int    type;
 270     int    max_iter;
 271     double epsilon;
 272 }
 273 CvTermCriteria;
 274 \end{lstlisting}
 275
 276 \begin{description}
 277 \cvarg{type}{A combination of CV\_TERMCRIT\_ITER and CV\_TERMCRIT\_EPS}
 278 \cvarg{max\_iter}{Maximum number of iterations}
 279 \cvarg{epsilon}{Required accuracy}
 280 \end{description}
 281
 282 \begin{lstlisting}
 283 /* Constructor */
 284 inline CvTermCriteria cvTermCriteria( int type, int max_iter, double epsilon );
 285
 286 /* Check and transform a CvTermCriteria so that
 287    type=CV_TERMCRIT_ITER+CV_TERMCRIT_EPS
 288    and both max_iter and epsilon are valid */
 289 CvTermCriteria cvCheckTermCriteria( CvTermCriteria criteria,
 290                                     double default_eps,
 291                                     int default_max_iters );
 292 \end{lstlisting}
 293 \else % }{
 294 Represented by a tuple \texttt{(type, max\_iter, epsilon)}.
 295
 296 \begin{description}
 297 \cvarg{type}{\texttt{CV\_TERMCRIT\_ITER}, \texttt{CV\_TERMCRIT\_EPS} or \texttt{CV\_TERMCRIT\_ITER | CV\_TERMCRIT\_EPS}}
 298 \cvarg{max\_iter}{Maximum number of iterations}
 299 \cvarg{epsilon}{Required accuracy}
 300 \end{description}
 301
 302 \fi % }
 303
 304 \label{CvMat}\cvclass{CvMat}
 305 A multi-channel matrix.
 306
 307 \begin{lstlisting}
 308 typedef struct CvMat
 309 {
 310     int type;
 311     int step;
 312
 313     int* refcount;
 314
 315     union
 316     {
 317         uchar* ptr;
 318         short* s;
 319         int* i;
 320         float* fl;
 321         double* db;
 322     } data;
 323
 324 #ifdef __cplusplus
 325     union
 326     {
 327         int rows;
 328         int height;
 329     };
 330
 331     union
 332     {
 333         int cols;
 334         int width;
 335     };
 336 #else
 337     int rows;
 338     int cols;
 339 #endif
 340
 341 } CvMat;
 342 \end{lstlisting}
 343
 344 \begin{description}
 345 \cvarg{type}{A CvMat signature (CV\_MAT\_MAGIC\_VAL) containing the type of elements and flags}
 346 \cvarg{step}{Full row length in bytes}
 347 \cvarg{refcount}{Underlying data reference counter}
 348 \cvarg{data}{Pointers to the actual matrix data}
 349 \cvarg{rows}{Number of rows}
 350 \cvarg{cols}{Number of columns}
 351 \end{description}
 352
 353 Matrices are stored row by row. All of the rows are aligned by 4 bytes.
 354
 355
 356 \label{CvMatND}\cvclass{CvMatND}
 357 Multi-dimensional dense multi-channel array.
 358
 359 \begin{lstlisting}
 360 typedef struct CvMatND
 361 {
 362     int type;
 363     int dims;
 364
 365     int* refcount;
 366
 367     union
 368     {
 369         uchar* ptr;
 370         short* s;
 371         int* i;
 372         float* fl;
 373         double* db;
 374     } data;
 375
 376     struct
 377     {
 378         int size;
 379         int step;
 380     }
 381     dim[CV_MAX_DIM];
 382
 383 } CvMatND;
 384 \end{lstlisting}
 385
 386 \begin{description}
 387 \cvarg{type}{A CvMatND signature (CV\_MATND\_MAGIC\_VAL), combining the type of elements and flags}
 388 \cvarg{dims}{The number of array dimensions}
 389 \cvarg{refcount}{Underlying data reference counter}
 390 \cvarg{data}{Pointers to the actual matrix data}
 391 \cvarg{dim}{For each dimension, the pair (number of elements, distance between elements in bytes)}
 392 \end{description}
 393
 394 \label{CvSparseMat}\cvclass{CvSparseMat}
 395 Multi-dimensional sparse multi-channel array.
 396
 397 \begin{lstlisting}
 398 typedef struct CvSparseMat
 399 {
 400     int type;
 401     int dims;
 402     int* refcount;
 403     struct CvSet* heap;
 404     void** hashtable;
 405     int hashsize;
 406     int total;
 407     int valoffset;
 408     int idxoffset;
 409     int size[CV_MAX_DIM];
 410
 411 } CvSparseMat;
 412 \end{lstlisting}
 413
 414 \begin{description}
 415 \cvarg{type}{A CvSparseMat signature (CV\_SPARSE\_MAT\_MAGIC\_VAL), combining the type of elements and flags.}
 416 \cvarg{dims}{Number of dimensions}
 417 \cvarg{refcount}{Underlying reference counter. Not used.}
 418 \cvarg{heap}{A pool of hash table nodes}
 419 \cvarg{hashtable}{The hash table. Each entry is a list of nodes.}
 420 \cvarg{hashsize}{Size of the hash table}
 421 \cvarg{total}{Total number of sparse array nodes}
 422 \cvarg{valoffset}{The value offset of the array nodes, in bytes}
 423 \cvarg{idxoffset}{The index offset of the array nodes, in bytes}
 424 \cvarg{size}{Array of dimension sizes}
 425 \end{description}
 426
 427 \label{IplImage}\cvclass{IplImage}
 428 IPL image header
 429
 430 \begin{lstlisting}
 431 typedef struct _IplImage
 432 {
 433     int  nSize;
 434     int  ID;
 435     int  nChannels;
 436     int  alphaChannel;
 437     int  depth;
 438     char colorModel[4];
 439     char channelSeq[4];
 440     int  dataOrder;
 441     int  origin;
 442     int  align;
 443     int  width;
 444     int  height;
 445     struct _IplROI *roi;
 446     struct _IplImage *maskROI;
 447     void  *imageId;
 448     struct _IplTileInfo *tileInfo;
 449     int  imageSize;
 450     char *imageData;
 451     int  widthStep;
 452     int  BorderMode[4];
 453     int  BorderConst[4];
 454     char *imageDataOrigin;
 455 }
 456 IplImage;
 457 \end{lstlisting}
 458
 459 \begin{description}
 460 \cvarg{nSize}{\texttt{sizeof(IplImage)}}
 461 \cvarg{ID}{Version, always equals 0}
 462 \cvarg{nChannels}{Number of channels. Most OpenCV functions support 1-4 channels.}
 463 \cvarg{alphaChannel}{Ignored by OpenCV}
 464 \cvarg{depth}{Pixel depth in bits. The supported depths are:
 465 \begin{description}
 466 \cvarg{IPL\_DEPTH\_8U}{Unsigned 8-bit integer}
 467 \cvarg{IPL\_DEPTH\_8S}{Signed 8-bit integer}
 468 \cvarg{IPL\_DEPTH\_16U}{Unsigned 16-bit integer}
 469 \cvarg{IPL\_DEPTH\_16S}{Signed 16-bit integer}
 470 \cvarg{IPL\_DEPTH\_32S}{Signed 32-bit integer}
 471 \cvarg{IPL\_DEPTH\_32F}{Single-precision floating point}
 472 \cvarg{IPL\_DEPTH\_64F}{Double-precision floating point}
 473 \end{description}}
 474 \cvarg{colorModel}{Ignored by OpenCV. The OpenCV function \cross{CvtColor} requires the source and destination color spaces as parameters.}
 475 \cvarg{channelSeq}{Ignored by OpenCV}
 476 \cvarg{dataOrder}{0 = \texttt{IPL\_DATA\_ORDER\_PIXEL} - interleaved color channels, 1 - separate color channels. \cross{CreateImage} only creates images with interleaved channels. For example, the usual layout of a color image is: $ b_{00} g_{00} r_{00} b_{10} g_{10} r_{10} ...$}
 477 \cvarg{origin}{0 - top-left origin, 1 - bottom-left origin (Windows bitmap style)}
 478 \cvarg{align}{Alignment of image rows (4 or 8). OpenCV ignores this and uses widthStep instead.}
 479 \cvarg{width}{Image width in pixels}
 480 \cvarg{height}{Image height in pixels}
 481 \cvarg{roi}{Region Of Interest (ROI). If not NULL, only this image region will be processed.}
 482 \cvarg{maskROI}{Must be NULL in OpenCV}
 483 \cvarg{imageId}{Must be NULL in OpenCV}
 484 \cvarg{tileInfo}{Must be NULL in OpenCV}
 485 \cvarg{imageSize}{Image data size in bytes. For interleaved data, this equals $\texttt{image->height} \cdot \texttt{image->widthStep}$ }
 486 \cvarg{imageData}{A pointer to the aligned image data}
 487 \cvarg{widthStep}{The size of an aligned image row, in bytes}
 488 \cvarg{BorderMode}{Border completion mode, ignored by OpenCV}
 489 \cvarg{BorderConst}{Border completion mode, ignored by OpenCV}
 490 \cvarg{imageDataOrigin}{A pointer to the origin of the image data (not necessarily aligned). This is used for image deallocation.}
 491 \end{description}
 492
 493 The \cross{IplImage} structure was inherited from the Intel Image Processing Library, in which the format is native. OpenCV only supports a subset of possible \cross{IplImage} formats, as outlined in the parameter list above.
 494
 495 In addition to the above restrictions, OpenCV handles ROIs differently. OpenCV functions require that the image size or ROI size of all source and destination images match exactly. On the other hand, the Intel Image Processing Library processes the area of intersection between the source and destination images (or ROIs), allowing them to vary independently.
 496
 497 \label{CvArr}\cvclass{CvArr}
 498 Arbitrary array
 499
 500 \begin{lstlisting}
 501 typedef void CvArr;
 502 \end{lstlisting}
 503
 504 The metatype \texttt{CvArr} is used \textit{only} as a function parameter to specify that the function accepts arrays of multiple types, such as IplImage*, CvMat* or even CvSeq* sometimes. The particular array type is determined at runtime by analyzing the first 4 bytes of the header.
 505 \fi
 506
 507 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 508 %                                                                                    %
 509 %                                        C++                                         %
 510 %                                                                                    %
 511 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 512
 513 \ifCpp
 514 \subsection{DataType}\label{DataType}
 515 Template "traits" class for other OpenCV primitive data types
 516
 517 \begin{lstlisting}
 518 template<typename _Tp> class DataType
 519 {
 520     // value_type is always a synonym for _Tp.
 521     typedef _Tp value_type;
 522
 523     // intermediate type used for operations on _Tp.
 524     // it is int for uchar, signed char, unsigned short, signed short and int,
 525     // float for float, double for double, ...
 526     typedef <...> work_type;
 527     // in the case of multi-channel data it is the data type of each channel
 528     typedef <...> channel_type;
 529     enum
 530     {
 531         // CV_8U ... CV_64F
 532         depth = DataDepth<channel_type>::value,
 533         // 1 ...
 534         channels = <...>,
 535         // '1u', '4i', '3f', '2d' etc.
 536         fmt=<...>,
 537         // CV_8UC3, CV_32FC2 ...
 538         type = CV_MAKETYPE(depth, channels)
 539     };
 540 };
 541 \end{lstlisting}
 542
 543 The template class \texttt{DataType} is descriptive class for OpenCV primitive data types and other types that comply with the following definition. A primitive OpenCV data type is one of \texttt{unsigned char, bool ($\sim$unsigned char), signed char, unsigned short, signed short, int, float, double} or a tuple of values of one of these types, where all the values in the tuple have the same type. If you are familiar with OpenCV \cross{CvMat}'s type notation, CV\_8U ... CV\_32FC3, CV\_64FC2 etc., then a primitive type can be defined as a type for which you can give a unique identifier in a form \verb*"CV\_<bit-depth>{U|S|F}C<number_of_channels>". A universal OpenCV structure able to store a single instance of such primitive data type is \cross{Vec}. Multiple instances of such a type can be stored to a \texttt{std::vector}, \texttt{Mat}, \texttt{Mat\_}, \texttt{MatND}, \texttt{MatND\_}, \texttt{SparseMat}, \texttt{SparseMat\_} or any other container that is able to store \cross{Vec} instances.
 544
 545 The class \texttt{DataType} is basically used to provide some description of such primitive data types without adding any fields or methods to the corresponding classes (and it is actually impossible to add anything to primitive C/C++ data types). This technique is known in C++ as class traits. It's not \texttt{DataType} itself that is used, but its specialized versions, such as:
 546
 547 \begin{lstlisting}
 548 template<> class DataType<uchar>
 549 {
 550     typedef uchar value_type;
 551     typedef int work_type;
 552     typedef uchar channel_type;
 553     enum { channel_type = CV_8U, channels = 1, fmt='u', type = CV_8U };
 554 };
 555 ...
 556 template<typename _Tp> DataType<std::complex<_Tp> >
 557 {
 558     typedef std::complex<_Tp> value_type;
 559     typedef std::complex<_Tp> work_type;
 560     typedef _Tp channel_type;
 561     // DataDepth is another helper trait class
 562     enum { depth = DataDepth<_Tp>::value, channels=2,
 563         fmt=(channels-1)*256+DataDepth<_Tp>::fmt,
 564         type=CV_MAKETYPE(depth, channels) };
 565 };
 566 ...
 567 \end{lstlisting}
 568
 569 The main purpose of the classes is to convert compile-time type information to OpenCV-compatible data type identifier, for example:
 570
 571 \begin{lstlisting}
 572 // allocates 30x40 floating-point matrix
 573 Mat A(30, 40, DataType<float>::type);
 574
 575 Mat B = Mat_<std::complex<double> >(3, 3);
 576 // the statement below will print 6, 2 /* i.e. depth == CV_64F, channels == 2 */
 577 cout << B.depth() << ", " << B.channels() << endl;
 578 \end{lstlisting}
 579
 580 that is, such traits are used to tell OpenCV which data type you are working with, even if such a type is not native to OpenCV (the matrix \texttt{B} intialization above compiles because OpenCV defines the proper specialized template class \texttt{DataType<complex<\_Tp> >}). Also, this mechanism is useful (and used in OpenCV this way) for generic algorithms implementations.
 581
 582 \subsection{Point\_}
 583 Template class for 2D points
 584
 585 \begin{lstlisting}
 586 template<typename _Tp> class Point_
 587 {
 588 public:
 589     typedef _Tp value_type;
 590
 591     Point_();
 592     Point_(_Tp _x, _Tp _y);
 593     Point_(const Point_& pt);
 594     Point_(const CvPoint& pt);
 595     Point_(const CvPoint2D32f& pt);
 596     Point_(const Size_<_Tp>& sz);
 597     Point_(const Vec<_Tp, 2>& v);
 598     Point_& operator = (const Point_& pt);
 599     template<typename _Tp2> operator Point_<_Tp2>() const;
 600     operator CvPoint() const;
 601     operator CvPoint2D32f() const;
 602     operator Vec<_Tp, 2>() const;
 603
 604     // computes dot-product (this->x*pt.x + this->y*pt.y)
 605     _Tp dot(const Point_& pt) const;
 606     // computes dot-product using double-precision arithmetics
 607     double ddot(const Point_& pt) const;
 608     // returns true if the point is inside the rectangle "r".
 609     bool inside(const Rect_<_Tp>& r) const;
 610
 611     _Tp x, y;
 612 };
 613 \end{lstlisting}
 614
 615 The class represents a 2D point, specified by its coordinates $x$ and $y$.
 616 Instance of the class is interchangeable with C structures \texttt{CvPoint} and \texttt{CvPoint2D32f}. There is also cast operator to convert point coordinates to the specified type. The conversion from floating-point coordinates to integer coordinates is done by rounding; in general case the conversion uses \hyperref[saturatecast]{saturate\_cast} operation on each of the coordinates. Besides the class members listed in the declaration above, the following operations on points are implemented:
 617
 618 \begin{lstlisting}
 619     pt1 = pt2 + pt3;
 620     pt1 = pt2 - pt3;
 621     pt1 = pt2 * a;
 622     pt1 = a * pt2;
 623     pt1 += pt2;
 624     pt1 -= pt2;
 625     pt1 *= a;
 626     double value = norm(pt); // L2 norm
 627     pt1 == pt2;
 628     pt1 != pt2;
 629 \end{lstlisting}
 630
 631 For user convenience, the following type aliases are defined:
 632 \begin{lstlisting}
 633 typedef Point_<int> Point2i;
 634 typedef Point2i Point;
 635 typedef Point_<float> Point2f;
 636 typedef Point_<double> Point2d;
 637 \end{lstlisting}
 638
 639 Here is a short example:
 640 \begin{lstlisting}
 641 Point2f a(0.3f, 0.f), b(0.f, 0.4f);
 642 Point pt = (a + b)*10.f;
 643 cout << pt.x << ", " << pt.y << endl;
 644 \end{lstlisting}
 645
 646 \subsection{Point3\_}
 647
 648 Template class for 3D points
 649
 650 \begin{lstlisting}
 651
 652 template<typename _Tp> class Point3_
 653 {
 654 public:
 655     typedef _Tp value_type;
 656
 657     Point3_();
 658     Point3_(_Tp _x, _Tp _y, _Tp _z);
 659     Point3_(const Point3_& pt);
 660     explicit Point3_(const Point_<_Tp>& pt);
 661     Point3_(const CvPoint3D32f& pt);
 662     Point3_(const Vec<_Tp, 3>& v);
 663     Point3_& operator = (const Point3_& pt);
 664     template<typename _Tp2> operator Point3_<_Tp2>() const;
 665     operator CvPoint3D32f() const;
 666     operator Vec<_Tp, 3>() const;
 667
 668     _Tp dot(const Point3_& pt) const;
 669     double ddot(const Point3_& pt) const;
 670
 671     _Tp x, y, z;
 672 };
 673 \end{lstlisting}
 674
 675 The class represents a 3D point, specified by its coordinates $x$, $y$ and $z$.
 676 Instance of the class is interchangeable with C structure \texttt{CvPoint2D32f}. Similarly to \texttt{Point\_}, the 3D points' coordinates can be converted to another type, and the vector arithmetic and comparison operations are also supported.
 677
 678 The following type aliases are available:
 679
 680 \begin{lstlisting}
 681 typedef Point3_<int> Point3i;
 682 typedef Point3_<float> Point3f;
 683 typedef Point3_<double> Point3d;
 684 \end{lstlisting}
 685
 686 \subsection{Size\_}
 687
 688 Template class for specfying image or rectangle size.
 689
 690 \begin{lstlisting}
 691 template<typename _Tp> class Size_
 692 {
 693 public:
 694     typedef _Tp value_type;
 695
 696     Size_();
 697     Size_(_Tp _width, _Tp _height);
 698     Size_(const Size_& sz);
 699     Size_(const CvSize& sz);
 700     Size_(const CvSize2D32f& sz);
 701     Size_(const Point_<_Tp>& pt);
 702     Size_& operator = (const Size_& sz);
 703     _Tp area() const;
 704
 705     operator Size_<int>() const;
 706     operator Size_<float>() const;
 707     operator Size_<double>() const;
 708     operator CvSize() const;
 709     operator CvSize2D32f() const;
 710
 711     _Tp width, height;
 712 };
 713 \end{lstlisting}
 714
 715 The class \texttt{Size\_} is similar to \texttt{Point\_}, except that the two members are called \texttt{width} and \texttt{height} instead of \texttt{x} and \texttt{y}. The structure can be converted to and from the old OpenCV structures \cross{CvSize} and \cross{CvSize2D32f}. The same set of arithmetic and comparison operations as for \texttt{Point\_} is available.
 716
 717 OpenCV defines the following type aliases:
 718
 719 \begin{lstlisting}
 720 typedef Size_<int> Size2i;
 721 typedef Size2i Size;
 722 typedef Size_<float> Size2f;
 723 \end{lstlisting}
 724
 725 \subsection{Rect\_}
 726
 727 Template class for 2D rectangles
 728
 729 \begin{lstlisting}
 730 template<typename _Tp> class Rect_
 731 {
 732 public:
 733     typedef _Tp value_type;
 734
 735     Rect_();
 736     Rect_(_Tp _x, _Tp _y, _Tp _width, _Tp _height);
 737     Rect_(const Rect_& r);
 738     Rect_(const CvRect& r);
 739     // (x, y) <- org, (width, height) <- sz
 740     Rect_(const Point_<_Tp>& org, const Size_<_Tp>& sz);
 741     // (x, y) <- min(pt1, pt2), (width, height) <- max(pt1, pt2) - (x, y)
 742     Rect_(const Point_<_Tp>& pt1, const Point_<_Tp>& pt2);
 743     Rect_& operator = ( const Rect_& r );
 744     // returns Point_<_Tp>(x, y)
 745     Point_<_Tp> tl() const;
 746     // returns Point_<_Tp>(x+width, y+height)
 747     Point_<_Tp> br() const;
 748
 749     // returns Size_<_Tp>(width, height)
 750     Size_<_Tp> size() const;
 751     // returns width*height
 752     _Tp area() const;
 753
 754     operator Rect_<int>() const;
 755     operator Rect_<float>() const;
 756     operator Rect_<double>() const;
 757     operator CvRect() const;
 758
 759     // x <= pt.x && pt.x < x + width &&
 760     // y <= pt.y && pt.y < y + height ? true : false
 761     bool contains(const Point_<_Tp>& pt) const;
 762
 763     _Tp x, y, width, height;
 764 };
 765 \end{lstlisting}
 766
 767 The rectangle is described by the coordinates of the top-left corner (which is the default interpretation of \texttt{Rect\_::x} and \texttt{Rect\_::y} in OpenCV; though, in your algorithms you may count \texttt{x} and \texttt{y} from the bottom-left corner), the rectangle width and height.
 768
 769 Another assumption OpenCV usually makes is that the top and left boundary of the rectangle are inclusive, while the right and bottom boundaries are not, for example, the method \texttt{Rect\_::contains} returns true if
 770 \begin{eqnarray*}
 771       x \leq pt.x < x+width,\\
 772       y \leq pt.y < y+height
 773 \end{eqnarray*}
 774 And virtually every loop over an image \cross{ROI} in OpenCV (where ROI is specified by \texttt{Rect\_<int>}) is implemented as:
 775 \begin{lstlisting}
 776 for(int y = roi.y; y < roi.y + rect.height; y++)
 777     for(int x = roi.x; x < roi.x + rect.width; x++)
 778     {
 779         // ...
 780     }
 781 \end{lstlisting}
 782
 783 In addition to the class members, the following operations on rectangles are implemented:
 784 \begin{itemize}
 785     \item $\texttt{rect} = \texttt{rect} \pm \texttt{point}$ (shifting rectangle by a certain offset)
 786     \item $\texttt{rect} = \texttt{rect} \pm \texttt{size}$ (expanding or shrinking rectangle by a certain amount)
 787     \item \texttt{rect += point, rect -= point, rect += size, rect -= size} (augmenting operations)
 788     \item \texttt{rect = rect1 \& rect2} (rectangle intersection)
 789     \item \texttt{rect = rect1 | rect2} (minimum area rectangle containing \texttt{rect2} and \texttt{rect3})
 790     \item \texttt{rect \&= rect1, rect |= rect1} (and the corresponding augmenting operations)
 791     \item \texttt{rect == rect1, rect != rect1} (rectangle comparison)
 792 \end{itemize}
 793
 794 Example. Here is how the partial ordering on rectangles can be established (rect1 $\subseteq$ rect2):
 795 \begin{lstlisting}
 796 template<typename _Tp> inline bool
 797 operator <= (const Rect_<_Tp>& r1, const Rect_<_Tp>& r2)
 798 {
 799     return (r1 & r2) == r1;
 800 }
 801 \end{lstlisting}
 802
 803 For user convenience, the following type alias is available:
 804 \begin{lstlisting}
 805 typedef Rect_<int> Rect;
 806 \end{lstlisting}
 807
 808 \subsection{RotatedRect}\label{RotatedRect}
 809 Possibly rotated rectangle
 810
 811 \begin{lstlisting}
 812 class RotatedRect
 813 {
 814 public:
 815     // constructors
 816     RotatedRect();
 817     RotatedRect(const Point2f& _center, const Size2f& _size, float _angle);
 818     RotatedRect(const CvBox2D& box);
 819
 820     // returns minimal up-right rectangle that contains the rotated rectangle
 821     Rect boundingRect() const;
 822     // backward conversion to CvBox2D
 823     operator CvBox2D() const;
 824
 825     // mass center of the rectangle
 826     Point2f center;
 827     // size
 828     Size2f size;
 829     // rotation angle in degrees
 830     float angle;
 831 };
 832 \end{lstlisting}
 833
 834 The class \texttt{RotatedRect} replaces the old \cross{CvBox2D} and fully compatible with it.
 835
 836 \subsection{TermCriteria}\label{TermCriteria}
 837
 838 Termination criteria for iterative algorithms
 839
 840 \begin{lstlisting}
 841 class TermCriteria
 842 {
 843 public:
 844     enum { COUNT=1, MAX_ITER=COUNT, EPS=2 };
 845
 846     // constructors
 847     TermCriteria();
 848     // type can be MAX_ITER, EPS or MAX_ITER+EPS.
 849     // type = MAX_ITER means that only the number of iterations does matter;
 850     // type = EPS means that only the required precision (epsilon) does matter
 851     //    (though, most algorithms put some limit on the number of iterations anyway)
 852     // type = MAX_ITER + EPS means that algorithm stops when
 853     // either the specified number of iterations is made,
 854     // or when the specified accuracy is achieved - whatever happens first.
 855     TermCriteria(int _type, int _maxCount, double _epsilon);
 856     TermCriteria(const CvTermCriteria& criteria);
 857     operator CvTermCriteria() const;
 858
 859     int type;
 860     int maxCount;
 861     double epsilon;
 862 };
 863 \end{lstlisting}
 864
 865 The class \texttt{TermCriteria} replaces the old \cross{CvTermCriteria} and fully compatible with it.
 866
 867
 868 \subsection{Vec}\label{Vec}
 869 Template class for short numerical vectors
 870
 871 \begin{lstlisting}
 872 template<typename _Tp, int cn> class Vec
 873 {
 874 public:
 875     typedef _Tp value_type;
 876     enum { depth = DataDepth<_Tp>::value, channels = cn,
 877            type = CV_MAKETYPE(depth, channels) };
 878
 879     // default constructor: all elements are set to 0
 880     Vec();
 881     // constructors taking up to 10 first elements as parameters
 882     Vec(_Tp v0);
 883     Vec(_Tp v0, _Tp v1);
 884     Vec(_Tp v0, _Tp v1, _Tp v2);
 885     ...
 886     Vec(_Tp v0, _Tp v1, _Tp v2, _Tp v3, _Tp v4,
 887         _Tp v5, _Tp v6, _Tp v7, _Tp v8, _Tp v9);
 888     Vec(const Vec<_Tp, cn>& v);
 889     // constructs vector with all the components set to alpha.
 890     static Vec all(_Tp alpha);
 891
 892     // two variants of dot-product
 893     _Tp dot(const Vec& v) const;
 894     double ddot(const Vec& v) const;
 895
 896     // cross-product; valid only when cn == 3.
 897     Vec cross(const Vec& v) const;
 898
 899     // element type conversion
 900     template<typename T2> operator Vec<T2, cn>() const;
 901
 902     // conversion to/from CvScalar (valid only when cn==4)
 903     operator CvScalar() const;
 904
 905     // element access
 906     _Tp operator [](int i) const;
 907     _Tp& operator[](int i);
 908
 909     _Tp val[cn];
 910 };
 911 \end{lstlisting}
 912
 913 The class is the most universal representation of short numerical vectors or tuples. It is possible to convert \texttt{Vec<T,2>} to/from \texttt{Point\_}, \texttt{Vec<T,3>} to/from \texttt{Point3\_}, and \texttt{Vec<T,4>} to \cross{CvScalar}~. The elements of \texttt{Vec} are accessed using \texttt{operator[]}. All the expected vector operations are implemented too:
 914
 915 \begin{itemize}
 916     \item \texttt{v1 = $v2 \pm v3$, v1 = v2 * $\alpha$, v1 = $\alpha$ * v2} (plus the corresponding augmenting operations; note that these operations apply \hyperref[saturatecast]{saturate\_cast.3C.3E} to the each computed vector component)
 917     \item \texttt{v1 == v2, v1 != v2}
 918     \item \texttt{double n = norm(v1); // $L_2$-norm}
 919 \end{itemize}
 920
 921 For user convenience, the following type aliases are introduced:
 922 \begin{lstlisting}
 923 typedef Vec<uchar, 2> Vec2b;
 924 typedef Vec<uchar, 3> Vec3b;
 925 typedef Vec<uchar, 4> Vec4b;
 926
 927 typedef Vec<short, 2> Vec2s;
 928 typedef Vec<short, 3> Vec3s;
 929 typedef Vec<short, 4> Vec4s;
 930
 931 typedef Vec<int, 2> Vec2i;
 932 typedef Vec<int, 3> Vec3i;
 933 typedef Vec<int, 4> Vec4i;
 934
 935 typedef Vec<float, 2> Vec2f;
 936 typedef Vec<float, 3> Vec3f;
 937 typedef Vec<float, 4> Vec4f;
 938 typedef Vec<float, 6> Vec6f;
 939
 940 typedef Vec<double, 2> Vec2d;
 941 typedef Vec<double, 3> Vec3d;
 942 typedef Vec<double, 4> Vec4d;
 943 typedef Vec<double, 6> Vec6d;
 944 \end{lstlisting}
 945
 946 The class \texttt{Vec} can be used for declaring various numerical objects, e.g. \texttt{Vec<double,9>} can be used to store a 3x3 double-precision matrix. It is also very useful for declaring and processing multi-channel arrays, see \texttt{Mat\_} description.
 947
 948 \subsection{Scalar\_}
 949 4-element vector
 950
 951 \begin{lstlisting}
 952 template<typename _Tp> class Scalar_ : public Vec<_Tp, 4>
 953 {
 954 public:
 955     Scalar_();
 956     Scalar_(_Tp v0, _Tp v1, _Tp v2=0, _Tp v3=0);
 957     Scalar_(const CvScalar& s);
 958     Scalar_(_Tp v0);
 959     static Scalar_<_Tp> all(_Tp v0);
 960     operator CvScalar() const;
 961
 962     template<typename T2> operator Scalar_<T2>() const;
 963
 964     Scalar_<_Tp> mul(const Scalar_<_Tp>& t, double scale=1 ) const;
 965     template<typename T2> void convertTo(T2* buf, int channels, int unroll_to=0) const;
 966 };
 967
 968 typedef Scalar_<double> Scalar;
 969 \end{lstlisting}
 970
 971 The template class \texttt{Scalar\_} and it's double-precision instantiation \texttt{Scalar} represent 4-element vector. Being derived from \texttt{Vec<\_Tp, 4>}, they can be used as typical 4-element vectors, but in addition they can be converted to/from \texttt{CvScalar}. The type \texttt{Scalar} is widely used in OpenCV for passing pixel values and it is a drop-in replacement for \cross{CvScalar} that was used for the same purpose in the earlier versions of OpenCV.
 972
 973 \subsection{Range}\label{Range}
 974 Specifies a continuous subsequence (a.k.a. slice) of a sequence.
 975
 976 \begin{lstlisting}
 977 class Range
 978 {
 979 public:
 980     Range();
 981     Range(int _start, int _end);
 982     Range(const CvSlice& slice);
 983     int size() const;
 984     bool empty() const;
 985     static Range all();
 986     operator CvSlice() const;
 987
 988     int start, end;
 989 };
 990 \end{lstlisting}
 991
 992 The class is used to specify a row or column span in a matrix (\cross{Mat}), and for many other purposes. \texttt{Range(a,b)} is basically the same as \texttt{a:b} in Matlab or \texttt{a..b} in Python. As in Python, \texttt{start} is inclusive left boundary of the range, and \texttt{end} is exclusive right boundary of the range. Such a half-opened interval is usually denoted as $[start,end)$.
 993
 994 The static method \texttt{Range::all()} returns some special variable that means "the whole sequence" or "the whole range", just like "\texttt{:}" in Matlab or "\texttt{...}" in Python. All the methods and functions in OpenCV that take \texttt{Range} support this special \texttt{Range::all()} value, but of course, in the case of your own custom processing you will probably have to check and handle it explicitly:
 995 \begin{lstlisting}
 996 void my_function(..., const Range& r, ....)
 997 {
 998     if(r == Range::all()) {
 999         // process all the data
1000     }
1001     else {
1002         // process [r.start, r.end)
1003     }
1004 }
1005 \end{lstlisting}
1006
1007 \subsection{Ptr}\label{Ptr}
1008
1009 A template class for smart reference-counting pointers
1010
1011 \begin{lstlisting}
1012 template<typename _Tp> class Ptr
1013 {
1014 public:
1015     // default constructor
1016     Ptr();
1017     // constructor that wraps the object pointer
1018     Ptr(_Tp* _obj);
1019     // destructor: calls release()
1020     ~Ptr();
1021     // copy constructor; increments ptr's reference counter
1022     Ptr(const Ptr& ptr);
1023     // assignment operator; decrements own reference counter
1024     // (with release()) and increments ptr's reference counter
1025     Ptr& operator = (const Ptr& ptr);
1026     // increments reference counter
1027     void addref();
1028     // decrements reference counter; when it becomes 0,
1029     // delete_obj() is called
1030     void release();
1031     // user-specified custom object deletion operation.
1032     // by default, "delete obj;" is called
1033     void delete_obj();
1034     // returns true if obj == 0;
1035     bool empty() const;
1036
1037     // provide access to the object fields and methods
1038     _Tp* operator -> ();
1039     const _Tp* operator -> () const;
1040
1041     // return the underlying object pointer;
1042     // thanks to the methods, the Ptr<_Tp> can be
1043     // used instead of _Tp*
1044     operator _Tp* ();
1045     operator const _Tp*() const;
1046 protected:
1047     // the incapsulated object pointer
1048     _Tp* obj;
1049     // the associated reference counter
1050     int* refcount;
1051 };
1052 \end{lstlisting}
1053
1054 The class \texttt{Ptr<\_Tp>} is a template class that wraps pointers of the corresponding type. It is similar to \texttt{shared\_ptr} that is a part of Boost library (\url{http://www.boost.org/doc/libs/1_40_0/libs/smart_ptr/shared_ptr.htm}) and also a part of the
1055 \href{http://en.wikipedia.org/wiki/C++0x}{C++0x} standard.
1056
1057 By using this class you can get the following capabilities:
1058
1059 \begin{itemize}
1060     \item default constructor, copy constructor and assignment operator for an arbitrary C++ class or a C structure. For some objects, like files, windows, mutexes, sockets etc, copy constructor or assignment operator are difficult to define. For some other objects, like complex classifiers in OpenCV, copy constructors are absent and not easy to implement. Finally, some of complex OpenCV and your own data structures may have been written in C. However, copy constructors and default constructors can simplify programming a lot; besides, they are often required (e.g. by STL containers). By wrapping a pointer to such a complex object \texttt{TObj} to \texttt{Ptr<TObj>} you will automatically get all of the necessary constructors and the assignment operator.
1061     \item all the above-mentioned operations running very fast, regardless of the data size, i.e. as "O(1)" operations. Indeed, while some structures, like \texttt{std::vector} provide a copy constructor and an assignment operator, the operations may take considerable time if the data structures are big. But if the structures are put into \texttt{Ptr<>}, the overhead becomes small and independent of the data size.
1062     \item automatic destruction, even for C structures. See the example below with \texttt{FILE*}.
1063     \item heterogeneous collections of objects. The standard STL and most other C++ and OpenCV containers can only store objects of the same type and the same size. The classical solution to store objects of different types in the same container is to store pointers to the base class \texttt{base\_class\_t*} instead, but when you loose the automatic memory management. Again, by using \texttt{Ptr<base\_class\_t>()} instead of the raw pointers, you can solve the problem.
1064 \end{itemize}
1065
1066 The class \texttt{Ptr} treats the wrapped object as a black box, the reference counter is allocated and managed separately. The only thing the pointer class needs to know about the object is how to deallocate it. This knowledge is incapsulated in \texttt{Ptr::delete\_obj()} method, which is called when the reference counter becomes 0. If the object is a C++ class instance, no additional coding is needed, because the default implementation of this method calls \texttt{delete obj;}.
1067 However, if the object is deallocated in a different way, then the specialized method should be created. For example, if you want to wrap \texttt{FILE}, the \texttt{delete\_obj} may be implemented as following:
1068
1069 \begin{lstlisting}
1070 template<> inline void Ptr<FILE>::delete_obj()
1071 {
1072     fclose(obj); // no need to clear the pointer afterwards,
1073                  // it is done externally.
1074 }
1075 ...
1076
1077 // now use it:
1078 Ptr<FILE> f(fopen("myfile.txt", "r"));
1079 if(f.empty())
1080     throw ...;
1081 fprintf(f, ....);
1082 ...
1083 // the file will be closed automatically by the Ptr<FILE> destructor.
1084 \end{lstlisting}
1085
1086 \textbf{Note}: The reference increment/decrement operations are implemented as atomic operations, and therefore it is normally safe to use the classes in multi-threaded applications. The same is true for \cross{Mat} and other C++ OpenCV classes that operate on the reference counters.
1087
1088 \subsection{Mat}\label{Mat}
1089
1090 OpenCV C++ matrix class.
1091
1092 \begin{lstlisting}
1093 class Mat
1094 {
1095 public:
1096     // constructors
1097     Mat();
1098     // constructs matrix of the specified size and type
1099     // (_type is CV_8UC1, CV_64FC3, CV_32SC(12) etc.)
1100     Mat(int _rows, int _cols, int _type);
1101     // constucts matrix and fills it with the specified value _s.
1102     Mat(int _rows, int _cols, int _type, const Scalar& _s);
1103     Mat(Size _size, int _type);
1104     // copy constructor
1105     Mat(const Mat& m);
1106     // constructor for matrix headers pointing to user-allocated data
1107     Mat(int _rows, int _cols, int _type, void* _data, size_t _step=AUTO_STEP);
1108     Mat(Size _size, int _type, void* _data, size_t _step=AUTO_STEP);
1109     // creates a matrix header for a part of the bigger matrix
1110     Mat(const Mat& m, const Range& rowRange, const Range& colRange);
1111     Mat(const Mat& m, const Rect& roi);
1112     // converts old-style CvMat to the new matrix; the data is not copied by default
1113     Mat(const CvMat* m, bool copyData=false);
1114     // converts old-style IplImage to the new matrix; the data is not copied by default
1115     Mat(const IplImage* img, bool copyData=false);
1116     // builds matrix from std::vector with or without copying the data
1117     template<typename _Tp> Mat(const vector<_Tp>& vec, bool copyData=false);
1118     // helper constructor to compile matrix expressions
1119     Mat(const MatExpr_Base& expr);
1120     // destructor - calls release()
1121     ~Mat();
1122     // assignment operators
1123     Mat& operator = (const Mat& m);
1124     Mat& operator = (const MatExpr_Base& expr);
1125
1126     ...
1127     // returns a new matrix header for the specified row
1128     Mat row(int y) const;
1129     // returns a new matrix header for the specified column
1130     Mat col(int x) const;
1131     // ... for the specified row span
1132     Mat rowRange(int startrow, int endrow) const;
1133     Mat rowRange(const Range& r) const;
1134     // ... for the specified column span
1135     Mat colRange(int startcol, int endcol) const;
1136     Mat colRange(const Range& r) const;
1137     // ... for the specified diagonal
1138     // (d=0 - the main diagonal,
1139     //  >0 - a diagonal from the lower half,
1140     //  <0 - a diagonal from the upper half)
1141     Mat diag(int d=0) const;
1142     // constructs a square diagonal matrix which main diagonal is vector "d"
1143     static Mat diag(const Mat& d);
1144
1145     // returns deep copy of the matrix, i.e. the data is copied
1146     Mat clone() const;
1147     // copies the matrix content to "m".
1148     // It calls m.create(this->size(), this->type()).
1149     void copyTo( Mat& m ) const;
1150     // copies those matrix elements to "m" that are marked with non-zero mask elements.
1151     void copyTo( Mat& m, const Mat& mask ) const;
1152     // converts matrix to another datatype with optional scalng. See cvConvertScale.
1153     void convertTo( Mat& m, int rtype, double alpha=1, double beta=0 ) const;
1154
1155     ...
1156     // sets every matrix element to s
1157     Mat& operator = (const Scalar& s);
1158     // sets some of the matrix elements to s, according to the mask
1159     Mat& setTo(const Scalar& s, const Mat& mask=Mat());
1160     // creates alternative matrix header for the same data, with different
1161     // number of channels and/or different number of rows. see cvReshape.
1162     Mat reshape(int _cn, int _rows=0) const;
1163
1164     // matrix transposition by means of matrix expressions
1165     MatExpr_<...> t() const;
1166     // matrix inversion by means of matrix expressions
1167     MatExpr_<...> inv(int method=DECOMP_LU) const;
1168     // per-element matrix multiplication by means of matrix expressions
1169     MatExpr_<...> mul(const Mat& m, double scale=1) const;
1170     MatExpr_<...> mul(const MatExpr_<...>& m, double scale=1) const;
1171
1172     // computes cross-product of 2 3D vectors
1173     Mat cross(const Mat& m) const;
1174     // computes dot-product
1175     double dot(const Mat& m) const;
1176
1177     // Matlab-style matrix initialization. see the description
1178     static MatExpr_Initializer zeros(int rows, int cols, int type);
1179     static MatExpr_Initializer zeros(Size size, int type);
1180     static MatExpr_Initializer ones(int rows, int cols, int type);
1181     static MatExpr_Initializer ones(Size size, int type);
1182     static MatExpr_Initializer eye(int rows, int cols, int type);
1183     static MatExpr_Initializer eye(Size size, int type);
1184
1185     // allocates new matrix data unless the matrix already has specified size and type.
1186     // previous data is unreferenced if needed.
1187     void create(int _rows, int _cols, int _type);
1188     void create(Size _size, int _type);
1189     // increases the reference counter; use with care to avoid memleaks
1190     void addref();
1191     // decreases reference counter;
1192     // deallocate the data when reference counter reaches 0.
1193     void release();
1194
1195     // locates matrix header within a parent matrix. See below
1196     void locateROI( Size& wholeSize, Point& ofs ) const;
1197     // moves/resizes the current matrix ROI inside the parent matrix.
1198     Mat& adjustROI( int dtop, int dbottom, int dleft, int dright );
1199     // extracts a rectangular sub-matrix
1200     // (this is a generalized form of row, rowRange etc.)
1201     Mat operator()( Range rowRange, Range colRange ) const;
1202     Mat operator()( const Rect& roi ) const;
1203
1204     // converts header to CvMat; no data is copied
1205     operator CvMat() const;
1206     // converts header to IplImage; no data is copied
1207     operator IplImage() const;
1208
1209     // returns true iff the matrix data is continuous
1210     // (i.e. when there are no gaps between successive rows).
1211     // similar to CV_IS_MAT_CONT(cvmat->type)
1212     bool isContinuous() const;
1213     // returns element size in bytes,
1214     // similar to CV_ELEM_SIZE(cvmat->type)
1215     size_t elemSize() const;
1216     // returns the size of element channel in bytes.
1217     size_t elemSize1() const;
1218     // returns element type, similar to CV_MAT_TYPE(cvmat->type)
1219     int type() const;
1220     // returns element type, similar to CV_MAT_DEPTH(cvmat->type)
1221     int depth() const;
1222     // returns element type, similar to CV_MAT_CN(cvmat->type)
1223     int channels() const;
1224     // returns step/elemSize1()
1225     size_t step1() const;
1226     // returns matrix size:
1227     // width == number of columns, height == number of rows
1228     Size size() const;
1229     // returns true if matrix data is NULL
1230     bool empty() const;
1231
1232     // returns pointer to y-th row
1233     uchar* ptr(int y=0);
1234     const uchar* ptr(int y=0) const;
1235
1236     // template version of the above method
1237     template<typename _Tp> _Tp* ptr(int y=0);
1238     template<typename _Tp> const _Tp* ptr(int y=0) const;
1239
1240     // template methods for read-write or read-only element access.
1241     // note that _Tp must match the actual matrix type -
1242     // the functions do not do any on-fly type conversion
1243     template<typename _Tp> _Tp& at(int y, int x);
1244     template<typename _Tp> _Tp& at(Point pt);
1245     template<typename _Tp> const _Tp& at(int y, int x) const;
1246     template<typename _Tp> const _Tp& at(Point pt) const;
1247
1248     // template methods for iteration over matrix elements.
1249     // the iterators take care of skipping gaps in the end of rows (if any)
1250     template<typename _Tp> MatIterator_<_Tp> begin();
1251     template<typename _Tp> MatIterator_<_Tp> end();
1252     template<typename _Tp> MatConstIterator_<_Tp> begin() const;
1253     template<typename _Tp> MatConstIterator_<_Tp> end() const;
1254
1255     enum { MAGIC_VAL=0x42FF0000, AUTO_STEP=0, CONTINUOUS_FLAG=CV_MAT_CONT_FLAG };
1256
1257     // includes several bit-fields:
1258     //  * the magic signature
1259     //  * continuity flag
1260     //  * depth
1261     //  * number of channels
1262     int flags;
1263     // the number of rows and columns
1264     int rows, cols;
1265     // a distance between successive rows in bytes; includes the gap if any
1266     size_t step;
1267     // pointer to the data
1268     uchar* data;
1269
1270     // pointer to the reference counter;
1271     // when matrix points to user-allocated data, the pointer is NULL
1272     int* refcount;
1273
1274     // helper fields used in locateROI and adjustROI
1275     uchar* datastart;
1276     uchar* dataend;
1277 };
1278 \end{lstlisting}
1279
1280 The class \texttt{Mat} represents a 2D numerical array that can act as a matrix (and further it's referred to as a matrix), image, optical flow map etc. It is very similar to \cross{CvMat} type from earlier versions of OpenCV, and similarly to \texttt{CvMat}, the matrix can be multi-channel, but it also fully supports \cross{ROI} mechanism, just like \cross{IplImage}.
1281
1282 There are many different ways to create \texttt{Mat} object. Here are the some popular ones:
1283 \begin{itemize}
1284 \item using \texttt{create(nrows, ncols, type)} method or
1285     the similar constructor \texttt{Mat(nrows, ncols, type[, fill\_value])} constructor.
1286     A new matrix of the specified size and specifed type will be allocated.
1287     \texttt{type} has the same meaning as in \cvCppCross{cvCreateMat} method,
1288     e.g. \texttt{CV\_8UC1} means 8-bit single-channel matrix,
1289     \texttt{CV\_32FC2} means 2-channel (i.e. complex) floating-point matrix etc:
1290
1291 \begin{lstlisting}
1292 // make 7x7 complex matrix filled with 1+3j.
1293 cv::Mat M(7,7,CV_32FC2,Scalar(1,3));
1294 // and now turn M to 100x60 15-channel 8-bit matrix.
1295 // The old content will be deallocated
1296 M.create(100,60,CV_8UC(15));
1297 \end{lstlisting}
1298
1299     As noted in the introduction of this chapter, \texttt{create()}
1300     will only allocate a new matrix when the current matrix dimensionality
1301     or type are different from the specified.
1302
1303 \item by using a copy constructor or assignment operator, where on the right side it can
1304       be a matrix or expression, see below. Again, as noted in the introduction,
1305       matrix assignment is O(1) operation because it only copies the header
1306       and increases the reference counter. \texttt{Mat::clone()} method can be used to get a full
1307       (a.k.a. deep) copy of the matrix when you need it.
1308
1309 \item by constructing a header for a part of another matrix. It can be a single row, single column,
1310       several rows, several columns, rectangular region in the matrix (called a minor in algebra) or
1311       a diagonal. Such operations are also O(1), because the new header will reference the same data.
1312       You can actually modify a part of the matrix using this feature, e.g.
1313
1314 \begin{lstlisting}
1315 // add 5-th row, multiplied by 3 to the 3rd row
1316 M.row(3) = M.row(3) + M.row(5)*3;
1317
1318 // now copy 7-th column to the 1-st column
1319 // M.col(1) = M.col(7); // this will not work
1320 Mat M1 = M.col(1);
1321 M.col(7).copyTo(M1);
1322
1323 // create new 320x240 image
1324 cv::Mat img(Size(320,240),CV_8UC3);
1325 // select a roi
1326 cv::Mat roi(img, Rect(10,10,100,100));
1327 // fill the ROI with (0,255,0) (which is green in RGB space);
1328 // the original 320x240 image will be modified
1329 roi = Scalar(0,255,0);
1330 \end{lstlisting}
1331
1332       Thanks to the additional \texttt{datastart} and \texttt{dataend} members, it is possible to
1333       compute the relative sub-matrix position in the main \emph{"container"} matrix using \texttt{locateROI()}:
1334
1335 \begin{lstlisting}
1336 Mat A = Mat::eye(10, 10, CV_32S);
1337 // extracts A columns, 1 (inclusive) to 3 (exclusive).
1338 Mat B = A(Range::all(), Range(1, 3));
1339 // extracts B rows, 5 (inclusive) to 9 (exclusive).
1340 // that is, C ~ A(Range(5, 9), Range(1, 3))
1341 Mat C = B(Range(5, 9), Range::all());
1342 Size size; Point ofs;
1343 C.locateROI(size, ofs);
1344 // size will be (width=10,height=10) and the ofs will be (x=1, y=5)
1345 \end{lstlisting}
1346
1347       As in the case of whole matrices, if you need a deep copy, use \texttt{clone()} method
1348       of the extracted sub-matrices.
1349
1350 \item by making a header for user-allocated-data. It can be useful for
1351     \begin{enumerate}
1352         \item processing "foreign" data using OpenCV (e.g. when you implement
1353         a DirectShow filter or a processing module for gstreamer etc.), e.g.
1354
1355 \begin{lstlisting}
1356 void process_video_frame(const unsigned char* pixels,
1357                          int width, int height, int step)
1358 {
1359     cv::Mat img(height, width, CV_8UC3, pixels, step);
1360     cv::GaussianBlur(img, img, cv::Size(7,7), 1.5, 1.5);
1361 }
1362 \end{lstlisting}
1363
1364         \item for quick initialization of small matrices and/or super-fast element access
1365 \begin{lstlisting}
1366 double m[3][3] = {{a, b, c}, {d, e, f}, {g, h, i}};
1367 cv::Mat M = cv::Mat(3, 3, CV_64F, m).inv();
1368 \end{lstlisting}
1369         \end{enumerate}
1370
1371         partial yet very common cases of this "user-allocated data" case are conversions
1372         from \cross{CvMat} and \cross{IplImage} to \texttt{Mat}. For this purpose there are special constructors
1373         taking pointers to \texttt{CvMat} or \texttt{IplImage} and the optional
1374         flag indicating whether to copy the data or not.
1375
1376         Backward conversion from \texttt{Mat} to \texttt{CvMat} or \texttt{IplImage} is provided via cast operators
1377         \texttt{Mat::operator CvMat() const} an \texttt{Mat::operator IplImage()}.
1378         The operators do \emph{not} copy the data.
1379
1380 \begin{lstlisting}
1381 IplImage* img = cvLoadImage("greatwave.jpg", 1);
1382 Mat mtx(img); // convert IplImage* -> cv::Mat
1383 CvMat oldmat = mtx; // convert cv::Mat -> CvMat
1384 CV_Assert(oldmat.cols == img->width && oldmat.rows == img->height &&
1385     oldmat.data.ptr == (uchar*)img->imageData && oldmat.step == img->widthStep);
1386 \end{lstlisting}
1387
1388 \item by using MATLAB-style matrix initializers, \texttt{zeros(), ones(), eye()}, e.g.:
1389
1390 \begin{lstlisting}
1391 // create a double-precision identity martix and add it to M.
1392 M += Mat::eye(M.rows, M.cols, CV_64F);
1393 \end{lstlisting}
1394
1395 \item by using comma-separated initializer:
1396 \begin{lstlisting}
1397 // create 3x3 double-precision identity matrix
1398 Mat M = (Mat_<double>(3,3) << 1, 0, 0, 0, 1, 0, 0, 0, 1);
1399 \end{lstlisting}
1400
1401 here we first call constructor of \texttt{Mat\_} class (that we describe further) with the proper matrix, and then we just put \texttt{<<} operator followed by comma-separated values that can be constants, variables, expressions etc. Also, note the extra parentheses that are needed to avoid compiler errors.
1402
1403 \end{itemize}
1404
1405 Once matrix is created, it will be automatically managed by using reference-counting mechanism (unless the matrix header is built on top of user-allocated data, in which case you should handle the data by yourself).
1406 The matrix data will be deallocated when no one points to it; if you want to release the data pointed by a matrix header before the matrix destructor is called, use \texttt{Mat::release()}.
1407
1408 The next important thing to learn about the matrix class is element access. Here is how the matrix is stored. The elements are stored in row-major order (row by row). The \texttt{Mat::data} member points to the first element of the first row, \texttt{Mat::rows} contains the number of matrix rows and \texttt{Mat::cols} -- the number of matrix columns. There is yet another member, called \texttt{Mat::step} that is used to actually compute address of a matrix element. The \texttt{Mat::step} is needed because the matrix can be a part of another matrix or because there can some padding space in the end of each row for a proper alignment.
1409 %\includegraphics[width=1.0\textwidth]{pics/roi.png}
1410
1411 Given these parameters, address of the matrix element $M_{ij}$ is computed as following:
1412
1413
1414 \texttt{addr($M_{ij}$)=M.data + M.step*i + j*M.elemSize()}
1415
1416
1417 if you know the matrix element type, e.g. it is \texttt{float}, then you can use \texttt{at<>()} method:
1418
1419
1420 \texttt{addr($M_{ij}$)=\&M.at<float>(i,j)}
1421
1422 (where \& is used to convert the reference returned by \texttt{at} to a pointer).
1423 if you need to process a whole row of matrix, the most efficient way is to get the pointer to the row first, and then just use plain C operator \texttt{[]}:
1424
1425 \begin{lstlisting}
1426 // compute sum of positive matrix elements
1427 // (assuming that M is double-precision matrix)
1428 double sum=0;
1429 for(int i = 0; i < M.rows; i++)
1430 {
1431     const double* Mi = M.ptr<double>(i);
1432     for(int j = 0; j < M.cols; j++)
1433         sum += std::max(Mi[j], 0.);
1434 }
1435 \end{lstlisting}
1436
1437 Some operations, like the above one, do not actually depend on the matrix shape, they just process elements of a matrix one by one (or elements from multiple matrices that are sitting in the same place, e.g. matrix addition). Such operations are called element-wise and it makes sense to check whether all the input/output matrices are continuous, i.e. have no gaps in the end of each row, and if yes, process them as a single long row:
1438
1439 \begin{lstlisting}
1440 // compute sum of positive matrix elements, optimized variant
1441 double sum=0;
1442 int cols = M.cols, rows = M.rows;
1443 if(M.isContinuous())
1444 {
1445     cols *= rows;
1446     rows = 1;
1447 }
1448 for(int i = 0; i < rows; i++)
1449 {
1450     const double* Mi = M.ptr<double>(i);
1451     for(int j = 0; j < cols; j++)
1452         sum += std::max(Mi[j], 0.);
1453 }
1454 \end{lstlisting}
1455 in the case of continuous matrix the outer loop body will be executed just once, so the overhead will be smaller, which will be especially noticeable in the case of small matrices.
1456
1457 Finally, there are STL-style iterators that are smart enough to skip gaps between successive rows:
1458 \begin{lstlisting}
1459 // compute sum of positive matrix elements, iterator-based variant
1460 double sum=0;
1461 MatConstIterator_<double> it = M.begin<double>(), it_end = M.end<double>();
1462 for(; it != it_end; ++it)
1463     sum += std::max(*it, 0.);
1464 \end{lstlisting}
1465
1466 The matrix iterators are random-access iterators, so they can be passed to any STL algorithm, including \texttt{std::sort()}.
1467
1468 \subsection{Matrix Expressions}
1469
1470 This is a list of implemented matrix operations that can be combined in arbitrary complex expressions
1471 (here \emph{A}, \emph{B} stand for matrices (\texttt{Mat}), \emph{s} for a scalar (\texttt{Scalar}),
1472 \emph{$\alpha$} for a real-valued scalar (\texttt{double})):
1473
1474 \begin{itemize}
1475     \item addition, subtraction, negation: $\texttt{A}\pm \texttt{B},\;\texttt{A}\pm \texttt{s},\;\texttt{s}\pm \texttt{A},\;-\texttt{A}$
1476     \item scaling: \texttt{A*$\alpha$, A/$\alpha$}
1477     \item per-element multiplication and division: \texttt{A.mul(B), A/B, $\alpha$/A}
1478     \item matrix multiplication: \texttt{A*B}
1479     \item transposition: \texttt{A.t() $\sim A^t$}
1480     \item matrix inversion and pseudo-inversion, solving linear systems and least-squares problems:
1481         \texttt{A.inv([method]) $\sim A^{-1}$}, \texttt{A.inv([method])*B $\sim X:\,AX=B$}
1482     \item comparison: $\texttt{A}\gtreqqless \texttt{B},\;\texttt{A} \ne \texttt{B},\;\texttt{A}\gtreqqless \alpha,\; \texttt{A} \ne \alpha$.
1483           The result of comparison is 8-bit single channel mask, which elements are set to 255
1484           (if the particular element or pair of elements satisfy the condition) and 0 otherwise.
1485     \item bitwise logical operations: \verb"A & B, A & s, A | B, A | s, A ^ B, A ^ s, ~A"
1486     \item element-wise minimum and maximum: \texttt{min(A, B), min(A, $\alpha$), max(A, B), max(A, $\alpha$)}
1487     \item element-wise absolute value: \texttt{abs(A)}
1488     \item cross-product, dot-product: \texttt{A.cross(B), A.dot(B)}
1489     \item any function of matrix or matrices and scalars that returns a matrix or a scalar, such as
1490           \cvCppCross{norm}, \cvCppCross{mean}, \cvCppCross{sum}, \cvCppCross{countNonZero}, \cvCppCross{trace},
1491           \cvCppCross{determinant}, \cvCppCross{repeat} etc.
1492     \item matrix initializers (\texttt{eye(), zeros(), ones()}), matrix comma-separated initializers,
1493           matrix constructors and operators that extract sub-matrices (see \cross{Mat} description).
1494     \item \verb"Mat_<destination_type>()" constructors to cast the result to the proper type.
1495 \end{itemize}
1496 Note, however, that comma-separated initializers and probably some other operations may require additional explicit \texttt{Mat()} or \verb"Mat_<T>()" constuctor calls to resolve possible ambiguity.
1497
1498 \subsection{Mat\_}\label{MatT}
1499 Template matrix class derived from \cross{Mat}
1500
1501 \begin{lstlisting}
1502 template<typename _Tp> class Mat_ : public Mat
1503 {
1504 public:
1505     typedef _Tp value_type;
1506     typedef typename DataType<_Tp>::channel_type channel_type;
1507     typedef MatIterator_<_Tp> iterator;
1508     typedef MatConstIterator_<_Tp> const_iterator;
1509
1510     Mat_();
1511     // equivalent to Mat(_rows, _cols, DataType<_Tp>::type)
1512     Mat_(int _rows, int _cols);
1513     // other forms of the above constructor
1514     Mat_(int _rows, int _cols, const _Tp& value);
1515     explicit Mat_(Size _size);
1516     Mat_(Size _size, const _Tp& value);
1517     // copy/conversion contructor. If m is of different type, it's converted
1518     Mat_(const Mat& m);
1519     // copy constructor
1520     Mat_(const Mat_& m);
1521     // construct a matrix on top of user-allocated data.
1522     // step is in bytes(!!!), regardless of the type
1523     Mat_(int _rows, int _cols, _Tp* _data, size_t _step=AUTO_STEP);
1524     // minor selection
1525     Mat_(const Mat_& m, const Range& rowRange, const Range& colRange);
1526     Mat_(const Mat_& m, const Rect& roi);
1527     // to support complex matrix expressions
1528     Mat_(const MatExpr_Base& expr);
1529     // makes a matrix out of Vec or std::vector. The matrix will have a single column
1530     template<int n> explicit Mat_(const Vec<_Tp, n>& vec);
1531     Mat_(const vector<_Tp>& vec, bool copyData=false);
1532
1533     Mat_& operator = (const Mat& m);
1534     Mat_& operator = (const Mat_& m);
1535     // set all the elements to s.
1536     Mat_& operator = (const _Tp& s);
1537
1538     // iterators; they are smart enough to skip gaps in the end of rows
1539     iterator begin();
1540     iterator end();
1541     const_iterator begin() const;
1542     const_iterator end() const;
1543
1544     // equivalent to Mat::create(_rows, _cols, DataType<_Tp>::type)
1545     void create(int _rows, int _cols);
1546     void create(Size _size);
1547     // cross-product
1548     Mat_ cross(const Mat_& m) const;
1549     // to support complex matrix expressions
1550     Mat_& operator = (const MatExpr_Base& expr);
1551     // data type conversion
1552     template<typename T2> operator Mat_<T2>() const;
1553     // overridden forms of Mat::row() etc.
1554     Mat_ row(int y) const;
1555     Mat_ col(int x) const;
1556     Mat_ diag(int d=0) const;
1557     Mat_ clone() const;
1558
1559     // transposition, inversion, per-element multiplication
1560     MatExpr_<...> t() const;
1561     MatExpr_<...> inv(int method=DECOMP_LU) const;
1562
1563     MatExpr_<...> mul(const Mat_& m, double scale=1) const;
1564     MatExpr_<...> mul(const MatExpr_<...>& m, double scale=1) const;
1565
1566     // overridden forms of Mat::elemSize() etc.
1567     size_t elemSize() const;
1568     size_t elemSize1() const;
1569     int type() const;
1570     int depth() const;
1571     int channels() const;
1572     size_t step1() const;
1573     // returns step()/sizeof(_Tp)
1574     size_t stepT() const;
1575
1576     // overridden forms of Mat::zeros() etc. Data type is omitted, of course
1577     static MatExpr_Initializer zeros(int rows, int cols);
1578     static MatExpr_Initializer zeros(Size size);
1579     static MatExpr_Initializer ones(int rows, int cols);
1580     static MatExpr_Initializer ones(Size size);
1581     static MatExpr_Initializer eye(int rows, int cols);
1582     static MatExpr_Initializer eye(Size size);
1583
1584     // some more overriden methods
1585     Mat_ reshape(int _rows) const;
1586     Mat_& adjustROI( int dtop, int dbottom, int dleft, int dright );
1587     Mat_ operator()( const Range& rowRange, const Range& colRange ) const;
1588     Mat_ operator()( const Rect& roi ) const;
1589
1590     // more convenient forms of row and element access operators
1591     _Tp* operator [](int y);
1592     const _Tp* operator [](int y) const;
1593
1594     _Tp& operator ()(int row, int col);
1595     const _Tp& operator ()(int row, int col) const;
1596     _Tp& operator ()(Point pt);
1597     const _Tp& operator ()(Point pt) const;
1598
1599     // to support matrix expressions
1600     operator MatExpr_<Mat_, Mat_>() const;
1601
1602     // conversion to vector.
1603     operator vector<_Tp>() const;
1604 };
1605 \end{lstlisting}
1606
1607 The class \texttt{Mat\_<\_Tp>} is a "thin" template wrapper on top of \texttt{Mat} class. It does not have any extra data fields, nor it or \texttt{Mat} have any virtual methods and thus references or pointers to these two classes can be freely converted one to another. But do it with care, e.g.:
1608
1609 \begin{lstlisting}
1610 // create 100x100 8-bit matrix
1611 Mat M(100,100,CV_8U);
1612 // this will compile fine. no any data conversion will be done.
1613 Mat_<float>& M1 = (Mat_<float>&)M;
1614 // the program will likely crash at the statement below
1615 M1(99,99) = 1.f;
1616 \end{lstlisting}
1617
1618 While \texttt{Mat} is sufficient in most cases, \texttt{Mat\_} can be more convenient if you use a lot of element access operations and if you know matrix type at compile time. Note that \texttt{Mat::at<\_Tp>(int y, int x)} and \texttt{Mat\_<\_Tp>::operator ()(int y, int x)} do absolutely the same and run at the same speed, but the latter is certainly shorter:
1619
1620 \begin{lstlisting}
1621 Mat_<double> M(20,20);
1622 for(int i = 0; i < M.rows; i++)
1623     for(int j = 0; j < M.cols; j++)
1624         M(i,j) = 1./(i+j+1);
1625 Mat E, V;
1626 eigen(M,E,V);
1627 cout << E.at<double>(0,0)/E.at<double>(M.rows-1,0);
1628 \end{lstlisting}
1629
1630 \emph{How to use \texttt{Mat\_} for multi-channel images/matrices?}
1631
1632 This is simple - just pass \texttt{Vec} as \texttt{Mat\_} parameter:
1633 \begin{lstlisting}
1634 // allocate 320x240 color image and fill it with green (in RGB space)
1635 Mat_<Vec3b> img(240, 320, Vec3b(0,255,0));
1636 // now draw a diagonal white line
1637 for(int i = 0; i < 100; i++)
1638     img(i,i)=Vec3b(255,255,255);
1639 // and now scramble the 2nd (red) channel of each pixel
1640 for(int i = 0; i < img.rows; i++)
1641     for(int j = 0; j < img.cols; j++)
1642         img(i,j)[2] ^= (uchar)(i ^ j);
1643 \end{lstlisting}
1644
1645 \subsection{MatND}\label{MatND}
1646 n-dimensional dense array
1647
1648 \begin{lstlisting}
1649 class MatND
1650 {
1651 public:
1652     // default constructor
1653     MatND();
1654     // constructs array with specific size and data type
1655     MatND(int _ndims, const int* _sizes, int _type);
1656     // constructs array and fills it with the specified value
1657     MatND(int _ndims, const int* _sizes, int _type, const Scalar& _s);
1658     // copy constructor. only the header is copied.
1659     MatND(const MatND& m);
1660     // sub-array selection. only the header is copied
1661     MatND(const MatND& m, const Range* ranges);
1662     // converts old-style nd array to MatND; optionally, copies the data
1663     MatND(const CvMatND* m, bool copyData=false);
1664     ~MatND();
1665     MatND& operator = (const MatND& m);
1666
1667     // creates a complete copy of the matrix (all the data is copied)
1668     MatND clone() const;
1669     // sub-array selection; only the header is copied
1670     MatND operator()(const Range* ranges) const;
1671
1672     // copies the data to another matrix.
1673     // Calls m.create(this->size(), this->type()) prior to
1674     // copying the data
1675     void copyTo( MatND& m ) const;
1676     // copies only the selected elements to another matrix.
1677     void copyTo( MatND& m, const MatND& mask ) const;
1678     // converts data to the specified data type.
1679     // calls m.create(this->size(), rtype) prior to the conversion
1680     void convertTo( MatND& m, int rtype, double alpha=1, double beta=0 ) const;
1681
1682     // assigns "s" to each array element.
1683     MatND& operator = (const Scalar& s);
1684     // assigns "s" to the selected elements of array
1685     // (or to all the elements if mask==MatND())
1686     MatND& setTo(const Scalar& s, const MatND& mask=MatND());
1687     // modifies geometry of array without copying the data
1688     MatND reshape(int _newcn, int _newndims=0, const int* _newsz=0) const;
1689
1690     // allocates a new buffer for the data unless the current one already
1691     // has the specified size and type.
1692     void create(int _ndims, const int* _sizes, int _type);
1693     // manually increment reference counter (use with care !!!)
1694     void addref();
1695     // decrements the reference counter. Dealloctes the data when
1696     // the reference counter reaches zero.
1697     void release();
1698
1699     // converts the matrix to 2D Mat or to the old-style CvMatND.
1700     // In either case the data is not copied.
1701     operator Mat() const;
1702     operator CvMatND() const;
1703     // returns true if the array data is stored continuously
1704     bool isContinuous() const;
1705     // returns size of each element in bytes
1706     size_t elemSize() const;
1707     // returns size of each element channel in bytes
1708     size_t elemSize1() const;
1709     // returns OpenCV data type id (CV_8UC1, ... CV_64FC4,...)
1710     int type() const;
1711     // returns depth (CV_8U ... CV_64F)
1712     int depth() const;
1713     // returns the number of channels
1714     int channels() const;
1715     // step1() ~ step()/elemSize1()
1716     size_t step1(int i) const;
1717
1718     // return pointer to the element (versions for 1D, 2D, 3D and generic nD cases)
1719     uchar* ptr(int i0);
1720     const uchar* ptr(int i0) const;
1721     uchar* ptr(int i0, int i1);
1722     const uchar* ptr(int i0, int i1) const;
1723     uchar* ptr(int i0, int i1, int i2);
1724     const uchar* ptr(int i0, int i1, int i2) const;
1725     uchar* ptr(const int* idx);
1726     const uchar* ptr(const int* idx) const;
1727
1728     // convenient template methods for element access.
1729     // note that _Tp must match the actual matrix type -
1730     // the functions do not do any on-fly type conversion
1731     template<typename _Tp> _Tp& at(int i0);
1732     template<typename _Tp> const _Tp& at(int i0) const;
1733     template<typename _Tp> _Tp& at(int i0, int i1);
1734     template<typename _Tp> const _Tp& at(int i0, int i1) const;
1735     template<typename _Tp> _Tp& at(int i0, int i1, int i2);
1736     template<typename _Tp> const _Tp& at(int i0, int i1, int i2) const;
1737     template<typename _Tp> _Tp& at(const int* idx);
1738     template<typename _Tp> const _Tp& at(const int* idx) const;
1739
1740     enum { MAGIC_VAL=0x42FE0000, AUTO_STEP=-1,
1741         CONTINUOUS_FLAG=CV_MAT_CONT_FLAG, MAX_DIM=CV_MAX_DIM };
1742
1743     // combines data type, continuity flag, signature (magic value)
1744     int flags;
1745     // the array dimensionality
1746     int dims;
1747
1748     // data reference counter
1749     int* refcount;
1750     // pointer to the data
1751     uchar* data;
1752     // and its actual beginning and end
1753     uchar* datastart;
1754     uchar* dataend;
1755
1756     // step and size for each dimension, MAX_DIM at max
1757     int size[MAX_DIM];
1758     size_t step[MAX_DIM];
1759 };
1760 \end{lstlisting}
1761
1762 The class \texttt{MatND} describes n-dimensional dense numerical single-channel or multi-channel array. This is a convenient representation for multi-dimensional histograms (when they are not very sparse, otherwise \texttt{SparseMat} will do better), voxel volumes, stacked motion fields etc. The data layout of matrix $M$ is defined by the array of \texttt{M.step[]}, so that the address of element $(i_0,...,i_{M.dims-1})$, where $0\leq i_k<M.size[k]$ is computed as:
1763 \[
1764 addr(M_{i_0,...,i_{M.dims-1}}) = M.data + M.step[0]*i_0 + M.step[1]*i_1 + ... + M.step[M.dims-1]*i_{M.dims-1}
1765 \]
1766 which is more general form of the respective formula for \cross{Mat}, wherein $\texttt{size[0]}\sim\texttt{rows}$,
1767 $\texttt{size[1]}\sim\texttt{cols}$, \texttt{step[0]} was simply called \texttt{step}, and \texttt{step[1]} was not stored at all but computed as \texttt{Mat::elemSize()}.
1768
1769 In other aspects \texttt{MatND} is also very similar to \texttt{Mat}, with the following limitations and differences:
1770 \begin{itemize}
1771     \item much less operations are implemented for \texttt{MatND}
1772     \item currently, algebraic expressions with \texttt{MatND}'s are not supported
1773     \item the \texttt{MatND} iterator is completely different from \texttt{Mat} and \texttt{Mat\_} iterators. The latter are per-element iterators, while the former is per-slice iterator, see below.
1774 \end{itemize}
1775
1776 Here is how you can use \texttt{MatND} to compute NxNxN histogram of color 8bpp image (i.e. each channel value ranges from 0..255 and we quantize it to 0..N-1):
1777
1778 \begin{lstlisting}
1779 void computeColorHist(const Mat& image, MatND& hist, int N)
1780 {
1781     const int histSize[] = {N, N, N};
1782
1783     // make sure that the histogram has proper size and type
1784     hist.create(3, histSize, CV_32F);
1785
1786     // and clear it
1787     hist = Scalar(0);
1788
1789     // the loop below assumes that the image
1790     // is 8-bit 3-channel, so let's check it.
1791     CV_Assert(image.type() == CV_8UC3);
1792     MatConstIterator_<Vec3b> it = image.begin<Vec3b>(),
1793                              it_end = image.end<Vec3b>();
1794     for( ; it != it_end; ++it )
1795     {
1796         const Vec3b& pix = *it;
1797
1798         // we could have incremented the cells by 1.f/(image.rows*image.cols)
1799         // instead of 1.f to make the histogram normalized.
1800         hist.at<float>(pix[0]*N/256, pix[1]*N/256, pix[2]*N/256) += 1.f;
1801     }
1802 }
1803 \end{lstlisting}
1804
1805 And here is how you can iterate through \texttt{MatND} elements:
1806
1807 \begin{lstlisting}
1808 void normalizeColorHist(MatND& hist)
1809 {
1810 #if 1
1811     // intialize iterator (the style is different from STL).
1812     // after initialization the iterator will contain
1813     // the number of slices or planes
1814     // the iterator will go through
1815     MatNDIterator it(hist);
1816     double s = 0;
1817     // iterate through the matrix. on each iteration
1818     // it.planes[*] (of type Mat) will be set to the current plane.
1819     for(int p = 0; p < it.nplanes; p++, ++it)
1820         s += sum(it.planes[0])[0];
1821     it = MatNDIterator(hist);
1822     s = 1./s;
1823     for(int p = 0; p < it.nplanes; p++, ++it)
1824         it.planes[0] *= s;
1825 #elif 1
1826     // this is a shorter implementation of the above
1827     // using built-in operations on MatND
1828     double s = sum(hist)[0];
1829     hist.convertTo(hist, hist.type(), 1./s, 0);
1830 #else
1831     // and this is even shorter one
1832     // (assuming that the histogram elements are non-negative)
1833     normalize(hist, hist, 1, 0, NORM_L1);
1834 #endif
1835 }
1836 \end{lstlisting}
1837
1838 You can iterate though several matrices simultaneously as long as they have the same geometry (dimensionality and all the dimension sizes are the same), which is useful for binary and n-ary operations on such matrices. Just pass those matrices to \texttt{MatNDIterator}. Then, during the iteration \texttt{it.planes[0]}, \texttt{it.planes[1]}, ... will be the slices of the corresponding matrices.
1839
1840 \subsection{MatND\_}
1841 Template class for n-dimensional dense array derived from \cross{MatND}.
1842
1843 \begin{lstlisting}
1844 template<typename _Tp> class MatND_ : public MatND
1845 {
1846 public:
1847     typedef _Tp value_type;
1848     typedef typename DataType<_Tp>::channel_type channel_type;
1849
1850     // constructors, the same as in MatND, only the type is omitted
1851     MatND_();
1852     MatND_(int dims, const int* _sizes);
1853     MatND_(int dims, const int* _sizes, const _Tp& _s);
1854     MatND_(const MatND& m);
1855     MatND_(const MatND_& m);
1856     MatND_(const MatND_& m, const Range* ranges);
1857     MatND_(const CvMatND* m, bool copyData=false);
1858     MatND_& operator = (const MatND& m);
1859     MatND_& operator = (const MatND_& m);
1860     // different initialization function
1861     // where we take _Tp instead of Scalar
1862     MatND_& operator = (const _Tp& s);
1863
1864     // no special destructor is needed; use the one from MatND
1865
1866     void create(int dims, const int* _sizes);
1867     template<typename T2> operator MatND_<T2>() const;
1868     MatND_ clone() const;
1869     MatND_ operator()(const Range* ranges) const;
1870
1871     size_t elemSize() const;
1872     size_t elemSize1() const;
1873     int type() const;
1874     int depth() const;
1875     int channels() const;
1876     // step[i]/elemSize()
1877     size_t stepT(int i) const;
1878     size_t step1(int i) const;
1879
1880     // shorter alternatives for MatND::at<_Tp>.
1881     _Tp& operator ()(const int* idx);
1882     const _Tp& operator ()(const int* idx) const;
1883     _Tp& operator ()(int idx0);
1884     const _Tp& operator ()(int idx0) const;
1885     _Tp& operator ()(int idx0, int idx1);
1886     const _Tp& operator ()(int idx0, int idx1) const;
1887     _Tp& operator ()(int idx0, int idx1, int idx2);
1888     const _Tp& operator ()(int idx0, int idx1, int idx2) const;
1889     _Tp& operator ()(int idx0, int idx1, int idx2);
1890     const _Tp& operator ()(int idx0, int idx1, int idx2) const;
1891 };
1892 \end{lstlisting}
1893
1894 \texttt{MatND\_} relates to \texttt{MatND}  almost like \texttt{Mat\_} to \texttt{Mat} - it provides a bit more convenient element access operations and adds no extra members of virtual methods to the base class, thus references/pointers to \texttt{MatND\_} and \texttt{MatND} can be easily converted one to another, e.g.
1895
1896 \begin{lstlisting}
1897 // alternative variant of the above histogram accumulation loop
1898 ...
1899 CV_Assert(hist.type() == CV_32FC1);
1900 MatND_<float>& _hist = (MatND_<float>&)hist;
1901 for( ; it != it_end; ++it )
1902 {
1903     const Vec3b& pix = *it;
1904     _hist(pix[0]*N/256, pix[1]*N/256, pix[2]*N/256) += 1.f;
1905 }
1906 ...
1907 \end{lstlisting}
1908
1909 \subsection{SparseMat}\label{SparseMat}
1910 Sparse n-dimensional array.
1911
1912 \begin{lstlisting}
1913 class SparseMat
1914 {
1915 public:
1916     typedef SparseMatIterator iterator;
1917     typedef SparseMatConstIterator const_iterator;
1918
1919     // internal structure - sparse matrix header
1920     struct Hdr
1921     {
1922         ...
1923     };
1924
1925     // sparse matrix node - element of a hash table
1926     struct Node
1927     {
1928         size_t hashval;
1929         size_t next;
1930         int idx[CV_MAX_DIM];
1931     };
1932
1933     ////////// constructors and destructor //////////
1934     // default constructor
1935     SparseMat();
1936     // creates matrix of the specified size and type
1937     SparseMat(int dims, const int* _sizes, int _type);
1938     // copy constructor
1939     SparseMat(const SparseMat& m);
1940     // converts dense 2d matrix to the sparse form,
1941     // if try1d is true and matrix is a single-column matrix (Nx1),
1942     // then the sparse matrix will be 1-dimensional.
1943     SparseMat(const Mat& m, bool try1d=false);
1944     // converts dense n-d matrix to the sparse form
1945     SparseMat(const MatND& m);
1946     // converts old-style sparse matrix to the new-style.
1947     // all the data is copied, so that "m" can be safely
1948     // deleted after the conversion
1949     SparseMat(const CvSparseMat* m);
1950     // destructor
1951     ~SparseMat();
1952
1953     ///////// assignment operations ///////////
1954
1955     // this is O(1) operation; no data is copied
1956     SparseMat& operator = (const SparseMat& m);
1957     // (equivalent to the corresponding constructor with try1d=false)
1958     SparseMat& operator = (const Mat& m);
1959     SparseMat& operator = (const MatND& m);
1960
1961     // creates full copy of the matrix
1962     SparseMat clone() const;
1963
1964     // copy all the data to the destination matrix.
1965     // the destination will be reallocated if needed.
1966     void copyTo( SparseMat& m ) const;
1967     // converts 1D or 2D sparse matrix to dense 2D matrix.
1968     // If the sparse matrix is 1D, then the result will
1969     // be a single-column matrix.
1970     void copyTo( Mat& m ) const;
1971     // converts arbitrary sparse matrix to dense matrix.
1972     // watch out the memory!
1973     void copyTo( MatND& m ) const;
1974     // multiplies all the matrix elements by the specified scalar
1975     void convertTo( SparseMat& m, int rtype, double alpha=1 ) const;
1976     // converts sparse matrix to dense matrix with optional type conversion and scaling.
1977     // When rtype=-1, the destination element type will be the same
1978     // as the sparse matrix element type.
1979     // Otherwise rtype will specify the depth and
1980     // the number of channels will remain the same is in the sparse matrix
1981     void convertTo( Mat& m, int rtype, double alpha=1, double beta=0 ) const;
1982     void convertTo( MatND& m, int rtype, double alpha=1, double beta=0 ) const;
1983
1984     // not used now
1985     void assignTo( SparseMat& m, int type=-1 ) const;
1986
1987     // reallocates sparse matrix. If it was already of the proper size and type,
1988     // it is simply cleared with clear(), otherwise,
1989     // the old matrix is released (using release()) and the new one is allocated.
1990     void create(int dims, const int* _sizes, int _type);
1991     // sets all the matrix elements to 0, which means clearing the hash table.
1992     void clear();
1993     // manually increases reference counter to the header.
1994     void addref();
1995     // decreses the header reference counter, when it reaches 0,
1996     // the header and all the underlying data are deallocated.
1997     void release();
1998
1999     // converts sparse matrix to the old-style representation.
2000     // all the elements are copied.
2001     operator CvSparseMat*() const;
2002     // size of each element in bytes
2003     // (the matrix nodes will be bigger because of
2004     //  element indices and other SparseMat::Node elements).
2005     size_t elemSize() const;
2006     // elemSize()/channels()
2007     size_t elemSize1() const;
2008
2009     // the same is in Mat and MatND
2010     int type() const;
2011     int depth() const;
2012     int channels() const;
2013
2014     // returns the array of sizes and 0 if the matrix is not allocated
2015     const int* size() const;
2016     // returns i-th size (or 0)
2017     int size(int i) const;
2018     // returns the matrix dimensionality
2019     int dims() const;
2020     // returns the number of non-zero elements
2021     size_t nzcount() const;
2022
2023     // compute element hash value from the element indices:
2024     // 1D case
2025     size_t hash(int i0) const;
2026     // 2D case
2027     size_t hash(int i0, int i1) const;
2028     // 3D case
2029     size_t hash(int i0, int i1, int i2) const;
2030     // n-D case
2031     size_t hash(const int* idx) const;
2032
2033     // low-level element-acccess functions,
2034     // special variants for 1D, 2D, 3D cases and the generic one for n-D case.
2035     //
2036     // return pointer to the matrix element.
2037     //  if the element is there (it's non-zero), the pointer to it is returned
2038     //  if it's not there and createMissing=false, NULL pointer is returned
2039     //  if it's not there and createMissing=true, then the new element
2040     //    is created and initialized with 0. Pointer to it is returned
2041     //  If the optional hashval pointer is not NULL, the element hash value is
2042     //  not computed, but *hashval is taken instead.
2043     uchar* ptr(int i0, bool createMissing, size_t* hashval=0);
2044     uchar* ptr(int i0, int i1, bool createMissing, size_t* hashval=0);
2045     uchar* ptr(int i0, int i1, int i2, bool createMissing, size_t* hashval=0);
2046     uchar* ptr(const int* idx, bool createMissing, size_t* hashval=0);
2047
2048     // higher-level element access functions:
2049     // ref<_Tp>(i0,...[,hashval]) - equivalent to *(_Tp*)ptr(i0,...true[,hashval]).
2050     //    always return valid reference to the element.
2051     //    If it's did not exist, it is created.
2052     // find<_Tp>(i0,...[,hashval]) - equivalent to (_const Tp*)ptr(i0,...false[,hashval]).
2053     //    return pointer to the element or NULL pointer if the element is not there.
2054     // value<_Tp>(i0,...[,hashval]) - equivalent to
2055     //    { const _Tp* p = find<_Tp>(i0,...[,hashval]); return p ? *p : _Tp(); }
2056     //    that is, 0 is returned when the element is not there.
2057     // note that _Tp must match the actual matrix type -
2058     // the functions do not do any on-fly type conversion
2059
2060     // 1D case
2061     template<typename _Tp> _Tp& ref(int i0, size_t* hashval=0);
2062     template<typename _Tp> _Tp value(int i0, size_t* hashval=0) const;
2063     template<typename _Tp> const _Tp* find(int i0, size_t* hashval=0) const;
2064
2065     // 2D case
2066     template<typename _Tp> _Tp& ref(int i0, int i1, size_t* hashval=0);
2067     template<typename _Tp> _Tp value(int i0, int i1, size_t* hashval=0) const;
2068     template<typename _Tp> const _Tp* find(int i0, int i1, size_t* hashval=0) const;
2069
2070     // 3D case
2071     template<typename _Tp> _Tp& ref(int i0, int i1, int i2, size_t* hashval=0);
2072     template<typename _Tp> _Tp value(int i0, int i1, int i2, size_t* hashval=0) const;
2073     template<typename _Tp> const _Tp* find(int i0, int i1, int i2, size_t* hashval=0) const;
2074
2075     // n-D case
2076     template<typename _Tp> _Tp& ref(const int* idx, size_t* hashval=0);
2077     template<typename _Tp> _Tp value(const int* idx, size_t* hashval=0) const;
2078     template<typename _Tp> const _Tp* find(const int* idx, size_t* hashval=0) const;
2079
2080     // erase the specified matrix element.
2081     // When there is no such element, the methods do nothing
2082     void erase(int i0, int i1, size_t* hashval=0);
2083     void erase(int i0, int i1, int i2, size_t* hashval=0);
2084     void erase(const int* idx, size_t* hashval=0);
2085
2086     // return the matrix iterators,
2087     //   pointing to the first sparse matrix element,
2088     SparseMatIterator begin();
2089     SparseMatConstIterator begin() const;
2090     //   ... or to the point after the last sparse matrix element
2091     SparseMatIterator end();
2092     SparseMatConstIterator end() const;
2093
2094     // and the template forms of the above methods.
2095     // _Tp must match the actual matrix type.
2096     template<typename _Tp> SparseMatIterator_<_Tp> begin();
2097     template<typename _Tp> SparseMatConstIterator_<_Tp> begin() const;
2098     template<typename _Tp> SparseMatIterator_<_Tp> end();
2099     template<typename _Tp> SparseMatConstIterator_<_Tp> end() const;
2100
2101     // return value stored in the sparse martix node
2102     template<typename _Tp> _Tp& value(Node* n);
2103     template<typename _Tp> const _Tp& value(const Node* n) const;
2104
2105     ////////////// some internal-use methods ///////////////
2106     ...
2107
2108     // pointer to the sparse matrix header
2109     Hdr* hdr;
2110 };
2111 \end{lstlisting}
2112
2113 The class \texttt{SparseMat} represents multi-dimensional sparse numerical arrays. Such a sparse array can store elements of any type that \cross{Mat} and \cross{MatND} can store. "Sparse" means that only non-zero elements are stored (though, as a result of operations on a sparse matrix, some of its stored elements can actually become 0. It's up to the user to detect such elements and delete them using \texttt{SparseMat::erase}). The non-zero elements are stored in a hash table that grows when it's filled enough, so that the search time is O(1) in average (regardless of whether element is there or not). Elements can be accessed using the following methods:
2114
2115 \begin{enumerate}
2116     \item query operations (\texttt{SparseMat::ptr} and the higher-level \texttt{SparseMat::ref}, \texttt{SparseMat::value} and \texttt{SparseMat::find}), e.g.:
2117     \begin{lstlisting}
2118     const int dims = 5;
2119     int size[] = {10, 10, 10, 10, 10};
2120     SparseMat sparse_mat(dims, size, CV_32F);
2121     for(int i = 0; i < 1000; i++)
2122     {
2123         int idx[dims];
2124         for(int k = 0; k < dims; k++)
2125             idx[k] = rand()%sparse_mat.size(k);
2126         sparse_mat.ref<float>(idx) += 1.f;
2127     }
2128     \end{lstlisting}
2129     \item sparse matrix iterators. Like \cross{Mat} iterators and unlike \cross{MatND} iterators, the sparse matrix iterators are STL-style, that is, the iteration loop is familiar to C++ users:
2130     \begin{lstlisting}
2131     // prints elements of a sparse floating-point matrix
2132     // and the sum of elements.
2133     SparseMatConstIterator_<float>
2134         it = sparse_mat.begin<float>(),
2135         it_end = sparse_mat.end<float>();
2136     double s = 0;
2137     int dims = sparse_mat.dims();
2138     for(; it != it_end; ++it)
2139     {
2140         // print element indices and the element value
2141         const Node* n = it.node();
2142         printf("(")
2143         for(int i = 0; i < dims; i++)
2144             printf("%3d%c", n->idx[i], i < dims-1 ? ',' : ')');
2145         printf(": %f\n", *it);
2146         s += *it;
2147     }
2148     printf("Element sum is %g\n", s);
2149     \end{lstlisting}
2150     If you run this loop, you will notice that elements are enumerated in no any logical order (lexicographical etc.), they come in the same order as they stored in the hash table, i.e. semi-randomly. You may collect pointers to the nodes and sort them to get the proper ordering. Note, however, that pointers to the nodes may become invalid when you add more elements to the matrix; this is because of possible buffer reallocation.
2151     \item a combination of the above 2 methods when you need to process 2 or more sparse matrices simultaneously, e.g. this is how you can compute unnormalized cross-correlation of the 2 floating-point sparse matrices:
2152     \begin{lstlisting}
2153     double cross_corr(const SparseMat& a, const SparseMat& b)
2154     {
2155         const SparseMat *_a = &a, *_b = &b;
2156         // if b contains less elements than a,
2157         // it's faster to iterate through b
2158         if(_a->nzcount() > _b->nzcount())
2159             std::swap(_a, _b);
2160         SparseMatConstIterator_<float> it = _a->begin<float>(),
2161                                        it_end = _a->end<float>();
2162         double ccorr = 0;
2163         for(; it != it_end; ++it)
2164         {
2165             // take the next element from the first matrix
2166             float avalue = *it;
2167             const Node* anode = it.node();
2168             // and try to find element with the same index in the second matrix.
2169             // since the hash value depends only on the element index,
2170             // we reuse hashvalue stored in the node
2171             float bvalue = _b->value<float>(anode->idx,&anode->hashval);
2172             ccorr += avalue*bvalue;
2173         }
2174         return ccorr;
2175     }
2176     \end{lstlisting}
2177 \end{enumerate}
2178
2179 \subsection{SparseMat\_}
2180 Template sparse n-dimensional array class derived from \cross{SparseMat}
2181
2182 \begin{lstlisting}
2183 template<typename _Tp> class SparseMat_ : public SparseMat
2184 {
2185 public:
2186     typedef SparseMatIterator_<_Tp> iterator;
2187     typedef SparseMatConstIterator_<_Tp> const_iterator;
2188
2189     // constructors;
2190     // the created matrix will have data type = DataType<_Tp>::type
2191     SparseMat_();
2192     SparseMat_(int dims, const int* _sizes);
2193     SparseMat_(const SparseMat& m);
2194     SparseMat_(const SparseMat_& m);
2195     SparseMat_(const Mat& m);
2196     SparseMat_(const MatND& m);
2197     SparseMat_(const CvSparseMat* m);
2198     // assignment operators; data type conversion is done when necessary
2199     SparseMat_& operator = (const SparseMat& m);
2200     SparseMat_& operator = (const SparseMat_& m);
2201     SparseMat_& operator = (const Mat& m);
2202     SparseMat_& operator = (const MatND& m);
2203
2204     // equivalent to the correspoding parent class methods
2205     SparseMat_ clone() const;
2206     void create(int dims, const int* _sizes);
2207     operator CvSparseMat*() const;
2208
2209     // overriden methods that do extra checks for the data type
2210     int type() const;
2211     int depth() const;
2212     int channels() const;
2213
2214     // more convenient element access operations.
2215     // ref() is retained (but <_Tp> specification is not need anymore);
2216     // operator () is equivalent to SparseMat::value<_Tp>
2217     _Tp& ref(int i0, size_t* hashval=0);
2218     _Tp operator()(int i0, size_t* hashval=0) const;
2219     _Tp& ref(int i0, int i1, size_t* hashval=0);
2220     _Tp operator()(int i0, int i1, size_t* hashval=0) const;
2221     _Tp& ref(int i0, int i1, int i2, size_t* hashval=0);
2222     _Tp operator()(int i0, int i1, int i2, size_t* hashval=0) const;
2223     _Tp& ref(const int* idx, size_t* hashval=0);
2224     _Tp operator()(const int* idx, size_t* hashval=0) const;
2225
2226     // iterators
2227     SparseMatIterator_<_Tp> begin();
2228     SparseMatConstIterator_<_Tp> begin() const;
2229     SparseMatIterator_<_Tp> end();
2230     SparseMatConstIterator_<_Tp> end() const;
2231 };
2232 \end{lstlisting}
2233
2234 \texttt{SparseMat\_} is a thin wrapper on top of \cross{SparseMat}, made in the same way as \texttt{Mat\_} and \texttt{MatND\_}.
2235 It simplifies notation of some operations, and that's it.
2236 \begin{lstlisting}
2237 int sz[] = {10, 20, 30};
2238 SparseMat_<double> M(3, sz);
2239 ...
2240 M.ref(1, 2, 3) = M(4, 5, 6) + M(7, 8, 9);
2241 \end{lstlisting}
2242 \fi