From 6d6d959d4da0c87fbe6f98ba127547760fad27bb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mael=20Rouxel-Labb=C3=A9?= Date: Fri, 17 Jul 2020 13:37:37 +0200 Subject: [PATCH] Enhance doc for generic I/O functions --- .../CGAL/boost/graph/IO/polygon_mesh_io.h | 4 +++ Point_set_3/include/CGAL/Point_set_3/IO.h | 33 +++++++++-------- .../include/CGAL/IO/read_points.h | 13 ++++--- .../include/CGAL/IO/write_points.h | 17 +++++---- .../IO/polygon_mesh_io.h | 35 +++++++------------ .../include/CGAL/IO/polygon_soup_io.h | 4 +++ 6 files changed, 57 insertions(+), 49 deletions(-) diff --git a/BGL/include/CGAL/boost/graph/IO/polygon_mesh_io.h b/BGL/include/CGAL/boost/graph/IO/polygon_mesh_io.h index c1295956d37..7ae18668fa9 100644 --- a/BGL/include/CGAL/boost/graph/IO/polygon_mesh_io.h +++ b/BGL/include/CGAL/boost/graph/IO/polygon_mesh_io.h @@ -88,6 +88,8 @@ bool read_polygon_mesh(std::istream& is, * - \ref IOStreamGocad (`.ts`) * - \ref IOStreamVTK (`.vtp`) * + * The format is detected from the filename extension. + * * \tparam Graph a model of `MutableFaceGraph` * \tparam NamedParameters a sequence of \ref bgl_namedparameters "Named Parameters" * @@ -206,6 +208,8 @@ bool read_polygon_mesh(const char* fname, Graph& g) * - \ref IOStreamGocad (`.ts`) * - \ref IOStreamVTK (`.vtp`) * + * The format is detected from the filename extension. + * * \tparam Graph a model of `FaceListGraph` and `HalfedgeListGraph` * \tparam NamedParameters a sequence of \ref bgl_namedparameters "Named Parameters" * diff --git a/Point_set_3/include/CGAL/Point_set_3/IO.h b/Point_set_3/include/CGAL/Point_set_3/IO.h index 6a072c706c8..1d1e9feee66 100644 --- a/Point_set_3/include/CGAL/Point_set_3/IO.h +++ b/Point_set_3/include/CGAL/Point_set_3/IO.h @@ -36,12 +36,13 @@ class Point_set_3; /*! \ingroup PkgPointSet3IO - \brief reads the point set from an input stream that can be either: + \brief reads the point set from an input stream. - - \link IOStreamXYZ XYZ \endlink - - \link IOStreamOFF OFF \endlink - - \link IOStreamPLY PLY \endlink - - \link IOStreamLAS LAS \endlink + Supported file formats are the following: + - \ref IOStreamOFF (`.off`) + - \ref IOStreamPLY (`.ply`) + - \ref IOStreamLAS (`.las`) + - \ref IOStreamXYZ (`.xyz`) The format is detected from the stream. If the stream contains normal vectors, the normal map is added to the point set. For PLY @@ -84,12 +85,13 @@ std::istream& operator>>(std::istream& is, /*! \ingroup PkgPointSet3IO - \brief reads the point set from an input file that can be either: + \brief reads the point set from an input file. - - \link IOStreamXYZ XYZ \endlink - - \link IOStreamOFF OFF \endlink - - \link IOStreamPLY PLY \endlink - - \link IOStreamLAS LAS \endlink + Supported file formats are the following: + - \ref IOStreamOFF (`.off`) + - \ref IOStreamPLY (`.ply`) + - \ref IOStreamLAS (`.las`) + - \ref IOStreamXYZ (`.xyz`) The format is detected from the filename extension. If the file contains normal vectors, the normal map is added to the point set. For PLY @@ -165,12 +167,13 @@ std::ostream& operator<<(std::ostream& os, /*! \ingroup PkgPointSet3IO - \brief inserts the point set in an output file that can be either: + \brief inserts the point set in an output file. - - \link IOStreamXYZ XYZ \endlink - - \link IOStreamOFF OFF \endlink - - \link IOStreamPLY PLY \endlink - - \link IOStreamLAS LAS \endlink + Supported file formats are the following: + - \ref IOStreamOFF (`.off`) + - \ref IOStreamPLY (`.ply`) + - \ref IOStreamLAS (`.las`) + - \ref IOStreamXYZ (`.xyz`) The format is detected from the filename extension. diff --git a/Point_set_processing_3/include/CGAL/IO/read_points.h b/Point_set_processing_3/include/CGAL/IO/read_points.h index c5d73862b7d..f988b943f2b 100644 --- a/Point_set_processing_3/include/CGAL/IO/read_points.h +++ b/Point_set_processing_3/include/CGAL/IO/read_points.h @@ -31,12 +31,15 @@ namespace CGAL { /** \ingroup PkgPointSetProcessing3IO - Reads the point set from an input file that can be either: + \brief reads the point set from an input file. - - \link IOStreamXYZ XYZ \endlink - - \link IOStreamOFF OFF \endlink - - \link IOStreamPLY PLY \endlink - - \link IOStreamLAS LAS \endlink + Supported file formats are the following: + - \ref IOStreamOFF (`.off`) + - \ref IOStreamPLY (`.ply`) + - \ref IOStreamLAS (`.las`) + - \ref IOStreamXYZ (`.xyz`) + + The format is detected from the filename extension. \tparam OutputIteratorValueType type of objects that can be put in `PointOutputIterator`. It is default to `value_type_traits::%type` and can be omitted when the default is fine. diff --git a/Point_set_processing_3/include/CGAL/IO/write_points.h b/Point_set_processing_3/include/CGAL/IO/write_points.h index 71e1d5552aa..10d508db0d0 100644 --- a/Point_set_processing_3/include/CGAL/IO/write_points.h +++ b/Point_set_processing_3/include/CGAL/IO/write_points.h @@ -36,18 +36,21 @@ namespace CGAL { /** \ingroup PkgPointSetProcessing3IO - Saves the range of `points` with properties to a file that can be either: + \brief saves the range of `points` with properties to a file. - - \link IOStreamXYZ XYZ \endlink - - \link IOStreamOFF OFF \endlink - - \link IOStreamPLY PLY \endlink - - \link IOStreamLAS LAS \endlink + Supported file formats are the following: + - \ref IOStreamOFF (`.off`) + - \ref IOStreamPLY (`.ply`) + - \ref IOStreamLAS (`.las`) + - \ref IOStreamXYZ (`.xyz`) + + The format is detected from the filename extension. \tparam PointRange is a model of `ConstRange`. The value type of its iterator is the key type of the named parameter `point_map`. \tparam NamedParameters a sequence of \ref bgl_namedparameters "Named Parameters" - \param fname the name of the input file. + \param fname the name of the output file. \param points the range of points that will be written. \param np optional sequence of \ref bgl_namedparameters "Named Parameters" among the ones listed below. @@ -61,7 +64,7 @@ namespace CGAL { \cgalParamNBegin{normal_map} \cgalParamDescription{a property map associating normals to the elements of the poing range} \cgalParamType{a model of `ReadablePropertyMap` with value type `geom_traits::Vector_3`} - \cgalParamDefault{If this parameter is omitted, normals in the input stream are ignored.} + \cgalParamDefault{If this parameter is omitted, normals are not written in the output stream.} \cgalParamNEnd \cgalParamNBegin{geom_traits} diff --git a/Polygon_mesh_processing/include/CGAL/Polygon_mesh_processing/IO/polygon_mesh_io.h b/Polygon_mesh_processing/include/CGAL/Polygon_mesh_processing/IO/polygon_mesh_io.h index 6c7666637d5..464310dbbe7 100644 --- a/Polygon_mesh_processing/include/CGAL/Polygon_mesh_processing/IO/polygon_mesh_io.h +++ b/Polygon_mesh_processing/include/CGAL/Polygon_mesh_processing/IO/polygon_mesh_io.h @@ -40,6 +40,16 @@ namespace Polygon_mesh_processing { * \brief Attempts to read a file as a polygon mesh; in case of failure, reads the file as a polygon soup, * repairs and orients it to obtain a polygon mesh. * + * Supported file formats are the following: + * - \ref IOStreamOFF (`.off`) + * - \ref IOStreamOBJ (`.obj`) + * - \ref IOStreamSTL (`.stl`) + * - \ref IOStreamPLY (`.ply`) + * - \ref IOStreamGocad (`.ts`) + * - \ref IOStreamVTK (`.vtp`) + * + * The format is detected from the filename extension. + * * \tparam PolygonMesh a model of `MutableFaceGraph` * \tparam NamedParameters a sequence of \ref bgl_namedparameters "Named Parameters" * @@ -58,15 +68,6 @@ namespace Polygon_mesh_processing { * must be available in `PolygonMesh`.} * \cgalParamNEnd * - * \cgalParamNBegin{geom_traits} - * \cgalParamDescription{an instance of a geometric traits class} - * \cgalParamType{The traits class must provide the nested functors `Less_xyz_3` and `Equal_3` - * to respectivelycompare lexicographically two points and to check if two points - * are identical. For each functor `Foo`, a function `Foo foo_object()` must be provided.} - * \cgalParamDefault{a \cgal Kernel deduced from the point type, using `CGAL::Kernel_traits`} - * \cgalParamExtra{The geometric traits class must be compatible with the vertex point type.} - * \cgalParamNEnd - * * \cgalParamNBegin{repair_polygon_soup} * \cgalParamDescription{a parameter used indicate whether `CGAL::Polygon_mesh_processing::repair_polygon_soup()` * should be called on the soup in case of issues in the input.} @@ -74,20 +75,10 @@ namespace Polygon_mesh_processing { * \cgalParamDefault{`true`} * \cgalParamNEnd * - * \cgalParamNBegin{erase_all_duplicates} - * \cgalParamDescription{Parameter to indicate, when multiple polygons are duplicates, - * whether all the duplicate polygons should be removed - * or if one (arbitrarily chosen) face should be kept.} + * \cgalParamNBegin{verbose} + * \cgalParamDescription{whether extra information is printed when an incident occurs during reading} * \cgalParamType{Boolean} - * \cgalParamDefault{`false`} - * \cgalParamNEnd - * - * \cgalParamNBegin{require_same_orientation} - * \cgalParamDescription{Parameter to indicate if polygon orientation should be taken - * into account when determining whether two polygons are duplicates, - * that is, whether e.g. the triangles `0,1,2` and `0,2,1` are duplicates.} - * \cgalParamType{Boolean} - * \cgalParamDefault{`false`} + * \cgalParamDefault{`true`} * \cgalParamNEnd * \cgalNamedParamsEnd * diff --git a/Stream_support/include/CGAL/IO/polygon_soup_io.h b/Stream_support/include/CGAL/IO/polygon_soup_io.h index 50ff8295f24..54219c07c0d 100644 --- a/Stream_support/include/CGAL/IO/polygon_soup_io.h +++ b/Stream_support/include/CGAL/IO/polygon_soup_io.h @@ -46,6 +46,8 @@ namespace CGAL { * - \ref IOStreamGocad (`.ts`) * - \ref IOStreamVTK (`.vtp`) * + * The format is detected from the filename extension. + * * \tparam PolygonRange a model of the concept `RandomAccessContainer` * whose value_type is a model of the concept `RandomAccessContainer` * whose value_type is `std::size_t`. @@ -134,6 +136,8 @@ bool read_polygon_soup(const std::string& fname, * - \ref IOStreamGocad (`.ts`) * - \ref IOStreamVTK (`.vtp`) * + * The format is detected from the filename extension. + * * \tparam PolygonRange a model of the concept `RandomAccessContainer` * whose value_type is a model of the concept `RandomAccessContainer` * whose value_type is `std::size_t`.