opencvref_cxcore.htm

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

The functions <code>cvGetReal*D</code> return the particular element of single-channel array.
If the array has multiple channels, runtime error is raised. Note that <a href="#decl_cvGet*D">cvGet*D</a> function
can be used safely for both single-channel and multiple-channel arrays though they are
a bit slower.</p><p>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_cvmGet">mGet</a></h3>
<p class="Blurb">Return the particular element of single-channel floating-point matrix</p>
<pre>
double cvmGet( const CvMat* mat, int row, int col );
</pre><p><dl>
<dt>mat<dd>Input matrix.
<dt>row<dd>The zero-based index of row.
<dt>col<dd>The zero-based index of column.
</dl><p>
The function <code>cvmGet</code> is a fast replacement for <a href="#decl_cvGetReal2D">cvGetReal2D</a> 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.</p>


<hr><h3><a name="decl_cvSet*D">Set*D</a></h3>
<p class="Blurb">Change the particular array element</p>
<pre>
void cvSet1D( CvArr* arr, int idx0, CvScalar value );
void cvSet2D( CvArr* arr, int idx0, int idx1, CvScalar value );
void cvSet3D( CvArr* arr, int idx0, int idx1, int idx2, CvScalar value );
void cvSetND( CvArr* arr, const int* idx, CvScalar value );
</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>value<dd>The assigned value
</dl><p>
The functions <code>cvSet*D</code> 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</p>


<hr><h3><a name="decl_cvSetReal*D">SetReal*D</a></h3>
<p class="Blurb">Change the particular array element</p>
<pre>
void cvSetReal1D( CvArr* arr, int idx0, double value );
void cvSetReal2D( CvArr* arr, int idx0, int idx1, double value );
void cvSetReal3D( CvArr* arr, int idx0, int idx1, int idx2, double value );
void cvSetRealND( CvArr* arr, const int* idx, double value );
</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>value<dd>The assigned value
</dl><p>
The functions <code>cvSetReal*D</code> assign the new value to the particular element of single-channel array.
If the array has multiple channels, runtime error is raised. Note that <a href="#decl_cvSet*D">cvSet*D</a> function
can be used safely for both single-channel and multiple-channel arrays though they are
a bit slower.</p>
<p>In case of sparse array the functions create the node if it does not exist yet</p>


<hr><h3><a name="decl_cvmSet">mSet</a></h3>
<p class="Blurb">Return the particular element of single-channel floating-point matrix</p>
<pre>
void cvmSet( CvMat* mat, int row, int col, double value );
</pre><p><dl>
<dt>mat<dd>The matrix.
<dt>row<dd>The zero-based index of row.
<dt>col<dd>The zero-based index of column.
<dt>value<dd>The new value of the matrix element
</dl><p>
The function <code>cvmSet</code> is a fast replacement for <a href="#decl_cvSetReal2D">cvSetReal2D</a> 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.</p>


<hr><h3><a name="decl_cvClearND">ClearND</a></h3>
<p class="Blurb">Clears the particular array element</p>
<pre>
void cvClearND( CvArr* arr, const int* idx );
</pre><p><dl>
<dt>arr<dd>Input array.
<dt>idx<dd>Array of the element indices
</dl><p>
The function <a href="#decl_cvClearND">cvClearND</a> 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.</p>


<hr><h2><a name="cxcore_arrays_copying">Copying and Filling</a></h2>


<hr><h3><a name="decl_cvCopy">Copy</a></h3>
<p class="Blurb">Copies one array to another</p>
<pre>
void cvCopy( const CvArr* src, CvArr* dst, const CvArr* mask=NULL );
</pre><p><dl>
<dt>src<dd>The source array.
<dt>dst<dd>The destination array.
<dt>mask<dd>Operation mask, 8-bit single channel array; specifies elements of
destination array to be changed.
</dl><p>
The function <code>cvCopy</code> copies selected elements from input array to output array:</p>
<p>
dst(I)=src(I) if mask(I)!=0.
</p><p>If any of the passed arrays is of <code>IplImage</code> 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).</p>


<hr><h3><a name="decl_cvSet">Set</a></h3>
<p class="Blurb">Sets every element of array to given value</p>
<pre>
void cvSet( CvArr* arr, CvScalar value, const CvArr* mask=NULL );
</pre><p><dl>
<dt>arr<dd>The destination array.
<dt>value<dd>Fill value.
<dt>mask<dd>Operation mask, 8-bit single channel array; specifies elements of
destination array to be changed.
</dl><p>
The function <code>cvSet</code> copies scalar <code>value</code> to every selected element of the destination
array:</p>
<pre>arr(I)=value if mask(I)!=0</pre>
<p>If array <code>arr</code> is of <code>IplImage</code> type, then is ROI used, but COI must not be
set.</p>


<hr><h3><a name="decl_cvSetZero">SetZero</a></h3>
<p class="Blurb">Clears the array</p>
<pre>
void cvSetZero( CvArr* arr );
#define cvZero cvSetZero
</pre><p><dl>
<dt>arr<dd>array to be cleared.
</dl><p>
The function <code>cvSetZero</code> clears the array. In case of dense arrays
(CvMat, CvMatND or IplImage) cvZero(array) is equivalent to cvSet(array,cvScalarAll(0),0),
in case of sparse arrays all the elements are removed.</p>


<hr><h3><a name="decl_cvSetIdentity">SetIdentity</a></h3>
<p class="Blurb">Initializes scaled identity matrix</p>
<pre>
void cvSetIdentity( CvArr* mat, CvScalar value=cvRealScalar(1) );
</pre><p><dl>
<dt>arr<dd>The matrix to initialize (not necesserily square).
<dt>value<dd>The value to assign to the diagonal elements.
</dl><p>
The function <code>cvSetIdentity</code> initializes scaled identity matrix:</p>
<pre>
arr(i,j)=value if i=j,
       0 otherwise
</pre>


<hr><h3><a name="decl_cvRange">Range</a></h3>
<p class="Blurb">Fills matrix with given range of numbers</p>
<pre>
void cvRange( CvArr* mat, double start, double end );
</pre><p><dl>
<dt>mat<dd>The matrix to initialize. It should be single-channel 32-bit, integer or floating-point.
<dt>start<dd>The lower inclusive boundary of the range.
<dt>end<dd>The upper exclusive boundary of the range.
</dl><p>
The function <code>cvRange</code> initializes the matrix as following:</p>
<pre>
arr(i,j)=(end-start)*(i*cols(arr)+j)/(cols(arr)*rows(arr))
</pre>
For example, the following code will initilize 1D vector with subsequent integer numbers.
<pre>
CvMat* A = cvCreateMat( 1, 10, CV_32S );
cvRange( A, 0, A->cols ); // A will be initialized as [0,1,2,3,4,5,6,7,8,9]
</pre>

<!-- *****************************************************************************************
     *****************************************************************************************
     ***************************************************************************************** -->

<hr><h2><a name="cxcore_arrays_permute">Transforms and Permutations</a></h2>

<hr><h3><a name="decl_cvReshape">Reshape</a></h3>
<p class="Blurb">Changes shape of matrix/image without copying data</p>
<pre>
CvMat* cvReshape( const CvArr* arr, CvMat* header, int new_cn, int new_rows=0 );
</pre><p><dl>
<dt>arr<dd>Input array.
<dt>header<dd>Output header to be filled.
<dt>new_cn<dd>New number of channels. <code>new_cn = 0</code> means that number of channels remains unchanged.
<dt>new_rows<dd>New number of rows. <code>new_rows = 0</code> means that number of rows remains unchanged unless
it needs to be changed according to <code>new_cn</code> value.
destination array to be changed.
</dl><p>
The function <code>cvReshape</code> 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.</p><p>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:</p>
<pre>
IplImage* color_img = cvCreateImage( cvSize(320,240), IPL_DEPTH_8U, 3 );
CvMat gray_mat_hdr;
IplImage gray_img_hdr, *gray_img;
cvReshape( color_img, &amp;gray_mat_hdr, 1 );
gray_img = cvGetImage( &amp;gray_mat_hdr, &amp;gray_img_hdr );
</pre>
<p>And the next example converts 3x3 matrix to a single 1x9 vector</p>
<pre>
CvMat* mat = cvCreateMat( 3, 3, CV_32F );
CvMat row_header, *row;
row = cvReshape( mat, &amp;row_header, 0, 1 );
</pre>


<hr><h3><a name="decl_cvReshapeMatND">ReshapeMatND</a></h3>
<p class="Blurb">Changes shape of multi-dimensional array w/o copying data</p>
<pre>
CvArr* cvReshapeMatND( const CvArr* arr,
                       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))

</pre><p><dl>
<dt>arr<dd>Input array.
<dt>sizeof_header<dd>Size of output header to distinguish between IplImage, CvMat and CvMatND output headers.
<dt>header<dd>Output header to be filled.
<dt>new_cn<dd>New number of channels. <code>new_cn = 0</code> means that number of channels remains unchanged.
<dt>new_dims<dd>New number of dimensions. <code>new_dims = 0</code> means that number of dimensions remains the same.
<dt>new_sizes<dd>Array of new dimension sizes. Only <code>new_dims-1</code> values are used, because the total number of
elements must remain the same. Thus, if <code>new_dims = 1</code>, <code>new_sizes</code> array is not used
</dl><p>
The function <code>cvReshapeMatND</code> is an advanced version of <a href="#decl_cvReshape">cvReshape</a> 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 <a href="#decl_cvReshape">cvReshape</a> description rewritten using <a href="#decl_cvReshapeMatND">cvReshapeMatND</a>:</p>
<pre>
IplImage* color_img = cvCreateImage( cvSize(320,240), IPL_DEPTH_8U, 3 );
IplImage gray_img_hdr, *gray_img;
gray_img = (IplImage*)cvReshapeND( color_img, &amp;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, &amp;row_header, 0, 1, 0 );
</pre>


<hr><h3><a name="decl_cvRepeat">Repeat</a></h3>
<p class="Blurb">Fill destination array with tiled source array</p>
<pre>
void cvRepeat( const CvArr* src, CvArr* dst );
</pre><p><dl>
<dt>src<dd>Source array, image or matrix.
<dt>dst<dd>Destination array, image or matrix.
</dl><p>
The function <code>cvRepeat</code> fills the destination array with source array tiled:</p>
<pre>dst(i,j)=src(i mod rows(src), j mod cols(src))</pre>
<p>
So the destination array may be as larger as well as smaller than
the source array.
</p>


<hr><h3><a name="decl_cvFlip">Flip</a></h3>
<p class="Blurb">Flip a 2D array around vertical, horizontall or both axises</p>
<pre>
void  cvFlip( const CvArr* src, CvArr* dst=NULL, int flip_mode=0);
#define cvMirror cvFlip

</pre><p><dl>
<dt>src<dd>Source array.
<dt>dst<dd>Destination array. If <code>dst = NULL</code> the flipping is done inplace.
<dt>flip_mode<dd>Specifies how to flip the array.<br>
                 flip_mode = 0 means flipping around x-axis,
                 flip_mode > 0 (e.g. 1) means flipping around y-axis
                 and flip_mode &lt; 0 (e.g. -1) means flipping around both axises.
                 See also the discussion below for the formulas
</dl><p>
The function <code>cvFlip</code> flips the array in one of different 3 ways
(row and column indices are 0-based):</p>
<pre>dst(i,j)=src(rows(src)-i-1,j) if flip_mode = 0</pre>
<pre>dst(i,j)=src(i,cols(src1)-j-1) if flip_mode > 0</pre>
<pre>dst(i,j)=src(rows(src)-i-1,cols(src)-j-1) if flip_mode &lt; 0</pre>
<p>The example cenaria of the function use are:
<ul>
<li>
vertical flipping of the image (flip_mode > 0) to switch between top-left
and bottom-left image origin, which is typical operation in video processing under Win32 systems.</li>
<li>
horizontal flipping of the image with subsequent horizontal shift and absolute difference calculation
to check for a vertical-axis symmetry (flip_mode > 0)</li>
<li>
simultaneous horizontal and vertical flipping of the image with subsequent shift and
absolute difference calculation to check for a central symmetry (flip_mode &lt; 0)</li>
<li>reversing the order of 1d point arrays(flip_mode > 0)</li>
</ul></p>


<hr><h3><a name="decl_cvSplit">Split</a></h3>
<p class="Blurb">Divides multi-channel array into several single-channel arrays or extracts
a single channel from the array</p>
<pre>
void cvSplit( const CvArr* src, CvArr* dst0, CvArr* dst1,
              CvArr* dst2, CvArr* dst3 );
#define cvCvtPixToPlane cvSplit
</pre><p><dl>
<dt>src<dd>Source array.
<dt>dst0...dst3<dd>Destination channels.
</dl><p>
The function <code>cvSplit</code> divides a multi-channel array into separate single-channel arrays.
Two modes are available for the opera