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