cgal/CGAL_ipelets/doc/CGAL_ipelets/CGAL_ipelets.txt

namespace CGAL {
/*!

\mainpage User Manual
\anchor Chapter_CGAL_Ipelets
\anchor chapcgalipelets
\cgalAutoToc
\author Olivier Devillers, Sébastien Loriot, and Sylvain Pion

\section CGAL_ipeletsIntroduction Introduction

The Ipe extensible drawing editor (<A HREF="https://ipe.otfried.org/">https://ipe.otfried.org/</A>) \cgalCite{schwarzkopf1995ede}, \cgalCite{ipe:man-09}
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 <I>ipelets</I>)
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 \f$ \dots\f$

\section seccgal_ipelets 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.

\section CGAL_ipeletsExample Example

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

\cgalExample{CGAL_ipelets/simple_triangulation.cpp}

\image html example.png
\image latex example.png

\section CGAL_ipeletsInstallation 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.

Below is the list of ipelets provided by the demo:

\section Ipelets_list List of provided Ipelets

\subsection alpha_shapes_ipelet Alpha Shapes

The input selection must be a set of points or circles
(considered as weighted points).
The whole spectrum of critical alpha values are computed and a dialog box
allows to choose one.


\subsection arrangement_ipelet Arrangement

The input selection can feature segments, circles, and arcs of circles.
The selected primitives are split at intersection points and arcs and
circles are split at their x-extrema.

\subsection bbox_restriction_ipelet Bounding Box Restriction

The input selection can feature segments, circles and arcs of circles, and
at least two points.
The selected primitives are clipped to the bounding box of the set of
points selected.


\subsection circle_pencils_ipelet Pencils of Circles

The input selection must be three circles or points (considered as
zero radius circles).

<ul>
<li><b> Circle in pencil, orthogonal to one circle</b>
draws the circle orthogonal to the primary
selection belonging to the pencil defined by the two other circles.
<li><b> Circle orthogonal to three circles</b>
draws the circle orthogonal to the three selected circles.
</ul>

\subsection cone_spanners_ipelet Cone spanners

The input selection must be a set of points. The value of k is asked
in a dialog box.

<ul>
<li><b>Theta-k-graph:</b>
Draws a theta-graph with k cones
<li><b>Yao-k-graph:</b>
Draws a Yao-graph with k cones
<li><b>Half-theta-k-graph with even cones:</b>
Draws an half-theta-graph with the even of k cones.
<li><b>Half-Yao-k-graph with even cones:</b>
Draws an half-Yao-graph with the even of k cones.
<li><b>Half-theta-k-graph with odd cones:</b>
Draws an half-theta-graph with the odd of k cones.
<li><b>Half-Yao-k-graph with odd cones:</b>
Draws an half-Yao-graph with the odd of k cones.
<li><b>k cones:</b> For earch selected point.
Draws the k cones around the point.
</ul>

\subsection diagrams_ipelet Diagrams
<ul>
<li><b> Voronoi:</b>
The input selection can feature points and segments. The Voronoi diagram
is computed and clipped to a box a bit larger than the selection.
The bisectors between a segment and its endpoints are drawn.
The Voronoi diagram partitions the plane depending on the closest
point or segment.
<li><b> Segment Voronoi skeleton:</b>
Same as the previous one, but the bisectors between a segment and its
endpoints are not drawn (the Voronoi region of the segment endpoints are
merged with that of the segment)
<li><b>Power diagram:</b>
The input selection must feature circles and points (zero radius circles). The power diagram
is computed and clipped to a box a bit larger than the selection.
The power diagram partitions the plane depending on the circle with smaller power.
<li><b> Apollonius:</b>
The input selection must feature circles and points (zero radius circles).
The Apollonius diagram is computed and clipped to a box a bit larger
than the selection.
The Apollonius diagram partitions the plane depending on the closest
circle (also called additively weighted Voronoi diagram).
</ul>

\subsection distance_ipelet Distance
The input selection must be two marks.
The distance between the two marks is output (for few seconds)
in the bottom of Ipe window. Can be computed in points, centimeters, or inches.
<ul>
<li><b> Distance between two marks (pts):</b>
<li><b> Distance between two marks (cm):</b>
<li><b> Distance between two marks (inch):</b>
</ul>


\subsection generator_ipelet Generators
A number of points to generate is asked in a dialog box.
<ul>
<li><b> Points in a disk</b>
generates random points in the selected circle.
 <li><b> Points on a grid</b>
generates a grid inside a square bounding the selection.
 <li><b> Points in a square</b>
generates random points inside a square bounding the selection.
 <li><b> Points on a convex hull</b>
generates a random convex polygon of given size  inside a square bounding the selection and
draw their convex hull.
 <li><b> Polygon</b>
generates a random simple polygon inside a square bounding the selection.
 <li><b> Segments in a square</b>
generates random line segments inside a square bounding the selection.
 <li><b> Circles (center in a square)</b>
generates random circles whose centers are inside a square bounding the selection.
</ul>

\subsection hilbert_sort_ipelet Hilbert Sort
The input selection must be a set of points.
<ul>
<li><b> Hilbert sorting curve, median policy</b>
splits the set of points in two at the median, alternatively in x and
y directions and draws the curve connecting the sorted points.
 <li><b> Hilbert sorting curve, middle policy</b>
splits the set of points in two at the middle, alternatively in x and
y directions and draws the curve connecting the sorted points.
</ul>

\subsection hull_ipelet Hulls
<ul>
 <li><b> Convex minimal:</b>
The input selection must feature points, segments or circles.
The convex hull of the selected primitive is drawn.
 <li><b>Crust:</b>
The input section must be a set of points.
The crust of the point set is drawn (curve reconstruction).
</ul>

\subsection hyperbolic_ipelet Hyperbolic
Tools for hyperbolic geometry in the Poincare disk model.

<ul>
 <li><b> Line through two points:</b>
The input selection must be the Poincare circle and two points inside the
circle. The hyperbolic line through the points is drawn.
 <li><b> Segment through two points:</b>
The input selection must be the Poincare circle and two points inside the
circle. The hyperbolic line segment through the points is drawn.
 <li><b> Bisector of two points:</b>
The input section must be the Poincare circle and two points inside the
circle. The hyperbolic bisector of the points is drawn.
 <li><b> Circle by center and point:</b>
The input selection must be the Poincare circle and two points inside the
circle, one of these points being the primary selection.
 The hyperbolic circle centered at the primary selection through the
 other point is drawn.
 <li><b> Circle center:</b>
The input selection must be the Poincare circle and another circle inside
the latter being the primary selection.
 The hyperbolic center of the primary selection is drawn.
</ul>

\subsection mesh_2_ipelet Mesh_2
The input selection must be a set of polygons defining a domain,
and a set of circles defining connected region that are not part
of the domains (holes).
A mesh of the domain is computed and drawn using the maximal edge
length provided asked in a dialog box.

\subsection minkowski_ipelet Minkowski Sum
<ul>
 <li><b>Minkowski Sum:</b>
The input selection must be two simple polygons.
The Minkowski sum of the two polygons is computed and drawn.
 <li><b>Polygon Offset:</b>
The input selection must be a circle and simple polygons.
The Minkowski sum of the polygons with the circle is computed and drawn.
</ul>

\subsection mst_ipelet Minimum Spanning Tree
The input selection must be a set of points. The Euclidean minimum spanning
tree of the points is computed and drawn.

\subsection multi_delaunay_ipelet k Order Delaunay
The input selection must be a set of points.
The order k Voronoi diagram or its dual the order k Delaunay is drawn.
<ul>
 <li><b> Delaunay:</b>
Ordinary Delaunay triangulation.
 <li><b> Delaunay 2:</b>
Triangulation of middle of Delaunay edges.
 <li><b> Delaunay 3:</b>
Triangulation of barycenters of some triangles.
 <li><b> Delaunay n-1:</b>
Dual of farthest neighbor Voronoi diagram.
 <li><b> Delaunay k:</b>
k is asked in a dialog box.
 <li><b> Voronoi:</b>
Ordinary Voronoi diagram.
 <li><b> Voronoi 2:</b>
Order 2 Voronoi diagram.
 <li><b> Voronoi 3:</b>
Order 3 Voronoi diagram.
 <li><b> Voronoi n-1:</b>
Farthest neighbor Voronoi diagram.
 <li><b> Voronoi k:</b>
k is asked in a dialog box.
</ul>

\subsection multi_regular_ipelet k Order Regular
The input selection must be a set of points and circles.
The order k power diagram or its dual the order k regular triangulation is drawn.
<ul>
 <li><b>Regular:</b> Ordinary regular triangulation.
 <li><b>Regular 2:</b> Triangulation of middle of  edges
 of the regular triangulation.
 <li><b>Regular 3:</b>
Triangulation of barycenters of some triangles.
 <li><b>Regular n-1:</b>
Dual of farthest neighbor power diagram.
 <li><b>Regular k:</b>
k is asked in a dialog box.
 <li><b>Power Diagram:</b> Ordinary power diagram.
 <li><b>Power Diagram 2:</b> Order 2 power diagram.
 <li><b>Power Diagram 3:</b> Order 3 power diagram.
 <li><b>Power Diagram n-1:</b> Farthest neighbor power diagram.
 <li><b>Power Diagram k:</b>
k is asked in a dialog box.
</ul>

\subsection partition_ipelet Polygon Partition
The input selection must be simple polygons.
The polygons are divided using different algorithms.
<ul>
 <li><b> Y monotone partition:</b> Regions of the partition are \f$ y
 \f$ monotone
 <li><b> Greene's approx Convex Partition:</b> Regions of the
 partition are convex.
 <li><b> Approx Convex Partition:</b>Regions of the
 partition are convex.
 <li><b> Optimal Convex Partition:</b>Regions of the
 partition are convex and their number is minimized.
</ul>

\subsection pca_ipelet PCA
The input selection must be a set of points.
A line segment giving the principal direction of the selection is drawn.

\subsection skeleton_ipelet  Skeleton and Offset
The input selection must be a simple polygon.
The straight skeleton and associated offsets of the polygon are drawn.
 <ul>
<li><b> Interior skeleton</b> draws the interior skeleton.
 <li><b> Exterior skeleton</b> draws the exterior skeleton.
 <li><b> Interior offset</b>
 draws an interior offset using the value provided in the dialog box.
 <li><b> Exterior offset</b>
 draws an exterior offset using the value provided in the dialog box.
 <li><b> Interior offsets</b>
draws several equally spaced  interior offsets are drawn
using the value provided in the dialog box.
 <li><b> Exterior offsets</b>
draws several equally spaced exterior offsets using the value provided in the dialog box.
</ul>

\subsection triangulation_ipelet Triangulations
<ul>
 <li><b> Delaunay:</b>
The input selection must be a set of points. The Delaunay triangulation of the
 points is drawn.
 <li><b> Constrained Delaunay:</b>
The input selection must be a set of points and line segments. The Delaunay
 triangulation of the points and segment's endpoints that respects the constraints is drawn.
 <li><b>Conforming Delaunay:</b>
The input selection must be a set of points and line segments. Points are
 added so that the Delaunay of selected points, segment's endpoints,
 and added points respects the constraints. The triangulation  is drawn.
 <li><b> Conforming Gabriel:</b>
The input selection must be a set of points and line segments. Points are
 added so that the pieces of segments have Gabriel property (their
 diametral disk is empty). The Delaunay triangulation  is drawn.
 <li><b> Regular:</b>
The input selection must be a set of points and circles (weighted points). The
 regular triangulation (dual of power diagram) of the
 points and circle's centers is drawn.
</ul>

\section CGAL_ipeletsDesign 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.
Olivier Devillers added the pencil of circles and hyperbolic geometry
ipelets in 2014.

*/
} /* namespace CGAL */