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