1 // Copyright (C) 2009  Davis E. King (davis@dlib.net)
2 // License: Boost Software License   See LICENSE.txt for the full license.
3 #undef DLIB_NULL_TRAINERs_ABSTRACT_
4 #ifdef DLIB_NULL_TRAINERs_ABSTRACT_
5 
6 #include "../algs.h"
7 #include "function_abstract.h"
8 
9 namespace dlib
10 {
11 
12 // ----------------------------------------------------------------------------------------
13 
14     template <
15         typename dec_funct_type
16         >
17     class null_trainer_type
18     {
19         /*!
20             REQUIREMENTS ON dec_funct_type
21                 dec_funct_type can be any copyable type that provides the needed
22                 typedefs used below (e.g. kernel_type, scalar_type, etc.).
23 
24             WHAT THIS OBJECT REPRESENTS
25                 This object is a simple tool for turning a decision function
26                 into a trainer object that always returns the original decision
27                 function when you try to train with it.
28 
29                 dlib contains a few "training post processing" algorithms (e.g.
30                 reduced() and reduced2()).  These tools take in a trainer object,
31                 tell it to perform training, and then they take the output decision
32                 function and do some kind of post processing to it.  The null_trainer_type
33                 object is useful because you can use it to run an already
34                 learned decision function through the training post processing
35                 algorithms by turning a decision function into a null_trainer_type
36                 and then giving it to a post processor.
37         !*/
38 
39     public:
40         typedef typename dec_funct_type::kernel_type kernel_type;
41         typedef typename dec_funct_type::scalar_type scalar_type;
42         typedef typename dec_funct_type::sample_type sample_type;
43         typedef typename dec_funct_type::mem_manager_type mem_manager_type;
44         typedef dec_funct_type trained_function_type;
45 
46         null_trainer_type (
47         );
48         /*!
49             ensures
50                 - any call to this->train(x,y) will return a default initialized
51                   dec_funct_type object.
52         !*/
53 
54         null_trainer_type (
55             const dec_funct_type& dec_funct
56         );
57         /*!
58             ensures
59                 - any call to this->train(x,y) will always return a copy of
60                   the given dec_funct object.
61         !*/
62 
63         template <
64             typename in_sample_vector_type,
65             typename in_scalar_vector_type
66             >
67         const dec_funct_type& train (
68             const in_sample_vector_type& x,
69             const in_scalar_vector_type& y
70         ) const;
71         /*!
72             ensures
73                 - returns a copy of the decision function object given to
74                   this object's constructor.
75         !*/
76 
77     };
78 
79 // ----------------------------------------------------------------------------------------
80 
81     template <
82         typename dec_funct_type
83         >
null_trainer(const dec_funct_type & dec_funct)84     const null_trainer_type<dec_funct_type> null_trainer (
85         const dec_funct_type& dec_funct
86     ) { return null_trainer_type<dec_funct_type>(dec_funct); }
87     /*!
88         ensures
89             - returns a null_trainer_type object that has been instantiated with
90               the given arguments.  That is, this function returns a null_trainer_type
91               trainer that will return a copy of the given dec_funct object every time
92               someone calls its train() function.
93     !*/
94 
95 // ----------------------------------------------------------------------------------------
96 
97 }
98 
99 #endif // DLIB_NULL_TRAINERs_ABSTRACT_
100 
101 
102