Documentation>C API
covdet.c File Reference

Covariant feature detectors - Definition. More...

#include "covdet.h"
#include <string.h>

Data Structures

struct  _VlCovDet
 Covariant feature detector. More...
 

Functions

static int _vl_resize_buffer (void **buffer, vl_size *bufferSize, vl_size targetSize)
 Reallocate buffer. More...
 
static int _vl_enlarge_buffer (void **buffer, vl_size *bufferSize, vl_size targetSize)
 Enlarge buffer. More...
 
vl_size vl_find_local_extrema_3 (vl_index **extrema, vl_size *bufferSize, float const *map, vl_size width, vl_size height, vl_size depth, double threshold)
 Find the extrema of a 3D function. More...
 
vl_size vl_find_local_extrema_2 (vl_index **extrema, vl_size *bufferSize, float const *map, vl_size width, vl_size height, double threshold)
 Find extrema in a 2D function. More...
 
vl_bool vl_refine_local_extreum_3 (VlCovDetExtremum3 *refined, float const *map, vl_size width, vl_size height, vl_size depth, vl_index x, vl_index y, vl_index z)
 Refine the location of a local extremum of a 3D map. More...
 
vl_bool vl_refine_local_extreum_2 (VlCovDetExtremum2 *refined, float const *map, vl_size width, vl_size height, vl_index x, vl_index y)
 Refine the location of a local extremum of a 2D map. More...
 
VlCovDetvl_covdet_new (VlCovDetMethod method)
 Create a new object instance. More...
 
void vl_covdet_reset (VlCovDet *self)
 Reset object. More...
 
void vl_covdet_delete (VlCovDet *self)
 Delete object instance. More...
 
int vl_covdet_append_feature (VlCovDet *self, VlCovDetFeature const *feature)
 Append a feature to the internal buffer. More...
 
int vl_covdet_put_image (VlCovDet *self, float const *image, vl_size width, vl_size height)
 Detect features in an image. More...
 
static void _vl_det_hessian_response (float *hessian, float const *image, vl_size width, vl_size height, double step, double sigma)
 Scaled derminant of the Hessian filter. More...
 
static void _vl_harris_response (float *harris, float const *image, vl_size width, vl_size height, double step, double sigma, double sigmaI, double alpha)
 Scale-normalised Harris response. More...
 
static void _vl_dog_response (float *dog, float const *level1, float const *level2, vl_size width, vl_size height)
 Difference of Gaussian. More...
 
void vl_covdet_detect (VlCovDet *self)
 Detect scale-space features. More...
 
vl_bool vl_covdet_extract_patch_helper (VlCovDet *self, double *sigma1, double *sigma2, float *patch, vl_size resolution, double extent, double sigma, double A_ [4], double T_ [2], double d1, double d2)
 Helper for extracting patches. More...
 
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. More...
 
int vl_covdet_extract_affine_shape_for_frame (VlCovDet *self, VlFrameOrientedEllipse *adapted, VlFrameOrientedEllipse frame)
 Extract the affine shape for a feature frame. More...
 
void vl_covdet_extract_affine_shape (VlCovDet *self)
 Extract the affine shape for the stored features. More...
 
VlCovDetFeatureOrientationvl_covdet_extract_orientations_for_frame (VlCovDet *self, vl_size *numOrientations, VlFrameOrientedEllipse frame)
 Extract the orientation(s) for a feature. More...
 
void vl_covdet_extract_orientations (VlCovDet *self)
 Extract the orientation(s) for the stored features. More...
 
VlCovDetFeatureLaplacianScalevl_covdet_extract_laplacian_scales_for_frame (VlCovDet *self, vl_size *numScales, VlFrameOrientedEllipse frame)
 Extract the Laplacian scale(s) for a feature frame. More...
 
void vl_covdet_extract_laplacian_scales (VlCovDet *self)
 Extract the Laplacian scales for the stored features. More...
 
void vl_covdet_drop_features_outside (VlCovDet *self, double margin)
 Drop features (partially) outside the image. More...
 
vl_bool vl_covdet_get_transposed (VlCovDet const *self)
 Get wether images are passed in transposed. More...
 
void vl_covdet_set_transposed (VlCovDet *self, vl_bool t)
 Set the index of the first octave. More...
 
double vl_covdet_get_edge_threshold (VlCovDet const *self)
 Get the edge threshold. More...
 
void vl_covdet_set_edge_threshold (VlCovDet *self, double edgeThreshold)
 Set the edge threshold. More...
 
double vl_covdet_get_peak_threshold (VlCovDet const *self)
 Get the peak threshold. More...
 
void vl_covdet_set_peak_threshold (VlCovDet *self, double peakThreshold)
 Set the peak threshold. More...
 
double vl_covdet_get_laplacian_peak_threshold (VlCovDet const *self)
 Get the Laplacian peak threshold. More...
 
void vl_covdet_set_laplacian_peak_threshold (VlCovDet *self, double peakThreshold)
 Set the Laplacian peak threshold. More...
 
vl_index vl_covdet_get_first_octave (VlCovDet const *self)
 Get the index of the first octave. More...
 
void vl_covdet_set_first_octave (VlCovDet *self, vl_index o)
 Set the index of the first octave. More...
 
vl_size vl_covdet_get_num_octaves (VlCovDet const *self)
 Get the max number of octaves. More...
 
double vl_covdet_get_base_scale (VlCovDet const *self)
 Get the GSS base scale. More...
 
void vl_covdet_set_num_octaves (VlCovDet *self, vl_size o)
 Set the max number of octaves. More...
 
void vl_covdet_set_base_scale (VlCovDet *self, double s)
 Set the GSS base scale. More...
 
void vl_covdet_set_max_num_orientations (VlCovDet *self, vl_size m)
 Set the max number of orientations. More...
 
vl_size vl_covdet_get_octave_resolution (VlCovDet const *self)
 Get the octave resolution. More...
 
void vl_covdet_set_octave_resolution (VlCovDet *self, vl_size r)
 Set the octave resolutuon. More...
 
vl_bool vl_covdet_get_aa_accurate_smoothing (VlCovDet const *self)
 Get whether affine adaptation uses accurate smoothing. More...
 
void vl_covdet_set_aa_accurate_smoothing (VlCovDet *self, vl_bool x)
 Set whether affine adaptation uses accurate smoothing. More...
 
vl_size vl_covdet_get_max_num_orientations (VlCovDet const *self)
 Get the max number of orientations. More...
 
double vl_covdet_get_non_extrema_suppression_threshold (VlCovDet const *self)
 Get the non-extrema suppression threshold. More...
 
void vl_covdet_set_non_extrema_suppression_threshold (VlCovDet *self, double x)
 Set the non-extrema suppression threshod. More...
 
vl_size vl_covdet_get_num_non_extrema_suppressed (VlCovDet const *self)
 Get the number of non-extrema suppressed. More...
 
vl_size vl_covdet_get_num_features (VlCovDet const *self)
 Get number of stored frames. More...
 
void * vl_covdet_get_features (VlCovDet *self)
 Get the stored frames. More...
 
VlScaleSpacevl_covdet_get_gss (VlCovDet const *self)
 Get the Gaussian scale space. More...
 
VlScaleSpacevl_covdet_get_css (VlCovDet const *self)
 Get the cornerness measure scale space. More...
 
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. More...
 
vl_bool vl_covdet_get_allow_padded_warping (VlCovDet const *self)
 Get wether to compute padded warped patches. More...
 
void vl_covdet_set_allow_padded_warping (VlCovDet *self, vl_bool t)
 Set wether to compute padded warped patches. More...
 

Detailed Description

Author
Karel Lenc
Andrea Vedaldi
Michal Perdoch

Function Documentation

◆ _vl_det_hessian_response()

static void _vl_det_hessian_response ( float *  hessian,
float const *  image,
vl_size  width,
vl_size  height,
double  step,
double  sigma 
)
static
Parameters
hessianoutput image.
imageinput image.
widthimage width.
heightimage height.
stepimage sampling step (pixel size).
sigmaGaussian smoothing of the input image.

◆ _vl_dog_response()

static void _vl_dog_response ( float *  dog,
float const *  level1,
float const *  level2,
vl_size  width,
vl_size  height 
)
static
Parameters
dogoutput image.
level1input image at the smaller Gaussian scale.
level2input image at the larger Gaussian scale.
widthimage width.
heightimage height.

◆ _vl_enlarge_buffer()

static int _vl_enlarge_buffer ( void **  buffer,
vl_size bufferSize,
vl_size  targetSize 
)
static
Parameters
buffer
bufferSize
targetSize
Returns
error code

◆ _vl_harris_response()

static void _vl_harris_response ( float *  harris,
float const *  image,
vl_size  width,
vl_size  height,
double  step,
double  sigma,
double  sigmaI,
double  alpha 
)
static
Parameters
harrisoutput image.
imageinput image.
widthimage width.
heightimage height.
stepimage sampling step (pixel size).
sigmaGaussian smoothing of the input image.
sigmaIintegration scale.
alphafactor in the definition of the Harris score.

◆ _vl_resize_buffer()

static int _vl_resize_buffer ( void **  buffer,
vl_size bufferSize,
vl_size  targetSize 
)
static
Parameters
buffer
bufferSize
targetSize
Returns
error code

◆ vl_covdet_append_feature()

int vl_covdet_append_feature ( VlCovDet self,
VlCovDetFeature const *  feature 
)
Parameters
selfobject.
featurea 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.

◆ vl_covdet_delete()

void vl_covdet_delete ( VlCovDet self)
Parameters
selfobject.

◆ vl_covdet_detect()

void vl_covdet_detect ( VlCovDet self)
Parameters
selfobject.

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

◆ vl_covdet_drop_features_outside()

void vl_covdet_drop_features_outside ( VlCovDet self,
double  margin 
)
Parameters
selfobject.
margingeometric 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.

◆ vl_covdet_extract_affine_shape()

void vl_covdet_extract_affine_shape ( VlCovDet self)
Parameters
selfobject.

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

◆ vl_covdet_extract_affine_shape_for_frame()

int vl_covdet_extract_affine_shape_for_frame ( VlCovDet self,
VlFrameOrientedEllipse adapted,
VlFrameOrientedEllipse  frame 
)
Parameters
selfobject.
adaptedthe shape-adapted frame.
framethe input frame.
Returns
VL_ERR_OK if affine adaptation is successful.

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

◆ vl_covdet_extract_laplacian_scales()

void vl_covdet_extract_laplacian_scales ( VlCovDet self)
Parameters
selfobject.

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

◆ vl_covdet_extract_laplacian_scales_for_frame()

VlCovDetFeatureLaplacianScale* vl_covdet_extract_laplacian_scales_for_frame ( VlCovDet self,
vl_size numScales,
VlFrameOrientedEllipse  frame 
)
Parameters
selfobject.
numScalesthe number of detected scales.
framepose of the feature.
Returns
an array of detected scales.

The function returns NULL if memory is insufficient.

◆ vl_covdet_extract_orientations()

void vl_covdet_extract_orientations ( VlCovDet self)
Parameters
selfobject.

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

◆ vl_covdet_extract_orientations_for_frame()

VlCovDetFeatureOrientation* vl_covdet_extract_orientations_for_frame ( VlCovDet self,
vl_size numOrientations,
VlFrameOrientedEllipse  frame 
)
Parameters
selfobject.
numOrientationsthe number of detected orientations.
framepose 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.

◆ vl_covdet_extract_patch_for_frame()

vl_bool vl_covdet_extract_patch_for_frame ( VlCovDet self,
float *  patch,
vl_size  resolution,
double  extent,
double  sigma,
VlFrameOrientedEllipse  frame 
)
Parameters
selfobject.
patchbuffer.
resolutionpatch resolution.
extentpatch extent.
sigmadesired smoothing in the patch frame.
framefeature 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.

◆ vl_covdet_extract_patch_helper()

vl_bool vl_covdet_extract_patch_helper ( VlCovDet self,
double *  sigma1,
double *  sigma2,
float *  patch,
vl_size  resolution,
double  extent,
double  sigma,
double  A_[4],
double  T_[2],
double  d1,
double  d2 
)
Parameters
selfobject.
[out]sigma1actual patch smoothing along the first axis.
[out]sigma2actual patch smoothing along the second axis.
patchbuffer.
resolutionpatch resolution.
extentpatch extent.
sigmadesired smoothing in the patch frame.
A_linear transfomration from patch to image.
T_translation from patch to image.
d1first singular value A.
d2second singular value of A.

◆ vl_covdet_get_aa_accurate_smoothing()

vl_bool vl_covdet_get_aa_accurate_smoothing ( VlCovDet const *  self)
Parameters
selfobject.
Returns
true if accurate smoothing is used.

◆ vl_covdet_get_allow_padded_warping()

vl_bool vl_covdet_get_allow_padded_warping ( VlCovDet const *  self)
Parameters
selfobject.
Returns
whether padded warped patches are computed.

◆ vl_covdet_get_base_scale()

double vl_covdet_get_base_scale ( VlCovDet const *  self)
Parameters
selfobject.
Returns
The base scale.

◆ vl_covdet_get_css()

VlScaleSpace* vl_covdet_get_css ( VlCovDet const *  self)
Returns
cornerness measure scale space.

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

◆ vl_covdet_get_edge_threshold()

double vl_covdet_get_edge_threshold ( VlCovDet const *  self)
Parameters
selfobject.
Returns
the edge threshold.

◆ vl_covdet_get_features()

void* vl_covdet_get_features ( VlCovDet self)
Returns
frames stored in the detector.

◆ vl_covdet_get_first_octave()

vl_index vl_covdet_get_first_octave ( VlCovDet const *  self)
Parameters
selfobject.
Returns
index of the first octave.

◆ vl_covdet_get_gss()

VlScaleSpace* vl_covdet_get_gss ( VlCovDet const *  self)
Returns
Gaussian scale space.

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

◆ vl_covdet_get_laplacian_peak_threshold()

double vl_covdet_get_laplacian_peak_threshold ( VlCovDet const *  self)
Parameters
selfobject.
Returns
the Laplacian peak threshold.

This parameter affects only the detecors using the Laplacian scale selectino method such as Harris-Laplace.

◆ vl_covdet_get_laplacian_scales_statistics()

vl_size const* vl_covdet_get_laplacian_scales_statistics ( VlCovDet const *  self,
vl_size numScales 
)
Parameters
selfobject.
numScaleslength 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

◆ vl_covdet_get_max_num_orientations()

vl_size vl_covdet_get_max_num_orientations ( VlCovDet const *  self)
Parameters
selfobject.
Returns
maximal number of orientations.

◆ vl_covdet_get_non_extrema_suppression_threshold()

double vl_covdet_get_non_extrema_suppression_threshold ( VlCovDet const *  self)
Parameters
selfobject.
Returns
threshold.

◆ vl_covdet_get_num_features()

vl_size vl_covdet_get_num_features ( VlCovDet const *  self)
Returns
number of frames stored in the detector.

◆ vl_covdet_get_num_non_extrema_suppressed()

vl_size vl_covdet_get_num_non_extrema_suppressed ( VlCovDet const *  self)
Parameters
selfobject.
Returns
number.

◆ vl_covdet_get_num_octaves()

vl_size vl_covdet_get_num_octaves ( VlCovDet const *  self)
Parameters
selfobject.
Returns
maximal number of octaves.

◆ vl_covdet_get_octave_resolution()

vl_size vl_covdet_get_octave_resolution ( VlCovDet const *  self)
Parameters
selfobject.
Returns
octave resolution.

◆ vl_covdet_get_peak_threshold()

double vl_covdet_get_peak_threshold ( VlCovDet const *  self)
Parameters
selfobject.
Returns
the peak threshold.

◆ vl_covdet_get_transposed()

vl_bool vl_covdet_get_transposed ( VlCovDet const *  self)
Parameters
selfobject.
Returns
whether images are transposed.

◆ vl_covdet_new()

VlCovDet* vl_covdet_new ( VlCovDetMethod  method)
Parameters
methodmethod for covariant feature detection.
Returns
new covariant detector.

◆ vl_covdet_put_image()

int vl_covdet_put_image ( VlCovDet self,
float const *  image,
vl_size  width,
vl_size  height 
)
Parameters
selfobject.
imageimage to process.
widthimage width.
heightimage 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.

◆ vl_covdet_reset()

void vl_covdet_reset ( VlCovDet self)
Parameters
selfobject.

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

◆ vl_covdet_set_aa_accurate_smoothing()

void vl_covdet_set_aa_accurate_smoothing ( VlCovDet self,
vl_bool  x 
)
Parameters
selfobject.
xwhether accurate smoothing should be usd.

◆ vl_covdet_set_allow_padded_warping()

void vl_covdet_set_allow_padded_warping ( VlCovDet self,
vl_bool  t 
)
Parameters
selfobject.
twhether padded warped patches are computed.

◆ vl_covdet_set_base_scale()

void vl_covdet_set_base_scale ( VlCovDet self,
double  s 
)
Parameters
selfobject.
sthe base scale.

Calling this function resets the detector.

◆ vl_covdet_set_edge_threshold()

void vl_covdet_set_edge_threshold ( VlCovDet self,
double  edgeThreshold 
)
Parameters
selfobject.
edgeThresholdthe edge threshold.

The edge threshold must be non-negative.

◆ vl_covdet_set_first_octave()

void vl_covdet_set_first_octave ( VlCovDet self,
vl_index  o 
)
Parameters
selfobject.
oindex of the first octave.

Calling this function resets the detector.

◆ vl_covdet_set_laplacian_peak_threshold()

void vl_covdet_set_laplacian_peak_threshold ( VlCovDet self,
double  peakThreshold 
)
Parameters
selfobject.
peakThresholdthe Laplacian peak threshold.

The peak threshold must be non-negative.

◆ vl_covdet_set_max_num_orientations()

void vl_covdet_set_max_num_orientations ( VlCovDet self,
vl_size  m 
)
Parameters
selfobject.
mthe max number of orientations.

Calling this function resets the detector.

◆ vl_covdet_set_non_extrema_suppression_threshold()

void vl_covdet_set_non_extrema_suppression_threshold ( VlCovDet self,
double  x 
)
Parameters
selfobject.
xthreshold.

◆ vl_covdet_set_num_octaves()

void vl_covdet_set_num_octaves ( VlCovDet self,
vl_size  o 
)
Parameters
selfobject.
omax number of octaves.

Calling this function resets the detector.

◆ vl_covdet_set_octave_resolution()

void vl_covdet_set_octave_resolution ( VlCovDet self,
vl_size  r 
)
Parameters
selfobject.
roctave resoltuion.

Calling this function resets the detector.

◆ vl_covdet_set_peak_threshold()

void vl_covdet_set_peak_threshold ( VlCovDet self,
double  peakThreshold 
)
Parameters
selfobject.
peakThresholdthe peak threshold.

The peak threshold must be non-negative.

◆ vl_covdet_set_transposed()

void vl_covdet_set_transposed ( VlCovDet self,
vl_bool  t 
)
Parameters
selfobject.
twhether images are transposed.

◆ vl_find_local_extrema_2()

vl_size vl_find_local_extrema_2 ( vl_index **  extrema,
vl_size bufferSize,
float const *  map,
vl_size  width,
vl_size  height,
double  threshold 
)
Parameters
extremabuffer containing the found extrema (in/out).
bufferSizesize of the extrema buffer in bytes (in/out).
mapa 3D array representing the map.
widthof the map.
heightof the map.
thresholdminumum extremum value.
Returns
number of extrema found.

An extremum contains 2 vl_index values; they are arranged sequentially.

The function can reuse an already allocated buffer if extrema and bufferSize are initialized on input. It may have to realloc the memory if the buffer is too small.

◆ vl_find_local_extrema_3()

vl_size vl_find_local_extrema_3 ( vl_index **  extrema,
vl_size bufferSize,
float const *  map,
vl_size  width,
vl_size  height,
vl_size  depth,
double  threshold 
)
Parameters
extremabuffer containing the extrema found (in/out).
bufferSizesize of the extrema buffer in bytes (in/out).
mapa 3D array representing the map.
widthof the map.
heightof the map.
depthof the map.
thresholdminumum extremum value.
Returns
number of extrema found.
See also
vl_refine_local_extreum_2.

◆ vl_refine_local_extreum_2()

vl_bool vl_refine_local_extreum_2 ( VlCovDetExtremum2 *  refined,
float const *  map,
vl_size  width,
vl_size  height,
vl_index  x,
vl_index  y 
)
Parameters
refinedrefined extremum (out).
mapa 2D array representing the map.
widthof the map.
heightof the map.
xinitial x position.
yinitial y position.
Returns
a flat indicating whether the extrema refinement was stable.

◆ vl_refine_local_extreum_3()

vl_bool vl_refine_local_extreum_3 ( VlCovDetExtremum3 *  refined,
float const *  map,
vl_size  width,
vl_size  height,
vl_size  depth,
vl_index  x,
vl_index  y,
vl_index  z 
)
Parameters
refinedrefined extremum (out).
mapa 3D array representing the map.
widthof the map.
heightof the map.
depthof the map.
xinitial x position.
yinitial y position.
zinitial z position.
Returns
a flat indicating whether the extrema refinement was stable.