*Last updated Dec. 17, 2011*

A compilation of answers to questions frequently asked by `homest` users

*Q1 -- What is*`homest`?*Q2 -- What types of homographies can*`homest`estimate?*Q3 -- What do I need to use*`homest`?*Q4 -- How can I compile*`homest`?*Q5 -- Where are the arguments of the various routines explained in detail?**Q6 -- What kind of robustness does*`homest`offer?*Q7 -- How can I print the set of inlying point matches?**Q8 -- How can I choose the cost function for the non-linear homography refinement step?**Q9 -- Why is there no option for non-linear refinement of an affine homography?**Q10 -- How can I compute a homography from image B to A given the homography from A to B?**Q11 -- How can I build a DLL containing*`homest`?*Q12 -- Can I use*`homest`from matlab?*Q13 -- How can I compile*`homest`'s MEX-file?*Q14 -- Can I include*`homest`in a commercial product?

-- [top]**Q1 -- What is**`homest`?-- [top]**Q2 -- What types of homographies can**`homest`estimate?-- [top]**Q3 -- What do I need to use**`homest`?-- [top]**Q4 -- How can I compile**`homest`?-- [top]**Q5 -- Where are the arguments of the various routines explained in detail?**-- [top]**Q6 -- What kind of robustness does**`homest`offer?-- [top]**Q7 -- How can I print the set of inlying point matches?**-- [top]**Q8 -- How can I choose the cost function for the non-linear homography refinement step?**-- [top]**Q9 -- Why is there no option for non-linear refinement of an affine homography?**-- [top]**Q10 -- How can I compute a homography from image B to A given the homography from A to B?**-- [top]**Q11 -- How can I build a DLL containing**`homest`?-- [top]**Q12 -- Can I use**`homest`from matlab?-- [top]**Q13 -- How can I compile**`homest`'s MEX-file?-- [top]**Q14 -- Can I include**`homest`in a commercial product?

`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

`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.