CV Reference Manual

• Image Processing
  • Gradients, Edges and Corners
  • Sampling, Interpolation and Geometrical Transforms
  • Morphological Operations
  • Filters and Color Conversion
  • Pyramids and the Applications
  • Image Segmentation, Connected Components and Contour Retrieval
  • Image and Contour Moments
  • Special Image Transforms
  • Histograms
  • Matching
• Structural Analysis
  • Contour Processing
  • Computational Geometry
  • Planar Subdivisions
• Motion Analysis and Object Tracking
  • Accumulation of Background Statistics
  • Motion Templates
  • Object Tracking
  • Optical Flow
  • Estimators
• Pattern Recognition
  • Object Detection
• Camera Calibration and 3D Reconstruction
  • Camera Calibration
  • Pose Estimation
  • Epipolar Geometry
• Alphabetical List of Functions
• Bibliography

Image Processing

Note:
The chapter describes functions for image processing and analysis. Most of the functions work with 2d arrays of pixels. We refer the arrays as "images" however they do not neccesserily have to be IplImage’s, they may be CvMat’s or CvMatND’s as well.

Gradients, Edges and Corners

Sobel

Calculates first, second, third or mixed image derivatives using extended Sobel operator

void cvSobel( const CvArr* src, CvArr* dst, int xorder, int yorder, int aperture_size=3 );

src

Source image.

dst

Destination image.

xorder

Order of the derivative x .

yorder

Order of the derivative y .

aperture_size

Size of the extended Sobel kernel, must be 1, 3, 5 or 7. In all cases except 1, aperture_size ×aperture_size separable kernel will be used to calculate the derivative. For aperture_size=1 3x1 or 1x3 kernel is used (Gaussian smoothing is not done). There is also special value CV_SCHARR (=-1) that corresponds to 3x3 Scharr filter that may give more accurate results than 3x3 Sobel. Scharr aperture is:

| -3 0  3|
|-10 0 10|
| -3 0  3|

for x-derivative or transposed for y-derivative.

The function cvSobel calculates the image derivative by convolving the image with the appropriate kernel:

dst(x,y) = dxorder+yodersrc/dxxorder•dyyorder |(x,y)

  |-1  0  1|
  |-2  0  2|
  |-1  0  1|

kernel and the second one corresponds to

  |-1 -2 -1|
  | 0  0  0|
  | 1  2  1|
or
  | 1  2  1|
  | 0  0  0|
  |-1 -2 -1|

Laplace

Calculates Laplacian of the image

void cvLaplace( const CvArr* src, CvArr* dst, int aperture_size=3 );

src

Source image.

dst

Destination image.

aperture_size

Aperture size (it has the same meaning as in cvSobel).

The function cvLaplace calculates Laplacian of the source image by summing second x- and y- derivatives calculated using Sobel operator:

dst(x,y) = d2src/dx2 + d2src/dy2

Specifying aperture_size=1 gives the fastest variant that is equal to convolving the image with the following kernel:

|0  1  0|
|1 -4  1|
|0  1  0|

Similar to cvSobel function, no scaling is done and the same combinations of input and output formats are supported.

Canny

Implements Canny algorithm for edge detection

void cvCanny( const CvArr* image, CvArr* edges, double threshold1,
              double threshold2, int aperture_size=3 );

image

Input image.

edges

Image to store the edges found by the function.

threshold1

The first threshold.

threshold2

The second threshold.

aperture_size

Aperture parameter for Sobel operator (see cvSobel).

The function cvCanny finds the edges on the input image image and marks them in the output image edges using the Canny algorithm. The smallest of threshold1 and threshold2 is used for edge linking, the largest - to find initial segments of strong edges.

PreCornerDetect

Calculates feature map for corner detection

void cvPreCornerDetect( const CvArr* image, CvArr* corners, int aperture_size=3 );

image

Input image.

corners

Image to store the corner candidates.

aperture_size

Aperture parameter for Sobel operator (see cvSobel).

The function cvPreCornerDetect calculates the function D_x²D_yy+D_y²D_xx - 2D_xD_yD_xy where D_? denotes one of the first image derivatives and D_?? denotes a second image derivative. The corners can be found as local maximums of the function:

// assume that the image is floating-point
IplImage* corners = cvCloneImage(image);
IplImage* dilated_corners = cvCloneImage(image);
IplImage* corner_mask = cvCreateImage( cvGetSize(image), 8, 1 );
cvPreCornerDetect( image, corners, 3 );
cvDilate( corners, dilated_corners, 0, 1 );
cvSubS( corners, dilated_corners, corners );
cvCmpS( corners, 0, corner_mask, CV_CMP_GE );
cvReleaseImage( &corners );
cvReleaseImage( &dilated_corners );

CornerEigenValsAndVecs

Calculates eigenvalues and eigenvectors of image blocks for corner detection

void cvCornerEigenValsAndVecs( const CvArr* image, CvArr* eigenvv,
                               int block_size, int aperture_size=3 );

image

Input image.

eigenvv

Image to store the results. It must be 6 times wider than the input image.

block_size

Neighborhood size (see discussion).

aperture_size

Aperture parameter for Sobel operator (see cvSobel).

For every pixel The function cvCornerEigenValsAndVecs considers block_size × block_size neigborhood S(p). It calcualtes covariation matrix of derivatives over the neigborhood as:

    | sumS(p)(dI/dx)2   sumS(p)(dI/dx•dI/dy)|
M = |                                 |
    | sumS(p)(dI/dx•dI/dy)  sumS(p)(dI/dy)2 |

After that it finds eigenvectors and eigenvalues of the matrix and stores them into destination image in form (λ₁, λ₂, x₁, y₁, x₂, y₂), where
λ₁, λ₂ - eigenvalues of M; not sorted
(x₁, y₁) - eigenvector corresponding to λ₁
(x₂, y₂) - eigenvector corresponding to λ₂

CornerMinEigenVal

Calculates minimal eigenvalue of gradient matrices for corner detection

void cvCornerMinEigenVal( const CvArr* image, CvArr* eigenval, int block_size, int aperture_size=3 );

image

Input image.

eigenval

Image to store the minimal eigen values. Should have the same size as image

block_size

Neighborhood size (see discussion of cvCornerEigenValsAndVecs).

aperture_size

Aperture parameter for Sobel operator (see cvSobel). format. In the case of floating-point input format this parameter is the number of the fixed float filter used for differencing.

The function cvCornerMinEigenVal is similar to cvCornerEigenValsAndVecs but it calculates and stores only the minimal eigen value of derivative covariation matrix for every pixel, i.e. min(λ₁, λ₂) in terms of the previous function.

CornerHarris

Harris edge detector

void cvCornerHarris( const CvArr* image, CvArr* harris_responce,
                     int block_size, int aperture_size=3, double k=0.04 );

image

Input image.

harris_responce

Image to store the Harris detector responces. Should have the same size as image

block_size

Neighborhood size (see discussion of cvCornerEigenValsAndVecs).

aperture_size

Aperture parameter for Sobel operator (see cvSobel). format. In the case of floating-point input format this parameter is the number of the fixed float filter used for differencing.

k

Harris detector free parameter. See the formula below.

The function cvCornerHarris runs the Harris edge detector on image. Similarly to cvCornerMinEigenVal and cvCornerEigenValsAndVecs, for each pixel it calculates 2x2 gradient covariation matrix M over block_size×block_size neighborhood. Then, it stores

det(M) - k*trace(M)2

FindCornerSubPix

Refines corner locations

void cvFindCornerSubPix( const CvArr* image, CvPoint2D32f* corners,
                         int count, CvSize win, CvSize zero_zone,
                         CvTermCriteria criteria );

image

Input image.

corners

Initial coordinates of the input corners and refined coordinates on output.

count

Number of corners.

win

Half sizes of the search window. For example, if win=(5,5) then 5*2+1 × 5*2+1 = 11 × 11 search window is used.

zero_zone

Half size of the dead region in the middle of the search zone over which the summation in formulae below is not done. It is used sometimes to avoid possible singularities of the autocorrelation matrix. The value of (-1,-1) indicates that there is no such size.

criteria

Criteria for termination of the iterative process of corner refinement. That is, the process of corner position refinement stops either after certain number of iteration or when a required accuracy is achieved. The criteria may specify either of or both the maximum number of iteration and the required accuracy.

The function cvFindCornerSubPix iterates to find the sub-pixel accurate location of corners, or radial saddle points, as shown in on the picture below.

Sub-pixel accurate corner locator is based on the observation that every vector from the center q to a point p located within a neighborhood of q is orthogonal to the image gradient at p subject to image and measurement noise. Consider the expression:

εi=DIpiT•(q-pi)

sumi(DIpi•DIpiT)•q - sumi(DIpi•DIpiT•pi) = 0

where the gradients are summed within a neighborhood ("search window") of q. Calling the first gradient term G and the second gradient term b gives:

q=G-1•b

The algorithm sets the center of the neighborhood window at this new center q and then iterates until the center keeps within a set threshold.

GoodFeaturesToTrack

Determines strong corners on image

void cvGoodFeaturesToTrack( const CvArr* image, CvArr* eig_image, CvArr* temp_image,
                            CvPoint2D32f* corners, int* corner_count,
                            double quality_level, double min_distance,
                            const CvArr* mask=NULL, int block_size=3,
                            int use_harris=0, double k=0.04 );

image

The source 8-bit or floating-point 32-bit, single-channel image.

eig_image

Temporary floating-point 32-bit image of the same size as image.

temp_image

Another temporary image of the same size and same format as eig_image.

corners

Output parameter. Detected corners.

corner_count

Output parameter. Number of detected corners.

quality_level

Multiplier for the maxmin eigenvalue; specifies minimal accepted quality of image corners.

min_distance

Limit, specifying minimum possible distance between returned corners; Euclidian distance is used.

mask

Region of interest. The function selects points either in the specified region or in the whole image if the mask is NULL.

block_size

Size of the averaging block, passed to underlying cvCornerMinEigenVal or cvCornerHarris used by the function.

use_harris

If nonzero, Harris operator (cvCornerHarris) is used instead of default cvCornerMinEigenVal.

k

Free parameter of Harris detector; used only if use_harris≠0

The function cvGoodFeaturesToTrack finds corners with big eigenvalues in the image. The function first calculates the minimal eigenvalue for every source image pixel using cvCornerMinEigenVal function and stores them in eig_image. Then it performs non-maxima suppression (only local maxima in 3x3 neighborhood remain). The next step is rejecting the corners with the minimal eigenvalue less than quality_level•max(eig_image(x,y)). Finally, the function ensures that all the corners found are distanced enough one from another by considering the corners (the most strongest corners are considered first) and checking that the distance between the newly considered feature and the features considered earlier is larger than min_distance. So, the function removes the features than are too close to the stronger features.

Sampling, Interpolation and Geometrical Transforms

SampleLine

Reads raster line to buffer

int cvSampleLine( const CvArr* image, CvPoint pt1, CvPoint pt2,
                  void* buffer, int connectivity=8 );

image

Image to sample the line from.

pt1

Starting the line point.

pt2

Ending the line point.

buffer

Buffer to store the line points; must have enough size to store max( |pt2.x-pt1.x|+1, |pt2.y-pt1.y|+1 ) points in case of 8-connected line and |pt2.x-pt1.x|+|pt2.y-pt1.y|+1 in case of 4-connected line.

connectivity

The line connectivity, 4 or 8.

The function cvSampleLine implements a particular case of application of line iterators. The function reads all the image points lying on the line between pt1 and pt2, including the ending points, and stores them into the buffer.

GetRectSubPix

Retrieves pixel rectangle from image with sub-pixel accuracy

void cvGetRectSubPix( const CvArr* src, CvArr* dst, CvPoint2D32f center );

src

Source image.

dst

Extracted rectangle.

center

Floating point coordinates of the extracted rectangle center within the source image. The center must be inside the image.

The function cvGetRectSubPix extracts pixels from src:

dst(x, y) = src(x + center.x - (width(dst)-1)*0.5, y + center.y - (height(dst)-1)*0.5)

where the values of pixels at non-integer coordinates are retrieved using bilinear interpolation. Every channel of multiple-channel images is processed independently. Whereas the rectangle center must be inside the image, the whole rectangle may be partially occluded. In this case, the replication border mode is used to get pixel values beyond the image boundaries.

GetQuadrangleSubPix

Retrieves pixel quadrangle from image with sub-pixel accuracy

void cvGetQuadrangleSubPix( const CvArr* src, CvArr* dst, const CvMat* map_matrix );

src

Source image.

dst

Extracted quadrangle.

map_matrix

The transformation 2 × 3 matrix [A|b] (see the discussion).

The function cvGetQuadrangleSubPix extracts pixels from src at sub-pixel accuracy and stores them to dst as follows:

dst(x, y)= src( A11x'+A12y'+b1, A21x'+A22y'+b2),

where A and b are taken from map_matrix
             | A11 A12  b1 |
map_matrix = |            |
             | A21 A22  b2 |,

x'=x-(width(dst)-1)*0.5, y'=y-(height(dst)-1)*0.5

where the values of pixels at non-integer coordinates A•(x,y)^T+b are retrieved using bilinear interpolation. When the function needs pixels outside of the image, it uses replication border mode to reconstruct the values. Every channel of multiple-channel images is processed independently.

Resize

Resizes image

void cvResize( const CvArr* src, CvArr* dst, int interpolation=CV_INTER_LINEAR );

src

Source image.

dst

Destination image.

interpolation

Interpolation method:

• CV_INTER_NN - nearest-neigbor interpolation,
• CV_INTER_LINEAR - bilinear interpolation (used by default)
• CV_INTER_AREA - resampling using pixel area relation. It is preferred method for image decimation that gives moire-free results. In case of zooming it is similar to CV_INTER_NN method.
• CV_INTER_CUBIC - bicubic interpolation.

The function cvResize resizes image src so that it fits exactly to dst. If ROI is set, the function consideres the ROI as supported as usual.

WarpAffine

Applies affine transformation to the image

void cvWarpAffine( const CvArr* src, CvArr* dst, const CvMat* map_matrix,
                   int flags=CV_INTER_LINEAR+CV_WARP_FILL_OUTLIERS,
                   CvScalar fillval=cvScalarAll(0) );

src

Source image.

dst

Destination image.

map_matrix

2×3 transformation matrix.

flags

A combination of interpolation method and the following optional flags:

• CV_WARP_FILL_OUTLIERS - fill all the destination image pixels. If some of them correspond to outliers in the source image, they are set to fillval.
• CV_WARP_INVERSE_MAP - indicates that matrix is inverse transform from destination image to source and, thus, can be used directly for pixel interpolation. Otherwise, the function finds the inverse transform from map_matrix.

fillval

A value used to fill outliers.

The function cvWarpAffine transforms source image using the specified matrix:

dst(x’,y’)<-src(x,y)
(x’,y’)T=map_matrix•(x,y,1)T+b if CV_WARP_INVERSE_MAP is not set,
(x, y)T=map_matrix•(x’,y&apos,1)T+b otherwise

The function is similar to cvGetQuadrangleSubPix but they are not exactly the same. cvWarpAffine requires input and output image have the same data type, has larger overhead (so it is not quite suitable for small images) and can leave part of destination image unchanged. While cvGetQuadrangleSubPix may extract quadrangles from 8-bit images into floating-point buffer, has smaller overhead and always changes the whole destination image content.

To transform a sparse set of points, use cvTransform function from cxcore.

GetAffineTransform

Calculates affine transform from 3 corresponding points

CvMat* cvGetAffineTransform( const CvPoint2D32f* src, const CvPoint2D32f* dst, 
                             CvMat* map_matrix );

src

Coordinates of 3 triangle vertices in the source image.

dst

Coordinates of the 3 corresponding triangle vertices in the destination image.

map_matrix

Pointer to the destination 2×3 matrix.

The function cvGetAffineTransform calculates the matrix of an affine transform such that:

(x'i,y'i)T=map_matrix•(xi,yi,1)T

where dst(i)=(x'i,y'i), src(i)=(xi,yi), i=0..2.

2DRotationMatrix

Calculates affine matrix of 2d rotation

CvMat* cv2DRotationMatrix( CvPoint2D32f center, double angle,
                           double scale, CvMat* map_matrix );

center

Center of the rotation in the source image.

angle

The rotation angle in degrees. Positive values mean couter-clockwise rotation (the coordiate origin is assumed at top-left corner).

scale

Isotropic scale factor.

map_matrix

Pointer to the destination 2×3 matrix.

The function cv2DRotationMatrix calculates matrix:

[  α  β  |  (1-α)*center.x - β*center.y ]
[ -β  α  |  β*center.x + (1-α)*center.y ]

where α=scale*cos(angle), β=scale*sin(angle)

The transformation maps the rotation center to itself. If this is not the purpose, the shift should be adjusted.

WarpPerspective

Applies perspective transformation to the image

void cvWarpPerspective( const CvArr* src, CvArr* dst, const CvMat* map_matrix,
                        int flags=CV_INTER_LINEAR+CV_WARP_FILL_OUTLIERS,
                        CvScalar fillval=cvScalarAll(0) );

src

Source image.

dst

Destination image.

map_matrix

3×3 transformation matrix.

flags

A combination of interpolation method and the following optional flags:

• CV_WARP_FILL_OUTLIERS - fill all the destination image pixels. If some of them correspond to outliers in the source image, they are set to fillval.
• CV_WARP_INVERSE_MAP - indicates that matrix is inverse transform from destination image to source and, thus, can be used directly for pixel interpolation. Otherwise, the function finds the inverse transform from map_matrix.

fillval

A value used to fill outliers.

The function cvWarpPerspective transforms source image using the specified matrix:

dst(x’,y’)<-src(x,y)
(t•x’,t•y’,t)T=map_matrix•(x,y,1)T+b if CV_WARP_INVERSE_MAP is not set,
(t•x, t•y, t)T=map_matrix•(x’,y&apos,1)T+b otherwise

For a sparse set of points use cvPerspectiveTransform function from cxcore.

GetPerspectiveTransform

Calculates perspective transform from 4 corresponding points

CvMat* cvGetPerspectiveTransform( const CvPoint2D32f* src, const CvPoint2D32f* dst,
                                  CvMat* map_matrix );

#define cvWarpPerspectiveQMatrix cvGetPerspectiveTransform

src

Coordinates of 4 quadrangle vertices in the source image.

dst

Coordinates of the 4 corresponding quadrangle vertices in the destination image.

map_matrix

Pointer to the destination 3×3 matrix.

The function cvGetPerspectiveTransform calculates matrix of perspective transform such that:

(ti•x'i,ti•y'i,ti)T=map_matrix•(xi,yi,1)T

where dst(i)=(x'i,y'i), src(i)=(xi,yi), i=0..3.

Remap

Applies generic geometrical transformation to the image

void cvRemap( const CvArr* src, CvArr* dst,
              const CvArr* mapx, const CvArr* mapy,
              int flags=CV_INTER_LINEAR+CV_WARP_FILL_OUTLIERS,
              CvScalar fillval=cvScalarAll(0) );

src

Source image.

dst

Destination image.

mapx

The map of x-coordinates (32fC1 image).

mapy

The map of y-coordinates (32fC1 image).

flags

A combination of interpolation method and the following optional flag(s):

• CV_WARP_FILL_OUTLIERS - fill all the destination image pixels. If some of them correspond to outliers in the source image, they are set to fillval.

fillval

A value used to fill outliers.

The function cvRemap transforms source image using the specified map:

dst(x,y)<-src(mapx(x,y),mapy(x,y))

Similar to other geometrical transformations, some interpolation method (specified by user) is used to extract pixels with non-integer coordinates.

LogPolar

Remaps image to log-polar space

void cvLogPolar( const CvArr* src, CvArr* dst,
                 CvPoint2D32f center, double M,
                 int flags=CV_INTER_LINEAR+CV_WARP_FILL_OUTLIERS );

src

Source image.

dst

Destination image.

center

The transformation center, where the output precision is maximal.

M

Magnitude scale parameter. See below.

flags

A combination of interpolation method and the following optional flags:

• CV_WARP_FILL_OUTLIERS - fill all the destination image pixels. If some of them correspond to outliers in the source image, they are set to zeros.
• CV_WARP_INVERSE_MAP - indicates that matrix is inverse transform from destination image to source and, thus, can be used directly for pixel interpolation. Otherwise, the function finds the inverse transform from map_matrix.

fillval

A value used to fill outliers.

The function cvLogPolar transforms source image using the following transformation:

Forward transformation (CV_WARP_INVERSE_MAP is not set):
dst(phi,rho)<-src(x,y)

Inverse transformation (CV_WARP_INVERSE_MAP is set):
dst(x,y)<-src(phi,rho),

where rho=M*log(sqrt(x2+y2))
      phi=atan(y/x)

The function emulates the human "foveal" vision and can be used for fast scale and rotation-invariant template matching, for object tracking etc.

Example. Log-polar transformation.

#include <cv.h>
#include <highgui.h>

int main(int argc, char** argv)
{
    IplImage* src;

    if( argc == 2 && (src=cvLoadImage(argv[1],1) != 0 )
    {
        IplImage* dst = cvCreateImage( cvSize(256,256), 8, 3 );
        IplImage* src2 = cvCreateImage( cvGetSize(src), 8, 3 );
        cvLogPolar( src, dst, cvPoint2D32f(src->width/2,src->height/2), 40, CV_INTER_LINEAR+CV_WARP_FILL_OUTLIERS );
        cvLogPolar( dst, src2, cvPoint2D32f(src->width/2,src->height/2), 40, CV_INTER_LINEAR+CV_WARP_FILL_OUTLIERS+CV_WARP_INVERSE_MAP );
        cvNamedWindow( "log-polar", 1 );
        cvShowImage( "log-polar", dst );
        cvNamedWindow( "inverse log-polar", 1 );
        cvShowImage( "inverse log-polar", src2 );
        cvWaitKey();
    }
    return 0;
}

And this is what the program displays when opencv/samples/c/fruits.jpg is passed to it

Morphological Operations

CreateStructuringElementEx

Creates structuring element

IplConvKernel* cvCreateStructuringElementEx( int cols, int rows, int anchor_x, int anchor_y,
                                             int shape, int* values=NULL );

cols

Number of columns in the structuring element.

rows

Number of rows in the structuring element.

anchor_x

Relative horizontal offset of the anchor point.

anchor_y

Relative vertical offset of the anchor point.

shape

Shape of the structuring element; may have the following values:

• CV_SHAPE_RECT, a rectangular element;
• CV_SHAPE_CROSS, a cross-shaped element;
• CV_SHAPE_ELLIPSE, an elliptic element;
• CV_SHAPE_CUSTOM, a user-defined element. In this case the parameter values specifies the mask, that is, which neighbors of the pixel must be considered.

values

Pointer to the structuring element data, a plane array, representing row-by-row scanning of the element matrix. Non-zero values indicate points that belong to the element. If the pointer is NULL, then all values are considered non-zero, that is, the element is of a rectangular shape. This parameter is considered only if the shape is CV_SHAPE_CUSTOM .

The function cv CreateStructuringElementEx allocates and fills the structure IplConvKernel, which can be used as a structuring element in the morphological operations.

ReleaseStructuringElement

Deletes structuring element

void cvReleaseStructuringElement( IplConvKernel** element );

element

Pointer to the deleted structuring element.

The function cvReleaseStructuringElement releases the structure IplConvKernel that is no longer needed. If *element is NULL, the function has no effect.

Erode

Erodes image by using arbitrary structuring element

void cvErode( const CvArr* src, CvArr* dst, IplConvKernel* element=NULL, int iterations=1 );

src

Source image.

dst

Destination image.

element

Structuring element used for erosion. If it is NULL, a 3×3 rectangular structuring element is used.

iterations

Number of times erosion is applied.

The function cvErode erodes the source image using the specified structuring element that determines the shape of a pixel neighborhood over which the minimum is taken:

dst=erode(src,element):  dst(x,y)=min((x',y') in element))src(x+x',y+y')

The function supports the in-place mode. Erosion can be applied several (iterations) times. In case of color image each channel is processed independently.

Dilate

Dilates image by using arbitrary structuring element

void cvDilate( const CvArr* src, CvArr* dst, IplConvKernel* element=NULL, int iterations=1 );

src

Source image.

dst

Destination image.

element

Structuring element used for erosion. If it is NULL, a 3×3 rectangular structuring element is used.

iterations

Number of times erosion is applied.

The function cvDilate dilates the source image using the specified structuring element that determines the shape of a pixel neighborhood over which the maximum is taken:

dst=dilate(src,element):  dst(x,y)=max((x',y') in element))src(x+x',y+y')

The function supports the in-place mode. Dilation can be applied several (iterations) times. In case of color image each channel is processed independently.

MorphologyEx

Performs advanced morphological transformations

void cvMorphologyEx( const CvArr* src, CvArr* dst, CvArr* temp,
                     IplConvKernel* element, int operation, int iterations=1 );

src

Source image.

dst

Destination image.

temp

Temporary image, required in some cases.

element

Structuring element.

operation

Type of morphological operation, one of:
CV_MOP_OPEN - opening
CV_MOP_CLOSE - closing
CV_MOP_GRADIENT - morphological gradient
CV_MOP_TOPHAT - "top hat"
CV_MOP_BLACKHAT - "black hat"

iterations

Number of times erosion and dilation are applied.

The function cvMorphologyEx can perform advanced morphological transformations using erosion and dilation as basic operations.

Opening:
dst=open(src,element)=dilate(erode(src,element),element)

Closing:
dst=close(src,element)=erode(dilate(src,element),element)

Morphological gradient:
dst=morph_grad(src,element)=dilate(src,element)-erode(src,element)

"Top hat":
dst=tophat(src,element)=src-open(src,element)

"Black hat":
dst=blackhat(src,element)=close(src,element)-src

The temporary image temp is required for morphological gradient and, in case of in-place operation, for "top hat" and "black hat".

Filters and Color Conversion

Smooth

Smooths the image in one of several ways

void cvSmooth( const CvArr* src, CvArr* dst,
               int smoothtype=CV_GAUSSIAN,
               int param1=3, int param2=0, double param3=0, double param4=0 );

src

The source image.

dst

The destination image.

smoothtype

Type of the smoothing:

• CV_BLUR_NO_SCALE (simple blur with no scaling) - summation over a pixel param1×param2 neighborhood. If the neighborhood size may vary, one may precompute integral image with cvIntegral function.
• CV_BLUR (simple blur) - summation over a pixel param1×param2 neighborhood with subsequent scaling by 1/(param1•param2).
• CV_GAUSSIAN (gaussian blur) - convolving image with param1×param2 Gaussian kernel.
• CV_MEDIAN (median blur) - finding median of param1×param1 neighborhood (i.e. the neighborhood is square).
• CV_BILATERAL (bilateral filter) - applying bilateral 3x3 filtering with color sigma=param1 and space sigma=param2. Information about bilateral filtering can be found at http://www.dai.ed.ac.uk/CVonline/LOCAL_COPIES/MANDUCHI1/Bilateral_Filtering.html

param1

The first parameter of smoothing operation.

param2

The second parameter of smoothing operation. In case of simple scaled/non-scaled and Gaussian blur if param2 is zero, it is set to param1.

param3

In case of Gaussian kernel this parameter may specify Gaussian sigma (standard deviation). If it is zero, it is calculated from the kernel size:

              sigma = (n/2 - 1)*0.3 + 0.8, where n=param1 for horizontal kernel,
                                                 n=param2 for vertical kernel.
              

With the standard sigma for small kernels (3×3 to 7×7) the performance is better. If param3 is not zero, while param1 and param2 are zeros, the kernel size is calculated from the sigma (to provide accurate enough operation).

param4

In case of non-square Gaussian kernel the parameter may be used to specify a different (from param3) sigma in the vertical direction.

The function cvSmooth smooths image using one of several methods. Every of the methods has some features and restrictions listed below

Blur with no scaling works with single-channel images only and supports accumulation of 8-bit to 16-bit format (similar to cvSobel and cvLaplace) and 32-bit floating point to 32-bit floating-point format.

Simple blur and Gaussian blur support 1- or 3-channel, 8-bit and 32-bit floating point images. These two methods can process images in-place.

Median and bilateral filters work with 1- or 3-channel 8-bit images and can not process images in-place.

Filter2D

Convolves image with the kernel

void cvFilter2D( const CvArr* src, CvArr* dst,
                 const CvMat* kernel,
                 CvPoint anchor=cvPoint(-1,-1));

src

The source image.

dst

The destination image.

kernel

Convolution kernel, single-channel floating point matrix. If you want to apply different kernels to different channels, split the image using cvSplit into separate color planes and process them individually.

anchor

The anchor of the kernel that indicates the relative position of a filtered point within the kernel. The anchor shoud lie within the kernel. The special default value (-1,-1) means that it is at the kernel center.

The function cvFilter2D applies arbitrary linear filter to the image. In-place operation is supported. When the aperture is partially outside the image, the function interpolates outlier pixel values from the nearest pixels that is inside the image.

CopyMakeBorder

Copies image and makes border around it

void cvCopyMakeBorder( const CvArr* src, CvArr* dst, CvPoint offset,
                       int bordertype, CvScalar value=cvScalarAll(0) );

src

The source image.

dst

The destination image.

offset

Coordinates of the top-left corner (or bottom-left in case of images with bottom-left origin) of the destination image rectangle where the source image (or its ROI) is copied. Size of the rectanlge matches the source image size/ROI size.

bordertype

Type of the border to create around the copied source image rectangle:
IPL_BORDER_CONSTANT - border is filled with the fixed value, passed as last parameter of the function.
IPL_BORDER_REPLICATE - the pixels from the top and bottom rows, the left-most and right-most columns are replicated to fill the border.
(The other two border types from IPL, IPL_BORDER_REFLECT and IPL_BORDER_WRAP, are currently unsupported).

value

Value of the border pixels if bordertype=IPL_BORDER_CONSTANT.

The function cvCopyMakeBorder copies the source 2D array into interior of destination array and makes a border of the specified type around the copied area. The function is useful when one needs to emulate border type that is different from the one embedded into a specific algorithm implementation. For example, morphological functions, as well as most of other filtering functions in OpenCV, internally use replication border type, while the user may need zero border or a border, filled with 1's or 255's.

Integral

Calculates integral images

void cvIntegral( const CvArr* image, CvArr* sum, CvArr* sqsum=NULL, CvArr* tilted_sum=NULL );

image

The source image, W×H, 8-bit or floating-point (32f or 64f) image.

sum

The integral image, W+1×H+1, 32-bit integer or double precision floating-point (64f).

sqsum

The integral image for squared pixel values, W+1×H+1, double precision floating-point (64f).

tilted_sum

The integral for the image rotated by 45 degrees, W+1×H+1, the same data type as sum.

The function cvIntegral calculates one or more integral images for the source image as following:

sum(X,Y)=sumx<X,y<Yimage(x,y)

sqsum(X,Y)=sumx<X,y<Yimage(x,y)2

tilted_sum(X,Y)=sumy<Y,abs(x-X)<yimage(x,y)

Using these integral images, one may calculate sum, mean, standard deviation over arbitrary up-right or rotated rectangular region of the image in a constant time, for example:

sumx1<=x<x2,y1<=y<y2image(x,y)=sum(x2,y2)-sum(x1,y2)-sum(x2,y1)+sum(x1,x1)

It makes possible to do a fast blurring or fast block correlation with variable window size etc. In case of multi-channel images sums for each channel are accumulated independently.

CvtColor

Converts image from one color space to another

void cvCvtColor( const CvArr* src, CvArr* dst, int code );

src

The source 8-bit (8u), 16-bit (16u) or single-precision floating-point (32f) image.

dst

The destination image of the same data type as the source one. The number of channels may be different.

code

Color conversion operation that can be specifed using CV_<src_color_space>2<dst_color_space> constants (see below).

The function cvCvtColor converts input image from one color space to another. The function ignores colorModel and channelSeq fields of IplImage header, so the source image color space should be specified correctly (including order of the channels in case of RGB space, e.g. BGR means 24-bit format with B₀ G₀ R₀ B₁ G₁ R₁ ... layout, whereas RGB means 24-bit format with R₀ G₀ B₀ R₁ G₁ B₁ ... layout).

The conventional range for R,G,B channel values is:

• 0..255 for 8-bit images
• 0..65535 for 16-bit images and
• 0..1 for floating-point images.

The function can do the following transformations:

• Transformations within RGB space like adding/removing alpha channel, reversing the channel order, conversion to/from 16-bit RGB color (R5:G6:B5 or R5:G5:B5) color, as well as conversion to/from grayscale using:

  RGB[A]->Gray: Y<-0.299*R + 0.587*G + 0.114*B
  Gray->RGB[A]: R<-Y G<-Y B<-Y A<-0
  

• RGB<=>CIE XYZ.Rec 709 with D65 white point (CV_BGR2XYZ, CV_RGB2XYZ, CV_XYZ2BGR, CV_XYZ2RGB):

  |X|    |0.412453  0.357580  0.180423| |R|
  |Y| <- |0.212671  0.715160  0.072169|*|G|
  |Z|    |0.019334  0.119193  0.950227| |B|
  
  |R|    | 3.240479  -1.53715  -0.498535| |X|
  |G| <- |-0.969256   1.875991  0.041556|*|Y|
  |B|    | 0.055648  -0.204043  1.057311| |Z|
  
  X, Y and Z cover the whole value range (in case of floating-point images Z may exceed 1).
  

• RGB<=>YCrCb JPEG (a.k.a. YCC) (CV_BGR2YCrCb, CV_RGB2YCrCb, CV_YCrCb2BGR, CV_YCrCb2RGB)

  Y <- 0.299*R + 0.587*G + 0.114*B
  Cr <- (R-Y)*0.713 + delta
  Cb <- (B-Y)*0.564 + delta
  
  R <- Y + 1.403*(Cr - delta)
  G <- Y - 0.344*(Cr - delta) - 0.714*(Cb - delta)
  B <- Y + 1.773*(Cb - delta),
  
                { 128 for 8-bit images,
  where delta = { 32768 for 16-bit images
                { 0.5 for floating-point images
  
  Y, Cr and Cb cover the whole value range.
  

• RGB<=>HSV (CV_BGR2HSV, CV_RGB2HSV, CV_HSV2BGR, CV_HSV2RGB)

  // In case of 8-bit and 16-bit images
  // R, G and B are converted to floating-point format and scaled to fit 0..1 range
  
  V <- max(R,G,B)
  S <- (V-min(R,G,B))/V   if V≠0, 0 otherwise
  
           (G - B)*60/S,  if V=R
  H <- 180+(B - R)*60/S,  if V=G
       240+(R - G)*60/S,  if V=B
  
  if H<0 then H<-H+360
  
  On output 0≤V≤1, 0≤S≤1, 0≤H≤360.
  The values are then converted to the destination data type:
      8-bit images:
          V <- V*255, S <- S*255, H <- H/2 (to fit to 0..255)
      16-bit images (currently not supported):
          V <- V*65535, S <- S*65535, H <- H
      32-bit images:
          H, S, V are left as is
  

• RGB<=>HLS (CV_BGR2HLS, CV_RGB2HLS, CV_HLS2BGR, CV_HLS2RGB)

  // In case of 8-bit and 16-bit images
  // R, G and B are converted to floating-point format and scaled to fit 0..1 range
  
  Vmax <- max(R,G,B)
  Vmin <- min(R,G,B)
  
  L <- (Vmax + Vmin)/2
  
  S <- (Vmax - Vmin)/(Vmax + Vmin)  if L < 0.5
       (Vmax - Vmin)/(2 - (Vmax + Vmin))  if L ≥ 0.5
  
           (G - B)*60/S,  if Vmax=R
  H <- 180+(B - R)*60/S,  if Vmax=G
       240+(R - G)*60/S,  if Vmax=B
  
  if H<0 then H<-H+360
  
  On output 0≤L≤1, 0≤S≤1, 0≤H≤360.
  The values are then converted to the destination data type:
      8-bit images:
          L <- L*255, S <- S*255, H <- H/2
      16-bit images (currently not supported):
          L <- L*65535, S <- S*65535, H <- H
      32-bit images:
          H, L, S are left as is
  

• RGB<=>CIE L*a*b* (CV_BGR2Lab, CV_RGB2Lab, CV_Lab2BGR, CV_Lab2RGB)

  // In case of 8-bit and 16-bit images
  // R, G and B are converted to floating-point format and scaled to fit 0..1 range
  
  // convert R,G,B to CIE XYZ
  |X|    |0.412453  0.357580  0.180423| |R|
  |Y| <- |0.212671  0.715160  0.072169|*|G|
  |Z|    |0.019334  0.119193  0.950227| |B|
  
  X <- X/Xn, where Xn = 0.950456
  Z <- Z/Zn, where Zn = 1.088754
  
  L <- 116*Y1/3      for Y>0.008856
  L <- 903.3*Y      for Y<=0.008856
  
  a <- 500*(f(X)-f(Y)) + delta
  b <- 200*(f(Y)-f(Z)) + delta
  where f(t)=t1/3              for t>0.008856
        f(t)=7.787*t+16/116   for t<=0.008856
  
  
  where delta = 128 for 8-bit images,
                0 for floating-point images
  
  On output 0≤L≤100, -127≤a≤127, -127≤b≤127
  The values are then converted to the destination data type:
      8-bit images:
          L <- L*255/100, a <- a + 128, b <- b + 128
      16-bit images are currently not supported
      32-bit images:
          L, a, b are left as is
  

• RGB<=>CIE L*u*v* (CV_BGR2Luv, CV_RGB2Luv, CV_Luv2BGR, CV_Luv2RGB)

  // In case of 8-bit and 16-bit images
  // R, G and B are converted to floating-point format and scaled to fit 0..1 range
  
  // convert R,G,B to CIE XYZ
  |X|    |0.412453  0.357580  0.180423| |R|
  |Y| <- |0.212671  0.715160  0.072169|*|G|
  |Z|    |0.019334  0.119193  0.950227| |B|
  
  L <- 116*Y1/3-16   for Y>0.008856
  L <- 903.3*Y      for Y<=0.008856
  
  u' <- 4*X/(X + 15*Y + 3*Z)
  v' <- 9*Y/(X + 15*Y + 3*Z)
  
  u <- 13*L*(u' - un), where un=0.19793943
  v <- 13*L*(v' - vn), where vn=0.46831096
  
  On output 0≤L≤100, -134≤u≤220, -140≤v≤122
  The values are then converted to the destination data type:
      8-bit images:
          L <- L*255/100, u <- (u + 134)*255/354, v <- (v + 140)*255/256
      16-bit images are currently not supported
      32-bit images:
          L, u, v are left as is
  

  The above formulae for converting RGB to/from various color spaces have been taken from multiple sources on Web, primarily from Color Space Conversions ([Ford98]) document at Charles Poynton site.

• Bayer=>RGB (CV_BayerBG2BGR, CV_BayerGB2BGR, CV_BayerRG2BGR, CV_BayerGR2BGR,
CV_BayerBG2RGB, CV_BayerGB2RGB, CV_BayerRG2RGB, CV_BayerGR2RGB)

  Bayer pattern is widely used in CCD and CMOS cameras. It allows to get color picture out of a single plane where R,G and B pixels (sensors of a particular component) are interleaved like this:

  R	G	R	G	R
  G	B	G	B	G
  R	G	R	G	R
  G	B	G	B	G
  R	G	R	G	R
  G	B	G	B	G

  The output RGB components of a pixel are interpolated from 1, 2 or 4 neighbors of the pixel having the same color. There are several modifications of the above pattern that can be achieved by shifting the pattern one pixel left and/or one pixel up. The two letters C₁ and C₂ in the conversion constants CV_BayerC₁C₂2{BGR|RGB} indicate the particular pattern type - these are components from the second row, second and third columns, respectively. For example, the above pattern has very popular "BG" type.

Threshold

Applies fixed-level threshold to array elements

void cvThreshold( const CvArr* src, CvArr* dst, double threshold,
                  double max_value, int threshold_type );

src

Source array (single-channel, 8-bit of 32-bit floating point).

dst

Destination array; must be either the same type as src or 8-bit.

threshold

Threshold value.

max_value

Maximum value to use with CV_THRESH_BINARY and CV_THRESH_BINARY_INV thresholding types.

threshold_type

Thresholding type (see the discussion)

The function cvThreshold applies fixed-level thresholding to single-channel array. The function is typically used to get bi-level (binary) image out of grayscale image (cvCmpS could be also used for this purpose) or for removing a noise, i.e. filtering out pixels with too small or too large values. There are several types of thresholding the function supports that are determined by threshold_type:

threshold_type=CV_THRESH_BINARY:
dst(x,y) = max_value, if src(x,y)>threshold
           0, otherwise

threshold_type=CV_THRESH_BINARY_INV:
dst(x,y) = 0, if src(x,y)>threshold
           max_value, otherwise

threshold_type=CV_THRESH_TRUNC:
dst(x,y) = threshold, if src(x,y)>threshold
           src(x,y), otherwise

threshold_type=CV_THRESH_TOZERO:
dst(x,y) = src(x,y), if src(x,y)>threshold
           0, otherwise

threshold_type=CV_THRESH_TOZERO_INV:
dst(x,y) = 0, if src(x,y)>threshold
           src(x,y), otherwise

And this is the visual description of thresholding types:

AdaptiveThreshold

Applies adaptive threshold to array

void cvAdaptiveThreshold( const CvArr* src, CvArr* dst, double max_value,
                          int adaptive_method=CV_ADAPTIVE_THRESH_MEAN_C,
                          int threshold_type=CV_THRESH_BINARY,
                          int block_size=3, double param1=5 );

src

Source image.

dst

Destination image.

max_value

Maximum value that is used with CV_THRESH_BINARY and CV_THRESH_BINARY_INV.

adaptive_method

Adaptive thresholding algorithm to use: CV_ADAPTIVE_THRESH_MEAN_C or CV_ADAPTIVE_THRESH_GAUSSIAN_C (see the discussion).

threshold_type

Thresholding type; must be one of

• CV_THRESH_BINARY,
• CV_THRESH_BINARY_INV

block_size

The size of a pixel neighborhood that is used to calculate a threshold value for the pixel: 3, 5, 7, ...

param1

The method-dependent parameter. For the methods CV_ADAPTIVE_THRESH_MEAN_C and CV_ADAPTIVE_THRESH_GAUSSIAN_C it is a constant subtracted from mean or weighted mean (see the discussion), though it may be negative.

The function cvAdaptiveThreshold transforms grayscale image to binary image according to the formulae:

threshold_type=CV_THRESH_BINARY:
dst(x,y) = max_value, if src(x,y)>T(x,y)
           0, otherwise

threshold_type=CV_THRESH_BINARY_INV:
dst(x,y) = 0, if src(x,y)>T(x,y)
           max_value, otherwise

where T_I is a threshold calculated individually for each pixel.

For the method CV_ADAPTIVE_THRESH_MEAN_C it is a mean of block_size × block_size pixel neighborhood, subtracted by param1.

For the method CV_ADAPTIVE_THRESH_GAUSSIAN_C it is a weighted sum (gaussian) of block_size × block_size pixel neighborhood, subtracted by param1.

Pyramids and the Applications

PyrDown

Downsamples image

void cvPyrDown( const CvArr* src, CvArr* dst, int filter=CV_GAUSSIAN_5x5 );

src

The source image.

dst

The destination image, should have 2x smaller width and height than the source.

filter

Type of the filter used for convolution; only CV_GAUSSIAN_5x5 is currently supported.

The function cvPyrDown performs downsampling step of Gaussian pyramid decomposition. First it convolves source image with the specified filter and then downsamples the image by rejecting even rows and columns.

PyrUp

Upsamples image

void cvPyrUp( const CvArr* src, CvArr* dst, int filter=CV_GAUSSIAN_5x5 );

src

The source image.

dst

The destination image, should have 2x smaller width and height than the source.

filter

Type of the filter used for convolution; only CV_GAUSSIAN_5x5 is currently supported.

The function cvPyrUp performs up-sampling step of Gaussian pyramid decomposition. First it upsamples the source image by injecting even zero rows and columns and then convolves result with the specified filter multiplied by 4 for interpolation. So the destination image is four times larger than the source image.

Image Segmentation, Connected Components and Contour Retrieval

CvConnectedComp

Connected component

    typedef struct CvConnectedComp
    {
        double area; /* area of the segmented component */
        float value; /* gray scale value of the segmented component */
        CvRect rect; /* ROI of the segmented component */
    } CvConnectedComp;

FloodFill

Fills a connected component with given color

void cvFloodFill( CvArr* image, CvPoint seed_point, CvScalar new_val,
                  CvScalar lo_diff=cvScalarAll(0), CvScalar up_diff=cvScalarAll(0),
                  CvConnectedComp* comp=NULL, int flags=4, CvArr* mask=NULL );
#define CV_FLOODFILL_FIXED_RANGE (1 << 16)
#define CV_FLOODFILL_MASK_ONLY   (1 << 17)

image

Input 1- or 3-channel, 8-bit or floating-point image. It is modified by the function unless CV_FLOODFILL_MASK_ONLY flag is set (see below).

seed_point

The starting point.

new_val

New value of repainted domain pixels.

lo_diff

Maximal lower brightness/color difference between the currently observed pixel and one of its neighbor belong to the component or seed pixel to add the pixel to component. In case of 8-bit color images it is packed value.

up_diff

Maximal upper brightness/color difference between the currently observed pixel and one of its neighbor belong to the component or seed pixel to add the pixel to component. In case of 8-bit color images it is packed value.

comp

Pointer to structure the function fills with the information about the repainted domain.

flags

The operation flags. Lower bits contain connectivity value, 4 (by default) or 8, used within the function. Connectivity determines which neighbors of a pixel are considered. Upper bits can be 0 or combination of the following flags:

• CV_FLOODFILL_FIXED_RANGE - if set the difference between the current pixel and seed pixel is considered, otherwise difference between neighbor pixels is considered (the range is floating).
• CV_FLOODFILL_MASK_ONLY - if set, the function does not fill the image (new_val is ignored), but the fills mask (that must be non-NULL in this case).

mask

Operation mask, should be singe-channel 8-bit image, 2 pixels wider and 2 pixels taller than image. If not NULL, the function uses and updates the mask, so user takes responsibility of initializing mask content. Floodfilling can't go across non-zero pixels in the mask, for example, an edge detector output can be used as a mask to stop filling at edges. Or it is possible to use the same mask in multiple calls to the function to make sure the filled area do not overlap. Note: because mask is larger than the filled image, pixel in mask that corresponds to (x,y) pixel in image will have coordinates (x+1,y+1).

The function cvFloodFill fills a connected component starting from the seed point with the specified color. The connectivity is determined by the closeness of pixel values. The pixel at (x, y) is considered to belong to the repainted domain if:

src(x',y')-lo_diff<=src(x,y)<=src(x',y')+up_diff,     grayscale image, floating range
src(seed.x,seed.y)-lo<=src(x,y)<=src(seed.x,seed.y)+up_diff, grayscale image, fixed range

src(x',y')r-lo_diffr<=src(x,y)r<=src(x',y')r+up_diffr and
src(x',y')g-lo_diffg<=src(x,y)g<=src(x',y')g+up_diffg and
src(x',y')b-lo_diffb<=src(x,y)b<=src(x',y')b+up_diffb, color image, floating range

src(seed.x,seed.y)r-lo_diffr<=src(x,y)r<=src(seed.x,seed.y)r+up_diffr and
src(seed.x,seed.y)g-lo_diffg<=src(x,y)g<=src(seed.x,seed.y)g+up_diffg and
src(seed.x,seed.y)b-lo_diffb<=src(x,y)b<=src(seed.x,seed.y)b+up_diffb, color image, fixed range

• color/brightness of one of its neighbors that are already referred to the connected component in case of floating range
• color/brightness of the seed point in case of fixed range.

FindContours

Finds contours in binary image

int cvFindContours( CvArr* image, CvMemStorage* storage, CvSeq** first_contour,
                    int header_size=sizeof(CvContour), int mode=CV_RETR_LIST,
                    int method=CV_CHAIN_APPROX_SIMPLE, CvPoint offset=cvPoint(0,0) );

image

The source 8-bit single channel image. Non-zero pixels are treated as 1’s, zero pixels remain 0’s - that is image treated as binary. To get such a binary image from grayscale, one may use cvThreshold, cvAdaptiveThreshold or cvCanny. The function modifies the source image content.

storage

Container of the retrieved contours.

first_contour

Output parameter, will contain the pointer to the first outer contour.

header_size

Size of the sequence header, >=sizeof(CvChain) if method=CV_CHAIN_CODE, and >=sizeof(CvContour) otherwise.

mode

Retrieval mode.

• CV_RETR_EXTERNAL - retrive only the extreme outer contours
• CV_RETR_LIST - retrieve all the contours and puts them in the list
• CV_RETR_CCOMP - retrieve all the contours and organizes them into two-level hierarchy: top level are external boundaries of the components, second level are bounda boundaries of the holes
• CV_RETR_TREE - retrieve all the contours and reconstructs the full hierarchy of nested contours

method

Approximation method (for all the modes, except CV_RETR_RUNS, which uses built-in approximation).

• CV_CHAIN_CODE - output contours in the Freeman chain code. All other methods output polygons (sequences of vertices).
• CV_CHAIN_APPROX_NONE - translate all the points from the chain code into points;
• CV_CHAIN_APPROX_SIMPLE - compress horizontal, vertical, and diagonal segments, that is, the function leaves only their ending points;
• CV_CHAIN_APPROX_TC89_L1,
  CV_CHAIN_APPROX_TC89_KCOS - apply one of the flavors of Teh-Chin chain approximation algorithm.
• CV_LINK_RUNS - use completely different contour retrieval algorithm via linking of horizontal segments of 1’s. Only CV_RETR_LIST retrieval mode can be used with this method.

offset

Offset, by which every contour point is shifted. This is useful if the contours are extracted from the image ROI and then they should be analyzed in the whole image context.

The function cvFindContours retrieves contours from the binary image and returns the number of retrieved contours. The pointer first_contour is filled by the function. It will contain pointer to the first most outer contour or NULL if no contours is detected (if the image is completely black). Other contours may be reached from first_contour using h_next and v_next links. The sample in cvDrawContours discussion shows how to use contours for connected component detection. Contours can be also used for shape analysis and object recognition - see squares.c in OpenCV sample directory.

StartFindContours

Initializes contour scanning process

CvContourScanner cvStartFindContours( CvArr* image, CvMemStorage* storage,
                                      int header_size=sizeof(CvContour),
                                      int mode=CV_RETR_LIST,
                                      int method=CV_CHAIN_APPROX_SIMPLE,
                                      CvPoint offset=cvPoint(0,0) );

image

The source 8-bit single channel binary image.

storage

Container of the retrieved contours.

header_size

Size of the sequence header, >=sizeof(CvChain) if method=CV_CHAIN_CODE, and >=sizeof(CvContour) otherwise.

mode

Retrieval mode; see cvFindContours.

method

Approximation method. It has the same meaning as in cvFindContours, but CV_LINK_RUNS can not be used here.

offset

ROI offset; see cvFindContours.

The function cvStartFindContours initializes and returns pointer to the contour scanner. The scanner is used further in cvFindNextContour to retrieve the rest of contours.

FindNextContour

Finds next contour in the image

CvSeq* cvFindNextContour( CvContourScanner scanner );

scanner

Contour scanner initialized by The function cvStartFindContours .

The function cvFindNextContour locates and retrieves the next contour in the image and returns pointer to it. The function returns NULL, if there is no more contours.

SubstituteContour

Replaces retrieved contour

void cvSubstituteContour( CvContourScanner scanner, CvSeq* new_contour );

scanner

Contour scanner initialized by the function cvStartFindContours .

new_contour

Substituting contour.

The function cvSubstituteContour replaces the retrieved contour, that was returned from the preceding call of The function cvFindNextContour and stored inside the contour scanner state, with the user-specified contour. The contour is inserted into the resulting structure, list, two-level hierarchy, or tree, depending on the retrieval mode. If the parameter new_contour=NULL, the retrieved contour is not included into the resulting structure, nor all of its children that might be added to this structure later.

EndFindContours

Finishes scanning process

CvSeq* cvEndFindContours( CvContourScanner* scanner );

scanner

Pointer to the contour scanner.

The function cvEndFindContours finishes the scanning process and returns the pointer to the first contour on the highest level.

PyrSegmentation

Does image segmentation by pyramids

void cvPyrSegmentation( IplImage* src, IplImage* dst,
                        CvMemStorage* storage, CvSeq** comp,
                        int level, double threshold1, double threshold2 );

src

The source image.

dst

The destination image.

storage

Storage; stores the resulting sequence of connected components.

comp

Pointer to the output sequence of the segmented components.

level

Maximum level of the pyramid for the segmentation.

threshold1

Error threshold for establishing the links.

threshold2

Error threshold for the segments clustering.

The function cvPyrSegmentation implements image segmentation by pyramids. The pyramid builds up to the level level. The links between any pixel a on level i and its candidate father pixel b on the adjacent level are established if

void cvPyrMeanShiftFiltering( const CvArr* src, CvArr* dst,
     double sp, double sr, int max_level=1,
     CvTermCriteria termcrit=cvTermCriteria(CV_TERMCRIT_ITER+CV_TERMCRIT_EPS,5,1));

{(x,y): X-sp≤x≤X+sp && Y-sp≤y≤Y+sp && ||(R,G,B)-(r,g,b)|| ≤ sr},

(X,Y)~(X',Y'), (R,G,B)~(R',G',B').

I(X,Y) <- (R*,G*,B*).

void cvWatershed( const CvArr* image, CvArr* markers );

void cvMoments( const CvArr* arr, CvMoments* moments, int binary=0 );

double cvGetSpatialMoment( CvMoments* moments, int x_order, int y_order );

Mx_order,y_order=sumx,y(I(x,y)•xx_order•yy_order)

double cvGetCentralMoment( CvMoments* moments, int x_order, int y_order );

μx_order,y_order=sumx,y(I(x,y)•(x-xc)x_order•(y-yc)y_order),

double cvGetNormalizedCentralMoment( CvMoments* moments, int x_order, int y_order );

ηx_order,y_order= μx_order,y_order/M00((y_order+x_order)/2+1)

void cvGetHuMoments( CvMoments* moments, CvHuMoments* hu_moments );

 h1=η20+η02

 h2=(η20-η02)²+4η11²

 h3=(η30-3η12)²+ (3η21-η03)²

 h4=(η30+η12)²+ (η21+η03)²

 h5=(η30-3η12)(η30+η12)[(η30+η12)²-3(η21+η03)²]+(3η21-η03)(η21+η03)[3(η30+η12)²-(η21+η03)²]

 h6=(η20-η02)[(η30+η12)²- (η21+η03)²]+4η11(η30+η12)(η21+η03)

 h7=(3η21-η03)(η21+η03)[3(η30+η12)²-(η21+η03)²]-(η30-3η12)(η21+η03)[3(η30+η12)²-(η21+η03)²]

CvSeq* cvHoughLines2( CvArr* image, void* line_storage, int method,
                      double rho, double theta, int threshold,
                      double param1=0, double param2=0 );

/* This is a standalone program. Pass an image name as a first parameter of the program.
   Switch between standard and probabilistic Hough transform by changing "#if 1" to "#if 0" and back */
#include <cv.h>
#include <highgui.h>
#include <math.h>

int main(int argc, char** argv)
{
    IplImage* src;
    if( argc == 2 && (src=cvLoadImage(argv[1], 0))!= 0)
    {
        IplImage* dst = cvCreateImage( cvGetSize(src), 8, 1 );
        IplImage* color_dst = cvCreateImage( cvGetSize(src), 8, 3 );
        CvMemStorage* storage = cvCreateMemStorage(0);
        CvSeq* lines = 0;
        int i;
        cvCanny( src, dst, 50, 200, 3 );
        cvCvtColor( dst, color_dst, CV_GRAY2BGR );
#if 1
        lines = cvHoughLines2( dst, storage, CV_HOUGH_STANDARD, 1, CV_PI/180, 100, 0, 0 );

        for( i = 0; i < MIN(lines->total,100); i++ )
        {
            float* line = (float*)cvGetSeqElem(lines,i);
            float rho = line[0];
            float theta = line[1];
            CvPoint pt1, pt2;
            double a = cos(theta), b = sin(theta);
            double x0 = a*rho, y0 = b*rho;
            pt1.x = cvRound(x0 + 1000*(-b));
            pt1.y = cvRound(y0 + 1000*(a));
            pt2.x = cvRound(x0 - 1000*(-b));
            pt2.y = cvRound(y0 - 1000*(a));
            cvLine( color_dst, pt1, pt2, CV_RGB(255,0,0), 3, 8 );
        }
#else
        lines = cvHoughLines2( dst, storage, CV_HOUGH_PROBABILISTIC, 1, CV_PI/180, 50, 50, 10 );
        for( i = 0; i < lines->total; i++ )
        {
            CvPoint* line = (CvPoint*)cvGetSeqElem(lines,i);
            cvLine( color_dst, line[0], line[1], CV_RGB(255,0,0), 3, 8 );
        }
#endif
        cvNamedWindow( "Source", 1 );
        cvShowImage( "Source", src );

        cvNamedWindow( "Hough", 1 );
        cvShowImage( "Hough", color_dst );

        cvWaitKey(0);
    }
}

CvSeq* cvHoughCircles( CvArr* image, void* circle_storage,
                       int method, double dp, double min_dist,
                       double param1=100, double param2=100,
                       int min_radius=0, int max_radius=0 );

#include <cv.h>
#include <highgui.h>
#include <math.h>

int main(int argc, char** argv)
{
    IplImage* img;
    if( argc == 2 && (img=cvLoadImage(argv[1], 1))!= 0)
    {
        IplImage* gray = cvCreateImage( cvGetSize(img), 8, 1 );
        CvMemStorage* storage = cvCreateMemStorage(0);
        cvCvtColor( img, gray, CV_BGR2GRAY );
        cvSmooth( gray, gray, CV_GAUSSIAN, 9, 9 ); // smooth it, otherwise a lot of false circles may be detected
        CvSeq* circles = cvHoughCircles( gray, storage, CV_HOUGH_GRADIENT, 2, gray->height/4, 200, 100 );
        int i;
        for( i = 0; i < circles->total; i++ )
        {
             float* p = (float*)cvGetSeqElem( circles, i );
             cvCircle( img, cvPoint(cvRound(p[0]),cvRound(p[1])), 3, CV_RGB(0,255,0), -1, 8, 0 );
             cvCircle( img, cvPoint(cvRound(p[0]),cvRound(p[1])), cvRound(p[2]), CV_RGB(255,0,0), 3, 8, 0 );
        }
        cvNamedWindow( "circles", 1 );
        cvShowImage( "circles", img );
    }
    return 0;
}

void cvDistTransform( const CvArr* src, CvArr* dst, int distance_type=CV_DIST_L2,
                      int mask_size=3, const float* mask=NULL, CvArr* labels=NULL );

CV_DIST_C (3×3):
a=1, b=1

CV_DIST_L1 (3×3):
a=1, b=2

CV_DIST_L2 (3×3):
a=0.955, b=1.3693

CV_DIST_L2 (5×5):
a=1, b=1.4, c=2.1969

void cvInpaint( const CvArr* src, const CvArr* mask, CvArr* dst,
                int flags, double inpaintRadius );

typedef struct CvHistogram
{
    int     type;
    CvArr*  bins;
    float   thresh[CV_MAX_DIM][2]; /* for uniform histograms */
    float** thresh2; /* for non-uniform histograms */
    CvMatND mat; /* embedded matrix header for array histograms */
}
CvHistogram;

CvHistogram* cvCreateHist( int dims, int* sizes, int type,
                           float** ranges=NULL, int uniform=1 );

void cvSetHistBinRanges( CvHistogram* hist, float** ranges, int uniform=1 );

void cvReleaseHist( CvHistogram** hist );

void cvClearHist( CvHistogram* hist );

CvHistogram*  cvMakeHistHeaderForArray( int dims, int* sizes, CvHistogram* hist,
                                        float* data, float** ranges=NULL, int uniform=1 );

#define cvQueryHistValue_1D( hist, idx0 ) \
    cvGetReal1D( (hist)->bins, (idx0) )
#define cvQueryHistValue_2D( hist, idx0, idx1 ) \
    cvGetReal2D( (hist)->bins, (idx0), (idx1) )
#define cvQueryHistValue_3D( hist, idx0, idx1, idx2 ) \
    cvGetReal3D( (hist)->bins, (idx0), (idx1), (idx2) )
#define cvQueryHistValue_nD( hist, idx ) \
    cvGetRealND( (hist)->bins, (idx) )

#define cvGetHistValue_1D( hist, idx0 ) \
    ((float*)(cvPtr1D( (hist)->bins, (idx0), 0 ))
#define cvGetHistValue_2D( hist, idx0, idx1 ) \
    ((float*)(cvPtr2D( (hist)->bins, (idx0), (idx1), 0 ))
#define cvGetHistValue_3D( hist, idx0, idx1, idx2 ) \
    ((float*)(cvPtr3D( (hist)->bins, (idx0), (idx1), (idx2), 0 ))
#define cvGetHistValue_nD( hist, idx ) \
    ((float*)(cvPtrND( (hist)->bins, (idx), 0 ))

void cvGetMinMaxHistValue( const CvHistogram* hist,
                           float* min_value, float* max_value,
                           int* min_idx=NULL, int* max_idx=NULL );

void cvNormalizeHist( CvHistogram* hist, double factor );

void cvThreshHist( CvHistogram* hist, double threshold );

double cvCompareHist( const CvHistogram* hist1, const CvHistogram* hist2, int method );

Correlation (method=CV_COMP_CORREL):
d(H1,H2)=sumI(H'1(I)•H'2(I))/sqrt(sumI[H'1(I)2]•sumI[H'2(I)2])
where
H'k(I)=Hk(I)-1/N•sumJHk(J) (N=number of histogram bins)

Chi-Square (method=CV_COMP_CHISQR):
d(H1,H2)=sumI[(H1(I)-H2(I))/(H1(I)+H2(I))]

Intersection (method=CV_COMP_INTERSECT):
d(H1,H2)=sumImin(H1(I),H2(I))

Bhattacharyya distance (method=CV_COMP_BHATTACHARYYA):
d(H1,H2)=sqrt(1-sumI(sqrt(H1(I)•H2(I))))

void cvCopyHist( const CvHistogram* src, CvHistogram** dst );

void cvCalcHist( IplImage** image, CvHistogram* hist,
                 int accumulate=0, const CvArr* mask=NULL );

#include <cv.h>
#include <highgui.h>

int main( int argc, char** argv )
{
    IplImage* src;
    if( argc == 2 && (src=cvLoadImage(argv[1], 1))!= 0)
    {
        IplImage* h_plane = cvCreateImage( cvGetSize(src), 8, 1 );
        IplImage* s_plane = cvCreateImage( cvGetSize(src), 8, 1 );
        IplImage* v_plane = cvCreateImage( cvGetSize(src), 8, 1 );
        IplImage* planes[] = { h_plane, s_plane };
        IplImage* hsv = cvCreateImage( cvGetSize(src), 8, 3 );
        int h_bins = 30, s_bins = 32;
        int hist_size[] = {h_bins, s_bins};
        float h_ranges[] = { 0, 180 }; /* hue varies from 0 (~0°red) to 180 (~360°red again) */
        float s_ranges[] = { 0, 255 }; /* saturation varies from 0 (black-gray-white) to 255 (pure spectrum color) */
        float* ranges[] = { h_ranges, s_ranges };
        int scale = 10;
        IplImage* hist_img = cvCreateImage( cvSize(h_bins*scale,s_bins*scale), 8, 3 );
        CvHistogram* hist;
        float max_value = 0;
        int h, s;

        cvCvtColor( src, hsv, CV_BGR2HSV );
        cvCvtPixToPlane( hsv, h_plane, s_plane, v_plane, 0 );
        hist = cvCreateHist( 2, hist_size, CV_HIST_ARRAY, ranges, 1 );
        cvCalcHist( planes, hist, 0, 0 );
        cvGetMinMaxHistValue( hist, 0, &max_value, 0, 0 );
        cvZero( hist_img );

        for( h = 0; h < h_bins; h++ )
        {
            for( s = 0; s < s_bins; s++ )
            {
                float bin_val = cvQueryHistValue_2D( hist, h, s );
                int intensity = cvRound(bin_val*255/max_value);
                cvRectangle( hist_img, cvPoint( h*scale, s*scale ),
                             cvPoint( (h+1)*scale - 1, (s+1)*scale - 1),
                             CV_RGB(intensity,intensity,intensity), /* graw a grayscale histogram.
                                                                       if you have idea how to do it
                                                                       nicer let us know */
                             CV_FILLED );
            }
        }

        cvNamedWindow( "Source", 1 );
        cvShowImage( "Source", src );

        cvNamedWindow( "H-S Histogram", 1 );
        cvShowImage( "H-S Histogram", hist_img );

        cvWaitKey(0);
    }
}

void cvCalcBackProject( IplImage** image, CvArr* back_project, const CvHistogram* hist );

void cvCalcBackProjectPatch( IplImage** images, CvArr* dst,
                             CvSize patch_size, CvHistogram* hist,
                             int method, float factor );

for (x,y) in images (until (x+patch_size.width-1,y+patch_size.height-1) is inside the images) do
    compute histogram over the ROI (x,y,x+patch_size.width,y+patch_size.height) in images
       (see cvCalcHist)
    normalize the histogram using the factor
       (see cvNormalizeHist)
    compare the normalized histogram with input histogram hist using the specified method
       (see cvCompareHist)
    store the result to dst(x,y)
end for

void  cvCalcProbDensity( const CvHistogram* hist1, const CvHistogram* hist2,
                         CvHistogram* dst_hist, double scale=255 );

dist_hist(I)=0      if hist1(I)==0
             scale  if hist1(I)!=0 && hist2(I)>hist1(I)
             hist2(I)*scale/hist1(I) if hist1(I)!=0 && hist2(I)<=hist1(I)

void  cvEqualizeHist( const CvArr* src, CvArr* dst );

1. calculate histogram H for src.
2. normalize histogram, so that the sum of histogram bins is 255.
3. compute integral of the histogram:
   H’(i) = sum0≤j≤iH(j)
4. transform the image using H’ as a look-up table: dst(x,y)=H’(src(x,y))

void cvMatchTemplate( const CvArr* image, const CvArr* templ,
                      CvArr* result, int method );

method=CV_TM_SQDIFF:
R(x,y)=sumx',y'[T(x',y')-I(x+x',y+y')]2

method=CV_TM_SQDIFF_NORMED:
R(x,y)=sumx',y'[T(x',y')-I(x+x',y+y')]2/sqrt[sumx',y'T(x',y')2•sumx',y'I(x+x',y+y')2]

method=CV_TM_CCORR:
R(x,y)=sumx',y'[T(x',y')•I(x+x',y+y')]

method=CV_TM_CCORR_NORMED:
R(x,y)=sumx',y'[T(x',y')•I(x+x',y+y')]/sqrt[sumx',y'T(x',y')2•sumx',y'I(x+x',y+y')2]

method=CV_TM_CCOEFF:
R(x,y)=sumx',y'[T'(x',y')•I'(x+x',y+y')],

where T'(x',y')=T(x',y') - 1/(w•h)•sumx",y"T(x",y")
      I'(x+x',y+y')=I(x+x',y+y') - 1/(w•h)•sumx",y"I(x+x",y+y")

method=CV_TM_CCOEFF_NORMED:
R(x,y)=sumx',y'[T'(x',y')•I'(x+x',y+y')]/sqrt[sumx',y'T'(x',y')2•sumx',y'I'(x+x',y+y')2]

double cvMatchShapes( const void* object1, const void* object2,
                      int method, double parameter=0 );

method=CV_CONTOUR_MATCH_I1:
I1(A,B)=sumi=1..7abs(1/mAi - 1/mBi)

method=CV_CONTOUR_MATCH_I2:
I2(A,B)=sumi=1..7abs(mAi - mBi)

method=CV_CONTOUR_MATCH_I3:
I3(A,B)=sumi=1..7abs(mAi - mBi)/abs(mAi)

where
mAi=sign(hAi)•log(hAi),
mBi=sign(hBi)•log(hBi),
hAi, hBi - Hu moments of A and B, respectively.

float cvCalcEMD2( const CvArr* signature1, const CvArr* signature2, int distance_type,
                  CvDistanceFunction distance_func=NULL, const CvArr* cost_matrix=NULL,
                  CvArr* flow=NULL, float* lower_bound=NULL, void* userdata=NULL );
typedef float (*CvDistanceFunction)(const float* f1, const float* f2, void* userdata);

CvSeq* cvApproxChains( CvSeq* src_seq, CvMemStorage* storage,
                       int method=CV_CHAIN_APPROX_SIMPLE,
                       double parameter=0, int minimal_perimeter=0, int recursive=0 );