opencvref_cxcore.htm

Simple example of circle detection in OpenCV + C++Builder6.

and returns a pointer to the created matrix. It is a short form for:</p>
<pre>
    CvMat* mat = cvCreateMatHeader( rows, cols, type );
    cvCreateData( mat );
</pre><p>
Matrices are stored row by row. All the rows are aligned by 4 bytes.
</p>


<hr><h3><a name="decl_cvCreateMatHeader">CreateMatHeader</a></h3>
<p class="Blurb">Creates new matrix header</p>
<pre>
CvMat* cvCreateMatHeader( int rows, int cols, int type );
</pre><p><dl>
<dt>rows<dd>Number of rows in the matrix.
<dt>cols<dd>Number of columns in the matrix.
<dt>type<dd>Type of the matrix elements (see <a href="#decl_cvCreateMat">cvCreateMat</a>).
</dl><p>
The function <code>cvCreateMatHeader</code> allocates new matrix header and returns pointer to
it. The matrix data can further be allocated using <a href="#decl_cvCreateData">cvCreateData</a> or set
explicitly to user-allocated data via <a href="#decl_cvSetData">cvSetData</a>.
</p>


<hr><h3><a name="decl_cvReleaseMat">ReleaseMat</a></h3>
<p class="Blurb">Deallocates matrix</p>
<pre>
void cvReleaseMat( CvMat** mat );
</pre><p><dl>
<dt>mat<dd>Double pointer to the matrix.
</dl><p>
The function <code>cvReleaseMat</code> decrements the matrix data reference counter and
releases matrix header:</p>
<pre>
    if( *mat )
        cvDecRefData( *mat );
    cvFree( (void**)mat );
</pre>
</p>


<hr><h3><a name="decl_cvInitMatHeader">InitMatHeader</a></h3>
<p class="Blurb">Initializes matrix header</p>
<pre>
CvMat* cvInitMatHeader( CvMat* mat, int rows, int cols, int type,
                        void* data=NULL, int step=CV_AUTOSTEP );
</pre><p><dl>
<dt>mat<dd>Pointer to the matrix header to be initialized.
<dt>rows<dd>Number of rows in the matrix.
<dt>cols<dd>Number of columns in the matrix.
<dt>type<dd>Type of the matrix elements.
<dt>data<dd>Optional data pointer assigned to the matrix header.
<dt>step<dd>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.
</dl><p>
The function <code>cvInitMatHeader</code> initializes already allocated <a href="#decl_CvMat">CvMat</a> structure. It can
be used to process raw data with OpenCV matrix functions.
<p>
For example, the following code computes matrix product of two matrices, stored
as ordinary arrays.
</p>
</p><p>
<font color=blue size=4>Calculating Product of Two Matrices</font></p>
<pre>
   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( &amp;Ma, 3, 4, CV_64FC1, a );
   cvInitMatHeader( &amp;Mb, 4, 3, CV_64FC1, b );
   cvInitMatHeader( &amp;Mc, 3, 3, CV_64FC1, c );

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


<hr><h3><a name="decl_cvMat">Mat</a></h3>
<p class="Blurb">Initializes matrix header (light-weight variant)</p>
<pre>
CvMat cvMat( int rows, int cols, int type, void* data=NULL );
</pre><p><dl>
<dt>rows<dd>Number of rows in the matrix.
<dt>cols<dd>Number of columns in the matrix.
<dt>type<dd>Type of the matrix elements (see CreateMat).
<dt>data<dd>Optional data pointer assigned to the matrix header.
</dl><p>
The function <code>cvMat</code> is a fast inline substitution for <a href="#decl_cvInitMatHeader">cvInitMatHeader</a>.
Namely, it is equivalent to:
<pre>
     CvMat mat;
     cvInitMatHeader( &amp;mat, rows, cols, type, data, CV_AUTOSTEP );
</pre>
</p>


<hr><h3><a name="decl_cvCloneMat">CloneMat</a></h3>
<p class="Blurb">Creates matrix copy</p>
<pre>
CvMat* cvCloneMat( const CvMat* mat );
</pre><p><dl>
<dt>mat<dd>Input matrix.
</dl><p>
The function <code>cvCloneMat</code> creates a copy of input matrix and returns the pointer to
it.
</p>


<hr><h3><a name="decl_cvCreateMatND">CreateMatND</a></h3>
<p class="Blurb">Creates multi-dimensional dense array</p>
<pre>
CvMatND* cvCreateMatND( int dims, const int* sizes, int type );
</pre><p><dl>
<dt>dims<dd>Number of array dimensions. It must not exceed CV_MAX_DIM (=32 by default,
            though it may be changed at build time)
<dt>sizes<dd>Array of dimension sizes.
<dt>type<dd>Type of array elements. The same as for <a href="#decl_CvMat">CvMat</a>
</dl><p>
The function <code>cvCreateMatND</code> allocates header for multi-dimensional dense array
and the underlying data, and returns pointer to the created array. It is a short form for:</p>
<pre>
    CvMatND* mat = cvCreateMatNDHeader( dims, sizes, type );
    cvCreateData( mat );
</pre><p>
Array data is stored row by row. All the rows are aligned by 4 bytes.
</p>


<hr><h3><a name="decl_cvCreateMatNDHeader">CreateMatNDHeader</a></h3>
<p class="Blurb">Creates new matrix header</p>
<pre>
CvMatND* cvCreateMatNDHeader( int dims, const int* sizes, int type );
</pre><p><dl>
<dt>dims<dd>Number of array dimensions.
<dt>sizes<dd>Array of dimension sizes.
<dt>type<dd>Type of array elements. The same as for CvMat
</dl><p>
The function <code>cvCreateMatND</code> allocates header for multi-dimensional dense array.
The array data can further be allocated using <a href="#decl_cvCreateData">cvCreateData</a> or set
explicitly to user-allocated data via <a href="#decl_cvSetData">cvSetData</a>.
</p>


<hr><h3><a name="decl_cvReleaseMatND">ReleaseMatND</a></h3>
<p class="Blurb">Deallocates multi-dimensional array</p>
<pre>
void cvReleaseMatND( CvMatND** mat );
</pre><p><dl>
<dt>mat<dd>Double pointer to the array.
</dl><p>
The function <code>cvReleaseMatND</code> decrements the array data reference counter and
releases the array header:</p>
<pre>
    if( *mat )
        cvDecRefData( *mat );
    cvFree( (void**)mat );
</pre>
</p>


<hr><h3><a name="decl_cvInitMatNDHeader">InitMatNDHeader</a></h3>
<p class="Blurb">Initializes multi-dimensional array header</p>
<pre>
CvMatND* cvInitMatNDHeader( CvMatND* mat, int dims, const int* sizes, int type, void* data=NULL );
</pre><p><dl>
<dt>mat<dd>Pointer to the array header to be initialized.
<dt>dims<dd>Number of array dimensions.
<dt>sizes<dd>Array of dimension sizes.
<dt>type<dd>Type of array elements. The same as for CvMat
<dt>data<dd>Optional data pointer assigned to the matrix header.
</dl><p>
The function <code>cvInitMatNDHeader</code> initializes <a href="#decl_CvMatND">CvMatND</a> structure allocated by
the user.
</p>


<hr><h3><a name="decl_cvCloneMatND">CloneMatND</a></h3>
<p class="Blurb">Creates full copy of multi-dimensional array</p>
<pre>
CvMatND* cvCloneMatND( const CvMatND* mat );
</pre><p><dl>
<dt>mat<dd>Input array.
</dl><p>
The function <code>cvCloneMatND</code> creates a copy of input array and returns pointer to
it.
</p>


<hr><h3><a name="decl_cvDecRefData">DecRefData</a></h3>
<p class="Blurb">Decrements array data reference counter</p>
<pre>
void cvDecRefData( CvArr* arr );
</pre><p><dl>
<dt>arr<dd>array header.
</dl><p>
The function <code>cvDecRefData</code> decrements <a href="#decl_CvMat">CvMat</a> or <a href="#decl_CvMatND">CvMatND</a> 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
<a href="#decl_cvCreateData">cvCreateData</a> function, in other cases such as:<br>
external data was assigned to the header using <a href="#decl_cvSetData">cvSetData</a><br>
the matrix header presents a part of a larger matrix or image<br>
the matrix header was converted from image or n-dimensional matrix header<br>
<br>
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.
</p>


<hr><h3><a name="decl_cvIncRefData">IncRefData</a></h3>
<p class="Blurb">Increments array data reference counter</p>
<pre>
int cvIncRefData( CvArr* arr );
</pre><p><dl>
<dt>arr<dd>array header.
</dl><p>
The function <code>cvIncRefData</code> increments <a href="#decl_CvMat">CvMat</a> or <a href="#decl_CvMatND">CvMatND</a> data reference counter and
returns the new counter value if the reference counter pointer is not NULL, otherwise it returns zero.
</p>


<hr><h3><a name="decl_cvCreateData">CreateData</a></h3>
<p class="Blurb">Allocates array data</p>
<pre>
void cvCreateData( CvArr* arr );
</pre><p><dl>
<dt>arr<dd>Array header.
</dl></p><p>
The function <code>cvCreateData</code> 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 <code>CV_TURN_ON_IPL_COMPATIBILITY</code> was called.
In the latter case IPL functions are used to allocate the data
</p>


<hr><h3><a name="decl_cvReleaseData">ReleaseData</a></h3>
<p class="Blurb">Releases array data</p>
<pre>
void cvReleaseData( CvArr* arr );
</pre><p><dl>
<dt>arr<dd>Array header
</dl><p>
The function <code>cvReleaseData</code> releases the array data.
In case of <a href="#decl_CvMat">CvMat</a> or <a href="#decl_CvMatND">CvMatND</a> it simply calls cvDecRefData(), that is
the function can not deallocate external data. See also the note to <a href="#decl_cvCreateData">cvCreateData</a>.
</p>


<hr><h3><a name="decl_cvSetData">SetData</a></h3>
<p class="Blurb">Assigns user data to the array header</p>
<pre>
void cvSetData( CvArr* arr, void* data, int step );
</pre><p><dl>
<dt>arr<dd>Array header.
<dt>data<dd>User data.
<dt>step<dd>Full row length in bytes.
</dl><p>
The function <code>cvSetData</code> assigns user data to the array header.
Header should be initialized before using cvCreate*Header,
cvInit*Header or <a href="#decl_cvMat">cvMat</a> (in case of matrix) function.
</p>


<hr><h3><a name="decl_cvGetRawData">GetRawData</a></h3>
<p class="Blurb">Retrieves low-level information about the array</p>
<pre>
void cvGetRawData( const CvArr* arr, uchar** data,
                   int* step=NULL, CvSize* roi_size=NULL );
</pre><p><dl>
<dt>arr<dd>Array header.
<dt>data<dd>Output pointer to the whole image origin or ROI origin if
ROI is set.
<dt>step<dd>Output full row length in bytes.
<dt>roi_size<dd>Output ROI size.
</dl><p>
The function <code>cvGetRawData</code> 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 <code>NULL</code>.
If the array is <code>IplImage</code> with ROI set,
parameters of ROI are returned.
</p>
<p>The following example shows how to get access to array elements using
this function.</p>
<p>
<font color=blue size=4>Using GetRawData to calculate absolute value of elements of
a single-channel floating-point array.</font>
<pre>
    float* data;
    int step;

    CvSize size;
    int x, y;

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

    for( y = 0; y &lt; size.height; y++, data += step )
        for( x = 0; x &lt; size.width; x++ )
            data[x] = (float)fabs(data[x]);
</pre></p>


<hr><h3><a name="decl_cvGetMat">GetMat</a></h3>
<p class="Blurb">Returns matrix header for arbitrary array</p>
<pre>
CvMat* cvGetMat( const CvArr* arr, CvMat* header, int* coi=NULL, int allowND=0 );
</pre><p><dl>
<dt>arr<dd>Input array.
<dt>header<dd>Pointer to <a href="#decl_CvMat">CvMat</a> structure used as a temporary buffer.