From: David Blasby Date: Wed, 28 Apr 2004 22:50:17 +0000 (+0000) Subject: Inital Version. Hasnt been proofread. X-Git-Tag: pgis_0_8_2~28 X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=313a8388401d8503239796a84cb823ea30ec6cd2;p=postgis Inital Version. Hasnt been proofread. git-svn-id: http://svn.osgeo.org/postgis/trunk@531 b70326c6-7e19-0410-871a-916f4a2858ee --- diff --git a/lwgeom/README b/lwgeom/README new file mode 100644 index 000000000..62b9fab82 --- /dev/null +++ b/lwgeom/README @@ -0,0 +1,203 @@ +Welcome to the Initial version of LWGEOM. + +More information is available on the PostGIS user's mailing list and +the PostGIS developer's mailing list. + + +Differences +----------- + +The LWGEOM is very much like the original PostGIS GEOMETRY type. The +main differences are: + +a) LWGEOMs are much smaller than the PostGIS GEOMETRY +b) LWGEOMs support 2d, 3d, and 4d points +c) LWGEOMs are indexed using single-precision bounding boxes. This + make the indexes significantly smaller than PostGIS GEOMETRY + indexes. +d) LWGEOMs are internally very similiar to OGC WKB +e) The "normal" view of LWGEOMs is OGC WKB - PostGIS GEOMETRY is OGC WKT +f) PostGIS geometries have a built-in BOX3D. LWGEOMs have an *optional* + BOX2D (see below). + + +Also included with the LWGEOMs is a type called 'box2d'. This is +very similiar to PostGIS BOX3D type: + +a) BOX2Ds are 2D - BOX3D is 3D +b) BOX2Ds are represented by single-precision floating point numbers, + while BOX3Ds are double-precision floating point numbers. +c) BOX2Ds will sometimes be slightly larger than you might expect. + This is because the conversion from double-precision to + single-precision is inexact. When this happens, the BOX2D will + automatically expand itself. + + +Installing +---------- +1. Build PostGIS normally +2. Go into the "lwgeom/" directory underneath your PostGIS installation +3. type 'make' +4. Install PostGIS normally into your database +5. Install LWGEOM into your database using the produced "lwgeom.sql" file. + \i lwgeom.sql +6. If you dont get any errors, LWGEOM is installed + +Testing +------- +1. type this in your database: + SELECT asText('POINT(0 0)'::lwgeom); +2. it should respond with + POINT(0 0) +3. if it didnt, LWGEOM did not install properly. +4. There are three regression tests to run. They are located + in the "lwgeom/regress/" directory. + ./run_regress + ./run_regress2 + ./run_regress3 + When you run these, it should be obvious if it passes or + fails. + + +Usage +----- + +There are not many actual LWGEOM functions available. Currently, there +are: + +1. all the functions necessary to support the BOX2D and LWGEOM types +2. functions required to build indexes on LWGEOMs +3. conversion and casting functions to move between LWGEOM and GEOMETRYs +4. OGC Well Known Text (WKT) and OGC Well Known Binary (WKB) parsing and + writing functions (Thanks to Ralph Mason). + +This means you can do most normal things with LWGEOMs. + +-- create a simple table. Notice that the_geom is of +-- type 'lwgeom' +CREATE TABLE lwgeom_test (the_geom lwgeom, id int); + +--insert a geometry into the table (WKT version) +INSERT INTO lwgeom_test VALUES ('POINT(1 1)', 1); + +-- insert a geometry into the table (WKB version) +-- WKB is usually used by programs NOT humans +INSERT INTO lwgeom_test VALUES ('0101000000000000000000F03F000000000000F03F', 2); + + +-- See whats in the table: +-- NOTICE that the 'normal' view of LWGEOMs is WKB - NOT WKT +SELECT * FROM lwgeom_test; + the_geom | id +--------------------------------------------+---- + 0101000000000000000000F03F000000000000F03F | 1 + 0101000000000000000000F03F000000000000F03F | 2 +(2 rows) + +-- Lets view it as WKT +SELECT asText(the_Geom),id FROM lwgeom_test; + astext | id +------------+---- + POINT(1 1) | 1 + POINT(1 1) | 2 +(2 rows) + + + + +-- explict conversions. +-- PostGIS -> LWGEOM +SELECT lwgeom('POINT(0 0)'::geometry); +-- LWGEOM --> PostGIS +SELECT geometry('POINT(0 0)'::lwgeom); + +-- Run some PostGIS based functions on LWGEOMs. All PostGIS functions +-- are runnable this way. +-- NOTE: this is doing a hidden LWGEOM->PostGIS GEOMETRY step +SELECT length('LINESTRING(0 0, 0 10)'::lwgeom); + length + -------- + 10 + (1 row) + + +-- Find the BOX2D bounding box of a geometry +SELECT box2d('LINESTRING(0 0, 0 10)'::lwgeom); + box2d +--------------- + BOX(0 0,0 10) +(1 row) + + + + +Building Indexes +---------------- + +This is very similiar to PostGIS: + +CREATE INDEX ON USING GIST ( GIST_LWGEOM_OPS); + +ie. CREATE INDEX lwgeom_test_lwgeom_idx ON lwgeom_test + USING GIST ( the_geom GIST_LWGEOM_OPS); + +Dont forget to VACUUM ANALYSE your table: +VACUUM ANALYSE
; + +Bounding Boxes +-------------- + + + +Bounding boxes are optional in LWGEOMs. By not having one, you are +saving a small amount of space per LWGEOM geometry (16 bytes). + +If you are cross-joining tables, you might want to explictly put a +bounding box inside the LWGEOM to make it faster. + +DROP INDEX ; +UPDATE
SET = AddBBOX(); +CREATE INDEX ON
USING GIST + ( GIST_LWGEOM_OPS); +VACUUM ANALYSE
; + + +A cross-joining query looks like this: + +SELECT table1.id as node_id1, + table2.id as node_id2 +FROM node_10000 table1, + node_10000 table2 +WHERE table1.the_geom && table2.the_geom; + +For every row in node_10000, postgresql searches for rows in node_10000 +that overlap. If node_10000 has 10,000 rows, this query will do 10,000 +index searches - THAT A LOT OF WORK. + + + +Space Saving +------------ + +LWGEOM indexs are approximately 40% smaller than PostGIS indexes. + +A LWGEOM 'POINT(0 0)' takes up 21 bytes, a POSTGIS 'POINT(0 0)' takes +up 140 bytes. This shows that LWGEOMs have a much smaller overhead. + +LWGEOMs will store 2D points as 2 double precision numbers (16 bytes) - +PostGIS will store 2D points with 3 (24 bytes). This can be another +big savings. + + +Future Developement +------------------- + +Testing Testing Testing +Native LWGEOM -> GEOS converter +Move most of the PostGIS functions so they run directly on LWGEOMs (with +out conversion) + +Stay tuned to the PostGIS mailing lists. + +