Boost polygon functions

The boost polygon operators, prefix bp_, combine an operation with an optional suffix in their name. This page lists the combinations, and what to write instead of the deprecated names that carry a kernel shape.

operations and suffixes

There are four base operators, each for spoint and ipoint polygons:

Each of them also exists with one of these suffixes, with the extra argument last:

  • _filtered drops the polygons whose area is below the given value, in squared coordinate units; see Polygon filtered
  • _inflated grows the polygons by the given distance first, placing every edge that distance outward, which can give very thin, pointed corners
  • _deflated shrinks the polygons by the given distance first

So bp_union_polygon_filtered(geometry, region_rel, 1000.0) dissolves per region and then drops the parts smaller than 1000. The suffixes do not combine: to deflate and then filter, nest two operators.

the deprecated kernel suffixes

The twelve kernel suffixes _i4HV, _i4D, _i8D, _i16D, _iXHV, _iXD and their _d counterparts, on the four base operators, 48 names in all, are deprecated. They work, and every use logs a warning that names the replacement. The kernel shape is an argument of minkowski_sum and minkowski_difference, which all five libraries provide and which also take a kernel polygon of your own.

A kernel suffix has the form _[a][X][y]:

  • a is i (inflate) or d (deflate): the choice between minkowski_sum and minkowski_difference
  • X is the degree of rounding, 4, 8 or 16, or X for a star shape: part of the variant argument
  • y is the kernel shape, D (diagonal, diamond-shaped) or HV (horizontal and vertical, square-shaped)

what to write instead

Apply the Minkowski operator to the result of the same operator without the suffix:

deprecated replacement
bp_polygon_i4HV(g, size) bp_minkowski_sum(bp_polygon(g), size, '4HV')
bp_union_polygon_i8D(g, size) bp_minkowski_sum(bp_union_polygon(g), size, '8D')
bp_union_polygon_i8D(g, part, size) bp_minkowski_sum(bp_union_polygon(g, part), size, '8D')
bp_split_polygon_dXD(g, size) bp_split_polygon(bp_minkowski_difference(bp_polygon(g), size, 'XD'))
bp_split_union_polygon_d8D(g, part, size) bp_split_polygon(bp_minkowski_difference(bp_union_polygon(g, part), size, '8D'))

The i- and d-prefixed variant spellings are accepted as the variant literal too, so 'i4HV' works on minkowski_sum and 'd4HV' on minkowski_difference; a prefix that disagrees with the operator is refused.

The replacement computes one intermediate polygon attribute that the suffixed operator did not: one polygon for the union forms, and one per element otherwise. For the union forms that is negligible; for a large attribute per element it is one extra pass over the geometry. In return it takes any kernel, and the same operator exists for the other libraries, also on float coordinates.

examples

A union without a partition results in a parameter, a split in a new domain unit, and a union with a partition in an attribute of the values unit of the partition:

parameter<rdc_mm> union (poly) := bp_union_polygon(Wegdeel/geometry[rdc_mm]);
unit<uint32> split_union := bp_split_union_polygon(Wegdeel/geometry[rdc_mm]);

This dissolves per province and then splits the result into single polygons:

unit<uint32> split_partitioned_union := bp_split_union_polygon(Wegdeel/geometry[rdc_mm], Wegdeel/province_rel);

see also