00001 /* +---------------------------------------------------------------------------+ 00002 | The Mobile Robot Programming Toolkit (MRPT) C++ library | 00003 | | 00004 | http://www.mrpt.org/ | 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 #ifndef CFeatureExtraction_H 00029 #define CFeatureExtraction_H 00030 00031 #include <mrpt/utils/CImage.h> 00032 #include <mrpt/utils/CTicTac.h> 00033 #include <mrpt/vision/utils.h> 00034 #include <mrpt/vision/CFeature.h> 00035 #include <mrpt/vision/TSimpleFeature.h> 00036 00037 namespace mrpt 00038 { 00039 namespace vision 00040 { 00041 /** The central class from which images can be analyzed in search of different kinds of interest points and descriptors computed for them. 00042 * To extract features from an image, create an instance of CFeatureExtraction, 00043 * fill out its CFeatureExtraction::options field, including the algorithm to use (see 00044 * CFeatureExtraction::TOptions::featsType), and call CFeatureExtraction::detectFeatures. 00045 * This will return a set of features of the class mrpt::vision::CFeature, which include 00046 * details for each interest point as well as the desired descriptors and/or patches. 00047 * 00048 * By default, a 21x21 patch is extracted for each detected feature. If the patch is not needed, 00049 * set patchSize to 0 in CFeatureExtraction::options 00050 * 00051 * The implemented <b>detection</b> algorithms are (see CFeatureExtraction::TOptions::featsType): 00052 * - KLT (Kanade-Lucas-Tomasi): A detector (no descriptor vector). 00053 * - Harris: A detector (no descriptor vector). 00054 * - BCD (Binary Corner Detector): A detector (no descriptor vector) (Not implemented yet). 00055 * - SIFT: An implementation of the SIFT detector and descriptor. The implemention may be selected with CFeatureExtraction::TOptions::SIFTOptions::implementation. 00056 * - SURF: OpenCV's implementation of SURF detector and descriptor. 00057 * - The FAST feature detector (OpenCV's implementation) 00058 * - The FASTER (9,10,12) detectors (Edward Rosten's libcvd implementation optimized for SSE2). 00059 * 00060 * Additionally, given a list of interest points onto an image, the following 00061 * <b>descriptors</b> can be computed for each point by calling CFeatureExtraction::computeDescriptors : 00062 * - SIFT descriptor (Lowe's descriptors). 00063 * - SURF descriptor (OpenCV's implementation - Requires OpenCV 1.1.0 from SVN or later). 00064 * - Intensity-domain spin images (SpinImage): Creates a vector descriptor with the 2D histogram as a single row. 00065 * - A circular patch in polar coordinates (Polar images): The matrix descriptor is a 2D polar image centered at the interest point. 00066 * - A log-polar image patch (Log-polar images): The matrix descriptor is the 2D log-polar image centered at the interest point. 00067 * 00068 * 00069 * Apart from the normal entry point \a detectFeatures(), these other low-level functions are provided for convenience: 00070 * - 00071 * 00072 * \note The descriptor "Intensity-domain spin images" is described in "A sparse texture representation using affine-invariant regions", S Lazebnik, C Schmid, J Ponce, 2003 IEEE Computer Society Conference on Computer Vision. 00073 * \sa mrpt::vision::CFeature 00074 * \ingroup mrptvision_features 00075 */ 00076 class VISION_IMPEXP CFeatureExtraction 00077 { 00078 public: 00079 enum TSIFTImplementation 00080 { 00081 LoweBinary = 0, 00082 CSBinary, 00083 VedaldiBinary, 00084 Hess, 00085 OpenCV 00086 }; 00087 00088 /** The set of parameters for all the detectors & descriptor algorithms */ 00089 struct VISION_IMPEXP TOptions : public utils::CLoadableOptions 00090 { 00091 /** Initalizer 00092 */ 00093 TOptions(const TFeatureType featsType = featKLT); 00094 00095 /** See utils::CLoadableOptions 00096 */ 00097 void loadFromConfigFile( 00098 const mrpt::utils::CConfigFileBase &source, 00099 const std::string §ion); 00100 00101 /** See utils::CLoadableOptions 00102 */ 00103 void dumpToTextStream(CStream &out) const; 00104 00105 /** Type of the extracted features 00106 */ 00107 TFeatureType featsType; 00108 00109 /** Size of the patch to extract, or 0 if no patch is desired (default=21). 00110 */ 00111 unsigned int patchSize; 00112 00113 /** Whether to use a mask for determining the regions where not to look for keypoints (default=false). 00114 */ 00115 bool useMask; 00116 00117 /** Whether to add the found features to the input feature list or clear it before adding them (default=false). 00118 */ 00119 bool addNewFeatures; 00120 00121 /** Indicates if subpixel accuracy is desired for the extracted points (only applicable to KLT and Harris features) 00122 */ 00123 bool FIND_SUBPIXEL; 00124 00125 /** KLT Options */ 00126 struct VISION_IMPEXP TKLTOptions 00127 { 00128 int radius; // size of the block of pixels used 00129 float threshold; // (default=0.1) for rejecting weak local maxima (with min_eig < threshold*max(eig_image)) 00130 float min_distance; // minimum distance between features 00131 bool tile_image; // splits the image into 8 tiles and search for the best points in all of them (distribute the features over all the image) 00132 } KLTOptions; 00133 00134 /** Harris Options */ 00135 struct VISION_IMPEXP THarrisOptions 00136 { 00137 float threshold; // (default=0.005) for rejecting weak local maxima (with min_eig < threshold*max(eig_image)) 00138 float k; // k factor for the Harris algorithm 00139 float sigma; // standard deviation for the gaussian smoothing function 00140 int radius; // size of the block of pixels used 00141 float min_distance; // minimum distance between features 00142 bool tile_image; // splits the image into 8 tiles and search for the best points in all of them (distribute the features over all the image) 00143 } harrisOptions; 00144 00145 /** BCD Options */ 00146 struct VISION_IMPEXP TBCDOptions 00147 { 00148 } BCDOptions; 00149 00150 /** FAST and FASTER Options */ 00151 struct VISION_IMPEXP TFASTOptions 00152 { 00153 int threshold; //!< default= 20 00154 bool nonmax_suppression; //!< Default = true 00155 float min_distance; //!< (default=5) minimum distance between features (in pixels) 00156 bool use_KLT_response; //!< (default=false) If true, use CImage::KLT_response to compute the response at each point instead of the FAST "standard response". 00157 } FASTOptions; 00158 00159 struct VISION_IMPEXP TSIFTOptions 00160 { 00161 /** SIFT Options 00162 */ 00163 TSIFTImplementation implementation; 00164 } SIFTOptions; 00165 00166 struct VISION_IMPEXP TSURFOptions 00167 { 00168 /** SURF Options 00169 */ 00170 bool rotation_invariant; //!< Compute the rotation invariant SURF (dim=128) if set to true (default), or the smaller uSURF otherwise (dim=64) 00171 } SURFOptions; 00172 00173 struct VISION_IMPEXP TSpinImagesOptions 00174 { 00175 /** SpinImages Options 00176 */ 00177 unsigned int hist_size_intensity; //!< Number of bins in the "intensity" axis of the 2D histogram (default=10). 00178 unsigned int hist_size_distance; //!< Number of bins in the "distance" axis of the 2D histogram (default=10). 00179 float std_dist; //!< Standard deviation in "distance", used for the "soft histogram" (default=0.4 pixels) 00180 float std_intensity; //!< Standard deviation in "intensity", used for the "soft histogram" (default=20 units [0,255]) 00181 unsigned int radius; //!< Maximum radius of the area of which the histogram is built, in pixel units (default=20 pixels) 00182 } SpinImagesOptions; 00183 00184 /** PolarImagesOptions Options 00185 */ 00186 struct VISION_IMPEXP TPolarImagesOptions 00187 { 00188 unsigned int bins_angle; //!< Number of bins in the "angular" axis of the polar image (default=8). 00189 unsigned int bins_distance; //!< Number of bins in the "distance" axis of the polar image (default=6). 00190 unsigned int radius; //!< Maximum radius of the area of which the polar image is built, in pixel units (default=20 pixels) 00191 } PolarImagesOptions; 00192 00193 /** LogPolarImagesOptions Options 00194 */ 00195 struct VISION_IMPEXP TLogPolarImagesOptions 00196 { 00197 unsigned int radius; //!< Maximum radius of the area of which the log polar image is built, in pixel units (default=30 pixels) 00198 unsigned int num_angles; //!< (default=16) Log-Polar image patch will have dimensions WxH, with: W=num_angles, H= rho_scale * log(radius) 00199 double rho_scale; //!< (default=5) Log-Polar image patch will have dimensions WxH, with: W=num_angles, H= rho_scale * log(radius) 00200 } LogPolarImagesOptions; 00201 00202 }; 00203 00204 TOptions options; //!< Set all the parameters of the desired method here before calling "detectFeatures" 00205 00206 /** Constructor 00207 */ 00208 CFeatureExtraction(); 00209 00210 /** Virtual destructor. 00211 */ 00212 virtual ~CFeatureExtraction(); 00213 00214 /** Extract features from the image based on the method defined in TOptions. 00215 * \param img (input) The image from where to extract the images. 00216 * \param feats (output) A complete list of features (containing a patch for each one of them if options.patchsize > 0). 00217 * \param nDesiredFeatures (op. input) Number of features to be extracted. Default: all possible. 00218 * \param ROI (op. input) Region of Interest. Default: The whole image. 00219 * 00220 * \sa computeDescriptors 00221 */ 00222 void detectFeatures( const CImage & img, 00223 CFeatureList & feats, 00224 const unsigned int init_ID = 0, 00225 const unsigned int nDesiredFeatures = 0, 00226 const TImageROI & ROI = TImageROI(), 00227 const CMatrixBool * mask = NULL ) const; // Important: This was a const ref. in mrpt <0.9.4, but the instantiation of a default value 00228 // for CMatrixBool being a template generated duplicated linking errors for MSVC, thus it was changed to a pointer. 00229 00230 /** Compute one (or more) descriptors for the given set of interest points onto the image, which may have been filled out manually or from \a detectFeatures 00231 * \param in_img (input) The image from where to compute the descriptors. 00232 * \param inout_features (input/output) The list of features whose descriptors are going to be computed. 00233 * \param in_descriptor_list (input) The bitwise OR of one or several descriptors defined in TDescriptorType. 00234 * 00235 * Each value in "in_descriptor_list" represents one descriptor to be computed, for example: 00236 * \code 00237 * // This call will compute both, SIFT and Spin-Image descriptors for a list of feature points lstFeats. 00238 * fext.computeDescriptors(img, lstFeats, descSIFT | descSpinImages ); 00239 * \endcode 00240 * 00241 * \note The SIFT descriptors for already located features can only be computed through the Hess and 00242 * CSBinary implementations which may be specified in CFeatureExtraction::TOptions::SIFTOptions. 00243 * 00244 * \note This call will also use additional parameters from \a options 00245 */ 00246 void computeDescriptors( 00247 const CImage &in_img, 00248 CFeatureList &inout_features, 00249 TDescriptorType in_descriptor_list) const; 00250 00251 /** Extract more features from the image (apart from the provided ones) based on the method defined in TOptions. 00252 * \param img (input) The image from where to extract the images. 00253 * \param inList (input) The actual features in the image. 00254 * \param outList (output) The list of new features (containing a patch for each one of them if options.patchsize > 0). 00255 * \param nDesiredFeatures (op. input) Number of features to be extracted. Default: all possible. 00256 * 00257 * \sa The more powerful class: mrpt::vision::CGenericFeatureTracker 00258 */ 00259 void findMoreFeatures( const CImage &img, 00260 const CFeatureList &inList, 00261 CFeatureList &outList, 00262 unsigned int nDesiredFeats = 0) const; 00263 00264 00265 /** @name Static methods with low-level detector functionality 00266 @{ */ 00267 00268 /** A SSE2-optimized implementation of FASTER-9 (requires img to be grayscale). If SSE2 is not available, it gratefully falls back to a non-optimized version 00269 * Only the pt.{x,y} fields are filled out for each feature: the rest of fields are left <b>uninitialized</b> and their content is <b>undefined</b> 00270 * Note that (x,y) are already scaled to the 0-level image coordinates if octave>0, by means of: 00271 * 00272 * pt.x = detected.x << octave; 00273 * pt.y = detected.y << octave; 00274 * 00275 * If \a append_to_list is true, the \a corners list is not cleared before adding the newly detected feats. 00276 * \ingroup mrptvision_features 00277 */ 00278 static void detectFeatures_SSE2_FASTER9(const CImage &img, TSimpleFeatureList & corners, const int threshold = 20, bool append_to_list = false, uint8_t octave = 0); 00279 00280 /** Just like \a detectFeatures_SSE2_FASTER9() for another version of the detector. 00281 * \ingroup mrptvision_features */ 00282 static void detectFeatures_SSE2_FASTER10(const CImage &img, TSimpleFeatureList & corners, const int threshold = 20, bool append_to_list = false, uint8_t octave = 0); 00283 00284 /** Just like \a detectFeatures_SSE2_FASTER9() for another version of the detector. 00285 * \ingroup mrptvision_features */ 00286 static void detectFeatures_SSE2_FASTER12(const CImage &img, TSimpleFeatureList & corners, const int threshold = 20, bool append_to_list = false, uint8_t octave = 0); 00287 00288 /** @} */ 00289 00290 private: 00291 /** Compute the SIFT descriptor of the provided features into the input image 00292 * \param in_img (input) The image from where to compute the descriptors. 00293 * \param in_features (input/output) The list of features whose descriptors are going to be computed. 00294 * 00295 * \note The SIFT descriptors for already located features can only be computed through the Hess and 00296 CSBinary implementations which may be specified in CFeatureExtraction::TOptions::SIFTOptions. 00297 */ 00298 void internal_computeSiftDescriptors( const CImage &in_img, 00299 CFeatureList &in_features) const; 00300 00301 00302 /** Compute the SURF descriptor of the provided features into the input image 00303 * \param in_img (input) The image from where to compute the descriptors. 00304 * \param in_features (input/output) The list of features whose descriptors are going to be computed. 00305 */ 00306 void internal_computeSurfDescriptors( const CImage &in_img, 00307 CFeatureList &in_features) const; 00308 00309 /** Compute the intensity-domain spin images descriptor of the provided features into the input image 00310 * \param in_img (input) The image from where to compute the descriptors. 00311 * \param in_features (input/output) The list of features whose descriptors are going to be computed. 00312 * 00313 * \note Additional parameters from CFeatureExtraction::TOptions::SpinImagesOptions are used in this method. 00314 */ 00315 void internal_computeSpinImageDescriptors( const CImage &in_img, 00316 CFeatureList &in_features) const; 00317 00318 /** Compute a polar-image descriptor of the provided features into the input image 00319 * \param in_img (input) The image from where to compute the descriptors. 00320 * \param in_features (input/output) The list of features whose descriptors are going to be computed. 00321 * 00322 * \note Additional parameters from CFeatureExtraction::TOptions::PolarImagesOptions are used in this method. 00323 */ 00324 void internal_computePolarImageDescriptors( const CImage &in_img, 00325 CFeatureList &in_features) const; 00326 00327 /** Compute a log-polar image descriptor of the provided features into the input image 00328 * \param in_img (input) The image from where to compute the descriptors. 00329 * \param in_features (input/output) The list of features whose descriptors are going to be computed. 00330 * 00331 * \note Additional parameters from CFeatureExtraction::TOptions::LogPolarImagesOptions are used in this method. 00332 */ 00333 void internal_computeLogPolarImageDescriptors( const CImage &in_img, 00334 CFeatureList &in_features) const; 00335 00336 /** Select good features using the openCV implementation of the KLT method. 00337 * \param img (input) The image from where to select extract the images. 00338 * \param feats (output) A complete list of features (containing a patch for each one of them if options.patchsize > 0). 00339 * \param nDesiredFeatures (op. input) Number of features to be extracted. Default: all possible. 00340 * \param omitPixels (op. input) A mask for determining the ROI. (0: do not omit this pixel, 1: omit this pixel) 00341 */ 00342 void selectGoodFeaturesKLT( 00343 const CImage &inImg, 00344 CFeatureList &feats, 00345 unsigned int init_ID = 0, 00346 unsigned int nDesiredFeatures = 0, 00347 void *mask_ = NULL) const; 00348 00349 /** Extract features from the image based on the KLT method. 00350 * \param img The image from where to extract the images. 00351 * \param feats The list of extracted features. 00352 * \param nDesiredFeatures Number of features to be extracted. Default: authomatic. 00353 * \param ROI (op. input) Region of Interest. Default: All the image. 00354 */ 00355 void extractFeaturesKLT( 00356 const CImage &img, 00357 CFeatureList &feats, 00358 unsigned int init_ID = 0, 00359 unsigned int nDesiredFeatures = 0, 00360 const TImageROI &ROI = TImageROI()) const; 00361 00362 // ------------------------------------------------------------------------------------ 00363 // BCD 00364 // ------------------------------------------------------------------------------------ 00365 /** Extract features from the image based on the BCD method. 00366 * \param img The image from where to extract the images. 00367 * \param feats The list of extracted features. 00368 * \param nDesiredFeatures Number of features to be extracted. Default: authomatic. 00369 * \param ROI (op. input) Region of Interest. Default: All the image. 00370 */ 00371 void extractFeaturesBCD( 00372 const CImage &img, 00373 CFeatureList &feats, 00374 unsigned int init_ID = 0, 00375 unsigned int nDesiredFeatures = 0, 00376 const TImageROI &ROI = TImageROI()) const; 00377 00378 // ------------------------------------------------------------------------------------ 00379 // SIFT 00380 // ------------------------------------------------------------------------------------ 00381 /** Extract features from the image based on the SIFT method. 00382 * \param img The image from where to extract the images. 00383 * \param feats The list of extracted features. 00384 * \param nDesiredFeatures Number of features to be extracted. Default: authomatic. 00385 * \param ROI (op. input) Region of Interest. Default: All the image. 00386 */ 00387 void extractFeaturesSIFT( 00388 const CImage &img, 00389 CFeatureList &feats, 00390 unsigned int init_ID = 0, 00391 unsigned int nDesiredFeatures = 0, 00392 const TImageROI &ROI = TImageROI()) const; 00393 00394 // ------------------------------------------------------------------------------------ 00395 // SURF 00396 // ------------------------------------------------------------------------------------ 00397 /** Extract features from the image based on the SURF method. 00398 * \param img The image from where to extract the images. 00399 * \param feats The list of extracted features. 00400 * \param nDesiredFeatures Number of features to be extracted. Default: authomatic. 00401 * \param ROI (op. input) Region of Interest. Default: All the image. 00402 */ 00403 void extractFeaturesSURF( 00404 const CImage &img, 00405 CFeatureList &feats, 00406 unsigned int init_ID = 0, 00407 unsigned int nDesiredFeatures = 0, 00408 const TImageROI &ROI = TImageROI()) const; 00409 00410 // ------------------------------------------------------------------------------------ 00411 // FAST 00412 // ------------------------------------------------------------------------------------ 00413 /** Extract features from the image based on the FAST method. 00414 * \param img The image from where to extract the images. 00415 * \param feats The list of extracted features. 00416 * \param nDesiredFeatures Number of features to be extracted. Default: authomatic. 00417 * \param ROI (op. input) Region of Interest. Default: All the image. 00418 */ 00419 void extractFeaturesFAST( 00420 const CImage &img, 00421 CFeatureList &feats, 00422 unsigned int init_ID = 0, 00423 unsigned int nDesiredFeatures = 0, 00424 const TImageROI &ROI = TImageROI(), 00425 const CMatrixBool * mask = NULL ) const; // Important: This was a const ref. in mrpt <0.9.4, but the instantiation of a default value 00426 // for CMatrixBool being a template generated duplicated linking errors for MSVC, thus it was changed to a pointer. 00427 00428 /** Edward's "FASTER & Better" detector, N=9,10,12 */ 00429 void extractFeaturesFASTER_N( 00430 const int N, 00431 const CImage &img, 00432 CFeatureList &feats, 00433 unsigned int init_ID = 0, 00434 unsigned int nDesiredFeatures = 0, 00435 const TImageROI &ROI = TImageROI()) const; 00436 00437 00438 // ------------------------------------------------------------------------------------ 00439 // my_scale_space_extrema 00440 // ------------------------------------------------------------------------------------ 00441 /** Computes extrema in the scale space. 00442 * \param dog_pyr Pyramid of images. 00443 * \param octvs Number of considered octaves. 00444 * \param intvls Number of intervales in octaves. 00445 */ 00446 void* my_scale_space_extrema( 00447 CFeatureList &featList, void* dog_pyr, 00448 int octvs, int intvls, double contr_thr, int curv_thr, 00449 void* storage ) const; 00450 00451 /** Adjust scale if the image was initially doubled. 00452 * \param features The sequence of features. 00453 */ 00454 void my_adjust_for_img_dbl( void* features ) const; 00455 00456 /** Gets the number of times that a point in the image is higher or lower than the surroundings in the image-scale space 00457 * \param dog_pyr Pyramid of images. 00458 * \param octvs Number of considered octaves. 00459 * \param intvls Number of intervales in octaves. 00460 * \param row The row of the feature in the original image. 00461 * \param col The column of the feature in the original image. 00462 * \param nMin [out]: Times that the feature is lower than the surroundings. 00463 * \param nMax [out]: Times that the feature is higher than the surroundings. 00464 */ 00465 void getTimesExtrema( void* dog_pyr, int octvs, int intvls, float row, float col, unsigned int &nMin, unsigned int &nMax ) const; 00466 00467 /** Computes the Laplacian value of the feature in the corresponing image in the pyramid. 00468 * \param dog_pyr Pyramid of images. 00469 * \param octvs Number of considered octaves. 00470 * \param intvls Number of intervales in octaves. 00471 * \param row The row of the feature in the original image. 00472 * \param col The column of the feature in the original image. 00473 */ 00474 double getLaplacianValue( void* dog_pyr, int octvs, int intvls, float row, float col ) const; 00475 00476 /** Append a sequence of openCV features into an MRPT feature list. 00477 * \param features The sequence of features. 00478 * \param list [in-out] The list of MRPT features. 00479 * \param init_ID [in] The initial ID for the new features. 00480 */ 00481 void insertCvSeqInCFeatureList( void* features, CFeatureList &list, unsigned int init_ID = 0 ) const; 00482 00483 /** Converts a sequence of openCV features into an MRPT feature list. 00484 * \param features The sequence of features. 00485 * \param list [in-out] The list of MRPT features. 00486 * \param init_ID [in][optional] The initial ID for the features (default = 0). 00487 * \param ROI [in][optional] The initial ID for the features (default = empty ROI -> not used). 00488 */ 00489 void convertCvSeqInCFeatureList( void* features, CFeatureList &list, unsigned int init_ID = 0, const TImageROI &ROI = TImageROI() ) const; 00490 00491 }; // end of class 00492 } // end of namespace 00493 } // end of namespace 00494 #endif
| Page generated by Doxygen 1.7.5 for MRPT 0.9.5 SVN: at Thu Oct 13 21:25:36 UTC 2011 |