modules/calib3d/include/opencv2/calib3d/calib3d.hpp

   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_CALIB3D_HPP__
  44 #define __OPENCV_CALIB3D_HPP__
  45
  46 #include "opencv2/core/core.hpp"
  47 #include "opencv2/features2d/features2d.hpp"
  48
  49 #ifdef __cplusplus
  50 extern "C" {
  51 #endif
  52
  53 /****************************************************************************************\
  54 *                      Camera Calibration, Pose Estimation and Stereo                    *
  55 \****************************************************************************************/
  56
  57 typedef struct CvPOSITObject CvPOSITObject;
  58
  59 /* Allocates and initializes CvPOSITObject structure before doing cvPOSIT */
  60 CVAPI(CvPOSITObject*)  cvCreatePOSITObject( CvPoint3D32f* points, int point_count );
  61
  62
  63 /* Runs POSIT (POSe from ITeration) algorithm for determining 3d position of
  64    an object given its model and projection in a weak-perspective case */
  65 CVAPI(void)  cvPOSIT(  CvPOSITObject* posit_object, CvPoint2D32f* image_points,
  66                        double focal_length, CvTermCriteria criteria,
  67                        float* rotation_matrix, float* translation_vector);
  68
  69 /* Releases CvPOSITObject structure */
  70 CVAPI(void)  cvReleasePOSITObject( CvPOSITObject**  posit_object );
  71
  72 /* updates the number of RANSAC iterations */
  73 CVAPI(int) cvRANSACUpdateNumIters( double p, double err_prob,
  74                                    int model_points, int max_iters );
  75
  76 CVAPI(void) cvConvertPointsHomogeneous( const CvMat* src, CvMat* dst );
  77
  78 /* Calculates fundamental matrix given a set of corresponding points */
  79 #define CV_FM_7POINT 1
  80 #define CV_FM_8POINT 2
  81
  82 #define CV_LMEDS 4
  83 #define CV_RANSAC 8
  84
  85 #define CV_FM_LMEDS_ONLY  CV_LMEDS
  86 #define CV_FM_RANSAC_ONLY CV_RANSAC
  87 #define CV_FM_LMEDS CV_LMEDS
  88 #define CV_FM_RANSAC CV_RANSAC
  89
  90 enum
  91 {
  92     CV_ITERATIVE = 0,
  93     CV_EPNP = 1, // F.Moreno-Noguer, V.Lepetit and P.Fua "EPnP: Efficient Perspective-n-Point Camera Pose Estimation"
  94     CV_P3P = 2 // X.S. Gao, X.-R. Hou, J. Tang, H.-F. Chang; "Complete Solution Classification for the Perspective-Three-Point Problem"
  95 };
  96
  97 CVAPI(int) cvFindFundamentalMat( const CvMat* points1, const CvMat* points2,
  98                                  CvMat* fundamental_matrix,
  99                                  int method CV_DEFAULT(CV_FM_RANSAC),
 100                                  double param1 CV_DEFAULT(3.), double param2 CV_DEFAULT(0.99),
 101                                  CvMat* status CV_DEFAULT(NULL) );
 102
 103 /* For each input point on one of images
 104    computes parameters of the corresponding
 105    epipolar line on the other image */
 106 CVAPI(void) cvComputeCorrespondEpilines( const CvMat* points,
 107                                          int which_image,
 108                                          const CvMat* fundamental_matrix,
 109                                          CvMat* correspondent_lines );
 110
 111 /* Triangulation functions */
 112
 113 CVAPI(void) cvTriangulatePoints(CvMat* projMatr1, CvMat* projMatr2,
 114                                 CvMat* projPoints1, CvMat* projPoints2,
 115                                 CvMat* points4D);
 116
 117 CVAPI(void) cvCorrectMatches(CvMat* F, CvMat* points1, CvMat* points2,
 118                              CvMat* new_points1, CvMat* new_points2);
 119
 120
 121 /* Computes the optimal new camera matrix according to the free scaling parameter alpha:
 122    alpha=0 - only valid pixels will be retained in the undistorted image
 123    alpha=1 - all the source image pixels will be retained in the undistorted image
 124 */
 125 CVAPI(void) cvGetOptimalNewCameraMatrix( const CvMat* camera_matrix,
 126                                          const CvMat* dist_coeffs,
 127                                          CvSize image_size, double alpha,
 128                                          CvMat* new_camera_matrix,
 129                                          CvSize new_imag_size CV_DEFAULT(cvSize(0,0)),
 130                                          CvRect* valid_pixel_ROI CV_DEFAULT(0),
 131                                          int center_principal_point CV_DEFAULT(0));
 132
 133 /* Converts rotation vector to rotation matrix or vice versa */
 134 CVAPI(int) cvRodrigues2( const CvMat* src, CvMat* dst,
 135                          CvMat* jacobian CV_DEFAULT(0) );
 136
 137 /* Finds perspective transformation between the object plane and image (view) plane */
 138 CVAPI(int) cvFindHomography( const CvMat* src_points,
 139                              const CvMat* dst_points,
 140                              CvMat* homography,
 141                              int method CV_DEFAULT(0),
 142                              double ransacReprojThreshold CV_DEFAULT(3),
 143                              CvMat* mask CV_DEFAULT(0));
 144
 145 /* Computes RQ decomposition for 3x3 matrices */
 146 CVAPI(void) cvRQDecomp3x3( const CvMat *matrixM, CvMat *matrixR, CvMat *matrixQ,
 147                            CvMat *matrixQx CV_DEFAULT(NULL),
 148                            CvMat *matrixQy CV_DEFAULT(NULL),
 149                            CvMat *matrixQz CV_DEFAULT(NULL),
 150                            CvPoint3D64f *eulerAngles CV_DEFAULT(NULL));
 151
 152 /* Computes projection matrix decomposition */
 153 CVAPI(void) cvDecomposeProjectionMatrix( const CvMat *projMatr, CvMat *calibMatr,
 154                                          CvMat *rotMatr, CvMat *posVect,
 155                                          CvMat *rotMatrX CV_DEFAULT(NULL),
 156                                          CvMat *rotMatrY CV_DEFAULT(NULL),
 157                                          CvMat *rotMatrZ CV_DEFAULT(NULL),
 158                                          CvPoint3D64f *eulerAngles CV_DEFAULT(NULL));
 159
 160 /* Computes d(AB)/dA and d(AB)/dB */
 161 CVAPI(void) cvCalcMatMulDeriv( const CvMat* A, const CvMat* B, CvMat* dABdA, CvMat* dABdB );
 162
 163 /* Computes r3 = rodrigues(rodrigues(r2)*rodrigues(r1)),
 164    t3 = rodrigues(r2)*t1 + t2 and the respective derivatives */
 165 CVAPI(void) cvComposeRT( const CvMat* _rvec1, const CvMat* _tvec1,
 166                          const CvMat* _rvec2, const CvMat* _tvec2,
 167                          CvMat* _rvec3, CvMat* _tvec3,
 168                          CvMat* dr3dr1 CV_DEFAULT(0), CvMat* dr3dt1 CV_DEFAULT(0),
 169                          CvMat* dr3dr2 CV_DEFAULT(0), CvMat* dr3dt2 CV_DEFAULT(0),
 170                          CvMat* dt3dr1 CV_DEFAULT(0), CvMat* dt3dt1 CV_DEFAULT(0),
 171                          CvMat* dt3dr2 CV_DEFAULT(0), CvMat* dt3dt2 CV_DEFAULT(0) );
 172
 173 /* Projects object points to the view plane using
 174    the specified extrinsic and intrinsic camera parameters */
 175 CVAPI(void) cvProjectPoints2( const CvMat* object_points, const CvMat* rotation_vector,
 176                               const CvMat* translation_vector, const CvMat* camera_matrix,
 177                               const CvMat* distortion_coeffs, CvMat* image_points,
 178                               CvMat* dpdrot CV_DEFAULT(NULL), CvMat* dpdt CV_DEFAULT(NULL),
 179                               CvMat* dpdf CV_DEFAULT(NULL), CvMat* dpdc CV_DEFAULT(NULL),
 180                               CvMat* dpddist CV_DEFAULT(NULL),
 181                               double aspect_ratio CV_DEFAULT(0));
 182
 183 /* Finds extrinsic camera parameters from
 184    a few known corresponding point pairs and intrinsic parameters */
 185 CVAPI(void) cvFindExtrinsicCameraParams2( const CvMat* object_points,
 186                                           const CvMat* image_points,
 187                                           const CvMat* camera_matrix,
 188                                           const CvMat* distortion_coeffs,
 189                                           CvMat* rotation_vector,
 190                                           CvMat* translation_vector,
 191                                           int use_extrinsic_guess CV_DEFAULT(0) );
 192
 193 /* Computes initial estimate of the intrinsic camera parameters
 194    in case of planar calibration target (e.g. chessboard) */
 195 CVAPI(void) cvInitIntrinsicParams2D( const CvMat* object_points,
 196                                      const CvMat* image_points,
 197                                      const CvMat* npoints, CvSize image_size,
 198                                      CvMat* camera_matrix,
 199                                      double aspect_ratio CV_DEFAULT(1.) );
 200
 201 #define CV_CALIB_CB_ADAPTIVE_THRESH  1
 202 #define CV_CALIB_CB_NORMALIZE_IMAGE  2
 203 #define CV_CALIB_CB_FILTER_QUADS     4
 204 #define CV_CALIB_CB_FAST_CHECK       8
 205
 206 // Performs a fast check if a chessboard is in the input image. This is a workaround to
 207 // a problem of cvFindChessboardCorners being slow on images with no chessboard
 208 // - src: input image
 209 // - size: chessboard size
 210 // Returns 1 if a chessboard can be in this image and findChessboardCorners should be called,
 211 // 0 if there is no chessboard, -1 in case of error
 212 CVAPI(int) cvCheckChessboard(IplImage* src, CvSize size);
 213
 214     /* Detects corners on a chessboard calibration pattern */
 215 CVAPI(int) cvFindChessboardCorners( const void* image, CvSize pattern_size,
 216                                     CvPoint2D32f* corners,
 217                                     int* corner_count CV_DEFAULT(NULL),
 218                                     int flags CV_DEFAULT(CV_CALIB_CB_ADAPTIVE_THRESH+CV_CALIB_CB_NORMALIZE_IMAGE) );
 219
 220 /* Draws individual chessboard corners or the whole chessboard detected */
 221 CVAPI(void) cvDrawChessboardCorners( CvArr* image, CvSize pattern_size,
 222                                      CvPoint2D32f* corners,
 223                                      int count, int pattern_was_found );
 224
 225 #define CV_CALIB_USE_INTRINSIC_GUESS  1
 226 #define CV_CALIB_FIX_ASPECT_RATIO     2
 227 #define CV_CALIB_FIX_PRINCIPAL_POINT  4
 228 #define CV_CALIB_ZERO_TANGENT_DIST    8
 229 #define CV_CALIB_FIX_FOCAL_LENGTH 16
 230 #define CV_CALIB_FIX_K1  32
 231 #define CV_CALIB_FIX_K2  64
 232 #define CV_CALIB_FIX_K3  128
 233 #define CV_CALIB_FIX_K4  2048
 234 #define CV_CALIB_FIX_K5  4096
 235 #define CV_CALIB_FIX_K6  8192
 236 #define CV_CALIB_RATIONAL_MODEL 16384
 237
 238 /* Finds intrinsic and extrinsic camera parameters
 239    from a few views of known calibration pattern */
 240 CVAPI(double) cvCalibrateCamera2( const CvMat* object_points,
 241                                 const CvMat* image_points,
 242                                 const CvMat* point_counts,
 243                                 CvSize image_size,
 244                                 CvMat* camera_matrix,
 245                                 CvMat* distortion_coeffs,
 246                                 CvMat* rotation_vectors CV_DEFAULT(NULL),
 247                                 CvMat* translation_vectors CV_DEFAULT(NULL),
 248                                 int flags CV_DEFAULT(0),
 249                                 CvTermCriteria term_crit CV_DEFAULT(cvTermCriteria(
 250                                     CV_TERMCRIT_ITER+CV_TERMCRIT_EPS,30,DBL_EPSILON)) );
 251
 252 /* Computes various useful characteristics of the camera from the data computed by
 253    cvCalibrateCamera2 */
 254 CVAPI(void) cvCalibrationMatrixValues( const CvMat *camera_matrix,
 255                                 CvSize image_size,
 256                                 double aperture_width CV_DEFAULT(0),
 257                                 double aperture_height CV_DEFAULT(0),
 258                                 double *fovx CV_DEFAULT(NULL),
 259                                 double *fovy CV_DEFAULT(NULL),
 260                                 double *focal_length CV_DEFAULT(NULL),
 261                                 CvPoint2D64f *principal_point CV_DEFAULT(NULL),
 262                                 double *pixel_aspect_ratio CV_DEFAULT(NULL));
 263
 264 #define CV_CALIB_FIX_INTRINSIC  256
 265 #define CV_CALIB_SAME_FOCAL_LENGTH 512
 266
 267 /* Computes the transformation from one camera coordinate system to another one
 268    from a few correspondent views of the same calibration target. Optionally, calibrates
 269    both cameras */
 270 CVAPI(double) cvStereoCalibrate( const CvMat* object_points, const CvMat* image_points1,
 271                                const CvMat* image_points2, const CvMat* npoints,
 272                                CvMat* camera_matrix1, CvMat* dist_coeffs1,
 273                                CvMat* camera_matrix2, CvMat* dist_coeffs2,
 274                                CvSize image_size, CvMat* R, CvMat* T,
 275                                CvMat* E CV_DEFAULT(0), CvMat* F CV_DEFAULT(0),
 276                                CvTermCriteria term_crit CV_DEFAULT(cvTermCriteria(
 277                                    CV_TERMCRIT_ITER+CV_TERMCRIT_EPS,30,1e-6)),
 278                                int flags CV_DEFAULT(CV_CALIB_FIX_INTRINSIC));
 279
 280 #define CV_CALIB_ZERO_DISPARITY 1024
 281
 282 /* Computes 3D rotations (+ optional shift) for each camera coordinate system to make both
 283    views parallel (=> to make all the epipolar lines horizontal or vertical) */
 284 CVAPI(void) cvStereoRectify( const CvMat* camera_matrix1, const CvMat* camera_matrix2,
 285                              const CvMat* dist_coeffs1, const CvMat* dist_coeffs2,
 286                              CvSize image_size, const CvMat* R, const CvMat* T,
 287                              CvMat* R1, CvMat* R2, CvMat* P1, CvMat* P2,
 288                              CvMat* Q CV_DEFAULT(0),
 289                              int flags CV_DEFAULT(CV_CALIB_ZERO_DISPARITY),
 290                              double alpha CV_DEFAULT(-1),
 291                              CvSize new_image_size CV_DEFAULT(cvSize(0,0)),
 292                              CvRect* valid_pix_ROI1 CV_DEFAULT(0),
 293                              CvRect* valid_pix_ROI2 CV_DEFAULT(0));
 294
 295 /* Computes rectification transformations for uncalibrated pair of images using a set
 296    of point correspondences */
 297 CVAPI(int) cvStereoRectifyUncalibrated( const CvMat* points1, const CvMat* points2,
 298                                         const CvMat* F, CvSize img_size,
 299                                         CvMat* H1, CvMat* H2,
 300                                         double threshold CV_DEFAULT(5));
 301
 302
 303
 304 /* stereo correspondence parameters and functions */
 305
 306 #define CV_STEREO_BM_NORMALIZED_RESPONSE  0
 307 #define CV_STEREO_BM_XSOBEL               1
 308
 309 /* Block matching algorithm structure */
 310 typedef struct CvStereoBMState
 311 {
 312     // pre-filtering (normalization of input images)
 313     int preFilterType; // =CV_STEREO_BM_NORMALIZED_RESPONSE now
 314     int preFilterSize; // averaging window size: ~5x5..21x21
 315     int preFilterCap; // the output of pre-filtering is clipped by [-preFilterCap,preFilterCap]
 316
 317     // correspondence using Sum of Absolute Difference (SAD)
 318     int SADWindowSize; // ~5x5..21x21
 319     int minDisparity;  // minimum disparity (can be negative)
 320     int numberOfDisparities; // maximum disparity - minimum disparity (> 0)
 321
 322     // post-filtering
 323     int textureThreshold;  // the disparity is only computed for pixels
 324                            // with textured enough neighborhood
 325     int uniquenessRatio;   // accept the computed disparity d* only if
 326                            // SAD(d) >= SAD(d*)*(1 + uniquenessRatio/100.)
 327                            // for any d != d*+/-1 within the search range.
 328     int speckleWindowSize; // disparity variation window
 329     int speckleRange; // acceptable range of variation in window
 330
 331     int trySmallerWindows; // if 1, the results may be more accurate,
 332                            // at the expense of slower processing
 333     CvRect roi1, roi2;
 334     int disp12MaxDiff;
 335
 336     // temporary buffers
 337     CvMat* preFilteredImg0;
 338     CvMat* preFilteredImg1;
 339     CvMat* slidingSumBuf;
 340     CvMat* cost;
 341     CvMat* disp;
 342 } CvStereoBMState;
 343
 344 #define CV_STEREO_BM_BASIC 0
 345 #define CV_STEREO_BM_FISH_EYE 1
 346 #define CV_STEREO_BM_NARROW 2
 347
 348 CVAPI(CvStereoBMState*) cvCreateStereoBMState(int preset CV_DEFAULT(CV_STEREO_BM_BASIC),
 349                                               int numberOfDisparities CV_DEFAULT(0));
 350
 351 CVAPI(void) cvReleaseStereoBMState( CvStereoBMState** state );
 352
 353 CVAPI(void) cvFindStereoCorrespondenceBM( const CvArr* left, const CvArr* right,
 354                                           CvArr* disparity, CvStereoBMState* state );
 355
 356 CVAPI(CvRect) cvGetValidDisparityROI( CvRect roi1, CvRect roi2, int minDisparity,
 357                                       int numberOfDisparities, int SADWindowSize );
 358
 359 CVAPI(void) cvValidateDisparity( CvArr* disparity, const CvArr* cost,
 360                                  int minDisparity, int numberOfDisparities,
 361                                  int disp12MaxDiff CV_DEFAULT(1) );
 362
 363 /* Reprojects the computed disparity image to the 3D space using the specified 4x4 matrix */
 364 CVAPI(void)  cvReprojectImageTo3D( const CvArr* disparityImage,
 365                                    CvArr* _3dImage, const CvMat* Q,
 366                                    int handleMissingValues CV_DEFAULT(0) );
 367
 368
 369 #ifdef __cplusplus
 370 }
 371
 372 //////////////////////////////////////////////////////////////////////////////////////////
 373 class CV_EXPORTS CvLevMarq
 374 {
 375 public:
 376     CvLevMarq();
 377     CvLevMarq( int nparams, int nerrs, CvTermCriteria criteria=
 378               cvTermCriteria(CV_TERMCRIT_EPS+CV_TERMCRIT_ITER,30,DBL_EPSILON),
 379               bool completeSymmFlag=false );
 380     ~CvLevMarq();
 381     void init( int nparams, int nerrs, CvTermCriteria criteria=
 382               cvTermCriteria(CV_TERMCRIT_EPS+CV_TERMCRIT_ITER,30,DBL_EPSILON),
 383               bool completeSymmFlag=false );
 384     bool update( const CvMat*& param, CvMat*& J, CvMat*& err );
 385     bool updateAlt( const CvMat*& param, CvMat*& JtJ, CvMat*& JtErr, double*& errNorm );
 386
 387     void clear();
 388     void step();
 389     enum { DONE=0, STARTED=1, CALC_J=2, CHECK_ERR=3 };
 390
 391     cv::Ptr<CvMat> mask;
 392     cv::Ptr<CvMat> prevParam;
 393     cv::Ptr<CvMat> param;
 394     cv::Ptr<CvMat> J;
 395     cv::Ptr<CvMat> err;
 396     cv::Ptr<CvMat> JtJ;
 397     cv::Ptr<CvMat> JtJN;
 398     cv::Ptr<CvMat> JtErr;
 399     cv::Ptr<CvMat> JtJV;
 400     cv::Ptr<CvMat> JtJW;
 401     double prevErrNorm, errNorm;
 402     int lambdaLg10;
 403     CvTermCriteria criteria;
 404     int state;
 405     int iters;
 406     bool completeSymmFlag;
 407 };
 408
 409 namespace cv
 410 {
 411 //! converts rotation vector to rotation matrix or vice versa using Rodrigues transformation
 412 CV_EXPORTS_W void Rodrigues(InputArray src, OutputArray dst, OutputArray jacobian=noArray());
 413
 414 //! type of the robust estimation algorithm
 415 enum
 416 {
 417     LMEDS=CV_LMEDS, //!< least-median algorithm
 418     RANSAC=CV_RANSAC //!< RANSAC algorithm
 419 };
 420
 421 //! computes the best-fit perspective transformation mapping srcPoints to dstPoints.
 422 CV_EXPORTS_W Mat findHomography( InputArray srcPoints, InputArray dstPoints,
 423                                  int method=0, double ransacReprojThreshold=3,
 424                                  OutputArray mask=noArray());
 425
 426 //! variant of findHomography for backward compatibility
 427 CV_EXPORTS Mat findHomography( InputArray srcPoints, InputArray dstPoints,
 428                                OutputArray mask, int method=0, double ransacReprojThreshold=3);
 429
 430 //! Computes RQ decomposition of 3x3 matrix
 431 CV_EXPORTS_W Vec3d RQDecomp3x3( InputArray src, OutputArray mtxR, OutputArray mtxQ,
 432                                 OutputArray Qx=noArray(),
 433                                 OutputArray Qy=noArray(),
 434                                 OutputArray Qz=noArray());
 435
 436 //! Decomposes the projection matrix into camera matrix and the rotation martix and the translation vector
 437 CV_EXPORTS_W void decomposeProjectionMatrix( InputArray projMatrix, OutputArray cameraMatrix,
 438                                              OutputArray rotMatrix, OutputArray transVect,
 439                                              OutputArray rotMatrixX=noArray(),
 440                                              OutputArray rotMatrixY=noArray(),
 441                                              OutputArray rotMatrixZ=noArray(),
 442                                              OutputArray eulerAngles=noArray() );
 443
 444 //! computes derivatives of the matrix product w.r.t each of the multiplied matrix coefficients
 445 CV_EXPORTS_W void matMulDeriv( InputArray A, InputArray B,
 446                                OutputArray dABdA,
 447                                OutputArray dABdB );
 448
 449 //! composes 2 [R|t] transformations together. Also computes the derivatives of the result w.r.t the arguments
 450 CV_EXPORTS_W void composeRT( InputArray rvec1, InputArray tvec1,
 451                              InputArray rvec2, InputArray tvec2,
 452                              OutputArray rvec3, OutputArray tvec3,
 453                              OutputArray dr3dr1=noArray(), OutputArray dr3dt1=noArray(),
 454                              OutputArray dr3dr2=noArray(), OutputArray dr3dt2=noArray(),
 455                              OutputArray dt3dr1=noArray(), OutputArray dt3dt1=noArray(),
 456                              OutputArray dt3dr2=noArray(), OutputArray dt3dt2=noArray() );
 457
 458 //! projects points from the model coordinate space to the image coordinates. Also computes derivatives of the image coordinates w.r.t the intrinsic and extrinsic camera parameters
 459 CV_EXPORTS_W void projectPoints( InputArray objectPoints,
 460                                  InputArray rvec, InputArray tvec,
 461                                  InputArray cameraMatrix, InputArray distCoeffs,
 462                                  OutputArray imagePoints,
 463                                  OutputArray jacobian=noArray(),
 464                                  double aspectRatio=0 );
 465
 466 //! computes the camera pose from a few 3D points and the corresponding projections. The outliers are not handled.
 467 enum
 468 {
 469     ITERATIVE=CV_ITERATIVE,
 470     EPNP=CV_EPNP,
 471     P3P=CV_P3P
 472 };
 473 CV_EXPORTS_W bool solvePnP( InputArray objectPoints, InputArray imagePoints,
 474                             InputArray cameraMatrix, InputArray distCoeffs,
 475                             OutputArray rvec, OutputArray tvec,
 476                             bool useExtrinsicGuess=false, int flags=ITERATIVE);
 477
 478 //! computes the camera pose from a few 3D points and the corresponding projections. The outliers are possible.
 479 CV_EXPORTS_W void solvePnPRansac( InputArray objectPoints,
 480                                   InputArray imagePoints,
 481                                   InputArray cameraMatrix,
 482                                   InputArray distCoeffs,
 483                                   OutputArray rvec,
 484                                   OutputArray tvec,
 485                                   bool useExtrinsicGuess = false,
 486                                   int iterationsCount = 100,
 487                                   float reprojectionError = 8.0,
 488                                   int minInliersCount = 100,
 489                                   OutputArray inliers = noArray(),
 490                                   int flags = ITERATIVE);
 491
 492 //! initializes camera matrix from a few 3D points and the corresponding projections.
 493 CV_EXPORTS_W Mat initCameraMatrix2D( InputArrayOfArrays objectPoints,
 494                                      InputArrayOfArrays imagePoints,
 495                                      Size imageSize, double aspectRatio=1. );
 496
 497 enum { CALIB_CB_ADAPTIVE_THRESH = 1, CALIB_CB_NORMALIZE_IMAGE = 2,
 498        CALIB_CB_FILTER_QUADS = 4, CALIB_CB_FAST_CHECK = 8 };
 499
 500 //! finds checkerboard pattern of the specified size in the image
 501 CV_EXPORTS_W bool findChessboardCorners( InputArray image, Size patternSize,
 502                                          OutputArray corners,
 503                                          int flags=CALIB_CB_ADAPTIVE_THRESH+CALIB_CB_NORMALIZE_IMAGE );
 504
 505 //! finds subpixel-accurate positions of the chessboard corners
 506 CV_EXPORTS bool find4QuadCornerSubpix(InputArray img, InputOutputArray corners, Size region_size);
 507
 508 //! draws the checkerboard pattern (found or partly found) in the image
 509 CV_EXPORTS_W void drawChessboardCorners( InputOutputArray image, Size patternSize,
 510                                          InputArray corners, bool patternWasFound );
 511
 512 enum { CALIB_CB_SYMMETRIC_GRID = 1, CALIB_CB_ASYMMETRIC_GRID = 2,
 513        CALIB_CB_CLUSTERING = 4 };
 514
 515 //! finds circles' grid pattern of the specified size in the image
 516 CV_EXPORTS_W bool findCirclesGrid( InputArray image, Size patternSize,
 517                                  OutputArray centers, int flags=CALIB_CB_SYMMETRIC_GRID,
 518                                  const Ptr<FeatureDetector> &blobDetector = new SimpleBlobDetector());
 519
 520 //! the deprecated function. Use findCirclesGrid() instead of it.
 521 CV_EXPORTS_W bool findCirclesGridDefault( InputArray image, Size patternSize,
 522                                           OutputArray centers, int flags=CALIB_CB_SYMMETRIC_GRID );
 523 enum
 524 {
 525     CALIB_USE_INTRINSIC_GUESS = CV_CALIB_USE_INTRINSIC_GUESS,
 526     CALIB_FIX_ASPECT_RATIO = CV_CALIB_FIX_ASPECT_RATIO,
 527     CALIB_FIX_PRINCIPAL_POINT = CV_CALIB_FIX_PRINCIPAL_POINT,
 528     CALIB_ZERO_TANGENT_DIST = CV_CALIB_ZERO_TANGENT_DIST,
 529     CALIB_FIX_FOCAL_LENGTH = CV_CALIB_FIX_FOCAL_LENGTH,
 530     CALIB_FIX_K1 = CV_CALIB_FIX_K1,
 531     CALIB_FIX_K2 = CV_CALIB_FIX_K2,
 532     CALIB_FIX_K3 = CV_CALIB_FIX_K3,
 533     CALIB_FIX_K4 = CV_CALIB_FIX_K4,
 534     CALIB_FIX_K5 = CV_CALIB_FIX_K5,
 535     CALIB_FIX_K6 = CV_CALIB_FIX_K6,
 536     CALIB_RATIONAL_MODEL = CV_CALIB_RATIONAL_MODEL,
 537     // only for stereo
 538     CALIB_FIX_INTRINSIC = CV_CALIB_FIX_INTRINSIC,
 539     CALIB_SAME_FOCAL_LENGTH = CV_CALIB_SAME_FOCAL_LENGTH,
 540     // for stereo rectification
 541     CALIB_ZERO_DISPARITY = CV_CALIB_ZERO_DISPARITY
 542 };
 543
 544 //! finds intrinsic and extrinsic camera parameters from several fews of a known calibration pattern.
 545 CV_EXPORTS_W double calibrateCamera( InputArrayOfArrays objectPoints,
 546                                      InputArrayOfArrays imagePoints,
 547                                      Size imageSize,
 548                                      CV_OUT InputOutputArray cameraMatrix,
 549                                      CV_OUT InputOutputArray distCoeffs,
 550                                      OutputArrayOfArrays rvecs, OutputArrayOfArrays tvecs,
 551                                      int flags=0, TermCriteria criteria = TermCriteria(
 552                                          TermCriteria::COUNT+TermCriteria::EPS, 30, DBL_EPSILON) );
 553
 554 //! computes several useful camera characteristics from the camera matrix, camera frame resolution and the physical sensor size.
 555 CV_EXPORTS_W void calibrationMatrixValues( InputArray cameraMatrix,
 556                                 Size imageSize,
 557                                 double apertureWidth,
 558                                 double apertureHeight,
 559                                 CV_OUT double& fovx,
 560                                 CV_OUT double& fovy,
 561                                 CV_OUT double& focalLength,
 562                                 CV_OUT Point2d& principalPoint,
 563                                 CV_OUT double& aspectRatio );
 564
 565 //! finds intrinsic and extrinsic parameters of a stereo camera
 566 CV_EXPORTS_W double stereoCalibrate( InputArrayOfArrays objectPoints,
 567                                      InputArrayOfArrays imagePoints1,
 568                                      InputArrayOfArrays imagePoints2,
 569                                      CV_OUT InputOutputArray cameraMatrix1,
 570                                      CV_OUT InputOutputArray distCoeffs1,
 571                                      CV_OUT InputOutputArray cameraMatrix2,
 572                                      CV_OUT InputOutputArray distCoeffs2,
 573                                      Size imageSize, OutputArray R,
 574                                      OutputArray T, OutputArray E, OutputArray F,
 575                                      TermCriteria criteria = TermCriteria(TermCriteria::COUNT+TermCriteria::EPS, 30, 1e-6),
 576                                      int flags=CALIB_FIX_INTRINSIC );
 577
 578
 579 //! computes the rectification transformation for a stereo camera from its intrinsic and extrinsic parameters
 580 CV_EXPORTS_W void stereoRectify( InputArray cameraMatrix1, InputArray distCoeffs1,
 581                                InputArray cameraMatrix2, InputArray distCoeffs2,
 582                                Size imageSize, InputArray R, InputArray T,
 583                                OutputArray R1, OutputArray R2,
 584                                OutputArray P1, OutputArray P2,
 585                                OutputArray Q, int flags=CALIB_ZERO_DISPARITY,
 586                                double alpha=-1, Size newImageSize=Size(),
 587                                CV_OUT Rect* validPixROI1=0, CV_OUT Rect* validPixROI2=0 );
 588
 589 //! computes the rectification transformation for an uncalibrated stereo camera (zero distortion is assumed)
 590 CV_EXPORTS_W bool stereoRectifyUncalibrated( InputArray points1, InputArray points2,
 591                                              InputArray F, Size imgSize,
 592                                              OutputArray H1, OutputArray H2,
 593                                              double threshold=5 );
 594
 595 //! computes the rectification transformations for 3-head camera, where all the heads are on the same line.
 596 CV_EXPORTS_W float rectify3Collinear( InputArray cameraMatrix1, InputArray distCoeffs1,
 597                                       InputArray cameraMatrix2, InputArray distCoeffs2,
 598                                       InputArray cameraMatrix3, InputArray distCoeffs3,
 599                                       InputArrayOfArrays imgpt1, InputArrayOfArrays imgpt3,
 600                                       Size imageSize, InputArray R12, InputArray T12,
 601                                       InputArray R13, InputArray T13,
 602                                       OutputArray R1, OutputArray R2, OutputArray R3,
 603                                       OutputArray P1, OutputArray P2, OutputArray P3,
 604                                       OutputArray Q, double alpha, Size newImgSize,
 605                                       CV_OUT Rect* roi1, CV_OUT Rect* roi2, int flags );
 606
 607 //! returns the optimal new camera matrix
 608 CV_EXPORTS_W Mat getOptimalNewCameraMatrix( InputArray cameraMatrix, InputArray distCoeffs,
 609                                             Size imageSize, double alpha, Size newImgSize=Size(),
 610                                             CV_OUT Rect* validPixROI=0, bool centerPrincipalPoint=false);
 611
 612 //! converts point coordinates from normal pixel coordinates to homogeneous coordinates ((x,y)->(x,y,1))
 613 CV_EXPORTS_W void convertPointsToHomogeneous( InputArray src, OutputArray dst );
 614
 615 //! converts point coordinates from homogeneous to normal pixel coordinates ((x,y,z)->(x/z, y/z))
 616 CV_EXPORTS_W void convertPointsFromHomogeneous( InputArray src, OutputArray dst );
 617
 618 //! for backward compatibility
 619 CV_EXPORTS void convertPointsHomogeneous( InputArray src, OutputArray dst );
 620
 621 //! the algorithm for finding fundamental matrix
 622 enum
 623 {
 624     FM_7POINT = CV_FM_7POINT, //!< 7-point algorithm
 625     FM_8POINT = CV_FM_8POINT, //!< 8-point algorithm
 626     FM_LMEDS = CV_FM_LMEDS,  //!< least-median algorithm
 627     FM_RANSAC = CV_FM_RANSAC  //!< RANSAC algorithm
 628 };
 629
 630 //! finds fundamental matrix from a set of corresponding 2D points
 631 CV_EXPORTS_W Mat findFundamentalMat( InputArray points1, InputArray points2,
 632                                      int method=FM_RANSAC,
 633                                      double param1=3., double param2=0.99,
 634                                      OutputArray mask=noArray());
 635
 636 //! variant of findFundamentalMat for backward compatibility
 637 CV_EXPORTS Mat findFundamentalMat( InputArray points1, InputArray points2,
 638                                    OutputArray mask, int method=FM_RANSAC,
 639                                    double param1=3., double param2=0.99);
 640
 641 //! finds coordinates of epipolar lines corresponding the specified points
 642 CV_EXPORTS void computeCorrespondEpilines( InputArray points,
 643                                            int whichImage, InputArray F,
 644                                            OutputArray lines );
 645
 646 CV_EXPORTS_W void triangulatePoints( InputArray projMatr1, InputArray projMatr2,
 647                                      InputArray projPoints1, InputArray projPoints2,
 648                                      OutputArray points4D );
 649
 650 CV_EXPORTS_W void correctMatches( InputArray F, InputArray points1, InputArray points2,
 651                                   OutputArray newPoints1, OutputArray newPoints2 );
 652
 653 template<> CV_EXPORTS void Ptr<CvStereoBMState>::delete_obj();
 654
 655 /*!
 656  Block Matching Stereo Correspondence Algorithm
 657
 658  The class implements BM stereo correspondence algorithm by K. Konolige.
 659 */
 660 class CV_EXPORTS_W StereoBM
 661 {
 662 public:
 663     enum { PREFILTER_NORMALIZED_RESPONSE = 0, PREFILTER_XSOBEL = 1,
 664         BASIC_PRESET=0, FISH_EYE_PRESET=1, NARROW_PRESET=2 };
 665
 666     //! the default constructor
 667     CV_WRAP StereoBM();
 668     //! the full constructor taking the camera-specific preset, number of disparities and the SAD window size
 669     CV_WRAP StereoBM(int preset, int ndisparities=0, int SADWindowSize=21);
 670     //! the method that reinitializes the state. The previous content is destroyed
 671     void init(int preset, int ndisparities=0, int SADWindowSize=21);
 672     //! the stereo correspondence operator. Finds the disparity for the specified rectified stereo pair
 673     CV_WRAP_AS(compute) void operator()( InputArray left, InputArray right,
 674                                          OutputArray disparity, int disptype=CV_16S );
 675
 676     //! pointer to the underlying CvStereoBMState
 677     Ptr<CvStereoBMState> state;
 678 };
 679
 680
 681 /*!
 682  Semi-Global Block Matching Stereo Correspondence Algorithm
 683
 684  The class implements the original SGBM stereo correspondence algorithm by H. Hirschmuller and some its modification.
 685  */
 686 class CV_EXPORTS_W StereoSGBM
 687 {
 688 public:
 689     enum { DISP_SHIFT=4, DISP_SCALE = (1<<DISP_SHIFT) };
 690
 691     //! the default constructor
 692     CV_WRAP StereoSGBM();
 693
 694     //! the full constructor taking all the necessary algorithm parameters
 695     CV_WRAP StereoSGBM(int minDisparity, int numDisparities, int SADWindowSize,
 696                int P1=0, int P2=0, int disp12MaxDiff=0,
 697                int preFilterCap=0, int uniquenessRatio=0,
 698                int speckleWindowSize=0, int speckleRange=0,
 699                bool fullDP=false);
 700     //! the destructor
 701     virtual ~StereoSGBM();
 702
 703     //! the stereo correspondence operator that computes disparity map for the specified rectified stereo pair
 704     CV_WRAP_AS(compute) virtual void operator()(InputArray left, InputArray right,
 705                                                 OutputArray disp);
 706
 707     CV_PROP_RW int minDisparity;
 708     CV_PROP_RW int numberOfDisparities;
 709     CV_PROP_RW int SADWindowSize;
 710     CV_PROP_RW int preFilterCap;
 711     CV_PROP_RW int uniquenessRatio;
 712     CV_PROP_RW int P1;
 713     CV_PROP_RW int P2;
 714     CV_PROP_RW int speckleWindowSize;
 715     CV_PROP_RW int speckleRange;
 716     CV_PROP_RW int disp12MaxDiff;
 717     CV_PROP_RW bool fullDP;
 718
 719 protected:
 720     Mat buffer;
 721 };
 722
 723 //! filters off speckles (small regions of incorrectly computed disparity)
 724 CV_EXPORTS_W void filterSpeckles( InputOutputArray img, double newVal, int maxSpeckleSize, double maxDiff,
 725                                   InputOutputArray buf=noArray() );
 726
 727 //! computes valid disparity ROI from the valid ROIs of the rectified images (that are returned by cv::stereoRectify())
 728 CV_EXPORTS_W Rect getValidDisparityROI( Rect roi1, Rect roi2,
 729                                         int minDisparity, int numberOfDisparities,
 730                                         int SADWindowSize );
 731
 732 //! validates disparity using the left-right check. The matrix "cost" should be computed by the stereo correspondence algorithm
 733 CV_EXPORTS_W void validateDisparity( InputOutputArray disparity, InputArray cost,
 734                                      int minDisparity, int numberOfDisparities,
 735                                      int disp12MaxDisp=1 );
 736
 737 //! reprojects disparity image to 3D: (x,y,d)->(X,Y,Z) using the matrix Q returned by cv::stereoRectify
 738 CV_EXPORTS_W void reprojectImageTo3D( InputArray disparity,
 739                                       OutputArray _3dImage, InputArray Q,
 740                                       bool handleMissingValues=false,
 741                                       int ddepth=-1 );
 742
 743 CV_EXPORTS_W  int estimateAffine3D(InputArray src, InputArray dst,
 744                                    OutputArray out, OutputArray inliers,
 745                                    double ransacThreshold=3, double confidence=0.99);
 746
 747 }
 748
 749 #endif
 750
 751 #endif