= PostGIS Topology =


PostGIS topology support is in pre-alpha stage.
It consists in a topology schema model and accessory functions.

With topology support enabled you can store [wiki:UsersWikiTopologicalPrimitives topological elements],
define [wiki:UsersWikiTopoGeometry TopoGeometry] objects as being composed by these elements,
convert !TopoGeometry objects to simple [wiki:UsersWikiGeometryType Geometry] objects
to use all functions defined on the latter.

Topological elements are Faces, Edges and Nodes.

An entity-relationship [raw-attachment:topology-ER.pdf diagram] of the topology concepts can
be found in the SVN repository of PostGIS (trunk), under
the [source:trunk/topology/ER topology/ER/ directory].

The SVN repository also contains initial code, being a set of
definitions and pl/pgsql functions. A [source:trunk/topology/README README] file therein contains
usage and test notes.

= Enabling PostGIS Topology =

In order to enable PostGIS support you need to be equipped with the following:

 * A schema-aware PostgreSQL installation (7.3 and up)
 * PostGIS 1.3.x or up
 * GEOS 2.1 or up

Move under the topology/ directory and run:

{{{
$ make
$ psql -f topology.sql <your_test_database>
}}}

No C libs involved so far, so no need to make install.

To uninstall/disable just drop the 'topology' schema. It contains
all the objects installed by the topology.sql script (remember to cascade).

= Creating a Topology =

Topology data are stored in named SCHEMAs, where the topology
name is the name of the SCHEMA containing its data.

A catalogue of avalable topologies is kept under the
"topology"."topology" table.

To create/destroy a topology:

{{{
SELECT topology.CreateTopology(name, [srid], [tolerance]);
SELECT topology.DropTopology(name);
}}}


== Loading Topology data ==

To load topology data in a topology you can use INSERT
statements filling up the Edge, Node and Face relations
under your topology schema:


 * Edge
  * edge_id integer PRIMARY KEY
  * start_node integer REFERENCES Node.node_id)
  * end_node integer REFERENCES Node.node_id)
  * next_left_edge integer REFERENCES abs(Edge.edge_id)
  * next_right_edge integer REFERENCES abs(Edge.edge_id)
  * left_face integer REFERENCES Face.face_id
  * right_face integer REFERENCES Face.face_id
  * geom geometry ( a linestring )


 * Node
  * node_id integer PRIMARY KEY
  * containing_face integer REFERENCES Face.face_id
  * geom geometry ( a point )

 * Face
  * face_id integer PRIMARY KEY
  * mbr box2d ( can be NULL )

Details on semantic are contained in the SQL/MM specification, which
this implementation follows as for these views structure.

== Validating Topology ==

To verify validity of a topology:

{{{
SELECT * FROM topology.ValidateTopology(name);
}}}

The return set will contain references to elements involved in the invalidity.

== Editing a Topology ==

See [wiki:UsersWikiTopologyEditing TopologyEditing]

= Working with !TopoGeometry objects =

See [wiki:UsersWikiCreatingTopoGeometryObjects CreatingTopoGeometryObjects]

== Getting simple Geometry values from !TopoGeometry objects ==

You currently need to explicit call the !TopoGeometry=>Geometry
cast function. This will probably be made implicit when the
code is more tested:

{{{
SELECT topology.Geometry(TopoGeometry);
}}}

= Testing Topology implementation =

Tests are included under the [source:trunk/topology/test/ topology/test] directory.
Run make w/out args to see a list of supported targets.