opencv/include/opencv/cv.h

   1 /*M///////////////////////////////////////////////////////////////////////////////////////
   2 //
   3 //  IMPORTANT: READ BEFORE DOWNLOADING, COPYING, INSTALLING OR USING.
   4 //
   5 //  By downloading, copying, installing or using the software you agree to this license.
   6 //  If you do not agree to this license, do not download, install,
   7 //  copy or use the software.
   8 //
   9 //
  10 //                           License Agreement
  11 //                For Open Source Computer Vision Library
  12 //
  13 // Copyright (C) 2000-2008, Intel Corporation, all rights reserved.
  14 // Copyright (C) 2009, Willow Garage Inc., all rights reserved.
  15 // Third party copyrights are property of their respective owners.
  16 //
  17 // Redistribution and use in source and binary forms, with or without modification,
  18 // are permitted provided that the following conditions are met:
  19 //
  20 //   * Redistribution's of source code must retain the above copyright notice,
  21 //     this list of conditions and the following disclaimer.
  22 //
  23 //   * Redistribution's in binary form must reproduce the above copyright notice,
  24 //     this list of conditions and the following disclaimer in the documentation
  25 //     and/or other materials provided with the distribution.
  26 //
  27 //   * The name of the copyright holders may not be used to endorse or promote products
  28 //     derived from this software without specific prior written permission.
  29 //
  30 // This software is provided by the copyright holders and contributors "as is" and
  31 // any express or implied warranties, including, but not limited to, the implied
  32 // warranties of merchantability and fitness for a particular purpose are disclaimed.
  33 // In no event shall the Intel Corporation or contributors be liable for any direct,
  34 // indirect, incidental, special, exemplary, or consequential damages
  35 // (including, but not limited to, procurement of substitute goods or services;
  36 // loss of use, data, or profits; or business interruption) however caused
  37 // and on any theory of liability, whether in contract, strict liability,
  38 // or tort (including negligence or otherwise) arising in any way out of
  39 // the use of this software, even if advised of the possibility of such damage.
  40 //
  41 //M*/
  42
  43 #ifndef __OPENCV_CV_H__
  44 #define __OPENCV_CV_H__
  45
  46 #ifdef __IPL_H__
  47 #define HAVE_IPL
  48 #endif
  49
  50 #ifndef SKIP_INCLUDES
  51   #if defined(_CH_)
  52     #pragma package <chopencv>
  53     #include <chdl.h>
  54     LOAD_CHDL(cv)
  55   #endif
  56 #endif
  57
  58 #include "cxcore.h"
  59 #include "cvtypes.h"
  60
  61 #ifdef __cplusplus
  62 extern "C" {
  63 #endif
  64
  65 /****************************************************************************************\
  66 *                                    Image Processing                                    *
  67 \****************************************************************************************/
  68
  69 /* Copies source 2D array inside of the larger destination array and
  70    makes a border of the specified type (IPL_BORDER_*) around the copied area. */
  71 CVAPI(void) cvCopyMakeBorder( const CvArr* src, CvArr* dst, CvPoint offset,
  72                               int bordertype, CvScalar value CV_DEFAULT(cvScalarAll(0)));
  73
  74 #define CV_BLUR_NO_SCALE 0
  75 #define CV_BLUR  1
  76 #define CV_GAUSSIAN  2
  77 #define CV_MEDIAN 3
  78 #define CV_BILATERAL 4
  79
  80 /* Smoothes array (removes noise) */
  81 CVAPI(void) cvSmooth( const CvArr* src, CvArr* dst,
  82                       int smoothtype CV_DEFAULT(CV_GAUSSIAN),
  83                       int size1 CV_DEFAULT(3),
  84                       int size2 CV_DEFAULT(0),
  85                       double sigma1 CV_DEFAULT(0),
  86                       double sigma2 CV_DEFAULT(0));
  87
  88 /* Convolves the image with the kernel */
  89 CVAPI(void) cvFilter2D( const CvArr* src, CvArr* dst, const CvMat* kernel,
  90                         CvPoint anchor CV_DEFAULT(cvPoint(-1,-1)));
  91
  92 /* Finds integral image: SUM(X,Y) = sum(x<X,y<Y)I(x,y) */
  93 CVAPI(void) cvIntegral( const CvArr* image, CvArr* sum,
  94                        CvArr* sqsum CV_DEFAULT(NULL),
  95                        CvArr* tilted_sum CV_DEFAULT(NULL));
  96
  97 /*
  98    Smoothes the input image with gaussian kernel and then down-samples it.
  99    dst_width = floor(src_width/2)[+1],
 100    dst_height = floor(src_height/2)[+1]
 101 */
 102 CVAPI(void)  cvPyrDown( const CvArr* src, CvArr* dst,
 103                         int filter CV_DEFAULT(CV_GAUSSIAN_5x5) );
 104
 105 /*
 106    Up-samples image and smoothes the result with gaussian kernel.
 107    dst_width = src_width*2,
 108    dst_height = src_height*2
 109 */
 110 CVAPI(void)  cvPyrUp( const CvArr* src, CvArr* dst,
 111                       int filter CV_DEFAULT(CV_GAUSSIAN_5x5) );
 112
 113 /* Builds pyramid for an image */
 114 CVAPI(CvMat**) cvCreatePyramid( const CvArr* img, int extra_layers, double rate,
 115                                 const CvSize* layer_sizes CV_DEFAULT(0),
 116                                 CvArr* bufarr CV_DEFAULT(0),
 117                                 int calc CV_DEFAULT(1),
 118                                 int filter CV_DEFAULT(CV_GAUSSIAN_5x5) );
 119
 120 /* Releases pyramid */
 121 CVAPI(void)  cvReleasePyramid( CvMat*** pyramid, int extra_layers );
 122
 123
 124 /* Splits color or grayscale image into multiple connected components
 125    of nearly the same color/brightness using modification of Burt algorithm.
 126    comp with contain a pointer to sequence (CvSeq)
 127    of connected components (CvConnectedComp) */
 128 CVAPI(void) cvPyrSegmentation( IplImage* src, IplImage* dst,
 129                               CvMemStorage* storage, CvSeq** comp,
 130                               int level, double threshold1,
 131                               double threshold2 );
 132
 133 /* Filters image using meanshift algorithm */
 134 CVAPI(void) cvPyrMeanShiftFiltering( const CvArr* src, CvArr* dst,
 135     double sp, double sr, int max_level CV_DEFAULT(1),
 136     CvTermCriteria termcrit CV_DEFAULT(cvTermCriteria(CV_TERMCRIT_ITER+CV_TERMCRIT_EPS,5,1)));
 137
 138 /* Segments image using seed "markers" */
 139 CVAPI(void) cvWatershed( const CvArr* image, CvArr* markers );
 140
 141 #define CV_INPAINT_NS      0
 142 #define CV_INPAINT_TELEA   1
 143
 144 /* Inpaints the selected region in the image */
 145 CVAPI(void) cvInpaint( const CvArr* src, const CvArr* inpaint_mask,
 146                        CvArr* dst, double inpaintRange, int flags );
 147
 148 #define CV_SCHARR -1
 149 #define CV_MAX_SOBEL_KSIZE 7
 150
 151 /* Calculates an image derivative using generalized Sobel
 152    (aperture_size = 1,3,5,7) or Scharr (aperture_size = -1) operator.
 153    Scharr can be used only for the first dx or dy derivative */
 154 CVAPI(void) cvSobel( const CvArr* src, CvArr* dst,
 155                     int xorder, int yorder,
 156                     int aperture_size CV_DEFAULT(3));
 157
 158 /* Calculates the image Laplacian: (d2/dx + d2/dy)I */
 159 CVAPI(void) cvLaplace( const CvArr* src, CvArr* dst,
 160                       int aperture_size CV_DEFAULT(3) );
 161
 162 /* Constants for color conversion */
 163 #define  CV_BGR2BGRA    0
 164 #define  CV_RGB2RGBA    CV_BGR2BGRA
 165
 166 #define  CV_BGRA2BGR    1
 167 #define  CV_RGBA2RGB    CV_BGRA2BGR
 168
 169 #define  CV_BGR2RGBA    2
 170 #define  CV_RGB2BGRA    CV_BGR2RGBA
 171
 172 #define  CV_RGBA2BGR    3
 173 #define  CV_BGRA2RGB    CV_RGBA2BGR
 174
 175 #define  CV_BGR2RGB     4
 176 #define  CV_RGB2BGR     CV_BGR2RGB
 177
 178 #define  CV_BGRA2RGBA   5
 179 #define  CV_RGBA2BGRA   CV_BGRA2RGBA
 180
 181 #define  CV_BGR2GRAY    6
 182 #define  CV_RGB2GRAY    7
 183 #define  CV_GRAY2BGR    8
 184 #define  CV_GRAY2RGB    CV_GRAY2BGR
 185 #define  CV_GRAY2BGRA   9
 186 #define  CV_GRAY2RGBA   CV_GRAY2BGRA
 187 #define  CV_BGRA2GRAY   10
 188 #define  CV_RGBA2GRAY   11
 189
 190 #define  CV_BGR2BGR565  12
 191 #define  CV_RGB2BGR565  13
 192 #define  CV_BGR5652BGR  14
 193 #define  CV_BGR5652RGB  15
 194 #define  CV_BGRA2BGR565 16
 195 #define  CV_RGBA2BGR565 17
 196 #define  CV_BGR5652BGRA 18
 197 #define  CV_BGR5652RGBA 19
 198
 199 #define  CV_GRAY2BGR565 20
 200 #define  CV_BGR5652GRAY 21
 201
 202 #define  CV_BGR2BGR555  22
 203 #define  CV_RGB2BGR555  23
 204 #define  CV_BGR5552BGR  24
 205 #define  CV_BGR5552RGB  25
 206 #define  CV_BGRA2BGR555 26
 207 #define  CV_RGBA2BGR555 27
 208 #define  CV_BGR5552BGRA 28
 209 #define  CV_BGR5552RGBA 29
 210
 211 #define  CV_GRAY2BGR555 30
 212 #define  CV_BGR5552GRAY 31
 213
 214 #define  CV_BGR2XYZ     32
 215 #define  CV_RGB2XYZ     33
 216 #define  CV_XYZ2BGR     34
 217 #define  CV_XYZ2RGB     35
 218
 219 #define  CV_BGR2YCrCb   36
 220 #define  CV_RGB2YCrCb   37
 221 #define  CV_YCrCb2BGR   38
 222 #define  CV_YCrCb2RGB   39
 223
 224 #define  CV_BGR2HSV     40
 225 #define  CV_RGB2HSV     41
 226
 227 #define  CV_BGR2Lab     44
 228 #define  CV_RGB2Lab     45
 229
 230 #define  CV_BayerBG2BGR 46
 231 #define  CV_BayerGB2BGR 47
 232 #define  CV_BayerRG2BGR 48
 233 #define  CV_BayerGR2BGR 49
 234
 235 #define  CV_BayerBG2RGB CV_BayerRG2BGR
 236 #define  CV_BayerGB2RGB CV_BayerGR2BGR
 237 #define  CV_BayerRG2RGB CV_BayerBG2BGR
 238 #define  CV_BayerGR2RGB CV_BayerGB2BGR
 239
 240 #define  CV_BGR2Luv     50
 241 #define  CV_RGB2Luv     51
 242 #define  CV_BGR2HLS     52
 243 #define  CV_RGB2HLS     53
 244
 245 #define  CV_HSV2BGR     54
 246 #define  CV_HSV2RGB     55
 247
 248 #define  CV_Lab2BGR     56
 249 #define  CV_Lab2RGB     57
 250 #define  CV_Luv2BGR     58
 251 #define  CV_Luv2RGB     59
 252 #define  CV_HLS2BGR     60
 253 #define  CV_HLS2RGB     61
 254
 255 #define  CV_COLORCVT_MAX  100
 256
 257 /* Converts input array pixels from one color space to another */
 258 CVAPI(void)  cvCvtColor( const CvArr* src, CvArr* dst, int code );
 259
 260 #define  CV_INTER_NN        0
 261 #define  CV_INTER_LINEAR    1
 262 #define  CV_INTER_CUBIC     2
 263 #define  CV_INTER_AREA      3
 264
 265 #define  CV_WARP_FILL_OUTLIERS 8
 266 #define  CV_WARP_INVERSE_MAP  16
 267
 268 /* Resizes image (input array is resized to fit the destination array) */
 269 CVAPI(void)  cvResize( const CvArr* src, CvArr* dst,
 270                        int interpolation CV_DEFAULT( CV_INTER_LINEAR ));
 271
 272 /* Warps image with affine transform */
 273 CVAPI(void)  cvWarpAffine( const CvArr* src, CvArr* dst, const CvMat* map_matrix,
 274                            int flags CV_DEFAULT(CV_INTER_LINEAR+CV_WARP_FILL_OUTLIERS),
 275                            CvScalar fillval CV_DEFAULT(cvScalarAll(0)) );
 276
 277 /* Computes affine transform matrix for mapping src[i] to dst[i] (i=0,1,2) */
 278 CVAPI(CvMat*) cvGetAffineTransform( const CvPoint2D32f * src,
 279                                     const CvPoint2D32f * dst,
 280                                     CvMat * map_matrix );
 281
 282 /* Computes rotation_matrix matrix */
 283 CVAPI(CvMat*)  cv2DRotationMatrix( CvPoint2D32f center, double angle,
 284                                    double scale, CvMat* map_matrix );
 285
 286 /* Warps image with perspective (projective) transform */
 287 CVAPI(void)  cvWarpPerspective( const CvArr* src, CvArr* dst, const CvMat* map_matrix,
 288                                 int flags CV_DEFAULT(CV_INTER_LINEAR+CV_WARP_FILL_OUTLIERS),
 289                                 CvScalar fillval CV_DEFAULT(cvScalarAll(0)) );
 290
 291 /* Computes perspective transform matrix for mapping src[i] to dst[i] (i=0,1,2,3) */
 292 CVAPI(CvMat*) cvGetPerspectiveTransform( const CvPoint2D32f* src,
 293                                          const CvPoint2D32f* dst,
 294                                          CvMat* map_matrix );
 295
 296 /* Performs generic geometric transformation using the specified coordinate maps */
 297 CVAPI(void)  cvRemap( const CvArr* src, CvArr* dst,
 298                       const CvArr* mapx, const CvArr* mapy,
 299                       int flags CV_DEFAULT(CV_INTER_LINEAR+CV_WARP_FILL_OUTLIERS),
 300                       CvScalar fillval CV_DEFAULT(cvScalarAll(0)) );
 301
 302 /* Converts mapx & mapy from floating-point to integer formats for cvRemap */
 303 CVAPI(void)  cvConvertMaps( const CvArr* mapx, const CvArr* mapy,
 304                             CvArr* mapxy, CvArr* mapalpha );
 305
 306 /* Performs forward or inverse log-polar image transform */
 307 CVAPI(void)  cvLogPolar( const CvArr* src, CvArr* dst,
 308                          CvPoint2D32f center, double M,
 309                          int flags CV_DEFAULT(CV_INTER_LINEAR+CV_WARP_FILL_OUTLIERS));
 310
 311 /* Performs forward or inverse linear-polar image transform */
 312 CVAPI(void)  cvLinearPolar( const CvArr* src, CvArr* dst,
 313                          CvPoint2D32f center, double maxRadius,
 314                          int flags CV_DEFAULT(CV_INTER_LINEAR+CV_WARP_FILL_OUTLIERS));
 315
 316 #define  CV_SHAPE_RECT      0
 317 #define  CV_SHAPE_CROSS     1
 318 #define  CV_SHAPE_ELLIPSE   2
 319 #define  CV_SHAPE_CUSTOM    100
 320
 321 /* creates structuring element used for morphological operations */
 322 CVAPI(IplConvKernel*)  cvCreateStructuringElementEx(
 323             int cols, int  rows, int  anchor_x, int  anchor_y,
 324             int shape, int* values CV_DEFAULT(NULL) );
 325
 326 /* releases structuring element */
 327 CVAPI(void)  cvReleaseStructuringElement( IplConvKernel** element );
 328
 329 /* erodes input image (applies minimum filter) one or more times.
 330    If element pointer is NULL, 3x3 rectangular element is used */
 331 CVAPI(void)  cvErode( const CvArr* src, CvArr* dst,
 332                       IplConvKernel* element CV_DEFAULT(NULL),
 333                       int iterations CV_DEFAULT(1) );
 334
 335 /* dilates input image (applies maximum filter) one or more times.
 336    If element pointer is NULL, 3x3 rectangular element is used */
 337 CVAPI(void)  cvDilate( const CvArr* src, CvArr* dst,
 338                        IplConvKernel* element CV_DEFAULT(NULL),
 339                        int iterations CV_DEFAULT(1) );
 340
 341 #define CV_MOP_ERODE        0
 342 #define CV_MOP_DILATE       1
 343 #define CV_MOP_OPEN         2
 344 #define CV_MOP_CLOSE        3
 345 #define CV_MOP_GRADIENT     4
 346 #define CV_MOP_TOPHAT       5
 347 #define CV_MOP_BLACKHAT     6
 348
 349 /* Performs complex morphological transformation */
 350 CVAPI(void)  cvMorphologyEx( const CvArr* src, CvArr* dst,
 351                              CvArr* temp, IplConvKernel* element,
 352                              int operation, int iterations CV_DEFAULT(1) );
 353
 354 /* Calculates all spatial and central moments up to the 3rd order */
 355 CVAPI(void) cvMoments( const CvArr* arr, CvMoments* moments, int binary CV_DEFAULT(0));
 356
 357 /* Retrieve particular spatial, central or normalized central moments */
 358 CVAPI(double)  cvGetSpatialMoment( CvMoments* moments, int x_order, int y_order );
 359 CVAPI(double)  cvGetCentralMoment( CvMoments* moments, int x_order, int y_order );
 360 CVAPI(double)  cvGetNormalizedCentralMoment( CvMoments* moments,
 361                                              int x_order, int y_order );
 362
 363 /* Calculates 7 Hu's invariants from precalculated spatial and central moments */
 364 CVAPI(void) cvGetHuMoments( CvMoments*  moments, CvHuMoments*  hu_moments );
 365
 366 /*********************************** data sampling **************************************/
 367
 368 /* Fetches pixels that belong to the specified line segment and stores them to the buffer.
 369    Returns the number of retrieved points. */
 370 CVAPI(int)  cvSampleLine( const CvArr* image, CvPoint pt1, CvPoint pt2, void* buffer,
 371                           int connectivity CV_DEFAULT(8));
 372
 373 /* Retrieves the rectangular image region with specified center from the input array.
 374  dst(x,y) <- src(x + center.x - dst_width/2, y + center.y - dst_height/2).
 375  Values of pixels with fractional coordinates are retrieved using bilinear interpolation*/
 376 CVAPI(void)  cvGetRectSubPix( const CvArr* src, CvArr* dst, CvPoint2D32f center );
 377
 378
 379 /* Retrieves quadrangle from the input array.
 380     matrixarr = ( a11  a12 | b1 )   dst(x,y) <- src(A[x y]' + b)
 381                 ( a21  a22 | b2 )   (bilinear interpolation is used to retrieve pixels
 382                                      with fractional coordinates)
 383 */
 384 CVAPI(void)  cvGetQuadrangleSubPix( const CvArr* src, CvArr* dst,
 385                                     const CvMat* map_matrix );
 386
 387 /* Methods for comparing two array */
 388 #define  CV_TM_SQDIFF        0
 389 #define  CV_TM_SQDIFF_NORMED 1
 390 #define  CV_TM_CCORR         2
 391 #define  CV_TM_CCORR_NORMED  3
 392 #define  CV_TM_CCOEFF        4
 393 #define  CV_TM_CCOEFF_NORMED 5
 394
 395 /* Measures similarity between template and overlapped windows in the source image
 396    and fills the resultant image with the measurements */
 397 CVAPI(void)  cvMatchTemplate( const CvArr* image, const CvArr* templ,
 398                               CvArr* result, int method );
 399
 400 /* Computes earth mover distance between
 401    two weighted point sets (called signatures) */
 402 CVAPI(float)  cvCalcEMD2( const CvArr* signature1,
 403                           const CvArr* signature2,
 404                           int distance_type,
 405                           CvDistanceFunction distance_func CV_DEFAULT(NULL),
 406                           const CvArr* cost_matrix CV_DEFAULT(NULL),
 407                           CvArr* flow CV_DEFAULT(NULL),
 408                           float* lower_bound CV_DEFAULT(NULL),
 409                           void* userdata CV_DEFAULT(NULL));
 410
 411 /****************************************************************************************\
 412 *                              Contours retrieving                                       *
 413 \****************************************************************************************/
 414
 415 /* Retrieves outer and optionally inner boundaries of white (non-zero) connected
 416    components in the black (zero) background */
 417 CVAPI(int)  cvFindContours( CvArr* image, CvMemStorage* storage, CvSeq** first_contour,
 418                             int header_size CV_DEFAULT(sizeof(CvContour)),
 419                             int mode CV_DEFAULT(CV_RETR_LIST),
 420                             int method CV_DEFAULT(CV_CHAIN_APPROX_SIMPLE),
 421                             CvPoint offset CV_DEFAULT(cvPoint(0,0)));
 422
 423
 424 /* Initalizes contour retrieving process.
 425    Calls cvStartFindContours.
 426    Calls cvFindNextContour until null pointer is returned
 427    or some other condition becomes true.
 428    Calls cvEndFindContours at the end. */
 429 CVAPI(CvContourScanner)  cvStartFindContours( CvArr* image, CvMemStorage* storage,
 430                             int header_size CV_DEFAULT(sizeof(CvContour)),
 431                             int mode CV_DEFAULT(CV_RETR_LIST),
 432                             int method CV_DEFAULT(CV_CHAIN_APPROX_SIMPLE),
 433                             CvPoint offset CV_DEFAULT(cvPoint(0,0)));
 434
 435 /* Retrieves next contour */
 436 CVAPI(CvSeq*)  cvFindNextContour( CvContourScanner scanner );
 437
 438
 439 /* Substitutes the last retrieved contour with the new one
 440    (if the substitutor is null, the last retrieved contour is removed from the tree) */
 441 CVAPI(void)   cvSubstituteContour( CvContourScanner scanner, CvSeq* new_contour );
 442
 443
 444 /* Releases contour scanner and returns pointer to the first outer contour */
 445 CVAPI(CvSeq*)  cvEndFindContours( CvContourScanner* scanner );
 446
 447 /* Approximates a single Freeman chain or a tree of chains to polygonal curves */
 448 CVAPI(CvSeq*) cvApproxChains( CvSeq* src_seq, CvMemStorage* storage,
 449                             int method CV_DEFAULT(CV_CHAIN_APPROX_SIMPLE),
 450                             double parameter CV_DEFAULT(0),
 451                             int  minimal_perimeter CV_DEFAULT(0),
 452                             int  recursive CV_DEFAULT(0));
 453
 454
 455 /* Initalizes Freeman chain reader.
 456    The reader is used to iteratively get coordinates of all the chain points.
 457    If the Freeman codes should be read as is, a simple sequence reader should be used */
 458 CVAPI(void) cvStartReadChainPoints( CvChain* chain, CvChainPtReader* reader );
 459
 460 /* Retrieves the next chain point */
 461 CVAPI(CvPoint) cvReadChainPoint( CvChainPtReader* reader );
 462
 463
 464 /****************************************************************************************\
 465 *                                  Motion Analysis                                       *
 466 \****************************************************************************************/
 467
 468 /************************************ optical flow ***************************************/
 469
 470 /* Calculates optical flow for 2 images using classical Lucas & Kanade algorithm */
 471 CVAPI(void)  cvCalcOpticalFlowLK( const CvArr* prev, const CvArr* curr,
 472                                   CvSize win_size, CvArr* velx, CvArr* vely );
 473
 474 /* Calculates optical flow for 2 images using block matching algorithm */
 475 CVAPI(void)  cvCalcOpticalFlowBM( const CvArr* prev, const CvArr* curr,
 476                                   CvSize block_size, CvSize shift_size,
 477                                   CvSize max_range, int use_previous,
 478                                   CvArr* velx, CvArr* vely );
 479
 480 /* Calculates Optical flow for 2 images using Horn & Schunck algorithm */
 481 CVAPI(void)  cvCalcOpticalFlowHS( const CvArr* prev, const CvArr* curr,
 482                                   int use_previous, CvArr* velx, CvArr* vely,
 483                                   double lambda, CvTermCriteria criteria );
 484
 485 #define  CV_LKFLOW_PYR_A_READY       1
 486 #define  CV_LKFLOW_PYR_B_READY       2
 487 #define  CV_LKFLOW_INITIAL_GUESSES   4
 488 #define  CV_LKFLOW_GET_MIN_EIGENVALS 8
 489
 490 /* It is Lucas & Kanade method, modified to use pyramids.
 491    Also it does several iterations to get optical flow for
 492    every point at every pyramid level.
 493    Calculates optical flow between two images for certain set of points (i.e.
 494    it is a "sparse" optical flow, which is opposite to the previous 3 methods) */
 495 CVAPI(void)  cvCalcOpticalFlowPyrLK( const CvArr*  prev, const CvArr*  curr,
 496                                      CvArr*  prev_pyr, CvArr*  curr_pyr,
 497                                      const CvPoint2D32f* prev_features,
 498                                      CvPoint2D32f* curr_features,
 499                                      int       count,
 500                                      CvSize    win_size,
 501                                      int       level,
 502                                      char*     status,
 503                                      float*    track_error,
 504                                      CvTermCriteria criteria,
 505                                      int       flags );
 506
 507
 508 /* Modification of a previous sparse optical flow algorithm to calculate
 509    affine flow */
 510 CVAPI(void)  cvCalcAffineFlowPyrLK( const CvArr*  prev, const CvArr*  curr,
 511                                     CvArr*  prev_pyr, CvArr*  curr_pyr,
 512                                     const CvPoint2D32f* prev_features,
 513                                     CvPoint2D32f* curr_features,
 514                                     float* matrices, int  count,
 515                                     CvSize win_size, int  level,
 516                                     char* status, float* track_error,
 517                                     CvTermCriteria criteria, int flags );
 518
 519 /* Estimate rigid transformation between 2 images or 2 point sets */
 520 CVAPI(int)  cvEstimateRigidTransform( const CvArr* A, const CvArr* B,
 521                                       CvMat* M, int full_affine );
 522
 523 /* Estimate optical flow for each pixel using the two-frame G. Farneback algorithm */
 524 CVAPI(void) cvCalcOpticalFlowFarneback( const CvArr* prev, const CvArr* next,
 525                                         CvArr* flow, double pyr_scale, int levels,
 526                                         int winsize, int iterations, int poly_n,
 527                                         double poly_sigma, int flags );
 528
 529 /********************************* motion templates *************************************/
 530
 531 /****************************************************************************************\
 532 *        All the motion template functions work only with single channel images.         *
 533 *        Silhouette image must have depth IPL_DEPTH_8U or IPL_DEPTH_8S                   *
 534 *        Motion history image must have depth IPL_DEPTH_32F,                             *
 535 *        Gradient mask - IPL_DEPTH_8U or IPL_DEPTH_8S,                                   *
 536 *        Motion orientation image - IPL_DEPTH_32F                                        *
 537 *        Segmentation mask - IPL_DEPTH_32F                                               *
 538 *        All the angles are in degrees, all the times are in milliseconds                *
 539 \****************************************************************************************/
 540
 541 /* Updates motion history image given motion silhouette */
 542 CVAPI(void)    cvUpdateMotionHistory( const CvArr* silhouette, CvArr* mhi,
 543                                       double timestamp, double duration );
 544
 545 /* Calculates gradient of the motion history image and fills
 546    a mask indicating where the gradient is valid */
 547 CVAPI(void)    cvCalcMotionGradient( const CvArr* mhi, CvArr* mask, CvArr* orientation,
 548                                      double delta1, double delta2,
 549                                      int aperture_size CV_DEFAULT(3));
 550
 551 /* Calculates average motion direction within a selected motion region
 552    (region can be selected by setting ROIs and/or by composing a valid gradient mask
 553    with the region mask) */
 554 CVAPI(double)  cvCalcGlobalOrientation( const CvArr* orientation, const CvArr* mask,
 555                                         const CvArr* mhi, double timestamp,
 556                                         double duration );
 557
 558 /* Splits a motion history image into a few parts corresponding to separate independent motions
 559    (e.g. left hand, right hand) */
 560 CVAPI(CvSeq*)  cvSegmentMotion( const CvArr* mhi, CvArr* seg_mask,
 561                                 CvMemStorage* storage,
 562                                 double timestamp, double seg_thresh );
 563
 564 /*********************** Background statistics accumulation *****************************/
 565
 566 /* Adds image to accumulator */
 567 CVAPI(void)  cvAcc( const CvArr* image, CvArr* sum,
 568                     const CvArr* mask CV_DEFAULT(NULL) );
 569
 570 /* Adds squared image to accumulator */
 571 CVAPI(void)  cvSquareAcc( const CvArr* image, CvArr* sqsum,
 572                           const CvArr* mask CV_DEFAULT(NULL) );
 573
 574 /* Adds a product of two images to accumulator */
 575 CVAPI(void)  cvMultiplyAcc( const CvArr* image1, const CvArr* image2, CvArr* acc,
 576                             const CvArr* mask CV_DEFAULT(NULL) );
 577
 578 /* Adds image to accumulator with weights: acc = acc*(1-alpha) + image*alpha */
 579 CVAPI(void)  cvRunningAvg( const CvArr* image, CvArr* acc, double alpha,
 580                            const CvArr* mask CV_DEFAULT(NULL) );
 581
 582
 583 /****************************************************************************************\
 584 *                                       Tracking                                         *
 585 \****************************************************************************************/
 586
 587 /* Implements CAMSHIFT algorithm - determines object position, size and orientation
 588    from the object histogram back project (extension of meanshift) */
 589 CVAPI(int)  cvCamShift( const CvArr* prob_image, CvRect  window,
 590                        CvTermCriteria criteria, CvConnectedComp* comp,
 591                        CvBox2D* box CV_DEFAULT(NULL) );
 592
 593 /* Implements MeanShift algorithm - determines object position
 594    from the object histogram back project */
 595 CVAPI(int)  cvMeanShift( const CvArr* prob_image, CvRect  window,
 596                         CvTermCriteria criteria, CvConnectedComp* comp );
 597
 598 /* Creates Kalman filter and sets A, B, Q, R and state to some initial values */
 599 CVAPI(CvKalman*) cvCreateKalman( int dynam_params, int measure_params,
 600                                 int control_params CV_DEFAULT(0));
 601
 602 /* Releases Kalman filter state */
 603 CVAPI(void)  cvReleaseKalman( CvKalman** kalman);
 604
 605 /* Updates Kalman filter by time (predicts future state of the system) */
 606 CVAPI(const CvMat*)  cvKalmanPredict( CvKalman* kalman,
 607                                      const CvMat* control CV_DEFAULT(NULL));
 608
 609 /* Updates Kalman filter by measurement
 610    (corrects state of the system and internal matrices) */
 611 CVAPI(const CvMat*)  cvKalmanCorrect( CvKalman* kalman, const CvMat* measurement );
 612
 613 /****************************************************************************************\
 614 *                              Planar subdivisions                                       *
 615 \****************************************************************************************/
 616
 617 /* Initializes Delaunay triangulation */
 618 CVAPI(void)  cvInitSubdivDelaunay2D( CvSubdiv2D* subdiv, CvRect rect );
 619
 620 /* Creates new subdivision */
 621 CVAPI(CvSubdiv2D*)  cvCreateSubdiv2D( int subdiv_type, int header_size,
 622                                       int vtx_size, int quadedge_size,
 623                                       CvMemStorage* storage );
 624
 625 /************************* high-level subdivision functions ***************************/
 626
 627 /* Simplified Delaunay diagram creation */
 628 CV_INLINE  CvSubdiv2D* cvCreateSubdivDelaunay2D( CvRect rect, CvMemStorage* storage )
 629 {
 630     CvSubdiv2D* subdiv = cvCreateSubdiv2D( CV_SEQ_KIND_SUBDIV2D, sizeof(*subdiv),
 631                          sizeof(CvSubdiv2DPoint), sizeof(CvQuadEdge2D), storage );
 632
 633     cvInitSubdivDelaunay2D( subdiv, rect );
 634     return subdiv;
 635 }
 636
 637
 638 /* Inserts new point to the Delaunay triangulation */
 639 CVAPI(CvSubdiv2DPoint*)  cvSubdivDelaunay2DInsert( CvSubdiv2D* subdiv, CvPoint2D32f pt);
 640
 641 /* Locates a point within the Delaunay triangulation (finds the edge
 642    the point is left to or belongs to, or the triangulation point the given
 643    point coinsides with */
 644 CVAPI(CvSubdiv2DPointLocation)  cvSubdiv2DLocate(
 645                                CvSubdiv2D* subdiv, CvPoint2D32f pt,
 646                                CvSubdiv2DEdge* edge,
 647                                CvSubdiv2DPoint** vertex CV_DEFAULT(NULL) );
 648
 649 /* Calculates Voronoi tesselation (i.e. coordinates of Voronoi points) */
 650 CVAPI(void)  cvCalcSubdivVoronoi2D( CvSubdiv2D* subdiv );
 651
 652
 653 /* Removes all Voronoi points from the tesselation */
 654 CVAPI(void)  cvClearSubdivVoronoi2D( CvSubdiv2D* subdiv );
 655
 656
 657 /* Finds the nearest to the given point vertex in subdivision. */
 658 CVAPI(CvSubdiv2DPoint*) cvFindNearestPoint2D( CvSubdiv2D* subdiv, CvPoint2D32f pt );
 659
 660
 661 /************ Basic quad-edge navigation and operations ************/
 662
 663 CV_INLINE  CvSubdiv2DEdge  cvSubdiv2DNextEdge( CvSubdiv2DEdge edge )
 664 {
 665     return  CV_SUBDIV2D_NEXT_EDGE(edge);
 666 }
 667
 668
 669 CV_INLINE  CvSubdiv2DEdge  cvSubdiv2DRotateEdge( CvSubdiv2DEdge edge, int rotate )
 670 {
 671     return  (edge & ~3) + ((edge + rotate) & 3);
 672 }
 673
 674 CV_INLINE  CvSubdiv2DEdge  cvSubdiv2DSymEdge( CvSubdiv2DEdge edge )
 675 {
 676     return edge ^ 2;
 677 }
 678
 679 CV_INLINE  CvSubdiv2DEdge  cvSubdiv2DGetEdge( CvSubdiv2DEdge edge, CvNextEdgeType type )
 680 {
 681     CvQuadEdge2D* e = (CvQuadEdge2D*)(edge & ~3);
 682     edge = e->next[(edge + (int)type) & 3];
 683     return  (edge & ~3) + ((edge + ((int)type >> 4)) & 3);
 684 }
 685
 686
 687 CV_INLINE  CvSubdiv2DPoint*  cvSubdiv2DEdgeOrg( CvSubdiv2DEdge edge )
 688 {
 689     CvQuadEdge2D* e = (CvQuadEdge2D*)(edge & ~3);
 690     return (CvSubdiv2DPoint*)e->pt[edge & 3];
 691 }
 692
 693
 694 CV_INLINE  CvSubdiv2DPoint*  cvSubdiv2DEdgeDst( CvSubdiv2DEdge edge )
 695 {
 696     CvQuadEdge2D* e = (CvQuadEdge2D*)(edge & ~3);
 697     return (CvSubdiv2DPoint*)e->pt[(edge + 2) & 3];
 698 }
 699
 700
 701 CV_INLINE  double  cvTriangleArea( CvPoint2D32f a, CvPoint2D32f b, CvPoint2D32f c )
 702 {
 703     return (b.x - a.x) * (c.y - a.y) - (b.y - a.y) * (c.x - a.x);
 704 }
 705
 706
 707 /****************************************************************************************\
 708 *                            Contour Processing and Shape Analysis                       *
 709 \****************************************************************************************/
 710
 711 #define CV_POLY_APPROX_DP 0
 712
 713 /* Approximates a single polygonal curve (contour) or
 714    a tree of polygonal curves (contours) */
 715 CVAPI(CvSeq*)  cvApproxPoly( const void* src_seq,
 716                              int header_size, CvMemStorage* storage,
 717                              int method, double parameter,
 718                              int parameter2 CV_DEFAULT(0));
 719
 720 /* Calculates perimeter of a contour or length of a part of contour */
 721 CVAPI(double)  cvArcLength( const void* curve,
 722                             CvSlice slice CV_DEFAULT(CV_WHOLE_SEQ),
 723                             int is_closed CV_DEFAULT(-1));
 724 #define cvContourPerimeter( contour ) cvArcLength( contour, CV_WHOLE_SEQ, 1 )
 725
 726 /* Calculates contour boundning rectangle (update=1) or
 727    just retrieves pre-calculated rectangle (update=0) */
 728 CVAPI(CvRect)  cvBoundingRect( CvArr* points, int update CV_DEFAULT(0) );
 729
 730 /* Calculates area of a contour or contour segment */
 731 CVAPI(double)  cvContourArea( const CvArr* contour,
 732                               CvSlice slice CV_DEFAULT(CV_WHOLE_SEQ),
 733                               int oriented CV_DEFAULT(0));
 734
 735 /* Finds minimum area rotated rectangle bounding a set of points */
 736 CVAPI(CvBox2D)  cvMinAreaRect2( const CvArr* points,
 737                                 CvMemStorage* storage CV_DEFAULT(NULL));
 738
 739 /* Finds minimum enclosing circle for a set of points */
 740 CVAPI(int)  cvMinEnclosingCircle( const CvArr* points,
 741                                   CvPoint2D32f* center, float* radius );
 742
 743 #define CV_CONTOURS_MATCH_I1  1
 744 #define CV_CONTOURS_MATCH_I2  2
 745 #define CV_CONTOURS_MATCH_I3  3
 746
 747 /* Compares two contours by matching their moments */
 748 CVAPI(double)  cvMatchShapes( const void* object1, const void* object2,
 749                               int method, double parameter CV_DEFAULT(0));
 750
 751 /* Builds hierarhical representation of a contour */
 752 CVAPI(CvContourTree*)  cvCreateContourTree( const CvSeq* contour,
 753                                             CvMemStorage* storage,
 754                                             double threshold );
 755
 756 /* Reconstruct (completelly or partially) contour a from contour tree */
 757 CVAPI(CvSeq*)  cvContourFromContourTree( const CvContourTree* tree,
 758                                          CvMemStorage* storage,
 759                                          CvTermCriteria criteria );
 760
 761 /* Compares two contour trees */
 762 #define  CV_CONTOUR_TREES_MATCH_I1  1
 763
 764 CVAPI(double)  cvMatchContourTrees( const CvContourTree* tree1,
 765                                     const CvContourTree* tree2,
 766                                     int method, double threshold );
 767
 768 #define CV_CLOCKWISE         1
 769 #define CV_COUNTER_CLOCKWISE 2
 770
 771 /* Calculates exact convex hull of 2d point set */
 772 CVAPI(CvSeq*) cvConvexHull2( const CvArr* input,
 773                              void* hull_storage CV_DEFAULT(NULL),
 774                              int orientation CV_DEFAULT(CV_CLOCKWISE),
 775                              int return_points CV_DEFAULT(0));
 776
 777 /* Checks whether the contour is convex or not (returns 1 if convex, 0 if not) */
 778 CVAPI(int)  cvCheckContourConvexity( const CvArr* contour );
 779
 780 /* Finds convexity defects for the contour */
 781 CVAPI(CvSeq*)  cvConvexityDefects( const CvArr* contour, const CvArr* convexhull,
 782                                    CvMemStorage* storage CV_DEFAULT(NULL));
 783
 784 /* Fits ellipse into a set of 2d points */
 785 CVAPI(CvBox2D) cvFitEllipse2( const CvArr* points );
 786
 787 /* Finds minimum rectangle containing two given rectangles */
 788 CVAPI(CvRect)  cvMaxRect( const CvRect* rect1, const CvRect* rect2 );
 789
 790 /* Finds coordinates of the box vertices */
 791 CVAPI(void) cvBoxPoints( CvBox2D box, CvPoint2D32f pt[4] );
 792
 793 /* Initializes sequence header for a matrix (column or row vector) of points -
 794    a wrapper for cvMakeSeqHeaderForArray (it does not initialize bounding rectangle!!!) */
 795 CVAPI(CvSeq*) cvPointSeqFromMat( int seq_kind, const CvArr* mat,
 796                                  CvContour* contour_header,
 797                                  CvSeqBlock* block );
 798
 799 /* Checks whether the point is inside polygon, outside, on an edge (at a vertex).
 800    Returns positive, negative or zero value, correspondingly.
 801    Optionally, measures a signed distance between
 802    the point and the nearest polygon edge (measure_dist=1) */
 803 CVAPI(double) cvPointPolygonTest( const CvArr* contour,
 804                                   CvPoint2D32f pt, int measure_dist );
 805
 806 /****************************************************************************************\
 807 *                                  Histogram functions                                   *
 808 \****************************************************************************************/
 809
 810 /* Creates new histogram */
 811 CVAPI(CvHistogram*)  cvCreateHist( int dims, int* sizes, int type,
 812                                    float** ranges CV_DEFAULT(NULL),
 813                                    int uniform CV_DEFAULT(1));
 814
 815 /* Assignes histogram bin ranges */
 816 CVAPI(void)  cvSetHistBinRanges( CvHistogram* hist, float** ranges,
 817                                 int uniform CV_DEFAULT(1));
 818
 819 /* Creates histogram header for array */
 820 CVAPI(CvHistogram*)  cvMakeHistHeaderForArray(
 821                             int  dims, int* sizes, CvHistogram* hist,
 822                             float* data, float** ranges CV_DEFAULT(NULL),
 823                             int uniform CV_DEFAULT(1));
 824
 825 /* Releases histogram */
 826 CVAPI(void)  cvReleaseHist( CvHistogram** hist );
 827
 828 /* Clears all the histogram bins */
 829 CVAPI(void)  cvClearHist( CvHistogram* hist );
 830
 831 /* Finds indices and values of minimum and maximum histogram bins */
 832 CVAPI(void)  cvGetMinMaxHistValue( const CvHistogram* hist,
 833                                    float* min_value, float* max_value,
 834                                    int* min_idx CV_DEFAULT(NULL),
 835                                    int* max_idx CV_DEFAULT(NULL));
 836
 837
 838 /* Normalizes histogram by dividing all bins by sum of the bins, multiplied by <factor>.
 839    After that sum of histogram bins is equal to <factor> */
 840 CVAPI(void)  cvNormalizeHist( CvHistogram* hist, double factor );
 841
 842
 843 /* Clear all histogram bins that are below the threshold */
 844 CVAPI(void)  cvThreshHist( CvHistogram* hist, double threshold );
 845
 846 #define CV_COMP_CORREL        0
 847 #define CV_COMP_CHISQR        1
 848 #define CV_COMP_INTERSECT     2
 849 #define CV_COMP_BHATTACHARYYA 3
 850
 851 /* Compares two histogram */
 852 CVAPI(double)  cvCompareHist( const CvHistogram* hist1,
 853                               const CvHistogram* hist2,
 854                               int method);
 855
 856 /* Copies one histogram to another. Destination histogram is created if
 857    the destination pointer is NULL */
 858 CVAPI(void)  cvCopyHist( const CvHistogram* src, CvHistogram** dst );
 859
 860
 861 /* Calculates bayesian probabilistic histograms
 862    (each or src and dst is an array of <number> histograms */
 863 CVAPI(void)  cvCalcBayesianProb( CvHistogram** src, int number,
 864                                 CvHistogram** dst);
 865
 866 /* Calculates array histogram */
 867 CVAPI(void)  cvCalcArrHist( CvArr** arr, CvHistogram* hist,
 868                             int accumulate CV_DEFAULT(0),
 869                             const CvArr* mask CV_DEFAULT(NULL) );
 870
 871 CV_INLINE  void  cvCalcHist( IplImage** image, CvHistogram* hist,
 872                              int accumulate CV_DEFAULT(0),
 873                              const CvArr* mask CV_DEFAULT(NULL) )
 874 {
 875     cvCalcArrHist( (CvArr**)image, hist, accumulate, mask );
 876 }
 877
 878 /* Calculates back project */
 879 CVAPI(void)  cvCalcArrBackProject( CvArr** image, CvArr* dst,
 880                                    const CvHistogram* hist );
 881 #define  cvCalcBackProject(image, dst, hist) cvCalcArrBackProject((CvArr**)image, dst, hist)
 882
 883
 884 /* Does some sort of template matching but compares histograms of
 885    template and each window location */
 886 CVAPI(void)  cvCalcArrBackProjectPatch( CvArr** image, CvArr* dst, CvSize range,
 887                                         CvHistogram* hist, int method,
 888                                         double factor );
 889 #define  cvCalcBackProjectPatch( image, dst, range, hist, method, factor ) \
 890      cvCalcArrBackProjectPatch( (CvArr**)image, dst, range, hist, method, factor )
 891
 892
 893 /* calculates probabilistic density (divides one histogram by another) */
 894 CVAPI(void)  cvCalcProbDensity( const CvHistogram* hist1, const CvHistogram* hist2,
 895                                 CvHistogram* dst_hist, double scale CV_DEFAULT(255) );
 896
 897 /* equalizes histogram of 8-bit single-channel image */
 898 CVAPI(void)  cvEqualizeHist( const CvArr* src, CvArr* dst );
 899
 900
 901 #define  CV_VALUE  1
 902 #define  CV_ARRAY  2
 903 /* Updates active contour in order to minimize its cummulative
 904    (internal and external) energy. */
 905 CVAPI(void)  cvSnakeImage( const IplImage* image, CvPoint* points,
 906                            int  length, float* alpha,
 907                            float* beta, float* gamma,
 908                            int coeff_usage, CvSize  win,
 909                            CvTermCriteria criteria, int calc_gradient CV_DEFAULT(1));
 910
 911 #define CV_DIST_MASK_3   3
 912 #define CV_DIST_MASK_5   5
 913 #define CV_DIST_MASK_PRECISE 0
 914
 915 /* Applies distance transform to binary image */
 916 CVAPI(void)  cvDistTransform( const CvArr* src, CvArr* dst,
 917                               int distance_type CV_DEFAULT(CV_DIST_L2),
 918                               int mask_size CV_DEFAULT(3),
 919                               const float* mask CV_DEFAULT(NULL),
 920                               CvArr* labels CV_DEFAULT(NULL));
 921
 922
 923 /* Types of thresholding */
 924 #define CV_THRESH_BINARY      0  /* value = value > threshold ? max_value : 0       */
 925 #define CV_THRESH_BINARY_INV  1  /* value = value > threshold ? 0 : max_value       */
 926 #define CV_THRESH_TRUNC       2  /* value = value > threshold ? threshold : value   */
 927 #define CV_THRESH_TOZERO      3  /* value = value > threshold ? value : 0           */
 928 #define CV_THRESH_TOZERO_INV  4  /* value = value > threshold ? 0 : value           */
 929 #define CV_THRESH_MASK        7
 930
 931 #define CV_THRESH_OTSU        8  /* use Otsu algorithm to choose the optimal threshold value;
 932                                     combine the flag with one of the above CV_THRESH_* values */
 933
 934 /* Applies fixed-level threshold to grayscale image.
 935    This is a basic operation applied before retrieving contours */
 936 CVAPI(double)  cvThreshold( const CvArr*  src, CvArr*  dst,
 937                             double  threshold, double  max_value,
 938                             int threshold_type );
 939
 940 #define CV_ADAPTIVE_THRESH_MEAN_C  0
 941 #define CV_ADAPTIVE_THRESH_GAUSSIAN_C  1
 942
 943 /* Applies adaptive threshold to grayscale image.
 944    The two parameters for methods CV_ADAPTIVE_THRESH_MEAN_C and
 945    CV_ADAPTIVE_THRESH_GAUSSIAN_C are:
 946    neighborhood size (3, 5, 7 etc.),
 947    and a constant subtracted from mean (...,-3,-2,-1,0,1,2,3,...) */
 948 CVAPI(void)  cvAdaptiveThreshold( const CvArr* src, CvArr* dst, double max_value,
 949                                   int adaptive_method CV_DEFAULT(CV_ADAPTIVE_THRESH_MEAN_C),
 950                                   int threshold_type CV_DEFAULT(CV_THRESH_BINARY),
 951                                   int block_size CV_DEFAULT(3),
 952                                   double param1 CV_DEFAULT(5));
 953
 954 #define CV_FLOODFILL_FIXED_RANGE (1 << 16)
 955 #define CV_FLOODFILL_MASK_ONLY   (1 << 17)
 956
 957 /* Fills the connected component until the color difference gets large enough */
 958 CVAPI(void)  cvFloodFill( CvArr* image, CvPoint seed_point,
 959                           CvScalar new_val, CvScalar lo_diff CV_DEFAULT(cvScalarAll(0)),
 960                           CvScalar up_diff CV_DEFAULT(cvScalarAll(0)),
 961                           CvConnectedComp* comp CV_DEFAULT(NULL),
 962                           int flags CV_DEFAULT(4),
 963                           CvArr* mask CV_DEFAULT(NULL));
 964
 965 /****************************************************************************************\
 966 *                                  Feature detection                                     *
 967 \****************************************************************************************/
 968
 969 #define CV_CANNY_L2_GRADIENT  (1 << 31)
 970
 971 /* Runs canny edge detector */
 972 CVAPI(void)  cvCanny( const CvArr* image, CvArr* edges, double threshold1,
 973                       double threshold2, int  aperture_size CV_DEFAULT(3) );
 974
 975 /* Calculates constraint image for corner detection
 976    Dx^2 * Dyy + Dxx * Dy^2 - 2 * Dx * Dy * Dxy.
 977    Applying threshold to the result gives coordinates of corners */
 978 CVAPI(void) cvPreCornerDetect( const CvArr* image, CvArr* corners,
 979                               int aperture_size CV_DEFAULT(3) );
 980
 981 /* Calculates eigen values and vectors of 2x2
 982    gradient covariation matrix at every image pixel */
 983 CVAPI(void)  cvCornerEigenValsAndVecs( const CvArr* image, CvArr* eigenvv,
 984                                       int block_size, int aperture_size CV_DEFAULT(3) );
 985
 986 /* Calculates minimal eigenvalue for 2x2 gradient covariation matrix at
 987    every image pixel */
 988 CVAPI(void)  cvCornerMinEigenVal( const CvArr* image, CvArr* eigenval,
 989                                  int block_size, int aperture_size CV_DEFAULT(3) );
 990
 991 /* Harris corner detector:
 992    Calculates det(M) - k*(trace(M)^2), where M is 2x2 gradient covariation matrix for each pixel */
 993 CVAPI(void)  cvCornerHarris( const CvArr* image, CvArr* harris_responce,
 994                              int block_size, int aperture_size CV_DEFAULT(3),
 995                              double k CV_DEFAULT(0.04) );
 996
 997 /* Adjust corner position using some sort of gradient search */
 998 CVAPI(void)  cvFindCornerSubPix( const CvArr* image, CvPoint2D32f* corners,
 999                                  int count, CvSize win, CvSize zero_zone,
1000                                  CvTermCriteria  criteria );
1001
1002 /* Finds a sparse set of points within the selected region
1003    that seem to be easy to track */
1004 CVAPI(void)  cvGoodFeaturesToTrack( const CvArr* image, CvArr* eig_image,
1005                                    CvArr* temp_image, CvPoint2D32f* corners,
1006                                    int* corner_count, double  quality_level,
1007                                    double  min_distance,
1008                                    const CvArr* mask CV_DEFAULT(NULL),
1009                                    int block_size CV_DEFAULT(3),
1010                                    int use_harris CV_DEFAULT(0),
1011                                    double k CV_DEFAULT(0.04) );
1012
1013 #define CV_HOUGH_STANDARD 0
1014 #define CV_HOUGH_PROBABILISTIC 1
1015 #define CV_HOUGH_MULTI_SCALE 2
1016 #define CV_HOUGH_GRADIENT 3
1017
1018 /* Finds lines on binary image using one of several methods.
1019    line_storage is either memory storage or 1 x <max number of lines> CvMat, its
1020    number of columns is changed by the function.
1021    method is one of CV_HOUGH_*;
1022    rho, theta and threshold are used for each of those methods;
1023    param1 ~ line length, param2 ~ line gap - for probabilistic,
1024    param1 ~ srn, param2 ~ stn - for multi-scale */
1025 CVAPI(CvSeq*)  cvHoughLines2( CvArr* image, void* line_storage, int method,
1026                               double rho, double theta, int threshold,
1027                               double param1 CV_DEFAULT(0), double param2 CV_DEFAULT(0));
1028
1029 /* Finds circles in the image */
1030 CVAPI(CvSeq*) cvHoughCircles( CvArr* image, void* circle_storage,
1031                               int method, double dp, double min_dist,
1032                               double param1 CV_DEFAULT(100),
1033                               double param2 CV_DEFAULT(100),
1034                               int min_radius CV_DEFAULT(0),
1035                               int max_radius CV_DEFAULT(0));
1036
1037 /* Fits a line into set of 2d or 3d points in a robust way (M-estimator technique) */
1038 CVAPI(void)  cvFitLine( const CvArr* points, int dist_type, double param,
1039                         double reps, double aeps, float* line );
1040
1041
1042
1043 struct CvFeatureTree;
1044
1045 /* Constructs kd-tree from set of feature descriptors */
1046 CVAPI(struct CvFeatureTree*) cvCreateKDTree(CvMat* desc);
1047
1048 /* Constructs spill-tree from set of feature descriptors */
1049 CVAPI(struct CvFeatureTree*) cvCreateSpillTree( const CvMat* raw_data,
1050                                     const int naive CV_DEFAULT(50),
1051                                     const double rho CV_DEFAULT(.7),
1052                                     const double tau CV_DEFAULT(.1) );
1053
1054 /* Release feature tree */
1055 CVAPI(void) cvReleaseFeatureTree(struct CvFeatureTree* tr);
1056
1057 /* Searches feature tree for k nearest neighbors of given reference points,
1058    searching (in case of kd-tree/bbf) at most emax leaves. */
1059 CVAPI(void) cvFindFeatures(struct CvFeatureTree* tr, const CvMat* query_points,
1060                            CvMat* indices, CvMat* dist, int k, int emax CV_DEFAULT(20));
1061
1062 /* Search feature tree for all points that are inlier to given rect region.
1063    Only implemented for kd trees */
1064 CVAPI(int) cvFindFeaturesBoxed(struct CvFeatureTree* tr,
1065                                CvMat* bounds_min, CvMat* bounds_max,
1066                                CvMat* out_indices);
1067
1068
1069 struct CvLSH;
1070 struct CvLSHOperations;
1071
1072 /* Construct a Locality Sensitive Hash (LSH) table, for indexing d-dimensional vectors of
1073    given type. Vectors will be hashed L times with k-dimensional p-stable (p=2) functions. */
1074 CVAPI(struct CvLSH*) cvCreateLSH(struct CvLSHOperations* ops, int d,
1075                                  int L CV_DEFAULT(10), int k CV_DEFAULT(10),
1076                                  int type CV_DEFAULT(CV_64FC1), double r CV_DEFAULT(4),
1077                                  int64 seed CV_DEFAULT(-1));
1078
1079 /* Construct in-memory LSH table, with n bins. */
1080 CVAPI(struct CvLSH*) cvCreateMemoryLSH(int d, int n, int L CV_DEFAULT(10), int k CV_DEFAULT(10),
1081                                        int type CV_DEFAULT(CV_64FC1), double r CV_DEFAULT(4),
1082                                        int64 seed CV_DEFAULT(-1));
1083
1084 /* Free the given LSH structure. */
1085 CVAPI(void) cvReleaseLSH(struct CvLSH** lsh);
1086
1087 /* Return the number of vectors in the LSH. */
1088 CVAPI(unsigned int) LSHSize(struct CvLSH* lsh);
1089
1090 /* Add vectors to the LSH structure, optionally returning indices. */
1091 CVAPI(void) cvLSHAdd(struct CvLSH* lsh, const CvMat* data, CvMat* indices CV_DEFAULT(0));
1092
1093 /* Remove vectors from LSH, as addressed by given indices. */
1094 CVAPI(void) cvLSHRemove(struct CvLSH* lsh, const CvMat* indices);
1095
1096 /* Query the LSH n times for at most k nearest points; data is n x d,
1097    indices and dist are n x k. At most emax stored points will be accessed. */
1098 CVAPI(void) cvLSHQuery(struct CvLSH* lsh, const CvMat* query_points,
1099                        CvMat* indices, CvMat* dist, int k, int emax);
1100
1101
1102 typedef struct CvSURFPoint
1103 {
1104     CvPoint2D32f pt;
1105     int laplacian;
1106     int size;
1107     float dir;
1108     float hessian;
1109 } CvSURFPoint;
1110
1111 CV_INLINE CvSURFPoint cvSURFPoint( CvPoint2D32f pt, int laplacian,
1112                                    int size, float dir CV_DEFAULT(0),
1113                                    float hessian CV_DEFAULT(0))
1114 {
1115     CvSURFPoint kp;
1116     kp.pt = pt;
1117     kp.laplacian = laplacian;
1118     kp.size = size;
1119     kp.dir = dir;
1120     kp.hessian = hessian;
1121     return kp;
1122 }
1123
1124 typedef struct CvSURFParams
1125 {
1126     int extended;
1127     double hessianThreshold;
1128
1129     int nOctaves;
1130     int nOctaveLayers;
1131 }
1132 CvSURFParams;
1133
1134 CVAPI(CvSURFParams) cvSURFParams( double hessianThreshold, int extended CV_DEFAULT(0) );
1135
1136 // If useProvidedKeyPts!=0, keypoints are not detected, but descriptors are computed
1137 //  at the locations provided in keypoints (a CvSeq of CvSURFPoint).
1138 CVAPI(void) cvExtractSURF( const CvArr* img, const CvArr* mask,
1139                            CvSeq** keypoints, CvSeq** descriptors,
1140                            CvMemStorage* storage, CvSURFParams params, int useProvidedKeyPts CV_DEFAULT(0)  );
1141
1142 typedef struct CvMSERParams
1143 {
1144     // delta, in the code, it compares (size_{i}-size_{i-delta})/size_{i-delta}
1145     int delta;
1146     // prune the area which bigger/smaller than max_area/min_area
1147     int maxArea;
1148     int minArea;
1149     // prune the area have simliar size to its children
1150     float maxVariation;
1151     // trace back to cut off mser with diversity < min_diversity
1152     float minDiversity;
1153     /* the next few params for MSER of color image */
1154     // for color image, the evolution steps
1155     int maxEvolution;
1156     // the area threshold to cause re-initialize
1157     double areaThreshold;
1158     // ignore too small margin
1159     double minMargin;
1160     // the aperture size for edge blur
1161     int edgeBlurSize;
1162 }
1163 CvMSERParams;
1164
1165 CVAPI(CvMSERParams) cvMSERParams( int delta CV_DEFAULT(5), int min_area CV_DEFAULT(60),
1166                            int max_area CV_DEFAULT(14400), float max_variation CV_DEFAULT(.25f),
1167                            float min_diversity CV_DEFAULT(.2f), int max_evolution CV_DEFAULT(200),
1168                            double area_threshold CV_DEFAULT(1.01),
1169                            double min_margin CV_DEFAULT(.003),
1170                            int edge_blur_size CV_DEFAULT(5) );
1171
1172 // Extracts the contours of Maximally Stable Extremal Regions
1173 CVAPI(void) cvExtractMSER( CvArr* _img, CvArr* _mask, CvSeq** contours, CvMemStorage* storage, CvMSERParams params );
1174
1175
1176 typedef struct CvStarKeypoint
1177 {
1178     CvPoint pt;
1179     int size;
1180     float response;
1181 }
1182 CvStarKeypoint;
1183
1184 CV_INLINE CvStarKeypoint cvStarKeypoint(CvPoint pt, int size, float response)
1185 {
1186     CvStarKeypoint kpt;
1187     kpt.pt = pt;
1188     kpt.size = size;
1189     kpt.response = response;
1190     return kpt;
1191 }
1192
1193 typedef struct CvStarDetectorParams
1194 {
1195     int maxSize;
1196     int responseThreshold;
1197     int lineThresholdProjected;
1198     int lineThresholdBinarized;
1199     int suppressNonmaxSize;
1200 }
1201 CvStarDetectorParams;
1202
1203 CV_INLINE CvStarDetectorParams cvStarDetectorParams(
1204     int maxSize CV_DEFAULT(45),
1205     int responseThreshold CV_DEFAULT(30),
1206     int lineThresholdProjected CV_DEFAULT(10),
1207     int lineThresholdBinarized CV_DEFAULT(8),
1208     int suppressNonmaxSize CV_DEFAULT(5))
1209 {
1210     CvStarDetectorParams params;
1211     params.maxSize = maxSize;
1212     params.responseThreshold = responseThreshold;
1213     params.lineThresholdProjected = lineThresholdProjected;
1214     params.lineThresholdBinarized = lineThresholdBinarized;
1215     params.suppressNonmaxSize = suppressNonmaxSize;
1216
1217     return params;
1218 }
1219
1220 CVAPI(CvSeq*) cvGetStarKeypoints( const CvArr* img, CvMemStorage* storage,
1221         CvStarDetectorParams params CV_DEFAULT(cvStarDetectorParams()));
1222
1223 /****************************************************************************************\
1224 *                         Haar-like Object Detection functions                           *
1225 \****************************************************************************************/
1226
1227 /* Loads haar classifier cascade from a directory.
1228    It is obsolete: convert your cascade to xml and use cvLoad instead */
1229 CVAPI(CvHaarClassifierCascade*) cvLoadHaarClassifierCascade(
1230                     const char* directory, CvSize orig_window_size);
1231
1232 CVAPI(void) cvReleaseHaarClassifierCascade( CvHaarClassifierCascade** cascade );
1233
1234 #define CV_HAAR_DO_CANNY_PRUNING    1
1235 #define CV_HAAR_SCALE_IMAGE         2
1236 #define CV_HAAR_FIND_BIGGEST_OBJECT 4
1237 #define CV_HAAR_DO_ROUGH_SEARCH     8
1238
1239 CVAPI(CvSeq*) cvHaarDetectObjects( const CvArr* image,
1240                      CvHaarClassifierCascade* cascade,
1241                      CvMemStorage* storage, double scale_factor CV_DEFAULT(1.1),
1242                      int min_neighbors CV_DEFAULT(3), int flags CV_DEFAULT(0),
1243                      CvSize min_size CV_DEFAULT(cvSize(0,0)));
1244
1245 /* sets images for haar classifier cascade */
1246 CVAPI(void) cvSetImagesForHaarClassifierCascade( CvHaarClassifierCascade* cascade,
1247                                                 const CvArr* sum, const CvArr* sqsum,
1248                                                 const CvArr* tilted_sum, double scale );
1249
1250 /* runs the cascade on the specified window */
1251 CVAPI(int) cvRunHaarClassifierCascade( const CvHaarClassifierCascade* cascade,
1252                                        CvPoint pt, int start_stage CV_DEFAULT(0));
1253
1254 /****************************************************************************************\
1255 *                      Camera Calibration, Pose Estimation and Stereo                    *
1256 \****************************************************************************************/
1257
1258 /* Transforms the input image to compensate lens distortion */
1259 CVAPI(void) cvUndistort2( const CvArr* src, CvArr* dst,
1260                           const CvMat* camera_matrix,
1261                           const CvMat* distortion_coeffs,
1262                           const CvMat* new_camera_matrix CV_DEFAULT(0) );
1263
1264 /* Computes transformation map from intrinsic camera parameters
1265    that can used by cvRemap */
1266 CVAPI(void) cvInitUndistortMap( const CvMat* camera_matrix,
1267                                 const CvMat* distortion_coeffs,
1268                                 CvArr* mapx, CvArr* mapy );
1269
1270 /* Computes undistortion+rectification map for a head of stereo camera */
1271 CVAPI(void) cvInitUndistortRectifyMap( const CvMat* camera_matrix,
1272                                        const CvMat* dist_coeffs,
1273                                        const CvMat *R, const CvMat* new_camera_matrix,
1274                                        CvArr* mapx, CvArr* mapy );
1275
1276 /* Computes the original (undistorted) feature coordinates
1277    from the observed (distorted) coordinates */
1278 CVAPI(void) cvUndistortPoints( const CvMat* src, CvMat* dst,
1279                                const CvMat* camera_matrix,
1280                                const CvMat* dist_coeffs,
1281                                const CvMat* R CV_DEFAULT(0),
1282                                const CvMat* P CV_DEFAULT(0));
1283
1284 /* Computes the optimal new camera matrix according to the free scaling parameter alpha:
1285    alpha=0 - only valid pixels will be retained in the undistorted image
1286    alpha=1 - all the source image pixels will be retained in the undistorted image
1287 */
1288 CVAPI(void) cvGetOptimalNewCameraMatrix( const CvMat* camera_matrix,
1289                                          const CvMat* dist_coeffs,
1290                                          CvSize image_size, double alpha,
1291                                          CvMat* new_camera_matrix,
1292                                          CvSize new_imag_size CV_DEFAULT(cvSize(0,0)),
1293                                          CvRect* valid_pixel_ROI CV_DEFAULT(0) );
1294
1295 /* Converts rotation vector to rotation matrix or vice versa */
1296 CVAPI(int) cvRodrigues2( const CvMat* src, CvMat* dst,
1297                          CvMat* jacobian CV_DEFAULT(0) );
1298
1299 #define CV_LMEDS 4
1300 #define CV_RANSAC 8
1301
1302 /* Finds perspective transformation between the object plane and image (view) plane */
1303 CVAPI(int) cvFindHomography( const CvMat* src_points,
1304                              const CvMat* dst_points,
1305                              CvMat* homography,
1306                              int method CV_DEFAULT(0),
1307                              double ransacReprojThreshold CV_DEFAULT(0),
1308                              CvMat* mask CV_DEFAULT(0));
1309
1310 /* Computes RQ decomposition for 3x3 matrices */
1311 CVAPI(void) cvRQDecomp3x3( const CvMat *matrixM, CvMat *matrixR, CvMat *matrixQ,
1312                            CvMat *matrixQx CV_DEFAULT(NULL),
1313                            CvMat *matrixQy CV_DEFAULT(NULL),
1314                            CvMat *matrixQz CV_DEFAULT(NULL),
1315                            CvPoint3D64f *eulerAngles CV_DEFAULT(NULL));
1316
1317 /* Computes projection matrix decomposition */
1318 CVAPI(void) cvDecomposeProjectionMatrix( const CvMat *projMatr, CvMat *calibMatr,
1319                                          CvMat *rotMatr, CvMat *posVect,
1320                                          CvMat *rotMatrX CV_DEFAULT(NULL),
1321                                          CvMat *rotMatrY CV_DEFAULT(NULL),
1322                                          CvMat *rotMatrZ CV_DEFAULT(NULL),
1323                                          CvPoint3D64f *eulerAngles CV_DEFAULT(NULL));
1324
1325 /* Computes d(AB)/dA and d(AB)/dB */
1326 CVAPI(void) cvCalcMatMulDeriv( const CvMat* A, const CvMat* B, CvMat* dABdA, CvMat* dABdB );
1327
1328 /* Computes r3 = rodrigues(rodrigues(r2)*rodrigues(r1)),
1329    t3 = rodrigues(r2)*t1 + t2 and the respective derivatives */
1330 CVAPI(void) cvComposeRT( const CvMat* _rvec1, const CvMat* _tvec1,
1331                          const CvMat* _rvec2, const CvMat* _tvec2,
1332                          CvMat* _rvec3, CvMat* _tvec3,
1333                          CvMat* dr3dr1 CV_DEFAULT(0), CvMat* dr3dt1 CV_DEFAULT(0),
1334                          CvMat* dr3dr2 CV_DEFAULT(0), CvMat* dr3dt2 CV_DEFAULT(0),
1335                          CvMat* dt3dr1 CV_DEFAULT(0), CvMat* dt3dt1 CV_DEFAULT(0),
1336                          CvMat* dt3dr2 CV_DEFAULT(0), CvMat* dt3dt2 CV_DEFAULT(0) );
1337
1338 /* Projects object points to the view plane using
1339    the specified extrinsic and intrinsic camera parameters */
1340 CVAPI(void) cvProjectPoints2( const CvMat* object_points, const CvMat* rotation_vector,
1341                               const CvMat* translation_vector, const CvMat* camera_matrix,
1342                               const CvMat* distortion_coeffs, CvMat* image_points,
1343                               CvMat* dpdrot CV_DEFAULT(NULL), CvMat* dpdt CV_DEFAULT(NULL),
1344                               CvMat* dpdf CV_DEFAULT(NULL), CvMat* dpdc CV_DEFAULT(NULL),
1345                               CvMat* dpddist CV_DEFAULT(NULL),
1346                               double aspect_ratio CV_DEFAULT(0));
1347
1348 /* Finds extrinsic camera parameters from
1349    a few known corresponding point pairs and intrinsic parameters */
1350 CVAPI(void) cvFindExtrinsicCameraParams2( const CvMat* object_points,
1351                                           const CvMat* image_points,
1352                                           const CvMat* camera_matrix,
1353                                           const CvMat* distortion_coeffs,
1354                                           CvMat* rotation_vector,
1355                                           CvMat* translation_vector,
1356                                           int use_extrinsic_guess CV_DEFAULT(0) );
1357
1358 /* Computes initial estimate of the intrinsic camera parameters
1359    in case of planar calibration target (e.g. chessboard) */
1360 CVAPI(void) cvInitIntrinsicParams2D( const CvMat* object_points,
1361                                      const CvMat* image_points,
1362                                      const CvMat* npoints, CvSize image_size,
1363                                      CvMat* camera_matrix,
1364                                      double aspect_ratio CV_DEFAULT(1.) );
1365
1366 #define CV_CALIB_CB_ADAPTIVE_THRESH  1
1367 #define CV_CALIB_CB_NORMALIZE_IMAGE  2
1368 #define CV_CALIB_CB_FILTER_QUADS     4
1369 #define CV_CALIB_CB_FAST_CHECK       8
1370
1371 // Performs a fast check if a chessboard is in the input image. This is a workaround to
1372 // a problem of cvFindChessboardCorners being slow on images with no chessboard
1373 // - src: input image
1374 // - size: chessboard size
1375 // Returns 1 if a chessboard can be in this image and findChessboardCorners should be called,
1376 // 0 if there is no chessboard, -1 in case of error
1377 CVAPI(int) cvCheckChessboard(IplImage* src, CvSize size);
1378
1379     /* Detects corners on a chessboard calibration pattern */
1380 CVAPI(int) cvFindChessboardCorners( const void* image, CvSize pattern_size,
1381                                     CvPoint2D32f* corners,
1382                                     int* corner_count CV_DEFAULT(NULL),
1383                                     int flags CV_DEFAULT(CV_CALIB_CB_ADAPTIVE_THRESH+
1384                                         CV_CALIB_CB_NORMALIZE_IMAGE) );
1385
1386 /* Draws individual chessboard corners or the whole chessboard detected */
1387 CVAPI(void) cvDrawChessboardCorners( CvArr* image, CvSize pattern_size,
1388                                      CvPoint2D32f* corners,
1389                                      int count, int pattern_was_found );
1390
1391 #define CV_CALIB_USE_INTRINSIC_GUESS  1
1392 #define CV_CALIB_FIX_ASPECT_RATIO     2
1393 #define CV_CALIB_FIX_PRINCIPAL_POINT  4
1394 #define CV_CALIB_ZERO_TANGENT_DIST    8
1395 #define CV_CALIB_FIX_FOCAL_LENGTH 16
1396 #define CV_CALIB_FIX_K1  32
1397 #define CV_CALIB_FIX_K2  64
1398 #define CV_CALIB_FIX_K3  128
1399
1400 /* Finds intrinsic and extrinsic camera parameters
1401    from a few views of known calibration pattern */
1402 CVAPI(double) cvCalibrateCamera2( const CvMat* object_points,
1403                                 const CvMat* image_points,
1404                                 const CvMat* point_counts,
1405                                 CvSize image_size,
1406                                 CvMat* camera_matrix,
1407                                 CvMat* distortion_coeffs,
1408                                 CvMat* rotation_vectors CV_DEFAULT(NULL),
1409                                 CvMat* translation_vectors CV_DEFAULT(NULL),
1410                                 int flags CV_DEFAULT(0) );
1411
1412 /* Computes various useful characteristics of the camera from the data computed by
1413    cvCalibrateCamera2 */
1414 CVAPI(void) cvCalibrationMatrixValues( const CvMat *camera_matrix,
1415                                 CvSize image_size,
1416                                 double aperture_width CV_DEFAULT(0),
1417                                 double aperture_height CV_DEFAULT(0),
1418                                 double *fovx CV_DEFAULT(NULL),
1419                                 double *fovy CV_DEFAULT(NULL),
1420                                 double *focal_length CV_DEFAULT(NULL),
1421                                 CvPoint2D64f *principal_point CV_DEFAULT(NULL),
1422                                 double *pixel_aspect_ratio CV_DEFAULT(NULL));
1423
1424 #define CV_CALIB_FIX_INTRINSIC  256
1425 #define CV_CALIB_SAME_FOCAL_LENGTH 512
1426
1427 /* Computes the transformation from one camera coordinate system to another one
1428    from a few correspondent views of the same calibration target. Optionally, calibrates
1429    both cameras */
1430 CVAPI(double) cvStereoCalibrate( const CvMat* object_points, const CvMat* image_points1,
1431                                const CvMat* image_points2, const CvMat* npoints,
1432                                CvMat* camera_matrix1, CvMat* dist_coeffs1,
1433                                CvMat* camera_matrix2, CvMat* dist_coeffs2,
1434                                CvSize image_size, CvMat* R, CvMat* T,
1435                                CvMat* E CV_DEFAULT(0), CvMat* F CV_DEFAULT(0),
1436                                CvTermCriteria term_crit CV_DEFAULT(cvTermCriteria(
1437                                    CV_TERMCRIT_ITER+CV_TERMCRIT_EPS,30,1e-6)),
1438                                int flags CV_DEFAULT(CV_CALIB_FIX_INTRINSIC));
1439
1440 #define CV_CALIB_ZERO_DISPARITY 1024
1441
1442 /* Computes 3D rotations (+ optional shift) for each camera coordinate system to make both
1443    views parallel (=> to make all the epipolar lines horizontal or vertical) */
1444 CVAPI(void) cvStereoRectify( const CvMat* camera_matrix1, const CvMat* camera_matrix2,
1445                              const CvMat* dist_coeffs1, const CvMat* dist_coeffs2,
1446                              CvSize image_size, const CvMat* R, const CvMat* T,
1447                              CvMat* R1, CvMat* R2, CvMat* P1, CvMat* P2,
1448                              CvMat* Q CV_DEFAULT(0),
1449                              int flags CV_DEFAULT(CV_CALIB_ZERO_DISPARITY),
1450                              double alpha CV_DEFAULT(-1),
1451                              CvSize new_image_size CV_DEFAULT(cvSize(0,0)),
1452                              CvRect* valid_pix_ROI1 CV_DEFAULT(0),
1453                              CvRect* valid_pix_ROI2 CV_DEFAULT(0));
1454
1455 /* Computes rectification transformations for uncalibrated pair of images using a set
1456    of point correspondences */
1457 CVAPI(int) cvStereoRectifyUncalibrated( const CvMat* points1, const CvMat* points2,
1458                                         const CvMat* F, CvSize img_size,
1459                                         CvMat* H1, CvMat* H2,
1460                                         double threshold CV_DEFAULT(5));
1461
1462 typedef struct CvPOSITObject CvPOSITObject;
1463
1464 /* Allocates and initializes CvPOSITObject structure before doing cvPOSIT */
1465 CVAPI(CvPOSITObject*)  cvCreatePOSITObject( CvPoint3D32f* points, int point_count );
1466
1467
1468 /* Runs POSIT (POSe from ITeration) algorithm for determining 3d position of
1469    an object given its model and projection in a weak-perspective case */
1470 CVAPI(void)  cvPOSIT(  CvPOSITObject* posit_object, CvPoint2D32f* image_points,
1471                        double focal_length, CvTermCriteria criteria,
1472                        CvMatr32f rotation_matrix, CvVect32f translation_vector);
1473
1474 /* Releases CvPOSITObject structure */
1475 CVAPI(void)  cvReleasePOSITObject( CvPOSITObject**  posit_object );
1476
1477 /* updates the number of RANSAC iterations */
1478 CVAPI(int) cvRANSACUpdateNumIters( double p, double err_prob,
1479                                    int model_points, int max_iters );
1480
1481 CVAPI(void) cvConvertPointsHomogeneous( const CvMat* src, CvMat* dst );
1482
1483 /* Calculates fundamental matrix given a set of corresponding points */
1484 #define CV_FM_7POINT 1
1485 #define CV_FM_8POINT 2
1486 #define CV_FM_LMEDS_ONLY  CV_LMEDS
1487 #define CV_FM_RANSAC_ONLY CV_RANSAC
1488 #define CV_FM_LMEDS CV_LMEDS
1489 #define CV_FM_RANSAC CV_RANSAC
1490 CVAPI(int) cvFindFundamentalMat( const CvMat* points1, const CvMat* points2,
1491                                  CvMat* fundamental_matrix,
1492                                  int method CV_DEFAULT(CV_FM_RANSAC),
1493                                  double param1 CV_DEFAULT(3.), double param2 CV_DEFAULT(0.99),
1494                                  CvMat* status CV_DEFAULT(NULL) );
1495
1496 /* For each input point on one of images
1497    computes parameters of the corresponding
1498    epipolar line on the other image */
1499 CVAPI(void) cvComputeCorrespondEpilines( const CvMat* points,
1500                                          int which_image,
1501                                          const CvMat* fundamental_matrix,
1502                                          CvMat* correspondent_lines );
1503
1504 /* Triangulation functions */
1505
1506 CVAPI(void) cvTriangulatePoints(CvMat* projMatr1, CvMat* projMatr2,
1507                                 CvMat* projPoints1, CvMat* projPoints2,
1508                                 CvMat* points4D);
1509
1510 CVAPI(void) cvCorrectMatches(CvMat* F, CvMat* points1, CvMat* points2,
1511                              CvMat* new_points1, CvMat* new_points2);
1512
1513 /* stereo correspondence parameters and functions */
1514
1515 #define CV_STEREO_BM_NORMALIZED_RESPONSE  0
1516 #define CV_STEREO_BM_XSOBEL               1
1517
1518 /* Block matching algorithm structure */
1519 typedef struct CvStereoBMState
1520 {
1521     // pre-filtering (normalization of input images)
1522     int preFilterType; // =CV_STEREO_BM_NORMALIZED_RESPONSE now
1523     int preFilterSize; // averaging window size: ~5x5..21x21
1524     int preFilterCap; // the output of pre-filtering is clipped by [-preFilterCap,preFilterCap]
1525
1526     // correspondence using Sum of Absolute Difference (SAD)
1527     int SADWindowSize; // ~5x5..21x21
1528     int minDisparity;  // minimum disparity (can be negative)
1529     int numberOfDisparities; // maximum disparity - minimum disparity (> 0)
1530
1531     // post-filtering
1532     int textureThreshold;  // the disparity is only computed for pixels
1533                            // with textured enough neighborhood
1534     int uniquenessRatio;   // accept the computed disparity d* only if
1535                            // SAD(d) >= SAD(d*)*(1 + uniquenessRatio/100.)
1536                            // for any d != d*+/-1 within the search range.
1537     int speckleWindowSize; // disparity variation window
1538     int speckleRange; // acceptable range of variation in window
1539
1540     int trySmallerWindows; // if 1, the results may be more accurate,
1541                            // at the expense of slower processing
1542     CvRect roi1, roi2;
1543     int disp12MaxDiff;
1544
1545     // temporary buffers
1546     CvMat* preFilteredImg0;
1547     CvMat* preFilteredImg1;
1548     CvMat* slidingSumBuf;
1549     CvMat* cost;
1550     CvMat* disp;
1551 }
1552 CvStereoBMState;
1553
1554 #define CV_STEREO_BM_BASIC 0
1555 #define CV_STEREO_BM_FISH_EYE 1
1556 #define CV_STEREO_BM_NARROW 2
1557
1558 CVAPI(CvStereoBMState*) cvCreateStereoBMState(int preset CV_DEFAULT(CV_STEREO_BM_BASIC),
1559                                               int numberOfDisparities CV_DEFAULT(0));
1560
1561 CVAPI(void) cvReleaseStereoBMState( CvStereoBMState** state );
1562
1563 CVAPI(void) cvFindStereoCorrespondenceBM( const CvArr* left, const CvArr* right,
1564                                           CvArr* disparity, CvStereoBMState* state );
1565
1566 CVAPI(CvRect) cvGetValidDisparityROI( CvRect roi1, CvRect roi2, int minDisparity,
1567                                       int numberOfDisparities, int SADWindowSize );
1568
1569 CVAPI(void) cvValidateDisparity( CvArr* disparity, const CvArr* cost,
1570                                  int minDisparity, int numberOfDisparities,
1571                                  int disp12MaxDiff CV_DEFAULT(1) );
1572
1573 /* Kolmogorov-Zabin stereo-correspondence algorithm (a.k.a. KZ1) */
1574 #define CV_STEREO_GC_OCCLUDED  SHRT_MAX
1575
1576 typedef struct CvStereoGCState
1577 {
1578     int Ithreshold;
1579     int interactionRadius;
1580     float K, lambda, lambda1, lambda2;
1581     int occlusionCost;
1582     int minDisparity;
1583     int numberOfDisparities;
1584     int maxIters;
1585
1586     CvMat* left;
1587     CvMat* right;
1588     CvMat* dispLeft;
1589     CvMat* dispRight;
1590     CvMat* ptrLeft;
1591     CvMat* ptrRight;
1592     CvMat* vtxBuf;
1593     CvMat* edgeBuf;
1594 }
1595 CvStereoGCState;
1596
1597 CVAPI(CvStereoGCState*) cvCreateStereoGCState( int numberOfDisparities, int maxIters );
1598 CVAPI(void) cvReleaseStereoGCState( CvStereoGCState** state );
1599
1600 CVAPI(void) cvFindStereoCorrespondenceGC( const CvArr* left, const CvArr* right,
1601                                           CvArr* disparityLeft, CvArr* disparityRight,
1602                                           CvStereoGCState* state,
1603                                           int useDisparityGuess CV_DEFAULT(0) );
1604
1605 /* Reprojects the computed disparity image to the 3D space using the specified 4x4 matrix */
1606 CVAPI(void)  cvReprojectImageTo3D( const CvArr* disparityImage,
1607                                    CvArr* _3dImage, const CvMat* Q,
1608                                    int handleMissingValues CV_DEFAULT(0) );
1609
1610 #ifdef __cplusplus
1611 }
1612 #endif
1613
1614 #ifdef __cplusplus
1615 #ifndef SKIP_INCLUDES // for now only expose old interface to swig
1616 #include "cv.hpp"
1617 #endif // SKIP_INCLUDES
1618 #endif
1619
1620 /****************************************************************************************\
1621 *                                 Backward compatibility                                 *
1622 \****************************************************************************************/
1623
1624 #ifndef CV_NO_BACKWARD_COMPATIBILITY
1625 #include "cvcompat.h"
1626 #endif
1627
1628 #endif