extend docs and tests for is_point_in_polygon_2d()

Author: mozman

src/ezdxf/math/construct2d.py

@@ -249,6 +249,9 @@ def is_point_in_polygon_2d(
     """Test if `point` is inside `polygon`. Returns ``-1`` (for outside) if the
     polygon is degenerated, no exception will be raised.
 
+    Supports convex and concave polygons with clockwise or counter-clockwise oriented
+    polygon vertices.
+
     Args:
         point: 2D point to test as :class:`Vec2`
         polygon: sequence of 2D points as :class:`Vec2`
@@ -260,6 +263,7 @@ def is_point_in_polygon_2d(
     """
     # Source: http://www.faqs.org/faqs/graphics/algorithms-faq/
     # Subject 2.03: How do I find if a point lies within a polygon?
+    # TODO: Cython implementation
     if not polygon:  # empty polygon
         return -1
 
@@ -281,17 +285,17 @@ def is_point_in_polygon_2d(
             if (c <= y <= d) and math.fabs(
                 (y2 - y1) * x - (x2 - x1) * y + (x2 * y1 - y2 * x1)
             ) <= abs_tol:
-                return 0
+                return 0  # on boundary line
         if ((y1 <= y < y2) or (y2 <= y < y1)) and (
             x < (x2 - x1) * (y - y1) / (y2 - y1) + x1
         ):
             inside = not inside
         x1 = x2
         y1 = y2
     if inside:
-        return 1
+        return 1  # inside polygon
     else:
-        return -1
+        return -1  # outside polygon
 
 
 def circle_radius_3p(a: Vec3, b: Vec3, c: Vec3) -> float:
@@ -355,16 +359,16 @@ def has_matrix_2d_stretching(m: Matrix44) -> bool:
 def is_convex_polygon_2d(polygon: list[Vec2], *, strict=False, epsilon=1e-6) -> bool:
     """Returns ``True`` if the 2D `polygon` is convex.
 
-    This function works with
-    open and closed polygons and clockwise or counter-clockwise vertex
-    orientation.
-    Coincident vertices will always be skipped and if argument `strict`
-    is ``True``, polygons with collinear vertices are not considered as
-    convex.
+    This function supports open and closed polygons with clockwise or counter-clockwise 
+    vertex orientation.
+
+    Coincident vertices will always be skipped and if argument `strict` is ``True``, 
+    polygons with collinear vertices are not considered as convex.
 
     This solution works only for simple non-self-intersecting polygons!
 
     """
+    # TODO: Cython implementation
     if len(polygon) < 3:
         return False
 
@@ -378,15 +382,15 @@ def is_convex_polygon_2d(polygon: list[Vec2], *, strict=False, epsilon=1e-6) ->
 
         det = (prev - vertex).det(prev_prev - prev)
         if abs(det) >= epsilon:
-            current_sign = -1 if det < 0.0 else +1 
+            current_sign = -1 if det < 0.0 else +1
             if not global_sign:
                 global_sign = current_sign
             # do all determinants have the same sign?
             if global_sign != current_sign:
-                return  False
+                return False
         elif strict:  # collinear vertices
-            return False       
-            
+            return False
+
         prev_prev = prev
         prev = vertex
     return bool(global_sign)

…test_06_math/test_613_point_in_poygon.py …_math/test_613_is_point_in_polygon_2d.pytests/test_06_math/test_613_point_in_poygon.py renamed to tests/test_06_math/test_613_is_point_in_polygon_2d.py tests/test_06_math/test_613_point_in_poygon.py renamed to tests/test_06_math/test_613_is_point_in_polygon_2d.py

@@ -1,31 +1,31 @@
-# Copyright (c) 2020, Manfred Moitzi
+# Copyright (c) 2020-2024, Manfred Moitzi
 # License: MIT License
 import pytest
-from ezdxf.math import is_point_in_polygon_2d, Vec2
+from ezdxf.math import is_point_in_polygon_2d, Vec2, is_convex_polygon_2d
 
 
-def test_inside_horiz_box():
+def test_inside_horizontal_box():
     square = Vec2.list([(0, 0), (1, 0), (1, 1), (0, 1)])
     assert is_point_in_polygon_2d(Vec2(0.5, 0.5), square) == 1
 
 
-def test_outside_horiz_box():
+def test_outside_horizontal_box():
     square = Vec2.list([(0, 0), (1, 0), (1, 1), (0, 1)])
     assert is_point_in_polygon_2d(Vec2(-0.5, 0.5), square) == -1
     assert is_point_in_polygon_2d(Vec2(1.5, 0.5), square) == -1
     assert is_point_in_polygon_2d(Vec2(0.5, -0.5), square) == -1
     assert is_point_in_polygon_2d(Vec2(0.5, 1.5), square) == -1
 
 
-def test_colinear_outside_horiz_box():
+def test_colinear_outside_horizontal_box():
     square = Vec2.list([(0, 0), (1, 0), (1, 1), (0, 1)])
     assert is_point_in_polygon_2d(Vec2(1.5, 0), square) == -1
     assert is_point_in_polygon_2d(Vec2(-0.5, 0), square) == -1
     assert is_point_in_polygon_2d(Vec2(0, 1.5), square) == -1
     assert is_point_in_polygon_2d(Vec2(0, -0.5), square) == -1
 
 
-def test_corners_horiz_box():
+def test_corners_horizontal_box():
     square = Vec2.list([(0, 0), (1, 0), (1, 1), (0, 1)])
     assert is_point_in_polygon_2d(Vec2(0, 0), square) == 0
     assert is_point_in_polygon_2d(Vec2(0, 1), square) == 0
@@ -62,5 +62,100 @@ def test_borders_slanted_box_stable():
     assert is_point_in_polygon_2d(Vec2(-0.5, 0.5), square) == 0
 
 
+# Test concave polygon:
+#
+#   0123456
+# 8 .......
+# 7 .7---6.
+# 6 .|...|.
+# 5 .|.4-5.
+# 4 .|.|...
+# 3 .|.3-2.
+# 2 .|...|.
+# 1 .0---1.
+# 0 .......
+#   0123456
+
+SHAPE_C_CCW = Vec2.list(
+    # 0       1       2       3       4       5       6       7
+    [(1, 1), (5, 1), (5, 3), (3, 3), (3, 5), (5, 5), (5, 7), (1, 7)]
+)
+SHAPE_C_CW = list(reversed(SHAPE_C_CCW))
+
+#   0123456
+# 8 .......
+# 7 .+---+.
+# 6 .|678|.
+# 5 .|5+-+.
+# 4 .|4|...
+# 3 .|3+-+.
+# 2 .|012|.
+# 1 .+---+.
+# 0 .......
+#   0123456
+
+POINTS_INSIDE = Vec2.list(
+    # 0       1       2       3       4       5       6       7       8
+    [(2, 2), (3, 2), (4, 2), (2, 3), (2, 4), (2, 5), (2, 6), (3, 6), (4, 6)]
+)
+
+#   0123456
+# 8 b.c.d.e
+# 7 .+---+.
+# 6 9|...|a
+# 5 .|.+-+.
+# 4 6|.|7.8
+# 3 .|.+-+.
+# 2 4|...|5
+# 1 .+---+.
+# 0 0.1.2.3
+#   0123456
+
+POINTS_OUTSIDE = Vec2.list(
+    [
+        (0, 0),  # 0
+        (2, 0),  # 1
+        (4, 0),  # 2
+        (6, 0),  # 3
+        (0, 2),  # 4
+        (6, 2),  # 5
+        (0, 4),  # 6
+        (4, 4),  # 7
+        (6, 2),  # 8
+        (0, 6),  # 9
+        (6, 6),  # a
+        (0, 8),  # b
+        (2, 8),  # c
+        (4, 8),  # d
+        (6, 8),  # e
+    ]
+)
+
+
+def test_shape_c_is_not_convex():
+    assert is_convex_polygon_2d(SHAPE_C_CCW) is False
+    assert is_convex_polygon_2d(SHAPE_C_CW) is False
+
+
+@pytest.mark.parametrize("point", POINTS_INSIDE)
+def test_is_inside_ccw_polygon(point: Vec2):
+    assert is_point_in_polygon_2d(point, SHAPE_C_CCW) >= 0
+
+
+@pytest.mark.parametrize("point", POINTS_OUTSIDE)
+def test_is_outside_ccw_polygon(point: Vec2):
+    assert is_point_in_polygon_2d(point, SHAPE_C_CCW) == -1
+
+
+@pytest.mark.parametrize("point", POINTS_INSIDE)
+def test_is_inside_cw_polygon(point: Vec2):
+    assert is_point_in_polygon_2d(point, SHAPE_C_CW) >= 0
+
+
+@pytest.mark.parametrize("point", POINTS_OUTSIDE)
+def test_is_outside_cw_polygon(point: Vec2):
+    assert is_point_in_polygon_2d(point, SHAPE_C_CW) == -1
+
+
 if __name__ == "__main__":
     pytest.main([__file__])