X-Git-Url: https://vcs.maemo.org/git/?a=blobdiff_plain;f=3rdparty%2Finclude%2Fflann%2Fflann.h;fp=3rdparty%2Finclude%2Fflann%2Fflann.h;h=068753f1b716b28266bfd88b3c8700dd5c8a0b4e;hb=e4c14cdbdf2fe805e79cd96ded236f57e7b89060;hp=0000000000000000000000000000000000000000;hpb=454138ff8a20f6edb9b65a910101403d8b520643;p=opencv diff --git a/3rdparty/include/flann/flann.h b/3rdparty/include/flann/flann.h new file mode 100644 index 0000000..068753f --- /dev/null +++ b/3rdparty/include/flann/flann.h @@ -0,0 +1,278 @@ +/*********************************************************************** + * 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*/