INSTALLATION

First make sure all dependencies are satisfied.
Extract the tarball to a local folder ($INSTALL).
The static GPU-Surf libraries (libncgl+libsurf) are located in $INSTALL/libncgl/lib/Release and $INSTALL/libsurf/lib/Release respectively.

Source code for an example application using the GPU-Surf library is provided in $INSTALL/gpusurf. Use the following steps to compile it:

1. Make changes to the $INSTALL/settings.mk file where necessary to point to the correct include directories and libraries.

2. Go to the folder $INSTALL/gpusurf and run 'make'. This will create the executable in $INSTALL/gpusurf/bin/Release/gpusurf

3. run "./bin/Release/gpusurf -h" for help.

USAGE

The example application accepts the following parameters:

-i : in-place descriptor files. Writes each descriptor file to the same directory as its corresponding input image.

-o outputdir : write each descriptor file to directory "outputdir".

-t thresh : set blob-response threshold to value "thresh".

-u : UP-Surf, bypasses rotation assignment (not rotation invariant).

-d : display result (for single image only). Useful for debugging and threshold value selection.

-q : quiet mode. Minimizes info sent to standard output.

-kp keypointfile : extracts descriptors for predefined feature locations stored in "keypointfile".

INPUT

When using the static GPU-Surf library from a C++ application, there are two ways to specify image data:

1. surfer->loadImage(imagefile); Loads an image stored on disk using ImageMagick.

2. surfer->loadMemoryImage(format, w, h, imdata); Loads an image stored in system memory. imdata is a pointer to an array of unsigned bytes. w and h specify the image dimensions. format can be one of "RGBA","RGB","BGRA","BGR" or "I". For single channel data (8bpp intensity), this format is "I". For color data, the preferred format is "BGRA".

The keypoint file used for extracting descriptors at predefined feature locations is an ASCII file with the following format:

image_width image_height
#features
x_1 y_1 r_1
x_2 y_2 r_3
...
x_#features y_#features r_#features

where x_i and y_i are the feature locations in pixel units. (x_i,y_i) = (0.0,0.0) corresponds to the top left corner of the top left pixel. r_i is a scalar value representing the radius to be used for calculating the descriptor. e.g. a radius of 8 corresponds to a descriptor-region of 16x16 pixels.

OUTPUT

The descriptor outputs are written to a featuredata structure in binary format. The header file for this data structure is located at $INSTALL/libsurf/inc/featuredata.hpp and has the following form:

file.read((char*)&imw,sizeof(unsigned int));
file.read((char*)&imh,sizeof(unsigned int));
file.read((char*)&nrf,sizeof(unsigned int));
file.read((char*)&nrsubregions,sizeof(int));
posdata = new float[nrf*4];
file.read((char*)&posdata[0],nrf*4*sizeof(float));
desc_data = new float[nrf*nrsubregions*nrsubregions*4];
file.read((char*)&desc_data[0],nrf*nrsubregions*nrsubregions*4*sizeof(float));

with

imw : image width
imh : image height
nrf : number of extracted features
nrsubregions: number of descriptor subregions (currently fixed to 4)
posdata array storing feature information with 4 components per feature
posdata[4*i+0]x-location of feature i
posdata[4*i+1]y-location of feature i
posdata[4*i+2] descriptor radius used for feature i
posdata[4*i+3] characteristic rotation angle assigned to feature i
desc_data: array with nrf*64 values to store feature descriptors.
desc_data[64*i] - desc_data[64*i+63]: feature descriptor for feature i