Documentation - C API
scalespace.h File Reference

Scale Space (Gaussian Scale Space) More...

#include "pgm.h"
#include <stdio.h>
#include <math.h>
#include "generic.h"
#include "imopv.h"

Data Structures

struct  VlScaleSpaceFrame
 Scale space feature frame. More...
struct  VlScaleSpace
 Scale space. More...
struct  VlAffineShapeEstimatorFrame
 Affine frame. More...
struct  VlAffineShapeEstimator
 Affine shape detector. More...

Typedefs

typedef void( VlScaleSpaceCallback )(float const *srcImage, int src_width, int src_height, float *dstImage, int dst_width, int dst_height, int octave, int level, void *params)
 Scale space processing callback.

Functions

Create and destroy
VlScaleSpacevl_scalespace_new (vl_size width, vl_size height, vl_index numOctaves, vl_index firstOctave, vl_size numLevels, vl_index firstLevel, vl_index lastLevel)
 Creates a new VlScaleSpace object.
void vl_scalespace_delete (VlScaleSpace *self)
 Delete a VlScaleSpace object.
VlScaleSpacevl_scalespace_clone_structure (VlScaleSpace *src)
 Clone the object but do not copy the data.
VlScaleSpacevl_scalespace_clone (VlScaleSpace *src)
 Clone the scale space with all its data.
void vl_scalespace_init (VlScaleSpace *self, float const *image)
 Initialise Scale space with new image.
VlAffineShapeEstimatorvl_affineshapeestimator_new (vl_size win_size)
 Create a new VlAffineShapeEstimator object instance.
void vl_affineshapeestimator_delete (VlAffineShapeEstimator *self)
 Delete Affine shape estimator filter.
Process data
void vl_scalespace_apply (VlScaleSpace const *self, VlScaleSpace *dst, VlScaleSpaceCallback *callback, void *params)
 Apply a function to all levels of the scale space.
void vl_scalespace_diff (VlScaleSpace const *self, VlScaleSpace *dst)
 Compute the scale derivative.
void vl_scalespace_find_local_extrema (VlScaleSpace *self, double peakThreshold, vl_size borderSize)
 Detect local extrema.
void vl_scalespace_refine_local_extrema (VlScaleSpace *self, double peakThrehsold, double edgeThreshold, vl_size borderSize)
 Refine local extrema.
int vl_scalespace_extract_affine_patch (VlScaleSpace *self, float *patch, vl_size patchWidth, vl_size patchHeight, double patchSigma, double t1, double t2, double a11, double a21, double a12, double a22)
void vl_scalespace_frame_init (VlScaleSpace const *self, VlScaleSpaceFrame *frame, double x, double y, double sigma)
 Initialize a frame from its position and scale.
int vl_affineshapeestimator_estimate (VlAffineShapeEstimator *self, VlScaleSpace *scsp, const VlScaleSpaceFrame *frame, VlAffineShapeEstimatorFrame *aff_frame)
 Estimate an affine shape on a given frame.
void vl_affineshapeestimator_frame_init_from_aff (VlAffineShapeEstimator const *self, VlAffineShapeEstimatorFrame *frm, double x, double y, double a11, double a12, double a21, double a22)
void vl_affineshapeestimator_frame_init_from_ell (VlAffineShapeEstimator const *self, VlAffineShapeEstimatorFrame *frm, double x, double y, double e11, double e12, double e22)
int vl_affineshapeestimator_interpolate_bilinear (const float *image, vl_size width, vl_size height, double tx, double ty, double a11, double a12, double a21, double a22, float *dst, vl_size dstWidth, vl_size dstHeight)
 Get affinely-warped rectangular patch with bilinear interpolation.
Retrieve data and parameters
vl_size vl_scalespace_get_octaves_num (VlScaleSpace const *self)
 Get number of octaves.
vl_index vl_scalespace_get_octave_min (VlScaleSpace const *self)
 Get index of first octave.
vl_index vl_scalespace_get_octave_max (VlScaleSpace const *self)
 Get index of last octave.
vl_size vl_scalespace_get_octave_width (VlScaleSpace const *self, vl_index o)
 Get octave width.
vl_size vl_scalespace_get_octave_height (VlScaleSpace const *self, vl_index o)
 Get octave height.
vl_size vl_scalespace_get_levels_num (VlScaleSpace const *self)
 Get number of levels per octave.
vl_index vl_scalespace_get_level_min (VlScaleSpace const *self)
 Get the index of the lowest level.
vl_index vl_scalespace_get_level_max (VlScaleSpace const *self)
 Get the index of the top level.
vl_size vl_scalespace_get_frames_num (VlScaleSpace const *self)
 Get the number of stored feature frames.
double vl_scalespace_get_sigma0 (VlScaleSpace const *self)
 Get stddev of smoothing of pyramid base.
double vl_scalespace_get_sigmak (VlScaleSpace const *self)
 Get stddev of smoothing of pyramid base.
float * vl_scalespace_get_octave (VlScaleSpace const *self, vl_index o, vl_index s)
 Get the data of a scale level.
double vl_scalespace_get_sigma_for_scale (VlScaleSpace const *self, vl_index o, vl_index s)
 Get continous scale coordinate from scale index.
VlScaleSpaceFrame const * vl_scalespace_get_frames (VlScaleSpace const *self)
 Get the stored feature frames.
vl_size vl_affineshapeestimator_get_window_size (VlAffineShapeEstimator const *f)
 Get size of the window for smm calculation.
vl_size vl_affineshapeestimator_get_max_iter (VlAffineShapeEstimator const *self)
 Get maximal number of iterations.
double vl_affineshapeestimator_get_conv_thresh (VlAffineShapeEstimator const *self)
 Get convergance threshold.
Set parameters
void vl_affineshapeestimator_set_max_iter (VlAffineShapeEstimator *self, int m)
 Set maximal number of iterations.
void vl_affineshapeestimator_set_conv_thresh (VlAffineShapeEstimator *self, double t)
 Set convergence threshold.

Detailed Description

Author:
Andrea Vedaldi
Karel Lenc
Michal Perdoch

Typedef Documentation

typedef void( VlScaleSpaceCallback)(float const *srcImage, int src_width, int src_height, float *dstImage, int dst_width, int dst_height, int octave, int level, void *params)

Scale space callback appliable to separate planes.


Function Documentation

void vl_affineshapeestimator_delete ( VlAffineShapeEstimator f)
Parameters:
fAffine shape estimator to delete.

The function frees the resources allocated by ::vl_affine_new().

int vl_affineshapeestimator_estimate ( VlAffineShapeEstimator self,
VlScaleSpace scsp,
VlScaleSpaceFrame const *  frame,
VlAffineShapeEstimatorFrame affineFrame 
)
Parameters:
fAffine estimator filter
blurScale-space plane where the frame was found
widthWidth of the blur plane
heightHeight of the blur plane
xx-coordinate of a frame in the blur plane
yy-coordinate of a frame in the blur plane
sScale of the frame in its octave
double vl_affineshapeestimator_get_conv_thresh ( VlAffineShapeEstimator const *  self) [inline]
Parameters:
fAffine filter.
Returns:
Convergence threshold.
vl_size vl_affineshapeestimator_get_max_iter ( VlAffineShapeEstimator const *  self) [inline]
Parameters:
fAffine filter.
Returns:
Maximal number of iterations.
vl_size vl_affineshapeestimator_get_window_size ( VlAffineShapeEstimator const *  f) [inline]
Parameters:
fAffine filter.
Returns:
Size of the window for smm calculation.
int vl_affineshapeestimator_interpolate_bilinear ( const float *  image,
vl_size  width,
vl_size  height,
double  tx,
double  ty,
double  a11,
double  a12,
double  a21,
double  a22,
float *  dst,
vl_size  dstWidth,
vl_size  dstHeight 
)
Parameters:
srcinput image.
widthwidth of input image.
heightheight of input image.
txx-coordinate of the patch center.
tyy-coordinate of the patch center.
a11component of the linear map.
a12component of the linear map.
a21component of the linear map.
a22component of the linear map.
dstoutput image.
dstWidthwidth of the output image.
dstHeightheight of the output image.

Interpolates affine neighbourhood of a point $x_0 = (offsx, offsy) $ from the src image into the image according to affine trasnformation matrix $ A $. The size of the interpolated neighbourhood is defined by the size of the $a dst image $a dst_width and $a dstHeight and of course by the properties of the affine transformation.

Interpolate affine neighbourhood

\[ \hat{x} \in \hat{\Omega}_{src} ; \hat{\Omega}_{src} \subset \Omega_{src}; \Omega_{src} = \left\{(x, y) : x \in \langle 0, \mathit{width}), y \in \langle 0, \mathit{height})\right\} \]

of image $ src (x); x \in \Omega_{src} $ to the image

\[ dst(x'); x' \in \Omega_{dst}; \Omega_{dst} = \left\{(x, y) : x \in \langle 0, \mathit{dstWidth}), y \in \langle 0, \mathit{dstHeight})\right\} \]

such that:

\[ \forall x' : dst(x') = src(\hat{x}), \hat{x} = A x' + x_0, A = \left[ \begin{array}{cc} a11 & a12 \\ a21 & a22 \end{array} \right], x_0 = (\mathit{offsx}, \mathit{offsy}) \]

Where the more precise values of dst are found using bilinear interpolation.

Returns:
!=0 if the region touches the boundary of the input
VlAffineShapeEstimator* vl_affineshapeestimator_new ( vl_size  win_size)
Parameters:
win_sizesize of the patch used for affine shape estimation
Returns:
new object instance.

The function allocates and initialises a new VlAffineShapeEstimator object instance for the specified size of the The function allocates and returns a new Affine shape estimator with the specified size of the window used for calculating the second moment matrix (SMM).

See also:
::vl_affine_delete().
void vl_affineshapeestimator_set_conv_thresh ( VlAffineShapeEstimator self,
double  t 
) [inline]
Parameters:
fAffine filter.
tConvergence threshold.
void vl_affineshapeestimator_set_max_iter ( VlAffineShapeEstimator self,
int  m 
) [inline]
Parameters:
fAffine filter.
mmaximal number of iterations.
void vl_scalespace_apply ( VlScaleSpace const *  self,
VlScaleSpace dst,
VlScaleSpaceCallback callback,
void *  params 
)
Parameters:
selfVlScaleSpace object instance.
dstDestination
callbackCallback applied to all planes
paramsPointer to auxiliar callback params

This function apply a callback to all the layers of scale space self and stores the result to the scale space res. self and res must have the same number of octaves and number of levels in each octave. The size of particular planes can differ however must be handled by the callback.

VlScaleSpace* vl_scalespace_clone ( VlScaleSpace self)

Performs deep copy of the scale space.

Parameters:
selfScale space which should be cloned.
VlScaleSpace* vl_scalespace_clone_structure ( VlScaleSpace self)
Parameters:
selfVlScaleSpace object instance.
Returns:
the object copy, or NULL.

The function can fail if the memory is insufficient to hold the object copy. In this case, the function returns NULL.

void vl_scalespace_delete ( VlScaleSpace self)
Parameters:
selfobject to delete.
See also:
vl_scalespace_new
void vl_scalespace_diff ( VlScaleSpace const *  self,
VlScaleSpace dst 
)
Parameters:
selfVlScaleSpace object instance to differentiate.
dstoutput VlScaleSpace object instance.

This function computes the differences of the scale level of the scale space and stores the result to a second scale sapce dst. If the scale space is a Gaussian scale space, then dst results in the so called Difference of Gaussian (DoG).

The geometry of dst must be compatible with the geometry of the scale space self. Specifically, the size of dst must be identical to the size of the scale space expect for the fact that there is one scale level less per octave:

int vl_scalespace_extract_affine_patch ( VlScaleSpace self,
float *  patch,
vl_size  patchWidth,
vl_size  patchHeight,
double  patchSigma,
double  t1,
double  t2,
double  a11,
double  a21,
double  a12,
double  a22 
)
Parameters:
selfVlScaleSpace object instance.
peakThresholdpeak threshold.
edgeThresholdedge threshold.
borderSizeboderd size.
Returns:
status.

This function filters and adjust with sub-pixel accuracy the local extrema found by vl_scalespace_find_local_extrema().

\[ [-\frac{\mathtt{patchWidth}}{2}, +\frac{\mathtt{patchWidth}}{2}] \]

The function returns VL_ERR_ALLOC if there is not enough free memory to complete the operation.

void vl_scalespace_find_local_extrema ( VlScaleSpace self,
double  peakThreshold,
vl_size  borderSize 
)
Parameters:
selfVlScaleSpace object.
peakThreshold
borderSizeThe function detects the local extrema in the scale space and stores the result in the internal feature frame buffer. The feature frames can be retrieved by vl_scalespace_get_frames.
See also:
vl_scalespace_find_local_extrema()
void vl_scalespace_frame_init ( VlScaleSpace const *  self,
VlScaleSpaceFrame frame,
double  x,
double  y,
double  sigma 
)
Parameters:
fScale space object.
kScale space frame (output).
xx coordinate of the frame center.
yy coordinate of the frame center.
sigmaframe scale.

The function initializes a frame structure k from the location x and y and the scale sigma of the frame. The frame structure maps the frame to an octave and scale level of the discretized Gaussian scale space, which is required for instance to compute the frame SIFT descriptor.

Algorithm

The formula linking the frame scale sigma to the octave and scale indexes is

\[ \sigma(o,s) = \sigma_0 2^{o+s/S} \]

In addition to the scale index s (which can be fractional due to scale interpolation) a frame has an integer scale index is too (which is the index of the scale level where it was detected in the DoG scale space). We have the constraints (sift-tech-detector see also the "SIFT detector"):

  • o is integer in the range $ [o_\mathrm{min}, o_{\mathrm{min}}+O-1] $.
  • is is integer in the range $ [s_\mathrm{min}+1, s_\mathrm{max}-2] $. This depends on how the scale is determined during detection, and must be so here because gradients are computed only for this range of scale levels and are required for the calculation of the SIFT descriptor.
  • $ |s - is| < 0.5 $ for detected frames in most cases due to the interpolation technique used during detection. However this is not necessary.

Thus octave o represents scales $ \{ \sigma(o, s) : s \in [s_\mathrm{min}+1-.5, s_\mathrm{max}-2+.5] \} $. Note that some scales may be represented more than once. For each scale, we select the largest possible octave that contains it, i.e.

\[ o(\sigma) = \max \{ o \in \mathbb{Z} : \sigma_0 2^{\frac{s_\mathrm{min}+1-.5}{S}} \leq \sigma \} = \mathrm{floor}\,\left[ \log_2(\sigma / \sigma_0) - \frac{s_\mathrm{min}+1-.5}{S}\right] \]

and then

\[ s(\sigma) = S \left[\log_2(\sigma / \sigma_0) - o(\sigma)\right], \quad is(\sigma) = \mathrm{round}\,(s(\sigma)) \]

In practice, both $ o(\sigma) $ and $ is(\sigma) $ are clamped to their feasible range as determined by the SIFT filter parameters.

VlScaleSpaceFrame const * vl_scalespace_get_frames ( VlScaleSpace const *  self) [inline]
Parameters:
selfVlScaleSpace object instance.
Returns:
pointer to the frames list.
vl_size vl_scalespace_get_frames_num ( VlScaleSpace const *  self) [inline]
Parameters:
selfVlScaleSpace object instance.
Returns:
number of frames.
vl_index vl_scalespace_get_level_max ( VlScaleSpace const *  self) [inline]
Parameters:
selfVlScaleSpace object instance..
Returns:
index of the top level.
vl_index vl_scalespace_get_level_min ( VlScaleSpace const *  self) [inline]
Parameters:
selfVlScaleSpace object instance.
Returns:
index of the lowest level.
vl_size vl_scalespace_get_levels_num ( VlScaleSpace const *  self) [inline]
Parameters:
selfVlScaleSpace object instance.
Returns:
number of leves per octave.
float * vl_scalespace_get_octave ( VlScaleSpace const *  self,
vl_index  o,
vl_index  s 
) [inline]
Parameters:
selfVlScaleSpace object instance.
ooctave index.
slevel index.
Returns:
pointer to the data for octave o, level s.

The octave index o must be in the range firstOctave to lastOctave and the scale index s must be in the range firstLevel to lastLevel.

vl_size vl_scalespace_get_octave_height ( VlScaleSpace const *  self,
vl_index  o 
) [inline]
Parameters:
selfVlScaleSpace object instance.
ooctave index.
Returns:
current octave height.
vl_index vl_scalespace_get_octave_max ( VlScaleSpace const *  self) [inline]
Parameters:
selfVlScaleSpace object instance.
Returns:
index of the last octave.
vl_index vl_scalespace_get_octave_min ( VlScaleSpace const *  self) [inline]
Parameters:
selfVlScaleSpace object instance.
Returns:
index of the first octave.
vl_size vl_scalespace_get_octave_width ( VlScaleSpace const *  self,
vl_index  o 
) [inline]
Parameters:
selfVlScaleSpace object instance.
ooctave index.
Returns:
current octave width.
vl_size vl_scalespace_get_octaves_num ( VlScaleSpace const *  self) [inline]
Parameters:
selfVlScaleSpace object instance..
Returns:
number of octaves.
double vl_scalespace_get_sigma0 ( VlScaleSpace const *  self) [inline]
Parameters:
selfVlScaleSpace object instance.
Returns:
Standard deviation of smoothing of pyramid base.
double vl_scalespace_get_sigma_for_scale ( VlScaleSpace const *  self,
vl_index  o,
vl_index  s 
) [inline]
Parameters:
selfVlScaleSpace object instance.
ooctave.
soctave sub-level.
Returns:
contiunous scale coordinate.
double vl_scalespace_get_sigmak ( VlScaleSpace const *  self) [inline]
Parameters:
selfVlScaleSpace object instance.
Returns:
Standard deviation of smoothing of pyramid base.
void vl_scalespace_init ( VlScaleSpace self,
float const *  image 
)
Parameters:
selfVlScaleSpace object instance.
imageimage to process.

Compute the data of all the defined octaves and scales of the scale space self.

VlScaleSpace* vl_scalespace_new ( vl_size  width,
vl_size  height,
vl_index  numOctaves,
vl_index  firstOctave,
vl_size  numLevels,
vl_index  firstLevel,
vl_index  lastLevel 
)
Parameters:
widthimage width.
heightimage height.
numOctavesnumber of octaves.
firstOctaveindex of the first octave.
numLevelsnumeber of levels per octave.
firstLevelindex of the first level.
lastLevelindex of the last level.
Returns:
the new scale space.

The function allocates and returns a new VlScaleSpace object of the specified geometry.

If numOctaves is a negative number, the number of octaves is selected to the maximum possible given the size of the image.

Parameters firstLevel and lastLevel allow to define additional levels on top or bottom of the scale-space although the scale-space would be calculated with parameters based on numLevels. This is for example used when we need to compute additional levels for local extrema localisation when e.g.:

 numLevels = 3, firstLevel = -1, lastLevel = 3

would create scale space with 5 levels indexed as:

 -1  0  1  2  3
See also:
vl_scalespace_delete().
void vl_scalespace_refine_local_extrema ( VlScaleSpace self,
double  peakThreshold,
double  edgeThreshold,
vl_size  borderSize 
)
Parameters:
selfVlScaleSpace object instance.
peakThresholdpeak threshold.
edgeThresholdedge threshold.
borderSizeboderd size.

This function filters and adjust with sub-pixel accuracy the local extrema found by vl_scalespace_find_local_extrema().

See also:
vl_scalespace_find_local_extrema()

Index GSS

Index matrix A