Documentation>C API
Gaussian Scale Space (GSS)

Author
  Karel Lenc
  Andrea Vedaldi
  Michal Perdoch

scalespace.h implements a Gaussian scale space, a data structure representing an image at multiple resolutions [32] [13] [14] . Scale spaces have many use, including the detection of co-variant local features [15] such as SIFT, Hessian-Affine, Harris-Affine, Harris-Laplace, etc. Getting started demonstreates how to use the C API to compute the scalespace of an image. For further details refer to:

- Gaussian scale space fundamentals

# Getting started

Given an input image `image`, the following example uses the VlScaleSpace object to compute its Gaussian scale space and return the image `level` at scale `(o,s)`, where `o` is the octave and `s` is the octave subdivision or sublevel:

float* level ;
VlScaleSpace ss = vl_scalespace_new(imageWidth, imageHeight) ;
vl_scalespace_put_image(ss, image) ;
level = vl_scalespace_get_level(ss, o, s) ;
vl_scalespace_put_image
void vl_scalespace_put_image(VlScaleSpace *self, float const *image)
Initialise Scale space with new image.
Definition: scalespace.c:812
vl_scalespace_new
VlScaleSpace * vl_scalespace_new(vl_size width, vl_size height)
Create a new scale space object.
Definition: scalespace.c:536
vl_scalespace_get_level
float * vl_scalespace_get_level(VlScaleSpace *self, vl_index o, vl_index s)
Get the data of a scale space level.
Definition: scalespace.c:390
VlScaleSpace
Scale space class.

The image `level` is obtained by convolving `image` by a Gaussian filter of isotropic standard deviation given by

double sigma = vl_scalespace_get_sigma(ss, o, s) ;

The resolution of `level` is in general different from the resolution of `image` and is determined by the octave `o`. It can be obtained as follows:

VlScaleSpaceOctaveGeometry ogeom = vl_scalespace_get_octave_geometry(ss, o) ;
ogeom.width // width of level (in number of pixels)
ogeom.height // height of level (in number of pixels)
ogeom.step // spatial sampling step
vl_scalespace_get_octave_geometry
VlScaleSpaceOctaveGeometry vl_scalespace_get_octave_geometry(VlScaleSpace const *self, vl_index o)
Get the geometry of an octave of the scalespace.
Definition: scalespace.c:369
VlScaleSpaceOctaveGeometry
Geometry of one octave of a scale space.
Definition: scalespace.h:54
VlScaleSpaceOctaveGeometry::height
vl_size height
Definition: scalespace.h:56
VlScaleSpaceOctaveGeometry::step
double step
Definition: scalespace.h:57
VlScaleSpaceOctaveGeometry::width
vl_size width
Definition: scalespace.h:55

The parameter `ogeom.step` is the sampling step relatively to the sampling of the input image `image`. The ranges of valid octaves and scale sublevels can be obtained as

VlScaleSpaceGeometry geom = vl_scalespace_get_geometry(ss) ;
geom.firstOctave // Index of the fisrt octave
geom.lastOctave // Index of the last octave
geom.octaveResolution ; // Number of octave subdivisions
geom.octaveFirstSubdivision // Index of the first octave subdivision
geom.octaveLastSubdivision // Index of the last octave subdivision
vl_scalespace_get_geometry
VlScaleSpaceGeometry vl_scalespace_get_geometry(VlScaleSpace const *self)
Get the geometry of the scale space.
Definition: scalespace.c:357
VlScaleSpaceGeometry
Geometry of a scale space.
Definition: scalespace.h:32
VlScaleSpaceGeometry::lastOctave
vl_index lastOctave
Definition: scalespace.h:36
VlScaleSpaceGeometry::octaveLastSubdivision
vl_index octaveLastSubdivision
Definition: scalespace.h:39
VlScaleSpaceGeometry::octaveResolution
vl_size octaveResolution
Definition: scalespace.h:37
VlScaleSpaceGeometry::octaveFirstSubdivision
vl_index octaveFirstSubdivision
Definition: scalespace.h:38
VlScaleSpaceGeometry::firstOctave
vl_index firstOctave
Definition: scalespace.h:35

So for example `o` minimum value is `geom.firstOctave` and maximum value is `geom.lastOctave`. The subdivision index `s` naturally spans the range 0 to `geom.octaveResolution-1`. However, the scale space object is flexible in that it allows different ranges of subdivisions to be computed and `s` varies in the range `geom.octaveFirstSubdivision` to `geom.octaveLastSubdivision`. See Gaussian scale space fundamentals for further details.

The geometry of the scale space can be customized upon creation, as follows:

VlScaleSpaceGeometry geom = vl_scalespace_get_default_geometry(imageWidth, imageHeight) ;
geom.firstOctave = -1 ;
geom.octaveFirstSubdivision = -1 ;
geom.octaveLastSubdivision = geom.octaveResolution ;
VlScaleSpacae ss = vl_scalespace_new_with_geometry (geom) ;
vl_scalespace_new_with_geometry
VlScaleSpace * vl_scalespace_new_with_geometry(VlScaleSpaceGeometry geom)
Create a new scale space with the specified geometry.
Definition: scalespace.c:558
vl_scalespace_get_default_geometry
VlScaleSpaceGeometry vl_scalespace_get_default_geometry(vl_size width, vl_size height)
Get the default geometry for a given image size.
Definition: scalespace.c:306