Documentation>C API
Data Structures
covdet.h File Reference

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

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

## Data Structures

struct | VlFrameDisc
| Disc feature frame. More...
struct | VlFrameOrientedDisc
| Oriented disc feature frame An upright frame has `angle` equal to zero. More...
struct | VlFrameEllipse
| Ellipse feature frame. More...
struct | VlFrameOrientedEllipse
| Oriented ellipse feature frame The affine transformation transforms the ellipse shape into a circular region. More...
struct | VlCovDetFeature
| A detected feature shape and location. More...
struct | VlCovDetFeatureOrientation
| A detected feature orientation. More...
struct | VlCovDetFeatureLaplacianScale
| A detected feature Laplacian scale. More...
struct | _VlCovDet
| Covariant feature detector. More...

## Functions

Create and destroy
VlCovDet * | vl_covdet_new (VlCovDetMethod method)
| Create a new object instance.
void | vl_covdet_delete (VlCovDet *self)
| Delete object instance.
void | vl_covdet_reset (VlCovDet *self)
| Reset object.
Process data
int | vl_covdet_put_image (VlCovDet *self, float const *image, vl_size width, vl_size height)
| Detect features in an image.
void | vl_covdet_detect (VlCovDet *self)
| Detect scale-space features.
int | vl_covdet_append_feature (VlCovDet *self, VlCovDetFeature const *feature)
| Append a feature to the internal buffer.
void | vl_covdet_extract_orientations (VlCovDet *self)
| Extract the orientation(s) for the stored features.
void | vl_covdet_extract_laplacian_scales (VlCovDet *self)
| Extract the Laplacian scales for the stored features.
void | vl_covdet_extract_affine_shape (VlCovDet *self)
| Extract the affine shape for the stored features.
VlCovDetFeatureOrientation * | vl_covdet_extract_orientations_for_frame (VlCovDet *self, vl_size *numOrientations, VlFrameOrientedEllipse frame)
| Extract the orientation(s) for a feature.
VlCovDetFeatureLaplacianScale * | vl_covdet_extract_laplacian_scales_for_frame (VlCovDet *self, vl_size *numScales, VlFrameOrientedEllipse frame)
| Extract the Laplacian scale(s) for a feature frame.
int | vl_covdet_extract_affine_shape_for_frame (VlCovDet *self, VlFrameOrientedEllipse *adapted, VlFrameOrientedEllipse frame)
| Extract the affine shape for a feature frame.
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.
void | vl_covdet_drop_features_outside (VlCovDet *self, double margin)
| Drop features (partially) outside the image.
Retrieve data and parameters
vl_size | vl_covdet_get_num_features (VlCovDet const *self)
| Get number of stored frames.
void * | vl_covdet_get_features (VlCovDet *self)
| Get the stored frames.
vl_index | vl_covdet_get_first_octave (VlCovDet const *self)
| Get the index of the first octave.
vl_size | vl_covdet_get_num_octaves (VlCovDet const *self)
| Get the max number of octaves.
double | vl_covdet_get_base_scale (VlCovDet const *self)
| Get the GSS base scale.
vl_size | vl_covdet_get_octave_resolution (VlCovDet const *self)
| Get the octave resolution.
double | vl_covdet_get_peak_threshold (VlCovDet const *self)
| Get the peak threshold.
double | vl_covdet_get_edge_threshold (VlCovDet const *self)
| Get the edge threshold.
vl_size | vl_covdet_get_max_num_orientations (VlCovDet const *self)
| Get the max number of orientations.
vl_bool | vl_covdet_get_transposed (VlCovDet const *self)
| Get wether images are passed in transposed.
VlScaleSpace * | vl_covdet_get_gss (VlCovDet const *self)
| Get the Gaussian scale space.
VlScaleSpace * | vl_covdet_get_css (VlCovDet const *self)
| Get the cornerness measure scale space.
vl_bool | vl_covdet_get_aa_accurate_smoothing (VlCovDet const *self)
| Get whether affine adaptation uses accurate smoothing.
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.
double | vl_covdet_get_non_extrema_suppression_threshold (VlCovDet const *self)
| Get the non-extrema suppression threshold.
vl_size | vl_covdet_get_num_non_extrema_suppressed (VlCovDet const *self)
| Get the number of non-extrema suppressed.
vl_bool | vl_covdet_get_allow_padded_warping (VlCovDet const *self)
| Get wether to compute padded warped patches.
Set parameters
void | vl_covdet_set_first_octave (VlCovDet *self, vl_index o)
| Set the index of the first octave.
void | vl_covdet_set_num_octaves (VlCovDet *self, vl_size o)
| Set the max number of octaves.
void | vl_covdet_set_base_scale (VlCovDet *self, double s)
| Set the GSS base scale.
void | vl_covdet_set_octave_resolution (VlCovDet *self, vl_size r)
| Set the octave resolutuon.
void | vl_covdet_set_peak_threshold (VlCovDet *self, double peakThreshold)
| Set the peak threshold.
void | vl_covdet_set_edge_threshold (VlCovDet *self, double edgeThreshold)
| Set the edge threshold.
void | vl_covdet_set_laplacian_peak_threshold (VlCovDet *self, double peakThreshold)
| Set the Laplacian peak threshold.
void | vl_covdet_set_max_num_orientations (VlCovDet *self, vl_size m)
| Set the max number of orientations.
void | vl_covdet_set_transposed (VlCovDet *self, vl_bool t)
| Set the index of the first octave.
void | vl_covdet_set_aa_accurate_smoothing (VlCovDet *self, vl_bool x)
| Set whether affine adaptation uses accurate smoothing.
void | vl_covdet_set_non_extrema_suppression_threshold (VlCovDet *self, double x)
| Set the non-extrema suppression threshod.
void | vl_covdet_set_allow_padded_warping (VlCovDet *self, vl_bool x)
| Set wether to compute padded warped patches.

## 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
| Covariant feature detection method.
const char * | vlFrameNames [VL_FRAMETYPE_NUM]
| Names of the frame types.
VlEnumerator | vlFrameTypes [VL_FRAMETYPE_NUM]
| Mapping between string values and VlFrameType values.
VlEnumerator | vlCovdetMethods [VL_COVDET_METHOD_NUM]
| Mapping between strings and VlCovDetMethod values.
struct _VlCovDet | VlCovDet
| Covariant feature detector.
vl_size | vl_get_frame_size (VlFrameType frameType)
| Get the size of a frame structure.
VlFrameType | vl_get_frame_type (vl_bool affineAdaptation, vl_bool orientation)
| Get the size of a frame structure.

## Detailed Description

Author
  Karel Lenc
  Andrea Vedaldi
  Michal Perdoch

## Enumeration Type Documentation

## ◆ VlFrameType

enum VlFrameType

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.

## Function Documentation

## ◆ vl_covdet_append_feature()

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

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.

## ◆ vl_covdet_delete()

void vl_covdet_delete | ( | VlCovDet * | self | ) |

Parameters

  self | object.

## ◆ vl_covdet_detect()

void vl_covdet_detect | ( | VlCovDet * | self | ) |

Parameters

  self | object.

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

  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.

## ◆ vl_covdet_extract_affine_shape()

void vl_covdet_extract_affine_shape | ( | VlCovDet * | self | ) |

Parameters

  self | object.

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

  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.

## ◆ vl_covdet_extract_laplacian_scales()

void vl_covdet_extract_laplacian_scales | ( | VlCovDet * | self | ) |

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.

## ◆ vl_covdet_extract_laplacian_scales_for_frame()

VlCovDetFeatureLaplacianScale * vl_covdet_extract_laplacian_scales_for_frame | ( | VlCovDet * | self,
|  | vl_size * | numScales,
|  | VlFrameOrientedEllipse | 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.

## ◆ vl_covdet_extract_orientations()

void vl_covdet_extract_orientations | ( | VlCovDet * | self | ) |

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.

## ◆ vl_covdet_extract_orientations_for_frame()

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

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.

## ◆ 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

  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.

## ◆ vl_covdet_get_aa_accurate_smoothing()

vl_bool vl_covdet_get_aa_accurate_smoothing | ( | VlCovDet const * | self | ) |

Parameters

  self | object.

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

  self | object.

Returns
  whether padded warped patches are computed.

## ◆ vl_covdet_get_base_scale()

double vl_covdet_get_base_scale | ( | VlCovDet const * | self | ) |

Parameters

  self | object.

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

  self | object.

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

  self | object.

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_scales_statistics()

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

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

## ◆ vl_covdet_get_max_num_orientations()

vl_size vl_covdet_get_max_num_orientations | ( | VlCovDet const * | self | ) |

Parameters

  self | object.

Returns
  maximal number of orientations.

## ◆ vl_covdet_get_non_extrema_suppression_threshold()

double vl_covdet_get_non_extrema_suppression_threshold | ( | VlCovDet const * | self | ) |

Parameters

  self | object.

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

  self | object.

Returns
  number.

## ◆ vl_covdet_get_num_octaves()

vl_size vl_covdet_get_num_octaves | ( | VlCovDet const * | self | ) |

Parameters

  self | object.

Returns
  maximal number of octaves.

## ◆ vl_covdet_get_octave_resolution()

vl_size vl_covdet_get_octave_resolution | ( | VlCovDet const * | self | ) |

Parameters

  self | object.

Returns
  octave resolution.

## ◆ vl_covdet_get_peak_threshold()

double vl_covdet_get_peak_threshold | ( | VlCovDet const * | self | ) |

Parameters

  self | object.

Returns
  the peak threshold.

## ◆ vl_covdet_get_transposed()

vl_bool vl_covdet_get_transposed | ( | VlCovDet const * | self | ) |

Parameters

  self | object.

Returns
  whether images are transposed.

## ◆ vl_covdet_new()

VlCovDet * vl_covdet_new | ( | VlCovDetMethod | method | ) |

Parameters

  method | method 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

  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.

## ◆ vl_covdet_reset()

void vl_covdet_reset | ( | VlCovDet * | self | ) |

Parameters

  self | object.

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

  self | object.
  x | whether accurate smoothing should be usd.

## ◆ vl_covdet_set_allow_padded_warping()

void vl_covdet_set_allow_padded_warping | ( | VlCovDet * | self,
|  | vl_bool | t )

Parameters

  self | object.
  t | whether padded warped patches are computed.

## ◆ vl_covdet_set_base_scale()

void vl_covdet_set_base_scale | ( | VlCovDet * | self,
|  | double | s )

Parameters

  self | object.
  s | the base scale.

Calling this function resets the detector.

## ◆ vl_covdet_set_edge_threshold()

void vl_covdet_set_edge_threshold | ( | VlCovDet * | self,
|  | double | edgeThreshold )

Parameters

  self | object.
  edgeThreshold | the 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

  self | object.
  o | index 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

  self | object.
  peakThreshold | the 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

  self | object.
  m | the 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

  self | object.
  x | threshold.

## ◆ vl_covdet_set_num_octaves()

void vl_covdet_set_num_octaves | ( | VlCovDet * | self,
|  | vl_size | o )

Parameters

  self | object.
  o | max 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

  self | object.
  r | octave resoltuion.

Calling this function resets the detector.

## ◆ vl_covdet_set_peak_threshold()

void vl_covdet_set_peak_threshold | ( | VlCovDet * | self,
|  | double | peakThreshold )

Parameters

  self | object.
  peakThreshold | the peak threshold.

The peak threshold must be non-negative.

## ◆ vl_covdet_set_transposed()

void vl_covdet_set_transposed | ( | VlCovDet * | self,
|  | vl_bool | t )

Parameters

  self | object.
  t | whether images are transposed.

## ◆ vl_get_frame_size()

vl_size vl_get_frame_size | ( | VlFrameType | frameType | ) |

inline

Parameters

  frameType | identifier of the type of frame.

Returns
  size of the corresponding frame structure in bytes.

## ◆ vl_get_frame_type()

VlFrameType vl_get_frame_type | ( | vl_bool | affineAdaptation,
|  | vl_bool | orientation )

inline

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.

## Variable Documentation

## ◆ VlCovDet

struct _VlCovDet VlCovDet

See also
  Covariant feature detectors