Improved Periodic_3 documentation

This commit is contained in:
Mael Rouxel-Labbé 2017-05-17 15:07:12 +02:00
parent e338cce067
commit 596fb64ffe
10 changed files with 154 additions and 68 deletions

View File

@ -7,18 +7,16 @@ namespace CGAL {
The class `Periodic_3_Delaunay_triangulation_3` represents a
Delaunay triangulation in three-dimensional periodic space.
\tparam Periodic_3DelaunayTriangulationTraits_3 is the geometric traits class.
\tparam PT must be a model of the concept `Periodic_3DelaunayTriangulationTraits_3`.
\tparam TriangulationDataStructure_3 is the triangulation data structure.
Its default value is
`Triangulation_data_structure_3<Triangulation_vertex_base_3<PT,Periodic_3_triangulation_ds_vertex_base_3<>>,Triangulation_cell_base_3<PT,Periodic_3_triangulation_ds_cell_base_3<>>>`.
\tparam TDS must be a model of the concept `TriangulationDataStructure_3`. Its default value
is `Triangulation_data_structure_3<Triangulation_vertex_base_3<PT,Periodic_3_triangulation_ds_vertex_base_3<>>,Triangulation_cell_base_3<PT,Periodic_3_triangulation_ds_cell_base_3<>>>`.
*/
template< typename Periodic_3DelaunayTriangulationTraits_3, typename TriangulationDataStructure_3 >
template< typename PT, typename TDS >
class Periodic_3_Delaunay_triangulation_3 :
public Periodic_3_triangulation_3<Periodic_3DelaunayTriangulationTraits_3,
TriangulationDataStructure_3>
{
public Periodic_3_triangulation_3<PT, TDS>
{
public:
/// \name Creation

View File

@ -8,7 +8,7 @@ The class `Periodic_3_Delaunay_triangulation_traits_3` is designed as a default
class `Periodic_3_Delaunay_triangulation_3<Periodic_3DelaunayTriangulationTraits_3,TriangulationDataStructure_3>`.
\tparam Traits must be a model of the `DelaunayTriangulationTraits_3` concept.
\tparam Periodic_3Offset_3 must be a model of the concept `Periodic_3Offset_3` and defaults to `Periodic_3_offset_3`.
\tparam Offset must be a model of the concept `Periodic_3Offset_3` and defaults to `Periodic_3_offset_3`.
If `Traits` is a `CGAL::Filtered_kernel` (detected when `Traits::Has_filtered_predicates` exists
and is `true`), this class automatically provides filtered predicates. Similarly, statically filtered predicates
@ -18,9 +18,9 @@ By default, this holds for `CGAL::Exact_predicates_inexact_constructions_kernel`
\cgalModels Periodic_3DelaunayTriangulationTraits_3
*/
template< typename Traits, typename Periodic_3Offset_3 >
template< typename Traits, typename Offset >
class Periodic_3_Delaunay_triangulation_traits_3
: public Periodic_3_triangulation_traits_base_3 < Traits, Periodic_3Offset_3> {
: public Periodic_3_triangulation_traits_base_3 < Traits, Offset> {
public:
}; /* end Periodic_3_Delaunay_triangulation_traits_3 */
} /* end namespace CGAL */

View File

@ -7,19 +7,18 @@ namespace CGAL {
The class `Periodic_3_regular_triangulation_3` represents a
weighted Delaunay triangulation in three-dimensional periodic space.
\tparam Periodic_3RegularTriangulationTraits_3 is the geometric traits class.
\tparam PT must be a model of the concept `Periodic_3RegularTriangulationTraits_3`.
\tparam TriangulationDataStructure_3 is the triangulation data structure.
\tparam TDS must be a model of the concept `TriangulationDataStructure_3`.
Its default value is
`Triangulation_data_structure_3<Regular_triangulation_vertex_base_3<PT,Periodic_3_triangulation_ds_vertex_base_3<> >,
Regular_triangulation_cell_base_3<PT,Periodic_3_triangulation_ds_cell_base_3<>>>`.
*/
template< typename Periodic_3TriangulationTraits_3, typename TriangulationDataStructure_3 >
template< typename PT, typename TDS >
class Periodic_3_regular_triangulation_3 :
public Periodic_3_triangulation_3<Periodic_3TriangulationTraits_3,
TriangulationDataStructure_3>
{
public Periodic_3_triangulation_3<PT, TDS>
{
public:
/// \name Types
@ -230,7 +229,7 @@ specifying where to start the search.
\pre `c` is a cell of `rt` and `p` lies in the original domain `domain`.
*/
Vertex_handle nearest_power_vertex(const Weighted_point & p,
Vertex_handle nearest_power_vertex(const Bare_point & p,
Cell_handle c = Cell_handle()) const;
/// @}
@ -343,13 +342,13 @@ Bare_point dual(Cell_handle c) const;
/*!
Returns the dual of facet `f`, which is a periodic segment.
*/
Periodic_segment dual(Facet f) const;
Periodic_segment_3 dual(Facet f) const;
/*!
same as the previous method for facet `(c,i)`.
\pre \f$ i\in\{0,1,2,3\}\f$
*/
Periodic_segment dual(Cell_handle c, int i) const;
Periodic_segment_3 dual(Cell_handle c, int i) const;
/*!
Returns in the output iterator the points of the dual polygon of

View File

@ -8,19 +8,18 @@ The class `Periodic_3_regular_triangulation_traits_3` is designed as a default t
class `Periodic_3_regular_triangulation_3<Periodic_3RegularTriangulationTraits_3,TriangulationDataStructure_3>`.
\tparam Traits must be a model of the `RegularTriangulationTraits_3` concept.
\tparam Periodic_3Offset_3 must be a model of the concept `Periodic_3Offset_3` and defaults to `Periodic_3_offset_3`.
\cgalModels Periodic_3RegularTriangulationTraits_3
\tparam Offset must be a model of the concept `Periodic_3Offset_3` and defaults to `Periodic_3_offset_3`.
If `Traits` is a `CGAL::Filtered_kernel` (detected when `Traits::Has_filtered_predicates` exists
and is `true`), this class automatically provides filtered predicates.
By default, this holds for `CGAL::Exact_predicates_inexact_constructions_kernel` and
`CGAL::Exact_predicates_exact_constructions_kernel`.
\cgalModels Periodic_3RegularTriangulationTraits_3
*/
template< typename Traits, typename Periodic_3Offset_3 >
template< typename Traits, typename Offset >
class Periodic_3_regular_triangulation_traits_3 :
public Periodic_3_triangulation_traits_base_3< Traits, Periodic_3Offset_3 > {
public Periodic_3_triangulation_traits_base_3< Traits, Offset > {
public:
}; /* end Periodic_3_regular_triangulation_traits_3 */
} /* end namespace CGAL */

View File

@ -4,18 +4,18 @@ namespace CGAL {
/*!
\ingroup PkgPeriodic3Triangulation3MainClasses
The class `Periodic_triangulation_3` represents a 3-dimensional
The class `Periodic_3_triangulation_3` represents a 3-dimensional
triangulation of a point set in \f$ \mathbb T_c^3\f$.
\tparam PT must be a model of the `Periodic_3TriangulationTraits_3` concept.
\tparam PT must be a model of the concept `Periodic_3TriangulationTraits_3`.
\tparam TDS must be a model of `TriangulationDataStructure_3` concept
with some additional functionality in cells and vertices.
\tparam TDS must be a model of the concept `TriangulationDataStructure_3`
with some additional functionality in cells and vertices.
Its default value is
`Triangulation_data_structure_3<Triangulation_vertex_base_3<PT,Periodic_3_triangulation_ds_vertex_base_3<>>,Triangulation_cell_base_3<PT,Periodic_3_triangulation_ds_cell_base_3<>>>`.
\sa `Periodic_3_Delaunay_triangulation_3`
\sa `Periodic_3_regular_triangulation_3`
*/
template< typename PT, typename TDS >
class Periodic_3_triangulation_3 {
@ -53,9 +53,18 @@ store the number of sheets in each direction of space.
typedef array<int,3> Covering_sheets;
/*!
The point type of the triangulation.
\note This type is equal to `Geometric_traits::Point_3` when considering periodic
Delaunay triangulations and to `Geometric_traits::Weighted_point_3` when
considering periodic weighted Delaunay triangulations.
*/
typedef Geometric_traits::Point_3 Point;
typedef TDS::Vertex::Point Point;
/*!
The geometric basic 3D point type.
*/
typedef Geometric_traits::Point_3 Point_3;
/*!
@ -73,35 +82,53 @@ typedef Geometric_traits::Triangle_3 Triangle;
typedef Geometric_traits::Tetrahedron_3 Tetrahedron;
/*!
Represents a point-offset pair. The point in the
pair lies in the original domain.
Represents a point-offset pair. The point in the pair lies in the original domain.
Note that the inner type is `Point`.
*/
typedef std::pair< Point, Offset >
Periodic_point;
typedef std::pair< Point, Offset > Periodic_point;
/*!
Represents a point-offset pair. The point in the pair lies in the original domain.
Note that the inner type is `Point_3`.
*/
typedef array< Periodic_point, 2>
Periodic_segment;
typedef std::pair< Point_3, Offset > Periodic_point_3;
/*!
A periodic segment. Note that the inner type is `Periodic_point`.
*/
typedef array< Periodic_point, 3>
Periodic_triangle;
typedef array< Periodic_point, 2> Periodic_segment;
/*!
A periodic segment. Note that the inner type is `Periodic_point_3`.
*/
typedef array< Periodic_point, 4>
Periodic_tetrahedron;
typedef array< Periodic_point_3, 2> Periodic_segment_3;
/*!
A periodic triangle. Note that the inner type is `Periodic_point`.
*/
typedef array< Periodic_point, 3> Periodic_triangle;
/*!
A periodic triangle. Note that the inner type is `Periodic_point_3`.
*/
typedef array< Periodic_point_3, 3> Periodic_triangle_3;
/*!
A periodic tetrahedron. Note that the inner type is `Periodic_point`.
*/
typedef array< Periodic_point, 4> Periodic_tetrahedron;
/*!
A periodic tetrahedron. Note that the inner type is `Periodic_point_3`.
*/
typedef array< Periodic_point_3, 4> Periodic_tetrahedron_3;
/// @}
/*! \name
Only vertices (\f$ 0\f$-faces) and cells (\f$ 3\f$-faces) are stored. Edges (\f$ 1\f$-faces) and facets (\f$ 2\f$-faces) are not explicitly represented and thus there are no corresponding classes (see Section \ref P3Triangulation3secintro).
Only vertices (\f$ 0\f$-faces) and cells (\f$ 3\f$-faces) are stored.
Edges (\f$ 1\f$-faces) and facets (\f$ 2\f$-faces) are not explicitly represented
and thus there are no corresponding classes (see Section \ref P3Triangulation3secintro).
*/
/// @{
@ -208,6 +235,8 @@ typedef Triangulation_data_structure::Facet_circulator Facet_circulator;
/// @}
/// \name Geometric Iterators:
/// The following iterators have value type `Periodic_segment`, `Periodic_triangle`,
/// and `Periodic_tetrahedron`, which have inner type `Point`.
/// @{
/*!
@ -511,6 +540,8 @@ size_type number_of_stored_facets() const;
/// @}
/// \name Geometric Access Functions
/// The following functions return object of types `Periodic_segment`,
/// `Periodic_triangle`, and `Periodic_tetrahedron`, which have inner type `Point`.
/// @{
/*!
@ -599,33 +630,92 @@ A translation in accordance with `offset` is applied on the point-offet pairs.
Periodic_tetrahedron periodic_tetrahedron(const Cell_handle c, Offset offset) const;
/// \name
/// \warning The following functions were renamed with %CGAL 4.11 to clarify
/// that they return geometric objects with inner type `Point_3`.
///
/// Note that a traits class providing exact constructions should be
/// used in order to guarantee the following operations to be exact
/// (as opposed to computing the triangulation only, which requires
/// only exact predicates).
///
/// @{
/*!
Converts the `Periodic_point` `s` (point-offset pair) to the
corresponding `Point` in \f$ \mathbb R^3\f$.
Converts the periodic point of type `PP` to a `Point_3`. The type `PP` can be either
`Periodic_point` or `Periodic_point_3`.
*/
Point point(const Periodic_point & p ) const;
template<typename PP>
Point_3 construct_point(const PP & pp) const;
/*!
Converts the `Periodic_segment` `s` to a `Segment`.
Converts the `Point` `p` to a `Point_3`.
*/
Segment segment(const Periodic_segment & s) const;
Point_3 construct_point(const Point & p) const;
/*!
Converts the `Periodic_triangle` `t` to a `Triangle`.
Same as above, with offsets.
*/
Triangle triangle(const Periodic_triangle & t) const;
template<typename P>
Point_3 construct_point(const P& p1, const Offset& o1) const;
/*!
Converts the `Periodic_tetrahedron` `t` to a `Tetrahedron`.
Converts the periodic segment of type `PS` to a `Segment`. The type `PS` can be
either `Periodic_segment` or `Periodic_segment_3`.
*/
Tetrahedron tetrahedron(const Periodic_tetrahedron & t)
const;
template<typename PS>
Segment construct_segment(const PS & s) const;
/*!
Creates a segment from two points. The type `P` can be either `Point` or `Point_3`.
*/
template<typename P>
Segment construct_segment(const P& p1, const P& p2) const;
/*!
Same as above, with offsets.
*/
template<typename P>
Segment construct_segment(const P& p1, const P& p2, const Offset& o1, const Offset& o2) const;
/*!
Converts the periodic triangle of type `PT` to a `Triangle`. The type `PT` can
be either `Periodic_triangle` or `Periodic_triangle_3`.
*/
template<typename PT>
Triangle construct_triangle(const PT & t) const;
/*!
Creates a triangle from three points. The type `P` can be either `Point` or `Point_3`.
*/
template<typename P>
Triangle construct_triangle(const P& p1, const P& p2, const P& p3) const;
/*!
Same as above, with offsets.
*/
template<typename P>
Triangle construct_triangle(const P& p1, const P& p2, const P& p3,
const Offset& o1, const Offset& o2, const Offset& o3) const;
/*!
Converts the periodic tetrahedron of type `PT` to a `Tetrahedron`. The type `PT`
can be either `Periodic_tetrahedron` or `Periodic_tetrahedron_3`.
*/
template<typename PT>
Tetrahedron construct_tetrahedron(const PT & t) const;
/*!
Creates a tetrahedron from four points. The type `P` can be either `Point` or `Point_3`.
*/
template<typename P>
Tetrahedron construct_tetrahedron(const P& p1, const P& p2, const P& p3, const P& p4) const;
/*!
Same as above, with offsets.
*/
template<typename P>
Tetrahedron construct_tetrahedron(const P& p1, const P& p2, const P& p3, const P& p4,
const Offset& o1, const Offset& o2, const Offset& o3, const Offset& o4) const;
/// @}

View File

@ -10,9 +10,8 @@ location queries.
\cgalHeading{Template Parameters}
It is templated by a parameter which must be instantiated by one of the \cgal periodic triangulation classes. <I>In the current
implementation, only `Periodic_3_Delaunay_triangulation_3` is
supported for `PTr`.</I>
\tparam PTr must be one of the \cgal periodic triangulation classes. <I>In the current
implementation, only `Periodic_3_Delaunay_triangulation_3` is supported for.</I>
`PTr::Vertex` has to be a model of the concept
`Periodic_3TriangulationHierarchyVertexBase_3`.
@ -21,14 +20,14 @@ supported for `PTr`.</I>
`Periodic_3DelaunayTriangulationTraits_3`.
`Periodic_3_triangulation_hierarchy_3` offers exactly the same functionalities as `PTr`.
Most of them (point location, insertion, removal \f$ \ldots\f$ ) are overloaded to
improve their efficiency by using the hierarchic structure.
Most of these functionalities (point location, insertion, removal \f$ \ldots\f$ )
are overloaded to improve their efficiency by using the hierarchic structure.
Note that, since the algorithms that are provided are randomized, the
running time of constructing a triangulation with a hierarchy may be
improved when shuffling the data points.
However, the I/O operations are not overloaded. So, writing a
However, the I/O operations are not overloaded. Thus, writing a
hierarchy into a file will lose the hierarchic structure and reading
it from the file will result in an ordinary triangulation whose
efficiency will be the same as `PTr`.

View File

@ -5,10 +5,10 @@ namespace CGAL {
\ingroup PkgPeriodic3Triangulation3TraitsClasses
The class `Periodic_3_triangulation_traits_3` is designed as a default traits class for the
class `Periodic_3_triangulation_3<Periodic_3TriangulationTraits_3,TriangulationDataStructure_3>`.
class `Periodic_3_triangulation_3<Periodic_3TriangulationTraits_3,TriangulationDataStructure_3>`.
\tparam Traits must be a model of the `TriangulationTraits_3` concept.
\tparam Periodic_3Offset_3 must be a model of the concept `Periodic_3Offset_3` and defaults to `Periodic_3_offset_3`.
\tparam Offset must be a model of the concept `Periodic_3Offset_3` and defaults to `Periodic_3_offset_3`.
If `Traits` is a `CGAL::Filtered_kernel` (detected when `Traits::Has_filtered_predicates` exists
and is `true`), this class automatically provides filtered predicates. Similarly, statically filtered predicates
@ -18,7 +18,7 @@ By default, this holds for `CGAL::Exact_predicates_inexact_constructions_kernel`
\cgalModels Periodic_3TriangulationTraits_3
*/
template< typename Traits, typename Periodic_3Offset_3 >
template< typename Traits, typename Offset >
class Periodic_3_triangulation_traits_3 : public Traits {
public:
}; /* end Periodic_3_triangulation_traits_3 */

View File

@ -273,7 +273,7 @@ The second parameter `Periodic_3Offset_3` defaults to
The kernels `Cartesian`, `Homogeneous`,
`Simple_cartesian`, `Simple_homogeneous` and
`Filtered_kernel` can all be used as \cgalModels of the concepts
`Filtered_kernel` can all be used as models of the concepts
`TriangulationTraits_3`, `DelaunayTriangulationTraits_3`, and
`RegularTriangulationTraits_3`.
The periodic triangulation classes provide exact
@ -423,7 +423,7 @@ data structure.
\cgalExample{Periodic_3_triangulation_3/simple_regular_example.cpp}
\subsubsection Periodic_3_triangulation_3P3TR3FirstExample Point Insertion and Vertex Removal
\subsubsection Periodic_3_triangulation_3P3TR3PointInsertionAndVertexRemoval Point Insertion and Vertex Removal
This example shows the incremental construction of a 3D regular triangulation,
and the removal of a vertex. It uses the default parameter of the

View File

@ -1,5 +1,6 @@
/*!
\example Periodic_3_triangulation_3/simple_example.cpp
\example Periodic_3_triangulation_3/simple_regular_example.cpp
\example Periodic_3_triangulation_3/colored_vertices.cpp
\example Periodic_3_triangulation_3/periodic_adding_handles.cpp
\example Periodic_3_triangulation_3/covering.cpp

View File

@ -6,8 +6,8 @@ namespace CGAL
*
* @class Robust_weighted_circumcenter_filtered_traits_3
*
* Overrides Construct_weighted_circumcenter_3(), Compute_squared_radius_3(),
* and Compute_squared_radius_smallest_orthogonal_sphere_3() with robust versions.
* Overrides the kernel functors Construct_weighted_circumcenter_3, Compute_squared_radius_3,
* and Compute_squared_radius_smallest_orthogonal_sphere_3 with robust versions.
*
* Robustness is achieved by using exact computations if the geometric configuration
* is close to degenerate.