core_c.h

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 // Copyright (C) 2013, OpenCV Foundation, all rights reserved.
00016 // Third party copyrights are property of their respective owners.
00017 //
00018 // Redistribution and use in source and binary forms, with or without modification,
00019 // are permitted provided that the following conditions are met:
00020 //
00021 //   * Redistribution's of source code must retain the above copyright notice,
00022 //     this list of conditions and the following disclaimer.
00023 //
00024 //   * Redistribution's in binary form must reproduce the above copyright notice,
00025 //     this list of conditions and the following disclaimer in the documentation
00026 //     and/or other materials provided with the distribution.
00027 //
00028 //   * The name of the copyright holders may not be used to endorse or promote products
00029 //     derived from this software without specific prior written permission.
00030 //
00031 // This software is provided by the copyright holders and contributors "as is" and
00032 // any express or implied warranties, including, but not limited to, the implied
00033 // warranties of merchantability and fitness for a particular purpose are disclaimed.
00034 // In no event shall the Intel Corporation or contributors be liable for any direct,
00035 // indirect, incidental, special, exemplary, or consequential damages
00036 // (including, but not limited to, procurement of substitute goods or services;
00037 // loss of use, data, or profits; or business interruption) however caused
00038 // and on any theory of liability, whether in contract, strict liability,
00039 // or tort (including negligence or otherwise) arising in any way out of
00040 // the use of this software, even if advised of the possibility of such damage.
00041 //
00042 //M*/
00043 
00044 
00045 #ifndef __OPENCV_CORE_C_H__
00046 #define __OPENCV_CORE_C_H__
00047 
00048 #include "opencv2/core/types_c.h"
00049 
00050 #ifdef __cplusplus
00051 #  ifdef _MSC_VER
00052 /* disable warning C4190: 'function' has C-linkage specified, but returns UDT 'typename'
00053                           which is incompatible with C
00054 
00055    It is OK to disable it because we only extend few plain structures with
00056    C++ construrtors for simpler interoperability with C++ API of the library
00057 */
00058 #    pragma warning(disable:4190)
00059 #  elif defined __clang__ && __clang_major__ >= 3
00060 #    pragma GCC diagnostic ignored "-Wreturn-type-c-linkage"
00061 #  endif
00062 #endif
00063 
00064 #ifdef __cplusplus
00065 extern "C" {
00066 #endif
00067 
00068 /** @addtogroup core_c
00069     @{
00070 */
00071 
00072 /****************************************************************************************\
00073 *          Array allocation, deallocation, initialization and access to elements         *
00074 \****************************************************************************************/
00075 
00076 /** `malloc` wrapper.
00077    If there is no enough memory, the function
00078    (as well as other OpenCV functions that call cvAlloc)
00079    raises an error. */
00080 CVAPI(void*)  cvAlloc( size_t size );
00081 
00082 /** `free` wrapper.
00083    Here and further all the memory releasing functions
00084    (that all call cvFree) take double pointer in order to
00085    to clear pointer to the data after releasing it.
00086    Passing pointer to NULL pointer is Ok: nothing happens in this case
00087 */
00088 CVAPI(void)   cvFree_( void* ptr );
00089 #define cvFree(ptr) (cvFree_(*(ptr)), *(ptr)=0)
00090 
00091 /** @brief Creates an image header but does not allocate the image data.
00092 
00093 @param size Image width and height
00094 @param depth Image depth (see cvCreateImage )
00095 @param channels Number of channels (see cvCreateImage )
00096  */
00097 CVAPI(IplImage*)  cvCreateImageHeader( CvSize size, int depth, int channels );
00098 
00099 /** @brief Initializes an image header that was previously allocated.
00100 
00101 The returned IplImage\* points to the initialized header.
00102 @param image Image header to initialize
00103 @param size Image width and height
00104 @param depth Image depth (see cvCreateImage )
00105 @param channels Number of channels (see cvCreateImage )
00106 @param origin Top-left IPL_ORIGIN_TL or bottom-left IPL_ORIGIN_BL
00107 @param align Alignment for image rows, typically 4 or 8 bytes
00108  */
00109 CVAPI(IplImage*) cvInitImageHeader( IplImage* image, CvSize size, int depth,
00110                                    int channels, int origin CV_DEFAULT(0),
00111                                    int align CV_DEFAULT(4));
00112 
00113 /** @brief Creates an image header and allocates the image data.
00114 
00115 This function call is equivalent to the following code:
00116 @code
00117     header = cvCreateImageHeader(size, depth, channels);
00118     cvCreateData(header);
00119 @endcode
00120 @param size Image width and height
00121 @param depth Bit depth of image elements. See IplImage for valid depths.
00122 @param channels Number of channels per pixel. See IplImage for details. This function only creates
00123 images with interleaved channels.
00124  */
00125 CVAPI(IplImage*)  cvCreateImage( CvSize size, int depth, int channels );
00126 
00127 /** @brief Deallocates an image header.
00128 
00129 This call is an analogue of :
00130 @code
00131     if(image )
00132     {
00133         iplDeallocate(*image, IPL_IMAGE_HEADER | IPL_IMAGE_ROI);
00134         *image = 0;
00135     }
00136 @endcode
00137 but it does not use IPL functions by default (see the CV_TURN_ON_IPL_COMPATIBILITY macro).
00138 @param image Double pointer to the image header
00139  */
00140 CVAPI(void)  cvReleaseImageHeader( IplImage** image );
00141 
00142 /** @brief Deallocates the image header and the image data.
00143 
00144 This call is a shortened form of :
00145 @code
00146     if(*image )
00147     {
00148         cvReleaseData(*image);
00149         cvReleaseImageHeader(image);
00150     }
00151 @endcode
00152 @param image Double pointer to the image header
00153 */
00154 CVAPI(void)  cvReleaseImage( IplImage** image );
00155 
00156 /** Creates a copy of IPL image (widthStep may differ) */
00157 CVAPI(IplImage*) cvCloneImage( const IplImage* image );
00158 
00159 /** @brief Sets the channel of interest in an IplImage.
00160 
00161 If the ROI is set to NULL and the coi is *not* 0, the ROI is allocated. Most OpenCV functions do
00162 *not* support the COI setting, so to process an individual image/matrix channel one may copy (via
00163 cvCopy or cvSplit) the channel to a separate image/matrix, process it and then copy the result
00164 back (via cvCopy or cvMerge) if needed.
00165 @param image A pointer to the image header
00166 @param coi The channel of interest. 0 - all channels are selected, 1 - first channel is selected,
00167 etc. Note that the channel indices become 1-based.
00168  */
00169 CVAPI(void)  cvSetImageCOI( IplImage* image, int coi );
00170 
00171 /** @brief Returns the index of the channel of interest.
00172 
00173 Returns the channel of interest of in an IplImage. Returned values correspond to the coi in
00174 cvSetImageCOI.
00175 @param image A pointer to the image header
00176  */
00177 CVAPI(int)  cvGetImageCOI( const IplImage* image );
00178 
00179 /** @brief Sets an image Region Of Interest (ROI) for a given rectangle.
00180 
00181 If the original image ROI was NULL and the rect is not the whole image, the ROI structure is
00182 allocated.
00183 
00184 Most OpenCV functions support the use of ROI and treat the image rectangle as a separate image. For
00185 example, all of the pixel coordinates are counted from the top-left (or bottom-left) corner of the
00186 ROI, not the original image.
00187 @param image A pointer to the image header
00188 @param rect The ROI rectangle
00189  */
00190 CVAPI(void)  cvSetImageROI( IplImage* image, CvRect  rect );
00191 
00192 /** @brief Resets the image ROI to include the entire image and releases the ROI structure.
00193 
00194 This produces a similar result to the following, but in addition it releases the ROI structure. :
00195 @code
00196     cvSetImageROI(image, cvRect(0, 0, image->width, image->height ));
00197     cvSetImageCOI(image, 0);
00198 @endcode
00199 @param image A pointer to the image header
00200  */
00201 CVAPI(void)  cvResetImageROI( IplImage* image );
00202 
00203 /** @brief Returns the image ROI.
00204 
00205 If there is no ROI set, cvRect(0,0,image->width,image->height) is returned.
00206 @param image A pointer to the image header
00207  */
00208 CVAPI(CvRect ) cvGetImageROI( const IplImage* image );
00209 
00210 /** @brief Creates a matrix header but does not allocate the matrix data.
00211 
00212 The function allocates a new matrix header and returns a pointer to it. The matrix data can then be
00213 allocated using cvCreateData or set explicitly to user-allocated data via cvSetData.
00214 @param rows Number of rows in the matrix
00215 @param cols Number of columns in the matrix
00216 @param type Type of the matrix elements, see cvCreateMat
00217  */
00218 CVAPI(CvMat*)  cvCreateMatHeader( int rows, int cols, int type );
00219 
00220 #define CV_AUTOSTEP  0x7fffffff
00221 
00222 /** @brief Initializes a pre-allocated matrix header.
00223 
00224 This function is often used to process raw data with OpenCV matrix functions. For example, the
00225 following code computes the matrix product of two matrices, stored as ordinary arrays:
00226 @code
00227     double a[] = { 1, 2, 3, 4,
00228                    5, 6, 7, 8,
00229                    9, 10, 11, 12 };
00230 
00231     double b[] = { 1, 5, 9,
00232                    2, 6, 10,
00233                    3, 7, 11,
00234                    4, 8, 12 };
00235 
00236     double c[9];
00237     CvMat Ma, Mb, Mc ;
00238 
00239     cvInitMatHeader(&Ma, 3, 4, CV_64FC1, a);
00240     cvInitMatHeader(&Mb, 4, 3, CV_64FC1, b);
00241     cvInitMatHeader(&Mc, 3, 3, CV_64FC1, c);
00242 
00243     cvMatMulAdd(&Ma, &Mb, 0, &Mc);
00244     // the c array now contains the product of a (3x4) and b (4x3)
00245 @endcode
00246 @param mat A pointer to the matrix header to be initialized
00247 @param rows Number of rows in the matrix
00248 @param cols Number of columns in the matrix
00249 @param type Type of the matrix elements, see cvCreateMat .
00250 @param data Optional: data pointer assigned to the matrix header
00251 @param step Optional: full row width in bytes of the assigned data. By default, the minimal
00252 possible step is used which assumes there are no gaps between subsequent rows of the matrix.
00253  */
00254 CVAPI(CvMat*) cvInitMatHeader( CvMat* mat, int rows, int cols,
00255                               int type, void* data CV_DEFAULT(NULL),
00256                               int step CV_DEFAULT(CV_AUTOSTEP) );
00257 
00258 /** @brief Creates a matrix header and allocates the matrix data.
00259 
00260 The function call is equivalent to the following code:
00261 @code
00262     CvMat* mat = cvCreateMatHeader(rows, cols, type);
00263     cvCreateData(mat);
00264 @endcode
00265 @param rows Number of rows in the matrix
00266 @param cols Number of columns in the matrix
00267 @param type The type of the matrix elements in the form
00268 CV_<bit depth><S|U|F>C<number of channels> , where S=signed, U=unsigned, F=float. For
00269 example, CV _ 8UC1 means the elements are 8-bit unsigned and the there is 1 channel, and CV _
00270 32SC2 means the elements are 32-bit signed and there are 2 channels.
00271  */
00272 CVAPI(CvMat*)  cvCreateMat( int rows, int cols, int type );
00273 
00274 /** @brief Deallocates a matrix.
00275 
00276 The function decrements the matrix data reference counter and deallocates matrix header. If the data
00277 reference counter is 0, it also deallocates the data. :
00278 @code
00279     if(*mat )
00280         cvDecRefData(*mat);
00281     cvFree((void**)mat);
00282 @endcode
00283 @param mat Double pointer to the matrix
00284  */
00285 CVAPI(void)  cvReleaseMat( CvMat** mat );
00286 
00287 /** @brief Decrements an array data reference counter.
00288 
00289 The function decrements the data reference counter in a CvMat or CvMatND if the reference counter
00290 
00291 pointer is not NULL. If the counter reaches zero, the data is deallocated. In the current
00292 implementation the reference counter is not NULL only if the data was allocated using the
00293 cvCreateData function. The counter will be NULL in other cases such as: external data was assigned
00294 to the header using cvSetData, header is part of a larger matrix or image, or the header was
00295 converted from an image or n-dimensional matrix header.
00296 @param arr Pointer to an array header
00297  */
00298 CV_INLINE  void  cvDecRefData( CvArr* arr )
00299 {
00300     if( CV_IS_MAT( arr ))
00301     {
00302         CvMat* mat = (CvMat*)arr;
00303         mat->data.ptr = NULL;
00304         if( mat->refcount != NULL && --*mat->refcount == 0 )
00305             cvFree( &mat->refcount );
00306         mat->refcount = NULL;
00307     }
00308     else if( CV_IS_MATND( arr ))
00309     {
00310         CvMatND * mat = (CvMatND *)arr;
00311         mat->data.ptr = NULL;
00312         if( mat->refcount != NULL && --*mat->refcount == 0 )
00313             cvFree( &mat->refcount );
00314         mat->refcount = NULL;
00315     }
00316 }
00317 
00318 /** @brief Increments array data reference counter.
00319 
00320 The function increments CvMat or CvMatND data reference counter and returns the new counter value if
00321 the reference counter pointer is not NULL, otherwise it returns zero.
00322 @param arr Array header
00323  */
00324 CV_INLINE  int  cvIncRefData( CvArr* arr )
00325 {
00326     int refcount = 0;
00327     if( CV_IS_MAT( arr ))
00328     {
00329         CvMat* mat = (CvMat*)arr;
00330         if( mat->refcount != NULL )
00331             refcount = ++*mat->refcount;
00332     }
00333     else if( CV_IS_MATND( arr ))
00334     {
00335         CvMatND * mat = (CvMatND *)arr;
00336         if( mat->refcount != NULL )
00337             refcount = ++*mat->refcount;
00338     }
00339     return refcount;
00340 }
00341 
00342 
00343 /** Creates an exact copy of the input matrix (except, may be, step value) */
00344 CVAPI(CvMat*) cvCloneMat( const CvMat* mat );
00345 
00346 
00347 /** @brief Returns matrix header corresponding to the rectangular sub-array of input image or matrix.
00348 
00349 The function returns header, corresponding to a specified rectangle of the input array. In other
00350 
00351 words, it allows the user to treat a rectangular part of input array as a stand-alone array. ROI is
00352 taken into account by the function so the sub-array of ROI is actually extracted.
00353 @param arr Input array
00354 @param submat Pointer to the resultant sub-array header
00355 @param rect Zero-based coordinates of the rectangle of interest
00356  */
00357 CVAPI(CvMat*) cvGetSubRect( const CvArr* arr, CvMat* submat, CvRect  rect );
00358 #define cvGetSubArr cvGetSubRect
00359 
00360 /** @brief Returns array row or row span.
00361 
00362 The functions return the header, corresponding to a specified row/row span of the input array.
00363 cvGetRow(arr, submat, row) is a shortcut for cvGetRows(arr, submat, row, row+1).
00364 @param arr Input array
00365 @param submat Pointer to the resulting sub-array header
00366 @param start_row Zero-based index of the starting row (inclusive) of the span
00367 @param end_row Zero-based index of the ending row (exclusive) of the span
00368 @param delta_row Index step in the row span. That is, the function extracts every delta_row -th
00369 row from start_row and up to (but not including) end_row .
00370  */
00371 CVAPI(CvMat*) cvGetRows( const CvArr* arr, CvMat* submat,
00372                         int start_row, int end_row,
00373                         int delta_row CV_DEFAULT(1));
00374 
00375 /** @overload
00376 @param arr Input array
00377 @param submat Pointer to the resulting sub-array header
00378 @param row Zero-based index of the selected row
00379 */
00380 CV_INLINE  CvMat*  cvGetRow( const CvArr* arr, CvMat* submat, int row )
00381 {
00382     return cvGetRows( arr, submat, row, row + 1, 1 );
00383 }
00384 
00385 
00386 /** @brief Returns one of more array columns.
00387 
00388 The functions return the header, corresponding to a specified column span of the input array. That
00389 
00390 is, no data is copied. Therefore, any modifications of the submatrix will affect the original array.
00391 If you need to copy the columns, use cvCloneMat. cvGetCol(arr, submat, col) is a shortcut for
00392 cvGetCols(arr, submat, col, col+1).
00393 @param arr Input array
00394 @param submat Pointer to the resulting sub-array header
00395 @param start_col Zero-based index of the starting column (inclusive) of the span
00396 @param end_col Zero-based index of the ending column (exclusive) of the span
00397  */
00398 CVAPI(CvMat*) cvGetCols( const CvArr* arr, CvMat* submat,
00399                         int start_col, int end_col );
00400 
00401 /** @overload
00402 @param arr Input array
00403 @param submat Pointer to the resulting sub-array header
00404 @param col Zero-based index of the selected column
00405 */
00406 CV_INLINE  CvMat*  cvGetCol( const CvArr* arr, CvMat* submat, int col )
00407 {
00408     return cvGetCols( arr, submat, col, col + 1 );
00409 }
00410 
00411 /** @brief Returns one of array diagonals.
00412 
00413 The function returns the header, corresponding to a specified diagonal of the input array.
00414 @param arr Input array
00415 @param submat Pointer to the resulting sub-array header
00416 @param diag Index of the array diagonal. Zero value corresponds to the main diagonal, -1
00417 corresponds to the diagonal above the main, 1 corresponds to the diagonal below the main, and so
00418 forth.
00419  */
00420 CVAPI(CvMat*) cvGetDiag( const CvArr* arr, CvMat* submat,
00421                             int diag CV_DEFAULT(0));
00422 
00423 /** low-level scalar <-> raw data conversion functions */
00424 CVAPI(void) cvScalarToRawData( const CvScalar * scalar, void* data, int type,
00425                               int extend_to_12 CV_DEFAULT(0) );
00426 
00427 CVAPI(void) cvRawDataToScalar( const void* data, int type, CvScalar * scalar );
00428 
00429 /** @brief Creates a new matrix header but does not allocate the matrix data.
00430 
00431 The function allocates a header for a multi-dimensional dense array. The array data can further be
00432 allocated using cvCreateData or set explicitly to user-allocated data via cvSetData.
00433 @param dims Number of array dimensions
00434 @param sizes Array of dimension sizes
00435 @param type Type of array elements, see cvCreateMat
00436  */
00437 CVAPI(CvMatND *)  cvCreateMatNDHeader( int dims, const int* sizes, int type );
00438 
00439 /** @brief Creates the header and allocates the data for a multi-dimensional dense array.
00440 
00441 This function call is equivalent to the following code:
00442 @code
00443     CvMatND* mat = cvCreateMatNDHeader(dims, sizes, type);
00444     cvCreateData(mat);
00445 @endcode
00446 @param dims Number of array dimensions. This must not exceed CV_MAX_DIM (32 by default, but can be
00447 changed at build time).
00448 @param sizes Array of dimension sizes.
00449 @param type Type of array elements, see cvCreateMat .
00450  */
00451 CVAPI(CvMatND *)  cvCreateMatND( int dims, const int* sizes, int type );
00452 
00453 /** @brief Initializes a pre-allocated multi-dimensional array header.
00454 
00455 @param mat A pointer to the array header to be initialized
00456 @param dims The number of array dimensions
00457 @param sizes An array of dimension sizes
00458 @param type Type of array elements, see cvCreateMat
00459 @param data Optional data pointer assigned to the matrix header
00460  */
00461 CVAPI(CvMatND *)  cvInitMatNDHeader( CvMatND * mat, int dims, const int* sizes,
00462                                     int type, void* data CV_DEFAULT(NULL) );
00463 
00464 /** @brief Deallocates a multi-dimensional array.
00465 
00466 The function decrements the array data reference counter and releases the array header. If the
00467 reference counter reaches 0, it also deallocates the data. :
00468 @code
00469     if(*mat )
00470         cvDecRefData(*mat);
00471     cvFree((void**)mat);
00472 @endcode
00473 @param mat Double pointer to the array
00474  */
00475 CV_INLINE  void  cvReleaseMatND( CvMatND ** mat )
00476 {
00477     cvReleaseMat( (CvMat**)mat );
00478 }
00479 
00480 /** Creates a copy of CvMatND (except, may be, steps) */
00481 CVAPI(CvMatND *) cvCloneMatND( const CvMatND * mat );
00482 
00483 /** @brief Creates sparse array.
00484 
00485 The function allocates a multi-dimensional sparse array. Initially the array contain no elements,
00486 that is PtrND and other related functions will return 0 for every index.
00487 @param dims Number of array dimensions. In contrast to the dense matrix, the number of dimensions is
00488 practically unlimited (up to \f$2^{16}\f$ ).
00489 @param sizes Array of dimension sizes
00490 @param type Type of array elements. The same as for CvMat
00491  */
00492 CVAPI(CvSparseMat*)  cvCreateSparseMat( int dims, const int* sizes, int type );
00493 
00494 /** @brief Deallocates sparse array.
00495 
00496 The function releases the sparse array and clears the array pointer upon exit.
00497 @param mat Double pointer to the array
00498  */
00499 CVAPI(void)  cvReleaseSparseMat( CvSparseMat** mat );
00500 
00501 /** Creates a copy of CvSparseMat (except, may be, zero items) */
00502 CVAPI(CvSparseMat*) cvCloneSparseMat( const CvSparseMat* mat );
00503 
00504 /** @brief Initializes sparse array elements iterator.
00505 
00506 The function initializes iterator of sparse array elements and returns pointer to the first element,
00507 or NULL if the array is empty.
00508 @param mat Input array
00509 @param mat_iterator Initialized iterator
00510  */
00511 CVAPI(CvSparseNode*) cvInitSparseMatIterator( const CvSparseMat* mat,
00512                                               CvSparseMatIterator* mat_iterator );
00513 
00514 /** @brief Returns the next sparse matrix element
00515 
00516 The function moves iterator to the next sparse matrix element and returns pointer to it. In the
00517 current version there is no any particular order of the elements, because they are stored in the
00518 hash table. The sample below demonstrates how to iterate through the sparse matrix:
00519 @code
00520     // print all the non-zero sparse matrix elements and compute their sum
00521     double sum = 0;
00522     int i, dims = cvGetDims(sparsemat);
00523     CvSparseMatIterator it;
00524     CvSparseNode* node = cvInitSparseMatIterator(sparsemat, &it);
00525 
00526     for(; node != 0; node = cvGetNextSparseNode(&it))
00527     {
00528         int* idx = CV_NODE_IDX(array, node);
00529         float val = *(float*)CV_NODE_VAL(array, node);
00530         printf("M");
00531         for(i = 0; i < dims; i++ )
00532             printf("[%d]", idx[i]);
00533         printf("=%g\n", val);
00534 
00535         sum += val;
00536     }
00537 
00538     printf("nTotal sum = %g\n", sum);
00539 @endcode
00540 @param mat_iterator Sparse array iterator
00541  */
00542 CV_INLINE CvSparseNode* cvGetNextSparseNode( CvSparseMatIterator* mat_iterator )
00543 {
00544     if( mat_iterator->node->next )
00545         return mat_iterator->node = mat_iterator->node->next;
00546     else
00547     {
00548         int idx;
00549         for( idx = ++mat_iterator->curidx; idx < mat_iterator->mat->hashsize; idx++ )
00550         {
00551             CvSparseNode* node = (CvSparseNode*)mat_iterator->mat->hashtable[idx];
00552             if( node )
00553             {
00554                 mat_iterator->curidx = idx;
00555                 return mat_iterator->node = node;
00556             }
00557         }
00558         return NULL;
00559     }
00560 }
00561 
00562 
00563 #define CV_MAX_ARR 10
00564 
00565 /** matrix iterator: used for n-ary operations on dense arrays */
00566 typedef struct CvNArrayIterator
00567 {
00568     int count; /**< number of arrays */
00569     int dims; /**< number of dimensions to iterate */
00570     CvSize size; /**< maximal common linear size: { width = size, height = 1 } */
00571     uchar* ptr[CV_MAX_ARR]; /**< pointers to the array slices */
00572     int stack[CV_MAX_DIM]; /**< for internal use */
00573     CvMatND * hdr[CV_MAX_ARR]; /**< pointers to the headers of the
00574                                  matrices that are processed */
00575 }
00576 CvNArrayIterator;
00577 
00578 #define CV_NO_DEPTH_CHECK     1
00579 #define CV_NO_CN_CHECK        2
00580 #define CV_NO_SIZE_CHECK      4
00581 
00582 /** initializes iterator that traverses through several arrays simulteneously
00583    (the function together with cvNextArraySlice is used for
00584     N-ari element-wise operations) */
00585 CVAPI(int) cvInitNArrayIterator( int count, CvArr** arrs,
00586                                  const CvArr* mask, CvMatND * stubs,
00587                                  CvNArrayIterator* array_iterator,
00588                                  int flags CV_DEFAULT(0) );
00589 
00590 /** returns zero value if iteration is finished, non-zero (slice length) otherwise */
00591 CVAPI(int) cvNextNArraySlice( CvNArrayIterator* array_iterator );
00592 
00593 
00594 /** @brief Returns type of array elements.
00595 
00596 The function returns type of the array elements. In the case of IplImage the type is converted to
00597 CvMat-like representation. For example, if the image has been created as:
00598 @code
00599     IplImage* img = cvCreateImage(cvSize(640, 480), IPL_DEPTH_8U, 3);
00600 @endcode
00601 The code cvGetElemType(img) will return CV_8UC3.
00602 @param arr Input array
00603  */
00604 CVAPI(int) cvGetElemType( const CvArr* arr );
00605 
00606 /** @brief Return number of array dimensions
00607 
00608 The function returns the array dimensionality and the array of dimension sizes. In the case of
00609 IplImage or CvMat it always returns 2 regardless of number of image/matrix rows. For example, the
00610 following code calculates total number of array elements:
00611 @code
00612     int sizes[CV_MAX_DIM];
00613     int i, total = 1;
00614     int dims = cvGetDims(arr, size);
00615     for(i = 0; i < dims; i++ )
00616         total *= sizes[i];
00617 @endcode
00618 @param arr Input array
00619 @param sizes Optional output vector of the array dimension sizes. For 2d arrays the number of rows
00620 (height) goes first, number of columns (width) next.
00621  */
00622 CVAPI(int) cvGetDims( const CvArr* arr, int* sizes CV_DEFAULT(NULL) );
00623 
00624 
00625 /** @brief Returns array size along the specified dimension.
00626 
00627 @param arr Input array
00628 @param index Zero-based dimension index (for matrices 0 means number of rows, 1 means number of
00629 columns; for images 0 means height, 1 means width)
00630  */
00631 CVAPI(int) cvGetDimSize( const CvArr* arr, int index );
00632 
00633 
00634 /** @brief Return pointer to a particular array element.
00635 
00636 The functions return a pointer to a specific array element. Number of array dimension should match
00637 to the number of indices passed to the function except for cvPtr1D function that can be used for
00638 sequential access to 1D, 2D or nD dense arrays.
00639 
00640 The functions can be used for sparse arrays as well - if the requested node does not exist they
00641 create it and set it to zero.
00642 
00643 All these as well as other functions accessing array elements ( cvGetND , cvGetRealND , cvSet
00644 , cvSetND , cvSetRealND ) raise an error in case if the element index is out of range.
00645 @param arr Input array
00646 @param idx0 The first zero-based component of the element index
00647 @param type Optional output parameter: type of matrix elements
00648  */
00649 CVAPI(uchar*) cvPtr1D( const CvArr* arr, int idx0, int* type CV_DEFAULT(NULL));
00650 /** @overload */
00651 CVAPI(uchar*) cvPtr2D( const CvArr* arr, int idx0, int idx1, int* type CV_DEFAULT(NULL) );
00652 /** @overload */
00653 CVAPI(uchar*) cvPtr3D( const CvArr* arr, int idx0, int idx1, int idx2,
00654                       int* type CV_DEFAULT(NULL));
00655 /** @overload
00656 @param arr Input array
00657 @param idx Array of the element indices
00658 @param type Optional output parameter: type of matrix elements
00659 @param create_node Optional input parameter for sparse matrices. Non-zero value of the parameter
00660 means that the requested element is created if it does not exist already.
00661 @param precalc_hashval Optional input parameter for sparse matrices. If the pointer is not NULL,
00662 the function does not recalculate the node hash value, but takes it from the specified location.
00663 It is useful for speeding up pair-wise operations (TODO: provide an example)
00664 */
00665 CVAPI(uchar*) cvPtrND( const CvArr* arr, const int* idx, int* type CV_DEFAULT(NULL),
00666                       int create_node CV_DEFAULT(1),
00667                       unsigned* precalc_hashval CV_DEFAULT(NULL));
00668 
00669 /** @brief Return a specific array element.
00670 
00671 The functions return a specific array element. In the case of a sparse array the functions return 0
00672 if the requested node does not exist (no new node is created by the functions).
00673 @param arr Input array
00674 @param idx0 The first zero-based component of the element index
00675  */
00676 CVAPI(CvScalar ) cvGet1D( const CvArr* arr, int idx0 );
00677 /** @overload */
00678 CVAPI(CvScalar ) cvGet2D( const CvArr* arr, int idx0, int idx1 );
00679 /** @overload */
00680 CVAPI(CvScalar ) cvGet3D( const CvArr* arr, int idx0, int idx1, int idx2 );
00681 /** @overload
00682 @param arr Input array
00683 @param idx Array of the element indices
00684 */
00685 CVAPI(CvScalar ) cvGetND( const CvArr* arr, const int* idx );
00686 
00687 /** @brief Return a specific element of single-channel 1D, 2D, 3D or nD array.
00688 
00689 Returns a specific element of a single-channel array. If the array has multiple channels, a runtime
00690 error is raised. Note that Get?D functions can be used safely for both single-channel and
00691 multiple-channel arrays though they are a bit slower.
00692 
00693 In the case of a sparse array the functions return 0 if the requested node does not exist (no new
00694 node is created by the functions).
00695 @param arr Input array. Must have a single channel.
00696 @param idx0 The first zero-based component of the element index
00697  */
00698 CVAPI(double) cvGetReal1D( const CvArr* arr, int idx0 );
00699 /** @overload */
00700 CVAPI(double) cvGetReal2D( const CvArr* arr, int idx0, int idx1 );
00701 /** @overload */
00702 CVAPI(double) cvGetReal3D( const CvArr* arr, int idx0, int idx1, int idx2 );
00703 /** @overload
00704 @param arr Input array. Must have a single channel.
00705 @param idx Array of the element indices
00706 */
00707 CVAPI(double) cvGetRealND( const CvArr* arr, const int* idx );
00708 
00709 /** @brief Change the particular array element.
00710 
00711 The functions assign the new value to a particular array element. In the case of a sparse array the
00712 functions create the node if it does not exist yet.
00713 @param arr Input array
00714 @param idx0 The first zero-based component of the element index
00715 @param value The assigned value
00716  */
00717 CVAPI(void) cvSet1D( CvArr* arr, int idx0, CvScalar  value );
00718 /** @overload */
00719 CVAPI(void) cvSet2D( CvArr* arr, int idx0, int idx1, CvScalar  value );
00720 /** @overload */
00721 CVAPI(void) cvSet3D( CvArr* arr, int idx0, int idx1, int idx2, CvScalar  value );
00722 /** @overload
00723 @param arr Input array
00724 @param idx Array of the element indices
00725 @param value The assigned value
00726 */
00727 CVAPI(void) cvSetND( CvArr* arr, const int* idx, CvScalar  value );
00728 
00729 /** @brief Change a specific array element.
00730 
00731 The functions assign a new value to a specific element of a single-channel array. If the array has
00732 multiple channels, a runtime error is raised. Note that the Set\*D function can be used safely for
00733 both single-channel and multiple-channel arrays, though they are a bit slower.
00734 
00735 In the case of a sparse array the functions create the node if it does not yet exist.
00736 @param arr Input array
00737 @param idx0 The first zero-based component of the element index
00738 @param value The assigned value
00739  */
00740 CVAPI(void) cvSetReal1D( CvArr* arr, int idx0, double value );
00741 /** @overload */
00742 CVAPI(void) cvSetReal2D( CvArr* arr, int idx0, int idx1, double value );
00743 /** @overload */
00744 CVAPI(void) cvSetReal3D( CvArr* arr, int idx0,
00745                         int idx1, int idx2, double value );
00746 /** @overload
00747 @param arr Input array
00748 @param idx Array of the element indices
00749 @param value The assigned value
00750 */
00751 CVAPI(void) cvSetRealND( CvArr* arr, const int* idx, double value );
00752 
00753 /** clears element of ND dense array,
00754    in case of sparse arrays it deletes the specified node */
00755 CVAPI(void) cvClearND( CvArr* arr, const int* idx );
00756 
00757 /** @brief Returns matrix header for arbitrary array.
00758 
00759 The function returns a matrix header for the input array that can be a matrix - CvMat, an image -
00760 IplImage, or a multi-dimensional dense array - CvMatND (the third option is allowed only if
00761 allowND != 0) . In the case of matrix the function simply returns the input pointer. In the case of
00762 IplImage\* or CvMatND it initializes the header structure with parameters of the current image ROI
00763 and returns &header. Because COI is not supported by CvMat, it is returned separately.
00764 
00765 The function provides an easy way to handle both types of arrays - IplImage and CvMat using the same
00766 code. Input array must have non-zero data pointer, otherwise the function will report an error.
00767 
00768 @note If the input array is IplImage with planar data layout and COI set, the function returns the
00769 pointer to the selected plane and COI == 0. This feature allows user to process IplImage structures
00770 with planar data layout, even though OpenCV does not support such images.
00771 @param arr Input array
00772 @param header Pointer to CvMat structure used as a temporary buffer
00773 @param coi Optional output parameter for storing COI
00774 @param allowND If non-zero, the function accepts multi-dimensional dense arrays (CvMatND\*) and
00775 returns 2D matrix (if CvMatND has two dimensions) or 1D matrix (when CvMatND has 1 dimension or
00776 more than 2 dimensions). The CvMatND array must be continuous.
00777 @sa cvGetImage, cvarrToMat.
00778  */
00779 CVAPI(CvMat*) cvGetMat( const CvArr* arr, CvMat* header,
00780                        int* coi CV_DEFAULT(NULL),
00781                        int allowND CV_DEFAULT(0));
00782 
00783 /** @brief Returns image header for arbitrary array.
00784 
00785 The function returns the image header for the input array that can be a matrix (CvMat) or image
00786 (IplImage). In the case of an image the function simply returns the input pointer. In the case of
00787 CvMat it initializes an image_header structure with the parameters of the input matrix. Note that
00788 if we transform IplImage to CvMat using cvGetMat and then transform CvMat back to IplImage using
00789 this function, we will get different headers if the ROI is set in the original image.
00790 @param arr Input array
00791 @param image_header Pointer to IplImage structure used as a temporary buffer
00792  */
00793 CVAPI(IplImage*) cvGetImage( const CvArr* arr, IplImage* image_header );
00794 
00795 
00796 /** @brief Changes the shape of a multi-dimensional array without copying the data.
00797 
00798 The function is an advanced version of cvReshape that can work with multi-dimensional arrays as
00799 well (though it can work with ordinary images and matrices) and change the number of dimensions.
00800 
00801 Below are the two samples from the cvReshape description rewritten using cvReshapeMatND:
00802 @code
00803     IplImage* color_img = cvCreateImage(cvSize(320,240), IPL_DEPTH_8U, 3);
00804     IplImage gray_img_hdr, *gray_img;
00805     gray_img = (IplImage*)cvReshapeMatND(color_img, sizeof(gray_img_hdr), &gray_img_hdr, 1, 0, 0);
00806     ...
00807     int size[] = { 2, 2, 2 };
00808     CvMatND* mat = cvCreateMatND(3, size, CV_32F);
00809     CvMat row_header, *row;
00810     row = (CvMat*)cvReshapeMatND(mat, sizeof(row_header), &row_header, 0, 1, 0);
00811 @endcode
00812 In C, the header file for this function includes a convenient macro cvReshapeND that does away with
00813 the sizeof_header parameter. So, the lines containing the call to cvReshapeMatND in the examples
00814 may be replaced as follow:
00815 @code
00816     gray_img = (IplImage*)cvReshapeND(color_img, &gray_img_hdr, 1, 0, 0);
00817     ...
00818     row = (CvMat*)cvReshapeND(mat, &row_header, 0, 1, 0);
00819 @endcode
00820 @param arr Input array
00821 @param sizeof_header Size of output header to distinguish between IplImage, CvMat and CvMatND
00822 output headers
00823 @param header Output header to be filled
00824 @param new_cn New number of channels. new_cn = 0 means that the number of channels remains
00825 unchanged.
00826 @param new_dims New number of dimensions. new_dims = 0 means that the number of dimensions
00827 remains the same.
00828 @param new_sizes Array of new dimension sizes. Only new_dims-1 values are used, because the
00829 total number of elements must remain the same. Thus, if new_dims = 1, new_sizes array is not
00830 used.
00831  */
00832 CVAPI(CvArr*) cvReshapeMatND( const CvArr* arr,
00833                              int sizeof_header, CvArr* header,
00834                              int new_cn, int new_dims, int* new_sizes );
00835 
00836 #define cvReshapeND( arr, header, new_cn, new_dims, new_sizes )   \
00837       cvReshapeMatND( (arr), sizeof(*(header)), (header),         \
00838                       (new_cn), (new_dims), (new_sizes))
00839 
00840 /** @brief Changes shape of matrix/image without copying data.
00841 
00842 The function initializes the CvMat header so that it points to the same data as the original array
00843 but has a different shape - different number of channels, different number of rows, or both.
00844 
00845 The following example code creates one image buffer and two image headers, the first is for a
00846 320x240x3 image and the second is for a 960x240x1 image:
00847 @code
00848     IplImage* color_img = cvCreateImage(cvSize(320,240), IPL_DEPTH_8U, 3);
00849     CvMat gray_mat_hdr;
00850     IplImage gray_img_hdr, *gray_img;
00851     cvReshape(color_img, &gray_mat_hdr, 1);
00852     gray_img = cvGetImage(&gray_mat_hdr, &gray_img_hdr);
00853 @endcode
00854 And the next example converts a 3x3 matrix to a single 1x9 vector:
00855 @code
00856     CvMat* mat = cvCreateMat(3, 3, CV_32F);
00857     CvMat row_header, *row;
00858     row = cvReshape(mat, &row_header, 0, 1);
00859 @endcode
00860 @param arr Input array
00861 @param header Output header to be filled
00862 @param new_cn New number of channels. 'new_cn = 0' means that the number of channels remains
00863 unchanged.
00864 @param new_rows New number of rows. 'new_rows = 0' means that the number of rows remains
00865 unchanged unless it needs to be changed according to new_cn value.
00866 */
00867 CVAPI(CvMat*) cvReshape( const CvArr* arr, CvMat* header,
00868                         int new_cn, int new_rows CV_DEFAULT(0) );
00869 
00870 /** Repeats source 2d array several times in both horizontal and
00871    vertical direction to fill destination array */
00872 CVAPI(void) cvRepeat( const CvArr* src, CvArr* dst );
00873 
00874 /** @brief Allocates array data
00875 
00876 The function allocates image, matrix or multi-dimensional dense array data. Note that in the case of
00877 matrix types OpenCV allocation functions are used. In the case of IplImage they are used unless
00878 CV_TURN_ON_IPL_COMPATIBILITY() has been called before. In the latter case IPL functions are used
00879 to allocate the data.
00880 @param arr Array header
00881  */
00882 CVAPI(void)  cvCreateData( CvArr* arr );
00883 
00884 /** @brief Releases array data.
00885 
00886 The function releases the array data. In the case of CvMat or CvMatND it simply calls
00887 cvDecRefData(), that is the function can not deallocate external data. See also the note to
00888 cvCreateData .
00889 @param arr Array header
00890  */
00891 CVAPI(void)  cvReleaseData( CvArr* arr );
00892 
00893 /** @brief Assigns user data to the array header.
00894 
00895 The function assigns user data to the array header. Header should be initialized before using
00896 cvCreateMatHeader, cvCreateImageHeader, cvCreateMatNDHeader, cvInitMatHeader,
00897 cvInitImageHeader or cvInitMatNDHeader.
00898 @param arr Array header
00899 @param data User data
00900 @param step Full row length in bytes
00901  */
00902 CVAPI(void)  cvSetData( CvArr* arr, void* data, int step );
00903 
00904 /** @brief Retrieves low-level information about the array.
00905 
00906 The function fills output variables with low-level information about the array data. All output
00907 
00908 parameters are optional, so some of the pointers may be set to NULL. If the array is IplImage with
00909 ROI set, the parameters of ROI are returned.
00910 
00911 The following example shows how to get access to array elements. It computes absolute values of the
00912 array elements :
00913 @code
00914     float* data;
00915     int step;
00916     CvSize size;
00917 
00918     cvGetRawData(array, (uchar**)&data, &step, &size);
00919     step /= sizeof(data[0]);
00920 
00921     for(int y = 0; y < size.height; y++, data += step )
00922         for(int x = 0; x < size.width; x++ )
00923             data[x] = (float)fabs(data[x]);
00924 @endcode
00925 @param arr Array header
00926 @param data Output pointer to the whole image origin or ROI origin if ROI is set
00927 @param step Output full row length in bytes
00928 @param roi_size Output ROI size
00929  */
00930 CVAPI(void) cvGetRawData( const CvArr* arr, uchar** data,
00931                          int* step CV_DEFAULT(NULL),
00932                          CvSize* roi_size CV_DEFAULT(NULL));
00933 
00934 /** @brief Returns size of matrix or image ROI.
00935 
00936 The function returns number of rows (CvSize::height) and number of columns (CvSize::width) of the
00937 input matrix or image. In the case of image the size of ROI is returned.
00938 @param arr array header
00939  */
00940 CVAPI(CvSize) cvGetSize( const CvArr* arr );
00941 
00942 /** @brief Copies one array to another.
00943 
00944 The function copies selected elements from an input array to an output array:
00945 
00946 \f[\texttt{dst} (I)= \texttt{src} (I)  \quad \text{if} \quad \texttt{mask} (I)  \ne 0.\f]
00947 
00948 If any of the passed arrays is of IplImage type, then its ROI and COI fields are used. Both arrays
00949 must have the same type, the same number of dimensions, and the same size. The function can also
00950 copy sparse arrays (mask is not supported in this case).
00951 @param src The source array
00952 @param dst The destination array
00953 @param mask Operation mask, 8-bit single channel array; specifies elements of the destination array
00954 to be changed
00955  */
00956 CVAPI(void)  cvCopy( const CvArr* src, CvArr* dst,
00957                      const CvArr* mask CV_DEFAULT(NULL) );
00958 
00959 /** @brief Sets every element of an array to a given value.
00960 
00961 The function copies the scalar value to every selected element of the destination array:
00962 \f[\texttt{arr} (I)= \texttt{value} \quad \text{if} \quad \texttt{mask} (I)  \ne 0\f]
00963 If array arr is of IplImage type, then is ROI used, but COI must not be set.
00964 @param arr The destination array
00965 @param value Fill value
00966 @param mask Operation mask, 8-bit single channel array; specifies elements of the destination
00967 array to be changed
00968  */
00969 CVAPI(void)  cvSet( CvArr* arr, CvScalar  value,
00970                     const CvArr* mask CV_DEFAULT(NULL) );
00971 
00972 /** @brief Clears the array.
00973 
00974 The function clears the array. In the case of dense arrays (CvMat, CvMatND or IplImage),
00975 cvZero(array) is equivalent to cvSet(array,cvScalarAll(0),0). In the case of sparse arrays all the
00976 elements are removed.
00977 @param arr Array to be cleared
00978  */
00979 CVAPI(void)  cvSetZero( CvArr* arr );
00980 #define cvZero  cvSetZero
00981 
00982 
00983 /** Splits a multi-channel array into the set of single-channel arrays or
00984    extracts particular [color] plane */
00985 CVAPI(void)  cvSplit( const CvArr* src, CvArr* dst0, CvArr* dst1,
00986                       CvArr* dst2, CvArr* dst3 );
00987 
00988 /** Merges a set of single-channel arrays into the single multi-channel array
00989    or inserts one particular [color] plane to the array */
00990 CVAPI(void)  cvMerge( const CvArr* src0, const CvArr* src1,
00991                       const CvArr* src2, const CvArr* src3,
00992                       CvArr* dst );
00993 
00994 /** Copies several channels from input arrays to
00995    certain channels of output arrays */
00996 CVAPI(void)  cvMixChannels( const CvArr** src, int src_count,
00997                             CvArr** dst, int dst_count,
00998                             const int* from_to, int pair_count );
00999 
01000 /** @brief Converts one array to another with optional linear transformation.
01001 
01002 The function has several different purposes, and thus has several different names. It copies one
01003 array to another with optional scaling, which is performed first, and/or optional type conversion,
01004 performed after:
01005 
01006 \f[\texttt{dst} (I) =  \texttt{scale} \texttt{src} (I) + ( \texttt{shift} _0, \texttt{shift} _1,...)\f]
01007 
01008 All the channels of multi-channel arrays are processed independently.
01009 
01010 The type of conversion is done with rounding and saturation, that is if the result of scaling +
01011 conversion can not be represented exactly by a value of the destination array element type, it is
01012 set to the nearest representable value on the real axis.
01013 @param src Source array
01014 @param dst Destination array
01015 @param scale Scale factor
01016 @param shift Value added to the scaled source array elements
01017  */
01018 CVAPI(void)  cvConvertScale( const CvArr* src, CvArr* dst,
01019                              double scale CV_DEFAULT(1),
01020                              double shift CV_DEFAULT(0) );
01021 #define cvCvtScale cvConvertScale
01022 #define cvScale  cvConvertScale
01023 #define cvConvert( src, dst )  cvConvertScale( (src), (dst), 1, 0 )
01024 
01025 
01026 /** Performs linear transformation on every source array element,
01027    stores absolute value of the result:
01028    dst(x,y,c) = abs(scale*src(x,y,c)+shift).
01029    destination array must have 8u type.
01030    In other cases one may use cvConvertScale + cvAbsDiffS */
01031 CVAPI(void)  cvConvertScaleAbs( const CvArr* src, CvArr* dst,
01032                                 double scale CV_DEFAULT(1),
01033                                 double shift CV_DEFAULT(0) );
01034 #define cvCvtScaleAbs  cvConvertScaleAbs
01035 
01036 
01037 /** checks termination criteria validity and
01038    sets eps to default_eps (if it is not set),
01039    max_iter to default_max_iters (if it is not set)
01040 */
01041 CVAPI(CvTermCriteria ) cvCheckTermCriteria( CvTermCriteria  criteria,
01042                                            double default_eps,
01043                                            int default_max_iters );
01044 
01045 /****************************************************************************************\
01046 *                   Arithmetic, logic and comparison operations                          *
01047 \****************************************************************************************/
01048 
01049 /** dst(mask) = src1(mask) + src2(mask) */
01050 CVAPI(void)  cvAdd( const CvArr* src1, const CvArr* src2, CvArr* dst,
01051                     const CvArr* mask CV_DEFAULT(NULL));
01052 
01053 /** dst(mask) = src(mask) + value */
01054 CVAPI(void)  cvAddS( const CvArr* src, CvScalar  value, CvArr* dst,
01055                      const CvArr* mask CV_DEFAULT(NULL));
01056 
01057 /** dst(mask) = src1(mask) - src2(mask) */
01058 CVAPI(void)  cvSub( const CvArr* src1, const CvArr* src2, CvArr* dst,
01059                     const CvArr* mask CV_DEFAULT(NULL));
01060 
01061 /** dst(mask) = src(mask) - value = src(mask) + (-value) */
01062 CV_INLINE  void  cvSubS( const CvArr* src, CvScalar  value, CvArr* dst,
01063                          const CvArr* mask CV_DEFAULT(NULL))
01064 {
01065     cvAddS( src, cvScalar( -value.val[0], -value.val[1], -value.val[2], -value.val[3]),
01066             dst, mask );
01067 }
01068 
01069 /** dst(mask) = value - src(mask) */
01070 CVAPI(void)  cvSubRS( const CvArr* src, CvScalar  value, CvArr* dst,
01071                       const CvArr* mask CV_DEFAULT(NULL));
01072 
01073 /** dst(idx) = src1(idx) * src2(idx) * scale
01074    (scaled element-wise multiplication of 2 arrays) */
01075 CVAPI(void)  cvMul( const CvArr* src1, const CvArr* src2,
01076                     CvArr* dst, double scale CV_DEFAULT(1) );
01077 
01078 /** element-wise division/inversion with scaling:
01079     dst(idx) = src1(idx) * scale / src2(idx)
01080     or dst(idx) = scale / src2(idx) if src1 == 0 */
01081 CVAPI(void)  cvDiv( const CvArr* src1, const CvArr* src2,
01082                     CvArr* dst, double scale CV_DEFAULT(1));
01083 
01084 /** dst = src1 * scale + src2 */
01085 CVAPI(void)  cvScaleAdd( const CvArr* src1, CvScalar  scale,
01086                          const CvArr* src2, CvArr* dst );
01087 #define cvAXPY( A, real_scalar, B, C ) cvScaleAdd(A, cvRealScalar(real_scalar), B, C)
01088 
01089 /** dst = src1 * alpha + src2 * beta + gamma */
01090 CVAPI(void)  cvAddWeighted( const CvArr* src1, double alpha,
01091                             const CvArr* src2, double beta,
01092                             double gamma, CvArr* dst );
01093 
01094 /** @brief Calculates the dot product of two arrays in Euclidean metrics.
01095 
01096 The function calculates and returns the Euclidean dot product of two arrays.
01097 
01098 \f[src1  \bullet src2 =  \sum _I ( \texttt{src1} (I)  \texttt{src2} (I))\f]
01099 
01100 In the case of multiple channel arrays, the results for all channels are accumulated. In particular,
01101 cvDotProduct(a,a) where a is a complex vector, will return \f$||\texttt{a}||^2\f$. The function can
01102 process multi-dimensional arrays, row by row, layer by layer, and so on.
01103 @param src1 The first source array
01104 @param src2 The second source array
01105  */
01106 CVAPI(double)  cvDotProduct( const CvArr* src1, const CvArr* src2 );
01107 
01108 /** dst(idx) = src1(idx) & src2(idx) */
01109 CVAPI(void) cvAnd( const CvArr* src1, const CvArr* src2,
01110                   CvArr* dst, const CvArr* mask CV_DEFAULT(NULL));
01111 
01112 /** dst(idx) = src(idx) & value */
01113 CVAPI(void) cvAndS( const CvArr* src, CvScalar  value,
01114                    CvArr* dst, const CvArr* mask CV_DEFAULT(NULL));
01115 
01116 /** dst(idx) = src1(idx) | src2(idx) */
01117 CVAPI(void) cvOr( const CvArr* src1, const CvArr* src2,
01118                  CvArr* dst, const CvArr* mask CV_DEFAULT(NULL));
01119 
01120 /** dst(idx) = src(idx) | value */
01121 CVAPI(void) cvOrS( const CvArr* src, CvScalar  value,
01122                   CvArr* dst, const CvArr* mask CV_DEFAULT(NULL));
01123 
01124 /** dst(idx) = src1(idx) ^ src2(idx) */
01125 CVAPI(void) cvXor( const CvArr* src1, const CvArr* src2,
01126                   CvArr* dst, const CvArr* mask CV_DEFAULT(NULL));
01127 
01128 /** dst(idx) = src(idx) ^ value */
01129 CVAPI(void) cvXorS( const CvArr* src, CvScalar  value,
01130                    CvArr* dst, const CvArr* mask CV_DEFAULT(NULL));
01131 
01132 /** dst(idx) = ~src(idx) */
01133 CVAPI(void) cvNot( const CvArr* src, CvArr* dst );
01134 
01135 /** dst(idx) = lower(idx) <= src(idx) < upper(idx) */
01136 CVAPI(void) cvInRange( const CvArr* src, const CvArr* lower,
01137                       const CvArr* upper, CvArr* dst );
01138 
01139 /** dst(idx) = lower <= src(idx) < upper */
01140 CVAPI(void) cvInRangeS( const CvArr* src, CvScalar  lower,
01141                        CvScalar  upper, CvArr* dst );
01142 
01143 #define CV_CMP_EQ   0
01144 #define CV_CMP_GT   1
01145 #define CV_CMP_GE   2
01146 #define CV_CMP_LT   3
01147 #define CV_CMP_LE   4
01148 #define CV_CMP_NE   5
01149 
01150 /** The comparison operation support single-channel arrays only.
01151    Destination image should be 8uC1 or 8sC1 */
01152 
01153 /** dst(idx) = src1(idx) _cmp_op_ src2(idx) */
01154 CVAPI(void) cvCmp( const CvArr* src1, const CvArr* src2, CvArr* dst, int cmp_op );
01155 
01156 /** dst(idx) = src1(idx) _cmp_op_ value */
01157 CVAPI(void) cvCmpS( const CvArr* src, double value, CvArr* dst, int cmp_op );
01158 
01159 /** dst(idx) = min(src1(idx),src2(idx)) */
01160 CVAPI(void) cvMin( const CvArr* src1, const CvArr* src2, CvArr* dst );
01161 
01162 /** dst(idx) = max(src1(idx),src2(idx)) */
01163 CVAPI(void) cvMax( const CvArr* src1, const CvArr* src2, CvArr* dst );
01164 
01165 /** dst(idx) = min(src(idx),value) */
01166 CVAPI(void) cvMinS( const CvArr* src, double value, CvArr* dst );
01167 
01168 /** dst(idx) = max(src(idx),value) */
01169 CVAPI(void) cvMaxS( const CvArr* src, double value, CvArr* dst );
01170 
01171 /** dst(x,y,c) = abs(src1(x,y,c) - src2(x,y,c)) */
01172 CVAPI(void) cvAbsDiff( const CvArr* src1, const CvArr* src2, CvArr* dst );
01173 
01174 /** dst(x,y,c) = abs(src(x,y,c) - value(c)) */
01175 CVAPI(void) cvAbsDiffS( const CvArr* src, CvArr* dst, CvScalar  value );
01176 #define cvAbs( src, dst ) cvAbsDiffS( (src), (dst), cvScalarAll(0))
01177 
01178 /****************************************************************************************\
01179 *                                Math operations                                         *
01180 \****************************************************************************************/
01181 
01182 /** Does cartesian->polar coordinates conversion.
01183    Either of output components (magnitude or angle) is optional */
01184 CVAPI(void)  cvCartToPolar( const CvArr* x, const CvArr* y,
01185                             CvArr* magnitude, CvArr* angle CV_DEFAULT(NULL),
01186                             int angle_in_degrees CV_DEFAULT(0));
01187 
01188 /** Does polar->cartesian coordinates conversion.
01189    Either of output components (magnitude or angle) is optional.
01190    If magnitude is missing it is assumed to be all 1's */
01191 CVAPI(void)  cvPolarToCart( const CvArr* magnitude, const CvArr* angle,
01192                             CvArr* x, CvArr* y,
01193                             int angle_in_degrees CV_DEFAULT(0));
01194 
01195 /** Does powering: dst(idx) = src(idx)^power */
01196 CVAPI(void)  cvPow( const CvArr* src, CvArr* dst, double power );
01197 
01198 /** Does exponention: dst(idx) = exp(src(idx)).
01199    Overflow is not handled yet. Underflow is handled.
01200    Maximal relative error is ~7e-6 for single-precision input */
01201 CVAPI(void)  cvExp( const CvArr* src, CvArr* dst );
01202 
01203 /** Calculates natural logarithms: dst(idx) = log(abs(src(idx))).
01204    Logarithm of 0 gives large negative number(~-700)
01205    Maximal relative error is ~3e-7 for single-precision output
01206 */
01207 CVAPI(void)  cvLog( const CvArr* src, CvArr* dst );
01208 
01209 /** Fast arctangent calculation */
01210 CVAPI(float) cvFastArctan( float y, float x );
01211 
01212 /** Fast cubic root calculation */
01213 CVAPI(float)  cvCbrt( float value );
01214 
01215 #define  CV_CHECK_RANGE    1
01216 #define  CV_CHECK_QUIET    2
01217 /** Checks array values for NaNs, Infs or simply for too large numbers
01218    (if CV_CHECK_RANGE is set). If CV_CHECK_QUIET is set,
01219    no runtime errors is raised (function returns zero value in case of "bad" values).
01220    Otherwise cvError is called */
01221 CVAPI(int)  cvCheckArr( const CvArr* arr, int flags CV_DEFAULT(0),
01222                         double min_val CV_DEFAULT(0), double max_val CV_DEFAULT(0));
01223 #define cvCheckArray cvCheckArr
01224 
01225 #define CV_RAND_UNI      0
01226 #define CV_RAND_NORMAL   1
01227 
01228 /** @brief Fills an array with random numbers and updates the RNG state.
01229 
01230 The function fills the destination array with uniformly or normally distributed random numbers.
01231 @param rng CvRNG state initialized by cvRNG
01232 @param arr The destination array
01233 @param dist_type Distribution type
01234 > -   **CV_RAND_UNI** uniform distribution
01235 > -   **CV_RAND_NORMAL** normal or Gaussian distribution
01236 @param param1 The first parameter of the distribution. In the case of a uniform distribution it is
01237 the inclusive lower boundary of the random numbers range. In the case of a normal distribution it
01238 is the mean value of the random numbers.
01239 @param param2 The second parameter of the distribution. In the case of a uniform distribution it
01240 is the exclusive upper boundary of the random numbers range. In the case of a normal distribution
01241 it is the standard deviation of the random numbers.
01242 @sa randu, randn, RNG::fill.
01243  */
01244 CVAPI(void) cvRandArr( CvRNG* rng, CvArr* arr, int dist_type,
01245                       CvScalar  param1, CvScalar  param2 );
01246 
01247 CVAPI(void) cvRandShuffle( CvArr* mat, CvRNG* rng,
01248                            double iter_factor CV_DEFAULT(1.));
01249 
01250 #define CV_SORT_EVERY_ROW 0
01251 #define CV_SORT_EVERY_COLUMN 1
01252 #define CV_SORT_ASCENDING 0
01253 #define CV_SORT_DESCENDING 16
01254 
01255 CVAPI(void) cvSort( const CvArr* src, CvArr* dst CV_DEFAULT(NULL),
01256                     CvArr* idxmat CV_DEFAULT(NULL),
01257                     int flags CV_DEFAULT(0));
01258 
01259 /** Finds real roots of a cubic equation */
01260 CVAPI(int) cvSolveCubic( const CvMat* coeffs, CvMat* roots );
01261 
01262 /** Finds all real and complex roots of a polynomial equation */
01263 CVAPI(void) cvSolvePoly(const CvMat* coeffs, CvMat *roots2,
01264       int maxiter CV_DEFAULT(20), int fig CV_DEFAULT(100));
01265 
01266 /****************************************************************************************\
01267 *                                Matrix operations                                       *
01268 \****************************************************************************************/
01269 
01270 /** @brief Calculates the cross product of two 3D vectors.
01271 
01272 The function calculates the cross product of two 3D vectors:
01273 \f[\texttt{dst} =  \texttt{src1} \times \texttt{src2}\f]
01274 or:
01275 \f[\begin{array}{l} \texttt{dst} _1 =  \texttt{src1} _2  \texttt{src2} _3 -  \texttt{src1} _3  \texttt{src2} _2 \\ \texttt{dst} _2 =  \texttt{src1} _3  \texttt{src2} _1 -  \texttt{src1} _1  \texttt{src2} _3 \\ \texttt{dst} _3 =  \texttt{src1} _1  \texttt{src2} _2 -  \texttt{src1} _2  \texttt{src2} _1 \end{array}\f]
01276 @param src1 The first source vector
01277 @param src2 The second source vector
01278 @param dst The destination vector
01279  */
01280 CVAPI(void)  cvCrossProduct( const CvArr* src1, const CvArr* src2, CvArr* dst );
01281 
01282 /** Matrix transform: dst = A*B + C, C is optional */
01283 #define cvMatMulAdd( src1, src2, src3, dst ) cvGEMM( (src1), (src2), 1., (src3), 1., (dst), 0 )
01284 #define cvMatMul( src1, src2, dst )  cvMatMulAdd( (src1), (src2), NULL, (dst))
01285 
01286 #define CV_GEMM_A_T 1
01287 #define CV_GEMM_B_T 2
01288 #define CV_GEMM_C_T 4
01289 /** Extended matrix transform:
01290    dst = alpha*op(A)*op(B) + beta*op(C), where op(X) is X or X^T */
01291 CVAPI(void)  cvGEMM( const CvArr* src1, const CvArr* src2, double alpha,
01292                      const CvArr* src3, double beta, CvArr* dst,
01293                      int tABC CV_DEFAULT(0));
01294 #define cvMatMulAddEx cvGEMM
01295 
01296 /** Transforms each element of source array and stores
01297    resultant vectors in destination array */
01298 CVAPI(void)  cvTransform( const CvArr* src, CvArr* dst,
01299                           const CvMat* transmat,
01300                           const CvMat* shiftvec CV_DEFAULT(NULL));
01301 #define cvMatMulAddS cvTransform
01302 
01303 /** Does perspective transform on every element of input array */
01304 CVAPI(void)  cvPerspectiveTransform( const CvArr* src, CvArr* dst,
01305                                      const CvMat* mat );
01306 
01307 /** Calculates (A-delta)*(A-delta)^T (order=0) or (A-delta)^T*(A-delta) (order=1) */
01308 CVAPI(void) cvMulTransposed( const CvArr* src, CvArr* dst, int order,
01309                              const CvArr* delta CV_DEFAULT(NULL),
01310                              double scale CV_DEFAULT(1.) );
01311 
01312 /** Tranposes matrix. Square matrices can be transposed in-place */
01313 CVAPI(void)  cvTranspose( const CvArr* src, CvArr* dst );
01314 #define cvT cvTranspose
01315 
01316 /** Completes the symmetric matrix from the lower (LtoR=0) or from the upper (LtoR!=0) part */
01317 CVAPI(void)  cvCompleteSymm( CvMat* matrix, int LtoR CV_DEFAULT(0) );
01318 
01319 /** Mirror array data around horizontal (flip=0),
01320    vertical (flip=1) or both(flip=-1) axises:
01321    cvFlip(src) flips images vertically and sequences horizontally (inplace) */
01322 CVAPI(void)  cvFlip( const CvArr* src, CvArr* dst CV_DEFAULT(NULL),
01323                      int flip_mode CV_DEFAULT(0));
01324 #define cvMirror cvFlip
01325 
01326 
01327 #define CV_SVD_MODIFY_A   1
01328 #define CV_SVD_U_T        2
01329 #define CV_SVD_V_T        4
01330 
01331 /** Performs Singular Value Decomposition of a matrix */
01332 CVAPI(void)   cvSVD( CvArr* A, CvArr* W, CvArr* U CV_DEFAULT(NULL),
01333                      CvArr* V CV_DEFAULT(NULL), int flags CV_DEFAULT(0));
01334 
01335 /** Performs Singular Value Back Substitution (solves A*X = B):
01336    flags must be the same as in cvSVD */
01337 CVAPI(void)   cvSVBkSb( const CvArr* W, const CvArr* U,
01338                         const CvArr* V, const CvArr* B,
01339                         CvArr* X, int flags );
01340 
01341 #define CV_LU  0
01342 #define CV_SVD 1
01343 #define CV_SVD_SYM 2
01344 #define CV_CHOLESKY 3
01345 #define CV_QR  4
01346 #define CV_NORMAL 16
01347 
01348 /** Inverts matrix */
01349 CVAPI(double)  cvInvert( const CvArr* src, CvArr* dst,
01350                          int method CV_DEFAULT(CV_LU));
01351 #define cvInv cvInvert
01352 
01353 /** Solves linear system (src1)*(dst) = (src2)
01354    (returns 0 if src1 is a singular and CV_LU method is used) */
01355 CVAPI(int)  cvSolve( const CvArr* src1, const CvArr* src2, CvArr* dst,
01356                      int method CV_DEFAULT(CV_LU));
01357 
01358 /** Calculates determinant of input matrix */
01359 CVAPI(double) cvDet( const CvArr* mat );
01360 
01361 /** Calculates trace of the matrix (sum of elements on the main diagonal) */
01362 CVAPI(CvScalar ) cvTrace( const CvArr* mat );
01363 
01364 /** Finds eigen values and vectors of a symmetric matrix */
01365 CVAPI(void)  cvEigenVV( CvArr* mat, CvArr* evects, CvArr* evals,
01366                         double eps CV_DEFAULT(0),
01367                         int lowindex CV_DEFAULT(-1),
01368                         int highindex CV_DEFAULT(-1));
01369 
01370 ///* Finds selected eigen values and vectors of a symmetric matrix */
01371 //CVAPI(void)  cvSelectedEigenVV( CvArr* mat, CvArr* evects, CvArr* evals,
01372 //                                int lowindex, int highindex );
01373 
01374 /** Makes an identity matrix (mat_ij = i == j) */
01375 CVAPI(void)  cvSetIdentity( CvArr* mat, CvScalar  value CV_DEFAULT(cvRealScalar(1)) );
01376 
01377 /** Fills matrix with given range of numbers */
01378 CVAPI(CvArr*)  cvRange( CvArr* mat, double start, double end );
01379 
01380 /**   @anchor core_c_CovarFlags
01381 @name Flags for cvCalcCovarMatrix
01382 @see cvCalcCovarMatrix
01383   @{
01384 */
01385 
01386 /** flag for cvCalcCovarMatrix, transpose([v1-avg, v2-avg,...]) * [v1-avg,v2-avg,...] */
01387 #define CV_COVAR_SCRAMBLED 0
01388 
01389 /** flag for cvCalcCovarMatrix, [v1-avg, v2-avg,...] * transpose([v1-avg,v2-avg,...]) */
01390 #define CV_COVAR_NORMAL    1
01391 
01392 /** flag for cvCalcCovarMatrix, do not calc average (i.e. mean vector) - use the input vector instead
01393    (useful for calculating covariance matrix by parts) */
01394 #define CV_COVAR_USE_AVG   2
01395 
01396 /** flag for cvCalcCovarMatrix, scale the covariance matrix coefficients by number of the vectors */
01397 #define CV_COVAR_SCALE     4
01398 
01399 /** flag for cvCalcCovarMatrix, all the input vectors are stored in a single matrix, as its rows */
01400 #define CV_COVAR_ROWS      8
01401 
01402 /** flag for cvCalcCovarMatrix, all the input vectors are stored in a single matrix, as its columns */
01403 #define CV_COVAR_COLS     16
01404 
01405 /** @} */
01406 
01407 /** Calculates covariation matrix for a set of vectors
01408 @see @ref core_c_CovarFlags "flags"
01409 */
01410 CVAPI(void)  cvCalcCovarMatrix( const CvArr** vects, int count,
01411                                 CvArr* cov_mat, CvArr* avg, int flags );
01412 
01413 #define CV_PCA_DATA_AS_ROW 0
01414 #define CV_PCA_DATA_AS_COL 1
01415 #define CV_PCA_USE_AVG 2
01416 CVAPI(void)  cvCalcPCA( const CvArr* data, CvArr* mean,
01417                         CvArr* eigenvals, CvArr* eigenvects, int flags );
01418 
01419 CVAPI(void)  cvProjectPCA( const CvArr* data, const CvArr* mean,
01420                            const CvArr* eigenvects, CvArr* result );
01421 
01422 CVAPI(void)  cvBackProjectPCA( const CvArr* proj, const CvArr* mean,
01423                                const CvArr* eigenvects, CvArr* result );
01424 
01425 /** Calculates Mahalanobis(weighted) distance */
01426 CVAPI(double)  cvMahalanobis( const CvArr* vec1, const CvArr* vec2, const CvArr* mat );
01427 #define cvMahalonobis  cvMahalanobis
01428 
01429 /****************************************************************************************\
01430 *                                    Array Statistics                                    *
01431 \****************************************************************************************/
01432 
01433 /** Finds sum of array elements */
01434 CVAPI(CvScalar )  cvSum( const CvArr* arr );
01435 
01436 /** Calculates number of non-zero pixels */
01437 CVAPI(int)  cvCountNonZero( const CvArr* arr );
01438 
01439 /** Calculates mean value of array elements */
01440 CVAPI(CvScalar )  cvAvg( const CvArr* arr, const CvArr* mask CV_DEFAULT(NULL) );
01441 
01442 /** Calculates mean and standard deviation of pixel values */
01443 CVAPI(void)  cvAvgSdv( const CvArr* arr, CvScalar * mean, CvScalar * std_dev,
01444                        const CvArr* mask CV_DEFAULT(NULL) );
01445 
01446 /** Finds global minimum, maximum and their positions */
01447 CVAPI(void)  cvMinMaxLoc( const CvArr* arr, double* min_val, double* max_val,
01448                           CvPoint* min_loc CV_DEFAULT(NULL),
01449                           CvPoint* max_loc CV_DEFAULT(NULL),
01450                           const CvArr* mask CV_DEFAULT(NULL) );
01451 
01452 /** @anchor core_c_NormFlags
01453   @name Flags for cvNorm and cvNormalize
01454   @{
01455 */
01456 #define CV_C            1
01457 #define CV_L1           2
01458 #define CV_L2           4
01459 #define CV_NORM_MASK    7
01460 #define CV_RELATIVE     8
01461 #define CV_DIFF         16
01462 #define CV_MINMAX       32
01463 
01464 #define CV_DIFF_C       (CV_DIFF | CV_C)
01465 #define CV_DIFF_L1      (CV_DIFF | CV_L1)
01466 #define CV_DIFF_L2      (CV_DIFF | CV_L2)
01467 #define CV_RELATIVE_C   (CV_RELATIVE | CV_C)
01468 #define CV_RELATIVE_L1  (CV_RELATIVE | CV_L1)
01469 #define CV_RELATIVE_L2  (CV_RELATIVE | CV_L2)
01470 /** @} */
01471 
01472 /** Finds norm, difference norm or relative difference norm for an array (or two arrays)
01473 @see ref core_c_NormFlags "flags"
01474 */
01475 CVAPI(double)  cvNorm( const CvArr* arr1, const CvArr* arr2 CV_DEFAULT(NULL),
01476                        int norm_type CV_DEFAULT(CV_L2),
01477                        const CvArr* mask CV_DEFAULT(NULL) );
01478 
01479 /** @see ref core_c_NormFlags "flags" */
01480 CVAPI(void)  cvNormalize( const CvArr* src, CvArr* dst,
01481                           double a CV_DEFAULT(1.), double b CV_DEFAULT(0.),
01482                           int norm_type CV_DEFAULT(CV_L2),
01483                           const CvArr* mask CV_DEFAULT(NULL) );
01484 
01485 /** @anchor core_c_ReduceFlags
01486   @name Flags for cvReduce
01487   @{
01488 */
01489 #define CV_REDUCE_SUM 0
01490 #define CV_REDUCE_AVG 1
01491 #define CV_REDUCE_MAX 2
01492 #define CV_REDUCE_MIN 3
01493 /** @} */
01494 
01495 /** @see @ref core_c_ReduceFlags "flags" */
01496 CVAPI(void)  cvReduce( const CvArr* src, CvArr* dst, int dim CV_DEFAULT(-1),
01497                        int op CV_DEFAULT(CV_REDUCE_SUM) );
01498 
01499 /****************************************************************************************\
01500 *                      Discrete Linear Transforms and Related Functions                  *
01501 \****************************************************************************************/
01502 
01503 /** @anchor core_c_DftFlags
01504   @name Flags for cvDFT, cvDCT and cvMulSpectrums
01505   @{
01506   */
01507 #define CV_DXT_FORWARD  0
01508 #define CV_DXT_INVERSE  1
01509 #define CV_DXT_SCALE    2 /**< divide result by size of array */
01510 #define CV_DXT_INV_SCALE (CV_DXT_INVERSE + CV_DXT_SCALE)
01511 #define CV_DXT_INVERSE_SCALE CV_DXT_INV_SCALE
01512 #define CV_DXT_ROWS     4 /**< transform each row individually */
01513 #define CV_DXT_MUL_CONJ 8 /**< conjugate the second argument of cvMulSpectrums */
01514 /** @} */
01515 
01516 /** Discrete Fourier Transform:
01517     complex->complex,
01518     real->ccs (forward),
01519     ccs->real (inverse)
01520 @see core_c_DftFlags "flags"
01521 */
01522 CVAPI(void)  cvDFT( const CvArr* src, CvArr* dst, int flags,
01523                     int nonzero_rows CV_DEFAULT(0) );
01524 #define cvFFT cvDFT
01525 
01526 /** Multiply results of DFTs: DFT(X)*DFT(Y) or DFT(X)*conj(DFT(Y))
01527 @see core_c_DftFlags "flags"
01528 */
01529 CVAPI(void)  cvMulSpectrums( const CvArr* src1, const CvArr* src2,
01530                              CvArr* dst, int flags );
01531 
01532 /** Finds optimal DFT vector size >= size0 */
01533 CVAPI(int)  cvGetOptimalDFTSize( int size0 );
01534 
01535 /** Discrete Cosine Transform
01536 @see core_c_DftFlags "flags"
01537 */
01538 CVAPI(void)  cvDCT( const CvArr* src, CvArr* dst, int flags );
01539 
01540 /****************************************************************************************\
01541 *                              Dynamic data structures                                   *
01542 \****************************************************************************************/
01543 
01544 /** Calculates length of sequence slice (with support of negative indices). */
01545 CVAPI(int) cvSliceLength( CvSlice slice, const CvSeq* seq );
01546 
01547 
01548 /** Creates new memory storage.
01549    block_size == 0 means that default,
01550    somewhat optimal size, is used (currently, it is 64K) */
01551 CVAPI(CvMemStorage*)  cvCreateMemStorage( int block_size CV_DEFAULT(0));
01552 
01553 
01554 /** Creates a memory storage that will borrow memory blocks from parent storage */
01555 CVAPI(CvMemStorage*)  cvCreateChildMemStorage( CvMemStorage* parent );
01556 
01557 
01558 /** Releases memory storage. All the children of a parent must be released before
01559    the parent. A child storage returns all the blocks to parent when it is released */
01560 CVAPI(void)  cvReleaseMemStorage( CvMemStorage** storage );
01561 
01562 
01563 /** Clears memory storage. This is the only way(!!!) (besides cvRestoreMemStoragePos)
01564    to reuse memory allocated for the storage - cvClearSeq,cvClearSet ...
01565    do not free any memory.
01566    A child storage returns all the blocks to the parent when it is cleared */
01567 CVAPI(void)  cvClearMemStorage( CvMemStorage* storage );
01568 
01569 /** Remember a storage "free memory" position */
01570 CVAPI(void)  cvSaveMemStoragePos( const CvMemStorage* storage, CvMemStoragePos* pos );
01571 
01572 /** Restore a storage "free memory" position */
01573 CVAPI(void)  cvRestoreMemStoragePos( CvMemStorage* storage, CvMemStoragePos* pos );
01574 
01575 /** Allocates continuous buffer of the specified size in the storage */
01576 CVAPI(void*) cvMemStorageAlloc( CvMemStorage* storage, size_t size );
01577 
01578 /** Allocates string in memory storage */
01579 CVAPI(CvString) cvMemStorageAllocString( CvMemStorage* storage, const char* ptr,
01580                                          int len CV_DEFAULT(-1) );
01581 
01582 /** Creates new empty sequence that will reside in the specified storage */
01583 CVAPI(CvSeq*)  cvCreateSeq( int seq_flags, size_t header_size,
01584                             size_t elem_size, CvMemStorage* storage );
01585 
01586 /** Changes default size (granularity) of sequence blocks.
01587    The default size is ~1Kbyte */
01588 CVAPI(void)  cvSetSeqBlockSize( CvSeq* seq, int delta_elems );
01589 
01590 
01591 /** Adds new element to the end of sequence. Returns pointer to the element */
01592 CVAPI(schar*)  cvSeqPush( CvSeq* seq, const void* element CV_DEFAULT(NULL));
01593 
01594 
01595 /** Adds new element to the beginning of sequence. Returns pointer to it */
01596 CVAPI(schar*)  cvSeqPushFront( CvSeq* seq, const void* element CV_DEFAULT(NULL));
01597 
01598 
01599 /** Removes the last element from sequence and optionally saves it */
01600 CVAPI(void)  cvSeqPop( CvSeq* seq, void* element CV_DEFAULT(NULL));
01601 
01602 
01603 /** Removes the first element from sequence and optioanally saves it */
01604 CVAPI(void)  cvSeqPopFront( CvSeq* seq, void* element CV_DEFAULT(NULL));
01605 
01606 
01607 #define CV_FRONT 1
01608 #define CV_BACK 0
01609 /** Adds several new elements to the end of sequence */
01610 CVAPI(void)  cvSeqPushMulti( CvSeq* seq, const void* elements,
01611                              int count, int in_front CV_DEFAULT(0) );
01612 
01613 /** Removes several elements from the end of sequence and optionally saves them */
01614 CVAPI(void)  cvSeqPopMulti( CvSeq* seq, void* elements,
01615                             int count, int in_front CV_DEFAULT(0) );
01616 
01617 /** Inserts a new element in the middle of sequence.
01618    cvSeqInsert(seq,0,elem) == cvSeqPushFront(seq,elem) */
01619 CVAPI(schar*)  cvSeqInsert( CvSeq* seq, int before_index,
01620                             const void* element CV_DEFAULT(NULL));
01621 
01622 /** Removes specified sequence element */
01623 CVAPI(void)  cvSeqRemove( CvSeq* seq, int index );
01624 
01625 
01626 /** Removes all the elements from the sequence. The freed memory
01627    can be reused later only by the same sequence unless cvClearMemStorage
01628    or cvRestoreMemStoragePos is called */
01629 CVAPI(void)  cvClearSeq( CvSeq* seq );
01630 
01631 
01632 /** Retrieves pointer to specified sequence element.
01633    Negative indices are supported and mean counting from the end
01634    (e.g -1 means the last sequence element) */
01635 CVAPI(schar*)  cvGetSeqElem( const CvSeq* seq, int index );
01636 
01637 /** Calculates index of the specified sequence element.
01638    Returns -1 if element does not belong to the sequence */
01639 CVAPI(int)  cvSeqElemIdx( const CvSeq* seq, const void* element,
01640                          CvSeqBlock** block CV_DEFAULT(NULL) );
01641 
01642 /** Initializes sequence writer. The new elements will be added to the end of sequence */
01643 CVAPI(void)  cvStartAppendToSeq( CvSeq* seq, CvSeqWriter* writer );
01644 
01645 
01646 /** Combination of cvCreateSeq and cvStartAppendToSeq */
01647 CVAPI(void)  cvStartWriteSeq( int seq_flags, int header_size,
01648                               int elem_size, CvMemStorage* storage,
01649                               CvSeqWriter* writer );
01650 
01651 /** Closes sequence writer, updates sequence header and returns pointer
01652    to the resultant sequence
01653    (which may be useful if the sequence was created using cvStartWriteSeq))
01654 */
01655 CVAPI(CvSeq*)  cvEndWriteSeq( CvSeqWriter* writer );
01656 
01657 
01658 /** Updates sequence header. May be useful to get access to some of previously
01659    written elements via cvGetSeqElem or sequence reader */
01660 CVAPI(void)   cvFlushSeqWriter( CvSeqWriter* writer );
01661 
01662 
01663 /** Initializes sequence reader.
01664    The sequence can be read in forward or backward direction */
01665 CVAPI(void) cvStartReadSeq( const CvSeq* seq, CvSeqReader* reader,
01666                            int reverse CV_DEFAULT(0) );
01667 
01668 
01669 /** Returns current sequence reader position (currently observed sequence element) */
01670 CVAPI(int)  cvGetSeqReaderPos( CvSeqReader* reader );
01671 
01672 
01673 /** Changes sequence reader position. It may seek to an absolute or
01674    to relative to the current position */
01675 CVAPI(void)   cvSetSeqReaderPos( CvSeqReader* reader, int index,
01676                                  int is_relative CV_DEFAULT(0));
01677 
01678 /** Copies sequence content to a continuous piece of memory */
01679 CVAPI(void*)  cvCvtSeqToArray( const CvSeq* seq, void* elements,
01680                                CvSlice slice CV_DEFAULT(CV_WHOLE_SEQ) );
01681 
01682 /** Creates sequence header for array.
01683    After that all the operations on sequences that do not alter the content
01684    can be applied to the resultant sequence */
01685 CVAPI(CvSeq*) cvMakeSeqHeaderForArray( int seq_type, int header_size,
01686                                        int elem_size, void* elements, int total,
01687                                        CvSeq* seq, CvSeqBlock* block );
01688 
01689 /** Extracts sequence slice (with or without copying sequence elements) */
01690 CVAPI(CvSeq*) cvSeqSlice( const CvSeq* seq, CvSlice slice,
01691                          CvMemStorage* storage CV_DEFAULT(NULL),
01692                          int copy_data CV_DEFAULT(0));
01693 
01694 CV_INLINE CvSeq* cvCloneSeq( const CvSeq* seq, CvMemStorage* storage CV_DEFAULT(NULL))
01695 {
01696     return cvSeqSlice( seq, CV_WHOLE_SEQ, storage, 1 );
01697 }
01698 
01699 /** Removes sequence slice */
01700 CVAPI(void)  cvSeqRemoveSlice( CvSeq* seq, CvSlice slice );
01701 
01702 /** Inserts a sequence or array into another sequence */
01703 CVAPI(void)  cvSeqInsertSlice( CvSeq* seq, int before_index, const CvArr* from_arr );
01704 
01705 /** a < b ? -1 : a > b ? 1 : 0 */
01706 typedef int (CV_CDECL* CvCmpFunc)(const void* a, const void* b, void* userdata );
01707 
01708 /** Sorts sequence in-place given element comparison function */
01709 CVAPI(void) cvSeqSort( CvSeq* seq, CvCmpFunc func, void* userdata CV_DEFAULT(NULL) );
01710 
01711 /** Finds element in a [sorted] sequence */
01712 CVAPI(schar*) cvSeqSearch( CvSeq* seq, const void* elem, CvCmpFunc func,
01713                            int is_sorted, int* elem_idx,
01714                            void* userdata CV_DEFAULT(NULL) );
01715 
01716 /** Reverses order of sequence elements in-place */
01717 CVAPI(void) cvSeqInvert( CvSeq* seq );
01718 
01719 /** Splits sequence into one or more equivalence classes using the specified criteria */
01720 CVAPI(int)  cvSeqPartition( const CvSeq* seq, CvMemStorage* storage,
01721                             CvSeq** labels, CvCmpFunc is_equal, void* userdata );
01722 
01723 /************ Internal sequence functions ************/
01724 CVAPI(void)  cvChangeSeqBlock( void* reader, int direction );
01725 CVAPI(void)  cvCreateSeqBlock( CvSeqWriter* writer );
01726 
01727 
01728 /** Creates a new set */
01729 CVAPI(CvSet*)  cvCreateSet( int set_flags, int header_size,
01730                             int elem_size, CvMemStorage* storage );
01731 
01732 /** Adds new element to the set and returns pointer to it */
01733 CVAPI(int)  cvSetAdd( CvSet* set_header, CvSetElem* elem CV_DEFAULT(NULL),
01734                       CvSetElem** inserted_elem CV_DEFAULT(NULL) );
01735 
01736 /** Fast variant of cvSetAdd */
01737 CV_INLINE  CvSetElem* cvSetNew( CvSet* set_header )
01738 {
01739     CvSetElem* elem = set_header->free_elems;
01740     if( elem )
01741     {
01742         set_header->free_elems = elem->next_free;
01743         elem->flags = elem->flags & CV_SET_ELEM_IDX_MASK;
01744         set_header->active_count++;
01745     }
01746     else
01747         cvSetAdd( set_header, NULL, &elem );
01748     return elem;
01749 }
01750 
01751 /** Removes set element given its pointer */
01752 CV_INLINE  void cvSetRemoveByPtr( CvSet* set_header, void* elem )
01753 {
01754     CvSetElem* _elem = (CvSetElem*)elem;
01755     assert( _elem->flags >= 0 /*&& (elem->flags & CV_SET_ELEM_IDX_MASK) < set_header->total*/ );
01756     _elem->next_free = set_header->free_elems;
01757     _elem->flags = (_elem->flags & CV_SET_ELEM_IDX_MASK) | CV_SET_ELEM_FREE_FLAG;
01758     set_header->free_elems = _elem;
01759     set_header->active_count--;
01760 }
01761 
01762 /** Removes element from the set by its index  */
01763 CVAPI(void)   cvSetRemove( CvSet* set_header, int index );
01764 
01765 /** Returns a set element by index. If the element doesn't belong to the set,
01766    NULL is returned */
01767 CV_INLINE CvSetElem* cvGetSetElem( const CvSet* set_header, int idx )
01768 {
01769     CvSetElem* elem = (CvSetElem*)(void *)cvGetSeqElem( (CvSeq*)set_header, idx );
01770     return elem && CV_IS_SET_ELEM( elem ) ? elem : 0;
01771 }
01772 
01773 /** Removes all the elements from the set */
01774 CVAPI(void)  cvClearSet( CvSet* set_header );
01775 
01776 /** Creates new graph */
01777 CVAPI(CvGraph*)  cvCreateGraph( int graph_flags, int header_size,
01778                                 int vtx_size, int edge_size,
01779                                 CvMemStorage* storage );
01780 
01781 /** Adds new vertex to the graph */
01782 CVAPI(int)  cvGraphAddVtx( CvGraph* graph, const CvGraphVtx* vtx CV_DEFAULT(NULL),
01783                            CvGraphVtx** inserted_vtx CV_DEFAULT(NULL) );
01784 
01785 
01786 /** Removes vertex from the graph together with all incident edges */
01787 CVAPI(int)  cvGraphRemoveVtx( CvGraph* graph, int index );
01788 CVAPI(int)  cvGraphRemoveVtxByPtr( CvGraph* graph, CvGraphVtx* vtx );
01789 
01790 
01791 /** Link two vertices specifed by indices or pointers if they
01792    are not connected or return pointer to already existing edge
01793    connecting the vertices.
01794    Functions return 1 if a new edge was created, 0 otherwise */
01795 CVAPI(int)  cvGraphAddEdge( CvGraph* graph,
01796                             int start_idx, int end_idx,
01797                             const CvGraphEdge* edge CV_DEFAULT(NULL),
01798                             CvGraphEdge** inserted_edge CV_DEFAULT(NULL) );
01799 
01800 CVAPI(int)  cvGraphAddEdgeByPtr( CvGraph* graph,
01801                                CvGraphVtx* start_vtx, CvGraphVtx* end_vtx,
01802                                const CvGraphEdge* edge CV_DEFAULT(NULL),
01803                                CvGraphEdge** inserted_edge CV_DEFAULT(NULL) );
01804 
01805 /** Remove edge connecting two vertices */
01806 CVAPI(void)  cvGraphRemoveEdge( CvGraph* graph, int start_idx, int end_idx );
01807 CVAPI(void)  cvGraphRemoveEdgeByPtr( CvGraph* graph, CvGraphVtx* start_vtx,
01808                                      CvGraphVtx* end_vtx );
01809 
01810 /** Find edge connecting two vertices */
01811 CVAPI(CvGraphEdge*)  cvFindGraphEdge( const CvGraph* graph, int start_idx, int end_idx );
01812 CVAPI(CvGraphEdge*)  cvFindGraphEdgeByPtr( const CvGraph* graph,
01813                                            const CvGraphVtx* start_vtx,
01814                                            const CvGraphVtx* end_vtx );
01815 #define cvGraphFindEdge cvFindGraphEdge
01816 #define cvGraphFindEdgeByPtr cvFindGraphEdgeByPtr
01817 
01818 /** Remove all vertices and edges from the graph */
01819 CVAPI(void)  cvClearGraph( CvGraph* graph );
01820 
01821 
01822 /** Count number of edges incident to the vertex */
01823 CVAPI(int)  cvGraphVtxDegree( const CvGraph* graph, int vtx_idx );
01824 CVAPI(int)  cvGraphVtxDegreeByPtr( const CvGraph* graph, const CvGraphVtx* vtx );
01825 
01826 
01827 /** Retrieves graph vertex by given index */
01828 #define cvGetGraphVtx( graph, idx ) (CvGraphVtx*)cvGetSetElem((CvSet*)(graph), (idx))
01829 
01830 /** Retrieves index of a graph vertex given its pointer */
01831 #define cvGraphVtxIdx( graph, vtx ) ((vtx)->flags & CV_SET_ELEM_IDX_MASK)
01832 
01833 /** Retrieves index of a graph edge given its pointer */
01834 #define cvGraphEdgeIdx( graph, edge ) ((edge)->flags & CV_SET_ELEM_IDX_MASK)
01835 
01836 #define cvGraphGetVtxCount( graph ) ((graph)->active_count)
01837 #define cvGraphGetEdgeCount( graph ) ((graph)->edges->active_count)
01838 
01839 #define  CV_GRAPH_VERTEX        1
01840 #define  CV_GRAPH_TREE_EDGE     2
01841 #define  CV_GRAPH_BACK_EDGE     4
01842 #define  CV_GRAPH_FORWARD_EDGE  8
01843 #define  CV_GRAPH_CROSS_EDGE    16
01844 #define  CV_GRAPH_ANY_EDGE      30
01845 #define  CV_GRAPH_NEW_TREE      32
01846 #define  CV_GRAPH_BACKTRACKING  64
01847 #define  CV_GRAPH_OVER          -1
01848 
01849 #define  CV_GRAPH_ALL_ITEMS    -1
01850 
01851 /** flags for graph vertices and edges */
01852 #define  CV_GRAPH_ITEM_VISITED_FLAG  (1 << 30)
01853 #define  CV_IS_GRAPH_VERTEX_VISITED(vtx) \
01854     (((CvGraphVtx*)(vtx))->flags & CV_GRAPH_ITEM_VISITED_FLAG)
01855 #define  CV_IS_GRAPH_EDGE_VISITED(edge) \
01856     (((CvGraphEdge*)(edge))->flags & CV_GRAPH_ITEM_VISITED_FLAG)
01857 #define  CV_GRAPH_SEARCH_TREE_NODE_FLAG   (1 << 29)
01858 #define  CV_GRAPH_FORWARD_EDGE_FLAG       (1 << 28)
01859 
01860 typedef struct CvGraphScanner
01861 {
01862     CvGraphVtx* vtx;       /* current graph vertex (or current edge origin) */
01863     CvGraphVtx* dst;       /* current graph edge destination vertex */
01864     CvGraphEdge* edge;     /* current edge */
01865 
01866     CvGraph* graph;        /* the graph */
01867     CvSeq*   stack;        /* the graph vertex stack */
01868     int      index;        /* the lower bound of certainly visited vertices */
01869     int      mask;         /* event mask */
01870 }
01871 CvGraphScanner;
01872 
01873 /** Creates new graph scanner. */
01874 CVAPI(CvGraphScanner*)  cvCreateGraphScanner( CvGraph* graph,
01875                                              CvGraphVtx* vtx CV_DEFAULT(NULL),
01876                                              int mask CV_DEFAULT(CV_GRAPH_ALL_ITEMS));
01877 
01878 /** Releases graph scanner. */
01879 CVAPI(void) cvReleaseGraphScanner( CvGraphScanner** scanner );
01880 
01881 /** Get next graph element */
01882 CVAPI(int)  cvNextGraphItem( CvGraphScanner* scanner );
01883 
01884 /** Creates a copy of graph */
01885 CVAPI(CvGraph*) cvCloneGraph( const CvGraph* graph, CvMemStorage* storage );
01886 
01887 
01888 /** Does look-up transformation. Elements of the source array
01889    (that should be 8uC1 or 8sC1) are used as indexes in lutarr 256-element table */
01890 CVAPI(void) cvLUT( const CvArr* src, CvArr* dst, const CvArr* lut );
01891 
01892 
01893 /******************* Iteration through the sequence tree *****************/
01894 typedef struct CvTreeNodeIterator
01895 {
01896     const void* node;
01897     int level;
01898     int max_level;
01899 }
01900 CvTreeNodeIterator;
01901 
01902 CVAPI(void) cvInitTreeNodeIterator( CvTreeNodeIterator* tree_iterator,
01903                                    const void* first, int max_level );
01904 CVAPI(void*) cvNextTreeNode( CvTreeNodeIterator* tree_iterator );
01905 CVAPI(void*) cvPrevTreeNode( CvTreeNodeIterator* tree_iterator );
01906 
01907 /** Inserts sequence into tree with specified "parent" sequence.
01908    If parent is equal to frame (e.g. the most external contour),
01909    then added contour will have null pointer to parent. */
01910 CVAPI(void) cvInsertNodeIntoTree( void* node, void* parent, void* frame );
01911 
01912 /** Removes contour from tree (together with the contour children). */
01913 CVAPI(void) cvRemoveNodeFromTree( void* node, void* frame );
01914 
01915 /** Gathers pointers to all the sequences,
01916    accessible from the `first`, to the single sequence */
01917 CVAPI(CvSeq*) cvTreeToNodeSeq( const void* first, int header_size,
01918                               CvMemStorage* storage );
01919 
01920 /** The function implements the K-means algorithm for clustering an array of sample
01921    vectors in a specified number of classes */
01922 #define CV_KMEANS_USE_INITIAL_LABELS    1
01923 CVAPI(int) cvKMeans2( const CvArr* samples, int cluster_count, CvArr* labels,
01924                       CvTermCriteria  termcrit, int attempts CV_DEFAULT(1),
01925                       CvRNG* rng CV_DEFAULT(0), int flags CV_DEFAULT(0),
01926                       CvArr* _centers CV_DEFAULT(0), double* compactness CV_DEFAULT(0) );
01927 
01928 /****************************************************************************************\
01929 *                                    System functions                                    *
01930 \****************************************************************************************/
01931 
01932 /** Loads optimized functions from IPP, MKL etc. or switches back to pure C code */
01933 CVAPI(int)  cvUseOptimized( int on_off );
01934 
01935 typedef IplImage* (CV_STDCALL* Cv_iplCreateImageHeader)
01936                             (int,int,int,char*,char*,int,int,int,int,int,
01937                             IplROI*,IplImage*,void*,IplTileInfo*);
01938 typedef void (CV_STDCALL* Cv_iplAllocateImageData)(IplImage*,int,int);
01939 typedef void (CV_STDCALL* Cv_iplDeallocate)(IplImage*,int);
01940 typedef IplROI* (CV_STDCALL* Cv_iplCreateROI)(int,int,int,int,int);
01941 typedef IplImage* (CV_STDCALL* Cv_iplCloneImage)(const IplImage*);
01942 
01943 /** @brief Makes OpenCV use IPL functions for allocating IplImage and IplROI structures.
01944 
01945 Normally, the function is not called directly. Instead, a simple macro
01946 CV_TURN_ON_IPL_COMPATIBILITY() is used that calls cvSetIPLAllocators and passes there pointers
01947 to IPL allocation functions. :
01948 @code
01949     ...
01950     CV_TURN_ON_IPL_COMPATIBILITY()
01951     ...
01952 @endcode
01953 @param create_header pointer to a function, creating IPL image header.
01954 @param allocate_data pointer to a function, allocating IPL image data.
01955 @param deallocate pointer to a function, deallocating IPL image.
01956 @param create_roi pointer to a function, creating IPL image ROI (i.e. Region of Interest).
01957 @param clone_image pointer to a function, cloning an IPL image.
01958  */
01959 CVAPI(void) cvSetIPLAllocators( Cv_iplCreateImageHeader create_header,
01960                                Cv_iplAllocateImageData allocate_data,
01961                                Cv_iplDeallocate deallocate,
01962                                Cv_iplCreateROI create_roi,
01963                                Cv_iplCloneImage clone_image );
01964 
01965 #define CV_TURN_ON_IPL_COMPATIBILITY()                                  \
01966     cvSetIPLAllocators( iplCreateImageHeader, iplAllocateImage,         \
01967                         iplDeallocate, iplCreateROI, iplCloneImage )
01968 
01969 /****************************************************************************************\
01970 *                                    Data Persistence                                    *
01971 \****************************************************************************************/
01972 
01973 /********************************** High-level functions ********************************/
01974 
01975 /** @brief Opens file storage for reading or writing data.
01976 
01977 The function opens file storage for reading or writing data. In the latter case, a new file is
01978 created or an existing file is rewritten. The type of the read or written file is determined by the
01979 filename extension: .xml for XML and .yml or .yaml for YAML. The function returns a pointer to the
01980 CvFileStorage structure. If the file cannot be opened then the function returns NULL.
01981 @param filename Name of the file associated with the storage
01982 @param memstorage Memory storage used for temporary data and for
01983 :   storing dynamic structures, such as CvSeq or CvGraph . If it is NULL, a temporary memory
01984     storage is created and used.
01985 @param flags Can be one of the following:
01986 > -   **CV_STORAGE_READ** the storage is open for reading
01987 > -   **CV_STORAGE_WRITE** the storage is open for writing
01988 @param encoding
01989  */
01990 CVAPI(CvFileStorage*)  cvOpenFileStorage( const char* filename, CvMemStorage* memstorage,
01991                                           int flags, const char* encoding CV_DEFAULT(NULL) );
01992 
01993 /** @brief Releases file storage.
01994 
01995 The function closes the file associated with the storage and releases all the temporary structures.
01996 It must be called after all I/O operations with the storage are finished.
01997 @param fs Double pointer to the released file storage
01998  */
01999 CVAPI(void) cvReleaseFileStorage( CvFileStorage** fs );
02000 
02001 /** returns attribute value or 0 (NULL) if there is no such attribute */
02002 CVAPI(const char*) cvAttrValue( const CvAttrList* attr, const char* attr_name );
02003 
02004 /** @brief Starts writing a new structure.
02005 
02006 The function starts writing a compound structure (collection) that can be a sequence or a map. After
02007 all the structure fields, which can be scalars or structures, are written, cvEndWriteStruct should
02008 be called. The function can be used to group some objects or to implement the write function for a
02009 some user object (see CvTypeInfo).
02010 @param fs File storage
02011 @param name Name of the written structure. The structure can be accessed by this name when the
02012 storage is read.
02013 @param struct_flags A combination one of the following values:
02014 -   **CV_NODE_SEQ** the written structure is a sequence (see discussion of CvFileStorage ),
02015     that is, its elements do not have a name.
02016 -   **CV_NODE_MAP** the written structure is a map (see discussion of CvFileStorage ), that
02017     is, all its elements have names.
02018 One and only one of the two above flags must be specified
02019 -   **CV_NODE_FLOW** the optional flag that makes sense only for YAML streams. It means that
02020      the structure is written as a flow (not as a block), which is more compact. It is
02021      recommended to use this flag for structures or arrays whose elements are all scalars.
02022 @param type_name Optional parameter - the object type name. In
02023     case of XML it is written as a type_id attribute of the structure opening tag. In the case of
02024     YAML it is written after a colon following the structure name (see the example in
02025     CvFileStorage description). Mainly it is used with user objects. When the storage is read, the
02026     encoded type name is used to determine the object type (see CvTypeInfo and cvFindType ).
02027 @param attributes This parameter is not used in the current implementation
02028  */
02029 CVAPI(void) cvStartWriteStruct( CvFileStorage* fs, const char* name,
02030                                 int struct_flags, const char* type_name CV_DEFAULT(NULL),
02031                                 CvAttrList attributes CV_DEFAULT(cvAttrList()));
02032 
02033 /** @brief Finishes writing to a file node collection.
02034 @param fs File storage
02035 @sa cvStartWriteStruct.
02036  */
02037 CVAPI(void) cvEndWriteStruct( CvFileStorage* fs );
02038 
02039 /** @brief Writes an integer value.
02040 
02041 The function writes a single integer value (with or without a name) to the file storage.
02042 @param fs File storage
02043 @param name Name of the written value. Should be NULL if and only if the parent structure is a
02044 sequence.
02045 @param value The written value
02046  */
02047 CVAPI(void) cvWriteInt( CvFileStorage* fs, const char* name, int value );
02048 
02049 /** @brief Writes a floating-point value.
02050 
02051 The function writes a single floating-point value (with or without a name) to file storage. Special
02052 values are encoded as follows: NaN (Not A Number) as .NaN, infinity as +.Inf or -.Inf.
02053 
02054 The following example shows how to use the low-level writing functions to store custom structures,
02055 such as termination criteria, without registering a new type. :
02056 @code
02057     void write_termcriteria( CvFileStorage* fs, const char* struct_name,
02058                              CvTermCriteria* termcrit )
02059     {
02060         cvStartWriteStruct( fs, struct_name, CV_NODE_MAP, NULL, cvAttrList(0,0));
02061         cvWriteComment( fs, "termination criteria", 1 ); // just a description
02062         if( termcrit->type & CV_TERMCRIT_ITER )
02063             cvWriteInteger( fs, "max_iterations", termcrit->max_iter );
02064         if( termcrit->type & CV_TERMCRIT_EPS )
02065             cvWriteReal( fs, "accuracy", termcrit->epsilon );
02066         cvEndWriteStruct( fs );
02067     }
02068 @endcode
02069 @param fs File storage
02070 @param name Name of the written value. Should be NULL if and only if the parent structure is a
02071 sequence.
02072 @param value The written value
02073 */
02074 CVAPI(void) cvWriteReal( CvFileStorage* fs, const char* name, double value );
02075 
02076 /** @brief Writes a text string.
02077 
02078 The function writes a text string to file storage.
02079 @param fs File storage
02080 @param name Name of the written string . Should be NULL if and only if the parent structure is a
02081 sequence.
02082 @param str The written text string
02083 @param quote If non-zero, the written string is put in quotes, regardless of whether they are
02084 required. Otherwise, if the flag is zero, quotes are used only when they are required (e.g. when
02085 the string starts with a digit or contains spaces).
02086  */
02087 CVAPI(void) cvWriteString( CvFileStorage* fs, const char* name,
02088                            const char* str, int quote CV_DEFAULT(0) );
02089 
02090 /** @brief Writes a comment.
02091 
02092 The function writes a comment into file storage. The comments are skipped when the storage is read.
02093 @param fs File storage
02094 @param comment The written comment, single-line or multi-line
02095 @param eol_comment If non-zero, the function tries to put the comment at the end of current line.
02096 If the flag is zero, if the comment is multi-line, or if it does not fit at the end of the current
02097 line, the comment starts a new line.
02098  */
02099 CVAPI(void) cvWriteComment( CvFileStorage* fs, const char* comment,
02100                             int eol_comment );
02101 
02102 /** @brief Writes an object to file storage.
02103 
02104 The function writes an object to file storage. First, the appropriate type info is found using
02105 cvTypeOf. Then, the write method associated with the type info is called.
02106 
02107 Attributes are used to customize the writing procedure. The standard types support the following
02108 attributes (all the dt attributes have the same format as in cvWriteRawData):
02109 
02110 -# CvSeq
02111     -   **header_dt** description of user fields of the sequence header that follow CvSeq, or
02112         CvChain (if the sequence is a Freeman chain) or CvContour (if the sequence is a contour or
02113         point sequence)
02114     -   **dt** description of the sequence elements.
02115     -   **recursive** if the attribute is present and is not equal to "0" or "false", the whole
02116         tree of sequences (contours) is stored.
02117 -# CvGraph
02118     -   **header_dt** description of user fields of the graph header that follows CvGraph;
02119     -   **vertex_dt** description of user fields of graph vertices
02120     -   **edge_dt** description of user fields of graph edges (note that the edge weight is
02121         always written, so there is no need to specify it explicitly)
02122 
02123 Below is the code that creates the YAML file shown in the CvFileStorage description:
02124 @code
02125     #include "cxcore.h"
02126 
02127     int main( int argc, char** argv )
02128     {
02129         CvMat* mat = cvCreateMat( 3, 3, CV_32F );
02130         CvFileStorage* fs = cvOpenFileStorage( "example.yml", 0, CV_STORAGE_WRITE );
02131 
02132         cvSetIdentity( mat );
02133         cvWrite( fs, "A", mat, cvAttrList(0,0) );
02134 
02135         cvReleaseFileStorage( &fs );
02136         cvReleaseMat( &mat );
02137         return 0;
02138     }
02139 @endcode
02140 @param fs File storage
02141 @param name Name of the written object. Should be NULL if and only if the parent structure is a
02142 sequence.
02143 @param ptr Pointer to the object
02144 @param attributes The attributes of the object. They are specific for each particular type (see
02145 the discussion below).
02146  */
02147 CVAPI(void) cvWrite( CvFileStorage* fs, const char* name, const void* ptr,
02148                          CvAttrList attributes CV_DEFAULT(cvAttrList()));
02149 
02150 /** @brief Starts the next stream.
02151 
02152 The function finishes the currently written stream and starts the next stream. In the case of XML
02153 the file with multiple streams looks like this:
02154 @code{.xml}
02155     <opencv_storage>
02156     <!-- stream #1 data -->
02157     </opencv_storage>
02158     <opencv_storage>
02159     <!-- stream #2 data -->
02160     </opencv_storage>
02161     ...
02162 @endcode
02163 The YAML file will look like this:
02164 @code{.yaml}
02165     %YAML:1.0
02166     # stream #1 data
02167     ...
02168     ---
02169     # stream #2 data
02170 @endcode
02171 This is useful for concatenating files or for resuming the writing process.
02172 @param fs File storage
02173  */
02174 CVAPI(void) cvStartNextStream( CvFileStorage* fs );
02175 
02176 /** @brief Writes multiple numbers.
02177 
02178 The function writes an array, whose elements consist of single or multiple numbers. The function
02179 call can be replaced with a loop containing a few cvWriteInt and cvWriteReal calls, but a single
02180 call is more efficient. Note that because none of the elements have a name, they should be written
02181 to a sequence rather than a map.
02182 @param fs File storage
02183 @param src Pointer to the written array
02184 @param len Number of the array elements to write
02185 @param dt Specification of each array element, see @ref format_spec "format specification"
02186  */
02187 CVAPI(void) cvWriteRawData( CvFileStorage* fs, const void* src,
02188                                 int len, const char* dt );
02189 
02190 /** @brief Returns a unique pointer for a given name.
02191 
02192 The function returns a unique pointer for each particular file node name. This pointer can be then
02193 passed to the cvGetFileNode function that is faster than cvGetFileNodeByName because it compares
02194 text strings by comparing pointers rather than the strings' content.
02195 
02196 Consider the following example where an array of points is encoded as a sequence of 2-entry maps:
02197 @code
02198     points:
02199       - { x: 10, y: 10 }
02200       - { x: 20, y: 20 }
02201       - { x: 30, y: 30 }
02202       # ...
02203 @endcode
02204 Then, it is possible to get hashed "x" and "y" pointers to speed up decoding of the points. :
02205 @code
02206     #include "cxcore.h"
02207 
02208     int main( int argc, char** argv )
02209     {
02210         CvFileStorage* fs = cvOpenFileStorage( "points.yml", 0, CV_STORAGE_READ );
02211         CvStringHashNode* x_key = cvGetHashedNode( fs, "x", -1, 1 );
02212         CvStringHashNode* y_key = cvGetHashedNode( fs, "y", -1, 1 );
02213         CvFileNode* points = cvGetFileNodeByName( fs, 0, "points" );
02214 
02215         if( CV_NODE_IS_SEQ(points->tag) )
02216         {
02217             CvSeq* seq = points->data.seq;
02218             int i, total = seq->total;
02219             CvSeqReader reader;
02220             cvStartReadSeq( seq, &reader, 0 );
02221             for( i = 0; i < total; i++ )
02222             {
02223                 CvFileNode* pt = (CvFileNode*)reader.ptr;
02224     #if 1 // faster variant
02225                 CvFileNode* xnode = cvGetFileNode( fs, pt, x_key, 0 );
02226                 CvFileNode* ynode = cvGetFileNode( fs, pt, y_key, 0 );
02227                 assert( xnode && CV_NODE_IS_INT(xnode->tag) &&
02228                         ynode && CV_NODE_IS_INT(ynode->tag));
02229                 int x = xnode->data.i; // or x = cvReadInt( xnode, 0 );
02230                 int y = ynode->data.i; // or y = cvReadInt( ynode, 0 );
02231     #elif 1 // slower variant; does not use x_key & y_key
02232                 CvFileNode* xnode = cvGetFileNodeByName( fs, pt, "x" );
02233                 CvFileNode* ynode = cvGetFileNodeByName( fs, pt, "y" );
02234                 assert( xnode && CV_NODE_IS_INT(xnode->tag) &&
02235                         ynode && CV_NODE_IS_INT(ynode->tag));
02236                 int x = xnode->data.i; // or x = cvReadInt( xnode, 0 );
02237                 int y = ynode->data.i; // or y = cvReadInt( ynode, 0 );
02238     #else // the slowest yet the easiest to use variant
02239                 int x = cvReadIntByName( fs, pt, "x", 0 );
02240                 int y = cvReadIntByName( fs, pt, "y", 0 );
02241     #endif
02242                 CV_NEXT_SEQ_ELEM( seq->elem_size, reader );
02243                 printf("
02244             }
02245         }
02246         cvReleaseFileStorage( &fs );
02247         return 0;
02248     }
02249 @endcode
02250 Please note that whatever method of accessing a map you are using, it is still much slower than
02251 using plain sequences; for example, in the above example, it is more efficient to encode the points
02252 as pairs of integers in a single numeric sequence.
02253 @param fs File storage
02254 @param name Literal node name
02255 @param len Length of the name (if it is known apriori), or -1 if it needs to be calculated
02256 @param create_missing Flag that specifies, whether an absent key should be added into the hash table
02257 */
02258 CVAPI(CvStringHashNode*) cvGetHashedKey( CvFileStorage* fs, const char* name,
02259                                         int len CV_DEFAULT(-1),
02260                                         int create_missing CV_DEFAULT(0));
02261 
02262 /** @brief Retrieves one of the top-level nodes of the file storage.
02263 
02264 The function returns one of the top-level file nodes. The top-level nodes do not have a name, they
02265 correspond to the streams that are stored one after another in the file storage. If the index is out
02266 of range, the function returns a NULL pointer, so all the top-level nodes can be iterated by
02267 subsequent calls to the function with stream_index=0,1,..., until the NULL pointer is returned.
02268 This function can be used as a base for recursive traversal of the file storage.
02269 @param fs File storage
02270 @param stream_index Zero-based index of the stream. See cvStartNextStream . In most cases,
02271 there is only one stream in the file; however, there can be several.
02272  */
02273 CVAPI(CvFileNode*) cvGetRootFileNode( const CvFileStorage* fs,
02274                                      int stream_index CV_DEFAULT(0) );
02275 
02276 /** @brief Finds a node in a map or file storage.
02277 
02278 The function finds a file node. It is a faster version of cvGetFileNodeByName (see
02279 cvGetHashedKey discussion). Also, the function can insert a new node, if it is not in the map yet.
02280 @param fs File storage
02281 @param map The parent map. If it is NULL, the function searches a top-level node. If both map and
02282 key are NULLs, the function returns the root file node - a map that contains top-level nodes.
02283 @param key Unique pointer to the node name, retrieved with cvGetHashedKey
02284 @param create_missing Flag that specifies whether an absent node should be added to the map
02285  */
02286 CVAPI(CvFileNode*) cvGetFileNode( CvFileStorage* fs, CvFileNode* map,
02287                                  const CvStringHashNode* key,
02288                                  int create_missing CV_DEFAULT(0) );
02289 
02290 /** @brief Finds a node in a map or file storage.
02291 
02292 The function finds a file node by name. The node is searched either in map or, if the pointer is
02293 NULL, among the top-level file storage nodes. Using this function for maps and cvGetSeqElem (or
02294 sequence reader) for sequences, it is possible to navigate through the file storage. To speed up
02295 multiple queries for a certain key (e.g., in the case of an array of structures) one may use a
02296 combination of cvGetHashedKey and cvGetFileNode.
02297 @param fs File storage
02298 @param map The parent map. If it is NULL, the function searches in all the top-level nodes
02299 (streams), starting with the first one.
02300 @param name The file node name
02301  */
02302 CVAPI(CvFileNode*) cvGetFileNodeByName( const CvFileStorage* fs,
02303                                        const CvFileNode* map,
02304                                        const char* name );
02305 
02306 /** @brief Retrieves an integer value from a file node.
02307 
02308 The function returns an integer that is represented by the file node. If the file node is NULL, the
02309 default_value is returned (thus, it is convenient to call the function right after cvGetFileNode
02310 without checking for a NULL pointer). If the file node has type CV_NODE_INT, then node->data.i is
02311 returned. If the file node has type CV_NODE_REAL, then node->data.f is converted to an integer
02312 and returned. Otherwise the error is reported.
02313 @param node File node
02314 @param default_value The value that is returned if node is NULL
02315  */
02316 CV_INLINE int cvReadInt( const CvFileNode* node, int default_value CV_DEFAULT(0) )
02317 {
02318     return !node ? default_value :
02319         CV_NODE_IS_INT(node->tag) ? node->data.i :
02320         CV_NODE_IS_REAL(node->tag) ? cvRound(node->data.f) : 0x7fffffff;
02321 }
02322 
02323 /** @brief Finds a file node and returns its value.
02324 
02325 The function is a simple superposition of cvGetFileNodeByName and cvReadInt.
02326 @param fs File storage
02327 @param map The parent map. If it is NULL, the function searches a top-level node.
02328 @param name The node name
02329 @param default_value The value that is returned if the file node is not found
02330  */
02331 CV_INLINE int cvReadIntByName( const CvFileStorage* fs, const CvFileNode* map,
02332                          const char* name, int default_value CV_DEFAULT(0) )
02333 {
02334     return cvReadInt( cvGetFileNodeByName( fs, map, name ), default_value );
02335 }
02336 
02337 /** @brief Retrieves a floating-point value from a file node.
02338 
02339 The function returns a floating-point value that is represented by the file node. If the file node
02340 is NULL, the default_value is returned (thus, it is convenient to call the function right after
02341 cvGetFileNode without checking for a NULL pointer). If the file node has type CV_NODE_REAL ,
02342 then node->data.f is returned. If the file node has type CV_NODE_INT , then node-:math:>data.f
02343 is converted to floating-point and returned. Otherwise the result is not determined.
02344 @param node File node
02345 @param default_value The value that is returned if node is NULL
02346  */
02347 CV_INLINE double cvReadReal( const CvFileNode* node, double default_value CV_DEFAULT(0.) )
02348 {
02349     return !node ? default_value :
02350         CV_NODE_IS_INT(node->tag) ? (double)node->data.i :
02351         CV_NODE_IS_REAL(node->tag) ? node->data.f : 1e300;
02352 }
02353 
02354 /** @brief Finds a file node and returns its value.
02355 
02356 The function is a simple superposition of cvGetFileNodeByName and cvReadReal .
02357 @param fs File storage
02358 @param map The parent map. If it is NULL, the function searches a top-level node.
02359 @param name The node name
02360 @param default_value The value that is returned if the file node is not found
02361  */
02362 CV_INLINE double cvReadRealByName( const CvFileStorage* fs, const CvFileNode* map,
02363                         const char* name, double default_value CV_DEFAULT(0.) )
02364 {
02365     return cvReadReal( cvGetFileNodeByName( fs, map, name ), default_value );
02366 }
02367 
02368 /** @brief Retrieves a text string from a file node.
02369 
02370 The function returns a text string that is represented by the file node. If the file node is NULL,
02371 the default_value is returned (thus, it is convenient to call the function right after
02372 cvGetFileNode without checking for a NULL pointer). If the file node has type CV_NODE_STR , then
02373 node-:math:>data.str.ptr is returned. Otherwise the result is not determined.
02374 @param node File node
02375 @param default_value The value that is returned if node is NULL
02376  */
02377 CV_INLINE const char* cvReadString( const CvFileNode* node,
02378                         const char* default_value CV_DEFAULT(NULL) )
02379 {
02380     return !node ? default_value : CV_NODE_IS_STRING(node->tag) ? node->data.str.ptr : 0;
02381 }
02382 
02383 /** @brief Finds a file node by its name and returns its value.
02384 
02385 The function is a simple superposition of cvGetFileNodeByName and cvReadString .
02386 @param fs File storage
02387 @param map The parent map. If it is NULL, the function searches a top-level node.
02388 @param name The node name
02389 @param default_value The value that is returned if the file node is not found
02390  */
02391 CV_INLINE const char* cvReadStringByName( const CvFileStorage* fs, const CvFileNode* map,
02392                         const char* name, const char* default_value CV_DEFAULT(NULL) )
02393 {
02394     return cvReadString( cvGetFileNodeByName( fs, map, name ), default_value );
02395 }
02396 
02397 
02398 /** @brief Decodes an object and returns a pointer to it.
02399 
02400 The function decodes a user object (creates an object in a native representation from the file
02401 storage subtree) and returns it. The object to be decoded must be an instance of a registered type
02402 that supports the read method (see CvTypeInfo). The type of the object is determined by the type
02403 name that is encoded in the file. If the object is a dynamic structure, it is created either in
02404 memory storage and passed to cvOpenFileStorage or, if a NULL pointer was passed, in temporary
02405 memory storage, which is released when cvReleaseFileStorage is called. Otherwise, if the object is
02406 not a dynamic structure, it is created in a heap and should be released with a specialized function
02407 or by using the generic cvRelease.
02408 @param fs File storage
02409 @param node The root object node
02410 @param attributes Unused parameter
02411  */
02412 CVAPI(void*) cvRead( CvFileStorage* fs, CvFileNode* node,
02413                         CvAttrList* attributes CV_DEFAULT(NULL));
02414 
02415 /** @brief Finds an object by name and decodes it.
02416 
02417 The function is a simple superposition of cvGetFileNodeByName and cvRead.
02418 @param fs File storage
02419 @param map The parent map. If it is NULL, the function searches a top-level node.
02420 @param name The node name
02421 @param attributes Unused parameter
02422  */
02423 CV_INLINE void* cvReadByName( CvFileStorage* fs, const CvFileNode* map,
02424                               const char* name, CvAttrList* attributes CV_DEFAULT(NULL) )
02425 {
02426     return cvRead( fs, cvGetFileNodeByName( fs, map, name ), attributes );
02427 }
02428 
02429 
02430 /** @brief Initializes the file node sequence reader.
02431 
02432 The function initializes the sequence reader to read data from a file node. The initialized reader
02433 can be then passed to cvReadRawDataSlice.
02434 @param fs File storage
02435 @param src The file node (a sequence) to read numbers from
02436 @param reader Pointer to the sequence reader
02437  */
02438 CVAPI(void) cvStartReadRawData( const CvFileStorage* fs, const CvFileNode* src,
02439                                CvSeqReader* reader );
02440 
02441 /** @brief Initializes file node sequence reader.
02442 
02443 The function reads one or more elements from the file node, representing a sequence, to a
02444 user-specified array. The total number of read sequence elements is a product of total and the
02445 number of components in each array element. For example, if dt=2if, the function will read total\*3
02446 sequence elements. As with any sequence, some parts of the file node sequence can be skipped or read
02447 repeatedly by repositioning the reader using cvSetSeqReaderPos.
02448 @param fs File storage
02449 @param reader The sequence reader. Initialize it with cvStartReadRawData .
02450 @param count The number of elements to read
02451 @param dst Pointer to the destination array
02452 @param dt Specification of each array element. It has the same format as in cvWriteRawData .
02453  */
02454 CVAPI(void) cvReadRawDataSlice( const CvFileStorage* fs, CvSeqReader* reader,
02455                                int count, void* dst, const char* dt );
02456 
02457 /** @brief Reads multiple numbers.
02458 
02459 The function reads elements from a file node that represents a sequence of scalars.
02460 @param fs File storage
02461 @param src The file node (a sequence) to read numbers from
02462 @param dst Pointer to the destination array
02463 @param dt Specification of each array element. It has the same format as in cvWriteRawData .
02464  */
02465 CVAPI(void) cvReadRawData( const CvFileStorage* fs, const CvFileNode* src,
02466                           void* dst, const char* dt );
02467 
02468 /** @brief Writes a file node to another file storage.
02469 
02470 The function writes a copy of a file node to file storage. Possible applications of the function are
02471 merging several file storages into one and conversion between XML and YAML formats.
02472 @param fs Destination file storage
02473 @param new_node_name New name of the file node in the destination file storage. To keep the
02474 existing name, use cvcvGetFileNodeName
02475 @param node The written node
02476 @param embed If the written node is a collection and this parameter is not zero, no extra level of
02477 hierarchy is created. Instead, all the elements of node are written into the currently written
02478 structure. Of course, map elements can only be embedded into another map, and sequence elements
02479 can only be embedded into another sequence.
02480  */
02481 CVAPI(void) cvWriteFileNode( CvFileStorage* fs, const char* new_node_name,
02482                             const CvFileNode* node, int embed );
02483 
02484 /** @brief Returns the name of a file node.
02485 
02486 The function returns the name of a file node or NULL, if the file node does not have a name or if
02487 node is NULL.
02488 @param node File node
02489  */
02490 CVAPI(const char*) cvGetFileNodeName( const CvFileNode* node );
02491 
02492 /*********************************** Adding own types ***********************************/
02493 
02494 /** @brief Registers a new type.
02495 
02496 The function registers a new type, which is described by info . The function creates a copy of the
02497 structure, so the user should delete it after calling the function.
02498 @param info Type info structure
02499  */
02500 CVAPI(void) cvRegisterType( const CvTypeInfo* info );
02501 
02502 /** @brief Unregisters the type.
02503 
02504 The function unregisters a type with a specified name. If the name is unknown, it is possible to
02505 locate the type info by an instance of the type using cvTypeOf or by iterating the type list,
02506 starting from cvFirstType, and then calling cvUnregisterType(info->typeName).
02507 @param type_name Name of an unregistered type
02508  */
02509 CVAPI(void) cvUnregisterType( const char* type_name );
02510 
02511 /** @brief Returns the beginning of a type list.
02512 
02513 The function returns the first type in the list of registered types. Navigation through the list can
02514 be done via the prev and next fields of the CvTypeInfo structure.
02515  */
02516 CVAPI(CvTypeInfo*) cvFirstType(void);
02517 
02518 /** @brief Finds a type by its name.
02519 
02520 The function finds a registered type by its name. It returns NULL if there is no type with the
02521 specified name.
02522 @param type_name Type name
02523  */
02524 CVAPI(CvTypeInfo*) cvFindType( const char* type_name );
02525 
02526 /** @brief Returns the type of an object.
02527 
02528 The function finds the type of a given object. It iterates through the list of registered types and
02529 calls the is_instance function/method for every type info structure with that object until one of
02530 them returns non-zero or until the whole list has been traversed. In the latter case, the function
02531 returns NULL.
02532 @param struct_ptr The object pointer
02533  */
02534 CVAPI(CvTypeInfo*) cvTypeOf( const void* struct_ptr );
02535 
02536 /** @brief Releases an object.
02537 
02538 The function finds the type of a given object and calls release with the double pointer.
02539 @param struct_ptr Double pointer to the object
02540  */
02541 CVAPI(void) cvRelease( void** struct_ptr );
02542 
02543 /** @brief Makes a clone of an object.
02544 
02545 The function finds the type of a given object and calls clone with the passed object. Of course, if
02546 you know the object type, for example, struct_ptr is CvMat\*, it is faster to call the specific
02547 function, like cvCloneMat.
02548 @param struct_ptr The object to clone
02549  */
02550 CVAPI(void*) cvClone( const void* struct_ptr );
02551 
02552 /** @brief Saves an object to a file.
02553 
02554 The function saves an object to a file. It provides a simple interface to cvWrite .
02555 @param filename File name
02556 @param struct_ptr Object to save
02557 @param name Optional object name. If it is NULL, the name will be formed from filename .
02558 @param comment Optional comment to put in the beginning of the file
02559 @param attributes Optional attributes passed to cvWrite
02560  */
02561 CVAPI(void) cvSave( const char* filename, const void* struct_ptr,
02562                     const char* name CV_DEFAULT(NULL),
02563                     const char* comment CV_DEFAULT(NULL),
02564                     CvAttrList attributes CV_DEFAULT(cvAttrList()));
02565 
02566 /** @brief Loads an object from a file.
02567 
02568 The function loads an object from a file. It basically reads the specified file, find the first
02569 top-level node and calls cvRead for that node. If the file node does not have type information or
02570 the type information can not be found by the type name, the function returns NULL. After the object
02571 is loaded, the file storage is closed and all the temporary buffers are deleted. Thus, to load a
02572 dynamic structure, such as a sequence, contour, or graph, one should pass a valid memory storage
02573 destination to the function.
02574 @param filename File name
02575 @param memstorage Memory storage for dynamic structures, such as CvSeq or CvGraph . It is not used
02576 for matrices or images.
02577 @param name Optional object name. If it is NULL, the first top-level object in the storage will be
02578 loaded.
02579 @param real_name Optional output parameter that will contain the name of the loaded object
02580 (useful if name=NULL )
02581  */
02582 CVAPI(void*) cvLoad( const char* filename,
02583                      CvMemStorage* memstorage CV_DEFAULT(NULL),
02584                      const char* name CV_DEFAULT(NULL),
02585                      const char** real_name CV_DEFAULT(NULL) );
02586 
02587 /*********************************** Measuring Execution Time ***************************/
02588 
02589 /** helper functions for RNG initialization and accurate time measurement:
02590    uses internal clock counter on x86 */
02591 CVAPI(int64)  cvGetTickCount( void );
02592 CVAPI(double) cvGetTickFrequency( void );
02593 
02594 /*********************************** CPU capabilities ***********************************/
02595 
02596 CVAPI(int) cvCheckHardwareSupport(int feature);
02597 
02598 /*********************************** Multi-Threading ************************************/
02599 
02600 /** retrieve/set the number of threads used in OpenMP implementations */
02601 CVAPI(int)  cvGetNumThreads( void );
02602 CVAPI(void) cvSetNumThreads( int threads CV_DEFAULT(0) );
02603 /** get index of the thread being executed */
02604 CVAPI(int)  cvGetThreadNum( void );
02605 
02606 
02607 /********************************** Error Handling **************************************/
02608 
02609 /** Get current OpenCV error status */
02610 CVAPI(int) cvGetErrStatus( void );
02611 
02612 /** Sets error status silently */
02613 CVAPI(void) cvSetErrStatus( int status );
02614 
02615 #define CV_ErrModeLeaf     0   /* Print error and exit program */
02616 #define CV_ErrModeParent   1   /* Print error and continue */
02617 #define CV_ErrModeSilent   2   /* Don't print and continue */
02618 
02619 /** Retrives current error processing mode */
02620 CVAPI(int)  cvGetErrMode( void );
02621 
02622 /** Sets error processing mode, returns previously used mode */
02623 CVAPI(int) cvSetErrMode( int mode );
02624 
02625 /** Sets error status and performs some additonal actions (displaying message box,
02626  writing message to stderr, terminating application etc.)
02627  depending on the current error mode */
02628 CVAPI(void) cvError( int status, const char* func_name,
02629                     const char* err_msg, const char* file_name, int line );
02630 
02631 /** Retrieves textual description of the error given its code */
02632 CVAPI(const char*) cvErrorStr( int status );
02633 
02634 /** Retrieves detailed information about the last error occured */
02635 CVAPI(int) cvGetErrInfo( const char** errcode_desc, const char** description,
02636                         const char** filename, int* line );
02637 
02638 /** Maps IPP error codes to the counterparts from OpenCV */
02639 CVAPI(int) cvErrorFromIppStatus( int ipp_status );
02640 
02641 typedef int (CV_CDECL *CvErrorCallback)( int status, const char* func_name,
02642                                         const char* err_msg, const char* file_name, int line, void* userdata );
02643 
02644 /** Assigns a new error-handling function */
02645 CVAPI(CvErrorCallback) cvRedirectError( CvErrorCallback error_handler,
02646                                        void* userdata CV_DEFAULT(NULL),
02647                                        void** prev_userdata CV_DEFAULT(NULL) );
02648 
02649 /** Output nothing */
02650 CVAPI(int) cvNulDevReport( int status, const char* func_name, const char* err_msg,
02651                           const char* file_name, int line, void* userdata );
02652 
02653 /** Output to console(fprintf(stderr,...)) */
02654 CVAPI(int) cvStdErrReport( int status, const char* func_name, const char* err_msg,
02655                           const char* file_name, int line, void* userdata );
02656 
02657 /** Output to MessageBox(WIN32) */
02658 CVAPI(int) cvGuiBoxReport( int status, const char* func_name, const char* err_msg,
02659                           const char* file_name, int line, void* userdata );
02660 
02661 #define OPENCV_ERROR(status,func,context)                           \
02662 cvError((status),(func),(context),__FILE__,__LINE__)
02663 
02664 #define OPENCV_ASSERT(expr,func,context)                            \
02665 {if (! (expr))                                      \
02666 {OPENCV_ERROR(CV_StsInternal,(func),(context));}}
02667 
02668 #define OPENCV_CALL( Func )                                         \
02669 {                                                                   \
02670 Func;                                                           \
02671 }
02672 
02673 
02674 /** CV_FUNCNAME macro defines icvFuncName constant which is used by CV_ERROR macro */
02675 #ifdef CV_NO_FUNC_NAMES
02676 #define CV_FUNCNAME( Name )
02677 #define cvFuncName ""
02678 #else
02679 #define CV_FUNCNAME( Name )  \
02680 static char cvFuncName[] = Name
02681 #endif
02682 
02683 
02684 /**
02685  CV_ERROR macro unconditionally raises error with passed code and message.
02686  After raising error, control will be transferred to the exit label.
02687  */
02688 #define CV_ERROR( Code, Msg )                                       \
02689 {                                                                   \
02690     cvError( (Code), cvFuncName, Msg, __FILE__, __LINE__ );        \
02691     __CV_EXIT__;                                                   \
02692 }
02693 
02694 /**
02695  CV_CHECK macro checks error status after CV (or IPL)
02696  function call. If error detected, control will be transferred to the exit
02697  label.
02698  */
02699 #define CV_CHECK()                                                  \
02700 {                                                                   \
02701     if( cvGetErrStatus() < 0 )                                      \
02702         CV_ERROR( CV_StsBackTrace, "Inner function failed." );      \
02703 }
02704 
02705 
02706 /**
02707  CV_CALL macro calls CV (or IPL) function, checks error status and
02708  signals a error if the function failed. Useful in "parent node"
02709  error procesing mode
02710  */
02711 #define CV_CALL( Func )                                             \
02712 {                                                                   \
02713     Func;                                                           \
02714     CV_CHECK();                                                     \
02715 }
02716 
02717 
02718 /** Runtime assertion macro */
02719 #define CV_ASSERT( Condition )                                          \
02720 {                                                                       \
02721     if( !(Condition) )                                                  \
02722         CV_ERROR( CV_StsInternal, "Assertion: " #Condition " failed" ); \
02723 }
02724 
02725 #define __CV_BEGIN__       {
02726 #define __CV_END__         goto exit; exit: ; }
02727 #define __CV_EXIT__        goto exit
02728 
02729 /** @} core_c */
02730 
02731 #ifdef __cplusplus
02732 } // extern "C"
02733 #endif
02734 
02735 #ifdef __cplusplus
02736 
02737 //! @addtogroup core_c_glue
02738 //! @{
02739 
02740 //! class for automatic module/RTTI data registration/unregistration
02741 struct CV_EXPORTS CvType
02742 {
02743     CvType( const char* type_name,
02744             CvIsInstanceFunc is_instance, CvReleaseFunc release=0,
02745             CvReadFunc read=0, CvWriteFunc write=0, CvCloneFunc clone=0 );
02746     ~CvType();
02747     CvTypeInfo* info;
02748 
02749     static CvTypeInfo* first;
02750     static CvTypeInfo* last;
02751 };
02752 
02753 //! @}
02754 
02755 #include "opencv2/core/utility.hpp"
02756 
02757 namespace cv
02758 {
02759 
02760 //! @addtogroup core_c_glue
02761 //! @{
02762 
02763 /////////////////////////////////////////// glue ///////////////////////////////////////////
02764 
02765 //! converts array (CvMat or IplImage) to cv::Mat
02766 CV_EXPORTS Mat cvarrToMat(const CvArr* arr, bool copyData=false,
02767                           bool allowND=true, int coiMode=0,
02768                           AutoBuffer<double>* buf=0);
02769 
02770 static inline Mat cvarrToMatND(const CvArr* arr, bool copyData=false, int coiMode=0)
02771 {
02772     return cvarrToMat(arr, copyData, true, coiMode);
02773 }
02774 
02775 
02776 //! extracts Channel of Interest from CvMat or IplImage and makes cv::Mat out of it.
02777 CV_EXPORTS void extractImageCOI(const CvArr* arr, OutputArray coiimg, int coi=-1);
02778 //! inserts single-channel cv::Mat into a multi-channel CvMat or IplImage
02779 CV_EXPORTS void insertImageCOI(InputArray coiimg, CvArr* arr, int coi=-1);
02780 
02781 
02782 
02783 ////// specialized implementations of DefaultDeleter::operator() for classic OpenCV types //////
02784 
02785 template<> CV_EXPORTS void DefaultDeleter<CvMat>::operator ()(CvMat* obj) const;
02786 template<> CV_EXPORTS void DefaultDeleter<IplImage>::operator ()(IplImage* obj) const;
02787 template<> CV_EXPORTS void DefaultDeleter<CvMatND>::operator ()(CvMatND * obj) const;
02788 template<> CV_EXPORTS void DefaultDeleter<CvSparseMat>::operator ()(CvSparseMat* obj) const;
02789 template<> CV_EXPORTS void DefaultDeleter<CvMemStorage>::operator ()(CvMemStorage* obj) const;
02790 
02791 ////////////// convenient wrappers for operating old-style dynamic structures //////////////
02792 
02793 template<typename _Tp> class SeqIterator;
02794 
02795 typedef Ptr<CvMemStorage> MemStorage;
02796 
02797 /*!
02798  Template Sequence Class derived from CvSeq
02799 
02800  The class provides more convenient access to sequence elements,
02801  STL-style operations and iterators.
02802 
02803  \note The class is targeted for simple data types,
02804     i.e. no constructors or destructors
02805     are called for the sequence elements.
02806 */
02807 template<typename _Tp> class Seq 
02808 {
02809 public:
02810     typedef SeqIterator<_Tp>  iterator ;
02811     typedef SeqIterator<_Tp>  const_iterator ;
02812 
02813     //! the default constructor
02814     Seq();
02815     //! the constructor for wrapping CvSeq structure. The real element type in CvSeq should match _Tp.
02816     Seq(const CvSeq* seq);
02817     //! creates the empty sequence that resides in the specified storage
02818     Seq(MemStorage& storage, int headerSize = sizeof(CvSeq));
02819     //! returns read-write reference to the specified element
02820     _Tp& operator [](int idx);
02821     //! returns read-only reference to the specified element
02822     const _Tp& operator[](int idx) const;
02823     //! returns iterator pointing to the beginning of the sequence
02824     SeqIterator<_Tp>  begin() const;
02825     //! returns iterator pointing to the element following the last sequence element
02826     SeqIterator<_Tp>  end() const;
02827     //! returns the number of elements in the sequence
02828     size_t size() const;
02829     //! returns the type of sequence elements (CV_8UC1 ... CV_64FC(CV_CN_MAX) ...)
02830     int type() const;
02831     //! returns the depth of sequence elements (CV_8U ... CV_64F)
02832     int depth() const;
02833     //! returns the number of channels in each sequence element
02834     int channels() const;
02835     //! returns the size of each sequence element
02836     size_t elemSize() const;
02837     //! returns index of the specified sequence element
02838     size_t index(const _Tp& elem) const;
02839     //! appends the specified element to the end of the sequence
02840     void push_back(const _Tp& elem);
02841     //! appends the specified element to the front of the sequence
02842     void push_front(const _Tp& elem);
02843     //! appends zero or more elements to the end of the sequence
02844     void push_back(const _Tp* elems, size_t count);
02845     //! appends zero or more elements to the front of the sequence
02846     void push_front(const _Tp* elems, size_t count);
02847     //! inserts the specified element to the specified position
02848     void insert(int idx, const _Tp& elem);
02849     //! inserts zero or more elements to the specified position
02850     void insert(int idx, const _Tp* elems, size_t count);
02851     //! removes element at the specified position
02852     void remove(int idx);
02853     //! removes the specified subsequence
02854     void remove(const Range& r);
02855 
02856     //! returns reference to the first sequence element
02857     _Tp& front();
02858     //! returns read-only reference to the first sequence element
02859     const _Tp& front() const;
02860     //! returns reference to the last sequence element
02861     _Tp& back();
02862     //! returns read-only reference to the last sequence element
02863     const _Tp& back() const;
02864     //! returns true iff the sequence contains no elements
02865     bool empty() const;
02866 
02867     //! removes all the elements from the sequence
02868     void clear();
02869     //! removes the first element from the sequence
02870     void pop_front();
02871     //! removes the last element from the sequence
02872     void pop_back();
02873     //! removes zero or more elements from the beginning of the sequence
02874     void pop_front(_Tp* elems, size_t count);
02875     //! removes zero or more elements from the end of the sequence
02876     void pop_back(_Tp* elems, size_t count);
02877 
02878     //! copies the whole sequence or the sequence slice to the specified vector
02879     void copyTo(std::vector<_Tp>& vec, const Range& range=Range::all()) const;
02880     //! returns the vector containing all the sequence elements
02881     operator std::vector<_Tp>() const;
02882 
02883     CvSeq* seq;
02884 };
02885 
02886 
02887 /*!
02888  STL-style Sequence Iterator inherited from the CvSeqReader structure
02889 */
02890 template<typename _Tp> class SeqIterator  : public CvSeqReader
02891 {
02892 public:
02893     //! the default constructor
02894     SeqIterator();
02895     //! the constructor setting the iterator to the beginning or to the end of the sequence
02896     SeqIterator(const Seq<_Tp> & seq, bool seekEnd=false);
02897     //! positions the iterator within the sequence
02898     void seek(size_t pos);
02899     //! reports the current iterator position
02900     size_t tell() const;
02901     //! returns reference to the current sequence element
02902     _Tp& operator *();
02903     //! returns read-only reference to the current sequence element
02904     const _Tp& operator *() const;
02905     //! moves iterator to the next sequence element
02906     SeqIterator & operator ++();
02907     //! moves iterator to the next sequence element
02908     SeqIterator  operator ++(int) const;
02909     //! moves iterator to the previous sequence element
02910     SeqIterator & operator --();
02911     //! moves iterator to the previous sequence element
02912     SeqIterator  operator --(int) const;
02913 
02914     //! moves iterator forward by the specified offset (possibly negative)
02915     SeqIterator & operator +=(int);
02916     //! moves iterator backward by the specified offset (possibly negative)
02917     SeqIterator & operator -=(int);
02918 
02919     // this is index of the current element module seq->total*2
02920     // (to distinguish between 0 and seq->total)
02921     int index;
02922 };
02923 
02924 
02925 
02926 // bridge C++ => C Seq API
02927 CV_EXPORTS schar*  seqPush( CvSeq* seq, const void* element=0);
02928 CV_EXPORTS schar*  seqPushFront( CvSeq* seq, const void* element=0);
02929 CV_EXPORTS void  seqPop( CvSeq* seq, void* element=0);
02930 CV_EXPORTS void  seqPopFront( CvSeq* seq, void* element=0);
02931 CV_EXPORTS void  seqPopMulti( CvSeq* seq, void* elements,
02932                               int count, int in_front=0 );
02933 CV_EXPORTS void  seqRemove( CvSeq* seq, int index );
02934 CV_EXPORTS void  clearSeq( CvSeq* seq );
02935 CV_EXPORTS schar*  getSeqElem( const CvSeq* seq, int index );
02936 CV_EXPORTS void  seqRemoveSlice( CvSeq* seq, CvSlice slice );
02937 CV_EXPORTS void  seqInsertSlice( CvSeq* seq, int before_index, const CvArr* from_arr );
02938 
02939 template<typename _Tp> inline Seq<_Tp>::Seq() : seq(0) {}
02940 template<typename _Tp> inline Seq<_Tp>::Seq( const CvSeq* _seq ) : seq((CvSeq*)_seq)
02941 {
02942     CV_Assert(!_seq || _seq->elem_size == sizeof(_Tp));
02943 }
02944 
02945 template<typename _Tp> inline Seq<_Tp>::Seq( MemStorage& storage,
02946                                              int headerSize )
02947 {
02948     CV_Assert(headerSize >= (int)sizeof(CvSeq));
02949     seq = cvCreateSeq(DataType<_Tp>::type, headerSize, sizeof(_Tp), storage);
02950 }
02951 
02952 template<typename _Tp> inline _Tp& Seq<_Tp>::operator [](int idx)
02953 { return *(_Tp*)getSeqElem(seq, idx); }
02954 
02955 template<typename _Tp> inline const _Tp& Seq<_Tp>::operator [](int idx) const
02956 { return *(_Tp*)getSeqElem(seq, idx); }
02957 
02958 template<typename _Tp> inline SeqIterator<_Tp>  Seq<_Tp>::begin() const
02959 { return SeqIterator<_Tp> (*this); }
02960 
02961 template<typename _Tp> inline SeqIterator<_Tp>  Seq<_Tp>::end() const
02962 { return SeqIterator<_Tp> (*this, true); }
02963 
02964 template<typename _Tp> inline size_t Seq<_Tp>::size() const
02965 { return seq ? seq->total : 0; }
02966 
02967 template<typename _Tp> inline int Seq<_Tp>::type() const
02968 { return seq ? CV_MAT_TYPE(seq->flags) : 0; }
02969 
02970 template<typename _Tp> inline int Seq<_Tp>::depth() const
02971 { return seq ? CV_MAT_DEPTH(seq->flags) : 0; }
02972 
02973 template<typename _Tp> inline int Seq<_Tp>::channels() const
02974 { return seq ? CV_MAT_CN(seq->flags) : 0; }
02975 
02976 template<typename _Tp> inline size_t Seq<_Tp>::elemSize() const
02977 { return seq ? seq->elem_size : 0; }
02978 
02979 template<typename _Tp> inline size_t Seq<_Tp>::index(const _Tp& elem) const
02980 { return cvSeqElemIdx(seq, &elem); }
02981 
02982 template<typename _Tp> inline void Seq<_Tp>::push_back(const _Tp& elem)
02983 { cvSeqPush(seq, &elem); }
02984 
02985 template<typename _Tp> inline void Seq<_Tp>::push_front(const _Tp& elem)
02986 { cvSeqPushFront(seq, &elem); }
02987 
02988 template<typename _Tp> inline void Seq<_Tp>::push_back(const _Tp* elem, size_t count)
02989 { cvSeqPushMulti(seq, elem, (int)count, 0); }
02990 
02991 template<typename _Tp> inline void Seq<_Tp>::push_front(const _Tp* elem, size_t count)
02992 { cvSeqPushMulti(seq, elem, (int)count, 1); }
02993 
02994 template<typename _Tp> inline _Tp& Seq<_Tp>::back()
02995 { return *(_Tp*)getSeqElem(seq, -1); }
02996 
02997 template<typename _Tp> inline const _Tp& Seq<_Tp>::back() const
02998 { return *(const _Tp*)getSeqElem(seq, -1); }
02999 
03000 template<typename _Tp> inline _Tp& Seq<_Tp>::front()
03001 { return *(_Tp*)getSeqElem(seq, 0); }
03002 
03003 template<typename _Tp> inline const _Tp& Seq<_Tp>::front() const
03004 { return *(const _Tp*)getSeqElem(seq, 0); }
03005 
03006 template<typename _Tp> inline bool Seq<_Tp>::empty() const
03007 { return !seq || seq->total == 0; }
03008 
03009 template<typename _Tp> inline void Seq<_Tp>::clear()
03010 { if(seq) clearSeq(seq); }
03011 
03012 template<typename _Tp> inline void Seq<_Tp>::pop_back()
03013 { seqPop(seq); }
03014 
03015 template<typename _Tp> inline void Seq<_Tp>::pop_front()
03016 { seqPopFront(seq); }
03017 
03018 template<typename _Tp> inline void Seq<_Tp>::pop_back(_Tp* elem, size_t count)
03019 { seqPopMulti(seq, elem, (int)count, 0); }
03020 
03021 template<typename _Tp> inline void Seq<_Tp>::pop_front(_Tp* elem, size_t count)
03022 { seqPopMulti(seq, elem, (int)count, 1); }
03023 
03024 template<typename _Tp> inline void Seq<_Tp>::insert(int idx, const _Tp& elem)
03025 { seqInsert(seq, idx, &elem); }
03026 
03027 template<typename _Tp> inline void Seq<_Tp>::insert(int idx, const _Tp* elems, size_t count)
03028 {
03029     CvMat m = cvMat(1, count, DataType<_Tp>::type, elems);
03030     seqInsertSlice(seq, idx, &m);
03031 }
03032 
03033 template<typename _Tp> inline void Seq<_Tp>::remove(int idx)
03034 { seqRemove(seq, idx); }
03035 
03036 template<typename _Tp> inline void Seq<_Tp>::remove(const Range& r)
03037 { seqRemoveSlice(seq, cvSlice(r.start, r.end)); }
03038 
03039 template<typename _Tp> inline void Seq<_Tp>::copyTo(std::vector<_Tp>& vec, const Range& range) const
03040 {
03041     size_t len = !seq ? 0 : range == Range::all() ? seq->total : range.end - range.start;
03042     vec.resize(len);
03043     if( seq && len )
03044         cvCvtSeqToArray(seq, &vec[0], range);
03045 }
03046 
03047 template<typename _Tp> inline Seq<_Tp>::operator std::vector<_Tp> () const
03048 {
03049     std::vector<_Tp> vec;
03050     copyTo(vec);
03051     return vec;
03052 }
03053 
03054 template<typename _Tp> inline SeqIterator<_Tp>::SeqIterator()
03055 { memset(this, 0, sizeof(*this)); }
03056 
03057 template<typename _Tp> inline SeqIterator<_Tp>::SeqIterator(const Seq<_Tp> & _seq, bool seekEnd)
03058 {
03059     cvStartReadSeq(_seq.seq, this);
03060     index = seekEnd ? _seq.seq->total : 0;
03061 }
03062 
03063 template<typename _Tp> inline void SeqIterator<_Tp>::seek(size_t pos)
03064 {
03065     cvSetSeqReaderPos(this, (int)pos, false);
03066     index = pos;
03067 }
03068 
03069 template<typename _Tp> inline size_t SeqIterator<_Tp>::tell() const
03070 { return index; }
03071 
03072 template<typename _Tp> inline _Tp& SeqIterator<_Tp>::operator *()
03073 { return *(_Tp*)ptr; }
03074 
03075 template<typename _Tp> inline const _Tp& SeqIterator<_Tp>::operator *() const
03076 { return *(const _Tp*)ptr; }
03077 
03078 template<typename _Tp> inline SeqIterator<_Tp> & SeqIterator<_Tp>::operator ++()
03079 {
03080     CV_NEXT_SEQ_ELEM(sizeof(_Tp), *this);
03081     if( ++index >= seq->total*2 )
03082         index = 0;
03083     return *this;
03084 }
03085 
03086 template<typename _Tp> inline SeqIterator<_Tp>  SeqIterator<_Tp>::operator ++(int) const
03087 {
03088     SeqIterator<_Tp>  it = *this;
03089     ++*this;
03090     return it;
03091 }
03092 
03093 template<typename _Tp> inline SeqIterator<_Tp> & SeqIterator<_Tp>::operator --()
03094 {
03095     CV_PREV_SEQ_ELEM(sizeof(_Tp), *this);
03096     if( --index < 0 )
03097         index = seq->total*2-1;
03098     return *this;
03099 }
03100 
03101 template<typename _Tp> inline SeqIterator<_Tp>  SeqIterator<_Tp>::operator --(int) const
03102 {
03103     SeqIterator<_Tp>  it = *this;
03104     --*this;
03105     return it;
03106 }
03107 
03108 template<typename _Tp> inline SeqIterator<_Tp> & SeqIterator<_Tp>::operator +=(int delta)
03109 {
03110     cvSetSeqReaderPos(this, delta, 1);
03111     index += delta;
03112     int n = seq->total*2;
03113     if( index < 0 )
03114         index += n;
03115     if( index >= n )
03116         index -= n;
03117     return *this;
03118 }
03119 
03120 template<typename _Tp> inline SeqIterator<_Tp> & SeqIterator<_Tp>::operator -=(int delta)
03121 {
03122     return (*this += -delta);
03123 }
03124 
03125 template<typename _Tp> inline ptrdiff_t operator - (const SeqIterator<_Tp> & a,
03126                                                     const SeqIterator<_Tp> & b)
03127 {
03128     ptrdiff_t delta = a.index - b.index, n = a.seq->total;
03129     if( delta > n || delta < -n )
03130         delta += delta < 0 ? n : -n;
03131     return delta;
03132 }
03133 
03134 template<typename _Tp> inline bool operator == (const SeqIterator<_Tp>& a,
03135                                                 const SeqIterator<_Tp>& b)
03136 {
03137     return a.seq == b.seq && a.index == b.index;
03138 }
03139 
03140 template<typename _Tp> inline bool operator != (const SeqIterator<_Tp>& a,
03141                                                 const SeqIterator<_Tp>& b)
03142 {
03143     return !(a == b);
03144 }
03145 
03146 //! @}
03147 
03148 } // cv
03149 
03150 #endif
03151 
03152 #endif
03153