From a69dd20004fe4e7fc790e48951a31f50fbad5aa9 Mon Sep 17 00:00:00 2001
From: Simon Giraudot <simon.giraudot@geometryfactory.com>
Date: Wed, 23 Sep 2015 13:54:53 +0200
Subject: [PATCH] Normal estimation

---
 .../Tutorials/Tutorial_reconstruction.txt     | 42 +++++++++++++++++++
 1 file changed, 42 insertions(+)

diff --git a/Documentation/doc/Documentation/Tutorials/Tutorial_reconstruction.txt b/Documentation/doc/Documentation/Tutorials/Tutorial_reconstruction.txt
index d407daa0c1b..b943a24c8a5 100644
--- a/Documentation/doc/Documentation/Tutorials/Tutorial_reconstruction.txt
+++ b/Documentation/doc/Documentation/Tutorials/Tutorial_reconstruction.txt
@@ -183,6 +183,48 @@ These functions directly modify the container:
 
 \subsection TutorialsReconstruction_preprocessing_normal Normal Estimation
 
+\ref Chapter_Poisson_Surface_Reconstruction "Poisson Surface
+Reconstruction" requires points with oriented normal vectors. To apply
+the algorithm to a raw point cloud, normals must be estimated first
+with one of these two functions:
+
+- `pca_estimate_normals()`
+- `jet_estimate_normals()`
+
+PCA is faster but jet is more accurate in the presence of high
+curvatures. These function only estimates the _direction_ of the
+normals, not their orientation (the orientation of the vectors might
+not be locally consistent). To properly orient the normals, the
+function `mst_orient_normals()` can be used. Notice that it can also
+be used directly on input normals if their orientation is not
+consistent.
+
+\code{.cpp}
+  // Point with normal vector stored in a std::pair.
+  typedef std::pair<Point, Vector> PointVectorPair;
+
+  // Use a container with normals
+  std::vector<PointVectorPair> points_with_normals;
+  for (std::vector<Point>::iterator it = points.begin (); it != points.end (); ++ i)
+    points_with_normals.push_back (std::make_pair (*it, Vector (0., 0., 0.)));
+
+  CGAL::jet_estimate_normals(points_with_normals.begin(), points_with_normals.end(),
+			     CGAL::First_of_pair_property_map<PointVectorPair>(),
+			     CGAL::Second_of_pair_property_map<PointVectorPair>(),
+			     24); // Use 24 neighbors
+
+  // Orientation of normals, returns iterator to first unoriented point
+  // (can be deleted
+  std::vector<PointVectorPair>::iterator unoriented_points_begin =
+    CGAL::mst_orient_normals(points_with_normals.begin(), points_with_normals.end(),
+			     CGAL::First_of_pair_property_map<PointVectorPair>(),
+			     CGAL::Second_of_pair_property_map<PointVectorPair>(),
+			     24); // Use 24 neighbors
+
+  points_with_normals.erase (unoriented_points_begin, points_with_normals.end ());
+\endcode
+
+
 \section TutorialsReconstruction_reconstruction Reconstruction
 
 \section TutorialsReconstruction_postprocessing Postprocessing