Merge pull request #7608 from kenohori/gsoc2023-polygon_repair-kenohori

Polygon repair

Documentation/doc/Documentation/packages.txt

@@ -31,6 +31,7 @@
 \cgalPackageSection{PartPolygons,Polygons}
 
 \package_listing{Polygon}
+\package_listing{Polygon_repair}
 \package_listing{Boolean_set_operations_2}
 \package_listing{Nef_2}
 \package_listing{Nef_S2}

Documentation/doc/biblio/geom.bib

@@ -152054,3 +152054,13 @@ @inproceedings{tang2009interactive
   year={2009},
   organization={ACM}
 }
+
+@article{ledoux2014triangulation,
+  title={A triangulation-based approach to automatically repair GIS polygons},
+  author={Ledoux, Hugo and Ohori, Ken Arroyo and Meijers, Martijn},
+  journal={Computers \& Geosciences},
+  volume={66},
+  pages={121--131},
+  year={2014},
+  publisher={Elsevier}
+}

Installation/CHANGES.md

@@ -16,6 +16,10 @@ Release date: October 2023
 - **Breaking change**: The usage of `boost::variant` has been replaced by `std::variant`. Packages affected are 2D Arrangements, and the Kernel intersection.
 - **Breaking change**: The file CMake file `UseCGAL.cmake` has been removed from CGAL. Usages of the CMake variables `${CGAL_USE_FILE}` and `${CGAL_LIBRARIES}` must be replaced by a link to the imported target `CGAL::CGAL`, for example: `target_link_library(the_target PRIVATE CGAL::CGAL)`.
 
+### [Polygon Repair](https://doc.cgal.org/6.0/Manual/packages.html#PkgPolygonRepair) (new package)
+
+-   This package provides functions to repair polygons, polygons with holes, and multipolygons with holes
+    using the odd-even heuristic.
 
 #### 2D Arrangements
 

Installation/include/CGAL/license/Polygon_repair.h

@@ -0,0 +1,54 @@
+// Copyright (c) 2016  GeometryFactory SARL (France).
+// All rights reserved.
+//
+// This file is part of CGAL (www.cgal.org)
+//
+// $URL$
+// $Id$
+// SPDX-License-Identifier: LGPL-3.0-or-later OR LicenseRef-Commercial
+//
+// Author(s) : Andreas Fabri
+//
+// Warning: this file is generated, see include/CGAL/license/README.md
+
+#ifndef CGAL_LICENSE_POLYGON_REPAIR_H
+#define CGAL_LICENSE_POLYGON_REPAIR_H
+
+#include <CGAL/config.h>
+#include <CGAL/license.h>
+
+#ifdef CGAL_POLYGON_REPAIR_COMMERCIAL_LICENSE
+
+#  if CGAL_POLYGON_REPAIR_COMMERCIAL_LICENSE < CGAL_RELEASE_DATE
+
+#    if defined(CGAL_LICENSE_WARNING)
+
+       CGAL_pragma_warning("Your commercial license for CGAL does not cover "
+                           "this release of the 2D Polygon Repair package.")
+#    endif
+
+#    ifdef CGAL_LICENSE_ERROR
+#      error "Your commercial license for CGAL does not cover this release \
+              of the 2D Polygon Repair package. \
+              You get this error, as you defined CGAL_LICENSE_ERROR."
+#    endif // CGAL_LICENSE_ERROR
+
+#  endif // CGAL_POLYGON_REPAIR_COMMERCIAL_LICENSE < CGAL_RELEASE_DATE
+
+#else // no CGAL_POLYGON_REPAIR_COMMERCIAL_LICENSE
+
+#  if defined(CGAL_LICENSE_WARNING)
+     CGAL_pragma_warning("\nThe macro CGAL_POLYGON_REPAIR_COMMERCIAL_LICENSE is not defined."
+                          "\nYou use the CGAL 2D Polygon Repair package under "
+                          "the terms of the GPLv3+.")
+#  endif // CGAL_LICENSE_WARNING
+
+#  ifdef CGAL_LICENSE_ERROR
+#    error "The macro CGAL_POLYGON_REPAIR_COMMERCIAL_LICENSE is not defined.\
+            You use the CGAL 2D Polygon Repair package under the terms of \
+            the GPLv3+. You get this error, as you defined CGAL_LICENSE_ERROR."
+#  endif // CGAL_LICENSE_ERROR
+
+#endif // no CGAL_POLYGON_REPAIR_COMMERCIAL_LICENSE
+
+#endif // CGAL_LICENSE_POLYGON_REPAIR_H

Polygon/doc/Polygon/Concepts/MultipolygonWithHoles_2.h

@@ -0,0 +1,101 @@
+/*! \ingroup PkgPolygon2Concepts
+ * \cgalConcept
+ *
+ * \cgalRefines{CopyConstructible,Assignable,DefaultConstructible}
+ *
+ * A model of this concept represents a multipolygon with holes.
+ *
+ * \cgalHasModelsBegin
+ * \cgalHasModels{CGAL::Multipolygon_with_holes_2<Polygon>}
+ * \cgalHasModelsEnd
+ */
+
+class MultipolygonWithHoles_2 {
+public:
+
+/// \name Types
+/// @{
+
+//! the polygon type used to represent each polygon with holes of the multipolygon.
+typedef unspecified_type Polygon_with_holes_2;
+
+/*! a bidirectional iterator over the polygons with holes.
+ * Its value type is `Polygon_with_holes_2`.
+ */
+typedef unspecified_type Polygon_with_holes_iterator;
+
+/*! a bidirectional const iterator over the polygons with holes.
+ * Its value type is `Polygon_with_holes_2`.
+ */
+typedef unspecified_type Polygon_with_holes_const_iterator;
+
+//! range type for iterating over polygons with holes.
+typedef unspecified_type Polygon_with_holes_container;
+
+//! size type
+typedef unsigned int Size;
+
+/// @}
+
+/// \name Creation
+/// @{
+
+/*! constructs a multipolygon using a range of polygons with holes.
+ */
+template <typename InputIterator>
+MultipolygonWithHoles_2(InputIterator begin, InputIterator end);
+
+/// @}
+
+/// \name Predicates
+/// @{
+
+/*! returns the number of polygons with holes.
+ */
+Size number_of_polygons_wih_holes();
+
+/// @}
+
+/// \name Access Functions
+/// @{
+
+/*! returns the begin iterator of the polygons with holes.
+ */
+Polygon_with_holes_iterator polygons_with_holes_begin();
+
+/*! returns the past-the-end iterator of the polygons with holes.
+ */
+  Polygon_with_holes_iterator polygons_with_holes_end();
+
+/*! returns the begin iterator of the polygons with holes.
+ */
+Polygon_with_holes_const_iterator polygons_with_holes_begin() const;
+
+/*! returns the past-the-end iterator of the polygons with holes.
+ */
+Polygon_with_holes_const_iterator polygons_with_holes_end() const;
+
+/*! returns the range of polygons with holes.
+ */
+const Polygon_with_holes_container& polygons_with_holes() const;
+
+/// @}
+
+/// \name Modifiers
+/// @{
+
+/*! adds a given polygon with holes to the multipolygon.
+ */
+void add_polygon_with_holes(const Polygon_with_holes_2& polygon);
+
+/*! erases the specified polygon.
+ */
+void erase_polygon_with_holes(Polygon_with_holes_const_iterator pit);
+
+/*! removes all the polygons with holes.
+ */
+void clear();
+
+/// @}
+
+}; /* end MultipolygonWithHoles_2 */

Polygon/doc/Polygon/PackageDescription.txt

@@ -16,7 +16,13 @@
 \cgalInclude{CGAL/draw_polygon_with_holes_2.h}
 */
 /// \defgroup PkgDrawPolygonWithHoles2 Draw a 2D Polygon with Holes
-/// \ingroup PkgPolygon2Ref
+
+/*!
+  \code
+  #include <CGAL/draw_multipolygon_with_holes_2.h>
+  \endcode
+*/
+/// \defgroup PkgDrawMultipolygonWithHoles2 Draw a 2D Multipolygon with Holes
 
 /*!
 \addtogroup PkgPolygon2Ref
@@ -42,11 +48,13 @@
 \cgalCRPSection{Concepts}
 - `PolygonTraits_2`
 - `GeneralPolygonWithHoles_2`
+- `MultipolygonWithHoles_2`
 
 \cgalCRPSection{Classes}
 - `CGAL::Polygon_2<PolygonTraits_2, Container>`
 - `CGAL::Polygon_with_holes_2<PolygonTraits_2,Container>`
 - `CGAL::General_polygon_with_holes_2<Polygon>`
+- `CGAL::Multipolygon_with_holes_2<PolygonTraits_2,Container>`
 
 \cgalCRPSection{Global Functions}
 - `CGAL::area_2()`
@@ -67,4 +75,7 @@
 \cgalCRPSection{Draw a Polygon_with_holes_2}
 - \link  PkgDrawPolygonWithHoles2 CGAL::draw<PH>() \endlink
 
+\cgalCRPSection{Draw a Multipolygon_with_holes_2}
+- \link  PkgDrawMultipolygonWithHoles2 CGAL::draw<MPH>() \endlink
+
 */

Polygon/doc/Polygon/Polygon.txt

@@ -37,6 +37,19 @@ points, but little more. Especially, computed values are not cached.
 That is, when the `Polygon_2::is_simple()` member function is called
 twice or more, the result is computed each time anew.
 
+\section secPolygonWithHole Polygons with Holes and Multipolygons with Holes
+
+This package also provides classes to represent polygons with holes and multipolygons with holes.
+
+For polygons with holes, these are `Polygon_with_holes_2` and `General_polygon_with_holes_2`. They can store a polygon that represents
+the outer boundary and a sequence of polygons that represent the holes.
+
+For multipolygons with holes, there is `Multipolygon_with_holes_2`.
+It stores a sequence of polygons with holes.
+
+These classes do not add any semantic requirements on the simplicity
+or orientation of their boundary polygons.
+
 \section secPolygonExamples Examples
 
 \subsection subsecPolygon The Polygon Class
@@ -46,6 +59,13 @@ some member functions.
 
 \cgalExample{Polygon/Polygon.cpp}
 
+\subsection SubsectionPolygonRepair_Multipolygon The Multipolygon with Holes Class
+
+The following example shows the creation of a multipolygon with holes and the traversal
+of the polygons in it.
+
+\cgalExample{Polygon/multipolygon.cpp}
+
 \cgalFigureBegin{polygon2_algo,pgn_algos.png}
 A polygon and some points
 \cgalFigureEnd
@@ -82,7 +102,8 @@ vertices. It additionally provides a member function `Polygon_2::vertices()` tha
 
 \subsection subsecPolygonDraw Draw a Polygon
 
-A polygon can be visualized by calling the \link  PkgDrawPolygon2 CGAL::draw<P>() \endlink function as shown in the following example. This function opens a new window showing the given polygon. A call to this function is blocking, that is the program continues as soon as the user closes the window (a version exists for polygon with holes, cf. \link PkgDrawPolygonWithHoles2 CGAL::draw<PH>() \endlink).
+A polygon can be visualized by calling the \link  PkgDrawPolygon2 CGAL::draw<P>() \endlink function as shown in the following example. This function opens a new window showing the given polygon. A call to this function is blocking, that is the program continues as soon as the user closes the window. Versions for polygons with holes and multipolygons with holes also exist, cf. \link PkgDrawPolygonWithHoles2 CGAL::draw<PH>() \endlink and \link PkgDrawMultipolygonWithHoles2
+CGAL::draw<MPH>() \endlink.
 
 \cgalExample{Polygon/draw_polygon.cpp}
 
@@ -94,15 +115,4 @@ Result of the run of the draw_polygon program. A window shows the polygon and al
 \cgalFigureEnd
 
 */
-
-\section secPolygonWithHole Polygons with Holes
-
-This package also provides two classes to represent polygons with holes,
-namely `Polygon_with_holes_2` and `General_polygon_with_holes_2`. They
-can store a polygon that represents the outer boundary and a sequence
-of polygons that represent the holes.
-
-These classes do not add any semantic requirements on the simplicity
-or orientation of their boundary polygons.
-
 }

Polygon/doc/Polygon/examples.txt

@@ -7,4 +7,6 @@
 \example Stream_support/Polygon_WKT.cpp
 \example Polygon/draw_polygon.cpp
 \example Polygon/draw_polygon_with_holes.cpp
+\example Polygon/multipolygon.cpp
+\example Polygon/draw_multipolygon_with_holes.cpp
 */

Polygon/examples/Polygon/CMakeLists.txt

@@ -18,4 +18,5 @@ endforeach()
 if(CGAL_Qt6_FOUND)
   target_link_libraries(draw_polygon PUBLIC CGAL::CGAL_Basic_viewer)
   target_link_libraries(draw_polygon_with_holes PUBLIC CGAL::CGAL_Basic_viewer)
+  target_link_libraries(draw_multipolygon_with_holes PUBLIC CGAL::CGAL_Basic_viewer)
 endif()

Polygon/examples/Polygon/draw_multipolygon_with_holes.cpp

@@ -0,0 +1,20 @@
+#include <iostream>
+#include <sstream>
+
+#include <CGAL/Exact_predicates_inexact_constructions_kernel.h>
+#include <CGAL/Multipolygon_with_holes_2.h>
+#include <CGAL/draw_multipolygon_with_holes_2.h>
+#include <CGAL/IO/WKT.h>
+
+using Kernel = CGAL::Exact_predicates_inexact_constructions_kernel;
+using Multipolygon_with_holes_2 = CGAL::Multipolygon_with_holes_2<Kernel>;
+
+int main() {
+  std::string wkt = "MULTIPOLYGON(((0 0,1 0,1 1,0 1,0 0),(0.1 0.1,0.1 0.9,0.9 0.9,0.9 0.1,0.1 0.1)),((0.2 0.2,0.8 0.2,0.8 0.8,0.2 0.8,0.2 0.2),(0.3 0.3,0.3 0.7,0.7 0.7,0.7 0.3,0.3 0.3)))";
+  std::istringstream iss(wkt);
+  Multipolygon_with_holes_2 mp;
+  CGAL::IO::read_multi_polygon_WKT(iss, mp);
+  CGAL::draw(mp);
+
+  return 0;
+}

Polygon/examples/Polygon/multipolygon.cpp

@@ -0,0 +1,31 @@
+#include <CGAL/Exact_predicates_inexact_constructions_kernel.h>
+#include <CGAL/Multipolygon_with_holes_2.h>
+
+using Kernel = CGAL::Exact_predicates_inexact_constructions_kernel;
+using Point_2 = Kernel::Point_2;
+using Polygon_2 = CGAL::Polygon_2<Kernel>;
+using Polygon_with_holes_2 = CGAL::Polygon_with_holes_2<Kernel>;
+using Multipolygon_with_holes_2 = CGAL::Multipolygon_with_holes_2<Kernel>;
+
+int main() {
+
+  Point_2 p1_outer[] = {Point_2(0,0), Point_2(1,0), Point_2(1,1), Point_2(0,1)};
+  Point_2 p1_inner[] = {Point_2(0.2,0.2), Point_2(0.8,0.2), Point_2(0.8,0.8), Point_2(0.2,0.8)};
+
+  Polygon_with_holes_2 p1(Polygon_2(p1_outer, p1_outer+4));
+  Polygon_2 h(p1_inner, p1_inner+4);
+  p1.add_hole(h);
+
+  Point_2 p2_outer[] = {Point_2(0.4,0.4), Point_2(0.6,0.4), Point_2(0.6,0.6), Point_2(0.4,0.6)};
+  Polygon_with_holes_2 p2(Polygon_2(p2_outer, p2_outer+4));
+
+  Multipolygon_with_holes_2 mp;
+  mp.add_polygon_with_holes(p1);
+  mp.add_polygon_with_holes(p2);
+
+  for (auto const& p: mp.polygons_with_holes()) {
+    std::cout << p << std::endl;
+  }
+
+  return 0;
+}

Polygon/include/CGAL/General_polygon_with_holes_2.h

@@ -28,8 +28,8 @@ namespace CGAL {
  *
  * The class `General_polygon_with_holes_2` models the concept
  * `GeneralPolygonWithHoles_2`. It represents a general polygon with holes.
- * It is parameterized with a type `Polygon` used to define the exposed
- * type `Polygon_2`. This type represents the outer boundary of the general
+ * It is parameterized with a type `Polygon_` used to define the exposed
+ * type `%Polygon_2`. This type represents the outer boundary of the general
  * polygon and each hole.
  *
  * \tparam Polygon_ must have input and output operators.