gasd.h
/*
* Software License Agreement (BSD License)
*
* Point Cloud Library (PCL) - www.pointclouds.org
* Copyright (c) 2016-, Open Perception, Inc.
* Copyright (c) 2016, Voxar Labs, CIn-UFPE / DEINFO-UFRPE
*
* 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.
*
*/
#pragma once
#include <pcl/features/feature.h>
namespace pcl
{
/// Different histogram interpolation methods
enum HistogramInterpolationMethod
{
INTERP_NONE, ///< no interpolation
INTERP_TRILINEAR, ///< trilinear interpolation
INTERP_QUADRILINEAR ///< quadrilinear interpolation
};
/** \brief GASDEstimation estimates the Globally Aligned Spatial Distribution (GASD) descriptor for a given
* point cloud dataset given XYZ data.
*
* The suggested PointOutT is pcl::GASDSignature512.
*
* \note If you use this code in any academic work, please cite:
*
* - J. Lima, V. Teichrieb.
* An Efficient Global Point Cloud Descriptor for Object Recognition and Pose Estimation.
* In Proceedings of the 29th SIBGRAPI - Conference on Graphics, Patterns and Images,
* Sao Jose dos Campos, Brazil, October 4-7 2016.
*
* \author Joao Paulo Lima
*
* Voxar Labs, Centro de Informatica, Universidade Federal de Pernambuco, Brazil
*
* Departamento de Estatistica e Informatica, Universidade Federal Rural de Pernambuco, Brazil
*
* \ingroup features
*/
template <typename PointInT, typename PointOutT = GASDSignature512>
class GASDEstimation : public Feature<PointInT, PointOutT>
{
public:
using typename Feature<PointInT, PointOutT>::PointCloudIn;
using typename Feature<PointInT, PointOutT>::PointCloudOut;
using Ptr = shared_ptr<GASDEstimation<PointInT, PointOutT> >;
using ConstPtr = shared_ptr<const GASDEstimation<PointInT, PointOutT> >;
/** \brief Constructor.
* \param[in] view_direction view direction
* \param[in] shape_half_grid_size shape half grid size
* \param[in] shape_hists_size shape histograms size
* \param[in] shape_interp shape histograms interpolation method
*/
GASDEstimation (const Eigen::Vector3f &view_direction = Eigen::Vector3f (0.0f, 0.0f, 1.0f),
const std::size_t shape_half_grid_size = 4,
const std::size_t shape_hists_size = 1,
const HistogramInterpolationMethod shape_interp = INTERP_TRILINEAR) :
view_direction_ (view_direction),
shape_half_grid_size_ (shape_half_grid_size),
shape_hists_size_ (shape_hists_size),
shape_interp_ (shape_interp)
{
search_radius_ = 0;
k_ = 1;
feature_name_ = "GASDEstimation";
}
/** \brief Set the view direction.
* \param[in] dir view direction
*/
inline void
setViewDirection (const Eigen::Vector3f &dir)
{
view_direction_ = dir;
}
/** \brief Set the shape half grid size.
* \param[in] shgs shape half grid size
*/
inline void
setShapeHalfGridSize (const std::size_t shgs)
{
shape_half_grid_size_ = shgs;
}
/** \brief Set the shape histograms size. If size is 1, then each histogram bin will store the number
* of points that belong to its correspondent cell in the 3D regular grid. If size > 1, then for each cell
* it will be computed a histogram of normalized distances between each sample and the cloud centroid
* \param[in] shs shape histograms size
*/
inline void
setShapeHistsSize (const std::size_t shs)
{
shape_hists_size_ = shs;
}
/** \brief Set the shape histograms interpolation method.
* \param[in] interp shape histograms interpolation method
*/
inline void
setShapeHistsInterpMethod (const HistogramInterpolationMethod interp)
{
shape_interp_ = interp;
}
/**
* \brief Returns the transformation aligning the point cloud to the canonical coordinate system
*/
const Eigen::Matrix4f&
getTransform () const
{
return transform_;
}
/** \brief Overloaded computed method from pcl::Feature.
* \param[out] output the resultant point cloud model dataset containing the estimated feature
*/
void
compute (PointCloudOut &output);
protected:
using Feature<PointInT, PointOutT>::feature_name_;
using Feature<PointInT, PointOutT>::getClassName;
using Feature<PointInT, PointOutT>::indices_;
using Feature<PointInT, PointOutT>::k_;
using Feature<PointInT, PointOutT>::search_radius_;
using Feature<PointInT, PointOutT>::surface_;
/** \brief Point cloud aligned to the canonical coordinate system. */
PointCloudIn shape_samples_;
/** \brief Normalization factor with respect to axis-aligned bounding cube centered on the origin. */
float max_coord_;
/** \brief Normalized sample contribution with respect to the total number of points in the cloud. */
float hist_incr_;
/** \brief Current position of output descriptor point cloud. */
std::size_t pos_;
/** \brief add a sample to its respective histogram, optionally performing interpolation.
* \param[in] p histogram sample
* \param[in] max_coord normalization factor with respect to axis-aligned bounding cube centered on the origin
* \param[in] half_grid_size half size of the regular grid used to compute the descriptor
* \param[in] interp interpolation method to be used while computing the descriptor
* \param[in] hbin histogram bin
* \param[in] hist_incr normalization factor of sample contribution
* \param[in,out] hists updated histograms
*/
void
addSampleToHistograms (const Eigen::Vector4f &p,
const float max_coord,
const std::size_t half_grid_size,
const HistogramInterpolationMethod interp,
const float hbin,
const float hist_incr,
std::vector<Eigen::VectorXf> &hists);
/** \brief Estimate GASD descriptor
*
* \param[out] output the resultant point cloud model dataset containing the GASD feature
*/
void
computeFeature (PointCloudOut &output) override;
private:
/** \brief Transform that aligns the point cloud to the canonical coordinate system. */
Eigen::Matrix4f transform_;
/** \brief Viewing direction, default value is (0, 0, 1). */
Eigen::Vector3f view_direction_;
/** \brief Half size of the regular grid used to compute the shape descriptor. */
std::size_t shape_half_grid_size_;
/** \brief Size of the histograms of normalized distances between each sample and the cloud centroid. */
std::size_t shape_hists_size_;
/** \brief Interpolation method to be used while computing the shape descriptor. */
HistogramInterpolationMethod shape_interp_;
/** \brief Estimates a reference frame for the point cloud and uses it to compute a transform that aligns the point cloud to the canonical coordinate system. */
void
computeAlignmentTransform ();
/** \brief copy computed shape histograms to output descriptor point cloud
* \param[in] grid_size size of the regular grid used to compute the descriptor
* \param[in] hists_size size of the shape histograms
* \param[in] hists shape histograms
* \param[out] output output descriptor point cloud
* \param[in,out] pos current position of output descriptor point cloud
*/
void
copyShapeHistogramsToOutput (const std::size_t grid_size,
const std::size_t hists_size,
const std::vector<Eigen::VectorXf> &hists,
PointCloudOut &output,
std::size_t &pos);
};
/** \brief GASDColorEstimation estimates the Globally Aligned Spatial Distribution (GASD) descriptor for a given
* point cloud dataset given XYZ and RGB data.
*
* The suggested PointOutT is pcl::GASDSignature984.
*
* \note If you use this code in any academic work, please cite:
*
* - J. Lima, V. Teichrieb.
* An Efficient Global Point Cloud Descriptor for Object Recognition and Pose Estimation.
* In Proceedings of the 29th SIBGRAPI - Conference on Graphics, Patterns and Images,
* Sao Jose dos Campos, Brazil, October 4-7 2016.
*
* \author Joao Paulo Lima
*
* Voxar Labs, Centro de Informatica, Universidade Federal de Pernambuco, Brazil
*
* Departamento de Estatistica e Informatica, Universidade Federal Rural de Pernambuco, Brazil
*
* \ingroup features
*/
template <typename PointInT, typename PointOutT = GASDSignature984>
class GASDColorEstimation : public GASDEstimation<PointInT, PointOutT>
{
public:
using typename Feature<PointInT, PointOutT>::PointCloudOut;
using Ptr = shared_ptr<GASDColorEstimation<PointInT, PointOutT> >;
using ConstPtr = shared_ptr<const GASDColorEstimation<PointInT, PointOutT> >;
/** \brief Constructor.
* \param[in] view_direction view direction
* \param[in] shape_half_grid_size shape half grid size
* \param[in] shape_hists_size shape histograms size
* \param[in] color_half_grid_size color half grid size
* \param[in] color_hists_size color histograms size
* \param[in] shape_interp shape histograms interpolation method
* \param[in] color_interp color histograms interpolation method
*/
GASDColorEstimation (const Eigen::Vector3f &view_direction = Eigen::Vector3f (0.0f, 0.0f, 1.0f),
const std::size_t shape_half_grid_size = 3,
const std::size_t shape_hists_size = 1,
const std::size_t color_half_grid_size = 2,
const std::size_t color_hists_size = 12,
const HistogramInterpolationMethod shape_interp = INTERP_NONE,
const HistogramInterpolationMethod color_interp = INTERP_NONE) :
GASDEstimation<PointInT, PointOutT> (view_direction, shape_half_grid_size, shape_hists_size, shape_interp),
color_half_grid_size_ (color_half_grid_size),
color_hists_size_ (color_hists_size),
color_interp_ (color_interp)
{
feature_name_ = "GASDColorEstimation";
}
/** \brief Set the color half grid size.
* \param[in] chgs color half grid size
*/
inline void
setColorHalfGridSize (const std::size_t chgs)
{
color_half_grid_size_ = chgs;
}
/** \brief Set the color histograms size (number of bins in the hue histogram for each cell of the 3D regular grid).
* \param[in] chs color histograms size
*/
inline void
setColorHistsSize (const std::size_t chs)
{
color_hists_size_ = chs;
}
/** \brief Set the color histograms interpolation method.
* \param[in] interp color histograms interpolation method
*/
inline void
setColorHistsInterpMethod (const HistogramInterpolationMethod interp)
{
color_interp_ = interp;
}
protected:
using Feature<PointInT, PointOutT>::feature_name_;
using Feature<PointInT, PointOutT>::getClassName;
using Feature<PointInT, PointOutT>::indices_;
using Feature<PointInT, PointOutT>::k_;
using Feature<PointInT, PointOutT>::search_radius_;
using Feature<PointInT, PointOutT>::surface_;
using GASDEstimation<PointInT, PointOutT>::shape_samples_;
using GASDEstimation<PointInT, PointOutT>::max_coord_;
using GASDEstimation<PointInT, PointOutT>::hist_incr_;
using GASDEstimation<PointInT, PointOutT>::pos_;
private:
/** \brief Half size of the regular grid used to compute the color descriptor. */
std::size_t color_half_grid_size_;
/** \brief Size of the hue histograms. */
std::size_t color_hists_size_;
/** \brief Interpolation method to be used while computing the color descriptor. */
HistogramInterpolationMethod color_interp_;
/** \brief copy computed color histograms to output descriptor point cloud
* \param[in] grid_size size of the regular grid used to compute the descriptor
* \param[in] hists_size size of the color histograms
* \param[in,out] hists color histograms, which are finalized, since they are circular
* \param[out] output output descriptor point cloud
* \param[in,out] pos current position of output descriptor point cloud
*/
void
copyColorHistogramsToOutput (const std::size_t grid_size,
const std::size_t hists_size,
std::vector<Eigen::VectorXf> &hists,
PointCloudOut &output,
std::size_t &pos);
/** \brief Estimate GASD color descriptor
*
* \param[out] output the resultant point cloud model dataset containing the GASD color feature
*/
void
computeFeature (PointCloudOut &output) override;
};
} // namespace pcl
#ifdef PCL_NO_PRECOMPILE
#include <pcl/features/impl/gasd.hpp>
#endif
pcl::Feature
Feature represents the base feature class.
Definition: feature.h:107
pcl::Feature< PointInT, GASDSignature512 >::PointCloudOut
pcl::PointCloud< GASDSignature512 > PointCloudOut
Definition: feature.h:124
pcl::Feature< PointInT, GASDSignature512 >::search_radius_
double search_radius_
The nearest neighbors search radius for each point.
Definition: feature.h:240
pcl::Feature< PointInT, GASDSignature512 >::k_
int k_
The number of K nearest neighbors to use for each point.
Definition: feature.h:243
pcl::Feature::Ptr
shared_ptr< Feature< PointInT, PointOutT > > Ptr
Definition: feature.h:114
pcl::Feature< PointInT, GASDSignature512 >::feature_name_
std::string feature_name_
The feature name.
Definition: feature.h:223
pcl::Feature::ConstPtr
shared_ptr< const Feature< PointInT, PointOutT > > ConstPtr
Definition: feature.h:115
pcl::GASDColorEstimation
GASDColorEstimation estimates the Globally Aligned Spatial Distribution (GASD) descriptor for a given...
Definition: gasd.h:257
pcl::GASDColorEstimation::setColorHistsInterpMethod
void setColorHistsInterpMethod(const HistogramInterpolationMethod interp)
Set the color histograms interpolation method.
Definition: gasd.h:309
pcl::GASDColorEstimation::setColorHistsSize
void setColorHistsSize(const std::size_t chs)
Set the color histograms size (number of bins in the hue histogram for each cell of the 3D regular gr...
Definition: gasd.h:300
pcl::GASDColorEstimation::setColorHalfGridSize
void setColorHalfGridSize(const std::size_t chgs)
Set the color half grid size.
Definition: gasd.h:291
pcl::GASDColorEstimation::GASDColorEstimation
GASDColorEstimation(const Eigen::Vector3f &view_direction=Eigen::Vector3f(0.0f, 0.0f, 1.0f), const std::size_t shape_half_grid_size=3, const std::size_t shape_hists_size=1, const std::size_t color_half_grid_size=2, const std::size_t color_hists_size=12, const HistogramInterpolationMethod shape_interp=INTERP_NONE, const HistogramInterpolationMethod color_interp=INTERP_NONE)
Constructor.
Definition: gasd.h:272
pcl::GASDEstimation
GASDEstimation estimates the Globally Aligned Spatial Distribution (GASD) descriptor for a given poin...
Definition: gasd.h:75
pcl::GASDEstimation::pos_
std::size_t pos_
Current position of output descriptor point cloud.
Definition: gasd.h:173
pcl::GASDEstimation::GASDEstimation
GASDEstimation(const Eigen::Vector3f &view_direction=Eigen::Vector3f(0.0f, 0.0f, 1.0f), const std::size_t shape_half_grid_size=4, const std::size_t shape_hists_size=1, const HistogramInterpolationMethod shape_interp=INTERP_TRILINEAR)
Constructor.
Definition: gasd.h:88
pcl::GASDEstimation::max_coord_
float max_coord_
Normalization factor with respect to axis-aligned bounding cube centered on the origin.
Definition: gasd.h:167
pcl::GASDEstimation::computeFeature
void computeFeature(PointCloudOut &output) override
Estimate GASD descriptor.
Definition: gasd.hpp:252
pcl::GASDEstimation::setShapeHistsSize
void setShapeHistsSize(const std::size_t shs)
Set the shape histograms size.
Definition: gasd.h:126
pcl::GASDEstimation::setShapeHistsInterpMethod
void setShapeHistsInterpMethod(const HistogramInterpolationMethod interp)
Set the shape histograms interpolation method.
Definition: gasd.h:135
pcl::GASDEstimation::shape_samples_
PointCloudIn shape_samples_
Point cloud aligned to the canonical coordinate system.
Definition: gasd.h:164
pcl::GASDEstimation::getTransform
const Eigen::Matrix4f & getTransform() const
Returns the transformation aligning the point cloud to the canonical coordinate system.
Definition: gasd.h:144
pcl::GASDEstimation::hist_incr_
float hist_incr_
Normalized sample contribution with respect to the total number of points in the cloud.
Definition: gasd.h:170
pcl::GASDEstimation::ConstPtr
shared_ptr< const GASDEstimation< PointInT, PointOutT > > ConstPtr
Definition: gasd.h:80
pcl::GASDEstimation::Ptr
shared_ptr< GASDEstimation< PointInT, PointOutT > > Ptr
Definition: gasd.h:79
pcl::GASDEstimation::setShapeHalfGridSize
void setShapeHalfGridSize(const std::size_t shgs)
Set the shape half grid size.
Definition: gasd.h:115
pcl::GASDEstimation::compute
void compute(PointCloudOut &output)
Overloaded computed method from pcl::Feature.
Definition: gasd.hpp:50
pcl::GASDEstimation::addSampleToHistograms
void addSampleToHistograms(const Eigen::Vector4f &p, const float max_coord, const std::size_t half_grid_size, const HistogramInterpolationMethod interp, const float hbin, const float hist_incr, std::vector< Eigen::VectorXf > &hists)
add a sample to its respective histogram, optionally performing interpolation.
Definition: gasd.hpp:117
pcl::GASDEstimation::setViewDirection
void setViewDirection(const Eigen::Vector3f &dir)
Set the view direction.
Definition: gasd.h:106
pcl::PointCloud< PointInT >
pcl
Definition: convolution.h:46
pcl::HistogramInterpolationMethod
HistogramInterpolationMethod
Different histogram interpolation methods.
Definition: gasd.h:47
pcl::INTERP_NONE
@ INTERP_NONE
no interpolation
Definition: gasd.h:48
pcl::INTERP_QUADRILINEAR
@ INTERP_QUADRILINEAR
quadrilinear interpolation
Definition: gasd.h:50
pcl::INTERP_TRILINEAR
@ INTERP_TRILINEAR
trilinear interpolation
Definition: gasd.h:49