= 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 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 diagram of the topology concepts can
be found in the CVS repository of PostGIS (head branch), under
the topology/ER directory.

The CVS repository also contains initial code, being a set of
definitions and pl/pgsql functions. A 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.1.x (current HEAD branch in CVS)
 * 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 [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 TopologyEditing

= Working with !TopoGeometry objects =

See 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 topology/test/ directory.
Run make w/out args to see a list of supported targets.