CGAL 6.1 - Kinetic Surface Reconstruction

Loading...
Searching...
No Matches
List of all members | Classes | Public Types | Public Member Functions
CGAL::Kinetic_surface_reconstruction_3< GeomTraits, PointRange, PointMap, NormalMap, IntersectionKernel > Class Template Reference
Reference Manual

`#include <CGAL/Kinetic_surface_reconstruction_3.h>`

## Definition

template<typename GeomTraits, typename PointRange, typename PointMap, typename NormalMap, typename IntersectionKernel = CGAL::Exact_predicates_exact_constructions_kernel>
class CGAL::Kinetic_surface_reconstruction_3< GeomTraits, PointRange, PointMap, NormalMap, IntersectionKernel >

Pipeline for piecewise planar surface reconstruction from a point cloud via inside/outside labeling of a kinetic partition using min-cut.

Template Parameters

  GeomTraits | must be a model of `KineticShapePartitionTraits_3`.
  PointRange | must be a range of 3D points and corresponding 3D normal vectors whose iterator type is `RandomAccessIterator`.
  PointMap | a model of `ReadablePropertyMap` whose key type is the value type of the `PointRange` and value type is `GeomTraits::Point_3`
  NormalMap | a model of `ReadablePropertyMap` whose key type is the value type of the `PointRange` and value type is `GeomTraits::Vector_3`
  IntersectionKernel | must be a model of `Kernel` using exact computations. Defaults to `CGAL::Exact_predicates_exact_constructions_kernel`. Used for the internal kinetic shape partition.

Examples
  Kinetic_surface_reconstruction/ksr_basic.cpp, Kinetic_surface_reconstruction/ksr_building.cpp, and Kinetic_surface_reconstruction/ksr_parameters.cpp.

## Public Types
using | Kernel = GeomTraits
using | Intersection_kernel = IntersectionKernel
using | FT = typename Kernel::FT
using | Point_3 = typename Kernel::Point_3
using | Plane_3 = typename Kernel::Plane_3
using | Point_range = PointRange
using | KSP = Kinetic_space_partition_3< Kernel, Intersection_kernel >
using | Point_map = PointMap
using | Normal_map = NormalMap

## Public Member Functions
template<typename NamedParameters = parameters::Default_named_parameters>
| Kinetic_surface_reconstruction_3 (Point_range &points, const NamedParameters &np=CGAL::parameters::default_values())
| creates a `Kinetic_shape_reconstruction_3` object.
template<typename NamedParameters = CGAL::parameters::Default_named_parameters>
std::size_t | detect_planar_shapes (const NamedParameters &np=parameters::default_values())
| detects shapes in the provided point cloud and regularizes them.
const std::vector< Plane_3 > & | detected_planar_shapes ()
| returns the support planes of the detected and regularized shapes.
const std::vector< std::vector< std::size_t > > & | detected_planar_shape_indices ()
| returns the indices of detected and regularized shapes.
template<typename NamedParameters = CGAL::parameters::Default_named_parameters>
void | detection_and_partition (std::size_t k, const NamedParameters &np=parameters::default_values())
| detects and regularizes shapes in the provided point cloud and creates the kinetic space partition.
void | estimate_detection_parameters (FT &max_distance, FT &normal_dev, std::size_t &min_inliers)
std::size_t | estimate_max_subdivision_depth ()
template<typename NamedParameters = CGAL::parameters::Default_named_parameters>
void | initialize_partition (const NamedParameters &np=parameters::default_values())
| initializes the kinetic partition.
void | partition (std::size_t k)
| propagates the kinetic polygons in the initialized partition.
const KSP & | kinetic_partition () const
| gives access to the kinetic partition.
template<class OutputPointIterator , class OutputPolygonIterator >
void | reconstruct_with_ground (FT lambda, OutputPointIterator pit, OutputPolygonIterator polyit)
| uses min-cut to solve an inside/outside labeling of the volumes of the kinetic partition and provides the reconstructed surface as a list of indexed polygons.
template<class OutputPointIterator , class OutputPolygonIterator >
void | reconstruct (FT lambda, std::map< typename KSP::Face_support, bool > external_nodes, OutputPointIterator pit, OutputPolygonIterator polyit)
| uses min-cut to solve an inside/outside labeling of the volumes of the kinetic partition and provides the reconstructed surface as a list of indexed polygons.

## Constructor & Destructor Documentation

## ◆ Kinetic_surface_reconstruction_3()

template<typename GeomTraits , typename PointRange , typename PointMap , typename NormalMap , typename IntersectionKernel = CGAL::Exact_predicates_exact_constructions_kernel>
template<typename NamedParameters = parameters::Default_named_parameters>

CGAL::Kinetic_surface_reconstruction_3< GeomTraits, PointRange, PointMap, NormalMap, IntersectionKernel >::Kinetic_surface_reconstruction_3 | ( | Point_range & | points,
|  | const NamedParameters & | np = `CGAL::parameters::default_values()`
| ) |  |

creates a `Kinetic_shape_reconstruction_3` object.

Parameters

  points | an instance of `PointRange` with 3D points and corresponding 3D normal vectors.
  np | a sequence of Named Parameters among the ones listed below

Optional Named Parameters

  a property map associating points to the elements of the point set `points` Type: a model of `ReadablePropertyMap` whose key type is the value type of the iterator of `PointRange` and whose value type is `GeomTraits::Point_3` Default: `PointMap()` |

## Member Function Documentation

## ◆ detect_planar_shapes()

template<typename GeomTraits , typename PointRange , typename PointMap , typename NormalMap , typename IntersectionKernel = CGAL::Exact_predicates_exact_constructions_kernel>
template<typename NamedParameters = CGAL::parameters::Default_named_parameters>

std::size_t CGAL::Kinetic_surface_reconstruction_3< GeomTraits, PointRange, PointMap, NormalMap, IntersectionKernel >::detect_planar_shapes | ( | const NamedParameters & | np = `parameters::default_values()` | ) |

detects shapes in the provided point cloud and regularizes them.

Template Parameters

  NamedParameters | a sequence of Named Parameters

Parameters

  np | an instance of `NamedParameters`.

Optional Named Parameters

  a property map associating points to the elements of the point set `points` Type: a model of `ReadablePropertyMap` whose key type is the value type of the iterator of `PointRange` and whose value type is `GeomTraits::Point_3` Default: `PointMap()` |
  a property map associating normals to the elements of the point set `points` Type: a model of `ReadablePropertyMap` whose key type is the value type of the iterator of `PointRange` and whose value type is `GeomTraits::Vector_3` Default: `NormalMap()` |
  Shape detection: the number of neighbors for each point considered during region growing Type: `std::size_t` Default: 12 |
  Shape detection: the maximum distance from a point to a plane Type: `GeomTraits::FT` Default: 2% of bounding box diagonal |
  Shape detection: maximum angle in degrees between the normal of a point and the plane normal Type: `GeomTraits::FT` Default: 15 degrees |
  Shape detection: minimum number of 3D points a region must have Type: `std::size_t` Default: 0.5% of input points |
  Shape regularization: maximum allowed angle in degrees between plane normals used for parallelism, orthogonality, and axis symmetry Type: `GeomTraits::FT` Default: 5 degrees |
  Shape regularization: maximum allowed orthogonal distance between two parallel planes such that they are considered to be coplanar Type: `GeomTraits::FT` Default: 0.5% of bounding box diagonal |
  Shape regularization: indicates whether parallelism should be regularized or not Type: boolean Default: false |
  Shape regularization: indicates whether orthogonality should be regularized or not Type: boolean Default: false |
  Shape regularization: indicates whether coplanarity should be regularized or not Type: boolean Default: true |
  Shape regularization: indicates whether axis symmetry should be regularized or not Type: boolean Default: false |
  Shape regularization: an axis for symmetry regularization Type: `GeomTraits::Vector_3` Default: Z axis that is `GeomTraits::Vector_3(0, 0, 1)` |

## ◆ detected_planar_shape_indices()

template<typename GeomTraits , typename PointRange , typename PointMap , typename NormalMap , typename IntersectionKernel = CGAL::Exact_predicates_exact_constructions_kernel>

const std::vector< std::vector< std::size_t > > & CGAL::Kinetic_surface_reconstruction_3< GeomTraits, PointRange, PointMap, NormalMap, IntersectionKernel >::detected_planar_shape_indices | ( |  | ) |

returns the indices of detected and regularized shapes.

Returns
  indices into `points` for each detected planar shape.

Precondition
  shape detection performed

## ◆ detected_planar_shapes()

template<typename GeomTraits , typename PointRange , typename PointMap , typename NormalMap , typename IntersectionKernel = CGAL::Exact_predicates_exact_constructions_kernel>

const std::vector< Plane_3 > & CGAL::Kinetic_surface_reconstruction_3< GeomTraits, PointRange, PointMap, NormalMap, IntersectionKernel >::detected_planar_shapes | ( |  | ) |

returns the support planes of the detected and regularized shapes.

Returns
  vector with a `Plane_3` for each detected planar shape.

Precondition
  shape detection performed

## ◆ detection_and_partition()

template<typename GeomTraits , typename PointRange , typename PointMap , typename NormalMap , typename IntersectionKernel = CGAL::Exact_predicates_exact_constructions_kernel>
template<typename NamedParameters = CGAL::parameters::Default_named_parameters>

void CGAL::Kinetic_surface_reconstruction_3< GeomTraits, PointRange, PointMap, NormalMap, IntersectionKernel >::detection_and_partition | ( | std::size_t | k,
|  | const NamedParameters & | np = `parameters::default_values()`
| ) |  |

detects and regularizes shapes in the provided point cloud and creates the kinetic space partition.

Combines calls of `detect_planar_shapes()`, `initialize_partition()` and `partition()`.

Template Parameters

  NamedParameters | a sequence of Named Parameters

Parameters

  k | maximum number of allowed intersections for each input polygon before its expansion stops.
  np | an instance of `NamedParameters`.

Optional Named Parameters

  a property map associating points to the elements of the point set `points` Type: a model of `ReadablePropertyMap` whose key type is the value type of the iterator of `PointRange` and whose value type is `GeomTraits::Point_3` Default: `PointMap()` |
  a property map associating normals to the elements of the point set `points` Type: a model of `ReadablePropertyMap` whose key type is the value type of the iterator of `PointRange` and whose value type is `GeomTraits::Vector_3` Default: `NormalMap()` |
  Shape detection: the number of neighbors for each point considered during region growing Type: `std::size_t` Default: 12 |
  Shape detection: the maximum distance from a point to a plane Type: `GeomTraits::FT` Default: 2% of bounding box diagonal |
  Shape detection: maximum angle in degrees between the normal of a point and the plane normal Type: `GeomTraits::FT` Default: 15 degrees |
  Shape detection: minimum number of 3D points a region must have Type: `std::size_t` Default: 0.5% of input points |
  Shape regularization: maximum allowed angle in degrees between plane normals used for parallelism, orthogonality, and axis symmetry Type: `GeomTraits::FT` Default: 5 degrees |
  Shape regularization: maximum allowed orthogonal distance between two parallel planes such that they are considered to be coplanar Type: `GeomTraits::FT` Default: 0.5% of bounding box diagonal |
  Shape regularization: indicates whether parallelism should be regularized or not Type: boolean Default: false |
  Shape regularization: indicates whether orthogonality should be regularized or not Type: boolean Default: false |
  Shape regularization: indicates whether coplanarity should be regularized or not Type: boolean Default: true |
  Shape regularization: indicates whether axis symmetry should be regularized or not Type: boolean Default: false |
  Shape regularization: an axis for symmetry regularization Type: `GeomTraits::Vector_3` Default: Z axis that is `GeomTraits::Vector_3(0, 0, 1)` |
  Use the oriented bounding box instead of the axis-aligned bounding box. Type: bool Default: false |
  Factor for extension of the bounding box of the input data to be used for the partition. Type: FT Default: 1.1 |

## ◆ initialize_partition()

template<typename GeomTraits , typename PointRange , typename PointMap , typename NormalMap , typename IntersectionKernel = CGAL::Exact_predicates_exact_constructions_kernel>
template<typename NamedParameters = CGAL::parameters::Default_named_parameters>

void CGAL::Kinetic_surface_reconstruction_3< GeomTraits, PointRange, PointMap, NormalMap, IntersectionKernel >::initialize_partition | ( | const NamedParameters & | np = `parameters::default_values()` | ) |

initializes the kinetic partition.

Parameters

  np | a sequence of Named Parameters among the ones listed below

Optional Named Parameters

  Use the oriented bounding box instead of the axis-aligned bounding box. Type: bool Default: false |
  Factor for extension of the bounding box of the input data to be used for the partition. Type: FT Default: 1.1 |

Precondition
  shape detection performed

## ◆ kinetic_partition()

template<typename GeomTraits , typename PointRange , typename PointMap , typename NormalMap , typename IntersectionKernel = CGAL::Exact_predicates_exact_constructions_kernel>

const KSP & CGAL::Kinetic_surface_reconstruction_3< GeomTraits, PointRange, PointMap, NormalMap, IntersectionKernel >::kinetic_partition | ( |  | ) | const

gives access to the kinetic partition.

Returns
  created kinetic partition data structure

Precondition
  partition created

## ◆ partition()

template<typename GeomTraits , typename PointRange , typename PointMap , typename NormalMap , typename IntersectionKernel = CGAL::Exact_predicates_exact_constructions_kernel>

void CGAL::Kinetic_surface_reconstruction_3< GeomTraits, PointRange, PointMap, NormalMap, IntersectionKernel >::partition | ( | std::size_t | k | ) |

propagates the kinetic polygons in the initialized partition.

Parameters

  k | maximum number of allowed intersections for each input polygon before its expansion stops.

Precondition
  partition initialized

## ◆ reconstruct()

template<typename GeomTraits , typename PointRange , typename PointMap , typename NormalMap , typename IntersectionKernel = CGAL::Exact_predicates_exact_constructions_kernel>
template<class OutputPointIterator , class OutputPolygonIterator >

void CGAL::Kinetic_surface_reconstruction_3< GeomTraits, PointRange, PointMap, NormalMap, IntersectionKernel >::reconstruct | ( | FT | lambda,
|  | std::map< typename KSP::Face_support, bool > | external_nodes,
|  | OutputPointIterator | pit,
|  | OutputPolygonIterator | polyit
| ) |  |

uses min-cut to solve an inside/outside labeling of the volumes of the kinetic partition and provides the reconstructed surface as a list of indexed polygons.

The `external_nodes` parameter allows to indicate the preferred labels for faces on the bounding box.

Template Parameters

  OutputPointIterator | an output iterator taking `Point_3`.
  OutputPolygonIterator | an output iterator taking polygon indices `std::vector<std::size_t>`.

Parameters

  lambda | trades data faithfulness of the reconstruction for low complexity. Must be in the range `[0, 1)`.
  external_nodes | adds label preference for the faces on the bounding box. Bounding box sides without preset label are chosen by the min-cut. Setting `external_nodes[ZMIN] = true` sets the inside label as the preferred label for the ZMIN side of the bounding box.
  pit | output iterator to receive the vertices of the reconstructed surface.
  polyit | output iterator to store all polygonal faces of the reconstructed surface.

Precondition
  partition created

## ◆ reconstruct_with_ground()

template<typename GeomTraits , typename PointRange , typename PointMap , typename NormalMap , typename IntersectionKernel = CGAL::Exact_predicates_exact_constructions_kernel>
template<class OutputPointIterator , class OutputPolygonIterator >

void CGAL::Kinetic_surface_reconstruction_3< GeomTraits, PointRange, PointMap, NormalMap, IntersectionKernel >::reconstruct_with_ground | ( | FT | lambda,
|  | OutputPointIterator | pit,
|  | OutputPolygonIterator | polyit
| ) |  |

uses min-cut to solve an inside/outside labeling of the volumes of the kinetic partition and provides the reconstructed surface as a list of indexed polygons.

Estimates a horizontal ground plane within the detected shapes. Cells in the partition below the ground plane receive a weight to be labeled as inside. The z axis is considered as vertical upwards pointing.

Template Parameters

  OutputPointIterator | an output iterator taking `Point_3`.
  OutputPolygonIterator | an output iterator taking polygon indices `std::vector<std::size_t>`.

Parameters

  lambda | trades data faithfulness of the reconstruction for low complexity. Must be in the range `[0, 1)`.
  pit | output iterator to receive the vertices of the reconstructed surface.
  polyit | output iterator to store all polygonal faces of the reconstructed surface.

Precondition
  partition created