Basic Structures and Operations Reference



Helper structures


CvPoint

2D point with integer coordinates

    typedef struct CvPoint
    {
        int x; /* x-coordinate, usually zero-based */
        int y; /* y-coordinate, usually zero-based */
    }
    CvPoint;

    /* the constructor function */
    inline CvPoint cvPoint( int x, int y );

    /* conversion from CvPoint2D32f */
    inline CvPoint cvPointFrom32f( CvPoint2D32f point );

CvPoint2D32f

2D point with floating-point coordinates

    typedef struct CvPoint2D32f
    {
        float x; /* x-coordinate, usually zero-based */
        float y; /* y-coordinate, usually zero-based */
    }
    CvPoint2D32f;

    /* the constructor function */
    inline CvPoint2D32f cvPoint2D32f( double x, double y );

    /* conversion from CvPoint */
    inline CvPoint2D32f cvPointTo32f( CvPoint point );

CvPoint3D32f

3D point with floating-point coordinates

    typedef struct CvPoint3D32f
    {
        float x; /* x-coordinate, usually zero-based */
        float y; /* y-coordinate, usually zero-based */
        float z; /* z-coordinate, usually zero-based */
    }
    CvPoint3D32f;

    /* the constructor function */
    inline CvPoint3D32f cvPoint3D32f( double x, double y, double z );

CvSize

pixel-accurate size of a rectangle

    typedef struct CvSize
    {
        int width; /* width of the rectangle */
        int height; /* height of the rectangle */
    }
    CvSize;

    /* the constructor function */
    inline CvSize cvSize( int width, int height );

CvSize2D32f

sub-pixel accurate size of a rectangle

    typedef struct CvSize2D32f
    {
        float width; /* width of the box */
        float height; /* height of the box */
    }
    CvSize2D32f;

    /* the constructor function */
    inline CvSize2D cvSize32f( double width, double height );

CvRect

offset and size of a rectangle

    typedef struct CvRect
    {
        int x; /* x-coordinate of the left-most rectangle corner[s] */
        int y; /* y-coordinate of the top-most or bottom-most
                  rectangle corner[s] */
        int width; /* width of the rectangle */
        int height; /* height of the rectangle */
    }
    CvRect;

    /* the constructor function */
    inline CvRect cvRect( int x, int y, int width, int height );

CvScalar

A container for 1-,2-,3- or 4-tuples of numbers

    typedef struct CvScalar
    {
        double val[4];
    }
    CvScalar;

    /* the constructor function: initializes val[0] with val0, val[1] with val1 etc. */
    inline CvScalar cvScalar( double val0, double val1=0,
                              double val2=0, double val3=0 );
    /* the constructor function: initializes val[0]...val[3] with val0123 */
    inline CvScalar cvScalarAll( double val0123 );

    /* the constructor function: initializes val[0] with val0, val[1]...val[3] with zeros */
    inline CvScalar cvRealScalar( double val0 );

Array structures


CvMat

Multi-channel matrix

    typedef struct CvMat
    {
        int type; /* CvMat signature (CV_MAT_MAGIC_VAL), element type and flags */
        int step; /* full row length in bytes */

        int* refcount; /* underlying data reference counter */

        union
        {
            uchar* ptr;
            short* s;
            int* i;
            float* fl;
            double* db;
        } data; /* data pointers */

    #ifdef __cplusplus
        union
        {
            int rows;
            int height;
        };

        union
        {
            int cols;
            int width;
        };
    #else
        int rows; /* number of rows */
        int cols; /* number of columns */
    #endif

    } CvMat;

CvMatND

Multi-dimensional dense multi-channel array

    typedef struct CvMatND
    {
        int type; /* CvMatND signature (CV_MATND_MAGIC_VAL), element type and flags */
        int dims; /* number of array dimensions */

        int* refcount; /* underlying data reference counter */

        union
        {
            uchar* ptr;
            short* s;
            int* i;
            float* fl;
            double* db;
        } data; /* data pointers */

        /* pairs (number of elements, distance between elements in bytes) for
           every dimension */
        struct
        {
            int size;
            int step;
        }
        dim[CV_MAX_DIM];

    } CvMatND;

CvSparseMat

Multi-dimensional sparse multi-channel array

    typedef struct CvSparseMat
    {
        int type; /* CvSparseMat signature (CV_SPARSE_MAT_MAGIC_VAL), element type and flags */
        int dims; /* number of dimensions */
        int* refcount; /* reference counter - not used */
        struct CvSet* heap; /* a pool of hashtable nodes */
        void** hashtable; /* hashtable: each entry has a list of nodes
                             having the same "hashvalue modulo hashsize" */
        int hashsize; /* size of hashtable */
        int total; /* total number of sparse array nodes */
        int valoffset; /* value offset in bytes for the array nodes */
        int idxoffset; /* index offset in bytes for the array nodes */
        int size[CV_MAX_DIM]; /* array of dimension sizes */

    } CvSparseMat;

IplImage

IPL image header

    typedef struct _IplImage
    {
        int  nSize;         /* sizeof(IplImage) */
        int  ID;            /* version (=0)*/
        int  nChannels;     /* Most of OpenCV functions support 1,2,3 or 4 channels */
        int  alphaChannel;  /* ignored by OpenCV */
        int  depth;         /* pixel depth in bits: IPL_DEPTH_8U, IPL_DEPTH_8S, IPL_DEPTH_16S,
                               IPL_DEPTH_32S, IPL_DEPTH_32F and IPL_DEPTH_64F are supported */
        char colorModel[4]; /* ignored by OpenCV */
        char channelSeq[4]; /* ditto */
        int  dataOrder;     /* 0 - interleaved color channels, 1 - separate color channels.
                               cvCreateImage can only create interleaved images */
        int  origin;        /* 0 - top-left origin,
                               1 - bottom-left origin (Windows bitmaps style) */
        int  align;         /* Alignment of image rows (4 or 8).
                               OpenCV ignores it and uses widthStep instead */
        int  width;         /* image width in pixels */
        int  height;        /* image height in pixels */
        struct _IplROI *roi;/* image ROI. when it is not NULL, this specifies image region to process */
        struct _IplImage *maskROI; /* must be NULL in OpenCV */
        void  *imageId;     /* ditto */
        struct _IplTileInfo *tileInfo; /* ditto */
        int  imageSize;     /* image data size in bytes
                               (=image->height*image->widthStep
                               in case of interleaved data)*/
        char *imageData;  /* pointer to aligned image data */
        int  widthStep;   /* size of aligned image row in bytes */
        int  BorderMode[4]; /* border completion mode, ignored by OpenCV */
        int  BorderConst[4]; /* ditto */
        char *imageDataOrigin; /* pointer to a very origin of image data
                                  (not necessarily aligned) -
                                  it is needed for correct image deallocation */
    }
    IplImage;

The structure IplImage came from Intel Image Processing Library where the format is native. OpenCV supports only subset of the possible IplImage formats:

Besides the above restrictions, OpenCV handles ROI differently. It requires that the sizes or ROI sizes of all source and destination images match exactly (according to the operation, e.g. for cvPyrDown destination width(height) must be equal to source width(height) divided by 2 ±1), whereas IPL processes the intersection area - that is, the sizes or ROI sizes of all images may vary independently.


CvArr

Arbitrary array

    typedef void CvArr;

CvArr* is used only as a function parameter to specify that the function accepts arrays of more than a single type, for example IplImage* and CvMat*. The particular array type is determined in runtime from looking at the first 4-byte field of array header.


Arrays: Allocation, deallocation, copying; setting and retrieving parts


Alloc

Allocates memory buffer

void* cvAlloc( size_t size );

size
Buffer size in bytes.

The function cvAlloc allocates size bytes and returns pointer to the allocated buffer. In case of error the function reports an error and returns NULL pointer. By default cvAlloc calls icvAlloc which itself calls malloc, however it is possible to assign user-defined memory allocation/deallocation functions using cvSetMemoryManager function.


Free

Deallocates memory buffer

void cvFree( void** buffer );

buffer
Double pointer to released buffer.

The function cvFree deallocates memory buffer allocated by cvAlloc. It clears the pointer to buffer upon exit, that is why the double pointer is used. If *buffer is already NULL, the function does nothing


CreateImage

Creates header and allocates data

IplImage* cvCreateImage( CvSize size, int depth, int channels );

size
Image width and height.
depth
Bit depth of image elements. Can be one of:
IPL_DEPTH_8U - unsigned 8-bit integers
IPL_DEPTH_8S - signed 8-bit integers
IPL_DEPTH_16S - signed 16-bit integers
IPL_DEPTH_32S - signed 32-bit integers
IPL_DEPTH_32F - single precision floating-point numbers
IPL_DEPTH_64F - double precision floating-point numbers
channels
Number of channels per element(pixel). Can be 1, 2, 3 or 4. The channels are interleaved, for example the usual data layout of a color image is:
b0 g0 r0 b1 g1 r1 ...
Although in general IPL image format can store non-interleaved images as well and some of OpenCV can process it, this function can create interleaved images only.

The function cvCreateImage creates the header and allocates data. This call is a shortened form of

    header = cvCreateImageHeader(size,depth,channels);
    cvCreateData(header);


CreateImageHeader

Allocates, initializes, and returns structure IplImage

IplImage* cvCreateImageHeader( CvSize size, int depth, int channels );

size
Image width and height.
depth
Image depth (see CreateImage).
channels
Number of channels (see CreateImage).

The function cvCreateImageHeader allocates, initializes, and returns the structure IplImage. This call is an analogue of

  iplCreateImageHeader( channels, 0, depth,
                        channels == 1 ? "GRAY" : "RGB",
                        channels == 1 ? "GRAY" : channels == 3 ? "BGR" :
                        channels == 4 ? "BGRA" : "",
                        IPL_DATA_ORDER_PIXEL, IPL_ORIGIN_TL, 4,
                        size.width, size.height,
                        0,0,0,0);
though it does not use IPL functions by default (see also CV_TURN_ON_IPL_COMPATIBILITY macro)


ReleaseImageHeader

Releases header

void cvReleaseImageHeader( IplImage** image );

image
Double pointer to the deallocated header.

The function cvReleaseImageHeader releases the header. This call is an analogue of

    if( image )
    {
        iplDeallocate( *image, IPL_IMAGE_HEADER | IPL_IMAGE_ROI );
        *image = 0;
    }
though it does not use IPL functions by default (see also CV_TURN_ON_IPL_COMPATIBILITY)


ReleaseImage

Releases header and image data

void cvReleaseImage( IplImage** image );

image
Double pointer to the header of the deallocated image.

The function cvReleaseImage releases the header and the image data. This call is a shortened form of

    if( *image )
    {
        cvReleaseData( *image );
        cvReleaseImageHeader( image );
    }


InitImageHeader

Initializes allocated by user image header

void cvInitImageHeader( IplImage* image, CvSize size, int depth,
                        int channels, int origin, int align );

image
Image header to initialize.
size
Image width and height.
depth
Image depth (see CreateImage).
channels
Number of channels (see CreateImage).
origin
IPL_ORIGIN_TL or IPL_ORIGIN_BL.
align
Alignment for image rows, typically 4 or 8 bytes.

The function cvInitImageHeader initializes the image header structure without memory allocation.


CloneImage

Makes a full copy of image

IplImage* cvCloneImage( const IplImage* image );

image
Original image.

The function cvCloneImage makes a full copy of the image including header, ROI and data


SetImageCOI

Sets channel of interest to given value

void cvSetImageCOI( IplImage* image, int coi );

image
Image header.
coi
Channel of interest.

The function cvSetImageCOI sets the channel of interest to a given value. Value 0 means that all channels are selected, 1 means that the first channel is selected etc. If ROI is NULL and coi != 0, ROI is allocated. Note that most of OpenCV functions do not support COI, so to process separate image/matrix channel one may copy (via cvCopy or cvCvtPixToPlane) the channel to separate image/matrix, process it and copy the result back (via cvCopy or cvCvtPlaneToPix) if need.


GetImageCOI

Returns index of channel of interest

int cvGetImageCOI( const IplImage* image );

image
Image header.

The function cvGetImageCOI returns channel of interest of the image (it returns 0 if all the channels are selected).


SetImageROI

Sets image ROI to given rectangle

void cvSetImageROI( IplImage* image, CvRect rect );

image
Image header.
rect
ROI rectangle.

The function cvSetImageROI sets the image ROI to a given rectangle. If ROI is NULL and the value of the parameter rect is not equal to the whole image, ROI is allocated. Unlike COI, most of OpenCV functions do support ROI and treat it in a way as it would be a separate image (for example, all the pixel coordinates are counted from top-left or bottom-left (depending on the image origin) corner of ROI)


ResetImageROI

Releases image ROI

void cvResetImageROI( IplImage* image, CvRect rect );

image
Image header.
rect
ROI rectangle.

The function cvResetImageROI releases image ROI. After that the whole image is considered selected. The similar result can be achieved by

cvSetImageROI( image, cvRect( 0, 0, image->width, image->height ));
cvSetImageCOI( image, 0 );

But the latter variant does not deallocate image->roi.


GetImageROI

Returns image ROI coordinates

CvRect cvGetImageROI( const IplImage* image );

image
Image header.

The function cvGetImageROI returns image ROI coordinates. The rectangle cvRect(0,0,image->width,image->height) is returned if there is no ROI


CreateMat

Creates new matrix

CvMat* cvCreateMat( int rows, int cols, int type );

rows
Number of rows in the matrix.
cols
Number of columns in the matrix.
type
Type of the matrix elements. Usually it is specified in form CV_<bit_depth>(S|U|F)C<number_of_channels>, for example:
CV_8UC1 means an 8-bit unsigned single-channel matrix, CV_32SC2 means a 32-bit signed matrix with two channels.

The function cvCreateMat allocates header for the new matrix and underlying data, and returns a pointer to the created matrix. It is a short form for:

    CvMat* mat = cvCreateMatHeader( rows, cols, type );
    cvCreateData( mat );

Matrices are stored row by row. All the rows are aligned by 4 bytes.


CreateMatHeader

Creates new matrix header

CvMat* cvCreateMatHeader( int rows, int cols, int type );

rows
Number of rows in the matrix.
cols
Number of columns in the matrix.
type
Type of the matrix elements (see cvCreateMat).

The function cvCreateMatHeader allocates new matrix header and returns pointer to it. The matrix data can further be allocated using cvCreateData or set explicitly to user-allocated data via cvSetData.


ReleaseMat

Deallocates matrix

void cvReleaseMat( CvMat** mat );

mat
Double pointer to the matrix.

The function cvReleaseMat decrements the matrix data reference counter and releases matrix header:

    if( *mat )
        cvDecRefData( *mat );
    cvFree( (void**)mat );


InitMatHeader

Initializes matrix header

void cvInitMatHeader( CvMat* mat, int rows, int cols, int type,
                      void* data=0, int step=CV_AUTOSTEP );

mat
Pointer to the matrix header to be initialized.
rows
Number of rows in the matrix.
cols
Number of columns in the matrix.
type
Type of the matrix elements.
data
Optional data pointer assigned to the matrix header.
step
Full row width in bytes of the data assigned. By default, the minimal possible step is used, i.e., no gaps is assumed between subsequent rows of the matrix.

The function cvInitMatHeader initializes already allocated CvMat structure. It can be used to process raw data with OpenCV matrix functions.

For example, the following code computes matrix product of two matrices, stored as ordinary arrays.

Calculating Product of Two Matrices

   double a[] = { 1, 2, 3, 4
                  5, 6, 7, 8,
                  9, 10, 11, 12 };

   double b[] = { 1, 5, 9,
                  2, 6, 10,
                  3, 7, 11,
                  4, 8, 12 };

   double c[9];
   CvMat Ma, Mb, Mc ;

   cvInitMatHeader( &Ma, 3, 4, CV_64FC1, a );
   cvInitMatHeader( &Mb, 4, 3, CV_64FC1, b );
   cvInitMatHeader( &Mc, 3, 3, CV_64FC1, c );

   cvMatMulAdd( &Ma, &Mb, 0, &Mc );
   // c array now contains product of a(3x4) and b(4x3) matrices


Mat

Initializes matrix header (light-weight variant)

CvMat cvMat( int rows, int cols, int type, void* data = 0 );

rows
Number of rows in the matrix.
cols
Number of columns in the matrix.
type
Type of the matrix elements (see CreateMat).
data
Optional data pointer assigned to the matrix header.

The function cvMat is a fast inline substitution for cvInitMatHeader. Namely, it is equivalent to:

     CvMat mat;
     cvInitMatHeader( &mat, rows, cols, type, data, CV_AUTOSTEP );


CloneMat

Creates matrix copy

CvMat* cvCloneMat( const CvMat* mat );

mat
Input matrix.

The function cvCloneMat creates a copy of input matrix and returns the pointer to it.


CreateMatND

Creates multi-dimensional dense array

CvMatND* cvCreateMatND( int dims, int* size, int type );

dims
Number of array dimensions. It must not exceed CV_MAX_DIM (=16 by default, though it may be changed at build time)
size
Array of dimension sizes.
type
Type of array elements. The same as for CvMat

The function cvCreateMatND allocates header for multi-dimensional dense array and the underlying data, and returns pointer to the created array. It is a short form for:

    CvMatND* mat = cvCreateMatNDHeader( dims, size, type );
    cvCreateData( mat );

Array data is stored row by row. All the rows are aligned by 4 bytes.


CreateMatNDHeader

Creates new matrix header

CvMatND* cvCreateMatNDHeader( int dims, int* size, int type );

dims
Number of array dimensions.
size
Array of dimension sizes.
type
Type of array elements. The same as for CvMat

The function cvCreateMatND allocates header for multi-dimensional dense array. The array data can further be allocated using cvCreateData or set explicitly to user-allocated data via cvSetData.


ReleaseMatND

Deallocates multi-dimensional array

void cvReleaseMatND( CvMatND** mat );

mat
Double pointer to the array.

The function cvReleaseMatND decrements the array data reference counter and releases the array header:

    if( *mat )
        cvDecRefData( *mat );
    cvFree( (void**)mat );


InitMatNDHeader

Initializes multi-dimensional array header

void cvInitMatNDHeader( CvMatND* mat, int dims, int* size, int type, void* data=0 );

mat
Pointer to the array header to be initialized.
rows
Number of rows in the matrix.
cols
Number of columns in the matrix.
type
Type of the matrix elements.
data
Optional data pointer assigned to the matrix header.

The function cvInitMatNDHeader initializes already allocated CvMatND structure.


CloneMatND

Creates full copy of multi-dimensional array

CvMatND* cvCloneMatND( const CvMatND* mat );

mat
Input array.

The function cvCloneMatND creates a copy of input array and returns pointer to it.


DecRefData

Decrements array data reference counter

void cvDecRefData( CvArr* array );

array
array header.

The function cvDecRefData decrements CvMat or CvMatND data reference counter if the reference counter pointer is not NULL and deallocates the data if the counter reaches zero. In the current implementation the reference counter is not NULL only if the data was allocated using cvCreateData function, in other cases such as:
external data was assigned to the header using cvSetData
the matrix header presents a part of a larger matrix or image
the matrix header was converted from image or n-dimensional matrix header

the reference counter is set to NULL and thus it is not decremented. Whenever the data is deallocated or not, the data pointer and reference counter pointers are cleared by the function.


IncRefData

Increments array data reference counter

int cvIncRefData( CvArr* array );

array
array header.

The function cvIncRefData increments CvMat or CvMatND data reference counter and returns the new counter value if the reference counter pointer is not NULL, otherwise it returns zero.


CreateData

Allocates array data

void cvCreateData( CvArr* array );

array
Array header.

The function cvCreateData allocates image, matrix or multi-dimensional array data. Note that in case of matrix types OpenCV allocation functions are used and in case of IplImage they are used too unless CV_TURN_ON_IPL_COMPATIBILITY was called. In the latter case IPL functions are used to allocate the data


ReleaseData

Releases array data

void cvReleaseData( CvArr* array );

array
Array header

The function cvReleaseData releases the array data. In case of CvMat or CvMatND it simply calls cvDecRefData(), that is the function can not deallocate external data. See also the note to cvCreateData.


SetData

Assigns user data to the array header

void cvSetData( CvArr* array, void* data, int step );

array
Array header.
data
User data.
step
Full row length in bytes.

The function cvSetData assigns user data to the array header. Header should be initialized before using cvCreate*Header, cvInit*Header or cvMat (in case of matrix) function.


GetRawData

Retrieves low-level information about the array

void cvGetRawData( const CvArr* array, uchar** data,
                   int* step, CvSize* roiSize );

array
Array header.
data
Output pointer to the whole image origin or ROI origin if ROI is set.
step
Output full row length in bytes.
roiSize
Output ROI size.

The function cvGetRawData fills output variables with low-level information about the array data. All output parameters are optional, so some of the pointers may be set to NULL. If the array is IplImage with ROI set, parameters of ROI are returned.

The following example shows how to get access to array elements using this function.

Using GetRawData to calculate absolute value of elements of a single-channel floating-point array.

    float* data;
    int step;

    CvSize size;
    int x, y;

    cvGetRawData( array, (uchar**)&data, &step, &size );
    step /= sizeof(data[0]);

    for( y = 0; y < size.height; y++, data += step )
        for( x = 0; x < size.width; x++ )
            data[x] = (float)fabs(data[x]);


GetMat

Returns matrix header for arbitrary array

CvMat* cvGetMat( const CvArr* arr, CvMat* mat, int* coi = 0, int allowND );

arr
Input array.
mat
Pointer to CvMat structure used as a temporary buffer.
coi
Optional output parameter for storing COI.
allowND
If non-zero, the function accepts multi-dimensional dense arrays (CvMatND*) and returns 2D (if CvMatND has two dimensions) or 1D matrix (when CvMatND has 1 dimension or more than 2 dimensions). The array must be continuous.

The function cvGetMat returns matrix header for the input array that can be matrix - CvMat*, image - IplImage* or multi-dimensional dense array - CvMatND* (latter case is allowed only if allowND != 0) . In the case of matrix the function simply returns the input pointer. In the case of IplImage* or CvMatND* it initializes mat structure with parameters of the current image ROI and returns pointer to this temporary structure. Because COI is not supported by CvMat, it is returned separately.

The function provides an easy way to handle both types of array - IplImage and CvMat -, using the same code. Reverse transform from CvMat to IplImage can be done using cvGetImage function.

Input array must have underlying data allocated or attached, otherwise the function fails.

If the input array is IplImage with planar data layout and COI set, the function returns pointer to the selected plane and COI = 0. It enables per-plane processing of multi-channel images with planar data layout using OpenCV functions.


GetImage

Returns image header for arbitrary array

IplImage* cvGetImage( const CvArr* arr, IplImage* image_header );

arr
Input array.
image_header
Pointer to IplImage structure used as a temporary buffer.

The function cvGetImage returns image header for the input array that can be matrix - CvMat*, or image - IplImage*. In the case of image the function simply returns the input pointer. In the case of CvMat* it initializes image_header structure with parameters of the input matrix. Note that if we transform IplImage to CvMat and then transform CvMat back to IplImage, we can get different headers if the ROI is set, and thus some IPL functions that calculate image stride from its width and align may fail on the resultant image.


GetSubRect

Returns matrix header corresponding to the rectangular sub-array of input image or matrix

CvMat* cvGetSubRect( const CvArr* array, CvMat* subarr, CvRect rect );

array
Input array.
subarr
Pointer to the resultant subarray header.
rect
Zero-based coordinates of the rectangle of interest.

The function cvGetSubRect returns header, corresponding to a specified rectangle of the input array. In other words, it allows the user to treat a rectangular part of input array as a stand-alone array. ROI is taken into account by the function so the sub-array of ROI is really extracted.


GetRow, GetRows

Returns array row or row span

CvMat* cvGetRow( const CvArr* arr, CvMat* subarr, int row );
CvMat* cvGetRows( const CvArr* arr, CvMat* subarr, int start_row, end_row );

arr
Input array.
subarr
Pointer to the resulting sub-array header.
row
Zero-based index of the selected row.
start_row
Zero-based index of the starting row (inclusive) of the span.
end_row
Zero-based index of the ending row (exclusive) of the span.

The functions GetRow and GetRows return the header, corresponding to a specified row/row span of the input array. Note that GetRow is a shortcut for cvGetRows:

cvGetRow( arr, subarr, row ); // ~ cvGetRows( arr, subarr, row, row + 1 );


GetCol, GetCols

Returns array column or column span

CvMat* cvGetCol( const CvArr* arr, CvMat* subarr, int col );
CvMat* cvGetCols( const CvArr* arr, CvMat* subarr, int start_col, end_col );

arr
Input array.
subarr
Pointer to the resulting sub-array header.
col
Zero-based index of the selected column.
start_col
Zero-based index of the starting column (inclusive) of the span.
end_col
Zero-based index of the ending column (exclusive) of the span.

The functions GetCol and GetCols return the header, corresponding to a specified column/column span of the input array. Note that GetCol is a shortcut for cvGetCols:

cvGetCol( arr, subarr, col ); // ~ cvGetCols( arr, subarr, col, col + 1 );


GetDiag

Returns one of array diagonals

CvMat* cvGetDiag( const CvArr* arr, CvMat* subarr, int diag=0 );

arr
Input array.
subarr
Pointer to the resulting sub-array header.
diag
Array diagonal. Zero corresponds to the main diagonal, -1 corresponds to the diagonal above the main etc., 1 corresponds to the diagonal below the main etc.

The function cvGetDiag returns the header, corresponding to a specified diagonal of the input array.


GetSize

Returns size of matrix or image ROI

CvSize cvGetSize( const CvArr* arr );

arr
array header.

The function cvGetSize returns number of rows (CvSize::height) and number of columns (CvSize::width) of the input matrix or image. In case of image the size of ROI is returned.


CreateSparseMat

Creates sparse array

CvSparseMat* cvCreateSparseMat( int dims, int* size, int type );

dims
Number of array dimensions. It must not exceed CV_MAX_DIM (=16 by default, though it may be changed at build time)
size
Array of dimension sizes.
type
Type of array elements. The same as for CvMat

The function cvCreateSparseMat allocates multi-dimensional sparse array. Initially the array contain no elements, that is cvGet*D will return zero for every index


ReleaseSparseMat

Deallocates sparse array

void cvReleaseSparseMat( CvSparseMat** mat );

mat
Double pointer to the array.

The function cvReleaseSparseMat releases the sparse array and clears the array pointer upon exit


CloneSparseMat

Creates full copy of sparse array

CvSparseMat* cvCloneSparseMat( const CvSparseMat* mat );

mat
Input array.

The function cvCloneSparseMat creates a copy of the input array and returns pointer to the copy.


InitSparseMatIterator

Initializes sparse array elements iterator

CvSparseMat* cvInitSparseMatIterator( const CvSparseMat* mat, CvSparseMatIterator* matIterator );

mat
Input array.
matIterator
Initialized iterator.

The function cvInitSparseMatIterator initializes iterator of sparse array elements and returns pointer to the first element, or NULL if the array is empty.


GetNextSparseNode

Initializes sparse array elements iterator

CvSparseMat* cvGetNextSparseNode( CvSparseMatIterator* matIterator );

matIterator
Sparse array iterator.

The function cvGetNextSparseNode moves iterator to the next sparse matrix element and returns pointer to it. In the current version there is no any particular order of the elements, because they are stored in hash table. The sample below demonstrates how to iterate through the sparse matrix:

Using cvInitSparseMatIterator and cvGetNextSparseNode to calculate sum of floating-point sparse array.

    double sum;
    int i, dims = cvGetDims( array );
    CvSparseMatIterator matIterator;
    CvSparseNode* node = cvInitSparseMatIterator( array, &matIterator );

    for( ; node != 0; node = cvGetNextSparseNode( &matIterator ))
    {
        int* idx = CV_NODE_IDX( array, node ); /* get pointer to the element indices */
        float val = (float*)CV_NODE_VAL( array, node ); /* get value of the element
                                                          (assume that the type is CV_32FC1) */
        printf( "(" );
        for( i = 0; i < dims; i++ )
            printf( "%4d%s", idx[i], i < dims - 1 "," : "): " );
        printf( "%g\n", val );

        sum += val;
    }

    printf( "\nTotal sum = %g\n", sum );


GetElemType

Returns type of array elements

int cvGetElemType( const CvArr* arr );

arr
Input array.

The functions GetElemType returns type of the array elements as it is described in cvCreateMat discussion:

CV_8UC1 ... CV_64FC4


GetDims, GetDimSize

Return number of array dimensions and their sizes or the size of particular dimension

int cvGetDims( const CvArr* arr, int* size=0 );
int cvGetDimSize( const CvArr* arr, int index );

arr
Input array.
size
Optional output vector of the array dimension sizes. For 2d arrays the number of rows (height) goes first, number of columns (width) next.
index
Zero-based dimension index (for matrices 0 means number of rows, 1 means number of columns; for images 0 means height, 1 means width).

The function cvGetDims returns number of array dimensions and their sizes. In case of IplImage or CvMat it always returns 2 regardless of number of image/matrix rows. The function cvGetDimSize returns the particular dimension size (number of elements per that dimension). For example, the following code calculates total number of array elements:


// via cvGetDims()
int size[CV_MAX_DIM];
int i, total = 1;
int dims = cvGetDims( arr, size );
for( i = 0; i < dims; i++ )
    total *= size[i];

// via cvGetDims() and cvGetDimSize()
int i, total = 1;
int dims = cvGetDims( arr );
for( i = 0; i < dims; i++ )
    total *= cvGetDimsSize( arr, i );


Ptr*D

Return pointer to the particular array element

uchar* cvPtr1D( const CvArr* arr, int idx0, int* type=0 );
uchar* cvPtr2D( const CvArr* arr, int idx0, int idx1, int* type=0 );
uchar* cvPtr3D( const CvArr* arr, int idx0, int idx1, int idx2, int* type=0 );
uchar* cvPtrND( const CvArr* arr, int* idx, int* type=0 );

arr
Input array.
idx0
The first zero-based component of the element index
idx1
The second zero-based component of the element index
idx2
The third zero-based component of the element index
idx
Array of the element indices
type
Optional output parameter: type of matrix elements

The functions cvPtr*D return pointer to the particular array element. Number of array dimension should match to the number of indices passed to the function except for cvPtr1D function that can be used for sequential access to 1D, 2D or nD dense arrays.

The functions can be used for sparse arrays as well - if the requested node does not exist they create it and set it to zero.

All these as well as other functions accessing array elements (cvGet[Real]*D, cvSet[Real]*D) raise an error in case if the element index is out of range.


Get*D

Return the particular array element

CvScalar cvGet1D( const CvArr* arr, int idx0 );
CvScalar cvGet2D( const CvArr* arr, int idx0, int idx1 );
CvScalar cvGet3D( const CvArr* arr, int idx0, int idx1, int idx2 );
CvScalar cvGetND( const CvArr* arr, int* idx );

arr
Input array.
idx0
The first zero-based component of the element index
idx1
The second zero-based component of the element index
idx2
The third zero-based component of the element index
idx
Array of the element indices

The functions cvGet*D return the particular array element. In case of sparse array the functions return 0 if the requested node does not exist (no new node is created by the functions)


GetReal*D

Return the particular element of single-channel array

double cvGetReal1D( const CvArr* arr, int idx0 );
double cvGetReal2D( const CvArr* arr, int idx0, int idx1 );
double cvGetReal3D( const CvArr* arr, int idx0, int idx1, int idx2 );
double cvGetRealND( const CvArr* arr, int* idx );

arr
Input array. Must have a single channel.
idx0
The first zero-based component of the element index
idx1
The second zero-based component of the element index
idx2
The third zero-based component of the element index
idx
Array of the element indices

The functions cvGetReal*D return the particular element of single-channel array. If the array has multiple channels, runtime error is raised. Note that cvGet*D function can be used safely for both single-channel and multiple-channel arrays though they are a bit slower.

In case of sparse array the functions return 0 if the requested node does not exist (no new node is created by the functions)


mGet

Return the particular element of single-channel floating-point matrix

double cvmGet( const CvMat* mat, int row, int col );

mat
Input matrix.
row
The zero-based index of row.
col
The zero-based index of column.

The function cvmGet is a fast replacement for cvGetReal2D in case of single-channel floating-point matrices. It is faster because it is inline, it does less checks for array type and array element type and it checks for the row and column ranges only in debug mode.


Set*D

Change the particular array element

void cvSet1D( CvArr* arr, int idx0, CvScalar new_value );
void cvSet2D( CvArr* arr, int idx0, int idx1, CvScalar new_value );
void cvSet3D( CvArr* arr, int idx0, int idx1, int idx2, CvScalar new_value );
void cvSetND( CvArr* arr, int* idx, CvScalar new_value );

arr
Input array.
idx0
The first zero-based component of the element index
idx1
The second zero-based component of the element index
idx2
The third zero-based component of the element index
idx
Array of the element indices
new_value
The assigned value

The functions cvSet*D assign the new value to the particular element of array. In case of sparse array the functions create the node if it does not exist yet


SetReal*D

Change the particular array element

void cvSetReal1D( CvArr* arr, int idx0, double new_value );
void cvSetReal2D( CvArr* arr, int idx0, int idx1, double new_value );
void cvSetReal3D( CvArr* arr, int idx0, int idx1, int idx2, double new_value );
void cvSetRealND( CvArr* arr, int* idx, double new_value );

arr
Input array.
idx0
The first zero-based component of the element index
idx1
The second zero-based component of the element index
idx2
The third zero-based component of the element index
idx
Array of the element indices
new_value
The assigned value

The functions cvSetReal*D assign the new value to the particular element of single-channel array. If the array has multiple channels, runtime error is raised. Note that cvSet*D function can be used safely for both single-channel and multiple-channel arrays though they are a bit slower.

In case of sparse array the functions create the node if it does not exist yet


mSet

Return the particular element of single-channel floating-point matrix

void cvmSet( CvMat* mat, int row, int col, double value );

mat
The matrix.
row
The zero-based index of row.
col
The zero-based index of column.
value
The new value of the matrix element

The function cvmSet is a fast replacement for cvSetReal2D in case of single-channel floating-point matrices. It is faster because it is inline, it does less checks for array type and array element type and it checks for the row and column ranges only in debug mode.


Clear*D

Clears the particular array element

void cvClearND( CvArr* arr, int* idx );

arr
Input array.
idx
Array of the element indices

The function cvClearND clears (sets to zero) the particular element of dense array or deletes the element of sparse array. If the element does not exists, the function does nothing.


Copy

Copies one array to another

void cvCopy( const CvArr* A, CvArr* B, const CvArr* mask =0);

A
The source array.
B
The destination array.
mask
Operation mask, 8-bit single channel array; specifies elements of destination array to be changed.

The function cvCopy copies selected elements from input array to output array:

B(I)=A(I) if mask(I)!=0.

If any of the passed arrays is of IplImage type, then its ROI and COI fields are used. Both arrays must have the same type, the same number of dimensions and the same size. The function can also copy sparse arrays (mask is not supported in this case).


Set

Sets every element of array to given value

void cvSet( CvArr* A, CvScalar S, const CvArr* mask=0 );

A
The destination array.
S
Fill value.
mask
Operation mask, 8-bit single channel array; specifies elements of destination array to be changed.

The function cvSet copies scalar S to every selected element of the destination array:

A(I)=S if mask(I)!=0

If array A is of IplImage type, then is ROI used, but COI must not be set.


SetZero

Clears the array

void cvSetZero( CvArr* arr );
#define cvZero cvSetZero

arr
array to be cleared.

The function cvSetZero clears the array. In case of dense arrays (CvMat, CvMatND or IplImage) cvZero(array) is equivalent to cvSet(array,cvScalarAll(0),0), but the function can clear sparse arrays by removing all the array elements


Arrays: Conversions, transformations, basic operations


Reshape

Changes shape of matrix/image without copying data

CvMat* cvReshape( const CvArr* array, CvMat* header, int new_cn, int new_rows=0 );

array
Input array.
header
Output header to be filled.
new_cn
New number of channels. new_cn = 0 means that number of channels remains unchanged.
new_rows
New number of rows. new_rows = 0 means that number of rows remains unchanged unless it needs to be changed according to new_cn value. destination array to be changed.

The function cvReshape initializes CvMat header so that it points to the same data as the original array but has different shape - different number of channels, different number of rows or both.

For example, the following code creates one image buffer and two image headers, first is for 320x240x3 image and the second is for 960x240x1 image:

IplImage* color_img = cvCreateImage( cvSize(320,240), IPL_DEPTH_8U, 3 );
CvMat gray_mat_hdr;
IplImage gray_img_hdr, *gray_img;
cvReshape( color_img, &gray_mat_hdr, 1 );
gray_img = cvGetImage( &gray_mat_hdr, &gray_img_hdr );

And the next example converts 3x3 matrix to a single 1x9 vector

CvMat* mat = cvCreateMat( 3, 3, CV_32F );
CvMat row_header, *row;
row = cvReshape( mat, &row_header, 0, 1 );

ReshapeMatND

Changes shape of multi-dimensional array w/o copying data

CvArr* cvReshapeMatND( const CvArr* array,
                       int sizeof_header, CvArr* header,
                       int new_cn, int new_dims, int* new_sizes );

#define cvReshapeND( arr, header, new_cn, new_dims, new_sizes )   \
      cvReshapeMatND( (arr), sizeof(*(header)), (header),         \
                      (new_cn), (new_dims), (new_sizes))

array
Input array.
sizeof_header
Size of output header to distinguish between IplImage, CvMat and CvMatND output headers.
header
Output header to be filled.
new_cn
New number of channels. new_cn = 0 means that number of channels remains unchanged.
new_dims
New number of dimensions. new_dims = 0 means that number of dimensions remains the same.
new_sizes
Array of new dimension sizes. Only new_dims-1 values are used, because the total number of elements must remain the same. Thus, if new_dims = 1, new_sizes array is not used

The function cvReshapeMatND is an advanced version of cvReshape that can work with multi-dimensional arrays as well (though, it can work with ordinary images and matrices) and change the number of dimensions. Below are the two samples from the cvReshape description rewritten using cvReshapeMatND:

IplImage* color_img = cvCreateImage( cvSize(320,240), IPL_DEPTH_8U, 3 );
IplImage gray_img_hdr, *gray_img;
gray_img = (IplImage*)cvReshapeND( color_img, &gray_img_hdr, 1, 0, 0 );

...

/* second example is modified to convert 2x2x2 array to 8x1 vector */
int size[] = { 2, 2, 2 };
CvMatND* mat = cvCreateMatND( 3, size, CV_32F );
CvMat row_header, *row;
row = cvReshapeND( mat, &row_header, 0, 1, 0 );

Repeat

Fill destination array with tiled source array

void cvRepeat( const CvArr* A, CvArr* B );

A
Source array, image or matrix.
B
Destination array, image or matrix.

The function cvRepeat fills the destination array with source array tiled:

B(i,j)=A(i%rows(A), j%cols(A))

where "%" means "modulo" operation. So the destination array may be as larger as well as smaller than the source array.


Flip

Flip a 2D array around vertical, horizontall or both axises

void  cvFlip( const CvArr* A, CvArr* B=0, int flip_mode=0);
#define cvMirror cvFlip

A
Source array.
B
Destination array. If dst = NULL the flipping is done inplace.
flip_mode
Specifies how to flip the array.
flip_mode = 0 means flipping around x-axis, flip_mode > 0 (e.g. 1) means flipping around y-axis and flip_mode < 0 (e.g. -1) means flipping around both axises. See also the discussion below for the formulas

The function cvFlip flips the array in one of different 3 ways (row and column indices are 0-based):

B(i,j)=A(rows(A)-i-1,j) if flip_mode = 0
B(i,j)=A(i,cols(A)-j-1) if flip_mode > 0
B(i,j)=A(rows(A)-i-1,cols(A)-j-1) if flip_mode < 0

The typical scenaria of the function use are:


CvtPixToPlane

Divides multi-channel array into several single-channel arrays or extracts a single channel from the array

void cvCvtPixToPlane( const CvArr* src, CvArr* dst0, CvArr* dst1,
                      CvArr* dst2, CvArr* dst3 );

src
Source array.
dst0...dst3
Destination channels.

The function cvCvtPixToPlane divides a multi-channel array into separate single-channel arrays. Two modes are available for the operation. If the source array has N channels then if the first N destination channels are not NULL, all they are extracted from the source array, otherwise if only a single destination channel of the first N is not NULL, this particular channel is extracted, otherwise an error is raised. Rest of destination channels (beyond the first N) must always be NULL. For IplImage cvCopy with COI set can be also used to extract a single channel from the image.


CvtPlaneToPix

Composes multi-channel array from several single-channel arrays or inserts a single channel into the array

void cvCvtPlaneToPix( const CvArr* src0, const CvArr* src1,
                      const CvArr* src2, const CvArr* src3, CvArr* dst );

src0... src3
Input channels.
dst
Destination array.

The function cvCvtPlaneToPix is the opposite to the previous. If the destination array has N channels then if the first N input channels are not NULL, all they are copied to the destination array, otherwise if only a single source channel of the first N is not NULL, this particular channel is copied into the destination array, otherwise an error is raised. Rest of source channels (beyond the first N) must always be NULL. For IplImage cvCopy with COI set can be also used to insert a single channel into the image.


ConvertScale

Converts one array to another with optional linear transformation

void cvConvertScale( const CvArr* A, CvArr* B, double scale=1, double shift=0 );

#define cvCvtScale cvConvertScale
#define cvScale  cvConvertScale
#define cvConvert( A, B )  cvConvertScale( (A), (B), 1, 0 )

A
Source array.
B
Destination array.
scale
Scale factor.
shift
Value added to the scaled source array elements.

The function cvConvertScale has several different purposes and thus has several synonyms. It copies one array to another with optional scaling, which is performed first, and/or optional type conversion, performed after:

B(I)=A(I)*scale + (shift,shift,...)

All the channels of multi-channel arrays are processed independently.

The type conversion is done with rounding and saturation, that is if a result of scaling + conversion can not be represented exactly by a value of destination array element type, it is set to the nearest representable value on the real axis.

In case of scale=1, shift=0 no prescaling is done. This is a specially optimized case and it has the appropriate cvConvert synonym. If source and destination array types have equal types, this is also a special case that can be used to scale and shift a matrix or an image and that fits to cvScale synonym.


ConvertScaleAbs

Converts input array elements to 8-bit unsigned integer another with optional linear transformation

void cvConvertScaleAbs( const CvArr* A, CvArr* B, double scale=1, double shift=0 );
#define cvCvtScaleAbs cvConvertScaleAbs

A
Source array.
B
Destination array (should have 8u depth).
scale
ScaleAbs factor.
shift
Value added to the scaled source array elements.

The function cvConvertScaleAbs is similar to the previous one, but it stores absolute values of the conversion results:

B(I)=abs(A(I)*scale + (shift,shift,...))

The function supports only destination arrays of 8u (8-bit unsigned integers) type, for other types the function can be emulated by combination of cvConvertScale and cvAbs functions.


Add

Computes per-element sum of two arrays

void cvAdd( const CvArr* A, const CvArr* B, CvArr* C, const CvArr* mask=0);

A
The first source array.
B
The second source array.
C
The destination array.
mask
Operation mask, 8-bit single channel array; specifies elements of destination array to be changed.

The function cvAdd adds one array to another one:

C(I)=A(I)+B(I) if mask(I)!=0

All the arrays must have the same type, except the mask, and the same size (or ROI size)


AddS

Computes sum of array and scalar

void cvAddS( const CvArr* A, CvScalar S, CvArr* C, const CvArr* mask=0 );

A
The source array.
S
Added scalar.
C
The destination array.
mask
Operation mask, 8-bit single channel array; specifies elements of destination array to be changed.

The function cvAddS adds scalar S to every element in the source array A and stores the result in C

C(I)=A(I)+S if mask(I)!=0

All the arrays must have the same type, except the mask, and the same size (or ROI size)


Sub

Computes per-element difference of two arrays

void cvSub( const CvArr* A, const CvArr* B, CvArr* C, const CvArr* mask=0);

A
The first source array.
B
The second source array.
C
The destination array.
mask
Operation mask, 8-bit single channel array; specifies elements of destination array to be changed.

The function cvSub subtracts one array from another one:

C(I)=A(I)-B(I) if mask(I)!=0

All the arrays must have the same type, except the mask, and the same size (or ROI size)


SubS

Computes difference of array and scalar

void cvSubS( const CvArr* A, CvScalar S, CvArr* C, const CvArr* mask=0 );

A
The source array.
S
Subed scalar.
C
The destination array.
mask
Operation mask, 8-bit single channel array; specifies elements of destination array to be changed.

The function cvSubS subtracts a scalar from every element of the source array:

C(I)=A(I)+S if mask(I)!=0

All the arrays must have the same type, except the mask, and the same size (or ROI size)


SubRS

Computes difference of scalar and array

void cvSubRS( const CvArr* A, CvScalar S, CvArr* C, const CvArr* mask=0 );

A
The first source array.
S
Scalar to subtract from.
C
The destination array.
mask
Operation mask, 8-bit single channel array; specifies elements of destination array to be changed.

The function cvSubRS subtracts every element of source array from a scalar:

C(I)=S-A(I) if mask(I)!=0

All the arrays must have the same type, except the mask, and the same size (or ROI size)


Mul

Calculates per-element product of two arrays

void cvMul( const CvArr* A, const CvArr* B, CvArr* C, double scale=1 );

A
The first source array.
B
The second source array.
C
The destination array.
scale
Optional scale factor

The function cvMul calculates per-element product of two arrays:

C(I)=scale•A(I)•B(I)

All the arrays must have the same type, and the same size (or ROI size)


Div

Performs per-element division of two arrays

void cvDiv( const CvArr* A, const CvArr* B, CvArr* C, double scale=1 );

A
The first source array. If the pointer is NULL, the array is assumed to be all 1's.
B
The second source array.
C
The destination array.
scale
Optional scale factor

The function cvDiv divides one array by another:

C(I)=scale•A(I)/B(I), if A!=NULL
C(I)=scale/B(I),      if A=NULL

All the arrays must have the same type, and the same size (or ROI size)


And

Calculates per-element bit-wise conjunction of two arrays

void cvAnd( const CvArr* A, const CvArr* B, CvArr* C, const CvArr* mask=0 );

A
The first source array.
B
The second source array.
C
The destination array.
mask
Operation mask, 8-bit single channel array; specifies elements of destination array to be changed.

The function cvAnd calculates per-element bit-wise logical conjunction of two arrays:

C(I)=A(I)&B(I) if mask(I)!=0

In the case of floating-point arrays their bit representations are used for the operation. All the arrays must have the same type, except the mask, and the same size


AndS

Calculates per-element bit-wise conjunction of array and scalar

void cvAndS( const CvArr* A, CvScalar S, CvArr* C, const CvArr* mask=0 );

A
The source array.
S
Scalar to use in the operation.
C
The destination array.
mask
Operation mask, 8-bit single channel array; specifies elements of destination array to be changed.

The function AndS calculates per-element bit-wise conjunction of array and scalar:

C(I)=A(I)&S if mask(I)!=0

Prior to the actual operation the scalar is converted to the same type as the arrays. In the case of floating-point arrays their bit representations are used for the operation. All the arrays must have the same type, except the mask, and the same size

The following sample demonstrates how to calculate absolute value of floating-point array elements by clearing the most-significant bit:

float a[] = { -1, 2, -3, 4, -5, 6, -7, 8, -9 };
CvMat A = cvMat( 3, 3, CV_32F, &a );
int i, abs_mask = 0x7fffffff;
cvAndS( &A, cvRealScalar(*(float*)&abs_mask), &A, 0 );
for( i = 0; i < 9; i++ )
    printf("%.1f ", a[i] );

The code should print:

1.0 2.0 3.0 4.0 5.0 6.0 7.0 8.0 9.0

Or

Calculates per-element bit-wise disjunction of two arrays

void cvOr( const CvArr* A, const CvArr* B, CvArr* C, const CvArr* mask=0 );

A
The first source array.
B
The second source array.
C
The destination array.
mask
Operation mask, 8-bit single channel array; specifies elements of destination array to be changed.

The function cvOr calculates per-element bit-wise disjunction of two arrays:

C(I)=A(I)|B(I)

In the case of floating-point arrays their bit representations are used for the operation. All the arrays must have the same type, except the mask, and the same size


OrS

Calculates per-element bit-wise disjunction of array and scalar

void cvOrS( const CvArr* A, CvScalar S, CvArr* C, const CvArr* mask=0 );

A
The source array.
S
Scalar to use in the operation.
C
The destination array.
mask
Operation mask, 8-bit single channel array; specifies elements of destination array to be changed.

The function OrS calculates per-element bit-wise disjunction of array and scalar:

C(I)=A(I)|S if mask(I)!=0

Prior to the actual operation the scalar is converted to the same type as the arrays. In the case of floating-point arrays their bit representations are used for the operation. All the arrays must have the same type, except the mask, and the same size


Xor

Performs per-element bit-wise "exclusive or" operation on two arrays

void cvXor( const CvArr* A, const CvArr* B, CvArr* C, const CvArr* mask=0 );

A
The first source array.
B
The second source array.
C
The destination array.
mask
Operation mask, 8-bit single channel array; specifies elements of destination array to be changed.

The function cvXor calculates per-element bit-wise logical conjunction of two arrays:

C(I)=A(I)^B(I) if mask(I)!=0

In the case of floating-point arrays their bit representations are used for the operation. All the arrays must have the same type, except the mask, and the same size


XorS

Performs per-element bit-wise "exclusive or" operation on array and scalar

void cvXorS( const CvArr* A, CvScalar S, CvArr* C, const CvArr* mask=0 );

A
The source array.
S
Scalar to use in the operation.
C
The destination array.
mask
Operation mask, 8-bit single channel array; specifies elements of destination array to be changed.

The function XorS calculates per-element bit-wise conjunction of array and scalar:

C(I)=A(I)^S if mask(I)!=0

Prior to the actual operation the scalar is converted to the same type as the arrays. In the case of floating-point arrays their bit representations are used for the operation. All the arrays must have the same type, except the mask, and the same size

The following sample demonstrates how to conjugate complex vector by switching the most-significant bit of imaging part:

float a[] = { 1, 0, 0, 1, -1, 0, 0, -1 }; /* 1, j, -1, -j */
CvMat A = cvMat( 4, 1, CV_32FC2, &a );
int i, neg_mask = 0x80000000;
cvXorS( &A, cvScalar( 0, *(float*)&neg_mask, 0, 0 ), &A, 0 );
for( i = 0; i < 4; i++ )
    printf("(%.1f, %.1f) ", a[i*2], a[i*2+1] );

The code should print:

(1.0,0.0) (0.0,-1.0) (-1.0,0.0) (0.0,1.0)

Not

Performs per-element bit-wise inversion of array elements

void cvNot( const CvArr* A, CvArr* C );

A
The source array.
C
The destination array.

The function Not inverses every bit of every array element:

C(I)=~A(I)

Cmp

Performs per-element comparison of two arrays

void cvCmp( const CvArr* A, const CvArr* B, CvArr* C, int cmp_op );

A
The first source array.
B
The second source array. Both source array must have a single channel.
C
The destination array, must have 8u or 8s type.
cmp_op
The flag specifying the relation between the elements to be checked:
CV_CMP_EQ - A(I) "equal to" B(I)
CV_CMP_GT - A(I) "greater than" B(I)
CV_CMP_GE - A(I) "greater or equal" B(I)
CV_CMP_LT - A(I) "less than" B(I)
CV_CMP_GE - A(I) "less or equal" B(I)
CV_CMP_NE - A(I) "not equal to" B(I)

The function cvCmp compares the corresponding elements of two arrays and fills the destination mask array:

C(I)=A(I) op B(I),

where op is '=', '>', '>=', '<', '<=' or '!='.

C(I) is set to 0xff (all '1'-bits) if the particular relation between the elements is true and 0 otherwise. All the arrays must have the same type, except the destination, and the same size (or ROI size)


CmpS

Performs per-element comparison of array and scalar

void cvCmpS( const CvArr* A, double S, CvArr* C, int cmp_op );

A
The source array, must have a single channel.
C
The destination array, must have 8u or 8s type.
cmp_op
The flag specifying the relation between the elements to be checked:
CV_CMP_EQ - A(I) "equal to" S
CV_CMP_GT - A(I) "greater than" S
CV_CMP_GE - A(I) "greater or equal" S
CV_CMP_LT - A(I) "less than" S
CV_CMP_GE - A(I) "less or equal" S
CV_CMP_NE - A(I) "not equal" S

The function cvCmpS compares the corresponding elements of array and scalar and fills the destination mask array:

C(I)=A(I) op S,

where op is '=', '>', '>=', '<', '<=' or '!='.

C(I) is set to 0xff (all '1'-bits) if the particular relation between the elements is true and 0 otherwise. All the arrays must have the same size (or ROI size)


InRange

Checks that array elements lie between elements of two other arrays

void cvInRange( const CvArr* A, const CvArr* L, const CvArr* U, CvArr* C );

A
The first source array.
L
The inclusive lower boundary array.
U
The exclusive upper boundary array.
C
The destination array, must have 8u or 8s type.

The function cvInRange does the range check for every element of the input array:

C(I)=L(I)0 <= A(I)0 < U(I)0

for single-channel arrays,

C(I)=L(I)0 <= A(I)0 < U(I)0 &&
     L(I)1 <= A(I)1 < U(I)1

for two-channel arrays etc.

C(I) is set to 0xff (all '1'-bits) if A(I) is within the range and 0 otherwise. All the arrays must have the same type, except the destination, and the same size (or ROI size)


InRangeS

Checks that array elements lie between two scalars

void cvInRangeS( const CvArr* A, CvScalar SL, CvScalar SU, CvArr* D );

A
The first source array.
SL
The inclusive lower boundary.
SU
The exclusive upper boundary.
C
The destination array, must have 8u or 8s type.

The function cvInRangeS does the range check for every element of the input array:

C(I)=SL0 <= A(I)0 < SU0

for a single-channel array,

C(I)=SL0 <= A(I)0 < SU0 &&
     SL1 <= A(I)1 < SU1

for a two-channel array etc.

C(I) is set to 0xff (all '1'-bits) if A(I) is within the range and 0 otherwise. All the arrays must have the same size (or ROI size)


Max

Finds per-element maximum of two arrays

void cvMax( const CvArr* A, const CvArr* B, CvArr* C );

A
The first source array.
B
The second source array.
C
The destination array.

The function cvMax calculates per-element maximum of two arrays:

C(I)=max(A(I), B(I))

All the arrays must have a single channel, the same data type and the same size (or ROI size).


MaxS

Finds per-element maximum of array and scalar

void cvMaxS( const CvArr* A, const CvArr* B, CvArr* C );

A
The first source array.
B
The second source array.
C
The destination array.

The function cvMaxS calculates per-element maximum of array and scalar:

C(I)=max(A(I), S)

All the arrays must have a single channel, the same data type and the same size (or ROI size).


Min

Finds per-element minimum of two arrays

void cvMin( const CvArr* A, const CvArr* B, CvArr* C );

A
The first source array.
B
The second source array.
C
The destination array.

The function cvMin calculates per-element minimum of two arrays:

C(I)=min(A(I),B(I))

All the arrays must have a single channel, the same data type and the same size (or ROI size).


MinS

Finds per-element minimum of array and scalar

void cvMinS( const CvArr* A, const CvArr* B, CvArr* C );

A
The first source array.
B
The second source array.
C
The destination array.

The function cvMinS calculates minimum of array and scalar:

C(I)=min(A(I), S)

All the arrays must have a single channel, the same data type and the same size (or ROI size).


AbsDiff

Calculates absolute difference between two arrays

void cvAbsDiff( const CvArr* A, const CvArr* B, CvArr* C );

A
The first source array.
B
The second source array.
C
The destination array.

The function cvAbsDiff calculates absolute difference between two arrays.

C(I)c = abs(A(I)c - B(I)c).

All the arrays must have the same data type and the same size (or ROI size).


AbsDiffS

Calculates absolute difference between array and scalar

void cvAbsDiffS( const CvArr* A, CvArr* C, CvScalar S );
#define cvAbs(A, C) cvAbsDiffS(A, C, cvScalarAll(0))

A
The source array.
C
The destination array.
S
The scalar.

The function cvAbsDiffS calculates absolute difference between array and scalar.

C(I)c = abs(A(I)c - Sc).

All the arrays must have the same data type and the same size (or ROI size).


Array statistics


CountNonZero

Counts non-zero array elements

int cvCountNonZero( const CvArr* A );

A
The array, must be single-channel array or multi-channel image with COI set.

The function cvCountNonZero returns the number of non-zero elements in A:

result = sumI A(I)!=0
In case of IplImage both ROI and COI are supported.


Sum

Summarizes array elements

CvScalar cvSum( const CvArr* A );

A
The array.

The function cvSum calculates sum S of array elements, independently for each channel:

Sc = sumI A(I)c
If the array is IplImage and COI is set, the function processes the selected channel only and stores the sum to the first scalar component (S0).


Avg

Calculates average (mean) of array elements

CvScalar cvAvg( const CvArr* A, const CvArr* mask=0 );

A
The array.
mask
The optional operation mask.

The function cvAvg calculates the average value M of array elements, independently for each channel:

N = sumI mask(I)!=0

Mc = 1/N • sumI A(I)c
If the array is IplImage and COI is set, the function processes the selected channel only and stores the average to the first scalar component (S0).


AvgSdv

Calculates average (mean) of array elements

void cvAvgSdv( const CvArr* A, CvScalar* _M, CvScalar* _S, const CvArr* mask=0 );

A
The array.
_M
Pointer to the mean value, may be NULL if it is not needed.
_S
Pointer to the standard deviation.
mask
The optional operation mask.

The function cvAvgSdv calculates the average value M=*_M and standard deviation S=*_S of array elements, independently for each channel:

N = sumI mask(I)!=0

Mc = 1/N • sumI A(I)c

Sc = sqrt(1/N • sumI (A(I)c - Mc)2)
If the array is IplImage and COI is set, the function processes the selected channel only and stores the average and standard deviation to the first compoenents of output scalars (M0 and S0).


MinMaxLoc

Finds global minimum and maximum in array or subarray

void cvMinMaxLoc( const CvArr* A, double* minVal, double* maxVal,
                  CvPoint* minLoc, CvPoint* maxLoc, const CvArr* mask=0 );

A
The source array, single-channel or multi-channel with COI set.
minVal
Pointer to returned minimum value.
maxVal
Pointer to returned maximum value.
minLoc
Pointer to returned minimum location.
maxLoc
Pointer to returned maximum location.
mask
The optional mask that is used to select a subarray.

The function MinMaxLoc finds minimum and maximum element values and their positions. The extremums are searched over the whole array, selected ROI (in case of IplImage) or, if mask is not NULL, in the specified array region. If the array has more than one channel, it must be IplImage with COI set. In case if multi-dimensional arrays minLoc->x and maxLoc->x will contain raw (linear) positions of the extremums.


Norm

Calculates absolute array norm, absolute difference norm or relative difference norm

double cvNorm( const CvArr* A, const CvArr* B, int normType, const CvArr* mask=0 );

A
The first source image.
B
The second source image. If it is NULL, the absolute norm of A is calculated, otherwise absolute or relative norm of A-B is calculated.
normType
Type of norm, see the discussion.
mask
The optional operation mask.

The function cvNorm calculates the absolute norm of A if B is NULL:

norm = ||A||C = maxI abs(A(I)),  if normType = CV_C

norm = ||A||L1 = sumI abs(A(I)),  if normType = CV_L1

norm = ||A||L2 = sqrt( sumI A(I)2),  if normType = CV_L2

And the function calculates absolute or relative difference norm if B is not NULL:

norm = ||A-B||C = maxI abs(A(I)-B(I)),  if normType = CV_C

norm = ||A-B||L1 = sumI abs(A(I)-B(I)),  if normType = CV_L1

norm = ||A-B||L2 = sqrt( sumI (A(I)-B(I))2 ),  if normType = CV_L2

or

norm = ||A-B||C/||B||C, if normType = CV_RELATIVE_C

norm = ||A-B||L1/||B||L1, if normType = CV_RELATIVE_L1

norm = ||A-B||L2/||B||L2, if normType = CV_RELATIVE_L2

The function Norm returns the calculated norm. The multiple-channel array are treated as single-channel, that is results for all channels are combined.


Matrix Operations, Linear Algebra and Math Functions


SetIdentity

Initializes scaled identity matrix

void cvSetIdenity( CvArr* A, CvScalar S );

A
The matrix to initialize (not necesserily square).
S
The value to assign to the diagonal elements.

The function cvSetIdentity initializes scaled identity matrix:

A(i,j)=S if i=j,
       0 otherwise

DotProduct

Calculates dot product of two arrays in Euclidian metrics

double cvDotProduct (const CvArr* A, const CvArr* B );

A
The first source array.
B
The second source array.

The function cvDotProduct calculates and returns the Euclidean dot product of two arrays.

A•B = sumI(A(I)*B(I))

In case of multiple channel arrays the results for all channels are accumulated. In particular, it gives a correct result for complex matrices. The function can process multi-dimensional arrays row by row.


CrossProduct

Calculates cross product of two 3D vectors

void cvCrossProduct( const CvArr* A, const CvArr* B, CvArr* C );

A
The first source vector.
B
The second source vector.
C
The destination vector.

The function cvCrossProduct calculates the cross product of two 3D vectors:

C = A×B, (C1 = A2B3 - A3B2 , C2 = A3B1 - A1B3 , C3 = A1B2 - A2B1).

ScaleAdd

Calculates sum of scaled array and another array

void cvScaleAdd( const CvArr* A, CvScalar S, const CvArr* B, CvArr* C );
#define cvMulAddS cvScaleAdd

A
The first source array.
S
Scale factor for the first array.
B
The second source array.
C
The destination array

The function cvScaleAdd calculates sum of scaled array and another array:

C(I)=A(I)*S + B(I)

All array parameters should be of the same size and the same size


MatMulAdd

Calculates shifted matrix product

void cvMatMulAdd( const CvArr* A, const CvArr* B, const CvArr* C, CvArr* D );
#define cvMatMul(A, B, D) cvMatMulAdd(A, B, 0, D)

A
The first source array.
B
The second source array.
C
The third source array (shift). Can be NULL, if there is no shift.
D
The destination array.

The function cvMatMulAdd calculates matrix product of two matrices and adds the third matrix to the product:

D = A*B + C   or  D(i,j)=sumk(A(i,k)*B(k,j)) + C(i,j)

All the matrices should be of the same type and the coordinated sizes. Only real or complex floating-point matrices are supported


GEMM

Performs generalized matrix multiplication

void  cvGEMM( const CvArr* A, const CvArr* B, double alpha,
              const CvArr* C, double beta, CvArr* D, int tABC=0 );
#define cvMatMulAddEx cvGEMM

A
The first source array.
B
The second source array.
C
The third source array (shift). Can be NULL, if there is no shift.
D
The destination array.
tABC
The operation flags that can be 0 or combination of the following:
CV_GEMM_A_T - transpose A
CV_GEMM_B_T - transpose B
CV_GEMM_C_T - transpose B
for example, CV_GEMM_A_T+CV_GEMM_C_T corresponds to
alpha*AT*B + beta*CT

The function cvGEMM performs generalized matrix multiplication:

D = alpha*op(A)*op(B) + beta*op(C), where op(X) is X or XT

All the matrices should be of the same type and the coordinated sizes. Only real or complex floating-point matrices are supported


MatMulAddS

Performs matrix transform on every element of array

void cvMatMulAddS( const CvArr* A, CvArr* C, const CvArr* M, const CvArr* V=0 );

A
The first source array.
C
The destination array.
M
Transformation matrix.
V
Optional shift.

The function cvMatMulAddS performs matrix transform on every element of array A and stores the result in C:

C(i,j)=M*A(i,j) + V   or   C(i,j)(k)=suml(M(k,l)*A(i,j)(l)) + V(k)

That is every element of N-channel array A is considered as N-element vector, which is transformed using matrix N×N matrix M and shift vector V. There is an option to code V into A. In this case A should be N×N+1 matrix and the right-most column is used as the shift vector.

Both source and destination arrays should be of the same size or selected ROI size and of the same type. M and V should be real floating-point matrices. The function can be used for geometrical transforms of point sets and linear color transformations.


MulTransposed

Calculates product of array and transposed array

void cvMulTransposed( const CvArr* A, CvArr* C, int order );

A
The source matrix.
C
The destination matrix.
order
Order of multipliers.

The function cvMulTransposed calculates the product of A and its transposition.

The function evaluates

C=A*AT

if order=0, and

C=AT*A

otherwise


Trace

Returns trace of matrix

CvScalar cvTrace( const CvArr* A );

A
The source matrix.

The function cvTrace returns sum of diagonal elements of the matrix A.

tr(A)=sumiA(i,i)

Transpose

Transposes matrix

void cvTranspose( const CvArr* A, CvArr* B );
#define cvT cvTranspose

A
The source matrix.
B
The destination matrix.

The function cvTranspose transposes matrix A:

B(i,j)=A(j,i)

Note that no complex conjugation is done in case of complex matrix. Conjugation should be done separately: look at the sample code in cvXorS for example


Det

Returns determinant of matrix

CvScalar cvDet( const CvArr* A );

A
The source matrix.

The function cvDet returns determinant of the square matrix A. The direct method is used for small matrices and Gaussian elimination is used for larger matrices


Invert

Finds inverse or pseudo-inverse of matrix

double cvInvert( const CvArr* A, CvArr* B, int method );
#define cvInv cvInvert

A
The source matrix.
B
The destination matrix.
method
Inversion method:
CV_LU - Gaussian elimination with optimal pivot element chose CV_SVD - Singular decomposition method

The function cvInvert inverts matrix A and stores the result in B

In case of LU method the function returns A determinant (A must be square). If it is 0, the matrix is not inverted and B is filled with zeros.

In case of SVD method the function returns the inversed condition number of A (ratio of the smallest singular value to the largest singular value) and 0 if A is all zeros. This method calculates a pseudo-inverse matrix if A is singular


Solve

Solves linear system or least-squares problem

int cvSolve( const CvArr* A, const CvArr* B, CvArr* X, int method );
#define cvInv cvSolve

A
The source matrix.
B
The right-hand part of the linear system.
method
The solution (matrix inversion) method:
CV_LU - Gaussian elimination with optimal pivot element chose CV_SVD - Singular decomposition method

The function cvSolve solves linear system or least-squares problem:

X* = arg minX||A*X-B||

If CV_LU method is used, the function returns 1 if A is non-singular and 0 otherwise, in the latter case X is not valid


SVD

Performs singular value decomposition of real floating-point matrix

void cvSVD( CvArr* A, CvArr* W, CvArr* U=0, CvArr* V=0, int flags=0 );

A
Source M×N matrix.
W
Resulting singular value matrix (M×N or N×N) or vector (N×1).
U
Optional left orthogonal matrix (M×M or M×N). If CV_SVD_U_T is specified, the number of rows and columns in the sentence above should be swapped.
V
Optional right orthogonal matrix (N×N)
flags
Operation flags; can be 0 or combination of the following:

The function cvSVD decomposes matrix A into a product of a diagonal matrix and two orthogonal matrices:

A=U*W*VT

Where W is diagonal matrix of singular values that can be coded as a 1D vector of singular values and U and V. All the singular values are non-negative and sorted (together with U and and V columns) in descenting order.

SVD algorithm is numerically robust and its typical applications include:


SVBkSb

Performs singular value back substitution

void  cvSVBkSb( const CvArr* W, const CvArr* U, const CvArr* V,
                const CvArr* B, CvArr* X, int flags );

W
Matrix or vector of singular values.
U
Left orthogonal matrix (tranposed, perhaps)
V
Right orthogonal matrix (tranposed, perhaps)
B
The matrix to multiply the pseudo-inverse of the original matrix A by. This is the optional parameter. If it is omitted then it is assumed to be an identity matrix of an appropriate size (So X will be the reconstructed pseudo-inverse of A).
X
The destination matrix: result of back substitution.
flags
Operation flags, should match exactly to the flags passed to cvSVD.

The function cvSVBkSb calculates back substitution for decomposed matrix A (see cvSVD description) and matrix B:

X=V*W-1*UT*B

Where

W-1(i,j)=1/W(i,j) if W(i,j) > epsilon,
                    0        otherwise

And epsilon is a small number - ≈10-6 or ≈10-15 depending on the matrices element type.

This function together with cvSVD is used inside cvInvert and cvSolve, and the possible reason to use these (svd & bksb) "low-level" function is to avoid temporary matrices allocation inside the high-level counterparts (inv & solve).


EigenVV

Computes eigenvalues and eigenvectors of symmetric matrix

void cvEigenVV( CvArr* A, CvArr* evects, CvArr* evals, double eps );

A
The source symmetric square matrix. It is modified during the processing.
evects
The output matrix of eigenvectors, stored as a subsequent rows.
evals
The output vector of eigenvalues, stored in the descenting order (order of eigenvalues and eigenvectors is syncronized, of course).
eps
Accuracy of diagonalization (typically, DBL_EPSILON=≈10-15 is enough).

The function cvEigenVV computes the eigenvalues and eigenvectors of the matrix A:

A*evects(i,:)' = evals(i)*evects(i,:)' (in MATLAB notation)

The contents of matrix A is destroyed by the function.

Currently the function is slower than cvSVD yet less accurate, so if A is known to be positively-defined (for example, it is a covariation matrix), it is recommended to use cvSVD to find eigenvalues and eigenvectors of A, especially if eigenvectors are not required.


PerspectiveTransform

Performs perspective matrix transform on 3D vector array

void cvPerspectiveTransform( const CvArr* A, CvArr* B, const CvArr* M );

A
The source three-channel floating-point array.
B
The destination three-channel floating-point array.
M
4 × 4 transformation matrix.

The function cvPerspectiveTransform transforms every element of A considering it a 3D vector as:

(x, y, z) -> (x'/w, y'/w, z'/w),

where
(x', y', z', w') = M*(x, y, z, 1)

and w = 1/w' if w'!=0,
          1  otherwise

CalcCovarMatrix

Calculates covariation matrix out of the set of arrays

void cvCalcCovarMatrix( CvArr** Vs, CvArr* M, CvArr* A );

Vs
The set of input arrays. All the arrays must have the same type and the same size.
M
The output covariation matrix that should be floating-point and square. Number of arrays is implicitly assumed to be equal to number of the matrix rows/columns.
A
The output array that is set to the average of the input arrays.

The function cvCalcCovarMatrix calculates the covariation matrix and average array out of the set of input arrays:

A(I)=sumkVs(k)(I)

M(i,j)=(Vs(i)-A)•(Vs(j)-A)

Where the upper index in parentheses means the particular array from the set and "•" means dot product. The covariation matrix may be used then (after inversion) in cvMahalonobis function to measure a distance between vectors, to find eigen objects via cvSVD etc.


Mahalonobis

Calculates Mahalonobis distance between vectors

double cvMahalonobis( const CvArr* A, const CvArr* B, CvArr* T );

A
The first 1D source vector.
B
The second 1D source vector.
T
The inverse covariation matrix.

The function cvMahalonobis calculates the weighted distance between two vectors and returns it:

d(A,B)=sqrt( sumi,j {T(i,j)*(A(i)-B(i))*(A(j)-B(j))} )

The covariation matrix may be calculated using cvCalcCovarMatrix function and further inverted using cvInvert function (CV_SVD method is the preffered one, because the matrix might be singular).


CartToPolar

Calculates magnitude and/or angle of 2d vectors

void cvCartToPolar( const CvArr* X, const CvArr* Y, CvArr* M, CvArr* A,
                    int angle_in_degrees=0 );

X
The array of x-coordinates
Y
The array of y-coordinates
M
The destination array of magnitudes, may be set to NULL if it is not needed
A
The destination array of angles, may be set to NULL if it is not needed. The angles are measured in radians (0..2π) or in degrees (0..360°).
angle_in_degrees
The flag indicating whether the angles are measured in radians, which is default mode, or in degrees.

The function cvCartToPolar calculates either magnitude, angle, or both of every vector (X(I),Y(I)):

M(I)=sqrt( X(I)2+Y(I)2 ),
A(I)=atan( Y(I)/X(I) )

The angles are calculated with ≈0.1° accuracy. For (0,0) point the angle is set to 0.


PolarToCart

Calculates cartesian coordinates of 2d vectors represented in polar form

void cvPolarToCart( const CvArr* M, const CvArr* A, CvArr* X, CvArr* Y,
                    int angle_in_degrees=0 );

M
The array of magnitudes. If it is NULL, the magnitudes are assumed all 1's.
A
The array of angles, whether in radians or degrees.
X
The destination array of x-coordinates, may be set to NULL if it is not needed.
Y
The destination array of y-coordinates, mau be set to NULL if it is not needed.
angle_in_degrees
The flag indicating whether the angles are measured in radians, which is default mode, or in degrees.

The function cvPolarToCart calculates either x-coodinate, y-coordinate or both of every vector M(I)*exp(A(I)*j):

X(I)=M(I)*cos(A(I)),
Y(I)=M(I)*sin(A(I))

Pow

Raises every array element to power

void cvPow( const CvArr* X, CvArr* Y, double p );

X
The source array.
Y
The destination array, should be the same type as the source.
p
The exponent of power.

The function cvPow raises every element of input array to p:

Y(I)=X(I)p, if p is integer
Y(I)=abs(X(I))p, otherwise

That is, for non-integer power exponent the absolute values of input array elements are used. However, it is possible to get true values for negative values using some extra operations, as the following sample, computing cube root of array elements, shows:

CvSize size = cvGetSize(src);
CvMat* mask = cvCreateMat( size.height, size.width, CV_8UC1 );
cvCmpS( src, 0, mask, CV_CMP_LT ); /* find negative elements */
cvPow( src, dst, 1./3 );
cvSubRS( dst, cvScalarAll(0), dst, mask ); /* negate the results of negative inputs */
cvReleaseMat( &mask );

For some values of power, such as integer values, 0.5 and -0.5, an optimized algorithm is used.


Exp

Calculates exponent of every array element

void cvExp( const CvArr* X, CvArr* Y );

X
The source array.
Y
The destination array, it should have double type or the same type as the source.

The function cvExp calculates exponent of every element of input array:

Y(I)=exp(X(I))

Maximum relative error is ≈7e-6. Currently, the function converts denormalized values to zeros on output.


Log

Calculates natural logarithm of every array element absolute value

void cvLog( const CvArr* X, CvArr* Y );

X
The source array.
Y
The destination array, it should have double type or the same type as the source.

The function cvLog calculates natural logarithm of absolute value of every element of input array:

Y(I)=log(abs(X(I))), X(I)!=0
Y(I)=C,  X(I)=0
Where C is large negative number (≈-700 in the current implementation)


CheckArr

Checks every element of input array for invalid values

int  cvCheckArr( const CvArr* X, int flags=0,
                 double minVal=0, double maxVal=0);
#define cvCheckArray cvCheckArr

X
The array to check.
flags
The operation flags, 0 or combination of:
CV_CHECK_RANGE - if set, the function checks that every value of array is within [minVal,maxVal) range, otherwise it just checks that every element is neigther NaN nor ±∞.
CV_CHECK_QUIET - if set, the function does not raises an error if an element is invalid or out of range
minVal
The inclusive lower boundary of valid values range. It is used only if CV_CHECK_RANGE is set.
maxVal
The exclusive upper boundary of valid values range. It is used only if CV_CHECK_RANGE is set.

The function cvCheckArr checks that every array element is neither NaN nor ±∞. If CV_CHECK_RANGE is set, it also checks that every element is greater than or equal to minVal and less than maxVal. The function returns nonzero if the check succeeded, i.e. all elements are valid and within the range, and zero otherwise. In the latter case if CV_CHECK_QUIET flag is not set, the function raiser runtime error.


RandInit

Initializes random number generator state

void cvRandInit( CvRandState* state, double param1, double param2, int seed,
                 int distType=CV_RAND_UNI );

state
Pointer to the initialized random number generator state structure.
param1
The first distribution parameter. In case of uniform distribution it is the inclusive lower boundary of random numbers range. In case of normal distribution it is the standard deviation of random numbers.
param2
The second distribution parameter. In case of uniform distribution it is the exclusive upper boundary of random numbers range. In case of normal distribution it is the mean value of random numbers.
seed
Initial 32-bit value to start a random sequence.
distType
Distribution type:
CV_RAND_UNI - uniform distribution
CV_RAND_NORMAL - normal or Gaussian distribution

The function cvRandInit initializes the state structure that is used for generating uniformly distributed numbers in the range [param1, param2) or normally distributed numbers with param1 mean and param2 standard deviation. The parameters are set for all the dimensions simultaneously - resemble that RNG has separate parameters for each of 4 dimensions. A multiply-with-carry generator is used.


RandSetRange

Changes the range of generated random numbers without touching RNG state

void cvRandSetRange( CvRandState* state, double param1, double param2, int index=-1 );

state
State of random number generator (RNG).
param1
New lower boundary/deviation of generated numbers.
param2
New upper boundary/mean value of generated numbers.
index
The 0-based index of dimension/channel for which the parameter are changed, -1 means changing the parameters for all dimensions.

The function cvRandSetRange changes the range of generated random numbers without reinitializing RNG state. It is useful if a few arrays of different types need to initialized with random numbers within a loop. Alternatively, you may have a separate generator for each array, but then you should provide several uncorrelated initialization seeds - one per each generator.


Rand

Fills array with random numbers and updates the RNG state

void cvRand( CvRandState* state, CvArr* arr );

state
RNG state initialized by RandInit and, optionally, customized by RandSetRange.
arr
The destination array.

The function cvRand fills the destination array with uniformly or normally distributed random numbers within the pre-set range and updates RNG state. In the sample below this and two functions above are used to put a few normally distributed floating-point numbers to random locations within a 2d array

/* let's noisy_screen be the floating-point 2d array that is to be "crapped" */
CvRandState rng_state;
int i, pointCount = 1000;
/* allocate the array of coordinates of points */
CvMat* locations = cvCreateMat( pointCount, 1, CV_32SC2 );
/* array of random point values */
CvMat* values = cvCreateMat( pointCount, 1, CV_32FC1 );
CvSize size = cvGetSize( noisy_screen );

cvRandInit( &rng_state,
            0, 1, /* use dummy parameters now and adjust them further */
            0xffffffff /* just use a fixed seed here */,
            CV_RAND_UNI /* specify uniform type */ );

/* customize the RNG to use it for initialiazing locations:
   the 0-th dimension is used for x's and the 1st - for y's */
cvRandSetRange( &rng_state, 0, size.width, 0 );
cvRandSetRange( &rng_state, 0, size.height, 1 );

/* initialize the locations */
cvRand( &rng_state, locations );

/* modify RNG to make it produce normally distributed values */
rng_state.disttype = CV_RAND_NORMAL;
cvRandSetRange( &rng_state,
                30 /* deviation */,
                100 /* average point brightness */,
                -1 /* initialize all the dimensions */ );
/* generate values */
cvRand( &rng_state, values );

/* set the points */
for( i = 0; i < pointCount; i++ )
{
    CvPoint pt = *(CvPoint*)cvPtr1D( locations, i, 0 );
    float value = *(float*)cvPtr1D( values, i, 0 );
    cvSetReal2D( noisy_screen, pt.y, pt.x, value );
}

/* not to forget to release the temporary arrays */
cvReleaseMat( &locations );
cvReleaseMat( &values );

/* cvRandInit does not allocate any memory, so there is no need
  (and no function) to deinitialize it */

RandNext

Returns 32-bit unsigned integer and updates RNG

unsigned cvRandNext( CvRandState* state );

state
RNG state initialized by RandInit and, optionally, customized by RandSetRange (though, the latter function does not affect on the discussed function outcome).

The function cvRandNext returns uniformly-distributed (regardless of the RNG distribution type settings) "plain" integer random number and updates RNG state. It is similar to rand() function from C runtime library, but it always generates 32-bit number whereas rand() returns a number in between 0 and RAND_MAX which is 2**16 or 2**32, depending on the platform.

The function is useful for generating scalar random numbers, such as points, patch sizes, table indices etc, where integer numbers of a certain range can be generated using modulo operation and floating-point numbers can be generated by scaling to 0..1 of any other specific range. Here is the example from the previous function discussion rewritten using cvRandNext:

/* the input and the task is the same as in the previous sample. */
CvRandState rng_state;
int i, pointCount = 1000;
/* ... - no arrays are allocated here */
CvSize size = cvGetSize( noisy_screen );
/* make a buffer for normally distributed numbers to reduce call overhead */
#define bufferSize 16
float normalValueBuffer[bufferSize];
CvMat normalValueMat = cvMat( bufferSize, 1, CV_32F, normalValueBuffer );
int valuesLeft = 0;

/* initialize RNG to produce normally distributed values.
   Coordinates will be uniformly distributed within 0..2**32
   anyway as they are generated using cvRandNext */
cvRandInit( &rng_state,
            100,
            30,
            0xffffffff /* just use a fixed seed here */,
            CV_RAND_NORMAL /* specify uniform type */ );

for( i = 0; i < pointCount; i++ )
{
    CvPoint pt;
    /* generate random point */
    pt.x = cvRandNext( &rng_state ) % size.width;
    pt.y = cvRandNext( &rng_state ) % size.height;

    if( valuesLeft <= 0 )
    {
        /* fulfill the buffer with normally distributed numbers if the buffer is empty */
        cvRand( &rng_state, &normalValueMat );
        valuesLeft = bufferSize;
    }
    cvSetReal2D( noisy_screen, pt.y, pt.x, normalValueBuffer[--valuesLeft]);
}

/* there is no need to deallocate normalValueMat because we have
both the matrix header and the data on stack. It is a common and efficient
practice of working with small, fixed-size matrices */

DFT

Performs forward or inverse Discrete Fourier transform of 1D or 2D floating-point array

#define CV_DXT_INVERSE  1
#define CV_DXT_SCALE 2
#define CV_DXT_INV_SCALE (CV_DXT_SCALE|CV_DXT_INVERSE)
#define CV_DXT_INVERSE_SCALE CV_DXT_INV_SCALE

void cvDFT( const CvArr* src, CvArr* dst, int flags );

src
Source array, real or complex.
dst
Destination array of the same size and same type as the source.
flags
Transformation flags, 0 or a combination of the following flags:
CV_DXT_INVERSE - perform inverse transform (w/o post-scaling>
CV_DXT_SCALE - divide the result by the number of array elements
For convenience, the constant CV_DXT_FORWARD may be used instead of literal 0.

The function cvDFT performs forward or inverse transform of 1D or 2D floating-point array:

Forward Fourier transform of 1D vector of N elements:
y = F•x, where Fik=exp(-j•Pi•i•k/N), j=sqrt(-1)

Inverse Fourier transform of 1D vector of N elements:
x = F-1•y = FT•y

Forward Fourier transform of 2D vector of M×N elements:
Y = F•X•F*

Inverse Fourier transform of 2D vector of M×N elements:
X = F*•Y•F

In case of real (single-channel) data, the packed format, borrowed from IPL, is used to to represent a result of forward Fourier transform or input for inverse Fourier transform:

Re Y0,0      Re Y0,1    Im Y0,1    Re Y0,2     Im Y0,2  ...  Re Y0,N/2-1   Im Y0,N/2-1  Re Y0,N/2
Re Y1,0      Re Y1,1    Im Y1,1    Re Y1,2     Im Y1,2  ...  Re Y1,N/2-1   Im Y1,N/2-1  Re Y1,N/2
Im Y2,0      Re Y2,1    Im Y2,1    Re Y2,2     Im Y2,2  ...  Re Y2,N/2-1   Im Y2,N/2-1  Im Y2,N/2
............................................................................................
Re YM/2-1,0   Re YM-3,1   Im YM-3,1  Re YM-3,2   Im YM-3,2 ...  Re YM-3,N/2-1  Im YM-3,N/2-1 Re YM-3,N/2
Im YM/2-1,0   Re YM-2,1   Im YM-2,1  Re YM-2,2   Im YM-2,2 ...  Re YM-2,N/2-1  Im YM-2,N/2-1 Im YM-2,N/2
Re YM/2,0    Re YM-1,1   Im YM-1,1  Re YM-1,2   Im YM-1,2  ... Re YM-1,N/2-1  Im YM-1,N/2-1 Im YM-1,N/2

Note: the last column is present if N is even, the last row is present if M is even.

In case of 1D real transform the result looks like the first row of the above matrix


MulCss

Performs per-element multiplication of two Fourier spectrums of two real arrays

void cvMulCss( const CvArr* srcA, const CvArr* srcB, CvArr* dst );

srcA
The first source array.
srcB
The second source array.
dst
The destination array of the same type and the same size of the sources.

The function cvMulCss performs per-element multiplication of the two packed matrices that are produced by forward real Fourier transform (1D or 2D).

Calculating DFT's of two real arrays, then multiplying results by cvMulCss and performing inverse DFT on the product is equivalent yet faster way to find cyclic convolution of the two original arrays.


DCT

Performs forward or inverse Discrete Cosine transform of 1D or 2D floating-point array

#define CV_DXT_INVERSE  1
#define CV_DXT_SCALE 2
#define CV_DXT_INV_SCALE (CV_DXT_SCALE|CV_DXT_INVERSE)
#define CV_DXT_INVERSE_SCALE CV_DXT_INV_SCALE

void cvDCT( const CvArr* src, CvArr* dst, int flags );

src
Source array, real 1D or 2D array.
dst
Destination array of the same size and same type as the source.
flags
Transformation flags, 0 or a combination of the following flags:
CV_DXT_INVERSE - perform inverse transform
CV_DXT_SCALE - divide the result by the number of array elements
For convenience, the constant CV_DXT_FORWARD may be used instead of literal 0.

The function cvDCT performs forward or inverse transform of 1D or 2D floating-point array:

Forward Cosine transform of 1D vector of N elements:
y = C•x, where Cik=sqrt((i==0?1:2)/N)•cos(Pi•(2i+1)•k/N), j=sqrt(-1)

Inverse Cosine transform of 1D vector of N elements:
x = C-1•y = CT•y

Forward Cosine transform of 2D vector of M×N elements:
Y = C•X•CT

Inverse Fourier transform of 2D vector of M×N elements:
X = CT•Y•C

Dynamic Data Structures


CvMemStorage

Growing memory storage

    typedef struct CvMemStorage
    {
        struct CvMemBlock* bottom;/* first allocated block */
        struct CvMemBlock* top; /* the current memory block - top of the stack */
        struct CvMemStorage* parent; /* borrows new blocks from */
        int block_size; /* block size */
        int free_space; /* free space in the top block (in bytes) */
    } CvMemStorage;

Memory storage is a low-level structure used to store dynamically growing data structures such as sequences, contours, graphs, subdivisions etc. It is organized as a list of memory blocks of equal size - bottom field is the beginning of the list of blocks and top is the currently used block, but not necessarily the last block of the list. All blocks between bottom and top, not including the latter, are considered fully ocupied; and all blocks between top and the last block, not including top, are considered free and top block itself is partly ocupied - free_space contains the number of free bytes left in the end of top.

New memory buffer that may be allocated explicitly by cvMemStorageAlloc function or implicitly by higher-level functions, such as cvSeqPush, cvGraphAddEdge etc., always starts in the end of the current block if it fits there. After allocation free_space is decremented by the size of the allocated buffer plus some padding to keep the proper alignment. When the allocated buffer does not fit into the available part of top, the next storage block from the list is taken as top and free_space is reset to the whole block size prior to the allocation.

If there is no more free blocks, a new block is allocated (or borrowed from parent, see cvCreateChildMemStorage) and added to the end of list. Thus, the storage behaves as a stack with bottom indicating bottom of the stack and the pair (top, free_space) indicating top of the stack. The stack top may be saved via cvSaveMemStoragePos, restored via cvRestoreMemStoragePos or reset via cvClearStorage.


CvMemBlock

Memory storage block

    typedef struct CvMemBlock
    {
        struct CvMemBlock* prev;
        struct CvMemBlock* next;
    } CvMemBlock;

The structure CvMemBlock represents a single block of memory storage. Actual data of the memory blocks follows the header, that is, the i-th byte of the memory block can be retrieved with the expression ((char*)(mem_block_ptr+1))[i]. However, normally there is no need to access the storage structure fields directly.


CvMemStoragePos

Memory storage position

    typedef struct CvMemStoragePos
    {
        CvMemBlock* top;
        int free_space;
    } CvMemStoragePos;

The structure described below stores the position of the stack top that can be saved via cvSaveMemStoragePos and restored via cvRestoreMemStoragePos.


CreateMemStorage

Creates memory storage

CvMemStorage* cvCreateMemStorage( int blockSize=0 );

blockSize
Size of the storage blocks in bytes. If it is 0, the block size is set to default value - currently it is ≈64K.

The function cvCreateMemStorage creates a memory storage and returns pointer to it. Initially the storage is empty. All fields of the header, except the block_size, are set to 0.


CreateChildMemStorage

Creates child memory storage

CvMemStorage* cvCreateChildMemStorage( CvMemStorage* parent );

parent
Parent memory storage.

The function cvCreateChildMemStorage creates a child memory storage that is similar to simple memory storage except for the differences in the memory allocation/deallocation mechanism. When a child storage needs a new block to add to the block list, it tries to get this block from the parent. The first unoccupied parent block available is taken and excluded from the parent block list. If no blocks are available, the parent either allocates a block or borrows one from its own parent, if any. In other words, the chain, or a more complex structure, of memory storages where every storage is a child/parent of another is possible. When a child storage is released or even cleared, it returns all blocks to the parent. In other aspects, the child storage is the same as the simple storage.

The children storages are useful in the following situation. Imagine that user needs to process dynamical data resided in some storage and put the result back to the same storage. With the simplest approach, when temporary data is resided in the same storage as the input and output data, the storage will look as following after processing:

Dynamic data processing without using child storage

That is, garbage appears in the middle of the storage. However, if one creates a child memory storage in the beginning of the processing, writes temporary data there and releases the child storage in the end, no garbage will appear in the source/destination storage:

Dynamic data processing using a child storage


ReleaseMemStorage

Releases memory storage

void cvReleaseMemStorage( CvMemStorage** storage );

storage
Pointer to the released storage.

The function cvReleaseMemStorage deallocates all storage memory blocks or returns them to the parent, if any. Then it deallocates the storage header and clears the pointer to the storage. All children of the storage must be released before the parent is released.


ClearMemStorage

Clears memory storage

void cvClearMemStorage( CvMemStorage* storage );

storage
Memory storage.

The function cvClearMemStorage resets the top (free space boundary) of the storage to the very beginning. This function does not deallocate any memory. If the storage has a parent, the function returns all blocks to the parent.


MemStorageAlloc

Allocates memory buffer in the storage

void* cvMemStorageAlloc( CvMemStorage* storage, int size );

storage
Memory storage.
size
Buffer size.

The function cvMemStorageAlloc allocates memory buffer in the storage. The buffer size must not exceed the storage block size, otherwise runtime error is raised. The buffer address is aligned by CV_STRUCT_ALIGN (=sizeof(double) for the moment) bytes.


SaveMemStoragePos

Saves memory storage position

void cvSaveMemStoragePos( const CvMemStorage* storage, CvMemStoragePos* pos );

storage
Memory storage.
pos
The output position of the storage top.

The function cvSaveMemStoragePos saves the current position of the storage top to the parameter pos. The function cvRestoreMemStoragePos can further retrieve this position.


RestoreMemStoragePos

Restores memory storage position

void cvRestoreMemStoragePos( CvMemStorage* storage, CvMemStoragePos* pos );

storage
Memory storage.
pos
New storage top position.

The function cvRestoreMemStoragePos restores the position of the storage top from the parameter pos. This function and the function cvClearMemStorage are the only methods to release memory occupied in memory blocks. Note again that there is no way to free memory in the middle of the occupied part of the storage.


Sequences


CvSeq

Growable sequence of elements

    #define CV_SEQUENCE_FIELDS() \
        int flags; /* micsellaneous flags */ \
        int header_size; /* size of sequence header */ \
        struct CvSeq* h_prev; /* previous sequence */ \
        struct CvSeq* h_next; /* next sequence */ \
        struct CvSeq* v_prev; /* 2nd previous sequence */ \
        struct CvSeq* v_next; /* 2nd next sequence */ \
        int total; /* total number of elements */ \
        int elem_size;/* size of sequence element in bytes */ \
        char* block_max;/* maximal bound of the last block */ \
        char* ptr; /* current write pointer */ \
        int delta_elems; /* how many elements allocated when the sequence grows (sequence granularity) */ \
        CvMemStorage* storage; /* where the seq is stored */ \
        CvSeqBlock* free_blocks; /* free blocks list */ \
        CvSeqBlock* first; /* pointer to the first sequence block */


    typedef struct CvSeq
    {
        CV_SEQUENCE_FIELDS()
    } CvSeq;

The structure CvSeq is a base for all of OpenCV dynamic data structures.

Such an unusual definition via a helper macro simplifies the extension of the structure CvSeq with additional parameters. To extend CvSeq the user may define a new structure and put user-defined fields after all CvSeq fields that are included via the macro CV_SEQUENCE_FIELDS().

There are two types of sequences - dense and sparse. Base type for dense sequences is CvSeq and such sequences are used to represent growable 1d arrays - vectors, stacks, queues, deques. They have no gaps in the middle - if an element is removed from the middle or inserted into the middle of the sequence the elements from the closer end are shifted. Sparse sequences have CvSet base class and they are discussed later in more details. They are sequences of nodes each of those may be either occupied or free as indicated by the node flag. Such sequences are used for unordered data structures such as sets of elements, graphs, hash tables etc.

The field header_size contains the actual size of the sequence header and should be greater or equal to sizeof(CvSeq).

The fields h_prev, h_next, v_prev, v_next can be used to create hierarchical structures from separate sequences. The fields h_prev and h_next point to the previous and the next sequences on the same hierarchical level while the fields v_prev and v_next point to the previous and the next sequence in the vertical direction, that is, parent and its first child. But these are just names and the pointers can be used in a different way.

The field first points to the first sequence block, whose structure is described below.

The field total contains the actual number of dense sequence elements and number of allocated nodes in sparse sequence.

The field flagscontain the particular dynamic type signature (CV_SEQ_MAGIC_VAL for dense sequences and CV_SET_MAGIC_VAL for sparse sequences) in the highest 16 bits and miscellaneous information about the sequence. The lowest CV_SEQ_ELTYPE_BITS bits contain the ID of the element type. Most of sequence processing functions do not use element type but element size stored in elem_size. If sequence contains the numeric data of one of CvMat type then the element type matches to the corresponding CvMat element type, e.g. CV_32SC2 may be used for sequence of 2D points, CV_32FC1 for sequences of floating-point values etc. CV_SEQ_ELTYPE(seq_header_ptr) macro retrieves the type of sequence elements. Processing function that work with numerical sequences check that elem_size is equal to the calculated from the type element size. Besides CvMat compatible types, there are few extra element types defined in cvtypes.h header:

Standard Types of Sequence Elements

    #define CV_SEQ_ELTYPE_POINT          CV_32SC2  /* (x,y) */
    #define CV_SEQ_ELTYPE_CODE           CV_8UC1   /* freeman code: 0..7 */
    #define CV_SEQ_ELTYPE_GENERIC        0 /* unspecified type of sequence elements */
    #define CV_SEQ_ELTYPE_PTR            CV_USRTYPE1 /* =6 */
    #define CV_SEQ_ELTYPE_PPOINT         CV_SEQ_ELTYPE_PTR  /* &elem: pointer to element of other sequence */
    #define CV_SEQ_ELTYPE_INDEX          CV_32SC1  /* #elem: index of element of some other sequence */
    #define CV_SEQ_ELTYPE_GRAPH_EDGE     CV_SEQ_ELTYPE_GENERIC  /* &next_o, &next_d, &vtx_o, &vtx_d */
    #define CV_SEQ_ELTYPE_GRAPH_VERTEX   CV_SEQ_ELTYPE_GENERIC  /* first_edge, &(x,y) */
    #define CV_SEQ_ELTYPE_TRIAN_ATR      CV_SEQ_ELTYPE_GENERIC  /* vertex of the binary tree   */
    #define CV_SEQ_ELTYPE_CONNECTED_COMP CV_SEQ_ELTYPE_GENERIC  /* connected component  */
    #define CV_SEQ_ELTYPE_POINT3D        CV_32FC3  /* (x,y,z)  */

The next CV_SEQ_KIND_BITS bits specify the kind of the sequence:

Standard Kinds of Sequences

    /* generic (unspecified) kind of sequence */
    #define CV_SEQ_KIND_GENERIC     (0 << CV_SEQ_ELTYPE_BITS)

    /* dense sequence suntypes */
    #define CV_SEQ_KIND_CURVE       (1 << CV_SEQ_ELTYPE_BITS)
    #define CV_SEQ_KIND_BIN_TREE    (2 << CV_SEQ_ELTYPE_BITS)

    /* sparse sequence (or set) subtypes */
    #define CV_SEQ_KIND_GRAPH       (3 << CV_SEQ_ELTYPE_BITS)
    #define CV_SEQ_KIND_SUBDIV2D    (4 << CV_SEQ_ELTYPE_BITS)

The remaining bits are used to identify different features specific to certain sequence kinds and element types. For example, curves made of points ( CV_SEQ_KIND_CURVE|CV_SEQ_ELTYPE_POINT ), together with the flag CV_SEQ_FLAG_CLOSED belong to the type CV_SEQ_POLYGON or, if other flags are used, to its subtype. Many contour processing functions check the type of the input sequence and report an error if they do not support this type. The file cvtypes.h stores the complete list of all supported predefined sequence types and helper macros designed to get the sequence type of other properties. Below follows the definition of the building block of sequences.


CvSeqBlock

Continuous sequence block

    typedef struct CvSeqBlock
    {
        struct CvSeqBlock* prev; /* previous sequence block */
        struct CvSeqBlock* next; /* next sequence block */
        int start_index; /* index of the first element in the block +
        sequence->first->start_index */
        int count; /* number of elements in the block */
        char* data; /* pointer to the first element of the block */
    } CvSeqBlock;

Sequence blocks make up a circular double-linked list, so the pointers prev and next are never NULL and point to the previous and the next sequence blocks within the sequence. It means that next of the last block is the first block and prev of the first block is the last block. The fields start_index and count help to track the block location within the sequence. For example, if the sequence consists of 10 elements and splits into three blocks of 3, 5, and 2 elements, and the first block has the parameter start_index = 2, then pairs (start_index, count) for the sequence blocks are (2,3), (5, 5), and (10, 2) correspondingly. The parameter start_index of the first block is usually 0 unless some elements have been inserted at the beginning of the sequence.


CreateSeq

Creates sequence

CvSeq* cvCreateSeq( int seqFlags, int headerSize,
                    int elemSize, CvMemStorage* storage );

seqFlags
Flags of the created sequence. If the sequence is not passed to any function working with a specific type of sequences, the sequence value may be set to 0, otherwise the appropriate type must be selected from the list of predefined sequence types.
headerSize
Size of the sequence header; must be greater or equal to sizeof(CvSeq). If a specific type or its extension is indicated, this type must fit the base type header.
elemSize
Size of the sequence elements in bytes. The size must be consistent with the sequence type. For example, for a sequence of points to be created, the element type CV_SEQ_ELTYPE_POINT should be specified and the parameter elemSize must be equal to sizeof(CvPoint).
storage
Sequence location.

The function cvCreateSeq creates a sequence and returns the pointer to it. The function allocates the sequence header in the storage block as one continuous chunk and fills the parameter elemSize, flags headerSize, and storage with passed values, sets delta_elems to the default value (that may be reassigned using cvSetSeqBlockSize function), and clears other fields, including the space behind sizeof(CvSeq).


SetSeqBlockSize

Sets up sequence block size

void cvSetSeqBlockSize( CvSeq* seq, int blockSize );

seq
Sequence.
blockSize
Desirable block size.

The function cvSetSeqBlockSize affects the memory allocation granularity. When the free space in the sequence buffers has run out, the function allocates blockSize bytes in the storage. If this block immediately follows the one previously allocated, the two blocks are concatenated, otherwise, a new sequence block is created. Therefore, the bigger the parameter is, the lower the possible sequence fragmentation, but the more space in the storage is wasted. When the sequence is created, the parameter blockSize is set to the default value ≈1K. The function can be called any time after the sequence is created and affects future allocations. The final block size can be different from the one desired, e.g., if it is larger than the storage block size, or smaller than the sequence block header size plus the sequence element size.


SeqPush

Adds element to sequence end

char* cvSeqPush( CvSeq* seq, void* element=0 );

seq
Sequence.
element
Added element.

The function cvSeqPush adds an element to the end of sequence and retuns pointer to the allocated element. If the input element is NULL, the function simply allocates a space for one more element.

The following code demonstrates how to create a new sequence using this function:

CvMemStorage* storage = cvCreateMemStorage(0);
CvSeq* seq = cvCreateSeq( CV_32SC1, /* sequence of integer elements */
                          sizeof(CvSeq), /* header size - no extra fields */
                          sizeof(int), /* element size */
                          storage /* the container storage */ );
int i;
for( i = 0; i < 100; i++ )
{
    int* added = (int*)cvSeqPush( seq, &i );
    printf( "%d is added\n", *added );
}

...
/* release memory storage in the end */
cvReleaseMemStorage( &storage );

The function cvSeqPush has O(1) complexity, but there is a faster method for writing large sequences (see cvStartWriteSeq and related functions).


SeqPop

Removes element from sequence end

void cvSeqPop( CvSeq* seq, void* element=0 );

seq
Sequence.
element
Optional parameter. If the pointer is not zero, the function copies the removed element to this location.

The function cvSeqPop removes an element from the sequence. The function reports an error if the sequence is already empty. The function has O(1) complexity.


SeqPushFront

Adds element to sequence beginning

char* cvSeqPushFront( CvSeq* seq, void* element=0 );

seq
Sequence.
element
Added element.

The function cvSeqPushFront is similar to cvSeqPush but it adds the new element to the beginning of the sequence. The function has O(1) complexity.


SeqPopFront

Removes element from sequence beginning

void cvSeqPopFront( CvSeq* seq, void* element=0 );

seq
Sequence.
element
Optional parameter. If the pointer is not zero, the function copies the removed element to this location.

The function cvSeqPopFront removes an element from the beginning of the sequence. The function reports an error if the sequence is already empty. The function has O(1) complexity.


SeqPushMulti

Pushes several elements to the either end of sequence

void cvSeqPushMulti( CvSeq* seq, void* elements, int count, int in_front=0 );

seq
Sequence.
elements
Added elements.
count
Number of elements to push.
in_front
The flags specifying the modified sequence end:
CV_BACK (=0) - the elements are added to the end of sequence
CV_FRONT(!=0) - the elements are added to the beginning of sequence

The function cvSeqPushMulti adds several elements to either end of the sequence. The elements are added to the sequence in the same order as they are arranged in the input array but they can fall into different sequence blocks.


SeqPopMulti

Removes several elements from the either end of sequence

void cvSeqPopMulti( CvSeq* seq, void* elements, int count, int in_front=0 );

seq
Sequence.
elements
Removed elements.
count
Number of elements to pop.
in_front
The flags specifying the modified sequence end:
CV_BACK (=0) - the elements are removed from the end of sequence
CV_FRONT(!=0) - the elements are removed from the beginning of sequence

The function cvSeqPopMulti removes several elements from either end of the sequence. If the number of the elements to be removed exceeds the total number of elements in the sequence, the function removes as many elements as possible.


SeqInsert

Inserts element in sequence middle

char* cvSeqInsert( CvSeq* seq, int beforeIndex, void* element=0 );

seq
Sequence.
beforeIndex
Index before which the element is inserted. Inserting before 0 (the minimal allowed value of the parameter) is equal to cvSeqPushFront and inserting before seq->total (the maximal allowed value of the parameter) is equal to cvSeqPush.
element
Inserted element.

The function cvSeqInsert shifts the sequence elements from the inserted position to the nearest end of the sequence and copies the element content there if the pointer is not NULL. The function returns pointer to the inserted element.


SeqRemove

Removes element from sequence middle

void cvSeqRemove( CvSeq* seq, int index );

seq
Sequence.
index
Index of removed element.

The function cvSeqRemove removes elements with the given index. If the index is out of range the function reports an error. An attempt to remove an element from an empty sequence is a partitial case of this situation. The function removes an element by shifting the sequence elements between the nearest end of the sequence and the index-th position, not counting the latter.


ClearSeq

Clears sequence

void cvClearSeq( CvSeq* seq );

seq
Sequence.

The function cvClearSeq removes all elements from the sequence. The function does not return the memory to the storage, but this memory is reused later when new elements are added to the sequence. This function time complexity is O(1).


GetSeqElem

Returns pointer to sequence element by its index

char* cvGetSeqElem( CvSeq* seq, int index, CvSeqBlock** block=0 );
#define CV_GET_SEQ_ELEM( TYPE, seq, index )  (TYPE*)cvGetSeqElem( (CvSeq*)(seq), (index), 0 )

seq
Sequence.
index
Index of element.
block
Optional output parameter. If it is not NULL, the pointer to the sequence block containing the requested element is stored in this location.

The function cvGetSeqElem finds the element with the given index in the sequence and returns the pointer to it. In addition, the function can return the pointer to the sequence block that contains the element. If the element is not found, the function returns 0. The function supports negative indices, where -1 stands for the last sequence element, -2 stands for the one before last, etc. If the sequence is most likely to consist of a single sequence block or the desired element is likely to be located in the first block, then the macro CV_GET_SEQ_ELEM( elemType, seq, index ) should be used, where the parameter elemType is the type of sequence elements ( CvPoint for example), the parameter seq is a sequence, and the parameter index is the index of the desired element. The macro checks first whether the desired element belongs to the first block of the sequence and, if so, returns the element, otherwise the macro calls the main function GetSeqElem. Negative indices always cause the cvGetSeqElem call. The function has O(1) time complexity assuming that number of blocks is much smaller than the number of elements.


SeqElemIdx

Returns index of concrete sequence element

int cvSeqElemIdx( CvSeq* seq, void* element, CvSeqBlock** block=0 );

seq
Sequence.
element
Pointer to the element within the sequence.
block
Optional argument. If the pointer is not NULL, the address of the sequence block that contains the element is stored in this location.

The function cvSeqElemIdx returns the index of a sequence element or a negative number if the element is not found.


CvtSeqToArray

Copies sequence to one continuous block of memory

void* cvCvtSeqToArray( CvSeq* seq, void* array, CvSlice slice=CV_WHOLE_SEQ );

seq
Sequence.
array
Pointer to the destination array that must fit all the sequence elements.
slice
The sequence part to copy to the array.

The function cvCvtSeqToArray copies the entire sequence or subsequence to the specified buffer and returns the pointer to the buffer.


MakeSeqHeaderForArray

Constructs sequence from array

void cvMakeSeqHeaderForArray( int seqType, int headerSize, int elemSize,
                              void* array, int total,
                              CvSeq* sequence, CvSeqBlock* block );

seqType
Type of the created sequence.
headerSize
Size of the header of the sequence. Parameter sequence must point to the structure of that size or greater size.
elemSize
Size of the sequence element.
array
Pointer to the array that makes up the sequence.
total
Total number of elements in the sequence. The number of array elements must be equal to the value of this parameter.
sequence
Pointer to the local variable that is used as the sequence header.
block
Pointer to the local variable that is the header of the single sequence block.

The function cvMakeSeqHeaderForArray initializes sequence header for array. The sequence header as well as the sequence block are allocated by the user (for example, on stack). No data is copied by the function. The resultant sequence will consists of a single block and have NULL storage pointer, thus, it is possible to read its elements, but the attempts to add elements to the sequence will raise an error in most cases.


SeqSlice

Makes separate header for the sequence slice

CvSeq* cvSeqSlice( CvSeq* seq, CvSlice slice=CV_WHOLE_SEQ,
                   CvMemStorage* storage=0, int copyData=0 );

cvCloneSeq(seq[,storage]) ~ cvSeqSlice(seq,CV_WHOLE_SEQ,storage,1)

seq
Sequence.
slice
The part of the sequence to extract.
storage
The destination storage to keep the new sequence header and the copied data if any. If it is NULL, the function uses the storage containing the input sequence.
copyData
The flag that indicates whether to copy the elements of the extracted slice (copyData!=0) or not (copyData=0)

The function cvSeqSlice creates another sequence and either makes it share the elements of the specified slice with the original sequence or creates another copy of the slice. So if one needs to process a part of sequence but the processing function does not have a slice parameter, the required sequence slice may be represented as a separate sequence using this function. Another purpose of the function is to make a copy of entire sequence that is done by cvCloneSeq inline shortcut to cvSeqSlice


SeqRemoveSlice

Removes sequence slice

void cvSeqRemoveSlice( CvSeq* seq, CvSlice slice );

seq
Sequence.
slice
The part of the sequence to remove.

The function cvSeqRemoveSlice removes slice from the sequence.


SeqInsertSlice

Inserts array in the middle of sequence

void cvSeqInsertSlice( CvSeq* seq, int beforeIndex, const CvArr* fromArr );

seq
Sequence.
slice
The part of the sequence to remove.

The function cvSeqInsertSlice inserts all fromArr array elements at the specified position of the sequence. The array may be matrix or another sequence.


SeqInvert

Reverses the order of sequence elements

void cvSeqInvert( CvSeq* seq );

seq
Sequence.

The function cvSeqInvert reverses the sequence in-place - makes the first element go last, the last element go first etc.


SeqSort

Sorts sequence element using the specified comparison function

/* a < b ? -1 : a > b ? 1 : 0 */
typedef int (CV_CDECL* CvCmpFunc)(const void* a, const void* b, void* userdata);

void cvSeqSort( CvSeq* seq, CvCmpFunc func, void* userdata );

seq
The sequence to sort
func
The comparison function that returns negative, zero or positive value depending on the elements relation (see the above declaration and the example below) - similar function is used by qsort from C runline except that in the latter userdata is not used
userdata
The user parameter passed to the compasion function; helps to avoid global variables in some cases.

The function cvSeqSort sorts the sequence in-place using the specified criteria. Below is the example of the function use:

/* Sort 2d points in top-to-bottom left-to-right order */
static int cmp_func( const void* _a, const void* _b, void* userdata )
{
    CvPoint* a = (CvPoint*)_a;
    CvPoint* b = (CvPoint*)_b;
    int y_diff = a->y - b->y;
    int x_diff = a->x - b->x;
    return y_diff ? y_diff : x_diff;
}

...

CvMemStorage* storage = cvCreateMemStorage(0);
CvSeq* seq = cvCreateSeq( CV_32SC2, sizeof(CvSeq), sizeof(CvPoint), storage );
int i;

for( i = 0; i < 10; i++ )
{
    CvPoint pt;
    pt.x = rand() % 1000;
    pt.y = rand() % 1000;
    cvSeqPush( seq, &pt );
}

cvSeqSort( seq, cmp_func, 0 /* userdata is not used here */ );

/* print out the sorted sequence */
for( i = 0; i < seq->total; i++ )
{
    CvPoint* pt = (CvPoint*)cvSeqElem( seq, i );
    printf( "(%d,%d)\n", pt->x, pt->y );
}

cvReleaseMemStorage( &storage );

StartAppendToSeq

Initializes process of writing to sequence

void cvStartAppendToSeq( CvSeq* seq, CvSeqWriter* writer );

seq
Pointer to the sequence.
writer
Writer state; initialized by the function.

The function cvStartAppendToSeq initializes the writer to write to the sequence. Written elements are added to the end of the sequence by CV_WRITE_SEQ_ELEM( written_elem, writer ) macro. Note that during the writing process other operations on the sequence may yield incorrect result or even corrupt the sequence (see description of cvFlushSeqWriter that helps to avoid some of that difficulties).


StartWriteSeq

Creates new sequence and initializes writer for it

void cvStartWriteSeq( int seqFlags, int headerSize, int elemSize,
                      CvMemStorage* storage, CvSeqWriter* writer );

seqFlags
Flags of the created sequence. If the sequence is not passed to any function working with a specific type of sequences, the sequence value may be equal to 0, otherwise the appropriate type must be selected from the list of predefined sequence types.
headerSize
Size of the sequence header. The parameter value may not be less than sizeof(CvSeq). If a certain type or extension is specified, it must fit the base type header.
elemSize
Size of the sequence elements in bytes; must be consistent with the sequence type. For example, if the sequence of points is created (element type CV_SEQ_ELTYPE_POINT ), then the parameter elemSize must be equal to sizeof(CvPoint).
storage
Sequence location.
writer
Writer state; initialized by the function.

The function cvStartWriteSeq is a composition of cvCreateSeq and cvStartAppendToSeq. The pointer to the created sequence is stored at writer->seq and is also returned by cvEndWriteSeq function that should be called in the end.


EndWriteSeq

Finishes process of writing sequence

CvSeq* cvEndWriteSeq( CvSeqWriter* writer );

writer
Writer state

The function cvEndWriteSeq finishes the writing process and returns the pointer to the written sequence. The function also truncates the last incomplete sequence block to return the remaining part of the block to the memory storage. After that the sequence can be read and modified safely.


FlushSeqWriter

Updates sequence headers from the writer state

void cvFlushSeqWriter( CvSeqWriter* writer );

writer
Writer state

The function cvFlushSeqWriter is intended to enable the user to read sequence elements, whenever required, during the writing process, e.g., in order to check specific conditions. The function updates the sequence headers to make reading from the sequence possible. The writer is not closed, however, so that the writing process can be continued any time. In some algorithm requires often flush'es, consider using cvSeqPush instead.


StartReadSeq

Initializes process of sequential reading from sequence

void cvStartReadSeq( CvSeq* seq, CvSeqReader* reader, int reverse=0 );

seq
Sequence.
reader
Reader state; initialized by the function.
reverse
Determines the direction of the sequence traversal. If reverse is 0, the reader is positioned at the first sequence element, otherwise it is positioned at the last element.

The function cvStartReadSeq initializes the reader state. After that all the sequence elements from the first down to the last one can be read by subsequent calls of the macro CV_READ_SEQ_ELEM( read_elem, reader ) in case of forward reading and by using CV_REV_READ_SEQ_ELEM( read_elem, reader ) in case of reversed reading. Both macros put the sequence element to read_elem and move the reading pointer toward the next element. A circular structure of sequence blocks is used for the reading process, that is, after the last element has been read by the macro CV_READ_SEQ_ELEM, the first element is read when the macro is called again. The same applies to CV_REV_READ_SEQ_ELEM . There is no function to finish the reading process, since it neither changes the sequence nor creates any temporary buffers. The reader field ptr points to the current element of the sequence that is to be read next. The code below demonstrates how to use sequence writer and reader.

CvMemStorage* storage = cvCreateMemStorage(0);
CvSeq* seq = cvCreateSeq( CV_32SC1, sizeof(CvSeq), sizeof(int), storage );
CvSeqWriter writer;
CvSeqReader reader;
int i;

cvStartAppendToSeq( seq, &writer );
for( i = 0; i < 10; i++ )
{
    int val = rand()%100;
    CV_WRITE_SEQ_ELEM( val, writer );
    printf("%d is written\n", val );
}
cvEndWriteSeq( &writer );

cvStartReadSeq( seq, &reader, 0 );
for( i = 0; i < seq->total; i++ )
{
    int val;
    CV_READ_SEQ_ELEM( val, reader );
    printf("%d is read\n", val );
}
...

cvReleaseStorage( &storage );

GetSeqReaderPos

Returns the current reader position

int cvGetSeqReaderPos( CvSeqReader* reader );

reader
Reader state.

The function cvGetSeqReaderPos returns the current reader position (within 0 ... reader->seq->total - 1).


SetSeqReaderPos

Moves the reader to specified position

void cvSetSeqReaderPos( CvSeqReader* reader, int index, int is_relative=0 );

reader
Reader state.
index
The destination position. If the positioning mode is used (see the next parameter) the actual position will be index mod reader->seq->total.
is_relative
If it is not zero, then index is a relative to the current position.

The function cvSetSeqReaderPos moves the read position to the absolute position or relative to the current position.


Sets


CvSet

Collection of nodes

    typedef struct CvSetElem
    {
        int flags; /* it is negative if the node is free and zero or positive otherwise */
        struct CvSetElem* next_free; /* if the node is free, the field is a
                                        pointer to next free node */
    }
    CvSetElem;

    #define CV_SET_FIELDS()    \
        CV_SEQUENCE_FIELDS()   /* inherits from CvSeq */ \
        struct CvSetElem* free_elems; /* list of free nodes */

    typedef struct CvSet
    {
        CV_SET_FIELDS()
    } CvSet;

The structure CvSet is a base for OpenCV sparse data structures.

As follows from the above declaration CvSet inherits from CvSeq and it adds free_elems field it to, which is a list of free nodes. Every set node, whether free or not, is the element of the underlying sequence. While there is no restrictions on elements of dense sequences, the set (and derived structures) elements must start with integer field and be able to fit CvSetElem structure, because these two fields (integer followed by the pointer) are required for organization of node set with the list of free nodes. If a node is free, flags field is negative (the most-significant bit, or MSB, of the field is set), and next_free points to the next free node (the first free node is referenced by free_elems field of CvSet). And if a node is occupied, flags field is positive and contains the node index that may be retrieved using (set_elem->flags & CV_SET_ELEM_IDX_MASK) expression, the rest of the node content is determined by the user. In particular, the occupied nodes are not linked as the free nodes are, so the second field can be used for such a link as well as for some different purpose. The macro CV_IS_SET_ELEM(set_elem_ptr) can be used to determined whether the specified node is occupied or not.

Initially the set and the list are empty. When a new node is requiested from the set, it is taken from the list of free nodes, which is updated then. If the list appears to be empty, a new sequence block is allocated and all the nodes within the block are joined in the list of free nodes. Thus, total field of the set is the total number of nodes both occupied and free. When an occupied node is released, it is added to the list of free nodes. The node released last will be occupied first.

In OpenCV CvSet is used for representing graphs (CvGraph), sparse multi-dimensional arrays (CvSparseMat), planar subdivisions (CvSubdiv2D) etc.


CreateSet

Creates empty set

CvSet* cvCreateSet( int setFlags, int headerSize,
                    int elemSize, CvMemStorage* storage );

setFlags
Type of the created set.
headerSize
Set header size; may not be less than sizeof(CvSet).
elemSize
Set element size; may not be less than CvSetElem.
storage
Container for the set.

The function cvCreateSet creates an empty set with a specified header size and element size, and returns the pointer to the set. The function is just a thin layer on top of cvCreateSeq.


SetAdd

Occupies a node in the set

int cvSetAdd( CvSet* set, void* elem, void** insertedElem=0 );

set
Set.
elem
Optional input argument, inserted element. If not NULL, the function copies the data to the allocated node (The MSB of the first integer field is cleared after copying).
insertedElem
Optional output argument; the pointer to the allocated cell.

The function cvSetAdd allocates a new node, optionally copies input element data to it, and returns the pointer and the index to the node. The index value is taken from the lower bits of flags field of the node. The function has O(1) complexity, however there exists a faster function for allocating set nodes (see cvSetNew).


SetRemove

Removes element from set

void cvSetRemove( CvSet* set, int index );

set
Set.
index
Index of the removed element.

The function cvSetRemove removes an element with a specified index from the set. If the node at the specified location is not occupied the function does nothing. The function has O(1) complexity, however, cvSetRemoveByPtr provides yet faster way to remove a set element if it is located already.


SetNew

Adds element to set (fast variant)

CvSetElem* cvSetNew( CvSet* set );

set
Set.

The function cvSetNew is inline light-weight variant of cvSetAdd. It occupies a new node and returns pointer to it rather than index.


SetRemoveByPtr

Removes set element given its pointer

void cvSetRemoveByPtr( CvSet* set, void* elem );

set
Set.
elem
Removed element.

The function cvSetRemoveByPtr is inline light-weight variant of cvSetRemove that takes element pointer. The function does not check whether the node is occupied or not - the user should take care of it.


GetSetElem

Finds set element by its index

CvSetElem* cvGetSetElem( CvSet* set, int index );

set
Set.
index
Index of the set element within a sequence.

The function cvGetSetElem finds a set element by index. The function returns the pointer to it or 0 if the index is invalid or the corresponding node is free. The function supports negative indices as it uses cvGetSeqElem to locate the node.


ClearSet

Clears set

void cvClearSet( CvSet* set );

set
Cleared set.

The function cvClearSet removes all elements from set. It has O(1) time complexity.


Graphs


CvGraph

Oriented or unoriented weigted graph

    #define CV_GRAPH_VERTEX_FIELDS()    \
        int flags; /* vertex flags */   \
        struct CvGraphEdge* first; /* the first incident edge */

    typedef struct CvGraphVtx
    {
        CV_GRAPH_VERTEX_FIELDS()
    }
    CvGraphVtx;

    #define CV_GRAPH_EDGE_FIELDS()      \
        int flags; /* edge flags */     \
        float weight; /* edge weight */ \
        struct CvGraphEdge* next[2]; /* the next edges in the incidence lists for staring (0) */ \
                                     /* and ending (1) vertices */ \
        struct CvGraphVtx* vtx[2]; /* the starting (0) and ending (1) vertices */

    typedef struct CvGraphEdge
    {
        CV_GRAPH_EDGE_FIELDS()
    }
    CvGraphEdge;

    #define  CV_GRAPH_FIELDS()                  \
        CV_SET_FIELDS() /* set of vertices */   \
        CvSet* edges;   /* set of edges */

    typedef struct CvGraph
    {
        CV_GRAPH_FIELDS()
    }
    CvGraph;

The structure CvGraph is a base for graphs used in OpenCV.

Graph structure inherits from CvSet - this part describes common graph properties and the graph vertices, and contains another set as a member - this part describes the graph edges.

The vertex, edge and the graph header structures are declared using the same technique as other extendible OpenCV structures - via macros, that simplifies extension and customization of the structures. While the vertex and edge structures do not inherit from CvSetElem explicitly, they satisfy both conditions on the set elements - have an integer field in the beginning and fit CvSetElem structure. The flags fields are used as for indicating occupied vertices and edges as well as for other purposes, for example, for graph traversal (see cvStartScanGraph et al.), so it is better not to use them directly.

The graph is represented as a set of edges each of whose has the list of incident edges. The incidence lists for different vertices are interleaved to avoid information duplication as much as posssible.

The graph may be oriented or unoriented. In the latter case there is no distiction between edge connecting vertex A with vertex B and the edge connecting vertex B with vertex A - only one of them can exist in the graph at the same moment and it represents both <A, B> and <B, A> edges..


CreateGraph

Creates empty graph

CvGraph* cvCreateGraph( int graphFlags, int headerSize, int vertexSize,
                        int edgeSize, CvStorage* storage );

graphFlags
Type of the created graph. Usually, it is either CV_SEQ_KIND_GRAPH for generic unoriented graphs and CV_SEQ_KIND_GRAPH | CV_GRAPH_FLAG_ORIENTED for generic oriented graphs.
headerSize
Graph header size; may not be less than sizeof(CvGraph).
vertexSize
Graph vertex size; the custom vertex structure must start with CvGraphVtx (use CV_GRAPH_VERTEX_FIELDS())
edgeSize
Graph edge size; the custom edge structure must start with CvGraphEdge (use CV_GRAPH_EDGE_FIELDS())
storage
The graph container.

The function cvCreateGraph creates an empty graph and returns pointer to it.


GraphAddVtx

Adds vertex to graph

int cvGraphAddVtx( CvGraph* graph, CvGraphVtx* vtx,
                   CvGraphVtx** insertedVtx=0 );

graph
Graph.
vtx
Optional input argument used to initialize the added vertex (only user-defined fields beyond sizeof(CvGraphVtx) are copied).
insertedVtx
Optional output argument. If not NULL, the address of the new vertex is written there.

The function cvGraphAddVtx adds a vertex to the graph and returns the vertex index.


GraphRemoveVtx

Removes vertex from graph

void cvGraphRemoveVtx( CvGraph* graph, int vtxIdx );

graph
Graph.
vtxIdx
Index of the removed vertex.

The function cvGraphRemoveAddVtx removes a vertex from the graph together with all the edges incident to it. The function reports an error, if the input vertex does not belong to the graph.


GraphRemoveVtxByPtr

Removes vertex from graph

void cvGraphRemoveVtxByPtr( CvGraph* graph, CvGraphVtx* vtx );

graph
Graph.
vtx
Pointer to the removed vertex.

The function cvGraphRemoveVtxByPtr removes a vertex from the graph together with all the edges incident to it. The function reports an error, if the vertex does not belong to the graph.


GetGraphVtx

Finds graph vertex by index

CvGraphVtx* cvGetGraphVtx( CvGraph* graph, int vtxIdx );

graph
Graph.
vtxIdx
Index of the vertex.

The function cvGetGraphVtx finds the graph vertex by index and returns the pointer to it or NULL if the vertex does not belong to the graph.


GraphVtxIdx

Returns index of graph vertex

int cvGraphVtxIdx( CvGraph* graph, CvGraphVtx* vtx );

graph
Graph.
vtx
Pointer to the graph vertex.

The function cvGraphVtxIdx returns index of the graph vertex.


GraphAddEdge

Adds edge to graph

int cvGraphAddEdge( CvGraph* graph, int startIdx, int endIdx,
                    CvGraphEdge* edge, CvGraphEdge** insertedEdge=0 );

graph
Graph.
startIdx
Index of the starting vertex of the edge.
endIdx
Index of the ending vertex of the edge. For unoriented graph the order of the vertex parameters does not matter.
edge
Optional input parameter, initialization data for the edge.
insertedEdge
Optional output parameter to contain the address of the inserted edge.

The function cvGraphAddEdge connects two specified vertices. The function returns 1 if the edge has been added successfully, 0 if the edge connecting the two vertices exists already and -1 if either of the vertices was not found, the starting and the ending vertex are the same or there is some other critical situation. In the latter case (i.e. when the result is negative) the function also reports an error by default.


GraphAddEdgeByPtr

Adds edge to graph

int cvGraphAddEdgeByPtr( CvGraph* graph, CvGraphVtx* startVtx, CvGraphVtx* endVtx,
                         CvGraphEdge* edge, CvGraphEdge** insertedEdge=0 );

graph
Graph.
startVtx
Pointer to the starting vertex of the edge.
endVtx
Pointer to the ending vertex of the edge. For unoriented graph the order of the vertex parameters does not matter.
edge
Optional input parameter, initialization data for the edge.
insertedEdge
Optional output parameter to contain the address of the inserted edge within the edge set.

The function cvGraphAddEdge connects two specified vertices. The function returns 1 if the edge has been added successfully, 0 if the edge connecting the two vertices exists already and -1 if either of the vertices was not found, the starting and the ending vertex are the same or there is some other critical situation. In the latter case (i.e. when the result is negative) the function also reports an error by default.


GraphRemoveEdge

Removes edge from graph

void cvGraphRemoveEdge( CvGraph* graph, int startIdx, int endIdx );

graph
Graph.
startIdx
Index of the starting vertex of the edge.
endIdx
Index of the ending vertex of the edge. For unoriented graph the order of the vertex parameters does not matter.

The function cvGraphRemoveEdge removes the edge connecting two specified vertices. If the vertices are not connected [in that order], the function does nothing.


GraphRemoveEdgeByPtr

Removes edge from graph

void cvGraphRemoveEdgeByPtr( CvGraph* graph, CvGraphVtx* startVtx, CvGraphVtx* endVtx );

graph
Graph.
startVtx
Pointer to the starting vertex of the edge.
endVtx
Pointer to the ending vertex of the edge. For unoriented graph the order of the vertex parameters does not matter.

The function cvGraphRemoveEdgeByPtr removes the edge connecting two specified vertices. If the vertices are not connected [in that order], the function does nothing.


FindGraphEdge

Finds edge in graph

CvGraphEdge* cvFindGraphEdge( CvGraph* graph, int startIdx, int endIdx );
#define cvGraphFindEdge cvFindGraphEdge

graph
Graph.
startIdx
Index of the starting vertex of the edge.
endIdx
Index of the ending vertex of the edge. For unoriented graph the order of the vertex parameters does not matter.

The function cvFindGraphEdge finds the graph edge connecting two specified vertices and returns pointer to it or NULL if the edge does not exists.


FindGraphEdgeByPtr

Finds edge in graph

CvGraphEdge* cvFindGraphEdgeByPtr( CvGraph* graph, CvGraphVtx* startVtx, CvGraphVtx* endVtx );
#define cvGraphFindEdgeByPtr cvFindGraphEdgeByPtr

graph
Graph.
startVtx
Pointer to the starting vertex of the edge.
endVtx
Pointer to the ending vertex of the edge. For unoriented graph the order of the vertex parameters does not matter.

The function cvFindGraphEdge finds the graph edge connecting two specified vertices and returns pointer to it or NULL if the edge does not exists.


GraphEdgeIdx

Returns index of graph edge

int cvGraphEdgeIdx( CvGraph* graph, CvGraphEdge* edge );

graph
Graph.
edge
Pointer to the graph edge.

The function cvGraphEdgeIdx returns index of the graph edge.


GraphVtxDegree

Counts edges indicent to the vertex

int cvGraphVtxDegree( CvGraph* graph, int vtxIdx );

graph
Graph.
vtx
Index of the graph vertex.

The function cvGraphVtxDegree returns the number of edges incident to the specified vertex, both incoming and outcoming. To count the edges, the following code is used:

    CvGraphEdge* edge = vertex->first; int count = 0;
    while( edge )
    {
        edge = CV_NEXT_GRAPH_EDGE( edge, vertex );
        count++;
    }

The macro CV_NEXT_GRAPH_EDGE( edge, vertex ) returns the edge incident to vertex that follows after edge.


GraphVtxDegreeByPtr

Finds edge in graph

int cvGraphVtxDegreeByPtr( CvGraph* graph, CvGraphVtx* vtx );

graph
Graph.
vtx
Pointer to the graph vertex.

The function cvGraphVtxDegree returns the number of edges incident to the specified vertex, both incoming and outcoming.


ClearGraph

Clears graph

void cvClearGraph( CvGraph* graph );

graph
Graph.

The function cvClearGraph removes all vertices and edges from the graph. The function has O(1) time complexity.


CloneGraph

Clone graph

CvGraph* cvCloneGraph( const CvGraph* graph, CvMemStorage* storage );

graph
The graph to copy.
storage
Container for the copy.

The function cvCloneGraph creates full copy of the graph. If the graph vertices or edges have pointers to some external data, it still be shared between the copies. The vertex and edge indices in the new graph may be different from the original, because the function defragments the vertex and edge sets.


CvGraphScanner

Graph traversal state

    typedef struct CvGraphScanner
    {
        CvGraphVtx* vtx;       /* current graph vertex (or current edge origin) */
        CvGraphVtx* dst;       /* current graph edge destination vertex */
        CvGraphEdge* edge;     /* current edge */

        CvGraph* graph;        /* the graph */
        CvSeq*   stack;        /* the graph vertex stack */
        int      index;        /* the lower bound of certainly visited vertices */
        int      mask;         /* event mask */
    }
    CvGraphScanner;

The structure CvGraphScanner is used for depth-first graph traversal. See discussion of the functions below.


StartScanGraph

Initializes graph traverser state

void cvStartScanGraph( CvGraph* graph, CvGraphScanner* scanner,
                       CvGraphVtx* vtx=0, int mask=CV_GRAPH_ALL_ITEMS );

graph
Graph.
scanner
Graph traversal state. It is initialized by the function.
vtx
Initial vertex to start from.
mask
Event mask indicating which events are interesting to the user (where cvNextGraphItem function returns control to the user) It can be CV_GRAPH_ALL_ITEMS (all events are interesting) or combination of the following flags:

The function cvStartScanGraph initializes graph traverser state. The initialized structure is used in cvNextGraphItem function - the incremental traversal procedure.


NextGraphItem

Makes one or more steps of the graph traversal procedure

int cvNextGraphItem( CvGraphScanner* scanner );

scanner
Graph traversal state. It is updated by the function.

The function cvNextGraphItem traverses through the graph until an event interesting to the user (that is, an event, marked in the mask in cvStartScanGraph call) is met or the traversal is over. In the first case it returns one of the events, listed in the description of mask parameter above and with the next call with the same state it resumes the traversal. In the latter case it returns CV_GRAPH_OVER (-1). When the event is CV_GRAPH_VERTEX, or CV_GRAPH_BACKTRACKING or CV_GRAPH_NEW_TREE, the currently observed vertex is stored in scanner->vtx. And if the event is edge-related, the edge itself is stored at scanner->edge, the previously visited vertex - at scanner->vtx and the other ending vertex of the edge - at scanner->dst.


EndScanGraph

Finishes graph traversal procedure

void cvEndScanGraph( CvGraphScanner* scanner );

scanner
Graph traversal state.

The function cvEndScanGraph finishes graph traversal procedure. It must be called after CV_GRAPH_OVER event is received or if the traversal is interrupted somewhere before, because the traverser state contains dynamically allocated structures that need to be released


Trees


CV_TREE_NODE_FIELDS

Helper macro for a tree node type declaration

#define CV_TREE_NODE_FIELDS(node_type)                          \
    int       flags;         /* micsellaneous flags */          \
    int       header_size;   /* size of sequence header */      \
    struct    node_type* h_prev; /* previous sequence */        \
    struct    node_type* h_next; /* next sequence */            \
    struct    node_type* v_prev; /* 2nd previous sequence */    \
    struct    node_type* v_next; /* 2nd next sequence */

The macro CV_TREE_NODE_FIELDS() is used to declare structures that can be organized into hierarchical strucutures (trees). Although, it is not shown, the macro is used to declared CvSeq - the basic type for all dynamical structures and CvFileNode - XML node type used in reading/writing functions (see Persistence section below). The trees made of nodes declared using this macro can be processed using the functions described below in this section.


CvTreeNodeIterator

Opens existing or creates new file storage

typedef struct CvTreeNodeIterator
{
    const void* node;
    int level;
    int maxLevel;
}
CvTreeNodeIterator;

The structure CvTreeNodeIterator is used to traverse trees. The tree node declaration should start with CV_TREE_NODE_FIELDS(...) macro.


InitTreeNodeIterator

Initializes tree node iterator

void cvInitTreeNodeIterator( CvTreeNodeIterator* treeIterator,
                             const void* first, int maxLevel );

treeIterator
Tree iterator initialized by the function.
first
The initial node to start traversing from.
maxLevel
The maximal level of the tree (first node assumed to be at the first level) to traverse up to. For example, 1 means that only nodes at the same level as first should be visited, 2 means that the nodes on the same level as first and their direct children should be visited etc.

The function cvInitTreeNodeIterator initializes tree iterator. The tree is traversed in depth-first order.


NextTreeNode

Returns the currently observed node and moves iterator toward the next node

void* cvNextTreeNode( CvTreeNodeIterator* treeIterator );

treeIterator
Tree iterator initialized by the function.

The function cvNextTreeNode returns the currently observed node and then updates the iterator - moves it toward the next node. In other words, the function behavior is similar to *p++ expression on usual C pointer or C++ collection iterator. The function returns NULL if there is no more nodes.


PrevTreeNode

Returns the currently observed node and moves iterator toward the previous node

void* cvPrevTreeNode( CvTreeNodeIterator* treeIterator );

treeIterator
Tree iterator initialized by the function.

The function cvPrevTreeNode returns the currently observed node and then updates the iterator - moves it toward the previous node. In other words, the function behavior is similar to *p-- expression on usual C pointer or C++ collection iterator. The function returns NULL if there is no more nodes.


TreeToNodeSeq

Gathers all node pointers to the single sequence

CvSeq* cvTreeToNodeSeq( const void* first, int header_size, CvMemStorage* storage );

first
The initial tree node.
header_size
Header size of the created sequence (sizeof(CvSeq) is the most used value).
storage
Container for the sequence.

The function cvTreeToNodeSeq puts pointers of all nodes reacheable from first to the single sequence. The pointers are written subsequently in the depth-first order.


InsertNodeIntoTree

Adds new node to the tree

void cvInsertNodeIntoTree( void* node, void* parent, void* frame );

node
The inserted node.
parent
The parent node that is already in the tree.
frame
The top level node. If parent and frame are the same, v_prev field of node is set to NULL rather than parent.

The function cvInsertNodeIntoTree adds another node into tree. The function does not allocate any memory, it can only modify links of the tree nodes.


RemoveNodeFromTree

Removes node from tree

void cvRemoveNodeFromTree( void* node, void* frame );

node
The removed node.
frame
The top level node. If node->v_prev = NULL and node->h_prev is NULL (i.e. if node is the first child of frame), frame->v_next is set to node->h_next (i.e. the first child or frame is changed).

The function cvRemoveNodeFromTree removes node from tree. The function does not deallocate any memory, it can only modify links of the tree nodes.


Persistence (Writing and Reading Structures)


OpenFileStorage

Opens existing or creates new file storage

CvFileStorage*  cvOpenFileStorage( const char* filename, CvMemStorage* memstorage, int flags );

filename
The storage file name.
memstorage
Memory storage used for storing temporary data and read dynamic structures. If it is NULL, the temporary memory storage is created and used.
flags
Can be one of the following:
CV_STORAGE_READ - the storage is open for reading
CV_STORAGE_WRITE_TEXT - the storage is open for writing data in text format
CV_STORAGE_WRITE_BINARY - the storage is open for writing data in XDR and base64-encoded binary format

The function cvOpenFileStorage open existing file storage or creates a new storage. The file has XML format and it allows user to store as standard OpenCV arrays and dynamic structures as well as custom data structures. The function returns pointer to CvFileStorage structure, which declaration is hidden, though not needed to access directly.


ReleaseFileStorage

Releases file storage

void  cvReleaseFileStorage( CvFileStorage** storage );

storage
Double pointer to the released file storage.

The function cvReleaseFileStorage closes the file on disk that has been written or read and releases all temporary structures. It must be called after all I/O operations with the storage are finished.


Write

Writes array or dynamic structure to the file storage

void  cvWrite( CvFileStorage* storage, const char* name,
               const void* structPtr,
               CvAttrList attributes=cvAttrList(),
               int flags=0 );

storage
File storage.
name
Name, or ID, of the written structure. It is used to index the written information and then access it using these ID's. If it is NULL or empty (""), no ID is written. If it has special value "<auto>", the address of the written structure in heximal notation will be used as the name.
structPtr
The written structure - CvMat*, IplImage*, CvSeq*, CvGraph* etc.
attributes
The list of attributes that can be formed from NULL-terminated array of <attr_name, attr_value> pairs using cvAttrList() function (see the example below). Most often it is just empty. The passed attributes override standard attributes with the same name, e.g. user may specify header_dt or dt attributes to write dynamic structures with custom headers and element types.
flags
The operation flags passed into the specific loading/storing function for the particular data type. Usually it is not used and may be set to 0. In case of contour trees (for details see cvFindContours function in Structural Analysis chapter of the reference) it may be set to CV_WRITE_TREE to force the whole contour tree to be written.

The function cvWrite writes a passed structure to OpenCV file storage. The sample below demonstrates how to write different types of data to storage.

/****************** Writing Data **************************/
#include <cv.h>

int main( int argc, char** argv )
{
    CvMemStorage* memstorage = cvCreateMemStorage(0);
    CvFileStorage* storage = cvOpenFileStorage( "sample.xml", 0, CV_STORAGE_WRITE_TEXT );
    CvMat* mat = cvCreateMat( 3, 3, CV_32FC1 );
    CvSeq* seq = cvCreateSeq( CV_32SC1, sizeof(CvSeq), sizeof(int), memstorage );
    char* seq_attr[] =
    {
    "created_by", argv[0],
    "the_sequence_creation_date", "1 Sep 2002",
    "comment", "just a comment",
    0
    };
    CvTermCriteria criteria = { CV_TERMCRIT_ITER|CV_TERMCRIT_EPS, 10, 0.1 };
    const char* string1 = "test";
    int i;

    cvSetIdentity( mat );
    cvWrite( storage, "The identity matrix", mat, cvAttrList(), 0 );

    for( i = 0; i < 10; i++ )
        cvSeqPush( seq, &i );

    cvWrite( storage, "SmallSequence", seq, cvAttrList(seq_attr,0), 0 );
    cvWriteElem( storage, "SampleStructure", "iid", &criteria ); /* writing C structure, see below */
    cvWriteElem( storage, "SampleString", "a", string1 ); /* writing C string, see below */

    cvReleaseFileStorage( &storage );
    cvReleaseMemStorage( &memstorage );
    return 0;
}
/**********************************************************/

After compiling and runnning the sample the file sample.xml will contain something like this:

<?xml version="1.0"?>
<opencv_storage>
<struct id="The identity matrix" type="CvMat" dt="f" size="3 3" format="text">
  1.000000e+000  0.000000e+000  0.000000e+000  0.000000e+000  1.000000e+000
  0.000000e+000  0.000000e+000  0.000000e+000  1.000000e+000
</struct>
<struct id="SmallSequence" type="CvSeq" flags="42990003" dt="i" format="text"
 created_by="D:\OpenCV\bin\test.exe" the_sequence_creation_date="1 Sep 2002"
 comment="just a comment">
      0      1      2      3      4      5      6      7      8      9
</struct>
<elem id="SampleStructure" dt="iid" value="      3     10  1.000000000000000e-001"/>
<elem id="SampleString" dt="a" value="test"/>
</opencv_storage>

StartWriteStruct

Writes the opening tag of a compound structure

void  cvStartWriteStruct( CvFileStorage* storage, const char* name,
                          const char* typeName=0, const void* structPtr=0,
                          CvAttrList attributes=cvAttrList());

storage
File storage.
name
Name, or ID, of the written structure. It is used to index the written information and then access it using these ID's. If it is NULL or empty (""), no ID is written. If it has special value "<auto>", the address of the written structure in heximal notation will be used as the name.
structPtr
The written structure pointer. It is not used unless name = "<auto>".
attributes
The list of attributes (the same as in the previous function)

The function cvStartWriteStruct writes the opening tag of a compound structure. It is used by cvWrite function and can be used explicitly to group some structures or write an writer for some custom data structure.


EndWriteStruct

Closes the last opened tag

void  cvEndWriteStruct( CvFileStorage* storage );

storage
File storage.

The function cvEndWriteStruct closes the most recent opened tag.


WriteElem

Writes a scalar variable

void  cvWriteElem( CvFileStorage* storage, const char* name,
                   const char* elem_spec, const void* data_ptr );

storage
File storage
name
Name, or ID, of the written scalar. As usual, "<auto>" means that the data pointer will be used as a name.
elem_spec
A sequence of character each of whose specifies a type of particualar field of the written structure:
data_ptr
Pointer to the written data. The written data can be a single value of one of basic numerical types (unsigned char, char, short, int, float or double), C structure containing one or more numerical fields or a character string. In case of C structures an ideal alignment must be used - short's must be aligned by 2 bytes, integer's and float's by 4 bytes and double's by 8 bytes. Usually such an alignment is used by C/C++ compiler by default, however some structures, e.g. BITMAPFILEHEADER Win32 structure break this rule. If you want to store such a structure, you may use sprintf( elem_spec, "%du", sizeof(my_struct)) to form an element spec that allows to store arbitrary structure, though the representation will neither be readable nor portable.

The function cvWriteElem writes a single numberical value, a structure of numerical values or a character string. Here are some examples (see cvWrite function discussion for complete sample):

CvScalar scalar = { 1., 2., 3.14, 4. };
cvWriteElem( filestorage, "scalar1", "4d", &scalar );

CvPoint pt = { 100, 50 };
cvWriteElem( filestorage, "feature_point", "2i", &pt };

struct
{
    char c;
    uchar u;
    short s;
    int i;
    float f;
    double d;
}
big_twos = { 20, 200, 20000, 2000000, 2e10, 2e100 };
cvWriteElem( filestorage, "big_twos", "cusifd", &big_twos );

cvWriteElem( filestorage, "string1", "a", "Hello, world!" };

Read

Reads array or dynamic structure from the file storage

void*  cvRead( CvFileStorage* storage, const char* name, CvAttrList** list=0 );

storage
File storage.
name
Name of the structure to read.
list
Optional output parameter that is filled with the node attributes list.

The function cvRead reads a structure with the specified name from OpenCV file storage. The structure is stored inside the file storage so it is be deallocated when the file storage is released, except the case when it is dynamic strucutre and non-NULL memory storage was passed to cvOpenFileStorage function. If you want to keep the sturcture, use cvClone*.


ReadElem

Reads a scalar variable

void  cvReadElem( CvFileStorage* storage, const char* name, void* data_ptr );

storage
File storage
name
Name of the variable to read.
data_ptr
Pointer to the destination structure. In case of strings, data_ptr should be char** - pointer to the string pointer that is filled by the function.

The function cvReadElem reads a single numberical value, a structure of numerical values or a character string. The order the variables are read in may be different from the order they are written. Here are examples - counterparts for examples from cvWriteElem discussion:

CvScalar scalar;
cvWriteElem( filestorage, "scalar1", &scalar );

CvPoint pt;
cvWriteElem( filestorage, "feature_point", &pt };

struct
{
    char c;
    uchar u;
    short s;
    int i;
    float f;
    double d;
}
big_twos;

cvReadElem( filestorage, "big_twos", &big_twos );

const char* string1 = 0;
cvReadElem( filestorage, "string1", (void*)&string1 };

CvFileNode

XML node representation

typedef struct CvFileNode
{
    int       flags;         /* micsellaneous flags */
    int       header_size;   /* size of node header */
    struct    node_type* h_prev; /* previous node having the same parent */
    struct    node_type* h_next; /* next node having the same parent */
    struct    node_type* v_prev; /* the parent node */
    struct    node_type* v_next; /* the first child node */
    const char* tagname; /* INTERNAL: XML tag name */
    const char* name; /* the node name */
    CvAttrList* attr; /* list of attributes */
    struct CvFileNode* hash_next; /* INTERNAL: next entry in hash table */
    unsigned hash_val; /* INTERNAL: hash value */
    int elem_size; /* size of a structure elements */
    struct CvTypeInfo* typeinfo; /* INTERNAL: type information */
    const char* body; /* INTERNAL: pointer to the structure or scalar content within XML file,
                         filled by XML parser */
    const void* content; /* the read structure, NULL if it is read yet */
}
CvFileNode;

The structure CvFileNode represents an XML node - building block of OpenCV file storage. The nodes are organized into tree that has a root node correponding to <opencv_storage> tag. When a file storage is written, the tree is constructed by cvWrite, cvStartWriteStruct, cvEndWriteStruct and cvWriteElem functions, and it does not to be accessed directly in most of cases. When the file storage is read, the whole tree is reconstructed by XML parser in cvOpenFileStorage function, but none of nodes are decoded. Instead, a particular node can be decoded via cvReadFileNode function, after its pointer is retrived by the node name using cvGetFileNode function or the node is reached from the root node. The functions cvInitTreeNodeIterator, cvNextTreeNode and cvPrevTreeNode can be used to traverse the XML tree. When the node is decoded, content field becomes valid and the same pointer will be returned by sebsequent calls to cvReadFileNode or cvRead for this node.


GetFileNode

Finds XML node by name

CvFileNode* cvGetFileNode( CvFileStorage* storage, const char* name );

storage
File storage.
name
The searched node name. If it is NULL, the root of the XML tree is returned.

The function cvGetFileNode locates XML node by name and returns pointer to the node or NULL if the node is not found.

.

ReadFileNode

Decodes XML node content

void* cvReadFileNode( CvFileStorage* storage, CvFileNode* node, CvAttrList** list=0 );

storage
File storage.
node
The node to decode.
list
Optional output parameter that is filled with the node attributes list.

The function cvReadFileNode decodes the file node content. If content field of the node is not NULL, no decoding is done and the pointer is simply returned.

.