Point Cloud Library (PCL)  1.9.1-dev
lum.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  * Copyright (c) 2012-, Open Perception, Inc.
7  *
8  * All rights reserved.
9  *
10  * Redistribution and use in source and binary forms, with or without
11  * modification, are permitted provided that the following conditions
12  * are met:
13  *
14  * * Redistributions of source code must retain the above copyright
15  * notice, this list of conditions and the following disclaimer.
16  * * Redistributions in binary form must reproduce the above
17  * copyright notice, this list of conditions and the following
18  * disclaimer in the documentation and/or other materials provided
19  * with the distribution.
20  * * Neither the name of the copyright holder(s) nor the names of its
21  * contributors may be used to endorse or promote products derived
22  * from this software without specific prior written permission.
23  *
24  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
25  * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
26  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
27  * FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
28  * COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
29  * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
30  * BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
31  * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
32  * CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
33  * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
34  * ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
35  * POSSIBILITY OF SUCH DAMAGE.
36  *
37  * $Id: lum.h 5663 2012-05-02 13:49:39Z florentinus $
38  *
39  */
40 
41 #pragma once
42 
43 #include <pcl/pcl_base.h>
44 #include <pcl/registration/eigen.h>
45 #include <pcl/registration/boost.h>
46 #include <pcl/common/transforms.h>
47 #include <pcl/correspondence.h>
48 #include <pcl/registration/boost_graph.h>
49 
50 namespace Eigen
51 {
52  typedef Eigen::Matrix<float, 6, 1> Vector6f;
53  typedef Eigen::Matrix<float, 6, 6> Matrix6f;
54 }
55 
56 namespace pcl
57 {
58  namespace registration
59  {
60  /** \brief Globally Consistent Scan Matching based on an algorithm by Lu and Milios.
61  * \details A GraphSLAM algorithm where registration data is managed in a graph:
62  * <ul>
63  * <li>Vertices represent poses and hold the point cloud data and relative transformations.</li>
64  * <li>Edges represent pose constraints and hold the correspondence data between two point clouds.</li>
65  * </ul>
66  * Computation uses the first point cloud in the SLAM graph as a reference pose and attempts to align all other point clouds to it simultaneously.
67  * For more information:
68  * <ul><li>
69  * F. Lu, E. Milios,
70  * Globally Consistent Range Scan Alignment for Environment Mapping,
71  * Autonomous Robots 4, April 1997
72  * </li><li>
73  * Dorit Borrmann, Jan Elseberg, Kai Lingemann, Andreas Nüchter, and Joachim Hertzberg,
74  * The Efficient Extension of Globally Consistent Scan Matching to 6 DoF,
75  * In Proceedings of the 4th International Symposium on 3D Data Processing, Visualization and Transmission (3DPVT '08), June 2008
76  * </li></ul>
77  * Usage example:
78  * \code
79  * pcl::registration::LUM<pcl::PointXYZ> lum;
80  * // Add point clouds as vertices to the SLAM graph
81  * lum.addPointCloud (cloud_0);
82  * lum.addPointCloud (cloud_1);
83  * lum.addPointCloud (cloud_2);
84  * // Use your favorite pairwise correspondence estimation algorithm(s)
85  * corrs_0_to_1 = someAlgo (cloud_0, cloud_1);
86  * corrs_1_to_2 = someAlgo (cloud_1, cloud_2);
87  * corrs_2_to_0 = someAlgo (lum.getPointCloud (2), lum.getPointCloud (0));
88  * // Add the correspondence results as edges to the SLAM graph
89  * lum.setCorrespondences (0, 1, corrs_0_to_1);
90  * lum.setCorrespondences (1, 2, corrs_1_to_2);
91  * lum.setCorrespondences (2, 0, corrs_2_to_0);
92  * // Change the computation parameters
93  * lum.setMaxIterations (5);
94  * lum.setConvergenceThreshold (0.0);
95  * // Perform the actual LUM computation
96  * lum.compute ();
97  * // Return the concatenated point cloud result
98  * cloud_out = lum.getConcatenatedCloud ();
99  * // Return the separate point cloud transformations
100  * for(int i = 0; i < lum.getNumVertices (); i++)
101  * {
102  * transforms_out[i] = lum.getTransformation (i);
103  * }
104  * \endcode
105  * \author Frits Florentinus, Jochen Sprickerhof
106  * \ingroup registration
107  */
108  template<typename PointT>
109  class LUM
110  {
111  public:
112  typedef boost::shared_ptr<LUM<PointT> > Ptr;
113  typedef boost::shared_ptr<const LUM<PointT> > ConstPtr;
114 
116  typedef typename PointCloud::Ptr PointCloudPtr;
118 
120  {
121  PointCloudPtr cloud_;
123  EIGEN_MAKE_ALIGNED_OPERATOR_NEW
124  };
126  {
130  EIGEN_MAKE_ALIGNED_OPERATOR_NEW
131  };
132 
133  typedef boost::adjacency_list<boost::eigen_vecS, boost::eigen_vecS, boost::bidirectionalS, VertexProperties, EdgeProperties, boost::no_property, boost::eigen_listS> SLAMGraph;
134  typedef boost::shared_ptr<SLAMGraph> SLAMGraphPtr;
135  typedef typename SLAMGraph::vertex_descriptor Vertex;
136  typedef typename SLAMGraph::edge_descriptor Edge;
137 
138  /** \brief Empty constructor.
139  */
140  LUM ()
141  : slam_graph_ (new SLAMGraph)
142  , max_iterations_ (5)
143  , convergence_threshold_ (0.0)
144  {
145  }
146 
147  /** \brief Set the internal SLAM graph structure.
148  * \details All data used and produced by LUM is stored in this boost::adjacency_list.
149  * It is recommended to use the LUM class itself to build the graph.
150  * This method could otherwise be useful for managing several SLAM graphs in one instance of LUM.
151  * \param[in] slam_graph The new SLAM graph.
152  */
153  inline void
154  setLoopGraph (const SLAMGraphPtr &slam_graph);
155 
156  /** \brief Get the internal SLAM graph structure.
157  * \details All data used and produced by LUM is stored in this boost::adjacency_list.
158  * It is recommended to use the LUM class itself to build the graph.
159  * This method could otherwise be useful for managing several SLAM graphs in one instance of LUM.
160  * \return The current SLAM graph.
161  */
162  inline SLAMGraphPtr
163  getLoopGraph () const;
164 
165  /** \brief Get the number of vertices in the SLAM graph.
166  * \return The current number of vertices in the SLAM graph.
167  */
168  typename SLAMGraph::vertices_size_type
169  getNumVertices () const;
170 
171  /** \brief Set the maximum number of iterations for the compute() method.
172  * \details The compute() method finishes when max_iterations are met or when the convergence criteria is met.
173  * \param[in] max_iterations The new maximum number of iterations (default = 5).
174  */
175  void
176  setMaxIterations (int max_iterations);
177 
178  /** \brief Get the maximum number of iterations for the compute() method.
179  * \details The compute() method finishes when max_iterations are met or when the convergence criteria is met.
180  * \return The current maximum number of iterations (default = 5).
181  */
182  inline int
183  getMaxIterations () const;
184 
185  /** \brief Set the convergence threshold for the compute() method.
186  * \details When the compute() method computes the new poses relative to the old poses, it will determine the length of the difference vector.
187  * When the average length of all difference vectors becomes less than the convergence_threshold the convergence is assumed to be met.
188  * \param[in] convergence_threshold The new convergence threshold (default = 0.0).
189  */
190  void
191  setConvergenceThreshold (float convergence_threshold);
192 
193  /** \brief Get the convergence threshold for the compute() method.
194  * \details When the compute() method computes the new poses relative to the old poses, it will determine the length of the difference vector.
195  * When the average length of all difference vectors becomes less than the convergence_threshold the convergence is assumed to be met.
196  * \return The current convergence threshold (default = 0.0).
197  */
198  inline float
199  getConvergenceThreshold () const;
200 
201  /** \brief Add a new point cloud to the SLAM graph.
202  * \details This method will add a new vertex to the SLAM graph and attach a point cloud to that vertex.
203  * Optionally you can specify a pose estimate for this point cloud.
204  * A vertex' pose is always relative to the first vertex in the SLAM graph, i.e. the first point cloud that was added.
205  * Because this first vertex is the reference, you can not set a pose estimate for this vertex.
206  * Providing pose estimates to the vertices in the SLAM graph will reduce overall computation time of LUM.
207  * \note Vertex descriptors are typecastable to int.
208  * \param[in] cloud The new point cloud.
209  * \param[in] pose (optional) The pose estimate relative to the reference pose (first point cloud that was added).
210  * \return The vertex descriptor of the newly created vertex.
211  */
212  Vertex
213  addPointCloud (const PointCloudPtr &cloud, const Eigen::Vector6f &pose = Eigen::Vector6f::Zero ());
214 
215  /** \brief Change a point cloud on one of the SLAM graph's vertices.
216  * \details This method will change the point cloud attached to an existing vertex and will not alter the SLAM graph structure.
217  * Note that the correspondences attached to this vertex will not change and may need to be updated manually.
218  * \note Vertex descriptors are typecastable to int.
219  * \param[in] vertex The vertex descriptor of which to change the point cloud.
220  * \param[in] cloud The new point cloud for that vertex.
221  */
222  inline void
223  setPointCloud (const Vertex &vertex, const PointCloudPtr &cloud);
224 
225  /** \brief Return a point cloud from one of the SLAM graph's vertices.
226  * \note Vertex descriptors are typecastable to int.
227  * \param[in] vertex The vertex descriptor of which to return the point cloud.
228  * \return The current point cloud for that vertex.
229  */
230  inline PointCloudPtr
231  getPointCloud (const Vertex &vertex) const;
232 
233  /** \brief Change a pose estimate on one of the SLAM graph's vertices.
234  * \details A vertex' pose is always relative to the first vertex in the SLAM graph, i.e. the first point cloud that was added.
235  * Because this first vertex is the reference, you can not set a pose estimate for this vertex.
236  * Providing pose estimates to the vertices in the SLAM graph will reduce overall computation time of LUM.
237  * \note Vertex descriptors are typecastable to int.
238  * \param[in] vertex The vertex descriptor of which to set the pose estimate.
239  * \param[in] pose The new pose estimate for that vertex.
240  */
241  inline void
242  setPose (const Vertex &vertex, const Eigen::Vector6f &pose);
243 
244  /** \brief Return a pose estimate from one of the SLAM graph's vertices.
245  * \note Vertex descriptors are typecastable to int.
246  * \param[in] vertex The vertex descriptor of which to return the pose estimate.
247  * \return The current pose estimate of that vertex.
248  */
249  inline Eigen::Vector6f
250  getPose (const Vertex &vertex) const;
251 
252  /** \brief Return a pose estimate from one of the SLAM graph's vertices as an affine transformation matrix.
253  * \note Vertex descriptors are typecastable to int.
254  * \param[in] vertex The vertex descriptor of which to return the transformation matrix.
255  * \return The current transformation matrix of that vertex.
256  */
257  inline Eigen::Affine3f
258  getTransformation (const Vertex &vertex) const;
259 
260  /** \brief Add/change a set of correspondences for one of the SLAM graph's edges.
261  * \details The edges in the SLAM graph are directional and point from source vertex to target vertex.
262  * The query indices of the correspondences, index the points at the source vertex' point cloud.
263  * The matching indices of the correspondences, index the points at the target vertex' point cloud.
264  * If no edge was present at the specified location, this method will add a new edge to the SLAM graph and attach the correspondences to that edge.
265  * If the edge was already present, this method will overwrite the correspondence information of that edge and will not alter the SLAM graph structure.
266  * \note Vertex descriptors are typecastable to int.
267  * \param[in] source_vertex The vertex descriptor of the correspondences' source point cloud.
268  * \param[in] target_vertex The vertex descriptor of the correspondences' target point cloud.
269  * \param[in] corrs The new set of correspondences for that edge.
270  */
271  void
272  setCorrespondences (const Vertex &source_vertex,
273  const Vertex &target_vertex,
274  const pcl::CorrespondencesPtr &corrs);
275 
276  /** \brief Return a set of correspondences from one of the SLAM graph's edges.
277  * \note Vertex descriptors are typecastable to int.
278  * \param[in] source_vertex The vertex descriptor of the correspondences' source point cloud.
279  * \param[in] target_vertex The vertex descriptor of the correspondences' target point cloud.
280  * \return The current set of correspondences of that edge.
281  */
283  getCorrespondences (const Vertex &source_vertex, const Vertex &target_vertex) const;
284 
285  /** \brief Perform LUM's globally consistent scan matching.
286  * \details Computation uses the first point cloud in the SLAM graph as a reference pose and attempts to align all other point clouds to it simultaneously.
287  * <br>
288  * Things to keep in mind:
289  * <ul>
290  * <li>Only those parts of the graph connected to the reference pose will properly align to it.</li>
291  * <li>All sets of correspondences should span the same space and need to be sufficient to determine a rigid transformation.</li>
292  * <li>The algorithm draws it strength from loops in the graph because it will distribute errors evenly amongst those loops.</li>
293  * </ul>
294  * Computation ends when either of the following conditions hold:
295  * <ul>
296  * <li>The number of iterations reaches max_iterations. Use setMaxIterations() to change.</li>
297  * <li>The convergence criteria is met. Use setConvergenceThreshold() to change.</li>
298  * </ul>
299  * Computation will change the pose estimates for the vertices of the SLAM graph, not the point clouds attached to them.
300  * The results can be retrieved with getPose(), getTransformation(), getTransformedCloud() or getConcatenatedCloud().
301  */
302  void
303  compute ();
304 
305  /** \brief Return a point cloud from one of the SLAM graph's vertices compounded onto its current pose estimate.
306  * \note Vertex descriptors are typecastable to int.
307  * \param[in] vertex The vertex descriptor of which to return the transformed point cloud.
308  * \return The transformed point cloud of that vertex.
309  */
310  PointCloudPtr
311  getTransformedCloud (const Vertex &vertex) const;
312 
313  /** \brief Return a concatenated point cloud of all the SLAM graph's point clouds compounded onto their current pose estimates.
314  * \return The concatenated transformed point clouds of the entire SLAM graph.
315  */
316  PointCloudPtr
317  getConcatenatedCloud () const;
318 
319  protected:
320  /** \brief Linearized computation of C^-1 and C^-1*D (results stored in slam_graph_). */
321  void
322  computeEdge (const Edge &e);
323 
324  /** \brief Returns a pose corrected 6DoF incidence matrix. */
325  inline Eigen::Matrix6f
326  incidenceCorrection (const Eigen::Vector6f &pose);
327 
328  private:
329  /** \brief The internal SLAM graph structure. */
330  SLAMGraphPtr slam_graph_;
331 
332  /** \brief The maximum number of iterations for the compute() method. */
333  int max_iterations_;
334 
335  /** \brief The convergence threshold for the summed vector lengths of all poses. */
336  float convergence_threshold_;
337  };
338  }
339 }
340 
341 #ifdef PCL_NO_PRECOMPILE
342 #include <pcl/registration/impl/lum.hpp>
343 #endif
pcl::CorrespondencesPtr corrs_
Definition: lum.h:127
boost::shared_ptr< const LUM< PointT > > ConstPtr
Definition: lum.h:113
Eigen::Matrix< float, 6, 6 > Matrix6f
Definition: lum.h:53
PointCloud::Ptr PointCloudPtr
Definition: lum.h:116
LUM()
Empty constructor.
Definition: lum.h:140
This file defines compatibility wrappers for low level I/O functions.
Definition: convolution.h:44
Eigen::Matrix< float, 6, 1 > Vector6f
Definition: lum.h:52
Globally Consistent Scan Matching based on an algorithm by Lu and Milios.
Definition: lum.h:109
Definition: bfgs.h:9
boost::shared_ptr< PointCloud< PointT > > Ptr
Definition: point_cloud.h:427
PointCloud::ConstPtr PointCloudConstPtr
Definition: lum.h:117
SLAMGraph::edge_descriptor Edge
Definition: lum.h:136
boost::adjacency_list< boost::eigen_vecS, boost::eigen_vecS, boost::bidirectionalS, VertexProperties, EdgeProperties, boost::no_property, boost::eigen_listS > SLAMGraph
Definition: lum.h:133
boost::shared_ptr< LUM< PointT > > Ptr
Definition: lum.h:112
boost::shared_ptr< const PointCloud< PointT > > ConstPtr
Definition: point_cloud.h:428
boost::shared_ptr< Correspondences > CorrespondencesPtr
PointCloud represents the base class in PCL for storing collections of 3D points. ...
SLAMGraph::vertex_descriptor Vertex
Definition: lum.h:135
pcl::PointCloud< PointT > PointCloud
Definition: lum.h:115
void getTransformation(Scalar x, Scalar y, Scalar z, Scalar roll, Scalar pitch, Scalar yaw, Eigen::Transform< Scalar, 3, Eigen::Affine > &t)
Create a transformation from the given translation and Euler angles (XYZ-convention) ...
Definition: eigen.hpp:687
boost::shared_ptr< SLAMGraph > SLAMGraphPtr
Definition: lum.h:134