#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 vpImagePoint *	getAllPointsInReferenceImage ()

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< vpImagePoint >	referenceImagePointsList

std::vector< vpImagePoint >	currentImagePointsList

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()
{
  vpImage<unsigned char> Ireference;
  vpImage<unsigned char> Icurrent;
  vpKeyPointSurf surf;
  //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()
{
  vpImage<unsigned char> Ireference;
  vpImage<unsigned char> Icurrent;
  vpKeyPointSurf surf;
  //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

enum vpKeyPointSurf::vpDescriptorType

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.

vpKeyPointSurf surf;
//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

List of the points which define the reference.

Definition at line 232 of file vpBasicKeyPoint.h.

Referenced by buildReference(), display(), vpFernClassifier::display(), getDescriptorParamReferencePoint(), getDescriptorReferencePoint(), getLaplacianReferencePoint(), and vpFernClassifier::train().

Public Types

Public Member Functions

Protected Attributes

Deprecated functions

Detailed Description

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation