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, .yml or .yaml for YAML and .json for JSON.
01980 
01981 At the same time, it also supports adding parameters like "example.xml?base64". The three ways
01982 are the same:
01983 @snippet samples/cpp/filestorage_base64.cpp suffix_in_file_name
01984 @snippet samples/cpp/filestorage_base64.cpp flag_write_base64
01985 @snippet samples/cpp/filestorage_base64.cpp flag_write_and_flag_base64
01986 
01987 The function returns a pointer to the CvFileStorage structure.
01988 If the file cannot be opened then the function returns NULL.
01989 @param filename Name of the file associated with the storage
01990 @param memstorage Memory storage used for temporary data and for
01991 :   storing dynamic structures, such as CvSeq or CvGraph . If it is NULL, a temporary memory
01992     storage is created and used.
01993 @param flags Can be one of the following:
01994 > -   **CV_STORAGE_READ** the storage is open for reading
01995 > -   **CV_STORAGE_WRITE** the storage is open for writing
01996       (use **CV_STORAGE_WRITE | CV_STORAGE_WRITE_BASE64** to write rawdata in Base64)
01997 @param encoding
01998  */
01999 CVAPI(CvFileStorage*)  cvOpenFileStorage( const char* filename, CvMemStorage* memstorage,
02000                                           int flags, const char* encoding CV_DEFAULT(NULL) );
02001 
02002 /** @brief Releases file storage.
02003 
02004 The function closes the file associated with the storage and releases all the temporary structures.
02005 It must be called after all I/O operations with the storage are finished.
02006 @param fs Double pointer to the released file storage
02007  */
02008 CVAPI(void) cvReleaseFileStorage( CvFileStorage** fs );
02009 
02010 /** returns attribute value or 0 (NULL) if there is no such attribute */
02011 CVAPI(const char*) cvAttrValue( const CvAttrList* attr, const char* attr_name );
02012 
02013 /** @brief Starts writing a new structure.
02014 
02015 The function starts writing a compound structure (collection) that can be a sequence or a map. After
02016 all the structure fields, which can be scalars or structures, are written, cvEndWriteStruct should
02017 be called. The function can be used to group some objects or to implement the write function for a
02018 some user object (see CvTypeInfo).
02019 @param fs File storage
02020 @param name Name of the written structure. The structure can be accessed by this name when the
02021 storage is read.
02022 @param struct_flags A combination one of the following values:
02023 -   **CV_NODE_SEQ** the written structure is a sequence (see discussion of CvFileStorage ),
02024     that is, its elements do not have a name.
02025 -   **CV_NODE_MAP** the written structure is a map (see discussion of CvFileStorage ), that
02026     is, all its elements have names.
02027 One and only one of the two above flags must be specified
02028 -   **CV_NODE_FLOW** the optional flag that makes sense only for YAML streams. It means that
02029      the structure is written as a flow (not as a block), which is more compact. It is
02030      recommended to use this flag for structures or arrays whose elements are all scalars.
02031 @param type_name Optional parameter - the object type name. In
02032     case of XML it is written as a type_id attribute of the structure opening tag. In the case of
02033     YAML it is written after a colon following the structure name (see the example in
02034     CvFileStorage description). In case of JSON it is written as a name/value pair.
02035     Mainly it is used with user objects. When the storage is read, the
02036     encoded type name is used to determine the object type (see CvTypeInfo and cvFindType ).
02037 @param attributes This parameter is not used in the current implementation
02038  */
02039 CVAPI(void) cvStartWriteStruct( CvFileStorage* fs, const char* name,
02040                                 int struct_flags, const char* type_name CV_DEFAULT(NULL),
02041                                 CvAttrList attributes CV_DEFAULT(cvAttrList()));
02042 
02043 /** @brief Finishes writing to a file node collection.
02044 @param fs File storage
02045 @sa cvStartWriteStruct.
02046  */
02047 CVAPI(void) cvEndWriteStruct( CvFileStorage* fs );
02048 
02049 /** @brief Writes an integer value.
02050 
02051 The function writes a single integer value (with or without a name) to the file storage.
02052 @param fs File storage
02053 @param name Name of the written value. Should be NULL if and only if the parent structure is a
02054 sequence.
02055 @param value The written value
02056  */
02057 CVAPI(void) cvWriteInt( CvFileStorage* fs, const char* name, int value );
02058 
02059 /** @brief Writes a floating-point value.
02060 
02061 The function writes a single floating-point value (with or without a name) to file storage. Special
02062 values are encoded as follows: NaN (Not A Number) as .NaN, infinity as +.Inf or -.Inf.
02063 
02064 The following example shows how to use the low-level writing functions to store custom structures,
02065 such as termination criteria, without registering a new type. :
02066 @code
02067     void write_termcriteria( CvFileStorage* fs, const char* struct_name,
02068                              CvTermCriteria* termcrit )
02069     {
02070         cvStartWriteStruct( fs, struct_name, CV_NODE_MAP, NULL, cvAttrList(0,0));
02071         cvWriteComment( fs, "termination criteria", 1 ); // just a description
02072         if( termcrit->type & CV_TERMCRIT_ITER )
02073             cvWriteInteger( fs, "max_iterations", termcrit->max_iter );
02074         if( termcrit->type & CV_TERMCRIT_EPS )
02075             cvWriteReal( fs, "accuracy", termcrit->epsilon );
02076         cvEndWriteStruct( fs );
02077     }
02078 @endcode
02079 @param fs File storage
02080 @param name Name of the written value. Should be NULL if and only if the parent structure is a
02081 sequence.
02082 @param value The written value
02083 */
02084 CVAPI(void) cvWriteReal( CvFileStorage* fs, const char* name, double value );
02085 
02086 /** @brief Writes a text string.
02087 
02088 The function writes a text string to file storage.
02089 @param fs File storage
02090 @param name Name of the written string . Should be NULL if and only if the parent structure is a
02091 sequence.
02092 @param str The written text string
02093 @param quote If non-zero, the written string is put in quotes, regardless of whether they are
02094 required. Otherwise, if the flag is zero, quotes are used only when they are required (e.g. when
02095 the string starts with a digit or contains spaces).
02096  */
02097 CVAPI(void) cvWriteString( CvFileStorage* fs, const char* name,
02098                            const char* str, int quote CV_DEFAULT(0) );
02099 
02100 /** @brief Writes a comment.
02101 
02102 The function writes a comment into file storage. The comments are skipped when the storage is read.
02103 @param fs File storage
02104 @param comment The written comment, single-line or multi-line
02105 @param eol_comment If non-zero, the function tries to put the comment at the end of current line.
02106 If the flag is zero, if the comment is multi-line, or if it does not fit at the end of the current
02107 line, the comment starts a new line.
02108  */
02109 CVAPI(void) cvWriteComment( CvFileStorage* fs, const char* comment,
02110                             int eol_comment );
02111 
02112 /** @brief Writes an object to file storage.
02113 
02114 The function writes an object to file storage. First, the appropriate type info is found using
02115 cvTypeOf. Then, the write method associated with the type info is called.
02116 
02117 Attributes are used to customize the writing procedure. The standard types support the following
02118 attributes (all the dt attributes have the same format as in cvWriteRawData):
02119 
02120 -# CvSeq
02121     -   **header_dt** description of user fields of the sequence header that follow CvSeq, or
02122         CvChain (if the sequence is a Freeman chain) or CvContour (if the sequence is a contour or
02123         point sequence)
02124     -   **dt** description of the sequence elements.
02125     -   **recursive** if the attribute is present and is not equal to "0" or "false", the whole
02126         tree of sequences (contours) is stored.
02127 -# CvGraph
02128     -   **header_dt** description of user fields of the graph header that follows CvGraph;
02129     -   **vertex_dt** description of user fields of graph vertices
02130     -   **edge_dt** description of user fields of graph edges (note that the edge weight is
02131         always written, so there is no need to specify it explicitly)
02132 
02133 Below is the code that creates the YAML file shown in the CvFileStorage description:
02134 @code
02135     #include "cxcore.h"
02136 
02137     int main( int argc, char** argv )
02138     {
02139         CvMat* mat = cvCreateMat( 3, 3, CV_32F );
02140         CvFileStorage* fs = cvOpenFileStorage( "example.yml", 0, CV_STORAGE_WRITE );
02141 
02142         cvSetIdentity( mat );
02143         cvWrite( fs, "A", mat, cvAttrList(0,0) );
02144 
02145         cvReleaseFileStorage( &fs );
02146         cvReleaseMat( &mat );
02147         return 0;
02148     }
02149 @endcode
02150 @param fs File storage
02151 @param name Name of the written object. Should be NULL if and only if the parent structure is a
02152 sequence.
02153 @param ptr Pointer to the object
02154 @param attributes The attributes of the object. They are specific for each particular type (see
02155 the discussion below).
02156  */
02157 CVAPI(void) cvWrite( CvFileStorage* fs, const char* name, const void* ptr,
02158                          CvAttrList attributes CV_DEFAULT(cvAttrList()));
02159 
02160 /** @brief Starts the next stream.
02161 
02162 The function finishes the currently written stream and starts the next stream. In the case of XML
02163 the file with multiple streams looks like this:
02164 @code{.xml}
02165     <opencv_storage>
02166     <!-- stream #1 data -->
02167     </opencv_storage>
02168     <opencv_storage>
02169     <!-- stream #2 data -->
02170     </opencv_storage>
02171     ...
02172 @endcode
02173 The YAML file will look like this:
02174 @code{.yaml}
02175     %YAML 1.0
02176     # stream #1 data
02177     ...
02178     ---
02179     # stream #2 data
02180 @endcode
02181 This is useful for concatenating files or for resuming the writing process.
02182 @param fs File storage
02183  */
02184 CVAPI(void) cvStartNextStream( CvFileStorage* fs );
02185 
02186 /** @brief Writes multiple numbers.
02187 
02188 The function writes an array, whose elements consist of single or multiple numbers. The function
02189 call can be replaced with a loop containing a few cvWriteInt and cvWriteReal calls, but a single
02190 call is more efficient. Note that because none of the elements have a name, they should be written
02191 to a sequence rather than a map.
02192 @param fs File storage
02193 @param src Pointer to the written array
02194 @param len Number of the array elements to write
02195 @param dt Specification of each array element, see @ref format_spec "format specification"
02196  */
02197 CVAPI(void) cvWriteRawData( CvFileStorage* fs, const void* src,
02198                                 int len, const char* dt );
02199 
02200 /** @brief Writes multiple numbers in Base64.
02201 
02202 If either CV_STORAGE_WRITE_BASE64 or cv::FileStorage::WRITE_BASE64 is used,
02203 this function will be the same as cvWriteRawData. If neither, the main
02204 difference is that it outputs a sequence in Base64 encoding rather than
02205 in plain text.
02206 
02207 This function can only be used to write a sequence with a type "binary".
02208 
02209 Consider the following two examples where their output is the same:
02210 @snippet samples/cpp/filestorage_base64.cpp without_base64_flag
02211 and
02212 @snippet samples/cpp/filestorage_base64.cpp with_write_base64_flag
02213 
02214 @param fs File storage
02215 @param src Pointer to the written array
02216 @param len Number of the array elements to write
02217 @param dt Specification of each array element, see @ref format_spec "format specification"
02218 */
02219 CVAPI(void) cvWriteRawDataBase64( CvFileStorage* fs, const void* src,
02220                                  int len, const char* dt );
02221 
02222 /** @brief Returns a unique pointer for a given name.
02223 
02224 The function returns a unique pointer for each particular file node name. This pointer can be then
02225 passed to the cvGetFileNode function that is faster than cvGetFileNodeByName because it compares
02226 text strings by comparing pointers rather than the strings' content.
02227 
02228 Consider the following example where an array of points is encoded as a sequence of 2-entry maps:
02229 @code
02230     points:
02231       - { x: 10, y: 10 }
02232       - { x: 20, y: 20 }
02233       - { x: 30, y: 30 }
02234       # ...
02235 @endcode
02236 Then, it is possible to get hashed "x" and "y" pointers to speed up decoding of the points. :
02237 @code
02238     #include "cxcore.h"
02239 
02240     int main( int argc, char** argv )
02241     {
02242         CvFileStorage* fs = cvOpenFileStorage( "points.yml", 0, CV_STORAGE_READ );
02243         CvStringHashNode* x_key = cvGetHashedNode( fs, "x", -1, 1 );
02244         CvStringHashNode* y_key = cvGetHashedNode( fs, "y", -1, 1 );
02245         CvFileNode* points = cvGetFileNodeByName( fs, 0, "points" );
02246 
02247         if( CV_NODE_IS_SEQ(points->tag) )
02248         {
02249             CvSeq* seq = points->data.seq;
02250             int i, total = seq->total;
02251             CvSeqReader reader;
02252             cvStartReadSeq( seq, &reader, 0 );
02253             for( i = 0; i < total; i++ )
02254             {
02255                 CvFileNode* pt = (CvFileNode*)reader.ptr;
02256     #if 1 // faster variant
02257                 CvFileNode* xnode = cvGetFileNode( fs, pt, x_key, 0 );
02258                 CvFileNode* ynode = cvGetFileNode( fs, pt, y_key, 0 );
02259                 assert( xnode && CV_NODE_IS_INT(xnode->tag) &&
02260                         ynode && CV_NODE_IS_INT(ynode->tag));
02261                 int x = xnode->data.i; // or x = cvReadInt( xnode, 0 );
02262                 int y = ynode->data.i; // or y = cvReadInt( ynode, 0 );
02263     #elif 1 // slower variant; does not use x_key & y_key
02264                 CvFileNode* xnode = cvGetFileNodeByName( fs, pt, "x" );
02265                 CvFileNode* ynode = cvGetFileNodeByName( fs, pt, "y" );
02266                 assert( xnode && CV_NODE_IS_INT(xnode->tag) &&
02267                         ynode && CV_NODE_IS_INT(ynode->tag));
02268                 int x = xnode->data.i; // or x = cvReadInt( xnode, 0 );
02269                 int y = ynode->data.i; // or y = cvReadInt( ynode, 0 );
02270     #else // the slowest yet the easiest to use variant
02271                 int x = cvReadIntByName( fs, pt, "x", 0 );
02272                 int y = cvReadIntByName( fs, pt, "y", 0 );
02273     #endif
02274                 CV_NEXT_SEQ_ELEM( seq->elem_size, reader );
02275                 printf("
02276             }
02277         }
02278         cvReleaseFileStorage( &fs );
02279         return 0;
02280     }
02281 @endcode
02282 Please note that whatever method of accessing a map you are using, it is still much slower than
02283 using plain sequences; for example, in the above example, it is more efficient to encode the points
02284 as pairs of integers in a single numeric sequence.
02285 @param fs File storage
02286 @param name Literal node name
02287 @param len Length of the name (if it is known apriori), or -1 if it needs to be calculated
02288 @param create_missing Flag that specifies, whether an absent key should be added into the hash table
02289 */
02290 CVAPI(CvStringHashNode*) cvGetHashedKey( CvFileStorage* fs, const char* name,
02291                                         int len CV_DEFAULT(-1),
02292                                         int create_missing CV_DEFAULT(0));
02293 
02294 /** @brief Retrieves one of the top-level nodes of the file storage.
02295 
02296 The function returns one of the top-level file nodes. The top-level nodes do not have a name, they
02297 correspond to the streams that are stored one after another in the file storage. If the index is out
02298 of range, the function returns a NULL pointer, so all the top-level nodes can be iterated by
02299 subsequent calls to the function with stream_index=0,1,..., until the NULL pointer is returned.
02300 This function can be used as a base for recursive traversal of the file storage.
02301 @param fs File storage
02302 @param stream_index Zero-based index of the stream. See cvStartNextStream . In most cases,
02303 there is only one stream in the file; however, there can be several.
02304  */
02305 CVAPI(CvFileNode*) cvGetRootFileNode( const CvFileStorage* fs,
02306                                      int stream_index CV_DEFAULT(0) );
02307 
02308 /** @brief Finds a node in a map or file storage.
02309 
02310 The function finds a file node. It is a faster version of cvGetFileNodeByName (see
02311 cvGetHashedKey discussion). Also, the function can insert a new node, if it is not in the map yet.
02312 @param fs File storage
02313 @param map The parent map. If it is NULL, the function searches a top-level node. If both map and
02314 key are NULLs, the function returns the root file node - a map that contains top-level nodes.
02315 @param key Unique pointer to the node name, retrieved with cvGetHashedKey
02316 @param create_missing Flag that specifies whether an absent node should be added to the map
02317  */
02318 CVAPI(CvFileNode*) cvGetFileNode( CvFileStorage* fs, CvFileNode* map,
02319                                  const CvStringHashNode* key,
02320                                  int create_missing CV_DEFAULT(0) );
02321 
02322 /** @brief Finds a node in a map or file storage.
02323 
02324 The function finds a file node by name. The node is searched either in map or, if the pointer is
02325 NULL, among the top-level file storage nodes. Using this function for maps and cvGetSeqElem (or
02326 sequence reader) for sequences, it is possible to navigate through the file storage. To speed up
02327 multiple queries for a certain key (e.g., in the case of an array of structures) one may use a
02328 combination of cvGetHashedKey and cvGetFileNode.
02329 @param fs File storage
02330 @param map The parent map. If it is NULL, the function searches in all the top-level nodes
02331 (streams), starting with the first one.
02332 @param name The file node name
02333  */
02334 CVAPI(CvFileNode*) cvGetFileNodeByName( const CvFileStorage* fs,
02335                                        const CvFileNode* map,
02336                                        const char* name );
02337 
02338 /** @brief Retrieves an integer value from a file node.
02339 
02340 The function returns an integer that is represented by the file node. If the file node is NULL, the
02341 default_value is returned (thus, it is convenient to call the function right after cvGetFileNode
02342 without checking for a NULL pointer). If the file node has type CV_NODE_INT, then node->data.i is
02343 returned. If the file node has type CV_NODE_REAL, then node->data.f is converted to an integer
02344 and returned. Otherwise the error is reported.
02345 @param node File node
02346 @param default_value The value that is returned if node is NULL
02347  */
02348 CV_INLINE int cvReadInt( const CvFileNode* node, int default_value CV_DEFAULT(0) )
02349 {
02350     return !node ? default_value :
02351         CV_NODE_IS_INT(node->tag) ? node->data.i :
02352         CV_NODE_IS_REAL(node->tag) ? cvRound(node->data.f) : 0x7fffffff;
02353 }
02354 
02355 /** @brief Finds a file node and returns its value.
02356 
02357 The function is a simple superposition of cvGetFileNodeByName and cvReadInt.
02358 @param fs File storage
02359 @param map The parent map. If it is NULL, the function searches a top-level node.
02360 @param name The node name
02361 @param default_value The value that is returned if the file node is not found
02362  */
02363 CV_INLINE int cvReadIntByName( const CvFileStorage* fs, const CvFileNode* map,
02364                          const char* name, int default_value CV_DEFAULT(0) )
02365 {
02366     return cvReadInt( cvGetFileNodeByName( fs, map, name ), default_value );
02367 }
02368 
02369 /** @brief Retrieves a floating-point value from a file node.
02370 
02371 The function returns a floating-point value that is represented by the file node. If the file node
02372 is NULL, the default_value is returned (thus, it is convenient to call the function right after
02373 cvGetFileNode without checking for a NULL pointer). If the file node has type CV_NODE_REAL ,
02374 then node->data.f is returned. If the file node has type CV_NODE_INT , then node-:math:>data.f
02375 is converted to floating-point and returned. Otherwise the result is not determined.
02376 @param node File node
02377 @param default_value The value that is returned if node is NULL
02378  */
02379 CV_INLINE double cvReadReal( const CvFileNode* node, double default_value CV_DEFAULT(0.) )
02380 {
02381     return !node ? default_value :
02382         CV_NODE_IS_INT(node->tag) ? (double)node->data.i :
02383         CV_NODE_IS_REAL(node->tag) ? node->data.f : 1e300;
02384 }
02385 
02386 /** @brief Finds a file node and returns its value.
02387 
02388 The function is a simple superposition of cvGetFileNodeByName and cvReadReal .
02389 @param fs File storage
02390 @param map The parent map. If it is NULL, the function searches a top-level node.
02391 @param name The node name
02392 @param default_value The value that is returned if the file node is not found
02393  */
02394 CV_INLINE double cvReadRealByName( const CvFileStorage* fs, const CvFileNode* map,
02395                         const char* name, double default_value CV_DEFAULT(0.) )
02396 {
02397     return cvReadReal( cvGetFileNodeByName( fs, map, name ), default_value );
02398 }
02399 
02400 /** @brief Retrieves a text string from a file node.
02401 
02402 The function returns a text string that is represented by the file node. If the file node is NULL,
02403 the default_value is returned (thus, it is convenient to call the function right after
02404 cvGetFileNode without checking for a NULL pointer). If the file node has type CV_NODE_STR , then
02405 node-:math:>data.str.ptr is returned. Otherwise the result is not determined.
02406 @param node File node
02407 @param default_value The value that is returned if node is NULL
02408  */
02409 CV_INLINE const char* cvReadString( const CvFileNode* node,
02410                         const char* default_value CV_DEFAULT(NULL) )
02411 {
02412     return !node ? default_value : CV_NODE_IS_STRING(node->tag) ? node->data.str.ptr : 0;
02413 }
02414 
02415 /** @brief Finds a file node by its name and returns its value.
02416 
02417 The function is a simple superposition of cvGetFileNodeByName and cvReadString .
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 default_value The value that is returned if the file node is not found
02422  */
02423 CV_INLINE const char* cvReadStringByName( const CvFileStorage* fs, const CvFileNode* map,
02424                         const char* name, const char* default_value CV_DEFAULT(NULL) )
02425 {
02426     return cvReadString( cvGetFileNodeByName( fs, map, name ), default_value );
02427 }
02428 
02429 
02430 /** @brief Decodes an object and returns a pointer to it.
02431 
02432 The function decodes a user object (creates an object in a native representation from the file
02433 storage subtree) and returns it. The object to be decoded must be an instance of a registered type
02434 that supports the read method (see CvTypeInfo). The type of the object is determined by the type
02435 name that is encoded in the file. If the object is a dynamic structure, it is created either in
02436 memory storage and passed to cvOpenFileStorage or, if a NULL pointer was passed, in temporary
02437 memory storage, which is released when cvReleaseFileStorage is called. Otherwise, if the object is
02438 not a dynamic structure, it is created in a heap and should be released with a specialized function
02439 or by using the generic cvRelease.
02440 @param fs File storage
02441 @param node The root object node
02442 @param attributes Unused parameter
02443  */
02444 CVAPI(void*) cvRead( CvFileStorage* fs, CvFileNode* node,
02445                         CvAttrList* attributes CV_DEFAULT(NULL));
02446 
02447 /** @brief Finds an object by name and decodes it.
02448 
02449 The function is a simple superposition of cvGetFileNodeByName and cvRead.
02450 @param fs File storage
02451 @param map The parent map. If it is NULL, the function searches a top-level node.
02452 @param name The node name
02453 @param attributes Unused parameter
02454  */
02455 CV_INLINE void* cvReadByName( CvFileStorage* fs, const CvFileNode* map,
02456                               const char* name, CvAttrList* attributes CV_DEFAULT(NULL) )
02457 {
02458     return cvRead( fs, cvGetFileNodeByName( fs, map, name ), attributes );
02459 }
02460 
02461 
02462 /** @brief Initializes the file node sequence reader.
02463 
02464 The function initializes the sequence reader to read data from a file node. The initialized reader
02465 can be then passed to cvReadRawDataSlice.
02466 @param fs File storage
02467 @param src The file node (a sequence) to read numbers from
02468 @param reader Pointer to the sequence reader
02469  */
02470 CVAPI(void) cvStartReadRawData( const CvFileStorage* fs, const CvFileNode* src,
02471                                CvSeqReader* reader );
02472 
02473 /** @brief Initializes file node sequence reader.
02474 
02475 The function reads one or more elements from the file node, representing a sequence, to a
02476 user-specified array. The total number of read sequence elements is a product of total and the
02477 number of components in each array element. For example, if dt=2if, the function will read total\*3
02478 sequence elements. As with any sequence, some parts of the file node sequence can be skipped or read
02479 repeatedly by repositioning the reader using cvSetSeqReaderPos.
02480 @param fs File storage
02481 @param reader The sequence reader. Initialize it with cvStartReadRawData .
02482 @param count The number of elements to read
02483 @param dst Pointer to the destination array
02484 @param dt Specification of each array element. It has the same format as in cvWriteRawData .
02485  */
02486 CVAPI(void) cvReadRawDataSlice( const CvFileStorage* fs, CvSeqReader* reader,
02487                                int count, void* dst, const char* dt );
02488 
02489 /** @brief Reads multiple numbers.
02490 
02491 The function reads elements from a file node that represents a sequence of scalars.
02492 @param fs File storage
02493 @param src The file node (a sequence) to read numbers from
02494 @param dst Pointer to the destination array
02495 @param dt Specification of each array element. It has the same format as in cvWriteRawData .
02496  */
02497 CVAPI(void) cvReadRawData( const CvFileStorage* fs, const CvFileNode* src,
02498                           void* dst, const char* dt );
02499 
02500 /** @brief Writes a file node to another file storage.
02501 
02502 The function writes a copy of a file node to file storage. Possible applications of the function are
02503 merging several file storages into one and conversion between XML, YAML and JSON formats.
02504 @param fs Destination file storage
02505 @param new_node_name New name of the file node in the destination file storage. To keep the
02506 existing name, use cvcvGetFileNodeName
02507 @param node The written node
02508 @param embed If the written node is a collection and this parameter is not zero, no extra level of
02509 hierarchy is created. Instead, all the elements of node are written into the currently written
02510 structure. Of course, map elements can only be embedded into another map, and sequence elements
02511 can only be embedded into another sequence.
02512  */
02513 CVAPI(void) cvWriteFileNode( CvFileStorage* fs, const char* new_node_name,
02514                             const CvFileNode* node, int embed );
02515 
02516 /** @brief Returns the name of a file node.
02517 
02518 The function returns the name of a file node or NULL, if the file node does not have a name or if
02519 node is NULL.
02520 @param node File node
02521  */
02522 CVAPI(const char*) cvGetFileNodeName( const CvFileNode* node );
02523 
02524 /*********************************** Adding own types ***********************************/
02525 
02526 /** @brief Registers a new type.
02527 
02528 The function registers a new type, which is described by info . The function creates a copy of the
02529 structure, so the user should delete it after calling the function.
02530 @param info Type info structure
02531  */
02532 CVAPI(void) cvRegisterType( const CvTypeInfo* info );
02533 
02534 /** @brief Unregisters the type.
02535 
02536 The function unregisters a type with a specified name. If the name is unknown, it is possible to
02537 locate the type info by an instance of the type using cvTypeOf or by iterating the type list,
02538 starting from cvFirstType, and then calling cvUnregisterType(info->typeName).
02539 @param type_name Name of an unregistered type
02540  */
02541 CVAPI(void) cvUnregisterType( const char* type_name );
02542 
02543 /** @brief Returns the beginning of a type list.
02544 
02545 The function returns the first type in the list of registered types. Navigation through the list can
02546 be done via the prev and next fields of the CvTypeInfo structure.
02547  */
02548 CVAPI(CvTypeInfo*) cvFirstType(void);
02549 
02550 /** @brief Finds a type by its name.
02551 
02552 The function finds a registered type by its name. It returns NULL if there is no type with the
02553 specified name.
02554 @param type_name Type name
02555  */
02556 CVAPI(CvTypeInfo*) cvFindType( const char* type_name );
02557 
02558 /** @brief Returns the type of an object.
02559 
02560 The function finds the type of a given object. It iterates through the list of registered types and
02561 calls the is_instance function/method for every type info structure with that object until one of
02562 them returns non-zero or until the whole list has been traversed. In the latter case, the function
02563 returns NULL.
02564 @param struct_ptr The object pointer
02565  */
02566 CVAPI(CvTypeInfo*) cvTypeOf( const void* struct_ptr );
02567 
02568 /** @brief Releases an object.
02569 
02570 The function finds the type of a given object and calls release with the double pointer.
02571 @param struct_ptr Double pointer to the object
02572  */
02573 CVAPI(void) cvRelease( void** struct_ptr );
02574 
02575 /** @brief Makes a clone of an object.
02576 
02577 The function finds the type of a given object and calls clone with the passed object. Of course, if
02578 you know the object type, for example, struct_ptr is CvMat\*, it is faster to call the specific
02579 function, like cvCloneMat.
02580 @param struct_ptr The object to clone
02581  */
02582 CVAPI(void*) cvClone( const void* struct_ptr );
02583 
02584 /** @brief Saves an object to a file.
02585 
02586 The function saves an object to a file. It provides a simple interface to cvWrite .
02587 @param filename File name
02588 @param struct_ptr Object to save
02589 @param name Optional object name. If it is NULL, the name will be formed from filename .
02590 @param comment Optional comment to put in the beginning of the file
02591 @param attributes Optional attributes passed to cvWrite
02592  */
02593 CVAPI(void) cvSave( const char* filename, const void* struct_ptr,
02594                     const char* name CV_DEFAULT(NULL),
02595                     const char* comment CV_DEFAULT(NULL),
02596                     CvAttrList attributes CV_DEFAULT(cvAttrList()));
02597 
02598 /** @brief Loads an object from a file.
02599 
02600 The function loads an object from a file. It basically reads the specified file, find the first
02601 top-level node and calls cvRead for that node. If the file node does not have type information or
02602 the type information can not be found by the type name, the function returns NULL. After the object
02603 is loaded, the file storage is closed and all the temporary buffers are deleted. Thus, to load a
02604 dynamic structure, such as a sequence, contour, or graph, one should pass a valid memory storage
02605 destination to the function.
02606 @param filename File name
02607 @param memstorage Memory storage for dynamic structures, such as CvSeq or CvGraph . It is not used
02608 for matrices or images.
02609 @param name Optional object name. If it is NULL, the first top-level object in the storage will be
02610 loaded.
02611 @param real_name Optional output parameter that will contain the name of the loaded object
02612 (useful if name=NULL )
02613  */
02614 CVAPI(void*) cvLoad( const char* filename,
02615                      CvMemStorage* memstorage CV_DEFAULT(NULL),
02616                      const char* name CV_DEFAULT(NULL),
02617                      const char** real_name CV_DEFAULT(NULL) );
02618 
02619 /*********************************** Measuring Execution Time ***************************/
02620 
02621 /** helper functions for RNG initialization and accurate time measurement:
02622    uses internal clock counter on x86 */
02623 CVAPI(int64)  cvGetTickCount( void );
02624 CVAPI(double) cvGetTickFrequency( void );
02625 
02626 /*********************************** CPU capabilities ***********************************/
02627 
02628 CVAPI(int) cvCheckHardwareSupport(int feature);
02629 
02630 /*********************************** Multi-Threading ************************************/
02631 
02632 /** retrieve/set the number of threads used in OpenMP implementations */
02633 CVAPI(int)  cvGetNumThreads( void );
02634 CVAPI(void) cvSetNumThreads( int threads CV_DEFAULT(0) );
02635 /** get index of the thread being executed */
02636 CVAPI(int)  cvGetThreadNum( void );
02637 
02638 
02639 /********************************** Error Handling **************************************/
02640 
02641 /** Get current OpenCV error status */
02642 CVAPI(int) cvGetErrStatus( void );
02643 
02644 /** Sets error status silently */
02645 CVAPI(void) cvSetErrStatus( int status );
02646 
02647 #define CV_ErrModeLeaf     0   /* Print error and exit program */
02648 #define CV_ErrModeParent   1   /* Print error and continue */
02649 #define CV_ErrModeSilent   2   /* Don't print and continue */
02650 
02651 /** Retrives current error processing mode */
02652 CVAPI(int)  cvGetErrMode( void );
02653 
02654 /** Sets error processing mode, returns previously used mode */
02655 CVAPI(int) cvSetErrMode( int mode );
02656 
02657 /** Sets error status and performs some additonal actions (displaying message box,
02658  writing message to stderr, terminating application etc.)
02659  depending on the current error mode */
02660 CVAPI(void) cvError( int status, const char* func_name,
02661                     const char* err_msg, const char* file_name, int line );
02662 
02663 /** Retrieves textual description of the error given its code */
02664 CVAPI(const char*) cvErrorStr( int status );
02665 
02666 /** Retrieves detailed information about the last error occured */
02667 CVAPI(int) cvGetErrInfo( const char** errcode_desc, const char** description,
02668                         const char** filename, int* line );
02669 
02670 /** Maps IPP error codes to the counterparts from OpenCV */
02671 CVAPI(int) cvErrorFromIppStatus( int ipp_status );
02672 
02673 typedef int (CV_CDECL *CvErrorCallback)( int status, const char* func_name,
02674                                         const char* err_msg, const char* file_name, int line, void* userdata );
02675 
02676 /** Assigns a new error-handling function */
02677 CVAPI(CvErrorCallback) cvRedirectError( CvErrorCallback error_handler,
02678                                        void* userdata CV_DEFAULT(NULL),
02679                                        void** prev_userdata CV_DEFAULT(NULL) );
02680 
02681 /** Output nothing */
02682 CVAPI(int) cvNulDevReport( int status, const char* func_name, const char* err_msg,
02683                           const char* file_name, int line, void* userdata );
02684 
02685 /** Output to console(fprintf(stderr,...)) */
02686 CVAPI(int) cvStdErrReport( int status, const char* func_name, const char* err_msg,
02687                           const char* file_name, int line, void* userdata );
02688 
02689 /** Output to MessageBox(WIN32) */
02690 CVAPI(int) cvGuiBoxReport( int status, const char* func_name, const char* err_msg,
02691                           const char* file_name, int line, void* userdata );
02692 
02693 #define OPENCV_ERROR(status,func,context)                           \
02694 cvError((status),(func),(context),__FILE__,__LINE__)
02695 
02696 #define OPENCV_ASSERT(expr,func,context)                            \
02697 {if (! (expr))                                      \
02698 {OPENCV_ERROR(CV_StsInternal,(func),(context));}}
02699 
02700 #define OPENCV_CALL( Func )                                         \
02701 {                                                                   \
02702 Func;                                                           \
02703 }
02704 
02705 
02706 /** CV_FUNCNAME macro defines icvFuncName constant which is used by CV_ERROR macro */
02707 #ifdef CV_NO_FUNC_NAMES
02708 #define CV_FUNCNAME( Name )
02709 #define cvFuncName ""
02710 #else
02711 #define CV_FUNCNAME( Name )  \
02712 static char cvFuncName[] = Name
02713 #endif
02714 
02715 
02716 /**
02717  CV_ERROR macro unconditionally raises error with passed code and message.
02718  After raising error, control will be transferred to the exit label.
02719  */
02720 #define CV_ERROR( Code, Msg )                                       \
02721 {                                                                   \
02722     cvError( (Code), cvFuncName, Msg, __FILE__, __LINE__ );        \
02723     __CV_EXIT__;                                                   \
02724 }
02725 
02726 /**
02727  CV_CHECK macro checks error status after CV (or IPL)
02728  function call. If error detected, control will be transferred to the exit
02729  label.
02730  */
02731 #define CV_CHECK()                                                  \
02732 {                                                                   \
02733     if( cvGetErrStatus() < 0 )                                      \
02734         CV_ERROR( CV_StsBackTrace, "Inner function failed." );      \
02735 }
02736 
02737 
02738 /**
02739  CV_CALL macro calls CV (or IPL) function, checks error status and
02740  signals a error if the function failed. Useful in "parent node"
02741  error procesing mode
02742  */
02743 #define CV_CALL( Func )                                             \
02744 {                                                                   \
02745     Func;                                                           \
02746     CV_CHECK();                                                     \
02747 }
02748 
02749 
02750 /** Runtime assertion macro */
02751 #define CV_ASSERT( Condition )                                          \
02752 {                                                                       \
02753     if( !(Condition) )                                                  \
02754         CV_ERROR( CV_StsInternal, "Assertion: " #Condition " failed" ); \
02755 }
02756 
02757 #define __CV_BEGIN__       {
02758 #define __CV_END__         goto exit; exit: ; }
02759 #define __CV_EXIT__        goto exit
02760 
02761 /** @} core_c */
02762 
02763 #ifdef __cplusplus
02764 } // extern "C"
02765 #endif
02766 
02767 #ifdef __cplusplus
02768 
02769 //! @addtogroup core_c_glue
02770 //! @{
02771 
02772 //! class for automatic module/RTTI data registration/unregistration
02773 struct CV_EXPORTS CvType
02774 {
02775     CvType( const char* type_name,
02776             CvIsInstanceFunc is_instance, CvReleaseFunc release=0,
02777             CvReadFunc read=0, CvWriteFunc write=0, CvCloneFunc clone=0 );
02778     ~CvType();
02779     CvTypeInfo* info;
02780 
02781     static CvTypeInfo* first;
02782     static CvTypeInfo* last;
02783 };
02784 
02785 //! @}
02786 
02787 #include "opencv2/core/utility.hpp"
02788 
02789 namespace cv
02790 {
02791 
02792 //! @addtogroup core_c_glue
02793 //! @{
02794 
02795 /////////////////////////////////////////// glue ///////////////////////////////////////////
02796 
02797 //! converts array (CvMat or IplImage) to cv::Mat
02798 CV_EXPORTS Mat cvarrToMat(const CvArr* arr, bool copyData=false,
02799                           bool allowND=true, int coiMode=0,
02800                           AutoBuffer<double>* buf=0);
02801 
02802 static inline Mat cvarrToMatND(const CvArr* arr, bool copyData=false, int coiMode=0)
02803 {
02804     return cvarrToMat(arr, copyData, true, coiMode);
02805 }
02806 
02807 
02808 //! extracts Channel of Interest from CvMat or IplImage and makes cv::Mat out of it.
02809 CV_EXPORTS void extractImageCOI(const CvArr* arr, OutputArray coiimg, int coi=-1);
02810 //! inserts single-channel cv::Mat into a multi-channel CvMat or IplImage
02811 CV_EXPORTS void insertImageCOI(InputArray coiimg, CvArr* arr, int coi=-1);
02812 
02813 
02814 
02815 ////// specialized implementations of DefaultDeleter::operator() for classic OpenCV types //////
02816 
02817 template<> CV_EXPORTS void DefaultDeleter<CvMat>::operator ()(CvMat* obj) const;
02818 template<> CV_EXPORTS void DefaultDeleter<IplImage>::operator ()(IplImage* obj) const;
02819 template<> CV_EXPORTS void DefaultDeleter<CvMatND>::operator ()(CvMatND * obj) const;
02820 template<> CV_EXPORTS void DefaultDeleter<CvSparseMat>::operator ()(CvSparseMat* obj) const;
02821 template<> CV_EXPORTS void DefaultDeleter<CvMemStorage>::operator ()(CvMemStorage* obj) const;
02822 
02823 ////////////// convenient wrappers for operating old-style dynamic structures //////////////
02824 
02825 template<typename _Tp> class SeqIterator;
02826 
02827 typedef Ptr<CvMemStorage> MemStorage;
02828 
02829 /*!
02830  Template Sequence Class derived from CvSeq
02831 
02832  The class provides more convenient access to sequence elements,
02833  STL-style operations and iterators.
02834 
02835  \note The class is targeted for simple data types,
02836     i.e. no constructors or destructors
02837     are called for the sequence elements.
02838 */
02839 template<typename _Tp> class Seq 
02840 {
02841 public:
02842     typedef SeqIterator<_Tp>  iterator ;
02843     typedef SeqIterator<_Tp>  const_iterator ;
02844 
02845     //! the default constructor
02846     Seq();
02847     //! the constructor for wrapping CvSeq structure. The real element type in CvSeq should match _Tp.
02848     Seq(const CvSeq* seq);
02849     //! creates the empty sequence that resides in the specified storage
02850     Seq(MemStorage& storage, int headerSize = sizeof(CvSeq));
02851     //! returns read-write reference to the specified element
02852     _Tp& operator [](int idx);
02853     //! returns read-only reference to the specified element
02854     const _Tp& operator[](int idx) const;
02855     //! returns iterator pointing to the beginning of the sequence
02856     SeqIterator<_Tp>  begin() const;
02857     //! returns iterator pointing to the element following the last sequence element
02858     SeqIterator<_Tp>  end() const;
02859     //! returns the number of elements in the sequence
02860     size_t size() const;
02861     //! returns the type of sequence elements (CV_8UC1 ... CV_64FC(CV_CN_MAX) ...)
02862     int type() const;
02863     //! returns the depth of sequence elements (CV_8U ... CV_64F)
02864     int depth() const;
02865     //! returns the number of channels in each sequence element
02866     int channels() const;
02867     //! returns the size of each sequence element
02868     size_t elemSize() const;
02869     //! returns index of the specified sequence element
02870     size_t index(const _Tp& elem) const;
02871     //! appends the specified element to the end of the sequence
02872     void push_back(const _Tp& elem);
02873     //! appends the specified element to the front of the sequence
02874     void push_front(const _Tp& elem);
02875     //! appends zero or more elements to the end of the sequence
02876     void push_back(const _Tp* elems, size_t count);
02877     //! appends zero or more elements to the front of the sequence
02878     void push_front(const _Tp* elems, size_t count);
02879     //! inserts the specified element to the specified position
02880     void insert(int idx, const _Tp& elem);
02881     //! inserts zero or more elements to the specified position
02882     void insert(int idx, const _Tp* elems, size_t count);
02883     //! removes element at the specified position
02884     void remove(int idx);
02885     //! removes the specified subsequence
02886     void remove(const Range& r);
02887 
02888     //! returns reference to the first sequence element
02889     _Tp& front();
02890     //! returns read-only reference to the first sequence element
02891     const _Tp& front() const;
02892     //! returns reference to the last sequence element
02893     _Tp& back();
02894     //! returns read-only reference to the last sequence element
02895     const _Tp& back() const;
02896     //! returns true iff the sequence contains no elements
02897     bool empty() const;
02898 
02899     //! removes all the elements from the sequence
02900     void clear();
02901     //! removes the first element from the sequence
02902     void pop_front();
02903     //! removes the last element from the sequence
02904     void pop_back();
02905     //! removes zero or more elements from the beginning of the sequence
02906     void pop_front(_Tp* elems, size_t count);
02907     //! removes zero or more elements from the end of the sequence
02908     void pop_back(_Tp* elems, size_t count);
02909 
02910     //! copies the whole sequence or the sequence slice to the specified vector
02911     void copyTo(std::vector<_Tp>& vec, const Range& range=Range::all()) const;
02912     //! returns the vector containing all the sequence elements
02913     operator std::vector<_Tp>() const;
02914 
02915     CvSeq* seq;
02916 };
02917 
02918 
02919 /*!
02920  STL-style Sequence Iterator inherited from the CvSeqReader structure
02921 */
02922 template<typename _Tp> class SeqIterator  : public CvSeqReader
02923 {
02924 public:
02925     //! the default constructor
02926     SeqIterator();
02927     //! the constructor setting the iterator to the beginning or to the end of the sequence
02928     SeqIterator(const Seq<_Tp> & seq, bool seekEnd=false);
02929     //! positions the iterator within the sequence
02930     void seek(size_t pos);
02931     //! reports the current iterator position
02932     size_t tell() const;
02933     //! returns reference to the current sequence element
02934     _Tp& operator *();
02935     //! returns read-only reference to the current sequence element
02936     const _Tp& operator *() const;
02937     //! moves iterator to the next sequence element
02938     SeqIterator & operator ++();
02939     //! moves iterator to the next sequence element
02940     SeqIterator  operator ++(int) const;
02941     //! moves iterator to the previous sequence element
02942     SeqIterator & operator --();
02943     //! moves iterator to the previous sequence element
02944     SeqIterator  operator --(int) const;
02945 
02946     //! moves iterator forward by the specified offset (possibly negative)
02947     SeqIterator & operator +=(int);
02948     //! moves iterator backward by the specified offset (possibly negative)
02949     SeqIterator & operator -=(int);
02950 
02951     // this is index of the current element module seq->total*2
02952     // (to distinguish between 0 and seq->total)
02953     int index;
02954 };
02955 
02956 
02957 
02958 // bridge C++ => C Seq API
02959 CV_EXPORTS schar*  seqPush( CvSeq* seq, const void* element=0);
02960 CV_EXPORTS schar*  seqPushFront( CvSeq* seq, const void* element=0);
02961 CV_EXPORTS void  seqPop( CvSeq* seq, void* element=0);
02962 CV_EXPORTS void  seqPopFront( CvSeq* seq, void* element=0);
02963 CV_EXPORTS void  seqPopMulti( CvSeq* seq, void* elements,
02964                               int count, int in_front=0 );
02965 CV_EXPORTS void  seqRemove( CvSeq* seq, int index );
02966 CV_EXPORTS void  clearSeq( CvSeq* seq );
02967 CV_EXPORTS schar*  getSeqElem( const CvSeq* seq, int index );
02968 CV_EXPORTS void  seqRemoveSlice( CvSeq* seq, CvSlice slice );
02969 CV_EXPORTS void  seqInsertSlice( CvSeq* seq, int before_index, const CvArr* from_arr );
02970 
02971 template<typename _Tp> inline Seq<_Tp>::Seq() : seq(0) {}
02972 template<typename _Tp> inline Seq<_Tp>::Seq( const CvSeq* _seq ) : seq((CvSeq*)_seq)
02973 {
02974     CV_Assert(!_seq || _seq->elem_size == sizeof(_Tp));
02975 }
02976 
02977 template<typename _Tp> inline Seq<_Tp>::Seq( MemStorage& storage,
02978                                              int headerSize )
02979 {
02980     CV_Assert(headerSize >= (int)sizeof(CvSeq));
02981     seq = cvCreateSeq(DataType<_Tp>::type, headerSize, sizeof(_Tp), storage);
02982 }
02983 
02984 template<typename _Tp> inline _Tp& Seq<_Tp>::operator [](int idx)
02985 { return *(_Tp*)getSeqElem(seq, idx); }
02986 
02987 template<typename _Tp> inline const _Tp& Seq<_Tp>::operator [](int idx) const
02988 { return *(_Tp*)getSeqElem(seq, idx); }
02989 
02990 template<typename _Tp> inline SeqIterator<_Tp>  Seq<_Tp>::begin() const
02991 { return SeqIterator<_Tp> (*this); }
02992 
02993 template<typename _Tp> inline SeqIterator<_Tp>  Seq<_Tp>::end() const
02994 { return SeqIterator<_Tp> (*this, true); }
02995 
02996 template<typename _Tp> inline size_t Seq<_Tp>::size() const
02997 { return seq ? seq->total : 0; }
02998 
02999 template<typename _Tp> inline int Seq<_Tp>::type() const
03000 { return seq ? CV_MAT_TYPE(seq->flags) : 0; }
03001 
03002 template<typename _Tp> inline int Seq<_Tp>::depth() const
03003 { return seq ? CV_MAT_DEPTH(seq->flags) : 0; }
03004 
03005 template<typename _Tp> inline int Seq<_Tp>::channels() const
03006 { return seq ? CV_MAT_CN(seq->flags) : 0; }
03007 
03008 template<typename _Tp> inline size_t Seq<_Tp>::elemSize() const
03009 { return seq ? seq->elem_size : 0; }
03010 
03011 template<typename _Tp> inline size_t Seq<_Tp>::index(const _Tp& elem) const
03012 { return cvSeqElemIdx(seq, &elem); }
03013 
03014 template<typename _Tp> inline void Seq<_Tp>::push_back(const _Tp& elem)
03015 { cvSeqPush(seq, &elem); }
03016 
03017 template<typename _Tp> inline void Seq<_Tp>::push_front(const _Tp& elem)
03018 { cvSeqPushFront(seq, &elem); }
03019 
03020 template<typename _Tp> inline void Seq<_Tp>::push_back(const _Tp* elem, size_t count)
03021 { cvSeqPushMulti(seq, elem, (int)count, 0); }
03022 
03023 template<typename _Tp> inline void Seq<_Tp>::push_front(const _Tp* elem, size_t count)
03024 { cvSeqPushMulti(seq, elem, (int)count, 1); }
03025 
03026 template<typename _Tp> inline _Tp& Seq<_Tp>::back()
03027 { return *(_Tp*)getSeqElem(seq, -1); }
03028 
03029 template<typename _Tp> inline const _Tp& Seq<_Tp>::back() const
03030 { return *(const _Tp*)getSeqElem(seq, -1); }
03031 
03032 template<typename _Tp> inline _Tp& Seq<_Tp>::front()
03033 { return *(_Tp*)getSeqElem(seq, 0); }
03034 
03035 template<typename _Tp> inline const _Tp& Seq<_Tp>::front() const
03036 { return *(const _Tp*)getSeqElem(seq, 0); }
03037 
03038 template<typename _Tp> inline bool Seq<_Tp>::empty() const
03039 { return !seq || seq->total == 0; }
03040 
03041 template<typename _Tp> inline void Seq<_Tp>::clear()
03042 { if(seq) clearSeq(seq); }
03043 
03044 template<typename _Tp> inline void Seq<_Tp>::pop_back()
03045 { seqPop(seq); }
03046 
03047 template<typename _Tp> inline void Seq<_Tp>::pop_front()
03048 { seqPopFront(seq); }
03049 
03050 template<typename _Tp> inline void Seq<_Tp>::pop_back(_Tp* elem, size_t count)
03051 { seqPopMulti(seq, elem, (int)count, 0); }
03052 
03053 template<typename _Tp> inline void Seq<_Tp>::pop_front(_Tp* elem, size_t count)
03054 { seqPopMulti(seq, elem, (int)count, 1); }
03055 
03056 template<typename _Tp> inline void Seq<_Tp>::insert(int idx, const _Tp& elem)
03057 { seqInsert(seq, idx, &elem); }
03058 
03059 template<typename _Tp> inline void Seq<_Tp>::insert(int idx, const _Tp* elems, size_t count)
03060 {
03061     CvMat m = cvMat(1, count, DataType<_Tp>::type, elems);
03062     seqInsertSlice(seq, idx, &m);
03063 }
03064 
03065 template<typename _Tp> inline void Seq<_Tp>::remove(int idx)
03066 { seqRemove(seq, idx); }
03067 
03068 template<typename _Tp> inline void Seq<_Tp>::remove(const Range& r)
03069 { seqRemoveSlice(seq, cvSlice(r.start, r.end)); }
03070 
03071 template<typename _Tp> inline void Seq<_Tp>::copyTo(std::vector<_Tp>& vec, const Range& range) const
03072 {
03073     size_t len = !seq ? 0 : range == Range::all() ? seq->total : range.end - range.start;
03074     vec.resize(len);
03075     if( seq && len )
03076         cvCvtSeqToArray(seq, &vec[0], range);
03077 }
03078 
03079 template<typename _Tp> inline Seq<_Tp>::operator std::vector<_Tp> () const
03080 {
03081     std::vector<_Tp> vec;
03082     copyTo(vec);
03083     return vec;
03084 }
03085 
03086 template<typename _Tp> inline SeqIterator<_Tp>::SeqIterator()
03087 { memset(this, 0, sizeof(*this)); }
03088 
03089 template<typename _Tp> inline SeqIterator<_Tp>::SeqIterator(const Seq<_Tp> & _seq, bool seekEnd)
03090 {
03091     cvStartReadSeq(_seq.seq, this);
03092     index = seekEnd ? _seq.seq->total : 0;
03093 }
03094 
03095 template<typename _Tp> inline void SeqIterator<_Tp>::seek(size_t pos)
03096 {
03097     cvSetSeqReaderPos(this, (int)pos, false);
03098     index = pos;
03099 }
03100 
03101 template<typename _Tp> inline size_t SeqIterator<_Tp>::tell() const
03102 { return index; }
03103 
03104 template<typename _Tp> inline _Tp& SeqIterator<_Tp>::operator *()
03105 { return *(_Tp*)ptr; }
03106 
03107 template<typename _Tp> inline const _Tp& SeqIterator<_Tp>::operator *() const
03108 { return *(const _Tp*)ptr; }
03109 
03110 template<typename _Tp> inline SeqIterator<_Tp> & SeqIterator<_Tp>::operator ++()
03111 {
03112     CV_NEXT_SEQ_ELEM(sizeof(_Tp), *this);
03113     if( ++index >= seq->total*2 )
03114         index = 0;
03115     return *this;
03116 }
03117 
03118 template<typename _Tp> inline SeqIterator<_Tp>  SeqIterator<_Tp>::operator ++(int) const
03119 {
03120     SeqIterator<_Tp>  it = *this;
03121     ++*this;
03122     return it;
03123 }
03124 
03125 template<typename _Tp> inline SeqIterator<_Tp> & SeqIterator<_Tp>::operator --()
03126 {
03127     CV_PREV_SEQ_ELEM(sizeof(_Tp), *this);
03128     if( --index < 0 )
03129         index = seq->total*2-1;
03130     return *this;
03131 }
03132 
03133 template<typename _Tp> inline SeqIterator<_Tp>  SeqIterator<_Tp>::operator --(int) const
03134 {
03135     SeqIterator<_Tp>  it = *this;
03136     --*this;
03137     return it;
03138 }
03139 
03140 template<typename _Tp> inline SeqIterator<_Tp> & SeqIterator<_Tp>::operator +=(int delta)
03141 {
03142     cvSetSeqReaderPos(this, delta, 1);
03143     index += delta;
03144     int n = seq->total*2;
03145     if( index < 0 )
03146         index += n;
03147     if( index >= n )
03148         index -= n;
03149     return *this;
03150 }
03151 
03152 template<typename _Tp> inline SeqIterator<_Tp> & SeqIterator<_Tp>::operator -=(int delta)
03153 {
03154     return (*this += -delta);
03155 }
03156 
03157 template<typename _Tp> inline ptrdiff_t operator - (const SeqIterator<_Tp> & a,
03158                                                     const SeqIterator<_Tp> & b)
03159 {
03160     ptrdiff_t delta = a.index - b.index, n = a.seq->total;
03161     if( delta > n || delta < -n )
03162         delta += delta < 0 ? n : -n;
03163     return delta;
03164 }
03165 
03166 template<typename _Tp> inline bool operator == (const SeqIterator<_Tp>& a,
03167                                                 const SeqIterator<_Tp>& b)
03168 {
03169     return a.seq == b.seq && a.index == b.index;
03170 }
03171 
03172 template<typename _Tp> inline bool operator != (const SeqIterator<_Tp>& a,
03173                                                 const SeqIterator<_Tp>& b)
03174 {
03175     return !(a == b);
03176 }
03177 
03178 //! @}
03179 
03180 } // cv
03181 
03182 #endif
03183 
03184 #endif