#include <CGAL/Point_set_3.h>

Definition

template<typename Point, typename Vector = typename Kernel_traits<Point>::Kernel::Vector_3>
class CGAL::Point_set_3< Point, Vector >

A collection of points with dynamically associated properties.

An instance of this class stores a set of indices of type Index, each representing a point. Properties can be associated to each point and can be retrieved using the index of the point. There are two particular properties that are hard coded by this class: the coordinates of the points and the normal vectors.

The coordinates of a point can be access using the index of the point and the member function point(). This property is always present. The normal vector of a point can be accessed using the index of the point and the normal() function. This property must be explicitly created.

All properties can be accessed as a range using the functions points(), normals(), and range() for points coordinates, normal vectors, and other properties respectively.

Removing a point with properties is achieved by moving its Index at the end of the container and keeping track of the number of removed elements. A garbage collection method must be called to really remove it from memory.

For convenience, all functions of the package Point Set Processing Reference are provided with an overload that takes a Point_set_3 object as an argument.

Template Parameters

Point	Point type.
Vector	Normal vector type.

Is Model Of:: Range

Examples:: Point_set_3/point_set.cpp, Point_set_3/point_set_advanced.cpp, Point_set_3/point_set_algo.cpp, Point_set_3/point_set_property.cpp, Point_set_3/point_set_read_ply.cpp, and Point_set_3/point_set_read_xyz.cpp.

Classes
class	Index
	This represents a point with associated properties. More...

Public Types
typedef unspecified_type	iterator
	Iterator type of the point set with value type `Index` More...

typedef unspecified_type	const_iterator
	Constant iterator type of the point set with value type `Index` More...

typedef Property_map< Point >	Point_map
	Property map of points.

typedef Property_map< Vector >	Vector_map
	Property map of vectors.

typedef Property_range< Point >	Point_range
	Constant range of points.

typedef Property_range< Vector >	Vector_range
	Constant range of vectors.

Related Functions
(Note that these are not member functions.)
template<typename Point , typename Vector >
std::istream &	operator>> (std::istream &is, CGAL::Point_set_3< Point, Vector > &ps)
	Reads the point set from an input stream that can be either: More...

template<typename Point , typename Vector >
std::ostream &	operator<< (std::ostream &os, const CGAL::Point_set_3< Point, Vector > &ps)
	Inserts the point set in an output stream in ASCII PLY format. More...

template<typename Point , typename Vector >
Point_set_3< Point, Vector > &	operator+= (Point_set_3< Point, Vector > &ps, Point_set_3< Point, Vector > &other)
	Append `other` at the end of `ps`. More...

Construction, Destruction, Assignment
	Point_set_3 (bool with_normal_map=false)
	Creates an empty point set with no additional property. More...

Point_set_3 &	operator= (const Point_set_3 &ps)
	Assignment operator, all properties with their content are copied.

Memory Management
bool	is_empty () const
	Returns `true` if the number of elements not marked as removed is 0, `false` otherwise. More...

std::size_t	number_of_points () const
	Returns the number of elements (not counting elements marked as removed). More...

bool	join (Point_set_3 &other)
	Merges `other` in the point set. More...

void	clear ()
	Clears the point set properties and content. More...

void	clear_properties ()
	Clears all properties created. More...

void	reserve (std::size_t s)
	Increases the capacity of internal containers to be able to efficiently accommodate at least `s` elements. More...

void	resize (std::size_t s)
	Changes size of the point set. More...

Adding Points and Normals
iterator	insert ()
	Inserts a new element with default property values. More...

iterator	insert (const Point &p)
	Inserts new point with default property values. More...

iterator	insert (const Point &p, const Vector &n)
	Convenience function to add a point with a normal vector. More...

Accessors and Iterators
iterator	begin ()
	Returns the begin iterator.

iterator	end ()
	Returns the past-the-end iterator. More...

const_iterator	begin () const
	Returns the begin constant iterator.

const_iterator	end () const
	Returns the past-the-end constant iterator. More...

Point &	point (const Index &index)
	Returns a reference to the point corresponding to `index`.

const Point &	point (const Index &index) const
	Returns a constant reference to the point corresponding to `index`.

Vector &	normal (const Index &index)
	Returns a reference to the normal corresponding to `index`. More...

const Vector &	normal (const Index &index) const
	Returns a constant reference to the normal corresponding to `index`. More...

Removal Functions
void	remove (iterator first, iterator last)
	Marks all elements between `first` and `last` as removed. More...

void	remove (iterator it)
	Marks element specified by iterator as removed. More...

void	remove (const Index &index)
	Marks element specified by `Index` as removed. More...

Garbage Management
bool	is_removed (const_iterator it) const
	Returns `true` if the element is marked as removed, `false` otherwise. More...

const_iterator	garbage_begin () const
	Returns the constant iterator to the first element marked as removed (equal to `garbage_end()` if no elements are marked as removed.

const_iterator	garbage_end () const
	Returns the past-the-end constant iterator of the elements marked as removed.

std::size_t	number_of_removed_points () const
	Number of removed points.

bool	has_garbage () const
	Returns `true` if there are elements marked as removed, `false` otherwise.

void	collect_garbage ()
	Erases from memory the elements marked as removed.

Property Handling
A property `Property_map<Type>` allows to associate properties of type `Type` to a point. Properties can be added, looked up with a string and removed at runtime.
template<class Type >
using	Property_map = unspecified_type
	Model of `LvaluePropertyMap` with `Index` as a key type and `Type` as value type. More...

template<typename T >
bool	has_property_map (const std::string &name) const
	Tests whether property `name` of type `T` already exists. More...

template<class T >
std::pair< Property_map< T > , bool >	add_property_map (const std::string &name, const T t=T())
	Adds a new property `name` of type `T` with given default value. More...

template<class T >
std::pair< Property_map< T > , bool >	property_map (const std::string &name) const
	Returns the property `name` of type `T`. More...

template<class T >
bool	remove_property_map (Property_map< T > &prop)
	Removes the specified property. More...

bool	has_normal_map () const
	Convenience method that tests whether the point set has normals. More...

bool	add_normal_map (const Vector &default_value=Vector(0., 0., 0.))
	Convenience method that adds a normal property. More...

Vector_map	normal_map ()
	Returns the property map of the normal property. More...

const Vector_map	normal_map () const
	Returns the property map of the normal property (constant version). More...

bool	remove_normal_map ()
	Convenience method that removes the normal property. More...

Point_map	point_map ()
	Returns the property map of the point property.

const Point_map	point_map () const
	Returns the property map of the point property (constant version).

std::vector< std::string >	properties () const
	Returns a vector with all strings that describe properties.

Ranges
template<class Type >
using	Property_range = unspecified_type
	Model of `ConstRange` that handles constant ranges for property maps with value type `Type`. More...

template<class T >
Property_range< T >	range (const Property_map< T > &pmap) const
	Returns a property as a range.

Point_range	points () const
	Returns a constant range of points.

Vector_range	normals () const
	Returns a constant range of normals.

Push Property Maps and Inserters (Advanced)
Advanced The following method are specifically designed to make `CGAL::Point_set_3` usable with CGAL input/output functions.
template<class Property >
using	Property_back_inserter = unspecified_type
	Advanced Model of `OutputIterator` used to insert elements by defining the value of the property `Property`. More...

template<class Property >
using	Push_property_map = unspecified_type
	Advanced Model of `WritablePropertyMap` based on `Property` and that is allowed to push new items to the point set if needed. More...

typedef Property_back_inserter < Index_map >	Index_back_inserter
	Advanced Back inserter on indices

typedef Property_back_inserter < Point_map >	Point_back_inserter
	Advanced Back inserter on points

typedef Push_property_map < Point_map >	Point_push_map
	Advanced Property map for pushing new points

typedef Push_property_map < Vector_map >	Vector_push_map
	Advanced Property map for pushing new vectors

template<class T >
Push_property_map < Property_map< T > >	push_property_map (Property_map< T > &prop)
	Advanced This is an advanced function. More...

Point_push_map	point_push_map ()
	Advanced This is an advanced function. More...

Vector_push_map	normal_push_map ()
	Advanced This is an advanced function. More...

Index_back_inserter	index_back_inserter ()
	Advanced This is an advanced function. More...

Point_back_inserter	point_back_inserter ()
	Advanced This is an advanced function. More...

Member Typedef Documentation

template<typename Point , typename Vector = typename Kernel_traits<Point>::Kernel::Vector_3>

typedef unspecified_type CGAL::Point_set_3< Point, Vector >::const_iterator

Constant iterator type of the point set with value type Index

Is Model Of:: RandomAccessIterator

template<typename Point , typename Vector = typename Kernel_traits<Point>::Kernel::Vector_3>

typedef unspecified_type CGAL::Point_set_3< Point, Vector >::iterator

Iterator type of the point set with value type Index

Is Model Of:: RandomAccessIterator

template<typename Point , typename Vector = typename Kernel_traits<Point>::Kernel::Vector_3>

template<class Property >

using CGAL::Point_set_3< Point, Vector >::Property_back_inserter = unspecified_type

Advanced

Model of OutputIterator used to insert elements by defining the value of the property Property.

template<typename Point , typename Vector = typename Kernel_traits<Point>::Kernel::Vector_3>

template<class Type >

using CGAL::Point_set_3< Point, Vector >::Property_map = unspecified_type

Model of LvaluePropertyMap with Index as a key type and Type as value type.

template<typename Point , typename Vector = typename Kernel_traits<Point>::Kernel::Vector_3>

template<class Type >

using CGAL::Point_set_3< Point, Vector >::Property_range = unspecified_type

Model of ConstRange that handles constant ranges for property maps with value type Type.

template<typename Point , typename Vector = typename Kernel_traits<Point>::Kernel::Vector_3>

template<class Property >

using CGAL::Point_set_3< Point, Vector >::Push_property_map = unspecified_type

Advanced

Model of WritablePropertyMap based on Property and that is allowed to push new items to the point set if needed.

Constructor & Destructor Documentation

template<typename Point , typename Vector = typename Kernel_traits<Point>::Kernel::Vector_3>

CGAL::Point_set_3< Point, Vector >::Point_set_3 ( bool with_normal_map = false)

Creates an empty point set with no additional property.

Parameters

with_normal_map true if the normal map should be added. If false (default value), the normal map can still be added later on (see add_normal_map()).

Member Function Documentation

template<typename Point , typename Vector = typename Kernel_traits<Point>::Kernel::Vector_3>

bool CGAL::Point_set_3< Point, Vector >::add_normal_map ( const Vector & default_value = Vector(0., 0., 0.))

Convenience method that adds a normal property.

This method adds a property of type Vector and named normal.

Returns: true if the property was added, false if it already existed.

template<typename Point , typename Vector = typename Kernel_traits<Point>::Kernel::Vector_3>

template<class T >

std::pair<Property_map<T>, bool> CGAL::Point_set_3< Point, Vector >::add_property_map	(	const std::string &	name,
		const T	t = `T()`
	)

Adds a new property name of type T with given default value.

Template Parameters

T	type of the property.

Parameters

name	Name of the property.
t	Value taken by the property on already created elements.

Returns: Returns a pair containing the property map and a Boolean that is true if the property was added and false if it already exists (and was therefore not added but only returned).

template<typename Point , typename Vector = typename Kernel_traits<Point>::Kernel::Vector_3>

void CGAL::Point_set_3< Point, Vector >::clear ( )

Clears the point set properties and content.

After calling this function, the object is the same as a newly constructed object. The additional properties (such as normal vectors) are also removed and must thus be re-added if needed.

template<typename Point , typename Vector = typename Kernel_traits<Point>::Kernel::Vector_3>

void CGAL::Point_set_3< Point, Vector >::clear_properties ( )

Clears all properties created.

After calling this function, all properties are removed. The points are left unchanged.

template<typename Point , typename Vector = typename Kernel_traits<Point>::Kernel::Vector_3>

iterator CGAL::Point_set_3< Point, Vector >::end ( )

Returns the past-the-end iterator.

Note: The returned value is the same as garbage_begin().

template<typename Point , typename Vector = typename Kernel_traits<Point>::Kernel::Vector_3>

const_iterator CGAL::Point_set_3< Point, Vector >::end ( ) const

Returns the past-the-end constant iterator.

Note: The returned value is the same as garbage_begin().

template<typename Point , typename Vector = typename Kernel_traits<Point>::Kernel::Vector_3>

bool CGAL::Point_set_3< Point, Vector >::has_normal_map ( ) const

Convenience method that tests whether the point set has normals.

This method tests whether a property of type Vector and named normal exists.

template<typename Point , typename Vector = typename Kernel_traits<Point>::Kernel::Vector_3>

template<typename T >

bool CGAL::Point_set_3< Point, Vector >::has_property_map ( const std::string & name) const

Tests whether property name of type T already exists.

Template Parameters

T	type of the property.

Parameters

name	Name of the property.

template<typename Point , typename Vector = typename Kernel_traits<Point>::Kernel::Vector_3>

Index_back_inserter CGAL::Point_set_3< Point, Vector >::index_back_inserter ( )

Advanced

This is an advanced function.

Returns the back inserter on the index property.

template<typename Point , typename Vector = typename Kernel_traits<Point>::Kernel::Vector_3>

iterator CGAL::Point_set_3< Point, Vector >::insert ( )

Inserts a new element with default property values.

Returns: The iterator on the newly added element.

Note: If a reallocation happens, all iterators, pointers and references related to the container are invalidated. Otherwise, only the end iterator is invalidated, and all iterators, pointers and references to elements are guaranteed to keep referring to the same elements they were referring to before the call.

template<typename Point , typename Vector = typename Kernel_traits<Point>::Kernel::Vector_3>

iterator CGAL::Point_set_3< Point, Vector >::insert ( const Point & p)

Inserts new point with default property values.

Parameters

p	Point to insert

Note: Properties of the added point are initialized to their default value.; If a reallocation happens, all iterators, pointers and references related to the container are invalidated. Otherwise, only the end iterator is invalidated, and all iterators, pointers and references to elements are guaranteed to keep referring to the same elements they were referring to before the call.

Returns: The iterator on the newly added element.

template<typename Point , typename Vector = typename Kernel_traits<Point>::Kernel::Vector_3>

iterator CGAL::Point_set_3< Point, Vector >::insert	(	const Point &	p,
		const Vector &	n
	)

Convenience function to add a point with a normal vector.

Parameters

p	Point to insert
n	Associated normal vector

Note: Properties of the added point other than its normal vector are initialized to their default value.; A normal property must have been added to the point set before using this method.; If a reallocation happens, all iterators, pointers and references related to the container are invalidated. Otherwise, only the end iterator is invalidated, and all iterators, pointers and references to elements are guaranteed to keep referring to the same elements they were referring to before the call.

Returns: The iterator on the newly added element.

template<typename Point , typename Vector = typename Kernel_traits<Point>::Kernel::Vector_3>

bool CGAL::Point_set_3< Point, Vector >::is_empty ( ) const

Returns true if the number of elements not marked as removed is 0, false otherwise.

Note: This does not count the removed elements.; The method empty() is also available (see Range) and does the same thing.

template<typename Point , typename Vector = typename Kernel_traits<Point>::Kernel::Vector_3>

bool CGAL::Point_set_3< Point, Vector >::is_removed ( const_iterator it) const

Returns true if the element is marked as removed, false otherwise.

Note: When iterating between begin() and end(), no element marked as removed can be found.

template<typename Point , typename Vector = typename Kernel_traits<Point>::Kernel::Vector_3>

bool CGAL::Point_set_3< Point, Vector >::join ( Point_set_3< Point, Vector > & other)

Merges other in the point set.

Shifts the indices of points of other by number_of_points() + other.number_of_points().

Copies entries of all property maps which have the same name in the point set and other. Property maps which are only in other are ignored.

Note: Garbage is collected in both point sets when calling this function.

template<typename Point , typename Vector = typename Kernel_traits<Point>::Kernel::Vector_3>

Vector& CGAL::Point_set_3< Point, Vector >::normal ( const Index & index)

Returns a reference to the normal corresponding to index.

Note: The normal property must have been added to the point set before calling this method (see add_normal_map()).

template<typename Point , typename Vector = typename Kernel_traits<Point>::Kernel::Vector_3>

const Vector& CGAL::Point_set_3< Point, Vector >::normal ( const Index & index) const

Returns a constant reference to the normal corresponding to index.

Note: The normal property must have been added to the point set before calling this method (see add_normal_map()).

template<typename Point , typename Vector = typename Kernel_traits<Point>::Kernel::Vector_3>

Vector_map CGAL::Point_set_3< Point, Vector >::normal_map ( )

Returns the property map of the normal property.

Note: The normal property must have been added to the point set before calling this method (see add_normal_map()).

template<typename Point , typename Vector = typename Kernel_traits<Point>::Kernel::Vector_3>

const Vector_map CGAL::Point_set_3< Point, Vector >::normal_map ( ) const

Returns the property map of the normal property (constant version).

Note: The normal property must have been added to the point set before calling this method (see add_normal_map()).

template<typename Point , typename Vector = typename Kernel_traits<Point>::Kernel::Vector_3>

Vector_push_map CGAL::Point_set_3< Point, Vector >::normal_push_map ( )

Advanced

This is an advanced function.

Returns the push property map of the normal property.

Note: The normal property must have been added to the point set before calling this method (see add_normal_map()).

template<typename Point , typename Vector = typename Kernel_traits<Point>::Kernel::Vector_3>

std::size_t CGAL::Point_set_3< Point, Vector >::number_of_points ( ) const

Returns the number of elements (not counting elements marked as removed).

Note: See number_of_removed_points() for getting the number of elements marked as removed.; The method size() is also available (see Range) and does the same thing.

template<typename Point , typename Vector = typename Kernel_traits<Point>::Kernel::Vector_3>

Point_back_inserter CGAL::Point_set_3< Point, Vector >::point_back_inserter ( )

Advanced

This is an advanced function.

Returns the back inserter on the point property.

template<typename Point , typename Vector = typename Kernel_traits<Point>::Kernel::Vector_3>

Point_push_map CGAL::Point_set_3< Point, Vector >::point_push_map ( )

Advanced

This is an advanced function.

Returns the push property map of the point property.

template<typename Point , typename Vector = typename Kernel_traits<Point>::Kernel::Vector_3>

template<class T >

std::pair<Property_map<T>,bool> CGAL::Point_set_3< Point, Vector >::property_map ( const std::string & name) const

Returns the property name of type T.

Template Parameters

T	type of the property.

Parameters

name	Name of the property.

Returns: Returns a pair containing: the specified property map and a Boolean set to true or an empty property map and a Boolean set to false (if the property was not found).

Examples:: Point_set_3/point_set_property.cpp.

template<typename Point , typename Vector = typename Kernel_traits<Point>::Kernel::Vector_3>

template<class T >

Push_property_map<Property_map<T> > CGAL::Point_set_3< Point, Vector >::push_property_map ( Property_map< T > & prop)

Advanced

This is an advanced function.

Returns the push property map of the given property.

Template Parameters

T	type of the property.

Parameters

prop	The property map.

Returns: Returns a pair containing: the specified property map and a Boolean set to true or an empty property map and a Boolean set to false (if the property was not found).

template<typename Point , typename Vector = typename Kernel_traits<Point>::Kernel::Vector_3>

void CGAL::Point_set_3< Point, Vector >::remove	(	iterator	first,
		iterator	last
	)

Marks all elements between first and last as removed.

Note: The elements are just marked as removed and are not erased from the memory. collect_garbage() should be called if the memory needs to be disallocated.; All iterators, pointers and references related to the container are invalidated.

template<typename Point , typename Vector = typename Kernel_traits<Point>::Kernel::Vector_3>

void CGAL::Point_set_3< Point, Vector >::remove ( iterator it)

Marks element specified by iterator as removed.

Note: The element is just marked as removed and is not erased from the memory. collect_garbage() should be called if the memory needs to be freed.; All iterators, pointers and references related to the container are invalidated.

template<typename Point , typename Vector = typename Kernel_traits<Point>::Kernel::Vector_3>

void CGAL::Point_set_3< Point, Vector >::remove ( const Index & index)

Marks element specified by Index as removed.

Note: The element is just marked as removed and is not erased from the memory. collect_garbage() should be called if the memory needs to be freed.; All iterators, pointers and references related to the container are invalidated.

template<typename Point , typename Vector = typename Kernel_traits<Point>::Kernel::Vector_3>

bool CGAL::Point_set_3< Point, Vector >::remove_normal_map ( )

Convenience method that removes the normal property.

Returns: Returns true if the property was removed and false if the property was not found.

template<typename Point , typename Vector = typename Kernel_traits<Point>::Kernel::Vector_3>

template<class T >

bool CGAL::Point_set_3< Point, Vector >::remove_property_map ( Property_map< T > & prop)

Removes the specified property.

Template Parameters

T	type of the property.

Parameters

prop	The property.

Returns: Returns true if the property was removed and false if the property was not found.

template<typename Point , typename Vector = typename Kernel_traits<Point>::Kernel::Vector_3>

void CGAL::Point_set_3< Point, Vector >::reserve ( std::size_t s)

Increases the capacity of internal containers to be able to efficiently accommodate at least s elements.

Parameters

s	Expected final number of elements.

Note: This method does not change the content of the point set and is only used for optimization.

template<typename Point , typename Vector = typename Kernel_traits<Point>::Kernel::Vector_3>

void CGAL::Point_set_3< Point, Vector >::resize ( std::size_t s)

Changes size of the point set.

Parameters

s	Target size of the point set.

Note: If the given size is larger than the current size, the capacity of the internal container is extended. If there are element marked as removed, they may be overwritten. If the given size is smaller than the current size, garbage is collected and the container is resized.

Friends And Related Function Documentation

template<typename Point , typename Vector >

Point_set_3< Point, Vector > & operator+=	(	Point_set_3< Point, Vector > &	ps,
		Point_set_3< Point, Vector > &	other
	)

Shifts the indices of points of other by ps.number_of_points() + other.number_of_points().

Copies entries of all property maps which have the same name in ps and other. Property maps which are only in other are ignored.

Note: Garbage is collected in both point sets when calling this function.

Definition

template<typename Point, typename Vector = typename Kernel_traits<Point>::Kernel::Vector_3> class CGAL::Point_set_3< Point, Vector >

Classes

Public Types

Related Functions

Construction, Destruction, Assignment

Memory Management

Adding Points and Normals

Accessors and Iterators

Removal Functions

Garbage Management

Property Handling

Ranges

Push Property Maps and Inserters (Advanced)

Member Typedef Documentation

Constructor & Destructor Documentation

Member Function Documentation

Friends And Related Function Documentation

template<typename Point, typename Vector = typename Kernel_traits<Point>::Kernel::Vector_3>
class CGAL::Point_set_3< Point, Vector >