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,14 +13,14 @@ 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$.
+\f$ \left\{ a + b ~|~ a \in A, b \in B \right\}\f$. Minkowski sums are
-Minkowski sums are used in many applications, such as motion planning and
+used in many applications, such as motion planning and computer-aided
-computer-aided design and manufacturing. This package contains functions
+design and manufacturing. This package contains functions that compute
-that compute the planar Minkowski sums of two simple polygons; namely,
+the planar Minkowski sums of two polygons. (Here, \f$ A\f$ and \f$ B\f$
-\f$ A\f$ and \f$ B\f$ are two closed polygons in \f$ \mathbb{R}^2\f$)
+are two closed polygons in \f$ \mathbb{R}^2\f$, which may have holes; see
-(see Chapter \ref Chapter_2D_Regularized_Boolean_Set-Operations
+Chapter \ref Chapter_2D_Regularized_Boolean_Set-Operations "2D
-"2D Regularized Boolean Set-Operations" for the precise definition of a
+Regularized Boolean Set-Operations" for the precise definition of valid
-simple polygon), and the planar Minkowski sum of a simple polygon and a
+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
 broader for certain operations, e.g., a degenerate polygon consisting of
@@ -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.
+<I>Decomposition</I> or the <I>Convolution</I> approaches described
-Regarding the implementation of the two approaches, applications of
+below.  Applications of some of the operations in this package are
-Minkowski sum operations are restricted to polygons that are simple.
+restricted to polygons that do not contain holes. (Resulting sums may
-Applications of some of the variant operations are also restricted to
+contain holes though.)
-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
+This approach relies on a successful decomposition of the input
-into convex pieces, and its performance depends on the quality and performance
+polygons into convex pieces, and its performance depends on the
-of the decomposition. The supplied decomposition methods do not handle point
+quality and performance of the decomposition. Some of the supplied
-sets that are not simple.
+decomposition methods do not handle polygons that contain holes.
 
 <DT><B>Convolution:</B><DD>
-Let us denote the vertices of the input polygons by
+Let \f$ P = \left( p_0, \ldots, p_{m-1} \right)\f$ and
-\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
-\f$ Q = \left( q_0, \ldots, q_{n-1} \right)\f$. We assume that both \f$ P\f$ and \f$ Q\f$
+the input polygons. We assume that both \f$ P\f$ and \f$ Q\f$ have
-have positive orientations (i.e.\ their boundaries wind in a counterclockwise
+positive orientations (i.e., their boundaries wind in a
-order around their interiors) and compute the convolution of the two polygon
+counterclockwise order around their interiors). The
-boundaries. The <I>convolution</I> of these two polygons \cgalCite{grs-kfcg-83},
+<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
+\f$ [p_i + q_j, p_{i+1} + q_j]\f$, \cgalFootnote{Throughout this
-or decrement an index of a vertex modulo the size of the polygon.}
+chapter, we increment or decrement an index of a vertex modulo the
-where the vector \f$ {\mathbf{p_i p_{i+1}}}\f$
+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
+lies between \f$ {\mathbf{q_{j-1} q_j}}\f$ and
-q_{j+1}}}\f$, \cgalFootnote{We say that a vector \f$ {\mathbf v}\f$ lies between
+\f$ {\mathbf{q_j q_{j+1}}}\f$, \cgalFootnote{We say that a vector
-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$,
+\f$ {\mathbf v}\f$ lies between two vectors \f$ {\mathbf u}\f$ and
-where the vector \f$ {\mathbf{q_j q_{j+1}}}\f$ lies between
+\f$ {\mathbf w}\f$ if we reach \f$ {\mathbf v}\f$ strictly before
-\f$ {\mathbf{p_{i-1} p_i}}\f$ and \f$ {\mathbf{p_i p_{i+1}}}\f$.
+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
+necessarily simple) polygonal curves called <I>convolution cycles</I>.
-cycles</I>. The Minkowski sum \f$ P \oplus Q\f$ is the set of points
+The Minkowski sum \f$ P \oplus Q\f$ is the set of points
-having a non-zero winding number with respect to the cycles
+having a non-zero winding number with respect to the cycles of
-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}
+\f$ P * Q\f$. \cgalFootnote{Informally speaking, the winding number
-for an illustration.
+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
+We construct the arrangement induced by the convolution cycles of
-smaller than the number of segments that constitute the boundaries of the
+\f$P \f$ and \f$Q \f$, then compute the winding numbers of the cells
-sub-sums \f$ S_{ij}\f$ when using the decomposition approach. As both approaches
+of the arrangement. Finally, we extract the Minkowski sum from the
-construct the arrangement of these segments and extract the sum from this
+arrangement. This variant is referred to as the full-convolution method.
-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}.
 
-The winding number property can no longer be used here. Instead we define two
+A segment \f$[p_i + q_j, p_{i+1} + q_j] \f$ (resp.
-different filters to identify holes in the Minkowski sum:
+\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
+<LI>A loop that is on the Minkowski sum boundary has to be orientable;
-is, all normal directions of its edges have to point either inward or
+  that is, all normal directions of its edges have to point either
-outward.</LI>
+  inward or outward.</LI>
-<LI>For any point \f$x\f$ inside of a hole of the Minkowski sum, the following
+<LI>For any point \f$x\f$ inside of a hole of the Minkowski sum, the
-condition holds: \f$(-P + x) \cap Q = \emptyset\f$. If, on the other hand, the
+  following condition holds: \f$(-P + x) \cap Q = \emptyset\f$. If, on
-inversed version of \f$P\f$, translated by \f$x\f$, overlaps \f$Q\f$, the loop
+  the other hand, the inversed version of \f$P\f$, translated by
-is a <I>false</I> hole and is in the Minkowski sum's interior.</LI>
+  \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
+After applying these two filters, only those segments which constitute
-Minkowski sum's boundary remain. In most cases, the reduced convolution
+the Minkowski sum boundary remain. This variant is referred to as the
-approach is even faster than the full convolution approach, as the induced
+reduced-convolution method.
-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.
 </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
+The function template \link minkowski_sum_2()
-accepts two simple polygons \f$ P\f$ and \f$ Q\f$ and computes their
+`minkowski_sum_2(P, Q)`\endlink accepts two polygons
-Minkowski sum \f$ S = P \oplus Q\f$ using the convolution method.
+\f$ P\f$ and \f$ Q\f$ and computes their Minkowski sum
-\link minkowski_sum_2() `minkowski_sum_2(P, Q)`\endlink defaults to calling the
+\f$ S = P \oplus Q\f$ using the convolution approach.
-function \link minkowski_sum_reduced_convolution_2() `minkowski_sum_reduced_convolution_2(P, Q)`\endlink,
+The call \link minkowski_sum_2() `minkowski_sum_2(P, Q)`\endlink
-which applies the reduced convolution aforementioned.
+defaults to the call \link minkowski_sum_reduced_convolution_2()
-Explicitly call the function \link minkowski_sum_full_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 full convolution method. The types of the operands accepted by
-The types of the operands are instances of the
+the function \link minkowski_sum_full_convolution_2()
-\link Polygon_2 `Polygon_2`\endlink class template. As the input polygons
+`minkowski_sum_full_convolution_2(P, Q)`\endlink are instances of
-may not be convex, their Minkowski sum may not be simply connected and
+the \link Polygon_2 `Polygon_2`\endlink class template. The types of
-contain polygonal holes; see for example \cgalFigureRef{mink_figonecyc}.
+operands accepted by the function \link
-The type of the returned object \f$ S \f$ is therefore an instance of the
+minkowski_sum_reduced_convolution_2()
-\link Polygon_with_holes_2 `Polygon_with_holes_2`\endlink class template.
+`minkowski_sum_reduced_convolution_2(P, Q)`\endlink
-The outer boundary of \f$ S \f$ is a polygon that can be accessed using
+are instances of either the \link Polygon_2 `Polygon_2`\endlink or
-`S.outer_boundary()`, and its polygonal holes are given by the range
+\link Polygon_with_holes_2 `Polygon_with_holes_2`\endlink class templates.
-[`S.holes_begin()`, `S.holes_end()`) (where \f$ S \f$ contains
+Even when the input polygons are restricted to be simple polygons, they
-`S.number_of_holes()` holes in its interior).
+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
+`minkowski_sum_2(P, Q, decompP, decompQ)`, where each of \f$P \f$
-that models the concept `PolygonConvexDecomposition`, which in turn
+and \f$Q \f$ is either a simple polygon or a polygon with holes.
-refines a `Functor` concept variant. Namely, it requires the provision
+If \f$P \f$ is a simple polygon, `decompP` must be an object of
-of a function operator (`operator()`) that accepts a planar polygon and
+a type that models the concept `PolygonConvexDecomposition_2`.
-returns a range of convex polygons that represents its convex decomposition.
+If \f$P \f$ is a polygon with holes, them `decompP` is an object
-If at least one of \f$ P \f$ or \f$ Q \f$ is a polygon with holes,
+of a type that models the concept
-`decomp` is an object of a type that models the concept
 `PolygonWithHolesConvexDecomposition_2`, which refines the concept
-`PolygonConvexDecomposition` and adds a requirement for the provision
+`PolygonConvexDecomposition_2`. The same holds for \f$Q \f$.
-of a function operator (`operator()`) that accepts a planar polygon with
+The two concepts `PolygonConvexDecomposition_2` and
-holes.
+`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