Point Cloud Library (PCL)  1.10.1-dev
correspondence_grouping.h
1 /*
2  * Software License Agreement (BSD License)
3  *
4  * Point Cloud Library (PCL) - www.pointclouds.org
5  * Copyright (c) 2010-2012, 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 Willow Garage, Inc. 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 
40 #pragma once
41 
42 #include <pcl/pcl_base.h>
43 #include <pcl/correspondence.h>
44 #include <pcl/console/print.h>
45 
46 namespace pcl
47 {
48  /** \brief Abstract base class for Correspondence Grouping algorithms.
49  *
50  * \author Tommaso Cavallari, Federico Tombari, Aitor Aldoma
51  * \ingroup recognition
52  */
53  template <typename PointModelT, typename PointSceneT>
54  class CorrespondenceGrouping : public PCLBase<PointModelT>
55  {
56  public:
58  using SceneCloudPtr = typename SceneCloud::Ptr;
60 
61  /** \brief Empty constructor. */
63 
64  /** \brief destructor. */
66  {
67  scene_.reset ();
68  model_scene_corrs_.reset ();
69  }
70 
71  /** \brief Provide a pointer to the scene dataset.
72  *
73  * \param[in] scene the const boost shared pointer to a PointCloud message.
74  */
75  virtual inline void
77  {
78  scene_ = scene;
79  }
80 
81  /** \brief Getter for the scene dataset.
82  *
83  * \return the const boost shared pointer to a PointCloud message.
84  */
85  inline SceneCloudConstPtr
86  getSceneCloud () const
87  {
88  return (scene_);
89  }
90 
91  /** \brief Provide a pointer to the precomputed correspondences between points in the input dataset and
92  * points in the scene dataset. The correspondences are going to be clustered into different model hypotheses
93  * by the algorithm.
94  *
95  * \param[in] corrs the correspondences between the model and the scene.
96  */
97  virtual inline void
99  {
100  model_scene_corrs_ = corrs;
101  }
102 
103  /** \brief Getter for the precomputed correspondences between points in the input dataset and
104  * points in the scene dataset.
105  *
106  * \return the correspondences between the model and the scene.
107  */
110  {
111  return (model_scene_corrs_);
112  }
113 
114  /** \brief Getter for the vector of characteristic scales associated to each cluster
115  *
116  * \return the vector of characteristic scales (assuming scale = model / scene)
117  */
118  inline std::vector<double>
120  {
121  return (corr_group_scale_);
122  }
123 
124  /** \brief Clusters the input correspondences belonging to different model instances.
125  *
126  * \param[out] clustered_corrs a vector containing the correspondences for each instance of the model found within the input data.
127  */
128  void
129  cluster (std::vector<Correspondences> &clustered_corrs);
130 
131  protected:
132  /** \brief The scene cloud. */
134 
136 
137  /** \brief The correspondences between points in the input and the scene datasets. */
139 
140  /** \brief characteristic scale associated to each correspondence subset;
141  * if the cg algorithm can not handle scale invariance, the size of the vector will be 0. */
142  std::vector <double> corr_group_scale_;
143 
144  /** \brief The actual clustering method, should be implemented by each subclass.
145  *
146  * \param[out] clustered_corrs a vector containing the correspondences for each instance of the model found within the input data.
147  */
148  virtual void
149  clusterCorrespondences (std::vector<Correspondences> &clustered_corrs) = 0;
150 
151  /** \brief This method should get called before starting the actual computation.
152  *
153  * Internally, initCompute() does the following:
154  * - checks if an input dataset is given, and returns false otherwise
155  * - checks if a scene dataset is given, and returns false otherwise
156  * - checks if the model-scene correspondences have been given, and returns false otherwise
157  */
158  inline bool
160  {
162  {
163  return (false);
164  }
165 
166  if (!scene_)
167  {
168  PCL_ERROR ("[initCompute] Scene not set.\n");
169  return (false);
170  }
171 
172  if (!input_)
173  {
174  PCL_ERROR ("[initCompute] Input not set.\n");
175  return (false);
176  }
177 
178  if (!model_scene_corrs_)
179  {
180  PCL_ERROR ("[initCompute] Model-Scene Correspondences not set.\n");
181  return (false);
182  }
183 
184  return (true);
185  }
186 
187  /** \brief This method should get called after finishing the actual computation.
188  *
189  */
190  inline bool
192  {
193  return (true);
194  }
195 
196  };
197 }
198 
199 #include <pcl/recognition/impl/cg/correspondence_grouping.hpp>
shared_ptr< const Correspondences > CorrespondencesConstPtr
virtual void setSceneCloud(const SceneCloudConstPtr &scene)
Provide a pointer to the scene dataset.
shared_ptr< PointCloud< PointT > > Ptr
Definition: point_cloud.h:414
typename SceneCloud::Ptr SceneCloudPtr
typename SceneCloud::ConstPtr SceneCloudConstPtr
std::vector< double > getCharacteristicScales() const
Getter for the vector of characteristic scales associated to each cluster.
virtual void clusterCorrespondences(std::vector< Correspondences > &clustered_corrs)=0
The actual clustering method, should be implemented by each subclass.
CorrespondenceGrouping()
Empty constructor.
virtual void setModelSceneCorrespondences(const CorrespondencesConstPtr &corrs)
Provide a pointer to the precomputed correspondences between points in the input dataset and points i...
CorrespondencesConstPtr model_scene_corrs_
The correspondences between points in the input and the scene datasets.
PCL base class.
Definition: pcl_base.h:70
void cluster(std::vector< Correspondences > &clustered_corrs)
Clusters the input correspondences belonging to different model instances.
CorrespondencesConstPtr getModelSceneCorrespondences() const
Getter for the precomputed correspondences between points in the input dataset and points in the scen...
PointCloud represents the base class in PCL for storing collections of 3D points. ...
bool deinitCompute()
This method should get called after finishing the actual computation.
Abstract base class for Correspondence Grouping algorithms.
std::vector< double > corr_group_scale_
characteristic scale associated to each correspondence subset; if the cg algorithm can not handle sca...
SceneCloudConstPtr getSceneCloud() const
Getter for the scene dataset.
SceneCloudConstPtr scene_
The scene cloud.
shared_ptr< const PointCloud< PointT > > ConstPtr
Definition: point_cloud.h:415
bool initCompute()
This method should get called before starting the actual computation.
PointCloudConstPtr input_
The input point cloud dataset.
Definition: pcl_base.h:148