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