motion_estimators.hpp

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 // Third party copyrights are property of their respective owners.
00016 //
00017 // Redistribution and use in source and binary forms, with or without modification,
00018 // are permitted provided that the following conditions are met:
00019 //
00020 //   * Redistribution's of source code must retain the above copyright notice,
00021 //     this list of conditions and the following disclaimer.
00022 //
00023 //   * Redistribution's in binary form must reproduce the above copyright notice,
00024 //     this list of conditions and the following disclaimer in the documentation
00025 //     and/or other materials provided with the distribution.
00026 //
00027 //   * The name of the copyright holders may not be used to endorse or promote products
00028 //     derived from this software without specific prior written permission.
00029 //
00030 // This software is provided by the copyright holders and contributors "as is" and
00031 // any express or implied warranties, including, but not limited to, the implied
00032 // warranties of merchantability and fitness for a particular purpose are disclaimed.
00033 // In no event shall the Intel Corporation or contributors be liable for any direct,
00034 // indirect, incidental, special, exemplary, or consequential damages
00035 // (including, but not limited to, procurement of substitute goods or services;
00036 // loss of use, data, or profits; or business interruption) however caused
00037 // and on any theory of liability, whether in contract, strict liability,
00038 // or tort (including negligence or otherwise) arising in any way out of
00039 // the use of this software, even if advised of the possibility of such damage.
00040 //
00041 //M*/
00042 
00043 #ifndef OPENCV_STITCHING_MOTION_ESTIMATORS_HPP
00044 #define OPENCV_STITCHING_MOTION_ESTIMATORS_HPP
00045 
00046 #include "opencv2/core.hpp"
00047 #include "matchers.hpp"
00048 #include "util.hpp"
00049 #include "camera.hpp"
00050 
00051 namespace cv {
00052 namespace detail {
00053 
00054 //! @addtogroup stitching_rotation
00055 //! @{
00056 
00057 /** @brief Rotation estimator base class.
00058 
00059 It takes features of all images, pairwise matches between all images and estimates rotations of all
00060 cameras.
00061 
00062 @note The coordinate system origin is implementation-dependent, but you can always normalize the
00063 rotations in respect to the first camera, for instance. :
00064  */
00065 class CV_EXPORTS Estimator
00066 {
00067 public:
00068     virtual ~Estimator() {}
00069 
00070     /** @brief Estimates camera parameters.
00071 
00072     @param features Features of images
00073     @param pairwise_matches Pairwise matches of images
00074     @param cameras Estimated camera parameters
00075     @return True in case of success, false otherwise
00076      */
00077     bool operator ()(const std::vector<ImageFeatures> &features,
00078                      const std::vector<MatchesInfo> &pairwise_matches,
00079                      std::vector<CameraParams> &cameras)
00080         { return estimate(features, pairwise_matches, cameras); }
00081 
00082 protected:
00083     /** @brief This method must implement camera parameters estimation logic in order to make the wrapper
00084     detail::Estimator::operator()_ work.
00085 
00086     @param features Features of images
00087     @param pairwise_matches Pairwise matches of images
00088     @param cameras Estimated camera parameters
00089     @return True in case of success, false otherwise
00090      */
00091     virtual bool estimate(const std::vector<ImageFeatures> &features,
00092                           const std::vector<MatchesInfo> &pairwise_matches,
00093                           std::vector<CameraParams> &cameras) = 0;
00094 };
00095 
00096 /** @brief Homography based rotation estimator.
00097  */
00098 class CV_EXPORTS HomographyBasedEstimator : public Estimator
00099 {
00100 public:
00101     HomographyBasedEstimator(bool is_focals_estimated = false)
00102         : is_focals_estimated_(is_focals_estimated) {}
00103 
00104 private:
00105     virtual bool estimate(const std::vector<ImageFeatures> &features,
00106                           const std::vector<MatchesInfo> &pairwise_matches,
00107                           std::vector<CameraParams> &cameras);
00108 
00109     bool is_focals_estimated_;
00110 };
00111 
00112 /** @brief Affine transformation based estimator.
00113 
00114 This estimator uses pairwise tranformations estimated by matcher to estimate
00115 final transformation for each camera.
00116 
00117 @sa cv::detail::HomographyBasedEstimator
00118  */
00119 class CV_EXPORTS AffineBasedEstimator : public Estimator
00120 {
00121 private:
00122     virtual bool estimate(const std::vector<ImageFeatures> &features,
00123                           const std::vector<MatchesInfo> &pairwise_matches,
00124                           std::vector<CameraParams> &cameras);
00125 };
00126 
00127 /** @brief Base class for all camera parameters refinement methods.
00128  */
00129 class CV_EXPORTS BundleAdjusterBase : public Estimator
00130 {
00131 public:
00132     const Mat refinementMask() const { return refinement_mask_.clone(); }
00133     void setRefinementMask(const Mat &mask)
00134     {
00135         CV_Assert(mask.type() == CV_8U && mask.size() == Size(3, 3));
00136         refinement_mask_ = mask.clone();
00137     }
00138 
00139     double confThresh() const { return conf_thresh_; }
00140     void setConfThresh(double conf_thresh) { conf_thresh_ = conf_thresh; }
00141 
00142     TermCriteria termCriteria() { return term_criteria_; }
00143     void setTermCriteria(const TermCriteria& term_criteria) { term_criteria_ = term_criteria; }
00144 
00145 protected:
00146     /** @brief Construct a bundle adjuster base instance.
00147 
00148     @param num_params_per_cam Number of parameters per camera
00149     @param num_errs_per_measurement Number of error terms (components) per match
00150      */
00151     BundleAdjusterBase(int num_params_per_cam, int num_errs_per_measurement)
00152         : num_params_per_cam_(num_params_per_cam),
00153           num_errs_per_measurement_(num_errs_per_measurement)
00154     {
00155         setRefinementMask(Mat::ones(3, 3, CV_8U));
00156         setConfThresh(1.);
00157         setTermCriteria(TermCriteria(TermCriteria::EPS + TermCriteria::COUNT, 1000, DBL_EPSILON));
00158     }
00159 
00160     // Runs bundle adjustment
00161     virtual bool estimate(const std::vector<ImageFeatures> &features,
00162                           const std::vector<MatchesInfo> &pairwise_matches,
00163                           std::vector<CameraParams> &cameras);
00164 
00165     /** @brief Sets initial camera parameter to refine.
00166 
00167     @param cameras Camera parameters
00168      */
00169     virtual void setUpInitialCameraParams(const std::vector<CameraParams> &cameras) = 0;
00170     /** @brief Gets the refined camera parameters.
00171 
00172     @param cameras Refined camera parameters
00173      */
00174     virtual void obtainRefinedCameraParams(std::vector<CameraParams> &cameras) const = 0;
00175     /** @brief Calculates error vector.
00176 
00177     @param err Error column-vector of length total_num_matches \* num_errs_per_measurement
00178      */
00179     virtual void calcError(Mat &err) = 0;
00180     /** @brief Calculates the cost function jacobian.
00181 
00182     @param jac Jacobian matrix of dimensions
00183     (total_num_matches \* num_errs_per_measurement) x (num_images \* num_params_per_cam)
00184      */
00185     virtual void calcJacobian(Mat &jac) = 0;
00186 
00187     // 3x3 8U mask, where 0 means don't refine respective parameter, != 0 means refine
00188     Mat refinement_mask_;
00189 
00190     int num_images_;
00191     int total_num_matches_;
00192 
00193     int num_params_per_cam_;
00194     int num_errs_per_measurement_;
00195 
00196     const ImageFeatures *features_;
00197     const MatchesInfo *pairwise_matches_;
00198 
00199     // Threshold to filter out poorly matched image pairs
00200     double conf_thresh_;
00201 
00202     //Levenberg–Marquardt algorithm termination criteria
00203     TermCriteria term_criteria_;
00204 
00205     // Camera parameters matrix (CV_64F)
00206     Mat cam_params_;
00207 
00208     // Connected images pairs
00209     std::vector<std::pair<int,int> > edges_;
00210 };
00211 
00212 
00213 /** @brief Stub bundle adjuster that does nothing.
00214  */
00215 class CV_EXPORTS NoBundleAdjuster : public BundleAdjusterBase
00216 {
00217 public:
00218     NoBundleAdjuster() : BundleAdjusterBase(0, 0) {}
00219 
00220 private:
00221     bool estimate(const std::vector<ImageFeatures> &, const std::vector<MatchesInfo> &,
00222                   std::vector<CameraParams> &)
00223     {
00224         return true;
00225     }
00226     void setUpInitialCameraParams(const std::vector<CameraParams> &) {}
00227     void obtainRefinedCameraParams(std::vector<CameraParams> &) const {}
00228     void calcError(Mat &) {}
00229     void calcJacobian(Mat &) {}
00230 };
00231 
00232 
00233 /** @brief Implementation of the camera parameters refinement algorithm which minimizes sum of the reprojection
00234 error squares
00235 
00236 It can estimate focal length, aspect ratio, principal point.
00237 You can affect only on them via the refinement mask.
00238  */
00239 class CV_EXPORTS BundleAdjusterReproj : public BundleAdjusterBase
00240 {
00241 public:
00242     BundleAdjusterReproj() : BundleAdjusterBase(7, 2) {}
00243 
00244 private:
00245     void setUpInitialCameraParams(const std::vector<CameraParams> &cameras);
00246     void obtainRefinedCameraParams(std::vector<CameraParams> &cameras) const;
00247     void calcError(Mat &err);
00248     void calcJacobian(Mat &jac);
00249 
00250     Mat err1_, err2_;
00251 };
00252 
00253 
00254 /** @brief Implementation of the camera parameters refinement algorithm which minimizes sum of the distances
00255 between the rays passing through the camera center and a feature. :
00256 
00257 It can estimate focal length. It ignores the refinement mask for now.
00258  */
00259 class CV_EXPORTS BundleAdjusterRay : public BundleAdjusterBase
00260 {
00261 public:
00262     BundleAdjusterRay() : BundleAdjusterBase(4, 3) {}
00263 
00264 private:
00265     void setUpInitialCameraParams(const std::vector<CameraParams> &cameras);
00266     void obtainRefinedCameraParams(std::vector<CameraParams> &cameras) const;
00267     void calcError(Mat &err);
00268     void calcJacobian(Mat &jac);
00269 
00270     Mat err1_, err2_;
00271 };
00272 
00273 
00274 /** @brief Bundle adjuster that expects affine transformation
00275 represented in homogeneous coordinates in R for each camera param. Implements
00276 camera parameters refinement algorithm which minimizes sum of the reprojection
00277 error squares
00278 
00279 It estimates all transformation parameters. Refinement mask is ignored.
00280 
00281 @sa AffineBasedEstimator AffineBestOf2NearestMatcher BundleAdjusterAffinePartial
00282  */
00283 class CV_EXPORTS BundleAdjusterAffine : public BundleAdjusterBase
00284 {
00285 public:
00286     BundleAdjusterAffine() : BundleAdjusterBase(6, 2) {}
00287 
00288 private:
00289     void setUpInitialCameraParams(const std::vector<CameraParams> &cameras);
00290     void obtainRefinedCameraParams(std::vector<CameraParams> &cameras) const;
00291     void calcError(Mat &err);
00292     void calcJacobian(Mat &jac);
00293 
00294     Mat err1_, err2_;
00295 };
00296 
00297 
00298 /** @brief Bundle adjuster that expects affine transformation with 4 DOF
00299 represented in homogeneous coordinates in R for each camera param. Implements
00300 camera parameters refinement algorithm which minimizes sum of the reprojection
00301 error squares
00302 
00303 It estimates all transformation parameters. Refinement mask is ignored.
00304 
00305 @sa AffineBasedEstimator AffineBestOf2NearestMatcher BundleAdjusterAffine
00306  */
00307 class CV_EXPORTS BundleAdjusterAffinePartial : public BundleAdjusterBase
00308 {
00309 public:
00310     BundleAdjusterAffinePartial() : BundleAdjusterBase(4, 2) {}
00311 
00312 private:
00313     void setUpInitialCameraParams(const std::vector<CameraParams> &cameras);
00314     void obtainRefinedCameraParams(std::vector<CameraParams> &cameras) const;
00315     void calcError(Mat &err);
00316     void calcJacobian(Mat &jac);
00317 
00318     Mat err1_, err2_;
00319 };
00320 
00321 
00322 enum WaveCorrectKind
00323 {
00324     WAVE_CORRECT_HORIZ,
00325     WAVE_CORRECT_VERT
00326 };
00327 
00328 /** @brief Tries to make panorama more horizontal (or vertical).
00329 
00330 @param rmats Camera rotation matrices.
00331 @param kind Correction kind, see detail::WaveCorrectKind.
00332  */
00333 void CV_EXPORTS waveCorrect(std::vector<Mat> &rmats, WaveCorrectKind kind);
00334 
00335 
00336 //////////////////////////////////////////////////////////////////////////////
00337 // Auxiliary functions
00338 
00339 // Returns matches graph representation in DOT language
00340 String CV_EXPORTS matchesGraphAsString(std::vector<String> &pathes, std::vector<MatchesInfo> &pairwise_matches,
00341                                             float conf_threshold);
00342 
00343 std::vector<int> CV_EXPORTS leaveBiggestComponent(
00344         std::vector<ImageFeatures> &features,
00345         std::vector<MatchesInfo> &pairwise_matches,
00346         float conf_threshold);
00347 
00348 void CV_EXPORTS findMaxSpanningTree(
00349         int num_images, const std::vector<MatchesInfo> &pairwise_matches,
00350         Graph &span_tree, std::vector<int> &centers);
00351 
00352 //! @} stitching_rotation
00353 
00354 } // namespace detail
00355 } // namespace cv
00356 
00357 #endif // OPENCV_STITCHING_MOTION_ESTIMATORS_HPP