00001 /* +---------------------------------------------------------------------------+ 00002 | The Mobile Robot Programming Toolkit (MRPT) C++ library | 00003 | | 00004 | http://mrpt.sourceforge.net/ | 00005 | | 00006 | Copyright (C) 2005-2010 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/CImageFloat.h> 00033 #include <mrpt/utils/CTicTac.h> 00034 #include <mrpt/vision/utils.h> 00035 #include <mrpt/vision/CFeature.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::TMethodExtraction), 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::TMethodExtraction): 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 * 00058 * Additionally, given a list of interest points onto an image, the following 00059 * <b>descriptors</b> can be computed for each point by calling CFeatureExtraction::computeDescriptors : 00060 * - SIFT descriptor (Lowe's descriptors). 00061 * - SURF descriptor (OpenCV's implementation - Requires OpenCV 1.1.0 from SVN or later). 00062 * - Intensity-domain spin images (SpinImage): Creates a vector descriptor with the 2D histogram as a single row. 00063 * - A circular patch in polar coordinates (Polar images): The matrix descriptor is a 2D polar image centered at the interest point. 00064 * - A log-polar image patch (Log-polar images): The matrix descriptor is the 2D log-polar image centered at the interest point. 00065 * 00066 * \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. 00067 * 00068 * \sa mrpt::vision::CFeature 00069 */ 00070 class VISION_IMPEXP CFeatureExtraction 00071 { 00072 public: 00073 enum TSIFTImplementation 00074 { 00075 LoweBinary = 0, 00076 CSBinary, 00077 VedaldiBinary, 00078 Hess, 00079 OpenCV 00080 }; 00081 00082 /** The set of parameters for all the detectors & descriptor algorithms */ 00083 struct VISION_IMPEXP TOptions : public utils::CLoadableOptions 00084 { 00085 /** Initalizer 00086 */ 00087 TOptions(); 00088 00089 /** See utils::CLoadableOptions 00090 */ 00091 void loadFromConfigFile( 00092 const mrpt::utils::CConfigFileBase &source, 00093 const std::string §ion); 00094 00095 /** See utils::CLoadableOptions 00096 */ 00097 void dumpToTextStream(CStream &out) const; 00098 00099 /** Type of the extracted features 00100 */ 00101 TFeatureType featsType; 00102 00103 /** Size of the patch to extract, or 0 if no patch is desired (default=21). 00104 */ 00105 unsigned int patchSize; 00106 00107 /** Indicates if subpixel accuracy is desired for the extracted points (only applicable to KLT and Harris features) 00108 */ 00109 bool FIND_SUBPIXEL; 00110 00111 struct VISION_IMPEXP TKLTOptions 00112 { 00113 /** KLT Options 00114 */ 00115 int radius; // size of the block of pixels used 00116 float threshold; // for rejecting weak local maxima (with min_eig < threshold*max(eig_image)) 00117 float min_distance; // minimum distance between features 00118 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) 00119 } KLTOptions; 00120 00121 struct VISION_IMPEXP THarrisOptions 00122 { 00123 /** Harris Options 00124 */ 00125 float threshold; // for rejecting weak local maxima (with min_eig < threshold*max(eig_image)) 00126 float k; // k factor for the Harris algorithm 00127 float sigma; // standard deviation for the gaussian smoothing function 00128 int radius; // size of the block of pixels used 00129 float min_distance; // minimum distance between features 00130 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) 00131 } harrisOptions; 00132 00133 struct VISION_IMPEXP TBCDOptions 00134 { 00135 /** BCD Options 00136 */ 00137 } BCDOptions; 00138 00139 struct VISION_IMPEXP TFASTOptions 00140 { 00141 /** FAST Options 00142 */ 00143 int threshold; 00144 bool nonmax_suppression; //!< Default = true 00145 } FASTOptions; 00146 00147 struct VISION_IMPEXP TSIFTOptions 00148 { 00149 /** SIFT Options 00150 */ 00151 TSIFTImplementation implementation; 00152 } SIFTOptions; 00153 00154 struct VISION_IMPEXP TSURFOptions 00155 { 00156 /** SURF Options 00157 */ 00158 bool rotation_invariant; //!< Compute the rotation invariant SURF (dim=128) if set to true (default), or the smaller uSURF otherwise (dim=64) 00159 } SURFOptions; 00160 00161 struct VISION_IMPEXP TSpinImagesOptions 00162 { 00163 /** SpinImages Options 00164 */ 00165 unsigned int hist_size_intensity; //!< Number of bins in the "intensity" axis of the 2D histogram (default=10). 00166 unsigned int hist_size_distance; //!< Number of bins in the "distance" axis of the 2D histogram (default=10). 00167 float std_dist; //!< Standard deviation in "distance", used for the "soft histogram" (default=0.4 pixels) 00168 float std_intensity; //!< Standard deviation in "intensity", used for the "soft histogram" (default=20 units [0,255]) 00169 unsigned int radius; //!< Maximum radius of the area of which the histogram is built, in pixel units (default=20 pixels) 00170 } SpinImagesOptions; 00171 00172 /** PolarImagesOptions Options 00173 */ 00174 struct VISION_IMPEXP TPolarImagesOptions 00175 { 00176 unsigned int bins_angle; //!< Number of bins in the "angular" axis of the polar image (default=8). 00177 unsigned int bins_distance; //!< Number of bins in the "distance" axis of the polar image (default=6). 00178 unsigned int radius; //!< Maximum radius of the area of which the polar image is built, in pixel units (default=20 pixels) 00179 } PolarImagesOptions; 00180 00181 /** LogPolarImagesOptions Options 00182 */ 00183 struct VISION_IMPEXP TLogPolarImagesOptions 00184 { 00185 unsigned int radius; //!< Maximum radius of the area of which the log polar image is built, in pixel units (default=30 pixels) 00186 unsigned int num_angles; //!< (default=16) Log-Polar image patch will have dimensions WxH, with: W=num_angles, H= rho_scale * log(radius) 00187 double rho_scale; //!< (default=5) Log-Polar image patch will have dimensions WxH, with: W=num_angles, H= rho_scale * log(radius) 00188 } LogPolarImagesOptions; 00189 00190 }; 00191 00192 TOptions options; //!< Set all the parameters of the desired method here before calling "detectFeatures" 00193 00194 /** Constructor 00195 */ 00196 CFeatureExtraction(); 00197 00198 /** Virtual destructor. 00199 */ 00200 virtual ~CFeatureExtraction(); 00201 00202 /** Extract features from the image based on the method defined in TOptions. 00203 * \param img (input) The image from where to extract the images. 00204 * \param feats (output) A complete list of features (containing a patch for each one of them if options.patchsize > 0). 00205 * \param nDesiredFeatures (op. input) Number of features to be extracted. Default: all possible. 00206 * \param ROI (op. input) Region of Interest. Default: The whole image. 00207 * 00208 * \sa computeDescriptors 00209 */ 00210 void detectFeatures( const CImage &img, 00211 CFeatureList &feats, 00212 unsigned int init_ID = 0, 00213 unsigned int nDesiredFeatures = 0, 00214 const TImageROI &ROI = TImageROI()) const; 00215 00216 //void detectFeatures2( 00217 // const CImage &img, 00218 // std::vector<CFeature> &feats, 00219 // unsigned int init_ID = 0, 00220 // unsigned int nDesiredFeatures = 0, 00221 // const TImageROI &ROI = TImageROI()) const; 00222 00223 00224 /** 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 00225 * \param in_img (input) The image from where to compute the descriptors. 00226 * \param inout_features (input/output) The list of features whose descriptors are going to be computed. 00227 * \param in_descriptor_list (input) The bitwise OR of one or several descriptors defined in TDescriptorType. 00228 * 00229 * Each value in "in_descriptor_list" represents one descriptor to be computed, for example: 00230 * \code 00231 * // This call will compute both, SIFT and Spin-Image descriptors for a list of feature points lstFeats. 00232 * fext.computeDescriptors(img, lstFeats, descSIFT | descSpinImages ); 00233 * \endcode 00234 * 00235 * \note The SIFT descriptors for already located features can only be computed through the Hess and 00236 * CSBinary implementations which may be specified in CFeatureExtraction::TOptions::SIFTOptions. 00237 * 00238 * \note This call will also use additional parameters from \a options 00239 */ 00240 void computeDescriptors( 00241 const CImage &in_img, 00242 CFeatureList &inout_features, 00243 TDescriptorType in_descriptor_list) const; 00244 00245 /** Extract more features from the image (apart from the provided ones) based on the method defined in TOptions. 00246 * \param img (input) The image from where to extract the images. 00247 * \param inList (input) The actual features in the image. 00248 * \param outList (output) The list of new features (containing a patch for each one of them if options.patchsize > 0). 00249 * \param nDesiredFeatures (op. input) Number of features to be extracted. Default: all possible. 00250 */ 00251 void findMoreFeatures( const CImage &img, 00252 const CFeatureList &inList, 00253 CFeatureList &outList, 00254 unsigned int nDesiredFeats = 0) const; 00255 00256 private: 00257 /** Compute the SIFT descriptor of the provided features into the input image 00258 * \param in_img (input) The image from where to compute the descriptors. 00259 * \param in_features (input/output) The list of features whose descriptors are going to be computed. 00260 * 00261 * \note The SIFT descriptors for already located features can only be computed through the Hess and 00262 CSBinary implementations which may be specified in CFeatureExtraction::TOptions::SIFTOptions. 00263 */ 00264 void internal_computeSiftDescriptors( const CImage &in_img, 00265 CFeatureList &in_features) const; 00266 00267 00268 /** Compute the SURF descriptor of the provided features into the input image 00269 * \param in_img (input) The image from where to compute the descriptors. 00270 * \param in_features (input/output) The list of features whose descriptors are going to be computed. 00271 */ 00272 void internal_computeSurfDescriptors( const CImage &in_img, 00273 CFeatureList &in_features) const; 00274 00275 /** Compute the intensity-domain spin images descriptor of the provided features into the input image 00276 * \param in_img (input) The image from where to compute the descriptors. 00277 * \param in_features (input/output) The list of features whose descriptors are going to be computed. 00278 * 00279 * \note Additional parameters from CFeatureExtraction::TOptions::SpinImagesOptions are used in this method. 00280 */ 00281 void internal_computeSpinImageDescriptors( const CImage &in_img, 00282 CFeatureList &in_features) const; 00283 00284 /** Compute a polar-image descriptor of the provided features into the input image 00285 * \param in_img (input) The image from where to compute the descriptors. 00286 * \param in_features (input/output) The list of features whose descriptors are going to be computed. 00287 * 00288 * \note Additional parameters from CFeatureExtraction::TOptions::PolarImagesOptions are used in this method. 00289 */ 00290 void internal_computePolarImageDescriptors( const CImage &in_img, 00291 CFeatureList &in_features) const; 00292 00293 /** Compute a log-polar image descriptor of the provided features into the input image 00294 * \param in_img (input) The image from where to compute the descriptors. 00295 * \param in_features (input/output) The list of features whose descriptors are going to be computed. 00296 * 00297 * \note Additional parameters from CFeatureExtraction::TOptions::LogPolarImagesOptions are used in this method. 00298 */ 00299 void internal_computeLogPolarImageDescriptors( const CImage &in_img, 00300 CFeatureList &in_features) const; 00301 00302 /** Select good features using the openCV implementation of the KLT method. 00303 * \param img (input) The image from where to select extract the images. 00304 * \param feats (output) A complete list of features (containing a patch for each one of them if options.patchsize > 0). 00305 * \param nDesiredFeatures (op. input) Number of features to be extracted. Default: all possible. 00306 * \param omitPixels (op. input) A mask for determining the ROI. (0: do not omit this pixel, 1: omit this pixel) 00307 */ 00308 void selectGoodFeaturesKLT( 00309 const CImage &inImg, 00310 CFeatureList &feats, 00311 unsigned int init_ID = 0, 00312 unsigned int nDesiredFeatures = 0, 00313 void *mask_ = NULL) const; 00314 00315 /** Extract features from the image based on the KLT method. 00316 * \param img The image from where to extract the images. 00317 * \param feats The list of extracted features. 00318 * \param nDesiredFeatures Number of features to be extracted. Default: authomatic. 00319 * \param ROI (op. input) Region of Interest. Default: All the image. 00320 */ 00321 void extractFeaturesKLT( 00322 const CImage &img, 00323 CFeatureList &feats, 00324 unsigned int init_ID = 0, 00325 unsigned int nDesiredFeatures = 0, 00326 const TImageROI &ROI = TImageROI()) const; 00327 00328 // ------------------------------------------------------------------------------------ 00329 // BCD 00330 // ------------------------------------------------------------------------------------ 00331 /** Extract features from the image based on the BCD method. 00332 * \param img The image from where to extract the images. 00333 * \param feats The list of extracted features. 00334 * \param nDesiredFeatures Number of features to be extracted. Default: authomatic. 00335 * \param ROI (op. input) Region of Interest. Default: All the image. 00336 */ 00337 void extractFeaturesBCD( 00338 const CImage &img, 00339 CFeatureList &feats, 00340 unsigned int init_ID = 0, 00341 unsigned int nDesiredFeatures = 0, 00342 const TImageROI &ROI = TImageROI()) const; 00343 00344 // ------------------------------------------------------------------------------------ 00345 // SIFT 00346 // ------------------------------------------------------------------------------------ 00347 /** Extract features from the image based on the SIFT method. 00348 * \param img The image from where to extract the images. 00349 * \param feats The list of extracted features. 00350 * \param nDesiredFeatures Number of features to be extracted. Default: authomatic. 00351 * \param ROI (op. input) Region of Interest. Default: All the image. 00352 */ 00353 void extractFeaturesSIFT( 00354 const CImage &img, 00355 CFeatureList &feats, 00356 unsigned int init_ID = 0, 00357 unsigned int nDesiredFeatures = 0, 00358 const TImageROI &ROI = TImageROI()) const; 00359 00360 // ------------------------------------------------------------------------------------ 00361 // SURF 00362 // ------------------------------------------------------------------------------------ 00363 /** Extract features from the image based on the SURF method. 00364 * \param img The image from where to extract the images. 00365 * \param feats The list of extracted features. 00366 * \param nDesiredFeatures Number of features to be extracted. Default: authomatic. 00367 * \param ROI (op. input) Region of Interest. Default: All the image. 00368 */ 00369 void extractFeaturesSURF( 00370 const CImage &img, 00371 CFeatureList &feats, 00372 unsigned int init_ID = 0, 00373 unsigned int nDesiredFeatures = 0, 00374 const TImageROI &ROI = TImageROI()) const; 00375 00376 // ------------------------------------------------------------------------------------ 00377 // FAST 00378 // ------------------------------------------------------------------------------------ 00379 /** Extract features from the image based on the FAST method. 00380 * \param img The image from where to extract the images. 00381 * \param feats The list of extracted features. 00382 * \param nDesiredFeatures Number of features to be extracted. Default: authomatic. 00383 * \param ROI (op. input) Region of Interest. Default: All the image. 00384 */ 00385 void extractFeaturesFAST( 00386 const CImage &img, 00387 CFeatureList &feats, 00388 unsigned int init_ID = 0, 00389 unsigned int nDesiredFeatures = 0, 00390 const TImageROI &ROI = TImageROI()) const; 00391 00392 //void extractFeaturesFAST2( 00393 // const CImage &img, 00394 // std::vector<CFeature> &feats, 00395 // unsigned int init_ID = 0, 00396 // unsigned int nDesiredFeatures = 0, 00397 // const TImageROI &ROI = TImageROI()) const; 00398 00399 00400 // ------------------------------------------------------------------------------------ 00401 // my_scale_space_extrema 00402 // ------------------------------------------------------------------------------------ 00403 /** Computes extrema in the scale space. 00404 * \param dog_pyr Pyramid of images. 00405 * \param octvs Number of considered octaves. 00406 * \param intvls Number of intervales in octaves. 00407 */ 00408 void* my_scale_space_extrema( 00409 CFeatureList &featList, void* dog_pyr, 00410 int octvs, int intvls, double contr_thr, int curv_thr, 00411 void* storage ) const; 00412 00413 /** Adjust scale if the image was initially doubled. 00414 * \param features The sequence of features. 00415 */ 00416 void my_adjust_for_img_dbl( void* features ) const; 00417 00418 /** Gets the number of times that a point in the image is higher or lower than the surroundings in the image-scale space 00419 * \param dog_pyr Pyramid of images. 00420 * \param octvs Number of considered octaves. 00421 * \param intvls Number of intervales in octaves. 00422 * \param row The row of the feature in the original image. 00423 * \param col The column of the feature in the original image. 00424 * \param nMin [out]: Times that the feature is lower than the surroundings. 00425 * \param nMax [out]: Times that the feature is higher than the surroundings. 00426 */ 00427 void getTimesExtrema( void* dog_pyr, int octvs, int intvls, float row, float col, unsigned int &nMin, unsigned int &nMax ) const; 00428 00429 /** Computes the Laplacian value of the feature in the corresponing image in the pyramid. 00430 * \param dog_pyr Pyramid of images. 00431 * \param octvs Number of considered octaves. 00432 * \param intvls Number of intervales in octaves. 00433 * \param row The row of the feature in the original image. 00434 * \param col The column of the feature in the original image. 00435 */ 00436 double getLaplacianValue( void* dog_pyr, int octvs, int intvls, float row, float col ) const; 00437 00438 /** Append a sequence of openCV features into an MRPT feature list. 00439 * \param features The sequence of features. 00440 * \param list [in-out] The list of MRPT features. 00441 * \param init_ID [in] The initial ID for the new features. 00442 */ 00443 void insertCvSeqInCFeatureList( void* features, CFeatureList &list, unsigned int init_ID = 0 ) const; 00444 00445 /** Converts a sequence of openCV features into an MRPT feature list. 00446 * \param features The sequence of features. 00447 * \param list [in-out] The list of MRPT features. 00448 * \param init_ID [in][optional] The initial ID for the features (default = 0). 00449 * \param ROI [in][optional] The initial ID for the features (default = empty ROI -> not used). 00450 */ 00451 void convertCvSeqInCFeatureList( void* features, CFeatureList &list, unsigned int init_ID = 0, const TImageROI &ROI = TImageROI() ) const; 00452 00453 }; // end of class 00454 } // end of namespace 00455 } // end of namespace 00456 #endif
| Page generated by Doxygen 1.6.1 for MRPT 0.9.0 SVN: at Mon Jun 7 06:47:58 UTC 2010 |
