Point Cloud Library (PCL)  1.3.1
range_image_border_extractor.h
Go to the documentation of this file.
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 
00035 #ifndef PCL_RANGE_IMAGE_BORDER_EXTRACTOR_H_
00036 #define PCL_RANGE_IMAGE_BORDER_EXTRACTOR_H_
00037 
00038 #include <pcl/point_types.h>
00039 #include <pcl/features/feature.h>
00040 
00041 namespace pcl
00042 {
00043   // FORWARD DECLARATIONS:
00044   class RangeImage;
00045   template <typename PointType>
00046   class PointCloud;
00047 
00053   class PCL_EXPORTS RangeImageBorderExtractor : public Feature<PointWithRange,BorderDescription>
00054   {
00055     public:
00056       // =====TYPEDEFS=====
00057       typedef Feature<PointWithRange,BorderDescription> BaseClass;
00058       
00059       // =====PUBLIC STRUCTS=====
00061       struct LocalSurface
00062       {
00063         Eigen::Vector3f normal;
00064         Eigen::Vector3f neighborhood_mean;
00065         Eigen::Vector3f eigen_values;
00066         Eigen::Vector3f normal_no_jumps;
00067         Eigen::Vector3f neighborhood_mean_no_jumps;
00068         Eigen::Vector3f eigen_values_no_jumps;
00069         float max_neighbor_distance_squared;
00070       };
00071       
00073       struct ShadowBorderIndices {
00074         ShadowBorderIndices () : left (-1), right (-1), top (-1), bottom (-1) {}
00075         int left, right, top, bottom;
00076       };
00077 
00079       struct Parameters
00080       {
00081         Parameters () : max_no_of_threads(1), pixel_radius_borders (3), pixel_radius_plane_extraction (2), pixel_radius_border_direction (2), 
00082                        minimum_border_probability (0.8f), pixel_radius_principal_curvature (2) {}
00083         int max_no_of_threads;
00084         int pixel_radius_borders;
00085         int pixel_radius_plane_extraction;
00086         int pixel_radius_border_direction;
00087         float minimum_border_probability;
00088         int pixel_radius_principal_curvature;
00089       };
00090       
00091       // =====STATIC METHODS=====
00095       static inline float
00096       getObstacleBorderAngle (const BorderTraits& border_traits);
00097       
00098       // =====CONSTRUCTOR & DESTRUCTOR=====
00100       RangeImageBorderExtractor (const RangeImage* range_image=NULL);
00102       ~RangeImageBorderExtractor ();
00103       
00104       // =====METHODS=====
00108       void
00109       setRangeImage (const RangeImage* range_image);
00110       
00112       void
00113       clearData ();
00114        
00118       float*
00119       getAnglesImageForBorderDirections ();
00120 
00124       float*
00125       getAnglesImageForSurfaceChangeDirections ();
00126       
00128       void
00129       compute (PointCloudOut& output);
00130       
00131       // =====GETTER=====
00132       Parameters&
00133       getParameters () { return parameters_; }
00134 
00135       bool
00136       hasRangeImage () const { return range_image_ != NULL; }
00137 
00138       const RangeImage&
00139       getRangeImage () const { return *range_image_; }
00140 
00141       float*
00142       getBorderScoresLeft ()   { extractBorderScoreImages (); return border_scores_left_; }
00143 
00144       float*
00145       getBorderScoresRight ()  { extractBorderScoreImages (); return border_scores_right_; }
00146 
00147       float*
00148       getBorderScoresTop ()    { extractBorderScoreImages (); return border_scores_top_; }
00149 
00150       float*
00151       getBorderScoresBottom () { extractBorderScoreImages (); return border_scores_bottom_; }
00152 
00153       LocalSurface**
00154       getSurfaceStructure () { extractLocalSurfaceStructure (); return surface_structure_; }
00155 
00156       PointCloudOut&
00157       getBorderDescriptions () { classifyBorders (); return *border_descriptions_; }
00158 
00159       ShadowBorderIndices**
00160       getShadowBorderInformations () { findAndEvaluateShadowBorders (); return shadow_border_informations_; }
00161 
00162       Eigen::Vector3f**
00163       getBorderDirections () { calculateBorderDirections (); return border_directions_; }
00164 
00165       float*
00166       getSurfaceChangeScores () { calculateSurfaceChanges (); return surface_change_scores_; }
00167 
00168       Eigen::Vector3f*
00169       getSurfaceChangeDirections () { calculateSurfaceChanges (); return surface_change_directions_; }
00170       
00171       
00172     protected:
00173       // =====PROTECTED MEMBER VARIABLES=====
00174       Parameters parameters_;
00175       const RangeImage* range_image_;
00176       int range_image_size_during_extraction_;
00177       float* border_scores_left_, * border_scores_right_, * border_scores_top_, * border_scores_bottom_;
00178       LocalSurface** surface_structure_;
00179       PointCloudOut* border_descriptions_;
00180       ShadowBorderIndices** shadow_border_informations_;
00181       Eigen::Vector3f** border_directions_;
00182       
00183       float* surface_change_scores_;
00184       Eigen::Vector3f* surface_change_directions_;
00185       
00186       
00187       // =====PROTECTED METHODS=====
00197       inline float
00198       getNeighborDistanceChangeScore (const LocalSurface& local_surface, int x, int y, 
00199                                       int offset_x, int offset_y, int pixel_radius=1) const;
00200       
00209       inline float
00210       getNormalBasedBorderScore (const LocalSurface& local_surface, int x, int y, 
00211                                  int offset_x, int offset_y) const;
00212       
00223       inline bool
00224       changeScoreAccordingToShadowBorderValue (int x, int y, int offset_x, int offset_y, float* border_scores,
00225                                                float* border_scores_other_direction, int& shadow_border_idx) const;
00226       
00233       inline float
00234       updatedScoreAccordingToNeighborValues (int x, int y, const float* border_scores) const;
00235 
00240       float*
00241       updatedScoresAccordingToNeighborValues (const float* border_scores) const;
00242 
00244       void
00245       updateScoresAccordingToNeighborValues ();
00246       
00257       inline bool
00258       checkPotentialBorder (int x, int y, int offset_x, int offset_y, float* border_scores_left,
00259                             float* border_scores_right, int& shadow_border_idx) const;
00260 
00270       inline bool
00271       checkIfMaximum (int x, int y, int offset_x, int offset_y, float* border_scores, int shadow_border_idx) const;
00272       
00274       void
00275       findAndEvaluateShadowBorders ();
00276       
00278       void
00279       extractLocalSurfaceStructure ();
00280       
00284       void
00285       extractBorderScoreImages ();
00286       
00290       void
00291       classifyBorders ();
00292       
00298       inline void
00299       calculateBorderDirection (int x, int y);
00300       
00304       void
00305       calculateBorderDirections ();
00306       
00314       inline bool
00315       get3dDirection (const BorderDescription& border_description, Eigen::Vector3f& direction,
00316                       const LocalSurface* local_surface=NULL);
00317       
00326       inline bool
00327       calculateMainPrincipalCurvature (int x, int y, int radius, float& magnitude,
00328                                        Eigen::Vector3f& main_direction) const;
00329       
00332       void
00333       calculateSurfaceChanges ();
00334 
00336       void
00337       blurSurfaceChanges ();
00338       
00340       virtual void
00341       computeFeature (PointCloudOut &output);
00342   };
00343 
00344 }  // namespace end
00345 
00346 #include <pcl/features/impl/range_image_border_extractor.hpp>  // Definitions of templated and inline functions
00347 
00348 #endif  //#ifndef PCL_RANGE_IMAGE_BORDER_EXTRACTOR_H_
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines