vcs.maemo.org Git - opencv/blob - docs/ref/opencvref_cv.htm

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0//EN">
   2 <html><head>
   3 <link rel="STYLESHEET" href="opencvref.css" charset="ISO-8859-1" type="text/css">
   4 <title>OpenCV: Image Processing and Computer Vision Reference Manual</title>
   5 </head><body>
   6
   7 <h1>CV Reference Manual</h1>
   8
   9 <hr><p><ul>
  10 <li><a href="#cv_imgproc">Image Processing</a>
  11 <ul>
  12 <li><a href="#cv_imgproc_features">Gradients, Edges and Corners</a>
  13 <li><a href="#cv_imgproc_resampling">Sampling, Interpolation and Geometrical Transforms</a>
  14 <li><a href="#cv_imgproc_morphology">Morphological Operations</a>
  15 <li><a href="#cv_imgproc_filters">Filters and Color Conversion</a>
  16 <li><a href="#cv_imgproc_pyramids">Pyramids and the Applications</a>
  17 <li><a href="#cv_imgproc_ccomp">Image Segmentation, Connected Components and Contour Retrieval</a>
  18 <li><a href="#cv_imgproc_moments">Image and Contour Moments</a>
  19 <li><a href="#cv_imgproc_special">Special Image Transforms</a>
  20 <li><a href="#cv_imgproc_histograms">Histograms</a>
  21 <li><a href="#cv_imgproc_matching">Matching</a>
  22 </ul>
  23 <li><a href="#cv_sa">Structural Analysis</a>
  24 <ul>
  25 <li><a href="#cv_sa_contours">Contour Processing</a>
  26 <li><a href="#cv_sa_compgeom">Computational Geometry</a>
  27 <li><a href="#cv_sa_subdiv">Planar Subdivisions</a>
  28 </ul>
  29 <li><a href="#cv_motion">Motion Analysis and Object Tracking</a>
  30 <ul>
  31 <li><a href="#cv_motion_acc">Accumulation of Background Statistics</a>
  32 <li><a href="#cv_motion_motempl">Motion Templates</a>
  33 <li><a href="#cv_motion_tracking">Object Tracking</a>
  34 <li><a href="#cv_motion_optflow">Optical Flow</a>
  35 <li><a href="#cv_motion_feature">Feature Matching</a>
  36 <li><a href="#cv_motion_estimators">Estimators</a>
  37 </ul>
  38 <li><a href="#cv_pattern">Pattern Recognition</a>
  39 <ul>
  40 <li><a href="#cv_pattern_objdetection">Object Detection</a>
  41 </ul>
  42 <li><a href="#cv_3d">Camera Calibration and 3D Reconstruction</a>
  43 <ul>
  44 <li><a href="#cv_3d_calibration">Camera Calibration</a>
  45 <li><a href="#cv_3d_pose">Pose Estimation</a>
  46 <li><a href="#cv_3d_epipolar">Epipolar Geometry</a>
  47 </ul>
  48 <li><a href="#cv_func_index">Alphabetical List of Functions</a>
  49 <li><a href="#cv_bib">Bibliography</a>
  50 </ul></p>
  51
  52 <hr><h1><a name="cv_imgproc">Image Processing</a></h1>
  53
  54 <p>
  55 Note:<br>
  56 The chapter describes functions for image processing and analysis.
  57 Most of the functions work with 2d arrays of pixels. We refer the arrays
  58 as "images" however they do not necessarily have to be IplImage&#146;s, they may
  59 be CvMat&#146;s or CvMatND&#146;s as well.
  60 </p>
  61
  62 <hr><h2><a name="cv_imgproc_features">Gradients, Edges and Corners</a></h2>
  63
  64 <hr><h3><a name="decl_cvSobel">Sobel</a></h3>
  65 <p class="Blurb">Calculates first, second, third or mixed image derivatives using extended Sobel operator</p>
  66 <pre>
  67 void cvSobel( const CvArr* src, CvArr* dst, int xorder, int yorder, int aperture_size=3 );
  68 </pre><p><dl>
  69 <dt>src<dd>Source image.
  70 <dt>dst<dd>Destination image.
  71 <dt>xorder<dd>Order of the derivative x .
  72 <dt>yorder<dd>Order of the derivative y .
  73 <dt>aperture_size<dd>Size of the extended Sobel kernel, must be 1, 3, 5 or 7.
  74 In all cases except 1, aperture_size &times;aperture_size separable kernel will be used to calculate
  75 the derivative. For <code>aperture_size</code>=1 3x1 or 1x3 kernel is used (Gaussian smoothing is not done).
  76 There is also special value <code>CV_SCHARR</code> (=-1) that corresponds to 3x3 Scharr filter that may
  77 give more accurate results than 3x3 Sobel. Scharr aperture is:
  78 <pre>
  79 | -3 0  3|
  80 |-10 0 10|
  81 | -3 0  3|
  82 </pre>
  83 for x-derivative or transposed for y-derivative.
  84 </dl><p>
  85 The function <code>cvSobel</code> calculates the image derivative by convolving the image
  86 with the appropriate kernel:</p>
  87 <pre>
  88 dst(x,y) = d<sup>xorder+yorder</sup>src/dx<sup>xorder</sup>&bull;dy<sup>yorder</sup> |<sub>(x,y)</sub>
  89 </pre>
  90 The Sobel operators combine Gaussian smoothing and differentiation so the result is more or less
  91 robust to the noise. Most often, the function is called with (xorder=1, yorder=0, aperture_size=3) or
  92 (xorder=0, yorder=1, aperture_size=3) to calculate first x- or y- image derivative.
  93 The first case corresponds to</p>
  94 <pre>
  95   |-1  0  1|
  96   |-2  0  2|
  97   |-1  0  1|
  98 </pre>
  99 <p>kernel and the second one corresponds to</p>
 100 <pre>
 101   |-1 -2 -1|
 102   | 0  0  0|
 103   | 1  2  1|
 104 or
 105   | 1  2  1|
 106   | 0  0  0|
 107   |-1 -2 -1|
 108 </pre>
 109 kernel, depending on the image origin (<code>origin</code> field of <code>IplImage</code> structure).
 110 No scaling is done, so the destination image usually has larger by absolute value numbers than
 111 the source image. To avoid overflow, the function requires 16-bit destination image if
 112 the source image is 8-bit. The result can be converted back to 8-bit using <a href="#decl_cvConvertScale">cvConvertScale</a> or
 113 <a href="opencvref_cxcore.htm#decl_cvConvertScaleAbs">cvConvertScaleAbs</a> functions. Besides 8-bit images the function
 114 can process 32-bit floating-point images.
 115 Both source and destination must be single-channel images of equal size or ROI size.
 116 </p>
 117
 118
 119 <hr><h3><a name="decl_cvLaplace">Laplace</a></h3>
 120 <p class="Blurb">Calculates Laplacian of the image</p>
 121 <pre>
 122 void cvLaplace( const CvArr* src, CvArr* dst, int aperture_size=3 );
 123 </pre><p><dl>
 124 <dt>src<dd>Source image.
 125 <dt>dst<dd>Destination image.
 126 <dt>aperture_size<dd>Aperture size (it has the same meaning as in <a href="#decl_cvSobel">cvSobel</a>).
 127 </dl><p>
 128 The function <code>cvLaplace</code> calculates Laplacian of the source image by summing
 129 second x- and y- derivatives calculated using Sobel operator:</p>
 130 <pre>
 131 dst(x,y) = d<sup>2</sup>src/dx<sup>2</sup> + d<sup>2</sup>src/dy<sup>2</sup>
 132 </pre>
 133 <p>
 134 Specifying <code>aperture_size</code>=1 gives the fastest variant that is equal to
 135 convolving the image with the following kernel:</p>
 136 <pre>
 137 |0  1  0|
 138 |1 -4  1|
 139 |0  1  0|
 140 </pre><p>
 141 Similar to <a href="#decl_cvSobel">cvSobel</a> function, no scaling is done and the same combinations of input and
 142 output formats are supported.
 143 </p>
 144
 145
 146 <hr><h3><a name="decl_cvCanny">Canny</a></h3>
 147 <p class="Blurb">Implements Canny algorithm for edge detection</p>
 148 <pre>
 149 void cvCanny( const CvArr* image, CvArr* edges, double threshold1,
 150               double threshold2, int aperture_size=3 );
 151 </pre><p><dl>
 152 <dt>image<dd>Input image.
 153 <dt>edges<dd>Image to store the edges found by the function.
 154 <dt>threshold1<dd>The first threshold.
 155 <dt>threshold2<dd>The second threshold.
 156 <dt>aperture_size<dd>Aperture parameter for Sobel operator (see <a href="#decl_cvSobel">cvSobel</a>).
 157 </dl><p>
 158 The function <code>cvCanny</code> finds the edges on the input image <code>image</code> and marks them in the
 159 output image <code>edges</code> using the Canny algorithm. The smallest of <code>threshold1</code> and
 160 <code>threshold2</code> is used for edge linking, the largest - to find initial segments of strong edges.</p>
 161
 162
 163 <hr><h3><a name="decl_cvPreCornerDetect">PreCornerDetect</a></h3>
 164 <p class="Blurb">Calculates feature map for corner detection</p>
 165 <pre>
 166 void cvPreCornerDetect( const CvArr* image, CvArr* corners, int aperture_size=3 );
 167 </pre><p><dl>
 168 <dt>image<dd>Input image.
 169 <dt>corners<dd>Image to store the corner candidates.
 170 <dt>aperture_size<dd>Aperture parameter for Sobel operator (see <a href="#decl_cvSobel">cvSobel</a>).
 171 </dl><p>
 172 The function <code>cvPreCornerDetect</code> calculates the function
 173 D<sub>x</sub><sup>2</sup>D<sub>yy</sub>+D<sub>y</sub><sup>2</sup>D<sub>xx</sub> - 2D<sub>x</sub>D<sub>y</sub>D<sub>xy</sub>
 174 where D<sub>?</sub> denotes one of the first image derivatives and D<sub>??</sub> denotes a second image
 175 derivative. The corners can be found as local maximums of the function:</p>
 176 <pre>
 177 // assume that the image is floating-point
 178 IplImage* corners = cvCloneImage(image);
 179 IplImage* dilated_corners = cvCloneImage(image);
 180 IplImage* corner_mask = cvCreateImage( cvGetSize(image), 8, 1 );
 181 cvPreCornerDetect( image, corners, 3 );
 182 cvDilate( corners, dilated_corners, 0, 1 );
 183 cvSubS( corners, dilated_corners, corners );
 184 cvCmpS( corners, 0, corner_mask, CV_CMP_GE );
 185 cvReleaseImage( &amp;corners );
 186 cvReleaseImage( &amp;dilated_corners );
 187 </pre>
 188
 189 <hr><h3><a name="decl_cvCornerEigenValsAndVecs">CornerEigenValsAndVecs</a></h3>
 190 <p class="Blurb">Calculates eigenvalues and eigenvectors of image blocks for corner detection</p>
 191 <pre>
 192 void cvCornerEigenValsAndVecs( const CvArr* image, CvArr* eigenvv,
 193                                int block_size, int aperture_size=3 );
 194 </pre><p><dl>
 195 <dt>image<dd>Input image.
 196 <dt>eigenvv<dd>Image to store the results. It must be 6 times wider than the input image.
 197 <dt>block_size<dd>Neighborhood size (see discussion).
 198 <dt>aperture_size<dd>Aperture parameter for Sobel operator (see <a href="#decl_cvSobel">cvSobel</a>).
 199 </dl><p>
 200 For every pixel The function <code>cvCornerEigenValsAndVecs</code> considers
 201 <code>block_size</code> &times; <code>block_size</code> neighborhood S(p). It calculates
 202 covariation matrix of derivatives over the neighborhood as:</p>
 203 <pre>
 204     | sum<sub>S(p)</sub>(dI/dx)<sup>2</sup>   sum<sub>S(p)</sub>(dI/dx&bull;dI/dy)|
 205 M = |                                 |
 206     | sum<sub>S(p)</sub>(dI/dx&bull;dI/dy)  sum<sub>S(p)</sub>(dI/dy)<sup>2</sup> |
 207 </pre><p>
 208 After that it finds eigenvectors and eigenvalues of the matrix and stores
 209 them into destination image in form
 210 (&lambda;<sub>1</sub>, &lambda;<sub>2</sub>, x<sub>1</sub>, y<sub>1</sub>, x<sub>2</sub>, y<sub>2</sub>),
 211 where<br>
 212 &lambda;<sub>1</sub>, &lambda;<sub>2</sub> - eigenvalues of <code>M</code>; not sorted<br>
 213 (x<sub>1</sub>, y<sub>1</sub>) - eigenvector corresponding to &lambda;<sub>1</sub><br>
 214 (x<sub>2</sub>, y<sub>2</sub>) - eigenvector corresponding to &lambda;<sub>2</sub><br>
 215 </p>
 216
 217
 218 <hr><h3><a name="decl_cvCornerMinEigenVal">CornerMinEigenVal</a></h3>
 219 <p class="Blurb">Calculates minimal eigenvalue of gradient matrices for corner detection</p>
 220 <pre>
 221 void cvCornerMinEigenVal( const CvArr* image, CvArr* eigenval, int block_size, int aperture_size=3 );
 222 </pre><p><dl>
 223 <dt>image<dd>Input image.
 224 <dt>eigenval<dd>Image to store the minimal eigenvalues. Should have the same size as <code>image</code>
 225 <dt>block_size<dd>Neighborhood size (see discussion of <a href="#decl_cvCornerEigenValsAndVecs">cvCornerEigenValsAndVecs</a>).
 226 <dt>aperture_size<dd>Aperture parameter for Sobel operator (see <a href="#decl_cvSobel">cvSobel</a>).
 227 format. In the case of floating-point input format this parameter is the number
 228 of the fixed float filter used for differencing.
 229 </dl><p>
 230 The function <code>cvCornerMinEigenVal</code> is similar to <a href="#decl_cvCornerEigenValsAndVecs">cvCornerEigenValsAndVecs</a> but
 231 it calculates and stores only the minimal eigenvalue of derivative covariation matrix for every pixel,
 232 i.e. min(&lambda;<sub>1</sub>, &lambda;<sub>2</sub>) in terms of the previous function.
 233 </p>
 234
 235
 236 <hr><h3><a name="decl_cvCornerHarris">CornerHarris</a></h3>
 237 <p class="Blurb">Harris edge detector</p>
 238 <pre>
 239 void cvCornerHarris( const CvArr* image, CvArr* harris_dst,
 240                      int block_size, int aperture_size=3, double k=0.04 );
 241 </pre><p><dl>
 242 <dt>image<dd>Input image.
 243 <dt>harris_dst<dd>Image to store the Harris detector responses. Should have the same size as <code>image</code>
 244 <dt>block_size<dd>Neighborhood size (see discussion of <a href="#decl_cvCornerEigenValsAndVecs">cvCornerEigenValsAndVecs</a>).
 245 <dt>aperture_size<dd>Aperture parameter for Sobel operator (see <a href="#decl_cvSobel">cvSobel</a>).
 246 format. In the case of floating-point input format this parameter is the number
 247 of the fixed float filter used for differencing.
 248 <dt>k<dd>Harris detector free parameter. See the formula below.
 249 </dl><p>
 250 The function <code>cvCornerHarris</code> finds feature points (corners) in the image
 251 using Harris' method. Similarly to
 252 <a href="#decl_cvCornerMinEigenVal">cvCornerMinEigenVal</a> and
 253 <a href="#decl_cvCornerEigenValsAndVecs">cvCornerEigenValsAndVecs</a>,
 254 for each pixel it calculates 2x2 gradient covariation matrix
 255 <code>M</code> over <code>block_size&times;block_size</code> neighborhood.
 256 Then, it stores</p>
 257 <pre>det(M) - k*trace(M)<sup>2</sup></pre>
 258 to the corresponding pixel of the destination image.
 259 The corners can be found as local maxima in the destination image.
 260 </p>
 261
 262
 263 <hr><h3><a name="decl_cvFindCornerSubPix">FindCornerSubPix</a></h3>
 264 <p class="Blurb">Refines corner locations</p>
 265 <pre>
 266 void cvFindCornerSubPix( const CvArr* image, CvPoint2D32f* corners,
 267                          int count, CvSize win, CvSize zero_zone,
 268                          CvTermCriteria criteria );
 269 </pre><p><dl>
 270 <dt>image<dd>Input image.
 271 <dt>corners<dd>Initial coordinates of the input corners and refined coordinates on
 272 output.
 273 <dt>count<dd>Number of corners.
 274 <dt>win<dd>Half sizes of the search window. For example, if <code>win</code>=(5,5) then
 275 5*2+1 &times; 5*2+1 = 11 &times; 11 search window is used.
 276 <dt>zero_zone<dd>Half size of the dead region in the middle of the search zone over which the
 277 summation in formulae below is not done. It is used sometimes to avoid possible singularities of the autocorrelation matrix.
 278 The value of (-1,-1) indicates that there is no such size.
 279 <dt>criteria<dd>Criteria for termination of the iterative process of corner refinement.
 280 That is, the process of corner position refinement stops either after certain number of iteration or
 281 when a required accuracy is achieved. The <code>criteria</code> may specify either of or both the maximum
 282 number of iteration and the required accuracy.
 283 </dl><p>
 284 The function <code>cvFindCornerSubPix</code> iterates to find the sub-pixel accurate location
 285 of corners, or radial saddle points, as shown in on the picture below.</p>
 286 <p>
 287 <image align="center" src="pics/cornersubpix.png">
 288 </p>
 289 <p>
 290 Sub-pixel accurate corner locator is based on the observation that every vector
 291 from the center <code>q</code> to a point <code>p</code> located within a neighborhood of <code>q</code> is orthogonal
 292 to the image gradient at <code>p</code> subject to image and measurement noise. Consider the expression:
 293 </p>
 294 <pre>
 295 &epsilon;<sub>i</sub>=DI<sub>p<sub>i</sub></sub><sup>T</sup>&bull;(q-p<sub>i</sub>)
 296 </pre>
 297 where <code>DI<sub>p<sub>i</sub></sub></code> is the image gradient
 298 at the one of the points <code>p<sub>i</sub></code> in a neighborhood of <code>q</code>.
 299 The value of <code>q</code> is to be found such that <code>&epsilon;<sub>i</sub></code> is minimized.
 300 A system of equations may be set up with <code>&epsilon;<sub>i</sub></code>' set to zero:</p>
 301 <pre>
 302 sum<sub>i</sub>(DI<sub>p<sub>i</sub></sub>&bull;DI<sub>p<sub>i</sub></sub><sup>T</sup>)&bull;q - sum<sub>i</sub>(DI<sub>p<sub>i</sub></sub>&bull;DI<sub>p<sub>i</sub></sub><sup>T</sup>&bull;p<sub>i</sub>) = 0
 303 </pre>
 304 <p>where the gradients are summed within a neighborhood ("search window") of <code>q</code>.
 305 Calling the first gradient term <code>G</code> and the second gradient term <code>b</code> gives:</p>
 306 <pre>
 307 q=G<sup>-1</sup>&bull;b
 308 </pre>
 309 <p>
 310 The algorithm sets the center of the neighborhood window at this new center <code>q</code>
 311 and then iterates until the center keeps within a set threshold.
 312 </p>
 313
 314
 315 <hr><h3><a name="decl_cvGoodFeaturesToTrack">GoodFeaturesToTrack</a></h3>
 316 <p class="Blurb">Determines strong corners on image</p>
 317 <pre>
 318 void cvGoodFeaturesToTrack( const CvArr* image, CvArr* eig_image, CvArr* temp_image,
 319                             CvPoint2D32f* corners, int* corner_count,
 320                             double quality_level, double min_distance,
 321                             const CvArr* mask=NULL, int block_size=3,
 322                             int use_harris=0, double k=0.04 );
 323 </pre><p><dl>
 324 <dt>image<dd>The source 8-bit or floating-point 32-bit, single-channel image.
 325 <dt>eig_image<dd>Temporary floating-point 32-bit image of the same size as <code>image</code>.
 326 <dt>temp_image<dd>Another temporary image of the same size and same format as <code>eig_image</code>.
 327 <dt>corners<dd>Output parameter. Detected corners.
 328 <dt>corner_count<dd>Output parameter. Number of detected corners.
 329 <dt>quality_level<dd>Multiplier for the maxmin eigenvalue; specifies minimal accepted
 330 quality of image corners.
 331 <dt>min_distance<dd>Limit, specifying minimum possible distance between returned
 332 corners; Euclidean distance is used.
 333 <dt>mask<dd>Region of interest. The function selects points either in the specified region
 334 or in the whole image if the mask is NULL.
 335 <dt>block_size<dd>Size of the averaging block, passed to underlying
 336            <a href="#decl_cvCornerMinEigenVal">cvCornerMinEigenVal</a> or
 337            <a href="#decl_cvCornerHarris">cvCornerHarris</a> used by the function.
 338 <dt>use_harris<dd>If nonzero, Harris operator (<a href="#decl_cvCornerHarris">cvCornerHarris</a>)
 339                   is used instead of default <a href="#decl_cvCornerMinEigenVal">cvCornerMinEigenVal</a>.
 340 <dt>k<dd>Free parameter of Harris detector; used only if <code>use_harris&ne;0</code>
 341 </dl><p>
 342 The function <code>cvGoodFeaturesToTrack</code> finds corners with big eigenvalues in the
 343 image. The function first calculates the minimal eigenvalue for every source image pixel
 344 using <a href="#decl_cvCornerMinEigenVal">cvCornerMinEigenVal</a> function and stores them in <code>eig_image</code>.
 345 Then it performs non-maxima suppression (only local maxima in 3x3 neighborhood remain).
 346 The next step is rejecting the corners with the
 347 minimal eigenvalue less than <code>quality_level</code>&bull;max(<code>eig_image</code>(x,y)). Finally,
 348 the function ensures that all the corners found are distanced enough one from
 349 another by considering the corners (the most strongest corners are considered first)
 350 and checking that the distance between the newly considered feature and the features considered earlier
 351 is larger than <code>min_distance</code>. So, the function removes the features than are too close
 352 to the stronger features.</p>
 353
 354
 355 <hr><h2><a name="cv_imgproc_resampling">Sampling, Interpolation and Geometrical Transforms</a></h2>
 356
 357 <hr><h3><a name="decl_cvSampleLine">SampleLine</a></h3>
 358 <p class="Blurb">Reads raster line to buffer</p>
 359 <pre>
 360 int cvSampleLine( const CvArr* image, CvPoint pt1, CvPoint pt2,
 361                   void* buffer, int connectivity=8 );
 362 </pre><p><dl>
 363 <dt>image<dd>Image to sample the line from.
 364 <dt>pt1<dd>Starting the line point.
 365 <dt>pt2<dd>Ending the line point.
 366 <dt>buffer<dd>Buffer to store the line points; must have enough size to store
 367 max( |<code>pt2.x</code>-<code>pt1.x</code>|+1, |<code>pt2.y</code>-<code>pt1.y</code>|+1 )</code> points in case
 368 of 8-connected line and |<code>pt2.x</code>-<code>pt1.x</code>|+|<code>pt2.y</code>-<code>pt1.y</code>|+1 in case
 369 of 4-connected line.
 370 <dt>connectivity<dd>The line connectivity, 4 or 8.
 371 </dl><p>
 372 The function <code>cvSampleLine</code> implements a particular case of application of line
 373 iterators. The function reads all the image points lying on the line between <code>pt1</code>
 374 and <code>pt2</code>, including the ending points, and stores them into the buffer.</p>
 375
 376
 377 <hr><h3><a name="decl_cvGetRectSubPix">GetRectSubPix</a></h3>
 378 <p class="Blurb">Retrieves pixel rectangle from image with sub-pixel accuracy</p>
 379 <pre>
 380 void cvGetRectSubPix( const CvArr* src, CvArr* dst, CvPoint2D32f center );
 381 </pre><p><dl>
 382 <dt>src<dd>Source image.
 383 <dt>dst<dd>Extracted rectangle.
 384 <dt>center<dd>Floating point coordinates of the extracted rectangle center within the source image.
 385 The center must be inside the image.
 386 </dl><p>
 387 The function <code>cvGetRectSubPix</code> extracts pixels from <code>src</code>:</p>
 388 <pre>
 389 dst(x, y) = src(x + center.x - (width(dst)-1)*0.5, y + center.y - (height(dst)-1)*0.5)
 390 </pre>
 391 <p>
 392 where the values of pixels at non-integer coordinates are
 393 retrieved using bilinear interpolation. Every channel of multiple-channel images is processed
 394 independently.
 395 Whereas the rectangle center must be inside the image, the whole rectangle may be partially occluded.
 396 In this case, the replication border mode is used to get pixel values beyond the image boundaries.
 397 </p>
 398
 399
 400 <hr><h3><a name="decl_cvGetQuadrangleSubPix">GetQuadrangleSubPix</a></h3>
 401 <p class="Blurb">Retrieves pixel quadrangle from image with sub-pixel accuracy</p>
 402 <pre>
 403 void cvGetQuadrangleSubPix( const CvArr* src, CvArr* dst, const CvMat* map_matrix );
 404 </pre><p><dl>
 405 <dt>src<dd>Source image.
 406 <dt>dst<dd>Extracted quadrangle.
 407 <dt>map_matrix<dd>The transformation 2 &times; 3 matrix [<code>A</code>|<code>b</code>] (see the discussion).
 408 </dl><p>
 409 The function <code>cvGetQuadrangleSubPix</code> extracts pixels from <code>src</code> at sub-pixel accuracy
 410 and stores them to <code>dst</code> as follows:</p>
 411 <pre>
 412 dst(x, y)= src( A<sub>11</sub>x'+A<sub>12</sub>y'+b<sub>1</sub>, A<sub>21</sub>x'+A<sub>22</sub>y'+b<sub>2</sub>),
 413
 414 where <code>A</code> and <code>b</code> are taken from <code>map_matrix</code>
 415              | A<sub>11</sub> A<sub>12</sub>  b<sub>1</sub> |
 416 map_matrix = |            |
 417              | A<sub>21</sub> A<sub>22</sub>  b<sub>2</sub> |,
 418
 419 x'=x-(width(dst)-1)*0.5, y'=y-(height(dst)-1)*0.5
 420 </pre>
 421 <p>
 422 where the values of pixels at non-integer coordinates A&bull;(x,y)<sup>T</sup>+b are
 423 retrieved using bilinear interpolation. When the function needs pixels outside of the image, it uses replication
 424 border mode to reconstruct the values. Every channel of multiple-channel images is processed
 425 independently.</p>
 426
 427
 428 <hr><h3><a name="decl_cvResize">Resize</a></h3>
 429 <p class="Blurb">Resizes image</p>
 430 <pre>
 431 void cvResize( const CvArr* src, CvArr* dst, int interpolation=CV_INTER_LINEAR );
 432 </pre><p><dl>
 433 <dt>src<dd>Source image.
 434 <dt>dst<dd>Destination image.
 435 <dt>interpolation<dd>Interpolation method:<ul>
 436     <li>CV_INTER_NN - nearest-neighbor interpolation,
 437     <li>CV_INTER_LINEAR - bilinear interpolation (used by default)
 438     <li>CV_INTER_AREA - resampling using pixel area relation. It is the preferred method for image
 439     decimation that gives moire-free results.
 440     In case of zooming it is similar to <code>CV_INTER_NN</code> method.
 441     <li>CV_INTER_CUBIC - bicubic interpolation.
 442     </ul>
 443 </dl><p>
 444 The function <code>cvResize</code> resizes image <code>src</code> (or its ROI)
 445 so that it fits exactly to <code>dst</code> (or its ROI).</p>
 446
 447 <hr><h3><a name="decl_cvWarpAffine">WarpAffine</a></h3>
 448 <p class="Blurb">Applies affine transformation to the image</p>
 449 <pre>
 450 void cvWarpAffine( const CvArr* src, CvArr* dst, const CvMat* map_matrix,
 451                    int flags=CV_INTER_LINEAR+CV_WARP_FILL_OUTLIERS,
 452                    CvScalar fillval=cvScalarAll(0) );
 453 </pre><p><dl>
 454 <dt>src<dd>Source image.
 455 <dt>dst<dd>Destination image.
 456 <dt>map_matrix<dd>2&times;3 transformation matrix.
 457 <dt>flags<dd>A combination of interpolation method and the following optional flags:<ul>
 458     <li>CV_WARP_FILL_OUTLIERS - fill all the destination image pixels. If some of them correspond to
 459             outliers in the source image, they are set to <code>fillval</code>.
 460     <li>CV_WARP_INVERSE_MAP - indicates that <code>matrix</code> is inverse transform from destination image
 461                             to source and, thus, can be used directly for pixel interpolation. Otherwise,
 462                             the function finds the inverse transform from <code>map_matrix</code>.
 463     </ul>
 464 <dt>fillval<dd>A value used to fill outliers.
 465 </dl><p>
 466 The function <code>cvWarpAffine</code> transforms source image using the specified
 467 matrix:</p>
 468 <pre>
 469 dst(x&#146;,y&#146;)&lt;-src(x,y)
 470 (x&#146;,y&#146;)<sup>T</sup>=map_matrix&bull;(x,y,1)<sup>T</sup>+b if CV_WARP_INVERSE_MAP is not set,
 471 (x, y)<sup>T</sup>=map_matrix&bull;(x&#146;,y&apos,1)<sup>T</sup>+b otherwise
 472 </pre>
 473 <p>
 474 The function is similar to <a href="#decl_cvGetQuadrangleSubPix">cvGetQuadrangleSubPix</a> but they are
 475 not exactly the same. <a href="#decl_cvWarpAffine">cvWarpAffine</a> requires input and output
 476 image have the same data type, has larger overhead (so it is not quite suitable for small images)
 477 and can leave part of destination image unchanged. While <a href="#decl_cvGetQuadrangleSubPix">cvGetQuadrangleSubPix</a>
 478 may extract quadrangles from 8-bit images into floating-point buffer, has smaller overhead and
 479 always changes the whole destination image content.
 480 </p>
 481 <p>
 482 To transform a sparse set of points, use <a href="#decl_cvTransform">cvTransform</a>
 483 function from cxcore.</p>
 484
 485 <hr><h3><a name="decl_cvGetAffineTransform">GetAffineTransform</a></h3>
 486 <p class="Blurb">Calculates affine transform from 3 corresponding points</p>
 487 <pre>
 488 CvMat* cvGetAffineTransform( const CvPoint2D32f* src, const CvPoint2D32f* dst,
 489                              CvMat* map_matrix );
 490 </pre><p><dl>
 491 <dt>src<dd>Coordinates of 3 triangle vertices in the source image.
 492 <dt>dst<dd>Coordinates of the 3 corresponding triangle vertices in the destination image.
 493 <dt>map_matrix<dd>Pointer to the destination 2&times;3 matrix.
 494 </dl><p>
 495 The function <code>cvGetAffineTransform</code> calculates the
 496 matrix of an affine transform such that:</p>
 497 <pre>
 498 (x'<sub>i</sub>,y'<sub>i</sub>)<sup>T</sup>=map_matrix&bull;(x<sub>i</sub>,y<sub>i</sub>,1)<sup>T</sup>
 499 </pre>
 500 <p>where <code>dst(i)=(x'<sub>i</sub>,y'<sub>i</sub>), src(i)=(x<sub>i</sub>,y<sub>i</sub>), i=0..2</code>.</p>
 501
 502 <hr><h3><a name="decl_cv2DRotationMatrix">2DRotationMatrix</a></h3>
 503 <p class="Blurb">Calculates affine matrix of 2d rotation</p>
 504 <pre>
 505 CvMat* cv2DRotationMatrix( CvPoint2D32f center, double angle,
 506                            double scale, CvMat* map_matrix );
 507 </pre><p><dl>
 508 <dt>center<dd>Center of the rotation in the source image.
 509 <dt>angle<dd>The rotation angle in degrees. Positive values mean counter-clockwise rotation
 510 (the coordinate origin is assumed at top-left corner).
 511 <dt>scale<dd>Isotropic scale factor.
 512 <dt>map_matrix<dd>Pointer to the destination 2&times;3 matrix.
 513 </dl><p>
 514 The function <code>cv2DRotationMatrix</code> calculates matrix:</p>
 515 <pre>
 516 [  &alpha;  &beta;  |  (1-&alpha;)*center.x - &beta;*center.y ]
 517 [ -&beta;  &alpha;  |  &beta;*center.x + (1-&alpha;)*center.y ]
 518
 519 where &alpha;=scale*cos(angle), &beta;=scale*sin(angle)
 520 </pre>
 521 <p>The transformation maps the rotation center to itself. If this is not the purpose,
 522 the shift should be adjusted.</p>
 523
 524
 525 <hr><h3><a name="decl_cvWarpPerspective">WarpPerspective</a></h3>
 526 <p class="Blurb">Applies perspective transformation to the image</p>
 527 <pre>
 528 void cvWarpPerspective( const CvArr* src, CvArr* dst, const CvMat* map_matrix,
 529                         int flags=CV_INTER_LINEAR+CV_WARP_FILL_OUTLIERS,
 530                         CvScalar fillval=cvScalarAll(0) );
 531 </pre><p><dl>
 532 <dt>src<dd>Source image.
 533 <dt>dst<dd>Destination image.
 534 <dt>map_matrix<dd>3&times;3 transformation matrix.
 535 <dt>flags<dd>A combination of interpolation method and the following optional flags:<ul>
 536     <li>CV_WARP_FILL_OUTLIERS - fill all the destination image pixels. If some of them correspond to
 537                                 outliers in the source image, they are set to <code>fillval</code>.
 538     <li>CV_WARP_INVERSE_MAP - indicates that <code>matrix</code> is inverse transform from destination image
 539                             to source and, thus, can be used directly for pixel interpolation. Otherwise,
 540                             the function finds the inverse transform from <code>map_matrix</code>.
 541     </ul>
 542 <dt>fillval<dd>A value used to fill outliers.
 543 </dl><p>
 544 The function <code>cvWarpPerspective</code> transforms source image using
 545 the specified matrix:</p>
 546 <pre>
 547 dst(x&#146;,y&#146;)&lt;-src(x,y)
 548 (t&bull;x&#146;,t&bull;y&#146;,t)<sup>T</sup>=map_matrix&bull;(x,y,1)<sup>T</sup>+b if CV_WARP_INVERSE_MAP is not set,
 549 (t&bull;x, t&bull;y, t)<sup>T</sup>=map_matrix&bull;(x&#146;,y&apos,1)<sup>T</sup>+b otherwise
 550 </pre>
 551 <p>
 552 For a sparse set of points
 553 use <a href="#decl_cvPerspectiveTransform">cvPerspectiveTransform</a> function from cxcore.</p>
 554
 555
 556 <hr><h3><a name="decl_cvGetPerspectiveTransform">GetPerspectiveTransform</a></h3>
 557 <p class="Blurb">Calculates perspective transform from 4 corresponding points</p>
 558 <pre>
 559 CvMat* cvGetPerspectiveTransform( const CvPoint2D32f* src, const CvPoint2D32f* dst,
 560                                   CvMat* map_matrix );
 561
 562 #define cvWarpPerspectiveQMatrix cvGetPerspectiveTransform
 563 </pre><p><dl>
 564 <dt>src<dd>Coordinates of 4 quadrangle vertices in the source image.
 565 <dt>dst<dd>Coordinates of the 4 corresponding quadrangle vertices in the destination image.
 566 <dt>map_matrix<dd>Pointer to the destination 3&times;3 matrix.
 567 </dl><p>
 568 The function <code>cvGetPerspectiveTransform</code> calculates
 569 matrix of perspective transform such that:</p>
 570 <pre>
 571 (t<sub>i</sub>&bull;x'<sub>i</sub>,t<sub>i</sub>&bull;y'<sub>i</sub>,t<sub>i</sub>)<sup>T</sup>=map_matrix&bull;(x<sub>i</sub>,y<sub>i</sub>,1)<sup>T</sup>
 572 </pre>
 573 <p>where <code>dst(i)=(x'<sub>i</sub>,y'<sub>i</sub>), src(i)=(x<sub>i</sub>,y<sub>i</sub>), i=0..3</code>.</p>
 574
 575
 576 <hr><h3><a name="decl_cvRemap">Remap</a></h3>
 577 <p class="Blurb">Applies generic geometrical transformation to the image</p>
 578 <pre>
 579 void cvRemap( const CvArr* src, CvArr* dst,
 580               const CvArr* mapx, const CvArr* mapy,
 581               int flags=CV_INTER_LINEAR+CV_WARP_FILL_OUTLIERS,
 582               CvScalar fillval=cvScalarAll(0) );
 583 </pre><p><dl>
 584 <dt>src<dd>Source image.
 585 <dt>dst<dd>Destination image.
 586 <dt>mapx<dd>The map of x-coordinates (32FC1 image).
 587 <dt>mapy<dd>The map of y-coordinates (32FC1 image).
 588 <dt>flags<dd>A combination of interpolation method and the following optional flag(s):<ul>
 589     <li>CV_WARP_FILL_OUTLIERS - fill all the destination image pixels. If some of them correspond to
 590                                 outliers in the source image, they are set to <code>fillval</code>.
 591     </ul>
 592 <dt>fillval<dd>A value used to fill outliers.
 593 </dl><p>
 594 The function <code>cvRemap</code> transforms source image using
 595 the specified map:</p>
 596 <pre>
 597 dst(x,y)&lt;-src(mapx(x,y),mapy(x,y))
 598 </pre>
 599 <p>Similar to other geometrical transformations, some interpolation method (specified by user)
 600 is used to extract pixels with non-integer coordinates.
 601 </p>
 602
 603
 604 <hr><h3><a name="decl_cvLogPolar">LogPolar</a></h3>
 605 <p class="Blurb">Remaps image to log-polar space</p>
 606 <pre>
 607 void cvLogPolar( const CvArr* src, CvArr* dst,
 608                  CvPoint2D32f center, double M,
 609                  int flags=CV_INTER_LINEAR+CV_WARP_FILL_OUTLIERS );
 610 </pre><p><dl>
 611 <dt>src<dd>Source image.
 612 <dt>dst<dd>Destination image.
 613 <dt>center<dd>The transformation center, where the output precision is maximal.
 614 <dt>M<dd>Magnitude scale parameter. See below.
 615 <dt>flags<dd>A combination of interpolation method and the following optional flags:<ul>
 616     <li>CV_WARP_FILL_OUTLIERS - fill all the destination image pixels. If some of them correspond to
 617                                 outliers in the source image, they are set to zeros.
 618     <li>CV_WARP_INVERSE_MAP - indicates that <code>matrix</code> is inverse transform from destination image
 619                             to source and, thus, can be used directly for pixel interpolation. Otherwise,
 620                             the function finds the inverse transform from <code>map_matrix</code>.
 621     </ul>
 622 <dt>fillval<dd>A value used to fill outliers.
 623 </dl><p>
 624 The function <code>cvLogPolar</code> transforms source image using
 625 the following transformation:</p>
 626 <pre>
 627 Forward transformation (<code>CV_WARP_INVERSE_MAP</code> is not set):
 628 dst(phi,rho)&lt;-src(x,y)
 629
 630 Inverse transformation (<code>CV_WARP_INVERSE_MAP</code> is set):
 631 dst(x,y)&lt;-src(phi,rho),
 632
 633 where rho=M*log(sqrt(x<sup>2</sup>+y<sup>2</sup>))
 634       phi=atan(y/x)
 635 </pre>
 636 <p>The function emulates the human "foveal" vision and can be used for fast scale and rotation-invariant
 637 template matching, for object tracking etc.</p>
 638
 639 <h4>Example. Log-polar transformation.</h4>
 640 <pre>
 641 #include &lt;cv.h&gt;
 642 #include &lt;highgui.h&gt;
 643
 644 int main(int argc, char** argv)
 645 {
 646     IplImage* src;
 647
 648     if( argc == 2 && (src=cvLoadImage(argv[1],1) != 0 )
 649     {
 650         IplImage* dst = cvCreateImage( cvSize(256,256), 8, 3 );
 651         IplImage* src2 = cvCreateImage( cvGetSize(src), 8, 3 );
 652         cvLogPolar( src, dst, cvPoint2D32f(src->width/2,src->height/2), 40, CV_INTER_LINEAR+CV_WARP_FILL_OUTLIERS );
 653         cvLogPolar( dst, src2, cvPoint2D32f(src->width/2,src->height/2), 40, CV_INTER_LINEAR+CV_WARP_FILL_OUTLIERS+CV_WARP_INVERSE_MAP );
 654         cvNamedWindow( "log-polar", 1 );
 655         cvShowImage( "log-polar", dst );
 656         cvNamedWindow( "inverse log-polar", 1 );
 657         cvShowImage( "inverse log-polar", src2 );
 658         cvWaitKey();
 659     }
 660     return 0;
 661 }
 662 </pre>
 663
 664 <p>And this is what the program displays when opencv/samples/c/fruits.jpg is passed to it</p>
 665 <p>
 666 <img align="center" src="pics/logpolar.jpg" width=256 height=256>
 667 <img align="center" src="pics/inv_logpolar.jpg" width=256 height=256>
 668 </p>
 669
 670
 671 <hr><h2><a name="cv_imgproc_morphology">Morphological Operations</a></h2>
 672
 673 <hr><h3><a name="decl_cvCreateStructuringElementEx">CreateStructuringElementEx</a></h3>
 674 <p class="Blurb">Creates structuring element</p>
 675 <pre>
 676 IplConvKernel* cvCreateStructuringElementEx( int cols, int rows, int anchor_x, int anchor_y,
 677                                              int shape, int* values=NULL );
 678 </pre><p><dl>
 679 <dt>cols<dd>Number of columns in the structuring element.
 680 <dt>rows<dd>Number of rows in the structuring element.
 681 <dt>anchor_x<dd>Relative horizontal offset of the anchor point.
 682 <dt>anchor_y<dd>Relative vertical offset of the anchor point.
 683 <dt>shape<dd>Shape of the structuring element; may have the following values:
 684 <ul>
 685 <li><code>CV_SHAPE_RECT</code>, a rectangular element;
 686 <li><code>CV_SHAPE_CROSS</code>, a cross-shaped element;
 687 <li><code>CV_SHAPE_ELLIPSE</code>, an elliptic element;
 688 <li><code>CV_SHAPE_CUSTOM</code>, a user-defined element. In this case the parameter <code>values</code>
 689 specifies the mask, that is, which neighbors of the pixel must be considered.
 690 </ul>
 691 <dt>values<dd> Pointer to the structuring element data, a plane array, representing
 692 row-by-row scanning of the element matrix. Non-zero values indicate points that
 693 belong to the element. If the pointer is <code>NULL</code>, then all values are considered
 694 non-zero, that is, the element is of a rectangular shape. This parameter is
 695 considered only if the shape is <code>CV_SHAPE_CUSTOM</code>  .
 696 </dl><p>
 697 The function <a href="#decl_cv CreateStructuringElementEx">cv CreateStructuringElementEx</a>  allocates and fills the structure
 698 <code> IplConvKernel</code>, which can be used as a structuring element in the morphological
 699 operations.</p>
 700
 701
 702 <hr><h3><a name="decl_cvReleaseStructuringElement">ReleaseStructuringElement</a></h3>
 703 <p class="Blurb">Deletes structuring element</p>
 704 <pre>
 705 void cvReleaseStructuringElement( IplConvKernel** element );
 706 </pre><p><dl>
 707 <dt>element<dd>Pointer to the deleted structuring element.
 708 </dl><p>
 709 The function <code>cvReleaseStructuringElement</code> releases the structure <code>IplConvKernel</code>
 710 that is no longer needed. If <code>*element</code> is <code>NULL</code>, the function has no effect.</p>
 711
 712
 713 <hr><h3><a name="decl_cvErode">Erode</a></h3>
 714 <p class="Blurb">Erodes image by using arbitrary structuring element</p>
 715 <pre>
 716 void cvErode( const CvArr* src, CvArr* dst, IplConvKernel* element=NULL, int iterations=1 );
 717 </pre><p><dl>
 718 <dt>src<dd>Source image.
 719 <dt>dst<dd>Destination image.
 720 <dt>element<dd>Structuring element used for erosion. If it is <code>NULL</code>, a 3&times;3 rectangular
 721 structuring element is used.
 722 <dt>iterations<dd>Number of times erosion is applied.
 723 </dl><p>
 724 The function <code>cvErode</code> erodes the source image using the specified structuring element
 725 that determines the shape of a pixel neighborhood over which the minimum is taken:</p>
 726 <pre>
 727 dst=erode(src,element):  dst(x,y)=min<sub>((x',y') in element)</sub>)</sub>src(x+x',y+y')
 728 </pre>
 729 <p>The function supports the in-place mode. Erosion can be applied several (<code>iterations</code>)
 730 times. In case of color image each channel is processed independently.</p>
 731
 732
 733 <hr><h3><a name="decl_cvDilate">Dilate</a></h3>
 734 <p class="Blurb">Dilates image by using arbitrary structuring element</p>
 735 <pre>
 736 void cvDilate( const CvArr* src, CvArr* dst, IplConvKernel* element=NULL, int iterations=1 );
 737 </pre><p><dl>
 738 <dt>src<dd>Source image.
 739 <dt>dst<dd>Destination image.
 740 <dt>element<dd>Structuring element used for erosion. If it is <code>NULL</code>, a 3&times;3 rectangular
 741 structuring element is used.
 742 <dt>iterations<dd>Number of times erosion is applied.
 743 </dl><p>
 744 The function <code>cvDilate</code> dilates the source image using the specified structuring element
 745 that determines the shape of a pixel neighborhood over which the maximum is taken:</p>
 746 <pre>
 747 dst=dilate(src,element):  dst(x,y)=max<sub>((x',y') in element)</sub>)</sub>src(x+x',y+y')
 748 </pre>
 749 <p>The function supports the in-place mode. Dilation can be applied several (<code>iterations</code>)
 750 times. In case of color image each channel is processed independently.</p>
 751
 752
 753 <hr><h3><a name="decl_cvMorphologyEx">MorphologyEx</a></h3>
 754 <p class="Blurb">Performs advanced morphological transformations</p>
 755 <pre>
 756 void cvMorphologyEx( const CvArr* src, CvArr* dst, CvArr* temp,
 757                      IplConvKernel* element, int operation, int iterations=1 );
 758 </pre><p><dl>
 759 <dt>src<dd>Source image.
 760 <dt>dst<dd>Destination image.
 761 <dt>temp<dd>Temporary image, required in some cases.
 762 <dt>element<dd>Structuring element.
 763 <dt>operation<dd>Type of morphological operation, one of:<br>
 764                <code>CV_MOP_OPEN</code> - opening<br>
 765                <code>CV_MOP_CLOSE</code> - closing<br>
 766                <code>CV_MOP_GRADIENT</code> - morphological gradient<br>
 767                <code>CV_MOP_TOPHAT</code> - "top hat"<br>
 768                <code>CV_MOP_BLACKHAT</code> - "black hat"<br>
 769 <dt>iterations<dd>Number of times erosion and dilation are applied.
 770 </dl><p>
 771 The function <code>cvMorphologyEx</code> can perform advanced morphological
 772 transformations using erosion and dilation as basic operations.</p>
 773 <pre>
 774 Opening:
 775 dst=open(src,element)=dilate(erode(src,element),element)
 776
 777 Closing:
 778 dst=close(src,element)=erode(dilate(src,element),element)
 779
 780 Morphological gradient:
 781 dst=morph_grad(src,element)=dilate(src,element)-erode(src,element)
 782
 783 "Top hat":
 784 dst=tophat(src,element)=src-open(src,element)
 785
 786 "Black hat":
 787 dst=blackhat(src,element)=close(src,element)-src
 788 </pre>
 789 <p>
 790 The temporary image <code>temp</code> is required for morphological gradient and, in case of in-place
 791 operation, for "top hat" and "black hat".
 792 </p>
 793
 794
 795 <hr><h2><a name="cv_imgproc_filters">Filters and Color Conversion</a></h2>
 796
 797 <hr><h3><a name="decl_cvSmooth">Smooth</a></h3>
 798 <p class="Blurb">Smoothes the image in one of several ways</p>
 799 <pre>
 800 void cvSmooth( const CvArr* src, CvArr* dst,
 801                int smoothtype=CV_GAUSSIAN,
 802                int size1=3, int size2=0, double sigma1=0, double sigma2=0 );
 803 </pre><p><dl>
 804 <dt>src<dd>The source image.
 805 <dt>dst<dd>The destination image.
 806 <dt>smoothtype<dd>Type of the smoothing operation:<ul>
 807 <li>CV_BLUR_NO_SCALE (simple blur with no scaling) -
 808               for each pixel the result is a sum of pixels values in
 809               <code>size1</code>&times;<code>size2</code> neighborhood of the pixel.
 810               If the neighborhood size varies from pixel to pixel, compute the sums
 811               using integral image (<a href="#decl_cvIntegral">cvIntegral</a>).
 812 <li>CV_BLUR (simple blur) - for each pixel the result is the average value (brightness/color)
 813               of <code>size1</code>&times;<code>size2</code> neighborhood of the pixel.
 814 <li>CV_GAUSSIAN (Gaussian blur) - the image is smoothed using the Gaussian kernel
 815               of aperture size <code>size1</code>&times;<code>size2</code>.
 816               <code>sigma1</code> and <code>sigma2</code> may optionally be
 817               used to specify shape of the kernel.
 818 <li>CV_MEDIAN (median blur) - the image is smoothed using medial filter
 819               of size <code>size1</code>&times;<code>size1</code> (i.e. only square aperture can be used).
 820               That is, for each pixel the result is the median computed
 821               over <code>size1</code>&times;<code>size1</code> neighborhood.
 822 <li>CV_BILATERAL (bilateral filter) -
 823               the image is smoothed using a bilateral 3x3 filter
 824               with color sigma=<code>sigma1</code> and
 825               spatial sigma=<code>sigma2</code>. If <code>size1!=0</code>, then
 826               a circular kernel with diameter <code>size1</code> is used;
 827               otherwise the diameter of the kernel is computed from <code>sigma2</code>.
 828               Information about bilateral filtering
 829               can be found at <a href="http://www.dai.ed.ac.uk/CVonline/LOCAL_COPIES/MANDUCHI1/Bilateral_Filtering.html">
 830               http://www.dai.ed.ac.uk/CVonline/LOCAL_COPIES/MANDUCHI1/Bilateral_Filtering.html</a>
 831 </ul>
 832 <dt>size1<dd>The first parameter of smoothing operation. It should be odd (1, 3, 5, ...),
 833              so that a pixel neighborhood used for smoothing operation is symmetrical
 834              relative to the pixel.
 835 <dt>size2<dd>The second parameter of smoothing operation. In case of simple scaled/non-scaled and
 836              Gaussian blur if <code>size2</code> is zero, it is set to <code>size1</code>.
 837              When not 0, it should be odd too.
 838 <dt>sigma1<dd><p>In case of Gaussian kernel this parameter may specify Gaussian sigma (standard deviation).
 839               If it is zero, it is calculated from the kernel size:<br>
 840               <pre>
 841               sigma = (n/2 - 1)*0.3 + 0.8, where n=param1 for horizontal kernel,
 842                                                  n=param2 for vertical kernel.
 843               </pre>
 844               With the standard sigma for small kernels (3&times;3 to 7&times;7) the performance is better.
 845               If <code>param3</code> is not zero, while <code>param1</code> and <code>param2</code>
 846               are zeros, the kernel size is calculated from the sigma (to provide accurate enough operation).</p>
 847
 848               <p>In case of Bilateral filter the parameter specifies color sigma; the larger the value,
 849               the stronger the pasterization effect of the filter is.</p>
 850 <dt>sigma2<dd><p>In case of non-square Gaussian kernel the parameter may be used to specify a different
 851               (from <code>param3</code>) sigma in the vertical direction.</p>
 852
 853               <p>In case of Bilateral filter the parameter specifies spatial sigma; the larger the value,
 854               the stronger the blurring effect of the filter. Note that with large <code>sigma2</code>
 855               the processing speed decreases substantionally, so it is recommended to limit the kernel
 856               size using the parameter <code>size1</code>.</p>
 857 </dl><p>
 858 The function <code>cvSmooth</code> smoothes image using one of the pre-defined methods. Every of the methods
 859 has some features and restrictions listed below:</p>
 860 <ul>
 861 <li>Blur with no scaling works with single-channel images only and supports accumulation of
 862 8u to 16s format (similar to <a href="#decl_cvSobel">cvSobel</a> and <a href="#decl_cvLaplace">cvLaplace</a>)
 863 and accumulation of 32f to 32f format.</li>
 864 <li>Simple blur and Gaussian blur support 1- or 3-channel, 8-bit, 16-bit and 32-bit floating-point images.
 865 These two methods can process images in-place.</li>
 866 <li>Median filter works with 1- or 3-channel 8-bit images and can not process images in-place.</li>
 867 <li>Bilateral filter works with 1- or 3-channel, 8-bit or 32-bit floating-point images and can not process images in-place.</li>
 868 </ul>
 869
 870 <hr><h3><a name="decl_cvFilter2D">Filter2D</a></h3>
 871 <p class="Blurb">Applies linear filter to image</p>
 872 <pre>
 873 void cvFilter2D( const CvArr* src, CvArr* dst,
 874                  const CvMat* kernel,
 875                  CvPoint anchor=cvPoint(-1,-1));
 876 </pre><p><dl>
 877 <dt>src<dd>The source image.
 878 <dt>dst<dd>The destination image.
 879 <dt>kernel<dd>The filter mask, single-channel 2d floating point matrix of coefficients.
 880               In case of multi-channel images every channel is processed independently
 881               using the same kernel. To process different channels differently,
 882               split the image using
 883               <a href="opencvref_cxcore.htm#decl_cvSplit">cvSplit</a>
 884               and filter the channels one by one.
 885 <dt>anchor<dd>The anchor of the kernel. It is relative position of the filtered pixel
 886 inside its neighborhood covered by the kernel mask. The anchor should be inside the kernel.
 887 The special default value (-1,-1) means that the anchor is at the kernel center.
 888 </ul>
 889 </dl></p><p>
 890 The function <code>cvFilter2D</code> applies the specified linear filter to the image.
 891 In-place operation is supported. When the aperture is partially outside the image,
 892 the function interpolates outlier pixel values from the nearest pixels at the
 893 image boundary. If ROI is set in the input
 894 image, cvFilter2D treats it, similarly to many other OpenCV functions, as if
 895 it were an isolated image, i.e. pixels inside the image but outside of the ROI
 896 are ignored. If it is undesirable, consider new C++ filtering classes declared
 897 in cv.hpp.
 898 </p>
 899
 900
 901 <hr><h3><a name="decl_cvCopyMakeBorder">CopyMakeBorder</a></h3>
 902 <p class="Blurb">Copies image and makes border around it</p>
 903 <pre>
 904 void cvCopyMakeBorder( const CvArr* src, CvArr* dst, CvPoint offset,
 905                        int bordertype, CvScalar value=cvScalarAll(0) );
 906 </pre><p><dl>
 907 <dt>src<dd>The source image.
 908 <dt>dst<dd>The destination image.
 909 <dt>offset<dd>Coordinates of the top-left corner (or bottom-left in case of images with bottom-left origin)
 910               of the destination image rectangle where the source image (or its ROI) is copied.
 911               Size of the rectangle matches the source image size/ROI size.
 912 <dt>bordertype<dd>Type of the border to create around the copied source image rectangle:<br>
 913               <code>IPL_BORDER_CONSTANT</code> -
 914                   border is filled with the fixed value, passed as last parameter of the function.<br>
 915               <code>IPL_BORDER_REPLICATE</code> -
 916                   the pixels from the top and bottom rows, the left-most and right-most columns are replicated
 917                   to fill the border.<br>
 918               (The other two border types from IPL, <code>IPL_BORDER_REFLECT</code> and <code>IPL_BORDER_WRAP</code>,
 919               are currently unsupported).
 920 <dt>value<dd>Value of the border pixels if <code>bordertype=IPL_BORDER_CONSTANT</code>.
 921 </dl></p><p>
 922 The function <code>cvCopyMakeBorder</code> copies the source 2D array into interior of destination array
 923 and makes a border of the specified type around the copied area.
 924 The function is useful when one needs to emulate border type that is different from the one embedded into a specific
 925 algorithm implementation. For example, morphological functions, as well as most of other filtering functions in OpenCV,
 926 internally use replication border type, while the user may need zero border or a border, filled with 1's or 255's.
 927 </p>
 928
 929
 930 <hr><h3><a name="decl_cvIntegral">Integral</a></h3>
 931 <p class="Blurb">Calculates integral images</p>
 932 <pre>
 933 void cvIntegral( const CvArr* image, CvArr* sum, CvArr* sqsum=NULL, CvArr* tilted_sum=NULL );
 934 </pre><p><dl>
 935 <dt>image<dd>The source image, <code>W</code>&times;<code>H</code>, 8-bit or floating-point (32f or 64f) image.
 936 <dt>sum<dd>The integral image, <code>W+1</code>&times;<code>H+1</code>, 32-bit integer or double precision floating-point (64f).
 937 <dt>sqsum<dd>The optional integral image for squared pixel values, <code>W+1</code>&times;<code>H+1</code>, double precision floating-point (64f).
 938 <dt>tilted_sum<dd>The optional integral for the image rotated by 45 degrees, <code>W+1</code>&times;<code>H+1</code>, of the same data type as <code>sum</code>.
 939 </dl><p>
 940 The function <code>cvIntegral</code> calculates one or more integral images for the source image as following:</p>
 941 <pre>
 942 sum(X,Y)=sum<sub>x&lt;X,y&lt;Y</sub>image(x,y)
 943
 944 sqsum(X,Y)=sum<sub>x&lt;X,y&lt;Y</sub>image(x,y)<sup>2</sup>
 945
 946 tilted_sum(X,Y)=sum<sub>y&lt;Y,abs(x-X)&lt;y</sub>image(x,y)
 947 </pre>
 948 <p>Using these integral images, one may calculate sum, mean, standard deviation over
 949 arbitrary up-right or rotated rectangular region of the image in a constant time, for example:</p>
 950 <pre>
 951 sum<sub>x1&lt;=x&lt;x2,y1&lt;=y&lt;y2</sub>image(x,y)=sum(x2,y2)-sum(x1,y2)-sum(x2,y1)+sum(x1,x1)
 952 </pre>
 953 <p>Using integral images it is possible to do variable-size image blurring,
 954 block correlation etc.
 955 In case of multi-channel input images the integral images must have
 956 the same number of channels, and every channel is processed independently.
 957 </p>
 958
 959 <hr><h3><a name="decl_cvCvtColor">CvtColor</a></h3>
 960 <p class="Blurb">Converts image from one color space to another</p>
 961 <pre>
 962 void cvCvtColor( const CvArr* src, CvArr* dst, int code );
 963 </pre><p><dl>
 964 <dt>src<dd>The source 8-bit (8u), 16-bit (16u) or single-precision floating-point (32f) image.
 965 <dt>dst<dd>The destination image of the same data type as the source one.
 966            The number of channels may be different.
 967 <dt>code<dd>Color conversion operation that can be specified using
 968 CV_&lt;src_color_space&gt;2&lt;dst_color_space&gt; constants (see below).
 969 </dl><p>
 970 The function <code>cvCvtColor</code> converts input image from one color space to another.
 971 The function ignores <code>colorModel</code> and <code>channelSeq</code> fields of <code>IplImage</code> header,
 972 so the source image color space should be specified correctly (including order of the channels in case
 973 of RGB space, e.g. BGR means 24-bit format with B<sub>0</sub> G<sub>0</sub> R<sub>0</sub> B<sub>1</sub> G<sub>1</sub> R<sub>1</sub> ... layout,
 974 whereas RGB means 24-bit format with R<sub>0</sub> G<sub>0</sub> B<sub>0</sub> R<sub>1</sub> G<sub>1</sub> B<sub>1</sub> ... layout).
 975 </p><p>
 976 The conventional range for R,G,B channel values is:
 977 <ul>
 978 <li>0..255 for 8-bit images
 979 <li>0..65535 for 16-bit images and
 980 <li>0..1 for floating-point images.
 981 </ul>
 982 Of course, in case of linear transformations the range can be arbitrary,
 983 but in order to get correct results in case of non-linear transformations,
 984 the input image should be scaled if necessary.
 985 </p><p>
 986 The function can do the following transformations:<ul>
 987 <li>Transformations within RGB space like adding/removing alpha channel, reversing the channel order,
 988 conversion to/from 16-bit RGB color (R5:G6:B5 or R5:G5:B5) color, as well as conversion to/from grayscale using:
 989 <pre>
 990 RGB[A]->Gray: Y&lt;-0.299*R + 0.587*G + 0.114*B
 991 Gray->RGB[A]: R&lt;-Y G&lt;-Y B&lt;-Y A&lt;-0
 992 </pre>
 993 <li>RGB&lt;=&gt;CIE XYZ.Rec 709 with D65 white point (<code>CV_BGR2XYZ, CV_RGB2XYZ, CV_XYZ2BGR, CV_XYZ2RGB</code>):
 994 <pre>
 995 |X|    |0.412453  0.357580  0.180423| |R|
 996 |Y| &lt;- |0.212671  0.715160  0.072169|*|G|
 997 |Z|    |0.019334  0.119193  0.950227| |B|
 998
 999 |R|    | 3.240479  -1.53715  -0.498535| |X|
1000 |G| &lt;- |-0.969256   1.875991  0.041556|*|Y|
1001 |B|    | 0.055648  -0.204043  1.057311| |Z|
1002
1003 X, Y and Z cover the whole value range (in case of floating-point images Z may exceed 1).
1004 </pre>
1005 <p></p>
1006 <li>RGB&lt;=&gt;YCrCb JPEG (a.k.a. YCC) (<code>CV_BGR2YCrCb, CV_RGB2YCrCb, CV_YCrCb2BGR, CV_YCrCb2RGB</code>)
1007 <pre>
1008 Y &lt;- 0.299*R + 0.587*G + 0.114*B
1009 Cr &lt;- (R-Y)*0.713 + delta
1010 Cb &lt;- (B-Y)*0.564 + delta
1011
1012 R &lt;- Y + 1.403*(Cr - delta)
1013 G &lt;- Y - 0.344*(Cr - delta) - 0.714*(Cb - delta)
1014 B &lt;- Y + 1.773*(Cb - delta),
1015
1016               { 128 for 8-bit images,
1017 where delta = { 32768 for 16-bit images
1018               { 0.5 for floating-point images
1019
1020 Y, Cr and Cb cover the whole value range.
1021 </pre>
1022 <p></p>
1023 <li>RGB&lt;=&gt;HSV (<code>CV_BGR2HSV, CV_RGB2HSV, CV_HSV2BGR, CV_HSV2RGB</code>)
1024 <pre>
1025 // In case of 8-bit and 16-bit images
1026 // R, G and B are converted to floating-point format and scaled to fit 0..1 range
1027
1028 V &lt;- max(R,G,B)
1029 S &lt;- (V-min(R,G,B))/V   if V&ne;0, 0 otherwise
1030
1031          (G - B)*60/S,  if V=R
1032 H &lt;- 180+(B - R)*60/S,  if V=G
1033      240+(R - G)*60/S,  if V=B
1034
1035 if H&lt;0 then H&lt;-H+360
1036
1037 On output 0&le;V&le;1, 0&le;S&le;1, 0&le;H&le;360.
1038 The values are then converted to the destination data type:
1039     8-bit images:
1040         V &lt;- V*255, S &lt;- S*255, H &lt;- H/2 (to fit to 0..255)
1041     16-bit images (currently not supported):
1042         V &lt;- V*65535, S &lt;- S*65535, H &lt;- H
1043     32-bit images:
1044         H, S, V are left as is
1045 </pre>
1046 <li>RGB&lt;=&gt;HLS (<code>CV_BGR2HLS, CV_RGB2HLS, CV_HLS2BGR, CV_HLS2RGB</code>)
1047 <pre>
1048 // In case of 8-bit and 16-bit images
1049 // R, G and B are converted to floating-point format and scaled to fit 0..1 range
1050
1051 V<sub>max</sub> &lt;- max(R,G,B)
1052 V<sub>min</sub> &lt;- min(R,G,B)
1053
1054 L &lt;- (V<sub>max</sub> + V<sub>min</sub>)/2
1055
1056 S &lt;- (V<sub>max</sub> - V<sub>min</sub>)/(V<sub>max</sub> + V<sub>min</sub>)  if L &lt; 0.5
1057      (V<sub>max</sub> - V<sub>min</sub>)/(2 - (V<sub>max</sub> + V<sub>min</sub>))  if L &ge; 0.5
1058
1059          (G - B)*60/S,  if V<sub>max</sub>=R
1060 H &lt;- 180+(B - R)*60/S,  if V<sub>max</sub>=G
1061      240+(R - G)*60/S,  if V<sub>max</sub>=B
1062
1063 if H&lt;0 then H&lt;-H+360
1064
1065 On output 0&le;L&le;1, 0&le;S&le;1, 0&le;H&le;360.
1066 The values are then converted to the destination data type:
1067     8-bit images:
1068         L &lt;- L*255, S &lt;- S*255, H &lt;- H/2
1069     16-bit images (currently not supported):
1070         L &lt;- L*65535, S &lt;- S*65535, H &lt;- H
1071     32-bit images:
1072         H, L, S are left as is
1073 </pre>
1074 <li>RGB&lt;=&gt;CIE L*a*b* (<code>CV_BGR2Lab, CV_RGB2Lab, CV_Lab2BGR, CV_Lab2RGB</code>)
1075 <pre>
1076 // In case of 8-bit and 16-bit images
1077 // R, G and B are converted to floating-point format and scaled to fit 0..1 range
1078
1079 // convert R,G,B to CIE XYZ
1080 |X|    |0.412453  0.357580  0.180423| |R|
1081 |Y| &lt;- |0.212671  0.715160  0.072169|*|G|
1082 |Z|    |0.019334  0.119193  0.950227| |B|
1083
1084 X &lt;- X/Xn, where Xn = 0.950456
1085 Z &lt;- Z/Zn, where Zn = 1.088754
1086
1087 L &lt;- 116*Y<sup>1/3</sup>      for Y>0.008856
1088 L &lt;- 903.3*Y      for Y&lt;=0.008856
1089
1090 a &lt;- 500*(f(X)-f(Y)) + delta
1091 b &lt;- 200*(f(Y)-f(Z)) + delta
1092 where f(t)=t<sup>1/3</sup>              for t>0.008856
1093       f(t)=7.787*t+16/116   for t&lt;=0.008856
1094
1095
1096 where delta = 128 for 8-bit images,
1097               0 for floating-point images
1098
1099 On output 0&le;L&le;100, -127&le;a&le;127, -127&le;b&le;127
1100 The values are then converted to the destination data type:
1101     8-bit images:
1102         L &lt;- L*255/100, a &lt;- a + 128, b &lt;- b + 128
1103     16-bit images are currently not supported
1104     32-bit images:
1105         L, a, b are left as is
1106 </pre>
1107
1108 <li>RGB&lt;=&gt;CIE L*u*v* (<code>CV_BGR2Luv, CV_RGB2Luv, CV_Luv2BGR, CV_Luv2RGB</code>)
1109 <pre>
1110 // In case of 8-bit and 16-bit images
1111 // R, G and B are converted to floating-point format and scaled to fit 0..1 range
1112
1113 // convert R,G,B to CIE XYZ
1114 |X|    |0.412453  0.357580  0.180423| |R|
1115 |Y| &lt;- |0.212671  0.715160  0.072169|*|G|
1116 |Z|    |0.019334  0.119193  0.950227| |B|
1117
1118 L &lt;- 116*Y<sup>1/3</sup>-16   for Y>0.008856
1119 L &lt;- 903.3*Y      for Y&lt;=0.008856
1120
1121 u' &lt;- 4*X/(X + 15*Y + 3*Z)
1122 v' &lt;- 9*Y/(X + 15*Y + 3*Z)
1123
1124 u &lt;- 13*L*(u' - u<sub>n</sub>), where u<sub>n</sub>=0.19793943
1125 v &lt;- 13*L*(v' - v<sub>n</sub>), where v<sub>n</sub>=0.46831096
1126
1127 On output 0&le;L&le;100, -134&le;u&le;220, -140&le;v&le;122
1128 The values are then converted to the destination data type:
1129     8-bit images:
1130         L &lt;- L*255/100, u &lt;- (u + 134)*255/354, v &lt;- (v + 140)*255/256
1131     16-bit images are currently not supported
1132     32-bit images:
1133         L, u, v are left as is
1134 </pre>
1135
1136 The above formulae for converting RGB to/from various color spaces have been taken
1137 from multiple sources on Web, primarily from <a href="#paper_ford98">Color Space Conversions (<b>[Ford98]</b>)</a>
1138 document at Charles Poynton site.
1139
1140 <p></p>
1141 <li>Bayer=>RGB (<code>CV_BayerBG2BGR, CV_BayerGB2BGR, CV_BayerRG2BGR, CV_BayerGR2BGR,<br>
1142                 CV_BayerBG2RGB, CV_BayerGB2RGB, CV_BayerRG2RGB, CV_BayerGR2RGB</code>)
1143 <p>Bayer pattern is widely used in CCD and CMOS cameras. It allows to get color picture
1144 out of a single plane where R,G and B pixels (sensors of a particular component) are interleaved like
1145 this:</p>
1146 <p>
1147 <table border=0 width=400>
1148 <tr>
1149 <td><font size=5 color="#ff0000"><p align="center">R</font></td>
1150 <td><font size=5 color="#008000"><p align="center">G</font></td>
1151 <td><font size=5 color="#ff0000"><p align="center">R</font></td>
1152 <td><font size=5 color="#008000"><p align="center">G</font></td>
1153 <td><font size=5 color="#ff0000"><p align="center">R</font></td>
1154 </tr><tr>
1155 <td><font size=5 color="#008000"><p align="center">G</font></td>
1156 <td bgcolor="pink"><font size=5 color="#0000ff" ><p align="center">B</font></td>
1157 <td bgcolor="pink"><font size=5 color="#008000" ><p align="center">G</font></td>
1158 <td><font size=5 color="#0000ff"><p align="center">B</font></td>
1159 <td><font size=5 color="#008000"><p align="center">G</font></td>
1160 </tr><tr>
1161 <td><font size=5 color="#ff0000"><p align="center">R</font></td>
1162 <td><font size=5 color="#008000"><p align="center">G</font></td>
1163 <td><font size=5 color="#ff0000"><p align="center">R</font></td>
1164 <td><font size=5 color="#008000"><p align="center">G</font></td>
1165 <td><font size=5 color="#ff0000"><p align="center">R</font></td>
1166 </tr><tr>
1167 <td><font size=5 color="#008000"><p align="center">G</font></td>
1168 <td><font size=5 color="#0000ff"><p align="center">B</font></td>
1169 <td><font size=5 color="#008000"><p align="center">G</font></td>
1170 <td><font size=5 color="#0000ff"><p align="center">B</font></td>
1171 <td><font size=5 color="#008000"><p align="center">G</font></td>
1172 </tr><tr>
1173 <td><font size=5 color="#ff0000"><p align="center">R</font></td>
1174 <td><font size=5 color="#008000"><p align="center">G</font></td>
1175 <td><font size=5 color="#ff0000"><p align="center">R</font></td>
1176 <td><font size=5 color="#008000"><p align="center">G</font></td>
1177 <td><font size=5 color="#ff0000"><p align="center">R</font></td>
1178 </tr><tr>
1179 <td><font size=5 color="#008000"><p align="center">G</font></td>
1180 <td><font size=5 color="#0000ff"><p align="center">B</font></td>
1181 <td><font size=5 color="#008000"><p align="center">G</font></td>
1182 <td><font size=5 color="#0000ff"><p align="center">B</font></td>
1183 <td><font size=5 color="#008000"><p align="center">G</font></td>
1184 </tr>
1185 </table>
1186 </p><p>
1187 The output RGB components of a pixel are interpolated from 1, 2 or 4 neighbors of the pixel
1188 having the same color. There are several modifications of the above pattern that can be achieved
1189 by shifting the pattern one pixel left and/or one pixel up.
1190 The two letters C<sub>1</sub> and C<sub>2</sub> in the conversion constants CV_BayerC<sub>1</sub>C<sub>2</sub>2{BGR|RGB}
1191 indicate the particular pattern type -
1192 these are components from the second row, second and third columns, respectively.
1193 For example, the above pattern has very popular "BG" type.</p>
1194 </ul>
1195 </p>
1196
1197
1198 <hr><h3><a name="decl_cvThreshold">Threshold</a></h3>
1199 <p class="Blurb">Applies fixed-level threshold to array elements</p>
1200 <pre>
1201 double cvThreshold( const CvArr* src, CvArr* dst, double threshold,
1202                     double max_value, int threshold_type );
1203 </pre><p><dl>
1204 <dt>src<dd>Source array (single-channel, 8-bit of 32-bit floating point).
1205 <dt>dst<dd>Destination array; must be either the same type as <code>src</code> or 8-bit.
1206 <dt>threshold<dd>Threshold value.
1207 <dt>max_value<dd>Maximum value to use with <code>CV_THRESH_BINARY</code> and
1208                  <code>CV_THRESH_BINARY_INV</code> thresholding types.
1209 <dt>threshold_type<dd>Thresholding type (see the discussion)
1210 </dl><p>
1211 The function <code>cvThreshold</code> applies fixed-level thresholding to single-channel array.
1212 The function is typically used to get bi-level (binary) image out of grayscale image
1213 (<a href="opencvref_cxcore.htm#decl_cvCmpS">cvCmpS</a>
1214 could be also used for this purpose) or for removing a noise, i.e. filtering out pixels with too small or too large values.
1215 There are several types of thresholding the function supports that are determined by <code>threshold_type</code>:</p>
1216 <pre>
1217 threshold_type=CV_THRESH_BINARY:
1218 dst(x,y) = max_value, if src(x,y)&gt;threshold
1219            0, otherwise
1220
1221 threshold_type=CV_THRESH_BINARY_INV:
1222 dst(x,y) = 0, if src(x,y)&gt;threshold
1223            max_value, otherwise
1224
1225 threshold_type=CV_THRESH_TRUNC:
1226 dst(x,y) = threshold, if src(x,y)&gt;threshold
1227            src(x,y), otherwise
1228
1229 threshold_type=CV_THRESH_TOZERO:
1230 dst(x,y) = src(x,y), if src(x,y)&gt;threshold
1231            0, otherwise
1232
1233 threshold_type=CV_THRESH_TOZERO_INV:
1234 dst(x,y) = 0, if src(x,y)&gt;threshold
1235            src(x,y), otherwise
1236 </pre>
1237 <p>And this is the visual description of thresholding types:</p>
1238 <p>
1239 <image align="center" src="pics/threshold.png">
1240 </p>
1241 Also, the special value <code>CV_THRESH_OTSU</code> may be combined with
1242 one of the above values. In this case the function determines the optimal threshold
1243 value using Otsu algorithm and uses it instead of the specified <code>thresh</code>.
1244 The function returns the computed threshold value.
1245 Currently, Otsu method is implemented only for 8-bit images.
1246 </p>
1247
1248 <hr><h3><a name="decl_cvAdaptiveThreshold">AdaptiveThreshold</a></h3>
1249 <p class="Blurb">Applies adaptive threshold to array</p>
1250 <pre>
1251 void cvAdaptiveThreshold( const CvArr* src, CvArr* dst, double max_value,
1252                           int adaptive_method=CV_ADAPTIVE_THRESH_MEAN_C,
1253                           int threshold_type=CV_THRESH_BINARY,
1254                           int block_size=3, double param1=5 );
1255 </pre><p><dl>
1256 <dt>src<dd>Source image.
1257 <dt>dst<dd>Destination image.
1258 <dt>max_value<dd>Maximum value that is used with <code>CV_THRESH_BINARY</code> and <code>CV_THRESH_BINARY_INV</code>.
1259 <dt>adaptive_method<dd>Adaptive thresholding algorithm to use: <code>CV_ADAPTIVE_THRESH_MEAN_C</code>
1260 or <code>CV_ADAPTIVE_THRESH_GAUSSIAN_C</code> (see the discussion).
1261 <dt>threshold_type<dd>Thresholding type; must be one of
1262 <ul>
1263 <li><code>CV_THRESH_BINARY,</code>
1264 <li><code>CV_THRESH_BINARY_INV</code>
1265 </ul>
1266 <dt>block_size<dd>The size of a pixel neighborhood that is used to calculate a threshold value for the pixel:
1267 3, 5, 7, ...
1268 <dt>param1<dd>The method-dependent parameter.
1269 For the methods <code>CV_ADAPTIVE_THRESH_MEAN_C</code> and <code>CV_ADAPTIVE_THRESH_GAUSSIAN_C</code>
1270 it is a constant subtracted from mean or weighted mean (see the discussion), though it may be negative.
1271 </dl><p>
1272 The function <code>cvAdaptiveThreshold</code> transforms grayscale image to binary image according to
1273 the formulae:</p>
1274 <pre>
1275 threshold_type=<code>CV_THRESH_BINARY</code>:
1276 dst(x,y) = max_value, if src(x,y)&gt;T(x,y)
1277            0, otherwise
1278
1279 threshold_type=<code>CV_THRESH_BINARY_INV</code>:
1280 dst(x,y) = 0, if src(x,y)&gt;T(x,y)
1281            max_value, otherwise
1282 </pre>
1283 <p>where T<sub>I</sub> is a threshold calculated individually for each pixel.</p>
1284 <p>
1285 For the method <code>CV_ADAPTIVE_THRESH_MEAN_C</code> it is a mean of <code>block_size</code> &times; <code>block_size</code>
1286 pixel neighborhood, subtracted by <code>param1</code>.</p><p>
1287 For the method <code>CV_ADAPTIVE_THRESH_GAUSSIAN_C</code> it is a weighted sum (Gaussian) of
1288 <code>block_size</code> &times; <code>block_size</code> pixel neighborhood, subtracted by <code>param1</code>.</p>
1289
1290
1291 <hr><h2><a name="cv_imgproc_pyramids">Pyramids and the Applications</a></h2>
1292
1293 <hr><h3><a name="decl_cvPyrDown">PyrDown</a></h3>
1294 <p class="Blurb">Downsamples image</p>
1295 <pre>
1296 void cvPyrDown( const CvArr* src, CvArr* dst, int filter=CV_GAUSSIAN_5x5 );
1297 </pre><p><dl>
1298 <dt>src<dd>The source image.
1299 <dt>dst<dd>The destination image, should have 2x smaller width and height than the source.
1300 <dt>filter<dd>Type of the filter used for convolution; only <code>CV_GAUSSIAN_5x5</code> is
1301 currently supported.
1302 </dl><p>
1303 The function <code>cvPyrDown</code> performs downsampling step of Gaussian pyramid
1304 decomposition. First it convolves source image with the specified filter and
1305 then downsamples the image by rejecting even rows and columns.</p>
1306
1307
1308 <hr><h3><a name="decl_cvPyrUp">PyrUp</a></h3>
1309 <p class="Blurb">Upsamples image</p>
1310 <pre>
1311 void cvPyrUp( const CvArr* src, CvArr* dst, int filter=CV_GAUSSIAN_5x5 );
1312 </pre><p><dl>
1313 <dt>src<dd>The source image.
1314 <dt>dst<dd>The destination image, should have 2x smaller width and height than the source.
1315 <dt>filter<dd>Type of the filter used for convolution; only <code>CV_GAUSSIAN_5x5</code> is
1316 currently supported.
1317 </dl><p>
1318 The function <code>cvPyrUp</code> performs up-sampling step of Gaussian pyramid decomposition.
1319 First it upsamples the source image by injecting even zero rows and columns and
1320 then convolves result with the specified filter multiplied by 4 for
1321 interpolation. So the destination image is four times larger than the source
1322 image.</p>
1323
1324 <hr><h2><a name="cv_imgproc_ccomp">Image Segmentation, Connected Components and Contour Retrieval</a></h2>
1325
1326 <hr><h3><a name="decl_CvConnectedComp">CvConnectedComp</a></h3>
1327 <p class="Blurb">Connected component</p>
1328 <pre>
1329     typedef struct CvConnectedComp
1330     {
1331         double area; /* area of the segmented component */
1332         float value; /* gray scale value of the segmented component */
1333         CvRect rect; /* ROI of the segmented component */
1334     } CvConnectedComp;
1335 </pre>
1336
1337
1338 <hr><h3><a name="decl_cvFloodFill">FloodFill</a></h3>
1339 <p class="Blurb">Fills a connected component with given color</p>
1340 <pre>
1341 void cvFloodFill( CvArr* image, CvPoint seed_point, CvScalar new_val,
1342                   CvScalar lo_diff=cvScalarAll(0), CvScalar up_diff=cvScalarAll(0),
1343                   CvConnectedComp* comp=NULL, int flags=4, CvArr* mask=NULL );
1344 #define CV_FLOODFILL_FIXED_RANGE (1 &lt;&lt; 16)
1345 #define CV_FLOODFILL_MASK_ONLY   (1 &lt;&lt; 17)
1346 </pre><p><dl>
1347 <dt>image<dd>Input 1- or 3-channel, 8-bit or floating-point image.
1348              It is modified by the function unless CV_FLOODFILL_MASK_ONLY flag is set (see below).
1349 <dt>seed_point<dd>The starting point.
1350 <dt>new_val<dd>New value of repainted domain pixels.
1351 <dt>lo_diff<dd>Maximal lower brightness/color difference between the currently observed pixel and one of its
1352 neighbor belong to the component or seed pixel to add the pixel to component.
1353 In case of 8-bit color images it is packed value.
1354 <dt>up_diff<dd>Maximal upper brightness/color difference between the currently observed pixel and one of its
1355 neighbor belong to the component or seed pixel to add the pixel to component.
1356 In case of 8-bit color images it is packed value.
1357 <dt>comp<dd>Pointer to structure the function fills with the information about the
1358 repainted domain.
1359 <dt>flags<dd>The operation flags. Lower bits contain connectivity value, 4 (by default) or 8,
1360 used within the function. Connectivity determines which neighbors of a pixel are considered.
1361 Upper bits can be 0 or combination of the following flags:<ul>
1362 <li>CV_FLOODFILL_FIXED_RANGE - if set the difference between the current pixel and seed pixel is considered,
1363                                otherwise difference between neighbor pixels is considered (the range is floating).
1364 <li>CV_FLOODFILL_MASK_ONLY - if set, the function does not fill the image (<code>new_val</code> is ignored),
1365 but the fills mask (that must be non-NULL in this case).
1366 </ul>
1367 <dt>mask<dd>Operation mask, should be singe-channel 8-bit image, 2 pixels wider and 2 pixels taller than
1368 <code>image</code>. If not NULL, the function uses and updates the mask, so user takes responsibility of
1369 initializing <code>mask</code> content. Floodfilling can't go across
1370 non-zero pixels in the mask, for example, an edge detector output can be used as a mask
1371 to stop filling at edges. Or it is possible to use the same mask in multiple calls to the function
1372 to make sure the filled area do not overlap. <em>Note</em>: because mask is larger than the filled image,
1373 pixel in <code>mask</code> that corresponds to <code>(x,y)</code> pixel in <code>image</code>
1374 will have coordinates <code>(x+1,y+1)</code>.
1375 </dl><p>
1376 The function <code>cvFloodFill</code> fills a connected component starting from the seed point
1377 with the specified color. The connectivity is determined by the closeness of pixel values.
1378 The pixel at <code>(x, y)</code> is considered to belong to the repainted domain if:</p>
1379 <pre>
1380 src(x',y')-lo_diff&lt;=src(x,y)&lt;=src(x',y')+up_diff,     grayscale image, floating range
1381 src(seed.x,seed.y)-lo&lt;=src(x,y)&lt;=src(seed.x,seed.y)+up_diff, grayscale image, fixed range
1382
1383 src(x',y')<sub>r</sub>-lo_diff<sub>r</sub>&lt;=src(x,y)<sub>r</sub>&lt;=src(x',y')<sub>r</sub>+up_diff<sub>r</sub> and
1384 src(x',y')<sub>g</sub>-lo_diff<sub>g</sub>&lt;=src(x,y)<sub>g</sub>&lt;=src(x',y')<sub>g</sub>+up_diff<sub>g</sub> and
1385 src(x',y')<sub>b</sub>-lo_diff<sub>b</sub>&lt;=src(x,y)<sub>b</sub>&lt;=src(x',y')<sub>b</sub>+up_diff<sub>b</sub>, color image, floating range
1386
1387 src(seed.x,seed.y)<sub>r</sub>-lo_diff<sub>r</sub>&lt;=src(x,y)<sub>r</sub>&lt;=src(seed.x,seed.y)<sub>r</sub>+up_diff<sub>r</sub> and
1388 src(seed.x,seed.y)<sub>g</sub>-lo_diff<sub>g</sub>&lt;=src(x,y)<sub>g</sub>&lt;=src(seed.x,seed.y)<sub>g</sub>+up_diff<sub>g</sub> and
1389 src(seed.x,seed.y)<sub>b</sub>-lo_diff<sub>b</sub>&lt;=src(x,y)<sub>b</sub>&lt;=src(seed.x,seed.y)<sub>b</sub>+up_diff<sub>b</sub>, color image, fixed range
1390 </pre>
1391 where <code>src(x',y')</code> is value of one of pixel neighbors.
1392 That is, to be added to the connected component, a pixel&#146;s color/brightness should be close enough to:
1393 <ul>
1394 <li>color/brightness of one of its neighbors that are already referred to the connected
1395 component in case of floating range
1396 <li>color/brightness of the seed point in case of fixed range.
1397 </ul>
1398 </p>
1399
1400
1401 <hr><h3><a name="decl_cvFindContours">FindContours</a></h3>
1402 <p class="Blurb">Finds contours in binary image</p>
1403 <pre>
1404 int cvFindContours( CvArr* image, CvMemStorage* storage, CvSeq** first_contour,
1405                     int header_size=sizeof(CvContour), int mode=CV_RETR_LIST,
1406                     int method=CV_CHAIN_APPROX_SIMPLE, CvPoint offset=cvPoint(0,0) );
1407 </pre><p><dl>
1408 <dt>image<dd>The source 8-bit single channel image. Non-zero pixels are treated as
1409 1&#146;s, zero pixels remain 0&#146;s - that is image treated as <code>binary</code>. To get such a binary image
1410 from grayscale, one may use <a href="#decl_cvThreshold">cvThreshold</a>, <a href="#decl_cvAdaptiveThreshold">cvAdaptiveThreshold</a> or <a href="#decl_cvCanny">cvCanny</a>.
1411 The function modifies the source image content.
1412 <dt>storage<dd>Container of the retrieved contours.
1413 <dt>first_contour<dd>Output parameter, will contain the pointer to the first outer contour.
1414 <dt>header_size<dd>Size of the sequence header, &gt;=sizeof(<a href="#decl_CvChain">CvChain</a>) if <code>method</code>=CV_CHAIN_CODE,
1415                   and &gt;=sizeof(CvContour) otherwise.
1416 <dt>mode<dd>Retrieval mode.
1417 <ul>
1418 <li><code>CV_RETR_EXTERNAL</code> - retrieve only the extreme outer contours
1419 <li><code>CV_RETR_LIST</code> - retrieve all the contours and puts them in the list
1420 <li><code>CV_RETR_CCOMP</code> - retrieve all the contours and organizes them into two-level hierarchy:
1421                           top level are external boundaries of the components, second level are
1422                           boundaries of the holes
1423 <li><code>CV_RETR_TREE</code> - retrieve all the contours and reconstructs the full hierarchy of
1424                          nested contours
1425 </ul>
1426 <dt>method<dd>Approximation method (for all the modes, except <code>CV_RETR_RUNS</code>, which uses
1427 built-in approximation).
1428 <ul>
1429 <li><code>CV_CHAIN_CODE</code> - output contours in the Freeman chain code. All other methods output polygons
1430      (sequences of vertices).
1431 <li><code>CV_CHAIN_APPROX_NONE</code> - translate all the points from the chain code into
1432   points;
1433 <li><code>CV_CHAIN_APPROX_SIMPLE</code> - compress horizontal, vertical, and diagonal segments,
1434   that is, the function leaves only their ending points;
1435 <li><code>CV_CHAIN_APPROX_TC89_L1,<div>CV_CHAIN_APPROX_TC89_KCOS</code> - apply one of the flavors of
1436   Teh-Chin chain approximation algorithm.
1437 <li><code>CV_LINK_RUNS</code> - use completely different contour retrieval algorithm via
1438 linking of horizontal segments of 1&#146;s. Only <code>CV_RETR_LIST</code> retrieval mode can be used
1439 with this method.
1440 </ul>
1441 <dt>offset<dd>Offset, by which every contour point is shifted. This is useful if the contours are extracted from
1442 the image ROI and then they should be analyzed in the whole image context.
1443 </dl><p>
1444 The function <code>cvFindContours</code> retrieves contours from the binary image and returns
1445 the number of retrieved contours. The pointer <code>first_contour</code> is filled by the function.
1446 It will contain pointer to the first most outer contour or NULL if no contours is detected (if the image is completely black).
1447 Other contours may be reached from <code>first_contour</code> using <code>h_next</code> and <code>v_next</code> links.
1448 The sample in <a href="#decl_cvDrawContours">cvDrawContours</a> discussion shows how to use contours for connected component
1449 detection. Contours can be also used for shape analysis and object recognition - see <code>squares.c</code>
1450 in OpenCV sample directory.</p>
1451
1452
1453 <hr><h3><a name="decl_cvStartFindContours">StartFindContours</a></h3>
1454 <p class="Blurb">Initializes contour scanning process</p>
1455 <pre>
1456 CvContourScanner cvStartFindContours( CvArr* image, CvMemStorage* storage,
1457                                       int header_size=sizeof(CvContour),
1458                                       int mode=CV_RETR_LIST,
1459                                       int method=CV_CHAIN_APPROX_SIMPLE,
1460                                       CvPoint offset=cvPoint(0,0) );
1461 </pre><p><dl>
1462 <dt>image<dd>The source 8-bit single channel binary image.
1463 <dt>storage<dd>Container of the retrieved contours.
1464 <dt>header_size<dd>Size of the sequence header, &gt;=sizeof(<a href="#decl_CvChain">CvChain</a>) if <code>method</code>=CV_CHAIN_CODE,
1465                   and &gt;=sizeof(CvContour) otherwise.
1466 <dt>mode<dd>Retrieval mode; see <a href="#decl_cvFindContours">cvFindContours</a>.
1467 <dt>method<dd>Approximation method. It has the same meaning as in <a href="#decl_cvFindContours">cvFindContours</a>,
1468 but CV_LINK_RUNS can not be used here.
1469 <dt>offset<dd>ROI offset; see <a href="#decl_cvFindContours">cvFindContours</a>.
1470 </ul>
1471 </dl><p>
1472 The function <code>cvStartFindContours</code> initializes and returns pointer to the contour
1473 scanner. The scanner is used further in <a href="#decl_cvFindNextContour">cvFindNextContour</a> to retrieve the rest of contours.
1474 </p>
1475
1476
1477 <hr><h3><a name="decl_cvFindNextContour">FindNextContour</a></h3>
1478 <p class="Blurb">Finds next contour in the image</p>
1479 <pre>
1480 CvSeq* cvFindNextContour( CvContourScanner scanner );
1481 </pre><p><dl>
1482 <dt>scanner<dd>Contour scanner initialized by The function <code>cvStartFindContours</code> .
1483 </dl><p>
1484 The function <code>cvFindNextContour</code> locates and retrieves the next contour in the image and
1485 returns pointer to it. The function returns NULL, if there is no more contours.</p>
1486
1487
1488 <hr><h3><a name="decl_cvSubstituteContour">SubstituteContour</a></h3>
1489 <p class="Blurb">Replaces retrieved contour</p>
1490 <pre>
1491 void cvSubstituteContour( CvContourScanner scanner, CvSeq* new_contour );
1492 </pre><p><dl>
1493 <dt>scanner<dd>Contour scanner initialized by the function cvStartFindContours .
1494 <dt>new_contour<dd>Substituting contour.
1495 </dl><p>
1496 The function <code>cvSubstituteContour</code> replaces the retrieved contour, that was returned
1497 from the preceding call of The function <code>cvFindNextContour</code> and stored inside
1498 the contour scanner state, with the user-specified contour. The contour is
1499 inserted into the resulting structure, list, two-level hierarchy, or tree,
1500 depending on the retrieval mode. If the parameter <code>new_contour</code>=NULL, the retrieved
1501 contour is not included into the resulting structure, nor all of its children
1502 that might be added to this structure later.
1503 </p>
1504
1505
1506 <hr><h3><a name="decl_cvEndFindContours">EndFindContours</a></h3>
1507 <p class="Blurb">Finishes scanning process</p>
1508 <pre>
1509 CvSeq* cvEndFindContours( CvContourScanner* scanner );
1510 </pre><p><dl>
1511 <dt>scanner<dd>Pointer to the contour scanner.
1512 </dl><p>
1513 The function <code>cvEndFindContours</code> finishes the scanning process and returns the
1514 pointer to the first contour on the highest level.</p>
1515
1516
1517 <hr><h3><a name="decl_cvPyrSegmentation">PyrSegmentation</a></h3>
1518 <p class="Blurb">Does image segmentation by pyramids</p>
1519 <pre>
1520 void cvPyrSegmentation( IplImage* src, IplImage* dst,
1521                         CvMemStorage* storage, CvSeq** comp,
1522                         int level, double threshold1, double threshold2 );
1523 </pre><p><dl>
1524 <dt>src<dd>The source image.
1525 <dt>dst<dd>The destination image.
1526 <dt>storage<dd>Storage; stores the resulting sequence of connected components.
1527 <dt>comp<dd>Pointer to the output sequence of the segmented components.
1528 <dt>level<dd>Maximum level of the pyramid for the segmentation.
1529 <dt>threshold1<dd>Error threshold for establishing the links.
1530 <dt>threshold2<dd>Error threshold for the segments clustering.
1531 </dl><p>
1532 The function <code>cvPyrSegmentation</code> implements image segmentation by pyramids. The
1533 pyramid builds up to the level <code>level</code>. The links between any pixel <code>a</code> on level <code>i</code>
1534 and its candidate father pixel <code>b</code> on the adjacent level are established if
1535 <div> <code>p(c(a),c(b))&lt;threshold1</code>.
1536 After the connected components are defined, they are joined into several
1537 clusters. Any two segments A and B belong to the same cluster, if
1538 <div> <code>p(c(A),c(B))&lt;threshold2</code>. The input
1539 image has only one channel, then
1540 <div><code> p(c&sup1;,c&sup2;)=|c&sup1;-c&sup2;|</code>. If the input image has three channels (red,
1541 green and blue), then
1542 <div><code>p(c&sup1;,c&sup2;)=0,3&middot;(c&sup1;<sub>r</sub>-c&sup2;<sub>r</sub>)+0,59&middot;(c&sup1;<sub>g</sub>-c&sup2;<sub>g</sub>)+0,11&middot;(c&sup1;<sub>b</sub>-c&sup2;<sub>b</sub>) </code> .
1543 There may be more than one connected component per a  cluster.
1544 <div>The images <code>src</code> and <code>dst</code> should be 8-bit single-channel or 3-channel images
1545 or equal size</p>
1546
1547
1548 <hr><h3><a name="decl_cvPyrMeanShiftFiltering">PyrMeanShiftFiltering</a></h3>
1549 <p class="Blurb">Does MeanShift image segmentation</p>
1550 <pre>
1551 void cvPyrMeanShiftFiltering( const CvArr* src, CvArr* dst,
1552      double sp, double sr, int max_level=1,
1553      CvTermCriteria termcrit=cvTermCriteria(CV_TERMCRIT_ITER+CV_TERMCRIT_EPS,5,1));
1554 </pre><p><dl>
1555 <dt>src<dd>The source 8-bit 3-channel image.
1556 <dt>dst<dd>The destination image of the same format and the same size as the source.
1557 <dt>sp<dd>The spatial window radius.
1558 <dt>sr<dd>The color window radius.
1559 <dt>max_level<dd>Maximum level of the pyramid for the segmentation.
1560 <dt>termcrit<dd>Termination criteria: when to stop meanshift iterations.
1561 </dl><p>
1562 The function <code>cvPyrMeanShiftFiltering</code> implements the filtering stage of meanshift
1563 segmentation, that is, the output of the function is the filtered "posterized" image with
1564 color gradients and fine-grain texture flattened. At every pixel <code>(X,Y)</code> of the
1565 input image (or down-sized input image, see below) the function executes meanshift iterations,
1566 that is, the pixel <code>(X,Y)</code> neighborhood in the joint space-color
1567 hyper-space is considered:
1568 <pre>{(x,y): X-sp&le;x&le;X+sp && Y-sp&le;y&le;Y+sp && ||(R,G,B)-(r,g,b)|| &le; sr},</pre>
1569 where <code>(R,G,B)</code> and <code>(r,g,b)</code> are the vectors of color components
1570 at <code>(X,Y)</code> and <code>(x,y)</code>, respectively (though, the algorithm does not depend
1571 on the color space used, so any 3-component color space can be used instead).
1572 Over the neighborhood the average spatial value <code>(X',Y')</code> and average color vector
1573 <code>(R',G',B')</code> are found and they act as the neighborhood center on the next iteration:
1574 <pre>(X,Y)~(X',Y'), (R,G,B)~(R',G',B').</pre>
1575 After the iterations over, the color components of the initial pixel
1576 (that is, the pixel from where the iterations started)
1577 are set to the final value (average color at the last iteration):
1578 <pre>I(X,Y) &lt;- (R*,G*,B*).</pre>
1579
1580 <p>Then <code>max_level</code>&gt;0, the Gaussian pyramid of <code>max_level</code>+1 levels is built,
1581 and the above procedure is run on the smallest layer. After that, the results are propagated to the
1582 larger layer and the iterations are run again only on those pixels where the layer colors
1583 differ much (&gt;<code>sr</code>) from the lower-resolution layer, that is,
1584 the boundaries of the color regions are clarified. Note, that the results
1585 will be actually different from the ones obtained by running the meanshift procedure
1586 on the whole original image (i.e. when <code>max_level</code>==0).</p>
1587
1588
1589 <hr><h3><a name="decl_cvWatershed">Watershed</a></h3>
1590 <p class="Blurb">Does watershed segmentation</p>
1591 <pre>
1592 void cvWatershed( const CvArr* image, CvArr* markers );
1593 </pre><p><dl>
1594 <dt>image<dd>The input 8-bit 3-channel image.
1595 <dt>markers<dd>The input/output 32-bit single-channel image (map) of markers.
1596 </dl><p>
1597 The function <code>cvWatershed</code> implements one of the variants of watershed,
1598 non-parametric marker-based segmentation algorithm, described in <a href="#paper_meyer92">[Meyer92]</a>
1599 Before passing the image to the function, user has to outline roughly the desired regions
1600 in the image <code>markers</code> with positive (&gt;0) indices, i.e. every region is represented as one or more
1601 connected components with the pixel values 1, 2, 3 etc. Those components will be "seeds" of the
1602 future image regions.
1603 All the other pixels in <code>markers</code>, which relation to the outlined regions is not known
1604 and should be defined by the algorithm, should be set to 0's. On the output of the function,
1605 each pixel in <code>markers</code> is set to one of values of the "seed" components, or to -1
1606 at boundaries between the regions.</p><p>Note, that it is not necessary that every
1607 two neighbor connected components
1608 are separated by a watershed boundary (-1's pixels), for example, in case when such tangent components
1609 exist in the initial marker image. Visual demonstration and usage example of the function can be
1610 found in OpenCV samples directory; see <code>watershed.cpp</code> demo.</p>
1611
1612 <hr><h2><a name="cv_imgproc_moments">Image and Contour moments</a></h2>
1613
1614 <hr><h3><a name="decl_cvMoments">Moments</a></h3>
1615 <p class="Blurb">Calculates all moments up to third order of a polygon or rasterized shape</p>
1616 <pre>
1617 void cvMoments( const CvArr* arr, CvMoments* moments, int binary=0 );
1618 </pre><p><dl>
1619 <dt>arr<dd>Image (1-channel or 3-channel with COI set)
1620            or polygon (CvSeq of points or a vector of points).
1621 <dt>moments<dd>Pointer to returned moment state structure.
1622 <dt>binary<dd>(For images only) If the flag is non-zero, all the zero pixel values are treated as
1623 zeroes, all the others are treated as 1&#146;s.
1624 </dl><p>
1625 The function <code>cvMoments</code> calculates spatial and central moments up to the third order and
1626 writes them to <code>moments</code>. The moments may be used then to calculate gravity center of the shape,
1627 its area, main axises and various shape characteristics including 7 Hu invariants.</p>
1628
1629
1630 <hr><h3><a name="decl_cvGetSpatialMoment">GetSpatialMoment</a></h3>
1631 <p class="Blurb">Retrieves spatial moment from moment state structure</p>
1632 <pre>
1633 double cvGetSpatialMoment( CvMoments* moments, int x_order, int y_order );
1634 </pre><p><dl>
1635 <dt>moments<dd>The moment state, calculated by <a href="#decl_cvMoments">cvMoments</a>.
1636 <dt>x_order<dd>x order of the retrieved moment, <code>x_order</code> &gt;= 0.
1637 <dt>y_order<dd>y order of the retrieved moment,
1638                  <code>y_order</code> &gt;= 0 and <code>x_order</code> + <code>y_order</code> &lt;= 3.
1639 </dl><p>
1640 The function <code>cvGetSpatialMoment</code> retrieves the spatial moment, which in case of
1641 image moments is defined as:</p>
1642 <pre>
1643 M<sub>x_order,y_order</sub>=sum<sub>x,y</sub>(I(x,y)&bull;x<sup>x_order</sup>&bull;y<sup>y_order</sup>)
1644 </pre>
1645 <p>where <code>I(x,y)</code> is the intensity of the pixel <code>(x, y)</code>.
1646
1647
1648 <hr><h3><a name="decl_cvGetCentralMoment">GetCentralMoment</a></h3>
1649 <p class="Blurb">Retrieves central moment from moment state structure</p>
1650 <pre>
1651 double cvGetCentralMoment( CvMoments* moments, int x_order, int y_order );
1652 </pre><p><dl>
1653 <dt>moments<dd>Pointer to the moment state structure.
1654 <dt>x_order<dd>x order of the retrieved moment, <code>x_order</code> &gt;= 0.
1655 <dt>y_order<dd>y order of the retrieved moment,
1656                  <code>y_order</code> &gt;= 0 and <code>x_order</code> + <code>y_order</code> &lt;= 3.
1657 </dl><p>
1658 The function <code>cvGetCentralMoment</code> retrieves the central moment, which in case of
1659 image moments is defined as:</p>
1660 <pre>
1661 &mu;<sub>x_order,y_order</sub>=sum<sub>x,y</sub>(I(x,y)&bull;(x-x<sub>c</sub>)<sup>x_order</sup>&bull;(y-y<sub>c</sub>)<sup>y_order</sup>),
1662 </pre>
1663 <p>where <code>x<sub>c</sub>=M<sub>10</sub>/M<sub>00</sub>, y<sub>c</sub>=M<sub>01</sub>/M<sub>00</sub></code> - coordinates of the gravity center</p>
1664
1665
1666
1667 <hr><h3><a name="decl_cvGetNormalizedCentralMoment">GetNormalizedCentralMoment</a></h3>
1668 <p class="Blurb">Retrieves normalized central moment from moment state structure</p>
1669 <pre>
1670 double cvGetNormalizedCentralMoment( CvMoments* moments, int x_order, int y_order );
1671 </pre><p><dl>
1672 <dt>moments<dd>Pointer to the moment state structure.
1673 <dt>x_order<dd>x order of the retrieved moment, <code>x_order</code> &gt;= 0.
1674 <dt>y_order<dd>y order of the retrieved moment,
1675                  <code>y_order</code> &gt;= 0 and <code>x_order</code> + <code>y_order</code> &lt;= 3.
1676 </dl><p>
1677 The function <code>cvGetNormalizedCentralMoment</code>
1678 retrieves the normalized central moment:</p>
1679 <pre>
1680 &eta;<sub>x_order,y_order</sub>= &mu;<sub>x_order,y_order</sub>/M<sub>00</sub><sup>((y_order+x_order)/2+1)</sup>
1681 </pre>
1682
1683
1684 <hr><h3><a name="decl_cvGetHuMoments">GetHuMoments</a></h3>
1685 <p class="Blurb">Calculates seven Hu invariants</p>
1686 <pre>
1687 void cvGetHuMoments( CvMoments* moments, CvHuMoments* hu_moments );
1688 </pre><p><dl>
1689 <dt>moments<dd>Pointer to the moment state structure.
1690 <dt>hu_moments<dd>Pointer to Hu moments structure.
1691 </dl><p>
1692 The function <code>cvGetHuMoments</code> calculates seven Hu invariants that are defined as:
1693 <pre>
1694  h<sub>1</sub>=&eta;<sub>20</sub>+&eta;<sub>02</sub>
1695
1696  h<sub>2</sub>=(&eta;<sub>20</sub>-&eta;<sub>02</sub>)&sup2;+4&eta;<sub>11</sub>&sup2;
1697
1698  h<sub>3</sub>=(&eta;<sub>30</sub>-3&eta;<sub>12</sub>)&sup2;+ (3&eta;<sub>21</sub>-&eta;<sub>03</sub>)&sup2;
1699
1700  h<sub>4</sub>=(&eta;<sub>30</sub>+&eta;<sub>12</sub>)&sup2;+ (&eta;<sub>21</sub>+&eta;<sub>03</sub>)&sup2;
1701
1702  h<sub>5</sub>=(&eta;<sub>30</sub>-3&eta;<sub>12</sub>)(&eta;<sub>30</sub>+&eta;<sub>12</sub>)[(&eta;<sub>30</sub>+&eta;<sub>12</sub>)&sup2;-3(&eta;<sub>21</sub>+&eta;<sub>03</sub>)&sup2;]+(3&eta;<sub>21</sub>-&eta;<sub>03</sub>)(&eta;<sub>21</sub>+&eta;<sub>03</sub>)[3(&eta;<sub>30</sub>+&eta;<sub>12</sub>)&sup2;-(&eta;<sub>21</sub>+&eta;<sub>03</sub>)&sup2;]
1703
1704  h<sub>6</sub>=(&eta;<sub>20</sub>-&eta;<sub>02</sub>)[(&eta;<sub>30</sub>+&eta;<sub>12</sub>)&sup2;- (&eta;<sub>21</sub>+&eta;<sub>03</sub>)&sup2;]+4&eta;<sub>11</sub>(&eta;<sub>30</sub>+&eta;<sub>12</sub>)(&eta;<sub>21</sub>+&eta;<sub>03</sub>)
1705
1706  h<sub>7</sub>=(3&eta;<sub>21</sub>-&eta;<sub>03</sub>)(&eta;<sub>21</sub>+&eta;<sub>03</sub>)[3(&eta;<sub>30</sub>+&eta;<sub>12</sub>)&sup2;-(&eta;<sub>21</sub>+&eta;<sub>03</sub>)&sup2;]-(&eta;<sub>30</sub>-3&eta;<sub>12</sub>)(&eta;<sub>21</sub>+&eta;<sub>03</sub>)[3(&eta;<sub>30</sub>+&eta;<sub>12</sub>)&sup2;-(&eta;<sub>21</sub>+&eta;<sub>03</sub>)&sup2;]
1707 </pre>
1708 <p>
1709 where <code>&eta;<sub>i,j</sub></code> are normalized central moments of
1710 2-nd and 3-rd orders.
1711 The computed values are proved to be invariant to the image scaling, rotation, and
1712 reflection except the seventh one, whose sign is changed by reflection.
1713 </p>
1714
1715
1716 <hr><h2><a name="cv_imgproc_special">Special Image Transforms</a></h2>
1717
1718 <hr><h3><a name="decl_cvHoughLines2">HoughLines2</a></h3>
1719 <p class="Blurb">Finds lines in binary image using Hough transform</p>
1720 <pre>
1721 CvSeq* cvHoughLines2( CvArr* image, void* line_storage, int method,
1722                       double rho, double theta, int threshold,
1723                       double param1=0, double param2=0 );
1724 </pre><p><dl>
1725 <dt>image<dd>The input 8-bit single-channel binary image. In case of probabilistic method the image is
1726              modified by the function.
1727 <dt>line_storage<dd>The storage for the lines detected. It can be a memory storage (in this case
1728 a sequence of lines is created in the storage and returned by the function) or single row/single column
1729 matrix (CvMat*) of a particular type (see below) to which the lines' parameters are written.
1730 The matrix header is modified by the function so its <code>cols</code> or <code>rows</code> will contain
1731 a number of lines detected. If <code>line_storage</code> is a matrix and the actual number of lines
1732 exceeds the matrix size, the maximum possible number of lines is returned
1733 (in case of standard hough transform the lines are sorted by the accumulator value).
1734 <dt>method<dd>The Hough transform variant, one of:<ul>
1735     <li><code>CV_HOUGH_STANDARD</code> - classical or standard Hough transform. Every line is represented by two floating-point numbers
1736          (&rho;, &theta;), where &rho; is a distance between (0,0) point and the line, and &theta; is the angle
1737          between x-axis and the normal to the line. Thus, the matrix must be (the created sequence will
1738          be) of CV_32FC2 type.
1739     <li><code>CV_HOUGH_PROBABILISTIC</code> - probabilistic Hough transform (more efficient in case if picture contains
1740     a few long linear segments). It returns line segments rather than the whole lines.
1741     Every segment is represented by starting and ending points, and the matrix must be
1742     (the created sequence will be) of CV_32SC4 type.
1743     <li><code>CV_HOUGH_MULTI_SCALE</code> - multi-scale variant of classical Hough transform.
1744     The lines are encoded the same way as in CV_HOUGH_STANDARD.
1745     </ul>
1746 <dt>rho<dd>Distance resolution in pixel-related units.
1747 <dt>theta<dd>Angle resolution measured in radians.
1748 <dt>threshold<dd>Threshold parameter. A line is returned by the function if the corresponding
1749 accumulator value is greater than <code>threshold</code>.
1750 <dt>param1<dd>The first method-dependent parameter:<ul>
1751               <li>For classical Hough transform it is not used (0).
1752               <li>For probabilistic Hough transform it is the minimum line length.
1753               <li>For multi-scale Hough transform it is divisor for distance resolution <code>rho</code>.
1754               (The coarse distance resolution will be <code>rho</code> and the accurate resolution will be (<code>rho</code> / <code>param1</code>)).
1755               </ul>
1756 <dt>param2<dd>The second method-dependent parameter:<ul>
1757               <li>For classical Hough transform it is not used (0).
1758               <li>For probabilistic Hough transform it is the maximum gap between line segments lying on the same line to
1759                   treat them as the single line segment (i.e. to join them).
1760               <li>For multi-scale Hough transform it is divisor for angle resolution <code>theta</code>.
1761               (The coarse angle resolution will be <code>theta</code> and the accurate resolution will be (<code>theta</code> / <code>param2</code>)).
1762               </ul>
1763 </dl><p>
1764 The function <code>cvHoughLines2</code> implements a few variants of Hough transform for line detection.</p>
1765 <h4>Example. Detecting lines with Hough transform.</h4>
1766 <pre>
1767 /* This is a stand-alone program. Pass an image name as a first parameter of the program.
1768    Switch between standard and probabilistic Hough transform by changing "#if 1" to "#if 0" and back */
1769 #include &lt;cv.h&gt;
1770 #include &lt;highgui.h&gt;
1771 #include &lt;math.h&gt;
1772
1773 int main(int argc, char** argv)
1774 {
1775     IplImage* src;
1776     if( argc == 2 && (src=cvLoadImage(argv[1], 0))!= 0)
1777     {
1778         IplImage* dst = cvCreateImage( cvGetSize(src), 8, 1 );
1779         IplImage* color_dst = cvCreateImage( cvGetSize(src), 8, 3 );
1780         CvMemStorage* storage = cvCreateMemStorage(0);
1781         CvSeq* lines = 0;
1782         int i;
1783         cvCanny( src, dst, 50, 200, 3 );
1784         cvCvtColor( dst, color_dst, CV_GRAY2BGR );
1785 #if 1
1786         lines = cvHoughLines2( dst, storage, CV_HOUGH_STANDARD, 1, CV_PI/180, 100, 0, 0 );
1787
1788         for( i = 0; i &lt; MIN(lines-&gt;total,100); i++ )
1789         {
1790             float* line = (float*)cvGetSeqElem(lines,i);
1791             float rho = line[0];
1792             float theta = line[1];
1793             CvPoint pt1, pt2;
1794             double a = cos(theta), b = sin(theta);
1795             double x0 = a*rho, y0 = b*rho;
1796             pt1.x = cvRound(x0 + 1000*(-b));
1797             pt1.y = cvRound(y0 + 1000*(a));
1798             pt2.x = cvRound(x0 - 1000*(-b));
1799             pt2.y = cvRound(y0 - 1000*(a));
1800             cvLine( color_dst, pt1, pt2, CV_RGB(255,0,0), 3, 8 );
1801         }
1802 #else
1803         lines = cvHoughLines2( dst, storage, CV_HOUGH_PROBABILISTIC, 1, CV_PI/180, 50, 50, 10 );
1804         for( i = 0; i &lt; lines-&gt;total; i++ )
1805         {
1806             CvPoint* line = (CvPoint*)cvGetSeqElem(lines,i);
1807             cvLine( color_dst, line[0], line[1], CV_RGB(255,0,0), 3, 8 );
1808         }
1809 #endif
1810         cvNamedWindow( "Source", 1 );
1811         cvShowImage( "Source", src );
1812
1813         cvNamedWindow( "Hough", 1 );
1814         cvShowImage( "Hough", color_dst );
1815
1816         cvWaitKey(0);
1817     }
1818 }
1819 </pre>
1820 <p>This is the sample picture the function parameters have been tuned for:</p>
1821 <p>
1822 <img src="pics/building.jpg" width=320 height=240></a>
1823 </p>
1824 <p>
1825 And this is the output of the above program in case of probabilistic Hough transform ("#if 0" case):
1826 </p>
1827 <p>
1828 <img src="pics/houghp.png" width=320 height=240></a>
1829 </p>
1830
1831
1832 <hr><h3><a name="decl_cvHoughCircles">HoughCircles</a></h3>
1833 <p class="Blurb">Finds circles in grayscale image using Hough transform</p>
1834 <pre>
1835 CvSeq* cvHoughCircles( CvArr* image, void* circle_storage,
1836                        int method, double dp, double min_dist,
1837                        double param1=100, double param2=100,
1838                        int min_radius=0, int max_radius=0 );
1839 </pre><p><dl>
1840 <dt>image<dd>The input 8-bit single-channel grayscale image.
1841 <dt>circle_storage<dd>The storage for the circles detected. It can be a memory storage (in this case
1842 a sequence of circles is created in the storage and returned by the function) or single row/single column
1843 matrix (CvMat*) of type CV_32FC3, to which the circles' parameters are written.
1844 The matrix header is modified by the function so its <code>cols</code> or <code>rows</code> will contain
1845 a number of lines detected. If <code>circle_storage</code> is a matrix and the actual number of lines
1846 exceeds the matrix size, the maximum possible number of circles is returned.
1847 Every circle is encoded as 3 floating-point numbers: center coordinates (x,y) and the radius.
1848 <dt>method<dd>Currently, the only implemented method is <code>CV_HOUGH_GRADIENT</code>, which is basically 21HT, described in
1849 <a href="#paper_yuen03"><b>[Yuen03]</b></a>.
1850 <dt>dp<dd>Resolution of the accumulator used to detect centers of the circles. For example, if it is 1,
1851 the accumulator will have the same resolution as the input image, if it is 2 - accumulator will have twice
1852 smaller width and height, etc.
1853 <dt>min_dist<dd>Minimum distance between centers of the detected circles. If the parameter is too small, multiple
1854 neighbor circles may be falsely detected in addition to a true one. If it is too large, some circles may be missed.
1855 <dt>param1<dd>The first method-specific parameter.
1856  In case of <code>CV_HOUGH_GRADIENT</code> it is the higher threshold of the two passed to Canny edge detector
1857  (the lower one will be twice smaller).
1858 <dt>param2<dd>The second method-specific parameter.
1859  In case of <code>CV_HOUGH_GRADIENT</code> it is accumulator threshold at the center detection stage.
1860  The smaller it is, the more false circles may be detected. Circles, corresponding to the larger accumulator
1861  values, will be returned first.
1862 <dt>min_radius<dd>Minimal radius of the circles to search for.
1863 <dt>max_radius<dd>Maximal radius of the circles to search for.
1864  By default the maximal radius is set to <code>max(image_width, image_height)</code>.
1865 </dl><p>
1866 The function <code>cvHoughCircles</code> finds circles in grayscale image using some modification of Hough transform.</p>
1867 <h4>Example. Detecting circles with Hough transform.</h4>
1868 <pre>
1869 #include &lt;cv.h&gt;
1870 #include &lt;highgui.h&gt;
1871 #include &lt;math.h&gt;
1872
1873 int main(int argc, char** argv)
1874 {
1875     IplImage* img;
1876     if( argc == 2 && (img=cvLoadImage(argv[1], 1))!= 0)
1877     {
1878         IplImage* gray = cvCreateImage( cvGetSize(img), 8, 1 );
1879         CvMemStorage* storage = cvCreateMemStorage(0);
1880         cvCvtColor( img, gray, CV_BGR2GRAY );
1881         cvSmooth( gray, gray, CV_GAUSSIAN, 9, 9 ); // smooth it, otherwise a lot of false circles may be detected
1882         CvSeq* circles = cvHoughCircles( gray, storage, CV_HOUGH_GRADIENT, 2, gray->height/4, 200, 100 );
1883         int i;
1884         for( i = 0; i < circles->total; i++ )
1885         {
1886              float* p = (float*)cvGetSeqElem( circles, i );
1887              cvCircle( img, cvPoint(cvRound(p[0]),cvRound(p[1])), 3, CV_RGB(0,255,0), -1, 8, 0 );
1888              cvCircle( img, cvPoint(cvRound(p[0]),cvRound(p[1])), cvRound(p[2]), CV_RGB(255,0,0), 3, 8, 0 );
1889         }
1890         cvNamedWindow( "circles", 1 );
1891         cvShowImage( "circles", img );
1892     }
1893     return 0;
1894 }
1895 </pre>
1896
1897 <hr><h3><a name="decl_cvDistTransform">DistTransform</a></h3>
1898 <p class="Blurb">Calculates distance to closest zero pixel for all non-zero pixels of source
1899 image</p>
1900 <pre>
1901 void cvDistTransform( const CvArr* src, CvArr* dst, int distance_type=CV_DIST_L2,
1902                       int mask_size=3, const float* mask=NULL, CvArr* labels=NULL );
1903 </pre><p><dl>
1904 <dt>src<dd>Source 8-bit single-channel (binary) image.
1905 <dt>dst<dd>Output image with calculated distances.
1906            In most cases it should be 32-bit floating-point, single-channel array of
1907            the same size as the input image.
1908            When <code>distance_type</code>==<code>CV_DIST_L1</code>, 8-bit, single-channel
1909            destination array may be also used (in-place operation is also supported in this case).
1910 <dt>distance_type<dd>Type of distance; can be <code>CV_DIST_L1, CV_DIST_L2, CV_DIST_C</code> or
1911 <code>CV_DIST_USER</code>.
1912 <dt>mask_size<dd>Size of distance transform mask; can be 3, 5 or 0. In case of <code>CV_DIST_L1</code> or
1913 <code>CV_DIST_C</code> the parameter is forced to 3, because 3&times;3 mask gives the same result
1914 as 5&times;5 yet it is faster. When <code>mask_size</code>==0, a different non-approximate algorithm
1915 is used to calculate distances.
1916 <dt>mask<dd>User-defined mask in case of user-defined distance, it consists of 2 numbers
1917 (horizontal/vertical shift cost, diagonal shift cost) in case of 3&times;3 mask and
1918 3 numbers (horizontal/vertical shift cost, diagonal shift cost, knight&#146;s move cost)
1919 in case of 5&times;5 mask.
1920 <dt>labels<dd>The optional output 2d array of labels of integer type
1921               and the same size as <code>src</code> and <code>dst</code>, can now be used only with
1922               <code>mask_size</code>==3 or 5.
1923 </dl><p>
1924 The function <code>cvDistTransform</code> calculates the approximated or exact distance from every binary image pixel
1925 to the nearest zero pixel. When <code>mask_size</code>==0, the function uses the accurate algorithm
1926 <a href="#paper_felzenszwalb04">[Felzenszwalb04]</a>. When <code>mask_size</code>==3 or 5, the function
1927 uses the approximate algorithm <a href="#paper_borgefors86">[Borgefors86]</a>.</p><p>Here is how the approximate
1928 algorithm works. For zero pixels the function sets the zero distance. For others it finds
1929 the shortest path to a zero pixel, consisting of basic shifts: horizontal, vertical, diagonal or knight&#146;s move (the
1930 latest is available for 5&times;5 mask). The overall distance is calculated as a sum of these basic distances.
1931 Because the distance function should be symmetric, all the horizontal and vertical shifts must have
1932 the same cost (that is denoted as <code>a</code>), all the diagonal shifts must have the same cost
1933 (denoted <code>b</code>), and all knight&#146;s moves must have the same cost (denoted <code>c</code>).
1934 For <code>CV_DIST_C</code> and <code>CV_DIST_L1</code> types the distance is calculated precisely,
1935 whereas for <code>CV_DIST_L2</code> (Euclidean distance) the distance can be calculated only with
1936 some relative error (5&times;5 mask gives more accurate results), OpenCV uses the values suggested in
1937 <a href="#paper_borgefors86">[Borgefors86]</a>:</p>
1938 <pre>
1939 CV_DIST_C (3&times;3):
1940 a=1, b=1
1941
1942 CV_DIST_L1 (3&times;3):
1943 a=1, b=2
1944
1945 CV_DIST_L2 (3&times;3):
1946 a=0.955, b=1.3693
1947
1948 CV_DIST_L2 (5&times;5):
1949 a=1, b=1.4, c=2.1969
1950 </pre>
1951 <p>
1952 And below are samples of distance field (black (0) pixel is in the middle of white square)
1953 in case of user-defined distance:
1954 </p>
1955 <h4>User-defined 3&times;3 mask (a=1, b=1.5)</h4>
1956 <p>
1957    <table border=3 cellpadding=5>
1958    <tr><td>4.5</td><td>4</td><td>3.5</td><td>3</td><td>3.5</td><td>4</td><td>4.5</td></tr>
1959    <tr><td>4</td><td>3</td><td>2.5</td><td>2</td><td>2.5</td><td>3</td><td>4</td></tr>
1960    <tr><td>3.5</td><td>2.5</td><td>1.5</td><td>1</td><td>1.5</td><td>2.5</td><td>3.5</td></tr>
1961    <tr><td>3</td><td>2</td><td>1</td><td>0</td><td>1</td><td>2</td><td>3</td></tr>
1962    <tr><td>3.5</td><td>2.5</td><td>1.5</td><td>1</td><td>1.5</td><td>2.5</td><td>3.5</td></tr>
1963    <tr><td>4</td><td>3</td><td>2.5</td><td>2</td><td>2.5</td><td>3</td><td>4</td></tr>
1964    <tr><td>4.5</td><td>4</td><td>3.5</td><td>3</td><td>3.5</td><td>4</td><td>4.5</td></tr>
1965    </table>
1966 </p>
1967 <h4>User-defined 5&times;5 mask (a=1, b=1.5, c=2)</h4>
1968 <p>
1969    <table border=3 cellpadding=5>
1970    <tr><td>4.5</td><td>3.5</td><td>3</td><td>3</td><td>3</td><td>3.5</td><td>4.5</td></tr>
1971    <tr><td>3.5</td><td>3</td><td>2</td><td>2</td><td>2</td><td>3</td><td>3.5</td></tr>
1972    <tr><td>3</td><td>2</td><td>1.5</td><td>1</td><td>1.5</td><td>2</td><td>3</td></tr>
1973    <tr><td>3</td><td>2</td><td>1</td><td>0</td><td>1</td><td>2</td><td>3</td></tr>
1974    <tr><td>3</td><td>2</td><td>1.5</td><td>1</td><td>1.5</td><td>2</td><td>3</td></tr>
1975    <tr><td>3.5</td><td>3</td><td>2</td><td>2</td><td>2</td><td>3</td><td>3.5</td></tr>
1976    <tr><td>4</td><td>3.5</td><td>3</td><td>3</td><td>3</td><td>3.5</td><td>4</td></tr>
1977    </table>
1978 </p>
1979
1980 <p>Typically, for fast coarse distance estimation CV_DIST_L2, 3&times;3 mask is used,
1981 and for more accurate distance estimation CV_DIST_L2, 5&times;5 mask is used.</p>
1982
1983 <p>When the output parameter <code>labels</code> is not <code>NULL</code>, for every non-zero pixel
1984 the function also finds the nearest connected component consisting of zero pixels. The connected components
1985 themselves are found as contours in the beginning of the function.</p>
1986 <p>
1987 In this mode the processing time is still O(N), where N is the number of pixels.
1988 Thus, the function provides a very fast way to compute approximate Voronoi diagram for the binary image.</p>
1989
1990
1991 <hr><h3><a name="decl_cvInpaint">Inpaint</a></h3>
1992 <p class="Blurb">Inpaints the selected region in the image</p>
1993 <pre>
1994 void cvInpaint( const CvArr* src, const CvArr* mask, CvArr* dst,
1995                 int flags, double inpaintRadius );
1996 </pre><p><dl>
1997 <dt>src<dd>The input 8-bit 1-channel or 3-channel image.
1998 <dt>mask<dd>The inpainting mask, 8-bit 1-channel image.
1999            Non-zero pixels indicate the area that needs to be inpainted.
2000 <dt>dst<dd>The output image of the same format and the same size as input.
2001 <dt>flags<dd>The inpainting method, one of the following:<br>
2002                  <code>CV_INPAINT_NS</code> - Navier-Stokes based method.<br>
2003                  <code>CV_INPAINT_TELEA</code> - The method by Alexandru Telea <a href="#paper_telea04">[Telea04]</a>
2004 <dt>inpaintRadius<dd>The radius of circular neighborhood of each point inpainted that is considered by the algorithm.
2005 </dl><p>
2006 The function <code>cvInpaint</code> reconstructs the selected image area from the pixel near the
2007 area boundary. The function may be used to remove dust and scratches from a scanned photo, or
2008 to remove undesirable objects from still images or video.</p>
2009
2010
2011 <hr><h2><a name="cv_imgproc_histograms">Histograms</a></h2>
2012
2013 <hr><h3><a name="decl_CvHistogram">CvHistogram</a></h3>
2014 <p class="Blurb">Multi-dimensional histogram</p>
2015 <pre>
2016 typedef struct CvHistogram
2017 {
2018     int     type;
2019     CvArr*  bins;
2020     float   thresh[CV_MAX_DIM][2]; /* for uniform histograms */
2021     float** thresh2; /* for non-uniform histograms */
2022     CvMatND mat; /* embedded matrix header for array histograms */
2023 }
2024 CvHistogram;
2025 </pre>
2026
2027 <hr><h3><a name="decl_cvCreateHist">CreateHist</a></h3>
2028 <p class="Blurb">Creates histogram</p>
2029 <pre>
2030 CvHistogram* cvCreateHist( int dims, int* sizes, int type,
2031                            float** ranges=NULL, int uniform=1 );
2032 </pre><p><dl>
2033 <dt>dims<dd>Number of histogram dimensions.
2034 <dt>sizes<dd>Array of histogram dimension sizes.
2035 <dt>type<dd>Histogram representation format: <code>CV_HIST_ARRAY</code> means that histogram data is
2036 represented as an multi-dimensional dense array <a href="#decl_CvMatND">CvMatND</a>;
2037 <code>CV_HIST_SPARSE</code> means that histogram data is represented
2038 as a multi-dimensional sparse array <a href="#decl_CvSparseMat">CvSparseMat</a>.
2039 <dt>ranges<dd>Array of ranges for histogram bins. Its meaning depends on the <code>uniform</code> parameter value.
2040 The ranges are used for when histogram is calculated or back-projected to determine, which histogram bin
2041 corresponds to which value/tuple of values from the input image[s].
2042 <dt>uniform<dd>Uniformity flag; if not 0, the histogram has evenly spaced bins and
2043 for every <code>0&lt;=i&lt;cDims</code> <code>ranges[i]</code> is array of two numbers: lower and upper
2044 boundaries for the i-th histogram dimension. The whole range [lower,upper] is split then
2045 into <code>dims[i]</code> equal parts to determine <code>i-th</code> input tuple value ranges for every histogram bin.
2046 And if <code>uniform=0</code>, then <code>i-th</code> element of <code>ranges</code> array contains <code>dims[i]+1</code> elements:
2047 <code>lower<sub>0</sub>, upper<sub>0</sub>, lower<sub>1</sub>, upper<sub>1</sub> == lower<sub>2</sub>, ..., upper<sub>dims[i]-1</sub></code>,
2048 where <code>lower<sub>j</sub></code> and <code>upper<sub>j</sub></code> are lower and upper
2049 boundaries of <code>i-th</code> input tuple value for <code>j-th</code> bin, respectively.
2050 In either case, the input values that are beyond the specified range for a histogram bin, are not
2051 counted by <a href="#decl_cvCalcHist">cvCalcHist</a> and filled with 0 by <a href="#decl_cvCalcBackProject">cvCalcBackProject</a>.
2052 </dl><p>
2053 The function <code>cvCreateHist</code> creates a histogram of the specified size and returns
2054 the pointer to the created histogram. If the array <code>ranges</code> is 0, the histogram
2055 bin ranges must be specified later via The function <code>cvSetHistBinRanges</code>, though
2056 <a href="#decl_cvCalcHist">cvCalcHist</a> and <a href="#decl_cvCalcBackProject">cvCalcBackProject</a> may process 8-bit images without setting
2057 bin ranges, they assume equally spaced in 0..255 bins.</p>
2058
2059
2060 <hr><h3><a name="decl_cvSetHistBinRanges">SetHistBinRanges</a></h3>
2061 <p class="Blurb">Sets bounds of histogram bins</p>
2062 <pre>
2063 void cvSetHistBinRanges( CvHistogram* hist, float** ranges, int uniform=1 );
2064 </pre><p><dl>
2065 <dt>hist<dd>Histogram.
2066 <dt>ranges<dd>Array of bin ranges arrays, see <a href="#decl_cvCreateHist">cvCreateHist</a>.
2067 <dt>uniform<dd>Uniformity flag, see <a href="#decl_cvCreateHist">cvCreateHist</a>.
2068 </dl><p>
2069 The function <code>cvSetHistBinRanges</code> is a stand-alone function for setting bin ranges
2070 in the histogram. For more detailed description of the parameters <code>ranges</code> and
2071 <code>uniform</code> see <a href="#decl_cvCalcHist">cvCalcHist</a> function,
2072 that can initialize the ranges as well.
2073 Ranges for histogram bins must be set before the histogram is calculated or
2074 back projection of the histogram is calculated.
2075 </p>
2076
2077
2078 <hr><h3><a name="decl_cvReleaseHist">ReleaseHist</a></h3>
2079 <p class="Blurb">Releases histogram</p>
2080 <pre>
2081 void cvReleaseHist( CvHistogram** hist );
2082 </pre><p><dl>
2083 <dt>hist<dd>Double pointer to the released histogram.
2084 </dl><p>
2085 The function <code>cvReleaseHist</code> releases the histogram (header and the data).
2086 The pointer to histogram is cleared by the function. If <code>*hist</code> pointer is already
2087 <code>NULL</code>, the function does nothing.</p>
2088
2089
2090 <hr><h3><a name="decl_cvClearHist">ClearHist</a></h3>
2091 <p class="Blurb">Clears histogram</p>
2092 <pre>
2093 void cvClearHist( CvHistogram* hist );
2094 </pre><p><dl>
2095 <dt>hist<dd>Histogram.
2096 </dl><p>
2097 The function <code>cvClearHist</code> sets all histogram bins to 0 in case of dense histogram and
2098 removes all histogram bins in case of sparse array.</p>
2099
2100
2101 <hr><h3><a name="decl_cvMakeHistHeaderForArray">MakeHistHeaderForArray</a></h3>
2102 <p class="Blurb">Makes a histogram out of array</p>
2103 <pre>
2104 CvHistogram*  cvMakeHistHeaderForArray( int dims, int* sizes, CvHistogram* hist,
2105                                         float* data, float** ranges=NULL, int uniform=1 );
2106 </pre><p><dl>
2107 <dt>dims<dd>Number of histogram dimensions.
2108 <dt>sizes<dd>Array of histogram dimension sizes.
2109 <dt>hist<dd>The histogram header initialized by the function.
2110 <dt>data<dd>Array that will be used to store histogram bins.
2111 <dt>ranges<dd>Histogram bin ranges, see <a href="#decl_cvCreateHist">cvCreateHist</a>.
2112 <dt>uniform<dd>Uniformity flag, see <a href="#decl_cvCreateHist">cvCreateHist</a>.
2113 </dl><p>
2114 The function <code>cvMakeHistHeaderForArray</code> initializes the histogram, which header and
2115 bins are allocated by user. No <a href="#decl_cvReleaseHist">cvReleaseHist</a> need to be called afterwards.
2116 Only dense histograms can be initialized this way. The function returns <code>hist</code>.
2117 </p>
2118
2119
2120 <hr><h3><a name="decl_cvQueryHistValue_*D">QueryHistValue_*D</a></h3>
2121 <p class="Blurb">Queries value of histogram bin</p>
2122 <pre>
2123 #define cvQueryHistValue_1D( hist, idx0 ) \
2124     cvGetReal1D( (hist)->bins, (idx0) )
2125 #define cvQueryHistValue_2D( hist, idx0, idx1 ) \
2126     cvGetReal2D( (hist)->bins, (idx0), (idx1) )
2127 #define cvQueryHistValue_3D( hist, idx0, idx1, idx2 ) \
2128     cvGetReal3D( (hist)->bins, (idx0), (idx1), (idx2) )
2129 #define cvQueryHistValue_nD( hist, idx ) \
2130     cvGetRealND( (hist)->bins, (idx) )
2131 </pre><p><dl>
2132 <dt>hist<dd>Histogram.
2133 <dt>idx0, idx1, idx2, idx3<dd>Indices of the bin.
2134 <dt>idx<dd>Array of indices
2135 </dl><p>
2136 The macros <a href="#decl_cvQueryHistValue_*D">cvQueryHistValue_*D</a> return the value of the specified bin of 1D, 2D, 3D or
2137 N-D histogram. In case of sparse histogram the function returns 0, if the bin is not present in the
2138 histogram, and no new bin is created.
2139 </p>
2140
2141
2142 <hr><h3><a name="decl_cvGetHistValue_*D">GetHistValue_*D</a></h3>
2143 <p class="Blurb">Returns pointer to histogram bin</p>
2144 <pre>
2145 #define cvGetHistValue_1D( hist, idx0 ) \
2146     ((float*)(cvPtr1D( (hist)->bins, (idx0), 0 ))
2147 #define cvGetHistValue_2D( hist, idx0, idx1 ) \
2148     ((float*)(cvPtr2D( (hist)->bins, (idx0), (idx1), 0 ))
2149 #define cvGetHistValue_3D( hist, idx0, idx1, idx2 ) \
2150     ((float*)(cvPtr3D( (hist)->bins, (idx0), (idx1), (idx2), 0 ))
2151 #define cvGetHistValue_nD( hist, idx ) \
2152     ((float*)(cvPtrND( (hist)->bins, (idx), 0 ))
2153 </pre><p><dl>
2154 <dt>hist<dd>Histogram.
2155 <dt>idx0, idx1, idx2, idx3<dd>Indices of the bin.
2156 <dt>idx<dd>Array of indices
2157 </dl><p>
2158 The macros <a href="#decl_cvGetHistValue_*D">cvGetHistValue_*D</a> return pointer to the specified bin of 1D, 2D, 3D or
2159 N-D histogram. In case of sparse histogram the function creates a new bin and sets it to 0,
2160 unless it exists already.
2161 </p>
2162
2163
2164 <hr><h3><a name="decl_cvGetMinMaxHistValue">GetMinMaxHistValue</a></h3>
2165 <p class="Blurb">Finds minimum and maximum histogram bins</p>
2166 <pre>
2167 void cvGetMinMaxHistValue( const CvHistogram* hist,
2168                            float* min_value, float* max_value,
2169                            int* min_idx=NULL, int* max_idx=NULL );
2170 </pre><p><dl>
2171 <dt>hist<dd>Histogram.
2172 <dt>min_value<dd>Pointer to the minimum value of the histogram
2173 <dt>max_value<dd>Pointer to the maximum value of the histogram
2174 <dt>min_idx<dd>Pointer to the array of coordinates for minimum
2175 <dt>max_idx<dd>Pointer to the array of coordinates for maximum
2176 </dl><p>
2177 The function <code>cvGetMinMaxHistValue</code> finds the minimum and maximum histogram bins and
2178 their positions. Any of output arguments is optional.
2179 Among several extremums with the same value the ones with minimum index (in lexicographical order)
2180 In case of several maximums or minimums the earliest in lexicographical order
2181 extrema locations are returned.</p>
2182
2183
2184 <hr><h3><a name="decl_cvNormalizeHist">NormalizeHist</a></h3>
2185 <p class="Blurb">Normalizes histogram</p>
2186 <pre>
2187 void cvNormalizeHist( CvHistogram* hist, double factor );
2188 </pre><p><dl>
2189 <dt>hist<dd>Pointer to the histogram.
2190 <dt>factor<dd>Normalization factor.
2191 </dl><p>
2192 The function <code>cvNormalizeHist</code> normalizes the histogram bins by scaling them,
2193 such that the sum of the bins becomes equal to <code>factor</code>.</p>
2194
2195
2196 <hr><h3><a name="decl_cvThreshHist">ThreshHist</a></h3>
2197 <p class="Blurb">Thresholds histogram</p>
2198 <pre>
2199 void cvThreshHist( CvHistogram* hist, double threshold );
2200 </pre><p><dl>
2201 <dt>hist<dd>Pointer to the histogram.
2202 <dt>threshold<dd>Threshold level.
2203 </dl><p>
2204 The function <code>cvThreshHist</code> clears histogram bins
2205 that are below the specified threshold.</p>
2206
2207
2208 <hr><h3><a name="decl_cvCompareHist">CompareHist</a></h3>
2209 <p class="Blurb">Compares two dense histograms</p>
2210 <pre>
2211 double cvCompareHist( const CvHistogram* hist1, const CvHistogram* hist2, int method );
2212 </pre><p><dl>
2213 <dt>hist1<dd>The first dense histogram.
2214 <dt>hist2<dd>The second dense histogram.
2215 <dt>method<dd>Comparison method, one of:
2216 <ul>
2217 <li>CV_COMP_CORREL
2218 <li>CV_COMP_CHISQR
2219 <li>CV_COMP_INTERSECT
2220 <li>CV_COMP_BHATTACHARYYA
2221 </ul>
2222 </dl><p>
2223 The function <code>cvCompareHist</code> compares two dense histograms using
2224 the specified method as following
2225 (<code>H<sub>1</sub></code> denotes the first histogram, <code>H<sub>2</sub></code> - the second):</p>
2226 <pre>
2227 Correlation (method=CV_COMP_CORREL):
2228 d(H<sub>1</sub>,H<sub>2</sub>)=sum<sub>I</sub>(H'<sub>1</sub>(I)&bull;H'<sub>2</sub>(I))/sqrt(sum<sub>I</sub>[H'<sub>1</sub>(I)<sup>2</sup>]&bull;sum<sub>I</sub>[H'<sub>2</sub>(I)<sup>2</sup>])
2229 where
2230 H'<sub>k</sub>(I)=H<sub>k</sub>(I)-1/N&bull;sum<sub>J</sub>H<sub>k</sub>(J) (N=number of histogram bins)
2231
2232 Chi-Square (method=CV_COMP_CHISQR):
2233 d(H<sub>1</sub>,H<sub>2</sub>)=sum<sub>I</sub>[(H<sub>1</sub>(I)-H<sub>2</sub>(I))/(H<sub>1</sub>(I)+H<sub>2</sub>(I))]
2234
2235 Intersection (method=CV_COMP_INTERSECT):
2236 d(H<sub>1</sub>,H<sub>2</sub>)=sum<sub>I</sub>min(H<sub>1</sub>(I),H<sub>2</sub>(I))
2237
2238 Bhattacharyya distance (method=CV_COMP_BHATTACHARYYA):
2239 d(H<sub>1</sub>,H<sub>2</sub>)=sqrt(1-sum<sub>I</sub>(sqrt(H<sub>1</sub>(I)&bull;H<sub>2</sub>(I))))
2240 </pre>
2241 <p>The function returns <code>d(H<sub>1</sub>,H<sub>2</sub>)</code> value.</p>
2242 <p>Note: the method <code>CV_COMP_BHATTACHARYYA</code> only works with normalized histograms.
2243 <p>To compare sparse histogram or more general sparse configurations of weighted points,
2244 consider using <a href="#decl_cvCalcEMD2">cvCalcEMD2</a> function.</p>
2245
2246
2247 <hr><h3><a name="decl_cvCopyHist">CopyHist</a></h3>
2248 <p class="Blurb">Copies histogram</p>
2249 <pre>
2250 void cvCopyHist( const CvHistogram* src, CvHistogram** dst );
2251 </pre><p><dl>
2252 <dt>src<dd>Source histogram.
2253 <dt>dst<dd>Pointer to destination histogram.
2254 </dl><p>
2255 The function <code>cvCopyHist</code> makes a copy of the histogram. If the second histogram
2256 pointer <code>*dst</code> is NULL, a new histogram of the same size as <code>src</code> is created.
2257 Otherwise, both histograms must have equal types and sizes.
2258 Then the function copies the source histogram bins values to destination histogram and
2259 sets the same bin values ranges as in <code>src</code>.</p>
2260
2261
2262 <hr><h3><a name="decl_cvCalcHist">CalcHist</a></h3>
2263 <p class="Blurb">Calculates histogram of image(s)</p>
2264 <pre>
2265 void cvCalcHist( IplImage** image, CvHistogram* hist,
2266                  int accumulate=0, const CvArr* mask=NULL );
2267 </pre><p><dl>
2268 <dt>image<dd>Source images (though, you may pass CvMat** as well), all are of the same size and type
2269 <dt>hist<dd>Pointer to the histogram.
2270 <dt>accumulate<dd>Accumulation flag. If it is set, the histogram is not cleared in the beginning.
2271 This feature allows user to compute a single histogram from several images, or to update the histogram online.
2272 <dt>mask<dd>The operation mask, determines what pixels of the source images are counted.
2273 </dl><p>
2274 The function <code>cvCalcHist</code> calculates the histogram of one or more single-channel images.
2275 The elements of a tuple that is used to increment a histogram bin are taken at the same
2276 location from the corresponding input images.</p>
2277 <h4>Sample. Calculating and displaying 2D Hue-Saturation histogram of a color image</h4>
2278 <pre>
2279 #include &lt;cv.h&gt;
2280 #include &lt;highgui.h&gt;
2281
2282 int main( int argc, char** argv )
2283 {
2284     IplImage* src;
2285     if( argc == 2 && (src=cvLoadImage(argv[1], 1))!= 0)
2286     {
2287         IplImage* h_plane = cvCreateImage( cvGetSize(src), 8, 1 );
2288         IplImage* s_plane = cvCreateImage( cvGetSize(src), 8, 1 );
2289         IplImage* v_plane = cvCreateImage( cvGetSize(src), 8, 1 );
2290         IplImage* planes[] = { h_plane, s_plane };
2291         IplImage* hsv = cvCreateImage( cvGetSize(src), 8, 3 );
2292         int h_bins = 30, s_bins = 32;
2293         int hist_size[] = {h_bins, s_bins};
2294         float h_ranges[] = { 0, 180 }; /* hue varies from 0 (~0&deg;red) to 180 (~360&deg;red again) */
2295         float s_ranges[] = { 0, 255 }; /* saturation varies from 0 (black-gray-white) to 255 (pure spectrum color) */
2296         float* ranges[] = { h_ranges, s_ranges };
2297         int scale = 10;
2298         IplImage* hist_img = cvCreateImage( cvSize(h_bins*scale,s_bins*scale), 8, 3 );
2299         CvHistogram* hist;
2300         float max_value = 0;
2301         int h, s;
2302
2303         cvCvtColor( src, hsv, CV_BGR2HSV );
2304         cvCvtPixToPlane( hsv, h_plane, s_plane, v_plane, 0 );
2305         hist = cvCreateHist( 2, hist_size, CV_HIST_ARRAY, ranges, 1 );
2306         cvCalcHist( planes, hist, 0, 0 );
2307         cvGetMinMaxHistValue( hist, 0, &max_value, 0, 0 );
2308         cvZero( hist_img );
2309
2310         for( h = 0; h &lt; h_bins; h++ )
2311         {
2312             for( s = 0; s &lt; s_bins; s++ )
2313             {
2314                 float bin_val = cvQueryHistValue_2D( hist, h, s );
2315                 int intensity = cvRound(bin_val*255/max_value);
2316                 cvRectangle( hist_img, cvPoint( h*scale, s*scale ),
2317                              cvPoint( (h+1)*scale - 1, (s+1)*scale - 1),
2318                              CV_RGB(intensity,intensity,intensity), /* draw a grayscale histogram.
2319                                                                        if you have idea how to do it
2320                                                                        nicer let us know */
2321                              CV_FILLED );
2322             }
2323         }
2324
2325         cvNamedWindow( "Source", 1 );
2326         cvShowImage( "Source", src );
2327
2328         cvNamedWindow( "H-S Histogram", 1 );
2329         cvShowImage( "H-S Histogram", hist_img );
2330
2331         cvWaitKey(0);
2332     }
2333 }
2334 </pre>
2335
2336
2337 <hr><h3><a name="decl_cvCalcBackProject">CalcBackProject</a></h3>
2338 <p class="Blurb">Calculates back projection</p>
2339 <pre>
2340 void cvCalcBackProject( IplImage** image, CvArr* back_project, const CvHistogram* hist );
2341 </pre><p><dl>
2342 <dt>image<dd>Source images (though you may pass CvMat** as well), all are of the same size and type
2343 <dt>back_project<dd>Destination back projection image of the same type as the source images.
2344 <dt>hist<dd>Histogram.
2345 </dl><p>
2346 The function <code>cvCalcBackProject</code> calculates the back project of the histogram. For
2347 each tuple of pixels at the same position of all input single-channel
2348 images the function puts the value of the histogram bin, corresponding to the tuple,
2349 to the destination image. In terms of statistics, the value of each output image pixel
2350 is probability of the observed tuple given the distribution (histogram).
2351 For example, to find a red object in the picture, one may do the following:
2352 <ol>
2353 <li>Calculate a hue histogram for the red object assuming the image contains only
2354   this object. The histogram is likely to have a strong maximum, corresponding
2355   to red color.
2356 <li>Calculate back projection of a hue plane of input image where the object is searched,
2357     using the histogram. Threshold the image.
2358 <li>Find connected components in the resulting picture and choose the right
2359   component using some additional criteria, for example, the largest connected
2360   component.
2361 </ol>
2362 That is the approximate algorithm of CamShift color object tracker, except for the 3rd step,
2363 instead of which CAMSHIFT algorithm is used to locate the object on the back projection given
2364 the previous object position.
2365 </p>
2366
2367 <hr><h3><a name="decl_cvCalcBackProjectPatch">CalcBackProjectPatch</a></h3>
2368 <p class="Blurb">Locates a template within image by histogram comparison</p>
2369 <pre>
2370 void cvCalcBackProjectPatch( IplImage** images, CvArr* dst,
2371                              CvSize patch_size, CvHistogram* hist,
2372                              int method, float factor );
2373 </pre><p><dl>
2374 <dt>images<dd>Source images (though, you may pass CvMat** as well), all of the same size
2375 <dt>dst<dd>Destination image.
2376 <dt>patch_size<dd>Size of patch slid though the source images.
2377 <dt>hist<dd>Histogram
2378 <dt>method<dd>Comparison method, passed to <a href="#decl_cvCompareHist">cvCompareHist</a> (see description of that function).
2379 <dt>factor<dd>Normalization factor for histograms,
2380     will affect normalization scale of destination image, pass 1. if unsure.
2381 </dl><p>
2382 The function <code>cvCalcBackProjectPatch</code> compares histogram, computed over
2383 each possible rectangular patch of the specified size in the input <code>images</code>,
2384 and stores the results to the output map <code>dst</code>.</p>
2385 <p>
2386 In pseudo-code the operation may be written as:
2387 <pre>
2388 for (x,y) in images (until (x+patch_size.width-1,y+patch_size.height-1) is inside the images) do
2389     compute histogram over the ROI (x,y,x+patch_size.width,y+patch_size.height) in images
2390        (see cvCalcHist)
2391     normalize the histogram using the factor
2392        (see cvNormalizeHist)
2393     compare the normalized histogram with input histogram hist using the specified method
2394        (see cvCompareHist)
2395     store the result to dst(x,y)
2396 end for
2397 </pre>
2398
2399 See also a similar function <a href="#decl_cvMatchTemplate">cvMatchTemplate</a>.
2400 </p>
2401 <h4>Back Project Calculation by Patches</h4>
2402 <p>
2403 <image align="center" src="pics/backprojectpatch.png">
2404 </p>
2405
2406
2407 <hr><h3><a name="decl_cvCalcProbDensity">CalcProbDensity</a></h3>
2408 <p class="Blurb">Divides one histogram by another</p>
2409 <pre>
2410 void  cvCalcProbDensity( const CvHistogram* hist1, const CvHistogram* hist2,
2411                          CvHistogram* dst_hist, double scale=255 );
2412 </pre><p><dl>
2413 <dt>hist1<dd>first histogram (the divisor).
2414 <dt>hist2<dd>second histogram.
2415 <dt>dst_hist<dd>destination histogram.
2416 <dt>scale<dd>scale factor for the destination histogram.
2417 </dl></p><p>
2418 The function <code>cvCalcProbDensity</code> calculates the object probability density from
2419 the two histograms as:</p>
2420 <pre>
2421 dist_hist(I)=0      if hist1(I)==0
2422              scale  if hist1(I)!=0 && hist2(I)&gt;hist1(I)
2423              hist2(I)*scale/hist1(I) if hist1(I)!=0 && hist2(I)&lt;=hist1(I)
2424 </pre>
2425 <p>
2426 So the destination histogram bins are within less than scale.
2427 </p>
2428
2429
2430 <hr><h3><a name="decl_cvEqualizeHist">EqualizeHist</a></h3>
2431 <p class="Blurb">Equalizes histogram of grayscale image</p>
2432 <pre>
2433 void  cvEqualizeHist( const CvArr* src, CvArr* dst );
2434 </pre><p><dl>
2435 <dt>src<dd>The input 8-bit single-channel image.
2436 <dt>dst<dd>The output image of the same size and the same data type as <code>src</code>.
2437 </dl></p><p>
2438 The function <code>cvEqualizeHist</code> equalizes histogram of the input image
2439 using the following algorithm:</p>
2440 <pre>
2441 1. calculate histogram H for src.
2442 2. normalize histogram, so that the sum of histogram bins is 255.
2443 3. compute integral of the histogram:
2444    H&#146;(i) = sum<sub>0&le;j&le;i</sub>H(j)
2445 4. transform the image using H&#146; as a look-up table: dst(x,y)=H&#146;(src(x,y))
2446 </pre>
2447 <p>The algorithm normalizes brightness and increases contrast of the image.</p>
2448
2449
2450 <hr><h2><a name="cv_imgproc_matching">Matching</a></h2>
2451
2452 <hr><h3><a name="decl_cvMatchTemplate">MatchTemplate</a></h3>
2453 <p class="Blurb">Compares template against overlapped image regions</p>
2454 <pre>
2455 void cvMatchTemplate( const CvArr* image, const CvArr* templ,
2456                       CvArr* result, int method );
2457 </pre><p><dl>
2458 <dt>image<dd>Image where the search is running.
2459            It should be 8-bit or 32-bit floating-point.
2460 <dt>templ<dd>Searched template; must be not greater than the source image and the same data type as the image.
2461 <dt>result<dd>A map of comparison results; single-channel 32-bit floating-point. If <code>image</code> is
2462 <code>W</code>&times;<code>H</code> and <code>templ</code> is <code>w</code>&times;<code>h</code> then <code>result</code> must
2463 be <code>W-w+1</code>&times;<code>H-h+1</code>.
2464 <dt>method<dd>Specifies the way the template must be compared with image regions (see below).
2465 </dl><p>
2466 The function <code>cvMatchTemplate</code> is similar to <a href="#decl_cvCalcBackProjectPatch">cvCalcBackProjectPatch</a>.
2467 It slides through <code>image</code>, compares overlapped patches of size <code>w</code>&times;<code>h</code>
2468 with <code>templ</code> using the specified method and stores the comparison results
2469 to <code>result</code>. Here are the formulae for the different comparison methods one may use
2470 (<code>I</code> denotes image, <code>T</code> - template, <code>R</code> - result.
2471 The summation is done over template and/or the image patch: <code>x'=0..w-1, y'=0..h-1</code>):</p>
2472 <pre>
2473 method=CV_TM_SQDIFF:
2474 R(x,y)=sum<sub>x',y'</sub>[T(x',y')-I(x+x',y+y')]<sup>2</sup>
2475
2476 method=CV_TM_SQDIFF_NORMED:
2477 R(x,y)=sum<sub>x',y'</sub>[T(x',y')-I(x+x',y+y')]<sup>2</sup>/sqrt[sum<sub>x',y'</sub>T(x',y')<sup>2</sup>&bull;sum<sub>x',y'</sub>I(x+x',y+y')<sup>2</sup>]
2478
2479 method=CV_TM_CCORR:
2480 R(x,y)=sum<sub>x',y'</sub>[T(x',y')&bull;I(x+x',y+y')]
2481
2482 method=CV_TM_CCORR_NORMED:
2483 R(x,y)=sum<sub>x',y'</sub>[T(x',y')&bull;I(x+x',y+y')]/sqrt[sum<sub>x',y'</sub>T(x',y')<sup>2</sup>&bull;sum<sub>x',y'</sub>I(x+x',y+y')<sup>2</sup>]
2484
2485 method=CV_TM_CCOEFF:
2486 R(x,y)=sum<sub>x',y'</sub>[T'(x',y')&bull;I'(x+x',y+y')],
2487
2488 where T'(x',y')=T(x',y') - 1/(w&bull;h)&bull;sum<sub>x",y"</sub>T(x",y")
2489       I'(x+x',y+y')=I(x+x',y+y') - 1/(w&bull;h)&bull;sum<sub>x",y"</sub>I(x+x",y+y")
2490
2491 method=CV_TM_CCOEFF_NORMED:
2492 R(x,y)=sum<sub>x',y'</sub>[T'(x',y')&bull;I'(x+x',y+y')]/sqrt[sum<sub>x',y'</sub>T'(x',y')<sup>2</sup>&bull;sum<sub>x',y'</sub>I'(x+x',y+y')<sup>2</sup>]
2493
2494 </pre>
2495 After the function finishes comparison, the best matches can be found as global minimums (CV_TM_SQDIFF*)
2496 or maximums (CV_TM_CCORR* and CV_TM_CCOEFF*) using <a href="opencvref_cxcore.htm#decl_cvMinMaxLoc">cvMinMaxLoc</a> function.
2497 In case of color image and template summation in both numerator and each sum in denominator is done
2498 over all the channels (and separate mean values are used for each channel).
2499 </p>
2500
2501
2502 <hr><h3><a name="decl_cvMatchShapes">MatchShapes</a></h3>
2503 <p class="Blurb">Compares two shapes</p>
2504 <pre>
2505 double cvMatchShapes( const void* object1, const void* object2,
2506                       int method, double parameter=0 );
2507 </pre><p><dl>
2508 <dt>object1<dd>First contour or grayscale image
2509 <dt>object2<dd>Second contour or grayscale image
2510 <dt>method<dd>Comparison method, one of CV_CONTOUR_MATCH_I1, CV_CONTOURS_MATCH_I2 or CV_CONTOURS_MATCH_I3.
2511 <dt>parameter<dd>Method-specific parameter (is not used now).
2512 </dl><p>
2513 The function <code>cvMatchShapes</code> compares two shapes. The 3 implemented methods all
2514 use Hu moments (see <a href="#decl_cvGetHuMoments">cvGetHuMoments</a>)
2515 (<code>A</code> ~ <code>object1</code>, <code>B</code> - <code>object2</code>):</p>
2516 <pre>
2517 method=CV_CONTOUR_MATCH_I1:
2518 I<sub>1</sub>(A,B)=sum<sub>i=1..7</sub>abs(1/m<sup>A</sup><sub>i</sub> - 1/m<sup>B</sup><sub>i</sub>)
2519
2520 method=CV_CONTOUR_MATCH_I2:
2521 I<sub>2</sub>(A,B)=sum<sub>i=1..7</sub>abs(m<sup>A</sup><sub>i</sub> - m<sup>B</sup><sub>i</sub>)
2522
2523 method=CV_CONTOUR_MATCH_I3:
2524 I<sub>3</sub>(A,B)=sum<sub>i=1..7</sub>abs(m<sup>A</sup><sub>i</sub> - m<sup>B</sup><sub>i</sub>)/abs(m<sup>A</sup><sub>i</sub>)
2525
2526 where
2527 m<sup>A</sup><sub>i</sub>=sign(h<sup>A</sup><sub>i</sub>)&bull;log(h<sup>A</sup><sub>i</sub>),
2528 m<sup>B</sup><sub>i</sub>=sign(h<sup>B</sup><sub>i</sub>)&bull;log(h<sup>B</sup><sub>i</sub>),
2529 h<sup>A</sup><sub>i</sub>, h<sup>B</sup><sub>i</sub> - Hu moments of A and B, respectively.
2530 </pre>
2531
2532
2533 <hr><h3><a name="decl_cvCalcEMD2">CalcEMD2</a></h3>
2534 <p class="Blurb">Computes "minimal work" distance between two weighted point configurations</p>
2535 <pre>
2536 float cvCalcEMD2( const CvArr* signature1, const CvArr* signature2, int distance_type,
2537                   CvDistanceFunction distance_func=NULL, const CvArr* cost_matrix=NULL,
2538                   CvArr* flow=NULL, float* lower_bound=NULL, void* userdata=NULL );
2539 typedef float (*CvDistanceFunction)(const float* f1, const float* f2, void* userdata);
2540 </pre><p><dl>
2541 <dt>signature1<dd>First signature, <code>size1</code>&times;<code>dims+1</code> floating-point matrix.
2542     Each row stores the point weight followed by the point coordinates. The matrix is allowed to
2543     have a single column (weights only) if the user-defined cost matrix is used.
2544 <dt>signature2<dd>Second signature of the same format as <code>signature1</code>, though the number
2545     of rows may be different. The total weights may be different, in this case an extra "dummy" point
2546     is added to either <code>signature1</code> or <code>signature2</code>.
2547 <dt>distance_type<dd>Metrics used; <code>CV_DIST_L1, CV_DIST_L2</code>, and <code>CV_DIST_C</code> stand for one of
2548 the standard metrics; <code>CV_DIST_USER</code> means that a user-defined function <code>distance_func</code> or
2549 pre-calculated <code>cost_matrix</code> is used.
2550 <dt>distance_func<dd>The user-defined distance function.
2551                 It takes coordinates of two points and returns the distance between the points.
2552 <dt>cost_matrix<dd>The user-defined <code>size1</code>&times;<code>size2</code> cost matrix.
2553                   At least one of <code>cost_matrix</code> and <code>distance_func</code> must be NULL.
2554                   Also, if a cost matrix is used, lower boundary (see below) can not be calculated,
2555                   because it needs a metric function.
2556 <dt>flow<dd>The resultant <code>size1</code>&times;<code>size2</code> flow matrix: <code>flow<sub>ij</sub></code> is a flow
2557             from i-th point of <code>signature1</code> to j-th point of <code>signature2</code>
2558 <dt>lower_bound<dd>Optional input/output parameter: lower boundary of distance between the two signatures that
2559                   is a distance between mass centers. The lower boundary may not be calculated if
2560                   the user-defined cost matrix is used, the total weights of point configurations are
2561                   not equal, or there is the signatures consist of weights only
2562                   (i.e. the signature matrices have a single column).
2563                   User <em>must</em> initialize <code>*lower_bound</code>.
2564                   If the calculated distance between mass centers is greater or equal to <code>*lower_bound</code>
2565                   (it means that the signatures are far enough) the function does not calculate EMD.
2566                   In any case <code>*lower_bound</code> is set to the calculated distance between mass centers
2567                   on return. Thus, if user wants to calculate both distance between mass centers and EMD,
2568                   <code>*lower_bound</code> should be set to 0.
2569 <dt>userdata<dd>Pointer to optional data that is passed into the user-defined distance function.
2570 </dl><p>
2571 The function <code>cvCalcEMD2</code> computes earth mover distance and/or a lower boundary of
2572 the distance between the two weighted point configurations.
2573 One of the application described in <a href="#paper_rubnersept98">[RubnerSept98]</a> is multi-dimensional
2574 histogram comparison for image retrieval.
2575 EMD is a transportation problem that is solved using some modification of simplex algorithm,
2576 thus the complexity is exponential in the worst case, though, it is much faster in average.
2577 In case of a real metric the lower boundary can be calculated even faster (using linear-time algorithm)
2578 and it can be used to determine roughly whether the two
2579 signatures are far enough so that they cannot relate to the same object.
2580 </p>
2581
2582 <hr><h1><a name="cv_sa">Structural Analysis</a></h1>
2583
2584 <hr><h2><a name="cv_sa_contours">Contour Processing Functions</a></h2>
2585
2586 <hr><h3><a name="decl_cvApproxChains">ApproxChains</a></h3>
2587 <p class="Blurb">Approximates Freeman chain(s) with polygonal curve</p>
2588 <pre>
2589 CvSeq* cvApproxChains( CvSeq* src_seq, CvMemStorage* storage,
2590                        int method=CV_CHAIN_APPROX_SIMPLE,
2591                        double parameter=0, int minimal_perimeter=0, int recursive=0 );
2592 </pre><p><dl>
2593 <dt>src_seq<dd>Pointer to the chain that can refer to other chains.
2594 <dt>storage<dd>Storage location for the resulting polylines.
2595 <dt>method<dd>Approximation method (see the description of the function
2596 <a href="#decl_cvFindContours">cvFindContours</a>).
2597 <dt>parameter<dd>Method parameter (not used now).
2598 <dt>minimal_perimeter<dd>Approximates only those contours whose perimeters are not less
2599 than <code>minimal_perimeter</code>. Other chains are removed from the resulting structure.
2600 <dt>recursive<dd>If not 0, the function approximates all chains that access can be
2601 obtained to from <code>src_seq</code> by <code>h_next</code> or <code>v_next links</code>. If 0, the single chain is
2602 approximated.
2603 </dl><p>
2604 This is a stand-alone approximation routine. The function <code>cvApproxChains</code> works
2605 exactly in the same way as <a href="#decl_cvFindContours">cvFindContours</a> with the corresponding approximation flag.
2606 The function returns pointer to the first resultant contour.
2607 Other approximated contours, if any, can be accessed via <code>v_next</code> or
2608 <code>h_next</code> fields of the returned structure.
2609 </p>
2610
2611
2612 <hr><h3><a name="decl_cvStartReadChainPoints">StartReadChainPoints</a></h3>
2613 <p class="Blurb">Initializes chain reader</p>
2614 <pre>
2615 void cvStartReadChainPoints( CvChain* chain, CvChainPtReader* reader );
2616 </pre><p><dl>
2617 chain Pointer to chain.
2618 reader Chain reader state.
2619 </dl><p>
2620 The function <code>cvStartReadChainPoints</code> initializes a special reader
2621 (see <a href="opencvref_cxcore.htm#cxcore_ds">Dynamic Data Structures</a>
2622 for more information on sets and sequences).
2623 </p>
2624
2625
2626 <hr><h3><a name="decl_cvReadChainPoint">ReadChainPoint</a></h3>
2627 <p class="Blurb">Gets next chain point</p>
2628 <pre>
2629 CvPoint cvReadChainPoint( CvChainPtReader* reader );
2630 </pre><p><dl>
2631 <dt>reader<dd>Chain reader state.
2632 </dl><p>
2633 The function <code>cvReadChainPoint</code> returns the current chain point and updates the reader position.</p>
2634
2635
2636 <hr><h3><a name="decl_cvApproxPoly">ApproxPoly</a></h3>
2637 <p class="Blurb">Approximates polygonal curve(s) with desired precision</p>
2638 <pre>
2639 CvSeq* cvApproxPoly( const void* src_seq, int header_size, CvMemStorage* storage,
2640                      int method, double parameter, int parameter2=0 );
2641 </pre><p><dl>
2642 <dt>src_seq<dd>Sequence of array of points.
2643 <dt>header_size<dd>Header size of approximated curve[s].
2644 <dt>storage<dd>Container for approximated contours. If it is NULL, the input sequences' storage is used.
2645 <dt>method<dd>Approximation method; only <code>CV_POLY_APPROX_DP</code> is supported, that
2646 corresponds to Douglas-Peucker algorithm.
2647 <dt>parameter<dd>Method-specific parameter; in case of <code>CV_POLY_APPROX_DP</code> it is a desired approximation accuracy.
2648 <dt>parameter2<dd>If case if <code>src_seq</code> is sequence it means whether the single sequence should
2649 be approximated or all sequences on the same level or below <code>src_seq</code> (see <a href="#decl_cvFindContours">cvFindContours</a> for
2650 description of hierarchical contour structures). And if <code>src_seq</code> is array (<a href="#decl_CvMat">CvMat</a>*) of
2651 points, the parameter specifies whether the curve is closed (<code>parameter2</code>!=0) or
2652 not (<code>parameter2</code>=0).
2653 </dl><p>
2654 The function <code>cvApproxPoly</code> approximates one or more curves and returns the approximation
2655 result[s]. In case of multiple curves approximation the resultant tree will have the same structure as
2656 the input one (1:1 correspondence).
2657 </p>
2658
2659
2660 <hr><h3><a name="decl_cvBoundingRect">BoundingRect</a></h3>
2661 <p class="Blurb">Calculates up-right bounding rectangle of point set</p>
2662 <pre>
2663 CvRect cvBoundingRect( CvArr* points, int update=0 );
2664 </pre><p><dl>
2665 <dt>points<dd>Either a 2D point set, represented as a sequence (<code>CvSeq*</code>, <code>CvContour*</code>)
2666   or vector (<code>CvMat*</code>) of points,
2667   or 8-bit single-channel mask image (<code>CvMat*</code>, <code>IplImage*</code>),
2668   in which non-zero pixels are considered.
2669 <dt>update<dd>The update flag. Here is list of possible combination of the flag values and type of <code>contour</code>:
2670 <ul>
2671 <li><code>points</code> is CvContour*, <code>update</code>=0: the bounding rectangle is not calculated, but it is read from <code>rect</code> field of the contour header.
2672 <li><code>points</code> is CvContour*, <code>update</code>=1: the bounding rectangle is calculated and written to <code>rect</code> field of the contour header.
2673 For example, this mode is used by <a href="#decl_cvFindContours">cvFindContours</a>.
2674 <li><code>points</code> is CvSeq* or CvMat*: <code>update</code> is ignored,
2675 the bounding rectangle is calculated and returned.
2676 </ul></dl><p>
2677 The function <code>cvBoundingRect</code> returns the up-right bounding rectangle for 2d point set.
2678 </p>
2679
2680
2681 <hr><h3><a name="decl_cvContourArea">ContourArea</a></h3>
2682 <p class="Blurb">Calculates area of the whole contour or contour section</p>
2683 <pre>
2684 double cvContourArea( const CvArr* contour, CvSlice slice=CV_WHOLE_SEQ );
2685 </pre><p><dl>
2686 <dt>contour<dd>Contour (sequence or array of vertices).
2687 <dt>slice<dd>Starting and ending points of the contour section of interest, by default area of the whole
2688 contour is calculated.
2689 </dl><p>
2690 The function <code>cvContourArea</code> calculates area of the whole contour or contour section. In the latter
2691 case the total area bounded by the contour arc and the chord connecting the 2 selected points is calculated as
2692 shown on the picture below:</p>
2693 <p>
2694 <p>
2695 <img align="center" src="pics/contoursecarea.png" width=150 height=150 >
2696 </p>
2697 <p><b>NOTE:</b> Orientation of the contour affects the area sign, thus the function may return
2698 <code>negative</code> result. Use <code>fabs()</code> function from C runtime to get the absolute value of
2699 area.</p>
2700
2701
2702 <hr><h3><a name="decl_cvArcLength">ArcLength</a></h3>
2703 <p class="Blurb">Calculates contour perimeter or curve length</p>
2704 <pre>
2705 double cvArcLength( const void* curve, CvSlice slice=CV_WHOLE_SEQ, int is_closed=-1 );
2706 </pre><p><dl>
2707 <dt>curve<dd>Sequence or array of the curve points.
2708 <dt>slice<dd>Starting and ending points of the curve, by default the whole curve length is
2709 calculated.
2710 <dt>is_closed<dd>Indicates whether the curve is closed or not. There are 3 cases:<ul>
2711                 <li>is_closed=0 - the curve is assumed to be unclosed.
2712                 <li>is_closed&gt;0 - the curve is assumed to be closed.
2713                 <li>is_closed&lt;0 - if curve is sequence, the flag CV_SEQ_FLAG_CLOSED of
2714                     ((CvSeq*)curve)->flags is checked to determine if the curve is closed or not,
2715                      otherwise (curve is represented by array (CvMat*) of points) it is assumed
2716                      to be unclosed.
2717 </ul>
2718 </dl><p>
2719 The function <code>cvArcLength</code> calculates length or curve as sum of lengths of segments
2720 between subsequent points</p>
2721
2722 <hr><h3><a name="decl_cvCreateContourTree">CreateContourTree</a></h3>
2723 <p class="Blurb">Creates hierarchical representation of contour</p>
2724 <pre>
2725 CvContourTree* cvCreateContourTree( const CvSeq* contour, CvMemStorage* storage, double threshold );
2726 </pre><p><dl>
2727 <dt>contour<dd>Input contour.
2728 <dt>storage<dd>Container for output tree.
2729 <dt>threshold<dd>Approximation accuracy.
2730 </dl><p>
2731 The function <code>cvCreateContourTree</code> creates binary tree representation for the input
2732 <code>contour</code> and returns the pointer to its root. If the parameter <code>threshold</code>
2733 is less than or equal to 0, the function creates full binary tree
2734 representation. If the threshold is greater than 0, the function creates
2735 representation with the precision <code>threshold</code>: if the vertices with the
2736 interceptive area of its base line are less than <code>threshold</code>, the tree should not
2737 be built any further. The function returns the created tree.
2738 </p>
2739
2740
2741 <hr><h3><a name="decl_cvContourFromContourTree">ContourFromContourTree</a></h3>
2742 <p class="Blurb">Restores contour from tree</p>
2743 <pre>
2744 CvSeq* cvContourFromContourTree( const CvContourTree* tree, CvMemStorage* storage,
2745                                  CvTermCriteria criteria );
2746 </pre><p><dl>
2747 <dt>tree<dd>Contour tree.
2748 <dt>storage<dd>Container for the reconstructed contour.
2749 <dt>criteria<dd>Criteria, where to stop reconstruction.
2750 </dl><p>
2751 The function <code>cvContourFromContourTree</code> restores the contour from its binary tree
2752 representation. The parameter <code>criteria</code> determines the accuracy and/or the
2753 number of tree levels used for reconstruction, so it is possible to build approximated contour.
2754 The function returns reconstructed contour.
2755 </p>
2756
2757
2758 <hr><h3><a name="decl_cvMatchContourTrees">MatchContourTrees</a></h3>
2759 <p class="Blurb">Compares two contours using their tree representations</p>
2760 <pre>
2761 double cvMatchContourTrees( const CvContourTree* tree1, const CvContourTree* tree2,
2762                             int method, double threshold );
2763 </pre><p><dl>
2764 <dt>tree1<dd>First contour tree.
2765 <dt>tree2<dd>Second contour tree.
2766 <dt>method<dd>Similarity measure, only <code>CV_CONTOUR_TREES_MATCH_I1</code> is supported.
2767 <dt>threshold<dd>Similarity threshold.
2768 </dl><p>
2769 The function <code>cvMatchContourTrees</code> calculates the value of the matching measure for
2770 two contour trees. The similarity measure is calculated level by level from the
2771 binary tree roots. If at the certain level difference between contours becomes less than <code>threshold</code>,
2772 the reconstruction process is interrupted and the current difference is returned.
2773 </p>
2774
2775
2776 <hr><h2><a name="cv_sa_compgeom">Computational Geometry</a></h2>
2777
2778
2779 <hr><h3><a name="decl_cvMaxRect">MaxRect</a></h3>
2780 <p class="Blurb">Finds bounding rectangle for two given rectangles</p>
2781 <pre>
2782 CvRect cvMaxRect( const CvRect* rect1, const CvRect* rect2 );
2783 </pre><p><dl>
2784 <dt>rect1<dd>First rectangle
2785 <dt>rect2<dd>Second rectangle
2786 </dl></p><p>
2787 The function <code>cvMaxRect</code> finds minimum area rectangle that contains both input rectangles inside:</p>
2788 <p>
2789 <img align="center" src="pics/maxrect.png">
2790 </p>
2791
2792
2793 <hr><h3><a name="decl_CvBox2D">CvBox2D</a></h3>
2794 <p class="Blurb">Rotated 2D box</p>
2795 <pre>
2796 typedef struct CvBox2D
2797 {
2798     CvPoint2D32f center;  /* center of the box */
2799     CvSize2D32f  size;    /* box width and length */
2800     float angle;          /* angle between the horizontal axis
2801                              and the first side (i.e. length) in degrees */
2802 }
2803 CvBox2D;
2804 </pre>
2805
2806
2807 <hr><h3><a name="decl_cvPointSeqFromMat">PointSeqFromMat</a></h3>
2808 <p class="Blurb">Initializes point sequence header from a point vector</p>
2809 <pre>
2810 CvSeq* cvPointSeqFromMat( int seq_kind, const CvArr* mat,
2811                           CvContour* contour_header,
2812                           CvSeqBlock* block );
2813 </pre><p><dl>
2814 <dt>seq_kind<dd>Type of the point sequence: point set (0), a curve (<code>CV_SEQ_KIND_CURVE</code>),
2815                 closed curve (<code>CV_SEQ_KIND_CURVE+CV_SEQ_FLAG_CLOSED</code>) etc.
2816 <dt>mat<dd>Input matrix. It should be continuous 1-dimensional vector of points, that is, it should have
2817 type <code>CV_32SC2</code> or <code>CV_32FC2</code>.
2818 <dt>contour_header<dd>Contour header, initialized by the function.
2819 <dt>block<dd>Sequence block header, initialized by the function.
2820 </dl></p><p>
2821 The function <code>cvPointSeqFromMat</code> initializes sequence header to create a "virtual" sequence which
2822 elements reside in the specified matrix. No data is copied. The initialized sequence header may be passed to
2823 any function that takes a point sequence on input. No extra elements could be added to the sequence,
2824 but some may be removed. The function is a specialized variant of
2825 <a href="opencvref_cxcore.htm#decl_cvMakeSeqHeaderForArray">cvMakeSeqHeaderForArray</a> and uses the latter internally.
2826 It returns pointer to the initialized contour header. Note that the bounding rectangle (field <code>rect</code> of
2827 <code>CvContour</code> structure is not initialized by the function. If you need one, use
2828 <a href="#decl_cvBoundingRect">cvBoundingRect</a>.
2829 <p>Here is the simple usage example.</p>
2830 <pre>
2831 CvContour header;
2832 CvSeqBlock block;
2833 CvMat* vector = cvCreateMat( 1, 3, CV_32SC2 );
2834
2835 CV_MAT_ELEM( *vector, CvPoint, 0, 0 ) = cvPoint(100,100);
2836 CV_MAT_ELEM( *vector, CvPoint, 0, 1 ) = cvPoint(100,200);
2837 CV_MAT_ELEM( *vector, CvPoint, 0, 2 ) = cvPoint(200,100);
2838
2839 IplImage* img = cvCreateImage( cvSize(300,300), 8, 3 );
2840 cvZero(img);
2841
2842 cvDrawContours( img, cvPointSeqFromMat(CV_SEQ_KIND_CURVE+CV_SEQ_FLAG_CLOSED,
2843    vector, &amp;header, &amp;block), CV_RGB(255,0,0), CV_RGB(255,0,0), 0, 3, 8, cvPoint(0,0));
2844 </pre>
2845
2846
2847 <hr><h3><a name="decl_cvBoxPoints">BoxPoints</a></h3>
2848 <p class="Blurb">Finds box vertices</p>
2849 <pre>
2850 void cvBoxPoints( CvBox2D box, CvPoint2D32f pt[4] );
2851 </pre><p><dl>
2852 <dt>box<dd>Box
2853 <dt>pt<dd>Array of vertices
2854 </dl></p><p>
2855 The function <code>cvBoxPoints</code> calculates vertices of the input 2d box.
2856 Here is the function code:</p>
2857 <pre>
2858 void cvBoxPoints( CvBox2D box, CvPoint2D32f pt[4] )
2859 {
2860     double angle = box.angle*CV_PI/180.
2861     float a = (float)cos(angle)*0.5f;
2862     float b = (float)sin(angle)*0.5f;
2863
2864     pt[0].x = box.center.x - a*box.size.height - b*box.size.width;
2865     pt[0].y = box.center.y + b*box.size.height - a*box.size.width;
2866     pt[1].x = box.center.x + a*box.size.height - b*box.size.width;
2867     pt[1].y = box.center.y - b*box.size.height - a*box.size.width;
2868     pt[2].x = 2*box.center.x - pt[0].x;
2869     pt[2].y = 2*box.center.y - pt[0].y;
2870     pt[3].x = 2*box.center.x - pt[1].x;
2871     pt[3].y = 2*box.center.y - pt[1].y;
2872 }
2873 </pre>
2874
2875
2876 <hr><h3><a name="decl_cvFitEllipse">FitEllipse</a></h3>
2877 <p class="Blurb">Fits ellipse to set of 2D points</p>
2878 <pre>
2879 CvBox2D cvFitEllipse2( const CvArr* points );
2880 </pre><p><dl>
2881 <dt>points<dd>Sequence or array of points.
2882 </dl><p>
2883 The function <code>cvFitEllipse</code> calculates ellipse that fits best (in least-squares sense)
2884 to a set of 2D points. The meaning of the returned structure fields is similar to those
2885 in <a href="#decl_cvEllipse">cvEllipse</a> except that <code>size</code> stores the full lengths of the ellipse axises,
2886 not half-lengths</p>
2887
2888
2889 <hr><h3><a name="decl_cvFitLine2D">FitLine</a></h3>
2890 <p class="Blurb">Fits line to 2D or 3D point set</p>
2891 <pre>
2892 void  cvFitLine( const CvArr* points, int dist_type, double param,
2893                  double reps, double aeps, float* line );
2894 </pre><p><dl>
2895 <dt>points<dd>Sequence or array of 2D or 3D points with 32-bit integer or floating-point coordinates.
2896 <dt>dist_type<dd>The distance used for fitting (see the discussion).
2897 <dt>param<dd>Numerical parameter (<code>C</code>) for some types of distances, if 0 then some optimal value is chosen.
2898 <dt>reps, aeps<dd>Sufficient accuracy for radius (distance between the coordinate origin and the line)
2899 and angle, respectively, 0.01 would be a good defaults for both.
2900 <dt>line<dd>The output line parameters. In case of 2d fitting it is array of 4 floats <code>(vx, vy, x0, y0)</code>
2901 where <code>(vx, vy)</code> is a normalized vector collinear to the line and <code>(x0, y0)</code> is some point on the line.
2902 In case of 3D fitting it is array of 6 floats <code>(vx, vy, vz, x0, y0, z0)</code>
2903 where <code>(vx, vy, vz)</code> is a normalized vector collinear to the line and <code>(x0, y0, z0)</code> is some point on the line.
2904 </dl><p>
2905 The function <code>cvFitLine</code> fits line to 2D or 3D point set by minimizing sum<sub>i</sub>&rho;(r<sub>i</sub>),
2906 where r<sub>i</sub> is distance between i-th point and the line and &rho;(r) is a distance function, one of:</p>
2907 <pre>
2908 dist_type=CV_DIST_L2 (L<sub>2</sub>):
2909 &rho;(r)=r<sup>2</sup>/2 (the simplest and the fastest least-squares method)
2910
2911 dist_type=CV_DIST_L1 (L<sub>1</sub>):
2912 &rho;(r)=r
2913
2914 dist_type=CV_DIST_L12 (L<sub>1</sub>-L<sub>2</sub>):
2915 &rho;(r)=2&bull;[sqrt(1+r<sup>2</sup>/2) - 1]
2916
2917 dist_type=CV_DIST_FAIR (Fair):
2918 &rho;(r)=C<sup>2</sup>&bull;[r/C - log(1 + r/C)],  C=1.3998
2919
2920 dist_type=CV_DIST_WELSCH (Welsch):
2921 &rho;(r)=C<sup>2</sup>/2&bull;[1 - exp(-(r/C)<sup>2</sup>)],  C=2.9846
2922
2923 dist_type=CV_DIST_HUBER (Huber):
2924 &rho;(r)= r<sup>2</sup>/2,   if r &lt; C
2925       C&bull;(r-C/2),   otherwise;   C=1.345
2926
2927 </pre>
2928
2929 <hr><h3><a name="decl_cvConvexHull2">ConvexHull2</a></h3>
2930 <p class="Blurb">Finds convex hull of point set</p>
2931 <pre>
2932 CvSeq* cvConvexHull2( const CvArr* input, void* hull_storage=NULL,
2933                       int orientation=CV_CLOCKWISE, int return_points=0 );
2934 </pre><p><dl>
2935 <dt>points<dd>Sequence or array of 2D points with 32-bit integer or floating-point coordinates.
2936 <dt>hull_storage<dd>The destination array (CvMat*) or memory storage (CvMemStorage*) that will store the convex hull.
2937                    If it is array, it should be 1d and have the same number of elements as the input array/sequence.
2938                    On output the header is modified: the number of columns/rows is truncated down to the hull size.
2939 <dt>orientation<dd>Desired orientation of convex hull: <code>CV_CLOCKWISE</code> or <code>CV_COUNTER_CLOCKWISE</code>.
2940 <dt>return_points<dd>If non-zero, the points themselves will be stored
2941                     in the hull instead of indices if <code>hull_storage</code> is array, or pointers if <code>hull_storage</code> is memory storage.
2942 </dl><p>
2943 The function <code>cvConvexHull2</code> finds convex hull of 2D point set using Sklansky&#146;s algorithm.
2944 If <code>hull_storage</code> is memory storage, the function creates a sequence containing the hull points or
2945 pointers to them, depending on <code>return_points</code> value and returns the sequence on output.
2946 </p>
2947 <h4>Example. Building convex hull for a sequence or array of points</h4>
2948 <pre>
2949 #include "cv.h"
2950 #include "highgui.h"
2951 #include &lt;stdlib.h&gt;
2952
2953 #define ARRAY  0 /* switch between array/sequence method by replacing 0&lt;=&gt;1 */
2954
2955 void main( int argc, char** argv )
2956 {
2957     IplImage* img = cvCreateImage( cvSize( 500, 500 ), 8, 3 );
2958     cvNamedWindow( "hull", 1 );
2959
2960 #if !ARRAY
2961         CvMemStorage* storage = cvCreateMemStorage();
2962 #endif
2963
2964     for(;;)
2965     {
2966         int i, count = rand()%100 + 1, hullcount;
2967         CvPoint pt0;
2968 #if !ARRAY
2969         CvSeq* ptseq = cvCreateSeq( CV_SEQ_KIND_GENERIC|CV_32SC2, sizeof(CvContour),
2970                                      sizeof(CvPoint), storage );
2971         CvSeq* hull;
2972
2973         for( i = 0; i &lt; count; i++ )
2974         {
2975             pt0.x = rand() % (img->width/2) + img->width/4;
2976             pt0.y = rand() % (img->height/2) + img->height/4;
2977             cvSeqPush( ptseq, &pt0 );
2978         }
2979         hull = cvConvexHull2( ptseq, 0, CV_CLOCKWISE, 0 );
2980         hullcount = hull->total;
2981 #else
2982         CvPoint* points = (CvPoint*)malloc( count * sizeof(points[0]));
2983         int* hull = (int*)malloc( count * sizeof(hull[0]));
2984         CvMat point_mat = cvMat( 1, count, CV_32SC2, points );
2985         CvMat hull_mat = cvMat( 1, count, CV_32SC1, hull );
2986
2987         for( i = 0; i &lt; count; i++ )
2988         {
2989             pt0.x = rand() % (img->width/2) + img->width/4;
2990             pt0.y = rand() % (img->height/2) + img->height/4;
2991             points[i] = pt0;
2992         }
2993         cvConvexHull2( &point_mat, &hull_mat, CV_CLOCKWISE, 0 );
2994         hullcount = hull_mat.cols;
2995 #endif
2996         cvZero( img );
2997         for( i = 0; i &lt; count; i++ )
2998         {
2999 #if !ARRAY
3000             pt0 = *CV_GET_SEQ_ELEM( CvPoint, ptseq, i );
3001 #else
3002             pt0 = points[i];
3003 #endif
3004             cvCircle( img, pt0, 2, CV_RGB( 255, 0, 0 ), CV_FILLED );
3005         }
3006
3007 #if !ARRAY
3008         pt0 = **CV_GET_SEQ_ELEM( CvPoint*, hull, hullcount - 1 );
3009 #else
3010         pt0 = points[hull[hullcount-1]];
3011 #endif
3012
3013         for( i = 0; i &lt; hullcount; i++ )
3014         {
3015 #if !ARRAY
3016             CvPoint pt = **CV_GET_SEQ_ELEM( CvPoint*, hull, i );
3017 #else
3018             CvPoint pt = points[hull[i]];
3019 #endif
3020             cvLine( img, pt0, pt, CV_RGB( 0, 255, 0 ));
3021             pt0 = pt;
3022         }
3023
3024         cvShowImage( "hull", img );
3025
3026         int key = cvWaitKey(0);
3027         if( key == 27 ) // 'ESC'
3028             break;
3029
3030 #if !ARRAY
3031         cvClearMemStorage( storage );
3032 #else
3033         free( points );
3034         free( hull );
3035 #endif
3036     }
3037 }
3038 </pre>
3039
3040
3041 <hr><h3><a name="decl_cvCheckContourConvexity">CheckContourConvexity</a></h3>
3042 <p class="Blurb">Tests contour convex</p>
3043 <pre>
3044 int cvCheckContourConvexity( const CvArr* contour );
3045 </pre><p><dl>
3046 <dt>contour<dd>Tested contour (sequence or array of points).
3047 </dl><p>
3048 The function <code>cvCheckContourConvexity</code> tests whether the input contour is convex or not.
3049 The contour must be simple, i.e. without self-intersections.
3050 </p>
3051
3052
3053 <hr><h3><a name="decl_CvConvexityDefect">CvConvexityDefect</a></h3>
3054 <p class="Blurb">Structure describing a single contour convexity detect</p>
3055 <pre>
3056 typedef struct CvConvexityDefect
3057 {
3058     CvPoint* start; /* point of the contour where the defect begins */
3059     CvPoint* end; /* point of the contour where the defect ends */
3060     CvPoint* depth_point; /* the farthest from the convex hull point within the defect */
3061     float depth; /* distance between the farthest point and the convex hull */
3062 } CvConvexityDefect;
3063 </pre>
3064 <h4>Picture. Convexity defects of hand contour.</h4>
3065 <p>
3066 <img src="pics/defects.png" width=200 height=200>
3067 </p>
3068
3069
3070 <hr><h3><a name="decl_cvConvexityDefects">ConvexityDefects</a></h3>
3071 <p class="Blurb">Finds convexity defects of contour</p>
3072 <pre>
3073 CvSeq* cvConvexityDefects( const CvArr* contour, const CvArr* convexhull,
3074                            CvMemStorage* storage=NULL );
3075 </pre><p><dl>
3076 <dt>contour<dd>Input contour.
3077 <dt>convexhull<dd>Convex hull obtained using <a href="#decl_cvConvexHull2">cvConvexHull2</a> that should contain pointers or indices
3078 to the contour points, not the hull points themselves, i.e. <code>return_points</code> parameter in <a href="#decl_cvConvexHull2">cvConvexHull2</a>
3079 should be 0.
3080 <dt>storage<dd>Container for output sequence of convexity defects. If it is NULL, contour or hull
3081 (in that order) storage is used.
3082 </dl><p>
3083 The function <code>cvConvexityDefects</code> finds all convexity defects of the input contour
3084 and returns a sequence of the <a href="#decl_CvConvexityDefect">CvConvexityDefect</a> structures.
3085 </p>
3086
3087
3088 <hr><h3><a name="decl_cvPointPolygonTest">PointPolygonTest</a></h3>
3089 <p class="Blurb">Point in contour test</p>
3090 <pre>
3091 double cvPointPolygonTest( const CvArr* contour,
3092                            CvPoint2D32f pt, int measure_dist );
3093 </pre><p><dl>
3094 <dt>contour<dd>Input contour.
3095 <dt>pt<dd>The point tested against the contour.
3096 <dt>measure_dist<dd>If it is non-zero, the function estimates distance from the point to the nearest contour edge.
3097 </dl><p>
3098 The function <code>cvPointPolygonTest</code> determines whether the point is inside contour, outside, or lies
3099 on an edge (or coincides with a vertex). It returns positive, negative or zero value, correspondingly.
3100 When <code>measure_dist=0</code>, the return value is +1, -1 and 0, respectively.
3101 When <code>measure_dist&ne;0</code>, it is a signed distance between the point and the nearest contour edge.
3102 </p><p>Here is the sample output of the function, where each image pixel is tested against the contour.</p>
3103
3104 <p><img src="pics/pointpolygon.png" width=200 height=200></p>
3105
3106
3107 <hr><h3><a name="decl_cvMinAreaRect2">MinAreaRect2</a></h3>
3108 <p class="Blurb">Finds circumscribed rectangle of minimal area for given 2D point set</p>
3109 <pre>
3110 CvBox2D  cvMinAreaRect2( const CvArr* points, CvMemStorage* storage=NULL );
3111 </pre><p><dl>
3112 <dt>points<dd>Sequence or array of points.
3113 <dt>storage<dd>Optional temporary memory storage.
3114 </dl><p>
3115 The function <code>cvMinAreaRect2</code> finds a circumscribed rectangle of the minimal area for 2D point set
3116 by building convex hull for the set and applying rotating calipers technique to the hull.</p>
3117 <h4>Picture. Minimal-area bounding rectangle for contour</h4>
3118 <p>
3119 <img align=center src="pics/minareabox.png">
3120 </p>
3121
3122
3123 <hr><h3><a name="decl_cvMinEnclosingCircle">MinEnclosingCircle</a></h3>
3124 <p class="Blurb">Finds circumscribed circle of minimal area for given 2D point set</p>
3125 <pre>
3126 int cvMinEnclosingCircle( const CvArr* points, CvPoint2D32f* center, float* radius );
3127 </pre><p><dl>
3128 <dt>points<dd>Sequence or array of 2D points.
3129 <dt>center<dd>Output parameter. The center of the enclosing circle.
3130 <dt>radius<dd>Output parameter. The radius of the enclosing circle.
3131 </dl><p>
3132 The function <code>cvMinEnclosingCircle</code> finds the minimal circumscribed circle for
3133 2D point set using iterative algorithm. It returns nonzero if the resultant circle contains all the
3134 input points and zero otherwise (i.e. algorithm failed).
3135 </p>
3136
3137
3138 <hr><h3><a name="decl_cvCalcPGH">CalcPGH</a></h3>
3139 <p class="Blurb">Calculates pair-wise geometrical histogram for contour</p>
3140 <pre>
3141 void cvCalcPGH( const CvSeq* contour, CvHistogram* hist );
3142 </pre><p><dl>
3143 <dt>contour<dd>Input contour. Currently, only integer point coordinates are allowed.
3144 <dt>hist<dd>Calculated histogram; must be two-dimensional.
3145 </dl><p>
3146 The function <code>cvCalcPGH</code> calculates 2D pair-wise geometrical histogram (PGH), described in
3147 <a href="#paper_iivarinen97">[Iivarinen97]</a>, for the contour.
3148 The algorithm considers every pair of the contour edges. The angle
3149 between the edges and the minimum/maximum distances are determined for every
3150 pair. To do this each of the edges in turn is taken as the base, while the
3151 function loops through all the other edges. When the base edge and any other
3152 edge are considered, the minimum and maximum distances from the points on the
3153 non-base edge and line of the base edge are selected. The angle between the
3154 edges defines the row of the histogram in which all the bins that correspond to
3155 the distance between the calculated minimum and maximum distances are
3156 incremented (that is, the histogram is transposed relatively to [Iivarninen97] definition).
3157 The histogram can be used for contour matching.
3158 </p>
3159
3160
3161 <hr><h2><a name="cv_sa_subdiv">Planar Subdivisions</a></h2>
3162
3163 <hr><h3><a name="decl_CvSubdiv2D">CvSubdiv2D</a></h3>
3164 <p class="Blurb">Planar subdivision</p>
3165 <pre>
3166 #define CV_SUBDIV2D_FIELDS()    \
3167     CV_GRAPH_FIELDS()           \
3168     int  quad_edges;            \
3169     int  is_geometry_valid;     \
3170     CvSubdiv2DEdge recent_edge; \
3171     CvPoint2D32f  topleft;      \
3172     CvPoint2D32f  bottomright;
3173
3174 typedef struct CvSubdiv2D
3175 {
3176     CV_SUBDIV2D_FIELDS()
3177 }
3178 CvSubdiv2D;
3179 </pre><p>
3180 Planar subdivision is a subdivision of a plane into a set of non-overlapped regions (facets) that
3181 cover the whole plane. The above structure describes a subdivision built on 2d point set, where
3182 the points are linked together and form a planar graph, which, together with a few edges connecting
3183 exterior subdivision points (namely, convex hull points) with infinity, subdivides a plane into facets
3184 by its edges.
3185 </p><p>
3186 For every subdivision there exists dual subdivision there facets and points (subdivision vertices)
3187 swap their roles, that is, a facet is treated as a vertex (called virtual point below) of dual subdivision
3188 and the original subdivision vertices become facets. On the picture below original subdivision is marked with solid lines
3189 and dual subdivision with dot lines</p>
3190 <p>
3191 <img src="pics/subdiv.png">
3192 </p><p>
3193 OpenCV subdivides plane into triangles using Delaunay&#146;s algorithm.
3194 Subdivision is built iteratively starting from a dummy triangle that includes
3195 all the subdivision points for sure.
3196 In this case the dual subdivision is Voronoi diagram of input 2d point set.
3197 The subdivisions can be used for 3d piece-wise transformation of a plane, morphing, fast location of
3198 points on the plane, building special graphs (such as NNG,RNG) etc.</p>
3199
3200
3201 <hr><h3><a name="decl_CvQuadEdge2D">CvQuadEdge2D</a></h3>
3202 <p class="Blurb">Quad-edge of planar subdivision</p>
3203 <pre>
3204 /* one of edges within quad-edge, lower 2 bits is index (0..3)
3205    and upper bits are quad-edge pointer */
3206 typedef long CvSubdiv2DEdge;
3207
3208 /* quad-edge structure fields */
3209 #define CV_QUADEDGE2D_FIELDS()     \
3210     int flags;                     \
3211     struct CvSubdiv2DPoint* pt[4]; \
3212     CvSubdiv2DEdge  next[4];
3213
3214 typedef struct CvQuadEdge2D
3215 {
3216     CV_QUADEDGE2D_FIELDS()
3217 }
3218 CvQuadEdge2D;
3219 </pre><p>
3220 Quad-edge is a basic element of subdivision, it contains four edges (e, eRot (in red) and reversed e &amp; eRot (in green)):
3221 </p><p>
3222 <img src="pics/quadedge.png" width=200 height=200>
3223 </p>
3224
3225
3226 <hr><h3><a name="decl_CvSubdiv2DPoint">CvSubdiv2DPoint</a></h3>
3227 <p class="Blurb">Point of original or dual subdivision</p>
3228 <pre>
3229 #define CV_SUBDIV2D_POINT_FIELDS()\
3230     int            flags;      \
3231     CvSubdiv2DEdge first;      \
3232     CvPoint2D32f   pt;
3233
3234 #define CV_SUBDIV2D_VIRTUAL_POINT_FLAG (1 &lt;&lt; 30)
3235
3236 typedef struct CvSubdiv2DPoint
3237 {
3238     CV_SUBDIV2D_POINT_FIELDS()
3239 }
3240 CvSubdiv2DPoint;
3241 </pre>
3242
3243
3244 <hr><h3><a name="decl_cvSubdiv2DGetEdge">Subdiv2DGetEdge</a></h3>
3245 <p class="Blurb">Returns one of edges related to given</p>
3246 <pre>
3247 CvSubdiv2DEdge  cvSubdiv2DGetEdge( CvSubdiv2DEdge edge, CvNextEdgeType type );
3248 #define cvSubdiv2DNextEdge( edge ) cvSubdiv2DGetEdge( edge, CV_NEXT_AROUND_ORG )
3249 </pre><p><dl>
3250 <dt>edge<dd>Subdivision edge (not a quad-edge)
3251 <dt>type<dd>Specifies, which of related edges to return, one of:<ul>
3252 <li>CV_NEXT_AROUND_ORG - next around the edge origin (<code>eOnext</code> on the picture above if <code>e</code> is the input edge)
3253 <li>CV_NEXT_AROUND_DST - next around the edge vertex (<code>eDnext</code>)
3254 <li>CV_PREV_AROUND_ORG - previous around the edge origin (reversed <code>eRnext</code>)
3255 <li>CV_PREV_AROUND_DST - previous around the edge destination (reversed <code>eLnext</code>)
3256 <li>CV_NEXT_AROUND_LEFT - next around the left facet (<code>eLnext</code>)
3257 <li>CV_NEXT_AROUND_RIGHT - next around the right facet (<code>eRnext</code>)
3258 <li>CV_PREV_AROUND_LEFT - previous around the left facet (reversed <code>eOnext</code>)
3259 <li>CV_PREV_AROUND_RIGHT - previous around the right facet (reversed <code>eDnext</code>)
3260 </ul>
3261 </dl><p>
3262 The function <code>cvSubdiv2DGetEdge</code> returns one the edges related to the input edge.
3263 </p>
3264
3265
3266 <hr><h3><a name="decl_cvSubdiv2DRotateEdge">Subdiv2DRotateEdge</a></h3>
3267 <p class="Blurb">Returns another edge of the same quad-edge</p>
3268 <pre>
3269 CvSubdiv2DEdge  cvSubdiv2DRotateEdge( CvSubdiv2DEdge edge, int rotate );
3270 </pre><p><dl>
3271 <dt>edge<dd>Subdivision edge (not a quad-edge)
3272 <dt>type<dd>Specifies, which of edges of the same quad-edge as the input one to return, one of:<ul>
3273 <li>0 - the input edge (<code>e</code> on the picture above if <code>e</code> is the input edge)
3274 <li>1 - the rotated edge (<code>eRot</code>)
3275 <li>2 - the reversed edge (reversed <code>e</code> (in green))
3276 <li>3 - the reversed rotated edge (reversed <code>eRot</code> (in green))
3277 </ul>
3278 </dl><p>
3279 The function <code>cvSubdiv2DRotateEdge</code> returns one the edges of the same quad-edge as the input edge.
3280 </p>
3281
3282
3283 <hr><h3><a name="decl_cvSubdiv2DEdgeOrg">Subdiv2DEdgeOrg</a></h3>
3284 <p class="Blurb">Returns edge origin</p>
3285 <pre>
3286 CvSubdiv2DPoint* cvSubdiv2DEdgeOrg( CvSubdiv2DEdge edge );
3287 </pre><p><dl>
3288 <dt>edge<dd>Subdivision edge (not a quad-edge)
3289 </dl><p>
3290 The function <code>cvSubdiv2DEdgeOrg</code> returns the edge origin. The returned pointer may be NULL if
3291 the edge is from dual subdivision and the virtual point coordinates are not calculated yet.
3292 The virtual points can be calculated using function <a href="#decl_cvCalcSubdivVoronoi2D">cvCalcSubdivVoronoi2D</a>.
3293 </p>
3294
3295 <hr><h3><a name="decl_cvSubdiv2DEdgeDst">Subdiv2DEdgeDst</a></h3>
3296 <p class="Blurb">Returns edge destination</p>
3297 <pre>
3298 CvSubdiv2DPoint* cvSubdiv2DEdgeDst( CvSubdiv2DEdge edge );
3299 </pre><p><dl>
3300 <dt>edge<dd>Subdivision edge (not a quad-edge)
3301 </dl><p>
3302 The function <code>cvSubdiv2DEdgeDst</code> returns the edge destination. The returned pointer may be NULL if
3303 the edge is from dual subdivision and the virtual point coordinates are not calculated yet.
3304 The virtual points can be calculated using function <a href="#decl_cvCalcSubdivVoronoi2D">cvCalcSubdivVoronoi2D</a>.
3305 </p>
3306
3307
3308 <hr><h3><a name="decl_cvCreateSubdivDelaunay2D">CreateSubdivDelaunay2D</a></h3>
3309 <p class="Blurb">Creates empty Delaunay triangulation</p>
3310 <pre>
3311 CvSubdiv2D* cvCreateSubdivDelaunay2D( CvRect rect, CvMemStorage* storage );
3312 </pre><p><dl>
3313 <dt>rect<dd>Rectangle that includes all the 2d points that are to be added to subdivision.
3314 <dt>storage<dd>Container for subdivision.
3315 </dl><p>
3316 The function <code>cvCreateSubdivDelaunay2D</code> creates an empty Delaunay subdivision,
3317 where 2d points can be added further using function <a href="#decl_cvSubdivDelaunay2DInsert">cvSubdivDelaunay2DInsert</a>.
3318 All the points to be added must be within the specified rectangle, otherwise a runtime error will be
3319 raised.
3320 </p>
3321
3322
3323 <hr><h3><a name="decl_cvSubdivDelaunay2DInsert">SubdivDelaunay2DInsert</a></h3>
3324 <p class="Blurb">Inserts a single point to Delaunay triangulation</p>
3325 <pre>
3326 CvSubdiv2DPoint*  cvSubdivDelaunay2DInsert( CvSubdiv2D* subdiv, CvPoint2D32f pt);
3327 </pre><p><dl>
3328 <dt>subdiv<dd>Delaunay subdivision created by function <a href="#decl_cvCreateSubdivDelaunay2D">cvCreateSubdivDelaunay2D</a>.
3329 <dt>pt<dd>Inserted point.
3330 </dl><p>
3331 The function <code>cvSubdivDelaunay2DInsert</code> inserts a single point to subdivision and
3332 modifies the subdivision topology appropriately.
3333 If a points with same coordinates exists already, no new points is added.
3334 The function returns pointer to the allocated point.
3335 No virtual points coordinates is calculated at this stage.
3336 </p>
3337
3338
3339 <hr><h3><a name="decl_cvSubdiv2DLocate">Subdiv2DLocate</a></h3>
3340 <p class="Blurb">Inserts a single point to Delaunay triangulation</p>
3341 <pre>
3342 CvSubdiv2DPointLocation  cvSubdiv2DLocate( CvSubdiv2D* subdiv, CvPoint2D32f pt,
3343                                            CvSubdiv2DEdge* edge,
3344                                            CvSubdiv2DPoint** vertex=NULL );
3345 </pre><p><dl>
3346 <dt>subdiv<dd>Delaunay or another subdivision.
3347 <dt>pt<dd>The point to locate.
3348 <dt>edge<dd>The output edge the point falls onto or right to.
3349 <dt>vertex<dd>Optional output vertex double pointer the input point coincides with.
3350 </dl><p>
3351 The function <code>cvSubdiv2DLocate</code> locates input point within subdivision.
3352 There are 5 cases:<ul>
3353 <li>point falls into some facet. The function returns CV_PTLOC_INSIDE and <code>*edge</code> will contain one of edges of the facet.
3354 <li>point falls onto the edge. The function returns CV_PTLOC_ON_EDGE and <code>*edge</code> will contain this edge.
3355 <li>point coincides with one of subdivision vertices. The function returns CV_PTLOC_VERTEX and <code>*vertex</code> will contain pointer to the vertex.
3356 <li>point is outside the subdivision reference rectangle. The function returns CV_PTLOC_OUTSIDE_RECT and no pointers is filled.
3357 <li>one of input arguments is invalid. Runtime error is raised or, if silent or "parent" error processing mode
3358 is selected, CV_PTLOC_ERROR is returned.
3359 </ul>
3360 </p>
3361
3362
3363 <hr><h3><a name="decl_cvFindNearestPoint2D">FindNearestPoint2D</a></h3>
3364 <p class="Blurb">Finds the closest subdivision vertex to given point</p>
3365 <pre>
3366 CvSubdiv2DPoint* cvFindNearestPoint2D( CvSubdiv2D* subdiv, CvPoint2D32f pt );
3367 </pre><p><dl>
3368 <dt>subdiv<dd>Delaunay or another subdivision.
3369 <dt>pt<dd>Input point.
3370 </dl><p>
3371 The function <code>cvFindNearestPoint2D</code> is another function that locates input point within subdivision.
3372 It finds subdivision vertex that is the closest to the input point. It is not necessarily one of
3373 vertices of the facet containing the input point, though the facet (located using <a href="#decl_cvSubdiv2DLocate">cvSubdiv2DLocate</a>)
3374 is used as a starting point. The function returns pointer to the found subdivision vertex</code>
3375
3376
3377 <hr><h3><a name="decl_cvCalcSubdivVoronoi2D">CalcSubdivVoronoi2D</a></h3>
3378 <p class="Blurb">Calculates coordinates of Voronoi diagram cells</p>
3379 <pre>
3380 void cvCalcSubdivVoronoi2D( CvSubdiv2D* subdiv );
3381 </pre><p><dl>
3382 <dt>subdiv<dd>Delaunay subdivision, where all the points are added already.
3383 </dl><p>
3384 The function <code>cvCalcSubdivVoronoi2D</code> calculates coordinates of virtual points.
3385 All virtual points corresponding to some vertex of original subdivision form (when connected together)
3386 a boundary of Voronoi cell of that point.
3387 </p>
3388
3389
3390 <hr><h3><a name="decl_cvClearSubdivVoronoi2D">ClearSubdivVoronoi2D</a></h3>
3391 <p class="Blurb">Removes all virtual points</p>
3392 <pre>
3393 void cvClearSubdivVoronoi2D( CvSubdiv2D* subdiv );
3394 </pre><p><dl>
3395 <dt>subdiv<dd>Delaunay subdivision.
3396 </dl><p>
3397 The function <code>cvClearSubdivVoronoi2D</code> removes all virtual points.
3398 It is called internally in <a href="#decl_cvCalcSubdivVoronoi2D">cvCalcSubdivVoronoi2D</a> if the subdivision was modified
3399 after previous call to the function.
3400 </p>
3401
3402 <hr><p>
3403 There are a few other lower-level functions that work with planar subdivisions, see cv.h
3404 and the sources. Demo script delaunay.c that builds Delaunay triangulation and Voronoi diagram of
3405 random 2d point set can be found at opencv/samples/c.
3406 </p>
3407
3408
3409 <hr><h1><a name="cv_motion">Motion Analysis and Object Tracking Reference</a></h1>
3410
3411
3412 <hr><h2><a name="cv_motion_acc">Accumulation of Background Statistics</a></h2>
3413
3414 <hr><h3><a name="decl_cvAcc">Acc</a></h3>
3415 <p class="Blurb">Adds frame to accumulator</p>
3416 <pre>
3417 void cvAcc( const CvArr* image, CvArr* sum, const CvArr* mask=NULL );
3418 </pre><p><dl>
3419 <dt>image<dd>Input image, 1- or 3-channel, 8-bit or 32-bit floating point.
3420          (each channel of multi-channel image is processed independently).
3421 <dt>sum<dd>Accumulator of the same number of channels as input image, 32-bit floating-point.
3422 <dt>mask<dd>Optional operation mask.
3423 </dl></p><p>
3424 The function <code>cvAcc</code> adds the whole image <code>image</code> or its selected region to accumulator <code>sum</code>:</p>
3425 <pre>
3426 sum(x,y)=sum(x,y)+image(x,y) if mask(x,y)!=0
3427 </pre>
3428
3429
3430 <hr><h3><a name="decl_cvSquareAcc">SquareAcc</a></h3>
3431 <p class="Blurb">Adds the square of source image to accumulator</p>
3432 <pre>
3433 void cvSquareAcc( const CvArr* image, CvArr* sqsum, const CvArr* mask=NULL );
3434 </pre><p><dl>
3435 <dt>image<dd>Input image, 1- or 3-channel, 8-bit or 32-bit floating point
3436          (each channel of multi-channel image is processed independently).
3437 <dt>sqsum<dd>Accumulator of the same number of channels as input image, 32-bit or 64-bit floating-point.
3438 <dt>mask<dd>Optional operation mask.
3439 </dl></p><p>
3440 The function <code>cvSquareAcc</code> adds the input image <code>image</code> or its selected region,
3441 raised to power 2, to the accumulator <code>sqsum</code>:</p>
3442 <pre>
3443 sqsum(x,y)=sqsum(x,y)+image(x,y)<sup>2</sup> if mask(x,y)!=0
3444 </pre>
3445
3446
3447 <hr><h3><a name="decl_cvMultiplyAcc">MultiplyAcc</a></h3>
3448 <p class="Blurb">Adds product of two input images to accumulator</p>
3449 <pre>
3450 void cvMultiplyAcc( const CvArr* image1, const CvArr* image2, CvArr* acc, const CvArr* mask=NULL );
3451 </pre><p><dl>
3452 <dt>image1<dd>First input image, 1- or 3-channel, 8-bit or 32-bit floating point
3453          (each channel of multi-channel image is processed independently).
3454 <dt>image2<dd>Second input image, the same format as the first one.
3455 <dt>acc<dd>Accumulator of the same number of channels as input images, 32-bit or 64-bit floating-point.
3456 <dt>mask<dd>Optional operation mask.
3457 </dl></p><p>
3458 The function <code>cvMultiplyAcc</code> adds product of 2 images
3459 or their selected regions to accumulator <code>acc</code>:</p>
3460 <pre>
3461 acc(x,y)=acc(x,y) + image1(x,y)&bull;image2(x,y) if mask(x,y)!=0
3462 </pre>
3463
3464
3465 <hr><h3><a name="decl_cvRunningAvg">RunningAvg</a></h3>
3466 <p class="Blurb">Updates running average</p>
3467 <pre>
3468 void cvRunningAvg( const CvArr* image, CvArr* acc, double alpha, const CvArr* mask=NULL );
3469 </pre><p><dl>
3470 <dt>image<dd>Input image, 1- or 3-channel, 8-bit or 32-bit floating point
3471           (each channel of multi-channel image is processed independently).
3472 <dt>acc<dd>Accumulator of the same number of channels as input image, 32-bit or 64-bit floating-point.
3473 <dt>alpha<dd>Weight of input image.
3474 <dt>mask<dd>Optional operation mask.
3475 </dl></p><p>
3476 The function <code>cvRunningAvg</code> calculates weighted sum of input image <code>image</code> and
3477 the accumulator <code>acc</code> so that <code>acc</code> becomes a running average of frame sequence:</p>
3478 <pre>
3479 acc(x,y)=(1-&alpha;)&bull;acc(x,y) + &alpha;&bull;image(x,y) if mask(x,y)!=0
3480 </pre><p>
3481 where &alpha; (alpha) regulates update speed (how fast accumulator forgets about previous frames).
3482 </p>
3483
3484
3485 <hr><h2><a name="cv_motion_motempl">Motion Templates</a></h2>
3486
3487 <hr><h3><a name="decl_cvUpdateMotionHistory">UpdateMotionHistory</a></h3>
3488 <p class="Blurb">Updates motion history image by moving silhouette</p>
3489 <pre>
3490 void cvUpdateMotionHistory( const CvArr* silhouette, CvArr* mhi,
3491                             double timestamp, double duration );
3492 </pre><p><dl>
3493 <dt>silhouette<dd>Silhouette mask that has non-zero pixels where the motion occurs.
3494 <dt>mhi<dd>Motion history image, that is updated by the function (single-channel, 32-bit floating-point)
3495 <dt>timestamp<dd>Current time in milliseconds or other units.
3496 <dt>duration<dd>Maximal duration of motion track in the same units as <code>timestamp</code>.
3497 </dl></p><p>
3498 The function <code>cvUpdateMotionHistory</code> updates the motion history image as following:</p>
3499 <pre>
3500 mhi(x,y)=timestamp  if silhouette(x,y)!=0
3501          0          if silhouette(x,y)=0 and mhi(x,y)&lt;timestamp-duration
3502          mhi(x,y)   otherwise
3503 </pre><p>
3504 That is, MHI pixels where motion occurs are set to the current timestamp, while the pixels
3505 where motion happened far ago are cleared.
3506 </p>
3507
3508
3509 <hr><h3><a name="decl_cvCalcMotionGradient">CalcMotionGradient</a></h3>
3510 <p class="Blurb">Calculates gradient orientation of motion history image</p>
3511 <pre>
3512 void cvCalcMotionGradient( const CvArr* mhi, CvArr* mask, CvArr* orientation,
3513                            double delta1, double delta2, int aperture_size=3 );
3514 </pre><p><dl>
3515 <dt>mhi<dd>Motion history image.
3516 <dt>mask<dd>Mask image; marks pixels where motion gradient data is correct. Output
3517 parameter.
3518 <dt>orientation<dd>Motion gradient orientation image; contains angles from 0 to ~360&deg;.
3519 <dt>delta1, delta2<dd>The function finds minimum (m(x,y)) and maximum (M(x,y)) mhi values over
3520 each pixel (x,y) neighborhood and assumes the gradient is valid only if
3521 <pre>min(delta1,delta2) &lt;= M(x,y)-m(x,y) &lt;= max(delta1,delta2).</pre>
3522 <dt>aperture_size<dd>Aperture size of derivative operators used by the function:
3523 CV_SCHARR, 1, 3, 5 or 7 (see <a href="#decl_cvSobel">cvSobel</a>).
3524 </dl></p><p>
3525 The function <code>cvCalcMotionGradient</code> calculates the derivatives <code>Dx</code> and <code>Dy</code> of
3526 <code>mhi</code> and then calculates gradient orientation as:</p>
3527 <pre>
3528 orientation(x,y)=arctan(Dy(x,y)/Dx(x,y))
3529 </pre>
3530 <p>
3531 where both <code>Dx(x,y)</code>' and <code>Dy(x,y)</code>' signs are taken into account
3532 (as in <a href="opencvref_cxcore.htm#decl_cvCartToPolar">cvCartToPolar</a> function).
3533 After that <code>mask</code> is filled to indicate
3534 where the orientation is valid (see <code>delta1</code> and <code>delta2</code> description).
3535 </p>
3536
3537
3538 <hr><h3><a name="decl_cvCalcGlobalOrientation">CalcGlobalOrientation</a></h3>
3539 <p class="Blurb">Calculates global motion orientation of some selected region</p>
3540 <pre>
3541 double cvCalcGlobalOrientation( const CvArr* orientation, const CvArr* mask, const CvArr* mhi,
3542                                 double timestamp, double duration );
3543 </pre><p><dl>
3544 <dt>orientation<dd>Motion gradient orientation image; calculated by the function
3545 <a href="#decl_cvCalcMotionGradient">cvCalcMotionGradient</a>.
3546 <dt>mask<dd>Mask image. It may be a conjunction of valid gradient mask, obtained with
3547 <a href="#decl_cvCalcMotionGradient">cvCalcMotionGradient</a> and mask of the region, whose direction needs to be
3548 calculated.
3549 <dt>mhi<dd>Motion history image.
3550 <dt>timestamp<dd>Current time in milliseconds or other units, it is better to store time passed to
3551 <a href="#decl_cvUpdateMotionHistory">cvUpdateMotionHistory</a> before and reuse it here, because running <a href="#decl_cvUpdateMotionHistory">cvUpdateMotionHistory</a>
3552 and <a href="#decl_cvCalcMotionGradient">cvCalcMotionGradient</a> on large images may take some time.
3553 <dt>duration<dd>Maximal duration of motion track in milliseconds, the same as in <a href="#decl_cvUpdateMotionHistory">cvUpdateMotionHistory</a>.
3554 </dl></p><p>
3555 The function <code>cvCalcGlobalOrientation</code>
3556 calculates the general motion direction in
3557 the selected region and returns the angle between 0&deg; and 360&deg;.
3558 At first the function builds the orientation histogram and finds the basic
3559 orientation as a coordinate of the histogram maximum. After that the function
3560 calculates the shift relative to the basic orientation as a weighted sum of all
3561 orientation vectors: the more recent is the motion, the greater is the weight.
3562 The resultant angle is a circular sum of the basic orientation and the shift.
3563
3564
3565 <hr><h3><a name="decl_cvSegmentMotion">SegmentMotion</a></h3>
3566 <p class="Blurb">Segments whole motion into separate moving parts</p>
3567 <pre>
3568 CvSeq* cvSegmentMotion( const CvArr* mhi, CvArr* seg_mask, CvMemStorage* storage,
3569                         double timestamp, double seg_thresh );
3570 </pre><p><dl>
3571 <dt>mhi<dd>Motion history image.
3572 <dt>seg_mask<dd>Image where the mask found should be stored, single-channel, 32-bit floating-point.
3573 <dt>storage<dd>Memory storage that will contain a sequence of motion connected components.
3574 <dt>timestamp<dd>Current time in milliseconds or other units.
3575 <dt>seg_thresh<dd>Segmentation threshold; recommended to be equal to the interval
3576 between motion history "steps" or greater.
3577 </dl></p><p>
3578 The function <code>cvSegmentMotion</code> finds all the motion segments and marks them in <code>seg_mask</code>
3579 with individual values each (1,2,...). It also returns a sequence of <a href="#decl_CvConnectedComp">CvConnectedComp</a> structures,
3580 one per each motion components. After than the motion direction for every component can be calculated
3581 with <a href="#decl_cvCalcGlobalOrientation">cvCalcGlobalOrientation</a> using extracted mask of the particular component
3582 (using <a href="opencvref_cxcore.htm#decl_cvCmp">cvCmp</a>)
3583 </p>
3584
3585
3586 <hr><h2><a name="cv_motion_tracking">Object Tracking</a></h2>
3587
3588
3589 <hr><h3><a name="decl_cvMeanShift">MeanShift</a></h3>
3590 <p class="Blurb">Finds object center on back projection</p>
3591 <pre>
3592 int cvMeanShift( const CvArr* prob_image, CvRect window,
3593                  CvTermCriteria criteria, CvConnectedComp* comp );
3594 </pre><p><dl>
3595 <dt>prob_image<dd>Back projection of object histogram (see <a href="#decl_cvCalcBackProject">cvCalcBackProject</a>).
3596 <dt>window<dd>Initial search window.
3597 <dt>criteria<dd>Criteria applied to determine when the window search should be
3598 finished.
3599 <dt>comp<dd>Resultant structure that contains converged search window coordinates
3600 (<code>comp->rect</code> field) and sum of all pixels inside the window (<code>comp->area</code> field).
3601 </dl></p><p>
3602 The function <code>cvMeanShift</code> iterates to find the object center given its back projection and
3603 initial position of search window. The iterations are made until the search window
3604 center moves by less than the given value and/or until the function has done the
3605 maximum number of iterations. The function returns the number of iterations
3606 made.
3607 </p>
3608
3609
3610 <hr><h3><a name="decl_cvCamShift">CamShift</a></h3>
3611 <p class="Blurb">Finds object center, size, and orientation</p>
3612 <pre>
3613 int cvCamShift( const CvArr* prob_image, CvRect window, CvTermCriteria criteria,
3614                 CvConnectedComp* comp, CvBox2D* box=NULL );
3615 </pre><p><dl>
3616 <dt>prob_image<dd>Back projection of object histogram (see <a href="#decl_cvCalcBackProject">cvCalcBackProject</a>).
3617 <dt>window<dd>Initial search window.
3618 <dt>criteria<dd>Criteria applied to determine when the window search should be
3619 finished.
3620 <dt>comp<dd>Resultant structure that contains converged search window coordinates
3621 (<code>comp->rect</code> field) and sum of all pixels inside the window (<code>comp->area</code> field).
3622 <dt>box<dd>Circumscribed box for the object. If not <code>NULL</code>, contains object size and
3623 orientation.
3624 </dl></p><p>
3625 The function <code>cvCamShift</code> implements CAMSHIFT object tracking
3626 algorithm (<a href="#paper_bradski98">[Bradski98]</a>).
3627 First, it finds an object center using <a href="#decl_cvMeanShift">cvMeanShift</a> and,
3628 after that, calculates the object size and orientation. The function returns
3629 number of iterations made within <a href="#decl_cvMeanShift">cvMeanShift</a>.
3630 </p><p>
3631 <a href="#decl_CvCamShiftTracker">CvCamShiftTracker</a> class declared in cv.hpp implements color object tracker that uses
3632 the function.
3633 </p>
3634
3635
3636 <hr><h3><a name="decl_cvSnakeImage">SnakeImage</a></h3>
3637 <p class="Blurb">Changes contour position to minimize its energy</p>
3638 <pre>
3639 void cvSnakeImage( const IplImage* image, CvPoint* points, int length,
3640                    float* alpha, float* beta, float* gamma, int coeff_usage,
3641                    CvSize win, CvTermCriteria criteria, int calc_gradient=1 );
3642 </pre><p><dl>
3643 <dt>image<dd>The source image or external energy field.
3644 <dt>points<dd>Contour points (snake).
3645 <dt>length<dd>Number of points in the contour.
3646 <dt>alpha<dd>Weight[s] of continuity energy, single float or array of <code>length</code> floats,
3647              one per each contour point.
3648 <dt>beta<dd>Weight[s] of curvature energy, similar to <code>alpha</code>.
3649 <dt>gamma<dd>Weight[s] of image energy, similar to <code>alpha</code>.
3650 <dt>coeff_usage<dd>Variant of usage of the previous three parameters:
3651 <ul>
3652 <li><code>CV_VALUE</code> indicates that each of <code>alpha, beta, gamma</code> is a pointer to a single
3653   value to be used for all points;
3654 <li><code>CV_ARRAY</code> indicates that each of <code>alpha, beta, gamma</code> is a pointer to an array
3655   of coefficients different for all the points of the snake. All the arrays must
3656   have the size equal to the contour size.
3657 </ul>
3658 <dt>win<dd>Size of neighborhood of every point used to search the minimum, both <code>win.width</code> and
3659 <code>win.height</code> must be odd.
3660 <dt>criteria<dd>Termination criteria.
3661 <dt>calc_gradient<dd>Gradient flag. If not 0, the function calculates gradient magnitude for every image pixel and
3662 considers it as the energy field, otherwise the input image itself is considered.
3663 </dl></p><p>
3664 The function <code>cvSnakeImage</code> updates snake in order to minimize its total energy that is a sum
3665 of internal energy that depends on contour shape (the smoother contour is, the smaller internal energy is)
3666 and external energy that depends on the energy field and reaches minimum at the local energy extremums
3667 that correspond to the image edges in case of image gradient.</p><p>
3668 The parameter <code>criteria.epsilon</code> is used to define the minimal number of points
3669 that must be moved during any iteration to keep the iteration process running.
3670 <p>
3671 If at some iteration the number of moved points is less than <code>criteria.epsilon</code> or the function
3672 performed <code>criteria.max_iter</code> iterations, the function terminates.
3673 </p>
3674
3675
3676 <hr><h2><a name="cv_motion_optflow">Optical Flow</a></h2>
3677
3678 <hr><h3><a name="decl_cvCalcOpticalFlowHS">CalcOpticalFlowHS</a></h3>
3679 <p class="Blurb">Calculates optical flow for two images</p>
3680 <pre>
3681 void cvCalcOpticalFlowHS( const CvArr* prev, const CvArr* curr, int use_previous,
3682                           CvArr* velx, CvArr* vely, double lambda,
3683                           CvTermCriteria criteria );
3684 </pre><p><dl>
3685 <dt>prev<dd>First image, 8-bit, single-channel.
3686 <dt>curr<dd>Second image, 8-bit, single-channel.
3687 <dt>use_previous<dd>Uses previous (input) velocity field.
3688 <dt>velx<dd>Horizontal component of the optical flow of the same size as input images,
3689             32-bit floating-point, single-channel.
3690 <dt>vely<dd>Vertical component of the optical flow of the same size as input images,
3691             32-bit floating-point, single-channel.
3692 <dt>lambda<dd>Lagrangian multiplier.
3693 <dt>criteria<dd>Criteria of termination of velocity computing.
3694 </dl></p><p>
3695 The function <code>cvCalcOpticalFlowHS</code> computes flow for every pixel of the first input image using
3696 Horn & Schunck algorithm <a href="#paper_horn81">[Horn81]</a>.
3697 </p>
3698
3699
3700 <hr><h3><a name="decl_cvCalcOpticalFlowLK">CalcOpticalFlowLK</a></h3>
3701 <p class="Blurb">Calculates optical flow for two images</p>
3702 <pre>
3703 void cvCalcOpticalFlowLK( const CvArr* prev, const CvArr* curr, CvSize win_size,
3704                           CvArr* velx, CvArr* vely );
3705 </pre><p><dl>
3706 <dt>prev<dd>First image, 8-bit, single-channel.
3707 <dt>curr<dd>Second image, 8-bit, single-channel.
3708 <dt>win_size<dd>Size of the averaging window used for grouping pixels.
3709 <dt>velx<dd>Horizontal component of the optical flow of the same size as input images,
3710             32-bit floating-point, single-channel.
3711 <dt>vely<dd>Vertical component of the optical flow of the same size as input images,
3712             32-bit floating-point, single-channel.
3713 </dl></p><p>
3714 The function <code>cvCalcOpticalFlowLK</code> computes flow for every pixel of the first input image using
3715 Lucas & Kanade algorithm <a href="#paper_lucas81">[Lucas81]</a>.
3716 </p>
3717
3718
3719 <hr><h3><a name="decl_cvCalcOpticalFlowBM">CalcOpticalFlowBM</a></h3>
3720 <p class="Blurb">Calculates optical flow for two images by block matching method</p>
3721 <pre>
3722 void cvCalcOpticalFlowBM( const CvArr* prev, const CvArr* curr, CvSize block_size,
3723                           CvSize shift_size, CvSize max_range, int use_previous,
3724                           CvArr* velx, CvArr* vely );
3725 </pre><p><dl>
3726 <dt>prev<dd>First image, 8-bit, single-channel.
3727 <dt>curr<dd>Second image, 8-bit, single-channel.
3728 <dt>block_size<dd>Size of basic blocks that are compared.
3729 <dt>shift_size<dd>Block coordinate increments.
3730 <dt>max_range<dd>Size of the scanned neighborhood in pixels around block.
3731 <dt>use_previous<dd>Uses previous (input) velocity field.
3732 <dt>velx<dd>Horizontal component of the optical flow of<br>
3733             floor((prev->width - block_size.width)/shiftSize.width) &times; floor((prev->height - block_size.height)/shiftSize.height) size,
3734             32-bit floating-point, single-channel.
3735 <dt>vely<dd>Vertical component of the optical flow of the same size <code>velx</code>,
3736             32-bit floating-point, single-channel.
3737 </dl></p><p>
3738 The function <code>cvCalcOpticalFlowBM</code> calculates optical flow for
3739 overlapped blocks <code>block_size.width&times;block_size.height</code> pixels each,
3740 thus the velocity fields are smaller than the original images. For every block in <code>prev</code>
3741 the functions tries to find a similar block in <code>curr</code> in some neighborhood of the original
3742 block or shifted by (velx(x0,y0),vely(x0,y0)) block as has been calculated
3743 by previous function call (if <code>use_previous=1</code>)
3744 </p>
3745
3746
3747 <hr><h3><a name="decl_cvCalcOpticalFlowPyrLK">CalcOpticalFlowPyrLK</a></h3>
3748 <p class="Blurb">Calculates optical flow for a sparse feature set using iterative Lucas-Kanade method in
3749         pyramids</p>
3750 <pre>
3751 void cvCalcOpticalFlowPyrLK( const CvArr* prev, const CvArr* curr, CvArr* prev_pyr, CvArr* curr_pyr,
3752                              const CvPoint2D32f* prev_features, CvPoint2D32f* curr_features,
3753                              int count, CvSize win_size, int level, char* status,
3754                              float* track_error, CvTermCriteria criteria, int flags );
3755 </pre><p><dl>
3756 <dt>prev<dd>First frame, at time <code>t</code>.
3757 <dt>curr<dd>Second frame, at time <code>t + dt</code> .
3758 <dt>prev_pyr<dd>Buffer for the pyramid for the first frame. If the pointer is not <code>NULL</code> ,
3759 the buffer must have a sufficient size to store the pyramid from level <code>1</code> to
3760 level #<code>level</code> ; the total size of <code>(image_width+8)*image_height/3</code> bytes
3761 is sufficient.
3762 <dt>curr_pyr<dd>Similar to <code>prev_pyr</code>, used for the second frame.
3763 <dt>prev_features<dd>Array of points for which the flow needs to be found.
3764 <dt>curr_features<dd>Array of 2D points containing calculated new positions of input features in the second image.
3765 <dt>count<dd>Number of feature points.
3766 <dt>win_size<dd>Size of the search window of each pyramid level.
3767 <dt>level<dd>Maximal pyramid level number. If <code>0</code> , pyramids are not used (single level),
3768 if <code>1</code> , two levels are used, etc.
3769 <dt>status<dd>Array. Every element of the array is set to <code>1</code> if the flow for the
3770 corresponding feature has been found, <code>0</code> otherwise.
3771 <dt>track_error<dd>Array of double numbers containing difference between patches around the
3772 original and moved points. Optional parameter; can be <code>NULL </code>.
3773 <dt>criteria<dd>Specifies when the iteration process of finding the flow for each point
3774 on each pyramid level should be stopped.
3775 <dt>flags<dd>Miscellaneous flags:
3776 <ul>
3777 <li>  <code>CV_LKFLOW_PYR_A_READY </code>, pyramid for the first frame is pre-calculated before
3778   the call;
3779 <li>  <code>CV_LKFLOW_PYR_B_READY</code> , pyramid for the second frame is pre-calculated before
3780   the call;
3781 <li>  <code>CV_LKFLOW_INITIAL_GUESSES</code> , array B contains initial coordinates of features
3782   before the function call.
3783 </ul>
3784 </dl></p><p>
3785 The function <code>cvCalcOpticalFlowPyrLK</code> implements
3786 sparse iterative version of Lucas-Kanade optical flow in pyramids (<a href="#paper_bouguet00">[Bouguet00]</a>).
3787 It calculates coordinates of the feature points on the current video frame given
3788 their coordinates on the previous frame. The function finds the coordinates with sub-pixel accuracy.
3789 <p>
3790 Both parameters <code>prev_pyr</code> and <code>curr_pyr</code> comply with the following rules: if the image
3791 pointer is 0, the function allocates the buffer internally, calculates the
3792 pyramid, and releases the buffer after processing. Otherwise, the function
3793 calculates the pyramid and stores it in the buffer unless the flag
3794 <code>CV_LKFLOW_PYR_A[B]_READY</code> is set. The image should be large enough to fit the
3795 Gaussian pyramid data. After the function call both pyramids are calculated and
3796 the readiness flag for the corresponding image can be set in the next call (i.e., typically,
3797 for all the image pairs except the very first one <code>CV_LKFLOW_PYR_A_READY</code> is set).
3798 </p>
3799
3800 <hr><h2><a name="cv_motion_feature">Feature Matching</a></h2>
3801
3802 <hr><h3><a name="decl_cvCreateFeatureTree">CreateFeatureTree</a></h3>
3803 <p class="Blurb">Constructs a tree of feature vectors</p>
3804 <pre>
3805 CvFeatureTree* cvCreateFeatureTree(CvMat* desc);
3806 </pre><p><dl>
3807 <dt>desc<dd>n x d matrix of n d-dimensional feature vectors (CV_32FC1 or CV_64FC1).
3808 </dl></p><p>
3809 The function <code>cvCreateFeatureTree</code> constructs a balanced kd-tree index of
3810 the given feature vectors. The lifetime of the desc matrix must exceed that
3811 of the returned tree. I.e., no copy is made of the vectors.
3812 </p>
3813
3814 <hr><h3><a name="decl_cvReleaseFeatureTree">ReleaseFeatureTree</a></h3>
3815 <p class="Blurb">Destroys a tree of feature vectors</p>
3816 <pre>
3817 void cvReleaseFeatureTree(CvFeatureTree* tr);
3818 </pre><p><dl>
3819 <dt>tr<dd>pointer to tree being destroyed.
3820 </dl></p><p>
3821 The function <code>cvReleaseFeatureTree</code> deallocates the given kd-tree.
3822 </p>
3823
3824 <hr><h3><a name="decl_cvFindFeatures">FindFeatures</a></h3>
3825 <p class="Blurb">Finds approximate k nearest neighbors of given vectors using best-bin-first search</p>
3826 <pre>
3827 void cvFindFeatures(CvFeatureTree* tr, CvMat* desc,
3828                     CvMat* results, CvMat* dist, int k=2, int emax=20);
3829 </pre><p><dl>
3830 <dt>tr<dd>pointer to kd-tree index of reference vectors.
3831 <dt>desc<dd>m x d matrix of (row-)vectors to find the nearest neighbors of.
3832 <dt>results<dd>m x k set of row indices of matching vectors (referring to matrix passed to cvCreateFeatureTree). Contains -1 in some columns if fewer than k neighbors found.
3833 <dt>dist<dd>m x k matrix of distances to k nearest neighbors.
3834 <dt>k<dd>The number of neighbors to find.
3835 <dt>emax<dd>The maximum number of leaves to visit.
3836 </dl></p><p>
3837 The function <code>cvFindFeatures</code> finds (with high probability) the <code>k</code> nearest
3838 neighbors in <code>tr</code> for each of the given (row-)vectors in <code>desc</code>, using
3839 best-bin-first searching (<a href="#paper_beis97">[Beis97]</a>).
3840 The complexity of the entire operation is at most <code>O(m*emax*log2(n))</code>,
3841 where <code>n</code> is the number of vectors in the tree.
3842 </p>
3843
3844 <hr><h3><a name="decl_cvFindFeaturesBoxed">FindFeaturesBoxed</a></h3>
3845 <p class="Blurb">Orthogonal range search</p>
3846 <pre>
3847 int cvFindFeaturesBoxed(CvFeatureTree* tr,
3848                         CvMat* bounds_min, CvMat* bounds_max,
3849                         CvMat* results);
3850 </pre><p><dl>
3851 <dt>tr<dd>pointer to kd-tree index of reference vectors.
3852 <dt>bounds_min<dd>1 x d or d x 1 vector (CV_32FC1 or CV_64FC1) giving minimum value for each dimension.
3853 <dt>bounds_max<dd>1 x d or d x 1 vector (CV_32FC1 or CV_64FC1) giving maximum value for each dimension.
3854 <dt>results<dd>1 x m or m x 1 vector (CV_32SC1) to contain output row indices (referring to matrix passed to cvCreateFeatureTree).
3855 </dl></p><p>
3856 The function <code>cvFindFeaturesBoxed</code> performs orthogonal range seaching on the
3857 given kd-tree. That is, it returns the set of vectors <code>v</code> in <code>tr</code> that satisfy
3858 <code>bounds_min[i] <= v[i] <= bounds_max[i], 0 <= i < d</code>, where <code>d</code> is the dimension
3859 of vectors in the tree.
3860 The function returns the number of such vectors found.
3861 </p>
3862
3863 <hr><h2><a name="cv_motion_estimators">Estimators</a></h2>
3864
3865 <hr><h3><a name="decl_CvKalman">CvKalman</a></h3>
3866 <p class="Blurb">Kalman filter state</p>
3867 <pre>
3868 typedef struct CvKalman
3869 {
3870     int MP;                     /* number of measurement vector dimensions */
3871     int DP;                     /* number of state vector dimensions */
3872     int CP;                     /* number of control vector dimensions */
3873
3874     /* backward compatibility fields */
3875 #if 1
3876     float* PosterState;         /* =state_pre->data.fl */
3877     float* PriorState;          /* =state_post->data.fl */
3878     float* DynamMatr;           /* =transition_matrix->data.fl */
3879     float* MeasurementMatr;     /* =measurement_matrix->data.fl */
3880     float* MNCovariance;        /* =measurement_noise_cov->data.fl */
3881     float* PNCovariance;        /* =process_noise_cov->data.fl */
3882     float* KalmGainMatr;        /* =gain->data.fl */
3883     float* PriorErrorCovariance;/* =error_cov_pre->data.fl */
3884     float* PosterErrorCovariance;/* =error_cov_post->data.fl */
3885     float* Temp1;               /* temp1->data.fl */
3886     float* Temp2;               /* temp2->data.fl */
3887 #endif
3888
3889     CvMat* state_pre;           /* predicted state (x'(k)):
3890                                     x(k)=A*x(k-1)+B*u(k) */
3891     CvMat* state_post;          /* corrected state (x(k)):
3892                                     x(k)=x'(k)+K(k)*(z(k)-H*x'(k)) */
3893     CvMat* transition_matrix;   /* state transition matrix (A) */
3894     CvMat* control_matrix;      /* control matrix (B)
3895                                    (it is not used if there is no control)*/
3896     CvMat* measurement_matrix;  /* measurement matrix (H) */
3897     CvMat* process_noise_cov;   /* process noise covariance matrix (Q) */
3898     CvMat* measurement_noise_cov; /* measurement noise covariance matrix (R) */
3899     CvMat* error_cov_pre;       /* priori error estimate covariance matrix (P'(k)):
3900                                     P'(k)=A*P(k-1)*At + Q)*/
3901     CvMat* gain;                /* Kalman gain matrix (K(k)):
3902                                     K(k)=P'(k)*Ht*inv(H*P'(k)*Ht+R)*/
3903     CvMat* error_cov_post;      /* posteriori error estimate covariance matrix (P(k)):
3904                                     P(k)=(I-K(k)*H)*P'(k) */
3905     CvMat* temp1;               /* temporary matrices */
3906     CvMat* temp2;
3907     CvMat* temp3;
3908     CvMat* temp4;
3909     CvMat* temp5;
3910 }
3911 CvKalman;
3912 </pre>
3913 <p>
3914 The structure <a href="#decl_CvKalman">CvKalman</a> is used to keep Kalman filter state. It is created
3915 by <a href="#decl_cvCreateKalman">cvCreateKalman</a> function, updated by <a href="#decl_cvKalmanPredict">cvKalmanPredict</a> and
3916 <a href="#decl_cvKalmanCorrect">cvKalmanCorrect</a> functions and released by <a href="#decl_cvReleaseKalman">cvReleaseKalman</a> functions.
3917 Normally, the structure is used for standard Kalman filter (notation and the formulae below are borrowed
3918 from the excellent Kalman tutorial <a href="#paper_welch95">[Welch95]</a>):</p>
3919 <pre>
3920 x<sub>k</sub>=A&bull;x<sub>k-1</sub>+B&bull;u<sub>k</sub>+w<sub>k</sub>
3921 z<sub>k</sub>=H&bull;x<sub>k</sub>+v<sub>k</sub>,
3922 </pre>
3923 <p>where:</p>
3924 <pre>
3925 x<sub>k</sub> (x<sub>k-1</sub>) - state of the system at the moment k (k-1)
3926 z<sub>k</sub> - measurement of the system state at the moment k
3927 u<sub>k</sub> - external control applied at the moment k
3928
3929 w<sub>k</sub> and v<sub>k</sub> are normally-distributed process and measurement noise, respectively:
3930 p(w) ~ N(0,Q)
3931 p(v) ~ N(0,R),
3932
3933 that is,
3934 Q - process noise covariance matrix, constant or variable,
3935 R - measurement noise covariance matrix, constant or variable
3936 </pre><p>
3937 In case of standard Kalman filter, all the matrices: A, B, H, Q and R are initialized once after
3938 <a href="#decl_CvKalman">CvKalman</a> structure is allocated via <a href="#decl_cvCreateKalman">cvCreateKalman</a>.
3939 However, the same structure and the same functions may be used to simulate extended Kalman filter by
3940 linearizing extended Kalman filter equation in the current system state neighborhood,
3941 in this case A, B, H (and, probably, Q and R) should be updated on every step.
3942 </p>
3943
3944
3945 <hr><h3><a name="decl_cvCreateKalman">CreateKalman</a></h3>
3946 <p class="Blurb">Allocates Kalman filter structure</p>
3947 <pre>
3948 CvKalman* cvCreateKalman( int dynam_params, int measure_params, int control_params=0 );
3949 </pre><p><dl>
3950 <dt>dynam_params<dd>dimensionality of the state vector
3951 <dt>measure_params<dd>dimensionality of the measurement vector
3952 <dt>control_params<dd>dimensionality of the control vector
3953 </dl></p><p>
3954 The function <code>cvCreateKalman</code> allocates <a href="#decl_CvKalman">CvKalman</a> and all its matrices
3955 and initializes them somehow.
3956 </p>
3957
3958
3959 <hr><h3><a name="decl_cvReleaseKalman">ReleaseKalman</a></h3>
3960 <p class="Blurb">Deallocates Kalman filter structure</p>
3961 <pre>
3962 void cvReleaseKalman( CvKalman** kalman );
3963 </pre><p><dl>
3964 <dt>kalman<dd>double pointer to the Kalman filter structure.
3965 </dl></p><p>
3966 The function <code>cvReleaseKalman</code> releases the structure <a href="#decl_CvKalman">CvKalman</a>
3967 and all underlying matrices.
3968 </p>
3969
3970
3971 <hr><h3><a name="decl_cvKalmanPredict">KalmanPredict</a></h3>
3972 <p class="Blurb">Estimates subsequent model state</p>
3973 <pre>
3974 const CvMat* cvKalmanPredict( CvKalman* kalman, const CvMat* control=NULL );
3975 #define cvKalmanUpdateByTime cvKalmanPredict
3976 </pre><p><dl>
3977 <dt>kalman<dd>Kalman filter state.
3978 <dt>control<dd>Control vector (u<sub>k</sub>),
3979                should be NULL iff there is no external control (<code>control_params</code>=0).
3980 </dl></p><p>
3981 The function <code>cvKalmanPredict</code> estimates the subsequent stochastic model state
3982 by its current state and stores it at <code>kalman->state_pre</code>:</p>
3983 <pre>
3984     x'<sub>k</sub>=A&bull;x<sub>k</sub>+B&bull;u<sub>k</sub>
3985     P'<sub>k</sub>=A&bull;P<sub>k-1</sub>*A<sup>T</sup> + Q,
3986 where
3987 x'<sub>k</sub> is predicted state (kalman->state_pre),
3988 x<sub>k-1</sub> is corrected state on the previous step (kalman->state_post)
3989                 (should be initialized somehow in the beginning, zero vector by default),
3990 u<sub>k</sub> is external control (<code>control</code> parameter),
3991 P'<sub>k</sub> is priori error covariance matrix (kalman->error_cov_pre)
3992 P<sub>k-1</sub> is posteriori error covariance matrix on the previous step (kalman->error_cov_post)
3993                 (should be initialized somehow in the beginning, identity matrix by default),
3994 </pre>
3995 The function returns the estimated state.
3996 </p>
3997
3998
3999 <hr><h3><a name="decl_cvKalmanCorrect">KalmanCorrect</a></h3>
4000 <p class="Blurb">Adjusts model state</p>
4001 <pre>
4002 const CvMat* cvKalmanCorrect( CvKalman* kalman, const CvMat* measurement );
4003 #define cvKalmanUpdateByMeasurement cvKalmanCorrect
4004 </pre><p><dl>
4005 <dt>kalman<dd>Pointer to the structure to be updated.
4006 <dt>measurement<dd>Pointer to the structure CvMat containing the measurement vector.
4007 </dl></p><p>
4008 The function <code>cvKalmanCorrect</code> adjusts stochastic model state on the
4009 basis of the given measurement of the model state:</p>
4010 <pre>
4011 K<sub>k</sub>=P'<sub>k</sub>&bull;H<sup>T</sup>&bull;(H&bull;P'<sub>k</sub>&bull;H<sup>T</sup>+R)<sup>-1</sup>
4012 x<sub>k</sub>=x'<sub>k</sub>+K<sub>k</sub>&bull;(z<sub>k</sub>-H&bull;x'<sub>k</sub>)
4013 P<sub>k</sub>=(I-K<sub>k</sub>&bull;H)&bull;P'<sub>k</sub>
4014 where
4015 z<sub>k</sub> - given measurement (<code>mesurement</code> parameter)
4016 K<sub>k</sub> - Kalman "gain" matrix.
4017 </pre>
4018 <p>
4019 The function stores adjusted state at <code>kalman->state_post</code> and returns it on output.
4020 </p>
4021
4022 <h4>Example. Using Kalman filter to track a rotating point</h4>
4023 <pre>
4024 #include "cv.h"
4025 #include "highgui.h"
4026 #include &lt;math.h&gt;
4027
4028 int main(int argc, char** argv)
4029 {
4030     /* A matrix data */
4031     const float A[] = { 1, 1, 0, 1 };
4032
4033     IplImage* img = cvCreateImage( cvSize(500,500), 8, 3 );
4034     CvKalman* kalman = cvCreateKalman( 2, 1, 0 );
4035     /* state is (phi, delta_phi) - angle and angle increment */
4036     CvMat* state = cvCreateMat( 2, 1, CV_32FC1 );
4037     CvMat* process_noise = cvCreateMat( 2, 1, CV_32FC1 );
4038     /* only phi (angle) is measured */
4039     CvMat* measurement = cvCreateMat( 1, 1, CV_32FC1 );
4040     CvRandState rng;
4041     int code = -1;
4042
4043     cvRandInit( &rng, 0, 1, -1, CV_RAND_UNI );
4044
4045     cvZero( measurement );
4046     cvNamedWindow( "Kalman", 1 );
4047
4048     for(;;)
4049     {
4050         cvRandSetRange( &rng, 0, 0.1, 0 );
4051         rng.disttype = CV_RAND_NORMAL;
4052
4053         cvRand( &rng, state );
4054
4055         memcpy( kalman->transition_matrix->data.fl, A, sizeof(A));
4056         cvSetIdentity( kalman->measurement_matrix, cvRealScalar(1) );
4057         cvSetIdentity( kalman->process_noise_cov, cvRealScalar(1e-5) );
4058         cvSetIdentity( kalman->measurement_noise_cov, cvRealScalar(1e-1) );
4059         cvSetIdentity( kalman->error_cov_post, cvRealScalar(1));
4060         /* choose random initial state */
4061         cvRand( &rng, kalman->state_post );
4062
4063         rng.disttype = CV_RAND_NORMAL;
4064
4065         for(;;)
4066         {
4067             #define calc_point(angle)                                      \
4068                 cvPoint( cvRound(img->width/2 + img->width/3*cos(angle)),  \
4069                          cvRound(img->height/2 - img->width/3*sin(angle)))
4070
4071             float state_angle = state->data.fl[0];
4072             CvPoint state_pt = calc_point(state_angle);
4073
4074             /* predict point position */
4075             const CvMat* prediction = cvKalmanPredict( kalman, 0 );
4076             float predict_angle = prediction->data.fl[0];
4077             CvPoint predict_pt = calc_point(predict_angle);
4078             float measurement_angle;
4079             CvPoint measurement_pt;
4080
4081             cvRandSetRange( &rng, 0, sqrt(kalman->measurement_noise_cov->data.fl[0]), 0 );
4082             cvRand( &rng, measurement );
4083
4084             /* generate measurement */
4085             cvMatMulAdd( kalman->measurement_matrix, state, measurement, measurement );
4086
4087             measurement_angle = measurement->data.fl[0];
4088             measurement_pt = calc_point(measurement_angle);
4089
4090             /* plot points */
4091             #define draw_cross( center, color, d )                                 \
4092                 cvLine( img, cvPoint( center.x - d, center.y - d ),                \
4093                              cvPoint( center.x + d, center.y + d ), color, 1, 0 ); \
4094                 cvLine( img, cvPoint( center.x + d, center.y - d ),                \
4095                              cvPoint( center.x - d, center.y + d ), color, 1, 0 )
4096
4097             cvZero( img );
4098             draw_cross( state_pt, CV_RGB(255,255,255), 3 );
4099             draw_cross( measurement_pt, CV_RGB(255,0,0), 3 );
4100             draw_cross( predict_pt, CV_RGB(0,255,0), 3 );
4101             cvLine( img, state_pt, predict_pt, CV_RGB(255,255,0), 3, 0 );
4102
4103             /* adjust Kalman filter state */
4104             cvKalmanCorrect( kalman, measurement );
4105
4106             cvRandSetRange( &rng, 0, sqrt(kalman->process_noise_cov->data.fl[0]), 0 );
4107             cvRand( &rng, process_noise );
4108             cvMatMulAdd( kalman->transition_matrix, state, process_noise, state );
4109
4110             cvShowImage( "Kalman", img );
4111             code = cvWaitKey( 100 );
4112
4113             if( code > 0 ) /* break current simulation by pressing a key */
4114                 break;
4115         }
4116         if( code == 27 ) /* exit by ESCAPE */
4117             break;
4118     }
4119
4120     return 0;
4121 }
4122 </pre>
4123
4124 <hr><h3><a name="data_CvConDensation">CvConDensation</a></h3>
4125 <p class="Blurb">ConDenstation state</p>
4126 <pre>
4127     typedef struct CvConDensation
4128     {
4129         int MP;     //Dimension of measurement vector
4130         int DP;     // Dimension of state vector
4131         float* DynamMatr;       // Matrix of the linear Dynamics system
4132         float* State;           // Vector of State
4133         int SamplesNum;         // Number of the Samples
4134         float** flSamples;      // array of the Sample Vectors
4135         float** flNewSamples;   // temporary array of the Sample Vectors
4136         float* flConfidence;    // Confidence for each Sample
4137         float* flCumulative;    // Cumulative confidence
4138         float* Temp;            // Temporary vector
4139         float* RandomSample;    // RandomVector to update sample set
4140         CvRandState* RandS;     // Array of structures to generate random vectors
4141     } CvConDensation;
4142 </pre>
4143 <p>
4144 The structure <a href="#decl_CvConDensation">CvConDensation</a> stores CONditional DENSity propagATION tracker state.
4145 The information about the algorithm can be found at
4146 <a href="http://www.dai.ed.ac.uk/CVonline/LOCAL_COPIES/ISARD1/condensation.html">
4147 http://www.dai.ed.ac.uk/CVonline/LOCAL_COPIES/ISARD1/condensation.html</a>
4148 </p>
4149
4150
4151 <hr><h3><a name="decl_cvCreateConDensation">CreateConDensation</a></h3>
4152 <p class="Blurb">Allocates ConDensation filter structure</p>
4153 <pre>
4154 CvConDensation* cvCreateConDensation( int dynam_params, int measure_params, int sample_count );
4155 </pre><p><dl>
4156 <dt>dynam_params<dd>Dimension of the state vector.
4157 <dt>measure_params<dd>Dimension of the measurement vector.
4158 <dt>sample_count<dd>Number of samples.
4159 </dl></p><p>
4160 The function <code>cvCreateConDensation</code> creates <a href="#decl_CvConDensation">CvConDensation</a>
4161 structure and returns pointer to the structure.
4162 </p>
4163
4164
4165 <hr><h3><a name="decl_cvReleaseConDensation">ReleaseConDensation</a></h3>
4166 <p class="Blurb">Deallocates ConDensation filter structure</p>
4167 <pre>
4168 void cvReleaseConDensation( CvConDensation** condens );
4169 </pre><p><dl>
4170 <dt>condens<dd>Pointer to the pointer to the structure to be released.
4171 </dl></p><p>
4172 The function <code>cvReleaseConDensation</code> releases the structure <a href="#decl_CvConDensation">CvConDensation</a> (see
4173 <a href="#decl_CvConDensation">cvConDensation</a>) and frees all memory previously allocated for the structure.
4174 </p>
4175
4176
4177 <hr><h3><a name="decl_cvConDensInitSampleSet">ConDensInitSampleSet</a></h3>
4178 <p class="Blurb">Initializes sample set for ConDensation algorithm</p>
4179 <pre>
4180 void cvConDensInitSampleSet( CvConDensation* condens, CvMat* lower_bound, CvMat* upper_bound );
4181 </pre><p><dl>
4182 <dt>condens<dd>Pointer to a structure to be initialized.
4183 <dt>lower_bound<dd>Vector of the lower boundary for each dimension.
4184 <dt>upper_bound<dd>Vector of the upper boundary for each dimension.
4185 </dl></p><p>
4186 The function <code>cvConDensInitSampleSet</code> fills the samples arrays in the structure
4187 <a href="#decl_CvConDensation">CvConDensation</a> with values within specified ranges.
4188 </p>
4189
4190
4191 <hr><h3><a name="decl_cvConDensUpdateByTime">ConDensUpdateByTime</a></h3>
4192 <p class="Blurb">Estimates subsequent model state</p>
4193 <pre>
4194 void cvConDensUpdateByTime( CvConDensation* condens );
4195 </pre><p><dl>
4196 <dt>condens<dd>Pointer to the structure to be updated.
4197 </dl></p><p>
4198 The function <code>cvConDensUpdateByTime</code>
4199 estimates the subsequent stochastic model state from its current state.
4200 </p>
4201
4202
4203 <hr><h1><a name="cv_pattern">Pattern Recognition</a></h1>
4204
4205 <hr><h2><a name="cv_pattern_objdetection">Object Detection</a></h2>
4206
4207 <p>
4208 The object detector described below has been initially proposed by Paul Viola
4209 <a href="#paper_viola01">[Viola01]</a> and improved by Rainer Lienhart
4210 <a href="#paper_lienhart02">[Lienhart02]</a>.
4211 First, a classifier (namely a <code>cascade of boosted classifiers working
4212 with haar-like features</code>) is trained with a few hundreds of sample
4213 views of a particular object (i.e., a face or a car), called positive
4214 examples, that are scaled to the same size (say, 20x20), and negative examples
4215 - arbitrary images of the same size.
4216 </p><p>
4217 After a classifier is trained, it can be applied to a region of interest (of
4218 the same size as used during the training) in an input image. The
4219 classifier outputs a "1" if the region is likely to show the object
4220 (i.e., face/car), and "0" otherwise. To search for the object in the
4221 whole image one can move the search window across the image and check
4222 every location using the classifier. The classifier is designed so that it can
4223 be easily "resized" in order to be able to find the objects of interest
4224 at different sizes, which is more efficient than resizing the image itself. So,
4225 to find an object of an unknown size in the image the scan procedure should be
4226 done several times at different scales.
4227 </p>
4228 <p>
4229 The word "cascade" in the classifier name means that the resultant classifier
4230 consists of several simpler classifiers (<code>stages</code>) that are applied
4231 subsequently to a region of interest until at some stage the candidate
4232 is rejected or all the stages are passed. The word
4233 "boosted" means that the classifiers at every stage of the cascade are complex
4234 themselves and they are built out of basic classifiers using one of four
4235 different <code>boosting</code> techniques (weighted voting). Currently
4236 Discrete Adaboost, Real Adaboost, Gentle Adaboost and Logitboost are supported.
4237 The basic classifiers are decision-tree classifiers with at least
4238 2 leaves. Haar-like features are the input to the basic classifiers, and
4239 are calculated as described below. The current algorithm uses the following
4240 Haar-like features:</p>
4241 <p>
4242 <img src="pics/haarfeatures.png">
4243 </p>
4244 <p>
4245 The feature used in a particular classifier is specified by its shape (1a,
4246 2b etc.), position within the region of interest and the scale (this scale is
4247 not the same as the scale used at the detection stage, though these two scales
4248 are multiplied). For example, in case of the third line feature (2c) the
4249 response is calculated as the difference between the sum of image pixels
4250 under the rectangle covering the whole feature (including the two white
4251 stripes and the black stripe in the middle) and the sum of the image
4252 pixels under the black stripe multiplied by 3 in order to compensate for
4253 the differences in the size of areas. The sums of pixel values over a
4254 rectangular regions are calculated rapidly using integral images
4255 (see below and <a href="#decl_cvIntegral">
4256 cvIntegral</a> description).
4257 </p><p>
4258 To see the object detector at work, have a look at HaarFaceDetect demo.
4259 </p><p>
4260 The following reference is for the detection part only. There is a
4261 separate application called <code>haartraining</code> that can train a
4262 cascade of boosted classifiers from a set of samples.
4263 See <code>opencv/apps/haartraining</code> for details.
4264 </p>
4265
4266
4267 <hr><h3><a name="decl_CvHaar*">CvHaarFeature, CvHaarClassifier, CvHaarStageClassifier, CvHaarClassifierCascade</a></h3>
4268 <p class="Blurb">Boosted Haar classifier structures</p>
4269 <pre>
4270 #define CV_HAAR_FEATURE_MAX  3
4271
4272 /* a haar feature consists of 2-3 rectangles with appropriate weights */
4273 typedef struct CvHaarFeature
4274 {
4275     int  tilted;  /* 0 means up-right feature, 1 means 45--rotated feature */
4276
4277     /* 2-3 rectangles with weights of opposite signs and
4278        with absolute values inversely proportional to the areas of the rectangles.
4279        if rect[2].weight !=0, then
4280        the feature consists of 3 rectangles, otherwise it consists of 2 */
4281     struct
4282     {
4283         CvRect r;
4284         float weight;
4285     } rect[CV_HAAR_FEATURE_MAX];
4286 }
4287 CvHaarFeature;
4288
4289 /* a single tree classifier (stump in the simplest case) that returns the response for the feature
4290    at the particular image location (i.e. pixel sum over sub-rectangles of the window) and gives out
4291    a value depending on the response */
4292 typedef struct CvHaarClassifier
4293 {
4294     int count;  /* number of nodes in the decision tree */
4295
4296     /* these are "parallel" arrays. Every index <code>i</code>
4297        corresponds to a node of the decision tree (root has 0-th index).
4298
4299        left[i] - index of the left child (or negated index if the left child is a leaf)
4300        right[i] - index of the right child (or negated index if the right child is a leaf)
4301        threshold[i] - branch threshold. if feature response is &lt;= threshold, left branch
4302                       is chosen, otherwise right branch is chosen.
4303        alpha[i] - output value corresponding to the leaf. */
4304     CvHaarFeature* haar_feature;
4305     float* threshold;
4306     int* left;
4307     int* right;
4308     float* alpha;
4309 }
4310 CvHaarClassifier;
4311
4312 /* a boosted battery of classifiers(=stage classifier):
4313    the stage classifier returns 1
4314    if the sum of the classifiers' responses
4315    is greater than <code>threshold</code> and 0 otherwise */
4316 typedef struct CvHaarStageClassifier
4317 {
4318     int  count;  /* number of classifiers in the battery */
4319     float threshold; /* threshold for the boosted classifier */
4320     CvHaarClassifier* classifier; /* array of classifiers */
4321
4322     /* these fields are used for organizing trees of stage classifiers,
4323        rather than just straight cascades */
4324     int next;
4325     int child;
4326     int parent;
4327 }
4328 CvHaarStageClassifier;
4329
4330 typedef struct CvHidHaarClassifierCascade CvHidHaarClassifierCascade;
4331
4332 /* cascade or tree of stage classifiers */
4333 typedef struct CvHaarClassifierCascade
4334 {
4335     int  flags; /* signature */
4336     int  count; /* number of stages */
4337     CvSize orig_window_size; /* original object size (the cascade is trained for) */
4338
4339     /* these two parameters are set by cvSetImagesForHaarClassifierCascade */
4340     CvSize real_window_size; /* current object size */
4341     double scale; /* current scale */
4342     CvHaarStageClassifier* stage_classifier; /* array of stage classifiers */
4343     CvHidHaarClassifierCascade* hid_cascade; /* hidden optimized representation of the cascade,
4344                                                 created by cvSetImagesForHaarClassifierCascade */
4345 }
4346 CvHaarClassifierCascade;
4347
4348 </pre>
4349 <p>
4350 All the structures are used for representing a cascaded of boosted Haar
4351 classifiers. The cascade has the following hierarchical structure:</p>
4352 <pre>
4353     Cascade:
4354         Stage<sub>1</sub>:
4355             Classifier<sub>11</sub>:
4356                 Feature<sub>11</sub>
4357             Classifier<sub>12</sub>:
4358                 Feature<sub>12</sub>
4359             ...
4360         Stage<sub>2</sub>:
4361             Classifier<sub>21</sub>:
4362                 Feature<sub>21</sub>
4363             ...
4364         ...
4365 </pre><p>
4366 The whole hierarchy can be constructed manually or loaded from a file
4367 using functions <a href="#decl_cvLoadHaarClassifierCascade">cvLoadHaarClassifierCascade</a>
4368 or <a href="opencvref_cv.htm#decl_cvLoad">cvLoad</a>.
4369 </p>
4370
4371
4372 <hr><h3><a name="decl_cvLoadHaarClassifierCascade">cvLoadHaarClassifierCascade</a></h3>
4373 <p class="Blurb">Loads a trained cascade classifier from file
4374                  or the classifier database embedded in OpenCV</p>
4375 <pre>
4376 CvHaarClassifierCascade* cvLoadHaarClassifierCascade(
4377                          const char* directory,
4378                          CvSize orig_window_size );
4379 </pre><p><dl>
4380 <dt>directory<dd>Name of directory containing the description of a trained cascade
4381                  classifier.
4382 <dt>orig_window_size<dd>Original size of objects the cascade has been
4383                    trained on. Note that it is not stored in the cascade and therefore must
4384                    be specified separately.
4385 </dl><p>
4386 The function <code>cvLoadHaarClassifierCascade</code>
4387 loads a trained cascade of haar classifiers from a file or the classifier
4388 database embedded in OpenCV. The base can be trained using <code>haartraining</code>
4389 application (see opencv/apps/haartraining for details).</p>
4390 <p>
4391 <em>The function is obsolete</em>. Nowadays object detection classifiers are stored in
4392 XML or YAML files, rather than in directories. To load cascade from a
4393 file, use <a href="opencvref_cxcore.htm#decl_cvLoad">cvLoad</a> function.
4394 </p>
4395
4396
4397 <hr><h3><a name="decl_cvReleaseHaarClassifierCascade">cvReleaseHaarClassifierCascade</a></h3>
4398 <p class="Blurb">Releases haar classifier cascade</p>
4399 <pre>
4400 void cvReleaseHaarClassifierCascade( CvHaarClassifierCascade** cascade );
4401 </pre>
4402 <p><dl>
4403 <dt>cascade<dd>Double pointer to the released cascade.
4404                The pointer is cleared by the function.
4405 </dl>
4406 <p>
4407 The function <code>cvReleaseHaarClassifierCascade</code>
4408 deallocates the cascade that has been created manually or loaded using
4409 <a href="#decl_cvLoadHaarClassifierCascade">cvLoadHaarClassifierCascade</a> or
4410 <a href="opencvref_cxcore.htm#decl_cvLoad">cvLoad</a>.
4411 </p>
4412
4413
4414 <hr><h3><a name="decl_cvHaarDetectObjects">cvHaarDetectObjects</a></h3>
4415 <p class="Blurb">Detects objects in the image</p>
4416 <pre>
4417 typedef struct CvAvgComp
4418 {
4419     CvRect rect; /* bounding rectangle for the object (average rectangle of a group) */
4420     int neighbors; /* number of neighbor rectangles in the group */
4421 }
4422 CvAvgComp;
4423
4424 CvSeq* cvHaarDetectObjects( const CvArr* image, CvHaarClassifierCascade* cascade,
4425                             CvMemStorage* storage, double scale_factor=1.1,
4426                             int min_neighbors=3, int flags=0,
4427                             CvSize min_size=cvSize(0,0) );
4428 </pre>
4429 <p><dl>
4430 <dt>image<dd>Image to detect objects in.
4431 <dt>cascade<dd>Haar classifier cascade in internal representation.
4432 <dt>storage<dd>Memory storage to store the resultant sequence of the
4433                object candidate rectangles.
4434 <dt>scale_factor<dd>The factor by which the search window is scaled between the subsequent scans,
4435                     for example, 1.1 means increasing window by 10%.
4436 <dt>min_neighbors<dd>Minimum number (minus 1) of neighbor rectangles
4437                      that makes up an object. All the groups of a smaller number of rectangles
4438                      than <code>min_neighbors</code>-1 are rejected.
4439                      If <code>min_neighbors</code> is 0, the function does not any
4440                      grouping at all and returns all the detected candidate rectangles,
4441                      which may be useful if the user wants to apply a customized grouping procedure.
4442 <dt>flags<dd>Mode of operation. It can be a combination of zero or more of the following values:<br>
4443              <code>CV_HAAR_SCALE_IMAGE</code> - for each scale factor used the function will
4444              downscale the image rather than "zoom" the feature coordinates in the classifier cascade.
4445              Currently, the option can only be used alone, i.e. the flag can not be set together with the others.<br>
4446              <code>CV_HAAR_DO_CANNY_PRUNING</code> - If it is set, the function uses Canny
4447              edge detector to reject some image regions that contain too few or too much edges
4448              and thus can not contain the searched object. The particular threshold values
4449              are tuned for face detection and in this case the pruning speeds up the processing.<br>
4450              <code>CV_HAAR_FIND_BIGGEST_OBJECT</code> - If it is set, the function finds
4451              the largest object (if any) in the image. That is, the output sequence will
4452              contain one (or zero) element(s).<br>
4453              <code>CV_HAAR_DO_ROUGH_SEARCH</code> - It should be used only when
4454              <code>CV_HAAR_FIND_BIGGEST_OBJECT</code> is set and <code>min_neighbors</code> > 0.
4455              If the flag is set, the function does not look for candidates of a smaller size
4456              as soon as it has found the object (with enough neighbor candidates) at the current
4457              scale. Typically, when <code>min_neighbors</code> is fixed, the
4458              mode yields less accurate (a bit larger) object rectangle than
4459              the regular single-object mode (<code>flags</code>=<code>CV_HAAR_FIND_BIGGEST_OBJECT</code>),
4460              but it is much faster, up to an order of magnitude. A greater value of
4461              <code>min_neighbors</code> may be specified to improve the accuracy.<p>
4462
4463              Note, that in single-object mode <code>CV_HAAR_DO_CANNY_PRUNING</code>
4464              does not improve performance much and can even slow down the processing.
4465
4466 <dt>min_size<dd>Minimum window size. By default, it is set to the size of samples the classifier
4467 has been trained on (~20&times;20 for face detection).
4468 </dl>
4469 <p>
4470 The function <code>cvHaarDetectObjects</code> finds
4471 rectangular regions in the given image that are likely to contain objects
4472 the cascade has been trained for and returns those regions as
4473 a sequence of rectangles. The function scans the image several
4474 times at different scales (see <a href="#decl_cvSetImagesForHaarClassifierCascade">
4475 cvSetImagesForHaarClassifierCascade</a>). Each time it considers
4476 overlapping regions in the image and applies the classifiers to the regions
4477 using <a href="#decl_cvRunHaarClassifierCascade">cvRunHaarClassifierCascade</a>.
4478 It may also apply some heuristics to reduce number of analyzed regions, such as
4479 Canny pruning. After it has proceeded and collected the candidate rectangles
4480 (regions that passed the classifier cascade), it groups them and returns a
4481 sequence of average rectangles for each large enough group. The default
4482 parameters (<code>scale_factor</code>=1.1, <code>min_neighbors</code>=3, <code>flags</code>=0)
4483 are tuned for accurate yet slow object detection. For a faster operation on
4484 real video images the more preferable settings are: <code>scale_factor</code>=1.2, <code>min_neighbors</code>=2,
4485 <code>flags</code>=CV_HAAR_DO_CANNY_PRUNING, <code>min_size</code>=&lt;minimum possible face size&gt;
4486 (for example, ~1/4 to 1/16 of the image area in case of video conferencing).
4487 </p>
4488 <h4>Example. Using cascade of Haar classifiers to find objects (e.g. faces).</h4>
4489 <pre>
4490 #include "cv.h"
4491 #include "highgui.h"
4492
4493 CvHaarClassifierCascade* load_object_detector( const char* cascade_path )
4494 {
4495     return (CvHaarClassifierCascade*)cvLoad( cascade_path );
4496 }
4497
4498 void detect_and_draw_objects( IplImage* image,
4499                               CvHaarClassifierCascade* cascade,
4500                               int do_pyramids )
4501 {
4502     IplImage* small_image = image;
4503     CvMemStorage* storage = cvCreateMemStorage(0);
4504     CvSeq* faces;
4505     int i, scale = 1;
4506
4507     /* if the flag is specified, down-scale the input image to get a
4508        performance boost w/o loosing quality (perhaps) */
4509     if( do_pyramids )
4510     {
4511         small_image = cvCreateImage( cvSize(image-&gt;width/2,image-&gt;height/2), IPL_DEPTH_8U, 3 );
4512         cvPyrDown( image, small_image, CV_GAUSSIAN_5x5 );
4513         scale = 2;
4514     }
4515
4516     /* use the fastest variant */
4517     faces = cvHaarDetectObjects( small_image, cascade, storage, 1.2, 2, CV_HAAR_DO_CANNY_PRUNING );
4518
4519     /* draw all the rectangles */
4520     for( i = 0; i &lt; faces-&gt;total; i++ )
4521     {
4522         /* extract the rectangles only */
4523         CvRect face_rect = *(CvRect*)cvGetSeqElem( faces, i, 0 );
4524         cvRectangle( image, cvPoint(face_rect.x*scale,face_rect.y*scale),
4525                      cvPoint((face_rect.x+face_rect.width)*scale,
4526                              (face_rect.y+face_rect.height)*scale),
4527                      CV_RGB(255,0,0), 3 );
4528     }
4529
4530     if( small_image != image )
4531         cvReleaseImage( &amp;small_image );
4532     cvReleaseMemStorage( &amp;storage );
4533 }
4534
4535 /* takes image filename and cascade path from the command line */
4536 int main( int argc, char** argv )
4537 {
4538     IplImage* image;
4539     if( argc==3 &amp;&amp; (image = cvLoadImage( argv[1], 1 )) != 0 )
4540     {
4541         CvHaarClassifierCascade* cascade = load_object_detector(argv[2]);
4542         detect_and_draw_objects( image, cascade, 1 );
4543         cvNamedWindow( "test", 0 );
4544         cvShowImage( "test", image );
4545         cvWaitKey(0);
4546         cvReleaseHaarClassifierCascade( &amp;cascade );
4547         cvReleaseImage( &amp;image );
4548     }
4549
4550     return 0;
4551 }
4552 </pre>
4553
4554
4555 <hr><h3><a name="decl_cvSetImagesForHaarClassifierCascade">cvSetImagesForHaarClassifierCascade</a></h3>
4556 <p class="Blurb">Assigns images to the hidden cascade</p>
4557 <pre>
4558 void cvSetImagesForHaarClassifierCascade( CvHaarClassifierCascade* cascade,
4559                                           const CvArr* sum, const CvArr* sqsum,
4560                                           const CvArr* tilted_sum, double scale );
4561 </pre>
4562 <p><dl>
4563 <dt>cascade<dd>Hidden Haar classifier cascade, created by <a href="#decl_cvCreateHidHaarClassifierCascade">
4564 cvCreateHidHaarClassifierCascade</a>.
4565 <dt>sum<dd>Integral (sum) single-channel image of 32-bit integer format. This image as well as the
4566                 two subsequent images are used for fast feature evaluation and
4567                 brightness/contrast normalization. They all can be retrieved from input 8-bit
4568                 or floating point single-channel image using The function <code>cvIntegral</code>.
4569 <dt>sqsum<dd>Square sum single-channel image of 64-bit floating-point format.
4570 <dt>tilted_sum<dd>Tilted sum single-channel image of 32-bit integer format.
4571 <dt>scale<dd>Window scale for the cascade. If <code>scale</code>=1, original window size is
4572              used (objects of that size are searched) - the same size as specified in
4573              <a href="#decl_cvLoadHaarClassifierCascade">cvLoadHaarClassifierCascade</a>
4574              (24x24 in case of "&lt;default_face_cascade&gt;"), if <code>scale</code>=2,
4575              a two times larger window is used (48x48 in case of default face cascade).
4576              While this will speed-up search about four times,
4577              faces smaller than 48x48 cannot be detected.
4578 </dl>
4579 <p>
4580 The function <code>cvSetImagesForHaarClassifierCascade</code>
4581 assigns images and/or window scale to the hidden classifier cascade.
4582 If image pointers are NULL, the previously set images are used further
4583 (i.e. NULLs mean "do not change images"). Scale parameter has no such a "protection" value, but
4584 the previous value can be retrieved by <a href="#decl_cvGetHaarClassifierCascadeScale">
4585 cvGetHaarClassifierCascadeScale</a> function and reused again. The function
4586 is used to prepare cascade for detecting object of the particular size in the
4587 particular image. The function is called internally by <a href="#decl_cvHaarDetectObjects">
4588 cvHaarDetectObjects</a>, but it can be called by user if there is a need in
4589 using lower-level function <a href="#decl_cvRunHaarClassifierCascade">cvRunHaarClassifierCascade</a>.
4590 </p>
4591
4592
4593 <hr>
4594 <h3><a name="decl_cvRunHaarClassifierCascade">cvRunHaarClassifierCascade</a></h3>
4595 <p class="Blurb">Runs cascade of boosted classifier at given image location</p>
4596 <pre>
4597 int cvRunHaarClassifierCascade( CvHaarClassifierCascade* cascade,
4598                                 CvPoint pt, int start_stage=0 );
4599 </pre>
4600 <p><dl>
4601 <dt>cascade<dd>Haar classifier cascade.
4602 <dt>pt<dd>Top-left corner of the analyzed
4603           region. Size of the region is a original window size scaled by the currently set
4604           scale. The current window size may be retrieved using <a href="#decl_cvGetHaarClassifierCascadeWindowSize">
4605           cvGetHaarClassifierCascadeWindowSize</a> function.
4606 <dt>start_stage<dd>Initial zero-based index of the cascade stage to start from.
4607                   The function assumes that all the previous stages are passed.
4608                   This feature is used internally by <a href="#decl_cvHaarDetectObjects">
4609                   cvHaarDetectObjects</a> for better processor cache utilization.
4610 </dl><p>
4611 The function <code>cvRunHaarHaarClassifierCascade</code>
4612 runs Haar classifier cascade at a single image location. Before using this
4613 function the integral images and the appropriate scale (=&gt; window size)
4614 should be set using <a href="#decl_cvSetImagesForHaarClassifierCascade">cvSetImagesForHaarClassifierCascade</a>.
4615 The function returns positive value if the analyzed rectangle passed all the classifier
4616 stages (it is a candidate) and zero or negative value otherwise.
4617 </p>
4618
4619
4620 <hr><h1><a name="cv_3d">Camera Calibration and 3D Reconstruction</a></h1>
4621
4622 <hr><h2><a name="cv_3d_model">Pinhole Camera Model, Distortion</a></h2>
4623
4624 <p>
4625 The functions in this section use so-called pinhole camera model. That is,
4626 a scene view is formed by projecting 3D points into the image plane using perspective transformation.
4627 <pre>
4628
4629 s*m' = A*[R|t]*M', or
4630
4631  [u]   [fx 0 cx] [r<sub>11</sub> r<sub>12</sub> r<sub>13</sub> t<sub>1</sub>] [X]
4632 s[v] = [0 fy cy]*[r<sub>21</sub> r<sub>22</sub> r<sub>23</sub> t<sub>2</sub>]*[Y]
4633  [1]   [0  0  1] [r<sub>31</sub> r<sub>32</sub> r<sub>33</sub> t<sub>2</sub>] [Z]
4634                                  [1]
4635 </pre>
4636
4637 Where <code>(X, Y, Z)</code> are coordinates of a 3D point in the world coordinate space,
4638 <code>(u, v)</code> are coordinates of point projection in pixels.
4639 <code>A</code> is called a camera matrix, or matrix of intrinsic parameters.
4640 <code>(cx, cy)</code> is a principal point (that is usually at the image center),
4641 and <code>fx, fy</code> are focal lengths expressed in pixel-related units.
4642 Thus, if an image from camera is up-sampled/down-sampled by some factor,
4643 all these parameters (<code>fx, fy, cx</code> and <code>cy</code>) should be scaled
4644 (multiplied/divided, respectively) by the same factor.
4645 The matrix of intrinsic parameters does not depend on the scene viewed
4646 and, once estimated, can be re-used (as long as the focal length is fixed (in case of zoom lens)).
4647
4648 The joint rotation-translation matrix <code>[R|t]</code> is called a matrix of extrinsic parameters.
4649 It is used to describe the camera motion around a static scene, or vice versa,
4650 rigid motion of an object in front of still camera. That is, <code>[R|t]</code> translates coordinates
4651 of a point <code>(X, Y, Z)</code> to some coordinate system, fixed with respect to the camera.
4652
4653 The transformation above is equivalent to the following (when z&ne;0):
4654
4655 <pre>
4656 [x]     [X]
4657 [y] = R*[Y] + t
4658 [z]     [Z]
4659
4660 x' = x/z
4661 y' = y/z
4662
4663 u = fx*x' + cx
4664 v = fy*y' + cy
4665 </pre>
4666
4667 Real lens usually have some distortion, which major components are radial distortion
4668 and slight tangential distortion. So, the above model is extended as:
4669
4670 <pre>
4671 [x]     [X]
4672 [y] = R*[Y] + t
4673 [z]     [Z]
4674
4675 x' = x/z
4676 y' = y/z
4677
4678 x" = x'*(1 + k<sub>1</sub>r<sup>2</sup> + k<sub>2</sub>r<sup>4</sup>) + 2*p<sub>1</sub>x'*y' + p<sub>2</sub>(r<sup>2</sup>+2*x'<sup>2</sup>)
4679 y" = y'*(1 + k<sub>1</sub>r<sup>2</sup> + k<sub>2</sub>r<sup>4</sup>) + p<sub>1</sub>(r<sup>2</sup>+2*y'<sup>2</sup>) + 2*p<sub>2</sub>*x'*y'
4680 where r<sup>2</sup> = x'<sup>2</sup>+y'<sup>2</sup>
4681
4682 u = fx*x" + cx
4683 v = fy*y" + cy
4684 </pre>
4685
4686 k<sub>1</sub>, k<sub>2</sub> are radial distortion coefficients,
4687 p<sub>1</sub>, p<sub>2</sub> are tangential distortion coefficients.
4688 Higher-order coefficients are not considered in OpenCV.
4689 The distortion coefficients also do not depend on the scene viewed,
4690 thus they are intrinsic camera parameters.
4691 And they remain the same regardless of the captured image resolution.
4692 </p><p>
4693 The functions below use the above model to
4694 <ul>
4695 <li>Project 3D points to the image plane given intrinsic and extrinsic parameters
4696 <li>Compute extrinsic parameters given intrinsic parameters, a few 3D points and their projections.
4697 <li>Estimate intrinsic and extrinsic camera parameters from several views of a known calibration pattern
4698     (i.e. every view is described by several 3D-2D point correspondences).
4699 </ul>
4700
4701 <hr><h2><a name="cv_3d_calibration">Camera Calibration</a></h2>
4702
4703 <hr><h3><a name="decl_cvProjectPoints2">ProjectPoints2</a></h3>
4704 <p class="Blurb">Projects 3D points to image plane</p>
4705 <pre>
4706 void cvProjectPoints2( const CvMat* object_points, const CvMat* rotation_vector,
4707                        const CvMat* translation_vector, const CvMat* intrinsic_matrix,
4708                        const CvMat* distortion_coeffs, CvMat* image_points,
4709                        CvMat* dpdrot=NULL, CvMat* dpdt=NULL, CvMat* dpdf=NULL,
4710                        CvMat* dpdc=NULL, CvMat* dpddist=NULL );
4711 </pre><p><dl>
4712 <dt>object_points<dd>The array of object points, 3xN or Nx3,
4713                      where N is the number of points in the view.
4714 <dt>rotation_vector<dd>The rotation vector, 1x3 or 3x1.
4715 <dt>translation_vector<dd>The translation vector, 1x3 or 3x1.
4716 <dt>intrinsic_matrix<dd>The camera matrix (A) [fx 0 cx; 0 fy cy; 0 0 1].
4717 <dt>distortion_coeffs<dd>The vector of distortion coefficients, 4x1 or 1x4
4718                          [k<sub>1</sub>, k<sub>2</sub>, p<sub>1</sub>, p<sub>2</sub>].
4719                          If it is NULL, all distortion coefficients are considered 0's.
4720 <dt>image_points<dd>The output array of image points, 2xN or Nx2,
4721                     where N is the total number of points in the view.
4722 <dt>dpdrot<dd>Optional Nx3 matrix of derivatives of image points with respect to components of the rotation vector.
4723 <dt>dpdt<dd>Optional Nx3 matrix of derivatives of image points w.r.t. components of the translation vector.
4724 <dt>dpdf<dd>Optional Nx2 matrix of derivatives of image points w.r.t. fx and fy.
4725 <dt>dpdc<dd>Optional Nx2 matrix of derivatives of image points w.r.t. cx and cy.
4726 <dt>dpddist<dd>Optional Nx4 matrix of derivatives of image points w.r.t. distortion coefficients.
4727 </dl></p><p>
4728 The function <code>cvProjectPoints2</code> computes projections of 3D points to the image plane given
4729 intrinsic and extrinsic camera parameters. Optionally, the function computes Jacobians - matrices of
4730 partial derivatives of image points as functions of all the input parameters w.r.t. the particular parameters,
4731 intrinsic and/or extrinsic. The Jacobians are used during the global optimization in
4732 <a href="#decl_cvCalibrateCamera2">cvCalibrateCamera2</a> and
4733 <a href="#decl_cvFindExtrinsicParams2">cvFindExtrinsicCameraParams2</a>.
4734 The function itself is also used to compute back-projection error for with current
4735 intrinsic and extrinsic parameters.
4736 </p><p>
4737 Note, that with intrinsic and/or extrinsic parameters set to special values,
4738 the function can be used to compute just extrinsic transformation or just intrinsic
4739 transformation (i.e. distortion of a sparse set of points).
4740 </p>
4741
4742
4743 <hr><h3><a name="decl_cvFindHomography">FindHomography</a></h3>
4744 <p class="Blurb">Finds perspective transformation between two planes</p>
4745 <pre>
4746 void cvFindHomography( const CvMat* src_points,
4747                        const CvMat* dst_points,
4748                        CvMat* homography );
4749 </pre><p><dl>
4750 <dt>src_points<dd>Point coordinates in the original plane, 2xN, Nx2, 3xN or Nx3 array
4751                   (the latter two are for representation in homogeneous coordinates),
4752                   where N is the number of points.
4753 <dt>dst_points<dd>Point coordinates in the destination plane, 2xN, Nx2, 3xN or Nx3 array
4754                   (the latter two are for representation in homogeneous coordinates)
4755 <dt>homography<dd>Output 3x3 homography matrix.
4756 </dl></p><p>
4757 The function <code>cvFindHomography</code> finds perspective transformation <code>H=||hij||</code> between the source
4758 and the destination planes:
4759
4760 <pre>
4761   [x'<sub>i</sub>]   [x<sub>i</sub>]
4762 s<sub>i</sub>[y'<sub>i</sub>]~H*[y<sub>i</sub>]
4763   [1  ]  [ 1]
4764 </pre>
4765
4766 So that the back-projection error is minimized:
4767
4768 <pre>
4769 sum_i((x'<sub>i</sub>-(h11*x<sub>i</sub> + h12*y<sub>i</sub> + h13)/(h31*x<sub>i</sub> + h32*y<sub>i</sub> + h33))<sup>2</sup>+
4770       (y'<sub>i</sub>-(h21*x<sub>i</sub> + h22*y<sub>i</sub> + h23)/(h31*x<sub>i</sub> + h32*y<sub>i</sub> + h33))<sup>2</sup>) -> min
4771 </pre>
4772
4773 The function is used to find initial intrinsic and extrinsic matrices.
4774 Homography matrix is determined up to a scale, thus it is normalized to make h33=1.</p>
4775
4776
4777 <hr><h3><a name="decl_cvCalibrateCamera2">CalibrateCamera2</a></h3>
4778 <p class="Blurb">Finds intrinsic and extrinsic camera parameters using calibration pattern</p>
4779 <pre>
4780 void cvCalibrateCamera2( const CvMat* object_points, const CvMat* image_points,
4781                          const CvMat* point_counts, CvSize image_size,
4782                          CvMat* intrinsic_matrix, CvMat* distortion_coeffs,
4783                          CvMat* rotation_vectors=NULL, CvMat* translation_vectors=NULL,
4784                          int flags=0 );
4785 </pre><p><dl>
4786 <dt>object_points<dd>The joint matrix of object points, 3xN or Nx3,
4787                      where N is the total number of points in all views.
4788 <dt>image_points<dd>The joint matrix of corresponding image points, 2xN or Nx2,
4789                     where N is the total number of points in all views.
4790 <dt>point_counts<dd>Vector containing numbers of points in each particular view,
4791                     1xM or Mx1, where M is the number of a scene views.
4792 <dt>image_size<dd>Size of the image, used only to initialize intrinsic camera matrix.
4793 <dt>intrinsic_matrix<dd>The output camera matrix (A) [fx 0 cx; 0 fy cy; 0 0 1].
4794                   If <code>CV_CALIB_USE_INTRINSIC_GUESS</code> and/or
4795                   <code>CV_CALIB_FIX_ASPECT_RATION</code> are specified, some or all
4796                   of <code>fx, fy, cx, cy</code> must be initialized.
4797 <dt>distortion_coeffs<dd>The output 4x1 or 1x4 vector of distortion coefficients
4798                          [k<sub>1</sub>, k<sub>2</sub>, p<sub>1</sub>, p<sub>2</sub>].
4799 <dt>rotation_vectors<dd>The output 3xM or Mx3 array of rotation vectors
4800                         (compact representation of rotation matrices,
4801                         see <a href="#decl_cvRodrigues2">cvRodrigues2</a>).
4802 <dt>translation_vectors<dd>The output 3xM or Mx3 array of translation vectors.
4803 <dt>flags<dd>Different flags, may be 0 or combination of the following values:<br>
4804              <code>CV_CALIB_USE_INTRINSIC_GUESS</code> - <code>intrinsic_matrix</code> contains
4805              valid initial values of <code>fx, fy, cx, cy</code> that are optimized further.
4806              Otherwise, <code>(cx, cy)</code> is initially set to the image center
4807              (<code>image_size</code> is used here),
4808              and focal distances are computed in some least-squares fashion.
4809              Note, that if intrinsic parameters are known, there is no need to use this function.
4810              Use <a href="#decl_cvFindExtrinsicCameraParams2">cvFindExtrinsicCameraParams2</a> instead.<br>
4811              <code>CV_CALIB_FIX_PRINCIPAL_POINT</code> - The principal point is not changed during the global
4812              optimization, it stays at the center and at the other location specified (when
4813              <code>CV_CALIB_USE_INTRINSIC_GUESS</code> is set as well).<br>
4814              <code>CV_CALIB_FIX_ASPECT_RATIO</code> - The optimization procedure consider only
4815              one of <code>fx</code> and <code>fy</code> as independent variable and keeps the aspect ratio
4816              <code>fx/fy</code> the same as it was set initially in <code>intrinsic_matrix</code>.
4817              In this case the actual initial values of <code>(fx, fy)</code> are either taken from the matrix
4818              (when <code>CV_CALIB_USE_INTRINSIC_GUESS</code> is set) or estimated somehow (in the latter case
4819              <code>fx, fy</code> may be set to arbitrary values, only their ratio is used).<br>
4820              <code>CV_CALIB_ZERO_TANGENT_DIST</code> - Tangential distortion coefficients are set to
4821              zeros and do not change during the optimization.<br>
4822 </dl></p><p>
4823 The function <code>cvCalibrateCamera2</code> estimates intrinsic camera parameters and extrinsic parameters
4824 for each of the views.
4825 The coordinates of 3D object points and their correspondent 2D projections in each view
4826 must be specified. That may be achieved by using an object with known geometry and easily detectable
4827 feature points. Such an object is called a calibration rig or calibration pattern, and OpenCV has built-in
4828 support for a chess board as a calibration rig
4829 (see <a href="#decl_cvFindChessboardCorners">cvFindChessboardCorners</a>).
4830 Currently, initialization of intrinsic parameters (when <code>CV_CALIB_USE_INTRINSIC_GUESS</code>
4831 is not set) is only implemented for planar calibration rigs (z-coordinates of object points
4832 must be all 0's or all 1's). 3D rigs can still be used as long as initial <code>intrinsic_matrix</code>
4833 is provided. After the initial values of intrinsic and extrinsic parameters are computed, they are
4834 optimized to minimize the total back-projection error - the sum of squared differences between the
4835 actual coordinates of image points and the ones computed using
4836 <a href="#decl_cvProjectPoints2">cvProjectPoints2</a>.
4837 </p>
4838
4839
4840 <hr><h3><a name="decl_cvCalibrationMatrixValues">CalibrationMatrixValues</a></h3>
4841 <p class="Blurb">Finds intrinsic and extrinsic camera parameters using calibration pattern</p>
4842 <pre>
4843 void cvCalibrationMatrixValues( const CvMat *calibMatr,
4844                                 int imgWidth, int imgHeight,
4845                                 double apertureWidth=0, double apertureHeight=0,
4846                                 double *fovx=NULL, double *fovy=NULL,
4847                                 double *focalLength=NULL,
4848                                 CvPoint2D64f *principalPoint=NULL,
4849                                 double *pixelAspectRatio=NULL );
4850 </pre><p><dl>
4851 <dt>calibMatr<dd>The matrix of intrinsic parameters, e.g. computed by <a href="#decl_cvCalibrateCamera2">cvCalibrateCamera2</a>
4852 <dt>imgWidth<dd>Image width in pixels
4853 <dt>imgHeight<dd>Image height in pixels
4854 <dt>apertureWidth<dd>Aperture width in realworld units (optional input parameter)
4855 <dt>apertureHeight<dd>Aperture width in realworld units (optional input parameter)
4856 <dt>fovx<dd>Field of view angle in x direction in degrees (optional output parameter)
4857 <dt>fovx<dd>Field of view angle in y direction in degrees (optional output parameter)
4858 <dt>focalLength<dd>Focal length in realworld units (optional output parameter)
4859 <dt>principalPoint<dd>The principal point in realworld units (optional output parameter)
4860 <dt>pixelAspectRatio<dd>The pixel aspect ratio ~ fy/fx (optional output parameter)
4861 </dl></p><p>
4862 The function <code>cvCalibrationMatrixValues</code> computes various useful camera (sensor/lens)
4863 characteristics using the computed camera calibration matrix, image frame resolution in pixels
4864 and the physical aperture size.</p>
4865
4866
4867 <hr><h3><a name="decl_cvFindExtrinsicCameraParams2">FindExtrinsicCameraParams2</a></h3>
4868 <p class="Blurb">Finds extrinsic camera parameters for particular view</p>
4869 <pre>
4870 void cvFindExtrinsicCameraParams2( const CvMat* object_points,
4871                                    const CvMat* image_points,
4872                                    const CvMat* intrinsic_matrix,
4873                                    const CvMat* distortion_coeffs,
4874                                    CvMat* rotation_vector,
4875                                    CvMat* translation_vector );
4876 </pre><p><dl>
4877 <dt>object_points<dd>The array of object points, 3xN or Nx3,
4878                      where N is the number of points in the view.
4879 <dt>image_points<dd>The array of corresponding image points, 2xN or Nx2,
4880                     where N is the number of points in the view.
4881 <dt>intrinsic_matrix<dd>The camera matrix (A) [fx 0 cx; 0 fy cy; 0 0 1].
4882 <dd><dt>distortion_coeffs<dd>The vector of distortion coefficients, 4x1 or 1x4
4883                          [k<sub>1</sub>, k<sub>2</sub>, p<sub>1</sub>, p<sub>2</sub>].
4884                          If it is NULL, all distortion coefficients are considered 0's.
4885 <dt>rotation_vector<dd>The output 3x1 or 1x3 rotation vector
4886                        (compact representation of a rotation matrix,
4887                        see <a href="#decl_cvRodrigues2">cvRodrigues2</a>).
4888 <dt>translation_vector<dd>The output 3x1 or 1x3 translation vector.
4889 </dl></p><p>
4890 The function <code>cvFindExtrinsicCameraParams2</code> estimates extrinsic camera parameters
4891 using known intrinsic parameters and and extrinsic parameters
4892 for each view. The coordinates of 3D object points and their correspondent 2D projections
4893 must be specified. This function also minimizes back-projection error.
4894 </p>
4895
4896
4897 <hr><h3><a name="decl_cvRodrigues2">Rodrigues2</a></h3>
4898 <p class="Blurb">Converts rotation matrix to rotation vector or vice versa</p>
4899 <pre>
4900 int  cvRodrigues2( const CvMat* src, CvMat* dst, CvMat* jacobian=0 );
4901 </pre><p><dl>
4902 <dt>src<dd>The input rotation vector (3x1 or 1x3) or rotation matrix (3x3).
4903 <dt>dst<dd>The output rotation matrix (3x3) or rotation vector (3x1 or 1x3), respectively.
4904 <dt>jacobian<dd>Optional output Jacobian matrix, 3x9 or 9x3 - partial derivatives of
4905                 the output array components w.r.t the input array components.
4906 </dl></p><p>
4907 The function <code>cvRodrigues2</code> converts a rotation vector to rotation matrix or
4908 vice versa. Rotation vector is a compact representation of rotation matrix.
4909 Direction of the rotation vector is the rotation axis and the length of the vector is the rotation
4910 angle around the axis.
4911 The rotation matrix <code>R</code>, corresponding to the rotation vector <code>r</code>,
4912 is computed as following:
4913 <pre>
4914 theta &lt;- norm(r)
4915 r &lt;- r/theta
4916                                                    [0 -r<sub>z</sub> r<sub>y</sub>]
4917 R = cos(theta)*I + (1-cos(theta))*rr<sup>T</sup> + sin(theta)*[r<sub>z</sub> 0 -r<sub>x</sub>]
4918                                                    [r<sub>y</sub> r<sub>x</sub> 0]
4919 </pre>
4920
4921 Inverse transformation can also be done easily as
4922
4923 <pre>
4924
4925 [0 -r<sub>z</sub> r<sub>y</sub>]
4926 sin(theta)*[r<sub>z</sub> 0 -r<sub>x</sub>] = (R - R<sup>T</sup>)/2
4927 [r<sub>y</sub> r<sub>x</sub> 0]
4928
4929 </pre>
4930
4931 Rotation vector is a convenient representation of a rotation matrix as a matrix with only 3 degrees of freedom.
4932 The representation is used in the global optimization procedures inside
4933 <a href="#decl_cvFindExtrinsicCameraParams2">cvFindExtrinsicCameraParams2</a> and
4934 <a href="#decl_cvCalibrateCamera2">cvCalibrateCamera2</a>.
4935 </p>
4936
4937
4938 <hr><h3><a name="decl_cvUndistort2">Undistort2</a></h3>
4939 <p class="Blurb">Transforms image to compensate lens distortion</p>
4940 <pre>
4941 void cvUndistort2( const CvArr* src, CvArr* dst,
4942                    const CvMat* intrinsic_matrix,
4943                    const CvMat* distortion_coeffs );
4944 </pre><p><dl>
4945 <dt>src<dd>The input (distorted) image.
4946 <dt>dst<dd>The output (corrected) image.
4947 <dt>intrinsic_matrix<dd>The camera matrix (A) [fx 0 cx; 0 fy cy; 0 0 1].
4948 <dd><dt>distortion_coeffs<dd>The vector of distortion coefficients, 4x1 or 1x4
4949                          [k<sub>1</sub>, k<sub>2</sub>, p<sub>1</sub>, p<sub>2</sub>].
4950 </dl></p><p>
4951 The function <code>cvUndistort2</code> transforms the image to compensate radial and tangential lens distortion.
4952 The camera matrix and distortion parameters can be determined using
4953 <a href="#decl_cvCalibrateCamera2">cvCalibrateCamera2</a>.
4954 For every pixel in the output image the function computes coordinates of the corresponding location in the input
4955 image using the formulae in the section beginning. Then, the pixel value is computed using bilinear interpolation.
4956 If the resolution of images is different from what was used at the calibration stage,
4957 <code>fx, fy, cx</code> and <code>cy</code> need to be adjusted appropriately, while
4958 the distortion coefficients remain the same.
4959 </p>
4960
4961 <hr><h3><a name="decl_cvInitUndistortMap">InitUndistortMap</a></h3>
4962 <p class="Blurb">Computes undistortion map</p>
4963 <pre>
4964 void cvInitUndistortMap( const CvMat* intrinsic_matrix,
4965                          const CvMat* distortion_coeffs,
4966                          CvArr* mapx, CvArr* mapy );
4967 </pre><p><dl>
4968 <dt>intrinsic_matrix<dd>The camera matrix (A) [fx 0 cx; 0 fy cy; 0 0 1].
4969 <dd><dt>distortion_coeffs<dd>The vector of distortion coefficients, 4x1 or 1x4
4970                          [k<sub>1</sub>, k<sub>2</sub>, p<sub>1</sub>, p<sub>2</sub>].
4971 <dt>mapx<dd>The output array of x-coordinates of the map.
4972 <dt>mapy<dd>The output array of y-coordinates of the map.
4973 </dl></p><p>
4974 The function <code>cvInitUndistortMap</code> pre-computes the undistortion map
4975 - coordinates of the corresponding pixel in the distorted image for every pixel in the corrected image.
4976 Then, the map (together with input and output images) can be passed
4977 to <a href="#decl_cvRemap">cvRemap</a> function.
4978 </p>
4979
4980 <hr><h3><a name="decl_cvFindChessboardCorners">FindChessboardCorners</a></h3>
4981 <p class="Blurb">Finds positions of internal corners of the chessboard</p>
4982 <pre>
4983 int cvFindChessboardCorners( const void* image, CvSize pattern_size,
4984                              CvPoint2D32f* corners, int* corner_count=NULL,
4985                              int flags=CV_CALIB_CB_ADAPTIVE_THRESH );
4986 </pre><p><dl>
4987 <dt>image<dd>Source chessboard view; it must be 8-bit grayscale or color image.
4988 <dt>pattern_size<dd>The number of inner corners per chessboard row and column.
4989 <dt>corners<dd>The output array of corners detected.
4990 <dt>corner_count<dd>The output corner counter. If it is not NULL, the function stores
4991 there the number of corners found.
4992 <dt>flags<dd>Various operation flags, can be 0 or a combination of the following values:<br>
4993                      <code>CV_CALIB_CB_ADAPTIVE_THRESH</code> - use adaptive thresholding to convert the
4994                      image to black-n-white, rather than a fixed threshold level (computed from the average image brightness).<br>
4995                      <code>CV_CALIB_CB_NORMALIZE_IMAGE</code> - normalize the image using
4996                      <a href="#decl_cvNormalizeHist">cvNormalizeHist</a> before applying fixed or adaptive thresholding.<br>
4997                      <code>CV_CALIB_CB_FILTER_QUADS</code> - use additional criteria (like contour area, perimeter,
4998                      square-like shape) to filter out false quads that are extracted at the contour retrieval stage.<br>
4999 </dl></p><p>
5000 The function <code>cvFindChessboardCorners</code> attempts to determine whether the input
5001 image is a view of the chessboard pattern and locate internal chessboard
5002 corners. The function returns non-zero value if all the corners have been found
5003 and they have been placed in a certain order (row by row, left to right in every
5004 row), otherwise, if the function fails to find all the corners or reorder them,
5005 it returns 0. For example, a regular chessboard has 8 x 8 squares and 7
5006 x 7 internal corners, that is, points, where the black squares touch each other.
5007 The coordinates detected are approximate, and to determine their position more accurately,
5008 the user may use the function <a href="#decl_cvFindCornerSubPix">cvFindCornerSubPix</a>.
5009 </p>
5010
5011
5012 <hr><h3><a name="decl_cvDrawChessBoardCorners">DrawChessBoardCorners</a></h3>
5013 <p class="Blurb">Renders the detected chessboard corners</p>
5014 <pre>
5015 void cvDrawChessboardCorners( CvArr* image, CvSize pattern_size,
5016                               CvPoint2D32f* corners, int count,
5017                               int pattern_was_found );
5018 </pre><p><dl>
5019 <dt>image<dd>The destination image; it must be 8-bit color image.
5020 <dt>pattern_size<dd>The number of inner corners per chessboard row and column.
5021 <dt>corners<dd>The array of corners detected.
5022 <dt>count<dd>The number of corners.
5023 <dt>pattern_was_found<dd>Indicates whether the complete board was found (&ne;0) or not (=0). One may just
5024                      pass the return value <a href="#decl_cvFindChessboardCorners">cvFindChessboardCorners</a> here.
5025 </dl></p><p>
5026 The function <code>cvDrawChessboardCorners</code> draws the individual chessboard corners detected (as red circles)
5027 in case if the board was not found (<code>pattern_was_found</code>=0) or the colored corners connected with lines
5028 when the board was found (<code>pattern_was_found</code>&ne;0).
5029 </p>
5030
5031
5032 <hr><h2><a name="cv_3d_pose">Pose Estimation</a></h2>
5033
5034 <hr><h3><a name="decl_cvCreatePOSITObject">CreatePOSITObject</a></h3>
5035 <p class="Blurb">Initializes structure containing object information</p>
5036 <pre>
5037 CvPOSITObject* cvCreatePOSITObject( CvPoint3D32f* points, int point_count );
5038 </pre><p><dl>
5039 <dt>points<dd>Pointer to the points of the 3D object model.
5040 <dt>point_count<dd>Number of object points.
5041 </dl></p><p>
5042 The function <code>cvCreatePOSITObject</code> allocates memory for the object structure and
5043 computes the object inverse matrix.
5044 <p>
5045 The pre-processed object data is stored in the structure <a href="#decl_CvPOSITObject">CvPOSITObject</a>, internal
5046 for OpenCV, which means that the user cannot directly access the structure data.
5047 The user may only create this structure and pass its pointer to the function.
5048 </p>
5049 <p>
5050 Object is defined as a set of points given in a coordinate system. The function
5051 <a href="#decl_cvPOSIT">cvPOSIT</a> computes a vector that begins at a camera-related coordinate system center
5052 and ends at the <code>points[0]</code> of the object.
5053 </p>
5054 Once the work with a given object is finished, the function
5055 <a href="#decl_cvReleasePOSITObject">cvReleasePOSITObject</a>
5056 must be called to free memory.
5057
5058 </p><hr><h3><a name="decl_cvPOSIT">POSIT</a></h3>
5059 <p class="Blurb">Implements POSIT algorithm</p>
5060 <pre>
5061 void cvPOSIT( CvPOSITObject* posit_object, CvPoint2D32f* image_points, double focal_length,
5062               CvTermCriteria criteria, CvMatr32f rotation_matrix, CvVect32f translation_vector );
5063 </pre><p><dl>
5064 <dt>posit_object<dd>Pointer to the object structure.
5065 <dt>image_points<dd>Pointer to the object points projections on the 2D image plane.
5066 <dt>focal_length<dd>Focal length of the camera used.
5067 <dt>criteria<dd>Termination criteria of the iterative POSIT algorithm.
5068 <dt>rotation_matrix<dd>Matrix of rotations.
5069 <dt>translation_vector<dd>Translation vector.
5070 </dl></p><p>
5071 The function <code>cvPOSIT</code> implements POSIT algorithm. Image coordinates are given in a
5072 camera-related coordinate system. The focal length may be retrieved using camera
5073 calibration functions. At every iteration of the algorithm new perspective
5074 projection of estimated pose is computed.
5075 <p>
5076 Difference norm between two projections is the maximal distance between
5077 corresponding points. The parameter <code>criteria.epsilon</code> serves to stop the
5078 algorithm if the difference is small.
5079 </p>
5080
5081 </p><hr><h3><a name="decl_cvReleasePOSITObject">ReleasePOSITObject</a></h3>
5082 <p class="Blurb">Deallocates 3D object structure</p>
5083 <pre>
5084 void cvReleasePOSITObject( CvPOSITObject** posit_object );
5085 </pre><p><dl>
5086 <dt>posit_object<dd>Double pointer to <code>CvPOSIT</code> structure.
5087 </dl></p><p>
5088 The function <code>cvReleasePOSITObject</code> releases memory previously allocated by the
5089 function <a href="#decl_cvCreatePOSITObject">cvCreatePOSITObject</a>.
5090 </p>
5091
5092 <hr><h3><a name="decl_cvCalcImageHomography">CalcImageHomography</a></h3>
5093 <p class="Blurb">Calculates homography matrix for oblong planar object (e.g. arm)</p>
5094 <pre>
5095 void cvCalcImageHomography( float* line, CvPoint3D32f* center,
5096                             float* intrinsic, float* homography );
5097 </pre><p><dl>
5098 <dt>line<dd>the main object axis direction (vector (dx,dy,dz)).
5099 <dt>center<dd>object center ((cx,cy,cz)).
5100 <dt>intrinsic<dd>intrinsic camera parameters (3x3 matrix).
5101 <dt>homography<dd>output homography matrix (3x3).
5102 </dl></p><p>
5103 The function <code>cvCalcImageHomography</code> calculates the homography matrix for the initial
5104 image transformation from image plane to the plane, defined by 3D oblong object line (See
5105 <u><font color=blue>Figure 6-10</font></u> in OpenCV Guide 3D Reconstruction Chapter).
5106 </p>
5107
5108 <!-- by Valery Mosyagin -->
5109
5110 <hr><h2><a name="cv_3d_epipolar">Epipolar Geometry</a></h2>
5111
5112 <hr><h3><a name="decl_cvFindFundamentalMat">FindFundamentalMat</a></h3>
5113 <p class="Blurb">Calculates fundamental matrix from corresponding points in two images</p>
5114 <pre>
5115 int cvFindFundamentalMat( const CvMat* points1,
5116                           const CvMat* points2,
5117                           CvMat* fundamental_matrix,
5118                           int    method=CV_FM_RANSAC,
5119                           double param1=1.,
5120                           double param2=0.99,
5121                           CvMat* status=NULL);
5122 </pre>
5123 <p>
5124 <dl>
5125 <dt>points1<dd>Array of the first image points of <code>2xN, Nx2, 3xN</code> or <code>Nx3</code> size
5126                (where <code>N</code> is number of points).
5127                Multi-channel <code>1xN</code> or <code>Nx1</code> array is also acceptable.
5128                The point coordinates should be floating-point (single or double precision)
5129 <dt>points2<dd>Array of the second image points of the same size and format as <code>points1</code>
5130 <dt>fundamental_matrix <dd>The output fundamental matrix or matrices. The size should be 3x3 or 9x3
5131                            (7-point method may return up to 3 matrices).
5132 <dt>method<dd>Method for computing the fundamental matrix
5133           <dd>CV_FM_7POINT - for 7-point algorithm. N == 7
5134           <dd>CV_FM_8POINT - for 8-point algorithm. N >= 8
5135           <dd>CV_FM_RANSAC - for RANSAC  algorithm. N >= 8
5136           <dd>CV_FM_LMEDS  - for LMedS   algorithm. N >= 8
5137 <dt>param1<dd>The parameter is used for RANSAC or LMedS methods only.
5138             It is the maximum distance from point to epipolar line in pixels,
5139             beyond which the point is considered an outlier and is not used
5140             for computing the final fundamental matrix.
5141             Usually it is set to 0.5 or 1.0.
5142 <dt>param2 <dd>The parameter is used for RANSAC or LMedS methods only.
5143             It denotes the desirable level of confidence that the matrix
5144             is correct.
5145 <dt>status<dd>The optional output array of N elements,
5146             every element of which is set to 0 for outliers
5147             and to 1 for the other points.
5148             The array is computed only in RANSAC and LMedS methods.
5149             For other methods it is set to all 1&#146;s.</p>
5150 </dl></p>
5151
5152 <p>
5153 The epipolar geometry is described by the following equation:
5154 <pre>p<sub>2</sub><sup>T</sup>*F*p<sub>1</sub>=0,</pre>
5155 </p>
5156
5157 <p>where <code>F</code> is fundamental matrix, <code>p<sub>1</sub></code> and <code>p<sub>2</sub></code> are corresponding
5158 points in the first and the second images, respectively.
5159 </p>
5160
5161 <p>
5162 The function <code>cvFindFundamentalMat</code> calculates fundamental matrix using one of four
5163 methods listed above and returns the number of fundamental matrices found (1 or 3) and 0,
5164 if no matrix is found.
5165 </p>
5166
5167 <p>
5168 The calculated fundamental matrix may be passed further to <code>cvComputeCorrespondEpilines</code>
5169 that finds epipolar lines corresponding to the specified points.</p>
5170
5171 <h4>Example. Estimation of fundamental matrix using RANSAC algorithm</h4>
5172 <pre>
5173 int point_count = 100;
5174 CvMat* points1;
5175 CvMat* points2;
5176 CvMat* status;
5177 CvMat* fundamental_matrix;
5178
5179 points1 = cvCreateMat(1,point_count,CV_32FC2);
5180 points2 = cvCreateMat(1,point_count,CV_32FC2);
5181 status = cvCreateMat(1,point_count,CV_8UC1);
5182
5183 /* Fill the points here ... */
5184 for( i = 0; i &lt; point_count; i++ )
5185 {
5186     points1->data.db[i*2] = &lt;x<sub>1,i</sub>&gt;;
5187     points1->data.db[i*2+1] = &lt;y<sub>1,i</sub>&gt;;
5188     points2->data.db[i*2] = &lt;x<sub>2,i</sub>&gt;;
5189     points2->data.db[i*2+1] = &lt;y<sub>2,i</sub>&gt;;
5190 }
5191
5192 fundamental_matrix = cvCreateMat(3,3,CV_32FC1);
5193 int fm_count = cvFindFundamentalMat( points1,points2,fundamental_matrix,
5194                                      CV_FM_RANSAC,1.0,0.99,status );
5195 </pre>
5196
5197
5198 <hr>
5199 <h3><a name="decl_cvComputeCorrespondEpilines">ComputeCorrespondEpilines</a></h3>
5200 <p class="Blurb">For points in one image of stereo pair computes the corresponding epilines in the other image</p>
5201
5202 <pre>
5203 void cvComputeCorrespondEpilines( const CvMat* points,
5204                                   int which_image,
5205                                   const CvMat* fundamental_matrix,
5206                                   CvMat* correspondent_lines);
5207 </pre>
5208 <p><dl>
5209
5210 <dt>points<dd>The input points. <code>2xN, Nx2, 3xN</code> or <code>Nx3</code> array (where <code>N</code> number of points).
5211               Multi-channel <code>1xN</code> or <code>Nx1</code> array is also acceptable.
5212 <dt>which_image<dd>Index of the image (1 or 2) that contains the <code>points</code>
5213 <dt>fundamental_matrix <dd>Fundamental matrix
5214 <dt>correspondent_lines<dd>Computed epilines, <code>3xN</code> or <code>Nx3</code> array
5215
5216 </dl></p>
5217
5218 <p>
5219 For every point in one of the two images of stereo-pair the function
5220 <code>cvComputeCorrespondEpilines</code> finds equation of a line that contains
5221 the corresponding point (i.e. projection of the same 3D point) in the other image.
5222 Each line is encoded by a vector of 3 elements <code>l=[a,b,c]<sup>T</sup></code>, so that:
5223 <pre>
5224
5225 l<sup>T</sup>*[x, y, 1]<sup>T</sup>=0, or
5226 a*x + b*y + c = 0
5227
5228 </pre>
5229
5230 From the fundamental matrix definition (see <a href="#decl_cvFindFundamentalMatrix">cvFindFundamentalMatrix</a>
5231 discussion), line <code>l<sub>2</sub></code> for a point <code>p<sub>1</sub></code>
5232 in the first image (<code>which_image</code>=1) can be computed as:
5233
5234 <pre>l<sub>2</sub>=F*p<sub>1</sub></pre>
5235
5236 and the line <code>l<sub>1</sub></code> for a point <code>p<sub>2</sub></code>
5237 in the second image (<code>which_image</code>=1) can be computed as:
5238
5239 <pre>l<sub>1</sub>=F<sup>T</sup>*p<sub>2</sub></pre>
5240
5241 <p>
5242 Line coefficients are defined up to a scale.
5243 They are normalized (<code>a<sup>2</sup>+b<sup>2</sup>=1</code>)
5244 are stored into <code>correspondent_lines</code>.
5245 </p>
5246
5247
5248 <hr>
5249 <h3><a name="decl_cvConvertPointsHomogenious">ConvertPointsHomogenious</a></h3>
5250 <p class="Blurb">Convert points to/from homogeneous coordinates</p>
5251
5252 <pre>
5253 void cvConvertPointsHomogenious( const CvMat* src, CvMat* dst );
5254 </pre>
5255 <p><dl>
5256
5257 <dt>src<dd>The input point array, <code>2xN, Nx2, 3xN, Nx3, 4xN or Nx4</code>
5258            (where <code>N</code> is the number of points).
5259            Multi-channel <code>1xN</code> or <code>Nx1</code> array is also acceptable.
5260 <dt>dst<dd>The output point array, must contain the same number of points as the input;
5261            The dimensionality must be the same, 1 less or 1 more than the input, and
5262            also within 2..4.
5263 </dl></p>
5264
5265 <p>
5266 The function <code>cvConvertPointsHomogenious</code> converts 2D or 3D points
5267 from/to homogeneous coordinates, or simply copies or transposes the array.
5268 In case if the input array dimensionality is larger than the output,
5269 each point coordinates are divided by the last coordinate:
5270 <pre>
5271 (x,y[,z],w) -> (x',y'[,z']):
5272
5273 x' = x/w
5274 y' = y/w
5275 z' = z/w (if output is 3D)
5276 </pre>
5277
5278 If the output array dimensionality is larger, an extra 1 is appended to each point.
5279 <pre>
5280 (x,y[,z]) -> (x,y[,z],1)
5281 </pre>
5282
5283 Otherwise, the input array is simply copied (with optional transposition) to the output.
5284 <b>Note</b> that, because the function accepts a large variety of array layouts, it
5285 may report an error when input/output array dimensionality is ambiguous.
5286 It is always safe to use the function with number of points <code>N</code>&gt;=5, or
5287 to use multi-channel <code>Nx1</code> or <code>1xN</code> arrays.
5288
5289 <hr><h1><a name="cv_func_index">Alphabetical List of Functions</a></h1>
5290
5291 <hr><h3>2</h3>
5292 <table width="100%">
5293 <tr>
5294 <td width="25%"><a href="#decl_cv2DRotationMatrix">2DRotationMatrix</a></td>
5295 <td width="25%%"></td>
5296 <td width="25%%"></td>
5297 </tr>
5298 </table>
5299 <hr><h3>A</h3>
5300 <table width="100%">
5301 <tr>
5302 <td width="25%"><a href="#decl_cvAcc">Acc</a></td>
5303 <td width="25%"><a href="#decl_cvApproxChains">ApproxChains</a></td>
5304 <td width="25%"><a href="#decl_cvArcLength">ArcLength</a></td>
5305 </tr>
5306 <tr>
5307 <td width="25%"><a href="#decl_cvAdaptiveThreshold">AdaptiveThreshold</a></td>
5308 <td width="25%"><a href="#decl_cvApproxPoly">ApproxPoly</a></td>
5309 <td width="25%%"></td>
5310 </tr>
5311 </table>
5312 <hr><h3>B</h3>
5313 <table width="100%">
5314 <tr>
5315 <td width="25%"><a href="#decl_cvBoundingRect">BoundingRect</a></td>
5316 <td width="25%"><a href="#decl_cvBoxPoints">BoxPoints</a></td>
5317 <td width="25%%"></td>
5318 </tr>
5319 </table>
5320 <hr><h3>C</h3>
5321 <table width="100%">
5322 <tr>
5323 <td width="25%"><a href="#decl_cvCalcBackProject">CalcBackProject</a></td>
5324 <td width="25%"><a href="#decl_cvCalcBackProjectPatch">CalcBackProjectPatch</a></td>
5325 <td width="25%"><a href="#decl_cvCalcEMD2">CalcEMD2</a></td>
5326 </tr>
5327 <tr>
5328 <td width="25%"><a href="#decl_cvCalcGlobalOrientation">CalcGlobalOrientation</a></td>
5329 <td width="25%"><a href="#decl_cvCalcHist">CalcHist</a></td>
5330 <td width="25%"><a href="#decl_cvCalcImageHomography">CalcImageHomography</a></td>
5331 </tr>
5332 <tr>
5333 <td width="25%"><a href="#decl_cvCalcMotionGradient">CalcMotionGradient</a></td>
5334 <td width="25%"><a href="#decl_cvCalcOpticalFlowBM">CalcOpticalFlowBM</a></td>
5335 <td width="25%"><a href="#decl_cvCalcOpticalFlowHS">CalcOpticalFlowHS</a></td>
5336 </tr>
5337 <tr>
5338 <td width="25%"><a href="#decl_cvCalcOpticalFlowLK">CalcOpticalFlowLK</a></td>
5339 <td width="25%"><a href="#decl_cvCalcOpticalFlowPyrLK">CalcOpticalFlowPyrLK</a></td>
5340 <td width="25%"><a href="#decl_cvCalcPGH">CalcPGH</a></td>
5341 </tr>
5342 <tr>
5343 <td width="25%"><a href="#decl_cvCalcProbDensity">CalcProbDensity</a></td>
5344 <td width="25%"><a href="#decl_cvCalcSubdivVoronoi2D">CalcSubdivVoronoi2D</a></td>
5345 <td width="25%"><a href="#decl_cvCalibrateCamera2">CalibrateCamera2</a></td>
5346 </tr>
5347 <tr>
5348 <td width="25%"><a href="#decl_cvCamShift">CamShift</a></td>
5349 <td width="25%"><a href="#decl_cvCanny">Canny</a></td>
5350 <td width="25%"><a href="#decl_cvCheckContourConvexity">CheckContourConvexity</a></td>
5351 </tr>
5352 <tr>
5353 <td width="25%"><a href="#decl_cvClearHist">ClearHist</a></td>
5354 <td width="25%"><a href="#decl_cvClearSubdivVoronoi2D">ClearSubdivVoronoi2D</a></td>
5355 <td width="25%"><a href="#decl_cvCompareHist">CompareHist</a></td>
5356 </tr>
5357 <tr>
5358 <td width="25%"><a href="#decl_cvComputeCorrespondEpilines">ComputeCorrespondEpilines</a></td>
5359 <td width="25%"><a href="#decl_cvConDensInitSampleSet">ConDensInitSampleSet</a></td>
5360 <td width="25%"><a href="#decl_cvConDensUpdateByTime">ConDensUpdateByTime</a></td>
5361 </tr>
5362 <tr>
5363 <td width="25%"><a href="#decl_cvContourArea">ContourArea</a></td>
5364 <td width="25%"><a href="#decl_cvContourFromContourTree">ContourFromContourTree</a></td>
5365 <td width="25%"><a href="#decl_cvConvertPointsHomogenious">ConvertPointsHomogenious</a></td>
5366 </tr>
5367 <tr>
5368 <td width="25%"><a href="#decl_cvConvexHull2">ConvexHull2</a></td>
5369 <td width="25%"><a href="#decl_cvConvexityDefects">ConvexityDefects</a></td>
5370 <td width="25%"><a href="#decl_cvCopyHist">CopyHist</a></td>
5371 </tr>
5372 <tr>
5373 <td width="25%"><a href="#decl_cvCopyMakeBorder">CopyMakeBorder</a></td>
5374 <td width="25%"><a href="#decl_cvCornerEigenValsAndVecs">CornerEigenValsAndVecs</a></td>
5375 <td width="25%"><a href="#decl_cvCornerHarris">CornerHarris</a></td>
5376 </tr>
5377 <tr>
5378 <td width="25%"><a href="#decl_cvCornerMinEigenVal">CornerMinEigenVal</a></td>
5379 <td width="25%"><a href="#decl_cvCreateConDensation">CreateConDensation</a></td>
5380 <td width="25%"><a href="#decl_cvCreateContourTree">CreateContourTree</a></td>
5381 </tr>
5382 <tr>
5383 <td width="25%"><a href="#decl_cvCreateFeatureTree">cvCreateFeatureTree</a></td>
5384 <td width="25%"><a href="#decl_cvCreateHist">CreateHist</a></td>
5385 <td width="25%"><a href="#decl_cvCreateKalman">CreateKalman</a></td>
5386 </tr>
5387 <tr>
5388 <td width="25%"><a href="#decl_cvCreatePOSITObject">CreatePOSITObject</a></td>
5389 <td width="25%"><a href="#decl_cvCreateStructuringElementEx">CreateStructuringElementEx</a></td>
5390 <td width="25%"><a href="#decl_cvCreateSubdivDelaunay2D">CreateSubdivDelaunay2D</a></td>
5391 </tr>
5392 <tr>
5393 <td width="25%"><a href="#decl_cvCvtColor">CvtColor</a></td>
5394 </tr>
5395 </table>
5396 <hr><h3>D</h3>
5397 <table width="100%">
5398 <tr>
5399 <td width="25%"><a href="#decl_cvDilate">Dilate</a></td>
5400 <td width="25%"><a href="#decl_cvDistTransform">DistTransform</a></td>
5401 <td width="25%"><a href="#decl_cvDrawChessBoardCorners">DrawChessBoardCorners</a></td>
5402 </tr>
5403 </table>
5404 <hr><h3>E</h3>
5405 <table width="100%">
5406 <tr>
5407 <td width="25%"><a href="#decl_cvEndFindContours">EndFindContours</a></td>
5408 <td width="25%"><a href="#decl_cvEqualizeHist">EqualizeHist</a></td>
5409 <td width="25%"><a href="#decl_cvErode">Erode</a></td>
5410 </tr>
5411 </table>
5412 <hr><h3>F</h3>
5413 <table width="100%">
5414 <tr>
5415 <td width="25%"><a href="#decl_cvFilter2D">Filter2D</a></td>
5416 <td width="25%"><a href="#decl_cvFindChessboardCorners">FindChessboardCorners</a></td>
5417 <td width="25%"><a href="#decl_cvFindContours">FindContours</a></td>
5418 </tr>
5419 <tr>
5420 <td width="25%"><a href="#decl_cvFindCornerSubPix">FindCornerSubPix</a></td>
5421 <td width="25%"><a href="#decl_cvFindExtrinsicCameraParams2">FindExtrinsicCameraParams2</a></td>
5422 <td width="25%"><a href="#decl_cvFindFeatures">FindFeatures</a></td>
5423 </tr>
5424 <tr>
5425 <td width="25%"><a href="#decl_cvFindFeaturesBoxed">FindFeaturesBoxed</a></td>
5426 <td width="25%"><a href="#decl_cvFindFundamentalMat">FindFundamentalMat</a></td>
5427 <td width="25%"><a href="#decl_cvFindHomography">FindHomography</a></td>
5428 </tr>
5429 <tr>
5430 <td width="25%"><a href="#decl_cvFindNearestPoint2D">FindNearestPoint2D</a></td>
5431 <td width="25%"><a href="#decl_cvFindNextContour">FindNextContour</a></td>
5432 <td width="25%"><a href="#decl_cvFitEllipse">FitEllipse</a></td>
5433 </tr>
5434 <tr>
5435 <td width="25%"><a href="#decl_cvFitLine2D">FitLine2D</a></td>
5436 <td width="25%"><a href="#decl_cvFloodFill">FloodFill</a></td>
5437 </tr>
5438 </table>
5439 <hr><h3>G</h3>
5440 <table width="100%">
5441 <tr>
5442 <td width="25%"><a href="#decl_cvGetAffineTransform">GetAffineTransform</a></td>
5443 <td width="25%"><a href="#decl_cvGetMinMaxHistValue">GetMinMaxHistValue</a></td>
5444 <td width="25%"><a href="#decl_cvGetRectSubPix">GetRectSubPix</a></td>
5445 </tr>
5446 <tr>
5447 <td width="25%"><a href="#decl_cvGetCentralMoment">GetCentralMoment</a></td>
5448 <td width="25%"><a href="#decl_cvGetNormalizedCentralMoment">GetNormalizedCentralMoment</a></td>
5449 <td width="25%"><a href="#decl_cvGetSpatialMoment">GetSpatialMoment</a></td>
5450 </tr>
5451 <tr>
5452 <td width="25%"><a href="#decl_cvGetHistValue_*D">GetHistValue_*D</a></td>
5453 <td width="25%"><a href="#decl_cvGetPerspectiveTransform">GetPerspectiveTransform</a></td>
5454 <td width="25%"><a href="#decl_cvGoodFeaturesToTrack">GoodFeaturesToTrack</a></td>
5455 </tr>
5456 <tr>
5457 <td width="25%"><a href="#decl_cvGetHuMoments">GetHuMoments</a></td>
5458 <td width="25%"><a href="#decl_cvGetQuadrangleSubPix">GetQuadrangleSubPix</a></td>
5459 <td width="25%%"></td>
5460 </tr>
5461 </table>
5462 <hr><h3>H</h3>
5463 <table width="100%">
5464 <tr>
5465 <td width="25%"><a href="#decl_cvHaarDetectObjects">HaarDetectObjects</a></td>
5466 <td width="25%"><a href="#decl_cvHoughCircles">HoughCircles</a></td>
5467 <td width="25%"><a href="#decl_cvHoughLines2">HoughLines2</a></td>
5468 </tr>
5469 </table>
5470 <hr><h3>I</h3>
5471 <table width="100%">
5472 <tr>
5473 <td width="25%"><a href="#decl_cvInitUndistortMap">InitUndistortMap</a></td>
5474 <td width="25%"><a href="#decl_cvInpaint">Inpaint</a></td>
5475 <td width="25%"><a href="#decl_cvIntegral">Integral</a></td>
5476 </tr>
5477 </table>
5478 <hr><h3>K</h3>
5479 <table width="100%">
5480 <tr>
5481 <td width="25%"><a href="#decl_cvKalmanCorrect">KalmanCorrect</a></td>
5482 <td width="25%"><a href="#decl_cvKalmanPredict">KalmanPredict</a></td>
5483 <td width="25%%"></td>
5484 </tr>
5485 </table>
5486 <hr><h3>L</h3>
5487 <table width="100%">
5488 <tr>
5489 <td width="25%"><a href="#decl_cvLaplace">Laplace</a></td>
5490 <td width="25%"><a href="#decl_cvLoadHaarClassifierCascade">LoadHaarClassifierCascade</a></td>
5491 <td width="25%"><a href="#decl_cvLogPolar">LogPolar</a></td>
5492 </tr>
5493 </table>
5494 <hr><h3>M</h3>
5495 <table width="100%">
5496 <tr>
5497 <td width="25%"><a href="#decl_cvMakeHistHeaderForArray">MakeHistHeaderForArray</a></td>
5498 <td width="25%"><a href="#decl_cvMaxRect">MaxRect</a></td>
5499 <td width="25%"><a href="#decl_cvMoments">Moments</a></td>
5500 </tr>
5501 <tr>
5502 <td width="25%"><a href="#decl_cvMatchContourTrees">MatchContourTrees</a></td>
5503 <td width="25%"><a href="#decl_cvMeanShift">MeanShift</a></td>
5504 <td width="25%"><a href="#decl_cvMorphologyEx">MorphologyEx</a></td>
5505 </tr>
5506 <tr>
5507 <td width="25%"><a href="#decl_cvMatchShapes">MatchShapes</a></td>
5508 <td width="25%"><a href="#decl_cvMinAreaRect2">MinAreaRect2</a></td>
5509 <td width="25%"><a href="#decl_cvMultiplyAcc">MultiplyAcc</a></td>
5510 </tr>
5511 <tr>
5512 <td width="25%"><a href="#decl_cvMatchTemplate">MatchTemplate</a></td>
5513 <td width="25%"><a href="#decl_cvMinEnclosingCircle">MinEnclosingCircle</a></td>
5514 <td width="25%%"></td>
5515 </tr>
5516 </table>
5517 <hr><h3>N</h3>
5518 <table width="100%">
5519 <tr>
5520 <td width="25%"><a href="#decl_cvNormalizeHist">NormalizeHist</a></td>
5521 <td width="25%%"></td>
5522 <td width="25%%"></td>
5523 </tr>
5524 </table>
5525 <hr><h3>P</h3>
5526 <table width="100%">
5527 <tr>
5528 <td width="25%"><a href="#decl_cvPOSIT">POSIT</a></td>
5529 <td width="25%"><a href="#decl_cvPreCornerDetect">PreCornerDetect</a></td>
5530 <td width="25%"><a href="#decl_cvPyrMeanShiftFiltering">PyrMeanShiftFiltering</a></td>
5531 </tr>
5532 <tr>
5533 <td width="25%"><a href="#decl_cvPointPolygonTest">PointPolygonTest</a></td>
5534 <td width="25%"><a href="#decl_cvProjectPoints2">ProjectPoints2</a></td>
5535 <td width="25%"><a href="#decl_cvPyrSegmentation">PyrSegmentation</a></td>
5536 </tr>
5537 <tr>
5538 <td width="25%"><a href="#decl_cvPointSeqFromMat">PointSeqFromMat</a></td>
5539 <td width="25%"><a href="#decl_cvPyrDown">PyrDown</a></td>
5540 <td width="25%"><a href="#decl_cvPyrUp">PyrUp</a></td>
5541 </tr>
5542 </table>
5543 <hr><h3>Q</h3>
5544 <table width="100%">
5545 <tr>
5546 <td width="25%"><a href="#decl_cvQueryHistValue_*D">QueryHistValue_*D</a></td>
5547 <td width="25%%"></td>
5548 <td width="25%%"></td>
5549 </tr>
5550 </table>
5551 <hr><h3>R</h3>
5552 <table width="100%">
5553 <tr>
5554 <td width="25%"><a href="#decl_cvReadChainPoint">ReadChainPoint</a></td>
5555 <td width="25%"><a href="#decl_cvReleaseKalman">ReleaseKalman</a></td>
5556 <td width="25%"><a href="#decl_cvResize">Resize</a></td>
5557 </tr>
5558 <tr>
5559 <td width="25%"><a href="#decl_cvReleaseConDensation">ReleaseConDensation</a></td>
5560 <td width="25%"><a href="#decl_cvReleasePOSITObject">ReleasePOSITObject</a></td>
5561 <td width="25%"><a href="#decl_cvRodrigues2">Rodrigues2</a></td>
5562 </tr>
5563 <tr>
5564 <td width="25%"><a href="#decl_cvReleaseFeatureTree">ReleaseFeatureTree</a></td>
5565 <td width="25%"><a href="#decl_cvReleaseHaarClassifierCascade">ReleaseHaarClassifierCascade</a></td>
5566 <td width="25%"><a href="#decl_cvReleaseStructuringElement">ReleaseStructuringElement</a></td>
5567 </tr>
5568 <tr>
5569 <td width="25%"><a href="#decl_cvRunHaarClassifierCascade">RunHaarClassifierCascade</a></td>
5570 <td width="25%"><a href="#decl_cvReleaseHist">ReleaseHist</a></td>
5571 <td width="25%"><a href="#decl_cvRemap">Remap</a></td>
5572 </tr>
5573 <tr>
5574 <td width="25%"><a href="#decl_cvRunningAvg">RunningAvg</a></td>
5575 </tr>
5576 </table>
5577 <hr><h3>S</h3>
5578 <table width="100%">
5579 <tr>
5580 <td width="25%"><a href="#decl_cvSampleLine">SampleLine</a></td>
5581 <td width="25%"><a href="#decl_cvSobel">Sobel</a></td>
5582 <td width="25%"><a href="#decl_cvSubdiv2DGetEdge">Subdiv2DGetEdge</a></td>
5583 </tr>
5584 <tr>
5585 <td width="25%"><a href="#decl_cvSegmentMotion">SegmentMotion</a></td>
5586 <td width="25%"><a href="#decl_cvSquareAcc">SquareAcc</a></td>
5587 <td width="25%"><a href="#decl_cvSubdiv2DLocate">Subdiv2DLocate</a></td>
5588 </tr>
5589 <tr>
5590 <td width="25%"><a href="#decl_cvSetHistBinRanges">SetHistBinRanges</a></td>
5591 <td width="25%"><a href="#decl_cvStartFindContours">StartFindContours</a></td>
5592 <td width="25%"><a href="#decl_cvSubdiv2DRotateEdge">Subdiv2DRotateEdge</a></td>
5593 </tr>
5594 <tr>
5595 <td width="25%"><a href="#decl_cvSetImagesForHaarClassifierCascade">SetImagesForHaarClassifierCascade</a></td>
5596 <td width="25%"><a href="#decl_cvStartReadChainPoints">StartReadChainPoints</a></td>
5597 <td width="25%"><a href="#decl_cvSubdivDelaunay2DInsert">SubdivDelaunay2DInsert</a></td>
5598 </tr>
5599 <tr>
5600 <td width="25%"><a href="#decl_cvSmooth">Smooth</a></td>
5601 <td width="25%"><a href="#decl_cvSubdiv2DEdgeDst">Subdiv2DEdgeDst</a></td>
5602 <td width="25%"><a href="#decl_cvSubstituteContour">SubstituteContour</a></td>
5603 </tr>
5604 <tr>
5605 <td width="25%"><a href="#decl_cvSnakeImage">SnakeImage</a></td>
5606 <td width="25%"><a href="#decl_cvSubdiv2DEdgeOrg">Subdiv2DEdgeOrg</a></td>
5607 <td width="25%%"></td>
5608 </tr>
5609 </table>
5610 <hr><h3>T</h3>
5611 <table width="100%">
5612 <tr>
5613 <td width="25%"><a href="#decl_cvThreshHist">ThreshHist</a></td>
5614 <td width="25%"><a href="#decl_cvThreshold">Threshold</a></td>
5615 <td width="25%%"></td>
5616 </tr>
5617 </table>
5618 <hr><h3>U</h3>
5619 <table width="100%">
5620 <tr>
5621 <td width="25%"><a href="#decl_cvUndistort2">Undistort2</a></td>
5622 <td width="25%"><a href="#decl_cvUpdateMotionHistory">UpdateMotionHistory</a></td>
5623 <td width="25%%"></td>
5624 </tr>
5625 </table>
5626 <hr><h3>W</h3>
5627 <table width="100%">
5628 <tr>
5629 <td width="25%"><a href="#decl_cvWarpAffine">WarpAffine</a></td>
5630 <td width="25%"><a href="#decl_cvWarpPerspective">WarpPerspective</a></td>
5631 <td width="25%"><a href="#decl_cvWatershed">Watershed</a></td>
5632 </tr>
5633 </table>
5634
5635 <hr><h1><a name="cv_bib">Bibliography</a></h1>
5636 <p>
5637 This bibliography provides a list of publications that were might be useful to
5638 the OpenCV users. This list is not complete; it serves only
5639 as a starting point.
5640 </p>
5641 <ol>
5642
5643
5644 <li><a name="paper_beis97"><b>[Beis97]</b>
5645 J.S. Beis and D.G. Lowe, "Shape indexing using approximate nearest-neighbor search in highdimensional spaces".
5646 In Proc. IEEE Conf. Comp. Vision Patt. Recog., pages 1000--1006, 1997.
5647 </a>
5648
5649 <li><a name="paper_borgefors86"><b>[Borgefors86]</b>
5650 Gunilla Borgefors, "Distance Transformations in Digital Images". Computer Vision, Graphics and Image Processing 34, 344-371 (1986).
5651 </a>
5652
5653 <li><a name="paper_bouguet00"><b>[Bouguet00]</b>
5654 Jean-Yves Bouguet. Pyramidal Implementation of the Lucas Kanade Feature Tracker.</a><br>
5655 The paper is included into OpenCV distribution (<a href="../papers/algo_tracking.pdf">algo_tracking.pdf</a>)
5656
5657 <li><a name="paper_bradski98"><b>[Bradski98]</b>
5658 G.R. Bradski. Computer vision face tracking as a component of a perceptual
5659 user interface. In Workshop on Applications of Computer Vision, pages 214\96219,
5660 Princeton, NJ, Oct. 1998.</a><br>
5661 Updated version can be found at
5662 <a href="http://www.intel.com/technology/itj/q21998/articles/art_2.htm">
5663 http://www.intel.com/technology/itj/q21998/articles/art_2.htm</a>.<br>
5664 Also, it is included into OpenCV distribution (<a href="../papers/camshift.pdf">camshift.pdf</a>)
5665
5666 <li><b>[Bradski00]</b> G. Bradski and J. Davis. Motion Segmentation and Pose Recognition
5667 with Motion History Gradients. IEEE WACV'00, 2000.
5668
5669 <li><b>[Burt81]</b> P. J. Burt, T. H. Hong, A. Rosenfeld. Segmentation and Estimation of
5670 Image Region Properties Through Cooperative Hierarchical Computation. IEEE Tran.
5671 On SMC, Vol. 11, N.12, 1981, pp. 802-809.
5672
5673 <li><b>[Canny86]</b> J. Canny. A Computational Approach to Edge Detection, IEEE Trans. on
5674 Pattern Analysis and Machine Intelligence, 8(6), pp. 679-698 (1986).
5675
5676 <li><b>[Davis97]</b> J. Davis and Bobick. The Representation and Recognition of Action
5677 Using Temporal Templates. MIT Media Lab Technical Report 402, 1997.
5678
5679 <li><b>[DeMenthon92]</b> Daniel F. DeMenthon and Larry S. Davis. Model-Based Object Pose in
5680 25 Lines of Code. In Proceedings of ECCV '92, pp. 335-343, 1992.
5681
5682 <li><a name="paper_felzenszwalb04"><b>[Felzenszwalb04]</b>
5683 Pedro F. Felzenszwalb and Daniel P. Huttenlocher.
5684 Distance Transforms of Sampled Functions.
5685 Cornell Computing and Information Science TR2004-1963.</a>
5686
5687 <li><b>[Fitzgibbon95]</b> Andrew W. Fitzgibbon, R.B.Fisher. A Buyer&#146;s Guide to Conic
5688 Fitting. Proc.5th British Machine Vision Conference, Birmingham, pp. 513-522,
5689 1995.
5690
5691 <li><a name="paper_ford98"><b>[Ford98]</b> Adrian Ford, Alan Roberts. Colour Space Conversions.</a>
5692 <a href="http://www.poynton.com/PDFs/coloureq.pdf">http://www.poynton.com/PDFs/coloureq.pdf</a>
5693
5694 <li><a name="paper_horn81"><b>[Horn81]</b>
5695 Berthold K.P. Horn and Brian G. Schunck. Determining Optical Flow.
5696 Artificial Intelligence, 17, pp. 185-203, 1981.
5697 </a>
5698
5699 <li><b>[Hu62]</b> M. Hu. Visual Pattern Recognition by Moment Invariants, IRE Transactions
5700 on Information Theory, 8:2, pp. 179-187, 1962.
5701
5702 <li><a name="paper_iivarinen97"><b>[Iivarinen97]</b>
5703 Jukka Iivarinen, Markus Peura, Jaakko Srel, and Ari Visa.
5704 Comparison of Combined Shape Descriptors for Irregular Objects, 8th British Machine Vision Conference, BMVC'97.</a><br>
5705 <a href="http://www.cis.hut.fi/research/IA/paper/publications/bmvc97/bmvc97.html">
5706 http://www.cis.hut.fi/research/IA/paper/publications/bmvc97/bmvc97.html</a>
5707
5708 <li><b>[Jahne97]</b> B. Jahne. Digital Image Processing. Springer, New York, 1997.
5709
5710 <li><a name="paper_lucas81"></a><b>[Lucas81]</b>
5711 Lucas, B., and Kanade, T. An Iterative Image
5712 Registration Technique with an Application to Stereo
5713 Vision, Proc. of 7th International Joint Conference on
5714 Artificial Intelligence (IJCAI), pp. 674-679.
5715 </a>
5716
5717 <li><b>[Kass88]</b> M. Kass, A. Witkin, and D. Terzopoulos. Snakes: Active Contour Models,
5718 International Journal of Computer Vision, pp. 321-331, 1988.
5719
5720 <li><a name="paper_lienhart02"><b>[Lienhart02]</b>
5721 Rainer Lienhart and Jochen Maydt.
5722 An Extended Set of Haar-like Features for Rapid Object Detection.
5723 IEEE ICIP 2002, Vol. 1, pp. 900-903, Sep. 2002.</a><br>
5724 This paper, as well as the extended technical report, can be retrieved at
5725 <a href="http://www.lienhart.de/Publications/publications.html">http://www.lienhart.de/Publications/publications.html</a>
5726
5727
5728 <li><b>[Matas98]</b> J.Matas, C.Galambos, J.Kittler. Progressive Probabilistic Hough
5729 Transform. British Machine Vision Conference, 1998.
5730
5731 <li><a name="paper_meyer92"><b>[Meyer92]</b>
5732 Meyer, F. (1992). Color image segmentation. In Proceedings of the International Conference on Image Processing and its Applications, pages 303--306.</a>
5733
5734 <li><b>[Rosenfeld73]</b> A. Rosenfeld and E. Johnston. Angle Detection on Digital Curves.
5735 IEEE Trans. Computers, 22:875-878, 1973.
5736
5737 <li><b>[RubnerJan98]</b> Y. Rubner. C. Tomasi, L.J. Guibas. Metrics for Distributions with
5738 Applications to Image Databases. Proceedings of the 1998 IEEE International
5739 Conference on Computer Vision, Bombay, India, January 1998, pp. 59-66.
5740
5741 <li><a name="paper_rubnersept98"><b>[RubnerSept98]</b>
5742 Y. Rubner. C. Tomasi, L.J. Guibas. The Earth Mover&#146;s Distance as a
5743 Metric for Image Retrieval. Technical Report STAN-CS-TN-98-86,
5744 Department of Computer Science, Stanford University, September
5745 1998.
5746 </a>
5747
5748 <li><b>[RubnerOct98]</b> Y. Rubner. C. Tomasi. Texture Metrics. Proceeding of the IEEE
5749 International Conference on Systems, Man, and Cybernetics, San-Diego, CA,
5750 October 1998, pp. 4601-4607.
5751 <a href="http://robotics.stanford.edu/~rubner/publications.html">
5752 http://robotics.stanford.edu/~rubner/publications.html</a>
5753
5754 <li><b>[Serra82]</b> J. Serra. Image Analysis and Mathematical Morphology. Academic Press,
5755 1982.
5756
5757 <li><b>[Schiele00]</b> Bernt Schiele and James L. Crowley. Recognition without
5758 Correspondence Using Multidimensional Receptive Field Histograms. In
5759 International Journal of Computer Vision 36 (1), pp. 31-50, January 2000.
5760
5761 <li><b>[Suzuki85]</b> S. Suzuki, K. Abe. Topological Structural Analysis of Digital Binary
5762 Images by Border Following. CVGIP, v.30, n.1. 1985, pp. 32-46.
5763
5764 <li><b>[Teh89]</b> C.H. Teh, R.T. Chin. On the Detection of Dominant Points on Digital
5765 Curves. - IEEE Tr. PAMI, 1989, v.11, No.8, p. 859-872.
5766
5767 <li><a name="paper_telea04"><b>[Telea04]</b>
5768 A. Telea, "An image inpainting technique based on the fast marching method,"
5769 J. Graphics Tools, vol.9, no.1, pp.25\9636, 2004.<br>
5770
5771 <li><b>[Trucco98]</b> Emanuele Trucco, Alessandro Verri. Introductory Techniques for 3-D
5772 Computer Vision. Prentice Hall, Inc., 1998.
5773
5774 <li><a name="paper_viola01"><b>[Viola01]</b>
5775 Paul Viola and Michael J. Jones.
5776 Rapid Object Detection using a Boosted Cascade of Simple Features. IEEE CVPR, 2001.</a><br>
5777 The paper is available online at
5778 <a href="http://www.ai.mit.edu/people/viola/">http://www.ai.mit.edu/people/viola/</a>
5779
5780
5781 <li><a name="paper_welch95"><b>[Welch95]</b>
5782 Greg Welch, Gary Bishop. An Introduction To the Kalman Filter.
5783 Technical Report TR95-041, University of North Carolina at Chapel Hill, 1995.</a><br>
5784 Online version is available at <a href="http://www.cs.unc.edu/~welch/kalman/kalmanIntro.html">
5785 http://www.cs.unc.edu/~welch/kalman/kalmanIntro.html</a>
5786
5787 <li><b>[Williams92]</b> D. J. Williams and M. Shah. A Fast Algorithm for Active Contours
5788 and Curvature Estimation. CVGIP: Image Understanding, Vol. 55, No. 1, pp. 14-26,
5789 Jan., 1992. http://www.cs.ucf.edu/~vision/papers/shah/92/WIS92A.pdf.
5790
5791 <li><a name="paper_yuen03"><b>[Yuen03]</b>
5792 H.K. Yuen, J. Princen, J. Illingworth and J. Kittler.
5793 Comparative study of Hough Transform methods for circle finding.<br>
5794 <a href="http://www.sciencedirect.com/science/article/B6V09-48TCV4N-5Y/2/91f551d124777f7a4cf7b18325235673">
5795 http://www.sciencedirect.com/science/article/B6V09-48TCV4N-5Y/2/91f551d124777f7a4cf7b18325235673</a>
5796
5797 <li><b>[Yuille89]</b> A.Y.Yuille, D.S.Cohen, and P.W.Hallinan. Feature Extraction from
5798 Faces Using Deformable Templates in CVPR, pp. 104-109, 1989.
5799
5800 <li><b>[Zhang96]</b> Z. Zhang. Parameter Estimation Techniques: A Tutorial with Application
5801 to Conic Fitting, Image and Vision Computing Journal, 1996.
5802
5803 <li><b>[Zhang99]</b> Z. Zhang. Flexible Camera Calibration By Viewing a Plane From Unknown
5804 Orientations. International Conference on Computer Vision (ICCV'99), Corfu,
5805 Greece, pages 666-673, September 1999.
5806
5807 <li><b>[Zhang00]</b> Z. Zhang. A Flexible New Technique for Camera Calibration. IEEE
5808 Transactions on Pattern Analysis and Machine Intelligence, 22(11):1330-1334,
5809 2000.
5810 </ol>
5811
5812 </body>
5813 </html>
5814