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