modules/videostab/doc/global_motion.rst

   1 Global Motion Estimation
   2 ========================
   3
   4 .. highlight:: cpp
   5
   6 The video stabilization module contains a set of functions and classes for global motion estimation between point clouds or between images. In the last case  features are extracted and matched internally. For the sake of convenience the motion estimation functions are wrapped into classes. Both the functions and the classes are available.
   7
   8 videostab::MotionModel
   9 ----------------------
  10
  11 .. ocv:class:: videostab::MotionModel
  12
  13 Describes motion model between two point clouds.
  14
  15 ::
  16
  17     enum MotionModel
  18     {
  19         MM_TRANSLATION = 0,
  20         MM_TRANSLATION_AND_SCALE = 1,
  21         MM_ROTATION = 2,
  22         MM_RIGID = 3,
  23         MM_SIMILARITY = 4,
  24         MM_AFFINE = 5,
  25         MM_HOMOGRAPHY = 6,
  26         MM_UNKNOWN = 7
  27     };
  28
  29
  30 videostab::RansacParams
  31 -----------------------
  32
  33 .. ocv:class:: videostab::RansacParams
  34
  35 Describes RANSAC method parameters.
  36
  37 ::
  38
  39     struct CV_EXPORTS RansacParams
  40     {
  41         int size; // subset size
  42         float thresh; // max error to classify as inlier
  43         float eps; // max outliers ratio
  44         float prob; // probability of success
  45
  46         RansacParams() : size(0), thresh(0), eps(0), prob(0) {}
  47         RansacParams(int size, float thresh, float eps, float prob);
  48
  49         int niters() const;
  50
  51         static RansacParams default2dMotion(MotionModel model);
  52     };
  53
  54
  55 videostab::RansacParams::RansacParams
  56 -------------------------------------
  57
  58 .. ocv:function:: RansacParams::RansacParams()
  59
  60     :return: RANSAC method empty parameters object.
  61
  62
  63 videostab::RansacParams::RansacParams
  64 -------------------------------------
  65
  66 .. ocv:function:: RansacParams::RansacParams(int size, float thresh, float eps, float prob)
  67
  68     :param size: Subset size.
  69
  70     :param thresh: Maximum re-projection error value to classify as inlier.
  71
  72     :param eps: Maximum ratio of incorrect correspondences.
  73
  74     :param prob: Required success probability.
  75
  76     :return: RANSAC method parameters object.
  77
  78
  79 videostab::RansacParams::niters
  80 -------------------------------
  81
  82 .. ocv:function:: int RansacParams::niters() const
  83
  84     :return: Number of iterations that'll be performed by RANSAC method.
  85
  86
  87 videostab::RansacParams::default2dMotion
  88 ----------------------------------------
  89
  90 .. ocv:function:: static RansacParams RansacParams::default2dMotion(MotionModel model)
  91
  92     :param model: Motion model. See :ocv:class:`videostab::MotionModel`.
  93
  94     :return: Default RANSAC method parameters for the given motion model.
  95
  96
  97 videostab::estimateGlobalMotionLeastSquares
  98 -------------------------------------------
  99
 100 Estimates best global motion between two 2D point clouds in the least-squares sense.
 101
 102 .. note:: Works in-place and changes input point arrays.
 103
 104 .. ocv:function:: Mat estimateGlobalMotionLeastSquares(InputOutputArray points0, InputOutputArray points1, int model = MM_AFFINE, float *rmse = 0)
 105
 106     :param points0: Source set of 2D points (``32F``).
 107
 108     :param points1: Destination set of 2D points (``32F``).
 109
 110     :param model: Motion model (up to ``MM_AFFINE``).
 111
 112     :param rmse: Final root-mean-square error.
 113
 114     :return: 3x3 2D transformation matrix (``32F``).
 115
 116
 117 videostab::estimateGlobalMotionRansac
 118 -------------------------------------
 119
 120 Estimates best global motion between two 2D point clouds robustly (using RANSAC method).
 121
 122 .. ocv:function:: Mat estimateGlobalMotionRansac(InputArray points0, InputArray points1, int model = MM_AFFINE, const RansacParams &params = RansacParams::default2dMotion(MM_AFFINE), float *rmse = 0, int *ninliers = 0)
 123
 124     :param points0: Source set of 2D points (``32F``).
 125
 126     :param points1: Destination set of 2D points (``32F``).
 127
 128     :param model: Motion model. See :ocv:class:`videostab::MotionModel`.
 129
 130     :param params: RANSAC method parameters. See :ocv:class:`videostab::RansacParams`.
 131
 132     :param rmse: Final root-mean-square error.
 133
 134     :param ninliers: Final number of inliers.
 135
 136
 137 videostab::getMotion
 138 --------------------
 139
 140 Computes motion between two frames assuming that all the intermediate motions are known.
 141
 142 .. ocv:function:: Mat getMotion(int from, int to, const std::vector<Mat> &motions)
 143
 144     :param from: Source frame index.
 145
 146     :param to: Destination frame index.
 147
 148     :param motions: Pair-wise motions. ``motions[i]`` denotes motion from the frame ``i`` to the frame ``i+1``
 149
 150     :return: Motion from the frame ``from`` to the frame ``to``.
 151
 152
 153 videostab::MotionEstimatorBase
 154 ------------------------------
 155
 156 .. ocv:class:: videostab::MotionEstimatorBase
 157
 158 Base class for all global motion estimation methods.
 159
 160 ::
 161
 162     class CV_EXPORTS MotionEstimatorBase
 163     {
 164     public:
 165         virtual ~MotionEstimatorBase();
 166
 167         virtual void setMotionModel(MotionModel val);
 168         virtual MotionModel motionModel() const;
 169
 170         virtual Mat estimate(InputArray points0, InputArray points1, bool *ok = 0) = 0;
 171     };
 172
 173
 174 videostab::MotionEstimatorBase::setMotionModel
 175 ----------------------------------------------
 176
 177 Sets motion model.
 178
 179 .. ocv:function:: void MotionEstimatorBase::setMotionModel(MotionModel val)
 180
 181     :param val: Motion model. See :ocv:class:`videostab::MotionModel`.
 182
 183
 184
 185 videostab::MotionEstimatorBase::motionModel
 186 ----------------------------------------------
 187
 188 .. ocv:function:: MotionModel MotionEstimatorBase::motionModel() const
 189
 190     :return: Motion model. See :ocv:class:`videostab::MotionModel`.
 191
 192
 193 videostab::MotionEstimatorBase::estimate
 194 ----------------------------------------
 195
 196 Estimates global motion between two 2D point clouds.
 197
 198 .. ocv:function:: Mat MotionEstimatorBase::estimate(InputArray points0, InputArray points1, bool *ok = 0)
 199
 200     :param points0: Source set of 2D points (``32F``).
 201
 202     :param points1: Destination set of 2D points (``32F``).
 203
 204     :param ok: Indicates whether motion was estimated successfully.
 205
 206     :return: 3x3 2D transformation matrix (``32F``).
 207
 208
 209 videostab::MotionEstimatorRansacL2
 210 ----------------------------------
 211
 212 .. ocv:class:: videostab::MotionEstimatorRansacL2
 213
 214 Describes a robust RANSAC-based global 2D motion estimation method which minimizes L2 error.
 215
 216 ::
 217
 218     class CV_EXPORTS MotionEstimatorRansacL2 : public MotionEstimatorBase
 219     {
 220     public:
 221         MotionEstimatorRansacL2(MotionModel model = MM_AFFINE);
 222
 223         void setRansacParams(const RansacParams &val);
 224         RansacParams ransacParams() const;
 225
 226         void setMinInlierRatio(float val);
 227         float minInlierRatio() const;
 228
 229         virtual Mat estimate(InputArray points0, InputArray points1, bool *ok = 0);
 230     };
 231
 232
 233 videostab::MotionEstimatorL1
 234 ----------------------------
 235
 236 .. ocv:class:: videostab::MotionEstimatorL1
 237
 238 Describes a global 2D motion estimation method which minimizes L1 error.
 239
 240 .. note:: To be able to use this method you must build OpenCV with CLP library support.
 241
 242 ::
 243
 244     class CV_EXPORTS MotionEstimatorL1 : public MotionEstimatorBase
 245     {
 246     public:
 247         MotionEstimatorL1(MotionModel model = MM_AFFINE);
 248
 249         virtual Mat estimate(InputArray points0, InputArray points1, bool *ok = 0);
 250     };
 251
 252
 253 videostab::ImageMotionEstimatorBase
 254 -----------------------------------
 255
 256 .. ocv:class:: videostab::ImageMotionEstimatorBase
 257
 258 Base class for global 2D motion estimation methods which take frames as input.
 259
 260 ::
 261
 262     class CV_EXPORTS ImageMotionEstimatorBase
 263     {
 264     public:
 265         virtual ~ImageMotionEstimatorBase();
 266
 267         virtual void setMotionModel(MotionModel val);
 268         virtual MotionModel motionModel() const;
 269
 270         virtual Mat estimate(const Mat &frame0, const Mat &frame1, bool *ok = 0) = 0;
 271     };
 272
 273
 274 videostab::KeypointBasedMotionEstimator
 275 ---------------------------------------
 276
 277 .. ocv:class:: videostab::KeypointBasedMotionEstimator
 278
 279 Describes a global 2D motion estimation method which uses keypoints detection and optical flow for matching.
 280
 281 ::
 282
 283     class CV_EXPORTS KeypointBasedMotionEstimator : public ImageMotionEstimatorBase
 284     {
 285     public:
 286         KeypointBasedMotionEstimator(Ptr<MotionEstimatorBase> estimator);
 287
 288         virtual void setMotionModel(MotionModel val);
 289         virtual MotionModel motionModel() const;
 290
 291         void setDetector(Ptr<FeatureDetector> val);
 292         Ptr<FeatureDetector> detector() const;
 293
 294         void setOpticalFlowEstimator(Ptr<ISparseOptFlowEstimator> val);
 295         Ptr<ISparseOptFlowEstimator> opticalFlowEstimator() const;
 296
 297         void setOutlierRejector(Ptr<IOutlierRejector> val);
 298         Ptr<IOutlierRejector> outlierRejector() const;
 299
 300         virtual Mat estimate(const Mat &frame0, const Mat &frame1, bool *ok = 0);
 301     };