// Copyright (C) 2009 Davis E. King (davis@dlib.net)
// License: Boost Software License See LICENSE.txt for the full license.
#undef DLIB_SURf_ABSTRACT_H_
#ifdef DLIB_SURf_ABSTRACT_H_
#include "hessian_pyramid_abstract.h"
#include "../geometry/vector_abstract.h"
#include "../matrix/matrix_abstract.h"
#include "../image_processing/generic_image.h"
namespace dlib
{
/*
The functions in this file implement the components of the SURF algorithm
for extracting scale invariant feature descriptors from images.
For the full story on what this algorithm does and how it works
you should refer to the following papers.
This is the original paper which introduced the algorithm:
SURF: Speeded Up Robust Features
By Herbert Bay, Tinne Tuytelaars, and Luc Van Gool
This paper provides a nice detailed overview of how the algorithm works:
Notes on the OpenSURF Library by Christopher Evans
*/
// ----------------------------------------------------------------------------------------
double gaussian (
double x,
double y,
double sig
);
/*!
requires
- sig > 0
ensures
- computes and returns the value of a 2D Gaussian function with mean 0
and standard deviation sig at the given (x,y) point.
!*/
// ----------------------------------------------------------------------------------------
template <typename integral_image_type, typename T>
double compute_dominant_angle (
const integral_image_type& img,
const dlib::vector<T,2>& center,
const double& scale
);
/*!
requires
- integral_image_type == an object such as dlib::integral_image or another
type that implements the interface defined in image_transforms/integral_image_abstract.h
- scale > 0
- get_rect(img).contains(centered_rect(center, 17*scale, 17*scale)) == true
(i.e. center can't be within 17*scale pixels of the edge of the image)
ensures
- computes and returns the dominant angle (i.e. the angle of the dominant gradient)
at the given center point and scale in img.
- The returned angle is in radians. Specifically, if the angle is described by
a vector vect then the angle is exactly the value of std::atan2(vect.y(), vect.x())
!*/
// ----------------------------------------------------------------------------------------
template <typename integral_image_type, typename T, typename MM, typename L>
void compute_surf_descriptor (
const integral_image_type& img,
const dlib::vector<T,2>& center,
const double scale,
const double angle,
matrix<double,64,1,MM,L>& des
)
/*!
requires
- integral_image_type == an object such as dlib::integral_image or another
type that implements the interface defined in image_transforms/integral_image_abstract.h
- scale > 0
- get_rect(img).contains(centered_rect(center, 32*scale, 32*scale)) == true
(i.e. center can't be within 32*scale pixels of the edge of the image)
ensures
- computes the 64 dimensional SURF descriptor vector of a box centered
at the given center point, tilted at an angle determined by the given
angle, and sized according to the given scale.
- #des == the computed SURF descriptor vector extracted from the img object.
- The angle is measured in radians and measures the degree of counter-clockwise
rotation around the center point. This is the same kind of rotation as is
performed by the dlib::rotate_point() function.
!*/
// ----------------------------------------------------------------------------------------
struct surf_point
{
/*!
WHAT THIS OBJECT REPRESENTS
This object represents a detected SURF point. The meanings of
its fields are defined below in the get_surf_points() function.
!*/
interest_point p;
matrix<double,64,1> des;
double angle;
};
// ----------------------------------------------------------------------------------------
void serialize (
const surf_point& item,
std::ostream& out
);
/*!
provides serialization support
!*/
void deserialize (
surf_point& item,
std::istream& in
);
/*!
provides serialization support
!*/
// ----------------------------------------------------------------------------------------
template <typename image_type>
const std::vector<surf_point> get_surf_points (
const image_type& img,
long max_points = 10000,
double detection_threshold = 30.0
);
/*!
requires
- max_points > 0
- detection_threshold >= 0
- image_type == an image object that implements the interface defined in
dlib/image_processing/generic_image.h
- Let P denote the type of pixel in img, then we require:
- pixel_traits<P>::has_alpha == false
ensures
- This function runs the complete SURF algorithm on the given input image and
returns the points it found.
- returns a vector V such that:
- V.size() <= max_points
- for all valid i:
- V[i] == a SURF point found in the given input image img
- V[i].p == the interest_point extracted from the hessian pyramid for this
SURF point.
- V[i].des == the SURF descriptor for this point (calculated using
compute_surf_descriptor())
- V[i].angle == the angle of the SURF box at this point (calculated using
compute_dominant_angle())
- V[i].p.score >= detection_threshold
!*/
// ----------------------------------------------------------------------------------------
}
#endif // DLIB_SURf_ABSTRACT_H_