[postgis-tickets] [SCM] PostGIS branch master updated. 3.1.0rc1-172-g7e03bb1
git at osgeo.org
git at osgeo.org
Fri Apr 30 09:32:27 PDT 2021
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 7e03bb102c46f4b55c7bdaac17f939edd05e333e (commit)
from 28bd4bbcffb08c9098e2ecc6b8f17b8945ffec31 (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 7e03bb102c46f4b55c7bdaac17f939edd05e333e
Author: Martin Davis <mtnclimb at gmail.com>
Date: Fri Apr 30 09:35:29 2021 -0700
Improve doc overlay functions
diff --git a/doc/reference_overlay.xml b/doc/reference_overlay.xml
index 928b7df..f535d13 100644
--- a/doc/reference_overlay.xml
+++ b/doc/reference_overlay.xml
@@ -14,7 +14,7 @@
<refentry id="ST_ClipByBox2D">
<refnamediv>
<refname>ST_ClipByBox2D</refname>
- <refpurpose>Returns the portion of a geometry falling within a rectangle.</refpurpose>
+ <refpurpose>Computes the portion of a geometry falling within a rectangle.</refpurpose>
</refnamediv>
<refsynopsisdiv>
@@ -64,7 +64,7 @@ SELECT ST_ClipByBox2D(the_geom, ST_MakeEnvelope(0,0,10,10)) FROM mytab;
<refnamediv>
<refname>ST_Difference</refname>
- <refpurpose>Returns a geometry representing the part of geometry A
+ <refpurpose>Computes a geometry representing the part of geometry A
that does not intersect geometry B.</refpurpose>
</refnamediv>
@@ -86,7 +86,7 @@ SELECT ST_ClipByBox2D(the_geom, ST_MakeEnvelope(0,0,10,10)) FROM mytab;
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>
+ then an empty atomic geometry of appropriate type 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>
@@ -176,7 +176,7 @@ MULTIPOINT(-118.6 38.329 6,-118.58 38.38 5)
<refname>ST_Intersection</refname>
<refpurpose>
-Returns a geometry representing the shared portion of geometries A and B.
+Computes a geometry representing the shared portion of geometries A and B.
</refpurpose>
</refnamediv>
<refsynopsisdiv>
@@ -216,10 +216,8 @@ Returns a geometry representing the shared portion of geometries A and B.
In other words, that portion of geometry A and geometry B
that is shared between the two geometries.</para>
- <para>If the geometries do not share any space (are disjoint), then an empty geometry collection
- is returned.</para>
- <para>ST_Intersection in conjunction with ST_Intersects is very useful for clipping geometries such as in bounding box, buffer, region
- queries where you only want to return that portion of a geometry that sits in a country or region of interest.</para>
+ <para>If the geometries have no points in common (i.e. are disjoint)
+ then an empty atomic geometry of appropriate type is returned.</para>
<para>
If the optional <code>gridSize</code> argument is provided, the inputs are
@@ -227,6 +225,9 @@ 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>ST_Intersection in conjunction with <xref linkend="ST_Intersects"/> is useful for clipping geometries such as in bounding box, buffer, or region
+ queries where you only require the portion of a geometry that is inside a country or region of interest.</para>
+
<note><para>Geography: For geography this is really a thin wrapper around the geometry implementation. It first determines the best SRID that
fits the bounding box of the 2 geography objects (if geography objects are within one half zone UTM but not same UTM will pick one of those) (favoring UTM or Lambert Azimuthal Equal Area (LAEA) north/south pole, and falling back on mercator in worst case scenario) and then intersection in that best fit planar spatial ref and retransforms back to WGS84 geography.</para></note>
@@ -307,7 +308,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 memory-efficent but slower way</refpurpose>
+ <refpurpose>Aggregate function which unions geometries in a memory-efficent but slower way</refpurpose>
</refnamediv>
<refsynopsisdiv>
@@ -323,12 +324,11 @@ 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
<refsection>
<title>Description</title>
- <para>Unions the input geometries, merging geometry to produce a result geometry
+ <para>An aggregate function that unions the input geometries, merging them to produce a result geometry
with no overlaps.
The output may be a single geometry, a MultiGeometry, or a Geometry Collection.
</para>
- <!-- optionally mention that this function uses indexes if appropriate -->
<note>
<para>Produces the same result as <xref linkend="ST_Union" />, but uses less memory
and more processor time.
@@ -345,7 +345,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
<refsection>
<title>Examples</title>
- <programlisting>See ST_Union</programlisting>
+ <programlisting>
+SELECT id,
+ ST_MemUnion(geom) as singlegeom
+FROM sometable f
+GROUP BY id;
+</programlisting>
</refsection>
<!-- Optionally add a "See Also" section -->
@@ -450,15 +455,15 @@ MULTILINESTRING((2 5,2 3),(2 3,2 1,4 1),(4 1,2 3),(4 1,6 1),(6 1,7 1))
<refsection>
<title>Description</title>
<para>
- The function supports splitting a line by a (multi)point, (multi)line or (multi)polygon boundary,
- or a (multi)polygon by line.
- The returned geometry is always a collection.
+ The function supports splitting a LineString by a (Multi)Point, (Multi)LineString or (Multi)Polygon boundary,
+ or a (Multi)Polygon by a LineString.
+ The result geometry is always a collection.
</para>
<para>
- Think of this function as the opposite of ST_Union.
- Theoretically applying ST_Union to the elements of the returned collection
- should always yield the original geometry.
+ This function is in a sense the opposite of <xref linkend="ST_Union" />.
+ Applying ST_Union to the returned collection should theoretically yield the original geometry
+ (although due to numerical rounding this may not be exactly the case).
</para>
<para>Availability: 2.0.0 requires GEOS</para>
@@ -468,8 +473,8 @@ MULTILINESTRING((2 5,2 3),(2 3,2 1,4 1),(4 1,2 3),(4 1,6 1),(6 1,7 1))
<note><para>To improve the robustness of ST_Split it may be convenient to <xref linkend="ST_Snap"/> the input to the blade in advance using a very low tolerance. Otherwise the internally used coordinate grid may cause tolerance problems, where coordinates of input and blade do not fall onto each other and the input is not being split correctly (see <ulink url="http://trac.osgeo.org/postgis/ticket/2192">#2192</ulink>).</para></note>
<note><para>
-When a (multi)polygon is passed as as the blade, its linear component
-(the boundary) is used for cutting the input.
+When a (Multi)Polygon is passed as as the blade, its linear components
+(the boundary) are used for cutting the input.
</para></note>
</refsection>
@@ -711,7 +716,7 @@ LINESTRING(44.7994523421035 82.5156766227011,85 85)</screen>
<refnamediv>
<refname>ST_SymDifference</refname>
- <refpurpose>Returns a geometry representing the portions of geometries A and B
+ <refpurpose>Computes a geometry representing the portions of geometries A and B
that do not intersect.</refpurpose>
</refnamediv>
@@ -821,11 +826,80 @@ MULTILINESTRING((1 3 2.75,1 4 2),(1 1 3,1 2 2.25))
</refsection>
</refentry>
+ <refentry id="ST_UnaryUnion">
+ <refnamediv>
+ <refname>ST_UnaryUnion</refname>
+
+ <refpurpose>Computes the union of the components of a single geometry.</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef>geometry <function>ST_UnaryUnion</function></funcdef>
+ <paramdef><type>geometry </type> <parameter>geom</parameter></paramdef>
+ <paramdef choice="opt"><type>float8 </type> <parameter>gridSize = -1</parameter></paramdef>
+ </funcprototype>
+
+ </funcsynopsis>
+ </refsynopsisdiv>
+
+ <refsection>
+ <title>Description</title>
+
+ <para>
+ 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>
+ 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>
+If the optional <code>gridSize</code> argument is provided, 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>
+
+ <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>
+
+ </refsection>
+
+
+ <!-- Optionally add a "See Also" section -->
+ <refsection>
+ <title>See Also</title>
+
+ <para>
+ <xref linkend="ST_Union" />,
+ <xref linkend="ST_MemUnion" />,
+ <xref linkend="ST_Collect" />,
+ <xref linkend="ST_Node" />
+ </para>
+ </refsection>
+ </refentry>
<refentry id="ST_Union">
<refnamediv>
<refname>ST_Union</refname>
- <refpurpose>Returns a geometry representing the point-set union of
+ <refpurpose>Computes a geometry representing the point-set union of
the input geometries.</refpurpose>
</refnamediv>
@@ -862,7 +936,7 @@ MULTILINESTRING((1 3 2.75,1 4 2),(1 1 3,1 2 2.25))
<title>Description</title>
<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.
+ The output may be an atomic geometry, a MultiGeometry, or a Geometry Collection.
Comes in several variants:</para>
<para><emphasis role="bold">Two-input variant:</emphasis>
@@ -881,7 +955,7 @@ MULTILINESTRING((1 3 2.75,1 4 2),(1 1 3,1 2 2.25))
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>See <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>
@@ -920,10 +994,10 @@ MULTILINESTRING((1 3 2.75,1 4 2),(1 1 3,1 2 2.25))
<title>Examples</title>
<para>Aggregate example</para>
<programlisting>
-SELECT stusps,
- ST_Union(f.geom) as singlegeom
+SELECT id,
+ ST_Union(geom) as singlegeom
FROM sometable f
-GROUP BY stusps
+GROUP BY id;
</programlisting>
<para>Non-Aggregate example</para>
<programlisting>
@@ -993,75 +1067,4 @@ MULTILINESTRING((3 4,4 5),(1 2,3 4))
</refsection>
</refentry>
- <refentry id="ST_UnaryUnion">
- <refnamediv>
- <refname>ST_UnaryUnion</refname>
-
- <refpurpose>Computes the union of the components of a single geometry.</refpurpose>
- </refnamediv>
-
- <refsynopsisdiv>
- <funcsynopsis>
- <funcprototype>
- <funcdef>geometry <function>ST_UnaryUnion</function></funcdef>
- <paramdef><type>geometry </type> <parameter>geom</parameter></paramdef>
- <paramdef choice="opt"><type>float8 </type> <parameter>gridSize = -1</parameter></paramdef>
- </funcprototype>
-
- </funcsynopsis>
- </refsynopsisdiv>
-
- <refsection>
- <title>Description</title>
-
- <para>
- 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>
- 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>
-If the optional <code>gridSize</code> argument is provided, 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>
-
- <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>
-
- </refsection>
-
-
- <!-- Optionally add a "See Also" section -->
- <refsection>
- <title>See Also</title>
-
- <para>
- <xref linkend="ST_Union" />,
- <xref linkend="ST_MemUnion" />,
- <xref linkend="ST_Collect" />,
- <xref linkend="ST_Node" />
- </para>
- </refsection>
- </refentry>
-
-
</sect1>
-----------------------------------------------------------------------
Summary of changes:
doc/reference_overlay.xml | 199 +++++++++++++++++++++++-----------------------
1 file changed, 101 insertions(+), 98 deletions(-)
hooks/post-receive
--
PostGIS
More information about the postgis-tickets
mailing list