added FREAK (by Kirell Benzi, Raphael Ortiz, Alexandre Alahi and Pierre Vandergheynst)

modules/core/include/opencv2/core/types_c.h

@@ -83,7 +83,7 @@
 #  if defined WIN32
 #    include <intrin.h>
 #  endif
-#  if __SSE2__ || !defined __GNUC__
+#  if defined __SSE2__ || !defined __GNUC__
 #    include <emmintrin.h>
 #  endif
 #endif
@@ -304,7 +304,7 @@ enum {
 
 CV_INLINE  int  cvRound( double value )
 {
-#if (defined _MSC_VER && defined _M_X64) || (defined __GNUC__ && defined __x86_64__ && __SSE2__ && !defined __APPLE__)
+#if (defined _MSC_VER && defined _M_X64) || (defined __GNUC__ && defined __x86_64__ && defined __SSE2__ && !defined __APPLE__)
     __m128d t = _mm_set_sd( value );
     return _mm_cvtsd_si32(t);
 #elif defined _MSC_VER && defined _M_IX86

modules/core/src/matrix.cpp

@@ -150,8 +150,8 @@ static void updateContinuityFlag(Mat& m)
             break;
     }
 
-    int64 t = (int64)m.step[0]*m.size[0];
-    if( j <= i && t == (int)t )
+    uint64 t = (uint64)m.step[0]*m.size[0];
+    if( j <= i && t == (size_t)t )
         m.flags |= Mat::CONTINUOUS_FLAG;
     else
         m.flags &= ~Mat::CONTINUOUS_FLAG;

modules/features2d/doc/feature_detection_and_description.rst

@@ -94,3 +94,36 @@ Finds keypoints in an image and computes their descriptors
 
     :param useProvidedKeypoints: If it is true, then the method will use the provided vector of keypoints instead of detecting them.
 
+    FREAK
+-----
+.. ocv:class:: FREAK
+
+Class implementing the FREAK (*Fast Retina Keypoint*) keypoint descriptor, described in [AOV12]_. The algorithm propose a novel keypoint descriptor inspired by the human visual system and more precisely the retina, coined Fast Retina Key- point (FREAK). A cascade of binary strings is computed by efficiently comparing image intensities over a retinal sampling pattern. FREAKs are in general faster to compute with lower memory load and also more robust than SIFT, SURF or BRISK. They are competitive alternatives to existing keypoints in particular for embedded applications.
+
+.. [AOV12] A. Alahi, R. Ortiz, and P. Vandergheynst. FREAK: Fast Retina Keypoint. In IEEE Conference on Computer Vision and Pattern Recognition, 2012. CVPR 2012 Open Source Award Winner.
+
+FREAK::FREAK
+------------
+The FREAK constructor
+
+.. ocv:function:: FREAK::FREAK(bool orientationNormalized = true, bool scaleNormalized = true, float patternScale = 22.0f, int nbOctave = 4, const vector<int>& selectedPairs = vector<int>())
+
+    :param orientationNormalized: Enable orientation normalization.
+    :param scaleNormalized: Enable scale normalization.
+    :param patternScale: Scaling of the description pattern.
+    :param nbOctave: Number of octaves covered by the detected keypoints.
+    :param selectedPairs: (Optional) user defined selected pairs indexes,
+
+FREAK::selectPairs
+------------------
+Select the 512 best description pair indexes from an input (grayscale) image set. FREAK is available with a set of pairs learned off-line. Researchers can run a training process to learn their own set of pair. For more details read section 4.2 in: A. Alahi, R. Ortiz, and P. Vandergheynst. FREAK: Fast Retina Keypoint. In IEEE Conference on Computer Vision and Pattern Recognition, 2012.
+
+We notice that for keypoint matching applications, image content has little effect on the selected pairs unless very specific what does matter is the detector type (blobs, corners,...) and the options used (scale/rotation invariance,...). Reduce corrThresh if not enough pairs are selected (43 points --> 903 possible pairs)
+
+.. ocv:function:: vector<int> FREAK::selectPairs(const vector<Mat>& images, vector<vector<KeyPoint> >& keypoints, const double corrThresh = 0.7, bool verbose = true)
+
+    :param images: Grayscale image input set.
+    :param keypoints: Set of detected keypoints
+    :param corrThresh: Correlation threshold.
+    :param verbose: Prints pair selection informations.
+        
\ No newline at end of file

modules/features2d/include/opencv2/features2d/features2d.hpp

@@ -310,6 +310,95 @@ protected:
 typedef ORB OrbFeatureDetector;
 typedef ORB OrbDescriptorExtractor;
 
+/*!
+  FREAK implementation
+*/
+class CV_EXPORTS FREAK : public DescriptorExtractor
+{
+public:
+    /** Constructor
+         * @param orientationNormalized enable orientation normalization
+         * @param scaleNormalized enable scale normalization
+         * @param patternScale scaling of the description pattern
+         * @param nbOctave number of octaves covered by the detected keypoints
+         * @param selectedPairs (optional) user defined selected pairs
+    */
+    explicit FREAK( bool orientationNormalized = true,
+           bool scaleNormalized = true,
+           float patternScale = 22.0f,
+           int nOctaves = 4,
+           const vector<int>& selectedPairs = vector<int>());
+	FREAK( const FREAK& rhs );
+    FREAK& operator=( const FREAK& );
+
+    virtual ~FREAK();
+
+    /** returns the descriptor length in bytes */
+    virtual int descriptorSize() const;
+
+    /** returns the descriptor type */
+    virtual int descriptorType() const;
+
+    /** select the 512 "best description pairs"
+         * @param images grayscale images set
+         * @param keypoints set of detected keypoints
+         * @param corrThresh correlation threshold
+         * @param verbose print construction information
+         * @return list of best pair indexes
+    */
+    vector<int> selectPairs( const vector<Mat>& images, vector<vector<KeyPoint> >& keypoints,
+                      const double corrThresh = 0.7, bool verbose = true );
+
+	AlgorithmInfo* info() const;
+
+	enum
+	{
+		NB_SCALES = 64, NB_PAIRS = 512, NB_ORIENPAIRS = 45
+	};
+
+protected:
+    virtual void computeImpl( const Mat& image, vector<KeyPoint>& keypoints, Mat& descriptors ) const;
+	void buildPattern();
+	uchar meanIntensity( const Mat& image, const Mat& integral, const float kp_x, const float kp_y,
+                         const unsigned int scale, const unsigned int rot, const unsigned int point ) const;
+
+	bool orientationNormalized; //true if the orientation is normalized, false otherwise
+    bool scaleNormalized; //true if the scale is normalized, false otherwise
+    double patternScale; //scaling of the pattern
+    int nOctaves; //number of octaves
+    bool extAll; // true if all pairs need to be extracted for pairs selection
+    
+    double patternScale0;
+    int nOctaves0;
+    vector<int> selectedPairs0;
+
+	struct PatternPoint
+	{
+	    float x; // x coordinate relative to center
+	    float y; // x coordinate relative to center
+	    float sigma; // Gaussian smoothing sigma
+	};
+
+	struct DescriptionPair
+	{
+	    uchar i; // index of the first point
+	    uchar j; // index of the second point
+	};
+
+	struct OrientationPair
+	{
+	    uchar i; // index of the first point
+	    uchar j; // index of the second point
+	    int weight_dx; // dx/(norm_sq))*4096
+	    int weight_dy; // dy/(norm_sq))*4096
+	};
+	
+	vector<PatternPoint> patternLookup; // look-up table for the pattern points (position+sigma of all points at all scales and orientation)
+    int patternSizes[NB_SCALES]; // size of the pattern at a specific scale (used to check if a point is within image boundaries)
+    DescriptionPair descriptionPairs[NB_PAIRS];
+    OrientationPair orientationPairs[NB_ORIENPAIRS];
+};
+
 
 /*!
  Maximal Stable Extremal Regions class.
@@ -464,7 +553,7 @@ protected:
   };
 
   virtual void detectImpl( const Mat& image, vector<KeyPoint>& keypoints, const Mat& mask=Mat() ) const;
-  virtual void findBlobs(const cv::Mat &image, const cv::Mat &binaryImage, std::vector<Center> &centers) const;
+  virtual void findBlobs(const Mat &image, const Mat &binaryImage, vector<Center> &centers) const;
 
   Params params;
 };

modules/features2d/src/features2d_init.cpp

@@ -96,6 +96,14 @@ CV_INIT_ALGORITHM(ORB, "Feature2D.ORB",
 
 ///////////////////////////////////////////////////////////////////////////////////////////////////////////
 
+CV_INIT_ALGORITHM(FREAK, "Feature2D.FREAK",
+    			  obj.info()->addParam(obj, "orientationNormalized", obj.orientationNormalized);
+			      obj.info()->addParam(obj, "scaleNormalized", obj.scaleNormalized);
+			      obj.info()->addParam(obj, "patternScale", obj.patternScale);
+			      obj.info()->addParam(obj, "nbOctave", obj.nOctaves));
+
+///////////////////////////////////////////////////////////////////////////////////////////////////////////
+
 CV_INIT_ALGORITHM(GFTTDetector, "Feature2D.GFTT",
                   obj.info()->addParam(obj, "nfeatures", obj.nfeatures);
                   obj.info()->addParam(obj, "qualityLevel", obj.qualityLevel);
@@ -148,6 +156,7 @@ bool cv::initModule_features2d(void)
     all &= !FastFeatureDetector_info_auto.name().empty();
     all &= !StarDetector_info_auto.name().empty();
     all &= !MSER_info_auto.name().empty();
+    all &= !FREAK_info_auto.name().empty();
     all &= !ORB_info_auto.name().empty();
     all &= !GFTTDetector_info_auto.name().empty();
     all &= !HarrisDetector_info_auto.name().empty();

modules/features2d/test/test_features2d.cpp

@@ -1035,6 +1035,14 @@ TEST( Features2d_DescriptorExtractor_ORB, regression )
     test.safe_run();
 }
 
+TEST( Features2d_DescriptorExtractor_FREAK, regression )
+{
+    // TODO adjust the parameters below
+    CV_DescriptorExtractorTest<Hamming> test( "descriptor-freak",  (CV_DescriptorExtractorTest<Hamming>::DistanceType)12.f,
+                                                 DescriptorExtractor::create("FREAK"), 0.010f );
+    test.safe_run();
+}
+
 TEST( Features2d_DescriptorExtractor_BRIEF, regression )
 {
     CV_DescriptorExtractorTest<Hamming> test( "descriptor-brief",  1,

samples/cpp/freak_demo.cpp

+//  demo.cpp
+//
+//	Here is an example on how to use the descriptor presented in the following paper:
+//	A. Alahi, R. Ortiz, and P. Vandergheynst. FREAK: Fast Retina Keypoint. In IEEE Conference on Computer Vision and Pattern Recognition, 2012.
+//  CVPR 2012 Open Source Award winner
+//
+//	Copyright (C) 2011-2012  Signal processing laboratory 2, EPFL,
+//	Kirell Benzi (kirell.benzi@epfl.ch),
+//	Raphael Ortiz (raphael.ortiz@a3.epfl.ch),
+//	Alexandre Alahi (alexandre.alahi@epfl.ch)
+//	and Pierre Vandergheynst (pierre.vandergheynst@epfl.ch)
+//
+//  Redistribution and use in source and binary forms, with or without modification,
+//  are permitted provided that the following conditions are met:
+//
+//   * Redistribution's of source code must retain the above copyright notice,
+//     this list of conditions and the following disclaimer.
+//
+//   * Redistribution's in binary form must reproduce the above copyright notice,
+//     this list of conditions and the following disclaimer in the documentation
+//     and/or other materials provided with the distribution.
+//
+//   * The name of the copyright holders may not be used to endorse or promote products
+//     derived from this software without specific prior written permission.
+//
+//  This software is provided by the copyright holders and contributors "as is" and
+//  any express or implied warranties, including, but not limited to, the implied
+//  warranties of merchantability and fitness for a particular purpose are disclaimed.
+//  In no event shall the Intel Corporation or contributors be liable for any direct,
+//  indirect, incidental, special, exemplary, or consequential damages
+//  (including, but not limited to, procurement of substitute goods or services;
+//  loss of use, data, or profits; or business interruption) however caused
+//  and on any theory of liability, whether in contract, strict liability,
+//  or tort (including negligence or otherwise) arising in any way out of
+//  the use of this software, even if advised of the possibility of such damage.
+
+#include <iostream>
+#include <string>
+#include <vector>
+
+#include <opencv2/core/core.hpp>
+#include <opencv2/highgui/highgui.hpp>
+#include <opencv2/features2d/features2d.hpp>
+#include <opencv2/nonfree/features2d.hpp>
+#include <opencv2/legacy/legacy.hpp>
+
+using namespace cv;
+
+static void help( char** argv )
+{
+    std::cout << "\nUsage: " << argv[0] << " [path/to/image1] [path/to/image2] \n"
+              << "This is an example on how to use the keypoint descriptor presented in the following paper: \n"
+              << "A. Alahi, R. Ortiz, and P. Vandergheynst. FREAK: Fast Retina Keypoint. \n"
+              << "In IEEE Conference on Computer Vision and Pattern Recognition, 2012. CVPR 2012 Open Source Award winner \n"
+              << std::endl;
+}
+
+int main( int argc, char** argv ) {
+    // check http://opencv.itseez.com/doc/tutorials/features2d/table_of_content_features2d/table_of_content_features2d.html
+    // for OpenCV general detection/matching framework details
+
+    if( argc != 3 ) {
+        help(argv);
+        return -1;
+    }
+
+    // Load images
+    Mat imgA = imread(argv[1], CV_LOAD_IMAGE_GRAYSCALE );
+    if( !imgA.data ) {
+        std::cout<< " --(!) Error reading image " << argv[1] << std::endl;
+        return -1;
+    }
+
+    Mat imgB = imread(argv[2], CV_LOAD_IMAGE_GRAYSCALE );
+    if( !imgA.data ) {
+        std::cout << " --(!) Error reading image " << argv[2] << std::endl;
+        return -1;
+    }
+
+    std::vector<KeyPoint> keypointsA, keypointsB;
+    Mat descriptorsA, descriptorsB;
+    std::vector<DMatch> matches;
+
+    // DETECTION
+    // Any openCV detector such as
+    SurfFeatureDetector detector(2000,4);
+
+    // DESCRIPTOR
+    // Our proposed FREAK descriptor
+    // (roation invariance, scale invariance, pattern radius corresponding to SMALLEST_KP_SIZE,
+    // number of octaves, optional vector containing the selected pairs)
+    // FREAK extractor(true, true, 22, 4, std::vector<int>());
+    FREAK extractor;
+
+    // MATCHER
+    // The standard Hamming distance can be used such as
+    // BruteForceMatcher<Hamming> matcher;
+    // or the proposed cascade of hamming distance using SSSE3
+    BruteForceMatcher<Hamming> matcher;
+
+    // detect
+    double t = (double)getTickCount();
+    detector.detect( imgA, keypointsA );
+    detector.detect( imgB, keypointsB );
+    t = ((double)getTickCount() - t)/getTickFrequency();
+    std::cout << "detection time [s]: " << t/1.0 << std::endl;
+
+    // extract
+    t = (double)getTickCount();
+    extractor.compute( imgA, keypointsA, descriptorsA );
+    extractor.compute( imgB, keypointsB, descriptorsB );
+    t = ((double)getTickCount() - t)/getTickFrequency();
+    std::cout << "extraction time [s]: " << t << std::endl;
+
+    // match
+    t = (double)getTickCount();
+    matcher.match(descriptorsA, descriptorsB, matches);
+    t = ((double)getTickCount() - t)/getTickFrequency();
+    std::cout << "matching time [s]: " << t << std::endl;
+
+    // Draw matches
+    Mat imgMatch;
+    drawMatches(imgA, keypointsA, imgB, keypointsB, matches, imgMatch);
+
+    namedWindow("matches", CV_WINDOW_KEEPRATIO);
+    imshow("matches", imgMatch);
+    waitKey(0);
+}