|
MetricKnn API
Fast Similarity Search using the Metric Space Approach
|
|
MetricKnn API
Fast Similarity Search using the Metric Space Approach
|
The Distance is the object with the definition of the method for comparing objects. More...
#include <mknn_distance.hpp>
Public Member Functions | |
| DistanceParams & | getParameters () |
| Return the parameters used to create the distance. More... | |
| std::string | getIdPredefinedDistance () |
| The id of the predefined distance. More... | |
| DistanceEval | newDistanceEval (Domain domain_left, Domain domain_right) |
| Creates a distance for computing distances between objects of the given domains. More... | |
| Distance () | |
| Default constructor. | |
| virtual | ~Distance () |
| Default destructor. | |
| Distance (const Distance &other) | |
| Copy constructor. | |
| Distance & | operator= (const Distance &other) |
| Assignment operator. | |
Static Public Member Functions | |
| static Distance | newPredefined (DistanceParams ¶meters) |
| Creates a new distance for the given parameters. More... | |
| static Distance | newCustom (DistanceCustomFactory *factory, bool delete_factory_on_distance_release) |
| Creates a new custom function. More... | |
Protected Attributes | |
| std::unique_ptr< Impl > | pimpl |
| Internal opaque class. | |
Friends | |
| class | Domain |
| class | Index |
Load/Save distances | |
| static Distance | restore (std::string filename_read, DistanceParams &more_parameters) |
| Loads a distance from a file. More... | |
| void | save (std::string filename_write) |
| The distance is saved to a file. More... | |
The Distance is the object with the definition of the method for comparing objects.
A distance object can be instantiated in three different ways:
1) Using one of the constructors for predefined distances in PredefinedDistance class.
2) Using function pointers and define a custom distance, see Distance::newCustom.
3) Using the generic method newPredefined, which requires a DistanceParams 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 PredefDistance::helpListDistances. The parameters supported by each distance can be printed by calling 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 compute distance values, the Distance object must be used to instantiate one or more DistanceEval objects (one for each parallel thread). The DistanceEval object is used to compute the distance value between two objects.
The DistanceEval is created by the method mknn::Distance::newDistanceEval, which requires the actual domain of the objects to be compared.
A search method uses the Distance to create as many DistanceEval as threads will be used to solve the search. During the search, each thread uses a single DistanceEval.
| std::string mknn::Distance::getIdPredefinedDistance | ( | ) |
The id of the predefined distance.
| DistanceParams& mknn::Distance::getParameters | ( | ) |
Return the parameters used to create the distance.
|
static |
Creates a new custom function.
When resolving a search using N parallel threads, the factory is invoked N times (thus creating a state for each thread), then each thread invokes mknn::DistanceCustomInstance::evalDistance.
| factory | the object that will be used to obtain instances of mknn::DistanceCustomInstance |
| delete_factory_on_distance_release | binds the lifetime of factory to the new distance object |
| DistanceEval mknn::Distance::newDistanceEval | ( | Domain | domain_left, |
| Domain | 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 DistanceEval::eval. These two domains must be compatible with the domain of distance, i.e., they may differ only in the datatype (see Domain::testEqualExceptDatatype).
| domain_left | the domain of the left object |
| domain_right | the domain of the right object |
|
static |
Creates a new distance for the given parameters.
The list of pre-defined distances can be listed by invoking PredefDistance::helpListDistances.
| parameters | the parameters to create the distance. |
| delete_parameters_on_distance_release | binds the lifetime of parameters to the new distance. |
|
static |
Loads a distance from a file.
The file must have been created by save.
| 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. |
| delete_parameters_on_distance_release | binds the lifetime of more_parameters to the new distance. |
| void mknn::Distance::save | ( | std::string | 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.
| filename_write | File to create. If the file already exists it is overwritten. |
1.8.9.1