SiftGPU.h
Go to the documentation of this file.
00001 
00002 //      File:           SiftGPU.h
00003 //      Author:         Changchang Wu
00004 //      Description :   interface for the SIFTGPU class.
00005 //                                      SiftGPU:        The SiftGPU Tool.  
00006 //                                      SiftGPUEX:      SiftGPU + viewer
00007 //                                      SiftParam:      Sift Parameters
00008 //                                      SiftMatchGPU: GPU SIFT Matcher;
00009 //
00010 //
00011 //      Copyright (c) 2007 University of North Carolina at Chapel Hill
00012 //      All Rights Reserved
00013 //
00014 //      Permission to use, copy, modify and distribute this software and its
00015 //      documentation for educational, research and non-profit purposes, without
00016 //      fee, and without a written agreement is hereby granted, provided that the
00017 //      above copyright notice and the following paragraph appear in all copies.
00018 //      
00019 //      The University of North Carolina at Chapel Hill make no representations
00020 //      about the suitability of this software for any purpose. It is provided
00021 //      'as is' without express or implied warranty. 
00022 //
00023 //      Please send BUG REPORTS to ccwu@cs.unc.edu
00024 //
00026 
00027 
00028 #ifndef GPU_SIFT_H
00029 #define GPU_SIFT_H
00030 
00031 #if  defined(_WIN32) 
00032         #ifdef SIFTGPU_DLL
00033                 #ifdef DLL_EXPORT
00034                         #define SIFTGPU_EXPORT __declspec(dllexport)
00035                 #else
00036                         #define SIFTGPU_EXPORT __declspec(dllimport)
00037                 #endif
00038         #else
00039                 #define SIFTGPU_EXPORT
00040         #endif
00041 
00042     #define SIFTGPU_EXPORT_EXTERN SIFTGPU_EXPORT
00043 
00044         #if _MSC_VER > 1000
00045                 #pragma once
00046         #endif
00047 #else
00048         #define SIFTGPU_EXPORT
00049     #define SIFTGPU_EXPORT_EXTERN extern "C"
00050 #endif
00051 
00053 //clss SiftParam
00054 //description: SIFT parameters
00056 class GlobalUtil;
00057 class SiftParam
00058 {
00059 public:
00060         float*          _sigma;
00061         float           _sigma_skip0; // 
00062         float           _sigma_skip1; //
00063         
00064         //sigma of the first level
00065         float           _sigma0;
00066         float           _sigman;
00067         int                     _sigma_num;
00068 
00069         //how many dog_level in an octave
00070         int                     _dog_level_num;
00071         int                     _level_num;
00072 
00073         //starting level in an octave
00074         int                     _level_min;
00075         int                     _level_max;
00076         int                     _level_ds;
00077         //dog threshold
00078         float           _dog_threshold;
00079         //edge elimination
00080         float           _edge_threshold;
00081         void             ParseSiftParam();
00082 public:
00083         float GetLevelSigma(int lev);
00084         float GetInitialSmoothSigma(int octave_min);
00085         SIFTGPU_EXPORT SiftParam();
00086         virtual ~SiftParam();
00087 };
00088 
00089 class LiteWindow;
00090 class GLTexInput;
00091 class ShaderMan;
00092 class SiftPyramid;
00093 class ImageList;
00095 //class SIftGPU
00096 //description: Interface of SiftGPU lib
00098 class SiftGPU:public SiftParam
00099 {
00100 public:
00101         enum
00102         {
00103                 SIFTGPU_NOT_SUPPORTED = 0,
00104                 SIFTGPU_PARTIAL_SUPPORTED = 1, // detction works, but not orientation/descriptor
00105                 SIFTGPU_FULL_SUPPORTED = 2
00106         };
00107         typedef struct SiftKeypoint
00108         {
00109                 float x, y, s, o; //x, y, scale, orientation.
00110         }SiftKeypoint;
00111 protected: 
00112         //when more than one images are specified
00113         //_current indicates the active one
00114         int             _current;
00115         //_initialized indicates if the shaders and OpenGL/SIFT parameters are initialized
00116         //they are initialized only once for one SiftGPU inistance
00117         //that is, SIFT parameters will not be changed
00118         int             _initialized;
00119         //_image_loaded indicates if the current images are loaded
00120         int             _image_loaded;
00121         //the name of current input image
00122         char*   _imgpath;
00123         //_outpath containes the name of the output file
00124         char*   _outpath;
00125         //the list of image filenames
00126         ImageList *    _list;
00127         //the texture that holds loaded input image
00128         GLTexInput *   _texImage;
00129         //the SiftPyramid
00130         SiftPyramid *  _pyramid;
00131         //print out the command line options
00132         static void PrintUsage();
00133         //Initialize OpenGL and SIFT paremeters, and create the shaders accordingly
00134         void InitSiftGPU();
00135         //load the image list from a file
00136         void LoadImageList(const char *imlist);
00137 public:
00138         //timing results for 10 steps
00139         float                       _timing[10];
00140     inline const char*  GetCurrentImagePath() {return _imgpath; }
00141 public:
00142         //set the image list for processing
00143         SIFTGPU_EXPORT virtual void SetImageList(int nimage, const char** filelist);
00144         //get the number of SIFT features in current image
00145         SIFTGPU_EXPORT virtual int      GetFeatureNum();
00146         //save the SIFT result as a ANSCII/BINARY file 
00147         SIFTGPU_EXPORT virtual void SaveSIFT(const char * szFileName);
00148         //Copy the SIFT result to two vectors
00149         SIFTGPU_EXPORT virtual void GetFeatureVector(SiftKeypoint * keys, float * descriptors);
00150         //Set keypoint list before running sift to get descriptors
00151         SIFTGPU_EXPORT virtual void SetKeypointList(int num, const SiftKeypoint * keys, int keys_have_orientation = 1);
00152         //Enable downloading results to CPU. 
00153         //create a new OpenGL context for processing
00154         //call VerifyContextGL instead if you want to crate openGL context yourself, or your are 
00155         //mixing mixing siftgpu with other openGL code
00156         SIFTGPU_EXPORT virtual int CreateContextGL();
00157         //verify the current opengl context..
00158         //(for example, you call wglmakecurrent yourself and verify the current context)
00159         SIFTGPU_EXPORT virtual int VerifyContextGL();
00160         //check if all siftgpu functions are supported
00161         SIFTGPU_EXPORT virtual int IsFullSupported();
00162         //set verbose mode
00163         SIFTGPU_EXPORT virtual void SetVerbose(int verbose = 4);
00164         //set SiftGPU to brief display mode, which is faster
00165         inline void SetVerboseBrief(){SetVerbose(2);};
00166         //parse SiftGPU parameters
00167         SIFTGPU_EXPORT virtual void ParseParam(int argc, char **argv);
00168         //run SIFT on a new image given filename
00169         SIFTGPU_EXPORT virtual int  RunSIFT(const char * imgpath);
00170         //run SIFT on an image in the image list given the file index
00171         SIFTGPU_EXPORT virtual int      RunSIFT(int index);
00172         //run SIFT on a new image given the pixel data and format/type;
00173         //gl_format (e.g. GL_LUMINANCE, GL_RGB) is the format of the pixel data
00174         //gl_type (e.g. GL_UNSIGNED_BYTE, GL_FLOAT) is the data type of the pixel data;
00175         //Check glTexImage2D(...format, type,...) for the accepted values
00176         //Using image data of GL_LUMINANCE + GL_UNSIGNED_BYTE can minimize transfer time
00177         SIFTGPU_EXPORT virtual int  RunSIFT(int width, int height,      const void * data, 
00178                                                                                 unsigned int gl_format, unsigned int gl_type);
00179         //run SIFT on current image (specified by arguments), or processing the current image again
00180         SIFTGPU_EXPORT virtual int  RunSIFT();
00181         //run SIFT with keypoints on current image again. 
00182         SIFTGPU_EXPORT virtual int  RunSIFT(int num, const SiftKeypoint * keys, int keys_have_orientation = 1);
00183         //constructor, the parameter np is ignored..
00184         SIFTGPU_EXPORT SiftGPU(int np = 1);
00185         //destructor
00186         SIFTGPU_EXPORT virtual ~SiftGPU();
00187         //set the active pyramid...dropped function
00188     SIFTGPU_EXPORT virtual void SetActivePyramid(int index) {}
00189         //retrieve the number of images in the image list
00190         SIFTGPU_EXPORT virtual int GetImageCount();
00191         //set parameter GlobalUtil::_ForceTightPyramid
00192         SIFTGPU_EXPORT virtual void SetTightPyramid(int tight = 1);
00193         //allocate pyramid for a given size of image
00194         SIFTGPU_EXPORT virtual int AllocatePyramid(int width, int height);
00195         //none of the texture in processing can be larger
00196         //automatic down-sample is used if necessary. 
00197         SIFTGPU_EXPORT virtual void SetMaxDimension(int sz);
00199 public:
00200         //overload the new operator because delete operator is virtual
00201         //and it is operating on the heap inside the dll (due to the 
00202         //compiler setting of /MT and /MTd). Without the overloaded operator
00203         //deleting a SiftGPU object will cause a heap corruption in the 
00204         //static link case (but not for the runtime dll loading).
00205         SIFTGPU_EXPORT void* operator new (size_t size); 
00206 };
00207 
00208 
00209 
00211 //class SIftGPUEX
00212 //description: adds some visualization functions to the interface of SiftGPU
00214 
00215 class SiftGPUEX:public SiftGPU
00216 {
00217         //view mode
00218         int     _view;
00219         //sub view mode
00220         int _sub_view;
00221         //whether display a debug view
00222         int _view_debug;
00223         //colors for SIFT feature display
00224         enum{COLOR_NUM = 36};
00225         float _colors[COLOR_NUM*3];
00226         //display functions
00227         void DisplayInput();    //display gray level image of input image       
00228         void DisplayDebug();    //display debug view
00229         void DisplayFeatureBox(int i);  //display SIFT features
00230         void DisplayLevel(void (*UseDisplayShader)(), int i);           //display one level image
00231         void DisplayOctave(void (*UseDisplayShader)(), int i);          //display all images in one octave
00232         //display different content of Pyramid by specifying different data and display shader
00233         //the first nskip1 levels and the last nskip2 levels are skiped in display
00234         void DisplayPyramid( void (*UseDisplayShader)(), int dataName, int nskip1 = 0, int nskip2 = 0);
00235         //use HSVtoRGB to generate random colors
00236         static void HSVtoRGB(float hsv[3],float rgb[3]);
00237 
00238 public:
00239         SIFTGPU_EXPORT SiftGPUEX();
00240         //change view mode
00241         SIFTGPU_EXPORT void SetView(int view, int sub_view, char * title);
00242         //display current view
00243         SIFTGPU_EXPORT void DisplaySIFT();
00244         //toggle debug mode on/off
00245         SIFTGPU_EXPORT void ToggleDisplayDebug();
00246         //randomize the display colors
00247         SIFTGPU_EXPORT void RandomizeColor();
00248         //retrieve the size of current input image
00249         SIFTGPU_EXPORT void GetImageDimension(int &w, int&h);
00250         //get the location of the window specified by user
00251         SIFTGPU_EXPORT void GetInitWindowPotition(int& x, int& y);
00252 };
00253 
00255 //This is a gpu-based sift match implementation. 
00256 class SiftMatchGPU
00257 {
00258 public:
00259         enum SIFTMATCH_LANGUAGE {
00260                 SIFTMATCH_SAME_AS_SIFTGPU = 0, //when siftgpu already initialized.
00261                 SIFTMATCH_GLSL = 2,
00262                 SIFTMATCH_CUDA = 3,
00263         SIFTMATCH_CUDA_DEVICE0 = 3 //to use device i, use SIFTMATCH_CUDA_DEVICE0 + i
00264         };
00265 private:
00266         int                             __max_sift;
00267         int                             __language;
00268         SiftMatchGPU *  __matcher;
00269         virtual void   InitSiftMatch(){}
00270 protected:
00271         //move the two functions here for derived class
00272         SIFTGPU_EXPORT virtual int  _CreateContextGL();
00273         SIFTGPU_EXPORT virtual int  _VerifyContextGL();
00274 public:
00275         //OpenGL Context creation/verification, initialization is done automatically inside
00276         inline int  CreateContextGL() {return _CreateContextGL();}
00277         inline int  VerifyContextGL() {return _VerifyContextGL();}
00278 
00279         //Consructor, the argument specifies the maximum number of features to match
00280         SIFTGPU_EXPORT SiftMatchGPU(int max_sift = 4096);
00281 
00282         //change gpu_language, check the enumerants in SIFTMATCH_LANGUAGE.
00283         SIFTGPU_EXPORT virtual void SetLanguage(int gpu_language);
00284 
00285     //after calling SetLanguage, you can call SetDeviceParam to select GPU
00286     //-winpos, -display, -cuda [device_id] 
00287     //This is only used when you call CreateContextGL..
00288         //This function doesn't change the language. 
00289     SIFTGPU_EXPORT virtual void SetDeviceParam(int argc, char**argv);
00290 
00291         //change the maximum of features to match whenever you want
00292         SIFTGPU_EXPORT virtual void SetMaxSift(int max_sift);
00293         //desctructor
00294         SIFTGPU_EXPORT virtual ~SiftMatchGPU();
00295 
00296         //Specifiy descriptors to match, index = [0/1] for two features sets respectively
00297         //Option1, use float descriptors, and they be already normalized to 1.0
00298         SIFTGPU_EXPORT virtual void SetDescriptors(int index, int num, const float* descriptors, int id  = -1);
00299         //Option 2 unsigned char descriptors. They must be already normalized to 512
00300         SIFTGPU_EXPORT virtual void SetDescriptors(int index, int num, const unsigned char * descriptors, int id = -1);
00301 
00302         //match two sets of features, the function RETURNS the number of matches.
00303         //Given two normalized descriptor d1,d2, the distance here is acos(d1 *d2);
00304         SIFTGPU_EXPORT virtual int  GetSiftMatch(
00305                                 int max_match,  // the length of the match_buffer.
00306                                 int match_buffer[][2], //buffer to receive the matched feature indices
00307                                 float distmax = 0.7,    //maximum distance of sift descriptor
00308                                 float ratiomax = 0.8,   //maximum distance ratio
00309                                 int mutual_best_match = 1); //mutual best match or one way
00310 
00311         //two functions for guded matching, two constraints can be used 
00312         //one homography and one fundamental matrix, the use is as follows
00313         //1. for each image, first call SetDescriptor then call SetFeatureLocation
00314         //2. Call GetGuidedSiftMatch
00315         //input feature location is a vector of [float x, float y, float skip[gap]]
00316         SIFTGPU_EXPORT virtual void SetFeautreLocation(int index, const float* locations, int gap = 0);
00317         inline void SetFeatureLocation(int index, const SiftGPU::SiftKeypoint * keys)
00318         {
00319                 SetFeautreLocation(index, (const float*) keys, 2);
00320         }
00321 
00322         //use a guiding Homography H and a guiding Fundamental Matrix F to compute feature matches
00323         //the function returns the number of matches.
00324         SIFTGPU_EXPORT virtual int  GetGuidedSiftMatch(
00325                                         int max_match, int match_buffer[][2], //buffer to recieve 
00326                                         float H[3][3],                  //homography matrix,  (Set NULL to skip)
00327                                         float F[3][3],                  //fundamental matrix, (Set NULL to skip)
00328                                         float distmax = 0.7,    //maximum distance of sift descriptor
00329                                         float ratiomax = 0.8,   //maximum distance ratio
00330                                         float hdistmax = 32,    //threshold for |H * x1 - x2|_1 
00331                                         float fdistmax = 16,    //threshold for sampson error of x2'FX1
00332                                         int mutual_best_match = 1); //mutual best or one way
00333 
00334 public:
00335         //overload the new operator, the same reason as SiftGPU above
00336         SIFTGPU_EXPORT void* operator new (size_t size);
00337 };
00338 
00339 typedef SiftGPU::SiftKeypoint SiftKeypoint;
00340 
00341 //Two exported global functions used to create SiftGPU and SiftMatchGPU
00342 SIFTGPU_EXPORT_EXTERN SiftGPU * CreateNewSiftGPU(int np =1);
00343 SIFTGPU_EXPORT_EXTERN SiftMatchGPU* CreateNewSiftMatchGPU(int max_sift = 4096);
00344 
00345 
00347 class ComboSiftGPU: public SiftGPU, public SiftMatchGPU 
00348 {
00349 public:
00351         SIFTGPU_EXPORT void* operator new (size_t size); 
00352 };
00353 SIFTGPU_EXPORT_EXTERN ComboSiftGPU* CreateComboSiftGPU(); 
00354 
00356 //Multi-process mode and remote mode
00357 SIFTGPU_EXPORT_EXTERN ComboSiftGPU* CreateRemoteSiftGPU(int port = 7777, char* remote_server = NULL);
00358 //Run SiftGPU computation on a remote computer/process/thread
00359 //if( remote_server == NULL) 
00360 //                      a local server is created in a different process and connected
00361 //                      multiple-GPU can be used by creating multiple instances
00362 //                      GPU selection done through SiftGPU::ParseParam function
00363 //otherwise, 
00364 //                      Assumes the existenc of a remote server and connects to it
00365 //                      GPU selection skipped if already done on the server-end
00366 //                      RUN server: server_siftgpu -server port [siftgpu_param]
00367 //example:
00368 //      ComboSiftGPU * combo = CreateRemoteSiftGPU(7777, "my.gpuserver.com");
00369 //      SiftGPU* siftgpu = combo, SiftMatchGPU * matcher = combo;
00370 //  siftgpu->ParseParam... siftgpu->CreateContextGL..
00371 //  matcher->SetLanguage...matcher->VerifyContextGL...
00372 //  // GPU-selection is done throught siftgpu->ParseParam, 
00373 //  // it doesn't really initialize SiftGPU untill you call CreateContextGL/VerifyContextGL
00374 //  delete combo;
00375 
00377 //two internally used function.
00378 SIFTGPU_EXPORT int  CreateLiteWindow(LiteWindow* window);
00379 SIFTGPU_EXPORT void RunServerLoop(int port, int argc, char** argv);
00380 #endif 


siftgpu
Author(s): Changchang Wu
autogenerated on Wed Aug 26 2015 15:24:06