Clarification on ST_CoverageClean Parameters: snappingDistance and gapMaximumWidth

[Douglas Fan]

Thanks a lot for the explanation—it really clarified things for me. Much
appreciated! 🙏

Best regards,
Man Ho Fan

On Tue, Oct 7, 2025 at 9:12 PM Martin Davis <mtnclimb at gmail.com> wrote:

> And note that the correct signature
>
> geometry ST_CoverageClean(geometry winset geom, float8 gapMaximumWidth =
> 0, float8 snappingDistance = -1, text overlapMergeStrategy =
> 'MERGE_LONGEST_BORDER');
>
> means that the best-practice pattern for using the function is to simply
> specify the maximum gap width, leaving the snapping tolerance and overlap
> merge strategy as defaulits:
>
> CREATE TABLE  example1_c AS
>   SELECT id,  ST_CoverageClean(geom, 1) OVER () AS GEOM
>   FROM  example1;
>
>
> On Tue, Oct 7, 2025 at 10:49 AM Paul Ramsey via postgis-users <
> postgis-users at lists.osgeo.org> wrote:
>
>> If I told you there is an error in the documentation and that the actual
>> signature is this, would that allay your concerns?
>>
>> ST_CoverageClean (geom geometry, gapMaximumWidth float8 default 0.0,
>> snappingDistance float8 default -1.0, overlapMergeStrategy text default '
>> MERGE_LONGEST_BORDER')
>>
>> P.
>>
>> On Tue, Sep 23, 2025 at 5:25 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/20251008/4bbf011f/attachment.htm>