Clarification on ST_CoverageClean Parameters: snappingDistance and gapMaximumWidth

[Martin Davis]

This appears to be a bug in the PostGIS usage of GEOS.  In GEOS, this case
works correctly.  (E.g. in your first example, the narrow input polygon is
preserved).  We're looking into this now.

The ST_CoverageClean documentation and your understanding are correct:
1. snappingDistance controls vertex snapping, with -1 applying an automatic
distance, and 0.0 disabling snapping.
2. gapMaximumWidth closes gaps smaller than the specified tolerance.

Note that "gaps" are narrow closed areas which occur *between* the input
polygons (after snapping, if any,  has taken place).  Narrow input polygons
are never treated as gaps, but are preserved (as long as they are not
snapped to the point of collapse).

Answers to your questions:

1. How do these two parameters interact?

Snapping is the first phase of the cleaning process.  It operates on
the vertices and edges of the input.  It accomplishes two things: (a)
increasing the robustness of the edge-noding process and (b) removing very
narrow slivers and gores from the input.  Generally the snapping tolerance
should be small relative to the precision of the input, to avoid unwanted
distortion.  It's probably best to simply use the parameter default for
most cases.

Gap merging is done in a subsequent phase, operating on the
snapped polygons.  The gap maximum width value is dataset-dependent, but
generally at least an order of magnitude larger than the snap tolerance.

A more detailed description of the process is here:
https://lin-ear-th-inking.blogspot.com/2025/04/coverage-cleaning-in-jts.html

2. Best practices or recommended workflows for cleaning polygonal coverages
with minimal geometry distortion.

Use the default snapping tolerance, or a very small one.

3. Any known edge cases or limitations when using ST_CoverageClean.

- Gaps are merged as-is, without splitting.  This can result in "spikes"
being created by gaps which have multiple "arms".  There is work being done
on splitting gaps to avoid this problem.
- Similarly, gaps which contain a wide portion (i.e. wider than the max gap
width) and also one or more narrow "arms" will not be merged, due to the
wide portion.  Handling these could be improved via a splitting approach,
hopefully.

4. Whether gapMaximumWidth also triggers geometry simplification or sliver
removal beyond gap closing.

gapMaximumWidth only determines which gaps are merged to adjacent
polygons.  No other simplification is performed.

HTH - Martin



On Tue, Sep 23, 2025 at 6:00 AM Douglas Fan <douglas.mhfan at gmail.com> wrote:

> Dear PostGIS Developers and Users,
>
> First of all, thank you for the development of the new ST_CoverageClean
> function in PostGIS 3.6.0. It’s a fantastic addition that has already
> helped a lot in my work with polygonal coverages. I really appreciate the
> effort that went into making this tool available.
> While testing the function, I’ve encountered some behaviors that I’d like
> to better understand, particularly regarding the snappingDistance and
> gapMaximumWidth parameters.
>
> From the documentation, I understand that:
> 1. snappingDistance controls vertex snapping, with -1 applying an
> automatic distance, and 0.0 disabling snapping.
> 2. gapMaximumWidth closes gaps smaller than the specified tolerance.
>
> However, during testing with various combinations (e.g., snappingDistance
> set to -1, 0.0, 1, 2 and gapMaximumWidth set to 0, 1, 2), I noticed:
> 1. Even when snappingDistance is explicitly set to 0.0, small sliver
> vertices still appear to be snapped or altered when gapMaximumWidth is
> greater than 0.
> 2. Slivers that are thinner than the gapMaximumWidth are removed, even
> when they are not actual gaps or overlaps.
>
> This behavior seems counterintuitive, as I expected no snapping to occur
> with snappingDistance = 0.0. Could this be due to internal gap cleaning
> logic that also affects vertex positions? Or is there an implicit snapping
> step tied to gapMaximumWidth?
>
> I’d be grateful for any insights into:
>
> 1. How do these two parameters interact?
> 2. Best practices or recommended workflows for cleaning polygonal
> coverages with minimal geometry distortion.
> 3. Any known edge cases or limitations when using ST_CoverageClean.
> 4. Whether gapMaximumWidth also triggers geometry simplification or sliver
> removal beyond gap closing.
>
> Thanks in advance for your help and for the continued development of
> PostGIS.
>
> Best regards,
> Man Ho Fan
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.osgeo.org/pipermail/postgis-users/attachments/20251007/f8b1c596/attachment.htm>