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