diff --git a/Periodic_3_triangulation_3/doc/Periodic_3_triangulation_3/CGAL/Periodic_3_Delaunay_triangulation_3.h b/Periodic_3_triangulation_3/doc/Periodic_3_triangulation_3/CGAL/Periodic_3_Delaunay_triangulation_3.h index c42d450b91a..c25a62192e3 100644 --- a/Periodic_3_triangulation_3/doc/Periodic_3_triangulation_3/CGAL/Periodic_3_Delaunay_triangulation_3.h +++ b/Periodic_3_triangulation_3/doc/Periodic_3_triangulation_3/CGAL/Periodic_3_Delaunay_triangulation_3.h @@ -95,7 +95,8 @@ Cell_handle loc, int li, int lj); /// @} /*! \name -The following method allows one to insert several points. It returns the number of inserted points. +The following method allows the insertion of several points and returns +the number of inserted points. */ /// @{ @@ -121,27 +122,28 @@ bool is_large_point_set = false); /// @{ /*! -Moves the point stored in `v` to `p`, while preserving the Delaunay -property. This performs an action semantically equivalent to `remove(v)` -followed by `insert(p)`, but is supposedly faster when the point has -not moved much. Returns the handle to the new vertex. -\pre `p` lies in the original domain `domain`. -*/ -Vertex_handle move_point(Vertex_handle v, const Point & p); +Moves the point stored in `v` to `p`, while preserving the Delaunay +property. This performs an action semantically equivalent to `remove(v)` +followed by `insert(p)`, but is supposedly faster when the point has +not moved much. Returns the handle to the new vertex. +\pre `p` lies in the original domain `domain`. +*/ +Vertex_handle move_point(Vertex_handle v, const Point & p); -/// @} +/// @} -/*! \name Removal +/*! \name Removal + +The following methods remove points in the triangulation. When a vertex `v` is removed from a triangulation, all the cells incident to `v` must be removed, and the polyhedral region consisting of all the tetrahedra that are incident to `v` must be -re-triangulated. So, the problem reduces to triangulating a polyhedral +re-triangulated. The problem thus reduces to triangulating a polyhedral region, while preserving its boundary, or to compute a constrained triangulation. This is known to be sometimes impossible: the Schönhardt polyhedron cannot be triangulated \cgalCite{cgal:s-cgehd-98}. - However, when dealing with Delaunay triangulations, the case of such polyhedra that cannot be re-triangulated cannot happen, so \cgal proposes a vertex removal. diff --git a/Periodic_3_triangulation_3/doc/Periodic_3_triangulation_3/CGAL/Periodic_3_Delaunay_triangulation_traits_3.h b/Periodic_3_triangulation_3/doc/Periodic_3_triangulation_3/CGAL/Periodic_3_Delaunay_triangulation_traits_3.h index 8219d09cc88..ceda8fa9239 100644 --- a/Periodic_3_triangulation_3/doc/Periodic_3_triangulation_3/CGAL/Periodic_3_Delaunay_triangulation_traits_3.h +++ b/Periodic_3_triangulation_3/doc/Periodic_3_triangulation_3/CGAL/Periodic_3_Delaunay_triangulation_traits_3.h @@ -11,7 +11,7 @@ class `Periodic_3_Delaunay_triangulation_3 -class Periodic_3_Delaunay_triangulation_traits_3 : public Traits { +class Periodic_3_Delaunay_triangulation_traits_3 + : public Periodic_3_triangulation_traits_base_3 < Traits, Periodic_3Offset_3> { public: }; /* end Periodic_3_Delaunay_triangulation_traits_3 */ } /* end namespace CGAL */ diff --git a/Periodic_3_triangulation_3/doc/Periodic_3_triangulation_3/CGAL/Periodic_3_regular_triangulation_3.h b/Periodic_3_triangulation_3/doc/Periodic_3_triangulation_3/CGAL/Periodic_3_regular_triangulation_3.h index 2fe338b5fcd..0aeb3c0702f 100644 --- a/Periodic_3_triangulation_3/doc/Periodic_3_triangulation_3/CGAL/Periodic_3_regular_triangulation_3.h +++ b/Periodic_3_triangulation_3/doc/Periodic_3_triangulation_3/CGAL/Periodic_3_regular_triangulation_3.h @@ -10,8 +10,9 @@ weighted Delaunay triangulation in three-dimensional periodic space. \tparam Periodic_3RegularTriangulationTraits_3 is the geometric traits class. \tparam TriangulationDataStructure_3 is the triangulation data structure. -Its default value is -`Triangulation_data_structure_3>,Regular_triangulation_cell_base_3>>`. +Its default value is +`Triangulation_data_structure_3 >, + Regular_triangulation_cell_base_3>>`. */ template< typename Periodic_3TriangulationTraits_3, typename TriangulationDataStructure_3 > @@ -25,8 +26,8 @@ public: /// @{ /*! -*/ -typedef Periodic_3RegularTriangulationTraits_3::Bare_point Bare_point; +*/ +typedef Periodic_3RegularTriangulationTraits_3::Point_3 Bare_point; /*! The type for points diff --git a/Periodic_3_triangulation_3/doc/Periodic_3_triangulation_3/CGAL/Periodic_3_regular_triangulation_traits_3.h b/Periodic_3_triangulation_3/doc/Periodic_3_triangulation_3/CGAL/Periodic_3_regular_triangulation_traits_3.h index 545a3cc9293..b7834a2a68e 100644 --- a/Periodic_3_triangulation_3/doc/Periodic_3_triangulation_3/CGAL/Periodic_3_regular_triangulation_traits_3.h +++ b/Periodic_3_triangulation_3/doc/Periodic_3_triangulation_3/CGAL/Periodic_3_regular_triangulation_traits_3.h @@ -7,23 +7,20 @@ namespace CGAL { The class `Periodic_3_regular_triangulation_traits_3` is designed as a default traits class for the class `Periodic_3_regular_triangulation_3`. -\tparam K 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 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 -This template class is specialized for -`CGAL::Regular_triangulation_euclidean_traits_3`, -so that it automatically provides -filtered predicates. This holds implicitly for -`CGAL::Regular_triangulation_euclidean_traits_3`, -as `CGAL::Exact_predicates_inexact_constructions_kernel` is an -instantiation of `CGAL::Filtered_kernel`. +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`. */ -template< typename K, typename Periodic_3Offset_3 > -class Periodic_3_regular_triangulation_traits_3 : - public Regular_triangulation_euclidean_traits_3< K > { +template< typename Traits, typename Periodic_3Offset_3 > +class Periodic_3_regular_triangulation_traits_3 : + public Periodic_3_triangulation_traits_base_3< Traits, Periodic_3Offset_3 > { public: }; /* end Periodic_3_regular_triangulation_traits_3 */ } /* end namespace CGAL */ diff --git a/Periodic_3_triangulation_3/doc/Periodic_3_triangulation_3/CGAL/Periodic_3_triangulation_traits_3.h b/Periodic_3_triangulation_3/doc/Periodic_3_triangulation_3/CGAL/Periodic_3_triangulation_traits_3.h index a849673050f..ed1815bf22a 100644 --- a/Periodic_3_triangulation_3/doc/Periodic_3_triangulation_3/CGAL/Periodic_3_triangulation_traits_3.h +++ b/Periodic_3_triangulation_3/doc/Periodic_3_triangulation_3/CGAL/Periodic_3_triangulation_traits_3.h @@ -4,8 +4,6 @@ namespace CGAL { /*! \ingroup PkgPeriodic3Triangulation3TraitsClasses -\warning Using this traits class for Periodic_3_Delaunay_triangulation_3 is deprecated. You should use Periodic_3_Delaunay_triangulation_traits_3 instead. - The class `Periodic_3_triangulation_traits_3` is designed as a default traits class for the class `Periodic_3_triangulation_3`. @@ -13,7 +11,7 @@ class `Periodic_3_triangulation_3 > -\cgalHasModel CGAL::Regular_triangulation_cell_base_with_weighted_circumcenter_3 > +\cgalHasModel CGAL::Regular_triangulation_cell_base_3 > +\cgalHasModel CGAL::Regular_triangulation_cell_base_with_weighted_circumcenter_3 > -The template parameter `Periodic_3RegularTriangulationTraits_3` is expected to be the same as the -traits class used in `Periodic_3_regular_triangulation_3`. +The template parameter `Periodic_3RegularTriangulationTraits_3` is expected to be the same as the +traits class used in `CGAL::Periodic_3_regular_triangulation_3`. -\sa `TriangulationDataStructure_3` -\sa `Periodic_3TriangulationDSVertexBase_3` +\sa `TriangulationDataStructure_3` +\sa `Periodic_3RegularTriangulationDSVertexBase_3` */ diff --git a/Periodic_3_triangulation_3/doc/Periodic_3_triangulation_3/Concepts/Periodic_3RegularTriangulationTraits_3.h b/Periodic_3_triangulation_3/doc/Periodic_3_triangulation_3/Concepts/Periodic_3RegularTriangulationTraits_3.h index 14c8d626cef..c49c07714f9 100644 --- a/Periodic_3_triangulation_3/doc/Periodic_3_triangulation_3/Concepts/Periodic_3RegularTriangulationTraits_3.h +++ b/Periodic_3_triangulation_3/doc/Periodic_3_triangulation_3/Concepts/Periodic_3RegularTriangulationTraits_3.h @@ -3,8 +3,8 @@ \ingroup PkgPeriodic3Triangulation3Concepts \cgalConcept -The concept `Periodic_3RegularTriangulationTraits_3` is the first template parameter of the class -`Periodic_3_regular_triangulation_3`. +The concept `Periodic_3RegularTriangulationTraits_3` is the first template parameter +of the class `CGAL::Periodic_3_regular_triangulation_3`. It refines the concept `RegularTriangulationTraits_3` from the \cgal 3D Triangulations. It redefines the geometric objects, predicates and constructions to @@ -36,65 +36,83 @@ public: /*! A predicate object that must provide the function operators: -`Oriented_side operator()(Weighted_point_3 p, Weighted_point_3 q, Weighted_point_3 r, Weighted_point_3 s, Weighted_point_3 t)`, +`Oriented_side operator()(Weighted_point_3 p, Weighted_point_3 q, Weighted_point_3 r, Weighted_point_3 s, Weighted_point_3 t)`, -which determines the position of `t` with respect to the power sphere of `p, q, r, s`. +which determines the position of `t` with respect to the power sphere of `p, q, r, s`. `Oriented_side operator()(Weighted_point_3 p, Weighted_point_3 q, Weighted_point_3 r, Weighted_point_3 s, Weighted_point_3 t, -Periodic_3_offset_3 o_p, Periodic_3_offset_3 o_q, Periodic_3_offset_3 o_r, Periodic_3_offset_3 o_s, Periodic_3_offset_3 o_t)`, +Periodic_3_offset_3 o_p, Periodic_3_offset_3 o_q, Periodic_3_offset_3 o_r, Periodic_3_offset_3 o_s, Periodic_3_offset_3 o_t)`, which is the same for the point-offset pair `(t,o_t)` with respect to the power sphere of the point-offset pairs -`(p,o_p), (q,o_q), (r,o_r), (s,o_s)`. -\pre `p`, `q`, `r`, `s`, `t` lie inside the domain and `p, q, r, s` are not coplanar. +`(p,o_p), (q,o_q), (r,o_r), (s,o_s)`. +\pre `p`, `q`, `r`, `s`, `t` lie inside the domain and `p, q, r, s` are not coplanar.
-In addition, only when vertex removal is used, the predicate must provide the following function operators: +When vertex removal is used, the predicate must in addition provide the following function operators: -`Oriented_side operator()( Weighted_point_3 p, Weighted_point_3 q, Weighted_point_3 r, Weighted_point_3 t)`, +`Oriented_side operator()( Weighted_point_3 p, Weighted_point_3 q, Weighted_point_3 r, Weighted_point_3 t)`, -which has a definition similar to the previous method, for coplanar points, -with the power circle of `p,q,r`. +which has a definition similar to the previous method, for coplanar points, +with the power circle of `p,q,r`. `Oriented_side operator()( Weighted_point_3 p, Weighted_point_3 q, Weighted_point_3 r, Weighted_point_3 t, -Periodic_3_offset_3 o_p, Periodic_3_offset_3 o_q, Periodic_3_offset_3 o_r, Periodic_3_offset_3 o_t)`, - -which is the same for point-offset pairs. - -\pre `p`, `q`, `r`, `t` lie inside the domain, `p, q, r` are not collinear, and `p, q, r, t` are coplanar. - - -`Oriented_side operator()( Weighted_point_3 p, Weighted_point_3 q, Weighted_point_3 t)`, - -which is the same for collinear points, and the power segment of `p` and `q`, - -`Oriented_side operator()( Weighted_point_3 p, Weighted_point_3 q, Weighted_point_3 t, -Periodic_3_offset_3 o_p, Periodic_3_offset_3 o_q, Periodic_3_offset_3 o_t)`, - -which is the same for point-offset pairs. - -\pre `p`, `q`, `t` lie inside the domain, `p` and `q` have different Bare_points, and `p, q, t` are collinear. - - -`Oriented_side operator()( Weighted_point_3 p, Weighted_point_3 q)`, - -which is the same for equal points, that is when `p` and `q` -have equal coordinates, then it returns the comparison of the weights. - -`Oriented_side operator()( Weighted_point_3 p, Weighted_point_3 q, -Periodic_3_offset_3 o_p, Periodic_3_offset_3 o_q)`, +Periodic_3_offset_3 o_p, Periodic_3_offset_3 o_q, Periodic_3_offset_3 o_r, Periodic_3_offset_3 o_t)`, which is the same for point-offset pairs. -\pre `p` and `q` lie inside the domain and have equal Bare_points. +\pre `p`, `q`, `r`, `t` lie inside the domain, `p, q, r` are not collinear, and `p, q, r, t` are coplanar. -*/ -typedef unspecified_type Power_test_3; + +`Oriented_side operator()( Weighted_point_3 p, Weighted_point_3 q, Weighted_point_3 t)`, + +which is the same for collinear points, and the power segment of `p` and `q`, + +`Oriented_side operator()( Weighted_point_3 p, Weighted_point_3 q, Weighted_point_3 t, +Periodic_3_offset_3 o_p, Periodic_3_offset_3 o_q, Periodic_3_offset_3 o_t)`, + +which is the same for point-offset pairs. + +\pre `p`, `q`, `t` lie inside the domain, `p` and `q` have different Bare_points, and `p, q, t` are collinear. + + +`Oriented_side operator()( Weighted_point_3 p, Weighted_point_3 q)`, + +which is the same for equal points, that is when `p` and `q` +have equal coordinates, then it returns the comparison of the weights. + +`Oriented_side operator()( Weighted_point_3 p, Weighted_point_3 q, +Periodic_3_offset_3 o_p, Periodic_3_offset_3 o_q)`, + +which is the same for point-offset pairs. + +\pre `p` and `q` lie inside the domain and have equal Bare_points. + +*/ +typedef unspecified_type Power_side_of_oriented_power_sphere_3; /// @} /// \name -/// In addition, only when vertex removal is used, the traits class must provide the following predicate object +/// @{ + +/*! +A predicate object that must provide the function operators: + +`Orientation operator()(Weighted_point_3 p, Weighted_point_3 q, Weighted_point_3 r, Weighted_point_3 s, FT w)`, + +which compares the weight of the smallest sphere orthogonal to the input weighted +points with the input weight `w` and returns a `SMALLER`, `EQUAL`, or `LARGER`. + +\pre `p`, `q`, `r`, and `s` lie inside the domain. + +*/ +typedef unspecified_type Compare_weighted_squared_radius_3; + +/// @} + +/// \name +/// When vertex removal is used, the traits class must in addition provide the following predicate object /// @{ /*! @@ -117,8 +135,8 @@ typedef unspecified_type Coplanar_orientation_3; /// @} /// \name -/// In addition, only when the dual operations are used, the traits -/// class must provide the following constructor object: +/// When the dual operations are used, the traits +/// class must in addition provide the following constructor object: /// @{ /*! @@ -159,13 +177,15 @@ Periodic_3_regular_triangulation_traits_3(const Periodic_3_regular_triangulation /*! -*/ -Power_test_3 power_test_3_object(); +*/ +Power_side_of_oriented_power_sphere_3 power_side_of_oriented_power_sphere_3_object(); + +Compare_weighted_squared_radius_3 compare_weighted_squared_radius_3_object(); /// @} /// \name -/// The following functions must be provided if vertex removal is +/// The following function must be provided if vertex removal is /// used; otherwise dummy functions can be provided. /// @{ @@ -180,13 +200,13 @@ Coplanar_orientation_3 coplanar_3_orientation_3_object(); /// The following function must be provided only if the methods of /// `Periodic_3_regular_triangulation_3` returning elements of the /// Voronoi diagram are used; otherwise a dummy function can be -/// provided: +/// provided. /// @{ /*! -*/ -Construct_circumcenter_3 construct_weighted_circumcenter_3_object(); +*/ +Construct_weighted_circumcenter_3 construct_weighted_circumcenter_3_object(); /// @} diff --git a/Periodic_3_triangulation_3/doc/Periodic_3_triangulation_3/Concepts/Periodic_3TriangulationDSCellBase_3.h b/Periodic_3_triangulation_3/doc/Periodic_3_triangulation_3/Concepts/Periodic_3TriangulationDSCellBase_3.h index 0997fd07c67..26ea6f35584 100644 --- a/Periodic_3_triangulation_3/doc/Periodic_3_triangulation_3/Concepts/Periodic_3TriangulationDSCellBase_3.h +++ b/Periodic_3_triangulation_3/doc/Periodic_3_triangulation_3/Concepts/Periodic_3TriangulationDSCellBase_3.h @@ -11,7 +11,7 @@ and \ref TDS3secdesign), a cell stores handles to its four vertices and to its four neighbor cells. The vertices and neighbors are indexed 0, 1, 2 and 3. Neighbor `i` lies opposite to vertex `i`. -For periodic triangulation the cell base class needs to +For periodic triangulations, the cell base class needs to additionally store an offset for each vertex. Only the last three bits of each integer are required to be stored. The remaining part does not contain any information. diff --git a/Periodic_3_triangulation_3/doc/Periodic_3_triangulation_3/Concepts/Periodic_3TriangulationDSVertexBase_3.h b/Periodic_3_triangulation_3/doc/Periodic_3_triangulation_3/Concepts/Periodic_3TriangulationDSVertexBase_3.h index e5394c0ea37..841a3197793 100644 --- a/Periodic_3_triangulation_3/doc/Periodic_3_triangulation_3/Concepts/Periodic_3TriangulationDSVertexBase_3.h +++ b/Periodic_3_triangulation_3/doc/Periodic_3_triangulation_3/Concepts/Periodic_3TriangulationDSVertexBase_3.h @@ -31,10 +31,9 @@ public: /// @{ /*! -A model of the concept -`Periodic_3Offset_3` -*/ -typedef unspecified_type Periodic_3_offset_3; +A model of the concept `Periodic_3Offset_3` +*/ +typedef unspecified_type Periodic_3_offset_3; /// @} diff --git a/Periodic_3_triangulation_3/doc/Periodic_3_triangulation_3/Concepts/Periodic_3TriangulationTraits_3.h b/Periodic_3_triangulation_3/doc/Periodic_3_triangulation_3/Concepts/Periodic_3TriangulationTraits_3.h index 8a4c323bca0..390456c6fef 100644 --- a/Periodic_3_triangulation_3/doc/Periodic_3_triangulation_3/Concepts/Periodic_3TriangulationTraits_3.h +++ b/Periodic_3_triangulation_3/doc/Periodic_3_triangulation_3/Concepts/Periodic_3TriangulationTraits_3.h @@ -196,12 +196,11 @@ Periodic_3_triangulation_traits_3(const Periodic_triangulation_traits_3 & tr); /// @{ /*! -Set the size of the -fundamental domain. This is necessary to evaluate predicates -correctly. -\pre `domain` represents a cube. -*/ -void set_domain(Iso_cuboid_3 domain); +Set the size of the fundamental domain. This is necessary to evaluate predicates +correctly. +\pre `domain` represents a cube. +*/ +void set_domain(const Iso_cuboid_3& domain); /// @} diff --git a/Periodic_3_triangulation_3/doc/Periodic_3_triangulation_3/PackageDescription.txt b/Periodic_3_triangulation_3/doc/Periodic_3_triangulation_3/PackageDescription.txt index 6f35717e71b..07ae717b1eb 100644 --- a/Periodic_3_triangulation_3/doc/Periodic_3_triangulation_3/PackageDescription.txt +++ b/Periodic_3_triangulation_3/doc/Periodic_3_triangulation_3/PackageDescription.txt @@ -16,7 +16,11 @@ \cgalPkgPicture{p3Delaunay3_small.jpg} \cgalPkgSummaryBegin \cgalPkgAuthors{Manuel Caroli, Aymeric Pellé, and Monique Teillaud} -\cgalPkgDesc{This package allows to build and handle triangulations of point sets in the three dimensional flat torus. Triangulations are built incrementally and can be modified by insertion or removal of vertices. They offer point location facilities. The package provides Delaunay triangulations and offers nearest neighbor queries and primitives to build the dual Voronoi diagrams.} +\cgalPkgDesc{This package allows to build and handle triangulations of point sets +in the three dimensional flat torus. Triangulations are built incrementally and +can be modified by insertion or removal of vertices. They offer point location +facilities. The package provides Delaunay and regular triangulations and offers +nearest neighbor queries and primitives to build the dual Voronoi diagrams.} \cgalPkgManuals{Chapter_3D_Periodic_Triangulations,PkgPeriodic3Triangulation3} \cgalPkgSummaryEnd \cgalPkgShortInfoBegin @@ -29,14 +33,14 @@ \cgalPkgDescriptionEnd The main classes of the 3D Periodic Triangulation package are -`Periodic_3_triangulation_3`, -`Periodic_3_Delaunay_triangulation_3`, -and `Periodic_3_regular_triangulation_3`. +`CGAL::Periodic_3_triangulation_3`, +`CGAL::Periodic_3_Delaunay_triangulation_3`, +and `CGAL::Periodic_3_regular_triangulation_3`. They contain functionality to access triangulations and to run queries on them. `CGAL::Periodic_3_Delaunay_triangulation_3` can construct and modify Delaunay triangulations, while -`Periodic_3_regular_triangulation_3` can do it for weighted Delaunay +`CGAL::Periodic_3_regular_triangulation_3` can do it for weighted Delaunay triangulations. They take the geometric traits as well as the triangulation data structure as template parameters. @@ -79,6 +83,7 @@ of the concept `Periodic_3Offset_3`. - `Periodic_3TriangulationDSCellBase_3` - `Periodic_3RegularTriangulationDSCellBase_3` +- `Periodic_3RegularTriangulationDSVertexBase_3` - `Periodic_3Offset_3` @@ -98,9 +103,9 @@ of the concept `Periodic_3Offset_3`. ### Traits Classes ### +- `CGAL::Periodic_3_triangulation_traits_3` - `CGAL::Periodic_3_Delaunay_triangulation_traits_3` - -- `CGAL::Periodic_3_regular_triangulation_traits_3` +- `CGAL::Periodic_3_regular_triangulation_traits_3` ## Enums ## diff --git a/Periodic_3_triangulation_3/doc/Periodic_3_triangulation_3/Periodic_3_triangulation_3.txt b/Periodic_3_triangulation_3/doc/Periodic_3_triangulation_3/Periodic_3_triangulation_3.txt index 876492022b2..7d76e350c56 100644 --- a/Periodic_3_triangulation_3/doc/Periodic_3_triangulation_3/Periodic_3_triangulation_3.txt +++ b/Periodic_3_triangulation_3/doc/Periodic_3_triangulation_3/Periodic_3_triangulation_3.txt @@ -150,8 +150,8 @@ five points are co-spherical. Note however that the \cgal implementation computes a uniquely defined triangulation even in these cases \cgalCite{cgal:dt-pvr3d-03}. -This implementation is fully dynamic: it supports both insertions of -points and vertex removal. +This implementation is fully dynamic: it supports both point insertion +and vertex removal. \section Periodic_3_triangulation_3regular Regular Triangulation @@ -167,8 +167,8 @@ definition. As for Delaunay triangulations, \cgal computes a uniquely defined regular triangulation even in degenerate cases \cgalCite{cgal:dt-pvrdr-06}. -The implementation is fully dynamic: it supports both insertions of -points and vertex removal. +The implementation is fully dynamic: it supports both point insertion +and vertex removal. \section Periodic_3_triangulation_3Triangulation Triangulation Hierarchy @@ -181,25 +181,10 @@ chapter \ref chapterTriangulation3 "3D Triangulations" to the periodic case. We have chosen the prefix "Periodic_3" to emphasize that the triangulation is periodic in all three directions of space. - - -The main classes `Periodic_3_Delaunay_triangulation_3`, -`Periodic_3_regular_triangulation_3`, and -`Periodic_3_triangulation_3` provide high-level geometric -functionality and are responsible for the geometric validity. -`Periodic_3_Delaunay_triangulation_3` contains all the -functionality that is special to Delaunay triangulations, such as -point insertion and vertex removal, the side-of-sphere test, finding -the conflicting region of a given point, dual functions etc. -`Periodic_3_regular_triangulation_3` does the same for regular -triangulations. - - -`Periodic_3_triangulation_3` contains all the functionality -that is common to triangulations in general, such as location of a -point in the triangulation \cgalCite{cgal:dpt-wt-02}, access functions, -geometric queries like the orientation test etc. - +The main classes `Periodic_3_triangulation_3`, +`Periodic_3_Delaunay_triangulation_3`, and `Periodic_3_regular_triangulation_3` +provide high-level geometric functionality and are responsible +for the geometric validity. They are built as layers on top of a triangulation data structure, which stores their combinatorial structure. This separation between the geometry and the combinatorics is reflected in the software design @@ -216,7 +201,18 @@ combinatorial structure, described in Section \ref P3Triangulation3sectds. -\subsection P3Triangulation3secTraits The Geometric Traits Parameter +The class `Periodic_3_triangulation_3` contains all the functionality +that is common to triangulations in general, such as location of a +point in the triangulation \cgalCite{cgal:dpt-wt-02}, access functions, +geometric queries like the orientation test etc. +The class `Periodic_3_Delaunay_triangulation_3` contains all the +functionality that is specific to Delaunay triangulations, such as +point insertion and vertex removal, the side-of-sphere test, finding +the conflicting region of a given point, computation of dual functions, etc. +The class `Periodic_3_regular_triangulation_3` does the same for regular +triangulations. + +\subsection P3Triangulation3secTraits The Geometric Traits Parameter \subsubsection P3Triangulation3secTraitsP3T3 Traits for Periodic Triangulations @@ -225,13 +221,12 @@ The first template parameter of the triangulation class is the geometric traits class, described by the concept `Periodic_3TriangulationTraits_3`. It is different to the TriangulationTraits_3 (see -chapter \ref Triangulation3secTraits "3D Triangulations") in that it -implements all objects, predicates and constructions with -using offsets. +chapter \ref Triangulation3secTraits "3D Triangulations") in that it +implements all objects, predicates and constructions using offsets. The class `Periodic_3_triangulation_traits_3` provides the required functionality. It expects two template -parameters: A model of the concept `TriangulationTraits_3` +parameters: a model of the concept `TriangulationTraits_3` and a model of the concept `Periodic_3Offset_3`. The second parameter `Periodic_3Offset_3` defaults to @@ -244,13 +239,12 @@ The first template parameter of the Delaunay triangulation class is the geometric traits class, described by the concept `Periodic_3DelaunayTriangulationTraits_3`. It is different to the DelaunayTriangulationTraits_3 (see -chapter \ref Triangulation3secTraits "3D Triangulations") in that it -implements all objects, predicates and constructions with -using offsets. +chapter \ref Triangulation3secTraits "3D Triangulations") in that it +implements all objects, predicates and constructions using offsets. The class `Periodic_3_Delaunay_triangulation_traits_3` provides the required functionality. It expects two template -parameters: A model of the concept `DelaunayTriangulationTraits_3` +parameters: a model of the concept `DelaunayTriangulationTraits_3` and a model of the concept `Periodic_3Offset_3`. The second parameter `Periodic_3Offset_3` defaults to @@ -264,13 +258,12 @@ The first template parameter of the regular triangulation class is the geometric traits class, described by the concept `Periodic_3RegularTriangulationTraits_3`. It is different to the RegularTriangulationTraits_3 (see -chapter \ref Triangulation3secTraits "3D Triangulations") in that it -implements all objects, predicates and constructions with -using offsets. +chapter \ref Triangulation3secTraits "3D Triangulations") in that it +implements all objects, predicates and constructions using offsets. The class `Periodic_3_regular_triangulation_traits_3` provides the required functionality. It expects two template -parameters: A model of the concept `RegularTriangulationTraits_3` +parameters: a model of the concept `RegularTriangulationTraits_3` and a model of the concept `Periodic_3Offset_3`. The second parameter `Periodic_3Offset_3` defaults to @@ -281,16 +274,14 @@ The second parameter `Periodic_3Offset_3` defaults to The kernels `Cartesian`, `Homogeneous`, `Simple_cartesian`, `Simple_homogeneous` and -`Filtered_kernel` can all be used as models for template parameters -`TriangulationTraits_3`, `DelaunayTriangulationTraits_3`. -The traits class `Regular_triangulation_euclidean_traits_3` can be used for the template parameter `RegularTriangulationTraits_3`. +`Filtered_kernel` can all be used as template parameters of the concepts +`TriangulationTraits_3`, `DelaunayTriangulationTraits_3`, and +`RegularTriangulationTraits_3`. The periodic triangulation classes provide exact predicates and exact constructions if these respective template parameters -do. They provide -exact predicates but not exact constructions if +do. They provide exact predicates but not exact constructions if `Filtered_kernel` with `CK` an inexact kernel is used as -template parameter. Using -`Exact_predicates_inexact_constructions_kernel` +template parameter. Using `Exact_predicates_inexact_constructions_kernel` provides fast and exact predicates and not exact constructions, using `Exact_predicates_exact_constructions_kernel` provides fast and exact predicates and exact constructions. The latter is recommended if @@ -320,13 +311,13 @@ structure or a different vertex or cell base class. \subsection Periodic_3_triangulation_3Flexibilityofthe Flexibility of the Design -`Periodic_3_triangulation_3` uses the -`TriangulationDataStructure_3` in essentially the same way as -`Triangulation_3`. That is why the flexibility described in -\ref Triangulation3secdesign is applicable in exactly the same -way. Also the classes `Triangulation_vertex_base_with_info_3` and +The class `Periodic_3_triangulation_3` uses the +`TriangulationDataStructure_3` in essentially the same way as the class +`Triangulation_3` and the flexibility described in +\ref Triangulation3secdesign is therefore applicable in exactly the same +way. Furthermore, the classes `Triangulation_vertex_base_with_info_3` and `Triangulation_cell_base_with_info_3` can be reused directly, see -also Example \ref P3Triangulation3secexamplescolor. +Example \ref P3Triangulation3secexamplescolor. \section P3Triangulation3secexamples Examples @@ -335,7 +326,7 @@ also Example \ref P3Triangulation3secexamplescolor. This example shows the incremental construction of a 3D Delaunay triangulation, the location of a point and how to perform elementary operations on indices in a cell. It uses the default parameter of the -`Periodic_3_Delaunay_triangulation_3` class for the triangulation +class `Periodic_3_Delaunay_triangulation_3` for the triangulation data structure. \cgalExample{Periodic_3_triangulation_3/simple_example.cpp} @@ -345,7 +336,7 @@ data structure. The following two examples show how the user can plug his own vertex base in a triangulation. Changing the cell base is similar. -\subsection P3Triangulation3secexamplescolor Adding a Color +\subsubsection P3Triangulation3secexamplescolor Adding a Color If the user does not need to add a type in a vertex that depends on the `TriangulationDataStructure_3` (e.g. a `Vertex_handle` or @@ -356,7 +347,7 @@ this way. \cgalExample{Periodic_3_triangulation_3/colored_vertices.cpp} -\subsection Periodic_3_triangulation_3AddingHandles Adding Handles +\subsubsection Periodic_3_triangulation_3AddingHandles Adding Handles If the user needs to add a type in a vertex that depends on the `TriangulationDataStructure_3` (e.g. a `Vertex_handle` or @@ -369,48 +360,46 @@ as the following example shows. The user can check at any time whether a triangulation would be a simplicial complex in \f$ \mathbb T_c^3\f$ and force a conversion if -so. However this should be done very carefully in order to be sure +so. However, this should be done very carefully in order to ensure that the internal structure always remains a simplicial complex and thus a triangulation. -In this example we construct a triangulation that can be converted to +In this example, we construct a triangulation that can be converted to the 1-sheeted covering space. However, we can insert new points such that the point set does not have a Delaunay triangulation in the 1-sheeted -covering space anymore, so the triangulation is not extensible. +covering space anymore, rendering the triangulation not extensible. \cgalExample{Periodic_3_triangulation_3/covering.cpp} \subsection Periodic_3_triangulation_3LargePointSet Large Point Set -For large point sets there are two optimizations available. Firstly, -there is spatial sorting that sorts the input points according to a +Two optimizations are available for large point sets. Firstly, +spatial sorting can be used to sort the input points according to a Hilbert curve, see chapter \ref secspatial_sorting "Spatial Sorting". -The second one inserts 36 appropriately chosen dummy points to avoid -the use of a 27-sheeted covering space in the beginning. The 36 dummy +Secondly, 36 appropriately chosen dummy points can be inserted to avoid +the use of a 27-sheeted covering space in the beginning. These 36 dummy points are deleted in the end. If the point set turns out to not have a Delaunay triangulation in the 1-sheeted covering space, the triangulation is converted to the 27-sheeted covering space during the removal of the 36 dummy -points. This might take even longer than computing the triangulation +points. Note that this might take even longer than computing the triangulation without using this optimization. In general, uniformly distributed random point sets of more than 1000 points have a Delaunay triangulation in the 1-sheeted covering space. -It is recommended to run this example only when compiled in release -mode because of the relatively large number of points. +The following example illustrates the use of these optimization techniques. \cgalExample{Periodic_3_triangulation_3/large_point_set.cpp} \subsection Periodic_3_triangulation_3GeometricAccess Geometric Access -There might be applications that need the geometric primitives of a -triangulation as an input but do not require a simplicial complex. For -these cases we provide the geometric iterators that return only the +Some application might use the geometric primitives of a +triangulation as an input but not require a simplicial complex. We provide +for these cases the geometric iterators that return only the geometric primitives fulfilling some properties. In the following -example we use the `Periodic_3_triangulation_3::Periodic_triangle_iterator` with the option -`UNIQUE_COVER_DOMAIN`. This means that only those triangles are -returned that have a non-empty intersection with the original domain -of the 1-sheeted covering space, see -Figure \ref P3Triangulation3figgeom_iterators. +example, we use the `Periodic_3_triangulation_3::Periodic_triangle_iterator` +with the option `UNIQUE_COVER_DOMAIN`. This means that only the triangles that +have a non-empty intersection with the original domain of the 1-sheeted covering +space are returned, see Figure \ref P3Triangulation3figgeom_iterators. The `Periodic_3_triangulation_3::Periodic_triangle` is actually a three-dimensional array of point-offset pairs. We check for all three entries of the periodic triangle whether the offset is (0,0,0) using the @@ -423,7 +412,9 @@ exact. \subsection Periodic_3_triangulation_3PeriodicRegularTriangulations Periodic Regular Triangulations The following four examples illustrate various features of 3D periodic -regular triangulations. +regular triangulations. + +\subsubsection Periodic_3_triangulation_3P3TR3FirstExample Point insertion and vertex removal The first example shows the incremental construction of a 3D regular triangulation, and the removal of a vertex. It uses the default parameter of the @@ -431,22 +422,28 @@ and the removal of a vertex. It uses the default parameter of the \cgalExample{Periodic_3_triangulation_3/p3rt3_insert_remove.cpp} +\subsubsection Periodic_3_triangulation_3P3TR3SecondExample Data structure + The second example shows the incremental construction of a 3D regular triangulation. It uses a more appropriate triangulation data structure, which saves some memory resources. \cgalExample{Periodic_3_triangulation_3/p3rt3_insert_only.cpp} +\subsubsection Periodic_3_triangulation_3P3TR3ThirdExample Hidden points + The third example shows that points can be hidden during the incremental construction of a 3D regular triangulation. -\cgalExample{p3rt3_hidden_points.cpp} +\cgalExample{Periodic_3_triangulation_3/p3rt3_hidden_points.cpp} + +\subsubsection Periodic_3_triangulation_3P3TR3FourthExample Bad weights Finally, the following example shows how points whose weight does not satisfy the precondition are handled during the incremental construction of a 3D regular triangulation. -\cgalExample{p3rt3_insert_point_with_bad_weight.cpp} +\cgalExample{Periodic_3_triangulation_3/p3rt3_insert_point_with_bad_weight.cpp} \subsection Periodic_3_triangulation_3PeriodicAlphaShapes Periodic Alpha Shapes diff --git a/Periodic_3_triangulation_3/doc/Periodic_3_triangulation_3/examples.txt b/Periodic_3_triangulation_3/doc/Periodic_3_triangulation_3/examples.txt index f94bb6f3521..6b8bf6be2bf 100644 --- a/Periodic_3_triangulation_3/doc/Periodic_3_triangulation_3/examples.txt +++ b/Periodic_3_triangulation_3/doc/Periodic_3_triangulation_3/examples.txt @@ -8,5 +8,5 @@ \example Periodic_3_triangulation_3/p3rt3_insert_remove.cpp \example Periodic_3_triangulation_3/p3rt3_insert_only.cpp \example Periodic_3_triangulation_3/p3rt3_hidden_points.cpp -\example Periodic_3_triangulation_3/p3rt3_hidden_point_with_bad_weight.cpp +\example Periodic_3_triangulation_3/p3rt3_insert_point_with_bad_weight.cpp /h*/