area - ObjectVision/GeoDMS GitHub Wiki

Geometric functions area

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

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.

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.

• data item polygon_data_item with fpoint or dpoint value type and composition type polygon.

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.

attribute<m2> surface   (district) := area(district/geometry, m2);
attribute<m2> surface_v2 (district) := area(district/geometry); // same values, m2 derived from the coordinates

domain district, nr of rows = 3