CGAL 6.1.2 - Point Set Processing: I/O (PLY Format)

CGAL 6.1.2 - Point Set Processing

Loading...
Searching...
No Matches
Classes | Functions
I/O (PLY Format)
Reference Manual

##

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

  VectorMap | the 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

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

  PointMap | the 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

  PointMap | the 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 | ( | 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

  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

  indicates whether data should be read in binary (`true`) or in ASCII (`false`) Type: Boolean Default: `true` |
  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>` |
  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. |
  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/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

  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

  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>` |
  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. |
  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_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

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

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

  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

  indicates whether data should be written in binary (`true`) or in ASCII (`false`) Type: Boolean Default: `true` |
  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>` |
  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. |
  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` |
  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/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

  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

  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>` |
  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. |
  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` |
  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_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

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

Parameters

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

Examples
  Point_set_processing_3/write_ply_points_example.cpp.