Merge pull request #98 from e-fominov/corellation-tracker-options

Corellation tracker options

dlib/image_processing/correlation_tracker.h

@@ -19,8 +19,20 @@ namespace dlib
     {
     public:
 
-        correlation_tracker (
+        explicit correlation_tracker (unsigned long filter_size = 6, 
+            unsigned long num_scale_levels = 5, 
+            unsigned long scale_window_size = 23,
+            double regularizer_space = 0.001,
+            double nu_space = 0.025,
+            double regularizer_scale = 0.001,
+            double nu_scale = 0.025,
+            double scale_pyramid_alpha = 1.020
         ) 
+            : filter_size(1 << filter_size), num_scale_levels(1 << num_scale_levels),
+            scale_window_size(scale_window_size),
+            regularizer_space(regularizer_space), nu_space(nu_space), 
+            regularizer_scale(regularizer_scale), nu_scale(nu_scale),
+            scale_pyramid_alpha(scale_pyramid_alpha)
         {
             // Create the cosine mask used for space filtering.
             mask = make_cosine_mask();
@@ -78,23 +90,23 @@ namespace dlib
 
 
         unsigned long get_filter_size (
-        ) const { return 128/2; } // must be power of 2
+        ) const { return filter_size; } 
 
         unsigned long get_num_scale_levels(
-        ) const { return 32; }  // must be power of 2
+        ) const { return num_scale_levels; }  
 
         unsigned long get_scale_window_size (
-        ) const { return 23; }
+        ) const { return scale_window_size; }
 
         double get_regularizer_space (
-        ) const { return 0.001; }
+        ) const { return regularizer_space; }
         inline double get_nu_space (
-        ) const { return 0.025;}
+        ) const { return nu_space;}
 
         double get_regularizer_scale (
-        ) const { return 0.001; }
+        ) const { return regularizer_scale; }
         double get_nu_scale (
-        ) const { return 0.025;}
+        ) const { return nu_scale;}
 
         drectangle get_position (
         ) const 
@@ -103,13 +115,11 @@ namespace dlib
         }
 
         double get_scale_pyramid_alpha (
-        ) const
-        {
-            return 1.020;
-        }
+        ) const { return scale_pyramid_alpha; }
+
 
         template <typename image_type>
-        double update (
+        double update_noscale(
             const image_type& img,
             const drectangle& guess
         )
@@ -125,7 +135,7 @@ namespace dlib
                 fft_inplace(F[i]);
 
             // use the current filter to predict the object's location
-            G = 0; 
+            G = 0;
             for (unsigned long i = 0; i < F.size(); ++i)
                 G += pointwise_multiply(F[i],conj(A[i]));
             G = pointwise_multiply(G, reciprocal(B+get_regularizer_space()));
@@ -147,9 +157,8 @@ namespace dlib
             }
             const double psr = (G(p.y(),p.x()).real()-rs.mean())/rs.stddev();
 
-
             // update the position of the object
-            position = translate_rect(guess,tform(pp)-center(guess));
+            position = translate_rect(guess, tform(pp)-center(guess));
 
             // now update the position filters
             make_target_location_image(pp, G);
@@ -160,7 +169,16 @@ namespace dlib
                 B += get_nu_space()*(squared(real(F[i]))+squared(imag(F[i])));
             }
 
+            return psr;
+        }
 
+        template <typename image_type>
+        double update (
+            const image_type& img,
+            const drectangle& guess
+        )
+        {
+            double psr = update_noscale(img, guess);
 
             // Now predict the scale change
             make_scale_space(img, Fs);
@@ -192,9 +210,17 @@ namespace dlib
         }
 
         template <typename image_type>
-        double update (
+        double update_noscale (
             const image_type& img
         )
+        {
+            return update_noscale(img, get_position());
+        }
+
+        template <typename image_type>
+        double update(
+            const image_type& img
+            )
         {
             return update(img, get_position());
         }
@@ -361,6 +387,15 @@ namespace dlib
         // here just so we can void reallocating them over and over.
         matrix<std::complex<double> > G;
         matrix<std::complex<double>,0,1> Gs;
+
+        unsigned long filter_size;
+        unsigned long num_scale_levels;
+        unsigned long scale_window_size;
+        double regularizer_space;
+        double nu_space;
+        double regularizer_scale;
+        double nu_scale;
+        double scale_pyramid_alpha;
     };
 }
 

dlib/image_processing/correlation_tracker_abstract.h

@@ -25,10 +25,23 @@ namespace dlib
 
     public:
 
-        correlation_tracker (
+        explicit correlation_tracker (unsigned long filter_size = 6, 
+            unsigned long num_scale_levels = 5, 
+            unsigned long scale_window_size = 23,
+            double regularizer_space = 0.001,
+            double nu_space = 0.025,
+            double regularizer_scale = 0.001,
+            double nu_scale = 0.025,
+            double scale_pyramid_alpha = 1.020
         );
         /*!
+            requires
+                - p.is_empty() == false
             ensures
+                - Initializes correlation_tracker. Higher value of filter_size and 
+                  num_scale_levels increases tracking precision but requires more CPU 
+                  for processing. Recommended values for filter_size = 5-7, 
+                  default = 6, for num_scale_levels = 4-6, default = 5
                 - #get_position().is_empty() == true
         !*/
 
@@ -58,6 +71,32 @@ namespace dlib
                 - returns the predicted position of the object under track.  
         !*/
 
+        template <
+            typename image_type
+            >
+        double update_noscale (
+            const image_type& img,
+            const drectangle& guess
+        );
+        /*!
+            requires
+                - image_type == an image object that implements the interface defined in
+                  dlib/image_processing/generic_image.h 
+                - get_position().is_empty() == false
+                  (i.e. you must have started tracking by calling start_track())
+            ensures
+                - When searching for the object in img, we search in the area around the
+                  provided guess. This function only tracks object position without trying
+                  to track the scale
+                - #get_position() == the new predicted location of the object in img.  This
+                  location will be a copy of guess that has been translated and NOT scaled
+                  appropriately based on the content of img so that it, hopefully, bounds
+                  the object in img.
+                - Returns the peak to side-lobe ratio.  This is a number that measures how
+                  confident the tracker is that the object is inside #get_position().
+                  Larger values indicate higher confidence.
+        !*/
+
         template <
             typename image_type
             >
@@ -83,6 +122,21 @@ namespace dlib
                   Larger values indicate higher confidence.
         !*/
 
+        template <
+            typename image_type
+            >
+        double update_noscale (
+            const image_type& img
+        );
+        /*!
+            requires
+                - image_type == an image object that implements the interface defined in
+                  dlib/image_processing/generic_image.h 
+                - get_position().is_empty() == false
+                  (i.e. you must have started tracking by calling start_track())
+            ensures
+                - performs: return update_noscale(img, get_position())
+        !*/
         template <
             typename image_type
             >