mahautils.shapes.Polygon¶

Bases: ClosedShape2D

An object representing a closed polygon in the 2D Cartesian plane

This class is intended to represent a polygon, comprised of the closed region inside a series of vertices connected by straight lines. The locations of the vertices are arbitrary and edges of the polygon can self-intersect.

Examples

Create a triangle:

>>> vertices = [[0, 0], [1, 0], [1, 2]]
>>> triangle = mahautils.shapes.Polygon(vertices)

View the points on the boundary of the polygon, optionally repeating the start/end point of the polygon:

>>> triangle.points()
(array([0., 0.]), array([1., 0.]), array([1., 2.]))
>>> triangle.points(repeat_end=True)
(array([0., 0.]), array([1., 0.]), array([1., 2.]), array([0., 0.]))

Check whether a point is inside the polygon:

>>> triangle.is_inside((0.5, 0.5))
True
>>> triangle.is_inside((0.5, 10))
False

Attributes

`area`	Returns the area of the polygon
`vertices`	Returns a copy of a NumPy array containing the vertices of the polygon

Methods

`__init__`(vertices[, construction, ...])	Creates an object representing a polygon
`is_inside`(point[, perimeter_is_inside])	Returns whether a point is inside the shape
`points`([repeat_end])	Returns a list containing discretized points around the perimeter of the shape
`reflect`(pntA, pntB)	Reflects the shape across a line defined by two points
`rotate`(center, angle[, angle_units])	Rotates the shape in the \(xy\)-plane
`translate`([x, y])	Translates the shape in the \(xy\)-plane
`xy_coordinates`([repeat_end])	Generates Cartesian coordinates of the shape

Inherited Attributes

`construction`	Whether the shape is a "construction shape" meant for visual display but not functional geometry
`default_num_coordinates`	The number of coordinates to use when representing a discretized form of the shape
`is_closed`	Whether the shape is bounded by a closed perimeter
`polygon_file_enclosed_conv`	Convention for considering enclosed area when generating a polygon file from `ClosedShape2D` objects
`units`	The units in which the geometry is defined

Inherited Methods

`reflect_x`()	Reflects the shape over the \(x\)-axis
`reflect_y`()	Reflects the shape over the \(y\)-axis

Creates an object representing a polygon

Parameters:

vertices (list or tuple or np.ndarray) – A 2D array containing a set of 2D points representing the vertices of the polygon, in order
construction (bool, optional) – Whether the shape is a “construction shape” meant for visual display but not functional geometry (default is False)
polygon_file_enclosed_conv (int, optional) – Convention for considering enclosed area when generating a polygon file from ClosedShape2D objects (default is 1)
units (str, optional) – The units in which the geometry is defined, or None to indicate dimensionless geometry or that units are to be ignored (default is None)

property area: float¶: Returns the area of the polygon

property vertices: ndarray¶

Returns a copy of a NumPy array containing the vertices of the polygon

Even though polygons are a closed shape, points are stored in the vertices attribute such that the first and last point are not repeated.

is_inside(point: List[float] | Tuple[float, float] | ndarray | CartesianPoint2D, perimeter_is_inside: bool = True) → bool¶

Returns whether a point is inside the shape

Parameters:

point (list or tuple or CartesianPoint2D) – The point whose location is to be checked. Must be either a CartesianPoint2D instance, or a list or tuple containing two elements of type float
perimeter_is_inside (bool, optional) – Whether to consider points on the perimeter of the shape to be inside the shape (default is True)

Returns:

If perimeter_is_inside is True, returns True if point is inside the shape or on the perimeter, and False otherwise. If perimeter_is_inside is False, returns True if point is inside the shape but NOT on the perimeter, and False otherwise

Return type:

bool

points(repeat_end: bool = False) → Tuple[ndarray, ...]¶

Returns a list containing discretized points around the perimeter of the shape

This method returns a tuple, of which each element is a point along the perimeter of the shape.

Parameters:: repeat_end (bool, optional) – Whether the first and last coordinate returned should be the same point (default is False). This is useful, for instance, when plotting the shape with Matplotlib: if repeat_end is set to False, there may be a slight gap visible between the end points of the shape

See also

xy_coordinates: Returns the same coordinates as xy_coordinates() except that points are returned as a list, where each entry is a point on the perimeter of the shape (essentially the transpose of xy_coordinates())

Reflects the shape across a line defined by two points

Parameters:

pntA (list or tuple or CartesianPoint2D) – One point on the line across which the shape is to be reflected
pntB (list or tuple or CartesianPoint2D) – Another point on the line across which the shape is to be reflected

rotate(center: List[float] | Tuple[float, float] | ndarray | CartesianPoint2D, angle: float, angle_units: str = 'rad') → None¶

Rotates the shape in the \(xy\)-plane

Rotates the shape the shape a given angle in the \(xy\)-plane about a user-specified point.

Parameters:

center (list or tuple or CartesianPoint2D) – The center of rotation about which to rotate the shape
angle (float) – The angle by which to rotate the shape about center
angle_units (str, optional) – The units (radians or degrees) of the angle argument. Must be either 'rad' or 'deg' (default is 'rad')

property construction¶: Whether the shape is a “construction shape” meant for visual display but not functional geometry

property default_num_coordinates¶: The number of coordinates to use when representing a discretized form of the shape

property is_closed¶: Whether the shape is bounded by a closed perimeter

property polygon_file_enclosed_conv: int¶

Convention for considering enclosed area when generating a polygon file from ClosedShape2D objects

This property is exclusively intended for use when generating Maha Multics polygon files. As discussed on the Polygon File Format page, when generating Maha Multics polygon files, the ENCLOSED_CONV option can be set for any given closed shape to indicate whether the area inside the shape (as determined by the winding number algorithm) is considered by the polygon file to to be “enclosed” area. This property is designed to store the value of this ENCLOSED_CONV option for any ClosedShape2D objects that are to be incorporated into a polygon file.

Note

For more information about the interpretation of this option, refer to the Polygon File Format page.

reflect_x()¶: Reflects the shape over the \(x\)-axis

reflect_y()¶: Reflects the shape over the \(y\)-axis

translate(x: float = 0, y: float = 0) → None¶

Translates the shape in the \(xy\)-plane

Translates the shape a user-specified distance in the \(x\)- and/or \(y\)-directions.

Parameters:

x (float, optional) – The distance to translate the shape in the \(x\)-direction (default is 0)
y (float, optional) – The distance to translate the shape in the \(y\)-direction (default is 0)

property units: str | None¶: The units in which the geometry is defined

xy_coordinates(repeat_end: bool = False) → Tuple[ndarray, ndarray]¶

Generates Cartesian coordinates of the shape

This method generates a set of discretized points around the perimeter of the shape. Points are returned as a tuple of two NumPy arrays: the first NumPy array contains the x-coordinates of the points, and the second NumPy array contains the y-coordinates. This format makes it relatively easy to plot the shape using packages like Matplotlib.

Parameters:: repeat_end (bool, optional) – Whether the first and last coordinate returned should be the same point (default is False). This is useful, for instance, when plotting the shape with Matplotlib: if repeat_end is set to False, there may be a slight gap visible between the end points of the shape