opencv/include/opencv/cxcore.h

   1 /*M///////////////////////////////////////////////////////////////////////////////////////
   2 //
   3 //  IMPORTANT: READ BEFORE DOWNLOADING, COPYING, INSTALLING OR USING.
   4 //
   5 //  By downloading, copying, installing or using the software you agree to this license.
   6 //  If you do not agree to this license, do not download, install,
   7 //  copy or use the software.
   8 //
   9 //
  10 //                        Intel License Agreement
  11 //                For Open Source Computer Vision Library
  12 //
  13 // Copyright (C) 2000, Intel Corporation, all rights reserved.
  14 // Third party copyrights are property of their respective owners.
  15 //
  16 // Redistribution and use in source and binary forms, with or without modification,
  17 // are permitted provided that the following conditions are met:
  18 //
  19 //   * Redistribution's of source code must retain the above copyright notice,
  20 //     this list of conditions and the following disclaimer.
  21 //
  22 //   * Redistribution's in binary form must reproduce the above copyright notice,
  23 //     this list of conditions and the following disclaimer in the documentation
  24 //     and/or other materials provided with the distribution.
  25 //
  26 //   * The name of Intel Corporation may not be used to endorse or promote products
  27 //     derived from this software without specific prior written permission.
  28 //
  29 // This software is provided by the copyright holders and contributors "as is" and
  30 // any express or implied warranties, including, but not limited to, the implied
  31 // warranties of merchantability and fitness for a particular purpose are disclaimed.
  32 // In no event shall the Intel Corporation or contributors be liable for any direct,
  33 // indirect, incidental, special, exemplary, or consequential damages
  34 // (including, but not limited to, procurement of substitute goods or services;
  35 // loss of use, data, or profits; or business interruption) however caused
  36 // and on any theory of liability, whether in contract, strict liability,
  37 // or tort (including negligence or otherwise) arising in any way out of
  38 // the use of this software, even if advised of the possibility of such damage.
  39 //
  40 //M*/
  41
  42
  43 #ifndef _CXCORE_H_
  44 #define _CXCORE_H_
  45
  46 #ifdef __IPL_H__
  47 #define HAVE_IPL
  48 #endif
  49
  50 #ifndef SKIP_INCLUDES
  51   #if defined HAVE_IPL && !defined __IPL_H__
  52     #ifndef _INC_WINDOWS
  53         #define CV_PRETEND_WINDOWS
  54         #define _INC_WINDOWS
  55         typedef struct tagBITMAPINFOHEADER BITMAPINFOHEADER;
  56         typedef int BOOL;
  57     #endif
  58     #if defined WIN32 || defined WIN64
  59       #include "ipl.h"
  60     #else
  61       #include "ipl/ipl.h"
  62     #endif
  63     #ifdef CV_PRETEND_WINDOWS
  64         #undef _INC_WINDOWS
  65     #endif
  66   #endif
  67 #endif // SKIP_INCLUDES
  68
  69 #include "cxtypes.h"
  70 #include "cxerror.h"
  71
  72 #ifdef __cplusplus
  73 extern "C" {
  74 #endif
  75
  76 /****************************************************************************************\
  77 *          Array allocation, deallocation, initialization and access to elements         *
  78 \****************************************************************************************/
  79
  80 /* <malloc> wrapper.
  81    If there is no enough memory, the function
  82    (as well as other OpenCV functions that call cvAlloc)
  83    raises an error. */
  84 CVAPI(void*)  cvAlloc( size_t size );
  85
  86 /* <free> wrapper.
  87    Here and further all the memory releasing functions
  88    (that all call cvFree) take double pointer in order to
  89    to clear pointer to the data after releasing it.
  90    Passing pointer to NULL pointer is Ok: nothing happens in this case
  91 */
  92 CVAPI(void)   cvFree_( void* ptr );
  93 #define cvFree(ptr) (cvFree_(*(ptr)), *(ptr)=0)
  94
  95 /* Allocates and initializes IplImage header */
  96 CVAPI(IplImage*)  cvCreateImageHeader( CvSize size, int depth, int channels );
  97
  98 /* Inializes IplImage header */
  99 CVAPI(IplImage*) cvInitImageHeader( IplImage* image, CvSize size, int depth,
 100                                    int channels, int origin CV_DEFAULT(0),
 101                                    int align CV_DEFAULT(4));
 102
 103 /* Creates IPL image (header and data) */
 104 CVAPI(IplImage*)  cvCreateImage( CvSize size, int depth, int channels );
 105
 106 /* Releases (i.e. deallocates) IPL image header */
 107 CVAPI(void)  cvReleaseImageHeader( IplImage** image );
 108
 109 /* Releases IPL image header and data */
 110 CVAPI(void)  cvReleaseImage( IplImage** image );
 111
 112 /* Creates a copy of IPL image (widthStep may differ) */
 113 CVAPI(IplImage*) cvCloneImage( const IplImage* image );
 114
 115 /* Sets a Channel Of Interest (only a few functions support COI) -
 116    use cvCopy to extract the selected channel and/or put it back */
 117 CVAPI(void)  cvSetImageCOI( IplImage* image, int coi );
 118
 119 /* Retrieves image Channel Of Interest */
 120 CVAPI(int)  cvGetImageCOI( const IplImage* image );
 121
 122 /* Sets image ROI (region of interest) (COI is not changed) */
 123 CVAPI(void)  cvSetImageROI( IplImage* image, CvRect rect );
 124
 125 /* Resets image ROI and COI */
 126 CVAPI(void)  cvResetImageROI( IplImage* image );
 127
 128 /* Retrieves image ROI */
 129 CVAPI(CvRect) cvGetImageROI( const IplImage* image );
 130
 131 /* Allocates and initalizes CvMat header */
 132 CVAPI(CvMat*)  cvCreateMatHeader( int rows, int cols, int type );
 133
 134 #define CV_AUTOSTEP  0x7fffffff
 135
 136 /* Initializes CvMat header */
 137 CVAPI(CvMat*) cvInitMatHeader( CvMat* mat, int rows, int cols,
 138                               int type, void* data CV_DEFAULT(NULL),
 139                               int step CV_DEFAULT(CV_AUTOSTEP) );
 140
 141 /* Allocates and initializes CvMat header and allocates data */
 142 CVAPI(CvMat*)  cvCreateMat( int rows, int cols, int type );
 143
 144 /* Releases CvMat header and deallocates matrix data
 145    (reference counting is used for data) */
 146 CVAPI(void)  cvReleaseMat( CvMat** mat );
 147
 148 /* Decrements CvMat data reference counter and deallocates the data if
 149    it reaches 0 */
 150 CV_INLINE  void  cvDecRefData( CvArr* arr )
 151 {
 152     if( CV_IS_MAT( arr ))
 153     {
 154         CvMat* mat = (CvMat*)arr;
 155         mat->data.ptr = NULL;
 156         if( mat->refcount != NULL && --*mat->refcount == 0 )
 157             cvFree( &mat->refcount );
 158         mat->refcount = NULL;
 159     }
 160     else if( CV_IS_MATND( arr ))
 161     {
 162         CvMatND* mat = (CvMatND*)arr;
 163         mat->data.ptr = NULL;
 164         if( mat->refcount != NULL && --*mat->refcount == 0 )
 165             cvFree( &mat->refcount );
 166         mat->refcount = NULL;
 167     }
 168 }
 169
 170 /* Increments CvMat data reference counter */
 171 CV_INLINE  int  cvIncRefData( CvArr* arr )
 172 {
 173     int refcount = 0;
 174     if( CV_IS_MAT( arr ))
 175     {
 176         CvMat* mat = (CvMat*)arr;
 177         if( mat->refcount != NULL )
 178             refcount = ++*mat->refcount;
 179     }
 180     else if( CV_IS_MATND( arr ))
 181     {
 182         CvMatND* mat = (CvMatND*)arr;
 183         if( mat->refcount != NULL )
 184             refcount = ++*mat->refcount;
 185     }
 186     return refcount;
 187 }
 188
 189
 190 /* Creates an exact copy of the input matrix (except, may be, step value) */
 191 CVAPI(CvMat*) cvCloneMat( const CvMat* mat );
 192
 193
 194 /* Makes a new matrix from <rect> subrectangle of input array.
 195    No data is copied */
 196 CVAPI(CvMat*) cvGetSubRect( const CvArr* arr, CvMat* submat, CvRect rect );
 197 #define cvGetSubArr cvGetSubRect
 198
 199 /* Selects row span of the input array: arr(start_row:delta_row:end_row,:)
 200     (end_row is not included into the span). */
 201 CVAPI(CvMat*) cvGetRows( const CvArr* arr, CvMat* submat,
 202                         int start_row, int end_row,
 203                         int delta_row CV_DEFAULT(1));
 204
 205 CV_INLINE  CvMat*  cvGetRow( const CvArr* arr, CvMat* submat, int row )
 206 {
 207     return cvGetRows( arr, submat, row, row + 1, 1 );
 208 }
 209
 210
 211 /* Selects column span of the input array: arr(:,start_col:end_col)
 212    (end_col is not included into the span) */
 213 CVAPI(CvMat*) cvGetCols( const CvArr* arr, CvMat* submat,
 214                         int start_col, int end_col );
 215
 216 CV_INLINE  CvMat*  cvGetCol( const CvArr* arr, CvMat* submat, int col )
 217 {
 218     return cvGetCols( arr, submat, col, col + 1 );
 219 }
 220
 221 /* Select a diagonal of the input array.
 222    (diag = 0 means the main diagonal, >0 means a diagonal above the main one,
 223    <0 - below the main one).
 224    The diagonal will be represented as a column (nx1 matrix). */
 225 CVAPI(CvMat*) cvGetDiag( const CvArr* arr, CvMat* submat,
 226                             int diag CV_DEFAULT(0));
 227
 228 /* low-level scalar <-> raw data conversion functions */
 229 CVAPI(void) cvScalarToRawData( const CvScalar* scalar, void* data, int type,
 230                               int extend_to_12 CV_DEFAULT(0) );
 231
 232 CVAPI(void) cvRawDataToScalar( const void* data, int type, CvScalar* scalar );
 233
 234 /* Allocates and initializes CvMatND header */
 235 CVAPI(CvMatND*)  cvCreateMatNDHeader( int dims, const int* sizes, int type );
 236
 237 /* Allocates and initializes CvMatND header and allocates data */
 238 CVAPI(CvMatND*)  cvCreateMatND( int dims, const int* sizes, int type );
 239
 240 /* Initializes preallocated CvMatND header */
 241 CVAPI(CvMatND*)  cvInitMatNDHeader( CvMatND* mat, int dims, const int* sizes,
 242                                     int type, void* data CV_DEFAULT(NULL) );
 243
 244 /* Releases CvMatND */
 245 CV_INLINE  void  cvReleaseMatND( CvMatND** mat )
 246 {
 247     cvReleaseMat( (CvMat**)mat );
 248 }
 249
 250 /* Creates a copy of CvMatND (except, may be, steps) */
 251 CVAPI(CvMatND*) cvCloneMatND( const CvMatND* mat );
 252
 253 /* Allocates and initializes CvSparseMat header and allocates data */
 254 CVAPI(CvSparseMat*)  cvCreateSparseMat( int dims, const int* sizes, int type );
 255
 256 /* Releases CvSparseMat */
 257 CVAPI(void)  cvReleaseSparseMat( CvSparseMat** mat );
 258
 259 /* Creates a copy of CvSparseMat (except, may be, zero items) */
 260 CVAPI(CvSparseMat*) cvCloneSparseMat( const CvSparseMat* mat );
 261
 262 /* Initializes sparse array iterator
 263    (returns the first node or NULL if the array is empty) */
 264 CVAPI(CvSparseNode*) cvInitSparseMatIterator( const CvSparseMat* mat,
 265                                               CvSparseMatIterator* mat_iterator );
 266
 267 // returns next sparse array node (or NULL if there is no more nodes)
 268 CV_INLINE CvSparseNode* cvGetNextSparseNode( CvSparseMatIterator* mat_iterator )
 269 {
 270     if( mat_iterator->node->next )
 271         return mat_iterator->node = mat_iterator->node->next;
 272     else
 273     {
 274         int idx;
 275         for( idx = ++mat_iterator->curidx; idx < mat_iterator->mat->hashsize; idx++ )
 276         {
 277             CvSparseNode* node = (CvSparseNode*)mat_iterator->mat->hashtable[idx];
 278             if( node )
 279             {
 280                 mat_iterator->curidx = idx;
 281                 return mat_iterator->node = node;
 282             }
 283         }
 284         return NULL;
 285     }
 286 }
 287
 288 /**************** matrix iterator: used for n-ary operations on dense arrays *********/
 289
 290 #define CV_MAX_ARR 10
 291
 292 typedef struct CvNArrayIterator
 293 {
 294     int count; /* number of arrays */
 295     int dims; /* number of dimensions to iterate */
 296     CvSize size; /* maximal common linear size: { width = size, height = 1 } */
 297     uchar* ptr[CV_MAX_ARR]; /* pointers to the array slices */
 298     int stack[CV_MAX_DIM]; /* for internal use */
 299     CvMatND* hdr[CV_MAX_ARR]; /* pointers to the headers of the
 300                                  matrices that are processed */
 301 }
 302 CvNArrayIterator;
 303
 304 #define CV_NO_DEPTH_CHECK     1
 305 #define CV_NO_CN_CHECK        2
 306 #define CV_NO_SIZE_CHECK      4
 307
 308 /* initializes iterator that traverses through several arrays simulteneously
 309    (the function together with cvNextArraySlice is used for
 310     N-ari element-wise operations) */
 311 CVAPI(int) cvInitNArrayIterator( int count, CvArr** arrs,
 312                                  const CvArr* mask, CvMatND* stubs,
 313                                  CvNArrayIterator* array_iterator,
 314                                  int flags CV_DEFAULT(0) );
 315
 316 /* returns zero value if iteration is finished, non-zero (slice length) otherwise */
 317 CVAPI(int) cvNextNArraySlice( CvNArrayIterator* array_iterator );
 318
 319
 320 /* Returns type of array elements:
 321    CV_8UC1 ... CV_64FC4 ... */
 322 CVAPI(int) cvGetElemType( const CvArr* arr );
 323
 324 /* Retrieves number of an array dimensions and
 325    optionally sizes of the dimensions */
 326 CVAPI(int) cvGetDims( const CvArr* arr, int* sizes CV_DEFAULT(NULL) );
 327
 328
 329 /* Retrieves size of a particular array dimension.
 330    For 2d arrays cvGetDimSize(arr,0) returns number of rows (image height)
 331    and cvGetDimSize(arr,1) returns number of columns (image width) */
 332 CVAPI(int) cvGetDimSize( const CvArr* arr, int index );
 333
 334
 335 /* ptr = &arr(idx0,idx1,...). All indexes are zero-based,
 336    the major dimensions go first (e.g. (y,x) for 2D, (z,y,x) for 3D */
 337 CVAPI(uchar*) cvPtr1D( const CvArr* arr, int idx0, int* type CV_DEFAULT(NULL));
 338 CVAPI(uchar*) cvPtr2D( const CvArr* arr, int idx0, int idx1, int* type CV_DEFAULT(NULL) );
 339 CVAPI(uchar*) cvPtr3D( const CvArr* arr, int idx0, int idx1, int idx2,
 340                       int* type CV_DEFAULT(NULL));
 341
 342 /* For CvMat or IplImage number of indices should be 2
 343    (row index (y) goes first, column index (x) goes next).
 344    For CvMatND or CvSparseMat number of infices should match number of <dims> and
 345    indices order should match the array dimension order. */
 346 CVAPI(uchar*) cvPtrND( const CvArr* arr, int* idx, int* type CV_DEFAULT(NULL),
 347                       int create_node CV_DEFAULT(1),
 348                       unsigned* precalc_hashval CV_DEFAULT(NULL));
 349
 350 /* value = arr(idx0,idx1,...) */
 351 CVAPI(CvScalar) cvGet1D( const CvArr* arr, int idx0 );
 352 CVAPI(CvScalar) cvGet2D( const CvArr* arr, int idx0, int idx1 );
 353 CVAPI(CvScalar) cvGet3D( const CvArr* arr, int idx0, int idx1, int idx2 );
 354 CVAPI(CvScalar) cvGetND( const CvArr* arr, int* idx );
 355
 356 /* for 1-channel arrays */
 357 CVAPI(double) cvGetReal1D( const CvArr* arr, int idx0 );
 358 CVAPI(double) cvGetReal2D( const CvArr* arr, int idx0, int idx1 );
 359 CVAPI(double) cvGetReal3D( const CvArr* arr, int idx0, int idx1, int idx2 );
 360 CVAPI(double) cvGetRealND( const CvArr* arr, int* idx );
 361
 362 /* arr(idx0,idx1,...) = value */
 363 CVAPI(void) cvSet1D( CvArr* arr, int idx0, CvScalar value );
 364 CVAPI(void) cvSet2D( CvArr* arr, int idx0, int idx1, CvScalar value );
 365 CVAPI(void) cvSet3D( CvArr* arr, int idx0, int idx1, int idx2, CvScalar value );
 366 CVAPI(void) cvSetND( CvArr* arr, int* idx, CvScalar value );
 367
 368 /* for 1-channel arrays */
 369 CVAPI(void) cvSetReal1D( CvArr* arr, int idx0, double value );
 370 CVAPI(void) cvSetReal2D( CvArr* arr, int idx0, int idx1, double value );
 371 CVAPI(void) cvSetReal3D( CvArr* arr, int idx0,
 372                         int idx1, int idx2, double value );
 373 CVAPI(void) cvSetRealND( CvArr* arr, int* idx, double value );
 374
 375 /* clears element of ND dense array,
 376    in case of sparse arrays it deletes the specified node */
 377 CVAPI(void) cvClearND( CvArr* arr, int* idx );
 378
 379 /* Converts CvArr (IplImage or CvMat,...) to CvMat.
 380    If the last parameter is non-zero, function can
 381    convert multi(>2)-dimensional array to CvMat as long as
 382    the last array's dimension is continous. The resultant
 383    matrix will be have appropriate (a huge) number of rows */
 384 CVAPI(CvMat*) cvGetMat( const CvArr* arr, CvMat* header,
 385                        int* coi CV_DEFAULT(NULL),
 386                        int allowND CV_DEFAULT(0));
 387
 388 /* Converts CvArr (IplImage or CvMat) to IplImage */
 389 CVAPI(IplImage*) cvGetImage( const CvArr* arr, IplImage* image_header );
 390
 391
 392 /* Changes a shape of multi-dimensional array.
 393    new_cn == 0 means that number of channels remains unchanged.
 394    new_dims == 0 means that number and sizes of dimensions remain the same
 395    (unless they need to be changed to set the new number of channels)
 396    if new_dims == 1, there is no need to specify new dimension sizes
 397    The resultant configuration should be achievable w/o data copying.
 398    If the resultant array is sparse, CvSparseMat header should be passed
 399    to the function else if the result is 1 or 2 dimensional,
 400    CvMat header should be passed to the function
 401    else CvMatND header should be passed */
 402 CVAPI(CvArr*) cvReshapeMatND( const CvArr* arr,
 403                              int sizeof_header, CvArr* header,
 404                              int new_cn, int new_dims, int* new_sizes );
 405
 406 #define cvReshapeND( arr, header, new_cn, new_dims, new_sizes )   \
 407       cvReshapeMatND( (arr), sizeof(*(header)), (header),         \
 408                       (new_cn), (new_dims), (new_sizes))
 409
 410 CVAPI(CvMat*) cvReshape( const CvArr* arr, CvMat* header,
 411                         int new_cn, int new_rows CV_DEFAULT(0) );
 412
 413 /* Repeats source 2d array several times in both horizontal and
 414    vertical direction to fill destination array */
 415 CVAPI(void) cvRepeat( const CvArr* src, CvArr* dst );
 416
 417 /* Allocates array data */
 418 CVAPI(void)  cvCreateData( CvArr* arr );
 419
 420 /* Releases array data */
 421 CVAPI(void)  cvReleaseData( CvArr* arr );
 422
 423 /* Attaches user data to the array header. The step is reffered to
 424    the pre-last dimension. That is, all the planes of the array
 425    must be joint (w/o gaps) */
 426 CVAPI(void)  cvSetData( CvArr* arr, void* data, int step );
 427
 428 /* Retrieves raw data of CvMat, IplImage or CvMatND.
 429    In the latter case the function raises an error if
 430    the array can not be represented as a matrix */
 431 CVAPI(void) cvGetRawData( const CvArr* arr, uchar** data,
 432                          int* step CV_DEFAULT(NULL),
 433                          CvSize* roi_size CV_DEFAULT(NULL));
 434
 435 /* Returns width and height of array in elements */
 436 CVAPI(CvSize) cvGetSize( const CvArr* arr );
 437
 438 /* Copies source array to destination array */
 439 CVAPI(void)  cvCopy( const CvArr* src, CvArr* dst,
 440                      const CvArr* mask CV_DEFAULT(NULL) );
 441
 442 /* Sets all or "masked" elements of input array
 443    to the same value*/
 444 CVAPI(void)  cvSet( CvArr* arr, CvScalar value,
 445                     const CvArr* mask CV_DEFAULT(NULL) );
 446
 447 /* Clears all the array elements (sets them to 0) */
 448 CVAPI(void)  cvSetZero( CvArr* arr );
 449 #define cvZero  cvSetZero
 450
 451
 452 /* Splits a multi-channel array into the set of single-channel arrays or
 453    extracts particular [color] plane */
 454 CVAPI(void)  cvSplit( const CvArr* src, CvArr* dst0, CvArr* dst1,
 455                       CvArr* dst2, CvArr* dst3 );
 456
 457 /* Merges a set of single-channel arrays into the single multi-channel array
 458    or inserts one particular [color] plane to the array */
 459 CVAPI(void)  cvMerge( const CvArr* src0, const CvArr* src1,
 460                       const CvArr* src2, const CvArr* src3,
 461                       CvArr* dst );
 462
 463 /* Copies several channels from input arrays to
 464    certain channels of output arrays */
 465 CVAPI(void)  cvMixChannels( const CvArr** src, int src_count,
 466                             CvArr** dst, int dst_count,
 467                             const int* from_to, int pair_count );
 468
 469 /* Performs linear transformation on every source array element:
 470    dst(x,y,c) = scale*src(x,y,c)+shift.
 471    Arbitrary combination of input and output array depths are allowed
 472    (number of channels must be the same), thus the function can be used
 473    for type conversion */
 474 CVAPI(void)  cvConvertScale( const CvArr* src, CvArr* dst,
 475                              double scale CV_DEFAULT(1),
 476                              double shift CV_DEFAULT(0) );
 477 #define cvCvtScale cvConvertScale
 478 #define cvScale  cvConvertScale
 479 #define cvConvert( src, dst )  cvConvertScale( (src), (dst), 1, 0 )
 480
 481
 482 /* Performs linear transformation on every source array element,
 483    stores absolute value of the result:
 484    dst(x,y,c) = abs(scale*src(x,y,c)+shift).
 485    destination array must have 8u type.
 486    In other cases one may use cvConvertScale + cvAbsDiffS */
 487 CVAPI(void)  cvConvertScaleAbs( const CvArr* src, CvArr* dst,
 488                                 double scale CV_DEFAULT(1),
 489                                 double shift CV_DEFAULT(0) );
 490 #define cvCvtScaleAbs  cvConvertScaleAbs
 491
 492
 493 /* checks termination criteria validity and
 494    sets eps to default_eps (if it is not set),
 495    max_iter to default_max_iters (if it is not set)
 496 */
 497 CVAPI(CvTermCriteria) cvCheckTermCriteria( CvTermCriteria criteria,
 498                                            double default_eps,
 499                                            int default_max_iters );
 500
 501 /****************************************************************************************\
 502 *                   Arithmetic, logic and comparison operations                          *
 503 \****************************************************************************************/
 504
 505 /* dst(mask) = src1(mask) + src2(mask) */
 506 CVAPI(void)  cvAdd( const CvArr* src1, const CvArr* src2, CvArr* dst,
 507                     const CvArr* mask CV_DEFAULT(NULL));
 508
 509 /* dst(mask) = src(mask) + value */
 510 CVAPI(void)  cvAddS( const CvArr* src, CvScalar value, CvArr* dst,
 511                      const CvArr* mask CV_DEFAULT(NULL));
 512
 513 /* dst(mask) = src1(mask) - src2(mask) */
 514 CVAPI(void)  cvSub( const CvArr* src1, const CvArr* src2, CvArr* dst,
 515                     const CvArr* mask CV_DEFAULT(NULL));
 516
 517 /* dst(mask) = src(mask) - value = src(mask) + (-value) */
 518 CV_INLINE  void  cvSubS( const CvArr* src, CvScalar value, CvArr* dst,
 519                          const CvArr* mask CV_DEFAULT(NULL))
 520 {
 521     cvAddS( src, cvScalar( -value.val[0], -value.val[1], -value.val[2], -value.val[3]),
 522             dst, mask );
 523 }
 524
 525 /* dst(mask) = value - src(mask) */
 526 CVAPI(void)  cvSubRS( const CvArr* src, CvScalar value, CvArr* dst,
 527                       const CvArr* mask CV_DEFAULT(NULL));
 528
 529 /* dst(idx) = src1(idx) * src2(idx) * scale
 530    (scaled element-wise multiplication of 2 arrays) */
 531 CVAPI(void)  cvMul( const CvArr* src1, const CvArr* src2,
 532                     CvArr* dst, double scale CV_DEFAULT(1) );
 533
 534 /* element-wise division/inversion with scaling:
 535     dst(idx) = src1(idx) * scale / src2(idx)
 536     or dst(idx) = scale / src2(idx) if src1 == 0 */
 537 CVAPI(void)  cvDiv( const CvArr* src1, const CvArr* src2,
 538                     CvArr* dst, double scale CV_DEFAULT(1));
 539
 540 /* dst = src1 * scale + src2 */
 541 CVAPI(void)  cvScaleAdd( const CvArr* src1, CvScalar scale,
 542                          const CvArr* src2, CvArr* dst );
 543 #define cvAXPY( A, real_scalar, B, C ) cvScaleAdd(A, cvRealScalar(real_scalar), B, C)
 544
 545 /* dst = src1 * alpha + src2 * beta + gamma */
 546 CVAPI(void)  cvAddWeighted( const CvArr* src1, double alpha,
 547                             const CvArr* src2, double beta,
 548                             double gamma, CvArr* dst );
 549
 550 /* result = sum_i(src1(i) * src2(i)) (results for all channels are accumulated together) */
 551 CVAPI(double)  cvDotProduct( const CvArr* src1, const CvArr* src2 );
 552
 553 /* dst(idx) = src1(idx) & src2(idx) */
 554 CVAPI(void) cvAnd( const CvArr* src1, const CvArr* src2,
 555                   CvArr* dst, const CvArr* mask CV_DEFAULT(NULL));
 556
 557 /* dst(idx) = src(idx) & value */
 558 CVAPI(void) cvAndS( const CvArr* src, CvScalar value,
 559                    CvArr* dst, const CvArr* mask CV_DEFAULT(NULL));
 560
 561 /* dst(idx) = src1(idx) | src2(idx) */
 562 CVAPI(void) cvOr( const CvArr* src1, const CvArr* src2,
 563                  CvArr* dst, const CvArr* mask CV_DEFAULT(NULL));
 564
 565 /* dst(idx) = src(idx) | value */
 566 CVAPI(void) cvOrS( const CvArr* src, CvScalar value,
 567                   CvArr* dst, const CvArr* mask CV_DEFAULT(NULL));
 568
 569 /* dst(idx) = src1(idx) ^ src2(idx) */
 570 CVAPI(void) cvXor( const CvArr* src1, const CvArr* src2,
 571                   CvArr* dst, const CvArr* mask CV_DEFAULT(NULL));
 572
 573 /* dst(idx) = src(idx) ^ value */
 574 CVAPI(void) cvXorS( const CvArr* src, CvScalar value,
 575                    CvArr* dst, const CvArr* mask CV_DEFAULT(NULL));
 576
 577 /* dst(idx) = ~src(idx) */
 578 CVAPI(void) cvNot( const CvArr* src, CvArr* dst );
 579
 580 /* dst(idx) = lower(idx) <= src(idx) < upper(idx) */
 581 CVAPI(void) cvInRange( const CvArr* src, const CvArr* lower,
 582                       const CvArr* upper, CvArr* dst );
 583
 584 /* dst(idx) = lower <= src(idx) < upper */
 585 CVAPI(void) cvInRangeS( const CvArr* src, CvScalar lower,
 586                        CvScalar upper, CvArr* dst );
 587
 588 #define CV_CMP_EQ   0
 589 #define CV_CMP_GT   1
 590 #define CV_CMP_GE   2
 591 #define CV_CMP_LT   3
 592 #define CV_CMP_LE   4
 593 #define CV_CMP_NE   5
 594
 595 /* The comparison operation support single-channel arrays only.
 596    Destination image should be 8uC1 or 8sC1 */
 597
 598 /* dst(idx) = src1(idx) _cmp_op_ src2(idx) */
 599 CVAPI(void) cvCmp( const CvArr* src1, const CvArr* src2, CvArr* dst, int cmp_op );
 600
 601 /* dst(idx) = src1(idx) _cmp_op_ value */
 602 CVAPI(void) cvCmpS( const CvArr* src, double value, CvArr* dst, int cmp_op );
 603
 604 /* dst(idx) = min(src1(idx),src2(idx)) */
 605 CVAPI(void) cvMin( const CvArr* src1, const CvArr* src2, CvArr* dst );
 606
 607 /* dst(idx) = max(src1(idx),src2(idx)) */
 608 CVAPI(void) cvMax( const CvArr* src1, const CvArr* src2, CvArr* dst );
 609
 610 /* dst(idx) = min(src(idx),value) */
 611 CVAPI(void) cvMinS( const CvArr* src, double value, CvArr* dst );
 612
 613 /* dst(idx) = max(src(idx),value) */
 614 CVAPI(void) cvMaxS( const CvArr* src, double value, CvArr* dst );
 615
 616 /* dst(x,y,c) = abs(src1(x,y,c) - src2(x,y,c)) */
 617 CVAPI(void) cvAbsDiff( const CvArr* src1, const CvArr* src2, CvArr* dst );
 618
 619 /* dst(x,y,c) = abs(src(x,y,c) - value(c)) */
 620 CVAPI(void) cvAbsDiffS( const CvArr* src, CvArr* dst, CvScalar value );
 621 #define cvAbs( src, dst ) cvAbsDiffS( (src), (dst), cvScalarAll(0))
 622
 623 /****************************************************************************************\
 624 *                                Math operations                                         *
 625 \****************************************************************************************/
 626
 627 /* Does cartesian->polar coordinates conversion.
 628    Either of output components (magnitude or angle) is optional */
 629 CVAPI(void)  cvCartToPolar( const CvArr* x, const CvArr* y,
 630                             CvArr* magnitude, CvArr* angle CV_DEFAULT(NULL),
 631                             int angle_in_degrees CV_DEFAULT(0));
 632
 633 /* Does polar->cartesian coordinates conversion.
 634    Either of output components (magnitude or angle) is optional.
 635    If magnitude is missing it is assumed to be all 1's */
 636 CVAPI(void)  cvPolarToCart( const CvArr* magnitude, const CvArr* angle,
 637                             CvArr* x, CvArr* y,
 638                             int angle_in_degrees CV_DEFAULT(0));
 639
 640 /* Does powering: dst(idx) = src(idx)^power */
 641 CVAPI(void)  cvPow( const CvArr* src, CvArr* dst, double power );
 642
 643 /* Does exponention: dst(idx) = exp(src(idx)).
 644    Overflow is not handled yet. Underflow is handled.
 645    Maximal relative error is ~7e-6 for single-precision input */
 646 CVAPI(void)  cvExp( const CvArr* src, CvArr* dst );
 647
 648 /* Calculates natural logarithms: dst(idx) = log(abs(src(idx))).
 649    Logarithm of 0 gives large negative number(~-700)
 650    Maximal relative error is ~3e-7 for single-precision output
 651 */
 652 CVAPI(void)  cvLog( const CvArr* src, CvArr* dst );
 653
 654 /* Fast arctangent calculation */
 655 CVAPI(float) cvFastArctan( float y, float x );
 656
 657 /* Fast cubic root calculation */
 658 CVAPI(float)  cvCbrt( float value );
 659
 660 /* Checks array values for NaNs, Infs or simply for too large numbers
 661    (if CV_CHECK_RANGE is set). If CV_CHECK_QUIET is set,
 662    no runtime errors is raised (function returns zero value in case of "bad" values).
 663    Otherwise cvError is called */
 664 #define  CV_CHECK_RANGE    1
 665 #define  CV_CHECK_QUIET    2
 666 CVAPI(int)  cvCheckArr( const CvArr* arr, int flags CV_DEFAULT(0),
 667                         double min_val CV_DEFAULT(0), double max_val CV_DEFAULT(0));
 668 #define cvCheckArray cvCheckArr
 669
 670 #define CV_RAND_UNI      0
 671 #define CV_RAND_NORMAL   1
 672 CVAPI(void) cvRandArr( CvRNG* rng, CvArr* arr, int dist_type,
 673                       CvScalar param1, CvScalar param2 );
 674
 675 CVAPI(void) cvRandShuffle( CvArr* mat, CvRNG* rng,
 676                            double iter_factor CV_DEFAULT(1.));
 677
 678 /* Finds real roots of a cubic equation */
 679 CVAPI(int) cvSolveCubic( const CvMat* coeffs, CvMat* roots );
 680
 681 /****************************************************************************************\
 682 *                                Matrix operations                                       *
 683 \****************************************************************************************/
 684
 685 /* Calculates cross product of two 3d vectors */
 686 CVAPI(void)  cvCrossProduct( const CvArr* src1, const CvArr* src2, CvArr* dst );
 687
 688 /* Matrix transform: dst = A*B + C, C is optional */
 689 #define cvMatMulAdd( src1, src2, src3, dst ) cvGEMM( (src1), (src2), 1., (src3), 1., (dst), 0 )
 690 #define cvMatMul( src1, src2, dst )  cvMatMulAdd( (src1), (src2), NULL, (dst))
 691
 692 #define CV_GEMM_A_T 1
 693 #define CV_GEMM_B_T 2
 694 #define CV_GEMM_C_T 4
 695 /* Extended matrix transform:
 696    dst = alpha*op(A)*op(B) + beta*op(C), where op(X) is X or X^T */
 697 CVAPI(void)  cvGEMM( const CvArr* src1, const CvArr* src2, double alpha,
 698                      const CvArr* src3, double beta, CvArr* dst,
 699                      int tABC CV_DEFAULT(0));
 700 #define cvMatMulAddEx cvGEMM
 701
 702 /* Transforms each element of source array and stores
 703    resultant vectors in destination array */
 704 CVAPI(void)  cvTransform( const CvArr* src, CvArr* dst,
 705                           const CvMat* transmat,
 706                           const CvMat* shiftvec CV_DEFAULT(NULL));
 707 #define cvMatMulAddS cvTransform
 708
 709 /* Does perspective transform on every element of input array */
 710 CVAPI(void)  cvPerspectiveTransform( const CvArr* src, CvArr* dst,
 711                                      const CvMat* mat );
 712
 713 /* Calculates (A-delta)*(A-delta)^T (order=0) or (A-delta)^T*(A-delta) (order=1) */
 714 CVAPI(void) cvMulTransposed( const CvArr* src, CvArr* dst, int order,
 715                              const CvArr* delta CV_DEFAULT(NULL),
 716                              double scale CV_DEFAULT(1.) );
 717
 718 /* Tranposes matrix. Square matrices can be transposed in-place */
 719 CVAPI(void)  cvTranspose( const CvArr* src, CvArr* dst );
 720 #define cvT cvTranspose
 721
 722
 723 /* Mirror array data around horizontal (flip=0),
 724    vertical (flip=1) or both(flip=-1) axises:
 725    cvFlip(src) flips images vertically and sequences horizontally (inplace) */
 726 CVAPI(void)  cvFlip( const CvArr* src, CvArr* dst CV_DEFAULT(NULL),
 727                      int flip_mode CV_DEFAULT(0));
 728 #define cvMirror cvFlip
 729
 730
 731 #define CV_SVD_MODIFY_A   1
 732 #define CV_SVD_U_T        2
 733 #define CV_SVD_V_T        4
 734
 735 /* Performs Singular Value Decomposition of a matrix */
 736 CVAPI(void)   cvSVD( CvArr* A, CvArr* W, CvArr* U CV_DEFAULT(NULL),
 737                      CvArr* V CV_DEFAULT(NULL), int flags CV_DEFAULT(0));
 738
 739 /* Performs Singular Value Back Substitution (solves A*X = B):
 740    flags must be the same as in cvSVD */
 741 CVAPI(void)   cvSVBkSb( const CvArr* W, const CvArr* U,
 742                         const CvArr* V, const CvArr* B,
 743                         CvArr* X, int flags );
 744
 745 #define CV_LU  0
 746 #define CV_SVD 1
 747 #define CV_SVD_SYM 2
 748 /* Inverts matrix */
 749 CVAPI(double)  cvInvert( const CvArr* src, CvArr* dst,
 750                          int method CV_DEFAULT(CV_LU));
 751 #define cvInv cvInvert
 752
 753 /* Solves linear system (src1)*(dst) = (src2)
 754    (returns 0 if src1 is a singular and CV_LU method is used) */
 755 CVAPI(int)  cvSolve( const CvArr* src1, const CvArr* src2, CvArr* dst,
 756                      int method CV_DEFAULT(CV_LU));
 757
 758 /* Calculates determinant of input matrix */
 759 CVAPI(double) cvDet( const CvArr* mat );
 760
 761 /* Calculates trace of the matrix (sum of elements on the main diagonal) */
 762 CVAPI(CvScalar) cvTrace( const CvArr* mat );
 763
 764 /* Finds eigen values and vectors of a symmetric matrix */
 765 CVAPI(void)  cvEigenVV( CvArr* mat, CvArr* evects,
 766                         CvArr* evals, double eps CV_DEFAULT(0));
 767
 768 /* Makes an identity matrix (mat_ij = i == j) */
 769 CVAPI(void)  cvSetIdentity( CvArr* mat, CvScalar value CV_DEFAULT(cvRealScalar(1)) );
 770
 771 /* Calculates covariation matrix for a set of vectors */
 772 /* transpose([v1-avg, v2-avg,...]) * [v1-avg,v2-avg,...] */
 773 #define CV_COVAR_SCRAMBLED 0
 774
 775 /* [v1-avg, v2-avg,...] * transpose([v1-avg,v2-avg,...]) */
 776 #define CV_COVAR_NORMAL    1
 777
 778 /* do not calc average (i.e. mean vector) - use the input vector instead
 779    (useful for calculating covariance matrix by parts) */
 780 #define CV_COVAR_USE_AVG   2
 781
 782 /* scale the covariance matrix coefficients by number of the vectors */
 783 #define CV_COVAR_SCALE     4
 784
 785 /* all the input vectors are stored in a single matrix, as its rows */
 786 #define CV_COVAR_ROWS      8
 787
 788 /* all the input vectors are stored in a single matrix, as its columns */
 789 #define CV_COVAR_COLS     16
 790
 791 CVAPI(void)  cvCalcCovarMatrix( const CvArr** vects, int count,
 792                                 CvArr* cov_mat, CvArr* avg, int flags );
 793
 794 #define CV_PCA_DATA_AS_ROW 0
 795 #define CV_PCA_DATA_AS_COL 1
 796 #define CV_PCA_USE_AVG 2
 797 #define CV_PCA_RET_SDV 4
 798 #define CV_PCA_RET_EVAL 0
 799
 800 CVAPI(void)  cvCalcPCA( const CvArr* data, CvArr* mean,
 801                         CvArr* eigenvals, CvArr* eigenvects, int flags );
 802
 803 CVAPI(void)  cvProjectPCA( const CvArr* data, const CvArr* mean,
 804                            const CvArr* eigenvects, CvArr* result );
 805
 806 CVAPI(void)  cvBackProjectPCA( const CvArr* proj, const CvArr* mean,
 807                                const CvArr* eigenvects, CvArr* result );
 808
 809 /* Calculates Mahalanobis(weighted) distance */
 810 CVAPI(double)  cvMahalanobis( const CvArr* vec1, const CvArr* vec2, CvArr* mat );
 811 #define cvMahalonobis  cvMahalanobis
 812
 813 /****************************************************************************************\
 814 *                                    Array Statistics                                    *
 815 \****************************************************************************************/
 816
 817 /* Finds sum of array elements */
 818 CVAPI(CvScalar)  cvSum( const CvArr* arr );
 819
 820 /* Calculates number of non-zero pixels */
 821 CVAPI(int)  cvCountNonZero( const CvArr* arr );
 822
 823 /* Calculates mean value of array elements */
 824 CVAPI(CvScalar)  cvAvg( const CvArr* arr, const CvArr* mask CV_DEFAULT(NULL) );
 825
 826 /* Calculates mean and standard deviation of pixel values */
 827 CVAPI(void)  cvAvgSdv( const CvArr* arr, CvScalar* mean, CvScalar* std_dev,
 828                        const CvArr* mask CV_DEFAULT(NULL) );
 829
 830 /* Finds global minimum, maximum and their positions */
 831 CVAPI(void)  cvMinMaxLoc( const CvArr* arr, double* min_val, double* max_val,
 832                           CvPoint* min_loc CV_DEFAULT(NULL),
 833                           CvPoint* max_loc CV_DEFAULT(NULL),
 834                           const CvArr* mask CV_DEFAULT(NULL) );
 835
 836 /* types of array norm */
 837 #define CV_C            1
 838 #define CV_L1           2
 839 #define CV_L2           4
 840 #define CV_NORM_MASK    7
 841 #define CV_RELATIVE     8
 842 #define CV_DIFF         16
 843 #define CV_MINMAX       32
 844
 845 #define CV_DIFF_C       (CV_DIFF | CV_C)
 846 #define CV_DIFF_L1      (CV_DIFF | CV_L1)
 847 #define CV_DIFF_L2      (CV_DIFF | CV_L2)
 848 #define CV_RELATIVE_C   (CV_RELATIVE | CV_C)
 849 #define CV_RELATIVE_L1  (CV_RELATIVE | CV_L1)
 850 #define CV_RELATIVE_L2  (CV_RELATIVE | CV_L2)
 851
 852 /* Finds norm, difference norm or relative difference norm for an array (or two arrays) */
 853 CVAPI(double)  cvNorm( const CvArr* arr1, const CvArr* arr2 CV_DEFAULT(NULL),
 854                        int norm_type CV_DEFAULT(CV_L2),
 855                        const CvArr* mask CV_DEFAULT(NULL) );
 856
 857 CVAPI(void)  cvNormalize( const CvArr* src, CvArr* dst,
 858                           double a, double b CV_DEFAULT(0.),
 859                           int norm_type CV_DEFAULT(CV_L2),
 860                           const CvArr* mask CV_DEFAULT(NULL) );
 861
 862
 863 #define CV_REDUCE_SUM 0
 864 #define CV_REDUCE_AVG 1
 865 #define CV_REDUCE_MAX 2
 866 #define CV_REDUCE_MIN 3
 867
 868 CVAPI(void)  cvReduce( const CvArr* src, CvArr* dst, int dim CV_DEFAULT(-1),
 869                        int op CV_DEFAULT(CV_REDUCE_SUM) );
 870
 871 /****************************************************************************************\
 872 *                      Discrete Linear Transforms and Related Functions                  *
 873 \****************************************************************************************/
 874
 875 #define CV_DXT_FORWARD  0
 876 #define CV_DXT_INVERSE  1
 877 #define CV_DXT_SCALE    2 /* divide result by size of array */
 878 #define CV_DXT_INV_SCALE (CV_DXT_INVERSE + CV_DXT_SCALE)
 879 #define CV_DXT_INVERSE_SCALE CV_DXT_INV_SCALE
 880 #define CV_DXT_ROWS     4 /* transform each row individually */
 881 #define CV_DXT_MUL_CONJ 8 /* conjugate the second argument of cvMulSpectrums */
 882
 883 /* Discrete Fourier Transform:
 884     complex->complex,
 885     real->ccs (forward),
 886     ccs->real (inverse) */
 887 CVAPI(void)  cvDFT( const CvArr* src, CvArr* dst, int flags,
 888                     int nonzero_rows CV_DEFAULT(0) );
 889 #define cvFFT cvDFT
 890
 891 /* Multiply results of DFTs: DFT(X)*DFT(Y) or DFT(X)*conj(DFT(Y)) */
 892 CVAPI(void)  cvMulSpectrums( const CvArr* src1, const CvArr* src2,
 893                              CvArr* dst, int flags );
 894
 895 /* Finds optimal DFT vector size >= size0 */
 896 CVAPI(int)  cvGetOptimalDFTSize( int size0 );
 897
 898 /* Discrete Cosine Transform */
 899 CVAPI(void)  cvDCT( const CvArr* src, CvArr* dst, int flags );
 900
 901 /****************************************************************************************\
 902 *                              Dynamic data structures                                   *
 903 \****************************************************************************************/
 904
 905 /* Calculates length of sequence slice (with support of negative indices). */
 906 CVAPI(int) cvSliceLength( CvSlice slice, const CvSeq* seq );
 907
 908
 909 /* Creates new memory storage.
 910    block_size == 0 means that default,
 911    somewhat optimal size, is used (currently, it is 64K) */
 912 CVAPI(CvMemStorage*)  cvCreateMemStorage( int block_size CV_DEFAULT(0));
 913
 914
 915 /* Creates a memory storage that will borrow memory blocks from parent storage */
 916 CVAPI(CvMemStorage*)  cvCreateChildMemStorage( CvMemStorage* parent );
 917
 918
 919 /* Releases memory storage. All the children of a parent must be released before
 920    the parent. A child storage returns all the blocks to parent when it is released */
 921 CVAPI(void)  cvReleaseMemStorage( CvMemStorage** storage );
 922
 923
 924 /* Clears memory storage. This is the only way(!!!) (besides cvRestoreMemStoragePos)
 925    to reuse memory allocated for the storage - cvClearSeq,cvClearSet ...
 926    do not free any memory.
 927    A child storage returns all the blocks to the parent when it is cleared */
 928 CVAPI(void)  cvClearMemStorage( CvMemStorage* storage );
 929
 930 /* Remember a storage "free memory" position */
 931 CVAPI(void)  cvSaveMemStoragePos( const CvMemStorage* storage, CvMemStoragePos* pos );
 932
 933 /* Restore a storage "free memory" position */
 934 CVAPI(void)  cvRestoreMemStoragePos( CvMemStorage* storage, CvMemStoragePos* pos );
 935
 936 /* Allocates continuous buffer of the specified size in the storage */
 937 CVAPI(void*) cvMemStorageAlloc( CvMemStorage* storage, size_t size );
 938
 939 /* Allocates string in memory storage */
 940 CVAPI(CvString) cvMemStorageAllocString( CvMemStorage* storage, const char* ptr,
 941                                         int len CV_DEFAULT(-1) );
 942
 943 /* Creates new empty sequence that will reside in the specified storage */
 944 CVAPI(CvSeq*)  cvCreateSeq( int seq_flags, int header_size,
 945                             int elem_size, CvMemStorage* storage );
 946
 947 /* Changes default size (granularity) of sequence blocks.
 948    The default size is ~1Kbyte */
 949 CVAPI(void)  cvSetSeqBlockSize( CvSeq* seq, int delta_elems );
 950
 951
 952 /* Adds new element to the end of sequence. Returns pointer to the element */
 953 CVAPI(char*)  cvSeqPush( CvSeq* seq, void* element CV_DEFAULT(NULL));
 954
 955
 956 /* Adds new element to the beginning of sequence. Returns pointer to it */
 957 CVAPI(char*)  cvSeqPushFront( CvSeq* seq, void* element CV_DEFAULT(NULL));
 958
 959
 960 /* Removes the last element from sequence and optionally saves it */
 961 CVAPI(void)  cvSeqPop( CvSeq* seq, void* element CV_DEFAULT(NULL));
 962
 963
 964 /* Removes the first element from sequence and optioanally saves it */
 965 CVAPI(void)  cvSeqPopFront( CvSeq* seq, void* element CV_DEFAULT(NULL));
 966
 967
 968 #define CV_FRONT 1
 969 #define CV_BACK 0
 970 /* Adds several new elements to the end of sequence */
 971 CVAPI(void)  cvSeqPushMulti( CvSeq* seq, void* elements,
 972                              int count, int in_front CV_DEFAULT(0) );
 973
 974 /* Removes several elements from the end of sequence and optionally saves them */
 975 CVAPI(void)  cvSeqPopMulti( CvSeq* seq, void* elements,
 976                             int count, int in_front CV_DEFAULT(0) );
 977
 978 /* Inserts a new element in the middle of sequence.
 979    cvSeqInsert(seq,0,elem) == cvSeqPushFront(seq,elem) */
 980 CVAPI(char*)  cvSeqInsert( CvSeq* seq, int before_index,
 981                            void* element CV_DEFAULT(NULL));
 982
 983 /* Removes specified sequence element */
 984 CVAPI(void)  cvSeqRemove( CvSeq* seq, int index );
 985
 986
 987 /* Removes all the elements from the sequence. The freed memory
 988    can be reused later only by the same sequence unless cvClearMemStorage
 989    or cvRestoreMemStoragePos is called */
 990 CVAPI(void)  cvClearSeq( CvSeq* seq );
 991
 992
 993 /* Retrives pointer to specified sequence element.
 994    Negative indices are supported and mean counting from the end
 995    (e.g -1 means the last sequence element) */
 996 CVAPI(char*)  cvGetSeqElem( const CvSeq* seq, int index );
 997
 998 /* Calculates index of the specified sequence element.
 999    Returns -1 if element does not belong to the sequence */
1000 CVAPI(int)  cvSeqElemIdx( const CvSeq* seq, const void* element,
1001                          CvSeqBlock** block CV_DEFAULT(NULL) );
1002
1003 /* Initializes sequence writer. The new elements will be added to the end of sequence */
1004 CVAPI(void)  cvStartAppendToSeq( CvSeq* seq, CvSeqWriter* writer );
1005
1006
1007 /* Combination of cvCreateSeq and cvStartAppendToSeq */
1008 CVAPI(void)  cvStartWriteSeq( int seq_flags, int header_size,
1009                               int elem_size, CvMemStorage* storage,
1010                               CvSeqWriter* writer );
1011
1012 /* Closes sequence writer, updates sequence header and returns pointer
1013    to the resultant sequence
1014    (which may be useful if the sequence was created using cvStartWriteSeq))
1015 */
1016 CVAPI(CvSeq*)  cvEndWriteSeq( CvSeqWriter* writer );
1017
1018
1019 /* Updates sequence header. May be useful to get access to some of previously
1020    written elements via cvGetSeqElem or sequence reader */
1021 CVAPI(void)   cvFlushSeqWriter( CvSeqWriter* writer );
1022
1023
1024 /* Initializes sequence reader.
1025    The sequence can be read in forward or backward direction */
1026 CVAPI(void) cvStartReadSeq( const CvSeq* seq, CvSeqReader* reader,
1027                            int reverse CV_DEFAULT(0) );
1028
1029
1030 /* Returns current sequence reader position (currently observed sequence element) */
1031 CVAPI(int)  cvGetSeqReaderPos( CvSeqReader* reader );
1032
1033
1034 /* Changes sequence reader position. It may seek to an absolute or
1035    to relative to the current position */
1036 CVAPI(void)   cvSetSeqReaderPos( CvSeqReader* reader, int index,
1037                                  int is_relative CV_DEFAULT(0));
1038
1039 /* Copies sequence content to a continuous piece of memory */
1040 CVAPI(void*)  cvCvtSeqToArray( const CvSeq* seq, void* elements,
1041                                CvSlice slice CV_DEFAULT(CV_WHOLE_SEQ) );
1042
1043 /* Creates sequence header for array.
1044    After that all the operations on sequences that do not alter the content
1045    can be applied to the resultant sequence */
1046 CVAPI(CvSeq*) cvMakeSeqHeaderForArray( int seq_type, int header_size,
1047                                        int elem_size, void* elements, int total,
1048                                        CvSeq* seq, CvSeqBlock* block );
1049
1050 /* Extracts sequence slice (with or without copying sequence elements) */
1051 CVAPI(CvSeq*) cvSeqSlice( const CvSeq* seq, CvSlice slice,
1052                          CvMemStorage* storage CV_DEFAULT(NULL),
1053                          int copy_data CV_DEFAULT(0));
1054
1055 CV_INLINE CvSeq* cvCloneSeq( const CvSeq* seq, CvMemStorage* storage CV_DEFAULT(NULL))
1056 {
1057     return cvSeqSlice( seq, CV_WHOLE_SEQ, storage, 1 );
1058 }
1059
1060 /* Removes sequence slice */
1061 CVAPI(void)  cvSeqRemoveSlice( CvSeq* seq, CvSlice slice );
1062
1063 /* Inserts a sequence or array into another sequence */
1064 CVAPI(void)  cvSeqInsertSlice( CvSeq* seq, int before_index, const CvArr* from_arr );
1065
1066 /* a < b ? -1 : a > b ? 1 : 0 */
1067 typedef int (CV_CDECL* CvCmpFunc)(const void* a, const void* b, void* userdata );
1068
1069 /* Sorts sequence in-place given element comparison function */
1070 CVAPI(void) cvSeqSort( CvSeq* seq, CvCmpFunc func, void* userdata CV_DEFAULT(NULL) );
1071
1072 /* Finds element in a [sorted] sequence */
1073 CVAPI(char*) cvSeqSearch( CvSeq* seq, const void* elem, CvCmpFunc func,
1074                           int is_sorted, int* elem_idx,
1075                           void* userdata CV_DEFAULT(NULL) );
1076
1077 /* Reverses order of sequence elements in-place */
1078 CVAPI(void) cvSeqInvert( CvSeq* seq );
1079
1080 /* Splits sequence into one or more equivalence classes using the specified criteria */
1081 CVAPI(int)  cvSeqPartition( const CvSeq* seq, CvMemStorage* storage,
1082                             CvSeq** labels, CvCmpFunc is_equal, void* userdata );
1083
1084 /************ Internal sequence functions ************/
1085 CVAPI(void)  cvChangeSeqBlock( void* reader, int direction );
1086 CVAPI(void)  cvCreateSeqBlock( CvSeqWriter* writer );
1087
1088
1089 /* Creates a new set */
1090 CVAPI(CvSet*)  cvCreateSet( int set_flags, int header_size,
1091                             int elem_size, CvMemStorage* storage );
1092
1093 /* Adds new element to the set and returns pointer to it */
1094 CVAPI(int)  cvSetAdd( CvSet* set_header, CvSetElem* elem CV_DEFAULT(NULL),
1095                       CvSetElem** inserted_elem CV_DEFAULT(NULL) );
1096
1097 /* Fast variant of cvSetAdd */
1098 CV_INLINE  CvSetElem* cvSetNew( CvSet* set_header )
1099 {
1100     CvSetElem* elem = set_header->free_elems;
1101     if( elem )
1102     {
1103         set_header->free_elems = elem->next_free;
1104         elem->flags = elem->flags & CV_SET_ELEM_IDX_MASK;
1105         set_header->active_count++;
1106     }
1107     else
1108         cvSetAdd( set_header, NULL, (CvSetElem**)&elem );
1109     return elem;
1110 }
1111
1112 /* Removes set element given its pointer */
1113 CV_INLINE  void cvSetRemoveByPtr( CvSet* set_header, void* elem )
1114 {
1115     CvSetElem* _elem = (CvSetElem*)elem;
1116     assert( _elem->flags >= 0 /*&& (elem->flags & CV_SET_ELEM_IDX_MASK) < set_header->total*/ );
1117     _elem->next_free = set_header->free_elems;
1118     _elem->flags = (_elem->flags & CV_SET_ELEM_IDX_MASK) | CV_SET_ELEM_FREE_FLAG;
1119     set_header->free_elems = _elem;
1120     set_header->active_count--;
1121 }
1122
1123 /* Removes element from the set by its index  */
1124 CVAPI(void)   cvSetRemove( CvSet* set_header, int index );
1125
1126 /* Returns a set element by index. If the element doesn't belong to the set,
1127    NULL is returned */
1128 CV_INLINE CvSetElem* cvGetSetElem( const CvSet* set_header, int index )
1129 {
1130     CvSetElem* elem = (CvSetElem*)cvGetSeqElem( (CvSeq*)set_header, index );
1131     return elem && CV_IS_SET_ELEM( elem ) ? elem : 0;
1132 }
1133
1134 /* Removes all the elements from the set */
1135 CVAPI(void)  cvClearSet( CvSet* set_header );
1136
1137 /* Creates new graph */
1138 CVAPI(CvGraph*)  cvCreateGraph( int graph_flags, int header_size,
1139                                 int vtx_size, int edge_size,
1140                                 CvMemStorage* storage );
1141
1142 /* Adds new vertex to the graph */
1143 CVAPI(int)  cvGraphAddVtx( CvGraph* graph, const CvGraphVtx* vtx CV_DEFAULT(NULL),
1144                            CvGraphVtx** inserted_vtx CV_DEFAULT(NULL) );
1145
1146
1147 /* Removes vertex from the graph together with all incident edges */
1148 CVAPI(int)  cvGraphRemoveVtx( CvGraph* graph, int index );
1149 CVAPI(int)  cvGraphRemoveVtxByPtr( CvGraph* graph, CvGraphVtx* vtx );
1150
1151
1152 /* Link two vertices specifed by indices or pointers if they
1153    are not connected or return pointer to already existing edge
1154    connecting the vertices.
1155    Functions return 1 if a new edge was created, 0 otherwise */
1156 CVAPI(int)  cvGraphAddEdge( CvGraph* graph,
1157                             int start_idx, int end_idx,
1158                             const CvGraphEdge* edge CV_DEFAULT(NULL),
1159                             CvGraphEdge** inserted_edge CV_DEFAULT(NULL) );
1160
1161 CVAPI(int)  cvGraphAddEdgeByPtr( CvGraph* graph,
1162                                CvGraphVtx* start_vtx, CvGraphVtx* end_vtx,
1163                                const CvGraphEdge* edge CV_DEFAULT(NULL),
1164                                CvGraphEdge** inserted_edge CV_DEFAULT(NULL) );
1165
1166 /* Remove edge connecting two vertices */
1167 CVAPI(void)  cvGraphRemoveEdge( CvGraph* graph, int start_idx, int end_idx );
1168 CVAPI(void)  cvGraphRemoveEdgeByPtr( CvGraph* graph, CvGraphVtx* start_vtx,
1169                                      CvGraphVtx* end_vtx );
1170
1171 /* Find edge connecting two vertices */
1172 CVAPI(CvGraphEdge*)  cvFindGraphEdge( const CvGraph* graph, int start_idx, int end_idx );
1173 CVAPI(CvGraphEdge*)  cvFindGraphEdgeByPtr( const CvGraph* graph,
1174                                            const CvGraphVtx* start_vtx,
1175                                            const CvGraphVtx* end_vtx );
1176 #define cvGraphFindEdge cvFindGraphEdge
1177 #define cvGraphFindEdgeByPtr cvFindGraphEdgeByPtr
1178
1179 /* Remove all vertices and edges from the graph */
1180 CVAPI(void)  cvClearGraph( CvGraph* graph );
1181
1182
1183 /* Count number of edges incident to the vertex */
1184 CVAPI(int)  cvGraphVtxDegree( const CvGraph* graph, int vtx_idx );
1185 CVAPI(int)  cvGraphVtxDegreeByPtr( const CvGraph* graph, const CvGraphVtx* vtx );
1186
1187
1188 /* Retrieves graph vertex by given index */
1189 #define cvGetGraphVtx( graph, idx ) (CvGraphVtx*)cvGetSetElem((CvSet*)(graph), (idx))
1190
1191 /* Retrieves index of a graph vertex given its pointer */
1192 #define cvGraphVtxIdx( graph, vtx ) ((vtx)->flags & CV_SET_ELEM_IDX_MASK)
1193
1194 /* Retrieves index of a graph edge given its pointer */
1195 #define cvGraphEdgeIdx( graph, edge ) ((edge)->flags & CV_SET_ELEM_IDX_MASK)
1196
1197 #define cvGraphGetVtxCount( graph ) ((graph)->active_count)
1198 #define cvGraphGetEdgeCount( graph ) ((graph)->edges->active_count)
1199
1200 #define  CV_GRAPH_VERTEX        1
1201 #define  CV_GRAPH_TREE_EDGE     2
1202 #define  CV_GRAPH_BACK_EDGE     4
1203 #define  CV_GRAPH_FORWARD_EDGE  8
1204 #define  CV_GRAPH_CROSS_EDGE    16
1205 #define  CV_GRAPH_ANY_EDGE      30
1206 #define  CV_GRAPH_NEW_TREE      32
1207 #define  CV_GRAPH_BACKTRACKING  64
1208 #define  CV_GRAPH_OVER          -1
1209
1210 #define  CV_GRAPH_ALL_ITEMS    -1
1211
1212 /* flags for graph vertices and edges */
1213 #define  CV_GRAPH_ITEM_VISITED_FLAG  (1 << 30)
1214 #define  CV_IS_GRAPH_VERTEX_VISITED(vtx) \
1215     (((CvGraphVtx*)(vtx))->flags & CV_GRAPH_ITEM_VISITED_FLAG)
1216 #define  CV_IS_GRAPH_EDGE_VISITED(edge) \
1217     (((CvGraphEdge*)(edge))->flags & CV_GRAPH_ITEM_VISITED_FLAG)
1218 #define  CV_GRAPH_SEARCH_TREE_NODE_FLAG   (1 << 29)
1219 #define  CV_GRAPH_FORWARD_EDGE_FLAG       (1 << 28)
1220
1221 typedef struct CvGraphScanner
1222 {
1223     CvGraphVtx* vtx;       /* current graph vertex (or current edge origin) */
1224     CvGraphVtx* dst;       /* current graph edge destination vertex */
1225     CvGraphEdge* edge;     /* current edge */
1226
1227     CvGraph* graph;        /* the graph */
1228     CvSeq*   stack;        /* the graph vertex stack */
1229     int      index;        /* the lower bound of certainly visited vertices */
1230     int      mask;         /* event mask */
1231 }
1232 CvGraphScanner;
1233
1234 /* Creates new graph scanner. */
1235 CVAPI(CvGraphScanner*)  cvCreateGraphScanner( CvGraph* graph,
1236                                              CvGraphVtx* vtx CV_DEFAULT(NULL),
1237                                              int mask CV_DEFAULT(CV_GRAPH_ALL_ITEMS));
1238
1239 /* Releases graph scanner. */
1240 CVAPI(void) cvReleaseGraphScanner( CvGraphScanner** scanner );
1241
1242 /* Get next graph element */
1243 CVAPI(int)  cvNextGraphItem( CvGraphScanner* scanner );
1244
1245 /* Creates a copy of graph */
1246 CVAPI(CvGraph*) cvCloneGraph( const CvGraph* graph, CvMemStorage* storage );
1247
1248 /****************************************************************************************\
1249 *                                     Drawing                                            *
1250 \****************************************************************************************/
1251
1252 /****************************************************************************************\
1253 *       Drawing functions work with images/matrices of arbitrary type.                   *
1254 *       For color images the channel order is BGR[A]                                     *
1255 *       Antialiasing is supported only for 8-bit image now.                              *
1256 *       All the functions include parameter color that means rgb value (that may be      *
1257 *       constructed with CV_RGB macro) for color images and brightness                   *
1258 *       for grayscale images.                                                            *
1259 *       If a drawn figure is partially or completely outside of the image, it is clipped.*
1260 \****************************************************************************************/
1261
1262 #define CV_RGB( r, g, b )  cvScalar( (b), (g), (r), 0 )
1263 #define CV_FILLED -1
1264
1265 #define CV_AA 16
1266
1267 /* Draws 4-connected, 8-connected or antialiased line segment connecting two points */
1268 CVAPI(void)  cvLine( CvArr* img, CvPoint pt1, CvPoint pt2,
1269                      CvScalar color, int thickness CV_DEFAULT(1),
1270                      int line_type CV_DEFAULT(8), int shift CV_DEFAULT(0) );
1271
1272 /* Draws a rectangle given two opposite corners of the rectangle (pt1 & pt2),
1273    if thickness<0 (e.g. thickness == CV_FILLED), the filled box is drawn */
1274 CVAPI(void)  cvRectangle( CvArr* img, CvPoint pt1, CvPoint pt2,
1275                           CvScalar color, int thickness CV_DEFAULT(1),
1276                           int line_type CV_DEFAULT(8),
1277                           int shift CV_DEFAULT(0));
1278
1279 /* Draws a circle with specified center and radius.
1280    Thickness works in the same way as with cvRectangle */
1281 CVAPI(void)  cvCircle( CvArr* img, CvPoint center, int radius,
1282                        CvScalar color, int thickness CV_DEFAULT(1),
1283                        int line_type CV_DEFAULT(8), int shift CV_DEFAULT(0));
1284
1285 /* Draws ellipse outline, filled ellipse, elliptic arc or filled elliptic sector,
1286    depending on <thickness>, <start_angle> and <end_angle> parameters. The resultant figure
1287    is rotated by <angle>. All the angles are in degrees */
1288 CVAPI(void)  cvEllipse( CvArr* img, CvPoint center, CvSize axes,
1289                         double angle, double start_angle, double end_angle,
1290                         CvScalar color, int thickness CV_DEFAULT(1),
1291                         int line_type CV_DEFAULT(8), int shift CV_DEFAULT(0));
1292
1293 CV_INLINE  void  cvEllipseBox( CvArr* img, CvBox2D box, CvScalar color,
1294                                int thickness CV_DEFAULT(1),
1295                                int line_type CV_DEFAULT(8), int shift CV_DEFAULT(0) )
1296 {
1297     CvSize axes;
1298     axes.width = cvRound(box.size.height*0.5);
1299     axes.height = cvRound(box.size.width*0.5);
1300
1301     cvEllipse( img, cvPointFrom32f( box.center ), axes, box.angle,
1302                0, 360, color, thickness, line_type, shift );
1303 }
1304
1305 /* Fills convex or monotonous polygon. */
1306 CVAPI(void)  cvFillConvexPoly( CvArr* img, CvPoint* pts, int npts, CvScalar color,
1307                                int line_type CV_DEFAULT(8), int shift CV_DEFAULT(0));
1308
1309 /* Fills an area bounded by one or more arbitrary polygons */
1310 CVAPI(void)  cvFillPoly( CvArr* img, CvPoint** pts, int* npts, int contours, CvScalar color,
1311                          int line_type CV_DEFAULT(8), int shift CV_DEFAULT(0) );
1312
1313 /* Draws one or more polygonal curves */
1314 CVAPI(void)  cvPolyLine( CvArr* img, CvPoint** pts, int* npts, int contours,
1315                          int is_closed, CvScalar color, int thickness CV_DEFAULT(1),
1316                          int line_type CV_DEFAULT(8), int shift CV_DEFAULT(0) );
1317
1318 #define cvDrawRect cvRectangle
1319 #define cvDrawLine cvLine
1320 #define cvDrawCircle cvCircle
1321 #define cvDrawEllipse cvEllipse
1322 #define cvDrawPolyLine cvPolyLine
1323
1324 /* Clips the line segment connecting *pt1 and *pt2
1325    by the rectangular window
1326    (0<=x<img_size.width, 0<=y<img_size.height). */
1327 CVAPI(int) cvClipLine( CvSize img_size, CvPoint* pt1, CvPoint* pt2 );
1328
1329 /* Initializes line iterator. Initially, line_iterator->ptr will point
1330    to pt1 (or pt2, see left_to_right description) location in the image.
1331    Returns the number of pixels on the line between the ending points. */
1332 CVAPI(int)  cvInitLineIterator( const CvArr* image, CvPoint pt1, CvPoint pt2,
1333                                 CvLineIterator* line_iterator,
1334                                 int connectivity CV_DEFAULT(8),
1335                                 int left_to_right CV_DEFAULT(0));
1336
1337 /* Moves iterator to the next line point */
1338 #define CV_NEXT_LINE_POINT( line_iterator )                     \
1339 {                                                               \
1340     int _line_iterator_mask = (line_iterator).err < 0 ? -1 : 0; \
1341     (line_iterator).err += (line_iterator).minus_delta +        \
1342         ((line_iterator).plus_delta & _line_iterator_mask);     \
1343     (line_iterator).ptr += (line_iterator).minus_step +         \
1344         ((line_iterator).plus_step & _line_iterator_mask);      \
1345 }
1346
1347
1348 /* basic font types */
1349 #define CV_FONT_HERSHEY_SIMPLEX         0
1350 #define CV_FONT_HERSHEY_PLAIN           1
1351 #define CV_FONT_HERSHEY_DUPLEX          2
1352 #define CV_FONT_HERSHEY_COMPLEX         3
1353 #define CV_FONT_HERSHEY_TRIPLEX         4
1354 #define CV_FONT_HERSHEY_COMPLEX_SMALL   5
1355 #define CV_FONT_HERSHEY_SCRIPT_SIMPLEX  6
1356 #define CV_FONT_HERSHEY_SCRIPT_COMPLEX  7
1357
1358 /* font flags */
1359 #define CV_FONT_ITALIC                 16
1360
1361 #define CV_FONT_VECTOR0    CV_FONT_HERSHEY_SIMPLEX
1362
1363 /* Font structure */
1364 typedef struct CvFont
1365 {
1366     int         font_face; /* =CV_FONT_* */
1367     const int*  ascii; /* font data and metrics */
1368     const int*  greek;
1369     const int*  cyrillic;
1370     float       hscale, vscale;
1371     float       shear; /* slope coefficient: 0 - normal, >0 - italic */
1372     int         thickness; /* letters thickness */
1373     float       dx; /* horizontal interval between letters */
1374     int         line_type;
1375 }
1376 CvFont;
1377
1378 /* Initializes font structure used further in cvPutText */
1379 CVAPI(void)  cvInitFont( CvFont* font, int font_face,
1380                          double hscale, double vscale,
1381                          double shear CV_DEFAULT(0),
1382                          int thickness CV_DEFAULT(1),
1383                          int line_type CV_DEFAULT(8));
1384
1385 CV_INLINE CvFont cvFont( double scale, int thickness CV_DEFAULT(1) )
1386 {
1387     CvFont font;
1388     cvInitFont( &font, CV_FONT_HERSHEY_PLAIN, scale, scale, 0, thickness, CV_AA );
1389     return font;
1390 }
1391
1392 /* Renders text stroke with specified font and color at specified location.
1393    CvFont should be initialized with cvInitFont */
1394 CVAPI(void)  cvPutText( CvArr* img, const char* text, CvPoint org,
1395                         const CvFont* font, CvScalar color );
1396
1397 /* Calculates bounding box of text stroke (useful for alignment) */
1398 CVAPI(void)  cvGetTextSize( const char* text_string, const CvFont* font,
1399                             CvSize* text_size, int* baseline );
1400
1401 /* Unpacks color value, if arrtype is CV_8UC?, <color> is treated as
1402    packed color value, otherwise the first channels (depending on arrtype)
1403    of destination scalar are set to the same value = <color> */
1404 CVAPI(CvScalar)  cvColorToScalar( double packed_color, int arrtype );
1405
1406 /* Returns the polygon points which make up the given ellipse.  The ellipse is define by
1407    the box of size 'axes' rotated 'angle' around the 'center'.  A partial sweep
1408    of the ellipse arc can be done by spcifying arc_start and arc_end to be something
1409    other than 0 and 360, respectively.  The input array 'pts' must be large enough to
1410    hold the result.  The total number of points stored into 'pts' is returned by this
1411    function. */
1412 CVAPI(int) cvEllipse2Poly( CvPoint center, CvSize axes,
1413                  int angle, int arc_start, int arc_end, CvPoint * pts, int delta );
1414
1415 /* Draws contour outlines or filled interiors on the image */
1416 CVAPI(void)  cvDrawContours( CvArr *img, CvSeq* contour,
1417                             CvScalar external_color, CvScalar hole_color,
1418                             int max_level, int thickness CV_DEFAULT(1),
1419                             int line_type CV_DEFAULT(8),
1420                             CvPoint offset CV_DEFAULT(cvPoint(0,0)));
1421
1422 /* Does look-up transformation. Elements of the source array
1423    (that should be 8uC1 or 8sC1) are used as indexes in lutarr 256-element table */
1424 CVAPI(void) cvLUT( const CvArr* src, CvArr* dst, const CvArr* lut );
1425
1426
1427 /******************* Iteration through the sequence tree *****************/
1428 typedef struct CvTreeNodeIterator
1429 {
1430     const void* node;
1431     int level;
1432     int max_level;
1433 }
1434 CvTreeNodeIterator;
1435
1436 CVAPI(void) cvInitTreeNodeIterator( CvTreeNodeIterator* tree_iterator,
1437                                    const void* first, int max_level );
1438 CVAPI(void*) cvNextTreeNode( CvTreeNodeIterator* tree_iterator );
1439 CVAPI(void*) cvPrevTreeNode( CvTreeNodeIterator* tree_iterator );
1440
1441 /* Inserts sequence into tree with specified "parent" sequence.
1442    If parent is equal to frame (e.g. the most external contour),
1443    then added contour will have null pointer to parent. */
1444 CVAPI(void) cvInsertNodeIntoTree( void* node, void* parent, void* frame );
1445
1446 /* Removes contour from tree (together with the contour children). */
1447 CVAPI(void) cvRemoveNodeFromTree( void* node, void* frame );
1448
1449 /* Gathers pointers to all the sequences,
1450    accessible from the <first>, to the single sequence */
1451 CVAPI(CvSeq*) cvTreeToNodeSeq( const void* first, int header_size,
1452                               CvMemStorage* storage );
1453
1454 /* The function implements the K-means algorithm for clustering an array of sample
1455    vectors in a specified number of classes */
1456 CVAPI(void)  cvKMeans2( const CvArr* samples, int cluster_count,
1457                         CvArr* labels, CvTermCriteria termcrit );
1458
1459 /****************************************************************************************\
1460 *                                    System functions                                    *
1461 \****************************************************************************************/
1462
1463 /* Add the function pointers table with associated information to the IPP primitives list */
1464 CVAPI(int)  cvRegisterModule( const CvModuleInfo* module_info );
1465
1466 /* Loads optimized functions from IPP, MKL etc. or switches back to pure C code */
1467 CVAPI(int)  cvUseOptimized( int on_off );
1468
1469 /* Retrieves information about the registered modules and loaded optimized plugins */
1470 CVAPI(void)  cvGetModuleInfo( const char* module_name,
1471                               const char** version,
1472                               const char** loaded_addon_plugins );
1473
1474 /* Get current OpenCV error status */
1475 CVAPI(int) cvGetErrStatus( void );
1476
1477 /* Sets error status silently */
1478 CVAPI(void) cvSetErrStatus( int status );
1479
1480 #define CV_ErrModeLeaf     0   /* Print error and exit program */
1481 #define CV_ErrModeParent   1   /* Print error and continue */
1482 #define CV_ErrModeSilent   2   /* Don't print and continue */
1483
1484 /* Retrives current error processing mode */
1485 CVAPI(int)  cvGetErrMode( void );
1486
1487 /* Sets error processing mode, returns previously used mode */
1488 CVAPI(int) cvSetErrMode( int mode );
1489
1490 /* Sets error status and performs some additonal actions (displaying message box,
1491    writing message to stderr, terminating application etc.)
1492    depending on the current error mode */
1493 CVAPI(void) cvError( int status, const char* func_name,
1494                     const char* err_msg, const char* file_name, int line );
1495
1496 /* Retrieves textual description of the error given its code */
1497 CVAPI(const char*) cvErrorStr( int status );
1498
1499 /* Retrieves detailed information about the last error occured */
1500 CVAPI(int) cvGetErrInfo( const char** errcode_desc, const char** description,
1501                         const char** filename, int* line );
1502
1503 /* Maps IPP error codes to the counterparts from OpenCV */
1504 CVAPI(int) cvErrorFromIppStatus( int ipp_status );
1505
1506 typedef int (CV_CDECL *CvErrorCallback)( int status, const char* func_name,
1507                     const char* err_msg, const char* file_name, int line, void* userdata );
1508
1509 /* Assigns a new error-handling function */
1510 CVAPI(CvErrorCallback) cvRedirectError( CvErrorCallback error_handler,
1511                                        void* userdata CV_DEFAULT(NULL),
1512                                        void** prev_userdata CV_DEFAULT(NULL) );
1513
1514 /*
1515     Output to:
1516         cvNulDevReport - nothing
1517         cvStdErrReport - console(fprintf(stderr,...))
1518         cvGuiBoxReport - MessageBox(WIN32)
1519 */
1520 CVAPI(int) cvNulDevReport( int status, const char* func_name, const char* err_msg,
1521                           const char* file_name, int line, void* userdata );
1522
1523 CVAPI(int) cvStdErrReport( int status, const char* func_name, const char* err_msg,
1524                           const char* file_name, int line, void* userdata );
1525
1526 CVAPI(int) cvGuiBoxReport( int status, const char* func_name, const char* err_msg,
1527                           const char* file_name, int line, void* userdata );
1528
1529 typedef void* (CV_CDECL *CvAllocFunc)(size_t size, void* userdata);
1530 typedef int (CV_CDECL *CvFreeFunc)(void* pptr, void* userdata);
1531
1532 /* Set user-defined memory managment functions (substitutors for malloc and free) that
1533    will be called by cvAlloc, cvFree and higher-level functions (e.g. cvCreateImage) */
1534 CVAPI(void) cvSetMemoryManager( CvAllocFunc alloc_func CV_DEFAULT(NULL),
1535                                CvFreeFunc free_func CV_DEFAULT(NULL),
1536                                void* userdata CV_DEFAULT(NULL));
1537
1538
1539 typedef IplImage* (CV_STDCALL* Cv_iplCreateImageHeader)
1540                             (int,int,int,char*,char*,int,int,int,int,int,
1541                             IplROI*,IplImage*,void*,IplTileInfo*);
1542 typedef void (CV_STDCALL* Cv_iplAllocateImageData)(IplImage*,int,int);
1543 typedef void (CV_STDCALL* Cv_iplDeallocate)(IplImage*,int);
1544 typedef IplROI* (CV_STDCALL* Cv_iplCreateROI)(int,int,int,int,int);
1545 typedef IplImage* (CV_STDCALL* Cv_iplCloneImage)(const IplImage*);
1546
1547 /* Makes OpenCV use IPL functions for IplImage allocation/deallocation */
1548 CVAPI(void) cvSetIPLAllocators( Cv_iplCreateImageHeader create_header,
1549                                Cv_iplAllocateImageData allocate_data,
1550                                Cv_iplDeallocate deallocate,
1551                                Cv_iplCreateROI create_roi,
1552                                Cv_iplCloneImage clone_image );
1553
1554 #define CV_TURN_ON_IPL_COMPATIBILITY()                                  \
1555     cvSetIPLAllocators( iplCreateImageHeader, iplAllocateImage,         \
1556                         iplDeallocate, iplCreateROI, iplCloneImage )
1557
1558 /****************************************************************************************\
1559 *                                    Data Persistence                                    *
1560 \****************************************************************************************/
1561
1562 /********************************** High-level functions ********************************/
1563
1564 /* opens existing or creates new file storage */
1565 CVAPI(CvFileStorage*)  cvOpenFileStorage( const char* filename,
1566                                           CvMemStorage* memstorage,
1567                                           int flags );
1568
1569 /* closes file storage and deallocates buffers */
1570 CVAPI(void) cvReleaseFileStorage( CvFileStorage** fs );
1571
1572 /* returns attribute value or 0 (NULL) if there is no such attribute */
1573 CVAPI(const char*) cvAttrValue( const CvAttrList* attr, const char* attr_name );
1574
1575 /* starts writing compound structure (map or sequence) */
1576 CVAPI(void) cvStartWriteStruct( CvFileStorage* fs, const char* name,
1577                                 int struct_flags, const char* type_name CV_DEFAULT(NULL),
1578                                 CvAttrList attributes CV_DEFAULT(cvAttrList()));
1579
1580 /* finishes writing compound structure */
1581 CVAPI(void) cvEndWriteStruct( CvFileStorage* fs );
1582
1583 /* writes an integer */
1584 CVAPI(void) cvWriteInt( CvFileStorage* fs, const char* name, int value );
1585
1586 /* writes a floating-point number */
1587 CVAPI(void) cvWriteReal( CvFileStorage* fs, const char* name, double value );
1588
1589 /* writes a string */
1590 CVAPI(void) cvWriteString( CvFileStorage* fs, const char* name,
1591                            const char* str, int quote CV_DEFAULT(0) );
1592
1593 /* writes a comment */
1594 CVAPI(void) cvWriteComment( CvFileStorage* fs, const char* comment,
1595                             int eol_comment );
1596
1597 /* writes instance of a standard type (matrix, image, sequence, graph etc.)
1598    or user-defined type */
1599 CVAPI(void) cvWrite( CvFileStorage* fs, const char* name, const void* ptr,
1600                          CvAttrList attributes CV_DEFAULT(cvAttrList()));
1601
1602 /* starts the next stream */
1603 CVAPI(void) cvStartNextStream( CvFileStorage* fs );
1604
1605 /* helper function: writes multiple integer or floating-point numbers */
1606 CVAPI(void) cvWriteRawData( CvFileStorage* fs, const void* src,
1607                                 int len, const char* dt );
1608
1609 /* returns the hash entry corresponding to the specified literal key string or 0
1610    if there is no such a key in the storage */
1611 CVAPI(CvStringHashNode*) cvGetHashedKey( CvFileStorage* fs, const char* name,
1612                                         int len CV_DEFAULT(-1),
1613                                         int create_missing CV_DEFAULT(0));
1614
1615 /* returns file node with the specified key within the specified map
1616    (collection of named nodes) */
1617 CVAPI(CvFileNode*) cvGetRootFileNode( const CvFileStorage* fs,
1618                                      int stream_index CV_DEFAULT(0) );
1619
1620 /* returns file node with the specified key within the specified map
1621    (collection of named nodes) */
1622 CVAPI(CvFileNode*) cvGetFileNode( CvFileStorage* fs, CvFileNode* map,
1623                                  const CvStringHashNode* key,
1624                                  int create_missing CV_DEFAULT(0) );
1625
1626 /* this is a slower version of cvGetFileNode that takes the key as a literal string */
1627 CVAPI(CvFileNode*) cvGetFileNodeByName( const CvFileStorage* fs,
1628                                        const CvFileNode* map,
1629                                        const char* name );
1630
1631 CV_INLINE int cvReadInt( const CvFileNode* node, int default_value CV_DEFAULT(0) )
1632 {
1633     return !node ? default_value :
1634         CV_NODE_IS_INT(node->tag) ? node->data.i :
1635         CV_NODE_IS_REAL(node->tag) ? cvRound(node->data.f) : 0x7fffffff;
1636 }
1637
1638
1639 CV_INLINE int cvReadIntByName( const CvFileStorage* fs, const CvFileNode* map,
1640                          const char* name, int default_value CV_DEFAULT(0) )
1641 {
1642     return cvReadInt( cvGetFileNodeByName( fs, map, name ), default_value );
1643 }
1644
1645
1646 CV_INLINE double cvReadReal( const CvFileNode* node, double default_value CV_DEFAULT(0.) )
1647 {
1648     return !node ? default_value :
1649         CV_NODE_IS_INT(node->tag) ? (double)node->data.i :
1650         CV_NODE_IS_REAL(node->tag) ? node->data.f : 1e300;
1651 }
1652
1653
1654 CV_INLINE double cvReadRealByName( const CvFileStorage* fs, const CvFileNode* map,
1655                         const char* name, double default_value CV_DEFAULT(0.) )
1656 {
1657     return cvReadReal( cvGetFileNodeByName( fs, map, name ), default_value );
1658 }
1659
1660
1661 CV_INLINE const char* cvReadString( const CvFileNode* node,
1662                         const char* default_value CV_DEFAULT(NULL) )
1663 {
1664     return !node ? default_value : CV_NODE_IS_STRING(node->tag) ? node->data.str.ptr : 0;
1665 }
1666
1667
1668 CV_INLINE const char* cvReadStringByName( const CvFileStorage* fs, const CvFileNode* map,
1669                         const char* name, const char* default_value CV_DEFAULT(NULL) )
1670 {
1671     return cvReadString( cvGetFileNodeByName( fs, map, name ), default_value );
1672 }
1673
1674
1675 /* decodes standard or user-defined object and returns it */
1676 CVAPI(void*) cvRead( CvFileStorage* fs, CvFileNode* node,
1677                         CvAttrList* attributes CV_DEFAULT(NULL));
1678
1679 /* decodes standard or user-defined object and returns it */
1680 CV_INLINE void* cvReadByName( CvFileStorage* fs, const CvFileNode* map,
1681                               const char* name, CvAttrList* attributes CV_DEFAULT(NULL) )
1682 {
1683     return cvRead( fs, cvGetFileNodeByName( fs, map, name ), attributes );
1684 }
1685
1686
1687 /* starts reading data from sequence or scalar numeric node */
1688 CVAPI(void) cvStartReadRawData( const CvFileStorage* fs, const CvFileNode* src,
1689                                CvSeqReader* reader );
1690
1691 /* reads multiple numbers and stores them to array */
1692 CVAPI(void) cvReadRawDataSlice( const CvFileStorage* fs, CvSeqReader* reader,
1693                                int count, void* dst, const char* dt );
1694
1695 /* combination of two previous functions for easier reading of whole sequences */
1696 CVAPI(void) cvReadRawData( const CvFileStorage* fs, const CvFileNode* src,
1697                           void* dst, const char* dt );
1698
1699 /* writes a copy of file node to file storage */
1700 CVAPI(void) cvWriteFileNode( CvFileStorage* fs, const char* new_node_name,
1701                             const CvFileNode* node, int embed );
1702
1703 /* returns name of file node */
1704 CVAPI(const char*) cvGetFileNodeName( const CvFileNode* node );
1705
1706 /*********************************** Adding own types ***********************************/
1707
1708 CVAPI(void) cvRegisterType( const CvTypeInfo* info );
1709 CVAPI(void) cvUnregisterType( const char* type_name );
1710 CVAPI(CvTypeInfo*) cvFirstType(void);
1711 CVAPI(CvTypeInfo*) cvFindType( const char* type_name );
1712 CVAPI(CvTypeInfo*) cvTypeOf( const void* struct_ptr );
1713
1714 /* universal functions */
1715 CVAPI(void) cvRelease( void** struct_ptr );
1716 CVAPI(void*) cvClone( const void* struct_ptr );
1717
1718 /* simple API for reading/writing data */
1719 CVAPI(void) cvSave( const char* filename, const void* struct_ptr,
1720                     const char* name CV_DEFAULT(NULL),
1721                     const char* comment CV_DEFAULT(NULL),
1722                     CvAttrList attributes CV_DEFAULT(cvAttrList()));
1723 CVAPI(void*) cvLoad( const char* filename,
1724                      CvMemStorage* memstorage CV_DEFAULT(NULL),
1725                      const char* name CV_DEFAULT(NULL),
1726                      const char** real_name CV_DEFAULT(NULL) );
1727
1728 /*********************************** Measuring Execution Time ***************************/
1729
1730 /* helper functions for RNG initialization and accurate time measurement:
1731    uses internal clock counter on x86 */
1732 CVAPI(int64)  cvGetTickCount( void );
1733 CVAPI(double) cvGetTickFrequency( void );
1734
1735 /*********************************** Multi-Threading ************************************/
1736
1737 /* retrieve/set the number of threads used in OpenMP implementations */
1738 CVAPI(int)  cvGetNumThreads( void );
1739 CVAPI(void) cvSetNumThreads( int threads CV_DEFAULT(0) );
1740 /* get index of the thread being executed */
1741 CVAPI(int)  cvGetThreadNum( void );
1742
1743 #ifdef __cplusplus
1744 }
1745
1746 #include "cxcore.hpp"
1747 #endif
1748
1749 #endif /*_CXCORE_H_*/