opencvref_cxcore.htm

Simple ellipse fitting example on C++Builder6 + OpenCV1.0.

<p class="Blurb">Multi-dimensional sparse multi-channel array</p>
<pre>
    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;
</pre>


<hr><h3><a name="decl_IplImage">IplImage</a></h3>
<p class="Blurb">IPL image header</p>
<pre>
    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;
</pre>
<p>
The structure <code>IplImage</code> came from <em>Intel Image Processing Library</em> where
the format is native. OpenCV supports only a subset of possible <code>IplImage</code> formats:
<ul>
<li><code>alphaChannel</code> is ignored by OpenCV.
<li><code>colorModel</code> and <code>channelSeq</code> are ignored by OpenCV. The single OpenCV function
<a href="#decl_cvCvtColor">cvCvtColor</a> working with color spaces takes the source and destination color spaces
as a parameter.
<li><code>dataOrder</code> 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.
<li><code>align</code> is ignored by OpenCV, while <code>widthStep</code> is used to access to subsequent image rows.
<li><code>maskROI</code> 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.
<li><code>tileInfo</code> is not supported.
<li><code>BorderMode</code> and <code>BorderConst</code> are not supported. Every OpenCV function
working with a pixel neigborhood uses a single hard-coded border mode (most often, replication).
</ul>
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 <a href="#decl_cvPyrDown">cvPyrDown</a>
destination width(height) must be equal to source width(height) divided by 2 &plusmn;1),
whereas IPL processes the intersection area - that is, the sizes or ROI sizes of all images may
vary independently.
</p>


<hr><h3><a name="decl_CvArr">CvArr</a></h3>
<p class="Blurb">Arbitrary array</p>
<pre>
    typedef void CvArr;
</pre>
<p>
The metatype <code>CvArr*</code> is used <em>only</em> 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.
</p>

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

<hr><h1><a name="cxcore_arrays">Operations on Arrays</a></h1>
<hr><h2><a name="cxcore_arrays_alloc_free">Initialization</a></h2>

<hr><h3><a name="decl_cvCreateImage">CreateImage</a></h3>
<p class="Blurb">Creates header and allocates data</p>
<pre>
IplImage* cvCreateImage( CvSize size, int depth, int channels );
</pre><p><dl>
<dt>size<dd>Image width and height.
<dt>depth<dd>Bit depth of image elements. Can be one of:<br>
             IPL_DEPTH_8U - unsigned 8-bit integers<br>
             IPL_DEPTH_8S - signed 8-bit integers<br>
             IPL_DEPTH_16U - unsigned 16-bit integers<br>
             IPL_DEPTH_16S - signed 16-bit integers<br>
             IPL_DEPTH_32S - signed 32-bit integers<br>
             IPL_DEPTH_32F - single precision floating-point numbers<br>
             IPL_DEPTH_64F - double precision floating-point numbers<br>
<dt>channels<dd>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:<br>
             b0 g0 r0 b1 g1 r1 ...<br>
             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.
</dl><p>
The function <code>cvCreateImage</code> creates the header and allocates data. This call is a
shortened form of
<pre>
    header = cvCreateImageHeader(size,depth,channels);
    cvCreateData(header);
</pre>
</p>


<hr><h3><a name="decl_cvCreateImageHeader">CreateImageHeader</a></h3>
<p class="Blurb">Allocates, initializes, and returns structure IplImage</p>
<pre>
IplImage* cvCreateImageHeader( CvSize size, int depth, int channels );
</pre><p><dl>
<dt>size<dd>Image width and height.
<dt>depth<dd>Image depth (see CreateImage).
<dt>channels<dd>Number of channels (see CreateImage).
</dl><p>
The function <code>cvCreateImageHeader</code> allocates, initializes, and returns the structure
<code>IplImage</code>. This call is an analogue of
<pre>
  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);
</pre>
though it does not use IPL functions by default
(see also <code>CV_TURN_ON_IPL_COMPATIBILITY</code> macro)
</p>


<hr><h3><a name="decl_cvReleaseImageHeader">ReleaseImageHeader</a></h3>
<p class="Blurb">Releases header</p>
<pre>
void cvReleaseImageHeader( IplImage** image );
</pre><p><dl>
<dt>image<dd>Double pointer to the deallocated header.
</dl><p>
The function <code>cvReleaseImageHeader</code> releases the header.
This call is an analogue of
<pre>
    if( image )
    {
        iplDeallocate( *image, IPL_IMAGE_HEADER | IPL_IMAGE_ROI );
        *image = 0;
    }
</pre>
though it does not use IPL functions by default
(see also <code>CV_TURN_ON_IPL_COMPATIBILITY</code>)
</p>


<hr><h3><a name="decl_cvReleaseImage">ReleaseImage</a></h3>
<p class="Blurb">Releases header and image data</p>
<pre>
void cvReleaseImage( IplImage** image );
</pre><p><dl>
<dt>image<dd>Double pointer to the header of the deallocated image.
</dl></p><p>
The function <code>cvReleaseImage</code> releases the header and the image data. This call is a
shortened form of
<pre>
    if( *image )
    {
        cvReleaseData( *image );
        cvReleaseImageHeader( image );
    }
</pre>
</p>


<hr><h3><a name="decl_cvInitImageHeader">InitImageHeader</a></h3>
<p class="Blurb">Initializes allocated by user image header</p>
<pre>
IplImage* cvInitImageHeader( IplImage* image, CvSize size, int depth,
                             int channels, int origin=0, int align=4 );
</pre><p><dl>
<dt>image<dd>Image header to initialize.
<dt>size<dd>Image width and height.
<dt>depth<dd>Image depth (see CreateImage).
<dt>channels<dd>Number of channels (see CreateImage).
<dt>origin<dd><code>IPL_ORIGIN_TL</code> or <code>IPL_ORIGIN_BL</code>.
<dt>align<dd>Alignment for image rows, typically 4 or 8 bytes.
</dl></p><p>
The function <code>cvInitImageHeader</code> initializes the image header structure,
pointer to which is passed by the user, and returns the pointer.
</p>


<hr><h3><a name="decl_cvCloneImage">CloneImage</a></h3>
<p class="Blurb">Makes a full copy of image</p>
<pre>
IplImage* cvCloneImage( const IplImage* image );
</pre><p><dl>
<dt>image<dd>Original image.
</dl></p><p>
The function <code>cvCloneImage</code> makes a full copy of the image including
header, ROI and data
</p>


<hr><h3><a name="decl_cvSetImageCOI">SetImageCOI</a></h3>
<p class="Blurb">Sets channel of interest to given value</p>
<pre>
void cvSetImageCOI( IplImage* image, int coi );
</pre><p><dl>
<dt>image<dd>Image header.
<dt>coi<dd>Channel of interest.
</dl><p>
The function <code>cvSetImageCOI</code> 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 <code>NULL</code> and <code>coi != 0</code>, ROI is allocated.
Note that most of OpenCV functions do not support COI, so
to process separate image/matrix channel one may copy (via <a href="#decl_cvCopy">cvCopy</a> or
<a href="#decl_cvSplit">cvSplit</a>) the channel to separate image/matrix,
process it and copy the result back (via <a href="#decl_cvCopy">cvCopy</a> or <a href="#decl_cvCvtPlaneToPix">cvCvtPlaneToPix</a>)
if need.</p>


<hr><h3><a name="decl_cvGetImageCOI">GetImageCOI</a></h3>
<p class="Blurb">Returns index of channel of interest</p>
<pre>
int cvGetImageCOI( const IplImage* image );
</pre><p><dl>
<dt>image<dd>Image header.
</dl><p>
The function <code>cvGetImageCOI</code> returns channel of interest of
the image (it returns 0 if all the channels are selected).</p>


<hr><h3><a name="decl_cvSetImageROI">SetImageROI</a></h3>
<p class="Blurb">Sets image ROI to given rectangle</p>
<pre>
void cvSetImageROI( IplImage* image, CvRect rect );
</pre><p><dl>
<dt>image<dd>Image header.
<dt>rect<dd>ROI rectangle.
</dl><p>
The function <code>cvSetImageROI</code> sets the image ROI to a given rectangle. If ROI is <code>NULL</code>
and the value of the parameter <code>rect</code> 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)</p>


<hr><h3><a name="decl_cvResetImageROI">ResetImageROI</a></h3>
<p class="Blurb">Releases image ROI</p>
<pre>
void cvResetImageROI( IplImage* image );
</pre><p><dl>
<dt>image<dd>Image header.
</dl><p>
The function <code>cvResetImageROI</code> releases image ROI. After that the whole image
is considered selected. The similar result can be achieved by</p>
<pre>
cvSetImageROI( image, cvRect( 0, 0, image->width, image->height ));
cvSetImageCOI( image, 0 );
</pre>
<p>
But the latter variant does not deallocate <code>image->roi</code>.
</p>


<hr><h3><a name="decl_cvGetImageROI">GetImageROI</a></h3>
<p class="Blurb">Returns image ROI coordinates</p>
<pre>
CvRect cvGetImageROI( const IplImage* image );
</pre><p><dl>
<dt>image<dd>Image header.
</dl><p>
The function <code>cvGetImageROI</code> returns image ROI coordinates.
The rectangle <a href="#decl_cvRect">cvRect</a>(0,0,image->width,image->height) is returned if
there is no ROI</p>


<hr><h3><a name="decl_cvCreateMat">CreateMat</a></h3>
<p class="Blurb">Creates new matrix</p>
<pre>
CvMat* cvCreateMat( 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.
            Usually it is specified in form
            <code>CV_&lt;bit_depth&gt;(S|U|F)C&lt;number_of_channels&gt;</code>, for example:<br>
            <code>CV_8UC1</code> means an 8-bit unsigned single-channel matrix,
            <code>CV_32SC2</code> means a 32-bit signed matrix with two channels.
</dl><p>
The function <code>cvCreateMat</code> allocates header for the new matrix and underlying data,