Covariant feature detectors (Covariant feature detectors) More...

#include "generic.h"
#include "stringop.h"
#include "scalespace.h"
#include <stdio.h>

Include dependency graph for covdet.h:

This graph shows which files directly or indirectly include this file:

Classes
struct	_VlCovDetFeature
	A detected feature shape and location. More...
struct	_VlCovDetFeatureLaplacianScale
	A detected feature Laplacian scale. More...
struct	_VlCovDetFeatureOrientation
	A detected feature orientation. More...
struct	_VlFrameDisc
	Disc feature frame. More...
struct	_VlFrameEllipse
	Ellipse feature frame. More...
struct	_VlFrameOrientedDisc
	Oriented disc feature frame An upright frame has `angle` equal to zero. More...
struct	_VlFrameOrientedEllipse
	Oriented ellipse feature frame The affine transformation transforms the ellipse shape into a circular region. More...
Functions
Create and destroy
VL_EXPORT VlCovDet *	vl_covdet_new (VlCovDetMethod method)
	Create a new object instance.
VL_EXPORT void	vl_covdet_delete (VlCovDet *self)
	Delete object instance.
VL_EXPORT void	vl_covdet_reset (VlCovDet *self)
	Reset object.
Process data
VL_EXPORT int	vl_covdet_put_image (VlCovDet self, float const image, vl_size width, vl_size height)
	Detect features in an image.
VL_EXPORT void	vl_covdet_detect (VlCovDet *self)
	Detect scale-space features.
VL_EXPORT int	vl_covdet_append_feature (VlCovDet self, VlCovDetFeature const feature)
	Append a feature to the internal buffer.
VL_EXPORT void	vl_covdet_extract_orientations (VlCovDet *self)
	Extract the orientation(s) for the stored features.
VL_EXPORT void	vl_covdet_extract_laplacian_scales (VlCovDet *self)
	Extract the Laplacian scales for the stored features.
VL_EXPORT void	vl_covdet_extract_affine_shape (VlCovDet *self)
	Extract the affine shape for the stored features.
VL_EXPORT VlCovDetFeatureOrientation *	vl_covdet_extract_orientations_for_frame (VlCovDet self, vl_size numOrientations, VlFrameOrientedEllipse frame)
	Extract the orientation(s) for a feature.
VL_EXPORT VlCovDetFeatureLaplacianScale *	vl_covdet_extract_laplacian_scales_for_frame (VlCovDet self, vl_size numScales, VlFrameOrientedEllipse frame)
	Extract the Laplacian scale(s) for a feature frame.
VL_EXPORT int	vl_covdet_extract_affine_shape_for_frame (VlCovDet self, VlFrameOrientedEllipse adapted, VlFrameOrientedEllipse frame)
	Extract the affine shape for a feature frame.
VL_EXPORT vl_bool	vl_covdet_extract_patch_for_frame (VlCovDet self, float patch, vl_size resolution, double extent, double sigma, VlFrameOrientedEllipse frame)
	Helper for extracting patches.
VL_EXPORT void	vl_covdet_drop_features_outside (VlCovDet *self, double margin)
	Drop features (partially) outside the image.
Retrieve data and parameters
VL_EXPORT vl_size	vl_covdet_get_num_features (VlCovDet const *self)
	Get number of stored frames.
VL_EXPORT void *	vl_covdet_get_features (VlCovDet *self)
	Get the stored frames.
VL_EXPORT vl_index	vl_covdet_get_first_octave (VlCovDet const *self)
	Get the index of the first octave.
VL_EXPORT vl_size	vl_covdet_get_octave_resolution (VlCovDet const *self)
	Get the octave resolution.
VL_EXPORT double	vl_covdet_get_peak_threshold (VlCovDet const *self)
	Get the peak threshold.
VL_EXPORT double	vl_covdet_get_edge_threshold (VlCovDet const *self)
	Get the edge threshold.
VL_EXPORT double	vl_covdeg_get_laplacian_peak_threshold (VlCovDet const *self)
VL_EXPORT vl_bool	vl_covdet_get_transposed (VlCovDet const *self)
	Get wether images are passed in transposed.
VL_EXPORT VlScaleSpace *	vl_covdet_get_gss (VlCovDet const *self)
	Get the Gaussian scale space.
VL_EXPORT VlScaleSpace *	vl_covdet_get_css (VlCovDet const *self)
	Get the cornerness measure scale space.
VL_EXPORT vl_bool	vl_covdet_get_aa_accurate_smoothing (VlCovDet const *self)
	Get whether affine adaptation uses accurate smoothing.
VL_EXPORT vl_size const *	vl_covdet_get_laplacian_scales_statistics (VlCovDet const self, vl_size numScales)
	Get the number of features found with a certain number of scales.
VL_EXPORT double	vl_covdet_get_non_extrema_suppression_threshold (VlCovDet const *self)
	Get the non-extrema suppression threshold.
VL_EXPORT vl_size	vl_covdet_get_num_non_extrema_suppressed (VlCovDet const *self)
	Get the number of non-extrema suppressed.
Set parameters
VL_EXPORT void	vl_covdet_set_first_octave (VlCovDet *self, vl_index o)
	Set the index of the first octave.
VL_EXPORT void	vl_covdet_set_octave_resolution (VlCovDet *self, vl_size r)
	Set the octave resolutuon.
VL_EXPORT void	vl_covdet_set_peak_threshold (VlCovDet *self, double peakThreshold)
	Set the peak threshold.
VL_EXPORT void	vl_covdet_set_edge_threshold (VlCovDet *self, double edgeThreshold)
	Set the edge threshold.
VL_EXPORT void	vl_covdet_set_laplacian_peak_threshold (VlCovDet *self, double peakThreshold)
	Set the Laplacian peak threshold.
VL_EXPORT void	vl_covdet_set_transposed (VlCovDet *self, vl_bool t)
	Set the index of the first octave.
VL_EXPORT void	vl_covdet_set_aa_accurate_smoothing (VlCovDet *self, vl_bool x)
	Set whether affine adaptation uses accurate smoothing.
VL_EXPORT void	vl_covdet_set_non_extrema_suppression_threshold (VlCovDet *self, double x)
	Set the non-extrema suppression threshod.
Feature frames
enum	_VlFrameType { VL_FRAMETYPE_DISC = 1, VL_FRAMETYPE_ORIENTED_DISC, VL_FRAMETYPE_ELLIPSE, VL_FRAMETYPE_ORIENTED_ELLIPSE, VL_FRAMETYPE_NUM }
	Types of feature frames. More...
enum	_VlCovDetMethod { VL_COVDET_METHOD_DOG = 1, VL_COVDET_METHOD_HESSIAN, VL_COVDET_METHOD_HESSIAN_LAPLACE, VL_COVDET_METHOD_HARRIS_LAPLACE, VL_COVDET_METHOD_MULTISCALE_HESSIAN, VL_COVDET_METHOD_MULTISCALE_HARRIS, VL_COVDET_METHOD_NUM }
	Covariant feature detection method. More...
typedef enum _VlFrameType	VlFrameType
	Types of feature frames.
typedef struct _VlFrameDisc	VlFrameDisc
	Disc feature frame.
typedef struct _VlFrameOrientedDisc	VlFrameOrientedDisc
	Oriented disc feature frame An upright frame has `angle` equal to zero.
typedef struct _VlFrameEllipse	VlFrameEllipse
	Ellipse feature frame.
typedef struct _VlFrameOrientedEllipse	VlFrameOrientedEllipse
	Oriented ellipse feature frame The affine transformation transforms the ellipse shape into a circular region.
typedef struct _VlCovDetFeature	VlCovDetFeature
	A detected feature shape and location.
typedef struct _VlCovDetFeatureOrientation	VlCovDetFeatureOrientation
	A detected feature orientation.
typedef struct _VlCovDetFeatureLaplacianScale	VlCovDetFeatureLaplacianScale
	A detected feature Laplacian scale.
typedef enum _VlCovDetMethod	VlCovDetMethod
	Covariant feature detection method.
typedef struct _VlCovDet	VlCovDet
	Covariant feature detector.
VL_EXPORT const char *	vlFrameNames [VL_FRAMETYPE_NUM]
	Names of the frame types.
VL_EXPORT VlEnumerator	vlFrameTypes [VL_FRAMETYPE_NUM]
	Mapping between string values and VlFrameType values.
VL_EXPORT VlEnumerator	vlCovdetMethods [VL_COVDET_METHOD_NUM]
	Mapping between strings and VlCovDetMethod values.
VL_INLINE vl_size	vl_get_frame_size (VlFrameType frameType)
	Get the size of a frame structure.
VL_INLINE VlFrameType	vl_get_frame_type (vl_bool affineAdaptation, vl_bool orientation)
	Get the size of a frame structure.

Detailed Description

Covariant feature detectors (Covariant feature detectors)

Author:: Karel Lenc; Andrea Vedaldi; Michal Perdoch

Definition in file covdet.h.

Typedef Documentation

typedef struct _VlCovDet VlCovDet

Covariant feature detector.

See also:: Covariant feature detectors

Definition at line 183 of file covdet.h.

typedef struct _VlCovDetFeature VlCovDetFeature

A detected feature shape and location.

typedef struct _VlCovDetFeatureLaplacianScale VlCovDetFeatureLaplacianScale

A detected feature Laplacian scale.

typedef struct _VlCovDetFeatureOrientation VlCovDetFeatureOrientation

A detected feature orientation.

typedef enum _VlCovDetMethod VlCovDetMethod

Covariant feature detection method.

typedef struct _VlFrameDisc VlFrameDisc

Disc feature frame.

typedef struct _VlFrameEllipse VlFrameEllipse

Ellipse feature frame.

typedef struct _VlFrameOrientedDisc VlFrameOrientedDisc

Oriented disc feature frame An upright frame has angle equal to zero.

typedef struct _VlFrameOrientedEllipse VlFrameOrientedEllipse

Oriented ellipse feature frame The affine transformation transforms the ellipse shape into a circular region.

typedef enum _VlFrameType VlFrameType

Types of feature frames.

Enumeration Type Documentation

enum _VlCovDetMethod

Covariant feature detection method.

Enumerator:

VL_COVDET_METHOD_DOG
VL_COVDET_METHOD_HESSIAN
VL_COVDET_METHOD_HESSIAN_LAPLACE
VL_COVDET_METHOD_HARRIS_LAPLACE
VL_COVDET_METHOD_MULTISCALE_HESSIAN
VL_COVDET_METHOD_MULTISCALE_HARRIS
VL_COVDET_METHOD_NUM

Definition at line 161 of file covdet.h.

enum _VlFrameType

Types of feature frames.

Enumerator:

VL_FRAMETYPE_DISC	A disc.
VL_FRAMETYPE_ORIENTED_DISC	An oriented disc.
VL_FRAMETYPE_ELLIPSE	An ellipse.
VL_FRAMETYPE_ORIENTED_ELLIPSE	An oriented ellipse.
VL_FRAMETYPE_NUM

Definition at line 34 of file covdet.h.

Function Documentation

VL_EXPORT double vl_covdeg_get_laplacian_peak_threshold ( VlCovDet const * self )

VL_EXPORT int vl_covdet_append_feature	(	VlCovDet *	self,
		VlCovDetFeature const *	feature
	)

Append a feature to the internal buffer.

Parameters:

self	object.
feature	a pointer to the feature to append.

Returns:: status.

The feature is copied. The function may fail with status equal to VL_ERR_ALLOC if there is insufficient memory.

Definition at line 1648 of file covdet.c.

VL_EXPORT void vl_covdet_delete ( VlCovDet * self )

Delete object instance.

Parameters:

self object.

Definition at line 1631 of file covdet.c.

VL_EXPORT void vl_covdet_detect ( VlCovDet * self )

Detect scale-space features.

Parameters:

self object.

This function runs the configured feature detector on the image that was passed by using vl_covdet_put_image.

Definition at line 1921 of file covdet.c.

VL_EXPORT void vl_covdet_drop_features_outside	(	VlCovDet *	self,
		double	margin
	)

Drop features (partially) outside the image.

Parameters:

self	object.
margin	geometric marging.

The feature extent is defined by maring. A bounding box in the normalised feature frame containin a circle of radius maring is created and mapped to the image by the feature frame transformation. Then the feature is dropped if the bounding box is not contained in the image.

For example, setting margin to zero drops a feature only if its center is not contained.

Typically a valua of margin equal to 1 or 2 is used.

Definition at line 3108 of file covdet.c.

VL_EXPORT void vl_covdet_extract_affine_shape ( VlCovDet * self )

Extract the affine shape for the stored features.

Parameters:

self object.

This function may discard features for which no affine shape can reliably be detected.

Definition at line 2644 of file covdet.c.

VL_EXPORT int vl_covdet_extract_affine_shape_for_frame	(	VlCovDet *	self,
		VlFrameOrientedEllipse *	adapted,
		VlFrameOrientedEllipse	frame
	)

Extract the affine shape for a feature frame.

Parameters:

self	object.
adapted	the shape-adapted frame.
frame	the input frame.

Returns:: VL_ERR_OK if affine adaptation is successful.

This function may fail if adaptation is unsuccessful or if memory is insufficient.

Definition at line 2455 of file covdet.c.

VL_EXPORT void vl_covdet_extract_laplacian_scales ( VlCovDet * self )

Extract the Laplacian scales for the stored features.

Parameters:

self object.

Note that, since more than one orientation can be detected for each feature, this function may create copies of them, one for each orientation.

Definition at line 3009 of file covdet.c.

VL_EXPORT VlCovDetFeatureLaplacianScale* vl_covdet_extract_laplacian_scales_for_frame	(	VlCovDet *	self,
		vl_size *	numScales,
		VlFrameOrientedEllipse	frame
	)

Extract the Laplacian scale(s) for a feature frame.

Parameters:

self	object.
numScales	the number of detected scales.
frame	pose of the feature.

Returns:: an array of detected scales.

The function returns NULL if memory is insufficient.

Definition at line 2900 of file covdet.c.

VL_EXPORT void vl_covdet_extract_orientations ( VlCovDet * self )

Extract the orientation(s) for the stored features.

Parameters:

self object.

Note that, since more than one orientation can be detected for each feature, this function may create copies of them, one for each orientation.

Definition at line 2850 of file covdet.c.

VL_EXPORT VlCovDetFeatureOrientation* vl_covdet_extract_orientations_for_frame	(	VlCovDet *	self,
		vl_size *	numOrientations,
		VlFrameOrientedEllipse	frame
	)

Extract the orientation(s) for a feature.

Parameters:

self	object.
numOrientations	the number of detected orientations.
frame	pose of the feature.

Returns:: an array of detected orientations with their scores.

The returned array is a matrix of size $2 \times n$ where n is the number of detected orientations.

The function returns NULL if memory is insufficient.

Definition at line 2690 of file covdet.c.

VL_EXPORT vl_bool vl_covdet_extract_patch_for_frame	(	VlCovDet *	self,
		float *	patch,
		vl_size	resolution,
		double	extent,
		double	sigma,
		VlFrameOrientedEllipse	frame
	)

Helper for extracting patches.

Parameters:

self	object.
patch	buffer.
resolution	patch resolution.
extent	patch extent.
sigma	desired smoothing in the patch frame.
frame	feature frame.

The function considers a patch of extent [-extent,extent] on each side, with a side counting 2*resolution+1 pixels. In attempts to extract from the scale space a patch based on the affine warping specified by frame in such a way that the resulting smoothing of the image is sigma (in the patch frame).

The transformation is specified by the matrices A and T embedded in the feature frame. Note that this transformation maps pixels from the patch frame to the image frame.

Definition at line 2423 of file covdet.c.

VL_EXPORT vl_bool vl_covdet_get_aa_accurate_smoothing ( VlCovDet const * self )

Get whether affine adaptation uses accurate smoothing.

Parameters:

self object.

Returns:: true if accurate smoothing is used.

Definition at line 3280 of file covdet.c.

VL_EXPORT VlScaleSpace* vl_covdet_get_css ( VlCovDet const * self )

Get the cornerness measure scale space.

Returns:: cornerness measure scale space.

A cornerness measure scale space exists only after calling vl_covdet_detect. Otherwise the function returns NULL.

Definition at line 3371 of file covdet.c.

VL_EXPORT double vl_covdet_get_edge_threshold ( VlCovDet const * self )

Get the edge threshold.

Parameters:

self object.

Returns:: the edge threshold.

Definition at line 3154 of file covdet.c.

VL_EXPORT void* vl_covdet_get_features ( VlCovDet * self )

Get the stored frames.

Returns:: frames stored in the detector.

Definition at line 3345 of file covdet.c.

VL_EXPORT vl_index vl_covdet_get_first_octave ( VlCovDet const * self )

Get the index of the first octave.

Parameters:

self object.

Returns:: index of the first octave.

Definition at line 3229 of file covdet.c.

VL_EXPORT VlScaleSpace* vl_covdet_get_gss ( VlCovDet const * self )

Get the Gaussian scale space.

Returns:: Gaussian scale space.

A Gaussian scale space exists only after calling vl_covdet_put_image. Otherwise the function returns NULL.

Definition at line 3358 of file covdet.c.

VL_EXPORT vl_size const* vl_covdet_get_laplacian_scales_statistics	(	VlCovDet const *	self,
		vl_size *	numScales
	)

Get the number of features found with a certain number of scales.

Parameters:

self	object.
numScales	length of the histogram (out).

Returns:: histogram.

Calling this function makes sense only after running a detector that uses the Laplacian as a secondary measure for scale detection

Definition at line 3387 of file covdet.c.

VL_EXPORT double vl_covdet_get_non_extrema_suppression_threshold ( VlCovDet const * self )

Get the non-extrema suppression threshold.

Parameters:

self object.

Returns:: threshold.

Definition at line 3303 of file covdet.c.

VL_EXPORT vl_size vl_covdet_get_num_features ( VlCovDet const * self )

Get number of stored frames.

Returns:: number of frames stored in the detector.

Definition at line 3336 of file covdet.c.

VL_EXPORT vl_size vl_covdet_get_num_non_extrema_suppressed ( VlCovDet const * self )

Get the number of non-extrema suppressed.

Parameters:

self object.

Returns:: number.

Definition at line 3325 of file covdet.c.

VL_EXPORT vl_size vl_covdet_get_octave_resolution ( VlCovDet const * self )

Get the octave resolution.

Parameters:

self object.

Returns:: octave resolution.

Definition at line 3254 of file covdet.c.

VL_EXPORT double vl_covdet_get_peak_threshold ( VlCovDet const * self )

Get the peak threshold.

Parameters:

self object.

Returns:: the peak threshold.

Definition at line 3178 of file covdet.c.

VL_EXPORT vl_bool vl_covdet_get_transposed ( VlCovDet const * self )

Get wether images are passed in transposed.

Parameters:

self object.

Returns:: whether images are transposed.

Definition at line 3133 of file covdet.c.

VL_EXPORT VlCovDet* vl_covdet_new ( VlCovDetMethod method )

Create a new object instance.

Parameters:

method method for covariant feature detection.

Returns:: new covariant detector.

Definition at line 1507 of file covdet.c.

VL_EXPORT int vl_covdet_put_image	(	VlCovDet *	self,
		float const *	image,
		vl_size	width,
		vl_size	height
	)

Detect features in an image.

Parameters:

self	object.
image	image to process.
width	image width.
height	image height.

Returns:: status.

width and height must be at least one pixel. The function fails by returing VL_ERR_ALLOC if the memory is insufficient.

Definition at line 1683 of file covdet.c.

VL_EXPORT void vl_covdet_reset ( VlCovDet * self )

Reset object.

Parameters:

self object.

This function removes any buffered features and frees other internal buffers.

Definition at line 1610 of file covdet.c.

VL_EXPORT void vl_covdet_set_aa_accurate_smoothing	(	VlCovDet *	self,
		vl_bool	x
	)

Set whether affine adaptation uses accurate smoothing.

Parameters:

self	object.
x	whether accurate smoothing should be usd.

Definition at line 3291 of file covdet.c.

VL_EXPORT void vl_covdet_set_edge_threshold	(	VlCovDet *	self,
		double	edgeThreshold
	)

Set the edge threshold.

Parameters:

self	object.
edgeThreshold	the edge threshold.

The edge threshold must be non-negative.

Definition at line 3166 of file covdet.c.

VL_EXPORT void vl_covdet_set_first_octave	(	VlCovDet *	self,
		vl_index	o
	)

Set the index of the first octave.

Parameters:

self	object.
o	index of the first octave.

Calling this function resets the detector.

Definition at line 3241 of file covdet.c.

VL_EXPORT void vl_covdet_set_laplacian_peak_threshold	(	VlCovDet *	self,
		double	peakThreshold
	)

Set the Laplacian peak threshold.

Parameters:

self	object.
peakThreshold	the Laplacian peak threshold.

The peak threshold must be non-negative.

Definition at line 3217 of file covdet.c.

VL_EXPORT void vl_covdet_set_non_extrema_suppression_threshold	(	VlCovDet *	self,
		double	x
	)

Set the non-extrema suppression threshod.

Parameters:

self	object.
x	threshold.

Definition at line 3314 of file covdet.c.

VL_EXPORT void vl_covdet_set_octave_resolution	(	VlCovDet *	self,
		vl_size	r
	)

Set the octave resolutuon.

Parameters:

self	object.
r	octave resoltuion.

Calling this function resets the detector.

Definition at line 3267 of file covdet.c.

VL_EXPORT void vl_covdet_set_peak_threshold	(	VlCovDet *	self,
		double	peakThreshold
	)

Set the peak threshold.

Parameters:

self	object.
peakThreshold	the peak threshold.

The peak threshold must be non-negative.

Definition at line 3190 of file covdet.c.

VL_EXPORT void vl_covdet_set_transposed	(	VlCovDet *	self,
		vl_bool	t
	)

Set the index of the first octave.

Parameters:

self	object.
t	whether images are transposed.

Definition at line 3143 of file covdet.c.

VL_INLINE vl_size vl_get_frame_size ( VlFrameType frameType )

Get the size of a frame structure.

Parameters:

frameType identifier of the type of frame.

Returns:: size of the corresponding frame structure in bytes.

Definition at line 92 of file covdet.h.

VL_INLINE VlFrameType vl_get_frame_type	(	vl_bool	affineAdaptation,
		vl_bool	orientation
	)

Get the size of a frame structure.

Parameters:

affineAdaptation	whether the detector use affine adaptation.
orientation	whether the detector estimates the feature orientation.

Returns:: the type of extracted frame.

Depedning on whether the detector estimate the affine shape and orientation of a feature, different frame types are extracted.

Definition at line 115 of file covdet.h.

Variable Documentation

VL_EXPORT VlEnumerator vlCovdetMethods[VL_COVDET_METHOD_NUM]

Mapping between strings and VlCovDetMethod values.

Definition at line 173 of file covdet.h.

VL_EXPORT const char* vlFrameNames[VL_FRAMETYPE_NUM]

Names of the frame types.

Definition at line 43 of file covdet.h.

VL_EXPORT VlEnumerator vlFrameTypes[VL_FRAMETYPE_NUM]

Mapping between string values and VlFrameType values.

Definition at line 46 of file covdet.h.

Classes

Functions

Feature frames

Detailed Description

Typedef Documentation

Enumeration Type Documentation

Function Documentation

Variable Documentation