1 /*
2  * Copyright (C) 2011 The Android Open Source Project
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  *      http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 
17 /*$Id: db_feature_matching.h,v 1.3 2011/06/17 14:03:30 mbansal Exp $*/
18 
19 #ifndef DB_FEATURE_MATCHING_H
20 #define DB_FEATURE_MATCHING_H
21 
22 /*****************************************************************
23 *    Lean and mean begins here                                   *
24 *****************************************************************/
25 /*!
26  * \defgroup FeatureMatching Feature Matching
27  */
28 #include "db_utilities.h"
29 #include "db_utilities_constants.h"
30 
31 DB_API void db_SignedSquareNormCorr21x21_PreAlign_u(short *patch,const unsigned char * const *f_img,int x_f,int y_f,float *sum,float *recip);
32 DB_API void db_SignedSquareNormCorr11x11_PreAlign_u(short *patch,const unsigned char * const *f_img,int x_f,int y_f,float *sum,float *recip);
33 float db_SignedSquareNormCorr21x21Aligned_Post_s(const short *f_patch,const short *g_patch,float fsum_gsum,float f_recip_g_recip);
34 float db_SignedSquareNormCorr11x11Aligned_Post_s(const short *f_patch,const short *g_patch,float fsum_gsum,float f_recip_g_recip);
35 
36 class db_PointInfo_f
37 {
38 public:
39     /*Coordinates of point*/
40     int x;
41     int y;
42     /*Id nr of point*/
43     int id;
44     /*Best match score*/
45     double s;
46     /*Best match candidate*/
47     db_PointInfo_f *pir;
48     /*Precomputed coefficients
49     of image patch*/
50     float sum;
51     float recip;
52     /*Pointer to patch layout*/
53     const float *patch;
54 };
55 
56 class db_Bucket_f
57 {
58 public:
59     db_PointInfo_f *ptr;
60     int nr;
61 };
62 
63 class db_PointInfo_u
64 {
65 public:
66     /*Coordinates of point*/
67     int x;
68     int y;
69     /*Id nr of point*/
70     int id;
71     /*Best match score*/
72     double s;
73     /*Best match candidate*/
74     db_PointInfo_u *pir;
75     /*Precomputed coefficients
76     of image patch*/
77     float sum;
78     float recip;
79     /*Pointer to patch layout*/
80     const short *patch;
81 };
82 
83 class db_Bucket_u
84 {
85 public:
86     db_PointInfo_u *ptr;
87     int nr;
88 };
89 /*!
90  * \class db_Matcher_f
91  * \ingroup FeatureMatching
92  * \brief Feature matcher for float images.
93  *
94  * Normalized correlation feature matcher for <b>float</b> images.
95  * Correlation window size is constant and set to 11x11.
96  * See \ref FeatureDetection to detect Harris corners.
97  * Images are managed with functions in \ref LMImageBasicUtilities.
98  */
99 class DB_API db_Matcher_f
100 {
101 public:
102     db_Matcher_f();
103     ~db_Matcher_f();
104 
105     /*!
106      * Set parameters and pre-allocate memory. Return an upper bound
107      * on the number of matches.
108      * \param im_width          width
109      * \param im_height         height
110      * \param max_disparity     maximum distance (as fraction of image size) between matches
111      * \param target_nr_corners maximum number of matches
112      * \return maximum number of matches
113      */
114     unsigned long Init(int im_width,int im_height,
115         double max_disparity=DB_DEFAULT_MAX_DISPARITY,
116         int target_nr_corners=DB_DEFAULT_TARGET_NR_CORNERS);
117 
118     /*!
119      * Match two sets of features.
120      * If the prewarp H is not NULL it will be applied to the features
121      * in the right image before matching.
122      * Parameters id_l and id_r must point to arrays of size target_nr_corners
123      * (returned by Init()).
124      * The results of matching are in id_l and id_r.
125      * Interpretaqtion of results: if id_l[i] = m and id_r[i] = n,
126      * feature at (x_l[m],y_l[m]) matched to (x_r[n],y_r[n]).
127      * \param l_img     left image
128      * \param r_img     right image
129      * \param x_l       left x coordinates of features
130      * \param y_l       left y coordinates of features
131      * \param nr_l      number of features in left image
132      * \param x_r       right x coordinates of features
133      * \param y_r       right y coordinates of features
134      * \param nr_r      number of features in right image
135      * \param id_l      indices of left features that matched
136      * \param id_r      indices of right features that matched
137      * \param nr_matches    number of features actually matched
138      * \param H         image homography (prewarp) to be applied to right image features
139      */
140     void Match(const float * const *l_img,const float * const *r_img,
141         const double *x_l,const double *y_l,int nr_l,const double *x_r,const double *y_r,int nr_r,
142         int *id_l,int *id_r,int *nr_matches,const double H[9]=0);
143 
144 protected:
145     void Clean();
146 
147     int m_w,m_h,m_bw,m_bh,m_nr_h,m_nr_v,m_bd,m_target;
148     unsigned long m_kA,m_kB;
149     db_Bucket_f **m_bp_l;
150     db_Bucket_f **m_bp_r;
151     float *m_patch_space,*m_aligned_patch_space;
152 };
153 /*!
154  * \class db_Matcher_u
155  * \ingroup FeatureMatching
156  * \brief Feature matcher for byte images.
157  *
158  * Normalized correlation feature matcher for <b>byte</b> images.
159  * Correlation window size is constant and set to 11x11.
160  * See \ref FeatureDetection to detect Harris corners.
161  * Images are managed with functions in \ref LMImageBasicUtilities.
162  *
163  * If the prewarp matrix H is supplied, the feature coordinates are warped by H before being placed in
164  * appropriate buckets. If H is an affine transform and the "affine" parameter is set to 1 or 2,
165  * then the correlation patches themselves are warped before being placed in the patch space.
166  */
167 class DB_API db_Matcher_u
168 {
169 public:
170     db_Matcher_u();
171 
GetPatchSize()172     int GetPatchSize(){return 11;};
173 
174     virtual ~db_Matcher_u();
175 
176     /*!
177      Copy ctor duplicates settings.
178      Memory not copied.
179      */
180     db_Matcher_u(const db_Matcher_u& cm);
181 
182     /*!
183      Assignment optor duplicates settings
184      Memory not copied.
185      */
186     db_Matcher_u& operator= (const db_Matcher_u& cm);
187 
188     /*!
189      * Set parameters and pre-allocate memory. Return an upper bound
190      * on the number of matches.
191      * If max_disparity_v is DB_DEFAULT_NO_DISPARITY, look for matches
192      * in a ellipse around a feature of radius max_disparity*im_width by max_disparity*im_height.
193      * If max_disparity_v is specified, use a rectangle max_disparity*im_width by max_disparity_v*im_height.
194      * \param im_width          width
195      * \param im_height         height
196      * \param max_disparity     maximum distance (as fraction of image size) between matches
197      * \param target_nr_corners maximum number of matches
198      * \param max_disparity_v   maximum vertical disparity (distance between matches)
199      * \param use_smaller_matching_window   if set to true, uses a correlation window of 5x5 instead of the default 11x11
200      * \return maximum number of matches
201      */
202     virtual unsigned long Init(int im_width,int im_height,
203         double max_disparity=DB_DEFAULT_MAX_DISPARITY,
204         int target_nr_corners=DB_DEFAULT_TARGET_NR_CORNERS,
205         double max_disparity_v=DB_DEFAULT_NO_DISPARITY,
206         bool use_smaller_matching_window=false, int use_21=0);
207 
208     /*!
209      * Match two sets of features.
210      * If the prewarp H is not NULL it will be applied to the features
211      * in the right image before matching.
212      * Parameters id_l and id_r must point to arrays of size target_nr_corners
213      * (returned by Init()).
214      * The results of matching are in id_l and id_r.
215      * Interpretaqtion of results: if id_l[i] = m and id_r[i] = n,
216      * feature at (x_l[m],y_l[m]) matched to (x_r[n],y_r[n]).
217      * \param l_img     left image
218      * \param r_img     right image
219      * \param x_l       left x coordinates of features
220      * \param y_l       left y coordinates of features
221      * \param nr_l      number of features in left image
222      * \param x_r       right x coordinates of features
223      * \param y_r       right y coordinates of features
224      * \param nr_r      number of features in right image
225      * \param id_l      indices of left features that matched
226      * \param id_r      indices of right features that matched
227      * \param nr_matches    number of features actually matched
228      * \param H         image homography (prewarp) to be applied to right image features
229      * \param affine    prewarp the 11x11 patches by given affine transform. 0 means no warping,
230                         1 means nearest neighbor, 2 means bilinear warping.
231      */
232     virtual void Match(const unsigned char * const *l_img,const unsigned char * const *r_img,
233         const double *x_l,const double *y_l,int nr_l,const double *x_r,const double *y_r,int nr_r,
234         int *id_l,int *id_r,int *nr_matches,const double H[9]=0,int affine=0);
235 
236     /*!
237      * Checks if Init() was called.
238      * \return 1 if Init() was called, 0 otherwise.
239      */
240     int IsAllocated();
241 
242 protected:
243     virtual void Clean();
244 
245 
246     int m_w,m_h,m_bw,m_bh,m_nr_h,m_nr_v,m_bd,m_target;
247     unsigned long m_kA,m_kB;
248     db_Bucket_u **m_bp_l;
249     db_Bucket_u **m_bp_r;
250     short *m_patch_space,*m_aligned_patch_space;
251 
252     double m_max_disparity, m_max_disparity_v;
253     int m_rect_window;
254     bool m_use_smaller_matching_window;
255     int m_use_21;
256 };
257 
258 
259 
260 #endif /*DB_FEATURE_MATCHING_H*/
261