Merging upstream version 1.44.3.

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 166 insertions, 0 deletions

diff --git a/ml/dlib/dlib/svm/one_vs_one_trainer_abstract.h b/ml/dlib/dlib/svm/one_vs_one_trainer_abstract.h
new file mode 100644
index 000000000..42ba35815
--- /dev/null
+++ b/ml/dlib/dlib/svm/one_vs_one_trainer_abstract.h
@@ -0,0 +1,166 @@
+// Copyright (C) 2010  Davis E. King (davis@dlib.net)
+// License: Boost Software License   See LICENSE.txt for the full license.
+#undef DLIB_ONE_VS_ONE_TRAiNER_ABSTRACT_Hh_
+#ifdef DLIB_ONE_VS_ONE_TRAiNER_ABSTRACT_Hh_
+
+
+#include "one_vs_one_decision_function_abstract.h"
+#include <vector>
+
+#include "../any/any_trainer_abstract.h"
+
+namespace dlib
+{
+
+// ----------------------------------------------------------------------------------------
+
+    template <
+        typename any_trainer,
+        typename label_type_ = double
+        >
+    class one_vs_one_trainer
+    {
+        /*!
+            REQUIREMENTS ON any_trainer
+                must be an instantiation of the dlib::any_trainer template.   
+
+            REQUIREMENTS ON label_type_
+                label_type_ must be default constructable, copyable, and comparable using
+                operator < and ==.  It must also be possible to write it to an std::ostream
+                using operator<<.
+
+            WHAT THIS OBJECT REPRESENTS
+                This object is a tool for turning a bunch of binary classifiers
+                into a multiclass classifier.  It does this by training the binary
+                classifiers in a one vs. one fashion.  That is, if you have N possible
+                classes then it trains N*(N-1)/2 binary classifiers which are then used
+                to vote on the identity of a test sample.
+
+                This object works with any kind of binary classification trainer object
+                capable of being assigned to an any_trainer object.  (e.g. the svm_nu_trainer) 
+        !*/
+
+    public:
+
+
+        typedef label_type_ label_type;
+
+        typedef typename any_trainer::sample_type sample_type;
+        typedef typename any_trainer::scalar_type scalar_type;
+        typedef typename any_trainer::mem_manager_type mem_manager_type;
+
+        typedef one_vs_one_decision_function<one_vs_one_trainer> trained_function_type;
+
+        one_vs_one_trainer (
+        );
+        /*!
+            ensures
+                - This object is properly initialized
+                - This object will not be verbose unless be_verbose() is called.
+                - No binary trainers are associated with *this.  I.e. you have to
+                  call set_trainer() before calling train().
+                - #get_num_threads() == 4
+        !*/
+
+        void set_trainer (
+            const any_trainer& trainer
+        );
+        /*!
+            ensures
+                - sets the trainer used for all pairs of training.  Any previous 
+                  calls to set_trainer() are overridden by this function.  Even the
+                  more specific set_trainer(trainer, l1, l2) form. 
+        !*/
+
+        void set_trainer (
+            const any_trainer& trainer,
+            const label_type& l1,
+            const label_type& l2
+        );
+        /*!
+            requires
+                - l1 != l2
+            ensures
+                - Sets the trainer object used to create a binary classifier to
+                  distinguish l1 labeled samples from l2 labeled samples.
+        !*/
+
+        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_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.
+        !*/
+
+        struct invalid_label : public dlib::error 
+        { 
+            /*!
+                This is the exception thrown by the train() function below.
+            !*/
+            label_type l1, l2;
+        };
+
+        trained_function_type train (
+            const std::vector<sample_type>& all_samples,
+            const std::vector<label_type>& all_labels
+        ) const;
+        /*!
+            requires
+                - is_learning_problem(all_samples, all_labels)
+            ensures
+                - trains a bunch of binary classifiers in a one vs one fashion to solve the given 
+                  multiclass classification problem.  
+                - returns a one_vs_one_decision_function F with the following properties:
+                    - F contains all the learned binary classifiers and can be used to predict
+                      the labels of new samples.
+                    - if (new_x is a sample predicted to have a label of L) then
+                        - F(new_x) == L
+                    - F.get_labels() == select_all_distinct_labels(all_labels)
+                    - F.number_of_classes() == select_all_distinct_labels(all_labels).size()
+            throws
+                - invalid_label
+                  This exception is thrown if there are labels in all_labels which don't have
+                  any corresponding trainer object.  This will never happen if set_trainer(trainer)
+                  has been called.  However, if only the set_trainer(trainer,l1,l2) form has been
+                  used then this exception is thrown if not all necessary label pairs have been
+                  given a trainer.
+
+                  invalid_label::l1 and invalid_label::l2 will contain the label pair which is
+                  missing a trainer object.  Additionally, the exception will contain an
+                  informative error message available via invalid_label::what().
+        !*/
+
+    };
+
+// ----------------------------------------------------------------------------------------
+
+}
+
+#endif // DLIB_ONE_VS_ONE_TRAiNER_ABSTRACT_Hh_
+
+