1 /** @file sift.h
2 ** @brief SIFT (@ref sift)
3 ** @author Andrea Vedaldi
4 **/
5
6 /*
7 Copyright (C) 2007-12 Andrea Vedaldi and Brian Fulkerson.
8 All rights reserved.
9
10 This file is part of the VLFeat library and is made available under
11 the terms of the BSD license (see the COPYING file).
12 */
13
14 #ifndef VL_SIFT_H
15 #define VL_SIFT_H
16
17 #include <stdio.h>
18 #include "generic.h"
19
20 /** @brief SIFT filter pixel type */
21 typedef float vl_sift_pix ;
22
23 /** ------------------------------------------------------------------
24 ** @brief SIFT filter keypoint
25 **
26 ** This structure represent a keypoint as extracted by the SIFT
27 ** filter ::VlSiftFilt.
28 **/
29
30 typedef struct _VlSiftKeypoint
31 {
32 int o ; /**< o coordinate (octave). */
33
34 int ix ; /**< Integer unnormalized x coordinate. */
35 int iy ; /**< Integer unnormalized y coordinate. */
36 int is ; /**< Integer s coordinate. */
37
38 float x ; /**< x coordinate. */
39 float y ; /**< y coordinate. */
40 float s ; /**< s coordinate. */
41 float sigma ; /**< scale. */
42 } VlSiftKeypoint ;
43
44 /** ------------------------------------------------------------------
45 ** @brief SIFT filter
46 **
47 ** This filter implements the SIFT detector and descriptor.
48 **/
49
50 #define EXPN_SZ 256 /**< ::fast_expn table size @internal */
51
52 typedef struct _VlSiftFilt
53 {
54 double sigman ; /**< nominal image smoothing. */
55 double sigma0 ; /**< smoothing of pyramid base. */
56 double sigmak ; /**< k-smoothing */
57 double dsigma0 ; /**< delta-smoothing. */
58
59 int width ; /**< image width. */
60 int height ; /**< image height. */
61 int O ; /**< number of octaves. */
62 int S ; /**< number of levels per octave. */
63 int o_min ; /**< minimum octave index. */
64 int s_min ; /**< minimum level index. */
65 int s_max ; /**< maximum level index. */
66 int o_cur ; /**< current octave. */
67
68 vl_sift_pix *temp ; /**< temporary pixel buffer. */
69 vl_sift_pix *octave ; /**< current GSS data. */
70 vl_sift_pix *dog ; /**< current DoG data. */
71 int octave_width ; /**< current octave width. */
72 int octave_height ; /**< current octave height. */
73
74 vl_sift_pix *gaussFilter ; /**< current Gaussian filter */
75 double gaussFilterSigma ; /**< current Gaussian filter std */
76 vl_size gaussFilterWidth ; /**< current Gaussian filter width */
77
78 VlSiftKeypoint* keys ;/**< detected keypoints. */
79 int nkeys ; /**< number of detected keypoints. */
80 int keys_res ; /**< size of the keys buffer. */
81
82 double peak_thresh ; /**< peak threshold. */
83 double edge_thresh ; /**< edge threshold. */
84 double norm_thresh ; /**< norm threshold. */
85 double magnif ; /**< magnification factor. */
86 double windowSize ; /**< size of Gaussian window (in spatial bins) */
87
88 vl_sift_pix *grad ; /**< GSS gradient data. */
89 int grad_o ; /**< GSS gradient data octave. */
90
91 double expn_tab [EXPN_SZ+1] ; /**< ::fast_expn table @internal */
92
93 } VlSiftFilt ;
94
95 /** @name Create and destroy
96 ** @{
97 **/
98 VL_EXPORT
99 VlSiftFilt* vl_sift_new (int width, int height,
100 int noctaves, int nlevels,
101 int o_min) ;
102 VL_EXPORT
103 void vl_sift_delete (VlSiftFilt *f) ;
104 /** @} */
105
106 /** @name Process data
107 ** @{
108 **/
109
110 VL_EXPORT
111 int vl_sift_process_first_octave (VlSiftFilt *f,
112 vl_sift_pix const *im) ;
113
114 VL_EXPORT
115 int vl_sift_process_next_octave (VlSiftFilt *f) ;
116
117 VL_EXPORT
118 void vl_sift_detect (VlSiftFilt *f) ;
119
120 VL_EXPORT
121 int vl_sift_calc_keypoint_orientations (VlSiftFilt *f,
122 double angles [4],
123 VlSiftKeypoint const*k);
124 VL_EXPORT
125 void vl_sift_calc_keypoint_descriptor (VlSiftFilt *f,
126 vl_sift_pix *descr,
127 VlSiftKeypoint const* k,
128 double angle) ;
129
130 VL_EXPORT
131 void vl_sift_calc_raw_descriptor (VlSiftFilt const *f,
132 vl_sift_pix const* image,
133 vl_sift_pix *descr,
134 int widht, int height,
135 double x, double y,
136 double s, double angle0) ;
137
138 VL_EXPORT
139 void vl_sift_keypoint_init (VlSiftFilt const *f,
140 VlSiftKeypoint *k,
141 double x,
142 double y,
143 double sigma) ;
144
145 VL_EXPORT
146 void vl_sift_update_gradient (VlSiftFilt *f);
147
148 /** @} */
149
150 /** @name Retrieve data and parameters
151 ** @{
152 **/
153 VL_INLINE int vl_sift_get_octave_index (VlSiftFilt const *f) ;
154 VL_INLINE int vl_sift_get_noctaves (VlSiftFilt const *f) ;
155 VL_INLINE int vl_sift_get_octave_first (VlSiftFilt const *f) ;
156 VL_INLINE int vl_sift_get_octave_width (VlSiftFilt const *f) ;
157 VL_INLINE int vl_sift_get_octave_height (VlSiftFilt const *f) ;
158 VL_INLINE int vl_sift_get_nlevels (VlSiftFilt const *f) ;
159 VL_INLINE int vl_sift_get_nkeypoints (VlSiftFilt const *f) ;
160 VL_INLINE double vl_sift_get_peak_thresh (VlSiftFilt const *f) ;
161 VL_INLINE double vl_sift_get_edge_thresh (VlSiftFilt const *f) ;
162 VL_INLINE double vl_sift_get_norm_thresh (VlSiftFilt const *f) ;
163 VL_INLINE double vl_sift_get_magnif (VlSiftFilt const *f) ;
164 VL_INLINE double vl_sift_get_window_size (VlSiftFilt const *f) ;
165
166 VL_INLINE vl_sift_pix *vl_sift_get_octave (VlSiftFilt const *f, int s) ;
167 VL_INLINE VlSiftKeypoint const *vl_sift_get_keypoints (VlSiftFilt const *f) ;
168 /** @} */
169
170 /** @name Set parameters
171 ** @{
172 **/
173 VL_INLINE void vl_sift_set_peak_thresh (VlSiftFilt *f, double t) ;
174 VL_INLINE void vl_sift_set_edge_thresh (VlSiftFilt *f, double t) ;
175 VL_INLINE void vl_sift_set_norm_thresh (VlSiftFilt *f, double t) ;
176 VL_INLINE void vl_sift_set_magnif (VlSiftFilt *f, double m) ;
177 VL_INLINE void vl_sift_set_window_size (VlSiftFilt *f, double m) ;
178 /** @} */
179
180 /* -------------------------------------------------------------------
181 * Inline functions implementation
182 * ---------------------------------------------------------------- */
183
184 /** ------------------------------------------------------------------
185 ** @brief Get current octave index.
186 ** @param f SIFT filter.
187 ** @return index of the current octave.
188 **/
189
190 VL_INLINE int
vl_sift_get_octave_index(VlSiftFilt const * f)191 vl_sift_get_octave_index (VlSiftFilt const *f)
192 {
193 return f-> o_cur ;
194 }
195
196 /** ------------------------------------------------------------------
197 ** @brief Get number of octaves.
198 ** @param f SIFT filter.
199 ** @return number of octaves.
200 **/
201
202 VL_INLINE int
vl_sift_get_noctaves(VlSiftFilt const * f)203 vl_sift_get_noctaves (VlSiftFilt const *f)
204 {
205 return f-> O ;
206 }
207
208 /**-------------------------------------------------------------------
209 ** @brief Get first octave.
210 ** @param f SIFT filter.
211 ** @return index of the first octave.
212 **/
213
214 VL_INLINE int
vl_sift_get_octave_first(VlSiftFilt const * f)215 vl_sift_get_octave_first (VlSiftFilt const *f)
216 {
217 return f-> o_min ;
218 }
219
220 /** ------------------------------------------------------------------
221 ** @brief Get current octave width
222 ** @param f SIFT filter.
223 ** @return current octave width.
224 **/
225
226 VL_INLINE int
vl_sift_get_octave_width(VlSiftFilt const * f)227 vl_sift_get_octave_width (VlSiftFilt const *f)
228 {
229 return f-> octave_width ;
230 }
231
232 /** ------------------------------------------------------------------
233 ** @brief Get current octave height
234 ** @param f SIFT filter.
235 ** @return current octave height.
236 **/
237
238 VL_INLINE int
vl_sift_get_octave_height(VlSiftFilt const * f)239 vl_sift_get_octave_height (VlSiftFilt const *f)
240 {
241 return f-> octave_height ;
242 }
243
244 /** ------------------------------------------------------------------
245 ** @brief Get current octave data
246 ** @param f SIFT filter.
247 ** @param s level index.
248 **
249 ** The level index @a s ranges in the interval <tt>s_min = -1</tt>
250 ** and <tt> s_max = S + 2</tt>, where @c S is the number of levels
251 ** per octave.
252 **
253 ** @return pointer to the octave data for level @a s.
254 **/
255
256 VL_INLINE vl_sift_pix *
vl_sift_get_octave(VlSiftFilt const * f,int s)257 vl_sift_get_octave (VlSiftFilt const *f, int s)
258 {
259 int w = vl_sift_get_octave_width (f) ;
260 int h = vl_sift_get_octave_height (f) ;
261 return f->octave + w * h * (s - f->s_min) ;
262 }
263
264 /** ------------------------------------------------------------------
265 ** @brief Get number of levels per octave
266 ** @param f SIFT filter.
267 ** @return number of leves per octave.
268 **/
269
270 VL_INLINE int
vl_sift_get_nlevels(VlSiftFilt const * f)271 vl_sift_get_nlevels (VlSiftFilt const *f)
272 {
273 return f-> S ;
274 }
275
276 /** ------------------------------------------------------------------
277 ** @brief Get number of keypoints.
278 ** @param f SIFT filter.
279 ** @return number of keypoints.
280 **/
281
282 VL_INLINE int
vl_sift_get_nkeypoints(VlSiftFilt const * f)283 vl_sift_get_nkeypoints (VlSiftFilt const *f)
284 {
285 return f-> nkeys ;
286 }
287
288 /** ------------------------------------------------------------------
289 ** @brief Get keypoints.
290 ** @param f SIFT filter.
291 ** @return pointer to the keypoints list.
292 **/
293
294 VL_INLINE VlSiftKeypoint const *
vl_sift_get_keypoints(VlSiftFilt const * f)295 vl_sift_get_keypoints (VlSiftFilt const *f)
296 {
297 return f-> keys ;
298 }
299
300 /** ------------------------------------------------------------------
301 ** @brief Get peaks treashold
302 ** @param f SIFT filter.
303 ** @return threshold ;
304 **/
305
306 VL_INLINE double
vl_sift_get_peak_thresh(VlSiftFilt const * f)307 vl_sift_get_peak_thresh (VlSiftFilt const *f)
308 {
309 return f -> peak_thresh ;
310 }
311
312 /** ------------------------------------------------------------------
313 ** @brief Get edges threshold
314 ** @param f SIFT filter.
315 ** @return threshold.
316 **/
317
318 VL_INLINE double
vl_sift_get_edge_thresh(VlSiftFilt const * f)319 vl_sift_get_edge_thresh (VlSiftFilt const *f)
320 {
321 return f -> edge_thresh ;
322 }
323
324 /** ------------------------------------------------------------------
325 ** @brief Get norm threshold
326 ** @param f SIFT filter.
327 ** @return threshold.
328 **/
329
330 VL_INLINE double
vl_sift_get_norm_thresh(VlSiftFilt const * f)331 vl_sift_get_norm_thresh (VlSiftFilt const *f)
332 {
333 return f -> norm_thresh ;
334 }
335
336 /** ------------------------------------------------------------------
337 ** @brief Get the magnification factor
338 ** @param f SIFT filter.
339 ** @return magnification factor.
340 **/
341
342 VL_INLINE double
vl_sift_get_magnif(VlSiftFilt const * f)343 vl_sift_get_magnif (VlSiftFilt const *f)
344 {
345 return f -> magnif ;
346 }
347
348 /** ------------------------------------------------------------------
349 ** @brief Get the Gaussian window size.
350 ** @param f SIFT filter.
351 ** @return standard deviation of the Gaussian window (in spatial bin units).
352 **/
353
354 VL_INLINE double
vl_sift_get_window_size(VlSiftFilt const * f)355 vl_sift_get_window_size (VlSiftFilt const *f)
356 {
357 return f -> windowSize ;
358 }
359
360
361
362 /** ------------------------------------------------------------------
363 ** @brief Set peaks threshold
364 ** @param f SIFT filter.
365 ** @param t threshold.
366 **/
367
368 VL_INLINE void
vl_sift_set_peak_thresh(VlSiftFilt * f,double t)369 vl_sift_set_peak_thresh (VlSiftFilt *f, double t)
370 {
371 f -> peak_thresh = t ;
372 }
373
374 /** ------------------------------------------------------------------
375 ** @brief Set edges threshold
376 ** @param f SIFT filter.
377 ** @param t threshold.
378 **/
379
380 VL_INLINE void
vl_sift_set_edge_thresh(VlSiftFilt * f,double t)381 vl_sift_set_edge_thresh (VlSiftFilt *f, double t)
382 {
383 f -> edge_thresh = t ;
384 }
385
386 /** ------------------------------------------------------------------
387 ** @brief Set norm threshold
388 ** @param f SIFT filter.
389 ** @param t threshold.
390 **/
391
392 VL_INLINE void
vl_sift_set_norm_thresh(VlSiftFilt * f,double t)393 vl_sift_set_norm_thresh (VlSiftFilt *f, double t)
394 {
395 f -> norm_thresh = t ;
396 }
397
398 /** ------------------------------------------------------------------
399 ** @brief Set the magnification factor
400 ** @param f SIFT filter.
401 ** @param m magnification factor.
402 **/
403
404 VL_INLINE void
vl_sift_set_magnif(VlSiftFilt * f,double m)405 vl_sift_set_magnif (VlSiftFilt *f, double m)
406 {
407 f -> magnif = m ;
408 }
409
410 /** ------------------------------------------------------------------
411 ** @brief Set the Gaussian window size
412 ** @param f SIFT filter.
413 ** @param x Gaussian window size (in units of spatial bin).
414 **
415 ** This is the parameter @f$ \hat \sigma_{\text{win}} @f$ of
416 ** the standard SIFT descriptor @ref sift-tech-descriptor-std.
417 **/
418
419 VL_INLINE void
vl_sift_set_window_size(VlSiftFilt * f,double x)420 vl_sift_set_window_size (VlSiftFilt *f, double x)
421 {
422 f -> windowSize = x ;
423 }
424
425 /* VL_SIFT_H */
426 #endif
427