4545 lines
167 KiB
XML
4545 lines
167 KiB
XML
<?xml version="1.0" encoding="UTF-8"?>
|
|
<chapter id="Topology">
|
|
<title>Topology</title>
|
|
<para>The PostGIS Topology types and functions are used to manage topological objects such as faces, edges and nodes. </para>
|
|
<para>Sandro Santilli's presentation at PostGIS Day Paris 2011 conference gives a good synopsis of PostGIS Topology and where it is headed <ulink url="http://strk.kbt.io/projects/postgis/Paris2011_TopologyWithPostGIS_2_0.pdf">Topology with PostGIS 2.0 slide deck</ulink>.</para>
|
|
<para>
|
|
Vincent Picavet provides a good synopsis and overview of what is Topology,
|
|
how is it used, and various FOSS4G tools that support it in <ulink
|
|
url="https://gitlab.com/Oslandia/documentation/presentations/-/blob/master/2012/pgconf_eu_2012/pgconfeu2012_vincent_picavet_postgis_topology.pdf"
|
|
>PostGIS Topology PGConf EU 2012</ulink>.
|
|
</para>
|
|
<para>An example of a topologically based GIS database is the <ulink url="https://www.census.gov/geo/maps-data/data/tiger.html">US Census Topologically Integrated Geographic Encoding and Referencing System (TIGER)</ulink> database. If you want to experiment with PostGIS topology and need some data, check out <xref linkend="Topology_Load_Tiger" />.</para>
|
|
<para>The PostGIS topology module has existed in prior versions of PostGIS but was never part of the Official PostGIS documentation.
|
|
In PostGIS 2.0.0 major cleanup is going on to remove use of all deprecated functions in it, fix known usability issues, better document the features and functions, add new functions, and enhance to closer conform to SQL-MM standards.</para>
|
|
<para>Details of this project can be found at <ulink url="http://trac.osgeo.org/postgis/wiki/UsersWikiPostgisTopology">PostGIS Topology Wiki</ulink></para>
|
|
<para>All functions and tables associated with this module are installed in a schema called <varname>topology</varname>.</para>
|
|
<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 build by default starting with PostGIS 2.0, and can be disabled specifying --without-topology configure option at build time as described in <xref linkend="postgis_installation"/></para>
|
|
|
|
<sect1 id="Topology_Types">
|
|
<sect1info>
|
|
<abstract>
|
|
<para>This section lists the PostgreSQL data types installed by PostGIS Topology. Note we describe the casting behavior of these which is very
|
|
important especially when designing your own functions.
|
|
</para>
|
|
</abstract>
|
|
</sect1info>
|
|
<title>Topology Types</title>
|
|
|
|
<refentry id="getfaceedges_returntype">
|
|
<refnamediv>
|
|
<refname>getfaceedges_returntype</refname>
|
|
<refpurpose>
|
|
A composite type that consists of a sequence
|
|
number and an edge number.
|
|
</refpurpose>
|
|
</refnamediv>
|
|
<refsection>
|
|
<title>Description</title>
|
|
<para>
|
|
A composite type that consists of a sequence number
|
|
and an edge number.
|
|
This is the return type for <varname>ST_GetFaceEdges</varname>
|
|
and <varname>GetNodeEdges</varname> functions.
|
|
</para>
|
|
<orderedlist>
|
|
<listitem>
|
|
<para><varname>sequence</varname> is an integer: Refers to a topology defined in the topology.topology table which defines the topology schema and srid.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><varname>edge</varname> is an integer: The identifier of an edge.</para>
|
|
</listitem>
|
|
</orderedlist>
|
|
</refsection>
|
|
</refentry>
|
|
|
|
<refentry id="topogeometry">
|
|
<refnamediv>
|
|
<refname>TopoGeometry</refname>
|
|
<refpurpose>A composite type representing a topologically defined geometry.</refpurpose>
|
|
</refnamediv>
|
|
<refsection>
|
|
<title>Description</title>
|
|
<para>A composite type that refers to a topology geometry in a specific topology layer, having a specific type and a specific id. The elements of a TopoGeometry are the properties: topology_id, layer_id, id integer, type integer.</para>
|
|
<orderedlist>
|
|
<listitem>
|
|
<para><varname>topology_id</varname> is an integer: Refers to a topology defined in the topology.topology table which defines the topology schema and srid.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><varname>layer_id</varname> is an integer: The layer_id in the layers table that the TopoGeometry belongs to. The combination of topology_id, layer_id provides a unique reference in the topology.layers table.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><varname>id</varname> is an integer: The id is the autogenerated sequence number that uniquely defines the topogeometry in the respective topology layer.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><varname>type</varname> integer between 1 - 4 that defines the geometry type: 1:[multi]point, 2:[multi]line, 3:[multi]poly, 4:collection</para>
|
|
</listitem>
|
|
</orderedlist>
|
|
</refsection>
|
|
|
|
<refsection>
|
|
<title>Casting Behavior</title>
|
|
<para>This section lists the automatic as well as explicit casts allowed for this data type</para>
|
|
<informaltable rowsep="1" frame="all">
|
|
<tgroup cols="2">
|
|
<tbody>
|
|
<row>
|
|
<entry>Cast To</entry>
|
|
<entry>Behavior</entry>
|
|
</row>
|
|
<row>
|
|
<entry>geometry</entry>
|
|
<entry>automatic</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
</refsection>
|
|
<!-- Optionally add a "See Also" section -->
|
|
<refsection>
|
|
<title>See Also</title>
|
|
<para><xref linkend="CreateTopoGeom"/></para>
|
|
</refsection>
|
|
</refentry>
|
|
|
|
<refentry id="validatetopology_returntype">
|
|
<refnamediv>
|
|
<refname>validatetopology_returntype</refname>
|
|
<refpurpose>A composite type that consists of an error message and id1 and id2 to denote location of error. This is the return type for <varname>ValidateTopology</varname>.</refpurpose>
|
|
</refnamediv>
|
|
<refsection>
|
|
<title>Description</title>
|
|
<para>A composite type that consists of an error message and two integers. The <xref linkend="ValidateTopology" /> function returns a set of these to denote validation errors and the id1 and id2 to denote the ids of the topology objects involved in the error.</para>
|
|
<orderedlist>
|
|
<listitem>
|
|
<para><varname>error</varname> is varchar: Denotes type of error. </para>
|
|
<para>Current error descriptors are: coincident nodes, edge crosses node, edge not simple, edge end node geometry mis-match, edge start node geometry mismatch, face overlaps face,face within face, </para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><varname>id1</varname> is an integer: Denotes identifier of edge / face / nodes in error.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><varname>id2</varname> is an integer: For errors that involve 2 objects denotes the secondary edge / or node</para>
|
|
</listitem>
|
|
</orderedlist>
|
|
|
|
</refsection>
|
|
<!-- Optionally add a "See Also" section -->
|
|
<refsection>
|
|
<title>See Also</title>
|
|
<para><xref linkend="ValidateTopology"/></para>
|
|
</refsection>
|
|
</refentry>
|
|
</sect1>
|
|
|
|
<sect1 id="Topology_Domains">
|
|
<sect1info>
|
|
<abstract>
|
|
<para>This section lists the PostgreSQL domains installed by PostGIS Topology. Domains can be used like object types as return objects of functions or table columns. The distinction between
|
|
a domain and a type is that a domain is an existing type with a check constraint bound to it.
|
|
</para>
|
|
</abstract>
|
|
</sect1info>
|
|
<title>Topology Domains</title>
|
|
|
|
<refentry id="topoelement">
|
|
<refnamediv>
|
|
<refname>TopoElement</refname>
|
|
<refpurpose>An array of 2 integers generally used to identify a TopoGeometry component.</refpurpose>
|
|
</refnamediv>
|
|
<refsection>
|
|
<title>Description</title>
|
|
<para>
|
|
An array of 2 integers used to represent one component of a simple or
|
|
hierarchical <xref linkend="topogeometry" />.
|
|
</para>
|
|
<para>
|
|
In the case of a simple TopoGeometry the first element of the array
|
|
represents the identifier of a topological primitive and the second
|
|
element represents its type (1:node, 2:edge, 3:face). In the case of a
|
|
hierarchical TopoGeometry the first element of the array represents the
|
|
identifier of a child TopoGeometry and the second element represents
|
|
its layer identifier.
|
|
</para>
|
|
|
|
<note><para>
|
|
For any given hierarchical TopoGeometry all child TopoGeometry
|
|
elements will come from the same child layer, as specified in
|
|
the topology.layer record for the layer of the TopoGeometry
|
|
being defined.
|
|
</para></note>
|
|
|
|
</refsection>
|
|
<refsection>
|
|
<title>Examples</title>
|
|
<programlisting>
|
|
SELECT te[1] AS id, te[2] AS type FROM
|
|
( SELECT ARRAY[1,2]::topology.topoelement AS te ) f;
|
|
id | type
|
|
----+------
|
|
1 | 2
|
|
</programlisting>
|
|
<programlisting>SELECT ARRAY[1,2]::topology.topoelement;
|
|
te
|
|
-------
|
|
{1,2}
|
|
</programlisting>
|
|
<programlisting>
|
|
--Example of what happens when you try to case a 3 element array to topoelement
|
|
-- NOTE: topoement has to be a 2 element array so fails dimension check
|
|
SELECT ARRAY[1,2,3]::topology.topoelement;
|
|
ERROR: value for domain topology.topoelement violates check constraint "dimensions"
|
|
</programlisting>
|
|
</refsection>
|
|
<!-- Optionally add a "See Also" section -->
|
|
<refsection>
|
|
<title>See Also</title>
|
|
<para>
|
|
<xref linkend="GetTopoGeomElements"/>,
|
|
<xref linkend="topoelementarray" />,
|
|
<xref linkend="topogeometry" />,
|
|
<xref linkend="TopoGeom_addElement" />,
|
|
<xref linkend="TopoGeom_remElement" />
|
|
</para>
|
|
</refsection>
|
|
</refentry>
|
|
|
|
<refentry id="topoelementarray">
|
|
<refnamediv>
|
|
<refname>TopoElementArray</refname>
|
|
<refpurpose>An array of TopoElement objects.</refpurpose>
|
|
</refnamediv>
|
|
<refsection>
|
|
<title>Description</title>
|
|
<para>An array of 1 or more TopoElement objects, generally used to pass around components of TopoGeometry objects.</para>
|
|
</refsection>
|
|
<refsection>
|
|
<title>Examples</title>
|
|
<programlisting>SELECT '{{1,2},{4,3}}'::topology.topoelementarray As tea;
|
|
tea
|
|
-------
|
|
{{1,2},{4,3}}
|
|
|
|
-- more verbose equivalent --
|
|
SELECT ARRAY[ARRAY[1,2], ARRAY[4,3]]::topology.topoelementarray As tea;
|
|
|
|
tea
|
|
-------
|
|
{{1,2},{4,3}}
|
|
|
|
--using the array agg function packaged with topology --
|
|
SELECT topology.TopoElementArray_Agg(ARRAY[e,t]) As tea
|
|
FROM generate_series(1,4) As e CROSS JOIN generate_series(1,3) As t;
|
|
tea
|
|
--------------------------------------------------------------------------
|
|
{{1,1},{1,2},{1,3},{2,1},{2,2},{2,3},{3,1},{3,2},{3,3},{4,1},{4,2},{4,3}}
|
|
</programlisting>
|
|
<programlisting>SELECT '{{1,2,4},{3,4,5}}'::topology.topoelementarray As tea;
|
|
ERROR: value for domain topology.topoelementarray violates check constraint "dimensions"
|
|
</programlisting>
|
|
</refsection>
|
|
<!-- Optionally add a "See Also" section -->
|
|
<refsection>
|
|
<title>See Also</title>
|
|
<para>
|
|
<xref linkend="topoelement" />,
|
|
<xref linkend="GetTopoGeomElementArray"/>,
|
|
<xref linkend="TopoElementArray_Agg" />
|
|
</para>
|
|
</refsection>
|
|
</refentry>
|
|
</sect1>
|
|
|
|
<sect1 id="Topology_ManagementFunctions">
|
|
<sect1info>
|
|
<abstract>
|
|
<para>This section lists the Topology functions for building new Topology schemas, validating topologies, and managing TopoGeometry Columns</para>
|
|
</abstract>
|
|
</sect1info>
|
|
<title>Topology and TopoGeometry Management</title>
|
|
<refentry id="AddTopoGeometryColumn">
|
|
<refnamediv>
|
|
<refname>AddTopoGeometryColumn</refname>
|
|
<refpurpose>Adds a topogeometry column to an existing table, registers this new column as a layer in topology.layer and returns the new layer_id.</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>integer <function>AddTopoGeometryColumn</function></funcdef>
|
|
<paramdef><type>varchar </type>
|
|
<parameter>topology_name</parameter></paramdef>
|
|
|
|
<paramdef><type>varchar </type>
|
|
<parameter>schema_name</parameter></paramdef>
|
|
|
|
<paramdef><type>varchar </type>
|
|
<parameter>table_name</parameter></paramdef>
|
|
|
|
<paramdef><type>varchar </type>
|
|
<parameter>column_name</parameter></paramdef>
|
|
|
|
<paramdef><type>varchar </type>
|
|
<parameter>feature_type</parameter></paramdef>
|
|
</funcprototype>
|
|
<funcprototype>
|
|
<funcdef>integer <function>AddTopoGeometryColumn</function></funcdef>
|
|
|
|
<paramdef><type>varchar </type>
|
|
<parameter>topology_name</parameter></paramdef>
|
|
|
|
<paramdef><type>varchar </type>
|
|
<parameter>schema_name</parameter></paramdef>
|
|
|
|
<paramdef><type>varchar </type>
|
|
<parameter>table_name</parameter></paramdef>
|
|
|
|
<paramdef><type>varchar </type>
|
|
<parameter>column_name</parameter></paramdef>
|
|
|
|
<paramdef><type>varchar </type>
|
|
<parameter>feature_type</parameter></paramdef>
|
|
|
|
<paramdef><type>integer </type>
|
|
<parameter>child_layer</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
</refsynopsisdiv>
|
|
|
|
<refsection>
|
|
<title>Description</title>
|
|
|
|
<para>Each TopoGeometry object belongs to a specific Layer of a specific Topology. Before creating a TopoGeometry object you need to create its TopologyLayer.
|
|
A Topology Layer is an association of a feature-table with the topology. It also contain type and hierarchy information. We create a layer using the AddTopoGeometryColumn() function: </para>
|
|
<para>This function will both add the requested column to the table and add a record to the topology.layer table with all the given info.</para>
|
|
<para>If you don't specify [child_layer] (or set it to NULL) this layer would contain Basic TopoGeometries (composed by primitive topology elements).
|
|
Otherwise this layer will contain hierarchical TopoGeometries (composed by TopoGeometries from the child_layer).</para>
|
|
|
|
<para>Once the layer is created (its id is returned by the AddTopoGeometryColumn function) you're ready to construct TopoGeometry objects in it</para>
|
|
<para>Valid <varname>feature_type</varname>s are: POINT, MULTIPOINT, LINE, MULTILINE, POLYGON, MULTIPOLYGON, COLLECTION</para>
|
|
|
|
<!-- use this format if new function -->
|
|
<para>Availability: 1.1</para>
|
|
|
|
</refsection>
|
|
|
|
|
|
<refsection>
|
|
<title>Examples</title>
|
|
<programlisting>-- Note for this example we created our new table in the ma_topo schema
|
|
-- though we could have created it in a different schema -- in which case topology_name and schema_name would be different
|
|
CREATE SCHEMA ma;
|
|
CREATE TABLE ma.parcels(gid serial, parcel_id varchar(20) PRIMARY KEY, address text);
|
|
SELECT topology.AddTopoGeometryColumn('ma_topo', 'ma', 'parcels', 'topo', 'POLYGON');</programlisting>
|
|
<programlisting>
|
|
CREATE SCHEMA ri;
|
|
CREATE TABLE ri.roads(gid serial PRIMARY KEY, road_name text);
|
|
SELECT topology.AddTopoGeometryColumn('ri_topo', 'ri', 'roads', 'topo', 'LINE');
|
|
</programlisting>
|
|
</refsection>
|
|
|
|
<!-- Optionally add a "See Also" section -->
|
|
<refsection>
|
|
<title>See Also</title>
|
|
|
|
<para>
|
|
<xref linkend="DropTopoGeometryColumn"/>,
|
|
<xref linkend="toTopoGeom" />,
|
|
<xref linkend="CreateTopology"/>,
|
|
<xref linkend="CreateTopoGeom"/>
|
|
</para>
|
|
</refsection>
|
|
</refentry>
|
|
<refentry id="RenameTopoGeometryColumn">
|
|
<refnamediv>
|
|
<refname>RenameTopoGeometryColumn</refname>
|
|
<refpurpose>Renames a topogeometry column</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>topology.layer <function>RenameTopoGeometryColumn</function></funcdef>
|
|
<paramdef><type>regclass </type>
|
|
<parameter>layer_table</parameter></paramdef>
|
|
<paramdef><type>name </type>
|
|
<parameter>feature_column</parameter></paramdef>
|
|
<paramdef><type>name </type>
|
|
<parameter>new_name</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
</refsynopsisdiv>
|
|
|
|
<refsection>
|
|
<title>Description</title>
|
|
|
|
<para>
|
|
This function changes the name of an existing TopoGeometry column
|
|
ensuring metadata information about it is updated accordingly.
|
|
</para>
|
|
|
|
<!-- use this format if new function -->
|
|
<para>Availability: 3.4.0</para>
|
|
|
|
</refsection>
|
|
|
|
<refsection>
|
|
<title>Examples</title>
|
|
<programlisting>
|
|
SELECT topology.RenameTopoGeometryColumn('public.parcels', 'topogeom', 'tgeom');
|
|
</programlisting>
|
|
</refsection>
|
|
|
|
<!-- Optionally add a "See Also" section -->
|
|
<refsection>
|
|
<title>See Also</title>
|
|
|
|
<para>
|
|
<xref linkend="AddTopoGeometryColumn"/>,
|
|
<xref linkend="RenameTopology"/>
|
|
</para>
|
|
</refsection>
|
|
</refentry>
|
|
<refentry id="DropTopology">
|
|
<refnamediv>
|
|
<refname>DropTopology</refname>
|
|
|
|
<refpurpose>Use with caution: Drops a topology schema and deletes its reference from topology.topology table and references to tables in that schema from the geometry_columns table.</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>integer <function>DropTopology</function></funcdef>
|
|
<paramdef><type>varchar </type> <parameter>topology_schema_name</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
</refsynopsisdiv>
|
|
|
|
<refsection>
|
|
<title>Description</title>
|
|
|
|
<para>Drops a topology schema and deletes its reference from topology.topology table and references to tables in that schema from the geometry_columns table.
|
|
This function should be USED WITH CAUTION, as it could destroy data you care about. If the schema does not exist, it just removes reference entries the named schema.</para>
|
|
|
|
<!-- use this format if new function -->
|
|
<para>Availability: 1.1</para>
|
|
</refsection>
|
|
|
|
|
|
<refsection>
|
|
<title>Examples</title>
|
|
<para>Cascade drops the ma_topo schema and removes all references to it in topology.topology and geometry_columns.</para>
|
|
<programlisting>SELECT topology.DropTopology('ma_topo');</programlisting>
|
|
</refsection>
|
|
|
|
<!-- Optionally add a "See Also" section -->
|
|
<refsection>
|
|
<title>See Also</title>
|
|
|
|
<para><xref linkend="DropTopoGeometryColumn"/></para>
|
|
</refsection>
|
|
</refentry>
|
|
<refentry id="RenameTopology">
|
|
<refnamediv>
|
|
<refname>RenameTopology</refname>
|
|
<refpurpose>Renames a topology</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>varchar <function>RenameTopology</function></funcdef>
|
|
<paramdef><type>varchar </type> <parameter>old_name</parameter></paramdef>
|
|
<paramdef><type>varchar </type> <parameter>new_name</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
</refsynopsisdiv>
|
|
|
|
<refsection>
|
|
<title>Description</title>
|
|
|
|
<para>
|
|
Renames a topology schema, updating its metadata record in the <varname>topology.topology</varname> table.
|
|
</para>
|
|
|
|
<!-- use this format if new function -->
|
|
<para>Availability: 3.4.0</para>
|
|
</refsection>
|
|
|
|
|
|
<refsection>
|
|
<title>Examples</title>
|
|
<para>
|
|
Rename a topology from <varname>topo_stage</varname> to <varname>topo_prod</varname>.
|
|
</para>
|
|
<programlisting>SELECT topology.RenameTopology('topo_stage', 'topo_prod');</programlisting>
|
|
|
|
</refsection>
|
|
|
|
<!-- Optionally add a "See Also" section -->
|
|
<refsection>
|
|
<title>See Also</title>
|
|
|
|
<para>
|
|
<xref linkend="CopyTopology" />,
|
|
<xref linkend="RenameTopoGeometryColumn" />
|
|
</para>
|
|
</refsection>
|
|
</refentry>
|
|
<refentry id="DropTopoGeometryColumn">
|
|
<refnamediv>
|
|
<refname>DropTopoGeometryColumn</refname>
|
|
|
|
<refpurpose>Drops the topogeometry column from the table named <varname>table_name</varname> in schema <varname>schema_name</varname> and unregisters the columns from topology.layer table.</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>text <function>DropTopoGeometryColumn</function></funcdef>
|
|
<paramdef><type>varchar </type> <parameter>schema_name</parameter></paramdef>
|
|
<paramdef><type>varchar </type> <parameter>table_name</parameter></paramdef>
|
|
<paramdef><type>varchar </type> <parameter>column_name</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
</refsynopsisdiv>
|
|
|
|
<refsection>
|
|
<title>Description</title>
|
|
|
|
<para>Drops the topogeometry column from the table named <varname>table_name</varname> in schema <varname>schema_name</varname> and unregisters the columns from topology.layer table. Returns summary
|
|
of drop status. NOTE: it first sets all values to NULL before dropping to bypass referential integrity checks.</para>
|
|
|
|
<!-- use this format if new function -->
|
|
<para>Availability: 1.1</para>
|
|
</refsection>
|
|
|
|
|
|
<refsection>
|
|
<title>Examples</title>
|
|
<programlisting>SELECT topology.DropTopoGeometryColumn('ma_topo', 'parcel_topo', 'topo');</programlisting>
|
|
</refsection>
|
|
|
|
<!-- Optionally add a "See Also" section -->
|
|
<refsection>
|
|
<title>See Also</title>
|
|
<para><xref linkend="AddTopoGeometryColumn"/></para>
|
|
</refsection>
|
|
</refentry>
|
|
|
|
<refentry id="Populate_Topology_Layer">
|
|
<refnamediv>
|
|
<refname>Populate_Topology_Layer</refname>
|
|
|
|
<refpurpose>Adds missing entries to topology.layer table by reading metadata from topo tables.</refpurpose>
|
|
</refnamediv>
|
|
|
|
|
|
<refsynopsisdiv>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>setof record <function>Populate_Topology_Layer</function></funcdef>
|
|
<paramdef></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
</refsynopsisdiv>
|
|
|
|
<refsection>
|
|
<title>Description</title>
|
|
|
|
<para>Adds missing entries to the <varname>topology.layer</varname> table by inspecting topology constraints on tables.
|
|
This function is useful for fixing up entries in topology catalog after restores of schemas with topo data.</para>
|
|
<para>It returns the list of entries created. Returned columns are <varname>schema_name</varname>, <varname>table_name</varname>, <varname>feature_column</varname>.</para>
|
|
|
|
<!-- use this format if new function -->
|
|
<para>Availability: 2.3.0</para>
|
|
</refsection>
|
|
|
|
|
|
<refsection>
|
|
<title>Examples</title>
|
|
<programlisting>SELECT CreateTopology('strk_topo');
|
|
CREATE SCHEMA strk;
|
|
CREATE TABLE strk.parcels(gid serial, parcel_id varchar(20) PRIMARY KEY, address text);
|
|
SELECT topology.AddTopoGeometryColumn('strk_topo', 'strk', 'parcels', 'topo', 'POLYGON');
|
|
-- this will return no records because this feature is already registered
|
|
SELECT *
|
|
FROM topology.Populate_Topology_Layer();
|
|
|
|
-- let's rebuild
|
|
TRUNCATE TABLE topology.layer;
|
|
|
|
SELECT *
|
|
FROM topology.Populate_Topology_Layer();
|
|
|
|
SELECT topology_id,layer_id, schema_name As sn, table_name As tn, feature_column As fc
|
|
FROM topology.layer;
|
|
|
|
</programlisting>
|
|
<screen> schema_name | table_name | feature_column
|
|
-------------+------------+----------------
|
|
strk | parcels | topo
|
|
(1 row)
|
|
|
|
topology_id | layer_id | sn | tn | fc
|
|
-------------+----------+------+---------+------
|
|
2 | 2 | strk | parcels | topo
|
|
(1 row)</screen>
|
|
</refsection>
|
|
|
|
<!-- Optionally add a "See Also" section -->
|
|
<refsection>
|
|
<title>See Also</title>
|
|
<para><xref linkend="AddTopoGeometryColumn"/></para>
|
|
</refsection>
|
|
</refentry>
|
|
|
|
<refentry id="TopologySummary">
|
|
<refnamediv>
|
|
<refname>TopologySummary</refname>
|
|
|
|
<refpurpose>Takes a topology name and provides summary totals of types of objects in topology.</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>text <function>TopologySummary</function></funcdef>
|
|
<paramdef><type>varchar </type> <parameter>topology_schema_name</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
</refsynopsisdiv>
|
|
|
|
<refsection>
|
|
<title>Description</title>
|
|
|
|
<para>Takes a topology name and provides summary totals of types of objects in topology.</para>
|
|
|
|
<!-- use this format if new function -->
|
|
<para>Availability: 2.0.0</para>
|
|
</refsection>
|
|
|
|
|
|
<refsection>
|
|
<title>Examples</title>
|
|
<programlisting>SELECT topology.topologysummary('city_data');
|
|
topologysummary
|
|
--------------------------------------------------------
|
|
Topology city_data (329), SRID 4326, precision: 0
|
|
22 nodes, 24 edges, 10 faces, 29 topogeoms in 5 layers
|
|
Layer 1, type Polygonal (3), 9 topogeoms
|
|
Deploy: features.land_parcels.feature
|
|
Layer 2, type Puntal (1), 8 topogeoms
|
|
Deploy: features.traffic_signs.feature
|
|
Layer 3, type Lineal (2), 8 topogeoms
|
|
Deploy: features.city_streets.feature
|
|
Layer 4, type Polygonal (3), 3 topogeoms
|
|
Hierarchy level 1, child layer 1
|
|
Deploy: features.big_parcels.feature
|
|
Layer 5, type Puntal (1), 1 topogeoms
|
|
Hierarchy level 1, child layer 2
|
|
Deploy: features.big_signs.feature</programlisting>
|
|
</refsection>
|
|
<!-- Optionally add a "See Also" section -->
|
|
<refsection>
|
|
<title>See Also</title>
|
|
<para><xref linkend="Topology_Load_Tiger" /></para>
|
|
</refsection>
|
|
</refentry>
|
|
|
|
<refentry id="ValidateTopology">
|
|
<refnamediv>
|
|
<refname>ValidateTopology</refname>
|
|
|
|
<refpurpose>Returns a set of validatetopology_returntype objects detailing issues with topology.</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>setof validatetopology_returntype <function>ValidateTopology</function></funcdef>
|
|
<paramdef><type>varchar </type> <parameter>toponame</parameter></paramdef>
|
|
<paramdef choice="opt"><type>geometry</type> <parameter>bbox</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
</refsynopsisdiv>
|
|
|
|
<refsection>
|
|
<title>Description</title>
|
|
|
|
<para>
|
|
Returns a set of <xref linkend="validatetopology_returntype"/> objects
|
|
detailing issues with topology, optionally limiting the check to the
|
|
area specified by the <varname>bbox</varname> parameter.
|
|
</para>
|
|
|
|
<para>List of possible errors, what they mean and what the returned ids represent are displayed below:</para>
|
|
|
|
<informaltable rowsep="1" frame="all">
|
|
<tgroup cols="4">
|
|
<thead>
|
|
<row>
|
|
<entry>Error</entry>
|
|
<entry>id1</entry>
|
|
<entry>id2</entry>
|
|
<entry>Meaning</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry>coincident nodes</entry>
|
|
<entry>Identifier of first node.</entry>
|
|
<entry>Identifier of second node.</entry>
|
|
<entry>
|
|
Two nodes have the same geometry.
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>edge crosses node</entry>
|
|
<entry>Identifier of the edge.</entry>
|
|
<entry>Identifier of the node.</entry>
|
|
<entry>
|
|
An edge has a node in its interior.
|
|
See <xref linkend="ST_Relate"/>.
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>invalid edge</entry>
|
|
<entry>Identifier of the edge.</entry>
|
|
<entry></entry>
|
|
<entry>
|
|
An edge geometry is invalid.
|
|
See <xref linkend="ST_IsValid" />.
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>edge not simple</entry>
|
|
<entry>Identifier of the edge.</entry>
|
|
<entry></entry>
|
|
<entry>
|
|
An edge geometry has self-intersections.
|
|
See <xref linkend="ST_IsSimple" />.
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>edge crosses edge</entry>
|
|
<entry>Identifier of first edge.</entry>
|
|
<entry>Identifier of second edge.</entry>
|
|
<entry>
|
|
Two edges have an interior intersection.
|
|
See <xref linkend="ST_Relate"/>.
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>edge start node geometry mis-match</entry>
|
|
<entry>Identifier of the edge.</entry>
|
|
<entry>
|
|
Identifier of the indicated start node.
|
|
</entry>
|
|
<entry>
|
|
The geometry of the node indicated as the starting node for an edge does
|
|
not match the first point of the edge geometry.
|
|
See <xref linkend="ST_StartPoint"/>.
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>edge end node geometry mis-match</entry>
|
|
<entry>Identifier of the edge.</entry>
|
|
<entry>
|
|
Identifier of the indicated end node.
|
|
</entry>
|
|
<entry>
|
|
The geometry of the node indicated as the ending node for an edge does
|
|
not match the last point of the edge geometry.
|
|
See <xref linkend="ST_EndPoint"/>.
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>face without edges</entry>
|
|
<entry>
|
|
Identifier of the orphaned face.
|
|
</entry>
|
|
<entry></entry>
|
|
<entry>
|
|
No edge reports an existing face on either of its sides
|
|
(left_face, right_face).
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>face has no rings</entry>
|
|
<entry>
|
|
Identifier of the partially-defined face.
|
|
</entry>
|
|
<entry></entry>
|
|
<entry>
|
|
Edges reporting a face on their sides do not form a ring.
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>face has wrong mbr</entry>
|
|
<entry>
|
|
Identifier of the face with wrong mbr cache.
|
|
</entry>
|
|
<entry></entry>
|
|
<entry>
|
|
Minimum bounding rectangle of a face does not match minimum bounding
|
|
box of the collection of edges reporting the face on their sides.
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>hole not in advertised face</entry>
|
|
<entry>
|
|
Signed identifier of an edge, identifying the ring.
|
|
See <xref linkend="GetRingEdges"/>.
|
|
</entry>
|
|
<entry></entry>
|
|
<entry>
|
|
A ring of edges reporting a face on its exterior
|
|
is contained in different face.
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>not-isolated node has not- containing_face</entry>
|
|
<entry>
|
|
Identifier of the ill-defined node.
|
|
</entry>
|
|
<entry></entry>
|
|
<entry>
|
|
A node which is reported as being on the boundary of one or more edges
|
|
is indicating a containing face.
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>isolated node has containing_face</entry>
|
|
<entry>
|
|
Identifier of the ill-defined node.
|
|
</entry>
|
|
<entry></entry>
|
|
<entry>
|
|
A node which is not reported as being on the boundary of any edges
|
|
is lacking the indication of a containing face.
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>isolated node has wrong containing_face</entry>
|
|
<entry>
|
|
Identifier of the misrepresented node.
|
|
</entry>
|
|
<entry></entry>
|
|
<entry>
|
|
A node which is not reported as being on the boundary of any edges
|
|
indicates a containing face which is not the actual face containing it.
|
|
See <xref linkend="GetFaceContainingPoint" />.
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>invalid next_right_edge</entry>
|
|
<entry>
|
|
Identifier of the misrepresented edge.
|
|
</entry>
|
|
<entry>
|
|
Signed id of the edge which should be indicated as the next right edge.
|
|
</entry>
|
|
<entry>
|
|
The edge indicated as the next edge encountered walking on the right
|
|
side of an edge is wrong.
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>invalid next_left_edge</entry>
|
|
<entry>
|
|
Identifier of the misrepresented edge.
|
|
</entry>
|
|
<entry>
|
|
Signed id of the edge which should be indicated as the next left edge.
|
|
</entry>
|
|
<entry>
|
|
The edge indicated as the next edge encountered walking on the
|
|
left side of an edge is wrong.
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>mixed face labeling in ring</entry>
|
|
<entry>
|
|
Signed identifier of an edge, identifying the ring.
|
|
See <xref linkend="GetRingEdges"/>.
|
|
</entry>
|
|
<entry></entry>
|
|
<entry>
|
|
Edges in a ring indicate conflicting faces on the walking side.
|
|
This is also known as a "Side Location Conflict".
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>non-closed ring</entry>
|
|
<entry>
|
|
Signed identifier of an edge, identifying the ring.
|
|
See <xref linkend="GetRingEdges"/>.
|
|
</entry>
|
|
<entry></entry>
|
|
<entry>
|
|
A ring of edges formed by following next_left_edge/next_right_edge
|
|
attributes starts and ends on different nodes.
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>face has multiple shells</entry>
|
|
<entry>
|
|
Identifier of the contended face.
|
|
</entry>
|
|
<entry>
|
|
Signed identifier of an edge, identifying the ring.
|
|
See <xref linkend="GetRingEdges"/>.
|
|
</entry>
|
|
<entry>
|
|
More than a one ring of edges indicate the same face on its interior.
|
|
</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
|
|
<!-- use this format if new function -->
|
|
<para>Availability: 1.0.0</para>
|
|
<!-- use this format if not a new function but functionality enhanced -->
|
|
<para>Enhanced: 2.0.0 more efficient edge crossing detection and fixes for false positives that were existent in prior versions.</para>
|
|
<para>Changed: 2.2.0 values for id1 and id2 were swapped for 'edge crosses node' to be consistent with error description.</para>
|
|
<para>Changed: 3.2.0 added optional bbox parameter, perform face labeling and edge linking checks.</para>
|
|
</refsection>
|
|
|
|
|
|
<refsection>
|
|
<title>Examples</title>
|
|
<programlisting>SELECT * FROM topology.ValidateTopology('ma_topo');
|
|
error | id1 | id2
|
|
-------------------+-----+-----
|
|
face without edges | 1 |
|
|
</programlisting>
|
|
</refsection>
|
|
|
|
<!-- Optionally add a "See Also" section -->
|
|
<refsection>
|
|
<title>See Also</title>
|
|
<para><xref linkend="validatetopology_returntype"/>, <xref linkend="Topology_Load_Tiger" /></para>
|
|
</refsection>
|
|
</refentry>
|
|
|
|
<refentry id="ValidateTopologyRelation">
|
|
<refnamediv>
|
|
<refname>ValidateTopologyRelation</refname>
|
|
|
|
<refpurpose>Returns info about invalid topology relation records</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>setof record <function>ValidateTopologyRelation</function></funcdef>
|
|
<paramdef><type>varchar </type> <parameter>toponame</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
</refsynopsisdiv>
|
|
|
|
<refsection>
|
|
<title>Description</title>
|
|
|
|
<para>
|
|
Returns a set records giving information about invalidities in the
|
|
relation table of the topology.
|
|
</para>
|
|
|
|
<!-- use this format if new function -->
|
|
<para>Availability: 3.2.0</para>
|
|
</refsection>
|
|
|
|
|
|
<!-- Optionally add a "See Also" section -->
|
|
<refsection>
|
|
<title>See Also</title>
|
|
<para><xref linkend="ValidateTopology"/></para>
|
|
</refsection>
|
|
</refentry>
|
|
|
|
<refentry id="FindTopology">
|
|
<refnamediv>
|
|
<refname>FindTopology</refname>
|
|
|
|
<refpurpose>Returns a topology record by different means.</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>topology <function>FindTopology</function></funcdef>
|
|
<paramdef><type>TopoGeometry</type> <parameter>topogeom</parameter></paramdef>
|
|
</funcprototype>
|
|
<funcprototype>
|
|
<funcdef>topology <function>FindTopology</function></funcdef>
|
|
<paramdef><type>regclass</type> <parameter>layerTable</parameter></paramdef>
|
|
<paramdef><type>name</type> <parameter>layerColumn</parameter></paramdef>
|
|
</funcprototype>
|
|
<funcprototype>
|
|
<funcdef>topology <function>FindTopology</function></funcdef>
|
|
<paramdef><type>name</type> <parameter>layerSchema</parameter></paramdef>
|
|
<paramdef><type>name</type> <parameter>layerTable</parameter></paramdef>
|
|
<paramdef><type>name</type> <parameter>layerColumn</parameter></paramdef>
|
|
</funcprototype>
|
|
<funcprototype>
|
|
<funcdef>topology <function>FindTopology</function></funcdef>
|
|
<paramdef><type>text</type> <parameter>topoName</parameter></paramdef>
|
|
</funcprototype>
|
|
<funcprototype>
|
|
<funcdef>topology <function>FindTopology</function></funcdef>
|
|
<paramdef><type>int</type> <parameter>id</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
</refsynopsisdiv>
|
|
|
|
<refsection>
|
|
<title>Description</title>
|
|
|
|
<para>Takes a topology identifier or the identifier of
|
|
a topology-related object and returns a topology.topology record.</para>
|
|
|
|
<!-- use this format if new function -->
|
|
<para>Availability: 3.2.0</para>
|
|
</refsection>
|
|
|
|
|
|
<refsection>
|
|
<title>Examples</title>
|
|
<programlisting>
|
|
SELECT name(findTopology('features.land_parcels', 'feature'));
|
|
name
|
|
-----------
|
|
city_data
|
|
(1 row)
|
|
</programlisting>
|
|
</refsection>
|
|
<!-- Optionally add a "See Also" section -->
|
|
<!-- Optionally add a "See Also" section -->
|
|
<refsection>
|
|
<title>See Also</title>
|
|
<para><xref linkend="FindLayer"/></para>
|
|
</refsection>
|
|
</refentry>
|
|
|
|
<refentry id="FindLayer">
|
|
<refnamediv>
|
|
<refname>FindLayer</refname>
|
|
|
|
<refpurpose>Returns a topology.layer record by different means.</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>topology.layer <function>FindLayer</function></funcdef>
|
|
<paramdef><type>TopoGeometry</type> <parameter>tg</parameter></paramdef>
|
|
</funcprototype>
|
|
<funcprototype>
|
|
<funcdef>topology.layer <function>FindLayer</function></funcdef>
|
|
<paramdef><type>regclass</type> <parameter>layer_table</parameter></paramdef>
|
|
<paramdef><type>name</type> <parameter>feature_column</parameter></paramdef>
|
|
</funcprototype>
|
|
<funcprototype>
|
|
<funcdef>topology.layer <function>FindLayer</function></funcdef>
|
|
<paramdef><type>name</type> <parameter>schema_name</parameter></paramdef>
|
|
<paramdef><type>name</type> <parameter>table_name</parameter></paramdef>
|
|
<paramdef><type>name</type> <parameter>feature_column</parameter></paramdef>
|
|
</funcprototype>
|
|
<funcprototype>
|
|
<funcdef>topology.layer <function>FindLayer</function></funcdef>
|
|
<paramdef><type>integer</type> <parameter>topology_id</parameter></paramdef>
|
|
<paramdef><type>integer</type> <parameter>layer_id</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
</refsynopsisdiv>
|
|
|
|
<refsection>
|
|
<title>Description</title>
|
|
|
|
<para>Takes a layer identifier or the identifier of
|
|
a topology-related object and returns a topology.layer record.</para>
|
|
|
|
<!-- use this format if new function -->
|
|
<para>Availability: 3.2.0</para>
|
|
</refsection>
|
|
|
|
|
|
<refsection>
|
|
<title>Examples</title>
|
|
<programlisting>
|
|
SELECT layer_id(findLayer('features.land_parcels', 'feature'));
|
|
layer_id
|
|
----------
|
|
1
|
|
(1 row)
|
|
</programlisting>
|
|
</refsection>
|
|
|
|
<!-- Optionally add a "See Also" section -->
|
|
<refsection>
|
|
<title>See Also</title>
|
|
<para><xref linkend="FindTopology"/></para>
|
|
</refsection>
|
|
</refentry>
|
|
</sect1>
|
|
|
|
<sect1 id="Topology_StatsManagement"
|
|
xreflabel="maintaining statistics during topology editing and population" >
|
|
<sect1info>
|
|
<abstract>
|
|
<para>
|
|
This section discusses management of database statistics during
|
|
topology building.
|
|
</para>
|
|
</abstract>
|
|
</sect1info>
|
|
<title>Topology Statistics Management</title>
|
|
|
|
<para>
|
|
Adding elements to a topology triggers many database queries for
|
|
finding existing edges that will be split, adding nodes and
|
|
updating edges that will node with the new linework. For this reason
|
|
it is useful that statistics about the data in the topology tables
|
|
are up-to-date.
|
|
</para>
|
|
|
|
<para>
|
|
PostGIS Topology population and editing functions do not automatically
|
|
update the statistics because a updating stats after each and every
|
|
change in a topology would be overkill, so it is the caller's duty
|
|
to take care of that.
|
|
</para>
|
|
|
|
<note>
|
|
<para>
|
|
That the statistics updated by autovacuum
|
|
will NOT be visible to transactions which started before autovacuum
|
|
process completed, so long-running transactions will need to run
|
|
ANALYZE themselves, to use updated statistics.
|
|
</para>
|
|
</note>
|
|
|
|
</sect1>
|
|
|
|
<sect1 id="Topology_Constructors">
|
|
<sect1info>
|
|
<abstract>
|
|
<para>This section covers the topology functions for creating new topologies.</para>
|
|
</abstract>
|
|
</sect1info>
|
|
<title>Topology Constructors</title>
|
|
|
|
<refentry id="CreateTopology">
|
|
<refnamediv>
|
|
<refname>CreateTopology</refname>
|
|
<refpurpose>Creates a new topology schema and registers it in the topology.topology table.</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>integer <function>CreateTopology</function></funcdef>
|
|
<paramdef><type>varchar </type> <parameter>topology_schema_name</parameter></paramdef>
|
|
</funcprototype>
|
|
|
|
<funcprototype>
|
|
<funcdef>integer <function>CreateTopology</function></funcdef>
|
|
<paramdef><type>varchar </type> <parameter>topology_schema_name</parameter></paramdef>
|
|
<paramdef><type>integer </type> <parameter>srid</parameter></paramdef>
|
|
</funcprototype>
|
|
|
|
<funcprototype>
|
|
<funcdef>integer <function>CreateTopology</function></funcdef>
|
|
<paramdef><type>varchar </type> <parameter>topology_schema_name</parameter></paramdef>
|
|
<paramdef><type>integer </type> <parameter>srid</parameter></paramdef>
|
|
<paramdef><type>double precision </type> <parameter>prec</parameter></paramdef>
|
|
</funcprototype>
|
|
|
|
<funcprototype>
|
|
<funcdef>integer <function>CreateTopology</function></funcdef>
|
|
<paramdef><type>varchar </type> <parameter>topology_schema_name</parameter></paramdef>
|
|
<paramdef><type>integer </type> <parameter>srid</parameter></paramdef>
|
|
<paramdef><type>double precision </type> <parameter>prec</parameter></paramdef>
|
|
<paramdef><type>boolean </type> <parameter>hasz</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
</refsynopsisdiv>
|
|
|
|
<refsection>
|
|
<title>Description</title>
|
|
|
|
<para>Creates a new topology schema with name <varname>topology_name</varname>
|
|
and registers it in the <varname>topology.topology</varname> table.
|
|
Topologies must be uniquely named.
|
|
The topology tables (<varname>edge_data</varname>, <varname>face</varname>, <varname>node</varname>,and <varname>relation</varname> are created in the schema.
|
|
It returns the id of the topology.
|
|
</para>
|
|
|
|
<para>The <varname>srid</varname> is the <link linkend="spatial_ref_sys">spatial reference system</link> SRID for the topology.
|
|
</para>
|
|
|
|
<para>The tolerance <varname>prec</varname> is measured in the units of the spatial reference system.
|
|
The tolerance defaults to 0.
|
|
</para>
|
|
|
|
<para><varname>hasz</varname> defaults to false if not specified. </para>
|
|
|
|
<para>This is similar to the SQL/MM <xref linkend="ST_InitTopoGeo" /> but has more functionality.</para>
|
|
|
|
<!-- use this format if new function -->
|
|
<para>Availability: 1.1</para>
|
|
<para>Enhanced: 2.0 added the signature accepting hasZ</para>
|
|
</refsection>
|
|
|
|
|
|
<refsection>
|
|
<title>Examples</title>
|
|
<para>Create a topology schema called <varname>ma_topo</varname> that stores edges and nodes in Massachusetts State Plane-meters (SRID = 26986).
|
|
The tolerance represents 0.5 meters since the spatial reference system is meter-based.</para>
|
|
<programlisting>SELECT topology.CreateTopology('ma_topo', 26986, 0.5);</programlisting>
|
|
|
|
<para>Create a topology for Rhode Island called <varname>ri_topo</varname> in spatial reference system State Plane-feet (SRID = 3438)</para>
|
|
<programlisting>SELECT topology.CreateTopology('ri_topo', 3438) AS topoid;
|
|
topoid
|
|
------
|
|
2</programlisting>
|
|
</refsection>
|
|
|
|
<!-- Optionally add a "See Also" section -->
|
|
<refsection>
|
|
<title>See Also</title>
|
|
|
|
<para><xref linkend="spatial_ref_sys"/>, <xref linkend="ST_InitTopoGeo" />, <xref linkend="Topology_Load_Tiger" /></para>
|
|
</refsection>
|
|
</refentry>
|
|
|
|
<refentry id="CopyTopology">
|
|
<refnamediv>
|
|
<refname>CopyTopology</refname>
|
|
<refpurpose>Makes a copy of a topology (nodes, edges, faces, layers and TopoGeometries) into a new schema</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>integer <function>CopyTopology</function></funcdef>
|
|
<paramdef><type>varchar </type> <parameter>existing_topology_name</parameter></paramdef>
|
|
<paramdef><type>varchar </type> <parameter>new_name</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
</refsynopsisdiv>
|
|
|
|
<refsection>
|
|
<title>Description</title>
|
|
|
|
<para>
|
|
Creates a new topology with name <varname>new_name</varname>, with SRID and precision copied from <varname>existing_topology_name</varname>
|
|
The nodes, edges and faces in <varname>existing_topology_name</varname> are copied into the new topology,
|
|
as well as Layers and their associated TopoGeometries.
|
|
</para>
|
|
|
|
<note><para>
|
|
The new rows in the <varname>topology.layer</varname> table contain synthetic values for schema_name, table_name and feature_column.
|
|
This is because the TopoGeometry objects exist only as a definition and are not yet available in a user-defined table.
|
|
</para></note>
|
|
|
|
<!-- use this format if new function -->
|
|
<para>Availability: 2.0.0</para>
|
|
</refsection>
|
|
|
|
|
|
<refsection>
|
|
<title>Examples</title>
|
|
<para>
|
|
Make a backup of a topology called <varname>ma_topo</varname>.
|
|
</para>
|
|
<programlisting>SELECT topology.CopyTopology('ma_topo', 'ma_topo_backup');</programlisting>
|
|
|
|
</refsection>
|
|
|
|
<!-- Optionally add a "See Also" section -->
|
|
<refsection>
|
|
<title>See Also</title>
|
|
|
|
<para>
|
|
<xref linkend="spatial_ref_sys"/>,
|
|
<xref linkend="CreateTopology" />,
|
|
<xref linkend="RenameTopology" />
|
|
</para>
|
|
</refsection>
|
|
</refentry>
|
|
|
|
<refentry id="ST_InitTopoGeo">
|
|
<refnamediv>
|
|
<refname>ST_InitTopoGeo</refname>
|
|
<refpurpose>Creates a new topology schema and registers it in the topology.topology table.</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>text <function>ST_InitTopoGeo</function></funcdef>
|
|
<paramdef><type>varchar </type> <parameter>topology_schema_name</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
</refsynopsisdiv>
|
|
|
|
<refsection>
|
|
<title>Description</title>
|
|
|
|
<para>This is the SQL-MM equivalent of <xref linkend="CreateTopology"/>.
|
|
It lacks options for spatial reference system and tolerance.
|
|
it returns a text description of the topology creation, instead of the topology id.</para>
|
|
|
|
<!-- use this format if new function -->
|
|
<para>Availability: 1.1</para>
|
|
<para>&sqlmm_compliant; SQL-MM 3 Topo-Geo and Topo-Net 3: Routine Details: X.3.17</para>
|
|
</refsection>
|
|
|
|
|
|
<refsection>
|
|
<title>Examples</title>
|
|
<programlisting>SELECT topology.ST_InitTopoGeo('topo_schema_to_create') AS topocreation;
|
|
astopocreation
|
|
------------------------------------------------------------
|
|
Topology-Geometry 'topo_schema_to_create' (id:7) created.
|
|
</programlisting>
|
|
</refsection>
|
|
|
|
<!-- Optionally add a "See Also" section -->
|
|
<refsection>
|
|
<title>See Also</title>
|
|
|
|
<para><xref linkend="CreateTopology"/></para>
|
|
</refsection>
|
|
</refentry>
|
|
|
|
|
|
<refentry id="ST_CreateTopoGeo">
|
|
<refnamediv>
|
|
<refname>ST_CreateTopoGeo</refname>
|
|
|
|
<refpurpose>
|
|
Adds a collection of geometries to a given empty topology and returns a message detailing success.
|
|
</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>text <function>ST_CreateTopoGeo</function></funcdef>
|
|
<paramdef><type>varchar </type> <parameter>atopology</parameter></paramdef>
|
|
<paramdef><type>geometry </type> <parameter>acollection</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
</refsynopsisdiv>
|
|
|
|
<refsection>
|
|
<title>Description</title>
|
|
|
|
<para>
|
|
Adds a collection of geometries to a given empty topology and returns a message detailing success.
|
|
</para>
|
|
|
|
<para>Useful for populating an empty topology.</para>
|
|
|
|
|
|
<!-- use this format if new function -->
|
|
<para>Availability: 2.0 </para>
|
|
<para>&sqlmm_compliant; SQL-MM: Topo-Geo and Topo-Net 3: Routine Details -- X.3.18</para>
|
|
</refsection>
|
|
|
|
|
|
<refsection>
|
|
<title>Examples</title>
|
|
<programlisting>
|
|
-- Populate topology --
|
|
SELECT topology.ST_CreateTopoGeo('ri_topo',
|
|
ST_GeomFromText('MULTILINESTRING((384744 236928,384750 236923,384769 236911,384799 236895,384811 236890,384833 236884,
|
|
384844 236882,384866 236881,384879 236883,384954 236898,385087 236932,385117 236938,
|
|
385167 236938,385203 236941,385224 236946,385233 236950,385241 236956,385254 236971,
|
|
385260 236979,385268 236999,385273 237018,385273 237037,385271 237047,385267 237057,
|
|
385225 237125,385210 237144,385192 237161,385167 237192,385162 237202,385159 237214,
|
|
385159 237227,385162 237241,385166 237256,385196 237324,385209 237345,385234 237375,
|
|
385237 237383,385238 237399,385236 237407,385227 237419,385213 237430,385193 237439,
|
|
385174 237451,385170 237455,385169 237460,385171 237475,385181 237503,385190 237521,
|
|
385200 237533,385206 237538,385213 237541,385221 237542,385235 237540,385242 237541,
|
|
385249 237544,385260 237555,385270 237570,385289 237584,385292 237589,385291 237596,385284 237630))',3438)
|
|
);
|
|
|
|
st_createtopogeo
|
|
----------------------------
|
|
Topology ri_topo populated
|
|
|
|
|
|
-- create tables and topo geometries --
|
|
CREATE TABLE ri.roads(gid serial PRIMARY KEY, road_name text);
|
|
|
|
SELECT topology.AddTopoGeometryColumn('ri_topo', 'ri', 'roads', 'topo', 'LINE');
|
|
</programlisting>
|
|
</refsection>
|
|
|
|
<!-- Optionally add a "See Also" section -->
|
|
<refsection>
|
|
<title>See Also</title>
|
|
<para><xref linkend="AddTopoGeometryColumn"/>, <xref linkend="CreateTopology"/>, <xref linkend="DropTopology"/></para>
|
|
</refsection>
|
|
</refentry>
|
|
|
|
<refentry id="TopoGeo_AddPoint">
|
|
<refnamediv>
|
|
<refname>TopoGeo_AddPoint</refname>
|
|
|
|
<refpurpose>
|
|
Adds a point to an existing topology using a tolerance and possibly splitting an existing edge.
|
|
</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>integer <function>TopoGeo_AddPoint</function></funcdef>
|
|
<paramdef><type>varchar </type> <parameter>atopology</parameter></paramdef>
|
|
<paramdef><type>geometry </type> <parameter>apoint</parameter></paramdef>
|
|
<paramdef choice="opt"><type>float8 </type> <parameter>tolerance</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
</refsynopsisdiv>
|
|
|
|
<refsection>
|
|
<title>Description</title>
|
|
|
|
<para>
|
|
Adds a point to an existing topology and returns its identifier.
|
|
The given point will snap to existing nodes or edges within given tolerance.
|
|
An existing edge may be split by the snapped point.
|
|
</para>
|
|
|
|
<!-- use this format if new function -->
|
|
<para>Availability: 2.0.0</para>
|
|
</refsection>
|
|
|
|
|
|
<!-- Optionally add a "See Also" section -->
|
|
<refsection>
|
|
<title>See Also</title>
|
|
<para>
|
|
<xref linkend="TopoGeo_AddLineString"/>,
|
|
<xref linkend="TopoGeo_AddPolygon"/>,
|
|
<xref linkend="AddNode"/>,
|
|
<xref linkend="CreateTopology"/>
|
|
</para>
|
|
</refsection>
|
|
</refentry>
|
|
|
|
<refentry id="TopoGeo_AddLineString">
|
|
<refnamediv>
|
|
<refname>TopoGeo_AddLineString</refname>
|
|
|
|
<refpurpose>Adds a linestring to an existing topology using a tolerance and possibly splitting existing edges/faces. Returns edge identifiers.</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>SETOF integer <function>TopoGeo_AddLineString</function></funcdef>
|
|
<paramdef><type>varchar </type> <parameter>atopology</parameter></paramdef>
|
|
<paramdef><type>geometry </type> <parameter>aline</parameter></paramdef>
|
|
<paramdef choice="opt"><type>float8 </type> <parameter>tolerance</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
</refsynopsisdiv>
|
|
|
|
<refsection>
|
|
<title>Description</title>
|
|
|
|
<para>
|
|
Adds a linestring to an existing topology and returns a set of edge identifiers forming it up.
|
|
The given line will snap to existing nodes or edges within given tolerance.
|
|
Existing edges and faces may be split by the line.
|
|
</para>
|
|
|
|
<note><para>
|
|
Updating statistics about topologies being loaded via this function is
|
|
up to caller, see <xref linkend="Topology_StatsManagement"/>.
|
|
</para></note>
|
|
|
|
<!-- use this format if new function -->
|
|
<para>Availability: 2.0.0</para>
|
|
</refsection>
|
|
|
|
|
|
<!-- Optionally add a "See Also" section -->
|
|
<refsection>
|
|
<title>See Also</title>
|
|
<para>
|
|
<xref linkend="TopoGeo_AddPoint"/>,
|
|
<xref linkend="TopoGeo_AddPolygon"/>,
|
|
<xref linkend="AddEdge"/>,
|
|
<xref linkend="CreateTopology"/>
|
|
</para>
|
|
</refsection>
|
|
</refentry>
|
|
|
|
<refentry id="TopoGeo_AddPolygon">
|
|
<refnamediv>
|
|
<refname>TopoGeo_AddPolygon</refname>
|
|
|
|
<refpurpose>Adds a polygon to an existing topology using a tolerance and possibly splitting existing edges/faces. Returns face identifiers.</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>SETOF integer <function>TopoGeo_AddPolygon</function></funcdef>
|
|
<paramdef><type>varchar </type> <parameter>atopology</parameter></paramdef>
|
|
<paramdef><type>geometry </type> <parameter>apoly</parameter></paramdef>
|
|
<paramdef choice="opt"><type>float8 </type> <parameter>tolerance</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
</refsynopsisdiv>
|
|
|
|
<refsection>
|
|
<title>Description</title>
|
|
|
|
<para>
|
|
Adds a polygon to an existing topology and returns a set of face identifiers forming it up.
|
|
The boundary of the given polygon will snap to existing nodes or edges within given tolerance.
|
|
Existing edges and faces may be split by the boundary of the new polygon.
|
|
</para>
|
|
|
|
<note><para>
|
|
Updating statistics about topologies being loaded via this function is
|
|
up to caller, see <xref linkend="Topology_StatsManagement"/>.
|
|
</para></note>
|
|
|
|
<!-- use this format if new function -->
|
|
<para>Availability: 2.0.0</para>
|
|
</refsection>
|
|
|
|
|
|
<!-- Optionally add a "See Also" section -->
|
|
<refsection>
|
|
<title>See Also</title>
|
|
<para>
|
|
<xref linkend="TopoGeo_AddPoint"/>,
|
|
<xref linkend="TopoGeo_AddLineString"/>,
|
|
<xref linkend="AddFace"/>,
|
|
<xref linkend="CreateTopology"/>
|
|
</para>
|
|
</refsection>
|
|
</refentry>
|
|
|
|
|
|
</sect1>
|
|
|
|
<sect1 id="Topology_Editing">
|
|
<sect1info>
|
|
<abstract>
|
|
<para>This section covers topology functions for adding, moving, deleting, and splitting edges, faces, and nodes. All of these functions are defined by ISO SQL/MM.</para>
|
|
</abstract>
|
|
</sect1info>
|
|
<title>Topology Editors</title>
|
|
|
|
<refentry id="ST_AddIsoNode">
|
|
<refnamediv>
|
|
<refname>ST_AddIsoNode</refname>
|
|
|
|
<refpurpose>Adds an isolated node to a face in a topology and returns the nodeid of the new node. If face is null, the node is still created.</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>integer <function>ST_AddIsoNode</function></funcdef>
|
|
<paramdef><type>varchar </type> <parameter>atopology</parameter></paramdef>
|
|
<paramdef><type>integer </type> <parameter>aface</parameter></paramdef>
|
|
<paramdef><type>geometry </type> <parameter>apoint</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
</refsynopsisdiv>
|
|
|
|
<refsection>
|
|
<title>Description</title>
|
|
|
|
<para>Adds an isolated node with point location <varname>apoint</varname> to an existing face with faceid <varname>aface</varname> to a topology <varname>atopology</varname> and returns the nodeid of the new node.</para>
|
|
<para>If the spatial reference system (srid) of the point geometry is not the same as the topology, the <varname>apoint</varname> is not a point geometry, the point is null, or the point intersects an existing edge
|
|
(even at the boundaries) then an exception is thrown. If the point already exists as a node, an exception is thrown.</para>
|
|
<para>If <varname>aface</varname> is not null and the <varname>apoint</varname> is not within the face, then an exception is thrown.</para>
|
|
|
|
<!-- use this format if new function -->
|
|
<para>Availability: 1.1 </para>
|
|
<para>&sqlmm_compliant; SQL-MM: Topo-Net Routines: X+1.3.1</para>
|
|
</refsection>
|
|
|
|
|
|
<refsection>
|
|
<title>Examples</title>
|
|
<para/>
|
|
<!-- TODO -->
|
|
</refsection>
|
|
|
|
<!-- Optionally add a "See Also" section -->
|
|
<refsection>
|
|
<title>See Also</title>
|
|
<para><xref linkend="AddNode"/>, <xref linkend="CreateTopology"/>, <xref linkend="DropTopology"/>, <xref linkend="ST_Intersects"/></para>
|
|
</refsection>
|
|
</refentry>
|
|
|
|
<refentry id="ST_AddIsoEdge">
|
|
<refnamediv>
|
|
<refname>ST_AddIsoEdge</refname>
|
|
|
|
<refpurpose>Adds an isolated edge defined by geometry <varname>alinestring</varname> to a topology connecting two existing isolated nodes <varname>anode</varname> and <varname>anothernode</varname> and returns the edge id of the new edge.</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>integer <function>ST_AddIsoEdge</function></funcdef>
|
|
<paramdef><type>varchar </type> <parameter>atopology</parameter></paramdef>
|
|
<paramdef><type>integer </type> <parameter>anode</parameter></paramdef>
|
|
<paramdef><type>integer </type> <parameter>anothernode</parameter></paramdef>
|
|
<paramdef><type>geometry </type> <parameter>alinestring</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
</refsynopsisdiv>
|
|
|
|
<refsection>
|
|
<title>Description</title>
|
|
|
|
<para>Adds an isolated edge defined by geometry <varname>alinestring</varname> to a topology connecting two existing isolated nodes <varname>anode</varname> and <varname>anothernode</varname> and returns the edge id of the new edge.</para>
|
|
<para>If the spatial reference system (srid) of the <varname>alinestring</varname> geometry is not the same as the topology, any of the input arguments are null, or the nodes are contained in more than one face, or the nodes are start or end nodes of an existing edge,
|
|
then an exception is thrown.</para>
|
|
<para>If the <varname>alinestring</varname> is not within the face of the face the <varname>anode</varname> and <varname>anothernode</varname> belong to, then an exception is thrown.</para>
|
|
<para>If the <varname>anode</varname> and <varname>anothernode</varname> are not the start and end points of the <varname>alinestring</varname> then an exception is thrown.</para>
|
|
|
|
<!-- use this format if new function -->
|
|
<para>Availability: 1.1 </para>
|
|
<para>&sqlmm_compliant; SQL-MM: Topo-Geo and Topo-Net 3: Routine Details: X.3.4</para>
|
|
</refsection>
|
|
|
|
|
|
<refsection>
|
|
<title>Examples</title>
|
|
<para/>
|
|
<!-- TODO -->
|
|
</refsection>
|
|
|
|
<!-- Optionally add a "See Also" section -->
|
|
<refsection>
|
|
<title>See Also</title>
|
|
<para><xref linkend="ST_AddIsoNode"/>, <xref linkend="ST_IsSimple"/>, <xref linkend="ST_Within"/></para>
|
|
</refsection>
|
|
</refentry>
|
|
|
|
<refentry id="ST_AddEdgeNewFaces">
|
|
<refnamediv>
|
|
<refname>ST_AddEdgeNewFaces</refname>
|
|
|
|
<refpurpose>Add a new edge and, if in doing so it splits a face, delete the original face and replace it with two new faces.</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>integer <function>ST_AddEdgeNewFaces</function></funcdef>
|
|
<paramdef><type>varchar </type> <parameter>atopology</parameter></paramdef>
|
|
<paramdef><type>integer </type> <parameter>anode</parameter></paramdef>
|
|
<paramdef><type>integer </type> <parameter>anothernode</parameter></paramdef>
|
|
<paramdef><type>geometry </type> <parameter>acurve</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
</refsynopsisdiv>
|
|
|
|
<refsection>
|
|
<title>Description</title>
|
|
|
|
<para>
|
|
Add a new edge and, if in doing so it splits a face, delete the original
|
|
face and replace it with two new faces.
|
|
Returns the id of the newly added edge.
|
|
</para>
|
|
|
|
<para>
|
|
Updates all existing joined edges and relationships accordingly.
|
|
</para>
|
|
|
|
<para>If any arguments are null, the given nodes are unknown (must already exist in the <varname>node</varname> table of the topology schema) ,
|
|
the <varname>acurve</varname> is not a <varname>LINESTRING</varname>, the <varname>anode</varname> and <varname>anothernode</varname> are not the start
|
|
and endpoints of <varname>acurve</varname> then an error is thrown.</para>
|
|
<para>If the spatial reference system (srid) of the <varname>acurve</varname> geometry is not the same as the topology an exception is thrown.</para>
|
|
|
|
<!-- use this format if new function -->
|
|
<para>Availability: 2.0 </para>
|
|
<para>&sqlmm_compliant; SQL-MM: Topo-Geo and Topo-Net 3: Routine Details: X.3.12</para>
|
|
</refsection>
|
|
|
|
|
|
<refsection>
|
|
<title>Examples</title>
|
|
<para/>
|
|
<!--TODO: Need examples -->
|
|
</refsection>
|
|
|
|
<!-- Optionally add a "See Also" section -->
|
|
<refsection>
|
|
<title>See Also</title>
|
|
<para><xref linkend="ST_RemEdgeNewFace"/></para>
|
|
<para><xref linkend="ST_AddEdgeModFace"/></para>
|
|
</refsection>
|
|
</refentry>
|
|
|
|
<refentry id="ST_AddEdgeModFace">
|
|
<refnamediv>
|
|
<refname>ST_AddEdgeModFace</refname>
|
|
|
|
<refpurpose>Add a new edge and, if in doing so it splits a face, modify the original face and add a new face.</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>integer <function>ST_AddEdgeModFace</function></funcdef>
|
|
<paramdef><type>varchar </type> <parameter>atopology</parameter></paramdef>
|
|
<paramdef><type>integer </type> <parameter>anode</parameter></paramdef>
|
|
<paramdef><type>integer </type> <parameter>anothernode</parameter></paramdef>
|
|
<paramdef><type>geometry </type> <parameter>acurve</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
</refsynopsisdiv>
|
|
|
|
<refsection>
|
|
<title>Description</title>
|
|
|
|
<para>
|
|
Add a new edge and, if doing so splits a face, modify the original
|
|
face and add a new one.
|
|
</para>
|
|
|
|
<note><para>
|
|
If possible, the new face will be created on left side of the new edge.
|
|
This will not be possible if the face on the left side will need to
|
|
be the Universe face (unbounded).
|
|
</para></note>
|
|
|
|
<para>
|
|
Returns the id of the newly added edge.
|
|
</para>
|
|
|
|
<para>
|
|
Updates all existing joined edges and relationships accordingly.
|
|
</para>
|
|
|
|
<para>If any arguments are null, the given nodes are unknown (must already exist in the <varname>node</varname> table of the topology schema) ,
|
|
the <varname>acurve</varname> is not a <varname>LINESTRING</varname>, the <varname>anode</varname> and <varname>anothernode</varname> are not the start
|
|
and endpoints of <varname>acurve</varname> then an error is thrown.</para>
|
|
<para>If the spatial reference system (srid) of the <varname>acurve</varname> geometry is not the same as the topology an exception is thrown.</para>
|
|
<!-- use this format if new function -->
|
|
<para>Availability: 2.0 </para>
|
|
<para>&sqlmm_compliant; SQL-MM: Topo-Geo and Topo-Net 3: Routine Details: X.3.13</para>
|
|
</refsection>
|
|
|
|
|
|
<refsection>
|
|
<title>Examples</title>
|
|
<para/>
|
|
<!--TODO: Need examples -->
|
|
</refsection>
|
|
|
|
<!-- Optionally add a "See Also" section -->
|
|
<refsection>
|
|
<title>See Also</title>
|
|
<para><xref linkend="ST_RemEdgeModFace"/></para>
|
|
<para><xref linkend="ST_AddEdgeNewFaces"/></para>
|
|
</refsection>
|
|
</refentry>
|
|
|
|
<refentry id="ST_RemEdgeNewFace">
|
|
<refnamediv>
|
|
<refname>ST_RemEdgeNewFace</refname>
|
|
|
|
<refpurpose>
|
|
Removes an edge and, if the removed edge separated two faces,
|
|
delete the original faces and replace them with a new face.
|
|
</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>integer <function>ST_RemEdgeNewFace</function></funcdef>
|
|
<paramdef><type>varchar </type> <parameter>atopology</parameter></paramdef>
|
|
<paramdef><type>integer </type> <parameter>anedge</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
</refsynopsisdiv>
|
|
|
|
<refsection>
|
|
<title>Description</title>
|
|
|
|
<para>
|
|
Removes an edge and, if the removed edge separated two faces,
|
|
delete the original faces and replace them with a new face.
|
|
</para>
|
|
|
|
<para>
|
|
Returns the id of a newly created face or NULL, if no new face is created.
|
|
No new face is created when the removed edge is dangling or isolated or
|
|
confined with the universe face (possibly making the universe flood into
|
|
the face on the other side).
|
|
</para>
|
|
|
|
<para>
|
|
Updates all existing joined edges and relationships accordingly.
|
|
</para>
|
|
|
|
<para>
|
|
Refuses to remove an edge participating in the definition of an
|
|
existing TopoGeometry.
|
|
Refuses to heal two faces if any TopoGeometry is defined by only
|
|
one of them (and not the other).
|
|
</para>
|
|
|
|
<para>
|
|
If any arguments are null, the given edge is unknown (must already exist in
|
|
the <varname>edge</varname> table of the topology schema), the topology
|
|
name is invalid then an error is thrown.
|
|
</para>
|
|
|
|
<!-- use this format if new function -->
|
|
<para>Availability: 2.0 </para>
|
|
<para>&sqlmm_compliant; SQL-MM: Topo-Geo and Topo-Net 3: Routine Details: X.3.14</para>
|
|
</refsection>
|
|
|
|
|
|
<refsection>
|
|
<title>Examples</title>
|
|
<para/>
|
|
<!--TODO: Need examples -->
|
|
</refsection>
|
|
|
|
<!-- Optionally add a "See Also" section -->
|
|
<refsection>
|
|
<title>See Also</title>
|
|
<para><xref linkend="ST_RemEdgeModFace"/></para>
|
|
<para><xref linkend="ST_AddEdgeNewFaces"/></para>
|
|
</refsection>
|
|
</refentry>
|
|
|
|
<refentry id="ST_RemEdgeModFace">
|
|
<refnamediv>
|
|
<refname>ST_RemEdgeModFace</refname>
|
|
|
|
<refpurpose>
|
|
Removes an edge, and if the edge separates two faces
|
|
deletes one face and modifies the other face to cover the space of both.
|
|
</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>integer <function>ST_RemEdgeModFace</function></funcdef>
|
|
<paramdef><type>varchar </type> <parameter>atopology</parameter></paramdef>
|
|
<paramdef><type>integer </type> <parameter>anedge</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
</refsynopsisdiv>
|
|
|
|
<refsection>
|
|
<title>Description</title>
|
|
|
|
<para>
|
|
Removes an edge, and if the removed edge separates two faces
|
|
deletes one face and modifies the other face to cover the space of both.
|
|
Preferentially keeps the face on the right, to be consistent with
|
|
<xref linkend="ST_AddEdgeModFace"/>.
|
|
Returns the id of the face which is preserved.
|
|
</para>
|
|
|
|
<para>
|
|
Updates all existing joined edges and relationships accordingly.
|
|
</para>
|
|
|
|
<para>
|
|
Refuses to remove an edge participating in the definition of an
|
|
existing TopoGeometry.
|
|
Refuses to heal two faces if any TopoGeometry is defined by only
|
|
one of them (and not the other).
|
|
</para>
|
|
|
|
<para>
|
|
If any arguments are null, the given edge is unknown (must already exist in
|
|
the <varname>edge</varname> table of the topology schema), the topology
|
|
name is invalid then an error is thrown.
|
|
</para>
|
|
|
|
<!-- use this format if new function -->
|
|
<para>Availability: 2.0 </para>
|
|
<para>&sqlmm_compliant; SQL-MM: Topo-Geo and Topo-Net 3: Routine Details: X.3.15</para>
|
|
</refsection>
|
|
|
|
|
|
<refsection>
|
|
<title>Examples</title>
|
|
<para/>
|
|
<!--TODO: Need examples -->
|
|
</refsection>
|
|
|
|
<!-- Optionally add a "See Also" section -->
|
|
<refsection>
|
|
<title>See Also</title>
|
|
<para><xref linkend="ST_AddEdgeModFace"/></para>
|
|
<para><xref linkend="ST_RemEdgeNewFace"/></para>
|
|
</refsection>
|
|
</refentry>
|
|
|
|
<refentry id="ST_ChangeEdgeGeom">
|
|
<refnamediv>
|
|
<refname>ST_ChangeEdgeGeom</refname>
|
|
|
|
<refpurpose>
|
|
Changes the shape of an edge without affecting the topology structure.
|
|
</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>integer <function>ST_ChangeEdgeGeom</function></funcdef>
|
|
<paramdef><type>varchar </type> <parameter>atopology</parameter></paramdef>
|
|
<paramdef><type>integer </type> <parameter>anedge</parameter></paramdef>
|
|
<paramdef><type>geometry </type> <parameter>acurve</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
</refsynopsisdiv>
|
|
|
|
<refsection>
|
|
<title>Description</title>
|
|
|
|
<para>
|
|
Changes the shape of an edge without affecting the topology structure.
|
|
</para>
|
|
<para>
|
|
If any arguments are null, the given edge does not exist in
|
|
the <varname>edge</varname> table of the topology schema, the
|
|
<varname>acurve</varname> is not a <varname>LINESTRING</varname>, or the modification would
|
|
change the underlying topology then an error is thrown.
|
|
</para>
|
|
<para>If the spatial reference system (srid) of the <varname>acurve</varname> geometry is not the same as the topology an exception is thrown.</para>
|
|
<para>If the new <varname>acurve</varname> is not simple, then an error is thrown.</para>
|
|
|
|
<para>
|
|
If moving the edge from old to new position would hit an obstacle then
|
|
an error is thrown.
|
|
</para>
|
|
|
|
<!-- use this format if new function -->
|
|
<para>Availability: 1.1.0</para>
|
|
|
|
<!-- use this format if not a new function but functionality enhanced -->
|
|
<para>
|
|
Enhanced: 2.0.0 adds topological consistency enforcement
|
|
</para>
|
|
|
|
<para>&sqlmm_compliant; SQL-MM: Topo-Geo and Topo-Net 3: Routine Details X.3.6</para>
|
|
</refsection>
|
|
|
|
|
|
<refsection>
|
|
<title>Examples</title>
|
|
<programlisting>SELECT topology.ST_ChangeEdgeGeom('ma_topo', 1,
|
|
ST_GeomFromText('LINESTRING(227591.9 893900.4,227622.6 893844.3,227641.6 893816.6, 227704.5 893778.5)', 26986) );
|
|
----
|
|
Edge 1 changed</programlisting>
|
|
</refsection>
|
|
|
|
<!-- Optionally add a "See Also" section -->
|
|
<refsection>
|
|
<title>See Also</title>
|
|
<para><xref linkend="ST_AddEdgeModFace"/></para>
|
|
<para><xref linkend="ST_RemEdgeModFace"/></para>
|
|
<para><xref linkend="ST_ModEdgeSplit"/></para>
|
|
</refsection>
|
|
</refentry>
|
|
|
|
<refentry id="ST_ModEdgeSplit">
|
|
<refnamediv>
|
|
<refname>ST_ModEdgeSplit</refname>
|
|
|
|
<refpurpose>Split an edge by creating a new node along an existing edge, modifying the original edge and adding a new edge.</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>integer <function>ST_ModEdgeSplit</function></funcdef>
|
|
<paramdef><type>varchar </type> <parameter>atopology</parameter></paramdef>
|
|
<paramdef><type>integer </type> <parameter>anedge</parameter></paramdef>
|
|
<paramdef><type>geometry </type> <parameter>apoint</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
</refsynopsisdiv>
|
|
|
|
<refsection>
|
|
<title>Description</title>
|
|
|
|
<para>
|
|
Split an edge by creating a new node along an existing edge,
|
|
modifying the original edge and adding a new edge.
|
|
Updates all existing joined edges and relationships accordingly.
|
|
Returns the identifier of the newly added node.
|
|
</para>
|
|
|
|
<!-- use this format if new function -->
|
|
<para>Availability: 1.1 </para>
|
|
<para>Changed: 2.0 - In prior versions, this was misnamed ST_ModEdgesSplit</para>
|
|
<para>&sqlmm_compliant; SQL-MM: Topo-Geo and Topo-Net 3: Routine Details: X.3.9</para>
|
|
</refsection>
|
|
|
|
|
|
<refsection>
|
|
<title>Examples</title>
|
|
<programlisting>
|
|
-- Add an edge --
|
|
SELECT topology.AddEdge('ma_topo', ST_GeomFromText('LINESTRING(227592 893910, 227600 893910)', 26986) ) As edgeid;
|
|
|
|
-- edgeid-
|
|
3
|
|
|
|
|
|
-- Split the edge --
|
|
SELECT topology.ST_ModEdgeSplit('ma_topo', 3, ST_SetSRID(ST_Point(227594,893910),26986) ) As node_id;
|
|
node_id
|
|
-------------------------
|
|
7
|
|
</programlisting>
|
|
</refsection>
|
|
|
|
<!-- Optionally add a "See Also" section -->
|
|
<refsection>
|
|
<title>See Also</title>
|
|
<para>
|
|
<xref linkend="ST_NewEdgesSplit"/>,
|
|
<xref linkend="ST_ModEdgeHeal"/>,
|
|
<xref linkend="ST_NewEdgeHeal"/>,
|
|
<xref linkend="AddEdge"/>
|
|
</para>
|
|
</refsection>
|
|
</refentry>
|
|
|
|
<refentry id="ST_ModEdgeHeal">
|
|
<refnamediv>
|
|
<refname>ST_ModEdgeHeal</refname>
|
|
|
|
<refpurpose>
|
|
Heals two edges by deleting the node connecting them, modifying the first edge
|
|
and deleting the second edge. Returns the id of the deleted node.
|
|
</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>int <function>ST_ModEdgeHeal</function></funcdef>
|
|
<paramdef><type>varchar </type> <parameter>atopology</parameter></paramdef>
|
|
<paramdef><type>integer </type> <parameter>anedge</parameter></paramdef>
|
|
<paramdef><type>integer </type> <parameter>anotheredge</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
</refsynopsisdiv>
|
|
|
|
<refsection>
|
|
<title>Description</title>
|
|
|
|
<para>
|
|
Heals two edges by deleting the node connecting them, modifying the first edge
|
|
and deleting the second edge.
|
|
Returns the id of the deleted node.
|
|
Updates all existing joined edges and relationships accordingly.
|
|
</para>
|
|
|
|
<!-- use this format if new function -->
|
|
<para>Availability: 2.0</para>
|
|
<para>&sqlmm_compliant; SQL-MM: Topo-Geo and Topo-Net 3: Routine Details: X.3.9</para>
|
|
</refsection>
|
|
|
|
|
|
<!-- Optionally add a "See Also" section -->
|
|
<refsection>
|
|
<title>See Also</title>
|
|
<para>
|
|
<xref linkend="ST_ModEdgeSplit"/>
|
|
<xref linkend="ST_NewEdgesSplit"/>
|
|
</para>
|
|
</refsection>
|
|
</refentry>
|
|
|
|
<refentry id="ST_NewEdgeHeal">
|
|
<refnamediv>
|
|
<refname>ST_NewEdgeHeal</refname>
|
|
|
|
<refpurpose>
|
|
Heals two edges by deleting the node connecting them, deleting both edges,
|
|
and replacing them with an edge whose direction is the same as the first
|
|
edge provided.
|
|
</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>int <function>ST_NewEdgeHeal</function></funcdef>
|
|
<paramdef><type>varchar </type> <parameter>atopology</parameter></paramdef>
|
|
<paramdef><type>integer </type> <parameter>anedge</parameter></paramdef>
|
|
<paramdef><type>integer </type> <parameter>anotheredge</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
</refsynopsisdiv>
|
|
|
|
<refsection>
|
|
<title>Description</title>
|
|
|
|
<para>
|
|
Heals two edges by deleting the node connecting them, deleting both edges,
|
|
and replacing them with an edge whose direction is the same as the first
|
|
edge provided.
|
|
Returns the id of the new edge replacing the healed ones.
|
|
Updates all existing joined edges and relationships accordingly.
|
|
</para>
|
|
|
|
|
|
<!-- use this format if new function -->
|
|
<para>Availability: 2.0</para>
|
|
<para>&sqlmm_compliant; SQL-MM: Topo-Geo and Topo-Net 3: Routine Details: X.3.9</para>
|
|
</refsection>
|
|
|
|
|
|
<!-- Optionally add a "See Also" section -->
|
|
<refsection>
|
|
<title>See Also</title>
|
|
<para>
|
|
<xref linkend="ST_ModEdgeHeal"/>
|
|
<xref linkend="ST_ModEdgeSplit"/>
|
|
<xref linkend="ST_NewEdgesSplit"/>
|
|
</para>
|
|
</refsection>
|
|
</refentry>
|
|
|
|
<refentry id="ST_MoveIsoNode">
|
|
<refnamediv>
|
|
<refname>ST_MoveIsoNode</refname>
|
|
|
|
<refpurpose>Moves an isolated node in a topology from one point to another. If new <varname>apoint</varname> geometry exists as a node an error is thrown. Returns description of move.</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>text <function>ST_MoveIsoNode</function></funcdef>
|
|
<paramdef><type>varchar </type> <parameter>atopology</parameter></paramdef>
|
|
<paramdef><type>integer </type> <parameter>anode</parameter></paramdef>
|
|
<paramdef><type>geometry </type> <parameter>apoint</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
</refsynopsisdiv>
|
|
|
|
<refsection>
|
|
<title>Description</title>
|
|
|
|
<para>Moves an isolated node in a topology from one point to another. If new <varname>apoint</varname> geometry exists as a node an error is thrown.</para>
|
|
<para>If any arguments are null, the
|
|
<varname>apoint</varname> is not a point, the existing node is not
|
|
isolated (is a start or end point of an existing edge), new node
|
|
location intersects an existing edge (even at the end points) or the
|
|
new location is in a different face (since 3.2.0) then an exception is thrown.
|
|
</para>
|
|
<para>If the spatial reference system (srid) of the point geometry is not the same as the topology an exception is thrown.</para>
|
|
|
|
|
|
<!-- use this format if new function -->
|
|
<para>Availability: 2.0.0 </para>
|
|
<para>
|
|
Enhanced: 3.2.0 ensures the nod cannot be moved in a different face
|
|
</para>
|
|
<para>&sqlmm_compliant; SQL-MM: Topo-Net Routines: X.3.2</para>
|
|
</refsection>
|
|
|
|
|
|
<refsection>
|
|
<title>Examples</title>
|
|
<programlisting>
|
|
-- Add an isolated node with no face --
|
|
SELECT topology.ST_AddIsoNode('ma_topo', NULL, ST_GeomFromText('POINT(227579 893916)', 26986) ) As nodeid;
|
|
nodeid
|
|
--------
|
|
7
|
|
-- Move the new node --
|
|
SELECT topology.ST_MoveIsoNode('ma_topo', 7, ST_GeomFromText('POINT(227579.5 893916.5)', 26986) ) As descrip;
|
|
descrip
|
|
----------------------------------------------------
|
|
Isolated Node 7 moved to location 227579.5,893916.5</programlisting>
|
|
</refsection>
|
|
|
|
<!-- Optionally add a "See Also" section -->
|
|
<refsection>
|
|
<title>See Also</title>
|
|
<para><xref linkend="ST_AddIsoNode"/></para>
|
|
</refsection>
|
|
</refentry>
|
|
<refentry id="ST_NewEdgesSplit">
|
|
<refnamediv>
|
|
<refname>ST_NewEdgesSplit</refname>
|
|
|
|
<refpurpose>Split an edge by creating a new node along an existing edge, deleting the original edge and replacing it with two new edges. Returns the id of the new node created that joins the new edges.</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>integer <function>ST_NewEdgesSplit</function></funcdef>
|
|
<paramdef><type>varchar </type> <parameter>atopology</parameter></paramdef>
|
|
<paramdef><type>integer </type> <parameter>anedge</parameter></paramdef>
|
|
<paramdef><type>geometry </type> <parameter>apoint</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
</refsynopsisdiv>
|
|
|
|
<refsection>
|
|
<title>Description</title>
|
|
|
|
<para>
|
|
Split an edge with edge id <varname>anedge</varname> by creating a
|
|
new node with point location <varname>apoint</varname> along current
|
|
edge, deleting the original edge and replacing it with two new edges.
|
|
Returns the id of the new node created that joins the new edges.
|
|
Updates all existing joined edges and relationships accordingly.
|
|
</para>
|
|
|
|
<para>If the spatial reference system (srid) of the point geometry is not the same as the topology, the <varname>apoint</varname> is not a point geometry, the point is null, the point already exists as a node, the edge does not correspond to an existing edge or the point is not within the edge then an exception is thrown.</para>
|
|
|
|
|
|
<!-- use this format if new function -->
|
|
<para>Availability: 1.1 </para>
|
|
<para>&sqlmm_compliant; SQL-MM: Topo-Net Routines: X.3.8</para>
|
|
</refsection>
|
|
|
|
|
|
<refsection>
|
|
<title>Examples</title>
|
|
<programlisting>
|
|
-- Add an edge --
|
|
SELECT topology.AddEdge('ma_topo', ST_GeomFromText('LINESTRING(227575 893917,227592 893900)', 26986) ) As edgeid;
|
|
-- result-
|
|
edgeid
|
|
------
|
|
2
|
|
-- Split the new edge --
|
|
SELECT topology.ST_NewEdgesSplit('ma_topo', 2, ST_GeomFromText('POINT(227578.5 893913.5)', 26986) ) As newnodeid;
|
|
newnodeid
|
|
---------
|
|
6</programlisting>
|
|
</refsection>
|
|
|
|
<!-- Optionally add a "See Also" section -->
|
|
<refsection>
|
|
<title>See Also</title>
|
|
<para>
|
|
<xref linkend="ST_ModEdgeSplit"/>
|
|
<xref linkend="ST_ModEdgeHeal"/>
|
|
<xref linkend="ST_NewEdgeHeal"/>
|
|
<xref linkend="AddEdge"/>
|
|
</para>
|
|
</refsection>
|
|
</refentry>
|
|
|
|
<refentry id="ST_RemoveIsoNode">
|
|
<refnamediv>
|
|
<refname>ST_RemoveIsoNode</refname>
|
|
|
|
<refpurpose>Removes an isolated node and returns description of action. If the node is not isolated (is start or end of an edge), then an exception is thrown.</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>text <function>ST_RemoveIsoNode</function></funcdef>
|
|
<paramdef><type>varchar </type> <parameter>atopology</parameter></paramdef>
|
|
<paramdef><type>integer </type> <parameter>anode</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
</refsynopsisdiv>
|
|
|
|
<refsection>
|
|
<title>Description</title>
|
|
|
|
<para>Removes an isolated node and returns description of action. If the node is not isolated (is start or end of an edge), then an exception is thrown.</para>
|
|
|
|
|
|
<!-- use this format if new function -->
|
|
<para>Availability: 1.1 </para>
|
|
<para>&sqlmm_compliant; SQL-MM: Topo-Geo and Topo-Net 3: Routine Details: X+1.3.3</para>
|
|
</refsection>
|
|
|
|
|
|
<refsection>
|
|
<title>Examples</title>
|
|
<programlisting>
|
|
-- Remove an isolated node with no face --
|
|
SELECT topology.ST_RemoveIsoNode('ma_topo', 7 ) As result;
|
|
result
|
|
-------------------------
|
|
Isolated node 7 removed
|
|
</programlisting>
|
|
</refsection>
|
|
|
|
<!-- Optionally add a "See Also" section -->
|
|
<refsection>
|
|
<title>See Also</title>
|
|
<para><xref linkend="ST_AddIsoNode"/></para>
|
|
</refsection>
|
|
</refentry>
|
|
|
|
<refentry id="ST_RemoveIsoEdge">
|
|
<refnamediv>
|
|
<refname>ST_RemoveIsoEdge</refname>
|
|
|
|
<refpurpose>Removes an isolated edge and returns description of action. If the edge is not isolated, then an exception is thrown.</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>text <function>ST_RemoveIsoEdge</function></funcdef>
|
|
<paramdef><type>varchar </type> <parameter>atopology</parameter></paramdef>
|
|
<paramdef><type>integer </type> <parameter>anedge</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
</refsynopsisdiv>
|
|
|
|
<refsection>
|
|
<title>Description</title>
|
|
|
|
<para>Removes an isolated edge and returns description of action. If the edge is not isolated, then an exception is thrown.</para>
|
|
|
|
|
|
<!-- use this format if new function -->
|
|
<para>Availability: 1.1 </para>
|
|
<para>&sqlmm_compliant; SQL-MM: Topo-Geo and Topo-Net 3: Routine Details: X+1.3.3</para>
|
|
</refsection>
|
|
|
|
|
|
<refsection>
|
|
<title>Examples</title>
|
|
<programlisting>
|
|
-- Remove an isolated node with no face --
|
|
SELECT topology.ST_RemoveIsoNode('ma_topo', 7 ) As result;
|
|
result
|
|
-------------------------
|
|
Isolated node 7 removed
|
|
</programlisting>
|
|
</refsection>
|
|
|
|
<!-- Optionally add a "See Also" section -->
|
|
<refsection>
|
|
<title>See Also</title>
|
|
<para><xref linkend="ST_AddIsoNode"/></para>
|
|
</refsection>
|
|
</refentry>
|
|
</sect1>
|
|
|
|
|
|
<sect1 id="Topology_Accessors">
|
|
<title>Topology Accessors</title>
|
|
<refentry id="GetEdgeByPoint">
|
|
<refnamediv>
|
|
<refname>GetEdgeByPoint</refname>
|
|
|
|
<refpurpose>Finds the edge-id of an edge that intersects a given point.</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>integer <function>GetEdgeByPoint</function></funcdef>
|
|
<paramdef><type>varchar </type> <parameter>atopology</parameter></paramdef>
|
|
<paramdef><type>geometry </type> <parameter>apoint</parameter></paramdef>
|
|
<paramdef><type>float8 </type> <parameter>tol1</parameter></paramdef>
|
|
</funcprototype>
|
|
|
|
</funcsynopsis>
|
|
</refsynopsisdiv>
|
|
|
|
<refsection>
|
|
<title>Description</title>
|
|
|
|
<para>Retrieves the id of an edge that intersects a Point.</para>
|
|
<para>The function returns an integer (id-edge) given a topology, a POINT and a tolerance. If tolerance = 0 then the point has to intersect the edge.</para>
|
|
<para>If <varname>apoint</varname> doesn't intersect an edge, returns 0 (zero).</para>
|
|
<para>If use tolerance > 0 and there is more than one edge near the point then an exception is thrown.</para>
|
|
|
|
|
|
<note>
|
|
<para>If tolerance = 0, the function uses ST_Intersects otherwise uses ST_DWithin.</para>
|
|
</note>
|
|
<para>Performed by the GEOS module.</para>
|
|
<para>Availability: 2.0.0</para>
|
|
</refsection>
|
|
|
|
|
|
<refsection>
|
|
<title>Examples</title>
|
|
<para>These examples use edges we created in <xref linkend="AddEdge" /></para>
|
|
<programlisting>SELECT topology.GetEdgeByPoint('ma_topo',geom, 1) As with1mtol, topology.GetEdgeByPoint('ma_topo',geom,0) As withnotol
|
|
FROM ST_GeomFromEWKT('SRID=26986;POINT(227622.6 893843)') As geom;
|
|
with1mtol | withnotol
|
|
-----------+-----------
|
|
2 | 0
|
|
</programlisting>
|
|
<programlisting>SELECT topology.GetEdgeByPoint('ma_topo',geom, 1) As nearnode
|
|
FROM ST_GeomFromEWKT('SRID=26986;POINT(227591.9 893900.4)') As geom;
|
|
|
|
-- get error --
|
|
ERROR: Two or more edges found</programlisting>
|
|
</refsection>
|
|
|
|
<!-- Optionally add a "See Also" section -->
|
|
<refsection>
|
|
<title>See Also</title>
|
|
|
|
<para>
|
|
<xref linkend="AddEdge" />,
|
|
<xref linkend="GetNodeByPoint" />,
|
|
<xref linkend="GetFaceByPoint" />
|
|
</para>
|
|
</refsection>
|
|
</refentry>
|
|
|
|
<refentry id="GetFaceByPoint">
|
|
<refnamediv>
|
|
<refname>GetFaceByPoint</refname>
|
|
<refpurpose>Finds face intersecting a given point.</refpurpose>
|
|
</refnamediv>
|
|
<refsynopsisdiv>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>integer <function>GetFaceByPoint</function></funcdef>
|
|
<paramdef><type>varchar </type> <parameter>atopology</parameter></paramdef>
|
|
<paramdef><type>geometry </type> <parameter>apoint</parameter></paramdef>
|
|
<paramdef><type>float8 </type> <parameter>tol1</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
</refsynopsisdiv>
|
|
<refsection>
|
|
<title>Description</title>
|
|
|
|
<para>
|
|
Finds a face referenced by a Point, with given tolerance.
|
|
</para>
|
|
|
|
<para>
|
|
The function will effectively look for a face intersecting a
|
|
circle having the point as center and the tolerance as radius.
|
|
</para>
|
|
|
|
<para>
|
|
If no face intersects the given query location, 0 is returned (universal face).
|
|
</para>
|
|
|
|
<para>
|
|
If more than one face intersect the query location an exception is thrown.
|
|
</para>
|
|
|
|
<para>Availability: 2.0.0</para>
|
|
<para>Enhanced: 3.2.0 more efficient implementation and clearer contract, stops working with invalid topologies.</para>
|
|
</refsection>
|
|
<refsection>
|
|
<title>Examples</title>
|
|
<programlisting>SELECT topology.GetFaceByPoint('ma_topo',geom, 10) As with1mtol, topology.GetFaceByPoint('ma_topo',geom,0) As withnotol
|
|
FROM ST_GeomFromEWKT('POINT(234604.6 899382.0)') As geom;
|
|
|
|
with1mtol | withnotol
|
|
-----------+-----------
|
|
1 | 0</programlisting>
|
|
|
|
<programlisting>SELECT topology.GetFaceByPoint('ma_topo',geom, 1) As nearnode
|
|
FROM ST_GeomFromEWKT('POINT(227591.9 893900.4)') As geom;
|
|
|
|
-- get error --
|
|
ERROR: Two or more faces found</programlisting>
|
|
</refsection>
|
|
<!-- Optionally add a "See Also" section -->
|
|
<refsection>
|
|
<title>See Also</title>
|
|
<para>
|
|
<xref linkend="GetFaceContainingPoint" />,
|
|
<xref linkend="AddFace" />,
|
|
<xref linkend="GetNodeByPoint" />,
|
|
<xref linkend="GetEdgeByPoint" />
|
|
</para>
|
|
</refsection>
|
|
</refentry>
|
|
|
|
<refentry id="GetFaceContainingPoint">
|
|
<refnamediv>
|
|
<refname>GetFaceContainingPoint</refname>
|
|
<refpurpose>Finds the face containing a point.</refpurpose>
|
|
</refnamediv>
|
|
<refsynopsisdiv>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>integer <function>GetFaceContainingPoint</function></funcdef>
|
|
<paramdef><type>text </type> <parameter>atopology</parameter></paramdef>
|
|
<paramdef><type>geometry </type> <parameter>apoint</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
</refsynopsisdiv>
|
|
<refsection>
|
|
<title>Description</title>
|
|
|
|
<para>Returns the id of the face containing a point.</para>
|
|
<para>An exception is thrown if the point falls on a face boundary.</para>
|
|
|
|
<note>
|
|
<para>The function relies on a valid topology, using edge linking and face labeling.</para>
|
|
</note>
|
|
|
|
<para>Availability: 3.2.0</para>
|
|
</refsection>
|
|
<refsection>
|
|
<title>See Also</title>
|
|
<para>
|
|
<xref linkend="ST_GetFaceGeometry"/>
|
|
</para>
|
|
</refsection>
|
|
</refentry>
|
|
|
|
<refentry id="GetNodeByPoint">
|
|
<refnamediv>
|
|
<refname>GetNodeByPoint</refname>
|
|
|
|
<refpurpose>Finds the node-id of a node at a point location.</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>integer <function>GetNodeByPoint</function></funcdef>
|
|
<paramdef><type>varchar </type> <parameter>atopology</parameter></paramdef>
|
|
<paramdef><type>geometry </type> <parameter>apoint</parameter></paramdef>
|
|
<paramdef><type>float8 </type> <parameter>tol1</parameter></paramdef>
|
|
</funcprototype>
|
|
|
|
</funcsynopsis>
|
|
</refsynopsisdiv>
|
|
|
|
<refsection>
|
|
<title>Description</title>
|
|
|
|
<para>Retrieves the id of a node at a point location.</para>
|
|
<para>The function returns an integer (id-node) given a topology, a POINT and a tolerance. If tolerance = 0 means exact intersection, otherwise retrieves the node from an interval.</para>
|
|
<para>If <varname>apoint</varname> doesn't intersect a node, returns 0 (zero).</para>
|
|
<para>If use tolerance > 0 and there is more than one node near the point then an exception is thrown.</para>
|
|
<note>
|
|
<para>If tolerance = 0, the function uses ST_Intersects otherwise uses ST_DWithin.</para>
|
|
</note>
|
|
<para>Performed by the GEOS module.</para>
|
|
<para>Availability: 2.0.0</para>
|
|
</refsection>
|
|
|
|
|
|
<refsection>
|
|
<title>Examples</title>
|
|
<para>These examples use edges we created in <xref linkend="AddEdge" /></para>
|
|
<programlisting>SELECT topology.GetNodeByPoint('ma_topo',geom, 1) As nearnode
|
|
FROM ST_GeomFromEWKT('SRID=26986;POINT(227591.9 893900.4)') As geom;
|
|
nearnode
|
|
----------
|
|
2
|
|
</programlisting>
|
|
<programlisting>SELECT topology.GetNodeByPoint('ma_topo',geom, 1000) As too_much_tolerance
|
|
FROM ST_GeomFromEWKT('SRID=26986;POINT(227591.9 893900.4)') As geom;
|
|
|
|
----get error--
|
|
ERROR: Two or more nodes found
|
|
</programlisting>
|
|
</refsection>
|
|
|
|
<!-- Optionally add a "See Also" section -->
|
|
<refsection>
|
|
<title>See Also</title>
|
|
|
|
<para>
|
|
<xref linkend="AddEdge" />,
|
|
<xref linkend="GetEdgeByPoint" />,
|
|
<xref linkend="GetFaceByPoint" />
|
|
</para>
|
|
</refsection>
|
|
</refentry>
|
|
|
|
<refentry id="GetTopologyID">
|
|
<refnamediv>
|
|
<refname>GetTopologyID</refname>
|
|
|
|
<refpurpose>Returns the id of a topology in the topology.topology table given the name of the topology.</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>integer <function>GetTopologyID</function></funcdef>
|
|
<paramdef><type>varchar</type> <parameter>toponame</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
</refsynopsisdiv>
|
|
|
|
<refsection>
|
|
<title>Description</title>
|
|
|
|
<para>Returns the id of a topology in the topology.topology table given the name of the topology.</para>
|
|
<!-- use this format if new function -->
|
|
<para>Availability: 1.1</para>
|
|
</refsection>
|
|
|
|
|
|
<refsection>
|
|
<title>Examples</title>
|
|
<programlisting>SELECT topology.GetTopologyID('ma_topo') As topo_id;
|
|
topo_id
|
|
---------
|
|
1</programlisting>
|
|
</refsection>
|
|
|
|
<!-- Optionally add a "See Also" section -->
|
|
<refsection>
|
|
<title>See Also</title>
|
|
<para>
|
|
<xref linkend="CreateTopology"/>,
|
|
<xref linkend="DropTopology"/>,
|
|
<xref linkend="GetTopologyName"/>,
|
|
<xref linkend="GetTopologySRID"/>
|
|
</para>
|
|
</refsection>
|
|
</refentry>
|
|
|
|
<refentry id="GetTopologySRID">
|
|
<refnamediv>
|
|
<refname>GetTopologySRID</refname>
|
|
|
|
<refpurpose>Returns the SRID of a topology in the topology.topology table given the name of the topology.</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>integer <function>GetTopologyID</function></funcdef>
|
|
<paramdef><type>varchar</type> <parameter>toponame</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
</refsynopsisdiv>
|
|
|
|
<refsection>
|
|
<title>Description</title>
|
|
|
|
<para>Returns the spatial reference id of a topology in the topology.topology table given the name of the topology.</para>
|
|
<!-- use this format if new function -->
|
|
<para>Availability: 2.0.0</para>
|
|
</refsection>
|
|
|
|
|
|
<refsection>
|
|
<title>Examples</title>
|
|
<programlisting>SELECT topology.GetTopologySRID('ma_topo') As SRID;
|
|
SRID
|
|
-------
|
|
4326</programlisting>
|
|
</refsection>
|
|
|
|
<!-- Optionally add a "See Also" section -->
|
|
<refsection>
|
|
<title>See Also</title>
|
|
<para>
|
|
<xref linkend="CreateTopology"/>,
|
|
<xref linkend="DropTopology"/>,
|
|
<xref linkend="GetTopologyName"/>,
|
|
<xref linkend="GetTopologyID"/>
|
|
</para>
|
|
</refsection>
|
|
</refentry>
|
|
|
|
<refentry id="GetTopologyName">
|
|
<refnamediv>
|
|
<refname>GetTopologyName</refname>
|
|
|
|
<refpurpose>Returns the name of a topology (schema) given the id of the topology.</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>varchar <function>GetTopologyName</function></funcdef>
|
|
<paramdef><type>integer</type> <parameter>topology_id</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
</refsynopsisdiv>
|
|
|
|
<refsection>
|
|
<title>Description</title>
|
|
|
|
<para>Returns the topology name (schema) of a topology from the topology.topology table given the topology id of the topology.</para>
|
|
<!-- use this format if new function -->
|
|
<para>Availability: 1.1</para>
|
|
</refsection>
|
|
|
|
|
|
<refsection>
|
|
<title>Examples</title>
|
|
<programlisting>SELECT topology.GetTopologyName(1) As topo_name;
|
|
topo_name
|
|
-----------
|
|
ma_topo</programlisting>
|
|
</refsection>
|
|
|
|
<!-- Optionally add a "See Also" section -->
|
|
<refsection>
|
|
<title>See Also</title>
|
|
<para>
|
|
<xref linkend="CreateTopology"/>,
|
|
<xref linkend="DropTopology"/>,
|
|
<xref linkend="GetTopologyID"/>,
|
|
<xref linkend="GetTopologySRID"/>
|
|
</para>
|
|
</refsection>
|
|
</refentry>
|
|
|
|
<refentry id="ST_GetFaceEdges">
|
|
<refnamediv>
|
|
<refname>ST_GetFaceEdges</refname>
|
|
|
|
<refpurpose>Returns a set of ordered edges that bound <varname>aface</varname>.</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>getfaceedges_returntype <function>ST_GetFaceEdges</function></funcdef>
|
|
<paramdef><type>varchar </type> <parameter>atopology</parameter></paramdef>
|
|
<paramdef><type>integer </type> <parameter>aface</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
</refsynopsisdiv>
|
|
|
|
<refsection>
|
|
<title>Description</title>
|
|
|
|
<para>Returns a set of ordered edges that bound <varname>aface</varname>. Each output consists of a sequence and edgeid. Sequence numbers start with value 1.</para>
|
|
|
|
<para>
|
|
Enumeration of each ring edges start from the edge with smallest identifier.
|
|
Order of edges follows a left-hand-rule (bound face is on the left of each directed edge).
|
|
</para>
|
|
|
|
<!-- use this format if new function -->
|
|
<para>Availability: 2.0 </para>
|
|
<para>&sqlmm_compliant; SQL-MM 3 Topo-Geo and Topo-Net 3: Routine Details: X.3.5</para>
|
|
</refsection>
|
|
|
|
|
|
<refsection>
|
|
<title>Examples</title>
|
|
<programlisting>
|
|
-- Returns the edges bounding face 1
|
|
SELECT (topology.ST_GetFaceEdges('tt', 1)).*;
|
|
-- result --
|
|
sequence | edge
|
|
----------+------
|
|
1 | -4
|
|
2 | 5
|
|
3 | 7
|
|
4 | -6
|
|
5 | 1
|
|
6 | 2
|
|
7 | 3
|
|
(7 rows)
|
|
</programlisting>
|
|
<programlisting>
|
|
-- Returns the sequence, edge id
|
|
-- and geometry of the edges that bound face 1
|
|
-- If you just need geom and seq, can use ST_GetFaceGeometry
|
|
SELECT t.seq, t.edge, geom
|
|
FROM topology.ST_GetFaceEdges('tt',1) As t(seq,edge)
|
|
INNER JOIN tt.edge AS e ON abs(t.edge) = e.edge_id;
|
|
</programlisting>
|
|
</refsection>
|
|
|
|
<!-- Optionally add a "See Also" section -->
|
|
<refsection>
|
|
<title>See Also</title>
|
|
<para>
|
|
<xref linkend="GetRingEdges"/>,
|
|
<xref linkend="AddFace"/>,
|
|
<xref linkend="ST_GetFaceGeometry"/>
|
|
</para>
|
|
</refsection>
|
|
</refentry>
|
|
|
|
<refentry id="ST_GetFaceGeometry">
|
|
<refnamediv>
|
|
<refname>ST_GetFaceGeometry</refname>
|
|
|
|
<refpurpose>Returns the polygon in the given topology with the specified face id.</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>geometry <function>ST_GetFaceGeometry</function></funcdef>
|
|
<paramdef><type>varchar </type> <parameter>atopology</parameter></paramdef>
|
|
<paramdef><type>integer </type> <parameter>aface</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
</refsynopsisdiv>
|
|
|
|
<refsection>
|
|
<title>Description</title>
|
|
|
|
<para>Returns the polygon in the given topology with the specified face id. Builds the polygon from the edges making up the face.</para>
|
|
|
|
|
|
<!-- use this format if new function -->
|
|
<para>Availability: 1.1 </para>
|
|
<para>&sqlmm_compliant; SQL-MM 3 Topo-Geo and Topo-Net 3: Routine Details: X.3.16</para>
|
|
</refsection>
|
|
|
|
|
|
<refsection>
|
|
<title>Examples</title>
|
|
<programlisting>
|
|
-- Returns the wkt of the polygon added with AddFace
|
|
SELECT ST_AsText(topology.ST_GetFaceGeometry('ma_topo', 1)) As facegeomwkt;
|
|
-- result --
|
|
facegeomwkt
|
|
|
|
--------------------------------------------------------------------------------
|
|
POLYGON((234776.9 899563.7,234896.5 899456.7,234914 899436.4,234946.6 899356.9,
|
|
234872.5 899328.7,234891 899285.4,234992.5 899145,234890.6 899069,
|
|
234755.2 899255.4,234612.7 899379.4,234776.9 899563.7))
|
|
</programlisting>
|
|
</refsection>
|
|
|
|
<!-- Optionally add a "See Also" section -->
|
|
<refsection>
|
|
<title>See Also</title>
|
|
<para><xref linkend="AddFace"/></para>
|
|
</refsection>
|
|
</refentry>
|
|
|
|
<refentry id="GetRingEdges">
|
|
<refnamediv>
|
|
<refname>GetRingEdges</refname>
|
|
|
|
<refpurpose>
|
|
Returns the ordered set of signed edge identifiers met by walking on an
|
|
a given edge side.
|
|
</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>getfaceedges_returntype <function>GetRingEdges</function></funcdef>
|
|
<paramdef><type>varchar </type> <parameter>atopology</parameter></paramdef>
|
|
<paramdef><type>integer </type> <parameter>aring</parameter></paramdef>
|
|
<paramdef choice="opt"><type>integer </type> <parameter>max_edges=null</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
</refsynopsisdiv>
|
|
|
|
<refsection>
|
|
<title>Description</title>
|
|
|
|
<para>
|
|
Returns the ordered set of signed edge identifiers met by walking on an
|
|
a given edge side.
|
|
Each output consists of a sequence and a signed edge id.
|
|
Sequence numbers start with value 1.
|
|
</para>
|
|
|
|
<para>
|
|
If you pass a positive edge id, the walk starts on the left side
|
|
of the corresponding edge and follows the edge direction.
|
|
If you pass a negative edge id, the walk starts on the right side
|
|
of it and goes backward.
|
|
</para>
|
|
|
|
<para>
|
|
If <varname>max_edges</varname> is not null no more than those records
|
|
are returned by that function. This is meant to be a safety parameter
|
|
when dealing with possibly invalid topologies.
|
|
</para>
|
|
|
|
<note><para>
|
|
This function uses edge ring linking metadata.
|
|
</para></note>
|
|
|
|
<!-- use this format if new function -->
|
|
<para>Availability: 2.0.0 </para>
|
|
</refsection>
|
|
|
|
|
|
<!-- Optionally add a "See Also" section -->
|
|
<refsection>
|
|
<title>See Also</title>
|
|
<para>
|
|
<xref linkend="ST_GetFaceEdges"/>,
|
|
<xref linkend="GetNodeEdges"/>
|
|
</para>
|
|
</refsection>
|
|
</refentry>
|
|
|
|
<refentry id="GetNodeEdges">
|
|
<refnamediv>
|
|
<refname>GetNodeEdges</refname>
|
|
|
|
<refpurpose>
|
|
Returns an ordered set of edges incident to the given node.
|
|
</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>getfaceedges_returntype <function>GetNodeEdges</function></funcdef>
|
|
<paramdef><type>varchar </type> <parameter>atopology</parameter></paramdef>
|
|
<paramdef><type>integer </type> <parameter>anode</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
</refsynopsisdiv>
|
|
|
|
<refsection>
|
|
<title>Description</title>
|
|
|
|
<para>
|
|
Returns an ordered set of edges incident to the given node.
|
|
Each output consists of a sequence and a signed edge id.
|
|
Sequence numbers start with value 1.
|
|
A positive edge starts at the given node.
|
|
A negative edge ends into the given node.
|
|
Closed edges will appear twice (with both signs).
|
|
Order is clockwise starting from northbound.
|
|
</para>
|
|
|
|
<note>
|
|
<para>
|
|
This function computes ordering rather than deriving from metadata
|
|
and is thus usable to build edge ring linking.
|
|
</para>
|
|
</note>
|
|
|
|
<!-- use this format if new function -->
|
|
<para>Availability: 2.0 </para>
|
|
</refsection>
|
|
|
|
<!-- Optionally add a "See Also" section -->
|
|
<refsection>
|
|
<title>See Also</title>
|
|
<para>
|
|
<xref linkend="getfaceedges_returntype"/>,
|
|
<xref linkend="GetRingEdges"/>,
|
|
<xref linkend="ST_Azimuth"/>
|
|
</para>
|
|
</refsection>
|
|
</refentry>
|
|
|
|
</sect1>
|
|
|
|
|
|
<sect1 id="Topology_Processing">
|
|
<sect1info>
|
|
<abstract>
|
|
<para>This section covers the functions for processing topologies in non-standard ways.</para>
|
|
</abstract>
|
|
</sect1info>
|
|
<title>Topology Processing</title>
|
|
<refentry id="TopologyPolygonize">
|
|
<refnamediv>
|
|
<refname>Polygonize</refname>
|
|
<refpurpose>Finds and registers all faces defined by topology edges.</refpurpose>
|
|
</refnamediv>
|
|
<refsynopsisdiv>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>text <function>Polygonize</function></funcdef>
|
|
<paramdef><type>varchar </type> <parameter>toponame</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
</refsynopsisdiv>
|
|
|
|
<refsection>
|
|
<title>Description</title>
|
|
|
|
<para>Registers all faces that can be built out a topology edge primitives.</para>
|
|
<para>The target topology is assumed to contain no self-intersecting edges.</para>
|
|
<note><para>Already known faces are recognized, so it is safe to call Polygonize multiple times on the same topology.</para></note>
|
|
<note><para>
|
|
This function does not use nor set the next_left_edge and next_right_edge fields of the edge table.
|
|
</para></note>
|
|
|
|
|
|
<!-- use this format if new function -->
|
|
<para>Availability: 2.0.0</para>
|
|
</refsection>
|
|
|
|
<!-- Optionally add a "See Also" section -->
|
|
<refsection>
|
|
<title>See Also</title>
|
|
<para><xref linkend="AddFace"/>, <xref linkend="ST_Polygonize"/></para>
|
|
</refsection>
|
|
</refentry>
|
|
|
|
<refentry id="AddNode">
|
|
<refnamediv>
|
|
<refname>AddNode</refname>
|
|
|
|
<refpurpose>Adds a point node to the node table in the specified topology schema and returns the nodeid of new node. If point already exists as node, the existing nodeid is returned.</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>integer <function>AddNode</function></funcdef>
|
|
<paramdef><type>varchar </type> <parameter>toponame</parameter></paramdef>
|
|
<paramdef><type>geometry </type> <parameter>apoint</parameter></paramdef>
|
|
<paramdef choice="opt"><type>boolean </type> <parameter>allowEdgeSplitting=false</parameter></paramdef>
|
|
<paramdef choice="opt"><type>boolean </type> <parameter>computeContainingFace=false</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
</refsynopsisdiv>
|
|
|
|
<refsection>
|
|
<title>Description</title>
|
|
|
|
<para>
|
|
Adds a point node to the node table in the specified topology schema.
|
|
The <xref linkend="AddEdge" /> function automatically adds start and end
|
|
points of an edge when called so not necessary to explicitly add nodes
|
|
of an edge.
|
|
</para>
|
|
|
|
<para>
|
|
If any edge crossing the node is found either an exception is raised or
|
|
the edge is split, depending on the <varname>allowEdgeSplitting</varname>
|
|
parameter value.
|
|
</para>
|
|
|
|
<para>
|
|
If <varname>computeContainingFace</varname> is true a newly added node would
|
|
get the correct containing face computed.
|
|
</para>
|
|
|
|
<note><para>If the <varname>apoint</varname> geometry already exists as a node, the node is not added but the existing nodeid is returned.</para></note>
|
|
|
|
<!-- use this format if new function -->
|
|
<para>Availability: 2.0.0</para>
|
|
</refsection>
|
|
|
|
|
|
<refsection>
|
|
<title>Examples</title>
|
|
<programlisting>SELECT topology.AddNode('ma_topo', ST_GeomFromText('POINT(227641.6 893816.5)', 26986) ) As nodeid;
|
|
-- result --
|
|
nodeid
|
|
--------
|
|
4
|
|
|
|
</programlisting>
|
|
</refsection>
|
|
|
|
<!-- Optionally add a "See Also" section -->
|
|
<refsection>
|
|
<title>See Also</title>
|
|
<para><xref linkend="AddEdge"/>, <xref linkend="CreateTopology"/></para>
|
|
</refsection>
|
|
</refentry>
|
|
|
|
<refentry id="AddEdge">
|
|
<refnamediv>
|
|
<refname>AddEdge</refname>
|
|
|
|
<refpurpose>Adds a linestring edge to the edge table and associated start and end points to the point nodes table of the specified topology schema using the specified linestring geometry and returns the edgeid of the new (or existing) edge.</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>integer <function>AddEdge</function></funcdef>
|
|
<paramdef><type>varchar </type> <parameter>toponame</parameter></paramdef>
|
|
<paramdef><type>geometry </type> <parameter>aline</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
</refsynopsisdiv>
|
|
|
|
<refsection>
|
|
<title>Description</title>
|
|
|
|
<para>Adds an edge to the edge table and associated nodes to the nodes table of the specified <varname>toponame</varname> schema using the specified linestring geometry and returns the edgeid of the new or existing record.
|
|
The newly added edge has "universe" face on both sides and links to itself.</para>
|
|
<note><para>If the <varname>aline</varname> geometry crosses, overlaps, contains or is contained by an existing linestring edge, then an error is thrown and the edge is not added.</para></note>
|
|
<note><para>The geometry of <varname>aline</varname> must have the same <varname>srid</varname> as defined for the topology otherwise an invalid spatial reference sys error will be thrown.</para></note>
|
|
<para>Performed by the GEOS module.</para>
|
|
<para>Availability: 2.0.0</para>
|
|
</refsection>
|
|
|
|
<refsection>
|
|
<title>Examples</title>
|
|
<programlisting>SELECT topology.AddEdge('ma_topo', ST_GeomFromText('LINESTRING(227575.8 893917.2,227591.9 893900.4)', 26986) ) As edgeid;
|
|
-- result-
|
|
edgeid
|
|
--------
|
|
1
|
|
|
|
SELECT topology.AddEdge('ma_topo', ST_GeomFromText('LINESTRING(227591.9 893900.4,227622.6 893844.2,227641.6 893816.5,
|
|
227704.5 893778.5)', 26986) ) As edgeid;
|
|
-- result --
|
|
edgeid
|
|
--------
|
|
2
|
|
|
|
SELECT topology.AddEdge('ma_topo', ST_GeomFromText('LINESTRING(227591.2 893900, 227591.9 893900.4,
|
|
227704.5 893778.5)', 26986) ) As edgeid;
|
|
-- gives error --
|
|
ERROR: Edge intersects (not on endpoints) with existing edge 1
|
|
</programlisting>
|
|
</refsection>
|
|
|
|
<!-- Optionally add a "See Also" section -->
|
|
<refsection>
|
|
<title>See Also</title>
|
|
<para>
|
|
<xref linkend="TopoGeo_AddLineString"/>,
|
|
<xref linkend="CreateTopology"/>,
|
|
<xref linkend="spatial_ref_sys"/>
|
|
</para>
|
|
</refsection>
|
|
</refentry>
|
|
|
|
<refentry id="AddFace">
|
|
<refnamediv>
|
|
<refname>AddFace</refname>
|
|
|
|
<refpurpose>Registers a face primitive to a topology and gets its identifier.</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>integer <function>AddFace</function></funcdef>
|
|
<paramdef><type>varchar </type> <parameter>toponame</parameter></paramdef>
|
|
<paramdef><type>geometry </type> <parameter>apolygon</parameter></paramdef>
|
|
<paramdef choice="opt"><type>boolean </type> <parameter>force_new=false</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
</refsynopsisdiv>
|
|
|
|
<refsection>
|
|
<title>Description</title>
|
|
|
|
<para>
|
|
Registers a face primitive to a topology and gets its identifier.
|
|
</para>
|
|
|
|
<para>
|
|
For a newly added face, the edges forming its boundaries and the ones
|
|
contained in the face will be updated to have correct values in the
|
|
left_face and right_face fields.
|
|
Isolated nodes contained in the face will also be updated to have a correct
|
|
containing_face field value.
|
|
</para>
|
|
|
|
<note><para>
|
|
This function does not use nor set the next_left_edge and next_right_edge fields of the edge table.
|
|
</para></note>
|
|
|
|
<para>The target topology is assumed to be valid (containing no self-intersecting edges). An exception is raised if: The polygon boundary is not fully defined by existing edges or the polygon overlaps an existing face.</para>
|
|
|
|
<para>
|
|
If the <varname>apolygon</varname> geometry already exists as a face, then:
|
|
if <varname>force_new</varname> is false (the default) the
|
|
face id of the existing face is returned;
|
|
if <varname>force_new</varname> is true a new id will be assigned to
|
|
the newly registered face.
|
|
</para>
|
|
|
|
<note><para>
|
|
When a new registration of an existing face is performed (force_new=true),
|
|
no action will be taken to resolve dangling references to the existing
|
|
face in the edge, node an relation tables, nor will the MBR field of the
|
|
existing face record be updated. It is up to the caller to deal with that.
|
|
</para></note>
|
|
|
|
<note><para>The <varname>apolygon</varname> geometry must have the same <varname>srid</varname> as defined for the topology otherwise an invalid spatial reference sys error will be thrown.</para></note>
|
|
|
|
<!-- use this format if new function -->
|
|
<para>Availability: 2.0.0</para>
|
|
</refsection>
|
|
|
|
|
|
<refsection>
|
|
<title>Examples</title>
|
|
<programlisting>
|
|
-- first add the edges we use generate_series as an iterator (the below
|
|
-- will only work for polygons with < 10000 points because of our max in gs)
|
|
SELECT topology.AddEdge('ma_topo', ST_MakeLine(ST_PointN(geom,i), ST_PointN(geom, i + 1) )) As edgeid
|
|
FROM (SELECT ST_NPoints(geom) AS npt, geom
|
|
FROM
|
|
(SELECT ST_Boundary(ST_GeomFromText('POLYGON((234896.5 899456.7,234914 899436.4,234946.6 899356.9,234872.5 899328.7,
|
|
234891 899285.4,234992.5 899145, 234890.6 899069,234755.2 899255.4,
|
|
234612.7 899379.4,234776.9 899563.7,234896.5 899456.7))', 26986) ) As geom
|
|
) As geoms) As facen CROSS JOIN generate_series(1,10000) As i
|
|
WHERE i < npt;
|
|
-- result --
|
|
edgeid
|
|
--------
|
|
3
|
|
4
|
|
5
|
|
6
|
|
7
|
|
8
|
|
9
|
|
10
|
|
11
|
|
12
|
|
(10 rows)
|
|
-- then add the face -
|
|
|
|
SELECT topology.AddFace('ma_topo',
|
|
ST_GeomFromText('POLYGON((234896.5 899456.7,234914 899436.4,234946.6 899356.9,234872.5 899328.7,
|
|
234891 899285.4,234992.5 899145, 234890.6 899069,234755.2 899255.4,
|
|
234612.7 899379.4,234776.9 899563.7,234896.5 899456.7))', 26986) ) As faceid;
|
|
-- result --
|
|
faceid
|
|
--------
|
|
1
|
|
|
|
</programlisting>
|
|
</refsection>
|
|
|
|
<!-- Optionally add a "See Also" section -->
|
|
<refsection>
|
|
<title>See Also</title>
|
|
<para><xref linkend="AddEdge"/>, <xref linkend="CreateTopology"/>, <xref linkend="spatial_ref_sys"/></para>
|
|
</refsection>
|
|
</refentry>
|
|
|
|
<refentry id="TP_ST_Simplify">
|
|
<refnamediv>
|
|
<refname>ST_Simplify</refname>
|
|
<refpurpose>Returns a "simplified" geometry version of the given TopoGeometry using
|
|
the Douglas-Peucker algorithm.</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>geometry <function>ST_Simplify</function></funcdef>
|
|
<paramdef><type>TopoGeometry</type> <parameter>tg</parameter></paramdef>
|
|
<paramdef><type>float8</type> <parameter>tolerance</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
</refsynopsisdiv>
|
|
|
|
<refsection>
|
|
<title>Description</title>
|
|
<para>Returns a "simplified" geometry version of the given TopoGeometry using
|
|
the Douglas-Peucker algorithm on each component edge.</para>
|
|
|
|
<note><para>The returned geometry may be non-simple or non-valid.</para>
|
|
<para>Splitting component edges may help retaining simplicity/validity.</para></note>
|
|
|
|
<para>Performed by the GEOS module.</para>
|
|
<para>Availability: 2.1.0</para>
|
|
</refsection>
|
|
|
|
<refsection>
|
|
<title>See Also</title>
|
|
<para>Geometry <xref linkend="ST_Simplify" />, <xref linkend="ST_IsSimple" />, <xref linkend="ST_IsValid" />, <xref linkend="ST_ModEdgeSplit" /></para>
|
|
</refsection>
|
|
</refentry>
|
|
|
|
<refentry id="TP_RemoveUnusedPrimitives">
|
|
<refnamediv>
|
|
<refname>RemoveUnusedPrimitives</refname>
|
|
<refpurpose>Removes topology primitives which not needed to define existing TopoGeometry objects.</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>int <function>RemoveUnusedPrimitives</function></funcdef>
|
|
<paramdef><type>text</type> <parameter>topology_name</parameter></paramdef>
|
|
<paramdef><type>geometry</type> <parameter>bbox</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
</refsynopsisdiv>
|
|
|
|
<refsection>
|
|
<title>Description</title>
|
|
<para>
|
|
Finds all primitives (nodes, edges, faces) that are not
|
|
strictly needed to represent existing TopoGeometry objects and removes
|
|
them, maintaining topology validity (edge linking, face labeling)
|
|
and TopoGeometry space occupation.
|
|
</para>
|
|
|
|
<para>
|
|
No new primitive identifiers are created, but rather existing primitives
|
|
are expanded to include merged faces (upon removing edges) or healed edges
|
|
(upon removing nodes).
|
|
</para>
|
|
|
|
<para>Availability: 3.3.0</para>
|
|
</refsection>
|
|
|
|
<refsection>
|
|
<title>See Also</title>
|
|
<para>
|
|
<xref linkend="ST_ModEdgeHeal" />,
|
|
<xref linkend="ST_RemEdgeModFace" />
|
|
</para>
|
|
</refsection>
|
|
</refentry>
|
|
|
|
|
|
</sect1>
|
|
|
|
<sect1 id="TopoGeometry_Constructors">
|
|
<sect1info>
|
|
<abstract>
|
|
<para>This section covers the topology functions for creating new topogeometries.</para>
|
|
</abstract>
|
|
</sect1info>
|
|
<title>TopoGeometry Constructors</title>
|
|
<refentry id="CreateTopoGeom">
|
|
<refnamediv>
|
|
<refname>CreateTopoGeom</refname>
|
|
|
|
<refpurpose>Creates a new topo geometry object from topo element array - tg_type: 1:[multi]point, 2:[multi]line, 3:[multi]poly, 4:collection</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>topogeometry <function>CreateTopoGeom</function></funcdef>
|
|
<paramdef><type>varchar </type> <parameter>toponame</parameter></paramdef>
|
|
<paramdef><type>integer </type> <parameter>tg_type</parameter></paramdef>
|
|
<paramdef><type>integer</type> <parameter>layer_id</parameter></paramdef>
|
|
<paramdef><type>topoelementarray</type> <parameter>tg_objs</parameter></paramdef>
|
|
</funcprototype>
|
|
|
|
<funcprototype>
|
|
<funcdef>topogeometry <function>CreateTopoGeom</function></funcdef>
|
|
<paramdef><type>varchar </type> <parameter>toponame</parameter></paramdef>
|
|
<paramdef><type>integer </type> <parameter>tg_type</parameter></paramdef>
|
|
<paramdef><type>integer</type> <parameter>layer_id</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
</refsynopsisdiv>
|
|
|
|
<refsection>
|
|
<title>Description</title>
|
|
|
|
<para>Creates a topogeometry object for layer denoted by <varname>layer_id</varname> and registers it in the relations table in the <varname>toponame</varname> schema.</para>
|
|
<para><varname>tg_type</varname> is an integer: 1:[multi]point (punctal), 2:[multi]line (lineal), 3:[multi]poly (areal), 4:collection. <varname>layer_id</varname> is the layer id in the topology.layer table.</para>
|
|
<para>punctal layers are formed from set of nodes, lineal layers are formed from a set of edges, areal layers are formed from a set of faces,
|
|
and collections can be formed from a mixture of nodes, edges, and faces.</para>
|
|
<para>Omitting the array of components generates an empty TopoGeometry object.</para>
|
|
<!-- use this format if new function -->
|
|
<para>Availability: 1.1</para>
|
|
</refsection>
|
|
|
|
|
|
<refsection>
|
|
<title>Examples: Form from existing edges</title>
|
|
<para>Create a topogeom in ri_topo schema for layer 2 (our ri_roads), of type (2) LINE, for the first edge (we loaded in <varname>ST_CreateTopoGeo</varname>).</para>
|
|
<programlisting>INSERT INTO ri.ri_roads(road_name, topo) VALUES('Unknown', topology.CreateTopoGeom('ri_topo',2,2,'{{1,2}}'::topology.topoelementarray);</programlisting>
|
|
|
|
</refsection>
|
|
|
|
<refsection>
|
|
<title>Examples: Convert an areal geometry to best guess topogeometry</title>
|
|
<para>Lets say we have geometries that should be formed from a collection of faces. We have for example blockgroups table
|
|
and want to know the topo geometry of each block group. If our data was perfectly aligned, we could do this:</para>
|
|
<programlisting>
|
|
-- create our topo geometry column --
|
|
SELECT topology.AddTopoGeometryColumn(
|
|
'topo_boston',
|
|
'boston', 'blockgroups', 'topo', 'POLYGON');
|
|
|
|
-- addtopgeometrycolumn --
|
|
1
|
|
|
|
-- update our column assuming
|
|
-- everything is perfectly aligned with our edges
|
|
UPDATE boston.blockgroups AS bg
|
|
SET topo = topology.CreateTopoGeom('topo_boston'
|
|
,3,1
|
|
, foo.bfaces)
|
|
FROM (SELECT b.gid, topology.TopoElementArray_Agg(ARRAY[f.face_id,3]) As bfaces
|
|
FROM boston.blockgroups As b
|
|
INNER JOIN topo_boston.face As f ON b.geom && f.mbr
|
|
WHERE ST_Covers(b.geom, topology.ST_GetFaceGeometry('topo_boston', f.face_id))
|
|
GROUP BY b.gid) As foo
|
|
WHERE foo.gid = bg.gid;
|
|
</programlisting>
|
|
|
|
<programlisting>
|
|
--the world is rarely perfect allow for some error
|
|
--count the face if 50% of it falls
|
|
-- within what we think is our blockgroup boundary
|
|
UPDATE boston.blockgroups AS bg
|
|
SET topo = topology.CreateTopoGeom('topo_boston'
|
|
,3,1
|
|
, foo.bfaces)
|
|
FROM (SELECT b.gid, topology.TopoElementArray_Agg(ARRAY[f.face_id,3]) As bfaces
|
|
FROM boston.blockgroups As b
|
|
INNER JOIN topo_boston.face As f ON b.geom && f.mbr
|
|
WHERE ST_Covers(b.geom, topology.ST_GetFaceGeometry('topo_boston', f.face_id))
|
|
OR
|
|
( ST_Intersects(b.geom, topology.ST_GetFaceGeometry('topo_boston', f.face_id))
|
|
AND ST_Area(ST_Intersection(b.geom, topology.ST_GetFaceGeometry('topo_boston', f.face_id) ) ) >
|
|
ST_Area(topology.ST_GetFaceGeometry('topo_boston', f.face_id))*0.5
|
|
)
|
|
GROUP BY b.gid) As foo
|
|
WHERE foo.gid = bg.gid;
|
|
|
|
-- and if we wanted to convert our topogeometry back
|
|
-- to a denormalized geometry aligned with our faces and edges
|
|
-- cast the topo to a geometry
|
|
-- The really cool thing is my new geometries
|
|
-- are now aligned with my tiger street centerlines
|
|
UPDATE boston.blockgroups SET new_geom = topo::geometry;
|
|
</programlisting>
|
|
</refsection>
|
|
|
|
<!-- Optionally add a "See Also" section -->
|
|
<refsection>
|
|
<title>See Also</title>
|
|
<para>
|
|
<xref linkend="AddTopoGeometryColumn"/>,
|
|
<xref linkend="toTopoGeom" />
|
|
<xref linkend="ST_CreateTopoGeo" />,
|
|
<xref linkend="ST_GetFaceGeometry"/>,
|
|
<xref linkend="topoelementarray" />,
|
|
<xref linkend="TopoElementArray_Agg" />
|
|
</para>
|
|
</refsection>
|
|
</refentry>
|
|
|
|
<refentry id="toTopoGeom">
|
|
<refnamediv>
|
|
<refname>toTopoGeom</refname>
|
|
|
|
<refpurpose>Converts a simple Geometry into a topo geometry.</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>topogeometry <function>toTopoGeom</function></funcdef>
|
|
<paramdef><type>geometry </type> <parameter>geom</parameter></paramdef>
|
|
<paramdef><type>varchar </type> <parameter>toponame</parameter></paramdef>
|
|
<paramdef><type>integer</type> <parameter>layer_id</parameter></paramdef>
|
|
<paramdef choice="opt"><type>float8</type> <parameter>tolerance</parameter></paramdef>
|
|
</funcprototype>
|
|
|
|
<funcprototype>
|
|
<funcdef>topogeometry <function>toTopoGeom</function></funcdef>
|
|
<paramdef><type>geometry </type> <parameter>geom</parameter></paramdef>
|
|
<paramdef><type>topogeometry </type> <parameter>topogeom</parameter></paramdef>
|
|
<paramdef choice="opt"><type>float8</type> <parameter>tolerance</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
</refsynopsisdiv>
|
|
|
|
<refsection>
|
|
<title>Description</title>
|
|
|
|
<para>
|
|
Converts a simple Geometry into a <xref linkend="topogeometry" />.
|
|
</para>
|
|
|
|
<para>
|
|
Topological primitives required to represent the input geometry will be
|
|
added to the underlying topology, possibly splitting existing ones,
|
|
and they will be associated with the output TopoGeometry in the
|
|
<varname>relation</varname> table.
|
|
</para>
|
|
|
|
<para>
|
|
Existing TopoGeometry objects (with the possible exception of
|
|
<varname>topogeom</varname>, if given) will retain their shapes.
|
|
</para>
|
|
|
|
<para>
|
|
When <varname>tolerance</varname> is given it will be used to snap the
|
|
input geometry to existing primitives.
|
|
</para>
|
|
|
|
<para>
|
|
In the first form a new TopoGeometry will be created for the given
|
|
layer (<varname>layer_id</varname>) of the given topology (<varname>toponame</varname>).
|
|
</para>
|
|
|
|
<para>
|
|
In the second form the primitives resulting from the conversion will be
|
|
added to the pre-existing TopoGeometry (<varname>topogeom</varname>),
|
|
possibly adding space to its final shape. To have the new shape completely
|
|
replace the old one see <xref linkend="clearTopoGeom" />.
|
|
</para>
|
|
|
|
<!-- use this format if new function -->
|
|
<para>Availability: 2.0</para>
|
|
<para>Enhanced: 2.1.0 adds the version taking an existing TopoGeometry.</para>
|
|
</refsection>
|
|
<refsection>
|
|
<title>Examples</title>
|
|
<para>This is a full self-contained workflow</para>
|
|
<programlisting> -- do this if you don't have a topology setup already
|
|
-- creates topology not allowing any tolerance
|
|
SELECT topology.CreateTopology('topo_boston_test', 2249);
|
|
-- create a new table
|
|
CREATE TABLE nei_topo(gid serial primary key, nei varchar(30));
|
|
--add a topogeometry column to it
|
|
SELECT topology.AddTopoGeometryColumn('topo_boston_test', 'public', 'nei_topo', 'topo', 'MULTIPOLYGON') As new_layer_id;
|
|
new_layer_id
|
|
-----------
|
|
1
|
|
|
|
--use new layer id in populating the new topogeometry column
|
|
-- we add the topogeoms to the new layer with 0 tolerance
|
|
INSERT INTO nei_topo(nei, topo)
|
|
SELECT nei, topology.toTopoGeom(geom, 'topo_boston_test', 1)
|
|
FROM neighborhoods
|
|
WHERE gid BETWEEN 1 and 15;
|
|
|
|
--use to verify what has happened --
|
|
SELECT * FROM
|
|
topology.TopologySummary('topo_boston_test');
|
|
|
|
-- summary--
|
|
Topology topo_boston_test (5), SRID 2249, precision 0
|
|
61 nodes, 87 edges, 35 faces, 15 topogeoms in 1 layers
|
|
Layer 1, type Polygonal (3), 15 topogeoms
|
|
Deploy: public.nei_topo.topo</programlisting>
|
|
|
|
<programlisting>
|
|
-- Shrink all TopoGeometry polygons by 10 meters
|
|
UPDATE nei_topo SET topo = ST_Buffer(clearTopoGeom(topo), -10);
|
|
|
|
-- Get the no-one-lands left by the above operation
|
|
-- I think GRASS calls this "polygon0 layer"
|
|
SELECT ST_GetFaceGeometry('topo_boston_test', f.face_id)
|
|
FROM topo_boston_test.face f
|
|
WHERE f.face_id > 0 -- don't consider the universe face
|
|
AND NOT EXISTS ( -- check that no TopoGeometry references the face
|
|
SELECT * FROM topo_boston_test.relation
|
|
WHERE layer_id = 1 AND element_id = f.face_id
|
|
);
|
|
</programlisting>
|
|
</refsection>
|
|
|
|
<!-- Optionally add a "See Also" section -->
|
|
<refsection>
|
|
<title>See Also</title>
|
|
<para>
|
|
<xref linkend="CreateTopology" />,
|
|
<xref linkend="AddTopoGeometryColumn"/>,
|
|
<xref linkend="CreateTopoGeom" />,
|
|
<xref linkend="TopologySummary" />,
|
|
<xref linkend="clearTopoGeom" />
|
|
</para>
|
|
</refsection>
|
|
</refentry>
|
|
|
|
<refentry id="TopoElementArray_Agg">
|
|
<refnamediv>
|
|
<refname>TopoElementArray_Agg</refname>
|
|
<refpurpose>Returns a <varname>topoelementarray</varname> for a set of element_id, type arrays (topoelements).</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>topoelementarray <function>TopoElementArray_Agg</function></funcdef>
|
|
<paramdef><type>topoelement set</type> <parameter>tefield</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
</refsynopsisdiv>
|
|
|
|
<refsection>
|
|
<title>Description</title>
|
|
|
|
<para>Used to create a <xref linkend="topoelementarray" /> from a set of <xref linkend="topoelement" />.</para>
|
|
|
|
<!-- use this format if new function -->
|
|
<para>Availability: 2.0.0</para>
|
|
</refsection>
|
|
|
|
|
|
<refsection>
|
|
<title>Examples</title>
|
|
<programlisting>SELECT topology.TopoElementArray_Agg(ARRAY[e,t]) As tea
|
|
FROM generate_series(1,3) As e CROSS JOIN generate_series(1,4) As t;
|
|
tea
|
|
--------------------------------------------------------------------------
|
|
{{1,1},{1,2},{1,3},{1,4},{2,1},{2,2},{2,3},{2,4},{3,1},{3,2},{3,3},{3,4}}</programlisting>
|
|
</refsection>
|
|
<refsection>
|
|
<title>See Also</title>
|
|
<para><xref linkend="topoelement"/>, <xref linkend="topoelementarray"/></para>
|
|
</refsection>
|
|
</refentry>
|
|
|
|
<refentry id="TopoElement">
|
|
<refnamediv>
|
|
<refname>TopoElement</refname>
|
|
<refpurpose>Converts a topogeometry to a topoelement.</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>topoelement <function>TopoElement</function></funcdef>
|
|
<paramdef><type>topogeometry </type> <parameter>topo</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
</refsynopsisdiv>
|
|
|
|
<refsection>
|
|
<title>Description</title>
|
|
<para>Converts a <xref linkend="topogeometry" /> to a <xref linkend="topoelement" />.</para>
|
|
<!-- use this format if new function -->
|
|
<para>Availability: 3.4.0</para>
|
|
</refsection>
|
|
|
|
<refsection>
|
|
<title>Examples</title>
|
|
<para>This is a full self-contained workflow</para>
|
|
<programlisting>-- do this if you don't have a topology setup already
|
|
-- Creates topology not allowing any tolerance
|
|
SELECT TopoElement(topo)
|
|
FROM neighborhoods;</programlisting>
|
|
|
|
<programlisting>-- using as cast
|
|
SELECT topology.TopoElementArray_Agg(topo::topoelement)
|
|
FROM neighborhoods
|
|
GROUP BY city;</programlisting>
|
|
</refsection>
|
|
|
|
<!-- Optionally add a "See Also" section -->
|
|
<refsection>
|
|
<title>See Also</title>
|
|
<para><xref linkend="TopoElementArray_Agg" />, <xref linkend="topogeometry" />, <xref linkend="topoelement" /></para>
|
|
</refsection>
|
|
</refentry>
|
|
</sect1>
|
|
|
|
<sect1 id="TopoGeometry_Editors">
|
|
<sect1info>
|
|
<abstract>
|
|
<para>This section covers the topology functions for editing existing topogeometries.</para>
|
|
</abstract>
|
|
</sect1info>
|
|
<title>TopoGeometry Editors</title>
|
|
|
|
<refentry id="clearTopoGeom">
|
|
<refnamediv>
|
|
<refname>clearTopoGeom</refname>
|
|
|
|
<refpurpose>Clears the content of a topo geometry.</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>topogeometry <function>clearTopoGeom</function></funcdef>
|
|
<paramdef><type>topogeometry </type> <parameter>topogeom</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
</refsynopsisdiv>
|
|
|
|
<refsection>
|
|
<title>Description</title>
|
|
|
|
<para>
|
|
Clears the content a <xref linkend="topogeometry" />
|
|
turning it into an empty one. Mostly useful in conjunction with <xref
|
|
linkend="toTopoGeom" /> to replace the shape of existing
|
|
objects and any dependent object in higher hierarchical levels.
|
|
</para>
|
|
|
|
<!-- use this format if new function -->
|
|
<para>Availability: 2.1</para>
|
|
</refsection>
|
|
<refsection>
|
|
<title>Examples</title>
|
|
<programlisting>
|
|
-- Shrink all TopoGeometry polygons by 10 meters
|
|
UPDATE nei_topo SET topo = ST_Buffer(clearTopoGeom(topo), -10);
|
|
</programlisting>
|
|
</refsection>
|
|
|
|
<!-- Optionally add a "See Also" section -->
|
|
<refsection>
|
|
<title>See Also</title>
|
|
<para>
|
|
<xref linkend="toTopoGeom" />
|
|
</para>
|
|
</refsection>
|
|
</refentry>
|
|
|
|
<refentry id="TopoGeom_addElement">
|
|
<refnamediv>
|
|
<refname>TopoGeom_addElement</refname>
|
|
<refpurpose>Adds an element to the definition of a TopoGeometry.</refpurpose>
|
|
</refnamediv>
|
|
<refsynopsisdiv>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>topogeometry <function>TopoGeom_addElement</function></funcdef>
|
|
<paramdef><type>topogeometry </type> <parameter>tg</parameter></paramdef>
|
|
<paramdef><type>topoelement </type> <parameter>el</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
</refsynopsisdiv>
|
|
|
|
<refsection>
|
|
<title>Description</title>
|
|
|
|
<para>
|
|
Adds a <xref linkend="topoelement" /> to the definition of a
|
|
TopoGeometry object. Does not error out if the element is already
|
|
part of the definition.
|
|
</para>
|
|
|
|
<!-- use this format if new function -->
|
|
<para>Availability: 2.3</para>
|
|
</refsection>
|
|
<refsection>
|
|
<title>Examples</title>
|
|
<programlisting>
|
|
-- Add edge 5 to TopoGeometry tg
|
|
UPDATE mylayer SET tg = TopoGeom_addElement(tg, '{5,2}');
|
|
</programlisting>
|
|
</refsection>
|
|
|
|
<!-- Optionally add a "See Also" section -->
|
|
<refsection>
|
|
<title>See Also</title>
|
|
<para>
|
|
<xref linkend="TopoGeom_remElement" />,
|
|
<xref linkend="CreateTopoGeom" />
|
|
</para>
|
|
</refsection>
|
|
</refentry>
|
|
|
|
<refentry id="TopoGeom_remElement">
|
|
<refnamediv>
|
|
<refname>TopoGeom_remElement</refname>
|
|
|
|
<refpurpose>Removes an element from the definition of a TopoGeometry.</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>topogeometry <function>TopoGeom_remElement</function></funcdef>
|
|
<paramdef><type>topogeometry </type> <parameter>tg</parameter></paramdef>
|
|
<paramdef><type>topoelement </type> <parameter>el</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
</refsynopsisdiv>
|
|
|
|
<refsection>
|
|
<title>Description</title>
|
|
|
|
<para>
|
|
Removes a <xref linkend="topoelement" /> from the definition of a
|
|
TopoGeometry object.
|
|
</para>
|
|
|
|
<!-- use this format if new function -->
|
|
<para>Availability: 2.3</para>
|
|
</refsection>
|
|
<refsection>
|
|
<title>Examples</title>
|
|
<programlisting>
|
|
-- Remove face 43 from TopoGeometry tg
|
|
UPDATE mylayer SET tg = TopoGeom_remElement(tg, '{43,3}');
|
|
</programlisting>
|
|
</refsection>
|
|
|
|
<!-- Optionally add a "See Also" section -->
|
|
<refsection>
|
|
<title>See Also</title>
|
|
<para>
|
|
<xref linkend="TopoGeom_addElement" />,
|
|
<xref linkend="CreateTopoGeom" />
|
|
</para>
|
|
</refsection>
|
|
</refentry>
|
|
|
|
<refentry id="TopoGeom_addTopoGeom">
|
|
<refnamediv>
|
|
<refname>TopoGeom_addTopoGeom</refname>
|
|
<refpurpose>Adds element of a TopoGeometry to the definition of another TopoGeometry.</refpurpose>
|
|
</refnamediv>
|
|
<refsynopsisdiv>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>topogeometry <function>TopoGeom_addTopoGeom</function></funcdef>
|
|
<paramdef><type>topogeometry </type> <parameter>tgt</parameter></paramdef>
|
|
<paramdef><type>topogeometry </type> <parameter>src</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
</refsynopsisdiv>
|
|
|
|
<refsection>
|
|
<title>Description</title>
|
|
|
|
<para>
|
|
Adds the elements of a <xref linkend="topogeometry" /> to the definition of
|
|
another TopoGeometry, possibly changing its cached type (type attribute)
|
|
to a collection, if needed to hold all elements in the source object.
|
|
</para>
|
|
|
|
<para>
|
|
The two TopoGeometry objects need be defined against the *same*
|
|
topology and, if hierarchically defined, need be composed by elements
|
|
of the same child layer.
|
|
</para>
|
|
|
|
<!-- use this format if new function -->
|
|
<para>Availability: 3.2</para>
|
|
</refsection>
|
|
<refsection>
|
|
<title>Examples</title>
|
|
<programlisting>
|
|
-- Set an "overall" TopoGeometry value to be composed by all
|
|
-- elements of specific TopoGeometry values
|
|
UPDATE mylayer SET tg_overall = TopoGeom_addTopogeom(
|
|
TopoGeom_addTopoGeom(
|
|
clearTopoGeom(tg_overall),
|
|
tg_specific1
|
|
),
|
|
tg_specific2
|
|
);
|
|
</programlisting>
|
|
</refsection>
|
|
|
|
<!-- Optionally add a "See Also" section -->
|
|
<refsection>
|
|
<title>See Also</title>
|
|
<para>
|
|
<xref linkend="TopoGeom_addElement" />,
|
|
<xref linkend="clearTopoGeom" />,
|
|
<xref linkend="CreateTopoGeom" />
|
|
</para>
|
|
</refsection>
|
|
</refentry>
|
|
|
|
<refentry id="toTopoGeom_editor_proxy">
|
|
<refnamediv>
|
|
<refname>toTopoGeom</refname>
|
|
<refpurpose>Adds a geometry shape to an existing topo geometry.</refpurpose>
|
|
</refnamediv>
|
|
<refsection>
|
|
<title>Description</title>
|
|
<para>
|
|
Refer to <xref linkend="toTopoGeom" />.
|
|
</para>
|
|
</refsection>
|
|
</refentry>
|
|
|
|
|
|
</sect1>
|
|
|
|
<sect1 id="TopoGeom_Accessors">
|
|
<title>TopoGeometry Accessors</title>
|
|
|
|
<refentry id="GetTopoGeomElementArray">
|
|
<refnamediv>
|
|
<refname>GetTopoGeomElementArray</refname>
|
|
|
|
<refpurpose>Returns a <varname>topoelementarray</varname> (an array of topoelements) containing the topological elements and type of the given TopoGeometry (primitive elements).</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>topoelementarray <function>GetTopoGeomElementArray</function></funcdef>
|
|
<paramdef><type>varchar </type> <parameter>toponame</parameter></paramdef>
|
|
<paramdef><type>integer </type> <parameter>layer_id</parameter></paramdef>
|
|
<paramdef><type>integer</type> <parameter>tg_id</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>topoelementarray <function>GetTopoGeomElementArray</function></funcdef>
|
|
<paramdef><type>topogeometry </type> <parameter>tg</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
</refsynopsisdiv>
|
|
|
|
<refsection>
|
|
<title>Description</title>
|
|
|
|
<para>Returns a <xref linkend="topoelementarray"/> containing the topological elements and type of the given TopoGeometry (primitive elements). This is similar to GetTopoGeomElements except it returns the elements as an array rather
|
|
than as a dataset.</para>
|
|
<para>tg_id is the topogeometry id of the topogeometry object in the topology in the layer denoted by <varname>layer_id</varname> in the topology.layer table.</para>
|
|
|
|
<!-- use this format if new function -->
|
|
<para>Availability: 1.1</para>
|
|
</refsection>
|
|
|
|
|
|
<refsection>
|
|
<title>Examples</title>
|
|
<para/>
|
|
<!-- TODO: -->
|
|
</refsection>
|
|
|
|
<!-- Optionally add a "See Also" section -->
|
|
<refsection>
|
|
<title>See Also</title>
|
|
<para><xref linkend="GetTopoGeomElements"/>, <xref linkend="topoelementarray"/></para>
|
|
</refsection>
|
|
</refentry>
|
|
<refentry id="GetTopoGeomElements">
|
|
<refnamediv>
|
|
<refname>GetTopoGeomElements</refname>
|
|
|
|
<refpurpose>Returns a set of <varname>topoelement</varname> objects containing the topological element_id,element_type of the given TopoGeometry (primitive elements).</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>setof topoelement <function>GetTopoGeomElements</function></funcdef>
|
|
<paramdef><type>varchar </type> <parameter>toponame</parameter></paramdef>
|
|
<paramdef><type>integer </type> <parameter>layer_id</parameter></paramdef>
|
|
<paramdef><type>integer</type> <parameter>tg_id</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>setof topoelement <function>GetTopoGeomElements</function></funcdef>
|
|
<paramdef><type>topogeometry </type> <parameter>tg</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
</refsynopsisdiv>
|
|
|
|
<refsection>
|
|
<title>Description</title>
|
|
|
|
<para>Returns a set of element_id,element_type (topoelements) for a given topogeometry object in <varname>toponame</varname> schema.</para>
|
|
<para>tg_id is the topogeometry id of the topogeometry object in the topology in the layer denoted by <varname>layer_id</varname> in the topology.layer table.</para>
|
|
|
|
<!-- use this format if new function -->
|
|
<para>Availability: 2.0.0</para>
|
|
</refsection>
|
|
|
|
|
|
<refsection>
|
|
<title>Examples</title>
|
|
<para/>
|
|
<!-- TODO: -->
|
|
</refsection>
|
|
|
|
<!-- Optionally add a "See Also" section -->
|
|
<refsection>
|
|
<title>See Also</title>
|
|
<para>
|
|
<xref linkend="GetTopoGeomElementArray"/>,
|
|
<xref linkend="topoelement"/>,
|
|
<xref linkend="TopoGeom_addElement" />,
|
|
<xref linkend="TopoGeom_remElement" />
|
|
</para>
|
|
</refsection>
|
|
</refentry>
|
|
|
|
<refentry id="TG_ST_SRID">
|
|
<refnamediv>
|
|
<refname>ST_SRID</refname>
|
|
<refpurpose>Returns the spatial reference identifier for a topogeometry.</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>integer <function>ST_SRID</function></funcdef>
|
|
<paramdef><type>topogeometry </type> <parameter>tg</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
</refsynopsisdiv>
|
|
|
|
<refsection>
|
|
<title>Description</title>
|
|
|
|
<para>Returns the spatial reference identifier for the ST_Geometry as defined in spatial_ref_sys table. <xref linkend="spatial_ref_sys" /></para>
|
|
<para><note><para>spatial_ref_sys
|
|
table is a table that catalogs all spatial reference systems known to PostGIS and is used for transformations from one spatial
|
|
reference system to another. So verifying you have the right spatial reference system identifier is important if you plan to ever transform your geometries.</para></note></para>
|
|
<para>Availability: 3.2.0</para>
|
|
<para>&sqlmm_compliant; SQL-MM 3: 14.1.5</para>
|
|
|
|
</refsection>
|
|
|
|
<refsection>
|
|
<title>Examples</title>
|
|
|
|
<programlisting>SELECT ST_SRID(ST_GeomFromText('POINT(-71.1043 42.315)',4326));
|
|
--result
|
|
4326
|
|
</programlisting>
|
|
</refsection>
|
|
<refsection>
|
|
<title>See Also</title>
|
|
|
|
<para><xref linkend="spatial_ref_sys" />, <xref linkend="ST_SetSRID" />, <xref linkend="ST_Transform" />, <xref linkend="ST_SRID" /></para>
|
|
</refsection>
|
|
</refentry>
|
|
|
|
</sect1>
|
|
|
|
|
|
<sect1 id="TopoGeometry_Outputs">
|
|
<title>TopoGeometry Outputs</title>
|
|
<refentry id="AsGML">
|
|
<refnamediv>
|
|
<refname>AsGML</refname>
|
|
|
|
<refpurpose>Returns the GML representation of a topogeometry.</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>text <function>AsGML</function></funcdef>
|
|
<paramdef><type>topogeometry </type> <parameter>tg</parameter></paramdef>
|
|
</funcprototype>
|
|
<funcprototype>
|
|
<funcdef>text <function>AsGML</function></funcdef>
|
|
<paramdef><type>topogeometry </type> <parameter>tg</parameter></paramdef>
|
|
<paramdef><type>text </type> <parameter>nsprefix_in</parameter></paramdef>
|
|
</funcprototype>
|
|
<funcprototype>
|
|
<funcdef>text <function>AsGML</function></funcdef>
|
|
<paramdef><type>topogeometry </type> <parameter>tg</parameter></paramdef>
|
|
<paramdef><type>regclass </type> <parameter>visitedTable</parameter></paramdef>
|
|
</funcprototype>
|
|
<funcprototype>
|
|
<funcdef>text <function>AsGML</function></funcdef>
|
|
<paramdef><type>topogeometry </type> <parameter>tg</parameter></paramdef>
|
|
<paramdef><type>regclass </type> <parameter>visitedTable</parameter></paramdef>
|
|
<paramdef><type>text </type> <parameter>nsprefix</parameter></paramdef>
|
|
</funcprototype>
|
|
<funcprototype>
|
|
<funcdef>text <function>AsGML</function></funcdef>
|
|
<paramdef><type>topogeometry </type> <parameter>tg</parameter></paramdef>
|
|
<paramdef><type>text </type> <parameter>nsprefix_in</parameter></paramdef>
|
|
<paramdef><type>integer </type> <parameter>precision</parameter></paramdef>
|
|
<paramdef><type>integer </type> <parameter>options</parameter></paramdef>
|
|
</funcprototype>
|
|
<funcprototype>
|
|
<funcdef>text <function>AsGML</function></funcdef>
|
|
<paramdef><type>topogeometry </type> <parameter>tg</parameter></paramdef>
|
|
<paramdef><type>text </type> <parameter>nsprefix_in</parameter></paramdef>
|
|
<paramdef><type>integer </type> <parameter>precision</parameter></paramdef>
|
|
<paramdef><type>integer </type> <parameter>options</parameter></paramdef>
|
|
<paramdef><type>regclass </type> <parameter>visitedTable</parameter></paramdef>
|
|
</funcprototype>
|
|
<funcprototype>
|
|
<funcdef>text <function>AsGML</function></funcdef>
|
|
<paramdef><type>topogeometry </type> <parameter>tg</parameter></paramdef>
|
|
<paramdef><type>text </type> <parameter>nsprefix_in</parameter></paramdef>
|
|
<paramdef><type>integer </type> <parameter>precision</parameter></paramdef>
|
|
<paramdef><type>integer </type> <parameter>options</parameter></paramdef>
|
|
<paramdef><type>regclass </type> <parameter>visitedTable</parameter></paramdef>
|
|
<paramdef><type>text </type> <parameter>idprefix</parameter></paramdef>
|
|
</funcprototype>
|
|
<funcprototype>
|
|
<funcdef>text <function>AsGML</function></funcdef>
|
|
<paramdef><type>topogeometry </type> <parameter>tg</parameter></paramdef>
|
|
<paramdef><type>text </type> <parameter>nsprefix_in</parameter></paramdef>
|
|
<paramdef><type>integer </type> <parameter>precision</parameter></paramdef>
|
|
<paramdef><type>integer </type> <parameter>options</parameter></paramdef>
|
|
<paramdef><type>regclass </type> <parameter>visitedTable</parameter></paramdef>
|
|
<paramdef><type>text </type> <parameter>idprefix</parameter></paramdef>
|
|
<paramdef><type>int </type> <parameter>gmlversion</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
</refsynopsisdiv>
|
|
|
|
<refsection>
|
|
<title>Description</title>
|
|
|
|
<para>Returns the GML representation of a topogeometry in version GML3 format. If no <varname>nsprefix_in</varname> is specified then <varname>gml</varname> is used. Pass in an empty string for nsprefix to get a non-qualified name space. The precision (default: 15) and options (default 1) parameters, if given, are passed untouched to the underlying call to ST_AsGML.</para>
|
|
|
|
<para>
|
|
The <varname>visitedTable</varname> parameter, if given, is used for keeping track of the visited Node and Edge elements so to use cross-references (xlink:xref) rather than duplicating definitions. The table is expected to have (at least) two integer fields: 'element_type' and 'element_id'. The calling user must have both read and write privileges on the given table.
|
|
For best performance, an index should be defined on
|
|
<varname>element_type</varname> and <varname>element_id</varname>,
|
|
in that order. Such index would be created automatically by adding a unique
|
|
constraint to the fields. Example:
|
|
<programlisting>
|
|
CREATE TABLE visited (
|
|
element_type integer, element_id integer,
|
|
unique(element_type, element_id)
|
|
);
|
|
</programlisting>
|
|
</para>
|
|
|
|
<para>The <varname>idprefix</varname> parameter, if given, will be prepended to Edge and Node tag identifiers.</para>
|
|
|
|
<para>The <varname>gmlver</varname> parameter, if given, will be passed to the underlying ST_AsGML. Defaults to 3.</para>
|
|
|
|
<!-- use this format if new function -->
|
|
<para>Availability: 2.0.0 </para>
|
|
</refsection>
|
|
|
|
|
|
<refsection>
|
|
<title>Examples</title>
|
|
<para>This uses the topo geometry we created in <xref linkend="CreateTopoGeom" /></para>
|
|
<programlisting>SELECT topology.AsGML(topo) As rdgml
|
|
FROM ri.roads
|
|
WHERE road_name = 'Unknown';
|
|
|
|
-- rdgml--
|
|
<![CDATA[<gml:TopoCurve>
|
|
<gml:directedEdge>
|
|
<gml:Edge gml:id="E1">
|
|
<gml:directedNode orientation="-">
|
|
<gml:Node gml:id="N1"/>
|
|
</gml:directedNode>
|
|
<gml:directedNode></gml:directedNode>
|
|
<gml:curveProperty>
|
|
<gml:Curve srsName="urn:ogc:def:crs:EPSG::3438">
|
|
<gml:segments>
|
|
<gml:LineStringSegment>
|
|
<gml:posList srsDimension="2">384744 236928 384750 236923 384769 236911 384799 236895 384811 236890
|
|
384833 236884 384844 236882 384866 236881 384879 236883 384954 236898 385087 236932 385117 236938
|
|
385167 236938 385203 236941 385224 236946 385233 236950 385241 236956 385254 236971
|
|
385260 236979 385268 236999 385273 237018 385273 237037 385271 237047 385267 237057 385225 237125
|
|
385210 237144 385192 237161 385167 237192 385162 237202 385159 237214 385159 237227 385162 237241
|
|
385166 237256 385196 237324 385209 237345 385234 237375 385237 237383 385238 237399 385236 237407
|
|
385227 237419 385213 237430 385193 237439 385174 237451 385170 237455 385169 237460 385171 237475
|
|
385181 237503 385190 237521 385200 237533 385206 237538 385213 237541 385221 237542 385235 237540 385242 237541
|
|
385249 237544 385260 237555 385270 237570 385289 237584 385292 237589 385291 237596 385284 237630</gml:posList>
|
|
</gml:LineStringSegment>
|
|
</gml:segments>
|
|
</gml:Curve>
|
|
</gml:curveProperty>
|
|
</gml:Edge>
|
|
</gml:directedEdge>
|
|
</gml:TopoCurve>]]>
|
|
</programlisting>
|
|
<para>Same exercise as previous without namespace</para>
|
|
<programlisting>SELECT topology.AsGML(topo,'') As rdgml
|
|
FROM ri.roads
|
|
WHERE road_name = 'Unknown';
|
|
|
|
-- rdgml--
|
|
<![CDATA[<TopoCurve>
|
|
<directedEdge>
|
|
<Edge id="E1">
|
|
<directedNode orientation="-">
|
|
<Node id="N1"/>
|
|
</directedNode>
|
|
<directedNode></directedNode>
|
|
<curveProperty>
|
|
<Curve srsName="urn:ogc:def:crs:EPSG::3438">
|
|
<segments>
|
|
<LineStringSegment>
|
|
<posList srsDimension="2">384744 236928 384750 236923 384769 236911 384799 236895 384811 236890
|
|
384833 236884 384844 236882 384866 236881 384879 236883 384954 236898 385087 236932 385117 236938
|
|
385167 236938 385203 236941 385224 236946 385233 236950 385241 236956 385254 236971
|
|
385260 236979 385268 236999 385273 237018 385273 237037 385271 237047 385267 237057 385225 237125
|
|
385210 237144 385192 237161 385167 237192 385162 237202 385159 237214 385159 237227 385162 237241
|
|
385166 237256 385196 237324 385209 237345 385234 237375 385237 237383 385238 237399 385236 237407
|
|
385227 237419 385213 237430 385193 237439 385174 237451 385170 237455 385169 237460 385171 237475
|
|
385181 237503 385190 237521 385200 237533 385206 237538 385213 237541 385221 237542 385235 237540 385242 237541
|
|
385249 237544 385260 237555 385270 237570 385289 237584 385292 237589 385291 237596 385284 237630</posList>
|
|
</LineStringSegment>
|
|
</segments>
|
|
</Curve>
|
|
</curveProperty>
|
|
</Edge>
|
|
</directedEdge>
|
|
</TopoCurve>]]>
|
|
</programlisting>
|
|
</refsection>
|
|
|
|
<!-- Optionally add a "See Also" section -->
|
|
<refsection>
|
|
<title>See Also</title>
|
|
<para><xref linkend="CreateTopoGeom"/>, <xref linkend="ST_CreateTopoGeo" /></para>
|
|
</refsection>
|
|
</refentry>
|
|
<refentry id="AsTopoJSON">
|
|
<refnamediv>
|
|
<refname>AsTopoJSON</refname>
|
|
|
|
<refpurpose>Returns the TopoJSON representation of a topogeometry.</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>text <function>AsTopoJSON</function></funcdef>
|
|
<paramdef><type>topogeometry </type> <parameter>tg</parameter></paramdef>
|
|
<paramdef><type>regclass </type> <parameter>edgeMapTable</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
</refsynopsisdiv>
|
|
|
|
<refsection>
|
|
<title>Description</title>
|
|
|
|
<para>Returns the TopoJSON representation of a topogeometry. If <varname>edgeMapTable</varname> is not null, it will be used as a lookup/storage mapping of edge identifiers to arc indices. This is to be able to allow for a compact "arcs" array in the final document.
|
|
</para>
|
|
|
|
<para>
|
|
The table, if given, is expected to have an "arc_id" field of type "serial" and an "edge_id" of type integer; the code will query the table for "edge_id" so it is recommended to add an index on that field.
|
|
</para>
|
|
|
|
<note>
|
|
<para>
|
|
Arc indices in the TopoJSON output are 0-based but they are 1-based
|
|
in the "edgeMapTable" table.
|
|
</para>
|
|
</note>
|
|
|
|
<para>
|
|
A full TopoJSON document will be need to contain, in
|
|
addition to the snippets returned by this function,
|
|
the actual arcs plus some headers. See the <ulink
|
|
url="http://github.com/mbostock/topojson-specification/blob/master/README.md"
|
|
>TopoJSON specification</ulink>.
|
|
</para>
|
|
|
|
<!-- use this format if new function -->
|
|
<para>Availability: 2.1.0 </para>
|
|
<para>Enhanced: 2.2.1 added support for puntal inputs</para>
|
|
</refsection>
|
|
|
|
|
|
<!-- Optionally add a "See Also" section -->
|
|
<refsection>
|
|
<title>See Also</title>
|
|
<para><xref linkend="ST_AsGeoJSON" /></para>
|
|
</refsection>
|
|
|
|
<refsection>
|
|
<title>Examples</title>
|
|
<programlisting>
|
|
CREATE TEMP TABLE edgemap(arc_id serial, edge_id int unique);
|
|
|
|
-- header
|
|
SELECT '{ "type": "Topology", "transform": { "scale": [1,1], "translate": [0,0] }, "objects": {'
|
|
|
|
-- objects
|
|
UNION ALL SELECT '"' || feature_name || '": ' || AsTopoJSON(feature, 'edgemap')
|
|
FROM features.big_parcels WHERE feature_name = 'P3P4';
|
|
|
|
-- arcs
|
|
WITH edges AS (
|
|
SELECT m.arc_id, e.geom FROM edgemap m, city_data.edge e
|
|
WHERE e.edge_id = m.edge_id
|
|
), points AS (
|
|
SELECT arc_id, (st_dumppoints(geom)).* FROM edges
|
|
), compare AS (
|
|
SELECT p2.arc_id,
|
|
CASE WHEN p1.path IS NULL THEN p2.geom
|
|
ELSE ST_Translate(p2.geom, -ST_X(p1.geom), -ST_Y(p1.geom))
|
|
END AS geom
|
|
FROM points p2 LEFT OUTER JOIN points p1
|
|
ON ( p1.arc_id = p2.arc_id AND p2.path[1] = p1.path[1]+1 )
|
|
ORDER BY arc_id, p2.path
|
|
), arcsdump AS (
|
|
SELECT arc_id, (regexp_matches( ST_AsGeoJSON(geom), '\[.*\]'))[1] as t
|
|
FROM compare
|
|
), arcs AS (
|
|
SELECT arc_id, '[' || array_to_string(array_agg(t), ',') || ']' as a FROM arcsdump
|
|
GROUP BY arc_id
|
|
ORDER BY arc_id
|
|
)
|
|
SELECT '}, "arcs": [' UNION ALL
|
|
SELECT array_to_string(array_agg(a), E',\n') from arcs
|
|
|
|
-- footer
|
|
UNION ALL SELECT ']}'::text as t;
|
|
|
|
-- Result:
|
|
{ "type": "Topology", "transform": { "scale": [1,1], "translate": [0,0] }, "objects": {
|
|
"P3P4": { "type": "MultiPolygon", "arcs": [[[-1]],[[6,5,-5,-4,-3,1]]]}
|
|
}, "arcs": [
|
|
[[25,30],[6,0],[0,10],[-14,0],[0,-10],[8,0]],
|
|
[[35,6],[0,8]],
|
|
[[35,6],[12,0]],
|
|
[[47,6],[0,8]],
|
|
[[47,14],[0,8]],
|
|
[[35,22],[12,0]],
|
|
[[35,14],[0,8]]
|
|
]}
|
|
</programlisting>
|
|
</refsection>
|
|
</refentry>
|
|
</sect1>
|
|
|
|
<sect1 id="Topology_Relationships">
|
|
<sect1info>
|
|
<abstract>
|
|
<para>This section lists the Topology functions used to check relationships between topogeometries and topology primitives</para>
|
|
</abstract>
|
|
</sect1info>
|
|
<title>Topology Spatial Relationships</title>
|
|
<refentry id="TG_Equals">
|
|
<refnamediv>
|
|
<refname>Equals</refname>
|
|
|
|
<refpurpose>Returns true if two topogeometries are composed of the same topology primitives.</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>boolean <function>Equals</function></funcdef>
|
|
<paramdef><type>topogeometry </type> <parameter>tg1</parameter></paramdef>
|
|
<paramdef><type>topogeometry </type> <parameter>tg2</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
</refsynopsisdiv>
|
|
|
|
<refsection>
|
|
<title>Description</title>
|
|
|
|
<para>Returns true if two topogeometries are composed of the same topology primitives: faces, edges, nodes.</para>
|
|
|
|
<!-- optionally mention that this function uses indexes if appropriate -->
|
|
<note>
|
|
<para>This function not supported for topogeometries that are geometry collections. It also can not compare topogeometries from different topologies.</para>
|
|
</note>
|
|
<!-- use this format if new function -->
|
|
<para>Availability: 1.1.0 </para>
|
|
|
|
|
|
<!-- Optionally mention 3d support -->
|
|
<para>&Z_support;</para>
|
|
</refsection>
|
|
|
|
|
|
<refsection>
|
|
<title>Examples</title>
|
|
|
|
<programlisting><!--TODO: Need example --></programlisting>
|
|
</refsection>
|
|
|
|
<!-- Optionally add a "See Also" section -->
|
|
<refsection>
|
|
<title>See Also</title>
|
|
|
|
<para><xref linkend="GetTopoGeomElements" />, <xref linkend="ST_Equals" /></para>
|
|
</refsection>
|
|
</refentry>
|
|
|
|
<refentry id="TG_Intersects">
|
|
<refnamediv>
|
|
<refname>Intersects</refname>
|
|
|
|
<refpurpose>Returns true if any pair of primitives from the two topogeometries intersect.</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>boolean <function>Intersects</function></funcdef>
|
|
<paramdef><type>topogeometry </type> <parameter>tg1</parameter></paramdef>
|
|
<paramdef><type>topogeometry </type> <parameter>tg2</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
</refsynopsisdiv>
|
|
|
|
<refsection>
|
|
<title>Description</title>
|
|
|
|
<para>
|
|
Returns true if any pair of primitives from the
|
|
two topogeometries intersect.
|
|
</para>
|
|
|
|
<!-- optionally mention that this function uses indexes if appropriate -->
|
|
<note>
|
|
<para>This function not supported for topogeometries that are geometry collections. It also can not compare topogeometries from different topologies.
|
|
Also not currently supported for hierarchical topogeometries (topogeometries composed of other topogeometries).</para>
|
|
</note>
|
|
<!-- use this format if new function -->
|
|
<para>Availability: 1.1.0 </para>
|
|
|
|
|
|
<!-- Optionally mention 3d support -->
|
|
<para>&Z_support;</para>
|
|
</refsection>
|
|
|
|
|
|
<refsection>
|
|
<title>Examples</title>
|
|
|
|
<programlisting><!--TODO: Need example --></programlisting>
|
|
</refsection>
|
|
|
|
<!-- Optionally add a "See Also" section -->
|
|
<refsection>
|
|
<title>See Also</title>
|
|
|
|
<para><xref linkend="ST_Intersects" /></para>
|
|
</refsection>
|
|
</refentry>
|
|
</sect1>
|
|
|
|
<sect1 id="Topology_Import_Export">
|
|
<title>Importing and exporting Topologies</title>
|
|
|
|
<para>
|
|
Once you have created topologies, and maybe associated topological layers,
|
|
you might want to export them into a file-based format for backup or transfer
|
|
into another database.
|
|
</para>
|
|
|
|
<para>
|
|
Using the standard dump/restore tools of PostgreSQL is
|
|
problematic because topologies are composed by a set of tables (4 for
|
|
primitives, an arbitrary number for layers) and records in metadata tables
|
|
(topology.topology and topology.layer). Additionally, topology identifiers
|
|
are not univoque across databases so that parameter of your topology
|
|
will need to be changes upon restoring it.
|
|
</para>
|
|
|
|
<para>
|
|
In order to simplify export/restore of topologies a pair of
|
|
executables are provided: <filename>pgtopo_export</filename>
|
|
and <filename>pgtopo_import</filename>. Example usage:
|
|
</para>
|
|
<programlisting>
|
|
pgtopo_export dev_db topo1 | pgtopo_import topo1 | psql staging_db
|
|
</programlisting>
|
|
|
|
<sect2 id="pgtopo_export">
|
|
<title>Using the Topology exporter</title>
|
|
|
|
<para>
|
|
The <filename>pgtopo_export</filename> script takes the name of a
|
|
database and a topology and outputs a dump file which can be used
|
|
to import the topology (and associated layers) into a new database.
|
|
</para>
|
|
|
|
<para>
|
|
By default <filename>pgtopo_export</filename> writes the
|
|
dump file to the standard output so that it can be piped to
|
|
<filename>pgtopo_import</filename> or redirected to a file
|
|
(refusing to write to terminal). You can optionally specify
|
|
an output filename with the <code>-f</code> commandline switch.
|
|
</para>
|
|
|
|
<para>
|
|
By default <filename>pgtopo_export</filename> includes a dump
|
|
of all layers defined against the given topology. This may be more
|
|
data than you need, or may be non-working (in case your layer tables
|
|
have complex dependencies) in which case you can request skipping the
|
|
layers with the <code>--skip-layers</code> switch and deal with those
|
|
separately.
|
|
</para>
|
|
|
|
<para>
|
|
Invoking <filename>pgtopo_export</filename> with the
|
|
<code>--help</code> (or <code>-h</code> for short) switch
|
|
will always print short usage string.
|
|
</para>
|
|
|
|
|
|
<para>
|
|
The dump file format is a compressed tar archive of a
|
|
<filename>pgtopo_export</filename> directory containing
|
|
at least a <filename>pgtopo_dump_version</filename> file with
|
|
format version info. As of version <code>1</code> the directory
|
|
contains tab-delimited CSV files with data of the topology
|
|
primitive tables (node, edge_data, face, relation), the
|
|
topology and layer records associated with it and
|
|
(unless <code>--skip-layers</code> is given) a custom-format
|
|
PostgreSQL dump of tables reported as being layers of the given
|
|
topology.
|
|
</para>
|
|
|
|
</sect2> <!-- pgtopo_export -->
|
|
|
|
<sect2 id="pgtopo_import">
|
|
<title>Using the Topology importer</title>
|
|
|
|
<para>
|
|
The <filename>pgtopo_import</filename> script takes a
|
|
<code>pgtopo_export</code> format topology dump and a
|
|
name to give to the topology to be created and outputs
|
|
an SQL script reconstructing the topology and associated
|
|
layers.
|
|
</para>
|
|
|
|
<para>
|
|
The generated SQL file will contain statements that create
|
|
a topology with the given name, load primitive data in it,
|
|
restores and registers all topology layers by properly
|
|
linking all TopoGeometry values to their correct topology.
|
|
</para>
|
|
|
|
|
|
<para>
|
|
By default <filename>pgtopo_import</filename> reads the dump
|
|
from the standard input so that it can be used in conjuction
|
|
with <filename>pgtopo_export</filename> in a pipeline.
|
|
You can optionally specify an input filename with the
|
|
<code>-f</code> commandline switch.
|
|
</para>
|
|
|
|
<para>
|
|
By default <filename>pgtopo_import</filename> includes in the output
|
|
SQL file the code to restore all layers found in the dump.
|
|
</para>
|
|
|
|
<para>
|
|
This may be unwanted or non-working in case your target database already
|
|
have tables with the same name as the ones in the dump. In that case
|
|
you can request skipping the layers with the <code>--skip-layers</code>
|
|
switch and deal with those separately (or later).
|
|
</para>
|
|
|
|
<para>
|
|
SQL to only load and link layers to a named topology can be generated
|
|
using the <code>--only-layers</code> switch. This can be useful to load
|
|
layers AFTER resolving the naming conflicts or to link layers to a
|
|
different topology (say a spatially-simplified version of the starting
|
|
topology).
|
|
</para>
|
|
|
|
</sect2> <!-- pgtopo_import -->
|
|
|
|
</sect1> <!-- Importing and exporting Topologies -->
|
|
|
|
</chapter>
|