Chapter 9. Topology

Table of Contents

Los tipos y funciones de PostGIS Topology son usados para manejar objetos topológicos tales como caras, bordes y nodos.

La presentación de Sandro Santilli en la conferencia PostGIS Day Paris 2011 da una buena sinopsis de la Topología PostGIS y hacia donde se dirige 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 ejemplo de una base de datos SIG basado topologicamente en la base de datos del Sistema de Codificación y Referencia Geográfica Topologicamente Integrado del Censo de US (TIGER) . Si desea experimentar con la topología de PostGIS y nesesita algunos datos, ver Topology_Load_Tiger.

El módulo de topología ha existido en versiones anteriores de PostGIS pero nunca hizo parte de la documentación oficial. En PostGIS 2.0.0 una limpieza a gran escala está teniendo lugar con el fin de eliminar el uso de todas las funciones obsoletas, solucionar los problemas de usabilidad conocidos, documentar mejor las características y funciones, agregar nuevas funciones y mejorarlo para satisfacer más de cerca los estándares SQL-MM.

Detalles de este proyecto pueden encontrarse en PostGIS Topology Wiki

Todas las funciones y tablas asociadas con este módulo son instaladas en un esquema llamado topology

Las funciones que son definidas bajo el estandar SQL/MM son prefijadas con ST_ y las funciones específicas a PostGIS no son prefijadas.

El soporte de topología se crea de manera predeterminada a partir de PostGIS 2.0, y se puede deshabilitar especificando la opción de configuración --without-topology en tiempo de compilación como se describe en Chapter 2, Instalación de PostGIS

9.1. Tipos en Topology

Abstract

Esta sección lista los tipos de datos de PostgreSQL instalados por PostGIS Topology. Note que describimos el comportamiento de la conversión de estos, lo cual es muy importante especialmente cuando diseñe sus propias funciones.

  • getfaceedges_returntype — Un tipo compuesto que necesita un número de secuencia y un número de eje.
  • TopoGeometry — Un tipo compuesto que representa una geometría topológicamente definida.
  • validatetopology_returntype — Un tipo compuesto que consta de un mensaje de error e id1 e id2 para denotar la ubicación del error. Este es el tipo de valor devuelto por ValidateTopology.

9.2. Dominios de Topology

Abstract

Esta sección enumera los dominios de PostgreSQL instalados por la topología de PostGIS. Los dominios pueden utilizarse como tipos de objetos como retorno de funciones o columnas de la tabla. La distinción entre un dominio y un tipo es que un dominio es un tipo existente con una restricción de control limitado a él.

  • TopoElement — Una matriz de 2 enteros usada generalmente para identificar un componente TopoGeometry
  • TopoElementArray — Matriz de objetos TopoElement.

9.3. Topología y Gestión de TopoGeometría

Abstract

Esta sección lista las funciones de Topología para construir nuevos esquemas Topology, validar las topologías, y manipular las columnas TopoGeometry.

  • AddTopoGeometryColumn — Agrega una columna topogeometry a una tabla existente, registra esta nueva columna como una capa en topology.layer y devuelve el nuevo layer_id
  • RenameTopoGeometryColumn — Renames a topogeometry column
  • DropTopology — Usar con precaución: Permite eliminar un esquema de topología y elimina su referencia de la talbla topology.topology y referencias a las tablas en ese esquema desde la tabla geometry_columns
  • RenameTopology — Renames a topology
  • DropTopoGeometryColumn — Elimina la columna topogeometry de la tabla nombrada en table_name en el esquema schema_name y anula el registro de las columnas de la tabla topology.layer.
  • Populate_Topology_Layer — Agrega entradas faltantes a la tabla topology.layer mediante la lectura de metadatos de las tablas de topo.
  • TopologySummary — Toma un nombre de topología y proporciona totales de resumen de tipos de objetos en la topología.
  • ValidateTopology — Devuelve un conjunto de objetos validatetopology_returntype que detallan problemas con la topología.
  • 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.

9.4. 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.5. Constructores de Topología

Abstract

Esta sección cubre las funciones de topología para crear nuevas topologías.

  • 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 — Agrega una colección de geometrías a una topología vacía dada y devuelve un mensaje que detalla el éxito.
  • TopoGeo_AddPoint — Agrega un punto a una topología existente utilizando una tolerancia y posiblemente dividiendo un borde existente.
  • TopoGeo_AddLineString — Agrega una cadena de línea a una topología existente utilizando una tolerancia y posiblemente dividiendo las aristas/caras existentes. Devuelve identificadores de borde.
  • TopoGeo_AddPolygon — Agrega un polígono a una topología existente utilizando una tolerancia y posiblemente dividiendo las aristas/caras existentes. Devuelve identificadores de cara.

9.6. Editores de Topología

Abstract

Esta sección cubre las funciones de topología para agregar, mover, eliminar y dividir aristas, caras y nodos. Todas estas funciones están definidas por ISO SQL/MM.

  • ST_AddIsoNode — Agrega un nodo aislado a una cara de una topología y devuelve el identificardor de nodo del nuevo nodo. Si la cara es nula, el nodo es creado de todas maneras.
  • ST_AddIsoEdge — Agrega un borde aislado definido por la geometría alinestring a una topología que conecta dos nodos aislados existentes anode y anothernode y devuelve el identificador de borde del nuevo borde.
  • ST_AddEdgeNewFaces — Agrega un nuevo borde y, si al hacerlo divide una cara, se elimina la cara original y es reemplazada con dos nuevas caras.
  • ST_AddEdgeModFace — Añada un nuevo borde y, si al hacerlo, divide una cara, modifica la cara original y añade una nueva cara.
  • ST_RemEdgeNewFace — Elimina un borde y, si el borde eliminado separa dos caras, borra las caras originales y las reemplaza con una nueva cara.
  • 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 — Cambia la forma de un borde sin afectar la estructura de la topología.
  • ST_ModEdgeSplit — Dividir un borde creando un nuevo nodo a lo largo de un borde existente, modificando el borde original y agregando un nuevo borde.
  • ST_ModEdgeHeal — Cura dos aristas eliminando el nodo que las conecta, modificando la primera arista y eliminando la segunda arista. Devuelve el identificador del nodo eliminado.
  • ST_NewEdgeHeal — Cura dos aristas eliminando el nodo que las conecta, eliminando ambas aristas y sustituyéndolas por una arista cuya dirección sea la misma que la primera arista proporcionada.
  • ST_MoveIsoNode — Mueve un nodo aislado en una topología de un punto a otro. Si la nueva geometría apoint existe como nodo se lanza un error. Devuelve la descripción del movimiento.
  • ST_NewEdgesSplit — Divide un borde creando un nuevo nodo a lo largo de un borde existente, eliminando el borde original y reemplazandolo con dos bordes nuevos. Devuelve el identificador del nuevo nodo creado que une los nuevos bordes.
  • ST_RemoveIsoNode — Elimina un nodo aislado y devuelve la descripción de la acción. Si el nodo no está aislado (es el inicio o el final de un borde), entonces se lanza una excepción.
  • ST_RemoveIsoEdge — Elimina un borde aislado y devuelve la descripción de la acción. Si el borde no está aislado, se lanza una excepción.

9.7. Accesores de Topología

  • GetEdgeByPoint — Busca el identificador de arista de una arista que cruza un punto determinado.
  • GetFaceByPoint — Finds face intersecting a given point.
  • GetFaceContainingPoint — Finds the face containing a point.
  • GetNodeByPoint — Busca el identificador de nodo de un nodo en un punto de ubicación.
  • GetTopologyID — Devuelve el identificador de una topología en la tabla topology.topology dado el nombre de la topología.
  • GetTopologySRID — Devuelve el SRID de una topología en la tabla topology.topology dado el nombre de la topología.
  • GetTopologyName — Devuelve el nombre de una topología (esquema) dado el identificador de la topología.
  • ST_GetFaceEdges — Devuelve un conjunto de bordes ordenados que ligan aface.
  • ST_GetFaceGeometry — Devuelve el polígono en la topología dada con el identificador de la cara especificada.
  • GetRingEdges — Devuelve el conjunto ordenado de identificadores de borde con signo asignado al caminar en un lado de borde dado.
  • GetNodeEdges — Devuelve un conjunto ordenado de aristas incidente al nodo dado.

9.8. Procesamiento de Topología

Abstract

Esta sección cubre las funciones para el procesamiento de topologías de formas no estándar.

  • Polygonize — Busca y registra todas las caras definidas por aristas de topología.
  • AddNode — Agrega un nodo de punto a la tabla de nodos del esquema de topología especificado y devuelve el identificador de nodo del nuevo nodo. Si el punto ya existe como nodo, se devuelve el identificador de nodo existente.
  • AddEdge — Agrega una arista de LineString a la tabla de arista y los puntos de inicio y fin asociados a la tabla nodos de puntos del esquema de topología usando la geometría LineString especificada y devuelve el identificador de arista de la arista nueva (o existente).
  • AddFace — Registra una primitiva de cara a una topología y obtiene su identificador.
  • ST_Simplify — Devuelve una versión "simplificada" de la geometría de la TopoGeometry dada usando el algoritmo de Douglas-Peucker.
  • RemoveUnusedPrimitives — Removes topology primitives which not needed to define existing TopoGeometry objects.

9.9. Constructores de Geometría Topográfica

Abstract

Esta sección cubre las funciones de topología para la creación de nuevos topogeometries.

  • CreateTopoGeom — Crea un nuevo objeto de geometría topo de la matriz de elementos topo - tg_type: 1:[multi]point, 2:[multi]line, 3:[multi]poly, 4:collection
  • toTopoGeom — Convierte un Geometry simple en una geometría topo.
  • TopoElementArray_Agg — Devuelve un topoelementarray para un conjunto de element_id, matriz de tipo (topoelements).
  • TopoElement — Converts a topogeometry to a topoelement.

9.10. Editores TopoGeometry

Abstract

Esta sección cubre las funciones de topología para editar topogeometries existentes.

  • clearTopoGeom — Borra el contenido de una topo geometry.
  • TopoGeom_addElement — Agrega un elemento a la definición de una TopoGeometry.
  • TopoGeom_remElement — Quita un elemento de la definición de una TopoGeometry.
  • TopoGeom_addTopoGeom — Adds element of a TopoGeometry to the definition of another TopoGeometry.
  • toTopoGeom — Agrega una forma de geometría a una geometría topográfica existente.

9.11. Descriptores de Geometría Topográfica

  • GetTopoGeomElementArray — Devuelve un topoelementarray (una matriz de topoelements) que contiene los elementos topológicos y el tipo de la TopoGeometry (elementos primitivos) especificados.
  • GetTopoGeomElements — Devuelve un conjunto de objetos topoelement que contienen el element_id topológico, element_type de la TopoGeometry (elementos primitivos) especificados.
  • ST_SRID — Returns the spatial reference identifier for a topogeometry.

9.12. Salidas de Geometría Topográfica

  • AsGML — Devuelve una representación GML de una geometría topográfica.
  • AsTopoJSON — Devuelve la representación TopoJSON de una topogeometry.

9.13. Relaciones espaciales de topología

Abstract

En esta sección se enumeran las funciones de topología utilizadas para comprobar las relaciones entre topogeometries y primitivas de topología

  • Equals — Devuelve true si dos topogeometries están compuestas de las mismas primitivas topologicas.
  • Intersects — Devuelve verdadero si cualquier par de primitivas de las dos topogeometries se intersectan.

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