// Copyright (C) 2014 Davis E. King (davis@dlib.net) // License: Boost Software License See LICENSE.txt for the full license. #undef DLIB_STRUCTURAL_TRACK_ASSOCIATION_TRAnER_ABSTRACT_Hh_ #ifdef DLIB_STRUCTURAL_TRACK_ASSOCIATION_TRAnER_ABSTRACT_Hh_ #include "track_association_function_abstract.h" #include "structural_assignment_trainer_abstract.h" namespace dlib { // ---------------------------------------------------------------------------------------- class structural_track_association_trainer { /*! WHAT THIS OBJECT REPRESENTS This object is a tool for learning to solve a track association problem. That is, it takes in a set of training data and outputs a track_association_function you can use to do detection to track association. The training data takes the form of a set or sets of "track histories". Each track history is a std::vector where each element contains all the detections from a single time step. Moreover, each detection has a label that uniquely identifies which object (e.g. person or whatever) the detection really corresponds to. That is, the labels indicate the correct detection to track associations. The goal of this object is then to produce a track_association_function that can perform a correct detection to track association at each time step. !*/ public: structural_track_association_trainer ( ); /*! ensures - #get_c() == 100 - this object isn't verbose - #get_epsilon() == 0.001 - #get_num_threads() == 2 - #get_max_cache_size() == 5 - #learns_nonnegative_weights() == false - #get_loss_per_track_break() == 1 - #get_loss_per_false_association() == 1 !*/ void set_num_threads ( unsigned long num ); /*! ensures - #get_num_threads() == num !*/ unsigned long get_num_threads ( ) const; /*! ensures - returns the number of threads used during training. You should usually set this equal to the number of processing cores on your machine. !*/ void set_epsilon ( double eps ); /*! requires - eps > 0 ensures - #get_epsilon() == eps !*/ double get_epsilon ( ) const; /*! ensures - returns the error epsilon that determines when training should stop. Smaller values may result in a more accurate solution but take longer to train. You can think of this epsilon value as saying "solve the optimization problem until the average number of association mistakes per time step is within epsilon of its optimal value". !*/ void set_max_cache_size ( unsigned long max_size ); /*! ensures - #get_max_cache_size() == max_size !*/ unsigned long get_max_cache_size ( ) const; /*! ensures - During training, this object basically runs the track_association_function on each training sample, over and over. To speed this up, it is possible to cache the results of these invocations. This function returns the number of cache elements per training sample kept in the cache. Note that a value of 0 means caching is not used at all. !*/ void be_verbose ( ); /*! ensures - This object will print status messages to standard out so that a user can observe the progress of the algorithm. !*/ void be_quiet ( ); /*! ensures - this object will not print anything to standard out !*/ void set_loss_per_false_association ( double loss ); /*! requires - loss > 0 ensures - #get_loss_per_false_association() == loss !*/ double get_loss_per_false_association ( ) const; /*! ensures - returns the amount of loss experienced for assigning a detection to the wrong track. If you care more about avoiding false associations than avoiding track breaks then you can increase this value. !*/ void set_loss_per_track_break ( double loss ); /*! requires - loss > 0 ensures - #get_loss_per_track_break() == loss !*/ double get_loss_per_track_break ( ) const; /*! ensures - returns the amount of loss experienced for incorrectly assigning a detection to a new track instead of assigning it to its existing track. If you care more about avoiding track breaks than avoiding things like track swaps then you can increase this value. !*/ void set_oca ( const oca& item ); /*! ensures - #get_oca() == item !*/ const oca get_oca ( ) const; /*! ensures - Internally this object treats track association learning as a structural SVM problem. This routine returns a copy of the optimizer used to solve the structural SVM problem. !*/ void set_c ( double C ); /*! ensures - returns the SVM regularization parameter. It is the parameter that determines the trade-off between trying to fit the training data (i.e. minimize the loss) or allowing more errors but hopefully improving the generalization of the resulting track_association_function. Larger values encourage exact fitting while smaller values of C may encourage better generalization. !*/ double get_c ( ) const; /*! requires - C > 0 ensures - #get_c() = C !*/ bool learns_nonnegative_weights ( ) const; /*! ensures - Ultimately, the output of training is a parameter vector that defines the behavior of the track_association_function. If learns_nonnegative_weights() == true then the resulting learned parameter vector will always have non-negative entries. !*/ void set_learns_nonnegative_weights ( bool value ); /*! ensures - #learns_nonnegative_weights() == value !*/ template < typename detection_type, typename label_type > const track_association_function train ( const std::vector > >& sample ) const; /*! requires - is_track_association_problem(sample) == true ensures - This function attempts to learn to do track association from the given training data. Note that we interpret sample as a single track history such that sample[0] are all detections from the first time step, then sample[1] are detections from the second time step, and so on. - returns a function F such that: - Executing F(tracks, detections) will try to correctly associate the contents of detections to the contents of tracks and perform track updating and creation. - if (learns_nonnegative_weights() == true) then - min(F.get_assignment_function().get_weights()) >= 0 !*/ template < typename detection_type, typename label_type > const track_association_function train ( const std::vector > > >& sample ) const; /*! requires - is_track_association_problem(samples) == true ensures - This function attempts to learn to do track association from the given training data. In this case, we take a set of track histories as training data instead of just one track history as with the above train() method. - returns a function F such that: - Executing F(tracks, detections) will try to correctly associate the contents of detections to the contents of tracks and perform track updating and creation. - if (learns_nonnegative_weights() == true) then - min(F.get_assignment_function().get_weights()) >= 0 !*/ }; // ---------------------------------------------------------------------------------------- } #endif // DLIB_STRUCTURAL_TRACK_ASSOCIATION_TRAnER_ABSTRACT_Hh_