calib3d_c.h

00001 /*M///////////////////////////////////////////////////////////////////////////////////////
00002 //
00003 //  IMPORTANT: READ BEFORE DOWNLOADING, COPYING, INSTALLING OR USING.
00004 //
00005 //  By downloading, copying, installing or using the software you agree to this license.
00006 //  If you do not agree to this license, do not download, install,
00007 //  copy or use the software.
00008 //
00009 //
00010 //                          License Agreement
00011 //                For Open Source Computer Vision Library
00012 //
00013 // Copyright (C) 2000-2008, Intel Corporation, all rights reserved.
00014 // Copyright (C) 2009, Willow Garage Inc., all rights reserved.
00015 // Copyright (C) 2013, OpenCV Foundation, all rights reserved.
00016 // Third party copyrights are property of their respective owners.
00017 //
00018 // Redistribution and use in source and binary forms, with or without modification,
00019 // are permitted provided that the following conditions are met:
00020 //
00021 //   * Redistribution's of source code must retain the above copyright notice,
00022 //     this list of conditions and the following disclaimer.
00023 //
00024 //   * Redistribution's in binary form must reproduce the above copyright notice,
00025 //     this list of conditions and the following disclaimer in the documentation
00026 //     and/or other materials provided with the distribution.
00027 //
00028 //   * The name of the copyright holders may not be used to endorse or promote products
00029 //     derived from this software without specific prior written permission.
00030 //
00031 // This software is provided by the copyright holders and contributors "as is" and
00032 // any express or implied warranties, including, but not limited to, the implied
00033 // warranties of merchantability and fitness for a particular purpose are disclaimed.
00034 // In no event shall the Intel Corporation or contributors be liable for any direct,
00035 // indirect, incidental, special, exemplary, or consequential damages
00036 // (including, but not limited to, procurement of substitute goods or services;
00037 // loss of use, data, or profits; or business interruption) however caused
00038 // and on any theory of liability, whether in contract, strict liability,
00039 // or tort (including negligence or otherwise) arising in any way out of
00040 // the use of this software, even if advised of the possibility of such damage.
00041 //
00042 //M*/
00043 
00044 #ifndef OPENCV_CALIB3D_C_H
00045 #define OPENCV_CALIB3D_C_H
00046 
00047 #include "opencv2/core/core_c.h"
00048 
00049 #ifdef __cplusplus
00050 extern "C" {
00051 #endif
00052 
00053 /** @addtogroup calib3d_c
00054   @{
00055   */
00056 
00057 /****************************************************************************************\
00058 *                      Camera Calibration, Pose Estimation and Stereo                    *
00059 \****************************************************************************************/
00060 
00061 typedef struct CvPOSITObject CvPOSITObject;
00062 
00063 /* Allocates and initializes CvPOSITObject structure before doing cvPOSIT */
00064 CVAPI(CvPOSITObject*)  cvCreatePOSITObject( CvPoint3D32f* points, int point_count );
00065 
00066 
00067 /* Runs POSIT (POSe from ITeration) algorithm for determining 3d position of
00068    an object given its model and projection in a weak-perspective case */
00069 CVAPI(void)  cvPOSIT(  CvPOSITObject* posit_object, CvPoint2D32f* image_points,
00070                        double focal_length, CvTermCriteria  criteria,
00071                        float* rotation_matrix, float* translation_vector);
00072 
00073 /* Releases CvPOSITObject structure */
00074 CVAPI(void)  cvReleasePOSITObject( CvPOSITObject**  posit_object );
00075 
00076 /* updates the number of RANSAC iterations */
00077 CVAPI(int) cvRANSACUpdateNumIters( double p, double err_prob,
00078                                    int model_points, int max_iters );
00079 
00080 CVAPI(void) cvConvertPointsHomogeneous( const CvMat* src, CvMat* dst );
00081 
00082 /* Calculates fundamental matrix given a set of corresponding points */
00083 #define CV_FM_7POINT 1
00084 #define CV_FM_8POINT 2
00085 
00086 #define CV_LMEDS 4
00087 #define CV_RANSAC 8
00088 
00089 #define CV_FM_LMEDS_ONLY  CV_LMEDS
00090 #define CV_FM_RANSAC_ONLY CV_RANSAC
00091 #define CV_FM_LMEDS CV_LMEDS
00092 #define CV_FM_RANSAC CV_RANSAC
00093 
00094 enum
00095 {
00096     CV_ITERATIVE = 0,
00097     CV_EPNP = 1, // F.Moreno-Noguer, V.Lepetit and P.Fua "EPnP: Efficient Perspective-n-Point Camera Pose Estimation"
00098     CV_P3P = 2, // X.S. Gao, X.-R. Hou, J. Tang, H.-F. Chang; "Complete Solution Classification for the Perspective-Three-Point Problem"
00099     CV_DLS = 3 // Joel A. Hesch and Stergios I. Roumeliotis. "A Direct Least-Squares (DLS) Method for PnP"
00100 };
00101 
00102 CVAPI(int) cvFindFundamentalMat( const CvMat* points1, const CvMat* points2,
00103                                  CvMat* fundamental_matrix,
00104                                  int method CV_DEFAULT(CV_FM_RANSAC),
00105                                  double param1 CV_DEFAULT(3.), double param2 CV_DEFAULT(0.99),
00106                                  CvMat* status CV_DEFAULT(NULL) );
00107 
00108 /* For each input point on one of images
00109    computes parameters of the corresponding
00110    epipolar line on the other image */
00111 CVAPI(void) cvComputeCorrespondEpilines( const CvMat* points,
00112                                          int which_image,
00113                                          const CvMat* fundamental_matrix,
00114                                          CvMat* correspondent_lines );
00115 
00116 /* Triangulation functions */
00117 
00118 CVAPI(void) cvTriangulatePoints(CvMat* projMatr1, CvMat* projMatr2,
00119                                 CvMat* projPoints1, CvMat* projPoints2,
00120                                 CvMat* points4D);
00121 
00122 CVAPI(void) cvCorrectMatches(CvMat* F, CvMat* points1, CvMat* points2,
00123                              CvMat* new_points1, CvMat* new_points2);
00124 
00125 
00126 /* Computes the optimal new camera matrix according to the free scaling parameter alpha:
00127    alpha=0 - only valid pixels will be retained in the undistorted image
00128    alpha=1 - all the source image pixels will be retained in the undistorted image
00129 */
00130 CVAPI(void) cvGetOptimalNewCameraMatrix( const CvMat* camera_matrix,
00131                                          const CvMat* dist_coeffs,
00132                                          CvSize image_size, double alpha,
00133                                          CvMat* new_camera_matrix,
00134                                          CvSize new_imag_size CV_DEFAULT(cvSize(0,0)),
00135                                          CvRect * valid_pixel_ROI CV_DEFAULT(0),
00136                                          int center_principal_point CV_DEFAULT(0));
00137 
00138 /* Converts rotation vector to rotation matrix or vice versa */
00139 CVAPI(int) cvRodrigues2( const CvMat* src, CvMat* dst,
00140                          CvMat* jacobian CV_DEFAULT(0) );
00141 
00142 /* Finds perspective transformation between the object plane and image (view) plane */
00143 CVAPI(int) cvFindHomography( const CvMat* src_points,
00144                              const CvMat* dst_points,
00145                              CvMat* homography,
00146                              int method CV_DEFAULT(0),
00147                              double ransacReprojThreshold CV_DEFAULT(3),
00148                              CvMat* mask CV_DEFAULT(0),
00149                              int maxIters CV_DEFAULT(2000),
00150                              double confidence CV_DEFAULT(0.995));
00151 
00152 /* Computes RQ decomposition for 3x3 matrices */
00153 CVAPI(void) cvRQDecomp3x3( const CvMat *matrixM, CvMat *matrixR, CvMat *matrixQ,
00154                            CvMat *matrixQx CV_DEFAULT(NULL),
00155                            CvMat *matrixQy CV_DEFAULT(NULL),
00156                            CvMat *matrixQz CV_DEFAULT(NULL),
00157                            CvPoint3D64f *eulerAngles CV_DEFAULT(NULL));
00158 
00159 /* Computes projection matrix decomposition */
00160 CVAPI(void) cvDecomposeProjectionMatrix( const CvMat *projMatr, CvMat *calibMatr,
00161                                          CvMat *rotMatr, CvMat *posVect,
00162                                          CvMat *rotMatrX CV_DEFAULT(NULL),
00163                                          CvMat *rotMatrY CV_DEFAULT(NULL),
00164                                          CvMat *rotMatrZ CV_DEFAULT(NULL),
00165                                          CvPoint3D64f *eulerAngles CV_DEFAULT(NULL));
00166 
00167 /* Computes d(AB)/dA and d(AB)/dB */
00168 CVAPI(void) cvCalcMatMulDeriv( const CvMat* A, const CvMat* B, CvMat* dABdA, CvMat* dABdB );
00169 
00170 /* Computes r3 = rodrigues(rodrigues(r2)*rodrigues(r1)),
00171    t3 = rodrigues(r2)*t1 + t2 and the respective derivatives */
00172 CVAPI(void) cvComposeRT( const CvMat* _rvec1, const CvMat* _tvec1,
00173                          const CvMat* _rvec2, const CvMat* _tvec2,
00174                          CvMat* _rvec3, CvMat* _tvec3,
00175                          CvMat* dr3dr1 CV_DEFAULT(0), CvMat* dr3dt1 CV_DEFAULT(0),
00176                          CvMat* dr3dr2 CV_DEFAULT(0), CvMat* dr3dt2 CV_DEFAULT(0),
00177                          CvMat* dt3dr1 CV_DEFAULT(0), CvMat* dt3dt1 CV_DEFAULT(0),
00178                          CvMat* dt3dr2 CV_DEFAULT(0), CvMat* dt3dt2 CV_DEFAULT(0) );
00179 
00180 /* Projects object points to the view plane using
00181    the specified extrinsic and intrinsic camera parameters */
00182 CVAPI(void) cvProjectPoints2( const CvMat* object_points, const CvMat* rotation_vector,
00183                               const CvMat* translation_vector, const CvMat* camera_matrix,
00184                               const CvMat* distortion_coeffs, CvMat* image_points,
00185                               CvMat* dpdrot CV_DEFAULT(NULL), CvMat* dpdt CV_DEFAULT(NULL),
00186                               CvMat* dpdf CV_DEFAULT(NULL), CvMat* dpdc CV_DEFAULT(NULL),
00187                               CvMat* dpddist CV_DEFAULT(NULL),
00188                               double aspect_ratio CV_DEFAULT(0));
00189 
00190 /* Finds extrinsic camera parameters from
00191    a few known corresponding point pairs and intrinsic parameters */
00192 CVAPI(void) cvFindExtrinsicCameraParams2( const CvMat* object_points,
00193                                           const CvMat* image_points,
00194                                           const CvMat* camera_matrix,
00195                                           const CvMat* distortion_coeffs,
00196                                           CvMat* rotation_vector,
00197                                           CvMat* translation_vector,
00198                                           int use_extrinsic_guess CV_DEFAULT(0) );
00199 
00200 /* Computes initial estimate of the intrinsic camera parameters
00201    in case of planar calibration target (e.g. chessboard) */
00202 CVAPI(void) cvInitIntrinsicParams2D( const CvMat* object_points,
00203                                      const CvMat* image_points,
00204                                      const CvMat* npoints, CvSize image_size,
00205                                      CvMat* camera_matrix,
00206                                      double aspect_ratio CV_DEFAULT(1.) );
00207 
00208 #define CV_CALIB_CB_ADAPTIVE_THRESH  1
00209 #define CV_CALIB_CB_NORMALIZE_IMAGE  2
00210 #define CV_CALIB_CB_FILTER_QUADS     4
00211 #define CV_CALIB_CB_FAST_CHECK       8
00212 
00213 // Performs a fast check if a chessboard is in the input image. This is a workaround to
00214 // a problem of cvFindChessboardCorners being slow on images with no chessboard
00215 // - src: input image
00216 // - size: chessboard size
00217 // Returns 1 if a chessboard can be in this image and findChessboardCorners should be called,
00218 // 0 if there is no chessboard, -1 in case of error
00219 CVAPI(int) cvCheckChessboard(IplImage* src, CvSize size);
00220 
00221     /* Detects corners on a chessboard calibration pattern */
00222 CVAPI(int) cvFindChessboardCorners( const void* image, CvSize pattern_size,
00223                                     CvPoint2D32f* corners,
00224                                     int* corner_count CV_DEFAULT(NULL),
00225                                     int flags CV_DEFAULT(CV_CALIB_CB_ADAPTIVE_THRESH+CV_CALIB_CB_NORMALIZE_IMAGE) );
00226 
00227 /* Draws individual chessboard corners or the whole chessboard detected */
00228 CVAPI(void) cvDrawChessboardCorners( CvArr* image, CvSize pattern_size,
00229                                      CvPoint2D32f* corners,
00230                                      int count, int pattern_was_found );
00231 
00232 #define CV_CALIB_USE_INTRINSIC_GUESS  1
00233 #define CV_CALIB_FIX_ASPECT_RATIO     2
00234 #define CV_CALIB_FIX_PRINCIPAL_POINT  4
00235 #define CV_CALIB_ZERO_TANGENT_DIST    8
00236 #define CV_CALIB_FIX_FOCAL_LENGTH 16
00237 #define CV_CALIB_FIX_K1  32
00238 #define CV_CALIB_FIX_K2  64
00239 #define CV_CALIB_FIX_K3  128
00240 #define CV_CALIB_FIX_K4  2048
00241 #define CV_CALIB_FIX_K5  4096
00242 #define CV_CALIB_FIX_K6  8192
00243 #define CV_CALIB_RATIONAL_MODEL 16384
00244 #define CV_CALIB_THIN_PRISM_MODEL 32768
00245 #define CV_CALIB_FIX_S1_S2_S3_S4  65536
00246 #define CV_CALIB_TILTED_MODEL  262144
00247 #define CV_CALIB_FIX_TAUX_TAUY  524288
00248 
00249 #define CV_CALIB_NINTRINSIC 18
00250 
00251 /* Finds intrinsic and extrinsic camera parameters
00252    from a few views of known calibration pattern */
00253 CVAPI(double) cvCalibrateCamera2( const CvMat* object_points,
00254                                 const CvMat* image_points,
00255                                 const CvMat* point_counts,
00256                                 CvSize image_size,
00257                                 CvMat* camera_matrix,
00258                                 CvMat* distortion_coeffs,
00259                                 CvMat* rotation_vectors CV_DEFAULT(NULL),
00260                                 CvMat* translation_vectors CV_DEFAULT(NULL),
00261                                 int flags CV_DEFAULT(0),
00262                                 CvTermCriteria  term_crit CV_DEFAULT(cvTermCriteria(
00263                                     CV_TERMCRIT_ITER+CV_TERMCRIT_EPS,30,DBL_EPSILON)) );
00264 
00265 /* Computes various useful characteristics of the camera from the data computed by
00266    cvCalibrateCamera2 */
00267 CVAPI(void) cvCalibrationMatrixValues( const CvMat *camera_matrix,
00268                                 CvSize image_size,
00269                                 double aperture_width CV_DEFAULT(0),
00270                                 double aperture_height CV_DEFAULT(0),
00271                                 double *fovx CV_DEFAULT(NULL),
00272                                 double *fovy CV_DEFAULT(NULL),
00273                                 double *focal_length CV_DEFAULT(NULL),
00274                                 CvPoint2D64f *principal_point CV_DEFAULT(NULL),
00275                                 double *pixel_aspect_ratio CV_DEFAULT(NULL));
00276 
00277 #define CV_CALIB_FIX_INTRINSIC  256
00278 #define CV_CALIB_SAME_FOCAL_LENGTH 512
00279 
00280 /* Computes the transformation from one camera coordinate system to another one
00281    from a few correspondent views of the same calibration target. Optionally, calibrates
00282    both cameras */
00283 CVAPI(double) cvStereoCalibrate( const CvMat* object_points, const CvMat* image_points1,
00284                                const CvMat* image_points2, const CvMat* npoints,
00285                                CvMat* camera_matrix1, CvMat* dist_coeffs1,
00286                                CvMat* camera_matrix2, CvMat* dist_coeffs2,
00287                                CvSize image_size, CvMat* R, CvMat* T,
00288                                CvMat* E CV_DEFAULT(0), CvMat* F CV_DEFAULT(0),
00289                                int flags CV_DEFAULT(CV_CALIB_FIX_INTRINSIC),
00290                                CvTermCriteria  term_crit CV_DEFAULT(cvTermCriteria(
00291                                    CV_TERMCRIT_ITER+CV_TERMCRIT_EPS,30,1e-6)) );
00292 
00293 #define CV_CALIB_ZERO_DISPARITY 1024
00294 
00295 /* Computes 3D rotations (+ optional shift) for each camera coordinate system to make both
00296    views parallel (=> to make all the epipolar lines horizontal or vertical) */
00297 CVAPI(void) cvStereoRectify( const CvMat* camera_matrix1, const CvMat* camera_matrix2,
00298                              const CvMat* dist_coeffs1, const CvMat* dist_coeffs2,
00299                              CvSize image_size, const CvMat* R, const CvMat* T,
00300                              CvMat* R1, CvMat* R2, CvMat* P1, CvMat* P2,
00301                              CvMat* Q CV_DEFAULT(0),
00302                              int flags CV_DEFAULT(CV_CALIB_ZERO_DISPARITY),
00303                              double alpha CV_DEFAULT(-1),
00304                              CvSize new_image_size CV_DEFAULT(cvSize(0,0)),
00305                              CvRect * valid_pix_ROI1 CV_DEFAULT(0),
00306                              CvRect * valid_pix_ROI2 CV_DEFAULT(0));
00307 
00308 /* Computes rectification transformations for uncalibrated pair of images using a set
00309    of point correspondences */
00310 CVAPI(int) cvStereoRectifyUncalibrated( const CvMat* points1, const CvMat* points2,
00311                                         const CvMat* F, CvSize img_size,
00312                                         CvMat* H1, CvMat* H2,
00313                                         double threshold CV_DEFAULT(5));
00314 
00315 
00316 
00317 /* stereo correspondence parameters and functions */
00318 
00319 #define CV_STEREO_BM_NORMALIZED_RESPONSE  0
00320 #define CV_STEREO_BM_XSOBEL               1
00321 
00322 /* Block matching algorithm structure */
00323 typedef struct CvStereoBMState
00324 {
00325     // pre-filtering (normalization of input images)
00326     int preFilterType; // =CV_STEREO_BM_NORMALIZED_RESPONSE now
00327     int preFilterSize; // averaging window size: ~5x5..21x21
00328     int preFilterCap; // the output of pre-filtering is clipped by [-preFilterCap,preFilterCap]
00329 
00330     // correspondence using Sum of Absolute Difference (SAD)
00331     int SADWindowSize; // ~5x5..21x21
00332     int minDisparity;  // minimum disparity (can be negative)
00333     int numberOfDisparities; // maximum disparity - minimum disparity (> 0)
00334 
00335     // post-filtering
00336     int textureThreshold;  // the disparity is only computed for pixels
00337                            // with textured enough neighborhood
00338     int uniquenessRatio;   // accept the computed disparity d* only if
00339                            // SAD(d) >= SAD(d*)*(1 + uniquenessRatio/100.)
00340                            // for any d != d*+/-1 within the search range.
00341     int speckleWindowSize; // disparity variation window
00342     int speckleRange; // acceptable range of variation in window
00343 
00344     int trySmallerWindows; // if 1, the results may be more accurate,
00345                            // at the expense of slower processing
00346     CvRect  roi1, roi2;
00347     int disp12MaxDiff;
00348 
00349     // temporary buffers
00350     CvMat* preFilteredImg0;
00351     CvMat* preFilteredImg1;
00352     CvMat* slidingSumBuf;
00353     CvMat* cost;
00354     CvMat* disp;
00355 } CvStereoBMState;
00356 
00357 #define CV_STEREO_BM_BASIC 0
00358 #define CV_STEREO_BM_FISH_EYE 1
00359 #define CV_STEREO_BM_NARROW 2
00360 
00361 CVAPI(CvStereoBMState*) cvCreateStereoBMState(int preset CV_DEFAULT(CV_STEREO_BM_BASIC),
00362                                               int numberOfDisparities CV_DEFAULT(0));
00363 
00364 CVAPI(void) cvReleaseStereoBMState( CvStereoBMState** state );
00365 
00366 CVAPI(void) cvFindStereoCorrespondenceBM( const CvArr* left, const CvArr* right,
00367                                           CvArr* disparity, CvStereoBMState* state );
00368 
00369 CVAPI(CvRect ) cvGetValidDisparityROI( CvRect  roi1, CvRect  roi2, int minDisparity,
00370                                       int numberOfDisparities, int SADWindowSize );
00371 
00372 CVAPI(void) cvValidateDisparity( CvArr* disparity, const CvArr* cost,
00373                                  int minDisparity, int numberOfDisparities,
00374                                  int disp12MaxDiff CV_DEFAULT(1) );
00375 
00376 /* Reprojects the computed disparity image to the 3D space using the specified 4x4 matrix */
00377 CVAPI(void)  cvReprojectImageTo3D( const CvArr* disparityImage,
00378                                    CvArr* _3dImage, const CvMat* Q,
00379                                    int handleMissingValues CV_DEFAULT(0) );
00380 
00381 /** @} calib3d_c */
00382 
00383 #ifdef __cplusplus
00384 } // extern "C"
00385 
00386 //////////////////////////////////////////////////////////////////////////////////////////
00387 class CV_EXPORTS CvLevMarq
00388 {
00389 public:
00390     CvLevMarq();
00391     CvLevMarq( int nparams, int nerrs, CvTermCriteria  criteria=
00392               cvTermCriteria(CV_TERMCRIT_EPS+CV_TERMCRIT_ITER,30,DBL_EPSILON),
00393               bool completeSymmFlag=false );
00394     ~CvLevMarq();
00395     void init( int nparams, int nerrs, CvTermCriteria  criteria=
00396               cvTermCriteria(CV_TERMCRIT_EPS+CV_TERMCRIT_ITER,30,DBL_EPSILON),
00397               bool completeSymmFlag=false );
00398     bool update( const CvMat*& param, CvMat*& J, CvMat*& err );
00399     bool updateAlt( const CvMat*& param, CvMat*& JtJ, CvMat*& JtErr, double*& errNorm );
00400 
00401     void clear();
00402     void step();
00403     enum { DONE=0, STARTED=1, CALC_J=2, CHECK_ERR=3 };
00404 
00405     cv::Ptr<CvMat>  mask;
00406     cv::Ptr<CvMat>  prevParam;
00407     cv::Ptr<CvMat>  param;
00408     cv::Ptr<CvMat>  J;
00409     cv::Ptr<CvMat>  err;
00410     cv::Ptr<CvMat>  JtJ;
00411     cv::Ptr<CvMat>  JtJN;
00412     cv::Ptr<CvMat>  JtErr;
00413     cv::Ptr<CvMat>  JtJV;
00414     cv::Ptr<CvMat>  JtJW;
00415     double prevErrNorm, errNorm;
00416     int lambdaLg10;
00417     CvTermCriteria  criteria;
00418     int state;
00419     int iters;
00420     bool completeSymmFlag;
00421     int solveMethod;
00422 };
00423 
00424 #endif
00425 
00426 #endif /* OPENCV_CALIB3D_C_H */