

Name: OpenGSURF 1.0
Date: 11-11-2011
Author: Pablo F. Alcantarilla
Institution: Department of Electronics, University of Alcalá

***************************************************************************************************************************
***************************************************************************************************************************

OpenGSURF is an opensource library that is based on C. Evans OpenSURF library.
This library is distributed under the GNU GPL.

OpenGSURF comprises several invariant descriptors that are based on gauge derivatives. Gauge derivatives are a very
important tool in computer vision and medical imaging, and multiscale gauge derivatives have very nice properties
such as rotation invariance.

In this library I coded several descriptors using gauge derivatives in a SURF descriptor framework obtaining very good
and interesting matching results.

For more information you can check the following two works from my website:
http://www.robesafe.com/personal/pablo.alcantarilla/full_list_of_publications.html

[1] Ph.D. Thesis. Pablo F. Alcantarilla. Vision Based Localization: From Humanoid Robots to Visually Impaired People. 
October 2011. University of Alcalá.

[2] Pablo F. Alcantarilla, Luis M. Bergasa and Andrew Davison. Gauge-SURF Descriptors. Submitted to Image and Vision
Computing. November 2011.

If you use the library for any research projects, I will appreciate if you cite my thesis work until we have the acceptance
of the submitted paper.

For more information, please contact me:
Contact: pablo.alcantarilla@depeca.uah.es, pablofdezalc@gmail.com

***************************************************************************************************************************
***************************************************************************************************************************

Library Dependencies Installation
---------------------------------------------------------------------------------------------------------------------------
The only libraries that are needed for a correct compilation are the same as for OpenSURF (http://code.google.com/p/opensurf1/) library:
g++-4.1 (although it works with different versions)
opencv1.0.0 (or newer versions)
cmake

***************************************************************************************************************************
***************************************************************************************************************************

Running the image matching example
---------------------------------------------------------------------------------------------------------------------------

For testing the sample image matching code, one needs to introduce the next arguments in command line:
./gsurf_match /img1 /imgN /H ground_truth Hthreshold mode extended upright
/img1: Path of the first image
/imgN: Path of the N image
/H: Ground truth homography file
ground_truth: Set to 1 in case we want to use the ground truth homography. Otherwise compute the fundamental matrix
Hthreshold: Hessian threshold for feature detection (FastHessian)
mode: Descriptors mode 
extended: Set to 1 in case we want to use the extended version of the descriptors
upright: Set to 1 in case we want to use the upright version of the descriptors (not invariant to rotation)

By default, the code performs image matching between images 1 and N, considering the nearest neighbors distance ratio. This distance ratio is set to 0.75.
You can change the value of this threshold by changing the global variable DRATIO in gsurf_match.h
   
In addition, to consider that a correspondence between two points is correct, the location error between the two points considering the ground truth homography, should be 
less than 2.5 pixels. You can change the value of the location error by setting the global variable MIN_H_ERROR in gsurf_match.h.
      
***************************************************************************************************************************
***************************************************************************************************************************

Descriptors mode
---------------------------------------------------------------------------------------------------------------------------

 Mode: Depending on the value of this variable, different SURF based descriptors are used.
 See surflib.h or reference paper for more details and understanding of the method.
 
    //! Get default OpenSURF descriptor with Gaussian Weighting
    //! MODE = 0
	void getDescriptor_64();
	void getUprightDescriptor_64();
	void getExtendedDescriptor_128();
	void getUprightExtendedDescriptor_128();

    //**********************************************************

    //! Get the modified descriptor. See Agrawal ECCV 08
    //! MODE = 1
    void getMDescriptor_64();
    void getMUprightDescriptor_64();
    void getMExtendedDescriptor_128();
    void getMUprightExtendedDescriptor_128();

    //**********************************************************

    //! Get the Gauge Descriptor
    //! MODE = 2
    void getGaugeDescriptor_16();
    void getGaugeUprightDescriptor_16();
    void getGaugeExtendedDescriptor_32();
    void getGaugeUprightExtendedDescriptor_32();
	
	//**********************************************************

    //! Get the Gauge Descriptor
    //! MODE = 3
    void getGaugeDescriptor_36();
    void getGaugeUprightDescriptor_36();
    void getGaugeExtendedDescriptor_72();
    void getGaugeUprightExtendedDescriptor_72();
	
    //**********************************************************

    //! Get the Gauge Descriptor
    //! MODE = 4
    void getGaugeDescriptor_64();
    void getGaugeUprightDescriptor_64();
    void getGaugeExtendedDescriptor_128();
    void getGaugeUprightExtendedDescriptor_128();

	//**********************************************************

    //! Get the Gauge Descriptor
    //! MODE = 5
    void getGaugeDescriptor_100();
    void getGaugeUprightDescriptor_100();
    void getGaugeExtendedDescriptor_200();
    void getGaugeUprightExtendedDescriptor_200();

	//**********************************************************

    //! Get the Gauge Descriptor
    //! MODE = 6
    void getGaugeDescriptor_144();
    void getGaugeUprightDescriptor_144();
    void getGaugeExtendedDescriptor_288();
    void getGaugeUprightExtendedDescriptor_288();
	
    //**********************************************************

    //! Get the SURF Descriptor Without Gaussian Weighting
    //! MODE = 7
    void getDescriptor_NW_16();
    void getUprightDescriptor_NW_16();
    void getExtendedDescriptor_NW_32();
    void getUprightExtendedDescriptor_NW_32();
	
	//**********************************************************

    //! Get the SURF Descriptor Without Gaussian Weighting
    //! MODE = 8
    void getDescriptor_NW_36();
    void getUprightDescriptor_NW_36();
    void getExtendedDescriptor_NW_72();
    void getUprightExtendedDescriptor_NW_72();
	
	//**********************************************************

    //! Get the SURF Descriptor Without Gaussian Weighting
    //! MODE = 9
    void getDescriptor_NW_64();
    void getUprightDescriptor_NW_64();
    void getExtendedDescriptor_NW_128();
    void getUprightExtendedDescriptor_NW_128();
	
	//**********************************************************

    //! Get the SURF Descriptor Without Gaussian Weighting
    //! MODE = 10
    void getDescriptor_NW_100();
    void getUprightDescriptor_NW_100();
    void getExtendedDescriptor_NW_200();
    void getUprightExtendedDescriptor_NW_200();
	
	//**********************************************************

    //! Get the SURF Descriptor Without Gaussian Weighting
    //! MODE = 11
    void getDescriptor_NW_144();
    void getUprightDescriptor_NW_144();
    void getExtendedDescriptor_NW_288();
    void getUprightExtendedDescriptor_NW_288();
	
	//**********************************************************

    //! Get the MG-SURF Descriptor
    //! MODE = 12
	void getMGaugeDescriptor_64();
	void getMGaugeUprightDescriptor_64();
	void getMGaugeExtendedDescriptor_128();
    void getMGaugeUprightExtendedDescriptor_128();
	