Doxygen documentation for all modules

modules/optflow/doc/optflow.bib

@@ -0,0 +1,39 @@
+@article{Bradski00,
+  title={Motion segmentation and pose recognition with motion history gradients},
+  author={Bradski, Gary R and Davis, James W},
+  journal={Machine Vision and Applications},
+  volume={13},
+  number={3},
+  pages={174--184},
+  year={2002},
+  publisher={Springer}
+}
+
+@inproceedings{Davis97,
+  title={The representation and recognition of human movement using temporal templates},
+  author={Davis, James W and Bobick, Aaron F},
+  booktitle={Computer Vision and Pattern Recognition, 1997. Proceedings., 1997 IEEE Computer Society Conference on},
+  pages={928--934},
+  year={1997},
+  organization={IEEE}
+}
+
+@inproceedings{Tao2012,
+  title={SimpleFlow: A Non-iterative, Sublinear Optical Flow Algorithm},
+  author={Tao, Michael and Bai, Jiamin and Kohli, Pushmeet and Paris, Sylvain},
+  booktitle={Computer Graphics Forum},
+  volume={31},
+  number={2pt1},
+  pages={345--353},
+  year={2012},
+  organization={Wiley Online Library}
+}
+
+@inproceedings{Weinzaepfel2013,
+  title={DeepFlow: Large displacement optical flow with deep matching},
+  author={Weinzaepfel, Philippe and Revaud, Jerome and Harchaoui, Zaid and Schmid, Cordelia},
+  booktitle={Computer Vision (ICCV), 2013 IEEE International Conference on},
+  pages={1385--1392},
+  year={2013},
+  organization={IEEE}
+}

modules/optflow/include/opencv2/optflow.hpp

@@ -43,15 +43,67 @@ the use of this software, even if advised of the possibility of such damage.
 #include "opencv2/core.hpp"
 #include "opencv2/video.hpp"
 
+/**
+@defgroup optflow Optical Flow Algorithms
+
+Dense optical flow algorithms compute motion for each point:
+
+- cv::optflow::calcOpticalFlowSF
+- cv::optflow::createOptFlow_DeepFlow
+
+Motion templates is alternative technique for detecting motion and computing its direction.
+See samples/motempl.py.
+
+- cv::motempl::updateMotionHistory
+- cv::motempl::calcMotionGradient
+- cv::motempl::calcGlobalOrientation
+- cv::motempl::segmentMotion
+
+Functions reading and writing .flo files in "Middlebury" format, see: <http://vision.middlebury.edu/flow/code/flow-code/README.txt>
+
+- cv::optflow::readOpticalFlow
+- cv::optflow::writeOpticalFlow
+
+ */
+
 namespace cv
 {
 namespace optflow
 {
     
-//! computes dense optical flow using Simple Flow algorithm
+//! @addtogroup optflow
+//! @{
+
+/** @overload */
 CV_EXPORTS_W void calcOpticalFlowSF( InputArray from, InputArray to, OutputArray flow,
                                      int layers, int averaging_block_size, int max_flow);
 
+/** @brief Calculate an optical flow using "SimpleFlow" algorithm.
+
+@param from First 8-bit 3-channel image.
+@param to Second 8-bit 3-channel image of the same size as prev
+@param flow computed flow image that has the same size as prev and type CV_32FC2
+@param layers Number of layers
+@param averaging_block_size Size of block through which we sum up when calculate cost function
+for pixel
+@param max_flow maximal flow that we search at each level
+@param sigma_dist vector smooth spatial sigma parameter
+@param sigma_color vector smooth color sigma parameter
+@param postprocess_window window size for postprocess cross bilateral filter
+@param sigma_dist_fix spatial sigma for postprocess cross bilateralf filter
+@param sigma_color_fix color sigma for postprocess cross bilateral filter
+@param occ_thr threshold for detecting occlusions
+@param upscale_averaging_radius window size for bilateral upscale operation
+@param upscale_sigma_dist spatial sigma for bilateral upscale operation
+@param upscale_sigma_color color sigma for bilateral upscale operation
+@param speed_up_thr threshold to detect point with irregular flow - where flow should be
+recalculated after upscale
+
+See @cite Tao2012. And site of project - <http://graphics.berkeley.edu/papers/Tao-SAN-2012-05/>.
+
+@note
+   -   An example using the simpleFlow algorithm can be found at samples/simpleflow_demo.cpp
+ */
 CV_EXPORTS_W void calcOpticalFlowSF( InputArray from, InputArray to, OutputArray flow, int layers,
                                      int averaging_block_size, int max_flow,
                                      double sigma_dist, double sigma_color, int postprocess_window,
@@ -59,24 +111,62 @@ CV_EXPORTS_W void calcOpticalFlowSF( InputArray from, InputArray to, OutputArray
                                      int upscale_averaging_radius, double upscale_sigma_dist,
                                      double upscale_sigma_color, double speed_up_thr );    
 
-//! reads optical flow from a file, Middlebury format:
-// http://vision.middlebury.edu/flow/code/flow-code/README.txt
+/** @brief Read a .flo file
+
+@param path Path to the file to be loaded
+
+The function readOpticalFlow loads a flow field from a file and returns it as a single matrix.
+Resulting Mat has a type CV_32FC2 - floating-point, 2-channel. First channel corresponds to the
+flow in the horizontal direction (u), second - vertical (v).
+ */
 CV_EXPORTS_W Mat readOpticalFlow( const String& path );
-//! writes optical flow to a file, Middlebury format
+/** @brief Write a .flo to disk
+
+@param path Path to the file to be written
+@param flow Flow field to be stored
+
+The function stores a flow field in a file, returns true on success, false otherwise.
+The flow field must be a 2-channel, floating-point matrix (CV_32FC2). First channel corresponds
+to the flow in the horizontal direction (u), second - vertical (v).
+ */
 CV_EXPORTS_W bool writeOpticalFlow( const String& path, InputArray flow );
 
 
+/** @brief DeepFlow optical flow algorithm implementation.
 
-
-// DeepFlow implementation, based on:
-//   P. Weinzaepfel, J. Revaud, Z. Harchaoui, and C. Schmid, “DeepFlow: Large Displacement Optical Flow with Deep Matching,”
+The class implements the DeepFlow optical flow algorithm described in @cite Weinzaepfel2013 . See
+also <http://lear.inrialpes.fr/src/deepmatching/> .
+Parameters - class fields - that may be modified after creating a class instance:
+-   member float alpha
+Smoothness assumption weight
+-   member float delta
+Color constancy assumption weight
+-   member float gamma
+Gradient constancy weight
+-   member float sigma
+Gaussian smoothing parameter
+-   member int minSize
+Minimal dimension of an image in the pyramid (next, smaller images in the pyramid are generated
+until one of the dimensions reaches this size)
+-   member float downscaleFactor
+Scaling factor in the image pyramid (must be \< 1)
+-   member int fixedPointIterations
+How many iterations on each level of the pyramid
+-   member int sorIterations
+Iterations of Succesive Over-Relaxation (solver)
+-   member float omega
+Relaxation factor in SOR
+ */
 CV_EXPORTS_W Ptr<DenseOpticalFlow> createOptFlow_DeepFlow();
 
-// Additional interface to the SimpleFlow algorithm - calcOpticalFlowSF()
+//! Additional interface to the SimpleFlow algorithm - calcOpticalFlowSF()
 CV_EXPORTS_W Ptr<DenseOpticalFlow> createOptFlow_SimpleFlow();
 
-// Additional interface to the Farneback's algorithm - calcOpticalFlowFarneback()
+//! Additional interface to the Farneback's algorithm - calcOpticalFlowFarneback()
 CV_EXPORTS_W Ptr<DenseOpticalFlow> createOptFlow_Farneback();
+
+//! @}
+
 } //optflow
 }
 

modules/optflow/include/opencv2/optflow/motempl.hpp

@@ -47,22 +47,100 @@ namespace cv
 namespace motempl
 {
 
-//! updates motion history image using the current silhouette
+//! @addtogroup optflow
+//! @{
+
+/** @brief Updates the motion history image by a moving silhouette.
+
+@param silhouette Silhouette mask that has non-zero pixels where the motion occurs.
+@param mhi Motion history image that is updated by the function (single-channel, 32-bit
+floating-point).
+@param timestamp Current time in milliseconds or other units.
+@param duration Maximal duration of the motion track in the same units as timestamp .
+
+The function updates the motion history image as follows:
+
+\f[\texttt{mhi} (x,y)= \forkthree{\texttt{timestamp}}{if \(\texttt{silhouette}(x,y) \ne 0\)}{0}{if \(\texttt{silhouette}(x,y) = 0\) and \(\texttt{mhi} < (\texttt{timestamp} - \texttt{duration})\)}{\texttt{mhi}(x,y)}{otherwise}\f]
+
+That is, MHI pixels where the motion occurs are set to the current timestamp , while the pixels
+where the motion happened last time a long time ago are cleared.
+
+The function, together with calcMotionGradient and calcGlobalOrientation , implements a motion
+templates technique described in @cite Davis97 and @cite Bradski00.
+ */
 CV_EXPORTS_W void updateMotionHistory( InputArray silhouette, InputOutputArray mhi,
                                        double timestamp, double duration );
 
-//! computes the motion gradient orientation image from the motion history image
+/** @brief Calculates a gradient orientation of a motion history image.
+
+@param mhi Motion history single-channel floating-point image.
+@param mask Output mask image that has the type CV_8UC1 and the same size as mhi . Its non-zero
+elements mark pixels where the motion gradient data is correct.
+@param orientation Output motion gradient orientation image that has the same type and the same
+size as mhi . Each pixel of the image is a motion orientation, from 0 to 360 degrees.
+@param delta1 Minimal (or maximal) allowed difference between mhi values within a pixel
+neighborhood.
+@param delta2 Maximal (or minimal) allowed difference between mhi values within a pixel
+neighborhood. That is, the function finds the minimum ( \f$m(x,y)\f$ ) and maximum ( \f$M(x,y)\f$ ) mhi
+values over \f$3 \times 3\f$ neighborhood of each pixel and marks the motion orientation at \f$(x, y)\f$
+as valid only if
+\f[\min ( \texttt{delta1}  ,  \texttt{delta2}  )  \le  M(x,y)-m(x,y)  \le   \max ( \texttt{delta1}  , \texttt{delta2} ).\f]
+@param apertureSize Aperture size of the Sobel operator.
+
+The function calculates a gradient orientation at each pixel \f$(x, y)\f$ as:
+
+\f[\texttt{orientation} (x,y)= \arctan{\frac{d\texttt{mhi}/dy}{d\texttt{mhi}/dx}}\f]
+
+In fact, fastAtan2 and phase are used so that the computed angle is measured in degrees and covers
+the full range 0..360. Also, the mask is filled to indicate pixels where the computed angle is
+valid.
+
+@note
+   -   (Python) An example on how to perform a motion template technique can be found at
+        opencv_source_code/samples/python2/motempl.py
+ */
 CV_EXPORTS_W void calcMotionGradient( InputArray mhi, OutputArray mask, OutputArray orientation,
                                       double delta1, double delta2, int apertureSize = 3 );
 
-//! computes the global orientation of the selected motion history image part
+/** @brief Calculates a global motion orientation in a selected region.
+
+@param orientation Motion gradient orientation image calculated by the function calcMotionGradient
+@param mask Mask image. It may be a conjunction of a valid gradient mask, also calculated by
+calcMotionGradient , and the mask of a region whose direction needs to be calculated.
+@param mhi Motion history image calculated by updateMotionHistory .
+@param timestamp Timestamp passed to updateMotionHistory .
+@param duration Maximum duration of a motion track in milliseconds, passed to updateMotionHistory
+
+The function calculates an average motion direction in the selected region and returns the angle
+between 0 degrees and 360 degrees. The average direction is computed from the weighted orientation
+histogram, where a recent motion has a larger weight and the motion occurred in the past has a
+smaller weight, as recorded in mhi .
+ */
 CV_EXPORTS_W double calcGlobalOrientation( InputArray orientation, InputArray mask, InputArray mhi,
                                            double timestamp, double duration );
 
+/** @brief Splits a motion history image into a few parts corresponding to separate independent motions (for
+example, left hand, right hand).
+
+@param mhi Motion history image.
+@param segmask Image where the found mask should be stored, single-channel, 32-bit floating-point.
+@param boundingRects Vector containing ROIs of motion connected components.
+@param timestamp Current time in milliseconds or other units.
+@param segThresh Segmentation threshold that is recommended to be equal to the interval between
+motion history "steps" or greater.
+
+The function finds all of the motion segments and marks them in segmask with individual values
+(1,2,...). It also computes a vector with ROIs of motion connected components. After that the motion
+direction for every component can be calculated with calcGlobalOrientation using the extracted mask
+of the particular component.
+ */
 CV_EXPORTS_W void segmentMotion( InputArray mhi, OutputArray segmask,
                                  CV_OUT std::vector<Rect>& boundingRects,
                                  double timestamp, double segThresh );
                                  
+
+//! @}
+
 }
 }