Completed the User Manual.

Minkowski_sum_2/doc_tex/Minkowski_sum_2/mink_sum.tex

@@ -35,13 +35,13 @@ also known as \emph{offsetting} or \emph{dilating} a polygon).
 \label{mink_sec:sum_poly}
 %====================================================
 
-Computing the Minkowski sum of two convex polygons $P$ ans $Q$ with
+Computing the Minkowski sum of two convex polygons $P$ and $Q$ with
 $m$ and $n$ vertices respectively is very easy, as $P \oplus Q$ is a
 convex polygon bounded by copies of the $m + n$ edges, and these edges
 are sorted by the angle they form with the $x$-axis. As the two
 input polygons are convex, their edges are already sorted by the
 angle they form with the $x$-axis. The Minkowski sum can therefore be
-computed in $O(m + n)$ time, by starting from two botommost vertices
+computed in $O(m + n)$ time, by starting from two bottommost vertices
 in $P$ and in $Q$ and performing ``merge sort'' on the edges.
 
 \begin{figure}[t]
@@ -78,7 +78,7 @@ We then calculate the pairwise sums $S_{ij} = P_i \oplus Q_j$ using the
 simple procedure described above, and compute the union $P \oplus Q =
 \bigcup_{ij}{S_{ij}}$.
 
-This approach relies on a decoposition strategy that computes the convex
+This approach relies on a decomposition strategy that computes the convex
 decomposition of the input polygons and its performance depends on the
 quality of the decomposition.
 %
@@ -91,7 +91,7 @@ order around their interiors) and compute the convolution of the two polygon
 boundaries. The {\em convolution} of these two polygons~\cite{grs-kfcg-83},
 denoted $P * Q$, is a collection of line segments of the form
 $[p_i + q_j, p_{i+1} + q_j]$,\footnote{Throughout this chapter, we increment
-or decrement an index of a vertex modulu the size of the polygon.}
+or decrement an index of a vertex modulo the size of the polygon.}
 where the vector $\overrightarrow{p_i p_{i+1}}$
 lies between $\overrightarrow{q_{j-1} q_j}$ and $\overrightarrow{q_j
 q_{j+1}}$,\footnote{We say that a vector $\vec{v}$ lies between
@@ -115,7 +115,7 @@ for an illustration.
 
 The number of segments in the convolution of two polygons is usually
 smaller than the number of segments that constitute the boundaries of the
-sub-sums $S_{ij}$ when using the decomposition approach. As both apporaches
+sub-sums $S_{ij}$ when using the decomposition approach. As both approaches
 construct the arrangement of these segments and extract the sum from this
 arrangement, computing Minkowski sum using the convolution approach usually
 generates a smaller intermediate arrangement, hence it is faster and
@@ -126,7 +126,7 @@ consumes less space.
 \label{mink_ssec:sum_conv}
 %------------------------------------------------------
 
-The function \ccc{minkowski_sum (P, Q)} accepts two simple polygons $P$
+The function \ccc{minkowski_sum_2 (P, Q)} accepts two simple polygons $P$
 and $Q$, represented using the \ccc{Polygon_2<Kernel,Container>}
 class-template and uses the convolution method in order to compute and
 return their Minkowski sum $S = P \oplus Q$.
@@ -156,12 +156,12 @@ in the example program \ccc{ex_sum_triangles.C}.}
 \label{mink_fig:sum_tri}
 \end{figure}
 
-The following example program constructs the Minkwoski sum of two triangles,
+The following example program constructs the Minkowski sum of two triangles,
 as depicted in Figure~\ref{mink_fig:sum_tri}. The result in this case is
-a convex hexagon. This program, as other example porgrams in this chapter,
+a convex hexagon. This program, as other example programs in this chapter,
 includes the auxiliary header file \ccc{ms_rational_nt.h} which defines
 \ccc{Number_type} as either \ccc{Gmpq} or \ccc{Quotient<MP_Float>},
-depending on whther the {\sc Gmp} library is installed or not.
+depending on whether the {\sc Gmp} library is installed or not.
 The file \ccc{print_util.h} includes auxiliary functions for printing polygons.
 
 \ccIncludeExampleCode{../examples/Minkowski_sum_2/ex_sum_triangles.C}
@@ -187,7 +187,7 @@ In the following program we compute the Minkowski sum of two polygons
 that are read from an input file. In this case, the sum is not simple
 and contains four holes, as illustrated in Figure~\ref{mink_fig:sum_holes}.
 Note that this example uses the predefined \cgal\ kernel with exact
-constrcutions. In general, instantiating polygons with this kernel yield
+constructions. In general, instantiating polygons with this kernel yield
 the fastest running times for Minkowski-sum computations.
 
 \ccIncludeExampleCode{../examples/Minkowski_sum_2/ex_sum_with_holes.C}
@@ -196,7 +196,7 @@ the fastest running times for Minkowski-sum computations.
 \label{mink_ssec:decomp}
 %------------------------------------
 
-In order to compute Minkwoski sums using the decomposition method, it is
+In order to compute Minkowski sums using the decomposition method, it is
 possible to call the function \ccc{minkowski_sum_2 (P, Q, decomp)}, where
 \ccc{decomp} is an instance of a class that models the concept
 \ccc{PolygonConvexDecomposition}, namely it should provide a method named
@@ -207,8 +207,8 @@ The Minkowski-sum package includes for models of the concept
 \ccc{PolygonConvexDecomposition}. The first three are classes that wrap
 the decomposition functions included in the Planar Polygon Partitioning
 package, while the fourth is an implementation of a decomposition algorithm
-introduced in~\cite{???}. The convex decompositions that it creates
+introduced in~\cite{cgal:afh-pdecm-02}. The convex decompositions that it
-usually yield efficient running times for Minkowski sum computations:
+creates usually yield efficient running times for Minkowski sum computations:
 \begin{itemize}
 \item
 The class \ccc{Optimal_convex_decomposition<Kernel>} uses the
@@ -236,7 +236,7 @@ and $O(n)$ space, and has the same approximation guarantee as
 Hertel and Mehlhorn's algorithm.
 %
 \item
-The class \ccc{Small_side_angle_bisecttor_convex_decomposition<Kernel>} uses
+The class \ccc{Small_side_angle_bisector_convex_decomposition<Kernel>} uses
 a heuristic improvement to the angle-bisector decomposition method
 suggested by Chazelle and Dobkin~\cite{cd-ocd-85}, which runs in
 $O(n^2)$ time. It starts by examining each pair of reflex vertices
@@ -314,7 +314,7 @@ sub-polygon and finally calculating the union of these sub-offsets
 the Minkowski sum of a pair of polygons, here it is also more
 efficient to compute the \emph{convolution cycle} of the polygon
 with the disc $B_r$,\footnote{As the disc is convex, it is guaranteed
-that the convolution curve is comrised of a single cycle.} which can be
+that the convolution curve is comprised of a single cycle.} which can be
 constructed by applying the process described in the previous
 paragraph. The only difference is that a circular arc induced by a
 reflex vertex $p_i$ is defined by an angle $540^{\circ} - \measuredangle
@@ -323,29 +323,43 @@ illustration. We finally compute the winding numbers of the faces of the
 arrangement induced by the convolution cycle to obtain the offset
 polygon.
 
-\begin{figure}[t]
-\begin{ccTexOnly}
-\begin{center}
-    \includegraphics{Minkowski_sum_2/fig/ex_offset} 
-\end{center}
-\end{ccTexOnly}
-\begin{ccHtmlOnly}
-  <p><center>
-  <img src="./fig/ex_offset.gif" border=0 alt="Offsetting a polygon">
-  </center>
-\end{ccHtmlOnly}
-\caption{The offset computation performed by the example programs
-\ccc{ex_exact_offset.C} and \ccc{ex_approx_offset.C}. The input polygon
-is shaded and the boundary of its offset is drawn in a thick black line.}
-\label{mink_fig:ex_offset}
-\end{figure}
-
-\ccIncludeExampleCode{../examples/Minkowski_sum_2/ex_exact_offset.C}
-
 \subsection{Approximating the Offset with a Guaranteed Error-Bound}
 \label{mink_ssec:approx_offset}
 %------------------------------------------------------------------
 
+Let us assume that we are given a counterclockwise-oriented polygon
+$P = \left( p_0, \ldots, p_{n-1} \right)$, whose vertices all have rational
+coordinates (i.e., for each vertex $p_i = (x_i, y_i)$ we have
+$x_i, y_i \in {\mathbb Q}$, and we wish to compute its Minkowski sum with a
+disc of radius $r$, where $r$ is also a rational number. The boundary of this
+sum is comprised of line segments an circular arcs, where:
+\begin{itemize}
+\item
+Each circular arc is supported by a circle of radius $r$ centered at one
+of the polygon vertices. The equation of this circle is $(x - x_i)^2 +
+(y - y_i)^2 = r^2$, and has only rational coefficients.
+%
+\item
+Each line segment is supported by a line parallel to one of the polygon
+edges $p_i p_{i+1}$, which lies at distance $r$ from this edge. If we 
+denote the supporting line of $p_i p_{i+1}$ by $Ax + By + C = 0$, where
+$A, B, C \in {\mathbb Q}$, then the offset edge is supported by the line
+$Ax + By + (C + \ell\cdot r) = 0$, where $\ell$ is the length of the edge
+$p_i p_{i+1}$ and is in general \emph{not} a rational number. The line segments
+that comprise the offset boundaries therefore cannot be represented as segments
+of lines with rational coefficients.
+%
+We mention that the locus of all points that lie at distance $r$ from the
+line $Ax + By + C = 0$ is given by:
+\[ \frac{(Ax + By + C)^2}{A^2 + B^2} = r^2 \ .\]
+Thus, the linear offset edges are segments of curves of an algebraic curve
+of degree 2 (a conic curve) with rational coefficients. This curve is
+actually a pair of the parallel lines $Ax + By + (C \pm \ell\cdot r) = 0$.
+In Section~\ref{mink_ssec:exact_offset} we use this representation to
+construct the offset polygon in an exact manner using the traits class for
+conic arcs.
+\end{itemize}
+
 \begin{figure}[t]
 \begin{ccTexOnly}
   \begin{center}
@@ -362,5 +376,112 @@ edge $p_1 p_2$ by two line segments $o'_1 q'$ and $q' o'_2$.}
 \label{mink_fig:approx_offset}
 \end{figure}
 
+The class-template \ccc{Gps_circle_segment_traits_2<Kernel>}, included in
+the Boolean Set-Operations package is used for representing general polygons
+whose edges are circular arcs or line segments, and for applying set operations
+(e.g. intersection, union, etc.) on such general polygon. It should be
+instantiated with a geometric kernel that employs exact rational arithmetic,
+such that the curves that comprise the polygon edges should be arcs of
+circles with rational coefficients or segments of lines with rational
+coefficients. As in our case the line segments do not satisfy this requirement,
+we apply a simple approximation scheme, such that each irrational line
+segment is approximated by two rational segments:
+\begin{enumerate}
+\item
+Consider the example depicted in Figure~\ref{mink_fig:approx_offset}, where
+the exact offset edge $o_1 o_2$ is obtained by shifting the polygon edge
+$p_1 p_2$ by a vector whose length is $r$ that form an angle $\phi$ with the
+$x$-axis. We select two points $o'_1$ and $o'_2$ with rational coordinates
+on the two circles centered at $p_1$ and $p_2$, respectively. These points
+are selected such that if we denote the angle that the vector $\vec{p_j o_j}$
+forms with the $x$-axis by $\phi'_j$ (for $j = 1, 2$), we have
+$\phi'_1 < \phi < \phi'_2$.
+%
+\item
+We construct two tangents to the two circles at $o'_1$ and $o'_2$,
+respectively. The tangent lines have rational coefficients.
+%
+\item
+We compute the intersection point of the two tangents, denoted $q'$.
+The two line segments $o'_1 q'$ and $q' o'_2$ approximate the original
+offset edge $o_1 o_2$.
+\end{enumerate}
+
+The function \ccc{approximated_offset_2 (P, r, eps)} accepts a polygon
+$P$, an offset radius $r$ and $\varepsilon > 0$. It constructs an
+approximation for the offset of $P$ by the radius $r$ using the procedure
+explained above. Furthermore, it is guaranteed that the approximation error,
+namely the distance of the point $q'$ from $o_1 o_2$ is bounded by
+$\varepsilon$. Using this function, we are capable of working with the
+\ccc{Gps_circle_segment_traits_2<Kernel>} class, which considerably
+speeds up the (approximate) construction of the offset polygon and the
+application of set operations on such polygons. The function returns an
+object of the nested type
+\ccc{Gps_circle_segment_traits_2<Kernel>::Polygon_with_holes_2} representing
+the approximated offset polygon (recall that if $P$ is not convex, its
+offset may not be simple an contain holes, whose boundary is also comprised
+of line segments and circular arcs).
+
+\begin{figure}[t]
+\begin{ccTexOnly}
+\begin{center}
+    \includegraphics{Minkowski_sum_2/fig/ex_offset} 
+\end{center}
+\end{ccTexOnly}
+\begin{ccHtmlOnly}
+  <p><center>
+  <img src="./fig/ex_offset.gif" border=0 alt="Offsetting a polygon">
+  </center>
+\end{ccHtmlOnly}
+\caption{The offset computation performed by the example programs
+\ccc{ex_approx_offset.C} and \ccc{ex_exact_offset.C}. The input polygon
+is shaded and the boundary of its offset is drawn in a thick black line.}
+\label{mink_fig:ex_offset}
+\end{figure}
+
+The following example demonstrates the construction of an approximated
+offset of a non-convex polygon, as depicted in
+Figure~\ref{mink_fig:ex_offset}. Note that we use a geometric kernel
+parameterized with a filtered rational number-type. Using filtering
+considerably speeds up the construction of the offset.
+
 \ccIncludeExampleCode{../examples/Minkowski_sum_2/ex_approx_offset.C}
 
+\subsection{Computing the Exact Offset}
+\label{mink_ssec:exact_offset}
+%--------------------------------------
+
+As we previously mentioned, it is possible to represent offset polygons
+in an exact manner, if we treat their edges as arcs of conic curves with
+rational coefficients. The function \ccc{offset_polygon_2 (traits, P, r)}
+computes the offset of the polygon $P$ by a rational radius $r$ in an
+exact manner. The \ccc{traits} parameter should be an instance of an
+arrangement-traits class that is capable of handling conic arcs in an
+exact manner; using the \ccc{Arr_conic_traits_2} class with the number
+types provided by the {\sc Core} library is the preferred option.
+The function returns an object of the nested type
+\ccc{Gps_traits_2<ArrConicTraits>::Polygons_with_holes_2} (see the
+documentation of the Boolean Set-Operations package for more details
+on the traits-class adapter \ccc{Gps_traits_2}), which represented the
+exact offset polygon.
+
+The following example demonstrates the construction of the offset
+of the same polygon that serves as an input for the example program
+\ccc{ex_approx_offset.C}, presented in the previous subsection (see also
+Figure~\ref{mink_fig:ex_offset}). Note that the resulting polygon is
+smaller than the one generated by the approximated-offset function (recall
+that each irrational line segment in this case is approximated by two
+rational line segments), but the offset computation is considerably slower:
+
+\ccIncludeExampleCode{../examples/Minkowski_sum_2/ex_exact_offset.C}
+
+\begin{ccAdvanced}
+Both functions \ccc{approximated_offset_2()} and \ccc{offset_polygon_2()}
+also have an overloaded versions that accept a decomposition strategy
+and use the polygon-decomposition approach to compute (or approximate)
+the offset. These functions are less efficient than their counterparts
+that employ the convolution approach, and are only included in the package
+for the sake of completeness.
+\end{ccAdvanced}
+
+