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

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.

Definition

Classes

Types

Initialization

Memory Management

Detection

Access

Member Typedef Documentation

◆ Input_range

◆ Point_index_range

Member Function Documentation

◆ add_shape_factory()

◆ clear()

◆ clear_octrees()

◆ detect()

◆ planes()

◆ preprocess()

◆ set_input()

◆ shapes()