Global Motion Estimation

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.

videostab::MotionModel

Describes motion model between two point clouds.

C++: enum videostab::MotionModel
MM_TRANSLATION = 0
MM_TRANSLATION_AND_SCALE = 1
MM_ROTATION = 2
MM_RIGID = 3
MM_SIMILARITY = 4
MM_AFFINE = 5
MM_HOMOGRAPHY = 6
MM_UNKNOWN = 7

videostab::RansacParams

struct videostab::RansacParams

Describes RANSAC method parameters.

struct RansacParams
{
    int size; // subset size
    float thresh; // max error to classify as inlier
    float eps; // max outliers ratio
    float prob; // probability of success

    RansacParams() : size(0), thresh(0), eps(0), prob(0) {}
    RansacParams(int size, float thresh, float eps, float prob);

    int niters() const;

    static RansacParams default2dMotion(MotionModel model);
};

videostab::RansacParams::RansacParams

C++: videostab::RansacParams::RansacParams()
Returns:RANSAC method empty parameters object.

videostab::RansacParams::RansacParams

C++: videostab::RansacParams::RansacParams(int size, float thresh, float eps, float prob)
Parameters:
  • size – Subset size.
  • thresh – Maximum re-projection error value to classify as inlier.
  • eps – Maximum ratio of incorrect correspondences.
  • prob – Required success probability.
Returns:

RANSAC method parameters object.

videostab::RansacParams::niters

C++: int videostab::RansacParams::niters() const
Returns:Number of iterations that’ll be performed by RANSAC method.

videostab::RansacParams::default2dMotion

C++: static RansacParams videostab::RansacParams::default2dMotion(MotionModel model)
Parameters:
Returns:

Default RANSAC method parameters for the given motion model.

videostab::estimateGlobalMotionLeastSquares

Estimates best global motion between two 2D point clouds in the least-squares sense.

Note

Works in-place and changes input point arrays.

C++: Mat videostab::estimateGlobalMotionLeastSquares(InputOutputArray points0, InputOutputArray points1, int model=MM_AFFINE, float* rmse=0)
Parameters:
  • points0 – Source set of 2D points (32F).
  • points1 – Destination set of 2D points (32F).
  • model – Motion model (up to MM_AFFINE).
  • rmse – Final root-mean-square error.
Returns:

3x3 2D transformation matrix (32F).

videostab::estimateGlobalMotionRansac

Estimates best global motion between two 2D point clouds robustly (using RANSAC method).

C++: Mat videostab::estimateGlobalMotionRansac(InputArray points0, InputArray points1, int model=MM_AFFINE, const RansacParams& params=RansacParams::default2dMotion(MM_AFFINE), float* rmse=0, int* ninliers=0)
Parameters:
  • points0 – Source set of 2D points (32F).
  • points1 – Destination set of 2D points (32F).
  • model – Motion model. See videostab::MotionModel.
  • params – RANSAC method parameters. See videostab::RansacParams.
  • rmse – Final root-mean-square error.
  • ninliers – Final number of inliers.

videostab::getMotion

Computes motion between two frames assuming that all the intermediate motions are known.

C++: Mat videostab::getMotion(int from, int to, const std::vector<Mat>& motions)
Parameters:
  • from – Source frame index.
  • to – Destination frame index.
  • motions – Pair-wise motions. motions[i] denotes motion from the frame i to the frame i+1
Returns:

Motion from the frame from to the frame to.

videostab::MotionEstimatorBase

class videostab::MotionEstimatorBase

Base class for all global motion estimation methods.

class MotionEstimatorBase
{
public:
    virtual ~MotionEstimatorBase();

    virtual void setMotionModel(MotionModel val);
    virtual MotionModel motionModel() const;

    virtual Mat estimate(InputArray points0, InputArray points1, bool *ok = 0) = 0;
};

videostab::MotionEstimatorBase::setMotionModel

Sets motion model.

C++: void videostab::MotionEstimatorBase::setMotionModel(MotionModel val)
Parameters:

videostab::MotionEstimatorBase::motionModel

C++: MotionModel videostab::MotionEstimatorBase::motionModel() const
Returns:Motion model. See videostab::MotionModel.

videostab::MotionEstimatorBase::estimate

Estimates global motion between two 2D point clouds.

C++: Mat videostab::MotionEstimatorBase::estimate(InputArray points0, InputArray points1, bool* ok=0)
Parameters:
  • points0 – Source set of 2D points (32F).
  • points1 – Destination set of 2D points (32F).
  • ok – Indicates whether motion was estimated successfully.
Returns:

3x3 2D transformation matrix (32F).

videostab::MotionEstimatorRansacL2

class videostab::MotionEstimatorRansacL2 : public videostab::MotionEstimatorBase

Describes a robust RANSAC-based global 2D motion estimation method which minimizes L2 error.

class MotionEstimatorRansacL2 : public MotionEstimatorBase
{
public:
    MotionEstimatorRansacL2(MotionModel model = MM_AFFINE);

    void setRansacParams(const RansacParams &val);
    RansacParams ransacParams() const;

    void setMinInlierRatio(float val);
    float minInlierRatio() const;

    virtual Mat estimate(InputArray points0, InputArray points1, bool *ok = 0);
};

videostab::MotionEstimatorL1

class videostab::MotionEstimatorL1 : public videostab::MotionEstimatorBase

Describes a global 2D motion estimation method which minimizes L1 error.

Note

To be able to use this method you must build OpenCV with CLP library support.

class MotionEstimatorL1 : public MotionEstimatorBase
{
public:
    MotionEstimatorL1(MotionModel model = MM_AFFINE);

    virtual Mat estimate(InputArray points0, InputArray points1, bool *ok = 0);
};

videostab::ImageMotionEstimatorBase

class videostab::ImageMotionEstimatorBase

Base class for global 2D motion estimation methods which take frames as input.

class ImageMotionEstimatorBase
{
public:
    virtual ~ImageMotionEstimatorBase();

    virtual void setMotionModel(MotionModel val);
    virtual MotionModel motionModel() const;

    virtual Mat estimate(const Mat &frame0, const Mat &frame1, bool *ok = 0) = 0;
};

videostab::KeypointBasedMotionEstimator

class videostab::KeypointBasedMotionEstimator : public videostab::ImageMotionEstimatorBase

Describes a global 2D motion estimation method which uses keypoints detection and optical flow for matching.

class KeypointBasedMotionEstimator : public ImageMotionEstimatorBase
{
public:
    KeypointBasedMotionEstimator(Ptr<MotionEstimatorBase> estimator);

    virtual void setMotionModel(MotionModel val);
    virtual MotionModel motionModel() const;

    void setDetector(Ptr<FeatureDetector> val);
    Ptr<FeatureDetector> detector() const;

    void setOpticalFlowEstimator(Ptr<ISparseOptFlowEstimator> val);
    Ptr<ISparseOptFlowEstimator> opticalFlowEstimator() const;

    void setOutlierRejector(Ptr<IOutlierRejector> val);
    Ptr<IOutlierRejector> outlierRejector() const;

    virtual Mat estimate(const Mat &frame0, const Mat &frame1, bool *ok = 0);
};