Cleaned up the new python object detection interface a little.

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;

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)

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.
     !*/