Documentation>C API
Vector of Locally Aggregated Descriptors (VLAD) encoding

Author
  David Novotny
  Andrea Vedaldi

vlad.h implements the Vector of Linearly Aggregated Descriptors (VLAD) image representation [11] [2] .

Getting started with VLAD demonstreates how to use the C API to compute the VLAD representation of an image. For further details on the VLAD image representation refer to:

- VLAD fundamentals - VLAD definition and computation.

# Getting started with VLAD

The VLAD encoding of a set of features is obtained by using the function vl_vlad_encode. The function can be applied to both `float` or `double` data types.

vl_vlad_encode requires a visual dictionary, for example obtained by using K-means clustering. Furthermore, the assignments of features to dictionary elements must be pre-computed, for example by using KD-trees and forests.

In the following example code, the vocabulary is first created using the KMeans clustering, then the points, that are to be encoded are assigned to its corresponding nearest vocabulary words, after that the original vlad encoding routine without any normalization option takes place. At the end of the process the encoding is stored in the `enc` variable.

vl_uint32 * indexes;
float * assignments;
float * enc
int i;
// create a KMeans object and run clustering to get vocabulary words (centers)
kmeans = vl_kmeans_new (VLDistanceL2, VL_TYPE_FLOAT) ;
vl_kmeans_cluster (kmeans,
data,
dimension,
numData,
numCenters) ;
// find nearest cliuster centers for the data that should be encoded
indexes = vl_malloc(sizeof(vl_uint32) * numDataToEncode);
vl_kmeans_quantize(kmeans,indexes,dataToEncode,numDataToEncode);
// convert indexes array to assignments array,
// which can be processed by vl_vlad_encode
assignments = vl_malloc(sizeof(float) * numDataToEncode * numCenters);
memset(assignments, 0, sizeof(float) * numDataToEncode * numCenters);
for(i = 0; i < numDataToEncode; i++) {
assignments[i * numCenters + indexes[i]] = 1.;
}
// allocate space for vlad encoding
enc = vl_malloc(sizeof(TYPE) * dimension * numCenters);
// do the encoding job
vl_vlad_encode (enc, VL_F_TYPE,
vl_kmeans_get_centers(kmeans), dimension, numCenters,
data, numData,
assignments,
0) ;
vl_malloc
void * vl_malloc(size_t n)
Allocate a memory block.
Definition generic.c:1312
VL_TYPE_FLOAT
#define VL_TYPE_FLOAT
Definition generic.h:35
vl_uint32
int unsigned vl_uint32
Unsigned 32-bit integer.
Definition host.h:382
vl_kmeans_quantize
void vl_kmeans_quantize(VlKMeans *self, vl_uint32 *assignments, void *distances, void const *data, vl_size numData)
Quantize data.
Definition kmeans.c:1912
vl_kmeans_new
VlKMeans * vl_kmeans_new(vl_type dataType, VlVectorComparisonType distance)
Create a new KMeans object.
Definition kmeans.c:406
vl_kmeans_cluster
double vl_kmeans_cluster(VlKMeans *self, void const *data, vl_size dimension, vl_size numData, vl_size numCenters)
Cluster data.
Definition kmeans.c:2028
vl_kmeans_get_centers
void const * vl_kmeans_get_centers(VlKMeans const *self)
Get centers.
Definition kmeans.h:252
vl_vlad_encode
void vl_vlad_encode(void *enc, vl_type dataType, void const *means, vl_size dimension, vl_size numClusters, void const *data, vl_size numData, void const *assignments, int flags)
VLAD encoding of a set of vectors.
Definition vlad.c:293

Various VLAD normalization normalizations can be applied to the VLAD vectors. These are controlled by the parameter flag of vl_vlad_encode.