Point Cloud Library (PCL)  1.8.1-dev
pca.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 the copyright holder(s) 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  * $Id$
37  */
38 
39 #ifndef PCL_PCA_H
40 #define PCL_PCA_H
41 
42 #include <pcl/pcl_base.h>
43 #include <pcl/pcl_macros.h>
44 
45 namespace pcl
46 {
47  /** Principal Component analysis (PCA) class.\n
48  * Principal components are extracted by singular values decomposition on the
49  * covariance matrix of the centered input cloud. Available data after pca computation
50  * are the mean of the input data, the eigenvalues (in descending order) and
51  * corresponding eigenvectors.\n
52  * Other methods allow projection in the eigenspace, reconstruction from eigenspace and
53  * update of the eigenspace with a new datum (according Matej Artec, Matjaz Jogan and
54  * Ales Leonardis: "Incremental PCA for On-line Visual Learning and Recognition").
55  *
56  * \author Nizar Sallem
57  * \ingroup common
58  */
59  template <typename PointT>
60  class PCA : public pcl::PCLBase <PointT>
61  {
62  public:
64  typedef typename Base::PointCloud PointCloud;
69 
70  using Base::input_;
71  using Base::indices_;
72  using Base::initCompute;
73  using Base::setInputCloud;
74 
75  /** Updating method flag */
76  enum FLAG
77  {
78  /** keep the new basis vectors if possible */
80  /** preserve subspace dimension */
82  };
83 
84  /** \brief Default Constructor
85  * \param basis_only flag to compute only the PCA basis
86  */
87  PCA (bool basis_only = false)
88  : Base ()
89  , compute_done_ (false)
90  , basis_only_ (basis_only)
91  , eigenvectors_ ()
92  , coefficients_ ()
93  , mean_ ()
94  , eigenvalues_ ()
95  {}
96 
97  /** Copy Constructor
98  * \param[in] pca PCA object
99  */
100  PCA (PCA const & pca)
101  : Base (pca)
102  , compute_done_ (pca.compute_done_)
103  , basis_only_ (pca.basis_only_)
104  , eigenvectors_ (pca.eigenvectors_)
105  , coefficients_ (pca.coefficients_)
106  , mean_ (pca.mean_)
107  , eigenvalues_ (pca.eigenvalues_)
108  {}
109 
110  /** Assignment operator
111  * \param[in] pca PCA object
112  */
113  inline PCA&
114  operator= (PCA const & pca)
115  {
116  eigenvectors_ = pca.eigenvectors_;
117  coefficients_ = pca.coefficients_;
118  eigenvalues_ = pca.eigenvalues_;
119  mean_ = pca.mean_;
120  return (*this);
121  }
122 
123  /** \brief Provide a pointer to the input dataset
124  * \param cloud the const boost shared pointer to a PointCloud message
125  */
126  inline void
128  {
129  Base::setInputCloud (cloud);
130  compute_done_ = false;
131  }
132 
133  /** \brief Provide a pointer to the vector of indices that represents the input data.
134  * \param[in] indices a pointer to the indices that represent the input data.
135  */
136  virtual void
137  setIndices (const IndicesPtr &indices)
138  {
139  Base::setIndices (indices);
140  compute_done_ = false;
141  }
142 
143  /** \brief Provide a pointer to the vector of indices that represents the input data.
144  * \param[in] indices a pointer to the indices that represent the input data.
145  */
146  virtual void
147  setIndices (const IndicesConstPtr &indices)
148  {
149  Base::setIndices (indices);
150  compute_done_ = false;
151  }
152 
153  /** \brief Provide a pointer to the vector of indices that represents the input data.
154  * \param[in] indices a pointer to the indices that represent the input data.
155  */
156  virtual void
158  {
159  Base::setIndices (indices);
160  compute_done_ = false;
161  }
162 
163  /** \brief Set the indices for the points laying within an interest region of
164  * the point cloud.
165  * \note you shouldn't call this method on unorganized point clouds!
166  * \param[in] row_start the offset on rows
167  * \param[in] col_start the offset on columns
168  * \param[in] nb_rows the number of rows to be considered row_start included
169  * \param[in] nb_cols the number of columns to be considered col_start included
170  */
171  virtual void
172  setIndices (size_t row_start, size_t col_start, size_t nb_rows, size_t nb_cols)
173  {
174  Base::setIndices (row_start, col_start, nb_rows, nb_cols);
175  compute_done_ = false;
176  }
177 
178  /** \brief Mean accessor
179  * \throw InitFailedException
180  */
181  inline Eigen::Vector4f&
183  {
184  if (!compute_done_)
185  initCompute ();
186  if (!compute_done_)
187  PCL_THROW_EXCEPTION (InitFailedException,
188  "[pcl::PCA::getMean] PCA initCompute failed");
189  return (mean_);
190  }
191 
192  /** Eigen Vectors accessor
193  * \throw InitFailedException
194  */
195  inline Eigen::Matrix3f&
197  {
198  if (!compute_done_)
199  initCompute ();
200  if (!compute_done_)
201  PCL_THROW_EXCEPTION (InitFailedException,
202  "[pcl::PCA::getEigenVectors] PCA initCompute failed");
203  return (eigenvectors_);
204  }
205 
206  /** Eigen Values accessor
207  * \throw InitFailedException
208  */
209  inline Eigen::Vector3f&
211  {
212  if (!compute_done_)
213  initCompute ();
214  if (!compute_done_)
215  PCL_THROW_EXCEPTION (InitFailedException,
216  "[pcl::PCA::getEigenVectors] PCA getEigenValues failed");
217  return (eigenvalues_);
218  }
219 
220  /** Coefficients accessor
221  * \throw InitFailedException
222  */
223  inline Eigen::MatrixXf&
225  {
226  if (!compute_done_)
227  initCompute ();
228  if (!compute_done_)
229  PCL_THROW_EXCEPTION (InitFailedException,
230  "[pcl::PCA::getEigenVectors] PCA getCoefficients failed");
231  return (coefficients_);
232  }
233 
234  /** update PCA with a new point
235  * \param[in] input input point
236  * \param[in] flag update flag
237  * \throw InitFailedException
238  */
239  inline void
240  update (const PointT& input, FLAG flag = preserve);
241 
242  /** Project point on the eigenspace.
243  * \param[in] input point from original dataset
244  * \param[out] projection the point in eigen vectors space
245  * \throw InitFailedException
246  */
247  inline void
248  project (const PointT& input, PointT& projection);
249 
250  /** Project cloud on the eigenspace.
251  * \param[in] input cloud from original dataset
252  * \param[out] projection the cloud in eigen vectors space
253  * \throw InitFailedException
254  */
255  inline void
256  project (const PointCloud& input, PointCloud& projection);
257 
258  /** Reconstruct point from its projection
259  * \param[in] projection point from eigenvector space
260  * \param[out] input reconstructed point
261  * \throw InitFailedException
262  */
263  inline void
264  reconstruct (const PointT& projection, PointT& input);
265 
266  /** Reconstruct cloud from its projection
267  * \param[in] projection cloud from eigenvector space
268  * \param[out] input reconstructed cloud
269  * \throw InitFailedException
270  */
271  inline void
272  reconstruct (const PointCloud& projection, PointCloud& input);
273 
274  private:
275  inline bool
276  initCompute ();
277 
278  bool compute_done_;
279  bool basis_only_;
280  Eigen::Matrix3f eigenvectors_;
281  Eigen::MatrixXf coefficients_;
282  Eigen::Vector4f mean_;
283  Eigen::Vector3f eigenvalues_;
284  }; // class PCA
285 } // namespace pcl
286 
287 #include <pcl/common/impl/pca.hpp>
288 
289 #endif // PCL_PCA_H
290 
Base::PointCloud PointCloud
Definition: pca.h:64
Principal Component analysis (PCA) class.
Definition: pca.h:60
PointCloud::ConstPtr PointCloudConstPtr
Definition: pcl_base.h:73
preserve subspace dimension
Definition: pca.h:81
boost::shared_ptr< std::vector< int > > IndicesPtr
Definition: pcl_base.h:60
Base::PointCloudPtr PointCloudPtr
Definition: pca.h:65
FLAG
Updating method flag.
Definition: pca.h:76
PCA & operator=(PCA const &pca)
Assignment operator.
Definition: pca.h:114
Base::PointCloudConstPtr PointCloudConstPtr
Definition: pca.h:66
IndicesPtr indices_
A pointer to the vector of point indices to use.
Definition: pcl_base.h:153
Base::PointIndicesConstPtr PointIndicesConstPtr
Definition: pca.h:68
virtual void setIndices(size_t row_start, size_t col_start, size_t nb_rows, size_t nb_cols)
Set the indices for the points laying within an interest region of the point cloud.
Definition: pca.h:172
virtual void setIndices(const PointIndicesConstPtr &indices)
Provide a pointer to the vector of indices that represents the input data.
Definition: pca.h:157
boost::shared_ptr< PointIndices > PointIndicesPtr
Definition: pcl_base.h:75
pcl::PCLBase< PointT > Base
Definition: pca.h:63
void update(const PointT &input, FLAG flag=preserve)
update PCA with a new point
Definition: pca.hpp:91
virtual void setIndices(const IndicesPtr &indices)
Provide a pointer to the vector of indices that represents the input data.
Definition: pca.h:137
bool initCompute()
This method should get called before starting the actual computation.
Definition: pcl_base.hpp:139
PointCloud::Ptr PointCloudPtr
Definition: pcl_base.h:72
PCA(PCA const &pca)
Copy Constructor.
Definition: pca.h:100
void reconstruct(const PointT &projection, PointT &input)
Reconstruct point from its projection.
Definition: pca.hpp:203
void project(const PointT &input, PointT &projection)
Project point on the eigenspace.
Definition: pca.hpp:161
boost::shared_ptr< PointIndices const > PointIndicesConstPtr
Definition: pcl_base.h:76
PCL base class.
Definition: pcl_base.h:68
An exception thrown when init can not be performed should be used in all the PCLBase class inheritant...
Definition: exceptions.h:194
Eigen::Vector4f & getMean()
Mean accessor.
Definition: pca.h:182
virtual void setIndices(const IndicesPtr &indices)
Provide a pointer to the vector of indices that represents the input data.
Definition: pcl_base.hpp:73
Base::PointIndicesPtr PointIndicesPtr
Definition: pca.h:67
Eigen::Matrix3f & getEigenVectors()
Eigen Vectors accessor.
Definition: pca.h:196
Eigen::MatrixXf & getCoefficients()
Coefficients accessor.
Definition: pca.h:224
PCA(bool basis_only=false)
Default Constructor.
Definition: pca.h:87
virtual void setInputCloud(const PointCloudConstPtr &cloud)
Provide a pointer to the input dataset.
Definition: pcl_base.hpp:66
boost::shared_ptr< const std::vector< int > > IndicesConstPtr
Definition: pcl_base.h:61
Eigen::Vector3f & getEigenValues()
Eigen Values accessor.
Definition: pca.h:210
PointCloudConstPtr input_
The input point cloud dataset.
Definition: pcl_base.h:150
keep the new basis vectors if possible
Definition: pca.h:79
A point structure representing Euclidean xyz coordinates, and the RGB color.
void setInputCloud(const PointCloudConstPtr &cloud)
Provide a pointer to the input dataset.
Definition: pca.h:127
virtual void setIndices(const IndicesConstPtr &indices)
Provide a pointer to the vector of indices that represents the input data.
Definition: pca.h:147