Point Cloud Library (PCL)  1.10.0
decision_forest_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 #pragma once
39 
40 #include <pcl/common/common.h>
41 
42 #include <pcl/ml/dt/decision_forest.h>
43 #include <pcl/ml/dt/decision_tree.h>
44 #include <pcl/ml/dt/decision_tree_trainer.h>
45 #include <pcl/ml/feature_handler.h>
46 #include <pcl/ml/stats_estimator.h>
47 
48 #include <vector>
49 
50 namespace pcl {
51 
52 /** Trainer for decision trees. */
53 template <class FeatureType,
54  class DataSet,
55  class LabelType,
56  class ExampleIndex,
57  class NodeType>
59 
60 public:
61  /** Constructor. */
63 
64  /** Destructor. */
65  virtual ~DecisionForestTrainer();
66 
67  /** Sets the number of trees to train.
68  *
69  * \param[in] num_of_trees the number of trees
70  */
71  inline void
72  setNumberOfTreesToTrain(const std::size_t num_of_trees)
73  {
74  num_of_trees_to_train_ = num_of_trees;
75  }
76 
77  /** Sets the feature handler used to create and evaluate features.
78  *
79  * \param[in] feature_handler the feature handler
80  */
81  inline void
84  {
85  decision_tree_trainer_.setFeatureHandler(feature_handler);
86  }
87 
88  /** Sets the object for estimating the statistics for tree nodes.
89  *
90  * \param[in] stats_estimator the statistics estimator
91  */
92  inline void
95  {
96  decision_tree_trainer_.setStatsEstimator(stats_estimator);
97  }
98 
99  /** Sets the maximum depth of the learned tree.
100  *
101  * \param[in] max_tree_depth maximum depth of the learned tree
102  */
103  inline void
104  setMaxTreeDepth(const std::size_t max_tree_depth)
105  {
106  decision_tree_trainer_.setMaxTreeDepth(max_tree_depth);
107  }
108 
109  /** Sets the number of features used to find optimal decision features.
110  *
111  * \param[in] num_of_features the number of features
112  */
113  inline void
114  setNumOfFeatures(const std::size_t num_of_features)
115  {
116  decision_tree_trainer_.setNumOfFeatures(num_of_features);
117  }
118 
119  /** Sets the number of thresholds tested for finding the optimal decision threshold on
120  * the feature responses.
121  *
122  * \param[in] num_of_threshold the number of thresholds
123  */
124  inline void
125  setNumOfThresholds(const std::size_t num_of_threshold)
126  {
127  decision_tree_trainer_.setNumOfThresholds(num_of_threshold);
128  }
129 
130  /** Sets the input data set used for training.
131  *
132  * \param[in] data_set the data set used for training
133  */
134  inline void
135  setTrainingDataSet(DataSet& data_set)
136  {
137  decision_tree_trainer_.setTrainingDataSet(data_set);
138  }
139 
140  /** Example indices that specify the data used for training.
141  *
142  * \param[in] examples the examples
143  */
144  inline void
145  setExamples(std::vector<ExampleIndex>& examples)
146  {
147  decision_tree_trainer_.setExamples(examples);
148  }
149 
150  /** Sets the label data corresponding to the example data.
151  *
152  * \param[in] label_data the label data
153  */
154  inline void
155  setLabelData(std::vector<LabelType>& label_data)
156  {
157  decision_tree_trainer_.setLabelData(label_data);
158  }
159 
160  /** Sets the minimum number of examples to continue growing a tree.
161  *
162  * \param[in] n number of examples
163  */
164  inline void
165  setMinExamplesForSplit(std::size_t n)
166  {
167  decision_tree_trainer_.setMinExamplesForSplit(n);
168  }
169 
170  /** Specify the thresholds to be used when evaluating features.
171  *
172  * \param[in] thres the threshold values
173  */
174  void
175  setThresholds(std::vector<float>& thres)
176  {
177  decision_tree_trainer_.setThresholds(thres);
178  }
179 
180  /** Specify the data provider.
181  *
182  * \param[in] dtdp the data provider that should implement getDatasetAndLabels()
183  * function
184  */
185  void
187  typename pcl::DecisionTreeTrainerDataProvider<FeatureType,
188  DataSet,
189  LabelType,
190  ExampleIndex,
191  NodeType>::Ptr& dtdp)
192  {
193  decision_tree_trainer_.setDecisionTreeDataProvider(dtdp);
194  }
195 
196  /** Specify if the features are randomly generated at each split node.
197  *
198  * \param[in] b do it or not
199  */
200  void
202  {
203  decision_tree_trainer_.setRandomFeaturesAtSplitNode(b);
204  }
205 
206  /** Trains a decision forest using the set training data and settings.
207  *
208  * \param[out] forest destination for the trained forest
209  */
210  void
211  train(DecisionForest<NodeType>& forest);
212 
213 private:
214  /** The number of trees to train. */
215  std::size_t num_of_trees_to_train_;
216 
217  /** The trainer for the decision trees of the forest. */
219  decision_tree_trainer_;
220 };
221 
222 } // namespace pcl
223 
224 #include <pcl/ml/impl/dt/decision_forest_trainer.hpp>
pcl::DecisionForestTrainer::setThresholds
void setThresholds(std::vector< float > &thres)
Specify the thresholds to be used when evaluating features.
Definition: decision_forest_trainer.h:175
pcl
This file defines compatibility wrappers for low level I/O functions.
Definition: convolution.h:45
common.h
pcl::DecisionForestTrainer::setExamples
void setExamples(std::vector< ExampleIndex > &examples)
Example indices that specify the data used for training.
Definition: decision_forest_trainer.h:145
pcl::DecisionForestTrainer::setMaxTreeDepth
void setMaxTreeDepth(const std::size_t max_tree_depth)
Sets the maximum depth of the learned tree.
Definition: decision_forest_trainer.h:104
pcl::FeatureHandler
Utility class interface which is used for creating and evaluating features.
Definition: feature_handler.h:49
pcl::DecisionForestTrainer::setNumOfFeatures
void setNumOfFeatures(const std::size_t num_of_features)
Sets the number of features used to find optimal decision features.
Definition: decision_forest_trainer.h:114
pcl::DecisionTreeTrainer
Trainer for decision trees.
Definition: decision_tree_trainer.h:57
pcl::DecisionTreeTrainerDataProvider
Definition: decision_tree_data_provider.h:50
pcl::DecisionForestTrainer
Trainer for decision trees.
Definition: decision_forest_trainer.h:58
pcl::DecisionForestTrainer::setLabelData
void setLabelData(std::vector< LabelType > &label_data)
Sets the label data corresponding to the example data.
Definition: decision_forest_trainer.h:155
pcl::DecisionForestTrainer::setMinExamplesForSplit
void setMinExamplesForSplit(std::size_t n)
Sets the minimum number of examples to continue growing a tree.
Definition: decision_forest_trainer.h:165
pcl::DecisionForestTrainer::setStatsEstimator
void setStatsEstimator(pcl::StatsEstimator< LabelType, NodeType, DataSet, ExampleIndex > &stats_estimator)
Sets the object for estimating the statistics for tree nodes.
Definition: decision_forest_trainer.h:93
pcl::DecisionForest
Class representing a decision forest.
Definition: decision_forest.h:51
pcl::DecisionForestTrainer::setFeatureHandler
void setFeatureHandler(pcl::FeatureHandler< FeatureType, DataSet, ExampleIndex > &feature_handler)
Sets the feature handler used to create and evaluate features.
Definition: decision_forest_trainer.h:82
pcl::StatsEstimator< LabelType, NodeType, DataSet, ExampleIndex >
pcl::DecisionForestTrainer::setDecisionTreeDataProvider
void setDecisionTreeDataProvider(typename pcl::DecisionTreeTrainerDataProvider< FeatureType, DataSet, LabelType, ExampleIndex, NodeType >::Ptr &dtdp)
Specify the data provider.
Definition: decision_forest_trainer.h:186
pcl::DecisionForestTrainer::setRandomFeaturesAtSplitNode
void setRandomFeaturesAtSplitNode(bool b)
Specify if the features are randomly generated at each split node.
Definition: decision_forest_trainer.h:201
pcl::DecisionForestTrainer::setTrainingDataSet
void setTrainingDataSet(DataSet &data_set)
Sets the input data set used for training.
Definition: decision_forest_trainer.h:135
pcl::DecisionForestTrainer::setNumOfThresholds
void setNumOfThresholds(const std::size_t num_of_threshold)
Sets the number of thresholds tested for finding the optimal decision threshold on the feature respon...
Definition: decision_forest_trainer.h:125
PCL_EXPORTS
#define PCL_EXPORTS
Definition: pcl_macros.h:253
pcl::DecisionForestTrainer::setNumberOfTreesToTrain
void setNumberOfTreesToTrain(const std::size_t num_of_trees)
Sets the number of trees to train.
Definition: decision_forest_trainer.h:72