Main MRPT website > C++ reference for MRPT 1.5.7
xform.h
Go to the documentation of this file.
1 /* +---------------------------------------------------------------------------+
2  | Mobile Robot Programming Toolkit (MRPT) |
3  | http://www.mrpt.org/ |
4  | |
5  | Copyright (c) 2005-2017, Individual contributors, see AUTHORS file |
6  | See: http://www.mrpt.org/Authors - All rights reserved. |
7  | Released under BSD License. See details in http://www.mrpt.org/License |
8  +---------------------------------------------------------------------------+ */
9 
10 #ifndef XFORM_H
11 #define XFORM_H
12 
13 //#include "cxcore.h"
14 // Universal include for all versions of OpenCV
15 #include <mrpt/otherlibs/do_opencv_includes.h>
16 
17 
18 /********************************** Structures *******************************/
19 
20 struct feature;
21 
22 /** holds feature data relevant to ransac */
24 {
26  int sampled;
27 };
28 
29 /******************************* Defs and macros *****************************/
30 
31 /* RANSAC error tolerance in pixels */
32 #define RANSAC_ERR_TOL 3
33 
34 /** pessimistic estimate of fraction of inlers for RANSAC */
35 #define RANSAC_INLIER_FRAC_EST 0.25
36 
37 /** estimate of the probability that a correspondence supports a bad model */
38 #define RANSAC_PROB_BAD_SUPP 0.10
39 
40 /* extracts a feature's RANSAC data */
41 #define feat_ransac_data( feat ) ( (struct ransac_data*) (feat)->feature_data )
42 
43 
44 /**
45 Prototype for transformation functions passed to ransac_xform(). Functions
46 of this type should compute a transformation matrix given a set of point
47 correspondences.
48 
49 @param pts array of points
50 @param mpts array of corresponding points; each \a pts[\a i], \a i=0..\a n-1,
51  corresponds to \a mpts[\a i]
52 @param n number of points in both \a pts and \a mpts
53 
54 @return Should return a transformation matrix that transforms each point in
55  \a pts to the corresponding point in \a mpts or NULL on failure.
56 */
57 typedef CvMat* (*ransac_xform_fn)( CvPoint2D64f* pts, CvPoint2D64f* mpts,
58  int n );
59 
60 
61 /**
62 Prototype for error functions passed to ransac_xform(). For a given
63 point, its correspondence, and a transform, functions of this type should
64 compute a measure of error between the correspondence and the point after
65 the point has been transformed by the transform.
66 
67 @param pt a point
68 @param mpt \a pt's correspondence
69 @param T a transform
70 
71 @return Should return a measure of error between \a mpt and \a pt after
72  \a pt has been transformed by the transform \a T.
73 */
74 typedef double (*ransac_err_fn)( CvPoint2D64f pt, CvPoint2D64f mpt, CvMat* M );
75 
76 
77 /***************************** Function Prototypes ***************************/
78 
79 
80 /**
81 Calculates a best-fit image transform from image feature correspondences
82 using RANSAC.
83 
84 For more information refer to:
85 
86 Fischler, M. A. and Bolles, R. C. Random sample consensus: a paradigm for
87 model fitting with applications to image analysis and automated cartography.
88 <EM>Communications of the ACM, 24</EM>, 6 (1981), pp. 381--395.
89 
90 @param features an array of features; only features with a non-NULL match
91  of type \a mtype are used in homography computation
92 @param n number of features in \a feat
93 @param mtype determines which of each feature's match fields to use
94  for transform computation; should be one of FEATURE_FWD_MATCH,
95  FEATURE_BCK_MATCH, or FEATURE_MDL_MATCH; if this is FEATURE_MDL_MATCH,
96  correspondences are assumed to be between a feature's img_pt field
97  and its match's mdl_pt field, otherwise correspondences are assumed to
98  be between the the feature's img_pt field and its match's img_pt field
99 @param xform_fn pointer to the function used to compute the desired
100  transformation from feature correspondences
101 @param m minimum number of correspondences necessary to instantiate the
102  transform computed by \a xform_fn
103 @param p_badxform desired probability that the final transformation
104  returned by RANSAC is corrupted by outliers (i.e. the probability that
105  no samples of all inliers were drawn)
106 @param err_fn pointer to the function used to compute a measure of error
107  between putative correspondences for a given transform
108 @param err_tol correspondences within this distance of each other are
109  considered as inliers for a given transform
110 @param inliers if not NULL, output as an array of pointers to the final
111  set of inliers
112 @param n_in if not NULL, output as the final number of inliers
113 
114 @return Returns a transformation matrix computed using RANSAC or NULL
115  on error or if an acceptable transform could not be computed.
116 */
117 extern CvMat* ransac_xform( struct feature* features, int n, int mtype,
118  ransac_xform_fn xform_fn, int m,
119  double p_badxform, ransac_err_fn err_fn,
120  double err_tol, struct feature*** inliers,
121  int* n_in );
122 
123 
124 /**
125 Calculates a least-squares planar homography from point correspondeces.
126 Intended for use as a ransac_xform_fn.
127 
128 @param pts array of points
129 @param mpts array of corresponding points; each \a pts[\a i], \a i=0..\a n-1,
130  corresponds to \a mpts[\a i]
131 @param n number of points in both \a pts and \a mpts; must be at least 4
132 
133 @return Returns the \f$3 \times 3\f$ least-squares planar homography
134  matrix that transforms points in \a pts to their corresponding points
135  in \a mpts or NULL if fewer than 4 correspondences were provided
136 */
137 extern CvMat* lsq_homog( CvPoint2D64f* pts, CvPoint2D64f* mpts, int n );
138 
139 
140 /**
141 Calculates the transfer error between a point and its correspondence for
142 a given homography, i.e. for a point \f$x\f$, it's correspondence \f$x'\f$,
143 and homography \f$H\f$, computes \f$d(x', Hx)^2\f$. Intended for use as a
144 ransac_err_fn.
145 
146 @param pt a point
147 @param mpt \a pt's correspondence
148 @param H a homography matrix
149 
150 @return Returns the transfer error between \a pt and \a mpt given \a H
151 */
152 extern double homog_xfer_err( CvPoint2D64f pt, CvPoint2D64f mpt, CvMat* H );
153 
154 
155 /**
156 Performs a perspective transformation on a single point. That is, for a
157 point \f$(x, y)\f$ and a \f$3 \times 3\f$ matrix \f$T\f$ this function
158 returns the point \f$(u, v)\f$, where<BR>
159 
160 \f$[x' \ y' \ w']^T = T \times [x \ y \ 1]^T\f$,<BR>
161 
162 and<BR>
163 
164 \f$(u, v) = (x'/w', y'/w')\f$.
165 
166 Note that affine transforms are a subset of perspective transforms.
167 
168 @param pt a 2D point
169 @param T a perspective transformation matrix
170 
171 @return Returns the point \f$(u, v)\f$ as above.
172 */
173 extern CvPoint2D64f persp_xform_pt( CvPoint2D64f pt, CvMat* T );
174 
175 
176 #endif
double homog_xfer_err(CvPoint2D64f pt, CvPoint2D64f mpt, CvMat *H)
Calculates the transfer error between a point and its correspondence for a given homography...
GLenum GLsizei n
Definition: glext.h:4618
holds feature data relevant to ransac
Definition: xform.h:23
CvPoint2D64f persp_xform_pt(CvPoint2D64f pt, CvMat *T)
Performs a perspective transformation on a single point.
CvMat * lsq_homog(CvPoint2D64f *pts, CvPoint2D64f *mpts, int n)
Calculates a least-squares planar homography from point correspondeces.
Structure to represent an affine invariant image feature.
Definition: imgfeatures.h:52
void * orig_feat_data
Definition: xform.h:25
int sampled
Definition: xform.h:26
CvMat * ransac_xform(struct feature *features, int n, int mtype, ransac_xform_fn xform_fn, int m, double p_badxform, ransac_err_fn err_fn, double err_tol, struct feature ***inliers, int *n_in)
Calculates a best-fit image transform from image feature correspondences using RANSAC.
double(* ransac_err_fn)(CvPoint2D64f pt, CvPoint2D64f mpt, CvMat *M)
Prototype for error functions passed to ransac_xform().
Definition: xform.h:74
CvMat *(* ransac_xform_fn)(CvPoint2D64f *pts, CvPoint2D64f *mpts, int n)
Prototype for transformation functions passed to ransac_xform().
Definition: xform.h:57



Page generated by Doxygen 1.8.14 for MRPT 1.5.7 Git: 5902e14cc Wed Apr 24 15:04:01 2019 +0200 at lun oct 28 01:39:17 CET 2019