This chapter describes the two-dimensional Apollonius graph of Cgal. We start with a few definitions in Section 43.1. The software design of the 2D Apollonius graph package is described in Section 43.2. In Section 43.3 we discuss the geometric traits of the 2D Apollonius graph package and in Section 43.4 the Apollonius graph hierarchy, a data structure suitable for fast nearest neighbor queries, is briefly described.
43.1 Definitions
The 2D Apollonius graph class of Cgal is designed to compute the dual of the Apollonius diagram or, as it is also known, the Additively weighted Voronoi diagram. The algorithm that has been implemented is dynamic, which means that we can perform insertions and deletions on line. The corresponding Cgal class is called Apollonius_graph_2<ApolloniusGraphTraits_2,ApolloniusGraphDataStructure_2> and will be discussed in more detail in the sequel. The interested reader may want to refer to the paper by Karavelas and Yvinec [KY02] for the general idea as well as the details of the algorithm implemented.
Before describing the details of the implementation we make a brief introduction to the theory of Apollonius diagrams. The Apollonius diagram is defined over a set of sites Pi=(ci,wi), i=1, … ,n, where ci is the point and wi the weight of Pi. It is a subdivision of the plane into connected regions, called cells, associated with the sites (see Fig. 43.1(left)). The cell of a site Pi is the locus of points on the plane that are closer to Pi than any other site Pj, j ≠ i. The distance δ(x, Pi) of a point x in the plane to a site Pi is defined as:
| δ(x,Pi)=||x-ci||-wi, |
If all weights wi are non-negative, the Apollonius diagram can be viewed as the Voronoi diagram of the set of circles {P1, … , Pn}, where ci is the center of the circle Pi and wi its radius. If the weights are allowed to be negative, we need to go to 3D in order to explain what the Apollonius diagram means geometrically. We identify the 2D Euclidean plane with the xy-plane in 3D. Then the Voronoi diagram of a set of points can be seen as the vertical projection on the xy-plane of the lower envelope of a set of 3D cones defined as follows: for each point p in the set of 2D points we have a cone Cp whose apex is the point p. The axis of Cp is a line parallel to the z-axis passing through p, the angle of Cp is 45° and, finally Cp is facing in the positive z-direction (that is, Cp is contained in the positive z-halfspace). The Apollonius diagram corresponds to shifting the apexes of these cones in the z-direction by a quantity equal to the weight. Sites with negative weight will give rise to cones whose apex is in the negative z-halfspace and sites with positive weight will give rise to cones whose apex is in the positive z-halfspace. In a manner analogous to the case of points, the Apollonius diagram can then be defined as the vertical projection on the xy-plane of the lower envelope of the set of shifted cones. Notice that when all apexes are translated along the z-direction by the same amount, the projection of the lower envelope of the set of cones does not change. In particular, we can translate all cones by a large enough amount so that all apexes are in the positive z-halfspace. Algebraically, this means that the Apollonius diagram does not change if we add to all weights the same quantity, which in particular, implies that we can assume without loss of generality that all weights are positive. Given the observations above and in order to simplify our discussion of Apollonius diagrams, we will, from now on, assume that all weights are positive, and we will refer to the sites as circles.
The Apollonius diagram is a planar graph, and so is its dual, the Apollonius graph. There are many ways to embed it on the plane and one such way is shown in Fig. 43.1(right). The Apollonius graph is uniquely defined once we have the Apollonius diagram. If the circles are in general position (see precise definition below), then the Apollonius graph is a graph with triangular faces away from the convex hull of the set of circles (by triangular we mean that every face has exactly three edges). Near the convex hull we may have some spikes (i.e., vertices of degree 1). To unify our approach and handling of the Apollonius graph we add to the set of (finite) circles a fictitious circle at infinity, which we call the site at infinity. We can then connect all vertices of the outer face of the Apollonius graph to the site at infinity which gives us a graph with the property that all of its faces are now triangular. However, the Apollonius graph is not a triangulation for two main reasons: we cannot always embed it on the plane with straight line segments that yield a triangulation and, moreover, we may have two faces of the graph that have two edges in common, which is not allowed in a triangulation. Both of these particularities appear when we consider the Apollonius graph of the set of circles in Fig. 43.1(right).
We would like to finish our brief introduction to the theory of Apollonius graphs by discussing the concept of general position. We say that a set of circles is in general position if no two triplets of circles have the same tritangent circle. This statement is rather technical and it is best understood in the context of points. The equivalent statement for points is that we have no two triplets of points that define the same circumcircle, or equivalently that no four points are co-circular. The statement about general position made above is a direct generalization of the (much simpler to understand) statement about points. On the contrary, when we have circles in degenerate position, the Apollonius graph has faces with more than three edges on their boundary. We can get a triangulated version of the graph by simply triangulating the corresponding faces in an arbitrary way. In fact the algorithm that has been implemented in Cgal has the property that it always returns a valid triangulated version of the Apollonius graph. By valid we mean that it contains the actual Apollonius graph (i.e., the actual dual of the Apollonius diagram) and whenever there are faces with more than three faces then they are triangulated. The way that they are triangulated depends on the order of insertion and deletion of the circles in the diagram.
One final point has to be made about hidden circles. First of all we would like to be more precise about our definition of hidden circles: we say that a circle is hidden if its cell has empty interior. This definition allows us to guarantee that all visible circles have cells that are two-dimensional regions. Geometrically the fact that a circle is hidden means that it is contained in the closure of the disk of another circle (see again Fig. 43.1). Note that a circle contained in the union of several disks, but not in the closure of any one of them, is not hidden.
Hidden circles pose an additional difficulty to our algorithm and software design. Since we allow circles to be inserted and deleted at wish, it is possible that a circle that was hidden at some point in time, may become visible at a later point in time; for example this can happen if we delete the circle that hides it. For this purpose we store hidden circles and have them reappear when they become visible. We will discuss this issue in detail below. For the time being it suffices to say that the user has the ability to control this behavior. More specifically it is possible to discard the circles that become hidden. This choice is totally natural when for example we expect to do only insertions, since in this case a circle that becomes hidden will never reappear. On the other hand if deletions are expected as well, then we lose the ability to have the hidden circles reappear.
Degenerate Dimensions. The dimension of the Apollonius graph is in general 2. The exceptions to this rule are as follows:
- The dimension is -1 if the Apollonius graph contains no circles.
- The dimension is 0 if the Apollonius graph contains exactly one visible circle.
- The dimension is 1 is the Apollonius graph contains exactly two visible circles.
43.2 Software Design
The 2D Apollonius graph class Apollonius_graph_2<ApolloniusGraphTraits_2,ApolloniusGraphDataStructure_2> follows the design of the triangulation package of Cgal. It is parametrized by two arguments:
- the geometric traits class. It provides the basic geometric objects involved in the algorithm, such as sites, points etc. It also provides the geometric predicates for the computation of the Apollonius graph, as well as some basic constructions that can be used, for example, to visualize the Apollonius graph or the Apollonius diagram. The geometric traits for the Apollonius graph will be discussed in more detail in the next section.
- the Apollonius graph data structure. This is essentially the same as the triangulation data structure (discussed in Chapter 36), augmented with some additional operations that are specific to Apollonius graphs. The corresponding concept is that of ApolloniusGraphDataStructure_2, which in fact is a refinement of the TriangulationDataStructure_2 concept. The class Triangulation_data_structure_2<Vb,Fb> is a model of the concept ApolloniusGraphDataStructure_2. A default value for the corresponding template parameter is provided, so the user does not need to specify it.
Storing Hidden Sites. As we have already mentioned a circle is hidden if it is contained inside some visible circle. This creates a parent-child relationship between visible and hidden circles: the parent of a hidden circle is the visible circle that contains it. If more than one visible circles contain a hidden circle then the hidden circle can be assigned to any of the visible circles arbitrarily.
To store hidden circles we assign to every visible circle a list. This list comprises the hidden circles that are contained in the visible circle. The user can access the hidden circles associated with a visible circle through an iterator called Hidden_sites_iterator. This iterator is defined in the ApolloniusGraphVertexBase_2 concept and is implemented by its model, the Apollonius_graph_vertex_base_2<Gt,StoreHidden> class. It is also possible to iterate through the entire set of hidden sites using an homonymous iterator defined by the Apollonius_graph_2<Gt,Agds> class.
Since storing hidden sites may not be of interest in some cases (e.g., for example this is the case if we only perform insertions in the Apollonius graph), the user has the possibility of controlling this behavior. More precisely, the class Apollonius_graph_vertex_base_2<Gt,StoreHidden> has two template parameters, the second of which is a Boolean value. This value is by default true and it indicates that hidden sites should be stored. The user can indicate that hidden sites may be discarded by setting this value to false.
43.3 The Geometric Traits
The predicates required for the computation of the Apollonius graph are rather complicated. It is not the purpose of this document to discuss them in detail. The interested reader may refer to the papers by Karavelas and Emiris for the details [KE02, KE03]. However, we would like to give a brief overview of what they compute. There are several predicates needed by this algorithm. We will discuss the most important/complicated ones. It turns out that it is much easier to describe them in terms of the Apollonius diagram, rather than the Apollonius graph. Whenever it is applicable we will also describe their meaning in terms of the Apollonius graph.
The first two geometric predicates are called Is_hidden_2 and Oriented_side_of_bisector_2. The first one involves two circles, say P1 and P2. It determines if P1 is hidden with respect to P2; more precisely it checks whether the circle P1 is contained in the closure of the disk defined by the circle P2. As its name indicates, it determines if a circle is hidden or not. The second predicate involves two circles P1 and P2 and a point q. It answers the question whether q is closer to P1 or P2. Its name stems from the fact that answering the aforementioned question is equivalent to determining the oriented side of the bisector of P1 and P2 that contains the query point q. This predicate is used by the algorithm for closest neighbor queries for points.
The next geometric predicate is called Vertex_conflict_2 and it involves four circles P1, P2, P3, and P4 (see Fig. 43.3). The first three (red circles in Fig. 43.3) define a tritangent circle (yellow circle in Fig. 43.3). What we want to determine is the sign of the distance of the green circle from the yellow circle. The distance between two circles K1=(c1,r1) and K2=(c2, r2) is defined as the distance of their centers minus their radii:
| δ(K1, K2) = ||c1-c2||-r1-r2. |
What we essentially want to compute when we construct incrementally a Voronoi diagram, is whether the object to be inserted destroys an edge of the Voronoi diagram or not. In the case of points this is really easy and it amounts to the well known incircle test. In the case of circles the situation is more complicated. We can have six possible outcomes as to what portion of an edge of the Apollonius diagram the new circle destroys (see Fig. 43.3). The first two can be answered directly by the Vertex_conflict_2 predicate evaluated for the two endpoints of the Apollonius diagram edge. This is due to the fact that the value of the Vertex_conflict_2 predicate is different for the two endpoints. If the two values are the same then we need an additional test which determines if the interior of the Apollonius diagram edge is destroyed by the new circle. This is what the Finite_edge_interior_conflict_2 and Infinite_edge_interior_conflict_2 predicates do. In essence, it is the same predicate (same idea) applied to two different types of edges in the Apollonius diagram: a finite or an infinite edge. An edge is infinite if its dual edge in the Apollonius graph connects the site at infinity with the vertex corresponding to a (finite) circle; otherwise it is a finite edge.
The last predicate that we want to discuss is called Is_degenerate_edge_2. It tells us whether an edge in the Apollonius diagram is degenerate, that is if its two endpoints coincide. In the Apollonius graph such an edge corresponds to one of the additional edges that we use to triangulate the non-triangular faces.
The aforementioned predicates are part of the ApolloniusGraphTraits_2 concept of Cgal. Cgal also provides a model for this concept, the Apollonius_graph_traits_2<K,Method_tag> class. The first template parameter of this class must be a model of the Kernel concept. The second template parameter is a tag that indicates what operations are allowed in the computations that take place within the traits class. The two possible values of the Method_tag parameter are CGAL::Ring_tag and CGAL::Sqrt_field_tag. When CGAL::Ring_tag is used, only ring operations are used during the evaluation of the predicates, whereas if CGAL::Sqrt_field_tag is chosen, all four field operations, as well as square roots, are used during the predicate evaluation.
The Apollonius_graph_traits_2<K,Method_tag> class provides exact predicates if the number type in the kernel K is an exact number type. This is to be associated with the type of operations allowed for the predicate evaluation. For example CGAL::MP_Float as number type, with CGAL::Ring_tag as tag will give exact predicates, whereas CGAL::MP_Float with CGAL::Sqrt_field_tag will give inexact predicates.
Since using an exact number type may be too slow, the Apollonius_graph_traits_2<K,Method_tag> class is designed to support the dynamic filtering of Cgal through the CGAL::Filtered_exact<CT,ET> mechanism. In particular if CT is an inexact number type that supports the operations denoted by the tag Method_tag and ET is an exact number type for these operations, then kernel with number type CGAL::Filtered_exact<CT,ET> will yield exact predicates for the Apollonius graph traits. To give a concrete example, CGAL::Filtered_exact<double,CGAL::MP_Float> with CGAL::Ring_tag will produce exact predicates.
Another possibility for fast and exact predicate evaluation is to use the Apollonius_graph_filtered_traits_2<CK,CM,EK,EM,FK,FM> class. This class is the analog of a filtered kernel. It takes a constructions kernel CK, a filtering kernel FK and an exact kernel EK, as well as the corresponding tags (CM, FM and EM, respectively). It evaluates the predicates by first using the filtering kernel, and if this fails the evaluation is performed using the exact kernel. The constructions are done using the kernel CK, which means that they are not necessarily exact. All template parameters except CK have default values, which are explained in the reference manual.
43.4 The Apollonius Graph Hierarchy
The Apollonius_graph_hierarchy_2<ApolloniusGraphTraits_2,ApolloniusGraphDataStructure_2> class is nothing but the equivalent of the Triangulation_hierarchy_2 class, applied to the Apollonius graph. It consists of a series of Apollonius graphs constructed in a manner analogous to the Delaunay hierarchy by Devillers [Dev98]. The class Apollonius_graph_hierarchy_2<ApolloniusGraphTraits_2,ApolloniusGraphDataStructure_2> has exactly the same interface and functionality as the Apollonius_graph_2<ApolloniusGraphTraits_2,ApolloniusGraphDataStructure_2> class. Using the Apollonius graph hierarchy involves an additional cost in space and time for maintaining the hierarchy. Our experiments have shown that it usually pays off to use the hierarchy for inputs consisting of more than 1,000 circles. This threshold holds for both the construction of the Apollonius diagram itself, as well as for nearest neighbor queries.
43.5 Examples
43.5.1 First Example
File: examples/Apollonius_graph_2/ag2_exact_traits.cpp
#include <CGAL/basic.h>
// standard includes
#include <iostream>
#include <fstream>
#include <cassert>
// the number type
#include <CGAL/MP_Float.h>
// example that uses an exact number type
typedef CGAL::MP_Float NT;
// choose the kernel
#include <CGAL/Simple_cartesian.h>
typedef CGAL::Simple_cartesian<NT> Kernel;
// typedefs for the traits and the algorithm
#include <CGAL/Apollonius_graph_2.h>
#include <CGAL/Apollonius_graph_traits_2.h>
typedef CGAL::Apollonius_graph_traits_2<Kernel> Traits;
typedef CGAL::Apollonius_graph_2<Traits> Apollonius_graph;
int main()
{
std::ifstream ifs("data/sites.cin");
assert( ifs );
Apollonius_graph ag;
Apollonius_graph::Site_2 site;
// read the sites and insert them in the Apollonius graph
while ( ifs >> site ) {
ag.insert(site);
}
// validate the Apollonius graph
assert( ag.is_valid(true, 1) );
std::cout << std::endl;
return 0;
}
43.5.2 Second Example
File: examples/Apollonius_graph_2/ag2_exact_traits_sqrt.cpp
#include <CGAL/basic.h>
// standard includes
#include <iostream>
#include <fstream>
#include <cassert>
#if defined CGAL_USE_LEDA
# include <CGAL/leda_real.h>
#elif defined CGAL_USE_CORE
# include <CGAL/CORE_Expr.h>
#endif
#if defined CGAL_USE_LEDA
// If LEDA is present use leda_real as the exact number type
typedef leda_real NT;
#elif defined CGAL_USE_CORE
// Otherwise if CORE is present use CORE's Expr as the exact number type
typedef CORE::Expr NT;
#else
// Otherwise just use double. This may cause numerical errors but it
// is still worth doing it to show how to define correctly the traits
// class
typedef double NT;
#endif
#include <CGAL/Simple_cartesian.h>
typedef CGAL::Simple_cartesian<NT> Kernel;
// typedefs for the traits and the algorithm
#include <CGAL/Apollonius_graph_2.h>
#include <CGAL/Apollonius_graph_traits_2.h>
// the traits class is now going to assume that the operations
// +,-,*,/ and sqrt are supported exactly
typedef
CGAL::Apollonius_graph_traits_2<Kernel,CGAL::Field_with_sqrt_tag> Traits;
typedef CGAL::Apollonius_graph_2<Traits> Apollonius_graph;
int main()
{
std::ifstream ifs("data/sites.cin");
assert( ifs );
Apollonius_graph ag;
Apollonius_graph::Site_2 site;
// read the sites and insert them in the Apollonius graph
while ( ifs >> site ) {
ag.insert(site);
}
// validate the Apollonius graph
assert( ag.is_valid(true, 1) );
std::cout << std::endl;
return 0;
}
43.5.3 Third Example
File: examples/Apollonius_graph_2/ag2_filtered_traits_no_hidden.cpp
#include <CGAL/basic.h>
// standard includes
#include <iostream>
#include <fstream>
#include <cassert>
#include <CGAL/basic.h>
// example that uses the filtered traits
// choose the representation
#include <CGAL/Simple_cartesian.h>
typedef CGAL::Simple_cartesian<double> Rep;
#include <CGAL/Apollonius_graph_2.h>
#include <CGAL/Triangulation_data_structure_2.h>
#include <CGAL/Apollonius_graph_vertex_base_2.h>
#include <CGAL/Triangulation_face_base_2.h>
#include <CGAL/Apollonius_graph_filtered_traits_2.h>
// typedef for the traits; the filtered traits class is used
typedef CGAL::Apollonius_graph_filtered_traits_2<Rep> Traits;
// typedefs for the algorithm
// With the second template argument in the vertex base class being
// false, we indicate that there is no need to store the hidden sites.
// One case where this is indeed not needed is when we only do
// insertions, like in the main program below.
typedef CGAL::Apollonius_graph_vertex_base_2<Traits,false> Vb;
typedef CGAL::Triangulation_face_base_2<Traits> Fb;
typedef CGAL::Triangulation_data_structure_2<Vb,Fb> Agds;
typedef CGAL::Apollonius_graph_2<Traits,Agds> Apollonius_graph;
int main()
{
std::ifstream ifs("data/sites.cin");
assert( ifs );
Apollonius_graph ag;
Apollonius_graph::Site_2 site;
// read the sites and insert them in the Apollonius graph
while ( ifs >> site ) {
ag.insert(site);
}
// validate the Apollonius graph
assert( ag.is_valid(true, 1) );
std::cout << std::endl;
// now remove all sites
std::cout << "Removing all sites... " << std::flush;
while ( ag.number_of_vertices() > 0 ) {
ag.remove( ag.finite_vertex() );
}
std::cout << "done!" << std::endl << std::endl;
return 0;
}
43.5.4 Fourth Example
File: examples/Apollonius_graph_2/ag2_hierarchy.cpp
#include <CGAL/basic.h>
// standard includes
#include <iostream>
#include <fstream>
#include <cassert>
// example that uses the filtered traits
#include <CGAL/MP_Float.h>
#include <CGAL/Simple_cartesian.h>
// constructions kernel (inexact)
typedef CGAL::Simple_cartesian<double> CK;
// exact kernel
typedef CGAL::Simple_cartesian<CGAL::MP_Float> EK;
// typedefs for the traits and the algorithm
#include <CGAL/Apollonius_graph_hierarchy_2.h>
#include <CGAL/Apollonius_graph_filtered_traits_2.h>
// Type definition for the traits class.
// In this example we explicitly define the exact kernel. We also
// explicitly define what operations to use for the evaluation of the
// predicates and constructions, when the filtering and the exact
// kernels are used respectively.
// Note that the operations allowed for the filtering and the
// constructions (field operations plus square roots) are different
// from the operations allowed when the exact kernel is used (ring
// operations).
typedef CGAL::Field_with_sqrt_tag CM;
typedef CGAL::Integral_domain_without_division_tag EM;
typedef CGAL::Apollonius_graph_filtered_traits_2<CK,CM,EK,EM> Traits;
// Now we use the Apollonius graph hierarchy.
// The hierarchy is faster for inputs consisting of about more than
// 1,000 sites
typedef CGAL::Apollonius_graph_hierarchy_2<Traits> Apollonius_graph;
int main()
{
std::ifstream ifs("data/hierarchy.cin");
assert( ifs );
Apollonius_graph ag;
Apollonius_graph::Site_2 site;
// read the sites and insert them in the Apollonius graph
while ( ifs >> site ) {
ag.insert(site);
}
// validate the Apollonius graph
assert( ag.is_valid(true, 1) );
return 0;
}