Chapter 9. Topologia
Prev     Next

Chapter 9. Topologia

Table of Contents

I tipi e le funzioni della Topologia PostGIS si usano per gestire oggetti topologici quali facce, bordi e nodi.

La presentazione di Sandro Santilli alla conferenza PostGIS Day Paris 2011 fornisce una buona introduzione alla Topologia PostGIS 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.

Un esempio di database GIS topologico è il database del US Census Topologically Integrated Geographic Encoding and Referencing System (TIGER). Se vuoi sperimentare con la topologia PostGIS ed hai bisogno di dati, vedi Topology_Load_Tiger.

The PostGIS topology module has existed for a long time but was not always part of the official documentation. Extensive cleanup removed deprecated functions, fixed known usability issues, documented the features and functions, added new functionality, and improved SQL-MM compliance.

Dettagli del progetto si possono trovare sul PostGIS Topology Wiki

Tutte le funzioni e le tabelle associate con questo modulo sono installate in uno schema chiamato topology.

Le funzioni definite dallo standard SQL/MM hanno il prefisso ST_ e le funzioni specifiche di PostGIS sono senza prefisso.

Topology support is built by default and can be disabled by specifying the --without-topology configure option at build time as described in Chapter 2, Installazione PostGIS

9.1. Topology Primitive Tables

The core primitives of any topology are stored in the edge_data, node, and face tables that live in the schema created by CreateTopology. Each row of edge_data represents an oriented edge: it records a directed curve from start_node to end_node together with the identifier of the face encountered on the left of that direction (left_face) and the face encountered on the right (right_face). The same geometric segment may therefore appear twice—once for each orientation—when it belongs to two faces.

The next_left_edge and next_right_edge columns complete this orientation information by encoding how to keep walking around a face. They store signed integers whose absolute value is the identifier of the next oriented edge and whose sign determines whether the stored orientation has to be followed as-is or reversed when traversing. Formally, the following rules hold for every edge e:

  • abs(next_left_edge) is the identifier of the edge reached by continuing around the face that lies to the left of e. If the value is positive the walk continues from the end node of e along the stored orientation of the referenced edge; if it is negative the referenced edge must be followed backwards so that the shared face remains on the walker’s left.

  • abs(next_right_edge) analogously follows the boundary of the face located on the right of e. A positive value means that the next edge is taken with its recorded orientation starting from the end node of e, whereas a negative value instructs to traverse the referenced edge in reverse, starting from its end node, so that the right-hand face is preserved.

  • A zero value indicates that the edge is dangling on the corresponding side (for example an isolated edge whose incident face is the universal face 0). The abs_next_left_edge and abs_next_right_edge columns exposed by the edge view are convenience projections of these absolute values.

This representation is a variant of a doubly connected edge list and is exploited by many topology routines. Functions such as GetRingEdges and ValidateTopology rely on it to reconstruct face boundaries and to diagnose inconsistencies—hence the “invalid next_left_edge” and “invalid next_right_edge” diagnostics reported during validation. Constructors like AddEdge initialise the next_* attributes with trivial self references, while editing routines including ST_AddEdgeModFace and ST_RemEdgeModFace update the links as edges are inserted or removed. Other bulk operations (for example Polygonize) may intentionally leave the fields unset, which is why the documentation flags their behaviour explicitly.

9.2. Tipi di dato topologici

Abstract

Questa sezione contiene una lista dei tipi di dato PostgreSQL installati dalla Topologia PostGIS. Nota che sono descritti i comportamenti di conversione di questi tipi di dato, informazione molto importante nel progettazione di funzioni proprie.

  • getfaceedges_returntype — Un tipo di dato composto che consiste in un numero sequenziale e un identificativo di edge.
  • TopoGeometry — Un tipo di dato composto che rappresenta una geometria definita topologicamente.
  • validatetopology_returntype — Un tipo di dato composto che consiste in un messaggio di errore e due identificativi (id1 e id2) che denotano la locazione spaziale dell'errore. Questo è il tipo di dato ritornato da ValidateTopology.

9.3. Domini Topologici

Abstract

Questa sezione contiene una lista dei domini PostgreSQL installati dalla Topologia PostGIS. I domini possono essere usati come tipo di dato per gli oggetti ritornati da alcune funzioni o utilizzati come colonne di tabelle. La distinzione tra un dominio e un tipo è che un dominio è un tipo esistente con dei vincoli di controllo associati.

  • TopoElement — Una array di due interi generalmente usata per identificare una componente di una TopoGeometry.
  • TopoElementArray — Un'array di oggetti di tipo TopoElement.

9.4. Gestione di topologie e TopoGeometry

Abstract

Questa sezione fornisce una lista delle funzioni topologiche usate per costruire nuovi schemi topologici, validare le topologie e gestire le colonne di tipo TopoGeometry

  • AddTopoGeometryColumn — Aggiunge una colonna di tipo TopoGeometry ad una tabella esistente, registra la nuova colonna come layer nella tabella topology.layer e restituisce il nuovo layer_id.
  • RenameTopoGeometryColumn — Renames a topogeometry column
  • DropTopology — Usare con cautela: cancella uno schema topologico e cancella i riferimenti ad esso dalla tabella topology.topology e dalla vista geometry_columns.
  • RenameTopology — Renames a topology
  • DropTopoGeometryColumn — Drops the topogeometry column from the table named table_name in schema schema_name and unregisters the columns from topology.layer table.
  • FixCorruptTopoGeometryColumn — Fixes topogeometry corruption caused by upgrade to postgis_topology 3.6.0 and higher
  • 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
  • ValidateTopologyPrecision — Returns non-precise vertices in the topology.
  • MakeTopologyPrecise — Snap topology vertices to precision grid.
  • FindTopology — Returns a topology record by different means.
  • FindLayer — Returns a topology.layer record by different means.
  • TotalTopologySize — Total disk space used by the specified topology, including all indexes and TOAST data.
  • UpgradeTopology — Upgrades the specified topology to support large ids (int8) for topology and primitive ids.

9.5. Topology Statistics Management

Abstract

This section discusses management of database statistics during topology building.

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]

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.

9.6. Topology Constructors

Abstract

This section covers the topology functions for creating new topologies.

  • 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.
  • TopoGeo_AddPolygon — Adds a polygon to an existing topology using a tolerance and possibly splitting existing edges/faces. Returns face identifiers.
  • TopoGeo_LoadGeometry — Load a geometry into an existing topology, snapping and splitting as needed.

9.7. 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 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 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.

9.8. Topology Accessors

  • 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.

9.9. Topology Processing

Abstract

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

  • 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.

9.10. 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).
  • TopoElement — Converts a topogeometry to a topoelement.

9.11. TopoGeometry Editors

Abstract

This section covers the topology functions for editing existing topogeometries.

9.12. 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).
  • ST_SRID — Returns the spatial reference identifier for a topogeometry.

9.13. TopoGeometry Outputs

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

9.14. 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.

9.15. Importing and exporting Topologies

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

9.15.1. Using the Topology exporter

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.

9.15.2. Using the Topology importer

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 conjunction 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).

If the target topology already exists and you want it dropped upfront you can pass the --drop-topology switch (since PostGIS-3.6.0).