Main MRPT website > C++ reference
MRPT logo

CFeatureExtraction.h

Go to the documentation of this file.
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 &section);
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.3 for MRPT 0.9.4 SVN: at Sat Mar 26 06:40:17 UTC 2011