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: at Sat Mar 26 06:40:17 UTC 2011 |