WIP: user manual

Point_set_3/doc/Point_set_3/Point_set_3.txt

@@ -6,11 +6,86 @@ namespace CGAL {
 \cgalAutoToc
 \author Simon Giraudot
 
-This chapter describes the ...
+\section Point_set_3_Principle General Principle
 
-\section Point_set_3_Definitions Definitions
+There exists many sensors that generate 3D point sets: laser scanners,
+LIDAR devices, cameras with photogrammetry post-processing... \cgal
+provides several algorithms to process such point sets (see
+\ref Chapter_Point_Set_Processing "Point Set Processing",
+\ref Chapter_Point_Set_Shape_Detection "Shape Detection",
+\ref Chapter_Advancing_Front_Surface_Reconstruction "Surface Reconstruction", etc.).
 
-Section on definitions here ...
+While these algorithms do not impose specific data structures to work
+on, \cgal provides a 3D point set structure to make it easier for the
+user to handle additional properties (such as normal vectors, colors,
+labels...) and to call \cgal algorithms on them.
+
+The point set data structure is based on a set of `std::vector`
+objects that each stores one property. When created, a
+`CGAL::Point_set_3<Gt>` object only contains 2 properties:
+
+- The "point" property (with `CGAL::Point_3<Gt>` type)
+
+- The "index" property (with `std::size_t` type) used to easily change
+the order of the points without having to move all the properties.
+
+Any property the user needs can be easily added, modified and
+removed. A property is identified by a unique name and a
+type. Convenience methods are provided to handle the property "normal"
+of type `CGAL::Vector_3<Gt>` that is a very common property on point
+sets.
+
+To avoid frequent memory allocation and disallocation, removal of
+points is handled by changing the "index" properties, putting the
+points marked as removed at the back of the indices and keeping track
+of the number of points marked as removed. It is then possible to
+actually free the memory by collecting this garbage.
+
+\section Point_set_3_Usage Simple Usage
+
+The data structure is designed to be easy to use despite its potential
+complexity when using properties. Several convenience methods are
+provided to handle points and normals without having to handle
+properties directly.
+
+The following example shows how to fill a point set with points, add a
+normal property, set the normal values, add or remove an item, etc.
+
+\cgalExample{Point_set_3/point_set.cpp}
+
+\section Point_set_3_Properties Using Additional Properties
+
+Every information in the point set is a property. A raw point set
+comes with "index" and "point" properties. As we saw in the previous
+section, the user can easily add a "normal" property. But this
+mechanism is generalized to any type of property.
+
+The following example shows how to define a color property and an
+intensity property, and how to modify the point set according to this.
+
+\cgalExample{Point_set_3/point_set_property.cpp}
+
+\section Point_set_3_Algorithms Applying CGAL Algorithms
+
+Most \cgal algorithms let the user free to choose whatever data
+structures he/she needs: the points and attributes are then access
+through iterators and property maps. The `CGAL::Point_set_3<Gt>`
+structure directly provides these iterators and property maps so that
+applying \cgal algorithms to it is straightforward.
+
+\subsection Point_set_3_PSP Point Set Processing
+
+When adding a new property to the point set, the associated property
+map is returned and can then be used as a standard property map. For
+points and normals, the property maps can recovered using the methods
+`point_pmap()` and `normal_pmap()`.
+
+The following example shows how to apply some algorithms from the
+\cgal library using a point set object:
+
+
+
+\subsection Point_set_3_IO Input/Output