Efficient Large-scale Image Search With a Vocabulary Tree
=========================================================
This is the source code used in the IPOL article:
http://www.ipol.im/pub/art/2018/199/

version number: 1.1.1
release date: apr.25.2018

Description
===========
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 <root> its directory structure is:
 <root>/vocabulary: the path where files used to build the vocabulary are placed (required)
 <root>/input: the path where files to be indexed are placed (required)
 <root>/data: the path where internal database data files are stored
 <root>/queries: a the path where to place files to be queried (might be empty)
 <root>/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 <http://opencv.org/>. 
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 <euriza@dc.uba.ar>
Francisco Gómez-Fernández <fgomez@dc.uba.ar>
Martin Rais <mrais@cmla.ens-cachan.fr>


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 <http://www.gnu.org/licenses/>.


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 <http://opencv.org/>.
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: opencv/opencv#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 <option> <params>

	if <option> == '-build': build a new database
	if <option> == '-start': starts server
	if <option> == '-stop': stops server
	if <option> == '-update': updates database
		params := <database path>

	if <option> == '-query': does a query
		params := <database path> <file to query>


Running the demo
================

CREATING A NEW DATABASE:
 a) create a new directory for example "/home/mydb", 
 b) create a new vocabulary directory "/home/mydb/vocabulary"
 c) copy all files you want to use to train vocabulary into the vocabulary directory (files can be images or videos).
 d) create a new directory input for files to be indexed "/home/mydb/input"
 e) copy all files you want to index to input directory (the files can be images or videos).
 f) create a text file "/home/mydb/config.txt"
 g) edit config.txt to specify the port where the database will be listening
 contents of config.txt :
	# settings for database
	port=64003
	
 we are now ready to build the database, execute the command 
 $ ./vt -build /home/mydb

 ... this could take some time depending on the number of images ...
 ... and if we don't get any error, we have built ok the database.


STARTING DATABASE:
 to start the database simply run the command:
 $ vt -start /home/mydb

STOPPING DATABASE:
 to start the database simply run the command:
 $ vt -stop /home/mydb

PERFORMING A QUERY:
 must specify the database and the query image file, for example:
 $ vt -query /home/mydb /home/images/img1.png

UPDATE INDEX:
 to re-index all the files under /home/mydb/input run the command:
 $ vt -update /home/mydb


Source files
============

List of source files provided:

Catalog.cpp        ExtKmeans.h            KeyPointPersistor.h  Server.cpp
Catalog.h          FeatureMethod.cpp      KMeans.cpp           Server.h
CMakeLists.txt     FeatureMethod.h        KMeans.h             ShootSegmenter.cpp
Configuration.cpp  FileHelper.cpp         main.cpp             ShootSegmenter.h
Configuration.h    FileHelper.h           Matching.cpp         VecPersistor.hpp
Database.cpp       FileManager.cpp        Matching.h           VocTree.cpp
Database.h         FileManager.h          MatPersistor.cpp     VocTree.h
ExtKmeans.cpp      KeyPointPersistor.cpp  MatPersistor.h


Changes in the software since it was first published
====================================================
none.

List of known defects
=====================
none.

Credits and acknowledgments
===========================
none.