global_motion.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-2011, 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_VIDEOSTAB_GLOBAL_MOTION_HPP
00044 #define OPENCV_VIDEOSTAB_GLOBAL_MOTION_HPP
00045 
00046 #include <vector>
00047 #include <fstream>
00048 #include "opencv2/core.hpp"
00049 #include "opencv2/features2d.hpp"
00050 #include "opencv2/opencv_modules.hpp"
00051 #include "opencv2/videostab/optical_flow.hpp"
00052 #include "opencv2/videostab/motion_core.hpp"
00053 #include "opencv2/videostab/outlier_rejection.hpp"
00054 
00055 #ifdef HAVE_OPENCV_CUDAIMGPROC
00056 #  include "opencv2/cudaimgproc.hpp"
00057 #endif
00058 
00059 namespace cv
00060 {
00061 namespace videostab
00062 {
00063 
00064 //! @addtogroup videostab_motion
00065 //! @{
00066 
00067 /** @brief Estimates best global motion between two 2D point clouds in the least-squares sense.
00068 
00069 @note Works in-place and changes input point arrays.
00070 
00071 @param points0 Source set of 2D points (32F).
00072 @param points1 Destination set of 2D points (32F).
00073 @param model Motion model (up to MM_AFFINE).
00074 @param rmse Final root-mean-square error.
00075 @return 3x3 2D transformation matrix (32F).
00076  */
00077 CV_EXPORTS Mat estimateGlobalMotionLeastSquares(
00078         InputOutputArray points0, InputOutputArray points1, int model = MM_AFFINE,
00079         float *rmse = 0);
00080 
00081 /** @brief Estimates best global motion between two 2D point clouds robustly (using RANSAC method).
00082 
00083 @param points0 Source set of 2D points (32F).
00084 @param points1 Destination set of 2D points (32F).
00085 @param model Motion model. See cv::videostab::MotionModel.
00086 @param params RANSAC method parameters. See videostab::RansacParams.
00087 @param rmse Final root-mean-square error.
00088 @param ninliers Final number of inliers.
00089  */
00090 CV_EXPORTS Mat estimateGlobalMotionRansac(
00091         InputArray points0, InputArray points1, int model = MM_AFFINE,
00092         const RansacParams &params = RansacParams::default2dMotion (MM_AFFINE),
00093         float *rmse = 0, int *ninliers = 0);
00094 
00095 /** @brief Base class for all global motion estimation methods.
00096  */
00097 class CV_EXPORTS MotionEstimatorBase
00098 {
00099 public:
00100     virtual ~MotionEstimatorBase() {}
00101 
00102     /** @brief Sets motion model.
00103 
00104     @param val Motion model. See cv::videostab::MotionModel.
00105      */
00106     virtual void setMotionModel(MotionModel val) { motionModel_ = val; }
00107 
00108     /**
00109     @return Motion model. See cv::videostab::MotionModel.
00110     */
00111     virtual MotionModel motionModel () const { return motionModel_; }
00112 
00113     /** @brief Estimates global motion between two 2D point clouds.
00114 
00115     @param points0 Source set of 2D points (32F).
00116     @param points1 Destination set of 2D points (32F).
00117     @param ok Indicates whether motion was estimated successfully.
00118     @return 3x3 2D transformation matrix (32F).
00119      */
00120     virtual Mat estimate(InputArray points0, InputArray points1, bool *ok = 0) = 0;
00121 
00122 protected:
00123     MotionEstimatorBase(MotionModel model) { setMotionModel(model); }
00124 
00125 private:
00126     MotionModel motionModel_;
00127 };
00128 
00129 /** @brief Describes a robust RANSAC-based global 2D motion estimation method which minimizes L2 error.
00130  */
00131 class CV_EXPORTS MotionEstimatorRansacL2 : public MotionEstimatorBase
00132 {
00133 public:
00134     MotionEstimatorRansacL2(MotionModel model = MM_AFFINE);
00135 
00136     void setRansacParams(const RansacParams &val) { ransacParams_ = val; }
00137     RansacParams ransacParams() const { return ransacParams_; }
00138 
00139     void setMinInlierRatio(float val) { minInlierRatio_ = val; }
00140     float minInlierRatio() const { return minInlierRatio_; }
00141 
00142     virtual Mat estimate(InputArray points0, InputArray points1, bool *ok = 0);
00143 
00144 private:
00145     RansacParams ransacParams_;
00146     float minInlierRatio_;
00147 };
00148 
00149 /** @brief Describes a global 2D motion estimation method which minimizes L1 error.
00150 
00151 @note To be able to use this method you must build OpenCV with CLP library support. :
00152  */
00153 class CV_EXPORTS MotionEstimatorL1 : public MotionEstimatorBase
00154 {
00155 public:
00156     MotionEstimatorL1(MotionModel model = MM_AFFINE);
00157 
00158     virtual Mat estimate(InputArray points0, InputArray points1, bool *ok = 0);
00159 
00160 private:
00161     std::vector<double> obj_, collb_, colub_;
00162     std::vector<double> elems_, rowlb_, rowub_;
00163     std::vector<int> rows_, cols_;
00164 
00165     void set(int row, int col, double coef)
00166     {
00167         rows_.push_back(row);
00168         cols_.push_back(col);
00169         elems_.push_back(coef);
00170     }
00171 };
00172 
00173 /** @brief Base class for global 2D motion estimation methods which take frames as input.
00174  */
00175 class CV_EXPORTS ImageMotionEstimatorBase
00176 {
00177 public:
00178     virtual ~ImageMotionEstimatorBase() {}
00179 
00180     virtual void setMotionModel(MotionModel val) { motionModel_ = val; }
00181     virtual MotionModel motionModel() const { return motionModel_; }
00182 
00183     virtual Mat estimate(const Mat &frame0, const Mat &frame1, bool *ok = 0) = 0;
00184 
00185 protected:
00186     ImageMotionEstimatorBase(MotionModel model) { setMotionModel(model); }
00187 
00188 private:
00189     MotionModel motionModel_;
00190 };
00191 
00192 class CV_EXPORTS FromFileMotionReader : public ImageMotionEstimatorBase
00193 {
00194 public:
00195     FromFileMotionReader(const String &path);
00196 
00197     virtual Mat estimate(const Mat &frame0, const Mat &frame1, bool *ok = 0);
00198 
00199 private:
00200     std::ifstream file_;
00201 };
00202 
00203 class CV_EXPORTS ToFileMotionWriter : public ImageMotionEstimatorBase
00204 {
00205 public:
00206     ToFileMotionWriter(const String &path, Ptr<ImageMotionEstimatorBase>  estimator);
00207 
00208     virtual void setMotionModel(MotionModel val) { motionEstimator_->setMotionModel(val); }
00209     virtual MotionModel motionModel() const { return motionEstimator_->motionModel(); }
00210 
00211     virtual Mat estimate(const Mat &frame0, const Mat &frame1, bool *ok = 0);
00212 
00213 private:
00214     std::ofstream file_;
00215     Ptr<ImageMotionEstimatorBase> motionEstimator_;
00216 };
00217 
00218 /** @brief Describes a global 2D motion estimation method which uses keypoints detection and optical flow for
00219 matching.
00220  */
00221 class CV_EXPORTS KeypointBasedMotionEstimator : public ImageMotionEstimatorBase
00222 {
00223 public:
00224     KeypointBasedMotionEstimator(Ptr<MotionEstimatorBase>  estimator);
00225 
00226     virtual void setMotionModel(MotionModel val) { motionEstimator_->setMotionModel(val); }
00227     virtual MotionModel motionModel() const { return motionEstimator_->motionModel(); }
00228 
00229     void setDetector(Ptr<FeatureDetector>  val) { detector_ = val; }
00230     Ptr<FeatureDetector>  detector() const { return detector_; }
00231 
00232     void setOpticalFlowEstimator(Ptr<ISparseOptFlowEstimator>  val) { optFlowEstimator_ = val; }
00233     Ptr<ISparseOptFlowEstimator>  opticalFlowEstimator() const { return optFlowEstimator_; }
00234 
00235     void setOutlierRejector(Ptr<IOutlierRejector>  val) { outlierRejector_ = val; }
00236     Ptr<IOutlierRejector>  outlierRejector() const { return outlierRejector_; }
00237 
00238     virtual Mat estimate(const Mat &frame0, const Mat &frame1, bool *ok = 0);
00239 
00240 private:
00241     Ptr<MotionEstimatorBase>  motionEstimator_;
00242     Ptr<FeatureDetector>  detector_;
00243     Ptr<ISparseOptFlowEstimator>  optFlowEstimator_;
00244     Ptr<IOutlierRejector>  outlierRejector_;
00245 
00246     std::vector<uchar> status_;
00247     std::vector<KeyPoint> keypointsPrev_;
00248     std::vector<Point2f> pointsPrev_, points_;
00249     std::vector<Point2f> pointsPrevGood_, pointsGood_;
00250 };
00251 
00252 #if defined(HAVE_OPENCV_CUDAIMGPROC) && defined(HAVE_OPENCV_CUDAOPTFLOW)
00253 
00254 class CV_EXPORTS KeypointBasedMotionEstimatorGpu : public ImageMotionEstimatorBase
00255 {
00256 public:
00257     KeypointBasedMotionEstimatorGpu(Ptr<MotionEstimatorBase>  estimator);
00258 
00259     virtual void setMotionModel(MotionModel val) { motionEstimator_->setMotionModel(val); }
00260     virtual MotionModel motionModel() const { return motionEstimator_->motionModel(); }
00261 
00262     void setOutlierRejector(Ptr<IOutlierRejector> val) { outlierRejector_ = val; }
00263     Ptr<IOutlierRejector> outlierRejector() const { return outlierRejector_; }
00264 
00265     virtual Mat estimate(const Mat &frame0, const Mat &frame1, bool *ok = 0);
00266     Mat estimate(const cuda::GpuMat &frame0, const cuda::GpuMat &frame1, bool *ok = 0);
00267 
00268 private:
00269     Ptr<MotionEstimatorBase> motionEstimator_;
00270     Ptr<cuda::CornersDetector> detector_;
00271     SparsePyrLkOptFlowEstimatorGpu optFlowEstimator_;
00272     Ptr<IOutlierRejector> outlierRejector_;
00273 
00274     cuda::GpuMat frame0_, grayFrame0_, frame1_;
00275     cuda::GpuMat pointsPrev_, points_;
00276     cuda::GpuMat status_;
00277 
00278     Mat hostPointsPrev_, hostPoints_;
00279     std::vector<Point2f> hostPointsPrevTmp_, hostPointsTmp_;
00280     std::vector<uchar> rejectionStatus_;
00281 };
00282 
00283 #endif // defined(HAVE_OPENCV_CUDAIMGPROC) && defined(HAVE_OPENCV_CUDAOPTFLOW)
00284 
00285 /** @brief Computes motion between two frames assuming that all the intermediate motions are known.
00286 
00287 @param from Source frame index.
00288 @param to Destination frame index.
00289 @param motions Pair-wise motions. motions[i] denotes motion from the frame i to the frame i+1
00290 @return Motion from the frame from to the frame to.
00291  */
00292 CV_EXPORTS Mat getMotion(int from, int to, const std::vector<Mat> &motions);
00293 
00294 //! @}
00295 
00296 } // namespace videostab
00297 } // namespace cv
00298 
00299 #endif