geo2d.geometry.Polygon

class geo2d.geometry.Polygon(vertices)

A general (closed) Polygon class.

The Polygon is made out of points (vertices of type Point) and edges (Segment). It can be created by passing a list of Point-like objects.

Parameters :

vertices : {list/tuple of point-like}

The list of Point-like objects that make the Polygon. The self.edges of the Polygon are automatically created and stored. If the length of the vertices list is < 3 this cannot be a Polygon and a ValueError will be raised.

Raises :

ValueError :

In case length of the vertices list is smaller than 3.

Attributes

area	[scalar] Get the (positive) area of this Polygon.
bbox_height	[scalar] Get self.bounding_box.height.
bbox_width	[scalar] Get self.bounding_box.width.
bounding_box	[BoundingBox] Get BoundingBox of self.
centroid	[Point] Get the centroid (Point) of the Polygon.
diameter	[scalar] Get the diameter of the Polygon.
edges	[list of segments] Get the edges, that is the segments.
vertices	[list of points] Get the vertices.
width	[scalar] Get the width of the Polygon.

Methods

__contains__(x)	Searches for x in “itself”.
__getitem__(idx)	Retreive points (self.vertices) by idx.
__len__()	The length of the Polygon is defined by the length of the
_compute_diameter_width()	Compute the diameter and width of the Polygon.
divide([obj, edge_no, frac, relative_phi, ...])	Divide the Polygon.
get_point_on_self([edge_no, frac])	Return a random Point on the given Segment
has(point)	Determine if point is inside Polygon based on the winding
intersection(obj)	Return points of intersection if any.
rotate(theta[, point, angle])	Rotate self around pivot point.
translate(dx, dy)	Translate self by given amounts on x and y.

Detailed description

class geo2d.geometry.Polygon(vertices)

A general (closed) Polygon class.

The Polygon is made out of points (vertices of type Point) and edges (Segment). It can be created by passing a list of Point-like objects.

Parameters :

vertices : {list/tuple of point-like}

The list of Point-like objects that make the Polygon. The self.edges of the Polygon are automatically created and stored. If the length of the vertices list is < 3 this cannot be a Polygon and a ValueError will be raised.

Raises :

ValueError :

In case length of the vertices list is smaller than 3.

__contains__(x)

Searches for x in “itself”. If we’re talking about a Point or a Vector then this searches within their components (x, y). For everything else it searches within the list of points (vertices).

Parameters :

x : {point, scalar}

The object to search for.

Returns :

out : {True, False}

True if we find x in self, else False.

__getitem__(idx)

Retreive points (self.vertices) by idx.

Parameters :

idx : scalar

The index of the Point (vertex).

Returns :

ret : point

The vertex by index.

__len__()

The length of the Polygon is defined by the length of the self.vertices list.

_compute_diameter_width()

Compute the diameter and width of the Polygon.

This is meant for internal use only. The diameter is defined by the length of the rectangle of minimum area enclosing the Polygon, and the width of the Polygon is then just the width of the same rectangle of minimum area enclosing the Polygon. It’s calculation is based on [Arnon1983].

area

[scalar] Get the (positive) area of this Polygon.

Using the standard formula [WPolygon] for the area of a Polygon:

\[\begin{split}A &= \frac{1}{2} \sum_{i=0}^{n-1} (x_iy_{i+1} - x_{i+1}y_i)\end{split}\]

\(A\) can be negative depending on the orientation of the Polygon but this property always returns the positive value.

Notes

This function (property) also sets up self._area if it’s not set. This variable (self._area) is meant to be just for internal use (at least for now).

bbox_height

[scalar] Get self.bounding_box.height.

bbox_width

[scalar] Get self.bounding_box.width.

bounding_box

[BoundingBox] Get BoundingBox of self.

centroid

[Point] Get the centroid (Point) of the Polygon.

Defined as [WPolygon]:

\[\begin{split}C_x &= \frac{1}{6A} \sum_{i=0}^{i=n-1}(x_i + x_{i+1}) (x_iy_{i+1}-x_{i+1}y_i)\end{split}\]\[\begin{split}C_y &= \frac{1}{6A} \sum_{i=0}^{i=n-1}(y_i + y_{i+1}) (x_iy_{i+1}-x_{i+1}y_i)\end{split}\]

where \(A\) is the area using the standard formula for a Polygon [WPolygon] so it can take negative values.

diameter

[scalar] Get the diameter of the Polygon.

Refer to _compute_diameter_width for details on how this is calculated.

See also

Polygon.diameter, Polygon._compute_diameter_width

divide(obj=None, edge_no=None, frac=None, relative_phi=None, drelative_phi=0)

Divide the Polygon.

Parameters :

obj : line-like, optional

If no obj is given then edge_no is used to build a Ray from a randomly chosen Point on self.edges[edge_no] with inward direction and the closest intersection Point to Ray.p1 is used to divide the Polygon in two, else all of the points given by the intersection between the Polygon and obj are used to split the Polygon in any number of polygons.

edge_no : int, optional

If given, self.edges[edge_no] will be used to build a Ray as explained above, else a random edge number will be chosen.

frac : float, optional

If given the point on self.edges[edge_no] will be situated at the fraction frac between self.edges[edge_no].p1 and self.edges[edge_no].p2 relateive to p1. Must be in the open interval (0, 1).

relative_phi : float, optional

Is an angle (in degrees) that gives the direction of the Ray spawned from self.edges[edge_no]. It has to be in the open interval (0, 90). If not given a random direction will be choosed in the interval (0, 90).

drelative_phi : float, optional

Is an angle interval centered on relative_phi which is used to calculate a random relative direction for the Ray spawned from self.edges[edge_no] in the interval [relateive_phi - drelative_phi/2, relative_phi + drelative_phi/2). If not given it’s assumed to be 0.

Returns :

ret : tuple of size 2

The first element is a list with the newly created polygons and the second element in the tuple is another list with the Segments that were used to divide the initial Polygon (ie. the common edge between the newly created polygons). These lists can be of length 0 if no division took place.

edges

[list of segments] Get the edges, that is the segments.

These are the edges of the Polygon, which are defined by the list of vertices. The Polygon is considered to be closed (ie. the last segment is defined by points pn and p1).

get_point_on_self(edge_no=None, frac=None)

Return a random Point on the given Segment defined by edge_no.

Parameters :

edge_no : int, optional

The index of the edge from the edge list. Default is edge_no = 0, which means the calculate on first edge.

frac : float, optional

A number in the open interval (0, 1). The point will be placed on the edge with the edge number edge_no and relative to the first point in the specified edge. If left to default (None), a random Point will be returned on the specified edge.

Returns :

out : point

The Point on this edge (Segment).

has(point)

Determine if point is inside Polygon based on the winding number.

Parameters :

point : point-like

The point to test if it’s included in self or not.

Returns :

out : {True, False}

True if the point is included in self (wn > 0), else False (wn == 0).

Notes

Winding number algorithm (C++ implementation): http://geomalgorithms.com/a03-_inclusion.html

intersection(obj)

Return points of intersection if any.

This method just calls the intersection method on the other objects that have it implemented.

Parameters :

obj : geometric object

obj is any object that has intersection implemented.

Returns :

ret : {point, None}

The point of intersection if any, if not, just None.

rotate(theta, point=None, angle='degrees')

Rotate self around pivot point.

Parameters :

theta : scalar

The angle to be rotated by.

point : {point-like}, optional

If given this will be used as the rotation pivot.

angle : {‘degrees’, ‘radians’}, optional

This tells the function how theta is passed: as degrees or as radians. Default is degrees.

translate(dx, dy)

Translate self by given amounts on x and y.

Parameters :

dx, dy : scalar

Amount to translate (relative movement).

vertices

[list of points] Get the vertices.

The list of Point-like objects that make up the Polygon. It’s lengths cannot be less than 3.

width

[scalar] Get the width of the Polygon.

Refer to _compute_diameter_width for details on how this is calculated.

See also

Polygon.diameter, Polygon._compute_diameter_width

[Arnon1983]

Arnon et al., A Linear Time Algorithm for the Minimum Area Rectangle Enclosing a Convex Polygon” (1983), Computer Science Technical Reports. Paper 382

[WPolygon]

(1, 2, 3) http://en.wikipedia.org/wiki/Polygon