1+ """
2+ polygon2
3+
4+ Author: Timothy Moore
5+
6+ Defines a class for simple 2-d convex polygons. Contains
7+ SAT-intersection.
8+ """
9+
10+ class Polygon2 (object ):
11+ """
12+ Define a concave polygon defined by a list of points such that each
13+ adjacent pair of points form a line, the line from the last point to
14+ the first point form a line, and the lines formed from the smaller
15+ index to the larger index will walk clockwise around the polygon.
16+
17+ .. note::
18+
19+ Polygons should be used as if they were completely immutable to
20+ ensure correctness. All attributes of Polygon2 can be reconstructed
21+ from the points array, and thus cannot be changed on their own and
22+ must be recalculated if there were any changes to `points`.
23+
24+ .. note::
25+
26+ To reduce unnecessary recalculations, Polygons notably do not have
27+ an easily modifiable position. However, where relevant, the class
28+ methods will accept offsets to the polygons. In all of these cases
29+ the offset may be None for a minor performance improvement.
30+
31+ .. note::
32+
33+ Unfortunately, operations on rotated polygons require recalculating
34+ the polygon based on its rotated points. This should be avoided
35+ unless necessary through the use of Axis-Aligned Bounding Boxes
36+ and similar tools.
37+
38+ :ivar points: the ordered set of points on this polygon
39+ :vartype points: list of :class:`pygorithm.geometry.vector2.Vector2`
40+
41+ :ivar lines: the ordered set of lines on this polygon
42+ :vartype lines: list of :class:`pygorithm.geometry.line2.Line2`
43+
44+ :ivar normals: the ordered set of normals on this polygon
45+ :vartype normals: list of :class:`pygorithm.geometry.vector2.Vector2`
46+
47+ :ivar center: the center of this polygon when unshifted.
48+ :vartype center: :class:`pygorithm.geometry.vector2.Vector2`
49+ """
50+
51+ def __init__ (self , points , suppress_errors = False ):
52+ """
53+ Create a new polygon from the set of points
54+
55+ .. caution::
56+
57+ A significant amount of calculation is performed when creating
58+ a polygon. These should be reused whenever possible. This cost
59+ can be alleviated somewhat by suppressing certain expensive
60+ sanity checks, but the polygon can behave very unexpectedly
61+ (and potentially without explicit errors) if the errors are
62+ suppressed.
63+
64+ :param points: the ordered set of points on this polygon
65+ :type points: list of :class:`pygorithm.geometry.vector2.Vector2`
66+
67+ :param suppress_errors: True to not do somewhat expensive sanity checks
68+ :type suppress_errors: bool
69+
70+ :raises ValueError: if there are any repeated points (not suppressable)
71+ :raises ValueError: if there are less than 3 points (not suppressable)
72+ :raises ValueError: if the polygon is not convex (suppressable)
73+ :raises ValueError: if the points are not clockwise oriented (suppressable)
74+ """
75+ pass
76+
77+ @property
78+ def area (self ):
79+ """
80+ Get the area of this polygon. Lazily initialized.
81+
82+ :returns: area of this polygon
83+ :rtype: :class:`numbers.Number`
84+ """
85+ pass
86+
87+ @staticmethod
88+ def contains_point (polygon , offset , point ):
89+ """
90+ Determine if the polygon at offset contains point.
91+
92+ Distinguish between points that are on the edge of the polygon and
93+ points that are completely contained by the polygon.
94+
95+ .. tip::
96+
97+ This can never return True, True
98+
99+ :param polygon: the polygon
100+ :type polygon: :class:`pygorithm.geometry.polygon2.Polygon2`
101+ :param offset: the offset of the polygon
102+ :type offset: :class:`pygorithm.geometry.vector2.Vector2` or None
103+ :param point: the point to check
104+ :type point: :class:`pygorithm.geometry.vector2.Vector2`
105+ :returns: (on edge, contained)
106+ :rtype: (bool, bool)
107+ """
108+ pass
109+
110+ @staticmethod
111+ def find_intersection (poly1 , poly2 , offset1 , offset2 , find_mtv = True ):
112+ """
113+ Find if the polygons are intersecting and how to resolve it.
114+
115+ Distinguish between polygons that are sharing 1 point or a single line
116+ (touching) as opposed to polygons that are sharing a 2-dimensional
117+ amount of space.
118+
119+ The resulting MTV should be applied to the first polygon (or its offset),
120+ or its negation can be applied to the second polyogn (or its offset).
121+
122+ The MTV will be non-null if overlapping is True and find_mtv is True.
123+
124+ .. note::
125+
126+ There is only a minor performance improvement from setting find_mtv to
127+ False. It is rarely an improvement to first check without finding
128+ mtv and then to find the mtv.
129+
130+
131+ :param poly1: the first polygon
132+ :type poly1: :class:`pygorithm.geometry.polygon2.Polygon2`
133+ :param poly2: the second polygon
134+ :type poly2: :class:`pygorithm.geometry.polygon2.Polygon2`
135+ :param offset1: the offset of the first polygon
136+ :type offset1: :class:`pygorithm.geometry.vector2.Vector2` or None
137+ :param offset2: the offset of the second polygon
138+ :type offset2: :class:`pygorithm.geometry.vector2.Vector2` or None
139+ :param find_mtv: if False, the mtv is always None and there is a small \
140+
141+ :type find_mtv: bool
142+ :returns: (touching, overlapping, (mtv distance, mtv axis))
143+ :rtype: (bool, bool, (:class:`numbers.Number`, :class:`pygorithm.geometry.vector2.Vector2`) or None)
144+ """
145+ pass
0 commit comments