opencvref_cxcore.htm

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

<dt>coi<dd>Optional output parameter for storing COI.
<dt>allowND<dd>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.
</dl><p>
The function <code>cvGetMat</code> returns matrix header for the input array that can be
matrix - <a href="#decl_CvMat">CvMat</a>, image - <code>IplImage</code> or multi-dimensional dense array - <a href="#decl_CvMatND*">CvMatND*</a>
(latter case is allowed only if <code>allowND != 0</code>) .
In the case of matrix the function simply returns the input pointer.
In the case of <code>IplImage*</code> or <a href="#decl_CvMatND*">CvMatND*</a> it initializes <code>header</code> structure
with parameters of the current image ROI and returns pointer to this temporary
structure. Because COI is not supported by <a href="#decl_CvMat">CvMat</a>, it is returned separately.
<p>
The function provides an easy way to handle both types of array - <code>IplImage</code> and
<a href="#decl_CvMat">CvMat</a> -, using the same code. Reverse transform from <a href="#decl_CvMat">CvMat</a> to <code>IplImage</code> can be
done using <a href="#decl_cvGetImage">cvGetImage</a> function.
</p><p>
Input array must have underlying data allocated or attached, otherwise the
function fails.
</p>
If the input array is <code>IplImage</code> 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.</p>


<hr><h3><a name="decl_cvGetImage">GetImage</a></h3>
<p class="Blurb">Returns image header for arbitrary array</p>
<pre>
IplImage* cvGetImage( const CvArr* arr, IplImage* image_header );
</pre><p><dl>
<dt>arr<dd>Input array.
<dt>image_header<dd>Pointer to <code>IplImage</code> structure used as a temporary buffer.
</dl><p>
The function <code>cvGetImage</code> returns image header for the input array that can be
matrix - <a href="#decl_CvMat*">CvMat*</a>, or image - <code>IplImage*</code>. In the case of image the function simply
returns the input pointer. In the case of <a href="#decl_CvMat*">CvMat*</a> it initializes <code>image_header</code> structure
with parameters of the input matrix. Note that if we transform <code>IplImage</code> to <a href="#decl_CvMat">CvMat</a> 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.</p>


<hr><h3><a name="decl_cvCreateSparseMat">CreateSparseMat</a></h3>
<p class="Blurb">Creates sparse array</p>
<pre>
CvSparseMat* cvCreateSparseMat( int dims, const int* sizes, int type );
</pre><p><dl>
<dt>dims<dd>Number of array dimensions. As opposite to the dense matrix, the number
            of dimensions is practically unlimited (up to 2<sup>16</sup>).
<dt>sizes<dd>Array of dimension sizes.
<dt>type<dd>Type of array elements. The same as for CvMat
</dl><p>
The function <code>cvCreateSparseMat</code> allocates multi-dimensional sparse array.
Initially the array contain no elements, that is <a href="#decl_cvGet*D">cvGet*D</a> or
<a href="#decl_cvGetReal*D">cvGetReal*D</a> return zero for every index</p>


<hr><h3><a name="decl_cvReleaseSparseMat">ReleaseSparseMat</a></h3>
<p class="Blurb">Deallocates sparse array</p>
<pre>
void cvReleaseSparseMat( CvSparseMat** mat );
</pre><p><dl>
<dt>mat<dd>Double pointer to the array.
</dl><p>
The function <code>cvReleaseSparseMat</code> releases the sparse array and clears the array pointer upon exit</p>


<hr><h3><a name="decl_cvCloneSparseMat">CloneSparseMat</a></h3>
<p class="Blurb">Creates full copy of sparse array</p>
<pre>
CvSparseMat* cvCloneSparseMat( const CvSparseMat* mat );
</pre><p><dl>
<dt>mat<dd>Input array.
</dl><p>
The function <code>cvCloneSparseMat</code> creates a copy of the input array and returns pointer to the copy.</p>


<hr><h2><a name="cxcore_arrays_get_set">Accessing Elements and sub-Arrays</a></h2>

<hr><h3><a name="decl_cvGetSubRect">GetSubRect</a></h3>
<p class="Blurb">Returns matrix header corresponding to the rectangular sub-array of input image or matrix</p>
<pre>
CvMat* cvGetSubRect( const CvArr* arr, CvMat* submat, CvRect rect );
</pre><p><dl>
<dt>arr<dd>Input array.
<dt>submat<dd>Pointer to the resultant sub-array header.
<dt>rect<dd>Zero-based coordinates of the rectangle of interest.
</dl><p>
The function <code>cvGetSubRect</code> 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.</p>


<hr><h3><a name="decl_cvGetRow">GetRow, GetRows</a></h3>
<p class="Blurb">Returns array row or row span</p>
<pre>
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 );
</pre><p><dl>
<dt>arr<dd>Input array.
<dt>submat<dd>Pointer to the resulting sub-array header.
<dt>row<dd>Zero-based index of the selected row.
<dt>start_row<dd>Zero-based index of the starting row (inclusive) of the span.
<dt>end_row<dd>Zero-based index of the ending row (exclusive) of the span.
<dt>delta_row<dd>Index step in the row span. That is, the function extracts every <code>delta_row</code>-th
row from <code>start_row</code> and up to (but not including) <code>end_row</code>.
</dl><p>
The functions <code>GetRow</code> and <code>GetRows</code> return the header, corresponding to a specified
row/row span of the input array. Note that <code>GetRow</code> is a shortcut for <a href="#decl_cvGetRows">cvGetRows</a>:
<pre>
cvGetRow( arr, submat, row ) ~ cvGetRows( arr, submat, row, row + 1, 1 );
</pre></p>


<hr><h3><a name="decl_cvGetCol">GetCol, GetCols</a></h3>
<p class="Blurb">Returns array column or column span</p>
<pre>
CvMat* cvGetCol( const CvArr* arr, CvMat* submat, int col );
CvMat* cvGetCols( const CvArr* arr, CvMat* submat, int start_col, int end_col );
</pre><p><dl>
<dt>arr<dd>Input array.
<dt>submat<dd>Pointer to the resulting sub-array header.
<dt>col<dd>Zero-based index of the selected column.
<dt>start_col<dd>Zero-based index of the starting column (inclusive) of the span.
<dt>end_col<dd>Zero-based index of the ending column (exclusive) of the span.
</dl><p>
The functions <code>GetCol</code> and <code>GetCols</code> return the header, corresponding to a specified
column/column span of the input array. Note that <code>GetCol</code> is a shortcut for <a href="#decl_cvGetCols">cvGetCols</a>:
<pre>
cvGetCol( arr, submat, col ); // ~ cvGetCols( arr, submat, col, col + 1 );
</pre></p>


<hr><h3><a name="decl_cvGetDiag">GetDiag</a></h3>
<p class="Blurb">Returns one of array diagonals</p>
<pre>
CvMat* cvGetDiag( const CvArr* arr, CvMat* submat, int diag=0 );
</pre><p><dl>
<dt>arr<dd>Input array.
<dt>submat<dd>Pointer to the resulting sub-array header.
<dt>diag<dd>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.
</dl><p>
The function <code>cvGetDiag</code> returns the header, corresponding to a specified
diagonal of the input array.</p>


<hr><h3><a name="decl_cvGetSize">GetSize</a></h3>
<p class="Blurb">Returns size of matrix or image ROI</p>
<pre>
CvSize cvGetSize( const CvArr* arr );
</pre><p><dl>
<dt>arr<dd>array header.
</dl><p>
The function <code>cvGetSize</code> 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.</p>


<hr><h3><a name="decl_cvInitSparseMatIterator">InitSparseMatIterator</a></h3>
<p class="Blurb">Initializes sparse array elements iterator</p>
<pre>
CvSparseNode* cvInitSparseMatIterator( const CvSparseMat* mat,
                                       CvSparseMatIterator* mat_iterator );
</pre><p><dl>
<dt>mat<dd>Input array.
<dt>mat_iterator<dd>Initialized iterator.
</dl><p>
The function <code>cvInitSparseMatIterator</code> initializes iterator of sparse array elements and
returns pointer to the first element, or NULL if the array is empty.</p>


<hr><h3><a name="decl_cvGetNextSparseNode">GetNextSparseNode</a></h3>
<p class="Blurb">Initializes sparse array elements iterator</p>
<pre>
CvSparseNode* cvGetNextSparseNode( CvSparseMatIterator* mat_iterator );
</pre><p><dl>
<dt>mat_iterator<dd>Sparse array iterator.
</dl><p>
The function <code>cvGetNextSparseNode</code> 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:</p>
<p>
<font color=blue size=4>Using <a href="#decl_cvInitSparseMatIterator">cvInitSparseMatIterator</a> and <a href="#decl_cvGetNextSparseNode">cvGetNextSparseNode</a> to calculate sum of
floating-point sparse array.</font>
<pre>
    double sum;
    int i, dims = cvGetDims( array );
    CvSparseMatIterator mat_iterator;
    CvSparseNode* node = cvInitSparseMatIterator( array, &amp;mat_iterator );

    for( ; node != 0; node = cvGetNextSparseNode( &amp;mat_iterator ))
    {
        const 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 &lt; dims; i++ )
            printf( "%4d%s", idx[i], i &lt; dims - 1 "," : "): " );
        printf( "%g\n", val );

        sum += val;
    }

    printf( "\nTotal sum = %g\n", sum );
</pre></p>

<hr><h3><a name="decl_cvGetElemType">GetElemType</a></h3>
<p class="Blurb">Returns type of array elements</p>
<pre>
int cvGetElemType( const CvArr* arr );
</pre><p><dl>
<dt>arr<dd>Input array.
</dl><p>
The functions <code>GetElemType</code> returns type of the array elements as it is described in
cvCreateMat discussion: <pre>CV_8UC1 ... CV_64FC4</pre></p>


<hr><h3><a name="decl_cvGetDims">GetDims, GetDimSize</a></h3>
<p class="Blurb">Return number of array dimensions and their sizes or the size of particular dimension</p>
<pre>
int cvGetDims( const CvArr* arr, int* sizes=NULL );
int cvGetDimSize( const CvArr* arr, int index );
</pre><p><dl>
<dt>arr<dd>Input array.
<dt>sizes<dd>Optional output vector of the array dimension sizes. For 2d arrays the number of rows (height)
goes first, number of columns (width) next.
<dt>index<dd>Zero-based dimension index (for matrices 0 means number of rows, 1 means number of columns;
for images 0 means height, 1 means width).
</dl><p>
The function <code>cvGetDims</code> returns number of array dimensions and their sizes.
In case of <code>IplImage</code> or <a href="#decl_CvMat">CvMat</a> it always returns 2 regardless of number of image/matrix rows.
The function <code>cvGetDimSize</code> 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:<pre>

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

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


<hr><h3><a name="decl_cvPtr*D">Ptr*D</a></h3>
<p class="Blurb">Return pointer to the particular array element</p>
<pre>
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, const int* idx, int* type=NULL, int create_node=1, unsigned* precalc_hashval=NULL );
</pre><p><dl>
<dt>arr<dd>Input array.
<dt>idx0<dd>The first zero-based component of the element index
<dt>idx1<dd>The second zero-based component of the element index
<dt>idx2<dd>The third zero-based component of the element index
<dt>idx<dd>Array of the element indices
<dt>type<dd>Optional output parameter: type of matrix elements
<dt>create_node<dd>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.
<dt>precalc_hashval<dd>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)
</dl><p>
The functions <code>>cvPtr*D</code> return pointer to the particular array element.
Number of array dimension should match to the number of indices passed to the function except
for <code>cvPtr1D</code> function that can be used for sequential access to 1D, 2D or nD dense arrays.
</p><p>
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.</p><p>
All these as well as other functions accessing array elements
(<a href="#decl_cvGet*D">cvGet*D</a>, <a href="#decl_cvGetReal*D">cvGetReal*D</a>,
<a href="#decl_cvSet*D">cvSet*D</a>, <a href="#decl_cvSetReal*D">cvSetReal*D</a>)
raise an error in case if the element index is out of range.
</p>


<hr><h3><a name="decl_cvGet*D">Get*D</a></h3>
<p class="Blurb">Return the particular array element</p>
<pre>
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, const int* idx );
</pre><p><dl>
<dt>arr<dd>Input array.
<dt>idx0<dd>The first zero-based component of the element index
<dt>idx1<dd>The second zero-based component of the element index
<dt>idx2<dd>The third zero-based component of the element index
<dt>idx<dd>Array of the element indices
</dl><p>
The functions <code>cvGet*D</code> 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)</p>


<hr><h3><a name="decl_cvGetReal*D">GetReal*D</a></h3>
<p class="Blurb">Return the particular element of single-channel array</p>
<pre>
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, const int* idx );
</pre><p><dl>
<dt>arr<dd>Input array. Must have a single channel.
<dt>idx0<dd>The first zero-based component of the element index
<dt>idx1<dd>The second zero-based component of the element index
<dt>idx2<dd>The third zero-based component of the element index
<dt>idx<dd>Array of the element indices
</dl><p>