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_image_homography.h,v 1.2 2011/06/17 14:03:31 mbansal Exp $ */
18
19#ifndef DB_IMAGE_HOMOGRAPHY
20#define DB_IMAGE_HOMOGRAPHY
21
22
23
24/*****************************************************************
25*    Lean and mean begins here                                   *
26*****************************************************************/
27
28#include "db_framestitching.h"
29/*!
30 * \defgroup LMImageHomography (LM) Image Homography Estimation (feature based)
31 */
32/*\{*/
33/*!
34Solve for projective H such that xp~Hx. Prior normalization is not necessary,
35although desirable for numerical conditioning
36\param H    image projective (out)
37\param x1   image 1 point 1
38\param x2   image 1 point 2
39\param x3   image 1 point 3
40\param x4   image 1 point 4
41\param xp1  image 2 point 1
42\param xp2  image 2 point 2
43\param xp3  image 2 point 3
44\param xp4  image 2 point 4
45*/
46DB_API void db_StitchProjective2D_4Points(double H[9],
47                                      double x1[3],double x2[3],double x3[3],double x4[3],
48                                      double xp1[3],double xp2[3],double xp3[3],double xp4[3]);
49
50/*!
51Solve for affine H such that xp~Hx. Prior normalization is not necessary,
52although desirable for numerical conditioning
53\param H    image projective (out)
54\param x1   image 1 point 1
55\param x2   image 1 point 2
56\param x3   image 1 point 3
57\param xp1  image 2 point 1
58\param xp2  image 2 point 2
59\param xp3  image 2 point 3
60*/
61DB_API void db_StitchAffine2D_3Points(double H[9],
62                                      double x1[3],double x2[3],double x3[3],
63                                      double xp1[3],double xp2[3],double xp3[3]);
64
65/*!
66Solve for rotation R such that xp~Rx.
67Image points have to be of unit norm for the least squares to be meaningful.
68\param R    image rotation (out)
69\param x1   image 1 point 1
70\param x2   image 1 point 2
71\param xp1  image 2 point 1
72\param xp2  image 2 point 2
73*/
74inline void db_StitchCameraRotation_2Points(double R[9],
75                                            /*Image points have to be of unit norm
76                                            for the least squares to be meaningful*/
77                                            double x1[3],double x2[3],
78                                            double xp1[3],double xp2[3])
79{
80    double* x[2];
81    double* xp[2];
82    double scale,t[3];
83
84    x[0]=x1;
85    x[1]=x2;
86    xp[0]=xp1;
87    xp[1]=xp2;
88    db_StitchSimilarity3DRaw(&scale,R,t,xp,x,2,1,0,1,0);
89}
90
91/*!
92Solve for a homography H generated by a rotation R with a common unknown focal length f, i.e.
93H=diag(f,f,1)*R*diag(1/f,1/f,1) such that xp~Hx.
94If signed_disambiguation is true, the points are
95required to be in front of the camera. No specific normalization of the homogenous points
96is required, although it could be desirable to keep x1,x2,xp1 and xp2 of reasonable magnitude.
97If a solution is obtained the function returns 1, otherwise 0. If the focal length is desired
98a valid pointer should be passed in f
99*/
100DB_API int db_StitchRotationCommonFocalLength_3Points(double H[9],double x1[3],double x2[3],double x3[3],
101                                                      double xp1[3],double xp2[3],double xp3[3],double *f=0,int signed_disambiguation=1);
102
103/*!
104Find scale, rotation and translation of the similarity that
105takes the nr_points inhomogenous 2D points X to Xp,
106i.e. for the homogenous equivalents
107Xp and X we would have
108\code
109Xp~
110[sR t]*X
111[0  1]
112\endcode
113If orientation_preserving is true, R is restricted such that det(R)>0.
114allow_scaling, allow_rotation and allow_translation allow s,R and t
115to differ from 1,Identity and 0
116
117Full similarity takes the following on 550MHz:
118\code
1190.9 microseconds with       2 points
1201.0 microseconds with       3 points
1211.1 microseconds with       4 points
1221.3 microseconds with       5 points
1231.4 microseconds with       6 points
1241.7 microseconds with      10 points
1259   microseconds with     100 points
126130 microseconds with    1000 points
1271.3 milliseconds with   10000 points
12835  milliseconds with  100000 points
129350 milliseconds with 1000000 points
130\endcode
131
132Without orientation_preserving:
133\code
1343 points is minimal for (s,R,t) (R,t)
1352 points is minimal for (s,t) (s,R) (R)
1361 point is minimal for  (s) (t)
137\endcode
138
139With orientation_preserving:
140\code
1412 points is minimal for (s,R,t) (R,t) (s,t)
1421 point is minimal for (s,R) (R) (s) (t)
143\endcode
144\param scale        (out)
145\param R            2D rotation (out)
146\param t            2D translation (out)
147\param Xp           (nr_points x 2) pointer to array of image points
148\param X            (nr_points x 2 ) pointer to array of image points
149\param nr_points    number of points
150\param orientation_preserving
151\param allow_scaling    compute scale (if 0, scale=1)
152\param allow_rotation   compute rotation (if 0, R=[I])
153\param allow_translation compute translation (if 0 t = [0,0]')
154*/
155DB_API void db_StitchSimilarity2DRaw(double *scale,double R[4],double t[2],
156                            double **Xp,double **X,int nr_points,int orientation_preserving=1,
157                            int allow_scaling=1,int allow_rotation=1,int allow_translation=1);
158/*!
159See db_StitchRotationCommonFocalLength_3Points().
160\param H            Image similarity transformation (out)
161\param Xp           (nr_points x 2) pointer to array of image points
162\param X            (nr_points x 2) pointer to array of image points
163\param nr_points    number of points
164\param orientation_preserving
165\param allow_scaling    compute scale (if 0, scale=1)
166\param allow_rotation   compute rotation (if 0, R=[I])
167\param allow_translation compute translation (if 0 t = [0,0]')
168*/
169inline void db_StitchSimilarity2D(double H[9],double **Xp,double **X,int nr_points,int orientation_preserving=1,
170                                  int allow_scaling=1,int allow_rotation=1,int allow_translation=1)
171{
172    double s,R[4],t[2];
173
174    db_StitchSimilarity2DRaw(&s,R,t,Xp,X,nr_points,orientation_preserving,
175        allow_scaling,allow_rotation,allow_translation);
176
177    H[0]=s*R[0]; H[1]=s*R[1]; H[2]=t[0];
178    H[3]=s*R[2]; H[4]=s*R[3]; H[5]=t[1];
179    db_Zero2(H+6);
180    H[8]=1.0;
181}
182/*\}*/
183#endif /* DB_IMAGE_HOMOGRAPHY */
184