namespace CGAL {
/*!

\mainpage User Manual
\anchor Chapter_CGAL_and_Boost_Property_Maps

\anchor chapterProperty_map

\cgalAutoToc

\authors Andreas Fabri and Laurent Saboret

\section Property_mapA 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 implementers 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="https://www.boost.org/libs/property_map/doc/property_map.html"><TT>https://www.boost.org/libs/property_map/doc/property_map.html</TT></A>

\section Property_mapCGAL 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 \ref Chapter_Point_Set_Processing "Point Set Processing" and
\ref Chapter_Poisson_Surface_Reconstruction "Poisson Surface Reconstruction"
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:

- `Identity_property_map<T>`
- `First_of_pair_property_map<Pair>` and `Second_of_pair_property_map<Pair>`
- `Nth_of_tuple_property_map<N, Tuple>`
- `Dereference_property_map<T>`

\subsection Property_mapExamplewithIdentity Example with Identity_property_map

The following example reads a point set and removes 5% of the points. It uses `Identity_property_map<Point_3>` as position property map.
\cgalExample{Point_set_processing_3/remove_outliers_example.cpp}

\subsection Property_mapExamplewithPairs 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{Point_set_processing_3/read_write_xyz_point_set_example.cpp}

\subsection Property_mapExamplewithTuples 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{Point_set_processing_3/average_spacing_example.cpp}

\section Property_mapCustom Writing Custom Property Maps

Property maps are especially useful when using predefined data
structures that are not part of the \cgal library: algorithms written
with property maps can be called on these data structures provided the
user writes the required property maps, without the need to create
deep copies of potentially large data into \cgal formats.

The following example shows how to write a readable point map and a
read-write normal map to run \cgal normal estimation and orientation
algorithm on raw `double` arrays:
\cgalExample{Property_map/custom_property_map.cpp}


*/
} /* namespace CGAL */

