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