Area

Geometric functions area

syntax

  • area(polygon_data_item, valuesunit)
  • area(polygon_data_item)

definition

area(polygon_data_item, valuesunit) calculates the surface of the polygon_data_item Argument, in the image the green hatched area.

The resulting Values unit is configured as second argument.

The second argument may be left out. area(polygon_data_item) then derives the resulting Values unit from the coordinates themselves: the square of their Metric, so m2 for a Coordinate system in metres, which is the normal case for a projected SpatialReference. Use it when you have no values unit of your own to name; configure the second argument when you do, since only a configured unit can be referred to elsewhere in the model.

description

The resulting area values need to be positive; if the values are negative it means the order of points in the Polygon Geometry is not according to the following rules:

The order of points in a sequence needs to be clockwise for exterior bounds and counter clockwise for holes in polygons (right-hand-rule)

Beware that area(g) < 0 is not a complete check on the point order. It is a single signed sum over the whole sequence, so it only catches a feature whose rings are all in the wrong direction; a multi-polygon where only one lake is turned the wrong way comes out too large rather than negative. Use has_correct_winding to test the point order, and fix_winding_order to repair it.

applies to

conditions

The Metric of the Values unit argument must match the square of the metric of the coordinates in the coordinate system. A matching values unit that is not the same size, such as km2 against coordinates in metres, is converted rather than only relabelled. A values unit whose metric does not match at all is deprecated: it is reported as a warning and still accepted as a label.

since version

The one-argument form since 20.3.0; on coordinates with a metric since 20.19.2.

example

attribute<m2> surface   (district) := area(district/geometry, m2);
attribute<m2> surface_v2 (district) := area(district/geometry); // same values, m2 derived from the coordinates
district/geometry surface
{21: xy(113810; 403025) … 1003100
{17: xy(113269; 400990) … 474460
{19: xy(115099; 401238) … 1246460

domain district, nr of rows = 3