[SCM] PostGIS branch master updated. 3.7.0beta1-136-g77265b958d
git at osgeo.org
git at osgeo.org
Fri Jul 31 08:21:22 PDT 2026
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 77265b958d6465ced2c97afac8da79b6af40a649 (commit)
via 2e4a585aa0abc7ec2d8d0b88bffe436069b3f30c (commit)
from d9fd33a2778f2a23ea7ef4b330f6c393bcba9c2f (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 77265b958d6465ced2c97afac8da79b6af40a649
Merge: d9fd33a277 2e4a585aa0
Author: Darafei Praliaskouski <komzpa at gmail.com>
Date: Fri Jul 31 08:21:16 2026 -0700
Merge pull request 'Document WKB hex and topology face workflows' (!636) from Komzpa/postgis:ai/trac-wiki-recipes-doc-20260731 into master
Move two durable cookbook fragments from Trac into the maintained PostGIS
manual.
* document a deterministic hexadecimal WKB round trip using PostgreSQL
`encode`/`decode` with `ST_AsBinary` and `ST_GeomFromWKB`
* replace the old topology shell-script recipe with a current SQL walkthrough
that builds faces from linework, validates the topology, locates point
attributes, detects outside or duplicate labels, and cleans up
Source pages:
* https://trac.osgeo.org/postgis/wiki/FAQ
* https://trac.osgeo.org/postgis/wiki/UsersWikiTopologyExample
The broader non-Notes Trac pass found the other cookbook SQL either already
covered by current functions and examples or too application-specific to move
into the canonical manual.
Validation:
* `make -C doc check`
* `make -C doc exampletest-report` (923 of 923 selected examples parseable)
* executed both WKB queries and the complete topology workflow against
PostgreSQL 18.4 with PostGIS 3.7.0dev; `ValidateTopology` returned zero errors
* verified the disposable test database was removed
* `git diff --check`
Reviewed-on: https://gitea.osgeo.org/postgis/postgis/pulls/636
commit 2e4a585aa0abc7ec2d8d0b88bffe436069b3f30c
Author: Darafei Praliaskouski <me at komzpa.net>
Date: Fri Jul 31 19:13:45 2026 +0400
doc: add WKB hex and topology face examples
diff --git a/doc/extras_topology.xml b/doc/extras_topology.xml
index 79884547a0..e95000b5eb 100644
--- a/doc/extras_topology.xml
+++ b/doc/extras_topology.xml
@@ -19,6 +19,91 @@ how is it used, and various FOSS4G tools that support it in <link xlink:href="ht
<para>Functions that are defined in SQL/MM standard are prefixed with ST_ and functions specific to PostGIS are not prefixed.</para>
<para>Topology support is built by default and can be disabled by specifying the --without-topology configure option at build time as described in <xref linkend="postgis_installation"/></para>
+ <section xml:id="Topology_Linework_Faces_Example">
+ <title>Building Faces from Linework</title>
+ <para>This example builds topology faces from noded linework and
+ associates point attributes with the resulting faces. It uses
+ <xref linkend="ST_CreateTopoGeo"/> to populate an empty topology,
+ <xref linkend="ValidateTopology"/> to check the result,
+ <xref linkend="GetFaceByPoint"/> to locate each attribute point,
+ and <xref linkend="ST_GetFaceGeometry"/> to materialize ordinary
+ polygon geometries.</para>
+
+ <para>Create an empty topology and populate it with linework that
+ encloses two faces:</para>
+<programlisting language="sql" role="requires-external-state">CREATE EXTENSION IF NOT EXISTS postgis_topology;
+
+SELECT topology.CreateTopology('topo_example', 3857);
+
+WITH lines(geom) AS (VALUES
+ ('SRID=3857;LINESTRING(0 0, 2 0)'::geometry),
+ ('SRID=3857;LINESTRING(0 1, 2 1)'::geometry),
+ ('SRID=3857;LINESTRING(0 0, 0 1)'::geometry),
+ ('SRID=3857;LINESTRING(1 0, 1 1)'::geometry),
+ ('SRID=3857;LINESTRING(2 0, 2 1)'::geometry)
+)
+SELECT topology.ST_CreateTopoGeo(
+ 'topo_example',
+ ST_Collect(geom)
+)
+FROM lines;
+
+SELECT * FROM topology.ValidateTopology('topo_example');</programlisting>
+
+ <para>An empty result from <function>ValidateTopology</function>
+ means that no topology errors were found. Attribute points can now
+ be matched to faces. A face identifier of <literal>0</literal>
+ denotes the universal face, so the point is outside every bounded
+ face.</para>
+<programlisting language="sql" role="requires-external-state">WITH labels(name, geom) AS (VALUES
+ ('west', 'SRID=3857;POINT(0.5 0.5)'::geometry),
+ ('east', 'SRID=3857;POINT(1.5 0.5)'::geometry),
+ ('outside', 'SRID=3857;POINT(3 0.5)'::geometry)
+),
+located AS (
+ SELECT name,
+ topology.GetFaceByPoint('topo_example', geom, 0) AS face_id
+ FROM labels
+)
+SELECT name,
+ face_id,
+ CASE WHEN face_id = 0 THEN NULL
+ ELSE topology.ST_GetFaceGeometry('topo_example', face_id)
+ END AS geom
+FROM located
+ORDER BY name;</programlisting>
+
+ <para>Before copying attributes into a face table, check both for
+ points outside bounded faces and for multiple source points assigned
+ to the same face:</para>
+<programlisting language="sql" role="requires-external-state">WITH labels(name, geom) AS (VALUES
+ ('west', 'SRID=3857;POINT(0.5 0.5)'::geometry),
+ ('east', 'SRID=3857;POINT(1.5 0.5)'::geometry),
+ ('outside', 'SRID=3857;POINT(3 0.5)'::geometry)
+),
+located AS (
+ SELECT name,
+ topology.GetFaceByPoint('topo_example', geom, 0) AS face_id
+ FROM labels
+)
+SELECT 'outside face' AS problem,
+ array_agg(name ORDER BY name) AS labels
+FROM located
+WHERE face_id = 0
+HAVING count(*) > 0
+UNION ALL
+SELECT 'duplicate face ' || face_id,
+ array_agg(name ORDER BY name)
+FROM located
+WHERE face_id != 0
+GROUP BY face_id
+HAVING count(*) > 1;</programlisting>
+
+ <para>Use <xref linkend="DropTopology"/> to remove the example
+ topology when it is no longer needed:</para>
+<programlisting language="sql" role="requires-external-state">SELECT topology.DropTopology('topo_example');</programlisting>
+ </section>
+
<section xml:id="Topology_PrimitiveTables">
<title>Topology Primitive Tables</title>
<para>The core primitives of any topology are stored in the <varname>edge_data</varname>, <varname>node</varname>, and <varname>face</varname> tables that live in the schema created by <xref linkend="CreateTopology"/>. Each row of <varname>edge_data</varname> represents an oriented edge: it records a directed curve from <varname>start_node</varname> to <varname>end_node</varname> together with the identifier of the face encountered on the left of that direction (<varname>left_face</varname>) and the face encountered on the right (<varname>right_face</varname>). The same geometric segment may therefore appear twice—once for each orientation—when it belongs to two faces.</para>
diff --git a/doc/reference_input.xml b/doc/reference_input.xml
index fd5f20113a..f47010156d 100644
--- a/doc/reference_input.xml
+++ b/doc/reference_input.xml
@@ -1189,13 +1189,22 @@ SELECT ST_MPointFromText('MULTIPOINT((-70.9590 42.1180),(-70.9611 42.1223))', 43
<programlisting language="sql">SELECT ST_GeomFromWKB(ST_AsEWKB('POINT(2 5)'::geometry)
);</programlisting>
<screen role="visual-primary text-primary">POINT(2 5)</screen>
+
+ <para>The PostgreSQL <link xlink:href="https://www.postgresql.org/docs/current/functions-binarystring.html"><function>decode</function></link>
+ function converts a hexadecimal WKB string to the <type>bytea</type> value
+ accepted by <function>ST_GeomFromWKB</function>.</para>
+ <programlisting language="sql">SELECT ST_AsEWKT(ST_GeomFromWKB(
+ decode('0101000000e5d022dbf93e2e40dbf97e6abc743540', 'hex'),
+ 4326
+)) AS geom;</programlisting>
+<screen role="text-primary">SRID=4326;POINT(15.123 21.456)</screen>
</refsection>
<!-- Optionally add a "See Also" section -->
<refsection>
<title>See Also</title>
- <para><xref linkend="ST_WKBToSQL"/>, <xref linkend="ST_AsBinary"/>, <xref linkend="ST_GeomFromEWKB"/></para>
+ <para><xref linkend="ST_WKBToSQL"/>, <xref linkend="ST_AsBinary"/>, <xref linkend="ST_AsEWKT"/>, <xref linkend="ST_GeomFromEWKB"/></para>
</refsection>
</refentry>
diff --git a/doc/reference_output.xml b/doc/reference_output.xml
index 0cf95ff22e..bdb9b938c3 100644
--- a/doc/reference_output.xml
+++ b/doc/reference_output.xml
@@ -269,6 +269,16 @@
<screen role="text-primary">\x000000000300000001000000050000000000000000000000000000000000000000000000003ff000
00000000003ff00000000000003ff00000000000003ff00000000000000000000000000000000000
00000000000000000000000000</screen>
+
+ <para>Use the PostgreSQL <link xlink:href="https://www.postgresql.org/docs/current/functions-binarystring.html"><function>encode</function></link>
+ function to produce a hexadecimal WKB string without the <literal>\x</literal>
+ prefix used for <type>bytea</type> display. Specifying <literal>NDR</literal>
+ makes the byte order deterministic.</para>
+ <programlisting language="sql">SELECT encode(
+ ST_AsBinary('POINT(15.123 21.456)'::geometry, 'NDR'),
+ 'hex'
+) AS wkb_hex;</programlisting>
+<screen role="text-primary">0101000000e5d022dbf93e2e40dbf97e6abc743540</screen>
</refsection>
<!-- Optionally add a "See Also" section -->
-----------------------------------------------------------------------
Summary of changes:
doc/extras_topology.xml | 85 ++++++++++++++++++++++++++++++++++++++++++++++++
doc/reference_input.xml | 11 ++++++-
doc/reference_output.xml | 10 ++++++
3 files changed, 105 insertions(+), 1 deletion(-)
hooks/post-receive
--
PostGIS
More information about the postgis-tickets
mailing list