geofileops.options.set_sliver_tolerance#

static options.set_sliver_tolerance(tolerance: float | None) → _RestoreOriginalHandler#

Tolerance to filter out slivers from overlay operations between polygons.

If 0.0, no sliver filtering is done. If negative, only slivers with tolerance abs(value) are retained in the output instead of filtering them out.

If the tolerance is not set, the default depends on the crs. If crs is a projected CRS, the default tolerance is 0.001 CRS units (typically meters or feet). If it is a geographic CRS, the default tolerance 1e-7 CRS units (typically degrees). If crs is None or invalid, the default tolerance is 0.0, so no sliver filtering is done.

The slivers meant here are very small, often very narrow polygons that are created as a side-effect of overlay operations between polygons. Due to the limitations of finite-precision floating point arithmetic used in such operations, a point that is “snapped” on a line segment, is sometimes not exactly located on the line. When calculating e.g. an intersection, this can lead to very small “sliver” polygons being created.

Most of the time, such slivers are not desired in the output. Hence, they are filtered out based on certain criteria by default.

The basic algorythm used to determine if a geometry is a sliver is to use the GEOS set_precision algorythm with a small tolerance. If the polygon becomes NULL, because it is smaller/narrower than the tolerance, it is considered a sliver. Note that this means the tolerance should not be interpreted as an absolute minimum width of polygons to retain, as the way the set_precision algorythm works is more complex than that.

Because the set_precision algorythm is relatively costly to apply, geometries are first pre-filtered with a less expensive filter: the average width:

average_width(geom) = 2 * area(geom) / length(geom)

This formula is an approximation that works well for long, narrow polygons, but it underestimates the width for square or round polygons. Some examples:

  • a 10 x 10 meter square: 2 * (10 * 10) / (4 * 10) = 400 / 40 = 5, which is an underestimation, as the real average width is 10.

  • a 1 x 100 meter rectangle: 2 * (1 * 100) / (2 * (1 + 100)) = 200 / 202 = ~0.99, which is almost correct as the real average width is 1.

The average width being underestimated for some shapes means that some geometries are marked as slivers even if they are not. Because the average_width check is only a pre-filter, this is not a problem: such geometries will still be retained if they pass the more precise set_precision check.

Remarks:

  • You can also set the option temporarily by using this function as a context manager.

  • You can also set the option by directly setting the environment variable GFO_SLIVER_TOLERANCE to a string representing the tolerance value.

Added in version 0.11.0.

Parameters:

tolerance (float | None) – The sliver tolerance value. If None, the option is unset (so the default behavior is used).

Examples

If you want to change the default value of the option in general, you can just call the function:

gfo.options.set_sliver_tolerance(0.01)

If you want to temporarily change the option, you can use the function as a context manager:

with gfo.options.set_sliver_tolerance(0.01):
    gfo.intersection(...)