Merge pull request #109 from lenlen/tld_test_and_doc_update

Tracking API doc update and test-perftest TLD tracker

modules/tracking/doc/misc/Tracker.txt

@@ -1,43 +0,0 @@
-@startuml
-package "Tracker package" #DDDDDD {
-
-
-
-
-class Algorithm {
-}
-class Tracker{
-    Ptr<TrackerFeatureSet> featureSet;
-    Ptr<TrackerSampler> sampler;
-    Ptr<TrackerModel> model;
-    ---
-    +static Ptr<Tracker> create(const string& trackerType);
-    +bool init(const Mat& image, const Rect& boundingBox);
-    +bool update(const Mat& image, Rect& boundingBox);
-}
-class Tracker
-note right: Tracker is the general interface for each specialized trackers
-class TrackerMIL{
-    +Params
-    ---
-    TrackerMIL(TrackerMIL::Params parameters);
-    +bool init(const Mat& image, const Rect& boundingBox);
-    +bool update(const Mat& image, Rect& boundingBox);
-}
-class TrackerBoosting{
-    +Params
-    ---
-    TrackerBoosting(TrackerBoosting::Params parameters);
-    +bool init(const Mat& image, const Rect& boundingBox);
-    +bool update(const Mat& image, Rect& boundingBox);
-}
-Algorithm <|-- Tracker : virtual inheritance
-Tracker <|-- TrackerMIL
-Tracker <|-- TrackerBoosting
-
-note "Single instance of the Tracker" as N1
-TrackerBoosting .. N1
-TrackerMIL .. N1
-}
-
-@enduml

modules/tracking/doc/misc/packages.txt

@@ -1,19 +0,0 @@
-@startuml
-package "Tracker" #DDDDDD {
-
-}
-package "TrackerFeature" #DDDDDD {
-
-}
-package "TrackerSampler" #DDDDDD {
-
-}
-package "TrackerModel" #DDDDDD {
-
-}
-Tracker -> TrackerModel: create
-Tracker -> TrackerSampler: create
-Tracker -> TrackerFeature: create
-
-
-@enduml

modules/tracking/doc/tracking.rst

@@ -21,49 +21,25 @@ The TrackerSampler and the TrackerFeatureSet are the visual representation of th
 
 A recent benchmark between these algorithms can be found in [OOT]_.
 
+.. only:: plantuml
+
   UML design:
   -----------
 
-**General diagram**
+  .. toctree::
-
-.. image:: pics/package.png
-   :width: 50%
-   :alt: General diagram
-   :align: center
-
-**Tracker diagram**
-
-.. image:: pics/Tracker.png
-   :width: 80%
-   :alt: Tracker diagram
-   :align: center
-
-**TrackerSampler diagram**
-
-.. image:: pics/TrackerSampler.png
-   :width: 100%
-   :alt: TrackerSampler diagram
-   :align: center
-
-**TrackerFeatureSet diagram**
-
-.. image:: pics/TrackerFeature.png
-   :width: 100%
-   :alt: TrackerFeatureSet diagram
-   :align: center
 
-**TrackerModel diagram**
+    uml/package
+    uml/Tracker
+    uml/TrackerSampler
+    uml/TrackerFeature
+    uml/TrackerModel
 
-.. image:: pics/TrackerModel.png
-   :width: 100%
-   :alt: TrackerModel diagram
-   :align: center
 
 To see how API works, try tracker demo:
 https://github.com/lenlen/opencv/blob/tracking_api/samples/cpp/tracker.cpp
 
 
-.. note:: This Tracking API has been designed with PlantUML. If you modify this API please change UML files under modules/tracking/misc/
+.. note:: This Tracking API has been designed with PlantUML. If you modify this API please change UML files under modules/tracking/doc/uml/
 
 The following reference was used in the API
 

modules/tracking/doc/uml/Tracker.rst

@@ -0,0 +1,40 @@
+Tracker diagram
+===============
+
+.. uml::
+
+  ..@startuml
+  package "Tracker package" #DDDDDD {
+
+
+  class Algorithm
+
+  class Tracker{
+    Ptr<TrackerFeatureSet> featureSet;
+    Ptr<TrackerSampler> sampler;
+    Ptr<TrackerModel> model;
+    ---
+    +static Ptr<Tracker> create(const string& trackerType);
+    +bool init(const Mat& image, const Rect& boundingBox);
+    +bool update(const Mat& image, Rect& boundingBox);
+  }
+  class Tracker
+  note right: Tracker is the general interface for each specialized trackers
+  class TrackerMIL{
+    +static Ptr<TrackerMIL> createTracker(const TrackerMIL::Params &parameters);
+      +virtual ~TrackerMIL();
+  }
+  class TrackerBoosting{
+    +static Ptr<TrackerBoosting> createTracker(const TrackerBoosting::Params &parameters);
+      +virtual ~TrackerBoosting();
+  }
+  Algorithm <|-- Tracker : virtual inheritance
+  Tracker <|-- TrackerMIL
+  Tracker <|-- TrackerBoosting
+
+  note "Single instance of the Tracker" as N1
+  TrackerBoosting .. N1
+  TrackerMIL .. N1
+  }
+
+  ..@enduml

modules/tracking/doc/uml/TrackerFeature.rst

@@ -1,4 +1,9 @@
-@startuml
+TrackerFeatureSet diagram
+=========================
+
+.. uml::
+
+  ..@startuml
   package "TrackerFeature package" #DDDDDD {
 
   class TrackerFeatureSet{
@@ -52,4 +57,4 @@ TrackerFeatureHOG .. N1
   TrackerFeatureFeature2D .. N1
   }
 
-@enduml
+  ..@enduml

modules/tracking/doc/uml/TrackerModel.rst

@@ -1,4 +1,9 @@
-@startuml
+TrackerModel diagram
+====================
+
+.. uml::
+
+  ..@startuml
   package "TrackerModel package" #DDDDDD {
 
   class Typedef << (T,#FF7700) >>{
@@ -32,7 +37,7 @@ class TrackerTargetState <<virtual>>{
     void setTargetPosition(Point2f position);
   }
   class TrackerTargetState
-note bottom: Each TrackerStateEstimator can create own state
+  note bottom: Each tracker can create own state
 
   class TrackerStateEstimator <<virtual>>{
     ~TrackerStateEstimator();
@@ -59,4 +64,4 @@ TrackerModel *-- TrackerTargetState
   TrackerStateEstimator <|-- TrackerStateEstimatorMILBoosting
   TrackerStateEstimator <|-- TrackerStateEstimatorSVM
   }
-@enduml
+  ..@enduml

modules/tracking/doc/uml/TrackerSampler.rst

@@ -1,4 +1,9 @@
-@startuml
+TrackerSampler diagram
+======================
+
+.. uml::
+
+  ..@startuml
   package "TrackerSampler package" #DDDDDD {
 
   class TrackerSampler{
@@ -36,9 +41,5 @@ class TrackerSamplerCSC{
   }
 
 
-
-TrackerSampler *-- TrackerSamplerAlgorithm
-TrackerSamplerAlgorithm <|-- TrackerSamplerCS
-TrackerSamplerAlgorithm <|-- TrackerSamplerCSC
   }
-@enduml
+  ..@enduml

modules/tracking/doc/uml/package.rst

@@ -0,0 +1,15 @@
+General diagram
+===============
+
+.. uml::
+
+  ..@startuml
+  package "Tracker"
+  package "TrackerFeature"
+  package "TrackerSampler"
+  package "TrackerModel"
+
+  Tracker -> TrackerModel: create
+  Tracker -> TrackerSampler: create
+  Tracker -> TrackerFeature: create
+  ..@enduml

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

@@ -59,7 +59,7 @@
  * 	- [AAM] S. Salti, A. Cavallaro, L. Di Stefano, Adaptive Appearance Modeling for Video Tracking: Survey and Evaluation
  *  - [AMVOT] X. Li, W. Hu, C. Shen, Z. Zhang, A. Dick, A. van den Hengel, A Survey of Appearance Models in Visual Object Tracking
  *
- * This Tracking API has been designed with PlantUML. If you modify this API please change UML files under modules/tracking/misc/
+ * This Tracking API has been designed with PlantUML. If you modify this API please change UML files under modules/tracking/doc/uml
  *
  */
 

modules/tracking/perf/perf_Tracker.cpp

@@ -273,3 +273,73 @@ PERF_TEST_P(tracking, boosting, testing::Combine(TESTSET_NAMES, SEGMENTS))
   SANITY_CHECK( bbs_mat, 15, ERROR_RELATIVE );
 
 }
+
+PERF_TEST_P(tracking, tld, testing::Combine(TESTSET_NAMES, SEGMENTS))
+{
+  string video = get<0>( GetParam() );
+  int segmentId = get<1>( GetParam() );
+
+  int startFrame;
+  string prefix;
+  string suffix;
+  string datasetMeta = getDataPath( TRACKING_DIR + "/" + video + "/" + video + ".yml" );
+  checkData( datasetMeta, startFrame, prefix, suffix );
+  int gtStartFrame = startFrame;
+
+  vector<Rect> gtBBs;
+  string gtFile = getDataPath( TRACKING_DIR + "/" + video + "/gt.txt" );
+  if( !getGroundTruth( gtFile, gtBBs ) )
+    FAIL()<< "Ground truth file " << gtFile << " can not be read" << endl;
+  int bbCounter = (int)gtBBs.size();
+
+  Mat frame;
+  bool initialized = false;
+  vector<Rect> bbs;
+
+  Ptr<Tracker> tracker = Tracker::create( "TLD" );
+  string folder = TRACKING_DIR + "/" + video + "/" + FOLDER_IMG;
+  int numSegments = ( sizeof ( SEGMENTS)/sizeof(int) );
+  int endFrame = 0;
+  getSegment( segmentId, numSegments, bbCounter, startFrame, endFrame );
+
+  Rect currentBBi = gtBBs[startFrame - gtStartFrame];
+  Rect2d currentBB(currentBBi);
+
+  TEST_CYCLE_N(1)
+  {
+    VideoCapture c;
+    c.open( getDataPath( TRACKING_DIR + "/" + video + "/" + FOLDER_IMG + "/" + video + ".webm" ) );
+    c.set( CAP_PROP_POS_FRAMES, startFrame );
+    for ( int frameCounter = startFrame; frameCounter < endFrame; frameCounter++ )
+    {
+      c >> frame;
+
+      if( frame.empty() )
+      {
+        break;
+      }
+
+      if( !initialized )
+      {
+        if( !tracker->init( frame, currentBB ) )
+        {
+          FAIL()<< "Could not initialize tracker" << endl;
+          return;
+        }
+        initialized = true;
+      }
+      else if( initialized )
+      {
+        tracker->update( frame, currentBB );
+      }
+      bbs.push_back( currentBB );
+
+    }
+  }
+  //save the bounding boxes in a Mat
+  Mat bbs_mat( (int)bbs.size(), 4, CV_32F );
+  getMatOfRects( bbs, bbs_mat );
+
+  SANITY_CHECK( bbs_mat, 15, ERROR_RELATIVE );
+
+}

modules/tracking/src/tld_tracker.cpp

@@ -347,11 +347,11 @@ bool TrackerTLDImpl::updateImpl(const Mat& image, Rect2d& boundingBox)
 
     std::vector<double>::iterator it = std::max_element(candidatesRes.begin(), candidatesRes.end());
 
-    dfprintf((stdout, "scale = %f\n", log(1.0 * boundingBox.width / (data->getMinSize()).width) / log(SCALE_STEP)));
+    //dfprintf((stdout, "scale = %f\n", log(1.0 * boundingBox.width / (data->getMinSize()).width) / log(SCALE_STEP)));
-    for( int i = 0; i < (int)candidatesRes.size(); i++ )
+    //for( int i = 0; i < (int)candidatesRes.size(); i++ )
-        dprintf(("\tcandidatesRes[%d] = %f\n", i, candidatesRes[i]));
+        //dprintf(("\tcandidatesRes[%d] = %f\n", i, candidatesRes[i]));
-    data->printme();
+    //data->printme();
-    tldModel->printme(stdout);
+    //tldModel->printme(stdout);
 
     if( it == candidatesRes.end() )
     {
@@ -371,13 +371,13 @@ bool TrackerTLDImpl::updateImpl(const Mat& image, Rect2d& boundingBox)
     if( it != candidatesRes.end() )
     {
         resample(imageForDetector, candidates[it - candidatesRes.begin()], standardPatch);
-        dfprintf((stderr, "%d %f %f\n", data->frameNum, tldModel->Sc(standardPatch), tldModel->Sr(standardPatch)));
+        //dfprintf((stderr, "%d %f %f\n", data->frameNum, tldModel->Sc(standardPatch), tldModel->Sr(standardPatch)));
-        if( candidatesRes.size() == 2 &&  it == (candidatesRes.begin() + 1) )
+        //if( candidatesRes.size() == 2 &&  it == (candidatesRes.begin() + 1) )
-            dfprintf((stderr, "detector WON\n"));
+            //dfprintf((stderr, "detector WON\n"));
     }
     else
     {
-        dfprintf((stderr, "%d x x\n", data->frameNum));
+        //dfprintf((stderr, "%d x x\n", data->frameNum));
     }
 #endif
 
@@ -409,7 +409,7 @@ bool TrackerTLDImpl::updateImpl(const Mat& image, Rect2d& boundingBox)
             detectorResults[i].isObject = expertResult;
         }
         tldModel->integrateRelabeled(imageForDetector, image_blurred, detectorResults);
-        dprintf(("%d relabeled by nExpert\n", negRelabeled));
+        //dprintf(("%d relabeled by nExpert\n", negRelabeled));
         pExpert.additionalExamples(examplesForModel, examplesForEnsemble);
         tldModel->integrateAdditional(examplesForModel, examplesForEnsemble, true);
         examplesForModel.clear(); examplesForEnsemble.clear();
@@ -497,7 +497,7 @@ timeStampPositiveNext(0), timeStampNegativeNext(0), params_(params), boundingBox
                 classifiers[k].integrate(blurredPatch, false);
         }
     }
-    dprintf(("positive patches: %d\nnegative patches: %d\n", (int)positiveExamples.size(), (int)negativeExamples.size()));
+    //dprintf(("positive patches: %d\nnegative patches: %d\n", (int)positiveExamples.size(), (int)negativeExamples.size()));
 }
 
 void TLDDetector::generateScanGrid(int rows, int cols, Size initBox, std::vector<Rect2d>& res, bool withScaling)
@@ -532,7 +532,7 @@ void TLDDetector::generateScanGrid(int rows, int cols, Size initBox, std::vector
             break;
         }
     }
-    dprintf(("%d rects in res\n", (int)res.size()));
+    //dprintf(("%d rects in res\n", (int)res.size()));
 }
 
 bool TLDDetector::detect(const Mat& img, const Mat& imgBlurred, Rect2d& res, std::vector<LabeledPatch>& patches)
@@ -554,7 +554,7 @@ bool TLDDetector::detect(const Mat& img, const Mat& imgBlurred, Rect2d& res, std
     double tmp = 0, maxSc = -5.0;
     Rect2d maxScRect;
 
-    START_TICK("detector");
+    //START_TICK("detector");
     do
     {
         Mat_<double> intImgP, intImgP2;
@@ -605,9 +605,9 @@ bool TLDDetector::detect(const Mat& img, const Mat& imgBlurred, Rect2d& res, std
         GaussianBlur(resized_img, blurred_img, GaussBlurKernelSize, 0.0f);
     }
     while( size.width >= initSize.width && size.height >= initSize.height );
-    END_TICK("detector");
+    //END_TICK("detector");
 
-    dfprintf((stdout, "after NCC: nneg = %d npos = %d\n", nneg, npos));
+    //dfprintf((stdout, "after NCC: nneg = %d npos = %d\n", nneg, npos));
 #if !1
         std::vector<Rect2d> poss, negs;
 
@@ -618,11 +618,11 @@ bool TLDDetector::detect(const Mat& img, const Mat& imgBlurred, Rect2d& res, std
             else
                 negs.push_back(patches[i].rect);
         }
-        dfprintf((stdout, "%d pos and %d neg\n", (int)poss.size(), (int)negs.size()));
+        //dfprintf((stdout, "%d pos and %d neg\n", (int)poss.size(), (int)negs.size()));
         drawWithRects(img, negs, poss, "tech");
 #endif
 
-    dfprintf((stdout, "%d after ensemble\n", pass));
+    //dfprintf((stdout, "%d after ensemble\n", pass));
     if( maxSc < 0 )
         return false;
     res = maxScRect;
@@ -727,6 +727,7 @@ void TrackerTLDModel::integrateRelabeled(Mat& img, Mat& imgBlurred, const std::v
                 classifiers[i].integrate(blurredPatch, patches[k].isObject);
         }
     }
+    /*
     if( negativeIntoModel > 0 )
         dfprintf((stdout, "negativeIntoModel = %d ", negativeIntoModel));
     if( positiveIntoModel > 0)
@@ -735,7 +736,7 @@ void TrackerTLDModel::integrateRelabeled(Mat& img, Mat& imgBlurred, const std::v
         dfprintf((stdout, "negativeIntoEnsemble = %d ", negativeIntoEnsemble));
     if( positiveIntoEnsemble > 0 )
         dfprintf((stdout, "positiveIntoEnsemble = %d ", positiveIntoEnsemble));
-    dfprintf((stdout, "\n"));
+    dfprintf((stdout, "\n"));*/
 }
 
 void TrackerTLDModel::integrateAdditional(const std::vector<Mat_<uchar> >& eForModel, const std::vector<Mat_<uchar> >& eForEnsemble, bool isPositive)
@@ -771,6 +772,7 @@ void TrackerTLDModel::integrateAdditional(const std::vector<Mat_<uchar> >& eForM
                 classifiers[i].integrate(eForEnsemble[k], isPositive);
         }
     }
+    /*
     if( negativeIntoModel > 0 )
         dfprintf((stdout, "negativeIntoModel = %d ", negativeIntoModel));
     if( positiveIntoModel > 0 )
@@ -779,7 +781,7 @@ void TrackerTLDModel::integrateAdditional(const std::vector<Mat_<uchar> >& eForM
         dfprintf((stdout, "negativeIntoEnsemble = %d ", negativeIntoEnsemble));
     if( positiveIntoEnsemble > 0 )
         dfprintf((stdout, "positiveIntoEnsemble = %d ", positiveIntoEnsemble));
-    dfprintf((stdout, "\n"));
+    dfprintf((stdout, "\n"));*/
 }
 
 int TrackerTLDImpl::Pexpert::additionalExamples(std::vector<Mat_<uchar> >& examplesForModel, std::vector<Mat_<uchar> >& examplesForEnsemble)
@@ -844,7 +846,7 @@ Data::Data(Rect2d initBox)
     minSize.width = (int)(initBox.width * 20.0 / minDim);
     minSize.height = (int)(initBox.height * 20.0 / minDim);
     frameNum = 0;
-    dprintf(("minSize = %dx%d\n", minSize.width, minSize.height));
+    //dprintf(("minSize = %dx%d\n", minSize.width, minSize.height));
 }
 
 void Data::printme(FILE*  port)

modules/tracking/test/test_trackerOPE.cpp

@@ -408,6 +408,20 @@ TEST_P(OPE_Overlap, Boosting)
   RecordProperty( "ratioSuccess", test.getRatioSucc() );
 }
 
+TEST_P(OPE_Distance, TLD)
+{
+  TrackerOPETest test( Tracker::create( "TLD" ), TrackerOPETest::DISTANCE, dataset, threshold );
+  test.run();
+  RecordProperty( "ratioSuccess", test.getRatioSucc() );
+}
+
+TEST_P(OPE_Overlap, TLD)
+{
+  TrackerOPETest test( Tracker::create( "TLD" ), TrackerOPETest::OVERLAP, dataset, threshold );
+  test.run();
+  RecordProperty( "ratioSuccess", test.getRatioSucc() );
+}
+
 INSTANTIATE_TEST_CASE_P( Tracking, OPE_Distance, testing::Combine( TESTSET_NAMES, LOCATION_ERROR_THRESHOLD ) );
 
 INSTANTIATE_TEST_CASE_P( Tracking, OPE_Overlap, testing::Combine( TESTSET_NAMES, OVERLAP_THRESHOLD ) );

modules/tracking/test/test_trackerSRE.cpp

@@ -515,6 +515,20 @@ TEST_P(SRE_Overlap, Boosting)
   RecordProperty( "ratioSuccess", test.getRatioSucc() );
 }
 
+TEST_P(SRE_Distance, TLD)
+{
+  TrackerSRETest test( Tracker::create( "TLD" ), TrackerSRETest::DISTANCE, dataset, shift, threshold );
+  test.run();
+  RecordProperty( "ratioSuccess", test.getRatioSucc() );
+}
+
+TEST_P(SRE_Overlap, TLD)
+{
+  TrackerSRETest test( Tracker::create( "TLD" ), TrackerSRETest::OVERLAP, dataset, shift, threshold );
+  test.run();
+  RecordProperty( "ratioSuccess", test.getRatioSucc() );
+}
+
 INSTANTIATE_TEST_CASE_P( Tracking, SRE_Distance, testing::Combine( TESTSET_NAMES, SPATIAL_SHIFTS, LOCATION_ERROR_THRESHOLD ) );
 
 INSTANTIATE_TEST_CASE_P( Tracking, SRE_Overlap, testing::Combine( TESTSET_NAMES, SPATIAL_SHIFTS, OVERLAP_THRESHOLD ) );

modules/tracking/test/test_trackerTRE.cpp

@@ -485,6 +485,20 @@ TEST_P(TRE_Overlap, Boosting)
   RecordProperty( "ratioSuccess", test.getRatioSucc() );
 }
 
+TEST_P(TRE_Distance, TLD)
+{
+  TrackerTRETest test( Tracker::create( "TLD" ), TrackerTRETest::DISTANCE, dataset, threshold, segment );
+  test.run();
+  RecordProperty( "ratioSuccess", test.getRatioSucc() );
+}
+
+TEST_P(TRE_Overlap, TLD)
+{
+  TrackerTRETest test( Tracker::create( "TLD" ), TrackerTRETest::OVERLAP, dataset, threshold, segment );
+  test.run();
+  RecordProperty( "ratioSuccess", test.getRatioSucc() );
+}
+
 INSTANTIATE_TEST_CASE_P( Tracking, TRE_Distance, testing::Combine( TESTSET_NAMES, SEGMENTS, LOCATION_ERROR_THRESHOLD ) );
 
 INSTANTIATE_TEST_CASE_P( Tracking, TRE_Overlap, testing::Combine( TESTSET_NAMES, SEGMENTS, OVERLAP_THRESHOLD ) );