Add Property_map and Point_set_processing doc

.gitattributes

@@ -4442,6 +4442,31 @@ Point_set_2/doc/Point_set_2/Point_set_2.txt -text
 Point_set_2/doc/Point_set_2/examples.txt -text
 Point_set_2/doc/Point_set_2/fig/point_set.png -text svneol=unset#image/png
 Point_set_2/doc_tex/Point_set_2/point_set.png -text
+Point_set_processing_3/doc/Point_set_processing_3/CGAL/IO/read_off_points.h -text
+Point_set_processing_3/doc/Point_set_processing_3/CGAL/IO/read_xyz_points.h -text
+Point_set_processing_3/doc/Point_set_processing_3/CGAL/IO/write_off_points.h -text
+Point_set_processing_3/doc/Point_set_processing_3/CGAL/IO/write_xyz_points.h -text
+Point_set_processing_3/doc/Point_set_processing_3/CGAL/compute_average_spacing.h -text
+Point_set_processing_3/doc/Point_set_processing_3/CGAL/grid_simplify_point_set.h -text
+Point_set_processing_3/doc/Point_set_processing_3/CGAL/jet_estimate_normals.h -text
+Point_set_processing_3/doc/Point_set_processing_3/CGAL/jet_smooth_point_set.h -text
+Point_set_processing_3/doc/Point_set_processing_3/CGAL/mst_orient_normals.h -text
+Point_set_processing_3/doc/Point_set_processing_3/CGAL/pca_estimate_normals.h -text
+Point_set_processing_3/doc/Point_set_processing_3/CGAL/random_simplify_point_set.h -text
+Point_set_processing_3/doc/Point_set_processing_3/CGAL/remove_outliers.h -text
+Point_set_processing_3/doc/Point_set_processing_3/PackageDescription.txt -text
+Point_set_processing_3/doc/Point_set_processing_3/Point_set_processing_3.txt -text
+Point_set_processing_3/doc/Point_set_processing_3/fig/grid_simplification.jpg -text svneol=unset#image/jpeg
+Point_set_processing_3/doc/Point_set_processing_3/fig/introduction.jpg -text svneol=unset#image/jpeg
+Point_set_processing_3/doc/Point_set_processing_3/fig/mst_orient_normals.jpg -text svneol=unset#image/jpeg
+Point_set_processing_3/doc/Point_set_processing_3/fig/pipeline.jpg -text svneol=unset#image/jpeg
+Point_set_processing_3/doc/Point_set_processing_3/fig/point_set_processing.jpg -text svneol=unset#image/jpeg
+Point_set_processing_3/doc/Point_set_processing_3/fig/point_set_processing_detail.png -text svneol=unset#image/png
+Point_set_processing_3/doc/Property_map/CGAL/property_map.h -text
+Point_set_processing_3/doc/Property_map/PackageDescription.txt -text
+Point_set_processing_3/doc/Property_map/Property_map.txt -text
+Point_set_processing_3/doc/Property_map/examples.txt -text
+Point_set_processing_3/doc/Property_map/fig/property_map.png -text svneol=unset#image/png
 Point_set_processing_3/doc_tex/Point_set_processing_3/Point_set_processing_images.ppt -text svneol=unset#application/vnd.ms-powerpoint
 Point_set_processing_3/doc_tex/Point_set_processing_3/analysis.tex -text
 Point_set_processing_3/doc_tex/Point_set_processing_3/fig/point_set_processing.jpg -text svneol=unset#image/jpeg

Documentation/doc/packages.txt

@@ -205,7 +205,7 @@ h1 {
 <a name="Pkg:BGL"></a>
 \package_listing{BGL}
 <a name="Pkg:Property_map"></a>
-\package_listing{Property_map}
+\package_listing{Point_set_processing_3/Property_map}
 <a name="Pkg:HandlesAndCirculators"></a>
 \package_listing{Circulator}
 <a name="Pkg:Generators"></a>

Documentation/doxyassist.xml

@@ -1006,6 +1006,31 @@ namespace for the XML file to be processed properly.  -->
         </doxygen>
       </project>
 
+      <project>
+        <name>CGAL and Boost Property Maps</name>
+        <input>../Point_set_processing_3/doc/Property_map</input>
+        <doxygen>
+          <string name="STRIP_FROM_PATH">../Point_set_processing_3/doc/Property_map</string>
+          <string name="STRIP_FROM_INC_PATH">../Point_set_processing_3/doc/Property_map</string>
+          <string name="GENERATE_TAGFILE">./tags/Property_map.tag</string>
+          <string name="EXAMPLE_PATH">../Point_set_processing_3/examples</string>
+        </doxygen>
+      </project>
+
+      <project>
+        <name>Point Set Processing</name>
+        <input>../Point_set_processing_3/doc/Point_set_processing_3</input>
+        <doxygen>
+          <string name="STRIP_FROM_PATH">../Point_set_processing_3/doc/Point_set_processing_3</string>
+          <string name="STRIP_FROM_INC_PATH">../Point_set_processing_3/doc/Point_set_processing_3</string>
+          <string name="GENERATE_TAGFILE">./tags/Point_set_processing_3.tag</string>
+          <string name="IMAGE_PATH">../Point_set_processing_3/doc/Point_set_processing_3/fig</string>
+          <string name="EXAMPLE_PATH">../Point_set_processing_3/examples</string>
+        </doxygen>
+      </project>
+
+
+
       <project>
         <name>3D Boolean Operations on Nef Polyhedra</name>
         <input>../Nef_3/doc</input>
@@ -1104,6 +1129,8 @@ namespace for the XML file to be processed properly.  -->
           <item>../Triangulation_3/doc/TDS_3/fig</item>
           <item>../Triangulation_3/doc/Triangulation_3/fig</item>
           <item>../Ridges_3/doc/Ridges_3/fig</item>
+          <item>../Point_set_processing_3/doc/Point_set_processing_3/fig</item>
+          <item>../Point_set_processing_3/doc/Property_map/fig</item>
           <item>../Periodic_3_triangulation_3/doc/Periodic_3_triangulation_3/fig</item>
           <item>../Spatial_searching/doc/Spatial_searching/fig</item>
           <item>../Spatial_sorting/doc/Spatial_sorting/fig</item>
@@ -1171,6 +1198,8 @@ namespace for the XML file to be processed properly.  -->
           <item>./tags/Triangulation_3.tag=../../CGAL.CGAL.3D-Triangulation/html</item>
           <item>./tags/Periodic_3_triangulation_3.tag=../../CGAL.CGAL.3D-Periodic-Triangulation/html</item>
           <item>./tags/Ridges_3.tag=../../CGAL.CGAL.Approximation-of-Ridges-and-Umbilics-on-Triangulated-Surface-Meshes/html</item>
+          <item>./tags/Property_map.tag=../../CGAL.CGAL.CGAL-and-Boost-Property-Maps/html</item>
+          <item>./tags/Point_set_processing_3.tag=../../CGAL.CGAL.Point-Set-Processing/html</item>
           <item>./tags/Snap_rounding_2.tag=../../CGAL.CGAL.2D-Snap-Rounding/html</item>
           <item>./tags/Spatial_searching.tag=../../CGAL.CGAL.dD-Spatial-Searching/html</item>
           <item>./tags/Spatial_sorting.tag=../../CGAL.CGAL.Spatial-Sorting/html</item>

Point_set_processing_3/doc/Point_set_processing_3/CGAL/IO/read_off_points.h

@@ -0,0 +1,80 @@
+namespace CGAL {
+
+/*!
+\ingroup PkgPointSetProcessing
+
+`CGAL::read_off_points()` reads the point from a .off ASCII stream. More specifically, it reads only the point locations and ignores all point attributes available from the stream. 
+`CGAL::read_off_points_and_normals()` reads the points as well as the normals (if available) from a .off ASCII stream. 
+In both cases the other primitives (segments, faces) are ignored. 
+
+\sa `CGAL::read_xyz_points`
+\sa `CGAL::write_xyz_points`
+\sa `CGAL::write_off_points`
+
+Example 
+-------------- 
+
+See `read_write_xyz_point_set_example.cpp`. 
+
+CONVERROR StrangeDoc placement
+
+Reads points (position only) from a .off ASCII stream. The function expects for each point a line with the x y z position. If the position is followed by the nx ny nz normal, then the normal will be ignored. Faces are ignored.
+
+Template Parameters
+--------------
+
+`OutputIterator`: iterator over output points. `PointPMap`: is a model of `boost::WritablePropertyMap` with a `value_type` = `Point_3<Kernel>`. It can be omitted if `OutputIterator` `value_type` is convertible to `Point_3<Kernel>`. `Kernel`: Geometric traits class. It can be omitted and deduced automatically from `PointPMap` `value_type`.
+
+Returns
+--------------
+
+true on success.
+
+Parameters
+--------------
+
+`stream`: input stream. `output`: output iterator over points. `point_pmap`: property map `OutputIterator` -\f$ >\f$ `Point_3`. `kernel`: geometric traits.
+
+*/
+template<typename OutputIterator, typename PointPMap, typename Kernel> bool read_off_points(std::istream& stream, OutputIterator output, PointPMap point_pmap, const Kernel& kernel);
+
+/*!
+\ingroup PkgPointSetProcessing
+
+`CGAL::read_off_points()` reads the point from a .off ASCII stream. More specifically, it reads only the point locations and ignores all point attributes available from the stream. 
+`CGAL::read_off_points_and_normals()` reads the points as well as the normals (if available) from a .off ASCII stream. 
+In both cases the other primitives (segments, faces) are ignored. 
+
+\sa `CGAL::read_xyz_points`
+\sa `CGAL::write_xyz_points`
+\sa `CGAL::write_off_points`
+
+Example 
+-------------- 
+
+See `read_write_xyz_point_set_example.cpp`. 
+
+CONVERROR StrangeDoc placement
+
+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.
+
+Template Parameters
+--------------
+
+`OutputIterator`: iterator over output points. `PointPMap`: is a model of `boost::WritablePropertyMap` with a `value_type` = `Point_3<Kernel>`. It can be omitted if `OutputIterator` `value_type` is convertible to `Point_3<Kernel>`. `NormalPMap`: is a model of `boost::WritablePropertyMap` with a `value_type` = `Vector_3<Kernel>`. `Kernel`: Geometric traits class. It can be omitted and deduced automatically from `PointPMap` `value_type`.
+
+Returns
+--------------
+
+true on success.
+
+Parameters
+--------------
+
+`stream`: input stream. `output`: output iterator over points. `point_pmap`: property map `OutputIterator` -\f$ >\f$ `Point_3`. `normal_pmap`: property map `OutputIterator` -\f$ >\f$ `Vector_3`. `kernel`: geometric traits.
+
+*/
+template<typename OutputIterator, typename PointPMap, typename NormalPMap, typename Kernel> bool read_off_points_and_normals(std::istream& stream, OutputIterator output, PointPMap point_pmap, NormalPMap normal_pmap, const Kernel& kernel);
+
+} /* namespace CGAL */
+

Point_set_processing_3/doc/Point_set_processing_3/CGAL/IO/read_xyz_points.h

@@ -0,0 +1,78 @@
+namespace CGAL {
+
+/*!
+\ingroup PkgPointSetProcessing
+
+`CGAL::read_xyz_points()` reads the point locations from a .xyz ASCII stream. 
+`CGAL::read_xyz_points_and_normals()` reads the points as well as the normals (if available) from a .xyz ASCII stream. 
+
+\sa `CGAL::write_xyz_points`
+\sa `CGAL::read_off_points`
+\sa `CGAL::write_off_points`
+
+Example 
+-------------- 
+
+See `read_write_xyz_point_set_example.cpp`. 
+
+CONVERROR StrangeDoc placement
+
+Reads points (positions only) from a .xyz ASCII stream. The function expects for each point a line with the x y z position. If the position is followed by the nx ny nz normal, then the normal will be ignored. The first line may contain the number of points in the file. Empty lines and comments starting by # character are allowed.
+
+Template Parameters
+--------------
+
+`OutputIterator`: iterator over output points. `PointPMap`: is a model of `boost::WritablePropertyMap` with a `value_type` = `Point_3<Kernel>`. It can be omitted if `OutputIterator` `value_type` is convertible to `Point_3<Kernel>`. `Kernel`: Geometric traits class. It can be omitted and deduced automatically from `PointPMap` `value_type`.
+
+Returns
+--------------
+
+true on success.
+
+Parameters
+--------------
+
+`stream`: input stream. `output`: output iterator over points. `point_pmap`: property map `OutputIterator` -\f$ >\f$ `Point_3`. `kernel`: geometric traits.
+
+*/
+template<typename OutputIterator, typename PointPMap, typename Kernel> bool read_xyz_points(std::istream& stream, OutputIterator output, PointPMap point_pmap, const Kernel& kernel);
+
+/*!
+\ingroup PkgPointSetProcessing
+
+`CGAL::read_xyz_points()` reads the point locations from a .xyz ASCII stream. 
+`CGAL::read_xyz_points_and_normals()` reads the points as well as the normals (if available) from a .xyz ASCII stream. 
+
+\sa `CGAL::write_xyz_points`
+\sa `CGAL::read_off_points`
+\sa `CGAL::write_off_points`
+
+Example 
+-------------- 
+
+See `read_write_xyz_point_set_example.cpp`. 
+
+CONVERROR StrangeDoc placement
+
+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.
+
+Template Parameters
+--------------
+
+`OutputIterator`: iterator over output points. `PointPMap`: is a model of `boost::WritablePropertyMap` with a `value_type` = `Point_3<Kernel>`. It can be omitted if `OutputIterator` `value_type` is convertible to `Point_3<Kernel>`. `NormalPMap`: is a model of `boost::WritablePropertyMap` with a `value_type` = `Vector_3<Kernel>`. `Kernel`: Geometric traits class. It can be omitted and deduced automatically from `PointPMap` `value_type`.
+
+Returns
+--------------
+
+true on success.
+
+Parameters
+--------------
+
+`stream`: input stream. `output`: output iterator over points. `point_pmap`: property map `OutputIterator` -\f$ >\f$ `Point_3`. `normal_pmap`: property map `OutputIterator` -\f$ >\f$ `Vector_3`. `kernel`: geometric traits.
+
+*/
+template<typename OutputIterator, typename PointPMap, typename NormalPMap, typename Kernel> bool read_xyz_points_and_normals(std::istream& stream, OutputIterator output, PointPMap point_pmap, NormalPMap normal_pmap, const Kernel& kernel);
+
+} /* namespace CGAL */
+

Point_set_processing_3/doc/Point_set_processing_3/CGAL/IO/write_off_points.h

@@ -0,0 +1,79 @@
+namespace CGAL {
+
+/*!
+\ingroup PkgPointSetProcessing
+
+`CGAL::write_off_points()` saves the points of an iterator range to a .off ASCII stream. More specifically, it saves only the point locations and ignores all other attributes. 
+`CGAL::write_off_points_and_normals()` saves the points as well the normals of an iterator range to a .off ASCII stream. 
+
+\sa `CGAL::read_xyz_points`
+\sa `CGAL::write_xyz_points`
+\sa `CGAL::read_off_points`
+
+Example 
+-------------- 
+
+See `read_write_xyz_point_set_example.cpp`. 
+
+CONVERROR StrangeDoc placement
+
+Saves the [first, beyond) range of points (positions only) to a .off ASCII stream. The function writes for each point a line with the x y z position.
+
+Template Parameters
+--------------
+
+`ForwardIterator`: iterator over input points. `PointPMap`: is a model of `boost::ReadablePropertyMap` with a `value_type` = `Point_3<Kernel>`. It can be omitted if `ForwardIterator` `value_type` is convertible to `Point_3<Kernel>`. `Kernel`: Geometric traits class. It can be omitted and deduced automatically from `PointPMap` `value_type`.
+
+Returns
+--------------
+
+true on success.
+
+Parameters
+--------------
+
+`stream`: output stream. `first`: iterator over the first input point. `beyond`: past-the-end iterator over the input points. `point_pmap`: property map `ForwardIterator` -\f$ >\f$ `Point_3`. `kernel`: geometric traits.
+
+*/
+template<typename ForwardIterator, typename PointPMap, typename Kernel> bool write_off_points(std::ostream& stream, ForwardIterator first, ForwardIterator beyond, PointPMap point_pmap, const Kernel& kernel);
+
+/*!
+\ingroup PkgPointSetProcessing
+
+`CGAL::write_off_points()` saves the points of an iterator range to a .off ASCII stream. More specifically, it saves only the point locations and ignores all other attributes. 
+`CGAL::write_off_points_and_normals()` saves the points as well the normals of an iterator range to a .off ASCII stream. 
+
+\sa `CGAL::read_xyz_points`
+\sa `CGAL::write_xyz_points`
+\sa `CGAL::read_off_points`
+
+Example 
+-------------- 
+
+See `read_write_xyz_point_set_example.cpp`. 
+
+CONVERROR StrangeDoc placement
+
+Saves the [first, beyond) range of points (positions + normals) 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.
+\pre normals must be unit vectors.
+
+Template Parameters
+--------------
+
+`ForwardIterator`: iterator over input points. `PointPMap`: is a model of `boost::ReadablePropertyMap` with a `value_type` = `Point_3<Kernel>`. It can be omitted if `ForwardIterator` `value_type` is convertible to `Point_3<Kernel>`. `NormalPMap`: is a model of `boost::WritablePropertyMap` with a `value_type` = `Vector_3<Kernel>`. `Kernel`: Geometric traits class. It can be omitted and deduced automatically from `PointPMap` `value_type`.
+
+Returns
+--------------
+
+true on success.
+
+Parameters
+--------------
+
+`stream`: output stream. `first`: iterator over the first input point. `beyond`: past-the-end iterator over the input points. `point_pmap`: property map `ForwardIterator` -\f$ >\f$ `Point_3`. `normal_pmap`: property map `ForwardIterator` -\f$ >\f$ `Vector_3`. `kernel`: geometric traits.
+
+*/
+template<typename ForwardIterator, typename PointPMap, typename NormalPMap, typename Kernel> bool write_off_points_and_normals(std::ostream& stream, ForwardIterator first, ForwardIterator beyond, PointPMap point_pmap, NormalPMap normal_pmap, const Kernel& kernel);
+
+} /* namespace CGAL */
+

Point_set_processing_3/doc/Point_set_processing_3/CGAL/IO/write_xyz_points.h

@@ -0,0 +1,79 @@
+namespace CGAL {
+
+/*!
+\ingroup PkgPointSetProcessing
+
+`CGAL::write_xyz_points()` saves points (positions only) to a .xyz ASCII stream. 
+`CGAL::write_xyz_points_and_normals()` saves points (positions + normals) to a .xyz ASCII stream. 
+
+\sa `CGAL::read_xyz_points`
+\sa `CGAL::read_off_points`
+\sa `CGAL::write_off_points`
+
+Example 
+-------------- 
+
+See `read_write_xyz_point_set_example.cpp`. 
+
+CONVERROR StrangeDoc placement
+
+Saves the [first, beyond) range of points (positions only) to a .xyz ASCII stream. The function writes for each point a line with the x y z position.
+
+Template Parameters
+--------------
+
+`ForwardIterator`: iterator over input points. `PointPMap`: is a model of `boost::ReadablePropertyMap` with a `value_type` = `Point_3<Kernel>`. It can be omitted if `ForwardIterator` `value_type` is convertible to `Point_3<Kernel>`. `Kernel`: Geometric traits class. It can be omitted and deduced automatically from `PointPMap` `value_type`.
+
+Returns
+--------------
+
+true on success.
+
+Parameters
+--------------
+
+`stream`: output stream. `first`: iterator over the first input point. `beyond`: past-the-end iterator over the input points. `point_pmap`: property map `ForwardIterator` -\f$ >\f$ `Point_3`. `kernel`: geometric traits.
+
+*/
+template<typename ForwardIterator, typename PointPMap, typename Kernel> bool write_xyz_points(std::ostream& stream, ForwardIterator first, ForwardIterator beyond, PointPMap point_pmap, const Kernel& kernel);
+
+/*!
+\ingroup PkgPointSetProcessing
+
+`CGAL::write_xyz_points()` saves points (positions only) to a .xyz ASCII stream. 
+`CGAL::write_xyz_points_and_normals()` saves points (positions + normals) to a .xyz ASCII stream. 
+
+\sa `CGAL::read_xyz_points`
+\sa `CGAL::read_off_points`
+\sa `CGAL::write_off_points`
+
+Example 
+-------------- 
+
+See `read_write_xyz_point_set_example.cpp`. 
+
+CONVERROR StrangeDoc placement
+
+Saves the [first, beyond) range of points (positions + normals) 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.
+\pre normals must be unit vectors.
+
+Template Parameters
+--------------
+
+`ForwardIterator`: iterator over input points. `PointPMap`: is a model of `boost::ReadablePropertyMap` with a `value_type` = `Point_3<Kernel>`. It can be omitted if `ForwardIterator` `value_type` is convertible to `Point_3<Kernel>`. `NormalPMap`: is a model of `boost::WritablePropertyMap` with a `value_type` = `Vector_3<Kernel>`. `Kernel`: Geometric traits class. It can be omitted and deduced automatically from `PointPMap` `value_type`.
+
+Returns
+--------------
+
+true on success.
+
+Parameters
+--------------
+
+`stream`: output stream. `first`: iterator over the first input point. `beyond`: past-the-end iterator over the input points. `point_pmap`: property map `ForwardIterator` -\f$ >\f$ `Point_3`. `normal_pmap`: property map `ForwardIterator` -\f$ >\f$ `Vector_3`. `kernel`: geometric traits.
+
+*/
+template<typename ForwardIterator, typename PointPMap, typename NormalPMap, typename Kernel> bool write_xyz_points_and_normals(std::ostream& stream, ForwardIterator first, ForwardIterator beyond, PointPMap point_pmap, NormalPMap normal_pmap, const Kernel& kernel);
+
+} /* namespace CGAL */
+

Point_set_processing_3/doc/Point_set_processing_3/CGAL/compute_average_spacing.h

@@ -0,0 +1,37 @@
+namespace CGAL {
+
+/*!
+\ingroup PkgPointSetProcessing
+
+`CGAL::compute_average_spacing()` computes the average spacing of all points from the input set to their \f$ k\f$ nearest neighbors. This value depends on the `k` parameter which can be set to 6 for isotropically sampled surfaces. 
+
+Example 
+-------------- 
+
+See `average_spacing_example.cpp`. 
+
+CONVERROR StrangeDoc placement
+
+Computes average spacing from k nearest neighbors.
+\pre k \f$ >\f$= 2.
+
+Template Parameters
+--------------
+
+`InputIterator`: iterator over input points. `PointPMap`: is a model of `boost::ReadablePropertyMap` with a `value_type` = `Point_3<Kernel>`. It can be omitted if `InputIterator` `value_type` is convertible to `Point_3<Kernel>`. `Kernel`: Geometric traits class. It can be omitted and deduced automatically from `PointPMap` `value_type`.
+
+Returns
+--------------
+
+average spacing (scalar).
+
+Parameters
+--------------
+
+`first`: iterator over the first input point. `beyond`: past-the-end iterator over the input points. `point_pmap`: property map `InputIterator` -\f$ >\f$ `Point_3`. `k`: number of neighbors. `kernel`: geometric traits.
+
+*/
+template<typename InputIterator, typename PointPMap, typename Kernel> Kernel::FT compute_average_spacing(InputIterator first, InputIterator beyond, PointPMap point_pmap, unsigned int k, const Kernel& kernel);
+
+} /* namespace CGAL */
+

Point_set_processing_3/doc/Point_set_processing_3/CGAL/grid_simplify_point_set.h

@@ -0,0 +1,43 @@
+namespace CGAL {
+
+/*!
+\ingroup PkgPointSetProcessing
+
+Function `CGAL::grid_simplify_point_set()` considers a regular grid covering the bounding box of the input point set, and clusters all points sharing the same cell of the grid by picking as representant one arbitrarily chosen point. 
+
+This method modifies the order of input points so as to pack all remaining points first, and returns an iterator over the first point to remove (see erase-remove idiom). For this reason it should not be called on sorted containers. 
+
+\sa `CGAL::random_simplify_point_set`
+
+Example 
+-------------- 
+
+See `grid_simplification_example.cpp`. 
+
+CONVERROR StrangeDoc placement
+
+Merges points which belong to the same cell of a grid of cell size = epsilon. 
+
+This method modifies the order of input points so as to pack all remaining points first, and returns an iterator over the first point to remove (see erase-remove idiom). For this reason it should not be called on sorted containers.
+\pre epsilon \f$ >\f$ 0.
+
+Template Parameters
+--------------
+
+`ForwardIterator`: iterator over input points. `PointPMap`: is a model of `boost::ReadablePropertyMap` with a `value_type` = `Point_3<Kernel>`. It can be omitted if `ForwardIterator` `value_type` is convertible to `Point_3<Kernel>`. `Kernel`: Geometric traits class. It can be omitted and deduced automatically from `PointPMap` `value_type`.
+
+Returns
+--------------
+
+iterator over the first point to remove.
+
+Parameters
+--------------
+
+`first`: iterator over the first input point. `beyond`: past-the-end iterator over the input points. `point_pmap`: property map `ForwardIterator` -\f$ >\f$ `Point_3`. `epsilon`: tolerance value when merging 3D points. `kernel`: geometric traits.
+
+*/
+template<typename ForwardIterator, typename PointPMap, typename Kernel> ForwardIterator grid_simplify_point_set(ForwardIterator first, ForwardIterator beyond, PointPMap point_pmap, double epsilon, const Kernel& kernel);
+
+} /* namespace CGAL */
+

Point_set_processing_3/doc/Point_set_processing_3/CGAL/jet_estimate_normals.h

@@ -0,0 +1,38 @@
+namespace CGAL {
+
+/*!
+\ingroup PkgPointSetProcessing
+
+`CGAL::jet_estimate_normals()` estimates normal directions of all points from the input set by fitting jet surfaces over the \f$ k\f$ nearest neighbors. The default jet surface is a quadric, and the result is an unoriented normal vector for each input point. 
+
+The output of the normal estimation algorithm highly depends on the `k` parameter. 
+The number of neighbors controls the size of the point subset considered for jet fitting at each input point. As this parameter is application-specific we do not provide any default value. Larger values lead to smoother normal fields and are more time consuming. For point sets with limited noise this value can be set to small number such as 18. For noisy point sets this value must be increased. 
+
+\sa `CGAL::pca_estimate_normals`
+\sa `CGAL::mst_orient_normals`
+
+Example 
+-------------- 
+
+See `normal_estimation.cpp` example. 
+
+CONVERROR StrangeDoc placement
+
+Estimates normal directions of the [first, beyond) range of points using jet fitting on the k nearest neighbors. The output normals are randomly oriented.
+\pre k \f$ >\f$= 2.
+
+Template Parameters
+--------------
+
+`InputIterator`: iterator over input points. `PointPMap`: is a model of `boost::ReadablePropertyMap` with a `value_type` = `Point_3<Kernel>`. It can be omitted if `InputIterator` `value_type` is convertible to `Point_3<Kernel>`. `NormalPMap`: is a model of `boost::WritablePropertyMap` with a `value_type` = `Vector_3<Kernel>`. `Kernel`: Geometric traits class. It can be omitted and deduced automatically from `PointPMap` `value_type`.
+
+Parameters
+--------------
+
+`first`: iterator over the first input point. `beyond`: past-the-end iterator over the input points. `point_pmap`: property map `InputIterator` -\f$ >\f$ `Point_3`. `normal_pmap`: property map `InputIterator` -\f$ >\f$ `Vector_3`. `k`: number of neighbors. `kernel`: geometric traits.
+
+*/
+template<typename InputIterator, typename PointPMap, typename NormalPMap, typename Kernel> void jet_estimate_normals(InputIterator first, InputIterator beyond, PointPMap point_pmap, NormalPMap normal_pmap, unsigned int k, const Kernel& kernel, unsigned int degree_fitting = 2);
+
+} /* namespace CGAL */
+

Point_set_processing_3/doc/Point_set_processing_3/CGAL/jet_smooth_point_set.h

@@ -0,0 +1,35 @@
+namespace CGAL {
+
+/*!
+\ingroup PkgPointSetProcessing
+
+`CGAL::jet_smooth_point_set()` smooths a point set by fitting for each point a jet surface and projecting it onto the jet. The default jet surface is a quadric. 
+
+The output of the smoothing algorithm highly depends on the `k` parameter. 
+The number of neighbors controls the size of the point subset considered for jet fitting at each input point. As this parameter is application-specific we do not provide any default value. Larger values lead to smoother point sets and are more time consuming. For point sets with limited noise this value can be set to small number such as 24. For noisy point sets this value must be increased. 
+
+Example 
+-------------- 
+
+See `jet_smoothing_example.cpp`. 
+
+CONVERROR StrangeDoc placement
+
+Smoothes the [first, beyond) range of points using jet fitting on the k nearest neighbors and reprojection onto the jet. As this method relocates the points, it should not be called on containers sorted w.r.t. point locations.
+\pre k \f$ >\f$= 2.
+
+Template Parameters
+--------------
+
+`InputIterator`: iterator over input points. `PointPMap`: is a model of `boost::ReadablePropertyMap` with a `value_type` = `Point_3<Kernel>`. It can be omitted if `InputIterator` `value_type` is convertible to `Point_3<Kernel>`. `Kernel`: Geometric traits class. It can be omitted and deduced automatically from `PointPMap` `value_type`.
+
+Parameters
+--------------
+
+`first`: iterator over the first input point. `beyond`: past-the-end iterator over the input points. `point_pmap`: property map `InputIterator` -\f$ >\f$ `Point_3`. `k`: number of neighbors. `kernel`: geometric traits.
+
+*/
+template<typename InputIterator, typename PointPMap, typename Kernel> void jet_smooth_point_set(InputIterator first, InputIterator beyond, PointPMap point_pmap, unsigned int k, const Kernel& kernel, unsigned int degree_fitting = 2, unsigned int degree_monge = 2);
+
+} /* namespace CGAL */
+

Point_set_processing_3/doc/Point_set_processing_3/CGAL/mst_orient_normals.h

@@ -0,0 +1,51 @@
+namespace CGAL {
+
+/*!
+\ingroup PkgPointSetProcessing
+
+`CGAL::mst_orient_normals()` orients the normals of a point set using the propagation of a seed orientation through a minimum spanning tree computed over the Riemannian graph \cite cgal:hddms-srup-92. 
+
+The seed is chosen as the top point of the point set. Its normal is oriented towards +Z axis. The success of the orientation algorithm depends on the `k` parameter. 
+The number of neighbors controls the number of candidates to propagate the orientation to around each input point. In general the value 18 works well. With smaller values the propagation may be blocked by large gaps in sparse point sets as the graph may be disconnected. Large values cause problems with points scattered over thin objects as the algorithm may incorrectly propagate the orientation from one side of the object to the other. In presence of disconnected clusters of points the algorithm may fail propagating the orientation from one cluster to the others and may only orient the top cluster. 
+
+This method modifies the order of the input points so as to pack all successfully oriented normals first, and returns an iterator over the first point with an unoriented normal (see erase-remove idiom). For this reason it should not be called on sorted containers. 
+
+\sa `CGAL::pca_estimate_normals`
+\sa `CGAL::jet_estimate_normals`
+
+Example 
+-------------- 
+
+See `pca_estimate_normals_example.cpp`. 
+
+CONVERROR StrangeDoc placement
+
+Orients the normals of the [first, beyond) range of points using the propagation of a seed orientation through a minimum spanning tree of the Riemannian graph \cite cgal:hddms-srup-92. 
+
+This method modifies the order of input points so as to pack all sucessfully oriented points first, and returns an iterator over the first point with an unoriented normal (see erase-remove idiom). For this reason it should not be called on sorted containers.
+
+Preconditions
+--------------
+
+Normals must be unit vectors. k \f$ >\f$= 2.
+
+Template Parameters
+--------------
+
+`ForwardIterator`: iterator over input points. `PointPMap`: is a model of `boost::ReadablePropertyMap` with a `value_type` = `Point_3<Kernel>`. It can be omitted if `ForwardIterator` `value_type` is convertible to `Point_3<Kernel>`. `NormalPMap`: is a model of `boost::ReadWritePropertyMap` with a `value_type` = `Vector_3<Kernel>`. `Kernel`: Geometric traits class. It can be omitted and deduced automatically from `PointPMap` `value_type`.
+
+Returns
+--------------
+
+iterator over the first point with an unoriented normal.
+
+Parameters
+--------------
+
+`first`: iterator over the first input point. `beyond`: past-the-end iterator over the input points. `point_pmap`: property map `ForwardIterator` -\f$ >\f$ `Point_3`. `normal_pmap`: property map `ForwardIterator` -\f$ >\f$ `Vector_3`. `k`: number of neighbors. `kernel`: geometric traits.
+
+*/
+template<typename ForwardIterator, typename PointPMap, typename NormalPMap, typename Kernel> ForwardIterator mst_orient_normals(ForwardIterator first, ForwardIterator beyond, PointPMap point_pmap, NormalPMap normal_pmap, unsigned int k, const Kernel& kernel);
+
+} /* namespace CGAL */
+

Point_set_processing_3/doc/Point_set_processing_3/CGAL/pca_estimate_normals.h

@@ -0,0 +1,38 @@
+namespace CGAL {
+
+/*!
+\ingroup PkgPointSetProcessing
+
+`CGAL::pca_estimate_normals()` estimates normal directions at all points of an input point set by linear least squares fitting of a plane over their \f$ k\f$ nearest neighbors. The result is an unoriented normal for each input point. 
+
+The output of the normal estimation algorithm highly depends on the `k` parameter. 
+The number of neighbors controls the size of the point subset considered for plane fitting at each input point. As this parameter is application-specific we do not provide any default value. For noise-free point sets this value can be set to a small number, e.g., 18. Larger values (e.g., 30 or more) lead to smoother normal fields and are more time consuming. We thus recommend using them only for noisy data sets. 
+
+\sa `CGAL::jet_estimate_normals`
+\sa `CGAL::mst_orient_normals`
+
+Example 
+-------------- 
+
+See `normals_example.cpp`. 
+
+CONVERROR StrangeDoc placement
+
+Estimates normal directions of the [first, beyond) range of points by linear least squares fitting of a plane over the k nearest neighbors. The output normals are randomly oriented.
+\pre k \f$ >\f$= 2.
+
+Template Parameters
+--------------
+
+`InputIterator`: iterator over input points. `PointPMap`: is a model of `boost::ReadablePropertyMap` with a `value_type` = `Point_3<Kernel>`. It can be omitted if `InputIterator` `value_type` is convertible to `Point_3<Kernel>`. `NormalPMap`: is a model of `boost::WritablePropertyMap` with a `value_type` = `Vector_3<Kernel>`. `Kernel`: Geometric traits class. It can be omitted and deduced automatically from `PointPMap` `value_type`.
+
+Parameters
+--------------
+
+`first`: iterator over the first input point. `beyond`: past-the-end iterator over the input points. `point_pmap`: property map `InputIterator` -\f$ >\f$ `Point_3`. `normal_pmap`: property map `InputIterator` -\f$ >\f$ `Vector_3`. `k`: number of neighbors. `kernel`: geometric traits.
+
+*/
+template<typename InputIterator, typename PointPMap, typename NormalPMap, typename Kernel> void pca_estimate_normals(InputIterator first, InputIterator beyond, PointPMap point_pmap, NormalPMap normal_pmap, unsigned int k, const Kernel& kernel);
+
+} /* namespace CGAL */
+

Point_set_processing_3/doc/Point_set_processing_3/CGAL/random_simplify_point_set.h

@@ -0,0 +1,40 @@
+namespace CGAL {
+
+/*!
+\ingroup PkgPointSetProcessing
+
+`CGAL::random_simplify_point_set()` randomly deletes a user-specified fraction of the input points. This method modifies the order of input points so as to pack all remaining points first, and returns an iterator over the first point to remove (see erase-remove idiom). For this reason it should not be called on sorted containers. 
+
+\sa `CGAL::grid_simplify_point_set`
+
+Example 
+-------------- 
+
+See `random_simplification_example.cpp`. 
+
+CONVERROR StrangeDoc placement
+
+Randomly deletes a user-specified fraction of the input points. 
+
+This method modifies the order of input points so as to pack all remaining points first, and returns an iterator over the first point to remove (see erase-remove idiom). For this reason it should not be called on sorted containers.
+
+Template Parameters
+--------------
+
+`ForwardIterator`: iterator over input points. `PointPMap`: is a model of `boost::ReadablePropertyMap` with a `value_type` = `Point_3<Kernel>`. It can be omitted if `ForwardIterator` `value_type` is convertible to `Point_3<Kernel>`. `Kernel`: Geometric traits class. It can be omitted and deduced automatically from `PointPMap` `value_type`.
+
+Returns
+--------------
+
+iterator over the first point to remove.
+
+Parameters
+--------------
+
+`first`: iterator over the first input point. `beyond`: past-the-end iterator over the input points. `point_pmap`: property map `ForwardIterator` -\f$ >\f$ `Point_3`. `removed_percentage`: percentage of points to remove. `kernel`: geometric traits.
+
+*/
+template<typename ForwardIterator, typename PointPMap, typename Kernel> ForwardIterator random_simplify_point_set(ForwardIterator first, ForwardIterator beyond, PointPMap point_pmap, double removed_percentage, const Kernel& kernel);
+
+} /* namespace CGAL */
+

Point_set_processing_3/doc/Point_set_processing_3/CGAL/remove_outliers.h

@@ -0,0 +1,46 @@
+namespace CGAL {
+
+/*!
+\ingroup PkgPointSetProcessing
+
+`CGAL::remove_outliers()` deletes a user-specified fraction of outliers from the input point set. More specifically, it sorts the input points in increasing order of average squared distances to the \f$ k\f$ nearest neighbors and computes the points with largest value. 
+
+The outliers detection depends on the `k` parameter, specifically the detection of clusters of outliers. 
+The number of neighbors should be higher than the size of clusters of outliers in the point set. 
+For datasets with no cluster of outliers, this value can be set to a few rings, e.g. 24. Larger value leads to longer computation times. 
+For these reasons, we do not provide any default value for this parameter. 
+
+This method modifies the order of input points so as to pack all remaining points first, and returns and returns an iterator over the first point to remove (see erase-remove idiom). For this reason it should not be called on sorted containers. 
+
+Example 
+-------------- 
+
+See `remove_outliers_example.cpp`. 
+
+CONVERROR StrangeDoc placement
+
+Removes outliers: computes average squared distance to the K nearest neighbors, and sorts the points in increasing order of average distance. 
+
+This method modifies the order of input points so as to pack all remaining points first, and returns an iterator over the first point to remove (see erase-remove idiom). For this reason it should not be called on sorted containers.
+\pre k \f$ >\f$= 2.
+
+Template Parameters
+--------------
+
+`InputIterator`: iterator over input points. `PointPMap`: is a model of `boost::ReadablePropertyMap` with a `value_type` = `Point_3<Kernel>`. It can be omitted if `InputIterator` `value_type` is convertible to `Point_3<Kernel>`. `Kernel`: Geometric traits class. It can be omitted and deduced automatically from `PointPMap` `value_type`.
+
+Returns
+--------------
+
+iterator over the first point to remove.
+
+Parameters
+--------------
+
+`first`: iterator over the first input point. `beyond`: past-the-end iterator over the input points. `point_pmap`: property map `InputIterator` -\f$ >\f$ `Point_3`. `k`: number of neighbors. `threshold_percent`: percentage of points to remove. `kernel`: geometric traits.
+
+*/
+template<typename InputIterator, typename PointPMap, typename Kernel> InputIterator remove_outliers(InputIterator first, InputIterator beyond, PointPMap point_pmap, unsigned int k, double threshold_percent, const Kernel& kernel);
+
+} /* namespace CGAL */
+

Point_set_processing_3/doc/Point_set_processing_3/PackageDescription.txt

@@ -0,0 +1,27 @@
+/// \defgroup PkgPointSetProcessing Point Set Processing
+
+/// \defgroup PkgPointSetProcessingConcepts Concepts
+/// \ingroup PkgPointSetProcessing
+
+/*!
+\addtogroup PkgPointSetProcessing
+\todo check generated documentation
+\PkgDescriptionBegin{Point Set Processing}
+\PkgPicture{point_set_processing_detail.png}
+\PkgAuthor{Pierre Alliez, Laurent Saboret, Nader Salman}
+\PkgDesc{This \cgal component implements methods to analyze and process unorganized point sets. The input is an unorganized point set, possibly with normal attributes (unoriented or oriented). The point set can be analyzed to measure its average spacing, and processed through functions devoted to the simplification, outlier removal, smoothing, normal estimation and normal orientation.}
+\PkgSince{3.5}
+\cgalbib{cgal:ass-psp}
+\license{\ref licensesGPL "GPL"}
+\PkgDescriptionEnd
+
+This \cgal component implements methods to analyze and process
+unorganized point sets. The input is an unorganized point set,
+possibly with attributes. This point set can be analyzed to measure
+average spacing, a global estimation of the point set
+density. Furthermore we can process it with functions devoted to
+simplification, outlier removal, smoothing, normal estimation and
+normal orientation.
+
+*/
+

Point_set_processing_3/doc/Point_set_processing_3/Point_set_processing_3.txt

@@ -0,0 +1,211 @@
+
+\page chappoint_set_processing_3 Point Set Processing
+
+namespace CGAL {
+/*!
+
+\mainpage Point Set Processing
+
+\anchor chappoint_set_processing_3
+
+\authors Pierre Alliez, Laurent Saboret, Nader Salman
+
+# Introduction #
+
+This \cgal component implements methods to analyze and process
+unorganized 3D point sets. The input is an unorganized 3D point set,
+possibly with normal attributes (unoriented or oriented). This point
+set can be analyzed to measure geometric properties such as average
+spacing between the points and their \f$ K\f$ nearest neighbors. It
+can be processed with functions devoted to the simplification, outlier
+removal, smoothing, normal estimation and normal orientation. The
+processing of point sets is often needed in applications dealing with
+measurement data, such as surface reconstruction from laser scanned
+data (see Figure \ref Point_set_processing_3figintroduction).
+
+\anchor Point_set_processing_3figintroduction
+\image html introduction.jpg "Point set processing. Left: 275K points sampled on the statue of an elephant with a Minolta laser scanner. Right: point set after clean-up and simplification to 17K points."
+
+In the context of surface reconstruction we can position the elements
+of this component along the common surface reconstruction pipeline
+(Figure \ref Point_set_processing_3figpipeline) which involves the
+following steps: 1) Scanning and scan alignment to produce a set of
+points or points with normals (alignment is not yet covered in \cgal);
+2) Outlier removal; 3) Simplification to reduce the number of input
+points; 4) Smoothing to reduce noise in the input data; 5) Normal
+estimation and orientation when the normals are not already provided
+by the acquisition device; and 6) Surface reconstruction. Chapter
+`Surface_reconstruction_points_3` \ref
+chapsurface_reconstruction_points_3 deals with surface reconstruction
+from point sets with normal attributes.
+
+\anchor Point_set_processing_3figpipeline
+\image html pipeline.jpg "Point set processing pipeline for surface reconstruction. The algorithms listed in gray are available from other \cgal components (bounding volumes and principal component analysis)."
+
+# Input/Output #
+
+## Property Maps ##
+
+The algorithms of this component take as input parameters iterator
+ranges of 3D points, or of 3D points with normals. The property maps
+are used to access the point or normal information from the input
+data, so as to let the user decide upon the implementation of a point
+with normal. The latter can be represented as, e.g., a class derived
+from the \cgal 3D point, or as a `std::pair<Point_3<K>, Vector_3<K>>`, 
+or as a `boost::tuple<..,Point_3<K>, ..., Vector_3<K> >`.
+
+The following classes described in Chapter \ref chapterProperty_map
+provide property maps for the implementations of points with normals
+listed above:
+
+- `CGAL::Dereference_property_map<T>` 
+- `CGAL::First_of_pair_property_map<Pair>` and `CGAL::Second_of_pair_property_map<Pair>` 
+- `CGAL::Nth_of_tuple_property_map<N, Tuple>` 
+
+`Dereference_property_map<Point_3>` is the default value of the
+position property map expected by all functions in this component.
+
+See below examples using pair and tuple property maps.
+
+Users of this package may use other types to represent positions and
+normals if they implement the corresponding property maps.
+
+## Streams ##
+
+We provide functions to read and write sets of points or sets of
+points with normals from the following ASCII file formats: XYZ (three
+point coordinates `x y z` per line or three point coordinates and
+three normal vector coordinates `x y z nx ny nz` per line), and OFF
+(Object File Format) \cite cgal:p-gmgv16-96.
+
+- `CGAL::read_xyz_points` 
+- `CGAL::read_off_points` 
+- `CGAL::write_off_points` 
+- `CGAL::write_xyz_points` 
+
+## Example ##
+
+The following example reads a point set from an input file and writes
+it to a file, both in the XYZ format. Positions and normals are stored
+in pairs and accessed through property maps.
+\cgalexample{read_write_xyz_point_set_example.cpp}
+
+# Analysis #
+
+Function `CGAL::compute_average_spacing()` computes the average
+spacing of all input points to their \f$ k\f$ nearest neighbor points,
+\f$ k\f$ being specified by the user. As it provides an order of a
+point set density, this function is used downstream the surface
+reconstruction pipeline to automatically determine some parameters
+such as output mesh sizing for surface reconstruction.
+
+## Example ##
+
+The following example reads a point set in the `xyz` format and
+computes the average spacing. Index, position and color are stored in
+a tuple and accessed through property maps.
+\cgalexample{average_spacing_example.cpp}
+
+Note that other functions such as centroid or bounding volumes are
+found in other \cgal components:
+
+- `CGAL::centroid` 
+- `CGAL::bounding_box` 
+- `Min_sphere_of_spheres_d<Traits>` 
+
+
+
+# Outlier Removal #
+
+Function `CGAL::remove_outliers()` deletes a user-specified fraction
+of outliers from an input point set. More specifically, it sorts the
+input points in increasing order of average squared distances to their
+\f$ k\f$ nearest neighbors and deletes the points with largest value.
+
+## Example ##
+
+The following example reads a point set and removes 5% of the
+points. It uses the `CGAL::Dereference_property_map<Point_3>` property
+map (optional as it is the default position property map of all
+functions in this component.)
+\cgalexample{remove_outliers_example.cpp}
+
+# Simplification #
+
+
+Two simplification functions are devised to reduce an input point set,
+either randomly or using a grid-based clustering approach.
+
+Function `CGAL::random_simplify_point_set()` randomly deletes a
+user-specified fraction of points from the input point set. This
+algorithm is fast.
+
+Function `CGAL::grid_simplify_point_set()` considers a regular grid
+covering the bounding box of the input point set, and clusters all
+points sharing the same cell of the grid by picking as representant
+one arbitrarily chosen point. This algorithm is slower than
+`CGAL::random_simplify_point_set()`.
+
+## Example ##
+
+The following example reads a point set and simplifies it by clustering.
+\cgalexample{grid_simplification_example.cpp}
+
+\anchor Point_set_processing_3figgrid_simplification
+\image html grid_simplification.jpg "Point set simplification through grid-based clustering. Removed points are depicted in red. Notice how low-density areas (in green) are not simplified."
+
+# Smoothing #
+
+
+Function `CGAL::jet_smooth_point_set` smooths the input point set by
+projecting each point onto a smooth parametric surface patch
+(so-called jet surface) fitted over its \f$ k\f$ nearest neighbors.
+
+
+## Example ##
+
+The following example generates a set of 9 points close to the \f$xy\f$ 
+plane and smooths them using 8 nearest neighbors:
+\cgalexample{jet_smoothing_example.cpp}
+
+# Normal Estimation #
+
+Assuming a point set sampled over an inferred surface \f$ S\f$, two
+functions provide an estimate of the normal to \f$ S\f$ at each
+point. The result is an unoriented normal vector for each input point.
+
+Function `CGAL::jet_estimate_normals()` estimates the normal direction
+at each point from the input set by fitting a jet surface over its \f$
+k\f$ nearest neighbors. The default jet is a quadric surface. This
+algorithm is well suited to point sets scattered over curved surfaces.
+
+Function `CGAL::pca_estimate_normals()` estimates the normal direction
+at each point from the set by linear least squares fitting of a plane
+over its \f$ k\f$ nearest neighbors. This algorithm is simpler and
+faster than `CGAL::jet_estimate_normals()`.
+
+# Normal Orientation #
+
+Function `CGAL::mst_orient_normals()` orients the normals of a set of
+points with unoriented normals using the method described by Hoppe et
+al. in <I>Surface reconstruction from unorganized points</I> \cite
+cgal:hddms-srup-92. More specifically, this method constructs a
+Riemannian graph over the input points (the graph of the \f$ K\f$
+nearest neighbor points) and propagates a seed normal orientation
+within a minimum spanning tree computed over this graph. The result is
+an oriented normal vector for each input unoriented normal, except for
+the normals which could not be successfully oriented.
+
+\anchor Point_set_processing_3figmst_orient_normals
+\image html  mst_orient_normals.jpg "Normal orientation of a sampled cube surface. Left: unoriented normals. Right: orientation of right face normals is propagated to bottom face."
+
+## Example ##
+
+The following example reads a point set from a file, estimates the
+normals through PCA over the 6 nearest neighbors and orients the
+normals:
+\cgalexample{normals_example.cpp}
+
+*/ 
+} /* namespace CGAL */
+

Point_set_processing_3/doc/Property_map/CGAL/property_map.h

@@ -0,0 +1,423 @@
+
+namespace CGAL {
+
+/*!
+\ingroup PkgProperty_map
+
+Property map that converts a `T*` pointer (or in general an iterator
+over `T` elements) to the `T` object.
+
+Parameters 
+-------------- 
+
+\code
+template<typename T> 
+struct Dereference_property_map; 
+\endcode
+
+\models `boost::LvaluePropertyMap`
+
+Example 
+-------------- 
+
+See \ref property_map.cpp example. 
+
+*/
+template< typename T >
+class Dereference_property_map : 
+    public boost::put_get_helper< T&, 
+                                  Dereference_property_map<T> > {
+public:
+
+  /// \name Types 
+  /// @{
+
+  /*! 
+
+  typedef to `T*` 
+
+  */ 
+  typedef Hidden_type key_type; 
+
+  /*! 
+
+  typedef to `T` 
+
+  */ 
+  typedef Hidden_type value_type; 
+
+  /*! 
+
+  typedef to `T&` 
+
+  */ 
+  typedef Hidden_type reference; 
+
+  /*! 
+
+  `boost::lvalue_property_map_tag` 
+
+  */ 
+  typedef Hidden_type category; 
+
+  /// @} 
+
+  /// \name Creation 
+  /// @{
+
+  /*! 
+
+  Constructor. 
+
+  */ 
+  Dereference_property_map(); 
+
+  /// @} 
+
+  /// \name Operations 
+  /// @{
+
+  /*! 
+
+  Access a property map element. 
+
+  Template Parameters 
+  -------------- 
+
+  `Iter`: Type convertible to `key_type`. 
+
+  */ 
+  template<class Iter> reference operator[](Iter it) const; 
+
+
+  /// @}
+
+}; /* end Dereference_property_map */
+
+/*! 
+
+Free function to create a `Dereference_property_map` property map. 
+
+\relates Dereference_property_map 
+*/ 
+Dereference_property_map<typename value_type_traits<Iter>::type> make_dereference_property_map(Iter); 
+
+
+/*!
+\ingroup PkgProperty_map
+
+Property map that accesses the first item of a `std::pair`. 
+
+Parameters 
+-------------- 
+
+template\f$ <\f$typename Pair\f$ >\f$ 
+
+struct `First_of_pair_property_map`; 
+
+Parameters 
+-------------- 
+
+`Pair`: Instance of `std::pair`. 
+
+Inherits From 
+-------------- 
+
+\models `boost::LvaluePropertyMap`
+
+\sa `CGAL::Second_of_pair_property_map<Pair>`
+
+Example 
+-------------- 
+
+See `property_map.cpp` example. 
+
+*/
+template< typename Pair >
+class First_of_pair_property_map : 
+    public boost::put_get_helper< Pair::first_type&, First_of_pair_property_map<Pair> >
+{
+public:
+
+  /// \name Types 
+  /// @{
+
+  /*! 
+
+  typedef to `Pair*` 
+
+  */ 
+  typedef Hidden_type key_type; 
+
+  /*! 
+
+  typedef to `Pair::first_type` 
+
+  */ 
+  typedef Hidden_type value_type; 
+
+  /*! 
+
+  typedef to `value_type`& 
+
+  */ 
+  typedef Hidden_type reference; 
+
+  /*! 
+
+  `boost::lvalue_property_map_tag` 
+
+  */ 
+  typedef Hidden_type category; 
+
+  /// @} 
+
+  /// \name Creation 
+  /// @{
+
+  /*! 
+
+  Constructor. 
+
+  */ 
+  First_of_pair_property_map(); 
+
+  /// @} 
+
+  /// \name Operations 
+  /// @{
+
+  /*! 
+
+  Access a property map element. 
+
+  Template Parameters 
+  -------------- 
+
+  `Iter`: Type convertible to `key_type`. 
+
+  */ 
+  template<class Iter> reference operator[](Iter pair) const; 
+
+  /// @}
+
+}; /* end First_of_pair_property_map */
+
+/*! 
+Free function to create a `First_of_pair_property_map` property map. 
+
+\relates First_of_pair_property_map 
+*/ 
+First_of_pair_property_map<typename value_type_traits<Iter>::type> make_first_of_pair_property_map(Iter); 
+
+
+/*!
+\ingroup PkgProperty_map
+
+Property map that accesses the Nth item of a `boost::tuple`. 
+
+Parameters 
+-------------- 
+
+template\f$ <\f$int N, typename Tuple\f$ >\f$ 
+
+struct `Nth_of_tuple_property_map`; 
+
+Parameters 
+-------------- 
+
+`N`: Index of the item to access. `Tuple`: Instance of `boost::tuple`. 
+
+\models `boost::LvaluePropertyMap`
+
+Example 
+-------------- 
+
+See `property_map.cpp` example. 
+
+*/
+template< typename N, typename Tuple >
+class Nth_of_tuple_property_map : 
+    public boost::put_get_helper< boost::tuples::element<N, Tuple>::type& , Nth_of_tuple_property_map<N, Tuple>> {
+public:
+
+  /// \name Types 
+  /// @{
+
+  /*! 
+
+  typedef to `Tuple*` 
+
+  */ 
+  typedef Hidden_type key_type; 
+
+  /*! 
+
+  typedef to `boost::tuples::element<N, Tuple>::type` 
+
+  */ 
+  typedef Hidden_type value_type; 
+
+  /*! 
+
+  typedef to `value_type`& 
+
+  */ 
+  typedef Hidden_type reference; 
+
+  /*! 
+
+  `boost::lvalue_property_map_tag` 
+
+  */ 
+  typedef Hidden_type category; 
+
+  /// @} 
+
+  /// \name Creation 
+  /// @{
+
+  /*! 
+
+  Constructor. 
+
+  */ 
+  Nth_of_tuple_property_map(); 
+
+  /// @} 
+
+  /// \name Operations 
+  /// @{
+
+  /*! 
+
+  Access a property map element. 
+
+  Template Parameters 
+  -------------- 
+
+  `Iter`: Type convertible to `key_type`. 
+
+  */ 
+  template<class Iter> reference operator[](Iter tuple) const; 
+
+
+  /// @}
+
+}; /* end Nth_of_tuple_property_map */
+
+/*! 
+
+Free function to create a `Nth_of_tuple_property_map` property map. 
+
+\relates Nth_of_tuple_property_map 
+*/ 
+Nth_of_tuple_property_map<N, typename value_type_traits<Iter>::type> make_nth_of_tuple_property_map(Iter); 
+
+
+/*!
+\ingroup PkgProperty_map
+
+Property map that accesses the second item of a `std::pair`. 
+
+Parameters 
+-------------- 
+
+template\f$ <\f$typename Pair\f$ >\f$ 
+
+struct `Second_of_pair_property_map`; 
+
+Parameters 
+-------------- 
+
+`Pair`: Instance of `std::pair`. 
+
+\models `boost::LvaluePropertyMap`
+
+\sa `CGAL::First_of_pair_property_map<Pair>`
+
+Example 
+-------------- 
+
+See `property_map.cpp` example. 
+
+*/
+template< typename Pair >
+class Second_of_pair_property_map : public 
+boost::put_get_helper< Pair::second_type& , Second_of_pair_property_map<Pair>> 
+{
+public:
+
+  /// \name Types 
+  /// @{
+
+  /*! 
+
+  typedef to `Pair*` 
+
+  */ 
+  typedef Hidden_type key_type; 
+
+  /*! 
+
+  typedef to `Pair::second_type` 
+
+  */ 
+  typedef Hidden_type value_type; 
+
+  /*! 
+
+  typedef to `value_type`& 
+
+  */ 
+  typedef Hidden_type reference; 
+
+  /*! 
+
+  `boost::lvalue_property_map_tag` 
+
+  */ 
+  typedef Hidden_type category; 
+
+  /// @} 
+
+  /// \name Creation 
+  /// @{
+
+  /*! 
+
+  Constructor. 
+
+  */ 
+  Second_of_pair_property_map(); 
+
+  /// @} 
+
+  /// \name Operations 
+  /// @{
+
+  /*! 
+  Access a property map element. 
+
+  Template Parameters 
+  -------------- 
+
+  `Iter`: Type convertible to `key_type`. 
+
+  */ 
+  template<class Iter> reference operator[](Iter pair) const; 
+
+
+  /// @}
+
+}; /* end Second_of_pair_property_map */
+
+/*! 
+Free function to create a `Second_of_pair_property_map` property map. 
+
+\relates Second_of_pair_property_map 
+*/ 
+Second_of_pair_property_map<typename value_type_traits<Iter>::type> make_second_of_pair_property_map(Iter); 
+
+
+} /* end namespace CGAL */

Point_set_processing_3/doc/Property_map/PackageDescription.txt

@@ -0,0 +1,18 @@
+/// \defgroup PkgProperty_map CGAL and Boost Property Maps
+
+/*!
+\addtogroup PkgProperty_map
+\todo check generated documentation
+\PkgDescriptionBegin{CGAL and Boost Property Maps}
+\PkgPicture{property_map.png}
+\PkgAuthor{Andreas Fabri and Laurent Saboret}
+\PkgDesc{This package provides a framework for interfacing \cgal data structures with algorithms expecting Boost Property Maps.}
+\PkgSince{3.5}
+\cgalbib{cgal:fs-cbpm}
+\license{\ref licensesGPL "GPL"}
+\PkgDescriptionEnd
+
+This package provides a framework for interfacing \cgal data
+structures with algorithms expecting Boost Property Maps.  
+*/
+

Point_set_processing_3/doc/Property_map/Property_map.txt

@@ -0,0 +1,55 @@
+namespace CGAL {
+/*!
+
+\mainpage CGAL and Boost Property Maps
+
+\anchor chapterProperty_map
+
+\authors Andreas Fabri and Laurent Saboret
+
+# A Short Introduction to the Boost Property Maps Library #
+
+The Boost Property Map Library consists mainly of interface specifications in the form of concepts. These interface specifications are intended for use by implementors of generic libraries in communicating requirements on template parameters to their users. In particular, the Boost Property Map concepts define a general purpose interface for mapping key objects to corresponding value objects, thereby hiding the details of how the mapping is implemented from algorithms. The implementation of types fulfilling the property map interface is up to the client of the algorithm to provide.
+
+The Boost Property Map Library also contains a few adaptors that convert commonly used data-structures that implement a mapping operation, such as builtin arrays (pointers), iterators, and std::map, to have the property map interface.
+
+Free functions `get` and `put` allow getting and putting information through a property map.
+The data themselves may be stored in the element, or they may
+be stored in an external data structure, or they may be computed on
+the fly. This is an "implementation detail" of the particular property map.<BR>
+
+Property maps in the Boost manuals: <A HREF="http://www.boost.org/libs/property_map/doc/property_map.html"><TT>http://www.boost.org/libs/property_map/doc/property_map.html</TT></A>
+
+# CGAL and Boost Property Maps #
+
+Some algorithms in \cgal take as input parameters iterator ranges and property maps to access information attached to elements of the sequence.
+
+For example, the algorithms of chapters `Point_set_processing_3` \ref chappoint_set_processing_3 and `Surface_reconstruction_points_3` \ref chapsurface_reconstruction_points_3 take as input parameters iterator ranges and property maps to access each point's position and normal.
+Position and normal might be represented in various ways, e.g., as a class derived from the \cgal point class, or as a `std::pair<Point_3<K>, Vector_3<K> >`, or as a `boost::tuple<..,Point_3<K>, ..., Vector_3<K> >`.
+
+This component provides property maps to support these cases: 
+
+`CGAL::Dereference_property_map<T>` 
+
+`CGAL::First_of_pair_property_map<Pair>` and `CGAL::Second_of_pair_property_map<Pair>` 
+
+`CGAL::Nth_of_tuple_property_map<N, Tuple>` 
+
+## Example with Dereference_property_map ##
+
+The following example reads a point set and removes 5% of the points. It uses `CGAL::Dereference_property_map<Point_3>` as position property map.
+\cgalexample{remove_outliers_example.cpp}
+
+## Example with Pairs ##
+
+The following example reads a point set from an input file and writes it to a file, both in the xyz format. Position and normal are stored in pairs and accessed through property maps.
+\cgalexample{read_write_xyz_point_set_example.cpp}
+
+## Example with Tuples ##
+
+The following example reads a point set in the `xyz` format and computes the average spacing. Index, position and color are stored in a tuple and accessed through property maps.
+\cgalexample{average_spacing_example.cpp}
+
+*/ 
+} /* namespace CGAL */
+

Point_set_processing_3/doc/Property_map/examples.txt

@@ -0,0 +1,5 @@
+/*!
+\example remove_outliers_example.cpp
+\example read_write_xyz_point_set_example.cpp
+\example average_spacing_example.cpp
+*/