git.maemo.org Git - opencv/blob - docs/ref/opencvref_cxcore.htm

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0//EN">
   2 <html><head>
   3 <link rel="STYLESHEET" href="opencvref.css" charset="ISO-8859-1" type="text/css">
   4 <title>CXCORE Reference Manual</title>
   5 </head><body>
   6
   7 <h1>CXCORE Reference Manual</h1>
   8
   9 <hr><p><ul>
  10 <li><a href="#cxcore_basic_structures">Basic Structures</a>
  11 <li><a href="#cxcore_arrays">Operations on Arrays</a>
  12 <ul>
  13 <li><a href="#cxcore_arrays_alloc_free">Initialization</a>
  14 <li><a href="#cxcore_arrays_get_set">Accessing Elements and sub-Arrays</a>
  15 <li><a href="#cxcore_arrays_copying">Copying and Filling</a>
  16 <li><a href="#cxcore_arrays_permute">Transforms and Permutations</a>
  17 <li><a href="#cxcore_arrays_arithm_logic">Arithmetic, Logic and Comparison</a>
  18 <li><a href="#cxcore_arrays_stat">Statistics</a>
  19 <li><a href="#cxcore_arrays_matrix">Linear Algebra</a>
  20 <li><a href="#cxcore_arrays_math">Math Functions</a>
  21 <li><a href="#cxcore_arrays_rng">Random Number Generation</a>
  22 <li><a href="#cxcore_arrays_dxt">Discrete Transforms</a>
  23 </ul>
  24 <li><a href="#cxcore_ds">Dynamic Structures</a>
  25 <ul>
  26 <li><a href="#cxcore_ds_storages">Memory Storages</a>
  27 <li><a href="#cxcore_ds_sequences">Sequences</a>
  28 <li><a href="#cxcore_ds_sets">Sets</a>
  29 <li><a href="#cxcore_ds_graphs">Graphs</a>
  30 <li><a href="#cxcore_ds_trees">Trees</a>
  31 </ul>
  32 <li><a href="#cxcore_drawing">Drawing Functions</a>
  33 <ul>
  34 <li><a href="#cxcore_drawing_shapes">Curves and Shapes</a>
  35 <li><a href="#cxcore_drawing_text">Text</a>
  36 <li><a href="#cxcore_drawing_seq">Point Sets and Contours</a>
  37 </ul>
  38 <li><a href="#cxcore_persistence">Data Persistence and RTTI</a>
  39 <ul>
  40 <li><a href="#cxcore_persistence_ds">File Storage</a>
  41 <li><a href="#cxcore_persistence_writing">Writing Data</a>
  42 <li><a href="#cxcore_persistence_reading">Reading Data</a>
  43 <li><a href="#cxcore_persistence_rtti">RTTI and Generic Functions</a>
  44 </ul>
  45 <li><a href="#cxcore_misc">Miscellaneous Functions</a>
  46 <li><a href="#cxcore_system">Error Handling and System Functions</a>
  47 <ul>
  48 <li><a href="#cxcore_system_error">Error Handling</a>
  49 <li><a href="#cxcore_system_sys">System Functions</a>
  50 </ul>
  51 <li><a href="#cxcore_func_index">Alphabetical List of Functions</a>
  52 <li><a href="#cxcore_sample_index">List of Examples</a>
  53 </ul></p>
  54
  55
  56 <!-- *****************************************************************************************
  57      *****************************************************************************************
  58      ***************************************************************************************** -->
  59
  60 <hr><h1><a name="cxcore_basic_structures">Basic Structures</a></h1>
  61
  62 <hr><h3><a name="decl_CvPoint">CvPoint</a></h3>
  63 <p class="Blurb">2D point with integer coordinates</p>
  64 <pre>
  65     typedef struct CvPoint
  66     {
  67         int x; /* x-coordinate, usually zero-based */
  68         int y; /* y-coordinate, usually zero-based */
  69     }
  70     CvPoint;
  71
  72     /* the constructor function */
  73     inline CvPoint cvPoint( int x, int y );
  74
  75     /* conversion from CvPoint2D32f */
  76     inline CvPoint cvPointFrom32f( CvPoint2D32f point );
  77 </pre>
  78
  79 <hr><h3><a name="decl_CvPoint2D32f">CvPoint2D32f</a></h3>
  80 <p class="Blurb">2D point with floating-point coordinates</p>
  81 <pre>
  82     typedef struct CvPoint2D32f
  83     {
  84         float x; /* x-coordinate, usually zero-based */
  85         float y; /* y-coordinate, usually zero-based */
  86     }
  87     CvPoint2D32f;
  88
  89     /* the constructor function */
  90     inline CvPoint2D32f cvPoint2D32f( double x, double y );
  91
  92     /* conversion from CvPoint */
  93     inline CvPoint2D32f cvPointTo32f( CvPoint point );
  94 </pre>
  95
  96
  97 <hr><h3><a name="decl_CvPoint3D32f">CvPoint3D32f</a></h3>
  98 <p class="Blurb">3D point with floating-point coordinates</p>
  99 <pre>
 100     typedef struct CvPoint3D32f
 101     {
 102         float x; /* x-coordinate, usually zero-based */
 103         float y; /* y-coordinate, usually zero-based */
 104         float z; /* z-coordinate, usually zero-based */
 105     }
 106     CvPoint3D32f;
 107
 108     /* the constructor function */
 109     inline CvPoint3D32f cvPoint3D32f( double x, double y, double z );
 110 </pre>
 111
 112
 113 <hr><h3><a name="decl_CvPoint2D64f">CvPoint2D64f</a></h3>
 114 <p class="Blurb">2D point with double precision floating-point coordinates</p>
 115 <pre>
 116     typedef struct CvPoint2D64f
 117     {
 118         double x; /* x-coordinate, usually zero-based */
 119         double y; /* y-coordinate, usually zero-based */
 120     }
 121     CvPoint2D64f;
 122
 123     /* the constructor function */
 124     inline CvPoint2D64f cvPoint2D64f( double x, double y );
 125
 126     /* conversion from CvPoint */
 127     inline CvPoint2D64f cvPointTo64f( CvPoint point );
 128 </pre>
 129
 130
 131 <hr><h3><a name="decl_CvPoint3D64f">CvPoint3D64f</a></h3>
 132 <p class="Blurb">3D point with double precision floating-point coordinates</p>
 133 <pre>
 134     typedef struct CvPoint3D64f
 135     {
 136         double x; /* x-coordinate, usually zero-based */
 137         double y; /* y-coordinate, usually zero-based */
 138         double z; /* z-coordinate, usually zero-based */
 139     }
 140     CvPoint3D64f;
 141
 142     /* the constructor function */
 143     inline CvPoint3D64f cvPoint3D64f( double x, double y, double z );
 144 </pre>
 145
 146
 147 <hr><h3><a name="decl_CvSize">CvSize</a></h3>
 148 <p class="Blurb">pixel-accurate size of a rectangle</p>
 149 <pre>
 150     typedef struct CvSize
 151     {
 152         int width; /* width of the rectangle */
 153         int height; /* height of the rectangle */
 154     }
 155     CvSize;
 156
 157     /* the constructor function */
 158     inline CvSize cvSize( int width, int height );
 159 </pre>
 160
 161
 162 <hr><h3><a name="decl_CvSize2D32f">CvSize2D32f</a></h3>
 163 <p class="Blurb">sub-pixel accurate size of a rectangle</p>
 164 <pre>
 165     typedef struct CvSize2D32f
 166     {
 167         float width; /* width of the box */
 168         float height; /* height of the box */
 169     }
 170     CvSize2D32f;
 171
 172     /* the constructor function */
 173     inline CvSize2D32f cvSize2D32f( double width, double height );
 174 </pre>
 175
 176
 177 <hr><h3><a name="decl_CvRect">CvRect</a></h3>
 178 <p class="Blurb">offset and size of a rectangle</p>
 179 <pre>
 180     typedef struct CvRect
 181     {
 182         int x; /* x-coordinate of the left-most rectangle corner[s] */
 183         int y; /* y-coordinate of the top-most or bottom-most
 184                   rectangle corner[s] */
 185         int width; /* width of the rectangle */
 186         int height; /* height of the rectangle */
 187     }
 188     CvRect;
 189
 190     /* the constructor function */
 191     inline CvRect cvRect( int x, int y, int width, int height );
 192 </pre>
 193
 194
 195 <hr><h3><a name="decl_CvScalar">CvScalar</a></h3>
 196 <p class="Blurb">A container for 1-,2-,3- or 4-tuples of numbers</p>
 197 <pre>
 198     typedef struct CvScalar
 199     {
 200         double val[4];
 201     }
 202     CvScalar;
 203
 204     /* the constructor function: initializes val[0] with val0, val[1] with val1 etc. */
 205     inline CvScalar cvScalar( double val0, double val1=0,
 206                               double val2=0, double val3=0 );
 207     /* the constructor function: initializes val[0]...val[3] with val0123 */
 208     inline CvScalar cvScalarAll( double val0123 );
 209
 210     /* the constructor function: initializes val[0] with val0, val[1]...val[3] with zeros */
 211     inline CvScalar cvRealScalar( double val0 );
 212 </pre>
 213
 214
 215 <hr><h3><a name="decl_CvTermCriteria">CvTermCriteria</a></h3>
 216 <p class="Blurb">Termination criteria for iterative algorithms</p>
 217 <pre>
 218 #define CV_TERMCRIT_ITER    1
 219 #define CV_TERMCRIT_NUMBER  CV_TERMCRIT_ITER
 220 #define CV_TERMCRIT_EPS     2
 221
 222 typedef struct CvTermCriteria
 223 {
 224     int    type;  /* a combination of CV_TERMCRIT_ITER and CV_TERMCRIT_EPS */
 225     int    max_iter; /* maximum number of iterations */
 226     double epsilon; /* accuracy to achieve */
 227 }
 228 CvTermCriteria;
 229
 230 /* the constructor function */
 231 inline  CvTermCriteria  cvTermCriteria( int type, int max_iter, double epsilon );
 232
 233 /* check termination criteria and transform it so that type=CV_TERMCRIT_ITER+CV_TERMCRIT_EPS,
 234    and both max_iter and epsilon are valid */
 235 CvTermCriteria cvCheckTermCriteria( CvTermCriteria criteria,
 236                                     double default_eps,
 237                                     int default_max_iters );
 238 </pre>
 239
 240
 241 <!-- *****************************************************************************************
 242      *****************************************************************************************
 243      ***************************************************************************************** -->
 244
 245 <!-- <hr><h2><a name="ch1_array_structs">Array structures</a></h2> -->
 246
 247 <hr><h3><a name="decl_CvMat">CvMat</a></h3>
 248 <p class="Blurb">Multi-channel matrix</p>
 249 <pre>
 250     typedef struct CvMat
 251     {
 252         int type; /* CvMat signature (CV_MAT_MAGIC_VAL), element type and flags */
 253         int step; /* full row length in bytes */
 254
 255         int* refcount; /* underlying data reference counter */
 256
 257         union
 258         {
 259             uchar* ptr;
 260             short* s;
 261             int* i;
 262             float* fl;
 263             double* db;
 264         } data; /* data pointers */
 265
 266     #ifdef __cplusplus
 267         union
 268         {
 269             int rows;
 270             int height;
 271         };
 272
 273         union
 274         {
 275             int cols;
 276             int width;
 277         };
 278     #else
 279         int rows; /* number of rows */
 280         int cols; /* number of columns */
 281     #endif
 282
 283     } CvMat;
 284 </pre>
 285
 286
 287 <hr><h3><a name="decl_CvMatND">CvMatND</a></h3>
 288 <p class="Blurb">Multi-dimensional dense multi-channel array</p>
 289 <pre>
 290     typedef struct CvMatND
 291     {
 292         int type; /* CvMatND signature (CV_MATND_MAGIC_VAL), element type and flags */
 293         int dims; /* number of array dimensions */
 294
 295         int* refcount; /* underlying data reference counter */
 296
 297         union
 298         {
 299             uchar* ptr;
 300             short* s;
 301             int* i;
 302             float* fl;
 303             double* db;
 304         } data; /* data pointers */
 305
 306         /* pairs (number of elements, distance between elements in bytes) for
 307            every dimension */
 308         struct
 309         {
 310             int size;
 311             int step;
 312         }
 313         dim[CV_MAX_DIM];
 314
 315     } CvMatND;
 316 </pre>
 317
 318
 319 <hr><h3><a name="decl_CvSparseMat">CvSparseMat</a></h3>
 320 <p class="Blurb">Multi-dimensional sparse multi-channel array</p>
 321 <pre>
 322     typedef struct CvSparseMat
 323     {
 324         int type; /* CvSparseMat signature (CV_SPARSE_MAT_MAGIC_VAL), element type and flags */
 325         int dims; /* number of dimensions */
 326         int* refcount; /* reference counter - not used */
 327         struct CvSet* heap; /* a pool of hashtable nodes */
 328         void** hashtable; /* hashtable: each entry has a list of nodes
 329                              having the same "hashvalue modulo hashsize" */
 330         int hashsize; /* size of hashtable */
 331         int total; /* total number of sparse array nodes */
 332         int valoffset; /* value offset in bytes for the array nodes */
 333         int idxoffset; /* index offset in bytes for the array nodes */
 334         int size[CV_MAX_DIM]; /* arr of dimension sizes */
 335
 336     } CvSparseMat;
 337 </pre>
 338
 339
 340 <hr><h3><a name="decl_IplImage">IplImage</a></h3>
 341 <p class="Blurb">IPL image header</p>
 342 <pre>
 343     typedef struct _IplImage
 344     {
 345         int  nSize;         /* sizeof(IplImage) */
 346         int  ID;            /* version (=0)*/
 347         int  nChannels;     /* Most of OpenCV functions support 1,2,3 or 4 channels */
 348         int  alphaChannel;  /* ignored by OpenCV */
 349         int  depth;         /* pixel depth in bits: IPL_DEPTH_8U, IPL_DEPTH_8S, IPL_DEPTH_16U,
 350                                IPL_DEPTH_16S, IPL_DEPTH_32S, IPL_DEPTH_32F and IPL_DEPTH_64F are supported */
 351         char colorModel[4]; /* ignored by OpenCV */
 352         char channelSeq[4]; /* ditto */
 353         int  dataOrder;     /* 0 - interleaved color channels, 1 - separate color channels.
 354                                cvCreateImage can only create interleaved images */
 355         int  origin;        /* 0 - top-left origin,
 356                                1 - bottom-left origin (Windows bitmaps style) */
 357         int  align;         /* Alignment of image rows (4 or 8).
 358                                OpenCV ignores it and uses widthStep instead */
 359         int  width;         /* image width in pixels */
 360         int  height;        /* image height in pixels */
 361         struct _IplROI *roi;/* image ROI. when it is not NULL, this specifies image region to process */
 362         struct _IplImage *maskROI; /* must be NULL in OpenCV */
 363         void  *imageId;     /* ditto */
 364         struct _IplTileInfo *tileInfo; /* ditto */
 365         int  imageSize;     /* image data size in bytes
 366                                (=image->height*image->widthStep
 367                                in case of interleaved data)*/
 368         char *imageData;  /* pointer to aligned image data */
 369         int  widthStep;   /* size of aligned image row in bytes */
 370         int  BorderMode[4]; /* border completion mode, ignored by OpenCV */
 371         int  BorderConst[4]; /* ditto */
 372         char *imageDataOrigin; /* pointer to a very origin of image data
 373                                   (not necessarily aligned) -
 374                                   it is needed for correct image deallocation */
 375     }
 376     IplImage;
 377 </pre>
 378 <p>
 379 The structure <code>IplImage</code> came from <em>Intel Image Processing Library</em> where
 380 the format is native. OpenCV supports only a subset of possible <code>IplImage</code> formats:
 381 <ul>
 382 <li><code>alphaChannel</code> is ignored by OpenCV.
 383 <li><code>colorModel</code> and <code>channelSeq</code> are ignored by OpenCV. The single OpenCV function
 384 <a href="#decl_cvCvtColor">cvCvtColor</a> working with color spaces takes the source and destination color spaces
 385 as a parameter.
 386 <li><code>dataOrder</code> must be IPL_DATA_ORDER_PIXEL (the color channels are interleaved), however
 387 selected channels of planar images can be processed as well if COI is set.
 388 <li><code>align</code> is ignored by OpenCV, while <code>widthStep</code> is used to access to subsequent image rows.
 389 <li><code>maskROI</code> is not supported. The function that can work with mask take it as a
 390 separate parameter. Also the mask in OpenCV is 8-bit, whereas in IPL it is 1-bit.
 391 <li><code>tileInfo</code> is not supported.
 392 <li><code>BorderMode</code> and <code>BorderConst</code> are not supported. Every OpenCV function
 393 working with a pixel neighborhood uses a single hard-coded border mode (most often, replication).
 394 </ul>
 395 Besides the above restrictions, OpenCV handles ROI differently. It requires that the sizes or ROI sizes of
 396 all source and destination images match exactly (according to the operation, e.g. for <a href="#decl_cvPyrDown">cvPyrDown</a>
 397 destination width(height) must be equal to source width(height) divided by 2 &plusmn;1),
 398 whereas IPL processes the intersection area - that is, the sizes or ROI sizes of all images may
 399 vary independently.
 400 </p>
 401
 402
 403 <hr><h3><a name="decl_CvArr">CvArr</a></h3>
 404 <p class="Blurb">Arbitrary array</p>
 405 <pre>
 406     typedef void CvArr;
 407 </pre>
 408 <p>
 409 The metatype <code>CvArr*</code> is used <em>only</em> as a function parameter to
 410 specify that the function accepts arrays of more than a
 411 single type, for example IplImage*, CvMat* or even CvSeq*. The particular array
 412 type is determined at runtime by analysing the first 4 bytes of the header.
 413 </p>
 414
 415 <!-- *****************************************************************************************
 416      *****************************************************************************************
 417      ***************************************************************************************** -->
 418
 419 <hr><h1><a name="cxcore_arrays">Operations on Arrays</a></h1>
 420 <hr><h2><a name="cxcore_arrays_alloc_free">Initialization</a></h2>
 421
 422 <hr><h3><a name="decl_cvCreateImage">CreateImage</a></h3>
 423 <p class="Blurb">Creates header and allocates data</p>
 424 <pre>
 425 IplImage* cvCreateImage( CvSize size, int depth, int channels );
 426 </pre><p><dl>
 427 <dt>size<dd>Image width and height.
 428 <dt>depth<dd>Bit depth of image elements. Can be one of:<br>
 429              IPL_DEPTH_8U - unsigned 8-bit integers<br>
 430              IPL_DEPTH_8S - signed 8-bit integers<br>
 431              IPL_DEPTH_16U - unsigned 16-bit integers<br>
 432              IPL_DEPTH_16S - signed 16-bit integers<br>
 433              IPL_DEPTH_32S - signed 32-bit integers<br>
 434              IPL_DEPTH_32F - single precision floating-point numbers<br>
 435              IPL_DEPTH_64F - double precision floating-point numbers<br>
 436 <dt>channels<dd>Number of channels per element(pixel). Can be 1, 2, 3 or 4.
 437              The channels are interleaved, for example the
 438              usual data layout of a color image is:<br>
 439              b0 g0 r0 b1 g1 r1 ...<br>
 440              Although in general IPL image format can store
 441              non-interleaved images as well and some of OpenCV
 442              can process it, this function can create interleaved images
 443              only.
 444 </dl><p>
 445 The function <code>cvCreateImage</code> creates the header and allocates data. This call is a
 446 shortened form of
 447 <pre>
 448     header = cvCreateImageHeader(size,depth,channels);
 449     cvCreateData(header);
 450 </pre>
 451 </p>
 452
 453
 454 <hr><h3><a name="decl_cvCreateImageHeader">CreateImageHeader</a></h3>
 455 <p class="Blurb">Allocates, initializes, and returns structure IplImage</p>
 456 <pre>
 457 IplImage* cvCreateImageHeader( CvSize size, int depth, int channels );
 458 </pre><p><dl>
 459 <dt>size<dd>Image width and height.
 460 <dt>depth<dd>Image depth (see CreateImage).
 461 <dt>channels<dd>Number of channels (see CreateImage).
 462 </dl><p>
 463 The function <code>cvCreateImageHeader</code> allocates, initializes, and returns the structure
 464 <code>IplImage</code>. This call is an analogue of
 465 <pre>
 466   iplCreateImageHeader( channels, 0, depth,
 467                         channels == 1 ? "GRAY" : "RGB",
 468                         channels == 1 ? "GRAY" : channels == 3 ? "BGR" :
 469                         channels == 4 ? "BGRA" : "",
 470                         IPL_DATA_ORDER_PIXEL, IPL_ORIGIN_TL, 4,
 471                         size.width, size.height,
 472                         0,0,0,0);
 473 </pre>
 474 though it does not use IPL functions by default
 475 (see also <code>CV_TURN_ON_IPL_COMPATIBILITY</code> macro)
 476 </p>
 477
 478
 479 <hr><h3><a name="decl_cvReleaseImageHeader">ReleaseImageHeader</a></h3>
 480 <p class="Blurb">Releases header</p>
 481 <pre>
 482 void cvReleaseImageHeader( IplImage** image );
 483 </pre><p><dl>
 484 <dt>image<dd>Double pointer to the deallocated header.
 485 </dl><p>
 486 The function <code>cvReleaseImageHeader</code> releases the header.
 487 This call is an analogue of
 488 <pre>
 489     if( image )
 490     {
 491         iplDeallocate( *image, IPL_IMAGE_HEADER | IPL_IMAGE_ROI );
 492         *image = 0;
 493     }
 494 </pre>
 495 though it does not use IPL functions by default
 496 (see also <code>CV_TURN_ON_IPL_COMPATIBILITY</code>)
 497 </p>
 498
 499
 500 <hr><h3><a name="decl_cvReleaseImage">ReleaseImage</a></h3>
 501 <p class="Blurb">Releases header and image data</p>
 502 <pre>
 503 void cvReleaseImage( IplImage** image );
 504 </pre><p><dl>
 505 <dt>image<dd>Double pointer to the header of the deallocated image.
 506 </dl></p><p>
 507 The function <code>cvReleaseImage</code> releases the header and the image data. This call is a
 508 shortened form of
 509 <pre>
 510     if( *image )
 511     {
 512         cvReleaseData( *image );
 513         cvReleaseImageHeader( image );
 514     }
 515 </pre>
 516 </p>
 517
 518
 519 <hr><h3><a name="decl_cvInitImageHeader">InitImageHeader</a></h3>
 520 <p class="Blurb">Initializes allocated by user image header</p>
 521 <pre>
 522 IplImage* cvInitImageHeader( IplImage* image, CvSize size, int depth,
 523                              int channels, int origin=0, int align=4 );
 524 </pre><p><dl>
 525 <dt>image<dd>Image header to initialise.
 526 <dt>size<dd>Image width and height.
 527 <dt>depth<dd>Image depth (see CreateImage).
 528 <dt>channels<dd>Number of channels (see CreateImage).
 529 <dt>origin<dd><code>IPL_ORIGIN_TL</code> or <code>IPL_ORIGIN_BL</code>.
 530 <dt>align<dd>Alignment for image rows, typically 4 or 8 bytes.
 531 </dl></p><p>
 532 The function <code>cvInitImageHeader</code> initializes the image header structure,
 533 pointer to which is passed by the user, and returns the pointer.
 534 </p>
 535
 536
 537 <hr><h3><a name="decl_cvCloneImage">CloneImage</a></h3>
 538 <p class="Blurb">Makes a full copy of image</p>
 539 <pre>
 540 IplImage* cvCloneImage( const IplImage* image );
 541 </pre><p><dl>
 542 <dt>image<dd>Original image.
 543 </dl></p><p>
 544 The function <code>cvCloneImage</code> makes a full copy of the image including
 545 header, ROI and data
 546 </p>
 547
 548
 549 <hr><h3><a name="decl_cvSetImageCOI">SetImageCOI</a></h3>
 550 <p class="Blurb">Sets channel of interest to given value</p>
 551 <pre>
 552 void cvSetImageCOI( IplImage* image, int coi );
 553 </pre><p><dl>
 554 <dt>image<dd>Image header.
 555 <dt>coi<dd>Channel of interest.
 556 </dl><p>
 557 The function <code>cvSetImageCOI</code> sets the channel of interest
 558 to a given value. Value 0 means that all channels are selected,
 559 1 means that the first channel is selected etc.
 560 If ROI is <code>NULL</code> and <code>coi != 0</code>, ROI is allocated.
 561 Note that most of OpenCV functions do not support COI, so
 562 to process separate image/matrix channel one may copy (via <a href="#decl_cvCopy">cvCopy</a> or
 563 <a href="#decl_cvSplit">cvSplit</a>) the channel to separate image/matrix,
 564 process it and copy the result back (via <a href="#decl_cvCopy">cvCopy</a> or <a href="#decl_cvCvtPlaneToPix">cvCvtPlaneToPix</a>)
 565 if need.</p>
 566
 567
 568 <hr><h3><a name="decl_cvGetImageCOI">GetImageCOI</a></h3>
 569 <p class="Blurb">Returns index of channel of interest</p>
 570 <pre>
 571 int cvGetImageCOI( const IplImage* image );
 572 </pre><p><dl>
 573 <dt>image<dd>Image header.
 574 </dl><p>
 575 The function <code>cvGetImageCOI</code> returns channel of interest of
 576 the image (it returns 0 if all the channels are selected).</p>
 577
 578
 579 <hr><h3><a name="decl_cvSetImageROI">SetImageROI</a></h3>
 580 <p class="Blurb">Sets image ROI to given rectangle</p>
 581 <pre>
 582 void cvSetImageROI( IplImage* image, CvRect rect );
 583 </pre><p><dl>
 584 <dt>image<dd>Image header.
 585 <dt>rect<dd>ROI rectangle.
 586 </dl><p>
 587 The function <code>cvSetImageROI</code> sets the image ROI to a given rectangle. If ROI is <code>NULL</code>
 588 and the value of the parameter <code>rect</code> is not equal to the whole image, ROI is
 589 allocated. Unlike COI, most of OpenCV functions do support ROI and treat
 590 it in a way as it would be a separate image (for example, all the pixel
 591 coordinates are counted from top-left or bottom-left
 592 (depending on the image origin) corner of ROI)</p>
 593
 594
 595 <hr><h3><a name="decl_cvResetImageROI">ResetImageROI</a></h3>
 596 <p class="Blurb">Releases image ROI</p>
 597 <pre>
 598 void cvResetImageROI( IplImage* image );
 599 </pre><p><dl>
 600 <dt>image<dd>Image header.
 601 </dl><p>
 602 The function <code>cvResetImageROI</code> releases image ROI. After that the whole image
 603 is considered selected. The similar result can be achieved by</p>
 604 <pre>
 605 cvSetImageROI( image, cvRect( 0, 0, image->width, image->height ));
 606 cvSetImageCOI( image, 0 );
 607 </pre>
 608 <p>
 609 But the latter variant does not deallocate <code>image->roi</code>.
 610 </p>
 611
 612
 613 <hr><h3><a name="decl_cvGetImageROI">GetImageROI</a></h3>
 614 <p class="Blurb">Returns image ROI coordinates</p>
 615 <pre>
 616 CvRect cvGetImageROI( const IplImage* image );
 617 </pre><p><dl>
 618 <dt>image<dd>Image header.
 619 </dl><p>
 620 The function <code>cvGetImageROI</code> returns image ROI coordinates.
 621 The rectangle <a href="#decl_cvRect">cvRect</a>(0,0,image->width,image->height) is returned if
 622 there is no ROI</p>
 623
 624
 625 <hr><h3><a name="decl_cvCreateMat">CreateMat</a></h3>
 626 <p class="Blurb">Creates new matrix</p>
 627 <pre>
 628 CvMat* cvCreateMat( int rows, int cols, int type );
 629 </pre><p><dl>
 630 <dt>rows<dd>Number of rows in the matrix.
 631 <dt>cols<dd>Number of columns in the matrix.
 632 <dt>type<dd>Type of the matrix elements.
 633             Usually it is specified in form
 634             <code>CV_&lt;bit_depth&gt;(S|U|F)C&lt;number_of_channels&gt;</code>, for example:<br>
 635             <code>CV_8UC1</code> means an 8-bit unsigned single-channel matrix,
 636             <code>CV_32SC2</code> means a 32-bit signed matrix with two channels.
 637 </dl><p>
 638 The function <code>cvCreateMat</code> allocates header for the new matrix and underlying data,
 639 and returns a pointer to the created matrix. It is a short form for:</p>
 640 <pre>
 641     CvMat* mat = cvCreateMatHeader( rows, cols, type );
 642     cvCreateData( mat );
 643 </pre><p>
 644 Matrices are stored row by row. All the rows are aligned by 4 bytes.
 645 </p>
 646
 647
 648 <hr><h3><a name="decl_cvCreateMatHeader">CreateMatHeader</a></h3>
 649 <p class="Blurb">Creates new matrix header</p>
 650 <pre>
 651 CvMat* cvCreateMatHeader( int rows, int cols, int type );
 652 </pre><p><dl>
 653 <dt>rows<dd>Number of rows in the matrix.
 654 <dt>cols<dd>Number of columns in the matrix.
 655 <dt>type<dd>Type of the matrix elements (see <a href="#decl_cvCreateMat">cvCreateMat</a>).
 656 </dl><p>
 657 The function <code>cvCreateMatHeader</code> allocates new matrix header and returns pointer to
 658 it. The matrix data can further be allocated using <a href="#decl_cvCreateData">cvCreateData</a> or set
 659 explicitly to user-allocated data via <a href="#decl_cvSetData">cvSetData</a>.
 660 </p>
 661
 662
 663 <hr><h3><a name="decl_cvReleaseMat">ReleaseMat</a></h3>
 664 <p class="Blurb">Deallocates matrix</p>
 665 <pre>
 666 void cvReleaseMat( CvMat** mat );
 667 </pre><p><dl>
 668 <dt>mat<dd>Double pointer to the matrix.
 669 </dl><p>
 670 The function <code>cvReleaseMat</code> decrements the matrix data reference counter and
 671 releases matrix header:</p>
 672 <pre>
 673     if( *mat )
 674         cvDecRefData( *mat );
 675     cvFree( (void**)mat );
 676 </pre>
 677 </p>
 678
 679
 680 <hr><h3><a name="decl_cvInitMatHeader">InitMatHeader</a></h3>
 681 <p class="Blurb">Initializes matrix header</p>
 682 <pre>
 683 CvMat* cvInitMatHeader( CvMat* mat, int rows, int cols, int type,
 684                         void* data=NULL, int step=CV_AUTOSTEP );
 685 </pre><p><dl>
 686 <dt>mat<dd>Pointer to the matrix header to be initialised.
 687 <dt>rows<dd>Number of rows in the matrix.
 688 <dt>cols<dd>Number of columns in the matrix.
 689 <dt>type<dd>Type of the matrix elements.
 690 <dt>data<dd>Optional data pointer assigned to the matrix header.
 691 <dt>step<dd>Full row width in bytes of the data assigned. By default, the minimal
 692 possible step is used, i.e., no gaps is assumed between subsequent rows of the
 693 matrix.
 694 </dl><p>
 695 The function <code>cvInitMatHeader</code> initializes already allocated <a href="#decl_CvMat">CvMat</a> structure. It can
 696 be used to process raw data with OpenCV matrix functions.
 697 <p>
 698 For example, the following code computes matrix product of two matrices, stored
 699 as ordinary arrays.
 700 </p>
 701 </p><p>
 702 <font color=blue size=4>Calculating Product of Two Matrices</font></p>
 703 <pre>
 704    double a[] = { 1, 2, 3, 4
 705                   5, 6, 7, 8,
 706                   9, 10, 11, 12 };
 707
 708    double b[] = { 1, 5, 9,
 709                   2, 6, 10,
 710                   3, 7, 11,
 711                   4, 8, 12 };
 712
 713    double c[9];
 714    CvMat Ma, Mb, Mc ;
 715
 716    cvInitMatHeader( &amp;Ma, 3, 4, CV_64FC1, a );
 717    cvInitMatHeader( &amp;Mb, 4, 3, CV_64FC1, b );
 718    cvInitMatHeader( &amp;Mc, 3, 3, CV_64FC1, c );
 719
 720    cvMatMulAdd( &amp;Ma, &amp;Mb, 0, &amp;Mc );
 721    // c array now contains product of a(3x4) and b(4x3) matrices
 722 </pre></p>
 723
 724
 725 <hr><h3><a name="decl_cvMat">Mat</a></h3>
 726 <p class="Blurb">Initializes matrix header (light-weight variant)</p>
 727 <pre>
 728 CvMat cvMat( int rows, int cols, int type, void* data=NULL );
 729 </pre><p><dl>
 730 <dt>rows<dd>Number of rows in the matrix.
 731 <dt>cols<dd>Number of columns in the matrix.
 732 <dt>type<dd>Type of the matrix elements (see CreateMat).
 733 <dt>data<dd>Optional data pointer assigned to the matrix header.
 734 </dl><p>
 735 The function <code>cvMat</code> is a fast inline substitution for <a href="#decl_cvInitMatHeader">cvInitMatHeader</a>.
 736 Namely, it is equivalent to:
 737 <pre>
 738      CvMat mat;
 739      cvInitMatHeader( &amp;mat, rows, cols, type, data, CV_AUTOSTEP );
 740 </pre>
 741 </p>
 742
 743
 744 <hr><h3><a name="decl_cvCloneMat">CloneMat</a></h3>
 745 <p class="Blurb">Creates matrix copy</p>
 746 <pre>
 747 CvMat* cvCloneMat( const CvMat* mat );
 748 </pre><p><dl>
 749 <dt>mat<dd>Input matrix.
 750 </dl><p>
 751 The function <code>cvCloneMat</code> creates a copy of input matrix and returns the pointer to
 752 it.
 753 </p>
 754
 755
 756 <hr><h3><a name="decl_cvCreateMatND">CreateMatND</a></h3>
 757 <p class="Blurb">Creates multi-dimensional dense array</p>
 758 <pre>
 759 CvMatND* cvCreateMatND( int dims, const int* sizes, int type );
 760 </pre><p><dl>
 761 <dt>dims<dd>Number of array dimensions. It must not exceed CV_MAX_DIM (=32 by default,
 762             though it may be changed at build time)
 763 <dt>sizes<dd>Array of dimension sizes.
 764 <dt>type<dd>Type of array elements. The same as for <a href="#decl_CvMat">CvMat</a>
 765 </dl><p>
 766 The function <code>cvCreateMatND</code> allocates header for multi-dimensional dense array
 767 and the underlying data, and returns pointer to the created array. It is a short form for:</p>
 768 <pre>
 769     CvMatND* mat = cvCreateMatNDHeader( dims, sizes, type );
 770     cvCreateData( mat );
 771 </pre><p>
 772 Array data is stored row by row. All the rows are aligned by 4 bytes.
 773 </p>
 774
 775
 776 <hr><h3><a name="decl_cvCreateMatNDHeader">CreateMatNDHeader</a></h3>
 777 <p class="Blurb">Creates new matrix header</p>
 778 <pre>
 779 CvMatND* cvCreateMatNDHeader( int dims, const int* sizes, int type );
 780 </pre><p><dl>
 781 <dt>dims<dd>Number of array dimensions.
 782 <dt>sizes<dd>Array of dimension sizes.
 783 <dt>type<dd>Type of array elements. The same as for CvMat
 784 </dl><p>
 785 The function <code>cvCreateMatND</code> allocates header for multi-dimensional dense array.
 786 The array data can further be allocated using <a href="#decl_cvCreateData">cvCreateData</a> or set
 787 explicitly to user-allocated data via <a href="#decl_cvSetData">cvSetData</a>.
 788 </p>
 789
 790
 791 <hr><h3><a name="decl_cvReleaseMatND">ReleaseMatND</a></h3>
 792 <p class="Blurb">Deallocates multi-dimensional array</p>
 793 <pre>
 794 void cvReleaseMatND( CvMatND** mat );
 795 </pre><p><dl>
 796 <dt>mat<dd>Double pointer to the array.
 797 </dl><p>
 798 The function <code>cvReleaseMatND</code> decrements the array data reference counter and
 799 releases the array header:</p>
 800 <pre>
 801     if( *mat )
 802         cvDecRefData( *mat );
 803     cvFree( (void**)mat );
 804 </pre>
 805 </p>
 806
 807
 808 <hr><h3><a name="decl_cvInitMatNDHeader">InitMatNDHeader</a></h3>
 809 <p class="Blurb">Initializes multi-dimensional array header</p>
 810 <pre>
 811 CvMatND* cvInitMatNDHeader( CvMatND* mat, int dims, const int* sizes, int type, void* data=NULL );
 812 </pre><p><dl>
 813 <dt>mat<dd>Pointer to the array header to be initialized.
 814 <dt>dims<dd>Number of array dimensions.
 815 <dt>sizes<dd>Array of dimension sizes.
 816 <dt>type<dd>Type of array elements. The same as for CvMat
 817 <dt>data<dd>Optional data pointer assigned to the matrix header.
 818 </dl><p>
 819 The function <code>cvInitMatNDHeader</code> initializes <a href="#decl_CvMatND">CvMatND</a> structure allocated by
 820 the user.
 821 </p>
 822
 823
 824 <hr><h3><a name="decl_cvCloneMatND">CloneMatND</a></h3>
 825 <p class="Blurb">Creates full copy of multi-dimensional array</p>
 826 <pre>
 827 CvMatND* cvCloneMatND( const CvMatND* mat );
 828 </pre><p><dl>
 829 <dt>mat<dd>Input array.
 830 </dl><p>
 831 The function <code>cvCloneMatND</code> creates a copy of input array and returns pointer to
 832 it.
 833 </p>
 834
 835
 836 <hr><h3><a name="decl_cvDecRefData">DecRefData</a></h3>
 837 <p class="Blurb">Decrements array data reference counter</p>
 838 <pre>
 839 void cvDecRefData( CvArr* arr );
 840 </pre><p><dl>
 841 <dt>arr<dd>array header.
 842 </dl><p>
 843 The function <code>cvDecRefData</code> decrements <a href="#decl_CvMat">CvMat</a> or <a href="#decl_CvMatND">CvMatND</a> data reference counter if the
 844 reference counter pointer is not NULL and deallocates the data if the counter reaches zero.
 845 In the current implementation the reference counter is not NULL only if the data was allocated using
 846 <a href="#decl_cvCreateData">cvCreateData</a> function, in other cases such as:<br>
 847 external data was assigned to the header using <a href="#decl_cvSetData">cvSetData</a><br>
 848 the matrix header presents a part of a larger matrix or image<br>
 849 the matrix header was converted from image or n-dimensional matrix header<br>
 850 <br>
 851 the reference counter is set to NULL and thus it is not decremented.
 852 Whenever the data is deallocated or not,
 853 the data pointer and reference counter pointers are cleared by the function.
 854 </p>
 855
 856
 857 <hr><h3><a name="decl_cvIncRefData">IncRefData</a></h3>
 858 <p class="Blurb">Increments array data reference counter</p>
 859 <pre>
 860 int cvIncRefData( CvArr* arr );
 861 </pre><p><dl>
 862 <dt>arr<dd>array header.
 863 </dl><p>
 864 The function <code>cvIncRefData</code> increments <a href="#decl_CvMat">CvMat</a> or <a href="#decl_CvMatND">CvMatND</a> data reference counter and
 865 returns the new counter value if the reference counter pointer is not NULL, otherwise it returns zero.
 866 </p>
 867
 868
 869 <hr><h3><a name="decl_cvCreateData">CreateData</a></h3>
 870 <p class="Blurb">Allocates array data</p>
 871 <pre>
 872 void cvCreateData( CvArr* arr );
 873 </pre><p><dl>
 874 <dt>arr<dd>Array header.
 875 </dl></p><p>
 876 The function <code>cvCreateData</code> allocates image, matrix or multi-dimensional array data.
 877 Note that in case of matrix types OpenCV allocation functions are used and
 878 in case of IplImage they are used too unless <code>CV_TURN_ON_IPL_COMPATIBILITY</code> was called.
 879 In the latter case IPL functions are used to allocate the data
 880 </p>
 881
 882
 883 <hr><h3><a name="decl_cvReleaseData">ReleaseData</a></h3>
 884 <p class="Blurb">Releases array data</p>
 885 <pre>
 886 void cvReleaseData( CvArr* arr );
 887 </pre><p><dl>
 888 <dt>arr<dd>Array header
 889 </dl><p>
 890 The function <code>cvReleaseData</code> releases the array data.
 891 In case of <a href="#decl_CvMat">CvMat</a> or <a href="#decl_CvMatND">CvMatND</a> it simply calls cvDecRefData(), that is
 892 the function can not deallocate external data. See also the note to <a href="#decl_cvCreateData">cvCreateData</a>.
 893 </p>
 894
 895
 896 <hr><h3><a name="decl_cvSetData">SetData</a></h3>
 897 <p class="Blurb">Assigns user data to the array header</p>
 898 <pre>
 899 void cvSetData( CvArr* arr, void* data, int step );
 900 </pre><p><dl>
 901 <dt>arr<dd>Array header.
 902 <dt>data<dd>User data.
 903 <dt>step<dd>Full row length in bytes.
 904 </dl><p>
 905 The function <code>cvSetData</code> assigns user data to the array header.
 906 Header should be initialized before using cvCreate*Header,
 907 cvInit*Header or <a href="#decl_cvMat">cvMat</a> (in case of matrix) function.
 908 </p>
 909
 910
 911 <hr><h3><a name="decl_cvGetRawData">GetRawData</a></h3>
 912 <p class="Blurb">Retrieves low-level information about the array</p>
 913 <pre>
 914 void cvGetRawData( const CvArr* arr, uchar** data,
 915                    int* step=NULL, CvSize* roi_size=NULL );
 916 </pre><p><dl>
 917 <dt>arr<dd>Array header.
 918 <dt>data<dd>Output pointer to the whole image origin or ROI origin if
 919 ROI is set.
 920 <dt>step<dd>Output full row length in bytes.
 921 <dt>roi_size<dd>Output ROI size.
 922 </dl><p>
 923 The function <code>cvGetRawData</code> fills output variables with low-level
 924 information about the array data.
 925 All output parameters are optional, so some of the pointers
 926 may be set to <code>NULL</code>.
 927 If the array is <code>IplImage</code> with ROI set,
 928 parameters of ROI are returned.
 929 </p>
 930 <p>The following example shows how to get access to array elements using
 931 this function.</p>
 932 <p>
 933 <font color=blue size=4>Using GetRawData to calculate absolute value of elements of
 934 a single-channel floating-point array.</font>
 935 <pre>
 936     float* data;
 937     int step;
 938
 939     CvSize size;
 940     int x, y;
 941
 942     cvGetRawData( array, (uchar**)&amp;data, &amp;step, &amp;size );
 943     step /= sizeof(data[0]);
 944
 945     for( y = 0; y &lt; size.height; y++, data += step )
 946         for( x = 0; x &lt; size.width; x++ )
 947             data[x] = (float)fabs(data[x]);
 948 </pre></p>
 949
 950
 951 <hr><h3><a name="decl_cvGetMat">GetMat</a></h3>
 952 <p class="Blurb">Returns matrix header for arbitrary array</p>
 953 <pre>
 954 CvMat* cvGetMat( const CvArr* arr, CvMat* header, int* coi=NULL, int allowND=0 );
 955 </pre><p><dl>
 956 <dt>arr<dd>Input array.
 957 <dt>header<dd>Pointer to <a href="#decl_CvMat">CvMat</a> structure used as a temporary buffer.
 958 <dt>coi<dd>Optional output parameter for storing COI.
 959 <dt>allowND<dd>If non-zero, the function accepts multi-dimensional dense
 960               arrays (CvMatND*) and returns 2D (if CvMatND has two dimensions)
 961               or 1D matrix (when CvMatND has 1 dimension or more than 2 dimensions).
 962               The array must be continuous.
 963 </dl><p>
 964 The function <code>cvGetMat</code> returns matrix header for the input array that can be
 965 matrix - <a href="#decl_CvMat">CvMat</a>, image - <code>IplImage</code> or multi-dimensional dense array - <a href="#decl_CvMatND*">CvMatND*</a>
 966 (latter case is allowed only if <code>allowND != 0</code>) .
 967 In the case of matrix the function simply returns the input pointer.
 968 In the case of <code>IplImage*</code> or <a href="#decl_CvMatND*">CvMatND*</a> it initializes <code>header</code> structure
 969 with parameters of the current image ROI and returns pointer to this temporary
 970 structure. Because COI is not supported by <a href="#decl_CvMat">CvMat</a>, it is returned separately.
 971 <p>
 972 The function provides an easy way to handle both types of array - <code>IplImage</code> and
 973 <a href="#decl_CvMat">CvMat</a> -, using the same code. Reverse transform from <a href="#decl_CvMat">CvMat</a> to <code>IplImage</code> can be
 974 done using <a href="#decl_cvGetImage">cvGetImage</a> function.
 975 </p><p>
 976 Input array must have underlying data allocated or attached, otherwise the
 977 function fails.
 978 </p>
 979 If the input array is <code>IplImage</code> with planar data layout and COI set, the function
 980 returns pointer to the selected plane and COI = 0. It enables per-plane
 981 processing of multi-channel images with planar data layout using OpenCV
 982 functions.</p>
 983
 984
 985 <hr><h3><a name="decl_cvGetImage">GetImage</a></h3>
 986 <p class="Blurb">Returns image header for arbitrary array</p>
 987 <pre>
 988 IplImage* cvGetImage( const CvArr* arr, IplImage* image_header );
 989 </pre><p><dl>
 990 <dt>arr<dd>Input array.
 991 <dt>image_header<dd>Pointer to <code>IplImage</code> structure used as a temporary buffer.
 992 </dl><p>
 993 The function <code>cvGetImage</code> returns image header for the input array that can be
 994 matrix - <a href="#decl_CvMat*">CvMat*</a>, or image - <code>IplImage*</code>. In the case of image the function simply
 995 returns the input pointer. In the case of <a href="#decl_CvMat*">CvMat*</a> it initializes <code>image_header</code> structure
 996 with parameters of the input matrix. Note that if we transform <code>IplImage</code> to <a href="#decl_CvMat">CvMat</a> and then transform
 997 CvMat back to IplImage, we can get different headers if the ROI is set, and thus some IPL functions
 998 that calculate image stride from its width and align may fail on the resultant image.</p>
 999
1000
1001 <hr><h3><a name="decl_cvCreateSparseMat">CreateSparseMat</a></h3>
1002 <p class="Blurb">Creates sparse array</p>
1003 <pre>
1004 CvSparseMat* cvCreateSparseMat( int dims, const int* sizes, int type );
1005 </pre><p><dl>
1006 <dt>dims<dd>Number of array dimensions. As opposite to the dense matrix, the number
1007             of dimensions is practically unlimited (up to 2<sup>16</sup>).
1008 <dt>sizes<dd>Array of dimension sizes.
1009 <dt>type<dd>Type of array elements. The same as for CvMat
1010 </dl><p>
1011 The function <code>cvCreateSparseMat</code> allocates multi-dimensional sparse array.
1012 Initially the array contains no elements, that is <a href="#decl_cvGet*D">cvGet*D</a> or
1013 <a href="#decl_cvGetReal*D">cvGetReal*D</a> return zero for every index</p>
1014
1015
1016 <hr><h3><a name="decl_cvReleaseSparseMat">ReleaseSparseMat</a></h3>
1017 <p class="Blurb">Deallocates sparse array</p>
1018 <pre>
1019 void cvReleaseSparseMat( CvSparseMat** mat );
1020 </pre><p><dl>
1021 <dt>mat<dd>Double pointer to the array.
1022 </dl><p>
1023 The function <code>cvReleaseSparseMat</code> releases the sparse array and clears the array pointer upon exit</p>
1024
1025
1026 <hr><h3><a name="decl_cvCloneSparseMat">CloneSparseMat</a></h3>
1027 <p class="Blurb">Creates full copy of sparse array</p>
1028 <pre>
1029 CvSparseMat* cvCloneSparseMat( const CvSparseMat* mat );
1030 </pre><p><dl>
1031 <dt>mat<dd>Input array.
1032 </dl><p>
1033 The function <code>cvCloneSparseMat</code> creates a copy of the input array and returns pointer to the copy.</p>
1034
1035
1036 <hr><h2><a name="cxcore_arrays_get_set">Accessing Elements and sub-Arrays</a></h2>
1037
1038 <hr><h3><a name="decl_cvGetSubRect">GetSubRect</a></h3>
1039 <p class="Blurb">Returns matrix header corresponding to the rectangular sub-array of input image or matrix</p>
1040 <pre>
1041 CvMat* cvGetSubRect( const CvArr* arr, CvMat* submat, CvRect rect );
1042 </pre><p><dl>
1043 <dt>arr<dd>Input array.
1044 <dt>submat<dd>Pointer to the resultant sub-array header.
1045 <dt>rect<dd>Zero-based coordinates of the rectangle of interest.
1046 </dl><p>
1047 The function <code>cvGetSubRect</code> returns header, corresponding
1048 to a specified rectangle of the input array.
1049 In other words, it allows the user to treat a rectangular part
1050 of input array as a stand-alone array. ROI is taken into account by the function
1051 so the sub-array of ROI is actually extracted.</p>
1052
1053
1054 <hr><h3><a name="decl_cvGetRow">GetRow, GetRows</a></h3>
1055 <p class="Blurb">Returns array row or row span</p>
1056 <pre>
1057 CvMat* cvGetRow( const CvArr* arr, CvMat* submat, int row );
1058 CvMat* cvGetRows( const CvArr* arr, CvMat* submat, int start_row, int end_row, int delta_row=1 );
1059 </pre><p><dl>
1060 <dt>arr<dd>Input array.
1061 <dt>submat<dd>Pointer to the resulting sub-array header.
1062 <dt>row<dd>Zero-based index of the selected row.
1063 <dt>start_row<dd>Zero-based index of the starting row (inclusive) of the span.
1064 <dt>end_row<dd>Zero-based index of the ending row (exclusive) of the span.
1065 <dt>delta_row<dd>Index step in the row span. That is, the function extracts every <code>delta_row</code>-th
1066 row from <code>start_row</code> and up to (but not including) <code>end_row</code>.
1067 </dl><p>
1068 The functions <code>GetRow</code> and <code>GetRows</code> return the header, corresponding to a specified
1069 row/row span of the input array. Note that <code>GetRow</code> is a shortcut for <a href="#decl_cvGetRows">cvGetRows</a>:
1070 <pre>
1071 cvGetRow( arr, submat, row ) ~ cvGetRows( arr, submat, row, row + 1, 1 );
1072 </pre></p>
1073
1074
1075 <hr><h3><a name="decl_cvGetCol">GetCol, GetCols</a></h3>
1076 <p class="Blurb">Returns array column or column span</p>
1077 <pre>
1078 CvMat* cvGetCol( const CvArr* arr, CvMat* submat, int col );
1079 CvMat* cvGetCols( const CvArr* arr, CvMat* submat, int start_col, int end_col );
1080 </pre><p><dl>
1081 <dt>arr<dd>Input array.
1082 <dt>submat<dd>Pointer to the resulting sub-array header.
1083 <dt>col<dd>Zero-based index of the selected column.
1084 <dt>start_col<dd>Zero-based index of the starting column (inclusive) of the span.
1085 <dt>end_col<dd>Zero-based index of the ending column (exclusive) of the span.
1086 </dl><p>
1087 The functions <code>GetCol</code> and <code>GetCols</code> return the header, corresponding to a specified
1088 column/column span of the input array. Note that <code>GetCol</code> is a shortcut for <a href="#decl_cvGetCols">cvGetCols</a>:
1089 <pre>
1090 cvGetCol( arr, submat, col ); // ~ cvGetCols( arr, submat, col, col + 1 );
1091 </pre></p>
1092
1093
1094 <hr><h3><a name="decl_cvGetDiag">GetDiag</a></h3>
1095 <p class="Blurb">Returns one of array diagonals</p>
1096 <pre>
1097 CvMat* cvGetDiag( const CvArr* arr, CvMat* submat, int diag=0 );
1098 </pre><p><dl>
1099 <dt>arr<dd>Input array.
1100 <dt>submat<dd>Pointer to the resulting sub-array header.
1101 <dt>diag<dd>Array diagonal. Zero corresponds to the main diagonal, -1 corresponds to the diagonal above
1102 the main etc., 1 corresponds to the diagonal below the main etc.
1103 </dl><p>
1104 The function <code>cvGetDiag</code> returns the header, corresponding to a specified
1105 diagonal of the input array.</p>
1106
1107
1108 <hr><h3><a name="decl_cvGetSize">GetSize</a></h3>
1109 <p class="Blurb">Returns size of matrix or image ROI</p>
1110 <pre>
1111 CvSize cvGetSize( const CvArr* arr );
1112 </pre><p><dl>
1113 <dt>arr<dd>array header.
1114 </dl><p>
1115 The function <code>cvGetSize</code> returns number of rows (CvSize::height) and number of columns
1116 (CvSize::width) of the input matrix or image. In case of image the size of ROI is returned.</p>
1117
1118
1119 <hr><h3><a name="decl_cvInitSparseMatIterator">InitSparseMatIterator</a></h3>
1120 <p class="Blurb">Initializes sparse array elements iterator</p>
1121 <pre>
1122 CvSparseNode* cvInitSparseMatIterator( const CvSparseMat* mat,
1123                                        CvSparseMatIterator* mat_iterator );
1124 </pre><p><dl>
1125 <dt>mat<dd>Input array.
1126 <dt>mat_iterator<dd>Initialized iterator.
1127 </dl><p>
1128 The function <code>cvInitSparseMatIterator</code> initializes iterator of sparse array elements and
1129 returns pointer to the first element, or NULL if the array is empty.</p>
1130
1131
1132 <hr><h3><a name="decl_cvGetNextSparseNode">GetNextSparseNode</a></h3>
1133 <p class="Blurb">Initializes sparse array elements iterator</p>
1134 <pre>
1135 CvSparseNode* cvGetNextSparseNode( CvSparseMatIterator* mat_iterator );
1136 </pre><p><dl>
1137 <dt>mat_iterator<dd>Sparse array iterator.
1138 </dl><p>
1139 The function <code>cvGetNextSparseNode</code> moves iterator to the next sparse matrix element and returns
1140 pointer to it. In the current version there is no any particular order of the elements, because they
1141 are stored in hash table. The sample below demonstrates how to iterate through the sparse matrix:</p>
1142 <p>
1143 <font color=blue size=4>Using <a href="#decl_cvInitSparseMatIterator">cvInitSparseMatIterator</a> and <a href="#decl_cvGetNextSparseNode">cvGetNextSparseNode</a> to calculate sum of
1144 floating-point sparse array.</font>
1145 <pre>
1146     double sum;
1147     int i, dims = cvGetDims( array );
1148     CvSparseMatIterator mat_iterator;
1149     CvSparseNode* node = cvInitSparseMatIterator( array, &amp;mat_iterator );
1150
1151     for( ; node != 0; node = cvGetNextSparseNode( &amp;mat_iterator ))
1152     {
1153         const int* idx = CV_NODE_IDX( array, node ); /* get pointer to the element indices */
1154         float val = *(float*)CV_NODE_VAL( array, node ); /* get value of the element
1155                                                           (assume that the type is CV_32FC1) */
1156         printf( "(" );
1157         for( i = 0; i &lt; dims; i++ )
1158             printf( "%4d%s", idx[i], i &lt; dims - 1 "," : "): " );
1159         printf( "%g\n", val );
1160
1161         sum += val;
1162     }
1163
1164     printf( "\nTotal sum = %g\n", sum );
1165 </pre></p>
1166
1167 <hr><h3><a name="decl_cvGetElemType">GetElemType</a></h3>
1168 <p class="Blurb">Returns type of array elements</p>
1169 <pre>
1170 int cvGetElemType( const CvArr* arr );
1171 </pre><p><dl>
1172 <dt>arr<dd>Input array.
1173 </dl><p>
1174 The functions <code>GetElemType</code> returns type of the array elements as it is described in
1175 cvCreateMat discussion: <pre>CV_8UC1 ... CV_64FC4</pre></p>
1176
1177
1178 <hr><h3><a name="decl_cvGetDims">GetDims, GetDimSize</a></h3>
1179 <p class="Blurb">Return number of array dimensions and their sizes or the size of particular dimension</p>
1180 <pre>
1181 int cvGetDims( const CvArr* arr, int* sizes=NULL );
1182 int cvGetDimSize( const CvArr* arr, int index );
1183 </pre><p><dl>
1184 <dt>arr<dd>Input array.
1185 <dt>sizes<dd>Optional output vector of the array dimension sizes. For 2d arrays the number of rows (height)
1186 goes first, number of columns (width) next.
1187 <dt>index<dd>Zero-based dimension index (for matrices 0 means number of rows, 1 means number of columns;
1188 for images 0 means height, 1 means width).
1189 </dl><p>
1190 The function <code>cvGetDims</code> returns number of array dimensions and their sizes.
1191 In case of <code>IplImage</code> or <a href="#decl_CvMat">CvMat</a> it always returns 2 regardless of number of image/matrix rows.
1192 The function <code>cvGetDimSize</code> returns the particular dimension size (number of elements per that dimension).
1193 For example, the following code calculates total number of array elements in two ways:<pre>
1194
1195 // via cvGetDims()
1196 int sizes[CV_MAX_DIM];
1197 int i, total = 1;
1198 int dims = cvGetDims( arr, size );
1199 for( i = 0; i &lt; dims; i++ )
1200     total *= sizes[i];
1201
1202 // via cvGetDims() and cvGetDimSize()
1203 int i, total = 1;
1204 int dims = cvGetDims( arr );
1205 for( i = 0; i &lt; dims; i++ )
1206     total *= cvGetDimsSize( arr, i );
1207 </pre>
1208 </p>
1209
1210
1211 <hr><h3><a name="decl_cvPtr*D">Ptr*D</a></h3>
1212 <p class="Blurb">Return pointer to the particular array element</p>
1213 <pre>
1214 uchar* cvPtr1D( const CvArr* arr, int idx0, int* type=NULL );
1215 uchar* cvPtr2D( const CvArr* arr, int idx0, int idx1, int* type=NULL );
1216 uchar* cvPtr3D( const CvArr* arr, int idx0, int idx1, int idx2, int* type=NULL );
1217 uchar* cvPtrND( const CvArr* arr, const int* idx, int* type=NULL, int create_node=1, unsigned* precalc_hashval=NULL );
1218 </pre><p><dl>
1219 <dt>arr<dd>Input array.
1220 <dt>idx0<dd>The first zero-based component of the element index
1221 <dt>idx1<dd>The second zero-based component of the element index
1222 <dt>idx2<dd>The third zero-based component of the element index
1223 <dt>idx<dd>Array of the element indices
1224 <dt>type<dd>Optional output parameter: type of matrix elements
1225 <dt>create_node<dd>Optional input parameter for sparse matrices. Non-zero value of the parameter means that
1226 the requested element is created if it does not exist already.
1227 <dt>precalc_hashval<dd>Optional input parameter for sparse matrices. If the pointer is not NULL, the function
1228 does not recalculate the node hash value, but takes it from the specified location. It is useful for speeding
1229 up pair-wise operations (TODO: provide an example)
1230 </dl><p>
1231 The functions <code>>cvPtr*D</code> return pointer to the particular array element.
1232 Number of array dimension should match to the number of indices passed to the function except
1233 for <code>cvPtr1D</code> function that can be used for sequential access to 1D, 2D or nD dense arrays.
1234 </p><p>
1235 The functions can be used for sparse arrays as well - if the requested node does not exist they
1236 create it and set it to zero.</p><p>
1237 All these as well as other functions accessing array elements
1238 (<a href="#decl_cvGet*D">cvGet*D</a>, <a href="#decl_cvGetReal*D">cvGetReal*D</a>,
1239 <a href="#decl_cvSet*D">cvSet*D</a>, <a href="#decl_cvSetReal*D">cvSetReal*D</a>)
1240 raise an error in case if the element index is out of range.
1241 </p>
1242
1243
1244 <hr><h3><a name="decl_cvGet*D">Get*D</a></h3>
1245 <p class="Blurb">Return the particular array element</p>
1246 <pre>
1247 CvScalar cvGet1D( const CvArr* arr, int idx0 );
1248 CvScalar cvGet2D( const CvArr* arr, int idx0, int idx1 );
1249 CvScalar cvGet3D( const CvArr* arr, int idx0, int idx1, int idx2 );
1250 CvScalar cvGetND( const CvArr* arr, const int* idx );
1251 </pre><p><dl>
1252 <dt>arr<dd>Input array.
1253 <dt>idx0<dd>The first zero-based component of the element index
1254 <dt>idx1<dd>The second zero-based component of the element index
1255 <dt>idx2<dd>The third zero-based component of the element index
1256 <dt>idx<dd>Array of the element indices
1257 </dl><p>
1258 The functions <code>cvGet*D</code> return the particular array element. In case of sparse array
1259 the functions return 0 if the requested node does not exist (no new node is created
1260 by the functions)</p>
1261
1262
1263 <hr><h3><a name="decl_cvGetReal*D">GetReal*D</a></h3>
1264 <p class="Blurb">Return the particular element of single-channel array</p>
1265 <pre>
1266 double cvGetReal1D( const CvArr* arr, int idx0 );
1267 double cvGetReal2D( const CvArr* arr, int idx0, int idx1 );
1268 double cvGetReal3D( const CvArr* arr, int idx0, int idx1, int idx2 );
1269 double cvGetRealND( const CvArr* arr, const int* idx );
1270 </pre><p><dl>
1271 <dt>arr<dd>Input array. Must have a single channel.
1272 <dt>idx0<dd>The first zero-based component of the element index
1273 <dt>idx1<dd>The second zero-based component of the element index
1274 <dt>idx2<dd>The third zero-based component of the element index
1275 <dt>idx<dd>Array of the element indices
1276 </dl><p>
1277 The functions <code>cvGetReal*D</code> return the particular element of single-channel array.
1278 If the array has multiple channels, runtime error is raised. Note that <a href="#decl_cvGet*D">cvGet*D</a> function
1279 can be used safely for both single-channel and multiple-channel arrays though they are
1280 a bit slower.</p><p>In case of sparse array
1281 the functions return 0 if the requested node does not exist (no new node is created
1282 by the functions)</p>
1283
1284
1285 <hr><h3><a name="decl_cvmGet">mGet</a></h3>
1286 <p class="Blurb">Return the particular element of single-channel floating-point matrix</p>
1287 <pre>
1288 double cvmGet( const CvMat* mat, int row, int col );
1289 </pre><p><dl>
1290 <dt>mat<dd>Input matrix.
1291 <dt>row<dd>The zero-based index of row.
1292 <dt>col<dd>The zero-based index of column.
1293 </dl><p>
1294 The function <code>cvmGet</code> is a fast replacement for <a href="#decl_cvGetReal2D">cvGetReal2D</a> in case of
1295 single-channel floating-point matrices. It is faster because it is inline,
1296 it does less checks for array type and array element type and it
1297 checks for the row and column ranges only in debug mode.</p>
1298
1299
1300 <hr><h3><a name="decl_cvSet*D">Set*D</a></h3>
1301 <p class="Blurb">Change the particular array element</p>
1302 <pre>
1303 void cvSet1D( CvArr* arr, int idx0, CvScalar value );
1304 void cvSet2D( CvArr* arr, int idx0, int idx1, CvScalar value );
1305 void cvSet3D( CvArr* arr, int idx0, int idx1, int idx2, CvScalar value );
1306 void cvSetND( CvArr* arr, const int* idx, CvScalar value );
1307 </pre><p><dl>
1308 <dt>arr<dd>Input array.
1309 <dt>idx0<dd>The first zero-based component of the element index
1310 <dt>idx1<dd>The second zero-based component of the element index
1311 <dt>idx2<dd>The third zero-based component of the element index
1312 <dt>idx<dd>Array of the element indices
1313 <dt>value<dd>The assigned value
1314 </dl><p>
1315 The functions <code>cvSet*D</code> assign the new value to the particular element of array.
1316 In case of sparse array the functions create the node if it does not exist yet</p>
1317
1318
1319 <hr><h3><a name="decl_cvSetReal*D">SetReal*D</a></h3>
1320 <p class="Blurb">Change the particular array element</p>
1321 <pre>
1322 void cvSetReal1D( CvArr* arr, int idx0, double value );
1323 void cvSetReal2D( CvArr* arr, int idx0, int idx1, double value );
1324 void cvSetReal3D( CvArr* arr, int idx0, int idx1, int idx2, double value );
1325 void cvSetRealND( CvArr* arr, const int* idx, double value );
1326 </pre><p><dl>
1327 <dt>arr<dd>Input array.
1328 <dt>idx0<dd>The first zero-based component of the element index
1329 <dt>idx1<dd>The second zero-based component of the element index
1330 <dt>idx2<dd>The third zero-based component of the element index
1331 <dt>idx<dd>Array of the element indices
1332 <dt>value<dd>The assigned value
1333 </dl><p>
1334 The functions <code>cvSetReal*D</code> assign the new value to the particular element of single-channel array.
1335 If the array has multiple channels, runtime error is raised. Note that <a href="#decl_cvSet*D">cvSet*D</a> function
1336 can be used safely for both single-channel and multiple-channel arrays though they are
1337 a bit slower.</p>
1338 <p>In case of sparse array the functions create the node if it does not exist yet</p>
1339
1340
1341 <hr><h3><a name="decl_cvmSet">mSet</a></h3>
1342 <p class="Blurb">Return the particular element of single-channel floating-point matrix</p>
1343 <pre>
1344 void cvmSet( CvMat* mat, int row, int col, double value );
1345 </pre><p><dl>
1346 <dt>mat<dd>The matrix.
1347 <dt>row<dd>The zero-based index of row.
1348 <dt>col<dd>The zero-based index of column.
1349 <dt>value<dd>The new value of the matrix element
1350 </dl><p>
1351 The function <code>cvmSet</code> is a fast replacement for <a href="#decl_cvSetReal2D">cvSetReal2D</a> in case of
1352 single-channel floating-point matrices. It is faster because it is inline,
1353 it does less checks for array type and array element type and it
1354 checks for the row and column ranges only in debug mode.</p>
1355
1356
1357 <hr><h3><a name="decl_cvClearND">ClearND</a></h3>
1358 <p class="Blurb">Clears the particular array element</p>
1359 <pre>
1360 void cvClearND( CvArr* arr, const int* idx );
1361 </pre><p><dl>
1362 <dt>arr<dd>Input array.
1363 <dt>idx<dd>Array of the element indices
1364 </dl><p>
1365 The function <a href="#decl_cvClearND">cvClearND</a> clears (sets to zero)
1366 the particular element of dense array or deletes the element of sparse array.
1367 If the element does not exists, the function does nothing.</p>
1368
1369
1370 <hr><h2><a name="cxcore_arrays_copying">Copying and Filling</a></h2>
1371
1372
1373 <hr><h3><a name="decl_cvCopy">Copy</a></h3>
1374 <p class="Blurb">Copies one array to another</p>
1375 <pre>
1376 void cvCopy( const CvArr* src, CvArr* dst, const CvArr* mask=NULL );
1377 </pre><p><dl>
1378 <dt>src<dd>The source array.
1379 <dt>dst<dd>The destination array.
1380 <dt>mask<dd>Operation mask, 8-bit single channel array; specifies elements of
1381 destination array to be changed.
1382 </dl><p>
1383 The function <code>cvCopy</code> copies selected elements from input array to output array:</p>
1384 <p>
1385 dst(I)=src(I) if mask(I)!=0.
1386 </p><p>If any of the passed arrays is of <code>IplImage</code> type, then its ROI and COI fields are
1387 used. Both arrays must have the same type, the same number of dimensions and the same size.
1388 The function can also copy sparse arrays (mask is not supported in this case).</p>
1389
1390
1391 <hr><h3><a name="decl_cvSet">Set</a></h3>
1392 <p class="Blurb">Sets every element of array to given value</p>
1393 <pre>
1394 void cvSet( CvArr* arr, CvScalar value, const CvArr* mask=NULL );
1395 </pre><p><dl>
1396 <dt>arr<dd>The destination array.
1397 <dt>value<dd>Fill value.
1398 <dt>mask<dd>Operation mask, 8-bit single channel array; specifies elements of
1399 destination array to be changed.
1400 </dl><p>
1401 The function <code>cvSet</code> copies scalar <code>value</code> to every selected element of the destination
1402 array:</p>
1403 <pre>arr(I)=value if mask(I)!=0</pre>
1404 <p>If array <code>arr</code> is of <code>IplImage</code> type, then is ROI used, but COI must not be
1405 set.</p>
1406
1407
1408 <hr><h3><a name="decl_cvSetZero">SetZero</a></h3>
1409 <p class="Blurb">Clears the array</p>
1410 <pre>
1411 void cvSetZero( CvArr* arr );
1412 #define cvZero cvSetZero
1413 </pre><p><dl>
1414 <dt>arr<dd>array to be cleared.
1415 </dl><p>
1416 The function <code>cvSetZero</code> clears the array. In case of dense arrays
1417 (CvMat, CvMatND or IplImage) cvZero(array) is equivalent to cvSet(array,cvScalarAll(0),0),
1418 in case of sparse arrays all the elements are removed.</p>
1419
1420
1421 <hr><h3><a name="decl_cvSetIdentity">SetIdentity</a></h3>
1422 <p class="Blurb">Initializes scaled identity matrix</p>
1423 <pre>
1424 void cvSetIdentity( CvArr* mat, CvScalar value=cvRealScalar(1) );
1425 </pre><p><dl>
1426 <dt>arr<dd>The matrix to initialize (not necessarily square).
1427 <dt>value<dd>The value to assign to the diagonal elements.
1428 </dl><p>
1429 The function <code>cvSetIdentity</code> initializes scaled identity matrix:</p>
1430 <pre>
1431 arr(i,j)=value if i=j,
1432        0 otherwise
1433 </pre>
1434
1435
1436 <hr><h3><a name="decl_cvRange">Range</a></h3>
1437 <p class="Blurb">Fills matrix with given range of numbers</p>
1438 <pre>
1439 void cvRange( CvArr* mat, double start, double end );
1440 </pre><p><dl>
1441 <dt>mat<dd>The matrix to initialize. It should be single-channel 32-bit, integer or floating-point.
1442 <dt>start<dd>The lower inclusive boundary of the range.
1443 <dt>end<dd>The upper exclusive boundary of the range.
1444 </dl><p>
1445 The function <code>cvRange</code> initializes the matrix as following:</p>
1446 <pre>
1447 arr(i,j)=(end-start)*(i*cols(arr)+j)/(cols(arr)*rows(arr))
1448 </pre>
1449 For example, the following code will initialize 1D vector with subsequent integer numbers.
1450 <pre>
1451 CvMat* A = cvCreateMat( 1, 10, CV_32S );
1452 cvRange( A, 0, A->cols ); // A will be initialized as [0,1,2,3,4,5,6,7,8,9]
1453 </pre>
1454
1455 <!-- *****************************************************************************************
1456      *****************************************************************************************
1457      ***************************************************************************************** -->
1458
1459 <hr><h2><a name="cxcore_arrays_permute">Transforms and Permutations</a></h2>
1460
1461 <hr><h3><a name="decl_cvReshape">Reshape</a></h3>
1462 <p class="Blurb">Changes shape of matrix/image without copying data</p>
1463 <pre>
1464 CvMat* cvReshape( const CvArr* arr, CvMat* header, int new_cn, int new_rows=0 );
1465 </pre><p><dl>
1466 <dt>arr<dd>Input array.
1467 <dt>header<dd>Output header to be filled.
1468 <dt>new_cn<dd>New number of channels. <code>new_cn = 0</code> means that number of channels remains unchanged.
1469 <dt>new_rows<dd>New number of rows. <code>new_rows = 0</code> means that number of rows remains unchanged unless
1470 it needs to be changed according to <code>new_cn</code> value.
1471 destination array to be changed.
1472 </dl><p>
1473 The function <code>cvReshape</code> initializes CvMat header so that it points to the same data as
1474 the original array but has different shape - different number of channels,
1475 different number of rows or both.</p><p>For example, the following code creates one image buffer and
1476 two image headers, first is for 320x240x3 image and the second is for 960x240x1 image:</p>
1477 <pre>
1478 IplImage* color_img = cvCreateImage( cvSize(320,240), IPL_DEPTH_8U, 3 );
1479 CvMat gray_mat_hdr;
1480 IplImage gray_img_hdr, *gray_img;
1481 cvReshape( color_img, &amp;gray_mat_hdr, 1 );
1482 gray_img = cvGetImage( &amp;gray_mat_hdr, &amp;gray_img_hdr );
1483 </pre>
1484 <p>And the next example converts 3x3 matrix to a single 1x9 vector</p>
1485 <pre>
1486 CvMat* mat = cvCreateMat( 3, 3, CV_32F );
1487 CvMat row_header, *row;
1488 row = cvReshape( mat, &amp;row_header, 0, 1 );
1489 </pre>
1490
1491
1492 <hr><h3><a name="decl_cvReshapeMatND">ReshapeMatND</a></h3>
1493 <p class="Blurb">Changes shape of multi-dimensional array w/o copying data</p>
1494 <pre>
1495 CvArr* cvReshapeMatND( const CvArr* arr,
1496                        int sizeof_header, CvArr* header,
1497                        int new_cn, int new_dims, int* new_sizes );
1498
1499 #define cvReshapeND( arr, header, new_cn, new_dims, new_sizes )   \
1500       cvReshapeMatND( (arr), sizeof(*(header)), (header),         \
1501                       (new_cn), (new_dims), (new_sizes))
1502
1503 </pre><p><dl>
1504 <dt>arr<dd>Input array.
1505 <dt>sizeof_header<dd>Size of output header to distinguish between IplImage, CvMat and CvMatND output headers.
1506 <dt>header<dd>Output header to be filled.
1507 <dt>new_cn<dd>New number of channels. <code>new_cn = 0</code> means that number of channels remains unchanged.
1508 <dt>new_dims<dd>New number of dimensions. <code>new_dims = 0</code> means that number of dimensions remains the same.
1509 <dt>new_sizes<dd>Array of new dimension sizes. Only <code>new_dims-1</code> values are used, because the total number of
1510 elements must remain the same. Thus, if <code>new_dims = 1</code>, <code>new_sizes</code> array is not used
1511 </dl><p>
1512 The function <code>cvReshapeMatND</code> is an advanced version of <a href="#decl_cvReshape">cvReshape</a> that can work
1513 with multi-dimensional arrays as well (though, it can work with ordinary images and matrices)
1514 and change the number of dimensions. Below are the two samples
1515 from the <a href="#decl_cvReshape">cvReshape</a> description rewritten using <a href="#decl_cvReshapeMatND">cvReshapeMatND</a>:</p>
1516 <pre>
1517 IplImage* color_img = cvCreateImage( cvSize(320,240), IPL_DEPTH_8U, 3 );
1518 IplImage gray_img_hdr, *gray_img;
1519 gray_img = (IplImage*)cvReshapeND( color_img, &amp;gray_img_hdr, 1, 0, 0 );
1520
1521 ...
1522
1523 /* second example is modified to convert 2x2x2 array to 8x1 vector */
1524 int size[] = { 2, 2, 2 };
1525 CvMatND* mat = cvCreateMatND( 3, size, CV_32F );
1526 CvMat row_header, *row;
1527 row = cvReshapeND( mat, &amp;row_header, 0, 1, 0 );
1528 </pre>
1529
1530
1531 <hr><h3><a name="decl_cvRepeat">Repeat</a></h3>
1532 <p class="Blurb">Fill destination array with tiled source array</p>
1533 <pre>
1534 void cvRepeat( const CvArr* src, CvArr* dst );
1535 </pre><p><dl>
1536 <dt>src<dd>Source array, image or matrix.
1537 <dt>dst<dd>Destination array, image or matrix.
1538 </dl><p>
1539 The function <code>cvRepeat</code> fills the destination array with source array tiled:</p>
1540 <pre>dst(i,j)=src(i mod rows(src), j mod cols(src))</pre>
1541 <p>
1542 So the destination array may be as larger as well as smaller than
1543 the source array.
1544 </p>
1545
1546
1547 <hr><h3><a name="decl_cvFlip">Flip</a></h3>
1548 <p class="Blurb">Flip a 2D array around vertical, horizontal or both axises</p>
1549 <pre>
1550 void  cvFlip( const CvArr* src, CvArr* dst=NULL, int flip_mode=0);
1551 #define cvMirror cvFlip
1552
1553 </pre><p><dl>
1554 <dt>src<dd>Source array.
1555 <dt>dst<dd>Destination array. If <code>dst = NULL</code> the flipping is done in-place.
1556 <dt>flip_mode<dd>Specifies how to flip the array.<br>
1557                  flip_mode = 0 means flipping around x-axis,
1558                  flip_mode > 0 (e.g. 1) means flipping around y-axis
1559                  and flip_mode &lt; 0 (e.g. -1) means flipping around both axises.
1560                  See also the discussion below for the formulas
1561 </dl><p>
1562 The function <code>cvFlip</code> flips the array in one of different 3 ways
1563 (row and column indices are 0-based):</p>
1564 <pre>dst(i,j)=src(rows(src)-i-1,j) if flip_mode = 0</pre>
1565 <pre>dst(i,j)=src(i,cols(src1)-j-1) if flip_mode > 0</pre>
1566 <pre>dst(i,j)=src(rows(src)-i-1,cols(src)-j-1) if flip_mode &lt; 0</pre>
1567 <p>The example scenario of the function use are:
1568 <ul>
1569 <li>
1570 vertical flipping of the image (flip_mode > 0) to switch between top-left
1571 and bottom-left image origin, which is typical operation in video processing under Win32 systems.</li>
1572 <li>
1573 horizontal flipping of the image with subsequent horizontal shift and absolute difference calculation
1574 to check for a vertical-axis symmetry (flip_mode > 0)</li>
1575 <li>
1576 simultaneous horizontal and vertical flipping of the image with subsequent shift and
1577 absolute difference calculation to check for a central symmetry (flip_mode &lt; 0)</li>
1578 <li>reversing the order of 1d point arrays(flip_mode > 0)</li>
1579 </ul></p>
1580
1581
1582 <hr><h3><a name="decl_cvSplit">Split</a></h3>
1583 <p class="Blurb">Divides multi-channel array into several single-channel arrays or extracts
1584 a single channel from the array</p>
1585 <pre>
1586 void cvSplit( const CvArr* src, CvArr* dst0, CvArr* dst1,
1587               CvArr* dst2, CvArr* dst3 );
1588 #define cvCvtPixToPlane cvSplit
1589 </pre><p><dl>
1590 <dt>src<dd>Source array.
1591 <dt>dst0...dst3<dd>Destination channels.
1592 </dl><p>
1593 The function <code>cvSplit</code> divides a multi-channel array into separate single-channel arrays.
1594 Two modes are available for the operation. If the source array has N channels then if
1595 the first N destination channels are not NULL, all they are extracted from the source array,
1596 otherwise if only a single destination channel of the first N is not NULL, this particular channel
1597 is extracted, otherwise an error is raised. Rest of destination channels (beyond the first N)
1598 must always be NULL.
1599 For IplImage <a href="#decl_cvCopy">cvCopy</a> with COI set can be also used to extract a single channel from the image.</p>
1600
1601
1602 <hr><h3><a name="decl_cvMerge">Merge</a></h3>
1603 <p class="Blurb">Composes multi-channel array from several single-channel arrays or inserts a
1604 single channel into the array</p>
1605 <pre>
1606 void cvMerge( const CvArr* src0, const CvArr* src1,
1607               const CvArr* src2, const CvArr* src3, CvArr* dst );
1608 #define cvCvtPlaneToPix cvMerge
1609 </pre><p><dl>
1610 <dt>src0... src3<dd>Input channels.
1611 <dt>dst<dd>Destination array.
1612 </dl><p>
1613 The function <code>cvMerge</code> is the opposite to the previous.
1614 If the destination array has N channels then if
1615 the first N input channels are not NULL, all they are copied to the destination array,
1616 otherwise if only a single source channel of the first N is not NULL, this particular channel is copied
1617 into the destination array, otherwise an error is raised. Rest of source channels (beyond the first N)
1618 must always be NULL.
1619 For IplImage <a href="#decl_cvCopy">cvCopy</a> with COI set can be also used to insert a single channel into the image.
1620 </p>
1621
1622
1623 <hr><h3><a name="decl_cvMixChannels">MixChannels</a></h3>
1624 <p class="Blurb">Copies several channels from input arrays to
1625    certain channels of output arrays</p>
1626 <pre>
1627 void cvMixChannels( const CvArr** src, int src_count,
1628                     CvArr** dst, int dst_count,
1629                     const int* from_to, int pair_count );
1630 </pre><p><dl>
1631 <dt>src<dd>The array of input arrays.
1632 <dt>src_count<dd>The number of input arrays.
1633 <dt>dst<dd>The array of output arrays.
1634 <dt>dst_count<dd>The number of output arrays.
1635 <dt>from_to<dd>The array of pairs of indices of the planes copied.
1636 <code>from_to[k*2]</code> is the 0-based index of the input plane,
1637 and <code>from_to[k*2+1]</code> is the index of the output plane, where the continuous numbering
1638 of the planes over all the input and over all the output arrays is used.
1639 When <code>from_to[k*2]</code> is negative, the corresponding output plane is filled with 0's.
1640 <dt>pair_count<dd>The number of pairs in <code>from_to</code>, or the number of the planes copied.
1641 </dl><p>
1642 The function <code>cvMixChannels</code> is a generalized form of <a href="#decl_cvSplit">cvSplit</a> and
1643 <a href="#decl_cvMerge">cvMerge</a> and some forms of <a href="opencvref_cv.htm#decl_cvCvtColor">cvCvtColor</a>.
1644 It can be used to change the order of the planes, add/remove alpha
1645 channel, extract or insert a single plane or multiple planes etc.
1646 Below is the example, how to split 4-channel RGBA image into 3-channel BGR (i.e. with R&B swapped) and
1647 separate alpha channel images:</p>
1648 <pre>
1649     CvMat* rgba = cvCreateMat( 100, 100, CV_8UC4 );
1650     CvMat* bgr = cvCreateMat( rgba->rows, rgba->cols, CV_8UC3 );
1651     CvMat* alpha = cvCreateMat( rgba->rows, rgba->cols, CV_8UC1 );
1652     CvArr* out[] = { bgr, alpha };
1653     int from_to[] = { 0, 2, 1, 1, 2, 0, 3, 3 };
1654     cvSet( rgba, cvScalar(1,2,3,4) );
1655     cvMixChannels( (const CvArr**)&rgba, 1, out, 2, from_to, 4 );
1656 </pre>
1657
1658
1659 <hr><h3><a name="decl_cvRandShuffle">RandShuffle</a></h3>
1660 <p class="Blurb">Randomly shuffles the array elements</p>
1661 <pre>
1662 void cvRandShuffle( CvArr* mat, CvRNG* rng, double iter_factor=1. );
1663 </pre><p><dl>
1664 <dt>mat<dd>The input/output matrix. It is shuffled in-place.
1665 <dt>rng<dd>The <a href="#cxcore_arrays_rng">Random Number Generator</a>
1666            used to shuffle the elements. When the pointer is NULL,
1667            a temporary RNG will be created and used.
1668 <dt>iter_factor<dd>The relative parameter that characterizes intensity of the shuffling performed.
1669                    See the description below.
1670 </dl><p>
1671 The function <code>cvRandShuffle</code> shuffles the matrix by swapping randomly chosen pairs
1672 of the matrix elements on each iteration (where each element may contain several components in case of multi-channel arrays).
1673 The number of iterations (i.e. pairs swapped) is <code>round(iter_factor*rows(mat)*cols(mat))</code>, so
1674 <code>iter_factor=0</code> means that no shuffling is done,
1675 <code>iter_factor=1</code> means that the function swaps
1676 <code>rows(mat)*cols(mat)</code> random pairs etc.
1677 </p>
1678
1679
1680 <hr><h2><a name="cxcore_arrays_arithm_logic">Arithmetic, Logic and Comparison</a></h2>
1681
1682
1683 <hr><h3><a name="decl_cvLUT">LUT</a></h3>
1684 <p class="Blurb">Performs look-up table transform of array</p>
1685 <pre>
1686 void cvLUT( const CvArr* src, CvArr* dst, const CvArr* lut );
1687 </pre><p><dl>
1688 <dt>src<dd>Source array of 8-bit elements.
1689 <dt>dst<dd>Destination array of arbitrary depth and of the same number of channels as the
1690 source array.
1691 <dt>lut<dd>Look-up table of 256 elements; should have the same depth as the
1692 destination array. In case of multi-channel source and destination arrays, the table
1693 should either have a single-channel (in this case the same table is used for all channels),
1694 or the same number of channels as the source/destination array.
1695 </dl><p>
1696 The function <code>cvLUT</code> fills the destination array with values
1697 from the look-up table. Indices of the entries are taken from the source array. That is, the
1698 function processes each element of <code>src</code> as following:</p>
1699 <pre>
1700 dst(I)=lut[src(I)+DELTA]
1701 </pre>
1702 where <code>DELTA=0</code> if <code>src</code> has depth <code>CV_8U</code>, and
1703 <code>DELTA=128</code> if <code>src</code> has depth <code>CV_8S</code>.
1704 </p>
1705
1706
1707 <hr><h3><a name="decl_cvConvertScale">ConvertScale</a></h3>
1708 <p class="Blurb">Converts one array to another with optional linear transformation</p>
1709 <pre>
1710 void cvConvertScale( const CvArr* src, CvArr* dst, double scale=1, double shift=0 );
1711
1712 #define cvCvtScale cvConvertScale
1713 #define cvScale  cvConvertScale
1714 #define cvConvert( src, dst )  cvConvertScale( (src), (dst), 1, 0 )
1715 </pre><p><dl>
1716 <dt>src<dd>Source array.
1717 <dt>dst<dd>Destination array.
1718 <dt>scale<dd>Scale factor.
1719 <dt>shift<dd>Value added to the scaled source array elements.
1720 </dl><p>
1721 The function <code>cvConvertScale</code> has several different purposes and thus has several synonyms.
1722 It copies one array to another with optional scaling, which is performed first, and/or optional type conversion, performed after:</p>
1723 <pre>dst(I)=src(I)*scale + (shift,shift,...)</pre>
1724 <p>All the channels of multi-channel arrays are processed independently.</p><p>
1725 The type conversion is done with rounding and saturation, that is if a result of scaling + conversion can not
1726 be represented exactly by a value of destination array element type, it is set to the nearest
1727 representable value on the real axis.</p>
1728 <p>In case of <code>scale=1, shift=0</code> no pre-scaling is done. This is a specially optimized case and it
1729 has the appropriate <a href="#decl_cvConvert">cvConvert</a> synonym. If source and destination array types have
1730 equal types, this is also a special case that can be used to scale and shift a matrix or an image and
1731 that fits to <a href="#decl_cvScale">cvScale</a> synonym.</p>
1732
1733
1734 <hr><h3><a name="decl_cvConvertScaleAbs">ConvertScaleAbs</a></h3>
1735 <p class="Blurb">Converts input array elements to 8-bit unsigned integer another with optional linear transformation</p>
1736 <pre>
1737 void cvConvertScaleAbs( const CvArr* src, CvArr* dst, double scale=1, double shift=0 );
1738 #define cvCvtScaleAbs cvConvertScaleAbs
1739
1740 </pre><p><dl>
1741 <dt>src<dd>Source array.
1742 <dt>dst<dd>Destination array (should have 8u depth).
1743 <dt>scale<dd>ScaleAbs factor.
1744 <dt>shift<dd>Value added to the scaled source array elements.
1745 </dl><p>
1746 The function <code>cvConvertScaleAbs</code> is similar to the previous one, but it stores absolute values
1747 of the conversion results:</p>
1748 <pre>dst(I)=abs(src(I)*scale + (shift,shift,...))</pre>
1749 <p>
1750 The function supports only destination arrays of 8u (8-bit unsigned integers) type, for
1751 other types the function can be emulated by combination of <a href="#decl_cvConvertScale">cvConvertScale</a> and <a href="#decl_cvAbsDiffS">cvAbs</a>
1752 functions.</p>
1753
1754
1755 <hr><h3><a name="decl_cvAdd">Add</a></h3>
1756 <p class="Blurb">Computes per-element sum of two arrays</p>
1757 <pre>
1758 void cvAdd( const CvArr* src1, const CvArr* src2, CvArr* dst, const CvArr* mask=NULL );
1759 </pre><p><dl>
1760
1761 <dt>src1<dd>The first source array.
1762 <dt>src2<dd>The second source array.
1763 <dt>dst<dd>The destination array.
1764 <dt>mask<dd>Operation mask, 8-bit single channel array; specifies elements of
1765 destination array to be changed.
1766 </dl><p>
1767 The function <code>cvAdd</code> adds one array to another one:</p>
1768 <pre>dst(I)=src1(I)+src2(I) if mask(I)!=0</pre>
1769 <p>All the arrays must have the same type, except the mask, and the same size (or ROI size)</p>
1770
1771
1772 </p><hr><h3><a name="decl_cvAddS">AddS</a></h3>
1773 <p class="Blurb">Computes sum of array and scalar</p>
1774 <pre>
1775 void cvAddS( const CvArr* src, CvScalar value, CvArr* dst, const CvArr* mask=NULL );
1776 </pre><p><dl>
1777 <dt>src<dd>The source array.
1778 <dt>value<dd>Added scalar.
1779 <dt>dst<dd>The destination array.
1780 <dt>mask<dd>Operation mask, 8-bit single channel array; specifies elements of
1781 destination array to be changed.
1782 </dl><p>
1783 The function <code>cvAddS</code> adds scalar <code>value</code> to every element in the source array <code>src1</code> and
1784 stores the result in <code>dst</code><p>
1785 <pre>dst(I)=src(I)+value if mask(I)!=0</pre>
1786 <p>All the arrays must have the same type, except the mask, and the same size (or ROI size)</p>
1787
1788
1789 <hr><h3><a name="decl_cvAddWeighted">AddWeighted</a></h3>
1790 <p class="Blurb">Computes weighted sum of two arrays</p>
1791 <pre>
1792 void  cvAddWeighted( const CvArr* src1, double alpha,
1793                      const CvArr* src2, double beta,
1794                      double gamma, CvArr* dst );
1795 </pre><p><dl>
1796 <dt>src1<dd>The first source array.
1797 <dt>alpha<dd>Weight of the first array elements.
1798 <dt>src2<dd>The second source array.
1799 <dt>beta<dd>Weight of the second array elements.
1800 <dt>dst<dd>The destination array.
1801 <dt>gamma<dd>Scalar, added to each sum.
1802 </dl><p>
1803 The function <code>cvAddWeighted</code> calculated weighted sum
1804 of two arrays as following:</p>
1805 <pre>dst(I)=src1(I)*alpha+src2(I)*beta+gamma</pre>
1806 <p>All the arrays must have the same type and the same size (or ROI size)</p>
1807
1808
1809 <hr><h3><a name="decl_cvSub">Sub</a></h3>
1810 <p class="Blurb">Computes per-element difference between two arrays</p>
1811 <pre>
1812 void cvSub( const CvArr* src1, const CvArr* src2, CvArr* dst, const CvArr* mask=NULL );
1813 </pre><p><dl>
1814 <dt>src1<dd>The first source array.
1815 <dt>src2<dd>The second source array.
1816 <dt>dst<dd>The destination array.
1817 <dt>mask<dd>Operation mask, 8-bit single channel array; specifies elements of
1818 destination array to be changed.
1819 </dl><p>
1820 The function <code>cvSub</code> subtracts one array from another one:</p>
1821 <pre>dst(I)=src1(I)-src2(I) if mask(I)!=0</pre>
1822 <p>All the arrays must have the same type, except the mask, and the same size (or ROI size)</p>
1823
1824
1825 </p><hr><h3><a name="decl_cvSubS">SubS</a></h3>
1826 <p class="Blurb">Computes difference between array and scalar</p>
1827 <pre>
1828 void cvSubS( const CvArr* src, CvScalar value, CvArr* dst, const CvArr* mask=NULL );
1829 </pre><p><dl>
1830 <dt>src<dd>The source array.
1831 <dt>value<dd>Subtracted scalar.
1832 <dt>dst<dd>The destination array.
1833 <dt>mask<dd>Operation mask, 8-bit single channel array; specifies elements of
1834 destination array to be changed.
1835 </dl><p>
1836 The function <code>cvSubS</code> subtracts a scalar from every element of the source array:<p>
1837 <pre>dst(I)=src(I)-value if mask(I)!=0</pre>
1838 <p>All the arrays must have the same type, except the mask, and the same size (or ROI size)</p>
1839
1840
1841 <hr><h3><a name="decl_cvSubRS">SubRS</a></h3>
1842 <p class="Blurb">Computes difference between scalar and array</p>
1843 <pre>
1844 void cvSubRS( const CvArr* src, CvScalar value, CvArr* dst, const CvArr* mask=NULL );
1845 </pre><p><dl>
1846 <dt>src<dd>The first source array.
1847 <dt>value<dd>Scalar to subtract from.
1848 <dt>dst<dd>The destination array.
1849 <dt>mask<dd>Operation mask, 8-bit single channel array; specifies elements of
1850 destination array to be changed.
1851 </dl><p>
1852 The function <code>cvSubRS</code> subtracts every element of source array from a scalar:</p>
1853 <pre>dst(I)=value-src(I) if mask(I)!=0</pre>
1854 <p>All the arrays must have the same type, except the mask, and the same size (or ROI size)</p>
1855
1856
1857 <hr><h3><a name="decl_cvMul">Mul</a></h3>
1858 <p class="Blurb">Calculates per-element product of two arrays</p>
1859 <pre>
1860 void cvMul( const CvArr* src1, const CvArr* src2, CvArr* dst, double scale=1 );
1861 </pre><p><dl>
1862 <dt>src1<dd>The first source array.
1863 <dt>src2<dd>The second source array.
1864 <dt>dst<dd>The destination array.
1865 <dt>scale<dd>Optional scale factor
1866 </dl><p>
1867 The function <code>cvMul</code> calculates per-element product of two arrays:</p>
1868 <pre>dst(I)=scale&bull;src1(I)&bull;src2(I)</pre>
1869 <p>All the arrays must have the same type, and the same size (or ROI size)</p>
1870
1871
1872 <hr><h3><a name="decl_cvDiv">Div</a></h3>
1873 <p class="Blurb">Performs per-element division of two arrays</p>
1874 <pre>
1875 void cvDiv( const CvArr* src1, const CvArr* src2, CvArr* dst, double scale=1 );
1876 </pre><p><dl>
1877 <dt>src1<dd>The first source array. If the pointer is NULL, the array is assumed to be all 1&#146;s.
1878 <dt>src2<dd>The second source array.
1879 <dt>dst<dd>The destination array.
1880 <dt>scale<dd>Optional scale factor
1881 </dl><p>
1882 The function <code>cvDiv</code> divides one array by another:</p>
1883 <pre>
1884 dst(I)=scale&bull;src1(I)/src2(I), if src1!=NULL
1885 dst(I)=scale/src2(I),      if src1=NULL
1886 </pre>
1887 <p>All the arrays must have the same type, and the same size (or ROI size)</p>
1888
1889
1890 <hr><h3><a name="decl_cvAnd">And</a></h3>
1891 <p class="Blurb">Calculates per-element bit-wise conjunction of two arrays</p>
1892 <pre>
1893 void cvAnd( const CvArr* src1, const CvArr* src2, CvArr* dst, const CvArr* mask=NULL );
1894 </pre><p><dl>
1895 <dt>src1<dd>The first source array.
1896 <dt>src2<dd>The second source array.
1897 <dt>dst<dd>The destination array.
1898 <dt>mask<dd>Operation mask, 8-bit single channel array; specifies elements of
1899 destination array to be changed.
1900 </dl><p>
1901 The function <code>cvAnd</code> calculates per-element bit-wise logical conjunction of two arrays:</p>
1902 <pre>dst(I)=src1(I)&amp;src2(I) if mask(I)!=0</pre>
1903 <p>In the case of floating-point arrays their bit representations are used for the
1904 operation. All the arrays must have the same type, except the mask, and the same size</p>
1905
1906
1907 <hr><h3><a name="decl_cvAndS">AndS</a></h3>
1908 <p class="Blurb">Calculates per-element bit-wise conjunction of array and scalar</p>
1909 <pre>
1910 void cvAndS( const CvArr* src, CvScalar value, CvArr* dst, const CvArr* mask=NULL );
1911 </pre><p><dl>
1912 <dt>src<dd>The source array.
1913 <dt>value<dd>Scalar to use in the operation.
1914 <dt>dst<dd>The destination array.
1915 <dt>mask<dd>Operation mask, 8-bit single channel array; specifies elements of
1916 destination array to be changed.
1917 </dl><p>
1918 The function AndS calculates per-element bit-wise conjunction of array and scalar:</p>
1919 <pre>dst(I)=src(I)&amp;value if mask(I)!=0</pre>
1920 <p>Prior to the actual operation the scalar is converted to the same type as
1921 the arrays. In the case of floating-point arrays their bit representations are used for the
1922 operation. All the arrays must have the same type, except the mask, and the same size</p>
1923
1924 <p>The following sample demonstrates how to calculate absolute value of floating-point array elements
1925 by clearing the most-significant bit:</p>
1926 <pre>
1927 float a[] = { -1, 2, -3, 4, -5, 6, -7, 8, -9 };
1928 CvMat A = cvMat( 3, 3, CV_32F, &amp;a );
1929 int i, abs_mask = 0x7fffffff;
1930 cvAndS( &amp;A, cvRealScalar(*(float*)&amp;abs_mask), &amp;A, 0 );
1931 for( i = 0; i &lt; 9; i++ )
1932     printf("%.1f ", a[i] );
1933 </pre>
1934 <p>The code should print:</p>
1935 <pre>1.0 2.0 3.0 4.0 5.0 6.0 7.0 8.0 9.0</pre>
1936
1937
1938 <hr><h3><a name="decl_cvOr">Or</a></h3>
1939 <p class="Blurb">Calculates per-element bit-wise disjunction of two arrays</p>
1940 <pre>
1941 void cvOr( const CvArr* src1, const CvArr* src2, CvArr* dst, const CvArr* mask=NULL );
1942 </pre><p><dl>
1943 <dt>src1<dd>The first source array.
1944 <dt>src2<dd>The second source array.
1945 <dt>dst<dd>The destination array.
1946 <dt>mask<dd>Operation mask, 8-bit single channel array; specifies elements of
1947 destination array to be changed.
1948 </dl><p>
1949 The function <code>cvOr</code> calculates per-element bit-wise disjunction of two arrays:</p>
1950 <pre>dst(I)=src1(I)|src2(I)</pre>
1951 <p>In the case of floating-point arrays their bit representations are used for the
1952 operation. All the arrays must have the same type, except the mask, and the same size</p>
1953
1954
1955 <hr><h3><a name="decl_cvOrS">OrS</a></h3>
1956 <p class="Blurb">Calculates per-element bit-wise disjunction of array and scalar</p>
1957 <pre>
1958 void cvOrS( const CvArr* src, CvScalar value, CvArr* dst, const CvArr* mask=NULL );
1959 </pre><p><dl>
1960 <dt>src1<dd>The source array.
1961 <dt>value<dd>Scalar to use in the operation.
1962 <dt>dst<dd>The destination array.
1963 <dt>mask<dd>Operation mask, 8-bit single channel array; specifies elements of
1964 destination array to be changed.
1965 </dl><p>
1966 The function OrS calculates per-element bit-wise disjunction of array and scalar:</p>
1967 <pre>dst(I)=src(I)|value if mask(I)!=0</pre>
1968 <p>Prior to the actual operation the scalar is converted to the same type as
1969 the arrays. In the case of floating-point arrays their bit representations are used for the
1970 operation. All the arrays must have the same type, except the mask, and the same size</p>
1971
1972
1973 <hr><h3><a name="decl_cvXor">Xor</a></h3>
1974 <p class="Blurb">Performs per-element bit-wise "exclusive or" operation on two arrays</p>
1975 <pre>
1976 void cvXor( const CvArr* src1, const CvArr* src2, CvArr* dst, const CvArr* mask=NULL );
1977 </pre><p><dl>
1978 <dt>src1<dd>The first source array.
1979 <dt>src2<dd>The second source array.
1980 <dt>dst<dd>The destination array.
1981 <dt>mask<dd>Operation mask, 8-bit single channel array; specifies elements of
1982 destination array to be changed.
1983 </dl><p>
1984 The function <code>cvXor</code> calculates per-element bit-wise logical conjunction of two arrays:</p>
1985 <pre>dst(I)=src1(I)^src2(I) if mask(I)!=0</pre>
1986 <p>In the case of floating-point arrays their bit representations are used for the
1987 operation. All the arrays must have the same type, except the mask, and the same size</p>
1988
1989
1990 <hr><h3><a name="decl_cvXorS">XorS</a></h3>
1991 <p class="Blurb">Performs per-element bit-wise "exclusive or" operation on array and scalar</p>
1992 <pre>
1993 void cvXorS( const CvArr* src, CvScalar value, CvArr* dst, const CvArr* mask=NULL );
1994 </pre><p><dl>
1995 <dt>src<dd>The source array.
1996 <dt>value<dd>Scalar to use in the operation.
1997 <dt>dst<dd>The destination array.
1998 <dt>mask<dd>Operation mask, 8-bit single channel array; specifies elements of
1999 destination array to be changed.
2000 </dl><p>
2001 The function XorS calculates per-element bit-wise conjunction of array and scalar:</p>
2002 <pre>dst(I)=src(I)^value if mask(I)!=0</pre>
2003 <p>Prior to the actual operation the scalar is converted to the same type as
2004 the arrays. In the case of floating-point arrays their bit representations are used for the
2005 operation. All the arrays must have the same type, except the mask, and the same size</p>
2006
2007 <p>The following sample demonstrates how to conjugate complex vector
2008 by switching the most-significant bit of imaging part:</p>
2009 <pre>
2010 float a[] = { 1, 0, 0, 1, -1, 0, 0, -1 }; /* 1, j, -1, -j */
2011 CvMat A = cvMat( 4, 1, CV_32FC2, &amp;a );
2012 int i, neg_mask = 0x80000000;
2013 cvXorS( &amp;A, cvScalar( 0, *(float*)&amp;neg_mask, 0, 0 ), &amp;A, 0 );
2014 for( i = 0; i &lt; 4; i++ )
2015     printf("(%.1f, %.1f) ", a[i*2], a[i*2+1] );
2016 </pre>
2017 <p>The code should print:</p>
2018 <pre>(1.0,0.0) (0.0,-1.0) (-1.0,0.0) (0.0,1.0)</pre>
2019
2020
2021 <hr><h3><a name="decl_cvNot">Not</a></h3>
2022 <p class="Blurb">Performs per-element bit-wise inversion of array elements</p>
2023 <pre>
2024 void cvNot( const CvArr* src, CvArr* dst );
2025 </pre><p><dl>
2026 <dt>src1<dd>The source array.
2027 <dt>dst<dd>The destination array.
2028 </dl><p>
2029 The function Not inverses every bit of every array element:</p>
2030 <pre>dst(I)=~src(I)</pre>
2031
2032
2033 <hr><h3><a name="decl_cvCmp">Cmp</a></h3>
2034 <p class="Blurb">Performs per-element comparison of two arrays</p>
2035 <pre>
2036 void cvCmp( const CvArr* src1, const CvArr* src2, CvArr* dst, int cmp_op );
2037 </pre><p><dl>
2038 <dt>src1<dd>The first source array.
2039 <dt>src2<dd>The second source array. Both source array must have a single channel.
2040 <dt>dst<dd>The destination array, must have 8u or 8s type.
2041 <dt>cmp_op<dd>The flag specifying the relation between the elements to be checked:<br>
2042               CV_CMP_EQ - src1(I) "equal to" src2(I)<br>
2043               CV_CMP_GT - src1(I) "greater than" src2(I)<br>
2044               CV_CMP_GE - src1(I) "greater or equal" src2(I)<br>
2045               CV_CMP_LT - src1(I) "less than" src2(I)<br>
2046               CV_CMP_LE - src1(I) "less or equal" src2(I)<br>
2047               CV_CMP_NE - src1(I) "not equal to" src2(I)<br>
2048 </dl><p>
2049 The function <code>cvCmp</code> compares the corresponding elements of two arrays and
2050 fills the destination mask array:</p>
2051 <pre>
2052 dst(I)=src1(I) op src2(I),
2053 </pre>
2054 <p>where <code>op</code> is '=', '&gt;', '&gt;=', '&lt;', '&lt;=' or '!='.</p>
2055 <p><code>dst(I)</code> is set to 0xff (all '1'-bits) if the particular relation between the elements
2056 is true and 0 otherwise.
2057 All the arrays must have the same type, except the destination, and the same size (or ROI size)</p>
2058
2059
2060 <hr><h3><a name="decl_cvCmpS">CmpS</a></h3>
2061 <p class="Blurb">Performs per-element comparison of array and scalar</p>
2062 <pre>
2063 void cvCmpS( const CvArr* src, double value, CvArr* dst, int cmp_op );
2064 </pre><p><dl>
2065 <dt>src<dd>The source array, must have a single channel.
2066 <dt>value<dd>The scalar value to compare each array element with.
2067 <dt>dst<dd>The destination array, must have 8u or 8s type.
2068 <dt>cmp_op<dd>The flag specifying the relation between the elements to be checked:<br>
2069               CV_CMP_EQ - src1(I) "equal to" value<br>
2070               CV_CMP_GT - src1(I) "greater than" value<br>
2071               CV_CMP_GE - src1(I) "greater or equal" value<br>
2072               CV_CMP_LT - src1(I) "less than" value<br>
2073               CV_CMP_LE - src1(I) "less or equal" value<br>
2074               CV_CMP_NE - src1(I) "not equal" value<br>
2075 </dl><p>
2076 The function <code>cvCmpS</code> compares the corresponding elements of array and scalar
2077 and fills the destination mask array:</p>
2078 <pre>
2079 dst(I)=src(I) op scalar,
2080 </pre>
2081 <p>where <code>op</code> is '=', '&gt;', '&gt;=', '&lt;', '&lt;=' or '!='.</p>
2082 <p><code>dst(I)</code> is set to 0xff (all '1'-bits) if the particular relation between the elements
2083 is true and 0 otherwise.
2084 All the arrays must have the same size (or ROI size)</p>
2085
2086
2087
2088 <hr><h3><a name="decl_cvInRange">InRange</a></h3>
2089 <p class="Blurb">Checks that array elements lie between elements of two other arrays</p>
2090 <pre>
2091 void cvInRange( const CvArr* src, const CvArr* lower, const CvArr* upper, CvArr* dst );
2092 </pre><p><dl>
2093 <dt>src<dd>The first source array.
2094 <dt>lower<dd>The inclusive lower boundary array.
2095 <dt>upper<dd>The exclusive upper boundary array.
2096 <dt>dst<dd>The destination array, must have 8u or 8s type.
2097 </dl><p>
2098 The function <code>cvInRange</code> does the range check for every element of the input array:</p>
2099 <pre>
2100 dst(I)=lower(I)<sub>0</sub> &lt;= src(I)<sub>0</sub> &lt; upper(I)<sub>0</sub>
2101 </pre>
2102 <p>for single-channel arrays,</p>
2103 <pre>
2104 dst(I)=lower(I)<sub>0</sub> &lt;= src(I)<sub>0</sub> &lt; upper(I)<sub>0</sub> &amp;&amp;
2105      lower(I)<sub>1</sub> &lt;= src(I)<sub>1</sub> &lt; upper(I)<sub>1</sub>
2106 </pre><p>for two-channel arrays etc.</p>
2107 <p><code>dst(I)</code> is set to 0xff (all '1'-bits) if <code>src(I)</code> is within the range and 0 otherwise.
2108 All the arrays must have the same type, except the destination, and the same size (or ROI size)</p>
2109
2110
2111 <hr><h3><a name="decl_cvInRangeS">InRangeS</a></h3>
2112 <p class="Blurb">Checks that array elements lie between two scalars</p>
2113 <pre>
2114 void cvInRangeS( const CvArr* src, CvScalar lower, CvScalar upper, CvArr* dst );
2115 </pre><p><dl>
2116 <dt>src<dd>The first source array.
2117 <dt>lower<dd>The inclusive lower boundary.
2118 <dt>upper<dd>The exclusive upper boundary.
2119 <dt>dst<dd>The destination array, must have 8u or 8s type.
2120 </dl><p>
2121 The function <code>cvInRangeS</code> does the range check for every element of the input array:</p>
2122 <pre>
2123 dst(I)=lower<sub>0</sub> &lt;= src(I)<sub>0</sub> &lt; upper<sub>0</sub>
2124 </pre>
2125 <p>for a single-channel array,</p>
2126 <pre>
2127 dst(I)=lower<sub>0</sub> &lt;= src(I)<sub>0</sub> &lt; upper<sub>0</sub> &amp;&amp;
2128      lower<sub>1</sub> &lt;= src(I)<sub>1</sub> &lt; upper<sub>1</sub>
2129 </pre><p>for a two-channel array etc.</p>
2130 <p>
2131 <p><code>dst(I)</code> is set to 0xff (all '1'-bits) if <code>src(I)</code> is within the range and 0 otherwise.
2132 All the arrays must have the same size (or ROI size)</p>
2133
2134
2135 <hr><h3><a name="decl_cvMax">Max</a></h3>
2136 <p class="Blurb">Finds per-element maximum of two arrays</p>
2137 <pre>
2138 void cvMax( const CvArr* src1, const CvArr* src2, CvArr* dst );
2139 </pre><p><dl>
2140 <dt>src1<dd>The first source array.
2141 <dt>src2<dd>The second source array.
2142 <dt>dst<dd>The destination array.
2143 </dl><p>
2144 The function <code>cvMax</code> calculates per-element maximum of two arrays:</p>
2145 <pre>dst(I)=max(src1(I), src2(I))</pre>
2146 <p>All the arrays must have a single channel, the same data type
2147 and the same size (or ROI size).</p>
2148
2149
2150 <hr><h3><a name="decl_cvMaxS">MaxS</a></h3>
2151 <p class="Blurb">Finds per-element maximum of array and scalar</p>
2152 <pre>
2153 void cvMaxS( const CvArr* src, double value, CvArr* dst );
2154 </pre><p><dl>
2155 <dt>src<dd>The first source array.
2156 <dt>value<dd>The scalar value.
2157 <dt>dst<dd>The destination array.
2158 </dl><p>
2159 The function <code>cvMaxS</code> calculates per-element maximum of array and scalar:</p>
2160 <pre>dst(I)=max(src(I), value)</pre>
2161 <p>All the arrays must have a single channel, the same data type
2162 and the same size (or ROI size).</p>
2163
2164
2165 <hr><h3><a name="decl_cvMin">Min</a></h3>
2166 <p class="Blurb">Finds per-element minimum of two arrays</p>
2167 <pre>
2168 void cvMin( const CvArr* src1, const CvArr* src2, CvArr* dst );
2169 </pre><p><dl>
2170 <dt>src1<dd>The first source array.
2171 <dt>src2<dd>The second source array.
2172 <dt>dst<dd>The destination array.
2173 </dl><p>
2174 The function <code>cvMin</code> calculates per-element minimum of two arrays:</p>
2175 <pre>
2176 dst(I)=min(src1(I),src2(I))
2177 </pre>
2178 <p>All the arrays must have a single channel, the same data type
2179 and the same size (or ROI size).</p>
2180
2181
2182
2183 <hr><h3><a name="decl_cvMinS">MinS</a></h3>
2184 <p class="Blurb">Finds per-element minimum of array and scalar</p>
2185 <pre>
2186 void cvMinS( const CvArr* src, double value, CvArr* dst );
2187 </pre><p><dl>
2188 <dt>src<dd>The first source array.
2189 <dt>value<dd>The scalar value.
2190 <dt>dst<dd>The destination array.
2191 </dl><p>
2192 The function <code>cvMinS</code> calculates minimum of array and scalar:</p>
2193 <pre>dst(I)=min(src(I), value)</pre>
2194 <p>All the arrays must have a single channel, the same data type
2195 and the same size (or ROI size).</p>
2196
2197
2198 <hr><h3><a name="decl_cvAbsDiff">AbsDiff</a></h3>
2199 <p class="Blurb">Calculates absolute difference between two arrays</p>
2200 <pre>
2201 void cvAbsDiff( const CvArr* src1, const CvArr* src2, CvArr* dst );
2202 </pre><p><dl>
2203 <dt>src1<dd>The first source array.
2204 <dt>src2<dd>The second source array.
2205 <dt>dst<dd>The destination array.
2206 </dl><p>
2207 The function <code>cvAbsDiff</code> calculates absolute difference between two arrays.</p>
2208 <pre>dst(I)<sub>c</sub> = abs(src1(I)<sub>c</sub> - src2(I)<sub>c</sub>).</pre>
2209 <p>All the arrays must have the same data type and the same size (or ROI size).</p>
2210
2211
2212 <hr><h3><a name="decl_cvAbsDiffS">AbsDiffS</a></h3>
2213 <p class="Blurb">Calculates absolute difference between array and scalar</p>
2214 <pre>
2215 void cvAbsDiffS( const CvArr* src, CvArr* dst, CvScalar value );
2216 #define cvAbs(src, dst) cvAbsDiffS(src, dst, cvScalarAll(0))
2217 </pre><p><dl>
2218 <dt>src<dd>The source array.
2219 <dt>dst<dd>The destination array.
2220 <dt>value<dd>The scalar.
2221 </dl><p>
2222 The function <code>cvAbsDiffS</code> calculates absolute difference between array and scalar.</p>
2223 <pre>dst(I)<sub>c</sub> = abs(src(I)<sub>c</sub> - value<sub>c</sub>).</pre>
2224 <p>All the arrays must have the same data type and the same size (or ROI size).</p>
2225
2226
2227 <hr><h2><a name="cxcore_arrays_stat">Statistics</a></h2>
2228
2229 <hr><h3><a name="decl_cvCountNonZero">CountNonZero</a></h3>
2230 <p class="Blurb">Counts non-zero array elements</p>
2231 <pre>
2232 int cvCountNonZero( const CvArr* arr );
2233 </pre><p><dl>
2234 <dt>arr<dd>The array, must be single-channel array or multi-channel image with COI set.
2235 </dl><p>
2236 The function <code>cvCountNonZero</code> returns the number of non-zero elements in src1:</p>
2237 <pre>
2238 result = sum<sub>I</sub> arr(I)!=0
2239 </pre>
2240 In case of <code>IplImage</code> both ROI and COI are supported.</p>
2241
2242
2243 <hr><h3><a name="decl_cvSum">Sum</a></h3>
2244 <p class="Blurb">Summarizes array elements</p>
2245 <pre>
2246 CvScalar cvSum( const CvArr* arr );
2247 </pre><p><dl>
2248 <dt>arr<dd>The array.
2249 </dl><p>
2250 The function <code>cvSum</code> calculates sum <code>S</code> of array elements, independently for each channel:</p>
2251 <pre>
2252 S<sub>c</sub> = sum<sub>I</sub> arr(I)<sub>c</sub>
2253 </pre>
2254 If the array is <code>IplImage</code> and COI is set, the function processes the selected channel only
2255 and stores the sum to the first scalar component (S<sub>0</sub>).</p>
2256
2257
2258 <hr><h3><a name="decl_cvAvg">Avg</a></h3>
2259 <p class="Blurb">Calculates average (mean) of array elements</p>
2260 <pre>
2261 CvScalar cvAvg( const CvArr* arr, const CvArr* mask=NULL );
2262 </pre><p><dl>
2263 <dt>arr<dd>The array.
2264 <dt>mask<dd>The optional operation mask.
2265 </dl><p>
2266 The function <code>cvAvg</code> calculates the average value <code>M</code> of array elements, independently for each channel:</p>
2267 <pre>
2268 N = sum<sub>I</sub> mask(I)!=0
2269
2270 M<sub>c</sub> = 1/N &bull; sum<sub>I,mask(I)!=0</sub> arr(I)<sub>c</sub>
2271 </pre>
2272 If the array is <code>IplImage</code> and COI is set, the function processes the selected channel only
2273 and stores the average to the first scalar component (S<sub>0</sub>).</p>
2274
2275
2276 <hr><h3><a name="decl_cvAvgSdv">AvgSdv</a></h3>
2277 <p class="Blurb">Calculates average (mean) of array elements</p>
2278 <pre>
2279 void cvAvgSdv( const CvArr* arr, CvScalar* mean, CvScalar* std_dev, const CvArr* mask=NULL );
2280 </pre><p><dl>
2281 <dt>arr<dd>The array.
2282 <dt>mean<dd>Pointer to the mean value, may be NULL if it is not needed.
2283 <dt>std_dev<dd>Pointer to the standard deviation.
2284 <dt>mask<dd>The optional operation mask.
2285 </dl><p>
2286 The function <code>cvAvgSdv</code> calculates the average value and
2287 standard deviation of array elements, independently for each channel:</p>
2288 <pre>
2289 N = sum<sub>I</sub> mask(I)!=0
2290
2291 mean<sub>c</sub> = 1/N &bull; sum<sub>I,mask(I)!=0</sub> arr(I)<sub>c</sub>
2292
2293 std_dev<sub>c</sub> = sqrt(1/N &bull; sum<sub>I,mask(I)!=0</sub> (arr(I)<sub>c</sub> - M<sub>c</sub>)<sup>2</sup>)
2294 </pre>
2295 If the array is <code>IplImage</code> and COI is set, the function processes the selected channel only
2296 and stores the average and standard deviation to the first components of output scalars (M<sub>0</sub>
2297 and S<sub>0</sub>).</p>
2298
2299
2300
2301 <hr><h3><a name="decl_cvMinMaxLoc">MinMaxLoc</a></h3>
2302 <p class="Blurb">Finds global minimum and maximum in array or subarray</p>
2303 <pre>
2304 void cvMinMaxLoc( const CvArr* arr, double* min_val, double* max_val,
2305                   CvPoint* min_loc=NULL, CvPoint* max_loc=NULL, const CvArr* mask=NULL );
2306 </pre><p><dl>
2307 <dt>arr<dd>The source array, single-channel or multi-channel with COI set.
2308 <dt>min_val<dd>Pointer to returned minimum value.
2309 <dt>max_val<dd>Pointer to returned maximum value.
2310 <dt>min_loc<dd>Pointer to returned minimum location.
2311 <dt>max_loc<dd>Pointer to returned maximum location.
2312 <dt>mask<dd>The optional mask that is used to select a subarray.
2313 </dl><p>
2314 The function <code>MinMaxLoc</code> finds minimum and maximum element values and their
2315 positions. The extremums are searched over the whole array, selected <code>ROI</code> (in case
2316 of <code>IplImage</code>) or, if <code>mask</code> is not <code>NULL</code>, in the specified array region.
2317 If the array has more than one channel, it must be <code>IplImage</code> with <code>COI</code> set.
2318 In case if multi-dimensional arrays <code>min_loc->x</code> and <code>max_loc->x</code> will contain raw (linear)
2319 positions of the extremums.</p>
2320
2321
2322 <hr><h3><a name="decl_cvNorm">Norm</a></h3>
2323 <p class="Blurb">Calculates absolute array norm, absolute difference norm or relative difference norm</p>
2324 <pre>
2325 double cvNorm( const CvArr* arr1, const CvArr* arr2=NULL, int norm_type=CV_L2, const CvArr* mask=NULL );
2326 </pre><p><dl>
2327 <dt>arr1<dd>The first source image.
2328 <dt>arr2<dd>The second source image. If it is NULL, the absolute norm of <code>arr1</code> is calculated, otherwise
2329          absolute or relative norm of <code>arr1</code>-<code>arr2</code> is calculated.
2330 <dt>normType<dd>Type of norm, see the discussion.
2331 <dt>mask<dd>The optional operation mask.
2332 </dl><p>
2333 The function <code>cvNorm</code> calculates the absolute norm of <code>arr1</code> if <code>arr2</code> is NULL:</p>
2334 <pre>
2335 norm = ||arr1||<sub>C</sub> = max<sub>I</sub> abs(arr1(I)),  if <code>normType</code> = CV_C
2336
2337 norm = ||arr1||<sub>L1</sub> = sum<sub>I</sub> abs(arr1(I)),  if <code>normType</code> = CV_L1
2338
2339 norm = ||arr1||<sub>L2</sub> = sqrt( sum<sub>I</sub> arr1(I)<sup>2</sup>),  if <code>normType</code> = CV_L2
2340
2341 </pre>
2342 <p>And the function calculates absolute or relative difference norm if <code>arr2</code> is not NULL:</p>
2343 <pre>
2344 norm = ||arr1-arr2||<sub>C</sub> = max<sub>I</sub> abs(arr1(I)-arr2(I)),  if <code>normType</code> = CV_C
2345
2346 norm = ||arr1-arr2||<sub>L1</sub> = sum<sub>I</sub> abs(arr1(I)-arr2(I)),  if <code>normType</code> = CV_L1
2347
2348 norm = ||arr1-arr2||<sub>L2</sub> = sqrt( sum<sub>I</sub> (arr1(I)-arr2(I))<sup>2</sup> ),  if <code>normType</code> = CV_L2
2349
2350 or
2351
2352 norm = ||arr1-arr2||<sub>C</sub>/||arr2||<sub>C</sub>, if <code>normType</code> = CV_RELATIVE_C
2353
2354 norm = ||arr1-arr2||<sub>L1</sub>/||arr2||<sub>L1</sub>, if <code>normType</code> = CV_RELATIVE_L1
2355
2356 norm = ||arr1-arr2||<sub>L2</sub>/||arr2||<sub>L2</sub>, if <code>normType</code> = CV_RELATIVE_L2
2357
2358 </pre>
2359 <p>
2360 The function<code> Norm</code> returns the calculated norm.
2361 The multiple-channel array are treated as single-channel, that is, the results for all channels
2362 are combined.
2363 </p>
2364
2365
2366 <hr><h3><a name="decl_cvReduce">Reduce</a></h3>
2367 <p class="Blurb">Reduces matrix to a vector</p>
2368 <pre>
2369 void cvReduce( const CvArr* src, CvArr* dst, int op=CV_REDUCE_SUM );
2370 </pre><p><dl>
2371 <dt>src<dd>The input matrix.
2372 <dt>dst<dd>The output single-row/single-column vector that accumulates
2373            somehow all the matrix rows/columns.
2374 <dt>dim<dd>The dimension index along which the matrix is reduce.
2375            0 means that the matrix is reduced to a single row,
2376            1 means that the matrix is reduced to a single column.
2377            -1 means that the dimension is chosen automatically by analysing the <code>dst</code> size.
2378 <dt>op<dd>The reduction operation. It can take of the following values:<br>
2379            <code>CV_REDUCE_SUM</code> - the output is the sum of all the matrix rows/columns.<br>
2380            <code>CV_REDUCE_AVG</code> - the output is the mean vector of all the matrix rows/columns.<br>
2381            <code>CV_REDUCE_MAX</code> - the output is the maximum (column/row-wise) of all the matrix rows/columns.<br>
2382            <code>CV_REDUCE_MIN</code> - the output is the minimum (column/row-wise) of all the matrix rows/columns.<br>
2383 </dl><p>
2384 The function <code>cvReduce</code> reduces matrix to a vector by treating the matrix rows/columns as a set
2385 of 1D vectors and performing the specified operation on the vectors until a single row/column is obtained.
2386 For example, the function can be used to compute horizontal and vertical projections of an raster image.
2387 In case of <code>CV_REDUCE_SUM</code> and <code>CV_REDUCE_AVG</code> the output may have a larger
2388 element bit-depth to preserve accuracy. And multi-channel arrays are also supported in these two reduction modes.
2389 </p>
2390
2391
2392 <!-- *****************************************************************************************
2393      *****************************************************************************************
2394      ***************************************************************************************** -->
2395
2396 <hr><h2><a name="cxcore_arrays_matrix">Linear Algebra</a></h2>
2397
2398 <hr><h3><a name="decl_cvDotProduct">DotProduct</a></h3>
2399 <p class="Blurb">Calculates dot product of two arrays in Euclidean metrics</p>
2400 <pre>
2401 double cvDotProduct( const CvArr* src1, const CvArr* src2 );
2402 </pre><p><dl>
2403 <dt>src1<dd>The first source array.
2404 <dt>src2<dd>The second source array.
2405 </dl><p>
2406 The function <code>cvDotProduct</code> calculates and returns the Euclidean dot product of two
2407 arrays.</p>
2408 <pre>src1&bull;src2 = sum<sub>I</sub>(src1(I)*src2(I))
2409 </pre>
2410 <p>In case of multiple channel arrays the results for all channels are
2411 accumulated. In particular, <code><a href="#decl_cvDotProduct">cvDotProduct</a>(a,a)</code>,
2412 where <code>a</code> is a complex vector, will return <code>||a||<sup>2</sup></code>.
2413 The function can process multi-dimensional arrays, row by row, layer by layer and so on.</p>
2414
2415
2416 <hr><h3><a name="decl_cvNormalize">Normalize</a></h3>
2417 <p class="Blurb">Normalizes array to a certain norm or value range</p>
2418 <pre>
2419 void cvNormalize( const CvArr* src, CvArr* dst,
2420                   double a=1, double b=0, int norm_type=CV_L2,
2421                   const CvArr* mask=NULL );
2422 </pre><p><dl>
2423 <dt>src<dd>The input array.
2424 <dt>dst<dd>The output array; in-place operation is supported.
2425 <dt>a<dd>The minimum/maximum value of the output array or the norm of output array.
2426 <dt>b<dd>The maximum/minimum value of the output array.
2427 <dt>norm_type<dd>The normalization type. It can take one of the following values:<br>
2428     <code>CV_C</code> - the C-norm (maximum of absolute values) of the array is normalized.<br>
2429     <code>CV_L1</code> - the L<sub>1</sub>-norm (sum of absolute values) of the array is normalized.<br>
2430     <code>CV_L2</code> - the (Euclidean) L<sub>2</sub>-norm of the array is normalized.<br>
2431     <code>CV_MINMAX</code> - the array values are scaled and shifted to the specified range.<br>
2432 <dt>mask<dd>The operation mask. Makes the function consider and normalize only certain array elements.
2433 </dl><p>
2434 The function <code>cvNormalize</code> normalizes the input array so that it's norm or value
2435 range takes the certain value(s).</p>
2436 <p>When <code>norm_type==CV_MINMAX</code>:
2437 <pre>
2438     dst(i,j)=(src(i,j)-min(src))*(b'-a')/(max(src)-min(src)) + a',  if mask(i,j)!=0
2439     dst(i,j)=src(i,j)  otherwise
2440 </pre>
2441 where <code>b'=MAX(a,b)</code>, <code>a'=MIN(a,b)</code>;<br>
2442 <code>min(src)</code> and <code>max(src)</code> are the global minimum and maximum, respectively,
2443 of the input array, computed over the whole array or the specified subset of it.
2444 <p>When <code>norm_type!=CV_MINMAX</code>:
2445 <pre>
2446     dst(i,j)=src(i,j)*a/<a href="#decl_cvNorm">cvNorm</a>(src,0,norm_type,mask), if mask(i,j)!=0
2447     dst(i,j)=src(i,j)  otherwise
2448 </pre>
2449 <p>Here is the short example:</p>
2450 <pre>
2451 float v[3] = { 1, 2, 3 };
2452 CvMat V = cvMat( 1, 3, CV_32F, v );
2453
2454 // make vector v unit-length;
2455 // equivalent to
2456 //   for(int i=0;i&lt;3;i++) v[i]/=sqrt(v[0]*v[0]+v[1]*v[1]+v[2]*v[2]);
2457 cvNormalize( &V, &V );
2458 </pre>
2459
2460 <hr><h3><a name="decl_cvCrossProduct">CrossProduct</a></h3>
2461 <p class="Blurb">Calculates cross product of two 3D vectors</p>
2462 <pre>
2463 void cvCrossProduct( const CvArr* src1, const CvArr* src2, CvArr* dst );
2464 </pre><p><dl>
2465 <dt>src1<dd>The first source vector.
2466 <dt>src2<dd>The second source vector.
2467 <dt>dst<dd>The destination vector.
2468 </dl><p>
2469 The function <code>cvCrossProduct</code> calculates the cross product of two 3D vectors:</p>
2470 <pre>dst = src1 &times; src2, (dst<sub>1</sub> = src1<sub>2</sub>src2<sub>3</sub> - src1<sub>3</sub>src2<sub>2</sub> , dst<sub>2</sub> = src1<sub>3</sub>src2<sub>1</sub> - src1<sub>1</sub>src2<sub>3</sub> , dst<sub>3</sub> = src1<sub>1</sub>src2<sub>2</sub> - src1<sub>2</sub>src2<sub>1</sub>).</pre>
2471
2472
2473 <hr><h3><a name="decl_cvScaleAdd">ScaleAdd</a></h3>
2474 <p class="Blurb">Calculates sum of scaled array and another array</p>
2475 <pre>
2476 void cvScaleAdd( const CvArr* src1, CvScalar scale, const CvArr* src2, CvArr* dst );
2477 #define cvMulAddS cvScaleAdd
2478 </pre><p><dl>
2479 <dt>src1<dd>The first source array.
2480 <dt>scale<dd>Scale factor for the first array.
2481 <dt>src2<dd>The second source array.
2482 <dt>dst<dd>The destination array
2483 </dl><p>
2484 The function <code>cvScaleAdd</code> calculates sum of scaled array and another array:</p>
2485 <pre>dst(I)=src1(I)*scale + src2(I)</pre>
2486 <p>All array parameters should have the same type and the same size.</p>
2487
2488
2489 <hr><h3><a name="decl_cvGEMM">GEMM</a></h3>
2490 <p class="Blurb">Performs generalized matrix multiplication</p>
2491 <pre>
2492 void  cvGEMM( const CvArr* src1, const CvArr* src2, double alpha,
2493               const CvArr* src3, double beta, CvArr* dst, int tABC=0 );
2494 #define cvMatMulAdd( src1, src2, src3, dst ) cvGEMM( src1, src2, 1, src3, 1, dst, 0 )
2495 #define cvMatMul( src1, src2, dst ) cvMatMulAdd( src1, src2, 0, dst )
2496 </pre><p><dl>
2497 <dt>src1<dd>The first source array.
2498 <dt>src2<dd>The second source array.
2499 <dt>src3<dd>The third source array (shift). Can be NULL, if there is no shift.
2500 <dt>dst<dd>The destination array.
2501 <dt>tABC<dd>The operation flags that can be 0 or combination of the following values:<br>
2502             CV_GEMM_A_T - transpose src1<br>
2503             CV_GEMM_B_T - transpose src2<br>
2504             CV_GEMM_C_T - transpose src3<br>
2505             for example, CV_GEMM_A_T+CV_GEMM_C_T corresponds to
2506             <pre>alpha*src1<sup>T</sup>*src2 + beta*src<sup>T</sup></pre>
2507 </dl><p>
2508 The function <code>cvGEMM</code> performs generalized matrix multiplication:</p>
2509 <pre>dst = alpha*op(src1)*op(src2) + beta*op(src3), where op(X) is X or X<sup>T</sup></pre>
2510 <p>
2511 All the matrices should have the same data type and the coordinated sizes.
2512 Real or complex floating-point matrices are supported</p>
2513
2514
2515 <hr><h3><a name="decl_cvTransform">Transform</a></h3>
2516 <p class="Blurb">Performs matrix transform of every array element</p>
2517 <pre>
2518 void cvTransform( const CvArr* src, CvArr* dst, const CvMat* transmat, const CvMat* shiftvec=NULL );
2519 </pre><p><dl>
2520 <dt>src<dd>The first source array.
2521 <dt>dst<dd>The destination array.
2522 <dt>transmat<dd>Transformation matrix.
2523 <dt>shiftvec<dd>Optional shift vector.
2524 </dl><p>
2525 The function <code>cvTransform</code> performs matrix transformation of every element of array <code>src</code>
2526 and stores the results in <code>dst</code>:</p>
2527 <pre>dst(I)=transmat*src(I) + shiftvec   or   dst(I)<sub>k</sub>=sum<sub>j</sub>(transmat(k,j)*src(I)<sub>j</sub>) + shiftvec(k)</pre>
2528 <p>That is every element of <code>N</code>-channel array <code>src</code> is considered as <code>N</code>-element vector, which is
2529 transformed using matrix <code>M</code>&times;<code>N</code> matrix <code>transmat</code> and shift vector <code>shiftvec</code>
2530 into an element of <code>M</code>-channel array <code>dst</code>.
2531 There is an option to embed <code>shiftvec</code> into <code>transmat</code>. In this case <code>transmat</code> should be
2532 <code>M</code>&times;<code>N+1</code> matrix and the right-most column is treated as the shift vector.</p>
2533 <p>
2534 Both source and destination arrays should have the same depth and the same size or selected ROI
2535 size. <code>transmat</code> and <code>shiftvec</code> should be real floating-point matrices.
2536 <p>The function may be used for geometrical transformation of <code>N</code>D point set,
2537 arbitrary linear color space transformation, shuffling the channels etc.
2538 </p>
2539
2540 <hr><h3><a name="decl_cvPerspectiveTransform">PerspectiveTransform</a></h3>
2541 <p class="Blurb">Performs perspective matrix transform of vector array</p>
2542 <pre>
2543 void cvPerspectiveTransform( const CvArr* src, CvArr* dst, const CvMat* mat );
2544 </pre><p><dl>
2545 <dt>src<dd>The source three-channel floating-point array.
2546 <dt>dst<dd>The destination three-channel floating-point array.
2547 <dt>mat<dd>3&times;3 or 4&times;4 transformation matrix.
2548 </dl><p>
2549 The function <code>cvPerspectiveTransform</code> transforms every element of <code>src</code>
2550 (by treating it as 2D or 3D vector) in the following way:</p>
2551 <pre>
2552 (x, y, z) -> (x&#146;/w, y&#146;/w, z&#146;/w) or
2553 (x, y) -> (x&#146;/w, y&#146;/w),
2554
2555 where
2556 (x&#146;, y&#146;, z&#146;, w&#146;) = mat4x4*(x, y, z, 1) or
2557 (x&#146;, y&#146;, w&#146;) = mat3x3*(x, y, 1)
2558
2559 and w = w&#146;   if w&#146;!=0,
2560         inf  otherwise
2561 </pre>
2562
2563
2564 <hr><h3><a name="decl_cvMulTransposed">MulTransposed</a></h3>
2565 <p class="Blurb">Calculates product of array and transposed array</p>
2566 <pre>
2567 void cvMulTransposed( const CvArr* src, CvArr* dst, int order, const CvArr* delta=NULL );
2568 </pre><p><dl>
2569 <dt>src<dd>The source matrix.
2570 <dt>dst<dd>The destination matrix.
2571 <dt>order<dd>Order of multipliers.
2572 <dt>delta<dd>An optional array, subtracted from <code>src</code> before multiplication.
2573 </dl><p>
2574 The function <code>cvMulTransposed</code> calculates the product of src and its transposition.</p>
2575 <p>The function evaluates</p>
2576 <pre>dst=(src-delta)*(src-delta)<sup>T</sup></pre>
2577 <p>if order=0, and
2578 <pre>dst=(src-delta)<sup>T</sup>*(src-delta)</pre>
2579 <p>otherwise.</p>
2580
2581
2582 <hr><h3><a name="decl_cvTrace">Trace</a></h3>
2583 <p class="Blurb">Returns trace of matrix</p>
2584 <pre>
2585 CvScalar cvTrace( const CvArr* mat );
2586 </pre><p><dl>
2587 <dt>mat<dd>The source matrix.
2588 </dl><p>
2589 The function <code>cvTrace</code> returns sum of diagonal elements of the matrix <code>src1</code>.
2590 <pre>
2591 tr(src1)=sum<sub>i</sub>mat(i,i)
2592 </pre>
2593
2594
2595 <hr><h3><a name="decl_cvTranspose">Transpose</a></h3>
2596 <p class="Blurb">Transposes matrix</p>
2597 <pre>
2598 void cvTranspose( const CvArr* src, CvArr* dst );
2599 #define cvT cvTranspose
2600 </pre><p><dl>
2601 <dt>src<dd>The source matrix.
2602 <dt>dst<dd>The destination matrix.
2603 </dl><p>
2604 The function <code>cvTranspose</code> transposes matrix <code>src1</code>:</p>
2605 <pre>
2606 dst(i,j)=src(j,i)
2607 </pre>
2608 <p>Note that no complex conjugation is done in case of complex matrix. Conjugation
2609 should be done separately: look at the sample code in <a href="#decl_cvXorS">cvXorS</a> for example</p>
2610
2611
2612 <hr><h3><a name="decl_cvDet">Det</a></h3>
2613 <p class="Blurb">Returns determinant of matrix</p>
2614 <pre>
2615 double cvDet( const CvArr* mat );
2616 </pre><p><dl>
2617 <dt>mat<dd>The source matrix.
2618 </dl><p>
2619 The function <code>cvDet</code> returns determinant of the square matrix <code>mat</code>.
2620 The direct method is used for small matrices and Gaussian elimination is used for larger matrices.
2621 For symmetric positive-determined matrices it is also possible to run <a href="#decl_cvSVD">SVD</a>
2622 with <code>U=V=NULL</code> and then calculate determinant as a product of the diagonal elements of <code>W</code></p>
2623
2624
2625 <hr><h3><a name="decl_cvInvert">Invert</a></h3>
2626 <p class="Blurb">Finds inverse or pseudo-inverse of matrix</p>
2627 <pre>
2628 double cvInvert( const CvArr* src, CvArr* dst, int method=CV_LU );
2629 #define cvInv cvInvert
2630 </pre><p><dl>
2631 <dt>src<dd>The source matrix.
2632 <dt>dst<dd>The destination matrix.
2633 <dt>method<dd>Inversion method:<br>
2634               CV_LU - Gaussian elimination with optimal pivot element chose<br>
2635               CV_SVD - Singular value decomposition (SVD) method<br>
2636               CV_SVD_SYM - SVD method for a symmetric positively-defined matrix<br>
2637 </dl><p>
2638 The function <code>cvInvert</code> inverts matrix <code>src1</code> and stores the result in <code>src2</code></p>
2639 <p>In case of <code>LU</code> method the function returns <code>src1</code> determinant (src1 must be square).
2640 If it is 0, the matrix is not inverted and <code>src2</code> is filled with zeros.</p>
2641 <p>In case of <code>SVD</code> methods the function returns the inverted condition number of <code>src1</code>
2642 (ratio of the smallest singular value to the largest singular value) and 0 if <code>src1</code> is all zeros.
2643 The SVD methods calculate a pseudo-inverse matrix if <code>src1</code> is singular</p>
2644
2645
2646 <hr><h3><a name="decl_cvSolve">Solve</a></h3>
2647 <p class="Blurb">Solves linear system or least-squares problem</p>
2648 <pre>
2649 int cvSolve( const CvArr* A, const CvArr* B, CvArr* X, int method=CV_LU );
2650 </pre><p><dl>
2651 <dt>A<dd>The source matrix.
2652 <dt>B<dd>The right-hand part of the linear system.
2653 <dt>X<dd>The output solution.
2654 <dt>method<dd>The solution (matrix inversion) method:<br>
2655               CV_LU - Gaussian elimination with optimal pivot element chose<br>
2656               CV_SVD - Singular value decomposition (SVD) method<br>
2657               CV_SVD_SYM - SVD method for a symmetric positively-defined matrix.
2658 </dl><p>
2659 The function <code>cvSolve</code> solves linear system or least-squares problem (the latter
2660 is possible with SVD methods):</p>
2661 <pre>
2662 dst = arg min<sub>X</sub>||A*X-B||
2663 </pre>
2664 <p>If <code>CV_LU</code> method is used, the function returns 1 if <code>src1</code> is non-singular and
2665 0 otherwise, in the latter case <code>dst</code> is not valid</p>
2666
2667
2668 <hr><h3><a name="decl_cvSVD">SVD</a></h3>
2669 <p class="Blurb">Performs singular value decomposition of real floating-point matrix</p>
2670 <pre>
2671 void cvSVD( CvArr* A, CvArr* W, CvArr* U=NULL, CvArr* V=NULL, int flags=0 );
2672 </pre><p><dl>
2673
2674 <dt>A<dd>Source <code>M</code>&times;<code>N</code> matrix.
2675 <dt>W<dd>Resulting singular value matrix (<code>M</code>&times;<code>N</code> or <code>N</code>&times;<code>N</code>) or
2676          vector (<code>N</code>&times;<code>1</code>).
2677 <dt>U<dd>Optional left orthogonal matrix (<code>M</code>&times;<code>M</code> or <code>M</code>&times;<code>N</code>).
2678          If CV_SVD_U_T is specified, the number of rows and columns in the sentence above should be swapped.
2679 <dt>V<dd>Optional right orthogonal matrix (<code>N</code>&times;<code>N</code>)
2680 <dt>flags<dd>Operation flags; can be 0 or combination of the following values:
2681 <ul>
2682 <li>  <code>CV_SVD_MODIFY_A</code> enables modification of matrix <code>src1</code> during the operation. It
2683   speeds up the processing.
2684 <li>  <code>CV_SVD_U_T</code> means that the transposed matrix <code>U</code> is returned.
2685       Specifying the flag speeds up the processing.
2686 <li>  <code>CV_SVD_V_T</code> means that the transposed matrix <code>V</code> is returned.
2687       Specifying the flag speeds up the processing.
2688 </ul>
2689 </dl><p>
2690 The function <code>cvSVD</code> decomposes matrix <code>A</code> into a product of a diagonal matrix and two
2691 orthogonal matrices:</p>
2692 <pre>
2693 A=U*W*V<sup>T</sup>
2694 </pre>
2695 <p>Where <code>W</code> is diagonal matrix of singular values that can be coded as a 1D
2696 vector of singular values and <code>U</code> and <code>V</code>. All the singular values are non-negative and sorted (together with <code>U</code> and
2697 and <code>V</code> columns) in descending order.</p>
2698 <p>SVD algorithm is numerically robust and its typical applications include:
2699 <ul>
2700 <li>accurate eigenvalue problem solution when matrix <code>A</code> is square, symmetric and positively
2701   defined matrix, for example, when it is a covariation matrix.
2702   <code>W</code> in this case will be a vector of eigenvalues, and <code>U</code>=<code>V</code> is matrix of
2703   eigenvectors (thus, only one of <code>U</code> or <code>V</code> needs to be calculated if
2704   the eigenvectors are required)</li>
2705 <li>accurate solution of poor-conditioned linear systems</li>
2706 <li>least-squares solution of overdetermined linear systems. This and previous is done by <a href="#decl_cvSolve">cvSolve</a>
2707     function with <code>CV_SVD</code> method</li>
2708 <li>accurate calculation of different matrix characteristics such as rank
2709    (number of non-zero singular values),
2710   condition number (ratio of the largest singular value to the smallest one),
2711   determinant (absolute value of determinant is equal to the product of singular values).
2712   All the things listed in this item do not require calculation of <code>U</code>
2713   and <code>V</code> matrices.</li>
2714 </ul></p>
2715
2716
2717
2718 <hr><h3><a name="decl_cvSVBkSb">SVBkSb</a></h3>
2719 <p class="Blurb">Performs singular value back substitution</p>
2720 <pre>
2721 void  cvSVBkSb( const CvArr* W, const CvArr* U, const CvArr* V,
2722                 const CvArr* B, CvArr* X, int flags );
2723 </pre><p><dl>
2724
2725 <dt>W<dd>Matrix or vector of singular values.
2726 <dt>U<dd>Left orthogonal matrix (transposed, perhaps)
2727 <dt>V<dd>Right orthogonal matrix (transposed, perhaps)
2728 <dt>B<dd>The matrix to multiply the pseudo-inverse of the original matrix <code>A</code> by.
2729          This is the optional parameter. If it is omitted then it is assumed to be
2730          an identity matrix of an appropriate size (So <code>X</code> will be the reconstructed
2731          pseudo-inverse of <code>A</code>).
2732 <dt>X<dd>The destination matrix: result of back substitution.
2733 <dt>flags<dd>Operation flags, should match exactly to the <code>flags</code> passed to <a href="#decl_cvSVD">cvSVD</a>.
2734 </dl><p>
2735 The function <code>cvSVBkSb</code> calculates back substitution for decomposed matrix <code>A</code> (see
2736 <a href="#decl_cvSVD">cvSVD</a> description) and matrix <code>B</code>:</p>
2737 <pre>
2738 X=V*W<sup>-1</sup>*U<sup>T</sup>*B
2739 </pre>
2740 <p>Where</p>
2741 <pre>
2742 W<sup>-1</sup>(i,i)=1/W(i,i) if W(i,i) > epsilon&bull;sum<sub>i</sub>W(i,i),
2743                     0        otherwise
2744 </pre>
2745 <p>And <code>epsilon</code> is a small number that depends on the matrix data type.
2746 </p>
2747 This function together with <a href="#decl_cvSVD">cvSVD</a> is used inside <a href="#decl_cvInvert">cvInvert</a> and <a href="#decl_cvSolve">cvSolve</a>,
2748 and the possible reason to use these (svd &amp; bksb) "low-level" function is to avoid
2749 temporary matrices allocation inside the high-level counterparts (inv &amp; solve).</p>
2750
2751
2752 <hr><h3><a name="decl_cvEigenVV">EigenVV</a></h3>
2753 <p class="Blurb">Computes eigenvalues and eigenvectors of symmetric matrix</p>
2754 <pre>
2755 void cvEigenVV( CvArr* mat, CvArr* evects, CvArr* evals, double eps=0 );
2756 </pre><p><dl>
2757 <dt>mat<dd>The input symmetric square matrix. It is modified during the processing.
2758 <dt>evects<dd>The output matrix of eigenvectors, stored as a subsequent rows.
2759 <dt>evals<dd>The output vector of eigenvalues, stored in the descending order (order of
2760 eigenvalues and eigenvectors is synchronized, of course).
2761 <dt>eps<dd>Accuracy of diagonalization (typically, DBL_EPSILON=&asymp;10<sup>-15</sup> is enough).
2762 </dl><p>
2763 The function <code>cvEigenVV</code> computes the eigenvalues and eigenvectors of the matrix <code>A</code>:</p>
2764 <pre>mat*evects(i,:)' = evals(i)*evects(i,:)' (in MATLAB notation)</pre>
2765 <p>The contents of matrix <code>A</code> is destroyed by the function.</p>
2766 <p>Currently the function is slower than <a href="#decl_cvSVD">cvSVD</a> yet less accurate,
2767 so if <code>A</code> is known to be positively-defined (for example, it is a covariation matrix),
2768 it is recommended to use <a href="#decl_cvSVD">cvSVD</a> to find eigenvalues and eigenvectors of <code>A</code>,
2769 especially if eigenvectors are not required. That is, instead of
2770 <pre>
2771 cvEigenVV(mat, eigenvals, eigenvects);
2772 </pre>
2773 call
2774 <pre>
2775 cvSVD(mat, eigenvals, eigenvects, 0, CV_SVD_U_T + CV_SVD_MODIFY_A);
2776 </pre>
2777 </p>
2778
2779
2780 <hr><h3><a name="decl_cvCalcCovarMatrix">CalcCovarMatrix</a></h3>
2781 <p class="Blurb">Calculates covariation matrix of the set of vectors</p>
2782 <pre>
2783 void cvCalcCovarMatrix( const CvArr** vects, int count, CvArr* cov_mat, CvArr* avg, int flags );
2784 </pre><p><dl>
2785 <dt>vects<dd>The input vectors. They all must have the same type and the same size.
2786              The vectors do not have to be 1D, they can be 2D (e.g. images) etc.
2787 <dt>count<dd>The number of input vectors.
2788 <dt>cov_mat<dd>The output covariation matrix that should be floating-point and square.
2789 <dt>avg<dd>The input or output (depending on the flags) array - the mean (average) vector of the input vectors.
2790 <dt>flags<dd>The operation flags, a combination of the following values:<br>
2791                  <code>CV_COVAR_SCRAMBLED</code> - the output covariation matrix is calculated as:<br>
2792                        <code>scale*[vects[0]-avg,vects[1]-avg,...]<sup>T</sup>*[vects[0]-avg,vects[1]-avg,...]</code>,<br>
2793                        that is, the covariation matrix is <code>count</code>&times;<code>count</code>. Such an unusual
2794                        covariation matrix is used for fast PCA of a set of very large vectors
2795                        (see, for example, Eigen Faces technique for face recognition). Eigenvalues of this
2796                        "scrambled" matrix will match to the eigenvalues of the true covariation matrix and
2797                        the "true" eigenvectors can be easily calculated from the eigenvectors of the "scrambled" covariation
2798                        matrix.<br>
2799                  <code>CV_COVAR_NORMAL</code> - the output covariation matrix is calculated as:<br>
2800                        <code>scale*[vects[0]-avg,vects[1]-avg,...]*[vects[0]-avg,vects[1]-avg,...]<sup>T</sup></code>,<br>
2801                        that is, <code>cov_mat</code> will be a usual covariation matrix with the same linear size as the total number of
2802                        elements in every input vector. One and only one of <code>CV_COVAR_SCRAMBLED</code> and <code>CV_COVAR_NORMAL</code> must be specified<br>
2803                  <code>CV_COVAR_USE_AVG</code> - if the flag is specified, the function does not calculate <code>avg</code> from
2804                        the input vectors, but, instead, uses the passed <code>avg</code> vector. This is useful if <code>avg</code>
2805                        has been already calculated somehow, or if the covariation matrix is calculated by parts - in this case,
2806                        <code>avg</code> is not a mean vector of the input sub-set of vectors, but rather the mean vector of
2807                        the whole set.<br>
2808                  <code>CV_COVAR_SCALE</code> - if the flag is specified, the covariation matrix is scaled by
2809                        the number of input vectors.
2810                  <code>CV_COVAR_ROWS</code> - Means that all the input vectors are stored as rows of a single matrix, <code>vects[0]</code>.
2811                        <code>count</code> is ignored in this case, and <code>avg</code> should be a single-row vector of an appropriate size.
2812                  <code>CV_COVAR_COLS</code> - Means that all the input vectors are stored as columns of a single matrix, <code>vects[0]</code>.
2813                        <code>count</code> is ignored in this case, and <code>avg</code> should be a single-column vector of an appropriate size.
2814 </dl><p>
2815 The function <code>cvCalcCovarMatrix</code> calculates the covariation matrix and, optionally,
2816 mean vector of the set of input vectors. The function can be used for PCA, for comparing vectors using Mahalanobis distance etc.
2817 </p>
2818
2819
2820 <hr><h3><a name="decl_cvMahalonobis">Mahalonobis</a></h3>
2821 <p class="Blurb">Calculates Mahalonobis distance between two vectors</p>
2822 <pre>
2823 double cvMahalanobis( const CvArr* vec1, const CvArr* vec2, CvArr* mat );
2824 </pre><p><dl>
2825 <dt>vec1<dd>The first 1D source vector.
2826 <dt>vec2<dd>The second 1D source vector.
2827 <dt>mat<dd>The inverse covariation matrix.
2828 </dl><p>
2829 The function <code>cvMahalonobis</code> calculates the weighted distance between two vectors
2830 and returns it:</p>
2831 <pre>
2832 d(vec1,vec2)=sqrt( sum<sub>i,j</sub> {mat(i,j)*(vec1(i)-vec2(i))*(vec1(j)-vec2(j))} )
2833 </pre>
2834 <p>The covariation matrix may be calculated using <a href="#decl_cvCalcCovarMatrix">cvCalcCovarMatrix</a> function and further
2835 inverted using <a href="#decl_cvInvert">cvInvert</a> function (CV_SVD method is the preferred one, because the matrix
2836 might be singular).</p>
2837
2838
2839 <hr><h3><a name="decl_cvCalcPCA">CalcPCA</a></h3>
2840 <p class="Blurb">Performs Principal Component Analysis of a vector set</p>
2841 <pre>
2842 void cvCalcPCA( const CvArr* data, CvArr* avg,
2843                 CvArr* eigenvalues, CvArr* eigenvectors, int flags );
2844 </pre><p><dl>
2845 <dt>data<dd>The input data; each vector is either a single row (<code>CV_PCA_DATA_AS_ROW</code>)
2846             or a single column (<code>CV_PCA_DATA_AS_COL</code>).
2847 <dt>avg<dd>The mean (average) vector, computed inside the function or provided by user.
2848 <dt>eigenvalues<dd>The output eigenvalues of covariation matrix.
2849 <dt>eigenvectors<dd>The output eigenvectors of covariation matrix (i.e. principal components);
2850                     one vector per row.
2851 <dt>flags<dd>The operation flags, a combination of the following values:<br>
2852              <code>CV_PCA_DATA_AS_ROW</code> - the vectors are stored as rows
2853              (i.e. all the components of a certain vector are stored continuously)<br>
2854              <code>CV_PCA_DATA_AS_COL</code> - the vectors are stored as columns
2855              (i.e. values of a certain vector component are stored continuously)<br>
2856              (the above two flags are mutually exclusive)<br>
2857              <code>CV_PCA_USE_AVG</code> - use pre-computed average vector<br>
2858 </dl><p>
2859 The function <code>cvCalcPCA</code> performs PCA analysis of the vector set.
2860 First, it uses <a href="#decl_cvCalcCovarMatrix">cvCalcCovarMatrix</a> to compute covariation matrix
2861 and then it finds its eigenvalues and eigenvectors. The output number of eigenvalues/eigenvectors
2862 should be less than or equal to <code>MIN(rows(data),cols(data))</code>.
2863
2864
2865 <hr><h3><a name="decl_cvProjectPCA">ProjectPCA</a></h3>
2866 <p class="Blurb">Projects vectors to the specified subspace</p>
2867 <pre>
2868 void cvProjectPCA( const CvArr* data, const CvArr* avg,
2869                    const CvArr* eigenvectors, CvArr* result )
2870 </pre><p><dl>
2871 <dt>data<dd>The input data; each vector is either a single row
2872             or a single column.
2873 <dt>avg<dd>The mean (average) vector. If it is a single-row vector,
2874            it means that the input vectors are stored as rows of <code>data</code>;
2875            otherwise, it should be a single-column vector,
2876            then the vectors are stored as columns of <code>data</code>.
2877 <dt>eigenvectors<dd>The eigenvectors (principal components); one vector per row.
2878 <dt>result<dd>The output matrix of decomposition coefficients. The number of rows must be
2879               the same as the number of vectors, the number of columns must
2880               be less than or equal to the number of rows in <code>eigenvectors</code>.
2881               That it is less, the input vectors are projected into subspace
2882               of the first <code>cols(result)</code> principal components.
2883 </dl><p>
2884 The function <code>cvProjectPCA</code> projects input vectors to the subspace represented by the
2885 orthonormal basis (<code>eigenvectors</code>). Before computing the dot products, <code>avg</code>
2886 vector is subtracted from the input vectors:</p>
2887 <pre>
2888 result(i,:)=(data(i,:)-avg)*eigenvectors' // for CV_PCA_DATA_AS_ROW layout.
2889 </pre>
2890
2891
2892 <hr><h3><a name="decl_cvBackProjectPCA">BackProjectPCA</a></h3>
2893 <p class="Blurb">Reconstructs the original vectors from the projection coefficients</p>
2894 <pre>
2895 void cvBackProjectPCA( const CvArr* proj, const CvArr* avg,
2896                        const CvArr* eigenvects, CvArr* result );
2897 </pre><p><dl>
2898 <dt>proj<dd>The input data; in the same format as <code>result</code> in
2899             <a href="#decl_cvProjectPCA">cvProjectPCA</a>.
2900 <dt>avg<dd>The mean (average) vector. If it is a single-row vector,
2901            it means that the output vectors are stored as rows of <code>result</code>;
2902            otherwise, it should be a single-column vector,
2903            then the vectors are stored as columns of <code>result</code>.
2904 <dt>eigenvectors<dd>The eigenvectors (principal components); one vector per row.
2905 <dt>result<dd>The output matrix of reconstructed vectors.
2906 </dl><p>
2907 The function <code>cvBackProjectPCA</code> reconstructs the vectors from the projection coefficients:</p>
2908 <pre>
2909 result(i,:)=proj(i,:)*eigenvectors + avg // for CV_PCA_DATA_AS_ROW layout.
2910 </pre>
2911
2912
2913 <hr><h2><a name="cxcore_arrays_math">Math Functions</a></h2>
2914
2915 <hr><h3><a name="decl_cvRound">Round, Floor, Ceil</a></h3>
2916 <p class="Blurb">Converts floating-point number to integer</p>
2917 <pre>
2918 int cvRound( double value );
2919 int cvFloor( double value );
2920 int cvCeil( double value );
2921 </pre><p><dl>
2922 <dt>value<dd>The input floating-point value
2923 </dl><p>
2924 The functions <code>cvRound, cvFloor</code> and <code>cvCeil</code> convert input floating-point number to
2925 integer using one of the rounding modes. <code>cvRound</code> returns the nearest integer value to
2926 the argument.
2927 <code>cvFloor</code> returns the maximum integer value that is not larger than the argument.
2928 <code>cvCeil</code> returns the minimum integer value that is not smaller than the argument.
2929 On some architectures the functions work <em>much</em> faster than the standard cast operations in C.
2930 If absolute value of the argument is greater than 2<sup>31</sup>, the result is not determined.
2931 Special values (&plusmn;Inf, NaN) are not handled.
2932 </p>
2933
2934
2935 <hr><h3><a name="decl_cvSqrt">Sqrt</a></h3>
2936 <p class="Blurb">Calculates square root</p>
2937 <pre>
2938 float cvSqrt( float value );
2939 </pre><p><dl>
2940 <dt>value<dd>The input floating-point value
2941 </dl><p>
2942 The function <code>cvSqrt</code> calculates square root of the argument.
2943 If the argument is negative, the result is not determined.
2944 </p>
2945
2946
2947 <hr><h3><a name="decl_cvInvSqrt">InvSqrt</a></h3>
2948 <p class="Blurb">Calculates inverse square root</p>
2949 <pre>
2950 float cvInvSqrt( float value );
2951 </pre><p><dl>
2952 <dt>value<dd>The input floating-point value
2953 </dl><p>
2954 The function <code>cvInvSqrt</code> calculates inverse square root of the argument, and
2955 normally it is faster than <code>1./sqrt(value)</code>. If the argument is zero or negative, the result is
2956 not determined. Special values (&plusmn;Inf, NaN) are not handled.
2957 </p>
2958
2959
2960 <hr><h3><a name="decl_cvCbrt">Cbrt</a></h3>
2961 <p class="Blurb">Calculates cubic root</p>
2962 <pre>
2963 float cvCbrt( float value );
2964 </pre><p><dl>
2965 <dt>value<dd>The input floating-point value
2966 </dl><p>
2967 The function <code>cvCbrt</code> calculates cubic root of the argument, and
2968 normally it is faster than <code>pow(value,1./3)</code>. Besides, negative arguments are handled properly.
2969 Special values (&plusmn;Inf, NaN) are not handled.
2970 </p>
2971
2972
2973 <hr><h3><a name="decl_cvFastArctan">FastArctan</a></h3>
2974 <p class="Blurb">Calculates angle of 2D vector</p>
2975 <pre>
2976 float cvFastArctan( float y, float x );
2977 </pre><p><dl>
2978 <dt>x<dd>x-coordinate of 2D vector
2979 <dt>y<dd>y-coordinate of 2D vector
2980 </dl><p>
2981 The function <code>cvFastArctan</code> calculates full-range angle of input 2D vector.
2982 The angle is measured in degrees and varies from 0&deg; to 360&deg;. The accuracy is ~0.1&deg;
2983 </p>
2984
2985
2986 <hr><h3><a name="decl_cvIsNaN">IsNaN</a></h3>
2987 <p class="Blurb">Determines if the argument is Not A Number</p>
2988 <pre>
2989 int cvIsNaN( double value );
2990 </pre><p><dl>
2991 <dt>value<dd>The input floating-point value
2992 </dl><p>
2993 The function <code>cvIsNaN</code> returns 1 if the argument is Not A Number (as defined
2994 by IEEE754 standard), 0 otherwise.
2995 </p>
2996
2997 <hr><h3><a name="decl_cvIsInf">IsInf</a></h3>
2998 <p class="Blurb">Determines if the argument is Infinity</p>
2999 <pre>
3000 int cvIsInf( double value );
3001 </pre><p><dl>
3002 <dt>value<dd>The input floating-point value
3003 </dl><p>
3004 The function <code>cvIsInf</code> returns 1 if the argument is &plusmn;Infinity (as defined
3005 by IEEE754 standard), 0 otherwise.
3006 </p>
3007
3008
3009 <hr><h3><a name="decl_cvCartToPolar">CartToPolar</a></h3>
3010 <p class="Blurb">Calculates magnitude and/or angle of 2d vectors</p>
3011 <pre>
3012 void cvCartToPolar( const CvArr* x, const CvArr* y, CvArr* magnitude,
3013                     CvArr* angle=NULL, int angle_in_degrees=0 );
3014 </pre><p><dl>
3015 <dt>x<dd>The array of x-coordinates
3016 <dt>y<dd>The array of y-coordinates
3017 <dt>magnitude<dd>The destination array of magnitudes, may be set to NULL if it is not needed
3018 <dt>angle<dd>The destination array of angles, may be set to NULL if it is not needed.
3019         The angles are measured in radians (0..2&pi;) or in degrees (0..360&deg;).
3020 <dt>angle_in_degrees<dd>The flag indicating whether the angles are measured in radians,
3021                         which is default mode, or in degrees.
3022 </dl><p>
3023 The function <code>cvCartToPolar</code> calculates either magnitude, angle,
3024 or both of every 2d vector <code>(x(I),y(I))</code>:</p>
3025 <pre>
3026 magnitude(I)=sqrt( x(I)<sup>2</sup>+y(I)<sup>2</sup> ),
3027 angle(I)=atan( y(I)/x(I) )
3028 </pre>
3029 <p>The angles are calculated with &asymp;0.1&deg; accuracy. For (0,0) point the angle
3030 is set to 0.</p>
3031
3032
3033 <hr><h3><a name="decl_cvPolarToCart">PolarToCart</a></h3>
3034 <p class="Blurb">Calculates Cartesian coordinates of 2d vectors represented in polar form</p>
3035 <pre>
3036 void cvPolarToCart( const CvArr* magnitude, const CvArr* angle,
3037                     CvArr* x, CvArr* y, int angle_in_degrees=0 );
3038 </pre><p><dl>
3039 <dt>magnitude<dd>The array of magnitudes. If it is NULL, the magnitudes are assumed all 1&#146;s.
3040 <dt>angle<dd>The array of angles, whether in radians or degrees.
3041 <dt>x<dd>The destination array of x-coordinates, may be set to NULL if it is not needed.
3042 <dt>y<dd>The destination array of y-coordinates, may be set to NULL if it is not needed.
3043 <dt>angle_in_degrees<dd>The flag indicating whether the angles are measured in radians,
3044                         which is default mode, or in degrees.
3045 </dl><p>
3046 The function <code>cvPolarToCart</code> calculates either x-coordinate, y-coordinate
3047 or both of every vector <code>magnitude(I)*exp(angle(I)*j), j=sqrt(-1)</code>:</p>
3048 <pre>
3049 x(I)=magnitude(I)*cos(angle(I)),
3050 y(I)=magnitude(I)*sin(angle(I))
3051 </pre>
3052
3053
3054 <hr><h3><a name="decl_cvPow">Pow</a></h3>
3055 <p class="Blurb">Raises every array element to power</p>
3056 <pre>
3057 void cvPow( const CvArr* src, CvArr* dst, double power );
3058 </pre><p><dl>
3059 <dt>src<dd>The source array.
3060 <dt>dst<dd>The destination array, should be the same type as the source.
3061 <dt>power<dd>The exponent of power.
3062 </dl><p>
3063 The function <code>cvPow</code> raises every element of input array to <code>p</code>:</p>
3064 <pre>
3065 dst(I)=src(I)<sup>p</sup>, if <code>p</code> is integer
3066 dst(I)=abs(src(I))<sup>p</sup>, otherwise
3067 </pre>
3068 <p>That is, for non-integer power exponent the absolute values of input
3069 array elements are used. However, it is possible to get true values
3070 for negative values using some extra operations, as the following sample,
3071 computing cube root of array elements, shows:</p>
3072 <pre>
3073 CvSize size = cvGetSize(src);
3074 CvMat* mask = cvCreateMat( size.height, size.width, CV_8UC1 );
3075 cvCmpS( src, 0, mask, CV_CMP_LT ); /* find negative elements */
3076 cvPow( src, dst, 1./3 );
3077 cvSubRS( dst, cvScalarAll(0), dst, mask ); /* negate the results of negative inputs */
3078 cvReleaseMat( &mask );
3079 </pre>
3080 <p>For some values of <code>power</code>, such as integer values, 0.5 and -0.5,
3081 specialized faster algorithms are used.</p>
3082
3083
3084 <hr><h3><a name="decl_cvExp">Exp</a></h3>
3085 <p class="Blurb">Calculates exponent of every array element</p>
3086 <pre>
3087 void cvExp( const CvArr* src, CvArr* dst );
3088 </pre><p><dl>
3089 <dt>src<dd>The source array.
3090 <dt>dst<dd>The destination array, it should have <code>double</code> type or
3091 the same type as the source.
3092 </dl><p>
3093 The function <code>cvExp</code> calculates exponent of every element of input array:</p>
3094 <pre>
3095 dst(I)=exp(src(I))
3096 </pre>
3097 <p>Maximum relative error is &asymp;7e-6. Currently,
3098 the function converts denormalized values to zeros on output.</p>
3099
3100
3101 <hr><h3><a name="decl_cvLog">Log</a></h3>
3102 <p class="Blurb">Calculates natural logarithm of every array element absolute value</p>
3103 <pre>
3104 void cvLog( const CvArr* src, CvArr* dst );
3105 </pre><p><dl>
3106 <dt>src<dd>The source array.
3107 <dt>dst<dd>The destination array, it should have <code>double</code> type or
3108 the same type as the source.
3109 </dl><p>
3110 The function <code>cvLog</code> calculates natural logarithm
3111 of absolute value of every element of input array:</p>
3112 <pre>
3113 dst(I)=log(abs(src(I))), src(I)!=0
3114 dst(I)=C,  src(I)=0
3115 </pre>
3116 Where <code>C</code> is large negative number (&asymp;-700 in the current implementation)</p>
3117
3118
3119 <hr><h3><a name="decl_cvSolveCubic">SolveCubic</a></h3>
3120 <p class="Blurb">Finds real roots of a cubic equation</p>
3121 <pre>
3122 int cvSolveCubic( const CvMat* coeffs, CvMat* roots );
3123 </pre><p><dl>
3124 <dt>coeffs<dd>The equation coefficients, array of 3 or 4 elements.
3125 <dt>roots<dd>The output array of real roots. Should have 3 elements.
3126 </dl><p>
3127 The function <code>cvSolveCubic</code> finds real roots of a cubic equation:</p>
3128 <pre>
3129 coeffs[0]*x<sup>3</sup> + coeffs[1]*x<sup>2</sup> + coeffs[2]*x + coeffs[3] = 0
3130 (if coeffs is 4-element vector)
3131
3132 or
3133
3134 x<sup>3</sup> + coeffs[0]*x<sup>2</sup> + coeffs[1]*x + coeffs[2] = 0
3135 (if coeffs is 3-element vector)
3136 </pre>
3137
3138 <p>The function returns the number of real roots found. The roots are stored
3139 to <code>root</code> array, which is padded with zeros if there is only one root.</p>
3140
3141
3142 <hr><h3><a name="decl_cvSolvePoly">SolvePoly</a></h3>
3143 <p class="Blurb">Finds real and complex roots of a polynomial equation with
3144 real coefficients</p>
3145 <pre>
3146 void cvSolvePoly(const CvMat* coeffs, CvMat *roots,
3147                  int maxiter = 10, int fig = 10);
3148 </pre><p><dl>
3149 <dt>coeffs<dd>The (degree + 1)-length array of equation coefficients (CV_32FC1 or CV_64FC1).
3150 <dt>roots<dd>The degree-length output array of real or complex roots (CV_32FC2 or CV_64FC2).
3151 <dt>maxiter<dd>The maximum number of iterations.
3152 <dt>fig<dd>The required figures of precision required.
3153 </dl><p>
3154 The function <code>cvSolvePoly</code> finds all real and complex roots of any
3155 degree polynomial with real coefficients.
3156
3157
3158 <hr><h2><a name="cxcore_arrays_rng">Random Number Generation</a></h2>
3159
3160 <hr><h3><a name="decl_cvRNG">RNG</a></h3>
3161 <p class="Blurb">Initializes random number generator state</p>
3162 <pre>
3163 CvRNG cvRNG( int64 seed=-1 );
3164 </pre><p><dl>
3165 <dt>seed<dd>64-bit value used to initiate a random sequence.
3166 </dl><p>
3167 The function <code>cvRNG</code> initializes random number generator
3168 and returns the state. Pointer to the state can be then passed to <a href="#decl_cvRandInt">cvRandInt</a>,
3169 <a href="#decl_cvRandReal">cvRandReal</a> and <a href="#decl_cvRandArr">cvRandArr</a> functions.
3170 In the current implementation a multiply-with-carry generator is used.</p>
3171
3172
3173 <hr><h3><a name="decl_cvRandArr">RandArr</a></h3>
3174 <p class="Blurb">Fills array with random numbers and updates the RNG state</p>
3175 <pre>
3176 void cvRandArr( CvRNG* rng, CvArr* arr, int dist_type, CvScalar param1, CvScalar param2 );
3177 </pre><p><dl>
3178 <dt>rng<dd>RNG state initialized by <a href="#decl_cvRNG">cvRNG</a>.
3179 <dt>arr<dd>The destination array.
3180 <dt>dist_type<dd>Distribution type:<br>
3181                      CV_RAND_UNI - uniform distribution<br>
3182                      CV_RAND_NORMAL - normal or Gaussian distribution<br>
3183 <dt>param1<dd>The first parameter of distribution. In case of uniform distribution it is
3184               the inclusive lower boundary of random numbers range. In case of
3185               normal distribution it is the mean value of random numbers.
3186 <dt>param2<dd>The second parameter of distribution. In case of uniform distribution it is
3187               the exclusive upper boundary of random numbers range. In case of
3188               normal distribution it is the standard deviation of random numbers.
3189 </dl><p>
3190 The function <code>cvRandArr</code> fills the destination array with
3191 uniformly or normally distributed random numbers. In the sample below
3192 the function is used to add a few normally distributed
3193 floating-point numbers to random locations within a 2d array</p>
3194 <pre>
3195 /* let noisy_screen be the floating-point 2d array that is to be "crapped" */
3196 CvRNG rng_state = cvRNG(0xffffffff);
3197 int i, pointCount = 1000;
3198 /* allocate the array of coordinates of points */
3199 CvMat* locations = cvCreateMat( pointCount, 1, CV_32SC2 );
3200 /* arr of random point values */
3201 CvMat* values = cvCreateMat( pointCount, 1, CV_32FC1 );
3202 CvSize size = cvGetSize( noisy_screen );
3203
3204 cvRandInit( &rng_state,
3205             0, 1, /* use dummy parameters now and adjust them further */
3206             0xffffffff /* just use a fixed seed here */,
3207             CV_RAND_UNI /* specify uniform type */ );
3208
3209 /* initialize the locations */
3210 cvRandArr( &rng_state, locations, CV_RAND_UNI, cvScalar(0,0,0,0), cvScalar(size.width,size.height,0,0) );
3211
3212 /* modify RNG to make it produce normally distributed values */
3213 rng_state.disttype = CV_RAND_NORMAL;
3214 cvRandSetRange( &rng_state,
3215                 30 /* deviation */,
3216                 100 /* average point brightness */,
3217                 -1 /* initialize all the dimensions */ );
3218 /* generate values */
3219 cvRandArr( &rng_state, values, CV_RAND_NORMAL,
3220            cvRealScalar(100), // average intensity
3221            cvRealScalar(30) // deviation of the intensity
3222            );
3223
3224 /* set the points */
3225 for( i = 0; i &lt; pointCount; i++ )
3226 {
3227     CvPoint pt = *(CvPoint*)cvPtr1D( locations, i, 0 );
3228     float value = *(float*)cvPtr1D( values, i, 0 );
3229     *((float*)cvPtr2D( noisy_screen, pt.y, pt.x, 0 )) += value;
3230 }
3231
3232 /* not to forget to release the temporary arrays */
3233 cvReleaseMat( &locations );
3234 cvReleaseMat( &values );
3235
3236 /* RNG state does not need to be deallocated */
3237 </pre>
3238
3239
3240 <hr><h3><a name="decl_cvRandInt">RandInt</a></h3>
3241 <p class="Blurb">Returns 32-bit unsigned integer and updates RNG</p>
3242 <pre>
3243 unsigned cvRandInt( CvRNG* rng );
3244 </pre><p><dl>
3245 <dt>rng<dd>RNG state initialized by <code>RandInit</code> and, optionally,
3246 customized by <code>RandSetRange</code> (though, the latter function does not
3247 affect on the discussed function outcome).
3248 </dl><p>
3249 The function <code>cvRandInt</code> returns uniformly-distributed random
3250 32-bit unsigned integer and updates RNG state. It is similar to rand() function from C runtime library,
3251 but it always generates 32-bit number whereas rand() returns a number in between 0
3252 and <code>RAND_MAX</code> which is 2**16 or 2**32, depending on the platform.</p><p>
3253 The function is useful for generating scalar random numbers, such as points, patch sizes,
3254 table indices etc, where integer numbers of a certain range can be generated using
3255 modulo operation and floating-point numbers can be generated by scaling to
3256 0..1 of any other specific range. Here is the example from the previous function discussion
3257 rewritten using <a href="#decl_cvRandInt">cvRandInt</a>:</p>
3258 <pre>
3259 /* the input and the task is the same as in the previous sample. */
3260 CvRNG rng_state = cvRNG(0xffffffff);
3261 int i, pointCount = 1000;
3262 /* ... - no arrays are allocated here */
3263 CvSize size = cvGetSize( noisy_screen );
3264 /* make a buffer for normally distributed numbers to reduce call overhead */
3265 #define bufferSize 16
3266 float normalValueBuffer[bufferSize];
3267 CvMat normalValueMat = cvMat( bufferSize, 1, CV_32F, normalValueBuffer );
3268 int valuesLeft = 0;
3269
3270 for( i = 0; i &lt; pointCount; i++ )
3271 {
3272     CvPoint pt;
3273     /* generate random point */
3274     pt.x = cvRandInt( &rng_state ) % size.width;
3275     pt.y = cvRandInt( &rng_state ) % size.height;
3276
3277     if( valuesLeft &lt;= 0 )
3278     {
3279         /* fulfill the buffer with normally distributed numbers if the buffer is empty */
3280         cvRandArr( &rng_state, &normalValueMat, CV_RAND_NORMAL, cvRealScalar(100), cvRealScalar(30) );
3281         valuesLeft = bufferSize;
3282     }
3283     *((float*)cvPtr2D( noisy_screen, pt.y, pt.x, 0 ) = normalValueBuffer[--valuesLeft];
3284 }
3285
3286 /* there is no need to deallocate normalValueMat because we have
3287 both the matrix header and the data on stack. It is a common and efficient
3288 practice of working with small, fixed-size matrices */
3289 </pre>
3290
3291
3292 <hr><h3><a name="decl_cvRandReal">RandReal</a></h3>
3293 <p class="Blurb">Returns floating-point random number and updates RNG</p>
3294 <pre>
3295 double cvRandReal( CvRNG* rng );
3296 </pre><p><dl>
3297 <dt>rng<dd>RNG state initialized by <a href="#decl_cvRNG">cvRNG</a>.
3298 </dl><p>
3299 The function <code>cvRandReal</code> returns uniformly-distributed random
3300 floating-point number from 0..1 range (1 is not included).</p>
3301
3302
3303 <hr><h2><a name="cxcore_arrays_dxt">Discrete Transforms</a></h2>
3304
3305 <hr><h3><a name="decl_cvDFT">DFT</a></h3>
3306 <p class="Blurb">Performs forward or inverse Discrete Fourier transform of 1D or 2D floating-point array</p>
3307 <pre>
3308 #define CV_DXT_FORWARD  0
3309 #define CV_DXT_INVERSE  1
3310 #define CV_DXT_SCALE    2
3311 #define CV_DXT_ROWS     4
3312 #define CV_DXT_INV_SCALE (CV_DXT_SCALE|CV_DXT_INVERSE)
3313 #define CV_DXT_INVERSE_SCALE CV_DXT_INV_SCALE
3314
3315 void cvDFT( const CvArr* src, CvArr* dst, int flags, int nonzero_rows=0 );
3316 </pre><p><dl>
3317 <dt>src<dd>Source array, real or complex.
3318 <dt>dst<dd>Destination array of the same size and same type as the source.
3319 <dt>flags<dd>Transformation flags, a combination of the following values:<br>
3320               <code>CV_DXT_FORWARD</code> - do forward 1D or 2D transform. The result is not scaled.<br>
3321               <code>CV_DXT_INVERSE</code> - do inverse 1D or 2D transform. The result is not scaled.
3322                                <code>CV_DXT_FORWARD</code> and <code>CV_DXT_INVERSE</code> are mutually exclusive,
3323                                of course.<br>
3324               <code>CV_DXT_SCALE</code> - scale the result: divide it by the number of array elements.
3325                                           Usually, it is combined with <code>CV_DXT_INVERSE</code>, and one
3326                                           may use a shortcut <code>CV_DXT_INV_SCALE</code>.<br>
3327               <code>CV_DXT_ROWS</code> - do forward or inverse transform of every individual row of the input
3328                                          matrix. This flag allows user to transform multiple vectors simultaneously and
3329                                          can be used to decrease the overhead (which is sometimes several times
3330                                          larger than the processing itself), to do 3D and higher-dimensional
3331                                          transforms etc.
3332 <dt>nonzero_rows<dd>Number of nonzero rows to in the source array (in case of forward 2d transform),
3333                     or a number of rows of interest in the destination array (in case of inverse 2d transform).
3334                     If the value is negative, zero, or greater than the total number of rows, it is ignored.
3335                     The parameter can be used to speed up 2d convolution/correlation when computing them via DFT.
3336                     See the sample below.
3337 </dl><p>
3338 The function <code>cvDFT</code> performs forward or inverse transform of
3339 1D or 2D floating-point array:
3340 <pre>
3341 Forward Fourier transform of 1D vector of N elements:
3342 y = F<sup>(N)</sup>&bull;x, where F<sup>(N)</sup><sub>jk</sub>=exp(-i&bull;2Pi&bull;j&bull;k/N), i=sqrt(-1)
3343
3344 Inverse Fourier transform of 1D vector of N elements:
3345 x'= (F<sup>(N)</sup>)<sup>-1</sup>&bull;y = conj(F<sup>(N)</sup>)&bull;y
3346 x = (1/N)&bull;x
3347
3348 Forward Fourier transform of 2D vector of M&times;N elements:
3349 Y = F<sup>(M)</sup>&bull;X&bull;F<sup>(N)</sup>
3350
3351 Inverse Fourier transform of 2D vector of M&times;N elements:
3352 X'= conj(F<sup>(M)</sup>)&bull;Y&bull;conj(F<sup>(N)</sup>)
3353 X = (1/(M&bull;N))&bull;X'
3354 </pre>
3355
3356 <p>In case of real (single-channel) data, the packed format, borrowed from IPL, is used to
3357 to represent a result of forward Fourier transform or input for inverse Fourier transform:
3358
3359 <pre>
3360 Re Y<sub>0,0</sub>      Re Y<sub>0,1</sub>    Im Y<sub>0,1</sub>    Re Y<sub>0,2</sub>     Im Y<sub>0,2</sub>  ...  Re Y<sub>0,N/2-1</sub>   Im Y<sub>0,N/2-1</sub>  Re Y<sub>0,N/2</sub>
3361 Re Y<sub>1,0</sub>      Re Y<sub>1,1</sub>    Im Y<sub>1,1</sub>    Re Y<sub>1,2</sub>     Im Y<sub>1,2</sub>  ...  Re Y<sub>1,N/2-1</sub>   Im Y<sub>1,N/2-1</sub>  Re Y<sub>1,N/2</sub>
3362 Im Y<sub>1,0</sub>      Re Y<sub>2,1</sub>    Im Y<sub>2,1</sub>    Re Y<sub>2,2</sub>     Im Y<sub>2,2</sub>  ...  Re Y<sub>2,N/2-1</sub>   Im Y<sub>2,N/2-1</sub>  Im Y<sub>2,N/2</sub>
3363 ............................................................................................
3364 Re Y<sub>M/2-1,0</sub>   Re Y<sub>M-3,1</sub>   Im Y<sub>M-3,1</sub>  Re Y<sub>M-3,2</sub>   Im Y<sub>M-3,2</sub> ...  Re Y<sub>M-3,N/2-1</sub>  Im Y<sub>M-3,N/2-1</sub> Re Y<sub>M-3,N/2</sub>
3365 Im Y<sub>M/2-1,0</sub>   Re Y<sub>M-2,1</sub>   Im Y<sub>M-2,1</sub>  Re Y<sub>M-2,2</sub>   Im Y<sub>M-2,2</sub> ...  Re Y<sub>M-2,N/2-1</sub>  Im Y<sub>M-2,N/2-1</sub> Im Y<sub>M-2,N/2</sub>
3366 Re Y<sub>M/2,0</sub>    Re Y<sub>M-1,1</sub>   Im Y<sub>M-1,1</sub>  Re Y<sub>M-1,2</sub>   Im Y<sub>M-1,2</sub>  ... Re Y<sub>M-1,N/2-1</sub>  Im Y<sub>M-1,N/2-1</sub> Im Y<sub>M-1,N/2</sub>
3367 </pre>
3368
3369 <p>Note: the last column is present if <code>N</code> is even, the last row is present if <code>M</code> is even.</p>
3370 <p>In case of 1D real transform the result looks like the first row of the above matrix</p>
3371
3372 <font color=blue size=4>Computing 2D Convolution using DFT</font></p>
3373 <pre>
3374    CvMat* A = cvCreateMat( M1, N1, CV_32F );
3375    CvMat* B = cvCreateMat( M2, N2, A->type );
3376
3377    // it is also possible to have only abs(M2-M1)+1&times;abs(N2-N1)+1
3378    // part of the full convolution result
3379    CvMat* conv = cvCreateMat( A->rows + B->rows - 1, A->cols + B->cols - 1, A->type );
3380
3381    // initialize A and B
3382    ...
3383
3384    int dft_M = cvGetOptimalDFTSize( A->rows + B->rows - 1 );
3385    int dft_N = cvGetOptimalDFTSize( A->cols + B->cols - 1 );
3386
3387    CvMat* dft_A = cvCreateMat( dft_M, dft_N, A->type );
3388    CvMat* dft_B = cvCreateMat( dft_M, dft_N, B->type );
3389    CvMat tmp;
3390
3391    // copy A to dft_A and pad dft_A with zeros
3392    cvGetSubRect( dft_A, &tmp, cvRect(0,0,A->cols,A->rows));
3393    cvCopy( A, &tmp );
3394    cvGetSubRect( dft_A, &tmp, cvRect(A->cols,0,dft_A->cols - A->cols,A->rows));
3395    cvZero( &tmp );
3396    // no need to pad bottom part of dft_A with zeros because of
3397    // use nonzero_rows parameter in cvDFT() call below
3398
3399    cvDFT( dft_A, dft_A, CV_DXT_FORWARD, A->rows );
3400
3401    // repeat the same with the second array
3402    cvGetSubRect( dft_B, &tmp, cvRect(0,0,B->cols,B->rows));
3403    cvCopy( B, &tmp );
3404    cvGetSubRect( dft_B, &tmp, cvRect(B->cols,0,dft_B->cols - B->cols,B->rows));
3405    cvZero( &tmp );
3406    // no need to pad bottom part of dft_B with zeros because of
3407    // use nonzero_rows parameter in cvDFT() call below
3408
3409    cvDFT( dft_B, dft_B, CV_DXT_FORWARD, B->rows );
3410
3411    cvMulSpectrums( dft_A, dft_B, dft_A, 0 /* or CV_DXT_MUL_CONJ to get correlation
3412                                              rather than convolution */ );
3413
3414    cvDFT( dft_A, dft_A, CV_DXT_INV_SCALE, conv->rows ); // calculate only the top part
3415    cvGetSubRect( dft_A, &tmp, cvRect(0,0,conv->cols,conv->rows) );
3416
3417    cvCopy( &tmp, conv );
3418 </pre></p>
3419
3420
3421 <hr><h3><a name="decl_cvGetOptimalDFTSize">GetOptimalDFTSize</a></h3>
3422 <p class="Blurb">Returns optimal DFT size for given vector size</p>
3423 <pre>
3424 int cvGetOptimalDFTSize( int size0 );
3425 </pre><p><dl>
3426 <dt>size0<dd>Vector size.
3427 </dl><p>
3428 The function <code>cvGetOptimalDFTSize</code> returns the minimum
3429 number <code>N</code> that is greater to equal to <code>size0</code>, such that DFT of a vector
3430 of size <code>N</code> can be computed fast. In the current implementation
3431 <code>N=2<sup>p</sup>&times;3<sup>q</sup>&times;5<sup>r</sup></code> for some <code>p, q, r</code>.
3432 </p>
3433 <p>The function returns a negative number if <code>size0</code> is too large (very close to <code>INT_MAX</code>)</p>
3434
3435
3436 <hr><h3><a name="decl_cvMulSpectrums">MulSpectrums</a></h3>
3437 <p class="Blurb">Performs per-element multiplication of two Fourier spectrums</p>
3438 <pre>
3439 void cvMulSpectrums( const CvArr* src1, const CvArr* src2, CvArr* dst, int flags );
3440 </pre><p><dl>
3441 <dt>src1<dd>The first source array.
3442 <dt>src2<dd>The second source array.
3443 <dt>dst<dd>The destination array of the same type and the same size of the sources.
3444 <dt>flags<dd>A combination of the following values:<br>
3445               <code>CV_DXT_ROWS</code> - treat each row of the arrays as a separate spectrum
3446                                          (see <a href="#decl_cvDFT">cvDFT</a> parameters description).<br>
3447               <code>CV_DXT_MUL_CONJ</code> - conjugate the second source array before the multiplication.<br>
3448 </dl><p>
3449 The function <code>cvMulSpectrums</code> performs per-element multiplication
3450 of the two CCS-packed or complex matrices that are results of real or complex Fourier transform.
3451 </p><p>
3452 The function, together with <a href="#decl_cvDFT">cvDFT</a>, may be used to calculate convolution
3453 of two arrays fast.
3454 </p>
3455
3456 <hr><h3><a name="decl_cvDCT">DCT</a></h3>
3457 <p class="Blurb">Performs forward or inverse Discrete Cosine transform of 1D or 2D floating-point array</p>
3458 <pre>
3459 #define CV_DXT_FORWARD  0
3460 #define CV_DXT_INVERSE  1
3461 #define CV_DXT_ROWS     4
3462
3463 void cvDCT( const CvArr* src, CvArr* dst, int flags );
3464 </pre><p><dl>
3465 <dt>src<dd>Source array, real 1D or 2D array.
3466 <dt>dst<dd>Destination array of the same size and same type as the source.
3467 <dt>flags<dd>Transformation flags, a combination of the following values:<br>
3468               <code>CV_DXT_FORWARD</code> - do forward 1D or 2D transform.<br>
3469               <code>CV_DXT_INVERSE</code> - do inverse 1D or 2D transform.<br>
3470               <code>CV_DXT_ROWS</code> - do forward or inverse transform of every individual row of the input
3471                                          matrix. This flag allows user to transform multiple vectors simultaneously and
3472                                          can be used to decrease the overhead (which is sometimes several times
3473                                          larger than the processing itself), to do 3D and higher-dimensional
3474                                          transforms etc.
3475 </dl><p>
3476 The function <code>cvDCT</code> performs forward or inverse transform of
3477 1D or 2D floating-point array:
3478 <pre>
3479 Forward Cosine transform of 1D vector of N elements:
3480 y = C<sup>(N)</sup>&bull;x, where C<sup>(N)</sup><sub>jk</sub>=sqrt((j==0?1:2)/N)&bull;cos(Pi&bull;(2k+1)&bull;j/N)
3481
3482 Inverse Cosine transform of 1D vector of N elements:
3483 x = (C<sup>(N)</sup>)<sup>-1</sup>&bull;y = (C<sup>(N)</sup>)<sup>T</sup>&bull;y
3484
3485 Forward Cosine transform of 2D vector of M&times;N elements:
3486 Y = (C<sup>(M)</sup>)&bull;X&bull;(C<sup>(N)</sup>)<sup>T</sup>
3487
3488 Inverse Cosine transform of 2D vector of M&times;N elements:
3489 X = (C<sup>(M)</sup>)<sup>T</sup>&bull;Y&bull;C<sup>(N)</sup>
3490 </pre>
3491
3492
3493 <hr><h1><a name="cxcore_ds">Dynamic Structures</a></h1>
3494
3495 <hr><h2><a name="cxcore_ds_storages">Memory Storages</a></h2>
3496
3497 <hr><h3><a name="decl_CvMemStorage">CvMemStorage</a></h3>
3498 <p class="Blurb">Growing memory storage</p>
3499 <pre>
3500 typedef struct CvMemStorage
3501 {
3502     struct CvMemBlock* bottom;/* first allocated block */
3503     struct CvMemBlock* top; /* the current memory block - top of the stack */
3504     struct CvMemStorage* parent; /* borrows new blocks from */
3505     int block_size; /* block size */
3506     int free_space; /* free space in the <code>top</code> block (in bytes) */
3507 } CvMemStorage;
3508 </pre>
3509 <p>
3510 Memory storage is a low-level structure used to store dynamically growing data structures such as
3511 sequences, contours, graphs, subdivisions etc. It is organized as a list of memory blocks of
3512 equal size - <code>bottom</code> field is the beginning of the list of blocks</code>
3513 and <code>top</code> is the currently used block, but not necessarily the last block of the list. All blocks
3514 between <code>bottom</code> and <code>top</code>, not including the latter, are considered fully occupied;
3515 and all blocks between <code>top</code> and the last block, not including <code>top</code>,
3516 are considered free and <code>top</code> block itself is partly occupied - <code>free_space</code>
3517 contains the number of free bytes left in the end of <code>top</code>.
3518 </p><p>New memory buffer that may be allocated explicitly by <a href="#decl_cvMemStorageAlloc">cvMemStorageAlloc</a> function
3519 or implicitly by
3520 higher-level functions, such as <a href="#decl_cvSeqPush">cvSeqPush</a>, <a href="#decl_cvGraphAddEdge">cvGraphAddEdge</a> etc., <code>always</code>
3521 starts in the end of the current block if it fits there. After allocation <code>free_space</code>
3522 is decremented by the size of the allocated buffer plus some padding to keep the proper alignment.
3523 When the allocated buffer does not fit into the available part of <code>top</code>, the next storage
3524 block from the list is taken as <code>top</code> and <code>free_space</code> is reset to the
3525 whole block size prior to the allocation.</p><p>
3526 If there is no more free blocks, a new block is allocated (or borrowed from parent, see
3527 <a href="#decl_cvCreateChildMemStorage">cvCreateChildMemStorage</a>) and added to the end of list. Thus, the storage behaves as a stack
3528 with <code>bottom</code> indicating bottom of the stack and the pair (<code>top</code>, <code>free_space</code>)
3529 indicating top of the stack. The stack top may be saved via <a href="#decl_cvSaveMemStoragePos">cvSaveMemStoragePos</a>,
3530 restored via <a href="#decl_cvRestoreMemStoragePos">cvRestoreMemStoragePos</a> or reset via <a href="#decl_cvClearStorage">cvClearStorage</a>.
3531 </p>
3532
3533
3534 <hr><h3><a name="decl_CvMemBlock">CvMemBlock</a></h3>
3535 <p class="Blurb">Memory storage block</p>
3536 <pre>
3537 typedef struct CvMemBlock
3538 {
3539     struct CvMemBlock* prev;
3540     struct CvMemBlock* next;
3541 } CvMemBlock;
3542 </pre>
3543 <p>
3544 The structure <a href="#decl_CvMemBlock">CvMemBlock</a> represents a single block of memory storage.
3545 Actual data of the memory blocks follows the header, that is, the <code>i-th</code> byte of
3546 the memory block can be retrieved with the expression <code>((char*)(mem_block_ptr+1))[i]</code>.
3547 However, normally there is no need to access the storage structure fields directly.
3548 </p>
3549
3550
3551 <hr><h3><a name="decl_CvMemStoragePos">CvMemStoragePos</a></h3>
3552 <p class="Blurb">Memory storage position</p>
3553 <pre>
3554 typedef struct CvMemStoragePos
3555 {
3556     CvMemBlock* top;
3557     int free_space;
3558 } CvMemStoragePos;
3559 </pre>
3560 <p>
3561 The structure described below stores the position of the stack top that can be
3562 saved via <a href="#decl_cvSaveMemStoragePos">cvSaveMemStoragePos</a> and restored via <a href="#decl_cvRestoreMemStoragePos">cvRestoreMemStoragePos</a>.</p>
3563
3564
3565 <hr><h3><a name="decl_cvCreateMemStorage">CreateMemStorage</a></h3>
3566 <p class="Blurb">Creates memory storage</p>
3567 <pre>
3568 CvMemStorage* cvCreateMemStorage( int block_size=0 );
3569 </pre><p><dl>
3570 <dt>block_size<dd>Size of the storage blocks in bytes. If it is 0, the block size is set to default value
3571 - currently it is &asymp;64K.
3572 </dl><p>
3573 The function <code>cvCreateMemStorage</code> creates a memory storage and returns pointer
3574 to it. Initially the storage is empty. All fields of the header, except the <code>block_size</code>,
3575 are set to 0.</p>
3576
3577
3578 <hr><h3><a name="decl_cvCreateChildMemStorage">CreateChildMemStorage</a></h3>
3579 <p class="Blurb">Creates child memory storage</p>
3580 <pre>
3581 CvMemStorage* cvCreateChildMemStorage( CvMemStorage* parent );
3582 </pre><p><dl>
3583 <dt>parent<dd>Parent memory storage.
3584 </dl><p>
3585 The function <code>cvCreateChildMemStorage</code> creates a child memory storage that is similar
3586 to simple memory storage except for the differences in the memory
3587 allocation/deallocation mechanism. When a child storage needs a new block to
3588 add to the block list, it tries to get this block from the parent. The first
3589 unoccupied parent block available is taken and excluded from the parent block
3590 list. If no blocks are available, the parent either allocates a block or borrows
3591 one from its own parent, if any. In other words, the chain, or a more complex
3592 structure, of memory storages where every storage is a child/parent of another
3593 is possible. When a child storage is released or even cleared, it returns all
3594 blocks to the parent. In other aspects, the child storage is the same as the simple storage.</p>
3595 <p>
3596 The children storages are useful in the following situation.
3597 Imagine that user needs to process dynamical data resided in some storage and
3598 put the result back to the same storage. With the simplest approach, when temporary
3599 data is resided in the same storage as the input and output data, the storage
3600 will look as following after processing:</p>
3601 <p>
3602 <font color=blue>Dynamic data processing without using child storage</font>
3603 </p>
3604 <p>
3605 <img align="center" src="pics/memstorage1.png" >
3606 </p>
3607 <p>
3608 That is, garbage appears in the middle of the storage.
3609 However, if one creates a child memory storage in the beginning of the processing,
3610 writes temporary data there and releases the child storage in the end, no garbage will
3611 appear in the source/destination storage:</p>
3612 <p><font color=blue>Dynamic data processing using a child storage</font>
3613 </p><p>
3614 <img align="center" src="pics/memstorage2.png" >
3615 </p>
3616
3617
3618 <hr><h3><a name="decl_cvReleaseMemStorage">ReleaseMemStorage</a></h3>
3619 <p class="Blurb">Releases memory storage</p>
3620 <pre>
3621 void cvReleaseMemStorage( CvMemStorage** storage );
3622 </pre><p><dl>
3623 <dt>storage<dd>Pointer to the released storage.
3624 </dl><p>
3625 The function <code>cvReleaseMemStorage</code> deallocates all storage memory blocks or returns
3626 them to the parent, if any. Then it deallocates the storage header and clears
3627 the pointer to the storage. All children of the storage must be released before
3628 the parent is released.</p>
3629
3630
3631 <hr><h3><a name="decl_cvClearMemStorage">ClearMemStorage</a></h3>
3632 <p class="Blurb">Clears memory storage</p>
3633 <pre>
3634 void cvClearMemStorage( CvMemStorage* storage );
3635 </pre><p><dl>
3636 <dt>storage<dd>Memory storage.
3637 </dl><p>
3638 The function <code>cvClearMemStorage</code> resets the top (free space boundary) of the storage
3639 to the very beginning. This function does not deallocate any memory. If the
3640 storage has a parent, the function returns all blocks to the parent.</p>
3641
3642
3643 <hr><h3><a name="decl_cvMemStorageAlloc">MemStorageAlloc</a></h3>
3644 <p class="Blurb">Allocates memory buffer in the storage</p>
3645 <pre>
3646 void* cvMemStorageAlloc( CvMemStorage* storage, size_t size );
3647 </pre><p><dl>
3648 <dt>storage<dd>Memory storage.
3649 <dt>size<dd>Buffer size.
3650 </dl><p>
3651 The function <code>cvMemStorageAlloc</code> allocates memory buffer in the storage. The buffer size
3652 must not exceed the storage block size, otherwise runtime error is raised. The buffer address is
3653 aligned by <code>CV_STRUCT_ALIGN</code> (=<code>sizeof(double)</code> for the moment) bytes.
3654 </p>
3655
3656
3657 <hr><h3><a name="decl_cvMemStorageAllocString">MemStorageAllocString</a></h3>
3658 <p class="Blurb">Allocates text string in the storage</p>
3659 <pre>
3660 typedef struct CvString
3661 {
3662     int len;
3663     char* ptr;
3664 }
3665 CvString;
3666
3667 CvString cvMemStorageAllocString( CvMemStorage* storage, const char* ptr, int len=-1 );
3668 </pre><p><dl>
3669 <dt>storage<dd>Memory storage.
3670 <dt>ptr<dd>The string.
3671 <dt>len<dd>Length of the string (not counting the ending '\0'). If the parameter is negative,
3672            the function computes the length.
3673 </dl><p>
3674 The function <code>cvMemStorageAllocString</code> creates copy of the
3675 string in the memory storage. It returns the structure that contains user-passed or computed length
3676 of the string and pointer to the copied string.
3677 </p>
3678
3679
3680 <hr><h3><a name="decl_cvSaveMemStoragePos">SaveMemStoragePos</a></h3>
3681 <p class="Blurb">Saves memory storage position</p>
3682 <pre>
3683 void cvSaveMemStoragePos( const CvMemStorage* storage, CvMemStoragePos* pos );
3684 </pre><p><dl>
3685 <dt>storage<dd>Memory storage.
3686 <dt>pos<dd>The output position of the storage top.
3687 </dl><p>
3688 The function <code>cvSaveMemStoragePos</code> saves the current position of the storage top to
3689 the parameter <code>pos</code>. The function <code>cvRestoreMemStoragePos</code> can further retrieve
3690 this position.</p>
3691
3692
3693 <hr><h3><a name="decl_cvRestoreMemStoragePos">RestoreMemStoragePos</a></h3>
3694 <p class="Blurb">Restores memory storage position</p>
3695 <pre>
3696 void cvRestoreMemStoragePos( CvMemStorage* storage, CvMemStoragePos* pos );
3697 </pre><p><dl>
3698 <dt>storage<dd>Memory storage.
3699 <dt>pos<dd>New storage top position.
3700 </dl><p>
3701 The function <code>cvRestoreMemStoragePos</code> restores the position of the storage top from
3702 the parameter <code>pos</code>. This function and The function <code>cvClearMemStorage</code> are the
3703 only methods to release memory occupied in memory blocks.
3704 Note again that there is no way to free memory in the middle of the occupied part of the storage.
3705 </p>
3706
3707
3708 <hr><h2><a name="cxcore_ds_sequences">Sequences</a></h2>
3709
3710 <hr><h3><a name="decl_CvSeq">CvSeq</a></h3>
3711 <p class="Blurb">Growable sequence of elements</p>
3712 <pre>
3713 #define CV_SEQUENCE_FIELDS() \
3714     int flags; /* miscellaneous flags */ \
3715     int header_size; /* size of sequence header */ \
3716     struct CvSeq* h_prev; /* previous sequence */ \
3717     struct CvSeq* h_next; /* next sequence */ \
3718     struct CvSeq* v_prev; /* 2nd previous sequence */ \
3719     struct CvSeq* v_next; /* 2nd next sequence */ \
3720     int total; /* total number of elements */ \
3721     int elem_size;/* size of sequence element in bytes */ \
3722     char* block_max;/* maximal bound of the last block */ \
3723     char* ptr; /* current write pointer */ \
3724     int delta_elems; /* how many elements allocated when the sequence grows (sequence granularity) */ \
3725     CvMemStorage* storage; /* where the seq is stored */ \
3726     CvSeqBlock* free_blocks; /* free blocks list */ \
3727     CvSeqBlock* first; /* pointer to the first sequence block */
3728
3729
3730 typedef struct CvSeq
3731 {
3732     CV_SEQUENCE_FIELDS()
3733 } CvSeq;
3734 </pre>
3735 <p>
3736 The structure <a href="#decl_CvSeq">CvSeq</a> is a base for all of OpenCV dynamic data structures.</p>
3737 <p>Such an unusual definition via a helper macro simplifies the extension of the structure
3738 <a href="#decl_CvSeq">CvSeq</a> with additional parameters.
3739 To extend <a href="#decl_CvSeq">CvSeq</a> the user may define a new structure and
3740 put user-defined fields after all <a href="#decl_CvSeq">CvSeq</a> fields that are included via the macro
3741 <code>CV_SEQUENCE_FIELDS()</code>.</p>
3742 <p>There are two types of sequences - dense and sparse. Base type for dense sequences is <a href="#decl_CvSeq">CvSeq</a>
3743 and such sequences are used to represent growable 1d arrays - vectors, stacks, queues, deques.
3744 They have no gaps in the middle - if an element is removed from the middle or inserted into the middle
3745 of the sequence the elements from the closer end are shifted.
3746 Sparse sequences have <a href="#decl_CvSet">CvSet</a> base
3747 class and they are discussed later in more details. They are sequences of nodes each of those may be
3748 either occupied or free as indicated by the node flag. Such sequences are used for unordered data
3749 structures such as sets of elements, graphs, hash tables etc.</p>
3750
3751 <p>The field <code>header_size</code> contains the actual size of the
3752 sequence header and should be greater or equal to <code>sizeof(CvSeq)</code>.</p><p>The fields
3753 <code>h_prev, h_next, v_prev, v_next</code> can be used to create hierarchical structures
3754 from separate sequences. The fields <code>h_prev</code> and <code>h_next</code> point to the previous and
3755 the next sequences on the same hierarchical level while the fields <code>v_prev</code> and
3756 <code>v_next</code> point to the previous and the next sequence in the vertical direction,
3757 that is, parent and its first child. But these are just names and the pointers
3758 can be used in a different way.</p><p>The field <code>first</code> points to the first sequence
3759 block, whose structure is described below.</p>
3760 <p>The field <code>total</code> contains the actual number of dense sequence elements and
3761 number of allocated nodes in sparse sequence.</p>
3762 <p>The field <code>flags</code>contain the particular dynamic type
3763 signature (<code>CV_SEQ_MAGIC_VAL</code> for dense sequences and <code>CV_SET_MAGIC_VAL</code> for sparse sequences)
3764 in the highest 16 bits and miscellaneous information about the sequence.
3765 The lowest <code>CV_SEQ_ELTYPE_BITS</code> bits contain the ID of the
3766 element type. Most of sequence processing functions do not use element type
3767 but element size stored in <code>elem_size</code>.
3768 If sequence contains the numeric data of one of <a href="#decl_CvMat">CvMat</a> type
3769 then the element type matches to the corresponding <a href="#decl_CvMat">CvMat</a> element type, e.g.
3770 CV_32SC2 may be used for sequence of 2D points, CV_32FC1 for sequences of floating-point values etc.
3771 <code>CV_SEQ_ELTYPE(seq_header_ptr)</code> macro retrieves the type of sequence elements.
3772 Processing function that work with numerical sequences check that <code>elem_size</code> is equal
3773 to the calculated from the type element size.
3774 Besides <a href="#decl_CvMat">CvMat</a> compatible types, there are few extra element types defined
3775 in <a href="#decl_cvtypes.h">cvtypes.h</a> header:</p>
3776 <p><font color=blue>Standard Types of Sequence Elements</font></p>
3777 <pre>
3778     #define CV_SEQ_ELTYPE_POINT          CV_32SC2  /* (x,y) */
3779     #define CV_SEQ_ELTYPE_CODE           CV_8UC1   /* freeman code: 0..7 */
3780     #define CV_SEQ_ELTYPE_GENERIC        0 /* unspecified type of sequence elements */
3781     #define CV_SEQ_ELTYPE_PTR            CV_USRTYPE1 /* =6 */
3782     #define CV_SEQ_ELTYPE_PPOINT         CV_SEQ_ELTYPE_PTR  /* &elem: pointer to element of other sequence */
3783     #define CV_SEQ_ELTYPE_INDEX          CV_32SC1  /* #elem: index of element of some other sequence */
3784     #define CV_SEQ_ELTYPE_GRAPH_EDGE     CV_SEQ_ELTYPE_GENERIC  /* &next_o, &next_d, &vtx_o, &vtx_d */
3785     #define CV_SEQ_ELTYPE_GRAPH_VERTEX   CV_SEQ_ELTYPE_GENERIC  /* first_edge, &(x,y) */
3786     #define CV_SEQ_ELTYPE_TRIAN_ATR      CV_SEQ_ELTYPE_GENERIC  /* vertex of the binary tree   */
3787     #define CV_SEQ_ELTYPE_CONNECTED_COMP CV_SEQ_ELTYPE_GENERIC  /* connected component  */
3788     #define CV_SEQ_ELTYPE_POINT3D        CV_32FC3  /* (x,y,z)  */
3789 </pre>
3790 <p>
3791 The next <code>CV_SEQ_KIND_BITS</code> bits specify the kind of the sequence:</p>
3792 <p><font color=blue>Standard Kinds of Sequences</font></p>
3793 <pre>
3794     /* generic (unspecified) kind of sequence */
3795     #define CV_SEQ_KIND_GENERIC     (0 &lt;&lt; CV_SEQ_ELTYPE_BITS)
3796
3797     /* dense sequence subtypes */
3798     #define CV_SEQ_KIND_CURVE       (1 &lt;&lt; CV_SEQ_ELTYPE_BITS)
3799     #define CV_SEQ_KIND_BIN_TREE    (2 &lt;&lt; CV_SEQ_ELTYPE_BITS)
3800
3801     /* sparse sequence (or set) subtypes */
3802     #define CV_SEQ_KIND_GRAPH       (3 &lt;&lt; CV_SEQ_ELTYPE_BITS)
3803     #define CV_SEQ_KIND_SUBDIV2D    (4 &lt;&lt; CV_SEQ_ELTYPE_BITS)
3804 </pre>
3805 <p>
3806 The remaining bits are used to identify different features specific to certain
3807 sequence kinds and element types. For example, curves made of points (
3808 <code>CV_SEQ_KIND_CURVE|CV_SEQ_ELTYPE_POINT</code> ), together with the flag
3809 <code>CV_SEQ_FLAG_CLOSED</code> belong to the type <code>CV_SEQ_POLYGON</code> or, if other flags are
3810 used, to its subtype. Many contour processing functions check the type of the input
3811 sequence and report an error if they do not support this type. The file
3812 <a href="#decl_cvtypes.h">cvtypes.h</a> stores the complete list of all supported predefined sequence types
3813 and helper macros designed to get the sequence type of other properties.
3814 Below follows the definition of the building block of sequences.</p>
3815
3816
3817 <hr><h3><a name="decl_CvSeqBlock">CvSeqBlock</a></h3>
3818 <p class="Blurb">Continuous sequence block</p>
3819 <pre>
3820 typedef struct CvSeqBlock
3821 {
3822     struct CvSeqBlock* prev; /* previous sequence block */
3823     struct CvSeqBlock* next; /* next sequence block */
3824     int start_index; /* index of the first element in the block +
3825     sequence->first->start_index */
3826     int count; /* number of elements in the block */
3827     char* data; /* pointer to the first element of the block */
3828 } CvSeqBlock;
3829 </pre>
3830 <p>
3831 Sequence blocks make up a circular double-linked list, so the pointers <code>prev</code> and
3832 <code>next</code> are never <code>NULL</code> and point to the previous and the next sequence blocks
3833 within the sequence. It means that <code>next</code> of the last block is the first block and
3834 <code>prev</code> of the first block is the last block. The fields <code>start_index</code> and <code>count</code> help
3835 to track the block location within the sequence. For example, if the sequence
3836 consists of 10 elements and splits into three blocks of 3, 5, and 2 elements,
3837 and the first block has the parameter <code>start_index = 2</code>, then pairs <code>(start_index, count)</code>
3838 for the sequence blocks are <code>(2,3), (5, 5)</code>, and <code>(10, 2)</code>
3839 correspondingly. The parameter <code>start_index</code> of the first block is usually <code>0</code>
3840 unless some elements have been inserted at the beginning of the sequence.
3841 </p>
3842
3843
3844 <hr><h3><a name="decl_CvSlice">CvSlice</a></h3>
3845 <p class="Blurb">A sequence slice</p>
3846 <pre>
3847 typedef struct CvSlice
3848 {
3849     int start_index;
3850     int end_index;
3851 } CvSlice;
3852
3853 inline CvSlice cvSlice( int start, int end );
3854 #define CV_WHOLE_SEQ_END_INDEX 0x3fffffff
3855 #define CV_WHOLE_SEQ  cvSlice(0, CV_WHOLE_SEQ_END_INDEX)
3856
3857 /* calculates the sequence slice length */
3858 int cvSliceLength( CvSlice slice, const CvSeq* seq );
3859 </pre>
3860 <p>
3861 Some of functions that operate on sequences take <code>CvSlice slice</code> parameter that is
3862 often set to the whole sequence (CV_WHOLE_SEQ) by default. Either of the <code>start_index</code>
3863 and <code>end_index</code> may be negative or exceed the sequence length, <code>start_index</code>
3864 is inclusive, <code>end_index</code> is exclusive boundary. If they are equal, the slice is considered
3865 empty (i.e. contains no elements). Because sequences are treated as circular structures,
3866 the slice may select a few elements in the end of a sequence followed by a few elements in the beginning
3867 of the sequence, for example, <code>cvSlice(-2, 3)</code> in case of 10-element sequence will select 5-element slice,
3868 containing pre-last (8th), last (9th), the very first (0th), second (1th) and third (2nd) elements.
3869 The functions normalize the slice argument in the following way: first, <a href="#decl_CvSlice">cvSliceLength</a>
3870 is called to determine the length of the slice, then, <code>start_index</code> of the slice is
3871 normalized similarly to the argument of <a href="#decl_cvGetSeqElem">cvGetSeqElem</a>
3872 (i.e. negative indices are allowed).
3873 The actual slice to process starts at the normalized <code>start_index</code>
3874 and lasts <a href="#decl_CvSlice">cvSliceLength</a> elements
3875 (again, assuming the sequence is a circular structure).
3876 </p>
3877
3878 <p>If a function does not take slice argument, but you want to process only a part of the sequence,
3879 the sub-sequence may be extracted using <a href="#decl_cvSeqSlice">cvSeqSlice</a> function,
3880 or stored as into a continuous buffer with <a href="#decl_cvCvtSeqToArray">cvCvtSeqToArray</a>
3881 (optionally, followed by <a href="#decl_cvMakeSeqHeaderForArray">cvMakeSeqHeaderForArray</a>.
3882 </p>
3883
3884
3885 <hr><h3><a name="decl_cvCreateSeq">CreateSeq</a></h3>
3886 <p class="Blurb">Creates sequence</p>
3887 <pre>
3888 CvSeq* cvCreateSeq( int seq_flags, int header_size,
3889                     int elem_size, CvMemStorage* storage );
3890 </pre><p><dl>
3891 <dt>seq_flags<dd>Flags of the created sequence. If the sequence is not passed to any
3892 function working with a specific type of sequences, the sequence value may be
3893 set to 0, otherwise the appropriate type must be selected from the list of
3894 predefined sequence types.
3895 <dt>header_size<dd>Size of the sequence header; must be greater or equal to
3896 <code>sizeof(CvSeq)</code>. If a specific type or its extension is indicated, this type must
3897 fit the base type header.
3898 <dt>elem_size<dd>Size of the sequence elements in bytes. The size must be consistent
3899 with the sequence type. For example, for a sequence of points to be created, the
3900 element type <code>CV_SEQ_ELTYPE_POINT</code> should be specified and the parameter <code>elem_size</code>
3901 must be equal to <code>sizeof(CvPoint)</code>.
3902 <dt>storage<dd>Sequence location.
3903 </dl><p>
3904 The function <code>cvCreateSeq</code> creates a sequence and returns the pointer to it. The
3905 function allocates the sequence header in the storage block as one continuous
3906 chunk and sets the structure fields <code>flags</code>, <code>elem_size</code>, <code>header_size</code> and <code>storage</code> to
3907 passed values, sets <code>delta_elems</code> to the default value (that may be reassigned using
3908 <a href="#decl_cvSetSeqBlockSize">cvSetSeqBlockSize</a> function), and clears other header fields,
3909 including the space after the first <code>sizeof(CvSeq)</code> bytes.</p>
3910
3911
3912 <hr><h3><a name="decl_cvSetSeqBlockSize">SetSeqBlockSize</a></h3>
3913 <p class="Blurb">Sets up sequence block size</p>
3914 <pre>
3915 void cvSetSeqBlockSize( CvSeq* seq, int delta_elems );
3916 </pre><p><dl>
3917 <dt>seq<dd>Sequence.
3918 <dt>delta_elems<dd>Desirable sequence block size in elements.
3919 </dl><p>
3920 The function <code>cvSetSeqBlockSize</code> affects memory allocation granularity.
3921 When the free space in the sequence buffers has run out, the function allocates the space
3922 for <code>delta_elems</code> sequence elements. If this block immediately follows the one
3923 previously allocated, the two blocks are concatenated, otherwise, a new sequence
3924 block is created. Therefore, the bigger the parameter is, the lower the possible sequence
3925 fragmentation, but the more space in the storage is wasted. When the
3926 sequence is created, the parameter <code>delta_elems</code> is set to the default value &asymp;1K.
3927 The function can be called any time after the sequence is created and affects
3928 future allocations. The function can modify the passed value of the parameter to
3929 meet the memory storage constraints.
3930 </p>
3931
3932
3933 <hr><h3><a name="decl_cvSeqPush">SeqPush</a></h3>
3934 <p class="Blurb">Adds element to sequence end</p>
3935 <pre>
3936 schar* cvSeqPush( CvSeq* seq, void* element=NULL );
3937 </pre><p><dl>
3938 <dt>seq<dd>Sequence.
3939 <dt>element<dd>Added element.
3940 </dl><p>
3941 The function <code>cvSeqPush</code> adds an element to the end of sequence and returns pointer
3942 to the allocated element. If the input <code>element</code> is NULL,
3943 the function simply allocates a space for one more element.</p>
3944 <p>The following code demonstrates how to create a new sequence using this function:</p>
3945 <pre>
3946 CvMemStorage* storage = cvCreateMemStorage(0);
3947 CvSeq* seq = cvCreateSeq( CV_32SC1, /* sequence of integer elements */
3948                           sizeof(CvSeq), /* header size - no extra fields */
3949                           sizeof(int), /* element size */
3950                           storage /* the container storage */ );
3951 int i;
3952 for( i = 0; i &lt; 100; i++ )
3953 {
3954     int* added = (int*)cvSeqPush( seq, &i );
3955     printf( "%d is added\n", *added );
3956 }
3957
3958 ...
3959 /* release memory storage in the end */
3960 cvReleaseMemStorage( &storage );
3961 </pre>
3962 <p>
3963 The function <code>cvSeqPush</code> has O(1) complexity, but there is a faster method for
3964 writing large sequences (see <a href="#decl_cvStartWriteSeq">cvStartWriteSeq</a> and related functions).
3965 </p>
3966
3967 <hr><h3><a name="decl_cvSeqPop">SeqPop</a></h3>
3968 <p class="Blurb">Removes element from sequence end</p>
3969 <pre>
3970 void cvSeqPop( CvSeq* seq, void* element=NULL );
3971 </pre><p><dl>
3972 <dt>seq<dd>Sequence.
3973 <dt>element<dd>Optional parameter. If the pointer is not zero, the function copies the
3974 removed element to this location.
3975 </dl><p>
3976 The function <code>cvSeqPop</code> removes an element from the sequence. The function reports
3977 an error if the sequence is already empty. The function has O(1) complexity. </p>
3978
3979
3980 <hr><h3><a name="decl_cvSeqPushFront">SeqPushFront</a></h3>
3981 <p class="Blurb">Adds element to sequence beginning</p>
3982 <pre>
3983 schar* cvSeqPushFront( CvSeq* seq, void* element=NULL );
3984 </pre><p><dl>
3985 <dt>seq<dd>Sequence.
3986 <dt>element<dd>Added element.
3987 </dl><p>
3988 The function <code>cvSeqPushFront</code> is similar to <a href="#decl_cvSeqPush">cvSeqPush</a> but it adds the new element
3989 to the beginning of the sequence. The function has O(1) complexity.
3990 </p>
3991
3992
3993 <hr><h3><a name="decl_cvSeqPopFront">SeqPopFront</a></h3>
3994 <p class="Blurb">Removes element from sequence beginning</p>
3995 <pre>
3996 void cvSeqPopFront( CvSeq* seq, void* element=NULL );
3997 </pre><p><dl>
3998 <dt>seq<dd>Sequence.
3999 <dt>element<dd>Optional parameter. If the pointer is not zero, the function copies the
4000 removed element to this location.
4001 </dl><p>
4002 The function <code>cvSeqPopFront</code> removes an element from the beginning of the sequence.
4003 The function reports an error if the sequence is already empty. The function has O(1) complexity. </p>
4004
4005
4006 <hr><h3><a name="decl_cvSeqPushMulti">SeqPushMulti</a></h3>
4007 <p class="Blurb">Pushes several elements to the either end of sequence</p>
4008 <pre>
4009 void cvSeqPushMulti( CvSeq* seq, void* elements, int count, int in_front=0 );
4010 </pre><p><dl>
4011 <dt>seq<dd>Sequence.
4012 <dt>elements<dd>Added elements.
4013 <dt>count<dd>Number of elements to push.
4014 <dt>in_front<dd>The flags specifying the modified sequence end:<br>
4015                 CV_BACK (=0) - the elements are added to the end of sequence<br>
4016                 CV_FRONT(!=0) - the elements are added to the beginning of sequence<br>
4017 </dl><p>
4018 The function <code>cvSeqPushMulti</code> adds several elements to either end of the sequence.
4019 The elements are added to the sequence in the same order as they are arranged in the
4020 input array but they can fall into different sequence blocks.</p>
4021
4022
4023 <hr><h3><a name="decl_cvSeqPopMulti">SeqPopMulti</a></h3>
4024 <p class="Blurb">Removes several elements from the either end of sequence</p>
4025 <pre>
4026 void cvSeqPopMulti( CvSeq* seq, void* elements, int count, int in_front=0 );
4027 </pre><p><dl>
4028 <dt>seq<dd>Sequence.
4029 <dt>elements<dd>Removed elements.
4030 <dt>count<dd>Number of elements to pop.
4031 <dt>in_front<dd>The flags specifying the modified sequence end:<br>
4032                 CV_BACK (=0) - the elements are removed from the end of sequence<br>
4033                 CV_FRONT(!=0) - the elements are removed from the beginning of sequence<br>
4034 </dl><p>
4035 The function <code>cvSeqPopMulti</code> removes several elements from either end of the sequence.
4036 If the number of the elements to be removed exceeds the total number of elements
4037 in the sequence, the function removes as many elements as possible.</p>
4038
4039
4040 <hr><h3><a name="decl_cvSeqInsert">SeqInsert</a></h3>
4041 <p class="Blurb">Inserts element in sequence middle</p>
4042 <pre>
4043 schar* cvSeqInsert( CvSeq* seq, int before_index, void* element=NULL );
4044 </pre><p><dl>
4045 <dt>seq<dd>Sequence.
4046 <dt>before_index<dd>Index before which the element is inserted. Inserting before 0 (the minimal allowed value
4047 of the parameter) is equal to <a href="#decl_cvSeqPushFront">cvSeqPushFront</a> and inserting before <code>seq->total</code> (the maximal
4048 allowed value of the parameter) is equal to <a href="#decl_cvSeqPush">cvSeqPush</a>.
4049 <dt>element<dd>Inserted element.
4050 </dl><p>
4051 The function <code>cvSeqInsert</code> shifts the sequence elements from the inserted position
4052 to the nearest end of the sequence and copies the <code>element</code> content there if
4053 the pointer is not NULL. The function returns pointer to the inserted element.</p>
4054
4055
4056 <hr><h3><a name="decl_cvSeqRemove">SeqRemove</a></h3>
4057 <p class="Blurb">Removes element from sequence middle</p>
4058 <pre>
4059 void cvSeqRemove( CvSeq* seq, int index );
4060 </pre><p><dl>
4061 <dt>seq<dd>Sequence.
4062 <dt>index<dd>Index of removed element.
4063 </dl><p>
4064 The function <code>cvSeqRemove</code> removes elements with the given index. If the index is
4065 out of range the function reports an error.
4066 An attempt to remove an element from an empty sequence is a
4067 partial case of this situation. The function removes an element by shifting the
4068 sequence elements between the nearest end of the sequence and the <code>index</code>-th position, not
4069 counting the latter.</p>
4070
4071
4072 <hr><h3><a name="decl_cvClearSeq">ClearSeq</a></h3>
4073 <p class="Blurb">Clears sequence</p>
4074 <pre>
4075 void cvClearSeq( CvSeq* seq );
4076 </pre><p><dl>
4077 <dt>seq<dd>Sequence.
4078 </dl><p>
4079 The function <code>cvClearSeq</code> removes all elements from the sequence. The function does not return the
4080 memory to the storage, but this memory is reused later when new elements are added
4081 to the sequence. This function time complexity is <code>O(1)</code>.
4082
4083
4084 <hr><h3><a name="decl_cvGetSeqElem">GetSeqElem</a></h3>
4085 <p class="Blurb">Returns pointer to sequence element by its index</p>
4086 <pre>
4087 char* cvGetSeqElem( const CvSeq* seq, int index );
4088 #define CV_GET_SEQ_ELEM( TYPE, seq, index )  (TYPE*)cvGetSeqElem( (CvSeq*)(seq), (index) )
4089 </pre><p><dl>
4090 <dt>seq<dd>Sequence.
4091 <dt>index<dd>Index of element.
4092 </dl><p>
4093 The function <code>cvGetSeqElem</code> finds the element with the given index in the sequence
4094 and returns the pointer to it. If the element is not found,
4095 the function returns 0. The function supports negative indices, where -1 stands
4096 for the last sequence element, -2 stands for the one before last, etc. If the
4097 sequence is most likely to consist of a single sequence block or the desired
4098 element is likely to be located in the first block, then the macro
4099 <code>CV_GET_SEQ_ELEM( elemType, seq, index )</code> should be used, where the parameter
4100 <code>elemType</code> is the type of sequence elements ( <a href="#decl_CvPoint">CvPoint</a> for example), the parameter
4101 <code>seq</code> is a sequence, and the parameter <code>index</code> is the index of the desired element.
4102 The macro checks first whether the desired element belongs to the first block of
4103 the sequence and returns it if it does, otherwise the macro calls the main
4104 function <code>GetSeqElem</code>. Negative indices always cause the <a href="#decl_cvGetSeqElem">cvGetSeqElem</a> call.
4105 The function has O(1) time complexity assuming that number of blocks is much smaller than the
4106 number of elements.</p>
4107
4108
4109 <hr><h3><a name="decl_cvSeqElemIdx">SeqElemIdx</a></h3>
4110 <p class="Blurb">Returns index of concrete sequence element</p>
4111 <pre>
4112 int cvSeqElemIdx( const CvSeq* seq, const void* element, CvSeqBlock** block=NULL );
4113 </pre><p><dl>
4114 <dt>seq<dd>Sequence.
4115 <dt>element<dd>Pointer to the element within the sequence.
4116 <dt>block<dd>Optional argument. If the pointer is not <code>NULL</code>, the address of the
4117 sequence block that contains the element is stored in this location.
4118 </dl><p>
4119 The function <code>cvSeqElemIdx</code> returns the index of a sequence element or a negative
4120 number if the element is not found.</p>
4121
4122
4123 <hr><h3><a name="decl_cvCvtSeqToArray">CvtSeqToArray</a></h3>
4124 <p class="Blurb">Copies sequence to one continuous block of memory</p>
4125 <pre>
4126 void* cvCvtSeqToArray( const CvSeq* seq, void* elements, CvSlice slice=CV_WHOLE_SEQ );
4127 </pre><p><dl>
4128 <dt>seq<dd>Sequence.
4129 <dt>elements<dd>Pointer to the destination array that must be large enough.
4130     It should be a pointer to data, not a matrix header.
4131 <dt>slice<dd>The sequence part to copy to the array.
4132 </dl><p>
4133 The function <code>cvCvtSeqToArray</code> copies the entire sequence or subsequence to the
4134 specified buffer and returns the pointer to the buffer.</p>
4135
4136
4137 <hr><h3><a name="decl_cvMakeSeqHeaderForArray">MakeSeqHeaderForArray</a></h3>
4138 <p class="Blurb">Constructs sequence from array</p>
4139 <pre>
4140 CvSeq* cvMakeSeqHeaderForArray( int seq_type, int header_size, int elem_size,
4141                                 void* elements, int total,
4142                                 CvSeq* seq, CvSeqBlock* block );
4143 </pre><p><dl>
4144 <dt>seq_type<dd>Type of the created sequence.
4145 <dt>header_size<dd>Size of the header of the sequence. Parameter sequence must point to
4146 the structure of that size or greater size.
4147 <dt>elem_size<dd>Size of the sequence element.
4148 <dt>elements<dd>Elements that will form a sequence.
4149 <dt>total<dd>Total number of elements in the sequence. The number of array elements
4150 must be equal to the value of this parameter.
4151 <dt>seq<dd>Pointer to the local variable that is used as the sequence header.
4152 <dt>block<dd>Pointer to the local variable that is the header of the single sequence
4153 block.
4154 </dl><p>
4155 The function <code>cvMakeSeqHeaderForArray</code> initializes sequence header for array.
4156 The sequence header as well as the sequence block are allocated by the user (for example, on stack).
4157 No data is copied by the function. The resultant sequence will consists of a single block and have
4158 NULL storage pointer, thus, it is possible to read its elements, but the attempts to
4159 add elements to the sequence will raise an error in most cases.</p>
4160
4161
4162 <hr><h3><a name="decl_cvSeqSlice">SeqSlice</a></h3>
4163 <p class="Blurb">Makes separate header for the sequence slice</p>
4164 <pre>
4165 CvSeq* cvSeqSlice( const CvSeq* seq, CvSlice slice,
4166                    CvMemStorage* storage=NULL, int copy_data=0 );
4167 </pre><p><dl>
4168 <dt>seq<dd>Sequence.
4169 <dt>slice<dd>The part of the sequence to extract.
4170 <dt>storage<dd>The destination storage to keep the new sequence header and the copied data if any.
4171                If it is NULL, the function uses the storage containing the input sequence.
4172 <dt>copy_data<dd>The flag that indicates whether to copy the elements of the extracted slice
4173                  (<code>copy_data</code>!=0) or not (<code>copy_data</code>=0)
4174 </dl><p>
4175 The function <code>cvSeqSlice</code> creates a sequence
4176 that represents the specified slice of the input sequence. The new sequence either shares the elements
4177 with the original sequence or has own copy of the elements.
4178 So if one needs to process a part of sequence but the processing function does not have a slice parameter,
4179 the required sub-sequence may be extracted using this function.
4180 </p>
4181
4182
4183 <hr><h3><a name="decl_cvCloneSeq">CloneSeq</a></h3>
4184 <p class="Blurb">Creates a copy of sequence</p>
4185 <pre>
4186 CvSeq* cvCloneSeq( const CvSeq* seq, CvMemStorage* storage=NULL );
4187 </pre><p><dl>
4188 <dt>seq<dd>Sequence.
4189 <dt>storage<dd>The destination storage to keep the new sequence header and the copied data if any.
4190                If it is NULL, the function uses the storage containing the input sequence.
4191 </dl><p>
4192 The function <code>cvCloneSeq</code> makes a complete copy of the input sequence and returns it.
4193 The call <code><a href="#decl_cvCloneSeq">cvCloneSeq</a>( seq, storage )</code> is equivalent to
4194 <code><a href="#decl_cvSeqSlice">cvSeqSlice</a>( seq, CV_WHOLE_SEQ, storage, 1 )</code>
4195 </p>
4196
4197
4198 <hr><h3><a name="decl_cvSeqRemoveSlice">SeqRemoveSlice</a></h3>
4199 <p class="Blurb">Removes sequence slice</p>
4200 <pre>
4201 void cvSeqRemoveSlice( CvSeq* seq, CvSlice slice );
4202 </pre><p><dl>
4203 <dt>seq<dd>Sequence.
4204 <dt>slice<dd>The part of the sequence to remove.
4205 </dl><p>
4206 The function <code>cvSeqRemoveSlice</code> removes slice from the sequence.</p>
4207
4208
4209 <hr><h3><a name="decl_cvSeqInsertSlice">SeqInsertSlice</a></h3>
4210 <p class="Blurb">Inserts array in the middle of sequence</p>
4211 <pre>
4212 void cvSeqInsertSlice( CvSeq* seq, int before_index, const CvArr* from_arr );
4213 </pre><p><dl>
4214 <dt>seq<dd>Sequence.
4215 <dt>slice<dd>The part of the sequence to remove.
4216 <dt>from_arr<dd>The array to take elements from.
4217 </dl><p>
4218 The function <code>cvSeqInsertSlice</code> inserts all <code>from_arr</code>
4219 array elements at the specified position of the sequence. The array <code>from_arr</code>
4220 can be a matrix or another sequence.</p>
4221
4222
4223 <hr><h3><a name="decl_cvSeqInvert">SeqInvert</a></h3>
4224 <p class="Blurb">Reverses the order of sequence elements</p>
4225 <pre>
4226 void cvSeqInvert( CvSeq* seq );
4227 </pre><p><dl>
4228 <dt>seq<dd>Sequence.
4229 </dl><p>
4230 The function <code>cvSeqInvert</code> reverses the sequence in-place - makes the first element go last,
4231 the last element go first etc.</p>
4232
4233
4234 <hr><h3><a name="decl_cvSeqSort">SeqSort</a></h3>
4235 <p class="Blurb">Sorts sequence element using the specified comparison function</p>
4236 <pre>
4237 /* a &lt; b ? -1 : a > b ? 1 : 0 */
4238 typedef int (CV_CDECL* CvCmpFunc)(const void* a, const void* b, void* userdata);
4239
4240 void cvSeqSort( CvSeq* seq, CvCmpFunc func, void* userdata=NULL );
4241 </pre><p><dl>
4242 <dt>seq<dd>The sequence to sort
4243 <dt>func<dd>The comparison function that returns negative, zero or positive value depending
4244             on the elements relation (see the above declaration and the example below) -
4245             similar function is used by <code>qsort</code> from C runtime except that in the latter
4246             <code>userdata</code> is not used
4247 <dt>userdata<dd>The user parameter passed to the comparison function;
4248                 helps to avoid global variables in some cases.
4249 </dl><p>
4250 The function <code>cvSeqSort</code> sorts the sequence in-place using the specified criteria.
4251 Below is the example of the function use:</p>
4252 <pre>
4253 /* Sort 2d points in top-to-bottom left-to-right order */
4254 static int cmp_func( const void* _a, const void* _b, void* userdata )
4255 {
4256     CvPoint* a = (CvPoint*)_a;
4257     CvPoint* b = (CvPoint*)_b;
4258     int y_diff = a->y - b->y;
4259     int x_diff = a->x - b->x;
4260     return y_diff ? y_diff : x_diff;
4261 }
4262
4263 ...
4264
4265 CvMemStorage* storage = cvCreateMemStorage(0);
4266 CvSeq* seq = cvCreateSeq( CV_32SC2, sizeof(CvSeq), sizeof(CvPoint), storage );
4267 int i;
4268
4269 for( i = 0; i &lt; 10; i++ )
4270 {
4271     CvPoint pt;
4272     pt.x = rand() % 1000;
4273     pt.y = rand() % 1000;
4274     cvSeqPush( seq, &pt );
4275 }
4276
4277 cvSeqSort( seq, cmp_func, 0 /* userdata is not used here */ );
4278
4279 /* print out the sorted sequence */
4280 for( i = 0; i &lt; seq->total; i++ )
4281 {
4282     CvPoint* pt = (CvPoint*)cvSeqElem( seq, i );
4283     printf( "(%d,%d)\n", pt->x, pt->y );
4284 }
4285
4286 cvReleaseMemStorage( &storage );
4287 </pre>
4288
4289
4290
4291 <hr><h3><a name="decl_cvSeqSearch">SeqSearch</a></h3>
4292 <p class="Blurb">Searches element in sequence</p>
4293 <pre>
4294 /* a &lt; b ? -1 : a > b ? 1 : 0 */
4295 typedef int (CV_CDECL* CvCmpFunc)(const void* a, const void* b, void* userdata);
4296
4297 char* cvSeqSearch( CvSeq* seq, const void* elem, CvCmpFunc func,
4298                    int is_sorted, int* elem_idx, void* userdata=NULL );
4299 </pre><p><dl>
4300 <dt>seq<dd>The sequence
4301 <dt>elem<dd>The element to look for
4302 <dt>func<dd>The comparison function that returns negative, zero or positive value depending
4303             on the elements relation (see also <a href="#decl_cvSeqSort">cvSeqSort</a>).
4304 <dt>is_sorted<dd>Whether the sequence is sorted or not.
4305 <dt>elem_idx<dd>Output parameter; index of the found element.
4306 <dt>userdata<dd>The user parameter passed to the comparison function;
4307                 helps to avoid global variables in some cases.
4308 </dl><p>
4309 The function <code>cvSeqSearch</code> searches the element in the sequence.
4310 If the sequence is sorted, binary O(log(N)) search is used, otherwise, a simple linear search is used.
4311 If the element is not found, the function returns NULL pointer and the index is set to the number of
4312 sequence elements if the linear search is used, and to the smallest index <code>i, seq(i)&gt;elem</code>.
4313 </p>
4314
4315
4316 <hr><h3><a name="decl_cvStartAppendToSeq">StartAppendToSeq</a></h3>
4317 <p class="Blurb">Initializes process of writing data to sequence</p>
4318 <pre>
4319 void cvStartAppendToSeq( CvSeq* seq, CvSeqWriter* writer );
4320 </pre><p><dl>
4321 <dt>seq<dd>Pointer to the sequence.
4322 <dt>writer<dd>Writer state; initialized by the function.
4323 </dl><p>
4324 The function <code>cvStartAppendToSeq</code> initializes the process of writing data to the sequence.
4325 Written elements are added to the end of the sequence by <code>CV_WRITE_SEQ_ELEM( written_elem, writer )</code> macro.
4326 Note that during the writing process other operations on the sequence may yield incorrect result or
4327 even corrupt the sequence (see description of <a href="#decl_cvFlushSeqWriter">cvFlushSeqWriter</a> that helps to avoid
4328 some of these problems).</p>
4329
4330
4331 <hr><h3><a name="decl_cvStartWriteSeq">StartWriteSeq</a></h3>
4332 <p class="Blurb">Creates new sequence and initializes writer for it</p>
4333 <pre>
4334 void cvStartWriteSeq( int seq_flags, int header_size, int elem_size,
4335                       CvMemStorage* storage, CvSeqWriter* writer );
4336 </pre><p><dl>
4337 <dt>seq_flags<dd>Flags of the created sequence. If the sequence is not passed to any
4338 function working with a specific type of sequences, the sequence value may be
4339 equal to 0, otherwise the appropriate type must be selected from the list of
4340 predefined sequence types.
4341 <dt>header_size<dd>Size of the sequence header. The parameter value may not be less than
4342 <code>sizeof(CvSeq)</code>. If a certain type or extension is specified, it must fit the
4343 base type header.
4344 <dt>elem_size<dd>Size of the sequence elements in bytes; must be consistent with the
4345 sequence type. For example, if the sequence of points is created (element type
4346 <code>CV_SEQ_ELTYPE_POINT</code> ), then the parameter elem_size must be equal to
4347 <code>sizeof(CvPoint)</code>.
4348 <dt>storage<dd>Sequence location.
4349 <dt>writer<dd>Writer state; initialized by the function.
4350 </dl><p>
4351 The function <code>cvStartWriteSeq</code> is a composition of <a href="#decl_cvCreateSeq">cvCreateSeq</a> and <a href="#decl_cvStartAppendToSeq">cvStartAppendToSeq</a>.
4352 The pointer to the created sequence is stored at <code>writer->seq</code> and is also returned
4353 by <a href="#decl_cvEndWriteSeq">cvEndWriteSeq</a> function that should be called in the end.</p>
4354
4355
4356 <hr><h3><a name="decl_cvEndWriteSeq">EndWriteSeq</a></h3>
4357 <p class="Blurb">Finishes process of writing sequence</p>
4358 <pre>
4359 CvSeq* cvEndWriteSeq( CvSeqWriter* writer );
4360 </pre><p><dl>
4361 <dt>writer<dd>Writer state
4362 </dl><p>
4363 The function <code>cvEndWriteSeq</code> finishes the writing process and returns the pointer to
4364 the written sequence. The function also truncates the last incomplete sequence block to
4365 return the remaining part of the block to the memory storage. After that the sequence
4366 can be read and modified safely.</p>
4367
4368
4369 <hr><h3><a name="decl_cvFlushSeqWriter">FlushSeqWriter</a></h3>
4370 <p class="Blurb">Updates sequence headers from the writer state</p>
4371 <pre>
4372 void cvFlushSeqWriter( CvSeqWriter* writer );
4373 </pre><p><dl>
4374 <dt>writer<dd>Writer state
4375 </dl><p>
4376 The function <code>cvFlushSeqWriter</code> is intended to enable the user to read sequence
4377 elements, whenever required, during the writing process, e.g., in order to check
4378 specific conditions. The function updates the sequence headers to make reading
4379 from the sequence possible. The writer is not closed, however, so that the
4380 writing process can be continued any time. If some algorithm requires often flushes,
4381 consider using <a href="#decl_cvSeqPush">cvSeqPush</a> instead.</p>
4382
4383
4384 <hr><h3><a name="decl_cvStartReadSeq">StartReadSeq</a></h3>
4385 <p class="Blurb">Initializes process of sequential reading from sequence</p>
4386 <pre>
4387 void cvStartReadSeq( const CvSeq* seq, CvSeqReader* reader, int reverse=0 );
4388 </pre><p><dl>
4389 <dt>seq<dd>Sequence.
4390 <dt>reader<dd>Reader state; initialized by the function.
4391 <dt>reverse<dd>Determines the direction of the sequence traversal. If <code>reverse</code> is 0,
4392 the reader is positioned at the first sequence element, otherwise it is positioned at the last
4393 element.
4394 </dl><p>
4395 The function <code>cvStartReadSeq</code> initializes the reader state. After that all the
4396 sequence elements from the first down to the last one can be read by subsequent
4397 calls of the macro <code>CV_READ_SEQ_ELEM( read_elem, reader )</code> in case of forward reading
4398 and by using <code>CV_REV_READ_SEQ_ELEM( read_elem, reader )</code> in case of reversed reading.
4399 Both macros put the sequence element to <code>read_elem</code> and move the
4400 reading pointer toward the next element.
4401 A circular structure of sequence blocks is used for the reading process, that
4402 is, after the last element has been read by the macro <code>CV_READ_SEQ_ELEM</code>, the
4403 first element is read when the macro is called again. The same applies to
4404 <code>CV_REV_READ_SEQ_ELEM </code>. There is no function to finish the reading process,
4405 since it neither changes the sequence nor creates any temporary buffers. The reader
4406 field <code>ptr</code> points to the current element of the sequence that is to be read
4407 next. The code below demonstrates how to use sequence writer and reader.</p>
4408 <pre>
4409 CvMemStorage* storage = cvCreateMemStorage(0);
4410 CvSeq* seq = cvCreateSeq( CV_32SC1, sizeof(CvSeq), sizeof(int), storage );
4411 CvSeqWriter writer;
4412 CvSeqReader reader;
4413 int i;
4414
4415 cvStartAppendToSeq( seq, &writer );
4416 for( i = 0; i &lt; 10; i++ )
4417 {
4418     int val = rand()%100;
4419     CV_WRITE_SEQ_ELEM( val, writer );
4420     printf("%d is written\n", val );
4421 }
4422 cvEndWriteSeq( &writer );
4423
4424 cvStartReadSeq( seq, &reader, 0 );
4425 for( i = 0; i &lt; seq->total; i++ )
4426 {
4427     int val;
4428 #if 1
4429     CV_READ_SEQ_ELEM( val, reader );
4430     printf("%d is read\n", val );
4431 #else /* alternative way, that is preferable if sequence elements are large,
4432          or their size/type is unknown at compile time */
4433     printf("%d is read\n", *(int*)reader.ptr );
4434     CV_NEXT_SEQ_ELEM( seq->elem_size, reader );
4435 #endif
4436 }
4437 ...
4438
4439 cvReleaseStorage( &storage );
4440 </pre>
4441
4442
4443 <hr><h3><a name="decl_cvGetSeqReaderPos">GetSeqReaderPos</a></h3>
4444 <p class="Blurb">Returns the current reader position</p>
4445 <pre>
4446 int cvGetSeqReaderPos( CvSeqReader* reader );
4447 </pre><p><dl>
4448 <dt>reader<dd>Reader state.
4449 </dl><p>
4450 The function <code>cvGetSeqReaderPos</code> returns the current reader position
4451 (within 0 ... <code>reader->seq->total</code> - 1).</p>
4452
4453
4454 <hr><h3><a name="decl_cvSetSeqReaderPos">SetSeqReaderPos</a></h3>
4455 <p class="Blurb">Moves the reader to specified position</p>
4456 <pre>
4457 void cvSetSeqReaderPos( CvSeqReader* reader, int index, int is_relative=0 );
4458 </pre><p><dl>
4459
4460 <dt>reader<dd>Reader state.
4461 <dt>index<dd>The destination position. If the positioning mode is used (see the next parameter)
4462              the actual position will be <code>index</code> mod <code>reader->seq->total</code>.
4463 <dt>is_relative<dd>If it is not zero, then <code>index</code> is a relative to the current position.
4464 </dl><p>
4465 The function <code>cvSetSeqReaderPos</code> moves the read position to the absolute position or
4466 relative to the current position.
4467 </p>
4468
4469
4470 <hr><h2><a name="cxcore_ds_sets">Sets</a></h2>
4471
4472 <hr><h3><a name="decl_CvSet">CvSet</a></h3>
4473 <p class="Blurb">Collection of nodes</p>
4474 <pre>
4475     typedef struct CvSetElem
4476     {
4477         int flags; /* it is negative if the node is free and zero or positive otherwise */
4478         struct CvSetElem* next_free; /* if the node is free, the field is a
4479                                         pointer to next free node */
4480     }
4481     CvSetElem;
4482
4483     #define CV_SET_FIELDS()    \
4484         CV_SEQUENCE_FIELDS()   /* inherits from <a href="#decl_CvSeq">CvSeq</a> */ \
4485         struct CvSetElem* free_elems; /* list of free nodes */
4486
4487     typedef struct CvSet
4488     {
4489         CV_SET_FIELDS()
4490     } CvSet;
4491 </pre>
4492 <p>
4493 The structure <a href="#decl_CvSet">CvSet</a> is a base for OpenCV sparse data structures.</p>
4494 <p>As follows from the above declaration <a href="#decl_CvSet">CvSet</a> inherits from <a href="#decl_CvSeq">CvSeq</a>
4495 and it adds <code>free_elems</code> field it to, which is a list of free nodes.
4496 Every set node, whether free or not, is the element of the underlying sequence.
4497 While there is no restrictions on elements of dense sequences, the set (and derived structures)
4498 elements must start with integer field and be able to fit CvSetElem structure, because
4499 these two fields (integer followed by the pointer) are required for organization of node set with
4500 the list of free nodes. If a node is free, <code>flags</code> field is negative (the most-significant
4501 bit, or MSB, of the field is set), and <code>next_free</code>
4502 points to the next free node (the first free node is referenced by <code>free_elems</code> field of
4503 <a href="#decl_CvSet">CvSet</a>). And if a node is occupied, <code>flags</code> field is positive and contains the node index
4504 that may be retrieved using (set_elem->flags & CV_SET_ELEM_IDX_MASK) expression,
4505 the rest of the node content is determined by the user. In particular, the occupied nodes
4506 are not linked as the free nodes are, so the second field can be used for such a link as well as
4507 for some different purpose. The macro <code>CV_IS_SET_ELEM(set_elem_ptr)</code>
4508 can be used to determined whether the specified node is occupied or not.</p>
4509 <p>
4510 Initially the set and the list are empty. When a new node is requested from the set,
4511 it is taken from the list of free nodes, which is updated then. If the list appears to be empty,
4512 a new sequence block is allocated and all the nodes within the block are joined in the list of free
4513 nodes. Thus, <code>total</code> field of the set is the total number of nodes both occupied and free.
4514 When an occupied node is released, it is added to the list of free nodes. The node released last
4515 will be occupied first.</p>
4516 <p>In OpenCV <a href="#decl_CvSet">CvSet</a> is used for representing graphs (<a href="#decl_CvGraph">CvGraph</a>),
4517 sparse multi-dimensional arrays (<a href="#decl_CvSparseMat">CvSparseMat</a>), planar subdivisions (<a href="#decl_CvSubdiv2D">CvSubdiv2D</a>) etc.</p>
4518
4519
4520 <hr><h3><a name="decl_cvCreateSet">CreateSet</a></h3>
4521 <p class="Blurb">Creates empty set</p>
4522 <pre>
4523 CvSet* cvCreateSet( int set_flags, int header_size,
4524                     int elem_size, CvMemStorage* storage );
4525 </pre><p><dl>
4526 <dt>set_flags<dd>Type of the created set.
4527 <dt>header_size<dd>Set header size; may not be less than <code>sizeof(CvSet)</code>.
4528 <dt>elem_size<dd>Set element size; may not be less than <a href="#decl_CvSetElem">CvSetElem</a>.
4529 <dt>storage<dd>Container for the set.
4530 </dl><p>
4531 The function <code>cvCreateSet</code> creates an empty set with a specified header size and element size, and
4532 returns the pointer to the set. The function is just a thin layer on top of <a href="#decl_cvCreateSeq">cvCreateSeq</a>.</p>
4533
4534
4535 <hr><h3><a name="decl_cvSetAdd">SetAdd</a></h3>
4536 <p class="Blurb">Occupies a node in the set</p>
4537 <pre>
4538 int cvSetAdd( CvSet* set_header, CvSetElem* elem=NULL, CvSetElem** inserted_elem=NULL );
4539 </pre><p><dl>
4540 <dt>set_header<dd>Set.
4541 <dt>elem<dd>Optional input argument, inserted element. If not NULL, the function
4542 copies the data to the allocated node (The MSB of the first integer field is cleared after copying).
4543 <dt>inserted_elem<dd>Optional output argument; the pointer to the allocated cell.
4544 </dl><p>
4545 The function <code>cvSetAdd</code> allocates a new node, optionally copies input element data
4546 to it, and returns the pointer and the index to the node. The index value is
4547 taken from the lower bits of <code>flags</code> field of the node. The function has O(1) complexity,
4548 however there exists a faster function for allocating set nodes (see <a href="#decl_cvSetNew">cvSetNew</a>).
4549 </p>
4550
4551
4552 <hr><h3><a name="decl_cvSetRemove">SetRemove</a></h3>
4553 <p class="Blurb">Removes element from set</p>
4554 <pre>
4555 void cvSetRemove( CvSet* set_header, int index );
4556 </pre><p><dl>
4557 <dt>set_header<dd>Set.
4558 <dt>index<dd>Index of the removed element.
4559 </dl><p>
4560 The function <code>cvSetRemove</code> removes an element with a specified index from the set.
4561 If the node at the specified location is not occupied the function does nothing.
4562 The function has O(1) complexity, however, <a href="#decl_cvSetRemoveByPtr">cvSetRemoveByPtr</a> provides yet
4563 faster way to remove a set element if it is located already.</p>
4564
4565
4566 <hr><h3><a name="decl_cvSetNew">SetNew</a></h3>
4567 <p class="Blurb">Adds element to set (fast variant)</p>
4568 <pre>
4569 CvSetElem* cvSetNew( CvSet* set_header );
4570 </pre><p><dl>
4571 <dt>set_header<dd>Set.
4572 </dl><p>
4573 The function <code>cvSetNew</code> is inline light-weight variant of <a href="#decl_cvSetAdd">cvSetAdd</a>.
4574 It occupies a new node and returns pointer to it rather than index.</p>
4575
4576
4577 <hr><h3><a name="decl_cvSetRemoveByPtr">SetRemoveByPtr</a></h3>
4578 <p class="Blurb">Removes set element given its pointer</p>
4579 <pre>
4580 void cvSetRemoveByPtr( CvSet* set_header, void* elem );
4581 </pre><p><dl>
4582 <dt>set_header<dd>Set.
4583 <dt>elem<dd>Removed element.
4584 </dl><p>
4585 The function <code>cvSetRemoveByPtr</code> is inline light-weight variant of <a href="#decl_cvSetRemove">cvSetRemove</a>
4586 that takes element pointer.
4587 The function does not check whether the node is occupied or not - the user should take care of it.</p>
4588
4589
4590 <hr><h3><a name="decl_cvGetSetElem">GetSetElem</a></h3>
4591 <p class="Blurb">Finds set element by its index</p>
4592 <pre>
4593 CvSetElem* cvGetSetElem( const CvSet* set_header, int index );
4594 </pre><p><dl>
4595 <dt>set_header<dd>Set.
4596 <dt>index<dd>Index of the set element within a sequence.
4597 </dl><p>
4598 The function <code>cvGetSetElem</code> finds a set element by index. The function returns the
4599 pointer to it or 0 if the index is invalid or the corresponding node is free.
4600 The function supports negative indices as it uses <a href="#decl_cvGetSeqElem">cvGetSeqElem</a> to locate the node.</p>
4601 </p>
4602
4603
4604 <hr><h3><a name="decl_cvClearSet">ClearSet</a></h3>
4605 <p class="Blurb">Clears set</p>
4606 <pre>
4607 void cvClearSet( CvSet* set_header );
4608 </pre><p><dl>
4609 <dt>set_header<dd>Cleared set.
4610 </dl><p>
4611 The function <code>cvClearSet</code> removes all elements from set. It has O(1) time complexity.</p>
4612
4613
4614 <hr><h2><a name="cxcore_ds_graphs">Graphs</a></h2>
4615
4616 <hr><h3><a name="decl_CvGraph">CvGraph</a></h3>
4617 <p class="Blurb">Oriented or undirected weighted graph</p>
4618 <pre>
4619     #define CV_GRAPH_VERTEX_FIELDS()    \
4620         int flags; /* vertex flags */   \
4621         struct CvGraphEdge* first; /* the first incident edge */
4622
4623     typedef struct CvGraphVtx
4624     {
4625         CV_GRAPH_VERTEX_FIELDS()
4626     }
4627     CvGraphVtx;
4628
4629     #define CV_GRAPH_EDGE_FIELDS()      \
4630         int flags; /* edge flags */     \
4631         float weight; /* edge weight */ \
4632         struct CvGraphEdge* next[2]; /* the next edges in the incidence lists for staring (0) */ \
4633                                      /* and ending (1) vertices */ \
4634         struct CvGraphVtx* vtx[2]; /* the starting (0) and ending (1) vertices */
4635
4636     typedef struct CvGraphEdge
4637     {
4638         CV_GRAPH_EDGE_FIELDS()
4639     }
4640     CvGraphEdge;
4641
4642     #define  CV_GRAPH_FIELDS()                  \
4643         CV_SET_FIELDS() /* set of vertices */   \
4644         CvSet* edges;   /* set of edges */
4645
4646     typedef struct CvGraph
4647     {
4648         CV_GRAPH_FIELDS()
4649     }
4650     CvGraph;
4651
4652 </pre>
4653 <p>
4654 The structure <a href="#decl_CvGraph">CvGraph</a> is a base for graphs used in OpenCV.</p>
4655 <p>Graph structure inherits from <a href="#decl_CvSet">CvSet</a> - this part describes common graph properties and
4656 the graph vertices, and contains another set as a member - this part describes the graph edges.</p>
4657 <p>The vertex, edge and the graph header structures are declared using the same technique as other
4658 extendible OpenCV structures - via macros, that simplifies extension and customization of the structures.
4659 While the vertex and edge structures do not inherit from <a href="#decl_CvSetElem">CvSetElem</a> explicitly, they satisfy
4660 both conditions on the set elements - have an integer field in the beginning and fit CvSetElem structure.
4661 The <code>flags</code> fields are used as for indicating occupied vertices and edges as well as
4662 for other purposes, for example, for graph traversal (see <a href="#decl_cvCreateGraphScanner">cvCreateGraphScanner</a> et al.), so
4663 it is better not to use them directly.</p>
4664 <p>The graph is represented as a set of edges each of whose has the list of incident edges. The incidence
4665 lists for different vertices are interleaved to avoid information duplication as much as possible.</p>
4666 <p>The graph may be oriented or undirected. In the latter case there is no distinction between edge
4667 connecting vertex A with vertex B and the edge connecting vertex B with vertex A - only one of them
4668 can exist in the graph at the same moment and it represents both &lt;A, B&gt; and &lt;B, A&gt; edges..</p>
4669
4670
4671
4672 <hr><h3><a name="decl_cvCreateGraph">CreateGraph</a></h3>
4673 <p class="Blurb">Creates empty graph</p>
4674 <pre>
4675 CvGraph* cvCreateGraph( int graph_flags, int header_size, int vtx_size,
4676                         int edge_size, CvMemStorage* storage );
4677 </pre><p><dl>
4678 <dt>graph_flags<dd>Type of the created graph. Usually, it is either <code>CV_SEQ_KIND_GRAPH</code>
4679 for generic undirected graphs and <code>CV_SEQ_KIND_GRAPH | CV_GRAPH_FLAG_ORIENTED</code> for generic oriented graphs.
4680 <dt>header_size<dd>Graph header size; may not be less than <code>sizeof(CvGraph).</code>
4681 <dt>vtx_size<dd>Graph vertex size; the custom vertex structure must start with <a href="#decl_CvGraphVtx">CvGraphVtx</a>
4682                   (use <code>CV_GRAPH_VERTEX_FIELDS()</code>)
4683 <dt>edge_size<dd>Graph edge size; the custom edge structure must start with <a href="#decl_CvGraphEdge">CvGraphEdge</a>
4684                 (use <code>CV_GRAPH_EDGE_FIELDS()</code>)
4685 <dt>storage<dd>The graph container.
4686 </dl><p>
4687 The function <code>cvCreateGraph</code> creates an empty graph and returns pointer to it.</p>
4688
4689
4690 <hr><h3><a name="decl_cvGraphAddVtx">GraphAddVtx</a></h3>
4691 <p class="Blurb">Adds vertex to graph</p>
4692 <pre>
4693 int cvGraphAddVtx( CvGraph* graph, const CvGraphVtx* vtx=NULL,
4694                    CvGraphVtx** inserted_vtx=NULL );
4695 </pre><p><dl>
4696 <dt>graph<dd>Graph.
4697 <dt>vtx<dd>Optional input argument used to initialize the added vertex (only user-defined fields
4698 beyond <code>sizeof(CvGraphVtx)</code> are copied).
4699 <dt>inserted_vertex<dd>Optional output argument. If not <code>NULL</code>, the address of the new
4700 vertex is written there.
4701 </dl><p>
4702 The function <code>cvGraphAddVtx</code> adds a vertex to the graph and returns the vertex
4703 index.</p>
4704
4705
4706 <hr><h3><a name="decl_cvGraphRemoveVtx">GraphRemoveVtx</a></h3>
4707 <p class="Blurb">Removes vertex from graph</p>
4708 <pre>
4709 int cvGraphRemoveVtx( CvGraph* graph, int index );
4710 </pre><p><dl>
4711 <dt>graph<dd>Graph.
4712 <dt>vtx_idx<dd>Index of the removed vertex.
4713 </dl><p>
4714 The function <code>cvGraphRemoveAddVtx</code> removes a vertex from the graph together with all
4715 the edges incident to it. The function reports an error, if the input vertex does
4716 not belong to the graph. The return value is number of edges deleted,
4717 or -1 if the vertex does not belong to the graph.</p>
4718
4719
4720 <hr><h3><a name="decl_cvGraphRemoveVtxByPtr">GraphRemoveVtxByPtr</a></h3>
4721 <p class="Blurb">Removes vertex from graph</p>
4722 <pre>
4723 int cvGraphRemoveVtxByPtr( CvGraph* graph, CvGraphVtx* vtx );
4724 </pre><p><dl>
4725 <dt>graph<dd>Graph.
4726 <dt>vtx<dd>Pointer to the removed vertex.
4727 </dl><p>
4728 The function <code>cvGraphRemoveVtxByPtr</code> removes a vertex from the graph together with
4729 all the edges incident to it. The function reports an error, if the vertex does not belong to the graph.
4730 The return value is number of edges deleted, or -1 if the vertex does not belong to the graph.</p>
4731
4732
4733 <hr><h3><a name="decl_cvGetGraphVtx">GetGraphVtx</a></h3>
4734 <p class="Blurb">Finds graph vertex by index</p>
4735 <pre>
4736 CvGraphVtx* cvGetGraphVtx( CvGraph* graph, int vtx_idx );
4737 </pre><p><dl>
4738 <dt>graph<dd>Graph.
4739 <dt>vtx_idx<dd>Index of the vertex.
4740 </dl><p>
4741 The function <code>cvGetGraphVtx</code> finds the graph vertex by index and returns the pointer
4742 to it or NULL if the vertex does not belong to the graph.</p>
4743
4744
4745 <hr><h3><a name="decl_cvGraphVtxIdx">GraphVtxIdx</a></h3>
4746 <p class="Blurb">Returns index of graph vertex</p>
4747 <pre>
4748 int cvGraphVtxIdx( CvGraph* graph, CvGraphVtx* vtx );
4749 </pre><p><dl>
4750 <dt>graph<dd>Graph.
4751 <dt>vtx<dd>Pointer to the graph vertex.
4752 </dl><p>
4753 The function <code>cvGraphVtxIdx</code> returns index of the graph vertex.</p>
4754
4755
4756 <hr><h3><a name="decl_cvGraphAddEdge">GraphAddEdge</a></h3>
4757 <p class="Blurb">Adds edge to graph</p>
4758 <pre>
4759 int cvGraphAddEdge( CvGraph* graph, int start_idx, int end_idx,
4760                     const CvGraphEdge* edge=NULL, CvGraphEdge** inserted_edge=NULL );
4761 </pre><p><dl>
4762 <dt>graph<dd>Graph.
4763 <dt>start_idx<dd>Index of the starting vertex of the edge.
4764 <dt>end_idx<dd>Index of the ending vertex of the edge. For undirected graph the order of the vertex
4765 parameters does not matter.
4766 <dt>edge<dd>Optional input parameter, initialization data for the edge.
4767 <dt>inserted_edge<dd>Optional output parameter to contain the address of the inserted
4768 edge.
4769 </dl><p>
4770 The function <code>cvGraphAddEdge</code> connects two specified vertices.
4771 The function returns 1 if the edge has been added successfully, 0 if the edge connecting
4772 the two vertices exists already and -1 if either of the vertices was not found, the starting and
4773 the ending vertex are the same or there is some other critical situation. In the latter case
4774 (i.e. when the result is negative) the function also reports an error by default.</p>
4775
4776
4777 <hr><h3><a name="decl_cvGraphAddEdgeByPtr">GraphAddEdgeByPtr</a></h3>
4778 <p class="Blurb">Adds edge to graph</p>
4779 <pre>
4780 int cvGraphAddEdgeByPtr( CvGraph* graph, CvGraphVtx* start_vtx, CvGraphVtx* end_vtx,
4781                          const CvGraphEdge* edge=NULL, CvGraphEdge** inserted_edge=NULL );
4782 </pre><p><dl>
4783 <dt>graph<dd>Graph.
4784 <dt>start_vtx<dd>Pointer to the starting vertex of the edge.
4785 <dt>end_vtx<dd>Pointer to the ending vertex of the edge. For undirected graph the order of the vertex
4786 parameters does not matter.
4787 <dt>edge<dd>Optional input parameter, initialization data for the edge.
4788 <dt>inserted_edge<dd>Optional output parameter to contain the address of the inserted
4789 edge within the edge set.
4790 </dl><p>
4791 The function <code>cvGraphAddEdge</code> connects two specified vertices.
4792 The function returns 1 if the edge has been added successfully, 0 if the edge connecting
4793 the two vertices exists already and -1 if either of the vertices was not found, the starting and
4794 the ending vertex are the same or there is some other critical situation. In the latter case
4795 (i.e. when the result is negative) the function also reports an error by default.</p>
4796
4797
4798 <hr><h3><a name="decl_cvGraphRemoveEdge">GraphRemoveEdge</a></h3>
4799 <p class="Blurb">Removes edge from graph</p>
4800 <pre>
4801 void cvGraphRemoveEdge( CvGraph* graph, int start_idx, int end_idx );
4802 </pre><p><dl>
4803 <dt>graph<dd>Graph.
4804 <dt>start_idx<dd>Index of the starting vertex of the edge.
4805 <dt>end_idx<dd>Index of the ending vertex of the edge. For undirected graph the order of the vertex
4806 parameters does not matter.
4807 </dl><p>
4808 The function <code>cvGraphRemoveEdge</code> removes the edge connecting two specified vertices.
4809 If the vertices are not connected [in that order], the function does nothing.
4810 </p>
4811
4812
4813 <hr><h3><a name="decl_cvGraphRemoveEdgeByPtr">GraphRemoveEdgeByPtr</a></h3>
4814 <p class="Blurb">Removes edge from graph</p>
4815 <pre>
4816 void cvGraphRemoveEdgeByPtr( CvGraph* graph, CvGraphVtx* start_vtx, CvGraphVtx* end_vtx );
4817 </pre><p><dl>
4818 <dt>graph<dd>Graph.
4819 <dt>start_vtx<dd>Pointer to the starting vertex of the edge.
4820 <dt>end_vtx<dd>Pointer to the ending vertex of the edge. For undirected graph the order of the vertex
4821 parameters does not matter.
4822 </dl><p>
4823 The function <code>cvGraphRemoveEdgeByPtr</code> removes the edge connecting two specified vertices.
4824 If the vertices are not connected [in that order], the function does nothing.</p>
4825
4826
4827 <hr><h3><a name="decl_cvFindGraphEdge">FindGraphEdge</a></h3>
4828 <p class="Blurb">Finds edge in graph</p>
4829 <pre>
4830 CvGraphEdge* cvFindGraphEdge( const CvGraph* graph, int start_idx, int end_idx );
4831 #define cvGraphFindEdge cvFindGraphEdge
4832 </pre><p><dl>
4833 <dt>graph<dd>Graph.
4834 <dt>start_idx<dd>Index of the starting vertex of the edge.
4835 <dt>end_idx<dd>Index of the ending vertex of the edge. For undirected graph the order of the vertex
4836 parameters does not matter.
4837 </dl><p>
4838 The function <code>cvFindGraphEdge</code> finds the graph edge connecting two specified vertices
4839 and returns pointer to it or NULL if the edge does not exists.</p>
4840
4841
4842 <hr><h3><a name="decl_cvFindGraphEdgeByPtr">FindGraphEdgeByPtr</a></h3>
4843 <p class="Blurb">Finds edge in graph</p>
4844 <pre>
4845 CvGraphEdge* cvFindGraphEdgeByPtr( const CvGraph* graph, const CvGraphVtx* start_vtx,
4846                                    const CvGraphVtx* end_vtx );
4847 #define cvGraphFindEdgeByPtr cvFindGraphEdgeByPtr
4848 </pre><p><dl>
4849 <dt>graph<dd>Graph.
4850 <dt>start_vtx<dd>Pointer to the starting vertex of the edge.
4851 <dt>end_vtx<dd>Pointer to the ending vertex of the edge. For undirected graph the order of the vertex
4852 parameters does not matter.
4853 </dl><p>
4854 The function <code>cvFindGraphEdge</code> finds the graph edge connecting two specified vertices
4855 and returns pointer to it or NULL if the edge does not exists.</p>
4856
4857
4858 <hr><h3><a name="decl_cvGraphEdgeIdx">GraphEdgeIdx</a></h3>
4859 <p class="Blurb">Returns index of graph edge</p>
4860 <pre>
4861 int cvGraphEdgeIdx( CvGraph* graph, CvGraphEdge* edge );
4862 </pre><p><dl>
4863 <dt>graph<dd>Graph.
4864 <dt>edge<dd>Pointer to the graph edge.
4865 </dl><p>
4866 The function <code>cvGraphEdgeIdx</code> returns index of the graph edge.</p>
4867
4868
4869 <hr><h3><a name="decl_cvGraphVtxDegree">GraphVtxDegree</a></h3>
4870 <p class="Blurb">Counts edges incident to the vertex</p>
4871 <pre>
4872 int cvGraphVtxDegree( const CvGraph* graph, int vtx_idx );
4873 </pre><p><dl>
4874 <dt>graph<dd>Graph.
4875 <dt>vtx<dd>Index of the graph vertex.
4876 </dl><p>
4877 The function <code>cvGraphVtxDegree</code> returns the number of edges
4878 incident to the specified vertex, both incoming and outgoing.
4879 To count the edges, the following code is used:</p>
4880 <pre>
4881     CvGraphEdge* edge = vertex->first; int count = 0;
4882     while( edge )
4883     {
4884         edge = CV_NEXT_GRAPH_EDGE( edge, vertex );
4885         count++;
4886     }
4887 </pre>
4888 <p>The macro <code>CV_NEXT_GRAPH_EDGE( edge, vertex )</code> returns the edge incident to <code>vertex</code>
4889 that follows after <code>edge</code>.</p>
4890
4891
4892 <hr><h3><a name="decl_cvGraphVtxDegreeByPtr">GraphVtxDegreeByPtr</a></h3>
4893 <p class="Blurb">Finds edge in graph</p>
4894 <pre>
4895 int cvGraphVtxDegreeByPtr( const CvGraph* graph, const CvGraphVtx* vtx );
4896 </pre><p><dl>
4897 <dt>graph<dd>Graph.
4898 <dt>vtx<dd>Pointer to the graph vertex.
4899 </dl><p>
4900 The function <code>cvGraphVtxDegree</code> returns the number of edges
4901 incident to the specified vertex, both incoming and outgoing.</p>
4902
4903
4904 <hr><h3><a name="decl_cvClearGraph">ClearGraph</a></h3>
4905 <p class="Blurb">Clears graph</p>
4906 <pre>
4907 void cvClearGraph( CvGraph* graph );
4908 </pre><p><dl>
4909 <dt>graph<dd>Graph.
4910 </dl><p>
4911 The function <code>cvClearGraph</code> removes all vertices and edges from the graph.
4912 The function has O(1) time complexity.</p>
4913
4914
4915 <hr><h3><a name="decl_cvCloneGraph">CloneGraph</a></h3>
4916 <p class="Blurb">Clone graph</p>
4917 <pre>
4918 CvGraph* cvCloneGraph( const CvGraph* graph, CvMemStorage* storage );
4919 </pre><p><dl>
4920 <dt>graph<dd>The graph to copy.
4921 <dt>storage<dd>Container for the copy.
4922 </dl><p>
4923 The function <code>cvCloneGraph</code> creates full copy of the graph. If the graph vertices
4924 or edges have pointers to some external data, it still be shared between the copies.
4925 The vertex and edge indices in the new graph may be different from the original, because
4926 the function defragments the vertex and edge sets.</p>
4927
4928
4929 <hr><h3><a name="decl_CvGraphScanner">CvGraphScanner</a></h3>
4930 <p class="Blurb">Graph traversal state</p>
4931 <pre>
4932     typedef struct CvGraphScanner
4933     {
4934         CvGraphVtx* vtx;       /* current graph vertex (or current edge origin) */
4935         CvGraphVtx* dst;       /* current graph edge destination vertex */
4936         CvGraphEdge* edge;     /* current edge */
4937
4938         CvGraph* graph;        /* the graph */
4939         CvSeq*   stack;        /* the graph vertex stack */
4940         int      index;        /* the lower bound of certainly visited vertices */
4941         int      mask;         /* event mask */
4942     }
4943     CvGraphScanner;
4944 </pre>
4945 <p>The structure <a href="#decl_CvGraphScanner">CvGraphScanner</a> is used for depth-first graph traversal.
4946 See discussion of the functions below.</p>
4947
4948
4949 <hr><h3><a name="decl_cvCreateGraphScanner">CreateGraphScanner</a></h3>
4950 <p class="Blurb">Creates structure for depth-first graph traversal</p>
4951 <pre>
4952 CvGraphScanner*  cvCreateGraphScanner( CvGraph* graph, CvGraphVtx* vtx=NULL,
4953                                        int mask=CV_GRAPH_ALL_ITEMS );
4954 </pre><p><dl>
4955 <dt>graph<dd>Graph.
4956 <dt>vtx<dd>Initial vertex to start from. If NULL, the traversal starts from the first vertex (a vertex with the
4957            minimal index in the sequence of vertices).
4958 <dt>mask<dd>Event mask indicating which events are interesting to the user (where <a href="#decl_cvNextGraphItem">cvNextGraphItem</a>
4959             function returns control to the user)
4960             It can be <code>CV_GRAPH_ALL_ITEMS</code> (all events are interesting)
4961             or combination of the following flags:<ul>
4962             <li>CV_GRAPH_VERTEX - stop at the graph vertices visited for the first time<br>
4963             <li>CV_GRAPH_TREE_EDGE - stop at tree edges (<code>tree edge</code> is the edge connecting the last visited vertex and
4964                                  the vertex to be visited next)<br>
4965             <li>CV_GRAPH_BACK_EDGE - stop at back edges (<code>back edge</code> is an edge connecting
4966                                  the last visited vertex with some of its ancestors in the search tree)<br>
4967             <li>CV_GRAPH_FORWARD_EDGE - stop at forward edges (<code>forward edge</code> is an edge connecting
4968                                  the last visited vertex with some of its descendants in the search tree).
4969                                  The <code>forward edges</code> are only possible during oriented graph traversal)<br>
4970             <li>CV_GRAPH_CROSS_EDGE - stop at cross edges (<code>cross edge</code> is an edge connecting different search trees or
4971                                  branches of the same tree.
4972                                  The <code>cross edges</code> are only possible during oriented graphs traversal)<br>
4973             <li>CV_GRAPH_ANY_EDGE - stop and any edge (<code>tree, back, forward</code> and <code>cross edges</code>)<br>
4974             <li>CV_GRAPH_NEW_TREE - stop in the beginning of every new search tree. When the traversal procedure
4975                                 visits all vertices and edges reachable from the initial vertex (the visited vertices
4976                                 together with tree edges make up a tree), it searches for some unvisited vertex
4977                                 in the graph and resumes the traversal process from that vertex.
4978                                 Before starting a new tree (including the very first tree
4979                                 when <code>cvNextGraphItem</code> is called for the first time)
4980                                 it generates <code>CV_GRAPH_NEW_TREE</code> event.<br>
4981                                 For undirected graphs each search tree corresponds to a connected component of the graph.<br>
4982             <li>CV_GRAPH_BACKTRACKING - stop at every already visited vertex during backtracking - returning to
4983                                 already visited vertexes of the traversal tree.<br></ul>
4984 </dl><p>
4985 The function <code>cvCreateGraphScanner</code> creates structure for
4986 depth-first graph traversal/search.
4987 The initialized structure is used in <a href="#decl_cvNextGraphItem">cvNextGraphItem</a> function
4988 - the incremental traversal procedure.</p>
4989
4990
4991 <hr><h3><a name="decl_cvNextGraphItem">NextGraphItem</a></h3>
4992 <p class="Blurb">Makes one or more steps of the graph traversal procedure</p>
4993 <pre>
4994 int cvNextGraphItem( CvGraphScanner* scanner );
4995 </pre><p><dl>
4996 <dt>scanner<dd>Graph traversal state. It is updated by the function.
4997 </dl><p>
4998 The function <code>cvNextGraphItem</code> traverses through the graph until an event interesting to the user
4999 (that is, an event, specified in the <code>mask</code> in <a href="#decl_cvCreateGraphScanner">cvCreateGraphScanner</a> call)
5000 is met or the traversal is over. In the first case it returns one of the events,
5001 listed in the description of <code>mask</code> parameter above and with the next call
5002 it resumes the traversal. In the latter case it returns CV_GRAPH_OVER (-1).
5003 When the event is <code>CV_GRAPH_VERTEX</code>, or <code>CV_GRAPH_BACKTRACKING</code> or <code>CV_GRAPH_NEW_TREE</code>,
5004 the currently observed vertex is stored in <code>scanner->vtx</code>. And if the event is edge-related,
5005 the edge itself is stored at <code>scanner->edge</code>,
5006 the previously visited vertex - at <code>scanner->vtx</code> and the other ending vertex of the edge -
5007 at <code>scanner->dst</code>.</p>
5008
5009
5010 <hr><h3><a name="decl_cvReleaseGraphScanner">ReleaseGraphScanner</a></h3>
5011 <p class="Blurb">Finishes graph traversal procedure</p>
5012 <pre>
5013 void cvReleaseGraphScanner( CvGraphScanner** scanner );
5014 </pre><p><dl>
5015 <dt>scanner<dd>Double pointer to graph traverser.
5016 </dl><p>
5017 The function <code>cvGraphScanner</code> finishes graph traversal procedure
5018 and releases the traverser state.</p>
5019
5020
5021 <hr><h2><a name="cxcore_ds_trees">Trees</a></h2>
5022
5023
5024 <hr><h3><a name="decl_CV_TREE_NODE_FIELDS">CV_TREE_NODE_FIELDS</a></h3>
5025 <p class="Blurb">Helper macro for a tree node type declaration</p>
5026 <pre>
5027 #define CV_TREE_NODE_FIELDS(node_type)                          \
5028     int       flags;         /* miscellaneous flags */          \
5029     int       header_size;   /* size of sequence header */      \
5030     struct    node_type* h_prev; /* previous sequence */        \
5031     struct    node_type* h_next; /* next sequence */            \
5032     struct    node_type* v_prev; /* 2nd previous sequence */    \
5033     struct    node_type* v_next; /* 2nd next sequence */
5034 </pre>
5035 <p>The macro <code>CV_TREE_NODE_FIELDS()</code> is used to declare structures
5036 that can be organized into hierarchical structures (trees), such as <a href="#decl_CvSeq">CvSeq</a> -
5037 the basic type for all dynamical structures.
5038 The trees made of nodes declared using this macro can be processed using
5039 the functions described below in this section.</p>
5040
5041
5042 <hr><h3><a name="decl_CvTreeNodeIterator">CvTreeNodeIterator</a></h3>
5043 <p class="Blurb">Opens existing or creates new file storage</p>
5044 <pre>
5045 typedef struct CvTreeNodeIterator
5046 {
5047     const void* node;
5048     int level;
5049     int max_level;
5050 }
5051 CvTreeNodeIterator;
5052 </pre>
5053 <p>The structure <a href="#decl_CvTreeNodeIterator">CvTreeNodeIterator</a> is used to traverse trees.
5054 The tree node declaration should start with <code>CV_TREE_NODE_FIELDS(...)</code> macro.</p>
5055
5056
5057 <hr><h3><a name="decl_cvInitTreeNodeIterator">InitTreeNodeIterator</a></h3>
5058 <p class="Blurb">Initializes tree node iterator</p>
5059 <pre>
5060 void cvInitTreeNodeIterator( CvTreeNodeIterator* tree_iterator,
5061                              const void* first, int max_level );
5062 </pre><p><dl>
5063 <dt>tree_iterator<dd>Tree iterator initialized by the function.
5064 <dt>first<dd>The initial node to start traversing from.
5065 <dt>max_level<dd>The maximal level of the tree (<code>first</code> node assumed to be at the first level) to
5066                 traverse up to. For example, 1 means that only nodes at the same level as <code>first</code>
5067                 should be visited, 2 means that the nodes on the same level as <code>first</code> and
5068                 their direct children should be visited etc.
5069 </dl><p>
5070 The function <code>cvInitTreeNodeIterator</code> initializes tree iterator.
5071 The tree is traversed in depth-first order.</p>
5072
5073
5074 <hr><h3><a name="decl_cvNextTreeNode">NextTreeNode</a></h3>
5075 <p class="Blurb">Returns the currently observed node and moves iterator toward the next node</p>
5076 <pre>
5077 void* cvNextTreeNode( CvTreeNodeIterator* tree_iterator );
5078 </pre><p><dl>
5079 <dt>tree_iterator<dd>Tree iterator initialized by the function.
5080 </dl><p>
5081 The function <code>cvNextTreeNode</code> returns the currently observed node and then
5082 updates the iterator - moves it toward the next node. In other words, the function behavior
5083 is similar to *p++ expression on usual C pointer or C++ collection iterator.
5084 The function returns NULL if there is no more nodes.</p>
5085
5086
5087 <hr><h3><a name="decl_cvPrevTreeNode">PrevTreeNode</a></h3>
5088 <p class="Blurb">Returns the currently observed node and moves iterator toward the previous node</p>
5089 <pre>
5090 void* cvPrevTreeNode( CvTreeNodeIterator* tree_iterator );
5091 </pre><p><dl>
5092 <dt>tree_iterator<dd>Tree iterator initialized by the function.
5093 </dl><p>
5094 The function <code>cvPrevTreeNode</code> returns the currently observed node and then
5095 updates the iterator - moves it toward the previous node. In other words, the function behavior
5096 is similar to *p-- expression on usual C pointer or C++ collection iterator.
5097 The function returns NULL if there is no more nodes.</p>
5098
5099
5100 <hr><h3><a name="decl_cvTreeToNodeSeq">TreeToNodeSeq</a></h3>
5101 <p class="Blurb">Gathers all node pointers to the single sequence</p>
5102 <pre>
5103 CvSeq* cvTreeToNodeSeq( const void* first, int header_size, CvMemStorage* storage );
5104 </pre><p><dl>
5105 <dt>first<dd>The initial tree node.
5106 <dt>header_size<dd>Header size of the created sequence (sizeof(CvSeq) is the most used value).
5107 <dt>storage<dd>Container for the sequence.
5108 </dl><p>
5109 The function <code>cvTreeToNodeSeq</code> puts pointers of all nodes reachable from <code>first</code>
5110 to the single sequence. The pointers are written subsequently in the depth-first order.</p>
5111
5112
5113 <hr><h3><a name="decl_cvInsertNodeIntoTree">InsertNodeIntoTree</a></h3>
5114 <p class="Blurb">Adds new node to the tree</p>
5115 <pre>
5116 void cvInsertNodeIntoTree( void* node, void* parent, void* frame );
5117 </pre><p><dl>
5118 <dt>node<dd>The inserted node.
5119 <dt>parent<dd>The parent node that is already in the tree.
5120 <dt>frame<dd>The top level node. If <code>parent</code> and <code>frame</code> are the same, <code>v_prev</code>
5121             field of <code>node</code> is set to NULL rather than <code>parent</code>.
5122 </dl><p>
5123 The function <code>cvInsertNodeIntoTree</code> adds another node into tree. The function does not
5124 allocate any memory, it can only modify links of the tree nodes.</p>
5125
5126
5127 <hr><h3><a name="decl_cvRemoveNodeFromTree">RemoveNodeFromTree</a></h3>
5128 <p class="Blurb">Removes node from tree</p>
5129 <pre>
5130 void cvRemoveNodeFromTree( void* node, void* frame );
5131 </pre><p><dl>
5132 <dt>node<dd>The removed node.
5133 <dt>frame<dd>The top level node. If <code>node->v_prev = NULL</code> and
5134             <code>node->h_prev</code> is NULL (i.e. if <code>node</code> is the first child of <code>frame</code>),
5135             <code>frame->v_next</code> is set to <code>node->h_next</code> (i.e. the first child or frame is changed).
5136 </dl><p>
5137 The function <code>cvRemoveNodeFromTree</code> removes node from tree. The function does not
5138 deallocate any memory, it can only modify links of the tree nodes.</p>
5139
5140
5141
5142 <hr><h1><a name="cxcore_drawing">Drawing Functions</a></h1>
5143
5144 <p>
5145 Drawing functions work with matrices/images or arbitrary depth.
5146 Antialiasing is implemented only for 8-bit images.
5147 All the functions include parameter color that means rgb value (that may be
5148 constructed with <code>CV_RGB</code> macro or <code>cvScalar</code> function)
5149 for color images and brightness for grayscale images.</p><p>
5150 If a drawn figure is partially or completely outside the image, it is clipped.
5151 For color images the order channel is: <font color=blue>B</font>lue <font color=green>G</font>reen <font color=red>R</font>ed ...
5152 If one needs a different channel order, it is possible to construct color
5153 via <code>cvScalar</code> with the particular channel order, or
5154 convert the image before and/or after drawing in it with
5155 <a href="opencvref_cv.htm#decl_cvCvtColor">cvCvtColor</a> or
5156 <a href="#decl_cvTransform">cvTransform</a>.
5157 </p>
5158
5159
5160 <hr><h2><a name="cxcore_drawing_shapes">Curves and Shapes</a></h2>
5161
5162 <hr><h3><a name="decl_CV_RGB">CV_RGB</a></h3>
5163 <p class="Blurb">Constructs a color value</p>
5164 <pre>
5165 #define CV_RGB( r, g, b )  cvScalar( (b), (g), (r) )
5166 </pre>
5167
5168
5169 <hr><h3><a name="decl_cvLine">Line</a></h3>
5170 <p class="Blurb">Draws a line segment connecting two points</p>
5171 <pre>
5172 void cvLine( CvArr* img, CvPoint pt1, CvPoint pt2, CvScalar color,
5173              int thickness=1, int line_type=8, int shift=0 );
5174 </pre><p><dl>
5175 <dt>img<dd>The image.
5176 <dt>pt1<dd>First point of the line segment.
5177 <dt>pt2<dd>Second point of the line segment.
5178 <dt>color<dd>Line color.
5179 <dt>thickness<dd>Line thickness.
5180 <dt>line_type<dd>Type of the line:<br>
5181                  <code>8</code> (or <code>0</code>) - 8-connected line.<br>
5182                  <code>4</code> - 4-connected line.<br>
5183                  <code>CV_AA</code> - antialiased line.
5184 <dt>shift<dd>Number of fractional bits in the point coordinates.
5185 </dl><p>
5186 The function <code>cvLine</code> draws the line segment between <code>pt1</code> and <code>pt2</code> points
5187 in the image. The line is clipped by the image or ROI rectangle. For non-antialiased lines
5188 with integer coordinates the 8-connected or 4-connected Bresenham algorithm is used.
5189 Thick lines are drawn with rounding endings. Antialiased lines are drawn using Gaussian filtering.
5190 To specify the line color, the user may use the macro <code>CV_RGB( r, g, b )</code>.</p>
5191
5192
5193 <hr><h3><a name="decl_cvRectangle">Rectangle</a></h3>
5194 <p class="Blurb">Draws simple, thick or filled rectangle</p>
5195 <pre>
5196 void cvRectangle( CvArr* img, CvPoint pt1, CvPoint pt2, CvScalar color,
5197                   int thickness=1, int line_type=8, int shift=0 );
5198 </pre><p><dl>
5199 <dt>img<dd>Image.
5200 <dt>pt1<dd>One of the rectangle vertices.
5201 <dt>pt2<dd>Opposite rectangle vertex.
5202 <dt>color<dd>Line color (RGB) or brightness (grayscale image).
5203 <dt>thickness<dd>Thickness of lines that make up the rectangle. Negative values, e.g. CV_FILLED,
5204 make the function to draw a filled rectangle.
5205 <dt>line_type<dd>Type of the line, see <a href="#decl_cvLine">cvLine</a> description.
5206 <dt>shift<dd>Number of fractional bits in the point coordinates.
5207 </dl><p>
5208 The function <code>cvRectangle</code> draws a rectangle with
5209 two opposite corners <code>pt1</code> and <code>pt2</code>.</p>
5210
5211
5212 <hr><h3><a name="decl_cvCircle">Circle</a></h3>
5213 <p class="Blurb">Draws a circle</p>
5214 <pre>
5215 void cvCircle( CvArr* img, CvPoint center, int radius, CvScalar color,
5216                int thickness=1, int line_type=8, int shift=0 );
5217 </pre><p><dl>
5218 <dt>img<dd>Image where the circle is drawn.
5219 <dt>center<dd>Center of the circle.
5220 <dt>radius<dd>Radius of the circle.
5221 <dt>color<dd>Circle color.
5222 <dt>thickness<dd>Thickness of the circle outline if positive, otherwise indicates that
5223 a filled circle has to be drawn.
5224 <dt>line_type<dd>Type of the circle boundary, see <a href="#decl_cvLine">cvLine</a> description.
5225 <dt>shift<dd>Number of fractional bits in the center coordinates and radius value.
5226 </dl><p>
5227 The function <code>cvCircle</code> draws a simple or filled circle with given center and
5228 radius. The circle is clipped by ROI rectangle. To specify the circle color, the user may
5229 use the macro <code>CV_RGB ( r, g, b )</code>.</p>
5230
5231
5232 <hr><h3><a name="decl_cvEllipse">Ellipse</a></h3>
5233 <p class="Blurb">Draws simple or thick elliptic arc or fills ellipse sector</p>
5234 <pre>
5235 void cvEllipse( CvArr* img, CvPoint center, CvSize axes, double angle,
5236                 double start_angle, double end_angle, CvScalar color,
5237                 int thickness=1, int line_type=8, int shift=0 );
5238 </pre><p><dl>
5239 <dt>img<dd>Image.
5240 <dt>center<dd>Center of the ellipse.
5241 <dt>axes<dd>Length of the ellipse axes.
5242 <dt>angle<dd>Rotation angle.
5243 <dt>start_angle<dd>Starting angle of the elliptic arc.
5244 <dt>end_angle<dd>Ending angle of the elliptic arc.
5245 <dt>color<dd>Ellipse color.
5246 <dt>thickness<dd>Thickness of the ellipse arc.
5247 <dt>line_type<dd>Type of the ellipse boundary, see <a href="#decl_cvLine">cvLine</a> description.
5248 <dt>shift<dd>Number of fractional bits in the center coordinates and axes' values.
5249 </dl><p>
5250 The function <code>cvEllipse</code> draws a simple or thick elliptic arc or fills an ellipse
5251 sector. The arc is clipped by ROI rectangle. A piecewise-linear
5252 approximation is used for antialiased arcs and thick arcs. All the angles are
5253 given in degrees. The picture below explains the meaning of the parameters.</p>
5254 <p>
5255 <font color=blue>Parameters of Elliptic Arc</font>
5256 </p>
5257 <p>
5258 <img align="center" src="pics/ellipse.png" >
5259 </p>
5260
5261
5262 <hr><h3><a name="decl_cvEllipseBox">EllipseBox</a></h3>
5263 <p class="Blurb">Draws simple or thick elliptic arc or fills ellipse sector</p>
5264 <pre>
5265 void cvEllipseBox( CvArr* img, CvBox2D box, CvScalar color,
5266                    int thickness=1, int line_type=8, int shift=0 );
5267 </pre><p><dl>
5268 <dt>img<dd>Image.
5269 <dt>box<dd>The enclosing box of the ellipse drawn
5270 <dt>thickness<dd>Thickness of the ellipse boundary.
5271 <dt>line_type<dd>Type of the ellipse boundary, see <a href="#decl_cvLine">cvLine</a> description.
5272 <dt>shift<dd>Number of fractional bits in the box vertex coordinates.
5273 </dl><p>
5274 The function <code>cvEllipseBox</code> draws a simple or thick ellipse outline,
5275 or fills an ellipse. The functions provides a convenient way to draw an ellipse
5276 approximating some shape; that is what <a href="opencvref_cv.htm#decl_cvCamShift">cvCamShift</a>
5277 and <a href="opencvref_cv.htm#decl_cvFitEllipse">cvFitEllipse</a> do.
5278 The ellipse drawn is clipped by ROI rectangle. A piecewise-linear
5279 approximation is used for antialiased arcs and thick arcs.</p>
5280
5281
5282 <hr><h3><a name="decl_cvFillPoly">FillPoly</a></h3>
5283 <p class="Blurb">Fills polygons interior</p>
5284 <pre>
5285 void cvFillPoly( CvArr* img, CvPoint** pts, int* npts, int contours,
5286                  CvScalar color, int line_type=8, int shift=0 );
5287 </pre><p><dl>
5288 <dt>img<dd>Image.
5289 <dt>pts<dd>Array of pointers to polygons.
5290 <dt>npts<dd>Array of polygon vertex counters.
5291 <dt>contours<dd>Number of contours that bind the filled region.
5292 <dt>color<dd>Polygon color.
5293 <dt>line_type<dd>Type of the polygon boundaries, see <a href="#decl_cvLine">cvLine</a> description.
5294 <dt>shift<dd>Number of fractional bits in the vertex coordinates.
5295 </dl><p>
5296 The function <code>cvFillPoly</code> fills an area bounded by several polygonal contours.
5297 The function fills complex areas, for example, areas with holes, contour self-intersection, etc.</p>
5298
5299
5300 <hr><h3><a name="decl_cvFillConvexPoly">FillConvexPoly</a></h3>
5301 <p class="Blurb">Fills convex polygon</p>
5302 <pre>
5303 void cvFillConvexPoly( CvArr* img, CvPoint* pts, int npts,
5304                        CvScalar color, int line_type=8, int shift=0 );
5305 </pre><p><dl>
5306 <dt>img<dd>Image.
5307 <dt>pts<dd>Array of pointers to a single polygon.
5308 <dt>npts<dd>Polygon vertex counter.
5309 <dt>color<dd>Polygon color.
5310 <dt>line_type<dd>Type of the polygon boundaries, see <a href="#decl_cvLine">cvLine</a> description.
5311 <dt>shift<dd>Number of fractional bits in the vertex coordinates.
5312 </dl><p>
5313 The function <code>cvFillConvexPoly</code> fills convex polygon interior.
5314 This function is much faster than The function <code>cvFillPoly</code> and can fill
5315 not only the convex polygons but any monotonic polygon, i.e. a polygon whose contour intersects every
5316 horizontal line (scan line) twice at the most.</p>
5317
5318
5319 <hr><h3><a name="decl_cvPolyLine">PolyLine</a></h3>
5320 <p class="Blurb">Draws simple or thick polygons</p>
5321 <pre>
5322 void cvPolyLine( CvArr* img, CvPoint** pts, int* npts, int contours, int is_closed,
5323                  CvScalar color, int thickness=1, int line_type=8, int shift=0 );
5324 </pre><p><dl>
5325 <dt>img<dd>Image.
5326 <dt>pts<dd>Array of pointers to polylines.
5327 <dt>npts<dd>Array of polyline vertex counters.
5328 <dt>contours<dd>Number of polyline contours.
5329 <dt>is_closed<dd>Indicates whether the polylines must be drawn closed. If closed, the
5330 function draws the line from the last vertex of every contour to the first
5331 vertex.
5332 <dt>color<dd>Polyline color.
5333 <dt>thickness<dd>Thickness of the polyline edges.
5334 <dt>line_type<dd>Type of the line segments, see <a href="#decl_cvLine">cvLine</a> description.
5335 <dt>shift<dd>Number of fractional bits in the vertex coordinates.
5336 </dl><p>
5337 The function <code>cvPolyLine</code> draws a single or multiple polygonal curves.</p>
5338
5339
5340 <hr><h2><a name="cxcore_drawing_text">Text</a></h2>
5341
5342 <hr><h3><a name="decl_cvInitFont">InitFont</a></h3>
5343 <p class="Blurb">Initializes font structure</p>
5344 <pre>
5345 void cvInitFont( CvFont* font, int font_face, double hscale,
5346                  double vscale, double shear=0,
5347                  int thickness=1, int line_type=8 );
5348 </pre><p><dl>
5349 <dt>font<dd>Pointer to the font structure initialized by the function.
5350 <dt>font_face<dd>Font name identifier. Only a subset of Hershey fonts
5351 (<a href="http://sources.isc.org/utils/misc/hershey-font.txt">http://sources.isc.org/utils/misc/hershey-font.txt</a>)
5352 are supported now:<br>
5353     <code>CV_FONT_HERSHEY_SIMPLEX</code> - normal size sans-serif font<br>
5354     <code>CV_FONT_HERSHEY_PLAIN</code> - small size sans-serif font<br>
5355     <code>CV_FONT_HERSHEY_DUPLEX</code> - normal size sans-serif font (more complex than <code>CV_FONT_HERSHEY_SIMPLEX</code>)<br>
5356     <code>CV_FONT_HERSHEY_COMPLEX</code> - normal size serif font<br>
5357     <code>CV_FONT_HERSHEY_TRIPLEX</code> - normal size serif font (more complex than <code>CV_FONT_HERSHEY_COMPLEX</code>)<br>
5358     <code>CV_FONT_HERSHEY_COMPLEX_SMALL</code> - smaller version of <code>CV_FONT_HERSHEY_COMPLEX</code><br>
5359     <code>CV_FONT_HERSHEY_SCRIPT_SIMPLEX</code> - hand-writing style font<br>
5360     <code>CV_FONT_HERSHEY_SCRIPT_COMPLEX</code> - more complex variant of <code>CV_FONT_HERSHEY_SCRIPT_SIMPLEX</code><br>
5361     The parameter can be composed from one of the values above and optional <code>CV_FONT_ITALIC</code> flag,
5362     that means italic or oblique font.
5363 <dt>hscale<dd>Horizontal scale. If equal to <code>1.0f</code>, the characters have the original
5364 width depending on the font type. If equal to <code>0.5f</code>, the characters are of half
5365 the original width.
5366 <dt>vscale<dd>Vertical scale. If equal to <code>1.0f</code>, the characters have the original
5367 height depending on the font type. If equal to <code>0.5f</code>, the characters are of half
5368 the original height.
5369 <dt>shear<dd>Approximate tangent of the character slope relative to the vertical
5370 line. Zero value means a non-italic font, <code>1.0f</code> means <code>&asymp;45&deg;</code> slope, etc.
5371 thickness Thickness of lines composing letters outlines. The function <code>cvLine</code> is
5372 used for drawing letters.
5373 <dt>thickness<dd>Thickness of the text strokes.
5374 <dt>line_type<dd>Type of the strokes, see <a href="#decl_cvLine">cvLine</a> description.
5375 </dl><p>
5376 The function <code>cvInitFont</code> initializes the font structure that can be passed to
5377 text rendering functions.</p>
5378
5379
5380 <hr><h3><a name="decl_cvPutText">PutText</a></h3>
5381 <p class="Blurb">Draws text string</p>
5382 <pre>
5383 void cvPutText( CvArr* img, const char* text, CvPoint org, const CvFont* font, CvScalar color );
5384 </pre><p><dl>
5385 <dt>img<dd>Input image.
5386 <dt>text<dd>String to print.
5387 <dt>org<dd>Coordinates of the bottom-left corner of the first letter.
5388 <dt>font<dd>Pointer to the font structure.
5389 <dt>color<dd>Text color.
5390 </dl><p>
5391 The function <code>cvPutText</code> renders the text in the image with the specified font and
5392 color. The printed text is clipped by ROI rectangle. Symbols that do not belong
5393 to the specified font are replaced with the rectangle symbol.</p>
5394
5395
5396 <hr><h3><a name="decl_cvGetTextSize">GetTextSize</a></h3>
5397 <p class="Blurb">Retrieves width and height of text string</p>
5398 <pre>
5399 void cvGetTextSize( const char* text_string, const CvFont* font, CvSize* text_size, int* baseline );
5400 </pre><p><dl>
5401 <dt>font<dd>Pointer to the font structure.
5402 <dt>text_string<dd>Input string.
5403 <dt>text_size<dd>Resultant size of the text string. Height of the text does not include
5404 the height of character parts that are below the baseline.
5405 <dt>baseline<dd>y-coordinate of the baseline relatively to the bottom-most text point.
5406 </dl><p>
5407 The function <code>cvGetTextSize</code> calculates the binding rectangle for the given text
5408 string when a specified font is used.</p>
5409
5410
5411 <hr><h2><a name="cxcore_drawing_seq">Point Sets and Contours</a></h2>
5412
5413 <hr><h3><a name="decl_cvDrawContours">DrawContours</a></h3>
5414 <p class="Blurb">Draws contour outlines or interiors in the image</p>
5415 <pre>
5416 void cvDrawContours( CvArr *img, CvSeq* contour,
5417                      CvScalar external_color, CvScalar hole_color,
5418                      int max_level, int thickness=1,
5419                      int line_type=8, CvPoint offset=cvPoint(0,0) );
5420 </pre><p><dl>
5421 <dt>img<dd>Image where the contours are to be drawn. Like in any other drawing
5422 function, the contours are clipped with the ROI.
5423 <dt>contour<dd>Pointer to the first contour.
5424 <dt>external_color<dd>Color of the external contours.
5425 <dt>hole_color<dd>Color of internal contours (holes).
5426 <dt>max_level<dd>Maximal level for drawn contours. If 0, only <code>contour</code> is drawn. If
5427 1, the contour and all contours after it on the same level are drawn. If 2, all
5428 contours after and all contours one level below the contours are drawn, etc.
5429 If the value is negative, the function does not draw the contours following after <code>contour</code>
5430 but draws child contours of <code>contour</code> up to abs(<code>max_level</code>)-1 level.
5431 <dt>thickness<dd>Thickness of lines the contours are drawn with. If it is negative (e.g. =CV_FILLED),
5432 the contour interiors are drawn.
5433 <dt>line_type<dd>Type of the contour segments, see <a href="#decl_cvLine">cvLine</a> description.
5434 <dt>offset<dd>Shift all the point coordinates by the specified value.
5435               It is useful in case if the contours retrieved in some image ROI and
5436               then the ROI offset needs to be taken into account during the rendering.
5437 </dl><p>
5438 The function <code>cvDrawContours</code> draws contour outlines in the image if <code>thickness</code>&gt;=0
5439 or fills area bounded by the contours if <code>thickness</code>&lt;0.
5440 </p>
5441 <h4>Example. Connected component detection via contour functions</h4>
5442 <pre>
5443 #include "cv.h"
5444 #include "highgui.h"
5445
5446 int main( int argc, char** argv )
5447 {
5448     IplImage* src;
5449     // the first command line parameter must be file name of binary (black-n-white) image
5450     if( argc == 2 && (src=cvLoadImage(argv[1], 0))!= 0)
5451     {
5452         IplImage* dst = cvCreateImage( cvGetSize(src), 8, 3 );
5453         CvMemStorage* storage = cvCreateMemStorage(0);
5454         CvSeq* contour = 0;
5455
5456         cvThreshold( src, src, 1, 255, CV_THRESH_BINARY );
5457         cvNamedWindow( "Source", 1 );
5458         cvShowImage( "Source", src );
5459
5460         cvFindContours( src, storage, &amp;contour, sizeof(CvContour), CV_RETR_CCOMP, CV_CHAIN_APPROX_SIMPLE );
5461         cvZero( dst );
5462
5463         for( ; contour != 0; contour = contour->h_next )
5464         {
5465             CvScalar color = CV_RGB( rand()&255, rand()&255, rand()&255 );
5466             /* replace CV_FILLED with 1 to see the outlines */
5467             cvDrawContours( dst, contour, color, color, -1, CV_FILLED, 8 );
5468         }
5469
5470         cvNamedWindow( "Components", 1 );
5471         cvShowImage( "Components", dst );
5472         cvWaitKey(0);
5473     }
5474 }
5475 </pre>
5476 <p>Replace CV_FILLED with 1 in the sample below to see the contour outlines
5477 </p>
5478
5479
5480 <hr><h3><a name="decl_cvInitLineIterator">InitLineIterator</a></h3>
5481 <p class="Blurb">Initializes line iterator</p>
5482 <pre>
5483 int cvInitLineIterator( const CvArr* image, CvPoint pt1, CvPoint pt2,
5484                         CvLineIterator* line_iterator, int connectivity=8,
5485                         int left_to_right=0 );
5486 </pre><p><dl>
5487 <dt>image<dd>Image to sample the line from.
5488 <dt>pt1<dd>First ending point of the line segment.
5489 <dt>pt2<dd>Second ending point of the line segment.
5490 <dt>line_iterator<dd>Pointer to the line iterator state structure.
5491 <dt>connectivity<dd>The scanned line connectivity, 4 or 8.
5492 <dt>left_to_right<dd>The flag, indicating whether the line should be always scanned from the
5493 left-most point to the right-most out of <code>pt1</code> and <code>pt2</code> (<code>left_to_right&ne;0</code>),
5494 or it is scanned in the specified order, from <code>pt1</code> to <code>pt2</code> (<code>left_to_right=0</code>).
5495 </dl><p>
5496 The function <code>cvInitLineIterator</code> initializes the line iterator and returns the
5497 number of pixels between two end points. Both points must be inside the image.
5498 After the iterator has been initialized, all the points on the raster line that
5499 connects the two ending points may be retrieved by successive calls of
5500 <code>CV_NEXT_LINE_POINT</code> point. The points on the line are calculated one by one using
5501 4-connected or 8-connected Bresenham algorithm.</p>
5502 <h4>Example. Using line iterator to calculate sum of pixel values along the color line</h4>
5503 <pre>
5504     CvScalar sum_line_pixels( IplImage* image, CvPoint pt1, CvPoint pt2 )
5505     {
5506         CvLineIterator iterator;
5507         int blue_sum = 0, green_sum = 0, red_sum = 0;
5508         int count = cvInitLineIterator( image, pt1, pt2, &iterator, 8, 0 );
5509
5510         for( int i = 0; i &lt; count; i++ ){
5511             blue_sum += iterator.ptr[0];
5512             green_sum += iterator.ptr[1];
5513             red_sum += iterator.ptr[2];
5514             CV_NEXT_LINE_POINT(iterator);
5515
5516             /* print the pixel coordinates: demonstrates how to calculate the coordinates */
5517             {
5518             int offset, x, y;
5519             /* assume that ROI is not set, otherwise need to take it into account. */
5520             offset = iterator.ptr - (uchar*)(image->imageData);
5521             y = offset/image->widthStep;
5522             x = (offset - y*image->widthStep)/(3*sizeof(uchar) /* size of pixel */);
5523             printf("(%d,%d)\n", x, y );
5524             }
5525         }
5526         return cvScalar( blue_sum, green_sum, red_sum );
5527     }
5528 </pre>
5529
5530
5531 <hr><h3><a name="decl_cvClipLine">ClipLine</a></h3>
5532 <p class="Blurb">Clips the line against the image rectangle</p>
5533 <pre>
5534 int cvClipLine( CvSize img_size, CvPoint* pt1, CvPoint* pt2 );
5535 </pre><p><dl>
5536 <dt>img_size<dd>Size of the image.
5537 <dt>pt1<dd>First ending point of the line segment. It is modified by the function.
5538 <dt>pt2<dd>Second ending point of the line segment. It is modified by the function.
5539 </dl><p>
5540 The function <code>cvClipLine</code> calculates a part of the line segment which is entirely in the image.
5541 It returns 0 if the line segment is completely outside the image and 1 otherwise.
5542 </p>
5543
5544
5545 <hr><h3><a name="decl_cvEllipse2Poly">Ellipse2Poly</a></h3>
5546 <p class="Blurb">Approximates elliptic arc with polyline</p>
5547 <pre>
5548 int cvEllipse2Poly( CvPoint center, CvSize axes,
5549                     int angle, int arc_start,
5550                     int arc_end, CvPoint* pts, int delta );
5551 </pre><p><dl>
5552 <dt>center<dd>Center of the arc.
5553 <dt>axes<dd>Half-sizes of the arc. See <a href="#decl_cvEllipse">cvEllipse</a>.
5554 <dt>angle<dd>Rotation angle of the ellipse in degrees. See <a href="#decl_cvEllipse">cvEllipse</a>.
5555 <dt>start_angle<dd>Starting angle of the elliptic arc.
5556 <dt>end_angle<dd>Ending angle of the elliptic arc.
5557 <dt>pts<dd>The array of points, filled by the function.
5558 <dt>delta<dd>Angle between the subsequent polyline vertices, approximation accuracy.
5559 So, the total number of output points will ceil((end_angle - start_angle)/delta) + 1 at max.
5560 </dl><p>
5561 The function <code>cvEllipse2Poly</code> computes vertices of the polyline that approximates the specified elliptic arc.
5562 It is used by <a href="#decl_cvEllipse">cvEllipse</a>.
5563 </p>
5564
5565
5566 <hr><h3><a name="decl_cvClipLine">ClipLine</a></h3>
5567 CVAPI(int) cvEllipse2Poly( CvPoint center, CvSize axes,
5568                  int angle, int arc_start, int arc_end, CvPoint * pts, int delta );
5569
5570
5571 <hr><h1><a name="cxcore_persistence">Data Persistence and RTTI</a></h1>
5572
5573 <hr><h2><a name="cxcore_persistence_ds">File Storage</a></h2>
5574
5575 <hr><h3><a name="decl_CvFileStorage">CvFileStorage</a></h3>
5576 <p class="Blurb">File Storage</p>
5577 <pre>
5578     typedef struct CvFileStorage
5579     {
5580         ...       // hidden fields
5581     } CvFileStorage;
5582 </pre>
5583 <p>
5584 The structure <a href="#decl_CvFileStorage">CvFileStorage</a> is "black box" representation of
5585 file storage that is associated with a file on disk. Several functions that are described below
5586 take <code>CvFileStorage</code> on input and allow user to save or to load hierarchical collections
5587 that consist of scalar values, standard CXCORE objects (such as matrices, sequences, graphs) and
5588 user-defined objects.
5589 </p><p>
5590 CXCORE can read and write data in XML (<a href="http://www.w3c.org/XML">http://www.w3c.org/XML</a>)
5591 or YAML (<a href="http://www.yaml.org">http://www.yaml.org</a>) formats. Below is the example of
5592 3&times;3 floating-point identity matrix <code>A</code>, stored in XML and YAML files using CXCORE functions:</p>
5593 <p><dl>
5594 <dt><b>XML:</b><dd><pre>
5595 &lt;?xml version="1.0"&gt;
5596 &lt;opencv_storage&gt;
5597 &lt;A type_id="opencv-matrix"&gt;
5598   &lt;rows&gt;3&lt;/rows&gt;
5599   &lt;cols&gt;3&lt;/cols&gt;
5600   &lt;dt&gt;f&lt;/dt&gt;
5601   &lt;data&gt;1. 0. 0. 0. 1. 0. 0. 0. 1.&lt;/data&gt;
5602 &lt;/A&gt;
5603 &lt;/opencv_storage&gt;
5604 </pre>
5605 <dt><b>YAML:</b><dd><pre>
5606 %YAML:1.0
5607 A: !!opencv-matrix
5608   rows: 3
5609   cols: 3
5610   dt: f
5611   data: [ 1., 0., 0., 0., 1., 0., 0., 0., 1.]
5612 </pre>
5613 </dl></p>
5614 <p>
5615 As it can be seen from the examples, XML uses nested tags to represent hierarchy,
5616 while YAML uses indentation for that purpose (similarly to Python programming language).
5617 </p><p>
5618 The same CXCORE functions can read and write data in both formats, the particular format is determined
5619 by the extension of the opened file, .xml for XML files and .yml or .yaml for YAML.
5620 </p>
5621
5622 <hr><h3><a name="decl_CvFileNode">CvFileNode</a></h3>
5623 <p class="Blurb">File Storage Node</p>
5624 <pre>
5625 /* file node type */
5626 #define CV_NODE_NONE        0
5627 #define CV_NODE_INT         1
5628 #define CV_NODE_INTEGER     CV_NODE_INT
5629 #define CV_NODE_REAL        2
5630 #define CV_NODE_FLOAT       CV_NODE_REAL
5631 #define CV_NODE_STR         3
5632 #define CV_NODE_STRING      CV_NODE_STR
5633 #define CV_NODE_REF         4 /* not used */
5634 #define CV_NODE_SEQ         5
5635 #define CV_NODE_MAP         6
5636 #define CV_NODE_TYPE_MASK   7
5637
5638 /* optional flags */
5639 #define CV_NODE_USER        16
5640 #define CV_NODE_EMPTY       32
5641 #define CV_NODE_NAMED       64
5642
5643 #define CV_NODE_TYPE(tag)  ((tag) & CV_NODE_TYPE_MASK)
5644
5645 #define CV_NODE_IS_INT(tag)        (CV_NODE_TYPE(tag) == CV_NODE_INT)
5646 #define CV_NODE_IS_REAL(tag)       (CV_NODE_TYPE(tag) == CV_NODE_REAL)
5647 #define CV_NODE_IS_STRING(tag)     (CV_NODE_TYPE(tag) == CV_NODE_STRING)
5648 #define CV_NODE_IS_SEQ(tag)        (CV_NODE_TYPE(tag) == CV_NODE_SEQ)
5649 #define CV_NODE_IS_MAP(tag)        (CV_NODE_TYPE(tag) == CV_NODE_MAP)
5650 #define CV_NODE_IS_COLLECTION(tag) (CV_NODE_TYPE(tag) >= CV_NODE_SEQ)
5651 #define CV_NODE_IS_FLOW(tag)       (((tag) & CV_NODE_FLOW) != 0)
5652 #define CV_NODE_IS_EMPTY(tag)      (((tag) & CV_NODE_EMPTY) != 0)
5653 #define CV_NODE_IS_USER(tag)       (((tag) & CV_NODE_USER) != 0)
5654 #define CV_NODE_HAS_NAME(tag)      (((tag) & CV_NODE_NAMED) != 0)
5655
5656 #define CV_NODE_SEQ_SIMPLE 256
5657 #define CV_NODE_SEQ_IS_SIMPLE(seq) (((seq)->flags & CV_NODE_SEQ_SIMPLE) != 0)
5658
5659 typedef struct CvString
5660 {
5661     int len;
5662     char* ptr;
5663 }
5664 CvString;
5665
5666 /* all the keys (names) of elements in the read file storage
5667    are stored in the hash to speed up the lookup operations */
5668 typedef struct CvStringHashNode
5669 {
5670     unsigned hashval;
5671     CvString str;
5672     struct CvStringHashNode* next;
5673 }
5674 CvStringHashNode;
5675
5676 /* basic element of the file storage - scalar or collection */
5677 typedef struct CvFileNode
5678 {
5679     int tag;
5680     struct CvTypeInfo* info; /* type information
5681             (only for user-defined object, for others it is 0) */
5682     union
5683     {
5684         double f; /* scalar floating-point number */
5685         int i;    /* scalar integer number */
5686         CvString str; /* text string */
5687         CvSeq* seq; /* sequence (ordered collection of file nodes) */
5688         struct CvMap* map; /* map (collection of named file nodes) */
5689     } data;
5690 }
5691 CvFileNode;
5692 </pre>
5693 <p>
5694 The structure is used only for retrieving data from file storage (i.e. for loading data from file).
5695 When data is written to file, it is done sequentially, with minimal buffering. No data is stored in the
5696 file storage.</p><p>In opposite, when data is read from file, the whole file is parsed and represented in memory
5697 as a tree. Every node of the tree is represented by <a href="#decl_CvFileNode">CvFileNode</a>. Type of the file node
5698 <code>N</code> can be retrieved as <code>CV_NODE_TYPE(N->tag)</code>. Some file nodes (leaves) are scalars:
5699 text strings, integer or floating-point numbers. Other file nodes are collections of file nodes, which can
5700 be scalars or collections in their turn. There are two types of collections: sequences and maps
5701 (we use YAML notation, however, the same is true for XML streams). Sequences (do not mix them with
5702 <a href="#decl_CvSeq">CvSeq</a>) are ordered collections of unnamed file nodes,
5703 maps are unordered collections of named file nodes. Thus, elements of sequences are
5704 accessed by index (<a href="#decl_cvGetSeqElem">cvGetSeqElem</a>),
5705 while elements of maps are accessed by name
5706 (<a href="#decl_cvGetFileNodeByName">cvGetFileNodeByName</a>).
5707 The table below describes the different types of a file node:</p>
5708 <p><table border=1 cellpadding="10%">
5709 <tr><td>Type</td><td>CV_NODE_TYPE(node->tag)</td><td>Value</td></tr>
5710 <tr><td>Integer</td><td>CV_NODE_INT</td><td>node->data.i</td></tr>
5711 <tr><td>Floating-point</td><td>CV_NODE_REAL</td><td>node->data.f</td></tr>
5712 <tr><td>Text string</td><td>CV_NODE_STR</td><td>node->data.str.ptr</td></tr>
5713 <tr><td>Sequence</td><td>CV_NODE_SEQ</td><td>node->data.seq</td></tr>
5714 <tr><td>Map</td><td>CV_NODE_MAP</td><td>node->data.map*</td></tr>
5715 </table>
5716 <dl>
5717 <dt>*<dd>There is no need to access <code>map</code> field directly (BTW, <code>CvMap</code> is a hidden structure).
5718           The elements of the map can be retrieved with <a href="#decl_cvGetFileNodeByName">cvGetFileNodeByName</a>
5719           function that takes pointer to the "map" file node.
5720 <!--
5721 <dt>**<dd>Tag of the file node that represent a user object (see below) also includes <code>CV_NODE_USER</code> flag.
5722           That is, <code>CV_NODE_IS_USER(node->tag)</code> returns 1 on such a node.
5723 <dt>***<dd>The field contains pointer to decoded object. The original map is still available as
5724           <code>node->data.obj.map</code>. -->
5725 </dl>
5726 </p><p>
5727 A user (custom) object is instance of either one of standard CXCORE types, such as <a href="#decl_CvMat">CvMat</a>, <a href="#decl_CvSeq">CvSeq</a> etc.,
5728 or any type registered with <a href="#decl_cvRegisterTypeInfo">cvRegisterTypeInfo</a>. Such an object is initially represented in file as a map
5729 (as shown in XML and YAML sample files above), after file storage has been opened and parsed.
5730 Then the object can be decoded (converted to the native representation) by request -
5731 when user calls <a href="#decl_cvRead">cvRead</a> or
5732 <a href="#decl_cvReadByName">cvReadByName</a> function.</p>
5733
5734 <hr><h3><a name="decl_CvAttrList">CvAttrList</a></h3>
5735 <p class="Blurb">List of attributes</p>
5736 <pre>
5737 typedef struct CvAttrList
5738 {
5739     const char** attr; /* NULL-terminated array of (attribute_name,attribute_value) pairs */
5740     struct CvAttrList* next; /* pointer to next chunk of the attributes list */
5741 }
5742 CvAttrList;
5743
5744 /* initializes CvAttrList structure */
5745 inline CvAttrList cvAttrList( const char** attr=NULL, CvAttrList* next=NULL );
5746
5747 /* returns attribute value or 0 (NULL) if there is no such attribute */
5748 const char* cvAttrValue( const CvAttrList* attr, const char* attr_name );
5749 </pre>
5750 <p>
5751 In the current implementation attributes are used to pass extra parameters when writing user objects
5752 (see <a href="#decl_cvWrite">cvWrite</a>).
5753 XML attributes inside tags are not supported, besides the object type specification
5754 (<code>type_id</code> attribute).
5755 </p>
5756
5757
5758 <hr><h3><a name="decl_cvOpenFileStorage">OpenFileStorage</a></h3>
5759 <p class="Blurb">Opens file storage for reading or writing data</p>
5760 <pre>
5761 CvFileStorage* cvOpenFileStorage( const char* filename, CvMemStorage* memstorage, int flags );
5762 </pre><p><dl>
5763 <dt>filename<dd>Name of the file associated with the storage.
5764 <dt>memstorage<dd>Memory storage used for temporary data and for storing dynamic structures,
5765 such as <a href="#decl_CvSeq">CvSeq</a> or <a href="#decl_CvGraph">CvGraph</a>.
5766 If it is NULL, a temporary memory storage is created and used.
5767 <dt>flags<dd>Can be one of the following:<br>
5768             <code>CV_STORAGE_READ</code> - the storage is open for reading<br>
5769             <code>CV_STORAGE_WRITE</code> - the storage is open for writing<br>
5770 </dl><p>
5771 The function <code>cvOpenFileStorage</code> opens file storage for
5772 reading or writing data. In the latter case a new file is created or existing file is
5773 rewritten. Type of the read of written file is determined by the filename extension: <code>.xml</code>
5774 for <em>XML</em>, and <code>.yml</code> or <code>.yaml</code> for <em>YAML</em>.
5775 The function returns pointer to <a href="#decl_CvFileStorage">CvFileStorage</a> structure.</p>
5776
5777
5778 <hr><h3><a name="decl_cvReleaseFileStorage">ReleaseFileStorage</a></h3>
5779 <p class="Blurb">Releases file storage</p>
5780 <pre>
5781 void  cvReleaseFileStorage( CvFileStorage** fs );
5782 </pre><p><dl>
5783 <dt>fs<dd>Double pointer to the released file storage.
5784 </dl><p>
5785 The function <code>cvReleaseFileStorage</code> closes the file
5786 associated with the storage and releases all the temporary structures.
5787 It must be called after all I/O operations with the storage are finished.</p>
5788
5789
5790 <hr><h2><a name="cxcore_persistence_writing">Writing Data</a></h2>
5791
5792 <hr><h3><a name="decl_cvStartWriteStruct">StartWriteStruct</a></h3>
5793 <p class="Blurb">Starts writing a new structure</p>
5794 <pre>
5795 void  cvStartWriteStruct( CvFileStorage* fs, const char* name,
5796                           int struct_flags, const char* type_name=NULL,
5797                           CvAttrList attributes=cvAttrList());
5798 </pre><p><dl>
5799 <dt>fs<dd>File storage.
5800 <dt>name<dd>Name of the written structure. The structure can be accessed by this name when
5801             the storage is read.
5802 <dt>struct_flags<dd>A combination one of the following values:<br>
5803               <code>CV_NODE_SEQ</code> - the written structure is a sequence (see discussion of
5804                 <a href="#decl_CvFileStorage">CvFileStorage</a>), that is,
5805                 its elements do not have a name. <br>
5806               <code>CV_NODE_MAP</code> - the written structure is a map (see discussion of
5807                 <a href="#decl_CvFileStorage">CvFileStorage</a>), that is,
5808                 all its elements have names. <br>
5809                <em>One and only one of the two above flags must be specified</em><br>
5810               <code>CV_NODE_FLOW</code> - the optional flag that has sense only for YAML streams.
5811                 It means that the structure is written as a flow (not as a block), which is more
5812                 compact. It is recommended to use this flag for structures or arrays whose elements are
5813                 all scalars.
5814 <dt>type_name<dd>Optional parameter - the object type name. In case of XML it is written as
5815                 <code>type_id</code> attribute of the structure opening tag. In case of YAML
5816                 it is written after a colon following the structure name (see the example in
5817                 <a href="#decl_CvFileStorage">CvFileStorage</a> description).
5818                 Mainly it comes with user objects.
5819                 When the storage is read, the encoded type name is used to determine
5820                 the object type (see <a href="#decl_CvTypeInfo">CvTypeInfo</a> and
5821                 <a href="#decl_cvFindTypeInfo">cvFindTypeInfo</a>).
5822 <dt>attributes<dd>This parameter is not used in the current implementation.
5823 </dl><p>
5824 The function <code>cvStartWriteStruct</code> starts writing
5825 a compound structure (collection) that can be a sequence or a map. After all the structure
5826 fields, which can be scalars or structures, are written,
5827 <a href="#decl_cvEndWriteStruct">cvEndWriteStruct</a> should be called.
5828 The function can be used to group some objects or to implement <em>write</em> function for a
5829 some user object (see <a href="#decl_CvTypeInfo">CvTypeInfo</a>).
5830 </p>
5831
5832
5833 <hr><h3><a name="decl_cvEndWriteStruct">EndWriteStruct</a></h3>
5834 <p class="Blurb">Ends writing a structure</p>
5835 <pre>
5836 void  cvEndWriteStruct( CvFileStorage* fs );
5837 </pre><p><dl>
5838 <dt>fs<dd>File storage.
5839 </dl><p>
5840 The function <code>cvEndWriteStruct</code> finishes the
5841 currently written structure.</p>
5842
5843
5844 <hr><h3><a name="decl_cvWriteInt">WriteInt</a></h3>
5845 <p class="Blurb">Writes an integer value</p>
5846 <pre>
5847 void  cvWriteInt( CvFileStorage* fs, const char* name, int value );
5848 </pre><p><dl>
5849 <dt>fs<dd>File storage.
5850 <dt>name<dd>Name of the written value. Should be NULL if and only if the
5851             parent structure is a sequence.
5852 <dt>value<dd>The written value.
5853 </dl><p>
5854 The function <code>cvWriteInt</code> writes a single integer value
5855 (with or without a name) to the file storage.</p>
5856
5857
5858 <hr><h3><a name="decl_cvWriteReal">WriteReal</a></h3>
5859 <p class="Blurb">Writes a floating-point value</p>
5860 <pre>
5861 void  cvWriteReal( CvFileStorage* fs, const char* name, double value );
5862 </pre><p><dl>
5863 <dt>fs<dd>File storage.
5864 <dt>name<dd>Name of the written value. Should be NULL if and only if the
5865             parent structure is a sequence.
5866 <dt>value<dd>The written value.
5867 </dl><p>
5868 The function <code>cvWriteReal</code> writes a single
5869 floating-point value (with or without a name) to the file storage. The special
5870 values are encoded: NaN (Not A Number) as .NaN, &plusmn;Infinity as +.Inf (-.Inf).</p>
5871 <p>The following example shows how to use the low-level writing functions to
5872 store custom structures, such as termination criteria, without registering
5873 a new type.</p>
5874 <pre>
5875 void write_termcriteria( CvFileStorage* fs, const char* struct_name,
5876                          CvTermCriteria* termcrit )
5877 {
5878     cvStartWriteStruct( fs, struct_name, CV_NODE_MAP, NULL, cvAttrList(0,0));
5879     cvWriteComment( fs, "termination criteria", 1 ); // just a description
5880     if( termcrit->type & CV_TERMCRIT_ITER )
5881         cvWriteInt( fs, "max_iterations", termcrit->max_iter );
5882     if( termcrit->type & CV_TERMCRIT_EPS )
5883         cvWriteReal( fs, "accuracy", termcrit->epsilon );
5884     cvEndWriteStruct( fs );
5885 }
5886 </pre>
5887
5888
5889 <hr><h3><a name="decl_cvWriteString">WriteString</a></h3>
5890 <p class="Blurb">Writes a text string</p>
5891 <pre>
5892 void  cvWriteString( CvFileStorage* fs, const char* name,
5893                      const char* str, int quote=0 );
5894 </pre><p><dl>
5895 <dt>fs<dd>File storage.
5896 <dt>name<dd>Name of the written string. Should be NULL if and only if the
5897             parent structure is a sequence.
5898 <dt>str<dd>The written text string.
5899 <dt>quote<dd>If non-zero, the written string is put in quotes, regardless of whether
5900              they are required or not. Otherwise, if the flag is zero, quotes are used
5901              only when they are required (e.g. when the string starts with a digit or contains
5902              spaces).
5903 </dl><p>
5904 The function <code>cvWriteString</code> writes a text string
5905 to the file storage.</p>
5906
5907
5908 <hr><h3><a name="decl_cvWriteComment">WriteComment</a></h3>
5909 <p class="Blurb">Writes comment</p>
5910 <pre>
5911 void  cvWriteComment( CvFileStorage* fs, const char* comment, int eol_comment );
5912 </pre><p><dl>
5913 <dt>fs<dd>File storage.
5914 <dt>comment<dd>The written comment, single-line or multi-line.
5915 <dt>eol_comment<dd>If non-zero, the function tries to put the comment in the end
5916              of current line. If the flag is zero, if the comment is multi-line, or
5917              if it does not fit in the end of the current line, the comment starts
5918              from a new line.
5919 </dl><p>
5920 The function <code>cvWriteComment</code> writes a comment into the
5921 file storage. The comments are skipped when the storage is read, so they may be
5922 used only for debugging or descriptive purposes.</p>
5923
5924
5925 <hr><h3><a name="decl_cvStartNextStream">StartNextStream</a></h3>
5926 <p class="Blurb">Starts the next stream</p>
5927 <pre>
5928 void  cvStartNextStream( CvFileStorage* fs );
5929 </pre><p><dl>
5930 <dt>fs<dd>File storage.
5931 </dl><p>
5932 The function <code>cvStartNextStream</code> starts the next
5933 stream in the file storage. Both YAML and XML supports multiple "streams". This
5934 is useful for concatenating files or for resuming the writing process.</p>
5935
5936
5937 <hr><h3><a name="decl_cvWrite">Write</a></h3>
5938 <p class="Blurb">Writes user object</p>
5939 <pre>
5940 void  cvWrite( CvFileStorage* fs, const char* name,
5941                const void* ptr, CvAttrList attributes=cvAttrList() );
5942 </pre><p><dl>
5943 <dt>fs<dd>File storage.
5944 <dt>name<dd>Name, of the written object. Should be NULL if and only if the parent
5945             structure is a sequence.
5946 <dt>ptr<dd>Pointer to the object.
5947 <dt>attributes<dd>The attributes of the object. They are specific for each particular
5948            type (see the discussion).
5949 </dl><p>
5950 The function <code>cvWrite</code> writes the object to file storage.
5951 First, the appropriate type info is found using <a href="#decl_cvTypeOf">cvTypeOf</a>.
5952 Then, <code>write</code> method of the type info is called.
5953 </p><p>
5954 Attributes are used to customize the writing procedure.
5955 The standard types support the following attributes
5956 (all the <code>*dt</code> attributes have the same format as in
5957 <a href="#decl_cvWriteRawData">cvWriteRawData</a>):
5958 <dl>
5959 <dt><a href="#decl_CvSeq">CvSeq</a><dd>
5960     <ul>
5961     <li><code>header_dt</code> - description
5962     of user fields of the sequence header that follow CvSeq, or CvChain
5963     (if the sequence is Freeman chain) or CvContour (if the sequence is a contour
5964     or point sequence)
5965     <li><code>dt</code> - description of the sequence elements.
5966     <li><code>recursive</code> - if the attribute is present and is not equal to "0" or "false",
5967     the whole tree of sequences (contours) is stored.
5968     </ul>
5969 <dt><code>CvGraph</code><dd>
5970     <ul>
5971     <li><code>header_dt</code> - description of user fields
5972     of the graph header that follow CvGraph;
5973     <li><code>vertex_dt</code> - description of
5974     user fields of graph vertices
5975     <li><code>edge_dt</code> - description of user fields of graph edges (note, that
5976     edge weight is always written, so there is no need to specify it explicitly)
5977     </ul>
5978 </dl>
5979 </p><p>
5980 Below is the code that creates the YAML file shown in <code>CvFileStorage</code>
5981 description:</p><p>
5982 <pre>
5983 #include "cxcore.h"
5984
5985 int main( int argc, char** argv )
5986 {
5987     CvMat* mat = cvCreateMat( 3, 3, CV_32F );
5988     CvFileStorage* fs = cvOpenFileStorage( "example.yml", 0, CV_STORAGE_WRITE );
5989
5990     cvSetIdentity( mat );
5991     cvWrite( fs, "A", mat, cvAttrList(0,0) );
5992
5993     cvReleaseFileStorage( &fs );
5994     cvReleaseMat( &mat );
5995     return 0;
5996 }
5997 </pre></p>
5998
5999
6000 <hr><h3><a name="decl_cvWriteRawData">WriteRawData</a></h3>
6001 <p class="Blurb">Writes multiple numbers</p>
6002 <pre>
6003 void  cvWriteRawData( CvFileStorage* fs, const void* src,
6004                       int len, const char* dt );
6005 </pre><p><dl>
6006 <dt>fs<dd>File storage.
6007 <dt>src<dd>Pointer to the written array
6008 <dt>len<dd>Number of the array elements to write.
6009 <dt>dt<dd>Specification of each array element that has the following format:
6010           <code>([count]{'u'|'c'|'w'|'s'|'i'|'f'|'d'})...</code>, where the characters
6011           correspond to fundamental C types:
6012           <ul>
6013               <li>'u' - 8-bit unsigned number
6014               <li>'c' - 8-bit signed number
6015               <li>'w' - 16-bit unsigned number
6016               <li>'s' - 16-bit signed number
6017               <li>'i' - 32-bit signed number
6018               <li>'f' - single precision floating-point number
6019               <li>'d' - double precision floating-point number
6020               <li>'r' - pointer. 32 lower bits of it are written as a signed
6021                         integer. The type can be used to store structures with
6022                         links between the elements.
6023           </ul>
6024           <code>count</code> is the optional counter of values of the certain type.
6025           For example, <code>dt='2if'</code> means that each array element is a structure
6026           of 2 integers, followed by a single-precision floating-point number. The equivalent
6027           notations of the above specification are <code>'iif'</code>, <code>'2i1f'</code> etc.
6028           Other examples: <code>dt='u'</code> means that the array consists of bytes,
6029           <code>dt='2d'</code> - the array consists of pairs of double&#146;s.
6030 </dl><p>
6031 The function <code>cvWriteRawData</code> writes array,
6032 which elements consist of a single of multiple numbers. The function call can
6033 be replaced with a loop containing a few <a href="#decl_cvWriteInt">cvWriteInt</a>
6034 and <a href="#decl_cvWriteReal">cvWriteReal</a> calls,
6035 but a single call is more efficient. Note, that because none of the elements
6036 have a name, they should be written to a sequence rather than a map.</p>
6037
6038
6039 <hr><h3><a name="decl_cvWriteFileNode">WriteFileNode</a></h3>
6040 <p class="Blurb">Writes file node to another file storage</p>
6041 <pre>
6042 void cvWriteFileNode( CvFileStorage* fs, const char* new_node_name,
6043                       const CvFileNode* node, int embed );
6044 </pre><dl>
6045 <dt>fs<dd>Destination file storage.
6046 <dt>new_file_node<dd>New name of the file node in the destination file storage.
6047                      To keep the existing name,
6048                      use <code><a href="#decl_cvGetFileNodeName">cvGetFileNodeName</a>(node)</code>.
6049 <dt>node<dd>The written node
6050 <dt>embed<dd>If the written node is a collection and this parameter is not zero,
6051              no extra level of hierarchy is created. Instead, all the elements of <code>node</code> are
6052              written into the currently written structure. Of course, map elements may be
6053              written only to map, and sequence elements may be written only to sequence.
6054 </dl><p>
6055 The function <code>cvWriteFileNode</code>
6056 writes a copy of file node to file storage. The possible application of the function are:
6057 merging several file storages into one. Conversion between XML and YAML formats etc.
6058 </p>
6059
6060
6061 <hr><h2><a name="cxcore_persistence_reading">Reading Data</a></h2>
6062
6063 <p>Data are retrieved from file storage in 2 steps:
6064 first, the file node containing the requested data is found;
6065 then, data is extracted from the node manually or using custom <code>read</code> method.</p>
6066
6067
6068 <hr><h3><a name="decl_cvGetRootFileNode">GetRootFileNode</a></h3>
6069 <p class="Blurb">Retrieves one of top-level nodes of the file storage</p>
6070 <pre>
6071 CvFileNode* cvGetRootFileNode( const CvFileStorage* fs, int stream_index=0 );
6072 </pre><p><dl>
6073 <dt>fs<dd>File storage.
6074 <dt>stream_index<dd>Zero-based index of the stream. See <a href="#decl_cvStartNextStream">cvStartNextStream</a>.
6075            In most cases, there is only one stream in the file, however there can be several.
6076 </dl><p>
6077 The function <code>cvGetRootFileNode</code> returns
6078 one of  top-level file nodes. The top-level nodes do not have a name, they correspond to
6079 the streams, that are stored one after another in the file storage.
6080 If the index is out of range, the function returns NULL pointer, so all the top-level
6081 nodes may be iterated by subsequent calls to the function with <code>stream_index=0,1,...</code>,
6082 until NULL pointer is returned. This function may be used as a base for recursive traversal of the
6083 file storage.</p>
6084
6085
6086 <hr><h3><a name="decl_cvGetFileNodeByName">GetFileNodeByName</a></h3>
6087 <p class="Blurb">Finds node in the map or file storage</p>
6088 <pre>
6089 CvFileNode* cvGetFileNodeByName( const CvFileStorage* fs,
6090                                  const CvFileNode* map,
6091                                  const char* name );
6092 </pre><p><dl>
6093 <dt>fs<dd>File storage.
6094 <dt>map<dd>The parent map. If it is NULL, the function searches
6095            in all the top-level nodes (streams), starting from the first one.
6096 <dt>name<dd>The file node name.
6097 </dl><p>
6098 The function <code>cvGetFileNodeByName</code> finds
6099 a file node by <code>name</code>. The node is searched either in <code>map</code>
6100 or, if the pointer is NULL, among the top-level file nodes of the storage.
6101 Using this function for maps and <a href="#decl_cvGetSeqElem">cvGetSeqElem</a>
6102 (or sequence reader) for sequences, it is possible to navigate through the file storage.
6103 To speed up multiple queries for a certain key (e.g. in case of array of structures)
6104 one may use a pair of <a href="#decl_cvGetHashedKey">cvGetHashedKey</a> and
6105 <a href="#decl_cvGetFileNode">cvGetFileNode</a>.</p>
6106
6107
6108 <hr><h3><a name="decl_cvGetHashedKey">GetHashedKey</a></h3>
6109 <p class="Blurb">Returns a unique pointer for given name</p>
6110 <pre>
6111 CvStringHashNode* cvGetHashedKey( CvFileStorage* fs, const char* name,
6112                                   int len=-1, int create_missing=0 );
6113 </pre><p><dl>
6114 <dt>fs<dd>File storage.
6115 <dt>name<dd>Literal node name.
6116 <dt>len<dd>Length of the name (if it is known a priori), or -1 if it needs to
6117            be calculated.
6118 <dt>create_missing<dd>Flag that specifies, whether an absent key should be
6119            added into the hash table, or not.
6120 </dl><p>
6121 The function <code>cvGetHashedKey</code> returns
6122 the unique pointer for each particular file node name. This pointer can be
6123 then passed to <a href="#decl_cvGetFileNode">cvGetFileNode</a> function that
6124 is faster than <a href="#decl_cvGetFileNodeByName">cvGetFileNodeByName</a>
6125 because it compares text strings by comparing pointers rather than the
6126 strings' content.</p><p>Consider the following example: an array of points
6127 is encoded as a sequence of 2-entry maps, e.g.:
6128 <pre>
6129 %YAML:1.0
6130 points:
6131   - { x: 10, y: 10 }
6132   - { x: 20, y: 20 }
6133   - { x: 30, y: 30 }
6134   # ...
6135 </pre>
6136 Then, it is possible to get hashed "x" and "y" pointers to speed up
6137 decoding of the points.
6138 <h4>Example. Reading an array of structures from file storage</h4>
6139 <pre>
6140 #include "cxcore.h"
6141
6142 int main( int argc, char** argv )
6143 {
6144     CvFileStorage* fs = cvOpenFileStorage( "points.yml", 0, CV_STORAGE_READ );
6145     CvStringHashNode* x_key = cvGetHashedNode( fs, "x", -1, 1 );
6146     CvStringHashNode* y_key = cvGetHashedNode( fs, "y", -1, 1 );
6147     CvFileNode* points = cvGetFileNodeByName( fs, 0, "points" );
6148
6149     if( CV_NODE_IS_SEQ(points->tag) )
6150     {
6151         CvSeq* seq = points->data.seq;
6152         int i, total = seq->total;
6153         CvSeqReader reader;
6154         cvStartReadSeq( seq, &reader, 0 );
6155         for( i = 0; i &lt; total; i++ )
6156         {
6157             CvFileNode* pt = (CvFileNode*)reader.ptr;
6158 #if 1 /* faster variant */
6159             CvFileNode* xnode = cvGetFileNode( fs, pt, x_key, 0 );
6160             CvFileNode* ynode = cvGetFileNode( fs, pt, y_key, 0 );
6161             assert( xnode && CV_NODE_IS_INT(xnode->tag) &&
6162                     ynode && CV_NODE_IS_INT(ynode->tag));
6163             int x = xnode->data.i; // or x = cvReadInt( xnode, 0 );
6164             int y = ynode->data.i; // or y = cvReadInt( ynode, 0 );
6165 #elif 1 /* slower variant; does not use x_key & y_key */
6166             CvFileNode* xnode = cvGetFileNodeByName( fs, pt, "x" );
6167             CvFileNode* ynode = cvGetFileNodeByName( fs, pt, "y" );
6168             assert( xnode && CV_NODE_IS_INT(xnode->tag) &&
6169                     ynode && CV_NODE_IS_INT(ynode->tag));
6170             int x = xnode->data.i; // or x = cvReadInt( xnode, 0 );
6171             int y = ynode->data.i; // or y = cvReadInt( ynode, 0 );
6172 #else /* the slowest yet the easiest to use variant */
6173             int x = cvReadIntByName( fs, pt, "x", 0 /* default value */ );
6174             int y = cvReadIntByName( fs, pt, "y", 0 /* default value */ );
6175 #endif
6176             CV_NEXT_SEQ_ELEM( seq->elem_size, reader );
6177             printf("%d: (%d, %d)\n", i, x, y );
6178         }
6179     }
6180     cvReleaseFileStorage( &fs );
6181     return 0;
6182 }
6183 </pre>
6184 <p>Please note that, whatever method of accessing map you are using,
6185 it is still <em>much</em> slower than using plain sequences, for example,
6186 in the above sample, it is more efficient to encode the points as pairs of
6187 integers in the single numeric sequence.</p>
6188
6189
6190 <hr><h3><a name="decl_cvGetFileNode">GetFileNode</a></h3>
6191 <p class="Blurb">Finds node in the map or file storage</p>
6192 <pre>
6193 CvFileNode* cvGetFileNode( CvFileStorage* fs, CvFileNode* map,
6194                            const CvStringHashNode* key, int create_missing=0 );
6195 </pre><p><dl>
6196 <dt>fs<dd>File storage.
6197 <dt>map<dd>The parent map. If it is NULL, the function searches a top-level node.
6198            If both <code>map</code> and <code>key</code> are NULLs,
6199            the function returns the root file node - a map
6200            that contains top-level nodes.
6201 <dt>key<dd>Unique pointer to the node name, retrieved with
6202            <a href="#decl_cvGetHashedKey">cvGetHashedKey</a>.
6203 <dt>create_missing<dd>Flag that specifies, whether an absent node should be
6204            added to the map, or not.
6205 </dl><p>
6206 The function <code>cvGetFileNode</code> finds a file node. It is
6207 a faster version <a href="#decl_cvGetFileNodeByName">cvGetFileNodeByName</a>
6208 (see <a href="#decl_cvGetHashedKey">cvGetHashedKey</a> discussion). Also,
6209 the function can insert a new node, if it is not in the map yet (which is used
6210 by parsing functions).</p>
6211
6212
6213 <hr><h3><a name="decl_cvGetFileNodeName">GetFileNodeName</a></h3>
6214 <p class="Blurb">Returns name of file node</p>
6215 <pre>
6216 const char* cvGetFileNodeName( const CvFileNode* node );
6217 </pre><p><dl>
6218 <dt>node<dd>File node
6219 </dl><p>
6220 The function <code>cvGetFileNodeName</code> returns name of the file node
6221 or NULL, if the file node does not have a name, or if <code>node</code> is <code>NULL</code>.</p>
6222
6223
6224 <hr><h3><a name="decl_cvReadInt">ReadInt</a></h3>
6225 <p class="Blurb">Retrieves integer value from file node</p>
6226 <pre>
6227 int cvReadInt( const CvFileNode* node, int default_value=0 );
6228 </pre><p><dl>
6229 <dt>node<dd>File node.
6230 <dt>default_value<dd>The value that is returned if <code>node</code> is NULL.
6231 </dl><p>
6232 The function <code>cvReadInt</code> returns integer that is
6233 represented by the file node. If the file node is NULL, <code>default_value</code>
6234 is returned (thus, it is convenient to call the function right after
6235 <a href="#decl_cvGetFileNode">cvGetFileNode</a> without checking for NULL pointer),
6236 otherwise if the file node has type <code>CV_NODE_INT</code>,
6237 then <code>node->data.i</code> is returned, otherwise if the file node has
6238 type <code>CV_NODE_REAL</code>, then <code>node->data.f</code>
6239 is converted to integer and returned, otherwise the result is not determined.</p>
6240
6241
6242 <hr><h3><a name="decl_cvReadIntByName">ReadIntByName</a></h3>
6243 <p class="Blurb">Finds file node and returns its value</p>
6244 <pre>
6245 int cvReadIntByName( const CvFileStorage* fs, const CvFileNode* map,
6246                      const char* name, int default_value=0 );
6247 </pre><p><dl>
6248 <dt>fs<dd>File storage.
6249 <dt>map<dd>The parent map. If it is NULL, the function searches a top-level node.
6250 <dt>name<dd>The node name.
6251 <dt>default_value<dd>The value that is returned if the file node is not found.
6252 </dl><p>
6253 The function <code>cvReadIntByName</code> is a simple
6254 superposition of <a href="#decl_cvGetFileNodeByName">cvGetFileNodeByName</a> and
6255 <a href="#decl_cvReadInt">cvReadInt</a>.
6256
6257
6258 <hr><h3><a name="decl_cvReadReal">ReadReal</a></h3>
6259 <p class="Blurb">Retrieves floating-point value from file node</p>
6260 <pre>
6261 double cvReadReal( const CvFileNode* node, double default_value=0. );
6262 </pre><p><dl>
6263 <dt>node<dd>File node.
6264 <dt>default_value<dd>The value that is returned if <code>node</code> is NULL.
6265 </dl><p>
6266 The function <code>cvReadReal</code> returns floating-point value that is
6267 represented by the file node. If the file node is NULL, <code>default_value</code>
6268 is returned (thus, it is convenient to call the function right after
6269 <a href="#decl_cvGetFileNode">cvGetFileNode</a> without checking for NULL pointer),
6270 otherwise if the file node has type <code>CV_NODE_REAL</code>,
6271 then <code>node->data.f</code> is returned, otherwise if the file node has
6272 type <code>CV_NODE_INT</code>, then <code>node->data.f</code>
6273 is converted to floating-point and returned, otherwise the result is not determined.</p>
6274
6275
6276 <hr><h3><a name="decl_cvReadRealByName">ReadRealByName</a></h3>
6277 <p class="Blurb">Finds file node and returns its value</p>
6278 <pre>
6279 double  cvReadRealByName( const CvFileStorage* fs, const CvFileNode* map,
6280                           const char* name, double default_value=0. );
6281 </pre><p><dl>
6282 <dt>fs<dd>File storage.
6283 <dt>map<dd>The parent map. If it is NULL, the function searches a top-level node.
6284 <dt>name<dd>The node name.
6285 <dt>default_value<dd>The value that is returned if the file node is not found.
6286 </dl><p>
6287 The function <code>cvReadRealByName</code> is a simple
6288 superposition of <a href="#decl_cvGetFileNodeByName">cvGetFileNodeByName</a> and
6289 <a href="#decl_cvReadReal">cvReadReal</a>.
6290
6291
6292 <hr><h3><a name="decl_cvReadString">ReadString</a></h3>
6293 <p class="Blurb">Retrieves text string from file node</p>
6294 <pre>
6295 const char* cvReadString( const CvFileNode* node, const char* default_value=NULL );
6296 </pre><p><dl>
6297 <dt>node<dd>File node.
6298 <dt>default_value<dd>The value that is returned if <code>node</code> is NULL.
6299 </dl><p>
6300 The function <code>cvReadString</code> returns text string that is
6301 represented by the file node. If the file node is NULL, <code>default_value</code>
6302 is returned (thus, it is convenient to call the function right after
6303 <a href="#decl_cvGetFileNode">cvGetFileNode</a> without checking for NULL pointer),
6304 otherwise if the file node has type <code>CV_NODE_STR</code>,
6305 then <code>node->data.str.ptr</code> is returned, otherwise the result is not determined.</p>
6306
6307
6308 <hr><h3><a name="decl_cvReadStringByName">ReadStringByName</a></h3>
6309 <p class="Blurb">Finds file node and returns its value</p>
6310 <pre>
6311 const char* cvReadStringByName( const CvFileStorage* fs, const CvFileNode* map,
6312                                 const char* name, const char* default_value=NULL );
6313 </pre><p><dl>
6314 <dt>fs<dd>File storage.
6315 <dt>map<dd>The parent map. If it is NULL, the function searches a top-level node.
6316 <dt>name<dd>The node name.
6317 <dt>default_value<dd>The value that is returned if the file node is not found.
6318 </dl><p>
6319 The function <code>cvReadStringByName</code> is a simple
6320 superposition of <a href="#decl_cvGetFileNodeByName">cvGetFileNodeByName</a> and
6321 <a href="#decl_cvReadString">cvReadString</a>.
6322
6323
6324 <hr><h3><a name="decl_cvRead">Read</a></h3>
6325 <p class="Blurb">Decodes object and returns pointer to it</p>
6326 <pre>
6327 void* cvRead( CvFileStorage* fs, CvFileNode* node,
6328               CvAttrList* attributes=NULL );
6329 </pre><p><dl>
6330 <dt>fs<dd>File storage.
6331 <dt>node<dd>The root object node.
6332 <dt>attributes<dd>Unused parameter.
6333 </dl><p>
6334 The function <code>cvRead</code> decodes user object (creates object
6335 in a native representation from the file storage subtree) and returns it.
6336 The object to be decoded must be an instance of registered type that supports <code>read</code>
6337 method (see <a href="#decl_CvTypeInfo">CvTypeInfo</a>). Type of the object is determined by
6338 the type name that is encoded in the file. If the object is dynamic structure, it is
6339 created either in memory storage, passed to <a href="#decl_cvOpenFileStorage">cvOpenFileStorage</a>
6340 or, if NULL pointer was passed, in temporary memory storage, which is release when
6341 <a href="#decl_cvReleaseFileStorage">cvReleaseFileStorage</a> is called.
6342 Otherwise, if the object is not a dynamic structure, it is created in heap and should be
6343 released with a specialized function or using generic <a href="#decl_cvRelease">cvRelease</a>.</p>
6344
6345
6346 <hr><h3><a name="decl_cvReadByName">ReadByName</a></h3>
6347 <p class="Blurb">Finds object and decodes it</p>
6348 <pre>
6349 void* cvReadByName( CvFileStorage* fs, const CvFileNode* map,
6350                     const char* name, CvAttrList* attributes=NULL );
6351 </pre><p><dl>
6352 <dt>fs<dd>File storage.
6353 <dt>map<dd>The parent map. If it is NULL, the function searches a top-level node.
6354 <dt>name<dd>The node name.
6355 <dt>attributes<dd>Unused parameter.
6356 </dl><p>
6357 The function <code>cvReadByName</code> is a simple
6358 superposition of <a href="#decl_cvGetFileNodeByName">cvGetFileNodeByName</a> and
6359 <a href="#decl_cvRead">cvRead</a>.
6360
6361
6362 <hr><h3><a name="decl_cvReadRawData">ReadRawData</a></h3>
6363 <p class="Blurb">Reads multiple numbers</p>
6364 <pre>
6365 void cvReadRawData( const CvFileStorage* fs, const CvFileNode* src,
6366                     void* dst, const char* dt );
6367 </pre><p><dl>
6368 <dt>fs<dd>File storage.
6369 <dt>src<dd>The file node (a sequence) to read numbers from.
6370 <dt>dst<dd>Pointer to the destination array.
6371 <dt>dt<dd>Specification of each array element. It has the same format as in
6372           <a href="#decl_cvWriteRawData">cvWriteRawData</a>.
6373 </dl><p>
6374 The function <code>cvReadRawData</code> reads elements
6375 from a file node that represents a sequence of scalars</p>
6376
6377
6378 <hr><h3><a name="decl_cvStartReadRawData">StartReadRawData</a></h3>
6379 <p class="Blurb">Initializes file node sequence reader</p>
6380 <pre>
6381 void cvStartReadRawData( const CvFileStorage* fs, const CvFileNode* src,
6382                          CvSeqReader* reader );
6383 </pre><p><dl>
6384 <dt>fs<dd>File storage.
6385 <dt>src<dd>The file node (a sequence) to read numbers from.
6386 <dt>reader<dd>Pointer to the sequence reader.
6387 </dl><p>
6388 The function <code>cvStartReadRawData</code> initializes
6389 sequence reader to read data from file node. The initialized reader can be then
6390 passed to <a href="#decl_cvReadRawDataSlice">cvReadRawDataSlice</a>.</p>
6391
6392
6393 <hr><h3><a name="decl_cvReadRawDataSlice">ReadRawDataSlice</a></h3>
6394 <p class="Blurb">Initializes file node sequence reader</p>
6395 <pre>
6396 void cvReadRawDataSlice( const CvFileStorage* fs, CvSeqReader* reader,
6397                          int count, void* dst, const char* dt );
6398 </pre><p><dl>
6399 <dt>fs<dd>File storage.
6400 <dt>reader<dd>The sequence reader. Initialize it with <a href="#decl_cvStartReadRawData">cvStartReadRawData</a>.
6401 <dt>count<dd>The number of elements to read.
6402 <dt>dst<dd>Pointer to the destination array.
6403 <dt>dt<dd>Specification of each array element. It has the same format as in
6404           <a href="#decl_cvWriteRawData">cvWriteRawData</a>.
6405 </dl><p>
6406 The function <code>cvReadRawDataSlice</code> reads one
6407 or more elements from the file node, representing a sequence, to user-specified
6408 array. The total number of read sequence elements is a product of <code>total</code>
6409 and the number of components in each array element.
6410 For example, if <code>dt='2if'</code>, the function will read <code>total*3</code> sequence elements.
6411 As with any sequence, some parts of the file node sequence may be skipped or read repeatedly
6412 by repositioning the reader using <a href="#decl_cvSetSeqReaderPos">cvSetSeqReaderPos</a>.</p>
6413
6414
6415 <hr><h2><a name="cxcore_persistence_rtti">RTTI and Generic Functions</a></h2>
6416
6417
6418 <hr><h3><a name="decl_CvTypeInfo">CvTypeInfo</a></h3>
6419 <p class="Blurb">Type information</p>
6420 <pre>
6421 typedef int (CV_CDECL *CvIsInstanceFunc)( const void* struct_ptr );
6422 typedef void (CV_CDECL *CvReleaseFunc)( void** struct_dblptr );
6423 typedef void* (CV_CDECL *CvReadFunc)( CvFileStorage* storage, CvFileNode* node );
6424 typedef void (CV_CDECL *CvWriteFunc)( CvFileStorage* storage,
6425                                       const char* name,
6426                                       const void* struct_ptr,
6427                                       CvAttrList attributes );
6428 typedef void* (CV_CDECL *CvCloneFunc)( const void* struct_ptr );
6429
6430 typedef struct CvTypeInfo
6431 {
6432     int flags; /* not used */
6433     int header_size; /* sizeof(CvTypeInfo) */
6434     struct CvTypeInfo* prev; /* previous registered type in the list */
6435     struct CvTypeInfo* next; /* next registered type in the list */
6436     const char* type_name; /* type name, written to file storage */
6437
6438     /* methods */
6439     CvIsInstanceFunc is_instance; /* checks if the passed object belongs to the type */
6440     CvReleaseFunc release; /* releases object (memory etc.) */
6441     CvReadFunc read; /* reads object from file storage */
6442     CvWriteFunc write; /* writes object to file storage */
6443     CvCloneFunc clone; /* creates a copy of the object */
6444 }
6445 CvTypeInfo;
6446 </pre><p>
6447 The structure <a href="#decl_CvTypeInfo">CvTypeInfo</a> contains information about
6448 one of standard or user-defined types. Instances of the type may or may not contain
6449 pointer to the corresponding <a href="#decl_CvTypeInfo">CvTypeInfo</a> structure.
6450 In any case there is a way to find type info structure for given object - using
6451 <a href="#decl_cvTypeOf">cvTypeOf</a> function. Alternatively, type info can be
6452 found by the type name using <a href="#decl_cvFindType">cvFindType</a>, which is
6453 used when object is read from file storage. User can register a new type with
6454 <a href="#decl_cvRegisterType">cvRegisterType</a> that adds the type information structure
6455 into the beginning of the type list - thus, it is possible to create specialized types
6456 from generic standard types and override the basic methods.
6457 <p>
6458
6459
6460 <hr><h3><a name="decl_cvRegisterType">RegisterType</a></h3>
6461 <p class="Blurb">Registers new type</p>
6462 <pre>
6463 void cvRegisterType( const CvTypeInfo* info );
6464 </pre><p><dl>
6465 <dt>info<dd>Type info structure.
6466 </dl><p>
6467 The function <code>cvRegisterType</code> registers a new type,
6468 which is described by <code>info</code>. The function creates a copy of the structure,
6469 so user should delete it after calling the function.</p>
6470
6471
6472 <hr><h3><a name="decl_cvUnregisterType">UnregisterType</a></h3>
6473 <p class="Blurb">Unregisters the type</p>
6474 <pre>
6475 void cvUnregisterType( const char* type_name );
6476 </pre><p><dl>
6477 <dt>type_name<dd>Name of the unregistered type.
6478 </dl><p>
6479 The function <code>cvUnregisterType</code> unregisters the type
6480 with the specified name. If the name is unknown, it is possible to locate the type info
6481 by an instance of the type using <a href="#decl_cvTypeOf">cvTypeOf</a> or by iterating
6482 the type list, starting from <a href="#decl_cvFirstType">cvFirstType</a>, and then
6483 call <code><a href="#decl_cvUnregisterType">cvUnregisterType</a>(info->type_name)</code>.</p>
6484
6485
6486 <hr><h3><a name="decl_cvFirstType">FirstType</a></h3>
6487 <p class="Blurb">Returns the beginning of type list</p>
6488 <pre>
6489 CvTypeInfo* cvFirstType( void );
6490 </pre><p>
6491 The function <code>cvFirstType</code> returns the first type of the list
6492 of registered types. Navigation through the list can be done via <code>prev</code> and <code>next</code>
6493 fields of <a href="#decl_CvTypeInfo">CvTypeInfo</a> structure.</p>
6494
6495
6496 <hr><h3><a name="decl_cvFindType">FindType</a></h3>
6497 <p class="Blurb">Finds type by its name</p>
6498 <pre>
6499 CvTypeInfo* cvFindType( const char* type_name );
6500 </pre><p><dl>
6501 <dt>type_name<dd>Type name.
6502 </dl><p>
6503 The function <code>cvFindType</code> finds a registered type by its name.
6504 It returns NULL, if there is no type with the specified name.</p>
6505
6506
6507 <hr><h3><a name="decl_cvTypeOf">TypeOf</a></h3>
6508 <p class="Blurb">Returns type of the object</p>
6509 <pre>
6510 CvTypeInfo* cvTypeOf( const void* struct_ptr );
6511 </pre><p><dl>
6512 <dt>struct_ptr<dd>The object pointer.
6513 </dl><p>
6514 The function <code>cvTypeOf</code> finds the type of given object. It iterates through the list
6515 of registered types and calls <code>is_instance</code> function/method of every type info structure with
6516 the object until one of them return non-zero or until the whole list has been traversed. In the latter
6517 case the function returns NULL.</p>
6518
6519
6520 <hr><h3><a name="decl_cvRelease">Release</a></h3>
6521 <p class="Blurb">Releases the object</p>
6522 <pre>
6523 void cvRelease( void** struct_ptr );
6524 </pre><p><dl>
6525 <dt>struct_ptr<dd>Double pointer to the object.
6526 </dl><p>
6527 The function <code>cvRelease</code> finds the type of given object and calls
6528 <code>release</code> with the double pointer.</p>
6529
6530
6531 <hr><h3><a name="decl_cvClone">Clone</a></h3>
6532 <p class="Blurb">Makes a clone of the object</p>
6533 <pre>
6534 void* cvClone( const void* struct_ptr );
6535 </pre><p><dl>
6536 <dt>struct_ptr<dd>The object to clone.
6537 </dl><p>
6538 The function <code>cvClone</code> finds the type of given object and calls
6539 <code>clone</code> with the passed object.</p>
6540
6541
6542 <hr><h3><a name="decl_cvSave">Save</a></h3>
6543 <p class="Blurb">Saves object to file</p>
6544 <pre>
6545 void cvSave( const char* filename, const void* struct_ptr,
6546              const char* name=NULL,
6547              const char* comment=NULL,
6548              CvAttrList attributes=cvAttrList());
6549 </pre><p><dl>
6550 <dt>filename<dd>File name.
6551 <dt>struct_ptr<dd>Object to save.
6552 <dt>name<dd>Optional object name. If it is NULL, the name will be formed from <code>filename</code>.
6553 <dt>comment<dd>Optional comment to put in the beginning of the file.
6554 <dt>attributes<dd>Optional attributes passed to <a href="#decl_cvWrite">cvWrite</a>.
6555 </dl><p>
6556 The function <code>cvSave</code> saves object to file. It provides a simple interface
6557 to <a href="#decl_cvWrite">cvWrite</a>.</p>
6558
6559
6560 <hr><h3><a name="decl_cvLoad">Load</a></h3>
6561 <p class="Blurb">Loads object from file</p>
6562 <pre>
6563 void* cvLoad( const char* filename, CvMemStorage* memstorage=NULL,
6564               const char* name=NULL, const char** real_name=NULL );
6565 </pre><p><dl>
6566 <dt>filename<dd>File name.
6567 <dt>memstorage<dd>Memory storage for dynamic structures, such as <a href="#decl_CvSeq">CvSeq</a>
6568                   or <a href="#decl_CvGraph">CvGraph</a>. It is not used for matrices or images.
6569 <dt>name<dd>Optional object name. If it is NULL, the first top-level object in the storage will be loaded.
6570 <dt>real_name<dd>Optional output parameter that will contain name of the loaded object
6571                  (useful if <code>name=NULL</code>).
6572 </dl><p>
6573 The function <code>cvLoad</code> loads object from file.
6574 It provides a simple interface to <a href="#decl_cvRead">cvRead</a>.
6575 After object is loaded,
6576 the file storage is closed and all the temporary buffers are deleted. Thus, to load a dynamic structure,
6577 such as sequence, contour or graph, one should pass a valid destination
6578 memory storage to the function.</p>
6579
6580
6581 <hr><h1><a name="cxcore_misc">Miscellaneous Functions</a></h1>
6582
6583 <hr><h3><a name="decl_cvCheckArr">CheckArr</a></h3>
6584 <p class="Blurb">Checks every element of input array for invalid values</p>
6585 <pre>
6586 int  cvCheckArr( const CvArr* arr, int flags=0,
6587                  double min_val=0, double max_val=0);
6588 #define cvCheckArray cvCheckArr
6589 </pre><p><dl>
6590 <dt>arr<dd>The array to check.
6591 <dt>flags<dd>The operation flags, 0 or combination of:<br>
6592              <code>CV_CHECK_RANGE</code> - if set, the function checks that every value of
6593                               array is within [minVal,maxVal) range,
6594                               otherwise it just checks that every element
6595                               is neither NaN nor &plusmn;Infinity.<br>
6596              <code>CV_CHECK_QUIET</code> - if set, the function does not raises an
6597                               error if an element is invalid or out of range
6598 <dt>min_val<dd>The inclusive lower boundary of valid values range.
6599               It is used only if <code>CV_CHECK_RANGE</code> is set.
6600 <dt>max_val<dd>The exclusive upper boundary of valid values range.
6601               It is used only if <code>CV_CHECK_RANGE</code> is set.
6602 </dl><p>
6603 The function <code>cvCheckArr</code> checks that every array element
6604 is neither NaN nor &plusmn;Infinity.
6605 If <code>CV_CHECK_RANGE</code> is set, it also checks that every element is
6606 greater than or equal to <code>minVal</code> and less than <code>maxVal</code>.
6607 The function returns nonzero if the check succeeded, i.e. all elements
6608 are valid and within the range, and zero otherwise.
6609 In the latter case if <code>CV_CHECK_QUIET</code> flag is not set, the function
6610 raises runtime error.
6611 </p>
6612
6613
6614 <hr><h3><a name="decl_cvKMeans2">KMeans2</a></h3>
6615 <p class="Blurb">Splits set of vectors by given number of clusters</p>
6616 <pre>
6617 void cvKMeans2( const CvArr* samples, int cluster_count,
6618                 CvArr* labels, CvTermCriteria termcrit );
6619 </pre><p><dl>
6620 <dt>samples<dd>Floating-point matrix of input samples, one row per sample.
6621 <dt>cluster_count<dd>Number of clusters to split the set by.
6622 <dt>labels<dd>Output integer vector storing cluster indices for every sample.
6623 <dt>termcrit<dd>Specifies maximum number of iterations and/or accuracy (distance the centers move by
6624 between the subsequent iterations).
6625 </dl><p>
6626 The function <code>cvKMeans2</code> implements k-means algorithm that finds centers of <code>cluster_count</code> clusters
6627 and groups the input samples around the clusters. On output <code>labels(i)</code> contains a cluster index
6628 for sample stored in the i-th row of <code>samples</code> matrix.
6629 <h4>Example. Clustering random samples of k-variate Gaussian distribution</h4>
6630 <pre>
6631 #include "cxcore.h"
6632 #include "highgui.h"
6633
6634 void main( int argc, char** argv )
6635 {
6636     #define MAX_CLUSTERS 5
6637     CvScalar color_tab[MAX_CLUSTERS];
6638     IplImage* img = cvCreateImage( cvSize( 500, 500 ), 8, 3 );
6639     CvRNG rng = cvRNG(0xffffffff);
6640
6641     color_tab[0] = CV_RGB(255,0,0);
6642     color_tab[1] = CV_RGB(0,255,0);
6643     color_tab[2] = CV_RGB(100,100,255);
6644     color_tab[3] = CV_RGB(255,0,255);
6645     color_tab[4] = CV_RGB(255,255,0);
6646
6647     cvNamedWindow( "clusters", 1 );
6648
6649     for(;;)
6650     {
6651         int k, cluster_count = cvRandInt(&rng)%MAX_CLUSTERS + 1;
6652         int i, sample_count = cvRandInt(&rng)%1000 + 1;
6653         CvMat* points = cvCreateMat( sample_count, 1, CV_32FC2 );
6654         CvMat* clusters = cvCreateMat( sample_count, 1, CV_32SC1 );
6655
6656         /* generate random sample from multivariate Gaussian distribution */
6657         for( k = 0; k &lt; cluster_count; k++ )
6658         {
6659             CvPoint center;
6660             CvMat point_chunk;
6661             center.x = cvRandInt(&rng)%img->width;
6662             center.y = cvRandInt(&rng)%img->height;
6663             cvGetRows( points, &point_chunk, k*sample_count/cluster_count,
6664                        k == cluster_count - 1 ? sample_count : (k+1)*sample_count/cluster_count );
6665             cvRandArr( &rng, &point_chunk, CV_RAND_NORMAL,
6666                        cvScalar(center.x,center.y,0,0),
6667                        cvScalar(img->width/6, img->height/6,0,0) );
6668         }
6669
6670         /* shuffle samples */
6671         for( i = 0; i &lt; sample_count/2; i++ )
6672         {
6673             CvPoint2D32f* pt1 = (CvPoint2D32f*)points->data.fl + cvRandInt(&rng)%sample_count;
6674             CvPoint2D32f* pt2 = (CvPoint2D32f*)points->data.fl + cvRandInt(&rng)%sample_count;
6675             CvPoint2D32f temp;
6676             CV_SWAP( *pt1, *pt2, temp );
6677         }
6678
6679         cvKMeans2( points, cluster_count, clusters,
6680                    cvTermCriteria( CV_TERMCRIT_EPS+CV_TERMCRIT_ITER, 10, 1.0 ));
6681
6682         cvZero( img );
6683
6684         for( i = 0; i &lt; sample_count; i++ )
6685         {
6686             CvPoint2D32f pt = ((CvPoint2D32f*)points->data.fl)[i];
6687             int cluster_idx = clusters->data.i[i];
6688             cvCircle( img, cvPointFrom32f(pt), 2, color_tab[cluster_idx], CV_FILLED );
6689         }
6690
6691         cvReleaseMat( &amp;points );
6692         cvReleaseMat( &amp;clusters );
6693
6694         cvShowImage( "clusters", img );
6695
6696         int key = cvWaitKey(0);
6697         if( key == 27 ) // 'ESC'
6698             break;
6699     }
6700 }
6701 </pre>
6702
6703
6704 <hr><h3><a name="decl_cvSeqPartition">SeqPartition</a></h3>
6705 <p class="Blurb">Splits sequence into equivalence classes</p>
6706 <pre>
6707 typedef int (CV_CDECL* CvCmpFunc)(const void* a, const void* b, void* userdata);
6708 int cvSeqPartition( const CvSeq* seq, CvMemStorage* storage, CvSeq** labels,
6709                     CvCmpFunc is_equal, void* userdata );
6710 </pre><p><dl>
6711 <dt>seq<dd>The sequence to partition.
6712 <dt>storage<dd>The storage to store the sequence of equivalence classes. If it is NULL,
6713                the function uses <code>seq->storage</code> for output labels.
6714 <dt>labels<dd>Output parameter. Double pointer to the sequence
6715               of 0-based labels of input sequence elements.
6716 <dt>is_equal<dd>The relation function that should return non-zero if the two particular sequence elements
6717                 are from the same class, and zero otherwise.
6718                 The partitioning algorithm uses transitive closure of the relation function as equivalence criteria.
6719 <dt>userdata<dd>Pointer that is transparently passed to the <code>is_equal</code> function.
6720 </dl><p>
6721 The function <code>cvSeqPartition</code> implements quadratic algorithm for splitting
6722 a set into one or more classes of equivalence. The function returns the number of equivalence classes.
6723 </p>
6724 <h4>Example. Partitioning 2d point set.</h4>
6725 <pre>
6726 #include "cxcore.h"
6727 #include "highgui.h"
6728 #include &lt;stdio.h&gt;
6729
6730 CvSeq* point_seq = 0;
6731 IplImage* canvas = 0;
6732 CvScalar* colors = 0;
6733 int pos = 10;
6734
6735 int is_equal( const void* _a, const void* _b, void* userdata )
6736 {
6737     CvPoint a = *(const CvPoint*)_a;
6738     CvPoint b = *(const CvPoint*)_b;
6739     double threshold = *(double*)userdata;
6740     return (double)(a.x - b.x)*(a.x - b.x) + (double)(a.y - b.y)*(a.y - b.y) &lt;= threshold;
6741 }
6742
6743 void on_track( int pos )
6744 {
6745     CvSeq* labels = 0;
6746     double threshold = pos*pos;
6747     int i, class_count = cvSeqPartition( point_seq, 0, &labels, is_equal, &threshold );
6748     printf("%4d classes\n", class_count );
6749     cvZero( canvas );
6750
6751     for( i = 0; i &lt; labels-&gt;total; i++ )
6752     {
6753         CvPoint pt = *(CvPoint*)cvGetSeqElem( point_seq, i, 0 );
6754         CvScalar color = colors[*(int*)cvGetSeqElem( labels, i, 0 )];
6755         cvCircle( canvas, pt, 1, color, -1 );
6756     }
6757
6758     cvShowImage( "points", canvas );
6759 }
6760
6761 int main( int argc, char** argv )
6762 {
6763     CvMemStorage* storage = cvCreateMemStorage(0);
6764     point_seq = cvCreateSeq( CV_32SC2, sizeof(CvSeq), sizeof(CvPoint), storage );
6765     CvRNG rng = cvRNG(0xffffffff);
6766
6767     int width = 500, height = 500;
6768     int i, count = 1000;
6769     canvas = cvCreateImage( cvSize(width,height), 8, 3 );
6770
6771     colors = (CvScalar*)cvAlloc( count*sizeof(colors[0]) );
6772     for( i = 0; i &lt; count; i++ )
6773     {
6774         CvPoint pt;
6775         int icolor;
6776         pt.x = cvRandInt( &rng ) % width;
6777         pt.y = cvRandInt( &rng ) % height;
6778         cvSeqPush( point_seq, &pt );
6779         icolor = cvRandInt( &rng ) | 0x00404040;
6780         colors[i] = CV_RGB(icolor & 255, (icolor >> 8)&255, (icolor >> 16)&255);
6781     }
6782
6783     cvNamedWindow( "points", 1 );
6784     cvCreateTrackbar( "threshold", "points", &pos, 50, on_track );
6785     on_track(pos);
6786     cvWaitKey(0);
6787     return 0;
6788 }
6789 </pre>
6790
6791
6792 <hr><h1><a name="cxcore_system">Error Handling and System Functions</a></h1>
6793
6794 <hr><h2><a name="cxcore_system_error">Error Handling</a></h2>
6795
6796 <p>Error handling in OpenCV is similar to IPL (Image Processing Library).
6797 In case of error functions do not return the error code. Instead, they raise
6798 an error using <a href="#decl_error_macros">CV_ERROR</a> macro that calls
6799 <a href="#decl_cvError">cvError</a> that, in its turn, sets the error status
6800 with <a href="#decl_cvSetErrStatus">cvSetErrStatus</a> and
6801 calls a standard or user-defined error handler (that can display a message box,
6802 write to log etc., see <a href="#decl_cvRedirectError">cvRedirectError</a>,
6803 <a href="#decl_cvNulDevReport">cvNulDevReport, cvStdErrReport, cvGuiBoxReport</a>).
6804 There is global variable, one per each program thread, that contains current
6805 error status (an integer value). The status can be retrieved with
6806 <a href="#decl_cvGetErrStatus">cvGetErrStatus</a> function.
6807 </p>
6808 <p>
6809 There are three modes of error handling (see <a href="#decl_cvSetErrMode">cvSetErrMode</a>
6810 and <a href="#decl_cvGetErrMode">cvGetErrMode</a>):
6811 <dl>
6812 <dt>Leaf<dd>The program is terminated after error handler is called.
6813             <em>This is the default value</em>. It is useful for debugging, as the error
6814             is signalled immediately after it occurs. However, for production systems
6815             other two methods may be preferable as they provide more control.
6816 <dt>Parent<dd>The program is not terminated, but the error handler is called.
6817               The stack is unwinded (it is done w/o using C++ exception mechanism).
6818               User may check error code after calling Cxcore function with
6819               <a href="#decl_cvGetErrStatus">cvGetErrStatus</a> and react.
6820 <dt>Silent<dd>Similar to <em>Parent</em> mode, but no error handler is called.
6821 </dl>
6822 <p>Actually, the semantics of <em>Leaf</em> and <em>Parent</em> modes is implemented by
6823 error handlers and the above description is true for <a href="#decl_cvNulDevReport">cvNulDevReport, cvStdErrReport</a>.
6824 <a href="#decl_cvNulDevReport">cvGuiBoxReport</a> behaves slightly differently,
6825 and some custom error handler may implement quite different semantics.</p>
6826
6827 <hr><h3><a name="decl_error_macros">ERROR Handling Macros</a></h3>
6828 <p class="Blurb">Macros for raising an error, checking for errors etc.</p>
6829 <pre>
6830 /* special macros for enclosing processing statements within a function and separating
6831    them from prologue (resource initialization) and epilogue (guaranteed resource release) */
6832 #define __BEGIN__       {
6833 #define __END__         goto exit; exit: ; }
6834 /* proceeds to "resource release" stage */
6835 #define EXIT            goto exit
6836
6837 /* Declares locally the function name for CV_ERROR() use */
6838 #define CV_FUNCNAME( Name )  \
6839     static char cvFuncName[] = Name
6840
6841 /* Raises an error within the current context */
6842 #define CV_ERROR( Code, Msg )                                       \
6843 {                                                                   \
6844      cvError( (Code), cvFuncName, Msg, __FILE__, __LINE__ );        \
6845      EXIT;                                                          \
6846 }
6847
6848 /* Checks status after calling CXCORE function */
6849 #define CV_CHECK()                                                  \
6850 {                                                                   \
6851     if( cvGetErrStatus() &lt; 0 )                                   \
6852         CV_ERROR( CV_StsBackTrace, "Inner function failed." );      \
6853 }
6854
6855 /* Provides shorthand for CXCORE function call and CV_CHECK() */
6856 #define CV_CALL( Statement )                                        \
6857 {                                                                   \
6858     Statement;                                                      \
6859     CV_CHECK();                                                     \
6860 }
6861
6862 /* Checks some condition in both debug and release configurations */
6863 #define CV_ASSERT( Condition )                                          \
6864 {                                                                       \
6865     if( !(Condition) )                                                  \
6866         CV_ERROR( CV_StsInternal, "Assertion: " #Condition " failed" ); \
6867 }
6868
6869 /* these macros are similar to their CV_... counterparts, but they
6870    do not need exit label nor cvFuncName to be defined */
6871 #define OPENCV_ERROR(status,func_name,err_msg) ...
6872 #define OPENCV_ERRCHK(func_name,err_msg) ...
6873 #define OPENCV_ASSERT(condition,func_name,err_msg) ...
6874 #define OPENCV_CALL(statement) ...
6875 </pre>
6876 Instead of a discussion, here are the documented example
6877 of typical CXCORE function and the example of the function use.
6878 <h4><a name="decl_error_handling_sample">Use of Error Handling Macros</a></h4>
6879 <pre>
6880 #include "cxcore.h"
6881 #include &lt;stdio.h&gt;
6882
6883 void cvResizeDCT( CvMat* input_array, CvMat* output_array )
6884 {
6885     CvMat* temp_array = 0; // declare pointer that should be released anyway.
6886
6887     CV_FUNCNAME( "cvResizeDCT" ); // declare cvFuncName
6888
6889     __BEGIN__; // start processing. There may be some declarations just after this macro,
6890                // but they couldn't be accessed from the epilogue.
6891
6892     if( !CV_IS_MAT(input_array) || !CV_IS_MAT(output_array) )
6893         // use CV_ERROR() to raise an error
6894         CV_ERROR( CV_StsBadArg, "input_array or output_array are not valid matrices" );
6895
6896     // some restrictions that are going to be removed later, may be checked with CV_ASSERT()
6897     CV_ASSERT( input_array->rows == 1 && output_array->rows == 1 );
6898
6899     // use CV_CALL for safe function call
6900     CV_CALL( temp_array = cvCreateMat( input_array->rows, MAX(input_array->cols,output_array->cols),
6901                                        input_array->type ));
6902
6903     if( output_array->cols &gt; input_array->cols )
6904         CV_CALL( cvZero( temp_array ));
6905
6906     temp_array->cols = input_array->cols;
6907     CV_CALL( cvDCT( input_array, temp_array, CV_DXT_FORWARD ));
6908     temp_array->cols = output_array->cols;
6909     CV_CALL( cvDCT( temp_array, output_array, CV_DXT_INVERSE ));
6910     CV_CALL( cvScale( output_array, output_array, 1./sqrt((double)input_array->cols*output_array->cols), 0 ));
6911
6912     __END__; // finish processing. Epilogue follows after the macro.
6913
6914     // release temp_array. If temp_array has not been allocated before an error occurred, cvReleaseMat
6915     // takes care of it and does nothing in this case.
6916     cvReleaseMat( &temp_array );
6917 }
6918
6919
6920 int main( int argc, char** argv )
6921 {
6922     CvMat* src = cvCreateMat( 1, 512, CV_32F );
6923 #if 1 /* no errors */
6924     CvMat* dst = cvCreateMat( 1, 256, CV_32F );
6925 #else
6926     CvMat* dst = 0; /* test error processing mechanism */
6927 #endif
6928     cvSet( src, cvRealScalar(1.), 0 );
6929 #if 0 /* change 0 to 1 to suppress error handler invocation */
6930     cvSetErrMode( CV_ErrModeSilent );
6931 #endif
6932     cvResizeDCT( src, dst ); // if some error occurs, the message box will pop up, or a message will be
6933                              // written to log, or some user-defined processing will be done
6934     if( cvGetErrStatus() &lt; 0 )
6935         printf("Some error occurred" );
6936     else
6937         printf("Everything is OK" );
6938     return 0;
6939 }
6940 </pre>
6941
6942
6943 <hr><h3><a name="decl_cvGetErrStatus">GetErrStatus</a></h3>
6944 <p class="Blurb">Returns the current error status</p>
6945 <pre>
6946 int cvGetErrStatus( void );
6947 </pre><p>
6948 The function <code>cvGetErrStatus</code> returns the current error status -
6949 the value set with the last <a href="#decl_cvSetErrStatus">cvSetErrStatus</a> call. Note, that
6950 in <em>Leaf</em> mode the program terminates immediately after error occurred, so to
6951 always get control after the function call, one should call <a href="#decl_cvSetErrMode">cvSetErrMode</a>
6952 and set <em>Parent</em> or <em>Silent</em> error mode.
6953 </p>
6954
6955
6956 <hr><h3><a name="decl_cvSetErrStatus">SetErrStatus</a></h3>
6957 <p class="Blurb">Sets the error status</p>
6958 <pre>
6959 void cvSetErrStatus( int status );
6960 </pre><p><dl>
6961 <dt>status<dd>The error status.
6962 </dl><p>
6963 The function <code>cvSetErrStatus</code> sets the error status to
6964 the specified value. Mostly, the function is used to reset the error status (set to it <code>CV_StsOk</code>)
6965 to recover after error. In other cases it is more natural to call <a href="#decl_cvError">cvError</a> or
6966 <a href="#decl_error_macros">CV_ERROR</a>.
6967 </p>
6968
6969
6970 <hr><h3><a name="decl_cvGetErrMode">GetErrMode</a></h3>
6971 <p class="Blurb">Returns the current error mode</p>
6972 <pre>
6973 int cvGetErrMode( void );
6974 </pre><p>
6975 The function <code>cvGetErrMode</code> returns the current error mode -
6976 the value set with the last <a href="#decl_cvSetErrMode">cvSetErrMode</a> call.
6977 </p>
6978
6979
6980 <hr><h3><a name="decl_cvSetErrMode">SetErrMode</a></h3>
6981 <p class="Blurb">Sets the error mode</p>
6982 <pre>
6983 #define CV_ErrModeLeaf    0
6984 #define CV_ErrModeParent  1
6985 #define CV_ErrModeSilent  2
6986 int cvSetErrMode( int mode );
6987 </pre><p><dl>
6988 <dt>mode<dd>The error mode.
6989 </dl><p>
6990 The function <code>cvSetErrMode</code> sets the specified error mode.
6991 For description of different error modes see the beginning of the <a href="#cxcore_system_error">section</a>.
6992 </p>
6993
6994
6995 <hr><h3><a name="decl_cvError">Error</a></h3>
6996 <p class="Blurb">Raises an error</p>
6997 <pre>
6998 int cvError( int status, const char* func_name,
6999              const char* err_msg, const char* file_name, int line );
7000 </pre><p><dl>
7001 <dt>status<dd>The error status.
7002 <dt>func_name<dd>Name of the function where the error occurred.
7003 <dt>err_msg<dd>Additional information/diagnostics about the error.
7004 <dt>file_name<dd>Name of the file where the error occurred.
7005 <dt>line<dd>Line number, where the error occurred.
7006 </dl><p>
7007 The function <code>cvError</code> sets the error status
7008 to the specified value (via <a href="#decl_cvSetErrStatus">cvSetErrStatus</a>)
7009 and, if the error mode is not <em>Silent</em>, calls the error handler.</p>
7010
7011
7012 <hr><h3><a name="decl_cvErrorStr">ErrorStr</a></h3>
7013 <p class="Blurb">Returns textual description of error status code</p>
7014 <pre>
7015 const char* cvErrorStr( int status );
7016 </pre><p><dl>
7017 <dt>status<dd>The error status.
7018 </dl><p>
7019 The function <code>cvErrorStr</code> returns the textual description
7020 for the specified error status code. In case of unknown status the function returns NULL pointer.
7021 </p>
7022
7023
7024 <hr><h3><a name="decl_cvRedirectError">RedirectError</a></h3>
7025 <p class="Blurb">Sets a new error handler</p>
7026 <pre>
7027 typedef int (CV_CDECL *CvErrorCallback)( int status, const char* func_name,
7028                     const char* err_msg, const char* file_name, int line );
7029
7030 CvErrorCallback cvRedirectError( CvErrorCallback error_handler,
7031                                  void* userdata=NULL, void** prev_userdata=NULL );
7032 </pre><p><dl>
7033 <dt>error_handler<dd>The new error_handler.
7034 <dt>userdata<dd>Arbitrary pointer that is transparently passed to the error handler.
7035 <dt>prev_userdata<dd>Pointer to the previously assigned user data pointer.
7036 </dl><p>
7037 The function <code>cvRedirectError</code> sets a new error handler that
7038 can be one of <a href="#decl_cvNulDevReport">standard handlers</a> or a custom handler that has
7039 the certain interface. The handler takes the same parameters as <a href="#decl_cvError">cvError</a>
7040 function. If the handler returns non-zero value, the program is terminated, otherwise, it continues.
7041 The error handler may check the current error mode with <a href="#decl_cvGetErrMode">cvGetErrMode</a>
7042 to make a decision.
7043 </p>
7044
7045
7046 <hr><h3><a name="decl_cvNulDevReport">cvNulDevReport</a>
7047 <a name="decl_cvStdErrReport">cvStdErrReport</a>
7048 <a name="decl_cvGuiBoxReport">cvGuiBoxReport</a></h3>
7049 <p class="Blurb">Provide standard error handling</p>
7050 <pre>
7051 int cvNulDevReport( int status, const char* func_name,
7052                     const char* err_msg, const char* file_name,
7053                     int line, void* userdata );
7054
7055 int cvStdErrReport( int status, const char* func_name,
7056                     const char* err_msg, const char* file_name,
7057                     int line, void* userdata );
7058
7059 int cvGuiBoxReport( int status, const char* func_name,
7060                     const char* err_msg, const char* file_name,
7061                     int line, void* userdata );
7062 </pre><p><dl>
7063 <dt>status<dd>The error status.
7064 <dt>func_name<dd>Name of the function where the error occurred.
7065 <dt>err_msg<dd>Additional information/diagnostics about the error.
7066 <dt>file_name<dd>Name of the file where the error occurred.
7067 <dt>line<dd>Line number, where the error occurred.
7068 <dt>userdata<dd>Pointer to the user data. Ignored by the standard handlers.
7069 </dl><p>
7070 The functions <code>cvNullDevReport, cvStdErrReport</code> and <code>cvGuiBoxReport</code>
7071 provide standard error handling. <code>cvGuiBoxReport</code> is the default
7072 error handler on Win32 systems, <code>cvStdErrReport</code> - on other systems.
7073 <code>cvGuiBoxReport</code> pops up message box with the error description and
7074 suggest a few options. Below is the sample message box that may be received with the
7075 <a name="decl_error_handling_sample">sample code</a> above, if one introduce an error as described
7076 in the sample</p>
7077 <h4>Error Message Box</h4>
7078 <p>
7079 <img align="center" src="pics/errmsg.png" >
7080 </p>
7081 If the error handler is set <code>cvStdErrReport</code>, the above message will
7082 be printed to standard error output and program will be terminated or continued, depending on the
7083 current error mode.</p>
7084 <h4>Error Message printed to Standard Error Output (in <em>Leaf</em> mode)</h4>
7085 <pre>
7086 OpenCV ERROR: Bad argument (input_array or output_array are not valid matrices)
7087         in function cvResizeDCT, D:\User\VP\Projects\avl_proba\a.cpp(75)
7088 Terminating the application...
7089 </pre>
7090
7091
7092 <hr><h2><a name="cxcore_system_sys">System and Utility Functions</a></h2>
7093
7094 <hr><h3><a name="decl_cvAlloc">Alloc</a></h3>
7095 <p class="Blurb">Allocates memory buffer</p>
7096 <pre>
7097 void* cvAlloc( size_t size );
7098 </pre><p><dl>
7099 <dt>size<dd>Buffer size in bytes.
7100 </dl><p>
7101 The function <code>cvAlloc</code> allocates <code>size</code> bytes and
7102 returns pointer to the allocated buffer. In case of error
7103 the function reports an error and returns NULL pointer.
7104 By default cvAlloc calls icvAlloc which itself calls malloc,
7105 however it is possible to assign user-defined memory allocation/deallocation
7106 functions using <a href="#decl_cvSetMemoryManager">cvSetMemoryManager</a> function.
7107 </p>
7108
7109
7110 <hr><h3><a name="decl_cvFree">Free</a></h3>
7111 <p class="Blurb">Deallocates memory buffer</p>
7112 <pre>
7113 void cvFree( T** ptr );
7114 </pre><p><dl>
7115 <dt>buffer<dd>Double pointer to released buffer.
7116 </dl><p>
7117 The function <code>cvFree</code> deallocates memory buffer allocated by <a href="#decl_cvAlloc">cvAlloc</a>.
7118 It clears the pointer to buffer upon exit, that is why the double pointer is
7119 used. If *buffer is already NULL, the function does nothing
7120 </p>
7121
7122
7123 <hr><h3><a name="decl_cvGetTickCount">GetTickCount</a></h3>
7124 <p class="Blurb">Returns number of tics</p>
7125 <pre>
7126 int64 cvGetTickCount( void );
7127 </pre><p>
7128 The function <code>cvGetTickCount</code> returns number of tics
7129 starting from some platform-dependent event (number of CPU ticks from the startup, number of milliseconds
7130 from 1970th year etc.). The function is useful for accurate measurement of
7131 a function/user-code execution time. To convert the number of tics to time units, use
7132 <a href="#decl_cvGetTickFrequency">cvGetTickFrequency</a>.</p>
7133
7134 <hr><h3><a name="decl_cvGetTickFrequency">GetTickFrequency</a></h3>
7135 <p class="Blurb">Returns number of tics per microsecond</p>
7136 <pre>
7137 double cvGetTickFrequency( void );
7138 </pre><p>
7139 The function <code>cvGetTickFrequency</code> returns number of tics
7140 per microsecond. Thus, the quotient of <a href="#decl_cvGetTickCount">cvGetTickCount</a>() and
7141 <a href="#decl_cvGetTickFrequency">cvGetTickFrequency</a>() will give a number of microseconds
7142 starting from the platform-dependent event.</p>
7143
7144
7145 <hr><h3><a name="decl_cvRegisterModule">RegisterModule</a></h3>
7146 <p class="Blurb">Registers another module</p>
7147 <pre>
7148 typedef struct CvPluginFuncInfo
7149 {
7150     void** func_addr;
7151     void* default_func_addr;
7152     const char* func_names;
7153     int search_modules;
7154     int loaded_from;
7155 }
7156 CvPluginFuncInfo;
7157
7158 typedef struct CvModuleInfo
7159 {
7160     struct CvModuleInfo* next;
7161     const char* name;
7162     const char* version;
7163     CvPluginFuncInfo* func_tab;
7164 }
7165 CvModuleInfo;
7166
7167 int cvRegisterModule( const CvModuleInfo* module_info );
7168 </pre><p><dl>
7169 <dt>module_info<dd>Information about the module.
7170 </dl><p>
7171 The function <code>cvRegisterModule</code> adds module to the list of registered
7172 modules. After the module is registered, information about it can be retrieved
7173 using <a href="#decl_cvGetModuleInfo">cvGetModuleInfo</a> function. Also, the registered module
7174 makes full use of optimized plugins (IPP, MKL, ...), supported by CXCORE.
7175 CXCORE itself, CV (computer vision), CVAUX (auxiliary computer vision) and HIGHGUI
7176 (visualization & image/video acquisition) are examples of modules. Registration is usually done
7177 then the shared library is loaded. See cxcore/src/cxswitcher.cpp and cv/src/cvswitcher.cpp
7178 for details, how registration is done and
7179 look at cxcore/src/cxswitcher.cpp, cxcore/src/_cxipp.h on how IPP and MKL are connected to the modules.</p>
7180
7181
7182 <hr><h3><a name="decl_cvGetModuleInfo">GetModuleInfo</a></h3>
7183 <p class="Blurb">Retrieves information about the registered module(s) and plugins</p>
7184 <pre>
7185 void  cvGetModuleInfo( const char* module_name,
7186                        const char** version,
7187                        const char** loaded_addon_plugins );
7188 </pre><p><dl>
7189 <dt>module_name<dd>Name of the module of interest, or NULL, which means all the modules.
7190 <dt>version<dd>The output parameter. Information about the module(s), including version.
7191 <dt>loaded_addon_plugins<dd>The list of names and versions of the optimized plugins that CXCORE was
7192         able to find and load.
7193 </dl><p>
7194 The function <code>cvGetModuleInfo</code> returns information about one of
7195 or all of the registered modules. The returned information is stored inside the libraries, so
7196 user should not deallocate or modify the returned text strings.</p>
7197
7198
7199 <hr><h3><a name="decl_cvUseOptimized">UseOptimized</a></h3>
7200 <p class="Blurb">Switches between optimized/non-optimized modes</p>
7201 <pre>
7202 int cvUseOptimized( int on_off );
7203 </pre><p><dl>
7204 <dt>on_off<dd>Use optimized (&lt;&gt;0) or not (0).
7205 </dl><p>
7206 The function <code>cvUseOptimized</code> switches between the mode, where
7207 only pure C implementations from cxcore, OpenCV etc. are used, and the mode, where
7208 IPP and MKL functions are used if available. When <code>cvUseOptimized(0)</code> is called,
7209 all the optimized libraries are unloaded. The function may be useful for debugging, IPP&MKL upgrade
7210 on the fly, online speed comparisons etc. It returns the number of optimized functions loaded.
7211 Note that by default the optimized plugins are loaded, so it is not necessary to
7212 call <code>cvUseOptimized(1)</code> in the beginning of the program (actually, it will only
7213 increase the startup time)</p>
7214
7215
7216 <hr><h3><a name="decl_cvSetMemoryManager">SetMemoryManager</a></h3>
7217 <p class="Blurb">Assigns custom/default memory managing functions</p>
7218 <pre>
7219 typedef void* (CV_CDECL *CvAllocFunc)(size_t size, void* userdata);
7220 typedef int (CV_CDECL *CvFreeFunc)(void* pptr, void* userdata);
7221
7222 void cvSetMemoryManager( CvAllocFunc alloc_func=NULL,
7223                          CvFreeFunc free_func=NULL,
7224                          void* userdata=NULL );
7225 </pre><p><dl>
7226 <dt>alloc_func<dd>Allocation function; the interface is similar to <code>malloc</code>, except that <code>userdata</code>
7227               may be used to determine the context.
7228 <dt>free_func<dd>Deallocation function; the interface is similar to <code>free</code>.
7229 <dt>userdata<dd>User data that is transparently passed to the custom functions.
7230 </dl><p>
7231 The function <code>cvSetMemoryManager</code>
7232 sets user-defined memory management functions (replacements for malloc and free) that
7233 will be called by cvAlloc, cvFree and higher-level functions (e.g. cvCreateImage).
7234 Note, that the function should be called when there is data allocated using <a href="#decl_cvAlloc">cvAlloc<a>.
7235 Also, to avoid infinite recursive calls, it is not allowed to call <a href="#decl_cvAlloc">cvAlloc</a>
7236 and <a href="#decl_cvFree">cvFree</a> from the custom allocation/deallocation functions.</p>
7237 <p>
7238 If <code>alloc_func</code> and <code>free_func</code> pointers are <code>NULL</code>,
7239 the default memory managing functions are restored.</p>
7240
7241
7242 <hr><h3><a name="decl_cvSetIPLAllocators">SetIPLAllocators</a></h3>
7243 <p class="Blurb">Switches to IPL functions for image allocation/deallocation</p>
7244 <pre>
7245 typedef IplImage* (CV_STDCALL* Cv_iplCreateImageHeader)
7246                             (int,int,int,char*,char*,int,int,int,int,int,
7247                             IplROI*,IplImage*,void*,IplTileInfo*);
7248 typedef void (CV_STDCALL* Cv_iplAllocateImageData)(IplImage*,int,int);
7249 typedef void (CV_STDCALL* Cv_iplDeallocate)(IplImage*,int);
7250 typedef IplROI* (CV_STDCALL* Cv_iplCreateROI)(int,int,int,int,int);
7251 typedef IplImage* (CV_STDCALL* Cv_iplCloneImage)(const IplImage*);
7252
7253 void cvSetIPLAllocators( Cv_iplCreateImageHeader create_header,
7254                          Cv_iplAllocateImageData allocate_data,
7255                          Cv_iplDeallocate deallocate,
7256                          Cv_iplCreateROI create_roi,
7257                          Cv_iplCloneImage clone_image );
7258
7259 #define CV_TURN_ON_IPL_COMPATIBILITY()                                  \
7260     cvSetIPLAllocators( iplCreateImageHeader, iplAllocateImage,         \
7261                         iplDeallocate, iplCreateROI, iplCloneImage )
7262 </pre><p><dl>
7263 <dt>create_header<dd>Pointer to iplCreateImageHeader.
7264 <dt>allocate_data<dd>Pointer to iplAllocateImage.
7265 <dt>deallocate<dd>Pointer to iplDeallocate.
7266 <dt>create_roi<dd>Pointer to iplCreateROI.
7267 <dt>clone_image<dd>Pointer to iplCloneImage.
7268 </dl><p>
7269 The function <code>cvSetIPLAllocators</code>
7270 makes CXCORE to use IPL functions for image allocation/deallocation operations.
7271 For convenience, there is the wrapping macro <code>CV_TURN_ON_IPL_COMPATIBILITY</code>.
7272 The function is useful for applications where IPL and CXCORE/OpenCV are used together and still
7273 there are calls to <code>iplCreateImageHeader</code> etc. The function is not necessary if
7274 IPL is called only for data processing and all the allocation/deallocation is done by CXCORE,
7275 or if all the allocation/deallocation is done by IPL and some of OpenCV functions are used to
7276 process the data.</p>
7277
7278
7279 <hr><h3><a name="decl_cvGetNumThreads">GetNumThreads</a></h3>
7280 <p class="Blurb">Returns the current number of threads used</p>
7281 <pre>
7282 int cvGetNumThreads(void);
7283 </pre>
7284 <p>
7285 The function <code>cvGetNumThreads</code> return the current number of threads
7286 that are used by parallelized (via OpenMP) OpenCV functions.</p>
7287
7288
7289 <hr><h3><a name="decl_cvSetNumThreads">SetNumThreads</a></h3>
7290 <p class="Blurb">Sets the number of threads</p>
7291 <pre>
7292 void cvSetNumThreads( int threads=0 );
7293 </pre><p><dl>
7294 <dt>threads<dd>The number of threads.
7295 </dl><p>
7296 The function <code>cvSetNumThreads</code> sets the number of threads
7297 that are used by parallelized OpenCV functions. When the argument
7298 is zero or negative, and at the beginning of the program,
7299 the number of threads is set to the number of processors in the system,
7300 as returned by the function <code>omp_get_num_procs()</code> from OpenMP runtime.
7301 </p>
7302
7303
7304 <hr><h3><a name="decl_cvGetThreadNum">GetThreadNum</a></h3>
7305 <p class="Blurb">Returns index of the current thread</p>
7306 <pre>
7307 int cvGetThreadNum( void );
7308 </pre><p>
7309 The function <code>cvGetThreadNum</code> returns the index, from 0 to
7310 <a href="#decl_cvGetNumThreads">cvGetNumThreads</a>()-1, of the thread that called the function.
7311 It is a wrapper for the function <code>omp_get_thread_num()</code> from OpenMP runtime.
7312 The retrieved index may be used to access local-thread data inside the parallelized code fragments.
7313 </p>
7314
7315
7316 <hr><h1><a name="cxcore_func_index">Alphabetical List of Functions</a></h1>
7317
7318 <hr><h3>A</h3>
7319 <table width="100%">
7320 <tr>
7321 <td width="25%"><a href="#decl_cvAbsDiff">AbsDiff</a></td>
7322 <td width="25%"><a href="#decl_cvAddWeighted">AddWeighted</a></td>
7323 <td width="25%"><a href="#decl_cvAvg">Avg</a></td>
7324 </tr>
7325 <tr>
7326 <td width="25%"><a href="#decl_cvAbsDiffS">AbsDiffS</a></td>
7327 <td width="25%"><a href="#decl_cvAlloc">Alloc</a></td>
7328 <td width="25%"><a href="#decl_cvAvgSdv">AvgSdv</a></td>
7329 </tr>
7330 <tr>
7331 <td width="25%"><a href="#decl_cvAdd">Add</a></td>
7332 <td width="25%"><a href="#decl_cvAnd">And</a></td>
7333 <td width="25%%"></td>
7334 </tr>
7335 <tr>
7336 <td width="25%"><a href="#decl_cvAddS">AddS</a></td>
7337 <td width="25%"><a href="#decl_cvAndS">AndS</a></td>
7338 <td width="25%%"></td>
7339 </tr>
7340 </table>
7341 <hr><h3>B</h3>
7342 <table width="100%">
7343 <tr>
7344 <td width="25%"><a href="#decl_cvBackProjectPCA">BackProjectPCA</a></td>
7345 <td width="25%%"></td>
7346 <td width="25%%"></td>
7347 </tr>
7348 </table>
7349 <hr><h3>C</h3>
7350 <table width="100%">
7351 <tr>
7352 <td width="25%"><a href="#decl_cvCalcCovarMatrix">CalcCovarMatrix</a></td>
7353 <td width="25%"><a href="#decl_cvCloneGraph">CloneGraph</a></td>
7354 <td width="25%"><a href="#decl_cvCreateGraph">CreateGraph</a></td>
7355 </tr>
7356 <tr>
7357 <td width="25%"><a href="#decl_cvCalcPCA">CalcPCA</a></td>
7358 <td width="25%"><a href="#decl_cvCloneImage">CloneImage</a></td>
7359 <td width="25%"><a href="#decl_cvCreateGraphScanner">CreateGraphScanner</a></td>
7360 </tr>
7361 <tr>
7362 <td width="25%"><a href="#decl_cvCartToPolar">CartToPolar</a></td>
7363 <td width="25%"><a href="#decl_cvCloneMat">CloneMat</a></td>
7364 <td width="25%"><a href="#decl_cvCreateImage">CreateImage</a></td>
7365 </tr>
7366 <tr>
7367 <td width="25%"><a href="#decl_cvCbrt">Cbrt</a></td>
7368 <td width="25%"><a href="#decl_cvCloneMatND">CloneMatND</a></td>
7369 <td width="25%"><a href="#decl_cvCreateImageHeader">CreateImageHeader</a></td>
7370 </tr>
7371 <tr>
7372 <td width="25%"><a href="#decl_cvCheckArr">CheckArr</a></td>
7373 <td width="25%"><a href="#decl_cvCloneSeq">CloneSeq</a></td>
7374 <td width="25%"><a href="#decl_cvCreateMat">CreateMat</a></td>
7375 </tr>
7376 <tr>
7377 <td width="25%"><a href="#decl_cvCircle">Circle</a></td>
7378 <td width="25%"><a href="#decl_cvCloneSparseMat">CloneSparseMat</a></td>
7379 <td width="25%"><a href="#decl_cvCreateMatHeader">CreateMatHeader</a></td>
7380 </tr>
7381 <tr>
7382 <td width="25%"><a href="#decl_cvClearGraph">ClearGraph</a></td>
7383 <td width="25%"><a href="#decl_cvCmp">Cmp</a></td>
7384 <td width="25%"><a href="#decl_cvCreateMatND">CreateMatND</a></td>
7385 </tr>
7386 <tr>
7387 <td width="25%"><a href="#decl_cvClearMemStorage">ClearMemStorage</a></td>
7388 <td width="25%"><a href="#decl_cvCmpS">CmpS</a></td>
7389 <td width="25%"><a href="#decl_cvCreateMatNDHeader">CreateMatNDHeader</a></td>
7390 </tr>
7391 <tr>
7392 <td width="25%"><a href="#decl_cvClearND">ClearND</a></td>
7393 <td width="25%"><a href="#decl_cvConvertScale">ConvertScale</a></td>
7394 <td width="25%"><a href="#decl_cvCreateMemStorage">CreateMemStorage</a></td>
7395 </tr>
7396 <tr>
7397 <td width="25%"><a href="#decl_cvClearSeq">ClearSeq</a></td>
7398 <td width="25%"><a href="#decl_cvConvertScaleAbs">ConvertScaleAbs</a></td>
7399 <td width="25%"><a href="#decl_cvCreateSeq">CreateSeq</a></td>
7400 </tr>
7401 <tr>
7402 <td width="25%"><a href="#decl_cvClearSet">ClearSet</a></td>
7403 <td width="25%"><a href="#decl_cvCopy">Copy</a></td>
7404 <td width="25%"><a href="#decl_cvCreateSet">CreateSet</a></td>
7405 </tr>
7406 <tr>
7407 <td width="25%"><a href="#decl_cvClipLine">ClipLine</a></td>
7408 <td width="25%"><a href="#decl_cvCountNonZero">CountNonZero</a></td>
7409 <td width="25%"><a href="#decl_cvCreateSparseMat">CreateSparseMat</a></td>
7410 </tr>
7411 <tr>
7412 <td width="25%"><a href="#decl_cvClipLine">ClipLine</a></td>
7413 <td width="25%"><a href="#decl_cvCreateChildMemStorage">CreateChildMemStorage</a></td>
7414 <td width="25%"><a href="#decl_cvCrossProduct">CrossProduct</a></td>
7415 </tr>
7416 <tr>
7417 <td width="25%"><a href="#decl_cvClone">Clone</a></td>
7418 <td width="25%"><a href="#decl_cvCreateData">CreateData</a></td>
7419 <td width="25%"><a href="#decl_cvCvtSeqToArray">CvtSeqToArray</a></td>
7420 </tr>
7421 </table>
7422 <hr><h3>D</h3>
7423 <table width="100%">
7424 <tr>
7425 <td width="25%"><a href="#decl_cvDCT">DCT</a></td>
7426 <td width="25%"><a href="#decl_cvDet">Det</a></td>
7427 <td width="25%"><a href="#decl_cvDrawContours">DrawContours</a></td>
7428 </tr>
7429 <tr>
7430 <td width="25%"><a href="#decl_cvDFT">DFT</a></td>
7431 <td width="25%"><a href="#decl_cvDiv">Div</a></td>
7432 <td width="25%%"></td>
7433 </tr>
7434 <tr>
7435 <td width="25%"><a href="#decl_cvDecRefData">DecRefData</a></td>
7436 <td width="25%"><a href="#decl_cvDotProduct">DotProduct</a></td>
7437 <td width="25%%"></td>
7438 </tr>
7439 </table>
7440 <hr><h3>E</h3>
7441 <table width="100%">
7442 <tr>
7443 <td width="25%"><a href="#decl_cvEigenVV">EigenVV</a></td>
7444 <td width="25%"><a href="#decl_cvEllipseBox">EllipseBox</a></td>
7445 <td width="25%"><a href="#decl_cvError">Error</a></td>
7446 </tr>
7447 <tr>
7448 <td width="25%"><a href="#decl_cvEllipse">Ellipse</a></td>
7449 <td width="25%"><a href="#decl_cvEndWriteSeq">EndWriteSeq</a></td>
7450 <td width="25%"><a href="#decl_cvErrorStr">ErrorStr</a></td>
7451 </tr>
7452 <tr>
7453 <td width="25%"><a href="#decl_cvEllipse2Poly">Ellipse2Poly</a></td>
7454 <td width="25%"><a href="#decl_cvEndWriteStruct">EndWriteStruct</a></td>
7455 <td width="25%"><a href="#decl_cvExp">Exp</a></td>
7456 </tr>
7457 </table>
7458 <hr><h3>F</h3>
7459 <table width="100%">
7460 <tr>
7461 <td width="25%"><a href="#decl_cvFastArctan">FastArctan</a></td>
7462 <td width="25%"><a href="#decl_cvFindGraphEdgeByPtr">FindGraphEdgeByPtr</a></td>
7463 <td width="25%"><a href="#decl_cvFlushSeqWriter">FlushSeqWriter</a></td>
7464 </tr>
7465 <tr>
7466 <td width="25%"><a href="#decl_cvFillConvexPoly">FillConvexPoly</a></td>
7467 <td width="25%"><a href="#decl_cvFindType">FindType</a></td>
7468 <td width="25%"><a href="#decl_cvFree">Free</a></td>
7469 </tr>
7470 <tr>
7471 <td width="25%"><a href="#decl_cvFillPoly">FillPoly</a></td>
7472 <td width="25%"><a href="#decl_cvFirstType">FirstType</a></td>
7473 <td width="25%%"></td>
7474 </tr>
7475 <tr>
7476 <td width="25%"><a href="#decl_cvFindGraphEdge">FindGraphEdge</a></td>
7477 <td width="25%"><a href="#decl_cvFlip">Flip</a></td>
7478 <td width="25%%"></td>
7479 </tr>
7480 </table>
7481 <hr><h3>G</h3>
7482 <table width="100%">
7483 <tr>
7484 <td width="25%"><a href="#decl_cvGEMM">GEMM</a></td>
7485 <td width="25%"><a href="#decl_cvGetMat">GetMat</a></td>
7486 <td width="25%"><a href="#decl_cvGetTickCount">GetTickCount</a></td>
7487 </tr>
7488 <tr>
7489 <td width="25%"><a href="#decl_cvGet*D">Get*D</a></td>
7490 <td width="25%"><a href="#decl_cvGetModuleInfo">GetModuleInfo</a></td>
7491 <td width="25%"><a href="#decl_cvGetTickFrequency">GetTickFrequency</a></td>
7492 </tr>
7493 <tr>
7494 <td width="25%"><a href="#decl_cvGetCol">GetCol</a></td>
7495 <td width="25%"><a href="#decl_cvGetNextSparseNode">GetNextSparseNode</a></td>
7496 <td width="25%"><a href="#decl_cvGraphAddEdge">GraphAddEdge</a></td>
7497 </tr>
7498 <tr>
7499 <td width="25%"><a href="#decl_cvGetDiag">GetDiag</a></td>
7500 <td width="25%"><a href="#decl_cvGetNumThreads">GetNumThreads</a></td>
7501 <td width="25%"><a href="#decl_cvGraphAddEdgeByPtr">GraphAddEdgeByPtr</a></td>
7502 </tr>
7503 <tr>
7504 <td width="25%"><a href="#decl_cvGetDims">GetDims</a></td>
7505 <td width="25%"><a href="#decl_cvGetOptimalDFTSize">GetOptimalDFTSize</a></td>
7506 <td width="25%"><a href="#decl_cvGraphAddVtx">GraphAddVtx</a></td>
7507 </tr>
7508 <tr>
7509 <td width="25%"><a href="#decl_cvGetElemType">GetElemType</a></td>
7510 <td width="25%"><a href="#decl_cvGetRawData">GetRawData</a></td>
7511 <td width="25%"><a href="#decl_cvGraphEdgeIdx">GraphEdgeIdx</a></td>
7512 </tr>
7513 <tr>
7514 <td width="25%"><a href="#decl_cvGetErrMode">GetErrMode</a></td>
7515 <td width="25%"><a href="#decl_cvGetReal*D">GetReal*D</a></td>
7516 <td width="25%"><a href="#decl_cvGraphRemoveEdge">GraphRemoveEdge</a></td>
7517 </tr>
7518 <tr>
7519 <td width="25%"><a href="#decl_cvGetErrStatus">GetErrStatus</a></td>
7520 <td width="25%"><a href="#decl_cvGetRootFileNode">GetRootFileNode</a></td>
7521 <td width="25%"><a href="#decl_cvGraphRemoveEdgeByPtr">GraphRemoveEdgeByPtr</a></td>
7522 </tr>
7523 <tr>
7524 <td width="25%"><a href="#decl_cvGetFileNode">GetFileNode</a></td>
7525 <td width="25%"><a href="#decl_cvGetRow">GetRow</a></td>
7526 <td width="25%"><a href="#decl_cvGraphRemoveVtx">GraphRemoveVtx</a></td>
7527 </tr>
7528 <tr>
7529 <td width="25%"><a href="#decl_cvGetFileNodeByName">GetFileNodeByName</a></td>
7530 <td width="25%"><a href="#decl_cvGetSeqElem">GetSeqElem</a></td>
7531 <td width="25%"><a href="#decl_cvGraphRemoveVtxByPtr">GraphRemoveVtxByPtr</a></td>
7532 </tr>
7533 <tr>
7534 <td width="25%"><a href="#decl_cvGetFileNodeName">GetFileNodeName</a></td>
7535 <td width="25%"><a href="#decl_cvGetSeqReaderPos">GetSeqReaderPos</a></td>
7536 <td width="25%"><a href="#decl_cvGraphVtxDegree">GraphVtxDegree</a></td>
7537 </tr>
7538 <tr>
7539 <td width="25%"><a href="#decl_cvGetGraphVtx">GetGraphVtx</a></td>
7540 <td width="25%"><a href="#decl_cvGetSetElem">GetSetElem</a></td>
7541 <td width="25%"><a href="#decl_cvGraphVtxDegreeByPtr">GraphVtxDegreeByPtr</a></td>
7542 </tr>
7543 <tr>
7544 <td width="25%"><a href="#decl_cvGetHashedKey">GetHashedKey</a></td>
7545 <td width="25%"><a href="#decl_cvGetSize">GetSize</a></td>
7546 <td width="25%"><a href="#decl_cvGraphVtxIdx">GraphVtxIdx</a></td>
7547 </tr>
7548 <tr>
7549 <td width="25%"><a href="#decl_cvGetImage">GetImage</a></td>
7550 <td width="25%"><a href="#decl_cvGetSubRect">GetSubRect</a></td>
7551 <td width="25%"><a href="#decl_cvGuiBoxReport">GuiBoxReport</a></td>
7552 </tr>
7553 <tr>
7554 <td width="25%"><a href="#decl_cvGetImageCOI">GetImageCOI</a></td>
7555 <td width="25%"><a href="#decl_cvGetTextSize">GetTextSize</a></td>
7556 <td width="25%"><a href="#decl_cvmGet">Get</a></td>
7557 </tr>
7558 <tr>
7559 <td width="25%"><a href="#decl_cvGetImageROI">GetImageROI</a></td>
7560 <td width="25%"><a href="#decl_cvGetThreadNum">GetThreadNum</a></td>
7561 <td width="25%%"></td>
7562 </tr>
7563 </table>
7564 <hr><h3>I</h3>
7565 <table width="100%">
7566 <tr>
7567 <td width="25%"><a href="#decl_cvInRange">InRange</a></td>
7568 <td width="25%"><a href="#decl_cvInitLineIterator">InitLineIterator</a></td>
7569 <td width="25%"><a href="#decl_cvInsertNodeIntoTree">InsertNodeIntoTree</a></td>
7570 </tr>
7571 <tr>
7572 <td width="25%"><a href="#decl_cvInRangeS">InRangeS</a></td>
7573 <td width="25%"><a href="#decl_cvInitMatHeader">InitMatHeader</a></td>
7574 <td width="25%"><a href="#decl_cvInvSqrt">InvSqrt</a></td>
7575 </tr>
7576 <tr>
7577 <td width="25%"><a href="#decl_cvIncRefData">IncRefData</a></td>
7578 <td width="25%"><a href="#decl_cvInitMatNDHeader">InitMatNDHeader</a></td>
7579 <td width="25%"><a href="#decl_cvInvert">Invert</a></td>
7580 </tr>
7581 <tr>
7582 <td width="25%"><a href="#decl_cvInitFont">InitFont</a></td>
7583 <td width="25%"><a href="#decl_cvInitSparseMatIterator">InitSparseMatIterator</a></td>
7584 <td width="25%"><a href="#decl_cvIsInf">IsInf</a></td>
7585 </tr>
7586 <tr>
7587 <td width="25%"><a href="#decl_cvInitImageHeader">InitImageHeader</a></td>
7588 <td width="25%"><a href="#decl_cvInitTreeNodeIterator">InitTreeNodeIterator</a></td>
7589 <td width="25%"><a href="#decl_cvIsNaN">IsNaN</a></td>
7590 </tr>
7591 </table>
7592 <hr><h3>K</h3>
7593 <table width="100%">
7594 <tr>
7595 <td width="25%"><a href="#decl_cvKMeans2">KMeans2</a></td>
7596 <td width="25%%"></td>
7597 <td width="25%%"></td>
7598 </tr>
7599 </table>
7600 <hr><h3>L</h3>
7601 <table width="100%">
7602 <tr>
7603 <td width="25%"><a href="#decl_cvLUT">LUT</a></td>
7604 <td width="25%"><a href="#decl_cvLoad">Load</a></td>
7605 <td width="25%%"></td>
7606 </tr>
7607 <tr>
7608 <td width="25%"><a href="#decl_cvLine">Line</a></td>
7609 <td width="25%"><a href="#decl_cvLog">Log</a></td>
7610 <td width="25%%"></td>
7611 </tr>
7612 </table>
7613 <hr><h3>M</h3>
7614 <table width="100%">
7615 <tr>
7616 <td width="25%"><a href="#decl_cvMahalonobis">Mahalonobis</a></td>
7617 <td width="25%"><a href="#decl_cvMemStorageAlloc">MemStorageAlloc</a></td>
7618 <td width="25%"><a href="#decl_cvMinS">MinS</a></td>
7619 </tr>
7620 <tr>
7621 <td width="25%"><a href="#decl_cvMakeSeqHeaderForArray">MakeSeqHeaderForArray</a></td>
7622 <td width="25%"><a href="#decl_cvMemStorageAllocString">MemStorageAllocString</a></td>
7623 <td width="25%"><a href="#decl_cvMixChannels">MixChannels</a></td>
7624 </tr>
7625 <tr>
7626 <td width="25%"><a href="#decl_cvMat">Mat</a></td>
7627 <td width="25%"><a href="#decl_cvMerge">Merge</a></td>
7628 <td width="25%"><a href="#decl_cvMul">Mul</a></td>
7629 </tr>
7630 <tr>
7631 <td width="25%"><a href="#decl_cvMax">Max</a></td>
7632 <td width="25%"><a href="#decl_cvMin">Min</a></td>
7633 <td width="25%"><a href="#decl_cvMulSpectrums">MulSpectrums</a></td>
7634 </tr>
7635 <tr>
7636 <td width="25%"><a href="#decl_cvMaxS">MaxS</a></td>
7637 <td width="25%"><a href="#decl_cvMinMaxLoc">MinMaxLoc</a></td>
7638 <td width="25%"><a href="#decl_cvMulTransposed">MulTransposed</a></td>
7639 </tr>
7640 </table>
7641 <hr><h3>N</h3>
7642 <table width="100%">
7643 <tr>
7644 <td width="25%"><a href="#decl_cvNextGraphItem">NextGraphItem</a></td>
7645 <td width="25%"><a href="#decl_cvNorm">Norm</a></td>
7646 <td width="25%"><a href="#decl_cvNot">Not</a></td>
7647 </tr>
7648 <tr>
7649 <td width="25%"><a href="#decl_cvNextTreeNode">NextTreeNode</a></td>
7650 <td width="25%"><a href="#decl_cvNormalize">Normalize</a></td>
7651 <td width="25%"><a href="#decl_cvNulDevReport">NulDevReport</a></td>
7652 </tr>
7653 </table>
7654 <hr><h3>O</h3>
7655 <table width="100%">
7656 <tr>
7657 <td width="25%"><a href="#decl_cvOpenFileStorage">OpenFileStorage</a></td>
7658 <td width="25%"><a href="#decl_cvOr">Or</a></td>
7659 <td width="25%"><a href="#decl_cvOrS">OrS</a></td>
7660 </tr>
7661 </table>
7662 <hr><h3>P</h3>
7663 <table width="100%">
7664 <tr>
7665 <td width="25%"><a href="#decl_cvPerspectiveTransform">PerspectiveTransform</a></td>
7666 <td width="25%"><a href="#decl_cvPow">Pow</a></td>
7667 <td width="25%"><a href="#decl_cvPtr*D">Ptr*D</a></td>
7668 </tr>
7669 <tr>
7670 <td width="25%"><a href="#decl_cvPolarToCart">PolarToCart</a></td>
7671 <td width="25%"><a href="#decl_cvPrevTreeNode">PrevTreeNode</a></td>
7672 <td width="25%"><a href="#decl_cvPutText">PutText</a></td>
7673 </tr>
7674 <tr>
7675 <td width="25%"><a href="#decl_cvPolyLine">PolyLine</a></td>
7676 <td width="25%"><a href="#decl_cvProjectPCA">ProjectPCA</a></td>
7677 <td width="25%%"></td>
7678 </tr>
7679 </table>
7680 <hr><h3>R</h3>
7681 <table width="100%">
7682 <tr>
7683 <td width="25%"><a href="#decl_cvRNG">RNG</a></td>
7684 <td width="25%"><a href="#decl_cvReadRealByName">ReadRealByName</a></td>
7685 <td width="25%"><a href="#decl_cvReleaseImageHeader">ReleaseImageHeader</a></td>
7686 </tr>
7687 <tr>
7688 <td width="25%"><a href="#decl_cvRandArr">RandArr</a></td>
7689 <td width="25%"><a href="#decl_cvReadString">ReadString</a></td>
7690 <td width="25%"><a href="#decl_cvReleaseMat">ReleaseMat</a></td>
7691 </tr>
7692 <tr>
7693 <td width="25%"><a href="#decl_cvRandInt">RandInt</a></td>
7694 <td width="25%"><a href="#decl_cvReadStringByName">ReadStringByName</a></td>
7695 <td width="25%"><a href="#decl_cvReleaseMatND">ReleaseMatND</a></td>
7696 </tr>
7697 <tr>
7698 <td width="25%"><a href="#decl_cvRandReal">RandReal</a></td>
7699 <td width="25%"><a href="#decl_cvRectangle">Rectangle</a></td>
7700 <td width="25%"><a href="#decl_cvReleaseMemStorage">ReleaseMemStorage</a></td>
7701 </tr>
7702 <tr>
7703 <td width="25%"><a href="#decl_cvRandShuffle">RandShuffle</a></td>
7704 <td width="25%"><a href="#decl_cvRedirectError">RedirectError</a></td>
7705 <td width="25%"><a href="#decl_cvReleaseSparseMat">ReleaseSparseMat</a></td>
7706 </tr>
7707 <tr>
7708 <td width="25%"><a href="#decl_cvRange">Range</a></td>
7709 <td width="25%"><a href="#decl_cvReduce">Reduce</a></td>
7710 <td width="25%"><a href="#decl_cvRemoveNodeFromTree">RemoveNodeFromTree</a></td>
7711 </tr>
7712 <tr>
7713 <td width="25%"><a href="#decl_cvRead">Read</a></td>
7714 <td width="25%"><a href="#decl_cvRegisterModule">RegisterModule</a></td>
7715 <td width="25%"><a href="#decl_cvRepeat">Repeat</a></td>
7716 </tr>
7717 <tr>
7718 <td width="25%"><a href="#decl_cvReadByName">ReadByName</a></td>
7719 <td width="25%"><a href="#decl_cvRegisterType">RegisterType</a></td>
7720 <td width="25%"><a href="#decl_cvResetImageROI">ResetImageROI</a></td>
7721 </tr>
7722 <tr>
7723 <td width="25%"><a href="#decl_cvReadInt">ReadInt</a></td>
7724 <td width="25%"><a href="#decl_cvRelease">Release</a></td>
7725 <td width="25%"><a href="#decl_cvReshape">Reshape</a></td>
7726 </tr>
7727 <tr>
7728 <td width="25%"><a href="#decl_cvReadIntByName">ReadIntByName</a></td>
7729 <td width="25%"><a href="#decl_cvReleaseData">ReleaseData</a></td>
7730 <td width="25%"><a href="#decl_cvReshapeMatND">ReshapeMatND</a></td>
7731 </tr>
7732 <tr>
7733 <td width="25%"><a href="#decl_cvReadRawData">ReadRawData</a></td>
7734 <td width="25%"><a href="#decl_cvReleaseFileStorage">ReleaseFileStorage</a></td>
7735 <td width="25%"><a href="#decl_cvRestoreMemStoragePos">RestoreMemStoragePos</a></td>
7736 </tr>
7737 <tr>
7738 <td width="25%"><a href="#decl_cvReadRawDataSlice">ReadRawDataSlice</a></td>
7739 <td width="25%"><a href="#decl_cvReleaseGraphScanner">ReleaseGraphScanner</a></td>
7740 <td width="25%"><a href="#decl_cvRound">Round</a></td>
7741 </tr>
7742 <tr>
7743 <td width="25%"><a href="#decl_cvReadReal">ReadReal</a></td>
7744 <td width="25%"><a href="#decl_cvReleaseImage">ReleaseImage</a></td>
7745 <td width="25%%"></td>
7746 </tr>
7747 </table>
7748 <hr><h3>S</h3>
7749 <table width="100%">
7750 <tr>
7751 <td width="25%"><a href="#decl_cvSVBkSb">SVBkSb</a></td>
7752 <td width="25%"><a href="#decl_cvSeqSlice">SeqSlice</a></td>
7753 <td width="25%"><a href="#decl_cvSetSeqReaderPos">SetSeqReaderPos</a></td>
7754 </tr>
7755 <tr>
7756 <td width="25%"><a href="#decl_cvSVD">SVD</a></td>
7757 <td width="25%"><a href="#decl_cvSeqSort">SeqSort</a></td>
7758 <td width="25%"><a href="#decl_cvSetZero">SetZero</a></td>
7759 </tr>
7760 <tr>
7761 <td width="25%"><a href="#decl_cvSave">Save</a></td>
7762 <td width="25%"><a href="#decl_cvSet">Set</a></td>
7763 <td width="25%"><a href="#decl_cvSolve">Solve</a></td>
7764 </tr>
7765 <tr>
7766 <td width="25%"><a href="#decl_cvSaveMemStoragePos">SaveMemStoragePos</a></td>
7767 <td width="25%"><a href="#decl_cvSet*D">Set*D</a></td>
7768 <td width="25%"><a href="#decl_cvSolveCubic">SolveCubic</a></td>
7769 </tr>
7770 <tr>
7771 <td width="25%"><a href="#decl_cvScaleAdd">ScaleAdd</a></td>
7772 <td width="25%"><a href="#decl_cvSetAdd">SetAdd</a></td>
7773 <td width="25%"><a href="#decl_cvSolvePoly">SolvePoly</a></td>
7774 </tr>
7775 <tr>
7776 <td width="25%"><a href="#decl_cvSeqElemIdx">SeqElemIdx</a></td>
7777 <td width="25%"><a href="#decl_cvSetData">SetData</a></td>
7778 <td width="25%"><a href="#decl_cvSqrt">Sqrt</a></td>
7779 </tr>
7780 <tr>
7781 <td width="25%"><a href="#decl_cvSeqInsert">SeqInsert</a></td>
7782 <td width="25%"><a href="#decl_cvSetErrMode">SetErrMode</a></td>
7783 <td width="25%"><a href="#decl_cvStartAppendToSeq">StartAppendToSeq</a></td>
7784 </tr>
7785 <tr>
7786 <td width="25%"><a href="#decl_cvSeqInsertSlice">SeqInsertSlice</a></td>
7787 <td width="25%"><a href="#decl_cvSetErrStatus">SetErrStatus</a></td>
7788 <td width="25%"><a href="#decl_cvStartNextStream">StartNextStream</a></td>
7789 </tr>
7790 <tr>
7791 <td width="25%"><a href="#decl_cvSeqInvert">SeqInvert</a></td>
7792 <td width="25%"><a href="#decl_cvSetIPLAllocators">SetIPLAllocators</a></td>
7793 <td width="25%"><a href="#decl_cvStartReadRawData">StartReadRawData</a></td>
7794 </tr>
7795 <tr>
7796 <td width="25%"><a href="#decl_cvSeqPartition">SeqPartition</a></td>
7797 <td width="25%"><a href="#decl_cvSetIdentity">SetIdentity</a></td>
7798 <td width="25%"><a href="#decl_cvStartReadSeq">StartReadSeq</a></td>
7799 </tr>
7800 <tr>
7801 <td width="25%"><a href="#decl_cvSeqPop">SeqPop</a></td>
7802 <td width="25%"><a href="#decl_cvSetImageCOI">SetImageCOI</a></td>
7803 <td width="25%"><a href="#decl_cvStartWriteSeq">StartWriteSeq</a></td>
7804 </tr>
7805 <tr>
7806 <td width="25%"><a href="#decl_cvSeqPopFront">SeqPopFront</a></td>
7807 <td width="25%"><a href="#decl_cvSetImageROI">SetImageROI</a></td>
7808 <td width="25%"><a href="#decl_cvStartWriteStruct">StartWriteStruct</a></td>
7809 </tr>
7810 <tr>
7811 <td width="25%"><a href="#decl_cvSeqPopMulti">SeqPopMulti</a></td>
7812 <td width="25%"><a href="#decl_cvSetMemoryManager">SetMemoryManager</a></td>
7813 <td width="25%"><a href="#decl_cvStdErrReport">StdErrReport</a></td>
7814 </tr>
7815 <tr>
7816 <td width="25%"><a href="#decl_cvSeqPush">SeqPush</a></td>
7817 <td width="25%"><a href="#decl_cvSetNew">SetNew</a></td>
7818 <td width="25%"><a href="#decl_cvSub">Sub</a></td>
7819 </tr>
7820 <tr>
7821 <td width="25%"><a href="#decl_cvSeqPushFront">SeqPushFront</a></td>
7822 <td width="25%"><a href="#decl_cvSetNumThreads">SetNumThreads</a></td>
7823 <td width="25%"><a href="#decl_cvSubRS">SubRS</a></td>
7824 </tr>
7825 <tr>
7826 <td width="25%"><a href="#decl_cvSeqPushMulti">SeqPushMulti</a></td>
7827 <td width="25%"><a href="#decl_cvSetReal*D">SetReal*D</a></td>
7828 <td width="25%"><a href="#decl_cvSubS">SubS</a></td>
7829 </tr>
7830 <tr>
7831 <td width="25%"><a href="#decl_cvSeqRemove">SeqRemove</a></td>
7832 <td width="25%"><a href="#decl_cvSetRemove">SetRemove</a></td>
7833 <td width="25%"><a href="#decl_cvSum">Sum</a></td>
7834 </tr>
7835 <tr>
7836 <td width="25%"><a href="#decl_cvSeqRemoveSlice">SeqRemoveSlice</a></td>
7837 <td width="25%"><a href="#decl_cvSetRemoveByPtr">SetRemoveByPtr</a></td>
7838 <td width="25%"><a href="#decl_cvmSet">Set</a></td>
7839 </tr>
7840 <tr>
7841 <td width="25%"><a href="#decl_cvSeqSearch">SeqSearch</a></td>
7842 <td width="25%"><a href="#decl_cvSetSeqBlockSize">SetSeqBlockSize</a></td>
7843 <td width="25%"><a href="#decl_cvSplit">Split</a></td>
7844 <td width="25%%"></td>
7845 </tr>
7846 </table>
7847 <hr><h3>T</h3>
7848 <table width="100%">
7849 <tr>
7850 <td width="25%"><a href="#decl_cvTrace">Trace</a></td>
7851 <td width="25%"><a href="#decl_cvTranspose">Transpose</a></td>
7852 <td width="25%"><a href="#decl_cvTypeOf">TypeOf</a></td>
7853 </tr>
7854 <tr>
7855 <td width="25%"><a href="#decl_cvTransform">Transform</a></td>
7856 <td width="25%"><a href="#decl_cvTreeToNodeSeq">TreeToNodeSeq</a></td>
7857 <td width="25%%"></td>
7858 </tr>
7859 </table>
7860 <hr><h3>U</h3>
7861 <table width="100%">
7862 <tr>
7863 <td width="25%"><a href="#decl_cvUnregisterType">UnregisterType</a></td>
7864 <td width="25%"><a href="#decl_cvUseOptimized">UseOptimized</a></td>
7865 <td width="25%%"></td>
7866 </tr>
7867 </table>
7868 <hr><h3>W</h3>
7869 <table width="100%">
7870 <tr>
7871 <td width="25%"><a href="#decl_cvWrite">Write</a></td>
7872 <td width="25%"><a href="#decl_cvWriteInt">WriteInt</a></td>
7873 <td width="25%"><a href="#decl_cvWriteString">WriteString</a></td>
7874 </tr>
7875 <tr>
7876 <td width="25%"><a href="#decl_cvWriteComment">WriteComment</a></td>
7877 <td width="25%"><a href="#decl_cvWriteRawData">WriteRawData</a></td>
7878 <td width="25%%"></td>
7879 </tr>
7880 <tr>
7881 <td width="25%"><a href="#decl_cvWriteFileNode">WriteFileNode</a></td>
7882 <td width="25%"><a href="#decl_cvWriteReal">WriteReal</a></td>
7883 <td width="25%%"></td>
7884 </tr>
7885 </table>
7886 <hr><h3>X</h3>
7887 <table width="100%">
7888 <tr>
7889 <td width="25%"><a href="#decl_cvXor">Xor</a></td>
7890 <td width="25%"><a href="#decl_cvXorS">XorS</a></td>
7891 <td width="25%%"></td>
7892 </tr>
7893 </table>
7894
7895 <hr><h1><a name="cxcore_sample_index">List of Examples</a></h1>
7896
7897 </body>
7898 </html>