update tutorial and doxygen

upload an example data in tutorial

modules/ccalib/include/opencv2/omnidir.hpp

@@ -50,8 +50,42 @@
 namespace cv
 {
 
-/* @defgroup calib3d_omnidir Omnidirectional camera model
+/* @defgroup calib3d_omnidir Omnidirectional camera model\
 
+    Here is a brief description of implenmented omnidirectional camera model. This model can be
+    used for both catadioptric and fisheye cameras. Especially, catadioptric cameras have very
+    large field of view (FOV), i.e., a 360 degrees of horizontal FOV, means the scene around the
+    camera can be all taken in a singel photo. Compared with perspective cameras, omnidirectional
+    cameras get more information in a single shot and avoid things like image stitching.
+
+    The large FOV of omnidirectional cameras also introduces large distortion, so that it is
+    not vivid for human's eye. Rectification that removes distortion is also included in this module.
+
+    For a 3D point Xw in world coordinate, it is first transformed to camera coordinate:
+
+    \f[X_c = R X_w + T \f]
+
+    where R and T are rotation and translation matrix. Then \f$ X_c \f$ is then projected to unit sphere:
+
+    \f[ X_s = \frac{Xc}{||Xc||}  \f]
+
+    Let \f$ X_s = (x, y, z) \f$, then \f$ X_s \f$ is projected to normalized plane:
+
+    \f[ (x_u, y_u, 1) = (\frac{x}{z + \xi}, \frac{y}{z + \xi}, 1) \f]
+
+    where \f$ \xi \f$ is a parameter of camera. So far the point contains no distortion, add distortion by
+
+    \f[ x_d = (1 + k_1 r^2 + k_2 r^4 )*x_u + 2p_1 x_u y_u + p_2(r^2 + 2x_u^2 )  \\
+        y_d = (1 + k_1 r^2 + k_2 r^4 )*y_u + p_1 (r^2 + 2y_u^2) + 2p_2 x_u y_u \f]
+
+    where \f$ r^2 = x_u^2 + y_u^2\f$ and \f$(k_1, k_2, p_1, p_2)\f$ are distortion coefficients.
+
+    At last, convert to pixel coordinates:
+
+    \f[ u = f_x x_d + s y_d + c_x \\
+        v = f_y y_d + c_y \f]
+
+    where \f$ s\f$ is the skew coefficient and \f$ (cx, cy\f$ are image centers.
 */
 /** @brief The methods in this namespace is to calibrate omnidirectional cameras.
     This module was accepted as a GSoC 2015 project for OpenCV, authored by

modules/ccalib/tutorial/omnidir_tutorial.markdown

@@ -5,6 +5,8 @@ This module includes calibration, rectification and stereo reconstruction of omn
 
 *C. Mei and P. Rives, Single view point omnidirectional camera calibration from planar grids, in ICRA 2007.*
 
+The model is capable of describing catadioptric cameras, which may have 360 degrees of field of view. Also, it can be used for fisheye cameras.
+
 The implementation of the calibration part is based on Li's calibration toolbox:
 
 *B. Li, L. Heng, K. Kevin and M. Pollefeys, "A Multiple-Camera System Calibration Toolbox Using A Feature Descriptor-Based Calibration Pattern", in IROS 2013.*
@@ -15,6 +17,7 @@ This tutorial will introduce the following parts of omnidirectional camera calib
 -    calibrate a system with multiple cameras.
 -    rectify images so that large distoration is removed.
 -    reconstruct 3D from two stereo images, with large filed of view.
+-    comparison with fisheye model in opencv/calib3d/
 
 Single Camera Calibration
 ---------------------
@@ -23,10 +26,21 @@ The first step to calibrate camera is to get a calibration object and take some
 
 Next extract checkerboard corners and get their positions in all images by Opencv function *findChessboardCorners* or by hand (if you do want to make sure that corners are perfectly extracted). Save the positions in images in imagePoints, with vector of Mat type of CV_64FC2. That is, you get a 1XN or NX1 CV_64FC2 mat for each image, N is the number of corners. Then set the world coordinate to one of the four extreme corners and set xy plane as the checkerboard plane so that the position of checkerboard corners in world frame can be determined. Save the points in world coordiante in objectPoints, with vector of Mat type of CV_64FC3. Each element in vector objectPoints and imagePoints must come from the same image.
 
-Now run the calibration function like:
+In the folder *data*, the file *omni_calib_data.xml* stores an example of objectPoints, imagePoints and imageSize. Use the following code to load them:
+
+@code{.cpp}
+cv::FileStorage fs("omni_calib_data.xml", cv::FileStorage::READ);
+std::vector<cv::Mat> objectPoints, imagePoints;
+cv::Size imgSize;
+fs["objectPoints"] >> objectPoints;
+fs["imagePoints"] >> imagePoints;
+fs["imageSize"] >> imgSize;
+@endcode
+
+Then run the calibration function like:
 
 @code{.cpp}
-omnidir::calibrate(objectPoints, imagePoints, size, K, xi, D, om, t, flags, critia)
+double rms = omnidir::calibrate(objectPoints, imagePoints, size, K, xi, D, om, t, flags, critia)
 @endcode
 
 The variable *size* of tyep Size is the size of images. *flags* is a enumeration for some features, including:
@@ -34,9 +48,9 @@ The variable *size* of tyep Size is the size of images. *flags* is a enumeration
 -    CALIB_USE_GUESS: initialize camera parameters by input K, xi, D, om, t.
 -    CALIB_FIX_SKEW, CALIB_FIX_K1, CALIB_FIX_K2, CALIB_FIX_P1, CALIB_FIX_P2, CALIB_FIX_XI, CALIB_FIX_GAMMA, CALIB_FIX_CENTER: fix the corresponding parameters during calibration, you can use 'plus' operator to set multiple features. For example, CALIB_FIX_SKEW+CALIB_FIX_K1 means fix skew and K1.
 
-K, xi, D, om, t are output internal and external parameters.
+*K*, *xi*, *D*, *om*, *t* are output internal and external parameters. The returned value *rms* is the root mean square of reprojection errors.
 
-critia is the stopping critia during optimization, set it to be, for example, cv::TermCriteria(cv::TermCriteria::COUNT + cv::TermCriteria::EPS, 200, 0.0001);
+critia is the stopping critia during optimization, set it to be, for example, cv::TermCriteria(cv::TermCriteria::COUNT + cv::TermCriteria::EPS, 200, 0.0001), which means using 200 iterations and stopping when relative change is smaller than 0.0001.
 
 Image Rectificaiton
 ---------------------------