centroid_polygon_xy

compas.geometry.centroid_polygon_xy(polygon)[source]

Compute the centroid of the surface of a polygon projected to the XY plane.

Parameters:
polygonsequence[[float, float] or [float, float, float] | compas.geometry.Point]

A sequence of polygon point XY(Z) coordinates. The Z coordinates are ignored.

Returns:
[float, float, 0.0]

The XYZ coordinates of the centroid in the XY plane.

Raises:
ValueError

If the polygon has less than three points.

Warning

The polygon need not be convex.

The polygon may be self-intersecting. However, it is unclear what the meaning of the centroid is in that case.

Notes

The centroid is the centre of gravity of the polygon surface if mass would be uniformly distributed over it.

It is calculated by triangulating the polygon surface with respect to the centroid of the polygon vertices, and then computing the centroid of the centroids of the individual triangles, weighted by the corresponding triangle area in proportion to the total surface area.

\[c_x = \frac{1}{A} \sum_{i=1}^{N} A_i \cdot c_{x,i} c_y = \frac{1}{A} \sum_{i=1}^{N} A_i \cdot c_{y,i} c_z = 0\]

Examples

>>> polygon = [[0.0, 0.0, 0.0], [1.0, 0.0, 0.0], [1.0, 1.0, 0.0], [0.0, 1.0, 0.0]]
>>> centroid_polygon_xy(polygon)
[0.5, 0.5, 0.0]