Improved and introduced the overloaded minkowski_sum_2(), which accepts 2 decompositio strategies

Minkowski_sum_2/doc/Minkowski_sum_2/Minkowski_sum_2.txt

@@ -13,16 +13,16 @@ namespace CGAL {
 
 Given two sets \f$ A,B \in \mathbb{R}^d\f$, their <I>Minkowski sum</I>,
 denoted by \f$ A \oplus B\f$, is their point-wise sum, namely the set
-\f$ \left\{ a + b ~|~ a \in A, b \in B \right\}\f$.
-Minkowski sums are used in many applications, such as motion planning and
-computer-aided design and manufacturing. This package contains functions
-that compute the planar Minkowski sums of two simple polygons; namely,
-\f$ A\f$ and \f$ B\f$ are two closed polygons in \f$ \mathbb{R}^2\f$)
-(see Chapter \ref Chapter_2D_Regularized_Boolean_Set-Operations
-"2D Regularized Boolean Set-Operations" for the precise definition of a
-simple polygon), and the planar Minkowski sum of a simple polygon and a
+\f$ \left\{ a + b ~|~ a \in A, b \in B \right\}\f$. Minkowski sums are
+used in many applications, such as motion planning and computer-aided
+design and manufacturing. This package contains functions that compute
+the planar Minkowski sums of two polygons. (Here, \f$ A\f$ and \f$ B\f$
+are two closed polygons in \f$ \mathbb{R}^2\f$, which may have holes; see
+Chapter \ref Chapter_2D_Regularized_Boolean_Set-Operations "2D
+Regularized Boolean Set-Operations" for the precise definition of valid
+polygons), and the planar Minkowski sum of a simple polygon and a
 disc---an operation also referred to as <I>offsetting</I> or <I>dilating</I>
-a polygon).\cgalFootnote{The family of valid types of summands is slightly
+a polygon). \cgalFootnote{The family of valid types of summands is slightly
 broader for certain operations, e.g., a degenerate polygon consisting of
 line segments is a valid operand for the approximate-offsetting operation.}
 This package, like the \ref Chapter_2D_Regularized_Boolean_Set-Operations
@@ -32,7 +32,7 @@ by the \ref chapterArrangement_on_surface_2 "2D Arrangements" package.
 The two packages are integrated well to
 allow mixed operations. For example, it is possible to apply Boolean set
 operations on objects that are the result of Minkowski sum
-computations.\cgalFootnote{The operands of the Minkowski sum operations
+computations. \cgalFootnote{The operands of the Minkowski sum operations
 supported by this package must be (linear) polygons, as opposed to the
 operands of the Boolean set operations supported by the
 \ref Chapter_2D_Regularized_Boolean_Set-Operations
@@ -51,7 +51,7 @@ edges ordered according to the angle they form with the \f$ x\f$-axis. As the
 two input polygons are convex, their edges are already sorted by the angle
 they form with the \f$ x\f$-axis; see the figure above.
 The Minkowski sum can therefore be computed using an operation similar to the
-merge step of the merge-sort algorithm\cgalFootnote{See, for example,
+merge step of the merge-sort algorithm \cgalFootnote{See, for example,
 <a href="http://en.wikipedia.org/wiki/Merge_sort">
 http://en.wikipedia.org/wiki/Merge_sort</a>.} in \f$ O(m + n)\f$ time,
 starting from two bottommost vertices in \f$ P\f$ and in \f$ Q\f$ and merging
@@ -62,16 +62,14 @@ The convolution of a convex polygon and a non-convex polygon. The convolution
 consists of a single self-intersecting cycle, drawn as a sequence of directed
 line segments. Each face of the arrangement induced by the segments forming
 the cycle contains its winding number. The Minkowski sum of the two polygons
-is shaded.
+is shaded. Dotted edges are not part of the reduced convolution.
 \cgalFigureEnd
 
 If the polygons are not convex, you can utilize either the
-<I>Decomposition</I> or the <I>Convolution</I> approaches described below.
-Regarding the implementation of the two approaches, applications of
-Minkowski sum operations are restricted to polygons that are simple.
-Applications of some of the variant operations are also restricted to
-polygons that do not contain holes. (Resulting sums may contain holes
-though.)
+<I>Decomposition</I> or the <I>Convolution</I> approaches described
+below.  Applications of some of the operations in this package are
+restricted to polygons that do not contain holes. (Resulting sums may
+contain holes though.)
 
 <DL>
 <DT><B>Decomposition:</B><DD>
@@ -84,92 +82,119 @@ simple procedure described above, and finally compute the union
 \f$ P \oplus Q = \bigcup_{ij}{S_{ij}}\f$;
 see \ref ref_bso_union "Union Functions".
 
-This approach relies on a successful decomposition of the input polygons
-into convex pieces, and its performance depends on the quality and performance
-of the decomposition. The supplied decomposition methods do not handle point
-sets that are not simple.
+This approach relies on a successful decomposition of the input
+polygons into convex pieces, and its performance depends on the
+quality and performance of the decomposition. Some of the supplied
+decomposition methods do not handle polygons that contain holes.
 
 <DT><B>Convolution:</B><DD>
-Let us denote the vertices of the input polygons by
-\f$ P = \left( p_0, \ldots, p_{m-1} \right)\f$ and
-\f$ Q = \left( q_0, \ldots, q_{n-1} \right)\f$. We assume that both \f$ P\f$ and \f$ Q\f$
-have positive orientations (i.e.\ their boundaries wind in a counterclockwise
-order around their interiors) and compute the convolution of the two polygon
-boundaries. The <I>convolution</I> of these two polygons \cgalCite{grs-kfcg-83},
+Let \f$ P = \left( p_0, \ldots, p_{m-1} \right)\f$ and
+\f$ Q = \left(q_0, \ldots, q_{n-1} \right)\f$ denote the vertices of
+the input polygons. We assume that both \f$ P\f$ and \f$ Q\f$ have
+positive orientations (i.e., their boundaries wind in a
+counterclockwise order around their interiors). The
+<I>convolution</I> of these two polygons \cgalCite{grs-kfcg-83},
 denoted \f$ P * Q\f$, is a collection of line segments of the form
-\f$ [p_i + q_j, p_{i+1} + q_j]\f$, \cgalFootnote{Throughout this chapter, we increment
-or decrement an index of a vertex modulo the size of the polygon.}
-where the vector \f$ {\mathbf{p_i p_{i+1}}}\f$
-lies between \f$ {\mathbf{q_{j-1} q_j}}\f$ and \f$ {\mathbf{q_j
-q_{j+1}}}\f$, \cgalFootnote{We say that a vector \f$ {\mathbf v}\f$ lies between
-two vectors \f$ {\mathbf u}\f$ and \f$ {\mathbf w}\f$ if we reach \f$ {\mathbf v}\f$ strictly before reaching \f$ {\mathbf w}\f$ if we move all three vectors to the origin and rotate \f$ {\mathbf u}\f$ counterclockwise. Note that this also covers the case where \f$ {\mathbf u}\f$ has the same direction as \f$ {\mathbf v}\f$.} and, symmetrically, of segments of the form \f$ [p_i + q_j, p_i + q_{j+1}]\f$,
-where the vector \f$ {\mathbf{q_j q_{j+1}}}\f$ lies between
-\f$ {\mathbf{p_{i-1} p_i}}\f$ and \f$ {\mathbf{p_i p_{i+1}}}\f$.
+\f$ [p_i + q_j, p_{i+1} + q_j]\f$, \cgalFootnote{Throughout this
+chapter, we increment or decrement an index of a vertex modulo the
+size of the polygon.} where the vector \f$ {\mathbf{p_i p_{i+1}}}\f$
+lies between \f$ {\mathbf{q_{j-1} q_j}}\f$ and
+\f$ {\mathbf{q_j q_{j+1}}}\f$, \cgalFootnote{We say that a vector
+\f$ {\mathbf v}\f$ lies between two vectors \f$ {\mathbf u}\f$ and
+\f$ {\mathbf w}\f$ if we reach \f$ {\mathbf v}\f$ strictly before
+reaching \f$ {\mathbf w}\f$ if we move all three vectors to the
+origin and rotate \f$ {\mathbf u}\f$ counterclockwise. Note that this
+also covers the case where \f$ {\mathbf u}\f$ has the same direction
+as \f$ {\mathbf v}\f$.} and, symmetrically, of segments of the form
+\f$ [p_i + q_j, p_i + q_{j+1}]\f$, where the vector \f$ {\mathbf{q_j
+q_{j+1}}}\f$ lies between \f$ {\mathbf{p_{i-1} p_i}}\f$ and \f$
+{\mathbf{p_i p_{i+1}}}\f$.
 
 The segments of the convolution form a number of closed (not
-necessarily simple) polygonal curves called <I>convolution
-cycles</I>. The Minkowski sum \f$ P \oplus Q\f$ is the set of points
-having a non-zero winding number with respect to the cycles
-of \f$ P * Q\f$. \cgalFootnote{Informally speaking, the winding number of a point \f$ p \in\mathbb{R}^2\f$ with respect to some planar curve \f$ \gamma\f$ is an integer number counting how many times does \f$ \gamma\f$ wind in a counterclockwise direction around \f$ p\f$.} See \cgalFigureRef{mink_figonecyc}
-for an illustration.
+necessarily simple) polygonal curves called <I>convolution cycles</I>.
+The Minkowski sum \f$ P \oplus Q\f$ is the set of points
+having a non-zero winding number with respect to the cycles of
+\f$ P * Q\f$. \cgalFootnote{Informally speaking, the winding number
+of a point \f$ p \in\mathbb{R}^2\f$ with respect to some planar curve
+\f$ \gamma\f$ is an integer number counting how many times does
+\f$ \gamma\f$ wind in a counterclockwise direction around \f$ p\f$.}
+See \cgalFigureRef{mink_figonecyc} 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 \f$ S_{ij}\f$ 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
-consumes less space.
-<DT><B>Reduced Convolution:</B><DD>
-We can reduce the number of segments in the arrangement even further by
-noticing that only convolution segments created by a convex vertex can be part
-of the Minkowski sum. In segments of the form \f$ [p_i + q_j, p_{i+1} + q_j]\f$,
-the vertex \f$q_j\f$ has to be convex, and in segments of the form \f$
-[p_i + q_j, p_i + q_{j+1}]\f$, the vertex \f$p_i\f$ has to be convex. The
-collection of the remaining segments is called the <I>reduced convolution</I>
-\cgalCite{cgal:bl-frmsurc-11}.
+We construct the arrangement induced by the convolution cycles of
+\f$P \f$ and \f$Q \f$, then compute the winding numbers of the cells
+of the arrangement. Finally, we extract the Minkowski sum from the
+arrangement. This variant is referred to as the full-convolution method.
 
-The winding number property can no longer be used here. Instead we define two
-different filters to identify holes in the Minkowski sum:
+A segment \f$[p_i + q_j, p_{i+1} + q_j] \f$ (resp.
+\f$[p_i + q_j, p_i + q_{j+1}] \f$) cannot possibly contribute to the
+boundary of the Minkowski sum if \f$q_j \f$ (resp. \f$p_i \f$) is a
+reflex vertex (see dotted edges in \cgalFigureRef{mink_figonecyc}).
+The remaining subset of convolution segments is called the
+<I>reduced convolution</I> \cgalCite{cgal:bl-frmsurc-11}. This subset
+is still a superset of the Minkowski sum boundary, but the winding
+number property does not apply any longer as there are no closed
+cycles anymore. We apply two different filters, which identify holes in
+the Minkowski sum:
 <OL>
-<LI>Loops that are on the Minkowski sum's boundary have to be orientable, that
-is, all normal directions of its edges have to point either inward or
-outward.</LI>
-<LI>For any point \f$x\f$ inside of a hole of the Minkowski sum, the following
-condition holds: \f$(-P + x) \cap Q = \emptyset\f$. If, on the other hand, the
-inversed version of \f$P\f$, translated by \f$x\f$, overlaps \f$Q\f$, the loop
-is a <I>false</I> hole and is in the Minkowski sum's interior.</LI>
+<LI>A loop that is on the Minkowski sum boundary has to be orientable;
+  that is, all normal directions of its edges have to point either
+  inward or outward.</LI>
+<LI>For any point \f$x\f$ inside of a hole of the Minkowski sum, the
+  following condition holds: \f$(-P + x) \cap Q = \emptyset\f$. If, on
+  the other hand, the inversed version of \f$P\f$, translated by
+  \f$x\f$, overlaps \f$Q\f$, the loop is a <I>false</I> hole and is in
+  the interior of the Minkowski sum.</LI>
 </OL>
 
-After applying these two filters, only those segments which constitute the
-Minkowski sum's boundary remain. In most cases, the reduced convolution
-approach is even faster than the full convolution approach, as the induced
-arrangement is usually much smaller. However, in degenerated cases with many
-holes in the Minkowski sum, the full convolution approach can be preferable to
-avoid the costly intersection tests.
+After applying these two filters, only those segments which constitute
+the Minkowski sum boundary remain. This variant is referred to as the
+reduced-convolution method.
 </DL>
 
+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 \f$ S_{ij}\f$ 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 consumes less space. In most cases,
+the reduced convolution method is faster than the full convolution
+method, as the respective induced arrangement is usually much smaller.
+However, in degenerate cases with many holes in the Minkowski sum, the
+full convolution method can be preferable, as it avoids costly
+intersection tests.
+
 \subsection mink_ssecsum_conv Computing Minkowski Sum using Convolutions
 
-The function template \link minkowski_sum_2() `minkowski_sum_2(P, Q)`\endlink
-accepts two simple polygons \f$ P\f$ and \f$ Q\f$ and computes their
-Minkowski sum \f$ S = P \oplus Q\f$ using the convolution method.
-\link minkowski_sum_2() `minkowski_sum_2(P, Q)`\endlink defaults to calling the
-function \link minkowski_sum_reduced_convolution_2() `minkowski_sum_reduced_convolution_2(P, Q)`\endlink,
-which applies the reduced convolution aforementioned.
-Explicitly call the function \link minkowski_sum_full_convolution_2()
+The function template \link minkowski_sum_2()
+`minkowski_sum_2(P, Q)`\endlink accepts two polygons
+\f$ P\f$ and \f$ Q\f$ and computes their Minkowski sum
+\f$ S = P \oplus Q\f$ using the convolution approach.
+The call \link minkowski_sum_2() `minkowski_sum_2(P, Q)`\endlink
+defaults to the call \link minkowski_sum_reduced_convolution_2()
+`minkowski_sum_reduced_convolution_2(P, Q)`\endlink, which applies
+the reduced convolution aforementioned method. Explicitly call
+\link minkowski_sum_full_convolution_2()
 `minkowski_sum_full_convolution_2(P, Q)`\endlink to apply
-the full convolution approach.
-The types of the operands are instances of the
-\link Polygon_2 `Polygon_2`\endlink class template. As the input polygons
-may not be convex, their Minkowski sum may not be simply connected and
-contain polygonal holes; see for example \cgalFigureRef{mink_figonecyc}.
-The type of the returned object \f$ S \f$ is therefore an instance of the
-\link Polygon_with_holes_2 `Polygon_with_holes_2`\endlink class template.
-The outer boundary of \f$ S \f$ is a polygon that can be accessed using
-`S.outer_boundary()`, and its polygonal holes are given by the range
-[`S.holes_begin()`, `S.holes_end()`) (where \f$ S \f$ contains
-`S.number_of_holes()` holes in its interior).
+the full convolution method. The types of the operands accepted by
+the function \link minkowski_sum_full_convolution_2()
+`minkowski_sum_full_convolution_2(P, Q)`\endlink are instances of
+the \link Polygon_2 `Polygon_2`\endlink class template. The types of
+operands accepted by the function \link
+minkowski_sum_reduced_convolution_2()
+`minkowski_sum_reduced_convolution_2(P, Q)`\endlink
+are instances of either the \link Polygon_2 `Polygon_2`\endlink or
+\link Polygon_with_holes_2 `Polygon_with_holes_2`\endlink class templates.
+Even when the input polygons are restricted to be simple polygons, they
+still may not be convex; thus, their Minkowski sum may not be simply
+connected and may contain polygonal holes; see for example
+\cgalFigureRef{mink_figonecyc}. The type of the returned object \f$ S \f$
+is therefore an instance of the
+\link Polygon_with_holes_2 `Polygon_with_holes_2`\endlink class template
+in all cases. Recall that the outer boundary of \f$S \f$  is a polygon
+that can be accessed using `S.outer_boundary()`, and its polygonal
+holes are given by the range [`S.holes_begin()`, `S.holes_end()`) (where
+\f$ S \f$ contains `S.number_of_holes()` holes in its interior).
 
 \cgalFigureBegin{mink_figsum_tri_sqr,ms_sum_triangle_square.png}
 The Minkowski sum of a triangle and a square, as computed by the example
@@ -208,17 +233,26 @@ Minkowski sum procedure.
 
 In order to compute Minkowski sums of two polygon \f$ P \f$ and
 \f$ Q \f$ using the decomposition method, issue the call
-`minkowski_sum_2(P, Q, decomp)`, where `decomp` is an object of a type
-that models the concept `PolygonConvexDecomposition`, which in turn
-refines a `Functor` concept variant. Namely, it requires the provision
-of a function operator (`operator()`) that accepts a planar polygon and
-returns a range of convex polygons that represents its convex decomposition.
-If at least one of \f$ P \f$ or \f$ Q \f$ is a polygon with holes,
-`decomp` is an object of a type that models the concept
+`minkowski_sum_2(P, Q, decompP, decompQ)`, where each of \f$P \f$
+and \f$Q \f$ is either a simple polygon or a polygon with holes.
+If \f$P \f$ is a simple polygon, `decompP` must be an object of
+a type that models the concept `PolygonConvexDecomposition_2`.
+If \f$P \f$ is a polygon with holes, them `decompP` is an object
+of a type that models the concept
 `PolygonWithHolesConvexDecomposition_2`, which refines the concept
-`PolygonConvexDecomposition` and adds a requirement for the provision
-of a function operator (`operator()`) that accepts a planar polygon with
-holes.
+`PolygonConvexDecomposition_2`. The same holds for \f$Q \f$.
+The two concepts `PolygonConvexDecomposition_2` and
+`PolygonWithHolesConvexDecomposition` refine a `Functor` concept
+variant. Namely, they both require the provision of a function
+operator (`operator()`). The function operator of the model of the
+concept `PolygonConvexDecomposition_2` accepts a planar simple
+polygon, while the function operator of the model of the concept
+`PolygonWithHolesConvexDecomposition_2` accepts a planar polygon
+with holes. Both return a range of convex polygons that represents
+the convex decomposition of the input polygon. If the decomposition
+strategy that decomposes \f$P \f$ is the same as the strategy that
+decompose \f$Q \f$, you can omit the forth argument, and
+issue the call `minkowski_sum_2(P, Q, decomp)`.
 
 The Minkowski-sum package includes four models of the concept
 `PolygonConvexDecomposition_2` and two models of the refined concept
@@ -274,7 +308,7 @@ diagonal that is closest to the angle bisector emanating from this
 vertex and having rational-coordinate endpoints on both sides.
 </UL>
 
-The following two models the refined concept
+The following are two models of the refined concept
 `PolygonWithHolesConvexDecomposition_2`. An instance of any one these
 two types can be used to decompose a polygon with holes. You can pass
 the instance as the third argument to call