Basic C Structures and Operations

The section describes the main data structures, used by the OpenCV 1.x API, and the basic functions to create and process the data structures.

CvPoint

2D point with integer coordinates (usually zero-based).

CvPoint2D32f

2D point with floating-point coordinates.

CvPoint3D32f

3D point with floating-point coordinates

CvPoint2D64f

2D point with double-precision floating-point coordinates.

CvPoint3D64f

3D point with double-precision floating-point coordinates.

CvSize

Size of a rectangle or an image.

CvSize2D32f

Sub-pixel accurate size of a rectangle.

CvRect

Stores coordinates of a rectangle.

CvScalar

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

CvTermCriteria

Termination criteria for iterative algorithms.

CvMat

A multi-channel dense matrix.

Matrix elements are stored row by row. Element (i, j) (i - 0-based row index, j - 0-based column index) of a matrix can be retrieved or modified using CV_MAT_ELEM macro:

uchar pixval = CV_MAT_ELEM(grayimg, uchar, i, j)
CV_MAT_ELEM(cameraMatrix, float, 0, 2) = image.width*0.5f;

To access multiple-channel matrices, you can use CV_MAT_ELEM(matrix, type, i, j*nchannels + channel_idx).

CvMat is now obsolete; consider using :ocv:class:`Mat` instead.

CvMatND

Multi-dimensional dense multi-channel array.

CvMatND is now obsolete; consider using :ocv:class:`Mat` instead.

CvSparseMat

Multi-dimensional sparse multi-channel array.

IplImage

IPL image header

The IplImage is taken from the Intel Image Processing Library, in which the format is native. OpenCV only supports a subset of possible IplImage formats, as outlined in the parameter list above.

In addition to the above restrictions, OpenCV handles ROIs differently. OpenCV functions require that the image size or ROI size of all source and destination images match exactly. On the other hand, the Intel Image Processing Library processes the area of intersection between the source and destination images (or ROIs), allowing them to vary independently.

CvArr

This is the "metatype" used only as a function parameter. It denotes that the function accepts arrays of multiple types, such as IplImage*, CvMat* or even CvSeq* sometimes. The particular array type is determined at runtime by analyzing the first 4 bytes of the header. In C++ interface the role of CvArr is played by InputArray and OutputArray.

ClearND

Clears a specific array element.

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

CloneImage

Makes a full copy of an image, including the header, data, and ROI.

CloneMat

Creates a full matrix copy.

Creates a full copy of a matrix and returns a pointer to the copy. Note that the matrix copy is compacted, that is, it will not have gaps between rows.

CloneMatND

Creates full copy of a multi-dimensional array and returns a pointer to the copy.

CloneSparseMat

Creates full copy of sparse array.

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

ConvertScale

Converts one array to another with optional linear transformation.

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

\texttt{dst} (I) =  \texttt{scale} \texttt{src} (I) + ( \texttt{shift} _0, \texttt{shift} _1,...)

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

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

Copy

Copies one array to another.

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

\texttt{dst} (I)= \texttt{src} (I)  \quad \text{if} \quad \texttt{mask} (I)  \ne 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).

CreateData

Allocates array data

The function allocates image, matrix or multi-dimensional dense array data. Note that in the case of matrix types OpenCV allocation functions are used. In the case of IplImage they are used unless CV_TURN_ON_IPL_COMPATIBILITY() has been called before. In the latter case IPL functions are used to allocate the data.

CreateImage

Creates an image header and allocates the image data.

This function call is equivalent to the following code:

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

CreateImageHeader

Creates an image header but does not allocate the image data.

CreateMat

Creates a matrix header and allocates the matrix data.

The function call is equivalent to the following code:

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

CreateMatHeader

Creates a matrix header but does not allocate the matrix data.

The function allocates a new matrix header and returns a pointer to it. The matrix data can then be allocated using :ocv:cfunc:`CreateData` or set explicitly to user-allocated data via :ocv:cfunc:`SetData`.

CreateMatND

Creates the header and allocates the data for a multi-dimensional dense array.

This function call is equivalent to the following code:

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

CreateMatNDHeader

Creates a new matrix header but does not allocate the matrix data.

The function allocates a header for a multi-dimensional dense array. The array data can further be allocated using :ocv:cfunc:`CreateData` or set explicitly to user-allocated data via :ocv:cfunc:`SetData`.

CreateSparseMat

Creates sparse array.

The function allocates a multi-dimensional sparse array. Initially the array contain no elements, that is :ocv:cfunc:`PtrND` and other related functions will return 0 for every index.

CrossProduct

Calculates the cross product of two 3D vectors.

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

\texttt{dst} =  \texttt{src1} \times \texttt{src2}

or:

\begin{array}{l} \texttt{dst} _1 =  \texttt{src1} _2  \texttt{src2} _3 -  \texttt{src1} _3  \texttt{src2} _2 \\ \texttt{dst} _2 =  \texttt{src1} _3  \texttt{src2} _1 -  \texttt{src1} _1  \texttt{src2} _3 \\ \texttt{dst} _3 =  \texttt{src1} _1  \texttt{src2} _2 -  \texttt{src1} _2  \texttt{src2} _1 \end{array}

DotProduct

Calculates the dot product of two arrays in Euclidian metrics.

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

src1  \bullet src2 =  \sum _I ( \texttt{src1} (I)  \texttt{src2} (I))

In the case of multiple channel arrays, the results for all channels are accumulated. In particular, cvDotProduct(a,a) where a is a complex vector, will return ||\texttt{a}||^2 . The function can process multi-dimensional arrays, row by row, layer by layer, and so on.

Get?D

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

GetCol(s)

Returns one of more array columns.

The functions return the header, corresponding to a specified column span of the input array. That is, no data is copied. Therefore, any modifications of the submatrix will affect the original array. If you need to copy the columns, use :ocv:cfunc:`CloneMat`. cvGetCol(arr, submat, col) is a shortcut for cvGetCols(arr, submat, col, col+1).

GetDiag

Returns one of array diagonals.

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

GetDims

Return number of array dimensions

The function returns the array dimensionality and the array of dimension sizes. In the case of IplImage or CvMat it always returns 2 regardless of number of image/matrix rows. For example, the following code calculates total number of array elements:

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

GetDimSize

Returns array size along the specified dimension.

GetElemType

Returns type of array elements.

The function returns type of the array elements. In the case of IplImage the type is converted to CvMat-like representation. For example, if the image has been created as:

IplImage* img = cvCreateImage(cvSize(640, 480), IPL_DEPTH_8U, 3);

The code cvGetElemType(img) will return CV_8UC3.

GetImage

Returns image header for arbitrary array.

The function returns the image header for the input array that can be a matrix (:ocv:struct:`CvMat`) or image (:ocv:struct:`IplImage`). In the case of an image the function simply returns the input pointer. In the case of CvMat it initializes an imageHeader structure with the parameters of the input matrix. Note that if we transform IplImage to CvMat using :ocv:cfunc:`GetMat` and then transform CvMat back to IplImage using this function, we will get different headers if the ROI is set in the original image.

GetImageCOI

Returns the index of the channel of interest.

Returns the channel of interest of in an IplImage. Returned values correspond to the coi in :ocv:cfunc:`SetImageCOI`.

GetImageROI

Returns the image ROI.

If there is no ROI set, cvRect(0,0,image->width,image->height) is returned.

GetMat

Returns matrix header for arbitrary array.

The function returns a matrix header for the input array that can be a matrix - :ocv:struct:`CvMat`, an image - :ocv:struct:`IplImage`, or a multi-dimensional dense array - :ocv:struct:`CvMatND` (the third option 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 the header structure with parameters of the current image ROI and returns &header. Because COI is not supported by CvMat, it is returned separately.

The function provides an easy way to handle both types of arrays - IplImage and CvMat using the same code. Input array must have non-zero data pointer, otherwise the function will report an error.

GetNextSparseNode

Returns the next sparse matrix element

The function 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 the hash table. The sample below demonstrates how to iterate through the sparse matrix:

// print all the non-zero sparse matrix elements and compute their sum
double sum = 0;
int i, dims = cvGetDims(sparsemat);
CvSparseMatIterator it;
CvSparseNode* node = cvInitSparseMatIterator(sparsemat, &it);

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

    sum += val;
}

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

GetRawData

Retrieves low-level information about the array.

The function 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, the parameters of ROI are returned.

The following example shows how to get access to array elements. It computes absolute values of the array elements

float* data;
int step;
CvSize size;

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

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

GetReal?D

Return a specific element of single-channel 1D, 2D, 3D or nD array.

Returns a specific element of a single-channel array. If the array has multiple channels, a runtime error is raised. Note that Get?D functions can be used safely for both single-channel and multiple-channel arrays though they are a bit slower.

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

GetRow(s)

Returns array row or row span.

The functions return the header, corresponding to a specified row/row span of the input array. cvGetRow(arr, submat, row) is a shortcut for cvGetRows(arr, submat, row, row+1).

GetSize

Returns size of matrix or image ROI.

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

GetSubRect

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

The function 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.

DecRefData

Decrements an array data reference counter.

The function decrements the data reference counter in a :ocv:struct:`CvMat` or :ocv:struct:`CvMatND` if the reference counter pointer is not NULL. If the counter reaches zero, the data is deallocated. In the current implementation the reference counter is not NULL only if the data was allocated using the :ocv:cfunc:`CreateData` function. The counter will be NULL in other cases such as: external data was assigned to the header using :ocv:cfunc:`SetData`, header is part of a larger matrix or image, or the header was converted from an image or n-dimensional matrix header.

IncRefData

Increments array data reference counter.

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

InitImageHeader

Initializes an image header that was previously allocated.

The returned IplImage* points to the initialized header.

InitMatHeader

Initializes a pre-allocated matrix header.

This function is often used to process raw data with OpenCV matrix functions. For example, the following code computes the matrix product of two matrices, stored as ordinary arrays:

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);
// the c array now contains the product of a (3x4) and b (4x3)

InitMatNDHeader

Initializes a pre-allocated multi-dimensional array header.

InitSparseMatIterator

Initializes sparse array elements iterator.

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

Mat

Initializes matrix header (lightweight variant).

Initializes a matrix header and assigns data to it. The matrix is filled row-wise (the first cols elements of data form the first row of the matrix, etc.)

This function is a fast inline substitution for :ocv:cfunc:`InitMatHeader`. Namely, it is equivalent to:

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

Ptr?D

Return pointer to a particular array element.

The functions return a pointer to a specific 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 ( :ocv:cfunc:`GetND` , :ocv:cfunc:`GetRealND` , :ocv:cfunc:`Set` , :ocv:cfunc:`SetND` , :ocv:cfunc:`SetRealND` ) raise an error in case if the element index is out of range.

ReleaseData

Releases array data.

The function releases the array data. In the case of :ocv:struct:`CvMat` or :ocv:struct:`CvMatND` it simply calls cvDecRefData(), that is the function can not deallocate external data. See also the note to :ocv:cfunc:`CreateData` .

ReleaseImage

Deallocates the image header and the image data.

This call is a shortened form of

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

ReleaseImageHeader

Deallocates an image header.

This call is an analogue of

if(image )
{
    iplDeallocate(*image, IPL_IMAGE_HEADER | IPL_IMAGE_ROI);
    *image = 0;
}

but it does not use IPL functions by default (see the CV_TURN_ON_IPL_COMPATIBILITY macro).

ReleaseMat

Deallocates a matrix.

The function decrements the matrix data reference counter and deallocates matrix header. If the data reference counter is 0, it also deallocates the data.

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

ReleaseMatND

Deallocates a multi-dimensional array.

The function decrements the array data reference counter and releases the array header. If the reference counter reaches 0, it also deallocates the data.

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

ReleaseSparseMat

Deallocates sparse array.

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

ResetImageROI

Resets the image ROI to include the entire image and releases the ROI structure.

This produces a similar result to the following, but in addition it releases the ROI structure.

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

Reshape

Changes shape of matrix/image without copying data.

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

The following example code creates one image buffer and two image headers, the first is for a 320x240x3 image and the second is for a 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 a 3x3 matrix to a single 1x9 vector:

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

ReshapeMatND

Changes the shape of a multi-dimensional array without copying the data.

The function is an advanced version of :ocv:cfunc:`Reshape` 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 :ocv:cfunc:`Reshape` description rewritten using :ocv:cfunc:`ReshapeMatND` :

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 = (CvMat*)cvReshapeND(mat, &row_header, 0, 1, 0);

Set

Sets every element of an array to a given value.

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

\texttt{arr} (I)= \texttt{value} \quad \text{if} \quad \texttt{mask} (I)  \ne 0

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

Set?D

Change the particular array element.

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

SetData

Assigns user data to the array header.

The function assigns user data to the array header. Header should be initialized before using :ocv:cfunc:`cvCreateMatHeader`, :ocv:cfunc:`cvCreateImageHeader`, :ocv:cfunc:`cvCreateMatNDHeader`, :ocv:cfunc:`cvInitMatHeader`, :ocv:cfunc:`cvInitImageHeader` or :ocv:cfunc:`cvInitMatNDHeader`.

SetImageCOI

Sets the channel of interest in an IplImage.

If the ROI is set to NULL and the coi is not 0, the ROI is allocated. Most OpenCV functions do not support the COI setting, so to process an individual image/matrix channel one may copy (via :ocv:cfunc:`Copy` or :ocv:cfunc:`Split`) the channel to a separate image/matrix, process it and then copy the result back (via :ocv:cfunc:`Copy` or :ocv:cfunc:`Merge`) if needed.

SetImageROI

Sets an image Region Of Interest (ROI) for a given rectangle.

If the original image ROI was NULL and the rect is not the whole image, the ROI structure is allocated.

Most OpenCV functions support the use of ROI and treat the image rectangle as a separate image. For example, all of the pixel coordinates are counted from the top-left (or bottom-left) corner of the ROI, not the original image.

SetReal?D

Change a specific array element.

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

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

SetZero

Clears the array.

The function clears the array. In the case of dense arrays (CvMat, CvMatND or IplImage), cvZero(array) is equivalent to cvSet(array,cvScalarAll(0),0). In the case of sparse arrays all the elements are removed.

mGet

Returns the particular element of single-channel floating-point matrix.

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

mSet

Sets a specific element of a single-channel floating-point matrix.

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

SetIPLAllocators

Makes OpenCV use IPL functions for allocating IplImage and IplROI structures.

Normally, the function is not called directly. Instead, a simple macro CV_TURN_ON_IPL_COMPATIBILITY() is used that calls cvSetIPLAllocators and passes there pointers to IPL allocation functions.

...
CV_TURN_ON_IPL_COMPATIBILITY()
...

RNG

Initializes a random number generator state.

The function initializes a random number generator and returns the state. The pointer to the state can be then passed to the :ocv:cfunc:`RandInt`, :ocv:cfunc:`RandReal` and :ocv:cfunc:`RandArr` functions. In the current implementation a multiply-with-carry generator is used.

RandArr

Fills an array with random numbers and updates the RNG state.

The function fills the destination array with uniformly or normally distributed random numbers.

RandInt

Returns a 32-bit unsigned integer and updates RNG.

The function returns a uniformly-distributed random 32-bit unsigned integer and updates the RNG state. It is similar to the rand() function from the C runtime library, except that OpenCV functions always generates a 32-bit random number, regardless of the platform.

RandReal

Returns a floating-point random number and updates RNG.

The function returns a uniformly-distributed random floating-point number between 0 and 1 (1 is not included).

fromarray

Create a CvMat from an object that supports the array interface.

If the object supports the array interface , return a :ocv:struct:`CvMat` or :ocv:struct:`CvMatND`, depending on allowND flag:

• If allowND = False, then the object's array must be either 2D or 3D. If it is 2D, then the returned CvMat has a single channel. If it is 3D, then the returned CvMat will have N channels, where N is the last dimension of the array. In this case, N cannot be greater than OpenCV's channel limit, CV_CN_MAX.
• If``allowND = True``, then fromarray returns a single-channel :ocv:struct:`CvMatND` with the same shape as the original array.

For example, NumPy arrays support the array interface, so can be converted to OpenCV objects: