coco
269 lines
9.6 KiB
C++
269 lines
9.6 KiB
C++
// 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_
|
|
|
|
|