Merge branch 'master' of github.com:mariusmuja/flann

Author: mariusmuja

CMakeLists.txt

@@ -12,9 +12,8 @@ set(FLANN_VERSION 1.8.4)
 DISSECT_VERSION()
 GET_OS_INFO()
 
-# CMAKE_C_COMPILER_ID and CMAKE_CXX_COMPILER_ID are documented as internal variables subject to
-# change at: http://www.cmake.org/cmake/help/v2.8.8/cmake.html#variable:CMAKE_LANG_COMPILER_ID
-# however currently this seems the most robust way to detect the presence of the Clang compiler
+
+# detect if using the Clang compiler
 if("${CMAKE_C_COMPILER_ID}" MATCHES "Clang")
   set(CMAKE_COMPILER_IS_CLANG 1)
 endif ()
@@ -54,6 +53,7 @@ option(BUILD_C_BINDINGS "Build C bindings" ON)
 option(BUILD_PYTHON_BINDINGS "Build Python bindings" ON)
 option(BUILD_MATLAB_BINDINGS "Build Matlab bindings" ON)
 option(BUILD_CUDA_LIB "Build CUDA library" OFF)
+option(BUILD_EXAMPLES "Build examples" ON)
 option(USE_OPENMP "Use OpenMP multi-threading" ON)
 option(USE_MPI "Use MPI" OFF)
 
@@ -146,16 +146,18 @@ include_directories(BEFORE ${PROJECT_SOURCE_DIR}/src/cpp)
 # require proper c++
 #add_definitions( "-Wall -ansi -pedantic" )
 # HDF5 uses long long which is not ansi
-if (MSVC)
+if("${CMAKE_C_COMPILER_ID}" MATCHES "MSVC" OR "${CMAKE_CXX_COMPILER_ID}" MATCHES "MSVC")
     # lots of warnings with cl.exe right now, use /W1
     add_definitions("/W1 -D_CRT_SECURE_NO_WARNINGS -D_SCL_SECURE_NO_WARNINGS /bigobj")
-else(MSVC)
+else()
     add_definitions( "-Wall -Wno-unknown-pragmas -Wno-unused-function" )
-endif(MSVC)
+endif()
 
 add_subdirectory( cmake )
 add_subdirectory( src )
-add_subdirectory( examples )
+if (BUILD_EXAMPLES)
+  add_subdirectory( examples )
+endif(BUILD_EXAMPLES)
 add_subdirectory( test )
 add_subdirectory( doc )
 

README.md

@@ -8,7 +8,7 @@ FLANN is written in C++ and contains bindings for the following languages: C, MA
 Documentation
 -------------
 
-Check FLANN web page [here](http://www.cs.ubc.ca/~mariusm/flann).
+Check FLANN web page [here](http://www.cs.ubc.ca/research/flann).
 
 Documentation on how to use the library can be found in the doc/manual.pdf file included in the release archives.
 

cmake/flann.pc.in

@@ -8,6 +8,6 @@ Name: @PROJECT_NAME@
 Description: @PKG_DESC@
 Version: @FLANN_VERSION@
 Requires: @PKG_EXTERNAL_DEPS@
-Libs: -L${libdir} -lflann_cpp
+Libs: -L${libdir} -lflann -lflann_cpp
 Cflags: -I${includedir}
 

doc/manual.pdf

@@ -670,7 +670,11 @@ \subsubsection{flann::Index::knnSearch}
 \item[indices]{Matrix that will contain the indices of the K-nearest neighbors found (size should be at least
 $num\_queries \times knn$ for the pre-allocated version).}
 \item[dists]{Matrix that will contain the distances to the K-nearest neighbors found (size should be at least
-$num\_queries \times knn$ for the pre-allocated version).}
+$num\_queries \times knn$ for the pre-allocated version). \\
+\emph{Note:} For Euclidean distances, the \texttt{flann::L2} functor computes squared distances, 
+so the value passed here needs to be a squared 
+distance as well.
+}
 \item[knn]{Number of nearest neighbors to search for.}
 \item[params]{Search parameters.} Structure containing parameters used during search.
 
@@ -679,16 +683,16 @@ \subsubsection{flann::Index::knnSearch}
 struct SearchParams
 {
 	SearchParams(int checks = 32,
-		  float eps = 0,
-		  bool sorted = true);
-
-    int checks;
-    float eps;
-    bool sorted;
-    int max_neighbors;
-    tri_type use_heap;
-    int cores;
-    bool matrices_in_gpu_ram;
+		float eps = 0,
+		bool sorted = true);
+
+	int checks;
+	float eps;
+	bool sorted;
+	int max_neighbors;
+	tri_type use_heap;
+	int cores;
+	bool matrices_in_gpu_ram;
 };
 \end{Verbatim}
 \begin{description}
@@ -737,9 +741,15 @@ \subsubsection{flann::Index::radiusSearch}
 will be resized as needed to fit all the neighbors to be returned, except if the ``max\_neighbors'' search parameter is
 set.}
 \item[dists]{Matrix that will contain the distances to the K-nearest neighbors found. The same number of values are
-returned here as for the \texttt{indices} matrix.}
-\item[radius]{The search radius}
-\item[params]{Search parameters}
+returned here as for the \texttt{indices} matrix.  \\
+\emph{Note:} For Euclidean distances, the 
+\texttt{flann::L2} functor computes squared distances, so the value passed here needs to 
+be a squared distance as well.}
+\item[radius]{The search radius. \\
+\emph{Note:} For Euclidean distances, the \texttt{flann::L2} functor computes squared distances, 
+so the value passed here needs to be a squared 
+distance as well.}
+\item[params]{Search parameters.}
 \end{description}
 The method returns the number of nearest neighbors found.
 
@@ -759,10 +769,10 @@ \subsubsection{flann::hierarchicalClustering}
 
 \begin{Verbatim}[fontsize=\footnotesize,frame=single]
 template <typename Distance>
-int hierarchicalClustering(const Matrix<typename Distance::ElementType>& features, 
-			Matrix<typename Distance::ResultType>& centers,
-			const KMeansIndexParams& params, 
-		        Distance d = Distance())
+int hierarchicalClustering(const Matrix<typename Distance::ElementType>& points, 
+	Matrix<typename Distance::ResultType>& centers,
+	const KMeansIndexParams& params,
+	Distance d = Distance())
 \end{Verbatim}
 \begin{description}
 \item[features]{The points to be clustered}
@@ -815,7 +825,7 @@ \subsubsection{flann::KdTreeCuda3dIndex}
 \begin{description}
  \item First, a GPU buffer of float4 values is created and filled with points. \footnote{For index creation, only \texttt{float4} points are supported, \texttt{float3} or structure-of-array (SOA) representations are currently not supported since
 \texttt{float4} proved to be best in terms of access speed for tree creation and search.}
- \item Then, a GPU pointer to the buffer is stored in a flann matrix with 3 columns and a stride of 4 (since the last element in the \texttt{float4} is unused).
+ \item Then, a GPU pointer to the buffer is stored in a flann matrix with 3 columns and a stride of 4 (the last element in the \texttt{float4} should be zero).
  \item Last, the index is created. The \texttt{input\_is\_gpu\_float4} flag tells the index to treat the matrix as a gpu buffer.
 \end{description}
 
@@ -892,52 +902,66 @@ \subsubsection{flann\_build\_index()}
 \item [flann\_params] - is a structure containing the parameters passed to
 the function. This structure is defined as follows:
 \begin{Verbatim}[fontsize=\footnotesize]
-struct FLANNParameters {
-  enum flann_algorithm_t algorithm; 	/* the algorithm to use */
-
-  /* search parameters */
-  int checks;            /* how many leafs (features) to check in one search */
-  float cb_index;        /* cluster boundary index. Used when searching the 
-			  kmeans tree */
-
-  /*  kdtree index parameters */
-  int trees;                 /* number of randomized trees to use (for kdtree) */
-
-  /* kmeans index parameters */
-  int branching;             /* branching factor (for kmeans tree) */
-  int iterations;            /* max iterations to perform in one kmeans cluetering 
-			      (kmeans tree) */
-  enum flann_centers_init_t centers_init;  /* algorithm used for picking the initial 
-				cluster centers for kmeans tree */
-
-  /* autotuned index parameters */
-  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 */
-
-  /* LSH parameters */
-  unsigned int table_number_; /** The number of hash tables to use */
-  unsigned int key_size_;     /** The length of the key in the hash tables */
-  unsigned int multi_probe_level_; /** Number of levels to use in multi-probe LSH, 0 for standard LSH */
-
-  /* other parameters */
-  enum flann_log_level_t log_level;   /* determines the verbosity of each flann function */
-  long random_seed;          		/* random seed to use */
+struct FLANNParameters
+{
+	enum flann_algorithm_t algorithm; /* the algorithm to use */
+
+	/* search time parameters */
+	int checks; /* how many leafs (features) to check in one search */
+	float eps; /* eps parameter for eps-knn search */
+	int sorted; /* indicates if results returned by radius search should be 
+	        sorted or not */
+	int max_neighbors; /* limits the maximum number of neighbors should be
+	        returned by radius search */
+	int cores; /* number of paralel cores to use for searching */
+
+	/*  kdtree index parameters */
+	int trees; /* number of randomized trees to use (for kdtree) */
+	int leaf_max_size;
+
+	/* kmeans index parameters */
+	int branching; /* branching factor (for kmeans tree) */
+	int iterations; /* max iterations to perform in one kmeans cluetering
+	        (kmeans tree) */
+	enum flann_centers_init_t centers_init; /* algorithm used for picking the
+	        initial cluster centers for kmeans tree */
+	float cb_index; /* cluster boundary index. Used when searching the kmeans
+	        tree */
+
+	/* autotuned index parameters */
+	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 */
+	/* LSH parameters */
+	unsigned int table_number_; /** The number of hash tables to use */
+	unsigned int key_size_; /** The length of the key in the hash tables */
+	unsigned int multi_probe_level_; /** Number of levels to use in multi-probe
+	        LSH, 0 for standard LSH */
+
+	/* other parameters */
+	enum flann_log_level_t log_level; /* determines the verbosity of each flann
+	        function */
+	long random_seed; /* random seed to use */
 };
 \end{Verbatim}
 
 The \texttt{algorithm} and \texttt{centers\_init} fields can take the
 following values:
 \begin{Verbatim}[fontsize=\footnotesize]
-enum flann_algorithm_t {
+enum flann_algorithm_t
+{
 	FLANN_INDEX_LINEAR = 0,
 	FLANN_INDEX_KDTREE = 1,
 	FLANN_INDEX_KMEANS = 2,
 	FLANN_INDEX_COMPOSITE = 3,
-	FLANN_INDEX_KDTREE_SINGLE = 3,
+	FLANN_INDEX_KDTREE_SINGLE = 4,
+	FLANN_INDEX_HIERARCHICAL = 5,
+	FLANN_INDEX_LSH = 6,
+	FLANN_INDEX_KDTREE_CUDA = 7, // available if compiled with CUDA
 	FLANN_INDEX_SAVED = 254,
-	FLANN_INDEX_AUTOTUNED = 255
+	FLANN_INDEX_AUTOTUNED = 255,
 };
 
 enum flann_centers_init_t {
@@ -966,20 +990,22 @@ \subsubsection{flann\_build\_index()}
 The field \texttt{log\_level} controls the verbosity of the messages generated by the FLANN
 library functions. It can take the following values:
 \begin{Verbatim}[fontsize=\footnotesize]
-enum flann_log_level_t {
-    FLANN_LOG_NONE = 0,
-    FLANN_LOG_FATAL = 1,
-    FLANN_LOG_ERROR = 2,
-    FLANN_LOG_WARN = 3,
-    FLANN_LOG_INFO = 4
+enum flann_log_level_t
+{
+	FLANN_LOG_NONE = 0,
+	FLANN_LOG_FATAL = 1,
+	FLANN_LOG_ERROR = 2,
+	FLANN_LOG_WARN = 3,
+	FLANN_LOG_INFO = 4,
+	FLANN_LOG_DEBUG = 5
 };
 \end{Verbatim}
 \end{description}
 
 
 \subsubsection{flann\_find\_nearest\_neighbors\_index()}
 \begin{Verbatim}[fontsize=\footnotesize,frame=single]
-int flann_find_nearest_neighbors_index(FLANN_INDEX index_id,
+int flann_find_nearest_neighbors_index(flann_index_t index_id,
 	float* testset,
 	int trows,
 	int* indices,
@@ -1023,15 +1049,13 @@ \subsubsection{flann\_find\_nearest\_neighbors()}
 \subsubsection{flann\_radius\_search()}
 
 \begin{Verbatim}[fontsize=\footnotesize,frame=single]
-int flann_radius_search(FLANN_INDEX index_ptr,
-	float* query,   /* query point */
-	int* indices, /* array for storing the indices */
+int flann_radius_search(flann_index_t 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);
+	struct FLANNParameters* flann_params);
 \end{Verbatim}
 
 This function performs a radius search to single query point. The indices of the neighbors found and
@@ -1061,7 +1085,7 @@ \subsubsection{flann\_load\_index()}
 
 \subsubsection{flann\_free\_index()}
 \begin{Verbatim}[fontsize=\footnotesize,frame=single]
-int flann_free_index(FLANN_INDEX index_id,
+int flann_free_index(flann_index_t index_id,
 	struct FLANNParameters* flann_params);
 \end{Verbatim}
 This function deletes a previously constructed index and frees all the memory
@@ -1077,14 +1101,22 @@ \subsubsection{flann\_set\_distance\_type}
 \begin{description}
 \item[distance\_type] The distance type to use. Possible values are
 \begin{Verbatim}[fontsize=\footnotesize]
-enum flann_distance_t {
-	FLANN_DIST_EUCLIDEAN = 1,  // squared euclidean distance
+enum flann_distance_t
+{
+	FLANN_DIST_EUCLIDEAN = 1,
+	FLANN_DIST_L2 = 1,
 	FLANN_DIST_MANHATTAN = 2,
+	FLANN_DIST_L1 = 2,
 	FLANN_DIST_MINKOWSKI = 3,
-	FLANN_DIST_HIST_INTERSECT  = 5,
-	FlANN_DIST_HELLINGER = 6,
-	FLANN_DIST_CHI_SQUARE  = 7,   // chi-square
-	FLANN_DIST_KULLBACK_LEIBLER  = 8,   // kullback-leibler divergence
+	FLANN_DIST_MAX = 4,
+	FLANN_DIST_HIST_INTERSECT = 5,
+	FLANN_DIST_HELLINGER = 6,
+	FLANN_DIST_CHI_SQUARE = 7,
+	FLANN_DIST_KULLBACK_LEIBLER = 8,
+	FLANN_DIST_HAMMING = 9,
+	FLANN_DIST_HAMMING_LUT = 10,
+	FLANN_DIST_HAMMING_POPCNT = 11,
+	FLANN_DIST_L2_SIMPLE = 12,
 };
 \end{Verbatim}
 \item[order] Used in for the \texttt{FLANN\_DIST\_MINKOWSKI} distance type, to choose the order of the Minkowski distance.

doc/manual.tex

@@ -88,6 +88,10 @@ if (BUILD_C_BINDINGS)
         target_link_libraries(flann -Wl,-whole-archive flann_s -Wl,-no-whole-archive)
     else()
         add_library(flann SHARED ${C_SOURCES})
+
+        if(MINGW)
+          target_link_libraries(flann -lgomp)
+        endif(MINGW)
     endif()
 
     set_target_properties(flann PROPERTIES