2D polgon

class Polygon2(vertices=None, close=True)

Class to represent 2D (planar) polygons

Note

Uses Matplotlib primitives to perform transformations and intersections.

__init__(vertices=None, close=True)

Create planar polygon from vertices

Parameters:

• vertices (ndarray(2, N), optional) – vertices of polygon, defaults to None

• close (bool) – closes the polygon, replicates the first vertex, defaults to True

Create a polygon from a set of points provided as columns of the 2D array vertices. A closed polygon is created so the last vertex should not equal the first.

Example:

>>> from spatialmath import Polygon2
>>> p = Polygon2([(1, 2), (3, 2), (2, 4)])

Warning

The points must be sequential around the perimeter and counter clockwise, otherwise moments will be negative.

Note

The polygon is represented by a Matplotlib Path

__len__()

Number of vertices in polygon

Returns:

number of vertices

Return type:

int

Example:

>>> from spatialmath import Polygon2
>>> p = Polygon2([(1, 2), (3, 2), (2, 4)])
>>> len(p)
3

__str__()

Polygon to string

Returns:

brief summary of polygon

Return type:

str

Example:

>>> from spatialmath import Polygon2
>>> import numpy as np
>>> p = Polygon2(np.array([[1, 3, 2], [2, 2, 4]]))
>>> print(p)
Polygon2 with 4 vertices

animate(T, **kwargs)

Animate a polygon

Parameters:

• T (SE2) – new pose of Polygon

• kwargs – options passed to Matplotlib Patch

Return type:

None

The plotted polygon is moved to the pose given by T. The pose is always with respect to the initial vertices when the polygon was constructed. The vertices of the polygon will be updated to reflect what is plotted.

If the polygon has already plotted, it will keep the same graphical attributes. If new attributes are given they will replace those given at construction time.

Seealso:

plot()

area()

Area of polygon

Returns:

area

Return type:

float

Example:

>>> from spatialmath import Polygon2
>>> p = Polygon2([(1, 2), (3, 2), (2, 4)])
>>> p.area()
2.0

Seealso:

moment()

bbox()

Bounding box of polygon

Returns:

bounding box as [xmin, xmax, ymin, ymax]

Return type:

ndarray(4)

Example:

>>> from spatialmath import Polygon2
>>> p = Polygon2([(1, 2), (3, 2), (2, 4)])
>>> p.bbox()
array([1., 2., 3., 4.])

centroid()

Centroid of polygon

Returns:

centroid

Return type:

ndarray(2)

Example:

>>> from spatialmath import Polygon2
>>> p = Polygon2([(1, 2), (3, 2), (2, 4)])
>>> p.centroid()
array([2.    , 2.6667])

Seealso:

moment()

contains(p, radius=0.0)

Test if point is inside polygon

Parameters:

• p (array_like(2)) – point

• radius (float, optional) – Add an additional margin to the polygon boundary, defaults to 0.0

Returns:

True if point is contained by polygon

Return type:

bool

radius can be used to inflate the polygon, or if negative, to deflated it.

Example:

>>> from spatialmath import Polygon2
>>> p = Polygon2([(1, 2), (3, 2), (2, 4)])
>>> p.contains([0, 0])
False
>>> p.contains([2, 3])
True

Warning

Returns True if the point is on the edge of the polygon but False if the point is one of the vertices.

Warning

For a polygon with clockwise ordering of vertices the sign of radius is flipped.

Seealso:

matplotlib.contains_point()

edges()

Iterate over polygon edge segments

Creates an iterator that returns pairs of points representing the end points of each segment.

Return type:

Iterator

intersects(other)

Test for intersection

Parameters:

other (Polygon2 or Line2 or list(Polygon2) or list(Line2)) – object to test for intersection

Returns:

True if the polygon intersects other

Return type:

bool

Raises:

ValueError –

Returns true if the polygon intersects the the given polygon or 2D line. If other is a list, test against all in the list and return on the first intersection.

moment(p, q)

Moments of polygon

Parameters:

• p (int) – moment order x

• q (int) – moment order y

Return type:

float

Returns the pq’th moment of the polygon

\[M(p, q) = \sum_{i=0}^{n-1} x_i^p y_i^q\]

Example:

>>> from spatialmath import Polygon2
>>> p = Polygon2([(1, 2), (3, 2), (2, 4)])
>>> p.moment(0, 0)  # area
2.0
>>> p.moment(3, 0)
18.0

Note is negative for clockwise perimeter.

plot(ax=None, **kwargs)

Plot polygon

Parameters:

• ax (Axes, optional) – axes in which to draw the polygon, defaults to None

• kwargs – options passed to Matplotlib Patch

Return type:

None

A Matplotlib Patch is created with the passed options **kwargs and added to the axes.

Examples:

>>> from spatialmath.base import plotvol2, plot_polygon
>>> plotvol2(5)
>>> p = Polygon2([(1, 2), (3, 2), (2, 4)])
>>> p.plot(fill=False)
>>> p.plot(facecolor="g", edgecolor="none")  # green filled triangle

(Source code, png, hires.png, pdf)

(Source code, png, hires.png, pdf)

Seealso:

animate() matplotlib.PathPatch()

radius()

Radius of smallest enclosing circle

Returns:

radius

Return type:

float

This is the radius of the smalleset circle, centred at the centroid, that encloses all vertices.

Example:

>>> from spatialmath import Polygon2
>>> p = Polygon2([(1, 2), (3, 2), (2, 4)])
>>> p.radius()
1.3333333333333335

transformed(T)

A transformed copy of polygon

Parameters:

T (SE2) – planar transformation

Returns:

transformed polygon

Return type:

Polygon2

Returns a new polgyon whose vertices have been transformed by T.

Example:

>>> from spatialmath import Polygon2, SE2
>>> p = Polygon2([(1, 2), (3, 2), (2, 4)])
>>> p.vertices()
array([[1., 3., 2.],
       [2., 2., 4.]])
>>> p.transformed(SE2(10, 0, 0)).vertices() # shift by x+10
array([[11., 13., 12.],
       [ 2.,  2.,  4.]])

vertices(unique=True)

Vertices of polygon

Parameters:

unique (bool, optional) – return only the unique vertices , defaults to True

Returns:

vertices

Return type:

ndarray(2,n)

Returns the set of vertices. The polygon is always closed, that is, the first and last vertices are the same. The unique option does not include the last vertex.

Example: