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
- Data item polygon_data_item with fpoint or dpoint Value type and composition type polygon.
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