#include <CGAL/Shape_detection/Efficient_RANSAC/Efficient_RANSAC.h>

Definition

Shape detection algorithm based on the 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 must be a model of EfficientRANSACTraits.

Examples:: Shape_detection/efficient_RANSAC_and_plane_regularization.cpp, Shape_detection/efficient_RANSAC_basic.cpp, Shape_detection/efficient_RANSAC_with_callback.cpp, Shape_detection/efficient_RANSAC_with_custom_shape.cpp, Shape_detection/efficient_RANSAC_with_parameters.cpp, and Shape_detection/efficient_RANSAC_with_point_access.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 Iterator_range< Point_index_iterator >	Point_index_range

Initialization
	Efficient_RANSAC (Traits t=Traits())
	Constructs an empty shape detection object.

	~Efficient_RANSAC ()
	Releases all memory allocated by this instance 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 the shape type `ShapeType` in the detection engine 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 std::function< bool(double)> &callback=std::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 () const
	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::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.

Member Function Documentation

◆ add_shape_factory()

template<class Traits >

template<class Shape_type >

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

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

For example, for registering a plane as detectable shape, you should call ransac.add_shape_factory< Shape_detection::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::Plane<Traits> >();.

◆ clear()

template<class Traits >

void CGAL::Shape_detection::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::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::Efficient_RANSAC< Traits >::detect	(	const Parameters &	options = `Parameters()`,
		const std::function< bool(double)> &	callback = `std::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.0 and 1.0) 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::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::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::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.

Examples:: Shape_detection/efficient_RANSAC_with_custom_shape.cpp.

◆ shapes()

template<class Traits >

Shape_range CGAL::Shape_detection::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

Member Function Documentation

◆ add_shape_factory()

◆ clear()

◆ clear_octrees()

◆ detect()

◆ planes()

◆ preprocess()

◆ set_input()

◆ shapes()