mirror of https://github.com/opencv/opencv.git
Open Source Computer Vision Library
https://opencv.org/
You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
278 lines
9.8 KiB
278 lines
9.8 KiB
/*********************************************************************** |
|
* Software License Agreement (BSD License) |
|
* |
|
* Copyright 2008-2009 Marius Muja (mariusm@cs.ubc.ca). All rights reserved. |
|
* Copyright 2008-2009 David G. Lowe (lowe@cs.ubc.ca). All rights reserved. |
|
* |
|
* THE BSD LICENSE |
|
* |
|
* Redistribution and use in source and binary forms, with or without |
|
* modification, are permitted provided that the following conditions |
|
* are met: |
|
* |
|
* 1. Redistributions of source code must retain the above copyright |
|
* notice, this list of conditions and the following disclaimer. |
|
* 2. Redistributions in binary form must reproduce the above copyright |
|
* notice, this list of conditions and the following disclaimer in the |
|
* documentation and/or other materials provided with the distribution. |
|
* |
|
* THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR |
|
* IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES |
|
* OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. |
|
* IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, |
|
* INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT |
|
* NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, |
|
* DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY |
|
* THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT |
|
* (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF |
|
* THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. |
|
*************************************************************************/ |
|
|
|
#ifndef FLANN_H |
|
#define FLANN_H |
|
|
|
|
|
#include "constants.h" |
|
|
|
|
|
#ifdef WIN32 |
|
/* win32 dll export/import directives */ |
|
#ifdef flann_EXPORTS |
|
#define LIBSPEC __declspec(dllexport) |
|
#else |
|
#define LIBSPEC __declspec(dllimport) |
|
#endif |
|
#else |
|
/* unix needs nothing */ |
|
#define LIBSPEC |
|
#endif |
|
|
|
|
|
|
|
|
|
|
|
struct FLANNParameters { |
|
flann_algorithm_t algorithm; // the algorithm to use (see constants.h) |
|
|
|
int checks; // how many leafs (features) to check in one search |
|
float cb_index; // cluster boundary index. Used when searching the kmeans tree |
|
int trees; // number of randomized trees to use (for kdtree) |
|
int branching; // branching factor (for kmeans tree) |
|
int iterations; // max iterations to perform in one kmeans cluetering (kmeans tree) |
|
flann_centers_init_t centers_init; // algorithm used for picking the initial cluetr centers for kmeans tree |
|
float target_precision; // precision desired (used for autotuning, -1 otherwise) |
|
float build_weight; // build tree time weighting factor |
|
float memory_weight; // index memory weigthing factor |
|
float sample_fraction; // what fraction of the dataset to use for autotuning |
|
|
|
flann_log_level_t log_level; // determines the verbosity of each flann function |
|
char* log_destination; // file where the output should go, NULL for the console |
|
long random_seed; // random seed to use |
|
}; |
|
|
|
|
|
|
|
typedef void* FLANN_INDEX; // deprecated |
|
typedef void* flann_index_t; |
|
|
|
#ifdef __cplusplus |
|
extern "C" { |
|
#endif |
|
|
|
/** |
|
Sets the log level used for all flann functions (unless |
|
specified in FLANNParameters for each call |
|
|
|
Params: |
|
level = verbosity level (defined in constants.h) |
|
*/ |
|
LIBSPEC void flann_log_verbosity(int level); |
|
|
|
|
|
/** |
|
* Sets the distance type to use throughout FLANN. |
|
* If distance type specified is MINKOWSKI, the second argument |
|
* specifies which order the minkowski distance should have. |
|
*/ |
|
LIBSPEC void flann_set_distance_type(flann_distance_t distance_type, int order); |
|
|
|
|
|
/** |
|
Builds and returns an index. It uses autotuning if the target_precision field of index_params |
|
is between 0 and 1, or the parameters specified if it's -1. |
|
|
|
Params: |
|
dataset = pointer to a data set stored in row major order |
|
rows = number of rows (features) in the dataset |
|
cols = number of columns in the dataset (feature dimensionality) |
|
speedup = speedup over linear search, estimated if using autotuning, output parameter |
|
index_params = index related parameters |
|
flann_params = generic flann parameters |
|
|
|
Returns: the newly created index or a number <0 for error |
|
*/ |
|
LIBSPEC FLANN_INDEX flann_build_index(float* dataset, |
|
int rows, |
|
int cols, |
|
float* speedup, |
|
struct FLANNParameters* flann_params); |
|
|
|
|
|
|
|
|
|
|
|
/** |
|
* Saves the index to a file. Only the index is saved into the file, the dataset corresponding to the index is not saved. |
|
* |
|
* @param index_id The index that should be saved |
|
* @param filename The filename the index should be saved to |
|
* @return Returns 0 on success, negative value on error. |
|
*/ |
|
LIBSPEC int flann_save_index(FLANN_INDEX index_id, |
|
char* filename); |
|
|
|
|
|
/** |
|
* Loads an index from a file. |
|
* |
|
* @param filename File to load the index from. |
|
* @param dataset The dataset corresponding to the index. |
|
* @param rows Dataset tors |
|
* @param cols Dataset columns |
|
* @return |
|
*/ |
|
LIBSPEC FLANN_INDEX flann_load_index(char* filename, |
|
float* dataset, |
|
int rows, |
|
int cols); |
|
|
|
|
|
|
|
/** |
|
Builds an index and uses it to find nearest neighbors. |
|
|
|
Params: |
|
dataset = pointer to a data set stored in row major order |
|
rows = number of rows (features) in the dataset |
|
cols = number of columns in the dataset (feature dimensionality) |
|
testset = pointer to a query set stored in row major order |
|
trows = number of rows (features) in the query dataset (same dimensionality as features in the dataset) |
|
indices = pointer to matrix for the indices of the nearest neighbors of the testset features in the dataset |
|
(must have trows number of rows and nn number of columns) |
|
nn = how many nearest neighbors to return |
|
index_params = index related parameters |
|
flann_params = generic flann parameters |
|
|
|
Returns: zero or -1 for error |
|
*/ |
|
LIBSPEC int flann_find_nearest_neighbors(float* dataset, |
|
int rows, |
|
int cols, |
|
float* testset, |
|
int trows, |
|
int* indices, |
|
float* dists, |
|
int nn, |
|
struct FLANNParameters* flann_params); |
|
|
|
|
|
|
|
/** |
|
Searches for nearest neighbors using the index provided |
|
|
|
Params: |
|
index_id = the index (constructed previously using flann_build_index). |
|
testset = pointer to a query set stored in row major order |
|
trows = number of rows (features) in the query dataset (same dimensionality as features in the dataset) |
|
indices = pointer to matrix for the indices of the nearest neighbors of the testset features in the dataset |
|
(must have trows number of rows and nn number of columns) |
|
nn = how many nearest neighbors to return |
|
checks = number of checks to perform before the search is stopped |
|
flann_params = generic flann parameters |
|
|
|
Returns: zero or a number <0 for error |
|
*/ |
|
LIBSPEC int flann_find_nearest_neighbors_index(FLANN_INDEX index_id, |
|
float* testset, |
|
int trows, |
|
int* indices, |
|
float* dists, |
|
int nn, |
|
int checks, |
|
struct FLANNParameters* flann_params); |
|
|
|
|
|
|
|
/** |
|
* Performs an radius search using an already constructed index. |
|
* |
|
* In case of radius search, instead of always returning a predetermined |
|
* number of nearest neighbours (for example the 10 nearest neighbours), the |
|
* search will return all the neighbours found within a search radius |
|
* of the query point. |
|
* |
|
* The check parameter in the function below sets the level of approximation |
|
* for the search by only visiting "checks" number of features in the index |
|
* (the same way as for the KNN search). A lower value for checks will give |
|
* a higher search speedup at the cost of potentially not returning all the |
|
* neighbours in the specified radius. |
|
*/ |
|
LIBSPEC int flann_radius_search(FLANN_INDEX index_ptr, /* the index */ |
|
float* query, /* query point */ |
|
int* indices, /* array for storing the indices found (will be modified) */ |
|
float* dists, /* similar, but for storing distances */ |
|
int max_nn, /* size of arrays indices and dists */ |
|
float radius, /* search radius (squared radius for euclidian metric) */ |
|
int checks, /* number of features to check, sets the level of approximation */ |
|
FLANNParameters* flann_params); |
|
|
|
|
|
/** |
|
Deletes an index and releases the memory used by it. |
|
|
|
Params: |
|
index_id = the index (constructed previously using flann_build_index). |
|
flann_params = generic flann parameters |
|
|
|
Returns: zero or a number <0 for error |
|
*/ |
|
LIBSPEC int flann_free_index(FLANN_INDEX index_id, |
|
struct FLANNParameters* flann_params); |
|
|
|
/** |
|
Clusters the features in the dataset using a hierarchical kmeans clustering approach. |
|
This is significantly faster than using a flat kmeans clustering for a large number |
|
of clusters. |
|
|
|
Params: |
|
dataset = pointer to a data set stored in row major order |
|
rows = number of rows (features) in the dataset |
|
cols = number of columns in the dataset (feature dimensionality) |
|
clusters = number of cluster to compute |
|
result = memory buffer where the output cluster centers are storred |
|
index_params = used to specify the kmeans tree parameters (branching factor, max number of iterations to use) |
|
flann_params = generic flann parameters |
|
|
|
Returns: number of clusters computed or a number <0 for error. This number can be different than the number of clusters requested, due to the |
|
way hierarchical clusters are computed. The number of clusters returned will be the highest number of the form |
|
(branch_size-1)*K+1 smaller than the number of clusters requested. |
|
*/ |
|
|
|
LIBSPEC int flann_compute_cluster_centers(float* dataset, |
|
int rows, |
|
int cols, |
|
int clusters, |
|
float* result, |
|
struct FLANNParameters* flann_params); |
|
|
|
|
|
#ifdef __cplusplus |
|
}; |
|
|
|
|
|
#include "flann.hpp" |
|
|
|
#endif |
|
|
|
|
|
#endif /*FLANN_H*/
|
|
|