-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathREADME.txt
234 lines (177 loc) · 8.49 KB
/
README.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
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 <[email protected]>
Francisco Gómez-Fernández <[email protected]>
Martin Rais <[email protected]>
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: 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 <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.