#include <visp3/vision/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

Detailed Description

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

Deprecated:: This class is deprecated with OpenCV 3.0.0 or more recent. You should rather use vpKeyPoint class that is more generic.

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 <visp3/core/vpConfig.h>
#include <visp3/core/vpImage.h>
#include <visp3/vision/vpKeyPointSurf.h>
int main()
{
#if defined (VISP_HAVE_OPENCV_NONFREE) && (VISP_HAVE_OPENCV_VERSION < 0x030000)
  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);
#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 <visp3/core/vpConfig.h>
#include <visp3/core/vpImage.h>
#include <visp3/core/vpDisplay.h>
#include <visp3/vision/vpKeyPointSurf.h>
int main()
{
#if defined (VISP_HAVE_OPENCV_NONFREE) && (VISP_HAVE_OPENCV_VERSION < 0x030000)
  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);
#endif
}

This class is also described in Tutorial: Keypoints matching.

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

Definition at line 188 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 195 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 197 of file vpKeyPointSurf.cpp.

vpKeyPointSurf::~vpKeyPointSurf ( )

virtual

Basic Destructor

Definition at line 222 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-deprecated.cpp, and tutorial-matching-surf-homography-deprecated.cpp.

Definition at line 239 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 296 of file vpKeyPointSurf.cpp.

References buildReference(), vpImageTools::crop(), 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 341 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 550 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 585 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 110 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 207 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 697 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 638 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 267 of file vpKeyPointSurf.h.

double vpKeyPointSurf::getHessianThreshold ( )

inline

Gets the value of the hessian threhold.

Returns: the hessian threshold value.

Definition at line 260 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 168 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 666 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 189 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-keypoint-homography.cpp, tutorial-matching-keypoint-SIFT.cpp, tutorial-matching-keypoint.cpp, tutorial-matching-surf-deprecated.cpp, and tutorial-matching-surf-homography-deprecated.cpp.

Definition at line 138 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 218 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 198 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 120 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 182 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-deprecated.cpp, and tutorial-matching-surf-homography-deprecated.cpp.

Definition at line 363 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 473 of file vpKeyPointSurf.cpp.

References vpImageTools::crop(), 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 520 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 597 of file vpKeyPointSurf.cpp.

References 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 103 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 250 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 239 of file vpKeyPointSurf.h.

Member Data Documentation

bool vpBasicKeyPoint::_reference_computed

protectedinherited

flag to indicate if the reference has been built.

Definition at line 244 of file vpBasicKeyPoint.h.

Referenced by buildReference(), vpFernClassifier::buildReference(), vpKeyPoint::buildReference(), vpKeyPoint::loadLearningData(), vpKeyPoint::matchPoint(), and vpKeyPoint::reset().

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 233 of file vpBasicKeyPoint.h.

Referenced by display(), vpFernClassifier::display(), vpKeyPoint::getQueryKeyPoints(), matchPoint(), vpFernClassifier::matchPoint(), vpKeyPoint::matchPoint(), and vpKeyPoint::reset().

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 241 of file vpBasicKeyPoint.h.

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

std::vector<vpImagePoint> vpBasicKeyPoint::referenceImagePointsList

protectedinherited

List of the points which define the reference.

Definition at line 227 of file vpBasicKeyPoint.h.

Referenced by buildReference(), vpKeyPoint::buildReference(), display(), vpFernClassifier::display(), getDescriptorParamReferencePoint(), getDescriptorReferencePoint(), getLaplacianReferencePoint(), vpKeyPoint::getTrainKeyPoints(), vpKeyPoint::loadLearningData(), vpKeyPoint::reset(), and vpFernClassifier::train().

Public Types

Public Member Functions

Protected Attributes

Detailed Description

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation