[postgis-tickets] [SCM] PostGIS branch master updated. 3.1.0rc1-505-gd77e8b0
git at osgeo.org
git at osgeo.org
Thu Sep 9 22:53:59 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 d77e8b01b6d485d8e2564c96b438ec31790a3f02 (commit)
from 6f9f76b7395f5c27c69c2136c53608e44ba0d38f (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 d77e8b01b6d485d8e2564c96b438ec31790a3f02
Author: Martin Davis <mtnclimb at gmail.com>
Date: Thu Sep 9 22:53:38 2021 -0700
Improve doc for bounding box functions
diff --git a/doc/reference_bbox.xml b/doc/reference_bbox.xml
index f086342..0bb09c7 100644
--- a/doc/reference_bbox.xml
+++ b/doc/reference_bbox.xml
@@ -256,30 +256,32 @@ BOX(-124.659652709961 24.6830825805664,-67.7798080444336 49.0012092590332)
<title>Description</title>
<para>This function returns a bounding box expanded from the bounding box of the input,
- either by specifying a single distance with which the box should be expanded in all
- directions, or by specifying an expansion distance for each direction.
+ either by specifying a single distance with which the box should be expanded on both
+ axes, or by specifying an expansion distance for each axis.
- Uses double-precision. Can be very useful for distance queries, or to add a bounding box
+ Uses double-precision. Can be used for distance queries, or to add a bounding box
filter to a query to take advantage of a spatial index.</para>
- <para>In addition to the geometry version of ST_Expand, which is the most commonly used, variants
- are provided that accept and produce internal BOX2D and BOX3D data types.
+
+ <para>In addition to the version of ST_Expand accepting and returning a geometry, variants
+ are provided that accept and return
+ <xref linkend="box2d_type" /> and <xref linkend="box3d_type" /> data types.
</para>
- <para>ST_Expand is similar in concept to <xref linkend="ST_Buffer" />,
- except while buffer expands the geometry in all directions,
+
+ <para>Distances are in the units of the spatial reference system of the input.</para>
+
+ <para>ST_Expand is similar to <xref linkend="ST_Buffer" />,
+ except while buffering expands a geometry in all directions,
ST_Expand expands the bounding box along each axis.</para>
- <para>Units are in the units of the spatial reference system in use denoted by the SRID.</para>
<note>
<para>Pre version 1.3, ST_Expand was used in conjunction with <xref linkend="ST_Distance" /> to do indexable distance queries. For example,
<code>geom && ST_Expand('POINT(10 20)', 10) AND ST_Distance(geom, 'POINT(10 20)') < 10</code>.
- This has been replaced by the easier <xref linkend="ST_DWithin" /> construct.</para>
+ This has been replaced by the simpler and more efficient <xref linkend="ST_DWithin" /> function.</para>
</note>
- <note>
- <para>Availability: 1.5.0 behavior changed to output double precision instead of float4 coordinates.</para>
- <para>Enhanced: 2.0.0 support for Polyhedral surfaces, Triangles and TIN was introduced.</para>
- <para>Enhanced: 2.3.0 support was added to expand a box by different amounts in different dimensions.</para>
- </note>
+ <para>Availability: 1.5.0 behavior changed to output double precision instead of float4 coordinates.</para>
+ <para>Enhanced: 2.0.0 support for Polyhedral surfaces, Triangles and TIN was introduced.</para>
+ <para>Enhanced: 2.3.0 support was added to expand a box by different amounts in different dimensions.</para>
<para>&P_support;</para>
<para>&T_support;</para>
@@ -314,7 +316,7 @@ SELECT ST_Expand(CAST('BOX3D(778783 2951741 1,794875 2970042.61545891 10)' As bo
<refsection>
<title>See Also</title>
- <para><xref linkend="ST_AsEWKT" />, <xref linkend="ST_Buffer" />, <xref linkend="ST_DWithin" />, <xref linkend="ST_GeomFromEWKT" />, <xref linkend="ST_GeomFromText" />, <xref linkend="ST_SRID" /></para>
+ <para><xref linkend="ST_Buffer" />, <xref linkend="ST_DWithin" />, <xref linkend="ST_SRID" /></para>
</refsection>
</refentry>
@@ -336,22 +338,24 @@ SELECT ST_Expand(CAST('BOX3D(778783 2951741 1,794875 2970042.61545891 10)' As bo
<refsection>
<title>Description</title>
- <para>ST_Extent returns a bounding box that encloses a set of geometries. The ST_Extent function is an "aggregate" function in the
+ <para>ST_Extent returns a <xref linkend="box2d_type" /> bounding box that encloses a set of geometries.
+ The ST_Extent function is an "aggregate" function in the
terminology of SQL. That means that it operates on lists
of data, in the same way the SUM() and AVG() functions do.</para>
- <para>Since it returns a bounding box, the spatial Units are in the units of the spatial reference system in use denoted by the SRID</para>
- <para>ST_Extent is similar in concept to Oracle Spatial/Locator's SDO_AGGR_MBR</para>
- <note>
- <para>Since ST_Extent returns a bounding box, the SRID meta-data is lost. Use ST_SetSRID to force it back into
- a geometry with SRID meta data. The coordinates are in the units of the spatial ref of the original geometries.</para>
- </note>
+
+ <para>The bounding box coordinates are in the spatial reference system of the input geometries.</para>
+
+ <para>ST_Extent is similar in concept to Oracle Spatial/Locator's SDO_AGGR_MBR.</para>
<note>
- <para>ST_Extent will return boxes with only an x and y component even with (x,y,z) coordinate geometries. To maintain x,y,z use ST_3DExtent instead.</para>
+ <para>The returned <code>box3d</code> value does not include a SRID.
+ Use <xref linkend="ST_SetSRID" /> to convert it into a geometry with SRID metadata.
+ The SRID is the same as the input geometries.</para>
</note>
<note>
- <para>Availability: 1.4.0</para>
+ <para>ST_Extent returns boxes with only x and y ordinates even with 3D geometries.
+ To provide x,y,z use <xref linkend="ST_3DExtent" /> instead.</para>
</note>
<para>Enhanced: 2.0.0 support for Polyhedral surfaces, Triangles and TIN was introduced.</para>
@@ -395,7 +399,7 @@ SELECT ST_SetSRID(ST_Extent(geom),2249) as bextent FROM sometable;
<refsection>
<title>See Also</title>
- <para><xref linkend="geometry_overlaps" />, <xref linkend="ST_AsEWKT" />, <xref linkend="ST_3DExtent" />, <xref linkend="ST_SetSRID" />, <xref linkend="ST_SRID" /></para>
+ <para><xref linkend="ST_3DExtent" />, <xref linkend="ST_SetSRID" /></para>
</refsection>
</refentry>
@@ -417,14 +421,15 @@ SELECT ST_SetSRID(ST_Extent(geom),2249) as bextent FROM sometable;
<refsection>
<title>Description</title>
- <para>ST_3DExtent returns a box3d (includes Z coordinate) bounding box that encloses a set of geometries. The ST_3DExtent function is an "aggregate" function in the
+ <para>ST_3DExtent returns a <xref linkend="box3d_type" /> (includes Z coordinate) bounding box that encloses a set of geometries. The ST_3DExtent function is an "aggregate" function in the
terminology of SQL. That means that it operates on lists
of data, in the same way the SUM() and AVG() functions do.</para>
- <para>Since it returns a bounding box, the spatial Units are in the units of the spatial reference system in use denoted by the SRID</para>
+ <para>The bounding box coordinates are in the spatial reference system of the input geometries.</para>
<note>
- <para>Since ST_3DExtent returns a bounding box, the SRID meta-data is lost. Use ST_SetSRID to force it back into
- a geometry with SRID meta data. The coordinates are in the units of the spatial ref of the original geometries.</para>
+ <para>The returned <code>box3d</code> value does not include a SRID.
+ Use <xref linkend="ST_SetSRID" /> to convert it into a geometry with SRID metadata.
+ The SRID is the same as the input geometries.</para>
</note>
<para>Enhanced: 2.0.0 support for Polyhedral surfaces, Triangles and TIN was introduced.</para>
@@ -462,7 +467,7 @@ FROM (SELECT ST_Translate(ST_Force_3DZ(ST_LineToCurve(ST_Buffer(ST_Point(x,y),1)
<refsection>
<title>See Also</title>
- <para><xref linkend="ST_Extent" />, <xref linkend="ST_Force_3DZ" /></para>
+ <para><xref linkend="ST_Extent" />, <xref linkend="ST_Force_3DZ" />, <xref linkend="ST_SetSRID" /></para>
</refsection>
</refentry>
-----------------------------------------------------------------------
Summary of changes:
doc/reference_bbox.xml | 65 +++++++++++++++++++++++++++-----------------------
1 file changed, 35 insertions(+), 30 deletions(-)
hooks/post-receive
--
PostGIS
More information about the postgis-tickets
mailing list