Point Cloud Library (PCL)  1.9.1
fern_trainer.h
1 /*
2  * Software License Agreement (BSD License)
3  *
4  * Point Cloud Library (PCL) - www.pointclouds.org
5  * Copyright (c) 2010-2011, Willow Garage, Inc.
6  *
7  * All rights reserved.
8  *
9  * Redistribution and use in source and binary forms, with or without
10  * modification, are permitted provided that the following conditions
11  * are met:
12  *
13  * * Redistributions of source code must retain the above copyright
14  * notice, this list of conditions and the following disclaimer.
15  * * Redistributions in binary form must reproduce the above
16  * copyright notice, this list of conditions and the following
17  * disclaimer in the documentation and/or other materials provided
18  * with the distribution.
19  * * Neither the name of Willow Garage, Inc. nor the names of its
20  * contributors may be used to endorse or promote products derived
21  * from this software without specific prior written permission.
22  *
23  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
24  * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
25  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
26  * FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
27  * COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
28  * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
29  * BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
30  * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
31  * CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
32  * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
33  * ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
34  * POSSIBILITY OF SUCH DAMAGE.
35  *
36  */
37 
38 #ifndef PCL_ML_FERNS_FERN_TRAINER_H_
39 #define PCL_ML_FERNS_FERN_TRAINER_H_
40 
41 #include <pcl/common/common.h>
42 
43 #include <pcl/ml/ferns/fern.h>
44 #include <pcl/ml/feature_handler.h>
45 #include <pcl/ml/stats_estimator.h>
46 
47 #include <vector>
48 
49 namespace pcl
50 {
51 
52  /** \brief Trainer for a Fern. */
53  template <class FeatureType, class DataSet, class LabelType, class ExampleIndex, class NodeType>
54  class PCL_EXPORTS FernTrainer
55  {
56 
57  public:
58 
59  /** \brief Constructor. */
60  FernTrainer ();
61  /** \brief Destructor. */
62  virtual
63  ~FernTrainer ();
64 
65  /** \brief Sets the feature handler used to create and evaluate features.
66  * \param[in] feature_handler The feature handler.
67  */
68  inline void
70  {
71  feature_handler_ = &feature_handler;
72  }
73 
74  /** \brief Sets the object for estimating the statistics for tree nodes.
75  * \param[in] stats_estimator The statistics estimator.
76  */
77  inline void
79  {
80  stats_estimator_ = &stats_estimator;
81  }
82 
83  /** \brief Sets the maximum depth of the learned tree.
84  * \param[in] fern_depth Maximum depth of the learned tree.
85  */
86  inline void
87  setFernDepth (const size_t fern_depth)
88  {
89  fern_depth_ = fern_depth;
90  }
91 
92  /** \brief Sets the number of features used to find optimal decision features.
93  * \param[in] num_of_features The number of features.
94  */
95  inline void
96  setNumOfFeatures (const size_t num_of_features)
97  {
98  num_of_features_ = num_of_features;
99  }
100 
101  /** \brief Sets the number of thresholds tested for finding the optimal decision threshold on the feature responses.
102  * \param[in] num_of_threshold The number of thresholds.
103  */
104  inline void
105  setNumOfThresholds (const size_t num_of_threshold)
106  {
107  num_of_thresholds_ = num_of_threshold;
108  }
109 
110  /** \brief Sets the input data set used for training.
111  * \param[in] data_set The data set used for training.
112  */
113  inline void
114  setTrainingDataSet (DataSet & data_set)
115  {
116  data_set_ = data_set;
117  }
118 
119  /** \brief Example indices that specify the data used for training.
120  * \param[in] examples The examples.
121  */
122  inline void
123  setExamples (std::vector<ExampleIndex> & examples)
124  {
125  examples_ = examples;
126  }
127 
128  /** \brief Sets the label data corresponding to the example data.
129  * \param[in] label_data The label data.
130  */
131  inline void
132  setLabelData (std::vector<LabelType> & label_data)
133  {
134  label_data_ = label_data;
135  }
136 
137  /** \brief Trains a decision tree using the set training data and settings.
138  * \param[out] fern Destination for the trained tree.
139  */
140  void
141  train (Fern<FeatureType, NodeType> & fern);
142 
143  protected:
144 
145  /** \brief Creates uniformely distrebuted thresholds over the range of the supplied values.
146  * \param[in] num_of_thresholds The number of thresholds to create.
147  * \param[in] values The values for estimating the expected value range.
148  * \param[out] thresholds The resulting thresholds.
149  */
150  static void
151  createThresholdsUniform (const size_t num_of_thresholds,
152  std::vector<float> & values,
153  std::vector<float> & thresholds);
154 
155  private:
156 
157  /** \brief Desired depth of the learned fern. */
158  size_t fern_depth_;
159  /** \brief Number of features used to find optimal decision features. */
160  size_t num_of_features_;
161  /** \brief Number of thresholds. */
162  size_t num_of_thresholds_;
163 
164  /** \brief FeatureHandler instance, responsible for creating and evaluating features. */
166  /** \brief StatsEstimator instance, responsible for gathering stats about a node. */
168 
169  /** \brief The training data set. */
170  DataSet data_set_;
171  /** \brief The label data. */
172  std::vector<LabelType> label_data_;
173  /** \brief The example data. */
174  std::vector<ExampleIndex> examples_;
175 
176  };
177 
178 }
179 
180 #include <pcl/ml/impl/ferns/fern_trainer.hpp>
181 
182 #endif
void setNumOfFeatures(const size_t num_of_features)
Sets the number of features used to find optimal decision features.
Definition: fern_trainer.h:96
void setFeatureHandler(pcl::FeatureHandler< FeatureType, DataSet, ExampleIndex > &feature_handler)
Sets the feature handler used to create and evaluate features.
Definition: fern_trainer.h:69
void setNumOfThresholds(const size_t num_of_threshold)
Sets the number of thresholds tested for finding the optimal decision threshold on the feature respon...
Definition: fern_trainer.h:105
void setFernDepth(const size_t fern_depth)
Sets the maximum depth of the learned tree.
Definition: fern_trainer.h:87
This file defines compatibility wrappers for low level I/O functions.
Definition: convolution.h:45
Define standard C methods and C++ classes that are common to all methods.
void setLabelData(std::vector< LabelType > &label_data)
Sets the label data corresponding to the example data.
Definition: fern_trainer.h:132
void setStatsEstimator(pcl::StatsEstimator< LabelType, NodeType, DataSet, ExampleIndex > &stats_estimator)
Sets the object for estimating the statistics for tree nodes.
Definition: fern_trainer.h:78
Class representing a Fern.
Definition: fern.h:51
Trainer for a Fern.
Definition: fern_trainer.h:54
void setTrainingDataSet(DataSet &data_set)
Sets the input data set used for training.
Definition: fern_trainer.h:114
void setExamples(std::vector< ExampleIndex > &examples)
Example indices that specify the data used for training.
Definition: fern_trainer.h:123
Utility class interface which is used for creating and evaluating features.