#3622, Signature updates to Voronoi functions

git-svn-id: http://svn.osgeo.org/postgis/trunk@15059 b70326c6-7e19-0410-871a-916f4a2858ee

diff --git a/doc/reference_processing.xml b/doc/reference_processing.xml
index abc593f190dba0fa3175ff46e942d3856986d08a..2b27710f00c65e666661c20533fe2d361ae31e31 100644 (file)
--- a/doc/reference_processing.xml
+++ b/doc/reference_processing.xml
@@ -3627,23 +3627,112 @@ MULTILINESTRING((3 4,4 5),(1 2,3 4))
          </refsection>
        </refentry>
 
-       <refentry id="ST_Voronoi">
+       <refentry id="ST_VoronoiLines">
          <refnamediv>
-               <refname>ST_Voronoi</refname>
+               <refname>ST_VoronoiLines</refname>
 
-               <refpurpose>Computes a Voronoi diagram from the vertices of a geometry.</refpurpose>
+               <refpurpose>Returns the boundaries between the cells of the Voronoi diagram constructed from the vertices of a geometry.</refpurpose>
          </refnamediv>
 
          <refsynopsisdiv>
                <funcsynopsis>
                  <funcprototype>
-                       <funcdef>geometry <function>ST_Voronoi</function></funcdef>
+                       <funcdef>geometry <function>ST_VoronoiLines</function></funcdef>
                        <paramdef>
                                <parameter>g1</parameter>
                                <type>geometry</type>
                        </paramdef>
                        <paramdef choice="opt">
-                               <parameter>clip</parameter>
+                               <parameter>tolerance</parameter>
+                               <type>float8</type>
+                       </paramdef>
+                       <paramdef choice="opt">
+                               <parameter>extend_to</parameter>
+                               <type>geometry</type>
+                       </paramdef>
+                 </funcprototype>
+
+               </funcsynopsis>
+         </refsynopsisdiv>
+
+         <refsection>
+               <title>Description</title>
+
+               <para>
+                       ST_VoronoiLines computes a two-dimensional <ulink url="https://en.wikipedia.org/wiki/Voronoi_diagram">Voronoi diagram</ulink> from the vertices of
+            the supplied geometry and returns the boundaries between cells in that diagram as a MultiLineString.
+        </para>
+
+               <para>
+                       Optional parameters:
+               <itemizedlist>
+                       <listitem>
+                <para> 'tolerance' : The distance within which vertices will be considered equivalent.  Robustness of the algorithm can be improved by supplying a nonzero tolerance distance.  (default = 0.0)</para>
+                       </listitem>
+                       <listitem>
+                               <para>'extend_to' : If a geometry is supplied as the "extend_to" parameter, the diagram will be extended to cover the
+                                       envelope of the "extend_to" geometry, unless that envelope is smaller than the default envelope.
+                                       (default = NULL)</para>
+                       </listitem>
+               </itemizedlist>
+               </para>
+
+               <para>Availability: 2.3.0 - requires GEOS &gt;= 3.5.0.</para>
+         </refsection>
+
+         <!-- Examples -->
+         <refsection>
+               <title>Examples</title>
+               <informaltable>
+                 <tgroup cols="1">
+                       <tbody>
+                        <row>
+                               <entry><para><informalfigure>
+                                       <mediaobject>
+                                         <imageobject>
+                                               <imagedata fileref="images/st_voronoi03.png" />
+                                         </imageobject>
+                                         <caption><para>Voronoi lines with tolerance of 30 units</para></caption>
+                                       </mediaobject>
+                                 </informalfigure>
+                                       <programlisting>SELECT ST_VoronoiLines(geom, 30) As geom
+FROM (SELECT 'MULTIPOINT (50 30, 60 30, 100 100,10 150, 110 120)'::geometry As geom ) As g</programlisting>
+<screen> -- ST_AsText output
+MULTILINESTRING((135.555555555556 270,36.8181818181818 92.2727272727273),(36.8181818181818 92.2727272727273,-110 43.3333333333333),(230 -45.7142857142858,36.8181818181818 92.2727272727273))
+</screen>
+                               </para></entry>
+                         </row>
+               </tbody>
+               </tgroup>
+               </informaltable>
+
+         </refsection>
+
+         <!-- Optionally add a "See Also" section -->
+         <refsection>
+               <title>See Also</title>
+
+               <para>
+                       <xref linkend="ST_DelaunayTriangles" />,
+                       <xref linkend="ST_VoronoiPolygons" />,
+                       <xref linkend="ST_Collect" />
+               </para>
+         </refsection>
+       </refentry>
+
+       <refentry id="ST_VoronoiPolygons">
+         <refnamediv>
+               <refname>ST_VoronoiPolygons</refname>
+
+               <refpurpose>Returns the cells of the Voronoi diagram constructed from the vertices of a geometry.</refpurpose>
+         </refnamediv>
+
+         <refsynopsisdiv>
+               <funcsynopsis>
+                 <funcprototype>
+                       <funcdef>geometry <function>ST_VoronoiPolygons</function></funcdef>
+                       <paramdef>
+                               <parameter>g1</parameter>
                                <type>geometry</type>
                        </paramdef>
                        <paramdef choice="opt">
@@ -3651,8 +3740,8 @@ MULTILINESTRING((3 4,4 5),(1 2,3 4))
                                <type>float8</type>
                        </paramdef>
                        <paramdef choice="opt">
-                               <parameter>return_polygons</parameter>
-                               <type>boolean</type>
+                               <parameter>extend_to</parameter>
+                               <type>geometry</type>
                        </paramdef>
                  </funcprototype>
 
@@ -3663,24 +3752,20 @@ MULTILINESTRING((3 4,4 5),(1 2,3 4))
                <title>Description</title>
 
                <para>
-                       ST_Voronoi computes a two-dimensional <ulink url="https://en.wikipedia.org/wiki/Voronoi_diagram">Voronoi diagram</ulink> from the vertices of
-                       the supplied geometry.  By default, the result will be a GeometryCollection of
-                       Polygons that covers an envelope larger than the extent of the input vertices.
+                       ST_VoronoiPolygons computes a two-dimensional <ulink url="https://en.wikipedia.org/wiki/Voronoi_diagram">Voronoi diagram</ulink> from the vertices of
+                       the supplied geometry.  The result is a GeometryCollection of Polygons that covers an envelope larger than the extent of the input vertices.
                </para>
 
                <para>
                        Optional parameters:
                <itemizedlist>
-                       <listitem>
-                               <para>'clip' : If a geometry is supplied as the "clip" parameter, the diagram will be extended to cover the
-                                       envelope of the "clip" geometry, unless that envelope is smaller than the default envelope.
-                                       (default = NULL)</para>
-                       </listitem>
                        <listitem>
                        <para>'tolerance' : The distance within which vertices will be considered equivalent.  Robustness of the algorithm can be improved by supplying a nonzero tolerance distance.  (default = 0.0)</para>
                        </listitem>
                        <listitem>
-                       <para>'return_polygons' : if true, the result of ST_Voronoi will be a GeometryCollection of Polygons.  If false, the result will be a MultiLineString. (default = true)</para>
+                               <para>'extend_to' : If a geometry is supplied as the "extend_to" parameter, the diagram will be extended to cover the
+                                       envelope of the "extend_to" geometry, unless that envelope is smaller than the default envelope.
+                                       (default = NULL)</para>
                        </listitem>
                </itemizedlist>
                </para>
@@ -3701,11 +3786,11 @@ MULTILINESTRING((3 4,4 5),(1 2,3 4))
                                          <imageobject>
                                                <imagedata fileref="images/st_voronoi01.png" />
                                          </imageobject>
-                                         <caption><para>Points overlaid on top of voronoi diagram</para></caption>
+                                         <caption><para>Points overlaid on top of Voronoi diagram</para></caption>
                                        </mediaobject>
                                        </informalfigure>
                                        <programlisting>SELECT
-       ST_Voronoi(geom) As geom
+       ST_VoronoiPolygons(geom) As geom
 FROM (SELECT 'MULTIPOINT (50 30, 60 30, 100 100,10 150, 110 120)'::geometry As geom ) As g;</programlisting>
 <screen> -- ST_AsText output
 GEOMETRYCOLLECTION(POLYGON((-110 43.3333333333333,-110 270,100.5 270,59.3478260869565 132.826086956522,36.8181818181818 92.2727272727273,-110 43.3333333333333)),
@@ -3725,7 +3810,7 @@ POLYGON((100.5 270,230 270,230 47.5,59.3478260869565 132.826086956522,100.5 270)
                                          <caption><para>Voronoi with tolerance of 30 units</para></caption>
                                        </mediaobject>
                                  </informalfigure>
-                                       <programlisting>SELECT ST_Voronoi(geom, null,30) As geom
+                                       <programlisting>SELECT ST_VoronoiPolygons(geom, 30) As geom
 FROM (SELECT 'MULTIPOINT (50 30, 60 30, 100 100,10 150, 110 120)'::geometry As geom ) As g;</programlisting>
 <screen> -- ST_AsText output
 GEOMETRYCOLLECTION(POLYGON((-110 43.3333333333333,-110 270,100.5 270,59.3478260869565 132.826086956522,36.8181818181818 92.2727272727273,-110 43.3333333333333)),
@@ -3740,10 +3825,10 @@ POLYGON((100.5 270,230 270,230 47.5,59.3478260869565 132.826086956522,100.5 270)
                                          <imageobject>
                                                <imagedata fileref="images/st_voronoi03.png" />
                                          </imageobject>
-                                         <caption><para>Voronoi with tolerance of 30 units as multilinestring</para></caption>
+                                         <caption><para>Voronoi with tolerance of 30 units as MultiLineString</para></caption>
                                        </mediaobject>
                                  </informalfigure>
-                                       <programlisting>SELECT ST_Voronoi(geom, null,30,false) As geom
+                                       <programlisting>SELECT ST_VoronoiLines(geom, 30) As geom
 FROM (SELECT 'MULTIPOINT (50 30, 60 30, 100 100,10 150, 110 120)'::geometry As geom ) As g</programlisting>
 <screen> -- ST_AsText output
 MULTILINESTRING((135.555555555556 270,36.8181818181818 92.2727272727273),(36.8181818181818 92.2727272727273,-110 43.3333333333333),(230 -45.7142857142858,36.8181818181818 92.2727272727273))
@@ -3762,6 +3847,7 @@ MULTILINESTRING((135.555555555556 270,36.8181818181818 92.2727272727273),(36.818
 
                <para>
                        <xref linkend="ST_DelaunayTriangles" />,
+                       <xref linkend="ST_VoronoiLines" />,
                        <xref linkend="ST_Collect" />
                </para>
          </refsection>

diff --git a/postgis/postgis.sql.in b/postgis/postgis.sql.in
index 708a46fbe5bf678691288d2854ae8f2e92db4c47..1466cf85e29dd0df2ad9ece3137993b095c18b7b 100644 (file)
--- a/postgis/postgis.sql.in
+++ b/postgis/postgis.sql.in
@@ -3653,8 +3653,9 @@ CREATE OR REPLACE FUNCTION ST_DelaunayTriangles(g1 geometry, tolerance float8 DE
        LANGUAGE 'c' IMMUTABLE STRICT _PARALLEL
        COST 25000;
 
+
 --------------------------------------------------------------------------------
--- ST_Voronoi
+-- _ST_Voronoi
 --------------------------------------------------------------------------------
 
 -- ST_Voronoi(g1 geometry, clip geometry, tolerance float8, return_polygons boolean)
@@ -3677,13 +3678,26 @@ CREATE OR REPLACE FUNCTION ST_DelaunayTriangles(g1 geometry, tolerance float8 DE
 -- Availability: 2.3.0
 -- Requires GEOS >= 3.5.0
 --
-CREATE OR REPLACE FUNCTION ST_Voronoi(g1 geometry, clip geometry DEFAULT NULL, tolerance float8 DEFAULT 0.0, return_polygons boolean DEFAULT true)
+
+CREATE OR REPLACE FUNCTION _ST_Voronoi(g1 geometry, clip geometry DEFAULT NULL, tolerance float8 DEFAULT 0.0, return_polygons boolean DEFAULT true)
        RETURNS geometry
        AS 'MODULE_PATHNAME', 'ST_Voronoi'
        LANGUAGE 'c' IMMUTABLE _PARALLEL
        COST 25000; -- Guessed cost
 
 
+CREATE OR REPLACE FUNCTION ST_VoronoiPolygons(g1 geometry, tolerance float8 DEFAULT 0.0, extend_to geometry DEFAULT NULL)
+       RETURNS geometry
+       AS $$ SELECT _ST_Voronoi(g1, extend_to, tolerance, true) $$
+       LANGUAGE SQL IMMUTABLE _PARALLEL
+       COST 25000; -- Guessed cost
+
+CREATE OR REPLACE FUNCTION ST_VoronoiLines(g1 geometry, tolerance float8 DEFAULT 0.0, extend_to geometry DEFAULT NULL)
+       RETURNS geometry
+       AS $$ SELECT _ST_Voronoi(g1, extend_to, tolerance, false) $$
+       LANGUAGE SQL IMMUTABLE _PARALLEL
+       COST 25000; -- Guessed cost
+
 --------------------------------------------------------------------------------
 -- Aggregates and their supporting functions
 --------------------------------------------------------------------------------

diff --git a/regress/voronoi.sql b/regress/voronoi.sql
index 61cee074bbf4913891462dd404f8c623a4a56185..b961bc65043c32171a60dd3c61dbc20ff6a936d4 100644 (file)
--- a/regress/voronoi.sql
+++ b/regress/voronoi.sql
@@ -1,17 +1,15 @@
 -- postgres
 
 -- SRID is preserved
-SELECT 1,  32145 = ST_SRID(ST_Voronoi('SRID=32145;MULTIPOINT (0 0, 1 1, 2 2)'));
+SELECT 1,  32145 = ST_SRID(ST_VoronoiPolygons('SRID=32145;MULTIPOINT (0 0, 1 1, 2 2)'));
 -- NULL -> NULL
-SELECT 2,  ST_Voronoi(NULL) IS NULL;
+SELECT 2,  ST_VoronoiPolygons(NULL) IS NULL;
 -- NULL tolerance produces error
-SELECT 3,  ST_Voronoi('MULTIPOINT (0 0, 1 1, 2 2)', NULL, NULL);
--- NULL return_polygons produces error
-SELECT 4,  ST_Voronoi('MULTIPOINT (0 0, 1 1, 2 2)', NULL, 0, NULL);
+SELECT 3,  ST_VoronoiPolygons('MULTIPOINT (0 0, 1 1, 2 2)', NULL);
 -- Tolerance can't be negative
-SELECT 5,  ST_Voronoi('MULTIPOINT (0 0, 1 1, 2 2)', NULL, -2);
+SELECT 5,  ST_VoronoiPolygons('MULTIPOINT (0 0, 1 1, 2 2)', -2);
 -- Output types are correct
-SELECT 6,  GeometryType(ST_Voronoi('MULTIPOINT (0 0, 1 1, 2 2)')) = 'GEOMETRYCOLLECTION';
-SELECT 7,  GeometryType(ST_Voronoi('MULTIPOINT (0 0, 1 1, 2 2)', NULL, 0, false)) = 'MULTILINESTRING';
+SELECT 6,  GeometryType(ST_VoronoiPolygons('MULTIPOINT (0 0, 1 1, 2 2)')) = 'GEOMETRYCOLLECTION';
+SELECT 7,  GeometryType(ST_VoronoiLines('MULTIPOINT (0 0, 1 1, 2 2)')) = 'MULTILINESTRING';
 -- Clipping extent is handled correctly
-SELECT 8,  ST_Equals(ST_Envelope('LINESTRING (-20 -10, 10 10)'::geometry), ST_Envelope(ST_Voronoi('MULTIPOINT (0 0, 1 1, 2 2)', 'MULTIPOINT (-20 -10, 10 10)')));
+SELECT 8,  ST_Equals(ST_Envelope('LINESTRING (-20 -10, 10 10)'::geometry), ST_Envelope(ST_VoronoiPolygons('MULTIPOINT (0 0, 1 1, 2 2)', 0.0, 'MULTIPOINT (-20 -10, 10 10)')));

diff --git a/regress/voronoi_expected b/regress/voronoi_expected
index ca57deaaed23739d46dc8a48f3d3d602eebd8f7f..08a9a86a47b5104cb2a2f6255f6859410272b072 100644 (file)
--- a/regress/voronoi_expected
+++ b/regress/voronoi_expected
@@ -1,7 +1,6 @@
 1|t
 2|t
 ERROR:  Tolerance must be a positive number.
-ERROR:  return_polygons must be true or false.
 ERROR:  Tolerance must be a positive number.
 6|t
 7|t