CGAL 5.6 - Point Set Processing

Read and write points (with or without additional properties) in PLY format.

Classes

struct  CGAL::IO::PLY_property< T >
 Class used to identify a PLY property as a type and a name. More...
 

Functions

template<typename PointMap >
std::tuple< PointMap, typename Kernel_traits< typename PointMap::value_type >::Kernel::Construct_point_3, PLY_property< FT >, PLY_property< FT >, PLY_property< FT > > CGAL::IO::make_ply_point_reader (PointMap point_map)
 Generates a PLY property handler to read 3D points. More...
 
template<typename VectorMap >
std::tuple< VectorMap, typename Kernel_traits< typename VectorMap::value_type >::Kernel::Construct_vector_3, PLY_property< FT >, PLY_property< FT >, PLY_property< FT > > CGAL::IO::make_ply_normal_reader (VectorMap normal_map)
 Generates a PLY property handler to read 3D normal vectors. More...
 
template<typename OutputIteratorValueType , typename PointOutputIterator , typename ... PropertyHandler>
bool CGAL::IO::read_PLY_with_properties (std::istream &is, PointOutputIterator output, PropertyHandler &&... properties)
 reads user-selected points properties from a .ply stream (ASCII or binary). More...
 
template<typename OutputIteratorValueType , typename PointOutputIterator , typename NamedParameters = CGAL::parameters::Default_named_parameters>
bool CGAL::IO::read_PLY (std::istream &is, PointOutputIterator output, const NamedParameters &np=parameters::default_values())
 reads points (positions + normals, if available), using the Polygon File Format (PLY). More...
 
template<typename OutputIteratorValueType , typename PointOutputIterator , typename NamedParameters = CGAL::parameters::Default_named_parameters>
bool CGAL::IO::read_PLY (const std::string &fname, PointOutputIterator output, const NamedParameters &np=parameters::default_values())
 reads points (positions + normals, if available), using the Polygon File Format (PLY). More...
 
template<typename PointMap >
std::tuple< PointMap, PLY_property< FT >, PLY_property< FT >, PLY_property< FT > > CGAL::IO::make_ply_point_writer (PointMap point_map)
 Generates a PLY property handler to write 3D points. More...
 
template<typename VectorMap >
std::tuple< VectorMap, PLY_property< FT >, PLY_property< FT >, PLY_property< FT > > CGAL::IO::make_ply_normal_writer (VectorMap normal_map)
 Generates a PLY property handler to write 3D normal vectors. More...
 
template<typename PointRange , typename ... PropertyHandler>
bool CGAL::IO::write_PLY_with_properties (std::ostream &os, const PointRange &points, PropertyHandler &&... properties)
 writes the range of points with properties using Polygon File Format (PLY). More...
 
template<typename PointRange , typename NamedParameters = CGAL::parameters::Default_named_parameters>
bool CGAL::IO::write_PLY (std::ostream &os, const PointRange &points, const NamedParameters &np=parameters::default_values())
 writes the range of points (positions + normals, if available) using Polygon File Format (PLY). More...
 
template<typename PointRange , typename NamedParameters = CGAL::parameters::Default_named_parameters>
bool CGAL::IO::write_PLY (const std::string &filename, const PointRange &points, const NamedParameters &np=parameters::default_values())
 writes the range of points (positions + normals, if available) using Polygon File Format (PLY). More...
 

Function Documentation

◆ make_ply_normal_reader()

template<typename VectorMap >
std::tuple<VectorMap, typename Kernel_traits<typename VectorMap::value_type>::Kernel::Construct_vector_3, PLY_property<FT>, PLY_property<FT>, PLY_property<FT> > CGAL::IO::make_ply_normal_reader ( VectorMap  normal_map)

#include <CGAL/IO/read_ply_points.h>

Generates a PLY property handler to read 3D normal vectors.

Vectors are constructed from the input using 3 PLY properties of type FT and named nx, ny and nz. FT is float if the points use CGAL::Simple_cartesian<float> and double otherwise.

Template Parameters
VectorMapthe property map used to store vectors.
See also
read_PLY_with_properties()
Polygon File Format (PLY)
Examples:
Point_set_processing_3/read_ply_points_with_colors_example.cpp.

◆ make_ply_normal_writer()

template<typename VectorMap >
std::tuple<VectorMap, PLY_property<FT>, PLY_property<FT>, PLY_property<FT> > CGAL::IO::make_ply_normal_writer ( VectorMap  normal_map)

#include <CGAL/IO/write_ply_points.h>

Generates a PLY property handler to write 3D normal vectors.

Vectors are written as 3 PLY properties of type FT and named nx, ny and nz. FT is float if the vectors use CGAL::Simple_cartesian<float> and double otherwise.

Template Parameters
VectorMapthe property map used to store vectors.
See also
write_PLY_with_properties()
Polygon File Format (PLY)

◆ make_ply_point_reader()

template<typename PointMap >
std::tuple<PointMap, typename Kernel_traits<typename PointMap::value_type>::Kernel::Construct_point_3, PLY_property<FT>, PLY_property<FT>, PLY_property<FT> > CGAL::IO::make_ply_point_reader ( PointMap  point_map)

#include <CGAL/IO/read_ply_points.h>

Generates a PLY property handler to read 3D points.

Points are constructed from the input using 3 PLY properties of type FT and named x, y and z. FT is float if the points use CGAL::Simple_cartesian<float> and double otherwise.

Template Parameters
PointMapthe property map used to store points.
See also
read_PLY_with_properties()
Polygon File Format (PLY)
Examples:
Point_set_processing_3/read_ply_points_with_colors_example.cpp.

◆ make_ply_point_writer()

template<typename PointMap >
std::tuple<PointMap, PLY_property<FT>, PLY_property<FT>, PLY_property<FT> > CGAL::IO::make_ply_point_writer ( PointMap  point_map)

#include <CGAL/IO/write_ply_points.h>

Generates a PLY property handler to write 3D points.

Points are written as 3 PLY properties of type FT and named x, y and z. FT is float if the points use CGAL::Simple_cartesian<float> and double otherwise.

Template Parameters
PointMapthe property map used to store points.
See also
write_PLY_with_properties()
Polygon File Format (PLY)
Examples:
Point_set_processing_3/write_ply_points_example.cpp.

◆ read_PLY() [1/2]

template<typename OutputIteratorValueType , typename PointOutputIterator , typename NamedParameters = CGAL::parameters::Default_named_parameters>
bool CGAL::IO::read_PLY ( std::istream &  is,
PointOutputIterator  output,
const NamedParameters &  np = parameters::default_values() 
)

#include <CGAL/IO/read_ply_points.h>

reads points (positions + normals, if available), using the Polygon File Format (PLY).

Potential additional point properties and faces are ignored.

Attention
To read a binary file, the flag std::ios::binary must be set during the creation of the ifstream.
Template Parameters
OutputIteratorValueTypetype of objects that can be put in PointOutputIterator. It must be a model of DefaultConstructible and defaults to value_type_traits<PointOutputIterator>::type. It can be omitted when the default is fine.
PointOutputIteratoriterator over output points.
NamedParametersa sequence of Named Parameters
Parameters
isinput stream.
outputoutput iterator over points.
npan optional sequence of Named Parameters among the ones listed below
Optional Named Parameters

  • a property map associating normals to the elements of the point range
  • Type: a model of WritablePropertyMap with value type geom_traits::Vector_3
  • Default: If this parameter is omitted, normals in the input stream are ignored.

Returns
true if reading was successful, false otherwise.
See also
read_PLY_with_properties()

◆ read_PLY() [2/2]

template<typename OutputIteratorValueType , typename PointOutputIterator , typename NamedParameters = CGAL::parameters::Default_named_parameters>
bool CGAL::IO::read_PLY ( const std::string &  fname,
PointOutputIterator  output,
const NamedParameters &  np = parameters::default_values() 
)

#include <CGAL/IO/read_ply_points.h>

reads points (positions + normals, if available), using the Polygon File Format (PLY).

Potential additional point properties and faces are ignored.

Template Parameters
OutputIteratorValueTypetype of objects that can be put in PointOutputIterator. It must be a model of DefaultConstructible and defaults to value_type_traits<PointOutputIterator>::type. It can be omitted when the default is fine.
PointOutputIteratoriterator over output points.
NamedParametersa sequence of Named Parameters
Parameters
fnameinput file name.
outputoutput iterator over points.
npoptional sequence of Named Parameters among the ones listed below.
Optional Named Parameters
  • indicates whether data should be read in binary (true) or in ASCII (false)
  • Type: Boolean
  • Default: true

  • a property map associating normals to the elements of the point range
  • Type: a model of WritablePropertyMap with value type geom_traits::Vector_3
  • Default: If this parameter is omitted, normals in the input stream are ignored.

Returns
true if reading was successful, false otherwise.
See also
Polygon File Format (PLY)
read_PLY_with_properties()

◆ read_PLY_with_properties()

template<typename OutputIteratorValueType , typename PointOutputIterator , typename ... PropertyHandler>
bool CGAL::IO::read_PLY_with_properties ( std::istream &  is,
PointOutputIterator  output,
PropertyHandler &&...  properties 
)

#include <CGAL/IO/read_ply_points.h>

reads user-selected points properties from a .ply stream (ASCII or binary).

Potential additional point properties and faces are ignored.

Properties are handled through a variadic list of property handlers. A PropertyHandler can either be:

  • A std::pair<PropertyMap, PLY_property<T> > if the user wants to read a PLY property as a scalar value T (for example, storing an int PLY property into an int variable).
  • A std::tuple<PropertyMap, Constructor, PLY_property<T>...> if the user wants to use one or several PLY properties to construct a complex object (for example, storing 3 uchar PLY properties into a Color object that can for example be a std::array<unsigned char, 3>). In that case, the second element of the tuple should be a functor that constructs the value type of PropertyMap from N objects of types T.
Attention
To read a binary file, the flag std::ios::binary must be set during the creation of the ifstream.
Template Parameters
OutputIteratorValueTypetype of objects that can be put in PointOutputIterator. It must be a model of DefaultConstructible and defaults to value_type_traits<PointOutputIterator>::type. It can be omitted when the default is fine.
PointOutputIteratoriterator over output points.
PropertyHandlerhandlers to recover properties.
Returns
true if reading was successful, false otherwise.
See also
Polygon File Format (PLY)
make_ply_point_reader()
make_ply_normal_reader()
Examples:
Point_set_processing_3/read_ply_points_with_colors_example.cpp.

◆ write_PLY() [1/2]

template<typename PointRange , typename NamedParameters = CGAL::parameters::Default_named_parameters>
bool CGAL::IO::write_PLY ( std::ostream &  os,
const PointRange &  points,
const NamedParameters &  np = parameters::default_values() 
)

#include <CGAL/IO/write_ply_points.h>

writes the range of points (positions + normals, if available) using Polygon File Format (PLY).

Attention
To write to a binary file, the flag std::ios::binary must be set during the creation of the ofstream, and the IO::Mode of the stream must be set to BINARY.
Template Parameters
PointRangeis a model of ConstRange. The value type of its iterator is the key type of the named parameter point_map.
NamedParametersa sequence of Named Parameters
Parameters
osoutput stream
pointsinput point range
npan optional sequence of Named Parameters among the ones listed below
Optional Named Parameters

  • a property map associating normals to the elements of the point range
  • Type: a model of ReadablePropertyMap with value type geom_traits::Vector_3
  • Default: If this parameter is omitted, normals are not written in the output stream.

  • a parameter used to set the precision (i.e. how many digits are generated) of the output stream
  • Type: int
  • Default: the precision of the stream os
  • Extra: This parameter is only meaningful while using ASCII encoding.
Returns
true if writing was successful, false otherwise.
See also
write_PLY_with_properties()
Examples:
Point_set_processing_3/orient_scanlines_example.cpp.

◆ write_PLY() [2/2]

template<typename PointRange , typename NamedParameters = CGAL::parameters::Default_named_parameters>
bool CGAL::IO::write_PLY ( const std::string &  filename,
const PointRange &  points,
const NamedParameters &  np = parameters::default_values() 
)

#include <CGAL/IO/write_ply_points.h>

writes the range of points (positions + normals, if available) using Polygon File Format (PLY).

Template Parameters
PointRangeis a model of ConstRange. The value type of its iterator is the key type of the named parameter point_map.
NamedParametersa sequence of Named Parameters
Parameters
filenamethe path to the output file
pointsinput point range
npan optional sequence of Named Parameters among the ones listed below
Optional Named Parameters
  • indicates whether data should be written in binary (true) or in ASCII (false)
  • Type: Boolean
  • Default: true

  • a property map associating normals to the elements of the point range
  • Type: a model of ReadablePropertyMap with value type geom_traits::Vector_3
  • Default: If this parameter is omitted, normals are not written in the output file.

  • a parameter used to set the precision (i.e. how many digits are generated) of the output stream
  • Type: int
  • Default: 6
  • Extra: This parameter is only meaningful while using ASCII encoding.
Returns
true if writing was successful, false otherwise.
See also
write_PLY_with_properties()

◆ write_PLY_with_properties()

template<typename PointRange , typename ... PropertyHandler>
bool CGAL::IO::write_PLY_with_properties ( std::ostream &  os,
const PointRange &  points,
PropertyHandler &&...  properties 
)

#include <CGAL/IO/write_ply_points.h>

writes the range of points with properties using Polygon File Format (PLY).

Properties are handled through a variadic list of property handlers. A PropertyHandler can either be:

  • A std::pair<PropertyMap, PLY_property<T> > if the user wants to write a scalar value T as a PLY property (for example, writing an int variable as an int PLY property).
  • A std::tuple<PropertyMap, PLY_property<T>...> if the user wants to write a complex object as several PLY properties. In that case, a specialization of Output_rep must be provided for PropertyMap::value_type that handles both ASCII and binary output (see CGAL::IO::get_mode()).
Attention
To write to a binary file, the flag std::ios::binary must be set during the creation of the ofstream, and the IO::Mode of the stream must be set to BINARY.
Template Parameters
PointRangeis a model of ConstRange. The value type of its iterator is the key type of the PropertyMap objects provided within the PropertyHandler parameter.
PropertyHandlerhandlers to recover properties.
Returns
true if writing was successful, false otherwise.
See also
Polygon File Format (PLY)
make_ply_point_writer()
make_ply_normal_writer()
Parameters
osoutput stream.
pointsinput point range.
propertiesparameter pack of property handlers
Examples:
Point_set_processing_3/write_ply_points_example.cpp.