\( \newcommand{\E}{\mathrm{E}} \) \( \newcommand{\A}{\mathrm{A}} \) \( \newcommand{\R}{\mathrm{R}} \) \( \newcommand{\N}{\mathrm{N}} \) \( \newcommand{\Q}{\mathrm{Q}} \) \( \newcommand{\Z}{\mathrm{Z}} \) \( \def\ccSum #1#2#3{ \sum_{#1}^{#2}{#3} } \def\ccProd #1#2#3{ \sum_{#1}^{#2}{#3} }\)
CGAL 4.14 - Point Set Shape Detection
List of all members | Classes
CGAL::Shape_detection_3::Efficient_RANSAC< Traits > Class Template Reference
Point Set Shape Detection Reference

#include <CGAL/Shape_detection_3/Efficient_RANSAC.h>

Definition

A shape detection algorithm using a RANSAC method.

Given a point set in 3D space with unoriented normals, sampled on surfaces, this class enables to detect subsets of connected points lying on the surface of primitive shapes. Each input point is assigned to either none or at most one detected primitive shape. The implementation follows [2].

Template Parameters
Traitsa model of ShapeDetectionTraits
Examples:
Point_set_shape_detection_3/efficient_RANSAC_custom_shape.cpp, Point_set_shape_detection_3/efficient_RANSAC_parameters.cpp, Point_set_shape_detection_3/efficient_RANSAC_point_access.cpp, Point_set_shape_detection_3/shape_detection_basic.cpp, and Point_set_shape_detection_3/shape_detection_with_callback.cpp.

Classes

struct  Parameters
 Parameters for the shape detection algorithm. More...
 

Types

typedef Traits::Input_range Input_range
 Model of the concept Range with random access iterators, providing input points and normals through the following two property maps. More...
 
typedef Traits::Point_map Point_map
 property map to access the location of an input point.
 
typedef Traits::Normal_map Normal_map
 property map to access the unoriented normal of an input point
 
typedef Shape_base< Traits > Shape
 shape type.
 
typedef Plane< Traits > Plane_shape
 plane shape type.
 
typedef unspecified_type Shape_range
 An Iterator_range with a bidirectional constant iterator type with value type boost::shared_ptr<Shape>.
 
typedef unspecified_type Plane_range
 An Iterator_range with a bidirectional constant iterator type with value type boost::shared_ptr<Plane_shape>.
 
typedef unspecified_type Point_index_range
 An Iterator_range with a bidirectional iterator with value type std::size_t as indices into the input data that has not been assigned to a shape. More...
 

Initialization

 Efficient_RANSAC (Traits t=Traits())
 Constructs an empty shape detection object.
 
 ~Efficient_RANSAC ()
 Releases all memory allocated by this instances including shapes.
 
const Traits & traits () const
 Retrieves the traits class.
 
const Point_map & point_map () const
 Retrieves the point property map.
 
const Normal_map & normal () const
 Retrieves the normal property map.
 
Input_iterator input_iterator_first () const
 
Input_iterator input_iterator_beyond () const
 
void set_input (Input_range &input_range, Point_map point_map=Point_map(), Normal_map normal_map=Normal_map())
 Sets the input data. More...
 
template<class Shape_type >
void add_shape_factory ()
 Registers in the detection engine the shape type ShapeType that must inherit from Shape_base. More...
 
bool preprocess ()
 Constructs internal data structures required for the shape detection. More...
 

Memory Management

void clear_shape_factories ()
 Removes all shape types registered for detection.
 
void clear_octrees ()
 Frees memory allocated for the internal search structures but keeps the detected shapes. More...
 
void clear ()
 Calls clear_octrees() and removes all detected shapes. More...
 

Detection

bool detect (const Parameters &options=Parameters(), const cpp11::function< bool(double)> &callback=cpp11::function< bool(double)>())
 Performs the shape detection. More...
 

Access

 


Shape_range shapes () const


 Returns an Iterator_range with a bidirectional iterator with value type boost::shared_ptr<Shape> over the detected shapes in the order of detection.  More...


 


Plane_range planes () const


 Returns an Iterator_range with a bidirectional iterator with value type boost::shared_ptr<Plane_shape> over only the detected planes in the order of detection.  More...


 



std::size_t number_of_unassigned_points ()


 Number of points not assigned to a shape. 


 



Point_index_range indices_of_unassigned_points ()


 Returns an Iterator_range with a bidirectional iterator with value type std::size_t as indices into the input data that has not been assigned to a shape. 


 




Member Typedef Documentation



◆ Input_range








template<class Traits > 

      

        

          typedef Traits::Input_range CGAL::Shape_detection_3::Efficient_RANSAC< Traits >::Input_range
        

      





Model of the concept Range with random access iterators, providing input points and normals through the following two property maps. 








◆ Point_index_range








template<class Traits > 

      

        

          typedef unspecified_type CGAL::Shape_detection_3::Efficient_RANSAC< Traits >::Point_index_range
        

      





An Iterator_range with a bidirectional iterator with value type std::size_t as indices into the input data that has not been assigned to a shape. 


As this range class has no size() method, the method Efficient_RANSAC::number_of_unassigned_points() is provided. 







Member Function Documentation



◆ add_shape_factory()








template<class Traits > 



template<class Shape_type > 

      

        

          void CGAL::Shape_detection_3::Efficient_RANSAC< Traits >::add_shape_factory 
          (
          )
          
        

      





Registers in the detection engine the shape type ShapeType that must inherit from Shape_base. 


For example, for registering a plane as detectable shape you should call ransac.add_shape_factory< Shape_detection_3::Plane<Traits> >();. Note that if your call is within a template, you should add the template keyword just before add_shape_factory: ransac.template add_shape_factory< Shape_detection_3::Plane<Traits> >();. 








◆ clear()








template<class Traits > 

      

        

          void CGAL::Shape_detection_3::Efficient_RANSAC< Traits >::clear 
          (
          )
          
        

      





Calls clear_octrees() and removes all detected shapes. 


All internal structures are cleaned, including formerly detected shapes. Thus iterators and ranges retrieved through shapes(), planes() and indices_of_unassigned_points() are invalidated. 








◆ clear_octrees()








template<class Traits > 

      

        

          void CGAL::Shape_detection_3::Efficient_RANSAC< Traits >::clear_octrees 
          (
          )
          
        

      





Frees memory allocated for the internal search structures but keeps the detected shapes. 


It invalidates the range retrieved using unassigned_points(). 








◆ detect()








template<class Traits > 

      

        

          bool CGAL::Shape_detection_3::Efficient_RANSAC< Traits >::detect 
          (
          const Parameters & 
          options = Parameters(), 
        

        

          
          
          const cpp11::function< bool(double)> & 
          callback = cpp11::function<bool(double)>() 
        

        

          
          )
          
        

      





Performs the shape detection. 


Shape types considered during the detection are those registered using add_shape_factory().


Parameters

  

    
optionsParameters for shape detection.

    
callbackcan be omitted if the algorithm should be run without any callback. It is called regularly when the algorithm is running: the current advancement (between 0. and 1.) is passed as parameter. If it returns true, then the algorithm continues its execution normally; if it returns false, the algorithm is stopped. Note that this interruption may leave the class in an invalid state.

  

  




Returns
true if shape types have been registered and input data has been set. Otherwise, false is returned. 








◆ planes()








template<class Traits > 

      

        

          Plane_range CGAL::Shape_detection_3::Efficient_RANSAC< Traits >::planes 
          (
          )
           const
        

      





Returns an Iterator_range with a bidirectional iterator with value type boost::shared_ptr<Plane_shape> over only the detected planes in the order of detection. 


Depending on the chosen probability for the detection, the planes are ordered with decreasing size. 








◆ preprocess()








template<class Traits > 

      

        

          bool CGAL::Shape_detection_3::Efficient_RANSAC< Traits >::preprocess 
          (
          )
          
        

      





Constructs internal data structures required for the shape detection. 


These structures only depend on the input data, i.e. the points and normal vectors. This method is called by detect(), if it was not called before by the user. 








◆ set_input()








template<class Traits > 

      

        

          void CGAL::Shape_detection_3::Efficient_RANSAC< Traits >::set_input 
          (
          Input_range & 
          input_range, 
        

        

          
          
          Point_map 
          point_map = Point_map(), 
        

        

          
          
          Normal_map 
          normal_map = Normal_map() 
        

        

          
          )
          
        

      





Sets the input data. 


The range must stay valid until the detection has been performed and the access to the results is no longer required. The data in the input is reordered by the methods detect() and preprocess(). This function first calls clear(). 


Parameters

  

    
input_rangerange of input data. 

    
point_mapproperty map to access the position of an input point. 

    
normal_mapproperty map to access the normal of an input point. 

  

  










◆ shapes()








template<class Traits > 

      

        

          Shape_range CGAL::Shape_detection_3::Efficient_RANSAC< Traits >::shapes 
          (
          )
           const
        

      





Returns an Iterator_range with a bidirectional iterator with value type boost::shared_ptr<Shape> over the detected shapes in the order of detection. 


Depending on the chosen probability for the detection, the shapes are ordered with decreasing size.