Free cookie consent management tool by TermsFeed Policy Generator

source: branches/2886_SymRegGrammarEnumeration/ExpressionClustering/flann/include/flann/flann.h @ 15840

Last change on this file since 15840 was 15840, checked in by gkronber, 6 years ago

#2886 added utility console program for clustering of expressions

File size: 23.6 KB
Line 
1/***********************************************************************
2 * Software License Agreement (BSD License)
3 *
4 * Copyright 2008-2009  Marius Muja (mariusm@cs.ubc.ca). All rights reserved.
5 * Copyright 2008-2009  David G. Lowe (lowe@cs.ubc.ca). All rights reserved.
6 *
7 * THE BSD LICENSE
8 *
9 * Redistribution and use in source and binary forms, with or without
10 * modification, are permitted provided that the following conditions
11 * are met:
12 *
13 * 1. Redistributions of source code must retain the above copyright
14 *    notice, this list of conditions and the following disclaimer.
15 * 2. Redistributions in binary form must reproduce the above copyright
16 *    notice, this list of conditions and the following disclaimer in the
17 *    documentation and/or other materials provided with the distribution.
18 *
19 * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
20 * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
21 * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
22 * IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
23 * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
24 * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
25 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
26 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
27 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
28 * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
29 *************************************************************************/
30
31#ifndef FLANN_H_
32#define FLANN_H_
33
34#include "defines.h"
35
36#ifdef __cplusplus
37extern "C"
38{
39    using namespace flann;
40#endif
41
42
43struct FLANNParameters
44{
45    enum flann_algorithm_t algorithm; /* the algorithm to use */
46
47    /* search time parameters */
48    int checks;                /* how many leafs (features) to check in one search */
49    float cb_index;            /* cluster boundary index. Used when searching the kmeans tree */
50    float eps;     /* eps parameter for eps-knn search */
51
52    /*  kdtree index parameters */
53    int trees;                 /* number of randomized trees to use (for kdtree) */
54    int leaf_max_size;
55
56    /* kmeans index parameters */
57    int branching;             /* branching factor (for kmeans tree) */
58    int iterations;            /* max iterations to perform in one kmeans cluetering (kmeans tree) */
59    enum flann_centers_init_t centers_init;  /* algorithm used for picking the initial cluster centers for kmeans tree */
60
61    /* autotuned index parameters */
62    float target_precision;    /* precision desired (used for autotuning, -1 otherwise) */
63    float build_weight;        /* build tree time weighting factor */
64    float memory_weight;       /* index memory weigthing factor */
65    float sample_fraction;     /* what fraction of the dataset to use for autotuning */
66
67    /* LSH parameters */
68    unsigned int table_number_; /** The number of hash tables to use */
69    unsigned int key_size_;     /** The length of the key in the hash tables */
70    unsigned int multi_probe_level_; /** Number of levels to use in multi-probe LSH, 0 for standard LSH */
71
72    /* other parameters */
73    enum flann_log_level_t log_level;    /* determines the verbosity of each flann function */
74    long random_seed;            /* random seed to use */
75};
76
77
78typedef void* FLANN_INDEX; /* deprecated */
79typedef void* flann_index_t;
80
81FLANN_EXPORT extern struct FLANNParameters DEFAULT_FLANN_PARAMETERS;
82
83/**
84   Sets the log level used for all flann functions (unless
85   specified in FLANNParameters for each call
86
87   Params:
88    level = verbosity level
89 */
90FLANN_EXPORT void flann_log_verbosity(int level);
91
92
93/**
94 * Sets the distance type to use throughout FLANN.
95 * If distance type specified is MINKOWSKI, the second argument
96 * specifies which order the minkowski distance should have.
97 */
98FLANN_EXPORT void flann_set_distance_type(enum flann_distance_t distance_type, int order);
99
100
101/**
102   Builds and returns an index. It uses autotuning if the target_precision field of index_params
103   is between 0 and 1, or the parameters specified if it's -1.
104
105   Params:
106    dataset = pointer to a data set stored in row major order
107    rows = number of rows (features) in the dataset
108    cols = number of columns in the dataset (feature dimensionality)
109    speedup = speedup over linear search, estimated if using autotuning, output parameter
110    index_params = index related parameters
111    flann_params = generic flann parameters
112
113   Returns: the newly created index or a number <0 for error
114 */
115FLANN_EXPORT flann_index_t flann_build_index(float* dataset,
116                                             int rows,
117                                             int cols,
118                                             float* speedup,
119                                             struct FLANNParameters* flann_params);
120
121FLANN_EXPORT flann_index_t flann_build_index_float(float* dataset,
122                                                   int rows,
123                                                   int cols,
124                                                   float* speedup,
125                                                   struct FLANNParameters* flann_params);
126
127FLANN_EXPORT flann_index_t flann_build_index_double(double* dataset,
128                                                    int rows,
129                                                    int cols,
130                                                    float* speedup,
131                                                    struct FLANNParameters* flann_params);
132
133FLANN_EXPORT flann_index_t flann_build_index_byte(unsigned char* dataset,
134                                                  int rows,
135                                                  int cols,
136                                                  float* speedup,
137                                                  struct FLANNParameters* flann_params);
138
139FLANN_EXPORT flann_index_t flann_build_index_int(int* dataset,
140                                                 int rows,
141                                                 int cols,
142                                                 float* speedup,
143                                                 struct FLANNParameters* flann_params);
144
145/**
146 * Saves the index to a file. Only the index is saved into the file, the dataset corresponding to the index is not saved.
147 *
148 * @param index_id The index that should be saved
149 * @param filename The filename the index should be saved to
150 * @return Returns 0 on success, negative value on error.
151 */
152FLANN_EXPORT int flann_save_index(flann_index_t index_id,
153                                  char* filename);
154
155FLANN_EXPORT int flann_save_index_float(flann_index_t index_id,
156                                        char* filename);
157
158FLANN_EXPORT int flann_save_index_double(flann_index_t index_id,
159                                         char* filename);
160
161FLANN_EXPORT int flann_save_index_byte(flann_index_t index_id,
162                                       char* filename);
163
164FLANN_EXPORT int flann_save_index_int(flann_index_t index_id,
165                                      char* filename);
166
167/**
168 * Loads an index from a file.
169 *
170 * @param filename File to load the index from.
171 * @param dataset The dataset corresponding to the index.
172 * @param rows Dataset tors
173 * @param cols Dataset columns
174 * @return
175 */
176FLANN_EXPORT flann_index_t flann_load_index(char* filename,
177                                            float* dataset,
178                                            int rows,
179                                            int cols);
180
181FLANN_EXPORT flann_index_t flann_load_index_float(char* filename,
182                                                  float* dataset,
183                                                  int rows,
184                                                  int cols);
185
186FLANN_EXPORT flann_index_t flann_load_index_double(char* filename,
187                                                   double* dataset,
188                                                   int rows,
189                                                   int cols);
190
191FLANN_EXPORT flann_index_t flann_load_index_byte(char* filename,
192                                                 unsigned char* dataset,
193                                                 int rows,
194                                                 int cols);
195
196FLANN_EXPORT flann_index_t flann_load_index_int(char* filename,
197                                                int* dataset,
198                                                int rows,
199                                                int cols);
200
201
202/**
203   Builds an index and uses it to find nearest neighbors.
204
205   Params:
206    dataset = pointer to a data set stored in row major order
207    rows = number of rows (features) in the dataset
208    cols = number of columns in the dataset (feature dimensionality)
209    testset = pointer to a query set stored in row major order
210    trows = number of rows (features) in the query dataset (same dimensionality as features in the dataset)
211    indices = pointer to matrix for the indices of the nearest neighbors of the testset features in the dataset
212            (must have trows number of rows and nn number of columns)
213    nn = how many nearest neighbors to return
214    flann_params = generic flann parameters
215
216   Returns: zero or -1 for error
217 */
218FLANN_EXPORT int flann_find_nearest_neighbors(float* dataset,
219                                              int rows,
220                                              int cols,
221                                              float* testset,
222                                              int trows,
223                                              int* indices,
224                                              float* dists,
225                                              int nn,
226                                              struct FLANNParameters* flann_params);
227
228FLANN_EXPORT int flann_find_nearest_neighbors_float(float* dataset,
229                                                    int rows,
230                                                    int cols,
231                                                    float* testset,
232                                                    int trows,
233                                                    int* indices,
234                                                    float* dists,
235                                                    int nn,
236                                                    struct FLANNParameters* flann_params);
237
238FLANN_EXPORT int flann_find_nearest_neighbors_double(double* dataset,
239                                                     int rows,
240                                                     int cols,
241                                                     double* testset,
242                                                     int trows,
243                                                     int* indices,
244                                                     double* dists,
245                                                     int nn,
246                                                     struct FLANNParameters* flann_params);
247
248FLANN_EXPORT int flann_find_nearest_neighbors_byte(unsigned char* dataset,
249                                                   int rows,
250                                                   int cols,
251                                                   unsigned char* testset,
252                                                   int trows,
253                                                   int* indices,
254                                                   float* dists,
255                                                   int nn,
256                                                   struct FLANNParameters* flann_params);
257
258FLANN_EXPORT int flann_find_nearest_neighbors_int(int* dataset,
259                                                  int rows,
260                                                  int cols,
261                                                  int* testset,
262                                                  int trows,
263                                                  int* indices,
264                                                  float* dists,
265                                                  int nn,
266                                                  struct FLANNParameters* flann_params);
267
268
269/**
270   Searches for nearest neighbors using the index provided
271
272   Params:
273    index_id = the index (constructed previously using flann_build_index).
274    testset = pointer to a query set stored in row major order
275    trows = number of rows (features) in the query dataset (same dimensionality as features in the dataset)
276    indices = pointer to matrix for the indices of the nearest neighbors of the testset features in the dataset
277            (must have trows number of rows and nn number of columns)
278    dists = pointer to matrix for the distances of the nearest neighbors of the testset features in the dataset
279            (must have trows number of rows and 1 column)
280    nn = how many nearest neighbors to return
281    flann_params = generic flann parameters
282
283   Returns: zero or a number <0 for error
284 */
285FLANN_EXPORT int flann_find_nearest_neighbors_index(flann_index_t index_id,
286                                                    float* testset,
287                                                    int trows,
288                                                    int* indices,
289                                                    float* dists,
290                                                    int nn,
291                                                    struct FLANNParameters* flann_params);
292
293FLANN_EXPORT int flann_find_nearest_neighbors_index_float(flann_index_t index_id,
294                                                          float* testset,
295                                                          int trows,
296                                                          int* indices,
297                                                          float* dists,
298                                                          int nn,
299                                                          struct FLANNParameters* flann_params);
300
301FLANN_EXPORT int flann_find_nearest_neighbors_index_double(flann_index_t index_id,
302                                                           double* testset,
303                                                           int trows,
304                                                           int* indices,
305                                                           double* dists,
306                                                           int nn,
307                                                           struct FLANNParameters* flann_params);
308
309FLANN_EXPORT int flann_find_nearest_neighbors_index_byte(flann_index_t index_id,
310                                                         unsigned char* testset,
311                                                         int trows,
312                                                         int* indices,
313                                                         float* dists,
314                                                         int nn,
315                                                         struct FLANNParameters* flann_params);
316
317FLANN_EXPORT int flann_find_nearest_neighbors_index_int(flann_index_t index_id,
318                                                        int* testset,
319                                                        int trows,
320                                                        int* indices,
321                                                        float* dists,
322                                                        int nn,
323                                                        struct FLANNParameters* flann_params);
324
325
326/**
327 * Performs an radius search using an already constructed index.
328 *
329 * In case of radius search, instead of always returning a predetermined
330 * number of nearest neighbours (for example the 10 nearest neighbours), the
331 * search will return all the neighbours found within a search radius
332 * of the query point.
333 *
334 * The check parameter in the FLANNParameters below sets the level of approximation
335 * for the search by only visiting "checks" number of features in the index
336 * (the same way as for the KNN search). A lower value for checks will give
337 * a higher search speedup at the cost of potentially not returning all the
338 * neighbours in the specified radius.
339 *
340 * The cores parameter in the FLANNParameters below sets the number of cores
341 * that will be used for the radius search, in case Intel TBB is present on
342 * the system and FLANN is built with multicore support on. Auto core selection
343 * can be achieved by setting the number of cores to -1.
344 */
345FLANN_EXPORT int flann_radius_search(flann_index_t index_ptr, /* the index */
346                                     float* query, /* query point */
347                                     int* indices, /* array for storing the indices found (will be modified) */
348                                     float* dists, /* similar, but for storing distances */
349                                     int max_nn,  /* size of arrays indices and dists */
350                                     float radius, /* search radius (squared radius for euclidian metric) */
351                                     struct FLANNParameters* flann_params);
352
353FLANN_EXPORT int flann_radius_search_float(flann_index_t index_ptr, /* the index */
354                                           float* query, /* query point */
355                                           int* indices, /* array for storing the indices found (will be modified) */
356                                           float* dists, /* similar, but for storing distances */
357                                           int max_nn,  /* size of arrays indices and dists */
358                                           float radius, /* search radius (squared radius for euclidian metric) */
359                                           struct FLANNParameters* flann_params);
360
361FLANN_EXPORT int flann_radius_search_double(flann_index_t index_ptr, /* the index */
362                                            double* query, /* query point */
363                                            int* indices, /* array for storing the indices found (will be modified) */
364                                            double* dists, /* similar, but for storing distances */
365                                            int max_nn,  /* size of arrays indices and dists */
366                                            float radius, /* search radius (squared radius for euclidian metric) */
367                                            struct FLANNParameters* flann_params);
368
369FLANN_EXPORT int flann_radius_search_byte(flann_index_t index_ptr, /* the index */
370                                          unsigned char* query, /* query point */
371                                          int* indices, /* array for storing the indices found (will be modified) */
372                                          float* dists, /* similar, but for storing distances */
373                                          int max_nn,  /* size of arrays indices and dists */
374                                          float radius, /* search radius (squared radius for euclidian metric) */
375                                          struct FLANNParameters* flann_params);
376
377FLANN_EXPORT int flann_radius_search_int(flann_index_t index_ptr, /* the index */
378                                         int* query, /* query point */
379                                         int* indices, /* array for storing the indices found (will be modified) */
380                                         float* dists, /* similar, but for storing distances */
381                                         int max_nn,  /* size of arrays indices and dists */
382                                         float radius, /* search radius (squared radius for euclidian metric) */
383                                         struct FLANNParameters* flann_params);
384
385/**
386   Deletes an index and releases the memory used by it.
387
388   Params:
389    index_id = the index (constructed previously using flann_build_index).
390    flann_params = generic flann parameters
391
392   Returns: zero or a number <0 for error
393 */
394FLANN_EXPORT int flann_free_index(flann_index_t index_id,
395                                  struct FLANNParameters* flann_params);
396
397FLANN_EXPORT int flann_free_index_float(flann_index_t index_id,
398                                        struct FLANNParameters* flann_params);
399
400FLANN_EXPORT int flann_free_index_double(flann_index_t index_id,
401                                         struct FLANNParameters* flann_params);
402
403FLANN_EXPORT int flann_free_index_byte(flann_index_t index_id,
404                                       struct FLANNParameters* flann_params);
405
406FLANN_EXPORT int flann_free_index_int(flann_index_t index_id,
407                                      struct FLANNParameters* flann_params);
408
409/**
410   Clusters the features in the dataset using a hierarchical kmeans clustering approach.
411   This is significantly faster than using a flat kmeans clustering for a large number
412   of clusters.
413
414   Params:
415    dataset = pointer to a data set stored in row major order
416    rows = number of rows (features) in the dataset
417    cols = number of columns in the dataset (feature dimensionality)
418    clusters = number of cluster to compute
419    result = memory buffer where the output cluster centers are storred
420    index_params = used to specify the kmeans tree parameters (branching factor, max number of iterations to use)
421    flann_params = generic flann parameters
422
423   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
424    way hierarchical clusters are computed. The number of clusters returned will be the highest number of the form
425    (branch_size-1)*K+1 smaller than the number of clusters requested.
426 */
427
428FLANN_EXPORT int flann_compute_cluster_centers(float* dataset,
429                                               int rows,
430                                               int cols,
431                                               int clusters,
432                                               float* result,
433                                               struct FLANNParameters* flann_params);
434
435FLANN_EXPORT int flann_compute_cluster_centers_float(float* dataset,
436                                                     int rows,
437                                                     int cols,
438                                                     int clusters,
439                                                     float* result,
440                                                     struct FLANNParameters* flann_params);
441
442FLANN_EXPORT int flann_compute_cluster_centers_double(double* dataset,
443                                                      int rows,
444                                                      int cols,
445                                                      int clusters,
446                                                      double* result,
447                                                      struct FLANNParameters* flann_params);
448
449FLANN_EXPORT int flann_compute_cluster_centers_byte(unsigned char* dataset,
450                                                    int rows,
451                                                    int cols,
452                                                    int clusters,
453                                                    float* result,
454                                                    struct FLANNParameters* flann_params);
455
456FLANN_EXPORT int flann_compute_cluster_centers_int(int* dataset,
457                                                   int rows,
458                                                   int cols,
459                                                   int clusters,
460                                                   float* result,
461                                                   struct FLANNParameters* flann_params);
462
463
464#ifdef __cplusplus
465}
466
467
468#include "flann.hpp"
469
470#endif
471
472
473#endif /*FLANN_H_*/
474
Note: See TracBrowser for help on using the repository browser.