User Manual

Authors

Pedro Machado Manhães de Castro, Sylvain Pion, and Monique Teillaud

Introduction

The goal of the circular kernel is to offer to the user a large set of functionalities on circles and circular arcs in the plane. All the choices (interface, robustness, representation, and so on) made here are consistent with the choices made in the CGAL kernel, for which we refer the user to the 2D kernel manual.

In this first release, all functionalities necessary for computing an arrangement of circular arcs and these line segments are defined. Three traits classes are provided for the CGAL arrangement package.

Software Design

The design is done in such a way that the algebraic concepts and the geometric concepts are clearly separated. Circular_kernel_2 has therefore two template parameters:

• the first parameter must model the CGAL three dimensional Kernel concept. The circular kernel derives from it, and it provides all elementary geometric objects like points, lines, circles, and elementary functionality on them.
• the second parameter is the algebraic kernel, which is responsible for computations on polynomials and algebraic numbers. It has to be a model of concept AlgebraicKernelForCircles. The robustness of the package relies on the fact that the algebraic kernel provides exact computations on algebraic objects.

The circular kernel uses the extensibility scheme presented in the 2D kernel manual (see Section Extensible Kernel). The types of Kernel are inherited by the circular kernel and some types are taken from the AlgebraicKernelForCircles parameter. Three new main geometric objects are introduced by Circular_kernel_2: circular arcs, points of circular arcs (used in particular for endpoints of arcs and intersection points between arcs) and line segments whose endpoints are points of this new type.

In fact, the circular kernel is documented as a concept, CircularKernel, and two models are provided:

• Circular_kernel_2<Kernel,AlgebraicKernelForCircles>, the basic kernel,
• and a predefined filtered kernel Exact_circular_kernel_2, that is based on similar techniques as Exact_predicates_exact_constructions_kernel.

Examples

The first example shows how to construct circles or circular arcs from points, and how to compute intersections between them using the global function.

File Circular_kernel_2/intersecting_arcs.cpp

#include <CGAL/Exact_circular_kernel_2.h>
#include <CGAL/point_generators_2.h>
#include <iostream>
 
typedef CGAL::Exact_circular_kernel_2             Circular_k;
 
typedef CGAL::Point_2<Circular_k>                 Point_2;
typedef CGAL::Circle_2<Circular_k>                Circle_2;
typedef CGAL::Circular_arc_2<Circular_k>          Circular_arc_2;
 
template <typename T>
double prob_2() {
  CGAL::Random_points_in_square_2<Point_2> g(1.0);
  double prob = 0.0;
  for (int i = 0; i < 10000; i++) {
 
    Point_2 p1, p2, p3, p4, p5, p6;
    p1 = *g++; p2 = *g++; p3 = *g++;
    p4 = *g++; p5 = *g++; p6 = *g++;
 
    // the pi's are points inherited from the Cartesian kernel Point_2, so,
    // the orientation predicate can be called on them
    if(CGAL::orientation(p1, p2, p3) != CGAL::COUNTERCLOCKWISE) std::swap(p1, p3);
    T o1 = T(p1, p2, p3);
    if(CGAL::orientation(p4, p5, p6) != CGAL::COUNTERCLOCKWISE) std::swap(p4, p6);
    T o2 = T(p4, p5, p6);
 
    typedef typename CGAL::CK2_Intersection_traits<Circular_k, T, T>::type
      Intersection_result;
    std::vector<Intersection_result> res;
    CGAL::intersection(o1, o2, std::back_inserter(res));
 
    prob += (res.size() != 0) ? 1.0 : 0.0;
  }
  return prob/10000.0;
}
 
int main()
{
  std::cout << "What is the probability that two arcs formed by" << std::endl;
  std::cout << "three random counterclockwise-oriented points on" << std::endl;
  std::cout << "an unit square intersect? (wait a second please)" << std::endl;
  std::cout << "The probability is: " << prob_2<Circular_arc_2>() <<
    std::endl << std::endl;
 
  std::cout << "And what about the probability that two circles formed by"
    << std::endl;
  std::cout << "three random counterclockwise-oriented points on" << std::endl;
  std::cout << "an unit square intersect? (wait a second please)" << std::endl;
  std::cout << "The probability is: " << prob_2<Circle_2>() << std::endl;
  return 0;
}

The following example shows how to use a functor of the kernel.

File Circular_kernel_2/functor_has_on_2.cpp

#include <CGAL/Exact_circular_kernel_2.h>
#include <iostream>
 
typedef CGAL::Exact_circular_kernel_2             Circular_k;
 
typedef CGAL::Point_2<Circular_k>                 Point_2;
typedef CGAL::Circular_arc_2<Circular_k>          Circular_arc_2;
 
int main()
{
  int n = 0;
  Circular_arc_2 c = Circular_arc_2(Point_2(10,0), Point_2(5,5), Point_2(0, 0));
 
  for(int i = 0; i <= 10; i++) {
    for(int j = 0; j <= 10; j++) {
      Point_2 p = Point_2(i, j);
      if(Circular_k().has_on_2_object()(c,p)) {
        n++;
        std::cout << "(" << i << "," << j << ")" << std::endl;
      }
    }
  }
  std::cout << "There are " << n << " points in the [0,..,10]x[0,..,10] "
            << "grid on the circular" << std::endl
            << " arc defined counterclockwisely by the points (0,0), (5,5), (10,0)"
            << std::endl << "See the points above." << std::endl;
  return 0;
}

Design and Implementation History

The first pieces of prototype code were comparisons of algebraic numbers of degree 2, written by Olivier Devillers [1],[2].

Some work was then done in the direction of a "kernel" for CGAL.Monique Teillaud, First Prototype of a CGAL Geometric Kernel with Circular Arcs, Technical Report ECG-TR-182203-01, 2002 Sylvain Pion and Monique Teillaud, Towards a CGAL-like kernel for curves, Technical Report ECG-TR-302206-01, 2003 and the first design emerged in [3].

The code of this package was initially written by Sylvain Pion and Monique Teillaud who also wrote the manual. Athanasios Kakargias had worked on a prototype version of this kernel in 2003. Julien Hazebrouck participated in the implementation in July and August

1. The contribution of Pedro Machado Manhães de Castro in summer 2006 improved significantly the efficiency of this kernel. He also added more functionality in 2008.

This work was partially supported by the IST Programme of the EU as a Shared-cost RTD (FET Open) Project under Contract No IST-2000-26473 (ECG - Effective Computational Geometry for Curves and Surfaces) and by the IST Programme of the 6th Framework Programme of the EU as a STREP (FET Open Scheme) Project under Contract No IST-006413 (ACS - Algorithms for Complex Shapes).

Todo:

fix manual for operator>>

Todo:

manual filtered bbox kernel, ref counting

Todo:

manual orientation: NO (only when points have same delta, so don't document)

Todo:

clean manual AK (concepts like Polynomial_1_2, access to a() b() c() ? used in solve to check that solutions are the same)

Todo:

rendre Bbox filtered kernel completement generique -> utilisation dans linear kernel aussi

Todo:

echecs de filtres

Todo:

voir make_x_monotone pour que ca retourne des arcs (necessite bricolage de la traits car Arr_2 demande des Object)

Todo:

interface intersect avec plusieurs outputIt types (types de retour differents)

Todo:

--> a transferer dans linear kernel ?

• unoriented equal (pb general orientation dans noyau cgal...)

Todo:

construct intersection for arcs should use solve or solve in range

Todo:

done (?)

Todo:

memory leaks in Filtered_bbox_circular_kernel_2

Todo:

from Andreas: there are new statements in constructors having no corresponding delete statements. This concerns the files in the directory: CGAL-3.3.1/include/CGAL/Filtered_bbox_circular_kernel_2/...with_bbox_2.h It should be enough to add destructors and add conditional deletes.

Todo:

Reading the code I think that the IO routines also don't do what they should do, namely computing new bboxes.