<!-- Converted by db4-upgrade version 1.1 -->
<section xmlns:xlink="http://www.w3.org/1999/xlink" xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="Coverage">
  <title>Coverages</title><info>
    <abstract>
      <para>These functions operate on sets of polygonal geometry that form "implicit coverages".
      To form a valid coverage polygons must not overlap, and the vertices of adjacent edges must match exactly.
      Coverages are fast to process, and can be operated on with window functions, which retain the coverage topology inside the window partition while altering the edges.</para>
    </abstract>
  </info>



  <refentry xml:id="ST_CoverageInvalidEdges">
    <refnamediv>
      <refname>ST_CoverageInvalidEdges</refname>

      <refpurpose>Window function that finds locations where polygons fail to form a valid coverage.</refpurpose>
    </refnamediv>

    <refsynopsisdiv>
      <funcsynopsis>
        <funcprototype>
          <funcdef>geometry <function>ST_CoverageInvalidEdges</function></funcdef>
          <paramdef><type>geometry winset </type>
            <parameter>geom</parameter></paramdef>
          <paramdef><type>float8 </type>
            <parameter>tolerance = 0</parameter></paramdef>
        </funcprototype>
      </funcsynopsis>
    </refsynopsisdiv>

    <refsection>
      <title>Description</title>

      <para>A window function which checks if the polygons in the window partition form a valid polygonal coverage.
      It returns linear indicators showing the location of invalid edges (if any) in each polygon.
      </para>
      <para>A set of valid polygons is a valid coverage if the following conditions hold:
        </para>

      <itemizedlist>
        <listitem><para>
            <emphasis role="bold">Non-overlapping</emphasis> - polygons do not overlap (their interiors do not intersect)
            </para></listitem>
        <listitem><para>
            <emphasis role="bold">Edge-Matched</emphasis> - vertices along shared edges are identical
            </para></listitem>
      </itemizedlist>

      <para>As a window function a value is returned for every input polygon.
      For polygons which violate one or more of the validity conditions the return value is a MULTILINESTRING containing the problematic edges.
      Coverage-valid polygons return the value NULL.
      Non-polygonal or empty geometries also produce NULL values.</para>

      <para>The conditions allow a valid coverage to contain holes (gaps between polygons),
      as long as the surrounding polygons are edge-matched.
      However, very narrow gaps are often undesirable.
      If the <parameter>tolerance</parameter> parameter is specified with a non-zero distance,
      edges forming narrower gaps will also be returned as invalid.
      </para>

      <para>The polygons being checked for coverage validity must also be valid geometries.
      This can be checked with <xref linkend="ST_IsValid"/>.
      </para>

      <para role="availability" conformance="3.4.0">Availability: 3.4.0</para>
      <para role="geos_requirement" conformance="3.12.0">Requires GEOS &gt;= 3.12.0</para>
    </refsection>

    <refsection>
      <title>Examples</title>

		<para>Invalid edges caused by overlap and non-matching vertices.</para>
      <programlisting>WITH coverage(id, geom) AS (VALUES
  (1, 'POLYGON ((10 190,30 160,40 110,100 70,120 10,10 10,10 190))'::geometry),
  (2, 'POLYGON ((100 190,10 190,30 160,40 110,50 80,74 110.5,100 130,140 120,140 160,100 190))'::geometry),
  (3, 'POLYGON ((140 190,190 190,190 80,140 80,140 190))'::geometry),
  (4, 'POLYGON ((180 40,120 10,100 70,140 80,190 80,180 40))'::geometry)
)
SELECT id, ST_CoverageInvalidEdges(geom) OVER ()
  FROM coverage;</programlisting>
<screen> id |               st_astext
----+---------------------------------------
  1 | LINESTRING (40 110, 100 70)
  2 | MULTILINESTRING ((100 130, 140 120, 140 160, 100 190), (40 110, 50 80, 74 110.5))
  3 | LINESTRING (140 80, 140 190)
  4 | null</screen>

      <para>This example tests the entire table for coverage validity.</para>
      <programlisting>
SELECT true = ALL (
    SELECT ST_CoverageInvalidEdges(geom) OVER () IS NULL
    FROM coverage
    );
      </programlisting>
    </refsection>

    <refsection>
      <title>See Also</title>
      <para>
        <xref linkend="ST_IsValid"/>,
        <xref linkend="ST_CoverageUnion"/>,
        <xref linkend="ST_CoverageClean"/>,
        <xref linkend="ST_CoverageSimplify"/>
      </para>
    </refsection>

  </refentry>

  <refentry xml:id="ST_CoverageClean">
    <refnamediv>
      <refname>ST_CoverageClean</refname>

      <refpurpose>Computes a clean (edge matched, non-overlapping, gap-cleared) polygonal coverage, given a non-clean input.</refpurpose>
    </refnamediv>

    <refsynopsisdiv>
      <funcsynopsis>
        <funcprototype>
          <funcdef>geometry <function>ST_CoverageClean</function></funcdef>
          <paramdef><type>geometry winset</type>
            <parameter>geom</parameter></paramdef>
          <paramdef choice="opt"><type>float8 </type>
            <parameter>gapMaximumWidth = 0</parameter></paramdef>
          <paramdef choice="opt"><type>float8 </type>
            <parameter>snappingDistance = -1</parameter></paramdef>
          <paramdef choice="opt"><type>text </type>
            <parameter>overlapMergeStrategy = 'MERGE_LONGEST_BORDER'</parameter></paramdef>
        </funcprototype>
      </funcsynopsis>
    </refsynopsisdiv>

    <refsection>
      <title>Description</title>

      <para>A window function which adjusts the edges of a set of valid polygonal geometries to produce a clean coverage.
      Cleaning involves:
      </para>
      <itemizedlist>
        <listitem><para>
            snapping vertices and edges to remove small discrepancies and ensure common edges are identically noded
            </para></listitem>
        <listitem><para>
            merging overlaps into a parent polygon
            </para></listitem>
        <listitem><para>
            merging narrow gaps into adjacent polygons
            </para></listitem>
      </itemizedlist>      
      <para><parameter>gapMaximumWidth</parameter> controls which gaps between polygons are merged. Gaps with width &lt;= this distance are merged into an adjacent polygon.</para>
      <para><parameter>snappingDistance</parameter> controls snapping of vertices and edges. The default (-1) automatically determines a snapping distance based on the input extent. Set to 0.0 to turn off snapping.</para>
      <para><parameter>overlapMergeStrategy</parameter> specifies how overlaps are merged into a parent polygon:</para>
      <itemizedlist>
        <listitem><para>
            <code>MERGE_LONGEST_BORDER</code> - merges into polygon with longest common border
            </para></listitem>
        <listitem><para>
            <code>MERGE_MAX_AREA</code> - merges into polygon with maximum area
            </para></listitem>
        <listitem><para>
            <code>MERGE_MIN_AREA</code> - merges into polygon with minimum area
            </para></listitem>
        <listitem><para>
            <code>MERGE_MIN_INDEX</code> - merges into polygon with smallest input index (defined by order of input polygons)
            </para></listitem>
      </itemizedlist>      
      <para>The result is a clean polygonal coverage that will pass validation by <xref linkend="ST_CoverageInvalidEdges"/>
      and can be input to coverage processing functions.
      </para>

      <note><para>To aid in determining a maximum gap width,
      gaps can be computed by cleaning with <code>gapMaximumWidth => 0</code> 
      and using <xref linkend="ST_CoverageUnion"/> to union the result coverage. 
      Holes in the union correspond to gaps in the original dataset.
      Gap widths can be measured by extracting the holes as polygons 
      and running <xref linkend="ST_MaximumInscribedCircle"/>
      on them; the gap width is twice the computed radius.
      </para></note>

      <para role="availability" conformance="3.6.0">Availability: 3.6.0 - requires GEOS &gt;= 3.14.0</para>
    </refsection>

    <refsection>
      <title>Examples</title>

      <para>Clean a coverage containing overlaps and narrow gaps, and compare the cleaned
      polygons with the original invalid edges.</para>
      <programlisting>WITH coverage(id, geom) AS (VALUES
  (1, 'POLYGON ((10 190,30 160,27 134.5,40 110,122 47,120 10,10 10,10 190))'::geometry),
  (2, 'POLYGON ((150 190,10 190,30 160,50 140,40 110,50 80,130 70,135 111,140 130,140 160,150 190))'::geometry),
  (3, 'POLYGON ((140 190,190 190,190 80,140 80,140 190))'::geometry),
  (4, 'POLYGON ((190 10,120 10,97 77,160 90,170 70,190 80,190 10))'::geometry)
), processed AS (
  SELECT id,
         ST_CoverageClean(geom, 1) OVER () AS cleaned,
         ST_CoverageInvalidEdges(geom) OVER () AS invalid_edges
  FROM coverage
)
SELECT ST_Collect(cleaned ORDER BY id) AS cleaned,
       ST_Collect(invalid_edges ORDER BY id) AS invalid_edges
FROM processed;</programlisting>
<screen role="visual-separate-output">MULTIPOLYGON(((10 10,10 190,30 160,27 134.5,40 110,84.7 75.7,102 62.3,120 10,10 10)),((140 190,140 160,140 130,135 111,131.7 84.2,97 77,98 74,84.7 75.7,40 110,50 140,30 160,10 190,140 190)),((190 190,190 80,165 80,140 80,140 85.9,140 130,140 160,140 190,150 190,190 190)),((190 10,120 10,102 62.3,98 74,97 77,131.7 84.2,140 85.9,140 80,165 80,170 70,190 80,190 10))) | MULTILINESTRING((40 110,122 47,120 10),(40 110,50 80,130 70,135 111,140 130,140 160,150 190,10 190),(190 80,140 80,140 190,190 190),(120 10,97 77,160 90,170 70))</screen>

    </refsection>

    <refsection>
      <title>See Also</title>
      <para>
        <xref linkend="ST_CoverageInvalidEdges"/>,
        <xref linkend="ST_CoverageUnion"/>,
        <xref linkend="ST_CoverageSimplify"/>,
        <xref linkend="ST_MaximumInscribedCircle"/>
      </para>
    </refsection>

  </refentry>

  <refentry xml:id="ST_CoverageSimplify">
    <refnamediv>
      <refname>ST_CoverageSimplify</refname>

      <refpurpose>Window function that simplifies the edges of a polygonal coverage.</refpurpose>
    </refnamediv>

    <refsynopsisdiv>
      <funcsynopsis>
        <funcprototype>
          <funcdef>geometry <function>ST_CoverageSimplify</function></funcdef>
          <paramdef><type>geometry winset </type>
            <parameter>geom</parameter></paramdef>
          <paramdef><type>float8 </type>
            <parameter>tolerance</parameter></paramdef>
          <paramdef choice="opt"><type>boolean </type>
            <parameter>simplifyBoundary = true</parameter></paramdef>
        </funcprototype>
      </funcsynopsis>
    </refsynopsisdiv>

    <refsection>
      <title>Description</title>

      <para>A window function which simplifies the edges of polygons in a polygonal coverage.
      The simplification preserves the coverage topology.
      This means the simplified output polygons are consistent along shared edges, and still form a valid coverage.
      </para>

      <para>The simplification uses a variant of the <link xlink:href="https://en.wikipedia.org/wiki/Visvalingam%E2%80%93Whyatt_algorithm">Visvalingam–Whyatt algorithm</link>.
      The <parameter>tolerance</parameter> parameter has units of distance,
      and is roughly equal to the square root of triangular areas to be simplified.
      </para>

      <para>To simplify only the "internal" edges of the coverage (those that are shared by two polygons) set the <parameter>simplifyBoundary</parameter> parameter to false.</para>

      <para>Use this function to simplify adjacent polygon layers when shared boundaries must remain
      edge-matched. For a single geometry where only self-intersection and ring validity matter, see
      <xref linkend="ST_SimplifyPreserveTopology"/>.</para>

      <note><para>If the input is not a valid coverage there may be unexpected artifacts in the output (such as boundary intersections, or separated boundaries which appeared to be shared).
      Use <xref linkend="ST_CoverageInvalidEdges"/> to determine if a coverage is valid.
      </para></note>

      <para role="availability" conformance="3.4.0">Availability: 3.4.0</para>
      <para role="geos_requirement" conformance="3.12.0">Requires GEOS &gt;= 3.12.0</para>
    </refsection>

    <refsection>
      <title>Examples</title>
		<para>Simplify a polygonal coverage while preserving shared boundaries.</para>
      <programlisting>WITH coverage(id, geom) AS (VALUES
  (1, 'POLYGON ((160 150,110 130,90 100,90 70,60 60,50 10,30 30,40 50,25 40,10 60,30 100,30 120,20 170,60 180,90 190,130 180,130 160,160 150),(40 160,50 140,66 125,60 100,80 140,90 170,60 160,40 160))'::geometry),
  (2, 'POLYGON ((40 160,60 160,90 170,80 140,60 100,66 125,50 140,40 160))'::geometry),
  (3, 'POLYGON ((110 130,160 50,140 50,120 33,90 30,50 10,60 60,90 70,90 100,110 130))'::geometry),
  (4, 'POLYGON ((160 150,150 120,160 90,160 50,110 130,160 150))'::geometry)
)
SELECT id, ST_CoverageSimplify(geom, 30) OVER ()
  FROM coverage;</programlisting>
<screen> id |               st_astext
----+---------------------------------------
  1 | POLYGON ((160 150, 110 130, 50 10, 10 60, 20 170, 90 190, 160 150), (40 160, 66 125, 90 170, 40 160))
  2 | POLYGON ((40 160, 66 125, 90 170, 40 160))
  3 | POLYGON ((110 130, 160 50, 50 10, 110 130))
  4 | POLYGON ((160 150, 160 50, 110 130, 160 150))</screen>
    </refsection>

    <refsection>
      <title>See Also</title>
      <para>
        <xref linkend="ST_CoverageInvalidEdges"/>,
        <xref linkend="ST_CoverageUnion"/>,
        <xref linkend="ST_CoverageClean"/>
      </para>
    </refsection>

  </refentry>

  <refentry xml:id="ST_CoverageEdges">
    <refnamediv>
      <refname>ST_CoverageEdges</refname>

      <refpurpose>Computes the unique edges of a polygonal coverage.</refpurpose>
    </refnamediv>

    <refsynopsisdiv>
      <funcsynopsis>
        <funcprototype>
          <funcdef>geometry <function>ST_CoverageEdges</function></funcdef>
          <paramdef><type>geometry </type>
            <parameter>geom</parameter></paramdef>
          <paramdef choice="opt"><type>integer </type>
            <parameter>edgetype = 0</parameter></paramdef>
        </funcprototype>
        <funcprototype>
          <funcdef>geometry <function>ST_CoverageEdges</function></funcdef>
          <paramdef><type>geometry[] </type>
            <parameter>geoms</parameter></paramdef>
          <paramdef choice="opt"><type>integer </type>
            <parameter>edgetype = 0</parameter></paramdef>
        </funcprototype>
      </funcsynopsis>
    </refsynopsisdiv>

    <refsection>
      <title>Description</title>

      <para>Returns a MultiLineString representing the unique edges of a polygonal coverage.
      A polygonal coverage is a set of non-overlapping polygons where adjacent polygons have matching vertices along shared edges.
      </para>
      <para>The <parameter>edgetype</parameter> parameter can be used to select which edges are returned:
        <itemizedlist>
          <listitem><para><emphasis role="bold">0 (ALL)</emphasis> - all unique edges (default)</para></listitem>
          <listitem><para><emphasis role="bold">1 (EXTERIOR)</emphasis> - only exterior edges (non-shared)</para></listitem>
          <listitem><para><emphasis role="bold">2 (INTERIOR)</emphasis> - only interior edges (shared)</para></listitem>
        </itemizedlist>
      </para>

      <para role="availability" conformance="3.7.0">Availability: 3.7.0</para>
      <para role="geos_requirement" conformance="3.15.0">Requires GEOS &gt;= 3.15.0</para>
    </refsection>

    <refsection>
      <title>Examples</title>
      <para>This example returns all unique edges of a coverage.</para>
      <programlisting language="sql">WITH coverage(geom) AS (
  VALUES (
    'GEOMETRYCOLLECTION(
      POLYGON((0 0,10 0,10 10,0 10,0 0)),
      POLYGON((10 0,20 0,20 10,10 10,10 0))
    )'::geometry
  )
)
SELECT geom AS input_coverage,
       ST_CoverageEdges(geom) AS all_edges
FROM coverage;</programlisting>
<screen role="visual-primary text-primary visual-output-only visual-overlay psql-expanded docbook-qa-ignore-wide-lines">-[ RECORD 1 ]--+----------------------------------------------------------------------------------------------
input_coverage | GEOMETRYCOLLECTION(POLYGON((0 0,10 0,10 10,0 10,0 0)),POLYGON((10 0,20 0,20 10,10 10,10 0)))
all_edges      | MULTILINESTRING((10 0,10 10),(10 10,0 10,0 0,10 0),(10 0,20 0,20 10,10 10))</screen>

      <para>This example returns only the interior shared edges of a coverage.</para>
      <programlisting language="sql">WITH coverage(geom) AS (
  VALUES (
    'GEOMETRYCOLLECTION(
      POLYGON((0 0,10 0,10 10,0 10,0 0)),
      POLYGON((10 0,20 0,20 10,10 10,10 0))
    )'::geometry
  )
)
SELECT geom AS input_coverage,
       ST_CoverageEdges(geom, 2) AS shared_edges
FROM coverage;</programlisting>
<screen role="visual-primary text-primary visual-output-only visual-overlay psql-expanded">-[ RECORD 1 ]--+----------------------------------------------------------------------------------------------
input_coverage | GEOMETRYCOLLECTION(POLYGON((0 0,10 0,10 10,0 10,0 0)),POLYGON((10 0,20 0,20 10,10 10,10 0)))
shared_edges   | MULTILINESTRING((10 0,10 10))</screen>
    </refsection>

    <refsection>
      <title>See Also</title>
      <para>
        <xref linkend="ST_CoverageInvalidEdges"/>,
        <xref linkend="ST_CoverageSimplify"/>,
        <xref linkend="ST_CoverageUnion"/>
      </para>
    </refsection>

  </refentry>

  <refentry xml:id="ST_CoverageUnion">
    <refnamediv>
      <refname>ST_CoverageUnion</refname>

      <refpurpose>Computes the union of a set of polygons forming a coverage by removing shared edges.</refpurpose>
    </refnamediv>

    <refsynopsisdiv>
      <funcsynopsis>
        <funcprototype>
          <funcdef>geometry <function>ST_CoverageUnion</function></funcdef>
          <paramdef><type>geometry set</type>
            <parameter>geom</parameter></paramdef>
        </funcprototype>
      </funcsynopsis>
    </refsynopsisdiv>

    <refsection>
      <title>Description</title>

      <para>An aggregate function which unions a set of polygons forming a polygonal coverage.
      The result is a polygonal geometry covering the same area as the coverage.
      This function produces the same result as <xref linkend="ST_Union"/>,
      but uses the coverage structure to compute the union much faster.
      </para>

      <note><para>If the input is not a valid coverage there may be unexpected artifacts in the output (such as unmerged or overlapping polygons).
            Use <xref linkend="ST_CoverageInvalidEdges"/> to determine if a coverage is valid.
      </para></note>

      <para role="availability" conformance="3.4.0">Availability: 3.4.0 - requires GEOS &gt;= 3.8.0</para>
    </refsection>

    <refsection>
      <title>Examples</title>
		<para>Union a polygonal coverage.</para>
      <programlisting>WITH coverage(id, geom) AS (VALUES
  (1, 'POLYGON ((10 10,10 150,80 190,110 150,90 110,40 110,50 60,10 10))'::geometry),
  (2, 'POLYGON ((120 10,10 10,50 60,100 70,120 10))'::geometry),
  (3, 'POLYGON ((140 80,120 10,100 70,40 110,90 110,110 150,140 80))'::geometry),
  (4, 'POLYGON ((140 190,120 170,140 130,160 150,140 190))'::geometry),
  (5, 'POLYGON ((180 160,170 140,140 130,160 150,140 190,180 160))'::geometry)
)
SELECT ST_CoverageUnion(geom) AS wkt
  FROM coverage;</programlisting>
<screen>MULTIPOLYGON(((10 150,80 190,110 150,140 80,120 10,10 10,10 150),(50 60,100 70,40 110,50 60)),((120 170,140 190,180 160,170 140,140 130,120 170)))</screen>
    </refsection>

    <refsection>
      <title>See Also</title>
      <para>
        <xref linkend="ST_CoverageInvalidEdges"/>,
        <xref linkend="ST_CoverageSimplify"/>,
        <xref linkend="ST_CoverageClean"/>,
        <xref linkend="ST_Union"/>
      </para>
    </refsection>

  </refentry>

</section>
