Introduce doxygen documentation for the code implemented with OpenCV.

Improve previous doc.

Author: fspindle

README.md

@@ -8,7 +8,7 @@ For most of the presented approaches presented in the submitted paper:
 
 	E. Marchand, H. Uchiyama and F. Spindler. Camera localization for augmented reality: a hands-on survey. 
 
-we provide the code of short examples. This should allow developers to easily bridge the gap between theoretical aspects and practice.  These examples have been written using <a href="http://team.inria.fr/lagadic/visp">ViSP library</a> developed at Inria.
+we provide the code of short examples. This should allow developers to easily bridge the gap between theoretical aspects and practice.  These examples have been written using either <a href="http://opencv.org">OpenCV</a> or <a href="http://visp.inria.fr">ViSP</a> developed at Inria.
 
 
 The full documentation of this project is available from <http://team.inria.fr/lagadic/camera_localization>.

doc/mainpage.doc.cmake

@@ -16,22 +16,18 @@ E. Marchand, H. Uchiyama and F. Spindler. Pose estimation for augmented reality:
 a hands-on survey. submitted
 \endcode
 
-  a brief but almost self contented introduction to the most important approaches dedicated to camera localization along with a survey of the extension that have been proposed in the recent years. We also try to link these methodological concepts to the main libraries and SDK available on the market. 
+a brief but almost self contented introduction to the most important approaches dedicated to camera localization along with a survey of the extension that have been proposed in the recent years. We also try to link these methodological concepts to the main libraries and SDK available on the market. 
 
 
 
 The aim of this paper is then to provide researchers and practitioners with an almost  comprehensive and consolidate 
 introduction to effective tools to facilitate  research in augmented reality. It is also dedicated to academics involved in teaching augmented reality at the undergraduate and graduate level. 
 
-  For most of the presented approaches, we also provide links to code of short examples. This should allow readers to easily bridge the gap between theoretical aspects and practice.  These examples have been written using <a href="http://opencv.org">OpenCV</a> but also <a href="http://visp.inria.fr">ViSP</a> developed at Inria.
+For most of the presented approaches, we also provide links to code of short examples. This should allow readers to easily bridge the gap between theoretical aspects and practice.  These examples have been written using <a href="http://opencv.org">OpenCV</a> but also <a href="http://visp.inria.fr">ViSP</a> developed at Inria.
 This page contains the documentation of these documented source code   proposed as a supplementary material of the paper.
 
-
 We hope this article and source code will be accessible and interesting to experts and students alike.
 
-
-
-
 \section install_sec Installation
 
 \subsection prereq_subsec Prerequisities
@@ -54,12 +50,12 @@ Once ViSP is installed, download the lastest source code release from github <ht
 
 Unzip the archive:
 \code
-$ unzip camera_localization-1.0.0.zip
+$ unzip camera_localization-2.0.0.zip
 \endcode
 
 or extract the code from tarball:
 \code
-$ tar xvzf camera_localization-1.0.0.tar.gz
+$ tar xvzf camera_localization-2.0.0.tar.gz
 \endcode
 
 
@@ -82,27 +78,27 @@ $ make doc
 
 In this section we give base algorithm for camera localization.
 
-- <b>Pose from Direct Linear Transform method</b> \ref tutorial-pose-dlt-visp "(ViSP)"<br>In this first tutorial a simple solution known as Direct Linear Transform (DLT) \cite HZ01 \cite Sut74 based on the resolution of a linear system is considered to estimate the pose of the camera from at least 6 non coplanar points.
+- <b>Pose from Direct Linear Transform method</b> using \ref tutorial-pose-dlt-opencv "OpenCV" or using \ref tutorial-pose-dlt-visp "ViSP"<br>In this first tutorial a simple solution known as Direct Linear Transform (DLT) \cite HZ01 \cite Sut74 based on the resolution of a linear system is considered to estimate the pose of the camera from at least 6 non coplanar points.
 
-- <b>Pose from Dementhon's POSIT method</b> \ref tutorial-pose-dementhon-visp "(ViSP)"<br>In this second tutorial we give Dementhon's POSIT method \cite DD95 \cite ODD96 used to estimate the pose based on the resolution of a linear system introducing additional constraints on the rotation matrix. The pose is estimated from at least 4 non coplanar points.
+- <b>Pose from Dementhon's POSIT method</b> using \ref tutorial-pose-dementhon-opencv "OpenCV" or using \ref tutorial-pose-dementhon-visp "ViSP"<br>In this second tutorial we give Dementhon's POSIT method \cite DD95 \cite ODD96 used to estimate the pose based on the resolution of a linear system introducing additional constraints on the rotation matrix. The pose is estimated from at least 4 non coplanar points.
 
-- <b>Pose from homography estimation</b> \ref tutorial-pose-dlt-planar-visp "(ViSP)" <br>In this tutorial we explain how to decompose the homography to estimate the pose from at least 4 coplanar points.
+- <b>Pose from homography estimation</b> using \ref tutorial-pose-dlt-planar-opencv "OpenCV" or using \ref tutorial-pose-dlt-planar-visp "ViSP" <br>In this tutorial we explain how to decompose the homography to estimate the pose from at least 4 coplanar points.
 
-- <b>Pose from a non-linear minimization method</b> \ref tutorial-pose-gauss-newton-visp "(ViSP)" <br>In this other tutorial we give a non-linear minimization method to estimate the pose from at least 4 points. This method requires an initialization of the pose to estimate. Depending on the points planarity, this initialization could be performed using one of the previous pose algorithms.
+- <b>Pose from a non-linear minimization method</b> using \ref tutorial-pose-gauss-newton-opencv "OpenCV" or using \ref tutorial-pose-gauss-newton-visp "ViSP" <br>In this other tutorial we give a non-linear minimization method to estimate the pose from at least 4 points. This method requires an initialization of the pose to estimate. Depending on the points planarity, this initialization could be performed using one of the previous pose algorithms.
 
 \subsection pose_mbt_sec Extension to markerless model-based tracking
 
-- <b>Pose from markerless model-based tracking</b> \ref tutorial-pose-mbt-visp "(ViSP)" <br>This tutorial focuses on markerless model-based tracking that allows to estimate the pose of the camera.
+- <b>Pose from markerless model-based tracking</b> using \ref tutorial-pose-mbt-visp "ViSP" <br>This tutorial focuses on markerless model-based tracking that allows to estimate the pose of the camera.
 
 \section motion_estimation_sec Pose estimation relying on an image model
 
 \subsection homography_from_point_sec Homography estimation
 
-- <b>Homography estimation</b> \ref tutorial-homography-visp "(ViSP)" <br>In this tutorial we describe the estimation of an homography using Direct Linear Transform (DLT) algorithm. At least 4 coplanar points are requested to achieve the estimation.
+- <b>Homography estimation</b> using \ref tutorial-homography-opencv "OpenCV" or using \ref tutorial-homography-visp "ViSP" <br>In this tutorial we describe the estimation of an homography using Direct Linear Transform (DLT) algorithm. At least 4 coplanar points are requested to achieve the estimation.
 
 \subsection homography_from_template_tracker_sec Direct motion estimation through template matching
 
-- <b>Direct motion estimation through template matching</b> \ref tutorial-template-matching-visp "(ViSP)" <br>In this other tutorial we propose a direct motion estimation through template matching approach. Here the reference template should be planar.
+- <b>Direct motion estimation through template matching</b> using \ref tutorial-template-matching-visp "ViSP" <br>In this other tutorial we propose a direct motion estimation through template matching approach. Here the reference template should be planar.
 
 
 

doc/tutorial-homography-opencv.doc

@@ -0,0 +1,66 @@
+/**
+
+\page tutorial-homography-opencv Homography estimation
+\tableofcontents
+
+\section intro_homography_cv Introduction
+
+The estimation of an homography from coplanar points can be easily and precisely achieved using a Direct Linear Transform algorithm \cite HZ01 \cite Sut74 based on the resolution of a linear system.
+
+\section homography_code_cv Source code
+
+The following source code that uses <a href="http://opencv.org">OpenCV</a> is also available in \ref homography-dlt-opencv.cpp file. It allows to estimate the homography between matched coplanar points. At least 4 points are required.
+
+\include homography-dlt-opencv.cpp
+
+\section homography_explained_cv Source code explained
+
+First of all we inlude OpenCV headers that are requested to manipulate vectors and matrices.
+
+\snippet homography-dlt-opencv.cpp Include
+
+Then we introduce the function that does the homography estimation.
+\snippet homography-dlt-opencv.cpp Estimation function
+
+From a vector of planar points \f${\bf x_1} = (x_1, y_1, 1)^T\f$ in image \f$I_1\f$ and a vector of matched points \f${\bf x_2} = (x_2, y_2, 1)^T\f$ in image \f$I_2\f$ it allows to estimate the homography \f$\bf {^2}H_1\f$:
+
+\f[\bf x_2 = {^2}H_1 x_1\f]
+
+The implementation of the Direct Linear Transform algorithm to estimate \f$\bf {^2}H_1\f$ is done next. First, for each point we update the values of matrix A using equation (33). Then we solve the system \f${\bf Ah}=0\f$ using a Singular Value Decomposition of \f$\bf A\f$. Finaly, we determine the smallest eigen value that allows to identify the eigen vector that corresponds to the solution \f$\bf h\f$.
+
+\snippet homography-dlt-opencv.cpp DLT
+
+From now the resulting eigen vector \f$\bf h\f$ that corresponds to the minimal
+eigen value of matrix \f$\bf A\f$ is used to update the homography \f$\bf {^2}H_1\f$.
+
+\snippet homography-dlt-opencv.cpp Update homography matrix
+
+Finally we define the main function in which we will initialize the input data before calling the previous function.
+
+\snippet homography-dlt-opencv.cpp Main function
+
+First in the main we create the data structures that will contain the 3D points coordinates \e wX in the world frame, their coordinates in the camera frame 1 \e c1X and 2 \e c2X and their coordinates in the image plane \e x1 and \e x2 obtained after perspective projection. Note here that at least 4 coplanar points are requested to estimate the 8 parameters of the homography. 
+
+\snippet homography-dlt-opencv.cpp Create data structures
+
+For our simulation we then initialize the input data from a ground truth pose that corresponds to the pose of the camera in frame 1 with respect to the object frame; in \e c1tw_truth for the translation vector and in \e c1Rw_truth for the rotation matrix. 
+For each point, we compute their coordinates in the camera frame 1 \e c1X = (c1X, c1Y, c1Z). These values are then used to compute their coordinates in the image plane \e x1 = (x1, y1) using perspective projection.
+
+Thanks to the ground truth transformation between camera frame 2 and camera frame 1 set in \e c2tc1 for the translation vector and in \e c2Rc1 for the rotation matrix, we compute also the coordinates of the points in camera frame 2 \e c2X = (c2X, c2Y, c2Z) and their corresponding coordinates \e x2 = (x2, y2) in the image plane.
+\snippet homography-dlt-opencv.cpp Simulation
+
+From here we have initialized \f${\bf x_1} = (x1,y1,1)^T\f$ and \f${\bf x_2} = (x2,y2,1)^T\f$. We are now ready to call the function that does the homography estimation.
+
+\snippet homography-dlt-opencv.cpp Call function
+
+\section homography_result_cv Resulting homography estimation
+
+If you run the previous code, it we produce the following result that shows that the estimated pose is equal to the ground truth one used to generate the input data:
+
+\code
+2H1 (computed with DLT):
+[0.5425233873981674, -0.04785624324415742, 0.03308292557420141;
+ 0.0476448024215215, 0.5427592708789931, 0.005830349194436123;
+ -0.02550335176952741, -0.005978041062955012, 0.6361649706821216]
+\endcode
+*/

doc/tutorial-homography-visp.doc

@@ -9,13 +9,13 @@ The estimation of an homography from coplanar points can be easily and precisely
 
 \section homography_code Source code
 
-The following source code also available in homography-dlt-visp.cpp allows to estimate the homography between matched coplanar points. At least 4 points are required.
+The following source code that uses <a href="http://visp.inria.fr">ViSP</a> is also available in \ref homography-dlt-visp.cpp file. It allows to estimate the homography between matched coplanar points. At least 4 points are required.
 
 \include homography-dlt-visp.cpp
 
 \section homography_explained Source code explained
 
-First of all we inlude the header of the files that are requested to manipulate vectors and matrices.
+First of all we inlude ViSP headers that are requested to manipulate vectors and matrices.
 
 \snippet homography-dlt-visp.cpp Include
 
@@ -35,18 +35,18 @@ eigen value of matrix \f$\bf A\f$ is used to update the homography \f$\bf {^2}H_
 
 \snippet homography-dlt-visp.cpp Update homography matrix
 
-Finally we define the main() function in which we will initialize the input data before calling the previous function.
+Finally we define the main function in which we will initialize the input data before calling the previous function.
 
 \snippet homography-dlt-visp.cpp Main function
 
-First in the main() we create the data structures that will contain the 3D points coordinates \e wX in the world frame, their coordinates in the camera frame 1 \e c1X and 2 \e c2X and their coordinates in the image plane \e x1 and \e x2 obtained after perspective projection. Note here that at least 4 coplanar points are requested to estimate the 8 parameters of the homography. 
+First in the main we create the data structures that will contain the 3D points coordinates \e wX in the world frame, their coordinates in the camera frame 1 \e c1X and 2 \e c2X and their coordinates in the image plane \e x1 and \e x2 obtained after perspective projection. Note here that at least 4 coplanar points are requested to estimate the 8 parameters of the homography. 
 
 \snippet homography-dlt-visp.cpp Create data structures
 
 For our simulation we then initialize the input data from a ground truth pose \e c1Tw_truth that corresponds to the pose of the camera in frame 1 with respect to the object frame. 
-For each point, we compute their coordinates in the camera frame 1 (c1X, c1Y, c1Z). These values are then used to compute their coordinates in the image plane (x1, y1) using perspective projection.
+For each point, we compute their coordinates in the camera frame 1 \e c1X = (c1X, c1Y, c1Z). These values are then used to compute their coordinates in the image plane \e x1 = (x1, y1) using perspective projection.
 
-Thanks to the ground truth transformation \e c2Tc1 between camera frame 2 and camera frame 1, we compute also the coordinates of the points in camera frame 2 (c2X, c2Y, c2Z) and their corresponding coordinates (x2, y2) in the image plane.
+Thanks to the ground truth transformation \e c2Tc1 between camera frame 2 and camera frame 1, we compute also the coordinates of the points in camera frame 2 \e c2X = (c2X, c2Y, c2Z) and their corresponding coordinates \e x2 = (x2, y2) in the image plane.
 \snippet homography-dlt-visp.cpp Simulation
 
 From here we have initialized \f${\bf x_1} = (x1,y1,1)^T\f$ and \f${\bf x_2} = (x2,y2,1)^T\f$. We are now ready to call the function that does the homography estimation.

doc/tutorial-pose-dementhon-opencv.doc

@@ -0,0 +1,73 @@
+/**
+
+\page tutorial-pose-dementhon-opencv Pose from Dementhon's POSIT method
+\tableofcontents
+
+\section intro_dementhon_cv Introduction
+
+An alternative and very elegant solution to pose estimation from points has been proposed in \cite DD95 \cite ODD96. This algorithm is called POSIT.
+
+\section dementhon_code_cv Source code
+
+The following source code that uses <a href="opencv.org">OpenCV</a> is also available in \ref pose-dementhon-opencv.cpp file. It allows to compute the pose of the camera from points.
+
+\include pose-dementhon-opencv.cpp
+
+\section dementon_explained_cv Source code explained
+
+First of all we include OpenCV headers that are requested to manipulate vectors and matrices.
+
+\snippet pose-dementhon-opencv.cpp Include
+
+Then we introduce the function that does the pose estimation. It takes as input parameters \f${^w}{\bf X} = (X,Y,Z,1)^T\f$ the 3D coordinates of the points in the world frame and \f${\bf x} = (x,y,1)^T\f$ their normalized coordinates in the image plane. It returns the estimated pose in \e ctw for the translation vector and in \e cRw for the rotation matrix.
+
+\snippet pose-dementhon-opencv.cpp Estimation function
+
+The implementation of the POSIT algorithm is done next. 
+\snippet pose-dementhon-opencv.cpp POSIT
+
+After a minimal number of iterations, all the parameters are estimated and can be used to update the value of the homogenous transformation, first in \e ctw for the translation, then in \e cRw for the rotation matrix.
+
+\snippet pose-dementhon-opencv.cpp Update homogeneous matrix
+
+Finally we define the main function in which we will initialize the input data before calling the previous function and computing the pose using Dementhon POSIT algorithm.
+
+\snippet pose-dementhon-opencv.cpp Main function
+
+First in the main we create the data structures that will contain the 3D points coordinates \e wX in the world frame, and their coordinates in the image plane \e x obtained after prerspective projection. Note here that at least 4 non coplanar points are requested to estimate the pose. 
+
+\snippet pose-dementhon-opencv.cpp Create data structures
+
+For our simulation we then initialize the input data from a ground truth pose with the translation in \e ctw_truth and the rotation matrix in \e cRw_truth. 
+For each point we set in \e wX[i] the 3D coordinates in the world frame (wX, wY, wZ, 1) and compute in \e cX their 3D coordinates (cX, cY, cZ, 1) in the camera frame. Then in \e x[i] we update their coordinates (x, y) in the image plane, obtained by perspective projection.
+
+\snippet pose-dementhon-opencv.cpp Simulation
+
+From here we have initialized \f${^w}{\bf X} = (X,Y,Z,1)^T\f$ and \f${\bf x} = (x,y,1)^T\f$. We are now ready to call the function that does the pose estimation.
+
+\snippet pose-dementhon-opencv.cpp Call function
+
+\section dementhon_result_cv Resulting pose estimation
+
+If you run the previous code, it we produce the following result that shows that the estimated pose is very close to the ground truth one used to generate the input data:
+
+\code
+ctw (ground truth):
+[-0.1;
+ 0.1;
+ 0.5]
+ctw (computed with DLT):
+[-0.1070274014258891;
+ 0.1741233539654255;
+ 0.5236967119016803]
+cRw (ground truth):
+[0.7072945483755065, -0.7061704379962989, 0.03252282795827704;
+ 0.7061704379962989, 0.7036809008245869, -0.07846338199958876;
+ 0.03252282795827704, 0.07846338199958876, 0.9963863524490802]
+cRw (computed with DLT):
+[0.6172726698299887, -0.7813181606576134, 0.09228425059326956;
+ 0.6906596219977137, 0.4249461799313228, -0.5851581245302429;
+ 0.4179788297943932, 0.4249391234325819, 0.8019325685199985]
+\endcode
+
+*/