Last updated Dec. 17, 2011
A compilation of answers to questions frequently asked by homest users
homest is a C/C++ implementation of an algorithm for non-linear, robust homography estimation from matched image point features that is distributed under the GNU General Public License.
homest can estimate fully projective homographies, i.e. homographies that depend on eight parameters up to scale. Furthermore, it can estimate affine homographies whose matrix has a third row equal to [0, 0, 1] and, therefore, depend upon six parameters. For more information, refer respectively to functions homest() and homestaff() in the code.
To be able to compile homest, you should have installed levmar, a GPL Levenberg-Marquardt implementation and LAPACK (or an equivalent vendor library). levmar can be downloaded from http://www.ics.forth.gr/~lourakis/levmar; a free f2c'ed version of LAPACK is available at http://www.netlib.org/clapack. homest users have also reported that the precompiled MSWin libraries at Netlib are broken, therefore it is suggested to build them yourself. Alternatively, precompiled MSWin LAPACK/BLAS libraries are offered here and here.
First, you should install levmar and LAPACK. To do so, please refer to levmar's FAQ and to the instructions accompanying your variant of LAPACK, respectively. The second step is to compile homest itself. The tarfile contains makefiles for Unix/Linux using gcc (Makefile) or Intel's icc (Makefile.icc) and MSWin using Visual Studio (Makefile.vc). Please read the comments within those files for more information. Also, do not forget to update them with the filesystem path of your compiled levmar and LAPACK libraries.
The source code of each function is preceeded by detailed comments explaining the role of each argument. See the *.c files.
homest incorporates an implementation of the Least Median of Squares (LMedS) robust estimator. LMedS is capable of automatically detecting and tolerating up to 50% outliers (i.e. mismatched image points) in homest's input.
After the completion of the LMedS robust regression, certain matching point pairs are marked as being erroneous, i.e. ouliers. The set of inlying point matches, i.e. the set of input point pairs excluding the outliers, can be printed by including a conditionally compiled code fragment in homest(): Search for the comment that reads include the following code fragment to print the (unnormalized) matching point pairs found to be inlying and change the #if 0 to #if 1.
homest implements five different cost functions for the non-linear refinement of homographies, namely the (non-symmetric) homographic transfer error in the first image, the (non-symmetric) homographic transfer error in the second image, the symmetric homographic transfer error, the Sampson error and the reprojection error. The user can choose between the five by passing respectively HOMEST_XFER_ERROR1, HOMEST_XFER_ERROR2, HOMEST_SYM_XFER_ERROR, HOMEST_SAMPSON_ERROR or HOMEST_REPR_ERROR as the value of the NLrefine argument of homest(). A value of HOMEST_NO_NLN_REFINE indicates that no non-linear refinement is desired. Note also that HOMEST_XFER_ERROR is an alias for HOMEST_XFER_ERROR2.
For affine homographies, the algebraic error is equal to the geometric one. Therefore, the DLT algorithm employed to minimize the algebraic distance, also minimizes the geometric distance and no subsequent refinement is necessary.
A homography H is associated with a direction, i.e. it transfers points from image A to B. The homography corresponding to the opposite direction B to A, is simply the matrix inverse of H. Refer to homest.h for functions performing such calculations.
To build a DLL and the corresponding import library that contains homest, the DLL_BUILD macro symbol should be defined in homest.h. This definition turns on certain compiler directives for MSVC that instruct it to create a DLL with homest exported functions.
Yes. Starting with version 1.2, homest includes a MEX-file that can be used to interface it with matlab. See homest.c in the matlab directory of homest's source distribution. Assuming that the MEX-file has been compiled (see also Q13), file homest_demo.m contains examples of its use with matlab. Try it with the command matlab < homest_demo.m.
The answer depends on your operating system/compiler. The Makefile in the matlab directory works with GCC under Linux, whereas Makefile.w32 works with MSVC under Windows. You might also need to run "mex -setup" from the matlab or OS command prompt to configure your system to build MEX-files. In any case, the provided makefiles can be used as a starting point for compiling on your own system.
homest is distributed under GPL with the intention of allowing its free use for research and personal purposes. GPL allows you to modify the original code into a new program and then sell copies of the modified program commercially, but only under the terms of the GPL. Thus, you must make the source code available to the users of the program as described in the GPL, and they must be allowed to redistribute and modify it as described in the GPL. Clearly, such requirements are in conflict with using homest as part of a proprietary application. However, it is possible to obtain a paid license for proprietary commercial use under terms different than those of GPL. Please contact the author for further information on such licensing. More answers to questions related to the GPL license can be found here.