Documentation>C API
Functions
kmeans.c File Reference

K-means - Declaration. More...

`#include "kmeans.h"`
`#include "generic.h"`
`#include "mathop.h"`
`#include <string.h>`
`#include "shuffle-def.h"`

## Functions

void | vl_kmeans_reset (VlKMeans *self)
| Reset state.
VlKMeans * | vl_kmeans_new (vl_type dataType, VlVectorComparisonType distance)
| Create a new KMeans object.
VlKMeans * | vl_kmeans_new_copy (VlKMeans const *kmeans)
| Create a new KMeans object by copy.
void | vl_kmeans_delete (VlKMeans *self)
| Deletes a KMeans object.
void | vl_kmeans_set_centers (VlKMeans *self, void const *centers, vl_size dimension, vl_size numCenters)
| Set centers.
void | vl_kmeans_init_centers_with_rand_data (VlKMeans *self, void const *data, vl_size dimension, vl_size numData, vl_size numCenters)
| init centers by randomly sampling data
void | vl_kmeans_init_centers_plus_plus (VlKMeans *self, void const *data, vl_size dimension, vl_size numData, vl_size numCenters)
| Seed centers by the KMeans++ algorithm.
void | vl_kmeans_quantize (VlKMeans *self, vl_uint32 *assignments, void *distances, void const *data, vl_size numData)
| Quantize data.
void | vl_kmeans_quantize_ann (VlKMeans *self, vl_uint32 *assignments, void *distances, void const *data, vl_size numData, vl_bool update)
| Quantize data using approximate nearest neighbours (ANN).
double | vl_kmeans_refine_centers (VlKMeans *self, void const *data, vl_size numData)
| Refine center locations.
double | vl_kmeans_cluster (VlKMeans *self, void const *data, vl_size dimension, vl_size numData, vl_size numCenters)
| Cluster data.

## Detailed Description

Author
  Andrea Vedaldi, David Novotny

## Function Documentation

## ◆ vl_kmeans_cluster()

double vl_kmeans_cluster | ( | VlKMeans * | self,
|  | void const * | data,
|  | vl_size | dimension,
|  | vl_size | numData,
|  | vl_size | numCenters )

Parameters

  self | KMeans object.
  data | data to quantize.
  dimension | data dimension.
  numData | number of data points.
  numCenters | number of clusters.

Returns
  K-means energy at the end of optimization.

The function initializes the centers by using the initialization algorithm set by vl_kmeans_set_initialization and refines them by the quantization algorithm set by vl_kmeans_set_algorithm. The process is repeated one or more times (see vl_kmeans_set_num_repetitions) and the resutl with smaller energy is retained.

## ◆ vl_kmeans_delete()

void vl_kmeans_delete | ( | VlKMeans * | self | ) |

Parameters

  self | KMeans object instance.

The function deletes the KMeans object instance created by vl_kmeans_new.

## ◆ vl_kmeans_init_centers_plus_plus()

void vl_kmeans_init_centers_plus_plus | ( | VlKMeans * | self,
|  | void const * | data,
|  | vl_size | dimension,
|  | vl_size | numData,
|  | vl_size | numCenters )

Parameters

  self | KMeans object.
  data | data to sample from.
  dimension | data dimension.
  numData | nmber of data points.
  numCenters | number of centers.

## ◆ vl_kmeans_init_centers_with_rand_data()

void vl_kmeans_init_centers_with_rand_data | ( | VlKMeans * | self,
|  | void const * | data,
|  | vl_size | dimension,
|  | vl_size | numData,
|  | vl_size | numCenters )

Parameters

  self | KMeans object.
  data | data to sample from.
  dimension | data dimension.
  numData | nmber of data points.
  numCenters | number of centers.

The function inits the KMeans centers by randomly sampling the data data.

## ◆ vl_kmeans_new()

VlKMeans * vl_kmeans_new | ( | vl_type | dataType,
|  | VlVectorComparisonType | distance )

Parameters

  dataType | type of data (VL_TYPE_FLOAT or VL_TYPE_DOUBLE)
  distance | distance.

Returns
  new KMeans object instance.

## ◆ vl_kmeans_new_copy()

VlKMeans * vl_kmeans_new_copy | ( | VlKMeans const * | kmeans | ) |

Parameters

  kmeans | KMeans object to copy.

Returns
  new copy.

## ◆ vl_kmeans_quantize()

void vl_kmeans_quantize | ( | VlKMeans * | self,
|  | vl_uint32 * | assignments,
|  | void * | distances,
|  | void const * | data,
|  | vl_size | numData )

Parameters

  self | KMeans object.
  assignments | data to closest center assignments (output).
  distances | data to closest center distance (output).
  data | data to quantize.
  numData | number of data points to quantize.

## ◆ vl_kmeans_quantize_ann()

void vl_kmeans_quantize_ann | ( | VlKMeans * | self,
|  | vl_uint32 * | assignments,
|  | void * | distances,
|  | void const * | data,
|  | vl_size | numData,
|  | vl_bool | update )

Parameters

  self | KMeans object.
  assignments | data to centers assignments (output).
  distances | data to closes center distance (output)
  data | data to quantize.
  numData | number of data points.
  update | choose wether to update current assignments.

The function uses an ANN procedure to compute the approximate nearest neighbours of the input data point.

Setting update to VL_TRUE will cause the algorithm to update existing assignments. This means that each element of assignments and distances is updated ony if the ANN procedure can find a better assignment of the existing one.

## ◆ vl_kmeans_refine_centers()

double vl_kmeans_refine_centers | ( | VlKMeans * | self,
|  | void const * | data,
|  | vl_size | numData )

Parameters

  self | KMeans object.
  data | data to quantize.
  numData | number of data points.

Returns
  K-means energy at the end of optimization.

The function calls the underlying K-means quantization algorithm (VlKMeansAlgorithm) to quantize the specified data data. The function assumes that the cluster centers have already been assigned by using one of the seeding functions, or by setting them.

## ◆ vl_kmeans_reset()

void vl_kmeans_reset | ( | VlKMeans * | self | ) |

The function reset the state of the KMeans object. It deletes any stored centers, releasing the corresponding memory. This cancels the effect of seeding or setting the centers, but does not change the other configuration parameters.

## ◆ vl_kmeans_set_centers()

void vl_kmeans_set_centers | ( | VlKMeans * | self,
|  | void const * | centers,
|  | vl_size | dimension,
|  | vl_size | numCenters )

Parameters

  self | KMeans object.
  centers | centers to copy.
  dimension | data dimension.
  numCenters | number of centers.