    // 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<detection_type> train (
                const std::vector<std::vector<labeled_detection<detection_type,label_type> > >& 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<detection_type> train (
                const std::vector<std::vector<std::vector<labeled_detection<detection_type,label_type> > > >& 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_