CGAL 6.1 - Shape Detection

Loading...
Searching...
No Matches
List of all members | Classes
CGAL::Shape_detection::Efficient_RANSAC< Traits > Class Template Reference
Reference Manual » Efficient RANSAC

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

## Definition

template<class Traits>
class CGAL::Shape_detection::Efficient_RANSAC< Traits >

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_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.
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
| `Iterator_range` with a bidirectional constant iterator type with value type `std::shared_ptr<Shape>`.
typedef unspecified_type | Plane_range
| `Iterator_range` with a bidirectional constant iterator type with value type `std::shared_ptr<Plane_shape>`.
typedef unspecified_type | Point_index_range
| `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.

## 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.
template<class Shape_type >
void | add_shape_factory ()
| Registers the shape type `ShapeType` in the detection engine that must inherit from `Shape_base`.
bool | preprocess ()
| Constructs internal data structures required for the shape detection.

## 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.
void | clear ()
| Calls `clear_octrees()` and removes all detected shapes.

## Detection
bool | detect (const Parameters &options=Parameters(), const std::function< bool(double)> &callback=std::function< bool(double)>())
| Performs the shape detection.

## Access
Shape_range | shapes () const
| Returns an `Iterator_range` with a bidirectional iterator with value type `std::shared_ptr<Shape>` over the detected shapes in the order of detection.
Plane_range | planes () const
| Returns an `Iterator_range` with a bidirectional iterator with value type `std::shared_ptr<Plane_shape>` over only the detected planes in the order of detection.
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

## ◆ Point_index_range

template<class Traits >

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

`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::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 `std::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 `std::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.