dms_union_polygon

Geometric functions 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.

The union is folded pairwise, so the work grows with the number of elements rather than with their square, and every reduction of one call snaps to the same grid, which keeps the answer independent of the order the fold happened to take.

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

1. The composition type of the polygon_data_item needs to be polygon.
2. 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);

see also

• dms polygon operators - the family: the even-odd rule, the grid and what the result looks like
• dms_polygon - the same reading, per element, without dissolving
• dms_split_union_polygon - the dissolve, then split into single polygons
• geos_union_polygon, bp_union_polygon, bg_union_polygon, cgal_union_polygon - the same operator on the geometry libraries
• Dissolve (merge geometries) - the configuration example
• Cleaning invalid polygons - the worked example of the family