This program is a full C++ implementation of the paper "Scalable Recognition with a Vocabulary Tree" by David Nistér and Henrik Stewénius. Open source code is provided, with a functional demo.
If the -build option is used, the demo will generate a "database" with the vocabulary tree and indexed images to be queried. It works like a database engine with a client-server model and accepts concurrent incoming queries.
When no query is received for a while, the demo stops itself and the memory is released.
A database is identified by its path on the file system. Let's call that path the database root.
Given a database root path its directory structure is:
/vocabulary: the path where files used to build the vocabulary are placed (required)
/input: the path where files to be indexed are placed (required)
/data: the path where internal database data files are stored
/queries: a the path where to place files to be queried (might be empty)
/results: the path where the database will write output results
The vocabulary will be created from the files on the vocabulary directory, and then images on input directory will be indexed. Make sure to fill those directories before running -build option.
This demo makes use of the well known OpenCV Library .
The following basic functionalities provided from OpenCV were used:
- core matrix support and arithmetic matrix operations
- standard k-means
- keypoint detection and descriptor extractor (SIFT, SURF, ORB, KAZE, etc)
- image and video manipulation
Authors and contact information
===============================
Esteban Uriza
Francisco Gómez-Fernández
Martin Rais
Citing this article
===================
If you use this code in your publication, plase cite our work:
@article{ipol.2018.199,
title = {Efficient Large-scale Image Search with a Vocabulary Tree},
author = {Uriza, Esteban and G{\'o}mez-Fern{\'a}ndez, Francisco and Rais, Mart{\'i}n},
journal = {Image Processing On Line},
volume = {8},
pages = {7--98},
year = {2018},
doi = {10.5201/ipol.2018.199},
}
% if your bibliography style doesn't support doi fields:
note = {\url{https://doi.org/10.5201/ipol.2018.199}}
License
=======
This program is free software: you can use, modify and/or
redistribute it under the terms of the GNU General Public
License as published by the Free Software Foundation, either
version 3 of the License, or (at your option) any later
version. You should have received a copy of this license along
this program. If not, see .
Patent warning
==============
This source code uses algorithms possibly linked to the following patents:
- D.G. Lowe. Method and apparatus for identifying scale invariant features in an image and use
of same for locating an object in an image, March 23 2004. US Patent 6,711,293
- R. Funayama, H. Yanagihara, L. Van Gool, T. Tuytelaars, and H. Bay. Robust interest point
detector and descriptor, September 24 2009. US Patent App. 12/298,879.
This code is made available for the exclusive aim of serving as
scientific tool to verify the soundness and completeness of the
algorithm description. Compilation, execution and redistribution
of this file may violate patents rights in certain countries.
The situation being different for every country and changing
over time, it is your responsibility to determine which patent
rights restrictions apply to you before you compile, use,
modify, or redistribute this file. A patent lawyer is qualified
to make this determination.
If and only if they don't conflict with any patent terms, you
can benefit from the following license terms attached to this
source code.
Tools and libraries needed to compile and use the program
=========================================================
In order to compile, it requires to install OpenCV 3.1.0 wich can be downloaded from the official OpenCV web site .
It is also required to compile the contrib module.
Installing OpenCV
-----------------
The standard way to install OpenCV is to install it in the /usr/local directory, but in this way can't coexist different versions of OpenCV in the same machine. Thus, the way recommend to install OpenCV is to install it in your home directory.
The following terminal commands shows the installation process:
$ mkdir ~/opencv
$ mkdir ~/opencv/installed
$ mkdir ~/opencv/installed/3.1.0
$ cd ~/opencv
$ git clone --branch 3.1.0 --depth 1 https://github.com/opencv/opencv.git ./opencv3.1.0
$ cd opencv3.1.0
$ git clone --branch 3.1.0 --depth 1 https://github.com/opencv/opencv_contrib.git ./contrib
$ mkdir release
$ cd release
$ cmake -D OPENCV_EXTRA_MODULES_PATH=~/opencv/opencv3.1.0/contrib/modules -D CMAKE_INSTALL_PREFIX=~/opencv/installed/3.1.0 ..
$ make -j 8
$ make install
Required modules:
- opencv_core
- opencv_highgui
- opencv_imgproc
- opencv_imgcodecs
- opencv_features2d
- opencv_xfeatures2d
- opencv_video
- opencv_videoio
- opencv_flann
- opencv_calib3d
Build error for python bindings with opencv_contrib modules
-----------------------------------------------------------
There is an issue when compiling contrib modules with python support in some systems.
Check this link for a workaround: https://github.com/opencv/opencv/issues/6016
Otherwise, simply add this flag to cmake command: -D BUILD_opencv_python2=OFF
Compiling voctree
-----------------
Unzip the source code into a workspace directory, and compile it with make command.
Also, CMakeLists.txt based project is provided.
$ tar -xvf voctree_1.1.1.tar.gz
$ cd voctree_1.1.1
$ make
Exporting library path
----------------------
You will need to export the path to the OpenCV libraries.
$ export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:~/opencv/installed/3.1.0/lib
Usage mode
------------
$ ./vt