CGAL::Kinetic_surface_reconstruction_3< GeomTraits, PointRange, PointMap, NormalMap, IntersectionKernel > Class Template Reference

#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 KineticSpacePartitionTraits_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	Regions = std::vector< std::pair< Plane_3, std::vector< std::size_t > > >
using	Point_map = PointMap
using	Normal_map = NormalMap
using	LCC_traits = CGAL::Linear_cell_complex_traits< 3, CGAL::Exact_predicates_exact_constructions_kernel >
using	LCC = CGAL::Linear_cell_complex_for_combinatorial_map< 3, 3, LCC_traits, typename KSP::Linear_cell_complex_min_items >

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.
template<typename NamedParameters = CGAL::parameters::Default_named_parameters>
std::size_t	regularize_planar_shapes (const NamedParameters &np=parameters::default_values())
	regularizes planar shapes.
template<typename RegionRange >
void	insert_planar_shapes (const RegionRange &regions)
	inserts planar shapes ti skip shape detection.
template<typename Regions >
void	insert_planar_shapes_and_linear_cell_complex (const Regions &regions, const LCC &lcc)
	inserts planar shapes and a linear cell complex to skip shape detection and kinetic space partitioning.
const LCC &	get_linear_cell_complex () const
const Regions &	planar_shapes ()
	returns the detected and possibly 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)
	statistical estimation of parameters for shape detection.
std::size_t	estimate_max_subdivision_depth ()
	estimates the subdivision depth for the kinetic space partition.
template<typename NamedParameters = CGAL::parameters::Default_named_parameters>
void	partition (std::size_t k, const NamedParameters &np=parameters::default_values())
	initializes the kinetic partition and propagates the planar shapes
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

point_map 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()
normal_map 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()

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.

Template Parameters

NamedParameters

a sequence of Named Parameters

Parameters

np	an instance of NamedParameters.

Returns

the number of detected shapes.

Optional Named Parameters

k_neighbors Shape detection: the number of neighbors for each point considered during region growing Type: std::size_t Default: 12
maximum_distance Shape detection: the maximum distance from a point to a plane Type: GeomTraits::FT Default: 2% of bounding box diagonal
maximum_angle Shape detection: maximum angle in degrees between the normal of a point and the plane normal Type: GeomTraits::FT Default: 15 degrees
minimum_region_size Shape detection: minimum number of 3D points a region must have Type: std::size_t Default: 0.5% of input points

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

point_map 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()
normal_map 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()
k_neighbors Shape detection: the number of neighbors for each point considered during region growing Type: std::size_t Default: 12
maximum_distance Shape detection: the maximum distance from a point to a plane Type: GeomTraits::FT Default: 2% of bounding box diagonal
maximum_angle Shape detection: maximum angle in degrees between the normal of a point and the plane normal Type: GeomTraits::FT Default: 15 degrees
minimum_region_size Shape detection: minimum number of 3D points a region must have Type: std::size_t Default: 0.5% of input points
angle_tolerance Shape regularization: maximum allowed angle in degrees between plane normals used for parallelism, orthogonality, and axis symmetry Type: GeomTraits::FT Default: 5 degrees
maximum_offset 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
regularize_parallelism Shape regularization: indicates whether parallelism should be regularized or not Type: boolean Default: false
regularize_orthogonality Shape regularization: indicates whether orthogonality should be regularized or not Type: boolean Default: false
regularize_coplanarity Shape regularization: indicates whether coplanarity should be regularized or not Type: boolean Default: true
regularize_axis_symmetry Shape regularization: indicates whether axis symmetry should be regularized or not Type: boolean Default: false
symmetry_direction Shape regularization: an axis for symmetry regularization Type: GeomTraits::Vector_3 Default: Z axis that is GeomTraits::Vector_3(0, 0, 1)
reorient_bbox Use the oriented bounding box instead of the axis-aligned bounding box. Type: bool Default: false
bbox_dilation_ratio Factor for extension of the bounding box of the input data to be used for the partition. Type: FT Default: 1.1

estimate_detection_parameters()

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 >::estimate_detection_parameters	(	FT &	max_distance,
		FT &	normal_dev,
		std::size_t &	min_inliers
	)

statistical estimation of parameters for shape detection.

Parameters

max_distance	will be set to 4 times the mean distance of local point neighborhoods.
normal_dev	will be set to the mean normal deviation of local point neighborhoods.
min_inliers	will be set to 0.5% of the number of points.

estimate_max_subdivision_depth()

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

std::size_t CGAL::Kinetic_surface_reconstruction_3< GeomTraits, PointRange, PointMap, NormalMap, IntersectionKernel >::estimate_max_subdivision_depth

(

)

estimates the subdivision depth for the kinetic space partition.

Returns

the estimated subdivision depth.

get_linear_cell_complex()

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

const LCC & CGAL::Kinetic_surface_reconstruction_3< GeomTraits, PointRange, PointMap, NormalMap, IntersectionKernel >::get_linear_cell_complex

(

)

const

Returns

linear cell complex from the kinetic space partition.

Precondition

partition() called after detection or insertion of planar shapes.

insert_planar_shapes()

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

template<typename RegionRange >

void CGAL::Kinetic_surface_reconstruction_3< GeomTraits, PointRange, PointMap, NormalMap, IntersectionKernel >::insert_planar_shapes

(

const RegionRange &

regions

)

inserts planar shapes ti skip shape detection.

Template Parameters

RegionRange

a model of Range whose iterator type is RandomAccessIterator and value type is std::pair<Plane_3, std::vector<item>>, where item is the key type of Point_map.

Parameters

regions

a range of planar shapes providing their support plane and indices into the point cloud.

insert_planar_shapes_and_linear_cell_complex()

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

template<typename Regions >

void CGAL::Kinetic_surface_reconstruction_3< GeomTraits, PointRange, PointMap, NormalMap, IntersectionKernel >::insert_planar_shapes_and_linear_cell_complex	(	const Regions &	regions,
		const LCC &	lcc
	)

inserts planar shapes and a linear cell complex to skip shape detection and kinetic space partitioning.

The input shapes regions need to be identical to the shapes used to create the lcc.

Template Parameters

RegionRange

a model of Range whose iterator type is RandomAccessIterator and value type is std::pair<Plane_3, std::vector<item>>, where item is the key type of Point_map.

Parameters

regions	a range of planar shapes providing their support plane and indices into the point cloud.
lcc	linear cell complex created by Kinetic_space_partition_3.

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>

template<typename NamedParameters = CGAL::parameters::Default_named_parameters>

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

initializes the kinetic partition and propagates the planar shapes

Template Parameters

NamedParameters

a sequence of Named Parameters

Parameters

k	maximum number of allowed intersections for each input polygon before its expansion stops.
np	a sequence of Named Parameters among the ones listed below

Precondition

planar shapes detected or inserted

Optional Named Parameters

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

planar_shapes()

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

const Regions & CGAL::Kinetic_surface_reconstruction_3< GeomTraits, PointRange, PointMap, NormalMap, IntersectionKernel >::planar_shapes

(

)

returns the detected and possibly regularized shapes.

Returns

vector with std::pair<Plane_3, std::vector<std::size_t> for each planar shape containing the support plane and the inlier indices.

Precondition

shape detection performed or shapes inserted

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

regularize_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 >::regularize_planar_shapes

(

const NamedParameters &

np = parameters::default_values()

)

regularizes planar shapes.

Requires detected or inserted planar shapes and needs to be called before partition().

Template Parameters

RegionRange	a model of Range whose iterator type is RandomAccessIterator and value type is std::pair<Plane_3, std::vector<item>>, where item is the key type of Point_map.
NamedParameters	a sequence of Named Parameters

Parameters

np	an instance of NamedParameters.

Returns

the number of shapes after regularization.

Precondition

shape detection performed or shapes inserted

Optional Named Parameters

angle_tolerance Shape regularization: maximum allowed angle in degrees between plane normals used for parallelism, orthogonality, and axis symmetry Type: GeomTraits::FT Default: 5 degrees
maximum_offset 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
regularize_parallelism Shape regularization: indicates whether parallelism should be regularized or not Type: boolean Default: false
regularize_orthogonality Shape regularization: indicates whether orthogonality should be regularized or not Type: boolean Default: false
regularize_coplanarity Shape regularization: indicates whether coplanarity should be regularized or not Type: boolean Default: true
regularize_axis_symmetry Shape regularization: indicates whether axis symmetry should be regularized or not Type: boolean Default: false
symmetry_direction Shape regularization: an axis for symmetry regularization Type: GeomTraits::Vector_3 Default: Z axis that is GeomTraits::Vector_3(0, 0, 1)