Point Cloud Library (PCL)  1.8.0
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
77  setSceneCloud (const SceneCloudConstPtr &scene)
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. */
134  SceneCloudConstPtr scene_;
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.
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
std::vector< double > getCharacteristicScales() const
Getter for the vector of characteristic scales associated to each cluster.
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
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 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
CorrespondencesConstPtr getModelSceneCorrespondences() const
Getter for the precomputed correspondences between points in the input dataset and points in the scen...
pcl::PointCloud< PointSceneT > SceneCloud
SceneCloudConstPtr getSceneCloud() const
Getter for the scene dataset.