[postgis-tickets] [SCM] PostGIS branch master updated. 3.1.0alpha3-26-g9abc7ea
git at osgeo.org
git at osgeo.org
Sun Dec 6 14:31:06 PST 2020
This is an automated email from the git hooks/post-receive script. It was
generated because a ref change was pushed to the repository containing
the project "PostGIS".
The branch, master has been updated
via 9abc7eabd179e61dce85b543f25a9a3f9de61cc7 (commit)
from 76427f6b01c37dd005659353d9c6474455842c6b (commit)
Those revisions listed above that are new to this repository have
not appeared on any other notification email; so we list those
revisions in full, below.
- Log -----------------------------------------------------------------
commit 9abc7eabd179e61dce85b543f25a9a3f9de61cc7
Author: Martin Davis <mtnclimb at gmail.com>
Date: Sun Dec 6 14:30:42 2020 -0800
Improve Doc Ref for overlay
diff --git a/doc/reference_overlay.xml b/doc/reference_overlay.xml
index 419eb60..67c57d9 100644
--- a/doc/reference_overlay.xml
+++ b/doc/reference_overlay.xml
@@ -64,8 +64,8 @@ SELECT ST_ClipByBox2D(the_geom, ST_MakeEnvelope(0,0,10,10)) FROM mytab;
<refnamediv>
<refname>ST_Difference</refname>
- <refpurpose>Returns a geometry that represents that part of geometry A
- that does not intersect with geometry B.</refpurpose>
+ <refpurpose>Returns a geometry representing the part of geometry A
+ that does not intersect geometry B.</refpurpose>
</refnamediv>
<refsynopsisdiv>
@@ -82,10 +82,13 @@ SELECT ST_ClipByBox2D(the_geom, ST_MakeEnvelope(0,0,10,10)) FROM mytab;
<refsection>
<title>Description</title>
- <para>Returns a geometry that represents that part of geometry A
- that does not intersect with geometry B. One can think of this as GeometryA - ST_Intersection(A,B). If A is completely contained in B
- then an empty geometry collection is returned.</para>
- <note><para>Order matters. B - A will always return a portion of B</para></note>
+ <para>Returns a geometry representing the part of geometry A
+ that does not intersect geometry B.
+ This is equivalent to <code>A - ST_Intersection(A,B)</code>.
+ If A is completely contained in B
+ then an empty geometry is returned.</para>
+ <note><para>This is the only overlay function where input order matters.
+ ST_Difference(A, B) always returns a portion of A.</para></note>
<para>
If the optional <code>gridSize</code> argument is provided, the inputs are
@@ -98,8 +101,8 @@ on that same grid. (Requires GEOS-3.9.0 or higher)
<para>&sfs_compliant; s2.1.1.3</para>
<para>&sqlmm_compliant; SQL-MM 3: 5.1.20</para>
- <para>&Z_support; However it seems to only consider x y when
- doing the difference and tacks back on the Z-Index</para>
+ <para>&Z_support; However, the result is computed using XY only.
+ The result Z values are copied, averaged or interpolated.</para>
</refsection>
<refsection>
@@ -173,7 +176,7 @@ MULTIPOINT(-118.6 38.329 6,-118.58 38.38 5)
<refname>ST_Intersection</refname>
<refpurpose>
-Returns a geometry that represents the shared portion of geomA and geomB.
+Returns a geometry representing the shared portion of geometries A and B.
</refpurpose>
</refnamediv>
<refsynopsisdiv>
@@ -208,7 +211,7 @@ Returns a geometry that represents the shared portion of geomA and geomB.
</refsynopsisdiv>
<refsection>
<title>Description</title>
- <para>Returns a geometry that represents the point-set
+ <para>Returns a geometry representing the point-set
intersection of two geometries.
In other words, that portion of geometry A and geometry B
that is shared between the two geometries.</para>
@@ -231,14 +234,16 @@ on that same grid. (Requires GEOS-3.9.0 or higher)
<warning><para>If working with 3D geometries, you may want to use SFGCAL based <xref linkend="ST_3DIntersection" /> which does a proper 3D intersection for 3D geometries. Although this function works with Z-coordinate, it does an averaging of Z-Coordinate.</para></warning>
- <para>Performed by the GEOS module</para>
+ <para>Performed by the GEOS module</para>
- <para>Enhanced: 3.1.0 accept a gridSize parameter - requires GEOS >= 3.9.0</para>
- <para>Changed: 3.0.0 does not depend on SFCGAL.</para>
- <para>Availability: 1.5 support for geography data type was introduced.</para>
+ <para>Enhanced: 3.1.0 accept a gridSize parameter - requires GEOS >= 3.9.0</para>
+ <para>Changed: 3.0.0 does not depend on SFCGAL.</para>
+ <para>Availability: 1.5 support for geography data type was introduced.</para>
- <para>&sfs_compliant; s2.1.1.3</para>
- <para>&sqlmm_compliant; SQL-MM 3: 5.1.18</para>
+ <para>&sfs_compliant; s2.1.1.3</para>
+ <para>&sqlmm_compliant; SQL-MM 3: 5.1.18</para>
+ <para>&Z_support; However, the result is computed using XY only.
+ The result Z values are copied, averaged or interpolated.</para>
</refsection>
<refsection>
<title>Examples</title>
@@ -302,7 +307,7 @@ from ST_GeomFromText('LINESTRING Z (2 2 6,1.5 1.5 7,1 1 8,0.5 0.5 8,0 0 10)') A
<refnamediv>
<refname>ST_MemUnion</refname>
- <refpurpose>Aggregate function which unions geometry in a slow but memory-friendly way</refpurpose>
+ <refpurpose>Aggregate function which unions geometry in a memory-efficent but slower way</refpurpose>
</refnamediv>
<refsynopsisdiv>
@@ -328,10 +333,12 @@ from ST_GeomFromText('LINESTRING Z (2 2 6,1.5 1.5 7,1 1 8,0.5 0.5 8,0 0 10)') A
<para>Produces the same result as <xref linkend="ST_Union" />, but uses less memory
and more processor time.
This aggregate function works by unioning the geometries incrementally, as opposed to
- the ST_Union aggregate which first creates an array and then unions</para>
+ the ST_Union aggregate which first accumulates an array and then unions the contents
+ using a fast algorithm.</para>
</note>
- <para>&Z_support;</para>
+ <para>&Z_support; However, the result is computed using XY only.
+ The result Z values are copied, averaged or interpolated.</para>
</refsection>
@@ -354,7 +361,7 @@ from ST_GeomFromText('LINESTRING Z (2 2 6,1.5 1.5 7,1 1 8,0.5 0.5 8,0 0 10)') A
<refname>ST_Node</refname>
<refpurpose>
-Nodes a set of lines.
+Nodes a collection of lines.
</refpurpose>
</refnamediv>
@@ -372,7 +379,7 @@ Nodes a set of lines.
<title>Description</title>
<para>
-Returns a (Multi)LineString representing the fully noded version of an input set of linestrings.
+Returns a (Multi)LineString representing the fully noded version of a collection of linestrings.
The noding preserves all of the input nodes,
and introduces the least possible number of new nodes.
The resulting linework is dissolved (duplicate lines are removed).
@@ -590,7 +597,7 @@ GEOMETRYCOLLECTION(
<refentry id="ST_Subdivide">
<refnamediv>
<refname>ST_Subdivide</refname>
- <refpurpose>Computes a rectilinear subdivision of a geometry with each part smaller than a given vertex count.</refpurpose>
+ <refpurpose>Computes a rectilinear subdivision of a geometry.</refpurpose>
</refnamediv>
<refsynopsisdiv>
@@ -608,8 +615,8 @@ GEOMETRYCOLLECTION(
<title>Description</title>
<para>
- Divides geometry into parts until a part can be represented using no more than <code>max_vertices</code>.
- Point-in-polygon and other overlay operations are normally faster for indexed subdivided dataset:
+ Divides geometry into parts using rectilinear lines, until each part can be represented using no more than <code>max_vertices</code>.
+ Point-in-polygon and other spatial operations are normally faster for indexed subdivided dataset:
"miss" cases are faster to check as boxes for all parts typically cover smaller area than original geometry box,
"hit" cases are faster because recheck operates on less points.
<code>max_vertices</code> must be 5 or more, as 5 points are needed to represent a closed box.
@@ -704,7 +711,7 @@ LINESTRING(44.7994523421035 82.5156766227011,85 85)</screen>
<refnamediv>
<refname>ST_SymDifference</refname>
- <refpurpose>Returns a geometry that represents the portions of A and B
+ <refpurpose>Returns a geometry representing the portions of geometries A and B
that do not intersect.</refpurpose>
</refnamediv>
@@ -722,9 +729,10 @@ LINESTRING(44.7994523421035 82.5156766227011,85 85)</screen>
<refsection>
<title>Description</title>
- <para>Returns a geometry that represents the portions of A and B
- that do not intersect. It is called a symmetric difference because
- ST_SymDifference(A,B) = ST_SymDifference(B,A). One can think of this as ST_Union(geomA,geomB) - ST_Intersection(A,B).
+ <para>Returns a geometry representing the portions of geonetries A and B
+ that do not intersect.
+ This is equivalent to <code>ST_Union(A,B) - ST_Intersection(A,B)</code>.
+ It is called a symmetric difference because <code>ST_SymDifference(A,B) = ST_SymDifference(B,A)</code>.
</para>
<para>
@@ -739,8 +747,8 @@ on that same grid. (Requires GEOS-3.9.0 or higher)
<para>&sfs_compliant; s2.1.1.3</para>
<para>&sqlmm_compliant; SQL-MM 3: 5.1.21</para>
- <para>&Z_support; However it seems to only consider x y when
- doing the difference and tacks back on the Z-Index</para>
+ <para>&Z_support; However, the result is computed using XY only.
+ The result Z values are copied, averaged or interpolated.</para>
</refsection>
@@ -817,7 +825,7 @@ MULTILINESTRING((1 3 2.75,1 4 2),(1 1 3,1 2 2.25))
<refentry id="ST_Union">
<refnamediv>
<refname>ST_Union</refname>
- <refpurpose>Returns a geometry that represents the point-set union of
+ <refpurpose>Returns a geometry representing the point-set union of
the input geometries.</refpurpose>
</refnamediv>
@@ -842,6 +850,11 @@ MULTILINESTRING((1 3 2.75,1 4 2),(1 1 3,1 2 2.25))
<funcdef>geometry <function>ST_Union</function></funcdef>
<paramdef><type>geometry set</type> <parameter>g1field</parameter></paramdef>
</funcprototype>
+ <funcprototype>
+ <funcdef>geometry <function>ST_Union</function></funcdef>
+ <paramdef><type>geometry set</type> <parameter>g1field</parameter></paramdef>
+ <paramdef><type>float8</type> <parameter>gridSize</parameter></paramdef>
+ </funcprototype>
</funcsynopsis>
</refsynopsisdiv>
@@ -850,35 +863,42 @@ MULTILINESTRING((1 3 2.75,1 4 2),(1 1 3,1 2 2.25))
<para>Unions the input geometries, merging geometry to produce a result geometry
with no overlaps.
The output may be a single geometry, a MultiGeometry, or a Geometry Collection.
- Comes in 2 variants. Variant 1 unions 2 geometries.
- Variant 2 is an aggregate function that unions a set of geometries.</para>
+ Comes in several variants:</para>
- <para><emphasis role="bold">Non-Aggregate variants:</emphasis>
+ <para><emphasis role="bold">Two-input variant:</emphasis>
returns a geometry that is the union of two input geometries.
- If either input is NULL, then NULL is returned.</para>
+ If either input is NULL, then NULL is returned.
+ </para>
- <para>The <code>gridSize</code> can be specified to work in fixed-precision space.
- The inputs are snapped to a grid of the given size, and the result vertices are computed
- on that same grid.
- (Requires GEOS-3.9.0 or higher)
+ <para><emphasis role="bold">Array variant:</emphasis>
+ returns a geometry that is the union of an array of geometries.
</para>
<para><emphasis role="bold">Aggregate variant:</emphasis>
- returns a geometry that is the union of a set of geometries.
+ returns a geometry that is the union of a rowset of geometries.
The ST_Union() function is an "aggregate"
function in the terminology of PostgreSQL. That means that it
operates on rows of data, in the same way the SUM() and AVG()
functions do and like most aggregates, it also ignores NULL geometries.</para>
+ <para>See also <xref linkend="ST_UnaryUnion" /> for a non-aggregate, single-input variant.</para>
+
+ <para>The ST_Union array and set variants use the fast Cascaded Union algorithm described in <ulink
+ url="http://blog.cleverelephant.ca/2009/01/must-faster-unions-in-postgis-14.html">http://blog.cleverelephant.ca/2009/01/must-faster-unions-in-postgis-14.html</ulink>
+ </para>
+
+ <para>A <code>gridSize</code> can be specified to work in fixed-precision space.
+ The inputs are snapped to a grid of the given size, and the result vertices are computed
+ on that same grid.
+ (Requires GEOS-3.9.0 or higher)
+ </para>
+
<note><para><xref linkend="ST_Collect" /> may sometimes be used in place of ST_Union,
if the result is not required to be non-overlapping.
ST_Collect is usually faster than ST_Union because it performs no processing
on the collected geometries.
</para></note>
- <para>ST_Union uses the fast Cascaded Union algorithm described in <ulink
- url="http://blog.cleverelephant.ca/2009/01/must-faster-unions-in-postgis-14.html">http://blog.cleverelephant.ca/2009/01/must-faster-unions-in-postgis-14.html</ulink></para>
-
<para>Performed by the GEOS module.</para>
<para>NOTE: this function was formerly called GeomUnion(), which
was renamed from "Union" because UNION is an SQL reserved
@@ -892,6 +912,8 @@ MULTILINESTRING((1 3 2.75,1 4 2),(1 1 3,1 2 2.25))
<note><para>Aggregate version is not explicitly defined in OGC SPEC.</para></note>
<para>&sqlmm_compliant; SQL-MM 3: 5.1.19
the z-index (elevation) when polygons are involved.</para>
+ <para>&Z_support; However, the result is computed using XY only.
+ The result Z values are copied, averaged or interpolated.</para>
</refsection>
<refsection>
@@ -975,7 +997,7 @@ MULTILINESTRING((3 4,4 5),(1 2,3 4))
<refnamediv>
<refname>ST_UnaryUnion</refname>
- <refpurpose>Like ST_Union, but working at the geometry component level.</refpurpose>
+ <refpurpose>Computes the union of the components of a single geometry.</refpurpose>
</refnamediv>
<refsynopsisdiv>
@@ -993,21 +1015,25 @@ MULTILINESTRING((3 4,4 5),(1 2,3 4))
<title>Description</title>
<para>
- Unlike ST_Union, ST_UnaryUnion dissolves boundaries
- between components of a multipolygon (invalid)
- and performs union between the components of a
- geometrycollection.
- Each component of the input geometry is assumed to be
- valid, so you won't get a valid multipolygon out of a
- bow-tie polygon (invalid).
+ A single-input variant of <xref linkend="ST_Union" />.
+ The input may be a single geometry, a MultiGeometry, or a GeometryCollection.
+ The union is applied to the individual components of the input.
+ This allow using this function to fix MultiPolygons which are
+ invalid due to overlapping components.
+ (However, the input components must each be valid.
+ An invalid input component such as a bow-tie polygon may cause an error.)
+ </para>
+
+ <para>
+ Another use of this function is to node and dissolve a collection of linestrings.
+ (This can also be done with <xref linkend="ST_Node" />.)
</para>
<para>
- You may use this function to node a set of linestrings.
- You may mix ST_UnaryUnion with ST_Collect to fine-tune
- how many geometries at once you want to dissolve to
- be nice on both memory size and CPU time, finding the
- balance between ST_Union and ST_MemUnion.
+ It is possible to mix ST_UnaryUnion with <xref linkend="ST_Collect" /> to fine-tune
+ how many geometries are be unioned at once.
+ This allows trading off between memory usage and compute time,
+ striking a balance between ST_Union and <xref linkend="ST_MemUnion" />.
</para>
<para>
@@ -1016,7 +1042,8 @@ snapped to a grid of the given size, and the result vertices are computed
on that same grid. (Requires GEOS-3.9.0 or higher)
</para>
- <para>&Z_support;</para>
+ <para>&Z_support; However, the result is computed using XY only.
+ The result Z values are copied, averaged or interpolated.</para>
<para>Enhanced: 3.1.0 accept a gridSize parameter - requires GEOS >= 3.9.0</para>
<para>Availability: 2.0.0</para>
-----------------------------------------------------------------------
Summary of changes:
doc/reference_overlay.xml | 141 +++++++++++++++++++++++++++-------------------
1 file changed, 84 insertions(+), 57 deletions(-)
hooks/post-receive
--
PostGIS
More information about the postgis-tickets
mailing list