CGAL 4.14 - Point Set Shape Detection
CGAL::Shape_detection_3::Efficient_RANSAC< Traits > Class Template 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
 Traits a 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_mappoint_map () const
Retrieves the point property map.

const Normal_mapnormal () 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 >
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.

## ◆ 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

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() )

Performs the shape detection.

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

Parameters
 options Parameters for shape detection. callback can 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_range range of input data. point_map property map to access the position of an input point. normal_map property 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.