1 /** @file covdet.h
2 ** @brief Covariant feature detectors (@ref covdet)
3 ** @author Karel Lenc
4 ** @author Andrea Vedaldi
5 ** @author Michal Perdoch
6 **/
7
8 /*
9 Copyright (C) 2013-14 Andrea Vedaldi.
10 Copyright (C) 2012 Karel Lenc, Andrea Vedaldi and Michal Perdoch.
11 All rights reserved.
12
13 This file is part of the VLFeat library and is made available under
14 the terms of the BSD license (see the COPYING file).
15 */
16
17 #ifndef VL_COVDET_H
18 #define VL_COVDET_H
19
20 #include "generic.h"
21 #include "stringop.h"
22 #include "scalespace.h"
23
24 #include <stdio.h>
25
26 /* ---------------------------------------------------------------- */
27 /* Feature Frames */
28 /* ---------------------------------------------------------------- */
29
30 /** @name Feature frames
31 ** @{ */
32
33 /** @brief Types of feature frames */
34 typedef enum _VlFrameType {
35 VL_FRAMETYPE_DISC = 1, /**< A disc. */
36 VL_FRAMETYPE_ORIENTED_DISC, /**< An oriented disc. */
37 VL_FRAMETYPE_ELLIPSE, /**< An ellipse. */
38 VL_FRAMETYPE_ORIENTED_ELLIPSE, /**< An oriented ellipse. */
39 VL_FRAMETYPE_NUM
40 } VlFrameType ;
41
42 /** @brief Names of the frame types */
43 VL_EXPORT const char* vlFrameNames [VL_FRAMETYPE_NUM] ;
44
45 /** @brief Mapping between string values and VlFrameType values */
46 VL_EXPORT VlEnumerator vlFrameTypes [VL_FRAMETYPE_NUM] ;
47
48 /** @brief Disc feature frame */
49 typedef struct _VlFrameDisc
50 {
51 float x ; /**< center x-coordinate */
52 float y ; /**< center y-coordinate */
53 float sigma ; /**< radius or scale */
54 } VlFrameDisc ;
55
56 /** @brief Oriented disc feature frame
57 ** An upright frame has @c angle equal to zero.
58 **/
59 typedef struct _VlFrameOrientedDisc {
60 float x ; /**< center x-coordinate */
61 float y ; /**< center y-coordinate */
62 float sigma ; /**< radius or scale */
63 float angle ; /**< rotation angle (rad) */
64 } VlFrameOrientedDisc ;
65
66 /** @brief Ellipse feature frame */
67 typedef struct _VlFrameEllipse {
68 float x ; /**< center x-coordinate */
69 float y ; /**< center y-coordinate */
70 float e11 ; /**< */
71 float e12 ;
72 float e22 ;
73 } VlFrameEllipse ;
74
75 /** @brief Oriented ellipse feature frame
76 ** The affine transformation transforms the ellipse shape into
77 ** a circular region. */
78 typedef struct _VlFrameOrientedEllipse {
79 float x ; /**< center x-coordinate */
80 float y ; /**< center y-coordinate */
81 float a11 ; /**< */
82 float a12 ;
83 float a21 ;
84 float a22 ;
85 } VlFrameOrientedEllipse;
86
87 /** @brief Get the size of a frame structure
88 ** @param frameType identifier of the type of frame.
89 ** @return size of the corresponding frame structure in bytes.
90 **/
91 VL_INLINE vl_size
vl_get_frame_size(VlFrameType frameType)92 vl_get_frame_size (VlFrameType frameType) {
93 switch (frameType) {
94 case VL_FRAMETYPE_DISC: return sizeof(VlFrameDisc);
95 case VL_FRAMETYPE_ORIENTED_DISC: return sizeof(VlFrameOrientedDisc);
96 case VL_FRAMETYPE_ELLIPSE: return sizeof(VlFrameEllipse);
97 case VL_FRAMETYPE_ORIENTED_ELLIPSE: return sizeof(VlFrameOrientedEllipse);
98 default:
99 assert(0);
100 break;
101 }
102 return 0;
103 }
104
105 /** @brief Get the size of a frame structure
106 ** @param affineAdaptation whether the detector use affine adaptation.
107 ** @param orientation whether the detector estimates the feature orientation.
108 ** @return the type of extracted frame.
109 **
110 ** Depedning on whether the detector estimate the affine shape
111 ** and orientation of a feature, different frame types
112 ** are extracted. */
113
114 VL_INLINE VlFrameType
vl_get_frame_type(vl_bool affineAdaptation,vl_bool orientation)115 vl_get_frame_type (vl_bool affineAdaptation, vl_bool orientation)
116 {
117 if (affineAdaptation) {
118 if (orientation) {
119 return VL_FRAMETYPE_ORIENTED_ELLIPSE;
120 } else {
121 return VL_FRAMETYPE_ELLIPSE;
122 }
123 } else {
124 if (orientation) {
125 return VL_FRAMETYPE_ORIENTED_DISC;
126 } else {
127 return VL_FRAMETYPE_DISC;
128 }
129 }
130 }
131
132 /* ---------------------------------------------------------------- */
133 /* Covariant Feature Detector */
134 /* ---------------------------------------------------------------- */
135
136 /** @brief A detected feature shape and location */
137 typedef struct _VlCovDetFeature
138 {
139 VlFrameOrientedEllipse frame ; /**< feature frame. */
140 int o ; /**< Detected octave. */
141 int s ; /**< Octave subdivision. */
142 float peakScore ; /**< peak score. */
143 float edgeScore ; /**< edge score. */
144 float orientationScore ; /**< orientation score. */
145 float laplacianScaleScore ; /**< Laplacian scale score. */
146 } VlCovDetFeature ;
147
148 /** @brief A detected feature orientation */
149 typedef struct _VlCovDetFeatureOrientation
150 {
151 double angle ;
152 double score ;
153 } VlCovDetFeatureOrientation ;
154
155 /** @brief A detected feature Laplacian scale */
156 typedef struct _VlCovDetFeatureLaplacianScale
157 {
158 double scale ;
159 double score ;
160 } VlCovDetFeatureLaplacianScale ;
161
162 /** @brief Covariant feature detection method */
163 typedef enum _VlCovDetMethod
164 {
165 VL_COVDET_METHOD_DOG = 1,
166 VL_COVDET_METHOD_HESSIAN,
167 VL_COVDET_METHOD_HESSIAN_LAPLACE,
168 VL_COVDET_METHOD_HARRIS_LAPLACE,
169 VL_COVDET_METHOD_MULTISCALE_HESSIAN,
170 VL_COVDET_METHOD_MULTISCALE_HARRIS,
171 VL_COVDET_METHOD_NUM
172 } VlCovDetMethod;
173
174 /** @brief Mapping between strings and ::VlCovDetMethod values */
175 VL_EXPORT VlEnumerator vlCovdetMethods [VL_COVDET_METHOD_NUM] ;
176
177 #ifdef __DOXYGEN__
178 /** @brief Covariant feature detector
179 ** @see @ref covdet */
180 struct _VlCovDet { }
181 #endif
182
183 /** @brief Covariant feature detector
184 ** @see @ref covdet */
185 typedef struct _VlCovDet VlCovDet ;
186
187 /** @name Create and destroy
188 ** @{ */
189 VL_EXPORT VlCovDet * vl_covdet_new (VlCovDetMethod method) ;
190 VL_EXPORT void vl_covdet_delete (VlCovDet * self) ;
191 VL_EXPORT void vl_covdet_reset (VlCovDet * self) ;
192 /** @} */
193
194 /** @name Process data
195 ** @{ */
196 VL_EXPORT int vl_covdet_put_image (VlCovDet * self,
197 float const * image,
198 vl_size width, vl_size height) ;
199
200 VL_EXPORT void vl_covdet_detect (VlCovDet * self, vl_size max_num_features) ;
201 VL_EXPORT int vl_covdet_append_feature (VlCovDet * self, VlCovDetFeature const * feature) ;
202 VL_EXPORT void vl_covdet_extract_orientations (VlCovDet * self) ;
203 VL_EXPORT void vl_covdet_extract_laplacian_scales (VlCovDet * self) ;
204 VL_EXPORT void vl_covdet_extract_affine_shape (VlCovDet * self) ;
205
206 VL_EXPORT VlCovDetFeatureOrientation *
207 vl_covdet_extract_orientations_for_frame (VlCovDet * self,
208 vl_size *numOrientations,
209 VlFrameOrientedEllipse frame) ;
210
211 VL_EXPORT VlCovDetFeatureLaplacianScale *
212 vl_covdet_extract_laplacian_scales_for_frame (VlCovDet * self,
213 vl_size * numScales,
214 VlFrameOrientedEllipse frame) ;
215 VL_EXPORT int
216 vl_covdet_extract_affine_shape_for_frame (VlCovDet * self,
217 VlFrameOrientedEllipse * adapted,
218 VlFrameOrientedEllipse frame) ;
219
220 VL_EXPORT vl_bool
221 vl_covdet_extract_patch_for_frame (VlCovDet * self, float * patch,
222 vl_size resolution,
223 double extent,
224 double sigma,
225 VlFrameOrientedEllipse frame) ;
226
227 VL_EXPORT void
228 vl_covdet_drop_features_outside (VlCovDet * self, double margin) ;
229 /** @} */
230
231 /** @name Retrieve data and parameters
232 ** @{ */
233 VL_EXPORT vl_size vl_covdet_get_num_features (VlCovDet const * self) ;
234 VL_EXPORT VlCovDetFeature * vl_covdet_get_features (VlCovDet * self) ;
235 VL_EXPORT vl_index vl_covdet_get_first_octave (VlCovDet const * self) ;
236 VL_EXPORT vl_size vl_covdet_get_octave_resolution (VlCovDet const * self) ;
237 VL_EXPORT double vl_covdet_get_peak_threshold (VlCovDet const * self) ;
238 VL_EXPORT double vl_covdet_get_edge_threshold (VlCovDet const * self) ;
239 VL_EXPORT double vl_covdeg_get_laplacian_peak_threshold (VlCovDet const * self) ;
240 VL_EXPORT vl_bool vl_covdet_get_transposed (VlCovDet const * self) ;
241 VL_EXPORT VlScaleSpace * vl_covdet_get_gss (VlCovDet const * self) ;
242 VL_EXPORT VlScaleSpace * vl_covdet_get_css (VlCovDet const * self) ;
243 VL_EXPORT vl_bool vl_covdet_get_aa_accurate_smoothing (VlCovDet const * self) ;
244 VL_EXPORT vl_size const * vl_covdet_get_laplacian_scales_statistics (VlCovDet const * self, vl_size * numScales) ;
245 VL_EXPORT double vl_covdet_get_non_extrema_suppression_threshold (VlCovDet const * self) ;
246 VL_EXPORT vl_size vl_covdet_get_num_non_extrema_suppressed (VlCovDet const * self) ;
247
248 /** @} */
249
250 /** @name Set parameters
251 ** @{ */
252 VL_EXPORT void vl_covdet_set_first_octave (VlCovDet * self, vl_index o) ;
253 VL_EXPORT void vl_covdet_set_octave_resolution (VlCovDet * self, vl_size r) ;
254 VL_EXPORT void vl_covdet_set_peak_threshold (VlCovDet * self, double peakThreshold) ;
255 VL_EXPORT void vl_covdet_set_edge_threshold (VlCovDet * self, double edgeThreshold) ;
256 VL_EXPORT void vl_covdet_set_laplacian_peak_threshold (VlCovDet * self, double peakThreshold) ;
257 VL_EXPORT void vl_covdet_set_transposed (VlCovDet * self, vl_bool t) ;
258 VL_EXPORT void vl_covdet_set_aa_accurate_smoothing (VlCovDet * self, vl_bool x) ;
259 VL_EXPORT void vl_covdet_set_non_extrema_suppression_threshold (VlCovDet * self, double x) ;
260 /** @} */
261
262 /* VL_COVDET_H */
263 #endif
264