Motion2D: a software to estimate 2D parametric motion models

00001 /*
 00002 
 00003   Copyright (c) 1995-2005 by INRIA.
 00004   All Rights Reserved.
 00005 
 00006   This software was developed at:
 00007   IRISA/INRIA Rennes
 00008   Campus Universitaire de Beaulieu
 00009   35042 Rennes Cedex
 00010 
 00011   http://www.irisa.fr
 00012 
 00013 */
 00014 
 00020 #ifndef CMotion2DEstimator_h
 00021 #define CMotion2DEstimator_h
 00022 
 00023 #include <stdio.h>
 00024 
 00025 #include <CMotion2DPyramid.h>
 00026 #include <CMotion2DModel.h>
 00027 
 00028 
 00029 #if defined (WIN32)
 00030 #  if defined MOTION2D_DLL_EXPORTS
 00031 #     define MOTION2D_API __declspec( dllexport )
 00032 #  elif defined MOTION2D_DLL_IMPORTS
 00033 #     define MOTION2D_API __declspec( dllimport )
 00034 #  else
 00035 #     define MOTION2D_API
 00036 #  endif
 00037 #else
 00038 #     define MOTION2D_API
 00039 #endif
 00040 
 00041 
 00042 
 00043 class MOTION2D_API CMotion2DEstimator
 00044 {
 00045  public:
 00046 
 00055   enum ERobustFunction {
 00056     Tukey,
 00059     Talwar,
 00062     Cauchy,
 00064     Welsh
 00066   };
 00067 
 00083   enum ECConstType {
 00084     CConst_Fixed,
 00087     CConst_Classic,
 00090     CConst_Robust
 00092   };
 00093 
 00094  public:
 00095   CMotion2DEstimator();
 00096   ~CMotion2DEstimator();
 00097 
 00098   bool estimate(const CMotion2DPyramid & pyramid1,
 00099                 const CMotion2DPyramid & pyramid2,
 00100                 const short *support, short label,
 00101                 CMotion2DModel &model, bool useModelAsInitialization=false);
 00102   bool estimate(const CMotion2DPyramid & pyramid1,
 00103                 const CMotion2DPyramid & pyramid2,
 00104                 const unsigned char *support, unsigned char label,
 00105                 CMotion2DModel &model, bool useModelAsInitialization=false);
 00106   float *getWeights(int &n_rows, int &n_cols);
 00107 
 00108 
 00117   void setRobustEstimator(bool robust=true) {
 00118     if (robust == true)
 00119       least_mean_square = false; // iterated weighted least-square
 00120     else {
 00121       least_mean_square = true; // just least-square.
 00122       //setNIterationMaxIRLS(1);
 00123     }
 00124   };
 00125 
 00135   void setRobustFunction(ERobustFunction function=Tukey) {
 00136     switch (function) {
 00137     case Tukey : ty_pond = 0; break;
 00138     case Talwar: ty_pond = 1; break;
 00139     case Cauchy: ty_pond = 2; break;
 00140     case Welsh : ty_pond = 3; break;
 00141     }
 00142   };
 00151   void setCConstant(ECConstType C_type=CConst_Fixed, double C=8.0) {
 00152     switch (C_type) {
 00153     case CConst_Fixed:
 00154       type_variance = 0; // Fixed C constant.
 00155       variance =  C; // Final value of the C constant
 00156       break;
 00157     case CConst_Classic:
 00158       type_variance = 1;
 00159       break;
 00160     case CConst_Robust:
 00161       type_variance = 2;
 00162       break;
 00163     }
 00164   };
 00165 
 00179   void setNIterationMaxIRLS(int niter=8) {
 00180     max_it_irls = niter;
 00181   };
 00182 
 00191   void setNIterationMaxLevel(int niter=7) {
 00192     max_it_stab = niter;
 00193   };
 00194 
 00204   void setLevelParameterIntroduction(int level_const=-1,
 00205                                      int level_affine=-1,
 00206                                      int level_quadratic=-1) {
 00207 
 00208     level_ct   = level_const;
 00209     level_lin  = level_affine;
 00210     level_quad = level_quadratic;
 00211   };
 00212 
 00236   bool setFirstEstimationLevel(unsigned level=3) {
 00237     if (level >= (unsigned) CMotion2DPyramid::NLEVELS_MAX) {
 00238        __panic("Cmotion2DEstimator::setFirstEstimationLevel() : Bad level...");
 00239        return false;
 00240     }
 00241     first_est_level = level;
 00242     return true;
 00243   };
 00244 
 00256   unsigned getFirstEstimationLevel() {
 00257     return pyr_level_max;
 00258   };
 00259 
 00271   bool setLastEstimationLevel(unsigned level=0) {
 00272     if (level >= (unsigned) CMotion2DPyramid::NLEVELS_MAX) {
 00273        __panic("Cmotion2DEstimator::setFirstEstimationLevel() : Bad level...");
 00274        return false;
 00275     }
 00276 
 00277     final_est_level = level;
 00278     return true;
 00279   };
 00280 
 00290   unsigned getLastEstimationLevel() {
 00291     return final_est_level;
 00292   };
 00293 
 00300   void setReliableSupportRate(float rate=0.4) {
 00301       if ((rate < 0.f) || (rate > 1.f)) {
 00302         __panic("CMotion2DEstimator::setReliableSupportRate(): Bad rate...");
 00303       }
 00304       tx_pts_min = rate;
 00305   };
 00306 
 00321   void computeSupportSize(bool compute=true, float threshold = 0.2f) {
 00322     if (compute == true) {
 00323       compute_support_size = 1; // Calcul nb pixels conformes par rapport au
 00324                                 // nb pixels zone de recouvrement.
 00325       if ((threshold < 0.f) || (threshold > 1.f)) {
 00326         __panic("CMotion2DEstimator::computeSupportSize(): Bad threshold.");
 00327       }
 00328       seuil_poids = threshold;  // Seuil au dela duquel 1 pixel est
 00329       // conforme au mvt.
 00330     }
 00331     else
 00332       compute_support_size = 0;
 00333   };
 00334 
 00342   bool isSupportSizeComputed() {
 00343     if (compute_support_size == 1)
 00344       return true;
 00345     else
 00346       return false;
 00347   };
 00348 
 00357   bool getSupportSize(double &size) {
 00358     if (compute_support_size == 1) {
 00359       size = rapport_poids;
 00360       return true;
 00361     }
 00362     else {
 00363       // The support size is not computed
 00364       size = 0.0;
 00365       return false;
 00366     }
 00367   };
 00368 
 00377   void computeResidualVariance(bool compute=false) {
 00378     compute_sigma2res = compute;
 00379   };
 00380 
 00390   bool isResidualVarianceComputed() {
 00391     if (compute_sigma2res == true)
 00392       return true;
 00393     else
 00394       return false;
 00395   };
 00396 
 00404   double getResidualVariance() {return sigma2res; };
 00405 
 00414   void computeCovarianceMatrix(bool compute=false) {
 00415     compute_covariance = compute;
 00416   };
 00417 
 00426   bool isCovarianceMatrixComputed() {
 00427     if (compute_covariance == true)
 00428       return true;
 00429     else
 00430       return false;
 00431   };
 00444   double *getCovarianceMatrix(int &n_rows, int &n_cols){
 00445     if (compute_covariance == true) {
 00446       n_rows = MAXCOEFSMODEL;
 00447       n_cols = MAXCOEFSMODEL;
 00448       return covariance;
 00449     }
 00450     else {
 00451       // The covariance matrix is not computed
 00452       n_rows = -1;
 00453       n_cols = -1;
 00454       return NULL;
 00455     }
 00456   };
 00457 
 00458   float *getDisplacedRowsSpatialGradientDataAddress(int level, int &n_rows, int &n_cols);
 00459   float *getDisplacedColsSpatialGradientDataAddress(int level, int &n_rows, int &n_cols);
 00460   float *getDFDDataAddress(int level, int &n_rows, int &n_cols);
 00461 
 00462 
 00463  private:
 00464   void __panic(char *message);
 00465 
 00467   // For the estimator tuning.
 00469   int nrows, ncols;
 00470   int type_variance;    // Variance given (0), classic (1), robust (2).
 00471   int ty_pond;          // Weights computation: Tukey(0), Talwar(1),Cauchy(2),
 00472                         // Welsch (3).
 00473   int max_it_stab;      // Max number of iterations at a given pyramid level
 00474   int max_it_irls;      // Max number of iterations in the IRLS method.
 00475   double variance;      // Final value of the C constant
 00476   int level_ct;         // Input level where constant models are considered.
 00477   int level_lin;        // Input level where linear models are considered.
 00478   int level_quad;       // Input level where quadratic models are considered.
 00479   unsigned first_est_level;// Pyramid level where the estimation starts.
 00480   unsigned final_est_level;// Pyramid level where the estimation stops
 00481   int pyr_level_max; // First pyramids level used for motion estimation
 00482   bool compute_sigma2res; //  If true compute the motion model variance.
 00483   bool compute_covariance; //  If true compute the covariance matrix
 00484   bool verbose;         // Verbose mode.
 00485 
 00486   double seuil_poids;   // Threshold to determine if a pixel is conform
 00487   bool least_mean_square;// If false robust estimation
 00488   double tx_pts_min;    // Min points requiered at a level
 00489 
 00490   bool init_mem_estIsDone;              // If 1, estimator memory allocated.
 00491   bool init_mem_weightsIsDone;          // If 1, memory allocated for weighs
 00492   TImageFloat pyr_fl1[CMotion2DPyramid::NLEVELS_MAX];   // Displaced gradients along x.
 00493   TImageFloat pyr_fl2[CMotion2DPyramid::NLEVELS_MAX];   // Displaced gradients along y.
 00494   TImageFloat pyr_fl3[CMotion2DPyramid::NLEVELS_MAX];   // DFD: I(pi+depl,t+1)-I(pi,t).
 00495   TImageFloat pyr_weights[CMotion2DPyramid::NLEVELS_MAX];// Weights pyramid
 00496   TImageShort pyr_support[CMotion2DPyramid::NLEVELS_MAX];// Support pyramid
 00497   int ct_level_intro;   // Level where constant models were considered
 00498   int lin_level_intro;  // Level where linear models were considered.
 00499   int quad_level_intro; // Level where quadratic models were considered.
 00500   int compute_support_size; // If true, compute the normalized ratio between
 00501                         // pixels considered as conform to the dominant
 00502                         // motion and the size of of the part of I(t) that is
 00503                         // likely to overlap I(t+1).
 00504   double rapport_poids; // Normalized ratio (see compute_support_size)
 00505   double sigma2res;     // Residual variance.
 00506   double covariance[MAXCOEFSMODEL * MAXCOEFSMODEL];     // Covariance matrix
 00507 
 00508 };
 00509 
 00510 
 00511 #endif
CMotion2DEstimator.h
