From f08eeecfb08c93615f11770df7e1c0ca69eab20e Mon Sep 17 00:00:00 2001 From: Sandro Santilli Date: Mon, 27 Dec 2004 13:34:49 +0000 Subject: [PATCH] Expanded "GIS Objects" chapter adding OGC/PostGIS (E)WKT/B and canonical forms. git-svn-id: http://svn.osgeo.org/postgis/trunk@1185 b70326c6-7e19-0410-871a-916f4a2858ee --- doc/postgis.xml | 182 ++++++++++++++++++++++++++++++++++-------------- 1 file changed, 129 insertions(+), 53 deletions(-) diff --git a/doc/postgis.xml b/doc/postgis.xml index dc80b0df8..6b78f81c0 100644 --- a/doc/postgis.xml +++ b/doc/postgis.xml @@ -699,8 +699,19 @@ AND The GIS objects supported by PostGIS are a superset of the "Simple Features" defined by the OpenGIS Consortium (OGC). As of version 0.9, PostGIS supports all the objects and functions - specified in the OGC "Simple - Features for SQL" specification. + specified in the OGC "Simple Features for SQL" specification. + + PostGIS extends the standard with support for 3DZ,3DM and 4D + coordinates. + + + OpenGIS WKB and WKT + + The OpenGIS specification defines two standard ways of + expressing spatial objects: the Well-Known Text (WKT) form and + the Well-Known Binary (WKB) form. Both WKT and WKB include + information about the type of the object and the + coordinates which form the object. Examples of the text representations (WKT) of the spatial objects of the features are as follows: @@ -737,8 +748,61 @@ AND - PostGIS extends the standard with support for 3DZ,3DM and 4D - coordinates. Examples of the text representations (EWKT) of the + + The OpenGIS specification also requires that the + internal storage format of spatial objects include a spatial + referencing system identifier (SRID). The SRID is required when + creating spatial objects for insertion into the database. + + +Input/Output of these formats are available using the following +interfaces: + + + + bytea WKB = asBinary(geometry); + text WKT = asText(geometry); + geometry = GeomFromWKB(bytea WKB, SRID); + geometry = GeometryFromText(text WKT, SRID); + + + For example, a valid insert statement to create and insert an OGC spatial object would be: + + + INSERT INTO SPATIALTABLE ( + THE_GEOM, + THE_NAME + ) + VALUES ( + GeomFromText('POINT(-126.4 45.32)', 312), + 'A Place' + ) + + + + + + PostGIS EWKB, EWKT and Canonical Forms + + + +OGC formats only support 2d geometries, and the associated SRID +is *never* embedded in the input/output representations. + + + +Postgis extended formats are currently superset of OGC one (every +valid WKB/WKT is a valid EWKB/EWKT) but this might vary in the +future, specifically if OGC comes out with a new format conflicting +with our extensions. Thus you SHOULD NOT rely on this feature! + + + +Postgis EWKB/EWKT add 3dm,3dz,4d coordinates support and embedded +SRID information. + + + Examples of the text representations (EWKT) of the extended spatial objects of the features are as follows: @@ -747,6 +811,10 @@ AND POINT(0 0 0) -- XYZ + + SRID=32632;POINT(0 0) -- XY with SRID + + POINTM(0 0 0) -- XYM @@ -756,7 +824,7 @@ AND - MULTIPOINTM(0 0 0,1 2 1) + SRID=4326;MULTIPOINTM(0 0 0,1 2 1) -- XYM with SRID @@ -775,62 +843,70 @@ AND - GEOMETRYCOLLECTIONM(POINT(2 3 9),LINESTRING((2 3 4,3 4 + GEOMETRYCOLLECTIONM(POINTM(2 3 9),LINESTRINGM((2 3 4,3 4 5))) - - Standard versus Canonical Forms + +Input/Output of these formats are available using the following +interfaces: + + + + bytea EWKB = asEWKB(geometry); + text EWKT = asEWKT(geometry); + geometry = GeomFromEWKB(bytea EWKB); + geometry = GeomFromEWKT(text EWKT); + + + +For example, a valid insert statement to create and insert a PostGIS spatial object would be: + + + + INSERT INTO SPATIALTABLE ( + THE_GEOM, + THE_NAME + ) + VALUES ( + GeomFromEWKT('SRID=312;POINTM(-126.4 45.32 15)'), + 'A Place' + ) + + +The "canonical forms" of a PostgreSQL type are the representations +you get with a simple query (without any function call) and the one +which is guaranteed to be accepted with a simple insert, update or +copy. For the postgis 'geometry' type these are: + + + - Output - + binary: EWKB + ascii: HEXEWKB (EWKB in hex form) + + - Input - + binary: EWKB + ascii: HEXEWKB|EWKT + + + + +For example this statement reads EWKT and returns HEXEWKB in the +process of canonical ascii input/output: + + + + =# SELECT 'SRID=4;POINT(0 0)'::geometry; + geometry + ---------------------------------------------------- + 01010000200400000000000000000000000000000000000000 + (1 row) + - The OpenGIS specification defines two standard ways of - expressing spatial objects: the Well-Known Text (WKT) form (shown in - the previous section) and the Well-Known Binary (WKB) form. Both WKT - and WKB include information about the type of the object and the - coordinates which form the object. - However, the OpenGIS specification also requires that the - internal storage format of spatial objects include a spatial - referencing system identifier (SRID). The SRID is required when - creating spatial objects for insertion into the database. For example, - a valid insert statement to create and insert a spatial object would - be: - - INSERT INTO SPATIALTABLE ( - THE_GEOM, - THE_NAME -) -VALUES ( - GeomFromText('POINT(-126.4 45.32)', 312), - 'A Place' -) - - Note that the "GeomFromText" function requires an SRID number. - - The "canonical form" of the spatial objects in PostgreSQL is a - text representation which includes all the information necessary to - construct the object. Unlike the OpenGIS standard forms, it includes - the type, dimensions, coordinate, and SRID - information. The canonical form is the default form returned from a - SELECT query. - Since version 1.0.0 the canonical form is an HEX-encoded extended - WKB (EWKB). - The example below shows the difference between the OGC standard and - PostGIS canonical forms: - - db=> SELECT AsText(geom) AS OGCGeom FROM SPATIALTABLE; -OGCGeom -------------------------------------------------- - POINT(-126.4 45.32) -(1 row) - -db=> SELECT geom AS PostGISGeom FROM thetable; -PostGISGeom -------------------------------------------------- - 0101000020380100009A99999999995FC0295C8FC2F5A84640 -(1 row) -- 2.40.0