Cinder

  • Main Page
  • Related Pages
  • Namespaces
  • Classes
  • Files
  • File List
  • File Members

include/OpenCV/cxcore.h

Go to the documentation of this file.
00001 /*M///////////////////////////////////////////////////////////////////////////////////////
00002 //
00003 //  IMPORTANT: READ BEFORE DOWNLOADING, COPYING, INSTALLING OR USING.
00004 //
00005 //  By downloading, copying, installing or using the software you agree to this license.
00006 //  If you do not agree to this license, do not download, install,
00007 //  copy or use the software.
00008 //
00009 //
00010 //                           License Agreement
00011 //                For Open Source Computer Vision Library
00012 //
00013 // Copyright (C) 2000-2008, Intel Corporation, all rights reserved.
00014 // Copyright (C) 2009, Willow Garage Inc., all rights reserved.
00015 // Third party copyrights are property of their respective owners.
00016 //
00017 // Redistribution and use in source and binary forms, with or without modification,
00018 // are permitted provided that the following conditions are met:
00019 //
00020 //   * Redistribution's of source code must retain the above copyright notice,
00021 //     this list of conditions and the following disclaimer.
00022 //
00023 //   * Redistribution's in binary form must reproduce the above copyright notice,
00024 //     this list of conditions and the following disclaimer in the documentation
00025 //     and/or other materials provided with the distribution.
00026 //
00027 //   * The name of the copyright holders may not be used to endorse or promote products
00028 //     derived from this software without specific prior written permission.
00029 //
00030 // This software is provided by the copyright holders and contributors "as is" and
00031 // any express or implied warranties, including, but not limited to, the implied
00032 // warranties of merchantability and fitness for a particular purpose are disclaimed.
00033 // In no event shall the Intel Corporation or contributors be liable for any direct,
00034 // indirect, incidental, special, exemplary, or consequential damages
00035 // (including, but not limited to, procurement of substitute goods or services;
00036 // loss of use, data, or profits; or business interruption) however caused
00037 // and on any theory of liability, whether in contract, strict liability,
00038 // or tort (including negligence or otherwise) arising in any way out of
00039 // the use of this software, even if advised of the possibility of such damage.
00040 //
00041 //M*/
00042 
00043 
00044 #ifndef __OPENCV_CORE_H__
00045 #define __OPENCV_CORE_H__
00046 
00047 #ifdef __IPL_H__
00048 #define HAVE_IPL
00049 #endif
00050 
00051 #ifndef SKIP_INCLUDES
00052   #if defined HAVE_IPL && !defined __IPL_H__
00053     #ifndef _INC_WINDOWS
00054         #define CV_PRETEND_WINDOWS
00055         #define _INC_WINDOWS
00056         typedef struct tagBITMAPINFOHEADER BITMAPINFOHEADER;
00057         typedef int BOOL;
00058     #endif
00059     #if defined WIN32 || defined _WIN32 || defined WIN64 || defined _WIN64
00060       #include "ipl.h"
00061     #else
00062       #include "ipl/ipl.h"
00063     #endif
00064     #ifdef CV_PRETEND_WINDOWS
00065         #undef _INC_WINDOWS
00066     #endif
00067   #endif
00068 #endif // SKIP_INCLUDES
00069 
00070 #include "cxtypes.h"
00071 #include "cxerror.h"
00072 #include "cvver.h"
00073 
00074 #ifdef __cplusplus
00075 extern "C" {
00076 #endif
00077 
00078 /****************************************************************************************\
00079 *          Array allocation, deallocation, initialization and access to elements         *
00080 \****************************************************************************************/
00081 
00082 /* <malloc> wrapper.
00083    If there is no enough memory, the function
00084    (as well as other OpenCV functions that call cvAlloc)
00085    raises an error. */
00086 CVAPI(void*)  cvAlloc( size_t size );
00087 
00088 /* <free> wrapper.
00089    Here and further all the memory releasing functions
00090    (that all call cvFree) take double pointer in order to
00091    to clear pointer to the data after releasing it.
00092    Passing pointer to NULL pointer is Ok: nothing happens in this case
00093 */
00094 CVAPI(void)   cvFree_( void* ptr );
00095 #define cvFree(ptr) (cvFree_(*(ptr)), *(ptr)=0)
00096 
00097 /* Allocates and initializes IplImage header */
00098 CVAPI(IplImage*)  cvCreateImageHeader( CvSize size, int depth, int channels );
00099 
00100 /* Inializes IplImage header */
00101 CVAPI(IplImage*) cvInitImageHeader( IplImage* image, CvSize size, int depth,
00102                                    int channels, int origin CV_DEFAULT(0),
00103                                    int align CV_DEFAULT(4));
00104 
00105 /* Creates IPL image (header and data) */
00106 CVAPI(IplImage*)  cvCreateImage( CvSize size, int depth, int channels );
00107 
00108 /* Releases (i.e. deallocates) IPL image header */
00109 CVAPI(void)  cvReleaseImageHeader( IplImage** image );
00110 
00111 /* Releases IPL image header and data */
00112 CVAPI(void)  cvReleaseImage( IplImage** image );
00113 
00114 /* Creates a copy of IPL image (widthStep may differ) */
00115 CVAPI(IplImage*) cvCloneImage( const IplImage* image );
00116 
00117 /* Sets a Channel Of Interest (only a few functions support COI) -
00118    use cvCopy to extract the selected channel and/or put it back */
00119 CVAPI(void)  cvSetImageCOI( IplImage* image, int coi );
00120 
00121 /* Retrieves image Channel Of Interest */
00122 CVAPI(int)  cvGetImageCOI( const IplImage* image );
00123 
00124 /* Sets image ROI (region of interest) (COI is not changed) */
00125 CVAPI(void)  cvSetImageROI( IplImage* image, CvRect rect );
00126 
00127 /* Resets image ROI and COI */
00128 CVAPI(void)  cvResetImageROI( IplImage* image );
00129 
00130 /* Retrieves image ROI */
00131 CVAPI(CvRect) cvGetImageROI( const IplImage* image );
00132 
00133 /* Allocates and initalizes CvMat header */
00134 CVAPI(CvMat*)  cvCreateMatHeader( int rows, int cols, int type );
00135 
00136 #define CV_AUTOSTEP  0x7fffffff
00137 
00138 /* Initializes CvMat header */
00139 CVAPI(CvMat*) cvInitMatHeader( CvMat* mat, int rows, int cols,
00140                               int type, void* data CV_DEFAULT(NULL),
00141                               int step CV_DEFAULT(CV_AUTOSTEP) );
00142 
00143 /* Allocates and initializes CvMat header and allocates data */
00144 CVAPI(CvMat*)  cvCreateMat( int rows, int cols, int type );
00145 
00146 /* Releases CvMat header and deallocates matrix data
00147    (reference counting is used for data) */
00148 CVAPI(void)  cvReleaseMat( CvMat** mat );
00149 
00150 /* Decrements CvMat data reference counter and deallocates the data if
00151    it reaches 0 */
00152 CV_INLINE  void  cvDecRefData( CvArr* arr )
00153 {
00154     if( CV_IS_MAT( arr ))
00155     {
00156         CvMat* mat = (CvMat*)arr;
00157         mat->data.ptr = NULL;
00158         if( mat->refcount != NULL && --*mat->refcount == 0 )
00159             cvFree( &mat->refcount );
00160         mat->refcount = NULL;
00161     }
00162     else if( CV_IS_MATND( arr ))
00163     {
00164         CvMatND* mat = (CvMatND*)arr;
00165         mat->data.ptr = NULL;
00166         if( mat->refcount != NULL && --*mat->refcount == 0 )
00167             cvFree( &mat->refcount );
00168         mat->refcount = NULL;
00169     }
00170 }
00171 
00172 /* Increments CvMat data reference counter */
00173 CV_INLINE  int  cvIncRefData( CvArr* arr )
00174 {
00175     int refcount = 0;
00176     if( CV_IS_MAT( arr ))
00177     {
00178         CvMat* mat = (CvMat*)arr;
00179         if( mat->refcount != NULL )
00180             refcount = ++*mat->refcount;
00181     }
00182     else if( CV_IS_MATND( arr ))
00183     {
00184         CvMatND* mat = (CvMatND*)arr;
00185         if( mat->refcount != NULL )
00186             refcount = ++*mat->refcount;
00187     }
00188     return refcount;
00189 }
00190 
00191 
00192 /* Creates an exact copy of the input matrix (except, may be, step value) */
00193 CVAPI(CvMat*) cvCloneMat( const CvMat* mat );
00194 
00195 
00196 /* Makes a new matrix from <rect> subrectangle of input array.
00197    No data is copied */
00198 CVAPI(CvMat*) cvGetSubRect( const CvArr* arr, CvMat* submat, CvRect rect );
00199 #define cvGetSubArr cvGetSubRect
00200 
00201 /* Selects row span of the input array: arr(start_row:delta_row:end_row,:)
00202     (end_row is not included into the span). */
00203 CVAPI(CvMat*) cvGetRows( const CvArr* arr, CvMat* submat,
00204                         int start_row, int end_row,
00205                         int delta_row CV_DEFAULT(1));
00206 
00207 CV_INLINE  CvMat*  cvGetRow( const CvArr* arr, CvMat* submat, int row )
00208 {
00209     return cvGetRows( arr, submat, row, row + 1, 1 );
00210 }
00211 
00212 
00213 /* Selects column span of the input array: arr(:,start_col:end_col)
00214    (end_col is not included into the span) */
00215 CVAPI(CvMat*) cvGetCols( const CvArr* arr, CvMat* submat,
00216                         int start_col, int end_col );
00217 
00218 CV_INLINE  CvMat*  cvGetCol( const CvArr* arr, CvMat* submat, int col )
00219 {
00220     return cvGetCols( arr, submat, col, col + 1 );
00221 }
00222 
00223 /* Select a diagonal of the input array.
00224    (diag = 0 means the main diagonal, >0 means a diagonal above the main one,
00225    <0 - below the main one).
00226    The diagonal will be represented as a column (nx1 matrix). */
00227 CVAPI(CvMat*) cvGetDiag( const CvArr* arr, CvMat* submat,
00228                             int diag CV_DEFAULT(0));
00229 
00230 /* low-level scalar <-> raw data conversion functions */
00231 CVAPI(void) cvScalarToRawData( const CvScalar* scalar, void* data, int type,
00232                               int extend_to_12 CV_DEFAULT(0) );
00233 
00234 CVAPI(void) cvRawDataToScalar( const void* data, int type, CvScalar* scalar );
00235 
00236 /* Allocates and initializes CvMatND header */
00237 CVAPI(CvMatND*)  cvCreateMatNDHeader( int dims, const int* sizes, int type );
00238 
00239 /* Allocates and initializes CvMatND header and allocates data */
00240 CVAPI(CvMatND*)  cvCreateMatND( int dims, const int* sizes, int type );
00241 
00242 /* Initializes preallocated CvMatND header */
00243 CVAPI(CvMatND*)  cvInitMatNDHeader( CvMatND* mat, int dims, const int* sizes,
00244                                     int type, void* data CV_DEFAULT(NULL) );
00245 
00246 /* Releases CvMatND */
00247 CV_INLINE  void  cvReleaseMatND( CvMatND** mat )
00248 {
00249     cvReleaseMat( (CvMat**)mat );
00250 }
00251 
00252 /* Creates a copy of CvMatND (except, may be, steps) */
00253 CVAPI(CvMatND*) cvCloneMatND( const CvMatND* mat );
00254 
00255 /* Allocates and initializes CvSparseMat header and allocates data */
00256 CVAPI(CvSparseMat*)  cvCreateSparseMat( int dims, const int* sizes, int type );
00257 
00258 /* Releases CvSparseMat */
00259 CVAPI(void)  cvReleaseSparseMat( CvSparseMat** mat );
00260 
00261 /* Creates a copy of CvSparseMat (except, may be, zero items) */
00262 CVAPI(CvSparseMat*) cvCloneSparseMat( const CvSparseMat* mat );
00263 
00264 /* Initializes sparse array iterator
00265    (returns the first node or NULL if the array is empty) */
00266 CVAPI(CvSparseNode*) cvInitSparseMatIterator( const CvSparseMat* mat,
00267                                               CvSparseMatIterator* mat_iterator );
00268 
00269 // returns next sparse array node (or NULL if there is no more nodes)
00270 CV_INLINE CvSparseNode* cvGetNextSparseNode( CvSparseMatIterator* mat_iterator )
00271 {
00272     if( mat_iterator->node->next )
00273         return mat_iterator->node = mat_iterator->node->next;
00274     else
00275     {
00276         int idx;
00277         for( idx = ++mat_iterator->curidx; idx < mat_iterator->mat->hashsize; idx++ )
00278         {
00279             CvSparseNode* node = (CvSparseNode*)mat_iterator->mat->hashtable[idx];
00280             if( node )
00281             {
00282                 mat_iterator->curidx = idx;
00283                 return mat_iterator->node = node;
00284             }
00285         }
00286         return NULL;
00287     }
00288 }
00289 
00290 /**************** matrix iterator: used for n-ary operations on dense arrays *********/
00291 
00292 #define CV_MAX_ARR 10
00293 
00294 typedef struct CvNArrayIterator
00295 {
00296     int count; /* number of arrays */
00297     int dims; /* number of dimensions to iterate */
00298     CvSize size; /* maximal common linear size: { width = size, height = 1 } */
00299     uchar* ptr[CV_MAX_ARR]; /* pointers to the array slices */
00300     int stack[CV_MAX_DIM]; /* for internal use */
00301     CvMatND* hdr[CV_MAX_ARR]; /* pointers to the headers of the
00302                                  matrices that are processed */
00303 }
00304 CvNArrayIterator;
00305 
00306 #define CV_NO_DEPTH_CHECK     1
00307 #define CV_NO_CN_CHECK        2
00308 #define CV_NO_SIZE_CHECK      4
00309 
00310 /* initializes iterator that traverses through several arrays simulteneously
00311    (the function together with cvNextArraySlice is used for
00312     N-ari element-wise operations) */
00313 CVAPI(int) cvInitNArrayIterator( int count, CvArr** arrs,
00314                                  const CvArr* mask, CvMatND* stubs,
00315                                  CvNArrayIterator* array_iterator,
00316                                  int flags CV_DEFAULT(0) );
00317 
00318 /* returns zero value if iteration is finished, non-zero (slice length) otherwise */
00319 CVAPI(int) cvNextNArraySlice( CvNArrayIterator* array_iterator );
00320 
00321 
00322 /* Returns type of array elements:
00323    CV_8UC1 ... CV_64FC4 ... */
00324 CVAPI(int) cvGetElemType( const CvArr* arr );
00325 
00326 /* Retrieves number of an array dimensions and
00327    optionally sizes of the dimensions */
00328 CVAPI(int) cvGetDims( const CvArr* arr, int* sizes CV_DEFAULT(NULL) );
00329 
00330 
00331 /* Retrieves size of a particular array dimension.
00332    For 2d arrays cvGetDimSize(arr,0) returns number of rows (image height)
00333    and cvGetDimSize(arr,1) returns number of columns (image width) */
00334 CVAPI(int) cvGetDimSize( const CvArr* arr, int index );
00335 
00336 
00337 /* ptr = &arr(idx0,idx1,...). All indexes are zero-based,
00338    the major dimensions go first (e.g. (y,x) for 2D, (z,y,x) for 3D */
00339 CVAPI(uchar*) cvPtr1D( const CvArr* arr, int idx0, int* type CV_DEFAULT(NULL));
00340 CVAPI(uchar*) cvPtr2D( const CvArr* arr, int idx0, int idx1, int* type CV_DEFAULT(NULL) );
00341 CVAPI(uchar*) cvPtr3D( const CvArr* arr, int idx0, int idx1, int idx2,
00342                       int* type CV_DEFAULT(NULL));
00343 
00344 /* For CvMat or IplImage number of indices should be 2
00345    (row index (y) goes first, column index (x) goes next).
00346    For CvMatND or CvSparseMat number of infices should match number of <dims> and
00347    indices order should match the array dimension order. */
00348 CVAPI(uchar*) cvPtrND( const CvArr* arr, const int* idx, int* type CV_DEFAULT(NULL),
00349                       int create_node CV_DEFAULT(1),
00350                       unsigned* precalc_hashval CV_DEFAULT(NULL));
00351 
00352 /* value = arr(idx0,idx1,...) */
00353 CVAPI(CvScalar) cvGet1D( const CvArr* arr, int idx0 );
00354 CVAPI(CvScalar) cvGet2D( const CvArr* arr, int idx0, int idx1 );
00355 CVAPI(CvScalar) cvGet3D( const CvArr* arr, int idx0, int idx1, int idx2 );
00356 CVAPI(CvScalar) cvGetND( const CvArr* arr, const int* idx );
00357 
00358 /* for 1-channel arrays */
00359 CVAPI(double) cvGetReal1D( const CvArr* arr, int idx0 );
00360 CVAPI(double) cvGetReal2D( const CvArr* arr, int idx0, int idx1 );
00361 CVAPI(double) cvGetReal3D( const CvArr* arr, int idx0, int idx1, int idx2 );
00362 CVAPI(double) cvGetRealND( const CvArr* arr, const int* idx );
00363 
00364 /* arr(idx0,idx1,...) = value */
00365 CVAPI(void) cvSet1D( CvArr* arr, int idx0, CvScalar value );
00366 CVAPI(void) cvSet2D( CvArr* arr, int idx0, int idx1, CvScalar value );
00367 CVAPI(void) cvSet3D( CvArr* arr, int idx0, int idx1, int idx2, CvScalar value );
00368 CVAPI(void) cvSetND( CvArr* arr, const int* idx, CvScalar value );
00369 
00370 /* for 1-channel arrays */
00371 CVAPI(void) cvSetReal1D( CvArr* arr, int idx0, double value );
00372 CVAPI(void) cvSetReal2D( CvArr* arr, int idx0, int idx1, double value );
00373 CVAPI(void) cvSetReal3D( CvArr* arr, int idx0,
00374                         int idx1, int idx2, double value );
00375 CVAPI(void) cvSetRealND( CvArr* arr, const int* idx, double value );
00376 
00377 /* clears element of ND dense array,
00378    in case of sparse arrays it deletes the specified node */
00379 CVAPI(void) cvClearND( CvArr* arr, const int* idx );
00380 
00381 /* Converts CvArr (IplImage or CvMat,...) to CvMat.
00382    If the last parameter is non-zero, function can
00383    convert multi(>2)-dimensional array to CvMat as long as
00384    the last array's dimension is continous. The resultant
00385    matrix will be have appropriate (a huge) number of rows */
00386 CVAPI(CvMat*) cvGetMat( const CvArr* arr, CvMat* header,
00387                        int* coi CV_DEFAULT(NULL),
00388                        int allowND CV_DEFAULT(0));
00389 
00390 /* Converts CvArr (IplImage or CvMat) to IplImage */
00391 CVAPI(IplImage*) cvGetImage( const CvArr* arr, IplImage* image_header );
00392 
00393 
00394 /* Changes a shape of multi-dimensional array.
00395    new_cn == 0 means that number of channels remains unchanged.
00396    new_dims == 0 means that number and sizes of dimensions remain the same
00397    (unless they need to be changed to set the new number of channels)
00398    if new_dims == 1, there is no need to specify new dimension sizes
00399    The resultant configuration should be achievable w/o data copying.
00400    If the resultant array is sparse, CvSparseMat header should be passed
00401    to the function else if the result is 1 or 2 dimensional,
00402    CvMat header should be passed to the function
00403    else CvMatND header should be passed */
00404 CVAPI(CvArr*) cvReshapeMatND( const CvArr* arr,
00405                              int sizeof_header, CvArr* header,
00406                              int new_cn, int new_dims, int* new_sizes );
00407 
00408 #define cvReshapeND( arr, header, new_cn, new_dims, new_sizes )   \
00409       cvReshapeMatND( (arr), sizeof(*(header)), (header),         \
00410                       (new_cn), (new_dims), (new_sizes))
00411 
00412 CVAPI(CvMat*) cvReshape( const CvArr* arr, CvMat* header,
00413                         int new_cn, int new_rows CV_DEFAULT(0) );
00414 
00415 /* Repeats source 2d array several times in both horizontal and
00416    vertical direction to fill destination array */
00417 CVAPI(void) cvRepeat( const CvArr* src, CvArr* dst );
00418 
00419 /* Allocates array data */
00420 CVAPI(void)  cvCreateData( CvArr* arr );
00421 
00422 /* Releases array data */
00423 CVAPI(void)  cvReleaseData( CvArr* arr );
00424 
00425 /* Attaches user data to the array header. The step is reffered to
00426    the pre-last dimension. That is, all the planes of the array
00427    must be joint (w/o gaps) */
00428 CVAPI(void)  cvSetData( CvArr* arr, void* data, int step );
00429 
00430 /* Retrieves raw data of CvMat, IplImage or CvMatND.
00431    In the latter case the function raises an error if
00432    the array can not be represented as a matrix */
00433 CVAPI(void) cvGetRawData( const CvArr* arr, uchar** data,
00434                          int* step CV_DEFAULT(NULL),
00435                          CvSize* roi_size CV_DEFAULT(NULL));
00436 
00437 /* Returns width and height of array in elements */
00438 CVAPI(CvSize) cvGetSize( const CvArr* arr );
00439 
00440 /* Copies source array to destination array */
00441 CVAPI(void)  cvCopy( const CvArr* src, CvArr* dst,
00442                      const CvArr* mask CV_DEFAULT(NULL) );
00443 
00444 /* Sets all or "masked" elements of input array
00445    to the same value*/
00446 CVAPI(void)  cvSet( CvArr* arr, CvScalar value,
00447                     const CvArr* mask CV_DEFAULT(NULL) );
00448 
00449 /* Clears all the array elements (sets them to 0) */
00450 CVAPI(void)  cvSetZero( CvArr* arr );
00451 #define cvZero  cvSetZero
00452 
00453 
00454 /* Splits a multi-channel array into the set of single-channel arrays or
00455    extracts particular [color] plane */
00456 CVAPI(void)  cvSplit( const CvArr* src, CvArr* dst0, CvArr* dst1,
00457                       CvArr* dst2, CvArr* dst3 );
00458 
00459 /* Merges a set of single-channel arrays into the single multi-channel array
00460    or inserts one particular [color] plane to the array */
00461 CVAPI(void)  cvMerge( const CvArr* src0, const CvArr* src1,
00462                       const CvArr* src2, const CvArr* src3,
00463                       CvArr* dst );
00464 
00465 /* Copies several channels from input arrays to
00466    certain channels of output arrays */
00467 CVAPI(void)  cvMixChannels( const CvArr** src, int src_count,
00468                             CvArr** dst, int dst_count,
00469                             const int* from_to, int pair_count );
00470 
00471 /* Performs linear transformation on every source array element:
00472    dst(x,y,c) = scale*src(x,y,c)+shift.
00473    Arbitrary combination of input and output array depths are allowed
00474    (number of channels must be the same), thus the function can be used
00475    for type conversion */
00476 CVAPI(void)  cvConvertScale( const CvArr* src, CvArr* dst,
00477                              double scale CV_DEFAULT(1),
00478                              double shift CV_DEFAULT(0) );
00479 #define cvCvtScale cvConvertScale
00480 #define cvScale  cvConvertScale
00481 #define cvConvert( src, dst )  cvConvertScale( (src), (dst), 1, 0 )
00482 
00483 
00484 /* Performs linear transformation on every source array element,
00485    stores absolute value of the result:
00486    dst(x,y,c) = abs(scale*src(x,y,c)+shift).
00487    destination array must have 8u type.
00488    In other cases one may use cvConvertScale + cvAbsDiffS */
00489 CVAPI(void)  cvConvertScaleAbs( const CvArr* src, CvArr* dst,
00490                                 double scale CV_DEFAULT(1),
00491                                 double shift CV_DEFAULT(0) );
00492 #define cvCvtScaleAbs  cvConvertScaleAbs
00493 
00494 
00495 /* checks termination criteria validity and
00496    sets eps to default_eps (if it is not set),
00497    max_iter to default_max_iters (if it is not set)
00498 */
00499 CVAPI(CvTermCriteria) cvCheckTermCriteria( CvTermCriteria criteria,
00500                                            double default_eps,
00501                                            int default_max_iters );
00502 
00503 /****************************************************************************************\
00504 *                   Arithmetic, logic and comparison operations                          *
00505 \****************************************************************************************/
00506 
00507 /* dst(mask) = src1(mask) + src2(mask) */
00508 CVAPI(void)  cvAdd( const CvArr* src1, const CvArr* src2, CvArr* dst,
00509                     const CvArr* mask CV_DEFAULT(NULL));
00510 
00511 /* dst(mask) = src(mask) + value */
00512 CVAPI(void)  cvAddS( const CvArr* src, CvScalar value, CvArr* dst,
00513                      const CvArr* mask CV_DEFAULT(NULL));
00514 
00515 /* dst(mask) = src1(mask) - src2(mask) */
00516 CVAPI(void)  cvSub( const CvArr* src1, const CvArr* src2, CvArr* dst,
00517                     const CvArr* mask CV_DEFAULT(NULL));
00518 
00519 /* dst(mask) = src(mask) - value = src(mask) + (-value) */
00520 CV_INLINE  void  cvSubS( const CvArr* src, CvScalar value, CvArr* dst,
00521                          const CvArr* mask CV_DEFAULT(NULL))
00522 {
00523     cvAddS( src, cvScalar( -value.val[0], -value.val[1], -value.val[2], -value.val[3]),
00524             dst, mask );
00525 }
00526 
00527 /* dst(mask) = value - src(mask) */
00528 CVAPI(void)  cvSubRS( const CvArr* src, CvScalar value, CvArr* dst,
00529                       const CvArr* mask CV_DEFAULT(NULL));
00530 
00531 /* dst(idx) = src1(idx) * src2(idx) * scale
00532    (scaled element-wise multiplication of 2 arrays) */
00533 CVAPI(void)  cvMul( const CvArr* src1, const CvArr* src2,
00534                     CvArr* dst, double scale CV_DEFAULT(1) );
00535 
00536 /* element-wise division/inversion with scaling:
00537     dst(idx) = src1(idx) * scale / src2(idx)
00538     or dst(idx) = scale / src2(idx) if src1 == 0 */
00539 CVAPI(void)  cvDiv( const CvArr* src1, const CvArr* src2,
00540                     CvArr* dst, double scale CV_DEFAULT(1));
00541 
00542 /* dst = src1 * scale + src2 */
00543 CVAPI(void)  cvScaleAdd( const CvArr* src1, CvScalar scale,
00544                          const CvArr* src2, CvArr* dst );
00545 #define cvAXPY( A, real_scalar, B, C ) cvScaleAdd(A, cvRealScalar(real_scalar), B, C)
00546 
00547 /* dst = src1 * alpha + src2 * beta + gamma */
00548 CVAPI(void)  cvAddWeighted( const CvArr* src1, double alpha,
00549                             const CvArr* src2, double beta,
00550                             double gamma, CvArr* dst );
00551 
00552 /* result = sum_i(src1(i) * src2(i)) (results for all channels are accumulated together) */
00553 CVAPI(double)  cvDotProduct( const CvArr* src1, const CvArr* src2 );
00554 
00555 /* dst(idx) = src1(idx) & src2(idx) */
00556 CVAPI(void) cvAnd( const CvArr* src1, const CvArr* src2,
00557                   CvArr* dst, const CvArr* mask CV_DEFAULT(NULL));
00558 
00559 /* dst(idx) = src(idx) & value */
00560 CVAPI(void) cvAndS( const CvArr* src, CvScalar value,
00561                    CvArr* dst, const CvArr* mask CV_DEFAULT(NULL));
00562 
00563 /* dst(idx) = src1(idx) | src2(idx) */
00564 CVAPI(void) cvOr( const CvArr* src1, const CvArr* src2,
00565                  CvArr* dst, const CvArr* mask CV_DEFAULT(NULL));
00566 
00567 /* dst(idx) = src(idx) | value */
00568 CVAPI(void) cvOrS( const CvArr* src, CvScalar value,
00569                   CvArr* dst, const CvArr* mask CV_DEFAULT(NULL));
00570 
00571 /* dst(idx) = src1(idx) ^ src2(idx) */
00572 CVAPI(void) cvXor( const CvArr* src1, const CvArr* src2,
00573                   CvArr* dst, const CvArr* mask CV_DEFAULT(NULL));
00574 
00575 /* dst(idx) = src(idx) ^ value */
00576 CVAPI(void) cvXorS( const CvArr* src, CvScalar value,
00577                    CvArr* dst, const CvArr* mask CV_DEFAULT(NULL));
00578 
00579 /* dst(idx) = ~src(idx) */
00580 CVAPI(void) cvNot( const CvArr* src, CvArr* dst );
00581 
00582 /* dst(idx) = lower(idx) <= src(idx) < upper(idx) */
00583 CVAPI(void) cvInRange( const CvArr* src, const CvArr* lower,
00584                       const CvArr* upper, CvArr* dst );
00585 
00586 /* dst(idx) = lower <= src(idx) < upper */
00587 CVAPI(void) cvInRangeS( const CvArr* src, CvScalar lower,
00588                        CvScalar upper, CvArr* dst );
00589 
00590 #define CV_CMP_EQ   0
00591 #define CV_CMP_GT   1
00592 #define CV_CMP_GE   2
00593 #define CV_CMP_LT   3
00594 #define CV_CMP_LE   4
00595 #define CV_CMP_NE   5
00596 
00597 /* The comparison operation support single-channel arrays only.
00598    Destination image should be 8uC1 or 8sC1 */
00599 
00600 /* dst(idx) = src1(idx) _cmp_op_ src2(idx) */
00601 CVAPI(void) cvCmp( const CvArr* src1, const CvArr* src2, CvArr* dst, int cmp_op );
00602 
00603 /* dst(idx) = src1(idx) _cmp_op_ value */
00604 CVAPI(void) cvCmpS( const CvArr* src, double value, CvArr* dst, int cmp_op );
00605 
00606 /* dst(idx) = min(src1(idx),src2(idx)) */
00607 CVAPI(void) cvMin( const CvArr* src1, const CvArr* src2, CvArr* dst );
00608 
00609 /* dst(idx) = max(src1(idx),src2(idx)) */
00610 CVAPI(void) cvMax( const CvArr* src1, const CvArr* src2, CvArr* dst );
00611 
00612 /* dst(idx) = min(src(idx),value) */
00613 CVAPI(void) cvMinS( const CvArr* src, double value, CvArr* dst );
00614 
00615 /* dst(idx) = max(src(idx),value) */
00616 CVAPI(void) cvMaxS( const CvArr* src, double value, CvArr* dst );
00617 
00618 /* dst(x,y,c) = abs(src1(x,y,c) - src2(x,y,c)) */
00619 CVAPI(void) cvAbsDiff( const CvArr* src1, const CvArr* src2, CvArr* dst );
00620 
00621 /* dst(x,y,c) = abs(src(x,y,c) - value(c)) */
00622 CVAPI(void) cvAbsDiffS( const CvArr* src, CvArr* dst, CvScalar value );
00623 #define cvAbs( src, dst ) cvAbsDiffS( (src), (dst), cvScalarAll(0))
00624 
00625 /****************************************************************************************\
00626 *                                Math operations                                         *
00627 \****************************************************************************************/
00628 
00629 /* Does cartesian->polar coordinates conversion.
00630    Either of output components (magnitude or angle) is optional */
00631 CVAPI(void)  cvCartToPolar( const CvArr* x, const CvArr* y,
00632                             CvArr* magnitude, CvArr* angle CV_DEFAULT(NULL),
00633                             int angle_in_degrees CV_DEFAULT(0));
00634 
00635 /* Does polar->cartesian coordinates conversion.
00636    Either of output components (magnitude or angle) is optional.
00637    If magnitude is missing it is assumed to be all 1's */
00638 CVAPI(void)  cvPolarToCart( const CvArr* magnitude, const CvArr* angle,
00639                             CvArr* x, CvArr* y,
00640                             int angle_in_degrees CV_DEFAULT(0));
00641 
00642 /* Does powering: dst(idx) = src(idx)^power */
00643 CVAPI(void)  cvPow( const CvArr* src, CvArr* dst, double power );
00644 
00645 /* Does exponention: dst(idx) = exp(src(idx)).
00646    Overflow is not handled yet. Underflow is handled.
00647    Maximal relative error is ~7e-6 for single-precision input */
00648 CVAPI(void)  cvExp( const CvArr* src, CvArr* dst );
00649 
00650 /* Calculates natural logarithms: dst(idx) = log(abs(src(idx))).
00651    Logarithm of 0 gives large negative number(~-700)
00652    Maximal relative error is ~3e-7 for single-precision output
00653 */
00654 CVAPI(void)  cvLog( const CvArr* src, CvArr* dst );
00655 
00656 /* Fast arctangent calculation */
00657 CVAPI(float) cvFastArctan( float y, float x );
00658 
00659 /* Fast cubic root calculation */
00660 CVAPI(float)  cvCbrt( float value );
00661 
00662 /* Checks array values for NaNs, Infs or simply for too large numbers
00663    (if CV_CHECK_RANGE is set). If CV_CHECK_QUIET is set,
00664    no runtime errors is raised (function returns zero value in case of "bad" values).
00665    Otherwise cvError is called */
00666 #define  CV_CHECK_RANGE    1
00667 #define  CV_CHECK_QUIET    2
00668 CVAPI(int)  cvCheckArr( const CvArr* arr, int flags CV_DEFAULT(0),
00669                         double min_val CV_DEFAULT(0), double max_val CV_DEFAULT(0));
00670 #define cvCheckArray cvCheckArr
00671 
00672 #define CV_RAND_UNI      0
00673 #define CV_RAND_NORMAL   1
00674 CVAPI(void) cvRandArr( CvRNG* rng, CvArr* arr, int dist_type,
00675                       CvScalar param1, CvScalar param2 );
00676 
00677 CVAPI(void) cvRandShuffle( CvArr* mat, CvRNG* rng,
00678                            double iter_factor CV_DEFAULT(1.));
00679 
00680 #define CV_SORT_EVERY_ROW 0
00681 #define CV_SORT_EVERY_COLUMN 1
00682 #define CV_SORT_ASCENDING 0
00683 #define CV_SORT_DESCENDING 16
00684 
00685 CVAPI(void) cvSort( const CvArr* src, CvArr* dst CV_DEFAULT(NULL),
00686                     CvArr* idxmat CV_DEFAULT(NULL),
00687                     int flags CV_DEFAULT(0));
00688 
00689 /* Finds real roots of a cubic equation */
00690 CVAPI(int) cvSolveCubic( const CvMat* coeffs, CvMat* roots );
00691 
00692 /* Finds all real and complex roots of a polynomial equation */
00693 CVAPI(void) cvSolvePoly(const CvMat* coeffs, CvMat *roots2,
00694             int maxiter CV_DEFAULT(20), int fig CV_DEFAULT(100));
00695 
00696 /****************************************************************************************\
00697 *                                Matrix operations                                       *
00698 \****************************************************************************************/
00699 
00700 /* Calculates cross product of two 3d vectors */
00701 CVAPI(void)  cvCrossProduct( const CvArr* src1, const CvArr* src2, CvArr* dst );
00702 
00703 /* Matrix transform: dst = A*B + C, C is optional */
00704 #define cvMatMulAdd( src1, src2, src3, dst ) cvGEMM( (src1), (src2), 1., (src3), 1., (dst), 0 )
00705 #define cvMatMul( src1, src2, dst )  cvMatMulAdd( (src1), (src2), NULL, (dst))
00706 
00707 #define CV_GEMM_A_T 1
00708 #define CV_GEMM_B_T 2
00709 #define CV_GEMM_C_T 4
00710 /* Extended matrix transform:
00711    dst = alpha*op(A)*op(B) + beta*op(C), where op(X) is X or X^T */
00712 CVAPI(void)  cvGEMM( const CvArr* src1, const CvArr* src2, double alpha,
00713                      const CvArr* src3, double beta, CvArr* dst,
00714                      int tABC CV_DEFAULT(0));
00715 #define cvMatMulAddEx cvGEMM
00716 
00717 /* Transforms each element of source array and stores
00718    resultant vectors in destination array */
00719 CVAPI(void)  cvTransform( const CvArr* src, CvArr* dst,
00720                           const CvMat* transmat,
00721                           const CvMat* shiftvec CV_DEFAULT(NULL));
00722 #define cvMatMulAddS cvTransform
00723 
00724 /* Does perspective transform on every element of input array */
00725 CVAPI(void)  cvPerspectiveTransform( const CvArr* src, CvArr* dst,
00726                                      const CvMat* mat );
00727 
00728 /* Calculates (A-delta)*(A-delta)^T (order=0) or (A-delta)^T*(A-delta) (order=1) */
00729 CVAPI(void) cvMulTransposed( const CvArr* src, CvArr* dst, int order,
00730                              const CvArr* delta CV_DEFAULT(NULL),
00731                              double scale CV_DEFAULT(1.) );
00732 
00733 /* Tranposes matrix. Square matrices can be transposed in-place */
00734 CVAPI(void)  cvTranspose( const CvArr* src, CvArr* dst );
00735 #define cvT cvTranspose
00736 
00737 /* Completes the symmetric matrix from the lower (LtoR=0) or from the upper (LtoR!=0) part */
00738 CVAPI(void)  cvCompleteSymm( CvMat* matrix, int LtoR CV_DEFAULT(0) );
00739 
00740 /* Mirror array data around horizontal (flip=0),
00741    vertical (flip=1) or both(flip=-1) axises:
00742    cvFlip(src) flips images vertically and sequences horizontally (inplace) */
00743 CVAPI(void)  cvFlip( const CvArr* src, CvArr* dst CV_DEFAULT(NULL),
00744                      int flip_mode CV_DEFAULT(0));
00745 #define cvMirror cvFlip
00746 
00747 
00748 #define CV_SVD_MODIFY_A   1
00749 #define CV_SVD_U_T        2
00750 #define CV_SVD_V_T        4
00751 
00752 /* Performs Singular Value Decomposition of a matrix */
00753 CVAPI(void)   cvSVD( CvArr* A, CvArr* W, CvArr* U CV_DEFAULT(NULL),
00754                      CvArr* V CV_DEFAULT(NULL), int flags CV_DEFAULT(0));
00755 
00756 /* Performs Singular Value Back Substitution (solves A*X = B):
00757    flags must be the same as in cvSVD */
00758 CVAPI(void)   cvSVBkSb( const CvArr* W, const CvArr* U,
00759                         const CvArr* V, const CvArr* B,
00760                         CvArr* X, int flags );
00761 
00762 #define CV_LU  0
00763 #define CV_SVD 1
00764 #define CV_SVD_SYM 2
00765 #define CV_CHOLESKY 3
00766 #define CV_QR  4
00767 #define CV_NORMAL 16
00768 
00769 /* Inverts matrix */
00770 CVAPI(double)  cvInvert( const CvArr* src, CvArr* dst,
00771                          int method CV_DEFAULT(CV_LU));
00772 #define cvInv cvInvert
00773 
00774 /* Solves linear system (src1)*(dst) = (src2)
00775    (returns 0 if src1 is a singular and CV_LU method is used) */
00776 CVAPI(int)  cvSolve( const CvArr* src1, const CvArr* src2, CvArr* dst,
00777                      int method CV_DEFAULT(CV_LU));
00778 
00779 /* Calculates determinant of input matrix */
00780 CVAPI(double) cvDet( const CvArr* mat );
00781 
00782 /* Calculates trace of the matrix (sum of elements on the main diagonal) */
00783 CVAPI(CvScalar) cvTrace( const CvArr* mat );
00784 
00785 /* Finds eigen values and vectors of a symmetric matrix */
00786 CVAPI(void)  cvEigenVV( CvArr* mat, CvArr* evects, CvArr* evals,
00787                         double eps CV_DEFAULT(0),
00788                         int lowindex CV_DEFAULT(-1),
00789                         int highindex CV_DEFAULT(-1));
00790 
00792 //CVAPI(void)  cvSelectedEigenVV( CvArr* mat, CvArr* evects, CvArr* evals,
00793 //                                int lowindex, int highindex );
00794 
00795 /* Makes an identity matrix (mat_ij = i == j) */
00796 CVAPI(void)  cvSetIdentity( CvArr* mat, CvScalar value CV_DEFAULT(cvRealScalar(1)) );
00797 
00798 /* Fills matrix with given range of numbers */
00799 CVAPI(CvArr*)  cvRange( CvArr* mat, double start, double end );
00800 
00801 /* Calculates covariation matrix for a set of vectors */
00802 /* transpose([v1-avg, v2-avg,...]) * [v1-avg,v2-avg,...] */
00803 #define CV_COVAR_SCRAMBLED 0
00804 
00805 /* [v1-avg, v2-avg,...] * transpose([v1-avg,v2-avg,...]) */
00806 #define CV_COVAR_NORMAL    1
00807 
00808 /* do not calc average (i.e. mean vector) - use the input vector instead
00809    (useful for calculating covariance matrix by parts) */
00810 #define CV_COVAR_USE_AVG   2
00811 
00812 /* scale the covariance matrix coefficients by number of the vectors */
00813 #define CV_COVAR_SCALE     4
00814 
00815 /* all the input vectors are stored in a single matrix, as its rows */
00816 #define CV_COVAR_ROWS      8
00817 
00818 /* all the input vectors are stored in a single matrix, as its columns */
00819 #define CV_COVAR_COLS     16
00820 
00821 CVAPI(void)  cvCalcCovarMatrix( const CvArr** vects, int count,
00822                                 CvArr* cov_mat, CvArr* avg, int flags );
00823 
00824 #define CV_PCA_DATA_AS_ROW 0
00825 #define CV_PCA_DATA_AS_COL 1
00826 #define CV_PCA_USE_AVG 2
00827 CVAPI(void)  cvCalcPCA( const CvArr* data, CvArr* mean,
00828                         CvArr* eigenvals, CvArr* eigenvects, int flags );
00829 
00830 CVAPI(void)  cvProjectPCA( const CvArr* data, const CvArr* mean,
00831                            const CvArr* eigenvects, CvArr* result );
00832 
00833 CVAPI(void)  cvBackProjectPCA( const CvArr* proj, const CvArr* mean,
00834                                const CvArr* eigenvects, CvArr* result );
00835 
00836 /* Calculates Mahalanobis(weighted) distance */
00837 CVAPI(double)  cvMahalanobis( const CvArr* vec1, const CvArr* vec2, const CvArr* mat );
00838 #define cvMahalonobis  cvMahalanobis
00839 
00840 /****************************************************************************************\
00841 *                                    Array Statistics                                    *
00842 \****************************************************************************************/
00843 
00844 /* Finds sum of array elements */
00845 CVAPI(CvScalar)  cvSum( const CvArr* arr );
00846 
00847 /* Calculates number of non-zero pixels */
00848 CVAPI(int)  cvCountNonZero( const CvArr* arr );
00849 
00850 /* Calculates mean value of array elements */
00851 CVAPI(CvScalar)  cvAvg( const CvArr* arr, const CvArr* mask CV_DEFAULT(NULL) );
00852 
00853 /* Calculates mean and standard deviation of pixel values */
00854 CVAPI(void)  cvAvgSdv( const CvArr* arr, CvScalar* mean, CvScalar* std_dev,
00855                        const CvArr* mask CV_DEFAULT(NULL) );
00856 
00857 /* Finds global minimum, maximum and their positions */
00858 CVAPI(void)  cvMinMaxLoc( const CvArr* arr, double* min_val, double* max_val,
00859                           CvPoint* min_loc CV_DEFAULT(NULL),
00860                           CvPoint* max_loc CV_DEFAULT(NULL),
00861                           const CvArr* mask CV_DEFAULT(NULL) );
00862 
00863 /* types of array norm */
00864 #define CV_C            1
00865 #define CV_L1           2
00866 #define CV_L2           4
00867 #define CV_NORM_MASK    7
00868 #define CV_RELATIVE     8
00869 #define CV_DIFF         16
00870 #define CV_MINMAX       32
00871 
00872 #define CV_DIFF_C       (CV_DIFF | CV_C)
00873 #define CV_DIFF_L1      (CV_DIFF | CV_L1)
00874 #define CV_DIFF_L2      (CV_DIFF | CV_L2)
00875 #define CV_RELATIVE_C   (CV_RELATIVE | CV_C)
00876 #define CV_RELATIVE_L1  (CV_RELATIVE | CV_L1)
00877 #define CV_RELATIVE_L2  (CV_RELATIVE | CV_L2)
00878 
00879 /* Finds norm, difference norm or relative difference norm for an array (or two arrays) */
00880 CVAPI(double)  cvNorm( const CvArr* arr1, const CvArr* arr2 CV_DEFAULT(NULL),
00881                        int norm_type CV_DEFAULT(CV_L2),
00882                        const CvArr* mask CV_DEFAULT(NULL) );
00883 
00884 CVAPI(void)  cvNormalize( const CvArr* src, CvArr* dst,
00885                           double a CV_DEFAULT(1.), double b CV_DEFAULT(0.),
00886                           int norm_type CV_DEFAULT(CV_L2),
00887                           const CvArr* mask CV_DEFAULT(NULL) );
00888 
00889 
00890 #define CV_REDUCE_SUM 0
00891 #define CV_REDUCE_AVG 1
00892 #define CV_REDUCE_MAX 2
00893 #define CV_REDUCE_MIN 3
00894 
00895 CVAPI(void)  cvReduce( const CvArr* src, CvArr* dst, int dim CV_DEFAULT(-1),
00896                        int op CV_DEFAULT(CV_REDUCE_SUM) );
00897 
00898 /****************************************************************************************\
00899 *                      Discrete Linear Transforms and Related Functions                  *
00900 \****************************************************************************************/
00901 
00902 #define CV_DXT_FORWARD  0
00903 #define CV_DXT_INVERSE  1
00904 #define CV_DXT_SCALE    2 /* divide result by size of array */
00905 #define CV_DXT_INV_SCALE (CV_DXT_INVERSE + CV_DXT_SCALE)
00906 #define CV_DXT_INVERSE_SCALE CV_DXT_INV_SCALE
00907 #define CV_DXT_ROWS     4 /* transform each row individually */
00908 #define CV_DXT_MUL_CONJ 8 /* conjugate the second argument of cvMulSpectrums */
00909 
00910 /* Discrete Fourier Transform:
00911     complex->complex,
00912     real->ccs (forward),
00913     ccs->real (inverse) */
00914 CVAPI(void)  cvDFT( const CvArr* src, CvArr* dst, int flags,
00915                     int nonzero_rows CV_DEFAULT(0) );
00916 #define cvFFT cvDFT
00917 
00918 /* Multiply results of DFTs: DFT(X)*DFT(Y) or DFT(X)*conj(DFT(Y)) */
00919 CVAPI(void)  cvMulSpectrums( const CvArr* src1, const CvArr* src2,
00920                              CvArr* dst, int flags );
00921 
00922 /* Finds optimal DFT vector size >= size0 */
00923 CVAPI(int)  cvGetOptimalDFTSize( int size0 );
00924 
00925 /* Discrete Cosine Transform */
00926 CVAPI(void)  cvDCT( const CvArr* src, CvArr* dst, int flags );
00927 
00928 /****************************************************************************************\
00929 *                              Dynamic data structures                                   *
00930 \****************************************************************************************/
00931 
00932 /* Calculates length of sequence slice (with support of negative indices). */
00933 CVAPI(int) cvSliceLength( CvSlice slice, const CvSeq* seq );
00934 
00935 
00936 /* Creates new memory storage.
00937    block_size == 0 means that default,
00938    somewhat optimal size, is used (currently, it is 64K) */
00939 CVAPI(CvMemStorage*)  cvCreateMemStorage( int block_size CV_DEFAULT(0));
00940 
00941 
00942 /* Creates a memory storage that will borrow memory blocks from parent storage */
00943 CVAPI(CvMemStorage*)  cvCreateChildMemStorage( CvMemStorage* parent );
00944 
00945 
00946 /* Releases memory storage. All the children of a parent must be released before
00947    the parent. A child storage returns all the blocks to parent when it is released */
00948 CVAPI(void)  cvReleaseMemStorage( CvMemStorage** storage );
00949 
00950 
00951 /* Clears memory storage. This is the only way(!!!) (besides cvRestoreMemStoragePos)
00952    to reuse memory allocated for the storage - cvClearSeq,cvClearSet ...
00953    do not free any memory.
00954    A child storage returns all the blocks to the parent when it is cleared */
00955 CVAPI(void)  cvClearMemStorage( CvMemStorage* storage );
00956 
00957 /* Remember a storage "free memory" position */
00958 CVAPI(void)  cvSaveMemStoragePos( const CvMemStorage* storage, CvMemStoragePos* pos );
00959 
00960 /* Restore a storage "free memory" position */
00961 CVAPI(void)  cvRestoreMemStoragePos( CvMemStorage* storage, CvMemStoragePos* pos );
00962 
00963 /* Allocates continuous buffer of the specified size in the storage */
00964 CVAPI(void*) cvMemStorageAlloc( CvMemStorage* storage, size_t size );
00965 
00966 /* Allocates string in memory storage */
00967 CVAPI(CvString) cvMemStorageAllocString( CvMemStorage* storage, const char* ptr,
00968                                         int len CV_DEFAULT(-1) );
00969 
00970 /* Creates new empty sequence that will reside in the specified storage */
00971 CVAPI(CvSeq*)  cvCreateSeq( int seq_flags, int header_size,
00972                             int elem_size, CvMemStorage* storage );
00973 
00974 /* Changes default size (granularity) of sequence blocks.
00975    The default size is ~1Kbyte */
00976 CVAPI(void)  cvSetSeqBlockSize( CvSeq* seq, int delta_elems );
00977 
00978 
00979 /* Adds new element to the end of sequence. Returns pointer to the element */
00980 CVAPI(schar*)  cvSeqPush( CvSeq* seq, const void* element CV_DEFAULT(NULL));
00981 
00982 
00983 /* Adds new element to the beginning of sequence. Returns pointer to it */
00984 CVAPI(schar*)  cvSeqPushFront( CvSeq* seq, const void* element CV_DEFAULT(NULL));
00985 
00986 
00987 /* Removes the last element from sequence and optionally saves it */
00988 CVAPI(void)  cvSeqPop( CvSeq* seq, void* element CV_DEFAULT(NULL));
00989 
00990 
00991 /* Removes the first element from sequence and optioanally saves it */
00992 CVAPI(void)  cvSeqPopFront( CvSeq* seq, void* element CV_DEFAULT(NULL));
00993 
00994 
00995 #define CV_FRONT 1
00996 #define CV_BACK 0
00997 /* Adds several new elements to the end of sequence */
00998 CVAPI(void)  cvSeqPushMulti( CvSeq* seq, const void* elements,
00999                              int count, int in_front CV_DEFAULT(0) );
01000 
01001 /* Removes several elements from the end of sequence and optionally saves them */
01002 CVAPI(void)  cvSeqPopMulti( CvSeq* seq, void* elements,
01003                             int count, int in_front CV_DEFAULT(0) );
01004 
01005 /* Inserts a new element in the middle of sequence.
01006    cvSeqInsert(seq,0,elem) == cvSeqPushFront(seq,elem) */
01007 CVAPI(schar*)  cvSeqInsert( CvSeq* seq, int before_index,
01008                             const void* element CV_DEFAULT(NULL));
01009 
01010 /* Removes specified sequence element */
01011 CVAPI(void)  cvSeqRemove( CvSeq* seq, int index );
01012 
01013 
01014 /* Removes all the elements from the sequence. The freed memory
01015    can be reused later only by the same sequence unless cvClearMemStorage
01016    or cvRestoreMemStoragePos is called */
01017 CVAPI(void)  cvClearSeq( CvSeq* seq );
01018 
01019 
01020 /* Retrieves pointer to specified sequence element.
01021    Negative indices are supported and mean counting from the end
01022    (e.g -1 means the last sequence element) */
01023 CVAPI(schar*)  cvGetSeqElem( const CvSeq* seq, int index );
01024 
01025 /* Calculates index of the specified sequence element.
01026    Returns -1 if element does not belong to the sequence */
01027 CVAPI(int)  cvSeqElemIdx( const CvSeq* seq, const void* element,
01028                          CvSeqBlock** block CV_DEFAULT(NULL) );
01029 
01030 /* Initializes sequence writer. The new elements will be added to the end of sequence */
01031 CVAPI(void)  cvStartAppendToSeq( CvSeq* seq, CvSeqWriter* writer );
01032 
01033 
01034 /* Combination of cvCreateSeq and cvStartAppendToSeq */
01035 CVAPI(void)  cvStartWriteSeq( int seq_flags, int header_size,
01036                               int elem_size, CvMemStorage* storage,
01037                               CvSeqWriter* writer );
01038 
01039 /* Closes sequence writer, updates sequence header and returns pointer
01040    to the resultant sequence
01041    (which may be useful if the sequence was created using cvStartWriteSeq))
01042 */
01043 CVAPI(CvSeq*)  cvEndWriteSeq( CvSeqWriter* writer );
01044 
01045 
01046 /* Updates sequence header. May be useful to get access to some of previously
01047    written elements via cvGetSeqElem or sequence reader */
01048 CVAPI(void)   cvFlushSeqWriter( CvSeqWriter* writer );
01049 
01050 
01051 /* Initializes sequence reader.
01052    The sequence can be read in forward or backward direction */
01053 CVAPI(void) cvStartReadSeq( const CvSeq* seq, CvSeqReader* reader,
01054                            int reverse CV_DEFAULT(0) );
01055 
01056 
01057 /* Returns current sequence reader position (currently observed sequence element) */
01058 CVAPI(int)  cvGetSeqReaderPos( CvSeqReader* reader );
01059 
01060 
01061 /* Changes sequence reader position. It may seek to an absolute or
01062    to relative to the current position */
01063 CVAPI(void)   cvSetSeqReaderPos( CvSeqReader* reader, int index,
01064                                  int is_relative CV_DEFAULT(0));
01065 
01066 /* Copies sequence content to a continuous piece of memory */
01067 CVAPI(void*)  cvCvtSeqToArray( const CvSeq* seq, void* elements,
01068                                CvSlice slice CV_DEFAULT(CV_WHOLE_SEQ) );
01069 
01070 /* Creates sequence header for array.
01071    After that all the operations on sequences that do not alter the content
01072    can be applied to the resultant sequence */
01073 CVAPI(CvSeq*) cvMakeSeqHeaderForArray( int seq_type, int header_size,
01074                                        int elem_size, void* elements, int total,
01075                                        CvSeq* seq, CvSeqBlock* block );
01076 
01077 /* Extracts sequence slice (with or without copying sequence elements) */
01078 CVAPI(CvSeq*) cvSeqSlice( const CvSeq* seq, CvSlice slice,
01079                          CvMemStorage* storage CV_DEFAULT(NULL),
01080                          int copy_data CV_DEFAULT(0));
01081 
01082 CV_INLINE CvSeq* cvCloneSeq( const CvSeq* seq, CvMemStorage* storage CV_DEFAULT(NULL))
01083 {
01084     return cvSeqSlice( seq, CV_WHOLE_SEQ, storage, 1 );
01085 }
01086 
01087 /* Removes sequence slice */
01088 CVAPI(void)  cvSeqRemoveSlice( CvSeq* seq, CvSlice slice );
01089 
01090 /* Inserts a sequence or array into another sequence */
01091 CVAPI(void)  cvSeqInsertSlice( CvSeq* seq, int before_index, const CvArr* from_arr );
01092 
01093 /* a < b ? -1 : a > b ? 1 : 0 */
01094 typedef int (CV_CDECL* CvCmpFunc)(const void* a, const void* b, void* userdata );
01095 
01096 /* Sorts sequence in-place given element comparison function */
01097 CVAPI(void) cvSeqSort( CvSeq* seq, CvCmpFunc func, void* userdata CV_DEFAULT(NULL) );
01098 
01099 /* Finds element in a [sorted] sequence */
01100 CVAPI(schar*) cvSeqSearch( CvSeq* seq, const void* elem, CvCmpFunc func,
01101                            int is_sorted, int* elem_idx,
01102                            void* userdata CV_DEFAULT(NULL) );
01103 
01104 /* Reverses order of sequence elements in-place */
01105 CVAPI(void) cvSeqInvert( CvSeq* seq );
01106 
01107 /* Splits sequence into one or more equivalence classes using the specified criteria */
01108 CVAPI(int)  cvSeqPartition( const CvSeq* seq, CvMemStorage* storage,
01109                             CvSeq** labels, CvCmpFunc is_equal, void* userdata );
01110 
01111 /************ Internal sequence functions ************/
01112 CVAPI(void)  cvChangeSeqBlock( void* reader, int direction );
01113 CVAPI(void)  cvCreateSeqBlock( CvSeqWriter* writer );
01114 
01115 
01116 /* Creates a new set */
01117 CVAPI(CvSet*)  cvCreateSet( int set_flags, int header_size,
01118                             int elem_size, CvMemStorage* storage );
01119 
01120 /* Adds new element to the set and returns pointer to it */
01121 CVAPI(int)  cvSetAdd( CvSet* set_header, CvSetElem* elem CV_DEFAULT(NULL),
01122                       CvSetElem** inserted_elem CV_DEFAULT(NULL) );
01123 
01124 /* Fast variant of cvSetAdd */
01125 CV_INLINE  CvSetElem* cvSetNew( CvSet* set_header )
01126 {
01127     CvSetElem* elem = set_header->free_elems;
01128     if( elem )
01129     {
01130         set_header->free_elems = elem->next_free;
01131         elem->flags = elem->flags & CV_SET_ELEM_IDX_MASK;
01132         set_header->active_count++;
01133     }
01134     else
01135         cvSetAdd( set_header, NULL, (CvSetElem**)&elem );
01136     return elem;
01137 }
01138 
01139 /* Removes set element given its pointer */
01140 CV_INLINE  void cvSetRemoveByPtr( CvSet* set_header, void* elem )
01141 {
01142     CvSetElem* _elem = (CvSetElem*)elem;
01143     assert( _elem->flags >= 0 /*&& (elem->flags & CV_SET_ELEM_IDX_MASK) < set_header->total*/ );
01144     _elem->next_free = set_header->free_elems;
01145     _elem->flags = (_elem->flags & CV_SET_ELEM_IDX_MASK) | CV_SET_ELEM_FREE_FLAG;
01146     set_header->free_elems = _elem;
01147     set_header->active_count--;
01148 }
01149 
01150 /* Removes element from the set by its index  */
01151 CVAPI(void)   cvSetRemove( CvSet* set_header, int index );
01152 
01153 /* Returns a set element by index. If the element doesn't belong to the set,
01154    NULL is returned */
01155 CV_INLINE CvSetElem* cvGetSetElem( const CvSet* set_header, int index )
01156 {
01157     CvSetElem* elem = (CvSetElem*)cvGetSeqElem( (CvSeq*)set_header, index );
01158     return elem && CV_IS_SET_ELEM( elem ) ? elem : 0;
01159 }
01160 
01161 /* Removes all the elements from the set */
01162 CVAPI(void)  cvClearSet( CvSet* set_header );
01163 
01164 /* Creates new graph */
01165 CVAPI(CvGraph*)  cvCreateGraph( int graph_flags, int header_size,
01166                                 int vtx_size, int edge_size,
01167                                 CvMemStorage* storage );
01168 
01169 /* Adds new vertex to the graph */
01170 CVAPI(int)  cvGraphAddVtx( CvGraph* graph, const CvGraphVtx* vtx CV_DEFAULT(NULL),
01171                            CvGraphVtx** inserted_vtx CV_DEFAULT(NULL) );
01172 
01173 
01174 /* Removes vertex from the graph together with all incident edges */
01175 CVAPI(int)  cvGraphRemoveVtx( CvGraph* graph, int index );
01176 CVAPI(int)  cvGraphRemoveVtxByPtr( CvGraph* graph, CvGraphVtx* vtx );
01177 
01178 
01179 /* Link two vertices specifed by indices or pointers if they
01180    are not connected or return pointer to already existing edge
01181    connecting the vertices.
01182    Functions return 1 if a new edge was created, 0 otherwise */
01183 CVAPI(int)  cvGraphAddEdge( CvGraph* graph,
01184                             int start_idx, int end_idx,
01185                             const CvGraphEdge* edge CV_DEFAULT(NULL),
01186                             CvGraphEdge** inserted_edge CV_DEFAULT(NULL) );
01187 
01188 CVAPI(int)  cvGraphAddEdgeByPtr( CvGraph* graph,
01189                                CvGraphVtx* start_vtx, CvGraphVtx* end_vtx,
01190                                const CvGraphEdge* edge CV_DEFAULT(NULL),
01191                                CvGraphEdge** inserted_edge CV_DEFAULT(NULL) );
01192 
01193 /* Remove edge connecting two vertices */
01194 CVAPI(void)  cvGraphRemoveEdge( CvGraph* graph, int start_idx, int end_idx );
01195 CVAPI(void)  cvGraphRemoveEdgeByPtr( CvGraph* graph, CvGraphVtx* start_vtx,
01196                                      CvGraphVtx* end_vtx );
01197 
01198 /* Find edge connecting two vertices */
01199 CVAPI(CvGraphEdge*)  cvFindGraphEdge( const CvGraph* graph, int start_idx, int end_idx );
01200 CVAPI(CvGraphEdge*)  cvFindGraphEdgeByPtr( const CvGraph* graph,
01201                                            const CvGraphVtx* start_vtx,
01202                                            const CvGraphVtx* end_vtx );
01203 #define cvGraphFindEdge cvFindGraphEdge
01204 #define cvGraphFindEdgeByPtr cvFindGraphEdgeByPtr
01205 
01206 /* Remove all vertices and edges from the graph */
01207 CVAPI(void)  cvClearGraph( CvGraph* graph );
01208 
01209 
01210 /* Count number of edges incident to the vertex */
01211 CVAPI(int)  cvGraphVtxDegree( const CvGraph* graph, int vtx_idx );
01212 CVAPI(int)  cvGraphVtxDegreeByPtr( const CvGraph* graph, const CvGraphVtx* vtx );
01213 
01214 
01215 /* Retrieves graph vertex by given index */
01216 #define cvGetGraphVtx( graph, idx ) (CvGraphVtx*)cvGetSetElem((CvSet*)(graph), (idx))
01217 
01218 /* Retrieves index of a graph vertex given its pointer */
01219 #define cvGraphVtxIdx( graph, vtx ) ((vtx)->flags & CV_SET_ELEM_IDX_MASK)
01220 
01221 /* Retrieves index of a graph edge given its pointer */
01222 #define cvGraphEdgeIdx( graph, edge ) ((edge)->flags & CV_SET_ELEM_IDX_MASK)
01223 
01224 #define cvGraphGetVtxCount( graph ) ((graph)->active_count)
01225 #define cvGraphGetEdgeCount( graph ) ((graph)->edges->active_count)
01226 
01227 #define  CV_GRAPH_VERTEX        1
01228 #define  CV_GRAPH_TREE_EDGE     2
01229 #define  CV_GRAPH_BACK_EDGE     4
01230 #define  CV_GRAPH_FORWARD_EDGE  8
01231 #define  CV_GRAPH_CROSS_EDGE    16
01232 #define  CV_GRAPH_ANY_EDGE      30
01233 #define  CV_GRAPH_NEW_TREE      32
01234 #define  CV_GRAPH_BACKTRACKING  64
01235 #define  CV_GRAPH_OVER          -1
01236 
01237 #define  CV_GRAPH_ALL_ITEMS    -1
01238 
01239 /* flags for graph vertices and edges */
01240 #define  CV_GRAPH_ITEM_VISITED_FLAG  (1 << 30)
01241 #define  CV_IS_GRAPH_VERTEX_VISITED(vtx) \
01242     (((CvGraphVtx*)(vtx))->flags & CV_GRAPH_ITEM_VISITED_FLAG)
01243 #define  CV_IS_GRAPH_EDGE_VISITED(edge) \
01244     (((CvGraphEdge*)(edge))->flags & CV_GRAPH_ITEM_VISITED_FLAG)
01245 #define  CV_GRAPH_SEARCH_TREE_NODE_FLAG   (1 << 29)
01246 #define  CV_GRAPH_FORWARD_EDGE_FLAG       (1 << 28)
01247 
01248 typedef struct CvGraphScanner
01249 {
01250     CvGraphVtx* vtx;       /* current graph vertex (or current edge origin) */
01251     CvGraphVtx* dst;       /* current graph edge destination vertex */
01252     CvGraphEdge* edge;     /* current edge */
01253 
01254     CvGraph* graph;        /* the graph */
01255     CvSeq*   stack;        /* the graph vertex stack */
01256     int      index;        /* the lower bound of certainly visited vertices */
01257     int      mask;         /* event mask */
01258 }
01259 CvGraphScanner;
01260 
01261 /* Creates new graph scanner. */
01262 CVAPI(CvGraphScanner*)  cvCreateGraphScanner( CvGraph* graph,
01263                                              CvGraphVtx* vtx CV_DEFAULT(NULL),
01264                                              int mask CV_DEFAULT(CV_GRAPH_ALL_ITEMS));
01265 
01266 /* Releases graph scanner. */
01267 CVAPI(void) cvReleaseGraphScanner( CvGraphScanner** scanner );
01268 
01269 /* Get next graph element */
01270 CVAPI(int)  cvNextGraphItem( CvGraphScanner* scanner );
01271 
01272 /* Creates a copy of graph */
01273 CVAPI(CvGraph*) cvCloneGraph( const CvGraph* graph, CvMemStorage* storage );
01274 
01275 /****************************************************************************************\
01276 *                                     Drawing                                            *
01277 \****************************************************************************************/
01278 
01279 /****************************************************************************************\
01280 *       Drawing functions work with images/matrices of arbitrary type.                   *
01281 *       For color images the channel order is BGR[A]                                     *
01282 *       Antialiasing is supported only for 8-bit image now.                              *
01283 *       All the functions include parameter color that means rgb value (that may be      *
01284 *       constructed with CV_RGB macro) for color images and brightness                   *
01285 *       for grayscale images.                                                            *
01286 *       If a drawn figure is partially or completely outside of the image, it is clipped.*
01287 \****************************************************************************************/
01288 
01289 #define CV_RGB( r, g, b )  cvScalar( (b), (g), (r), 0 )
01290 #define CV_FILLED -1
01291 
01292 #define CV_AA 16
01293 
01294 /* Draws 4-connected, 8-connected or antialiased line segment connecting two points */
01295 CVAPI(void)  cvLine( CvArr* img, CvPoint pt1, CvPoint pt2,
01296                      CvScalar color, int thickness CV_DEFAULT(1),
01297                      int line_type CV_DEFAULT(8), int shift CV_DEFAULT(0) );
01298 
01299 /* Draws a rectangle given two opposite corners of the rectangle (pt1 & pt2),
01300    if thickness<0 (e.g. thickness == CV_FILLED), the filled box is drawn */
01301 CVAPI(void)  cvRectangle( CvArr* img, CvPoint pt1, CvPoint pt2,
01302                           CvScalar color, int thickness CV_DEFAULT(1),
01303                           int line_type CV_DEFAULT(8),
01304                           int shift CV_DEFAULT(0));
01305 
01306 /* Draws a rectangle specified by a CvRect structure */
01307 CVAPI(void)  cvRectangleR( CvArr* img, CvRect r,
01308                            CvScalar color, int thickness CV_DEFAULT(1),
01309                            int line_type CV_DEFAULT(8),
01310                            int shift CV_DEFAULT(0));
01311     
01312     
01313 /* Draws a circle with specified center and radius.
01314    Thickness works in the same way as with cvRectangle */
01315 CVAPI(void)  cvCircle( CvArr* img, CvPoint center, int radius,
01316                        CvScalar color, int thickness CV_DEFAULT(1),
01317                        int line_type CV_DEFAULT(8), int shift CV_DEFAULT(0));
01318 
01319 /* Draws ellipse outline, filled ellipse, elliptic arc or filled elliptic sector,
01320    depending on <thickness>, <start_angle> and <end_angle> parameters. The resultant figure
01321    is rotated by <angle>. All the angles are in degrees */
01322 CVAPI(void)  cvEllipse( CvArr* img, CvPoint center, CvSize axes,
01323                         double angle, double start_angle, double end_angle,
01324                         CvScalar color, int thickness CV_DEFAULT(1),
01325                         int line_type CV_DEFAULT(8), int shift CV_DEFAULT(0));
01326 
01327 CV_INLINE  void  cvEllipseBox( CvArr* img, CvBox2D box, CvScalar color,
01328                                int thickness CV_DEFAULT(1),
01329                                int line_type CV_DEFAULT(8), int shift CV_DEFAULT(0) )
01330 {
01331     CvSize axes;
01332     axes.width = cvRound(box.size.width*0.5);
01333     axes.height = cvRound(box.size.height*0.5);
01334 
01335     cvEllipse( img, cvPointFrom32f( box.center ), axes, box.angle,
01336                0, 360, color, thickness, line_type, shift );
01337 }
01338 
01339 /* Fills convex or monotonous polygon. */
01340 CVAPI(void)  cvFillConvexPoly( CvArr* img, const CvPoint* pts, int npts, CvScalar color,
01341                                int line_type CV_DEFAULT(8), int shift CV_DEFAULT(0));
01342 
01343 /* Fills an area bounded by one or more arbitrary polygons */
01344 CVAPI(void)  cvFillPoly( CvArr* img, CvPoint** pts, const int* npts,
01345                          int contours, CvScalar color,
01346                          int line_type CV_DEFAULT(8), int shift CV_DEFAULT(0) );
01347 
01348 /* Draws one or more polygonal curves */
01349 CVAPI(void)  cvPolyLine( CvArr* img, CvPoint** pts, const int* npts, int contours,
01350                          int is_closed, CvScalar color, int thickness CV_DEFAULT(1),
01351                          int line_type CV_DEFAULT(8), int shift CV_DEFAULT(0) );
01352 
01353 #define cvDrawRect cvRectangle
01354 #define cvDrawLine cvLine
01355 #define cvDrawCircle cvCircle
01356 #define cvDrawEllipse cvEllipse
01357 #define cvDrawPolyLine cvPolyLine
01358 
01359 /* Clips the line segment connecting *pt1 and *pt2
01360    by the rectangular window
01361    (0<=x<img_size.width, 0<=y<img_size.height). */
01362 CVAPI(int) cvClipLine( CvSize img_size, CvPoint* pt1, CvPoint* pt2 );
01363 
01364 /* Initializes line iterator. Initially, line_iterator->ptr will point
01365    to pt1 (or pt2, see left_to_right description) location in the image.
01366    Returns the number of pixels on the line between the ending points. */
01367 CVAPI(int)  cvInitLineIterator( const CvArr* image, CvPoint pt1, CvPoint pt2,
01368                                 CvLineIterator* line_iterator,
01369                                 int connectivity CV_DEFAULT(8),
01370                                 int left_to_right CV_DEFAULT(0));
01371 
01372 /* Moves iterator to the next line point */
01373 #define CV_NEXT_LINE_POINT( line_iterator )                     \
01374 {                                                               \
01375     int _line_iterator_mask = (line_iterator).err < 0 ? -1 : 0; \
01376     (line_iterator).err += (line_iterator).minus_delta +        \
01377         ((line_iterator).plus_delta & _line_iterator_mask);     \
01378     (line_iterator).ptr += (line_iterator).minus_step +         \
01379         ((line_iterator).plus_step & _line_iterator_mask);      \
01380 }
01381 
01382 
01383 /* basic font types */
01384 #define CV_FONT_HERSHEY_SIMPLEX         0
01385 #define CV_FONT_HERSHEY_PLAIN           1
01386 #define CV_FONT_HERSHEY_DUPLEX          2
01387 #define CV_FONT_HERSHEY_COMPLEX         3
01388 #define CV_FONT_HERSHEY_TRIPLEX         4
01389 #define CV_FONT_HERSHEY_COMPLEX_SMALL   5
01390 #define CV_FONT_HERSHEY_SCRIPT_SIMPLEX  6
01391 #define CV_FONT_HERSHEY_SCRIPT_COMPLEX  7
01392 
01393 /* font flags */
01394 #define CV_FONT_ITALIC                 16
01395 
01396 #define CV_FONT_VECTOR0    CV_FONT_HERSHEY_SIMPLEX
01397 
01398 /* Font structure */
01399 typedef struct CvFont
01400 {
01401     int         font_face; /* =CV_FONT_* */
01402     const int*  ascii; /* font data and metrics */
01403     const int*  greek;
01404     const int*  cyrillic;
01405     float       hscale, vscale;
01406     float       shear; /* slope coefficient: 0 - normal, >0 - italic */
01407     int         thickness; /* letters thickness */
01408     float       dx; /* horizontal interval between letters */
01409     int         line_type;
01410 }
01411 CvFont;
01412 
01413 /* Initializes font structure used further in cvPutText */
01414 CVAPI(void)  cvInitFont( CvFont* font, int font_face,
01415                          double hscale, double vscale,
01416                          double shear CV_DEFAULT(0),
01417                          int thickness CV_DEFAULT(1),
01418                          int line_type CV_DEFAULT(8));
01419 
01420 CV_INLINE CvFont cvFont( double scale, int thickness CV_DEFAULT(1) )
01421 {
01422     CvFont font;
01423     cvInitFont( &font, CV_FONT_HERSHEY_PLAIN, scale, scale, 0, thickness, CV_AA );
01424     return font;
01425 }
01426 
01427 /* Renders text stroke with specified font and color at specified location.
01428    CvFont should be initialized with cvInitFont */
01429 CVAPI(void)  cvPutText( CvArr* img, const char* text, CvPoint org,
01430                         const CvFont* font, CvScalar color );
01431 
01432 /* Calculates bounding box of text stroke (useful for alignment) */
01433 CVAPI(void)  cvGetTextSize( const char* text_string, const CvFont* font,
01434                             CvSize* text_size, int* baseline );
01435 
01436 /* Unpacks color value, if arrtype is CV_8UC?, <color> is treated as
01437    packed color value, otherwise the first channels (depending on arrtype)
01438    of destination scalar are set to the same value = <color> */
01439 CVAPI(CvScalar)  cvColorToScalar( double packed_color, int arrtype );
01440 
01441 /* Returns the polygon points which make up the given ellipse.  The ellipse is define by
01442    the box of size 'axes' rotated 'angle' around the 'center'.  A partial sweep
01443    of the ellipse arc can be done by spcifying arc_start and arc_end to be something
01444    other than 0 and 360, respectively.  The input array 'pts' must be large enough to
01445    hold the result.  The total number of points stored into 'pts' is returned by this
01446    function. */
01447 CVAPI(int) cvEllipse2Poly( CvPoint center, CvSize axes,
01448                  int angle, int arc_start, int arc_end, CvPoint * pts, int delta );
01449 
01450 /* Draws contour outlines or filled interiors on the image */
01451 CVAPI(void)  cvDrawContours( CvArr *img, CvSeq* contour,
01452                              CvScalar external_color, CvScalar hole_color,
01453                              int max_level, int thickness CV_DEFAULT(1),
01454                              int line_type CV_DEFAULT(8),
01455                              CvPoint offset CV_DEFAULT(cvPoint(0,0)));
01456 
01457 /* Does look-up transformation. Elements of the source array
01458    (that should be 8uC1 or 8sC1) are used as indexes in lutarr 256-element table */
01459 CVAPI(void) cvLUT( const CvArr* src, CvArr* dst, const CvArr* lut );
01460 
01461 
01462 /******************* Iteration through the sequence tree *****************/
01463 typedef struct CvTreeNodeIterator
01464 {
01465     const void* node;
01466     int level;
01467     int max_level;
01468 }
01469 CvTreeNodeIterator;
01470 
01471 CVAPI(void) cvInitTreeNodeIterator( CvTreeNodeIterator* tree_iterator,
01472                                    const void* first, int max_level );
01473 CVAPI(void*) cvNextTreeNode( CvTreeNodeIterator* tree_iterator );
01474 CVAPI(void*) cvPrevTreeNode( CvTreeNodeIterator* tree_iterator );
01475 
01476 /* Inserts sequence into tree with specified "parent" sequence.
01477    If parent is equal to frame (e.g. the most external contour),
01478    then added contour will have null pointer to parent. */
01479 CVAPI(void) cvInsertNodeIntoTree( void* node, void* parent, void* frame );
01480 
01481 /* Removes contour from tree (together with the contour children). */
01482 CVAPI(void) cvRemoveNodeFromTree( void* node, void* frame );
01483 
01484 /* Gathers pointers to all the sequences,
01485    accessible from the <first>, to the single sequence */
01486 CVAPI(CvSeq*) cvTreeToNodeSeq( const void* first, int header_size,
01487                               CvMemStorage* storage );
01488 
01489 /* The function implements the K-means algorithm for clustering an array of sample
01490    vectors in a specified number of classes */
01491 #define CV_KMEANS_USE_INITIAL_LABELS    1
01492 CVAPI(int) cvKMeans2( const CvArr* samples, int cluster_count, CvArr* labels,
01493                       CvTermCriteria termcrit, int attempts CV_DEFAULT(1),
01494                       CvRNG* rng CV_DEFAULT(0), int flags CV_DEFAULT(0),
01495                       CvArr* _centers CV_DEFAULT(0), double* compactness CV_DEFAULT(0) );
01496 
01497 /****************************************************************************************\
01498 *                                    System functions                                    *
01499 \****************************************************************************************/
01500 
01501 /* Add the function pointers table with associated information to the IPP primitives list */
01502 CVAPI(int)  cvRegisterModule( const CvModuleInfo* module_info );
01503 
01504 /* Loads optimized functions from IPP, MKL etc. or switches back to pure C code */
01505 CVAPI(int)  cvUseOptimized( int on_off );
01506 
01507 /* Retrieves information about the registered modules and loaded optimized plugins */
01508 CVAPI(void)  cvGetModuleInfo( const char* module_name,
01509                               const char** version,
01510                               const char** loaded_addon_plugins );
01511 
01512 /* Get current OpenCV error status */
01513 CVAPI(int) cvGetErrStatus( void );
01514 
01515 /* Sets error status silently */
01516 CVAPI(void) cvSetErrStatus( int status );
01517 
01518 #define CV_ErrModeLeaf     0   /* Print error and exit program */
01519 #define CV_ErrModeParent   1   /* Print error and continue */
01520 #define CV_ErrModeSilent   2   /* Don't print and continue */
01521 
01522 /* Retrives current error processing mode */
01523 CVAPI(int)  cvGetErrMode( void );
01524 
01525 /* Sets error processing mode, returns previously used mode */
01526 CVAPI(int) cvSetErrMode( int mode );
01527 
01528 /* Sets error status and performs some additonal actions (displaying message box,
01529    writing message to stderr, terminating application etc.)
01530    depending on the current error mode */
01531 CVAPI(void) cvError( int status, const char* func_name,
01532                     const char* err_msg, const char* file_name, int line );
01533 
01534 /* Retrieves textual description of the error given its code */
01535 CVAPI(const char*) cvErrorStr( int status );
01536 
01537 /* Retrieves detailed information about the last error occured */
01538 CVAPI(int) cvGetErrInfo( const char** errcode_desc, const char** description,
01539                         const char** filename, int* line );
01540 
01541 /* Maps IPP error codes to the counterparts from OpenCV */
01542 CVAPI(int) cvErrorFromIppStatus( int ipp_status );
01543 
01544 typedef int (CV_CDECL *CvErrorCallback)( int status, const char* func_name,
01545                     const char* err_msg, const char* file_name, int line, void* userdata );
01546 
01547 /* Assigns a new error-handling function */
01548 CVAPI(CvErrorCallback) cvRedirectError( CvErrorCallback error_handler,
01549                                        void* userdata CV_DEFAULT(NULL),
01550                                        void** prev_userdata CV_DEFAULT(NULL) );
01551 
01552 /*
01553     Output to:
01554         cvNulDevReport - nothing
01555         cvStdErrReport - console(fprintf(stderr,...))
01556         cvGuiBoxReport - MessageBox(WIN32)
01557 */
01558 CVAPI(int) cvNulDevReport( int status, const char* func_name, const char* err_msg,
01559                           const char* file_name, int line, void* userdata );
01560 
01561 CVAPI(int) cvStdErrReport( int status, const char* func_name, const char* err_msg,
01562                           const char* file_name, int line, void* userdata );
01563 
01564 CVAPI(int) cvGuiBoxReport( int status, const char* func_name, const char* err_msg,
01565                           const char* file_name, int line, void* userdata );
01566 
01567 typedef void* (CV_CDECL *CvAllocFunc)(size_t size, void* userdata);
01568 typedef int (CV_CDECL *CvFreeFunc)(void* pptr, void* userdata);
01569 
01570 /* Set user-defined memory managment functions (substitutors for malloc and free) that
01571    will be called by cvAlloc, cvFree and higher-level functions (e.g. cvCreateImage) */
01572 CVAPI(void) cvSetMemoryManager( CvAllocFunc alloc_func CV_DEFAULT(NULL),
01573                                CvFreeFunc free_func CV_DEFAULT(NULL),
01574                                void* userdata CV_DEFAULT(NULL));
01575 
01576 
01577 typedef IplImage* (CV_STDCALL* Cv_iplCreateImageHeader)
01578                             (int,int,int,char*,char*,int,int,int,int,int,
01579                             IplROI*,IplImage*,void*,IplTileInfo*);
01580 typedef void (CV_STDCALL* Cv_iplAllocateImageData)(IplImage*,int,int);
01581 typedef void (CV_STDCALL* Cv_iplDeallocate)(IplImage*,int);
01582 typedef IplROI* (CV_STDCALL* Cv_iplCreateROI)(int,int,int,int,int);
01583 typedef IplImage* (CV_STDCALL* Cv_iplCloneImage)(const IplImage*);
01584 
01585 /* Makes OpenCV use IPL functions for IplImage allocation/deallocation */
01586 CVAPI(void) cvSetIPLAllocators( Cv_iplCreateImageHeader create_header,
01587                                Cv_iplAllocateImageData allocate_data,
01588                                Cv_iplDeallocate deallocate,
01589                                Cv_iplCreateROI create_roi,
01590                                Cv_iplCloneImage clone_image );
01591 
01592 #define CV_TURN_ON_IPL_COMPATIBILITY()                                  \
01593     cvSetIPLAllocators( iplCreateImageHeader, iplAllocateImage,         \
01594                         iplDeallocate, iplCreateROI, iplCloneImage )
01595 
01596 /****************************************************************************************\
01597 *                                    Data Persistence                                    *
01598 \****************************************************************************************/
01599 
01600 /********************************** High-level functions ********************************/
01601 
01602 /* opens existing or creates new file storage */
01603 CVAPI(CvFileStorage*)  cvOpenFileStorage( const char* filename,
01604                                           CvMemStorage* memstorage,
01605                                           int flags );
01606 
01607 /* closes file storage and deallocates buffers */
01608 CVAPI(void) cvReleaseFileStorage( CvFileStorage** fs );
01609 
01610 /* returns attribute value or 0 (NULL) if there is no such attribute */
01611 CVAPI(const char*) cvAttrValue( const CvAttrList* attr, const char* attr_name );
01612 
01613 /* starts writing compound structure (map or sequence) */
01614 CVAPI(void) cvStartWriteStruct( CvFileStorage* fs, const char* name,
01615                                 int struct_flags, const char* type_name CV_DEFAULT(NULL),
01616                                 CvAttrList attributes CV_DEFAULT(cvAttrList()));
01617 
01618 /* finishes writing compound structure */
01619 CVAPI(void) cvEndWriteStruct( CvFileStorage* fs );
01620 
01621 /* writes an integer */
01622 CVAPI(void) cvWriteInt( CvFileStorage* fs, const char* name, int value );
01623 
01624 /* writes a floating-point number */
01625 CVAPI(void) cvWriteReal( CvFileStorage* fs, const char* name, double value );
01626 
01627 /* writes a string */
01628 CVAPI(void) cvWriteString( CvFileStorage* fs, const char* name,
01629                            const char* str, int quote CV_DEFAULT(0) );
01630 
01631 /* writes a comment */
01632 CVAPI(void) cvWriteComment( CvFileStorage* fs, const char* comment,
01633                             int eol_comment );
01634 
01635 /* writes instance of a standard type (matrix, image, sequence, graph etc.)
01636    or user-defined type */
01637 CVAPI(void) cvWrite( CvFileStorage* fs, const char* name, const void* ptr,
01638                          CvAttrList attributes CV_DEFAULT(cvAttrList()));
01639 
01640 /* starts the next stream */
01641 CVAPI(void) cvStartNextStream( CvFileStorage* fs );
01642 
01643 /* helper function: writes multiple integer or floating-point numbers */
01644 CVAPI(void) cvWriteRawData( CvFileStorage* fs, const void* src,
01645                                 int len, const char* dt );
01646 
01647 /* returns the hash entry corresponding to the specified literal key string or 0
01648    if there is no such a key in the storage */
01649 CVAPI(CvStringHashNode*) cvGetHashedKey( CvFileStorage* fs, const char* name,
01650                                         int len CV_DEFAULT(-1),
01651                                         int create_missing CV_DEFAULT(0));
01652 
01653 /* returns file node with the specified key within the specified map
01654    (collection of named nodes) */
01655 CVAPI(CvFileNode*) cvGetRootFileNode( const CvFileStorage* fs,
01656                                      int stream_index CV_DEFAULT(0) );
01657 
01658 /* returns file node with the specified key within the specified map
01659    (collection of named nodes) */
01660 CVAPI(CvFileNode*) cvGetFileNode( CvFileStorage* fs, CvFileNode* map,
01661                                  const CvStringHashNode* key,
01662                                  int create_missing CV_DEFAULT(0) );
01663 
01664 /* this is a slower version of cvGetFileNode that takes the key as a literal string */
01665 CVAPI(CvFileNode*) cvGetFileNodeByName( const CvFileStorage* fs,
01666                                        const CvFileNode* map,
01667                                        const char* name );
01668 
01669 CV_INLINE int cvReadInt( const CvFileNode* node, int default_value CV_DEFAULT(0) )
01670 {
01671     return !node ? default_value :
01672         CV_NODE_IS_INT(node->tag) ? node->data.i :
01673         CV_NODE_IS_REAL(node->tag) ? cvRound(node->data.f) : 0x7fffffff;
01674 }
01675 
01676 
01677 CV_INLINE int cvReadIntByName( const CvFileStorage* fs, const CvFileNode* map,
01678                          const char* name, int default_value CV_DEFAULT(0) )
01679 {
01680     return cvReadInt( cvGetFileNodeByName( fs, map, name ), default_value );
01681 }
01682 
01683 
01684 CV_INLINE double cvReadReal( const CvFileNode* node, double default_value CV_DEFAULT(0.) )
01685 {
01686     return !node ? default_value :
01687         CV_NODE_IS_INT(node->tag) ? (double)node->data.i :
01688         CV_NODE_IS_REAL(node->tag) ? node->data.f : 1e300;
01689 }
01690 
01691 
01692 CV_INLINE double cvReadRealByName( const CvFileStorage* fs, const CvFileNode* map,
01693                         const char* name, double default_value CV_DEFAULT(0.) )
01694 {
01695     return cvReadReal( cvGetFileNodeByName( fs, map, name ), default_value );
01696 }
01697 
01698 
01699 CV_INLINE const char* cvReadString( const CvFileNode* node,
01700                         const char* default_value CV_DEFAULT(NULL) )
01701 {
01702     return !node ? default_value : CV_NODE_IS_STRING(node->tag) ? node->data.str.ptr : 0;
01703 }
01704 
01705 
01706 CV_INLINE const char* cvReadStringByName( const CvFileStorage* fs, const CvFileNode* map,
01707                         const char* name, const char* default_value CV_DEFAULT(NULL) )
01708 {
01709     return cvReadString( cvGetFileNodeByName( fs, map, name ), default_value );
01710 }
01711 
01712 
01713 /* decodes standard or user-defined object and returns it */
01714 CVAPI(void*) cvRead( CvFileStorage* fs, CvFileNode* node,
01715                         CvAttrList* attributes CV_DEFAULT(NULL));
01716 
01717 /* decodes standard or user-defined object and returns it */
01718 CV_INLINE void* cvReadByName( CvFileStorage* fs, const CvFileNode* map,
01719                               const char* name, CvAttrList* attributes CV_DEFAULT(NULL) )
01720 {
01721     return cvRead( fs, cvGetFileNodeByName( fs, map, name ), attributes );
01722 }
01723 
01724 
01725 /* starts reading data from sequence or scalar numeric node */
01726 CVAPI(void) cvStartReadRawData( const CvFileStorage* fs, const CvFileNode* src,
01727                                CvSeqReader* reader );
01728 
01729 /* reads multiple numbers and stores them to array */
01730 CVAPI(void) cvReadRawDataSlice( const CvFileStorage* fs, CvSeqReader* reader,
01731                                int count, void* dst, const char* dt );
01732 
01733 /* combination of two previous functions for easier reading of whole sequences */
01734 CVAPI(void) cvReadRawData( const CvFileStorage* fs, const CvFileNode* src,
01735                           void* dst, const char* dt );
01736 
01737 /* writes a copy of file node to file storage */
01738 CVAPI(void) cvWriteFileNode( CvFileStorage* fs, const char* new_node_name,
01739                             const CvFileNode* node, int embed );
01740 
01741 /* returns name of file node */
01742 CVAPI(const char*) cvGetFileNodeName( const CvFileNode* node );
01743 
01744 /*********************************** Adding own types ***********************************/
01745 
01746 CVAPI(void) cvRegisterType( const CvTypeInfo* info );
01747 CVAPI(void) cvUnregisterType( const char* type_name );
01748 CVAPI(CvTypeInfo*) cvFirstType(void);
01749 CVAPI(CvTypeInfo*) cvFindType( const char* type_name );
01750 CVAPI(CvTypeInfo*) cvTypeOf( const void* struct_ptr );
01751 
01752 /* universal functions */
01753 CVAPI(void) cvRelease( void** struct_ptr );
01754 CVAPI(void*) cvClone( const void* struct_ptr );
01755 
01756 /* simple API for reading/writing data */
01757 CVAPI(void) cvSave( const char* filename, const void* struct_ptr,
01758                     const char* name CV_DEFAULT(NULL),
01759                     const char* comment CV_DEFAULT(NULL),
01760                     CvAttrList attributes CV_DEFAULT(cvAttrList()));
01761 CVAPI(void*) cvLoad( const char* filename,
01762                      CvMemStorage* memstorage CV_DEFAULT(NULL),
01763                      const char* name CV_DEFAULT(NULL),
01764                      const char** real_name CV_DEFAULT(NULL) );
01765 
01766 /*********************************** Measuring Execution Time ***************************/
01767 
01768 /* helper functions for RNG initialization and accurate time measurement:
01769    uses internal clock counter on x86 */
01770 CVAPI(int64)  cvGetTickCount( void );
01771 CVAPI(double) cvGetTickFrequency( void );
01772 
01773 /*********************************** CPU capabilities ***********************************/
01774 
01775 #define CV_CPU_NONE    0    
01776 #define CV_CPU_MMX     1
01777 #define CV_CPU_SSE     2
01778 #define CV_CPU_SSE2    3
01779 #define CV_CPU_SSE3    4
01780 #define CV_CPU_SSSE3   5
01781 #define CV_CPU_SSE4_1  6
01782 #define CV_CPU_SSE4_2  7
01783 #define CV_CPU_AVX    10
01784 #define CV_HARDWARE_MAX_FEATURE 255
01785 
01786 CVAPI(int) cvCheckHardwareSupport(int feature);
01787 
01788 /*********************************** Multi-Threading ************************************/
01789 
01790 /* retrieve/set the number of threads used in OpenMP implementations */
01791 CVAPI(int)  cvGetNumThreads( void );
01792 CVAPI(void) cvSetNumThreads( int threads CV_DEFAULT(0) );
01793 /* get index of the thread being executed */
01794 CVAPI(int)  cvGetThreadNum( void );
01795     
01796 
01797 #ifdef __cplusplus
01798 }
01799 
01800 // classes for automatic module/RTTI data registration/unregistration
01801 struct CV_EXPORTS CvModule
01802 {
01803     CvModule( CvModuleInfo* _info );
01804     ~CvModule();
01805     CvModuleInfo* info;
01806 
01807     static CvModuleInfo* first;
01808     static CvModuleInfo* last;
01809 };
01810 
01811 struct CV_EXPORTS CvType
01812 {
01813     CvType( const char* type_name,
01814             CvIsInstanceFunc is_instance, CvReleaseFunc release=0,
01815             CvReadFunc read=0, CvWriteFunc write=0, CvCloneFunc clone=0 );
01816     ~CvType();
01817     CvTypeInfo* info;
01818 
01819     static CvTypeInfo* first;
01820     static CvTypeInfo* last;
01821 };
01822 
01823 #endif
01824 
01825 #ifndef SKIP_INCLUDES // for now only expose old interface to swig
01826 #include "cxcore.hpp"
01827 #endif // SKIP_INCLUDES
01828 
01829 #endif