CGAL 4.12 - 3D Point Set
CGAL::Point_set_3< Point, Vector > Class Template Reference

#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:

## 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_3operator= (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...

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.

unspecified_type parameters () const
Returns a sequence of Named Parameters for Point Set Processing algorithms. More...

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

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

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

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

Back inserter on indices

typedef Property_back_inserter< Point_mapPoint_back_inserter

Back inserter on points

typedef Push_property_map< Point_mapPoint_push_map

Property map for pushing new points

typedef Push_property_map< Vector_mapVector_push_map

Property map for pushing new vectors

template<class T >
Push_property_map< Property_map< T > > push_property_map (Property_map< T > &prop)

This is an advanced function. More...

Point_push_map point_push_map ()

This is an advanced function. More...

Vector_push_map normal_push_map ()

This is an advanced function. More...

Index_back_inserter index_back_inserter ()

This is an advanced function. More...

Point_back_inserter point_back_inserter ()

This is an advanced function. More...

## ◆ const_iterator

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

## ◆ iterator

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

## ◆ Property_back_inserter

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

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

## ◆ Property_map

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.

## ◆ Property_range

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.

## ◆ Push_property_map

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

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

## ◆ Point_set_3()

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, 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).

## ◆ clear()

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.

## ◆ clear_properties()

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.

## ◆ end() [1/2]

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

## ◆ end() [2/2]

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

## ◆ has_normal_map()

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.

## ◆ has_property_map()

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.

## ◆ index_back_inserter()

template<typename Point , typename Vector = typename Kernel_traits<Point>::Kernel::Vector_3>
 Index_back_inserter CGAL::Point_set_3< Point, Vector >::index_back_inserter ( )

Returns the back inserter on the index property.

## ◆ insert() [1/3]

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.

## ◆ insert() [2/3]

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.

## ◆ insert() [3/3]

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.

## ◆ is_empty()

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.

## ◆ is_removed()

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.

## ◆ join()

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.

## ◆ normal() [1/2]

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

## ◆ normal() [2/2]

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

## ◆ normal_map() [1/2]

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

## ◆ normal_map() [2/2]

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

## ◆ normal_push_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 ( )

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

## ◆ number_of_points()

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.

## ◆ parameters()

template<typename Point , typename Vector = typename Kernel_traits<Point>::Kernel::Vector_3>
 unspecified_type CGAL::Point_set_3< Point, Vector >::parameters ( ) const

Returns a sequence of Named Parameters for Point Set Processing algorithms.

Named Parameters
 point_map contains the point map (see point_map()) normal_map contains the normal map (see normal_map()) geom_traits contains the kernel typename Kernel_traits::Kernel
Warning
this method does not check if the normal map was instanciated or not. The normal map named parameter should not be used if this property was not instanciated first.

## ◆ point_back_inserter()

template<typename Point , typename Vector = typename Kernel_traits<Point>::Kernel::Vector_3>
 Point_back_inserter CGAL::Point_set_3< Point, Vector >::point_back_inserter ( )

Returns the back inserter on the point property.

## ◆ point_push_map()

template<typename Point , typename Vector = typename Kernel_traits<Point>::Kernel::Vector_3>
 Point_push_map CGAL::Point_set_3< Point, Vector >::point_push_map ( )

Returns the push property map of the point property.

## ◆ property_map()

template<typename Point , typename Vector = typename Kernel_traits<Point>::Kernel::Vector_3>
template<class T >
 std::pair,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.

## ◆ push_property_map()

template<typename Point , typename Vector = typename Kernel_traits<Point>::Kernel::Vector_3>
template<class T >
 Push_property_map > CGAL::Point_set_3< Point, Vector >::push_property_map ( Property_map< T > & prop )

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

## ◆ remove() [1/3]

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.

## ◆ remove() [2/3]

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.

## ◆ remove() [3/3]

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.

## ◆ remove_normal_map()

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.

## ◆ remove_property_map()

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.

## ◆ reserve()

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.

## ◆ resize()

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.

## ◆ operator+=()

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

Append other at the end of ps.

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.