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
31DB_API void db_SignedSquareNormCorr21x21_PreAlign_u(short *patch,const unsigned char * const *f_img,int x_f,int y_f,float *sum,float *recip);
32DB_API void db_SignedSquareNormCorr11x11_PreAlign_u(short *patch,const unsigned char * const *f_img,int x_f,int y_f,float *sum,float *recip);
33float db_SignedSquareNormCorr21x21Aligned_Post_s(const short *f_patch,const short *g_patch,float fsum_gsum,float f_recip_g_recip);
34float db_SignedSquareNormCorr11x11Aligned_Post_s(const short *f_patch,const short *g_patch,float fsum_gsum,float f_recip_g_recip);
35
36class db_PointInfo_f
37{
38public:
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
56class db_Bucket_f
57{
58public:
59    db_PointInfo_f *ptr;
60    int nr;
61};
62
63class db_PointInfo_u
64{
65public:
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
83class db_Bucket_u
84{
85public:
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 */
99class DB_API db_Matcher_f
100{
101public:
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
144protected:
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 */
167class DB_API db_Matcher_u
168{
169public:
170    db_Matcher_u();
171
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
242protected:
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