namespace CGAL {
/*!

\mainpage User Manual
\anchor Chapter_Point_Set_3
\cgalAutoToc
\author Simon Giraudot


\cgal provides several algorithms for processing point sets, ranging from
\ref Chapter_Shape_Detection "Shape Detection" to
\ref Chapter_Advancing_Front_Surface_Reconstruction "Surface Reconstruction"
through standard \ref Chapter_Point_Set_Processing "Point Set Processing" tools.

While these algorithms do not impose specific data structures to work
on, this package 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.


\section Point_set_3_Principle General Principle

`CGAL::Point_set_3<Point,Vector>` is a vector based data structure
that contains a default property (named `point`) for the coordinates
of the points.

Any property the user needs can be easily added, modified, and
removed at runtime. A property is identified by a unique name and a
type. Convenience methods are provided to handle the normal vectors
(property named `normal`) that is a very common property on point sets.

To optimize memory allocation and deallocation, each point is associated an index.
The removal of a point simply marks the index as removed.
Internally, this avoids the property vectors to be modified at each removal,
and allow insertion of new points to reuse indices of points marked as removed.
In particular this implies that a point inserted after some removal was done
might has a non default initialized property.
If the user needs memory to be effectively deallocated, the element marked as removed
can be actually deleted from memory using `Point_set_3::garbage_collect()`.

\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, add a
normal property, set the normal values, add and remove a point.

\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 only with a `point` property. As we saw in the previous example,
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 an input data
structure: the points and attributes are then accessed through ranges
and property maps. The `CGAL::Point_set_3` class is a range that
provides property maps: applying \cgal algorithms is straightforward.

As the \ref PkgPointSetProcessing3Ref "Point Set Processing" algorithms
use \ref BGLNamedParameters to handle property maps, a method
`CGAL::Point_set_3::parameters()` is provided: it returns a named
parameter object with the right point and normal maps to read and
write in the point set object.

In addition, all input/output functions of the package
\ref Chapter_Point_Set_Processing "Point Set Processing" are overloaded so
that the user only has to call them with a `CGAL::Point_set_3`
object as a parameter (see \ref Point_set_3_IO).

\subsection Point_set_3_PSP Point Set Processing

The following example shows how to apply some algorithms from the
\cgal library using a point set object:

- generating a point set around a sphere

- estimating the normals with `CGAL::jet_estimate_normals()`

- simplifying the point set with `CGAL::grid_simplify_point_set()`

- detecting the sphere shape with `CGAL::Shape_detection::Efficient_RANSAC`

\cgalExample{Point_set_3/point_set_algo.cpp}

\subsection Point_set_3_IO Input/Output

The following example shows how to read a point set in the XYZ format, normalize
and invert the normal vectors, and write the result in the OFF
format.

\cgalExample{Point_set_3/point_set_read_xyz.cpp}

The PLY format is the usual choice when storing an arbitrary number of
additional properties of points is needed. \cgal provides a function
\link PkgPointSet3IOPLY `read_PLY()` \endlink that allows the user to recover any PLY
property wanted, provided the adapted PLY interpreter is
implemented.

A `CGAL::Point_set_3` object can be filled with all readable properties
of a PLY input. Each PLY property is read and stored into as a
property with similar name and type.

For example, if the following line is found in the PLY header:

> property uchar red

Then a property named `red` and with type `std::uint8_t` (`boost`
types are used because of their fixed memory size) will be
instantiated in the point set and filled with the corresponding
values.

Points and normals are recovered as properties with specific class
types (namely the template types `Point` and `Vector`). Other non-1D
properties are stored with simple number types. For example, if a
color is given with integer red, green and blue values, 3 integer
properties `red`, `green` and `blue` will be created. A
user-defined interpreter must be implemented if such properties should
be stored all together (a unique property `color` of type
`std::array` for example).

The following example shows how to use this interpreter and how to
access a specific property afterwards:

\cgalExample{Point_set_3/point_set_read_ply.cpp}

\subsection Point_set_3_Avdanced Advanced Usage

Using functions of \cgal to read files requires a slightly different
behavior because internally the properties of a point are defined
_before_ this point is inserted into the point set (which is not
possible with `CGAL::Point_set_3`). Although using the provided
overloads presented in the previous subsection should cover most
usages, we document the specific back inserters and property maps that
are used internally:

- `CGAL::Point_set_3::index_back_inserter()` is used as an output iterator that creates
new points.

- `CGAL::Point_set_3::point_push_map()` is a property map for setting the coordinates
of a point. It will first insert the point create in the structure if it has not been
created first (by `index_back_inserter()` for example).

- `CGAL::Point_set_3::normal_push_map()` works similarly but for normal vectors.

Such _push property maps_ are also available for other user-defined
properties (see `CGAL::Point_set_3::push_property_map()`).

The following example shows how to read OFF point without using the
overload provided for `CGAL::Point_set_3`:

\cgalExample{Point_set_3/point_set_advanced.cpp}

\subsection Point_set_3_Draw Draw a Point Set

A 3D point set can be visualized by calling the \link PkgDrawPointSet3D CGAL::draw<PS>() \endlink function as shown in the following example. This function opens a new window showing the given point set. A call to this function is blocking, that is the program continues as soon as the user closes the window.

\cgalExample{Point_set_3/draw_point_set_3.cpp}

This function requires `CGAL_Qt6`, and is only available if the macro `CGAL_USE_BASIC_VIEWER` is defined.
Linking with the cmake target `CGAL::CGAL_Basic_viewer` will link with `CGAL_Qt6` and add the definition `CGAL_USE_BASIC_VIEWER`.

\cgalFigureBegin{fig_draw_point_set,draw_point_set.png}
Result of the run of the draw_point_set_3 program. A window shows the 3D points and allows to navigate through the 3D scene.
\cgalFigureEnd

\section Point_set_3_History History

This package has been created to fill the need for a practical data
structure that handles points with a user-defined set of
properties. A property mechanism was already implemented in the
\ref Chapter_3D_Surface_mesh "Surface Mesh" package: all the classes
dedicated to the management of properties were extracted so that they
can be used in this package. `CGAL::Surface_mesh<Point>` and
`CGAL::Point_set_3<Point,Vector>` now follow a similar API for property
management.
*/
} /* namespace CGAL */
