centroid_polygon

compas.geometry.centroid_polygon(polygon)[source]

Compute the centroid of the surface of a polygon.

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

A sequence of polygon point coordinates.

Returns:
[float, float, float]

The XYZ coordinates of the centroid.

Raises:
ValueError

If the polygon has less than three points.

Warning

The polygon need not be convex.

The polygon need not be flat. However, it is unclear what the meaning of the centroid is in that case.

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 = \frac{1}{A} \sum_{i=1}^{N} A_i \cdot c_{z,i}\]

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(polygon)
[0.5, 0.5, 0.0]