Area - ObjectVision/GeoDMS GitHub Wiki
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.
Since GeoDMS 20.3.0 that second argument may be left out. area(polygon_data_item) derives the resulting values unit from the coordinates themselves: the square of their metric, so m2 for a coordinate system in metres. 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.
Since GeoDMS 20.19.2 the single-argument form also works on coordinates that have a metric, which is the normal case for a projected SpatialReference. Before 20.19.2 it crashed the GeoDMS GUI on exactly those coordinates; only coordinates without a metric, such as a plain grid domain, came through. The two-argument form was never affected.
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 with the square of the metric of the coordinates in the coordinate system. Since GeoDMS 20.3.0 a matching values unit that is not the same size, such as km2 against coordinates in metres, is converted rather than only relabelled, and a values unit whose metric does not match at all is reported as a warning and still accepted as a label, which is deprecated behaviour.
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