Last updated Feb. 14, 2016
A compilation of answers to questions frequently asked by fundest users
fundest is a C/C++ implementation of a set of algorithms for non-linear, robust fundamental matrix (fmatrix) estimation from matched image point features that is distributed under the GNU General Public License.
fundest can currently estimate only fully projective fmatrices that depend on seven parameters up to scale. For more information, refer to function fundest() in the code. In the future, support for affine fmatrices whose upper left 2x2 submatrix is zero (4 DOF) might be added.
To be able to compile fundest, 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. fundest 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 fundest 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 f2c library is needed for f2c'ed versions of LAPACK/BLAS. On some systems it is equivalent to the F77 and I77 libraries, whereas on others it is not needed at all. If your linker complains about a missing f2c library, edit CMakeLists.txt and try substituting it with F77 and I77 or remove it altogether.
The source code of each function is preceeded by detailed comments explaining the role of each argument. See the *.c files.
fundest 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 fundest'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 fundest(): 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.
fundest implements three different schemes for the non-linear refinement of fmatrices, namely the algebraic error, the symmetric distance to epipolar lines and the Sampson error. The user can choose between the three by passing respectively FUNDEST_ALGMIN, FUNDEST_EPIP_DIST or FUNDEST_SAMPSON_ERROR as the value of the howto argument of fundest()/fundest_wie(). A value of FUNDEST_8PT indicates that no non-linear refinement is desired and fundest stops after the linear estimation.
A fmatrix F is associated with a direction, i.e. it defines in B the epipolar lines of points from A, The fmatrix corresponding to the opposite direction B to A, is simply the matrix transpose of F.
If a reasonably accurate fmatrix estimate is available (e.g., from a previous estimation, from extrisinc calibration, etc), it can be updated at low cost using the function fundest_wie(). This function relies on a supplied estimate to detect outliers and then uses them to linearly estimate the fundamental matrix or non-linearly refine the supplied estimate. Since fundest_wie() avoids the invocation of LMedS for detecting outliers, it is several times faster than fundest().
The epipoles associated with an fmatrix are its null vectors and can be extracted with the SVD. This operation is implemented by function fundest_epipfromF().
The essential matrix corresponding to an image pair can be computed from a fundamental matrix with the function fundest_EfromFK(). Note that this requires the camera instrinsics to be known.
There are four possible rotation-translation pairs compatible with an essential matrix. They can be computed from a given essential matrix with the function fundest_RtfromE(). Note that this function computes two pairs R1,t1 and R2,t2 with t2 = −t1, but R2,t1 and R1,t2 are also valid pairs.
A set of matching point pairs is termed degenerate with respect to a model if it does not admit a unique solution with respect
to that model. In the case of fmatrix estimation, a degenerate data set conforms to more than one epipolar constraints. Sets of
matching points that are constrained by a plane-to-plane projectivity (homography) are degenerate, since they are compatible with
a two parameter family of fundamental matrices. Degenerate cases for fmatrix estimation arise, for example, when a camera is
rotating about its focal point without any translation or when all matched points are coplanar in 3D.
To identify such cases, model selection can be employed. This involves
fitting both a homography and a fundamental matrix to the data. For each model, a cost function is applied that measures the
robust likelihood of the mapping for the correspondences. fundest implements a cost function known as
GRIC (Geometric Robust Information Criterion). GRIC is the sum
of two terms, the first related to the goodness of the fit and the second to the parsimony of the model. For degenerate
data, GRIC will generally give a lower score to a homography than to a fmatrix. Thus, GRIC allows one to determine which
model better captures the relationship between frames and eventually assess the relative quality of each fit.
fundest_demo.c includes an example of using GRIC, in which the homography is estimated with
homest (http://www.ics.forth.gr/~lourakis/homest).
To try it, homest should be installed and the macro HAVE_HOMEST has to be defined during the
compilation of fundest.
Yes. fundest includes a MEX-file that can be used to interface it with matlab. See fundest.c in the matlab directory of fundest's source distribution. Assuming that the MEX-file has been compiled (see also Q17), file fundest_demo.m contains examples of its use with matlab. Try it with the command matlab < fundest_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.
fundest 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 fundest 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.