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 The class `Periodic_3_Delaunay_triangulation_3` represents a
Delaunay triangulation in three-dimensional periodic space. 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. \tparam TDS must be a model of the concept `TriangulationDataStructure_3`. Its default value
Its default value is 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<>>>`.
`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 : class Periodic_3_Delaunay_triangulation_3 :
public Periodic_3_triangulation_3<Periodic_3DelaunayTriangulationTraits_3, public Periodic_3_triangulation_3<PT, TDS>
TriangulationDataStructure_3> {
{
public: public:
/// \name Creation /// \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>`. class `Periodic_3_Delaunay_triangulation_3<Periodic_3DelaunayTriangulationTraits_3,TriangulationDataStructure_3>`.
\tparam Traits must be a model of the `DelaunayTriangulationTraits_3` concept. \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 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 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 \cgalModels Periodic_3DelaunayTriangulationTraits_3
*/ */
template< typename Traits, typename Periodic_3Offset_3 > template< typename Traits, typename Offset >
class Periodic_3_Delaunay_triangulation_traits_3 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: public:
}; /* end Periodic_3_Delaunay_triangulation_traits_3 */ }; /* end Periodic_3_Delaunay_triangulation_traits_3 */
} /* end namespace CGAL */ } /* end namespace CGAL */

View File

@ -7,19 +7,18 @@ namespace CGAL {
The class `Periodic_3_regular_triangulation_3` represents a The class `Periodic_3_regular_triangulation_3` represents a
weighted Delaunay triangulation in three-dimensional periodic space. 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 Its default value is
`Triangulation_data_structure_3<Regular_triangulation_vertex_base_3<PT,Periodic_3_triangulation_ds_vertex_base_3<> >, `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<>>>`. 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 : class Periodic_3_regular_triangulation_3 :
public Periodic_3_triangulation_3<Periodic_3TriangulationTraits_3, public Periodic_3_triangulation_3<PT, TDS>
TriangulationDataStructure_3> {
{
public: public:
/// \name Types /// \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`. \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; 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. 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)`. same as the previous method for facet `(c,i)`.
\pre \f$ i\in\{0,1,2,3\}\f$ \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 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>`. class `Periodic_3_regular_triangulation_3<Periodic_3RegularTriangulationTraits_3,TriangulationDataStructure_3>`.
\tparam Traits must be a model of the `RegularTriangulationTraits_3` concept. \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`. \tparam Offset must be a model of the concept `Periodic_3Offset_3` and defaults to `Periodic_3_offset_3`.
\cgalModels Periodic_3RegularTriangulationTraits_3
If `Traits` is a `CGAL::Filtered_kernel` (detected when `Traits::Has_filtered_predicates` exists If `Traits` is a `CGAL::Filtered_kernel` (detected when `Traits::Has_filtered_predicates` exists
and is `true`), this class automatically provides filtered predicates. and is `true`), this class automatically provides filtered predicates.
By default, this holds for `CGAL::Exact_predicates_inexact_constructions_kernel` and By default, this holds for `CGAL::Exact_predicates_inexact_constructions_kernel` and
`CGAL::Exact_predicates_exact_constructions_kernel`. `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 : 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: public:
}; /* end Periodic_3_regular_triangulation_traits_3 */ }; /* end Periodic_3_regular_triangulation_traits_3 */
} /* end namespace CGAL */ } /* end namespace CGAL */

View File

@ -4,18 +4,18 @@ namespace CGAL {
/*! /*!
\ingroup PkgPeriodic3Triangulation3MainClasses \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$. 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 \tparam TDS must be a model of the concept `TriangulationDataStructure_3`
with some additional functionality in cells and vertices. with some additional functionality in cells and vertices.
Its default value is 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<>>>`. `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_Delaunay_triangulation_3`
\sa `Periodic_3_regular_triangulation_3`
*/ */
template< typename PT, typename TDS > template< typename PT, typename TDS >
class Periodic_3_triangulation_3 { 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; 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; typedef Geometric_traits::Tetrahedron_3 Tetrahedron;
/*! /*!
Represents a point-offset pair. The point in the Represents a point-offset pair. The point in the pair lies in the original domain.
pair lies in the original domain. Note that the inner type is `Point`.
*/ */
typedef std::pair< Point, Offset > typedef std::pair< Point, Offset > Periodic_point;
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> typedef std::pair< Point_3, Offset > Periodic_point_3;
Periodic_segment;
/*! /*!
A periodic segment. Note that the inner type is `Periodic_point`.
*/ */
typedef array< Periodic_point, 3> typedef array< Periodic_point, 2> Periodic_segment;
Periodic_triangle;
/*! /*!
A periodic segment. Note that the inner type is `Periodic_point_3`.
*/ */
typedef array< Periodic_point, 4> typedef array< Periodic_point_3, 2> Periodic_segment_3;
Periodic_tetrahedron;
/*!
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 /*! \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: /// \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 /// \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; Periodic_tetrahedron periodic_tetrahedron(const Cell_handle c, Offset offset) const;
/// \name /// \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 /// Note that a traits class providing exact constructions should be
/// used in order to guarantee the following operations to be exact /// used in order to guarantee the following operations to be exact
/// (as opposed to computing the triangulation only, which requires /// (as opposed to computing the triangulation only, which requires
/// only exact predicates). /// only exact predicates).
///
/// @{ /// @{
/*! /*!
Converts the `Periodic_point` `s` (point-offset pair) to the Converts the periodic point of type `PP` to a `Point_3`. The type `PP` can be either
corresponding `Point` in \f$ \mathbb R^3\f$. `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) template<typename PS>
const; 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} \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 \tparam PTr must be one of the \cgal periodic triangulation classes. <I>In the current
implementation, only `Periodic_3_Delaunay_triangulation_3` is implementation, only `Periodic_3_Delaunay_triangulation_3` is supported for.</I>
supported for `PTr`.</I>
`PTr::Vertex` has to be a model of the concept `PTr::Vertex` has to be a model of the concept
`Periodic_3TriangulationHierarchyVertexBase_3`. `Periodic_3TriangulationHierarchyVertexBase_3`.
@ -21,14 +20,14 @@ supported for `PTr`.</I>
`Periodic_3DelaunayTriangulationTraits_3`. `Periodic_3DelaunayTriangulationTraits_3`.
`Periodic_3_triangulation_hierarchy_3` offers exactly the same functionalities as `PTr`. `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 Most of these functionalities (point location, insertion, removal \f$ \ldots\f$ )
improve their efficiency by using the hierarchic structure. are overloaded to improve their efficiency by using the hierarchic structure.
Note that, since the algorithms that are provided are randomized, the Note that, since the algorithms that are provided are randomized, the
running time of constructing a triangulation with a hierarchy may be running time of constructing a triangulation with a hierarchy may be
improved when shuffling the data points. 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 hierarchy into a file will lose the hierarchic structure and reading
it from the file will result in an ordinary triangulation whose it from the file will result in an ordinary triangulation whose
efficiency will be the same as `PTr`. efficiency will be the same as `PTr`.

View File

@ -8,7 +8,7 @@ The class `Periodic_3_triangulation_traits_3` is designed as a default traits cl
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 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 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 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 \cgalModels Periodic_3TriangulationTraits_3
*/ */
template< typename Traits, typename Periodic_3Offset_3 > template< typename Traits, typename Offset >
class Periodic_3_triangulation_traits_3 : public Traits { class Periodic_3_triangulation_traits_3 : public Traits {
public: public:
}; /* end Periodic_3_triangulation_traits_3 */ }; /* end Periodic_3_triangulation_traits_3 */

View File

@ -273,7 +273,7 @@ The second parameter `Periodic_3Offset_3` defaults to
The kernels `Cartesian`, `Homogeneous`, The kernels `Cartesian`, `Homogeneous`,
`Simple_cartesian`, `Simple_homogeneous` and `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 `TriangulationTraits_3`, `DelaunayTriangulationTraits_3`, and
`RegularTriangulationTraits_3`. `RegularTriangulationTraits_3`.
The periodic triangulation classes provide exact The periodic triangulation classes provide exact
@ -423,7 +423,7 @@ data structure.
\cgalExample{Periodic_3_triangulation_3/simple_regular_example.cpp} \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, This example shows the incremental construction of a 3D regular triangulation,
and the removal of a vertex. It uses the default parameter of the 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_example.cpp
\example Periodic_3_triangulation_3/simple_regular_example.cpp
\example Periodic_3_triangulation_3/colored_vertices.cpp \example Periodic_3_triangulation_3/colored_vertices.cpp
\example Periodic_3_triangulation_3/periodic_adding_handles.cpp \example Periodic_3_triangulation_3/periodic_adding_handles.cpp
\example Periodic_3_triangulation_3/covering.cpp \example Periodic_3_triangulation_3/covering.cpp

View File

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