Modifications to User Manual (figures, refs, added two examples)

This commit is contained in:
Iordan Iordanov 2018-11-16 18:37:38 +01:00
parent c4f687ef6a
commit 2f7e21c767
9 changed files with 211 additions and 202 deletions

View File

@ -7,7 +7,7 @@ namespace CGAL {
/*!
\ingroup PkgHyperbolicTriangulation2MainClasses
The class `Hyperbolic_Delaunay_triangulation_2` is the main class of the 2D Hyperbolic Triangulations package.
The class `Hyperbolic_Delaunay_triangulation_2` is the main class of the 2D Hyperbolic Delaunay Triangulations package.
It is designed to represent Delaunay triangulations of sets of points in the hyperbolic plane.
The hyperbolic plane is represented in the Poincaré disk model.

View File

@ -4,6 +4,9 @@ EXTRACT_PRIVATE = NO
EXAMPLE_PATH = ${CGAL_PACKAGE_DIR}/examples
PROJECT_NAME = "CGAL ${CGAL_DOC_VERSION} - 2D Hyperbolic Triangulations"
PROJECT_NAME = "CGAL ${CGAL_DOC_VERSION} - 2D Hyperbolic Delaunay Triangulations"
HTML_EXTRA_FILES = ${CGAL_PACKAGE_DOC_DIR}/fig/ht-empty-disks.png
HTML_EXTRA_FILES = ${CGAL_PACKAGE_DOC_DIR}/fig/ht-empty-disks.png \
${CGAL_PACKAGE_DOC_DIR}/fig/poincare-disk.png \
${CGAL_PACKAGE_DOC_DIR}/fig/header.png \
${CGAL_PACKAGE_DOC_DIR}/fig/hyperbolic-vs-euclidean.png

View File

@ -11,16 +11,14 @@ namespace CGAL {
\cgalAutoToc
\author Mikhail Bogdanov, and Iordan Iordanov, and Monique Teillaud
\image html ht-450px.png
<center>
<img src="header.png" style="max-width:60%; width=60%;"/>
</center>
\cgalModifBegin
TODO image Delaunay + Voronoi a cote
\cgalModifEnd
This package allows to compute Delaunay triangulations of point sets in the Poincar&eacute;
disk model of the hyperbolic plane, as well as their dual objects.
This package allows to compute triangulations of point sets in the Poincar&eacute;
disk model of the hyperbolic plane.
\section The Poincar&eacute; Disk Model of the Hyperbolic Plane
\section HT2_Poincare_model The Poincar&eacute; Disk Model of the Hyperbolic Plane
The Poincar&eacute; disk model represents the hyperbolic plane
\f$\mathbb H^2\f$ as the open unit disk centered at the origin in the
Euclidean plane. The unit circle represents the set \f$\mathcal
@ -32,21 +30,35 @@ a diameter of the unit disk. A hyperbolic circle is a Euclidean circle
contained in the unit disk; however, its hyperbolic center and radius
are not the same as its Euclidean center and radius.
\cgalModifBegin
TODO figure showing \f$\mathcal H_\infty\f$ and O in black, 2 lines (one of each
kind) in e.g., blue, and a few co-circular circles in e.g., green
\cgalModifEnd
\cgalFigureAnchor{Hyperbolic_triangulation_2Poincare_disk}
<center>
<img src="poincare-disk.png" style="max-width:35%; width=35%;"/>
</center>
\cgalFigureCaptionBegin{Hyperbolic_triangulation_2Poincare_disk}
The Poincar&eacute; disk model for the hyperbolic plane. The figure shows
two hyperbolic lines and three concentric hyperbolic circles with different
radii.
\cgalFigureCaptionEnd
\section Euclidean and Hyperbolic Delaunay Triangulations
\section HT2_Euclidean_and_hyperbolic_Delaunay_triangulations Euclidean and Hyperbolic Delaunay Triangulations
As hyperbolic circles coincide with Euclidean circles contained in the
unit disk, the combinatorial structure of the hyperbolic Delaunay
triangulation of a set \f$\mathcal P\f of points in \f$\mathbb H^2\f$
triangulation of a set \f$\mathcal P\f$ of points in \f$\mathbb H^2\f$
is a subset of the Euclidean Delaunay triangulation of \f$\mathcal
P\f. Of course, the hyperbolic and Euclidean geometric embeddings of a
given Delaunay face are different.
\cgalModifBegin
TODO maybe figure showing the 2 embeddings?
\cgalModifEnd
P\f$. Of course, the hyperbolic and Euclidean geometric embeddings of a
given Delaunay face are different. See
\cgalFigureRef{Hyperbolic_triangulation_2Euclidean_vs_hyperbolic}.
\cgalFigureAnchor{Hyperbolic_triangulation_2Euclidean_vs_hyperbolic}
<center>
<img src="hyperbolic-vs-euclidean.png" style="max-width:35%; width=35%;"/>
</center>
\cgalFigureCaptionBegin{Hyperbolic_triangulation_2Euclidean_vs_hyperbolic}
Comparison of the Euclidean (green) and hyperbolic (black) Delaunay triangulations
of a given set of points in the unit disk. Note that only the colored faces
are faces of the hyperbolic Delaunay triangulation.
\cgalFigureCaptionEnd
More precisely, the hyperbolic Delaunay triangulation of \f$\mathcal
P\f$ is a connected simplicial complex. It only
@ -58,20 +70,16 @@ are <i>hyperbolic</i>:
<li> An Euclidean Delaunay edge is hyperbolic if one fo the
empty disks (i.e., not containing any point of \f$\mathcal
P\f$) passing through its endpoints is contained in \f$\mathbb
H^2\f.
H^2\f$.
</ul>
In the Euclidean Delaunay triangulation, there is a bijection between
non-hyperbolic faces and non-hyperbolic edges
\cgalCite{cgal:bdt-hdcvd-14}. See
\cgalFigureRef{Hyperbolic_triangulation_2Empty_disks}
\cgalModifBegin
TODO fix bib entry: Delaunay and Voronoi should be capitalized
\cgalModifEnd
\cgalFigureAnchor{Hyperbolic_triangulation_2Empty_disks}
<center>
<img src="ht-empty-disks.png" style="max-width:30%; width=30%;"/>
<img src="ht-empty-disks.png" style="max-width:35%; width=35%;"/>
</center>
\cgalFigureCaptionBegin{Hyperbolic_triangulation_2Empty_disks}
The shaded face is non-hyperbolic. Its dashed edge is non-hyperbolic,
@ -79,24 +87,19 @@ as no empty circle through its endpoints is contained in
\f$\mathbb H^2\f$. Its other two edges are hyperbolic.
\cgalFigureCaptionEnd
\cgalModifBegin
TODO fix the picture so that it shows what is written in the caption.
\cgalModifEnd
\section Software Design
\section HT2_Software_design Software Design
From what was said above, it is natural that the class
`Hyperbolic_Delaunay_triangulation_2` privately inherits from the class
`Delaunay_triangulation_2`. So, users are encouraged to look at the chapter
\cgalModifBegin
TODO link T2
\cgalModifEnd
of the CGAL manual to know more in particular about the
representation of triangulations in CGAL and the flexibility of the design.
\ref Chapter_2D_Triangulations "2D Triangulation" of the CGAL manual to
know more in particular about the representation of triangulations in
CGAL and the flexibility of the design.
The class `Hyperbolic_Delaunay_triangulation_2` has two template
parameters:
<ul>
<li> A geometric traits class `Gt`, which provides geometric
<li> A geometric traits class `Gt`, which provides geometric
primitives. The requirements on this first template parameter
are described by the concept
`HyperbolicDelaunayTriangulationTraits_2`, which refines
@ -119,10 +122,14 @@ algebraic coordinates; however the first model is more efficient for
rational points.
\section Examples
\cgalModifBegin
TODO two examples, one with each traits. Maybe one with colors on
vertices to show how to plug vertex-with-info
\cgalModifEnd
The example below shows insertion of random points in a hyperbolic Delaunay triangulation.
The same set of points is inserted twice. The first time points are inserted one by one,
which causes Euclidean faces to be filtered at each insertion. The second time, all points
are inserted and the filtering is done once at the end.
\cgalExample{Hyperbolic_triangulation_2/ht2_example.cpp}
The example below shows how user-defined info can be added to the hyperbolic faces.
\cgalExample{Hyperbolic_triangulation_2/ht2_example_color.cpp}
\section HT2_Design Design and Implementation History

View File

@ -1,4 +1,4 @@
/// \defgroup PkgHyperbolicTriangulation2 2D Hyperbolic Triangulations Reference
/// \defgroup PkgHyperbolicTriangulation2 2D Hyperbolic Delaunay Triangulations Reference
/// \defgroup PkgHyperbolicTriangulation2Concepts Concepts
/// \ingroup PkgHyperbolicTriangulation2

View File

@ -0,0 +1,27 @@
# Created by the script cgal_create_cmake_script
# This is the CMake script for compiling a CGAL application.
project( Periodic_4_hyperbolic_triangulation_2_examples )
cmake_minimum_required(VERSION 2.8.10)
find_package(CGAL QUIET COMPONENTS Core )
if ( CGAL_FOUND )
include( ${CGAL_USE_FILE} )
include( CGAL_CreateSingleSourceCGALProgram )
include_directories (BEFORE "../../include" $HOME/include)
create_single_source_cgal_program( "ht2_example.cpp" )
create_single_source_cgal_program( "ht2_example_color.cpp" )
else()
message(STATUS "This program requires the CGAL library, and will not be compiled.")
endif()

View File

@ -0,0 +1,62 @@
#include <CGAL/Hyperbolic_Delaunay_triangulation_2.h>
#include <CGAL/Hyperbolic_Delaunay_triangulation_traits_2.h>
#include <CGAL/point_generators_2.h>
#include <CGAL/CORE_Expr.h>
#include <CGAL/Timer.h>
typedef CGAL::Hyperbolic_Delaunay_triangulation_traits_2<> Gt;
typedef Gt::Point_2 Point_2;
typedef Gt::Circle_2 Circle_2;
typedef Gt::FT FT;
typedef CGAL::Hyperbolic_Delaunay_triangulation_2<Gt> Dt;
typedef CGAL::Creator_uniform_2<FT, Point_2> Creator;
int main(int argc, char** argv)
{
if (argc < 2) {
std::cout << "usage: " << argv[0] << " [number_of_points]" << std::endl;
return -1;
}
int N = atoi(argv[1]);
std::cout << "Number of points: " << N << std::endl;
CGAL::Timer timer;
CGAL::Random_points_in_disc_2<Point_2, Creator> in_disc;
std::vector<Point_2> pts;
std::vector<Point_2>::iterator ip;
for (int i=0 ; i < N; i++) {
pts.push_back(*(in_disc++));
}
Dt dt_during;
std::cout << "Insertion of points one by one (hyperbolic filtering at each step)" << std::endl;
std::cout << "===================================================================" << std::endl;
timer.start();
for(ip = pts.begin(); ip != pts.end(); ++ip) {
dt_during.insert(*ip);
}
timer.stop();
std::cout << "Number of vertices: " << dt_during.number_of_vertices() << std::endl;
std::cout << "Number of hyperbolic faces: " << dt_during.number_of_hyperbolic_faces() << std::endl;
std::cout << "Number of hyperbolic edges: " << dt_during.number_of_hyperbolic_edges() << std::endl;
std::cout << "Time: " << timer.time() << std::endl << std::endl;
Dt dt_end;
std::cout << "Insertion of point set (hyperbolic filtering only once at the end)" << std::endl;
std::cout << "===================================================================" << std::endl;
timer.reset();
timer.start();
dt_end.insert(pts.begin(),pts.end());
timer.stop();
std::cout << "Number of vertices: " << dt_end.number_of_vertices() << std::endl;
std::cout << "Number of hyperbolic faces: " << dt_end.number_of_hyperbolic_faces() << std::endl;
std::cout << "Number of hyperbolic edges: " << dt_end.number_of_hyperbolic_edges() << std::endl;
std::cout << "Time: " << timer.time() << std::endl;
return 0;
}

View File

@ -0,0 +1,69 @@
#include <CGAL/Triangulation_face_base_with_info_2.h>
#include <CGAL/Triangulation_vertex_base_2.h>
#include <CGAL/Hyperbolic_triangulation_face_base_2.h>
#include <CGAL/Hyperbolic_Delaunay_triangulation_2.h>
#include <CGAL/Hyperbolic_Delaunay_triangulation_CK_traits_2.h>
#include <CGAL/point_generators_2.h>
#include <CGAL/IO/Color.h>
typedef CGAL::Hyperbolic_Delaunay_triangulation_CK_traits_2<> Gt;
typedef CGAL::Hyperbolic_triangulation_face_base_2<Gt> Hyperbolic_face_base;
typedef CGAL::Triangulation_face_base_with_info_2<CGAL::Color,
Gt, Hyperbolic_face_base> Face_base_with_info;
typedef CGAL::Triangulation_vertex_base_2<Gt> Vertex_base;
typedef CGAL::Triangulation_data_structure_2 <
Vertex_base, Face_base_with_info> TDS;
typedef CGAL::Hyperbolic_Delaunay_triangulation_2<Gt, TDS> Dt;
typedef Dt::Point Point_2;
typedef CGAL::Creator_uniform_2<Gt::FT, Point_2> Creator;
int main(int argc, char** argv)
{
if (argc < 2) {
std::cout << "usage: " << argv[0] << " [number_of_points]" << std::endl;
return -1;
}
int N = atoi(argv[1]);
std::cout << "Number of points: " << N << std::endl;
CGAL::Random_points_in_disc_2<Point_2, Creator> in_disc;
std::vector<Point_2> pts;
std::vector<Point_2>::iterator ip;
for (int i=0 ; i < N; i++) {
pts.push_back(*(in_disc++));
}
Dt dt;
dt.insert(pts.begin(), pts.end());
Dt::Vertex_handle vo = dt.insert(Point_2(0,0));
int origin_faces = 0;
Dt::Hyperbolic_faces_iterator fit;
for (fit = dt.hyperbolic_faces_begin(); fit != dt.hyperbolic_faces_end(); ++fit) {
if (fit->has_vertex(vo)) {
fit->info() = CGAL::RED;
origin_faces++;
}
}
int red_faces = 0;
for (fit = dt.hyperbolic_faces_begin(); fit != dt.hyperbolic_faces_end(); ++fit) {
if (fit->info() == CGAL::RED) {
red_faces++;
}
}
assert(red_faces == origin_faces);
std::cout << "Number of points " << N << std::endl;
std::cout << "Number of vertices: " << dt.number_of_vertices() << std::endl;
std::cout << "Number of hyperbolic faces: " << dt.number_of_hyperbolic_faces() << std::endl;
std::cout << "Number of faces incident to the origin: " << origin_faces << std::endl;
return 0;
}

View File

@ -1,62 +0,0 @@
#include <fstream>
// CGAL headers
#include <CGAL/IO/io.h>
#include <CGAL/Exact_circular_kernel_2.h>
#include <CGAL/Hyperbolic_triangulation_face_base_with_info_2.h>
#include <CGAL/Hyperbolic_Delaunay_triangulation_2.h>
#include <CGAL/Hyperbolic_Delaunay_triangulation_traits_2.h>
#include <CGAL/IO/Color.h>
typedef CGAL::Exact_circular_kernel_2 K;
typedef CGAL::Hyperbolic_Delaunay_triangulation_traits_2< K > Gt;
typedef Gt::Point_2 Point_2;
typedef CGAL::Hyperbolic_triangulation_face_base_with_info_2<CGAL::Color, Gt> Fb;
typedef CGAL::Triangulation_data_structure_2 <
CGAL::Triangulation_vertex_base_2<Gt>, Fb > TDS;
typedef CGAL::Hyperbolic_Delaunay_triangulation_2<Gt, TDS> Dt;
int main()
{
std::vector<Point_2> pts;
Point_2 p;
std::ifstream ifs("input-file");
while(ifs >> p) {
pts.push_back(p);
}
Dt dt;
dt.insert(pts.begin(),pts.end());
Dt::Vertex_handle vo = dt.insert(Point_2(0,0));
int origin_faces = 0;
Dt::Hyperbolic_faces_iterator fit;
for (fit = dt.hyperbolic_faces_begin(); fit != dt.hyperbolic_faces_end(); ++fit)
if (fit->has_vertex(vo))
{
fit->info() = CGAL::RED;
origin_faces++;
}
int red_faces = 0;
for (fit = dt.hyperbolic_faces_begin(); fit != dt.hyperbolic_faces_end(); ++fit)
if (fit->info() == CGAL::RED)
red_faces++;
assert(red_faces == origin_faces);
std::cout << "number of points " << std::distance(pts.begin(),pts.end())+1 << std::endl;
std::cout << "Number of (finite) vertices: " << dt.number_of_vertices() << std::endl;
std::cout << "number of (finite) Euclidean faces: " << dt.number_of_faces() << std::endl;
std::cout << "number of hyperbolic faces: " << dt.number_of_hyperbolic_faces() << std::endl;
std::cout << "number of faces having the origin as vertex: " << origin_faces << std::endl;
return 0;
}

View File

@ -1,97 +0,0 @@
#include <fstream>
// CGAL headers
#include <CGAL/IO/io.h>
#include <CGAL/Exact_circular_kernel_2.h>
#include <CGAL/Hyperbolic_Delaunay_triangulation_2.h>
#include <CGAL/Hyperbolic_Delaunay_triangulation_traits_2.h>
#include <CGAL/Random.h>
#include <CGAL/point_generators_2.h>
#include <CGAL/Timer.h>
typedef CGAL::Exact_circular_kernel_2 K;
typedef CGAL::Hyperbolic_Delaunay_triangulation_traits_2<K> Gt;
typedef Gt::Point_2 Point_2;
typedef Gt::Circle_2 Circle_2;
typedef Gt::FT FT;
typedef CGAL::Hyperbolic_Delaunay_triangulation_2<Gt> Dt;
int main()
{
CGAL::Timer timer;
typedef CGAL::Creator_uniform_2<FT, Point_2> Creator;
CGAL::Random_points_in_disc_2<Point_2, Creator> in_disc(FT(1));
int n = 100;
std::cout << "Number of points: " << n << std::endl;
std::vector<Point_2> pts(n);
std::vector<Point_2>::iterator ip;
// Generating n random points
for (int i=0 ; i < n ; i++) {
pts.at(i) = *in_disc;
in_disc++;
}
// std::vector<Point_2> pts;
// std::vector<Point_2>::iterator ip;
// Point_2 p;
// std::ifstream ifs("input-file");
// while(ifs >> p) {
// pts.push_back(p);
// }
// std::cout << "number of points " << std::distance(pts.begin(),pts.end()) << std::endl << std::endl;
std::cout << "check for hyperbolic faces during insertion" << std::endl;
timer.start();
Dt dt_during;
for(ip = pts.begin(); ip != pts.end(); ++ip) {
dt_during.insert(*ip);
}
timer.stop();
assert(dt_during.is_valid());
std::cout << "Number of (finite) vertices: " << dt_during.number_of_vertices() << std::endl;
std::cout << "number of (finite) Euclidean faces: " << dt_during.number_of_faces() << std::endl;
std::cout << "number of hyperbolic faces: " << dt_during.number_of_hyperbolic_faces() << std::endl;
std::cout << "number of hyperbolic edges: " << dt_during.number_of_hyperbolic_edges() << std::endl;
std::cout << "Time: " << timer.time() << std::endl << std::endl;
timer.reset();
timer.start();
std::cout << "check for hyperbolic faces only at the end" << std::endl;
Dt dt_end;
dt_end.insert(pts.begin(),pts.end());
timer.stop();
assert(dt_end.is_valid());
std::cout << "Number of (finite) vertices: " << dt_end.number_of_vertices() << std::endl;
std::cout << "number of (finite) Euclidean faces: " << dt_end.number_of_faces() << std::endl;
std::cout << "number of hyperbolic faces: " << dt_end.number_of_hyperbolic_faces() << std::endl;
std::cout << "number of hyperbolic edges: " << dt_end.number_of_hyperbolic_edges() << std::endl;
std::cout << "Time: " << timer.time() << std::endl;
timer.reset();
return 0;
}