PLY I/O Functions

I/O Functions for the Polygon File Format (PLY).

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

Functions
template<class PointRange , class PolygonRange , typename NamedParameters = CGAL::parameters::Default_named_parameters>
bool	CGAL::IO::read_PLY (std::istream &is, PointRange &points, PolygonRange &polygons, std::string &comments, const NamedParameters &np=parameters::default_values())
	reads the content of is into points and polygons, using the Polygon File Format (PLY).
template<typename PointRange , typename PolygonRange , typename NamedParameters = CGAL::parameters::Default_named_parameters>
bool	CGAL::IO::read_PLY (const std::string &fname, PointRange &points, PolygonRange &polygons, std::string &comments, const NamedParameters &np=parameters::default_values())
	reads the content of fname into points and polygons, using the Polygon File Format (PLY).
template<class PointRange , class PolygonRange , typename NamedParameters = CGAL::parameters::Default_named_parameters>
bool	CGAL::IO::write_PLY (std::ostream &out, const PointRange &points, const PolygonRange &polygons, const NamedParameters &np=parameters::default_values())
	writes the content of points and polygons in out, using the Polygon File Format (PLY).
template<class PointRange , class PolygonRange , typename NamedParameters = CGAL::parameters::Default_named_parameters>
bool	CGAL::IO::write_PLY (const std::string &fname, const PointRange &points, const PolygonRange &polygons, const NamedParameters &np=parameters::default_values())
	writes the content of points and polygons in the file fname, using the Polygon File Format (PLY).
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.
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.
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).
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).
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).
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.
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.
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).
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).
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).

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/PLY.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

VectorMap

the property map used to store vectors.

See also

read_PLY_with_properties()

Polygon File Format (PLY)

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/PLY.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

VectorMap

the 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/PLY.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

PointMap

the property map used to store points.

See also

read_PLY_with_properties()

Polygon File Format (PLY)

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/PLY.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

PointMap

the property map used to store points.

See also

write_PLY_with_properties()

Polygon File Format (PLY)

read_PLY() [1/4]

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/PLY.h>

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

Potential additional point properties and faces are ignored.

Template Parameters

OutputIteratorValueType	type 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.
PointOutputIterator	iterator over output points.
NamedParameters	a sequence of Named Parameters

Parameters

fname	input file name.
output	output iterator over points.
np	optional sequence of Named Parameters among the ones listed below.

Optional Named Parameters

use_binary_mode indicates whether data should be read in binary (true) or in ASCII (false) Type: Boolean Default: true
point_map a property map associating points to the elements of the point range Type: a model of WritablePropertyMap with value type geom_traits::Point_3 Default: CGAL::Identity_property_map<geom_traits::Point_3>
normal_map 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.
geom_traits an instance of a geometric traits class Type: a model of Kernel Default: a CGAL Kernel deduced from the point type, using CGAL::Kernel_traits

Returns

true if reading was successful, false otherwise.

See also

Polygon File Format (PLY)

read_PLY_with_properties()

read_PLY() [2/4]

template<typename PointRange , typename PolygonRange , typename NamedParameters = CGAL::parameters::Default_named_parameters>

bool CGAL::IO::read_PLY	(	const std::string &	fname,
		PointRange &	points,
		PolygonRange &	polygons,
		std::string &	comments,
		const NamedParameters &	np = parameters::default_values()
	)

#include <CGAL/IO/PLY.h>

reads the content of fname into points and polygons, using the Polygon File Format (PLY).

Attention

The polygon soup is not cleared, and the data from the file are appended.

Template Parameters

PointRange	a model of the concept RandomAccessContainer whose value type is the point type.
PolygonRange	a model of the concepts SequenceContainer and BackInsertionSequence whose value_type is itself a model of the concept SequenceContainer and BackInsertionSequence whose value_type is an integer type
NamedParameters	a sequence of Named Parameters

Parameters

fname	the path to the input file
points	points of the soup of polygons
polygons	a range of polygons. Each element in it describes a polygon using the indices of the points in points
comments	a string that will contain all the comments found in the PLY file
np	optional Named Parameters described below

Optional Named Parameters

use_binary_mode indicates whether data should be read in binary (true) or in ASCII (false) Type: Boolean Default: true
verbose indicates whether output warnings and error messages should be printed or not. Type: Boolean Default: false

Returns

true if the reading was successful, false otherwise.

read_PLY() [3/4]

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/PLY.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

OutputIteratorValueType	type 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.
PointOutputIterator	iterator over output points.
NamedParameters	a sequence of Named Parameters

Parameters

is	input stream.
output	output iterator over points.
np	an optional sequence of Named Parameters among the ones listed below

Optional Named Parameters

point_map a property map associating points to the elements of the point range Type: a model of WritablePropertyMap with value type geom_traits::Point_3 Default: CGAL::Identity_property_map<geom_traits::Point_3>
normal_map 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.
geom_traits an instance of a geometric traits class Type: a model of Kernel Default: a CGAL Kernel deduced from the point type, using CGAL::Kernel_traits

Returns

true if reading was successful, false otherwise.

See also

read_PLY_with_properties()

read_PLY() [4/4]

template<class PointRange , class PolygonRange , typename NamedParameters = CGAL::parameters::Default_named_parameters>

bool CGAL::IO::read_PLY	(	std::istream &	is,
		PointRange &	points,
		PolygonRange &	polygons,
		std::string &	comments,
		const NamedParameters &	np = parameters::default_values()
	)

#include <CGAL/IO/PLY.h>

reads the content of is into points and polygons, using the Polygon File Format (PLY).

Attention

The polygon soup is not cleared, and the data from the stream are appended.

To read a binary file, the flag std::ios::binary must be set during the creation of the ifstream.

Template Parameters

PointRange	a model of the concepts RandomAccessContainer and BackInsertionSequence whose value type is the point type
PolygonRange	a model of the concepts SequenceContainer and BackInsertionSequence whose value_type is itself a model of the concept SequenceContainer and BackInsertionSequence whose value_type is an unsigned integer type convertible to std::size_t
NamedParameters	a sequence of Named Parameters

Parameters

is	the input stream
points	points of the soup of polygons
polygons	a range of polygons. Each element in it describes a polygon using the indices of the points in points
comments	a string that will contain all the comments found in the PLY file
np	optional Named Parameters described below

Optional Named Parameters

use_binary_mode indicates whether data should be read in binary (true) or in ASCII (false) Type: Boolean Default: true
verbose indicates whether output warnings and error messages should be printed or not. Type: Boolean Default: false

Returns

true if the reading was successful, false otherwise.

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/PLY.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

OutputIteratorValueType	type 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.
PointOutputIterator	iterator over output points.
PropertyHandler	handlers 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()

write_PLY() [1/4]

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/PLY.h>

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

Template Parameters

PointRange	is a model of ConstRange. The value type of its iterator is the key type of the named parameter point_map.
NamedParameters	a sequence of Named Parameters

Parameters

filename	the path to the output file
points	input point range
np	an optional sequence of Named Parameters among the ones listed below

Optional Named Parameters

use_binary_mode indicates whether data should be written in binary (true) or in ASCII (false) Type: Boolean Default: true
point_map a property map associating points to the elements of the point range Type: a model of ReadablePropertyMap with value type geom_traits::Point_3 Default: CGAL::Identity_property_map<geom_traits::Point_3>
normal_map 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.
geom_traits an instance of a geometric traits class Type: a model of Kernel Default: a CGAL Kernel deduced from the point type, using CGAL::Kernel_traits
stream_precision 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() [2/4]

template<class PointRange , class PolygonRange , typename NamedParameters = CGAL::parameters::Default_named_parameters>

bool CGAL::IO::write_PLY	(	const std::string &	fname,
		const PointRange &	points,
		const PolygonRange &	polygons,
		const NamedParameters &	np = parameters::default_values()
	)

#include <CGAL/IO/PLY.h>

writes the content of points and polygons in the file fname, using the Polygon File Format (PLY).

Template Parameters

PointRange	a model of the concept RandomAccessContainer whose value type is the point type
PolygonRange	a model of the concept SequenceContainer whose value_type is itself a model of the concept SequenceContainer whose value_type is an unsigned integer type convertible to std::size_t
NamedParameters	a sequence of Named Parameters

Parameters

fname	the path to the output file
points	points of the soup of polygons
polygons	a range of polygons. Each element in it describes a polygon using the indices of the points in points.
np	optional Named Parameters described below

Optional Named Parameters

use_binary_mode indicates whether data should be written in binary (true) or in ASCII (false) Type: Boolean Default: true
stream_precision 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 the writing was successful, false otherwise.

write_PLY() [3/4]

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/PLY.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

PointRange	is a model of ConstRange. The value type of its iterator is the key type of the named parameter point_map.
NamedParameters	a sequence of Named Parameters

Parameters

os	output stream
points	input point range
np	an optional sequence of Named Parameters among the ones listed below

Optional Named Parameters

point_map a property map associating points to the elements of the point range Type: a model of ReadablePropertyMap with value type geom_traits::Point_3 Default: CGAL::Identity_property_map<geom_traits::Point_3>
normal_map 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.
geom_traits an instance of a geometric traits class Type: a model of Kernel Default: a CGAL Kernel deduced from the point type, using CGAL::Kernel_traits
stream_precision 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()

write_PLY() [4/4]

template<class PointRange , class PolygonRange , typename NamedParameters = CGAL::parameters::Default_named_parameters>

bool CGAL::IO::write_PLY	(	std::ostream &	out,
		const PointRange &	points,
		const PolygonRange &	polygons,
		const NamedParameters &	np = parameters::default_values()
	)

#include <CGAL/IO/PLY.h>

writes the content of points and polygons in out, using the 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

PointRange	a model of the concept RandomAccessContainer whose value type is the point type
PolygonRange	a model of the concept SequenceContainer whose value_type is itself a model of the concept SequenceContainer whose value_type is an unsigned integer type convertible to std::size_t
NamedParameters	a sequence of Named Parameters

Parameters

out	the output stream
points	points of the soup of polygons
polygons	a range of polygons. Each element in it describes a polygon using the indices of the points in points.
np	optional Named Parameters described below

Optional Named Parameters

stream_precision 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 the writing was successful, false otherwise.

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/PLY.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

PointRange	is a model of ConstRange. The value type of its iterator is the key type of the PropertyMap objects provided within the PropertyHandler parameter.
PropertyHandler	handlers 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() parameter pack of property handlers

Parameters

os	output stream.
points	input point range.
properties	parameter pack of property handlers