Quick Links : Main Page - CxCore - CvReference - CvAux - HighGui - FAQ
CXCORE Reference Manual
Table of Contents
Contents
Basic Structures
CvPoint
2D point with integer coordinates
typedef struct CvPoint
{
int x; /* x-coordinate, usually zero-based */
int y; /* y-coordinate, usually zero-based */
}
CvPoint;
/* the constructor function */
inline CvPoint cvPoint( int x, int y );
/* conversion from CvPoint2D32f */
inline CvPoint cvPointFrom32f( CvPoint2D32f point );
CvPoint2D32f
2D point with floating-point coordinates
typedef struct CvPoint2D32f
{
float x; /* x-coordinate, usually zero-based */
float y; /* y-coordinate, usually zero-based */
}
CvPoint2D32f;
/* the constructor function */
inline CvPoint2D32f cvPoint2D32f( double x, double y );
/* conversion from CvPoint */
inline CvPoint2D32f cvPointTo32f( CvPoint point );
CvPoint3D32f
3D point with floating-point coordinates
typedef struct CvPoint3D32f
{
float x; /* x-coordinate, usually zero-based */
float y; /* y-coordinate, usually zero-based */
float z; /* z-coordinate, usually zero-based */
}
CvPoint3D32f;
/* the constructor function */
inline CvPoint3D32f cvPoint3D32f( double x, double y, double z );
CvPoint2D64f
2D point with double precision floating-point coordinates
typedef struct CvPoint2D64f
{
double x; /* x-coordinate, usually zero-based */
double y; /* y-coordinate, usually zero-based */
}
CvPoint2D64f;
/* the constructor function */
inline CvPoint2D64f cvPoint2D64f( double x, double y );
/* conversion from CvPoint */
inline CvPoint2D64f cvPointTo64f( CvPoint point );
CvPoint3D64f
3D point with double precision floating-point coordinates
typedef struct CvPoint3D64f
{
double x; /* x-coordinate, usually zero-based */
double y; /* y-coordinate, usually zero-based */
double z; /* z-coordinate, usually zero-based */
}
CvPoint3D64f;
/* the constructor function */
inline CvPoint3D64f cvPoint3D64f( double x, double y, double z );
CvSize
pixel-accurate size of a rectangle
typedef struct CvSize
{
int width; /* width of the rectangle */
int height; /* height of the rectangle */
}
CvSize;
/* the constructor function */
inline CvSize cvSize( int width, int height );
CvSize2D32f
sub-pixel accurate size of a rectangle
typedef struct CvSize2D32f
{
float width; /* width of the box */
float height; /* height of the box */
}
CvSize2D32f;
/* the constructor function */
inline CvSize2D32f cvSize2D32f( double width, double height );
CvRect
offset and size of a rectangle
typedef struct CvRect
{
int x; /* x-coordinate of the left-most rectangle corner[s] */
int y; /* y-coordinate of the top-most or bottom-most
rectangle corner[s] */
int width; /* width of the rectangle */
int height; /* height of the rectangle */
}
CvRect;
/* the constructor function */
inline CvRect cvRect( int x, int y, int width, int height );
CvScalar
A container for 1-,2-,3- or 4-tuples of numbers
typedef struct CvScalar
{
double val[4];
}
CvScalar;
/* the constructor function: initializes val[0] with val0, val[1] with val1 etc. */
inline CvScalar cvScalar( double val0, double val1=0,
double val2=0, double val3=0 );
/* the constructor function: initializes val[0]...val[3] with val0123 */
inline CvScalar cvScalarAll( double val0123 );
/* the constructor function: initializes val[0] with val0, val[1]...val[3] with zeros */
inline CvScalar cvRealScalar( double val0 );
CvTermCriteria
Termination criteria for iterative algorithms
#define CV_TERMCRIT_ITER 1
#define CV_TERMCRIT_NUMBER CV_TERMCRIT_ITER
#define CV_TERMCRIT_EPS 2
typedef struct CvTermCriteria
{
int type; /* a combination of CV_TERMCRIT_ITER and CV_TERMCRIT_EPS */
int max_iter; /* maximum number of iterations */
double epsilon; /* accuracy to achieve */
}
CvTermCriteria;
/* the constructor function */
inline CvTermCriteria cvTermCriteria( int type, int max_iter, double epsilon );
/* check termination criteria and transform it so that type=CV_TERMCRIT_ITER+CV_TERMCRIT_EPS,
and both max_iter and epsilon are valid */
CvTermCriteria cvCheckTermCriteria( CvTermCriteria criteria,
double default_eps,
int default_max_iters );<!-- *****************************************************************************************
- ****************************************************************************************
**************************************************************************************** --> <!-- <hr><h2><a name="ch1_array_structs">Array structures</a></h2> -->
CvMat
Multi-channel matrix
typedef struct CvMat
{
int type; /* CvMat signature (CV_MAT_MAGIC_VAL), element type and flags */
int step; /* full row length in bytes */
int* refcount; /* underlying data reference counter */
union
{
uchar* ptr;
short* s;
int* i;
float* fl;
double* db;
} data; /* data pointers */
#ifdef __cplusplus
union
{
int rows;
int height;
};
union
{
int cols;
int width;
};
#else
int rows; /* number of rows */
int cols; /* number of columns */
#endif
} CvMat;
CvMatND
Multi-dimensional dense multi-channel array
typedef struct CvMatND
{
int type; /* CvMatND signature (CV_MATND_MAGIC_VAL), element type and flags */
int dims; /* number of array dimensions */
int* refcount; /* underlying data reference counter */
union
{
uchar* ptr;
short* s;
int* i;
float* fl;
double* db;
} data; /* data pointers */
/* pairs (number of elements, distance between elements in bytes) for
every dimension */
struct
{
int size;
int step;
}
dim[CV_MAX_DIM];
} CvMatND;
CvSparseMat
Multi-dimensional sparse multi-channel array
typedef struct CvSparseMat
{
int type; /* CvSparseMat signature (CV_SPARSE_MAT_MAGIC_VAL), element type and flags */
int dims; /* number of dimensions */
int* refcount; /* reference counter - not used */
struct CvSet* heap; /* a pool of hashtable nodes */
void** hashtable; /* hashtable: each entry has a list of nodes
having the same "hashvalue modulo hashsize" */
int hashsize; /* size of hashtable */
int total; /* total number of sparse array nodes */
int valoffset; /* value offset in bytes for the array nodes */
int idxoffset; /* index offset in bytes for the array nodes */
int size[CV_MAX_DIM]; /* arr of dimension sizes */
} CvSparseMat;
IplImage
IPL image header
typedef struct _IplImage
{
int nSize; /* sizeof(IplImage) */
int ID; /* version (=0)*/
int nChannels; /* Most of OpenCV functions support 1,2,3 or 4 channels */
int alphaChannel; /* ignored by OpenCV */
int depth; /* pixel depth in bits: IPL_DEPTH_8U, IPL_DEPTH_8S, IPL_DEPTH_16U,
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 a subset of 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).
Besides the above restrictions, OpenCV handles ROI differently. It requires that the sizes or ROI sizes of all source and destination images match exactly (according to the operation, e.g. for cvPyrDown destination width(height) must be equal to source width(height) divided by 2 ±1), whereas IPL processes the intersection area - that is, the sizes or ROI sizes of all images may vary independently.
CvArr
Arbitrary array
typedef void CvArr;
The metatype CvArr* is used only as a function parameter to specify that the function accepts arrays of more than a single type, for example IplImage*, CvMat* or even CvSeq*. The particular array type is determined at runtime by analyzing the first 4 bytes of the header.
<!-- *****************************************************************************************
- ****************************************************************************************
**************************************************************************************** -->
Operations on Arrays
Initialization
CreateImage
Creates header and allocates data
IplImage* cvCreateImage( CvSize size, int depth, int channels );
size:: Image width and height.depth:: Bit depth of image elements. Can be one of:
IPL_DEPTH_8U - unsigned 8-bit integers
IPL_DEPTH_8S - signed 8-bit integers
IPL_DEPTH_16U - unsigned 16-bit integers
IPL_DEPTH_16S - signed 16-bit integers
IPL_DEPTH_32S - signed 32-bit integers
IPL_DEPTH_32F - single precision floating-point numbers
IPL_DEPTH_64F - double precision floating-point numbers
channels:: Number of channels per element(pixel). Can be 1, 2, 3 or 4. The channels are interleaved, for example the usual data layout of a color image is:
b0 g0 r0 b1 g1 r1 ...
Although in general IPL image format can store non-interleaved images as well and some of OpenCV can process it, this function can create interleaved images only.
The function cvCreateImage creates the header and allocates data. This call is a shortened form of
header = cvCreateImageHeader(size,depth,channels); cvCreateData(header);
CreateImageHeader
Allocates, initializes, and returns structure IplImage
IplImage* cvCreateImageHeader( CvSize size, int depth, int channels );
size:: Image width and height.depth:: Image depth (see CreateImage).channels:: Number of channels (see CreateImage).
The function cvCreateImageHeader allocates, initializes, and returns the structure IplImage. This call is an analogue of
iplCreateImageHeader( channels, 0, depth,
channels == 1 ? "GRAY" : "RGB",
channels == 1 ? "GRAY" : channels == 3 ? "BGR" :
channels == 4 ? "BGRA" : "",
IPL_DATA_ORDER_PIXEL, IPL_ORIGIN_TL, 4,
size.width, size.height,
0,0,0,0);though it does not use IPL functions by default (see also CV_TURN_ON_IPL_COMPATIBILITY macro)
ReleaseImageHeader
Releases header
void cvReleaseImageHeader( IplImage** image );
image:: Double pointer to the deallocated header.
The function cvReleaseImageHeader releases the header. This call is an analogue of
if( image )
{
iplDeallocate( *image, IPL_IMAGE_HEADER | IPL_IMAGE_ROI );
*image = 0;
}though it does not use IPL functions by default (see also CV_TURN_ON_IPL_COMPATIBILITY)
ReleaseImage
Releases header and image data
void cvReleaseImage( IplImage** image );
image:: Double pointer to the header of the deallocated image.
The function cvReleaseImage releases the header and the image data. This call is a shortened form of
if( *image )
{
cvReleaseData( *image );
cvReleaseImageHeader( image );
}
InitImageHeader
Initializes allocated by user image header
IplImage* cvInitImageHeader( IplImage* image, CvSize size, int depth,
int channels, int origin=0, int align=4 );image:: Image header to initialize.size:: Image width and height.depth:: Image depth (see CreateImage).channels:: Number of channels (see CreateImage).origin:: IPL_ORIGIN_TL or IPL_ORIGIN_BL.align:: Alignment for image rows, typically 4 or 8 bytes.
The function cvInitImageHeader initializes the image header structure, pointer to which is passed by the user, and returns the pointer.
CloneImage
Makes a full copy of image
IplImage* cvCloneImage( const IplImage* image );
image:: Original image.
The function cvCloneImage makes a full copy of the image including header, ROI and data
SetImageCOI
Sets channel of interest to given value
void cvSetImageCOI( IplImage* image, int coi );
image:: Image header.coi:: Channel of interest.
The function cvSetImageCOI sets the channel of interest to a given value. Value 0 means that all channels are selected, 1 means that the first channel is selected etc. If ROI is NULL and coi != 0, ROI is allocated. Note that most of OpenCV functions do not support COI, so to process separate image/matrix channel one may copy (via cvCopy or cvSplit) the channel to separate image/matrix, process it and copy the result back (via cvCopy or cvCvtPlaneToPix) if need.
GetImageCOI
Returns index of channel of interest
int cvGetImageCOI( const IplImage* image );
image:: Image header.
The function cvGetImageCOI returns channel of interest of the image (it returns 0 if all the channels are selected).
SetImageROI
Sets image ROI to given rectangle
void cvSetImageROI( IplImage* image, CvRect rect );
image:: Image header.rect:: ROI rectangle.
The function cvSetImageROI sets the image ROI to a given rectangle. If ROI is NULL and the value of the parameter rect is not equal to the whole image, ROI is allocated. Unlike COI, most of OpenCV functions do support ROI and treat it in a way as it would be a separate image (for example, all the pixel coordinates are counted from top-left or bottom-left (depending on the image origin) corner of ROI)
ResetImageROI
Releases image ROI
void cvResetImageROI( IplImage* image );
image:: Image header.
The function cvResetImageROI releases image ROI. After that the whole image is considered selected. The similar result can be achieved by
cvSetImageROI( image, cvRect( 0, 0, image->width, image->height )); cvSetImageCOI( image, 0 );
But the latter variant does not deallocate image->roi.
GetImageROI
Returns image ROI coordinates
CvRect cvGetImageROI( const IplImage* image );
image:: Image header.
The function cvGetImageROI returns image ROI coordinates. The rectangle cvRect(0,0,image->width,image->height) is returned if there is no ROI
CreateMat
Creates new matrix
CvMat* cvCreateMat( int rows, int cols, int type );
rows:: Number of rows in the matrix.cols:: Number of columns in the matrix.type:: Type of the matrix elements. Usually it is specified in form CV_<bit_depth>(S|U|F)C<number_of_channels>, for example:
CV_8UC1 means an 8-bit unsigned single-channel matrix, CV_32SC2 means a 32-bit signed matrix with two channels.
The function cvCreateMat allocates header for the new matrix and underlying data, and returns a pointer to the created matrix. It is a short form for:
CvMat* mat = cvCreateMatHeader( rows, cols, type ); cvCreateData( mat );
Matrices are stored row by row. All the rows are aligned by 4 bytes.
CreateMatHeader
Creates new matrix header
CvMat* cvCreateMatHeader( int rows, int cols, int type );
rows:: Number of rows in the matrix.cols:: Number of columns in the matrix.type:: Type of the matrix elements (see cvCreateMat).
The function cvCreateMatHeader allocates new matrix header and returns pointer to it. The matrix data can further be allocated using cvCreateData or set explicitly to user-allocated data via cvSetData.
ReleaseMat
Deallocates matrix
void cvReleaseMat( CvMat** mat );
mat:: Double pointer to the matrix.
The function cvReleaseMat decrements the matrix data reference counter and releases matrix header:
if( *mat )
cvDecRefData( *mat );
cvFree( (void**)mat );
InitMatHeader
Initializes matrix header
CvMat* cvInitMatHeader( CvMat* mat, int rows, int cols, int type,
void* data=NULL, int step=CV_AUTOSTEP );mat:: Pointer to the matrix header to be initialized.rows:: Number of rows in the matrix.cols:: Number of columns in the matrix.type:: Type of the matrix elements.data:: Optional data pointer assigned to the matrix header.step:: Full row width in bytes of the data assigned. By default, the minimal possible step is used, i.e., no gaps is assumed between subsequent rows of the matrix.
The function cvInitMatHeader initializes already allocated CvMat structure. It can be used to process raw data with OpenCV matrix functions.
For example, the following code computes matrix product of two matrices, stored as ordinary arrays.
Calculating Product of Two Matrices
double a[] = { 1, 2, 3, 4
5, 6, 7, 8,
9, 10, 11, 12 };
double b[] = { 1, 5, 9,
2, 6, 10,
3, 7, 11,
4, 8, 12 };
double c[9];
CvMat Ma, Mb, Mc ;
cvInitMatHeader( &Ma, 3, 4, CV_64FC1, a );
cvInitMatHeader( &Mb, 4, 3, CV_64FC1, b );
cvInitMatHeader( &Mc, 3, 3, CV_64FC1, c );
cvMatMulAdd( &Ma, &Mb, 0, &Mc );
// c array now contains product of a(3x4) and b(4x3) matrices
Mat
Initializes matrix header (light-weight variant)
CvMat cvMat( int rows, int cols, int type, void* data=NULL );
rows:: Number of rows in the matrix.cols:: Number of columns in the matrix.type:: Type of the matrix elements (see CreateMat).data:: Optional data pointer assigned to the matrix header.
The function 'cvMat' fills the first 'cols' number of data into the first row. Then the next 'cols' number of data in the second and so on until finish the 'rows'th row.
The function cvMat is a fast inline substitution for cvInitMatHeader. Namely, it is equivalent to:
CvMat mat; cvInitMatHeader( &mat, rows, cols, type, data, CV_AUTOSTEP );
CloneMat
Creates matrix copy
CvMat* cvCloneMat( const CvMat* mat );
mat:: Input matrix.
The function cvCloneMat creates a copy of input matrix and returns the pointer to it.
CreateMatND
Creates multi-dimensional dense array
CvMatND* cvCreateMatND( int dims, const int* sizes, int type );
dims:: Number of array dimensions. It must not exceed CV_MAX_DIM (=32 by default, though it may be changed at build time)sizes:: Array of dimension sizes.type:: Type of array elements. The same as for CvMat
The function cvCreateMatND allocates header for multi-dimensional dense array and the underlying data, and returns pointer to the created array. It is a short form for:
CvMatND* mat = cvCreateMatNDHeader( dims, sizes, type ); cvCreateData( mat );
Array data is stored row by row. All the rows are aligned by 4 bytes.
CreateMatNDHeader
Creates new matrix header
CvMatND* cvCreateMatNDHeader( int dims, const int* sizes, int type );
dims:: Number of array dimensions.sizes:: Array of dimension sizes.type:: Type of array elements. The same as for CvMat
The function cvCreateMatND allocates header for multi-dimensional dense array. The array data can further be allocated using cvCreateData or set explicitly to user-allocated data via cvSetData.
ReleaseMatND
Deallocates multi-dimensional array
void cvReleaseMatND( CvMatND** mat );
mat:: Double pointer to the array.
The function cvReleaseMatND decrements the array data reference counter and releases the array header:
if( *mat )
cvDecRefData( *mat );
cvFree( (void**)mat );
InitMatNDHeader
Initializes multi-dimensional array header
CvMatND* cvInitMatNDHeader( CvMatND* mat, int dims, const int* sizes, int type, void* data=NULL );
mat:: Pointer to the array header to be initialized.dims:: Number of array dimensions.sizes:: Array of dimension sizes.type:: Type of array elements. The same as for CvMatdata:: Optional data pointer assigned to the matrix header.
The function cvInitMatNDHeader initializes CvMatND structure allocated by the user.
CloneMatND
Creates full copy of multi-dimensional array
CvMatND* cvCloneMatND( const CvMatND* mat );
mat:: Input array.
The function cvCloneMatND creates a copy of input array and returns pointer to it.
DecRefData
Decrements array data reference counter
void cvDecRefData( CvArr* arr );
arr:: array header.
The function cvDecRefData decrements CvMat or CvMatND data reference counter if the reference counter pointer is not NULL and deallocates the data if the counter reaches zero. In the current implementation the reference counter is not NULL only if the data was allocated using cvCreateData function, in other cases such as:
external data was assigned to the header using cvSetData
the matrix header presents a part of a larger matrix or image
the matrix header was converted from image or n-dimensional matrix header
the reference counter is set to NULL and thus it is not decremented. Whenever the data is deallocated or not, the data pointer and reference counter pointers are cleared by the function.
IncRefData
Increments array data reference counter
int cvIncRefData( CvArr* arr );
arr:: array header.
The function cvIncRefData increments CvMat or CvMatND data reference counter and returns the new counter value if the reference counter pointer is not NULL, otherwise it returns zero.
CreateData
Allocates array data
void cvCreateData( CvArr* arr );
arr:: Array header.
The function cvCreateData allocates image, matrix or multi-dimensional array data. Note that in case of matrix types OpenCV allocation functions are used and in case of IplImage they are used too unless CV_TURN_ON_IPL_COMPATIBILITY was called. In the latter case IPL functions are used to allocate the data
ReleaseData
Releases array data
void cvReleaseData( CvArr* arr );
arr:: Array header
The function cvReleaseData releases the array data. In case of CvMat or CvMatND it simply calls cvDecRefData(), that is the function can not deallocate external data. See also the note to cvCreateData.
SetData
Assigns user data to the array header
void cvSetData( CvArr* arr, void* data, int step );
arr:: Array header.data:: User data.step:: Full row length in bytes.
The function cvSetData assigns user data to the array header. Header should be initialized before using cvCreate*Header, cvInit*Header or cvMat (in case of matrix) function.
GetRawData
Retrieves low-level information about the array
void cvGetRawData( const CvArr* arr, uchar** data,
int* step=NULL, CvSize* roi_size=NULL );arr:: Array header.data:: Output pointer to the whole image origin or ROI origin if ROI is set.step:: Output full row length in bytes.roi_size:: Output ROI size.
The function cvGetRawData fills output variables with low-level information about the array data. All output parameters are optional, so some of the pointers may be set to NULL. If the array is IplImage with ROI set, parameters of ROI are returned.
The following example shows how to get access to array elements using this function.
Using GetRawData to calculate absolute value of elements of a single-channel floating-point array.
float* data;
int step;
CvSize size;
int x, y;
cvGetRawData( array, (uchar**)&data, &step, &size );
step /= sizeof(data[0]);
for( y = 0; y < size.height; y++, data += step )
for( x = 0; x < size.width; x++ )
data[x] = (float)fabs(data[x]);
GetMat
Returns matrix header for arbitrary array
CvMat* cvGetMat( const CvArr* arr, CvMat* header, int* coi=NULL, int allowND=0 );
arr:: Input array.header:: Pointer to CvMat structure used as a temporary buffer.coi:: Optional output parameter for storing COI.allowND:: If non-zero, the function accepts multi-dimensional dense arrays (CvMatND*) and returns 2D (if CvMatND has two dimensions) or 1D matrix (when CvMatND has 1 dimension or more than 2 dimensions). The array must be continuous.
The function cvGetMat returns matrix header for the input array that can be matrix - CvMat, image - IplImage or multi-dimensional dense array - CvMatND* (latter case is allowed only if allowND != 0) . In the case of matrix the function simply returns the input pointer. In the case of IplImage* or CvMatND* it initializes header structure with parameters of the current image ROI and returns pointer to this temporary structure. Because COI is not supported by CvMat, it is returned separately.
The function provides an easy way to handle both types of array - IplImage and CvMat -, using the same code. Reverse transform from CvMat to IplImage can be done using cvGetImage function.
Input array must have underlying data allocated or attached, otherwise the function fails.
If the input array is IplImage with planar data layout and COI set, the function returns pointer to the selected plane and COI = 0. It enables per-plane processing of multi-channel images with planar data layout using OpenCV functions.
GetImage
Returns image header for arbitrary array
IplImage* cvGetImage( const CvArr* arr, IplImage* image_header );
arr:: Input array.image_header:: Pointer to IplImage structure used as a temporary buffer.
The function cvGetImage returns image header for the input array that can be matrix - CvMat*, or image - IplImage*. In the case of image the function simply returns the input pointer. In the case of CvMat* it initializes image_header structure with parameters of the input matrix. Note that if we transform IplImage to CvMat and then transform CvMat back to IplImage, we can get different headers if the ROI is set, and thus some IPL functions that calculate image stride from its width and align may fail on the resultant image.
CreateSparseMat
Creates sparse array
CvSparseMat* cvCreateSparseMat( int dims, const int* sizes, int type );
dims:: Number of array dimensions. As opposite to the dense matrix, the number of dimensions is practically unlimited (up to 216).sizes:: Array of dimension sizes.type:: Type of array elements. The same as for CvMat
The function cvCreateSparseMat allocates multi-dimensional sparse array. Initially the array contain no elements, that is cvGet*D or cvGetReal*D return zero for every index
ReleaseSparseMat
Deallocates sparse array
void cvReleaseSparseMat( CvSparseMat** mat );
mat:: Double pointer to the array.
The function cvReleaseSparseMat releases the sparse array and clears the array pointer upon exit
CloneSparseMat
Creates full copy of sparse array
CvSparseMat* cvCloneSparseMat( const CvSparseMat* mat );
mat:: Input array.
The function cvCloneSparseMat creates a copy of the input array and returns pointer to the copy.
Accessing Elements and sub-Arrays
GetSubRect
Returns matrix header corresponding to the rectangular sub-array of input image or matrix
CvMat* cvGetSubRect( const CvArr* arr, CvMat* submat, CvRect rect );
arr:: Input array.submat:: Pointer to the resultant sub-array header.rect:: Zero-based coordinates of the rectangle of interest.
The function cvGetSubRect returns header, corresponding to a specified rectangle of the input array. In other words, it allows the user to treat a rectangular part of input array as a stand-alone array. ROI is taken into account by the function so the sub-array of ROI is actually extracted.
GetRow, GetRows
Returns array row or row span
CvMat* cvGetRow( const CvArr* arr, CvMat* submat, int row ); CvMat* cvGetRows( const CvArr* arr, CvMat* submat, int start_row, int end_row, int delta_row=1 );
arr:: Input array.submat:: Pointer to the resulting sub-array header.row:: Zero-based index of the selected row.start_row:: Zero-based index of the starting row (inclusive) of the span.end_row:: Zero-based index of the ending row (exclusive) of the span.delta_row:: Index step in the row span. That is, the function extracts every delta_row-th row from start_row and up to (but not including) 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, submat, row ) ~ cvGetRows( arr, submat, row, row + 1, 1 );
GetCol, GetCols
Returns array column or column span
CvMat* cvGetCol( const CvArr* arr, CvMat* submat, int col ); CvMat* cvGetCols( const CvArr* arr, CvMat* submat, int start_col, int end_col );
arr:: Input array.submat:: Pointer to the resulting sub-array header.col:: Zero-based index of the selected column.start_col:: Zero-based index of the starting column (inclusive) of the span.end_col:: Zero-based index of the ending column (exclusive) of the span.
The functions GetCol and GetCols return the header, corresponding to a specified column/column span of the input array. Note that GetCol is a shortcut for cvGetCols:
cvGetCol( arr, submat, col ); // ~ cvGetCols( arr, submat, col, col + 1 );
GetDiag
Returns one of array diagonals
CvMat* cvGetDiag( const CvArr* arr, CvMat* submat, int diag=0 );
arr:: Input array.submat:: Pointer to the resulting sub-array header.diag:: Array diagonal. Zero corresponds to the main diagonal, -1 corresponds to the diagonal above the main etc., 1 corresponds to the diagonal below the main etc.
The function cvGetDiag returns the header, corresponding to a specified diagonal of the input array.
GetSize
Returns size of matrix or image ROI
CvSize cvGetSize( const CvArr* arr );
arr:: array header.
The function cvGetSize returns number of rows (CvSize::height) and number of columns (CvSize::width) of the input matrix or image. In case of image the size of ROI is returned.
InitSparseMatIterator
Initializes sparse array elements iterator
CvSparseNode* cvInitSparseMatIterator( const CvSparseMat* mat,
CvSparseMatIterator* mat_iterator );mat:: Input array.mat_iterator:: Initialized iterator.
The function cvInitSparseMatIterator initializes iterator of sparse array elements and returns pointer to the first element, or NULL if the array is empty.
GetNextSparseNode
Initializes sparse array elements iterator
CvSparseNode* cvGetNextSparseNode( CvSparseMatIterator* mat_iterator );
mat_iterator:: Sparse array iterator.
The function cvGetNextSparseNode moves iterator to the next sparse matrix element and returns pointer to it. In the current version there is no any particular order of the elements, because they are stored in hash table. The sample below demonstrates how to iterate through the sparse matrix:
Using cvInitSparseMatIterator and cvGetNextSparseNode to calculate sum of floating-point sparse array.
double sum;
int i, dims = cvGetDims( array );
CvSparseMatIterator mat_iterator;
CvSparseNode* node = cvInitSparseMatIterator( array, &mat_iterator );
for( ; node != 0; node = cvGetNextSparseNode( &mat_iterator ))
{
int* idx = CV_NODE_IDX( array, node ); /* get pointer to the element indices */
float val = *(float*)CV_NODE_VAL( array, node ); /* get value of the element
(assume that the type is CV_32FC1) */
printf( "(" );
for( i = 0; i < dims; i++ )
printf( "%4d%s", idx[i], i < dims - 1 "," : "): " );
printf( "%g\n", val );
sum += val;
}
printf( "\nTotal sum = %g\n", sum );
GetElemType
Returns type of array elements
int cvGetElemType( const CvArr* arr );
arr:: Input array.
The functions GetElemType returns type of the array elements as it is described in cvCreateMat discussion:
CV_8UC1 ... CV_64FC4
GetDims, GetDimSize
Return number of array dimensions and their sizes or the size of particular dimension
int cvGetDims( const CvArr* arr, int* sizes=NULL ); int cvGetDimSize( const CvArr* arr, int index );
arr:: Input array.sizes:: Optional output vector of the array dimension sizes. For 2d arrays the number of rows (height) goes first, number of columns (width) next.index:: Zero-based dimension index (for matrices 0 means number of rows, 1 means number of columns; for images 0 means height, 1 means width).
The function cvGetDims returns number of array dimensions and their sizes. In case of IplImage or CvMat it always returns 2 regardless of number of image/matrix rows. The function cvGetDimSize returns the particular dimension size (number of elements per that dimension). For example, the following code calculates total number of array elements in two ways:
// via cvGetDims()
int sizes[CV_MAX_DIM];
int i, total = 1;
int dims = cvGetDims( arr, size );
for( i = 0; i < dims; i++ )
total *= sizes[i];
// via cvGetDims() and cvGetDimSize()
int i, total = 1;
int dims = cvGetDims( arr );
for( i = 0; i < dims; i++ )
total *= cvGetDimsSize( arr, i );
Ptr*D
Return pointer to the particular array element
uchar* cvPtr1D( const CvArr* arr, int idx0, int* type=NULL ); uchar* cvPtr2D( const CvArr* arr, int idx0, int idx1, int* type=NULL ); uchar* cvPtr3D( const CvArr* arr, int idx0, int idx1, int idx2, int* type=NULL ); uchar* cvPtrND( const CvArr* arr, int* idx, int* type=NULL, int create_node=1, unsigned* precalc_hashval=NULL );
arr:: Input array.idx0:: The first zero-based component of the element indexidx1:: The second zero-based component of the element indexidx2:: The third zero-based component of the element indexidx:: Array of the element indicestype:: Optional output parameter: type of matrix elementscreate_node:: Optional input parameter for sparse matrices. Non-zero value of the parameter means that the requested element is created if it does not exist already.precalc_hashval:: Optional input parameter for sparse matrices. If the pointer is not NULL, the function does not recalculate the node hash value, but takes it from the specified location. It is useful for speeding up pair-wise operations (TODO: provide an example)
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*D, cvGetReal*D, cvSet*D, cvSetReal*D) raise an error in case if the element index is out of range.
Get*D
Return the particular array element
CvScalar cvGet1D( const CvArr* arr, int idx0 ); CvScalar cvGet2D( const CvArr* arr, int idx0, int idx1 ); CvScalar cvGet3D( const CvArr* arr, int idx0, int idx1, int idx2 ); CvScalar cvGetND( const CvArr* arr, int* idx );
arr:: Input array.idx0:: The first zero-based component of the element indexidx1:: The second zero-based component of the element indexidx2:: The third zero-based component of the element indexidx:: Array of the element indices
The functions cvGet*D return the particular array element. In case of sparse array the functions return 0 if the requested node does not exist (no new node is created by the functions)
GetReal*D
Return the particular element of single-channel array