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 Base class for all camera parameters refinement methods.
00113  */
00114 class CV_EXPORTS BundleAdjusterBase : public Estimator
00115 {
00116 public:
00117     const Mat refinementMask() const { return refinement_mask_.clone(); }
00118     void setRefinementMask(const Mat &mask)
00119     {
00120         CV_Assert(mask.type() == CV_8U && mask.size() == Size(3, 3));
00121         refinement_mask_ = mask.clone();
00122     }
00123 
00124     double confThresh() const { return conf_thresh_; }
00125     void setConfThresh(double conf_thresh) { conf_thresh_ = conf_thresh; }
00126 
00127     TermCriteria termCriteria() { return term_criteria_; }
00128     void setTermCriteria(const TermCriteria& term_criteria) { term_criteria_ = term_criteria; }
00129 
00130 protected:
00131     /** @brief Construct a bundle adjuster base instance.
00132 
00133     @param num_params_per_cam Number of parameters per camera
00134     @param num_errs_per_measurement Number of error terms (components) per match
00135      */
00136     BundleAdjusterBase(int num_params_per_cam, int num_errs_per_measurement)
00137         : num_params_per_cam_(num_params_per_cam),
00138           num_errs_per_measurement_(num_errs_per_measurement)
00139     {
00140         setRefinementMask(Mat::ones(3, 3, CV_8U));
00141         setConfThresh(1.);
00142         setTermCriteria(TermCriteria(TermCriteria::EPS + TermCriteria::COUNT, 1000, DBL_EPSILON));
00143     }
00144 
00145     // Runs bundle adjustment
00146     virtual bool estimate(const std::vector<ImageFeatures> &features,
00147                           const std::vector<MatchesInfo> &pairwise_matches,
00148                           std::vector<CameraParams> &cameras);
00149 
00150     /** @brief Sets initial camera parameter to refine.
00151 
00152     @param cameras Camera parameters
00153      */
00154     virtual void setUpInitialCameraParams(const std::vector<CameraParams> &cameras) = 0;
00155     /** @brief Gets the refined camera parameters.
00156 
00157     @param cameras Refined camera parameters
00158      */
00159     virtual void obtainRefinedCameraParams(std::vector<CameraParams> &cameras) const = 0;
00160     /** @brief Calculates error vector.
00161 
00162     @param err Error column-vector of length total_num_matches \* num_errs_per_measurement
00163      */
00164     virtual void calcError(Mat &err) = 0;
00165     /** @brief Calculates the cost function jacobian.
00166 
00167     @param jac Jacobian matrix of dimensions
00168     (total_num_matches \* num_errs_per_measurement) x (num_images \* num_params_per_cam)
00169      */
00170     virtual void calcJacobian(Mat &jac) = 0;
00171 
00172     // 3x3 8U mask, where 0 means don't refine respective parameter, != 0 means refine
00173     Mat refinement_mask_;
00174 
00175     int num_images_;
00176     int total_num_matches_;
00177 
00178     int num_params_per_cam_;
00179     int num_errs_per_measurement_;
00180 
00181     const ImageFeatures *features_;
00182     const MatchesInfo *pairwise_matches_;
00183 
00184     // Threshold to filter out poorly matched image pairs
00185     double conf_thresh_;
00186 
00187     //Levenberg–Marquardt algorithm termination criteria
00188     TermCriteria term_criteria_;
00189 
00190     // Camera parameters matrix (CV_64F)
00191     Mat cam_params_;
00192 
00193     // Connected images pairs
00194     std::vector<std::pair<int,int> > edges_;
00195 };
00196 
00197 
00198 /** @brief Implementation of the camera parameters refinement algorithm which minimizes sum of the reprojection
00199 error squares
00200 
00201 It can estimate focal length, aspect ratio, principal point.
00202 You can affect only on them via the refinement mask.
00203  */
00204 class CV_EXPORTS BundleAdjusterReproj : public BundleAdjusterBase
00205 {
00206 public:
00207     BundleAdjusterReproj() : BundleAdjusterBase(7, 2) {}
00208 
00209 private:
00210     void setUpInitialCameraParams(const std::vector<CameraParams> &cameras);
00211     void obtainRefinedCameraParams(std::vector<CameraParams> &cameras) const;
00212     void calcError(Mat &err);
00213     void calcJacobian(Mat &jac);
00214 
00215     Mat err1_, err2_;
00216 };
00217 
00218 
00219 /** @brief Implementation of the camera parameters refinement algorithm which minimizes sum of the distances
00220 between the rays passing through the camera center and a feature. :
00221 
00222 It can estimate focal length. It ignores the refinement mask for now.
00223  */
00224 class CV_EXPORTS BundleAdjusterRay : public BundleAdjusterBase
00225 {
00226 public:
00227     BundleAdjusterRay() : BundleAdjusterBase(4, 3) {}
00228 
00229 private:
00230     void setUpInitialCameraParams(const std::vector<CameraParams> &cameras);
00231     void obtainRefinedCameraParams(std::vector<CameraParams> &cameras) const;
00232     void calcError(Mat &err);
00233     void calcJacobian(Mat &jac);
00234 
00235     Mat err1_, err2_;
00236 };
00237 
00238 
00239 enum WaveCorrectKind
00240 {
00241     WAVE_CORRECT_HORIZ,
00242     WAVE_CORRECT_VERT
00243 };
00244 
00245 /** @brief Tries to make panorama more horizontal (or vertical).
00246 
00247 @param rmats Camera rotation matrices.
00248 @param kind Correction kind, see detail::WaveCorrectKind.
00249  */
00250 void CV_EXPORTS waveCorrect(std::vector<Mat> &rmats, WaveCorrectKind kind);
00251 
00252 
00253 //////////////////////////////////////////////////////////////////////////////
00254 // Auxiliary functions
00255 
00256 // Returns matches graph representation in DOT language
00257 String CV_EXPORTS matchesGraphAsString(std::vector<String> &pathes, std::vector<MatchesInfo> &pairwise_matches,
00258                                             float conf_threshold);
00259 
00260 std::vector<int> CV_EXPORTS leaveBiggestComponent(
00261         std::vector<ImageFeatures> &features,
00262         std::vector<MatchesInfo> &pairwise_matches,
00263         float conf_threshold);
00264 
00265 void CV_EXPORTS findMaxSpanningTree(
00266         int num_images, const std::vector<MatchesInfo> &pairwise_matches,
00267         Graph &span_tree, std::vector<int> &centers);
00268 
00269 //! @} stitching_rotation
00270 
00271 } // namespace detail
00272 } // namespace cv
00273 
00274 #endif // __OPENCV_STITCHING_MOTION_ESTIMATORS_HPP__
00275