Merge pull request #27369 from SaraKuhnert:minEnclosingPolygon

imgproc: add minEnclosingConvexPolygon #27369

### Pull Request Readiness Checklist

- [x] I agree to contribute to the project under Apache 2 License.
- [x] To the best of my knowledge, the proposed patch is not based on a code under GPL or another license that is incompatible with OpenCV
- [ ] The PR is proposed to the proper branch
- [ ] There is a reference to the original bug report and related work
- [ ] There is accuracy test, performance test and test data in opencv_extra repository, if applicable
      Patch to opencv_extra has the same branch name.
- [ ] The feature is well documented and sample code can be built with the project CMake

doc/opencv.bib

@@ -1552,3 +1552,12 @@
   year = {2014},
   url = {http://www.marcozuliani.com/docs/RANSAC4Dummies.pdf}
 }
+@article{Aggarwal1985,
+  author = {Aggarwal, A. and Chang, J. and Yap, Chee K.},
+  title = {Minimum area circumscribing Polygons},
+  year = {1985},
+  pages = {112--117},
+  journal = {The Visual Computer},
+  volume = {7},
+  url = {https://doi.org/10.1007/BF01898354}
+}

modules/imgproc/include/opencv2/imgproc.hpp

@@ -4192,7 +4192,8 @@ The function finds the four vertices of a rotated rectangle. The four vertices a
 in clockwise order starting from the point with greatest \f$y\f$. If two points have the
 same \f$y\f$ coordinate the rightmost is the starting point. This function is useful to draw the
 rectangle. In C++, instead of using this function, you can directly use RotatedRect::points method. Please
-visit the @ref tutorial_bounding_rotated_ellipses "tutorial on Creating Bounding rotated boxes and ellipses for contours" for more information.
+visit the @ref tutorial_bounding_rotated_ellipses "tutorial on Creating Bounding rotated boxes and ellipses
+for contours" for more information.
 
 @param box The input rotated rectangle. It may be the output of @ref minAreaRect.
 @param points The output array of four vertices of rectangles.
@@ -4234,6 +4235,30 @@ of the OutputArray must be CV_32F.
  */
 CV_EXPORTS_W double minEnclosingTriangle( InputArray points, CV_OUT OutputArray triangle );
 
+
+/**
+@brief Finds a convex polygon of minimum area enclosing a 2D point set and returns its area.
+
+This function takes a given set of 2D points and finds the enclosing polygon with k vertices and minimal
+area. It takes the set of points and the parameter k as input and returns the area of the minimal
+enclosing polygon.
+
+The Implementation is based on a paper by Aggarwal, Chang and Yap @cite Aggarwal1985. They
+provide a \f$\theta(n²log(n)log(k))\f$ algorighm for finding the minimal convex polygon with k
+vertices enclosing a 2D convex polygon with n vertices (k < n). Since the #minEnclosingConvexPolygon
+function takes a 2D point set as input, an additional preprocessing step of computing the convex hull
+of the 2D point set is required. The complexity of the #convexHull function is \f$O(n log(n))\f$ which
+is lower than \f$\theta(n²log(n)log(k))\f$. Thus the overall complexity of the function is
+\f$O(n²log(n)log(k))\f$.
+
+@param points   Input vector of 2D points, stored in std::vector\<\> or Mat
+@param polygon  Output vector of 2D points defining the vertices of the enclosing polygon
+@param k        Number of vertices of the output polygon
+ */
+
+CV_EXPORTS_W double minEnclosingConvexPolygon ( InputArray points, OutputArray polygon, int k );
+
+
 /** @brief Compares two shapes.
 
 The function compares two shapes. All three implemented methods use the Hu invariants (see #HuMoments)

modules/imgproc/test/test_convhull.cpp

@@ -1069,5 +1069,106 @@ TEST(minEnclosingCircle, three_points)
     EXPECT_LE(delta, 1.f);
 }
 
+
+//============================ minEnclosingPolygon tests ============================
+
+TEST(minEnclosingPolygon, input_errors)
+{
+    std::vector<cv::Point2f> kgon;
+    std::vector<cv::Point2f> ngon {{0.0, 0.0}, {1.0, 1.0}};
+
+    EXPECT_THROW(minEnclosingConvexPolygon(ngon, kgon, 3), cv::Exception);
+
+    ngon = {{0.0, 0.0}, {0.0, 1.0}, {1.0, 0.0}, {1.0, 1.0}};
+    EXPECT_THROW(minEnclosingConvexPolygon(ngon, kgon, 2), cv::Exception);
+    EXPECT_THROW(minEnclosingConvexPolygon(ngon, kgon, 5), cv::Exception);
+}
+
+TEST(minEnclosingPolygon, input_corner_cases)
+{
+    double area = -1.0;
+    std::vector<cv::Point2f> kgon;
+    std::vector<cv::Point2f> ngon = {{0.0, 0.0}, {0.0, 0.0}, {1.0, 1.0}, {1.0, 1.0}};
+
+    EXPECT_NO_THROW(area = minEnclosingConvexPolygon(ngon, kgon, 3))
+    << "unexpected exception: not enough different points in input ngon (double points)";
+    EXPECT_LE(area, 0.);
+    EXPECT_TRUE(kgon.empty());
+
+    ngon = {{0.0, 0.0}, {1.0, 1.0}, {2.0, 2.0}, {3.0, 3.0}, {4.0, 4.0}};
+    EXPECT_NO_THROW(area = minEnclosingConvexPolygon(ngon, kgon, 3))
+    << "unexpected exception: all points on line";
+    EXPECT_LE(area, 0.);
+    EXPECT_TRUE(kgon.empty());
+}
+
+TEST(minEnclosingPolygon, unit_circle)
+{
+    const int n = 64;
+    const int k = 7;
+    double area = -1.0;
+    std::vector<cv::Point2f> kgon;
+    std::vector<cv::Point2f> ngon(n);
+
+    for(int i = 0; i < n; i++)
+    {
+        ngon[i] = { cosf(float(i * 2.f * M_PI / n)), sinf(float(i * 2.f * M_PI / n)) };
+    }
+
+    EXPECT_NO_THROW(area = minEnclosingConvexPolygon(ngon, kgon, k));
+    EXPECT_GT(area, cv::contourArea(ngon));
+    EXPECT_EQ((int)kgon.size(), k);
+}
+
+TEST(minEnclosingPolygon, random_points)
+{
+    const int n = 100;
+    const int k = 7;
+
+    double area = -1.0;
+    std::vector<cv::Point2f> kgon;
+    std::vector<cv::Point2f> ngon(n);
+    std::vector<cv::Point2f> ngonHull;
+
+    cv::randu(ngon, 1, 101);
+    cv::convexHull(ngon, ngonHull, true);
+
+    EXPECT_NO_THROW(area = minEnclosingConvexPolygon(ngon, kgon, k));
+    EXPECT_GT(area, cv::contourArea(ngonHull));
+    EXPECT_EQ(kgon.size(), (size_t)k);
+}
+
+TEST(minEnclosingPolygon, pentagon)
+{
+    double area;
+    std::vector<cv::Point2f> kgon;
+    std::vector<cv::Point2f> expectedKgon;
+    std::vector<cv::Point2f> ngon;
+
+    ngon = {{1, 0}, {0, 8}, {4, 12}, {8, 8}, {7, 0}};
+    EXPECT_NO_THROW({
+        area = minEnclosingConvexPolygon(ngon, kgon, 4);
+    });
+
+    expectedKgon = {{1, 0}, {-0.5, 12}, {8.5, 12}, {7, 0}};
+    EXPECT_EQ(area, cv::contourArea(expectedKgon));
+    ASSERT_EQ((int)kgon.size(), 4);
+
+    for (size_t i = 0; i < 4; i++)
+    {
+        bool match = false;
+        for (size_t j = 0; j < 4; j++)
+        {
+            if(expectedKgon[i].x == kgon[j].x && expectedKgon[i].y == kgon[j].y)
+            {
+                match = true;
+                break;
+            }
+        }
+        EXPECT_EQ(match, true);
+    }
+}
+
 }} // namespace
+
 /* End of file. */