Stream support: Fix for Epeck (#9072)

## Summary of Changes

For file formats that expect floating point coordinates we convert on
the fly so that `CGAL::io::write_polygon_soup()` also works for polygon
soups with ` FT` which are non-float/double, e.g.
`Exact_predicates_exact_constructions_kernel`.
Additionally, we document the named parameter `point_map` as it was
missing.

## Release Management

* Affected package(s): Stream_support
* Issue(s) solved (if any): fix #9071
* License and copyright ownership: unchanged 
* upon integration update and test #9109

Author: sloriot

Documentation/doc/Documentation/Tutorials/Tutorial_reconstruction.txt

@@ -83,12 +83,12 @@ a newline character and each coordinate separated by a white
 space. Other formats available are 'OFF', 'PLY' and 'LAS'. \cgal
 provides functions to read such formats:
 
-- `read_XYZ()`
-- `read_OFF()`
-- `read_PLY()`
-- `read_PLY_with_properties()` to read additional PLY properties
-- `read_LAS()`
-- `read_LAS_with_properties()` to read additional LAS properties
+- `CGAL::IO::read_XYZ()`
+- `CGAL::IO::read_OFF()`
+- `CGAL::IO::read_PLY()`
+- `CGAL::IO::read_PLY_with_properties()` to read additional PLY properties
+- `CGAL::IO::read_LAS()`
+- `CGAL::IO::read_LAS_with_properties()` to read additional LAS properties
 
 \cgal also provides a dedicated container `CGAL::Point_set_3` to
 handle point sets with additional properties such as normal

Kernel_23/doc/Kernel_23/CGAL/Cartesian_converter.h

@@ -48,7 +48,7 @@ Cartesian_converter<>();
 /// @{
 
 /*!
-returns a `K2::Point_2` which coordinates are those of `p`,
+returns a `K2::Point_2` whose coordinates are those of `p`,
 converted by `NTConverter`.
 */
 K2::Point_2 operator()(const K1::Point_2&p);

Property_map/include/CGAL/property_map.h

@@ -105,7 +105,6 @@ make_OR_property_map(const PM1& pm1, const PM2& pm2)
 /// \cgalModels{ReadablePropertyMap}
 ///
 /// \tparam InputIterator an input iterator
-/// \endcond
 template<class InputIterator>
 struct Input_iterator_property_map{
   typedef InputIterator key_type;
@@ -119,6 +118,8 @@ struct Input_iterator_property_map{
   get(Input_iterator_property_map<InputIterator>, const InputIterator& it){ return *it; }
 };
 
+/// \endcond
+
 #ifdef DOXYGEN_RUNNING
 /// \ingroup PkgPropertyMapRef
 /// Property map that composes two property maps,
@@ -274,8 +275,8 @@ struct Compose_property_map<KeyMap, ValueMap, boost::lvalue_property_map_tag>
 };
 #endif
 /// \ingroup PkgPropertyMapRef
-/// \relates Compose_property_map
 /// returns `Compose_property_maps<KeyMap, ValueMap>(km,vm)`
+/// \relates Compose_property_map
 template <class KeyMap, class ValueMap>
 Compose_property_map<KeyMap, ValueMap>
 make_compose_property_map(const KeyMap& km, const ValueMap& vm)
@@ -304,8 +305,8 @@ struct Dereference_property_map
   reference operator[](const Iter_& it) const { return *it; }
 };
 
+/// \ingroup PkgPropertyMapRef
 /// Free function to create a `Dereference_property_map` property map.
-///
 /// \relates Dereference_property_map
 template <class Iter> // Type convertible to `key_type`
 Dereference_property_map<typename CGAL::value_type_traits<Iter>::type>
@@ -371,8 +372,8 @@ struct Identity_property_map_no_lvalue
 };
 /// \endcond
 
+/// \ingroup PkgPropertyMapRef
 /// Free function to create a `Identity_property_map` property map.
-///
 /// \relates Identity_property_map
 template <class T> // Key and value type
 Identity_property_map<T>
@@ -409,8 +410,8 @@ struct First_of_pair_property_map
   /// @}
 };
 
+/// \ingroup PkgPropertyMapRef
 /// Free function to create a `First_of_pair_property_map` property map.
-///
 /// \relates First_of_pair_property_map
 template <class Pair> // Pair type
 First_of_pair_property_map<Pair>
@@ -449,8 +450,8 @@ struct Second_of_pair_property_map
   /// @}
 };
 
+/// \ingroup PkgPropertyMapRef
 /// Free function to create a Second_of_pair_property_map property map.
-///
 /// \relates Second_of_pair_property_map
 template <class Pair> // Pair type
 Second_of_pair_property_map<Pair>
@@ -509,8 +510,8 @@ struct Nth_of_tuple_property_map<N,std::tuple<T...> >
   friend void put(const Self&, key_type& k, const value_type& v) { std::get<N>(k) = v; }
 };
 
+/// \ingroup PkgPropertyMapRef
 /// Free function to create a Nth_of_tuple_property_map property map.
-///
 /// \relates Nth_of_tuple_property_map
 template <int N, class Tuple> // Tuple type
 Nth_of_tuple_property_map<N, Tuple>
@@ -563,6 +564,7 @@ struct Pointer_property_map{
 /// This function is a shortcut to the recommended replacement:
 /// `boost::make_iterator_property_map(<pointer>, boost::typed_identity_property_map<std::size_t>())`
 /// Note that the property map is a mutable `LvaluePropertyMap` with `std::size_t` as key.
+/// \relates Pointer_property_map
 template <class T>
 inline
 typename Pointer_property_map<T>::type
@@ -574,6 +576,7 @@ make_property_map(T* pointer)
 /// \ingroup PkgPropertyMapRef
 /// equivalent to `make_property_map(&v[0])`
 /// Note that `v` must not be modified while using the property map created
+/// \relates Pointer_property_map
 template <class T>
 inline
 typename Pointer_property_map<T>::type
@@ -587,6 +590,7 @@ make_property_map(std::vector<T>& v)
 
 /// \ingroup PkgPropertyMapRef
 /// Non-mutable version
+/// \relates Pointer_property_map
 template <class T>
 inline
 typename Pointer_property_map<T>::const_type
@@ -598,6 +602,7 @@ make_property_map(const T* pointer)
 /// \ingroup PkgPropertyMapRef
 /// equivalent to `make_property_map(&v[0])`
 /// Note that `v` must not be modified while using the property map created
+/// \relates Pointer_property_map
 template <class T>
 inline
 typename Pointer_property_map<T>::const_type
@@ -674,6 +679,7 @@ struct Boolean_property_map
 
 /// \ingroup PkgPropertyMapRef
 /// returns `Boolean_property_map<Set>(set_)`
+/// \relates Boolean_property_map
 template <class Set>
 Boolean_property_map<Set>
 make_boolean_property_map(Set& set_)
@@ -716,6 +722,7 @@ struct Cartesian_converter_property_map
 
 /// \ingroup PkgPropertyMapRef
 /// returns `Cartesian_converter_property_map<GeomObject, Vpm>(vpm)`
+/// \relates Cartesian_converter_property_map
 template<class GeomObject, class Vpm>
 Cartesian_converter_property_map<GeomObject, Vpm>
 make_cartesian_converter_property_map(Vpm vpm)
@@ -765,8 +772,8 @@ class Random_access_property_map
 };
 
 /// \ingroup PkgPropertyMapRef
-/// \relates Random_access_property_map
 /// returns `Random_access_property_map<Container>(container)`
+/// \relates Random_access_property_map
 template <class Container>
 Random_access_property_map<Container>
 make_random_access_property_map(Container& container)
@@ -775,6 +782,7 @@ make_random_access_property_map(Container& container)
 }
 
 /// \cond SKIP_IN_MANUAL
+
 // Syntaxic sugar for transform_iterator+pmap_to_unary_function
 template <typename Iterator, typename Pmap>
 typename boost::transform_iterator<CGAL::Property_map_to_unary_function<Pmap>, Iterator>

STL_Extension/doc/STL_Extension/dependencies

@@ -5,3 +5,4 @@ Manual
 Miscellany
 Number_types
 Surface_mesh
+Triangulation_3

Snap_rounding_2/examples/Snap_rounding_2/snap_rounding_data.cpp

@@ -1,16 +1,3 @@
-// Copyright 2009,2014 Max-Planck-Institute Saarbruecken (Germany).
-// All rights reserved.
-//
-// This file is part of CGAL (www.cgal.org).
-//
-// $URL$
-// $Id$
-// SPDX-License-Identifier: GPL-3.0-or-later OR LicenseRef-Commercial
-//
-//
-// author(s)     : Waqar Khan <[email protected]>
-
-
 /* Usage
  *
  *  This example converts arbitrary-precision arrangement into fixed-precision using Snap Rounding and by using INPUT DATA FROM A USER SPECIFIED FILE.

Stream_support/doc/Stream_support/dependencies

@@ -12,6 +12,7 @@ Point_set_processing_3
 Polygon
 Polygon_mesh_processing
 Polyhedron
+Property_map
 SMDS_3
 STL_Extension
 Surface_mesh

Stream_support/include/CGAL/IO/GOCAD.h

@@ -21,6 +21,8 @@
 #include <CGAL/boost/graph/named_params_helper.h>
 #include <CGAL/iterator.h>
 #include <CGAL/Kernel_traits.h>
+#include <CGAL/Cartesian_converter.h>
+#include <CGAL/Simple_cartesian.h>
 #include <CGAL/use.h>
 
 #include <boost/range/value_type.hpp>
@@ -295,8 +297,11 @@ bool write_GOCAD(std::ostream& os,
         "END_ORIGINAL_COORDINATE_SYSTEM\n"
         "TFACE\n";
 
+  typedef typename Kernel_traits<typename boost::property_traits<PointMap>::value_type>::type K;
+  typedef Simple_cartesian<double> SC;
+  Cartesian_converter<K,SC> conv;
   for(std::size_t i=0, end=points.size(); i<end; ++i)
-    os << "VRTX " << i << " " << get(point_map, points[i]) << "\n";
+    os << "VRTX " << i << " " << conv(get(point_map, points[i])) << "\n";
 
   for(const Poly& poly : polygons)
   {
@@ -331,8 +336,14 @@ bool write_GOCAD(std::ostream& os,
  * \param np optional sequence of \ref bgl_namedparameters "Named Parameters" among the ones listed below
  *
  * \cgalNamedParamsBegin
+ *   \cgalParamNBegin{point_map}
+ *     \cgalParamDescription{a property map associating points to the elements of the range `points`}
+ *     \cgalParamType{a model of `ReadablePropertyMap` whose key type is the value type
+ *                    of the iterator of `PointRange` and value type is a model of the concept `Kernel::Point_3`}
+ *     \cgalParamDefault{`CGAL::Identity_property_map<std::iterator_traits<PointRange::iterator>::value_type>`}
+ *   \cgalParamNEnd
  *   \cgalParamNBegin{stream_precision}
- *     \cgalParamDescription{a parameter used to set the precision (i.e. how many digits are generated) of the output stream}
+ *     \cgalParamDescription{a parameter used to set the precision (i.e., how many digits are generated) of the output stream}
  *     \cgalParamType{int}
  *     \cgalParamDefault{the precision of the stream `os`}
  *   \cgalParamNEnd
@@ -373,6 +384,12 @@ bool write_GOCAD(std::ostream& os,
  * \param np optional sequence of \ref bgl_namedparameters "Named Parameters" among the ones listed below
  *
  * \cgalNamedParamsBegin
+ *   \cgalParamNBegin{point_map}
+ *     \cgalParamDescription{a property map associating points to the elements of the range `points`}
+ *     \cgalParamType{a model of `ReadablePropertyMap` whose key type is the value type
+ *                    of the iterator of `PointRange` and value type is a model of the concept `Point_3`}
+ *     \cgalParamDefault{`CGAL::Identity_property_map<std::iterator_traits<PointRange::iterator>::value_type>`}
+ *   \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}

Stream_support/include/CGAL/IO/Generic_writer.h

@@ -19,6 +19,8 @@
 
 #include <CGAL/Named_function_parameters.h>
 #include <CGAL/boost/graph/named_params_helper.h>
+#include <CGAL/Cartesian_converter.h>
+#include <CGAL/Simple_cartesian.h>
 
 #include <iostream>
 #include <iterator>
@@ -51,11 +53,14 @@ class Generic_writer
 
     set_stream_precision_from_NP(m_os, np);
 
+    typedef typename Kernel_traits<typename boost::property_traits<PointMap>::value_type>::type K;
+    typedef Simple_cartesian<double> SC;
+    Cartesian_converter<K,SC> conv;
     m_writer.write_header(m_os, points.size(), 0, polygons.size());
     for(std::size_t i=0, end=points.size(); i<end; ++i)
     {
-      const typename boost::property_traits<PointMap>::value_type& p = get(point_map, points[i]);
-      m_writer.write_vertex(to_double(p.x()), to_double(p.y()), to_double(p.z()));
+      decltype(auto) p = conv(get(point_map, points[i]));
+      m_writer.write_vertex(p.x(), p.y(), p.z());
     }
 
     m_writer.write_facet_header();

Stream_support/include/CGAL/IO/OBJ.h

@@ -320,6 +320,12 @@ bool read_OBJ(const std::string& fname,
  * \param np optional sequence of \ref bgl_namedparameters "Named Parameters" among the ones listed below
  *
  * \cgalNamedParamsBegin
+ *   \cgalParamNBegin{point_map}
+ *     \cgalParamDescription{a property map associating points to the elements of the range `points`}
+ *     \cgalParamType{a model of `ReadablePropertyMap` whose key type is the value type
+ *                    of the iterator of `PointRange` and value type is a model of the concept `Point_3`}
+ *     \cgalParamDefault{`CGAL::Identity_property_map<std::iterator_traits<PointRange::iterator>::value_type>`}
+ *   \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}
@@ -364,6 +370,12 @@ bool write_OBJ(std::ostream& os,
  * \param np optional sequence of \ref bgl_namedparameters "Named Parameters" among the ones listed below
  *
  * \cgalNamedParamsBegin
+ *   \cgalParamNBegin{point_map}
+ *     \cgalParamDescription{a property map associating points to the elements of the range `points`}
+ *     \cgalParamType{a model of `ReadablePropertyMap` whose key type is the value type
+ *                    of the iterator of `PointRange` and value type is a model of the concept `Kernel::Point_3`}
+ *     \cgalParamDefault{`CGAL::Identity_property_map<std::iterator_traits<PointRange::iterator>::value_type>`}
+ *   \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}

Stream_support/include/CGAL/IO/OFF.h

@@ -267,6 +267,12 @@ bool read_OFF(const std::string& fname,
  * \param np optional sequence of \ref bgl_namedparameters "Named Parameters" among the ones listed below
  *
  * \cgalNamedParamsBegin
+ *   \cgalParamNBegin{point_map}
+ *     \cgalParamDescription{a property map associating points  to the elements of the range`points`}
+ *     \cgalParamType{a model of `ReadablePropertyMap` whose key type is the value type
+ *                    of the iterator of `PointRange` and value type is a model of the concept `Point_3`}
+ *     \cgalParamDefault{`CGAL::Identity_property_map<std::iterator_traits<PointRange::iterator>::value_type>`}
+ *   \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}
@@ -308,6 +314,12 @@ bool write_OFF(std::ostream& os,
  * \param np optional sequence of \ref bgl_namedparameters "Named Parameters" among the ones listed below
  *
  * \cgalNamedParamsBegin
+ *   \cgalParamNBegin{point_map}
+ *     \cgalParamDescription{a property map associating points to the elements of the range `points`}
+ *     \cgalParamType{a model of `ReadablePropertyMap` whose key type is the value type
+ *                    of the iterator of `PointRange` and value type is a model of the concept `Kernel::Point_3`}
+ *     \cgalParamDefault{`CGAL::Identity_property_map<std::iterator_traits<PointRange::iterator>::value_type>`}
+ *   \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}