Skip to content

D
dlib
Commit cdcbe6dc authored by Davis King's avatar Davis King
Browse files
Options

Fleshed out the spec.

parent 97c8bfca
Show whitespace changes
Inline Side-by-side
Showing with 109 additions and 1 deletion
dlib/svm/structural_object_detection_trainer_abstract.h
View file @ cdcbe6dc
......@@ -20,7 +20,21 @@ namespace dlib
class structural_object_detection_trainer : noncopyable
{
/*!
REQUIREMENTS ON image_scanner_type
image_scanner_type must be an implementation of
dlib/image_processing/scan_image_pyramid_abstract.h
REQUIREMENTS ON overlap_tester_type
overlap_tester_type must be an implementation of the test_box_overlap
object defined in dlib/image_processing/box_overlap_testing_abstract.h.
WHAT THIS OBJECT REPRESENTS
This object is a tool for learning to detect objects in images based on a
set of labeled images. The training procedure produces an object_detector
which can be used to predict the locations of objects in new images.
Note that this is just a convenience wrapper around the structural_svm_object_detection_problem
to make it look similar to all the other trainers in dlib.
!*/
public:
......@@ -51,16 +65,36 @@ namespace dlib
void set_overlap_tester (
const overlap_tester_type& tester
);
/*!
ensures
- #get_overlap_tester() == tester
!*/
overlap_tester_type get_overlap_tester (
) const;
/*!
ensures
- returns the overlap tester object which will be used to perform non-max suppression.
In particular, this function returns the overlap tester which will populate the
object_detector returned by train().
!*/
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 (
scalar_type eps
......@@ -74,26 +108,65 @@ namespace dlib
const scalar_type 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 execute. You can think of this epsilon value as saying "solve the
optimization problem until the average loss per sample is within epsilon
of it's 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 object detector on
each image, over and over. To speed this up, it is possible to cache
the results of these detector 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. Note also that
each cache element takes up about sizeof(double)*scanner.get_num_dimensions()
memory (where scanner is the scanner given to this object's constructor).
!*/
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_oca (
const oca& item
);
/*!
ensures
- #get_oca() == item
!*/
const oca get_oca (
) const;
/*!
ensures
- returns a copy of the optimizer used to solve the structural SVM problem.
!*/
void set_c (
scalar_type C
......@@ -107,6 +180,15 @@ namespace dlib
const scalar_type get_c (
) const;
/*!
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 detector. Larger
values encourage exact fitting while smaller values of C may encourage
better generalization.
!*/
void set_overlap_eps (
double eps
......@@ -120,9 +202,23 @@ namespace dlib
double get_overlap_eps (
) const;
/*!
ensures
- returns the amount of overlap necessary for a detection to be considered
as overlapping with a ground truth rectangle. If it doesn't overlap then
it is considered to be a false alarm. To define this precisely, let
A and B be two rectangles, then A and B overlap if and only if:
A.intersect(B).area()/(A+B).area() > get_overlap_eps()
!*/
double get_loss_per_missed_target (
) const;
/*!
ensures
- returns the amount of loss experienced for failing to detect one of the
targets. If you care more about finding targets than having a low false
alarm rate then you can increase this value.
!*/
void set_loss_per_missed_target (
double loss
......@@ -136,6 +232,13 @@ namespace dlib
double get_loss_per_false_alarm (
) const;
/*!
ensures
- returns the amount of loss experienced for emitting a false alarm detection.
Or in other words, the loss for generating a detection that doesn't correspond
to one of the truth rectangles. If you care more about having a low false
alarm rate than finding all the targets then you can increase this value.
!*/
void set_loss_per_false_alarm (
double loss
......@@ -158,8 +261,13 @@ namespace dlib
requires
- is_learning_problem(images, truth_rects) == true
- it must be valid to pass images[0] into the image_scanner_type::load() method.
(also, image_array_type must be an implementation of dlib/array/array_kernel_abstract.h)
ensures
-
- Uses the structural_svm_object_detection_problem to train an object_detector
on the given images and truth_rects.
- returns a function F with the following properties:
- F(new_image) == A prediction of what objects are present in new_image. This
is a set of rectangles indicating their positions.
!*/
};
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment