Navigation :

Chapter 11. Topology

Chapter 11. Topology
Prev       Next

Chapter 11. Topology

Table of Contents

11.1. Topology Types
11.2. Topology Domains
11.3. Topology and TopoGeometry Management
11.4. Topology Constructors
11.5. Topology Editors
11.6. Topology Accessors
11.7. Topology Processing
11.8. TopoGeometry Constructors
11.9. TopoGeometry Editors
11.10. TopoGeometry Accessors
11.11. TopoGeometry Outputs
11.12. Topology Spatial Relationships

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.

To build PostGIS 2.0 with topology support, compile with the --with-topology option as described in Chapter 2, PostGIS Installation . Some functions depend on GEOS 3.3+ so you should compile with GEOS 3.3+ to fully utilize the topology support.

11.1. Topology Types

Abstract

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.

getfaceedges_returntype — A composite type that consists of a sequence number and edge number. This is the return type for ST_GetFaceEdges
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

11.2. Topology Domains

Abstract

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

11.3. Topology and TopoGeometry Management

Abstract

This section lists the Topology functions for building new Topology schemas, validating topologies, and managing TopoGeometry Columns

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.
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.
DropTopoGeometryColumn — Drops the topogeometry column from the table named table_name in schema schema_name and 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

11.4. Topology Constructors

Abstract

This section covers the topology functions for creating new topologies.

CreateTopology — Creates a new topology schema and registers this new schema in the topology.topology table.
CopyTopology — Makes a copy of a topology structure (nodes, edges, faces, layers and TopoGeometries).
ST_InitTopoGeo — Creates a new topology schema and registers this new schema in the topology.topology table and details summary of process.
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.

11.5. Topology Editors

Abstract

This section covers topology functions for adding, moving, deleting, and splitting edges, faces, and nodes. All of these functions are defined by ISO SQL/MM.

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 alinestring to a topology connecting two existing isolated nodes anode and anothernode and 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 removed edge separated two faces, delete one of the them and modify the other to take 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 — 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.
ST_NewEdgeHeal — 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.
ST_MoveIsoNode — Moves an isolated node in a topology from one point to another. If new apoint geometry 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.

11.6. Topology Accessors

GetEdgeByPoint — Find the edge-id of an edge that intersects a given point
GetFaceByPoint — Find the face-id of a face that intersects a given point
GetNodeByPoint — Find the 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.

11.7. Topology Processing

Abstract

This section covers the functions for processing topologies in non-standard ways.

Polygonize — Find and register 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.

11.8. TopoGeometry Constructors

Abstract

This section covers the topology functions for creating new topogeometries.

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 topoelementarray for a set of element_id, type arrays (topoelements)

11.9. TopoGeometry Editors

Abstract

This section covers the topology functions for editing existing topogeometries.

clearTopoGeom — Clears the content of a topo geometry
TopoGeom_addElement — Add an element to the definition of a TopoGeometry
TopoGeom_remElement — Remove an element from the definition of a TopoGeometry
toTopoGeom — Adds a geometry shape to an existing topo geometry

11.10. TopoGeometry Accessors

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 topoelement objects containing the topological element_id,element_type of the given TopoGeometry (primitive elements)

11.11. TopoGeometry Outputs

AsGML — Returns the GML representation of a topogeometry.
AsTopoJSON — Returns the TopoJSON representation of a topogeometry.

11.12. Topology Spatial Relationships

Abstract

This section lists the Topology functions used to check relationships between topogeometries and topology primitives

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.
Prev       Next
Chapter 10. PostGIS Raster Frequently Asked Questions  Home  getfaceedges_returntype