dms_overlay_polygon

Geometric functions dms_overlay_polygon

syntax

  • dms_overlay_polygon(first_polygon_data_item, second_polygon_data_item)
  • dms_overlay_polygon(polygon_data_item)

description

dms_overlay_polygon finds the pairs of polygons that overlap and computes the intersection geometry of each pair, resulting in a new uint32 Domain unit with one entry per pair. In QGIS this operation is known as intersect.

With two arguments the pairs run between two polygon sets: every polygon of the first with every polygon of the second that it overlaps. With one argument the pairs are those within a single set; each pair occurs once, with first_rel < second_rel, and a polygon is never paired with itself.

Unlike the four library variants, neither argument has to be a valid polygon: each pair is read under the even-odd rule of the dms polygon operators family, which is what makes an overlay possible on a source that self-intersects or has flipped rings without repairing it first.

Two polygons form a pair when their intersection encloses an area. Polygons that only touch, along a shared edge or in one point, are not a pair, as with bp_overlay_polygon and unlike geos_overlay_polygon.

result

The result is a new domain unit (uint32) with:

  • geometry: the intersection polygon of that pair
  • first_rel: a relation towards the domain of the first (or only) argument
  • second_rel: a relation towards the domain of the second argument, or of the only argument in the one-argument form

A relation is absent when its argument is a Parameter (a Void domain).

applies to

  • Attribute arguments with a polygon Value type: spoint, ipoint, wpoint, upoint, fpoint or dpoint

conditions

  1. The composition type of the arguments needs to be polygon.
  2. The Values unit of the two arguments must match.

since version

20.20.0

performance

The work is spread over the threads by the polygons of the first argument, so put the argument with the most, and the smallest, polygons first; see Which argument first under polygon operators.

example 

unit<uint32> intersect := dms_overlay_polygon(building/geometry, district/geometry)
{
    attribute<ipoint>   geometry;
    attribute<building> first_rel;
    attribute<district> second_rel;
}

see also