\( \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.8 - Point Set Shape Detection

All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Groups Pages
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 [1].

Template Parameters

  Traits | a model of `EfficientRANSACTraits`

Examples:
  Point_set_shape_detection_3/efficient_RANSAC_basic.cpp, Point_set_shape_detection_3/efficient_RANSAC_custom_shape.cpp, Point_set_shape_detection_3/efficient_RANSAC_parameters.cpp, and Point_set_shape_detection_3/efficient_RANSAC_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 unspecified_type | Shape_range
| An `Iterator_range` with a bidirectional constant iterator type with value type `boost::shared_ptr<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 engine.
| ~Efficient_RANSAC ()
| Releases all memory allocated by this instances including shapes.
const Traits & | traits () const
| Retrieves the traits class.
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())
| 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...
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

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.

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> >();`.

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()` and `indices_of_unassigned_points()` are invalidated.

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

template<class Traits >

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

Performs the shape detection.

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

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

Parameters

  options | Parameters for shape detection.

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.

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.

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.