iLab Neuromorphic Robotics Toolkit  0.1
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
ModelBase.H
Go to the documentation of this file.
1 /*! @file
2  @author Shane Grant
3  @copyright GNU Public License (GPL v3)
4  @section License
5  @verbatim
6  // ////////////////////////////////////////////////////////////////////////
7  // The iLab Neuromorphic Robotics Toolkit (NRT) //
8  // Copyright 2010-2012 by the University of Southern California (USC) //
9  // and the iLab at USC. //
10  // //
11  // iLab - University of Southern California //
12  // Hedco Neurociences Building, Room HNB-10 //
13  // Los Angeles, Ca 90089-2520 - USA //
14  // //
15  // See http://ilab.usc.edu for information about this project. //
16  // ////////////////////////////////////////////////////////////////////////
17  // This file is part of The iLab Neuromorphic Robotics Toolkit. //
18  // //
19  // The iLab Neuromorphic Robotics Toolkit is free software: you can //
20  // redistribute it and/or modify it under the terms of the GNU General //
21  // Public License as published by the Free Software Foundation, either //
22  // version 3 of the License, or (at your option) any later version. //
23  // //
24  // The iLab Neuromorphic Robotics Toolkit is distributed in the hope //
25  // that it will be useful, but WITHOUT ANY WARRANTY; without even the //
26  // implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR //
27  // PURPOSE. See the GNU General Public License for more details. //
28  // //
29  // You should have received a copy of the GNU General Public License //
30  // along with The iLab Neuromorphic Robotics Toolkit. If not, see //
31  // <http://www.gnu.org/licenses/>. //
32  // ////////////////////////////////////////////////////////////////////////
33  @endverbatim */
34 
35 #ifdef NRT_HAVE_CLOUD
36 #ifndef INCLUDE_NRT_POINTCLOUD2_SAMPLECONCENSUS_MODELS_MODELBASE_H_
37 #define INCLUDE_NRT_POINTCLOUD2_SAMPLECONCENSUS_MODELS_MODELBASE_H_
38 
39 #include <memory>
40 #include <random>
41 
44 
45 namespace nrt
46 {
47  //! Interface for all sample concensus methods
48  class ModelBase : public SourceCloud
49  {
50  typedef PointCloud2::VectorX VectorX;
51 
52  public:
53  //! Convenience typedef for shared ptr to this
54  typedef std::shared_ptr<ModelBase> SharedPtr;
55 
56  //! A function that returns true if a set of points returns a valid sample
57  /*! A validation function takes in a set of indices that correspond to indices from the
58  point cloud (regardless of whether a subset was used) that should be evaluated as to
59  whether the values at these indices can produce a valid model.
60 
61  The typical way to create one of these functions is to capture relevant information in
62  a lambda function or some functor, e.g.:
63 
64  @code
65  MyCoolModel model( myCloud,
66  [myCloud]( Indices const & indices )
67  {
68  for( auto point : myCloud.const_subset_range( indices ) )
69  // do something with the points
70  return true;
71  },
72  other_parameters... );
73  @endcode
74 
75  Be sure to capture any copy on write data by value unless you can be sure that it will
76  be accessed in a thread safe manner. Also be careful to utilize const accessors for
77  your point cloud or other data if you will not be modifying it */
78  typedef std::function<bool(Indices const &)> SampleValidFunction;
79 
80  //! Constructor with no subset
81  /*! @param source The source cloud
82  @param func The function to evaluate whether a set of samples is valid
83  @param inlierThreshold Distance threshold to use for select and countWithinDistance()
84  @param sampleMaxIterations Maximum number of iterations to use during sample selection
85  @param seedRandom If true, the random number generator will be seeded with
86  the current time, otherwise it will always
87  receive the same default seed */
88  ModelBase( PointCloud2 const source,
90  double inlierThreshold = std::numeric_limits<double>::max(),
91  size_t sampleMaxIterations = 1000,
92  bool seedRandom = false );
93 
94  //! Constructor with a subset
95  /*! @param source The point cloud to use
96  @param indices The subset of the cloud to consider
97  @param func The function to evaluate whether a set of samples is valid
98  @param inlierThreshold Distance threshold to use for select and countWithinDistance()
99  @param sampleMaxIterations Maximum number of iterations to use during sample selection
100  @param seedRandom If true, the random number generator will be seeded with
101  the current time, otherwise it will always
102  receive the same default seed */
103  ModelBase( PointCloud2 const source, Indices const indices,
104  SampleValidFunction func,
105  double inlierThreshold = std::numeric_limits<double>::max(),
106  size_t sampleMaxIterations = 1000,
107  bool seedRandom = false );
108 
109  //! Virtual destructor
110  virtual ~ModelBase();
111 
112  //! Generates a set of randomly chosen indices according to the
113  //! models minimum sample size
114  /*! @return The indices that made a valid sample */
115  Indices getSamples() const;
116 
117  //! Returns the minimum valid sample size for the model
118  virtual size_t getSampleSize() const = 0;
119 
120  //! Attempts to form a valid model from the points at the selected indices
121  /*! @param sampleIndices The valid indices (check with itsIsSampleValidFunction() ) to use
122  @return The coefficients for the model */
123  virtual VectorX computeModelCoefficients( Indices const sampleIndices ) const = 0;
124 
125  //! Recomputes the model coefficients using the provided inlier indices
126  /*! This can be called after inliers have been computed to refine a solution
127  @param inlierIndices The inlier indices
128  @param modelCoefficients The coefficients found via computeModelCoefficients()
129  @return The optimized set of model coefficients */
130  virtual VectorX optimizeModelCoefficients( Indices const inlierIndices,
131  VectorX const & modelCoefficients ) const = 0;
132 
133  //! Computes distances from transformed points to their correspondences
134  virtual std::vector<double> getDistancesToModel( VectorX const & modelCoefficients ) const = 0;
135 
136  //! Selects all points from the input data set that are inliers under the model according
137  //! to some threshold
138  virtual Indices selectWithinDistance( VectorX const & modelCoefficients ) const = 0;
139 
140  //! Counts all of the points which respect the model coefficients that are inliers
141  virtual int countWithinDistance( VectorX const & modelCoefficients ) const = 0;
142 
143  protected:
144  //! The input point cloud
146 
147  //! Evaluates whether a set of indices is valid
149 
150  const double itsInlierThreshold; //!< used during sample selection
151 
152  const size_t itsSampleMaxIterations; //!< distance threshold for selection and counting
153 
154  //! The random number generator
155  mutable std::mt19937 itsRNG;
156  };
157 } //namespace nrt
158 
159 #endif // INCLUDE_NRT_POINTCLOUD2_SAMPLECONCENSUS_MODELS_MODELBASE_H_
160 #endif // NRT_HAVE_CLOUD