Main MRPT website > C++ reference
MRPT logo

tracking.h

Go to the documentation of this file.
00001 /* +---------------------------------------------------------------------------+
00002    |          The Mobile Robot Programming Toolkit (MRPT) C++ library          |
00003    |                                                                           |
00004    |                   http://mrpt.sourceforge.net/                            |
00005    |                                                                           |
00006    |   Copyright (C) 2005-2011  University of Malaga                           |
00007    |                                                                           |
00008    |    This software was written by the Machine Perception and Intelligent    |
00009    |      Robotics Lab, University of Malaga (Spain).                          |
00010    |    Contact: Jose-Luis Blanco  <jlblanco@ctima.uma.es>                     |
00011    |                                                                           |
00012    |  This file is part of the MRPT project.                                   |
00013    |                                                                           |
00014    |     MRPT is free software: you can redistribute it and/or modify          |
00015    |     it under the terms of the GNU General Public License as published by  |
00016    |     the Free Software Foundation, either version 3 of the License, or     |
00017    |     (at your option) any later version.                                   |
00018    |                                                                           |
00019    |   MRPT is distributed in the hope that it will be useful,                 |
00020    |     but WITHOUT ANY WARRANTY; without even the implied warranty of        |
00021    |     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the         |
00022    |     GNU General Public License for more details.                          |
00023    |                                                                           |
00024    |     You should have received a copy of the GNU General Public License     |
00025    |     along with MRPT.  If not, see <http://www.gnu.org/licenses/>.         |
00026    |                                                                           |
00027    +---------------------------------------------------------------------------+ */
00028 
00029 #ifndef mrpt_vision_tracking_H
00030 #define mrpt_vision_tracking_H
00031 
00032 #include <mrpt/vision/types.h>
00033 #include <mrpt/vision/link_pragmas.h>
00034 
00035 #include <mrpt/vision/CFeature.h>
00036 #include <mrpt/utils/CImage.h>
00037 #include <mrpt/utils/CTimeLogger.h>
00038 
00039 #include <mrpt/utils/metaprogramming.h>
00040 
00041 #include <memory>       // for auto_ptr
00042 
00043 namespace mrpt
00044 {
00045         namespace vision
00046         {
00047                 using namespace mrpt::slam;
00048                 using namespace mrpt::math;
00049                 using namespace mrpt::utils;
00050 
00051                 /**  @name All related to feature tracking
00052                      @{
00053                   */
00054 
00055                 /** (Deprecated) Track a set of features from img1 -> img2 using sparse optimal flow (classic KL method)
00056                   *  \sa OpenCV's method cvCalcOpticalFlowPyrLK
00057                   */
00058                 MRPT_DECLARE_DEPRECATED_FUNCTION("Deprecated: See CGenericFeatureTracker",
00059                  void VISION_IMPEXP trackFeatures(
00060                         const CImage &old_img,
00061                         const CImage &new_img,
00062                         vision::CFeatureList &featureList,
00063                         const unsigned int window_width = 15,
00064                         const unsigned int window_height = 15 ) );
00065 
00066 
00067                 /** A virtual interface for all feature trackers, implementing the part of feature tracking that is common to any specific tracker implementation.
00068                   *   This class provides a quite robust tracking of features, avoiding as many outliers as possible but not all of them:
00069                   *    more robust tracking would require application-specific information and could be done in a number of very different approaches,
00070                   *    so this class will not try to do any kind of RANSAC or any other advanced outlier rejection; instead, it should
00071                   *    be done by the users or the classes that employ this class.
00072                   *
00073                   *   The basic usage of this class is as follows:
00074                   *    \code
00075                   *       CFeatureTracker_KL    tracker;  // Note: CFeatureTracker_KL is the most robust implementation for now.
00076                   *       tracker.extra_params["add_new_features"] = 1;  // Enable detection of new features, not only tracking
00077                   *       tracker.extra_params[...] = ...
00078                   *       // ....
00079                   *       CFeatureList  theFeats;  // The list of features
00080                   *       mrpt::utils::CImage  previous_img, current_img;
00081                   *
00082                   *       while (true) {
00083                   *           current_img = ... // Grab new image.
00084                   *           if ( previous_img_is_ok )
00085                   *               tracker.trackFeatures(previous_img, current_img, theFeats);
00086                   *           previous_img = current_img;
00087                   *       }
00088                   *    \endcode
00089                   *
00090                   *  Below follows the list of optional parameters for "extra_params" which can be set
00091                   *  and will be understood by this base class for any specific tracker implementation.
00092                   *  Note that all parameters are double's, but boolean flags are emulated by the values 0.0 (false) and 1.0 (true).
00093                   *
00094                   *  List of parameters:
00095                   * <table border="1" >
00096                   *   <tr><td align="center" > <b>Parameter name</b>  </td>  <td align="center" > <b>Default value</b> </td> <td align="center" > <b>Comments</b> </td> </tr>
00097                   *   <tr><td align="center" > add_new_features  </td>  <td align="center" > 0 </td>
00098                   *      <td> If set to "1", the class will not only track existing features, but will also perform (after doing the actual tracking) an efficient
00099                   *            search for new features with the FAST detector, and will add them to the passed "CFeatureList" if they fulfill a set of restrictions,
00100                   *            as stablished by the other parameters (see <i>add_new_feat_min_separation</i>,<i>add_new_feat_max_features</i>,<i>minimum_KLT_response_to_add</i>).
00101                   *        </td> </tr>
00102                   *   <tr><td align="center" > add_new_feat_min_separation  </td>  <td align="center" > 15 </td>
00103                   *      <td> If <i>add_new_features</i>==1,  this is the minimum separation (in pixels) to any other (old, or new) feature for it
00104                   *             being considered a candidate to be added.
00105                   *         </td> </tr>
00106                   *   <tr><td align="center" > add_new_feat_max_features  </td>  <td align="center" > 100 </td>
00107                   *      <td> If <i>add_new_features</i>==1,  FAST features are detected in each frame, and only the best <i>add_new_feat_max_features</i> keypoints
00108                   *             (ordered by their KLT response) will be considered as eligible for addition to the set of tracked features.
00109                   *         </td> </tr>
00110                   *   <tr><td align="center" > add_new_feat_patch_size  </td>  <td align="center" > 11 </td>
00111                   *      <td> If <i>add_new_features</i>==1,  for each new added feature, this is the size of the patch to be extracted around the keypoint (set to 0 if patches are not required at all).
00112                   *          </td> </tr>
00113                   *   <tr><td align="center" > minimum_KLT_response_to_add  </td>  <td align="center" > 10 </td>
00114                   *      <td> If <i>add_new_features</i>==1, this sets the minimum KLT response of candidate FAST features to be added in each frame, if they also fulfil the other restrictions (e.g. min.distance).
00115                   *         </td> </tr>
00116                   *   <tr><td align="center" > check_KLT_response_every  </td>  <td align="center" > 0 </td>
00117                   *      <td> If >0, it will compute the KLT response at each feature point every <i>N</i> frames
00118                   *            and those below <i>minimum_KLT_response</i> will be marked as "lost" in their "track_status" field.
00119                   *        </td> </tr>
00120                   *   <tr><td align="center" > minimum_KLT_response  </td>  <td align="center" > 5 </td>
00121                   *      <td> See explanation of <i>check_KLT_response_every</i>.
00122                   *        </td> </tr>
00123                   *   <tr><td align="center" > KLT_response_half_win  </td>  <td align="center" > 4 </td>
00124                   *      <td> When computing the KLT response of features (see <i>minimum_KLT_response</i> and <i>minimum_KLT_response_to_add</i>),
00125                   *            the window centered at the point for its estimation will be of size (2*W+1)x(2*W+1), with <i>W</i> being this parameter value.
00126                   *       </td> </tr>
00127                   *   <tr><td align="center" > update_patches_every  </td>  <td align="center" > 0 </td>
00128                   *      <td> If !=0, the patch associated to each feature will be updated with every N'th frame. </td> </tr>
00129                   * </table>
00130                   *
00131                   *  This class also offers a time profiler, disabled by default (see getProfiler and enableTimeLogger).
00132                   *
00133                   * \sa CFeatureTracker_KL, the example application "track-video-features".
00134                   */
00135                 struct VISION_IMPEXP  CGenericFeatureTracker
00136                 {
00137                         /** Optional list of extra parameters to the algorithm. */
00138                         mrpt::utils::TParametersDouble extra_params;
00139 
00140                         /** Default ctor */
00141                         inline CGenericFeatureTracker() : m_timlog(false), m_update_patches_counter(0),m_check_KLT_counter(0),m_detector_adaptive_thres(10)
00142                         { }
00143                         /** Ctor with extra parameters */
00144                         inline CGenericFeatureTracker(mrpt::utils::TParametersDouble extraParams) : extra_params(extraParams), m_timlog(false), m_update_patches_counter(0),m_check_KLT_counter(0),m_detector_adaptive_thres(10)
00145                         { }
00146                         /** Dtor */
00147                         virtual ~CGenericFeatureTracker()
00148                         { }
00149 
00150                         /** Perform feature tracking from "old_img" to "new_img", with a (possibly empty) list of previously tracked features "inout_featureList".
00151                           *  This is a list of parameters (in "extraParams") accepted by ALL implementations of feature tracker (see each derived class for more specific parameters).
00152                           *             - "add_new_features" (Default=0). If set to "1", new features will be also added to the existing ones in areas of the image poor of features.
00153                           * This method does:
00154                           *    - Convert old and new images to grayscale, if they're in color.
00155                           *    - Call the pure virtual "trackFeatures_impl" method.
00156                           *    - Implement the optional detection of new features if "add_new_features"!=0.
00157                           */
00158                         void trackFeatures(
00159                                 const CImage &old_img,
00160                                 const CImage &new_img,
00161                                 vision::CFeatureList &inout_featureList );
00162 
00163                         /** A wrapper around the basic trackFeatures() method, but keeping the original list of features unmodified and returns the tracked ones in a new list. */
00164                         inline void trackFeaturesNewList(
00165                                 const CImage &old_img,
00166                                 const CImage &new_img,
00167                                 const vision::CFeatureList &in_featureList,
00168                                 vision::CFeatureList &out_featureList
00169                                 )
00170                         {
00171                                 out_featureList = in_featureList;
00172                                 std::for_each(
00173                                         out_featureList.begin(),out_featureList.end(),
00174                                         mrpt::utils::metaprogramming::ObjectMakeUnique() );
00175                                 this->trackFeatures(old_img, new_img, out_featureList);
00176                         }
00177 
00178                         /** Returns a read-only reference to the internal time logger */
00179                         inline const mrpt::utils::CTimeLogger  & getProfiler() const { return m_timlog; }
00180                         /** Returns a reference to the internal time logger */
00181                         inline mrpt::utils::CTimeLogger  & getProfiler() { return m_timlog; }
00182 
00183                         /** Returns a read-only reference to the internal time logger */
00184                         inline void enableTimeLogger(bool enable=true) { m_timlog.enable(enable); }
00185 
00186                 protected:
00187                         /** The tracking method implementation, to be implemented in children classes. */
00188                         virtual void trackFeatures_impl(
00189                                 const CImage &old_img,
00190                                 const CImage &new_img,
00191                                 vision::CFeatureList &inout_featureList ) = 0;
00192 
00193                         mrpt::utils::CTimeLogger  m_timlog; //!< the internal time logger, disabled by default.
00194 
00195                 private:
00196                         size_t          m_update_patches_counter;       //!< for use when "update_patches_every">=1
00197                         size_t          m_check_KLT_counter;    //!< For use when "check_KLT_response_every">=1
00198                         int                     m_detector_adaptive_thres;  //!< For use in "add_new_features" == true
00199 
00200                 };
00201 
00202                 typedef std::auto_ptr<CGenericFeatureTracker> CGenericFeatureTrackerAutoPtr;
00203 
00204 
00205                 /** Track a set of features from old_img -> new_img using sparse optimal flow (classic KL method).
00206                   *
00207                   *  See CGenericFeatureTracker for a more detailed explanation on how to use this class.
00208                   *
00209                   *   List of additional parameters in "extra_params" (apart from those in CGenericFeatureTracker) accepted by this class:
00210                   *             - "window_width"  (Default=15)
00211                   *             - "window_height" (Default=15)
00212                   *
00213                   *  \sa OpenCV's method cvCalcOpticalFlowPyrLK
00214                   */
00215                 struct VISION_IMPEXP CFeatureTracker_KL : public CGenericFeatureTracker
00216                 {
00217                         /** Default ctor */
00218                         inline CFeatureTracker_KL() { }
00219                         /** Ctor with extra parameters */
00220                         inline CFeatureTracker_KL(mrpt::utils::TParametersDouble extraParams) : CGenericFeatureTracker(extraParams)     { }
00221 
00222                 protected:
00223                         virtual void trackFeatures_impl(
00224                                 const CImage &old_img,
00225                                 const CImage &new_img,
00226                                 vision::CFeatureList &inout_featureList );
00227                 };
00228 
00229                 /** Track a set of features from old_img -> new_img by patch correlation over the closest FAST features, using a KD-tree for looking closest correspondences.
00230                   *  See CGenericFeatureTracker for a more detailed explanation on how to use this class.
00231                   *
00232                   *   List of additional parameters in "extra_params" (apart from those in CGenericFeatureTracker) accepted by this class:
00233                   *             - "window_width"  (Default=15)
00234                   *             - "window_height" (Default=15)
00235                   *
00236                   */
00237                 struct VISION_IMPEXP CFeatureTracker_FAST : public CGenericFeatureTracker
00238                 {
00239                         /** Ctor */
00240                         CFeatureTracker_FAST(const mrpt::utils::TParametersDouble & extraParams = mrpt::utils::TParametersDouble() );
00241 
00242                         struct VISION_IMPEXP TExtraOutputInfo
00243                         {
00244                                 size_t  raw_FAST_feats_detected;  //!< In the new_img with the last adaptive threshold
00245                         };
00246 
00247                         TExtraOutputInfo  last_execution_extra_info; //!< Updated with each call to trackFeatures()
00248 
00249                 protected:
00250                         virtual void trackFeatures_impl(
00251                                 const CImage &old_img,
00252                                 const CImage &new_img,
00253                                 vision::CFeatureList &inout_featureList );
00254 
00255                 private:
00256                         int             m_detector_adaptive_thres;              //!< threshold for cvFAST()
00257                         size_t  m_hysteresis_min_num_feats, m_hysteresis_max_num_feats; //!< for the adaptive control of "m_detector_adaptive_thres"
00258                 };
00259 
00260 
00261                 /** Track a set of features from old_img -> new_img by patch matching over a fixed window centered at each feature's previous location.
00262                   *  See CGenericFeatureTracker for a more detailed explanation on how to use this class.
00263                   *
00264                   *   List of additional parameters in "extra_params" (apart from those in CGenericFeatureTracker) accepted by this class:
00265                   *             - "window_width"  (Default=15)
00266                   *             - "window_height" (Default=15)
00267                   *
00268                   */
00269                 struct VISION_IMPEXP CFeatureTracker_PatchMatch : public CGenericFeatureTracker
00270                 {
00271                         /** Ctor */
00272                         CFeatureTracker_PatchMatch(const mrpt::utils::TParametersDouble & extraParams = mrpt::utils::TParametersDouble() );
00273 
00274                 protected:
00275                         virtual void trackFeatures_impl(
00276                                 const CImage &old_img,
00277                                 const CImage &new_img,
00278                                 vision::CFeatureList &inout_featureList );
00279                 };
00280 
00281 
00282                 /** (Deprecated) Track a set of features from img1 -> img2 using sparse optimal flow (classic KL method)
00283                   *  \sa OpenCV's method cvCalcOpticalFlowPyrLK
00284                   */
00285                 MRPT_DECLARE_DEPRECATED_FUNCTION("Deprecated: See CGenericFeatureTracker",
00286                 void VISION_IMPEXP trackFeatures(
00287                         const CImage &inImg1,
00288                         const CImage &inImg2,
00289                         const CFeatureList &inFeatureList,
00290                         CFeatureList &outFeatureList,
00291                         const unsigned int window_width,
00292                         const unsigned int window_height)
00293                         );
00294 
00295 
00296                 /** Search for correspondences which are not in the same row and deletes them
00297                   * ...
00298                   */
00299                 void VISION_IMPEXP checkTrackedFeatures( CFeatureList &leftList,
00300                                                         CFeatureList &rightList,
00301                                                         vision::TMatchingOptions options);
00302 
00303                 /** Tracks a set of features in an image.
00304                   *  Deprecated: See CGenericFeatureTracker
00305                   */
00306                 void VISION_IMPEXP trackFeatures2(
00307                         const CImage &inImg1,
00308                         const CImage &inImg2,
00309                         CFeatureList &featureList,
00310                         const unsigned int window_width = 15,
00311                         const unsigned int window_height = 15);
00312 
00313                 /** Filter bad correspondences by distance
00314                   * ...
00315                   */
00316                 void VISION_IMPEXP filterBadCorrsByDistance( mrpt::utils::TMatchingPairList &list,      // The list of correspondences
00317                                                                                 unsigned int numberOfSigmas );                          // Threshold
00318 
00319 
00320 
00321                 /**  @}  */
00322         }
00323 }
00324 
00325 
00326 #endif



Page generated by Doxygen 1.7.3 for MRPT 0.9.4 SVN:exported at Tue Jan 25 21:56:31 UTC 2011