Point Cloud Library (PCL)  1.7.0
/tmp/buildd/pcl-1.7-1.7.0/surface/include/pcl/surface/poisson.h
00001 /*
00002  * Software License Agreement (BSD License)
00003  *
00004  *  Copyright (c) 2010, Willow Garage, Inc.
00005  *  All rights reserved.
00006  *
00007  *  Redistribution and use in source and binary forms, with or without
00008  *  modification, are permitted provided that the following conditions
00009  *  are met:
00010  *
00011  *   * Redistributions of source code must retain the above copyright
00012  *     notice, this list of conditions and the following disclaimer.
00013  *   * Redistributions in binary form must reproduce the above
00014  *     copyright notice, this list of conditions and the following
00015  *     disclaimer in the documentation and/or other materials provided
00016  *     with the distribution.
00017  *   * Neither the name of Willow Garage, Inc. nor the names of its
00018  *     contributors may be used to endorse or promote products derived
00019  *     from this software without specific prior written permission.
00020  *
00021  *  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
00022  *  "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
00023  *  LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
00024  *  FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
00025  *  COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
00026  *  INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
00027  *  BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
00028  *  LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
00029  *  CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
00030  *  LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
00031  *  ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
00032  *  POSSIBILITY OF SUCH DAMAGE.
00033  *
00034  * $Id$
00035  *
00036  */
00037 
00038 #ifndef PCL_SURFACE_POISSON_H_
00039 #define PCL_SURFACE_POISSON_H_
00040 
00041 #include <pcl/surface/reconstruction.h>
00042 
00043 namespace pcl
00044 {
00045   namespace poisson
00046   {
00047     class CoredVectorMeshData;
00048     template <class Real> struct Point3D;
00049   }
00050 
00051   /** \brief The Poisson surface reconstruction algorithm.
00052     * \note Code adapted from Misha Kazhdan: http://www.cs.jhu.edu/~misha/Code/PoissonRecon/
00053     * \note Based on the paper:
00054     *       * Michael Kazhdan, Matthew Bolitho, Hugues Hoppe, "Poisson surface reconstruction",
00055     *         SGP '06 Proceedings of the fourth Eurographics symposium on Geometry processing
00056     * \author Alexandru-Eugen Ichim
00057     * \ingroup surface
00058     */
00059   template<typename PointNT>
00060   class Poisson : public SurfaceReconstruction<PointNT>
00061   {
00062     public:
00063       typedef boost::shared_ptr<Poisson<PointNT> > Ptr;
00064       typedef boost::shared_ptr<const Poisson<PointNT> > ConstPtr;
00065 
00066       using SurfaceReconstruction<PointNT>::input_;
00067       using SurfaceReconstruction<PointNT>::tree_;
00068 
00069       typedef typename pcl::PointCloud<PointNT>::Ptr PointCloudPtr;
00070 
00071       typedef typename pcl::KdTree<PointNT> KdTree;
00072       typedef typename pcl::KdTree<PointNT>::Ptr KdTreePtr;
00073 
00074       /** \brief Constructor that sets all the parameters to working default values. */
00075       Poisson ();
00076 
00077       /** \brief Destructor. */
00078       ~Poisson ();
00079 
00080       /** \brief Create the surface.
00081         * \param[out] output the resultant polygonal mesh
00082         */
00083       void
00084       performReconstruction (pcl::PolygonMesh &output);
00085 
00086       /** \brief Create the surface.
00087         * \param[out] points the vertex positions of the resulting mesh
00088         * \param[out] polygons the connectivity of the resulting mesh
00089         */
00090       void
00091       performReconstruction (pcl::PointCloud<PointNT> &points,
00092                              std::vector<pcl::Vertices> &polygons);
00093 
00094       /** \brief Set the maximum depth of the tree that will be used for surface reconstruction.
00095         * \note Running at depth d corresponds to solving on a voxel grid whose resolution is no larger than
00096         * 2^d x 2^d x 2^d. Note that since the reconstructor adapts the octree to the sampling density, the specified
00097         * reconstruction depth is only an upper bound.
00098         * \param[in] depth the depth parameter
00099         */
00100       inline void
00101       setDepth (int depth) { depth_ = depth; }
00102 
00103       /** \brief Get the depth parameter */
00104       inline int
00105       getDepth () { return depth_; }
00106 
00107       inline void
00108       setMinDepth (int min_depth) { min_depth_ = min_depth; }
00109 
00110       inline int
00111       getMinDepth () { return min_depth_; }
00112 
00113       inline void
00114       setPointWeight (float point_weight) { point_weight_ = point_weight; }
00115 
00116       inline float
00117       getPointWeight () { return point_weight_; }
00118 
00119       /** \brief Set the ratio between the diameter of the cube used for reconstruction and the diameter of the
00120         * samples' bounding cube.
00121         * \param[in] scale the given parameter value
00122         */
00123       inline void
00124       setScale (float scale) { scale_ = scale; }
00125 
00126       /** Get the ratio between the diameter of the cube used for reconstruction and the diameter of the
00127         * samples' bounding cube.
00128         */
00129       inline float
00130       getScale () { return scale_; }
00131 
00132       /** \brief Set the the depth at which a block Gauss-Seidel solver is used to solve the Laplacian equation
00133         * \note Using this parameter helps reduce the memory overhead at the cost of a small increase in
00134         * reconstruction time. (In practice, we have found that for reconstructions of depth 9 or higher a subdivide
00135         * depth of 7 or 8 can greatly reduce the memory usage.)
00136         * \param[in] solver_divide the given parameter value
00137         */
00138       inline void
00139       setSolverDivide (int solver_divide) { solver_divide_ = solver_divide; }
00140 
00141       /** \brief Get the the depth at which a block Gauss-Seidel solver is used to solve the Laplacian equation */
00142       inline int
00143       getSolverDivide () { return solver_divide_; }
00144 
00145       /** \brief Set the depth at which a block iso-surface extractor should be used to extract the iso-surface
00146         * \note Using this parameter helps reduce the memory overhead at the cost of a small increase in extraction
00147         * time. (In practice, we have found that for reconstructions of depth 9 or higher a subdivide depth of 7 or 8
00148         * can greatly reduce the memory usage.)
00149         * \param[in] iso_divide the given parameter value
00150         */
00151       inline void
00152       setIsoDivide (int iso_divide) { iso_divide_ = iso_divide; }
00153 
00154       /** \brief Get the depth at which a block iso-surface extractor should be used to extract the iso-surface */
00155       inline int
00156       getIsoDivide () { return iso_divide_; }
00157 
00158       /** \brief Set the minimum number of sample points that should fall within an octree node as the octree
00159         * construction is adapted to sampling density
00160         * \note For noise-free samples, small values in the range [1.0 - 5.0] can be used. For more noisy samples,
00161         * larger values in the range [15.0 - 20.0] may be needed to provide a smoother, noise-reduced, reconstruction.
00162         * \param[in] samples_per_node the given parameter value
00163         */
00164       inline void
00165       setSamplesPerNode (float samples_per_node) { samples_per_node_ = samples_per_node; }
00166 
00167       /** \brief Get the minimum number of sample points that should fall within an octree node as the octree
00168         * construction is adapted to sampling density
00169         */
00170       inline float
00171       getSamplesPerNode () { return samples_per_node_; }
00172 
00173       /** \brief Set the confidence flag
00174         * \note Enabling this flag tells the reconstructor to use the size of the normals as confidence information.
00175         * When the flag is not enabled, all normals are normalized to have unit-length prior to reconstruction.
00176         * \param[in] confidence the given flag
00177         */
00178       inline void
00179       setConfidence (bool confidence) { confidence_ = confidence; }
00180 
00181       /** \brief Get the confidence flag */
00182       inline bool
00183       getConfidence () { return confidence_; }
00184 
00185       /** \brief Enabling this flag tells the reconstructor to output a polygon mesh (rather than triangulating the
00186         * results of Marching Cubes).
00187         * \param[in] output_polygons the given flag
00188         */
00189       inline void
00190       setOutputPolygons (bool output_polygons) { output_polygons_ = output_polygons; }
00191 
00192       /** \brief Get whether the algorithm outputs a polygon mesh or a triangle mesh */
00193       inline bool
00194       getOutputPolygons () { return output_polygons_; }
00195 
00196       /** \brief Set the degree parameter
00197         * \param[in] degree the given degree
00198         */
00199       inline void
00200       setDegree (int degree) { degree_ = degree; }
00201 
00202       /** \brief Get the degree parameter */
00203       inline int
00204       getDegree () { return degree_; }
00205 
00206       /** \brief Set the manifold flag.
00207         * \note Enabling this flag tells the reconstructor to add the polygon barycenter when triangulating polygons
00208         * with more than three vertices.
00209         * \param[in] manifold the given flag
00210         */
00211       inline void
00212       setManifold (bool manifold) { manifold_ = manifold; }
00213 
00214       /** \brief Get the manifold flag */
00215       inline bool
00216       getManifold () { return manifold_; }
00217 
00218     protected:
00219       /** \brief Class get name method. */
00220       std::string
00221       getClassName () const { return ("Poisson"); }
00222 
00223     private:
00224       int depth_;
00225       int min_depth_;
00226       float point_weight_;
00227       float scale_;
00228       int solver_divide_;
00229       int iso_divide_;
00230       float samples_per_node_;
00231       bool confidence_;
00232       bool output_polygons_;
00233 
00234       bool no_reset_samples_;
00235       bool no_clip_tree_;
00236       bool manifold_;
00237 
00238       int refine_;
00239       int kernel_depth_;
00240       int degree_;
00241       bool non_adaptive_weights_;
00242       bool show_residual_;
00243       int min_iterations_;
00244       float solver_accuracy_;
00245 
00246       template<int Degree> void
00247       execute (poisson::CoredVectorMeshData &mesh,
00248                poisson::Point3D<float> &translate,
00249                float &scale);
00250 
00251     public:
00252       EIGEN_MAKE_ALIGNED_OPERATOR_NEW
00253   };
00254 }
00255 
00256 #endif  // PCL_SURFACE_POISSON_H_