MknnDistance represents a method for comparing objects. More...

#include "../metricknn_c.h"

Typedefs
typedef void (	mknn_function_distanceEval_createState) (MknnDomain domain_left, MknnDomain domain_right)
	The function of a custom distance that creates a new state. More...

typedef double(*	mknn_function_distanceEval_eval) (void state_distEval, void object_left, void *object_right, double current_threshold)
	Computes the distance between two objects. More...

typedef void(*	mknn_function_distanceEval_releaseState) (void *state_distEval)
	The function of a custom distance that releases a state. More...

typedef void(*	mknn_function_distanceFactory_createDistEval) (void state_factory, MknnDomain domain_left, MknnDomain domain_right, void out_state_distEval, mknn_function_distanceEval_eval out_func_eval, mknn_function_distanceEval_releaseState *out_func_releaseState)
	The function of a custom distance factory. More...

typedef void(*	mknn_function_distanceFactory_releaseFactory) (void *state_factory)
	The function to release the state of the distance factory. More...

Functions
MknnDistance *	mknn_distance_newPredefined (MknnDistanceParams *parameters, bool free_parameters_on_distance_release)
	Creates a new distance for the given parameters. More...

MknnDistance *	mknn_distance_newCustom (mknn_function_distanceEval_createState func_createState, mknn_function_distanceEval_eval func_eval, mknn_function_distanceEval_releaseState func_releaseState)
	Creates a new custom distance. More...

MknnDistance *	mknn_distance_newCustomFactory (void *state_factory, mknn_function_distanceFactory_createDistEval func_factory, mknn_function_distanceFactory_releaseFactory func_release)
	Creates a new custom distance, using a factory method. More...

MknnDistanceParams *	mknn_distance_getParameters (MknnDistance *distance)
	Return the parameters used to create the predefined distance. More...

const char *	mknn_distance_getIdPredefinedDistance (MknnDistance *distance)
	The id of the predefined distance. More...

void	mknn_distance_save (MknnDistance distance, const char filename_write)
	The distance is saved to a file. More...

MknnDistance *	mknn_distance_restore (const char filename_read, MknnDistanceParams more_parameters, bool free_parameters_on_distance_release)
	Loads a distance from a file. More...

MknnDistanceEval *	mknn_distance_newDistanceEval (MknnDistance distance, MknnDomain domain_left, MknnDomain *domain_right)
	Creates a distance for computing distances between objects of the given domains. More...

void	mknn_distance_release (MknnDistance *distance)
	Releases the distance. More...

Detailed Description

MknnDistance represents a method for comparing objects.

A MknnDistance object can be instantiated in three different ways:

1) Using one of the constructors for predefined distances. For example, mknn_predefDistance_L2.

2) Using function pointers and define a custom distance, see mknn_distance_newCustom.

3) Using the generic method mknn_distance_newPredefined, which requires a MknnDistanceParams object. The parameters can be created by parsing a string of parameters (e.g. a command line parameter), by setting each required parameter, or by loading a configuration file. Each pre-defined distance is identified by a unique distance identifier. Some valid IDs are:

L1 The Manhattan or taxi-cab distance.
L2 The Euclidean distance.
LMAX The maximum distance.
LP Any Minkowsky distance.
EMD The Earth Mover's distance.
DPF The Dynamic Partial Function.
CHI2 The Chi-squared distance.
HAMMING The hamming distance.

The complete list of pre-defined distances provided by MetricKnn can be printed by calling mknn_predefDistance_helpListDistances. The parameters supported by each distance can be printed by calling mknn_predefDistance_helpPrintDistance.

Depending on the distance, the constructor method may take some time to complete. In order to reduce the build time, a distance can be saved and then loaded.

Each predefined distance requires the objects to compare be in a given general domain, i.e., vectors, strings or multi object.

In order to compare objects, the MknnDistance must be used to instantiate one or more MknnDistanceEval objects.

Typedef Documentation

typedef void*(* mknn_function_distanceEval_createState) (MknnDomain *domain_left, MknnDomain *domain_right)

The function of a custom distance that creates a new state.

This method is internally invoked by mknn_distance_newDistanceEval to create one state for each thread resolving the search.

Parameters

domain_left	domain of the left object of the distance.
domain_right	domain of the right object of the distance.

Returns: a new state that will be given to mknn_function_distanceEval_eval

typedef double(* mknn_function_distanceEval_eval) (void *state_distEval, void *object_left, void *object_right, double current_threshold)

Computes the distance between two objects.

The parameters state_dist is the value returned by mknn_function_distanceEval_createState. The parameters domain_left and domain_right are the same objects given to mknn_function_distanceEval_createState.

This method is internally invoked by mknn_distanceEval_eval.

Parameters

state_distEval	an object that was previously created by mknn_function_distanceEval_createState.
object_left	is the left object of the distance.
object_right	is the right object of the distance.
current_threshold	is the value of the current k-th candidate in a search. This value may be used to trigger an early termination of the computation. See mknn_distanceEval_eval.

Returns: the distance value between object_left and object_right which must be a number >= 0.

typedef void(* mknn_function_distanceEval_releaseState) (void *state_distEval)

The function of a custom distance that releases a state.

The state is an object that was returned by mknn_function_distanceEval_createState.

This method is internally invoked by mknn_distanceEval_release for each state previously created by mknn_function_distanceEval_createState.

Parameters

state_eval the value to be released.

typedef void(* mknn_function_distanceFactory_createDistEval) (void *state_factory, MknnDomain *domain_left, MknnDomain *domain_right, void **out_state_distEval, mknn_function_distanceEval_eval *out_func_eval, mknn_function_distanceEval_releaseState *out_func_releaseState)

The function of a custom distance factory.

Parameters

state_factory	the state of the factory
domain_left	domain of the left object of the distance.
domain_right	domain of the right object of the distance.
out_state_distEval	the state of the created distance
out_func_eval	the function to eval the distance
out_func_releaseState	the function to release `out_state_distEval`.

typedef void(* mknn_function_distanceFactory_releaseFactory) (void *state_factory)

The function to release the state of the distance factory.

Called by mknn_distance_release.

Parameters

state_factory the state of the factory to release

Function Documentation

const char* mknn_distance_getIdPredefinedDistance ( MknnDistance * distance )

The id of the predefined distance.

Parameters

distance a predefined distance.

Returns: a string with an id or NULL if it is a custom distance.

MknnDistanceParams* mknn_distance_getParameters ( MknnDistance * distance )

Return the parameters used to create the predefined distance.

Parameters

distance a predefined distance.

Returns: the parameters used to create the distance.

MknnDistance* mknn_distance_newCustom	(	mknn_function_distanceEval_createState	func_createState,
		mknn_function_distanceEval_eval	func_eval,
		mknn_function_distanceEval_releaseState	func_releaseState
	)

Creates a new custom distance.

When resolving a search using N parallel threads, the function func_createState is invoked N times (creating a state for each thread), then each thread invokes func_eval passing its corresponding state, and at the end func_releaseState is invoked N times to release the N states.

Remarks: func_createState, func_eval and func_releaseState may be called in parallel by different threads. Therefore if they write to some global variable, some synchronization method is required (e.g. pthread_mutex_lock and pthread_mutex_unlock). Despite func_eval may be called in parallel, it does not need any synchronization if it only writes to the state_dist object (which is created by func_createState).

If func_createState needs some common state (e.g. to save time at invoking for all threads) or if the definition of func_eval depends on the domains, the mknn_distance_newCustomFactory can use a common state and can vary the func_eval.

Parameters

func_createState	The function that creates a new state for computing the distance or NULL if it is not required.
func_eval	The function that computes the distance between two objects.
func_releaseState	The function that releases the state created by `func_createState`.

Returns: the new distance

MknnDistance* mknn_distance_newCustomFactory	(	void *	state_factory,
		mknn_function_distanceFactory_createDistEval	func_factory,
		mknn_function_distanceFactory_releaseFactory	func_release
	)

Creates a new custom distance, using a factory method.

Parameters

state_factory
func_factory
func_release

Returns: the new distance

MknnDistanceEval* mknn_distance_newDistanceEval	(	MknnDistance *	distance,
		MknnDomain *	domain_left,
		MknnDomain *	domain_right
	)

Creates a distance for computing distances between objects of the given domains.

domain_object1 and domain_object2 are the domains of the objects that will be used in mknn_distanceEval_eval. These two domains must be compatible with the domain of distance, i.e., they may differ only in the datatype (see mknn_domain_testEqualExceptDatatype).

Parameters

distance	the distance
domain_left	the domain of the left object
domain_right	the domain of the right object

Returns: a new distance (it must be released with mknn_distanceEval_release).

MknnDistance* mknn_distance_newPredefined	(	MknnDistanceParams *	parameters,
		bool	free_parameters_on_distance_release
	)

Creates a new distance for the given parameters.

The list of pre-defined distances can be listed by invoking mknn_predefDistance_helpListDistances.

Parameters

parameters	the parameters to create the distance.
free_parameters_on_distance_release	bind the lifetime of `parameters` to the new distance.

Returns: a new distance (must be released)

void mknn_distance_release ( MknnDistance * distance )

Releases the distance.

Parameters

distance the distance to be released.

MknnDistance* mknn_distance_restore	(	const char *	filename_read,
		MknnDistanceParams *	more_parameters,
		bool	free_parameters_on_distance_release
	)

Loads a distance from a file.

The file must have been created by mknn_distance_save.

Parameters

filename_read	File to read. If the file does not exists an error is raised.
more_parameters	any parameter that may override the stored parameters or new parameters that could not be saved.
free_parameters_on_distance_release	to release `more_parameters` during the release of the new distance.

Returns: a new distance (it must be released with mknn_distance_release).

void mknn_distance_save	(	MknnDistance *	distance,
		const char *	filename_write
	)

The distance is saved to a file.

It may create other files using filename_write as prefix. The created files may be in binary format for fast loading.

Remarks: A custom distance cannot be saved.

Parameters

distance	the distance to save
filename_write	File to create. If the file already exists it is overwritten.

Typedefs

Functions

Detailed Description

Typedef Documentation

Function Documentation