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

#include <CGAL/Point_set_3.h>

Definition

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 accessed 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() method. This property must be explicitly created.

All properties can be accessed as a range using the methods points(), normals(), and range() for point 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 automatically create the right named parameters if called with a CGAL::Point_set_3 object as argument.

Template Parameters
PointPoint type
VectorNormal vector type
Is Model Of:
Range

Public Types

typedef Point Point_3
 The point type.
 
typedef Vector Vector_3
 The vector type.
 
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 >
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...
 
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. 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...
 

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 method to add a point with a normal vector. More...
 
iterator insert (const Point_set_3 &other, const Index &idx)
 Convenience method to copy a point with all its properties from another point set. 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 Methods

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...
 
bool is_removed (const Index &index) 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. More...
 
std::size_t garbage_size () const
 Number of removed points. More...
 
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.
 
void cancel_removals ()
 restores all removed points. More...
 

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...
 
std::pair< Vector_map, bool > add_normal_map (const Vector &default_value=CGAL::NULL_VECTOR)
 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).
 
void copy_properties (const Point_set_3 &other)
 Copies the properties from another point set. More...
 
std::vector< std::string > properties () const
 returns a vector with all strings that describe properties.
 
std::vector< std::pair< std::string, std::type_index > > properties_and_types () const
 returns a vector of pairs that describe properties and associated types.
 
unspecified_type parameters () const
 returns a sequence of Named Parameters to be used in 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)

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
 This is an advanced type. More...
 
template<class Property >
using Push_property_map = unspecified_type
 This is an advanced type. More...
 
typedef Property_back_inserter< Index_map > Index_back_inserter
 This is an advanced type. More...
 
typedef Property_back_inserter< Point_mapPoint_back_inserter
 This is an advanced type. More...
 
typedef Push_property_map< Point_mapPoint_push_map
 This is an advanced type. More...
 
typedef Push_property_map< Vector_mapVector_push_map
 This is an advanced type. More...
 
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...
 

Member Typedef Documentation

◆ const_iterator

template<typename Point , typename Vector >
typedef unspecified_type Point_set_3< Point, Vector >::const_iterator

Constant iterator type of the point set with value type Index

Is Model Of:
RandomAccessIterator

◆ Index_back_inserter

template<typename Point , typename Vector >
typedef Property_back_inserter<Index_map> Point_set_3< Point, Vector >::Index_back_inserter

This is an advanced type.

Advanced

Back inserter on indices

◆ iterator

template<typename Point , typename Vector >
typedef unspecified_type Point_set_3< Point, Vector >::iterator

Iterator type of the point set with value type Index

Is Model Of:
RandomAccessIterator

◆ Point_back_inserter

template<typename Point , typename Vector >
typedef Property_back_inserter<Point_map> Point_set_3< Point, Vector >::Point_back_inserter

This is an advanced type.

Advanced

Back inserter on points

◆ Point_push_map

template<typename Point , typename Vector >
typedef Push_property_map<Point_map> Point_set_3< Point, Vector >::Point_push_map

This is an advanced type.

Advanced

Property map for pushing new points

◆ Property_back_inserter

template<typename Point , typename Vector >
template<class Property >
using Point_set_3< Point, Vector >::Property_back_inserter = unspecified_type

This is an advanced type.

Advanced

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

◆ Property_map

template<typename Point , typename Vector >
template<class Type >
using 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 >
template<class Type >
using 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 >
template<class Property >
using Point_set_3< Point, Vector >::Push_property_map = unspecified_type

This is an advanced type.

Advanced

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

◆ Vector_push_map

template<typename Point , typename Vector >
typedef Push_property_map<Vector_map> Point_set_3< Point, Vector >::Vector_push_map

This is an advanced type.

Advanced

Property map for pushing new vectors

Constructor & Destructor Documentation

◆ Point_set_3()

template<typename Point , typename Vector >
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_maptrue 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

◆ add_normal_map()

template<typename Point , typename Vector >
std::pair<Vector_map, bool> Point_set_3< Point, Vector >::add_normal_map ( const Vector &  default_value = CGAL::NULL_VECTOR)

Convenience method that adds a normal property.

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

Returns
Returns a pair containing the normal 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).

◆ add_property_map()

template<typename Point , typename Vector >
template<class T >
std::pair<Property_map<T>, bool> 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
Ttype of the property.
Parameters
nameName of the property.
tValue 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).

◆ cancel_removals()

template<typename Point , typename Vector >
void Point_set_3< Point, Vector >::cancel_removals ( )

restores all removed points.

After removing one or several points, calling this method restores the point set to its initial state: points that were removed (and their associated properties) are restored.

Note
This method is only guaranteed to work if no point was inserted after the removal: otherwise, some points might not be restored.
If collect_garbage() was called after removal, the points are irremediably lost and nothing will be restored.

◆ clear()

template<typename Point , typename Vector >
void Point_set_3< Point, Vector >::clear ( )

Clears the point set properties and content.

After calling this method, 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 >
void Point_set_3< Point, Vector >::clear_properties ( )

Clears all properties created.

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

◆ copy_properties()

template<typename Point , typename Vector >
void Point_set_3< Point, Vector >::copy_properties ( const Point_set_3< Point, Vector > &  other)

Copies the properties from another point set.

All properties from other that do not already exist in this point set are added and filled to their default values. Properties that exist in both point sets are left unchanged.

◆ end() [1/2]

template<typename Point , typename Vector >
iterator 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 >
const_iterator Point_set_3< Point, Vector >::end ( ) const

returns the past-the-end constant iterator.

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

◆ garbage_size()

template<typename Point , typename Vector >
std::size_t Point_set_3< Point, Vector >::garbage_size ( ) const

Number of removed points.

See also
number_of_removed_points()

◆ has_normal_map()

template<typename Point , typename Vector >
bool 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 >
template<typename T >
bool Point_set_3< Point, Vector >::has_property_map ( const std::string &  name) const

tests whether property name of type T already exists.

Template Parameters
Ttype of the property.
Parameters
nameName of the property.

◆ index_back_inserter()

template<typename Point , typename Vector >
Index_back_inserter Point_set_3< Point, Vector >::index_back_inserter ( )

This is an advanced function.

Advanced

returns the back inserter on the index property.

◆ insert() [1/4]

template<typename Point , typename Vector >
iterator 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/4]

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

inserts new point with default property values.

Parameters
pPoint 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/4]

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

Convenience method to add a point with a normal vector.

Parameters
pPoint to insert
nAssociated normal vector
Note
Properties of the added point other than its normal vector are initialized to their default value.
If not already added, a normal property is automatically added to the point set when using this method. The default value for normal vectors is CGAL::NULL_VECTOR.
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() [4/4]

template<typename Point , typename Vector >
iterator Point_set_3< Point, Vector >::insert ( const Point_set_3< Point, Vector > &  other,
const Index idx 
)

Convenience method to copy a point with all its properties from another point set.

In the case where two point sets have the same properties, this method allows the user to easily copy one point (along with the values of all its properties) from one point set to another.

Parameters
otherPoint set to which the point to copy belongs
idxIndex of the point to copy in other
Warning
This point set and other must have the exact same properties, with the exact same names and types in the exact same order.
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.
Returns
The iterator on the newly added element.

◆ is_empty()

template<typename Point , typename Vector >
bool 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() [1/2]

template<typename Point , typename Vector >
bool 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.

◆ is_removed() [2/2]

template<typename Point , typename Vector >
bool Point_set_3< Point, Vector >::is_removed ( const Index index) 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 >
bool 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
If copy_properties() with other as argument is called before calling this method, then all the content of other will be copied and no property will be lost in the process.
Garbage is collected in both point sets when calling this method.

◆ normal() [1/2]

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

returns a reference to the normal corresponding to index.

Note
If not already added, a normal property is automatically added to the point set (see add_normal_map()).

◆ normal() [2/2]

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

returns a constant reference to the normal corresponding to index.

Note
If not already added, a normal property is automatically added to the point set (see add_normal_map()).

◆ normal_map() [1/2]

template<typename Point , typename Vector >
Vector_map Point_set_3< Point, Vector >::normal_map ( )

returns the property map of the normal property.

Note
If the normal property has not been added yet to the point set before calling this method, the property map is automatically added with add_normal_map().

◆ normal_map() [2/2]

template<typename Point , typename Vector >
const Vector_map 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 >
Vector_push_map Point_set_3< Point, Vector >::normal_push_map ( )

This is an advanced function.

Advanced

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

◆ number_of_removed_points()

template<typename Point , typename Vector >
std::size_t Point_set_3< Point, Vector >::number_of_removed_points ( ) const

Number of removed points.

See also
garbage_size()

◆ parameters()

template<typename Point , typename Vector >
unspecified_type Point_set_3< Point, Vector >::parameters ( ) const

returns a sequence of Named Parameters to be used in Point Set Processing algorithms.

The following named parameters are used:

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

◆ point_back_inserter()

template<typename Point , typename Vector >
Point_back_inserter Point_set_3< Point, Vector >::point_back_inserter ( )

This is an advanced function.

Advanced

returns the back inserter on the point property.

◆ point_push_map()

template<typename Point , typename Vector >
Point_push_map Point_set_3< Point, Vector >::point_push_map ( )

This is an advanced function.

Advanced

returns the push property map of the point property.

◆ property_map()

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

returns the property name of type T.

Template Parameters
Ttype of the property.
Parameters
nameName 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).

◆ push_property_map()

template<typename Point , typename Vector >
template<class T >
Push_property_map<Property_map<T> > Point_set_3< Point, Vector >::push_property_map ( Property_map< T > &  prop)

This is an advanced function.

Advanced

returns the push property map of the given property.

Template Parameters
Ttype of the property.
Parameters
propThe 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 >
void 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. Elements can be recovered with cancel_removals().
All iterators, pointers and references related to the container are invalidated.

◆ remove() [2/3]

template<typename Point , typename Vector >
void 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. The element can be recovered with cancel_removals().
The end() iterator is invalidated, it dereferences to a different element.

◆ remove() [3/3]

template<typename Point , typename Vector >
void 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. The element can be recovered with cancel_removals().
The end() iterator is invalidated, it dereferences to a different element.

◆ remove_normal_map()

template<typename Point , typename Vector >
bool 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 >
template<class T >
bool Point_set_3< Point, Vector >::remove_property_map ( Property_map< T > &  prop)

removes the specified property.

Template Parameters
Ttype of the property.
Parameters
propThe property.
Returns
Returns true if the property was removed and false if the property was not found.

◆ reserve()

template<typename Point , typename Vector >
void 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
sExpected 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 >
void Point_set_3< Point, Vector >::resize ( std::size_t  s)

changes size of the point set.

Parameters
sTarget 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

◆ 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 method.