ViSP  2.9.0
vpKeyPointSurf Class Reference

#include <vpKeyPointSurf.h>

+ Inheritance diagram for vpKeyPointSurf:

Public Types

enum  vpDescriptorType { basicDescriptor, extendedDescriptor }
 

Public Member Functions

 vpKeyPointSurf ()
 
virtual ~vpKeyPointSurf ()
 
unsigned int buildReference (const vpImage< unsigned char > &I)
 
unsigned int buildReference (const vpImage< unsigned char > &I, const vpImagePoint &iP, const unsigned int height, const unsigned int width)
 
unsigned int buildReference (const vpImage< unsigned char > &I, const vpRect &rectangle)
 
unsigned int matchPoint (const vpImage< unsigned char > &I)
 
unsigned int matchPoint (const vpImage< unsigned char > &I, const vpImagePoint &iP, const unsigned int height, const unsigned int width)
 
unsigned int matchPoint (const vpImage< unsigned char > &I, const vpRect &rectangle)
 
void display (const vpImage< unsigned char > &Iref, const vpImage< unsigned char > &Icurrent, unsigned int size=3)
 
void display (const vpImage< unsigned char > &Icurrent, unsigned int size=3, const vpColor &color=vpColor::green)
 
std::list< int * > * matchPoint (std::list< float * > descriptorList, std::list< int > laplacianList)
 
float * getDescriptorReferencePoint (const int index)
 
int getLaplacianReferencePoint (const int index)
 
void getDescriptorParamReferencePoint (const int index, int &size, float &dir)
 
void setHessianThreshold (double hessian_threshold)
 
void setDescriptorType (vpDescriptorType descriptor_type)
 
double getHessianThreshold ()
 
vpDescriptorType getDescriptorType ()
 
bool referenceBuilt () const
 
const vpImagePointgetAllPointsInReferenceImage ()
 
void getReferencePoint (const unsigned int index, vpImagePoint &referencePoint)
 
void getMatchedPoints (const unsigned int index, vpImagePoint &referencePoint, vpImagePoint &currentPoint)
 
unsigned int getIndexInAllReferencePointList (const unsigned int indexInMatchedPointList)
 
unsigned int getReferencePointNumber () const
 
unsigned int getMatchedPointNumber () const
 
const std::vector< vpImagePoint > & getReferenceImagePointsList () const
 
const std::vector< vpImagePoint > & getCurrentImagePointsList () const
 
const std::vector< unsigned int > & getMatchedReferencePoints () const
 

Protected Attributes

std::vector< vpImagePointreferenceImagePointsList
 
std::vector< vpImagePointcurrentImagePointsList
 
std::vector< unsigned int > matchedReferencePoints
 
bool _reference_computed
 

Deprecated functions

vp_deprecated vpList< int * > * matchPoint (vpList< float * > descriptorList, vpList< int > laplacianList)
 

Detailed Description

Class that implements the SURF key points and technics thanks to the OpenCV library.

The goal of this class is to provide a tool to match points from a model and points belonging to an image in which the model appears. The coordinates of the different reference points and matched points are given in pixel thanks to the class vpImagePoint. In this documentation we do not explain the SURF technics. So if you want to learn more about it you can refer to the following article : Herbert Bay, Tinne Tuytelaars and Luc Van Gool "SURF: Speeded Up Robust Features", Proceedings of the 9th European Conference on Computer Vision, Springer LNCS volume 3951, part 1, pp 404–417, 2006.

If you use this class the first things you have to do is to create the reference thanks to a reference image which contains the interesting object to detect. Then you have to grab other images containing the object. After calling the specific method to match points you can access to the lists of matched points thanks to the methods getMatchedPointsInReferenceImage() and getMatchedPointsInCurrentImage(). These two methods return a list of matched points. The nth element of the first list is matched with the nth element of the second list. The following small example show how to use the class.

#include <visp/vpConfig.h>
#include <visp/vpImage.h>
#include <visp/vpKeyPointSurf.h>
#if VISP_HAVE_OPENCV_VERSION >= 0x010100 // Surf key-points only available since OpenCV-1.1.0
int main()
{
//First grab the reference image Ireference
//Build the reference SURF points.
surf.buildReference(Ireference);
//Then grab another image which represents the current image Icurrent
//Match points between the reference points and the SURF points computed in the current image.
surf.matchPoint(Icurrent);
//Display the matched points
surf.display(Ireference, Icurrent);
return (0);
}
#else
int main() {}
#endif

It is also possible to create the reference thanks to only a part of the reference image (not the whole image) and find points to match in only a part of the current image. The small following example shows how to this

#include <visp/vpConfig.h>
#include <visp/vpImage.h>
#include <visp/vpDisplay.h>
#include <visp/vpKeyPointSurf.h>
#if VISP_HAVE_OPENCV_VERSION >= 0x010100 // Surf key-points only available since OpenCV-1.1.0
int main()
{
//First grab the reference image Ireference
//Select a part of the image by clincking on two points which define a rectangle
vpImagePoint corners[2];
for (int i=0 ; i < 2 ; i++)
{
vpDisplay::getClick(Ireference, corners[i]);
}
//Build the reference SURF points.
int nbrRef;
unsigned int height, width;
height = (unsigned int)(corners[1].get_i() - corners[0].get_i());
width = (unsigned int)(corners[1].get_j() - corners[0].get_j());
nbrRef = surf.buildReference(Ireference, corners[0], height, width);
//Then grab another image which represents the current image Icurrent
//Select a part of the image by clincking on two points which define a rectangle
for (int i=0 ; i < 2 ; i++)
{
vpDisplay::getClick(Icurrent, corners[i]);
}
//Match points between the reference points and the SURF points computed in the current image.
int nbrMatched;
height = (unsigned int)(corners[1].get_i() - corners[0].get_i());
width = (unsigned int)(corners[1].get_j() - corners[0].get_j());
nbrMatched = surf.matchPoint(Icurrent, corners[0], height, width);
//Display the matched points
surf.display(Ireference, Icurrent);
return(0);
}
#else
int main() {}
#endif

This class is also described in Tutorial: Keypoint matching.

Examples:
keyPointSurf.cpp, testSurfKeyPoint.cpp, tutorial-matching-surf-homography.cpp, and tutorial-matching-surf.cpp.

Definition at line 195 of file vpKeyPointSurf.h.

Member Enumeration Documentation

This enumerate enables to set the detail level of the descriptors.

Enumerator
basicDescriptor 
extendedDescriptor 

Definition at line 202 of file vpKeyPointSurf.h.

Constructor & Destructor Documentation

vpKeyPointSurf::vpKeyPointSurf ( )

Basic constructor. It sets by default the hessian threshold to 500 (a good default value is between 300 and 500) and the descriptor type to extended.

Definition at line 202 of file vpKeyPointSurf.cpp.

vpKeyPointSurf::~vpKeyPointSurf ( )
virtual

Basic Destructor

Definition at line 227 of file vpKeyPointSurf.cpp.

Member Function Documentation

unsigned int vpKeyPointSurf::buildReference ( const vpImage< unsigned char > &  I)
virtual

Build the list of reference points. The computation of the points is made all over the image I.

Parameters
I: The gray scaled image where the reference points are computed.
Returns
the number of reference points.

Implements vpBasicKeyPoint.

Examples:
keyPointSurf.cpp, testSurfKeyPoint.cpp, tutorial-matching-surf-homography.cpp, and tutorial-matching-surf.cpp.

Definition at line 244 of file vpKeyPointSurf.cpp.

References vpBasicKeyPoint::_reference_computed, vpImage< Type >::bitmap, vpImageConvert::convert(), vpImage< Type >::getHeight(), vpImage< Type >::getWidth(), and vpBasicKeyPoint::referenceImagePointsList.

Referenced by buildReference().

unsigned int vpKeyPointSurf::buildReference ( const vpImage< unsigned char > &  I,
const vpImagePoint iP,
const unsigned int  height,
const unsigned int  width 
)
virtual

Build the list of reference points. The computation of the points is made only on a part of the image. This part is a rectangle defined by its top left corner, its height and its width. The parameters of this rectangle must be given in pixel.

Parameters
I: The gray scaled image where the reference points are computed.
iP: The top left corner of the rectangle.
height: height of the rectangle (in pixel).
width: width of the rectangle (in pixel).
Returns
the number of reference points.

Implements vpBasicKeyPoint.

Definition at line 301 of file vpKeyPointSurf.cpp.

References buildReference(), vpImageTools::createSubImage(), vpImagePoint::get_i(), vpImagePoint::get_j(), vpImage< Type >::getHeight(), vpImage< Type >::getWidth(), vpImageException::notInTheImage, vpBasicKeyPoint::referenceImagePointsList, and vpTRACE.

unsigned int vpKeyPointSurf::buildReference ( const vpImage< unsigned char > &  I,
const vpRect rectangle 
)
virtual

Build the list of reference points. The computation of the points is made only on a part of the image. This part is a rectangle. The parameters of this rectangle must be given in pixel.

Parameters
I: The gray scaled image where the reference points are computed.
rectangle: The rectangle which defines the interesting part of the image.
Returns
the number of reference points.

Implements vpBasicKeyPoint.

Definition at line 346 of file vpKeyPointSurf.cpp.

References buildReference(), vpRect::getHeight(), vpRect::getLeft(), vpRect::getTop(), vpRect::getWidth(), vpImagePoint::set_i(), and vpImagePoint::set_j().

void vpKeyPointSurf::display ( const vpImage< unsigned char > &  Ireference,
const vpImage< unsigned char > &  Icurrent,
unsigned int  size = 3 
)
virtual

This function displays the matched reference points and the matched points computed in the current image. The reference points are displayed in the image Ireference and the matched points coming from the current image are displayed in the image Icurrent. It is possible to set Ireference and Icurrent with the same image when calling the method.

Parameters
Ireference: The image where the matched reference points are displayed.
Icurrent: The image where the matched points computed in the current image are displayed.
size: Size in pixels of the cross that is used to display matched points.

Implements vpBasicKeyPoint.

Examples:
keyPointSurf.cpp, and testSurfKeyPoint.cpp.

Definition at line 555 of file vpKeyPointSurf.cpp.

References vpBasicKeyPoint::currentImagePointsList, vpDisplay::displayCross(), vpColor::green, vpBasicKeyPoint::matchedReferencePoints, vpColor::red, and vpBasicKeyPoint::referenceImagePointsList.

void vpKeyPointSurf::display ( const vpImage< unsigned char > &  Icurrent,
unsigned int  size = 3,
const vpColor color = vpColor::green 
)
virtual

This function displays only the matched points computed in the current image. They are displayed in the image Icurrent.

Parameters
Icurrent: The image where the matched points computed in the current image are displayed.
size: Size in pixels of the cross that is used to display matched points.
color: Color used to display the matched points.

Implements vpBasicKeyPoint.

Definition at line 590 of file vpKeyPointSurf.cpp.

References vpBasicKeyPoint::currentImagePointsList, vpDisplay::displayCross(), and vpBasicKeyPoint::matchedReferencePoints.

const vpImagePoint* vpBasicKeyPoint::getAllPointsInReferenceImage ( )
inlineinherited

Get the pointer to the complete list of reference points. The pointer is const. Thus the points can not be modified

Returns
The pointer to the complete list of reference points.

Definition at line 115 of file vpBasicKeyPoint.h.

const std::vector<vpImagePoint>& vpBasicKeyPoint::getCurrentImagePointsList ( ) const
inlineinherited

Return the vector of current image point.

Warning
Should not be modified.
Returns
Vector of the current image point.

Definition at line 212 of file vpBasicKeyPoint.h.

void vpKeyPointSurf::getDescriptorParamReferencePoint ( const int  index,
int &  size,
float &  dir 
)

Get the parameters of the descriptor of the nth reference point.

Parameters
index: The index of the desired reference point. The index must be between 0 and the number of reference points - 1.
size: The size of the point used to compute the descriptor.
dir: The orientation of the descriptor (in degree).

Definition at line 759 of file vpKeyPointSurf.cpp.

References vpException::fatalError, vpBasicKeyPoint::referenceImagePointsList, and vpTRACE.

float * vpKeyPointSurf::getDescriptorReferencePoint ( const int  index)

Get the descriptor of the nth reference point.

Parameters
index: The index of the desired reference point. The index must be between 0 and the number of reference points - 1.

Definition at line 700 of file vpKeyPointSurf.cpp.

References vpException::fatalError, vpBasicKeyPoint::referenceImagePointsList, and vpTRACE.

vpDescriptorType vpKeyPointSurf::getDescriptorType ( )
inline

Gets the type of descriptor used.

Returns
the type of descriptor used.

Definition at line 274 of file vpKeyPointSurf.h.

double vpKeyPointSurf::getHessianThreshold ( )
inline

Gets the value of the hessian threhold.

Returns
the hessian threshold value.

Definition at line 267 of file vpKeyPointSurf.h.

unsigned int vpBasicKeyPoint::getIndexInAllReferencePointList ( const unsigned int  indexInMatchedPointList)
inlineinherited

Get the nth matched reference point index in the complete list of reference point.

In the code below referencePoint1 and referencePoint2 correspond to the same matched reference point.

//Here the code to compute the reference points and the current points.
vpImagePoint referencePoint1;
vpImagePoint currentPoint;
surf.getMatchedPoints(1, referencePoint1, currentPoint); //Get the first matched points
vpImagePoint referencePoint2;
const vpImagePoint* referencePointsList = surf.getAllPointsInReferenceImage();
int index = surf.getIndexInAllReferencePointList(1); //Get the first matched reference point index in the complete reference point list
referencePoint2 = referencePointsList[index]; //Get the first matched reference point

Definition at line 173 of file vpBasicKeyPoint.h.

References vpException::fatalError, and vpTRACE.

int vpKeyPointSurf::getLaplacianReferencePoint ( const int  index)

Get the laplacian of the nth reference point.

Parameters
index: The index of the desired reference point. The index must be between 0 and the number of reference points - 1.

Definition at line 728 of file vpKeyPointSurf.cpp.

References vpException::fatalError, vpBasicKeyPoint::referenceImagePointsList, and vpTRACE.

unsigned int vpBasicKeyPoint::getMatchedPointNumber ( ) const
inlineinherited

Get the number of matched points.

Returns
the number of matched points.

Definition at line 194 of file vpBasicKeyPoint.h.

void vpBasicKeyPoint::getMatchedPoints ( const unsigned int  index,
vpImagePoint referencePoint,
vpImagePoint currentPoint 
)
inlineinherited

Get the nth couple of reference point and current point which have been matched. These points are copied in the vpImagePoint instances given in argument.

Parameters
index: The index of the desired couple of reference point and current point . The index must be between 0 and the number of matched points - 1.
referencePoint: The coordinates of the desired reference point are copied here.
currentPoint: The coordinates of the desired current point are copied here.
Examples:
tutorial-matching-surf-homography.cpp, and tutorial-matching-surf.cpp.

Definition at line 143 of file vpBasicKeyPoint.h.

References vpException::fatalError, vpImagePoint::set_ij(), and vpTRACE.

const std::vector<unsigned int>& vpBasicKeyPoint::getMatchedReferencePoints ( ) const
inlineinherited

Return the index of the matched associated to the current image point i. The ith element of the vector is the index of the reference image point matching with the current image point.

Warning
Should not be modified.
Returns
The vector of matching index.

Definition at line 223 of file vpBasicKeyPoint.h.

const std::vector<vpImagePoint>& vpBasicKeyPoint::getReferenceImagePointsList ( ) const
inlineinherited

Return the vector of reference image point.

Warning
Should not be modified.
Returns
Vector of reference image point.

Definition at line 203 of file vpBasicKeyPoint.h.

void vpBasicKeyPoint::getReferencePoint ( const unsigned int  index,
vpImagePoint referencePoint 
)
inlineinherited

Get the nth reference point. This point is copied in the vpImagePoint instance given in argument.

Parameters
index: The index of the desired reference point. The index must be between 0 and the number of reference points - 1.
referencePoint: The coordinates of the desired reference point are copied there.

Definition at line 125 of file vpBasicKeyPoint.h.

References vpException::fatalError, vpImagePoint::set_ij(), and vpTRACE.

unsigned int vpBasicKeyPoint::getReferencePointNumber ( ) const
inlineinherited

Get the number of reference points.

Returns
the number of reference points.

Definition at line 187 of file vpBasicKeyPoint.h.

unsigned int vpKeyPointSurf::matchPoint ( const vpImage< unsigned char > &  I)
virtual

Computes the SURF points in the current image I and try to matched them with the points in the reference list. Only the matched points are stored.

Parameters
I: The gray scaled image where the points are computed.
Returns
the number of point which have been matched.

Implements vpBasicKeyPoint.

Examples:
keyPointSurf.cpp, testSurfKeyPoint.cpp, tutorial-matching-surf-homography.cpp, and tutorial-matching-surf.cpp.

Definition at line 368 of file vpKeyPointSurf.cpp.

References vpImage< Type >::bitmap, vpImageConvert::convert(), vpBasicKeyPoint::currentImagePointsList, vpImage< Type >::getHeight(), vpImage< Type >::getWidth(), and vpBasicKeyPoint::matchedReferencePoints.

Referenced by matchPoint().

unsigned int vpKeyPointSurf::matchPoint ( const vpImage< unsigned char > &  I,
const vpImagePoint iP,
const unsigned int  height,
const unsigned int  width 
)
virtual

Computes the SURF points in only a part of the current image I and try to matched them with the points in the reference list. The part of the image is a rectangle defined by its top left corner, its height and its width. The parameters of this rectangle must be given in pixel. Only the matched points are stored.

Parameters
I: The gray scaled image where the points are computed.
iP: The top left corner of the rectangle.
height: height of the rectangle (in pixel).
width: width of the rectangle (in pixel).
Returns
the number of point which have been matched.

Implements vpBasicKeyPoint.

Definition at line 478 of file vpKeyPointSurf.cpp.

References vpImageTools::createSubImage(), vpBasicKeyPoint::currentImagePointsList, vpImagePoint::get_i(), vpImagePoint::get_j(), vpImage< Type >::getHeight(), vpImage< Type >::getWidth(), matchPoint(), vpImageException::notInTheImage, and vpTRACE.

unsigned int vpKeyPointSurf::matchPoint ( const vpImage< unsigned char > &  I,
const vpRect rectangle 
)
virtual

Computes the SURF points in only a part of the current image I and try to matched them with the points in the reference list. The part of the image is a rectangle. The parameters of this rectangle must be given in pixel. Only the matched points are stored.

Parameters
I: The gray scaled image where the points are computed.
rectangle: The rectangle which defines the interesting part of the image.
Returns
the number of point which have been matched.

Implements vpBasicKeyPoint.

Definition at line 525 of file vpKeyPointSurf.cpp.

References vpRect::getHeight(), vpRect::getLeft(), vpRect::getTop(), vpRect::getWidth(), matchPoint(), vpImagePoint::set_i(), and vpImagePoint::set_j().

std::list< int * > * vpKeyPointSurf::matchPoint ( std::list< float * >  descriptorList,
std::list< int >  laplacianList 
)

Definition at line 659 of file vpKeyPointSurf.cpp.

References vpTRACE.

vp_deprecated vpList< int * > * vpKeyPointSurf::matchPoint ( vpList< float * >  descriptorList,
vpList< int >  laplacianList 
)
Deprecated:
This method is deprecated, you should use matchPoint(std::list<float*> , std::list<int> ) instead.

Computes the SURF points given by their descriptor and laplacian and try to match them with the points in the reference list. Only the matched points are stored. The two lists must have the same number of element while they correspond the same unique list of point.

Warning
The list returned contains allocated data (2 int per element). Must be deleted to avoid memory leak.
Parameters
descriptorList: The list of the descriptor
laplacianList: The list of laplacian
Returns
the list of the pair, the first element contains the index in the reference sequence and the second element contains the index in the list given in parameter.

Definition at line 622 of file vpKeyPointSurf.cpp.

References vpList< type >::addRight(), vpList< type >::front(), vpList< type >::nb, vpList< type >::next(), vpList< type >::outside(), vpList< type >::value(), and vpTRACE.

bool vpBasicKeyPoint::referenceBuilt ( ) const
inlineinherited

Indicate wether the reference has been built or not.

Returns
True if the reference of the current instance has been built.

Definition at line 108 of file vpBasicKeyPoint.h.

void vpKeyPointSurf::setDescriptorType ( vpDescriptorType  descriptor_type)
inline

Sets the type of descriptors to use.

Parameters
descriptor_type: Type of descriptor to use.

Definition at line 257 of file vpKeyPointSurf.h.

void vpKeyPointSurf::setHessianThreshold ( double  hessian_threshold)
inline

Sets the value of the hessian threhold. Note that during the computation of the hessian for each potential points, only the points which have a hessian value higher than the threshold are keeped. Fore more details about the threshold see the article Herbert Bay, Tinne Tuytelaars and Luc Van Gool "SURF: Speeded Up Robust Features", Proceedings of the 9th European Conference on Computer Vision, Springer LNCS volume 3951, part 1, pp 404–417, 2006.

Parameters
hessian_threshold: Desired hessian threshold value.

Definition at line 246 of file vpKeyPointSurf.h.

Member Data Documentation

bool vpBasicKeyPoint::_reference_computed
protectedinherited

flag to indicate if the reference has been built.

Definition at line 249 of file vpBasicKeyPoint.h.

Referenced by buildReference(), and vpFernClassifier::buildReference().

std::vector<vpImagePoint> vpBasicKeyPoint::currentImagePointsList
protectedinherited

List of the points which belong to the current image and have been matched with points belonging to the reference.

Definition at line 238 of file vpBasicKeyPoint.h.

Referenced by display(), vpFernClassifier::display(), matchPoint(), and vpFernClassifier::matchPoint().

std::vector<unsigned int> vpBasicKeyPoint::matchedReferencePoints
protectedinherited

Array containing the index in the array "referenceImagePointsList" of the reference points which have been matched.

The first element of the "currentImagePointsList" array is matched with the nth element of the "referenceImagePointsList" array. The value of n is stored in the first element of the "matchedReferencePoints" array.

Definition at line 246 of file vpBasicKeyPoint.h.

Referenced by display(), vpFernClassifier::display(), matchPoint(), and vpFernClassifier::matchPoint().

std::vector<vpImagePoint> vpBasicKeyPoint::referenceImagePointsList
protectedinherited