Documentation additions

Minkowski_sum_2/doc/Minkowski_sum_2/CGAL/minkowski_sum_2.h

@@ -3,21 +3,21 @@ namespace CGAL {
 /*!
 \ingroup PkgMinkowskiSum2
 
-Computes the Minkowski sum \f$ P \oplus Q\f$ of the two given polygons.
+Computes the Minkowski sum \f$ P \oplus Q\f$ of two given polygons
-This method defaults to the reduced convolution method, see below.
+(which may have holes). `PolygonType1` and `PolygonType2` can be any combination of:
-Note that as the input polygons may not be convex, their Minkowski
-sum may not be a simple polygon. The result is therefore represented
-as a polygon with holes.
 
-\pre Both `P` and `Q` are simple, counterclockwise-oriented polygons.
+- `Polygon_2`
+- `Polygon_with_holes_2`
+
+This method defaults to the reduced convolution method, see below.
 
 \sa `CGAL::minkowski_sum_reduced_convolution_2()`
 \sa `CGAL::minkowski_sum_full_convolution_2()`
  */
 template<class Kernel, class Container>
 Polygon_with_holes_2<Kernel,Container>
-minkowski_sum_2 (const Polygon_2<Kernel,Container>& P,
+minkowski_sum_2 (const PolygonType1<Kernel,Container>& P,
-                 const Polygon_2<Kernel,Container>& Q);
+                 const PolygonType2<Kernel,Container>& Q);
 
 /*!
 \ingroup PkgMinkowskiSum2
@@ -29,17 +29,17 @@ the Minkowsi sum. This method works very efficiently, regardless of whether `P`
 and `Q` are convex or non-convex. It is usually faster than the full
 convolution method, except in degenerate cases where the output polygon has
 many holes.
-Note that as the input polygons may not be convex, their Minkowski
-sum may not be a simple polygon. The result is therefore represented
-as a polygon with holes.
 
-\pre Both `P` and `Q` are simple, counterclockwise-oriented polygons.
+`PolygonType1` and `PolygonType2` can be any combination of:
+
+- `Polygon_2`
+- `Polygon_with_holes_2`
 */
 
 template<class Kernel, class Container>
 Polygon_with_holes_2<Kernel,Container>
-minkowski_sum_reduced_convolution_2 (const Polygon_2<Kernel,Container>& P,
+minkowski_sum_reduced_convolution_2 (const PolygonType1<Kernel,Container>& P,
-                                     const Polygon_2<Kernel,Container>& Q);
+                                     const PolygonType2<Kernel,Container>& Q);
 
 /*!
 \ingroup PkgMinkowskiSum2
@@ -49,16 +49,16 @@ The function computes the (full) convolution cycles of the two polygons and
 extract the regions having positive winding number with respect to these
 cycles. This method work very efficiently, regardless of whether `P`
 and `Q` are convex or non-convex.
-Note that as the input polygons may not be convex, their Minkowski
-sum may not be a simple polygon. The result is therefore represented
-as a polygon with holes.
 
-\pre Both `P` and `Q` are simple polygons.
+`PolygonType1` and `PolygonType2` can be any combination of:
+
+- `Polygon_2`
+- `Polygon_with_holes_2`
 */
 template<class Kernel, class Container>
 Polygon_with_holes_2<Kernel,Container>
-minkowski_sum_full_convolution_2(const Polygon_2<Kernel,Container>& P,
+minkowski_sum_full_convolution_2(const PolygonType1<Kernel,Container>& P,
-                                 const Polygon_2<Kernel,Container>& Q,
+                                 const PolygonType2<Kernel,Container>& Q,
                                  const Kernel& kernel = Kernel());
 
 /*!
@@ -72,62 +72,17 @@ decomposes them into convex sub-polygons \f$ P_1, \ldots, P_k\f$ and
 The decomposition is performed using the given decomposition method
 `decomp`, which must be an instance of a class template that models
 the concept `PolygonConvexDecomposition_2`.
-Note that as the input polygons may not be convex, their Minkowski
+
-sum may not be a simple polygon. The result is therefore represented
+`PolygonType1` and `PolygonType2` can be any combination of:
-as a polygon with holes.
+
-\pre Both `P` and `Q` are simple polygons.
+- `Polygon_2`
+- `Polygon_with_holes_2`
 */
 template<class Kernel, class Container, class PolygonConvexDecomposition_2>
 Polygon_with_holes_2<Kernel,Container>
-minkowski_sum_2 (const Polygon_2<Kernel,Container>& P,
+minkowski_sum_2 (const PolygonType1<Kernel,Container>& P,
-                 const Polygon_2<Kernel,Container>& Q,
+                 const PolygonType2<Kernel,Container>& Q,
                  const PolygonConvexDecomposition_2& decomp,
                  const Gps_segment_traits_2& traits = Gps_segment_traits_2<Kernel,Container,Arr_segment_traits>());
 
-/*!
-\ingroup PkgMinkowskiSum2
-
-Computes the Minkowski sum \f$ P \oplus Q\f$ of polygon \f$ P\f$ and the
-polygon with holes \f$ Q\f$. If the input polygons `P` and `Q` are not
-convex, the function decomposes them into convex sub-polygons
-\f$ P_1, \ldots, P_k\f$ and \f$ Q_1, \ldots, Q_{\ell}\f$ and computes
-the union of pairwise sub-sums (namely \f$ \bigcup_{i,j}{(P_i \oplus Q_j)}\f$).
-The decomposition is performed using the given decomposition method
-`decomp`, which must be an instance of a class template that models the
-concept `PolygonWithHolesConvexDecomposition_2`.
-Note that as the input polygons may not be convex, their Minkowski
-sum may not be a simple polygon. The result is therefore represented
-as a polygon with holes.
-*/
-template<class Kernel, class Container,
-         class PolygonWithHolesConvexDecomposition_2>
-Polygon_with_holes_2<Kernel,Container>
-minkowski_sum_2 (const Polygon_2<Kernel,Container>& P,
-                 const Polygon_with_holes_2<Kernel,Container>& Q,
-                 const PolygonWithHolesConvexDecomposition_2& decomp,
-                 const Gps_segment_traits_2& traits = Gps_segment_traits_2<Kernel,Container,Arr_segment_traits>());
-
-/*!
-\ingroup PkgMinkowskiSum2
-
-Computes the Minkowski sum \f$ P \oplus Q\f$ of the two given polygons with
-holes. If the input polygons `P` and `Q` are not convex, the function
-decomposes them into convex sub-polygons \f$ P_1, \ldots, P_k\f$ and
-\f$ Q_1, \ldots, Q_{\ell}\f$ and computes the union of pairwise sub-sums
-(namely \f$ \bigcup_{i,j}{(P_i \oplus Q_j)}\f$).
-The decomposition is performed using the given decomposition method
-`decomp`, which must be an instance of a class template that models the
-concept `PolygonWithHolesConvexDecomposition_2`.
-Note that as the input polygons may not be convex, their Minkowski
-sum may not be a simple polygon. The result is therefore represented
-as a polygon with holes.
-*/
-template<class Kernel, class Container,
-         class PolygonWithHolesConvexDecomposition_2>
-Polygon_with_holes_2<Kernel,Container>
-minkowski_sum_2 (const Polygon_with_holes_2<Kernel,Container>& P,
-                 const Polygon_with_holes_2<Kernel,Container>& Q,
-                 const PolygonWithHolesConvexDecomposition_2& decomp,
-                 const Gps_segment_traits_2& traits = Gps_segment_traits_2<Kernel,Container,Arr_segment_traits>());
-
 } /* namespace CGAL */

Minkowski_sum_2/include/CGAL/Minkowski_sum_2/Hole_filter_2.h

@@ -6,6 +6,11 @@
 
 namespace CGAL {
 
+/*! \class
+ * This class applies filter to a polygon with holes,
+ * by removing all of its holes that cannot possibly contribute
+ * to the Minkowski sum boundary.
+ */
 template <class Kernel_, class Container_>
 class Hole_filter_2
 {

Minkowski_sum_2/include/CGAL/minkowski_sum_2.h

@@ -185,6 +185,49 @@ minkowski_sum_2(const Polygon_2<Kernel_, Container_>& pgn1,
   return minkowski_sum_reduced_convolution_2(pgn1, pgn2);
 }
 
+/*!
+ * Compute the Minkowski sum of two polygons with holes using the convolution
+ * method. This function defaults to calling the reduced convolution method,
+ * as it is more efficient in most cases.
+ * Note that the result may not be a simple polygon. The result is therefore
+ * represented as a polygon with holes.
+ * \param pgn1 (in) The first polygon with holes.
+ * \param pgn2 (in) The second polygon with holes.
+ * \return The resulting polygon with holes, representing the sum.
+ *
+ * \sa `CGAL::minkowski_sum_reduced_convolution_2()`
+ * \sa `CGAL::minkowski_sum_full_convolution_2()`
+ */
+template <typename Kernel_, typename Container_>
+Polygon_with_holes_2<Kernel_, Container_>
+minkowski_sum_2(const Polygon_with_holes_2<Kernel_, Container_>& pgn1,
+                const Polygon_with_holes_2<Kernel_, Container_>& pgn2)
+{
+  return minkowski_sum_reduced_convolution_2(pgn1, pgn2);
+}
+
+/*!
+ * Compute the Minkowski sum of a simple polygons and a polygon-with-holes
+ * using the convolution method. This function defaults to calling the reduced
+ * convolution method, as it is more efficient in most cases.
+ * Note that the result may not be a simple polygon. The result is therefore
+ * represented as a polygon with holes.
+ * \param pgn1 (in) The polygon.
+ * \param pgn2 (in) The polygon with holes.
+ * \return The resulting polygon with holes, representing the sum.
+ *
+ * \sa `CGAL::minkowski_sum_reduced_convolution_2()`
+ * \sa `CGAL::minkowski_sum_full_convolution_2()`
+ */
+template <typename Kernel_, typename Container_>
+Polygon_with_holes_2<Kernel_, Container_>
+minkowski_sum_2(const Polygon_2<Kernel_, Container_>& pgn1,
+                const Polygon_with_holes_2<Kernel_, Container_>& pgn2)
+{
+  Polygon_with_holes_2<Kernel_, Container_> pgnwh1(pgn1);
+  return minkowski_sum_reduced_convolution_2(pgnwh1, pgn2);
+}
+
 /*!
  * Compute the Minkowski sum of two simple polygons by decomposing each
  * polygon to convex sub-polygons and computing the union of the pairwise