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