[SCM] PostGIS branch stable-3.2 updated. 3.2.7-31-g340af0fac
git at osgeo.org
git at osgeo.org
Mon Apr 28 03:28:59 PDT 2025
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, stable-3.2 has been updated
via 340af0fac6a1a96aa79c396d9c9db941fc3d7542 (commit)
from d221dd93806c5de63425c54627051ded3dc7c316 (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 340af0fac6a1a96aa79c396d9c9db941fc3d7542
Author: Sandro Santilli <strk at kbt.io>
Date: Mon Apr 28 11:09:17 2025 +0200
Reword paragraph about gridSize parameter of overlay operations
The text erroneously reported that the input geometries would
be snapped to the given grid, while instead it is EXPECTED to
be already snapped.
This change turns the corrisponding documentation snippet into
a reusable tag and uses it in all appropriate overlay operation
sections.
References #5885 in 3.2 branch (3.2.9dev)
diff --git a/doc/postgis.xml b/doc/postgis.xml
index 43792f4ee..afd1d1d45 100644
--- a/doc/postgis.xml
+++ b/doc/postgis.xml
@@ -70,6 +70,13 @@
url='http://www.opengeospatial.org/standards/sfs'>OGC Simple Features
Implementation Specification for SQL 1.1.</ulink>">
+<!ENTITY overlay_gridsize_arg
+"If the optional <code>gridSize</code> parameter is given (GEOS-3.9.0 or higher required),
+all result vertices are guaranteed to fall on a grid of the specified
+size. For the operation to give predictable results all the input vertices
+must fall already on the specified grid, see <xref linkend='ST_ReducePrecision'/>.
+">
+
<!ENTITY sqlmm_compliant
"<inlinemediaobject>
<imageobject>
diff --git a/doc/reference_overlay.xml b/doc/reference_overlay.xml
index 5f051ec1b..5a7a72e96 100644
--- a/doc/reference_overlay.xml
+++ b/doc/reference_overlay.xml
@@ -90,11 +90,7 @@ SELECT ST_ClipByBox2D(geom, ST_MakeEnvelope(0,0,10,10)) FROM mytab;
<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
-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> &overlay_gridsize_arg; </para>
<para>Performed by the GEOS module</para>
<para>Enhanced: 3.1.0 accept a gridSize parameter - requires GEOS >= 3.9.0</para>
@@ -167,7 +163,12 @@ MULTIPOINT(-118.6 38.329 6,-118.58 38.38 5)
<refsection>
<title>See Also</title>
- <para><xref linkend="ST_SymDifference" />, <xref linkend="ST_Intersection" />, <xref linkend="ST_Union" /></para>
+ <para>
+<xref linkend="ST_SymDifference"/>,
+<xref linkend="ST_Intersection"/>,
+<xref linkend="ST_Union"/>,
+<xref linkend="ST_ReducePrecision"/>
+ </para>
</refsection>
</refentry>
@@ -219,11 +220,7 @@ Computes a geometry representing the shared portion of geometries A and B.
<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
-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> &overlay_gridsize_arg; </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>
@@ -299,7 +296,19 @@ 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>
<refsection>
<title>See Also</title>
- <para><xref linkend="ST_3DIntersection" />, <xref linkend="ST_Difference"/>, <xref linkend="ST_Union"/>, <xref linkend="ST_Dimension"/>, <xref linkend="ST_Dump"/>, <xref linkend="ST_Force2D" />, <xref linkend="ST_SymDifference"/>, <xref linkend="ST_Intersects"/>, <xref linkend="ST_Multi"/></para>
+ <para>
+<xref linkend="ST_3DIntersection"/>,
+<xref linkend="ST_Difference"/>,
+<xref linkend="ST_Union"/>,
+<xref linkend="ST_ClipByBox2D"/>,
+<xref linkend="ST_Dimension"/>,
+<xref linkend="ST_Dump"/>,
+<xref linkend="ST_Force2D"/>,
+<xref linkend="ST_SymDifference"/>,
+<xref linkend="ST_Intersects"/>,
+<xref linkend="ST_Multi"/>,
+<xref linkend="ST_ReducePrecision"/>
+ </para>
</refsection>
</refentry>
@@ -625,8 +634,10 @@ GEOMETRYCOLLECTION(
"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.
- <code>gridSize</code> can be specified to have clipping work in fixed-precision space (requires GEOS-3.9.0+).
</para>
+
+ <para> &overlay_gridsize_arg; </para>
+
<para>Performed by the GEOS module.</para>
<para>Availability: 2.2.0</para>
<para>Enhanced: 2.5.0 reuses existing points on polygon split, vertex count is lowered from 8 to 5.</para>
@@ -704,10 +715,11 @@ LINESTRING(44.7994523421035 82.5156766227011,85 85)</screen>
<title>See Also</title>
<para>
<xref linkend="ST_AsText" />,
-<xref linkend="ST_ClipByBox2D" />,
-<xref linkend="ST_Segmentize" />,
-<xref linkend="ST_Split" />,
-<xref linkend="ST_NPoints" />
+<xref linkend="ST_ClipByBox2D"/>,
+<xref linkend="ST_Segmentize"/>,
+<xref linkend="ST_Split"/>,
+<xref linkend="ST_NPoints"/>,
+<xref linkend="ST_ReducePrecision"/>
</para>
</refsection>
</refentry>
@@ -740,11 +752,7 @@ LINESTRING(44.7994523421035 82.5156766227011,85 85)</screen>
It is called a symmetric difference because <code>ST_SymDifference(A,B) = ST_SymDifference(B,A)</code>.
</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> &overlay_gridsize_arg; </para>
<para>Performed by the GEOS module</para>
@@ -822,7 +830,12 @@ MULTILINESTRING((1 3 2.75,1 4 2),(1 1 3,1 2 2.25))
<refsection>
<title>See Also</title>
- <para><xref linkend="ST_Difference" />, <xref linkend="ST_Intersection" />, <xref linkend="ST_Union" /></para>
+ <para>
+<xref linkend="ST_Difference"/>,
+<xref linkend="ST_Intersection"/>,
+<xref linkend="ST_Union"/>,
+<xref linkend="ST_ReducePrecision"/>
+ </para>
</refsection>
</refentry>
@@ -869,11 +882,7 @@ MULTILINESTRING((1 3 2.75,1 4 2),(1 1 3,1 2 2.25))
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> &overlay_gridsize_arg; </para>
<para>&Z_support; However, the result is computed using XY only.
The result Z values are copied, averaged or interpolated.</para>
@@ -888,10 +897,12 @@ on that same grid. (Requires GEOS-3.9.0 or higher)
<title>See Also</title>
<para>
- <xref linkend="ST_Union" />,
- <xref linkend="ST_MemUnion" />,
- <xref linkend="ST_Collect" />,
- <xref linkend="ST_Node" />
+ <xref linkend="ST_Union"/>,
+ <xref linkend="ST_MemUnion"/>,
+ <xref linkend="ST_MakeValid"/>,
+ <xref linkend="ST_Collect"/>,
+ <xref linkend="ST_Node"/>,
+ <xref linkend="ST_ReducePrecision"/>
</para>
</refsection>
</refentry>
@@ -961,11 +972,7 @@ on that same grid. (Requires GEOS-3.9.0 or higher)
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>
+ <para> &overlay_gridsize_arg; </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.
@@ -976,7 +983,7 @@ on that same grid. (Requires GEOS-3.9.0 or higher)
<para>Performed by the GEOS module.</para>
<para>ST_Union creates MultiLineString and does not sew LineStrings into a single LineString.
Use <xref linkend="ST_LineMerge" /> to sew LineStrings.</para>
-
+
<para>NOTE: this function was formerly called GeomUnion(), which
was renamed from "Union" because UNION is an SQL reserved
word.</para>
@@ -1061,12 +1068,13 @@ MULTILINESTRING((3 4,4 5),(1 2,3 4))
<refsection>
<title>See Also</title>
<para>
- <xref linkend="ST_Collect" />,
- <xref linkend="ST_UnaryUnion" />,
- <xref linkend="ST_MemUnion" />,
- <xref linkend="ST_Intersection" />,
- <xref linkend="ST_Difference" />,
- <xref linkend="ST_SymDifference" />
+ <xref linkend="ST_Collect"/>,
+ <xref linkend="ST_UnaryUnion"/>,
+ <xref linkend="ST_MemUnion"/>,
+ <xref linkend="ST_Intersection"/>,
+ <xref linkend="ST_Difference"/>,
+ <xref linkend="ST_SymDifference"/>,
+ <xref linkend="ST_ReducePrecision"/>
</para>
</refsection>
</refentry>
-----------------------------------------------------------------------
Summary of changes:
doc/postgis.xml | 7 ++++
doc/reference_overlay.xml | 96 +++++++++++++++++++++++++----------------------
2 files changed, 59 insertions(+), 44 deletions(-)
hooks/post-receive
--
PostGIS
More information about the postgis-tickets
mailing list