# Basic Structures and Operations Reference

- Helper structures
  - Point
  - Point2D32f
  - Point3D32f
  - Size
  - Size2D32f
  - Rect
  - Scalar
- Array structures
  - Mat
  - MatND
  - SparseMat
  - Arr
- Arrays: Allocation/deallocation/copying/setting and retrieving parts
  - Alloc
  - Free
  - CreateImage
  - CreateImageHeader
  - ReleaseImageHeader
  - ReleaseImage
  - InitImageHeader
  - CloneImage
  - SetImageCOI
  - GetImageCOI
  - SetImageROI
  - ResetImageROI
  - GetImageROI
  - CreateMat
  - CreateMatHeader
  - ReleaseMat
  - InitMatHeader
  - Mat
  - CloneMat
  - CreateMatND
  - CreateMatNDHeader
  - ReleaseMatND
  - InitMatNDHeader
  - CloneMatND
  - DecRefData
  - IncRefData
  - CreateData
  - ReleaseData
  - SetData
  - GetRawData
  - GetMat
  - GetImage
  - GetSubRect
  - GetRow
  - GetCol
  - GetDiag
  - GetSize
  - CreateSparseMat
  - ReleaseSparseMat
  - CloneSparseMat
  - InitSparseMatIterator
  - GetNextSparseNode
  - GetElemType
  - GetDims
  - Ptr*D
  - Get*D
  - GetReal*D
  - mGet
  - Set*D
  - SetReal*D
  - mSet
  - Clear*D
  - Copy
  - Set
  - SetZero
- Arrays: Conversions, transformations, basic operations
  - Reshape
  - ReshapeMatND
  - Repeat
  - Flip
  - CvtPixToPlane
  - CvtPlaneToPix
  - ConvertScale
  - ConvertScaleAbs
  - Add
  - AddS
  - Sub
  - SubS
  - SubRS
  - Mul
  - Div
  - And
  - AndS
  - Or
  - OrS
  - Xor
  - XorS
  - Not
  - Cmp
  - CmpS
  - InRange
  - InRangeS
  - Max
  - MaxS
  - Min
  - MinS
  - AbsDiff
  - AbsDiffS
- Array statistics
  - CountNonZero
  - Sum
  - Avg
  - AvgSdv
  - MinMaxLoc
  - Norm
- Matrix Operations, Linear Algebra and Math Functions
  - SetIdentity
  - DotProduct
  - CrossProduct
  - ScaleAdd
  - MatMulAdd
  - GEMM
  - MatMulAddS
  - MulTransposed
  - Trace
  - Transpose
  - Det
  - Invert
  - Solve
  - SVD
  - SVBkSb
  - EigenVV
  - PerspectiveTransform
  - CalcCovarMatrix
  - Mahalonobis
  - CartToPolar
  - PolarToCart
  - Pow
  - Exp
  - Log
  - CheckArr
  - RandInit
  - RandSetRange
  - Rand
  - RandNext
  - DFT
  - MulCss
  - DCT
- Dynamic Data Structures
  - MemStorage
  - MemBlock
  - MemStoragePos
  - CreateMemStorage
  - CreateChildMemStorage
  - ReleaseMemStorage
  - ClearMemStorage
  - MemStorageAlloc
  - SaveMemStoragePos
  - RestoreMemStoragePos
- Sequences
  - Seq
  - SeqBlock
  - CreateSeq
  - SetSeqBlockSize
  - SeqPush
  - SeqPop
  - SeqPushFront
  - SeqPopFront
  - SeqPushMulti
  - SeqPopMulti
  - SeqInsert
  - SeqRemove
  - ClearSeq
  - GetSeqElem
  - SeqElemIdx
  - tSeqToArray
  - MakeSeqHeaderForArray
  - SeqSlice
  - SeqRemoveSlice
  - SeqInsertSlice
  - SeqInvert
  - SeqSort
  - StartAppendToSeq
  - StartWriteSeq
  - EndWriteSeq
  - FlushSeqWriter
  - StartReadSeq
  - GetSeqReaderPos
  - SetSeqReaderPos
- Sets
  - Set
  - CreateSet
  - SetAdd
  - SetRemove
  - SetNew
  - SetRemoveByPtr
  - GetSetElem
  - ClearSet
- Graphs
  - Graph
  - CreateGraph
  - GraphAddVtx
  - GraphRemoveVtx
  - GraphRemoveVtxByPtr
  - GetGraphVtx
  - GraphVtxIdx
  - GraphAddEdge
  - GraphAddEdgeByPtr
  - GraphRemoveEdge
  - GraphRemoveEdgeByPtr
  - FindGraphEdge
  - FindGraphEdgeByPtr
  - GraphEdgeIdx
  - GraphVtxDegree
  - GraphVtxDegreeByPtr
  - ClearGraph
  - CloneGraph
  - GraphScanner
  - StartScanGraph
  - NextGraphItem
  - EndScanGraph
- Trees
  - TreeNodeIterator
  - InitTreeNodeIterator
  - NextTreeNode
  - PrevTreeNode
  - TreeToNodeSeq
  - InsertNodeIntoTree
  - RemoveNodeFromTree
- Persistence (Writing and Reading Structures)
  - OpenFileStorage
  - ReleaseFileStorage
  - Write
  - StartWriteStruct
  - EndWriteStruct
  - WriteElem
  - Read
  - ReadElem
  - FileNode
  - GetFileNode
  - ReadFileNode

## Helper structures

### CvPoint

2D point with integer coordinates

        typedef struct CvPoint
        {
            int x; /* x-coordinate, usually zero-based */
            int y; /* y-coordinate, usually zero-based */
        }
        CvPoint;

        /* the constructor function */
        inline CvPoint cvPoint( int x, int y );

        /* conversion from CvPoint2D32f */
        inline CvPoint cvPointFrom32f( CvPoint2D32f point );

### CvPoint2D32f

2D point with floating-point coordinates

        typedef struct CvPoint2D32f
        {
            float x; /* x-coordinate, usually zero-based */
            float y; /* y-coordinate, usually zero-based */
        }
        CvPoint2D32f;

        /* the constructor function */
        inline CvPoint2D32f cvPoint2D32f( double x, double y );

        /* conversion from CvPoint */
        inline CvPoint2D32f cvPointTo32f( CvPoint point );

### CvPoint3D32f

3D point with floating-point coordinates

        typedef struct CvPoint3D32f
        {
            float x; /* x-coordinate, usually zero-based */
            float y; /* y-coordinate, usually zero-based */
            float z; /* z-coordinate, usually zero-based */
        }
        CvPoint3D32f;

        /* the constructor function */
        inline CvPoint3D32f cvPoint3D32f( double x, double y, double z );

### CvSize

pixel-accurate size of a rectangle

        typedef struct CvSize
        {
            int width; /* width of the rectangle */
            int height; /* height of the rectangle */
        }
        CvSize;

        /* the constructor function */
        inline CvSize cvSize( int width, int height );

### CvSize2D32f

sub-pixel accurate size of a rectangle

        typedef struct CvSize2D32f
        {
            float width; /* width of the box */
            float height; /* height of the box */
        }
        CvSize2D32f;

        /* the constructor function */
        inline CvSize2D cvSize32f( double width, double height );

### CvRect

offset and size of a rectangle

        typedef struct CvRect
        {
            int x; /* x-coordinate of the left-most rectangle corner[s] */
            int y; /* y-coordinate of the top-most or bottom-most
                      rectangle corner[s] */
            int width; /* width of the rectangle */
            int height; /* height of the rectangle */
        }
        CvRect;

        /* the constructor function */
        inline CvRect cvRect( int x, int y, int width, int height );

### CvScalar

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

        typedef struct CvScalar
        {
            double val[4];
        }
        CvScalar;

        /* the constructor function: initializes val[0] with val0, val[1] with val1 etc. */
        inline CvScalar cvScalar( double val0, double val1=0,
                                  double val2=0, double val3=0 );
        /* the constructor function: initializes val[0]...val[3] with val0123 */
        inline CvScalar cvScalarAll( double val0123 );

        /* the constructor function: initializes val[0] with val0, val[1]...val[3] with zeros */
        inline CvScalar cvRealScalar( double val0 );

## Array structures

### CvMat

Multi-channel matrix

        typedef struct CvMat
        {
            int type; /* CvMat signature (CV_MAT_MAGIC_VAL), element type and flags */
            int step; /* full row length in bytes */

            int* refcount; /* underlying data reference counter */

            union
            {
                uchar* ptr;
                short* s;
                int* i;
                float* fl;
                double* db;
            } data; /* data pointers */

        #ifdef __cplusplus
            union
            {
                int rows;
                int height;
            };

            union
            {
                int cols;
                int width;
            };
        #else
            int rows; /* number of rows */
            int cols; /* number of columns */
        #endif

        } CvMat;

### CvMatND

Multi-dimensional dense multi-channel array

        typedef struct CvMatND
        {
            int type; /* CvMatND signature (CV_MATND_MAGIC_VAL), element type and flags */
            int dims; /* number of array dimensions */

            int* refcount; /* underlying data reference counter */

            union
            {
                uchar* ptr;
                short* s;
                int* i;
                float* fl;
                double* db;
            } data; /* data pointers */

            /* pairs (number of elements, distance between elements in bytes) for
               every dimension */
            struct
            {
                int size;
                int step;
            }
            dim[CV_MAX_DIM];

        } CvMatND;

### CvSparseMat

Multi-dimensional sparse multi-channel array

        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]; /* array of dimension sizes */

        } CvSparseMat;

### IplImage

IPL image header

        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_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;

The structure IplImage came from Intel Image Processing Library where the format is native. OpenCV supports only subset of the possible IplImage formats:

- `alphaChannel` is ignored by OpenCV.
- `colorModel` and `channelSeq` are ignored by OpenCV. The single OpenCV function cvCvtColor working with color spaces takes the source and destination color spaces as a parameter.
- `dataOrder` 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.
- `align` is ignored by OpenCV, while `widthStep` is used to access to subsequent image rows.
- `maskROI` 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.
- `tileInfo` is not supported.
- `BorderMode` and `BorderConst` are not supported. Every OpenCV function working with a pixel neigborhood uses a single hard-coded border mode (most often, replication).

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 cvPyrDown destination width(height) must be equal to source width(height) divided by 2 ±1), whereas IPL processes the intersection area - that is, the sizes or ROI sizes of all images may vary independently.

### CvArr

Arbitrary array

        typedef void CvArr;

CvArr* is used only as a function parameter to specify that the function accepts arrays of more than a single type, for example IplImage* and CvMat*. The particular array type is determined in runtime from looking at the first 4-byte field of array header.

## Arrays: Allocation, deallocation, copying; setting and retrieving parts

### Alloc

Allocates memory buffer

    void* cvAlloc( size_t size );

size
  Buffer size in bytes.

The function cvAlloc allocates size bytes and returns pointer to the allocated buffer. In case of error the function reports an error and returns NULL pointer. By default cvAlloc calls icvAlloc which itself calls malloc, however it is possible to assign user-defined memory allocation/deallocation functions using cvSetMemoryManager function.

### Free

Deallocates memory buffer

    void cvFree( void** buffer );

buffer
  Double pointer to released buffer.

The function cvFree deallocates memory buffer allocated by cvAlloc. It clears the pointer to buffer upon exit, that is why the double pointer is used. If *buffer is already NULL, the function does nothing

### CreateImage

Creates header and allocates data

    IplImage* cvCreateImage( CvSize size, int depth, int channels );

size
  Image width and height.
depth
  Bit depth of image elements. Can be one of:
  IPL_DEPTH_8U - unsigned 8-bit integers
  IPL_DEPTH_8S - signed 8-bit integers
  IPL_DEPTH_16S - signed 16-bit integers
  IPL_DEPTH_32S - signed 32-bit integers
  IPL_DEPTH_32F - single precision floating-point numbers
  IPL_DEPTH_64F - double precision floating-point numbers
channels
  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:
  b0 g0 r0 b1 g1 r1 ...
  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.

The function cvCreateImage creates the header and allocates data. This call is a shortened form of

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

### CreateImageHeader

Allocates, initializes, and returns structure IplImage

    IplImage* cvCreateImageHeader( CvSize size, int depth, int channels );

size
  Image width and height.
depth
  Image depth (see CreateImage).
channels
  Number of channels (see CreateImage).

The function cvCreateImageHeader allocates, initializes, and returns the structure IplImage. This call is an analogue of

      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);

though it does not use IPL functions by default (see also CV_TURN_ON_IPL_COMPATIBILITY macro)

### ReleaseImageHeader

Releases header

    void cvReleaseImageHeader( IplImage** image );

image
  Double pointer to the deallocated header.

The function cvReleaseImageHeader releases the header. This call is an analogue of

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

though it does not use IPL functions by default (see also CV_TURN_ON_IPL_COMPATIBILITY)

### ReleaseImage

Releases header and image data

    void cvReleaseImage( IplImage** image );

image
  Double pointer to the header of the deallocated image.

The function cvReleaseImage releases the header and the image data. This call is a shortened form of

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

### InitImageHeader

Initializes allocated by user image header

    void cvInitImageHeader( IplImage* image, CvSize size, int depth,
                            int channels, int origin, int align );

image
  Image header to initialize.
size
  Image width and height.
depth
  Image depth (see CreateImage).
channels
  Number of channels (see CreateImage).
origin
  IPL_ORIGIN_TL or IPL_ORIGIN_BL.
align
  Alignment for image rows, typically 4 or 8 bytes.

The function cvInitImageHeader initializes the image header structure without memory allocation.

### CloneImage

Makes a full copy of image

    IplImage* cvCloneImage( const IplImage* image );

image
  Original image.

The function cvCloneImage makes a full copy of the image including header, ROI and data

### SetImageCOI

Sets channel of interest to given value

    void cvSetImageCOI( IplImage* image, int coi );

image
  Image header.
coi
  Channel of interest.

The function cvSetImageCOI 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 NULL and coi != 0, ROI is allocated. Note that most of OpenCV functions do not support COI, so to process separate image/matrix channel one may copy (via cvCopy or cvCvtPixToPlane) the channel to separate image/matrix, process it and copy the result back (via cvCopy or cvCvtPlaneToPix) if need.

### GetImageCOI

Returns index of channel of interest

    int cvGetImageCOI( const IplImage* image );

image
  Image header.

The function cvGetImageCOI returns channel of interest of the image (it returns 0 if all the channels are selected).

### SetImageROI

Sets image ROI to given rectangle

    void cvSetImageROI( IplImage* image, CvRect rect );

image
  Image header.
rect
  ROI rectangle.

The function cvSetImageROI sets the image ROI to a given rectangle. If ROI is NULL and the value of the parameter rect 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)

### ResetImageROI

Releases image ROI

    void cvResetImageROI( IplImage* image );

image
  Image header.

The function cvResetImageROI releases image ROI. After that the whole image is considered selected. The similar result can be achieved by

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

But the latter variant does not deallocate image->roi.

### GetImageROI

Returns image ROI coordinates

    CvRect cvGetImageROI( const IplImage* image );

image
  Image header.

The function cvGetImageROI returns image ROI coordinates. The rectangle cvRect(0,0,image->width,image->height) is returned if there is no ROI

### CreateMat

Creates new matrix

    CvMat* cvCreateMat( int rows, int cols, int type );

rows
  Number of rows in the matrix.
cols
  Number of columns in the matrix.
type
  Type of the matrix elements. Usually it is specified in form CV_<bit_depth>(S|U|F)C<number_of_channels>, for example:
  CV_8UC1 means an 8-bit unsigned single-channel matrix, CV_32SC2 means a 32-bit signed matrix with two channels.

The function cvCreateMat allocates header for the new matrix and underlying data, and returns a pointer to the created matrix. It is a short form for:

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

Matrices are stored row by row. All the rows are aligned by 4 bytes.

### CreateMatHeader

Creates new matrix header

    CvMat* cvCreateMatHeader( int rows, int cols, int type );

rows
  Number of rows in the matrix.
cols
  Number of columns in the matrix.
type
  Type of the matrix elements (see cvCreateMat).

The function cvCreateMatHeader allocates new matrix header and returns pointer to it. The matrix data can further be allocated using cvCreateData or set explicitly to user-allocated data via cvSetData.

### ReleaseMat

Deallocates matrix

    void cvReleaseMat( CvMat** mat );

mat
  Double pointer to the matrix.

The function cvReleaseMat decrements the matrix data reference counter and releases matrix header:

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

### InitMatHeader

Initializes matrix header

    void cvInitMatHeader( CvMat* mat, int rows, int cols, int type,
                          void* data=0, int step=CV_AUTOSTEP );

mat
  Pointer to the matrix header to be initialized.
rows
  Number of rows in the matrix.
cols
  Number of columns in the matrix.
type
  Type of the matrix elements.
data
  Optional data pointer assigned to the matrix header.
step
  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.

The function cvInitMatHeader initializes already allocated CvMat structure. It can be used to process raw data with OpenCV matrix functions.

For example, the following code computes matrix product of two matrices, stored as ordinary arrays.

Calculating Product of Two Matrices

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

### Mat

Initializes matrix header (light-weight variant)

    CvMat cvMat( int rows, int cols, int type, void* data = 0 );

rows
  Number of rows in the matrix.
cols
  Number of columns in the matrix.
type
  Type of the matrix elements (see CreateMat).
data
  Optional data pointer assigned to the matrix header.

The function cvMat is a fast inline substitution for cvInitMatHeader. Namely, it is equivalent to:

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

### CloneMat

Creates matrix copy

    CvMat* cvCloneMat( const CvMat* mat );

mat
  Input matrix.

The function cvCloneMat creates a copy of input matrix and returns the pointer to it.

### CreateMatND

Creates multi-dimensional dense array

    CvMatND* cvCreateMatND( int dims, int* size, int type );

dims
  Number of array dimensions. It must not exceed CV_MAX_DIM (=16 by default, though it may be changed at build time)
size
  Array of dimension sizes.
type
  Type of array elements. The same as for CvMat

The function cvCreateMatND allocates header for multi-dimensional dense array and the underlying data, and returns pointer to the created array. It is a short form for:

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

Array data is stored row by row. All the rows are aligned by 4 bytes.

### CreateMatNDHeader

Creates new matrix header

    CvMatND* cvCreateMatNDHeader( int dims, int* size, int type );

dims
  Number of array dimensions.
size
  Array of dimension sizes.
type
  Type of array elements. The same as for CvMat

The function cvCreateMatND allocates header for multi-dimensional dense array. The array data can further be allocated using cvCreateData or set explicitly to user-allocated data via cvSetData.

### ReleaseMatND

Deallocates multi-dimensional array

    void cvReleaseMatND( CvMatND** mat );

mat
  Double pointer to the array.

The function cvReleaseMatND decrements the array data reference counter and releases the array header:

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

### InitMatNDHeader

Initializes multi-dimensional array header

    void cvInitMatNDHeader( CvMatND* mat, int dims, int* size, int type, void* data=0 );

mat
  Pointer to the array header to be initialized.
rows
  Number of rows in the matrix.
cols
  Number of columns in the matrix.
type
  Type of the matrix elements.
data
  Optional data pointer assigned to the matrix header.

The function cvInitMatNDHeader initializes already allocated CvMatND structure.

### CloneMatND

Creates full copy of multi-dimensional array

    CvMatND* cvCloneMatND( const CvMatND* mat );

mat
  Input array.

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

### DecRefData

Decrements array data reference counter

    void cvDecRefData( CvArr* array );

array
  array header.

The function cvDecRefData decrements CvMat or CvMatND 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 cvCreateData function, in other cases such as:
external data was assigned to the header using cvSetData
the matrix header presents a part of a larger matrix or image
the matrix header was converted from image or n-dimensional matrix header
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.

### IncRefData

Increments array data reference counter

    int cvIncRefData( CvArr* array );

array
  array header.

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

### CreateData

Allocates array data

    void cvCreateData( CvArr* array );

array
  Array header.

The function cvCreateData 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 CV_TURN_ON_IPL_COMPATIBILITY was called. In the latter case IPL functions are used to allocate the data

### ReleaseData

Releases array data

    void cvReleaseData( CvArr* array );

array
  Array header

The function cvReleaseData releases the array data. In case of CvMat or CvMatND it simply calls cvDecRefData(), that is the function can not deallocate external data. See also the note to cvCreateData.

### SetData

Assigns user data to the array header

    void cvSetData( CvArr* array, void* data, int step );

array
  Array header.
data
  User data.
step
  Full row length in bytes.

The function cvSetData assigns user data to the array header. Header should be initialized before using cvCreate*Header, cvInit*Header or cvMat (in case of matrix) function.

### GetRawData

Retrieves low-level information about the array

    void cvGetRawData( const CvArr* array, uchar** data,
                       int* step, CvSize* roiSize );

array
  Array header.
data
  Output pointer to the whole image origin or ROI origin if ROI is set.
step
  Output full row length in bytes.
roiSize
  Output ROI size.

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

The following example shows how to get access to array elements using this function.

Using GetRawData to calculate absolute value of elements of a single-channel floating-point array.

        float* data;
        int step;

        CvSize size;
        int x, y;

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

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

### GetMat

Returns matrix header for arbitrary array

    CvMat* cvGetMat( const CvArr* arr, CvMat* mat, int* coi = 0, int allowND );

arr
  Input array.
mat
  Pointer to CvMat structure used as a temporary buffer.
coi
  Optional output parameter for storing COI.
allowND
  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.

The function cvGetMat returns matrix header for the input array that can be matrix - CvMat*, image - IplImage* or multi-dimensional dense array - CvMatND* (latter case 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 mat structure with parameters of the current image ROI and returns pointer to this temporary structure. Because COI is not supported by CvMat, it is returned separately.

The function provides an easy way to handle both types of array - IplImage and CvMat -, using the same code. Reverse transform from CvMat to IplImage can be done using cvGetImage function.

Input array must have underlying data allocated or attached, otherwise the function fails.

If the input array is IplImage 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.

### GetImage

Returns image header for arbitrary array

    IplImage* cvGetImage( const CvArr* arr, IplImage* image_header );

arr
  Input array.
image_header
  Pointer to IplImage structure used as a temporary buffer.

The function cvGetImage returns image header for the input array that can be matrix - CvMat*, or image - IplImage*. In the case of image the function simply returns the input pointer. In the case of CvMat* it initializes image_header structure with parameters of the input matrix. Note that if we transform IplImage to CvMat 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.

### GetSubRect

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

    CvMat* cvGetSubRect( const CvArr* array, CvMat* subarr, CvRect rect );

array
  Input array.
subarr
  Pointer to the resultant subarray header.
rect
  Zero-based coordinates of the rectangle of interest.

The function cvGetSubRect 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 really extracted.

### GetRow, GetRows

Returns array row or row span

    CvMat* cvGetRow( const CvArr* arr, CvMat* subarr, int row );
    CvMat* cvGetRows( const CvArr* arr, CvMat* subarr, int start_row, end_row );

arr
  Input array.
subarr
  Pointer to the resulting sub-array header.
row
  Zero-based index of the selected row.
start_row
  Zero-based index of the starting row (inclusive) of the span.
end_row
  Zero-based index of the ending row (exclusive) of the span.

The functions GetRow and GetRows return the header, corresponding to a specified row/row span of the input array. Note that GetRow is a shortcut for cvGetRows:

    cvGetRow( arr, subarr, row ); // ~ cvGetRows( arr, subarr, row, row + 1 );

### GetCol, GetCols

Returns array column or column span

    CvMat* cvGetCol( const CvArr* arr, CvMat* subarr, int col );
    CvMat* cvGetCols( const CvArr* arr, CvMat* subarr, int start_col, end_col );

arr
  Input array.
subarr
  Pointer to the resulting sub-array header.
col
  Zero-based index of the selected column.
start_col
  Zero-based index of the starting column (inclusive) of the span.
end_col
  Zero-based index of the ending column (exclusive) of the span.

The functions GetCol and GetCols return the header, corresponding to a specified column/column span of the input array. Note that GetCol is a shortcut for cvGetCols:

    cvGetCol( arr, subarr, col ); // ~ cvGetCols( arr, subarr, col, col + 1 );

### GetDiag

Returns one of array diagonals

    CvMat* cvGetDiag( const CvArr* arr, CvMat* subarr, int diag=0 );

arr
  Input array.
subarr
  Pointer to the resulting sub-array header.
diag
  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.

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

### GetSize

Returns size of matrix or image ROI

    CvSize cvGetSize( const CvArr* arr );

arr
  array header.

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

### CreateSparseMat

Creates sparse array

    CvSparseMat* cvCreateSparseMat( int dims, int* size, int type );

dims
  Number of array dimensions. It must not exceed CV_MAX_DIM (=16 by default, though it may be changed at build time)
size
  Array of dimension sizes.
type
  Type of array elements. The same as for CvMat

The function cvCreateSparseMat allocates multi-dimensional sparse array. Initially the array contain no elements, that is cvGet*D will return zero for every index

### ReleaseSparseMat

Deallocates sparse array

    void cvReleaseSparseMat( CvSparseMat** mat );

mat
  Double pointer to the array.

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

### CloneSparseMat

Creates full copy of sparse array

    CvSparseMat* cvCloneSparseMat( const CvSparseMat* mat );

mat
  Input array.

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

### InitSparseMatIterator

Initializes sparse array elements iterator

    CvSparseMat* cvInitSparseMatIterator( const CvSparseMat* mat, CvSparseMatIterator* matIterator );

mat
  Input array.
matIterator
  Initialized iterator.

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

### GetNextSparseNode

Initializes sparse array elements iterator

    CvSparseMat* cvGetNextSparseNode( CvSparseMatIterator* matIterator );

matIterator
  Sparse array iterator.

The function cvGetNextSparseNode 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:

Using cvInitSparseMatIterator and cvGetNextSparseNode to calculate sum of floating-point sparse array.

        double sum;
        int i, dims = cvGetDims( array );
        CvSparseMatIterator matIterator;
        CvSparseNode* node = cvInitSparseMatIterator( array, &matIterator );

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

            sum += val;
        }

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

### GetElemType

Returns type of array elements

    int cvGetElemType( const CvArr* arr );

arr
  Input array.

The functions GetElemType returns type of the array elements as it is described in cvCreateMat discussion:

    CV_8UC1 ... CV_64FC4

### GetDims, GetDimSize

Return number of array dimensions and their sizes or the size of particular dimension

    int cvGetDims( const CvArr* arr, int* size=0 );
    int cvGetDimSize( const CvArr* arr, int index );

arr
  Input array.
size
  Optional output vector of the array dimension sizes. For 2d arrays the number of rows (height) goes first, number of columns (width) next.
index
  Zero-based dimension index (for matrices 0 means number of rows, 1 means number of columns; for images 0 means height, 1 means width).

The function cvGetDims returns number of array dimensions and their sizes. In case of IplImage or CvMat it always returns 2 regardless of number of image/matrix rows. The function cvGetDimSize returns the particular dimension size (number of elements per that dimension). For example, the following code calculates total number of array elements:

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

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

### Ptr*D

Return pointer to the particular array element

    uchar* cvPtr1D( const CvArr* arr, int idx0, int* type=0 );
    uchar* cvPtr2D( const CvArr* arr, int idx0, int idx1, int* type=0 );
    uchar* cvPtr3D( const CvArr* arr, int idx0, int idx1, int idx2, int* type=0 );
    uchar* cvPtrND( const CvArr* arr, int* idx, int* type=0 );

arr
  Input array.
idx0
  The first zero-based component of the element index
idx1
  The second zero-based component of the element index
idx2
  The third zero-based component of the element index
idx
  Array of the element indices
type
  Optional output parameter: type of matrix elements

The functions cvPtr*D return pointer to the particular 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 (cvGet[Real]*D, cvSet[Real]*D) raise an error in case if the element index is out of range.

### Get*D

Return the particular array element

    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, int* idx );

arr
  Input array.
idx0
  The first zero-based component of the element index
idx1
  The second zero-based component of the element index
idx2
  The third zero-based component of the element index
idx
  Array of the element indices

The functions cvGet*D 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)

### GetReal*D

Return the particular element of single-channel array

    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, int* idx );

arr
  Input array. Must have a single channel.
idx0
  The first zero-based component of the element index
idx1
  The second zero-based component of the element index
idx2
  The third zero-based component of the element index
idx
  Array of the element indices

The functions cvGetReal*D return the particular element of single-channel array. If the array has multiple channels, runtime error is raised. Note that cvGet*D function can be used safely for both single-channel and multiple-channel arrays though they are a bit slower.

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

### mGet

Return the particular element of single-channel floating-point matrix

    double cvmGet( const CvMat* mat, int row, int col );

mat
  Input matrix.
row
  The zero-based index of row.
col
  The zero-based index of column.

The function cvmGet is a fast replacement for cvGetReal2D 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.

### Set*D

Change the particular array element

    void cvSet1D( CvArr* arr, int idx0, CvScalar new_value );
    void cvSet2D( CvArr* arr, int idx0, int idx1, CvScalar new_value );
    void cvSet3D( CvArr* arr, int idx0, int idx1, int idx2, CvScalar new_value );
    void cvSetND( CvArr* arr, int* idx, CvScalar new_value );

arr
  Input array.
idx0
  The first zero-based component of the element index
idx1
  The second zero-based component of the element index
idx2
  The third zero-based component of the element index
idx
  Array of the element indices
new_value
  The assigned value

The functions cvSet*D 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

### SetReal*D

Change the particular array element

    void cvSetReal1D( CvArr* arr, int idx0, double new_value );
    void cvSetReal2D( CvArr* arr, int idx0, int idx1, double new_value );
    void cvSetReal3D( CvArr* arr, int idx0, int idx1, int idx2, double new_value );
    void cvSetRealND( CvArr* arr, int* idx, double new_value );

arr
  Input array.
idx0
  The first zero-based component of the element index
idx1
  The second zero-based component of the element index
idx2
  The third zero-based component of the element index
idx
  Array of the element indices
new_value
  The assigned value

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

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

### mSet

Return the particular element of single-channel floating-point matrix

    void cvmSet( CvMat* mat, int row, int col, double value );

mat
  The matrix.
row
  The zero-based index of row.
col
  The zero-based index of column.
value
  The new value of the matrix element

The function cvmSet is a fast replacement for cvSetReal2D 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.

### Clear*D

Clears the particular array element

    void cvClearND( CvArr* arr, int* idx );

arr
  Input array.
idx
  Array of the element indices

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

### Copy

Copies one array to another

    void cvCopy( const CvArr* A, CvArr* B, const CvArr* mask =0);

A
  The source array.
B
  The destination array.
mask
  Operation mask, 8-bit single channel array; specifies elements of destination array to be changed.

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

B(I)=A(I) if mask(I)!=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).

### Set

Sets every element of array to given value

    void cvSet( CvArr* A, CvScalar S, const CvArr* mask=0 );

A
  The destination array.
S
  Fill value.
mask
  Operation mask, 8-bit single channel array; specifies elements of destination array to be changed.

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

    A(I)=S if mask(I)!=0

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

### SetZero

Clears the array

    void cvSetZero( CvArr* arr );
    #define cvZero cvSetZero

arr
  array to be cleared.

The function cvSetZero clears the array. In case of dense arrays (CvMat, CvMatND or IplImage) cvZero(array) is equivalent to cvSet(array,cvScalarAll(0),0), but the function can clear sparse arrays by removing all the array elements

## Arrays: Conversions, transformations, basic operations

### Reshape

Changes shape of matrix/image without copying data

    CvMat* cvReshape( const CvArr* array, CvMat* header, int new_cn, int new_rows=0 );

array
  Input array.
header
  Output header to be filled.
new_cn
  New number of channels. new_cn = 0 means that number of channels remains unchanged.
new_rows
  New number of rows. new_rows = 0 means that number of rows remains unchanged unless it needs to be changed according to new_cn value. destination array to be changed.

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

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:

    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 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 shape of multi-dimensional array w/o copying data

    CvArr* cvReshapeMatND( const CvArr* array,
                           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))

array
  Input array.
sizeof_header
  Size of output header to distinguish between IplImage, CvMat and CvMatND output headers.
header
  Output header to be filled.
new_cn
  New number of channels. new_cn = 0 means that number of channels remains unchanged.
new_dims
  New number of dimensions. new_dims = 0 means that number of dimensions remains the same.
new_sizes
  Array of new dimension sizes. Only new_dims-1 values are used, because the total number of elements must remain the same. Thus, if new_dims = 1, new_sizes array is not used

The function cvReshapeMatND is an advanced version of cvReshape 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 cvReshape description rewritten using cvReshapeMatND:

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

### Repeat

Fill destination array with tiled source array

    void cvRepeat( const CvArr* A, CvArr* B );

A
  Source array, image or matrix.
B
  Destination array, image or matrix.

The function cvRepeat fills the destination array with source array tiled:

    B(i,j)=A(i%rows(A), j%cols(A))

where "%" means "modulo" operation. So the destination array may be as larger as well as smaller than the source array.

### Flip

Flip a 2D array around vertical, horizontall or both axises

    void  cvFlip( const CvArr* A, CvArr* B=0, int flip_mode=0);
    #define cvMirror cvFlip

A
  Source array.
B
  Destination array. If dst = NULL the flipping is done inplace.
flip_mode
  Specifies how to flip the array.
  flip_mode = 0 means flipping around x-axis, flip_mode > 0 (e.g. 1) means flipping around y-axis and flip_mode < 0 (e.g. -1) means flipping around both axises. See also the discussion below for the formulas

The function cvFlip flips the array in one of different 3 ways (row and column indices are 0-based):

    B(i,j)=A(rows(A)-i-1,j) if flip_mode = 0

    B(i,j)=A(i,cols(A)-j-1) if flip_mode > 0

    B(i,j)=A(rows(A)-i-1,cols(A)-j-1) if flip_mode < 0

The typical scenaria of the function use are:

- 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.
- horizontal flipping of the image with subsequent horizontal shift and absolute difference calculation to check for a vertical-axis symmetry (flip_mode > 0)
- simultaneous horizontal and vertical flipping of the image with subsequent shift and absolute difference calculation to check for a central symmetry (flip_mode < 0)
- reversing the order of 1d point arrays(flip_mode > 0)

### CvtPixToPlane

Divides multi-channel array into several single-channel arrays or extracts a single channel from the array

    void cvCvtPixToPlane( const CvArr* src, CvArr* dst0, CvArr* dst1,
                          CvArr* dst2, CvArr* dst3 );

src
  Source array.
dst0...dst3
  Destination channels.

The function cvCvtPixToPlane divides a multi-channel array into separate single-channel arrays. Two modes are available for the operation. If the source array has N channels then if the first N destination channels are not NULL, all they are extracted from the source array, otherwise if only a single destination channel of the first N is not NULL, this particular channel is extracted, otherwise an error is raised. Rest of destination channels (beyond the first N) must always be NULL. For IplImage cvCopy with COI set can be also used to extract a single channel from the image.

### CvtPlaneToPix

Composes multi-channel array from several single-channel arrays or inserts a single channel into the array

    void cvCvtPlaneToPix( const CvArr* src0, const CvArr* src1,
                          const CvArr* src2, const CvArr* src3, CvArr* dst );

src0... src3
  Input channels.
dst
  Destination array.

The function cvCvtPlaneToPix is the opposite to the previous. If the destination array has N channels then if the first N input channels are not NULL, all they are copied to the destination array, otherwise if only a single source channel of the first N is not NULL, this particular channel is copied into the destination array, otherwise an error is raised. Rest of source channels (beyond the first N) must always be NULL. For IplImage cvCopy with COI set can be also used to insert a single channel into the image.

### ConvertScale

Converts one array to another with optional linear transformation

    void cvConvertScale( const CvArr* A, CvArr* B, double scale=1, double shift=0 );

    #define cvCvtScale cvConvertScale
    #define cvScale  cvConvertScale
    #define cvConvert( A, B )  cvConvertScale( (A), (B), 1, 0 )

A
  Source array.
B
  Destination array.
scale
  Scale factor.
shift
  Value added to the scaled source array elements.

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

    B(I)=A(I)*scale + (shift,shift,...)

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

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

In case of scale=1, shift=0 no prescaling is done. This is a specially optimized case and it has the appropriate cvConvert synonym. If source and destination array types have equal types, this is also a special case that can be used to scale and shift a matrix or an image and that fits to cvScale synonym.

### ConvertScaleAbs

Converts input array elements to 8-bit unsigned integer another with optional linear transformation

    void cvConvertScaleAbs( const CvArr* A, CvArr* B, double scale=1, double shift=0 );
    #define cvCvtScaleAbs cvConvertScaleAbs

A
  Source array.
B
  Destination array (should have 8u depth).
scale
  ScaleAbs factor.
shift
  Value added to the scaled source array elements.

The function cvConvertScaleAbs is similar to the previous one, but it stores absolute values of the conversion results:

    B(I)=abs(A(I)*scale + (shift,shift,...))

The function supports only destination arrays of 8u (8-bit unsigned integers) type, for other types the function can be emulated by combination of cvConvertScale and cvAbs functions.

### Add

Computes per-element sum of two arrays

    void cvAdd( const CvArr* A, const CvArr* B, CvArr* C, const CvArr* mask=0);

A
  The first source array.
B
  The second source array.
C
  The destination array.
mask
  Operation mask, 8-bit single channel array; specifies elements of destination array to be changed.

The function cvAdd adds one array to another one:

    C(I)=A(I)+B(I) if mask(I)!=0

All the arrays must have the same type, except the mask, and the same size (or ROI size)

### AddS

Computes sum of array and scalar

    void cvAddS( const CvArr* A, CvScalar S, CvArr* C, const CvArr* mask=0 );

A
  The source array.
S
  Added scalar.
C
  The destination array.
mask
  Operation mask, 8-bit single channel array; specifies elements of destination array to be changed.

The function cvAddS adds scalar S to every element in the source array A and stores the result in C

    C(I)=A(I)+S if mask(I)!=0

All the arrays must have the same type, except the mask, and the same size (or ROI size)

### Sub

Computes per-element difference of two arrays

    void cvSub( const CvArr* A, const CvArr* B, CvArr* C, const CvArr* mask=0);

A
  The first source array.
B
  The second source array.
C
  The destination array.
mask
  Operation mask, 8-bit single channel array; specifies elements of destination array to be changed.

The function cvSub subtracts one array from another one:

    C(I)=A(I)-B(I) if mask(I)!=0

All the arrays must have the same type, except the mask, and the same size (or ROI size)

### SubS

Computes difference of array and scalar

    void cvSubS( const CvArr* A, CvScalar S, CvArr* C, const CvArr* mask=0 );

A
  The source array.
S
  Subed scalar.
C
  The destination array.
mask
  Operation mask, 8-bit single channel array; specifies elements of destination array to be changed.

The function cvSubS subtracts a scalar from every element of the source array:

    C(I)=A(I)+S if mask(I)!=0

All the arrays must have the same type, except the mask, and the same size (or ROI size)

### SubRS

Computes difference of scalar and array

    void cvSubRS( const CvArr* A, CvScalar S, CvArr* C, const CvArr* mask=0 );

A
  The first source array.
S
  Scalar to subtract from.
C
  The destination array.
mask
  Operation mask, 8-bit single channel array; specifies elements of destination array to be changed.

The function cvSubRS subtracts every element of source array from a scalar:

    C(I)=S-A(I) if mask(I)!=0

All the arrays must have the same type, except the mask, and the same size (or ROI size)

### Mul

Calculates per-element product of two arrays

    void cvMul( const CvArr* A, const CvArr* B, CvArr* C, double scale=1 );

A
  The first source array.
B
  The second source array.
C
  The destination array.
scale
  Optional scale factor

The function cvMul calculates per-element product of two arrays:

    C(I)=scale•A(I)•B(I)

All the arrays must have the same type, and the same size (or ROI size)

### Div

Performs per-element division of two arrays

    void cvDiv( const CvArr* A, const CvArr* B, CvArr* C, double scale=1 );

A
  The first source array. If the pointer is NULL, the array is assumed to be all 1's.
B
  The second source array.
C
  The destination array.
scale
  Optional scale factor

The function cvDiv divides one array by another:

    C(I)=scale•A(I)/B(I), if A!=NULL
    C(I)=scale/B(I),      if A=NULL

All the arrays must have the same type, and the same size (or ROI size)

### And

Calculates per-element bit-wise conjunction of two arrays

    void cvAnd( const CvArr* A, const CvArr* B, CvArr* C, const CvArr* mask=0 );

A
  The first source array.
B
  The second source array.
C
  The destination array.
mask
  Operation mask, 8-bit single channel array; specifies elements of destination array to be changed.

The function cvAnd calculates per-element bit-wise logical conjunction of two arrays:

    C(I)=A(I)&B(I) if mask(I)!=0

In the case of floating-point arrays their bit representations are used for the operation. All the arrays must have the same type, except the mask, and the same size

### AndS

Calculates per-element bit-wise conjunction of array and scalar

    void cvAndS( const CvArr* A, CvScalar S, CvArr* C, const CvArr* mask=0 );

A
  The source array.
S
  Scalar to use in the operation.
C
  The destination array.
mask
  Operation mask, 8-bit single channel array; specifies elements of destination array to be changed.

The function AndS calculates per-element bit-wise conjunction of array and scalar:

    C(I)=A(I)&S if mask(I)!=0

Prior to the actual operation the scalar is converted to the same type as the arrays. In the case of floating-point arrays their bit representations are used for the operation. All the arrays must have the same type, except the mask, and the same size

The following sample demonstrates how to calculate absolute value of floating-point array elements by clearing the most-significant bit:

    float a[] = { -1, 2, -3, 4, -5, 6, -7, 8, -9 };
    CvMat A = cvMat( 3, 3, CV_32F, &a );
    int i, abs_mask = 0x7fffffff;
    cvAndS( &A, cvRealScalar(*(float*)&abs_mask), &A, 0 );
    for( i = 0; i < 9; i++ )
        printf("%.1f ", a[i] );

The code should print:

    1.0 2.0 3.0 4.0 5.0 6.0 7.0 8.0 9.0

### Or

Calculates per-element bit-wise disjunction of two arrays

    void cvOr( const CvArr* A, const CvArr* B, CvArr* C, const CvArr* mask=0 );

A
  The first source array.
B
  The second source array.
C
  The destination array.
mask
  Operation mask, 8-bit single channel array; specifies elements of destination array to be changed.

The function cvOr calculates per-element bit-wise disjunction of two arrays:

    C(I)=A(I)|B(I)

In the case of floating-point arrays their bit representations are used for the operation. All the arrays must have the same type, except the mask, and the same size

### OrS

Calculates per-element bit-wise disjunction of array and scalar

    void cvOrS( const CvArr* A, CvScalar S, CvArr* C, const CvArr* mask=0 );

A
  The source array.
S
  Scalar to use in the operation.
C
  The destination array.
mask
  Operation mask, 8-bit single channel array; specifies elements of destination array to be changed.

The function OrS calculates per-element bit-wise disjunction of array and scalar:

    C(I)=A(I)|S if mask(I)!=0

Prior to the actual operation the scalar is converted to the same type as the arrays. In the case of floating-point arrays their bit representations are used for the operation. All the arrays must have the same type, except the mask, and the same size

### Xor

Performs per-element bit-wise "exclusive or" operation on two arrays

    void cvXor( const CvArr* A, const CvArr* B, CvArr* C, const CvArr* mask=0 );

A
  The first source array.
B
  The second source array.
C
  The destination array.
mask
  Operation mask, 8-bit single channel array; specifies elements of destination array to be changed.

The function cvXor calculates per-element bit-wise logical conjunction of two arrays:

    C(I)=A(I)^B(I) if mask(I)!=0

In the case of floating-point arrays their bit representations are used for the operation. All the arrays must have the same type, except the mask, and the same size

### XorS

Performs per-element bit-wise "exclusive or" operation on array and scalar

    void cvXorS( const CvArr* A, CvScalar S, CvArr* C, const CvArr* mask=0 );

A
  The source array.
S
  Scalar to use in the operation.
C
  The destination array.
mask
  Operation mask, 8-bit single channel array; specifies elements of destination array to be changed.

The function XorS calculates per-element bit-wise conjunction of array and scalar:

    C(I)=A(I)^S if mask(I)!=0

Prior to the actual operation the scalar is converted to the same type as the arrays. In the case of floating-point arrays their bit representations are used for the operation. All the arrays must have the same type, except the mask, and the same size

The following sample demonstrates how to conjugate complex vector by switching the most-significant bit of imaging part:

    float a[] = { 1, 0, 0, 1, -1, 0, 0, -1 }; /* 1, j, -1, -j */
    CvMat A = cvMat( 4, 1, CV_32FC2, &a );
    int i, neg_mask = 0x80000000;
    cvXorS( &A, cvScalar( 0, *(float*)&neg_mask, 0, 0 ), &A, 0 );
    for( i = 0; i < 4; i++ )
        printf("(%.1f, %.1f) ", a[i*2], a[i*2+1] );

The code should print:

    (1.0,0.0) (0.0,-1.0) (-1.0,0.0) (0.0,1.0)

### Not

Performs per-element bit-wise inversion of array elements

    void cvNot( const CvArr* A, CvArr* C );

A
  The source array.
C
  The destination array.

The function Not inverses every bit of every array element:

    C(I)=~A(I)

### Cmp

Performs per-element comparison of two arrays

    void cvCmp( const CvArr* A, const CvArr* B, CvArr* C, int cmp_op );

A
  The first source array.
B
  The second source array. Both source array must have a single channel.
C
  The destination array, must have 8u or 8s type.
cmp_op
  The flag specifying the relation between the elements to be checked:
  CV_CMP_EQ - A(I) "equal to" B(I)
  CV_CMP_GT - A(I) "greater than" B(I)
  CV_CMP_GE - A(I) "greater or equal" B(I)
  CV_CMP_LT - A(I) "less than" B(I)
  CV_CMP_GE - A(I) "less or equal" B(I)
  CV_CMP_NE - A(I) "not equal to" B(I)

The function cvCmp compares the corresponding elements of two arrays and fills the destination mask array:

    C(I)=A(I) op B(I),

where op is '=', '>', '>=', '<', '<=' or '!='.

C(I) is set to 0xff (all '1'-bits) if the particular relation between the elements is true and 0 otherwise. All the arrays must have the same type, except the destination, and the same size (or ROI size)

### CmpS

Performs per-element comparison of array and scalar

    void cvCmpS( const CvArr* A, double S, CvArr* C, int cmp_op );

A
  The source array, must have a single channel.
C
  The destination array, must have 8u or 8s type.
cmp_op
  The flag specifying the relation between the elements to be checked:
  CV_CMP_EQ - A(I) "equal to" S
  CV_CMP_GT - A(I) "greater than" S
  CV_CMP_GE - A(I) "greater or equal" S
  CV_CMP_LT - A(I) "less than" S
  CV_CMP_GE - A(I) "less or equal" S
  CV_CMP_NE - A(I) "not equal" S

The function cvCmpS compares the corresponding elements of array and scalar and fills the destination mask array:

    C(I)=A(I) op S,

where op is '=', '>', '>=', '<', '<=' or '!='.

C(I) is set to 0xff (all '1'-bits) if the particular relation between the elements is true and 0 otherwise. All the arrays must have the same size (or ROI size)

### InRange

Checks that array elements lie between elements of two other arrays

    void cvInRange( const CvArr* A, const CvArr* L, const CvArr* U, CvArr* C );

A
  The first source array.
L
  The inclusive lower boundary array.
U
  The exclusive upper boundary array.
C
  The destination array, must have 8u or 8s type.

The function cvInRange does the range check for every element of the input array:

    C(I)=L(I)0 <= A(I)0 < U(I)0

for single-channel arrays,

    C(I)=L(I)0 <= A(I)0 < U(I)0 &&
         L(I)1 <= A(I)1 < U(I)1

for two-channel arrays etc.

C(I) is set to 0xff (all '1'-bits) if A(I) is within the range and 0 otherwise. All the arrays must have the same type, except the destination, and the same size (or ROI size)

### InRangeS

Checks that array elements lie between two scalars

    void cvInRangeS( const CvArr* A, CvScalar SL, CvScalar SU, CvArr* D );

A
  The first source array.
SL
  The inclusive lower boundary.
SU
  The exclusive upper boundary.
C
  The destination array, must have 8u or 8s type.

The function cvInRangeS does the range check for every element of the input array:

    C(I)=SL0 <= A(I)0 < SU0

for a single-channel array,

    C(I)=SL0 <= A(I)0 < SU0 &&
         SL1 <= A(I)1 < SU1

for a two-channel array etc.

C(I) is set to 0xff (all '1'-bits) if A(I) is within the range and 0 otherwise. All the arrays must have the same size (or ROI size)

### Max

Finds per-element maximum of two arrays

    void cvMax( const CvArr* A, const CvArr* B, CvArr* C );

A
  The first source array.
B
  The second source array.
C
  The destination array.

The function cvMax calculates per-element maximum of two arrays:

    C(I)=max(A(I), B(I))

All the arrays must have a single channel, the same data type and the same size (or ROI size).

### MaxS

Finds per-element maximum of array and scalar

    void cvMaxS( const CvArr* A, const CvArr* B, CvArr* C );

A
  The first source array.
B
  The second source array.
C
  The destination array.

The function cvMaxS calculates per-element maximum of array and scalar:

    C(I)=max(A(I), S)

All the arrays must have a single channel, the same data type and the same size (or ROI size).

### Min

Finds per-element minimum of two arrays

    void cvMin( const CvArr* A, const CvArr* B, CvArr* C );

A
  The first source array.
B
  The second source array.
C
  The destination array.

The function cvMin calculates per-element minimum of two arrays:

    C(I)=min(A(I),B(I))

All the arrays must have a single channel, the same data type and the same size (or ROI size).

### MinS

Finds per-element minimum of array and scalar

    void cvMinS( const CvArr* A, const CvArr* B, CvArr* C );

A
  The first source array.
B
  The second source array.
C
  The destination array.

The function cvMinS calculates minimum of array and scalar:

    C(I)=min(A(I), S)

All the arrays must have a single channel, the same data type and the same size (or ROI size).

### AbsDiff

Calculates absolute difference between two arrays

    void cvAbsDiff( const CvArr* A, const CvArr* B, CvArr* C );

A
  The first source array.
B
  The second source array.
C
  The destination array.

The function cvAbsDiff calculates absolute difference between two arrays.

    C(I)c = abs(A(I)c - B(I)c).

All the arrays must have the same data type and the same size (or ROI size).

### AbsDiffS

Calculates absolute difference between array and scalar

    void cvAbsDiffS( const CvArr* A, CvArr* C, CvScalar S );
    #define cvAbs(A, C) cvAbsDiffS(A, C, cvScalarAll(0))

A
  The source array.
C
  The destination array.
S
  The scalar.

The function cvAbsDiffS calculates absolute difference between array and scalar.

    C(I)c = abs(A(I)c - Sc).

All the arrays must have the same data type and the same size (or ROI size).

## Array statistics

### CountNonZero

Counts non-zero array elements

    int cvCountNonZero( const CvArr* A );

A
  The array, must be single-channel array or multi-channel image with COI set.

The function cvCountNonZero returns the number of non-zero elements in A:

    result = sumI A(I)!=0

In case of IplImage both ROI and COI are supported.

### Sum

Summarizes array elements

    CvScalar cvSum( const CvArr* A );

A
  The array.

The function cvSum calculates sum S of array elements, independently for each channel:

    Sc = sumI A(I)c

If the array is IplImage and COI is set, the function processes the selected channel only and stores the sum to the first scalar component (S0).

### Avg

Calculates average (mean) of array elements

    CvScalar cvAvg( const CvArr* A, const CvArr* mask=0 );

A
  The array.
mask
  The optional operation mask.

The function cvAvg calculates the average value M of array elements, independently for each channel:

    N = sumI mask(I)!=0

    Mc = 1/N • sumI A(I)c

If the array is IplImage and COI is set, the function processes the selected channel only and stores the average to the first scalar component (S0).

### AvgSdv

Calculates average (mean) of array elements

    void cvAvgSdv( const CvArr* A, CvScalar* _M, CvScalar* _S, const CvArr* mask=0 );

A
  The array.
_M
  Pointer to the mean value, may be NULL if it is not needed.
_S
  Pointer to the standard deviation.
mask
  The optional operation mask.

The function cvAvgSdv calculates the average value M=*_M and standard deviation S=*_S of array elements, independently for each channel:

    N = sumI mask(I)!=0

    Mc = 1/N • sumI A(I)c

    Sc = sqrt(1/N • sumI (A(I)c - Mc)2)

If the array is IplImage and COI is set, the function processes the selected channel only and stores the average and standard deviation to the first compoenents of output scalars (M0 and S0).

### MinMaxLoc

Finds global minimum and maximum in array or subarray

    void cvMinMaxLoc( const CvArr* A, double* minVal, double* maxVal,
                      CvPoint* minLoc, CvPoint* maxLoc, const CvArr* mask=0 );

A
  The source array, single-channel or multi-channel with COI set.
minVal
  Pointer to returned minimum value.
maxVal
  Pointer to returned maximum value.
minLoc
  Pointer to returned minimum location.
maxLoc
  Pointer to returned maximum location.
mask
  The optional mask that is used to select a subarray.

The function MinMaxLoc finds minimum and maximum element values and their positions. The extremums are searched over the whole array, selected ROI (in case of IplImage) or, if mask is not NULL, in the specified array region. If the array has more than one channel, it must be IplImage with COI set. In case if multi-dimensional arrays minLoc->x and maxLoc->x will contain raw (linear) positions of the extremums.

### Norm

Calculates absolute array norm, absolute difference norm or relative difference norm

    double cvNorm( const CvArr* A, const CvArr* B, int normType, const CvArr* mask=0 );

A
  The first source image.
B
  The second source image. If it is NULL, the absolute norm of A is calculated, otherwise absolute or relative norm of A-B is calculated.
normType
  Type of norm, see the discussion.
mask
  The optional operation mask.

The function cvNorm calculates the absolute norm of A if B is NULL:

    norm = ||A||C = maxI abs(A(I)),  if normType = CV_C

    norm = ||A||L1 = sumI abs(A(I)),  if normType = CV_L1

    norm = ||A||L2 = sqrt( sumI A(I)2),  if normType = CV_L2

And the function calculates absolute or relative difference norm if B is not NULL:

    norm = ||A-B||C = maxI abs(A(I)-B(I)),  if normType = CV_C

    norm = ||A-B||L1 = sumI abs(A(I)-B(I)),  if normType = CV_L1

    norm = ||A-B||L2 = sqrt( sumI (A(I)-B(I))2 ),  if normType = CV_L2

    or

    norm = ||A-B||C/||B||C, if normType = CV_RELATIVE_C

    norm = ||A-B||L1/||B||L1, if normType = CV_RELATIVE_L1

    norm = ||A-B||L2/||B||L2, if normType = CV_RELATIVE_L2

The function Norm returns the calculated norm. The multiple-channel array are treated as single-channel, that is results for all channels are combined.

## Matrix Operations, Linear Algebra and Math Functions

### SetIdentity

Initializes scaled identity matrix

    void cvSetIdenity( CvArr* A, CvScalar S );

A
  The matrix to initialize (not necesserily square).
S
  The value to assign to the diagonal elements.

The function cvSetIdentity initializes scaled identity matrix:

    A(i,j)=S if i=j,
           0 otherwise

### DotProduct

Calculates dot product of two arrays in Euclidian metrics

    double cvDotProduct (const CvArr* A, const CvArr* B );

A
  The first source array.
B
  The second source array.

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

    A•B = sumI(A(I)*B(I))

In case of multiple channel arrays the results for all channels are accumulated. In particular, it gives a correct result for complex matrices. The function can process multi-dimensional arrays row by row.

### CrossProduct

Calculates cross product of two 3D vectors

    void cvCrossProduct( const CvArr* A, const CvArr* B, CvArr* C );

A
  The first source vector.
B
  The second source vector.
C
  The destination vector.

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

    C = A×B, (C1 = A2B3 - A3B2 , C2 = A3B1 - A1B3 , C3 = A1B2 - A2B1).

### ScaleAdd

Calculates sum of scaled array and another array

    void cvScaleAdd( const CvArr* A, CvScalar S, const CvArr* B, CvArr* C );
    #define cvMulAddS cvScaleAdd

A
  The first source array.
S
  Scale factor for the first array.
B
  The second source array.
C
  The destination array

The function cvScaleAdd calculates sum of scaled array and another array:

    C(I)=A(I)*S + B(I)

All array parameters should be of the same size and the same size

### MatMulAdd

Calculates shifted matrix product

    void cvMatMulAdd( const CvArr* A, const CvArr* B, const CvArr* C, CvArr* D );
    #define cvMatMul(A, B, D) cvMatMulAdd(A, B, 0, D)

A
  The first source array.
B
  The second source array.
C
  The third source array (shift). Can be NULL, if there is no shift.
D
  The destination array.

The function cvMatMulAdd calculates matrix product of two matrices and adds the third matrix to the product:

    D = A*B + C   or  D(i,j)=sumk(A(i,k)*B(k,j)) + C(i,j)

All the matrices should be of the same type and the coordinated sizes. Only real or complex floating-point matrices are supported

### GEMM

Performs generalized matrix multiplication

    void  cvGEMM( const CvArr* A, const CvArr* B, double alpha,
                  const CvArr* C, double beta, CvArr* D, int tABC=0 );
    #define cvMatMulAddEx cvGEMM

A
  The first source array.
B
  The second source array.
C
  The third source array (shift). Can be NULL, if there is no shift.
D
  The destination array.
tABC
  The operation flags that can be 0 or combination of the following:
  CV_GEMM_A_T - transpose A
  CV_GEMM_B_T - transpose B
  CV_GEMM_C_T - transpose B
  for example, CV_GEMM_A_T+CV_GEMM_C_T corresponds to

      alpha*AT*B + beta*CT

The function cvGEMM performs generalized matrix multiplication:

    D = alpha*op(A)*op(B) + beta*op(C), where op(X) is X or XT

All the matrices should be of the same type and the coordinated sizes. Only real or complex floating-point matrices are supported

### MatMulAddS

Performs matrix transform on every element of array

    void cvMatMulAddS( const CvArr* A, CvArr* C, const CvArr* M, const CvArr* V=0 );

A
  The first source array.
C
  The destination array.
M
  Transformation matrix.
V
  Optional shift.

The function cvMatMulAddS performs matrix transform on every element of array A and stores the result in C:

    C(i,j)=M*A(i,j) + V   or   C(i,j)(k)=suml(M(k,l)*A(i,j)(l)) + V(k)

That is every element of N-channel array A is considered as N-element vector, which is transformed using matrix N×N matrix M and shift vector V. There is an option to code V into A. In this case A should be N×N+1 matrix and the right-most column is used as the shift vector.

Both source and destination arrays should be of the same size or selected ROI size and of the same type. M and V should be real floating-point matrices. The function can be used for geometrical transforms of point sets and linear color transformations.

### MulTransposed

Calculates product of array and transposed array

    void cvMulTransposed( const CvArr* A, CvArr* C, int order );

A
  The source matrix.
C
  The destination matrix.
order
  Order of multipliers.

The function cvMulTransposed calculates the product of A and its transposition.

The function evaluates

    C=A*AT

if order=0, and

    C=AT*A

otherwise

### Trace

Returns trace of matrix

    CvScalar cvTrace( const CvArr* A );

A
  The source matrix.

The function cvTrace returns sum of diagonal elements of the matrix A.

    tr(A)=sumiA(i,i)

### Transpose

Transposes matrix

    void cvTranspose( const CvArr* A, CvArr* B );
    #define cvT cvTranspose

A
  The source matrix.
B
  The destination matrix.

The function cvTranspose transposes matrix A:

    B(i,j)=A(j,i)

Note that no complex conjugation is done in case of complex matrix. Conjugation should be done separately: look at the sample code in cvXorS for example

### Det

Returns determinant of matrix

    CvScalar cvDet( const CvArr* A );

A
  The source matrix.

The function cvDet returns determinant of the square matrix A. The direct method is used for small matrices and Gaussian elimination is used for larger matrices

### Invert

Finds inverse or pseudo-inverse of matrix

    double cvInvert( const CvArr* A, CvArr* B, int method );
    #define cvInv cvInvert

A
  The source matrix.
B
  The destination matrix.
method
  Inversion method:
  CV_LU - Gaussian elimination with optimal pivot element chose CV_SVD - Singular decomposition method

The function cvInvert inverts matrix A and stores the result in B

In case of LU method the function returns A determinant (A must be square). If it is 0, the matrix is not inverted and B is filled with zeros.

In case of SVD method the function returns the inversed condition number of A (ratio of the smallest singular value to the largest singular value) and 0 if A is all zeros. This method calculates a pseudo-inverse matrix if A is singular

### Solve

Solves linear system or least-squares problem

    int cvSolve( const CvArr* A, const CvArr* B, CvArr* X, int method );
    #define cvInv cvSolve

A
  The source matrix.
B
  The right-hand part of the linear system.
method
  The solution (matrix inversion) method:
  CV_LU - Gaussian elimination with optimal pivot element chose CV_SVD - Singular decomposition method

The function cvSolve solves linear system or least-squares problem:

    X* = arg minX||A*X-B||

If CV_LU method is used, the function returns 1 if A is non-singular and 0 otherwise, in the latter case X is not valid

### SVD

Performs singular value decomposition of real floating-point matrix

    void cvSVD( CvArr* A, CvArr* W, CvArr* U=0, CvArr* V=0, int flags=0 );

A
  Source M×N matrix.
W
  Resulting singular value matrix (M×N or N×N) or vector (N×1).
U
  Optional left orthogonal matrix (M×M or M×N). If CV_SVD_U_T is specified, the number of rows and columns in the sentence above should be swapped.
V
  Optional right orthogonal matrix (N×N)
flags
  Operation flags; can be 0 or combination of the following:
  - CV_SVD_MODIFY_A enables modification of matrix A during the operation. It speeds up the processing.
  - CV_SVD_U_T means that the tranposed matrix U is returned. Specifying the flag speeds up the processing.
  - CV_SVD_V_T means that the tranposed matrix V is returned. Specifying the flag speeds up the processing.

The function cvSVD decomposes matrix A into a product of a diagonal matrix and two orthogonal matrices:

    A=U*W*VT

Where W is diagonal matrix of singular values that can be coded as a 1D vector of singular values and U and V. All the singular values are non-negative and sorted (together with U and and V columns) in descenting order.

SVD algorithm is numerically robust and its typical applications include:

- accurate eigenvalue problem solution when matrix A is square, symmetric and positively defined matrix, for example, when it is a covariation matrix. W in this case will be a vector of eigen values, and U=V is matrix of eigen vectors (thus, only one of U or V needs to be calculated if the eigen vectors are required)
- accurate solution of poor-conditioned linear systems
- least-squares solution of overdetermined linear systems. This and previous is done by cvSolve function with CV_SVD method
- accurate calculation of different matrix characteristics such as rank (number of non-zero singular values), condition number (ratio of the largest singular value to the smallest one), determinant (absolute value of determinant is equal to the product of singular values). All the things listed in this item do not require calculation of U and V matrices.

### SVBkSb

Performs singular value back substitution

    void  cvSVBkSb( const CvArr* W, const CvArr* U, const CvArr* V,
                    const CvArr* B, CvArr* X, int flags );

W
  Matrix or vector of singular values.
U
  Left orthogonal matrix (tranposed, perhaps)
V
  Right orthogonal matrix (tranposed, perhaps)
B
  The matrix to multiply the pseudo-inverse of the original matrix A by. This is the optional parameter. If it is omitted then it is assumed to be an identity matrix of an appropriate size (So X will be the reconstructed pseudo-inverse of A).
X
  The destination matrix: result of back substitution.
flags
  Operation flags, should match exactly to the flags passed to cvSVD.

The function cvSVBkSb calculates back substitution for decomposed matrix A (see cvSVD description) and matrix B:

    X=V*W-1*UT*B

Where

    W-1(i,j)=1/W(i,j) if W(i,j) > epsilon,
                        0        otherwise

And epsilon is a small number - ≈10-6 or ≈10-15 depending on the matrices element type.

This function together with cvSVD is used inside cvInvert and cvSolve, and the possible reason to use these (svd & bksb) "low-level" function is to avoid temporary matrices allocation inside the high-level counterparts (inv & solve).

### EigenVV

Computes eigenvalues and eigenvectors of symmetric matrix

    void cvEigenVV( CvArr* A, CvArr* evects, CvArr* evals, double eps );

A
  The source symmetric square matrix. It is modified during the processing.
evects
  The output matrix of eigenvectors, stored as a subsequent rows.
evals
  The output vector of eigenvalues, stored in the descenting order (order of eigenvalues and eigenvectors is syncronized, of course).
eps
  Accuracy of diagonalization (typically, DBL_EPSILON=≈10-15 is enough).

The function cvEigenVV computes the eigenvalues and eigenvectors of the matrix A:

    A*evects(i,:)' = evals(i)*evects(i,:)' (in MATLAB notation)

The contents of matrix A is destroyed by the function.

Currently the function is slower than cvSVD yet less accurate, so if A is known to be positively-defined (for example, it is a covariation matrix), it is recommended to use cvSVD to find eigenvalues and eigenvectors of A, especially if eigenvectors are not required.

### PerspectiveTransform

Performs perspective matrix transform on 3D vector array

    void cvPerspectiveTransform( const CvArr* A, CvArr* B, const CvArr* M );

A
  The source three-channel floating-point array.
B
  The destination three-channel floating-point array.
M
  4 × 4 transformation matrix.

The function cvPerspectiveTransform transforms every element of A considering it a 3D vector as:

    (x, y, z) -> (x'/w, y'/w, z'/w),

    where
    (x', y', z', w') = M*(x, y, z, 1)

    and w = 1/w' if w'!=0,
              1  otherwise

### CalcCovarMatrix

Calculates covariation matrix out of the set of arrays

    void cvCalcCovarMatrix( CvArr** Vs, CvArr* M, CvArr* A );

Vs
  The set of input arrays. All the arrays must have the same type and the same size.
M
  The output covariation matrix that should be floating-point and square. Number of arrays is implicitly assumed to be equal to number of the matrix rows/columns.
A
  The output array that is set to the average of the input arrays.

The function cvCalcCovarMatrix calculates the covariation matrix and average array out of the set of input arrays:

    A(I)=sumkVs(k)(I)

    M(i,j)=(Vs(i)-A)•(Vs(j)-A)

Where the upper index in parentheses means the particular array from the set and "•" means dot product. The covariation matrix may be used then (after inversion) in cvMahalonobis function to measure a distance between vectors, to find eigen objects via cvSVD etc.

### Mahalonobis

Calculates Mahalonobis distance between vectors

    double cvMahalonobis( const CvArr* A, const CvArr* B, CvArr* T );

A
  The first 1D source vector.
B
  The second 1D source vector.
T
  The inverse covariation matrix.

The function cvMahalonobis calculates the weighted distance between two vectors and returns it:

    d(A,B)=sqrt( sumi,j {T(i,j)*(A(i)-B(i))*(A(j)-B(j))} )

The covariation matrix may be calculated using cvCalcCovarMatrix function and further inverted using cvInvert function (CV_SVD method is the preffered one, because the matrix might be singular).

### CartToPolar

Calculates magnitude and/or angle of 2d vectors

    void cvCartToPolar( const CvArr* X, const CvArr* Y, CvArr* M, CvArr* A,
                        int angle_in_degrees=0 );

X
  The array of x-coordinates
Y
  The array of y-coordinates
M
  The destination array of magnitudes, may be set to NULL if it is not needed
A
  The destination array of angles, may be set to NULL if it is not needed. The angles are measured in radians (0..2π) or in degrees (0..360°).
angle_in_degrees
  The flag indicating whether the angles are measured in radians, which is default mode, or in degrees.

The function cvCartToPolar calculates either magnitude, angle, or both of every vector (X(I),Y(I)):

    M(I)=sqrt( X(I)2+Y(I)2 ),
    A(I)=atan( Y(I)/X(I) )

The angles are calculated with ≈0.1° accuracy. For (0,0) point the angle is set to 0.

### PolarToCart

Calculates cartesian coordinates of 2d vectors represented in polar form

    void cvPolarToCart( const CvArr* M, const CvArr* A, CvArr* X, CvArr* Y,
                        int angle_in_degrees=0 );

M
  The array of magnitudes. If it is NULL, the magnitudes are assumed all 1's.
A
  The array of angles, whether in radians or degrees.
X
  The destination array of x-coordinates, may be set to NULL if it is not needed.
Y
  The destination array of y-coordinates, mau be set to NULL if it is not needed.
angle_in_degrees
  The flag indicating whether the angles are measured in radians, which is default mode, or in degrees.

The function cvPolarToCart calculates either x-coodinate, y-coordinate or both of every vector M(I)*exp(A(I)*j):

    X(I)=M(I)*cos(A(I)),
    Y(I)=M(I)*sin(A(I))

### Pow

Raises every array element to power

    void cvPow( const CvArr* X, CvArr* Y, double p );

X
  The source array.
Y
  The destination array, should be the same type as the source.
p
  The exponent of power.

The function cvPow raises every element of input array to p:

    Y(I)=X(I)p, if p is integer
    Y(I)=abs(X(I))p, otherwise

That is, for non-integer power exponent the absolute values of input array elements are used. However, it is possible to get true values for negative values using some extra operations, as the following sample, computing cube root of array elements, shows:

    CvSize size = cvGetSize(src);
    CvMat* mask = cvCreateMat( size.height, size.width, CV_8UC1 );
    cvCmpS( src, 0, mask, CV_CMP_LT ); /* find negative elements */
    cvPow( src, dst, 1./3 );
    cvSubRS( dst, cvScalarAll(0), dst, mask ); /* negate the results of negative inputs */
    cvReleaseMat( &mask );

For some values of power, such as integer values, 0.5 and -0.5, an optimized algorithm is used.

### Exp

Calculates exponent of every array element

    void cvExp( const CvArr* X, CvArr* Y );

X
  The source array.
Y
  The destination array, it should have double type or the same type as the source.

The function cvExp calculates exponent of every element of input array:

    Y(I)=exp(X(I))

Maximum relative error is ≈7e-6. Currently, the function converts denormalized values to zeros on output.

### Log

Calculates natural logarithm of every array element absolute value

    void cvLog( const CvArr* X, CvArr* Y );

X
  The source array.
Y
  The destination array, it should have double type or the same type as the source.

The function cvLog calculates natural logarithm of absolute value of every element of input array:

    Y(I)=log(abs(X(I))), X(I)!=0
    Y(I)=C,  X(I)=0

Where C is large negative number (≈-700 in the current implementation)

### CheckArr

Checks every element of input array for invalid values

    int  cvCheckArr( const CvArr* X, int flags=0,
                     double minVal=0, double maxVal=0);
    #define cvCheckArray cvCheckArr

X
  The array to check.
flags
  The operation flags, 0 or combination of:
  CV_CHECK_RANGE - if set, the function checks that every value of array is within [minVal,maxVal) range, otherwise it just checks that every element is neigther NaN nor ±∞.
  CV_CHECK_QUIET - if set, the function does not raises an error if an element is invalid or out of range
minVal
  The inclusive lower boundary of valid values range. It is used only if CV_CHECK_RANGE is set.
maxVal
  The exclusive upper boundary of valid values range. It is used only if CV_CHECK_RANGE is set.

The function cvCheckArr checks that every array element is neither NaN nor ±∞. If CV_CHECK_RANGE is set, it also checks that every element is greater than or equal to minVal and less than maxVal. The function returns nonzero if the check succeeded, i.e. all elements are valid and within the range, and zero otherwise. In the latter case if CV_CHECK_QUIET flag is not set, the function raiser runtime error.

### RandInit

Initializes random number generator state

    void cvRandInit( CvRandState* state, double param1, double param2, int seed,
                     int distType=CV_RAND_UNI );

state
  Pointer to the initialized random number generator state structure.
param1
  The first distribution parameter. In case of uniform distribution it is the inclusive lower boundary of random numbers range. In case of normal distribution it is the standard deviation of random numbers.
param2
  The second distribution parameter. In case of uniform distribution it is the exclusive upper boundary of random numbers range. In case of normal distribution it is the mean value of random numbers.
seed
  Initial 32-bit value to start a random sequence.
distType
  Distribution type:
  CV_RAND_UNI - uniform distribution
  CV_RAND_NORMAL - normal or Gaussian distribution

The function cvRandInit initializes the state structure that is used for generating uniformly distributed numbers in the range [param1, param2) or normally distributed numbers with param1 mean and param2 standard deviation. The parameters are set for all the dimensions simultaneously - resemble that RNG has separate parameters for each of 4 dimensions. A multiply-with-carry generator is used.

### RandSetRange

Changes the range of generated random numbers without touching RNG state

    void cvRandSetRange( CvRandState* state, double param1, double param2, int index=-1 );

state
  State of random number generator (RNG).
param1
  New lower boundary/deviation of generated numbers.
param2
  New upper boundary/mean value of generated numbers.
index
  The 0-based index of dimension/channel for which the parameter are changed, -1 means changing the parameters for all dimensions.

The function cvRandSetRange changes the range of generated random numbers without reinitializing RNG state. It is useful if a few arrays of different types need to initialized with random numbers within a loop. Alternatively, you may have a separate generator for each array, but then you should provide several uncorrelated initialization seeds - one per each generator.

### Rand

Fills array with random numbers and updates the RNG state

    void cvRand( CvRandState* state, CvArr* arr );

state
  RNG state initialized by RandInit and, optionally, customized by RandSetRange.
arr
  The destination array.

The function cvRand fills the destination array with uniformly or normally distributed random numbers within the pre-set range and updates RNG state. In the sample below this and two functions above are used to put a few normally distributed floating-point numbers to random locations within a 2d array

    /* let's noisy_screen be the floating-point 2d array that is to be "crapped" */
    CvRandState rng_state;
    int i, pointCount = 1000;
    /* allocate the array of coordinates of points */
    CvMat* locations = cvCreateMat( pointCount, 1, CV_32SC2 );
    /* array of random point values */
    CvMat* values = cvCreateMat( pointCount, 1, CV_32FC1 );
    CvSize size = cvGetSize( noisy_screen );

    cvRandInit( &rng_state,
                0, 1, /* use dummy parameters now and adjust them further */
                0xffffffff /* just use a fixed seed here */,
                CV_RAND_UNI /* specify uniform type */ );

    /* customize the RNG to use it for initialiazing locations:
       the 0-th dimension is used for x's and the 1st - for y's */
    cvRandSetRange( &rng_state, 0, size.width, 0 );
    cvRandSetRange( &rng_state, 0, size.height, 1 );

    /* initialize the locations */
    cvRand( &rng_state, locations );

    /* modify RNG to make it produce normally distributed values */
    rng_state.disttype = CV_RAND_NORMAL;
    cvRandSetRange( &rng_state,
                    30 /* deviation */,
                    100 /* average point brightness */,
                    -1 /* initialize all the dimensions */ );
    /* generate values */
    cvRand( &rng_state, values );

    /* set the points */
    for( i = 0; i < pointCount; i++ )
    {
        CvPoint pt = *(CvPoint*)cvPtr1D( locations, i, 0 );
        float value = *(float*)cvPtr1D( values, i, 0 );
        cvSetReal2D( noisy_screen, pt.y, pt.x, value );
    }

    /* not to forget to release the temporary arrays */
    cvReleaseMat( &locations );
    cvReleaseMat( &values );

    /* cvRandInit does not allocate any memory, so there is no need
      (and no function) to deinitialize it */

### RandNext

Returns 32-bit unsigned integer and updates RNG

    unsigned cvRandNext( CvRandState* state );

state
  RNG state initialized by RandInit and, optionally, customized by RandSetRange (though, the latter function does not affect on the discussed function outcome).

The function cvRandNext returns uniformly-distributed (regardless of the RNG distribution type settings) "plain" integer random number and updates RNG state. It is similar to rand() function from C runtime library, but it always generates 32-bit number whereas rand() returns a number in between 0 and RAND_MAX which is 2**16 or 2**32, depending on the platform.

The function is useful for generating scalar random numbers, such as points, patch sizes, table indices etc, where integer numbers of a certain range can be generated using modulo operation and floating-point numbers can be generated by scaling to 0..1 of any other specific range. Here is the example from the previous function discussion rewritten using cvRandNext:

    /* the input and the task is the same as in the previous sample. */
    CvRandState rng_state;
    int i, pointCount = 1000;
    /* ... - no arrays are allocated here */
    CvSize size = cvGetSize( noisy_screen );
    /* make a buffer for normally distributed numbers to reduce call overhead */
    #define bufferSize 16
    float normalValueBuffer[bufferSize];
    CvMat normalValueMat = cvMat( bufferSize, 1, CV_32F, normalValueBuffer );
    int valuesLeft = 0;

    /* initialize RNG to produce normally distributed values.
       Coordinates will be uniformly distributed within 0..2**32
       anyway as they are generated using cvRandNext */
    cvRandInit( &rng_state,
                100,
                30,
                0xffffffff /* just use a fixed seed here */,
                CV_RAND_NORMAL /* specify uniform type */ );

    for( i = 0; i < pointCount; i++ )
    {
        CvPoint pt;
        /* generate random point */
        pt.x = cvRandNext( &rng_state ) % size.width;
        pt.y = cvRandNext( &rng_state ) % size.height;

        if( valuesLeft <= 0 )
        {
            /* fulfill the buffer with normally distributed numbers if the buffer is empty */
            cvRand( &rng_state, &normalValueMat );
            valuesLeft = bufferSize;
        }
        cvSetReal2D( noisy_screen, pt.y, pt.x, normalValueBuffer[--valuesLeft]);
    }

    /* there is no need to deallocate normalValueMat because we have
    both the matrix header and the data on stack. It is a common and efficient
    practice of working with small, fixed-size matrices */

### DFT

Performs forward or inverse Discrete Fourier transform of 1D or 2D floating-point array

    #define CV_DXT_INVERSE  1
    #define CV_DXT_SCALE 2
    #define CV_DXT_INV_SCALE (CV_DXT_SCALE|CV_DXT_INVERSE)
    #define CV_DXT_INVERSE_SCALE CV_DXT_INV_SCALE

    void cvDFT( const CvArr* src, CvArr* dst, int flags );

src
  Source array, real or complex.
dst
  Destination array of the same size and same type as the source.
flags
  Transformation flags, 0 or a combination of the following flags:
  CV_DXT_INVERSE - perform inverse transform (w/o post-scaling>
  CV_DXT_SCALE - divide the result by the number of array elements
  For convenience, the constant CV_DXT_FORWARD may be used instead of literal 0.

The function cvDFT performs forward or inverse transform of 1D or 2D floating-point array:

    Forward Fourier transform of 1D vector of N elements:
    y = F•x, where Fik=exp(-j•Pi•i•k/N), j=sqrt(-1)

    Inverse Fourier transform of 1D vector of N elements:
    x = F-1•y = FT•y

    Forward Fourier transform of 2D vector of M×N elements:
    Y = F•X•F*

    Inverse Fourier transform of 2D vector of M×N elements:
    X = F*•Y•F

In case of real (single-channel) data, the packed format, borrowed from IPL, is used to to represent a result of forward Fourier transform or input for inverse Fourier transform:

    Re Y0,0      Re Y0,1    Im Y0,1    Re Y0,2     Im Y0,2  ...  Re Y0,N/2-1   Im Y0,N/2-1  Re Y0,N/2
    Re Y1,0      Re Y1,1    Im Y1,1    Re Y1,2     Im Y1,2  ...  Re Y1,N/2-1   Im Y1,N/2-1  Re Y1,N/2
    Im Y2,0      Re Y2,1    Im Y2,1    Re Y2,2     Im Y2,2  ...  Re Y2,N/2-1   Im Y2,N/2-1  Im Y2,N/2
    ............................................................................................
    Re YM/2-1,0   Re YM-3,1   Im YM-3,1  Re YM-3,2   Im YM-3,2 ...  Re YM-3,N/2-1  Im YM-3,N/2-1 Re YM-3,N/2
    Im YM/2-1,0   Re YM-2,1   Im YM-2,1  Re YM-2,2   Im YM-2,2 ...  Re YM-2,N/2-1  Im YM-2,N/2-1 Im YM-2,N/2
    Re YM/2,0    Re YM-1,1   Im YM-1,1  Re YM-1,2   Im YM-1,2  ... Re YM-1,N/2-1  Im YM-1,N/2-1 Im YM-1,N/2

Note: the last column is present if `N` is even, the last row is present if `M` is even.

In case of 1D real transform the result looks like the first row of the above matrix

### MulCss

Performs per-element multiplication of two Fourier spectrums of two real arrays

    void cvMulCss( const CvArr* srcA, const CvArr* srcB, CvArr* dst );

srcA
  The first source array.
srcB
  The second source array.
dst
  The destination array of the same type and the same size of the sources.

The function cvMulCss performs per-element multiplication of the two packed matrices that are produced by forward real Fourier transform (1D or 2D).

Calculating DFT's of two real arrays, then multiplying results by cvMulCss and performing inverse DFT on the product is equivalent yet faster way to find cyclic convolution of the two original arrays.

### DCT

Performs forward or inverse Discrete Cosine transform of 1D or 2D floating-point array

    #define CV_DXT_INVERSE  1
    #define CV_DXT_SCALE 2
    #define CV_DXT_INV_SCALE (CV_DXT_SCALE|CV_DXT_INVERSE)
    #define CV_DXT_INVERSE_SCALE CV_DXT_INV_SCALE

    void cvDCT( const CvArr* src, CvArr* dst, int flags );

src
  Source array, real 1D or 2D array.
dst
  Destination array of the same size and same type as the source.
flags
  Transformation flags, 0 or a combination of the following flags:
  CV_DXT_INVERSE - perform inverse transform
  CV_DXT_SCALE - divide the result by the number of array elements
  For convenience, the constant CV_DXT_FORWARD may be used instead of literal 0.

The function cvDCT performs forward or inverse transform of 1D or 2D floating-point array:

    Forward Cosine transform of 1D vector of N elements:
    y = C•x, where Cik=sqrt((i==0?1:2)/N)•cos(Pi•(2i+1)•k/N), j=sqrt(-1)

    Inverse Cosine transform of 1D vector of N elements:
    x = C-1•y = CT•y

    Forward Cosine transform of 2D vector of M×N elements:
    Y = C•X•CT

    Inverse Fourier transform of 2D vector of M×N elements:
    X = CT•Y•C

## Dynamic Data Structures

### CvMemStorage

Growing memory storage

        typedef struct CvMemStorage
        {
            struct CvMemBlock* bottom;/* first allocated block */
            struct CvMemBlock* top; /* the current memory block - top of the stack */
            struct CvMemStorage* parent; /* borrows new blocks from */
            int block_size; /* block size */
            int free_space; /* free space in the top block (in bytes) */
        } CvMemStorage;

Memory storage is a low-level structure used to store dynamically growing data structures such as sequences, contours, graphs, subdivisions etc. It is organized as a list of memory blocks of equal size - bottom field is the beginning of the list of blocks and top is the currently used block, but not necessarily the last block of the list. All blocks between bottom and top, not including the latter, are considered fully ocupied; and all blocks between top and the last block, not including top, are considered free and top block itself is partly ocupied - free_space contains the number of free bytes left in the end of top.

New memory buffer that may be allocated explicitly by cvMemStorageAlloc function or implicitly by higher-level functions, such as cvSeqPush, cvGraphAddEdge etc., always starts in the end of the current block if it fits there. After allocation free_space is decremented by the size of the allocated buffer plus some padding to keep the proper alignment. When the allocated buffer does not fit into the available part of top, the next storage block from the list is taken as top and free_space is reset to the whole block size prior to the allocation.

If there is no more free blocks, a new block is allocated (or borrowed from parent, see cvCreateChildMemStorage) and added to the end of list. Thus, the storage behaves as a stack with bottom indicating bottom of the stack and the pair (top, free_space) indicating top of the stack. The stack top may be saved via cvSaveMemStoragePos, restored via cvRestoreMemStoragePos or reset via cvClearStorage.

### CvMemBlock

Memory storage block

        typedef struct CvMemBlock
        {
            struct CvMemBlock* prev;
            struct CvMemBlock* next;
        } CvMemBlock;

The structure CvMemBlock represents a single block of memory storage. Actual data of the memory blocks follows the header, that is, the i-th byte of the memory block can be retrieved with the expression ((char*)(mem_block_ptr+1))[i]. However, normally there is no need to access the storage structure fields directly.

### CvMemStoragePos

Memory storage position

        typedef struct CvMemStoragePos
        {
            CvMemBlock* top;
            int free_space;
        } CvMemStoragePos;

The structure described below stores the position of the stack top that can be saved via cvSaveMemStoragePos and restored via cvRestoreMemStoragePos.

### CreateMemStorage

Creates memory storage

    CvMemStorage* cvCreateMemStorage( int blockSize=0 );

blockSize
  Size of the storage blocks in bytes. If it is 0, the block size is set to default value - currently it is ≈64K.

The function cvCreateMemStorage creates a memory storage and returns pointer to it. Initially the storage is empty. All fields of the header, except the block_size, are set to 0.

### CreateChildMemStorage

Creates child memory storage

    CvMemStorage* cvCreateChildMemStorage( CvMemStorage* parent );

parent
  Parent memory storage.

The function cvCreateChildMemStorage creates a child memory storage that is similar to simple memory storage except for the differences in the memory allocation/deallocation mechanism. When a child storage needs a new block to add to the block list, it tries to get this block from the parent. The first unoccupied parent block available is taken and excluded from the parent block list. If no blocks are available, the parent either allocates a block or borrows one from its own parent, if any. In other words, the chain, or a more complex structure, of memory storages where every storage is a child/parent of another is possible. When a child storage is released or even cleared, it returns all blocks to the parent. In other aspects, the child storage is the same as the simple storage.

The children storages are useful in the following situation. Imagine that user needs to process dynamical data resided in some storage and put the result back to the same storage. With the simplest approach, when temporary data is resided in the same storage as the input and output data, the storage will look as following after processing:

Dynamic data processing without using child storage

That is, garbage appears in the middle of the storage. However, if one creates a child memory storage in the beginning of the processing, writes temporary data there and releases the child storage in the end, no garbage will appear in the source/destination storage:

Dynamic data processing using a child storage

### ReleaseMemStorage

Releases memory storage

    void cvReleaseMemStorage( CvMemStorage** storage );

storage
  Pointer to the released storage.

The function cvReleaseMemStorage deallocates all storage memory blocks or returns them to the parent, if any. Then it deallocates the storage header and clears the pointer to the storage. All children of the storage must be released before the parent is released.

### ClearMemStorage

Clears memory storage

    void cvClearMemStorage( CvMemStorage* storage );

storage
  Memory storage.

The function cvClearMemStorage resets the top (free space boundary) of the storage to the very beginning. This function does not deallocate any memory. If the storage has a parent, the function returns all blocks to the parent.

### MemStorageAlloc

Allocates memory buffer in the storage

    void* cvMemStorageAlloc( CvMemStorage* storage, int size );

storage
  Memory storage.
size
  Buffer size.

The function cvMemStorageAlloc allocates memory buffer in the storage. The buffer size must not exceed the storage block size, otherwise runtime error is raised. The buffer address is aligned by CV_STRUCT_ALIGN (=sizeof(double) for the moment) bytes.

### SaveMemStoragePos

Saves memory storage position

    void cvSaveMemStoragePos( const CvMemStorage* storage, CvMemStoragePos* pos );

storage
  Memory storage.
pos
  The output position of the storage top.

The function cvSaveMemStoragePos saves the current position of the storage top to the parameter pos. The function cvRestoreMemStoragePos can further retrieve this position.

### RestoreMemStoragePos

Restores memory storage position

    void cvRestoreMemStoragePos( CvMemStorage* storage, CvMemStoragePos* pos );

storage
  Memory storage.
pos
  New storage top position.

The function cvRestoreMemStoragePos restores the position of the storage top from the parameter pos. This function and the function cvClearMemStorage are the only methods to release memory occupied in memory blocks. Note again that there is no way to free memory in the middle of the occupied part of the storage.

## Sequences

### CvSeq

Growable sequence of elements

        #define CV_SEQUENCE_FIELDS() \
            int flags; /* micsellaneous flags */ \
            int header_size; /* size of sequence header */ \
            struct CvSeq* h_prev; /* previous sequence */ \
            struct CvSeq* h_next; /* next sequence */ \
            struct CvSeq* v_prev; /* 2nd previous sequence */ \
            struct CvSeq* v_next; /* 2nd next sequence */ \
            int total; /* total number of elements */ \
            int elem_size;/* size of sequence element in bytes */ \
            char* block_max;/* maximal bound of the last block */ \
            char* ptr; /* current write pointer */ \
            int delta_elems; /* how many elements allocated when the sequence grows (sequence granularity) */ \
            CvMemStorage* storage; /* where the seq is stored */ \
            CvSeqBlock* free_blocks; /* free blocks list */ \
            CvSeqBlock* first; /* pointer to the first sequence block */

        typedef struct CvSeq
        {
            CV_SEQUENCE_FIELDS()
        } CvSeq;

The structure CvSeq is a base for all of OpenCV dynamic data structures.

Such an unusual definition via a helper macro simplifies the extension of the structure CvSeq with additional parameters. To extend CvSeq the user may define a new structure and put user-defined fields after all CvSeq fields that are included via the macro CV_SEQUENCE_FIELDS().

There are two types of sequences - dense and sparse. Base type for dense sequences is CvSeq and such sequences are used to represent growable 1d arrays - vectors, stacks, queues, deques. They have no gaps in the middle - if an element is removed from the middle or inserted into the middle of the sequence the elements from the closer end are shifted. Sparse sequences have CvSet base class and they are discussed later in more details. They are sequences of nodes each of those may be either occupied or free as indicated by the node flag. Such sequences are used for unordered data structures such as sets of elements, graphs, hash tables etc.

The field header_size contains the actual size of the sequence header and should be greater or equal to sizeof(CvSeq).

The fields h_prev, h_next, v_prev, v_next can be used to create hierarchical structures from separate sequences. The fields h_prev and h_next point to the previous and the next sequences on the same hierarchical level while the fields v_prev and v_next point to the previous and the next sequence in the vertical direction, that is, parent and its first child. But these are just names and the pointers can be used in a different way.

The field first points to the first sequence block, whose structure is described below.

The field total contains the actual number of dense sequence elements and number of allocated nodes in sparse sequence.

The field flagscontain the particular dynamic type signature (CV_SEQ_MAGIC_VAL for dense sequences and CV_SET_MAGIC_VAL for sparse sequences) in the highest 16 bits and miscellaneous information about the sequence. The lowest CV_SEQ_ELTYPE_BITS bits contain the ID of the element type. Most of sequence processing functions do not use element type but element size stored in elem_size. If sequence contains the numeric data of one of CvMat type then the element type matches to the corresponding CvMat element type, e.g. CV_32SC2 may be used for sequence of 2D points, CV_32FC1 for sequences of floating-point values etc. CV_SEQ_ELTYPE(seq_header_ptr) macro retrieves the type of sequence elements. Processing function that work with numerical sequences check that elem_size is equal to the calculated from the type element size. Besides CvMat compatible types, there are few extra element types defined in cvtypes.h header:

Standard Types of Sequence Elements

        #define CV_SEQ_ELTYPE_POINT          CV_32SC2  /* (x,y) */
        #define CV_SEQ_ELTYPE_CODE           CV_8UC1   /* freeman code: 0..7 */
        #define CV_SEQ_ELTYPE_GENERIC        0 /* unspecified type of sequence elements */
        #define CV_SEQ_ELTYPE_PTR            CV_USRTYPE1 /* =6 */
        #define CV_SEQ_ELTYPE_PPOINT         CV_SEQ_ELTYPE_PTR  /* &elem: pointer to element of other sequence */
        #define CV_SEQ_ELTYPE_INDEX          CV_32SC1  /* #elem: index of element of some other sequence */
        #define CV_SEQ_ELTYPE_GRAPH_EDGE     CV_SEQ_ELTYPE_GENERIC  /* &next_o, &next_d, &vtx_o, &vtx_d */
        #define CV_SEQ_ELTYPE_GRAPH_VERTEX   CV_SEQ_ELTYPE_GENERIC  /* first_edge, &(x,y) */
        #define CV_SEQ_ELTYPE_TRIAN_ATR      CV_SEQ_ELTYPE_GENERIC  /* vertex of the binary tree   */
        #define CV_SEQ_ELTYPE_CONNECTED_COMP CV_SEQ_ELTYPE_GENERIC  /* connected component  */
        #define CV_SEQ_ELTYPE_POINT3D        CV_32FC3  /* (x,y,z)  */

The next CV_SEQ_KIND_BITS bits specify the kind of the sequence:

Standard Kinds of Sequences

        /* generic (unspecified) kind of sequence */
        #define CV_SEQ_KIND_GENERIC     (0 << CV_SEQ_ELTYPE_BITS)

        /* dense sequence suntypes */
        #define CV_SEQ_KIND_CURVE       (1 << CV_SEQ_ELTYPE_BITS)
        #define CV_SEQ_KIND_BIN_TREE    (2 << CV_SEQ_ELTYPE_BITS)

        /* sparse sequence (or set) subtypes */
        #define CV_SEQ_KIND_GRAPH       (3 << CV_SEQ_ELTYPE_BITS)
        #define CV_SEQ_KIND_SUBDIV2D    (4 << CV_SEQ_ELTYPE_BITS)

The remaining bits are used to identify different features specific to certain sequence kinds and element types. For example, curves made of points ( CV_SEQ_KIND_CURVE|CV_SEQ_ELTYPE_POINT ), together with the flag CV_SEQ_FLAG_CLOSED belong to the type CV_SEQ_POLYGON or, if other flags are used, to its subtype. Many contour processing functions check the type of the input sequence and report an error if they do not support this type. The file cvtypes.h stores the complete list of all supported predefined sequence types and helper macros designed to get the sequence type of other properties. Below follows the definition of the building block of sequences.

### CvSeqBlock

Continuous sequence block

        typedef struct CvSeqBlock
        {
            struct CvSeqBlock* prev; /* previous sequence block */
            struct CvSeqBlock* next; /* next sequence block */
            int start_index; /* index of the first element in the block +
            sequence->first->start_index */
            int count; /* number of elements in the block */
            char* data; /* pointer to the first element of the block */
        } CvSeqBlock;

Sequence blocks make up a circular double-linked list, so the pointers prev and next are never NULL and point to the previous and the next sequence blocks within the sequence. It means that next of the last block is the first block and prev of the first block is the last block. The fields start_index and count help to track the block location within the sequence. For example, if the sequence consists of 10 elements and splits into three blocks of 3, 5, and 2 elements, and the first block has the parameter start_index = 2, then pairs (start_index, count) for the sequence blocks are (2,3), (5, 5), and (10, 2) correspondingly. The parameter start_index of the first block is usually 0 unless some elements have been inserted at the beginning of the sequence.

### CreateSeq

Creates sequence

    CvSeq* cvCreateSeq( int seqFlags, int headerSize,
                        int elemSize, CvMemStorage* storage );

seqFlags
  Flags of the created sequence. If the sequence is not passed to any function working with a specific type of sequences, the sequence value may be set to 0, otherwise the appropriate type must be selected from the list of predefined sequence types.
headerSize
  Size of the sequence header; must be greater or equal to sizeof(CvSeq). If a specific type or its extension is indicated, this type must fit the base type header.
elemSize
  Size of the sequence elements in bytes. The size must be consistent with the sequence type. For example, for a sequence of points to be created, the element type CV_SEQ_ELTYPE_POINT should be specified and the parameter elemSize must be equal to sizeof(CvPoint).
storage
  Sequence location.

The function cvCreateSeq creates a sequence and returns the pointer to it. The function allocates the sequence header in the storage block as one continuous chunk and fills the parameter elemSize, flags headerSize, and storage with passed values, sets delta_elems to the default value (that may be reassigned using cvSetSeqBlockSize function), and clears other fields, including the space behind sizeof(CvSeq).

### SetSeqBlockSize

Sets up sequence block size

    void cvSetSeqBlockSize( CvSeq* seq, int blockSize );

seq
  Sequence.
blockSize
  Desirable block size.

The function cvSetSeqBlockSize affects the memory allocation granularity. When the free space in the sequence buffers has run out, the function allocates blockSize bytes in the storage. If this block immediately follows the one previously allocated, the two blocks are concatenated, otherwise, a new sequence block is created. Therefore, the bigger the parameter is, the lower the possible sequence fragmentation, but the more space in the storage is wasted. When the sequence is created, the parameter blockSize is set to the default value ≈1K. The function can be called any time after the sequence is created and affects future allocations. The final block size can be different from the one desired, e.g., if it is larger than the storage block size, or smaller than the sequence block header size plus the sequence element size.

### SeqPush

Adds element to sequence end

    char* cvSeqPush( CvSeq* seq, void* element=0 );

seq
  Sequence.
element
  Added element.

The function cvSeqPush adds an element to the end of sequence and retuns pointer to the allocated element. If the input element is NULL, the function simply allocates a space for one more element.

The following code demonstrates how to create a new sequence using this function:

    CvMemStorage* storage = cvCreateMemStorage(0);
    CvSeq* seq = cvCreateSeq( CV_32SC1, /* sequence of integer elements */
                              sizeof(CvSeq), /* header size - no extra fields */
                              sizeof(int), /* element size */
                              storage /* the container storage */ );
    int i;
    for( i = 0; i < 100; i++ )
    {
        int* added = (int*)cvSeqPush( seq, &i );
        printf( "%d is added\n", *added );
    }

    ...
    /* release memory storage in the end */
    cvReleaseMemStorage( &storage );

The function cvSeqPush has O(1) complexity, but there is a faster method for writing large sequences (see cvStartWriteSeq and related functions).

### SeqPop

Removes element from sequence end

    void cvSeqPop( CvSeq* seq, void* element=0 );

seq
  Sequence.
element
  Optional parameter. If the pointer is not zero, the function copies the removed element to this location.

The function cvSeqPop removes an element from the sequence. The function reports an error if the sequence is already empty. The function has O(1) complexity.

### SeqPushFront

Adds element to sequence beginning

    char* cvSeqPushFront( CvSeq* seq, void* element=0 );

seq
  Sequence.
element
  Added element.

The function cvSeqPushFront is similar to cvSeqPush but it adds the new element to the beginning of the sequence. The function has O(1) complexity.

### SeqPopFront

Removes element from sequence beginning

    void cvSeqPopFront( CvSeq* seq, void* element=0 );

seq
  Sequence.
element
  Optional parameter. If the pointer is not zero, the function copies the removed element to this location.

The function cvSeqPopFront removes an element from the beginning of the sequence. The function reports an error if the sequence is already empty. The function has O(1) complexity.

### SeqPushMulti

Pushes several elements to the either end of sequence

    void cvSeqPushMulti( CvSeq* seq, void* elements, int count, int in_front=0 );

seq
  Sequence.
elements
  Added elements.
count
  Number of elements to push.
in_front
  The flags specifying the modified sequence end:
  CV_BACK (=0) - the elements are added to the end of sequence
  CV_FRONT(!=0) - the elements are added to the beginning of sequence

The function cvSeqPushMulti adds several elements to either end of the sequence. The elements are added to the sequence in the same order as they are arranged in the input array but they can fall into different sequence blocks.

### SeqPopMulti

Removes several elements from the either end of sequence

    void cvSeqPopMulti( CvSeq* seq, void* elements, int count, int in_front=0 );

seq
  Sequence.
elements
  Removed elements.
count
  Number of elements to pop.
in_front
  The flags specifying the modified sequence end:
  CV_BACK (=0) - the elements are removed from the end of sequence
  CV_FRONT(!=0) - the elements are removed from the beginning of sequence

The function cvSeqPopMulti removes several elements from either end of the sequence. If the number of the elements to be removed exceeds the total number of elements in the sequence, the function removes as many elements as possible.

### SeqInsert

Inserts element in sequence middle

    char* cvSeqInsert( CvSeq* seq, int beforeIndex, void* element=0 );

seq
  Sequence.
beforeIndex
  Index before which the element is inserted. Inserting before 0 (the minimal allowed value of the parameter) is equal to cvSeqPushFront and inserting before seq->total (the maximal allowed value of the parameter) is equal to cvSeqPush.
element
  Inserted element.

The function cvSeqInsert shifts the sequence elements from the inserted position to the nearest end of the sequence and copies the element content there if the pointer is not NULL. The function returns pointer to the inserted element.

### SeqRemove

Removes element from sequence middle

    void cvSeqRemove( CvSeq* seq, int index );

seq
  Sequence.
index
  Index of removed element.

The function cvSeqRemove removes elements with the given index. If the index is out of range the function reports an error. An attempt to remove an element from an empty sequence is a partitial case of this situation. The function removes an element by shifting the sequence elements between the nearest end of the sequence and the index-th position, not counting the latter.

### ClearSeq

Clears sequence

    void cvClearSeq( CvSeq* seq );

seq
  Sequence.

The function cvClearSeq removes all elements from the sequence. The function does not return the memory to the storage, but this memory is reused later when new elements are added to the sequence. This function time complexity is O(1).

### GetSeqElem

Returns pointer to sequence element by its index

    char* cvGetSeqElem( CvSeq* seq, int index, CvSeqBlock** block=0 );
    #define CV_GET_SEQ_ELEM( TYPE, seq, index )  (TYPE*)cvGetSeqElem( (CvSeq*)(seq), (index), 0 )

seq
  Sequence.
index
  Index of element.
block
  Optional output parameter. If it is not NULL, the pointer to the sequence block containing the requested element is stored in this location.

The function cvGetSeqElem finds the element with the given index in the sequence and returns the pointer to it. In addition, the function can return the pointer to the sequence block that contains the element. If the element is not found, the function returns 0. The function supports negative indices, where -1 stands for the last sequence element, -2 stands for the one before last, etc. If the sequence is most likely to consist of a single sequence block or the desired element is likely to be located in the first block, then the macro CV_GET_SEQ_ELEM( elemType, seq, index ) should be used, where the parameter elemType is the type of sequence elements ( CvPoint for example), the parameter seq is a sequence, and the parameter index is the index of the desired element. The macro checks first whether the desired element belongs to the first block of the sequence and, if so, returns the element, otherwise the macro calls the main function GetSeqElem. Negative indices always cause the cvGetSeqElem call. The function has O(1) time complexity assuming that number of blocks is much smaller than the number of elements.

### SeqElemIdx

Returns index of concrete sequence element

    int cvSeqElemIdx( CvSeq* seq, void* element, CvSeqBlock** block=0 );

seq
  Sequence.
element
  Pointer to the element within the sequence.
block
  Optional argument. If the pointer is not NULL, the address of the sequence block that contains the element is stored in this location.

The function cvSeqElemIdx returns the index of a sequence element or a negative number if the element is not found.

### CvtSeqToArray

Copies sequence to one continuous block of memory

    void* cvCvtSeqToArray( CvSeq* seq, void* array, CvSlice slice=CV_WHOLE_SEQ );

seq
  Sequence.
array
  Pointer to the destination array that must fit all the sequence elements.
slice
  The sequence part to copy to the array.

The function cvCvtSeqToArray copies the entire sequence or subsequence to the specified buffer and returns the pointer to the buffer.

### MakeSeqHeaderForArray

Constructs sequence from array

    void cvMakeSeqHeaderForArray( int seqType, int headerSize, int elemSize,
                                  void* array, int total,
                                  CvSeq* sequence, CvSeqBlock* block );

seqType
  Type of the created sequence.
headerSize
  Size of the header of the sequence. Parameter sequence must point to the structure of that size or greater size.
elemSize
  Size of the sequence element.
array
  Pointer to the array that makes up the sequence.
total
  Total number of elements in the sequence. The number of array elements must be equal to the value of this parameter.
sequence
  Pointer to the local variable that is used as the sequence header.
block
  Pointer to the local variable that is the header of the single sequence block.

The function cvMakeSeqHeaderForArray initializes sequence header for array. The sequence header as well as the sequence block are allocated by the user (for example, on stack). No data is copied by the function. The resultant sequence will consists of a single block and have NULL storage pointer, thus, it is possible to read its elements, but the attempts to add elements to the sequence will raise an error in most cases.

### SeqSlice

Makes separate header for the sequence slice

    CvSeq* cvSeqSlice( CvSeq* seq, CvSlice slice=CV_WHOLE_SEQ,
                       CvMemStorage* storage=0, int copyData=0 );

    cvCloneSeq(seq[,storage]) ~ cvSeqSlice(seq,CV_WHOLE_SEQ,storage,1)

seq
  Sequence.
slice
  The part of the sequence to extract.
storage
  The destination storage to keep the new sequence header and the copied data if any. If it is NULL, the function uses the storage containing the input sequence.
copyData
  The flag that indicates whether to copy the elements of the extracted slice (copyData!=0) or not (copyData=0)

The function cvSeqSlice creates another sequence and either makes it share the elements of the specified slice with the original sequence or creates another copy of the slice. So if one needs to process a part of sequence but the processing function does not have a slice parameter, the required sequence slice may be represented as a separate sequence using this function. Another purpose of the function is to make a copy of entire sequence that is done by cvCloneSeq inline shortcut to cvSeqSlice

### SeqRemoveSlice

Removes sequence slice

    void cvSeqRemoveSlice( CvSeq* seq, CvSlice slice );

seq
  Sequence.
slice
  The part of the sequence to remove.

The function cvSeqRemoveSlice removes slice from the sequence.

### SeqInsertSlice

Inserts array in the middle of sequence

    void cvSeqInsertSlice( CvSeq* seq, int beforeIndex, const CvArr* fromArr );

seq
  Sequence.
slice
  The part of the sequence to remove.

The function cvSeqInsertSlice inserts all fromArr array elements at the specified position of the sequence. The array may be matrix or another sequence.

### SeqInvert

Reverses the order of sequence elements

    void cvSeqInvert( CvSeq* seq );

seq
  Sequence.

The function cvSeqInvert reverses the sequence in-place - makes the first element go last, the last element go first etc.

### SeqSort

Sorts sequence element using the specified comparison function

    /* a < b ? -1 : a > b ? 1 : 0 */
    typedef int (CV_CDECL* CvCmpFunc)(const void* a, const void* b, void* userdata);

    void cvSeqSort( CvSeq* seq, CvCmpFunc func, void* userdata );

seq
  The sequence to sort
func
  The comparison function that returns negative, zero or positive value depending on the elements relation (see the above declaration and the example below) - similar function is used by qsort from C runline except that in the latter userdata is not used
userdata
  The user parameter passed to the compasion function; helps to avoid global variables in some cases.

The function cvSeqSort sorts the sequence in-place using the specified criteria. Below is the example of the function use:

    /* Sort 2d points in top-to-bottom left-to-right order */
    static int cmp_func( const void* _a, const void* _b, void* userdata )
    {
        CvPoint* a = (CvPoint*)_a;
        CvPoint* b = (CvPoint*)_b;
        int y_diff = a->y - b->y;
        int x_diff = a->x - b->x;
        return y_diff ? y_diff : x_diff;
    }

    ...

    CvMemStorage* storage = cvCreateMemStorage(0);
    CvSeq* seq = cvCreateSeq( CV_32SC2, sizeof(CvSeq), sizeof(CvPoint), storage );
    int i;

    for( i = 0; i < 10; i++ )
    {
        CvPoint pt;
        pt.x = rand() % 1000;
        pt.y = rand() % 1000;
        cvSeqPush( seq, &pt );
    }

    cvSeqSort( seq, cmp_func, 0 /* userdata is not used here */ );

    /* print out the sorted sequence */
    for( i = 0; i < seq->total; i++ )
    {
        CvPoint* pt = (CvPoint*)cvSeqElem( seq, i );
        printf( "(%d,%d)\n", pt->x, pt->y );
    }

    cvReleaseMemStorage( &storage );

### StartAppendToSeq

Initializes process of writing to sequence

    void cvStartAppendToSeq( CvSeq* seq, CvSeqWriter* writer );

seq
  Pointer to the sequence.
writer
  Writer state; initialized by the function.

The function cvStartAppendToSeq initializes the writer to write to the sequence. Written elements are added to the end of the sequence by CV_WRITE_SEQ_ELEM( written_elem, writer ) macro. Note that during the writing process other operations on the sequence may yield incorrect result or even corrupt the sequence (see description of cvFlushSeqWriter that helps to avoid some of that difficulties).

### StartWriteSeq

Creates new sequence and initializes writer for it

    void cvStartWriteSeq( int seqFlags, int headerSize, int elemSize,
                          CvMemStorage* storage, CvSeqWriter* writer );

seqFlags
  Flags of the created sequence. If the sequence is not passed to any function working with a specific type of sequences, the sequence value may be equal to 0, otherwise the appropriate type must be selected from the list of predefined sequence types.
headerSize
  Size of the sequence header. The parameter value may not be less than sizeof(CvSeq). If a certain type or extension is specified, it must fit the base type header.
elemSize
  Size of the sequence elements in bytes; must be consistent with the sequence type. For example, if the sequence of points is created (element type CV_SEQ_ELTYPE_POINT ), then the parameter elemSize must be equal to sizeof(CvPoint).
storage
  Sequence location.
writer
  Writer state; initialized by the function.

The function cvStartWriteSeq is a composition of cvCreateSeq and cvStartAppendToSeq. The pointer to the created sequence is stored at writer->seq and is also returned by cvEndWriteSeq function that should be called in the end.

### EndWriteSeq

Finishes process of writing sequence

    CvSeq* cvEndWriteSeq( CvSeqWriter* writer );

writer
  Writer state

The function cvEndWriteSeq finishes the writing process and returns the pointer to the written sequence. The function also truncates the last incomplete sequence block to return the remaining part of the block to the memory storage. After that the sequence can be read and modified safely.

### FlushSeqWriter

Updates sequence headers from the writer state

    void cvFlushSeqWriter( CvSeqWriter* writer );

writer
  Writer state

The function cvFlushSeqWriter is intended to enable the user to read sequence elements, whenever required, during the writing process, e.g., in order to check specific conditions. The function updates the sequence headers to make reading from the sequence possible. The writer is not closed, however, so that the writing process can be continued any time. In some algorithm requires often flush'es, consider using cvSeqPush instead.

### StartReadSeq

Initializes process of sequential reading from sequence

    void cvStartReadSeq( CvSeq* seq, CvSeqReader* reader, int reverse=0 );

seq
  Sequence.
reader
  Reader state; initialized by the function.
reverse
  Determines the direction of the sequence traversal. If reverse is 0, the reader is positioned at the first sequence element, otherwise it is positioned at the last element.

The function cvStartReadSeq initializes the reader state. After that all the sequence elements from the first down to the last one can be read by subsequent calls of the macro CV_READ_SEQ_ELEM( read_elem, reader ) in case of forward reading and by using CV_REV_READ_SEQ_ELEM( read_elem, reader ) in case of reversed reading. Both macros put the sequence element to read_elem and move the reading pointer toward the next element. A circular structure of sequence blocks is used for the reading process, that is, after the last element has been read by the macro CV_READ_SEQ_ELEM, the first element is read when the macro is called again. The same applies to CV_REV_READ_SEQ_ELEM . There is no function to finish the reading process, since it neither changes the sequence nor creates any temporary buffers. The reader field ptr points to the current element of the sequence that is to be read next. The code below demonstrates how to use sequence writer and reader.

    CvMemStorage* storage = cvCreateMemStorage(0);
    CvSeq* seq = cvCreateSeq( CV_32SC1, sizeof(CvSeq), sizeof(int), storage );
    CvSeqWriter writer;
    CvSeqReader reader;
    int i;

    cvStartAppendToSeq( seq, &writer );
    for( i = 0; i < 10; i++ )
    {
        int val = rand()%100;
        CV_WRITE_SEQ_ELEM( val, writer );
        printf("%d is written\n", val );
    }
    cvEndWriteSeq( &writer );

    cvStartReadSeq( seq, &reader, 0 );
    for( i = 0; i < seq->total; i++ )
    {
        int val;
        CV_READ_SEQ_ELEM( val, reader );
        printf("%d is read\n", val );
    }
    ...

    cvReleaseStorage( &storage );

### GetSeqReaderPos

Returns the current reader position

    int cvGetSeqReaderPos( CvSeqReader* reader );

reader
  Reader state.

The function cvGetSeqReaderPos returns the current reader position (within 0 ... reader->seq->total - 1).

### SetSeqReaderPos

Moves the reader to specified position

    void cvSetSeqReaderPos( CvSeqReader* reader, int index, int is_relative=0 );

reader
  Reader state.
index
  The destination position. If the positioning mode is used (see the next parameter) the actual position will be index mod reader->seq->total.
is_relative
  If it is not zero, then index is a relative to the current position.

The function cvSetSeqReaderPos moves the read position to the absolute position or relative to the current position.

## Sets

### CvSet

Collection of nodes

        typedef struct CvSetElem
        {
            int flags; /* it is negative if the node is free and zero or positive otherwise */
            struct CvSetElem* next_free; /* if the node is free, the field is a
                                            pointer to next free node */
        }
        CvSetElem;

        #define CV_SET_FIELDS()    \
            CV_SEQUENCE_FIELDS()   /* inherits from CvSeq */ \
            struct CvSetElem* free_elems; /* list of free nodes */

        typedef struct CvSet
        {
            CV_SET_FIELDS()
        } CvSet;

The structure CvSet is a base for OpenCV sparse data structures.

As follows from the above declaration CvSet inherits from CvSeq and it adds free_elems field it to, which is a list of free nodes. Every set node, whether free or not, is the element of the underlying sequence. While there is no restrictions on elements of dense sequences, the set (and derived structures) elements must start with integer field and be able to fit CvSetElem structure, because these two fields (integer followed by the pointer) are required for organization of node set with the list of free nodes. If a node is free, flags field is negative (the most-significant bit, or MSB, of the field is set), and next_free points to the next free node (the first free node is referenced by free_elems field of CvSet). And if a node is occupied, flags field is positive and contains the node index that may be retrieved using (set_elem->flags & CV_SET_ELEM_IDX_MASK) expression, the rest of the node content is determined by the user. In particular, the occupied nodes are not linked as the free nodes are, so the second field can be used for such a link as well as for some different purpose. The macro CV_IS_SET_ELEM(set_elem_ptr) can be used to determined whether the specified node is occupied or not.

Initially the set and the list are empty. When a new node is requiested from the set, it is taken from the list of free nodes, which is updated then. If the list appears to be empty, a new sequence block is allocated and all the nodes within the block are joined in the list of free nodes. Thus, total field of the set is the total number of nodes both occupied and free. When an occupied node is released, it is added to the list of free nodes. The node released last will be occupied first.

In OpenCV CvSet is used for representing graphs (CvGraph), sparse multi-dimensional arrays (CvSparseMat), planar subdivisions (CvSubdiv2D) etc.

### CreateSet

Creates empty set

    CvSet* cvCreateSet( int setFlags, int headerSize,
                        int elemSize, CvMemStorage* storage );

setFlags
  Type of the created set.
headerSize
  Set header size; may not be less than sizeof(CvSet).
elemSize
  Set element size; may not be less than CvSetElem.
storage
  Container for the set.

The function cvCreateSet creates an empty set with a specified header size and element size, and returns the pointer to the set. The function is just a thin layer on top of cvCreateSeq.

### SetAdd

Occupies a node in the set

    int cvSetAdd( CvSet* set, void* elem, void** insertedElem=0 );

set
  Set.
elem
  Optional input argument, inserted element. If not NULL, the function copies the data to the allocated node (The MSB of the first integer field is cleared after copying).
insertedElem
  Optional output argument; the pointer to the allocated cell.

The function cvSetAdd allocates a new node, optionally copies input element data to it, and returns the pointer and the index to the node. The index value is taken from the lower bits of flags field of the node. The function has O(1) complexity, however there exists a faster function for allocating set nodes (see cvSetNew).

### SetRemove

Removes element from set

    void cvSetRemove( CvSet* set, int index );

set
  Set.
index
  Index of the removed element.

The function cvSetRemove removes an element with a specified index from the set. If the node at the specified location is not occupied the function does nothing. The function has O(1) complexity, however, cvSetRemoveByPtr provides yet faster way to remove a set element if it is located already.

### SetNew

Adds element to set (fast variant)

    CvSetElem* cvSetNew( CvSet* set );

set
  Set.

The function cvSetNew is inline light-weight variant of cvSetAdd. It occupies a new node and returns pointer to it rather than index.

### SetRemoveByPtr

Removes set element given its pointer

    void cvSetRemoveByPtr( CvSet* set, void* elem );

set
  Set.
elem
  Removed element.

The function cvSetRemoveByPtr is inline light-weight variant of cvSetRemove that takes element pointer. The function does not check whether the node is occupied or not - the user should take care of it.

### GetSetElem

Finds set element by its index

    CvSetElem* cvGetSetElem( CvSet* set, int index );

set
  Set.
index
  Index of the set element within a sequence.

The function cvGetSetElem finds a set element by index. The function returns the pointer to it or 0 if the index is invalid or the corresponding node is free. The function supports negative indices as it uses cvGetSeqElem to locate the node.

### ClearSet

Clears set

    void cvClearSet( CvSet* set );

set
  Cleared set.

The function cvClearSet removes all elements from set. It has O(1) time complexity.

## Graphs

### CvGraph

Oriented or unoriented weigted graph

        #define CV_GRAPH_VERTEX_FIELDS()    \
            int flags; /* vertex flags */   \
            struct CvGraphEdge* first; /* the first incident edge */

        typedef struct CvGraphVtx
        {
            CV_GRAPH_VERTEX_FIELDS()
        }
        CvGraphVtx;

        #define CV_GRAPH_EDGE_FIELDS()      \
            int flags; /* edge flags */     \
            float weight; /* edge weight */ \
            struct CvGraphEdge* next[2]; /* the next edges in the incidence lists for staring (0) */ \
                                         /* and ending (1) vertices */ \
            struct CvGraphVtx* vtx[2]; /* the starting (0) and ending (1) vertices */

        typedef struct CvGraphEdge
        {
            CV_GRAPH_EDGE_FIELDS()
        }
        CvGraphEdge;

        #define  CV_GRAPH_FIELDS()                  \
            CV_SET_FIELDS() /* set of vertices */   \
            CvSet* edges;   /* set of edges */

        typedef struct CvGraph
        {
            CV_GRAPH_FIELDS()
        }
        CvGraph;

The structure CvGraph is a base for graphs used in OpenCV.

Graph structure inherits from CvSet - this part describes common graph properties and the graph vertices, and contains another set as a member - this part describes the graph edges.

The vertex, edge and the graph header structures are declared using the same technique as other extendible OpenCV structures - via macros, that simplifies extension and customization of the structures. While the vertex and edge structures do not inherit from CvSetElem explicitly, they satisfy both conditions on the set elements - have an integer field in the beginning and fit CvSetElem structure. The flags fields are used as for indicating occupied vertices and edges as well as for other purposes, for example, for graph traversal (see cvStartScanGraph et al.), so it is better not to use them directly.

The graph is represented as a set of edges each of whose has the list of incident edges. The incidence lists for different vertices are interleaved to avoid information duplication as much as posssible.

The graph may be oriented or unoriented. In the latter case there is no distiction between edge connecting vertex A with vertex B and the edge connecting vertex B with vertex A - only one of them can exist in the graph at the same moment and it represents both <A, B> and <B, A> edges..

### CreateGraph

Creates empty graph

    CvGraph* cvCreateGraph( int graphFlags, int headerSize, int vertexSize,
                            int edgeSize, CvStorage* storage );

graphFlags
  Type of the created graph. Usually, it is either CV_SEQ_KIND_GRAPH for generic unoriented graphs and CV_SEQ_KIND_GRAPH | CV_GRAPH_FLAG_ORIENTED for generic oriented graphs.
headerSize
  Graph header size; may not be less than sizeof(CvGraph).
vertexSize
  Graph vertex size; the custom vertex structure must start with CvGraphVtx (use CV_GRAPH_VERTEX_FIELDS())
edgeSize
  Graph edge size; the custom edge structure must start with CvGraphEdge (use CV_GRAPH_EDGE_FIELDS())
storage
  The graph container.

The function cvCreateGraph creates an empty graph and returns pointer to it.

### GraphAddVtx

Adds vertex to graph

    int cvGraphAddVtx( CvGraph* graph, CvGraphVtx* vtx,
                       CvGraphVtx** insertedVtx=0 );

graph
  Graph.
vtx
  Optional input argument used to initialize the added vertex (only user-defined fields beyond sizeof(CvGraphVtx) are copied).
insertedVtx
  Optional output argument. If not NULL, the address of the new vertex is written there.

The function cvGraphAddVtx adds a vertex to the graph and returns the vertex index.

### GraphRemoveVtx

Removes vertex from graph

    void cvGraphRemoveVtx( CvGraph* graph, int vtxIdx );

graph
  Graph.
vtxIdx
  Index of the removed vertex.

The function cvGraphRemoveAddVtx removes a vertex from the graph together with all the edges incident to it. The function reports an error, if the input vertex does not belong to the graph.

### GraphRemoveVtxByPtr

Removes vertex from graph

    void cvGraphRemoveVtxByPtr( CvGraph* graph, CvGraphVtx* vtx );

graph
  Graph.
vtx
  Pointer to the removed vertex.

The function cvGraphRemoveVtxByPtr removes a vertex from the graph together with all the edges incident to it. The function reports an error, if the vertex does not belong to the graph.

### GetGraphVtx

Finds graph vertex by index

    CvGraphVtx* cvGetGraphVtx( CvGraph* graph, int vtxIdx );

graph
  Graph.
vtxIdx
  Index of the vertex.

The function cvGetGraphVtx finds the graph vertex by index and returns the pointer to it or NULL if the vertex does not belong to the graph.

### GraphVtxIdx

Returns index of graph vertex

    int cvGraphVtxIdx( CvGraph* graph, CvGraphVtx* vtx );

graph
  Graph.
vtx
  Pointer to the graph vertex.

The function cvGraphVtxIdx returns index of the graph vertex.

### GraphAddEdge

Adds edge to graph

    int cvGraphAddEdge( CvGraph* graph, int startIdx, int endIdx,
                        CvGraphEdge* edge, CvGraphEdge** insertedEdge=0 );

graph
  Graph.
startIdx
  Index of the starting vertex of the edge.
endIdx
  Index of the ending vertex of the edge. For unoriented graph the order of the vertex parameters does not matter.
edge
  Optional input parameter, initialization data for the edge.
insertedEdge
  Optional output parameter to contain the address of the inserted edge.

The function cvGraphAddEdge connects two specified vertices. The function returns 1 if the edge has been added successfully, 0 if the edge connecting the two vertices exists already and -1 if either of the vertices was not found, the starting and the ending vertex are the same or there is some other critical situation. In the latter case (i.e. when the result is negative) the function also reports an error by default.

### GraphAddEdgeByPtr

Adds edge to graph

    int cvGraphAddEdgeByPtr( CvGraph* graph, CvGraphVtx* startVtx, CvGraphVtx* endVtx,
                             CvGraphEdge* edge, CvGraphEdge** insertedEdge=0 );

graph
  Graph.
startVtx
  Pointer to the starting vertex of the edge.
endVtx
  Pointer to the ending vertex of the edge. For unoriented graph the order of the vertex parameters does not matter.
edge
  Optional input parameter, initialization data for the edge.
insertedEdge
  Optional output parameter to contain the address of the inserted edge within the edge set.

The function cvGraphAddEdge connects two specified vertices. The function returns 1 if the edge has been added successfully, 0 if the edge connecting the two vertices exists already and -1 if either of the vertices was not found, the starting and the ending vertex are the same or there is some other critical situation. In the latter case (i.e. when the result is negative) the function also reports an error by default.

### GraphRemoveEdge

Removes edge from graph

    void cvGraphRemoveEdge( CvGraph* graph, int startIdx, int endIdx );

graph
  Graph.
startIdx
  Index of the starting vertex of the edge.
endIdx
  Index of the ending vertex of the edge. For unoriented graph the order of the vertex parameters does not matter.

The function cvGraphRemoveEdge removes the edge connecting two specified vertices. If the vertices are not connected [in that order], the function does nothing.

### GraphRemoveEdgeByPtr

Removes edge from graph

    void cvGraphRemoveEdgeByPtr( CvGraph* graph, CvGraphVtx* startVtx, CvGraphVtx* endVtx );

graph
  Graph.
startVtx
  Pointer to the starting vertex of the edge.
endVtx
  Pointer to the ending vertex of the edge. For unoriented graph the order of the vertex parameters does not matter.

The function cvGraphRemoveEdgeByPtr removes the edge connecting two specified vertices. If the vertices are not connected [in that order], the function does nothing.

### FindGraphEdge

Finds edge in graph

    CvGraphEdge* cvFindGraphEdge( CvGraph* graph, int startIdx, int endIdx );
    #define cvGraphFindEdge cvFindGraphEdge

graph
  Graph.
startIdx
  Index of the starting vertex of the edge.
endIdx
  Index of the ending vertex of the edge. For unoriented graph the order of the vertex parameters does not matter.

The function cvFindGraphEdge finds the graph edge connecting two specified vertices and returns pointer to it or NULL if the edge does not exists.

### FindGraphEdgeByPtr

Finds edge in graph

    CvGraphEdge* cvFindGraphEdgeByPtr( CvGraph* graph, CvGraphVtx* startVtx, CvGraphVtx* endVtx );
    #define cvGraphFindEdgeByPtr cvFindGraphEdgeByPtr

graph
  Graph.
startVtx
  Pointer to the starting vertex of the edge.
endVtx
  Pointer to the ending vertex of the edge. For unoriented graph the order of the vertex parameters does not matter.

The function cvFindGraphEdge finds the graph edge connecting two specified vertices and returns pointer to it or NULL if the edge does not exists.

### GraphEdgeIdx

Returns index of graph edge

    int cvGraphEdgeIdx( CvGraph* graph, CvGraphEdge* edge );

graph
  Graph.
edge
  Pointer to the graph edge.

The function cvGraphEdgeIdx returns index of the graph edge.

### GraphVtxDegree

Counts edges indicent to the vertex

    int cvGraphVtxDegree( CvGraph* graph, int vtxIdx );

graph
  Graph.
vtx
  Index of the graph vertex.

The function cvGraphVtxDegree returns the number of edges incident to the specified vertex, both incoming and outcoming. To count the edges, the following code is used:

        CvGraphEdge* edge = vertex->first; int count = 0;
        while( edge )
        {
            edge = CV_NEXT_GRAPH_EDGE( edge, vertex );
            count++;
        }

The macro CV_NEXT_GRAPH_EDGE( edge, vertex ) returns the edge incident to vertex that follows after edge.

### GraphVtxDegreeByPtr

Finds edge in graph

    int cvGraphVtxDegreeByPtr( CvGraph* graph, CvGraphVtx* vtx );

graph
  Graph.
vtx
  Pointer to the graph vertex.

The function cvGraphVtxDegree returns the number of edges incident to the specified vertex, both incoming and outcoming.

### ClearGraph

Clears graph

    void cvClearGraph( CvGraph* graph );

graph
  Graph.

The function cvClearGraph removes all vertices and edges from the graph. The function has O(1) time complexity.

### CloneGraph

Clone graph

    CvGraph* cvCloneGraph( const CvGraph* graph, CvMemStorage* storage );

graph
  The graph to copy.
storage
  Container for the copy.

The function cvCloneGraph creates full copy of the graph. If the graph vertices or edges have pointers to some external data, it still be shared between the copies. The vertex and edge indices in the new graph may be different from the original, because the function defragments the vertex and edge sets.

### CvGraphScanner

Graph traversal state

        typedef struct CvGraphScanner
        {
            CvGraphVtx* vtx;       /* current graph vertex (or current edge origin) */
            CvGraphVtx* dst;       /* current graph edge destination vertex */
            CvGraphEdge* edge;     /* current edge */

            CvGraph* graph;        /* the graph */
            CvSeq*   stack;        /* the graph vertex stack */
            int      index;        /* the lower bound of certainly visited vertices */
            int      mask;         /* event mask */
        }
        CvGraphScanner;

The structure CvGraphScanner is used for depth-first graph traversal. See discussion of the functions below.

### StartScanGraph

Initializes graph traverser state

    void cvStartScanGraph( CvGraph* graph, CvGraphScanner* scanner,
                           CvGraphVtx* vtx=0, int mask=CV_GRAPH_ALL_ITEMS );

graph
  Graph.
scanner
  Graph traversal state. It is initialized by the function.
vtx
  Initial vertex to start from.
mask
  Event mask indicating which events are interesting to the user (where cvNextGraphItem function returns control to the user) It can be CV_GRAPH_ALL_ITEMS (all events are interesting) or combination of the following flags:
  - CV_GRAPH_VERTEX - stop at the graph vertices visited for the first time
  - CV_GRAPH_TREE_EDGE - stop at tree edges (tree edge is the edge connecting the last visited vertex and the vertex to be visited next)
  - CV_GRAPH_BACK_EDGE - stop at back edges (back edge is the edge connecting the last visited vertex and the vertex that was visited before)
  - CV_GRAPH_FORWARD_EDGE - stop at forward edges (forward edge is the edge connecting the vertex not visited yet and the last visited vertex (in that order). The forward edges are possible only during oriented graph traversal)
  - CV_GRAPH_CROSS_EDGE - stop at cross edges (cross edge is similar to back edge but the ending vertex belongs to another traversal tree). The cross edges are also possible only during oriented graphs traversal)
  - CV_GRAPH_ANY_EDGE - stop and any edge (tree, back, forward and cross edges)
  - CV_GRAPH_NEW_TREE - stop in the beginning of every new traversal tree. When the traversal procedure visits all vertices and edges reachible from the initial vertex (the visited vertices together with tree edges make up a tree), it search for some unvisited vertices in the graph and resumes the traversal process from the vertex. Before starting the new tree (including the initial call of the traversal procedure) it generates CV_GRAPH_NEW_TREE event.
    For unoriented graphs traversal tree corresponds to a connected component of the graph.
  - CV_GRAPH_BACKTRACKING - stop at every already visited vertex during backtracking - returning to visited already visited vertexes of the traversal tree.

The function cvStartScanGraph initializes graph traverser state. The initialized structure is used in cvNextGraphItem function - the incremental traversal procedure.

### NextGraphItem

Makes one or more steps of the graph traversal procedure

    int cvNextGraphItem( CvGraphScanner* scanner );

scanner
  Graph traversal state. It is updated by the function.

The function cvNextGraphItem traverses through the graph until an event interesting to the user (that is, an event, marked in the mask in cvStartScanGraph call) is met or the traversal is over. In the first case it returns one of the events, listed in the description of mask parameter above and with the next call with the same state it resumes the traversal. In the latter case it returns CV_GRAPH_OVER (-1). When the event is CV_GRAPH_VERTEX, or CV_GRAPH_BACKTRACKING or CV_GRAPH_NEW_TREE, the currently observed vertex is stored in scanner->vtx. And if the event is edge-related, the edge itself is stored at scanner->edge, the previously visited vertex - at scanner->vtx and the other ending vertex of the edge - at scanner->dst.

### EndScanGraph

Finishes graph traversal procedure

    void cvEndScanGraph( CvGraphScanner* scanner );

scanner
  Graph traversal state.

The function cvEndScanGraph finishes graph traversal procedure. It must be called after CV_GRAPH_OVER event is received or if the traversal is interrupted somewhere before, because the traverser state contains dynamically allocated structures that need to be released

## Trees

### CV_TREE_NODE_FIELDS

Helper macro for a tree node type declaration

    #define CV_TREE_NODE_FIELDS(node_type)                          \
        int       flags;         /* micsellaneous flags */          \
        int       header_size;   /* size of sequence header */      \
        struct    node_type* h_prev; /* previous sequence */        \
        struct    node_type* h_next; /* next sequence */            \
        struct    node_type* v_prev; /* 2nd previous sequence */    \
        struct    node_type* v_next; /* 2nd next sequence */

The macro CV_TREE_NODE_FIELDS() is used to declare structures that can be organized into hierarchical strucutures (trees). Although, it is not shown, the macro is used to declared CvSeq - the basic type for all dynamical structures and CvFileNode - XML node type used in reading/writing functions (see Persistence section below). The trees made of nodes declared using this macro can be processed using the functions described below in this section.

### CvTreeNodeIterator

Opens existing or creates new file storage

    typedef struct CvTreeNodeIterator
    {
        const void* node;
        int level;
        int maxLevel;
    }
    CvTreeNodeIterator;

The structure CvTreeNodeIterator is used to traverse trees. The tree node declaration should start with CV_TREE_NODE_FIELDS(...) macro.

### InitTreeNodeIterator

Initializes tree node iterator

    void cvInitTreeNodeIterator( CvTreeNodeIterator* treeIterator,
                                 const void* first, int maxLevel );

treeIterator
  Tree iterator initialized by the function.
first
  The initial node to start traversing from.
maxLevel
  The maximal level of the tree (first node assumed to be at the first level) to traverse up to. For example, 1 means that only nodes at the same level as first should be visited, 2 means that the nodes on the same level as first and their direct children should be visited etc.

The function cvInitTreeNodeIterator initializes tree iterator. The tree is traversed in depth-first order.

### NextTreeNode

Returns the currently observed node and moves iterator toward the next node

    void* cvNextTreeNode( CvTreeNodeIterator* treeIterator );

treeIterator
  Tree iterator initialized by the function.

The function cvNextTreeNode returns the currently observed node and then updates the iterator - moves it toward the next node. In other words, the function behavior is similar to *p++ expression on usual C pointer or C++ collection iterator. The function returns NULL if there is no more nodes.

### PrevTreeNode

Returns the currently observed node and moves iterator toward the previous node

    void* cvPrevTreeNode( CvTreeNodeIterator* treeIterator );

treeIterator
  Tree iterator initialized by the function.

The function cvPrevTreeNode returns the currently observed node and then updates the iterator - moves it toward the previous node. In other words, the function behavior is similar to *p-- expression on usual C pointer or C++ collection iterator. The function returns NULL if there is no more nodes.

### TreeToNodeSeq

Gathers all node pointers to the single sequence

    CvSeq* cvTreeToNodeSeq( const void* first, int header_size, CvMemStorage* storage );

first
  The initial tree node.
header_size
  Header size of the created sequence (sizeof(CvSeq) is the most used value).
storage
  Container for the sequence.

The function cvTreeToNodeSeq puts pointers of all nodes reacheable from first to the single sequence. The pointers are written subsequently in the depth-first order.

### InsertNodeIntoTree

Adds new node to the tree

    void cvInsertNodeIntoTree( void* node, void* parent, void* frame );

node
  The inserted node.
parent
  The parent node that is already in the tree.
frame
  The top level node. If parent and frame are the same, v_prev field of node is set to NULL rather than parent.

The function cvInsertNodeIntoTree adds another node into tree. The function does not allocate any memory, it can only modify links of the tree nodes.

### RemoveNodeFromTree

Removes node from tree

    void cvRemoveNodeFromTree( void* node, void* frame );

node
  The removed node.
frame
  The top level node. If node->v_prev = NULL and node->h_prev is NULL (i.e. if node is the first child of frame), frame->v_next is set to node->h_next (i.e. the first child or frame is changed).

The function cvRemoveNodeFromTree removes node from tree. The function does not deallocate any memory, it can only modify links of the tree nodes.

## Persistence (Writing and Reading Structures)

### OpenFileStorage

Opens existing or creates new file storage

    CvFileStorage*  cvOpenFileStorage( const char* filename, CvMemStorage* memstorage, int flags );

filename
  The storage file name.
memstorage
  Memory storage used for storing temporary data and read dynamic structures. If it is NULL, the temporary memory storage is created and used.
flags
  Can be one of the following:
  CV_STORAGE_READ - the storage is open for reading
  CV_STORAGE_WRITE_TEXT - the storage is open for writing data in text format
  CV_STORAGE_WRITE_BINARY - the storage is open for writing data in XDR and base64-encoded binary format

The function cvOpenFileStorage open existing file storage or creates a new storage. The file has XML format and it allows user to store as standard OpenCV arrays and dynamic structures as well as custom data structures. The function returns pointer to CvFileStorage structure, which declaration is hidden, though not needed to access directly.

### ReleaseFileStorage

Releases file storage

    void  cvReleaseFileStorage( CvFileStorage** storage );

storage
  Double pointer to the released file storage.

The function cvReleaseFileStorage closes the file on disk that has been written or read and releases all temporary structures. It must be called after all I/O operations with the storage are finished.

### Write

Writes array or dynamic structure to the file storage

    void  cvWrite( CvFileStorage* storage, const char* name,
                   const void* structPtr,
                   CvAttrList attributes=cvAttrList(),
                   int flags=0 );

storage
  File storage.
name
  Name, or ID, of the written structure. It is used to index the written information and then access it using these ID's. If it is NULL or empty (""), no ID is written. If it has special value "<auto>", the address of the written structure in heximal notation will be used as the name.
structPtr
  The written structure - CvMat*, IplImage*, CvSeq*, CvGraph* etc.
attributes
  The list of attributes that can be formed from NULL-terminated array of <attr_name, attr_value> pairs using cvAttrList() function (see the example below). Most often it is just empty. The passed attributes override standard attributes with the same name, e.g. user may specify header_dt or dt attributes to write dynamic structures with custom headers and element types.
flags
  The operation flags passed into the specific loading/storing function for the particular data type. Usually it is not used and may be set to 0. In case of contour trees (for details see cvFindContours function in Structural Analysis chapter of the reference) it may be set to CV_WRITE_TREE to force the whole contour tree to be written.

The function cvWrite writes a passed structure to OpenCV file storage. The sample below demonstrates how to write different types of data to storage.

    /****************** Writing Data **************************/
    #include <cv.h>

    int main( int argc, char** argv )
    {
        CvMemStorage* memstorage = cvCreateMemStorage(0);
        CvFileStorage* storage = cvOpenFileStorage( "sample.xml", 0, CV_STORAGE_WRITE_TEXT );
        CvMat* mat = cvCreateMat( 3, 3, CV_32FC1 );
        CvSeq* seq = cvCreateSeq( CV_32SC1, sizeof(CvSeq), sizeof(int), memstorage );
        char* seq_attr[] =
        {
        "created_by", argv[0],
        "the_sequence_creation_date", "1 Sep 2002",
        "comment", "just a comment",
        0
        };
        CvTermCriteria criteria = { CV_TERMCRIT_ITER|CV_TERMCRIT_EPS, 10, 0.1 };
        const char* string1 = "test";
        int i;

        cvSetIdentity( mat );
        cvWrite( storage, "The identity matrix", mat, cvAttrList(), 0 );

        for( i = 0; i < 10; i++ )
            cvSeqPush( seq, &i );

        cvWrite( storage, "SmallSequence", seq, cvAttrList(seq_attr,0), 0 );
        cvWriteElem( storage, "SampleStructure", "iid", &criteria ); /* writing C structure, see below */
        cvWriteElem( storage, "SampleString", "a", string1 ); /* writing C string, see below */

        cvReleaseFileStorage( &storage );
        cvReleaseMemStorage( &memstorage );
        return 0;
    }
    /**********************************************************/

After compiling and runnning the sample the file sample.xml will contain something like this:

    <?xml version="1.0"?>
    <opencv_storage>
    <struct id="The identity matrix" type="CvMat" dt="f" size="3 3" format="text">
      1.000000e+000  0.000000e+000  0.000000e+000  0.000000e+000  1.000000e+000
      0.000000e+000  0.000000e+000  0.000000e+000  1.000000e+000
    </struct>
    <struct id="SmallSequence" type="CvSeq" flags="42990003" dt="i" format="text"
     created_by="D:\OpenCV\bin\test.exe" the_sequence_creation_date="1 Sep 2002"
     comment="just a comment">
          0      1      2      3      4      5      6      7      8      9
    </struct>
    <elem id="SampleStructure" dt="iid" value="      3     10  1.000000000000000e-001"/>
    <elem id="SampleString" dt="a" value="test"/>
    </opencv_storage>

### StartWriteStruct

Writes the opening tag of a compound structure

    void  cvStartWriteStruct( CvFileStorage* storage, const char* name,
                              const char* typeName=0, const void* structPtr=0,
                              CvAttrList attributes=cvAttrList());

storage
  File storage.
name
  Name, or ID, of the written structure. It is used to index the written information and then access it using these ID's. If it is NULL or empty (""), no ID is written. If it has special value "<auto>", the address of the written structure in heximal notation will be used as the name.
structPtr
  The written structure pointer. It is not used unless name = "<auto>".
attributes
  The list of attributes (the same as in the previous function)

The function cvStartWriteStruct writes the opening tag of a compound structure. It is used by cvWrite function and can be used explicitly to group some structures or write an writer for some custom data structure.

### EndWriteStruct

Closes the last opened tag

    void  cvEndWriteStruct( CvFileStorage* storage );

storage
  File storage.

The function cvEndWriteStruct closes the most recent opened tag.

### WriteElem

Writes a scalar variable

    void  cvWriteElem( CvFileStorage* storage, const char* name,
                       const char* elem_spec, const void* data_ptr );

storage
  File storage
name
  Name, or ID, of the written scalar. As usual, "<auto>" means that the data pointer will be used as a name.
elem_spec
  A sequence of character each of whose specifies a type of particualar field of the written structure:
  - 'a' - NULL-terminated C string. It must be the only character of specification string.
  - 'u' - 8-bit unsigned number
  - 'c' - 8-bit signed number
  - 's' - 16-bit signed number
  - 'i' - 32-bit signed number
  - 'f' - single precision floating-point number
  - 'd' - double precision floating-point number
  - 'p' - pointer, it is not stored, but it takes some space in the input structure, so it must be specified in order to write the subsequent fields correctly.
  - 'r' - the same as pointer, but the integer number, but the lowest 32 bit of the pointer are written as an integer. This is useful for storing dynamic structures where different nodes reference each other. In this case the pointers are replaced with some indices, the structure is written and, the pointers are restored back.
data_ptr
  Pointer to the written data. The written data can be a single value of one of basic numerical types (unsigned char, char, short, int, float or double), C structure containing one or more numerical fields or a character string. In case of C structures an ideal alignment must be used - short's must be aligned by 2 bytes, integer's and float's by 4 bytes and double's by 8 bytes. Usually such an alignment is used by C/C++ compiler by default, however some structures, e.g. BITMAPFILEHEADER Win32 structure break this rule. If you want to store such a structure, you may use sprintf( elem_spec, "%du", sizeof(my_struct)) to form an element spec that allows to store arbitrary structure, though the representation will neither be readable nor portable.

The function cvWriteElem writes a single numberical value, a structure of numerical values or a character string. Here are some examples (see cvWrite function discussion for complete sample):

    CvScalar scalar = { 1., 2., 3.14, 4. };
    cvWriteElem( filestorage, "scalar1", "4d", &scalar );

    CvPoint pt = { 100, 50 };
    cvWriteElem( filestorage, "feature_point", "2i", &pt };

    struct
    {
        char c;
        uchar u;
        short s;
        int i;
        float f;
        double d;
    }
    big_twos = { 20, 200, 20000, 2000000, 2e10, 2e100 };
    cvWriteElem( filestorage, "big_twos", "cusifd", &big_twos );

    cvWriteElem( filestorage, "string1", "a", "Hello, world!" };

### Read

Reads array or dynamic structure from the file storage

    void*  cvRead( CvFileStorage* storage, const char* name, CvAttrList** list=0 );

storage
  File storage.
name
  Name of the structure to read.
list
  Optional output parameter that is filled with the node attributes list.

The function cvRead reads a structure with the specified name from OpenCV file storage. The structure is stored inside the file storage so it is be deallocated when the file storage is released, except the case when it is dynamic strucutre and non-NULL memory storage was passed to cvOpenFileStorage function. If you want to keep the sturcture, use cvClone*.

### ReadElem

Reads a scalar variable

    void  cvReadElem( CvFileStorage* storage, const char* name, void* data_ptr );

storage
  File storage
name
  Name of the variable to read.
data_ptr
  Pointer to the destination structure. In case of strings, data_ptr should be char** - pointer to the string pointer that is filled by the function.

The function cvReadElem reads a single numberical value, a structure of numerical values or a character string. The order the variables are read in may be different from the order they are written. Here are examples - counterparts for examples from cvWriteElem discussion:

    CvScalar scalar;
    cvWriteElem( filestorage, "scalar1", &scalar );

    CvPoint pt;
    cvWriteElem( filestorage, "feature_point", &pt };

    struct
    {
        char c;
        uchar u;
        short s;
        int i;
        float f;
        double d;
    }
    big_twos;

    cvReadElem( filestorage, "big_twos", &big_twos );

    const char* string1 = 0;
    cvReadElem( filestorage, "string1", (void*)&string1 };

### CvFileNode

XML node representation

    typedef struct CvFileNode
    {
        int       flags;         /* micsellaneous flags */
        int       header_size;   /* size of node header */
        struct    node_type* h_prev; /* previous node having the same parent */
        struct    node_type* h_next; /* next node having the same parent */
        struct    node_type* v_prev; /* the parent node */
        struct    node_type* v_next; /* the first child node */
        const char* tagname; /* INTERNAL: XML tag name */
        const char* name; /* the node name */
        CvAttrList* attr; /* list of attributes */
        struct CvFileNode* hash_next; /* INTERNAL: next entry in hash table */
        unsigned hash_val; /* INTERNAL: hash value */
        int elem_size; /* size of a structure elements */
        struct CvTypeInfo* typeinfo; /* INTERNAL: type information */
        const char* body; /* INTERNAL: pointer to the structure or scalar content within XML file,
                             filled by XML parser */
        const void* content; /* the read structure, NULL if it is read yet */
    }
    CvFileNode;

The structure CvFileNode represents an XML node - building block of OpenCV file storage. The nodes are organized into tree that has a root node correponding to <opencv_storage> tag. When a file storage is written, the tree is constructed by cvWrite, cvStartWriteStruct, cvEndWriteStruct and cvWriteElem functions, and it does not to be accessed directly in most of cases. When the file storage is read, the whole tree is reconstructed by XML parser in cvOpenFileStorage function, but none of nodes are decoded. Instead, a particular node can be decoded via cvReadFileNode function, after its pointer is retrived by the node name using cvGetFileNode function or the node is reached from the root node. The functions cvInitTreeNodeIterator, cvNextTreeNode and cvPrevTreeNode can be used to traverse the XML tree. When the node is decoded, content field becomes valid and the same pointer will be returned by sebsequent calls to cvReadFileNode or cvRead for this node.

### GetFileNode

Finds XML node by name

    CvFileNode* cvGetFileNode( CvFileStorage* storage, const char* name );

storage
  File storage.
name
  The searched node name. If it is NULL, the root of the XML tree is returned.

The function cvGetFileNode locates XML node by name and returns pointer to the node or NULL if the node is not found.

.

### ReadFileNode

Decodes XML node content

    void* cvReadFileNode( CvFileStorage* storage, CvFileNode* node, CvAttrList** list=0 );

storage
  File storage.
node
  The node to decode.
list
  Optional output parameter that is filled with the node attributes list.

The function cvReadFileNode decodes the file node content. If content field of the node is not NULL, no decoding is done and the pointer is simply returned.

.