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.