Updates to the documentation (new functions, 0.6 special info, mapserver

info). Other release-specific updates in CHANGES, README, TODO to give
info on the new code.


git-svn-id: http://svn.osgeo.org/postgis/trunk@64 b70326c6-7e19-0410-871a-916f4a2858ee

CHANGES

@@ -1,3 +1,48 @@
+PostGIS 0.6
+
+- New functions
+  - postgis_version()
+    Return the PostGIS version number.
+  - find_srid(<db/schema>::varchar, <table>::varchar, <column>::varchar)
+    Return the SRID number for a particular column of a database.
+  - AddGeometryColumn(<db/schema>::varchar, <table>::varchar,
+      <column>::varchar, <srid>::integer, <type>::varchar, 
+      <dimension>::integer)
+    Appends a geometry column to an existing table and updates the
+    metadata tables appropriately.
+  - DropGeometryColumn(<db/schema>::varchar, <table>::varchar, 
+      <column>::varchar)
+    Removes a geometry column from an existing spatial table.
+  - Distance(<geom1>::geometry, <geom2>::geometry)
+    Returns the cartesian distance between two geometries.
+  - AsText(<geom>::geometry)
+    Returns the OGC well-known text version of the geometry.
+  - SRID(<geom>::geometry)
+    Returns the integer SRID of the geometry.
+  - GeometryFromText(<geom>::varchar, <srid>::integer)
+    Creates a geometry object given the OGC well-known text and a valid
+    SRID.
+  - SetSRID(<geom>::geometry)
+    Sets the SRID of a geometry to a particular value.
+  - IsClosed(<geom>::geometry)
+    Returns true of first and last points of geometry are coincident.
+  - StartPoint(<geom>::geometry)
+    Returns the first point of a geometry.
+  - EndPoint(<geom>::geometry)
+    Returns the last point of a geometry.
+  - Centroid(<geom>::geometry)
+    Returns the centroid of a geometry.
+- More OpenGIS SFSQL compatibility
+  - SPATIAL_REF_SYS table
+  - GEOMETRY_COLUMNS table
+  - SRID integrity checking
+- Better Mapserver compatibility
+- Minor fixes/changes
+  - Support for WKB in the tables
+  - Miscellaneous bug fixes
+  - Placeholders for precision grid
+
+
 PostGIS 0.5
 
 - New functions

Makefile

@@ -19,7 +19,7 @@ test_db = geom_regress
 # shared library parameters
 NAME=postgis
 SO_MAJOR_VERSION=0
-SO_MINOR_VERSION=5
+SO_MINOR_VERSION=6
 
 #override CPPFLAGS := -I$(srcdir) $(CPPFLAGS)
 # Altered for Cynwin

README.postgis

@@ -1,7 +1,7 @@
 PostGIS - Geographic Information Systems Extensions to PostgreSQL
 ~~~~~~~   ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-VERSION: 0.5 (2001/07/20)
+VERSION: 0.6 (2001/09/20)
 
 MORE INFORMATION: http://postgis.refractions.net
 
@@ -12,15 +12,15 @@ and analyzing geographic data.
 
 Directory structure:
 
-	./      Core source code, makefiles and install directions.
-	./jdbc  Extensions to the PostgreSQL JDBC drivers to support
-	        the GIS objects. 
-	./doc   Documentation on the code, objects and functions 
-	        provided. 
-	./loader  A program to convert ESRI Shape files into SQL text
-	        suitable for uploading into a PostGIS/PostgreSQL database.
-	./examples  Small programs which demonstrate ways of accessing 
-	        GIS data.
+  ./      Core source code, makefiles and install directions.
+  ./jdbc  Extensions to the PostgreSQL JDBC drivers to support
+          the GIS objects. 
+  ./doc   Documentation on the code, objects and functions 
+          provided. 
+  ./loader  A program to convert ESRI Shape files into SQL text
+          suitable for uploading into a PostGIS/PostgreSQL database.
+  ./examples  Small programs which demonstrate ways of accessing 
+          GIS data.
 	        
 
 INSTALLATION:
@@ -33,19 +33,29 @@ it for this to work.
 
 Then run:
 	
-	make
-	make install
+  make
+  make install
 
-Finally, load the function and object definitions into a database with psql 
-(you must run this as a database user with system privledges):
+PostGIS now requires the PL/pgSQL procedural language in order to operate
+correctly. To install PL/pgSQL, locate the plpgsql.so library in your
+PostgreSQL installation (usually in the 'lib' directory). Then run the
+following SQL commands in your database, replacing the plpgsql.so 
+location with the correct one for your system:
 
-	psql -f postgis.sql -d yourdatabase
+  CREATE FUNCTION plpgsql_call_handler() 
+     RETURNS OPAQUE AS '/usr/local/pgsql/lib/plpgsql.so' 
+     LANGUAGE 'C';
+  CREATE TRUSTED PROCEDURAL LANGUAGE 'plpgsql'
+     HANDLER plpgsql_call_handler
+     LANCOMPILER 'PL/pgSQL';
+
+Finally, load the function and object definitions into your database 
+with psql (you must run this as a database user with system privledges):
+
+  psql -f postgis.sql -d yourdatabase
 
 Installation should be complete.
 
-To run some regression tests, use 'make test'. The results will be output
-to tests/output.log and compared to tests/expected.log.
-
 
 UPGRADING:
 
@@ -55,58 +65,90 @@ To avoid problems when upgrading, you will have to dump all the tables
 in your database, destroy the database, create a new one, upload the
 new postgis.sql file, then upload your database dump:
 
-        pg_dump -t "*" -f dumpfile.sql yourdatabase
-        dropdb yourdatabase
-        createdb yourdatabase
-        psql -f postgis.sql -d yourdatabase
-        psql -f dumpfile.sql -d yourdatabase
-	vacuumdb -z yourdatabase
+  pg_dump -t "*" -f dumpfile.sql yourdatabase
+  dropdb yourdatabase
+  createdb yourdatabase
+  psql -f postgis.sql -d yourdatabase
+  psql -f dumpfile.sql -d yourdatabase
+  vacuumdb -z yourdatabase
+
+When upgrading to 0.6, all your geometries will be created with an SRID
+of -1. To create valid OpenGIS geometries, you will have to create a 
+valid SRID in the SPATIAL_REF_SYS table, and then update your geometries
+to reference the SRID with the following SQL (with the appropriate
+substitutions:
+
+  UPDATE TABLE <table> SET <geocolumn> = SetSRID(<geocolumn>,<SRID>);
 
 
 USAGE:
 
-Try the following example SQL statements:
+Try the following example SQL statements to create non-OpenGIS tables and 
+geometries:
+
+  CREATE TABLE geom_test ( gid int4, geom geometry,name varchar(25) );
+  INSERT INTO geom_test ( gid, geom, name ) 
+    VALUES ( 1, 'POLYGON((0 0 0,0 5 0,5 5 0,5 0 0,0 0 0))', '3D Square');
+  INSERT INTO geom_test ( gid, geom, name ) 
+    VALUES ( 2, 'LINESTRING(1 1 1,5 5 5,7 7 5)', '3D Line' );
+  INSERT INTO geom_test ( gid, geom, name )
+    VALUES ( 3, 'MULTIPOINT(3 4,8 9)', '2D Aggregate Point' );
+  SELECT * from geom_test WHERE geom && 'BOX3D(2 2 0,3 3 0)'::box3d;
+
+The following SQL creates proper OpenGIS entries in the SPATIAL_REF_SYS
+and GEOMETRY_COLUMNS tables, and ensures that all geometries are created
+with an SRID.
+
+  INSERT INTO SPATIAL_REF_SYS
+    ( SRID, AUTH_NAME, AUTH_SRID, SRTEXT ) VALUES
+    ( 1, 'EPSG', 4269,
+      'GEOGCS["NAD83",
+        DATUM[
+          "North_American_Datum_1983",
+          SPHEROID[
+          "GRS 1980",
+          6378137,
+          298.257222101
+        ]
+      ],
+      PRIMEM["Greenwich",0],
+      UNIT["degree",0.0174532925199433]]'
+    );
+
+  CREATE TABLE geotest (
+    id INT4,
+    name VARCHAR(32)
+    );
+
+  SELECT AddGeometryColumn('db','geotest','geopoint',1,'POINT',2);
+
+  INSERT INTO geotest (id, name, geopoint)
+    VALUES (1, 'Olympia', GeometryFromText('POINT(-122.90,46.97)',1));
+  INSERT INTO geotest (id, name, geopoint)
+    VALUES (2, 'Renton', GeometryFromText('POINT(-122.22,47.50)',1));
+
+  SELECT name,AsText(geopoint) FROM geotest;
 
-CREATE TABLE geom_test ( gid int4, geom geometry, name varchar(25) );
-INSERT INTO geom_test ( gid, geom, name ) 
-  VALUES ( 1, 'POLYGON((0 0 0,0 5 0,5 5 0,5 0 0,0 0 0))', '3D Square');
-INSERT INTO geom_test ( gid, geom, name ) 
-  VALUES ( 2, 'LINESTRING(1 1 1,5 5 5,7 7 5)', '3D Line' );
-INSERT INTO geom_test ( gid, geom, name )
-  VALUES ( 3, 'MULTIPOINT(3 4,8 9)', '2D Aggregate Point' );
-SELECT * from geom_test WHERE geom && 'BOX3D(2 2 0,3 3 0)'::box3d;
 
 RTREE vs GIST:
 
-PostgreSQL provides support for rtree and GiST index schemes. The rtree scheme 
-is marginally faster, but does not support the indexing of objects greater 
-than 8K in size. Unfortunately, GIS objects get larger than 8K moderately
-often.  The GiST scheme offers indexing even on large objects, using a system
-of "lossy" indexing where a large object is proxied by a smaller one in the 
-index.  In the case of the PostGIS indexing system, all objects are proxied
-in the index by their bounding boxes.
-
-PostGIS fully supports GiST indexing, because it is the most widely useful for 
-GIS indexing. RTree indexing is partially supported, and may be discontinued
-in the future. We recommend you use GiST indexes.
+PostgreSQL provides support for GiST indexing. The GiST scheme offers 
+indexing even on large objects, using a system of "lossy" indexing where 
+a large object is proxied by a smaller one in the index.  In the case 
+of the PostGIS indexing system, all objects are proxied in the index by 
+their bounding boxes.
 
 You can build a GiST index with:
 
- CREATE INDEX <indexname> ON <tablename>  
+  CREATE INDEX <indexname> ON <tablename>  
      USING gist ( <geometryfield> gist_geometry_ops ) WITH ( islossy );
 
-You can build an rtree index with:
+Note that PostgreSQL may not use the GiST indexes when performing 
+searches unless *forced* to do so. If you find your system is not
+using the indexes automatically (use 'EXPLAIN' to see the query plan)
+you can force index use with the command: 
 
- CREATE INDEX <indexname> ON <tablename> 
-    USING rtree ( <geometryfield> rt_geometry_ops );
-
-Note that PostgreSQL does not use the GiST or rtree indexes when performing 
-searches unless *forced* to do so. This is not good behavior, but it seems
-to stem from the fact that the developers are optimizing the planner while 
-looking at btree indexing schemes. To force the system to use your spacial
-indexes, use the command:
-
- SET ENABLE_SEQSCAN = OFF
+  SET ENABLE_SEQSCAN = OFF
 
 Try doing an EXPLAIN on your query before and after the 'enable_seqscan'
 command to see the different query plans.

TODO

@@ -1,7 +1,7 @@
-2001/07/20
+2001/09/20
 
 - GML import/export routines
-- Possible re-write to become more OGC compliant (?)
 - Inclusion of OGC simple feature predicate functions for overlaps, 
   intersections, etc.
+  - Port of JTS topology suite to C++
 - Connectivity to commercial GIS software.