From 2293c91e00c927a91e5bf5564bb4a04331664ffd Mon Sep 17 00:00:00 2001
From: Davis King <davis@dlib.net>
Date: Sun, 23 Feb 2014 16:02:52 -0500
Subject: [PATCH] Cleaned up the new python object detection interface a
little.
---
tools/python/src/object_detection.cpp | 60 ++++++++++++++++++-
tools/python/src/simple_object_detector.h | 13 ++--
.../src/simple_object_detector_abstract.h | 22 +++----
3 files changed, 75 insertions(+), 20 deletions(-)
diff --git a/tools/python/src/object_detection.cpp b/tools/python/src/object_detection.cpp
index c4c3aafb..d0e70ede 100644
--- a/tools/python/src/object_detection.cpp
+++ b/tools/python/src/object_detection.cpp
@@ -232,6 +232,8 @@ void bind_object_detection()
&simple_object_detector_training_options::add_left_right_image_flips)
.add_property("detection_window_size", &simple_object_detector_training_options::detection_window_size,
&simple_object_detector_training_options::detection_window_size)
+ .add_property("C", &simple_object_detector_training_options::C,
+ &simple_object_detector_training_options::C)
.add_property("num_threads", &simple_object_detector_training_options::num_threads,
&simple_object_detector_training_options::num_threads);
@@ -261,12 +263,64 @@ void bind_object_detection()
"Returns the default face detector");
def("train_simple_object_detector", train_simple_object_detector,
- (arg("dataset_filename"), arg("detector_output_filename"), arg("C"), arg("options")=simple_object_detector_training_options()),
- "whatever");
+ (arg("dataset_filename"), arg("detector_output_filename"), arg("options")),
+"requires \n\
+ - options.C > 0 \n\
+ensures \n\
+ - Uses the structural_object_detection_trainer to train a \n\
+ simple_object_detector based on the labeled images in the XML file \n\
+ dataset_filename. This function assumes the file dataset_filename is in the \n\
+ XML format produced by dlib's save_image_dataset_metadata() routine. \n\
+ - This function will apply a reasonable set of default parameters and \n\
+ preprocessing techniques to the training procedure for simple_object_detector \n\
+ objects. So the point of this function is to provide you with a very easy \n\
+ way to train a basic object detector. \n\
+ - The trained object detector is serialized to the file detector_output_filename."
+ /*!
+ requires
+ - options.C > 0
+ ensures
+ - Uses the structural_object_detection_trainer to train a
+ simple_object_detector based on the labeled images in the XML file
+ dataset_filename. This function assumes the file dataset_filename is in the
+ XML format produced by dlib's save_image_dataset_metadata() routine.
+ - This function will apply a reasonable set of default parameters and
+ preprocessing techniques to the training procedure for simple_object_detector
+ objects. So the point of this function is to provide you with a very easy
+ way to train a basic object detector.
+ - The trained object detector is serialized to the file detector_output_filename.
+ !*/
+ );
def("test_simple_object_detector", test_simple_object_detector,
(arg("dataset_filename"), arg("detector_filename")),
- "whatever");
+"ensures \n\
+ - Loads an image dataset from dataset_filename. We assume dataset_filename is \n\
+ a file using the XML format written by save_image_dataset_metadata(). \n\
+ - Loads a simple_object_detector from the file detector_filename. This means \n\
+ detector_filename should be a file produced by the train_simple_object_detector() \n\
+ routine. \n\
+ - This function tests the detector against the dataset and returns the \n\
+ precision, recall, and average precision of the detector. In fact, The \n\
+ return value of this function is identical to that of dlib's \n\
+ test_object_detection_function() routine. Therefore, see the documentation \n\
+ for test_object_detection_function() for a detailed definition of these \n\
+ metrics. "
+ /*!
+ ensures
+ - Loads an image dataset from dataset_filename. We assume dataset_filename is
+ a file using the XML format written by save_image_dataset_metadata().
+ - Loads a simple_object_detector from the file detector_filename. This means
+ detector_filename should be a file produced by the train_simple_object_detector()
+ routine.
+ - This function tests the detector against the dataset and returns the
+ precision, recall, and average precision of the detector. In fact, The
+ return value of this function is identical to that of dlib's
+ test_object_detection_function() routine. Therefore, see the documentation
+ for test_object_detection_function() for a detailed definition of these
+ metrics.
+ !*/
+ );
{
typedef simple_object_detector_py type;
diff --git a/tools/python/src/simple_object_detector.h b/tools/python/src/simple_object_detector.h
index 27bcf02a..4f888013 100644
--- a/tools/python/src/simple_object_detector.h
+++ b/tools/python/src/simple_object_detector.h
@@ -30,12 +30,14 @@ namespace dlib
add_left_right_image_flips = false;
num_threads = 4;
detection_window_size = 80*80;
+ C = 1;
}
bool be_verbose;
bool add_left_right_image_flips;
unsigned long num_threads;
unsigned long detection_window_size;
+ double C;
};
// ----------------------------------------------------------------------------------------
@@ -119,11 +121,10 @@ namespace dlib
inline void train_simple_object_detector (
const std::string& dataset_filename,
const std::string& detector_output_filename,
- const double C,
- const simple_object_detector_training_options& options = simple_object_detector_training_options()
+ const simple_object_detector_training_options& options
)
{
- if (C <= 0)
+ if (options.C <= 0)
throw error("Invalid C value given to train_simple_object_detector(), C must be > 0.");
dlib::array<array2d<unsigned char> > images;
@@ -140,11 +141,11 @@ namespace dlib
scanner.set_detection_window_size(width, height);
structural_object_detection_trainer<image_scanner_type> trainer(scanner);
trainer.set_num_threads(options.num_threads);
- trainer.set_c(C);
+ trainer.set_c(options.C);
trainer.set_epsilon(0.01);
if (options.be_verbose)
{
- std::cout << "Training with C: " << C << std::endl;
+ std::cout << "Training with C: " << options.C << std::endl;
std::cout << "Training using " << options.num_threads << " threads."<< std::endl;
std::cout << "Training with sliding window " << width << " pixels wide by " << height << " pixels tall." << std::endl;
if (options.add_left_right_image_flips)
@@ -195,7 +196,7 @@ namespace dlib
if (options.be_verbose)
{
std::cout << "Training complete, saved detector to file " << detector_output_filename << std::endl;
- std::cout << "Trained with C: " << C << std::endl;
+ std::cout << "Trained with C: " << options.C << std::endl;
std::cout << "Trained using " << options.num_threads << " threads."<< std::endl;
std::cout << "Trained with sliding window " << width << " pixels wide by " << height << " pixels tall." << std::endl;
if (upsample_amount != 0)
diff --git a/tools/python/src/simple_object_detector_abstract.h b/tools/python/src/simple_object_detector_abstract.h
index 7cd87273..dd09ca47 100644
--- a/tools/python/src/simple_object_detector_abstract.h
+++ b/tools/python/src/simple_object_detector_abstract.h
@@ -19,9 +19,8 @@ namespace dlib
{
/*!
WHAT THIS OBJECT REPRESENTS
- This object is a container for the more advanced options to the
- train_simple_object_detector() routine. The parameters have the following
- interpretations:
+ This object is a container for the options to the train_simple_object_detector()
+ routine. The parameters have the following interpretations:
- be_verbose: If true, train_simple_object_detector() will print out a
lot of information to the screen while training.
- add_left_right_image_flips: if true, train_simple_object_detector()
@@ -33,6 +32,11 @@ namespace dlib
machine to obtain the fastest training speed.
- detection_window_size: The sliding window used will have about this
many pixels inside it.
+ - C is the usual SVM C regularization parameter. So it is passed to
+ structural_object_detection_trainer::set_c(). Larger values of C
+ will encourage the trainer to fit the data better but might lead to
+ overfitting. Therefore, you must determine the proper setting of
+ this parameter experimentally.
!*/
fhog_training_options()
@@ -41,12 +45,14 @@ namespace dlib
add_left_right_image_flips = false;
num_threads = 4;
detection_window_size = 80*80;
+ C = 1;
}
bool be_verbose;
bool add_left_right_image_flips;
unsigned long num_threads;
unsigned long detection_window_size;
+ double C;
};
// ----------------------------------------------------------------------------------------
@@ -58,12 +64,11 @@ namespace dlib
void train_simple_object_detector (
const std::string& dataset_filename,
const std::string& detector_output_filename,
- const double C,
- const fhog_training_options& options = fhog_training_options()
+ const fhog_training_options& options
);
/*!
requires
- - C > 0
+ - options.C > 0
ensures
- Uses the structural_object_detection_trainer to train a
simple_object_detector based on the labeled images in the XML file
@@ -73,11 +78,6 @@ namespace dlib
preprocessing techniques to the training procedure for simple_object_detector
objects. So the point of this function is to provide you with a very easy
way to train a basic object detector.
- - C is the usual SVM C regularization parameter. So it is passed to
- structural_object_detection_trainer::set_c(). Larger values of C will
- encourage the trainer to fit the data better but might lead to overfitting.
- Therefore, you must determine the proper setting of this parameter
- experimentally.
- The trained object detector is serialized to the file detector_output_filename.
!*/
--
2.18.0