Chapter 8. Topology
- 8.1. Topology Types
- 8.2. Topology Domains
- 8.3. Topology and TopoGeometry Management
- 8.4. Topology Statistics Management
- 8.5. Topology Constructors
- 8.6. Topology Editors
- 8.7. Topology Accessors
- 8.8. Topology Processing
- 8.9. TopoGeometry Constructors
- 8.10. TopoGeometry Editors
- 8.11. TopoGeometry Accessors
- 8.12. TopoGeometry Outputs
- 8.13. Topology Spatial Relationships
- 8.14. Importing and exporting Topologies
The PostGIS Topology types and functions are used to manage topological objects such as faces, edges and nodes.
Sandro Santilli's presentation at PostGIS Day Paris 2011 conference gives a good synopsis of PostGIS Topology and where it is headed Topology with PostGIS 2.0 slide deck .
Vincent Picavet provides a good synopsis and overview of what is Topology, how is it used, and various FOSS4G tools that support it in PostGIS Topology PGConf EU 2012 .
An example of a topologically based GIS database is the US Census Topologically Integrated Geographic Encoding and Referencing System (TIGER) database. If you want to experiment with PostGIS topology and need some data, check out Topology_Load_Tiger .
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.
Details of this project can be found at PostGIS Topology Wiki
All functions and tables associated with this module are installed in a schema called
topology
.
Functions that are defined in SQL/MM standard are prefixed with ST_ and functions specific to PostGIS are not prefixed.
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 Chapter 2, PostGIS Installation
- getfaceedges_returntype — A composite type that consists of a sequence number and an edge number.
- TopoGeometry — A composite type representing a topologically defined geometry.
-
validatetopology_returntype
— A composite type that consists of an error message and id1 and id2 to denote location of error. This is the return type for
ValidateTopology.
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.
- TopoElement — An array of 2 integers generally used to identify a TopoGeometry component.
- TopoElementArray — An array of TopoElement objects.
- AddTopoGeometryColumn — Adds a topogeometry column to an existing table, registers this new column as a layer in topology.layer and returns the new layer_id.
- RenameTopoGeometryColumn — Renames a topogeometry column
- DropTopology — 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.
- RenameTopology — Renames a topology
-
DropTopoGeometryColumn
— Drops the topogeometry column from the table named
table_namein schemaschema_nameand unregisters the columns from topology.layer table. - Populate_Topology_Layer — Adds missing entries to topology.layer table by reading metadata from topo tables.
- TopologySummary — Takes a topology name and provides summary totals of types of objects in topology.
- ValidateTopology — Returns a set of validatetopology_returntype objects detailing issues with topology.
- ValidateTopologyRelation — Returns info about invalid topology relation records
- FindTopology — Returns a topology record by different means.
- FindLayer — Returns a topology.layer record by different means.
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.
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.
![[Note]](./images/note.png)
|
|
|
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. |
- CreateTopology — Creates a new topology schema and registers it in the topology.topology table.
- CopyTopology — Makes a copy of a topology (nodes, edges, faces, layers and TopoGeometries) into a new schema
- ST_InitTopoGeo — Creates a new topology schema and registers it in the topology.topology table.
- ST_CreateTopoGeo — Adds a collection of geometries to a given empty topology and returns a message detailing success.
- TopoGeo_AddPoint — Adds a point to an existing topology using a tolerance and possibly splitting an existing edge.
- TopoGeo_AddLineString — Adds a linestring to an existing topology using a tolerance and possibly splitting existing edges/faces. Returns edge identifiers.
- TopoGeo_AddPolygon — Adds a polygon to an existing topology using a tolerance and possibly splitting existing edges/faces. Returns face identifiers.
- ST_AddIsoNode — 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.
-
ST_AddIsoEdge
— Adds an isolated edge defined by geometry
alinestringto a topology connecting two existing isolated nodesanodeandanothernodeand returns the edge id of the new edge. - ST_AddEdgeNewFaces — Add a new edge and, if in doing so it splits a face, delete the original face and replace it with two new faces.
- ST_AddEdgeModFace — Add a new edge and, if in doing so it splits a face, modify the original face and add a new face.
- ST_RemEdgeNewFace — Removes an edge and, if the removed edge separated two faces, delete the original faces and replace them with a new face.
- ST_RemEdgeModFace — Removes an edge, and if the edge separates two faces deletes one face and modifies the other face to cover the space of both.
- ST_ChangeEdgeGeom — Changes the shape of an edge without affecting the topology structure.
- ST_ModEdgeSplit — Split an edge by creating a new node along an existing edge, modifying the original edge and adding a new edge.
- ST_ModEdgeHeal — 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.
- ST_NewEdgeHeal — 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.
-
ST_MoveIsoNode
— Moves an isolated node in a topology from one point to another. If new
apointgeometry exists as a node an error is thrown. Returns description of move. - ST_NewEdgesSplit — 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.
- ST_RemoveIsoNode — 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.
- ST_RemoveIsoEdge — Removes an isolated edge and returns description of action. If the edge is not isolated, then an exception is thrown.
- GetEdgeByPoint — Finds the edge-id of an edge that intersects a given point.
- GetFaceByPoint — Finds face intersecting a given point.
- GetFaceContainingPoint — Finds the face containing a point.
- GetNodeByPoint — Finds the node-id of a node at a point location.
- GetTopologyID — Returns the id of a topology in the topology.topology table given the name of the topology.
- GetTopologySRID — Returns the SRID of a topology in the topology.topology table given the name of the topology.
- GetTopologyName — Returns the name of a topology (schema) given the id of the topology.
-
ST_GetFaceEdges
— Returns a set of ordered edges that bound
aface. - ST_GetFaceGeometry — Returns the polygon in the given topology with the specified face id.
- GetRingEdges — Returns the ordered set of signed edge identifiers met by walking on an a given edge side.
- GetNodeEdges — Returns an ordered set of edges incident to the given node.
- Polygonize — Finds and registers all faces defined by topology edges.
- AddNode — 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.
- AddEdge — 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.
- AddFace — Registers a face primitive to a topology and gets its identifier.
- ST_Simplify — Returns a "simplified" geometry version of the given TopoGeometry using the Douglas-Peucker algorithm.
- RemoveUnusedPrimitives — Removes topology primitives which not needed to define existing TopoGeometry objects.
- CreateTopoGeom — Creates a new topo geometry object from topo element array - tg_type: 1:[multi]point, 2:[multi]line, 3:[multi]poly, 4:collection
- toTopoGeom — Converts a simple Geometry into a topo geometry.
-
TopoElementArray_Agg
— Returns a
topoelementarrayfor a set of element_id, type arrays (topoelements). - TopoElement — Converts a topogeometry to a topoelement.
- clearTopoGeom — Clears the content of a topo geometry.
- TopoGeom_addElement — Adds an element to the definition of a TopoGeometry.
- TopoGeom_remElement — Removes an element from the definition of a TopoGeometry.
- TopoGeom_addTopoGeom — Adds element of a TopoGeometry to the definition of another TopoGeometry.
- toTopoGeom — Adds a geometry shape to an existing topo geometry.
-
GetTopoGeomElementArray
— Returns a
topoelementarray(an array of topoelements) containing the topological elements and type of the given TopoGeometry (primitive elements). -
GetTopoGeomElements
— Returns a set of
topoelementobjects containing the topological element_id,element_type of the given TopoGeometry (primitive elements). - ST_SRID — Returns the spatial reference identifier for a topogeometry.
- AsGML — Returns the GML representation of a topogeometry.
- AsTopoJSON — Returns the TopoJSON representation of a topogeometry.
- Equals — Returns true if two topogeometries are composed of the same topology primitives.
- Intersects — Returns true if any pair of primitives from the two topogeometries intersect.
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.
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.
In order to simplify export/restore of topologies a pair of
executables are provided:
pgtopo_export
and
pgtopo_import
. Example usage:
pgtopo_export dev_db topo1 | pgtopo_import topo1 | psql staging_db
The
pgtopo_export
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.
By default
pgtopo_export
writes the
dump file to the standard output so that it can be piped to
pgtopo_import
or redirected to a file
(refusing to write to terminal). You can optionally specify
an output filename with the
-f
commandline switch.
By default
pgtopo_export
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
--skip-layers
switch and deal with those
separately.
Invoking
pgtopo_export
with the
--help
(or
-h
for short) switch
will always print short usage string.
The dump file format is a compressed tar archive of a
pgtopo_export
directory containing
at least a
pgtopo_dump_version
file with
format version info. As of version
1
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
--skip-layers
is given) a custom-format
PostgreSQL dump of tables reported as being layers of the given
topology.
The
pgtopo_import
script takes a
pgtopo_export
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.
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.
By default
pgtopo_import
reads the dump
from the standard input so that it can be used in conjuction
with
pgtopo_export
in a pipeline.
You can optionally specify an input filename with the
-f
commandline switch.
By default
pgtopo_import
includes in the output
SQL file the code to restore all layers found in the dump.
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
--skip-layers
switch and deal with those separately (or later).
SQL to only load and link layers to a named topology can be generated
using the
--only-layers
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).