--- /dev/null
+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 <name> ON <table> USING GIST (<lwgeom column> 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 <table>;
+
+Bounding Boxes
+--------------
+
+<this section for advanced users. Ignore it if you dont understand
+ what its saying>
+
+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 <lwgeom index name>;
+UPDATE <table> SET <lwgeom column> = AddBBOX(<lwgeom column>);
+CREATE INDEX <lwgeom index name> ON <table> USING GIST
+ (<lwgeom column> GIST_LWGEOM_OPS);
+VACUUM ANALYSE <table>;
+
+
+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.
+
+
projects / postgis / commitdiff