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// Copyright (C) 2013, OpenCV Foundation, all rights reserved.
16// Third party copyrights are property of their respective owners.
17//
18// Redistribution and use in source and binary forms, with or without modification,
19// are permitted provided that the following conditions are met:
20//
21//   * Redistribution's of source code must retain the above copyright notice,
22//     this list of conditions and the following disclaimer.
23//
24//   * Redistribution's in binary form must reproduce the above copyright notice,
25//     this list of conditions and the following disclaimer in the documentation
26//     and/or other materials provided with the distribution.
27//
28//   * The name of the copyright holders may not be used to endorse or promote products
29//     derived from this software without specific prior written permission.
30//
31// This software is provided by the copyright holders and contributors "as is" and
32// any express or implied warranties, including, but not limited to, the implied
33// warranties of merchantability and fitness for a particular purpose are disclaimed.
34// In no event shall the Intel Corporation or contributors be liable for any direct,
35// indirect, incidental, special, exemplary, or consequential damages
36// (including, but not limited to, procurement of substitute goods or services;
37// loss of use, data, or profits; or business interruption) however caused
38// and on any theory of liability, whether in contract, strict liability,
39// or tort (including negligence or otherwise) arising in any way out of
40// the use of this software, even if advised of the possibility of such damage.
41//
42//M*/
43
44#ifndef __OPENCV_CALIB3D_C_H__
45#define __OPENCV_CALIB3D_C_H__
46
47#include "opencv2/core/core_c.h"
48
49#ifdef __cplusplus
50extern "C" {
51#endif
52
53/** @addtogroup calib3d_c
54  @{
55  */
56
57/****************************************************************************************\
58*                      Camera Calibration, Pose Estimation and Stereo                    *
59\****************************************************************************************/
60
61typedef struct CvPOSITObject CvPOSITObject;
62
63/* Allocates and initializes CvPOSITObject structure before doing cvPOSIT */
64CVAPI(CvPOSITObject*)  cvCreatePOSITObject( CvPoint3D32f* points, int point_count );
65
66
67/* Runs POSIT (POSe from ITeration) algorithm for determining 3d position of
68   an object given its model and projection in a weak-perspective case */
69CVAPI(void)  cvPOSIT(  CvPOSITObject* posit_object, CvPoint2D32f* image_points,
70                       double focal_length, CvTermCriteria criteria,
71                       float* rotation_matrix, float* translation_vector);
72
73/* Releases CvPOSITObject structure */
74CVAPI(void)  cvReleasePOSITObject( CvPOSITObject**  posit_object );
75
76/* updates the number of RANSAC iterations */
77CVAPI(int) cvRANSACUpdateNumIters( double p, double err_prob,
78                                   int model_points, int max_iters );
79
80CVAPI(void) cvConvertPointsHomogeneous( const CvMat* src, CvMat* dst );
81
82/* Calculates fundamental matrix given a set of corresponding points */
83#define CV_FM_7POINT 1
84#define CV_FM_8POINT 2
85
86#define CV_LMEDS 4
87#define CV_RANSAC 8
88
89#define CV_FM_LMEDS_ONLY  CV_LMEDS
90#define CV_FM_RANSAC_ONLY CV_RANSAC
91#define CV_FM_LMEDS CV_LMEDS
92#define CV_FM_RANSAC CV_RANSAC
93
94enum
95{
96    CV_ITERATIVE = 0,
97    CV_EPNP = 1, // F.Moreno-Noguer, V.Lepetit and P.Fua "EPnP: Efficient Perspective-n-Point Camera Pose Estimation"
98    CV_P3P = 2, // X.S. Gao, X.-R. Hou, J. Tang, H.-F. Chang; "Complete Solution Classification for the Perspective-Three-Point Problem"
99    CV_DLS = 3 // Joel A. Hesch and Stergios I. Roumeliotis. "A Direct Least-Squares (DLS) Method for PnP"
100};
101
102CVAPI(int) cvFindFundamentalMat( const CvMat* points1, const CvMat* points2,
103                                 CvMat* fundamental_matrix,
104                                 int method CV_DEFAULT(CV_FM_RANSAC),
105                                 double param1 CV_DEFAULT(3.), double param2 CV_DEFAULT(0.99),
106                                 CvMat* status CV_DEFAULT(NULL) );
107
108/* For each input point on one of images
109   computes parameters of the corresponding
110   epipolar line on the other image */
111CVAPI(void) cvComputeCorrespondEpilines( const CvMat* points,
112                                         int which_image,
113                                         const CvMat* fundamental_matrix,
114                                         CvMat* correspondent_lines );
115
116/* Triangulation functions */
117
118CVAPI(void) cvTriangulatePoints(CvMat* projMatr1, CvMat* projMatr2,
119                                CvMat* projPoints1, CvMat* projPoints2,
120                                CvMat* points4D);
121
122CVAPI(void) cvCorrectMatches(CvMat* F, CvMat* points1, CvMat* points2,
123                             CvMat* new_points1, CvMat* new_points2);
124
125
126/* Computes the optimal new camera matrix according to the free scaling parameter alpha:
127   alpha=0 - only valid pixels will be retained in the undistorted image
128   alpha=1 - all the source image pixels will be retained in the undistorted image
129*/
130CVAPI(void) cvGetOptimalNewCameraMatrix( const CvMat* camera_matrix,
131                                         const CvMat* dist_coeffs,
132                                         CvSize image_size, double alpha,
133                                         CvMat* new_camera_matrix,
134                                         CvSize new_imag_size CV_DEFAULT(cvSize(0,0)),
135                                         CvRect* valid_pixel_ROI CV_DEFAULT(0),
136                                         int center_principal_point CV_DEFAULT(0));
137
138/* Converts rotation vector to rotation matrix or vice versa */
139CVAPI(int) cvRodrigues2( const CvMat* src, CvMat* dst,
140                         CvMat* jacobian CV_DEFAULT(0) );
141
142/* Finds perspective transformation between the object plane and image (view) plane */
143CVAPI(int) cvFindHomography( const CvMat* src_points,
144                             const CvMat* dst_points,
145                             CvMat* homography,
146                             int method CV_DEFAULT(0),
147                             double ransacReprojThreshold CV_DEFAULT(3),
148                             CvMat* mask CV_DEFAULT(0),
149                             int maxIters CV_DEFAULT(2000),
150                             double confidence CV_DEFAULT(0.995));
151
152/* Computes RQ decomposition for 3x3 matrices */
153CVAPI(void) cvRQDecomp3x3( const CvMat *matrixM, CvMat *matrixR, CvMat *matrixQ,
154                           CvMat *matrixQx CV_DEFAULT(NULL),
155                           CvMat *matrixQy CV_DEFAULT(NULL),
156                           CvMat *matrixQz CV_DEFAULT(NULL),
157                           CvPoint3D64f *eulerAngles CV_DEFAULT(NULL));
158
159/* Computes projection matrix decomposition */
160CVAPI(void) cvDecomposeProjectionMatrix( const CvMat *projMatr, CvMat *calibMatr,
161                                         CvMat *rotMatr, CvMat *posVect,
162                                         CvMat *rotMatrX CV_DEFAULT(NULL),
163                                         CvMat *rotMatrY CV_DEFAULT(NULL),
164                                         CvMat *rotMatrZ CV_DEFAULT(NULL),
165                                         CvPoint3D64f *eulerAngles CV_DEFAULT(NULL));
166
167/* Computes d(AB)/dA and d(AB)/dB */
168CVAPI(void) cvCalcMatMulDeriv( const CvMat* A, const CvMat* B, CvMat* dABdA, CvMat* dABdB );
169
170/* Computes r3 = rodrigues(rodrigues(r2)*rodrigues(r1)),
171   t3 = rodrigues(r2)*t1 + t2 and the respective derivatives */
172CVAPI(void) cvComposeRT( const CvMat* _rvec1, const CvMat* _tvec1,
173                         const CvMat* _rvec2, const CvMat* _tvec2,
174                         CvMat* _rvec3, CvMat* _tvec3,
175                         CvMat* dr3dr1 CV_DEFAULT(0), CvMat* dr3dt1 CV_DEFAULT(0),
176                         CvMat* dr3dr2 CV_DEFAULT(0), CvMat* dr3dt2 CV_DEFAULT(0),
177                         CvMat* dt3dr1 CV_DEFAULT(0), CvMat* dt3dt1 CV_DEFAULT(0),
178                         CvMat* dt3dr2 CV_DEFAULT(0), CvMat* dt3dt2 CV_DEFAULT(0) );
179
180/* Projects object points to the view plane using
181   the specified extrinsic and intrinsic camera parameters */
182CVAPI(void) cvProjectPoints2( const CvMat* object_points, const CvMat* rotation_vector,
183                              const CvMat* translation_vector, const CvMat* camera_matrix,
184                              const CvMat* distortion_coeffs, CvMat* image_points,
185                              CvMat* dpdrot CV_DEFAULT(NULL), CvMat* dpdt CV_DEFAULT(NULL),
186                              CvMat* dpdf CV_DEFAULT(NULL), CvMat* dpdc CV_DEFAULT(NULL),
187                              CvMat* dpddist CV_DEFAULT(NULL),
188                              double aspect_ratio CV_DEFAULT(0));
189
190/* Finds extrinsic camera parameters from
191   a few known corresponding point pairs and intrinsic parameters */
192CVAPI(void) cvFindExtrinsicCameraParams2( const CvMat* object_points,
193                                          const CvMat* image_points,
194                                          const CvMat* camera_matrix,
195                                          const CvMat* distortion_coeffs,
196                                          CvMat* rotation_vector,
197                                          CvMat* translation_vector,
198                                          int use_extrinsic_guess CV_DEFAULT(0) );
199
200/* Computes initial estimate of the intrinsic camera parameters
201   in case of planar calibration target (e.g. chessboard) */
202CVAPI(void) cvInitIntrinsicParams2D( const CvMat* object_points,
203                                     const CvMat* image_points,
204                                     const CvMat* npoints, CvSize image_size,
205                                     CvMat* camera_matrix,
206                                     double aspect_ratio CV_DEFAULT(1.) );
207
208#define CV_CALIB_CB_ADAPTIVE_THRESH  1
209#define CV_CALIB_CB_NORMALIZE_IMAGE  2
210#define CV_CALIB_CB_FILTER_QUADS     4
211#define CV_CALIB_CB_FAST_CHECK       8
212
213// Performs a fast check if a chessboard is in the input image. This is a workaround to
214// a problem of cvFindChessboardCorners being slow on images with no chessboard
215// - src: input image
216// - size: chessboard size
217// Returns 1 if a chessboard can be in this image and findChessboardCorners should be called,
218// 0 if there is no chessboard, -1 in case of error
219CVAPI(int) cvCheckChessboard(IplImage* src, CvSize size);
220
221    /* Detects corners on a chessboard calibration pattern */
222CVAPI(int) cvFindChessboardCorners( const void* image, CvSize pattern_size,
223                                    CvPoint2D32f* corners,
224                                    int* corner_count CV_DEFAULT(NULL),
225                                    int flags CV_DEFAULT(CV_CALIB_CB_ADAPTIVE_THRESH+CV_CALIB_CB_NORMALIZE_IMAGE) );
226
227/* Draws individual chessboard corners or the whole chessboard detected */
228CVAPI(void) cvDrawChessboardCorners( CvArr* image, CvSize pattern_size,
229                                     CvPoint2D32f* corners,
230                                     int count, int pattern_was_found );
231
232#define CV_CALIB_USE_INTRINSIC_GUESS  1
233#define CV_CALIB_FIX_ASPECT_RATIO     2
234#define CV_CALIB_FIX_PRINCIPAL_POINT  4
235#define CV_CALIB_ZERO_TANGENT_DIST    8
236#define CV_CALIB_FIX_FOCAL_LENGTH 16
237#define CV_CALIB_FIX_K1  32
238#define CV_CALIB_FIX_K2  64
239#define CV_CALIB_FIX_K3  128
240#define CV_CALIB_FIX_K4  2048
241#define CV_CALIB_FIX_K5  4096
242#define CV_CALIB_FIX_K6  8192
243#define CV_CALIB_RATIONAL_MODEL 16384
244#define CV_CALIB_THIN_PRISM_MODEL 32768
245#define CV_CALIB_FIX_S1_S2_S3_S4  65536
246
247
248/* Finds intrinsic and extrinsic camera parameters
249   from a few views of known calibration pattern */
250CVAPI(double) cvCalibrateCamera2( const CvMat* object_points,
251                                const CvMat* image_points,
252                                const CvMat* point_counts,
253                                CvSize image_size,
254                                CvMat* camera_matrix,
255                                CvMat* distortion_coeffs,
256                                CvMat* rotation_vectors CV_DEFAULT(NULL),
257                                CvMat* translation_vectors CV_DEFAULT(NULL),
258                                int flags CV_DEFAULT(0),
259                                CvTermCriteria term_crit CV_DEFAULT(cvTermCriteria(
260                                    CV_TERMCRIT_ITER+CV_TERMCRIT_EPS,30,DBL_EPSILON)) );
261
262/* Computes various useful characteristics of the camera from the data computed by
263   cvCalibrateCamera2 */
264CVAPI(void) cvCalibrationMatrixValues( const CvMat *camera_matrix,
265                                CvSize image_size,
266                                double aperture_width CV_DEFAULT(0),
267                                double aperture_height CV_DEFAULT(0),
268                                double *fovx CV_DEFAULT(NULL),
269                                double *fovy CV_DEFAULT(NULL),
270                                double *focal_length CV_DEFAULT(NULL),
271                                CvPoint2D64f *principal_point CV_DEFAULT(NULL),
272                                double *pixel_aspect_ratio CV_DEFAULT(NULL));
273
274#define CV_CALIB_FIX_INTRINSIC  256
275#define CV_CALIB_SAME_FOCAL_LENGTH 512
276
277/* Computes the transformation from one camera coordinate system to another one
278   from a few correspondent views of the same calibration target. Optionally, calibrates
279   both cameras */
280CVAPI(double) cvStereoCalibrate( const CvMat* object_points, const CvMat* image_points1,
281                               const CvMat* image_points2, const CvMat* npoints,
282                               CvMat* camera_matrix1, CvMat* dist_coeffs1,
283                               CvMat* camera_matrix2, CvMat* dist_coeffs2,
284                               CvSize image_size, CvMat* R, CvMat* T,
285                               CvMat* E CV_DEFAULT(0), CvMat* F CV_DEFAULT(0),
286                               int flags CV_DEFAULT(CV_CALIB_FIX_INTRINSIC),
287                               CvTermCriteria term_crit CV_DEFAULT(cvTermCriteria(
288                                   CV_TERMCRIT_ITER+CV_TERMCRIT_EPS,30,1e-6)) );
289
290#define CV_CALIB_ZERO_DISPARITY 1024
291
292/* Computes 3D rotations (+ optional shift) for each camera coordinate system to make both
293   views parallel (=> to make all the epipolar lines horizontal or vertical) */
294CVAPI(void) cvStereoRectify( const CvMat* camera_matrix1, const CvMat* camera_matrix2,
295                             const CvMat* dist_coeffs1, const CvMat* dist_coeffs2,
296                             CvSize image_size, const CvMat* R, const CvMat* T,
297                             CvMat* R1, CvMat* R2, CvMat* P1, CvMat* P2,
298                             CvMat* Q CV_DEFAULT(0),
299                             int flags CV_DEFAULT(CV_CALIB_ZERO_DISPARITY),
300                             double alpha CV_DEFAULT(-1),
301                             CvSize new_image_size CV_DEFAULT(cvSize(0,0)),
302                             CvRect* valid_pix_ROI1 CV_DEFAULT(0),
303                             CvRect* valid_pix_ROI2 CV_DEFAULT(0));
304
305/* Computes rectification transformations for uncalibrated pair of images using a set
306   of point correspondences */
307CVAPI(int) cvStereoRectifyUncalibrated( const CvMat* points1, const CvMat* points2,
308                                        const CvMat* F, CvSize img_size,
309                                        CvMat* H1, CvMat* H2,
310                                        double threshold CV_DEFAULT(5));
311
312
313
314/* stereo correspondence parameters and functions */
315
316#define CV_STEREO_BM_NORMALIZED_RESPONSE  0
317#define CV_STEREO_BM_XSOBEL               1
318
319/* Block matching algorithm structure */
320typedef struct CvStereoBMState
321{
322    // pre-filtering (normalization of input images)
323    int preFilterType; // =CV_STEREO_BM_NORMALIZED_RESPONSE now
324    int preFilterSize; // averaging window size: ~5x5..21x21
325    int preFilterCap; // the output of pre-filtering is clipped by [-preFilterCap,preFilterCap]
326
327    // correspondence using Sum of Absolute Difference (SAD)
328    int SADWindowSize; // ~5x5..21x21
329    int minDisparity;  // minimum disparity (can be negative)
330    int numberOfDisparities; // maximum disparity - minimum disparity (> 0)
331
332    // post-filtering
333    int textureThreshold;  // the disparity is only computed for pixels
334                           // with textured enough neighborhood
335    int uniquenessRatio;   // accept the computed disparity d* only if
336                           // SAD(d) >= SAD(d*)*(1 + uniquenessRatio/100.)
337                           // for any d != d*+/-1 within the search range.
338    int speckleWindowSize; // disparity variation window
339    int speckleRange; // acceptable range of variation in window
340
341    int trySmallerWindows; // if 1, the results may be more accurate,
342                           // at the expense of slower processing
343    CvRect roi1, roi2;
344    int disp12MaxDiff;
345
346    // temporary buffers
347    CvMat* preFilteredImg0;
348    CvMat* preFilteredImg1;
349    CvMat* slidingSumBuf;
350    CvMat* cost;
351    CvMat* disp;
352} CvStereoBMState;
353
354#define CV_STEREO_BM_BASIC 0
355#define CV_STEREO_BM_FISH_EYE 1
356#define CV_STEREO_BM_NARROW 2
357
358CVAPI(CvStereoBMState*) cvCreateStereoBMState(int preset CV_DEFAULT(CV_STEREO_BM_BASIC),
359                                              int numberOfDisparities CV_DEFAULT(0));
360
361CVAPI(void) cvReleaseStereoBMState( CvStereoBMState** state );
362
363CVAPI(void) cvFindStereoCorrespondenceBM( const CvArr* left, const CvArr* right,
364                                          CvArr* disparity, CvStereoBMState* state );
365
366CVAPI(CvRect) cvGetValidDisparityROI( CvRect roi1, CvRect roi2, int minDisparity,
367                                      int numberOfDisparities, int SADWindowSize );
368
369CVAPI(void) cvValidateDisparity( CvArr* disparity, const CvArr* cost,
370                                 int minDisparity, int numberOfDisparities,
371                                 int disp12MaxDiff CV_DEFAULT(1) );
372
373/* Reprojects the computed disparity image to the 3D space using the specified 4x4 matrix */
374CVAPI(void)  cvReprojectImageTo3D( const CvArr* disparityImage,
375                                   CvArr* _3dImage, const CvMat* Q,
376                                   int handleMissingValues CV_DEFAULT(0) );
377
378/** @} calib3d_c */
379
380#ifdef __cplusplus
381} // extern "C"
382
383//////////////////////////////////////////////////////////////////////////////////////////
384class CV_EXPORTS CvLevMarq
385{
386public:
387    CvLevMarq();
388    CvLevMarq( int nparams, int nerrs, CvTermCriteria criteria=
389              cvTermCriteria(CV_TERMCRIT_EPS+CV_TERMCRIT_ITER,30,DBL_EPSILON),
390              bool completeSymmFlag=false );
391    ~CvLevMarq();
392    void init( int nparams, int nerrs, CvTermCriteria criteria=
393              cvTermCriteria(CV_TERMCRIT_EPS+CV_TERMCRIT_ITER,30,DBL_EPSILON),
394              bool completeSymmFlag=false );
395    bool update( const CvMat*& param, CvMat*& J, CvMat*& err );
396    bool updateAlt( const CvMat*& param, CvMat*& JtJ, CvMat*& JtErr, double*& errNorm );
397
398    void clear();
399    void step();
400    enum { DONE=0, STARTED=1, CALC_J=2, CHECK_ERR=3 };
401
402    cv::Ptr<CvMat> mask;
403    cv::Ptr<CvMat> prevParam;
404    cv::Ptr<CvMat> param;
405    cv::Ptr<CvMat> J;
406    cv::Ptr<CvMat> err;
407    cv::Ptr<CvMat> JtJ;
408    cv::Ptr<CvMat> JtJN;
409    cv::Ptr<CvMat> JtErr;
410    cv::Ptr<CvMat> JtJV;
411    cv::Ptr<CvMat> JtJW;
412    double prevErrNorm, errNorm;
413    int lambdaLg10;
414    CvTermCriteria criteria;
415    int state;
416    int iters;
417    bool completeSymmFlag;
418};
419
420#endif
421
422#endif /* __OPENCV_CALIB3D_C_H__ */
423