dms_union_polygon

syntax

dms_union_polygon(polygon_data_item)
dms_union_polygon(polygon_data_item, partition_attribute)

description

dms_union_polygon(polygon_data_item) dissolves every polygon of the argument into one value: the union of them all, as a Parameter with a Void domain.

dms_union_polygon(polygon_data_item, partition_attribute) dissolves per group. Polygons that share a partition value are merged, and the result has one element per value of the partition attribute’s Values unit. This is the dissolve by attribute of GIS terminology.

Unlike the four library variants, the elements do not have to be valid polygons: each is read under the even-odd rule of the dms polygon operators family, so a source with self-intersecting rings, flipped holes or unclosed rings dissolves without a repair pass. A dissolve of an invalid element with a valid one is well defined, which is what the family exists for.

Every element is cleaned alone, and the cleaned rings are then noded together once, on one grid for the whole call: for float coordinates the grid is derived from the declared range of the Values unit when it has one, and from the extent of all the elements otherwise, so the answer depends neither on the order of the elements nor on how the attribute is tiled. A face is inside the result when the number of elements covering it is not zero, so an element wound the wrong way round still adds to the union rather than cutting a hole. The work grows with the number of vertices and crossings rather than with the square of the number of elements.

applies to

Attribute polygon_data_item with a polygon Value type: spoint, ipoint, wpoint, upoint, fpoint or dpoint
Attribute partition_attribute (optional) with a Categorical value type, over the same Domain unit as polygon_data_item

conditions

The composition type of the polygon_data_item needs to be polygon.
A partition_attribute, when given, must have the same domain as polygon_data_item.

since version

20.20.0

example

parameter<ipoint>  country  (polygon) := dms_union_polygon(municipality/geometry);
attribute<ipoint>  province (province, polygon) := dms_union_polygon(municipality/geometry, municipality/province_rel);