\( \newcommand{\E}{\mathrm{E}} \) \( \newcommand{\A}{\mathrm{A}} \) \( \newcommand{\R}{\mathrm{R}} \) \( \newcommand{\N}{\mathrm{N}} \) \( \newcommand{\Q}{\mathrm{Q}} \) \( \newcommand{\Z}{\mathrm{Z}} \) \( \def\ccSum #1#2#3{ \sum_{#1}^{#2}{#3} } \def\ccProd #1#2#3{ \sum_{#1}^{#2}{#3} }\)

CGAL 4.3 - CGAL Ipelets

All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Groups Pages
User Manual

Author
  Sébastien Loriot and Sylvain Pion

# Introduction

The Ipe extensible drawing editor (http://tclab.kaist.ac.kr/ipe/) [2], [1] is a tool used by computational geometry researchers to produce 2D figures for inclusion in articles or presentations. The extensible adjective sheds a light on an important feature: the possibility for users to write small extensions (called ipelets) to interface any algorithm with Ipe. This feature is especially interesting to produce illustrations in a paper describing a new algorithm. This package provides one class that eases the writing of ipelets based on CGAL, reducing the needed knowledge of the API of Ipe. This class is designed to fulfill most of the needs to implement an ipelet for a 2D CGAL algorithm. In addition, this package comes with more than ten complete examples of ipelets: alpha-shape, arrangements, Voronoi diagrams, convex hulls, Hilbert curve, k-order Delaunay, 2D mesh, Minkowski sum, polygon partition, random generators, triangulations \( \dots\)

# CGAL Ipelets

The class `Ipelet_base` derives from the class `Ipelets` from Ipe and has one template parameter indicating which kernel must be used within the ipelet. In practice, we recommend to use either `Exact_predicates_exact_constructions_kernel` or `Exact_predicates_inexact_constructions_kernel`.

Two main methods are provided by the `Ipelet_base` class. The first one, `read_active_objects` retrieves all primitives selected in Ipe when calling an ipelet, and converts them into equivalent CGAL objects. The second method, `draw_in_ipe` draws CGAL objects in the Ipe window. These functions handle basic objects such as points, segments, polygons, circles and circular arcs.

The registration of an ipelet into Ipe can be done using the macro `CGAL_IPELET`. `CGAL_IPELET(ipelet_class_name)` must follow the definition of the ipelet class, in the same file source file.

# Example

The following example shows how the class `Ipelet_base` can be used to easily interface the CGAL 2D Delaunay triangulation with Ipe.

File CGAL_ipelets/simple_triangulation.cpp

#include <CGAL/Exact_predicates_inexact_constructions_kernel.h>
#include <CGAL/Delaunay_triangulation_2.h>
#include <CGAL/CGAL_Ipelet_base.h>
namespace my_triangulation{
typedef CGAL::Exact_predicates_inexact_constructions_kernel Kernel;
typedef CGAL::Delaunay_triangulation_2<Kernel> Delaunay;
//Function names of the ipelet
const std::string labels[] = { "Delaunay","Help" };
//Help message associated to the first function
const std::string hmsg[] = {
"Draw a Delaunay triangulation of a set of points"
};
class Triangulation_ipelet
: public CGAL::Ipelet_base<Kernel,2>{
public:
//declare an ipelet called CGAL Delaunay, with 2 functions (including help message).
Triangulation_ipelet()
:CGAL::Ipelet_base<Kernel,2>("CGAL Delaunay",labels,hmsg){}
void protected_run(int);
};
//function called when using the ipelet.
void Triangulation_ipelet::protected_run(int fn)
{
switch (fn){
case 1:
show_help();//print an help message
return;
default:
std::list<Point_2> pt_lst;
//Recovering points using output iterator of type
//Dispatch_or_drop_output_iterator
read_active_objects(
CGAL::dispatch_or_drop_output<Point_2>(std::back_inserter(pt_lst))
);
if (pt_lst.empty()) {
print_error_message("No mark selected");
return;
}
Delaunay dt;
dt.insert(pt_lst.begin(),pt_lst.end());
//draw the triangulation.
draw_in_ipe(dt);
};
}
}//namespace my_triangulation
//register the ipelet in Ipe
CGAL_IPELET(my_triangulation::Triangulation_ipelet)

# Installation of the Demo Ipelets

Some working ipelets can be found within the demo directory of this package. To install them you need to go to the demo directory of the package and run cmake. The compilation of these demo requires the source tree and the library of Ipe. If your Ipe installation is not detected you need to set the cmake variables `IPE_INCLUDE_DIR` and `IPE_LIBRARIES`. If you want to install ipelets automatically (using `make install` for example) you also need to set the cmake variable `IPELET_INSTALL_DIR`, if the ipelet installation path has not already been detected. These ipelets have been tested with the versions 6.0pre28 to 6.0pre32 of Ipe, as well as with the version 7 (at least up to version 7.10). These ipelets are a good starting point to design your own ipelet. For more details on how to compile an ipelet, please refer to the Ipe manual.

# Design and Implementation History

A first draft of the CGAL ipelets has been implemented during the internship of Nicolas Carrez, in 2005, supervised by Olivier Devillers. Since then, the ipelets have been rewritten and extended by Sebastien Loriot as a stand-alone software with the help of Laurent Rineau. Finally, an enhanced version has been formally contributed to CGAL in 2009 by Sebastien Loriot. Sylvain Pion has participated in the discussion of the overall design, and contributed the Hilbert sort ipelet demo.