Planar tracking support for motion tracking
[blender.git] / extern / libmv / libmv / multiview / homography.h
1 // Copyright (c) 2011 libmv authors.
2 //
3 // Permission is hereby granted, free of charge, to any person obtaining a copy
4 // of this software and associated documentation files (the "Software"), to
5 // deal in the Software without restriction, including without limitation the
6 // rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
7 // sell copies of the Software, and to permit persons to whom the Software is
8 // furnished to do so, subject to the following conditions:
9 //
10 // The above copyright notice and this permission notice shall be included in
11 // all copies or substantial portions of the Software.
12 //
13 // THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
14 // IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
15 // FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
16 // AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
17 // LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
18 // FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
19 // IN THE SOFTWARE.
20
21 #ifndef LIBMV_MULTIVIEW_HOMOGRAPHY_H_
22 #define LIBMV_MULTIVIEW_HOMOGRAPHY_H_
23
24 #include "libmv/numeric/numeric.h"
25
26 namespace libmv {
27
28 /**
29  * 2D homography transformation estimation.
30  * 
31  * This function estimates the homography transformation from a list of 2D
32  * correspondences which represents either:
33  *
34  * - 3D points on a plane, with a general moving camera.
35  * - 3D points with a rotating camera (pure rotation).
36  * - 3D points + different planar projections
37  * 
38  * \param x1 The first 2xN or 3xN matrix of euclidean or homogeneous points.
39  * \param x2 The second 2xN or 3xN matrix of euclidean or homogeneous points.
40  * \param  H The 3x3 homography transformation matrix (8 dof) such that
41  *               x2 = H * x1   with       |a b c| 
42  *                                    H = |d e f|
43  *                                        |g h 1| 
44  * \param expected_precision The expected precision in order for instance 
45  *                           to accept almost homography matrices.
46  *
47  * \return True if the transformation estimation has succeeded.
48  * \note There must be at least 4 non-colinear points.
49  */
50 bool Homography2DFromCorrespondencesLinear(const Mat &x1,
51                                            const Mat &x2,
52                                            Mat3 *H,
53                                            double expected_precision = 
54                                              EigenDouble::dummy_precision());
55
56 /**
57  * 3D Homography transformation estimation.
58  * 
59  * This function can be used in order to estimate the homography transformation
60  * from a list of 3D correspondences.
61  *
62  * \param[in] x1 The first 4xN matrix of homogeneous points
63  * \param[in] x2 The second 4xN matrix of homogeneous points
64  * \param[out] H The 4x4 homography transformation matrix (15 dof) such that
65  *               x2 = H * x1   with       |a b c d| 
66  *                                    H = |e f g h|
67  *                                        |i j k l|
68  *                                        |m n o 1| 
69  * \param[in] expected_precision The expected precision in order for instance 
70  *        to accept almost homography matrices.
71  * 
72  * \return true if the transformation estimation has succeeded
73  * 
74  * \note Need at least 5 non coplanar points 
75  * \note Points coordinates must be in homogeneous coordinates
76  */
77 bool Homography3DFromCorrespondencesLinear(const Mat &x1,
78                                            const Mat &x2,
79                                            Mat4 *H,
80                                            double expected_precision = 
81                                              EigenDouble::dummy_precision());
82 } // namespace libmv
83
84 #endif  // LIBMV_MULTIVIEW_HOMOGRAPHY_H_