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