1/*
2 IMPORTANT: READ BEFORE DOWNLOADING, COPYING, INSTALLING OR USING.
3
4 By downloading, copying, installing or using the software you agree to this license.
5 If you do not agree to this license, do not download, install,
6 copy or use the software.
7
8
9 BSD 3-Clause License
10
11 Copyright (C) 2014, Olexa Bilaniuk, Hamid Bazargani & Robert Laganiere, all rights reserved.
12
13 Redistribution and use in source and binary forms, with or without modification,
14 are permitted provided that the following conditions are met:
15
16 * Redistribution's of source code must retain the above copyright notice,
17 this list of conditions and the following disclaimer.
18
19 * Redistribution's in binary form must reproduce the above copyright notice,
20 this list of conditions and the following disclaimer in the documentation
21 and/or other materials provided with the distribution.
22
23 * The name of the copyright holders may not be used to endorse or promote products
24 derived from this software without specific prior written permission.
25
26 This software is provided by the copyright holders and contributors "as is" and
27 any express or implied warranties, including, but not limited to, the implied
28 warranties of merchantability and fitness for a particular purpose are disclaimed.
29 In no event shall the Intel Corporation or contributors be liable for any direct,
30 indirect, incidental, special, exemplary, or consequential damages
31 (including, but not limited to, procurement of substitute goods or services;
32 loss of use, data, or profits; or business interruption) however caused
33 and on any theory of liability, whether in contract, strict liability,
34 or tort (including negligence or otherwise) arising in any way out of
35 the use of this software, even if advised of the possibility of such damage.
36*/
37
38/**
39 * Bilaniuk, Olexa, Hamid Bazargani, and Robert Laganiere. "Fast Target
40 * Recognition on Mobile Devices: Revisiting Gaussian Elimination for the
41 * Estimation of Planar Homographies." In Computer Vision and Pattern
42 * Recognition Workshops (CVPRW), 2014 IEEE Conference on, pp. 119-125.
43 * IEEE, 2014.
44 */
45
46/* Include Guards */
47#ifndef __OPENCV_RHO_H__
48#define __OPENCV_RHO_H__
49
50
51
52/* Includes */
53#include <opencv2/core.hpp>
54
55
56
57
58
59/* Defines */
60
61
62/* Flags */
63#ifndef RHO_FLAG_NONE
64#define RHO_FLAG_NONE (0U<<0)
65#endif
66#ifndef RHO_FLAG_ENABLE_NR
67#define RHO_FLAG_ENABLE_NR (1U<<0)
68#endif
69#ifndef RHO_FLAG_ENABLE_REFINEMENT
70#define RHO_FLAG_ENABLE_REFINEMENT (1U<<1)
71#endif
72#ifndef RHO_FLAG_ENABLE_FINAL_REFINEMENT
73#define RHO_FLAG_ENABLE_FINAL_REFINEMENT (1U<<2)
74#endif
75
76
77
78/* Namespace cv */
79namespace cv{
80
81/* Data structures */
82
83/**
84 * Homography Estimation context.
85 */
86
87struct RHO_HEST;
88typedef struct RHO_HEST RHO_HEST;
89
90
91/* Functions */
92
93/**
94 * Initialize the estimator context, by allocating the aligned buffers
95 * internally needed.
96 *
97 * @return A pointer to the context if successful; NULL if an error occurred.
98 */
99
100Ptr<RHO_HEST> rhoInit(void);
101
102
103/**
104 * Ensure that the estimator context's internal table for non-randomness
105 * criterion is at least of the given size, and uses the given beta. The table
106 * should be larger than the maximum number of matches fed into the estimator.
107 *
108 * A value of N of 0 requests deallocation of the table.
109 *
110 * @param [in] p The initialized estimator context
111 * @param [in] N If 0, deallocate internal table. If > 0, ensure that the
112 * internal table is of at least this size, reallocating if
113 * necessary.
114 * @param [in] beta The beta-factor to use within the table.
115 * @return 0 if unsuccessful; non-zero otherwise.
116 */
117
118int rhoEnsureCapacity(Ptr<RHO_HEST> p, unsigned N, double beta);
119
120
121
122/**
123 * Seeds the internal PRNG with the given seed.
124 *
125 * Although it is not required to call this function, since context
126 * initialization seeds itself with entropy from rand(), this function allows
127 * reproducible results by using a specified seed.
128 *
129 * @param [in] p The estimator context whose PRNG is to be seeded.
130 * @param [in] seed The 64-bit integer seed.
131 */
132
133void rhoSeed(Ptr<RHO_HEST> p, uint64_t seed);
134
135
136/**
137 * Estimates the homography using the given context, matches and parameters to
138 * PROSAC.
139 *
140 * The given context must have been initialized.
141 *
142 * The matches are provided as two arrays of N single-precision, floating-point
143 * (x,y) points. Points with corresponding offsets in the two arrays constitute
144 * a match. The homography estimation attempts to find the 3x3 matrix H which
145 * best maps the homogeneous-coordinate points in the source array to their
146 * corresponding homogeneous-coordinate points in the destination array.
147 *
148 * Note: At least 4 matches must be provided (N >= 4).
149 * Note: A point in either array takes up 2 floats. The first of two stores
150 * the x-coordinate and the second of the two stores the y-coordinate.
151 * Thus, the arrays resemble this in memory:
152 *
153 * src = [x0, y0, x1, y1, x2, y2, x3, y3, x4, y4, ...]
154 * Matches: | | | | |
155 * dst = [x0, y0, x1, y1, x2, y2, x3, y3, x4, y4, ...]
156 * Note: The matches are expected to be provided sorted by quality, or at
157 * least not be worse-than-random in ordering.
158 *
159 * A pointer to the base of an array of N bytes can be provided. It serves as
160 * an output mask to indicate whether the corresponding match is an inlier to
161 * the returned homography, if any. A zero indicates an outlier; A non-zero
162 * value indicates an inlier.
163 *
164 * The PROSAC estimator requires a few parameters of its own. These are:
165 *
166 * - The maximum distance that a source point projected onto the destination
167 * plane can be from its putative match and still be considered an
168 * inlier. Must be non-negative.
169 * A sane default is 3.0.
170 * - The maximum number of PROSAC iterations. This corresponds to the
171 * largest number of samples that will be drawn and tested.
172 * A sane default is 2000.
173 * - The RANSAC convergence parameter. This corresponds to the number of
174 * iterations after which PROSAC will start sampling like RANSAC.
175 * A sane default is 2000.
176 * - The confidence threshold. This corresponds to the probability of
177 * finding a correct solution. Must be bounded by [0, 1].
178 * A sane default is 0.995.
179 * - The minimum number of inliers acceptable. Only a solution with at
180 * least this many inliers will be returned. The minimum is 4.
181 * A sane default is 10% of N.
182 * - The beta-parameter for the non-randomness termination criterion.
183 * Ignored if non-randomness criterion disabled, otherwise must be
184 * bounded by (0, 1).
185 * A sane default is 0.35.
186 * - Optional flags to control the estimation. Available flags are:
187 * HEST_FLAG_NONE:
188 * No special processing.
189 * HEST_FLAG_ENABLE_NR:
190 * Enable non-randomness criterion. If set, the beta parameter
191 * must also be set.
192 * HEST_FLAG_ENABLE_REFINEMENT:
193 * Enable refinement of each new best model, as they are found.
194 * HEST_FLAG_ENABLE_FINAL_REFINEMENT:
195 * Enable one final refinement of the best model found before
196 * returning it.
197 *
198 * The PROSAC estimator optionally accepts an extrinsic initial guess of H.
199 *
200 * The PROSAC estimator outputs a final estimate of H provided it was able to
201 * find one with a minimum of supporting inliers. If it was not, it outputs
202 * the all-zero matrix.
203 *
204 * The extrinsic guess at and final estimate of H are both in the same form:
205 * A 3x3 single-precision floating-point matrix with step 3. Thus, it is a
206 * 9-element array of floats, with the elements as follows:
207 *
208 * [ H00, H01, H02,
209 * H10, H11, H12,
210 * H20, H21, 1.0 ]
211 *
212 * Notice that the homography is normalized to H22 = 1.0.
213 *
214 * The function returns the number of inliers if it was able to find a
215 * homography with at least the minimum required support, and 0 if it was not.
216 *
217 *
218 * @param [in,out] p The context to use for homography estimation. Must
219 * be already initialized. Cannot be NULL.
220 * @param [in] src The pointer to the source points of the matches.
221 * Must be aligned to 4 bytes. Cannot be NULL.
222 * @param [in] dst The pointer to the destination points of the matches.
223 * Must be aligned to 4 bytes. Cannot be NULL.
224 * @param [out] inl The pointer to the output mask of inlier matches.
225 * Must be aligned to 4 bytes. May be NULL.
226 * @param [in] N The number of matches. Minimum 4.
227 * @param [in] maxD The maximum distance. Minimum 0.
228 * @param [in] maxI The maximum number of PROSAC iterations.
229 * @param [in] rConvg The RANSAC convergence parameter.
230 * @param [in] cfd The required confidence in the solution.
231 * @param [in] minInl The minimum required number of inliers. Minimum 4.
232 * @param [in] beta The beta-parameter for the non-randomness criterion.
233 * @param [in] flags A union of flags to fine-tune the estimation.
234 * @param [in] guessH An extrinsic guess at the solution H, or NULL if
235 * none provided.
236 * @param [out] finalH The final estimation of H, or the zero matrix if
237 * the minimum number of inliers was not met.
238 * Cannot be NULL.
239 * @return The number of inliers if the minimum number of
240 * inliers for acceptance was reached; 0 otherwise.
241 */
242
243unsigned rhoHest(Ptr<RHO_HEST> p, /* Homography estimation context. */
244 const float* src, /* Source points */
245 const float* dst, /* Destination points */
246 char* inl, /* Inlier mask */
247 unsigned N, /* = src.length = dst.length = inl.length */
248 float maxD, /* 3.0 */
249 unsigned maxI, /* 2000 */
250 unsigned rConvg, /* 2000 */
251 double cfd, /* 0.995 */
252 unsigned minInl, /* 4 */
253 double beta, /* 0.35 */
254 unsigned flags, /* 0 */
255 const float* guessH, /* Extrinsic guess, NULL if none provided */
256 float* finalH); /* Final result. */
257
258
259
260
261/* End Namespace cv */
262}
263
264
265
266
267#endif
268

Provided by KDAB

Privacy Policy
Learn to use CMake with our Intro Training
Find out more

source code of opencv/modules/calib3d/src/rho.h