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 #include <stdint.h> 55 56 57 58 59 60 /* Defines */ 61 62 63 /* Flags */ 64 #ifndef RHO_FLAG_NONE 65 #define RHO_FLAG_NONE (0U<<0) 66 #endif 67 #ifndef RHO_FLAG_ENABLE_NR 68 #define RHO_FLAG_ENABLE_NR (1U<<0) 69 #endif 70 #ifndef RHO_FLAG_ENABLE_REFINEMENT 71 #define RHO_FLAG_ENABLE_REFINEMENT (1U<<1) 72 #endif 73 #ifndef RHO_FLAG_ENABLE_FINAL_REFINEMENT 74 #define RHO_FLAG_ENABLE_FINAL_REFINEMENT (1U<<2) 75 #endif 76 77 78 79 /* Namespace cv */ 80 namespace cv{ 81 82 /* Data structures */ 83 84 /** 85 * Homography Estimation context. 86 */ 87 88 struct RHO_HEST; 89 typedef struct RHO_HEST RHO_HEST; 90 91 92 /* Functions */ 93 94 /** 95 * Initialize the estimator context, by allocating the aligned buffers 96 * internally needed. 97 * 98 * @return A pointer to the context if successful; NULL if an error occured. 99 */ 100 101 Ptr<RHO_HEST> rhoInit(void); 102 103 104 /** 105 * Ensure that the estimator context's internal table for non-randomness 106 * criterion is at least of the given size, and uses the given beta. The table 107 * should be larger than the maximum number of matches fed into the estimator. 108 * 109 * A value of N of 0 requests deallocation of the table. 110 * 111 * @param [in] p The initialized estimator context 112 * @param [in] N If 0, deallocate internal table. If > 0, ensure that the 113 * internal table is of at least this size, reallocating if 114 * necessary. 115 * @param [in] beta The beta-factor to use within the table. 116 * @return 0 if unsuccessful; non-zero otherwise. 117 */ 118 119 int rhoEnsureCapacity(Ptr<RHO_HEST> p, unsigned N, double beta); 120 121 122 123 /** 124 * Seeds the internal PRNG with the given seed. 125 * 126 * Although it is not required to call this function, since context 127 * initialization seeds itself with entropy from rand(), this function allows 128 * reproducible results by using a specified seed. 129 * 130 * @param [in] p The estimator context whose PRNG is to be seeded. 131 * @param [in] seed The 64-bit integer seed. 132 */ 133 134 void rhoSeed(Ptr<RHO_HEST> p, uint64_t seed); 135 136 137 /** 138 * Estimates the homography using the given context, matches and parameters to 139 * PROSAC. 140 * 141 * The given context must have been initialized. 142 * 143 * The matches are provided as two arrays of N single-precision, floating-point 144 * (x,y) points. Points with corresponding offsets in the two arrays constitute 145 * a match. The homography estimation attempts to find the 3x3 matrix H which 146 * best maps the homogeneous-coordinate points in the source array to their 147 * corresponding homogeneous-coordinate points in the destination array. 148 * 149 * Note: At least 4 matches must be provided (N >= 4). 150 * Note: A point in either array takes up 2 floats. The first of two stores 151 * the x-coordinate and the second of the two stores the y-coordinate. 152 * Thus, the arrays resemble this in memory: 153 * 154 * src = [x0, y0, x1, y1, x2, y2, x3, y3, x4, y4, ...] 155 * Matches: | | | | | 156 * dst = [x0, y0, x1, y1, x2, y2, x3, y3, x4, y4, ...] 157 * Note: The matches are expected to be provided sorted by quality, or at 158 * least not be worse-than-random in ordering. 159 * 160 * A pointer to the base of an array of N bytes can be provided. It serves as 161 * an output mask to indicate whether the corresponding match is an inlier to 162 * the returned homography, if any. A zero indicates an outlier; A non-zero 163 * value indicates an inlier. 164 * 165 * The PROSAC estimator requires a few parameters of its own. These are: 166 * 167 * - The maximum distance that a source point projected onto the destination 168 * plane can be from its putative match and still be considered an 169 * inlier. Must be non-negative. 170 * A sane default is 3.0. 171 * - The maximum number of PROSAC iterations. This corresponds to the 172 * largest number of samples that will be drawn and tested. 173 * A sane default is 2000. 174 * - The RANSAC convergence parameter. This corresponds to the number of 175 * iterations after which PROSAC will start sampling like RANSAC. 176 * A sane default is 2000. 177 * - The confidence threshold. This corresponds to the probability of 178 * finding a correct solution. Must be bounded by [0, 1]. 179 * A sane default is 0.995. 180 * - The minimum number of inliers acceptable. Only a solution with at 181 * least this many inliers will be returned. The minimum is 4. 182 * A sane default is 10% of N. 183 * - The beta-parameter for the non-randomness termination criterion. 184 * Ignored if non-randomness criterion disabled, otherwise must be 185 * bounded by (0, 1). 186 * A sane default is 0.35. 187 * - Optional flags to control the estimation. Available flags are: 188 * HEST_FLAG_NONE: 189 * No special processing. 190 * HEST_FLAG_ENABLE_NR: 191 * Enable non-randomness criterion. If set, the beta parameter 192 * must also be set. 193 * HEST_FLAG_ENABLE_REFINEMENT: 194 * Enable refinement of each new best model, as they are found. 195 * HEST_FLAG_ENABLE_FINAL_REFINEMENT: 196 * Enable one final refinement of the best model found before 197 * returning it. 198 * 199 * The PROSAC estimator optionally accepts an extrinsic initial guess of H. 200 * 201 * The PROSAC estimator outputs a final estimate of H provided it was able to 202 * find one with a minimum of supporting inliers. If it was not, it outputs 203 * the all-zero matrix. 204 * 205 * The extrinsic guess at and final estimate of H are both in the same form: 206 * A 3x3 single-precision floating-point matrix with step 3. Thus, it is a 207 * 9-element array of floats, with the elements as follows: 208 * 209 * [ H00, H01, H02, 210 * H10, H11, H12, 211 * H20, H21, 1.0 ] 212 * 213 * Notice that the homography is normalized to H22 = 1.0. 214 * 215 * The function returns the number of inliers if it was able to find a 216 * homography with at least the minimum required support, and 0 if it was not. 217 * 218 * 219 * @param [in/out] p The context to use for homography estimation. Must 220 * be already initialized. Cannot be NULL. 221 * @param [in] src The pointer to the source points of the matches. 222 * Must be aligned to 4 bytes. Cannot be NULL. 223 * @param [in] dst The pointer to the destination points of the matches. 224 * Must be aligned to 4 bytes. Cannot be NULL. 225 * @param [out] inl The pointer to the output mask of inlier matches. 226 * Must be aligned to 4 bytes. May be NULL. 227 * @param [in] N The number of matches. Minimum 4. 228 * @param [in] maxD The maximum distance. Minimum 0. 229 * @param [in] maxI The maximum number of PROSAC iterations. 230 * @param [in] rConvg The RANSAC convergence parameter. 231 * @param [in] cfd The required confidence in the solution. 232 * @param [in] minInl The minimum required number of inliers. Minimum 4. 233 * @param [in] beta The beta-parameter for the non-randomness criterion. 234 * @param [in] flags A union of flags to fine-tune the estimation. 235 * @param [in] guessH An extrinsic guess at the solution H, or NULL if 236 * none provided. 237 * @param [out] finalH The final estimation of H, or the zero matrix if 238 * the minimum number of inliers was not met. 239 * Cannot be NULL. 240 * @return The number of inliers if the minimum number of 241 * inliers for acceptance was reached; 0 otherwise. 242 */ 243 244 unsigned rhoHest(Ptr<RHO_HEST> p, /* Homography estimation context. */ 245 const float* src, /* Source points */ 246 const float* dst, /* Destination points */ 247 char* inl, /* Inlier mask */ 248 unsigned N, /* = src.length = dst.length = inl.length */ 249 float maxD, /* 3.0 */ 250 unsigned maxI, /* 2000 */ 251 unsigned rConvg, /* 2000 */ 252 double cfd, /* 0.995 */ 253 unsigned minInl, /* 4 */ 254 double beta, /* 0.35 */ 255 unsigned flags, /* 0 */ 256 const float* guessH, /* Extrinsic guess, NULL if none provided */ 257 float* finalH); /* Final result. */ 258 259 260 261 262 /* End Namespace cv */ 263 } 264 265 266 267 268 #endif 269