geos_buffer_multi_polygon

Geometric functions > geos_buffer_multi_polygon

syntax

geos_buffer_multi_polygon(polygon_data_item, buffer_distance, nrPointsInCircle)

description

geos_buffer_multi_polygon(polygon_data_item, buffer_distance, nrPointsInCircle) creates an expanded (positive buffer) or contracted (negative buffer) polygon for each element in the polygon_data_item. The result is a polygon data item with the same domain as the input.

The buffer_distance is a Float64 value that specifies the buffer distance in the units of the coordinate system. A positive value expands the polygon outward; a negative value contracts it inward.

The nrPointsInCircle is a UInt8 value that specifies the number of points used to approximate rounded corners. A higher value results in a smoother buffer but increases computation time. The minimum value is 3.

For a polygon, nrPointsInCircle is given to geos as it is, and geos takes it as the number of segments per quarter circle: each rounded corner of a polygon gets nrPointsInCircle segments, so a square buffered with 16 gets about 68 points. This differs from the point and arc buffers, where nrPointsInCircle is the number of points of a full circle, and from the bg_ family. The difference is kept because existing models are calibrated on it; to get a polygon buffer with the corners of a point buffer of n points per circle, pass n / 4.

The geos_ prefix of the function name indicates that the implementation of the operator uses geos.

applies to

attribute polygon_data_item with a polygon value type
parameter buffer_distance with a Float64 value type
parameter nrPointsInCircle with a UInt8 value type

conditions

The composition type of the polygon_data_item needs to be polygon.
The order of points in the polygon_data_item needs to be clockwise for exterior bounds and counterclockwise for holes (right-hand-rule).
nrPointsInCircle must be at least 3.

since version

example

// Expand each municipality polygon by 500 metres
attribute<fpoint> buffered_geometry (municipality) := geos_buffer_multi_polygon(municipality/geometry, 500.0, 16b);

// Contract each polygon by 100 metres (negative buffer)
attribute<fpoint> contracted_geometry (district) := geos_buffer_multi_polygon(district/geometry, -100.0, 16b);