Point Cloud Library (PCL)  1.7.0
/tmp/buildd/pcl-1.7-1.7.0/common/include/pcl/correspondence.h
00001 /*
00002  * Software License Agreement (BSD License)
00003  *
00004  *  Point Cloud Library (PCL) - www.pointclouds.org
00005  *  Copyright (c) 2010-2011, Willow Garage, Inc.
00006  *  Copyright (c) 2012-, Open Perception, Inc.
00007  *
00008  *  All rights reserved.
00009  *
00010  *  Redistribution and use in source and binary forms, with or without
00011  *  modification, are permitted provided that the following conditions
00012  *  are met:
00013  *
00014  *   * Redistributions of source code must retain the above copyright
00015  *     notice, this list of conditions and the following disclaimer.
00016  *   * Redistributions in binary form must reproduce the above
00017  *     copyright notice, this list of conditions and the following
00018  *     disclaimer in the documentation and/or other materials provided
00019  *     with the distribution.
00020  *   * Neither the name of the copyright holder(s) nor the names of its
00021  *     contributors may be used to endorse or promote products derived
00022  *     from this software without specific prior written permission.
00023  *
00024  *  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
00025  *  "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
00026  *  LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
00027  *  FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
00028  *  COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
00029  *  INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
00030  *  BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
00031  *  LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
00032  *  CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
00033  *  LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
00034  *  ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
00035  *  POSSIBILITY OF SUCH DAMAGE.
00036  *
00037  */
00038 #ifndef PCL_COMMON_CORRESPONDENCE_H_
00039 #define PCL_COMMON_CORRESPONDENCE_H_
00040 
00041 #ifdef __GNUC__
00042 #pragma GCC system_header 
00043 #endif
00044 
00045 #include <boost/shared_ptr.hpp>
00046 #include <Eigen/StdVector>
00047 #include <Eigen/Geometry>
00048 #include <pcl/pcl_exports.h>
00049 
00050 namespace pcl
00051 {
00052   /** \brief Correspondence represents a match between two entities (e.g., points, descriptors, etc). This is 
00053     * represesented via the indices of a \a source point and a \a target point, and the distance between them.
00054     *
00055     * \author Dirk Holz, Radu B. Rusu, Bastian Steder
00056     * \ingroup common
00057     */
00058   struct Correspondence
00059   {
00060     /** \brief Index of the query (source) point. */
00061     int index_query;
00062     /** \brief Index of the matching (target) point. Set to -1 if no correspondence found. */
00063     int index_match;
00064     /** \brief Distance between the corresponding points, or the weight denoting the confidence in correspondence estimation */
00065     union
00066     {
00067       float distance;
00068       float weight;
00069     };
00070     
00071     /** \brief Standard constructor. 
00072       * Sets \ref index_query to 0, \ref index_match to -1, and \ref distance to FLT_MAX.
00073       */
00074     inline Correspondence () : index_query (0), index_match (-1), 
00075                                distance (std::numeric_limits<float>::max ())
00076     {}
00077 
00078     /** \brief Constructor. */
00079     inline Correspondence (int _index_query, int _index_match, float _distance) : 
00080       index_query (_index_query), index_match (_index_match), distance (_distance)
00081     {}
00082 
00083     /** \brief Empty destructor. */
00084     virtual ~Correspondence () {}
00085     
00086     EIGEN_MAKE_ALIGNED_OPERATOR_NEW
00087   };
00088   
00089   /** \brief overloaded << operator */
00090   PCL_EXPORTS std::ostream& operator << (std::ostream& os, const Correspondence& c);
00091 
00092   typedef std::vector< pcl::Correspondence, Eigen::aligned_allocator<pcl::Correspondence> > Correspondences;
00093   typedef boost::shared_ptr<Correspondences> CorrespondencesPtr;
00094   typedef boost::shared_ptr<const Correspondences > CorrespondencesConstPtr;
00095 
00096   /**
00097     * \brief Get the query points of correspondences that are present in
00098     * one correspondence vector but not in the other, e.g., to compare
00099     * correspondences before and after rejection.
00100     * \param[in] correspondences_before Vector of correspondences before rejection
00101     * \param[in] correspondences_after Vector of correspondences after rejection
00102     * \param[out] indices Query point indices of correspondences that have been rejected
00103     * \param[in] presorting_required Enable/disable internal sorting of vectors.
00104     * By default (true), vectors are internally sorted before determining their difference.
00105     * If the order of correspondences in \a correspondences_after is not different (has not been changed)
00106     * from the order in \b correspondences_before this pre-processing step can be disabled
00107     * in order to gain efficiency. In order to disable pre-sorting set \a presorting_requered to false.
00108     */
00109   void
00110   getRejectedQueryIndices (const pcl::Correspondences &correspondences_before,
00111                            const pcl::Correspondences &correspondences_after,
00112                            std::vector<int>& indices,
00113                            bool presorting_required = true);
00114 
00115   /**
00116     * \brief Representation of a (possible) correspondence between two 3D points in two different coordinate frames
00117     *        (e.g. from feature matching)
00118     * \ingroup common
00119     */
00120   struct PointCorrespondence3D : public Correspondence
00121   {
00122     Eigen::Vector3f point1;  //!< The 3D position of the point in the first coordinate frame
00123     Eigen::Vector3f point2;  //!< The 3D position of the point in the second coordinate frame
00124 
00125     /** \brief Empty constructor. */
00126     PointCorrespondence3D () : point1 (), point2 () {}
00127 
00128     /** \brief Empty destructor. */
00129     virtual ~PointCorrespondence3D () {}
00130     
00131     EIGEN_MAKE_ALIGNED_OPERATOR_NEW
00132   };
00133   typedef std::vector<PointCorrespondence3D, Eigen::aligned_allocator<PointCorrespondence3D> > PointCorrespondences3DVector;
00134 
00135   /**
00136     * \brief Representation of a (possible) correspondence between two points (e.g. from feature matching),
00137     *        that encode complete 6DOF transoformations.
00138     * \ingroup common
00139     */
00140   struct PointCorrespondence6D : public PointCorrespondence3D
00141   {
00142     Eigen::Affine3f transformation;  //!< The transformation to go from the coordinate system
00143                                         //!< of point2 to the coordinate system of point1
00144     /** \brief Empty destructor. */
00145     virtual ~PointCorrespondence6D () {}
00146 
00147     EIGEN_MAKE_ALIGNED_OPERATOR_NEW
00148   };
00149   typedef std::vector<PointCorrespondence6D, Eigen::aligned_allocator<PointCorrespondence6D> > PointCorrespondences6DVector;
00150 
00151   /**
00152     * \brief Comparator to enable us to sort a vector of PointCorrespondences according to their scores using
00153     *        std::sort (begin(), end(), isBetterCorrespondence);
00154     * \ingroup common
00155     */
00156   inline bool
00157   isBetterCorrespondence (const Correspondence &pc1, const Correspondence &pc2)
00158   {
00159     return (pc1.distance > pc2.distance);
00160   }
00161 }
00162 
00163 #endif /* PCL_COMMON_CORRESPONDENCE_H_ */