[postgis-tickets] r15059 - #3622, Signature updates to Voronoi functions
Daniel Baston
dbaston at gmail.com
Mon Sep 5 13:48:39 PDT 2016
Author: dbaston
Date: 2016-09-05 13:48:39 -0700 (Mon, 05 Sep 2016)
New Revision: 15059
Modified:
trunk/doc/reference_processing.xml
trunk/postgis/postgis.sql.in
trunk/regress/voronoi.sql
trunk/regress/voronoi_expected
Log:
#3622, Signature updates to Voronoi functions
Modified: trunk/doc/reference_processing.xml
===================================================================
--- trunk/doc/reference_processing.xml 2016-09-05 03:19:44 UTC (rev 15058)
+++ trunk/doc/reference_processing.xml 2016-09-05 20:48:39 UTC (rev 15059)
@@ -3627,32 +3627,121 @@
</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 >= 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">
<parameter>tolerance</parameter>
<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 @@
<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 @@
<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 @@
<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 @@
<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 @@
<para>
<xref linkend="ST_DelaunayTriangles" />,
+ <xref linkend="ST_VoronoiLines" />,
<xref linkend="ST_Collect" />
</para>
</refsection>
Modified: trunk/postgis/postgis.sql.in
===================================================================
--- trunk/postgis/postgis.sql.in 2016-09-05 03:19:44 UTC (rev 15058)
+++ trunk/postgis/postgis.sql.in 2016-09-05 20:48:39 UTC (rev 15059)
@@ -3653,8 +3653,9 @@
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 @@
-- 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
--------------------------------------------------------------------------------
Modified: trunk/regress/voronoi.sql
===================================================================
--- trunk/regress/voronoi.sql 2016-09-05 03:19:44 UTC (rev 15058)
+++ trunk/regress/voronoi.sql 2016-09-05 20:48:39 UTC (rev 15059)
@@ -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)')));
Modified: trunk/regress/voronoi_expected
===================================================================
--- trunk/regress/voronoi_expected 2016-09-05 03:19:44 UTC (rev 15058)
+++ trunk/regress/voronoi_expected 2016-09-05 20:48:39 UTC (rev 15059)
@@ -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
More information about the postgis-tickets
mailing list