mirror of
https://git.osgeo.org/gitea/postgis/postgis
synced 2024-10-23 16:42:35 +00:00
2254 lines
95 KiB
XML
2254 lines
95 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.keybit.net/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="http://2010.foss4g.org/presentations/3555.pdf">State of the art of FOSS4G for topology and network analysis</ulink>.</para>
|
|
<para>An example of a topologically based GIS database is the <ulink url="http://www.census.gov/geo/www/tiger/overview.html">US Census Topologically Integrated Geographic Encoding and Reference System (TIGER)</ulink> database.</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>To build PostGIS 2.0 with topology support, compile with the --with-topology option as described in <xref linkend="postgis_installation"/>. Some functions depend on GEOS 3.3+ so you should compile with GEOS 3.3+ to fully utilize the topology support.</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>PostgreSQL PostGIS Topology Types</title>
|
|
|
|
<refentry id="getfaceedges_returntype">
|
|
<refnamediv>
|
|
<refname>getfaceedges_returntype</refname>
|
|
<refpurpose>A composite type that consists of a sequence number and edge number. This is the return type for <varname>ST_GetFaceEdges</varname></refpurpose>
|
|
</refnamediv>
|
|
<refsection>
|
|
<title>Description</title>
|
|
<para>A composite type that consists of a sequence number and edge number. This is the return type for <varname>ST_GetFaceEdges</varname> function.</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 that refers to a topology geometry in a specific topology, layer, having specific type (1:[multi]point, 2:[multi]line, 3:[multi]poly, 4:collection) with specific identifier id in the topology. The id uniquely defines the topogeometry in the topology.</refpurpose>
|
|
</refnamediv>
|
|
<refsection>
|
|
<title>Description</title>
|
|
<para>A composite type that refers to a topology geometry in a specific topology, layer, having specific type with 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 hte topogeometry belongs to. The combination of topology_id, layer_id provides a unique reference in the topology.layers table.</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>
|
|
<listitem>
|
|
<para><varname>id</varname> is an integer: The id is the autogenerated sequence number that uniquely defines the topogeometry in the respective topology.</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>ST_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>PostgreSQL PostGIS 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 the id and type of a topology primitive or the id and layer of a TopoGeometry. Sets of such pairs are used to define TopoGeometry objects (either simple or hierarchical).</para>
|
|
</refsection>
|
|
<refsection>
|
|
<title>Examples</title>
|
|
<programlisting>SELECT ARRAY[1,2]::topology.topoelement;
|
|
te
|
|
-------
|
|
{1,2}
|
|
</programlisting>
|
|
<programlisting>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"/></para>
|
|
</refsection>
|
|
</refentry>
|
|
|
|
<refentry id="topoelementarray">
|
|
<refnamediv>
|
|
<refname>topoelementarray</refname>
|
|
<refpurpose>An array of element_id,element_type values. a bidimensional array of integers: '{{id,type}, {id,type}, ...}'</refpurpose>
|
|
</refnamediv>
|
|
<refsection>
|
|
<title>Description</title>
|
|
<para>An array of 1 or more topoelements ( a bidimensional array of integers: '{{id,type}, {id,type}, ...}'). So an array of 1 or more arrays each having 2 integers generally used to return an array of sets of element id and element type of a topology relation.</para>
|
|
</refsection>
|
|
<refsection>
|
|
<title>Examples</title>
|
|
<programlisting>SELECT '{{1,2},{3,4}}'::topology.topoelementarray As tea;
|
|
tea
|
|
-------
|
|
{{1,2},{3,4}}
|
|
|
|
-- more verbose equivalent --
|
|
SELECT ARRAY[ARRAY[1,2], ARRAY[3,4]]::topology.topoelementarray As tea;
|
|
|
|
tea
|
|
-------
|
|
{{1,2},{3,4}}
|
|
|
|
--using the array agg function packaged with topology --
|
|
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>
|
|
<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="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 Management Functions</title>
|
|
<refentry id="AddTopoGeometryColumn">
|
|
<refnamediv>
|
|
<refname>AddTopoGeometryColumn</refname>
|
|
<refpurpose>Adds a topogeometry column to an existing feature table, registers this new column as a layer in topology.layer and returns the new layer_id.</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>text <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>text <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_layar</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 (it's 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, LINE, POLYGON, COLLECTION</para>
|
|
|
|
<!-- use this format if new function -->
|
|
<para>Availability: 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="CreateTopology"/>, <xref linkend="CreateTopoGeom"/></para>
|
|
</refsection>
|
|
</refentry>
|
|
<refentry id="CreateTopology">
|
|
<refnamediv>
|
|
<refname>CreateTopology</refname>
|
|
<refpurpose>Creates a new topology schema and registers this new schema 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>tolerance</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>tolerance</parameter></paramdef>
|
|
<paramdef><type>boolean </type> <parameter>hasz</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
</refsynopsisdiv>
|
|
|
|
<refsection>
|
|
<title>Description</title>
|
|
|
|
<para>Creates a new schema with name <varname>topology_name</varname> consisting of tables (<varname>edge_data</varname>,<varname>face</varname>,<varname>node</varname>, <varname>relation</varname>
|
|
and registers this new topology in the topology.topology table. It returns the id of the topology in the topology table. The srid is the spatial reference identified as
|
|
defined in spatial_ref_sys table for that topology. Topologies must be uniquely named. The tolerance is measured in the units of the spatial reference system. If the tolerance is not specified defaults to 0.</para>
|
|
|
|
<para>This is similar to the SQL/MM <xref linkend="ST_InitTopoGeo" /> but a bit more functional. <varname>hasz</varname> defaults to false if not specified.</para>
|
|
|
|
<!-- use this format if new function -->
|
|
<para>Availability: 1.?</para>
|
|
</refsection>
|
|
|
|
|
|
<refsection>
|
|
<title>Examples</title>
|
|
<para>This example creates a new schema called ma_topo that will store edges, faces, and relations in Massachusetts State Plane meters.
|
|
The tolerance represents 1/2 meter since the spatial reference system is a meter based spatial reference system</para>
|
|
<programlisting>SELECT topology.CreateTopology('ma_topo',26986, 0.5);</programlisting>
|
|
|
|
<para>Create Rhode Island topology in State Plane ft</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" /></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.?</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></para>
|
|
</refsection>
|
|
</refentry>
|
|
<refentry id="CopyTopology">
|
|
<refnamediv>
|
|
<refname>CopyTopology</refname>
|
|
<refpurpose>Makes a copy of a topology structure (nodes, edges, faces, layers and TopoGeometries).</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_topology_name</varname> and SRID and precision taken from <varname>existing_topology_name</varname>, copies all nodes, edges and faces in there, copies layers and their TopoGeometries too.
|
|
</para>
|
|
|
|
<note><para>
|
|
The new rows in topology.layer will contain synthesized values for schema_name, table_name and feature_column. This is because the TopoGeometry will only exist as a definition but won't be available in any user-level table yet.
|
|
</para></note>
|
|
|
|
<!-- use this format if new function -->
|
|
<para>Availability: 2.0.0</para>
|
|
</refsection>
|
|
|
|
|
|
<refsection>
|
|
<title>Examples</title>
|
|
<para>
|
|
This example makes a backup of a topology called ma_topo
|
|
</para>
|
|
<programlisting>SELECT topology.CopyTopology('ma_topo', 'ma_topo_bakup');</programlisting>
|
|
|
|
</refsection>
|
|
|
|
<!-- Optionally add a "See Also" section -->
|
|
<refsection>
|
|
<title>See Also</title>
|
|
|
|
<para><xref linkend="spatial_ref_sys"/>, <xref linkend="CreateTopology" /></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.?</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="ST_InitTopoGeo">
|
|
<refnamediv>
|
|
<refname>ST_InitTopoGeo</refname>
|
|
<refpurpose>Creates a new topology schema and registers this new schema in the topology.topology table and details summary of process.</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 an SQL-MM equivalent of CreateTopology but lacks the spatial reference and tolerance options of CreateTopology and outputs a text description of creation instead of topology id.</para>
|
|
|
|
<!-- use this format if new function -->
|
|
<para>Availability: 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="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>
|
|
</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>topology_schema_name</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
</refsynopsisdiv>
|
|
|
|
<refsection>
|
|
<title>Description</title>
|
|
|
|
<para>Returns a set of <xref linkend="validatetopology_returntype"/> objects detailing issues with topology. Refer to
|
|
<xref linkend="validatetopology_returntype"/> for listing of possible errors.</para>
|
|
|
|
<!-- use this format if new function -->
|
|
<para>Availability: 1.?</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>
|
|
</refsection>
|
|
|
|
|
|
<refsection>
|
|
<title>Examples</title>
|
|
<programlisting>SELECT * FROM topology.ValidateTopology('ma_topo');
|
|
error | id1 | id2
|
|
-------------------+-----+-----
|
|
face without edges | 0 |
|
|
</programlisting>
|
|
</refsection>
|
|
|
|
<!-- Optionally add a "See Also" section -->
|
|
<refsection>
|
|
<title>See Also</title>
|
|
<para><xref linkend="validatetopology_returntype"/></para>
|
|
</refsection>
|
|
</refentry>
|
|
</sect1>
|
|
<sect1 id="Topology_Constructors">
|
|
<sect1info>
|
|
<abstract>
|
|
<para>This section covers the topology functions for creating new topogeometries, edges, faces, and nodes.</para>
|
|
</abstract>
|
|
</sect1info>
|
|
<title>TopoGeometry and other Topology Object Constructors</title>
|
|
<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>
|
|
|
|
|
|
<!-- use this format if new function -->
|
|
<para>Availability: 2.0.0 requires GEOS >= 3.3.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="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 get it's 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 get it's 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>
|
|
|
|
<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="TopologyPolygonize">
|
|
<refnamediv>
|
|
<refname>Polygonize</refname>
|
|
<refpurpose>Find and register 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>Register 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>
|
|
|
|
<!-- 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>
|
|
</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.
|
|
When adding a new node it checks for the existence of any edge crossing the given point, raising an exception if found.</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="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>
|
|
</funcsynopsis>
|
|
</refsynopsisdiv>
|
|
|
|
<refsection>
|
|
<title>Description</title>
|
|
|
|
<para>Creates a topogeometry object for layer denoted by layer_id and registers it in the relations table in tho <varname>toponame</varname> schema.</para>
|
|
<para>tg_type is an integer: 1:[multi]point, 2:[multi]line, 3:[multi]poly, 4:collection. layer_id is the layer id in the topology.layer table.</para>
|
|
|
|
<!-- use this format if new function -->
|
|
<para>Availability: 1.?</para>
|
|
</refsection>
|
|
|
|
|
|
<refsection>
|
|
<title>Examples</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>
|
|
|
|
<!-- Optionally add a "See Also" section -->
|
|
<refsection>
|
|
<title>See Also</title>
|
|
<para><xref linkend="AddTopoGeometryColumn"/>, <xref linkend="ST_CreateTopoGeo" />, <xref linkend="topoelementarray" /></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.? </para>
|
|
<para>&sqlmm_compliant; SQL-MM: Topo-Geo and Topo-Net 3: Routine Details: X.3.4</para>
|
|
</refsection>
|
|
|
|
|
|
<refsection>
|
|
<title>Examples</title>
|
|
<!-- 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_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.? </para>
|
|
<para>&sqlmm_compliant; SQL-MM: Topo-Net Routines: X+1.3.1</para>
|
|
</refsection>
|
|
|
|
|
|
<refsection>
|
|
<title>Examples</title>
|
|
<!-- 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_CreateTopoGeo">
|
|
<refnamediv>
|
|
<refname>ST_CreateTopoGeo</refname>
|
|
|
|
<refpurpose>Adds a collection of geometries to a given topology and returns a message detailing success. If collection contains anything but points and linestrings, an error is thrown. Will also
|
|
throw an error if there are already edges and nodes in the topology. polygon support not implemented yet.</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 topology and returns a message detailing success. If collection contains anything but points and linestrings an error is thrown. Will also
|
|
throw an error if there are already edges and nodes in the topology or coincident nodes etc. Support for polygons not yet implemented.</para>
|
|
|
|
<para>Useful for populating an empty topology.</para>
|
|
|
|
|
|
<!-- use this format if new function -->
|
|
<para>Availability: 1.? </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="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>
|
|
</sect1>
|
|
|
|
<sect1 id="Topology_Accessors">
|
|
<title>TopoGeometry and other Topology Object Accessors</title>
|
|
<refentry id="GetEdgeByPoint">
|
|
<refnamediv>
|
|
<refname>GetEdgeByPoint</refname>
|
|
|
|
<refpurpose>Find 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>tol</parameter></paramdef>
|
|
</funcprototype>
|
|
|
|
</funcsynopsis>
|
|
</refsynopsisdiv>
|
|
|
|
<refsection>
|
|
<title>Retrieve the id of an edge that intersects a Point</title>
|
|
|
|
<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 the point is the location of a node, then an exception is thrown. To avoid this run the GetNodeByPoint function.</para>
|
|
<para>If the point 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>
|
|
|
|
|
|
<!-- optionally mention that this function uses indexes if appropriate -->
|
|
<note>
|
|
<para>If tolerance = 0, the function use ST_Intersects otherwise uses ST_DWithin.</para>
|
|
</note>
|
|
<!-- use this format if new function -->
|
|
<para>Availability: 2.0.0 - requires GEOS >= 3.3.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" /></para>
|
|
</refsection>
|
|
</refentry>
|
|
|
|
<refentry id="GetFaceByPoint">
|
|
<refnamediv>
|
|
<refname>GetFaceByPoint</refname>
|
|
<refpurpose>Find the face-id of a face that intersects 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>tol</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
</refsynopsisdiv>
|
|
<refsection>
|
|
<para>Retrieve the id of a face that intersects a Point.</para>
|
|
<para>The function returns an integer (id-face) given a topology, a POINT and a tolerance. If tolerance = 0 then the point has to intersect the face.</para>
|
|
<para>If the point is the location of a node, then an exception is thrown. To avoid this run the GetNodeByPoint function.</para>
|
|
<para>If the point doesn't intersect a face, returns 0 (zero).</para>
|
|
<para>If use tolerance > 0 and there is more than one face near the point then an exception is thrown.</para>
|
|
|
|
<!-- optionally mention that this function uses indexes if appropriate -->
|
|
<note>
|
|
<para>If tolerance = 0, the function uses ST_Intersects otherwise uses ST_DWithin.</para>
|
|
</note>
|
|
<!-- use this format if new function -->
|
|
<para>Availability: 2.0.0 - requires GEOS >= 3.3.0. </para>
|
|
</refsection>
|
|
<refsection>
|
|
<title>Examples</title>
|
|
<para>These examples use edges faces created in <xref linkend="AddFace" /></para>
|
|
<programlisting>SELECT topology.GetFaceByPoint('ma_topo',geom, 10) As with1mtol, topology.GetFaceByPoint('ma_topo',geom,0) As withnotol
|
|
FROM ST_GeomFromEWKT('SRID=-1;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('SRID=-1;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="AddFace" />,<xref linkend="GetNodeByPoint" />,<xref linkend="GetEdgeByPoint" /></para>
|
|
</refsection>
|
|
</refentry>
|
|
|
|
<refentry id="GetNodeByPoint">
|
|
<refnamediv>
|
|
<refname>GetNodeByPoint</refname>
|
|
|
|
<refpurpose>Find the 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>point</parameter></paramdef>
|
|
<paramdef><type>float8 </type> <parameter>tol</parameter></paramdef>
|
|
</funcprototype>
|
|
|
|
</funcsynopsis>
|
|
</refsynopsisdiv>
|
|
|
|
<refsection>
|
|
<title>Retrieve the id of a node at a point location</title>
|
|
|
|
<para>The function return an integer (id-node) given a topology, a POINT and a tolerance. If tolerance = 0 mean exactly intersection otherwise retrieve the node from an interval.</para>
|
|
<para>If there isn't a node at the point, it return 0 (zero).</para>
|
|
<para>If use tolerance > 0 and near the point there are more than one node it throw an exception.</para>
|
|
|
|
|
|
<!-- optionally mention that this function uses indexes if appropriate -->
|
|
<note>
|
|
<para>If tolerance = 0, the function use ST_Intersects otherwise will use ST_DWithin.</para>
|
|
</note>
|
|
<!-- use this format if new function -->
|
|
<para>Availability: 2.0.0 - requires GEOS >= 3.3.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" /></para>
|
|
</refsection>
|
|
</refentry>
|
|
|
|
<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 topoelement <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.?</para>
|
|
</refsection>
|
|
|
|
|
|
<refsection>
|
|
<title>Examples</title>
|
|
<!-- 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: 1.?</para>
|
|
</refsection>
|
|
|
|
|
|
<refsection>
|
|
<title>Examples</title>
|
|
<!-- TODO: -->
|
|
</refsection>
|
|
|
|
<!-- Optionally add a "See Also" section -->
|
|
<refsection>
|
|
<title>See Also</title>
|
|
<para><xref linkend="GetTopoGeomElementArray"/>,<xref linkend="topoelement"/></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.?</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"/></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.?</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"/></para>
|
|
</refsection>
|
|
</refentry>
|
|
|
|
<refentry id="ST_GetFaceEdges">
|
|
<refnamediv>
|
|
<refname>ST_GetFaceEdges</refname>
|
|
|
|
<refpurpose>Returns a set of ordered edges that bound <varname>aface</varname> includes the sequence order.</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> includes the sequence order. 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.
|
|
</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 sequenc, 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="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.? </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>
|
|
|
|
</sect1>
|
|
|
|
<sect1 id="Topology_Processing">
|
|
<sect1info>
|
|
<abstract>
|
|
<para>This section covers topology functions for moving, deleting, and splitting edges, faces, and nodes.</para>
|
|
</abstract>
|
|
</sect1info>
|
|
<title>Topology Processing Functions</title>
|
|
<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>
|
|
<!--TODO: Need examples -->
|
|
</refsection>
|
|
|
|
<!-- Optionally add a "See Also" section -->
|
|
<refsection>
|
|
<title>See Also</title>
|
|
<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 in doing so it splits a face, modify the original
|
|
face and add a new face. Unless the face being split is the Universal Face,
|
|
the new edge will be on the right side of the newly added edge.
|
|
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>
|
|
<!--TODO: Need examples -->
|
|
</refsection>
|
|
|
|
<!-- Optionally add a "See Also" section -->
|
|
<refsection>
|
|
<title>See Also</title>
|
|
<para><xref linkend="ST_AddEdgeNewFaces"/></para>
|
|
</refsection>
|
|
</refentry>
|
|
|
|
<refentry id="ST_ChangeEdgeGeom">
|
|
<refnamediv>
|
|
<refname>ST_ChangeEdgeGeom</refname>
|
|
|
|
<refpurpose>Changes the linestring that define the specified edge. Will raise an error if the start and end points are not the same as the original or the new linestring
|
|
crosses an existing edge (not at end points) or new linestring is not simple.</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 linestring that defines the specified edge. Will raise an error if the start and end points are not the same as the original or the new linestring
|
|
crosses an existing edge (except at end points) or intersects another edge.</para>
|
|
<para>If any arguments are null, the given edge does not 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>
|
|
<para>If the new <varname>acurve</varname> is not simple, then an error is thrown.</para>
|
|
|
|
<!-- use this format if new function -->
|
|
<para>Availability: 1.x </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="AddEdge"/></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>text <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.
|
|
</para>
|
|
|
|
<!-- use this format if new function -->
|
|
<para>Availability: 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 result;
|
|
result
|
|
-------------------------
|
|
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>
|
|
Heal 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>
|
|
Heal 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>
|
|
Heal 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>
|
|
Heal 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>anedge</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) 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: 1.? </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.? </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.? </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>
|
|
-- Add 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_Outputs">
|
|
<title>Topology 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.</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>
|
|
</sect1>
|
|
</chapter>
|