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 );
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 );
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 );
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 );
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 );
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 );
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 );
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;
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;
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;
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:
alphaChannel is ignored by OpenCV.
colorModel and channelSeq are ignored by OpenCV. The single OpenCV function
cvCvtColor working with color spaces takes the source and destination color spaces
as a parameter.
dataOrder must be IPL_DATA_ORDER_PIXEL (the color channels are interleaved), however
selected channels of planar images can be processed as well if COI is set.
align is ignored by OpenCV, while widthStep is used to access to subsequent image rows.
maskROI is not supported. The function that can work with mask take it as a
separate parameter. Also the mask in OpenCV is 8-bit, whereas in IPL it is 1-bit.
tileInfo is not supported.
BorderMode and BorderConst are not supported. Every OpenCV function
working with a pixel neigborhood uses a single hard-coded border mode (most often, replication).
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.
Allocates memory buffer
void* cvAlloc( size_t size );
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.
Deallocates memory buffer
void cvFree( void** 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
Creates header and allocates data
IplImage* cvCreateImage( CvSize size, int depth, int channels );
The function cvCreateImage creates the header and allocates data. This call is a shortened form of
header = cvCreateImageHeader(size,depth,channels);
cvCreateData(header);
Allocates, initializes, and returns structure IplImage
IplImage* cvCreateImageHeader( CvSize size, int depth, int channels );
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)
Releases header
void cvReleaseImageHeader( IplImage** image );
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)
Releases header and image data
void cvReleaseImage( IplImage** image );
The function cvReleaseImage releases the header and the image data. This call is a shortened form of
if( *image )
{
cvReleaseData( *image );
cvReleaseImageHeader( image );
}
Initializes allocated by user image header
void cvInitImageHeader( IplImage* image, CvSize size, int depth,
int channels, int origin, int align );
The function cvInitImageHeader initializes the image header structure without memory allocation.
Makes a full copy of image
IplImage* cvCloneImage( const IplImage* image );
The function cvCloneImage makes a full copy of the image including header, ROI and data
Sets channel of interest to given value
void cvSetImageCOI( IplImage* image, int coi );
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.
Returns index of channel of interest
int cvGetImageCOI( const IplImage* image );
The function cvGetImageCOI returns channel of interest of the image (it returns 0 if all the channels are selected).
Sets image ROI to given rectangle
void cvSetImageROI( IplImage* image, CvRect rect );
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)
Releases image ROI
void cvResetImageROI( IplImage* image, CvRect rect );
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.
Returns image ROI coordinates
CvRect cvGetImageROI( const IplImage* image );
The function cvGetImageROI returns image ROI coordinates. The rectangle cvRect(0,0,image->width,image->height) is returned if there is no ROI
Creates new matrix
CvMat* cvCreateMat( int rows, int cols, int type );
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.
Creates new matrix header
CvMat* cvCreateMatHeader( int rows, int cols, int type );
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.
Deallocates matrix
void cvReleaseMat( CvMat** mat );
The function cvReleaseMat decrements the matrix data reference counter and releases matrix header:
if( *mat )
cvDecRefData( *mat );
cvFree( (void**)mat );
Initializes matrix header
void cvInitMatHeader( CvMat* mat, int rows, int cols, int type,
void* data=0, int step=CV_AUTOSTEP );
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
Initializes matrix header (light-weight variant)
CvMat cvMat( int rows, int cols, int type, void* data = 0 );
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 );
Creates matrix copy
CvMat* cvCloneMat( const CvMat* mat );
The function cvCloneMat creates a copy of input matrix and returns the pointer to it.
Creates multi-dimensional dense array
CvMatND* cvCreateMatND( int dims, int* size, int type );
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.
Creates new matrix header
CvMatND* cvCreateMatNDHeader( int dims, int* size, int type );
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.
Deallocates multi-dimensional array
void cvReleaseMatND( CvMatND** mat );
The function cvReleaseMatND decrements the array data reference counter and releases the array header:
if( *mat )
cvDecRefData( *mat );
cvFree( (void**)mat );
Initializes multi-dimensional array header
void cvInitMatNDHeader( CvMatND* mat, int dims, int* size, int type, void* data=0 );
The function cvInitMatNDHeader initializes already allocated CvMatND structure.
Creates full copy of multi-dimensional array
CvMatND* cvCloneMatND( const CvMatND* mat );
The function cvCloneMatND creates a copy of input array and returns pointer to it.
Decrements array data reference counter
void cvDecRefData( CvArr* array );
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.
Increments array data reference counter
int cvIncRefData( CvArr* array );
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.
Allocates array data
void cvCreateData( CvArr* array );
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
Releases array data
void cvReleaseData( CvArr* array );
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.
Assigns user data to the array header
void cvSetData( CvArr* array, void* data, int step );
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.
Retrieves low-level information about the array
void cvGetRawData( const CvArr* array, uchar** data,
int* step, CvSize* roiSize );
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]);
Returns matrix header for arbitrary array
CvMat* cvGetMat( const CvArr* arr, CvMat* mat, int* coi = 0, int allowND );
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.Returns image header for arbitrary array
IplImage* cvGetImage( const CvArr* arr, IplImage* image_header );
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.
Returns matrix header corresponding to the rectangular sub-array of input image or matrix
CvMat* cvGetSubRect( const CvArr* array, CvMat* subarr, CvRect rect );
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.
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 );
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 );
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 );
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 );
Returns one of array diagonals
CvMat* cvGetDiag( const CvArr* arr, CvMat* subarr, int diag=0 );
The function cvGetDiag returns the header, corresponding to a specified diagonal of the input array.
Returns size of matrix or image ROI
CvSize cvGetSize( const CvArr* arr );
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.
Creates sparse array
CvSparseMat* cvCreateSparseMat( int dims, int* size, int type );
The function cvCreateSparseMat allocates multi-dimensional sparse array. Initially the array contain no elements, that is cvGet*D will return zero for every index
Deallocates sparse array
void cvReleaseSparseMat( CvSparseMat** mat );
The function cvReleaseSparseMat releases the sparse array and clears the array pointer upon exit
Creates full copy of sparse array
CvSparseMat* cvCloneSparseMat( const CvSparseMat* mat );
The function cvCloneSparseMat creates a copy of the input array and returns pointer to the copy.
Initializes sparse array elements iterator
CvSparseMat* cvInitSparseMatIterator( const CvSparseMat* mat, CvSparseMatIterator* matIterator );
The function cvInitSparseMatIterator initializes iterator of sparse array elements and returns pointer to the first element, or NULL if the array is empty.
Initializes sparse array elements iterator
CvSparseMat* cvGetNextSparseNode( CvSparseMatIterator* matIterator );
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 );
Returns type of array elements
int cvGetElemType( const CvArr* arr );
The functions GetElemType returns type of the array elements as it is described in cvCreateMat discussion:
CV_8UC1 ... CV_64FC4
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 );
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 );
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 );
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.
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 );
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)
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 );
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)
Return the particular element of single-channel floating-point matrix
double cvmGet( const CvMat* mat, int row, int col );
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.
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 );
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
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 );
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
Return the particular element of single-channel floating-point matrix
void cvmSet( CvMat* mat, int row, int col, double value );
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.
Clears the particular array element
void cvClearND( CvArr* arr, int* idx );
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.
Copies one array to another
void cvCopy( const CvArr* A, CvArr* B, const CvArr* mask =0);
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).
Sets every element of array to given value
void cvSet( CvArr* A, CvScalar S, const CvArr* mask=0 );
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.
Clears the array
void cvSetZero( CvArr* arr ); #define cvZero cvSetZero
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
Changes shape of matrix/image without copying data
CvMat* cvReshape( const CvArr* array, CvMat* header, int new_cn, int new_rows=0 );
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 );
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))
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 );
Fill destination array with tiled source array
void cvRepeat( const CvArr* A, CvArr* B );
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 a 2D array around vertical, horizontall or both axises
void cvFlip( const CvArr* A, CvArr* B=0, int flip_mode=0); #define cvMirror cvFlip
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:
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 );
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.
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 );
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.
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 )
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.
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
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.
Computes per-element sum of two arrays
void cvAdd( const CvArr* A, const CvArr* B, CvArr* C, const CvArr* mask=0);
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)
Computes sum of array and scalar
void cvAddS( const CvArr* A, CvScalar S, CvArr* C, const CvArr* mask=0 );
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)
Computes per-element difference of two arrays
void cvSub( const CvArr* A, const CvArr* B, CvArr* C, const CvArr* mask=0);
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)
Computes difference of array and scalar
void cvSubS( const CvArr* A, CvScalar S, CvArr* C, const CvArr* mask=0 );
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)
Computes difference of scalar and array
void cvSubRS( const CvArr* A, CvScalar S, CvArr* C, const CvArr* mask=0 );
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)
Calculates per-element product of two arrays
void cvMul( const CvArr* A, const CvArr* B, CvArr* C, double scale=1 );
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)
Performs per-element division of two arrays
void cvDiv( const CvArr* A, const CvArr* B, CvArr* C, double scale=1 );
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)
Calculates per-element bit-wise conjunction of two arrays
void cvAnd( const CvArr* A, const CvArr* B, CvArr* C, const CvArr* mask=0 );
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
Calculates per-element bit-wise conjunction of array and scalar
void cvAndS( const CvArr* A, CvScalar S, CvArr* C, const CvArr* mask=0 );
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
Calculates per-element bit-wise disjunction of two arrays
void cvOr( const CvArr* A, const CvArr* B, CvArr* C, const CvArr* mask=0 );
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
Calculates per-element bit-wise disjunction of array and scalar
void cvOrS( const CvArr* A, CvScalar S, CvArr* C, const CvArr* mask=0 );
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
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 );
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
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 );
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)
Performs per-element bit-wise inversion of array elements
void cvNot( const CvArr* A, CvArr* C );
The function Not inverses every bit of every array element:
C(I)=~A(I)
Performs per-element comparison of two arrays
void cvCmp( const CvArr* A, const CvArr* B, CvArr* C, int cmp_op );
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)
Performs per-element comparison of array and scalar
void cvCmpS( const CvArr* A, double S, CvArr* C, int cmp_op );
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)
Checks that array elements lie between elements of two other arrays
void cvInRange( const CvArr* A, const CvArr* L, const CvArr* U, CvArr* C );
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)
Checks that array elements lie between two scalars
void cvInRangeS( const CvArr* A, CvScalar SL, CvScalar SU, CvArr* D );
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)
Finds per-element maximum of two arrays
void cvMax( const CvArr* A, const CvArr* B, CvArr* C );
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).
Finds per-element maximum of array and scalar
void cvMaxS( const CvArr* A, const CvArr* B, CvArr* C );
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).
Finds per-element minimum of two arrays
void cvMin( const CvArr* A, const CvArr* B, CvArr* C );
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).
Finds per-element minimum of array and scalar
void cvMinS( const CvArr* A, const CvArr* B, CvArr* C );
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).
Calculates absolute difference between two arrays
void cvAbsDiff( const CvArr* A, const CvArr* B, CvArr* C );
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).
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))
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).
Counts non-zero array elements
int cvCountNonZero( const CvArr* A );
The function cvCountNonZero returns the number of non-zero elements in A:
result = sumI A(I)!=0In case of IplImage both ROI and COI are supported.
Summarizes array elements
CvScalar cvSum( const CvArr* A );
The function cvSum calculates sum S of array elements, independently for each channel:
Sc = sumI A(I)cIf 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).
Calculates average (mean) of array elements
CvScalar cvAvg( const CvArr* A, const CvArr* mask=0 );
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)cIf 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).
Calculates average (mean) of array elements
void cvAvgSdv( const CvArr* A, CvScalar* _M, CvScalar* _S, const CvArr* mask=0 );
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).
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 );
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.
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 );
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.
Initializes scaled identity matrix
void cvSetIdenity( CvArr* A, CvScalar S );
The function cvSetIdentity initializes scaled identity matrix:
A(i,j)=S if i=j,
0 otherwise
Calculates dot product of two arrays in Euclidian metrics
double cvDotProduct (const CvArr* A, const CvArr* B );
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.
Calculates cross product of two 3D vectors
void cvCrossProduct( const CvArr* A, const CvArr* B, CvArr* C );
The function cvCrossProduct calculates the cross product of two 3D vectors:
C = A×B, (C1 = A2B3 - A3B2 , C2 = A3B1 - A1B3 , C3 = A1B2 - A2B1).
Calculates sum of scaled array and another array
void cvScaleAdd( const CvArr* A, CvScalar S, const CvArr* B, CvArr* C ); #define cvMulAddS cvScaleAdd
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
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)
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
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
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
Performs matrix transform on every element of array
void cvMatMulAddS( const CvArr* A, CvArr* C, const CvArr* M, const CvArr* V=0 );
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.
Calculates product of array and transposed array
void cvMulTransposed( const CvArr* A, CvArr* C, int order );
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
Returns trace of matrix
CvScalar cvTrace( const CvArr* A );
The function cvTrace returns sum of diagonal elements of the matrix A.
tr(A)=sumiA(i,i)
Transposes matrix
void cvTranspose( const CvArr* A, CvArr* B ); #define cvT cvTranspose
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
Returns determinant of matrix
CvScalar cvDet( const CvArr* A );
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
Finds inverse or pseudo-inverse of matrix
double cvInvert( const CvArr* A, CvArr* B, int method ); #define cvInv cvInvert
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
Solves linear system or least-squares problem
int cvSolve( const CvArr* A, const CvArr* B, CvArr* X, int method ); #define cvInv cvSolve
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
Performs singular value decomposition of real floating-point matrix
void cvSVD( CvArr* A, CvArr* W, CvArr* U=0, CvArr* V=0, int flags=0 );
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:
Performs singular value back substitution
void cvSVBkSb( const CvArr* W, const CvArr* U, const CvArr* V,
const CvArr* B, CvArr* X, int flags );
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).Computes eigenvalues and eigenvectors of symmetric matrix
void cvEigenVV( CvArr* A, CvArr* evects, CvArr* evals, double eps );
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.
Performs perspective matrix transform on 3D vector array
void cvPerspectiveTransform( const CvArr* A, CvArr* B, const CvArr* M );
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
Calculates covariation matrix out of the set of arrays
void cvCalcCovarMatrix( CvArr** Vs, CvArr* M, CvArr* A );
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.
Calculates Mahalonobis distance between vectors
double cvMahalonobis( const CvArr* A, const CvArr* B, CvArr* T );
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).
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 );
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.
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 );
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))
Raises every array element to power
void cvPow( const CvArr* X, CvArr* Y, double p );
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.
Calculates exponent of every array element
void cvExp( const CvArr* X, CvArr* Y );
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.
Calculates natural logarithm of every array element absolute value
void cvLog( const CvArr* X, CvArr* Y );
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)=0Where C is large negative number (≈-700 in the current implementation)
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
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.
Initializes random number generator state
void cvRandInit( CvRandState* state, double param1, double param2, int seed,
int distType=CV_RAND_UNI );
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.
Changes the range of generated random numbers without touching RNG state
void cvRandSetRange( CvRandState* state, double param1, double param2, int index=-1 );
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.
Fills array with random numbers and updates the RNG state
void cvRand( CvRandState* state, CvArr* arr );
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 */
Returns 32-bit unsigned integer and updates RNG
unsigned cvRandNext( CvRandState* state );
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 */
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 );
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
Performs per-element multiplication of two Fourier spectrums of two real arrays
void cvMulCss( const CvArr* srcA, const CvArr* srcB, CvArr* dst );
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.
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 );
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
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.
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.
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.
Creates memory storage
CvMemStorage* cvCreateMemStorage( int blockSize=0 );
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.
Creates child memory storage
CvMemStorage* cvCreateChildMemStorage( CvMemStorage* parent );
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
Releases memory storage
void cvReleaseMemStorage( CvMemStorage** 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.
Clears memory storage
void cvClearMemStorage( CvMemStorage* 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.
Allocates memory buffer in the storage
void* cvMemStorageAlloc( CvMemStorage* storage, int 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.
Saves memory storage position
void cvSaveMemStoragePos( const CvMemStorage* storage, CvMemStoragePos* pos );
The function cvSaveMemStoragePos saves the current position of the storage top to the parameter pos. The function cvRestoreMemStoragePos can further retrieve this position.
Restores memory storage position
void cvRestoreMemStoragePos( CvMemStorage* storage, CvMemStoragePos* pos );
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.
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.
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.
Creates sequence
CvSeq* cvCreateSeq( int seqFlags, int headerSize,
int elemSize, CvMemStorage* storage );
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).
Sets up sequence block size
void cvSetSeqBlockSize( CvSeq* seq, int blockSize );
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.
Adds element to sequence end
char* cvSeqPush( CvSeq* seq, void* element=0 );
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).
Removes element from sequence end
void cvSeqPop( CvSeq* seq, void* element=0 );
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.
Adds element to sequence beginning
char* cvSeqPushFront( CvSeq* seq, void* element=0 );
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.
Removes element from sequence beginning
void cvSeqPopFront( CvSeq* seq, void* element=0 );
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.
Pushes several elements to the either end of sequence
void cvSeqPushMulti( CvSeq* seq, void* elements, int count, int in_front=0 );
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.
Removes several elements from the either end of sequence
void cvSeqPopMulti( CvSeq* seq, void* elements, int count, int in_front=0 );
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.
Inserts element in sequence middle
char* cvSeqInsert( CvSeq* seq, int beforeIndex, void* element=0 );
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.
Removes element from sequence middle
void cvSeqRemove( CvSeq* seq, int index );
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.
Clears sequence
void cvClearSeq( CvSeq* seq );
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).
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 )
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.
Returns index of concrete sequence element
int cvSeqElemIdx( CvSeq* seq, void* element, CvSeqBlock** block=0 );
The function cvSeqElemIdx returns the index of a sequence element or a negative number if the element is not found.
Copies sequence to one continuous block of memory
void* cvCvtSeqToArray( CvSeq* seq, void* array, CvSlice slice=CV_WHOLE_SEQ );
The function cvCvtSeqToArray copies the entire sequence or subsequence to the specified buffer and returns the pointer to the buffer.
Constructs sequence from array
void cvMakeSeqHeaderForArray( int seqType, int headerSize, int elemSize,
void* array, int total,
CvSeq* sequence, CvSeqBlock* 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.
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)
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
Removes sequence slice
void cvSeqRemoveSlice( CvSeq* seq, CvSlice slice );
The function cvSeqRemoveSlice removes slice from the sequence.
Inserts array in the middle of sequence
void cvSeqInsertSlice( CvSeq* seq, int beforeIndex, const CvArr* fromArr );
The function cvSeqInsertSlice inserts all fromArr array elements at the specified position of the sequence. The array may be matrix or another sequence.
Reverses the order of sequence elements
void cvSeqInvert( CvSeq* seq );
The function cvSeqInvert reverses the sequence in-place - makes the first element go last, the last element go first etc.
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 );
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 );
Initializes process of writing to sequence
void cvStartAppendToSeq( CvSeq* seq, CvSeqWriter* writer );
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).
Creates new sequence and initializes writer for it
void cvStartWriteSeq( int seqFlags, int headerSize, int elemSize,
CvMemStorage* storage, CvSeqWriter* writer );
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.
Finishes process of writing sequence
CvSeq* cvEndWriteSeq( CvSeqWriter* writer );
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.
Updates sequence headers from the writer state
void cvFlushSeqWriter( CvSeqWriter* writer );
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.
Initializes process of sequential reading from sequence
void cvStartReadSeq( CvSeq* seq, CvSeqReader* reader, int reverse=0 );
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 );
Returns the current reader position
int cvGetSeqReaderPos( CvSeqReader* reader );
The function cvGetSeqReaderPos returns the current reader position (within 0 ... reader->seq->total - 1).
Moves the reader to specified position
void cvSetSeqReaderPos( CvSeqReader* reader, int index, int is_relative=0 );
The function cvSetSeqReaderPos moves the read position to the absolute position or relative to the current position.
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.
Creates empty set
CvSet* cvCreateSet( int setFlags, int headerSize,
int elemSize, CvMemStorage* storage );
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.
Occupies a node in the set
int cvSetAdd( CvSet* set, void* elem, void** insertedElem=0 );
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).
Removes element from set
void cvSetRemove( CvSet* set, int index );
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.
Adds element to set (fast variant)
CvSetElem* cvSetNew( CvSet* set );
The function cvSetNew is inline light-weight variant of cvSetAdd. It occupies a new node and returns pointer to it rather than index.
Removes set element given its pointer
void cvSetRemoveByPtr( CvSet* set, void* elem );
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.
Finds set element by its index
CvSetElem* cvGetSetElem( CvSet* set, int index );
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.
Clears set
void cvClearSet( CvSet* set );
The function cvClearSet removes all elements from set. It has O(1) time complexity.
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..
Creates empty graph
CvGraph* cvCreateGraph( int graphFlags, int headerSize, int vertexSize,
int edgeSize, CvStorage* storage );
The function cvCreateGraph creates an empty graph and returns pointer to it.
Adds vertex to graph
int cvGraphAddVtx( CvGraph* graph, CvGraphVtx* vtx,
CvGraphVtx** insertedVtx=0 );
The function cvGraphAddVtx adds a vertex to the graph and returns the vertex index.
Removes vertex from graph
void cvGraphRemoveVtx( CvGraph* graph, int vtxIdx );
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.
Removes vertex from graph
void cvGraphRemoveVtxByPtr( CvGraph* graph, CvGraphVtx* vtx );
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.
Finds graph vertex by index
CvGraphVtx* cvGetGraphVtx( CvGraph* graph, int vtxIdx );
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.
Returns index of graph vertex
int cvGraphVtxIdx( CvGraph* graph, CvGraphVtx* vtx );
The function cvGraphVtxIdx returns index of the graph vertex.
Adds edge to graph
int cvGraphAddEdge( CvGraph* graph, int startIdx, int endIdx,
CvGraphEdge* edge, CvGraphEdge** insertedEdge=0 );
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.
Adds edge to graph
int cvGraphAddEdgeByPtr( CvGraph* graph, CvGraphVtx* startVtx, CvGraphVtx* endVtx,
CvGraphEdge* edge, CvGraphEdge** insertedEdge=0 );
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.
Removes edge from graph
void cvGraphRemoveEdge( CvGraph* graph, int startIdx, int endIdx );
The function cvGraphRemoveEdge removes the edge connecting two specified vertices. If the vertices are not connected [in that order], the function does nothing.
Removes edge from graph
void cvGraphRemoveEdgeByPtr( CvGraph* graph, CvGraphVtx* startVtx, CvGraphVtx* endVtx );
The function cvGraphRemoveEdgeByPtr removes the edge connecting two specified vertices. If the vertices are not connected [in that order], the function does nothing.
Finds edge in graph
CvGraphEdge* cvFindGraphEdge( CvGraph* graph, int startIdx, int endIdx ); #define cvGraphFindEdge cvFindGraphEdge
The function cvFindGraphEdge finds the graph edge connecting two specified vertices and returns pointer to it or NULL if the edge does not exists.
Finds edge in graph
CvGraphEdge* cvFindGraphEdgeByPtr( CvGraph* graph, CvGraphVtx* startVtx, CvGraphVtx* endVtx ); #define cvGraphFindEdgeByPtr cvFindGraphEdgeByPtr
The function cvFindGraphEdge finds the graph edge connecting two specified vertices and returns pointer to it or NULL if the edge does not exists.
Returns index of graph edge
int cvGraphEdgeIdx( CvGraph* graph, CvGraphEdge* edge );
The function cvGraphEdgeIdx returns index of the graph edge.
Counts edges indicent to the vertex
int cvGraphVtxDegree( CvGraph* graph, int vtxIdx );
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.
Finds edge in graph
int cvGraphVtxDegreeByPtr( CvGraph* graph, CvGraphVtx* vtx );
The function cvGraphVtxDegree returns the number of edges incident to the specified vertex, both incoming and outcoming.
Clears graph
void cvClearGraph( CvGraph* graph );
The function cvClearGraph removes all vertices and edges from the graph. The function has O(1) time complexity.
Clone graph
CvGraph* cvCloneGraph( const CvGraph* graph, CvMemStorage* storage );
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.
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.
Initializes graph traverser state
void cvStartScanGraph( CvGraph* graph, CvGraphScanner* scanner,
CvGraphVtx* vtx=0, int mask=CV_GRAPH_ALL_ITEMS );
The function cvStartScanGraph initializes graph traverser state. The initialized structure is used in cvNextGraphItem function - the incremental traversal procedure.
Makes one or more steps of the graph traversal procedure
int cvNextGraphItem( CvGraphScanner* scanner );
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.
Finishes graph traversal procedure
void cvEndScanGraph( CvGraphScanner* scanner );
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
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.
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.
Initializes tree node iterator
void cvInitTreeNodeIterator( CvTreeNodeIterator* treeIterator,
const void* first, int maxLevel );
The function cvInitTreeNodeIterator initializes tree iterator. The tree is traversed in depth-first order.
Returns the currently observed node and moves iterator toward the next node
void* cvNextTreeNode( CvTreeNodeIterator* treeIterator );
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.
Returns the currently observed node and moves iterator toward the previous node
void* cvPrevTreeNode( CvTreeNodeIterator* treeIterator );
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.
Gathers all node pointers to the single sequence
CvSeq* cvTreeToNodeSeq( const void* first, int header_size, CvMemStorage* storage );
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.
Adds new node to the tree
void cvInsertNodeIntoTree( void* node, void* parent, void* frame );
The function cvInsertNodeIntoTree adds another node into tree. The function does not allocate any memory, it can only modify links of the tree nodes.
Removes node from tree
void cvRemoveNodeFromTree( void* node, void* frame );
The function cvRemoveNodeFromTree removes node from tree. The function does not deallocate any memory, it can only modify links of the tree nodes.
Opens existing or creates new file storage
CvFileStorage* cvOpenFileStorage( const char* filename, CvMemStorage* memstorage, int flags );
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.
Releases file storage
void cvReleaseFileStorage( CvFileStorage** 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.
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 );
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>
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());
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.
Closes the last opened tag
void cvEndWriteStruct( CvFileStorage* storage );
The function cvEndWriteStruct closes the most recent opened tag.
Writes a scalar variable
void cvWriteElem( CvFileStorage* storage, const char* name,
const char* elem_spec, const void* data_ptr );
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!" };
Reads array or dynamic structure from the file storage
void* cvRead( CvFileStorage* storage, const char* name, CvAttrList** list=0 );
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*.
Reads a scalar variable
void cvReadElem( CvFileStorage* storage, const char* name, void* data_ptr );
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 };
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.
Finds XML node by name
CvFileNode* cvGetFileNode( CvFileStorage* storage, const char* name );
The function cvGetFileNode locates XML node by name and returns pointer to the node or NULL if the node is not found.
.Decodes XML node content
void* cvReadFileNode( CvFileStorage* storage, CvFileNode* node, CvAttrList** list=0 );
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.
.