[postgis-tickets] [SCM] PostGIS branch master updated. 3.1.0rc1-152-gb10a467
git at osgeo.org
git at osgeo.org
Thu Apr 22 13:27:03 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 b10a4673f2168567065c0373ba9534ea2da56f73 (commit)
from adc0c61c6b65c11c50f0b490385a7e2070531c78 (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 b10a4673f2168567065c0373ba9534ea2da56f73
Author: Martin Davis <mtnclimb at gmail.com>
Date: Thu Apr 22 13:26:56 2021 -0700
Improve doc WKB/WKT information
diff --git a/doc/introduction.xml b/doc/introduction.xml
index 527b7e3..793706b 100644
--- a/doc/introduction.xml
+++ b/doc/introduction.xml
@@ -12,7 +12,7 @@
organizations all over the world that gain great benefit from its functionality and versatility.</para>
<para>The PostGIS project development group plans on supporting and
enhancing PostGIS to better support a range of important GIS functionality
- in the areas of OpenGIS and SQL/MM spatial standards, advanced topological constructs (coverages,
+ in the areas of OGC and SQL/MM spatial standards, advanced topological constructs (coverages,
surfaces, networks), data source for desktop user interface tools for viewing and editing
GIS data, and web-based access tools.</para>
diff --git a/doc/postgis.xml b/doc/postgis.xml
index e55b2f8..c9eba82 100644
--- a/doc/postgis.xml
+++ b/doc/postgis.xml
@@ -67,7 +67,7 @@
<imageobject><imagedata fileref='images/check.png' /></imageobject>
</inlinemediaobject>
This method implements the <ulink
- url='http://www.opengeospatial.org/standards/sfs'>OpenGIS Simple Features
+ url='http://www.opengeospatial.org/standards/sfs'>OGC Simple Features
Implementation Specification for SQL 1.1.</ulink>">
<!ENTITY sqlmm_compliant
diff --git a/doc/reference_output.xml b/doc/reference_output.xml
index 842e601..cced670 100644
--- a/doc/reference_output.xml
+++ b/doc/reference_output.xml
@@ -131,7 +131,7 @@ CIRCULARSTRING(220268 150415 1,220227 150505 2,220227 150406 3)
<refsection>
<title>Description</title>
- <para>Returns the <link linkend="OpenGISWKBWKT">Well-Known Text</link> (WKT) representation of the geometry/geography.
+ <para>Returns the OGC <link linkend="OpenGISWKBWKT">Well-Known Text</link> (WKT) representation of the geometry/geography.
The optional <parameter>maxdecimaldigits</parameter> argument may be used to limit the number
of digits after the decimal point in output ordinates (defaults to 15).</para>
@@ -202,7 +202,7 @@ F000000000000000000000000000000000000000000000000');
<refentry id="ST_AsBinary">
<refnamediv>
<refname>ST_AsBinary</refname>
- <refpurpose>Return the Well-Known Binary (WKB) representation of the geometry/geography without SRID meta data.</refpurpose>
+ <refpurpose>Return the OGC/ISO Well-Known Binary (WKB) representation of the geometry/geography without SRID meta data.</refpurpose>
</refnamediv>
<refsynopsisdiv>
@@ -231,22 +231,21 @@ F000000000000000000000000000000000000000000000000');
<refsection>
<title>Description</title>
- <para>Returns the Well-Known Binary representation of the geometry. There are 2 variants of the function. The first
+ <para>Returns the OGC/ISO <link linkend="OpenGISWKBWKT">Well-Known Binary</link> representation of the geometry. There are 2 variants of the function. The first
variant takes no endian encoding parameter and defaults to server machine endian. The second variant takes a second argument
denoting the encoding - using little-endian ('NDR') or big-endian ('XDR') encoding.</para>
<para>This is useful in binary cursors to pull data out of the
database without converting it to a string representation.</para>
+ <para>To perform the inverse conversion of WKB to PostGIS geometry use <xref linkend="ST_GeomFromWKB" />.</para>
+
<note>
- <para>The WKB spec does not include the SRID. To get the WKB with SRID format use ST_AsEWKB</para>
- </note>
- <note>
- <para>ST_AsBinary is the reverse of <xref linkend="ST_GeomFromWKB" /> for geometry. Use <xref linkend="ST_GeomFromWKB" /> to convert to a postgis geometry from ST_AsBinary representation.</para>
+ <para>The OGC/ISO WKB does not include the SRID. To get the EWKB format including SRID use <xref linkend="ST_AsEWKB" /></para>
</note>
<note>
- <para>The default behavior in PostgreSQL 9.0 has been changed to output bytea in hex encoding. ST_AsBinary is the reverse of <xref linkend="ST_GeomFromWKB" /> for geometry. If your GUI tools
- require the old behavior, then SET bytea_output='escape' in your database.</para>
+ <para>The default behavior in PostgreSQL 9.0 has been changed to output bytea in hex encoding.
+ If your GUI tools require the old behavior, then SET bytea_output='escape' in your database.</para>
</note>
<para>Enhanced: 2.0.0 support for Polyhedral surfaces, Triangles and TIN was introduced.</para>
@@ -307,7 +306,7 @@ F000000000000000000000000000000000000000000000000');
<refentry id="ST_AsEWKB">
<refnamediv>
<refname>ST_AsEWKB</refname>
- <refpurpose>Return the Well-Known Binary (WKB) representation of the geometry with SRID meta data.</refpurpose>
+ <refpurpose>Return the Extended Well-Known Binary (EWKB) representation of the geometry with SRID meta data.</refpurpose>
</refnamediv>
<refsynopsisdiv>
@@ -326,17 +325,18 @@ F000000000000000000000000000000000000000000000000');
<refsection>
<title>Description</title>
- <para>Returns the Well-Known Binary representation of the geometry with SRID metadata. There are 2 variants of the function. The first
+ <para>Returns the <link linkend="EWKB_EWKT">Extended Well-Known Binary</link> (EWKB) representation of the geometry with SRID metadata. There are 2 variants of the function. The first
variant takes no endian encoding parameter and defaults to little endian. The second variant takes a second argument
denoting the encoding - using little-endian ('NDR') or big-endian ('XDR') encoding.</para>
<para>This is useful in binary cursors to pull data out of the
database without converting it to a string representation.</para>
+
+ <para>To perform the inverse conversion of EWKB to PostGIS geometry use <xref linkend="ST_GeomFromEWKB" />.</para>
+
<note>
- <para>The WKB spec does not include the SRID. To get the OGC WKB format use ST_AsBinary</para>
- </note>
- <note>
- <para>ST_AsEWKB is the reverse of ST_GeomFromEWKB. Use ST_GeomFromEWKB to convert to a postgis geometry from ST_AsEWKB representation.</para>
+ <para>The OGC/ISO WKB spec does not include the SRID. To get the OGC WKB format use <xref linkend="ST_AsBinary" /></para>
</note>
+
<para>Enhanced: 2.0.0 support for Polyhedral surfaces, Triangles and TIN was introduced.</para>
<para>&Z_support;</para>
<para>&curve_support;</para>
@@ -352,32 +352,28 @@ F000000000000000000000000000000000000000000000000');
st_asewkb
--------------------------------
-\001\003\000\000 \346\020\000\000\001\000
-\000\000\005\000\000\000\000
-\000\000\000\000\000\000\000\000
-\000\000\000\000\000\000\000\000\000
-\000\000\000\000\000\000\000\000\000\000
-\000\000\360?\000\000\000\000\000\000\360?
-\000\000\000\000\000\000\360?\000\000\000\000\000
-\000\360?\000\000\000\000\000\000\000\000\000\000\000
-\000\000\000\000\000\000\000\000\000\000\000\000\000
-(1 row)</programlisting>
+\x0103000020e61000000100000005000000
+000000000000000000000000000000000000
+000000000000000000000000f03f00000000
+0000f03f000000000000f03f000000000000
+f03f000000000000000000000000000000000000000000000000
+</programlisting>
<programlisting>
SELECT ST_AsEWKB(ST_GeomFromText('POLYGON((0 0,0 1,1 1,1 0,0 0))',4326), 'XDR');
st_asewkb
--------------------------------
-\000 \000\000\003\000\000\020\346\000\000\000\001\000\000\000\005\000\000\000\000\
-000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000?
-\360\000\000\000\000\000\000?\360\000\000\000\000\000\000?\360\000\000\000\000
-\000\000?\360\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000
-\000\000\000\000\000\000\000\000\000\000\000\000\000
+\x0020000003000010e60000000100000005
+000000000000000000000000000000000000
+0000000000003ff00000000000003ff00000
+000000003ff00000000000003ff000000000
+0000000000000000000000000000000000000000000000000000
</programlisting>
</refsection>
<!-- Optionally add a "See Also" section -->
<refsection>
<title>See Also</title>
- <para><xref linkend="ST_AsBinary" />, <xref linkend="ST_AsEWKT" />, <xref linkend="ST_AsText" />, <xref linkend="ST_GeomFromEWKT" />, <xref linkend="ST_SRID" /></para>
+ <para><xref linkend="ST_AsBinary" />, <xref linkend="ST_GeomFromEWKB" />, <xref linkend="ST_SRID" /></para>
</refsection>
</refentry>
diff --git a/doc/using_postgis_dataman.xml b/doc/using_postgis_dataman.xml
index ea35e6c..2bd6615 100644
--- a/doc/using_postgis_dataman.xml
+++ b/doc/using_postgis_dataman.xml
@@ -6,18 +6,18 @@
<title>GIS Objects</title>
<para>The GIS objects supported by PostGIS are a superset of the "Simple
- Features" standard defined by the OpenGIS Consortium (OGC).
+ Features" standard defined by the Open Geospatial Consortium (OGC).
PostGIS supports all the objects and functions specified in the OGC
"Simple Features for SQL" specification (SFS).</para>
<para>PostGIS extends the standard with support for embedded SRID information.</para>
<sect2 id="OpenGISWKBWKT">
- <title>OpenGIS WKB and WKT</title>
+ <title>OGC WKB and WKT</title>
- <para>The OpenGIS specification defines two standard ways of expressing
- spatial objects: the Well-Known Text (WKT) form and the Well-Known
- Binary (WKB) form. Both WKT and WKB include information about the type
+ <para>The OGC SFS specification defines two standard ways of expressing
+ spatial objects: Well-Known Text (WKT) format and Well-Known
+ Binary (WKB) format. Both WKT and WKB include information about the type
of the object and the coordinates which form the object.</para>
<para>Examples of the text representations (WKT) of the spatial objects
@@ -66,7 +66,7 @@
</listitem>
</itemizedlist>
- <para>The OpenGIS specification also requires that the internal storage
+ <para>The OGC specification requires that the internal storage
format of spatial objects include a spatial referencing system
identifier (SRID). The SRID is required when creating spatial objects
for insertion into the database.</para>
@@ -89,31 +89,36 @@ geometry = ST_GeometryFromText(text WKT, SRID);</programlisting>
<sect2 id="EWKB_EWKT">
<title>PostGIS EWKB, EWKT and Canonical Forms</title>
- <para>First OpenGIS specifications (prior to 1.2.0) only support 2D geometries,
- and the associated SRID is *never* embedded in the input/output representations.</para>
+ <para>OGC specifications prior to 1.2.0 only support 2D geometries,
+ and the associated SRID is *never* included in the input/output representations.</para>
- <para>Even though the last OpenGIS specification 1.2.1 supports 3DM and 3DZ coordinates
- specifing ZM qualifiers, it does not include yet the associated SRID in the
+ <para>The OGC specification 1.2.1 (which is aligned with the ISO 19125 standard)
+ supports 3D (ZYZ and XYM) and 4D (XYZM) coordinates
+ via specifing ZM qualifiers. But it still does not include the SRID in the
input/output representations.</para>
- <para>PostGIS extended formats add 3DM, 3DZ, 4D coordinates support and embedded
- SRID information. However, PostGIS EWKB/EWKT outputs have several peculiarities:</para>
+ <para>Because of these limitations PostGIS has implemented extended EWKB and EWKT formats.
+ They provide XYZ, XYM, and 4D (XYZM) coordinate support
+ and includes SRID information.
+ Including *all* geometry fields allows PostGIS to use EWKB as the format of record
+ (e.g. in DUMP files).
+ PostGIS EWKT outputs have a few differences to OGC WKT:</para>
<itemizedlist>
<listitem>
<para>For 3DZ geometries they will drop the Z qualifier:</para>
- <para>OpenGIS: POINT Z (1 2 3)</para>
- <para>EWKB/EWKT: POINT(1 2 3)</para>
+ <para>OGC: POINT Z (1 2 3)</para>
+ <para>EWKT: POINT(1 2 3)</para>
</listitem>
<listitem>
<para>For 3DM geometries they will keep the M qualifier:</para>
- <para>OpenGIS: POINT M (1 2 3)</para>
- <para>EWKB/EWKT: POINTM(1 2 3)</para>
+ <para>OGC: POINT M (1 2 3)</para>
+ <para>EWKT: POINTM(1 2 3)</para>
</listitem>
<listitem>
<para>For 4D geometries they will drop the ZM qualifiers:</para>
- <para>OpenGIS: POINT ZM (1 2 3 4)</para>
- <para>EWKB/EWKT: POINT(1 2 3 4)</para>
+ <para>OGC: POINT ZM (1 2 3 4)</para>
+ <para>EWKT: POINT(1 2 3 4)</para>
</listitem>
</itemizedlist>
@@ -133,9 +138,9 @@ geometry = ST_GeometryFromText(text WKT, SRID);</programlisting>
</itemizedlist>
<caution>
- <para>PostGIS extended formats are currently superset of the OGC one (every valid WKB/WKT is a valid EWKB/EWKT)
- but this might vary in the future, specifically if OGC comes out with a new format conflicting with our
- extensions. Thus you SHOULD NOT rely on this feature!</para>
+ <para>PostGIS extended formats are currently a superset of the OGC one, so that every valid OGC WKB/WKT is also valid EWKB/EWKT.
+ However, this might vary in the future, specifically if OGC comes out with a new format conflicting with the
+ extensions. Thus you SHOULD NOT rely on this compatibility!</para>
</caution>
<para>Examples of the text representations (EWKT) of the extended
-----------------------------------------------------------------------
Summary of changes:
doc/introduction.xml | 2 +-
doc/postgis.xml | 2 +-
doc/reference_output.xml | 58 ++++++++++++++++++++-----------------------
doc/using_postgis_dataman.xml | 47 +++++++++++++++++++----------------
4 files changed, 55 insertions(+), 54 deletions(-)
hooks/post-receive
--
PostGIS
More information about the postgis-tickets
mailing list