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