Documentation - C API
scalespace.c File Reference

Scale Space - Definition. More...

#include "scalespace.h"
#include "mathop.h"
#include <assert.h>
#include <stdlib.h>
#include <string.h>
#include <math.h>
#include <stdio.h>

Functions

static void copy_and_upsample (float *destination, float const *source, vl_size width, vl_size height)
 Upsample the rows and take the transpose.
static void copy_and_downsample (float *destination, float const *source, vl_size width, vl_size height, vl_size numOctaves)
 Downsample.
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 (VlScaleSpace *self)
 Clone the scale space with all its data.
VlScaleSpacevl_scalespace_clone_structure (VlScaleSpace *self)
 Clone the object but do not copy the data.
void _vl_scalespace_fill_octave (VlScaleSpace *self, vl_index o)
 Fill octave startinf from first level.
static void _vl_scalespace_start_octave_from_image (VlScaleSpace *self, float const *image, vl_index o)
 Initialize the first level of an octave from an image.
static void _vl_scalespace_start_octave_from_previous_octave (VlScaleSpace *self, vl_index o)
 Initialize the first level of an octave from the previous octave.
void vl_scalespace_init (VlScaleSpace *self, float const *image)
 Initialise Scale space with new image.
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.
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_refine_local_extrema (VlScaleSpace *self, double peakThreshold, double edgeThreshold, vl_size borderSize)
 Refine local extrema.
void vl_scalespace_frame_init (VlScaleSpace const *self, VlScaleSpaceFrame *frame, double x, double y, double sigma)
 Initialize a frame from its position and scale.
void vl_compute_gauss_mask (float *mask, int width, float sigma)
 Compute Gaussian mask.
int get_eigen_values (float a, float b, float c, float d, float *l1, float *l2)
 Get real-valued Eigen-values of 2x2 matrix [a,b;c,d].
VlAffineShapeEstimatorvl_affineshapeestimator_new (vl_size win_size)
 Create a new VlAffineShapeEstimator object instance.
void vl_affineshapeestimator_delete (VlAffineShapeEstimator *f)
 Delete Affine shape estimator filter.
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.
int vl_affineshapeestimator_estimate (VlAffineShapeEstimator *self, VlScaleSpace *scsp, VlScaleSpaceFrame const *frame, VlAffineShapeEstimatorFrame *affineFrame)
 Estimate an affine shape on a given frame.

Detailed Description

Author:
Andrea Vedaldi
Karel Lenc
Michal Perdoch

Function Documentation

void _vl_scalespace_fill_octave ( VlScaleSpace self,
vl_index  o 
)
Parameters:
selfVlScaleSpace object instance.
ooctave to process.

The function takes the first level of octave o and iteratively smoothes it to obtain the other octave levels.

static void _vl_scalespace_start_octave_from_image ( VlScaleSpace self,
float const *  image,
vl_index  o 
) [static]
Parameters:
selfVlScaleSpace object instance.
imageimage data.
ooctave to start.

The function initializes the first level of octave o from image image. The dimensions of the image are the ones set during the creation of the VlScaleSpace object instance.

static void _vl_scalespace_start_octave_from_previous_octave ( VlScaleSpace self,
vl_index  o 
) [static]
Parameters:
VlScaleSpaceobjet instance.
ooctave to initialize.

The function initializes the first level of octave o from the content of octave o - 1.

static void copy_and_downsample ( float *  destination,
float const *  source,
vl_size  width,
vl_size  height,
vl_size  numOctaves 
) [static]
Parameters:
destinationoutput imgae buffer.
sourceinput image buffer.
widthinput image width.
heightinput image height.
numOctavesoctaves (non negative).

The function downsamples the image d times, reducing it to 1/2^d of its original size. The parameters width and height are the size of the input image. The destination image dst is assumed to be floor(width/2^d) pixels wide and floor(height/2^d) pixels high.

static void copy_and_upsample ( float *  destination,
float const *  source,
vl_size  width,
vl_size  height 
) [static]
Parameters:
destinationoutput image.
sourceinput image.
widthinput image width.
heightinput image height.

The output image has dimensions height by 2 width (so the destination buffer must be at least as big as two times the input buffer).

Upsampling is performed by linear interpolation.

int get_eigen_values ( float  a,
float  b,
float  c,
float  d,
float *  l1,
float *  l2 
) [inline]
Parameters:
a,b,c,dMatrix values.
l1Pointer to first eigen value.
l2Pointer to second eigen value.
Returns:
1 if the eigen values are real numbers. 0 if not or zero.
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
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_compute_gauss_mask ( float *  mask,
int  width,
float  sigma 
) [inline]
Parameters:
mskPointer to mask image
widthWidth of the mask
heightHeight of the mask
sigmaStandard deviation of the Gauss. function
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.

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