Update documentation of Tracking API

modules/tracking/include/opencv2/tracking.hpp

@@ -39,8 +39,8 @@
  //
  //M*/
 
-#ifndef __OPENCV_TRACKING_LENLEN_HPP__
-#define __OPENCV_TRACKING_LENLEN_HPP__
+#ifndef __OPENCV_TRACKING_HPP__
+#define __OPENCV_TRACKING_HPP__
 
 #include "opencv2/core/cvdef.h"
 
@@ -49,12 +49,12 @@
 Long-term optical tracking API
 ------------------------------
 
-Long-term optical tracking is one of most important issue for many computer vision applications in
+Long-term optical tracking is an important issue for many computer vision applications in
 real world scenario. The development in this area is very fragmented and this API is an unique
 interface useful for plug several algorithms and compare them. This work is partially based on
 @cite AAM and @cite AMVOT .
 
-This algorithms start from a bounding box of the target and with their internal representation they
+These algorithms start from a bounding box of the target and with their internal representation they
 avoid the drift during the tracking. These long-term trackers are able to evaluate online the
 quality of the location of the target in the new frame, without ground truth.
 
@@ -69,23 +69,16 @@ the TrackerModel is the statistical model.
 
 A recent benchmark between these algorithms can be found in @cite OOT
 
-To see how API works, try tracker demo:
-<https://github.com/lenlen/opencv/blob/tracking_api/samples/cpp/tracker.cpp>
-
-Creating Own Tracker
+Creating Your Own %Tracker
 --------------------
 
-If you want create a new tracker, here's what you have to do. First, decide on the name of the class
+If you want to create a new tracker, here's what you have to do. First, decide on the name of the class
 for the tracker (to meet the existing style, we suggest something with prefix "tracker", e.g.
-trackerMIL, trackerBoosting) -- we shall refer to this choice as to "classname" in subsequent. Also,
-you should decide upon the name of the tracker, is it will be known to user (the current style
-suggests using all capitals, say MIL or BOOSTING) --we'll call it a "name".
+trackerMIL, trackerBoosting) -- we shall refer to this choice as to "classname" in subsequent.
 
--   Declare your tracker in include/opencv2/tracking/tracker.hpp. Your tracker should inherit from
+-   Declare your tracker in modules/tracking/include/opencv2/tracking/tracker.hpp. Your tracker should inherit from
     Tracker (please, see the example below). You should declare the specialized Param structure,
-    where you probably will want to put the data, needed to initialize your tracker. Also don't
-    forget to put the BOILERPLATE_CODE(name,classname) macro inside the class declaration. That
-    macro will generate static createTracker() function, which we'll talk about later. You should
+    where you probably will want to put the data, needed to initialize your tracker. You should
     get something similar to :
 @code
         class CV_EXPORTS_W TrackerMIL : public Tracker
@@ -109,20 +102,10 @@ suggests using all capitals, say MIL or BOOSTING) --we'll call it a "name".
 @endcode
     of course, you can also add any additional methods of your choice. It should be pointed out,
     however, that it is not expected to have a constructor declared, as creation should be done via
-    the corresponding createTracker() method.
--   In src/tracker.cpp file add BOILERPLATE_CODE(name,classname) line to the body of
-    Tracker::create() method you will find there, like :
-@code
-        Ptr<Tracker> Tracker::create( const String& trackerType )
-        {
-          BOILERPLATE_CODE("BOOSTING",TrackerBoosting);
-          BOILERPLATE_CODE("MIL",TrackerMIL);
-          return Ptr<Tracker>();
-        }
-@endcode
+    the corresponding create() method.
 -   Finally, you should implement the function with signature :
 @code
-        Ptr<classname> classname::createTracker(const classname::Params &parameters){
+        Ptr<classname> classname::create(const classname::Params &parameters){
             ...
         }
 @endcode
@@ -292,16 +275,10 @@ Example of creating specialized TrackerTargetState TrackerMILTargetState : :
 
     };
 @endcode
-### Try it
-
-To try your tracker you can use the demo at
-<https://github.com/lenlen/opencv/blob/tracking_api/samples/cpp/tracker.cpp>.
-
-The first argument is the name of the tracker and the second is a video source.
 
 */
 
 #include <opencv2/tracking/tracker.hpp>
 #include <opencv2/tracking/tldDataset.hpp>
 
-#endif //__OPENCV_TRACKING_LENLEN
+#endif //__OPENCV_TRACKING_HPP__

modules/tracking/include/opencv2/tracking/tracker.hpp

@@ -1091,8 +1091,9 @@ class CV_EXPORTS_W TrackerMIL : public Tracker
   virtual ~TrackerMIL() CV_OVERRIDE {}
 };
 
-/** @brief This is a real-time object tracking based on a novel on-line version of the AdaBoost algorithm.
+/** @brief the Boosting tracker
 
+This is a real-time object tracking based on a novel on-line version of the AdaBoost algorithm.
 The classifier uses the surrounding background as negative examples in update step to avoid the
 drifting problem. The implementation is based on @cite OLB .
  */
@@ -1128,7 +1129,7 @@ class CV_EXPORTS_W TrackerBoosting : public Tracker
   virtual ~TrackerBoosting() CV_OVERRIDE {}
 };
 
-/** @brief Median Flow tracker implementation.
+/** @brief the Median Flow tracker
 
 Implementation of a paper @cite MedianFlow .
 
@@ -1167,7 +1168,9 @@ class CV_EXPORTS_W TrackerMedianFlow : public Tracker
   virtual ~TrackerMedianFlow() CV_OVERRIDE {}
 };
 
-/** @brief TLD is a novel tracking framework that explicitly decomposes the long-term tracking task into
+/** @brief the TLD (Tracking, learning and detection) tracker
+
+TLD is a novel tracking framework that explicitly decomposes the long-term tracking task into
 tracking, learning and detection.
 
 The tracker follows the object from frame to frame. The detector localizes all appearances that
@@ -1175,7 +1178,7 @@ have been observed so far and corrects the tracker if necessary. The learning es
 errors and updates it to avoid these errors in the future. The implementation is based on @cite TLD .
 
 The Median Flow algorithm (see cv::TrackerMedianFlow) was chosen as a tracking component in this
-implementation, following authors. Tracker is supposed to be able to handle rapid motions, partial
+implementation, following authors. The tracker is supposed to be able to handle rapid motions, partial
 occlusions, object absence etc.
  */
 class CV_EXPORTS_W TrackerTLD : public Tracker
@@ -1198,7 +1201,9 @@ class CV_EXPORTS_W TrackerTLD : public Tracker
   virtual ~TrackerTLD() CV_OVERRIDE {}
 };
 
-/** @brief KCF is a novel tracking framework that utilizes properties of circulant matrix to enhance the processing speed.
+/** @brief the KCF (Kernelized Correlation Filter) tracker
+
+ * KCF is a novel tracking framework that utilizes properties of circulant matrix to enhance the processing speed.
  * This tracking method is an implementation of @cite KCF_ECCV which is extended to KCF with color-names features (@cite KCF_CN).
  * The original paper of KCF is available at <http://www.robots.ox.ac.uk/~joao/publications/henriques_tpami2015.pdf>
  * as well as the matlab implementation. For more information about KCF with color-names features, please refer to
@@ -1264,7 +1269,9 @@ public:
   virtual ~TrackerKCF() CV_OVERRIDE {}
 };
 
-/** @brief GOTURN (@cite GOTURN) is kind of trackers based on Convolutional Neural Networks (CNN). While taking all advantages of CNN trackers,
+/** @brief the GOTURN (Generic Object Tracking Using Regression Networks) tracker
+
+ *  GOTURN (@cite GOTURN) is kind of trackers based on Convolutional Neural Networks (CNN). While taking all advantages of CNN trackers,
  *  GOTURN is much faster due to offline training without online fine-tuning nature.
  *  GOTURN tracker addresses the problem of single target tracking: given a bounding box label of an object in the first frame of the video,
  *  we track that object through the rest of the video. NOTE: Current method of GOTURN does not handle occlusions; however, it is fairly
@@ -1297,9 +1304,10 @@ public:
   virtual ~TrackerGOTURN() CV_OVERRIDE {}
 };
 
-/** @brief the MOSSE tracker
-note, that this tracker works with grayscale images, if passed bgr ones, they will get converted internally.
-@cite MOSSE Visual Object Tracking using Adaptive Correlation Filters
+/** @brief the MOSSE (Minimum Output Sum of Squared %Error) tracker
+
+The implementation is based on @cite MOSSE Visual Object Tracking using Adaptive Correlation Filters
+@note this tracker works with grayscale images, if passed bgr ones, they will get converted internally.
 */
 
 class CV_EXPORTS_W TrackerMOSSE : public Tracker
@@ -1315,7 +1323,8 @@ class CV_EXPORTS_W TrackerMOSSE : public Tracker
 
 /************************************ MultiTracker Class ---By Laksono Kurnianggoro---) ************************************/
 /** @brief This class is used to track multiple objects using the specified tracker algorithm.
-* The MultiTracker is naive implementation of multiple object tracking.
+
+* The %MultiTracker is naive implementation of multiple object tracking.
 * It process the tracked objects independently without any optimization accross the tracked objects.
 */
 class CV_EXPORTS_W MultiTracker : public Algorithm
@@ -1431,7 +1440,9 @@ public:
   std::vector<Scalar> colors;
 };
 
-/** @brief Multi Object Tracker for TLD. TLD is a novel tracking framework that explicitly decomposes
+/** @brief Multi Object %Tracker for TLD.
+
+TLD is a novel tracking framework that explicitly decomposes
 the long-term tracking task into tracking, learning and detection.
 
 The tracker follows the object from frame to frame. The detector localizes all appearances that
@@ -1439,7 +1450,7 @@ have been observed so far and corrects the tracker if necessary. The learning es
 errors and updates it to avoid these errors in the future. The implementation is based on @cite TLD .
 
 The Median Flow algorithm (see cv::TrackerMedianFlow) was chosen as a tracking component in this
-implementation, following authors. Tracker is supposed to be able to handle rapid motions, partial
+implementation, following authors. The tracker is supposed to be able to handle rapid motions, partial
 occlusions, object absence etc.
 
 @sa Tracker, MultiTracker, TrackerTLD
@@ -1460,10 +1471,10 @@ public:
   bool update_opt(InputArray image);
 };
 
-//! @}
-
 /*********************************** CSRT ************************************/
-/** @brief Discriminative Correlation Filter Tracker with Channel and Spatial Reliability
+/** @brief the CSRT tracker
+
+The implementation is based on @cite Lukezic_IJCV2018 Discriminative Correlation Filter with Channel and Spatial Reliability
 */
 class CV_EXPORTS_W TrackerCSRT : public Tracker
 {
@@ -1476,12 +1487,12 @@ public:
     Params();
 
     /**
-    * \brief Read parameters from file
+    * \brief Read parameters from a file
     */
     void read(const FileNode& /*fn*/);
 
     /**
-    * \brief Write parameters from file
+    * \brief Write parameters to a file
     */
     void write(cv::FileStorage& fs) const;
 
@@ -1529,6 +1540,7 @@ public:
   virtual ~TrackerCSRT() CV_OVERRIDE {}
 };
 
+//! @}
 } /* namespace cv */
 
 #endif