From 0d66e19361abd18c187e3b56db167a1cb66c1381 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mael=20Rouxel-Labb=C3=A9?= Date: Fri, 24 Jul 2020 17:05:10 +0200 Subject: [PATCH] IO documentation fixes See @sloriot's review: https://cgal.geometryfactory.com/CGAL/Members/wiki/Features/Polgyon_soup_mesh_IO/2nd_round/Answer_to_review (+ some commits before and after this one) --- .../Arr_extended_rational_arc_traits_d_1.h | 2 +- .../Arr_geodesic_arc_on_sphere_traits_2.h | 2 +- .../CGAL/Arr_geometry_traits/Bezier_point_2.h | 2 +- .../include/CGAL/Arr_linear_traits_2.h | 2 +- .../Trapezoidal_decomposition_2_impl.h | 2 +- .../include/CGAL/Arr_polycurve_traits_2.h | 2 +- .../include/CGAL/Arr_tracing_traits_2.h | 2 +- .../Arrangement_2/Arrangement_zone_2_impl.h | 2 +- .../include/CGAL/Arrangement_on_surface_2.h | 2 +- .../Arrangement_on_surface_with_history_2.h | 2 +- .../CGAL/Curved_kernel_via_analysis_2/Arc_2.h | 4 +- .../gfx/Subdivision_1.h | 2 +- .../Arrangement_on_surface_2/test_overlay.cpp | 2 +- BGL/include/CGAL/boost/graph/IO/GOCAD.h | 12 ++-- BGL/include/CGAL/boost/graph/IO/OBJ.h | 12 ++-- BGL/include/CGAL/boost/graph/IO/OFF.h | 28 ++++---- BGL/include/CGAL/boost/graph/IO/PLY.h | 30 ++++---- BGL/include/CGAL/boost/graph/IO/STL.h | 14 ++-- BGL/include/CGAL/boost/graph/IO/VTK.h | 5 +- .../CGAL/boost/graph/IO/polygon_mesh_io.h | 6 +- BGL/include/CGAL/boost/graph/properties.h | 2 +- .../doc/CGAL_ipelets/PackageDescription.txt | 2 +- .../benchmark/parser/benchmark_parser.h | 2 +- .../CGAL/Cone_spanners_2/Plane_scan_tree.h | 2 +- Convex_hull_d/include/CGAL/Convex_hull_d.h | 4 +- .../Envelope_3/Envelope_element_visitor_3.h | 2 +- .../include/CGAL/HalfedgeDS_decorator.h | 2 +- Installation/CHANGES.md | 2 +- ...mall_side_angle_bisector_decomposition_2.h | 2 +- .../CGAL/Sqrt_extension/Sqrt_extension_type.h | 2 +- Point_set_3/doc/Point_set_3/Point_set_3.txt | 2 +- Point_set_3/include/CGAL/Point_set_3.h | 4 +- Point_set_3/include/CGAL/Point_set_3/IO.h | 69 ++++++++++++++----- Point_set_3/include/CGAL/Point_set_3/IO/LAS.h | 16 ++--- Point_set_3/include/CGAL/Point_set_3/IO/OFF.h | 14 ++-- Point_set_3/include/CGAL/Point_set_3/IO/PLY.h | 15 ++-- Point_set_3/include/CGAL/Point_set_3/IO/XYZ.h | 16 ++--- .../Point_set_processing_3.txt | 4 +- .../include/CGAL/IO/read_las_points.h | 6 +- .../include/CGAL/IO/read_off_points.h | 24 +++---- .../include/CGAL/IO/read_ply_points.h | 18 ++--- .../include/CGAL/IO/read_points.h | 18 +++-- .../include/CGAL/IO/read_xyz_points.h | 26 +++---- .../include/CGAL/IO/write_las_points.h | 8 +-- .../include/CGAL/IO/write_off_points.h | 24 ++----- .../include/CGAL/IO/write_ply_points.h | 18 ++--- .../include/CGAL/IO/write_points.h | 14 +++- .../include/CGAL/IO/write_xyz_points.h | 19 ++--- .../IO/polygon_mesh_io.h | 6 +- .../CGAL/Polygon_mesh_processing/distance.h | 4 +- .../orient_polygon_soup.h | 4 +- .../polygon_soup_to_polygon_mesh.h | 4 +- .../repair_polygon_soup.h | 32 ++++----- .../Polyhedron/CGAL/IO/Polyhedron_iostream.h | 21 +++--- .../doc/Polyhedron/PackageDescription.txt | 2 +- Polyhedron/doc/Polyhedron/Polyhedron.txt | 9 +-- .../doc/STL_Extension/STL_Extension.txt | 2 +- .../include/CGAL/Handle_with_policy.h | 2 +- .../File_formats/Supported_file_formats.txt | 55 +++++++-------- .../doc/Stream_support/IOstream.txt | 2 +- Stream_support/include/CGAL/IO/3MF.h | 4 +- Stream_support/include/CGAL/IO/GOCAD.h | 16 ++--- Stream_support/include/CGAL/IO/OBJ.h | 16 ++--- Stream_support/include/CGAL/IO/OFF.h | 16 ++--- Stream_support/include/CGAL/IO/PLY.h | 16 ++--- Stream_support/include/CGAL/IO/STL.h | 35 +++++----- Stream_support/include/CGAL/IO/VTK.h | 12 ++-- .../include/CGAL/IO/polygon_soup_io.h | 8 +-- .../doc/Surface_mesh/Surface_mesh.txt | 6 +- .../include/CGAL/Surface_mesh/IO/OFF.h | 58 ++++++++-------- .../CGAL/Variational_shape_approximation.h | 2 +- .../include/CGAL/internal/auxiliary/graph.h | 2 +- .../internal/Path_on_surface_with_rle.h | 2 +- Three/include/CGAL/Three/Scene_item.h | 2 +- 74 files changed, 392 insertions(+), 418 deletions(-) diff --git a/Arrangement_on_surface_2/archive/include/CGAL/Arr_extended_rational_arc_traits_d_1.h b/Arrangement_on_surface_2/archive/include/CGAL/Arr_extended_rational_arc_traits_d_1.h index a4c447248b1..0a710185dfe 100644 --- a/Arrangement_on_surface_2/archive/include/CGAL/Arr_extended_rational_arc_traits_d_1.h +++ b/Arrangement_on_surface_2/archive/include/CGAL/Arr_extended_rational_arc_traits_d_1.h @@ -10,7 +10,7 @@ // Author(s) : Oren Salzman // Michael Hemmer -//TODO: somehow use the fact the the x-value is the same in all comparisons +//TODO: somehow use the fact the x-value is the same in all comparisons #ifndef CGAL_ARR_VERTICAL_SEGMENT_TRAITS #define CGAL_ARR_VERTICAL_SEGMENT_TRAITS diff --git a/Arrangement_on_surface_2/include/CGAL/Arr_geodesic_arc_on_sphere_traits_2.h b/Arrangement_on_surface_2/include/CGAL/Arr_geodesic_arc_on_sphere_traits_2.h index 6ccd5d249bc..3855dee3c67 100644 --- a/Arrangement_on_surface_2/include/CGAL/Arr_geodesic_arc_on_sphere_traits_2.h +++ b/Arrangement_on_surface_2/include/CGAL/Arr_geodesic_arc_on_sphere_traits_2.h @@ -1068,7 +1068,7 @@ public: * LARGER - x(xcv1, ce) > x(xcv2, ce). * \pre the ce end of the arc xcv1 lies on a pole. * \pre the ce end of the arc xcv2 lies on a pole. - * \pre the the $x$-coordinates of xcv1 and xcv2 at their ce end are + * \pre the $x$-coordinates of xcv1 and xcv2 at their ce end are * equal (implying that the curves overlap). * \pre xcv1 does not coincide with the vertical identification curve. * \pre xcv2 does not coincide with the vertical identification curve. diff --git a/Arrangement_on_surface_2/include/CGAL/Arr_geometry_traits/Bezier_point_2.h b/Arrangement_on_surface_2/include/CGAL/Arr_geometry_traits/Bezier_point_2.h index 62312301940..e0e46cace0b 100644 --- a/Arrangement_on_surface_2/include/CGAL/Arr_geometry_traits/Bezier_point_2.h +++ b/Arrangement_on_surface_2/include/CGAL/Arr_geometry_traits/Bezier_point_2.h @@ -751,7 +751,7 @@ public: } /*! - * Compare the the two points xy-lexicographically. + * Compare the two points xy-lexicographically. * \param pt The other point. * \param cache A cache for the vertical tangency points and the * intersection points. diff --git a/Arrangement_on_surface_2/include/CGAL/Arr_linear_traits_2.h b/Arrangement_on_surface_2/include/CGAL/Arr_linear_traits_2.h index 0e1262db0ec..3fe62601378 100644 --- a/Arrangement_on_surface_2/include/CGAL/Arr_linear_traits_2.h +++ b/Arrangement_on_surface_2/include/CGAL/Arr_linear_traits_2.h @@ -1139,7 +1139,7 @@ public: * that xcv1 is vertical. * \pre the ce end of the line xcv2 lies on a boundary, implying * that xcv2 is vertical. - * \pre the the $x$-coordinates of xcv1 and xcv2 at their ce ends are + * \pre the $x$-coordinates of xcv1 and xcv2 at their ce ends are * equal, implying that the curves overlap! */ Comparison_result diff --git a/Arrangement_on_surface_2/include/CGAL/Arr_point_location/Trapezoidal_decomposition_2_impl.h b/Arrangement_on_surface_2/include/CGAL/Arr_point_location/Trapezoidal_decomposition_2_impl.h index bb309ed663b..d86c0c869f9 100644 --- a/Arrangement_on_surface_2/include/CGAL/Arr_point_location/Trapezoidal_decomposition_2_impl.h +++ b/Arrangement_on_surface_2/include/CGAL/Arr_point_location/Trapezoidal_decomposition_2_impl.h @@ -1488,7 +1488,7 @@ Trapezoidal_decomposition_2::insert(Halfedge_const_handle he) // if the edge starts at a vertex, we should not insert it into the DAG. // Instead, we should update all the edges incident to the vertex. // Otherwise, this is a new vertex, insert a node to the DAG that represents - // the new vertex. In this case, the the edge itself is the only incident + // the new vertex. In this case, the edge itself is the only incident // edge, and so it is a trivial operation. Td_map_item p1_item = (lt1 == POINT) ? update_vtx_with_new_edge(he, ce1, item1, lt1) : diff --git a/Arrangement_on_surface_2/include/CGAL/Arr_polycurve_traits_2.h b/Arrangement_on_surface_2/include/CGAL/Arr_polycurve_traits_2.h index 6d61db9e61e..5d430ebcafc 100644 --- a/Arrangement_on_surface_2/include/CGAL/Arr_polycurve_traits_2.h +++ b/Arrangement_on_surface_2/include/CGAL/Arr_polycurve_traits_2.h @@ -779,7 +779,7 @@ public: } } - // Check if the the left endpoint lies on the other polycurve. + // Check if the left endpoint lies on the other polycurve. bool left_coincides = (left_res == EQUAL); bool left_overlap = false; diff --git a/Arrangement_on_surface_2/include/CGAL/Arr_tracing_traits_2.h b/Arrangement_on_surface_2/include/CGAL/Arr_tracing_traits_2.h index 5847dd43e02..9738f6cf7f4 100644 --- a/Arrangement_on_surface_2/include/CGAL/Arr_tracing_traits_2.h +++ b/Arrangement_on_surface_2/include/CGAL/Arr_tracing_traits_2.h @@ -660,7 +660,7 @@ public: /*! Operate * \param xcv1 the first curve * \param xcv2 the second curve - * \return true if the the two curve are mergeable and false otherwise. + * \return true if the two curve are mergeable and false otherwise. * Two curves are mergeable if they have the same underlying theoretical * curve */ diff --git a/Arrangement_on_surface_2/include/CGAL/Arrangement_2/Arrangement_zone_2_impl.h b/Arrangement_on_surface_2/include/CGAL/Arrangement_2/Arrangement_zone_2_impl.h index b3d8c63f5b2..1a88af753c2 100644 --- a/Arrangement_on_surface_2/include/CGAL/Arrangement_2/Arrangement_zone_2_impl.h +++ b/Arrangement_on_surface_2/include/CGAL/Arrangement_2/Arrangement_zone_2_impl.h @@ -1514,7 +1514,7 @@ bool Arrangement_zone_2::_zone_in_overlap() // In this case m_overlap_cv has a finite right endpoint. In this case, // if the right vertex of m_intersect_he is associated with a finite point, // we check whether it is equal to cv_right_pt. Otherwise, we know that - // m_intersect_he extends to the the right of m_overlap_cv, and there is no + // m_intersect_he extends to the right of m_overlap_cv, and there is no // vertex currently associated with m_overlap_cv's right endpoint. if (! he_right_v->is_at_open_boundary() && equal(cv_right_pt, he_right_v->point())) diff --git a/Arrangement_on_surface_2/include/CGAL/Arrangement_on_surface_2.h b/Arrangement_on_surface_2/include/CGAL/Arrangement_on_surface_2.h index c119e3b8c51..be31e9dea99 100644 --- a/Arrangement_on_surface_2/include/CGAL/Arrangement_on_surface_2.h +++ b/Arrangement_on_surface_2/include/CGAL/Arrangement_on_surface_2.h @@ -1471,7 +1471,7 @@ public: * \pre cv1's source and cv2's target equal the endpoints of the curve * currently assoicated with e (respectively), and cv1's target equals * cv2's target, and this is the split point (ot vice versa). - * \return A handle for the halfedge whose source is the source of the the + * \return A handle for the halfedge whose source is the source of the * original halfedge e, and whose target is the split point. */ Halfedge_handle split_edge(Halfedge_handle e, diff --git a/Arrangement_on_surface_2/include/CGAL/Arrangement_on_surface_with_history_2.h b/Arrangement_on_surface_2/include/CGAL/Arrangement_on_surface_with_history_2.h index 5525703839b..808546e0bdd 100644 --- a/Arrangement_on_surface_2/include/CGAL/Arrangement_on_surface_with_history_2.h +++ b/Arrangement_on_surface_2/include/CGAL/Arrangement_on_surface_with_history_2.h @@ -557,7 +557,7 @@ public: * \param e The edge to split (one of the pair of twin halfedges). * \param p The split point. * \pre p lies in the interior of the curve associated with e. - * \return A handle for the halfedge whose source is the source of the the + * \return A handle for the halfedge whose source is the source of the * original halfedge e, and whose target is the split point. */ Halfedge_handle split_edge (Halfedge_handle e, const Point_2& p); diff --git a/Arrangement_on_surface_2/include/CGAL/Curved_kernel_via_analysis_2/Arc_2.h b/Arrangement_on_surface_2/include/CGAL/Curved_kernel_via_analysis_2/Arc_2.h index 0e963f93c88..c8c67b36d5e 100644 --- a/Arrangement_on_surface_2/include/CGAL/Curved_kernel_via_analysis_2/Arc_2.h +++ b/Arrangement_on_surface_2/include/CGAL/Curved_kernel_via_analysis_2/Arc_2.h @@ -2695,9 +2695,9 @@ protected: * if arcs' x-ranges overlap; otherwise returns \c false * * \param cv2 The second arc - * \param pt_low Output: Point indicating the lower bound of the the joint + * \param pt_low Output: Point indicating the lower bound of the joint * x-range - * \param pt_high Output: Point indicating the upper bound of the the joint + * \param pt_high Output: Point indicating the upper bound of the joint * x-range * \return \c true, if arcs overlap, \c false otherwise * diff --git a/Arrangement_on_surface_2/include/CGAL/Curved_kernel_via_analysis_2/gfx/Subdivision_1.h b/Arrangement_on_surface_2/include/CGAL/Curved_kernel_via_analysis_2/gfx/Subdivision_1.h index 322f57d0846..395b44a9f11 100644 --- a/Arrangement_on_surface_2/include/CGAL/Curved_kernel_via_analysis_2/gfx/Subdivision_1.h +++ b/Arrangement_on_surface_2/include/CGAL/Curved_kernel_via_analysis_2/gfx/Subdivision_1.h @@ -264,7 +264,7 @@ private: //!@} }; // class Subdivision_1<> -//! \brief main rasterization procedure, copies in the the output iterator +//! \brief main rasterization procedure, copies in the output iterator //! \c oi a set of pixel coordinates template diff --git a/Arrangement_on_surface_2/test/Arrangement_on_surface_2/test_overlay.cpp b/Arrangement_on_surface_2/test/Arrangement_on_surface_2/test_overlay.cpp index ca54f1d25c5..f648439034a 100644 --- a/Arrangement_on_surface_2/test/Arrangement_on_surface_2/test_overlay.cpp +++ b/Arrangement_on_surface_2/test/Arrangement_on_surface_2/test_overlay.cpp @@ -11,7 +11,7 @@ * by the elements in the two pairs above, respectively. * 5. Initialize the data field of each halfedge with the number of curves * that induced that halfedge if the halfedge is directed left-to-right - * and twice the the number of curves that induced that halfedge if the + * and twice the number of curves that induced that halfedge if the * halfedge is directed right-to-left. We initialize the data field of * each face with the total sum of the data of the halfedges on the * boundary of the face. We initialize the data field of each isolated diff --git a/BGL/include/CGAL/boost/graph/IO/GOCAD.h b/BGL/include/CGAL/boost/graph/IO/GOCAD.h index d972a77135d..c781ff1d300 100644 --- a/BGL/include/CGAL/boost/graph/IO/GOCAD.h +++ b/BGL/include/CGAL/boost/graph/IO/GOCAD.h @@ -82,6 +82,8 @@ public: /// /// \brief reads the graph `g` from the input stream, using the \ref IOStreamGocad. /// +/// The data is expected to represent a 2-manifold (possibly with borders). +/// /// \attention The graph `g` is not cleared, and the data from the stream is added. /// /// \tparam Graph a model of `MutableFaceGraph` @@ -95,7 +97,7 @@ public: /// \cgalNamedParamsBegin /// \cgalParamNBegin{vertex_point_map} /// \cgalParamDescription{a property map associating points to the vertices of `g`} -/// \cgalParamType{a class model of `ReadWritePropertyMap` with `boost::graph_traits::%vertex_descriptor` +/// \cgalParamType{a class model of `WritablePropertyMap` with `boost::graph_traits::%vertex_descriptor` /// as key type and `%Point_3` as value type} /// \cgalParamDefault{`boost::get(CGAL::vertex_point, g)`} /// \cgalParamExtra{If this parameter is omitted, an internal property map for `CGAL::vertex_point_t` @@ -109,8 +111,6 @@ public: /// \cgalParamNEnd /// \cgalNamedParamsEnd /// -/// \pre The data must represent a 2-manifold -/// /// \returns `true` if reading was successful and the resulting mesh is valid, `false` otherwise. /// template ::%vertex_descriptor` +/// \cgalParamType{a class model of `WritablePropertyMap` with `boost::graph_traits::%vertex_descriptor` /// as key type and `%Point_3` as value type} /// \cgalParamDefault{`boost::get(CGAL::vertex_point, g)`} /// \cgalParamExtra{If this parameter is omitted, an internal property map for `CGAL::vertex_point_t` @@ -198,8 +200,6 @@ bool read_GOCAD(std::istream& is, Graph& g, /// /// \returns `true` if reading was successful and the resulting mesh is valid, `false` otherwise. /// -/// \pre The data must represent a 2-manifold -/// template bool read_GOCAD(const char* fname, diff --git a/BGL/include/CGAL/boost/graph/IO/OBJ.h b/BGL/include/CGAL/boost/graph/IO/OBJ.h index 8bdf6dd3cb3..115555c0c45 100644 --- a/BGL/include/CGAL/boost/graph/IO/OBJ.h +++ b/BGL/include/CGAL/boost/graph/IO/OBJ.h @@ -75,6 +75,8 @@ public: \brief reads the graph `g` from the stream `in`, using the \ref IOStreamOBJ. + The data is expected to represent a 2-manifold (possibly with borders). + Ignores comment lines which start with a hash, and lines with whitespace. \attention The graph `g` is not cleared, and the data from the stream is added. @@ -89,7 +91,7 @@ public: \cgalNamedParamsBegin \cgalParamNBegin{vertex_point_map} \cgalParamDescription{a property map associating points to the vertices of `g`} - \cgalParamType{a class model of `ReadWritePropertyMap` with `boost::graph_traits::%vertex_descriptor` + \cgalParamType{a class model of `WritablePropertyMap` with `boost::graph_traits::%vertex_descriptor` as key type and `%Point_3` as value type} \cgalParamDefault{`boost::get(CGAL::vertex_point, g)`} \cgalParamExtra{If this parameter is omitted, an internal property map for `CGAL::vertex_point_t` @@ -103,8 +105,6 @@ public: \cgalParamNEnd \cgalNamedParamsEnd - \pre The data must represent a 2-manifold - \returns `true` if reading was successful and the resulting mesh is valid, `false` otherwise. \sa Overloads of this function for specific models of the concept `FaceGraph`. @@ -142,6 +142,8 @@ bool read_OBJ(std::istream& is, Graph& g, \brief reads the graph `g` from the file `fname`, using the \ref IOStreamOBJ. + The data is expected to represent a 2-manifold (possibly with borders). + Ignores comment lines which start with a hash, and lines with whitespace. \attention The graph `g` is not cleared, and the data from the stream is added. @@ -156,7 +158,7 @@ bool read_OBJ(std::istream& is, Graph& g, \cgalNamedParamsBegin \cgalParamNBegin{vertex_point_map} \cgalParamDescription{a property map associating points to the vertices of `g`} - \cgalParamType{a class model of `ReadWritePropertyMap` with `boost::graph_traits::%vertex_descriptor` + \cgalParamType{a class model of `WritablePropertyMap` with `boost::graph_traits::%vertex_descriptor` as key type and `%Point_3` as value type} \cgalParamDefault{`boost::get(CGAL::vertex_point, g)`} \cgalParamExtra{If this parameter is omitted, an internal property map for `CGAL::vertex_point_t` @@ -170,8 +172,6 @@ bool read_OBJ(std::istream& is, Graph& g, \cgalParamNEnd \cgalNamedParamsEnd - \pre The data must represent a 2-manifold - \returns `true` if reading was successful and the resulting mesh is valid, `false` otherwise. \sa Overloads of this function for specific models of the concept `FaceGraph`. diff --git a/BGL/include/CGAL/boost/graph/IO/OFF.h b/BGL/include/CGAL/boost/graph/IO/OFF.h index fb7f224c20a..9a24e2b443f 100644 --- a/BGL/include/CGAL/boost/graph/IO/OFF.h +++ b/BGL/include/CGAL/boost/graph/IO/OFF.h @@ -90,6 +90,8 @@ bool read_OFF_BGL(std::istream& is, \brief reads the graph `g` from data in the input stream, using the \ref IOStreamOFF. + The data is expected to represent a 2-manifold (possibly with borders). + This function reads the point property as well as vertex normals (NOFF), vertex and face colors (COFF), and texture vertex coordinates (TOFF). Those properties are stored in property maps that are passed through named parameters (see below), when passed. @@ -108,7 +110,7 @@ bool read_OFF_BGL(std::istream& is, \cgalNamedParamsBegin \cgalParamNBegin{vertex_point_map} \cgalParamDescription{a property map associating points to the vertices of `g`} - \cgalParamType{a class model of `ReadWritePropertyMap` with `boost::graph_traits::%vertex_descriptor` + \cgalParamType{a class model of `WritablePropertyMap` with `boost::graph_traits::%vertex_descriptor` as key type and `%Point_3` as value type} \cgalParamDefault{`boost::get(CGAL::vertex_point, g)`} \cgalParamExtra{If this parameter is omitted, an internal property map for `CGAL::vertex_point_t` @@ -117,28 +119,28 @@ bool read_OFF_BGL(std::istream& is, \cgalParamNBegin{vertex_normal_map} \cgalParamDescription{a property map associating normals to the vertices of `g`} - \cgalParamType{a class model of `ReadWritePropertyMap` with `boost::graph_traits::%vertex_descriptor` + \cgalParamType{a class model of `WritablePropertyMap` with `boost::graph_traits::%vertex_descriptor` as key type and `%Vector_3` as value type} \cgalParamDefault{vertex normals that may exist in the input will be ignored} \cgalParamNEnd \cgalParamNBegin{vertex_color_map} \cgalParamDescription{a property map associating colors to the vertices of `g`} - \cgalParamType{a class model of `ReadWritePropertyMap` with `boost::graph_traits::%vertex_descriptor` + \cgalParamType{a class model of `WritablePropertyMap` with `boost::graph_traits::%vertex_descriptor` as key type and `CGAL::Color` as value type} \cgalParamDefault{vertex colors that may exist in the input will be ignored} \cgalParamNEnd \cgalParamNBegin{vertex_texture_map} \cgalParamDescription{a property map associating textures to the vertices of `g`} - \cgalParamType{a class model of `ReadWritePropertyMap` with `boost::graph_traits::%vertex_descriptor` + \cgalParamType{a class model of `WritablePropertyMap` with `boost::graph_traits::%vertex_descriptor` as key type and `%Point_2` as value type} \cgalParamDefault{vertex textures that may exist in the input will be ignored} \cgalParamNEnd \cgalParamNBegin{face_color_map} \cgalParamDescription{a property map associating colors to the faces of `g`} - \cgalParamType{a class model of `ReadWritePropertyMap` with `boost::graph_traits::%face_descriptor` + \cgalParamType{a class model of `WritablePropertyMap` with `boost::graph_traits::%face_descriptor` as key type and `CGAL::Color` as value type} \cgalParamDefault{face colors that may exist in the input will be ignored} \cgalParamNEnd @@ -150,8 +152,6 @@ bool read_OFF_BGL(std::istream& is, \cgalParamNEnd \cgalNamedParamsEnd - \pre The data must represent a 2-manifold - \returns `true` if reading was successful and the resulting mesh is valid, `false` otherwise. \sa Overloads of this function for specific models of the concept `FaceGraph`. @@ -185,6 +185,8 @@ bool read_OFF(std::istream& is, Graph& g, \brief reads the graph `g` from the file `fname`, using the \ref IOStreamOFF. + The data is expected to represent a 2-manifold (possibly with borders). + This function reads the point property as well as vertex normals (NOFF), vertex and face colors (COFF), and texture vertex coordinates (TOFF). Those properties are stored in property maps that are passed through named parameters (see below), when passed. @@ -203,7 +205,7 @@ bool read_OFF(std::istream& is, Graph& g, \cgalNamedParamsBegin \cgalParamNBegin{vertex_point_map} \cgalParamDescription{a property map associating points to the vertices of `g`} - \cgalParamType{a class model of `ReadWritePropertyMap` with `boost::graph_traits::%vertex_descriptor` + \cgalParamType{a class model of `WritablePropertyMap` with `boost::graph_traits::%vertex_descriptor` as key type and `%Point_3` as value type} \cgalParamDefault{`boost::get(CGAL::vertex_point, g)`} \cgalParamExtra{If this parameter is omitted, an internal property map for `CGAL::vertex_point_t` @@ -212,28 +214,28 @@ bool read_OFF(std::istream& is, Graph& g, \cgalParamNBegin{vertex_normal_map} \cgalParamDescription{a property map associating normals to the vertices of `g`} - \cgalParamType{a class model of `ReadWritePropertyMap` with `boost::graph_traits::%vertex_descriptor` + \cgalParamType{a class model of `WritablePropertyMap` with `boost::graph_traits::%vertex_descriptor` as key type and `%Vector_3` as value type} \cgalParamDefault{vertex normals that may exist in the input will be ignored} \cgalParamNEnd \cgalParamNBegin{vertex_color_map} \cgalParamDescription{a property map associating colors to the vertices of `g`} - \cgalParamType{a class model of `ReadWritePropertyMap` with `boost::graph_traits::%vertex_descriptor` + \cgalParamType{a class model of `WritablePropertyMap` with `boost::graph_traits::%vertex_descriptor` as key type and `CGAL::Color` as value type} \cgalParamDefault{vertex colors that may exist in the input will be ignored} \cgalParamNEnd \cgalParamNBegin{vertex_texture_map} \cgalParamDescription{a property map associating textures to the vertices of `g`} - \cgalParamType{a class model of `ReadWritePropertyMap` with `boost::graph_traits::%vertex_descriptor` + \cgalParamType{a class model of `WritablePropertyMap` with `boost::graph_traits::%vertex_descriptor` as key type and `%Point_2` as value type} \cgalParamDefault{vertex textures that may exist in the input will be ignored} \cgalParamNEnd \cgalParamNBegin{face_color_map} \cgalParamDescription{a property map associating colors to the faces of `g`} - \cgalParamType{a class model of `ReadWritePropertyMap` with `boost::graph_traits::%face_descriptor` + \cgalParamType{a class model of `WritablePropertyMap` with `boost::graph_traits::%face_descriptor` as key type and `CGAL::Color` as value type} \cgalParamDefault{face colors that may exist in the input will be ignored} \cgalParamNEnd @@ -245,8 +247,6 @@ bool read_OFF(std::istream& is, Graph& g, \cgalParamNEnd \cgalNamedParamsEnd - \pre The data must represent a 2-manifold - \returns `true` if reading was successful and the resulting mesh is valid, `false` otherwise. \sa Overloads of this function for specific models of the concept `FaceGraph`. diff --git a/BGL/include/CGAL/boost/graph/IO/PLY.h b/BGL/include/CGAL/boost/graph/IO/PLY.h index 0fdca4c4b07..a62c4086c4a 100644 --- a/BGL/include/CGAL/boost/graph/IO/PLY.h +++ b/BGL/include/CGAL/boost/graph/IO/PLY.h @@ -83,6 +83,8 @@ bool read_PLY_BGL(std::istream& is, \brief reads the graph `g` from the input stream, using the \ref IOStreamPLY. + The data is expected to represent a 2-manifold (possibly with borders). + \attention When reading a binary file, the flag `std::ios::binary` flag must be set during the creation of the `ifstream`. \tparam Graph a model of `MutableFaceGraph` @@ -95,7 +97,7 @@ bool read_PLY_BGL(std::istream& is, \cgalNamedParamsBegin \cgalParamNBegin{vertex_point_map} \cgalParamDescription{a property map associating points to the vertices of `g`} - \cgalParamType{a class model of `ReadWritePropertyMap` with `boost::graph_traits::%vertex_descriptor` + \cgalParamType{a class model of `WritablePropertyMap` with `boost::graph_traits::%vertex_descriptor` as key type and `%Point_3` as value type} \cgalParamDefault{`boost::get(CGAL::vertex_point, g)`} \cgalParamExtra{If this parameter is omitted, an internal property map for `CGAL::vertex_point_t` @@ -104,21 +106,21 @@ bool read_PLY_BGL(std::istream& is, \cgalParamNBegin{vertex_index_map} \cgalParamDescription{a property map associating to each vertex of `graph` a unique index} - \cgalParamType{a class model of `ReadWritePropertyMap` with `boost::graph_traits::%vertex_descriptor` + \cgalParamType{a class model of `WritablePropertyMap` with `boost::graph_traits::%vertex_descriptor` as key type and `std::size_t` as value type} \cgalParamDefault{vertex indices that may exist in the input will be ignored} \cgalParamNEnd \cgalParamNBegin{vertex_color_map} \cgalParamDescription{a property map associating colors to the vertices of `g`} - \cgalParamType{a class model of `ReadWritePropertyMap` with `boost::graph_traits::%vertex_descriptor` + \cgalParamType{a class model of `WritablePropertyMap` with `boost::graph_traits::%vertex_descriptor` as key type and `CGAL::Color` as value type} \cgalParamDefault{vertex colors that may exist in the input will be ignored} \cgalParamNEnd \cgalParamNBegin{face_color_map} \cgalParamDescription{a property map associating colors to the faces of `g`} - \cgalParamType{a class model of `ReadWritePropertyMap` with `boost::graph_traits::%face_descriptor` + \cgalParamType{a class model of `WritablePropertyMap` with `boost::graph_traits::%face_descriptor` as key type and `CGAL::Color` as value type} \cgalParamDefault{face colors that may exist in the input will be ignored} \cgalParamNEnd @@ -130,8 +132,6 @@ bool read_PLY_BGL(std::istream& is, \cgalParamNEnd \cgalNamedParamsEnd - \pre The data must represent a 2-manifold - \returns `true` if reading was successful and the resulting mesh is valid, `false` otherwise. \sa Overloads of this function for specific models of the concept `FaceGraph`. @@ -165,6 +165,8 @@ bool read_PLY(std::istream& is, Graph& g, \brief reads the graph `g` from a file named `fname`, using the \ref IOStreamPLY. + The data is expected to represent a 2-manifold (possibly with borders). + \tparam Graph a model of `MutableFaceGraph` \tparam NamedParameters a sequence of \ref bgl_namedparameters "Named Parameters" @@ -181,7 +183,7 @@ bool read_PLY(std::istream& is, Graph& g, \cgalParamNBegin{vertex_point_map} \cgalParamDescription{a property map associating points to the vertices of `g`} - \cgalParamType{a class model of `ReadWritePropertyMap` with `boost::graph_traits::%vertex_descriptor` + \cgalParamType{a class model of `WritablePropertyMap` with `boost::graph_traits::%vertex_descriptor` as key type and `%Point_3` as value type} \cgalParamDefault{`boost::get(CGAL::vertex_point, g)`} \cgalParamExtra{If this parameter is omitted, an internal property map for `CGAL::vertex_point_t` @@ -190,21 +192,21 @@ bool read_PLY(std::istream& is, Graph& g, \cgalParamNBegin{vertex_index_map} \cgalParamDescription{a property map associating to each vertex of `graph` a unique index} - \cgalParamType{a class model of `ReadWritePropertyMap` with `boost::graph_traits::%vertex_descriptor` + \cgalParamType{a class model of `WritablePropertyMap` with `boost::graph_traits::%vertex_descriptor` as key type and `std::size_t` as value type} \cgalParamDefault{vertex indices that may exist in the input will be ignored} \cgalParamNEnd \cgalParamNBegin{vertex_color_map} \cgalParamDescription{a property map associating colors to the vertices of `g`} - \cgalParamType{a class model of `ReadWritePropertyMap` with `boost::graph_traits::%vertex_descriptor` + \cgalParamType{a class model of `WritablePropertyMap` with `boost::graph_traits::%vertex_descriptor` as key type and `CGAL::Color` as value type} \cgalParamDefault{vertex colors that may exist in the input will be ignored} \cgalParamNEnd \cgalParamNBegin{face_color_map} \cgalParamDescription{a property map associating colors to the faces of `g`} - \cgalParamType{a class model of `ReadWritePropertyMap` with `boost::graph_traits::%face_descriptor` + \cgalParamType{a class model of `WritablePropertyMap` with `boost::graph_traits::%face_descriptor` as key type and `CGAL::Color` as value type} \cgalParamDefault{face colors that may exist in the input will be ignored} \cgalParamNEnd @@ -216,8 +218,6 @@ bool read_PLY(std::istream& is, Graph& g, \cgalParamNEnd \cgalNamedParamsEnd - \pre The data must represent a 2-manifold - \returns `true` if reading was successful and the resulting mesh is valid, `false` otherwise. \sa Overloads of this function for specific models of the concept `FaceGraph`. @@ -303,21 +303,21 @@ bool read_PLY(const std::string& fname, Graph& g, \cgalParamNBegin{vertex_index_map} \cgalParamDescription{a property map associating to each vertex of `graph` a unique index} - \cgalParamType{a class model of `ReadWritePropertyMap` with `boost::graph_traits::%vertex_descriptor` + \cgalParamType{a class model of `WritablePropertyMap` with `boost::graph_traits::%vertex_descriptor` as key type and `std::size_t` as value type} \cgalParamDefault{vertex indices that may exist in the input will be ignored} \cgalParamNEnd \cgalParamNBegin{vertex_color_map} \cgalParamDescription{a property map associating colors to the vertices of `g`} - \cgalParamType{a class model of `ReadWritePropertyMap` with `boost::graph_traits::%vertex_descriptor` + \cgalParamType{a class model of `WritablePropertyMap` with `boost::graph_traits::%vertex_descriptor` as key type and `CGAL::Color` as value type} \cgalParamDefault{vertex colors that may exist in the input will be ignored} \cgalParamNEnd \cgalParamNBegin{face_color_map} \cgalParamDescription{a property map associating colors to the faces of `g`} - \cgalParamType{a class model of `ReadWritePropertyMap` with `boost::graph_traits::%face_descriptor` + \cgalParamType{a class model of `WritablePropertyMap` with `boost::graph_traits::%face_descriptor` as key type and `CGAL::Color` as value type} \cgalParamDefault{face colors that may exist in the input will be ignored} \cgalParamNEnd diff --git a/BGL/include/CGAL/boost/graph/IO/STL.h b/BGL/include/CGAL/boost/graph/IO/STL.h index c9aded3268b..442670ca6ad 100644 --- a/BGL/include/CGAL/boost/graph/IO/STL.h +++ b/BGL/include/CGAL/boost/graph/IO/STL.h @@ -70,6 +70,8 @@ public: \brief reads the graph `g` from the input stream, using the \ref IOStreamSTL. + The data is expected to represent a 2-manifold (possibly with borders). + \attention The graph `g` is not cleared, and the data from the stream is added. \attention When reading a binary file, the flag `std::ios::binary` flag must be set during the creation of the `ifstream`. @@ -84,7 +86,7 @@ public: \cgalNamedParamsBegin \cgalParamNBegin{vertex_point_map} \cgalParamDescription{a property map associating points to the vertices of `g`} - \cgalParamType{a class model of `ReadWritePropertyMap` with `boost::graph_traits::%vertex_descriptor` + \cgalParamType{a class model of `WritablePropertyMap` with `boost::graph_traits::%vertex_descriptor` as key type and `%Point_3` as value type} \cgalParamDefault{`boost::get(CGAL::vertex_point, g)`} \cgalParamExtra{If this parameter is omitted, an internal property map for `CGAL::vertex_point_t` @@ -98,8 +100,6 @@ public: \cgalParamNEnd \cgalNamedParamsEnd - \pre The data must represent a 2-manifold - \returns `true` if reading was successful and the resulting mesh is valid, `false` otherwise. \sa Overloads of this function for specific models of the concept `FaceGraph`. @@ -121,6 +121,8 @@ bool read_STL(std::istream& is, \brief reads the graph `g` from the file `fname`, using the \ref IOStreamSTL. + The data is expected to represent a 2-manifold (possibly with borders). + \attention The graph `g` is not cleared, and the data from the stream is added. \tparam Graph a model of `MutableFaceGraph` @@ -139,7 +141,7 @@ bool read_STL(std::istream& is, \cgalParamNBegin{vertex_point_map} \cgalParamDescription{a property map associating points to the vertices of `g`} - \cgalParamType{a class model of `ReadWritePropertyMap` with `boost::graph_traits::%vertex_descriptor` + \cgalParamType{a class model of `WritablePropertyMap` with `boost::graph_traits::%vertex_descriptor` as key type and `%Point_3` as value type} \cgalParamDefault{`boost::get(CGAL::vertex_point, g)`} \cgalParamExtra{If this parameter is omitted, an internal property map for `CGAL::vertex_point_t` @@ -153,8 +155,6 @@ bool read_STL(std::istream& is, \cgalParamNEnd \cgalNamedParamsEnd - \pre The data must represent a 2-manifold - \returns `true` if reading was successful and the resulting mesh is valid, `false` otherwise. \sa Overloads of this function for specific models of the concept `FaceGraph`. @@ -329,7 +329,7 @@ bool write_STL(std::ostream& os, \cgalParamNBegin{vertex_point_map} \cgalParamDescription{a property map associating points to the vertices of `g`} - \cgalParamType{a class model of `ReadWritePropertyMap` with `boost::graph_traits::%vertex_descriptor` + \cgalParamType{a class model of `WritablePropertyMap` with `boost::graph_traits::%vertex_descriptor` as key type and `%Point_3` as value type} \cgalParamDefault{`boost::get(CGAL::vertex_point, g)`} \cgalParamExtra{If this parameter is omitted, an internal property map for `CGAL::vertex_point_t` diff --git a/BGL/include/CGAL/boost/graph/IO/VTK.h b/BGL/include/CGAL/boost/graph/IO/VTK.h index c900b1cc760..c4b6760e1f4 100644 --- a/BGL/include/CGAL/boost/graph/IO/VTK.h +++ b/BGL/include/CGAL/boost/graph/IO/VTK.h @@ -116,6 +116,8 @@ bool vtkPointSet_to_polygon_mesh(vtkPointSet* poly_data, * * \brief reads a PolyData in the \ref IOStreamVTK into a triangulated surface mesh. * + * The data is expected to represent a 2-manifold (possibly with borders). + * * \attention The graph `g` is not cleared, and the data from the stream is added. * * \tparam Graph a model of `MutableFaceGraph` @@ -128,7 +130,7 @@ bool vtkPointSet_to_polygon_mesh(vtkPointSet* poly_data, * \cgalNamedParamsBegin * \cgalParamNBegin{vertex_point_map} * \cgalParamDescription{a property map associating points to the vertices of `g`} - * \cgalParamType{a class model of `ReadWritePropertyMap` with `boost::graph_traits::%vertex_descriptor` + * \cgalParamType{a class model of `WritablePropertyMap` with `boost::graph_traits::%vertex_descriptor` * as key type and `%Point_3` as value type} * \cgalParamDefault{`boost::get(CGAL::vertex_point, g)`} * \cgalParamExtra{If this parameter is omitted, an internal property map for `CGAL::vertex_point_t` @@ -137,7 +139,6 @@ bool vtkPointSet_to_polygon_mesh(vtkPointSet* poly_data, * * \cgalNamedParamsEnd * - * \pre The data must represent a 2-manifold * * \returns `true` if reading was successful, `false` otherwise. */ 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 7ca2eaed520..569493ae2e4 100644 --- a/BGL/include/CGAL/boost/graph/IO/polygon_mesh_io.h +++ b/BGL/include/CGAL/boost/graph/IO/polygon_mesh_io.h @@ -140,6 +140,8 @@ bool read_polygon_mesh(const std::string& fname, Graph& g) * * The format is detected from the filename extension (letter case is not important). * + * The data is expected to represent a 2-manifold (possibly with borders). + * * \tparam Graph a model of `MutableFaceGraph` * \tparam NamedParameters a sequence of \ref bgl_namedparameters "Named Parameters" * @@ -150,7 +152,7 @@ bool read_polygon_mesh(const std::string& fname, Graph& g) * \cgalNamedParamsBegin * \cgalParamNBegin{vertex_point_map} * \cgalParamDescription{a property map associating points to the vertices of `g`} - * \cgalParamType{a class model of `ReadWritePropertyMap` with `boost::graph_traits::%vertex_descriptor` + * \cgalParamType{a class model of `WritablePropertyMap` with `boost::graph_traits::%vertex_descriptor` * as key type and `%Point_3` as value type} * \cgalParamDefault{`boost::get(CGAL::vertex_point, g)`} * \cgalParamExtra{If this parameter is omitted, an internal property map for `CGAL::vertex_point_t` @@ -173,8 +175,6 @@ bool read_polygon_mesh(const std::string& fname, Graph& g) * * Other named parameters may be used according to the file extension, see \ref PkgBGLIOFct for an exhaustive list. * - * \pre The data must represent a 2-manifold - * * \return `true` if reading was successful, `false` otherwise. * * \sa \link PMP_IO_grp `CGAL::Polygon_mesh_processing::read_polygon_mesh()`\endlink if the data is not 2-manifold diff --git a/BGL/include/CGAL/boost/graph/properties.h b/BGL/include/CGAL/boost/graph/properties.h index 588ea76885e..cdf30aec48f 100644 --- a/BGL/include/CGAL/boost/graph/properties.h +++ b/BGL/include/CGAL/boost/graph/properties.h @@ -163,7 +163,7 @@ struct Is_writable_property_map // 'lvalue_pmap_tag' is annoying, because the property map is allowed to be non-mutable, // but boost::lvalue_property_map_tag is defined as: // struct lvalue_property_map_tag : public read_write_property_map_tag -// so we can't just check that 'writable_property_map_tag' is a base of the the lvalue tag. +// so we can't just check that 'writable_property_map_tag' is a base of the lvalue tag. // // This checks if the reference is non-const, which is not completely correct: map[key] returning // a non-const reference doesn't mean that 'put(map, key, val)' exists, which is what a writable diff --git a/CGAL_ipelets/doc/CGAL_ipelets/PackageDescription.txt b/CGAL_ipelets/doc/CGAL_ipelets/PackageDescription.txt index 92f725573d4..3f15baf90de 100644 --- a/CGAL_ipelets/doc/CGAL_ipelets/PackageDescription.txt +++ b/CGAL_ipelets/doc/CGAL_ipelets/PackageDescription.txt @@ -5,7 +5,7 @@ \cgalPkgPicture{ipeico.jpg} \cgalPkgSummaryBegin \cgalPkgAuthors{Olivier Devillers, Sébastien Loriot, and Sylvain Pion} -\cgalPkgDesc{This package provides a generic framework to easily write ipelets (plug-in's) using \cgal for the the Ipe extensible drawing editor.} +\cgalPkgDesc{This package provides a generic framework to easily write ipelets (plug-in's) using \cgal for the Ipe extensible drawing editor.} \cgalPkgManuals{Chapter_CGAL_Ipelets,PkgCGALIpeletsRef} \cgalPkgSummaryEnd \cgalPkgShortInfoBegin diff --git a/Circular_kernel_2/benchmark/parser/benchmark_parser.h b/Circular_kernel_2/benchmark/parser/benchmark_parser.h index 5a43fb65fdf..f1870fe8d40 100644 --- a/Circular_kernel_2/benchmark/parser/benchmark_parser.h +++ b/Circular_kernel_2/benchmark/parser/benchmark_parser.h @@ -24,7 +24,7 @@ // If the file has a different format name, it is rejected. If the // Major number in the file is higher than the major number listed // here then the file is also rejected. If the number -// in the file is lower than the the number listed here, the parser +// in the file is lower than the number listed here, the parser // assumes backwards compatibility and continues parsing. const std::string BENCHMARK_FORMAT_NAME( "AcsBenchmark"); const int BENCHMARK_FORMAT_MAJOR = 0; diff --git a/Cone_spanners_2/include/CGAL/Cone_spanners_2/Plane_scan_tree.h b/Cone_spanners_2/include/CGAL/Cone_spanners_2/Plane_scan_tree.h index 88dea372275..74d37f0d0bc 100644 --- a/Cone_spanners_2/include/CGAL/Cone_spanners_2/Plane_scan_tree.h +++ b/Cone_spanners_2/include/CGAL/Cone_spanners_2/Plane_scan_tree.h @@ -154,7 +154,7 @@ public: return const_iterator (l, k); } - /* Returns the the minimum value that has a key strictly greater than + /* Returns the minimum value that has a key strictly greater than * the specified key. * * @param x The threshold key diff --git a/Convex_hull_d/include/CGAL/Convex_hull_d.h b/Convex_hull_d/include/CGAL/Convex_hull_d.h index 611d649398b..46c6d0f1fc1 100644 --- a/Convex_hull_d/include/CGAL/Convex_hull_d.h +++ b/Convex_hull_d/include/CGAL/Convex_hull_d.h @@ -322,7 +322,7 @@ typedef Hull_vertex_iterator_ can be used as handles. Note also that all iterator and handle types come also in a const flavor, e.g., |Vertex_const_iterator| is the constant version of |Vertex_iterator|. Thus use the const version -whenever the the convex hull object is referenced as constant.}*/ +whenever the convex hull object is referenced as constant.}*/ #define CGAL_USING(t) typedef typename Base::t t CGAL_USING(Simplex_const_iterator);CGAL_USING(Vertex_const_iterator); @@ -396,7 +396,7 @@ protected: /*{\Xop adds all unmarked unbounded simplices with $x$-visible base facet to |visible_simplices| and marks them. In |location| the procedure returns the position of |x| with respect to the - current hull: $-1$ for inside, $0$ for on the the boundary, + current hull: $-1$ for inside, $0$ for on the boundary, and $+1$ for outside; the initial value of |location| for the outermost call must be $-1$. If $x$ is contained in the boundary of |\Mvar| then a facet incident to $x$ is returned diff --git a/Envelope_3/include/CGAL/Envelope_3/Envelope_element_visitor_3.h b/Envelope_3/include/CGAL/Envelope_3/Envelope_element_visitor_3.h index 6f7f4c54cfe..147ddaf717b 100644 --- a/Envelope_3/include/CGAL/Envelope_3/Envelope_element_visitor_3.h +++ b/Envelope_3/include/CGAL/Envelope_3/Envelope_element_visitor_3.h @@ -533,7 +533,7 @@ public: CGAL_assertion(!cur_obj.is_empty()); if (assign(point, cur_obj)) { - // if the point is on the curve, should add it the the split points + // if the point is on the curve, should add it the split points // list, otherwise, it is irrelevant and should be ignored if (is_point_on_curve(point, original_cv)) split_points.push_back(Point_2_with_info(point, false, false)); diff --git a/HalfedgeDS/include/CGAL/HalfedgeDS_decorator.h b/HalfedgeDS/include/CGAL/HalfedgeDS_decorator.h index e6fc3c03fac..92afeab7ae1 100644 --- a/HalfedgeDS/include/CGAL/HalfedgeDS_decorator.h +++ b/HalfedgeDS/include/CGAL/HalfedgeDS_decorator.h @@ -695,7 +695,7 @@ public: protected: // Supports_halfedge_vertices void erase_connected_component_vertex( Halfedge_handle ,Tag_false){} void erase_connected_component_vertex( Halfedge_handle h, Tag_true) { - // Erases the the vertex incident to h and sets all references + // Erases the vertex incident to h and sets all references // from halfedges around this vertex to Halfedge_handle(), // if the incident vertex handle is not already equal to // Halfedge_handle(). It is used to erase vertices as soon diff --git a/Installation/CHANGES.md b/Installation/CHANGES.md index b6cc3849288..d5cb7c50271 100644 --- a/Installation/CHANGES.md +++ b/Installation/CHANGES.md @@ -1199,7 +1199,7 @@ Release date: September 2017 robust versions of the kernel functors `Construct_weighted_circumcenter_3`, `Compute_squared_radius_3`, and `Compute_squared_radius_smallest_orthogonal_sphere_3`. This class - can be used as traits class in the the `Mesh_3` package to + can be used as traits class in the `Mesh_3` package to efficiently yet robustly generate 3D meshes. - Add a new type of polyhedral domain with features, `Polyhedral_complex_mesh_domain_3`. The domain is defined by a diff --git a/Minkowski_sum_2/include/CGAL/Small_side_angle_bisector_decomposition_2.h b/Minkowski_sum_2/include/CGAL/Small_side_angle_bisector_decomposition_2.h index 678ffefc270..c0ff417cc65 100644 --- a/Minkowski_sum_2/include/CGAL/Small_side_angle_bisector_decomposition_2.h +++ b/Minkowski_sum_2/include/CGAL/Small_side_angle_bisector_decomposition_2.h @@ -731,7 +731,7 @@ private: } /*! - * Get the angle ratio created by the the bisection of the angle at the + * Get the angle ratio created by the bisection of the angle at the * reflex vertex v by the diagonal uv. * \param vec A vector defining counterclockwise-oriented polygon. * \param v_ind The index of the vertex v. diff --git a/Number_types/include/CGAL/Sqrt_extension/Sqrt_extension_type.h b/Number_types/include/CGAL/Sqrt_extension/Sqrt_extension_type.h index ff676eb45c2..95fd32ac954 100644 --- a/Number_types/include/CGAL/Sqrt_extension/Sqrt_extension_type.h +++ b/Number_types/include/CGAL/Sqrt_extension/Sqrt_extension_type.h @@ -525,7 +525,7 @@ compare (const NT& num) const { } // compare of two values that may be in different extension -// However, the default is, that the the numbers are defined over the same +// However, the default is, that the numbers are defined over the same // extension. CGAL::Comparison_result compare(const Self& y, bool in_same_extension = !ACDE_TAG::value ) const diff --git a/Point_set_3/doc/Point_set_3/Point_set_3.txt b/Point_set_3/doc/Point_set_3/Point_set_3.txt index 2a765f352bf..a97a768ae54 100644 --- a/Point_set_3/doc/Point_set_3/Point_set_3.txt +++ b/Point_set_3/doc/Point_set_3/Point_set_3.txt @@ -105,7 +105,7 @@ format. The PLY format is the usual choice when storing an arbitrary number of additional properties of points is needed. \cgal provides a function -`read_ply_point_set()` that allows the user to recover any PLY +\link PkgPointSet3IOPLY `read_PLY()` \endlink that allows the user to recover any PLY property wanted, provided the adapted PLY interpreter is implemented. diff --git a/Point_set_3/include/CGAL/Point_set_3.h b/Point_set_3/include/CGAL/Point_set_3.h index 8748cd51597..569da854beb 100644 --- a/Point_set_3/include/CGAL/Point_set_3.h +++ b/Point_set_3/include/CGAL/Point_set_3.h @@ -65,8 +65,8 @@ namespace CGAL { parameters if called with a `CGAL::Point_set_3` object as argument. - \tparam Point Point type. - \tparam Vector Normal vector type. + \tparam Point Point type + \tparam Vector Normal vector type \cgalModels `Range` */ 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 87f28f58c11..8c7818621b3 100644 --- a/Point_set_3/include/CGAL/Point_set_3/IO.h +++ b/Point_set_3/include/CGAL/Point_set_3/IO.h @@ -48,8 +48,7 @@ class Point_set_3; normal vectors, the normal map is added to the point set. For PLY input, all point properties found in the header are added. - \tparam Point a `CGAL::Point_3` - \tparam Vector a `CGAL::Vector_3` + \attention When reading a binary file, the flag `std::ios::binary` flag must be set during the creation of the `ifstream`. \param is the input stream \param ps the point set @@ -84,10 +83,10 @@ std::istream& operator>>(std::istream& is, /// \cond SKIP_IN_MANUAL -template +template bool read_point_set(const std::string& fname, - CGAL::Point_set_3& ps) + CGAL::Point_set_3& ps, + const CGAL_BGL_NP_CLASS& np) { const std::string ext = IO::internal::get_file_extension(fname); @@ -96,7 +95,7 @@ bool read_point_set(const std::string& fname, else if(ext == "off") return read_OFF(fname, ps); else if(ext =="ply") - return read_PLY(fname, ps); + return read_PLY(fname, ps, np); #ifdef CGAL_LINKED_WITH_LASLIB else if(ext == "las") return read_LAS(fname, ps); @@ -122,20 +121,48 @@ bool read_point_set(const std::string& fname, If the file contains normal vectors, the normal map is added to the point set. For PLY input, all point properties found in the header are added. - \tparam Point a `CGAL::Point_3` - \tparam Vector a `CGAL::Vector_3` + \tparam Point the point type of the `Point_set_3` + \tparam Vector the vector type of the `Point_set_3` + \tparam NamedParameters a sequence of \ref bgl_namedparameters "Named Parameters" \param fname the path to the input file \param ps the point set + \param np an optional sequence of \ref bgl_namedparameters "Named Parameters" among the ones listed below + + \cgalNamedParamsBegin + \cgalParamNBegin{use_binary_mode} + \cgalParamDescription{indicates whether data should be read in binary (`true`) or in ASCII (`false`)} + \cgalParamType{Boolean} + \cgalParamDefault{`true`} + \cgalParamExtra{This parameter is only relevant for `PLY` writing: the `OFF` and `XYZ` formats + are always ASCII, and the `LAS` format is always binary.} + \cgalParamNEnd + \cgalNamedParamsEnd \return `true` if the reading was successful, `false` otherwise. */ +template +bool read_point_set(const char* fname, CGAL::Point_set_3& ps, const CGAL_BGL_NP_CLASS& np) +{ + return read_point_set(std::string(fname), ps, np); +} + +/// \cond SKIP_IN_MANUAL + template bool read_point_set(const char* fname, CGAL::Point_set_3& ps) { - return read_point_set(std::string(fname), ps); + return write_point_set(fname, ps, parameters::all_default()); } +template +bool read_point_set(const std::string& fname, CGAL::Point_set_3& ps) +{ + return write_point_set(fname.c_str(), ps, parameters::all_default()); +} + +/// \endcond + //////////////////////////////////////////////////////////////////////////////////////////////////// //////////////////////////////////////////////////////////////////////////////////////////////////// // Write @@ -143,18 +170,16 @@ bool read_point_set(const char* fname, CGAL::Point_set_3& ps) /*! \ingroup PkgPointSet3IO - \brief inserts the point set in an output stream in ASCII PLY format. - All properties are inserted in their instantiation order. + \brief writes the point set in an output stream in the \ref IOStreamPLY. - \tparam Point a `CGAL::Point_3` - \tparam Vector a `CGAL::Vector_3` + All properties are inserted in their instantiation order. + + \attention When writing a binary file, the flag `std::ios::binary` flag must be set during the creation of the `ofstream`. \param os the output stream \param ps the point set \return `os` - - \relates Point_set_3 */ template std::ostream& operator<<(std::ostream& os, @@ -192,7 +217,7 @@ bool write_point_set(const std::string& fname, /*! \ingroup PkgPointSet3IO - \brief inserts the point set in an output file. + \brief writes the point set in an output file. Supported file formats are the following: - \ref IOStreamOFF (`.off`) @@ -202,8 +227,8 @@ bool write_point_set(const std::string& fname, The format is detected from the filename extension (letter case is not important). - \tparam Point a `CGAL::Point_3` - \tparam Vector a `CGAL::Vector_3` + \tparam Point the point type of the `Point_set_3` + \tparam Vector the vector type of the `Point_set_3` \tparam NamedParameters a sequence of \ref bgl_namedparameters "Named Parameters" \param fname the path to the output file @@ -211,6 +236,14 @@ bool write_point_set(const std::string& fname, \param np an optional sequence of \ref bgl_namedparameters "Named Parameters" among the ones listed below \cgalNamedParamsBegin + \cgalParamNBegin{use_binary_mode} + \cgalParamDescription{indicates whether data should be written in binary (`true`) or in ASCII (`false`)} + \cgalParamType{Boolean} + \cgalParamDefault{`true`} + \cgalParamExtra{This parameter is only relevant for `PLY` writing: the `OFF` and `XYZ` formats + are always ASCII, and the `LAS` format is always binary.} + \cgalParamNEnd + \cgalParamNBegin{stream_precision} \cgalParamDescription{a parameter used to set the precision (i.e. how many digits are generated) of the output stream} \cgalParamType{int} diff --git a/Point_set_3/include/CGAL/Point_set_3/IO/LAS.h b/Point_set_3/include/CGAL/Point_set_3/IO/LAS.h index b0ca1a60a14..aae9735de10 100644 --- a/Point_set_3/include/CGAL/Point_set_3/IO/LAS.h +++ b/Point_set_3/include/CGAL/Point_set_3/IO/LAS.h @@ -65,9 +65,6 @@ void check_if_property_is_used(PointSet& point_set, \attention When reading a binary file, the flag `std::ios::binary` flag must be set during the creation of the `ifstream`. - \tparam Point a `CGAL::Point_3` - \tparam Vector a `CGAL::Vector_3` - \param is the input stream \param point_set the point set @@ -159,10 +156,7 @@ bool read_LAS(std::istream& is, /*! \ingroup PkgPointSet3IOLAS - \brief reads the content of an intput stream in the \ref IOStreamLAS into a point set. - - \tparam Point a `CGAL::Point_3` - \tparam Vector a `CGAL::Vector_3` + \brief reads the content of an intput file in the \ref IOStreamLAS into a point set. \param fname the path to the input file \param point_set the point set @@ -217,8 +211,8 @@ CGAL_DEPRECATED bool read_las_point_set(std::istream& is, ///< input stream. \attention When writing a binary file, the flag `std::ios::binary` flag must be set during the creation of the `ofstream`. - \tparam Point a `CGAL::Point_3` - \tparam Vector a `CGAL::Vector_3` + \tparam Point the point type of the `Point_set_3` + \tparam Vector the vector type of the `Point_set_3` \tparam NamedParameters a sequence of \ref bgl_namedparameters "Named Parameters" \param os the output stream @@ -426,8 +420,8 @@ bool write_LAS(std::ostream& os, CGAL::Point_set_3& point_set) \brief writes the content of a point set into an output file in the \ref IOStreamLAS. - \tparam Point a `CGAL::Point_3` - \tparam Vector a `CGAL::Vector_3` + \tparam Point the point type of the `Point_set_3` + \tparam Vector the vector type of the `Point_set_3` \tparam NamedParameters a sequence of \ref bgl_namedparameters "Named Parameters" \param fname the path to the output file diff --git a/Point_set_3/include/CGAL/Point_set_3/IO/OFF.h b/Point_set_3/include/CGAL/Point_set_3/IO/OFF.h index b7dbbcc9661..b468ec2839f 100644 --- a/Point_set_3/include/CGAL/Point_set_3/IO/OFF.h +++ b/Point_set_3/include/CGAL/Point_set_3/IO/OFF.h @@ -44,9 +44,6 @@ class Point_set_3; \brief reads the content of an intput stream in the \ref IOStreamOFF into a point set. - \tparam Point a `CGAL::Point_3` - \tparam Vector a `CGAL::Vector_3` - \param is the input stream \param point_set the point set @@ -83,9 +80,6 @@ bool read_OFF(std::istream& is, \brief reads the content of an input file in the \ref IOStreamOFF into a point set. - \tparam Point a `CGAL::Point_3` - \tparam Vector a `CGAL::Vector_3` - \param fname the path to the input file \param point_set the point set @@ -134,8 +128,8 @@ CGAL_DEPRECATED bool read_off_point_set(std::istream& is, ///< input stream. \brief writes the content of a point set into an output stream in the \ref IOStreamOFF. - \tparam Point a `CGAL::Point_3` - \tparam Vector a `CGAL::Vector_3` + \tparam Point the point type of the `Point_set_3` + \tparam Vector the vector type of the `Point_set_3` \tparam NamedParameters a sequence of \ref bgl_namedparameters "Named Parameters" \param os the output stream @@ -181,8 +175,8 @@ bool write_OFF(std::ostream& os, const CGAL::Point_set_3& point_s \brief writes the content of a point set into an output file in the \ref IOStreamOFF. - \tparam Point a `CGAL::Point_3` - \tparam Vector a `CGAL::Vector_3` + \tparam Point the point type of the `Point_set_3` + \tparam Vector the vector type of the `Point_set_3` \tparam NamedParameters a sequence of \ref bgl_namedparameters "Named Parameters" \param fname the path to the output file diff --git a/Point_set_3/include/CGAL/Point_set_3/IO/PLY.h b/Point_set_3/include/CGAL/Point_set_3/IO/PLY.h index b4897d62056..f9626ce091f 100644 --- a/Point_set_3/include/CGAL/Point_set_3/IO/PLY.h +++ b/Point_set_3/include/CGAL/Point_set_3/IO/PLY.h @@ -240,9 +240,6 @@ public: \attention When reading a binary file, the flag `std::ios::binary` flag must be set during the creation of the `ifstream`. - \tparam Point a `CGAL::Point_3` - \tparam Vector a `CGAL::Vector_3` - \param is the input stream \param point_set the point set \param comments optional PLY comments. @@ -327,8 +324,8 @@ bool read_PLY(std::istream& is, CGAL::Point_set_3& point_set) header. Each line starting by "comment " in the header is appended to the `comments` string (without the "comment " word). - \tparam Point a `CGAL::Point_3` - \tparam Vector a `CGAL::Vector_3` + \tparam Point the point type of the `Point_set_3` + \tparam Vector the vector type of the `Point_set_3` \tparam NamedParameters a sequence of \ref bgl_namedparameters "Named Parameters" \param fname the path to the input file @@ -468,8 +465,8 @@ CGAL_DEPRECATED bool read_ply_point_set(std::istream& is, ///< input stream. \attention When writing a binary file, the flag `std::ios::binary` flag must be set during the creation of the `ofstream`. - \tparam Point a `CGAL::Point_3` - \tparam Vector a `CGAL::Vector_3` + \tparam Point the point type of the `Point_set_3` + \tparam Vector the vector type of the `Point_set_3` \tparam NamedParameters a sequence of \ref bgl_namedparameters "Named Parameters" \param os the output stream @@ -737,8 +734,8 @@ bool write_PLY(std::ostream& os, const CGAL::Point_set_3& point_s the header of the PLY stream (each line will be precedeed by "comment "). - \tparam Point a `CGAL::Point_3` - \tparam Vector a `CGAL::Vector_3` + \tparam Point the point type of the `Point_set_3` + \tparam Vector the vector type of the `Point_set_3` \tparam NamedParameters a sequence of \ref bgl_namedparameters "Named Parameters" \param fname the path to the output file diff --git a/Point_set_3/include/CGAL/Point_set_3/IO/XYZ.h b/Point_set_3/include/CGAL/Point_set_3/IO/XYZ.h index d59d41ad1a9..c96132fdf0e 100644 --- a/Point_set_3/include/CGAL/Point_set_3/IO/XYZ.h +++ b/Point_set_3/include/CGAL/Point_set_3/IO/XYZ.h @@ -43,9 +43,6 @@ class Point_set_3; \brief reads the content of an intput stream in the \ref IOStreamXYZ into a point set. - \tparam Point a `CGAL::Point_3` - \tparam Vector a `CGAL::Vector_3` - \param is the input stream \param point_set the point set @@ -80,10 +77,7 @@ bool read_XYZ(std::istream& is, /*! \ingroup PkgPointSet3IOXYZ - \brief reads the content of an input file in the the \ref IOStreamXYZ into a point set. - - \tparam Point a `CGAL::Point_3` - \tparam Vector a `CGAL::Vector_3` + \brief reads the content of an input file in the \ref IOStreamXYZ into a point set. \param fname the path to the input file \param point_set the point set @@ -132,8 +126,8 @@ CGAL_DEPRECATED bool read_xyz_point_set(std::istream& is, CGAL::Point_set_3& point_s \brief writes the content of a point set into an output file in the \ref IOStreamXYZ. - \tparam Point a `CGAL::Point_3` - \tparam Vector a `CGAL::Vector_3` + \tparam Point the point type of the `Point_set_3` + \tparam Vector the vector type of the `Point_set_3` \tparam NamedParameters a sequence of \ref bgl_namedparameters "Named Parameters" \param fname the path to the output file diff --git a/Point_set_processing_3/doc/Point_set_processing_3/Point_set_processing_3.txt b/Point_set_processing_3/doc/Point_set_processing_3/Point_set_processing_3.txt index 5f635c5f8bd..cf60a22918b 100644 --- a/Point_set_processing_3/doc/Point_set_processing_3/Point_set_processing_3.txt +++ b/Point_set_processing_3/doc/Point_set_processing_3/Point_set_processing_3.txt @@ -147,8 +147,8 @@ the detailed API of the Point Set Processing functions. \subsection Point_set_processing_3Points_io Points And Normals -\cgal provides functions to read and write sets of points or sets of -points with normals from the following file formats: +\cgal provides functions to read and write sets of points (possibly with normals) +from the following file formats: - \link IOStreamXYZ XYZ \endlink (ASCII file three point coordinates `x y z` per line or three point coordinates and three normal vector coordinates `x y z nx ny nz` diff --git a/Point_set_processing_3/include/CGAL/IO/read_las_points.h b/Point_set_processing_3/include/CGAL/IO/read_las_points.h index 0b1ee012828..cf4bec0e539 100644 --- a/Point_set_processing_3/include/CGAL/IO/read_las_points.h +++ b/Point_set_processing_3/include/CGAL/IO/read_las_points.h @@ -366,7 +366,7 @@ void process_properties (const LASpoint& reader, OutputValueType& new_element, \attention When reading a binary file, the flag `std::ios::binary` flag must be set during the creation of the `ifstream`. \tparam OutputIteratorValueType type of objects that can be put in `OutputIterator`. - It is default to `value_type_traits::%type` and can be omitted when the default is fine. + It defaults to `value_type_traits::%type` and can be omitted when the default is fine. \tparam OutputIterator iterator over output points. \tparam PropertyHandler handlers to recover properties. @@ -432,7 +432,7 @@ bool read_LAS_with_properties(std::istream& is, \attention When reading a binary file, the flag `std::ios::binary` flag must be set during the creation of the `ifstream`. \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. + It defaults to `value_type_traits::%type` and can be omitted when the default is fine. \tparam PointOutputIterator iterator over output points. \tparam NamedParameters a sequence of \ref bgl_namedparameters "Named Parameters" @@ -509,7 +509,7 @@ bool read_LAS(std::istream& is, OutputIterator output, Potential additional properties are ignored. \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. + It defaults to `value_type_traits::%type` and can be omitted when the default is fine. \tparam PointOutputIterator iterator over output points. \tparam NamedParameters a sequence of \ref bgl_namedparameters "Named Parameters" diff --git a/Point_set_processing_3/include/CGAL/IO/read_off_points.h b/Point_set_processing_3/include/CGAL/IO/read_off_points.h index f782328e52c..352e58de6b8 100644 --- a/Point_set_processing_3/include/CGAL/IO/read_off_points.h +++ b/Point_set_processing_3/include/CGAL/IO/read_off_points.h @@ -43,14 +43,10 @@ namespace CGAL { /** \ingroup PkgPointSetProcessing3IOOff - \brief reads points (positions + normals, if available) from a .off ASCII stream. - - The function expects for each point a line with the x y z position, - optionally followed by the nx ny nz normal. - Faces are ignored. + \brief reads points (positions + normals, if available), using the \ref IOStreamOFF. \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. + It defaults to `value_type_traits::%type` and can be omitted when the default is fine. \tparam PointOutputIterator iterator over output points. \tparam NamedParameters a sequence of \ref bgl_namedparameters "Named Parameters" @@ -66,8 +62,8 @@ namespace CGAL { \cgalParamNEnd \cgalParamNBegin{normal_map} - \cgalParamDescription{a property map associating normals to the elements of the poing range} - \cgalParamType{a model of `ReadWritePropertyMap` with value type `geom_traits::Vector_3`} + \cgalParamDescription{a property map associating normals to the elements of the point range} + \cgalParamType{a model of `WritablePropertyMap` with value type `geom_traits::Vector_3`} \cgalParamDefault{If this parameter is omitted, normals in the input stream are ignored.} \cgalParamNEnd @@ -201,14 +197,10 @@ bool read_OFF(std::istream& is, /** \ingroup PkgPointSetProcessing3IOOff - \brief reads points (positions + normals, if available) from a .off ASCII file. - - The function expects for each point a line with the x y z position, - optionally followed by the nx ny nz normal. - Faces are ignored. + \brief reads points (positions + normals, if available), using the \ref IOStreamOFF. \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. + It defaults to `value_type_traits::%type` and can be omitted when the default is fine. \tparam PointOutputIterator iterator over output points. \tparam NamedParameters a sequence of \ref bgl_namedparameters "Named Parameters" @@ -224,8 +216,8 @@ bool read_OFF(std::istream& is, \cgalParamNEnd \cgalParamNBegin{normal_map} - \cgalParamDescription{a property map associating normals to the elements of the poing range} - \cgalParamType{a model of `ReadWritePropertyMap` with value type `geom_traits::Vector_3`} + \cgalParamDescription{a property map associating normals to the elements of the point range} + \cgalParamType{a model of `WritablePropertyMap` with value type `geom_traits::Vector_3`} \cgalParamDefault{If this parameter is omitted, normals in the input stream are ignored.} \cgalParamNEnd diff --git a/Point_set_processing_3/include/CGAL/IO/read_ply_points.h b/Point_set_processing_3/include/CGAL/IO/read_ply_points.h index 7274e9a98a2..209452d5141 100644 --- a/Point_set_processing_3/include/CGAL/IO/read_ply_points.h +++ b/Point_set_processing_3/include/CGAL/IO/read_ply_points.h @@ -123,7 +123,7 @@ make_ply_normal_reader(VectorMap normal_map); the value type of `PropertyMap` from N objects of types `T`. \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. + It defaults to `value_type_traits::%type` and can be omitted when the default is fine. \tparam PointOutputIterator iterator over output points. \tparam PropertyHandler handlers to recover properties. @@ -198,14 +198,14 @@ bool read_PLY_with_properties(std::istream& is, /** \ingroup PkgPointSetProcessing3IOPly - \brief reads points (positions + normals, if available) from a .ply stream (ASCII or binary). + \brief reads points (positions + normals, if available), using the \ref IOStreamPLY. Potential additional point properties and faces are ignored. \attention When reading a binary file, the flag `std::ios::binary` flag must be set during the creation of the `ifstream`. \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. + It defaults to `value_type_traits::%type` and can be omitted when the default is fine. \tparam PointOutputIterator iterator over output points. \tparam NamedParameters a sequence of \ref bgl_namedparameters "Named Parameters" @@ -221,8 +221,8 @@ bool read_PLY_with_properties(std::istream& is, \cgalParamNEnd \cgalParamNBegin{normal_map} - \cgalParamDescription{a property map associating normals to the elements of the poing range} - \cgalParamType{a model of `ReadWritePropertyMap` with value type `geom_traits::Vector_3`} + \cgalParamDescription{a property map associating normals to the elements of the point range} + \cgalParamType{a model of `WritablePropertyMap` with value type `geom_traits::Vector_3`} \cgalParamDefault{If this parameter is omitted, normals in the input stream are ignored.} \cgalParamNEnd @@ -274,12 +274,12 @@ bool read_PLY(std::istream& is, /** \ingroup PkgPointSetProcessing3IOPly - \brief reads points (positions + normals, if available) from a .ply file (ASCII or binary). + \brief reads points (positions + normals, if available), using the \ref IOStreamPLY. Potential additional point properties and faces are ignored. \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. + It defaults to `value_type_traits::%type` and can be omitted when the default is fine. \tparam PointOutputIterator iterator over output points. \tparam NamedParameters a sequence of \ref bgl_namedparameters "Named Parameters" @@ -301,8 +301,8 @@ bool read_PLY(std::istream& is, \cgalParamNEnd \cgalParamNBegin{normal_map} - \cgalParamDescription{a property map associating normals to the elements of the poing range} - \cgalParamType{a model of `ReadWritePropertyMap` with value type `geom_traits::Vector_3`} + \cgalParamDescription{a property map associating normals to the elements of the point range} + \cgalParamType{a model of `WritablePropertyMap` with value type `geom_traits::Vector_3`} \cgalParamDefault{If this parameter is omitted, normals in the input stream are ignored.} \cgalParamNEnd 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 308a24c798b..97b4faeb267 100644 --- a/Point_set_processing_3/include/CGAL/IO/read_points.h +++ b/Point_set_processing_3/include/CGAL/IO/read_points.h @@ -89,7 +89,7 @@ bool read_points(const std::string& fname, OutputIterator output) The format is detected from the filename extension (letter case is not important). \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. + It defaults to `value_type_traits::%type` and can be omitted when the default is fine. \tparam PointOutputIterator iterator over output points. \tparam NamedParameters a sequence of \ref bgl_namedparameters "Named Parameters" @@ -105,8 +105,8 @@ bool read_points(const std::string& fname, OutputIterator output) \cgalParamNEnd \cgalParamNBegin{normal_map} - \cgalParamDescription{a property map associating normals to the elements of the poing range} - \cgalParamType{a model of `ReadWritePropertyMap` with value type `geom_traits::Vector_3`} + \cgalParamDescription{a property map associating normals to the elements of the point range} + \cgalParamType{a model of `WritablePropertyMap` with value type `geom_traits::Vector_3`} \cgalParamDefault{If this parameter is omitted, normals in the input stream are ignored.} \cgalParamNEnd @@ -115,12 +115,20 @@ bool read_points(const std::string& fname, OutputIterator output) \cgalParamType{a model of `Kernel`} \cgalParamDefault{a \cgal Kernel deduced from the point type, using `CGAL::Kernel_traits`} \cgalParamNEnd + + \cgalParamNBegin{use_binary_mode} + \cgalParamDescription{indicates whether data should be read in binary (`true`) or in ASCII (`false`)} + \cgalParamType{Boolean} + \cgalParamDefault{`true`} + \cgalParamExtra{This parameter is only relevant for `PLY` reading: the `OFF` and `XYZ` formats + are always ASCII, and the `LAS` format is always binary.} + \cgalParamNEnd \cgalNamedParamsEnd \returns `true` if reading was successful, `false` otherwise. */ -template -bool read_points(const char* fname, OutputIterator output, const NamedParameters& np) +template +bool read_points(const char* fname, PointOutputIterator output, const NamedParameters& np) { return read_points(std::string(fname), output, np); } diff --git a/Point_set_processing_3/include/CGAL/IO/read_xyz_points.h b/Point_set_processing_3/include/CGAL/IO/read_xyz_points.h index ff20e077ba4..51816d7bb7a 100644 --- a/Point_set_processing_3/include/CGAL/IO/read_xyz_points.h +++ b/Point_set_processing_3/include/CGAL/IO/read_xyz_points.h @@ -40,15 +40,10 @@ namespace CGAL { /** \ingroup PkgPointSetProcessing3IOXyz - \brief reads points (positions + normals, if available) from a .xyz ASCII stream. - - The function expects for each point a line with the x y z position, - optionally followed by the nx ny nz normal. - The first line may contain the number of points in the file. - Empty lines and comments starting by # character are allowed. + \brief reads points (positions + normals, if available), using the \ref IOStreamXYZ. \tparam OutputIteratorValueType type of objects that can be put in `OutputIterator`. - It is default to `value_type_traits::%type` and can be omitted when the default is fine. + It defaults to `value_type_traits::%type` and can be omitted when the default is fine. \tparam OutputIterator iterator over output points. \tparam NamedParameters a sequence of \ref bgl_namedparameters "Named Parameters" @@ -64,8 +59,8 @@ namespace CGAL { \cgalParamNEnd \cgalParamNBegin{normal_map} - \cgalParamDescription{a property map associating normals to the elements of the poing range} - \cgalParamType{a model of `ReadWritePropertyMap` with value type `geom_traits::Vector_3`} + \cgalParamDescription{a property map associating normals to the elements of the point range} + \cgalParamType{a model of `WritablePropertyMap` with value type `geom_traits::Vector_3`} \cgalParamDefault{If this parameter is omitted, normals in the input stream are ignored.} \cgalParamNEnd @@ -188,15 +183,10 @@ bool read_XYZ(std::istream& is, /** \ingroup PkgPointSetProcessing3IOXyz - \brief reads points (positions + normals, if available) from a .xyz ASCII file. - - The function expects for each point a line with the x y z position, - optionally followed by the nx ny nz normal. - The first line may contain the number of points in the file. - Empty lines and comments starting by # character are allowed. + \brief reads points (positions + normals, if available), using the \ref IOStreamXYZ. \tparam OutputIteratorValueType type of objects that can be put in `OutputIterator`. - It is default to `value_type_traits::%type` and can be omitted when the default is fine. + It defaults to `value_type_traits::%type` and can be omitted when the default is fine. \tparam OutputIterator iterator over output points. \tparam NamedParameters a sequence of \ref bgl_namedparameters "Named Parameters" @@ -212,8 +202,8 @@ bool read_XYZ(std::istream& is, \cgalParamNEnd \cgalParamNBegin{normal_map} - \cgalParamDescription{a property map associating normals to the elements of the poing range} - \cgalParamType{a model of `ReadWritePropertyMap` with value type `geom_traits::Vector_3`} + \cgalParamDescription{a property map associating normals to the elements of the point range} + \cgalParamType{a model of `WritablePropertyMap` with value type `geom_traits::Vector_3`} \cgalParamDefault{If this parameter is omitted, normals in the input stream are ignored.} \cgalParamNEnd diff --git a/Point_set_processing_3/include/CGAL/IO/write_las_points.h b/Point_set_processing_3/include/CGAL/IO/write_las_points.h index f510b55ae72..e5305f0031f 100644 --- a/Point_set_processing_3/include/CGAL/IO/write_las_points.h +++ b/Point_set_processing_3/include/CGAL/IO/write_las_points.h @@ -69,7 +69,7 @@ namespace CGAL { /** \ingroup PkgPointSetProcessing3IOLas - Generates a %LAS property handler to write 3D points. + \brief generates a %LAS property handler to write 3D points. \tparam PointMap the property map used to store points. @@ -162,7 +162,7 @@ namespace LAS { /** \ingroup PkgPointSetProcessing3IOLas - Saves the range of `points` with properties to a .las stream. + \brief writes the range of `points` with properties to a .las stream. Properties are handled through a variadic list of property handlers. A `PropertyHandle` is a `std::pair`precision()` - of the output stream might not be sufficient depending on the data to be written. + \brief writes the range of `points` (positions + normals, if available), using the \ref IOStreamOFF. \tparam PointRange is a model of `ConstRange`. The value type of its iterator is the key type of the named parameter `point_map`. @@ -115,7 +109,7 @@ bool write_OFF_PSP(std::ostream& os, \cgalParamNEnd \cgalParamNBegin{normal_map} - \cgalParamDescription{a property map associating normals to the elements of the poing range} + \cgalParamDescription{a property map associating normals to the elements of the point range} \cgalParamType{a model of `ReadablePropertyMap` with value type `geom_traits::Vector_3`} \cgalParamDefault{If this parameter is omitted, normals are not written in the output stream.} \cgalParamNEnd @@ -134,8 +128,6 @@ bool write_OFF_PSP(std::ostream& os, \cgalNamedParamsEnd \returns `true` if writing was successful, `false` otherwise. - - \sa \ref IOStreamOFF */ template bool write_OFF(std::ostream& os, @@ -163,13 +155,7 @@ bool write_OFF(std::ostream& os, const PointRange& points, /** \ingroup PkgPointSetProcessing3IOOff - \brief saves the range of `points` (positions + normals, if available) to a .off ASCII stream. - - The function writes for each point a line with the x y z position - followed by the nx ny nz normal (if available). - - \note The `precision()` - of the output stream might not be sufficient depending on the data to be written. + \brief writes the range of `points` (positions + normals, if available), using the \ref IOStreamOFF. \tparam PointRange is a model of `ConstRange`. The value type of its iterator is the key type of the named parameter `point_map`. @@ -187,9 +173,9 @@ bool write_OFF(std::ostream& os, const PointRange& points, \cgalParamNEnd \cgalParamNBegin{normal_map} - \cgalParamDescription{a property map associating normals to the elements of the poing range} + \cgalParamDescription{a property map associating normals to the elements of the point range} \cgalParamType{a model of `ReadablePropertyMap` with value type `geom_traits::Vector_3`} - \cgalParamDefault{If this parameter is omitted, normals are not written in the output stream.} + \cgalParamDefault{If this parameter is omitted, normals are not written in the output file.} \cgalParamNEnd \cgalParamNBegin{geom_traits} diff --git a/Point_set_processing_3/include/CGAL/IO/write_ply_points.h b/Point_set_processing_3/include/CGAL/IO/write_ply_points.h index 5dbb488f99c..673171e5c8e 100644 --- a/Point_set_processing_3/include/CGAL/IO/write_ply_points.h +++ b/Point_set_processing_3/include/CGAL/IO/write_ply_points.h @@ -79,9 +79,7 @@ namespace CGAL { /** \ingroup PkgPointSetProcessing3IOPly - \brief saves the range of `points` with properties using \ref IOStreamPLY. - - %PLY is either ASCII or binary depending on the value of `CGAL::get_mode(os)`. + \brief writes the range of `points` with properties using \ref IOStreamPLY. Properties are handled through a variadic list of property handlers. A `PropertyHandler` can either be: @@ -141,9 +139,7 @@ template bool write_XYZ(std::ostream& os, @@ -156,10 +152,7 @@ bool write_XYZ(std::ostream& os, const PointRange& points, /** \ingroup PkgPointSetProcessing3IOXyz - \brief saves the range of `points` (positions + normals, if available) to a .xyz ASCII stream. - - The function writes for each point a line with the x y z position - followed by the nx ny nz normal (if available). + \brief writes the range of `points` (positions + normals, if available), using the \ref IOStreamXYZ. \tparam PointRange is a model of `ConstRange`. The value type of its iterator is the key type of the named parameter `point_map`. @@ -177,9 +170,9 @@ bool write_XYZ(std::ostream& os, const PointRange& points, \cgalParamNEnd \cgalParamNBegin{normal_map} - \cgalParamDescription{a property map associating normals to the elements of the poing range} + \cgalParamDescription{a property map associating normals to the elements of the point range} \cgalParamType{a model of `ReadablePropertyMap` with value type `geom_traits::Vector_3`} - \cgalParamDefault{If this parameter is omitted, normals are not written in the output stream.} + \cgalParamDefault{If this parameter is omitted, normals are not written in the output file.} \cgalParamNEnd \cgalParamNBegin{geom_traits} @@ -196,8 +189,6 @@ bool write_XYZ(std::ostream& os, const PointRange& points, \cgalNamedParamsEnd \returns `true` if writing was successful, `false` otherwise. - - \sa \ref IOStreamXYZ */ template bool write_XYZ(const char* filename, 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 1c94e854d20..085e22e4caa 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 @@ -37,7 +37,7 @@ namespace Polygon_mesh_processing { /*! \ingroup PMP_IO_grp - * \brief Attempts to read a file as a polygon mesh; in case of failure, reads the file as a polygon soup, + * \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: @@ -61,7 +61,7 @@ namespace Polygon_mesh_processing { * * \cgalParamNBegin{vertex_point_map} * \cgalParamDescription{a property map associating points to the vertices of `g`} - * \cgalParamType{a class model of `ReadWritePropertyMap` with `boost::graph_traits::%vertex_descriptor` + * \cgalParamType{a class model of `WritablePropertyMap` with `boost::graph_traits::%vertex_descriptor` * as key type and `%Point_3` as value type} * \cgalParamDefault{`boost::get(CGAL::vertex_point, g)`} * \cgalParamExtra{If this parameter is omitted, an internal property map for `CGAL::vertex_point_t` @@ -82,7 +82,7 @@ namespace Polygon_mesh_processing { * \cgalParamNEnd * \cgalNamedParamsEnd * - * \return `true` if the reading and conversion worked, `false` otherwise. + * \return `true` if the reading and conversion were successful, `false` otherwise. * * \sa \link PkgBGLIOFct `CGAL::write_polygon_mesh()` \endlink */ diff --git a/Polygon_mesh_processing/include/CGAL/Polygon_mesh_processing/distance.h b/Polygon_mesh_processing/include/CGAL/Polygon_mesh_processing/distance.h index 51582e9c861..b945dccf702 100644 --- a/Polygon_mesh_processing/include/CGAL/Polygon_mesh_processing/distance.h +++ b/Polygon_mesh_processing/include/CGAL/Polygon_mesh_processing/distance.h @@ -866,8 +866,8 @@ sample_triangle_mesh(const TriangleMesh& tm, * * @tparam PointRange a model of the concept `RandomAccessContainer` whose value type is the point type. * @tparam TriangleRange a model of the concept `RandomAccessContainer` - * whose value_type is itself a model of the concept `RandomAccessContainer` - * whose value_type is an unsigned integral value. + * whose `value_type` is itself a model of the concept `RandomAccessContainer` + * whose `value_type` is an unsigned integral value. * @tparam PointOutputIterator a model of `OutputIterator` holding objects of the same type as `PointRange`'s value type * @tparam NamedParameters a sequence of \ref bgl_namedparameters "Named Parameters" * diff --git a/Polygon_mesh_processing/include/CGAL/Polygon_mesh_processing/orient_polygon_soup.h b/Polygon_mesh_processing/include/CGAL/Polygon_mesh_processing/orient_polygon_soup.h index 10158f472a4..25020b0136d 100644 --- a/Polygon_mesh_processing/include/CGAL/Polygon_mesh_processing/orient_polygon_soup.h +++ b/Polygon_mesh_processing/include/CGAL/Polygon_mesh_processing/orient_polygon_soup.h @@ -458,8 +458,8 @@ struct Polygon_soup_orienter * @tparam PointRange a model of the concepts `RandomAccessContainer` * and `BackInsertionSequence` whose value type is the point type. * @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`. + * whose `value_type` is a model of the concept `RandomAccessContainer` + * whose `value_type` is `std::size_t`. * * @param points points of the soup of polygons. Some additional points might be pushed back to resolve * non-manifoldness or non-orientability issues. diff --git a/Polygon_mesh_processing/include/CGAL/Polygon_mesh_processing/polygon_soup_to_polygon_mesh.h b/Polygon_mesh_processing/include/CGAL/Polygon_mesh_processing/polygon_soup_to_polygon_mesh.h index b64d4d52a8a..58ffe9262df 100644 --- a/Polygon_mesh_processing/include/CGAL/Polygon_mesh_processing/polygon_soup_to_polygon_mesh.h +++ b/Polygon_mesh_processing/include/CGAL/Polygon_mesh_processing/polygon_soup_to_polygon_mesh.h @@ -145,8 +145,8 @@ private: * boundaries of the polygons provided in `polygons`. * * @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`. +* whose `value_type` is a model of the concept `RandomAccessContainer` +* whose `value_type` is `std::size_t`. * * @param polygons each element in the range describes a polygon * using the indices of the vertices. diff --git a/Polygon_mesh_processing/include/CGAL/Polygon_mesh_processing/repair_polygon_soup.h b/Polygon_mesh_processing/include/CGAL/Polygon_mesh_processing/repair_polygon_soup.h index 309f8a3a3f8..8f63f00ad56 100644 --- a/Polygon_mesh_processing/include/CGAL/Polygon_mesh_processing/repair_polygon_soup.h +++ b/Polygon_mesh_processing/include/CGAL/Polygon_mesh_processing/repair_polygon_soup.h @@ -167,8 +167,8 @@ bool simplify_polygon(PointRange& points, // // \tparam PointRange a model of the concept `RandomAccessContainer` whose value type is the point type. // \tparam PolygonRange a model of the concept `SequenceContainer` -// whose value_type is itself a model of the concept `SequenceContainer` -// whose value_type is `std::size_t`. +// whose `value_type` is itself a model of the concept `SequenceContainer` +// whose `value_type` is `std::size_t`. // \tparam NamedParameters a sequence of \ref bgl_namedparameters "Named Parameters" // // \param points points of the soup of polygons. @@ -221,8 +221,8 @@ std::size_t simplify_polygons_in_polygon_soup(PointRange& points, // // \tparam PointRange a model of the concept `RandomAccessContainer` whose value type is the point type. // \tparam PolygonRange a model of the concept `SequenceContainer` -// whose value_type is itself a model of the concepts `SequenceContainer` -// and `Swappable` whose value_type is `std::size_t`. +// whose `value_type` is itself a model of the concepts `SequenceContainer` +// and `Swappable` whose `value_type` is `std::size_t`. // \tparam NamedParameters a sequence of \ref bgl_namedparameters "Named Parameters" // // \param points points of the soup of polygons. @@ -326,8 +326,8 @@ std::size_t split_pinched_polygons_in_polygon_soup(PointRange& points, // // \tparam PointRange a model of the concept `Container` whose value type is the point type. // \tparam PolygonRange a model of the concept `SequenceContainer` -// whose value_type is itself a model of the concept `Container` -// whose value_type is `std::size_t`. +// whose `value_type` is itself a model of the concept `Container` +// whose `value_type` is `std::size_t`. // \tparam NamedParameters a sequence of \ref bgl_namedparameters "Named Parameters" // // \param points points of the soup of polygons. @@ -384,8 +384,8 @@ std::size_t remove_degenerate_polygons_in_polygon_soup(PointRange& points, /// /// \tparam PointRange a model of the concept `SequenceContainer` whose value type is the point type. /// \tparam PolygonRange a model of the concept `RandomAccessContainer` -/// whose value_type is itself a model of the concept `RandomAccessContainer` -/// whose value_type is `std::size_t`. +/// whose `value_type` is itself a model of the concept `RandomAccessContainer` +/// whose `value_type` is `std::size_t`. /// /// \param points points of the soup of polygons. /// \param polygons a vector of polygons. Each element in the vector describes a polygon @@ -488,8 +488,8 @@ std::size_t remove_isolated_points_in_polygon_soup(PointRange& points, /// \tparam PointRange a model of the concepts `SequenceContainer` and `Swappable` /// whose value type is the point type. /// \tparam PolygonRange a model of the concept `RandomAccessContainer` -/// whose value_type is itself a model of the concept `RandomAccessContainer` -/// whose value_type is `std::size_t`. +/// whose `value_type` is itself a model of the concept `RandomAccessContainer` +/// whose `value_type` is `std::size_t`. /// \tparam NamedParameters a sequence of \ref bgl_namedparameters "Named Parameters" /// /// \param points points of the soup of polygons. @@ -800,8 +800,8 @@ struct Duplicate_collector // // \tparam PointRange a model of the concept `RandomAccessContainer` whose value type is the point type. // \tparam PolygonRange a model of the concept `RandomAccessContainer` -// whose value_type is itself a model of the concepts `RandomAccessContainer` -// and `ReversibleContainer` whose value_type is `std::size_t`. +// whose `value_type` is itself a model of the concepts `RandomAccessContainer` +// and `ReversibleContainer` whose `value_type` is `std::size_t`. // \tparam DuplicateOutputIterator a model of `OutputIterator` with value type // `std::vector >`. // @@ -878,8 +878,8 @@ DuplicateOutputIterator collect_duplicate_polygons(const PointRange& points, /// /// \tparam PointRange a model of the concept `RandomAccessContainer` whose value type is the point type. /// \tparam PolygonRange a model of the concept `SequenceContainer` -/// whose value_type is itself a model of the concepts `RandomAccessContainer` -/// and `ReversibleContainer` whose value_type is `std::size_t`. +/// whose `value_type` is itself a model of the concepts `RandomAccessContainer` +/// and `ReversibleContainer` whose `value_type` is `std::size_t`. /// \tparam NamedParameters a sequence of \ref bgl_namedparameters "Named Parameters" /// /// \param points points of the soup of polygons. @@ -1042,8 +1042,8 @@ std::size_t merge_duplicate_polygons_in_polygon_soup(PointRange& points, /// \tparam PointRange a model of the concepts `SequenceContainer` and `Swappable` /// and whose value type is the point type. /// \tparam PolygonRange a model of the concept `SequenceContainer`. -/// whose value_type is itself a model of the concepts `SequenceContainer`, -/// `Swappable`, and `ReversibleContainer` whose value_type is `std::size_t`. +/// whose `value_type` is itself a model of the concepts `SequenceContainer`, +/// `Swappable`, and `ReversibleContainer` whose `value_type` is `std::size_t`. /// \tparam NamedParameters a sequence of \ref bgl_namedparameters "Named Parameters" /// /// \param points points of the soup of polygons. diff --git a/Polyhedron/doc/Polyhedron/CGAL/IO/Polyhedron_iostream.h b/Polyhedron/doc/Polyhedron/CGAL/IO/Polyhedron_iostream.h index ee2def4101b..55adea20854 100644 --- a/Polyhedron/doc/Polyhedron/CGAL/IO/Polyhedron_iostream.h +++ b/Polyhedron/doc/Polyhedron/CGAL/IO/Polyhedron_iostream.h @@ -4,9 +4,8 @@ namespace CGAL { \relates Polyhedron_3 \ingroup PkgPolyhedronIOFunc -This function reads a polyhedral surface in %Object File Format, OFF, -with file extension .off, which is also understood by -Geomview \cgalCite{cgal:p-gmgv16-96}, from the input stream `in` and +reads a polyhedral surface in %Object File Format, OFF, +with file extension .off, from the input stream `in` and appends it to the polyhedral surface \f$ P\f$. Only the point coordinates and facets from the input stream are used to build the polyhedral surface. Neither normal vectors nor color attributes are evaluated. @@ -18,7 +17,8 @@ format automatically and can read both. \sa `CGAL::Polyhedron_incremental_builder_3` \sa \link PkgPolyhedronIOFunc `operator<<(std::ostream&, Polyhedron_3&)`\endlink -This function overloads the generic function \link PkgBGLIoFuncsOFF `read_OFF(std::istream&, FaceGraph)`\endlink. +This function overloads the generic function \link PkgBGLIoFuncsOFF `read_OFF(std::istream&, FaceGraph)`\endlink +(if no named parameters are used). \cgalHeading{Implementation} @@ -28,9 +28,8 @@ class, which allows the construction in a single, efficient scan pass of the input and handles also all the possible flexibility of the polyhedral surface. -\note Before \cgal 5.0 this function has set the `ios::badbit` of the input stream `in` -when the file contained 0 vertices. - +\note Starting with \cgal 5.2, this function will no longer set the `ios::badbit` + of the input stream `in` if the file contains 0 vertices. */ template bool read_OFF( std::istream& in, Polyhedron_3& P); @@ -55,10 +54,9 @@ std::istream& operator>>( std::istream& in, Polyhedron_3& P) \relates Polyhedron_3 \ingroup PkgPolyhedronIOFunc -This function writes the polyhedral surface \f$P\f$ to the output +writes the polyhedral surface \f$P\f$ to the output stream `out` using the %Object File Format, OFF, with file extension -.off, which is also understood by GeomView \cgalCite{cgal:p-gmgv16-96}. The -output is in ASCII format. From the polyhedral surface, only the point +.off. The output is in ASCII format. From the polyhedral surface, only the point coordinates and facets are written. Neither normal vectors nor color attributes are used. @@ -69,7 +67,8 @@ to allow for (a few) structuring comments in the output. Otherwise, the output would be free of comments. The default for writing is ASCII without comments. -This function overloads the generic function \link PkgBGLIoFuncsOFF `write_OFF(std::istream&,FaceGraph)` \endlink. +This function overloads the generic function \link PkgBGLIoFuncsOFF `write_OFF(std::istream&,FaceGraph)` \endlink +(if no named parameters are used). \sa `CGAL::Polyhedron_3` \sa `CGAL::Polyhedron_incremental_builder_3` diff --git a/Polyhedron/doc/Polyhedron/PackageDescription.txt b/Polyhedron/doc/Polyhedron/PackageDescription.txt index 505deede94f..827683c7918 100644 --- a/Polyhedron/doc/Polyhedron/PackageDescription.txt +++ b/Polyhedron/doc/Polyhedron/PackageDescription.txt @@ -66,7 +66,7 @@ surface can be used without knowing the halfedge data structure. - `CGAL::Polyhedron_min_items_3` - `CGAL::Polyhedron_incremental_builder_3` -\cgalCRPSection{Functions} +\cgalCRPSection{I/O Functions} - \link PkgPolyhedronIOFunc `CGAL::operator<<()` \endlink - \link PkgPolyhedronIOFunc `CGAL::operator>>()` \endlink - \link PkgPolyhedronIOFunc `write_OFF()` \endlink diff --git a/Polyhedron/doc/Polyhedron/Polyhedron.txt b/Polyhedron/doc/Polyhedron/Polyhedron.txt index 2d50d686717..ff1b4df6ec8 100644 --- a/Polyhedron/doc/Polyhedron/Polyhedron.txt +++ b/Polyhedron/doc/Polyhedron/Polyhedron.txt @@ -292,14 +292,12 @@ Result of the run of the draw_polyhedron program. A window shows the polyhedron \anchor sectionPolyIO -Simple file I/O for polyhedral surfaces is already provided in the -library. The file I/O considers so far only the topology of the +The file I/O currently considers only the topology of the surface and its point coordinates. It ignores a possible plane equation or any user-added attributes, such as color. The default file format supported in \cgal for output as well as for -input is the \ref IOStreamOFF, with file extension .off, -which is also understood by Geomview \cgalCite{cgal:p-gmgv16-96}. +input is the \ref IOStreamOFF, with file extension .off. The modifier `set_pretty_mode()` can be used to allow for (a few) structuring comments in the output. Otherwise, the output would be free of comments. The default for writing is without comments. Since this file format is the default format, iostream operators are provided for it. @@ -503,8 +501,7 @@ illustrating further the design of the halfedge data structure. This program reads a polyhedral surface from the standard input and writes a refined polyhedral surface to the standard output. Input and output are in the %Object File Format, OFF, with the common file -extension .off, which is also understood by -Geomview \cgalCite{cgal:p-gmgv16-96}. +extension .off. The refinement is a single step of the \f$ \sqrt{3}\f$-scheme for creating a subdivision surface \cgalCite{cgal:k-s-00}. Each step subdivides a facet diff --git a/STL_Extension/doc/STL_Extension/STL_Extension.txt b/STL_Extension/doc/STL_Extension/STL_Extension.txt index f2f1912f13a..0886b18cf7b 100644 --- a/STL_Extension/doc/STL_Extension/STL_Extension.txt +++ b/STL_Extension/doc/STL_Extension/STL_Extension.txt @@ -264,7 +264,7 @@ example. Note that the setting of the standard macro `NDEBUG` sets `CGAL_NDEBUG`, unless `CGAL_DEBUG` is also defined. If both `NDEBUG` and `CGAL_DEBUG` are -defined, then the the standard `assert` macro is disabled, but not the CGAL +defined, then the standard `assert` macro is disabled, but not the CGAL assertions and preconditions. Not all checks are on by default. diff --git a/STL_Extension/include/CGAL/Handle_with_policy.h b/STL_Extension/include/CGAL/Handle_with_policy.h index 0fa9dedbd18..ca34fff19cf 100644 --- a/STL_Extension/include/CGAL/Handle_with_policy.h +++ b/STL_Extension/include/CGAL/Handle_with_policy.h @@ -851,7 +851,7 @@ protected: //! constructor used for class hierarchies of representations, where //! the handle class derived from this handle creates the different //! representations itself with the \c new operator. Except for this - //! constructor, the the one with the \c Use_with_initialize_with + //! constructor, the one with the \c Use_with_initialize_with //! argument, and the single argument template constructor no other //! constructor will work for class hierarchies of representations. Handle_with_policy( Rep* p) : ptr_( p) { diff --git a/Stream_support/doc/Stream_support/File_formats/Supported_file_formats.txt b/Stream_support/doc/Stream_support/File_formats/Supported_file_formats.txt index 3c167055fc0..4bebf42577b 100644 --- a/Stream_support/doc/Stream_support/File_formats/Supported_file_formats.txt +++ b/Stream_support/doc/Stream_support/File_formats/Supported_file_formats.txt @@ -5,7 +5,7 @@ \cgal provides a large number of data structures and algorithms dedicated to various applications. This page lists the various supported file formats and the data structures offered by \cgal that may be used to read and write files of -this specific format. +each specific format. - \ref IOStreamOFF - \ref IOStreamOBJ @@ -188,9 +188,9 @@ which offers combinatorial repairing while reading bad inputs. \section IOStreamPLY Polygon File Format (PLY) -Conceived to store the data obtained during 3D scans, the `PLY` file format stores objects -as a simple list of polygons and is capable of storing external properties. -It uses the file extension `.ply`. +The `PLY` file format, using the file extension `.ply`, is an ASCII or binary format +conceived to store the data obtained during 3D scans. Objects are stored +as a simple list of polygons and external properties can be stored. A precise specification of those formats is available here. @@ -380,7 +380,7 @@ A precise specification of the format is available at Input Polygon Mesh `CGAL::Surface_mesh` - \link PkgSurfaceMeshIOFunc3MF CGAL::read_3MF(const char*, CGAL::Surface_mesh&)\endlink + \link PkgSurfaceMeshIOFunc3MF CGAL::read_3MF(const char*, Surface_meshRange&)\endlink Polygon Soup @@ -388,12 +388,8 @@ A precise specification of the format is available at Output - Polygon Mesh - `CGAL::Surface_mesh` - \link PkgSurfaceMeshIOFunc3MF CGAL::read_3MF(const char*, CGAL::Surface_mesh&)\endlink - - + Output + Polygon Mesh Any model of `FaceGraph` \link PkgBGLIoFuncs3MF CGAL::write_3MF(const char*, GraphRange&)\endlink @@ -411,11 +407,9 @@ which offers combinatorial repairing while reading bad inputs. \section IOStreamWRL Virtual Reality Modeling Language (VRML) File Format -File format often used by browser plug-ins to display virtual reality environments. -VRML files are known as “worlds,” which is what WRL stands for. -WRL files are plain ASCII text files. -A WRL file includes data specifying 3-D details such as vertices, -edges for a 3-D polygon, surface color, ... +The `VRML` format, using the file extension `.wrl`, is an ASCII format often used by browser plug-ins +to display virtual reality environments. VRML files are known as “worlds,” which is what "WRL" stands for. +A WRL file includes data specifying 3-D details such as vertices, edges for a 3-D polygon, surface color, ... A precise specification of the format is available here. @@ -427,10 +421,10 @@ using the function \link PkgBGLIoFuncsWRL `CGAL::write_WRL()` \endlink. \attention \cgal needs to be configured with the VTK Libraries for this function to be available. The VTK libraries use different file formats to handle data structures, but we only support two: -- The `VTU` format can be used to store am unordered collection of 3D cells, like tetrahedra, +- The `VTU` format can be used to store a collection of 3D cells, like tetrahedra, but also points, triangles, lines, etc. In the VTK Libraries, it is the format reserved to store `Unstructured Grids`, and in \cgal, - we use it to store triangulations(2D and 3D). + we use it to store triangulations (2D and 3D). - The `VTP` format can be used to store collections of points, lines, and triangles. In the VTK Libraries, it is the format @@ -475,21 +469,23 @@ The following \cgal data structures can be exported into the `.VTU` file format: \section IOStreamAvizo Avizo File Format -The `.am` files are used by Avizo to read 3D geometry. +The AmiraMesh format, using file extension `.am`, is used +by the Avizo software to read 3D geometry. -Only the `CGAL::Mesh_complex_3_in_triangulation_3` \cgal data structure can be exported into `.am` files. -This can be done using the function \ref CGAL::output_to_avizo(). +A single \cgal data structure, `CGAL::Mesh_complex_3_in_triangulation_3`, can be exported into `.am` files. +This can be done using the function `CGAL::output_to_avizo()`. \section IOStreamMedit Medit File Format -The `.mesh` Medit file format is a format used by the Medit software. In \cgal, -it is mostly used to represent 3D meshes. +The Medit format, using file extension `.mesh`, is a format used by the Medit software. +In \cgal, it is used to represent 3D meshes. + A precise specification of the format is available in this report, in the appendices (section 7.2.1, page 36). Only the `CGAL::Mesh_complex_3_in_triangulation_3` \cgal data structure can be exported into `.mesh` -This can be done using the function \ref CGAL::output_to_medit() +This can be done using the function `CGAL::output_to_medit()`. \section IOStreamTetgen Tetgen File Format @@ -499,14 +495,15 @@ A precise specification of the format is available at wikipedia page for details. +The `WKT` format, using the file extension `.wkt`, is a text markup language for representing +vector geometry objects on a geographical map. -See Section \ref IOstreamWKT for a list of available structures. +A precise specification of the format is available on wikipedia. + +See Section \ref IOstream2DGeo for a list of available functions. */ diff --git a/Stream_support/doc/Stream_support/IOstream.txt b/Stream_support/doc/Stream_support/IOstream.txt index 301be64abbe..7df3e7353e3 100644 --- a/Stream_support/doc/Stream_support/IOstream.txt +++ b/Stream_support/doc/Stream_support/IOstream.txt @@ -450,7 +450,7 @@ If this is not the case, the package \ref PkgPolygonMeshProcessing offers the fu \link PMP_IO_grp `CGAL::Polygon_mesh_processing::read_polygon_mesh()` \endlink which can perform some combinatorial repairing to ensure the input data is a 2-manifold. -\subsection IOstreamWKT Simple 2D Geometry IO +\subsection IOstream2DGeo Simple 2D Geometry IO `WKT` stands for Well-Known Text and it is a text markup language for representing vector geometry objects on a geographical map. See the wikipedia page for details. diff --git a/Stream_support/include/CGAL/IO/3MF.h b/Stream_support/include/CGAL/IO/3MF.h index cfb26f38654..09edbec98f6 100644 --- a/Stream_support/include/CGAL/IO/3MF.h +++ b/Stream_support/include/CGAL/IO/3MF.h @@ -389,7 +389,7 @@ bool read_3MF(const std::string& fname, * \tparam TriangleRanges a model of the concept `RandomAccessContainer` whose * `value_type` is a model of the concept `RandomAccessContainer` * whose `value_type` is a model of the concept `RandomAccessContainer` whose - * `value_type` is an integer type. + * `value_type` is an unsigned integer type convertible to `std::size_t`. * \tparam ColorRanges a model of the concepts `RandomAccessContainer` and * `BackInsertionSequence` whose `value_type` is * a model of the concepts `RandomAccessContainer` and `BackInsertionSequence` @@ -439,7 +439,7 @@ int read_3MF(const std::string& fname, * \tparam TriangleRanges a model of the concept `RandomAccessContainer` whose * `value_type` is a model of the concept `RandomAccessContainer` * whose `value_type` is a model of the concept `RandomAccessContainer` whose - * `value_type` is an integer type. + * `value_type` is an unsigned integer type convertible to `std::size_t`. * * \param fname the name of the 3mf file to write * \param all_points a `PointRanges` that contains the points of the soups to write diff --git a/Stream_support/include/CGAL/IO/GOCAD.h b/Stream_support/include/CGAL/IO/GOCAD.h index 498113e0bbb..9caf43c6fe9 100644 --- a/Stream_support/include/CGAL/IO/GOCAD.h +++ b/Stream_support/include/CGAL/IO/GOCAD.h @@ -162,8 +162,8 @@ bool read_GOCAD(std::istream& is, * * \tparam PointRange a model of the concept `RandomAccessContainer` whose value type is the point type. * \tparam PolygonRange a model of the concept `SequenceContainer` - * whose value_type is itself a model of the concept `SequenceContainer` - * whose value_type is an integer type. + * whose `value_type` is itself a model of the concept `SequenceContainer` + * whose `value_type` is an unsigned integer type convertible to `std::size_t`. * \tparam NamedParameters a sequence of \ref bgl_namedparameters "Named Parameters" * * \param is the input stream @@ -215,8 +215,8 @@ bool read_GOCAD(std::istream& is, PointRange& points, PolygonRange& polygons, * * \tparam PointRange a model of the concept `RandomAccessContainer` whose value type is the point type. * \tparam PolygonRange a model of the concept `SequenceContainer` - * whose value_type is itself a model of the concept `SequenceContainer` - * whose value_type is an integer type. + * whose `value_type` is itself a model of the concept `SequenceContainer` + * whose `value_type` is an unsigned integer type convertible to `std::size_t`. * \tparam NamedParameters a sequence of \ref bgl_namedparameters "Named Parameters" * * \param fname the path to the input file @@ -349,8 +349,8 @@ bool write_GOCAD(std::ostream& os, * * \tparam PointRange a model of the concept `RandomAccessContainer` whose value type is the point type. * \tparam PolygonRange a model of the concept `SequenceContainer` - * whose value_type is itself a model of the concept `SequenceContainer` - * whose value_type is an integer type. + * whose `value_type` is itself a model of the concept `SequenceContainer` + * whose `value_type` is an unsigned integer type convertible to `std::size_t`. * \tparam NamedParameters a sequence of \ref bgl_namedparameters "Named Parameters" * * \param os the output stream @@ -402,8 +402,8 @@ bool write_GOCAD(std::ostream& os, const PointRange& points, const PolygonRange& * * \tparam PointRange a model of the concept `RandomAccessContainer` whose value type is the point type. * \tparam PolygonRange a model of the concept `SequenceContainer` - * whose value_type is itself a model of the concept `SequenceContainer` - * whose value_type is an integer type. + * whose `value_type` is itself a model of the concept `SequenceContainer` + * whose `value_type` is an unsigned integer type convertible to `std::size_t`. * \tparam NamedParameters a sequence of \ref bgl_namedparameters "Named Parameters" * * \param fname the path to the output file diff --git a/Stream_support/include/CGAL/IO/OBJ.h b/Stream_support/include/CGAL/IO/OBJ.h index 958776950d3..ed3d2505522 100644 --- a/Stream_support/include/CGAL/IO/OBJ.h +++ b/Stream_support/include/CGAL/IO/OBJ.h @@ -192,8 +192,8 @@ bool read_OBJ(std::istream& is, /// /// \tparam PointRange a model of the concept `RandomAccessContainer` whose value type is the point type. /// \tparam PolygonRange a model of the concept `SequenceContainer` -/// whose value_type is itself a model of the concept `SequenceContainer` -/// whose value_type is an integer type. +/// whose `value_type` is itself a model of the concept `SequenceContainer` +/// whose `value_type` is an unsigned integer type convertible to `std::size_t`. /// \tparam NamedParameters a sequence of \ref bgl_namedparameters "Named Parameters" /// /// \param is the input stream @@ -245,8 +245,8 @@ bool read_OBJ(std::istream& is, PointRange& points, PolygonRange& polygons, /// /// \tparam PointRange a model of the concept `RandomAccessContainer` whose value type is the point type. /// \tparam PolygonRange a model of the concept `SequenceContainer` -/// whose value_type is itself a model of the concept `SequenceContainer` -/// whose value_type is an integer type. +/// whose `value_type` is itself a model of the concept `SequenceContainer` +/// whose `value_type` is an unsigned integer type convertible to `std::size_t`. /// \tparam NamedParameters a sequence of \ref bgl_namedparameters "Named Parameters" /// /// \param fname the path to the input file @@ -315,8 +315,8 @@ bool read_OBJ(const std::string& fname, PointRange& points, PolygonRange& polygo * * \tparam PointRange a model of the concept `RandomAccessContainer` whose value type is the point type. * \tparam PolygonRange a model of the concept `SequenceContainer` - * whose value_type is itself a model of the concept `SequenceContainer` - * whose value_type is an integer type. + * whose `value_type` is itself a model of the concept `SequenceContainer` + * whose `value_type` is an unsigned integer type convertible to `std::size_t`. * \tparam NamedParameters a sequence of \ref bgl_namedparameters "Named Parameters" * * \param os the output stream @@ -370,8 +370,8 @@ bool write_OBJ(std::ostream& os, const PointRange& points, const PolygonRange& p * * \tparam PointRange a model of the concept `RandomAccessContainer` whose value type is the point type. * \tparam PolygonRange a model of the concept `SequenceContainer` - * whose value_type is itself a model of the concept `SequenceContainer` - * whose value_type is an integer type. + * whose `value_type` is itself a model of the concept `SequenceContainer` + * whose `value_type` is an unsigned integer type convertible to `std::size_t`. * \tparam NamedParameters a sequence of \ref bgl_namedparameters "Named Parameters" * * \param fname the path to the output file diff --git a/Stream_support/include/CGAL/IO/OFF.h b/Stream_support/include/CGAL/IO/OFF.h index f7808dacf58..4ae4a076f50 100644 --- a/Stream_support/include/CGAL/IO/OFF.h +++ b/Stream_support/include/CGAL/IO/OFF.h @@ -171,8 +171,8 @@ bool read_OFF(std::istream& is, * * \tparam PointRange a model of the concept `RandomAccessContainer` whose value type is the point type. * \tparam PolygonRange a model of the concept `SequenceContainer` - * whose value_type is itself a model of the concept `SequenceContainer` - * whose value_type is an integer type. + * whose `value_type` is itself a model of the concept `SequenceContainer` + * whose `value_type` is an unsigned integer type convertible to `std::size_t`. * \tparam NamedParameters a sequence of \ref bgl_namedparameters "Named Parameters" * * \param is the input stream @@ -234,8 +234,8 @@ bool read_OFF(std::istream& is, PointRange& points, PolygonRange& polygons, * * \tparam PointRange a model of the concept `RandomAccessContainer` whose value type is the point type. * \tparam PolygonRange a model of the concept `SequenceContainer` - * whose value_type is itself a model of the concept `SequenceContainer` - * whose value_type is an integer type. + * whose `value_type` is itself a model of the concept `SequenceContainer` + * whose `value_type` is an unsigned integer type convertible to `std::size_t`. * \tparam NamedParameters a sequence of \ref bgl_namedparameters "Named Parameters" * * \param fname the path to the input file @@ -304,8 +304,8 @@ bool read_OFF(const std::string& fname, PointRange& points, PolygonRange& polygo * * \tparam PointRange a model of the concept `RandomAccessContainer` whose value type is the point type. * \tparam PolygonRange a model of the concept `SequenceContainer` - * whose value_type is itself a model of the concept `SequenceContainer` - * whose value_type is an integer type. + * whose `value_type` is itself a model of the concept `SequenceContainer` + * whose `value_type` is an unsigned integer type convertible to `std::size_t`. * \tparam NamedParameters a sequence of \ref bgl_namedparameters "Named Parameters" * * \param os the output stream @@ -356,8 +356,8 @@ bool write_OFF(std::ostream& os, const PointRange& points, const PolygonRange& p * * \tparam PointRange a model of the concept `RandomAccessContainer` whose value type is the point type. * \tparam PolygonRange a model of the concept `SequenceContainer` - * whose value_type is itself a model of the concept `SequenceContainer` - * whose value_type is an integer type. + * whose `value_type` is itself a model of the concept `SequenceContainer` + * whose `value_type` is an unsigned integer type convertible to `std::size_t`. * \tparam NamedParameters a sequence of \ref bgl_namedparameters "Named Parameters" * * \param fname the path to the output file diff --git a/Stream_support/include/CGAL/IO/PLY.h b/Stream_support/include/CGAL/IO/PLY.h index a7568515b04..830bdf4db6d 100644 --- a/Stream_support/include/CGAL/IO/PLY.h +++ b/Stream_support/include/CGAL/IO/PLY.h @@ -278,8 +278,8 @@ bool read_PLY(std::istream& is, * * \tparam PointRange a model of the concept `RandomAccessContainer` whose value type is the point type. * \tparam PolygonRange a model of the concept `SequenceContainer` - * whose value_type is itself a model of the concept `SequenceContainer` - * whose value_type is an integer type. + * whose `value_type` is itself a model of the concept `SequenceContainer` + * whose `value_type` is an unsigned integer type convertible to `std::size_t`. * \tparam NamedParameters a sequence of \ref bgl_namedparameters "Named Parameters" * * \param is the input stream @@ -347,8 +347,8 @@ bool read_PLY(std::istream& is, PointRange& points, PolygonRange& polygons, * * \tparam PointRange a model of the concept `RandomAccessContainer` whose value type is the point type. * \tparam PolygonRange a model of the concept `SequenceContainer` - * whose value_type is itself a model of the concept `SequenceContainer` - * whose value_type is an integer type + * whose `value_type` is itself a model of the concept `SequenceContainer` + * whose `value_type` is an integer type * \tparam NamedParameters a sequence of \ref bgl_namedparameters "Named Parameters" * * \param fname the path to the input file @@ -438,8 +438,8 @@ bool read_PLY(const std::string& fname, PointRange& points, PolygonRange& polygo * * \tparam PointRange a model of the concept `RandomAccessContainer` whose value type is the point type. * \tparam PolygonRange a model of the concept `SequenceContainer` - * whose value_type is itself a model of the concept `SequenceContainer` - * whose value_type is an integer type. + * whose `value_type` is itself a model of the concept `SequenceContainer` + * whose `value_type` is an unsigned integer type convertible to `std::size_t`. * \tparam NamedParameters a sequence of \ref bgl_namedparameters "Named Parameters" * * \param out the output stream @@ -522,8 +522,8 @@ bool write_PLY(std::ostream& out, const PointRange& points, const PolygonRange& * * \tparam PointRange a model of the concept `RandomAccessContainer` whose value type is the point type. * \tparam PolygonRange a model of the concept `SequenceContainer` - * whose value_type is itself a model of the concept `SequenceContainer` - * whose value_type is an integer type. + * whose `value_type` is itself a model of the concept `SequenceContainer` + * whose `value_type` is an unsigned integer type convertible to `std::size_t`. * \tparam NamedParameters a sequence of \ref bgl_namedparameters "Named Parameters" * * \param fname the path to the output file diff --git a/Stream_support/include/CGAL/IO/STL.h b/Stream_support/include/CGAL/IO/STL.h index a506aa1886d..43bbb0ea382 100644 --- a/Stream_support/include/CGAL/IO/STL.h +++ b/Stream_support/include/CGAL/IO/STL.h @@ -49,14 +49,13 @@ namespace CGAL { * * \tparam PointRange a model of the concept `RandomAccessContainer` whose value type is the point type. * \tparam TriangleRange a model of the concept `SequenceContainer` - * whose value_type is itself a model of the concept `SequenceContainer` - * whose value_type is an integer type. + * whose `value_type` is itself a model of the concept `SequenceContainer` + * whose `value_type` is an unsigned integer type convertible to `std::size_t`. * \tparam NamedParameters a sequence of \ref bgl_namedparameters "Named Parameters" * * \param is the input stream * \param points points of the soup of triangles - * \param facets a `TriangleRange`. Each element in it describes a triangle - * using the indices of the points in `points`. + * \param facets a range of triangles; each triangle uses the indices of the points in `points`. * \param np optional \ref bgl_namedparameters "Named Parameters" described below * * \cgalNamedParamsBegin @@ -181,14 +180,13 @@ bool read_STL(std::istream& is, PointRange& points, TriangleRange& facets, * * \tparam PointRange a model of the concept `RandomAccessContainer` whose value type is the point type. * \tparam TriangleRange a model of the concept `SequenceContainer` - * whose value_type is itself a model of the concept `SequenceContainer` - * whose value_type is an integer type. + * whose `value_type` is itself a model of the concept `SequenceContainer` + * whose `value_type` is an unsigned integer type convertible to `std::size_t`. * \tparam NamedParameters a sequence of \ref bgl_namedparameters "Named Parameters" * * \param fname the path to the input file * \param points points of the soup of triangles - * \param facets a `TriangleRange`. Each element in it describes a triangle - * using the indices of the points in `points`. + * \param facets a range of triangles; each triangle uses the indices of the points in `points`. * \param np optional \ref bgl_namedparameters "Named Parameters" described below * * \cgalNamedParamsBegin @@ -208,8 +206,11 @@ bool read_STL(std::istream& is, PointRange& points, TriangleRange& facets, * \returns `true` if the reading was successful, `false` otherwise. */ template -bool read_STL(const char* fname, PointRange& points, TriangleRange& facets, const CGAL_BGL_NP_CLASS& np, - typename boost::enable_if >::type* = nullptr) +bool read_STL(const char* fname, PointRange& points, TriangleRange& facets, const CGAL_BGL_NP_CLASS& np +#ifndef DOXYGEN_RUNNING + , typename boost::enable_if >::type* = nullptr +#endif + ) { const bool binary = parameters::choose_parameter(parameters::get_parameter(np, internal_np::use_binary_mode), true); if(binary) @@ -264,14 +265,13 @@ bool read_STL(const std::string& fname, PointRange& points, TriangleRange& facet * * \tparam PointRange a model of the concept `RandomAccessContainer` whose value type is the point type. * \tparam TriangleRange a model of the concept `SequenceContainer` - * whose value_type is itself a model of the concept `SequenceContainer` - * whose value_type is an integer type. + * whose `value_type` is itself a model of the concept `SequenceContainer` + * whose `value_type` is an unsigned integer type convertible to `std::size_t`. * \tparam NamedParameters a sequence of \ref bgl_namedparameters "Named Parameters" * * \param os the output stream * \param points points of the soup of triangles - * \param facets a `TriangleRange`. Each element in it describes a triangle - * using the indices of the points in `points`. + * \param facets a range of triangles; each triangle uses the indices of the points in `points`. * \param np optional sequence of \ref bgl_namedparameters "Named Parameters" among the ones listed below * * \cgalNamedParamsBegin @@ -377,14 +377,13 @@ bool write_STL(std::ostream& os, const PointRange& points, const TriangleRange& * * \tparam PointRange a model of the concept `RandomAccessContainer` whose value type is the point type. * \tparam TriangleRange a model of the concept `SequenceContainer` - * whose value_type is itself a model of the concept `SequenceContainer` - * whose value_type is an integer type. + * whose `value_type` is itself a model of the concept `SequenceContainer` + * whose `value_type` is an unsigned integer type convertible to `std::size_t`. * \tparam NamedParameters a sequence of \ref bgl_namedparameters "Named Parameters" * * \param fname the path to the output file * \param points points of the soup of triangles - * \param facets a `TriangleRange`. Each element in it describes a triangle - * using the indices of the points in `points`. + * \param facets a range of triangles; each triangle uses the indices of the points in `points`. * \param np optional sequence of \ref bgl_namedparameters "Named Parameters" among the ones listed below * * \cgalNamedParamsBegin diff --git a/Stream_support/include/CGAL/IO/VTK.h b/Stream_support/include/CGAL/IO/VTK.h index 2788fe7bc79..9d54bc5cdc1 100644 --- a/Stream_support/include/CGAL/IO/VTK.h +++ b/Stream_support/include/CGAL/IO/VTK.h @@ -127,8 +127,8 @@ bool read_VTP(const char* fname, * * \tparam PointRange a model of the concept `RandomAccessContainer` whose value type is the point type. * \tparam PolygonRange a model of the concept `SequenceContainer` - * whose value_type is itself a model of the concept `SequenceContainer` - * whose value_type is an integer type. + * whose `value_type` is itself a model of the concept `SequenceContainer` + * whose `value_type` is an unsigned integer type convertible to `std::size_t`. * * \param fname the path to the input file * \param points points of the soup of polygons. @@ -362,8 +362,8 @@ void write_soup_polys_points(std::ostream& os, * * \tparam PointRange a model of the concept `RandomAccessContainer` whose value type is the point type. * \tparam PolygonRange a model of the concept `SequenceContainer` - * whose value_type is itself a model of the concept `SequenceContainer` - * whose value_type is an integer type. + * whose `value_type` is itself a model of the concept `SequenceContainer` + * whose `value_type` is an unsigned integer type convertible to `std::size_t`. * \tparam NamedParameters a sequence of \ref bgl_namedparameters "Named Parameters" * * \param os the output stream @@ -461,8 +461,8 @@ bool write_VTP(std::ostream& os, const PointRange& points, const PolygonRange& p * * \tparam PointRange a model of the concept `RandomAccessContainer` whose value type is the point type. * \tparam PolygonRange a model of the concept `SequenceContainer` - * whose value_type is itself a model of the concept `SequenceContainer` - * whose value_type is an integer type. + * whose `value_type` is itself a model of the concept `SequenceContainer` + * whose `value_type` is an unsigned integer type convertible to `std::size_t`. * \tparam NamedParameters a sequence of \ref bgl_namedparameters "Named Parameters" * * \param fname the path to the output file diff --git a/Stream_support/include/CGAL/IO/polygon_soup_io.h b/Stream_support/include/CGAL/IO/polygon_soup_io.h index 3cb03ffe49f..c443d4bae78 100644 --- a/Stream_support/include/CGAL/IO/polygon_soup_io.h +++ b/Stream_support/include/CGAL/IO/polygon_soup_io.h @@ -103,8 +103,8 @@ bool read_polygon_soup(const std::string& fname, PointRange& points, PolygonRang * The format is detected from the filename extension (letter case is not important). * * \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`. + * whose `value_type` is a model of the concept `RandomAccessContainer` + * whose `value_type` is `std::size_t`. * \tparam PointRange a model of the concept `RandomAccessContainer` whose value type is the point type * \tparam NamedParameters a sequence of \ref bgl_namedparameters "Named Parameters" * @@ -214,8 +214,8 @@ bool write_polygon_soup(const std::string& fname, PointRange& points, PolygonRan * The format is detected from the filename extension (letter case is not important). * * \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`. + * whose `value_type` is a model of the concept `RandomAccessContainer` + * whose `value_type` is `std::size_t`. * \tparam PointRange a model of the concept `RandomAccessContainer` whose value type is the point type * \tparam NamedParameters a sequence of \ref bgl_namedparameters "Named Parameters" * diff --git a/Surface_mesh/doc/Surface_mesh/Surface_mesh.txt b/Surface_mesh/doc/Surface_mesh/Surface_mesh.txt index 297f88b300d..0b9c670d85e 100644 --- a/Surface_mesh/doc/Surface_mesh/Surface_mesh.txt +++ b/Surface_mesh/doc/Surface_mesh/Surface_mesh.txt @@ -314,12 +314,12 @@ this boils down to an identity function as vertices \em are indices. \section sectionSurfaceMesh_IO Surface Mesh I/O As a model of `FaceGraph` (see Section \ref sectionSurfaceMesh_BGL), `CGAL::Surface_mesh` -can be read from and written to files using a number of different file formats. Refer to +can be read from and written using a number of different file formats. Refer to the \ref PkgBGLIOFct of the \ref PkgBGL package, and the \ref PMP_IO_grp of the \ref PkgPolygonMeshProcessing package for more information. -In addition, this package provides overloads of these I/O functions specific to `CGAL::Surface_mesh` -to read and write directly from/to internal property maps, +In addition, this package provides `Surface_mesh`-specific overloads of the I/O functions +from the \ref PkgBGL package. This enables reading/writing directly from/to internal property maps, see \ref PkgSurfaceMeshIOFunc for more information. \section sectionSurfaceMesh_memory Memory Management diff --git a/Surface_mesh/include/CGAL/Surface_mesh/IO/OFF.h b/Surface_mesh/include/CGAL/Surface_mesh/IO/OFF.h index 9661d813982..fcc3850f7d8 100644 --- a/Surface_mesh/include/CGAL/Surface_mesh/IO/OFF.h +++ b/Surface_mesh/include/CGAL/Surface_mesh/IO/OFF.h @@ -261,8 +261,8 @@ bool read_OFF_with_or_without_vnormals(std::istream& is, /// \brief extracts the surface mesh from an input stream in the \ref IOStreamOFF /// and appends it to the surface mesh `sm`. /// -/// This function reads the point property as well as vertex normals, vertex and face colors, -/// and texture vertex coordinates. Those properties are stored in internal property maps +/// This function reads points as well as vertex normals, vertex and face colors, +/// and texture vertex coordinates. Those last four attributes are stored in internal property maps /// named "v:normal", "v:color", "f:color", and `"v:texcoord"`, respectively. /// If property maps are passed through named parameters (see below), /// then they are used instead of the internal ones. @@ -283,39 +283,41 @@ bool read_OFF_with_or_without_vnormals(std::istream& is, /// \cgalNamedParamsBegin /// \cgalParamNBegin{vertex_point_map} /// \cgalParamDescription{a property map associating points to the vertices of `sm`} -/// \cgalParamType{a class model of `ReadWritePropertyMap` with `Surface_mesh::Vertex_index` -/// as key type and `%Point_3` as value type} +/// \cgalParamType{a class model of `WritablePropertyMap` with `Surface_mesh::Vertex_index` +/// as key type and `Point` as value type} /// \cgalParamDefault{`boost::get(CGAL::vertex_point, g)`} -/// \cgalParamExtra{If this parameter is omitted, an internal property map for `CGAL::vertex_point_t` -/// must be available in `sm`.} /// \cgalParamNEnd /// /// \cgalParamNBegin{vertex_normal_map} /// \cgalParamDescription{a property map associating normals to the vertices of `sm`} -/// \cgalParamType{a class model of `ReadWritePropertyMap` with `Surface_mesh::Vertex_index` -/// as key type and `%Vector_3` as value type} -/// \cgalParamDefault{vertex normals will be output using the internal property map, if it exists} +/// \cgalParamType{a class model of `WritablePropertyMap` with `Surface_mesh::Vertex_index` +/// as key type and a 3D vector type issued from the same kernel as `Point` as value type} +/// \cgalParamDefault{If this parameter is unsused, vertex normals (if they exist) +/// will be written in an internal property map called `v:normal`.} /// \cgalParamNEnd /// /// \cgalParamNBegin{vertex_color_map} /// \cgalParamDescription{a property map associating colors to the vertices of `sm`} -/// \cgalParamType{a class model of `ReadWritePropertyMap` with `Surface_mesh::Vertex_index` +/// \cgalParamType{a class model of `WritablePropertyMap` with `Surface_mesh::Vertex_index` /// as key type and `CGAL::Color` as value type} -/// \cgalParamDefault{vertex colors will be output using the internal property map, if it exists} +/// \cgalParamDefault{If this parameter is unsused, vertex colors (if they exist) +/// will be written in an internal property map called `v:color`.} /// \cgalParamNEnd /// /// \cgalParamNBegin{vertex_texture_map} /// \cgalParamDescription{a property map associating textures to the vertices of `sm`} -/// \cgalParamType{a class model of `ReadWritePropertyMap` with `Surface_mesh::Vertex_index` -/// as key type and `%Point_2` as value type} -/// \cgalParamDefault{vertex textures will be output using the internal property map, if it exists} +/// \cgalParamType{a class model of `WritablePropertyMap` with `Surface_mesh::Vertex_index` +/// as key type and a 2D vector type issued from the same kernel as `Point` as value type} +/// \cgalParamDefault{If this parameter is unsused, vertex textures (if they exist) +/// will be written in an internal property map called `v:texcoords`.} /// \cgalParamNEnd /// /// \cgalParamNBegin{face_color_map} /// \cgalParamDescription{a property map associating colors to the faces of `sm`} -/// \cgalParamType{a class model of `ReadWritePropertyMap` with `Surface_mesh::Face_index` +/// \cgalParamType{a class model of `WritablePropertyMap` with `Surface_mesh::Face_index` /// as key type and `CGAL::Color` as value type} -/// \cgalParamDefault{face colors will be output using the internal property map, if it exists} +/// \cgalParamDefault{If this parameter is unsused, face colors (if they exist) +/// will be written in an internal property map called `f:color`.} /// \cgalParamNEnd /// \cgalNamedParamsEnd /// @@ -506,10 +508,10 @@ bool write_OFF_with_or_without_vnormals(std::ostream& os, /// the following property maps internal to the surface mesh, if they exist and if they are not /// already present in the named parameters: /// -/// - vertex:normal map (property map named "v:normal" in the surface mesh) -/// - vertex:color map (property map named "v:color" in the surface mesh) -/// - vertex:texture map (property map named "v:texcoord" in the surface mesh) -/// - face:color map (property map named "f:color" in the surface mesh) +/// - vertex normals (property map named "v:normal" in the surface mesh) +/// - vertex colors (property map named "v:color" in the surface mesh) +/// - vertex textures (property map named "v:texcoord" in the surface mesh) +/// - face colors (property map named "f:color" in the surface mesh) /// /// \tparam Point The type of the \em point property of a vertex. There is no requirement on `P`, /// besides being default constructible and assignable. @@ -524,38 +526,36 @@ bool write_OFF_with_or_without_vnormals(std::ostream& os, /// \cgalParamNBegin{vertex_point_map} /// \cgalParamDescription{a property map associating points to the vertices of `sm`} /// \cgalParamType{a class model of `ReadablePropertyMap` with `Surface_mesh::Vertex_index` -/// as key type and `%Point_3` as value type} +/// as key type and `%Point` as value type} /// \cgalParamDefault{`boost::get(CGAL::vertex_point, g)`} -/// \cgalParamExtra{If this parameter is omitted, an internal property map for `CGAL::vertex_point_t` -/// must be available in `sm`.} /// \cgalParamNEnd /// /// \cgalParamNBegin{vertex_normal_map} /// \cgalParamDescription{a property map associating normals to the vertices of `sm`} /// \cgalParamType{a class model of `ReadablePropertyMap` with `Surface_mesh::Vertex_index` -/// as key type and `%Vector_3` as value type} -/// \cgalParamDefault{vertex normals will be output using the internal property map, if it exists} +/// as key type and a 3D vector type issued from the same kernel as `Point` as value type} +/// \cgalParamDefault{vertex normals will be output using the internal property map, if it exists.} /// \cgalParamNEnd /// /// \cgalParamNBegin{vertex_color_map} /// \cgalParamDescription{a property map associating colors to the vertices of `sm`} /// \cgalParamType{a class model of `ReadablePropertyMap` with `Surface_mesh::Vertex_index` /// as key type and `CGAL::Color` as value type} -/// \cgalParamDefault{vertex colors will be output using the internal property map, if it exists} +/// \cgalParamDefault{vertex colors will be output using the internal property map, if it exists.} /// \cgalParamNEnd /// /// \cgalParamNBegin{vertex_texture_map} /// \cgalParamDescription{a property map associating textures to the vertices of `sm`} /// \cgalParamType{a class model of `ReadablePropertyMap` with `Surface_mesh::Vertex_index` -/// as key type and `%Point_2` as value type} -/// \cgalParamDefault{vertex textures will be output using the internal property map, if it exists} +/// as key type and a 2D point type issued from the same kernel as `Point` as value type} +/// \cgalParamDefault{vertex textures will be output using the internal property map, if it exists.} /// \cgalParamNEnd /// /// \cgalParamNBegin{face_color_map} /// \cgalParamDescription{a property map associating colors to the faces of `sm`} /// \cgalParamType{a class model of `ReadablePropertyMap` with `Surface_mesh::Face_index` /// as key type and `CGAL::Color` as value type} -/// \cgalParamDefault{face colors will be output using the internal property map, if it exists} +/// \cgalParamDefault{face colors will be output using the internal property map, if it exists.} /// \cgalParamNEnd /// /// \cgalParamNBegin{stream_precision} diff --git a/Surface_mesh_approximation/include/CGAL/Variational_shape_approximation.h b/Surface_mesh_approximation/include/CGAL/Variational_shape_approximation.h index 9e5c7b02d63..069e682b75f 100644 --- a/Surface_mesh_approximation/include/CGAL/Variational_shape_approximation.h +++ b/Surface_mesh_approximation/include/CGAL/Variational_shape_approximation.h @@ -1833,7 +1833,7 @@ private: * @param chord_begin begin iterator of the chord * @param chord_end end iterator of the chord * @param subdivision_ratio the chord recursive split error threshold - * @param relative_to_chord set `true` if the subdivision_ratio is relative to the the chord length (relative sense), + * @param relative_to_chord set `true` if the subdivision_ratio is relative to the chord length (relative sense), * otherwise it's relative to the average edge length (absolute sense). * @param with_dihedral_angle if set to `true` add dihedral angle weight to the distance. * @return the number of anchors of the chord apart from the first one diff --git a/Surface_mesh_segmentation/include/CGAL/internal/auxiliary/graph.h b/Surface_mesh_segmentation/include/CGAL/internal/auxiliary/graph.h index 545f50062f5..5698e0c59a0 100644 --- a/Surface_mesh_segmentation/include/CGAL/internal/auxiliary/graph.h +++ b/Surface_mesh_segmentation/include/CGAL/internal/auxiliary/graph.h @@ -242,7 +242,7 @@ void main() # endif // CGAL_LICENSE_WARNING # ifdef CGAL_LICENSE_ERROR -# error "You use the the MaxFlow package of Vladimir Kolmogorov under the terms of the GPLv2+.\ +# error "You use the MaxFlow package of Vladimir Kolmogorov under the terms of the GPLv2+.\ You get this error, as you defined CGAL_LICENSE_ERROR." # endif // CGAL_LICENSE_ERROR diff --git a/Surface_mesh_topology/include/CGAL/Surface_mesh_topology/internal/Path_on_surface_with_rle.h b/Surface_mesh_topology/include/CGAL/Surface_mesh_topology/internal/Path_on_surface_with_rle.h index 64438208dd6..a8e984fd348 100644 --- a/Surface_mesh_topology/include/CGAL/Surface_mesh_topology/internal/Path_on_surface_with_rle.h +++ b/Surface_mesh_topology/include/CGAL/Surface_mesh_topology/internal/Path_on_surface_with_rle.h @@ -1027,7 +1027,7 @@ public: return; } - it2=next_iterator(it1); // it2 is the the next flat after it1 + it2=next_iterator(it1); // it2 is the next flat after it1 reduce_flat_from_end(it1, modified_flats); // decrease also m_length reduce_flat_from_beginning(it3, modified_flats); diff --git a/Three/include/CGAL/Three/Scene_item.h b/Three/include/CGAL/Three/Scene_item.h index 2b3f2fd83c1..726ba958e0d 100644 --- a/Three/include/CGAL/Three/Scene_item.h +++ b/Three/include/CGAL/Three/Scene_item.h @@ -281,7 +281,7 @@ public: virtual Header_data header()const; //!Returns true if the item has statistics. virtual bool has_stats()const{return false;} - //!Returns a QString containing the requested value for the the table in the statistics dialog + //!Returns a QString containing the requested value for the table in the statistics dialog /*! \verbatim * Example : * ____________________________