Loading...
Searching...
No Matches
pca.h
/*
* Software License Agreement (BSD License)
*
* Point Cloud Library (PCL) - www.pointclouds.org
* Copyright (c) 2010-2011, Willow Garage, Inc.
*
* All rights reserved.
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions
* are met:
*
* * Redistributions of source code must retain the above copyright
* notice, this list of conditions and the following disclaimer.
* * Redistributions in binary form must reproduce the above
* copyright notice, this list of conditions and the following
* disclaimer in the documentation and/or other materials provided
* with the distribution.
* * Neither the name of the copyright holder(s) nor the names of its
* contributors may be used to endorse or promote products derived
* from this software without specific prior written permission.
*
* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
* "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
* LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
* FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
* COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
* INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
* BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
* LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
* CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
* LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
* ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
* POSSIBILITY OF SUCH DAMAGE.
*
* $Id$
*/
#pragma once
#include <pcl/pcl_base.h>
#include <pcl/pcl_macros.h>
namespace pcl
{
/** Principal Component analysis (PCA) class.\n
* Principal components are extracted by singular values decomposition on the
* covariance matrix of the centered input cloud. Available data after pca computation
* are:\n
* - The Mean of the input data\n
* - The Eigenvectors: Ordered set of vectors representing the resultant principal components and the eigenspace cartesian basis (right-handed coordinate system).\n
* - The Eigenvalues: Eigenvectors correspondent loadings ordered in descending order.\n\n
* Other methods allow projection in the eigenspace, reconstruction from eigenspace and
* update of the eigenspace with a new datum (according Matej Artec, Matjaz Jogan and
* Ales Leonardis: "Incremental PCA for On-line Visual Learning and Recognition").
*
* \author Nizar Sallem
* \ingroup common
*/
template <typename PointT>
class PCA : public pcl::PCLBase <PointT>
{
public:
using Base = pcl::PCLBase<PointT>;
using PointCloud = typename Base::PointCloud;
using PointCloudPtr = typename Base::PointCloudPtr;
using PointCloudConstPtr = typename Base::PointCloudConstPtr;
using PointIndicesPtr = typename Base::PointIndicesPtr;
using PointIndicesConstPtr = typename Base::PointIndicesConstPtr;
using Base::input_;
using Base::indices_;
using Base::initCompute;
using Base::setInputCloud;
/** Updating method flag */
enum FLAG
{
/** keep the new basis vectors if possible */
increase,
/** preserve subspace dimension */
preserve
};
/** \brief Default Constructor
* \param basis_only flag to compute only the PCA basis
*/
PCA (bool basis_only = false)
: Base ()
, basis_only_ (basis_only)
{}
/** Copy Constructor
* \param[in] pca PCA object
*/
PCA (PCA const & pca)
: Base (pca)
, compute_done_ (pca.compute_done_)
, basis_only_ (pca.basis_only_)
, eigenvectors_ (pca.eigenvectors_)
, coefficients_ (pca.coefficients_)
, mean_ (pca.mean_)
, eigenvalues_ (pca.eigenvalues_)
{}
/** Assignment operator
* \param[in] pca PCA object
*/
inline PCA&
operator= (PCA const & pca)
{
eigenvectors_ = pca.eigenvectors_;
coefficients_ = pca.coefficients_;
eigenvalues_ = pca.eigenvalues_;
mean_ = pca.mean_;
return (*this);
}
/** \brief Provide a pointer to the input dataset
* \param cloud the const boost shared pointer to a PointCloud message
*/
inline void
setInputCloud (const PointCloudConstPtr &cloud) override
{
Base::setInputCloud (cloud);
compute_done_ = false;
}
/** \brief Provide a pointer to the vector of indices that represents the input data.
* \param[in] indices a pointer to the indices that represent the input data.
*/
void
setIndices (const IndicesPtr &indices) override
{
Base::setIndices (indices);
compute_done_ = false;
}
/** \brief Provide a pointer to the vector of indices that represents the input data.
* \param[in] indices a pointer to the indices that represent the input data.
*/
void
setIndices (const IndicesConstPtr &indices) override
{
Base::setIndices (indices);
compute_done_ = false;
}
/** \brief Provide a pointer to the vector of indices that represents the input data.
* \param[in] indices a pointer to the indices that represent the input data.
*/
void
setIndices (const PointIndicesConstPtr &indices) override
{
Base::setIndices (indices);
compute_done_ = false;
}
/** \brief Set the indices for the points laying within an interest region of
* the point cloud.
* \note you shouldn't call this method on unorganized point clouds!
* \param[in] row_start the offset on rows
* \param[in] col_start the offset on columns
* \param[in] nb_rows the number of rows to be considered row_start included
* \param[in] nb_cols the number of columns to be considered col_start included
*/
void
setIndices (std::size_t row_start, std::size_t col_start, std::size_t nb_rows, std::size_t nb_cols) override
{
Base::setIndices (row_start, col_start, nb_rows, nb_cols);
compute_done_ = false;
}
/** \brief Mean accessor
* \throw InitFailedException
*/
inline Eigen::Vector4f&
getMean ()
{
if (!compute_done_)
initCompute ();
if (!compute_done_)
PCL_THROW_EXCEPTION (InitFailedException,
"[pcl::PCA::getMean] PCA initCompute failed");
return (mean_);
}
/** Eigen Vectors accessor
* \return Column ordered eigenvectors, representing the eigenspace cartesian basis (right-handed coordinate system).
* \throw InitFailedException
*/
inline Eigen::Matrix3f&
getEigenVectors ()
{
if (!compute_done_)
initCompute ();
if (!compute_done_)
PCL_THROW_EXCEPTION (InitFailedException,
"[pcl::PCA::getEigenVectors] PCA initCompute failed");
return (eigenvectors_);
}
/** Eigen Values accessor
* \throw InitFailedException
*/
inline Eigen::Vector3f&
getEigenValues ()
{
if (!compute_done_)
initCompute ();
if (!compute_done_)
PCL_THROW_EXCEPTION (InitFailedException,
"[pcl::PCA::getEigenVectors] PCA getEigenValues failed");
return (eigenvalues_);
}
/** Coefficients accessor
* \throw InitFailedException
*/
inline Eigen::MatrixXf&
getCoefficients ()
{
if (!compute_done_)
initCompute ();
if (!compute_done_)
PCL_THROW_EXCEPTION (InitFailedException,
"[pcl::PCA::getEigenVectors] PCA getCoefficients failed");
return (coefficients_);
}
/** update PCA with a new point
* \param[in] input input point
* \param[in] flag update flag
* \throw InitFailedException
*/
inline void
update (const PointT& input, FLAG flag = preserve);
/** Project point on the eigenspace.
* \param[in] input point from original dataset
* \param[out] projection the point in eigen vectors space
* \throw InitFailedException
*/
inline void
project (const PointT& input, PointT& projection);
/** Project cloud on the eigenspace.
* \param[in] input cloud from original dataset
* \param[out] projection the cloud in eigen vectors space
* \throw InitFailedException
*/
inline void
project (const PointCloud& input, PointCloud& projection);
/** Reconstruct point from its projection
* \param[in] projection point from eigenvector space
* \param[out] input reconstructed point
* \throw InitFailedException
*/
inline void
reconstruct (const PointT& projection, PointT& input);
/** Reconstruct cloud from its projection
* \param[in] projection cloud from eigenvector space
* \param[out] input reconstructed cloud
* \throw InitFailedException
*/
inline void
reconstruct (const PointCloud& projection, PointCloud& input);
private:
inline bool
initCompute ();
bool compute_done_{false};
bool basis_only_;
Eigen::Matrix3f eigenvectors_;
Eigen::MatrixXf coefficients_;
Eigen::Vector4f mean_;
Eigen::Vector3f eigenvalues_;
}; // class PCA
} // namespace pcl
#include <pcl/common/impl/pca.hpp>
pcl::InitFailedException
An exception thrown when init can not be performed should be used in all the PCLBase class inheritant...
Definition exceptions.h:197
pcl::PCA
Principal Component analysis (PCA) class.
Definition pca.h:62
pcl::PCA::PointCloudConstPtr
typename Base::PointCloudConstPtr PointCloudConstPtr
Definition pca.h:67
pcl::PCA::setInputCloud
void setInputCloud(const PointCloudConstPtr &cloud) override
Provide a pointer to the input dataset.
Definition pca.h:123
pcl::PCA::FLAG
FLAG
Updating method flag.
Definition pca.h:78
pcl::PCA::preserve
@ preserve
preserve subspace dimension
Definition pca.h:82
pcl::PCA::increase
@ increase
keep the new basis vectors if possible
Definition pca.h:80
pcl::PCA::project
void project(const PointT &input, PointT &projection)
Project point on the eigenspace.
Definition pca.hpp:166
pcl::PCA::update
void update(const PointT &input, FLAG flag=preserve)
update PCA with a new point
Definition pca.hpp:96
pcl::PCA::getEigenVectors
Eigen::Matrix3f & getEigenVectors()
Eigen Vectors accessor.
Definition pca.h:193
pcl::PCA::Base
pcl::PCLBase< PointT > Base
Definition pca.h:64
pcl::PCA::getMean
Eigen::Vector4f & getMean()
Mean accessor.
Definition pca.h:178
pcl::PCA::operator=
PCA & operator=(PCA const &pca)
Assignment operator.
Definition pca.h:110
pcl::PCA::setIndices
void setIndices(std::size_t row_start, std::size_t col_start, std::size_t nb_rows, std::size_t nb_cols) override
Set the indices for the points laying within an interest region of the point cloud.
Definition pca.h:168
pcl::PCA::getCoefficients
Eigen::MatrixXf & getCoefficients()
Coefficients accessor.
Definition pca.h:221
pcl::PCA::PointCloudPtr
typename Base::PointCloudPtr PointCloudPtr
Definition pca.h:66
pcl::PCA::PCA
PCA(bool basis_only=false)
Default Constructor.
Definition pca.h:88
pcl::PCA::PCA
PCA(PCA const &pca)
Copy Constructor.
Definition pca.h:96
pcl::PCA::setIndices
void setIndices(const PointIndicesConstPtr &indices) override
Provide a pointer to the vector of indices that represents the input data.
Definition pca.h:153
pcl::PCA::PointIndicesConstPtr
typename Base::PointIndicesConstPtr PointIndicesConstPtr
Definition pca.h:69
pcl::PCA::getEigenValues
Eigen::Vector3f & getEigenValues()
Eigen Values accessor.
Definition pca.h:207
pcl::PCA::PointCloud
typename Base::PointCloud PointCloud
Definition pca.h:65
pcl::PCA::setIndices
void setIndices(const IndicesConstPtr &indices) override
Provide a pointer to the vector of indices that represents the input data.
Definition pca.h:143
pcl::PCA::reconstruct
void reconstruct(const PointT &projection, PointT &input)
Reconstruct point from its projection.
Definition pca.hpp:208
pcl::PCA::setIndices
void setIndices(const IndicesPtr &indices) override
Provide a pointer to the vector of indices that represents the input data.
Definition pca.h:133
pcl::PCA::PointIndicesPtr
typename Base::PointIndicesPtr PointIndicesPtr
Definition pca.h:68
pcl::PCLBase
PCL base class.
Definition pcl_base.h:70
pcl::PCLBase::input_
PointCloudConstPtr input_
The input point cloud dataset.
Definition pcl_base.h:147
pcl::PCLBase::setInputCloud
virtual void setInputCloud(const PointCloudConstPtr &cloud)
Provide a pointer to the input dataset.
Definition pcl_base.hpp:65
pcl::PCLBase::PointCloudPtr
typename PointCloud::Ptr PointCloudPtr
Definition pcl_base.h:73
pcl::PCLBase::PointCloudConstPtr
typename PointCloud::ConstPtr PointCloudConstPtr
Definition pcl_base.h:74
pcl::PCLBase::PointCloud
pcl::PointCloud< PointT > PointCloud
Definition pcl_base.h:72
pcl::PCLBase::indices_
IndicesPtr indices_
A pointer to the vector of point indices to use.
Definition pcl_base.h:150
pcl::PCLBase::setIndices
virtual void setIndices(const IndicesPtr &indices)
Provide a pointer to the vector of indices that represents the input data.
Definition pcl_base.hpp:72
pcl::PCLBase::initCompute
bool initCompute()
This method should get called before starting the actual computation.
Definition pcl_base.hpp:138
pcl::PCLBase::PointIndicesConstPtr
PointIndices::ConstPtr PointIndicesConstPtr
Definition pcl_base.h:77
pcl::PCLBase::PointIndicesPtr
PointIndices::Ptr PointIndicesPtr
Definition pcl_base.h:76
pcl::PointCloud
PointCloud represents the base class in PCL for storing collections of 3D points.
Definition point_cloud.h:174
pcl
Definition convolution.h:46
pcl::IndicesPtr
shared_ptr< Indices > IndicesPtr
Definition pcl_base.h:58
pcl::IndicesConstPtr
shared_ptr< const Indices > IndicesConstPtr
Definition pcl_base.h:59
pcl_macros.h
Defines all the PCL and non-PCL macros used.