Doc fixes according to Mariette's review

This commit is contained in:
Clement Jamin 2014-03-31 19:38:56 +02:00
parent 7cb5ef208d
commit ee1183f8b5
13 changed files with 164 additions and 104 deletions

View File

@ -4,10 +4,14 @@ namespace CGAL {
/*!
\ingroup PkgTriangulations
\cgalModifBegin
The class `Triangulation` is used to store and query the full cells and vertices of
a triangulationin dimension \f$ d\f$. A special vertex, named
a triangulationin dimension \f$ d\f$(see the
\ref Chapter_Triangulations "User Manual" for
a definition of "triangulation"). A special vertex, named
<I>infinite vertex</I>, is used to triangulate the outside of the convex
hull of the points in so called <I>infinite cells</I>.
\cgalModifEnd
Parameters
--------------
@ -55,7 +59,7 @@ A point in Euclidean space.
typedef TriangulationTraits::Point_d Point;
/*!
This indicates whether the dimension of the underlying space is static
This indicates whether the maximal dimension is static
(i.e.\ if the type of `Maximal_dimension` is `CGAL::Dimension_tag<int dim>`)
or dynamic (i.e.\ if the type of `Maximal_dimension` is
`CGAL::Dynamic_dimension_tag`).
@ -542,7 +546,7 @@ to the newly created full cells are output in the `out` output iterator.
interior and not contain any vertex all of whose incident full cells are in
\f$C\f$ . (This implies that `t.current_dimension()`\f$ \geq 2\f$ if
\f$|C|>1\f$ .) The boundary of \f$C\f$ must be a triangulation of the sphere
\f$ \mathcal S ^k-1\f$.
\f$ \mathcal S ^d-1\f$.
\cgalAdvancedEnd
*/
template < typename ForwardIterator, typename OutputIterator >

View File

@ -5,16 +5,16 @@ namespace CGAL {
\ingroup PkgTriangulations
This class is used for storing the combinatorial information of a triangulation
of dimension \f$ k\leq d\f$.
of dimension \f$ d\leq D\f$ (`D` is the maximal dimension).
Parameters
--------------
`Dimensionality` can be either <UL>
<LI>CGAL::`Dimension_tag<d>` for some integer `d`. This
<LI>CGAL::`Dimension_tag<D>` for some integer `D`. This
indicates that the triangulation data structure can store simplices (full cells) of dimension at most
`d`. The maximum dimension `d` is known by the compiler, which
`D`. The maximal dimension `D` is known by the compiler, which
triggers some optimizations. Or
<LI>CGAL::`Dynamic_dimension_tag`. In this case, the maximum
@ -78,16 +78,6 @@ bool is_valid(bool verbose = true) const;
/// \name Types
/// @{
/*!
\cgalAdvancedBegin
A data member of type `Full_cell_data` is stored in every full cell
(models of the concept `TriangulationDSFullCell`). It is used to mark
some full cells, during modifications of the triangulation data
structure.
\cgalAdvancedEnd
*/
typedef Hidden_type Full_cell_data;
/// @}
/// \name Vertex insertion

View File

@ -36,9 +36,10 @@ defined by the points in range `[start,end)`.
If the simplex is positively
oriented, then the positive side of sphere corresponds geometrically
to its bounded side.
\pre `std::distance(start,end)=D+1`, where
`Point_dimension_d(*it)` is \f$ D\f$ for all `it` in
`[start,end)`. `Point_dimension_d(p)` is also \f$ D\f$.
\cgalModifBegin
\pre If `Dimension`=`CGAL::``Dimension_tag<D>`,
then `std::distance(start,end)=D+1`.
\cgalModifEnd
The points in range
`[start,end)` must be affinely independent, i.e., the simplex must
not be flat.
@ -65,12 +66,9 @@ The points in range `[start,end)` and `p` are supposed to belong to the lower di
whose orientation is given by `orient`.
\pre `std::distance(start,end)=k+1` where \f$ k\f$ is the number of
points used to construct `orient`.
`Point_dimension_d(*it)` is \f$ D\f$ for all `it` in
`[start,end)`. `Point_dimension_d(p)` is also \f$ D\f$.
The points in range
`[start,end)` must be affinely independent, i.e., the simplex must
not be flat.
not be flat. `p` must be in the flat generated by this simplex.
*/
typedef Hidden_type In_flat_side_of_oriented_sphere_d;

View File

@ -0,0 +1,40 @@
/*!
\ingroup PkgTriangulationsConcepts
\cgalConcept
\cgalModifBegin
The concept `FullCellData` describes the requirements on the type which
is used to mark some full cells, during modifications of the triangulation data
structure.
\cgalModifEnd
\sa `TriangulationDataStructure`
\sa `TriangulationDSFullCell`
*/
class FullCellData
{
public:
/*!
Clear all data.
*/
void clear();
/*!
Mark the full cell as visited.
*/
void mark_visited();
/*!
Mark the full cell as not visited.
*/
void clear_visited();
/*!
Returns `true` if the full cell is <b>not</b> marked as visited, `false` otherwise.
*/
bool is_clear() const;
/*!
Returns `true` if the full cell is marked as visited, `false` otherwise.
*/
bool is_visited() const;
}; /* end FullCellData */

View File

@ -31,16 +31,23 @@ public:
/// @{
/*!
Must be the same as the nested type
`TriangulationDataStructure::Full_cell_handle` of the `TriangulationDataStructure` in which the `TriangulationDSFace` is
\cgalModifBegin
The `Triangulation_data_structure` in which the `TriangulationDSFace` is
defined/used.
Must be a model of the `TriangulationDataStructure` concept.
\cgalModifEnd
*/
typedef Hidden_type Triangulation_data_structure;
/*!
Must be the same as the nested type
`Triangulation_data_structure::Full_cell_handle`.
*/
typedef Hidden_type Full_cell_handle;
/*!
Must be the same as the nested type
`TriangulationDataStructure::Vertex_handle` of the `TriangulationDataStructure` in which the `TriangulationDSFace` is
defined/used.
`Triangulation_data_structure::Vertex_handle`.
*/
typedef Hidden_type Vertex_handle;

View File

@ -34,11 +34,19 @@ public:
/// \name Types
/// @{
/*!
\cgalModifBegin
The `Triangulation_data_structure` in which the `TriangulationDSFullCell` is
defined/used.
Must be a model of the `TriangulationDataStructure` concept.
\cgalModifEnd
*/
typedef Hidden_type Triangulation_data_structure;
/*!
A handle to a vertex. It must be the same as the
nested type `TriangulationDataStructure::Vertex_handle` of the `TriangulationDataStructure` in which the
`TriangulationDSFullCell` is defined/used.
nested type `TriangulationDataStructure::Vertex_handle`.
*/
typedef Hidden_type Vertex_handle;
@ -50,8 +58,7 @@ typedef Hidden_type Vertex_handle_iterator;
/*!
A handle to a full cell. It must be the same as the
nested type `TriangulationDataStructure::Full_cell_handle` of the `TriangulationDataStructure` in which the
`TriangulationDSFullCell` is defined/used.
nested type `TriangulationDataStructure::Full_cell_handle`.
*/
typedef Hidden_type Full_cell_handle;
@ -299,19 +306,23 @@ void * for_compact_container() const;
void * & for_compact_container();
/*!
Reads (possibly) non-combinatorial information about a full cell from the stream `is`
into `c`.
*/
template<class TriangulationDataStructure>
std::istream& operator>>(std::istream & is, Triangulation_ds_full_cell<TriangulationDataStructure> & c);
/*!
\cgalModifBegin
Writes (possibly) non-combinatorial information about full cell `c` to the stream
`os`.
\cgalModifEnd
*/
template<class TriangulationDataStructure>
std::ostream& operator<<(std::ostream & os, const Triangulation_ds_full_cell<TriangulationDataStructure> & c);
/*!
\cgalModifBegin
Reads from stream `is` the full cell information written
by `operator<<`.
\cgalModifEnd
*/
template<class TriangulationDataStructure>
std::istream& operator>>(std::istream & is, Triangulation_ds_full_cell<TriangulationDataStructure> & c);
/// @}
}; /* end TriangulationDSFullCell */

View File

@ -29,11 +29,19 @@ public:
/// \name Types
/// @{
/*!
\cgalModifBegin
The `Triangulation_data_structure` in which the `TriangulationDSVertex` is
defined/used.
Must be a model of the `TriangulationDataStructure` concept.
\cgalModifEnd
*/
typedef Hidden_type Triangulation_data_structure;
/*!
A handle to a cell. It must be the same as the
nested type `TriangulationDataStructure::Full_cell_handle` of the `TriangulationDataStructure` in which the
`TriangulationDSVertex` is defined/used.
nested type `TriangulationDataStructure::Full_cell_handle`.
*/
typedef Hidden_type Full_cell_handle;
@ -121,19 +129,22 @@ void * for_compact_container() const;
void * & for_compact_container();
/*!
Reads (possibly) non-combinatorial information about a vertex from the stream `is`
into `v`.
*/
template<class TriangulationDataStructure>
std::istream& operator>>(std::istream & is, Triangulation_ds_vertex<TriangulationDataStructure> & v);
/*!
\cgalModifBegin
Writes (possibly) non-combinatorial information about vertex `v` to the stream
`os`.
\cgalModifEnd
*/
template<class TriangulationDataStructure>
std::ostream& operator<<(std::ostream & os, const Triangulation_ds_vertex<TriangulationDataStructure> & v);
/*!
\cgalModifBegin
Reads from stream `is` the vertex information written by `operator<<`.
\cgalModifEnd
*/
template<class TriangulationDataStructure>
std::istream& operator>>(std::istream & is, Triangulation_ds_vertex<TriangulationDataStructure> & v);
/// @}
}; /* end TriangulationDSVertex */

View File

@ -95,6 +95,12 @@ The full cell type. A model of the concept `TriangulationDSFullCell`.
*/
typedef Hidden_type Full_cell;
/*!
\cgalModifBegin
A model of the concept `FullCellData`.
\cgalModifEnd
*/
typedef Hidden_type Full_cell_data;
/*!
The concept `TriangulationDataStructure` also defines a type for

View File

@ -9,14 +9,11 @@ It brings the geometric ingredient to the
definition of a triangulation, while the combinatorial ingredient is brought by
the second template parameter, `TriangulationDataStructure`.
Inserting a range of points in a triangulation is optimized using
spatial sorting, thus besides the requirements below,
a class provided as `TriangulationTraits` should also satisfy the concept
`SpatialSortingTraits_d`.
\cgalRefines ::SpatialSortingTraits_d If a range of points is inserted, the
traits must refine `SpatialSortingTraits_d`. This is not needed
if the points are inserted one by one.
\cgalModifBegin
\cgalRefines `SpatialSortingTraits_d` If a range of points is inserted, the
traits must refine `SpatialSortingTraits_d` (this operation is optimized using
spatial sorting). This is not required if the points are inserted one by one.
\cgalModifEnd
\cgalHasModel `CGAL::Cartesian_d<FT, Dim, LA>`
\cgalHasModel `CGAL::Epick_d<Dim>` (recommended)
@ -31,13 +28,13 @@ public:
/// \name Types
/// @{
/*!
A type representing the dimension of the underlying space. it can be static
(`Maximal_dimension`=`CGAL::``Dimension_tag<int dim>`) or
dynamic (`Maximal_dimension`=`CGAL::``Dynamic_dimension_tag`).
This dimension must match the dimension of the predicate
`Orientation_d` but not necessarily the one of `Point_d`.
/*!
\cgalModifBegin
A type representing the dimension of the `Orientation_d` predicate
(but not necessarily the one of `Point_d`).
Tt can be static (`Dimension`=`CGAL::``Dimension_tag<int dim>`) or
dynamic (`Dimension`=`CGAL::``Dynamic_dimension_tag`).
\cgalModifEnd
*/
typedef Hidden_type Dimension;
@ -46,24 +43,16 @@ A type representing a point in Euclidean space.
*/
typedef Hidden_type Point_d;
/*!
Functor returning the dimension of a `Point_d`.
Must provide
`int operator()(Point_d p)` returning the dimension of \f$ p\f$.
*/
typedef Hidden_type Point_dimension_d;
/*!
A predicate object that must provide the
templated operator
`template<typename ForwardIterator> Orientation operator()(ForwardIterator start, ForwardIterator end)`.
The operator returns
`CGAL::POSITIVE`, `CGAL::NEGATIVE` or `CGAL::COPLANAR` depending on
the orientation of the simplex defined by the points in the range `[start, end)`.
\pre `std::distance(start,end)=D+1`, where
`Point_dimension_d(*it)` is \f$ D\f$ for all `it` in `[start,end)`.
`template<typename ForwardIterator> Orientation operator()(ForwardIterator start, ForwardIterator end)`.
\cgalModifBegin
The operator returns the orientation of the simplex defined by the points
in the range `[start, end)`; the value can be
`CGAL::POSITIVE`, `CGAL::NEGATIVE` or `CGAL::COPLANAR`.
\pre If `Dimension`=`CGAL::``Dimension_tag<D>`, then `std::distance(start,end)=D+1`.
\cgalModifEnd
*/
typedef Hidden_type Orientation_d;
@ -73,11 +62,13 @@ the templated operator
`template<typename ForwardIterator> bool operator()(ForwardIterator start, ForwardIterator end, const Point_d & p)`.
The operator returns `true` if and only if point `p` is
contained in the affine space spanned by the points in the range `[start, end)`. That affine space is also called the <I>affine hull</I> of the points
in the range.
\pre The \f$ k\f$ points in the range
in the range.
\cgalModifBegin
\pre If `Dimension`=`CGAL::``Dimension_tag<D>`,
then `std::distance(start,end)=D+1`.
The points in the range
must be affinely independent.
`Point_dimension_d(*it)` is \f$ D\f$ for all `it` in
`[start,end)`, for some \f$ D\f$.
\cgalModifEnd
\f$ 2\leq k\leq D\f$.
*/
@ -112,11 +103,13 @@ The flat spanned by the points in
the range `R=[start, end)` can be oriented in two different ways,
the operator
returns an object that allow to orient that flat so that `R=[start, end)`
defines a positive simplex.
\pre The \f$ k\f$ points in the range
must be affinely independent.
`Point_dimension_d(*it)` is \f$ D\f$ for all `it` in `R` for
some \f$ D\f$.
defines a positive simplex.
\cgalModifBegin
\pre If `Dimension`=`CGAL::``Dimension_tag<D>`,
then `std::distance(start,end)=D+1`.
The points in range
`[start,end)` must be affinely independent.
\cgalModifEnd
\f$ 2\leq k\leq D\f$.
*/
@ -124,8 +117,6 @@ typedef Hidden_type Construct_flat_orientation_d;
/*!
CJTODO: update this?
A predicate object that must provide the
templated operator
`template<typename ForwardIterator> Orientation operator()(Flat_orientation_d orient,ForwardIterator start, ForwardIterator end)`.
@ -136,11 +127,7 @@ the orientation of the simplex defined by the points in the range `[start, end)`
The points are supposed to belong to the lower dimensional flat
whose orientation is given by `orient`.
\pre `std::distance(start,end)=k` where \f$ k\f$ is the number of
points
used to construct `orient`.
`Point_dimension_d(*it)` is \f$ D\f$ for all `it` in
`[start,end)` where \f$ D\f$ is the dimension of the points used to
construct `orient`.
points used to construct `orient`.
\f$ 2\leq k\leq D\f$.
*/

View File

@ -73,6 +73,8 @@ following concepts:
`TriangulationDSFace`
`FullCellData`
## Triangulations ##
`TriangulationTraits`
@ -89,26 +91,26 @@ The latter two concepts are also abbreviated respectively as `TrVertex` and `TrF
## Triangulation data structure ##
\ref ::CGAL::Triangulation_data_structure<Dimensionality, TriangulationDSVertex, TriangulationDSFullCell>
- `CGAL::Triangulation_data_structure<Dimensionality, TriangulationDSVertex, TriangulationDSFullCell>`
\ref ::CGAL::Triangulation_ds_vertex<TriangulationDataStructure>
- `CGAL::Triangulation_ds_vertex<TriangulationDataStructure>`
\ref ::CGAL::Triangulation_ds_full_cell<TriangulationDataStructure, TDSFullCellStoragePolicy>
- `CGAL::Triangulation_ds_full_cell<TriangulationDataStructure, TDSFullCellStoragePolicy>`
\ref ::CGAL::Triangulation_face<TriangulationDataStructure>
- `CGAL::Triangulation_face<TriangulationDataStructure>`
## (Geometric) triangulations ##
\ref ::CGAL::Triangulation<TriangulationTraits, TriangulationDataStructure>
- `CGAL::Triangulation<TriangulationTraits, TriangulationDataStructure>`
\ref ::CGAL::Delaunay_triangulation<DelaunayTriangulationTraits, TriangulationDataStructure>
- `CGAL::Delaunay_triangulation<DelaunayTriangulationTraits, TriangulationDataStructure>`
\ref ::CGAL::Triangulation_vertex<TriangulationTraits, Data, TriangulationDSVertex>
- `CGAL::Triangulation_vertex<TriangulationTraits, Data, TriangulationDSVertex>`
\ref ::CGAL::Triangulation_full_cell<TriangulationTraits, Data, TriangulationDSFullCell>
- `CGAL::Triangulation_full_cell<TriangulationTraits, Data, TriangulationDSFullCell>`
## Enums ##
\ref ::CGAL::Triangulation::Locate_type
- `CGAL::Triangulation::Locate_type`
*/

View File

@ -36,6 +36,7 @@ class Triangulation_ds_full_cell
typedef typename TDS::Maximal_dimension Maximal_dimension;
public:
typedef typename TDS Triangulation_data_structure;
typedef typename TDS::Face Face;
typedef typename TDS::Vertex_handle Vertex_handle; /* Concept */
typedef typename TDS::Vertex_const_handle Vertex_const_handle;
@ -287,6 +288,7 @@ class Triangulation_ds_full_cell<void, StoragePolicy>
{
public:
typedef internal::Triangulation::Dummy_TDS TDS;
typedef typename TDS Triangulation_data_structure;
typedef TDS::Vertex_handle Vertex_handle;
typedef TDS::Vertex_const_handle Vertex_const_handle;
typedef TDS::Full_cell_handle Full_cell_handle;

View File

@ -33,6 +33,7 @@ class Triangulation_ds_vertex
typedef Triangulation_ds_vertex<TDS> Self;
public:
typedef typename TDS Triangulation_data_structure;
typedef typename TDS::Full_cell_handle Full_cell_handle; /* Concept */
template <typename TDS2>
@ -137,9 +138,9 @@ operator<<(std::ostream & os, const Triangulation_ds_vertex<TDS> & v) /* Concept
template<>
class Triangulation_ds_vertex<void>
{
typedef internal::Triangulation::Dummy_TDS Triangulation_ds;
public:
typedef Triangulation_ds::Full_cell_handle Full_cell_handle; /* Concept */
typedef internal::Triangulation::Dummy_TDS Triangulation_data_structure;
typedef Triangulation_data_structure::Full_cell_handle Full_cell_handle; /* Concept */
template <typename TDS2>
struct Rebind_TDS /* Concept */
{

View File

@ -28,6 +28,7 @@ class Triangulation_face
{
typedef typename internal::Dimen_plus_one<typename TDS::Maximal_dimension>::type Dimen_plus;
public:
typedef typename TDS Triangulation_data_structure;
typedef typename TDS::Full_cell_handle Full_cell_handle; /* Concept */
typedef typename TDS::Vertex_handle Vertex_handle; /* Concept */
typedef internal::S_or_D_array<int, Dimen_plus> Indices;